hermes - 💡(How to fix) Fix Windows: kanban workers crash with ModuleNotFoundError when gateway runs from venv (pip console_script launcher fails with restricted PATH)

Bug Description

On Windows 11, when the Hermes gateway runs from a virtual environment (venv) via Scheduled Task, the kanban dispatcher spawns worker processes that crash immediately with:

ModuleNotFoundError: No module named 'hermes_cli'

The root cause is in _resolve_hermes_argv() (hermes_cli/kanban_db.py, line 5196):

hermes_bin = _safe_which_no_cwd("hermes") if _IS_WINDOWS else shutil.which("hermes")
if hermes_bin:
    return _hermes_path_argv(hermes_bin)
return _module_hermes_argv()

Root Cause Chain

1. Gateway runs from a venv Python via Scheduled Task
2. Dispatcher calls _resolve_hermes_argv() → finds system Python hermes.EXE on PATH (from a different Python version)
3. Spawns this .exe via subprocess.Popen
4. pip's console_script launcher cannot bootstrap Python correctly when PATH is restricted (Scheduled Task / non-interactive session)
5. The editable install's __editable__ finder (.pth file) is never loaded → ModuleNotFoundError

Key finding: python -m hermes_cli.main (_module_hermes_argv()) always works in the same environment — the .exe launcher is the fragile path.

Workaround

Set HERMES_BIN=python -m hermes_cli.main in the gateway's environment. This forces _resolve_hermes_argv() to fall through to _module_hermes_argv(), which uses the current interpreter directly.

Suggested Fix

In _resolve_hermes_argv(), prefer the module form on Windows when running from a venv:

def _resolve_hermes_argv() -> list[str]:
    # On Windows, prefer module form inside a venv to avoid
    # pip console_script launcher failures under restricted PATH.
    if _IS_WINDOWS and (os.environ.get("VIRTUAL_ENV") or sys.prefix != sys.base_prefix):
        return _module_hermes_argv()
    # ... existing logic ...

Environment

• OS: Windows 11
• Hermes Agent: v0.14.0 (2026.5.16), editable install
• Gateway: Scheduled Task via Hermes_Gateway.cmd
• System Python: 3.12.10
• Venv Python: 3.13.12