hermes - 💡(How to fix) Fix doctor: Homebrew install falsely warns 'Venv entry point not found' [2 pull requests]

Bug Description

On the Homebrew install, hermes doctor reports a command-installation warning even though Hermes is installed and runnable from the Homebrew-managed libexec/bin/hermes entry point.

The warning appears to assume only editable/source checkouts with venv/bin/hermes or .venv/bin/hermes are valid:

◆ Command Installation
  ⚠ Venv entry point not found (hermes not in venv/bin/ or .venv/bin/ — reinstall with pip install -e '.[all]')

This is misleading for Homebrew users, because the actual entry point is present and working under the formula prefix.

Steps to Reproduce

On macOS with Hermes installed through Homebrew:

brew install hermes-agent
hermes --version
hermes doctor

Expected Behavior

hermes doctor should recognize the Homebrew layout as healthy when the entry point exists at:

$(brew --prefix hermes-agent)/libexec/bin/hermes

and avoid suggesting:

cd <site-packages> && source venv/bin/activate && pip install -e '.[all]'

for a Homebrew-managed install.

Actual Behavior

hermes doctor warns:

⚠ Venv entry point not found

and suggests a source checkout / editable-install remediation that does not match the Homebrew package layout.

Environment

Validated locally:

Hermes Agent v0.15.2 (2026.5.29.2)
Project: /opt/homebrew/Cellar/hermes-agent/2026.5.29.2/libexec/lib/python3.14/site-packages
Python: 3.14.5

Working entry point:

/opt/homebrew/Cellar/hermes-agent/2026.5.29.2/libexec/bin/hermes

Launchd gateway also points to the current Homebrew install:

/opt/homebrew/Cellar/hermes-agent/2026.5.29.2/libexec/bin/python -m hermes_cli.main gateway run --replace

Likely Cause

In hermes_cli/doctor.py, the Command Installation section currently searches only:

PROJECT_ROOT / "venv" / "bin" / "hermes"
PROJECT_ROOT / ".venv" / "bin" / "hermes"

For Homebrew installs, PROJECT_ROOT is the package site-packages directory, while the actual executable lives in the sibling libexec/bin directory.

Suggested Fix

Detect Homebrew-style installs before warning. For example, treat any of these as healthy:

• sys.executable under .../Cellar/hermes-agent/<version>/libexec/bin/python
• Path(sys.executable).with_name("hermes") exists
• shutil.which("hermes") resolves inside the same Homebrew formula prefix

Then print something like:

✓ Homebrew entry point exists (libexec/bin/hermes)

instead of the editable-install warning.

Impact

Low severity but noisy: it makes hermes doctor report a false issue after a normal Homebrew install/update, which can send users toward an inappropriate pip install -e repair path.