fix(sandbox): enrich PATH before Lima detection so packaged macOS app finds limactl

In the packaged macOS app, GUI processes inherit a stripped launchd PATH
(/usr/bin:/bin:/usr/sbin:/sbin) that excludes /opt/homebrew/bin and
/usr/local/bin, where Homebrew installs `limactl`. The sandbox/Lima detection
(`LimaBridge.checkLimaStatus` -> `which limactl`) runs at startup and from the
`sandbox.checkLima` IPC, but `enrichProcessPathForBuild()` only ran lazily
before the first `createCodingTools()` call. As a result `which limactl` failed
and the sandbox was reported as unavailable ("Lima not installed") even when
Lima was installed via `brew install lima`.

Export `enrichProcessPathForBuild()` and await it once at the top of the
`app.whenReady()` handler, before the sandbox bootstrap and any IPC can run.
The function is idempotent (guarded by `pathEnriched`), so the existing call
before `createCodingTools()` becomes a no-op. Dev mode and the Windows
registry-based PATH restore are unaffected.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: craigamcw

src/main/claude/agent-runner.ts

@@ -295,11 +295,14 @@ function resolveBundledToolsBinDir(): string | null {
  * 3. Deduplicates all entries
  * 4. Writes the result back to `process.env.PATH`
  *
- * Called once before the first `createCodingTools()` — subsequent calls are no-ops.
+ * Idempotent: enriches once and caches the result, so it is safe to call from
+ * multiple entry points. Call at app startup (before the sandbox bootstrap /
+ * Lima detection) and before the first `createCodingTools()` — subsequent calls
+ * are no-ops.
  */
 let pathEnriched = false;
 
-async function enrichProcessPathForBuild(): Promise<void> {
+export async function enrichProcessPathForBuild(): Promise<void> {
   if (pathEnriched) return;
   pathEnriched = true;
 

src/main/index.ts

@@ -41,6 +41,7 @@ import { SandboxSync } from './sandbox/sandbox-sync';
 import { WSLBridge } from './sandbox/wsl-bridge';
 import { LimaBridge } from './sandbox/lima-bridge';
 import { getSandboxBootstrap } from './sandbox/sandbox-bootstrap';
+import { enrichProcessPathForBuild } from './claude/agent-runner';
 import type { MCPServerConfig } from './mcp/mcp-manager';
 import type {
   ClientEvent,
@@ -804,6 +805,14 @@ app
       process.exit(0);
     }
 
+    // Enrich PATH before anything else so Homebrew-installed CLIs (notably
+    // `limactl`) are discoverable by the sandbox bootstrap and the
+    // `sandbox.checkLima` IPC. In the packaged macOS app, GUI processes inherit
+    // a stripped launchd PATH that excludes /opt/homebrew/bin and
+    // /usr/local/bin, which otherwise makes `which limactl` fail and reports
+    // the sandbox as unavailable even when Lima is installed.
+    await enrichProcessPathForBuild();
+
     // Apply dev logs setting from config
     const enableDevLogs = configStore.get('enableDevLogs');
     setDevLogsEnabled(enableDevLogs);

tests/startup-path-enrichment.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+const read = (rel: string): string => readFileSync(path.resolve(process.cwd(), rel), 'utf8');
+
+/**
+ * Regression guard for the macOS sandbox-detection bug.
+ *
+ * In the packaged macOS app, GUI processes inherit a stripped launchd PATH that
+ * excludes /opt/homebrew/bin and /usr/local/bin. The sandbox/Lima detection
+ * (`which limactl`) runs at startup and from the `sandbox.checkLima` IPC, so it
+ * must run AFTER the login-shell PATH has been restored — otherwise Lima is
+ * reported as unavailable even when it is installed. The PATH enrichment used to
+ * run only before the first `createCodingTools()` call (an agent task), which is
+ * too late for the sandbox detection.
+ */
+describe('PATH enrichment is wired into app startup, before sandbox detection', () => {
+  const agentRunner = read('src/main/claude/agent-runner.ts');
+  const indexTs = read('src/main/index.ts');
+
+  it('exports enrichProcessPathForBuild so the startup path can reuse it', () => {
+    expect(agentRunner).toMatch(/export\s+async\s+function\s+enrichProcessPathForBuild/);
+  });
+
+  it('keeps the enrichment idempotent so repeated calls are safe', () => {
+    expect(agentRunner).toContain('let pathEnriched = false;');
+    expect(agentRunner).toContain('if (pathEnriched) return;');
+  });
+
+  it('imports the enrichment into the main entrypoint', () => {
+    expect(indexTs).toMatch(
+      /import\s*\{\s*enrichProcessPathForBuild\s*\}\s*from\s*['"]\.\/claude\/agent-runner['"]/
+    );
+  });
+
+  it('awaits the enrichment during the whenReady startup sequence', () => {
+    const readyIdx = indexTs.indexOf('.whenReady()');
+    const enrichIdx = indexTs.indexOf('await enrichProcessPathForBuild()');
+    expect(readyIdx).toBeGreaterThan(-1);
+    expect(enrichIdx).toBeGreaterThan(-1);
+    // The enrichment must be invoked from the startup sequence, not only from
+    // the lazy agent-task path, so it precedes any Lima detection.
+    expect(enrichIdx).toBeGreaterThan(readyIdx);
+  });
+});