refactor(hermes): defer port recovery changes

Signed-off-by: Shannon Sands <shannon.sands.1979@gmail.com>

Author: shannonsands

agents/hermes/plugin/__init__.py

@@ -18,7 +18,6 @@
 import os
 import subprocess
 import yaml
-from urllib.parse import urlparse
 
 
 def _load_nemoclaw_config():
@@ -48,22 +47,6 @@ def _load_hermes_config():
     return None
 
 
-def _get_gateway_port():
-    """Return the sandbox-exposed Hermes API port."""
-    raw = os.environ.get("NEMOCLAW_DASHBOARD_PORT")
-    if raw and raw.isdigit():
-        return int(raw)
-    chat_url = os.environ.get("CHAT_UI_URL", "")
-    if chat_url:
-        try:
-            parsed = urlparse(chat_url)
-            if parsed.port:
-                return int(parsed.port)
-        except Exception:
-            pass
-    return 8642
-
-
 def _get_sandbox_info():
     """Gather sandbox status information."""
     hermes_cfg = _load_hermes_config()
@@ -84,11 +67,10 @@ def _get_sandbox_info():
         provider = nemoclaw_cfg.get("provider", provider)
 
     # Check gateway health
-    gateway_port = _get_gateway_port()
     gateway_ok = False
     try:
         result = subprocess.run(
-            ["curl", "-sf", f"http://localhost:{gateway_port}/health"],
+            ["curl", "-sf", "http://localhost:8642/health"],
             capture_output=True,
             text=True,
             timeout=5,
@@ -104,7 +86,7 @@ def _get_sandbox_info():
         "provider": provider,
         "base_url": base_url,
         "gateway": "running" if gateway_ok else "stopped",
-        "port": gateway_port,
+        "port": 8642,
     }
 
 

agents/hermes/start.sh

@@ -109,23 +109,7 @@ case "${1:-}" in
 esac
 NEMOCLAW_CMD=("$@")
 CHAT_UI_URL="${CHAT_UI_URL:-http://127.0.0.1:8642}"
-PUBLIC_PORT="${NEMOCLAW_DASHBOARD_PORT:-}"
-if [ -z "$PUBLIC_PORT" ]; then
-  _chat_port="${CHAT_UI_URL##*:}"
-  _chat_port="${_chat_port%%/*}"
-  _chat_port="${_chat_port%%\?*}"
-  _chat_port="${_chat_port%%#*}"
-  case "$_chat_port" in
-    '' | *[!0-9]*) PUBLIC_PORT=8642 ;;
-    *) PUBLIC_PORT="$_chat_port" ;;
-  esac
-fi
-case "$PUBLIC_PORT" in
-  '' | *[!0-9]*) PUBLIC_PORT=8642 ;;
-esac
-export NEMOCLAW_DASHBOARD_PORT="$PUBLIC_PORT"
-CHAT_UI_URL="http://127.0.0.1:${PUBLIC_PORT}"
-export CHAT_UI_URL
+PUBLIC_PORT=8642
 # Hermes binds to 127.0.0.1 regardless of config (upstream bug).
 # Run it on an internal port and use socat to expose on PUBLIC_PORT.
 INTERNAL_PORT=18642

src/lib/actions/sandbox/process-recovery.ts

