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

57bf0ac→main·

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)

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
}

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

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: