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

[liuhao1024]

What does this PR do?

Fixes a crash in subdirectory_hints.py when the $HOME environment variable is unset. On Python 3.11+, Path.expanduser() and Path.home() raise RuntimeError (not OSError or ValueError) when $HOME is unset, but the existing except clauses only caught the latter two — allowing the RuntimeError to propagate and crash the agent conversation loop.

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 both except clauses that handle Path.expanduser() (line 147) and Path.home() (line 248) calls
• tests/agent/test_subdirectory_hints.py: Added 2 regression tests verifying graceful handling when expanduser() and Path.home() raise RuntimeError

How to Test

1. Run pytest tests/agent/test_subdirectory_hints.py -v — all 27 tests should pass
2. On a Linux system (or container) without $HOME set: env -u HOME python -c "from agent.subdirectory_hints import SubdirectoryHintTracker; t = SubdirectoryHintTracker(working_dir='.'); print('OK')" — should not crash
3. Verify existing functionality still works: pytest tests/agent/test_subdirectory_hints.py::TestSubdirectoryHintTracker -v

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 — _add_path_candidate(), _load_hints_for_file()
• Blast radius: LOW — only affects error handling in hint discovery, no control flow changes
• Related patterns: Path.expanduser() / Path.home() RuntimeError on Python 3.11+ when $HOME is unset (common in containers/CI)

[tonydwb]

Code Review Summary

Verdict: Approved

Fix: catch RuntimeError raised by Path.expanduser() or Path.home() when the $HOME environment variable is unset (common in certain container/entrypoint environments). Wraps the expansion in a try/except and falls back gracefully.

Looks Good

• Minimal, focused 3-line addition to one function
• Proper exception handling with a meaningful fallback
• No test changes (edge-case fix in a runtime detection path)
• No security concerns

[alt-glitch]

Duplicate of #29433 — same fix in agent/subdirectory_hints.py (add RuntimeError to the Path.expanduser()/Path.home() except clauses for Py3.11+ when $HOME is unset). #29433 is the earliest still-open PR for this fix.

[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 an approval from @alexzhu0.