feat(checkpoints): v2 single-store rewrite with real pruning + disk guardrails

[teknium1]

Summary

Fixes the open-ended growth of ~/.hermes/checkpoints/. Single shared shadow git store replaces per-directory repos, _prune() actually prunes, and a new hermes checkpoints CLI surfaces size + cleanup.

On one active machine: 847 MB across 47 shadow repos, mostly redundant clones of the same source tree. v2 dedups objects across projects; after a size-cap pass that collapses into a fraction of the old footprint.

Root cause (three compounding problems)

1. Each working directory got its own full shadow git repo — no object dedup across projects or across worktrees of the same project.
2. _prune() was a documented no-op: max_snapshots only capped the /rollback listing. Loose objects accumulated forever.
3. Defaults enabled: True + auto_prune: False meant users paid the disk cost without ever opting into /rollback.

Architecture (v2)

~/.hermes/checkpoints/
  store/                          single bare git repo (objects dedup across all projects)
    HEAD, objects/, refs/         git internals (shared)
    refs/hermes/<hash>            per-project branch tip
    indexes/<hash>                per-project git index (GIT_INDEX_FILE)
    projects/<hash>.json          {workdir, created_at, last_touch}
    info/exclude                  default excludes (shared)
  .last_prune                     auto-prune idempotency marker
  legacy-<ts>/                    archived pre-v2 per-project shadow repos

Migration: on first v2 init, any pre-existing per-directory shadow repos are renamed into legacy-<timestamp>/ so the new store starts clean. No in-place data migration. Users can still inspect the archive with git if they need old /rollback history; hermes checkpoints clear-legacy reclaims the space when ready.

Changes

• tools/checkpoint_manager.py — full rewrite. Per-project refs + indexes + metadata inside one shared bare repo. _prune() actually rewrites the ref to the last max_snapshots commits and runs git gc --prune=now. New _enforce_size_cap() drops oldest commits round-robin across projects when the store exceeds max_total_size_mb. New _drop_oversize_from_index() filters files larger than max_file_size_mb out of snapshots. New helpers for CLI: store_status(), clear_all(), clear_legacy().
• hermes_cli/checkpoints.py — new hermes checkpoints CLI (status / list / prune / clear / clear-legacy) for managing the store outside a session.
• hermes_cli/config.py — flipped defaults: enabled: True → False, max_snapshots: 50 → 20, auto_prune: False → True. Added max_total_size_mb: 500 and max_file_size_mb: 10. Tightened DEFAULT_EXCLUDES (added target/, *.so/*.dylib/*.dll, *.mp4/*.mov, *.zip/*.tar.gz, .worktrees/, .mypy_cache/, .ruff_cache/, etc.).
• run_agent.py / cli.py / gateway/run.py — thread new kwargs through AIAgent and the startup auto-prune hooks.
• tests/tools/test_checkpoint_manager.py — rewritten for v2 semantics. Keeps backwards-compat coverage for the pre-v2 prune path so anyone mid-migration still gets cleaned up.
• website/docs — user guide and CLI reference updated for new defaults, migration, and the new CLI.

Validation

Targeted tests: tests/tools/test_checkpoint_manager.py — 73/73 passing.
Adjacent: tests/tools/ and tests/tui_gateway/ clean. tests/hermes_cli/ and tests/run_agent/ failures are all pre-existing on main (confirmed via stash test).

E2E (real git, real file I/O, isolated HERMES_HOME):

Check	Result
Legacy migration: pre-v2 shadow repos auto-archived into legacy-<ts>/	✓
Object dedup: 2 projects sharing identical blob → 7 total objects in store	✓
max_snapshots=3 actually enforced after 6 commits	✓ (list returns 3)
Orphan prune: deleted workdir → ref + index + metadata all wiped	✓
max_file_size_mb=1 excludes a 2 MB binary while keeping source files	✓
hermes checkpoints {status,prune,clear,clear-legacy}	✓ all work

Behavior change notice for users

Anyone currently relying on /rollback must now opt in explicitly:

# ~/.hermes/config.yaml
checkpoints:
  enabled: true

or pass hermes chat --checkpoints. The rationale: most users never invoke /rollback, and the v1 store grew unboundedly. The feature is fully functional — just not the default.

Existing ~/.hermes/checkpoints/<hash>/ shadow repos are moved into legacy-<timestamp>/ on first v2 run and will be auto-pruned by auto_prune after retention_days (default 7).