fix(env): scope terminal config re-bridge to the true process profile

[Bergmann89]

What does this PR do?

In a multiplexed dashboard/gateway (one process serving every profile on the host), a secondary profile's terminal.backend could leak into the shared os.environ and silently override the launch profile's terminal backend. A profile configured for terminal.backend: ssh would end up running every command on the local host because a sibling profile with backend: local had polluted the shared environment.

The tell is an asymmetric env state on the launch session:

TERMINAL_ENV=local             # leaked from a sibling profile
TERMINAL_SSH_HOST=10.10.0.103  # still the launch profile's — untouched

A restart does not help: as soon as the sibling profile is touched again (a turn, a cron tick), the shared env is re-poisoned.

Root cause

env_loader._reapply_terminal_config_bridge() guards "only re-bridge config into the shared os.environ when this load is for the process's own profile":

if Path(home_path).resolve() != _process_hermes_home().resolve():
    return

_process_hermes_home() delegated to get_hermes_home(), which follows the context-local set_hermes_home_override a per-request task installs. When a per-turn handler is scoped to a secondary profile (via _config_profile_scope / set_hermes_home_override) and triggers a load_hermes_dotenv() reload, both sides of the comparison resolve to that secondary profile — the guard passes, and the bridge runs apply_terminal_config_to_env(env=None) against the shared os.environ, writing the wrong profile's terminal.backend.

Because the secondary profile's config.yaml carries no TERMINAL_SSH_* keys, only TERMINAL_ENV is overwritten (explicit-keys-only bridge semantics), producing the asymmetric state above.

The helper was originally introduced for the config-cache key (where following the active home is correct) and later reused for the terminal bridge guard, where the override-following semantics are wrong.

The fix

Delegate _process_hermes_home() to get_process_hermes_home(), the override-immune resolver built for exactly this — it reflects the scope the process was launched under, ignoring per-task overrides. Both call sites (the bridge guard and the secrets-cache reuse check in _load_secrets_config) want the true process home.

This is the correct boundary: in a multiplex process os.environ belongs to the launch profile. A secondary profile's terminal config must reach its own sessions through session-scoped mechanisms (see Related), never by mutating the shared process environment.

Related Issue

Same bug class (cross-profile terminal-backend leak under multiplexing), addressed here at a bridge site that no open PR touches:

• Related to [Bug]: Desktop in-process agent spawns container labeled CODER with code-reviewer's terminal.* config (cross-profile env bridge) #96992 (main-verified, desktop in-process; enumerates the layers of this class) and Desktop app: tool execution environment uses wrong HERMES_HOME and doesn't load profile .env #72480 (wrong HERMES_HOME for tool env — same symptom class at the process-env layer).
• Complementary, not a duplicate:
  • fix(tools): scope the terminal env bridge one-shot to the Hermes home #94206 / _ensure_terminal_env_bridged one-shot leaks profile-specific TERMINAL_ENV across multiplexed profiles #94200 fix the terminal_tool._ensure_terminal_env_bridged() process-global one-shot latch.
  • fix(gateway): scope terminal config per routed profile in multiplexed gateway #79117 / [Bug]: Multiplexed gateway ignores routed profile terminal backend; Docker profile inherits local backend #68559 scope terminal config in gateway/run.py for routed multiplex profiles.
  • fix(gateway): bind multiplex sessions to routed profile cwd #88635 scopes terminal.cwd (not backend) for multiplex sessions.

Each of those fixes a different bridge site. This PR fixes a third, independent one — env_loader._reapply_terminal_config_bridge() — which runs on every load_hermes_dotenv() and is not covered by any of the above. Fixing only the others leaves this path as a live leak (and vice versa).

Happy to fold this into #96992's tracking or coordinate with #94206's author if the maintainers prefer to consolidate the cluster.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)

Changes Made

• hermes_cli/env_loader.py — _process_hermes_home() now delegates to hermes_constants.get_process_hermes_home() (override-immune) instead of get_hermes_home() (which follows the per-task context override). Docstring expanded to explain why both callers require the true process home.
• tests/hermes_cli/test_terminal_bridge_profile_scope.py — new regression test:
  • test_process_hermes_home_ignores_task_override — the resolver ignores an active set_hermes_home_override.
  • test_secondary_profile_reload_does_not_bridge_into_shared_env — a secondary-profile reload leaves the launch profile's TERMINAL_ENV and TERMINAL_SSH_* in os.environ untouched.

How to Test

Reproduce the leak and confirm the fix:

1. Configure two profiles: laptop (terminal.backend: ssh, with ssh_host/ssh_user) and tommy (terminal.backend: local, no ssh keys).

2. Launch under laptop (HERMES_HOME=…/laptop), so the shared env carries TERMINAL_ENV=ssh + TERMINAL_SSH_*.

3. Simulate a per-turn handler scoped to the secondary profile and drive a reload for its home:

   from hermes_constants import set_hermes_home_override, reset_hermes_home_override
   import hermes_cli.env_loader as env_loader
   
   tok = set_hermes_home_override(str(tommy_home))
   try:
       env_loader._reapply_terminal_config_bridge(tommy_home)
   finally:
       reset_hermes_home_override(tok)

4. Before: os.environ["TERMINAL_ENV"] == "local" (tommy's backend leaked), TERMINAL_SSH_HOST still laptop's — the launch session silently runs locally. After: TERMINAL_ENV stays "ssh"; nothing leaks.

Automated:

pytest tests/hermes_cli/test_terminal_bridge_profile_scope.py -q

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(env): …)
• I searched for existing PRs/issues to make sure this isn't a duplicate (found a related cluster — see Related Issue; this bridge site is uncovered)
• My PR contains only changes related to this fix (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes
• I've tested on my platform: Linux (aarch64, Docker)

Documentation & Housekeeping

• I've updated relevant documentation (docstrings) — expanded _process_hermes_home docstring; no user-facing docs affected
• cli-config.yaml.example — N/A (no config keys added/changed)
• CONTRIBUTING.md / AGENTS.md — N/A (no architecture/workflow change)
• Cross-platform impact considered — resolver swap is platform-agnostic; single-profile / CLI behaviour is unchanged (with no active override the two resolvers are identical)
• Tool descriptions/schemas — N/A (no tool behaviour change)

[monerostar]

Ubuntu 26.04 on linux-5800x (kernel 7.0.0-30-generic). This box runs more than one Hermes profile in one process family, so the shared os.environ leak is the class we care about.

Copied the PR tests to /tmp so pytest would import each tree:

• main 8c098e9e8: both fail. _process_hermes_home() follows set_hermes_home_override (get_hermes_home()). After a secondary-profile reload, TERMINAL_ENV goes ssh -> local.
• this PR 6eb4b5050: 2 passed in 0.03s. Process home stays the launch home. TERMINAL_ENV stays ssh.

Python 3.11.15. Looks good.

[kshitijk4poor]

Landed on main via #103625 as 2e24e06e55 — your commit cherry-picked unchanged with authorship preserved, @Bergmann89. Live-verified: scoping to a secondary profile and reloading its .env (what the multiplex cron tick does) leaked TERMINAL_ENV=docker + that profile's TERMINAL_DOCKER_VOLUMES into the shared env on main; with your fix both stay unset. Thanks — closing in favour of the merged salvage.