Fall back to v1 checkpoint transcripts for v2 reads

[pfleidi]

https://entire.io/gh/entireio/cli/trails/384

What

• Centralize committed checkpoint reader selection behind the shared reader factory.
• Use DualCheckpointReader for v2 dual-read mode so missing v2 full transcript artifacts fall back to v1 raw artifacts.
• Keep v2 compact transcript reads v2-only, with callers falling through to the shared raw-content path when v2 compact metadata is unavailable.

Verification

• mise run build
• mise run lint
• mise run test:ci:core
• mise run test:ci:integration:shard -- b

E2E canary was left to CI because this branch does not change e2e prompts or agent-facing canary behavior.

---

Note

Medium Risk
Changes core checkpoint read-selection and transcript retrieval paths across explain, resume, rewind, and strategy restore flows; risk is mainly around subtle fallback/error-handling differences in mixed v1/v2 repos.

Overview
Centralizes committed checkpoint reading behind a new mode-based factory (CommittedReadV1/Dual/V2) and introduces DualCheckpointReader that reads v2 first but falls back to v1 for summaries, session content, metadata, and listing.

Fixes missing v2 full-transcript artifacts by making dual-mode session reads fall back to v1 raw transcripts using the v2 session ID, while keeping v2-only compact transcript reads and adding explicit fall-through to raw transcripts when compact content is unavailable.

Refactors CLI call sites to use the shared reader (newCommittedCheckpointReader) and new helpers (ReadCommittedCheckpoint, ReadLatestSessionContent, ReadRawSessionLogForCheckpoint), removing bespoke v1/v2 resolution/merge logic and adding coverage for v1 fallback and transcript-offset correctness.

^{Reviewed by Cursor Bugbot for commit 6a4e043. Configure here.}

[Copilot]

Pull request overview

This PR centralizes the selection of committed checkpoint readers behind a new shared factory (NewCommittedReader / committedCheckpointReadMode) and introduces a DualCheckpointReader that, when v2 dual-read mode is active, transparently falls back from v2 to v1 raw transcript artifacts (e.g., when only v2 compact transcripts exist but v2 /full/* is missing). Compact transcript reads remain v2-only, with callers routed back through the raw-content path when compact metadata is unavailable.

Changes:

• Add CommittedReadMode, NewCommittedReader, DualCheckpointReader, ReadCommittedCheckpoint, ReadLatestSessionContent, and ReadRawSessionLogForCheckpoint helpers in checkpoint/committed_reader_resolve.go, plus a new cmd/entire/cli/checkpoint_reader.go factory used across callers.
• Refactor explain.go/explain_export.go/resume.go/rewind.go/review_helpers.go/review_context.go/manual_commit_rewind.go to use the new factory and reader, removing duplicated v1/v2 selection logic and replacing direct *V2GitStore type assertions with capability interfaces (v2MainContentReader, compactTranscriptReader).
• Add tests for dual-read fallback (compact-only v2 → v1 raw), mode selection, and list merging.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
cmd/entire/cli/checkpoint/committed_reader_resolve.go	Introduces CommittedReadMode, DualCheckpointReader, and shared read helpers; reworks ResolveCommittedReaderForCheckpoint/ResolveRawSessionLogForCheckpoint to route through them.
cmd/entire/cli/checkpoint/committed_reader_resolve_test.go	Adds coverage for mode selection, dual reader fallback to v1 raw by session ID, list merging, and v2-only no-fallback behavior.
cmd/entire/cli/checkpoint_reader.go	New CLI-side factory that builds v1/v2 stores plus a CommittedListReader per the resolved read mode.
cmd/entire/cli/explain.go	Switches to the shared reader/factory; replaces *V2GitStore type assertions with v2MainContentReader; removes local listCommittedForExplain / readLatestSessionContentForExplain helpers in favor of shared variants.
cmd/entire/cli/explain_export.go	Uses the shared reader and a compactTranscriptReader capability interface; adds raw fallback when compact transcript is missing; consolidates metadata-read switch.
cmd/entire/cli/explain_test.go / explain_export_test.go	Adds tests for v1 raw fallback when v2 /full/* is missing and updates listCommittedForExplain tests to use NewCommittedReader.
cmd/entire/cli/resume.go	Replaces inline v2/v1 GetSessionLog logic with the shared reader; falls back to LookupSessionLog only when the repo can't be opened.
cmd/entire/cli/resume_test.go	Adds a fake agent and a regression test for v1 fallback on resume when v2 has only a compact transcript.
cmd/entire/cli/rewind.go	Uses shared reader + ReadRawSessionLogForCheckpoint for session transcript restore.
cmd/entire/cli/review_context.go	Switches review-context lookup to shared reader; treats ErrCheckpointNotFound from v2 metadata/prompts as fall-through to ReadSessionContent.
cmd/entire/cli/review_helpers.go	Uses shared reader for HEAD review-checkpoint detection; drops bespoke v2URL/store wiring.
cmd/entire/cli/strategy/manual_commit_rewind.go	Removes local committedReader interface and inline v2-first logic in favor of cpkg.NewCommittedReader/ReadCommittedCheckpoint; tightens v2-only-mode error handling.

[pfleidi]

Bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

1 issue from previous review remains unresolved.

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

^{Reviewed by Cursor Bugbot for commit 0854f2b. Configure here.}

[pfleidi]

Bugbot run

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

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

^{Reviewed by Cursor Bugbot for commit 6a4e043. Configure here.}