@@ -58,21 +58,20 @@ export function resolveSandboxDashboardPort(
   sandboxName: string,
   deps: SandboxPortDeps = {},
 ): number {
-  const getSandbox = deps.getSandbox ?? registry.getSandbox;
-  const sandbox = getSandbox(sandboxName);
-  if (isValidPort(sandbox?.dashboardPort)) {
-    return sandbox.dashboardPort;
-  }
-
   const getSessionAgent = deps.getSessionAgent ?? agentRuntime.getSessionAgent;
   const agent = getSessionAgent(sandboxName);
-  return agent && isValidPort(agent.forwardPort) ? agent.forwardPort : DASHBOARD_PORT;
+  if (agent && isValidPort(agent.forwardPort)) {
+    return agent.forwardPort;
+  }
+
+  const getSandbox = deps.getSandbox ?? registry.getSandbox;
+  const sandbox = getSandbox(sandboxName);
+  return isValidPort(sandbox?.dashboardPort) ? sandbox.dashboardPort : DASHBOARD_PORT;
 }
 
 function getSandboxHealthProbeUrl(sandboxName: string): string {
   const agent = agentRuntime.getSessionAgent(sandboxName);
-  const port = resolveSandboxDashboardPort(sandboxName);
-  if (agent) return agentRuntime.getHealthProbeUrlForPort(agent, port);
+  if (agent) return agentRuntime.getHealthProbeUrl(agent);
   return `http://127.0.0.1:${resolveSandboxDashboardPort(sandboxName)}/health`;
 }
 
@@ -302,10 +301,6 @@ function ensureSandboxPortForward(sandboxName: string): boolean {
   return isSandboxForwardHealthy(sandboxName) === true;
 }
 
