feat(helexa-acp): expand ~ / $HOME and fall back to local fs on ACP read errors

Two related polish fixes for daily use:

- New `path_util` module expands `~`, `~/…`, `$HOME`, and `$HOME/…`
  prefixes in every tool that takes a path (read_file, write_file,
  edit_file, list_dir, bash cwd). The expansion is also applied to
  the plan-mode write gate so `~/.local/share/helexa-acp/plans/…`
  comparisons behave correctly regardless of which form the model
  emits.
- `read_file` now falls back to `std::fs::read_to_string` when ACP's
  `fs/read_text_file` errors out. Zed's workspace-scoped read was
  the source of "model can't see ~/git/architecture/generic.md"
  when the session cwd is a different project; the fallback lets
  the agent pull in shared material that lives outside the active
  workspace, the same way `list_dir` already does via local
  `std::fs::read_dir`. Local fallback honours line/limit args.

The fallback also produces a combined error message when both ACP
and local-fs reads fail, so the model sees what actually broke
rather than just the ACP-side error.

14 new unit tests cover path_util's prefix matrix, fallback
success/failure paths, and the line/limit slicing in fallback.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

crates/helexa-acp/src/path_util.rs

@@ -0,0 +1,184 @@
+//! Path expansion shared across every tool that takes a path.
+//!
+//! Models often emit shell-style paths like `~/git/repo/file.rs` or
+//! `$HOME/notes.md`. ACP's `fs/read_text_file` and friends — and our
+//! own local `std::fs` reads — both want a real absolute path; the
+//! `~` / `$HOME` forms reach them as literal strings and the open
+//! fails. The tool schemas already document "absolute path" but in
+//! practice the model slips up often enough that handling it
+//! server-side is the difference between "works" and "the agent is
+//! brittle".
+//!
+//! Scope is deliberately small:
+//!
+//! - `~` and `~/` (current user only — `~user` lookups would require
+//!   pulling in passwd parsing).
+//! - `$HOME` and `$HOME/`.
+//!
+//! Any other shell variable (`$PWD`, `${HOME}`, …) passes through
+//! unchanged. The shell already expands them inside `bash` tool
+//! commands; for the file-tool argument fields, we deliberately
+//! limit the set so the behaviour is predictable.
+//!
+//! Falls back to the input path verbatim when `HOME` is unset
+//! (stripped-down container env). That preserves the "no surprise
+//! mutations" rule — never invent a path the caller didn't ask for.
+
+use std::path::{Path, PathBuf};
+
+/// Expand `~`, `~/`, `$HOME`, and `$HOME/` prefixes against the
+/// current user's home directory. All other inputs pass through
+/// unchanged.
+///
+/// Returns the input verbatim if `HOME` isn't set in the env.
+pub fn expand_path(input: &Path) -> PathBuf {
+    let Some(s) = input.to_str() else {
+        return input.to_path_buf();
+    };
+    let Ok(home) = std::env::var("HOME") else {
+        return input.to_path_buf();
+    };
+    let home = PathBuf::from(home);
+    if s == "~" || s == "$HOME" {
+        return home;
+    }
+    if let Some(rest) = s.strip_prefix("~/") {
+        return home.join(rest);
+    }
+    if let Some(rest) = s.strip_prefix("$HOME/") {
+        return home.join(rest);
+    }
+    input.to_path_buf()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Set HOME for the duration of the test. Tests using this run
+    /// serially under one mutex because env mutation isn't
+    /// thread-safe — `cargo test` parallel workers would race
+    /// without it.
+    fn with_home<F: FnOnce()>(home: &str, body: F) {
+        use std::sync::Mutex;
+        static LOCK: Mutex<()> = Mutex::new(());
+        let _g = LOCK.lock().unwrap();
+        let prior = std::env::var("HOME").ok();
+        // SAFETY: tests touch process-global env. The mutex
+        // serialises access; sub-threads in other test modules
+        // touching HOME aren't expected (none in this crate).
+        unsafe {
+            std::env::set_var("HOME", home);
+        }
+        body();
+        unsafe {
+            match prior {
+                Some(p) => std::env::set_var("HOME", p),
+                None => std::env::remove_var("HOME"),
+            }
+        }
+    }
+
+    #[test]
+    fn expands_tilde_slash() {
+        with_home("/home/me", || {
+            assert_eq!(
+                expand_path(Path::new("~/git/repo/file.rs")),
+                PathBuf::from("/home/me/git/repo/file.rs")
+            );
+        });
+    }
+
+    #[test]
+    fn expands_bare_tilde() {
+        with_home("/home/me", || {
+            assert_eq!(expand_path(Path::new("~")), PathBuf::from("/home/me"));
+        });
+    }
+
+    #[test]
+    fn expands_dollar_home_slash() {
+        with_home("/home/me", || {
+            assert_eq!(
+                expand_path(Path::new("$HOME/notes.md")),
+                PathBuf::from("/home/me/notes.md")
+            );
+        });
+    }
+
+    #[test]
+    fn expands_bare_dollar_home() {
+        with_home("/home/me", || {
+            assert_eq!(expand_path(Path::new("$HOME")), PathBuf::from("/home/me"));
+        });
+    }
+
+    #[test]
+    fn absolute_path_passes_through() {
+        with_home("/home/me", || {
+            assert_eq!(
+                expand_path(Path::new("/etc/hostname")),
+                PathBuf::from("/etc/hostname")
+            );
+        });
+    }
+
+    #[test]
+    fn relative_path_passes_through() {
+        with_home("/home/me", || {
+            assert_eq!(
+                expand_path(Path::new("src/main.rs")),
+                PathBuf::from("src/main.rs")
+            );
+        });
+    }
+
+    #[test]
+    fn tilde_user_form_not_expanded() {
+        // ~other is shell sugar for /home/other and would require
+        // passwd parsing to resolve. Out of scope — pass it
+        // through and let the open fail with a clear error.
+        with_home("/home/me", || {
+            assert_eq!(
+                expand_path(Path::new("~other/x")),
+                PathBuf::from("~other/x")
+            );
+        });
+    }
+
+    #[test]
+    fn no_home_env_passes_through() {
+        // Lock + clear HOME for this one.
+        use std::sync::Mutex;
+        static LOCK: Mutex<()> = Mutex::new(());
+        let _g = LOCK.lock().unwrap();
+        let prior = std::env::var("HOME").ok();
+        // SAFETY: serialised by LOCK above.
+        unsafe {
+            std::env::remove_var("HOME");
+        }
+        assert_eq!(
+            expand_path(Path::new("~/git/repo")),
+            PathBuf::from("~/git/repo")
+        );
+        unsafe {
+            if let Some(p) = prior {
+                std::env::set_var("HOME", p);
+            }
+        }
+    }
+
+    #[test]
+    fn dollar_other_var_not_expanded() {
+        with_home("/home/me", || {
+            assert_eq!(
+                expand_path(Path::new("$PWD/file")),
+                PathBuf::from("$PWD/file")
+            );
+            assert_eq!(
+                expand_path(Path::new("${HOME}/file")),
+                PathBuf::from("${HOME}/file")
+            );
+        });
+    }
+}