feat: v2 dual-write for checkpoints behind feature flag

[pfleidi]

Summary

Introduces checkpoints v2 dual-write support. When checkpoints_v2 is enabled in strategy options, the CLI writes checkpoint data to both v1 (entire/checkpoints/v1 branch) and v2 custom refs (refs/entire/checkpoints/v2/main and refs/entire/checkpoints/v2/full/current).

• V2GitStore — new store type for v2 ref operations, separate from GitStore (v1) to simplify future v1 removal
• /main ref — receives metadata, prompts, session metadata (no raw transcript). Compact transcript.jsonl will be added here once compaction (workstream B) is ready
• /full/current ref — receives raw transcript (full.jsonl) + content_hash.txt. Each write replaces the entire tree (no accumulation); generation rotation is future work
• Dual-write wiring — CondenseSession and stop-time finalization both dual-write, gated by settings.IsCheckpointsV2Enabled(). V2 failures are best-effort (logged as warnings, never block v1)
• Shared validation — extracted validateWriteOpts used by both v1 and v2 stores

What's NOT in scope (future steps per design spec)

• Task checkpoint support on /main
• Push logic for v2 refs
• Read paths (entire status, entire explain, entire resume)
• Generation rotation for /full/current
• Compact transcript format / compaction (workstream B)
• v1 → v2 migration tool

Test plan

• 20 unit tests for V2GitStore (ref management, write/update for both refs, multi-session, edge cases)
• 2 strategy-level tests (v2 enabled vs disabled in CondenseSession)
• 3 integration tests (full workflow, disabled path, stop-time finalization)
• mise run fmt && mise run lint — 0 issues
• mise run test:ci — all unit, integration, and E2E canary tests pass

🤖 Generated with Claude Code

---

Note

Medium Risk
Adds a new v2 checkpoint storage path using custom git refs and wires it into commit/stop-time flows; mistakes could lead to missing or inconsistent checkpoint data even though v1 remains the source of truth. Risk is mitigated by feature-flag gating and best-effort v2 writes that do not block v1.

Overview
Adds feature-flagged v2 dual-write for checkpoints: when checkpoints_v2 is enabled, the manual-commit strategy continues writing v1 checkpoint data while also writing to new custom refs refs/entire/checkpoints/v2/main and refs/entire/checkpoints/v2/full/current.

Introduces V2GitStore with ref management and write/update flows that split data: /main stores checkpoint/session metadata + prompts (no transcript), while /full/current stores the redacted, chunked full.jsonl transcript plus content_hash.txt and replaces prior contents on each write. Validation for write options is centralized via validateWriteOpts, and tests are expanded with new unit tests, integration tests, and test-env helpers to read custom refs.

^{Written by Cursor Bugbot for commit 66841b2. Configure here.}

[pfleidi]

These attributes might not be set going forward. Omitting them in such a case made sense to me.

[computermode]

Why would Transcript be missing but Prompt isn't? Should Prompt be omitempty too? (Also, is this for the sub-agent case? Or is there some other case you had in mind?)

[pfleidi]

The original thought was that by moving the full transcript to the /full/* refs we wouldn't need this anymore unless a checkpoint was pinned. Given that these attributes were only used for the full transcripts we should be okay omitting them unless checkpoints are pinned down the road.

Your comment brought up a few more questions, though:

• Do we want this attribute to point to the compactedtranscript.jsonl file instead?
• Do we want to introduce new attributes for compacted transcripts and their hashes?
• Do we want a way to refer to objects in the /full/* namespace to somehow make the lookup simpler?

Let's take a look at those a bit more closely tomorrow.

[Copilot]

Pull request overview

Adds a feature-flagged “checkpoints v2” dual-write path so the manual-commit strategy can persist checkpoint data to both the existing v1 metadata branch and the new v2 custom refs, enabling a gradual migration without breaking current read paths.

Changes:

• Wire dual-write into CondenseSession and stop-time finalization (UpdateCommitted) behind settings.IsCheckpointsV2Enabled(), with v2 failures treated as best-effort.
• Introduce V2GitStore to write v2 checkpoint data to custom refs (/main for metadata/prompts, /full/current for raw transcript + content hash).
• Add unit + strategy-level + integration tests, and extend integration TestEnv helpers to read from arbitrary refs.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
cmd/entire/cli/strategy/manual_commit_condensation.go	Builds shared v1/v2 write opts and adds best-effort v2 dual-write during condensation.
cmd/entire/cli/strategy/manual_commit_hooks.go	Adds best-effort v2 dual-write during stop-time checkpoint finalization.
cmd/entire/cli/strategy/manual_commit_test.go	Adds strategy-level tests for v2 dual-write enabled/disabled behavior.
cmd/entire/cli/paths/paths.go	Defines v2 custom ref names under refs/entire/....
cmd/entire/cli/integration_test/v2_dual_write_test.go	Adds integration coverage for full workflow, disabled path, and stop-time finalization.
cmd/entire/cli/integration_test/testenv.go	Adds helpers for reading files from full refs and for checking ref existence.
cmd/entire/cli/checkpoint/v2_store.go	Adds low-level v2 ref creation/state/update primitives.
cmd/entire/cli/checkpoint/v2_committed.go	Implements v2 committed write/update logic for /main and /full/current.
cmd/entire/cli/checkpoint/v2_store_test.go	Adds unit tests for v2 ref management and committed write/update behavior.
cmd/entire/cli/checkpoint/committed.go	Reuses shared write-option validation via validateWriteOpts.
cmd/entire/cli/checkpoint/checkpoint.go	Makes SessionFilePaths JSON fields omitempty to support v2 layouts with missing fields.

[Copilot]

Pull request overview

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

[Copilot]

Docstring states that writeMainSessionToSubdirectory writes a content hash to /main, but the implementation doesn't write content_hash.txt (it only writes prompts + metadata). Please adjust the docstring to avoid implying content_hash.txt exists on /main.

[Copilot]

updateCommittedV2IfEnabled() calls settings.IsCheckpointsV2Enabled(), which loads and parses settings from disk each time. Since this is invoked inside the per-checkpoint loop, stop-time finalization can end up reloading settings N times. Consider evaluating the feature flag once before the loop (or passing a precomputed bool into the helper) to avoid unnecessary I/O during stop-time finalization.

[Copilot]

The comment says /main session writes include a content hash, but this function only writes metadata.json and (optionally) prompt.txt; no content_hash.txt is written on /main. Please update the comment to match the actual behavior (or add the content hash write if the intent is to store it on /main).

Suggested change

	// Write session files (metadata, prompts, content hash — no transcript)
	// Write session files (metadata and prompts — no transcript or content hash)