feat(cli): locate claude across native and homebrew installs

shell_env::locate_claude falls back from the login-shell PATH to the
well-known install locations (~/.local/bin, ~/.claude/local,
/opt/homebrew/bin, /usr/local/bin, exec bit required), so a GUI launch
with an unresolved shell env still finds a standard install. The
headless indexer now resolves through it.

Author: Swofty-Developments

crates/forge-index/src/headless.rs

@@ -20,13 +20,14 @@ const STDERR_SNIPPET_LEN: usize = 500;
 /// extracted result text. The binary resolves via the login-shell PATH so
 /// desktop-launched apps find the right install.
 pub(crate) async fn run_headless_claude(repo_root: &Path, prompt: &str) -> Result<String> {
-    // `which` checks the login-shell PATH first, then the process PATH; a `None`
-    // here is definitive — there is no `claude` to fall back to. Name it rather
-    // than spawning a bare "claude" that would fail with a confusing ENOENT.
-    let claude = forge_session::shell_env::which("claude").ok_or_else(|| {
+    // `locate_claude` checks the login-shell PATH, then the well-known install
+    // locations (native installer, legacy local, Homebrew); a `None` here is
+    // definitive — there is no `claude` to fall back to. Name it rather than
+    // spawning a bare "claude" that would fail with a confusing ENOENT.
+    let claude = forge_session::shell_env::locate_claude().ok_or_else(|| {
         Error::Indexer(
-            "Claude CLI not found on PATH — install Claude Code (https://claude.com/claude-code) \
-             and ensure `claude` is on your login shell PATH"
+            "Claude Code CLI not found — install it (`brew install --cask claude-code` or \
+             `curl -fsSL https://claude.ai/install.sh | bash`) and reopen the app"
                 .into(),
         )
     })?;

crates/forge-session/src/shell_env.rs

@@ -67,6 +67,47 @@ pub fn which(cmd: &str) -> Option<PathBuf> {
     None
 }
 
+/// Locate the Claude Code CLI: the resolved PATH first, then the well-known
+/// install locations PATH misses when the login-shell probe fails or the
+/// profile doesn't export them — the native installer (`~/.local/bin`), the
+/// legacy local install (`~/.claude/local`), and Homebrew (Apple-silicon and
+/// Intel prefixes).
+pub fn locate_claude() -> Option<PathBuf> {
+    if let Some(found) = which("claude") {
+        return Some(found);
+    }
+    well_known_claude_paths().into_iter().find(|p| is_executable(p))
+}
+
+/// Candidate `claude` install locations outside PATH, best-first.
+fn well_known_claude_paths() -> Vec<PathBuf> {
+    let mut candidates = Vec::new();
+    let home = std::env::var_os("HOME").or_else(|| std::env::var_os("USERPROFILE"));
+    if let Some(home) = home {
+        let home = PathBuf::from(home);
+        candidates.push(home.join(".local/bin/claude"));
+        candidates.push(home.join(".claude/local/claude"));
+    }
+    candidates.push(PathBuf::from("/opt/homebrew/bin/claude"));
+    candidates.push(PathBuf::from("/usr/local/bin/claude"));
+    candidates
+}
+
+/// A regular file with an exec bit (symlinks followed, so Homebrew's Cellar
+/// links qualify). Non-unix: existence is the best available signal.
+#[cfg(unix)]
+fn is_executable(path: &std::path::Path) -> bool {
+    use std::os::unix::fs::PermissionsExt;
+    path.metadata()
+        .map(|m| m.is_file() && m.permissions().mode() & 0o111 != 0)
+        .unwrap_or(false)
+}
+
+#[cfg(not(unix))]
+fn is_executable(path: &std::path::Path) -> bool {
+    path.is_file()
+}
+
 /// Resolve the user's login-shell environment by running:
 ///   `$SHELL -l -i -c 'env -0'`  (preferred, NUL-separated)
 ///   `$SHELL -l -c 'env'`        (fallback)
@@ -141,4 +182,29 @@ mod tests {
     fn which_finds_sh() {
         assert!(which("sh").is_some());
     }
+
+    #[cfg(unix)]
+    #[test]
+    fn executable_probe_requires_exec_bit() {
+        use std::os::unix::fs::PermissionsExt;
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let plain = tmp.path().join("claude");
+        std::fs::write(&plain, "#!/bin/sh\n").expect("write");
+        std::fs::set_permissions(&plain, std::fs::Permissions::from_mode(0o644)).expect("chmod");
+        assert!(!is_executable(&plain), "no exec bit");
+        std::fs::set_permissions(&plain, std::fs::Permissions::from_mode(0o755)).expect("chmod");
+        assert!(is_executable(&plain), "exec bit set");
+        assert!(!is_executable(&tmp.path().join("missing")), "missing file");
+    }
+
+    #[test]
+    fn well_known_paths_cover_native_and_homebrew() {
+        let paths = well_known_claude_paths();
+        let rendered: Vec<String> =
+            paths.iter().map(|p| p.to_string_lossy().into_owned()).collect();
+        assert!(rendered.iter().any(|p| p.ends_with(".local/bin/claude")), "native installer");
+        assert!(rendered.iter().any(|p| p.ends_with(".claude/local/claude")), "legacy local");
+        assert!(rendered.contains(&"/opt/homebrew/bin/claude".to_string()), "brew arm64");
+        assert!(rendered.contains(&"/usr/local/bin/claude".to_string()), "brew intel");
+    }
 }