feat: v2-aware explain with compact transcript support

[pfleidi]

Summary

The explain command had no v2 checkpoint awareness — it only read from the v1 metadata branch. With checkpoints_v2 enabled, checkpoints are dual-written to both stores, and explain needs to read from v2 to take advantage of the compact transcript format and to remain functional as v2 becomes the primary store.

• v2/v1 fallback resolution: explain --checkpoint resolves checkpoints from v2 first (when preferred), falling back to v1. Listing merges both stores so pre-v2 checkpoints remain discoverable by prefix during the transition period.
• Compact transcript display: v2 stores a normalized transcript.jsonl alongside the raw transcript. explain now prefers this compact format for human-readable output (default/verbose modes), producing cleaner intent extraction and transcript formatting. --full retains raw semantics. The compact override is applied after --generate so the summarizer always receives the raw transcript it expects.
• Dual-write summary generation: explain --generate writes summaries to both v1 (required) and v2 (best-effort). This required implementing V2GitStore.UpdateSummary.
• Compact transcript parsing: Centralized into transcript/compact/parse.go so both formatTranscriptBytes and extractPromptsFromTranscript can fall back to compact format when raw parsing fails.
• Prompt attribution consistency: PendingPromptAttribution (set during UserPromptSubmit but only moved to PromptAttributions during SaveStep) is now included in persisted prompt_attributions metadata, matching what calculateSessionAttributions actually uses. Without this, mid-turn commits (e.g., Codex) had inconsistent diagnostic metadata.

Test plan

• mise run fmt && mise run lint && mise run test:ci passes
• Unit tests for v2 explain resolution, compact transcript parsing, merged listing, summary dual-write, prompt attribution persistence
• Integration tests for v2-enabled fallback to v1 and v2-preferred dual-write checkpoint explain
• E2E canary (vogon + roger-roger) all green

---

Note

Medium Risk
Changes the explain --checkpoint data source selection and transcript rendering paths to prefer v2 with fallback to v1; mistakes could cause missing/incorrect output or regress summary persistence during the v2 migration.

Overview
Makes explain --checkpoint v2-aware by resolving committed checkpoints via a new CommittedReader abstraction and ResolveCommittedReaderForCheckpoint, preferring v2 when checkpoints_v2 is enabled but falling back to v1 on missing/corrupt v2 data (plus a similar resolver for raw transcript bytes).

Adds v2 read capabilities needed by explain: V2GitStore.ListCommitted, /main-only reads via ReadSessionMetadataAndPrompts and ReadSessionCompactTranscript, and v2 summary persistence via V2GitStore.UpdateSummary (with --generate persisting to v1 and best-effort to v2).

Improves default explain output for v2 by using the compact transcript.jsonl from /main (avoiding /full/* raw transcript fetch/rotation issues), and introduces a shared compact transcript parser (transcript/compact) as a fallback for intent extraction and transcript formatting. Also fixes persisted prompt attribution diagnostics to include PendingPromptAttribution for mid-turn commits.

Adds extensive unit + integration coverage for v2/v1 listing+resolution behavior, compact transcript parsing, and summary/attribution persistence.

^{Reviewed by Cursor Bugbot for commit 7119e1f. Configure here.}

[cursor]

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

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Silent v1 error drops pre-v2 checkpoints from listing
  • Added a v1 error check in the v2-success merge path so v1 listing failures now surface instead of silently dropping pre-v2 checkpoints.

Or push these changes by commenting:

@cursor push d94b37b032

Preview (d94b37b032)

diff --git a/cmd/entire/cli/explain.go b/cmd/entire/cli/explain.go
--- a/cmd/entire/cli/explain.go
+++ b/cmd/entire/cli/explain.go
@@ -368,6 +368,9 @@
 		}
 		return v1Committed, nil
 	}
+	if v1Err != nil {
+		return nil, fmt.Errorf("listing checkpoints: %w", v1Err)
+	}
 
 	// Merge: start with v2, add v1-only entries so pre-v2 checkpoints
 	// remain visible during the transition period.

_{This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.}

[Copilot]

Pull request overview

Updates the explain command to be checkpoint v2-aware, including v2→v1 fallback resolution and preferential use of v2’s compact transcript format to keep explain functional and readable during the v1→v2 transition.

Changes:

• Added v2-first (with v1 fallback) checkpoint resolution and merged v1/v2 committed listing for prefix discovery.
• Prefer v2 transcript.jsonl (compact) for human-readable output while keeping --full and --raw-transcript on raw semantics.
• Added best-effort dual-write summary persistence (v1 required + v2 optional) and persisted pending prompt attribution diagnostics.

Reviewed changes

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

Show a summary per file

File	Description
cmd/entire/cli/transcript/compact/parse.go	Adds compact transcript parsing and condensed entry extraction.
cmd/entire/cli/transcript/compact/parse_test.go	Unit tests for compact transcript parsing/condensing.
cmd/entire/cli/strategy/manual_commit_test.go	Tests for persisting prompt attributions including pending attribution.
cmd/entire/cli/strategy/manual_commit_hooks.go	Minor parent commit detection simplification.
cmd/entire/cli/strategy/manual_commit_condensation.go	Persists pending prompt attribution in diagnostic metadata.
cmd/entire/cli/integration_test/explain_test.go	Integration coverage for v2-enabled explain fallback/preference behavior.
cmd/entire/cli/explain.go	Core v2-aware explain resolution, compact transcript preference, dual-write summary update, compact parsing fallback.
cmd/entire/cli/explain_test.go	Unit tests for v2-only/dual-write explain behavior and merged listing.
cmd/entire/cli/checkpoint/v2_read.go	Adds v2 ListCommitted and ReadSessionCompactTranscript.
cmd/entire/cli/checkpoint/v2_read_test.go	Tests for reading compact transcripts and v2 summary update behavior.
cmd/entire/cli/checkpoint/v2_committed.go	Implements V2GitStore.UpdateSummary for v2 metadata updates.
cmd/entire/cli/checkpoint/committed_reader_resolve.go	Adds a shared v1/v2 committed reader resolver and raw log resolver.
cmd/entire/cli/checkpoint/committed_reader_resolve_test.go	Tests for committed reader and raw log resolution behavior.

[pfleidi]

Bugbot run

[pfleidi]

Bugbot run

[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 7119e1f. Configure here.}

The merge-base changed after approval.

The merge-base changed after approval.