Bug Report: Hermes Desktop v0.18.x — Frontend WebSocket not connected to `hermes serve` backend

[lofspade]

Environment

• Hardware: NVIDIA DGX Spark (ARM64, NVIDIA GB10 GPU)
• OS: Ubuntu 24.04, X11 (DISPLAY=:1)
• Hermes version: 0.18.2 (build 0b2907f)
• Electron version: 40.10.2
• Model provider: DeepSeek， LM Studio
• Desktop launch method: hermes desktop (CLI)

Symptoms

After hermes update (from ~0.15.x to 0.18.x), Hermes Desktop exhibits the following issues:

1. Electron window opens, backend (hermes serve) starts successfully (visible in desktop.log)
2. User can type in the chat input, and the agent starts executing tool calls (task timer is visible)
3. Agent response text NEVER appears in the chat window — only tool execution progress is shown
4. After first failed response, a second message attempt shows "Gateway is not connected" error
5. The Desktop window must be restarted to clear the error

What works correctly

• hermes serve backend starts and runs normally
• hermes dashboard (Web UI in browser) works perfectly — same backend, same model
• hermes chat (CLI) works perfectly
• All gateway platforms (QQ Bot, Feishu) work fine

Root Cause Analysis

The issue is in the Electron Desktop's gateway WebSocket connection mechanism introduced with hermes serve as the backend.

How it works (v0.18.x):

1. hermes desktop spawns the Electron binary
2. Electron's startHermes() → spawns hermes serve --port 0 as a child process (auto-assigned random port)
3. The backend announces readiness via stdout HERMES_BACKEND_READY port=XXXXX
4. Desktop frontend calls hermes:gateway:ws-url IPC to get the WebSocket URL
5. Frontend establishes a WebSocket connection to ws://127.0.0.1:PORT/api/ws?token=...
6. The agent's streaming responses are pushed through this WebSocket

The bug:

• The hermes:api REST IPC works fine (session list, tool execution → timer visible)
• The WebSocket connection either fails to establish or drops after the first request
• When agent tries to stream response → ECONNRESET / socket hang up
• Frontend shows error "Gateway is not connected"
• The old backend port becomes stale when desktop is restarted or respawns

Key log evidence:

Error occurred in handler for 'hermes:api': Error: connect ECONNREFUSED 127.0.0.1:44583
[hermes] [boot] Hermes backend is ready. Finalizing desktop startup
[hermes] [renderer] render-process-gone reason=clean-exit exitCode=0

The issue is NOT GPU-related (already confirmed with --no-sandbox --disable-gpu --in-process-gpu).

Additional issue on DGX Spark:

Electron v40.10.2 has GPU process crash on this platform due to NVIDIA ARM64 GPU incompatibility:

FATAL:content/browser/gpu/gpu_data_manager_impl_private.cc:415
GPU process isn't usable. Goodbye.

This was worked around with --disable-gpu --disable-software-rasterizer --in-process-gpu flags via desktop.electron_flags config. However, even with this fix, the WS disconnection issue persists independently.

Suggested Investigation

1. Check getGatewayWsUrl() → freshGatewayWsUrl() in apps/desktop/electron/main.ts — verify the WS URL returned to frontend matches the actual hermes serve port
2. Check whether hermes serve's WebSocket endpoint at /api/ws correctly authenticates the token passed from Electron
3. Investigate if the WS connection is established via the Electron main process proxy or direct from renderer — the hermes:api IPC works, suggesting the REST API is fine but the WS path is different
4. The connection.json at app.getPath("userData")/connection.json with {"mode":"local"} should be sufficient for local mode — verify it's not causing WS issues
5. Check if hermes gateway run (spawned as subprocess of hermes serve) handles WS differently from the old hermes dashboard backend

Workaround

Using hermes dashboard (Web UI via browser) instead of the Electron Desktop completely avoids the issue.