Mirror v1 checkpoint refs for v1.1 reads#1335
Merged
Merged
Conversation
Move v1.1 committed metadata mirroring into the strategy package so CLI and hook callers share one implementation. The mirror now points directly at the v1 primary ref, matching its local-only mirror role. Entire-Checkpoint: 555ddb60c8cb
After active v1 checkpoint metadata fetch or sync paths update the local branch, best-effort mirror the resulting tip to the v1.1 local read ref when enabled. This keeps v1 as the source of truth while ensuring v1.1 reads observe explicitly fetched metadata. Entire-Checkpoint: 077731df431b
Committed reads now use the configured read ref as-is. Active v1 write and fetch paths are responsible for keeping the v1.1 mirror current. Entire-Checkpoint: 0adaf0f2e559
Record that v1 remains the source of truth while checkpoints v1.1 reads use the local mirror as-is. This keeps the architecture notes aligned with the strategy-owned mirror paths. Entire-Checkpoint: c1f42862e3ac
Derive metadata fetch and mirror decisions from CommittedRefs.Primary instead of re-deriving the v1 branch name at each call site. This keeps the v1.1 mirror plumbing aligned with the shared committed-ref topology. Entire-Checkpoint: 9f6cdebf67e3
Route user-facing committed metadata reads through the configured read store so v1.1 mode reads the local mirror as-is. Add a regression that diverges v1 after seeding the custom ref to catch accidental fallback to the primary branch. Entire-Checkpoint: 18d361781db9
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the committed-checkpoint ref topology so that v1 remains the durable write/fetch target while v1.1 reads use a local-only mirror ref (refs/entire/checkpoints/v1.1) as-is, removing prior read-time mirroring behavior. Mirroring is centralized in the strategy layer and invoked after active v1 write/fetch paths so user-facing reads consistently follow the configured committed-read ref.
Changes:
- Centralize committed-metadata mirroring in
strategy.MirrorCommittedMetadataRef/MirrorCommittedMetadataRefBestEffort, and remove CLI-level mirroring helpers. - Route committed-checkpoint reads (listing, review context, dispatch enumeration, explain/rewind/resume support paths) through
checkpoint.NewCommittedReadStorewithout read-time mirroring. - Update docs and tests to reflect “mirror on write/fetch, read as-is” semantics for checkpoints_version
1.1.
Reviewed changes
Copilot reviewed 30 out of 30 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| docs/architecture/sessions-and-checkpoints.md | Documents the v1.1 local-only committed-read mirror and the “read as-is” behavior. |
| cmd/entire/cli/v1_custom_ref_mirror.go | Removes CLI-level mirror implementation (now centralized in strategy). |
| cmd/entire/cli/v1_custom_ref_mirror_test.go | Removes CLI-level mirror tests (moved to strategy tests). |
| cmd/entire/cli/strategy/v1_custom_ref_mirror.go | Introduces centralized mirror functions with error vs best-effort behavior. |
| cmd/entire/cli/strategy/v1_custom_ref_mirror_test.go | Adds/updates strategy-level tests for mirror behavior (create/advance/overwrite/error). |
| cmd/entire/cli/strategy/push_common.go | Mirrors the v1.1 ref after successful metadata sync/rebase of the primary branch. |
| cmd/entire/cli/strategy/push_common_test.go | Verifies push/fetch sync paths update the v1.1 mirror when enabled. |
| cmd/entire/cli/strategy/manual_commit.go | Removes read-time mirroring from committed read store creation. |
| cmd/entire/cli/strategy/manual_commit_hooks.go | Updates post-write hook paths to mirror using centralized best-effort helper. |
| cmd/entire/cli/strategy/manual_commit_condensation.go | Mirrors after condense committed writes using centralized helper. |
| cmd/entire/cli/strategy/common.go | Switches checkpoint listing to use committed read store (configured read ref). |
| cmd/entire/cli/strategy/checkpoint_remote.go | Fetches primary metadata ref by resolved topology and mirrors after fetch. |
| cmd/entire/cli/strategy/checkpoint_remote_test.go | Ensures fetch updates the v1.1 mirror in v1.1 mode. |
| cmd/entire/cli/rewind.go | Removes read-time mirroring; reads committed content via committed read store. |
| cmd/entire/cli/review_context.go | Uses committed read store for committed metadata reads. |
| cmd/entire/cli/resume_test.go | Updates messaging expectations around missing v1.1 metadata behavior. |
| cmd/entire/cli/paths/paths.go | Updates inline documentation for v1.1 ref semantics (“read as-is”, mirror on write/fetch). |
| cmd/entire/cli/head_checkpoint_flags.go | Reads checkpoint flags via committed read store (configured committed-read ref). |
| cmd/entire/cli/head_checkpoint_flags_test.go | Adds coverage confirming v1.1 mode reads the custom ref as-is. |
| cmd/entire/cli/git_operations.go | Mirrors v1.1 ref after fetching/advancing primary metadata from origin. |
| cmd/entire/cli/git_operations_test.go | Adds test ensuring origin metadata fetch updates the v1.1 mirror. |
| cmd/entire/cli/explain.go | Removes read-time mirroring and uses centralized mirroring after summary writes. |
| cmd/entire/cli/explain_test.go | Adjusts test to explicitly mirror and assert write-time mirroring semantics. |
| cmd/entire/cli/dispatch/mode_local.go | Uses committed read store for local dispatch candidate enumeration. |
| cmd/entire/cli/checkpoint/store.go | Clarifies write-vs-read ref behavior and how v1.1 reads are configured. |
| cmd/entire/cli/checkpoint/committed_refs.go | Updates mirror field doc to reflect mirroring after v1 writes/fetches. |
| cmd/entire/cli/checkpoint/committed_read_store.go | Removes SyncCommittedReadRef and related read-time mirror logic. |
| cmd/entire/cli/checkpoint/committed_read_store_test.go | Updates tests to assert “no read-time seeding/sync; read custom ref as-is”. |
| cmd/entire/cli/attach.go | Uses centralized mirror function after committed writes when mirroring is enabled. |
| CLAUDE.md | Updates strategy documentation to reflect v1.1 mirror and read behavior. |
…advance-after-sync # Conflicts: # cmd/entire/cli/review_context.go
Contributor
Author
|
Bugbot run |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
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 323d257. Configure here.
Refresh the configured committed metadata mirror when reconciliation advances the v1 metadata branch. This keeps v1.1 reads aligned even if push-time sync returns before a later success-path mirror call. Entire-Checkpoint: 8dd71c02ade6
…advance-after-sync Entire-Checkpoint: 3dfee3839b09
computermode
previously approved these changes
Jun 2, 2026
EnsureMetadataBranch advances the v1 branch from origin or creates a fresh orphan during setup, but the new committed-ref mirror was only updated by later hook-time writes. In v1.1 mode the mirror stayed unset between `entire enable` and the first session-end condensation, so every NewCommittedReadStore consumer (list/status/dispatch/rewind/ review) returned empty. Mirror after each SetReference that advances the v1 branch, and thread ctx through the function so the mirror, the pre-existing Debug log, and SignCommitBestEffort share the caller's context. Entire-Checkpoint: 928986401e8e
computermode
previously approved these changes
Jun 3, 2026
DeleteOrphanedCheckpoints commits a cleanup tree on entire/checkpoints/v1 and advances the local branch, but did not update the v1.1 custom ref. In v1.1 mode the mirror still pointed at the pre-cleanup tip, so every NewCommittedReadStore consumer (list/status/explain/dispatch) kept surfacing the just-deleted checkpoints until another v1 write happened to mirror. Mirror after the SetReference, gated by checkpoints_version through MirrorCommittedMetadataRefBestEffort. Entire-Checkpoint: 7c38d2aad996
Earlier wording said the mirror is advanced "after active v1 write/fetch paths" without specifying who advances it, that failures are non-fatal, or that the resume bootstrap is excluded. Update CLAUDE.md and sessions-and-checkpoints.md to describe the actual contract: - mirror is best-effort, gated on the checkpoints_version setting - entire-managed v1 writes and fetches advance it; failures log but never fail the primary operation - promoteRemoteTrackingMetadataBranch deliberately does not mirror and is skipped entirely when v1.1 is opted in - read paths use the configured ref as-is Entire-Checkpoint: eb7c055bbe39
Three small visibility fixes for the v1.1 mirror best-effort path: - Add ErrPrimaryMetadataMissing sentinel. MirrorCommittedMetadataRef wraps the primary-ref NotFound case with the sentinel, so the best-effort caller can log Debug only for that case and Warn for every other failure — including a SetReference NotFound that the previous errors.Is(err, plumbing.ErrReferenceNotFound) check conflated with 'primary missing'. - Detach cancellation in MirrorCommittedMetadataRefBestEffort with context.WithoutCancel. A near-expired parent deadline (e.g. the 2-minute fetch budget in fetchMetadataFromOrigin) could fail settings.Load silently inside ResolveCommittedRefs, causing HasMirror to report false and the mirror to skip with no log. The mirror is short and best-effort; trace/value context is preserved. - Log Debug in mirrorSyncedMetadataBranch for the two cases that previously returned silently (primary not a branch; branch name does not match primary). These are future-topology guards; today they never fire, but a silent skip would be hard to find later. Entire-Checkpoint: 3372c9e81e2d
computermode
approved these changes
Jun 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
https://entire.io/gh/entireio/cli/trails/488
What
How
Verification
Note
Medium Risk
Changes how committed checkpoint metadata is resolved across explain, resume, dispatch, and hooks when v1.1 is enabled; wrong mirror timing could make reads miss data until the next v1 sync.
Overview
For checkpoints v1.1, committed metadata still writes and fetches on
entire/checkpoints/v1, but reads use the local-onlyrefs/entire/checkpoints/v1.1without read-time sync from v1.Mirroring is centralized in
strategy.MirrorCommittedMetadataRef(strict) andMirrorCommittedMetadataRefBestEffort(hooks/condense). The mirror is updated after v1 writes, metadata fetches, and push-time metadata sync—not when listing or loading checkpoints. CLI-onlymirrorToV1CustomRefandSyncCommittedReadRefare removed.Call sites such as
explain,dispatch,resumemessaging, HEAD checkpoint flags, and manual-commit reads now usecheckpoint.NewCommittedReadStoreso behavior followscheckpoints_version. Docs and tests spell out the new read vs mirror contract.Reviewed by Cursor Bugbot for commit 323d257. Configure here.