fix(subdirectory_hints): catch RuntimeError from Path.expanduser()

[udatny]

What does this PR do?

Fixes a silent agent failure where any tool-call command containing a literal ~ in a non-path context (e.g. ~500-700 agencies, ~45,000 CVEs, ~80/hr blended rate — common LLM output meaning "approximately") causes the entire tool invocation to surface as Error during OpenAI-compatible API call #N: Could not determine home directory. from inside the conversation loop's catch-all.

The actual root cause is in agent/subdirectory_hints.py: Path(token).expanduser() raises RuntimeError when the tilde-expansion can't resolve to a real user, and the existing except (OSError, ValueError): clauses do not catch it. The exception bubbles up through the tool dispatcher and gets misreported as an API call error, masking the bug and making it look model-specific.

Related Issue

Fixes

Type of Change

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

Changes Made

• agent/subdirectory_hints.py:138 — except (OSError, ValueError) → except (OSError, ValueError, RuntimeError) (in _add_path_candidate, which calls Path(raw_path).expanduser()).
• agent/subdirectory_hints.py:198 — except ValueError → except (ValueError, RuntimeError) (around hint_path.relative_to(self.working_dir), which also touches the tilde-expansion path internally).
• agent/subdirectory_hints.py:202 — same as 198 around hint_path.relative_to(Path.home()) (where Path.home() itself can raise RuntimeError if HOME is not resolvable in the calling context).
• tests/agent/test_subdirectory_hints.py — three new tests in a TestSubdirectoryHintTrackerTildeRobustness class:
  • test_tilde_approximately_in_command_does_not_crash: simulates an LLM heredoc with ~500-700/~45,000-style tokens. Without the fix, raises RuntimeError. With the fix, returns silently.
  • test_tilde_with_unknown_user_does_not_crash: ~nonexistent_user/path (POSIX), same expectation.
  • test_valid_tilde_user_still_works: regression guard so legitimate ~/Documents paths still work.

How to Test

Repro on main (without the fix):

>>> from pathlib import Path
>>> Path("~500-700").expanduser()
RuntimeError: Could not determine home directory.

Inside Hermes (without the fix), the symptom is:

$ cat > out.md <<EOF
Size signal: ~500-700 agencies
EOF
  0.0s [error]
❌ Error during OpenAI-compatible API call #2: Could not determine home directory.

After applying the fix:

pytest tests/agent/test_subdirectory_hints.py -q
# All TestSubdirectoryHintTrackerTildeRobustness tests pass.

Affected models we've reproduced this on (it is not model-specific):

• openai/gpt-5-mini via OpenRouter
• openai/gpt-5.1-codex via OpenRouter (mid-pipeline, ~33 turns in, on a heredoc containing ~80/hr blended rate)
• deepseek/deepseek-v4-flash via OpenRouter

Checklist

Code

• I've read the Contributing Guide
• Conventional Commits: fix(subdirectory_hints): catch RuntimeError from Path.expanduser()
• No duplicate PR — searched issues/PRs for "Could not determine home directory" and "subdirectory_hints"
• PR contains only this fix + its test
• pytest tests/agent/test_subdirectory_hints.py -q passes
• Added tests covering the bug + a regression test for the legitimate-tilde case
• Tested on: Linux (Docker nousresearch/hermes-agent:latest), Python 3.13

Documentation & Housekeeping

• N/A — internal fix, no user-facing config or docs change
• N/A — no config key changes
• N/A — no architecture change
• No cross-platform impact: bug and fix are pure Python/pathlib
• No tool description / schema changes

Why this is hard to notice without the fix

The surfaced error string is "Error during OpenAI-compatible API call #N: Could not determine home directory." which strongly suggests an API-side or environment-side problem. In reality it's a pathlib exception three frames deep in the hint walker, wrapped twice by the conversation loop's catch-all. Once you know to look at subdirectory_hints.py, the one-line nature of the fix is obvious. Hopefully this PR saves the next user the few hours we spent tracing it.

[alexzhu0]

LGTM — strong candidate for merge

Reproduced the symptom on main against openai/gpt-5.1-codex and minimax-cn/MiniMax-M3 (this session) — a terminal command with ~500-700 in a heredoc blew up the tool dispatcher with the misleading "Could not determine home directory" error string. The author's three-line fix in subdirectory_hints.py resolves it.

Strengths

• Reproduces a real LLM output pattern (~ as "approximately"), not a contrived edge case
• Three test cases cover: buggy case, edge case, regression guard
• The companion fix to Path.home() (lines 198/202) is a nice catch — same exception class affects relative_to(Path.home())
• Conventional Commits + clean checklist

Suggestions (non-blocking)

1. Rebase needed — main advanced 5 days since this branch was cut; mergeable_state: blocked likely from required CI checks rather than conflicts, but a rebase onto current main will rule that out.

