fix(agent): catch RuntimeError from Path.expanduser/home when $HOME is unset

[liuhao1024]

What does this PR do?

Catches RuntimeError from Path.expanduser() and Path.home() in SubdirectoryHintTracker when the $HOME environment variable is unset, preventing the agent conversation loop from crashing.

Related Issue

Fixes #45401

Type of Change

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

Changes Made

• agent/subdirectory_hints.py: Added RuntimeError to 4 except clauses that previously only caught (OSError, ValueError). On Python 3.11+, Path.expanduser() and Path.home() raise RuntimeError when $HOME is unset — this was unhandled and crashed the agent.
• tests/agent/test_subdirectory_hints_runtime_error.py: 4 tests covering each RuntimeError site — _add_path_candidate, _is_valid_subdir, _load_hints_for_directory (is_relative_to), and the Path.home() relative-path fallback.

How to Test

1. python -m pytest tests/agent/test_subdirectory_hints_runtime_error.py -v — all 4 tests should pass
2. Verify the fix manually: unset HOME && hermes chat — should no longer crash with RuntimeError: Could not determine home directory
3. Confirm normal behavior: with $HOME set, hint tracking works as before

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: macOS

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Code Intelligence

• Analyzed: agent/subdirectory_hints.py (callers: 2 in agent/tool_executor.py, 1 in agent/agent_init.py)
• Blast radius: LOW — only adds exception types to existing catch clauses, no control-flow changes
• Related patterns: Python 3.11+ pathlib RuntimeError on missing $HOME

[alt-glitch]

Duplicate of #29433 - same file and same fix (add RuntimeError to the except clauses in agent/subdirectory_hints.py for Path.expanduser()/home()). #29433 is the earliest open PR; this fixes #45401. See also #41870 (safe_expanduser sweep).

[tonydwb]

Code Review Summary

Verdict: Approved

Adds RuntimeError to the exception handlers in _add_path_candidate, _is_valid_subdir, and _load_hints_for_directory throughout subdirectory_hints.py. Python 3.11+ raises RuntimeError from Path.expanduser() and Path.home() when $HOME is unset.

• Clean regression fix with dedicated test fixture covering all three error paths
• Test file is well-documented with issue reference (#45401)
• No security concerns
• No debug artifacts

---

Reviewed by Hermes Agent

[liuhao1024]

Closing as duplicate of #29433 by @udatny, which implements the same fix (adding RuntimeError to except clauses in agent/subdirectory_hints.py). That PR was opened earlier (May 20) and has passing CI. Our PR covered the same except blocks plus _is_valid_subdir — but the core fix is identical.