Phase 1: mirror committed checkpoints to v1 custom ref (opt-in, local-only)

[computermode]

Summary

Phase 1 of the v1.1 checkpoints rollout. Adds opt-in, local-only mirroring of committed checkpoint metadata to a new v1 custom ref refs/entire/checkpoints/v1.1, gated on strategy_options.checkpoints_version: "1.1" (string only).

• v1 (refs/heads/entire/checkpoints/v1) remains the source of truth.
• The custom ref is never read, pushed, or fetched in this PR — it is only populated, so later phases can verify it and eventually flip reads/writes over to it.
• Staged rollout this is step 1 of: mirror → verify reads → flip reads (v1 fallback) → push/fetch → replace.

What changed

• paths new const MetadataRefName = "refs/entire/checkpoints/v1.1". Lives under refs/entire/ so it stays invisible to git branch -a / GitHub's branch UI and is not pulled by a default git clone.
• settings the string checkpoints_version: "1.1" is now a recognized value mapping to data-format major version 1 (so it no longer trips the "unsupported version, falling back" warning). New gate MirrorsToV1CustomRef. Only the string "1.1" opts in; the numeric form 1.1 falls back to v1 and logs as unsupported.
• strategy new mirrorMetadataToV1CustomRef(ctx, repo) helper that, when opted in, advances the custom ref to the v1 branch's current commit using SafelyAdvanceLocalRef (the established ancestry-safe advancement for refs/entire/ metadata refs). Wired into all post-commit-hook committed writes: condensation, finalize, and combined-attribution (UpdateCheckpointSummary). A mirror failure is logged, never propagated, so it can't affect the v1 write that preceded it.
• Tests settings gate; mirror-helper unit tests (create / disabled no-op / advance / v1-missing no-op); integration tests that run the real CondenseSession and finalize (PostCommit + HandleTurnEnd) paths and assert the custom ref equals v1's actual checkpoint commit; and a pre-push test proving the custom ref is never pushed while the v1 branch is.

Divergences from the handoff plan (plan.md) and why

Follows the plan's scope and intent but not its mechanism (a MirroringCommittedStore wrapper on a reworked GitStore):

1. No MirroringCommittedStore, no GitStore rework, no signature change (plan §GitStore, §Write Return Values, §MirroringCommittedStore). Replaced by a post-write ref-sync helper — same outcome, much smaller blast radius, zero churn to the working v1 write path.
2. No seed behavior / vercel.json init (plan §Seed Behavior). N/A under mirroring: the custom ref only ever points at v1's existing commit; it is never independently initialized.
3. Dev docs (plan Task 6) intentionally omitted for this PR.

(Earlier divergences now closed: the opt-in is string-only per the plan; and the custom ref now advances ancestry-safely via SafelyAdvanceLocalRef rather than a raw SetReference.)

Known limitation — comprehensive mirroring deferred (follow-up)

Mirroring covers the post-commit-hook write paths (condensation, finalize, combined-attribution). Two non-hook paths also advance the v1 ref and do not mirror yet:

• UpdateSummary (explain --generate)
• attach (WriteCommitted)

After either of those, the custom ref lags v1 until the next hook write re-syncs it. Benign for phase 1 (nothing reads the custom ref), but must be addressed before reads flip in phase 2. Deferred per PR review.

Note for the follow-up: every committed write — including explain's, which goes through NewCommittedReader/DualCheckpointReader rather than a raw *GitStore — ultimately funnels through GitStore's four committed-write methods. So a single mirror point inside GitStore (gated + cached) is the clean way to cover all paths and any future writer, rather than wiring each construction site.

Out of scope (per plan)

Reads (list/explain/rewind stay v1-only for reading), push/fetch/reconcile/cleanup/doctor for the custom ref, and any new CLI surface — all untouched.

Testing

• mise run lint clean (0 issues).
• Full unit suite passes; strategy + settings packages green.

🤖 Generated with Claude Code

[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 8007d39. Configure here.}

[Copilot]

Pull request overview

Phase 1 of a staged v1.1 checkpoints rollout. When strategy_options.checkpoints_version is "1.1" (or JSON number 1.1), committed checkpoint metadata written to the existing v1 branch is additionally mirrored locally to a new custom ref refs/entire/checkpoints/v1.1. v1 remains authoritative; the new ref is never read, fetched, or pushed in this PR. Mirror failures are logged only and never affect the underlying v1 write.

Changes:

• Add paths.MetadataRefName = "refs/entire/checkpoints/v1.1" and a mirrorMetadataToV1CustomRef helper invoked after WriteCommitted in CondenseSession and once after the finalizeAllTurnCheckpoints update loop.
• Recognize "1.1" / 1.1 as a valid checkpoints_version mapping to v1 data format (avoids the "unsupported version" warning) and add MirrorsToV1CustomRef gate on both package and EntireSettings.
• Add unit, integration, and pre-push tests covering enabled/disabled mirroring, advancing/missing-ref cases, and the invariant that the custom ref is never pushed.

Reviewed changes

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

Show a summary per file

File	Description
cmd/entire/cli/paths/paths.go	Adds MetadataRefName constant for the v1.1 custom ref.
cmd/entire/cli/settings/settings.go	Recognizes 1.1/"1.1" as v1 format and adds MirrorsToV1CustomRef gate (package + receiver).
cmd/entire/cli/settings/settings_test.go	Tests MirrorsToV1CustomRef value matrix and that 1.1 is a recognized version.
cmd/entire/cli/strategy/v1_custom_ref_mirror.go	New helper that points the custom ref at the v1 branch tip when opted in; logs mirror failures.
cmd/entire/cli/strategy/v1_custom_ref_mirror_test.go	Unit + integration tests for mirror behavior, real condense/finalize paths, and pre-push exclusion.
cmd/entire/cli/strategy/manual_commit_condensation.go	Invokes mirror helper after the v1 committed write.
cmd/entire/cli/strategy/manual_commit_hooks.go	Invokes mirror helper once after finalizeAllTurnCheckpoints update loop.

[pfleidi]

Left two minor comments. Otherwise, it looks good 👍

[computermode]

Verified that checkpoints are mirrored in a test repo. Tested with a new session and then an advancement of the session and noticed both refs advanced.

➜  test-repo git:(new-v-1-1) ✗ git rev-parse refs/entire/checkpoints/v1.1 refs/heads/entire/checkpoints/v1
2930e5278d124d2e2877008fabd99b632192c514
2930e5278d124d2e2877008fabd99b632192c514