#17929: fix(skills): augment PATH with /etc/paths on macOS for binary detection
commands
stale
size: S
experienced-contributor
Cluster:
Node and macOS Enhancements
## Summary
Fixes #17890.
`detectBinary` uses `/usr/bin/env which <name>` to locate binaries, but inherits `process.env.PATH` from the parent process. When launched as a macOS app (not from a shell), the process PATH is restricted to `/usr/bin:/bin:/usr/sbin:/sbin`, which excludes `/opt/homebrew/bin` (Homebrew on Apple Silicon) and `/usr/local/bin`.
## Root Cause
`detectBinary` spawns `which` via `runCommandWithTimeout`, which passes `process.env` to the child process. macOS app processes do not inherit shell-configured PATH, so Homebrew-installed binaries are invisible.
## Fix
Add a `resolveSystemPath()` helper that reads `/etc/paths` and `/etc/paths.d/*` on macOS, plus common Homebrew prefixes (`/opt/homebrew/bin`, `/usr/local/bin`) as fallbacks. The merged PATH is passed to the `which` subprocess via the `env` option.
## Before
```
detectBinary("brew") with restricted PATH: false
❌ FAIL: detectBinary cannot find brew with restricted PATH
```
## After
```
detectBinary("brew") with restricted PATH: true
✅ PASS: detectBinary finds brew with restricted PATH after fix
```
## Test Plan
- Added `onboard-helpers.detect-binary.test.ts` with 6 tests covering empty names, standard binaries, absolute paths, nonexistent binaries, and the macOS restricted-PATH regression case.
- All tests pass locally.
- Lint passes (`pnpm lint` — 0 warnings, 0 errors).
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
This PR fixes `detectBinary` failing to find Homebrew-installed binaries when the process runs as a macOS app (not from a shell), where `process.env.PATH` is restricted to `/usr/bin:/bin:/usr/sbin:/sbin`.
- Adds a `resolveSystemPath()` helper that reads `/etc/paths` and `/etc/paths.d/*` on macOS, plus common Homebrew prefixes (`/opt/homebrew/bin`, `/usr/local/bin`) as fallbacks
- The resolved system PATH is cached at module level to avoid repeated file I/O across multiple `detectBinary` calls
- The merged PATH is passed via the `env` option to `runCommandWithTimeout`, which correctly merges it with `process.env` (preserving all other environment variables)
- The fix is macOS-only — on other platforms, `resolveSystemPath()` returns `undefined` and the original behavior is preserved
- Adds a new test file with 6 test cases covering edge cases and the macOS restricted-PATH regression
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge — it's a well-scoped macOS-only fix with proper caching, error handling, and no behavioral change on other platforms.
- The fix is narrowly targeted to macOS binary detection, correctly reads standard system PATH configuration files, caches the result to avoid repeated I/O, and preserves existing behavior on all non-macOS platforms. The `runCommandWithTimeout` function properly merges the custom env with `process.env`, so all other environment variables are preserved. Error paths fall back gracefully to `undefined`. The test covers relevant edge cases and the specific regression scenario.
- No files require special attention.
<sub>Last reviewed commit: 68a25bb</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#22370: fix(skills): resolve Homebrew/common binary locations
by AIflow-Labs · 2026-02-21
82.2%
#17951: fix: macOS app: Skill binary detection does not respect /etc/paths ...
by MisterGuy420 · 2026-02-16
81.3%
#18112: fix(daemon): gateway install on macOS ignores fnm/nvm node (#18090)
by yinghaosang · 2026-02-16
77.7%
#20584: fix: use stable Homebrew symlink for daemon node path
by mwfj · 2026-02-19
77.4%
#4709: fix(daemon): include user bin dirs in macOS LaunchAgent PATH
by ekson73 · 2026-01-30
77.3%
#19931: Config: merge PATH env vars and bootstrap Windows bins
by Kemalau · 2026-02-18
76.3%
#21733: security(exec): platform-aware allowlist matching and restricted sa...
by Esubaalew · 2026-02-20
73.7%
#20330: Fix SSH tunnel startup on Windows by resolving ssh from PATH
by graysurf · 2026-02-18
73.3%
#22910: fix(browser): resolve symlinks in upload path validation
by erdinccurebal · 2026-02-21
73.2%
#16295: fix: filter brew install options when brew is unavailable
by superlowburn · 2026-02-14
73.2%