-function getPortForwardLabel(agent: unknown): string {
-  return agent ? `${agentRuntime.getAgentDisplayName(agent)} port forward` : "Dashboard port forward";
-}
-
 /**
  * Probe `openshell forward list` for the sandbox's dashboard forward.
  * Returns true when an entry exists for the expected sandbox+port pair
@@ -336,7 +331,7 @@ export function classifySandboxForwardHealth(
   const match = entries.find((entry) => entry.port === port);
   if (!match) return false;
   if (match.sandboxName !== sandboxName) return "occupied";
-  return match.status.includes("running") || match.status.includes("active");
+  return match.status === "running";
 }
 
 /**
@@ -356,7 +351,6 @@ export function checkAndRecoverSandboxProcesses(
   }
   const recoveryAgent = agentRuntime.getSessionAgent(sandboxName);
   const recoveryPort = resolveSandboxDashboardPort(sandboxName);
-  const forwardLabel = getPortForwardLabel(recoveryAgent);
   if (running) {
     // Gateway is alive but the host-side forward can still be dead or
     // owned by another sandbox. Probe and re-establish only when
@@ -365,15 +359,15 @@ export function checkAndRecoverSandboxProcesses(
     if (forwardHealthy === false) {
       if (!quiet) {
         console.log("");
-        console.log(`  ${forwardLabel} to '${sandboxName}' is missing or dead.`);
+        console.log(`  Dashboard port forward to '${sandboxName}' is missing or dead.`);
         console.log("  Re-establishing...");
       }
       const forwardRecovered = ensureSandboxPortForward(sandboxName);
       if (!quiet) {
         if (forwardRecovered) {
-          console.log(`  ${G}✓${R} ${forwardLabel} re-established.`);
+          console.log(`  ${G}✓${R} Dashboard port forward re-established.`);
         } else {
-          console.error(`  Failed to re-establish the ${forwardLabel.toLowerCase()}.`);
+          console.error("  Failed to re-establish the dashboard port forward.");
           console.error(
             `  Run \`openshell forward start --background <port> ${sandboxName}\` manually.`,
           );
@@ -422,9 +416,9 @@ export function checkAndRecoverSandboxProcesses(
         `  ${G}✓${R} ${agentRuntime.getAgentDisplayName(recoveryAgent)} gateway restarted inside sandbox.`,
       );
       if (forwardRecovered) {
-        console.log(`  ${G}✓${R} ${forwardLabel} re-established.`);
+        console.log(`  ${G}✓${R} Dashboard port forward re-established.`);
       } else {
-        console.error(`  Failed to re-establish the ${forwardLabel.toLowerCase()}.`);
+        console.error("  Failed to re-establish the dashboard port forward.");
         console.error(
           `  Run \`openshell forward start --background <port> ${sandboxName}\` manually.`,
         );

src/lib/agent/runtime.test.ts

@@ -7,7 +7,6 @@ import {
   buildManualRecoveryCommand,
   buildOpenClawRecoveryScript,
   buildRecoveryScript,
-  getHealthProbeUrlForPort,
 } from "../../../dist/lib/agent/runtime";
 import type { AgentDefinition } from "./defs";
 
@@ -94,21 +93,14 @@ describe("buildRecoveryScript", () => {
   });
 
   it("omits --port for Hermes so config.yaml controls the internal listen port (#2426)", () => {
-    const script = buildRecoveryScript(hermesAgent, 18790);
+    const script = buildRecoveryScript(hermesAgent, 8642);
     expect(script).toContain("export HERMES_HOME=/sandbox/.hermes");
     expect(script).toContain("HERMES_HOME=/sandbox/.hermes");
-    expect(script).toContain("NEMOCLAW_DASHBOARD_PORT=18790");
-    expect(script).toContain("CHAT_UI_URL=http://127.0.0.1:18790");
     expect(script).toContain("HTTPS_PROXY=http://127.0.0.1:3129");
-    expect(script).toContain("http://localhost:18790/health");
     expect(script).toContain("nemoclaw-decode-proxy");
     expect(script).toContain('"$AGENT_BIN" gateway run');
-    expect(script).not.toContain('"$AGENT_BIN" gateway run --port 18790');
-    expect(script).not.toContain("hermes gateway run --port 18790");
-  });
-
-  it("rewrites health probe URLs to the active forwarded port", () => {
-    expect(getHealthProbeUrlForPort(hermesAgent, 18790)).toBe("http://localhost:18790/health");
+    expect(script).not.toContain('"$AGENT_BIN" gateway run --port 8642');
+    expect(script).not.toContain("hermes gateway run --port 8642");
   });
 
   it("falls back to openclaw gateway run when gateway_command is absent", () => {
@@ -322,14 +314,12 @@ describe("buildManualRecoveryCommand (#2426)", () => {
   });
 
   it("omits --port for Hermes and uses the current Hermes home", () => {
-    const cmd = buildManualRecoveryCommand(hermesAgent, 18790);
+    const cmd = buildManualRecoveryCommand(hermesAgent, 8642);
     expect(cmd).toContain("HERMES_HOME=/sandbox/.hermes");
-    expect(cmd).toContain("NEMOCLAW_DASHBOARD_PORT=18790");
-    expect(cmd).toContain("CHAT_UI_URL=http://127.0.0.1:18790");
     expect(cmd).toContain("HTTPS_PROXY=http://127.0.0.1:3129");
     expect(cmd).toContain("nemoclaw-decode-proxy");
     expect(cmd).toContain("nohup hermes gateway run");
-    expect(cmd).not.toContain("--port 18790");
+    expect(cmd).not.toContain("--port 8642");
     expect(cmd).not.toContain("/sandbox/.hermes-data");
   });
 

src/lib/agent/runtime.ts

@@ -52,18 +52,6 @@ export function getHealthProbeUrl(agent: AgentDefinition | null): string {
   return agent.healthProbe?.url || `http://127.0.0.1:${DASHBOARD_PORT}/health`;
 }
 
-export function getHealthProbeUrlForPort(agent: AgentDefinition | null, port: number): string {
-  const probeUrl = getHealthProbeUrl(agent);
-  if (!Number.isInteger(port) || port < 1 || port > 65535) return probeUrl;
-  try {
-    const parsed = new URL(probeUrl);
-    parsed.port = String(port);
-    return parsed.toString();
-  } catch {
-    return probeUrl.replace(/:(\d+)(?=\/|$)/, `:${String(port)}`);
-  }
-}
-
 function escapeEre(value: string): string {
   return value.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
 }
@@ -154,20 +142,15 @@ function gatewayLaunchCommand(command: string, runAsUser?: string): string {
   return `${logSelection} if [ "$(id -u)" = "0" ] && command -v gosu >/dev/null 2>&1 && id ${shellQuote(runAsUser)} >/dev/null 2>&1; then nohup gosu ${shellQuote(runAsUser)} ${command} >> "$_GATEWAY_LOG" 2>&1 & else ${userLaunch} fi;`;
 }
 
-function hermesGatewayEnvPrefix(port?: number): string {
+function hermesGatewayEnvPrefix(): string {
   const decodeProxy = "http://127.0.0.1:3129";
-  const envVars = [
+  return [
     "HERMES_HOME=/sandbox/.hermes",
     `HTTPS_PROXY=${decodeProxy}`,
     `HTTP_PROXY=${decodeProxy}`,
     `https_proxy=${decodeProxy}`,
     `http_proxy=${decodeProxy}`,
-  ];
-  if (typeof port === "number" && Number.isInteger(port) && port >= 1 && port <= 65535) {
-    envVars.push(`NEMOCLAW_DASHBOARD_PORT=${String(port)}`);
-    envVars.push(`CHAT_UI_URL=http://127.0.0.1:${String(port)}`);
-  }
-  return envVars.join(" ");
+  ].join(" ");
 }
 
 function hermesDecodeProxyRecoveryCommand(): string {
@@ -207,7 +190,7 @@ export function buildOpenClawRecoveryScript(port: number): string {
 export function buildRecoveryScript(agent: AgentDefinition | null, port: number): string | null {
   if (!agent) return null;
 
-  const probeUrl = getHealthProbeUrlForPort(agent, port);
+  const probeUrl = getHealthProbeUrl(agent);
   const binaryPath = agent.binary_path || "/usr/local/bin/openclaw";
   const binaryName = binaryPath.split("/").pop() ?? "openclaw";
   const defaultGatewayCommand = `${binaryName} gateway run`;
@@ -231,7 +214,7 @@ export function buildRecoveryScript(agent: AgentDefinition | null, port: number)
   // that's about to crash on a missing guard. (#2478)
   const isHermes = agent.name === "hermes";
   const hermesHome = isHermes ? "export HERMES_HOME=/sandbox/.hermes; " : "";
-  const hermesLaunchEnv = isHermes ? `env ${hermesGatewayEnvPrefix(port)} ` : "";
+  const hermesLaunchEnv = isHermes ? `env ${hermesGatewayEnvPrefix()} ` : "";
   const launchCommand = usesValidatedBinary
     ? gatewayLaunchCommand(`${hermesLaunchEnv}"$AGENT_BIN" gateway run${isHermes ? "" : ` --port ${port}`}`)
     : gatewayLaunchCommand(
@@ -279,10 +262,6 @@ export function getGatewayCommand(agent: AgentDefinition | null): string {
   return agent?.gateway_command || "openclaw gateway run";
 }
 
-export function getAgentForwardPort(agent: AgentDefinition | null): number {
-  return agent?.forwardPort ?? DASHBOARD_PORT;
-}
-
 /**
  * Build a single copy-pasteable command for the user to run when automatic
  * gateway recovery fails. Unlike the raw gateway command, this keeps the
@@ -293,7 +272,7 @@ export function buildManualRecoveryCommand(agent: AgentDefinition | null, port:
   const defaultGatewayCommand = `${shellQuote(binaryPath)} gateway run`;
   const gatewayCmd = agent?.gateway_command?.trim() || defaultGatewayCommand;
   const isHermes = agent?.name === "hermes";
-  const envPrefix = isHermes ? `${hermesGatewayEnvPrefix(port)} ` : "";
+  const envPrefix = isHermes ? `${hermesGatewayEnvPrefix()} ` : "";
   const portFlag = isHermes ? "" : ` --port ${port}`;
   const decodeProxySetup = isHermes ? `${hermesDecodeProxyRecoveryCommand()} ` : "";
   return `${buildGatewayLogSelection()} ${decodeProxySetup}${envPrefix}nohup ${gatewayCmd}${portFlag} >> "$_GATEWAY_LOG" 2>&1 &`;

test/hermes-plugin-handlers.test.ts

@@ -15,29 +15,6 @@ function runPython(script: string): string {
 }
 
 describe("Hermes NemoClaw plugin handlers", () => {
-  it("reads the active Hermes API port from the sandbox environment", () => {
-    const output = runPython(`
-import importlib.util
-import os
-import pathlib
-import sys
-import types
-
-plugin_path = pathlib.Path(sys.argv[1])
-yaml_stub = types.ModuleType("yaml")
-yaml_stub.safe_load = lambda *_args, **_kwargs: {}
-sys.modules.setdefault("yaml", yaml_stub)
-spec = importlib.util.spec_from_file_location("hermes_plugin", plugin_path)
-module = importlib.util.module_from_spec(spec)
-spec.loader.exec_module(module)
-
-os.environ["NEMOCLAW_DASHBOARD_PORT"] = "18790"
-print(module._get_gateway_port())
-`);
-
-    expect(output.trim()).toBe("18790");
-  });
-
   it("accepts Hermes dispatch kwargs for status, info, and reload handlers", () => {
     const output = runPython(`
 import importlib.util

test/process-recovery.test.ts

@@ -27,21 +27,12 @@ describe("resolveSandboxDashboardPort", () => {
     ).toBe(18789);
   });
 
-  it("uses the recorded dashboard port for non-OpenClaw agents when present", () => {
+  it("keeps non-OpenClaw agents on their declared forward port", () => {
     expect(
       resolveSandboxDashboardPort("hermes-box", {
         getSessionAgent: () => ({ forwardPort: 8642 }),
         getSandbox: () => ({ name: "hermes-box", dashboardPort: 18790 }),
       }),
-    ).toBe(18790);
-  });
-
-  it("falls back to a non-OpenClaw agent's declared forward port without registry metadata", () => {
-    expect(
-      resolveSandboxDashboardPort("hermes-box", {
-        getSessionAgent: () => ({ forwardPort: 8642 }),
-        getSandbox: () => null,
-      }),
     ).toBe(8642);
   });
 

test/recover-port-forward.test.ts

@@ -31,7 +31,6 @@ function setupFixture(opts: {
    *  reporting the original dead/missing state — models a failed restart. */
   forwardStartHeals?: boolean;
   port?: string;