2. Broader blast radius — while reading the diff I grep'd the repo for other Path(...).expanduser() call sites that don't catch RuntimeError. Three adjacent ones worth considering for a follow-up PR (would happily file any/all if you want to keep this one focused):

   • agent/tool_dispatch_helpers.py:158 — expanded = Path(raw_path).expanduser() in _get_path_target. This is on the hot path for every path-scoped tool call (read_file/write_file/edit_file/...). Same bug class, higher impact than subdirectory_hints because the path comes straight from function_args["path"].
   • agent/skill_commands.py:63 — identifier_path = Path(raw_identifier).expanduser() in slash-command resolver. raw_identifier is user-supplied.
   • hermes_cli/gateway.py:2095-2101 — Path.home() itself can raise RuntimeError, only ValueError is caught.

3. Optional: a lint rule — would prevent future regressions. A simple flake8-no-runtime-warn plugin or a one-off AST check that flags bare Path(...).expanduser() not wrapped in try/except (..., RuntimeError).

Verdict

LGTM. The PR is correctly scoped, well-tested, and addresses a real production pain point that misleads users into chasing model/environment issues. Recommending merge once rebased and CI green.

[gtyler]

Confirming this is the right fix — reproduced on main: Path.expanduser() raises RuntimeError("Could not determine home directory.") for a ~user token whose user has no passwd entry (the ~user form does a passwd lookup, so $HOME being set doesn't help), and it escapes the except (OSError, ValueError) in _add_path_candidate, aborting the whole agent turn (~3×/24h on a long-running gateway here). Tracked in #43963.

Two things worth folding in before this lands:

• Second call site, same bug: hermes_cli/kanban_db.py:_is_managed_scratch_path() (~line 3781) resolves HERMES_KANBAN_WORKSPACES_ROOT via expanduser() and also catches only OSError — it'll crash the same way. Worth fixing in the same PR (or via the safe_expanduser() sweep in feat(utils): add safe_expanduser() — crash-free path expansion for HOME-unset environments #41870).
• Regression test: a test that exercises the real ~nonexistentuser passwd-lookup path through check_tool_call would lock this in.

Closing my duplicate #43970 in favor of this earlier PR.

[udatny]

Rebased onto current main. The 3-line fix in subdirectory_hints.py plus the test file reapplied cleanly — no conflicts, same diff, just shifted line numbers (now 144 / 241 / 244 in current main). Head is 2351002, mergeable: MERGEABLE now.

Keeping this PR scoped to subdirectory_hints.py to keep review surface small. The other expanduser() sites you both flagged are real and have the same bug class — happy to file follow-up PRs for each:

• @gtyler — hermes_cli/kanban_db.py:_is_managed_scratch_path() (same except OSError only pattern). Your ~nonexistentuser real-passwd-lookup regression test is a stronger test than the synthesized one currently in the diff — would fold that into the follow-up.
• @alexzhu0 — agent/tool_dispatch_helpers.py:_get_path_target (hot path for every path-scoped tool call — higher blast radius than this PR), plus agent/skill_commands.py and hermes_cli/gateway.py:Path.home().

Happy to consolidate into one omnibus PR instead if maintainers prefer — let me know.

@gtyler — thanks for closing #43970 in favor of this one.

[udatny]

Small follow-up: the test file as originally submitted referenced a project fixture that's only defined locally in tests/agent/test_subdirectory_hints.py, so it didn't resolve when the file ran standalone (the README in my upstream-pr/ bundle said "append OR new file" but the new-file path was broken — my mistake).

Fixed by switching the three tests to pytest's built-in tmp_path — they don't need the richer mock-project tree anyway, just a working directory. Amended into the same commit (head now fef4124).

Verified on Linux:

PASS: test_tilde_approximately_in_command_does_not_crash
PASS: test_tilde_with_unknown_user_does_not_crash
PASS: test_valid_tilde_user_still_works

Also independently confirmed the bug-vs-fix behaviour on Path("~500-700").expanduser(): raises RuntimeError on POSIX without the patch, swallowed by the widened except with the patch. Windows doesn't reproduce (no passwd lookup on ~user), so the regression test is POSIX-meaningful only — but harmless on Windows.

[teknium1]

Thanks for the focused fix. This is already implemented on current main via the contributor-authored commit c126a99fc1e2f82a1e23ebe27fb52e26687fdafa and shipped in v2026.7.1.

Automated hermes-sweeper review evidence:

• agent/subdirectory_hints.py:147 catches RuntimeError with the existing path-resolution errors; the corresponding display-path handlers are at lines 244 and 248.
• tests/agent/test_subdirectory_hints_tilde.py:19 contains the approximate-tilde, unknown-user, and valid-tilde regression coverage.
• git diff HEAD fef4124 -- agent/subdirectory_hints.py tests/agent/test_subdirectory_hints_tilde.py is empty, so the PR's changed paths are already identical on main.