fix(terminal): complete sane PATH entries on POSIX

[y0shua1ee]

What does this PR do?

Fixes macOS gateway/launchd terminal sessions whose PATH already includes /usr/bin while omitting Apple Silicon Homebrew paths. LocalEnvironment._make_run_env() now appends each missing _SANE_PATH entry individually on POSIX, preserving caller precedence and avoiding duplicate sane entries.

Root cause: the previous logic used /usr/bin as the sentinel for sane PATH injection. macOS launchd commonly provides /usr/bin while leaving out /opt/homebrew/bin and /opt/homebrew/sbin, so Homebrew-installed CLIs stayed unavailable in terminal tool calls.

User-visible impact: terminal sessions launched from the gateway can resolve Homebrew CLIs such as gh, brew, and xurl through the default environment fallback, reducing absolute-path workarounds on macOS.

Related Issue

Fixes #35613

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• tools/environments/local.py
  • Add _append_missing_sane_path_entries() to append missing _SANE_PATH entries per item on POSIX.
  • Add _path_env_key() so Windows keeps the existing PATH/Path key casing.
  • Update _make_run_env() to use the helper instead of the /usr/bin sentinel.
• tests/tools/test_local_env_blocklist.py
  • Add a regression test for launchd-style PATH=/usr/local/bin:/usr/bin:/bin missing Homebrew entries.
  • Cover duplicate prevention and Windows Path casing preservation.
• tests/tools/test_windows_native_support.py
  • Replace the brittle source-string check with behavior coverage for Windows PATH no-op handling.

How to Test

1. Reproduce the old failure with the new regression test against the previous implementation:

   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

   Old behavior failed with:

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

2. Run the targeted cross-platform coverage:

   PYTHONPATH=. python -m pytest \
     tests/tools/test_local_env_blocklist.py \
     tests/tools/test_env_passthrough.py \
     tests/test_subprocess_home_isolation.py \
     tests/tools/test_windows_native_support.py::TestLocalEnvironmentPathInjectionGated \
     tests/tools/test_local_env_windows_msys.py \
     -o 'addopts=' -q

   Result: 69 passed.

3. Run formatting/lint checks:

   git diff --check
   PYTHONPATH=. python -m ruff check \
     tools/environments/local.py \
     tests/tools/test_local_env_blocklist.py \
     tests/tools/test_windows_native_support.py

   Result: All checks passed!.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: macOS 26.5

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

.....................................................................    [100%]
69 passed in 1.48s
All checks passed!
OK: added-line privacy/security scans passed

[tonydwb]

Code Review Summary

Verdict: Approved ✅

Reviewed Changes

• tools/environments/local.py — Refactored PATH injection into _append_missing_sane_path_entries() and _path_env_key() helpers. PATH completion now: (1) skips Windows entirely, (2) checks each POSIX sane entry individually rather than using a /usr/bin presence heuristic, (3) deduplicates entries, (4) handles Windows Path key casing.
• tests/tools/test_local_env_blocklist.py — Expanded tests: macOS launchd minimal PATH, Homebrew completion, no duplication, Windows PATH unchanged, Windows mixed-case Path key.
• tests/tools/test_windows_native_support.py — Replaced source-string assertion with actual runtime test.

✅ Looks Good

• Correctness: The old code used /usr/bin not in existing_path.split(":") which would match a /usr/bin anywhere in the path — but then appended the entire _SANE_PATH. Worse, on Windows with ; separator, the split produced one huge chunk which would always match the heuristic and skip injection entirely (wrong behavior in both directions). The new code checks each sane entry individually and appends only what's missing. Windows is completely skipped.
• Edge cases: Empty PATH, mixed-case Windows Path key, macOS Homebrew paths, duplicate entry prevention — all handled.
• Test coverage: The old source-string assertion ('not _IS_WINDOWS and "/usr/bin" not in existing_path.split(":")' in source) was brittle and tested the implementation detail, not the behavior. The new tests actually exercise the function.

---

Reviewed by Hermes Agent

[marsmensch]

Adding a concrete real-world repro to help push this over the line.

Reproduction: Hermes Desktop (.app) on macOS

Launching Hermes from the macOS Desktop app (com.nousresearch.hermes) gives the Python process the bare launchd GUI PATH:

/usr/bin:/bin:/usr/sbin:/sbin

With the unfixed guard, _make_run_env sees /usr/bin already present and skips injection entirely. The result: read_file shells out to sed -n '...' <path> and intermittently fails with:

Failed to read file: /bin/bash: line 2: sed: command not found

This also breaks search_files, patch, and any other file tool that uses the local backend — anything that shells out to standard Unix utils. The failure is intermittent because the persistent-shell snapshot can mask it until it's rebuilt in a degraded state.

Verified fix: the approach in this PR (append missing entries per-item rather than all-or-nothing) resolves it completely. Applied the same logic locally, 7/7 regression tests pass including the new test_make_run_env_fills_missing_homebrew_when_usr_bin_present that directly covers the launchd PATH case.

Merging this would fix the Desktop app for all macOS users. The PR is already approved — flagging in case it just needs a final review pass to land.

[kshitijk4poor]

Thanks for this @y0shua1ee — the root-cause analysis was spot on. The /usr/bin sentinel really did mask the common macOS launchd case where /usr/bin is present but the Homebrew dirs aren't.

This landed via #42653 (merged just now): your fix is the first commit, cherry-picked unchanged and credited via Co-authored-by, with a small follow-up that de-duplicates the caller PATH and strips empty entries, plus a docs commit clarifying the normalisation semantics. I verified it end-to-end against a real launchd-style PATH through LocalEnvironment.execute() — gh/brew resolve via /opt/homebrew/bin with the fix and fail without it.

Closing in favour of #42653. Appreciate the clean diagnosis and tests!