fix(bootstrap): clarify shebang fallback precedence + tighten test setup

Addresses review feedback on PR #1817:

1. Extend the `_agent_dir_from_hermes_cli` docstring to spell out that
   the shebang fallback is a last-resort discovery step, not an override.
   Stale clones in known candidate paths still win — same precedence as
   today, but now documented so a future maintainer doesn't get the
   wrong idea.

2. Drop the misleading "install exists but no run_agent.py" comment in
   `test_returns_none_when_shebang_interpreter_does_not_walk_to_run_agent`.
   The test exercises a shebang pointing at /usr/bin/python3 whose
   parents never reach a run_agent.py — it doesn't actually need a fake
   install dir at all. Renamed for accuracy and removed the unused
   _make_agent_install call.

bootstrap.py

@@ -102,6 +102,12 @@ def _agent_dir_from_hermes_cli() -> Path | None:
     `run_agent.py` recovers the install root regardless of where the user
     chose to clone the agent (e.g. ~/Projects/GitHub/hermes-agent), which
     the hard-coded candidate list in :func:`discover_agent_dir` cannot.
+
+    Last-resort only: this is invoked after every explicit candidate
+    (`HERMES_WEBUI_AGENT_DIR`, `$HERMES_HOME/hermes-agent`, etc.) has missed.
+    A stale clone in a known location still wins over the live `hermes` CLI
+    — that's intentional, since the candidate list is treated as
+    authoritative when present, and matches existing behavior.
     """
     hermes_path = shutil.which("hermes")
     if not hermes_path:

tests/test_bootstrap_discover_agent.py

@@ -83,9 +83,8 @@ def test_returns_none_when_hermes_has_no_shebang(monkeypatch, tmp_path):
     assert bootstrap.discover_agent_dir() is None
 
 
-def test_returns_none_when_shebang_interpreter_does_not_have_run_agent(monkeypatch, tmp_path):
-    """Shebang points at /usr/bin/python3 — no install root walks up to run_agent.py."""
-    _make_agent_install(tmp_path, with_run_agent=False)  # install exists but no run_agent.py
+def test_returns_none_when_shebang_interpreter_does_not_walk_to_run_agent(monkeypatch, tmp_path):
+    """Shebang points at a system Python — no parent of /usr/bin/python3 has run_agent.py."""
     hermes = _make_hermes_cli(tmp_path, "/usr/bin/python3")
     _isolate_discover_agent_dir(monkeypatch, tmp_path, hermes)