fix(file_tools): resolve tilde using profile home for file operations (#48552)

File tools (read_file, write_file, patch, list_directory, etc.) used
os.path.expanduser() which reads the gateway process HOME env var.
In Docker/systemd/s6 deployments where the gateway HOME differs from
interactive sessions, tilde expanded to the wrong directory.

Add _expand_tilde() helper that delegates to get_subprocess_home() when
available, falling back to os.path.expanduser(). Replace all 9
expanduser() call sites in file_tools.py with _expand_tilde().

tests/tools/test_file_tools_tilde_profile.py

@@ -0,0 +1,109 @@
+"""Regression tests for profile-aware tilde expansion in file tools.
+
+The bug (#48552): in-process file tools (write_file, read_file, patch,
+search_files) resolved ``~`` via ``os.path.expanduser()``, which reads the
+gateway process's ``HOME``.  In profile mode (Docker, systemd, s6) the gateway
+``HOME`` differs from the profile ``HOME`` that interactive sessions use, so
+``~`` expanded to the wrong directory and file operations failed with
+"no such file or directory".
+
+The fix adds ``_expand_tilde()`` which delegates to
+``hermes_constants.get_subprocess_home()`` — the same policy the terminal tool
+uses for subprocess environments.
+
+See: https://github.com/NousResearch/hermes-agent/issues/48552
+"""
+
+import os
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+import tools.file_tools as ft
+
+
+# ---------------------------------------------------------------------------
+# _expand_tilde() unit tests
+# ---------------------------------------------------------------------------
+
+class TestExpandTilde:
+    """Verify the _expand_tilde() helper resolves ~ to the profile home."""
+
+    def test_tilde_expands_to_profile_home(self):
+        """When get_subprocess_home returns a value, ~/path uses it."""
+        with patch("hermes_constants.get_subprocess_home", return_value="/opt/data/profiles/coder/home"):
+            result = ft._expand_tilde("~/scratch/file.txt")
+        assert result == "/opt/data/profiles/coder/home/scratch/file.txt"
+
+    def test_bare_tilde_expands_to_profile_home(self):
+        """Bare ~ expands to the profile home."""
+        with patch("hermes_constants.get_subprocess_home", return_value="/opt/data/profiles/coder/home"):
+            result = ft._expand_tilde("~")
+        assert result == "/opt/data/profiles/coder/home"
+
+    def test_falls_back_when_no_profile_home(self):
+        """When get_subprocess_home returns None, use os.path.expanduser."""
+        with patch("hermes_constants.get_subprocess_home", return_value=None):
+            result = ft._expand_tilde("~/Documents")
+        assert result == os.path.expanduser("~/Documents")
+
+    def test_other_user_tilde_not_overridden(self):
+        """~user/path must NOT use the profile home — it's a different user."""
+        with patch("hermes_constants.get_subprocess_home", return_value="/opt/data/profiles/coder/home"):
+            result = ft._expand_tilde("~root/file.txt")
+        # Should use os.path.expanduser, not the profile home
+        assert "/opt/data/profiles/coder/home" not in result
+
+    def test_no_tilde_unchanged(self):
+        """Paths without ~ are returned unchanged (modulo expanduser)."""
+        with patch("hermes_constants.get_subprocess_home", return_value="/opt/data/profiles/coder/home"):
+            result = ft._expand_tilde("/etc/passwd")
+        assert result == "/etc/passwd"
+
+    def test_empty_path_unchanged(self):
+        """Empty string returns empty."""
+        with patch("hermes_constants.get_subprocess_home", return_value="/opt/data/profiles/coder/home"):
+            assert ft._expand_tilde("") == ""
+
+
+# ---------------------------------------------------------------------------
+# Integration: _resolve_path_for_task uses profile home
+# ---------------------------------------------------------------------------
+
+class TestResolvePathUsesProfileHome:
+    """Verify _resolve_path_for_task resolves ~ to the profile home."""
+
+    def test_relative_tilde_resolves_to_profile_home(self, tmp_path, monkeypatch):
+        """A ~/path argument resolves under the profile home, not process HOME."""
+        profile_home = tmp_path / "profile_home"
+        profile_home.mkdir()
+        process_home = tmp_path / "process_home"
+        process_home.mkdir()
+
+        monkeypatch.setenv("HOME", str(process_home))
+        monkeypatch.setattr(ft, "_get_live_tracking_cwd", lambda task_id="default": None)
+
+        with patch("hermes_constants.get_subprocess_home", return_value=str(profile_home)):
+            resolved = ft._resolve_path_for_task("~/test_file.txt", task_id="test")
+
+        assert str(resolved).startswith(str(profile_home))
+        assert "process_home" not in str(resolved)
+
+    def test_absolute_tilde_in_workspace_root(self, tmp_path, monkeypatch):
+        """A workspace root specified with ~ resolves to profile home."""
+        profile_home = tmp_path / "profile_home"
+        profile_home.mkdir()
+        process_home = tmp_path / "process_home"
+        process_home.mkdir()
+
+        monkeypatch.setenv("HOME", str(process_home))
+        monkeypatch.setattr(ft, "_get_live_tracking_cwd", lambda task_id="default": None)
+
+        with patch("hermes_constants.get_subprocess_home", return_value=str(profile_home)):
+            # _resolve_base_dir uses the workspace root from config; if it contains ~,
+            # it should resolve to profile home
+            resolved = ft._resolve_path_for_task("~/data/config.json", task_id="test")
+
+        assert str(profile_home) in str(resolved)
+        assert str(process_home) not in str(resolved)

tools/file_tools.py

@@ -23,6 +23,29 @@ logger = logging.getLogger(__name__)
 
 _EXPECTED_WRITE_ERRNOS = {errno.EACCES, errno.EPERM, errno.EROFS}
 
+
+def _expand_tilde(path: str) -> str:
+    """Expand ``~`` using the effective profile home when available.
+
+    In-process file tools share the gateway process's HOME, which may differ
+    from the profile-specific HOME that interactive CLI sessions use.  This
+    mirrors ``hermes_constants.get_subprocess_home()`` so that ``~`` resolves
+    consistently regardless of whether the tool runs interactively or inside a
+    gateway-driven cron job (#48552).
+    """
+    if not path or "~" not in path:
+        return path
+    try:
+        from hermes_constants import get_subprocess_home
+
+        home = get_subprocess_home()
+    except Exception:
+        home = None
+    if home and (path == "~" or path.startswith("~/")):
+        return home if path == "~" else os.path.join(home, path[2:])
+    return os.path.expanduser(path)
+
+
 # ---------------------------------------------------------------------------
 # Read-size guard: cap the character count returned to the model.
 # We're model-agnostic so we can't count tokens; characters are a safe proxy.
@@ -107,7 +130,7 @@ def _sentinel_free_abs_cwd(raw: str | None) -> str | None:
     raw = str(raw or "").strip()
     if raw.lower() in _TERMINAL_CWD_SENTINELS:
         return None
-    expanded = os.path.expanduser(raw)
+    expanded = _expand_tilde(raw)
     if not os.path.isabs(expanded):
         return None
     return expanded
@@ -222,7 +245,7 @@ def _resolve_base_dir(task_id: str = "default") -> Path:
     """
     root = _authoritative_workspace_root(task_id)
     if root:
-        base = Path(root).expanduser()
+        base = Path(_expand_tilde(root))
     else:
         base = Path(os.getcwd())
     if not base.is_absolute():
@@ -239,7 +262,7 @@ def _resolve_path_for_task(filepath: str, task_id: str = "default") -> Path:
     See :func:`_resolve_base_dir` for how the base is chosen. Absolute input
     paths are returned resolved-but-unanchored.
     """
-    p = Path(filepath).expanduser()
+    p = Path(_expand_tilde(filepath))
     if p.is_absolute():
         return p.resolve()
     return (_resolve_base_dir(task_id) / p).resolve()
@@ -261,12 +284,12 @@ def _path_resolution_warning(filepath: str, resolved: Path, task_id: str = "defa
     (no ``cd`` run yet) is warned on the very first write.
     """
     try:
-        if Path(filepath).expanduser().is_absolute():
+        if Path(_expand_tilde(filepath)).is_absolute():
             return None
         workspace_root = _authoritative_workspace_root(task_id)
         if not workspace_root:
             return None  # No authoritative workspace root to compare against.
-        root = Path(workspace_root).expanduser().resolve()
+        root = Path(_expand_tilde(workspace_root)).resolve()
         # Is `resolved` inside `root`?
         try:
             resolved.relative_to(root)
@@ -285,7 +308,7 @@ def _path_resolution_warning(filepath: str, resolved: Path, task_id: str = "defa
 
 def _is_blocked_device_path(path: str) -> bool:
     """Return True for concrete device/fd paths that can hang reads."""
-    normalized = os.path.normpath(os.path.expanduser(path))
+    normalized = os.path.normpath(_expand_tilde(path))
     if normalized in _BLOCKED_DEVICE_PATHS:
         return True
     # /proc/self/fd/0-2 and /proc/<pid>/fd/0-2 are Linux aliases for stdio
@@ -309,7 +332,7 @@ def _is_blocked_device(filepath: str, base_dir: str | Path | None = None) -> boo
     they resolve to terminal-specific paths. Then check each symlink hop before
     the final resolved path so aliases to devices cannot bypass the guard.
     """
-    expanded = os.path.expanduser(filepath)
+    expanded = _expand_tilde(filepath)
     if base_dir is not None and not os.path.isabs(expanded):
         expanded = os.path.join(os.fspath(base_dir), expanded)
     normalized = os.path.normpath(expanded)
@@ -365,7 +388,7 @@ def _get_hermes_config_resolved() -> str | None:
         _hermes_config_resolved = str(get_config_path().resolve())
     except Exception:
         try:
-            _hermes_config_resolved = str(Path("~/.hermes/config.yaml").expanduser().resolve())
+            _hermes_config_resolved = str(Path(_expand_tilde("~/.hermes/config.yaml")).resolve())
         except Exception:
             _hermes_config_resolved = None
     return _hermes_config_resolved
@@ -377,7 +400,7 @@ def _check_sensitive_path(filepath: str, task_id: str = "default") -> str | None
         resolved = str(_resolve_path_for_task(filepath, task_id))
     except (OSError, ValueError):
         resolved = filepath
-    normalized = os.path.normpath(os.path.expanduser(filepath))
+    normalized = os.path.normpath(_expand_tilde(filepath))
     _err = (
         f"Refusing to write to sensitive system path: {filepath}\n"
         "Use the terminal tool with sudo if you need to modify system files."