# Push checkpoints v1.1 ref to remote (rollout milestone 2)

`57bf0ac`→[main](/content/gh/entireio/cli/commits/main/index.html)·

computermode·1mo ago·8 files·+126 added/-20 removed

Stacked on #1376 (feat/checkpoints-v1.1-streamline-mirroring), which made the
CommittedRefs resolver the single source of the committed-metadata ref
topology. This is the next rollout phase: get refs/entire/checkpoints/v1.1
onto the configured remote before a later milestone flips it to the primary
write target.

- Resolver: append v1.1 to CommittedRefs.Push in opted-in mode, so PrePush
  pushes it alongside v1. Primary stays v1, so PrimaryFetchableFromOrigin
  (gated on Primary.IsBranch) and ReadBootstrappableFromOrigin (Read==Primary)
  are unchanged -- reads still treat v1.1 as local-only.
- PrePush: re-point the mirror at the primary tip before the push loop, so a
tip left stale by an earlier best-effort advance is published correctly.
  Best-effort: a refresh failure is logged and never blocks the user's push.
- Tests: updated resolver Push expectations, added ReadBootstrappableFromOrigin
  coverage, inverted the milestone-1 "v1.1 never pushed" guard to assert v1.1
  is pushed, and added an integration test that v1.1 lands on the remote at the
  v1 tip.
- Docs: CLAUDE.md and sessions-and-checkpoints.md no longer describe v1.1 as
  local-only.

## Sessions

1facee2350c8View transcript

### Changes

8

- MCLAUDE.md+1/-1

- cmd/entire/cli

- checkpoint
    
    - Mcommitted_refs.go+5
    
    - Mcommitted_refs_test.go+27/-2

- integration_test

- Mremote_operations_test.go+46

- strategy

- Mmanual_commit_push.go+25
    
    - Mpush_common_test.go+2/-3
    
    - Mv1_custom_ref_mirror_test.go+6/-6

- docs/architecture

- Msessions-and-checkpoints.md+14/-8

#### Features

- **Worktree-specific branches** - each git worktree gets its own shadow branch namespace, preventing conflicts
- **Supports multiple concurrent sessions** - checkpoints from different sessions in the same directory interleave on the same shadow branch
- Condenses session logs to permanent `entire/checkpoints/v1` branch on user commits
- When `checkpoints_version` is `1.1`, best-effort mirrors v1 metadata to the local-only `refs/entire/checkpoints/v1.1` read ref after entire-managed v1 writes and fetches; mirror failures are logged, not fatal. The resume bootstrap that promotes local v1 from origin's remote-tracking ref is the deliberate exception — it does not mirror and is skipped entirely in v1.1 mode. Read paths use the configured ref as-is.
- Uses the `post-rewrite` Git hook to keep local session linkage aligned after amend/rebase rewrites
- Builds git trees in-memory using go-git plumbing APIs
- Rewind restores files from shadow branch commit tree (does not use `git reset`)

```go
custom := plumbing.ReferenceName(paths.MetadataRefName)
refs.Read = custom
refs.Mirror = custom
// Push v1.1 alongside v1 so the new ref exists on the remote before a
// later milestone flips it to Primary. Primary stays v1, so
// PrimaryFetchableFromOrigin (which requires Primary.IsBranch) is
// unaffected by adding the non-branch v1.1 ref here.
refs.Push = append(refs.Push, custom)
}
return refs
}
```

```go
func TestPrePush_PushesV1CustomRefWhenOptedIn(t *testing.T) {
t.Parallel()
env := NewFeatureBranchEnv(t)

// Opt into v1.1 before any session activity so condensation mirrors v1.1
// and the resolver puts v1.1 in the push set.
env.PatchSettings(map[string]any{
    "strategy_options": map[string]any{"checkpoints_version": "1.1"},
})

bareDir := env.SetupBareRemote()

session := env.NewSession()
transcriptPath := session.CreateTranscript("Add auth module", []FileChange{
    {Path: "auth.go", Content: "package auth"},
})
if err := env.SimulateUserPromptSubmitWithPromptAndTranscriptPath(session.ID, "Add auth module", transcriptPath); err != nil {
    t.Fatalf("SimulateUserPromptSubmit failed: %v", err)
}
env.WriteFile("auth.go", "package auth")
env.GitAdd("auth.go")
if err := env.SimulateStop(session.ID, transcriptPath); err != nil {
    t.Fatalf("SimulateStop failed: %v", err)
}
env.GitCommitWithShadowHooks("Add auth module", "auth.go")

env.RunPrePush("origin")

// The v1 branch still pushes as before.
if !env.BranchExistsOnRemote(bareDir, paths.MetadataBranchName) {
    t.Fatalf("%s should exist on bare remote after PrePush", paths.MetadataBranchName)
}

// The v1.1 ref must now exist on the remote and point at the same commit as
// the v1 branch (revParse fails the test if the v1.1 ref is absent).
remoteV1 := revParse(t, bareDir, "refs/heads/"+paths.MetadataBranchName)
remoteCustom := revParse(t, bareDir, paths.MetadataRefName)
if remoteV1 != remoteCustom {
    t.Errorf("remote %s = %s, want %s (remote v1 tip)", paths.MetadataRefName, remoteCustom, remoteV1)
}
}
```

### Session State

| Session State | `.git/entire-sessions/<id>.json` | Active session tracking |
| ------------- | -------------------- | -------------------- |
| Temporary     | `entire/<commit[:7]>-<worktreeHash[:6]>` branch | Full state (code + metadata) |
| Committed      | `entire/checkpoints/v1` branch (sharded) | Metadata + commit reference |
| Committed read mirror | `refs/entire/checkpoints/v1.1` ref | Local-only mirror used by v1.1 reads |
| Committed read mirror | `refs/entire/checkpoints/v1.1` ref | Mirror used by v1.1 reads; pushed alongside v1 when opted in |

remotes. When `strategy_options.checkpoints_version` is `"1.1"`, committed reads
resolve against `refs/entire/checkpoints/v1.1` instead.

The v1.1 ref is a local-only mirror. It lives outside `refs/heads/`, is never
pushed, and does not appear in normal branch listings. Entire-managed v1 write
and fetch paths advance the mirror best-effort after they advance
`entire/checkpoints/v1`; mirror failures are logged but never fail the primary
operation. The resume bootstrap that promotes local v1 from origin's remote-tracking ref is the deliberate exception — it does not mirror and is
skipped entirely in v1.1 mode.

Read paths do not create, repair, or advance the mirror before use; they read
the configured committed-read ref as-is. The repair tool is `entire doctor`:
```