@geravant/sinain 1.14.0 → 1.15.1

package/sinain-core/src/agents-loader.ts

@@ -0,0 +1,254 @@
+// agents-loader.ts
+//
+// sinain-core's view of sinain-agent/agents.json. Loaded once at startup,
+// gives config.ts a typed snapshot of the bare-agent + OpenClaw config that
+// used to live in .env.
+//
+// Why sinain-core reads it at all: the OpenClaw WS client is constructed
+// before the bare agent ever registers, and stays connected across the
+// session for heartbeat / situation push / feedback. So sinain-core needs
+// the gateway URL/token at startup — it can't wait for run.sh to forward
+// them via /bareagent/register.
+//
+// Path resolution:
+//   1. AGENTS_CONFIG_PATH env var (explicit override)
+//   2. <repo-root>/sinain-agent/agents.json (default)
+//   3. <repo-root>/sinain-agent/agents.example.json (fresh-checkout fallback)
+//
+// Returns null if no candidate exists. config.ts treats null as "use env
+// defaults" so the migration is non-breaking.
+//
+// Field expansion happens in two passes (shell-like ordering):
+//   1. Cross-field literal expansion: ${allowedTools} inside escAllowedTools
+//      resolves against other top-level fields. Lets users compose
+//      whitelists by reference.
+//   2. Env-var indirection: ${OPENROUTER_API_KEY}, ${HOME}, etc. resolve
+//      against process.env. Mirrors run.sh's apply_profile_env regex
+//      (\$\{[A-Za-z_][A-Za-z0-9_]*\}).
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Regex shared with run.sh's apply_profile_env. Keep the two implementations
+// in lockstep when changing either side.
+const VAR_REF_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+export interface OpenClawProfileFields {
+  type: "openclaw";
+  wsUrl?: string;
+  wsToken?: string;
+  httpUrl?: string;
+  httpToken?: string;
+  sessionKey?: string;
+  phase1TimeoutMs?: number;
+  phase2TimeoutMs?: number;
+  pingIntervalMs?: number;
+}
+
+export interface AgentProfile {
+  type?: string;
+  bin?: string;
+  settings?: string;
+  model?: string;
+  env?: Record<string, string>;
+  // openclaw-specific fields (typed loose since profiles are heterogeneous)
+  wsUrl?: string;
+  wsToken?: string;
+  httpUrl?: string;
+  httpToken?: string;
+  sessionKey?: string;
+  phase1TimeoutMs?: number;
+  phase2TimeoutMs?: number;
+  pingIntervalMs?: number;
+}
+
+export interface AnalyzerBlock {
+  debounceMs?: number;
+  maxIntervalMs?: number;
+}
+
+export interface EscalationBlock {
+  mode?: string;
+  cooldownMs?: number;
+  staleMs?: number;
+}
+
+export interface AgentsConfig {
+  default?: string;
+  pollIntervalSec?: number;
+  agentMaxTurns?: number;
+  spawnMaxTurns?: number;
+  allowedTools?: string;
+  escAllowedTools?: string;
+  spawnAllowedTools?: string;
+  autoApproveTools?: string;
+  analyzer?: AnalyzerBlock;
+  escalation?: EscalationBlock;
+  profiles?: Record<string, AgentProfile>;
+  /** Absolute path of the file actually loaded (for debug logging). */
+  loadedFrom?: string;
+}
+
+function expandVars(value: string): string {
+  return value.replace(VAR_REF_RE, (_, name: string) => process.env[name] ?? "");
+}
+
+/** Recursively expand ${env} references in any string field of `obj`. */
+function expandEnvDeep<T>(obj: T): T {
+  if (obj === null || obj === undefined) return obj;
+  if (typeof obj === "string") return expandVars(obj) as unknown as T;
+  if (Array.isArray(obj)) return obj.map((x) => expandEnvDeep(x)) as unknown as T;
+  if (typeof obj === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(obj as Record<string, unknown>)) {
+      out[k] = expandEnvDeep(v);
+    }
+    return out as T;
+  }
+  return obj;
+}
+
+/**
+ * Cross-field literal expansion at the top level. Lets users write
+ *   "escAllowedTools": "${allowedTools} Bash(git:*) Edit"
+ * and have it compose with the value of `allowedTools`. Only string
+ * top-level fields are eligible to be referenced; nested blocks aren't.
+ */
+function expandTopLevelRefs(cfg: AgentsConfig): void {
+  const refTargets: Record<string, string | undefined> = {
+    allowedTools: cfg.allowedTools,
+    escAllowedTools: cfg.escAllowedTools,
+    spawnAllowedTools: cfg.spawnAllowedTools,
+    autoApproveTools: cfg.autoApproveTools,
+    default: cfg.default,
+  };
+  const expand = (s?: string): string | undefined => {
+    if (!s) return s;
+    return s.replace(VAR_REF_RE, (m, name: string) => {
+      const ref = refTargets[name];
+      // Only substitute when the referenced field is a top-level field
+      // *that has a value*. Otherwise leave the placeholder untouched so
+      // the env-var pass can still pick it up (e.g. ${HOME}).
+      return ref !== undefined ? ref : m;
+    });
+  };
+  cfg.escAllowedTools = expand(cfg.escAllowedTools);
+  cfg.spawnAllowedTools = expand(cfg.spawnAllowedTools);
+}
+
+function candidatePaths(): string[] {
+  const explicit = process.env.AGENTS_CONFIG_PATH;
+  if (explicit) return [resolve(explicit)];
+  // ~/.sinain/agents.json is the wizard's write target — works on npm
+  // installs where the package dir is read-only. Highest priority after
+  // an explicit env override so user-home config wins over the shipped
+  // template.
+  const userHome = resolve(homedir(), ".sinain", "agents.json");
+  // sinain-core compiled output sits at sinain-core/dist/, source at
+  // sinain-core/src/. From either, sinain-agent is two levels up.
+  const repoRoot = resolve(__dirname, "..", "..");
+  return [
+    userHome,
+    resolve(repoRoot, "sinain-agent", "agents.json"),
+    resolve(repoRoot, "sinain-agent", "agents.example.json"),
+  ];
+}
+
+/**
+ * Load agents.json (or fall back to agents.example.json). Returns null if
+ * neither candidate file exists or parsing fails. Caller (config.ts) is
+ * expected to treat null as "use env defaults" so the migration is
+ * non-breaking.
+ */
+export function loadAgentsConfig(): AgentsConfig | null {
+  for (const path of candidatePaths()) {
+    if (!existsSync(path)) continue;
+    try {
+      const raw = readFileSync(path, "utf-8");
+      const parsed = JSON.parse(raw) as AgentsConfig;
+      // Pass 1: cross-field literal substitution at top level. Has to run
+      // before env-var expansion so `${allowedTools}` doesn't accidentally
+      // resolve to process.env.allowedTools (which doesn't exist anyway,
+      // but the principle of layered substitution is what we want).
+      expandTopLevelRefs(parsed);
+      // Pass 2: ${ENV_VAR} expansion across the whole tree. Profile-level
+      // env blocks are deliberately skipped here — those are applied by
+      // run.sh in a subshell at invocation time, not by sinain-core.
+      const profiles = parsed.profiles;
+      delete parsed.profiles;
+      const expanded = expandEnvDeep(parsed);
+      // Restore profiles (with their own env blocks expanded for the few
+      // openclaw-specific fields that sinain-core does read).
+      if (profiles) {
+        const expandedProfiles: Record<string, AgentProfile> = {};
+        for (const [name, profile] of Object.entries(profiles)) {
+          // Don't expand the per-profile `env` block — those are evaluated
+          // at agent invocation time inside run.sh. But DO expand other
+          // profile fields (wsToken, etc.) since sinain-core reads them.
+          const { env: profileEnv, ...rest } = profile;
+          expandedProfiles[name] = {
+            ...expandEnvDeep(rest),
+            ...(profileEnv !== undefined ? { env: profileEnv } : {}),
+          };
+        }
+        expanded.profiles = expandedProfiles;
+      }
+      expanded.loadedFrom = path;
+      return expanded;
+    } catch (err) {
+      console.warn(`[agents-loader] failed to parse ${path}: ${(err as Error).message}`);
+    }
+  }
+  return null;
+}
+
+/** Convenience: pull the openclaw profile if present, else null.
+ *  @deprecated Prefer findGatewayProfile() — it doesn't assume the name. */
+export function getOpenClawProfile(cfg: AgentsConfig | null): AgentProfile | null {
+  return cfg?.profiles?.openclaw ?? null;
+}
+
+/**
+ * Find a gateway-style profile (any profile with `type: "openclaw"`,
+ * regardless of the profile's name). Used by sinain-core to:
+ *   - load WS connection params at startup (config.ts)
+ *   - decide whether a lane choice should route via WS or HTTP (escalator.ts)
+ *
+ * Preference order: the canonical name "openclaw" wins if present, otherwise
+ * the first openclaw-typed profile found in the JSON. This lets users add
+ * `nemoclaw`, `nanoclaw-prod`, etc. with their own URLs as drop-in replacements.
+ */
+export function findGatewayProfile(
+  cfg: AgentsConfig | null,
+): { name: string; profile: AgentProfile } | null {
+  const profiles = cfg?.profiles;
+  if (!profiles) return null;
+  if (profiles.openclaw?.type === "openclaw") {
+    return { name: "openclaw", profile: profiles.openclaw };
+  }
+  for (const [name, profile] of Object.entries(profiles)) {
+    if (profile?.type === "openclaw") return { name, profile };
+  }
+  return null;
+}
+
+/** Is the given profile name a gateway-style (WS-dispatched) profile? */
+export function isGatewayProfile(
+  cfg: AgentsConfig | null,
+  name: string,
+): boolean {
+  return cfg?.profiles?.[name]?.type === "openclaw";
+}
+
+/** All openclaw-typed profile names in the config. */
+export function gatewayProfileNames(cfg: AgentsConfig | null): string[] {
+  const profiles = cfg?.profiles;
+  if (!profiles) return [];
+  return Object.entries(profiles)
+    .filter(([_, p]) => p?.type === "openclaw")
+    .map(([name]) => name);
+}

