fix: tighten subprocess Python environment isolation in #78917

[Starfie1d1272]

Summary

Follow-up to NousResearch#78917, based on independent local verification of that PR (see my Tested-by comment on NousResearch#78917, comment 5231755967). This does not re-implement the original PR — it fixes issues found in its _strip_mismatched_site_packages() implementation through adversarial review.

Changes

1. Remove the cross-version heuristic (fixes over-strip + semantic problem)

The original Check 1 stripped any PYTHONPATH entry whose path contains a python{X.Y} component when {X.Y} differs from the Hermes backend's interpreter version — without requiring the entry to be site-packages. Reproduced on macOS:

/opt/tools/python3.13/bin            → deleted (a bin dir, not site-packages)
/opt/downloads/python3.13            → deleted (a filename component)
/custom/lib/python3.13/site-packages → deleted (legitimate user path for a child python3.13)

The subprocess env builder cannot know which Python version a child will ultimately run, so judging user paths against the backend's interpreter version is incorrect. The cross-version check is removed entirely; Hermes-owned entries are now identified by path ownership, not by version.

2. Repo-root stripping narrowed to the exact root (over-strip fix)

Every real launcher producer was audited — Electron electron-main.mjs, gateway/run.py::_ensure_windows_gateway_venv_imports, cron/scheduler.py::_windows_cron_python_invocation, tui_gateway/host_supervisor.py — and none injects <repo>/tools or another direct child as an independent PYTHONPATH entry. The previous depth <= 1 rule deleted user paths that merely live under the repo directory. Only the exact repo root is now stripped; direct children and deeper user paths are preserved.

3. Windows junction/symlink alias recognition

The Windows gateway launcher deliberately renders Hermes-owned paths under the configured HERMES_HOME spelling (gateway_windows.py::_preserve_hermes_home_path), which may be a junction/symlink to another drive. That spelling differs lexically from Path(__file__).resolve(), so the ownership check previously could not recognize Hermes' own injected paths. _hermes_repo_root_aliases now carries both the resolved and unresolved (HERMES_HOME) spellings; both are recognized as Hermes-owned.

