docs(hermes-agent): v0.13 -> v0.12 rollback runbook

[Ghenghis]

Summary

Operator-runnable runbook to flip Hermes3D OS from v0.13 (current default after Wave 1) back to v0.12 (G:/Github/hermes-agent-fresh) in under 60 seconds. Builds on the per-call resolver shipped in PR #155 (8544bbc) and provides a PR-level revert escape hatch for PR #160 (3158a4e) if the env-flip alone is insufficient.

Lives at 03_implementation/docs/runbooks/HERMES_AGENT_V013_ROLLBACK.md.

Sections shipped

1. When to use - 5 symptom triggers (provider 5xx, runtime crash, security regression, BLK-013 sandbox-escape suspicion, outdated provider auth) with diagnostic SQL.
2. Mid-process flip - Windows Service / NSSM, systemd drop-in override, docker / docker-compose, bare uvicorn --env-file, plus a 2.5 fallback for hosts that block all four. Anchored on 12-Factor Rule III.
3. Verification - the 3 commands required by the brief (curl /api/agents/update/status, python -c hermes_agent_checkout(), git -C G:/Github/hermes-agent-fresh rev-parse HEAD) with expected values.
4. DB cleanup - SELECT/UPDATE/INSERT against agent_config and proof_events (hermes_agent.update.last_run, hermes_agent.update.last_rollback, hermes_agent.update.latest_backup) that mark v0.13 rows as superseded WITHOUT deletion, preserving the proof chain.
5. PR-level revert - git revert -m 1 3158a4e onto a hotfix/* branch through the release gateway (per the existing 06_release/ROLLBACK_RUNBOOK.md flow).
6. Re-promotion - unset env var (env-flip path) OR revert-the-revert PR (PR-revert path), each with the proof_events row the operator must append.
   Appendix A - one-page emergency card.

Sources cited

• 12-Factor App Rule III - Config: https://12factor.net/config
• Docker run --env: https://docs.docker.com/reference/cli/docker/container/run/#env
• FastAPI / uvicorn --reload warning: https://fastapi.tiangolo.com/deployment/manually/
• Repo: 06_release/ROLLBACK_RUNBOOK.md, agent_checkout.py, agent_updates.py

Test plan

• Reviewer: confirm Section 3 verification commands match the running endpoint signature in 03_implementation/src/hermes3d/api/routes/agent_updates.py
• Reviewer: confirm Section 4 SQL keys match hermes_agent.update.last_run / last_rollback / latest_backup writes
• Reviewer: confirm Section 5 revert recipe (git revert -m 1 3158a4e) matches the squash-merge mainline parent

Hermes evidence chain: PASS
Task ID: P1-6
hermes_run_gate: docs-rollback-runbook
hermes3d-locks lock: claude-p1-6 / 8136730b5277d65e236275be

Out of scope

• Actual recovery loop / Tenacity adapter changes (handled in the Hermes Agent Recovery Controller lane)
• v0.13 hard-gate re-runs (already documented in PR feat(hermes-agent): promote v0.13 to production default (Wave 1 P1-5; 7/7 gates green) #160's commit body)

Co-Authored-By: Claude Opus 4.7 (1M context)

Generated with Claude Code

[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: 1bc272f1-ba7c-4268-9de9-1bbc3cc178f2

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/v013-rollback-runbook

---

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