feat(hermes-agent): version registry for v0.12 + v0.13 (Wave 2 P2-1)

[Ghenghis]

Summary

• Adds services/agent_version_registry.py — a frozen-dataclass registry of known Hermes Agent versions (v0.12 @ v2026.4.30, v0.13 @ v2026.5.7) with their feature flags. Pairs with agent_checkout.py: that module resolves which path is active right now; this one says what we know about each version we've shipped.
• active_version() reads the live checkout via hermes_agent_checkout() so per-call env-flips (PR feat(hermes-agent): canary env-switch resolver (Wave A4 + A5 combined) #155 / Wave A5) propagate, and returns None if the operator points HERMES_AGENT_CHECKOUT at an unknown custom fork.
• Read-only on agent_checkout.py. Imports DEFAULT_AGENT_CHECKOUT, V012_FALLBACK_CHECKOUT, hermes_agent_checkout only.

Why a separate module

agent_checkout.py answers which path is live; downstream callers (compat matrix, proof-event tagger, rollback UI) need what we know about each version. Keeping that metadata in its own frozen-record module:

• Makes feature-gating explicit (if active_version().has_kanban: ...) instead of string-matching paths.
• Survives operator env flips because active_version() re-reads the checkout per-call.
• Cannot leak state across callers (frozen dataclass; __setattr__ raises FrozenInstanceError).

Required surface

Symbol	Status
HermesAgentVersion(label, upstream_tag, checkout_path, venv_python, redaction_default_on, has_kanban, has_heartbeat_reclaim, has_zombie_detection, has_pluggable_providers_dir)	shipped, frozen=True
V012, V013 (module constants)	shipped
KNOWN_VERSIONS: tuple[HermesAgentVersion, ...]	shipped (order: V012, V013)
active_version() -> HermesAgentVersion | None	shipped, returns None for unknown paths

Pinned facts (each pinned by a test)

Fact	Source
v0.12 upstream tag = v2026.4.30	Wave 1 promotion brief
v0.13 upstream tag = v2026.5.7 ("Tenacity Release")	Wave 1 promotion brief
v0.13 redaction_default_on=True	NousResearch/hermes-agent#21193, Wave A3 verified
v0.12 redaction_default_on=False	Wave 2 prior swarm Agent 2 finding
v0.13 ships kanban + heartbeat-reclaim + zombie-detection + plugins/model-providers/	Wave 1 candidate snapshot
active_version() defaults to v0.13 with env unset	post PR #160 default
active_version() returns v0.12 when HERMES_AGENT_CHECKOUT=G:/Github/hermes-agent-fresh	per-call env semantics
active_version() returns None for unknown paths	resolver fallthrough

Persistence note

Feature flags here are static booleans per shipped version. If a future feature is conditionally available (e.g. only present when an extra is installed), do not mutate these frozen records — open a follow-up next_fix_attempt issue and add the flag once the conditional is resolved at instance construction.

Constraint compliance

• Source: 89 file lines, 67 non-blank/non-comment LoC (target ≤80).
• Tests: 114 lines, 13 cases (target ~80).
• No edits to existing files. Only ADDs the 2 new files.
• Online research: Python dataclasses frozen-instance docs + Django AppConfig registry pattern (cross-comparison) — both cited inline in the module docstring.
• No secret values; venv_python typed Path | None, never strings.
• MCP locks held for both new files (33eb9592..., a37b5c7b...); released after PR open.

Test plan

• pytest 04_testing/pytest/unit/test_agent_version_registry.py — 13/13 pass in 0.08s
• pytest 04_testing/pytest/unit/test_agent_checkout_resolver.py 04_testing/pytest/unit/test_agent_version_registry.py — 24/24 pass in 1.54s (no resolver regression)
• Pre-push hook ran the project's fast-suite, all green
• CI mech-review check (auto-runs on PR open)

Hermes evidence chain: PASS

• Task ID: a2a_p2_1_version_registry
• hermes_run_gate: pending CI
• MCP locks: acquired (33eb9592..., a37b5c7b...); will release after PR opens

Handoff

• P2-5 (compat matrix) reads KNOWN_VERSIONS to render the "feature × version" capability table.
• P2-6 (version-tagged proof events) reads active_version().label and active_version().upstream_tag to add a version_tag field on every proof event so post-mortem can rebuild what version produced what evidence.

Source links

• Python @dataclass(frozen=True) semantics: https://docs.python.org/3/library/dataclasses.html#frozen-instances
• Django AppConfig per-app metadata + registry pattern (cross-comparison): https://docs.djangoproject.com/en/5.1/ref/applications/
• 12-Factor III config (the per-call env discipline this preserves): https://12factor.net/config

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 475c0ff6-2eab-4196-93f8-cc007fc1f656

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/agent-version-registry

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}