fix(desktop): find user-installed CLIs when shell probing fails

[CyberStefNef]

What Changed

resolveKnownPosixCliDirs in packages/shared/src/shell.ts returns the standard CLI directories for macOS and Linux, beside the existing resolveKnownWindowsCliDirs. Both POSIX PATH hydration paths now fall back to it when neither the login shell nor launchctl getenv PATH answers: installPosixEnvironment in apps/desktop/src/shell/DesktopShellEnvironment.ts and hydratePosixPath in apps/server/src/os-jank.ts.

The fallback is last in the chain, so a shell that did answer still decides the order. Directories are not checked for existence, matching resolveKnownWindowsCliDirs.

Why

A Finder launch starts the app with /usr/bin:/bin:/usr/sbin:/sbin. Both hydration paths repair that from the login shell, but the probe collapses failures and timeouts into an empty result, so a profile slower than the 5s timeout leaves PATH untouched. launchctl getenv PATH is unset on recent macOS, so the second probe returns nothing either. Every bare-name spawn then fails with ENOENT: #7618 counted 1246 failed gh spawns and zero successes over 14 hours, with gh auth status never running.

#1799 built this chain and added the launchctl probe as its last step. This adds the next step, for machines where that probe is also empty. Raising the timeout does not help, since the probe fails for reasons unrelated to how long it is given.

Both Windows paths already end in resolveKnownWindowsCliDirs. POSIX ended in nothing.

Closes #7618

Verification

• vp test run apps/desktop/src/shell/DesktopShellEnvironment.test.ts packages/shared/src/shell.test.ts apps/server/src/os-jank.test.ts: 54 passed.
• Typecheck for @t3tools/desktop, @t3tools/shared, and the server.
• vp lint on the five changed files with --report-unused-disable-directives.
• git diff --check: clean.
• Seven added tests: the macOS and Linux fallbacks in both hydration paths, and guards that the known directories stay out of the merge when either probe answers. Reverting the source change fails the fallback tests and leaves the guards passing.

Checklist

• This PR is small and focused
• I explained what changed and why
• Screenshots are not applicable because nothing visual changed
• A video is not applicable because no motion or interaction changed

---

Note

Medium Risk
Changes process PATH for all POSIX desktop and server startups when probes fail; behavior shifts from minimal system PATH to hard-coded install locations, which could affect spawn resolution in edge environments but addresses widespread CLI spawn failures.

Overview
When login-shell and (on macOS) launchctl PATH probes return nothing—common for GUI/Finder launches with a minimal PATH—POSIX hydration no longer leaves only /usr/bin:/bin:….

Shared: Adds resolveKnownPosixCliDirs (macOS Homebrew//usr/local/~/.local/bin, Linux Linuxbrew//usr/local/~/.local/bin; skips ~/.local if HOME is blank), mirroring the existing Windows known-CLI helper and without checking that directories exist.

Desktop & server: installPosixEnvironment and hydratePosixPath use that list as the last preferred PATH segment before merging with the inherited PATH. Any PATH from the login shell or launchctl still wins and does not inject these defaults.

New unit tests cover macOS/Linux fallback merges and assert the known dirs are not added when either probe succeeds.

^{Reviewed by Cursor Bugbot for commit 10ead92. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add known CLI directory fallback to hydratePosixPath and installPosixEnvironment

• Adds shared resolveKnownPosixCliDirs resolver that returns platform-specific CLI install directories (Homebrew on macOS, Linuxbrew on Linux, plus system-local and HOME-local bin).
• Both desktop POSIX environment installation and server PATH hydration now prepend these known directories as a final fallback when neither the login shell nor launchctl produces a PATH.
• A PATH from the login shell or launchctl remains preferred and is used directly without adding the fallback directories.
• Risk: any caller relying on an empty PATH when probes fail will now receive a non-empty PATH composed of known CLI directories; the HOME-local entry is omitted when HOME is blank or unset.

^{Macroscope summarized 10ead92.}

[macroscopeapp]

Approvability

Verdict: Approved at 5d8d654

Macroscope's review found this PR approvable — This focused bug fix adds known POSIX CLI directories only when existing shell and launchctl PATH discovery fails, leaving successful probe paths unchanged. The implementation is small, isolated, and tested, with no schema, deployment, security-sensitive, or static-analysis configuration changes.

^{You can add or adjust custom eligibility rules. Learn more.}

[weskcode]

Hit the same bug (Claude Code and OpenCode installed via their native installers, at ~/.local/bin/claude and ~/.opencode/bin/opencode; neither found on PATH) and had built basically this same fix before finding this PR.

One directory missing from resolveKnownPosixCliDirs that would close the gap for OpenCode specifically: ~/.opencode/bin. Claude Code is already covered here via the shared ~/.local/bin entry.

Separately (more of a discussion than a one-line fix): this only fires via Option.orElse when both probes return nothing. resolveKnownWindowsCliDirs's usage in resolveWindowsEnvironment merges its known dirs unconditionally, after the resolved PATH, regardless of whether the probe succeeded — the comment there even says it's meant to "fill gaps when desktop apps launch without the full interactive-shell PATH." Doing the same here would also catch a probe that succeeds but is just missing a directory. Not proposing this as part of the same patch, since it reverses a guard you explicitly tested for (the two tests asserting known dirs stay out when either probe succeeds) — just flagging the asymmetry with the Windows path in case it's worth a follow-up.

Happy to open a PR adding ~/.opencode/bin on top of this branch, or hand it over if that's less work for you. juliusmarminge flagged this class of fix as a useful last-resort mitigation on #10534, just not enough on its own to close that issue.