4. Sanitize inherited PYTHONHOME (completes NousResearch#75018)

NousResearch#75018 explicitly names PYTHONHOME as leaking into no_agent cron children (alongside PYTHONPATH and VIRTUAL_ENV). If the Hermes runtime inherits or carries PYTHONHOME in its process environment, it redirects the stdlib search of any child interpreter to the Hermes venv and crashes before a script even imports a package. PYTHONHOME is now part of _ACTIVE_VENV_MARKER_VARS, so all default/sanitized child-environment paths drop it:

• _make_run_env (foreground terminal)
• _sanitize_subprocess_env (background/PTY + cron no_agent via build_subprocess_env)
• hermes_subprocess_env (non-terminal spawns: TTS providers, browser)

This is consistent with Hermes' own child-process handling (managed_uv.py, sqlite_runtime.py already remove it) and with execute_code, which already scrubbed it via _SAFE_ENV_PREFIXES. The documented byte-for-byte escape hatch build_subprocess_env(scrub_secrets=False) is unchanged — it preserves everything, including PYTHONHOME, by contract (pinned by test).

5. Rename stale abstraction

_strip_mismatched_site_packages → _strip_hermes_owned_pythonpath: the cross-version heuristic is gone, so the old name misdescribed the behavior. All call sites, tests, and docstrings updated; no old symbol remains.

Known residual case

Nix extraPythonPackages are appended to PYTHONPATH by the Hermes Nix wrapper (nix/hermes-agent.nix, --suffix PYTHONPATH) outside the normal repo-root / venv-site-packages ownership boundary. This follow-up deliberately does not guess ownership from /nix/store path shape: Nix users' legitimate PYTHONPATH entries also live under /nix/store, and there is no provenance data to distinguish Hermes-injected store paths from user-set ones. A provenance-aware producer-side solution (e.g. an explicit Hermes-internal marker) would be safer and is left to a future discussion.

Windows test coverage — what it actually proves

• test_windows_backslash_paths (POSIX CI): a safety test — Windows-looking user strings are never destroyed by the ownership filter on a POSIX host. It does NOT claim Windows stripping works.
• test_windows_hermes_owned_paths_stripped (@pytest.mark.skipif(sys.platform != "win32")): the real Windows behavior test — Hermes venv site-packages written with backslashes is stripped, user Windows paths preserved. Runs only on Windows CI.
• test_repo_root_junction_alias_stripped: the alias logic is tested on any host via a monkeypatched lexical pair (resolved vs junction spelling).

Rationale

Strip Hermes-owned runtime contamination, not arbitrary user Python paths.

The original PR's selective-filter direction is correct and strictly better than blanket-strip alternatives (NousResearch#74951/NousResearch#74871). The problems were only in what counts as "dangerous": the backend's interpreter version is not a proxy for the child's, pythonX.Y alone over-strips, and repo-root matching was broader than any real producer.

Tests

Ran on macOS arm64 (Hermes backend Python 3.11.15) against this branch:

TestPythonpathSelectiveStrip (16 tests) + TestPythonhomeSanitized (6 tests): 22 passed, 1 skipped (Windows-only)
Full file tests/tools/test_local_env_blocklist.py: 52 passed, 1 skipped / 16 failed

The 16 failures are pre-existing on the base branch (yiipu/fix/pythonpath-selective-strip) — identical node IDs (verified by diff), all isolation-venv environment issues (module 'tools' has no attribute 'terminal_tool' in pkgutil traversal). Base run: 42 passed / 16 failed. Net: +10 passing tests, 0 regressions.

Integration validation: the three-commit chain (this branch) cherry-picks cleanly onto current upstream main (35e562e) — no conflicts, no duplicate env handling, same 52 passed / 16 failed there.

Live E2E (this machine):

Before (unpatched main):        PYTHONPATH=/Users/…/.hermes/hermes-agent:/Users/…/venv/lib/python3.11/site-packages leaked into children;
                                python3.13 conda env: import numpy → ModuleNotFoundError: numpy._core._multiarray_umath (3.11 ABI)
After this branch:              Hermes repo root + venv site-packages stripped;
                                /opt/tools/python3.13/bin, /custom/lib/python3.13/site-packages preserved;
                                PYTHONHOME removed from all sanitized builders (no-scrub path unchanged);
                                junction spelling of repo root recognized;
                                python3.13 conda env imports numpy/PIL from its own site-packages

Relationship

• Follow-up to: fix(tools): selectively strip Hermes-venv PYTHONPATH from subprocesses (#74817) NousResearch/hermes-agent#78917
• Issues: PYTHONPATH leaks into terminal-tool subprocesses on macOS/Linux, can crash unrelated third-party apps NousResearch/hermes-agent#74817 (PYTHONPATH leak), Gateway exports PYTHONPATH/VIRTUAL_ENV to no_agent cron children, poisoning non-venv Python interpreters NousResearch/hermes-agent#75018 (cron child env; this PR completes its PYTHONHOME portion)
• Prior verification comment: fix(tools): selectively strip Hermes-venv PYTHONPATH from subprocesses (#74817) NousResearch/hermes-agent#78917 comment 5231755967
• Do not close fix(tools): selectively strip Hermes-venv PYTHONPATH from subprocesses (#74817) NousResearch/hermes-agent#78917 with this PR — it builds on top of it and should merge after (or together with) it.

[Starfie1d1272]

The follow-up has now been consolidated into direct upstream PR NousResearch#82581 on current main. All commits from this PR and NousResearch#78917 were retained with their original Git authorship, with additional Windows runtime ownership hardening and paired pristine-base validation. I am leaving this PR open; its superseded/close status remains for the owners to decide.