-  agentName?: string;
 }): Fixture {
   const sandboxName = opts.sandboxName;
   const port = opts.port ?? "18789";
@@ -56,7 +55,6 @@ function setupFixture(opts: {
           provider: "nvidia-prod",
           gpuEnabled: false,
           policies: [],
-          agent: opts.agentName,
           dashboardPort: Number(port),
         },
       },
@@ -242,26 +240,4 @@ describe("nemoclaw <name> recover", () => {
       expect(calls.some((l) => l.startsWith("forward start "))).toBe(false);
     },
   );
-
-  it(
-    "uses the registry dashboard port for Hermes recovery instead of the manifest default",
-    testTimeoutOptions(20_000),
-    () => {
-      const fixture = setupFixture({
-        sandboxName: "hermes-sandbox",
-        gatewayProbe: "RUNNING",
-        forwardListStatus: "dead",
-        port: "18790",
-        agentName: "hermes",
-      });
-      const result = runRecover(fixture);
-      expect(result.status).toBe(0);
-
-      const calls = fs.readFileSync(fixture.invocationLog, "utf-8").split("\n");
-      expect(calls.some((l) => l.startsWith("forward stop 18790"))).toBe(true);
-      expect(calls.some((l) => l.startsWith("forward start --background 18790"))).toBe(true);
-      expect(calls.some((l) => l.startsWith("forward stop 8642"))).toBe(false);
-      expect(calls.some((l) => l.startsWith("forward start --background 8642"))).toBe(false);
-    },
-  );
 });