fix(updates): fall through to branch check when HEAD is past latest tag (#2653)

[munim]

Closes #2653

Thinking Path

• Hermes WebUI aims for near 1:1 parity with the Hermes CLI in a browser
• The update checker uses two strategies: release-tag gap first, branch commit-count as fallback
• _check_repo_release wins whenever v* tags exist — even when HEAD has moved past the latest tag
• The bug: current_tag == latest_tag → behind=0 → green Up to date ✓ pill, regardless of how many commits master has accumulated since the tag
• Three independent user reports (Deor, huhu1030, Maheśvara) all describe the same symptom: the agent checkout shows v2026.5.16-593-gedb2d9105 yet the badge stays green
• The fix is to detect the -N-gSHA suffix on git describe --tags --always when behind==0; if present, return None from _check_repo_release so _check_repo_branch runs and counts the real gap via rev-list

What Changed

api/updates.py — _check_repo_release(), ~10 LOC:

After computing behind == 0, run git describe --tags --always. If the
output differs from current_tag (i.e. has a -N-gSHA suffix), return
None. _check_repo then falls through to _check_repo_branch which
counts commits between HEAD and origin/<branch> and reports the real gap.

When HEAD is exactly on the latest tag the new branch is never taken;
behaviour is unchanged for repos (like WebUI) that tag on every release.

tests/test_updates.py — 3 new tests:

• test_check_repo_release_falls_through_when_head_is_past_tag — unit: release check returns None for a post-tag HEAD
• test_check_repo_release_not_affected_when_head_exactly_on_tag — regression: exact-tag HEAD still returns behind: 0
• test_check_repo_branch_check_runs_for_post_tag_commits — end-to-end: mirrors the exact huhu1030 scenario (v2026.5.16-608-g…) and asserts behind=608

Why It Matters

"Up to date ✓" is actively misleading — worse than a missing banner,
because users trust the green checkmark. Deor, huhu1030, and Maheśvara
all stopped relying on the in-app banner and fell back to manual git pull.

Verification

pytest tests/test_updates.py -v           # 14 passed
pytest tests/test_update_banner_fixes.py tests/test_update_checker.py \
       tests/test_update_check_ui.py tests/test_update_apply_ui.py -v  # 87 passed

All pre-existing update tests pass unchanged.

Risks / Follow-ups

• The fix adds one extra git describe call per update check cycle when a repo has tags and behind==0. Fast local op (<10 ms), runs at most twice per 30-min TTL window — no meaningful overhead.
• Option B from the issue (combining both signals into a single behind value) is more thorough but requires more surface area. This fix (Option A) is minimal and addresses all three reported cases.
• No changes to the UI, the API response shape, or any other module.

Model Used

• Provider: GitHub Copilot / Anthropic
• Model: github-copilot/claude-sonnet-4.6
• Mode: OpenCode interactive CLI with Karpathy guidelines (caveman mode)

[nesquena-hermes]

Reading api/updates.py:374-401 on origin/master and the diff at this PR head — the fix is precise and minimal. Walking through it:

_check_repo (line 473) calls _check_repo_release first; if it returns non-None the release-based result wins. The bug is at line 381–386 on master:

def _check_repo_release(path, name):
    tags = _release_tags(path)
    if not tags:
        return None
    latest_tag = tags[0]
    current_tag = _current_release_tag(path)
    behind = _release_gap(tags, current_tag, latest_tag)
    # ... build release_info dict with behind=0, return it

_current_release_tag (line 339) is git describe --tags --abbrev=0, which strips any -N-gSHA suffix. So current_tag == latest_tag == "v2026.5.16" even when HEAD is hundreds of commits past v2026.5.16. _release_gap returns 0, the release-based dict goes out the door, and the UI shows the green "Up to date" pill.

This PR's added lines short-circuit on the suffix:

if behind == 0:
    full_desc, ok = _run_git(['describe', '--tags', '--always'], path)
    if ok and full_desc and full_desc != current_tag:
        return None

_check_repo then falls through to _check_repo_branch(path, name, fetch=False) (line 509), which counts the real commit gap via rev-list --count. That's the right layering — release detection stays the primary path for tagged-only consumers (WebUI), and the agent repo's between-tag commits get reported through the branch fallback instead of being silently zeroed.

Correctness checks

• Exact-tag HEAD: git describe --tags --always returns the bare tag name, so full_desc == current_tag, the new branch is skipped, behaviour unchanged. The second test (test_check_repo_release_not_affected_when_head_exactly_on_tag) covers this.
• HEAD past tag with no tags: _release_tags(path) returns [] and we return None before any of this runs — also unchanged.
• Fetch-failure path at api/updates.py:489-497 builds a stale release_info before the new logic gets a chance to run, so a stale "Up to date" can still slip through when origin is unreachable. That's a pre-existing edge and probably acceptable: when fetch fails, the UI already shows the stale_check: True flag.

Test coverage

The three new tests in tests/test_updates.py are well-scoped: one isolates _check_repo_release in the past-tag case, one covers the exact-tag regression, and the end-to-end test_check_repo_branch_check_runs_for_post_tag_commits mirrors the actual #2653 reproduction (v2026.5.16-608-g1d22b9c2d, asserts behind=608). Mocking _run_git at the boundary is the right depth.

Cost

One extra git describe --tags --always call per cache-miss when both _release_tags(path) is non-empty and behind == 0. That's a local git op (< 10 ms), gated by the 30-min CACHE_TTL, only runs for repos that have tags but where HEAD has passed the latest one. Practical impact for WebUI is essentially zero (WebUI tags every release, so HEAD lands on a tag); the agent repo pays the cost once per TTL window.

Suggestions

• Worth checking what the resulting compare URL looks like in the UI when the fallback fires. _check_repo_branch builds compare/<merge-base>...<HEAD> rather than tag-to-tag, which is the right thing for a tagless gap — just confirming the existing branch-check format renders cleanly when the release-check would have linked tags.
• The PR body mentions Option B (combine both signals into a single behind value). Option A is the right call here — it's a one-line behavioural rebalance with zero new state, and the branch fallback already exists for exactly this case. Don't expand the surface.

LGTM for merge after the standard review pass. Cross-link from #2653 once it merges so the three user reporters (Deor, huhu1030, Maheśvara) can git pull and confirm.

[nesquena-hermes]

Shipped in v0.51.120 via release/stage-batch2 (#2810). The post-tag fall-through is in — agent-cadence repos will now correctly report commits-behind instead of false 'Up to date'. Thanks for the 8 new edge-case tests. Resolves #2653.