hermes - 💡(How to fix) Fix Dashboard /chat shows 'gateway exited' when .venv exists alongside venv

Summary

The Dashboard embedded chat (/chat) fails with "gateway exited" when both .venv/ and venv/ directories exist under the hermes-agent root, but .venv is an incomplete virtual environment (missing dependencies like python-dotenv).

Root Cause

ui-tui/dist/gatewayClient.js resolves the Python interpreter via resolvePython(), which checks candidates in this order:

// gatewayClient.js — resolvePython()
const hit = [
  venv && resolve(venv, 'bin/python'),        // VIRTUAL_ENV
  venv && resolve(venv, 'Scripts/python.exe'),
  resolve(root, '.venv/bin/python'),           // ← matched first
  resolve(root, '.venv/bin/python3'),
  resolve(root, 'venv/bin/python'),            // ← correct one, never reached
  resolve(root, 'venv/bin/python3')
].find(p => p && existsSync(p));

When .venv/bin/python exists (created by uv during initial setup), it is selected before venv/bin/python. However, .venv was never fully set up — it's missing packages like python-dotenv that tui_gateway.entry requires at import time.

The result:

$ .venv/bin/python -m tui_gateway.entry
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "/Users/…/tui_gateway/entry.py", line 19, in <module>
    from tui_gateway import server
  File "/Users/…/tui_gateway/server.py", line 19, in <module>
    from hermes_cli.env_loader import load_hermes_dotenv
  File "/Users/…/hermes_cli/env_loader.py", line 9, in <module>
    from dotenv import load_dotenv
ModuleNotFoundError: No module named 'dotenv'

The TUI's GatewayClient sees the subprocess exit with code 1, and renders "error: gateway exited" with no further detail — the crash log (~/.hermes/logs/tui_gateway_crash.log) is never written because the process dies before entry.py:main() runs.

Reproduction

1. Install hermes-agent (creates both .venv/ and venv/)
2. Ensure .venv/ exists but is incomplete (no pip install -e '.[all]' was run in it)
3. Run HERMES_DASHBOARD_TUI=1 hermes dashboard
4. Open http://127.0.0.1:9119/chat
5. Observe "gateway exited" in the chat terminal

Suggested Fix

Either:

1. Validate the resolved Python — after resolvePython(), verify the Python can actually import tui_gateway before using it. Fall through to the next candidate on failure.
2. Prefer venv/ over .venv/ — swap the search order so the pip-managed venv is checked first.
3. Remove stale .venv/ — if the installer creates .venv/ via uv but then builds deps in venv/, clean up the incomplete .venv/ afterward.

Option 1 is the most robust since it handles any misconfigured venv, not just this specific ordering issue.

Workaround

Set HERMES_PYTHON in ~/.hermes/.env to bypass the resolution logic:

HERMES_PYTHON=/path/to/hermes-agent/venv/bin/python3

Environment

• macOS 14 (Darwin 24.6.0, aarch64)
• hermes-agent installed via pip
• .venv created by uv 0.11.9, venv created by hermes installer
• Both point to cpython-3.11.15