feat(update): add --release to pin tagged releases (#34514)

[hustshawn]

Summary

Adds hermes update --release [TAG] to pin an install to a tagged release instead of tracking a branch tip.

• hermes update --release / --release latest → install the newest vYYYY.M.D tag
• hermes update --release v2026.5.29 → pin to that exact tag
• hermes update --check --release [TAG] → report without installing
• The tag is checked out as a detached HEAD, so the pin survives across runs

Fixes the core complaint in #34514 that a tag-pinned (detached-HEAD) install gets forced back onto main by hermes update: when --release is used we skip the branch-switch entirely and land on the tag, and we never drag a pin forward to upstream/main.

Relationship to #24938

This is complementary to @Sunwo0u's #24938 (opt-in --channel {main,release}), not a replacement. That PR adds a "track the latest release" channel; this PR adds specific-tag pinning and the respect-the-pin / detached-HEAD behavior the issue asks for. The two can land independently or together — there's no overlap in flags (--channel vs --release).

Behavior & safety

• Non-breaking: with no --release flag the code path is byte-for-byte the historical branch-tracking behavior. Default is unchanged.
• Reuses the existing post-pull syntax guard + auto-rollback (the PR feat(kanban): stale detection for running tasks in dispatcher (#23790) #28452 incident guard) on the release path — a bad tag still rolls back cleanly.
• Pre-update snapshot/backup, dependency reinstall, skills sync, config migration and gateway restart all run unchanged after the checkout.
• --release and --branch are mutually exclusive (clear error rather than silent precedence).
• The Windows ZIP fallback refuses --release (it can't honor a tag pin reliably), mirroring how it already refuses --branch=<non-main>.

Implementation

• Helpers: _resolve_release_request, _latest_release_tag (version-sorted), _tag_exists, _head_is_at_or_after.
• _cmd_update_impl: resolve the target tag after a --tags fetch, skip branch-switch for pins, git checkout --detach <tag>, reuse the guard/rollback.
• _cmd_update_check_release for the --check --release reporting path.

Test plan

• python -m pytest tests/hermes_cli/test_cmd_update.py -q → 30 passed (21 pre-existing + 9 new)
• Related suites green: test_update_autostash.py, test_update_yes_flag.py, test_cmd_update_docker.py, test_update_concurrent_quarantine.py
• End-to-end smoke against this repo's real tags:
  • update --check --release → "Already on release v2026.5.29"
  • update --check --release v9999.1.1 → "Release tag 'v9999.1.1' not found"
• New tests cover: flag parsing (absent/bare/blank/explicit), latest-pin detached checkout, specific-tag pin, already-installed short-circuit, unknown-tag exit, and --release/--branch mutual exclusion.

Refs #34514. Complements #24938.

[teknium1]

Thanks for implementing the explicit release-pin path. The underlying problem is still present on current main: a detached checkout is switched to the default update branch at hermes_cli/main.py:9633-9647, and tests/hermes_cli/test_update_autostash.py:625-639 covers that behavior.

Problems

• hermes_cli/main.py:9232 treats any descendant of the requested tag as already pinned. On main after vX, merge-base --is-ancestor vX HEAD succeeds and returns before the proposed detached checkout, so --release vX cannot downgrade/pin exactly as documented.
• The implementation targets an older update layout. Current main registers the parser in hermes_cli/subcommands/update.py:12-76 and the live flow has newer scoped-fetch, Windows, venv-health, and interrupted-install handling at hermes_cli/main.py:9584-9978.
• The public update docs would need the release behavior documented; current pages only document --branch (website/docs/getting-started/updating.md:34-43, website/docs/reference/cli-commands.md:1542-1558).

Suggested changes

• Use exact HEAD/tag identity, not ancestry, for the already-pinned fast path.
• Rework the feature onto the current parser and update flow, then add descendant-of-tag and current-path coverage.

Automated hermes-sweeper review.

[teknium1]

This ancestry check makes --release vX a no-op whenever HEAD is a descendant of vX (for example, main after that release). Exact pinning needs an identity comparison against the peeled tag target; otherwise the later detached checkout is skipped.