hermes - 💡(How to fix) Fix hermes update: stale 'commits behind' banner persists for custom HERMES_HOME profiles

Summary

hermes update invalidates the update-check cache for the default profile (~/.hermes/) and any subdirectories under ~/.hermes/profiles/, but it does not invalidate the cache at $HERMES_HOME/.update_check when HERMES_HOME points outside ~/.hermes. As a result, hermes --version continues to show the pre-update "X commits behind" banner indefinitely from any custom-HERMES_HOME profile, even though the upgrade succeeded.

Reproducer

1. Set HERMES_HOME=/some/other/path (e.g., a per-project install) and run hermes from there for a while so $HERMES_HOME/.update_check gets written with {"behind": N, ...} for some N > 0.
2. From ~/.hermes (or any default profile location), run hermes update. Update succeeds; ~/.hermes/.update_check is cleared and rewritten with behind: 0.
3. From the custom-HERMES_HOME profile, run hermes --version. Banner still says Update available: N commits behind — run 'hermes update', even though no update is needed.

Confirmed on Hermes Agent v0.13.0 (2026.5.7) on macOS.

Root cause

_invalidate_update_cache() in hermes_cli/main.py (around line 6388 in the v0.13.0 tree) walks:

• get_default_hermes_root() (resolves to ~/.hermes/ outside Docker)
• subdirectories of <default_root>/profiles/

It does not consult os.environ.get("HERMES_HOME"), so any custom profile installed outside the default tree keeps its stale cache.

Suggested fix

Include Path(os.environ["HERMES_HOME"]) in the homes list when HERMES_HOME is set and resolves to a path outside the default tree. Something like:

hermes_home = os.environ.get("HERMES_HOME", "").strip()
if hermes_home:
    p = Path(hermes_home).expanduser().resolve()
    if p not in (h.resolve() for h in homes):
        homes.append(p)

Workaround until fixed: rm \"\$HERMES_HOME/.update_check\" after running hermes update.

Environment

• Hermes Agent v0.13.0 (2026.5.7), upgraded from v0.12.0 (2026.4.30)
• macOS (Darwin 25.3.0), zsh
• Python 3.11.15