Improve shell PATH hydration and fallback detection

[juliusmarminge]

Closes #1787

Summary

• Add shared login-shell candidate resolution that checks the configured shell, the user shell, and platform defaults without duplicates.
• Hydrate PATH by merging shell-provided entries with inherited entries instead of replacing them outright.
• Add a macOS launchctl fallback when shell probing does not yield a PATH value.
• Expand desktop and server environment hydration to preserve additional Homebrew and XDG variables when available.
• Cover the new shell candidate, launchctl, and PATH merge behavior with tests in shared, desktop, and server layers.

Testing

• bun fmt
• bun lint
• bun typecheck
• bun run test

---

Note

Medium Risk
Changes PATH and environment hydration behavior on macOS/linux (candidate shell probing, PATH merging, and launchctl fallback), which can affect command resolution and tooling discovery. Logging and additional env propagation reduce silent failures but broaden surface for platform-specific edge cases.

Overview
Improves PATH hydration for desktop and server on macOS/linux. Instead of replacing PATH with the login-shell value, the code now merges login-shell (or macOS launchctl) entries with inherited entries, preserving extra paths while keeping login-shell precedence.

Shell probing now tries multiple candidates (env SHELL → detected user shell → platform default) and logs per-shell failures rather than silently swallowing errors. Desktop hydration also pulls through additional variables (HOMEBREW_*, XDG_*) when missing, with new/updated tests covering candidate selection, PATH merge behavior, and the launchctl fallback.

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

Note

Improve shell PATH hydration with multi-candidate fallback and launchctl support

• Replaces single-shell resolution with listLoginShellCandidates in packages/shared/src/shell.ts, iterating over env.SHELL, a userShell, and a platform fallback in order without duplicates.
• Adds mergePathEntries to combine login-shell (or launchctl) PATH with inherited PATH, preserving unique entries from both sources with correct platform delimiters.
• Adds readPathFromLaunchctl as a macOS fallback when all shell candidates fail to return a PATH.
• Expands hydration in syncShellEnvironment and fixPath to include HOMEBREW_PREFIX, HOMEBREW_CELLAR, HOMEBREW_REPOSITORY, XDG_CONFIG_HOME, and XDG_DATA_HOME when missing.
• Per-candidate shell probe failures are now logged via logWarning instead of silently swallowed.
• Behavioral Change: PATH is now a merge of login-shell and inherited entries rather than a full replacement, so inherited extras are retained.

^{Macroscope summarized 99b6d62.}

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

Bugbot Autofix prepared fixes for all 3 issues found in the latest run.

• ✅ Fixed: Unnecessary synchronous subprocess spawned on macOS every time
  • Deferred the readPathFromLaunchctl() call by adding a !shellEnvironment.PATH / !shellPath guard so the synchronous subprocess is only spawned when the login shell did not provide a PATH.
• ✅ Fixed: resolveLoginShell has no production callers after refactor
  • Removed the dead resolveLoginShell function from shell.ts and its corresponding import and test from shell.test.ts.
• ✅ Fixed: Outer catch discards error details unlike server counterpart
  • Changed the bare catch { in syncShellEnvironment.ts to catch (error) and passed the error to logWarning to match the os-jank.ts pattern.

Or push these changes by commenting:

@cursor push 526ff40ceb

Preview (526ff40ceb)

diff --git a/apps/desktop/src/syncShellEnvironment.ts b/apps/desktop/src/syncShellEnvironment.ts
--- a/apps/desktop/src/syncShellEnvironment.ts
+++ b/apps/desktop/src/syncShellEnvironment.ts
@@ -50,7 +50,9 @@
     }
 
     const launchctlPath =
-      platform === "darwin" ? (options.readLaunchctlPath ?? readPathFromLaunchctl)() : undefined;
+      platform === "darwin" && !shellEnvironment.PATH
+        ? (options.readLaunchctlPath ?? readPathFromLaunchctl)()
+        : undefined;
     const mergedPath = mergePathEntries(shellEnvironment.PATH ?? launchctlPath, env.PATH, platform);
     if (mergedPath) {
       env.PATH = mergedPath;
@@ -71,7 +73,7 @@
         env[name] = shellEnvironment[name];
       }
     }
-  } catch {
-    logWarning("Failed to synchronize the desktop shell environment.");
+  } catch (error) {
+    logWarning("Failed to synchronize the desktop shell environment.", error);
   }
 }

diff --git a/apps/server/src/os-jank.ts b/apps/server/src/os-jank.ts
--- a/apps/server/src/os-jank.ts
+++ b/apps/server/src/os-jank.ts
@@ -43,7 +43,9 @@
     }
 
     const launchctlPath =
-      platform === "darwin" ? (options.readLaunchctlPath ?? readPathFromLaunchctl)() : undefined;
+      platform === "darwin" && !shellPath
+        ? (options.readLaunchctlPath ?? readPathFromLaunchctl)()
+        : undefined;
     const mergedPath = mergePathEntries(shellPath ?? launchctlPath, env.PATH, platform);
     if (mergedPath) {
       env.PATH = mergedPath;

diff --git a/packages/shared/src/shell.test.ts b/packages/shared/src/shell.test.ts
--- a/packages/shared/src/shell.test.ts
+++ b/packages/shared/src/shell.test.ts
@@ -7,7 +7,6 @@
   readEnvironmentFromLoginShell,
   readPathFromLaunchctl,
   readPathFromLoginShell,
-  resolveLoginShell,
 } from "./shell";
 
 describe("extractPathFromShellOutput", () => {
@@ -176,14 +175,6 @@
   });
 });
 
-describe("resolveLoginShell", () => {
-  it("returns the first available login shell candidate", () => {
-    expect(resolveLoginShell("darwin", undefined, "/opt/homebrew/bin/fish")).toBe(
-      "/opt/homebrew/bin/fish",
-    );
-  });
-});
-
 describe("mergePathEntries", () => {
   it("prefers login-shell PATH entries and keeps inherited extras", () => {
     expect(

diff --git a/packages/shared/src/shell.ts b/packages/shared/src/shell.ts
--- a/packages/shared/src/shell.ts
+++ b/packages/shared/src/shell.ts
@@ -45,14 +45,6 @@
   return candidates;
 }
 
-export function resolveLoginShell(
-  platform: NodeJS.Platform,
-  shell: string | undefined,
-  userShell = readUserLoginShell(),
-): string | undefined {
-  return listLoginShellCandidates(platform, shell, userShell)[0];
-}
-
 export function extractPathFromShellOutput(output: string): string | null {
   const startIndex = output.indexOf(PATH_CAPTURE_START);
   if (startIndex === -1) return null;

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 0d649e0. Configure here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR changes runtime behavior for PATH hydration by introducing new shell candidate selection logic, PATH merging (instead of replacement), and launchctl fallback. While well-tested, these changes affect how the application discovers executables and should be reviewed by someone familiar with the shell environment handling.

^{You can customize Macroscope's approvability policy. Learn more.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 10d53845-30e2-4cde-b9fd-2ce0a69e8573

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch t3code/brew-provider-detection

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[juliusmarminge]

@cursor push 526ff40