package/sinain-core/src/config.ts

@@ -2,8 +2,9 @@ import { readFileSync, existsSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import os from "node:os";
-import type { CoreConfig, AudioPipelineConfig, TranscriptionConfig, AnalysisConfig, EscalationConfig, OpenClawConfig, EscalationMode, EscalationTransport, LearningConfig, PrivacyConfig, PrivacyMatrix, PrivacyLevel, PrivacyRow } from "./types.js";
+import type { CoreConfig, AudioPipelineConfig, TranscriptionConfig, AnalysisConfig, EscalationConfig, OpenClawConfig, EscalationMode, LearningConfig, PrivacyConfig, PrivacyMatrix, PrivacyLevel, PrivacyRow } from "./types.js";
 import { PRESETS } from "./privacy/presets.js";
+import { loadAgentsConfig, findGatewayProfile, type AgentsConfig } from "./agents-loader.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -140,6 +141,26 @@ function loadPrivacyConfig(): PrivacyConfig {
 }
 
 export function loadConfig(): CoreConfig {
+  // sinain-agent/agents.json is the new single source of truth for the
+  // bare-agent + OpenClaw config that used to live in .env. Loading
+  // happens once at startup; null means the file isn't there (fresh
+  // checkout, custom layout, etc.) and we fall back to env defaults.
+  const agentsCfg = loadAgentsConfig();
+  if (agentsCfg) {
+    console.log(`[config] loaded agents config from ${agentsCfg.loadedFrom}`);
+  }
+
+  // Helpers that prefer agents.json values, then env, then a hardcoded
+  // default. Keeps .env working as a safety net during the migration.
+  const fromCfgStr = (cfgVal: string | undefined, envKey: string, def: string): string => {
+    if (cfgVal !== undefined && cfgVal !== "") return cfgVal;
+    return env(envKey, def);
+  };
+  const fromCfgInt = (cfgVal: number | undefined, envKey: string, def: number): number => {
+    if (cfgVal !== undefined) return cfgVal;
+    return intEnv(envKey, def);
+  };
+
   const audioConfig: AudioPipelineConfig = {
     device: env("AUDIO_DEVICE", "BlackHole 2ch"),
     sampleRate: intEnv("AUDIO_SAMPLE_RATE", 16000),
@@ -196,30 +217,57 @@ export function loadConfig(): CoreConfig {
       .split(",").map(s => s.trim()).filter(Boolean),
     timeout: intEnv("ANALYSIS_TIMEOUT", 15000),
     pushToFeed: boolEnv("AGENT_PUSH_TO_FEED", true),
-    debounceMs: intEnv("AGENT_DEBOUNCE_MS", 3000),
-    maxIntervalMs: intEnv("AGENT_MAX_INTERVAL_MS", 30000),
+    // analyzer pacing: agents.json `analyzer` block, fall back to env
+    debounceMs: fromCfgInt(agentsCfg?.analyzer?.debounceMs, "AGENT_DEBOUNCE_MS", 3000),
+    maxIntervalMs: fromCfgInt(agentsCfg?.analyzer?.maxIntervalMs, "AGENT_MAX_INTERVAL_MS", 30000),
     cooldownMs: intEnv("AGENT_COOLDOWN_MS", 10000),
     maxAgeMs: intEnv("AGENT_MAX_AGE_MS", 120000),
     historyLimit: intEnv("AGENT_HISTORY_LIMIT", 50),
   };
 
-  const escalationMode = env("ESCALATION_MODE", "rich") as EscalationMode;
+  // escalation policy: agents.json `escalation` block, fall back to env.
+  // Mode is runtime-mutable via the overlay's flash-icon selector; this only
+  // sets the boot-time default. (Transport is no longer a setting — per-lane
+  // agent choice in the overlay determines WS vs HTTP dispatch.)
+  const escalationMode = fromCfgStr(agentsCfg?.escalation?.mode, "ESCALATION_MODE", "rich") as EscalationMode;
   const escalationConfig: EscalationConfig = {
     mode: escalationMode,
-    cooldownMs: intEnv("ESCALATION_COOLDOWN_MS", 30000),
-    staleMs: intEnv("ESCALATION_STALE_MS", 90000),
-    transport: env("ESCALATION_TRANSPORT", "auto") as EscalationTransport,
+    cooldownMs: fromCfgInt(agentsCfg?.escalation?.cooldownMs, "ESCALATION_COOLDOWN_MS", 30000),
+    staleMs: fromCfgInt(agentsCfg?.escalation?.staleMs, "ESCALATION_STALE_MS", 90000),
   };
 
+  // OpenClaw gateway config: pick the first openclaw-TYPED profile
+  // (preferring the canonical name "openclaw"). This lets users add
+  // server-side variants — `nemoclaw`, `nanoclaw-prod`, etc. — as full
+  // peers; the WS client connects to whichever shows up first in the
+  // profiles list. Removing all openclaw-typed profiles (and unsetting
+  // the env vars) leaves gatewayWsUrl empty → registerBareAgent skips
+  // injecting any gateway entry into the roster, and escalator.start()
+  // skips the WS connect.
+  //
+  // Limitation: only ONE gateway URL gets a live WS client today. Adding
+  // multiple openclaw-typed profiles with different URLs lets the user
+  // pick them in the overlay roster, but dispatch always uses the first
+  // one's connection params. True per-profile WS clients is a follow-up.
+  const gateway = findGatewayProfile(agentsCfg);
+  const openclawProfile = gateway?.profile;
+  // wsUrl/hookUrl default to empty so "delete the openclaw profile" genuinely
+  // disables the gateway. The shipped agents.example.json includes the
+  // profile with localhost defaults, so fresh installs still work out of
+  // the box; removal is an explicit opt-out.
   const openclawConfig: OpenClawConfig = {
-    gatewayWsUrl: envAllowEmpty("OPENCLAW_WS_URL", "OPENCLAW_GATEWAY_WS_URL", "ws://localhost:18789"),
-    gatewayToken: env("OPENCLAW_WS_TOKEN", env("OPENCLAW_GATEWAY_TOKEN", "")),
-    hookUrl: envAllowEmpty("OPENCLAW_HTTP_URL", "OPENCLAW_HOOK_URL", "http://localhost:18789/hooks/agent"),
-    hookToken: env("OPENCLAW_HTTP_TOKEN", env("OPENCLAW_HOOK_TOKEN", "")),
-    sessionKey: env("OPENCLAW_SESSION_KEY", "agent:main:sinain"),
-    phase1TimeoutMs: intEnv("OPENCLAW_PHASE1_TIMEOUT_MS", 30_000),
-    phase2TimeoutMs: intEnv("OPENCLAW_PHASE2_TIMEOUT_MS", 120_000),
-    pingIntervalMs: intEnv("OPENCLAW_PING_INTERVAL_MS", 30_000),
+    gatewayWsUrl: fromCfgStr(openclawProfile?.wsUrl, "OPENCLAW_WS_URL",
+      envAllowEmpty("OPENCLAW_GATEWAY_WS_URL", undefined, "")),
+    gatewayToken: fromCfgStr(openclawProfile?.wsToken, "OPENCLAW_WS_TOKEN",
+      env("OPENCLAW_GATEWAY_TOKEN", "")),
+    hookUrl: fromCfgStr(openclawProfile?.httpUrl, "OPENCLAW_HTTP_URL",
+      envAllowEmpty("OPENCLAW_HOOK_URL", undefined, "")),
+    hookToken: fromCfgStr(openclawProfile?.httpToken, "OPENCLAW_HTTP_TOKEN",
+      env("OPENCLAW_HOOK_TOKEN", "")),
+    sessionKey: fromCfgStr(openclawProfile?.sessionKey, "OPENCLAW_SESSION_KEY", "agent:main:sinain"),
+    phase1TimeoutMs: fromCfgInt(openclawProfile?.phase1TimeoutMs, "OPENCLAW_PHASE1_TIMEOUT_MS", 30_000),
+    phase2TimeoutMs: fromCfgInt(openclawProfile?.phase2TimeoutMs, "OPENCLAW_PHASE2_TIMEOUT_MS", 120_000),
+    pingIntervalMs: fromCfgInt(openclawProfile?.pingIntervalMs, "OPENCLAW_PING_INTERVAL_MS", 30_000),
   };
 
   const situationDir = env("OPENCLAW_WORKSPACE_DIR", "~/.openclaw/workspace");
@@ -236,6 +284,19 @@ export function loadConfig(): CoreConfig {
 
   const privacyConfig = loadPrivacyConfig();
 
+  // autoApproveTools: agents.json top-level field, falls back to
+  // SINAIN_AUTO_APPROVE_TOOLS env. Space-separated tool names or prefix
+  // patterns (suffix *) that sinain-core auto-approves at /spawn/approve
+  // without routing to the overlay.
+  const autoApproveRaw = fromCfgStr(
+    agentsCfg?.autoApproveTools,
+    "SINAIN_AUTO_APPROVE_TOOLS",
+    "Read Glob Grep Ls Cat mcp__sinain*",
+  );
+  const permissionsConfig = {
+    autoApproveTools: autoApproveRaw.split(/\s+/).filter((t) => t.length > 0),
+  };
+
   return {
     port: intEnv("PORT", 9500),
     audioConfig,
@@ -251,5 +312,6 @@ export function loadConfig(): CoreConfig {
     costDisplayEnabled: boolEnv("COST_DISPLAY_ENABLED", false),
     learningConfig,
     privacyConfig,
+    permissionsConfig,
   };
 }

package/sinain-core/src/escalation/escalator.ts

@@ -33,6 +33,23 @@ export interface EscalatorDeps {
   feedbackStore?: FeedbackStore;
   signalCollector?: SignalCollector;
   queryKnowledgeFacts?: (entities: string[], maxFacts: number) => Promise<string>;
+  /** Returns the currently-selected spawn-lane agent from the bare-agent
+   *  roster ("" = Off). When a local agent is selected, dispatchSpawnTask
+   *  prefers the HTTP bare-agent path over the OpenClaw gateway WS path,
+   *  so the overlay's agent-selector choice is respected even when the
+   *  gateway is connected. */
+  getSpawnAgent?: () => string;
+  /** Returns the currently-selected escalation-lane agent. Gateway-typed
+   *  profiles (any agent whose `type` is "openclaw" — see isGatewayAgent)
+   *  route via WS; any other non-empty value routes to the local bare
+   *  agent via HTTP httpPending. */
+  getEscalationAgent?: () => string;
+  /** Returns true if the named profile is a gateway-style profile
+   *  (i.e. dispatched via WS RPC, not invoked as a local CLI). Lookup is
+   *  by `agentsCfg.profiles[name].type === "openclaw"`. Custom profiles
+   *  like "nemoclaw" or "nanoclaw-prod" with that type get WS dispatch
+   *  automatically — the routing key is type, not name. */
+  isGatewayAgent?: (name: string) => boolean;
 }
 
 /**
@@ -52,6 +69,14 @@ export class Escalator {
   private slot: EscalationSlot;
   private httpPending: HttpPendingEscalation | null = null;
 
+  // Grace window for stale escalation IDs — when analyzer rotates the pending
+  // slot mid-response (agent takes 10-30s on MCP flow while ticks fire every
+  // 3-6s), the agent's respondHttp(oldId) would fail. Keep last 5 IDs for ~60s
+  // so those responses still land on HUD instead of being silently dropped.
+  private recentHttpIds: Array<{ id: string; ts: number }> = [];
+  private static readonly STALE_ID_GRACE_MS = 60_000;
+  private static readonly STALE_ID_BUFFER_SIZE = 5;
+
   private lastEscalationTs = 0;
   private lastEscalatedDigest = "";
 
@@ -139,9 +164,17 @@ export class Escalator {
     log(TAG, `user command set: "${preview}"`);
   }
 
-  /** Start the WS connection to OpenClaw (skipped when transport=http). */
+  /** Start the WS connection to OpenClaw.
+   *
+   * Connects whenever the gateway URL is configured AND escalation isn't
+   * fully off. WS is the transport for the openclaw lane — the user selects
+   * it via the overlay's agent picker, and dispatch routes accordingly.
+   * Removing the openclaw profile from agents.json (and unsetting the env
+   * vars) leaves gatewayWsUrl empty → no connect attempt.
+   */
   start(): void {
-    if (this.deps.escalationConfig.mode !== "off" && this.deps.escalationConfig.transport !== "http") {
+    const wsConfigured = !!this.deps.openclawConfig.gatewayWsUrl;
+    if (this.deps.escalationConfig.mode !== "off" && wsConfigured) {
       this.wsClient.connect();
       const tokenHash = this.deps.openclawConfig.gatewayToken
         ? createHash("sha256").update(this.deps.openclawConfig.gatewayToken).digest("hex").slice(0, 12)
@@ -185,11 +218,16 @@ export class Escalator {
       this.pendingUserCommand = null;
     }
 
-    // Skip WS escalations when circuit is open (HTTP transport bypasses this)
-    const transport = this.deps.escalationConfig.transport;
-    if (this.wsClient.isCircuitOpen && transport !== "http") {
-      log(TAG, `tick #${entry.id}: skipped — circuit breaker open`);
-      return;
+    // Early skip when circuit is open AND the user has selected openclaw —
+    // saves the cost of building the escalation message just to drop it.
+    // Local-agent lanes (claude, openclaude, etc.) bypass this since they
+    // route via HTTP and don't depend on WS.
+    if (this.wsClient.isCircuitOpen) {
+      const escalationAgent = this.deps.getEscalationAgent?.() || "";
+      if (this.deps.isGatewayAgent?.(escalationAgent)) {
+        log(TAG, `tick #${entry.id}: skipped — circuit breaker open and gateway agent "${escalationAgent}" selected`);
+        return;
+      }
     }
 
     // If user command is pending, force escalation (bypass score + cooldown)
@@ -275,9 +313,48 @@ export class Escalator {
       ts: entry.ts,
     };
 
-    const useHttp = transport === "http" || (transport === "auto" && !this.wsClient.isConnected);
+    // Per-lane dispatch: agent identity *is* the transport.
+    //   - profile.type === "openclaw" (gateway-style) → WS dispatch
+    //   - any other non-empty agent (local CLI: claude, openclaude, ...) → HTTP
+    //   - empty (Off) → escalator.setMode("off") should have stopped us
+    //     upstream; defensive bailout.
+    //
+    // Routing keys off the profile's `type` field, not its name, so custom
+    // gateway profiles like "nemoclaw" or "nanoclaw-prod" route via WS
+    // automatically as long as they declare `type: "openclaw"` in agents.json.
+    //
+    // openclaw + WS-disconnected drops with a toast (no HTTP fallback),
+    // because the bare agent can't run a gateway profile as a local CLI —
+    // the fallback caused infinite skip loops historically.
+    const escalationAgent = this.deps.getEscalationAgent?.() || "";
+    const isGateway = this.deps.isGatewayAgent?.(escalationAgent) ?? false;
+    let useHttp: boolean;
+    if (isGateway) {
+      if (!this.wsClient.isConnected) {
+        log(TAG, `escalation dropped: gateway agent "${escalationAgent}" selected but WS disconnected`);
+        this.deps.wsHandler.broadcast(
+          `⚠ Gateway disconnected — escalation dropped. Pick a local agent or check the ${escalationAgent} gateway.`,
+          "high",
+        );
+        return;
+      }
+      useHttp = false;
+    } else if (escalationAgent) {
+      useHttp = true;
+    } else {
+      log(TAG, `escalation dropped: lane is Off (escalationAgent="")`);
+      return;
+    }
 
     if (useHttp) {
+      // Remember the outgoing ID before overwriting so late-arriving responses
+      // still find a valid match in respondHttp's grace window.
+      if (this.httpPending) {
+        this.recentHttpIds.push({ id: this.httpPending.id, ts: this.httpPending.ts });
+        if (this.recentHttpIds.length > Escalator.STALE_ID_BUFFER_SIZE) {
+          this.recentHttpIds.shift();
+        }
+      }
       // Store in HTTP pending slot (newest wins, like EscalationSlot)
       this.httpPending = {
         id: slotId,
@@ -287,13 +364,50 @@ export class Escalator {
         ts: entry.ts,
         feedbackCtx: slotEntry.feedbackCtx,
       };
-      log(TAG, `tick #${entry.id} → httpPending id=${slotId} (transport=${transport})`);
+      log(TAG, `tick #${entry.id} → httpPending id=${slotId} (lane=${escalationAgent || "<default>"})`);
     } else {
       log(TAG, `tick #${entry.id} → slot.insert id=${slotId} depth=${this.slot.depth}`);
       this.slot.insert(slotEntry);
     }
   }
 
+  /** Redispatch a stale httpPending escalation through the WS slot.
+   *
+   * Called by index.ts when the escalation lane flips to a gateway-typed
+   * agent (e.g., openclaude → openclaw): an escalation queued for HTTP
+   * before the switch is now mis-routed. Rather than letting the bare
+   * agent skip it (which posts a confusing "[skipped: gateway-routed]"
+   * to the user's HUD), we move it into the WS slot so the gateway
+   * actually handles the user's pending question.
+   *
+   * If WS isn't connected, silently clear httpPending — the agent loop
+   * will produce a new escalation through the proper drop-with-toast
+   * path on the next tick. Better than the user seeing the skip message
+   * AND the gateway-disconnect toast for the same logical event.
+   *
+   * Returns true if a redispatch (or clear) actually happened, so the
+   * caller can log meaningfully.
+   */
+  redispatchHttpPendingToWs(): boolean {
+    if (!this.httpPending) return false;
+    const stale = this.httpPending;
+    this.httpPending = null;
+    if (!this.wsClient.isConnected) {
+      log(TAG, `redispatch skipped: WS not connected — cleared stale httpPending id=${stale.id}`);
+      return true;
+    }
+    const slotEntry: SlotEntry = {
+      id: stale.id,
+      message: stale.message,
+      sessionKey: this.deps.openclawConfig.sessionKey,
+      feedbackCtx: stale.feedbackCtx,
+      ts: stale.ts,
+    };
+    log(TAG, `redispatching stale httpPending id=${stale.id} → WS slot (lane switched to gateway)`);
+    this.slot.insert(slotEntry);
+    return true;
+  }
+
   /** Push fresh SITUATION.md content to the gateway server (fire-and-forget). */
   pushSituationMd(content: string): void {
     if (!this.wsClient.isConnected) return;
@@ -381,11 +495,29 @@ ${recentLines.join("\n")}`;
 
   /** Respond to an HTTP pending escalation. */
   respondHttp(id: string, response: string): { ok: boolean; error?: string } {
-    if (!this.httpPending) {
-      return { ok: false, error: "no pending escalation" };
-    }
-    if (this.httpPending.id !== id) {
-      return { ok: false, error: `id mismatch: expected ${this.httpPending.id}` };
+    // Grace path: the agent's response arrived for a stale ID because the
+    // analyzer rotated the pending slot mid-flight. Still push to HUD — the
+    // response was written against context that was fresh seconds ago and is
+    // almost certainly still relevant — but don't clear the current pending,
+    // so the agent can still address the newer escalation on its next poll.
+    if (!this.httpPending || this.httpPending.id !== id) {
+      const recent = this.recentHttpIds.find((e) => e.id === id);
+      if (recent && Date.now() - recent.ts < Escalator.STALE_ID_GRACE_MS) {
+        // Grace path: response was generated against a context that's now
+        // stale (analyzer rotated the slot mid-flight) but still recent
+        // enough that the answer is almost certainly still relevant.
+        // Push to HUD and return a clean ok=true — don't surface the
+        // grace marker on the wire, because generic LLM clients read
+        // any non-empty `error` field as a failure signal and write
+        // apologetic meta-messages to the user. The breadcrumb stays
+        // in this log for debug.
+        log(TAG, `respondHttp grace: id=${id} is stale (rotated ${((Date.now() - recent.ts) / 1000).toFixed(1)}s ago) — pushing to HUD anyway`);
+        this.pushResponse(response, this.lastEscalationContext);
+        return { ok: true };
+      }
+      return this.httpPending
+        ? { ok: false, error: `id mismatch: expected ${this.httpPending.id}` }
+        : { ok: false, error: "no pending escalation" };
     }
 
     this.pushResponse(response, this.lastEscalationContext);
@@ -446,7 +578,6 @@ ${recentLines.join("\n")}`;
   getStats(): Record<string, unknown> {
     return {
       mode: this.deps.escalationConfig.mode,
-      transport: this.deps.escalationConfig.transport,
       gatewayConnected: this.wsClient.isConnected,
       circuitOpen: this.wsClient.isCircuitOpen,
       slotDepth: this.slot.depth,
@@ -501,13 +632,42 @@ ${recentLines.join("\n")}`;
     // ★ Broadcast "spawned" BEFORE the RPC — TSK tab shows ··· immediately
     this.broadcastTaskEvent(taskId, "spawned", label, startedAt);
 
-    if (!this.wsClient.isConnected) {
-      // No OpenClaw gateway — queue for bare agent HTTP polling
+    // Route explicitly by the overlay's spawn-agent selection:
+    //   "openclaw" (or "" with WS connected) → send to remote gateway via WS RPC
+    //   any other non-empty value             → queue for local bare agent HTTP poll
+    //   "" with WS disconnected               → queue for HTTP fallback (same)
+    // This makes the overlay's choice authoritative. Before openclaw was a
+    // roster option, the old heuristic "if WS connected, use gateway" hijacked
+    // every spawn regardless of user intent, which surfaced as 401/credential
+    // errors from the gateway's stale OpenRouter key.
+    // Per-lane dispatch (mirror of escalation routing above):
+    //   - profile.type === "openclaw" → WS to gateway (drop with toast if
+    //     WS down — bare agent can't run gateway profiles as local CLIs)
+    //   - any other non-empty agent → HTTP queue for bare agent polling
+    //   - empty (Off) → drop; the spawn poll skip in run.sh should already
+    //     prevent us from getting here.
+    const spawnAgent = this.deps.getSpawnAgent?.() || "";
+    const spawnIsGateway = this.deps.isGatewayAgent?.(spawnAgent) ?? false;
+    if (spawnIsGateway) {
+      if (!this.wsClient.isConnected) {
+        log(TAG, `spawn-task ${taskId}: dropped — gateway agent "${spawnAgent}" selected but WS disconnected`);
+        this.deps.wsHandler.broadcast(
+          `⚠ Gateway disconnected — spawn task dropped. Pick a local agent or check the ${spawnAgent} gateway.`,
+          "high",
+        );
+        return;
+      }
+      // Fall through to gateway dispatch below.
+    } else if (spawnAgent) {
+      // Local bare-agent path: queue for polling.
       this.spawnHttpPending = { id: taskId, task, label: label || "background-task", ts: startedAt };
       const preview = task.length > 60 ? task.slice(0, 60) + "…" : task;
       this.deps.feedBuffer.push(`🔧 Task queued for agent: ${preview}`, "normal", "system", "stream");
       this.deps.wsHandler.broadcast(`🔧 Task queued for agent: ${preview}`, "normal");
-      log(TAG, `spawn-task ${taskId}: WS disconnected — queued for bare agent polling`);
+      log(TAG, `spawn-task ${taskId}: queued for bare agent (lane=${spawnAgent})`);
+      return;
+    } else {
+      log(TAG, `spawn-task ${taskId}: dropped — lane is Off (spawnAgent="")`);
       return;
     }