From d67cd58e7723601e6944b6cd1484f19a273ea610 Mon Sep 17 00:00:00 2001 From: Xinyu Du Date: Fri, 14 Aug 2026 03:28:14 +0800 Subject: [PATCH] fix(tools): recover repo-level junction lexical root via exact identity Second real-world topology reported and confirmed on native Windows 11: the repository itself is a cross-drive junction (D:\hermes\hermes-agent -> C:\...\hermes-agent) under a real HERMES_HOME directory. The editable import spelling resolves to the physical location, so _hermes_repo_root is physical while the launcher writes the lexical spelling into PYTHONPATH. The home-relative mapping cannot express a cross-drive link (commonpath raises on different drives), so the lexical repo root survives stripping; and with the repo alias missing, a lexical VIRTUAL_ENV (D:\hermes\hermes-agent\venv) also fails _validated_runtime_venv, so the venv site-packages survives too (uv-base gateway: both entries survive). Fix: after the existing home/profile-root mapping, try the single deterministic candidate / for every trusted home candidate (configured home, plus the profile root when the configured home is a profile path) and accept it only when strict resolve proves it is the exact physical repo root (fail-closed: missing paths, real directories that are not the known repo, and unrelated spellings are never aliased). This also re-enables the VIRTUAL_ENV validation for lexical venv spellings, so uv-base gateway site-packages cleanup follows the repo alias. Tests: repo-level junction positive + negative control (same-named real directory preserved), profile-home + repo-level junction combination, lexical VIRTUAL_ENV validation after recovery (root + site-packages stripped, user entries kept), and a no-provenance lookalike preserved. The execute_code composition test now compares composed paths with os.path.normcase so a Windows case-only spelling difference (resolve() vs abspath() casing) can never fail the composition contract. --- tests/tools/test_local_env_blocklist.py | 186 +++++++++++++++++++++++- tools/environments/local.py | 22 +++ 2 files changed, 201 insertions(+), 7 deletions(-) diff --git a/tests/tools/test_local_env_blocklist.py b/tests/tools/test_local_env_blocklist.py index 2e61c4ab66..cd5a9cfefa 100644 --- a/tests/tools/test_local_env_blocklist.py +++ b/tests/tools/test_local_env_blocklist.py @@ -814,21 +814,33 @@ class TestPythonpathSelectiveStrip: assert "PYTHONPATH" in captured["env"], \ "execute_code never reached Popen" parts = captured["env"]["PYTHONPATH"].split(os.pathsep) - assert parts[0] == captured["staging"], \ + # Windows path comparison is case-insensitive: the inherited entries + # and the re-added repo root can carry a different case than the + # resolve()/abspath()-derived spellings used in this test (e.g. a + # launcher-written lowercase PYTHONPATH). Normalize with + # os.path.normcase so a case-only difference never fails the + # composition contract (identity on POSIX). + norm_parts = [os.path.normcase(p) for p in parts] + norm_staging = os.path.normcase(captured["staging"]) + norm_root = os.path.normcase(hermes_root) + norm_venv = os.path.normcase(venv_sp) + norm_user_a = os.path.normcase(user_a) + norm_user_b = os.path.normcase(user_b) + assert norm_parts[0] == norm_staging, \ "staging tmpdir must be the first PYTHONPATH entry" - assert venv_sp not in parts, \ + assert norm_venv not in norm_parts, \ "inherited Hermes venv site-packages must be stripped" - assert user_a in parts and user_b in parts, \ + assert norm_user_a in norm_parts and norm_user_b in norm_parts, \ "user PYTHONPATH entries must survive" - assert parts.index(user_a) > parts.index(captured["staging"]), \ + assert norm_parts.index(norm_user_a) > norm_parts.index(norm_staging), \ "user entries must come after the staging tmpdir" if same_env: - assert parts.count(hermes_root) == 1, \ + assert norm_parts.count(norm_root) == 1, \ "repo root must be re-added exactly once for a same-env child" - assert parts.index(user_a) > parts.index(hermes_root), \ + assert norm_parts.index(norm_user_a) > norm_parts.index(norm_root), \ "user entries must come after the re-added repo root" else: - assert hermes_root not in parts, \ + assert norm_root not in norm_parts, \ "repo root must stay absent for an external-env child" def test_repo_root_stripped(self): @@ -974,6 +986,166 @@ class TestPythonpathSelectiveStrip: assert env["PYTHONPATH"].split(os.pathsep) == ["/home/user/my-lib"] + def test_repo_level_junction_recovers_lexical_alias(self, tmp_path, monkeypatch): + """The repo itself may be a junction under the configured root + (e.g. D:\\hermes\\hermes-agent -> C:\\...\\hermes-agent) while the + editable import spelling resolves to the physical location. The + alias builder must recover the lexical spelling via exact-identity + proof (strict resolve), not a name-based guess. + """ + import tools.environments.local as local + + physical_home = tmp_path / "physical-home" + physical_root = physical_home / "hermes-agent" + physical_root.mkdir(parents=True) + configured_home = tmp_path / "configured-home" + configured_home.mkdir() + # repo-level link: /hermes-agent -> physical repo + try: + _make_directory_link(configured_home / "hermes-agent", physical_root) + except OSError as exc: + pytest.skip(f"directory link unavailable on this host: {exc}") + + lexical_root = configured_home / "hermes-agent" + aliases = local._build_hermes_repo_root_aliases( + physical_root.resolve(), + physical_root, + configured_home, + ) + assert any(local._same_path(a, lexical_root) for a in aliases) + + monkeypatch.setattr(local, "_hermes_repo_root_aliases", aliases) + env = {"PYTHONPATH": os.pathsep.join([str(lexical_root), "/home/user/my-lib"])} + local._strip_hermes_owned_pythonpath(env) + assert env["PYTHONPATH"].split(os.pathsep) == ["/home/user/my-lib"] + + def test_repo_level_junction_negative_control(self, tmp_path, monkeypatch): + """A same-named REAL directory under the configured root (not a link + to the known physical repo) must never become an alias or be + stripped -- exact filesystem identity decides, not the name. + """ + import tools.environments.local as local + + physical_home = tmp_path / "physical-home" + physical_root = physical_home / "hermes-agent" + physical_root.mkdir(parents=True) + configured_home = tmp_path / "configured-home" + (configured_home / "hermes-agent").mkdir(parents=True) + + aliases = local._build_hermes_repo_root_aliases( + physical_root.resolve(), + physical_root, + configured_home, + ) + lookalike = configured_home / "hermes-agent" + assert not any(local._same_path(a, lookalike) for a in aliases) + + monkeypatch.setattr(local, "_hermes_repo_root_aliases", aliases) + env = {"PYTHONPATH": os.pathsep.join([str(lookalike), "/home/user/my-lib"])} + local._strip_hermes_owned_pythonpath(env) + assert env["PYTHONPATH"].split(os.pathsep) == [str(lookalike), "/home/user/my-lib"] + + def test_profile_home_with_repo_level_junction(self, tmp_path, monkeypatch): + """Profile re-home + repo-level junction together: the configured home + is /profiles/ while the repo is a link at /hermes-agent. + The root spelling must be derived (profiles -> grandparent) and then + the lexical repo alias recovered from it. + """ + import tools.environments.local as local + + physical_home = tmp_path / "physical-home" + physical_root = physical_home / "hermes-agent" + physical_root.mkdir(parents=True) + configured_root = tmp_path / "configured-root" + (configured_root / "profiles" / "coder").mkdir(parents=True) + try: + _make_directory_link(configured_root / "hermes-agent", physical_root) + except OSError as exc: + pytest.skip(f"directory link unavailable on this host: {exc}") + + configured_home = configured_root / "profiles" / "coder" + lexical_root = configured_root / "hermes-agent" + aliases = local._build_hermes_repo_root_aliases( + physical_root.resolve(), + physical_root, + configured_home, + ) + assert any(local._same_path(a, lexical_root) for a in aliases) + assert not any(local._same_path(a, configured_home / "hermes-agent") for a in aliases) + + monkeypatch.setattr(local, "_hermes_repo_root_aliases", aliases) + env = {"PYTHONPATH": os.pathsep.join([str(lexical_root), "/home/user/my-lib"])} + local._strip_hermes_owned_pythonpath(env) + assert env["PYTHONPATH"].split(os.pathsep) == ["/home/user/my-lib"] + + def test_validated_runtime_venv_lexical_after_repo_recovery(self, tmp_path, monkeypatch): + """uv-base gateway: once the lexical repo alias is recovered, a lexical + VIRTUAL_ENV (/venv) validates and its site-packages is + stripped together with the repo root, while user entries survive. + """ + import tools.environments.local as local + + physical_home = tmp_path / "physical-home" + physical_root = physical_home / "hermes-agent" + venv_dir = physical_root / "venv" + venv_dir.mkdir(parents=True) + (venv_dir / "pyvenv.cfg").write_text("home = x\n", encoding="utf-8") + configured_home = tmp_path / "configured-home" + configured_home.mkdir() + try: + _make_directory_link(configured_home / "hermes-agent", physical_root) + except OSError as exc: + pytest.skip(f"directory link unavailable on this host: {exc}") + + lexical_root = configured_home / "hermes-agent" + aliases = local._build_hermes_repo_root_aliases( + physical_root.resolve(), + physical_root, + configured_home, + ) + assert any(local._same_path(a, lexical_root) for a in aliases) + monkeypatch.setattr(local, "_hermes_repo_root_aliases", aliases) + + lexical_venv = lexical_root / "venv" + validated = local._validated_runtime_venv({"VIRTUAL_ENV": str(lexical_venv)}) + assert validated is not None + assert local._same_path(validated, lexical_venv) + + local._hermes_site_packages = None + env = {"PYTHONPATH": os.pathsep.join([ + str(lexical_root), + str(lexical_venv / "Lib" / "site-packages"), + "/home/user/my-lib", + ]), "VIRTUAL_ENV": str(lexical_venv)} + local._strip_hermes_owned_pythonpath(env) + assert env["PYTHONPATH"].split(os.pathsep) == ["/home/user/my-lib"] + + def test_lookalike_user_path_without_provenance_preserved(self, tmp_path, monkeypatch): + """A user PYTHONPATH entry that merely looks like a Hermes path + (repo-named directory, no link to the known physical repo) must be + preserved -- no ownership provenance, no strip. + """ + import tools.environments.local as local + + physical_home = tmp_path / "physical-home" + physical_root = physical_home / "hermes-agent" + physical_root.mkdir(parents=True) + unrelated = tmp_path / "user-tools" / "hermes-agent" + unrelated.mkdir(parents=True) + + aliases = local._build_hermes_repo_root_aliases( + physical_root.resolve(), + physical_root, + tmp_path / "configured-home", + ) + assert not any(local._same_path(a, unrelated) for a in aliases) + + monkeypatch.setattr(local, "_hermes_repo_root_aliases", aliases) + env = {"PYTHONPATH": os.pathsep.join([str(unrelated), "/home/user/my-lib"])} + local._strip_hermes_owned_pythonpath(env) + assert env["PYTHONPATH"].split(os.pathsep) == [str(unrelated), "/home/user/my-lib"] + + def test_deep_path_under_repo_root_preserved(self): """A deeper path under the repo root (depth=2) is preserved. diff --git a/tools/environments/local.py b/tools/environments/local.py index 761581a518..afc0769e68 100644 --- a/tools/environments/local.py +++ b/tools/environments/local.py @@ -1370,6 +1370,10 @@ def _build_hermes_repo_root_aliases( the resolved HERMES_HOME back onto the configured HERMES_HOME spelling. Mirror that producer contract here so a junction-backed install is matched without treating arbitrary descendants of HERMES_HOME as Hermes-owned. + Additionally, when the repo itself is a junction under the configured root + (repo-level junction, possibly cross-drive), the single deterministic + candidate / is accepted only when strict resolve + proves it is the exact physical repo root. """ aliases: list[Path] = [] @@ -1403,6 +1407,24 @@ def _build_hermes_repo_root_aliases( except (OSError, ValueError): pass + # Repo-level junction recovery: the repository itself may be a + # junction/symlink under the configured root (e.g. D:\hermes\hermes-agent + # -> C:\...\hermes-agent) while the import spelling (editable install) + # resolves to the physical location. The home-relative mapping above + # cannot express a cross-drive link (commonpath raises on different + # drives), so prove the EXACT filesystem identity of the single + # deterministic candidate -- / -- with a + # strict resolve before accepting it as Hermes-owned. Fail-closed: a + # missing path (strict resolve raises), a real directory that is not the + # known physical root, or any unrelated spelling never becomes an alias. + for home in home_candidates: + repo_candidate = home / resolved_root.name + try: + if repo_candidate.resolve(strict=True) == resolved_root.resolve(strict=True): + add(repo_candidate) + except OSError: + pass + return tuple(aliases)