# NousResearch/hermes-agent · Update check logic, caching, and version reporting bugs

## Open now

- 6 issues, 8 PRs open on GitHub.
- #8063: \[Feature\]: Add fixed-cycle stable version release mechanism (monthly/optional weekly)
- #16640: \[Feature\]: Docker stable releases
- #20728: Bug: TUI banner shows stale "N commits behind" after successful \`hermes update\`
- #23681: \[Bug\]: Update check cache hides commit list until ~/.hermes/.update_check is manually deleted
- #23721: \[Feature\]: "hermes update" command need support  tag  parameter.
- #39771: hermes version shows '860 commits behind' after checking out latest tag v2026.5.29.2
- PR #11329: fix: invalidate update cache in _update_via_zip path (#11327)
- PR #23699: fix: don't cache failed update checks; sync cache on explicit --check
- PR #27844: fix(update): key update-check cache by git HEAD
- PR #39776: fix(version): suppress false 'commits behind' warning on detached HEAD (tag checkout)
- PR #40999: fix: invalidate update cache using local HEAD (fixes #40944)
- PR #41012: fix(cli): invalidate update cache when source HEAD changes
- PR #41043: fix(cli): bust update-check cache when local HEAD moves
- PR #43824: fix: clarify update status for branch and tag checkouts

These issues and PRs concern problems with how the update checker determines the latest version (main vs. release tags), stale or incorrectly keyed update-check cache behavior, and false 'commits behind' warnings shown to users. A few adjacent items touch Windows update behavior and stable release cadence proposals.

## TL;DR

- 41 member(s): 6 open issue(s), 13 closed issue(s), 8 open PR(s), 2 merged PR(s), 12 PR(s) closed without merging.
- A fix was merged to main in PR #1637. Verify it addresses your case.
- **Recommended:** read PR #1637 (and any competing PRs below) before filing. Confirm the merged change covers your symptom.

## Maintainer resolution verdict

- Internal-tracker verdict over this cluster's issue members: `partially_resolved` · deciding PR(s): `pr-1637,pr-34846`. This is distinct from the fix status above. Weigh it yourself.

## How this cluster was grouped

- Link evidence (`STRUCTURAL_PARTIAL`): some members are connected by structural evidence (shared changed files, or a closing/superseded reference); the rest are joined by an automated relevance judgement over their text.
- Members outside that structural core may belong to a different underlying problem.
- Pairwise link density `0.05`: the share of member pairs that carry a link, counting a structural link in full and a relevance-only link at 0.36. `1.00` means every pair is linked.

## Open related issues

- #8063: \[Feature\]: Add fixed-cycle stable version release mechanism (monthly/optional weekly)
- #16640: \[Feature\]: Docker stable releases
- #20728: Bug: TUI banner shows stale "N commits behind" after successful \`hermes update\`
- #23681: \[Bug\]: Update check cache hides commit list until ~/.hermes/.update_check is manually deleted
- #23721: \[Feature\]: "hermes update" command need support  tag  parameter.
- #39771: hermes version shows '860 commits behind' after checking out latest tag v2026.5.29.2

## Closed / duplicate issues

- #1620: \[Bug\]: \`hermes --version\` shows "26 commits behind" when already on latest
- #11007: Stale update cache: banner shows 'N commits behind' after updating
- #11327: Banner shows stale 'commits behind' after successful update — .update_check cache not invalidated
- #21526: hermes update: stale 'commits behind' banner persists for custom HERMES_HOME profiles
- #27841: Update check cache can report stale commits-behind after git pull
- #34491: check_for_updates() cache not invalidated after pip upgrade, showing stale "1 commit behind"
- #34514: \[Feature\]: hermes update should track the latest release, not the latest main commit
- #38093: \[Bug\]: main branch reports 0.15.1 after v2026.5.29.2 release
- #38618: Update reports 7 commits behind / remains on 0.15.1 when main differs from latest release tag 0.15.2
- #40944: Banner shows stale "commits behind" count after manual git pull in source installs
- #49611: \[Feature\]: Do Not Automatically Update Windows Desktop on Startup
- #52814: \[Feature\]: Update to latest tagged release
- #58746: feat(hermes): hermes update should target the latest stable release, not main

## Prior & competing PRs

- **#1637: fix(cli): invalidate update-check cache after hermes update**. merged to main · fix tier `verified`
  - maintainer direction: category `merged`; implication `superseded`
  - files: `hermes_cli/main.py`
  - fix hunks:
  - `hermes_cli/main.py`

    ```diff
    @@ -2124,7 +2124,17 @@ def _restore_stashed_changes(
         print("  Review `git diff` / `git status` if Hermes behaves unexpectedly.")
         return True
     
    -
    +def _invalidate_update_cache():
    +    """Delete the update-check cache so ``hermes --version`` doesn't
    +    report a stale "commits behind" count after a successful update."""
    +    try:
    +        cache_file = Path(os.getenv(
    +            "HERMES_HOME", Path.home() / ".hermes"
    +        )) / ".update_check"
    +        if cache_file.exists():
    +            cache_file.unlink()
    +    except Exception:
    +        pass
     
     def cmd_update(args):
         """Update Hermes Agent to the latest version."""
    ```

    ```diff
    @@ -2197,6 +2207,7 @@ def cmd_update(args):
             commit_count = int(result.stdout.strip())
             
             if commit_count == 0:
    +            _invalidate_update_cache()
                 print("✓ Already up to date!")
                 return
             
    ```

    ```diff
    @@ -2217,6 +2228,8 @@ def cmd_update(args):
                         prompt_user=prompt_for_restore,
                     )
             
    +        _invalidate_update_cache()
    +        
             # Reinstall Python dependencies (prefer uv for speed, fall back to pip)
             print("→ Updating Python dependencies...")
             uv_bin = shutil.which("uv")
    ```
