hermes - 💡(How to fix) Fix [Bug]: macOS gateway terminal PATH skips Homebrew dirs when /usr/bin exists

Bug Description

Hermes Agent's terminal tool can start with an incomplete PATH on macOS gateway/launchd sessions. The current LocalEnvironment._make_run_env() logic gates _SANE_PATH injection on whether /usr/bin is present. A launchd/gateway PATH commonly already contains /usr/bin while still omitting Apple Silicon Homebrew directories such as /opt/homebrew/bin and /opt/homebrew/sbin.

User-visible impact: common Homebrew/user CLIs such as gh, brew, xurl, claude, codex, hermes, node, npm, and opencli require absolute paths or a custom shell init workaround in gateway terminal sessions.

Steps to Reproduce

1. Simulate a macOS launchd/gateway-style terminal environment with PATH=/usr/local/bin:/usr/bin:/bin.
2. Call tools.environments.local._make_run_env({}) with that environment.
3. Inspect the returned PATH.

A regression test captures the reproduction:

PYTHONPATH=. python -m pytest \
  tests/tools/test_local_env_blocklist.py::TestSanePathIncludesHomebrew::test_make_run_env_fills_missing_homebrew_when_usr_bin_present \
  -o 'addopts=' -q

Expected Behavior

The returned POSIX terminal PATH should preserve existing entries and append missing _SANE_PATH entries individually, including:

• /opt/homebrew/bin
• /opt/homebrew/sbin
• /usr/local/bin
• /usr/local/sbin

Existing entries should remain in their original order and should not be duplicated.

Actual Behavior

When /usr/bin is already present, _make_run_env() leaves the PATH unchanged. The Homebrew directories in _SANE_PATH are skipped, so Homebrew-installed CLIs are unavailable in the Hermes terminal environment.

Affected Component

• Gateway (Telegram/Discord/Slack/WhatsApp)
• Tools (terminal, file ops, web, code execution, etc.)
• Configuration (config.yaml, .env, hermes setup)

Messaging Platform

Discord gateway observed the issue; the root cause is in the local terminal environment setup and can affect any macOS gateway launched by launchd.

Debug Report

No uploaded debug report. This issue is backed by a focused unit-test reproduction and the root-cause analysis below.

Operating System

macOS via launchd/gateway terminal environment.

Python Version

Python 3.11.x.

Hermes Version

Upstream main at the time of filing.

Additional Logs / Traceback

The old behavior fails the new regression test with:

AssertionError: assert '/opt/homebrew/bin' in ['/usr/local/bin', '/usr/bin', '/bin']

Root Cause Analysis

tools/environments/local.py::_make_run_env() currently uses this sentinel:

if not _IS_WINDOWS and "/usr/bin" not in existing_path.split(":"):
    run_env["PATH"] = f"{existing_path}:{_SANE_PATH}" if existing_path else _SANE_PATH

The sentinel treats /usr/bin as proof that sane system paths are already present. macOS launchd commonly provides /usr/bin while omitting Homebrew directories, so the _SANE_PATH fallback path misses the main broken case.

Proposed Fix

• Add a helper that appends each missing _SANE_PATH entry individually on POSIX.
• Preserve the existing PATH order and avoid duplicate sane entries.
• Keep Windows behavior unchanged so POSIX paths are not injected into native Windows PATH values.
• Preserve Windows Path/PATH casing when an existing PATH-like environment key is present.

Are you willing to submit a PR for this?

• I'd like to fix this myself and submit a PR