Checkpoints V2: add retention-based cleanup for v2 transcript generations in entire clean

[pfleidi]

Summary

• Add entire clean --all support for deleting archived v2 transcript generations past the configured retention window (default 60 days)
• Warn on malformed generations (missing metadata, invalid timestamps) instead of silently skipping or deleting them
• Use git update-ref -d via CLI instead of go-git's RemoveReference to handle packed refs correctly
• Add compare-and-swap OID binding to ref deletion, preventing TOCTOU data loss if a ref is repointed between enumeration and deletion
• Add GetFullTranscriptGenerationRetentionDays() settings helper
• Gate v2 cleanup help text in entire clean --help behind the checkpoints_v2 feature flag

Detail

Archived /full/* generation refs accumulate over time as transcript data is rotated. This PR adds a cleanup path gated behind the checkpoints_v2 feature flag and the full_transcript_generation_retention_days setting.

Safety invariants:

• Generations within the retention window are preserved
• Malformed generations (missing generation.json, incomplete timestamps, inverted timestamps) are skipped with warnings to stderr
• Ref deletion uses compare-and-swap: the OID observed at listing time is threaded through CleanupItem → V2GenerationRef → DeleteRefCLI, so git update-ref -d <ref> <old-oid> refuses deletion if the ref was repointed between enumeration and deletion
• go-git's RemoveReference is replaced with git update-ref -d via CLI to handle packed refs correctly (same class of go-git v5 bug as checkout/reset)

Test plan

• mise run check passes (fmt + lint + unit + integration tests)
• TestCleanCmd_All_ForceDeletesEligibleV2Generations — happy path deletion
• TestCleanCmd_All_DryRunSkipsV2GenerationsWithinRetention — retention preserved
• TestCleanCmd_All_ForceSkipsV2GenerationMissingMetadata — malformed skipped with warning
• TestCleanCmd_All_ForceSkipsV2GenerationWithInvalidTimestamps — invalid timestamps skipped
• TestDeleteRefCLI_DeletesPackedCustomRef — packed ref deletion works
• TestDeleteRefCLI_RejectsOIDMismatch — CAS rejects stale OID
• TestGetFullTranscriptGenerationRetentionDays — settings helper
• TestCleanLongDescription_DefaultIsGeneric — help text without v2
• TestCleanLongDescription_IncludesV2CleanupWhenEnabled — help text with v2

---

Note

Medium Risk
Touches repo-cleanup and git ref-deletion paths; while guarded by feature flag, retention checks, and OID compare-and-swap, bugs could still lead to unintended ref cleanup or missed deletions.

Overview
entire clean --all now (when checkpoints_v2 is enabled) enumerates archived checkpoints v2 /full/* generations and deletes only those older than a configurable retention window, emitting warnings (to stderr) for malformed/unreadable generations instead of deleting them.

Cleanup plumbing is extended with a new v2-generation cleanup type that carries an observed ref OID through listing to deletion, and introduces DeleteRefCLI (via git update-ref -d) with optional compare-and-swap semantics to reliably and safely delete packed refs. The clean help text is updated to mention v2 cleanup only when the feature flag is enabled, and output formatting is refactored for clearer sectioned previews/results.

Adds settings.GetFullTranscriptGenerationRetentionDays() (default 60) plus comprehensive CLI/strategy/settings tests covering retention behavior, warnings, packed-ref deletion, and OID mismatch protection.

^{Reviewed by Cursor Bugbot for commit 70ab784. Configure here.}

[Copilot]

Pull request overview

Adds retention-based cleanup for archived checkpoints v2 “/full/*” transcript generations to the existing entire clean --all flow, with safety guards (malformed generation warnings, packed-ref-safe deletion, and compare-and-swap ref deletion) and settings support.

Changes:

• Add DeleteRefCLI (CAS-capable) for reliable custom-ref deletion via git update-ref -d, plus new error types.
• Add v2 generation eligibility listing + deletion to cleanup strategy, driven by a retention-days setting.
• Update clean command help/output and add tests for v2 cleanup behavior and settings parsing.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
cmd/entire/cli/strategy/common.go	Adds DeleteRefCLI and new ref-related errors for CLI-based deletion with optional OID CAS.
cmd/entire/cli/strategy/cleanup.go	Introduces listing/deleting eligible archived v2 generations and threads ref OIDs through cleanup items/results.
cmd/entire/cli/strategy/clean_test.go	Adds unit tests covering packed-ref deletion and OID mismatch rejection for DeleteRefCLI.
cmd/entire/cli/settings/settings.go	Adds GetFullTranscriptGenerationRetentionDays() with a default retention window.
cmd/entire/cli/settings/settings_test.go	Adds tests for retention-days settings parsing/defaulting behavior.
cmd/entire/cli/clean.go	Gates v2 cleanup help text behind checkpoints_v2, lists eligible v2 generations in --all, and reports results.
cmd/entire/cli/clean_test.go	Adds command-level tests for v2 generation cleanup behaviors (retention, malformed metadata warnings, deletion).

[pfleidi]

Bugbot run

[pfleidi]

Bugbot run

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 70ab784. Configure here.}

[gtrrz-victor]

Tested and it's working!! 🦾