- **#20792: fix(banner): bind update-check cache to local HEAD so banner refreshes after hermes update (#20728)**. closed without merge · fix tier `suggested`
  - maintainer direction: category `superseded_by_pr`; implication `superseded`; refs `#20653`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#22256: Fix stale update cache invalidation for custom HERMES_HOME**. closed without merge · fix tier `suggested`
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`; refs `4a65c9cd08cc3ea27ea4e221a5aca71161428c90`, `#21526`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#23700: fix(update): show pending commit list in --check output and banner**. closed without merge · fix tier `suggested`
  - maintainer direction: category `uncategorized`; implication `needs_llm`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#34846: feat(cli): warn on unsupported pip installs + fix stale update-check cache (#34491)**. merged to main · fix tier `verified`
  - maintainer direction: category `merged`; implication `superseded`
  - files: `hermes_cli/banner.py`, `tests/hermes_cli/test_pip_install_detection.py`, `tests/hermes_cli/test_update_check.py`, `website/docs/user-guide/features/code-execution.md`
- **#38103: fix(version): bump main branch to 0.15.2 to match latest release tag v2026.5.29.2**. closed without merge · fix tier `suggested`
  - maintainer direction: category `uncategorized`; implication `needs_llm`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#11329: fix: invalidate update cache in _update_via_zip path (#11327)**. open
  - maintainer direction: category `uncategorized`; implication `needs_llm`
  - files: `hermes_cli/main.py`
- **#11451: Fix stale update cache after successful updates**. closed without merge
  - maintainer direction: category `uncategorized`; implication `needs_llm`
- **#21447: fix: invalidate stale update-check cache**. closed without merge
  - maintainer direction: category `duplicate_of`; implication `duplicate`; refs `#18236`, `#9670`, `#5359`, `#11327`, `#21675`
- **#23259: fix(update): clear update cache under custom HERMES_HOME**. closed without merge
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`; refs `4a65c9cd08cc3ea27ea4e221a5aca71161428c90`, `#22256`, `#21526`
- **#23699: fix: don't cache failed update checks; sync cache on explicit --check**. open
  - maintainer direction: category `uncategorized`; implication `needs_llm`
  - files: `hermes_cli/banner.py`, `hermes_cli/main.py`
- **#27844: fix(update): key update-check cache by git HEAD**. open
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`; refs `9f4cd99743653a2fb9ec7d21a3f10b4ef89af975`
  - files: `hermes_cli/banner.py`, `tests/hermes_cli/test_update_check.py`
- **#34501: fix(cli): invalidate update-check cache when installed version changes**. closed without merge
  - maintainer direction: category `superseded_by_pr`; implication `superseded`; refs `689ef5e23`, `#34846`, `#34491`, `#34491`
- **#38619: fix: bump version from 0.15.1 to 0.15.2 to match release tag v2026.5.29.2**. closed without merge
  - maintainer direction: category `duplicate_of`; implication `duplicate`; refs `#38103`
- **#39776: fix(version): suppress false 'commits behind' warning on detached HEAD (tag checkout)**. open
  - maintainer direction: category `uncategorized`; implication `needs_llm`; refs `226e8de82`
  - files: `hermes_cli/banner.py`, `tests/hermes_cli/test_update_check.py`
- **#40985: fix(banner): invalidate update-check cache when local git HEAD moves**. closed without merge
  - maintainer direction: category `silent_close`; implication `active`
- **#40999: fix: invalidate update cache using local HEAD (fixes #40944)**. open
  - maintainer direction: category `uncategorized`; implication `needs_llm`
  - files: `hermes_cli/banner.py`, `tests/hermes_cli/test_update_check.py`
- **#41012: fix(cli): invalidate update cache when source HEAD changes**. open
  - maintainer direction: category `uncategorized`; implication `needs_llm`
  - files: `hermes_cli/banner.py`, `tests/hermes_cli/test_update_check.py`
- **#41043: fix(cli): bust update-check cache when local HEAD moves**. open
  - maintainer direction: category `wontfix_bydesign`; implication `wontfix`
  - files: `hermes_cli/banner.py`, `tests/hermes_cli/test_update_check.py`
- **#43824: fix: clarify update status for branch and tag checkouts**. open
  - maintainer direction: category `uncategorized`; implication `needs_llm`
  - files: `hermes_cli/banner.py`, `hermes_cli/main.py`
- **#107496: feat(update): support configurable stable branch tracking**. closed without merge
  - maintainer direction: category `partial_fix`; implication `needs_llm`; refs `b0c7613b47b6c1678f50e6ab35dc92103d15075f`, `38c9611791d3c8eccee5bb3fdad8075ec1d58565`, `#58746`, `#58746`, `#58746`, `#58746`
- **#113278: feat(update): stable-release default channel with install-scoped record and Desktop selector**. closed without merge
  - maintainer direction: category `uncategorized`; implication `needs_llm`

## Fix status

- Merged to main in PR #1637 (cited above). No release data is tracked. Verify downstream.
- Fix last verified (merged) `2026-05-29`.
- Subsystem: `apps/desktop`