feat(desktop): resolve login-shell PATH for GUI launches (port of cline/cline#12429)

[teknium1]

Summary

GUI-launched Hermes Desktop (Finder/Dock on macOS, desktop launchers on Linux) now resolves the user's login-shell PATH once at startup and merges it into process.env before the backend spawns — so the backend subtree and the Electron-side resolvers can find Homebrew-, nvm-, pyenv-, cargo-, and ~/.local/bin-installed CLIs.

Ported from cline/cline#12429 (same approach as VS Code's shell environment resolution), adapted to the desktop app's existing backend-env.ts PATH machinery.

Root cause: launchd/desktop launchers hand GUI apps a minimal PATH (/usr/bin:/bin:/usr/sbin:/sbin); shell profiles never run. backend-env.ts's static sane-entry list papers over Homebrew//usr/local, but anything only a profile adds stays invisible — breaking tool availability checks (shutil.which('cua-driver') → computer_use schema silently missing, #51249), stdio MCP server spawns (npx/uvx from nvm or ~/.local/bin), and the Electron-side git/gh/hermes resolvers (#48158). The Python terminal tool's login-shell snapshot covers agent terminal commands, but not the backend process env itself.

Changes

• apps/desktop/electron/shell-path.ts (new): runs $SHELL -ilc (fallback -lc for the macOS system-bash-3.2 swallow documented in tests/tools/test_find_shell.py) printing $PATH between sentinel markers so profile banners/motd can't corrupt the capture. Merges login-shell entries first (Homebrew/version managers win), current-only entries appended, deduped via backend-env's appendUniquePathEntries. Single-flight, 5s-per-attempt timeout, stdin closed, never rejects — a broken shell profile never blocks boot. win32 no-op (Windows GUI apps get the user PATH from the registry env block).
• apps/desktop/electron/main.ts: warm the resolution at app.whenReady; await the same single-flight promise in the local-backend start path before runtime resolution, with rememberLog breadcrumbs.
• apps/desktop/electron/shell-path.test.ts (new): 12 tests — sentinel extraction under banner noise, last-marker poisoning guard, merge ordering/dedupe, -ilc→-lc fallback, failure/unchanged/win32 no-ops, single-flight memoization, never-rejects.

Validation

Check	Result
vitest --project electron shell-path.test.ts	12/12 pass
vitest --project electron backend-env.test.ts	6/6 pass (module reused, no regression)
tsc -p tsconfig.electron.json --noEmit	clean
eslint + prettier on changed files	clean
Live E2E (real shell, GUI-minimal env PATH=/usr/bin:/bin:/usr/sbin:/sbin)	enriched with ~/.local/bin, nvm node bin, ~/.cargo/bin, go bin; login entries first; deduped

Related

• Fixes desktop: macOS resolvers ignore Homebrew PATH before backend spawn #48158 (macOS resolvers ignore Homebrew PATH before backend spawn)
• Fixes [Bug]: Hermes Desktop backend PATH misses ~/.local/bin #51249 (Desktop backend PATH misses ~/.local/bin → cua-driver/computer_use invisible)
• Subsumes the narrower point-fixes in fix: resolve desktop binaries with backend PATH #48227 (@rlaope), fix(desktop): include user local bin in backend PATH #51251 (@y0shua1ee), and fix(desktop): resolve hermes CLI via login shell on Linux #43834 (@VrtxOmega) — credit to those contributors for independently mapping this bug family; maintainer call on close-with-credit.
• Source design: fix(desktop): resolve login shell PATH so agent can find gh and other CLI tools cline/cline#12429

Infographic

[github-actions]

૮ >ﻌ< ა ci review

_{ran on 8b3e136 — fix: resolve semantic merge conflict — startHermes update-wa}

⚠️ Warnings

CI timings · View report · View job

Wall time 27m17s vs 8m (+241.0%). 7 job(s) slower, 12 faster,

• Check no committed infographics / check-no-committed-infographics: +45.0s
• JS & TS checks / apps/desktop / check:test:ui:shard-1of3: +44.0s
• JS & TS checks / apps/desktop / check:test:ui:shard-2of3: -21.0s
• JS & TS checks / web / check: -13.0s
• JS & TS checks / apps/desktop / check:test:desktop:all: +11.0s

---

OSV vulnerability scan · View job

5 known vulnerabilities found in pinned dependencies.

• CVE-2026-67213 in package-lock.json
• CVE-2026-67213 in website/package-lock.json
• CVE-2026-70608 in package-lock.json
• CVE-2026-56876 in package-lock.json
• CVE-2026-70606 in package-lock.json

How to fix:

Review the findings in the Security tab. Update the affected dependencies if a patched version is available.

[VrtxOmega]

Thank you for the explicit credit and for carrying the diagnosis forward into the broader startup-level PATH solution. Resolving the login-shell PATH once for the backend is clearly stronger than my original point fix, and I appreciate you naming #43834 and the other contributors who independently mapped this bug family. I’m glad the investigation was useful.

[isak-ialogics]

Current main now conflicts in apps/desktop/electron/main.ts because local startup moved into runPrimaryBackendStartup; this needs a semantic rebase rather than choosing either conflict side. A narrow resolution is to retain main’s orchestrator and replace waitForLocalStart: waitForUpdateToFinish with an async callback that (1) awaits waitForUpdateToFinish(), then (2) awaits ensureLoginShellPath() and emits this PR’s applied/fallback log. That preserves main’s saved-remote fast path and guarantees the merged PATH is installed before prepareLocalBackend calls resolveHermesBackend. Keep this PR’s import and non-blocking app.whenReady() warmup; do not restore the old inline token/backend-resolution block.

[teknium1]

Refreshed against current main: startHermes local startup moved into runPrimaryBackendStartup (which now owns the update-mutex wait via waitForLocalStart), so the branch's pre-existing top-level waitForUpdateToFinish() call became a duplicate — removed it in the merge resolution and kept ensureLoginShellPath() before backend resolve, matching the new startup seam (thanks @isak-ialogics for flagging the semantic conflict). Verified: tsc -p tsconfig.electron.json clean, vitest --project electron electron/shell-path.test.ts 12/12 passing.