Back to Signal Feed
CodeTracked since May 18, 2026

Add v1 fallback for missing v2 committed checkpoint transcripts

The PR refactors committed checkpoint reads to a shared factory-based flow (`newCommittedCheckpointReader`) and introduces `DualCheckpointReader` so CLI flows use one selection path while handling mixed-format checkpoints safely. Its key behavior is: v2 reads still take precedence, but if v2 full-transcript artifacts or v2-only compact transcript metadata are missing, the code falls back to existing v1 raw transcript/session artifacts.

CommittedReadV1DualCheckpointReadernewCommittedCheckpointReaderv1 checkpoint artifacts

What Happened

  • The PR refactors committed checkpoint reads to a shared factory-based flow (`newCommittedCheckpointReader`) and introduces `DualCheckpointReader` so CLI flows use one selection path while handling mixed-format checkpoints safely. Its key behavior is: v2 reads still take precedence, but if v2 full-transcript artifacts or v2-only compact transcript metadata are missing, the code falls back to existing v1 raw transcript/session artifacts.
  • The PR refactors committed checkpoint reads to a shared factory-based flow (`newCommittedCheckpointReader`) and introduces `DualCheckpointReader` so CLI flows use one selection path while handling mixed-format checkpoints safely. Its key behavior is: v2 reads still take precedence, but if v2 full-transcript artifacts or v2-only compact transcript metadata are missing, the code falls back to existing v1 raw transcript/session artifacts.
  • 1 evidence item attached for review.

What is Different

Before

Scattered source updates, isolated context, and manual follow-up across multiple feeds.

Now

Introduced a shared committed-checkpoint reader factory and explicit dual-mode fallback logic so `explain`, `resume`, `rewind`, and restore paths no longer depend on duplicated v1/v2 reader branching logic. The fix specifically restores session transcript reading for v2 reads by falling back to v1 raw transcript artifacts when v2 full-transcript or compact-transcript metadata is unavailable.

Why Track This

Why It Matters

Operators and developers using session restore paths on repositories with mixed checkpoint formats are less likely to hit missing-checkpoint failures, so recovery workflows stay usable even when v2 transcript files are incomplete or partially missing. The implementation now routes all committed checkpoint reads through one reader pipeline and a v2-first fallback strategy; watch for edge cases in mixed v1/v2 repos where artifact availability and session ID/offset mapping could still cause incorrect transcript selection.

Impact

Operators and developers using session restore paths on repositories with mixed checkpoint formats are less likely to hit missing-checkpoint failures, so recovery workflows stay usable even when v2 transcript files are incomplete or partially missing. The implementation now routes all committed checkpoint reads through one reader pipeline and a v2-first fallback strategy; watch for edge cases in mixed v1/v2 repos where artifact availability and session ID/offset mapping could still cause incorrect transcript selection.

What To Watch Next

  • Watch whether CommittedReadV1 becomes a repeated pattern.
  • Track follow-up changes around Code Repository Intelligence.
  • Compare future signals against this evidence trail.
  • Re-check risk flags: mixed_version_checkpoint_fallback_misroute, raw_vs_compact_transcript_selection_errors.
Open Topic TimelineOpen Technical EventOpen Original Sourcemixed_version_checkpoint_fallback_misroute / raw_vs_compact_transcript_selection_errors / session_id_offset_mismatch_after_fallback

Supporting Evidence

GITHUB PULL REQUESTHigh Trust

entireio/cli PR #1223: Fall back to v1 checkpoint transcripts for v2 reads

Centralizes committed checkpoint reader selection with a mode-based factory and uses DualCheckpointReader to read v2 first, then fall back to v1 raw session artifacts when needed.