checkpoint: remove v1.1 mirror machinery · Entire
Log in
checkpoint: remove v1.1 mirror machinery
051354e→main·
pfleidi·1mo ago·37 files·+29 added/-2,038 removed
Stop maintaining and diagnosing the retired v1.1 committed metadata mirror.
Committed reads and writes now use the v1 metadata branch directly, and tests that only covered the custom-ref path are removed.
Sessions
35f3afc670c0View transcript
?\ Collapse Checkpoint Metadata to v1Codex·GPT-5.5·2 steps
Changes
37
cmd/entire/cli
Mattach.go-4
Mattach_test.go-37
checkpoint
Mcommitted_refs.go-3
dispatch
Mmode_local.go+2/-5
Mmode_local_test.go-133
Mdoctor.go+2/-93
Mdoctor_bundle.go+2/-27
Mdoctor_bundle_test.go+1/-15
Mdoctor_test.go-179
Mexplain.go-5
Mexplain_test.go+9/-24
Mgit_operations.go-5
Mgit_operations_test.go-43
Mhead_checkpoint_flags_test.go-26
integration_test
Mattach_test.go-45
Mremote_operations_test.go-41
paths
Mpaths.go-8
Mresume.go+1/-2
Mresume_test.go-207
Mreview_context_test.go-67
strategy
Mcheckpoint_remote.go-8
Mcheckpoint_remote_test.go-8
Mclean_test.go-59
Mcleanup.go+1/-2
Mcommon.go+3/-3
Mcommon_test.go+3/-13
Mmanual_commit_condensation.go-4
Mmanual_commit_hooks.go-9
Mmanual_commit_push.go-20
Mmanual_commit_test.go-58
Mmetadata_reconcile.go+1/-2
Mmetadata_reconcile_test.go-63
Mpush_common.go+1/-3
Mpush_common_test.go+3/-6
Mrewind_test.go-44
Dv1_custom_ref_mirror.go-205
Dv1_custom_ref_mirror_test.go-562
347 unmodified lines
348
349
350
351
352
353
354
351
352
353
347 unmodified lines
return fmt.Errorf("failed to write checkpoint: %w", err)
}
if err := strategy.MirrorCommittedMetadataRef(ctx, repo, refs); err != nil {
return fmt.Errorf("checkpoint was written to %s, but failed to mirror to %s: %w", refs.Primary, refs.Mirror, err)
}
// Create or update session state.
if err := saveAttachSessionState(logCtx, repo, existingState, sessionID, ag.Type(), transcriptPath, checkpointID, meta, tokenUsage, opts, reviewSkills); err != nil {
logging.Warn(logCtx, "failed to save session state", "error", err)
Mcmd/entire/cli/attach.go-4
540 unmodified lines
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
544
545
546
540 unmodified lines
}
}
func TestAttach_MirrorsToV1CustomRefWhenOptedIn(t *testing.T) {
setupAttachTestRepo(t)
repoRoot := mustGetwd(t)
sessionID := "test-attach-v1-1-mirror"
setupClaudeTranscript(t, sessionID, `{"type":"user","message":{"role":"user","content":"hello"},"uuid":"u1"}
{"type":"assistant","message":{"role":"assistant","content":"hi"},"uuid":"a1"}
`)
var out bytes.Buffer
opts := attachOptions{
Force: true,
entireSettings: &settings.EntireSettings{
StrategyOptions: map[string]any{"checkpoints_version": "1.1"},
},
}
if err := runAttach(context.Background(), &out, sessionID, agent.AgentNameClaudeCode, opts); err != nil {
t.Fatalf("runAttach failed: %v", err)
}
repo, err := git.PlainOpen(repoRoot)
if err != nil {
t.Fatal(err)
}
v1Ref, err := repo.Reference(plumbing.NewBranchReferenceName(paths.MetadataBranchName), true)
if err != nil {
t.Fatalf("v1 metadata branch missing: %v", err)
}
customRef, err := repo.Reference(plumbing.ReferenceName(paths.MetadataRefName), true)
if err != nil {
t.Fatalf("v1.1 custom ref missing: %v", err)
}
if v1Ref.Hash() != customRef.Hash() {
t.Errorf("v1.1 custom ref = %s, want %s (v1 tip)", customRef.Hash(), v1Ref.Hash())
}
}
func TestCountUserTurns(t *testing.T) {
t.Parallel()
Mcmd/entire/cli/attach_test.go-37
13 unmodified lines
14
15
16
17
17
18
19
21
22
20
21
22
13 unmodified lines
type CommittedRefs struct {
Primary plumbing.ReferenceName
Read plumbing.ReferenceName
Mirror plumbing.ReferenceName
Push []plumbing.ReferenceName
}
func (r CommittedRefs) HasMirror() bool { return r.Mirror != "" }
// DefaultV1Refs returns the v1-only topology.
func DefaultV1Refs() CommittedRefs {
v1Branch := plumbing.NewBranchReferenceName(paths.MetadataBranchName)
Mcmd/entire/cli/checkpoint/committed_refs.go-3
172 unmodified lines
173
174
175
176
177
178
179
180
176
177
178
179
180
172 unmodified lines
return nil, err
}
// The committed-read topology (and thus the v1.1 mirror opt-in) is resolved
// from settings relative to the context's worktree root, which defaults to
// the process cwd. repoRoot may be a different repo (--repo/RepoPaths) or
// the cwd may not be a repo at all, so scope settings resolution to this
// repo before consulting the topology.
// repoRoot may be a different repo (--repo/RepoPaths) or the cwd may not be
// a repo at all, so scope checkpoint store construction to this repo.
repoCtx := settings.WithWorktreeRoot(ctx, repoRoot)
stores, err := checkpoint.Open(repoCtx, repo, checkpoint.OpenOptions{})
if err != nil {
Mcmd/entire/cli/dispatch/mode_local.go+2/-5
11 unmodified lines
12
13
14
15
15
16
17
18
19
21
20
21
22
48 unmodified lines
71
72
73
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
74
75
76
51 unmodified lines
128
129
130
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
131
132
133
721 unmodified lines
855
856
857
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
858
859
860
11 unmodified lines
"github.com/entireio/cli/cmd/entire/cli/agent"
"github.com/entireio/cli/cmd/entire/cli/checkpoint"
checkpointid "github.com/entireio/cli/cmd/entire/cli/checkpoint/id"
"github.com/entireio/cli/cmd/entire/cli/paths"
"github.com/entireio/cli/cmd/entire/cli/testutil"
"github.com/entireio/cli/cmd/entire/cli/trailers"
"github.com/entireio/cli/redact"
"github.com/go-git/go-git/v6"
"github.com/go-git/go-git/v6/config"
"github.com/go-git/go-git/v6/plumbing"
"github.com/go-git/go-git/v6/plumbing/object"
)
48 unmodified lines
}
}
func TestLocalMode_ReadsV1CustomRefWhenEnabled(t *testing.T) {
dir := t.TempDir()
stubGeneratedLocalDispatch(t)
testutil.InitRepo(t, dir)
testutil.WriteFile(t, dir, "a.txt", "x")
testutil.GitAdd(t, dir, "a.txt")
testutil.GitCommit(t, dir, "initial")
addOriginRemote(t, dir)
createdAt := time.Now().UTC()
seedCommittedCheckpoint(t, dir, seededCheckpoint{
id: testCheckpointID,
branch: "main",
createdAt: createdAt,
filesTouched: []string{"a.txt"},
outcome: testLocalFallbackText,
})
moveCheckpointsToCustomRefOnly(t, dir)
oldNow := nowUTC
nowUTC = func() time.Time { return createdAt.Add(2 * time.Hour) }
t.Cleanup(func() { nowUTC = oldNow })
t.Chdir(dir)
opts := Options{Mode: ModeLocal, Since: "7d", Branches: []string{"main"}}
// Mirror disabled: the checkpoint lives only on the custom ref, so the v1 read finds nothing.
got, err := Run(context.Background(), opts)
if err != nil {
t.Fatal(err)
}
if len(got.Repos) != 0 {
t.Fatalf("expected no checkpoints with mirror disabled, got %+v", got.Repos)
}
// Mirror enabled: reads resolve against the custom ref.
writeV1CustomRefMirrorSettings(t, dir)
got, err = Run(context.Background(), opts)
if err != nil {
t.Fatal(err)
}
if len(got.Repos) != 1 || got.Repos[0].Sections[0].Bullets[0].Text != testLocalFallbackText {
t.Fatalf("expected checkpoint via custom ref, got %+v", got.Repos)
}
}
func TestLocalMode_ExplicitRepoUsesTargetRepoCheckpointSettings(t *testing.T) {
cwdDir := t.TempDir()
targetDir := t.TempDir()
51 unmodified lines
}
}
// TestLocalMode_ExplicitRepoResolvesMirrorOptInFromTargetRepo guards against
// resolving the committed-read topology from the process cwd instead of the
// enumerated repo. The target repo opts into the v1.1 mirror and keeps its
// checkpoint only on the custom ref; cwd is a separate repo with the mirror
// off. If the opt-in were read from cwd, the checkpoint would be invisible.
func TestLocalMode_ExplicitRepoResolvesMirrorOptInFromTargetRepo(t *testing.T) {
cwdDir := t.TempDir()
targetDir := t.TempDir()
stubGeneratedLocalDispatch(t)
// cwd repo: mirror explicitly disabled.
testutil.InitRepo(t, cwdDir)
testutil.WriteFile(t, cwdDir, ".entire/settings.json", `{"enabled": true}`)
testutil.InitRepo(t, targetDir)
testutil.WriteFile(t, targetDir, "a.txt", "x")
testutil.GitAdd(t, targetDir, "a.txt")
testutil.GitCommit(t, targetDir, "initial")
addOriginRemote(t, targetDir)
createdAt := time.Now().UTC()
seedCommittedCheckpoint(t, targetDir, seededCheckpoint{
id: testCheckpointID,
branch: "main",
createdAt: createdAt,
filesTouched: []string{"a.txt"},
outcome: testLocalFallbackText,
})
// Reachable only via the custom ref, and the target repo opts into the mirror.
moveCheckpointsToCustomRefOnly(t, targetDir)
writeV1CustomRefMirrorSettings(t, targetDir)
oldNow := nowUTC
nowUTC = func() time.Time { return createdAt.Add(2 * time.Hour) }
t.Cleanup(func() {
nowUTC = oldNow
})
t.Chdir(cwdDir)
got, err := Run(context.Background(), Options{
Mode: ModeLocal,
RepoPaths: []string{targetDir},
Since: "7d",
Branches: []string{"main"},
})
if err != nil {
t.Fatal(err)
}
if len(got.Repos) != 1 || got.Repos[0].Sections[0].Bullets[0].Text != testLocalFallbackText {
t.Fatalf("expected target repo's v1.1 custom-ref checkpoint, got %+v", got.Repos)
}
}
func TestLocalMode_UsesUntilWindow(t *testing.T) {
dir := t.TempDir()
stubGeneratedLocalDispatch(t)
721 unmodified lines
}
}
// moveCheckpointsToCustomRefOnly points the v1 custom ref at the v1 branch tip
// and removes the v1 branch, so committed checkpoints are reachable only via the
// custom ref.
func moveCheckpointsToCustomRefOnly(t *testing.T, repoDir string) {
t.Helper()
repo, err := git.PlainOpenWithOptions(repoDir, &git.PlainOpenOptions{DetectDotGit: true})
if err != nil {
t.Fatal(err)
}
v1Branch := plumbing.NewBranchReferenceName(paths.MetadataBranchName)
v1Ref, err := repo.Reference(v1Branch, true)
if err != nil {
t.Fatal(err)
}
if err := repo.Storer.SetReference(plumbing.NewHashReference(plumbing.ReferenceName(paths.MetadataRefName), v1Ref.Hash())); err != nil {
t.Fatal(err)
}
if err := repo.Storer.RemoveReference(v1Branch); err != nil {
t.Fatal(err)
}
}
// writeV1CustomRefMirrorSettings opts repoDir into the v1 custom-ref mirror.
// "1.1" is the on-disk checkpoints_version encoding read by
// settings.MirrorsToV1CustomRef.
func writeV1CustomRefMirrorSettings(t *testing.T, repoDir string) {
t.Helper()
testutil.WriteFile(t, repoDir, ".entire/settings.json",
`{"enabled": true, "strategy_options": {"checkpoints_version": "1.1"}}`)
}
func addOriginRemote(t *testing.T, repoDir string) {
t.Helper()
Mcmd/entire/cli/dispatch/mode_local_test.go-133
33 unmodified lines
34
35
36
37
38
39
40
41
37
43
38
39
40
41
42
48
43
44
45
46
44 unmodified lines
91
92
93
99
100
101
102
103
104
105
106
94
95
96
280 unmodified lines
377
378
379
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
380
381
382
23 unmodified lines
406
407
408
492
493
494
495
496
497
498
499
409
410
411
33 unmodified lines
entire/checkpoints/v1 branches share no common ancestor (caused by a
previous bug). Fixes by cherry-picking local checkpoints onto remote tip.
2. Checkpoint read mirror (checkpoints v1.1 only): detects when the
local-only refs/entire/checkpoints/v1.1 read mirror is missing, stale,
or diverged relative to entire/checkpoints/v1, which makes reads miss
checkpoints. Fixes by pointing the mirror at the v1 tip.
When Codex hooks are installed:
3. Codex hook trust: warn when hooks declared in .codex/hooks.json
2. Codex hook trust: warn when hooks declared in .codex/hooks.json
lack a trusted_hash entry in the user's Codex config (i.e. /hooks
review hasn't run yet on this machine, or a newer entire release
added a hook the user hasn't approved yet).
4. Stuck sessions: sessions stuck in ACTIVE or ENDED phase that need cleanup.
3. Stuck sessions: sessions stuck in ACTIVE or ENDED phase that need cleanup.
A session is considered stuck if:
- It is in ACTIVE phase with no interaction for over 1 hour
44 unmodified lines
finalErr = NewSilentError(fmt.Errorf("metadata check failed: %w", metadataErr))
}
// Check 2: v1.1 read-mirror drift (after check 1: reconciliation rewrites
// v1 and re-mirrors).
if mirrorErr := checkCommittedMetadataMirror(cmd, force); mirrorErr != nil {
fmt.Fprintf(cmd.ErrOrStderr(), "Error: checkpoint read mirror check failed: %v\n", mirrorErr)
if finalErr == nil {
finalErr = NewSilentError(fmt.Errorf("checkpoint read mirror check failed: %w", mirrorErr))
}
}
fmt.Fprintln(cmd.OutOrStdout())
ctx := cmd.Context()
280 unmodified lines
return nil
}
// checkCommittedMetadataMirror detects and optionally repairs v1.1 read-mirror
// drift. Read paths use the mirror as-is, so doctor is the repair tool.
// Silent when the topology has no mirror.
func checkCommittedMetadataMirror(cmd *cobra.Command, force bool) error {
ctx := cmd.Context()
repo, err := openRepository(ctx)
if err != nil {
return fmt.Errorf("failed to open repository: %w", err)
}
defer repo.Close()
diag, err := strategy.DiagnoseCommittedMetadataMirror(ctx, repo)
if err != nil {
return fmt.Errorf("could not check checkpoint read mirror state: %w", err)
}
w := cmd.OutOrStdout()
primary := diag.Refs.Primary.Short()
switch diag.Status {
case strategy.MirrorNotConfigured:
return nil
case strategy.MirrorOK:
fmt.Fprintln(w, "✓ Checkpoint read mirror: OK")
return nil
case strategy.MirrorNoMetadata:
fmt.Fprintln(w, "✓ Checkpoint read mirror: OK (no committed metadata yet)")
return nil
case strategy.MirrorPrimaryMissing:
fmt.Fprintf(w, "Checkpoint read mirror: %s\n", diag.Status)
fmt.Fprintf(w, " The read mirror %s exists, but the %s branch it mirrors is gone.\n",
diag.Refs.Mirror, primary)
fmt.Fprintln(w, " Restore the branch and re-run doctor:")
fmt.Fprintf(w, " git fetch origin %s:%s\n", primary, primary)
return nil
case strategy.MirrorMissing:
fmt.Fprintf(w, "Checkpoint read mirror: %s\n", diag.Status)
fmt.Fprintf(w, " %s does not exist; reads will find no checkpoints.\n", diag.Refs.Mirror)
fmt.Fprintf(w, " Fix: seed the mirror at the %s tip.\n", primary)
case strategy.MirrorBehind:
fmt.Fprintf(w, "Checkpoint read mirror: %s\n", diag.Status)
fmt.Fprintf(w, " Mirror is at %s, behind %s at %s; reads miss newer checkpoints.\n",
shortMirrorHash(diag.Mirror), primary, shortMirrorHash(diag.Primary))
fmt.Fprintf(w, " Fix: advance the mirror to the %s tip.\n", primary)
case strategy.MirrorDiverged:
fmt.Fprintf(w, "Checkpoint read mirror: %s\n", diag.Status)
fmt.Fprintf(w, " Mirror at %s has commits not on %s (at %s). Writes never target the\n",
shortMirrorHash(diag.Mirror), primary, shortMirrorHash(diag.Primary))
fmt.Fprintln(w, " mirror, so something outside entire moved it.")
fmt.Fprintf(w, " Fix: reset the mirror to the %s tip — the diverged mirror commits\n", primary)
fmt.Fprintf(w, " are discarded (%s is the source of truth).\n", primary)
}
if !force {
proceed, promptErr := confirmDoctorFix(ctx, w, "Repair checkpoint read mirror?")
if promptErr != nil {
return promptErr
}
if !proceed {
return nil
}
}
if fixErr := strategy.MirrorCommittedMetadataRef(ctx, repo, diag.Refs); fixErr != nil {
return fmt.Errorf("failed to repair checkpoint read mirror: %w", fixErr)
}
fmt.Fprintf(w, " ✓ Fixed: mirror now points at the %s tip\n", primary)
return nil
}
// confirmDoctorFix prompts to apply a doctor fix. Declining (which prints
// "-> Skipped"), aborting (Ctrl+C), and context cancellation all return false
// with no error.
23 unmodified lines
return confirmed, nil
}
// shortMirrorHash abbreviates a hash for mirror-check output; "none" when zero.
func shortMirrorHash(h plumbing.Hash) string {
if h.IsZero() {
return "none"
}
return h.String()[:7]
}
// checkCodexHookTrust warns about two kinds of drift in the Codex hook
// setup:
//
Mcmd/entire/cli/doctor.go+2/-93
15 unmodified lines
16
17
18
19
20
19
20
23
21
22
23
121 unmodified lines
145
146
147
151
148
149
150
151
152
156
157
153
154
155
156
3 unmodified lines
160
161
162
167
168
163
164
165
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
166
167
168
15 unmodified lines
"github.com/entireio/cli/cmd/entire/cli/logging"
"github.com/entireio/cli/cmd/entire/cli/paths"
"github.com/entireio/cli/cmd/entire/cli/settings"
"github.com/entireio/cli/cmd/entire/cli/strategy"
"github.com/entireio/cli/cmd/entire/cli/versioninfo"
"github.com/entireio/cli/redact"
"github.com/go-git/go-git/v6"
"github.com/spf13/cobra"
)
121 unmodified lines
return nil
}
// entireRefsReport captures entire-related git refs plus the mirror diagnosis.
// entireRefsReport captures entire-related git refs.
// Best-effort: failures are recorded in the report, not returned.
func entireRefsReport(ctx context.Context, repoRoot string) string {
var sb strings.Builder
// Broad globs on purpose: refs/heads/entire also catches shadow/trails
// branches, refs/entire catches the v1.1 mirror and future custom refs.
// Broad globs on purpose: refs/heads/entire also catches shadow/trails branches.
cmd := exec.CommandContext(ctx, "git", "for-each-ref", "--format=%(refname) %(objectname)",
"refs/heads/entire", "refs/entire", "refs/remotes/origin/entire")
cmd.Dir = repoRoot
3 unmodified lines
fmt.Fprintf(&sb, "[error: %v]\n", err)
}
sb.WriteString("\n")
sb.WriteString(mirrorStatusReportLine(ctx, repoRoot))
return sb.String()
}
// mirrorStatusReportLine renders the v1.1 mirror diagnosis for the bundle.
func mirrorStatusReportLine(ctx context.Context, repoRoot string) string {
repo, err := git.PlainOpen(repoRoot)
if err != nil {
return fmt.Sprintf("mirror status: [error: %v]\n", err)
}
defer repo.Close()
// Scope settings to repoRoot; the bundle's CWD may be elsewhere.
diag, err := strategy.DiagnoseCommittedMetadataMirror(settings.WithWorktreeRoot(ctx, repoRoot), repo)
if err != nil {
return fmt.Sprintf("mirror status: [error: %v]\n", err)
}
if diag.Status == strategy.MirrorNotConfigured {
return "mirror status: not configured (checkpoints v1)\n"
}
return fmt.Sprintf("mirror status: %s (mirror %s, v1 %s)\n",
diag.Status, shortMirrorHash(diag.Mirror), shortMirrorHash(diag.Primary))
}
func versionInfoString() string {
var sb strings.Builder
fmt.Fprintf(&sb, "Entire CLI %s (%s)\n", versioninfo.Version, versioninfo.Commit)
Mcmd/entire/cli/doctor_bundle.go+2/-27
75 unmodified lines
76
77
78
79
80
79
80
81
82
3 unmodified lines
86
87
88
90
91
92
93
94
95
96
97
98
99
89
90
91
5 unmodified lines
97
98
99
111
112
113
100
101
102
75 unmodified lines
}
}
// The bundle must record entire's git refs and the mirror diagnosis so
// support can debug v1.1 read issues from a bundle alone.
// The bundle must record entire's git refs.
func TestWriteDoctorBundle_CapturesEntireRefs(t *testing.T) {
t.Parallel()
3 unmodified lines
testutil.GitAdd(t, dir, "f.txt")
testutil.GitCommit(t, dir, "init")
entireDir := filepath.Join(dir, ".entire")
if err := os.MkdirAll(entireDir, 0o755); err != nil {
t.Fatalf("mkdir .entire: %v", err)
}
settingsJSON := `{"enabled": true, "strategy_options": {"checkpoints_version": "1.1"}}`
if err := os.WriteFile(filepath.Join(entireDir, "settings.json"), []byte(settingsJSON), 0o600); err != nil {
t.Fatalf("write settings: %v", err)
}
// v1 branch at HEAD with no mirror ref → diagnosis must report MISSING.
runDoctorBundleGit(t, dir, "update-ref", "refs/heads/entire/checkpoints/v1", "HEAD")
out := filepath.Join(dir, "bundle.zip")
5 unmodified lines
if !strings.Contains(content, "refs/heads/entire/checkpoints/v1") {
t.Errorf("entire-refs.txt missing v1 branch ref, got:\n%s", content)
}
if !strings.Contains(content, "mirror status: MISSING") {
t.Errorf("entire-refs.txt missing mirror diagnosis line, got:\n%s", content)
}
}
func TestWriteDoctorBundle_RedactsCredentialedRemote(t *testing.T) {
Mcmd/entire/cli/doctor_bundle_test.go+1/-15
12 unmodified lines
13
14
15
16
16
17
18
380 unmodified lines
399
400
401
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
402
403
404
12 unmodified lines
"github.com/entireio/cli/cmd/entire/cli/paths"
"github.com/entireio/cli/cmd/entire/cli/session"
"github.com/entireio/cli/cmd/entire/cli/strategy"
"github.com/entireio/cli/cmd/entire/cli/testutil"
"github.com/go-git/go-git/v6"
"github.com/go-git/go-git/v6/plumbing"
380 unmodified lines
}
}
// setupMirrorCheckRepo is setupHeadFlagsRepo plus the v1.1 settings opt-in.
func setupMirrorCheckRepo(t *testing.T) *git.Repository {
t.Helper()
repo := setupHeadFlagsRepo(t)
cwd, err := os.Getwd()
require.NoError(t, err)
require.NoError(t, os.MkdirAll(filepath.Join(cwd, paths.EntireDir), 0o755))
require.NoError(t, os.WriteFile(
filepath.Join(cwd, paths.EntireDir, paths.SettingsFileName),
[]byte(`{"enabled": true, "strategy_options": {"checkpoints_version": "1.1"}}`),
0o644,
))
return repo
}
// setMetadataV1Branch points the v1 metadata branch at HEAD and returns the hash.
func setMetadataV1Branch(t *testing.T, repo *git.Repository) plumbing.Hash {
t.Helper()
head, err := repo.Head()
require.NoError(t, err)
require.NoError(t, repo.Storer.SetReference(
plumbing.NewHashReference(plumbing.NewBranchReferenceName(paths.MetadataBranchName), head.Hash())))
return head.Hash()
}
// setMetadataMirrorRef points the v1.1 mirror ref at the given hash.
func setMetadataMirrorRef(t *testing.T, repo *git.Repository, hash plumbing.Hash) {
t.Helper()
require.NoError(t, repo.Storer.SetReference(
plumbing.NewHashReference(plumbing.ReferenceName(paths.MetadataRefName), hash)))
}
// metadataMirrorHash resolves the v1.1 mirror ref, reporting existence.
func metadataMirrorHash(t *testing.T, repo *git.Repository) (plumbing.Hash, bool) {
t.Helper()
ref, err := repo.Reference(plumbing.ReferenceName(paths.MetadataRefName), true)
if err != nil {
return plumbing.ZeroHash, false
}
return ref.Hash(), true
}
// secondCommitInCwd creates a second commit in the test repo and returns its hash.
func secondCommitInCwd(t *testing.T, repo *git.Repository) plumbing.Hash {
t.Helper()
cwd, err := os.Getwd()
require.NoError(t, err)
testutil.WriteFile(t, cwd, "f2.txt", "more")
testutil.GitAdd(t, cwd, "f2.txt")
testutil.GitCommit(t, cwd, "second")
head, err := repo.Head()
require.NoError(t, err)
return head.Hash()
}
// Not parallel: uses t.Chdir(). Setup returns the expected final mirror state.
func TestCheckCommittedMetadataMirror(t *testing.T) {
tests := []struct {
name string
v1Only bool // skip the v1.1 settings opt-in
force bool
setup func(t *testing.T, repo *git.Repository) (plumbing.Hash, bool)
wantOut []string // empty = expect no output at all
}{
{
name: "silent when not configured",
v1Only: true,
setup: func(t *testing.T, repo *git.Repository) (plumbing.Hash, bool) {
setMetadataV1Branch(t, repo)
return plumbing.ZeroHash, false
},
},
{
name: "ok",
setup: func(t *testing.T, repo *git.Repository) (plumbing.Hash, bool) {
v1 := setMetadataV1Branch(t, repo)
setMetadataMirrorRef(t, repo, v1)
return v1, true
},
wantOut: []string{"✓ Checkpoint read mirror: OK"},
},
{
name: "ok when no metadata yet",
setup: func(_ *testing.T, _ *git.Repository) (plumbing.Hash, bool) {
return plumbing.ZeroHash, false
},
wantOut: []string{"✓ Checkpoint read mirror: OK (no committed metadata yet)"},
},
{
// Warn-only anomaly: even --force must not move or delete the mirror.
name: "warns when mirror outlives v1",
force: true,
setup: func(t *testing.T, repo *git.Repository) (plumbing.Hash, bool) {
head, err := repo.Head()
require.NoError(t, err)
setMetadataMirrorRef(t, repo, head.Hash())
return head.Hash(), true
},
wantOut: []string{
"Checkpoint read mirror: V1 BRANCH MISSING",
"git fetch origin entire/checkpoints/v1:entire/checkpoints/v1",
},
},
{
name: "force seeds missing mirror",
force: true,
setup: func(t *testing.T, repo *git.Repository) (plumbing.Hash, bool) {
return setMetadataV1Branch(t, repo), true
},
wantOut: []string{"Checkpoint read mirror: MISSING", "✓ Fixed"},
},
{
name: "force advances stale mirror",
force: true,
setup: func(t *testing.T, repo *git.Repository) (plumbing.Hash, bool) {
setMetadataMirrorRef(t, repo, setMetadataV1Branch(t, repo))
secondCommitInCwd(t, repo)
return setMetadataV1Branch(t, repo), true
},
wantOut: []string{"Checkpoint read mirror: STALE", "✓ Fixed"},
},
{
name: "force resets diverged mirror",
force: true,
setup: func(t *testing.T, repo *git.Repository) (plumbing.Hash, bool) {
v1 := setMetadataV1Branch(t, repo)
setMetadataMirrorRef(t, repo, secondCommitInCwd(t, repo))
return v1, true
},
wantOut: []string{"Checkpoint read mirror: DIVERGED", "discard", "✓ Fixed"},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
var repo *git.Repository
if tt.v1Only {
repo = setupHeadFlagsRepo(t)
} else {
repo = setupMirrorCheckRepo(t)
}
wantMirror, wantExists := tt.setup(t, repo)
cmd, stdout := newTestCmd(t)
require.NoError(t, checkCommittedMetadataMirror(cmd, tt.force))
if len(tt.wantOut) == 0 {
assert.Empty(t, stdout.String())
}
for _, want := range tt.wantOut {
assert.Contains(t, stdout.String(), want)
}
gotMirror, gotExists := metadataMirrorHash(t, repo)
require.Equal(t, wantExists, gotExists)
if wantExists {
assert.Equal(t, wantMirror, gotMirror)
}
})
}
}
// Proves the mirror check is wired into the main doctor flow.
func TestRunSessionsFix_IncludesMirrorCheck(t *testing.T) {
repo := setupMirrorCheckRepo(t)
v1Hash := setMetadataV1Branch(t, repo)
cmd, stdout := newTestCmd(t)
require.NoError(t, runSessionsFix(cmd, true))
out := stdout.String()
assert.Contains(t, out, "Checkpoint read mirror: MISSING")
assert.Contains(t, out, "✓ Fixed")
got, ok := metadataMirrorHash(t, repo)
require.True(t, ok)
assert.Equal(t, v1Hash, got)
}
// TestCheckCodexHookTrust_SilentWhenCodexNotInstalled — `entire doctor`
// shouldn't print anything Codex-related when this repo doesn't have
// .codex/hooks.json. Other agents (Claude, Cursor) keep their existing
Mcmd/entire/cli/doctor_test.go-179
945 unmodified lines
946
947
948
949
950
951
952
953
949
950
951
945 unmodified lines
return fmt.Errorf("failed to save summary: %w", err)
}
refs := checkpoint.ResolveCommittedRefs(ctx)
if err := strategy.MirrorCommittedMetadataRef(ctx, stores.Repository(), refs); err != nil {
return fmt.Errorf("summary was written to %s, but failed to mirror to %s: %w", refs.Primary, refs.Mirror, err)
}
styles := newStatusStyles(w)
rows := summaryProviderRows(provider)
rows = append(rows, explainRow{Label: "duration", Value: formatSummaryDuration(elapsed)})
Mcmd/entire/cli/explain.go-5
993 unmodified lines
994
995
996
997
997
998
999
1000
2 unmodified lines
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1006
1007
1008
51 unmodified lines
1060
1061
1062
1071
1072
1073
1074
1063
1064
1065
1158 unmodified lines
2224
2225
2226
2239
2227
2228
2229
2230
14 unmodified lines
2245
2246
2247
2260
2248
2249
2250
2251
20 unmodified lines
2272
2273
2274
2287
2275
2276
2277
2278
2279
2280
2281
2294
2282
2283
2284
2285
2286
2299
2287
2288
2289
2290
2291
2292
2305
2293
2294
2295
2296
2310
2297
2298
2299
2300
2301
2315
2302
2303
2304
2305
2319
2320
2321
2306
2307
2308
2309
993 unmodified lines
}
// Not parallel: uses t.Chdir() and package-level var stubs.
func TestGenerateCheckpointSummary_MirrorsToV1CustomRefWhenOptedIn(t *testing.T) {
func TestGenerateCheckpointSummary_AdvancesV1Metadata(t *testing.T) {
ctx := context.Background()
tmpDir := t.TempDir()
testutil.InitRepo(t, tmpDir)
2 unmodified lines
testutil.GitCommit(t, tmpDir, "init")
t.Chdir(tmpDir)
entireDir := filepath.Join(tmpDir, ".entire")
require.NoError(t, os.MkdirAll(entireDir, 0o755))
require.NoError(t, os.WriteFile(
filepath.Join(entireDir, paths.SettingsFileName),
[]byte(`{"enabled":true,"strategy_options":{"checkpoints_version":"1.1"}}`),
0o644,
))
repo, err := git.PlainOpen(tmpDir)
require.NoError(t, err)
v1Refs := checkpoint.DefaultV1Refs()
51 unmodified lines
v1After, err := repo.Reference(plumbing.NewBranchReferenceName(paths.MetadataBranchName), true)
require.NoError(t, err)
require.NotEqual(t, v1Before.Hash(), v1After.Hash(), "v1 metadata branch must advance after UpdateSummary")
customRef, err := repo.Reference(plumbing.ReferenceName(paths.MetadataRefName), true)
require.NoError(t, err)
require.Equal(t, v1After.Hash(), customRef.Hash())
}
func TestGenerateCheckpointAISummary_ClampsLongParentDeadlineToDefaultTimeout(t *testing.T) {
1158 unmodified lines
require.Equal(t, "selected v1 intent", v1Metadata.Summary.Intent)
}
func TestRunExplainCheckpoint_GenerateV11ReloadsAfterV1Write(t *testing.T) {
func TestRunExplainCheckpoint_GenerateReloadsAfterV1Write(t *testing.T) {
tmpDir := t.TempDir()
t.Chdir(tmpDir)
14 unmodified lines
require.NoError(t, os.MkdirAll(filepath.Join(tmpDir, ".entire"), 0o755))
require.NoError(t, os.WriteFile(
filepath.Join(tmpDir, ".entire", "settings.json"),
[]byte(`{"enabled": true, "strategy_options": {"checkpoints_version": "1.1"}, "summary_generation": {"provider": "claude-code"}}`),
[]byte(`{"enabled": true, "summary_generation": {"provider": "claude-code"}}`),
0o644,
))
20 unmodified lines
_ types.AgentType,
_ summarize.Generator,
) (*checkpoint.Summary, error) {
return &checkpoint.Summary{Intent: "generated v1.1 intent", Outcome: "generated v1.1 outcome"}, nil
return &checkpoint.Summary{Intent: "generated v1 intent", Outcome: "generated v1 outcome"}, nil
}
v1Store := checkpoint.NewGitStore(repo, checkpoint.DefaultV1Refs())
cpID := id.MustCheckpointID("bbccddee1122")
ctx := context.Background()
transcript := []byte(`{"type":"user","message":{"content":[{"type":"text","text":"generate v1.1 test"}]}}` + "\n" +
transcript := []byte(`{"type":"user","message":{"content":[{"type":"text","text":"generate v1 test"}]}}` + "\n" +
`{"type":"assistant","message":{"content":"done"}}` + "\n")
require.NoError(t, v1Store.WriteCommitted(ctx, checkpoint.WriteCommittedOptions{
CheckpointID: cpID,
SessionID: "session-v11",
SessionID: "session-v1",
Strategy: "manual-commit",
Transcript: redact.AlreadyRedacted(transcript),
AuthorName: "Test",
AuthorEmail: "test@example.com",
}))
require.NoError(t, strategy.MirrorCommittedMetadataRef(ctx, repo, checkpoint.ResolveCommittedRefs(ctx)))
var buf, errBuf bytes.Buffer
err = runExplainCheckpoint(ctx, &buf, &errBuf, "bbccdd", false, false, false, false, true, true, false, 0)
require.NoError(t, err)
require.Contains(t, buf.String(), "generated v1.1 intent")
require.Contains(t, buf.String(), "generated v1 intent")
v1Metadata, err := v1Store.ReadSessionMetadata(ctx, cpID, 0)
require.NoError(t, err)
require.NotNil(t, v1Metadata.Summary)
require.Equal(t, "generated v1.1 intent", v1Metadata.Summary.Intent)
require.Equal(t, "generated v1 intent", v1Metadata.Summary.Intent)
v1Ref, err := repo.Reference(plumbing.NewBranchReferenceName(paths.MetadataBranchName), true)
require.NoError(t, err)
customRef, err := repo.Reference(plumbing.ReferenceName(paths.MetadataRefName), true)
require.NoError(t, err)
require.Equal(t, v1Ref.Hash(), customRef.Hash(), "summary generation should mirror the v1 write to v1.1")
require.False(t, v1Ref.Hash().IsZero())
}
func TestRunExplainCheckpoint_DefaultViewUsesV1Transcript(t *testing.T) {
Mcmd/entire/cli/explain_test.go+9/-24
471 unmodified lines
472
473
474
475
476
477
478
479
475
476
477
471 unmodified lines
if err := strategy.SafelyAdvanceLocalRef(ctx, repo, refs.Primary, remoteRef.Hash()); err != nil {
return fmt.Errorf("failed to advance local %s branch: %w", branchName, err)
}
if err := strategy.MirrorCommittedMetadataRef(ctx, repo, refs); err != nil && !errors.Is(err, strategy.ErrPrimaryMetadataMissing) {
logging.Warn(ctx, "committed-ref mirror failed after origin fetch",
slog.String("ref", refs.Mirror.String()),
slog.String("error", err.Error()))
}
return nil
}
Mcmd/entire/cli/git_operations.go-5
7 unmodified lines
8
9
10
11
11
12
13
698 unmodified lines
712
713
714
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
715
716
717
7 unmodified lines
"strings"
"testing"
"github.com/entireio/cli/cmd/entire/cli/paths"
"github.com/entireio/cli/cmd/entire/cli/testutil"
"github.com/go-git/go-git/v6"
698 unmodified lines
assert.Equal(t, "origin", target)
}
// Not parallel: uses t.Chdir().
func TestFetchMetadataBranch_MirrorsV11Ref(t *testing.T) {
ctx := context.Background()
remoteDir := t.TempDir()
testutil.InitRepo(t, remoteDir)
testutil.WriteFile(t, remoteDir, "f.txt", "init")
testutil.GitAdd(t, remoteDir, "f.txt")
testutil.GitCommit(t, remoteDir, "init")
defaultBranch := gitDefaultBranch(t, remoteDir)
gitRun(t, remoteDir, "checkout", "--orphan", paths.MetadataBranchName)
gitRun(t, remoteDir, "rm", "-rf", ".")
testutil.WriteFile(t, remoteDir, "metadata.json", `{"version": 1}`)
testutil.GitAdd(t, remoteDir, "metadata.json")
gitRun(t, remoteDir, "-c", "commit.gpgsign=false", "commit", "-m", "checkpoint metadata")
gitRun(t, remoteDir, "checkout", defaultBranch)
localDir := t.TempDir()
testutil.InitRepo(t, localDir)
testutil.WriteFile(t, localDir, "f.txt", "init")
testutil.GitAdd(t, localDir, "f.txt")
testutil.GitCommit(t, localDir, "init")
gitRun(t, localDir, "remote", "add", "origin", remoteDir)
require.NoError(t, os.MkdirAll(filepath.Join(localDir, ".entire"), 0o755))
require.NoError(t, os.WriteFile(
filepath.Join(localDir, ".entire", paths.SettingsFileName),
[]byte(`{"enabled": true, "strategy_options": {"checkpoints_version": "1.1"}}`),
0o644,
))
t.Chdir(localDir)
paths.ClearWorktreeRootCache()
require.NoError(t, FetchMetadataBranch(ctx))
v1Hash := gitOutput(t, localDir, "rev-parse", paths.MetadataBranchName)
mirrorHash := gitOutput(t, localDir, "rev-parse", paths.MetadataRefName)
assert.Equal(t, v1Hash, mirrorHash)
}
// setupRepoWithBlobOnMetadataBranch creates a repo with a blob committed on
// entire/checkpoints/v1, checks out the default branch, and returns
// (repoDir, blobHash) for tests that need a reachable blob on the metadata branch.
Mcmd/entire/cli/git_operations_test.go-43
2 unmodified lines
3
4
5
6
6
7
8
3 unmodified lines
12
13
14
16
15
16
17
116 unmodified lines
134
135
136
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
2 unmodified lines
import (
"context"
"os"
"path/filepath"
"strings"
"testing"
3 unmodified lines
"github.com/entireio/cli/cmd/entire/cli/testutil"
"github.com/entireio/cli/redact"
"github.com/go-git/go-git/v6"
"github.com/go-git/go-git/v6/plumbing"
"github.com/stretchr/testify/require"
)
116 unmodified lines
require.False(t, hasInvestigation, "wrapper must not piggyback on HasReview")
require.Empty(t, info, "info must be empty when the wrapper returns false")
}
func TestHeadCheckpointFlags_V11ReadsCustomRefAsIs(t *testing.T) {
repo := setupHeadFlagsRepo(t)
cwd, err := os.Getwd()
require.NoError(t, err)
require.NoError(t, os.MkdirAll(filepath.Join(cwd, paths.EntireDir), 0o755))
require.NoError(t, os.WriteFile(
filepath.Join(cwd, paths.EntireDir, paths.SettingsFileName),
[]byte(`{"enabled": true, "strategy_options": {"checkpoints_version": "1.1"}}`),
0o644,
))
cpID := writeHeadCheckpointWithFlags(t, repo, true, true)
v1Ref, err := repo.Reference(plumbing.NewBranchReferenceName(paths.MetadataBranchName), true)
require.NoError(t, err)
require.NoError(t, repo.Storer.SetReference(plumbing.NewHashReference(plumbing.ReferenceName(paths.MetadataRefName), v1Ref.Hash())))
writeHeadCheckpointWithFlags(t, repo, false, false)
hasReview, hasInvestigation, info := headCheckpointFlags(context.Background())
require.True(t, hasReview, "v1.1 reads must use the custom ref, not the diverged v1 branch")
require.True(t, hasInvestigation, "v1.1 reads must use the custom ref, not the diverged v1 branch")
require.Contains(t, info, cpID.String())
}
Mcmd/entire/cli/head_checkpoint_flags_test.go-26
2 unmodified lines
3
4
5
6
6
7
8
9
10
11
13
12
13
14
348 unmodified lines
363
364
365
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
2 unmodified lines
package integration
import (
"bytes"
"os"
"os/exec"
"path/filepath"
"strings"
"testing"
"github.com/entireio/cli/cmd/entire/cli/testutil"
"github.com/entireio/cli/cmd/entire/cli/trailers"
)
348 unmodified lines
t.Error("expected error for invalid session ID")
}
}
// TestAttach_MirrorsToV1CustomRefWhenOptedIn verifies that running attach
// through the real entire binary with checkpoints_version "1.1" leaves
// refs/entire/checkpoints/v1.1 at the same hash as entire/checkpoints/v1.
func TestAttach_MirrorsToV1CustomRefWhenOptedIn(t *testing.T) {
t.Parallel()
env := NewFeatureBranchEnv(t)
env.PatchSettings(map[string]any{
"strategy_options": map[string]any{"checkpoints_version": "1.1"},
})
sessionID := "attach-v1-1-mirror"
tb := NewTranscriptBuilder()
tb.AddUserMessage("hello")
tb.AddAssistantMessage("hi")
transcriptPath := filepath.Join(env.ClaudeProjectDir, sessionID+".jsonl")
if err := tb.WriteToFile(transcriptPath); err != nil {
t.Fatalf("failed to write transcript: %v", err)
}
env.RunCLI("session", "attach", sessionID, "-a", "claude-code", "-f")
v1 := revParse(t, env.RepoDir, "entire/checkpoints/v1")
custom := revParse(t, env.RepoDir, "refs/entire/checkpoints/v1.1")
if v1 != custom {
t.Errorf("refs/entire/checkpoints/v1.1 = %s, want %s (entire/checkpoints/v1)", custom, v1)
}
}
func revParse(t *testing.T, dir, ref string) string {
t.Helper()
cmd := exec.CommandContext(t.Context(), "git", "rev-parse", "--verify", ref)
cmd.Dir = dir
cmd.Env = testutil.GitIsolatedEnv()
var stderr bytes.Buffer
cmd.Stderr = &stderr
out, err := cmd.Output()
if err != nil {
t.Fatalf("git rev-parse %s in %s failed: %v\n%s", ref, dir, err, stderr.String())
}
return strings.TrimSpace(string(out))
}
Mcmd/entire/cli/integration_test/attach_test.go-45
67 unmodified lines
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
71
72
73
67 unmodified lines
}
}
// TestPrePush_PushesV1CustomRefWhenOptedIn verifies that with
// checkpoints_version "1.1", PrePush pushes the v1.1 ref to the remote at the v1 tip.
func TestPrePush_PushesV1CustomRefWhenOptedIn(t *testing.T) {
t.Parallel()
env := NewFeatureBranchEnv(t)
// Opt in before session activity so condensation mirrors v1.1.
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")
if !env.BranchExistsOnRemote(bareDir, paths.MetadataBranchName) {
t.Fatalf("%s should exist on bare remote after PrePush", paths.MetadataBranchName)
}
// v1.1 must exist on the remote at the v1 tip (revParse fails if 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)
}
}
// TestPrePush_NoOpWhenNoCheckpoints verifies that PrePush is a no-op
// when no sessions or checkpoints exist.
func TestPrePush_NoOpWhenNoCheckpoints(t *testing.T) {
Mcmd/entire/cli/integration_test/remote_operations_test.go-41
37 unmodified lines
38
39
40
41
42
43
44
45
46
47
48
41
42
43
37 unmodified lines
// MetadataBranchName is the orphan branch used by manual-commit strategy to store metadata
const MetadataBranchName = "entire/checkpoints/v1"
// MetadataRefName is the v1 custom ref that committed metadata is mirrored to
// when checkpoints_version is "1.1". It lives under refs/entire/ (not
// refs/heads/) so it stays invisible to `git branch -a` and is not pulled by a
// default `git clone`. v1 remains the source of truth; this ref mirrors it.
// When v1.1 is enabled, committed reads resolve against this ref, active v1
// write/fetch paths update the mirror, and PrePush pushes it alongside v1.
const MetadataRefName = "refs/entire/checkpoints/v1.1"
// TrailsBranchName is the orphan branch used to store trail metadata.
// Trails are branch-centric work tracking abstractions that link to checkpoints by branch name.
const TrailsBranchName = "entire/trails/v1"
Mcmd/entire/cli/paths/paths.go-8
681 unmodified lines
682
683
684
685
686
685
686
687
688
681 unmodified lines
}
// checkRemoteMetadata checks if checkpoint metadata exists on the remote and
// fetches it if available. Skips when reads don't target a ref origin tracks
// (e.g. the local-only v1.1 mirror).
// fetches it if available. Skips when reads don't target a ref origin tracks.
func checkRemoteMetadata(
ctx context.Context,
w, errW io.Writer,
Mcmd/entire/cli/resume.go+1/-2
545 unmodified lines
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
549
550
551
137 unmodified lines
689
690
691
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
692
693
694
222 unmodified lines
917
918
919
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
920
921
922
545 unmodified lines
}
}
func mirrorMetadataBranchToV11Ref(t *testing.T, repo *git.Repository) {
t.Helper()
v1Ref, err := repo.Reference(plumbing.NewBranchReferenceName(paths.MetadataBranchName), true)
if err != nil {
t.Fatalf("read v1 metadata branch: %v", err)
}
if err := repo.Storer.SetReference(plumbing.NewHashReference(plumbing.ReferenceName(paths.MetadataRefName), v1Ref.Hash())); err != nil {
t.Fatalf("set v1.1 metadata ref: %v", err)
}
}
func enableResumeV11(t *testing.T, repoRoot string) {
t.Helper()
t.Setenv("ENTIRE_TEST_CLAUDE_PROJECT_DIR", filepath.Join(repoRoot, "claude-projects"))
if err := os.MkdirAll(filepath.Join(repoRoot, ".entire"), 0o755); err != nil {
t.Fatalf("create settings dir: %v", err)
}
settingsPath := filepath.Join(repoRoot, ".entire", paths.SettingsFileName)
settingsJSON := []byte(`{"enabled": true, "strategy_options": {"checkpoints_version": "1.1"}}`)
if err := os.WriteFile(settingsPath, settingsJSON, 0o644); err != nil {
t.Fatalf("write settings: %v", err)
}
}
func commitResumeTrailer(t *testing.T, worktree *git.Worktree, repoRoot, fileName, commitMessage string) {
t.Helper()
137 unmodified lines
}
}
func TestResumeFromCurrentBranch_UsesV11MetadataOnly(t *testing.T) {
tmpDir := t.TempDir()
t.Chdir(tmpDir)
repo, worktree, _ := setupResumeTestRepo(t, tmpDir, false)
enableResumeV11(t, tmpDir)
cpID := id.MustCheckpointID("b1b2b3b4b5b6")
sessionID := "session-v11-only"
writeCommittedResumeCheckpoint(t, repo, cpID, sessionID, time.Date(2025, 1, 2, 10, 0, 0, 0, time.UTC))
mirrorMetadataBranchToV11Ref(t, repo)
if err := repo.Storer.RemoveReference(plumbing.NewBranchReferenceName(paths.MetadataBranchName)); err != nil {
t.Fatalf("remove v1 metadata branch: %v", err)
}
commitResumeTrailer(t, worktree, tmpDir, "feature-v11-only.txt", "Add feature\n\nEntire-Checkpoint: "+cpID.String())
var stdout, stderr bytes.Buffer
if err := resumeFromCurrentBranch(context.Background(), &stdout, &stderr, "master", true); err != nil {
t.Fatalf("resumeFromCurrentBranch error: %v\nstdout: %s\nstderr: %s", err, stdout.String(), stderr.String())
}
combined := stdout.String() + stderr.String()
if !strings.Contains(combined, sessionID) {
t.Fatalf("resume did not read v1.1 metadata for session %q:\n%s", sessionID, combined)
}
if strings.Contains(combined, "found in commit but the entire/checkpoints/v1 branch is not available") {
t.Fatalf("resume fell through to missing-v1 metadata message despite v1.1 metadata:\n%s", combined)
}
}
func TestResolveLatestCheckpoint_V11DoesNotFallbackToStaleV1(t *testing.T) {
tmpDir := t.TempDir()
t.Chdir(tmpDir)
repo, _, _ := setupResumeTestRepo(t, tmpDir, false)
enableResumeV11(t, tmpDir)
baseHash := readMetadataBranchHash(t, repo)
customOnlyID := id.MustCheckpointID("c1c2c3c4c5c6")
writeCommittedResumeCheckpoint(t, repo, customOnlyID, "session-custom-only", time.Date(2025, 1, 2, 10, 0, 0, 0, time.UTC))
mirrorMetadataBranchToV11Ref(t, repo)
v1RefName := plumbing.NewBranchReferenceName(paths.MetadataBranchName)
if err := repo.Storer.SetReference(plumbing.NewHashReference(v1RefName, baseHash)); err != nil {
t.Fatalf("reset v1 metadata branch: %v", err)
}
staleV1ID := id.MustCheckpointID("d1d2d3d4d5d6")
writeCommittedResumeCheckpoint(t, repo, staleV1ID, "session-stale-v1", time.Date(2025, 1, 3, 10, 0, 0, 0, time.UTC))
store := checkpoint.NewGitStore(repo, checkpoint.ResolveCommittedRefs(context.Background()))
store.SetBlobFetcher(FetchBlobsByHash)
_, err := resolveLatestCheckpoint(context.Background(), store, []id.CheckpointID{staleV1ID})
if err == nil {
t.Fatal("resolveLatestCheckpoint found checkpoint from stale v1 even though v1.1 custom ref differs")
}
}
func TestResumeFromCurrentBranch_V11DoesNotSeedFromV1(t *testing.T) {
tmpDir := t.TempDir()
t.Chdir(tmpDir)
repo, worktree, _ := setupResumeTestRepo(t, tmpDir, false)
enableResumeV11(t, tmpDir)
cpID := id.MustCheckpointID("1122aabbccdd")
sessionID := "session-v1-only"
writeCommittedResumeCheckpoint(t, repo, cpID, sessionID, time.Date(2025, 1, 2, 10, 0, 0, 0, time.UTC))
commitResumeTrailer(t, worktree, tmpDir, "feature-v1-only.txt", "Add feature\n\nEntire-Checkpoint: "+cpID.String())
combined := stdout.String() + stderr.String()
if strings.Contains(combined, sessionID) {
t.Fatalf("resume used v1 metadata for session %q in v1.1 mode:\n%s", sessionID, combined)
}
if !strings.Contains(stderr.String(), paths.MetadataRefName) {
t.Fatalf("resume did not report missing v1.1 metadata ref:\nstdout: %s\nstderr: %s", stdout.String(), stderr.String())
}
if strings.Contains(combined, "git fetch origin entire/checkpoints/v1") {
t.Fatalf("resume suggested v1 fetch in v1.1 mode:\n%s", combined)
}
if !strings.Contains(stderr.String(), "entire explain "+cpID.String()) {
t.Fatalf("resume did not suggest 'entire explain' for missing v1.1 metadata:\nstderr: %s", stderr.String())
}
}
func TestResumeFromCurrentBranch_V11SquashUsesLatestMetadataTimestamp(t *testing.T) {
tmpDir := t.TempDir()
t.Chdir(tmpDir)
repo, worktree, _ := setupResumeTestRepo(t, tmpDir, false)
enableResumeV11(t, tmpDir)
olderID := id.MustCheckpointID("e1e2e3e4e5e6")
newerID := id.MustCheckpointID("f1f2f3f4f5f6")
olderSession := "session-v11-older"
newerSession := "session-v11-newer"
writeCommittedResumeCheckpoint(t, repo, olderID, olderSession, time.Date(2025, 1, 2, 10, 0, 0, 0, time.UTC))
writeCommittedResumeCheckpoint(t, repo, newerID, newerSession, time.Date(2025, 1, 2, 11, 0, 0, 0, time.UTC))
mirrorMetadataBranchToV11Ref(t, repo)
if err := repo.Storer.RemoveReference(plumbing.NewBranchReferenceName(paths.MetadataBranchName)); err != nil {
t.Fatalf("remove v1 metadata branch: %v", err)
}
squashMsg := fmt.Sprintf("Squash feature\n\nEntire-Checkpoint: %s\n\nEntire-Checkpoint: %s\n", olderID, newerID)
commitResumeTrailer(t, worktree, tmpDir, "feature-v11-squash.txt", squashMsg)
combined := stdout.String() + stderr.String()
if !strings.Contains(combined, "resuming from the latest") {
t.Fatalf("resume did not report latest-checkpoint selection:\n%s", combined)
}
if !strings.Contains(combined, newerSession) {
t.Fatalf("resume did not use newest v1.1 metadata session %q:\n%s", newerSession, combined)
}
if strings.Contains(combined, olderSession) {
t.Fatalf("resume used older v1.1 metadata session %q:\n%s", olderSession, combined)
}
}
func TestFindCheckpointInHistory_MultipleCheckpoints(t *testing.T) {
tmpDir := t.TempDir()
t.Chdir(tmpDir)
222 unmodified lines
}
}
func TestResumeSingleSession_UsesV11Transcript(t *testing.T) {
tmpDir := t.TempDir()
t.Chdir(tmpDir)
repo, _, _ := setupResumeTestRepo(t, tmpDir, false)
enableResumeV11(t, tmpDir)
ctx := context.Background()
cpID := id.MustCheckpointID("bca123bca123")
sessionID := "resume-v11-session"
v11Raw := []byte(`{"type":"user","message":{"content":[{"type":"text","text":"resume from v11"}]}}` + "\n")
staleV1Raw := []byte(`{"type":"user","message":{"content":[{"type":"text","text":"stale v1"}]}}` + "\n")
writeCommittedResumeCheckpointWithTranscript(
t,
repo,
cpID,
sessionID,
time.Date(2025, 1, 2, 10, 0, 0, 0, time.UTC),
agent.AgentTypeClaudeCode,
v11Raw,
)
mirrorMetadataBranchToV11Ref(t, repo)
writeCommittedResumeCheckpointWithTranscript(
t,
repo,
cpID,
sessionID,
time.Date(2025, 1, 3, 10, 0, 0, 0, time.UTC),
agent.AgentTypeClaudeCode,
staleV1Raw,
)
ag := &recordingResumeAgent{sessionDir: filepath.Join(tmpDir, "sessions")}
var stdout, stderr bytes.Buffer
if err := resumeSingleSession(ctx, &stdout, &stderr, ag, sessionID, cpID, tmpDir, true); err != nil {
t.Fatalf("resumeSingleSession() error = %v\nstdout: %s\nstderr: %s", err, stdout.String(), stderr.String())
}
if ag.writtenSession == nil {
t.Fatal("resumeSingleSession() did not restore a session")
}
if string(ag.writtenSession.NativeData) != string(v11Raw) {
t.Fatalf("restored transcript = %q, want v1.1 transcript %q", string(ag.writtenSession.NativeData), string(v11Raw))
}
}
func TestCheckRemoteMetadata_MetadataExistsOnRemote(t *testing.T) {
tmpDir := t.TempDir()
t.Chdir(tmpDir)
Mcmd/entire/cli/resume_test.go-207
12 unmodified lines
13
14
15
16
16
17
18
57 unmodified lines
76
77
78
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
79
80
81
331 unmodified lines
413
414
415
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
416
417
418
12 unmodified lines
"time"
git "github.com/go-git/go-git/v6"
"github.com/go-git/go-git/v6/plumbing"
"github.com/entireio/cli/cmd/entire/cli/agent"
"github.com/entireio/cli/cmd/entire/cli/agent/types"
57 unmodified lines
}
}
// Review committed-context reads resolve against the v1 custom ref when the
// mirror is enabled, and the v1 branch otherwise. No t.Parallel: t.Chdir drives
// settings.
func TestReviewCheckpointContext_ReadsV1CustomRefWhenEnabled(t *testing.T) {
repoRoot := newReviewContextRepo(t)
t.Chdir(repoRoot)
const cpID = "c1d2e3f4a5b6"
writeReviewContextCheckpointCustomRefOnly(t, repoRoot, cpID, reviewContextCheckpointOptions{
agentType: agent.AgentTypeClaudeCode,
summary: &checkpoint.Summary{Intent: "custom-ref-only checkpoint", Outcome: "read via custom ref"},
})
commitReviewContextChange(t, repoRoot, "cp.go", "cp\n", "cp change", "Entire-Checkpoint: "+cpID)
const wantDetail = "summary: custom-ref-only checkpoint; read via custom ref"
// Mirror disabled: reads hit the v1 branch, which no longer holds the checkpoint.
if got := reviewCheckpointContext(context.Background(), repoRoot, "master"); strings.Contains(got, wantDetail) {
t.Fatalf("checkpoint detail leaked with mirror disabled:\n%s", got)
}
// Mirror enabled: reads hit the custom ref.
enableV1CustomRefMirror(t, repoRoot)
if got := reviewCheckpointContext(context.Background(), repoRoot, "master"); !strings.Contains(got, wantDetail) {
t.Fatalf("checkpoint detail missing with mirror enabled:\n%s", got)
}
}
func TestReviewCheckpointContext_CapsCheckpointLines(t *testing.T) {
t.Parallel()
331 unmodified lines
}
}
// writeReviewContextCheckpointCustomRefOnly writes a checkpoint, then points the
// custom ref at it and drops the v1 branch so it is reachable only via the
// custom ref.
func writeReviewContextCheckpointCustomRefOnly(t *testing.T, repoRoot, checkpointID string, opts reviewContextCheckpointOptions) {
t.Helper()
writeReviewContextCheckpoint(t, repoRoot, checkpointID, opts)
repo, err := git.PlainOpen(repoRoot)
if err != nil {
t.Fatalf("open repo: %v", err)
}
v1Branch := plumbing.NewBranchReferenceName(paths.MetadataBranchName)
v1Ref, err := repo.Reference(v1Branch, true)
if err != nil {
t.Fatalf("resolve v1 metadata branch: %v", err)
}
customRef := plumbing.ReferenceName(paths.MetadataRefName)
if err := repo.Storer.SetReference(plumbing.NewHashReference(customRef, v1Ref.Hash())); err != nil {
t.Fatalf("point custom ref at v1 tip: %v", err)
}
if err := repo.Storer.RemoveReference(v1Branch); err != nil {
t.Fatalf("remove v1 metadata branch: %v", err)
}
}
// enableV1CustomRefMirror enables the v1 custom-ref mirror in repo settings.
func enableV1CustomRefMirror(t *testing.T, repoRoot string) {
t.Helper()
entireDir := filepath.Join(repoRoot, ".entire")
if err := os.MkdirAll(entireDir, 0o750); err != nil {
t.Fatalf("create .entire dir: %v", err)
}
body := `{"enabled":true,"strategy_options":{"checkpoints_version":"1.1"}}` + "\n"
if err := os.WriteFile(filepath.Join(entireDir, paths.SettingsFileName), []byte(body), 0o600); err != nil {
t.Fatalf("write settings: %v", err)
}
}
func installReviewContextClaudeHooks(t *testing.T) {
t.Helper()
ag, err := agent.Get(agent.AgentNameClaudeCode)
Mcmd/entire/cli/review_context_test.go-67
117 unmodified lines
118
119
120
121
122
123
124
125
126
127
128
121
122
123
117 unmodified lines
return err
}
repo, err := OpenRepository(ctx)
if err != nil {
logging.Warn(ctx, "committed-ref mirror skipped after metadata fetch",
slog.String("error", err.Error()))
return nil
}
defer repo.Close()
mirrorCommittedMetadataRefBestEffort(ctx, repo, refs)
return nil
}
Mcmd/entire/cli/strategy/checkpoint_remote.go-8
659 unmodified lines
660
661
662
663
664
665
666
667
668
663
664
665
36 unmodified lines
702
703
704
711
712
705
706
707
659 unmodified lines
testutil.WriteFile(t, localDir, "f.txt", "init")
testutil.GitAdd(t, localDir, "f.txt")
testutil.GitCommit(t, localDir, "init")
require.NoError(t, os.MkdirAll(filepath.Join(localDir, ".entire"), 0o755))
require.NoError(t, os.WriteFile(
filepath.Join(localDir, ".entire", paths.SettingsFileName),
[]byte(`{"enabled": true, "strategy_options": {"checkpoints_version": "1.1"}}`),
0o644,
))
t.Chdir(localDir)
paths.ClearWorktreeRootCache()
36 unmodified lines
hash2 := strings.TrimSpace(string(hash2Out))
assert.NotEqual(t, hash1, hash2, "FetchMetadataBranch should update existing local branch to new remote tip")
assert.Equal(t, hash2, checkpointRemoteRevParse(ctx, t, localDir, paths.MetadataRefName),
"FetchMetadataBranch should mirror fetched v1 metadata to the v1.1 custom ref")
}
// TestFetchMetadataBranch_DoesNotRewindLocalAhead verifies that calling
Mcmd/entire/cli/strategy/checkpoint_remote_test.go-8
1 unmodified line
2
3
4
5
5
7
6
7
8
466 unmodified lines
475
476
477
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
478
479
480
1 unmodified line
import (
"context"
"os"
"os/exec"
"path/filepath"
"strings"
"testing"
"time"
466 unmodified lines
}
}
// In v1.1 mode, a session whose checkpoint lives only on v1 must be flagged
// orphaned because the topology read goes to the (unset) mirror.
func TestListOrphanedSessionStates_V11ReadsViaTopology(t *testing.T) {
dir := t.TempDir()
testutil.InitRepo(t, dir)
testutil.WriteFile(t, dir, "f.txt", "init")
testutil.GitAdd(t, dir, "f.txt")
testutil.GitCommit(t, dir, "init")
t.Chdir(dir)
repo, err := git.PlainOpen(dir)
require.NoError(t, err)
const sessionID = "test-session-v11-orphan"
cpID := id.MustCheckpointID("b2c3d4e5f6a1")
require.NoError(t, checkpoint.NewGitStore(repo, checkpoint.DefaultV1Refs()).WriteCommitted(t.Context(), checkpoint.WriteCommittedOptions{
CheckpointID: cpID,
SessionID: sessionID,
Strategy: "manual-commit",
Transcript: redact.AlreadyRedacted([]byte("transcript\n")),
Prompts: []string{"prompt"},
AuthorName: "Test",
AuthorEmail: "test@test.com",
}))
// BaseCommit is arbitrary; no shadow branch is created, so any value routes
// through the same orphan path. StartedAt clears the grace window.
state := &SessionState{
SessionID: sessionID,
BaseCommit: "0000000000000000000000000000000000000000",
StartedAt: time.Now().Add(-(sessionGracePeriod + time.Minute)),
StepCount: 1,
}
require.NoError(t, SaveSessionState(t.Context(), state))
settingsDir := filepath.Join(dir, ".entire")
require.NoError(t, os.MkdirAll(settingsDir, 0o755))
require.NoError(t, os.WriteFile(
filepath.Join(settingsDir, paths.SettingsFileName),
[]byte(`{"enabled": true, "strategy_options": {"checkpoints_version": "1.1"}}`),
0o644,
))
orphans, err := ListOrphanedSessionStates(t.Context())
require.NoError(t, err)
var flagged bool
for _, item := range orphans {
if item.ID == sessionID {
flagged = true
break
}
}
assert.True(t, flagged, "session must be flagged orphaned: mirror is unset, so topology read returns no checkpoints")
}
// Archived sessions of a multi-session condensed checkpoint must not be
// flagged as orphaned: their IDs appear in cp.SessionIDs even though
// cp.SessionID is the most-recent session.
Mcmd/entire/cli/strategy/clean_test.go-59
335 unmodified lines
336
337
338
339
340
339
340
341
342
335 unmodified lines
return nil, nil, fmt.Errorf("failed to store commit: %w", err)
}
// Update branch reference and best-effort mirror
if err := AdvanceCommittedPrimary(ctx, repo, refs, commitHash); err != nil {
if err := setRefHash(repo, refs.Primary, commitHash); err != nil {
return nil, nil, fmt.Errorf("failed to update branch: %w", err)
}
Mcmd/entire/cli/strategy/cleanup.go+1/-2
480 unmodified lines
481
482
483
484
484
485
486
487
15 unmodified lines
503
504
505
506
506
507
508
509
49 unmodified lines
559
560
561
562
562
563
564
565
480 unmodified lines
}
if isEmpty {
// Empty orphan — just point to remote
if setErr := AdvanceCommittedPrimary(ctx, repo, refs, remoteRef.Hash()); setErr != nil {
if setErr := setRefHash(repo, refs.Primary, remoteRef.Hash()); setErr != nil {
return fmt.Errorf("failed to update metadata ref from remote: %w", setErr)
}
fmt.Fprintf(os.Stderr, "[entire] Updated local ref '%s' from origin\n", primaryName)
15 unmodified lines
// Local ref doesn't exist — create from remote if available
if remoteRef != nil {
if err := AdvanceCommittedPrimary(ctx, repo, refs, remoteRef.Hash()); err != nil {
if err := setRefHash(repo, refs.Primary, remoteRef.Hash()); err != nil {
return fmt.Errorf("failed to create metadata ref from remote: %w", err)
}
fmt.Fprintf(os.Stderr, "✓ Created local ref '%s' from origin\n", primaryName)
49 unmodified lines
return fmt.Errorf("failed to store orphan commit: %w", err)
}
if err := AdvanceCommittedPrimary(ctx, repo, refs, commitHash); err != nil {
if err := setRefHash(repo, refs.Primary, commitHash); err != nil {
return fmt.Errorf("failed to create metadata ref: %w", err)
}
Mcmd/entire/cli/strategy/common.go+3/-3
1141 unmodified lines
1142
1143
1144
1145
1146
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1150
1151
1152
2 unmodified lines
1155
1156
1157
1164
1158
1159
1166
1167
1168
1169
1160
1161
1162
1141 unmodified lines
}
}
// Not parallel: uses t.Chdir so settings.Load picks up the v1.1 opt-in.
func TestEnsurePrimaryRef_MirrorsV11WhenSeedingFromRemote(t *testing.T) {
// Not parallel: uses t.Chdir.
func TestEnsurePrimaryRef_SeedsV1FromRemote(t *testing.T) {
bareDir := initBareWithMetadataBranch(t)
cloneDir, _ := cloneWithConfig(t, bareDir)
require.NoError(t, os.MkdirAll(filepath.Join(cloneDir, ".entire"), 0o755))
require.NoError(t, os.WriteFile(
filepath.Join(cloneDir, ".entire", paths.SettingsFileName),
[]byte(`{"enabled": true, "strategy_options": {"checkpoints_version": "1.1"}}`),
0o644,
))
t.Chdir(cloneDir)
paths.ClearWorktreeRootCache()
2 unmodified lines
require.NoError(t, EnsurePrimaryRef(t.Context(), repo))
v1Ref, err := repo.Reference(plumbing.NewBranchReferenceName(paths.MetadataBranchName), true)
_, err = repo.Reference(plumbing.NewBranchReferenceName(paths.MetadataBranchName), true)
require.NoError(t, err, "local v1 branch should be seeded from origin")
mirrorRef, err := repo.Reference(plumbing.ReferenceName(paths.MetadataRefName), true)
require.NoError(t, err, "v1.1 mirror should track the v1 write performed by EnsurePrimaryRef")
assert.Equal(t, v1Ref.Hash(), mirrorRef.Hash())
}
// cloneWithConfig clones bareDir into a new temp directory, configures git identity,
Mcmd/entire/cli/strategy/common_test.go+3/-13
290 unmodified lines
291
292
293
294
295
296
297
294
295
296
290 unmodified lines
// report the same count instead of the second showing 0.
state.PromptWindowResetPending = true
// Mirror the committed write to refs.Mirror when configured (best-effort;
// failures are logged, not fatal).
mirrorCommittedMetadataRefBestEffort(ctx, repo, store.Refs())
logging.Debug(logCtx, "condense timings",
slog.String("session_id", state.SessionID),
slog.String("checkpoint_id", checkpointID.String()),
Mcmd/entire/cli/strategy/manual_commit_condensation.go-4
1161 unmodified lines
1162
1163
1164
1165
1166
1167
1168
1165
1166
1167
1675 unmodified lines
2843
2844
2845
2850
2851
2852
2853
2854
2846
2847
2848
1161 unmodified lines
return fmt.Errorf("persisting combined attribution: %w", err)
}
// Combined attribution is a committed write in the post-commit hook, so the
// mirror must track it too when configured (best-effort).
mirrorCommittedMetadataRefBestEffort(ctx, repo, stores.Refs())
return nil
}
1675 unmodified lines
)
}
// Mirror the finalized primary metadata to refs.Mirror when configured
// (best-effort; failures are logged, not fatal). Once after the loop is
// enough — it tracks Primary's final commit.
mirrorCommittedMetadataRefBestEffort(ctx, repo, stores.Refs())
// Clear turn checkpoint IDs. Do NOT update CheckpointTranscriptStart here — it was
// already set correctly by PostCommit: condenseAndUpdateState sets it to the total
// transcript lines when condensing, and carryForwardToNewShadowBranch resets it to 0
Mcmd/entire/cli/strategy/manual_commit_hooks.go-9
1 unmodified line
2
3
4
5
5
6
8
7
8
9
21 unmodified lines
31
32
33
36
37
34
35
36
6 unmodified lines
43
44
45
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
1 unmodified line
import (
"context"
"log/slog"
"github.com/entireio/cli/cmd/entire/cli/checkpoint"
"github.com/entireio/cli/cmd/entire/cli/logging"
"github.com/entireio/cli/perf"
)
21 unmodified lines
refs := checkpoint.ResolveCommittedRefs(ctx)
refreshMirrorBeforePush(ctx, refs)
// Thread the span's context into the push so the network push and any
// fetch+rebase recovery nest beneath it as child steps in the perf trace.
pushCtx, pushCheckpointsSpan := perf.Start(ctx, "push_checkpoint_refs")
6 unmodified lines
}
return nil
}
// refreshMirrorBeforePush advances the mirror to the primary tip before
// pushing. Best-effort: failures are logged, never blocking the push.
func refreshMirrorBeforePush(ctx context.Context, refs checkpoint.CommittedRefs) {
if !refs.HasMirror() {
return
}
repo, err := OpenRepository(ctx)
if err != nil {
logging.Debug(ctx, "pre-push mirror refresh skipped: open repository failed",
slog.String("error", err.Error()))
return
}
defer repo.Close()
mirrorCommittedMetadataRefBestEffort(ctx, repo, refs)
}
Mcmd/entire/cli/strategy/manual_commit_push.go-20
453 unmodified lines
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
457
458
459
453 unmodified lines
}
}
// In v1.1 mode the picker must read prompt text from the topology mirror,
// not v1.
func TestShadowStrategy_GetRewindPoints_V11ReadsPromptFromMirror(t *testing.T) {
dir := t.TempDir()
testutil.InitRepo(t, dir)
testutil.WriteFile(t, dir, "f.txt", "init")
testutil.GitAdd(t, dir, "f.txt")
testutil.GitCommit(t, dir, "init")
repo, err := git.PlainOpen(dir)
require.NoError(t, err)
baseRef, err := repo.Head()
require.NoError(t, err)
baseHash := baseRef.Hash()
cpID := id.MustCheckpointID("a1b2c3d4e5f6")
const wantPrompt = "only-on-mirror"
require.NoError(t, checkpoint.NewGitStore(repo, checkpoint.DefaultV1Refs()).WriteCommitted(t.Context(), checkpoint.WriteCommittedOptions{
CheckpointID: cpID,
SessionID: "test-session-v11-rewind",
Strategy: "manual-commit",
Transcript: redact.AlreadyRedacted([]byte("transcript\n")),
Prompts: []string{wantPrompt},
AuthorName: "Test",
AuthorEmail: "test@test.com",
}))
v1Ref := plumbing.NewBranchReferenceName(paths.MetadataBranchName)
committedRef, err := repo.Reference(v1Ref, true)
require.NoError(t, err)
// Mirror carries the checkpoint; v1 points at the initial commit (no metadata).
mirrorRef := plumbing.ReferenceName(paths.MetadataRefName)
require.NoError(t, repo.Storer.SetReference(plumbing.NewHashReference(mirrorRef, committedRef.Hash())))
require.NoError(t, repo.Storer.SetReference(plumbing.NewHashReference(v1Ref, baseHash)))
// HEAD trailer drives the picker's log walk.
testutil.WriteFile(t, dir, "g.txt", "feat")
testutil.GitAdd(t, dir, "g.txt")
testutil.GitCommit(t, dir, "feat\n\nEntire-Checkpoint: "+cpID.String())
t.Chdir(dir)
settingsDir := filepath.Join(dir, ".entire")
require.NoError(t, os.MkdirAll(settingsDir, 0o755))
require.NoError(t, os.WriteFile(
filepath.Join(settingsDir, paths.SettingsFileName),
[]byte(`{"enabled": true, "strategy_options": {"checkpoints_version": "1.1"}}`),
0o644,
))
strat := NewManualCommitStrategy()
points, err := strat.GetRewindPoints(t.Context(), 10)
require.NoError(t, err)
require.Len(t, points, 1)
assert.Equal(t, wantPrompt, points[0].SessionPrompt, "prompt must come from the mirror, not v1")
}
// When the most-recent session of a multi-session condensed checkpoint has no
// prompt, the picker must fall back to the latest non-empty session prompt
// rather than displaying nothing.
Mcmd/entire/cli/strategy/manual_commit_test.go-58
111 unmodified lines
112
113
114
115
115
117
116
117
118
119
111 unmodified lines
remoteRefName plumbing.ReferenceName,
w io.Writer,
) error {
refs := checkpoint.ResolveCommittedRefs(ctx)
advance := func(hash plumbing.Hash) error {
return AdvanceLocalRef(ctx, repo, refs, localRefName, hash)
return setRefHash(repo, localRefName, hash)
}
// Check local ref
Mcmd/entire/cli/strategy/metadata_reconcile.go+1/-2
244 unmodified lines
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
248
249
250
244 unmodified lines
}
}
// Not parallel: uses t.Chdir().
func TestReconcileDisconnected_MirrorsV1CustomRefAfterRepair(t *testing.T) {
tests := []struct {
name string
setup func(t *testing.T, dir string, run func(args ...string))
}{
{
name: "empty orphan reset",
setup: func(t *testing.T, _ string, run func(args ...string)) {
t.Helper()
run("checkout", "--orphan", "temp-orphan")
run("rm", "-rf", ".")
run("commit", "--allow-empty", "-m", "empty orphan init")
run("branch", "-f", paths.MetadataBranchName, "temp-orphan")
run("checkout", "main")
},
},
{
name: "local checkpoint replay",
setup: func(t *testing.T, dir string, run func(args ...string)) {
t.Helper()
run("checkout", "--orphan", "temp-orphan")
run("rm", "-rf", ".")
localDir := filepath.Join(dir, "ab", "cdef012345")
require.NoError(t, os.MkdirAll(localDir, 0o755))
require.NoError(t, os.WriteFile(
filepath.Join(localDir, "metadata.json"),
[]byte(`{"checkpoint_id":"abcdef012345"}`),
0o644,
))
run("add", ".")
run("commit", "-m", "Checkpoint: abcdef012345")
run("branch", "-f", paths.MetadataBranchName, "temp-orphan")
run("checkout", "main")
},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
bareDir := initBareWithMetadataBranch(t)
cloneDir, run := cloneWithConfig(t, bareDir)
tt.setup(t, cloneDir, run)
enableV1CustomRefMirror(t, cloneDir)
t.Chdir(cloneDir)
repo, err := git.PlainOpen(cloneDir)
require.NoError(t, err)
_, ok := v1CustomRefHash(t, repo)
require.False(t, ok, "custom ref should not exist before reconciliation")
require.NoError(t, ReconcileDisconnectedMetadataRef(t.Context(), repo, metadataLocalRef(), metadataOriginRemoteRef(), io.Discard))
localRef, err := repo.Reference(plumbing.NewBranchReferenceName(paths.MetadataBranchName), true)
require.NoError(t, err)
got, ok := v1CustomRefHash(t, repo)
require.True(t, ok, "expected %s to exist", paths.MetadataRefName)
assert.Equal(t, localRef.Hash(), got)
})
}
}
func TestReconcileDisconnected_MultipleLocalCheckpoints(t *testing.T) {
t.Parallel()
Mcmd/entire/cli/strategy/metadata_reconcile_test.go-63
11 unmodified lines
12
13
14
15
15
16
17
395 unmodified lines
413
414
415
417
416
419
417
418
419
420
11 unmodified lines
"sync"
"time"
"github.com/entireio/cli/cmd/entire/cli/checkpoint"
"github.com/entireio/cli/cmd/entire/cli/checkpoint/remote"
"github.com/entireio/cli/cmd/entire/cli/logging"
"github.com/entireio/cli/cmd/entire/cli/settings"
395 unmodified lines
return fmt.Errorf("failed to get remote ref: %w", err)
}
refs := checkpoint.ResolveCommittedRefs(ctx)
advance := func(hash plumbing.Hash) error {
if err := AdvanceLocalRef(ctx, repo, refs, ref, hash); err != nil {
if err := setRefHash(repo, ref, hash); err != nil {
return err
}
if usedTempRef {
Mcmd/entire/cli/strategy/push_common.go+1/-3
145 unmodified lines
146
147
148
149
149
150
151
152
68 unmodified lines
221
222
223
224
224
225
226
227
919 unmodified lines
1147
1148
1149
1150
1150
1151
1152
1153
18 unmodified lines
1172
1173
1174
1175
1176
1177
1175
1176
1177
145 unmodified lines
// TestPushRefIfNeeded_NonBranchRef verifies that pushRefIfNeeded accepts
// arbitrary refs (not just branches under refs/heads) and pushes them with a
// generic refspec, e.g. refs/entire/checkpoints/v1.1.
// generic refspec, e.g. refs/entire/checkpoints/custom.
//
// Not parallel: uses t.Chdir() (required for OpenRepository).
func TestPushRefIfNeeded_NonBranchRef(t *testing.T) {
68 unmodified lines
}
// TestFetchAndRebase_NonBranchRef verifies the fetch+rebase wiring accepts a
// non-branch ref (e.g. refs/entire/checkpoints/v1.1). Today's resolver doesn't
// non-branch ref (e.g. refs/entire/checkpoints/custom). Today's resolver doesn't
// emit non-branch refs in CommittedRefs.Push, but the helper must remain
// correct when one is wired in.
//
919 unmodified lines
require.NoError(t, os.MkdirAll(filepath.Join(cloneDir, ".entire"), 0o755))
require.NoError(t, os.WriteFile(
filepath.Join(cloneDir, ".entire", "settings.json"),
[]byte(`{"enabled": true, "strategy_options": {"filtered_fetches": true, "checkpoints_version": "1.1"}}`),
[]byte(`{"enabled": true, "strategy_options": {"filtered_fetches": true}}`),
0o644,
))
18 unmodified lines
localRef, err := repo.Reference(plumbing.NewBranchReferenceName(branchName), true)
require.NoError(t, err)
customRef, err := repo.Reference(plumbing.ReferenceName(paths.MetadataRefName), true)
require.NoError(t, err)
assert.Equal(t, localRef.Hash(), customRef.Hash(), "fetchAndRebaseRefCommon should mirror synced v1 metadata to the v1.1 custom ref")
tipCommit, err := repo.CommitObject(localRef.Hash())
require.NoError(t, err)
Mcmd/entire/cli/strategy/push_common_test.go+3/-6
21 unmodified lines
22
23
24
25
25
26
27
179 unmodified lines
207
208
209
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
210
211
212
21 unmodified lines
"github.com/stretchr/testify/require"
"github.com/go-git/go-git/v6"
"github.com/go-git/go-git/v6/plumbing"
"github.com/go-git/go-git/v6/plumbing/object"
)
179 unmodified lines
}
}
func TestRestoreLogsOnly_UsesV11Transcript(t *testing.T) {
repo := setupV1CustomRefRepo(t, `"1.1"`)
repoRoot, err := os.Getwd()
require.NoError(t, err)
agentName := types.AgentName("restore-logs-v11-agent")
agentType := types.AgentType("Restore Logs V11 Agent")
sessionDir := filepath.Join(repoRoot, "restored-sessions")
agent.Register(agentName, func() agent.Agent {
return &restoreLogsOnlyAgent{
name: agentName,
agentType: agentType,
sessionDir: sessionDir,
}
})
ctx := context.Background()
cpID := id.MustCheckpointID("abc987abc987")
sessionID := "restore-v11-session"
v11Transcript := []byte(`{"type":"user","message":{"content":[{"type":"text","text":"restore from v11"}]}}` + "\n")
staleV1Transcript := []byte(`{"type":"user","message":{"content":[{"type":"text","text":"stale v1"}]}}` + "\n")
writeCommittedRewindCheckpoint(t, repo, cpID, sessionID, agentType, v11Transcript, time.Date(2025, 1, 2, 10, 0, 0, 0, time.UTC))
v1Ref, err := repo.Reference(plumbing.NewBranchReferenceName(paths.MetadataBranchName), true)
require.NoError(t, err)
require.NoError(t, repo.Storer.SetReference(plumbing.NewHashReference(plumbing.ReferenceName(paths.MetadataRefName), v1Ref.Hash())))
writeCommittedRewindCheckpoint(t, repo, cpID, sessionID, agentType, staleV1Transcript, time.Date(2025, 1, 3, 10, 0, 0, 0, time.UTC))
var stdout, stderr bytes.Buffer
restored, err := NewManualCommitStrategy().RestoreLogsOnly(ctx, &stdout, &stderr, RewindPoint{
IsLogsOnly: true,
CheckpointID: cpID,
}, true)
require.NoError(t, err, "stderr: %s", stderr.String())
require.Len(t, restored, 1, "stdout: %s\nstderr: %s", stdout.String(), stderr.String())
restoredPath := filepath.Join(sessionDir, sessionID+".jsonl")
got, err := os.ReadFile(restoredPath)
require.NoError(t, err)
require.Equal(t, string(v11Transcript), string(got))
}
// TestRestoreLogsOnly_KeepsExistingLocalLog verifies the default (non-force)
// behavior: a session log already present on disk is kept untouched and still
// reported so the caller prints its resume command. --force overwrites it.
Mcmd/entire/cli/strategy/rewind_test.go-44
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
package strategy
import (
"context"
"errors"
"fmt"
"log/slog"
git "github.com/go-git/go-git/v6"
"github.com/go-git/go-git/v6/plumbing"
"github.com/entireio/cli/cmd/entire/cli/checkpoint"
"github.com/entireio/cli/cmd/entire/cli/logging"
)
// ErrPrimaryMetadataMissing is returned by MirrorCommittedMetadataRef when the
// primary ref does not exist yet. Callers match this sentinel to distinguish
// "expected on first use" from a real read failure, and from a SetReference
// NotFound on the mirror itself.
var ErrPrimaryMetadataMissing = errors.New("primary metadata ref missing")
// AdvanceCommittedPrimary points refs.Primary at hash and best-effort-advances
// refs.Mirror. Mirror failure does not abort the primary operation.
func AdvanceCommittedPrimary(ctx context.Context, repo *git.Repository, refs checkpoint.CommittedRefs, hash plumbing.Hash) error {
if err := repo.Storer.SetReference(plumbing.NewHashReference(refs.Primary, hash)); err != nil {
return fmt.Errorf("set primary metadata ref %s to %s: %w", refs.Primary, hash, err)
}
setMirrorToBestEffort(ctx, repo, refs, hash)
return nil
}
// AdvanceLocalRef points ref at hash, advancing the mirror best-effort when
// ref is refs.Primary.
func AdvanceLocalRef(ctx context.Context, repo *git.Repository, refs checkpoint.CommittedRefs, ref plumbing.ReferenceName, hash plumbing.Hash) error {
if ref == refs.Primary {
return AdvanceCommittedPrimary(ctx, repo, refs, hash)
}
if err := repo.Storer.SetReference(plumbing.NewHashReference(ref, hash)); err != nil {
return fmt.Errorf("set ref %s to %s: %w", ref, hash, err)
}
return nil
}
// MirrorStatus classifies the committed-metadata mirror's relationship to the
// primary metadata ref.
type MirrorStatus int
const (
MirrorNotConfigured MirrorStatus = iota // topology has no mirror (v1 mode)
MirrorOK // mirror == primary tip
MirrorNoMetadata // neither primary nor mirror exists yet (fresh repo)
MirrorMissing // primary exists, mirror ref absent
MirrorBehind // mirror is an ancestor of the primary tip
MirrorDiverged // mirror is not an ancestor of the primary tip
MirrorPrimaryMissing // mirror exists but the primary ref it mirrors is gone
)
// String returns the status label shared by doctor and bundle output.
func (s MirrorStatus) String() string {
switch s {
case MirrorNotConfigured:
return "NOT CONFIGURED"
case MirrorOK:
return "OK"
case MirrorNoMetadata:
return "NO METADATA"
case MirrorMissing:
return "MISSING"
case MirrorBehind:
return "STALE"
case MirrorDiverged:
return "DIVERGED"
case MirrorPrimaryMissing:
return "V1 BRANCH MISSING"
default:
return fmt.Sprintf("UNKNOWN(%d)", int(s))
}
}
// MirrorDiagnosis is the mirror's state plus the resolved topology for repair.
type MirrorDiagnosis struct {
Status MirrorStatus
Refs checkpoint.CommittedRefs
Primary plumbing.Hash // zero when the primary ref is missing
Mirror plumbing.Hash // zero when the mirror ref is missing
}
// DiagnoseCommittedMetadataMirror classifies the mirror ref against the local
// primary metadata ref. Read-only; repair is the caller's decision.
func DiagnoseCommittedMetadataMirror(ctx context.Context, repo *git.Repository) (MirrorDiagnosis, error) {
refs := checkpoint.ResolveCommittedRefs(ctx)
diag := MirrorDiagnosis{Status: MirrorNotConfigured, Refs: refs}
if !refs.HasMirror() {
return diag, nil
}
mirrorRef, err := repo.Reference(refs.Mirror, true)
switch {
case errors.Is(err, plumbing.ErrReferenceNotFound):
// Mirror absent — diag.Mirror stays zero.
case err != nil:
return diag, fmt.Errorf("read mirror ref %s: %w", refs.Mirror, err)
default:
diag.Mirror = mirrorRef.Hash()
}
primaryRef, err := repo.Reference(refs.Primary, true)
if err != nil {
if errors.Is(err, plumbing.ErrReferenceNotFound) {
if diag.Mirror.IsZero() {
diag.Status = MirrorNoMetadata // fresh repo: nothing committed yet
} else {
diag.Status = MirrorPrimaryMissing // mirror outlived its primary
}
return diag, nil
}
return diag, fmt.Errorf("read primary metadata ref %s: %w", refs.Primary, err)
}
diag.Primary = primaryRef.Hash()
switch {
case diag.Mirror.IsZero():
diag.Status = MirrorMissing
return diag, nil
case diag.Mirror == diag.Primary:
diag.Status = MirrorOK
return diag, nil
}
mirrorCommit, err := repo.CommitObject(diag.Mirror)
if err != nil {
return diag, fmt.Errorf("read mirror commit %s: %w", diag.Mirror, err)
}
primaryCommit, err := repo.CommitObject(diag.Primary)
if err != nil {
return diag, fmt.Errorf("read primary commit %s: %w", diag.Primary, err)
}
isAncestor, err := mirrorCommit.IsAncestor(primaryCommit)
if err != nil {
return diag, fmt.Errorf("check mirror ancestry against %s: %w", refs.Primary, err)
}
if isAncestor {
diag.Status = MirrorBehind
} else {
diag.Status = MirrorDiverged
}
return diag, nil
}
// MirrorCommittedMetadataRef points refs.Mirror at refs.Primary's tip. No-op
// when the topology has no mirror.
func MirrorCommittedMetadataRef(ctx context.Context, repo *git.Repository, refs checkpoint.CommittedRefs) error {
if !refs.HasMirror() {
return nil
}
primaryRef, err := repo.Reference(refs.Primary, true)
if err != nil {
if errors.Is(err, plumbing.ErrReferenceNotFound) {
return fmt.Errorf("primary metadata ref %s missing: %w", refs.Primary, ErrPrimaryMetadataMissing)
}
return fmt.Errorf("read primary metadata ref %s: %w", refs.Primary, err)
}
return setMirrorTo(ctx, repo, refs, primaryRef.Hash())
}
func setMirrorTo(ctx context.Context, repo *git.Repository, refs checkpoint.CommittedRefs, hash plumbing.Hash) error {
if err := repo.Storer.SetReference(plumbing.NewHashReference(refs.Mirror, hash)); err != nil {
return fmt.Errorf("set mirror ref %s to %s: %w", refs.Mirror, hash, err)
}
logging.Debug(ctx, "committed-ref mirror updated",
slog.String("ref", refs.Mirror.String()),
slog.String("hash", hash.String()))
return nil
}
func setMirrorToBestEffort(ctx context.Context, repo *git.Repository, refs checkpoint.CommittedRefs, hash plumbing.Hash) {
if !refs.HasMirror() {
return
}
// Detach cancellation so a parent deadline near expiry doesn't silently
// drop the mirror write; the mirror itself is short.
ctx = context.WithoutCancel(ctx)
if err := setMirrorTo(ctx, repo, refs, hash); err != nil {
logging.Warn(ctx, "committed-ref mirror failed",
slog.String("ref", refs.Mirror.String()),
slog.String("error", err.Error()))
}
}
func mirrorCommittedMetadataRefBestEffort(ctx context.Context, repo *git.Repository, refs checkpoint.CommittedRefs) {
if !refs.HasMirror() {
return
}
ctx = context.WithoutCancel(ctx)
if err := MirrorCommittedMetadataRef(ctx, repo, refs); err != nil {
if errors.Is(err, ErrPrimaryMetadataMissing) {
logging.Debug(ctx, "committed-ref mirror skipped: primary metadata ref unavailable",
slog.String("error", err.Error()))
return
}
logging.Warn(ctx, "committed-ref mirror failed",
slog.String("ref", refs.Mirror.String()),
slog.String("error", err.Error()))
}
}
Dcmd/entire/cli/strategy/v1_custom_ref_mirror.go-205
package strategy
import ( "errors" "os" "path/filepath" "testing" "time"
git "github.com/go-git/go-git/v6" "github.com/go-git/go-git/v6/plumbing" "github.com/go-git/go-git/v6/storage" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require"
"github.com/entireio/cli/cmd/entire/cli/checkpoint" "github.com/entireio/cli/cmd/entire/cli/checkpoint/id" "github.com/entireio/cli/cmd/entire/cli/paths" "github.com/entireio/cli/cmd/entire/cli/session" "github.com/entireio/cli/cmd/entire/cli/testutil" )
type setReferenceErrorStorer struct { storage.Storer
err error }
func (s setReferenceErrorStorer) SetReference(*plumbing.Reference) error { return s.err }
// setupV1CustomRefRepo creates an isolated repo with one commit, writes settings // with the given checkpoints_version (empty string omits the option), chdirs // in, and returns the open repo. func setupV1CustomRefRepo(t *testing.T, version string) *git.Repository { t.Helper() tmpDir := t.TempDir() testutil.InitRepo(t, tmpDir) testutil.WriteFile(t, tmpDir, "f.txt", "init") testutil.GitAdd(t, tmpDir, "f.txt") testutil.GitCommit(t, tmpDir, "init")
body := {"enabled": true}
if version != "" {
body = {"enabled": true, "strategy_options": {"checkpoints_version": + version + }}
}
entireDir := filepath.Join(tmpDir, ".entire")
require.NoError(t, os.MkdirAll(entireDir, 0o755))
require.NoError(t, os.WriteFile(filepath.Join(entireDir, "settings.json"), []byte(body), 0o644))
t.Chdir(tmpDir) repo, err := git.PlainOpen(tmpDir) require.NoError(t, err) return repo }
// setV1MetadataBranch points the v1 metadata branch at HEAD and returns the hash. func setV1MetadataBranch(t *testing.T, repo *git.Repository) plumbing.Hash { t.Helper() head, err := repo.Head() require.NoError(t, err) require.NoError(t, repo.Storer.SetReference( plumbing.NewHashReference(plumbing.NewBranchReferenceName(paths.MetadataBranchName), head.Hash()))) return head.Hash() }
func v1CustomRefHash(t *testing.T, repo *git.Repository) (plumbing.Hash, bool) { t.Helper() ref, err := repo.Reference(plumbing.ReferenceName(paths.MetadataRefName), true) if err != nil { return plumbing.ZeroHash, false } return ref.Hash(), true }
func localRefExists(t *testing.T, dir, refName string) bool { t.Helper() repo, err := git.PlainOpen(dir) require.NoError(t, err) _, err = repo.Reference(plumbing.ReferenceName(refName), true) return err == nil }
func v1MetadataBranchHash(t *testing.T, repo *git.Repository) plumbing.Hash { t.Helper() ref, err := repo.Reference(plumbing.NewBranchReferenceName(paths.MetadataBranchName), true) require.NoError(t, err) return ref.Hash() }
func enableV1CustomRefMirror(t *testing.T, dir string) {
t.Helper()
entireDir := filepath.Join(dir, ".entire")
require.NoError(t, os.MkdirAll(entireDir, 0o755))
require.NoError(t, os.WriteFile(
filepath.Join(entireDir, paths.SettingsFileName),
[]byte({"enabled": true, "strategy_options": {"checkpoints_version": "1.1"}}),
0o644,
))
}
func v1CustomRefsForTest() checkpoint.CommittedRefs { v1Branch := plumbing.NewBranchReferenceName(paths.MetadataBranchName) return checkpoint.CommittedRefs{ Primary: v1Branch, Read: plumbing.ReferenceName(paths.MetadataRefName), Mirror: plumbing.ReferenceName(paths.MetadataRefName), Push: []plumbing.ReferenceName{v1Branch}, } }
// Not parallel: uses t.Chdir().
func TestMirrorCommittedMetadataRef_CreatesRef(t *testing.T) {
repo := setupV1CustomRefRepo(t, "1.1")
v1Hash := setV1MetadataBranch(t, repo)
require.NoError(t, MirrorCommittedMetadataRef(t.Context(), repo, v1CustomRefsForTest()))
got, ok := v1CustomRefHash(t, repo) require.True(t, ok, "expected %s to exist", paths.MetadataRefName) assert.Equal(t, v1Hash, got) }
// Not parallel: uses t.Chdir(). func TestMirrorCommittedMetadataRef_DisabledNoOp(t *testing.T) { repo := setupV1CustomRefRepo(t, "") // v1 only setV1MetadataBranch(t, repo)
require.NoError(t, MirrorCommittedMetadataRef(t.Context(), repo, checkpoint.CommittedRefs{ Primary: plumbing.NewBranchReferenceName(paths.MetadataBranchName), Read: plumbing.NewBranchReferenceName(paths.MetadataBranchName), }))
_, ok := v1CustomRefHash(t, repo) assert.False(t, ok, "v1 custom ref must not be created when not opted in") }
// Not parallel: uses t.Chdir().
func TestMirrorCommittedMetadataRef_AdvancesExistingRef(t *testing.T) {
repo := setupV1CustomRefRepo(t, "1.1")
oldHash := setV1MetadataBranch(t, repo)
require.NoError(t, repo.Storer.SetReference(
plumbing.NewHashReference(plumbing.ReferenceName(paths.MetadataRefName), oldHash)))
cwd, err := os.Getwd() require.NoError(t, err) testutil.WriteFile(t, cwd, "f2.txt", "more") testutil.GitAdd(t, cwd, "f2.txt") testutil.GitCommit(t, cwd, "second") newHash := setV1MetadataBranch(t, repo) require.NotEqual(t, oldHash, newHash)
require.NoError(t, MirrorCommittedMetadataRef(t.Context(), repo, v1CustomRefsForTest()))
got, ok := v1CustomRefHash(t, repo) require.True(t, ok) assert.Equal(t, newHash, got) }
// Not parallel: uses t.Chdir().
func TestMirrorCommittedMetadataRef_UsesProvidedRefs(t *testing.T) {
repo := setupV1CustomRefRepo(t, "1.1")
head, err := repo.Head()
require.NoError(t, err)
primary := plumbing.NewBranchReferenceName("entire/checkpoints/custom") mirror := plumbing.ReferenceName("refs/entire/checkpoints/custom-read") require.NoError(t, repo.Storer.SetReference(plumbing.NewHashReference(primary, head.Hash())))
require.NoError(t, MirrorCommittedMetadataRef(t.Context(), repo, checkpoint.CommittedRefs{ Primary: primary, Read: mirror, Mirror: mirror, }))
ref, err := repo.Reference(mirror, true) require.NoError(t, err) assert.Equal(t, head.Hash(), ref.Hash()) }
// Not parallel: uses t.Chdir().
func TestMirrorCommittedMetadataRef_ReplacesLocallyAheadMirror(t *testing.T) {
repo := setupV1CustomRefRepo(t, "1.1")
v1Hash := setV1MetadataBranch(t, repo)
cwd, err := os.Getwd() require.NoError(t, err) testutil.WriteFile(t, cwd, "f2.txt", "more") testutil.GitAdd(t, cwd, "f2.txt") testutil.GitCommit(t, cwd, "second") head, err := repo.Head() require.NoError(t, err) require.NotEqual(t, v1Hash, head.Hash()) require.NoError(t, repo.Storer.SetReference( plumbing.NewHashReference(plumbing.ReferenceName(paths.MetadataRefName), head.Hash())))
require.NoError(t, MirrorCommittedMetadataRef(t.Context(), repo, v1CustomRefsForTest()))
got, ok := v1CustomRefHash(t, repo) require.True(t, ok) assert.Equal(t, v1Hash, got) }
// Not parallel: uses t.Chdir(). func TestCondenseSession_MirrorsV1CustomRefWhenEnabled(t *testing.T) { dir := setupGitRepo(t) t.Chdir(dir) enableV1CustomRefMirror(t, dir)
repo, err := git.PlainOpen(dir) require.NoError(t, err)
s := &ManualCommitStrategy{} sessionID := "test-condense-v1-custom-ref" setupSessionWithCheckpoint(t, s, repo, dir, sessionID)
state, err := s.loadSessionState(t.Context(), sessionID) require.NoError(t, err)
checkpointID := id.MustCheckpointID("aabbccdd1122") result, err := s.CondenseSession(t.Context(), repo, checkpointID, state, nil) require.NoError(t, err) require.False(t, result.Skipped)
v1Hash := v1MetadataBranchHash(t, repo) got, ok := v1CustomRefHash(t, repo) require.True(t, ok, "expected %s to exist", paths.MetadataRefName) assert.Equal(t, v1Hash, got) }
// Not parallel: uses t.Chdir(). func TestDeleteOrphanedCheckpoints_MirrorsV1CustomRefWhenEnabled(t *testing.T) { dir := setupGitRepo(t) t.Chdir(dir) enableV1CustomRefMirror(t, dir)
repo, err := git.PlainOpen(dir) require.NoError(t, err) setV1MetadataBranch(t, repo) v1HashBefore := v1MetadataBranchHash(t, repo)
cpID := id.MustCheckpointID("aabbccdd1122") deleted, failed, err := DeleteOrphanedCheckpoints(t.Context(), []string{cpID.String()}) require.NoError(t, err) require.Empty(t, failed) require.Equal(t, []string{cpID.String()}, deleted)
v1HashAfter := v1MetadataBranchHash(t, repo) require.NotEqual(t, v1HashBefore, v1HashAfter, "cleanup must advance v1 with a new commit")
mirrorHash, ok := v1CustomRefHash(t, repo) require.True(t, ok, "expected %s to exist", paths.MetadataRefName) assert.Equal(t, v1HashAfter, mirrorHash, "v1.1 mirror should track v1 after DeleteOrphanedCheckpoints") }
// Not parallel: uses t.Chdir(). func TestFinalizeAllTurnCheckpoints_MirrorsV1CustomRefWhenEnabled(t *testing.T) { dir := setupGitRepo(t) t.Chdir(dir) enableV1CustomRefMirror(t, dir)
repo, err := git.PlainOpen(dir) require.NoError(t, err)
s := &ManualCommitStrategy{} sessionID := "test-finalize-v1-custom-ref" setupSessionWithCheckpoint(t, s, repo, dir, sessionID)
state, err := s.loadSessionState(t.Context(), sessionID) require.NoError(t, err) state.Phase = session.PhaseActive state.TurnCheckpointIDs = nil require.NoError(t, s.saveSessionState(t.Context(), state))
commitWithCheckpointTrailer(t, repo, dir, "bbccdd112233") require.NoError(t, s.PostCommit(t.Context()))
state, err = s.loadSessionState(t.Context(), sessionID) require.NoError(t, err) require.Equal(t, []string{"bbccdd112233"}, state.TurnCheckpointIDs)
beforeV1Hash := v1MetadataBranchHash(t, repo) beforeCustomHash, ok := v1CustomRefHash(t, repo) require.True(t, ok, "expected %s to exist after condensation", paths.MetadataRefName) require.Equal(t, beforeV1Hash, beforeCustomHash)
fullTranscript := testTranscriptPromptResponse + {"type":"human","message":{"content":"now test it"}} {"type":"assistant","message":{"content":"tests pass"}}
transcriptPath := filepath.Join(dir, ".entire", "metadata", sessionID, paths.TranscriptFileName)
require.NoError(t, os.WriteFile(transcriptPath, []byte(fullTranscript), 0o644))
state.TranscriptPath = transcriptPath
require.NoError(t, s.HandleTurnEnd(t.Context(), state))
afterV1Hash := v1MetadataBranchHash(t, repo) require.NotEqual(t, beforeV1Hash, afterV1Hash, "finalization should advance v1 metadata") afterCustomHash, ok := v1CustomRefHash(t, repo) require.True(t, ok, "expected %s to exist after finalization", paths.MetadataRefName) assert.Equal(t, afterV1Hash, afterCustomHash) }
// Not parallel: uses t.Chdir().
func TestMirrorCommittedMetadataRef_V1MissingErrors(t *testing.T) {
repo := setupV1CustomRefRepo(t, "1.1") // no v1 metadata branch created
err := MirrorCommittedMetadataRef(t.Context(), repo, v1CustomRefsForTest()) require.Error(t, err) assert.Contains(t, err.Error(), paths.MetadataBranchName) require.ErrorIs(t, err, ErrPrimaryMetadataMissing, "primary-missing must use the sentinel so callers can disambiguate from SetReference NotFound")
_, ok := v1CustomRefHash(t, repo) assert.False(t, ok, "v1 custom ref must not be created when v1 metadata branch is absent") }
// Not parallel: uses t.Chdir().
func TestMirrorCommittedMetadataRef_SetReferenceNotFoundIsNotPrimaryMissing(t *testing.T) {
repo := setupV1CustomRefRepo(t, "1.1")
setV1MetadataBranch(t, repo)
repo.Storer = setReferenceErrorStorer{Storer: repo.Storer, err: plumbing.ErrReferenceNotFound}
err := MirrorCommittedMetadataRef(t.Context(), repo, v1CustomRefsForTest()) require.Error(t, err) require.ErrorIs(t, err, plumbing.ErrReferenceNotFound, "SetReference NotFound should still unwrap to plumbing.ErrReferenceNotFound") require.NotErrorIs(t, err, ErrPrimaryMetadataMissing, "SetReference NotFound must not be mistaken for a missing primary") }
// Not parallel: uses t.Chdir().
func TestMirrorCommittedMetadataRef_SetReferenceErrorNamesTarget(t *testing.T) {
repo := setupV1CustomRefRepo(t, "1.1")
v1Hash := setV1MetadataBranch(t, repo)
storerErr := errors.New("set failed")
repo.Storer = setReferenceErrorStorer{Storer: repo.Storer, err: storerErr}
err := MirrorCommittedMetadataRef(t.Context(), repo, v1CustomRefsForTest()) require.ErrorIs(t, err, storerErr) assert.Contains(t, err.Error(), paths.MetadataRefName) assert.Contains(t, err.Error(), v1Hash.String()) }
// Not parallel: uses t.Chdir(). func TestAdvanceCommittedPrimary_NoMirror(t *testing.T) { repo := setupV1CustomRefRepo(t, "") // v1 only hash := setV1MetadataBranch(t, repo)
refs := checkpoint.DefaultV1Refs() require.NoError(t, AdvanceCommittedPrimary(t.Context(), repo, refs, hash))
ref, err := repo.Reference(refs.Primary, true) require.NoError(t, err) assert.Equal(t, hash, ref.Hash())
_, ok := v1CustomRefHash(t, repo) assert.False(t, ok, "no mirror configured; v1.1 ref must not exist") }
// Not parallel: uses t.Chdir().
func TestAdvanceCommittedPrimary_AdvancesBothRefs(t *testing.T) {
repo := setupV1CustomRefRepo(t, "1.1")
head, err := repo.Head()
require.NoError(t, err)
require.NoError(t, AdvanceCommittedPrimary(t.Context(), repo, v1CustomRefsForTest(), head.Hash()))
primaryRef, err := repo.Reference(plumbing.NewBranchReferenceName(paths.MetadataBranchName), true) require.NoError(t, err) assert.Equal(t, head.Hash(), primaryRef.Hash())
mirror, ok := v1CustomRefHash(t, repo) require.True(t, ok) assert.Equal(t, head.Hash(), mirror, "mirror must track primary after advance") }
type selectiveSetReferenceErrorStorer struct { storage.Storer
failRef plumbing.ReferenceName err error }
func (s selectiveSetReferenceErrorStorer) SetReference(ref *plumbing.Reference) error { if ref.Name() == s.failRef { return s.err } return s.Storer.SetReference(ref) }
// Not parallel: uses t.Chdir().
func TestAdvanceCommittedPrimary_MirrorFailureDoesNotFailPrimary(t *testing.T) {
repo := setupV1CustomRefRepo(t, "1.1")
head, err := repo.Head()
require.NoError(t, err)
mirrorRef := plumbing.ReferenceName(paths.MetadataRefName) repo.Storer = selectiveSetReferenceErrorStorer{ Storer: repo.Storer, failRef: mirrorRef, err: errors.New("mirror set failed"), }
require.NoError(t, AdvanceCommittedPrimary(t.Context(), repo, v1CustomRefsForTest(), head.Hash()), "mirror failure must be swallowed; only Primary failure should surface")
_, ok := v1CustomRefHash(t, repo) assert.False(t, ok, "mirror write was rejected, so the ref must not exist") }
// Not parallel: uses t.Chdir(). func TestUpdateCombinedAttribution_MirrorsV1CustomRefWhenEnabled(t *testing.T) { dir := setupGitRepo(t) t.Chdir(dir) enableV1CustomRefMirror(t, dir)
repo, err := git.PlainOpen(dir) require.NoError(t, err)
s := &ManualCommitStrategy{} // Two sessions overlapping the same commit make the checkpoint hold >1 // session, which triggers combined-attribution persistence — a second v1 // write that lands after per-session condensation has already mirrored. sessions := []struct{ id, file string }{ {"combined-a", "a.txt"}, {"combined-b", "b.txt"}, } files := make([]string, 0, len(sessions)) for _, sess := range sessions { setupSessionWithCheckpointAndFile(t, s, dir, sess.id, sess.file) state, loadErr := s.loadSessionState(t.Context(), sess.id) require.NoError(t, loadErr) now := time.Now() state.Phase = session.PhaseEnded state.EndedAt = &now state.FilesTouched = []string{sess.file} require.NoError(t, s.saveSessionState(t.Context(), state)) files = append(files, sess.file) }
commitFilesWithTrailer(t, repo, dir, "ccddee112233", files...) require.NoError(t, s.PostCommit(t.Context()))
v1Hash := v1MetadataBranchHash(t, repo) got, ok := v1CustomRefHash(t, repo) require.True(t, ok, "expected %s to exist", paths.MetadataRefName) assert.Equal(t, v1Hash, got, "custom ref must track v1 after combined-attribution write") }
// Not parallel: uses t.Chdir(). Setup returns the expected diagnosis fields. func TestDiagnoseCommittedMetadataMirror(t *testing.T) { setMirror := func(t *testing.T, repo *git.Repository, hash plumbing.Hash) { t.Helper() require.NoError(t, repo.Storer.SetReference( plumbing.NewHashReference(plumbing.ReferenceName(paths.MetadataRefName), hash))) } secondCommit := func(t *testing.T, repo *git.Repository) plumbing.Hash { t.Helper() cwd, err := os.Getwd() require.NoError(t, err) testutil.WriteFile(t, cwd, "f2.txt", "more") testutil.GitAdd(t, cwd, "f2.txt") testutil.GitCommit(t, cwd, "second") head, err := repo.Head() require.NoError(t, err) return head.Hash() }
type want struct {
status MirrorStatus
primary plumbing.Hash
mirror plumbing.Hash
}
tests := []struct {
name string
version string
setup func(t *testing.T, repo *git.Repository) want
}{
{"not configured in v1 mode", "", func(t *testing.T, repo *git.Repository) want {
setV1MetadataBranch(t, repo)
return want{status: MirrorNotConfigured}
}},
{"ok when mirror matches v1", "1.1", func(t *testing.T, repo *git.Repository) want {
v1 := setV1MetadataBranch(t, repo)
setMirror(t, repo, v1)
return want{status: MirrorOK, primary: v1, mirror: v1}
}},
{"missing when mirror ref absent", "1.1", func(t *testing.T, repo *git.Repository) want {
v1 := setV1MetadataBranch(t, repo)
return want{status: MirrorMissing, primary: v1}
}},
{"behind when mirror is an ancestor of v1", "1.1", func(t *testing.T, repo *git.Repository) want {
old := setV1MetadataBranch(t, repo)
setMirror(t, repo, old)
secondCommit(t, repo)
newHash := setV1MetadataBranch(t, repo)
require.NotEqual(t, old, newHash)
return want{status: MirrorBehind, primary: newHash, mirror: old}
}},
{"diverged when mirror is not an ancestor of v1", "1.1", func(t *testing.T, repo *git.Repository) want {
v1 := setV1MetadataBranch(t, repo)
ahead := secondCommit(t, repo)
setMirror(t, repo, ahead)
return want{status: MirrorDiverged, primary: v1, mirror: ahead}
}},
{"no metadata when neither ref exists", "1.1", func(_ *testing.T, _ *git.Repository) want {
return want{status: MirrorNoMetadata}
}},
{"primary missing when mirror outlives v1", "1.1", func(t *testing.T, repo *git.Repository) want {
head, err := repo.Head()
require.NoError(t, err)
setMirror(t, repo, head.Hash())
return want{status: MirrorPrimaryMissing, mirror: head.Hash()}
}},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
repo := setupV1CustomRefRepo(t, tt.version)
expected := tt.setup(t, repo)
mirrorBefore, mirrorExistedBefore := v1CustomRefHash(t, repo)
diag, err := DiagnoseCommittedMetadataMirror(t.Context(), repo) require.NoError(t, err) assert.Equal(t, expected.status, diag.Status) assert.Equal(t, expected.primary, diag.Primary) assert.Equal(t, expected.mirror, diag.Mirror) assert.Equal(t, expected.status != MirrorNotConfigured, diag.Refs.HasMirror(), "Refs must carry the topology for repair")
mirrorAfter, mirrorExistsAfter := v1CustomRefHash(t, repo) require.Equal(t, mirrorExistedBefore, mirrorExistsAfter, "diagnosis must not create or delete the mirror ref") assert.Equal(t, mirrorBefore, mirrorAfter, "diagnosis must not move the mirror ref") }) } }
// TestPrePush_PushesV1CustomRefWhenOptedIn proves that with the mirror opted
// in, pre-push pushes the v1 branch and the v1 custom ref alongside it.
//
// Not parallel: uses t.Chdir().
func TestPrePush_PushesV1CustomRefWhenOptedIn(t *testing.T) {
ctx := t.Context()
repo := setupV1CustomRefRepo(t, "1.1")
head := setV1MetadataBranch(t, repo)
require.NoError(t, repo.Storer.SetReference(
plumbing.NewHashReference(plumbing.ReferenceName(paths.MetadataRefName), head)))
cwd, err := os.Getwd() require.NoError(t, err) bareDir := t.TempDir() runCheckpointRemoteGit(ctx, t, bareDir, "init", "--bare") runCheckpointRemoteGit(ctx, t, cwd, "remote", "add", "origin", bareDir)
require.NoError(t, (&ManualCommitStrategy{}).PrePush(ctx, "origin"))
assert.True(t, localRefExists(t, bareDir, "refs/heads/"+paths.MetadataBranchName), "v1 metadata branch should be pushed") assert.True(t, localRefExists(t, bareDir, paths.MetadataRefName), "v1 custom ref should be pushed alongside v1 when opted in") }
Dcmd/entire/cli/strategy/v1\_custom\_ref\_mirror\_test.go-562