fix(desktop): resolve shell environment for macOS GUI apps

apps/desktop/package.json

@@ -114,6 +114,7 @@
 		"rehype-sanitize": "^6.0.0",
 		"remark-gfm": "^4.0.1",
 		"semver": "^7.7.3",
+		"shell-env": "^4.0.1",
 		"shell-quote": "^1.8.3",
 		"simple-git": "^3.30.0",
 		"strip-ansi": "^7.1.2",

apps/desktop/src/main/index.ts

@@ -13,6 +13,7 @@ import { initAppState } from "./lib/app-state";
 import { authService, parseAuthDeepLink } from "./lib/auth";
 import { setupAutoUpdater } from "./lib/auto-updater";
 import { localDb } from "./lib/local-db";
+import { ensureShellEnvVars } from "./lib/shell-env";
 import { terminalManager } from "./lib/terminal";
 import { MainWindow } from "./windows/main";
 
@@ -207,6 +208,10 @@ if (!gotTheLock) {
 		await initAppState();
 		await authService.initialize();
 
+		// Resolve shell environment before setting up agent hooks
+		// This ensures ZDOTDIR and PATH are available for terminal initialization
+		await ensureShellEnvVars();
+
 		try {
 			setupAgentHooks();
 		} catch (error) {

apps/desktop/src/main/lib/shell-env.test.ts

@@ -0,0 +1,80 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mergePathFromShell } from "./shell-env";
+
+describe("shell-env", () => {
+	describe("mergePathFromShell", () => {
+		let originalPath: string | undefined;
+
+		beforeEach(() => {
+			originalPath = process.env.PATH;
+		});
+
+		afterEach(() => {
+			process.env.PATH = originalPath;
+		});
+
+		it("should prepend new paths from shell", () => {
+			process.env.PATH = "/usr/bin:/bin";
+			const result = mergePathFromShell("/opt/homebrew/bin:/usr/bin:/bin");
+
+			expect(result).toBe(true);
+			expect(process.env.PATH).toBe("/opt/homebrew/bin:/usr/bin:/bin");
+		});
+
+		it("should return false when no new paths to add", () => {
+			process.env.PATH = "/usr/bin:/bin:/opt/homebrew/bin";
+			const result = mergePathFromShell("/usr/bin:/bin");
+
+			expect(result).toBe(false);
+			expect(process.env.PATH).toBe("/usr/bin:/bin:/opt/homebrew/bin");
+		});
+
+		it("should preserve existing paths", () => {
+			process.env.PATH = "/electron/path:/usr/bin";
+			const result = mergePathFromShell("/new/path:/usr/bin");
+
+			expect(result).toBe(true);
+			expect(process.env.PATH).toBe("/new/path:/electron/path:/usr/bin");
+		});
+
+		it("should handle empty current PATH", () => {
+			process.env.PATH = "";
+			const result = mergePathFromShell("/usr/bin:/bin");
+
+			expect(result).toBe(true);
+			expect(process.env.PATH).toBe("/usr/bin:/bin");
+		});
+
+		it("should handle empty shell PATH", () => {
+			process.env.PATH = "/usr/bin";
+			const result = mergePathFromShell("");
+
+			expect(result).toBe(false);
+			expect(process.env.PATH).toBe("/usr/bin");
+		});
+
+		it("should deduplicate paths", () => {
+			process.env.PATH = "/usr/bin:/bin";
+			const result = mergePathFromShell("/new/path:/usr/bin:/another:/bin");
+
+			expect(result).toBe(true);
+			expect(process.env.PATH).toBe("/new/path:/another:/usr/bin:/bin");
+		});
+
+		it("should filter empty path segments", () => {
+			process.env.PATH = "/usr/bin::/bin";
+			const result = mergePathFromShell("/new/path:::/usr/bin");
+
+			expect(result).toBe(true);
+			expect(process.env.PATH).toBe("/new/path:/usr/bin::/bin");
+		});
+
+		it("should maintain shell path order for new entries", () => {
+			process.env.PATH = "/existing";
+			const result = mergePathFromShell("/first:/second:/third");
+
+			expect(result).toBe(true);
+			expect(process.env.PATH).toBe("/first:/second:/third:/existing");
+		});
+	});
+});

apps/desktop/src/main/lib/shell-env.ts

@@ -0,0 +1,65 @@
+import { shellEnv } from "shell-env";
+
+const SHELL_ENV_TIMEOUT_MS = 5000;
+
+function isLaunchedFromTerminal(): boolean {
+	return Boolean(process.stdout.isTTY || process.env.TERM_PROGRAM);
+}
+
+export function mergePathFromShell(shellPath: string): boolean {
+	const currentPath = process.env.PATH || "";
+	const currentPaths = new Set(currentPath.split(":").filter(Boolean));
+	const shellPaths = shellPath.split(":").filter(Boolean);
+	const newPaths = shellPaths.filter((p) => !currentPaths.has(p));
+
+	if (newPaths.length === 0) {
+		return false;
+	}
+
+	process.env.PATH = [...newPaths, currentPath].filter(Boolean).join(":");
+	return true;
+}
+
+/** Resolves shell environment for macOS GUI apps (which don't inherit shell env). */
+export async function ensureShellEnvVars(): Promise<void> {
+	if (process.platform === "win32") {
+		return;
+	}
+
+	if (isLaunchedFromTerminal()) {
+		console.log("[shell-env] Skipping - launched from terminal");
+		return;
+	}
+
+	try {
+		console.log("[shell-env] Resolving shell environment...");
+
+		const timeoutPromise = new Promise<never>((_, reject) => {
+			setTimeout(
+				() => reject(new Error("Shell environment resolution timed out")),
+				SHELL_ENV_TIMEOUT_MS,
+			);
+		});
+
+		const env = await Promise.race([shellEnv(), timeoutPromise]);
+
+		let resolved = false;
+
+		if (env.ZDOTDIR && !process.env.ZDOTDIR) {
+			process.env.ZDOTDIR = env.ZDOTDIR;
+			console.log("[shell-env] Resolved ZDOTDIR:", env.ZDOTDIR);
+			resolved = true;
+		}
+
+		if (env.PATH && mergePathFromShell(env.PATH)) {
+			console.log("[shell-env] Merged PATH from shell");
+			resolved = true;
+		}
+
+		if (!resolved) {
+			console.log("[shell-env] No additional env vars needed");
+		}
+	} catch (error) {
+		console.warn("[shell-env] Failed to resolve:", error);
+	}
+}