fix(agent): guard subdirectory_hints against unset HOME RuntimeError

[Kewe63]

Summary

Path.expanduser() and Path.home() raise RuntimeError (not OSError/ValueError) on Python 3.11+ when $HOME is unset. This was not caught by the existing except clauses in agent/subdirectory_hints.py, crashing the entire agent conversation loop. This fix adds RuntimeError to all 5 affected except clauses.

---

Changes

File: agent/subdirectory_hints.py

• Added RuntimeError to except clauses at lines 147, 191, 213, 244, 248.

---

How to Test

pytest tests/agent/test_subdirectory_hints.py -xvs
# ✅ 25/25 passed

---

Checklist

• Tests pass — 25/25
• Changes scoped to this fix only
• Follows Conventional Commits

---

Risk & Impact

Minimal. Five-character additive change per clause — no behavioral change in environments where $HOME is set. Prevents a full conversation loop crash in containerized or minimal environments where $HOME may be unset.

Type: 🐛 Bug fix
Closes: #45401

[liuhao1024]

Verification: clean defensive fix

Reviewed the diff — adding RuntimeError to exception handlers in agent/subdirectory_hints.py is the correct fix. Path.home() raises RuntimeError when HOME is unset (containers, CI, Windows service accounts). The fix covers all 5 call sites where Path.home() or relative_to() could fail with this error:

1. _add_path_candidate — parent traversal loop
2. _is_valid_subdir — is_relative_to check
3. _load_hints_for_directory — is_relative_to check
4. _load_hints_for_directory — relative_to(self.working_dir) fallback
5. _load_hints_for_directory — relative_to(Path.home()) fallback

The fallback behavior (keep absolute path, skip directory) is safe. No behavioral change for normal environments — RuntimeError only fires when HOME is unset.

[tonydwb]

Code Review Summary

Verdict: Approved

Overview

Adds RuntimeError to exception handling in SubdirectoryHintTracker to guard against Path.home() raising RuntimeError when $HOME is unset (a RuntimeError is raised when the HOME environment variable is not set, unlike OSError for other path errors).

Changes

• Catches RuntimeError alongside OSError and ValueError in _add_path_candidate, _is_valid_subdir, and _load_hints_for_directory
• Minor cosmetic changes (tuple formatting, line wrapping)

Assessment

• Correctness: Path.home() raises RuntimeError when HOME is unset — this is a known edge case on systems where HOME is not defined. The fix is targeted and correct.
• No security or performance concerns.

---

Reviewed by Hermes Agent

[alt-glitch]

Duplicate of #29433 — same file (agent/subdirectory_hints.py), same fix (add RuntimeError to the expanduser/home except clauses). #29433 is the earliest open PR for this; #45430 and #45468 were prior closed twins.

[Kewe63]

Thanks for pointing this out. Closing in favour of #29433 same fix, earlier PR. Happy to review or test if that helps move it forward.