hermes - 💡(How to fix) Fix hermes doctor crashes with PermissionError when gh is unavailable (e.g. WSL pointing to gh.exe) [3 pull requests]

Bug Description

Running hermes doctor crashes with an uncaught PermissionError when the gh CLI either isn't installed, isn't executable, or is a non-executable binary in $PATH (e.g. WSL users with Windows' gh.exe reachable via WSL PATH interop).

The function _gh_authenticated() in hermes_cli/doctor.py only catches FileNotFoundError and subprocess.TimeoutExpired, so any other OSError/PermissionError from subprocess.run propagates all the way out and aborts the doctor with a full traceback — even though the check is non-fatal and should just report "no GITHUB_TOKEN".

Steps to Reproduce

On WSL where Windows' gh.exe is reachable via $PATH but isn't a Linux executable:

1. From a shell where gh.exe is in $PATH (Windows-side GitHub CLI mounted into WSL):

   $ which gh          # empty
   $ command -v gh     # empty
   $ python3 -c "import subprocess; subprocess.run(['gh','--version'])"
   PermissionError: [Errno 13] Permission denied: 'gh'

2. Run hermes doctor.
3. Observe a traceback ending in:

   File ".../hermes_cli/doctor.py", line 1987, in _gh_authenticated
       result = subprocess.run(...)
   PermissionError: [Errno 13] Permission denied: 'gh'

The crash happens after the doctor has already printed most of its output, so users see what looks like a serious failure instead of a soft warning.

Expected Behavior

hermes doctor should treat _gh_authenticated() failures the same as "gh not found" — silently return False, then fall through to the existing check_warn("No GITHUB_TOKEN", ...) branch. No traceback.

Actual Behavior

Full Python traceback printed, exit code 0 (so it's confusing — looks like a crash but the command "succeeds").

Proposed Fix

Broaden the exception handler in _gh_authenticated() (hermes_cli/doctor.py ~line 1980) to also catch OSError:

def _gh_authenticated() -> bool:
    """Check if gh CLI is authenticated via token file or device flow."""
    try:
        result = subprocess.run(
            ["gh", "auth", "status", "--json", "authenticated"],
            capture_output=True, timeout=10,
        )
        return result.returncode == 0
    except (FileNotFoundError, PermissionError, OSError, subprocess.TimeoutExpired):
        return False

PermissionError is a subclass of OSError, so catching OSError covers both the unexecutable-binary case and any other platform-specific exec failure. Keeps the check non-fatal regardless of host environment.

Environment

• Hermes Agent: v0.15.1 (2026.5.29)
• OS: WSL2 Ubuntu
• Python: 3.11.15
• gh: not installed natively; gh.exe reachable via Windows PATH interop

Related

• #29442 — different doctor bug, around Copilot detection
• #16115 — older closed issue, "doctor warns missing GITHUB_TOKEN when gh CLI is authenticated"

Severity

Low — doctor still produces useful output, the crash is cosmetic. But it's the kind of thing that looks alarming in CI logs and erodes trust in the diagnostic.