Merge pull request #1001 from entireio/update-checkpoints-version-setting

Checkpoints V2: allow for a `checkpoints_version` setting in settings.json

Author: computermode

cmd/entire/cli/attach.go

@@ -177,17 +177,18 @@ func runAttach(ctx context.Context, w io.Writer, sessionID string, agentName typ
 		writeOpts.CompactTranscript = compacted
 	}
 
-	v2Only := settings.IsCheckpointsV2OnlyEnabled(logCtx)
-	if !v2Only {
+	v2 := settings.CheckpointsVersion(logCtx) == 2
+	if !v2 {
 		if err := store.WriteCommitted(ctx, writeOpts); err != nil {
 			return fmt.Errorf("failed to write checkpoint: %w", err)
 		}
 	}
-	// IsCheckpointsV2Enabled is true whenever v2Only is true, so this covers both
-	// the v2-only and dual-write paths. Only v2-only propagates the error.
+	// IsCheckpointsV2Enabled is true whenever v2 writes are enabled, including
+	// both v2-only mode (checkpoints_version == 2) and dual-write mode. Only
+	// v2-only mode propagates the error.
 	if settings.IsCheckpointsV2Enabled(logCtx) {
 		if err := writeAttachCheckpointV2(logCtx, repo, writeOpts); err != nil {
-			if v2Only {
+			if v2 {
 				return fmt.Errorf("failed to write checkpoint to v2: %w", err)
 			}
 			logging.Warn(logCtx, "attach v2 dual-write failed", "error", err)

cmd/entire/cli/integration_test/v2_dual_write_test.go

@@ -245,10 +245,11 @@ func TestV2DualWrite_StopTimeFinalization(t *testing.T) {
 	assert.Contains(t, compactTranscript, `"v":1`)
 }
 
-// TestV2Only_SkipsV1Write verifies the v2-only specific deltas: v1 metadata is
-// not written and v2 refs still exist. The full v2 payload shape is already
-// covered by TestV2DualWrite_FullWorkflow.
-func TestV2Only_SkipsV1Write(t *testing.T) {
+// TestCheckpointsVersion2_SkipsV1Write verifies the specific deltas of running
+// with checkpoints_version: 2 — v1 metadata is not written and v2 refs still
+// exist. The full v2 payload shape is already covered by
+// TestV2DualWrite_FullWorkflow.
+func TestCheckpointsVersion2_SkipsV1Write(t *testing.T) {
 	t.Parallel()
 	env := NewTestEnv(t)
 	defer env.Cleanup()
@@ -259,10 +260,10 @@ func TestV2Only_SkipsV1Write(t *testing.T) {
 	env.GitAdd("README.md")
 	env.GitAdd(".gitignore")
 	env.GitCommit("Initial commit")
-	env.GitCheckoutNewBranch("feature/v2-only-test")
+	env.GitCheckoutNewBranch("feature/checkpoints-v2-test")
 
 	env.InitEntireWithOptions(map[string]any{
-		"checkpoints_v2_only": true,
+		"checkpoints_version": 2,
 	})
 
 	session := env.NewSession()
@@ -287,7 +288,7 @@ func TestV2Only_SkipsV1Write(t *testing.T) {
 	// v1: should NOT be written.
 	_, found := env.ReadFileFromBranch(paths.MetadataBranchName, cpPath+"/"+paths.MetadataFileName)
 	assert.False(t, found,
-		"v1 committed checkpoint metadata should NOT exist when checkpoints_v2_only is enabled")
+		"v1 committed checkpoint metadata should NOT exist when checkpoints_version is 2")
 
 	// v2: smoke check that the checkpoint still landed.
 	assert.True(t, env.RefExists(paths.V2MainRefName), "v2 /main ref should exist")

cmd/entire/cli/integration_test/v2_push_test.go

@@ -124,10 +124,10 @@ func TestV2Push_Disabled_NoV2Refs(t *testing.T) {
 		"v1 metadata branch should still exist on remote")
 }
 
-// TestV2Push_V2OnlySkipsV1Branch verifies that the v1 metadata branch is not
-// pushed when checkpoints_v2_only is enabled; v2 ref pushing itself is covered
+// TestV2Push_Version2SkipsV1Branch verifies that the v1 metadata branch is not
+// pushed when checkpoints_version is set to 2; v2 ref pushing itself is covered
 // by TestV2Push_FullCycle.
-func TestV2Push_V2OnlySkipsV1Branch(t *testing.T) {
+func TestV2Push_Version2SkipsV1Branch(t *testing.T) {
 	t.Parallel()
 	env := NewTestEnv(t)
 	defer env.Cleanup()
@@ -138,10 +138,10 @@ func TestV2Push_V2OnlySkipsV1Branch(t *testing.T) {
 	env.GitAdd("README.md")
 	env.GitAdd(".gitignore")
 	env.GitCommit("Initial commit")
-	env.GitCheckoutNewBranch("feature/v2-only-push-test")
+	env.GitCheckoutNewBranch("feature/checkpoints-v2-push-test")
 
 	env.InitEntireWithOptions(map[string]any{
-		"checkpoints_v2_only": true,
+		"checkpoints_version": 2,
 	})
 
 	bareDir := env.SetupBareRemote()
@@ -162,7 +162,7 @@ func TestV2Push_V2OnlySkipsV1Branch(t *testing.T) {
 	env.RunPrePush("origin")
 
 	assert.False(t, bareRefExists(t, bareDir, "refs/heads/"+paths.MetadataBranchName),
-		"v1 metadata branch should NOT exist on remote when checkpoints_v2_only is enabled")
+		"v1 metadata branch should NOT exist on remote when checkpoints_version is 2")
 	// Smoke: v2 refs still land; full payload asserted in TestV2Push_FullCycle.
 	assert.True(t, bareRefExists(t, bareDir, paths.V2MainRefName),
 		"v2 /main ref should exist on remote after push")

cmd/entire/cli/settings/settings.go

@@ -10,7 +10,9 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strconv"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/entireio/cli/cmd/entire/cli/jsonutil"
@@ -27,6 +29,8 @@ const (
 	defaultGenerationRetentionDays = 60
 )
 
+var checkpointsVersionWarningOnce sync.Once
+
 // Commit linking mode constants.
 const (
 	// CommitLinkingAlways auto-links commits to sessions without prompting.
@@ -607,14 +611,27 @@ func IsCheckpointsV2Enabled(ctx context.Context) bool {
 	return settings.IsCheckpointsV2Enabled()
 }
 
-// IsCheckpointsV2OnlyEnabled checks if checkpoints should be written and pushed
-// only via v2 refs.
-func IsCheckpointsV2OnlyEnabled(ctx context.Context) bool {
+// CheckpointsVersion returns the configured checkpoints format version, or 1
+// if settings cannot be loaded or the value is unset/invalid.
+func CheckpointsVersion(ctx context.Context) int {
 	s, err := Load(ctx)
 	if err != nil {
-		return false
+		return 1
+	}
+	version := s.CheckpointsVersion()
+	if s.StrategyOptions != nil {
+		if configured, ok := s.StrategyOptions["checkpoints_version"]; ok {
+			if _, supported := parseCheckpointsVersion(configured); !supported {
+				checkpointsVersionWarningOnce.Do(func() {
+					fmt.Fprintf(os.Stderr,
+						"[entire] unsupported strategy_options.checkpoints_version %v detected in settings. Falling back to the default version (1).\n",
+						configured,
+					)
+				})
+			}
+		}
 	}
-	return s.IsCheckpointsV2OnlyEnabled()
+	return version
 }
 
 // IsPushV2RefsEnabled checks if pushing v2 refs is enabled in settings.
@@ -709,9 +726,9 @@ func (s *EntireSettings) GetCheckpointRemote() *CheckpointRemoteConfig {
 }
 
 // IsCheckpointsV2Enabled checks if checkpoints v2 is enabled.
-// Returns true when either checkpoints_v2 or checkpoints_v2_only is enabled.
+// Returns true when either checkpoints_v2 is set or checkpoints_version is 2.
 func (s *EntireSettings) IsCheckpointsV2Enabled() bool {
-	if s.IsCheckpointsV2OnlyEnabled() {
+	if s.CheckpointsVersion() == 2 {
 		return true
 	}
 	if s.StrategyOptions == nil {
@@ -721,20 +738,47 @@ func (s *EntireSettings) IsCheckpointsV2Enabled() bool {
 	return ok && val
 }
 
-// IsCheckpointsV2OnlyEnabled checks if checkpoints should be written and pushed
-// only via v2 refs, with no v1 dual-write.
-func (s *EntireSettings) IsCheckpointsV2OnlyEnabled() bool {
+// CheckpointsVersion returns the configured checkpoints format version from
+// strategy_options.checkpoints_version. Returns 1 when unset, invalid, or
+// unsupported. The currently supported versions are 1 and 2.
+func (s *EntireSettings) CheckpointsVersion() int {
 	if s.StrategyOptions == nil {
-		return false
+		return 1
 	}
-	val, ok := s.StrategyOptions["checkpoints_v2_only"].(bool)
-	return ok && val
+	val, ok := s.StrategyOptions["checkpoints_version"]
+	if !ok {
+		return 1
+	}
+	version, ok := parseCheckpointsVersion(val)
+	if ok {
+		return version
+	}
+	return 1
+}
+
+func parseCheckpointsVersion(val any) (int, bool) {
+	v, ok := val.(int)
+	if ok && (v == 1 || v == 2) {
+		return v, true
+	}
+	floatV, ok := val.(float64)
+	if ok && (floatV == 1 || floatV == 2) {
+		return int(floatV), true
+	}
+	stringV, ok := val.(string)
+	if ok {
+		parsed, err := strconv.Atoi(stringV)
+		if err == nil && (parsed == 1 || parsed == 2) {
+			return parsed, true
+		}
+	}
+	return 1, false
 }
 
 // IsPushV2RefsEnabled checks if pushing v2 refs is enabled.
-// checkpoints_v2_only forces v2 ref pushes on, regardless of push_v2_refs.
+// checkpoints_version: 2 forces v2 ref pushes on, regardless of push_v2_refs.
 func (s *EntireSettings) IsPushV2RefsEnabled() bool {
-	if s.IsCheckpointsV2OnlyEnabled() {
+	if s.CheckpointsVersion() == 2 {
 		return true
 	}
 	if !s.IsCheckpointsV2Enabled() {

cmd/entire/cli/settings/settings_test.go

@@ -692,14 +692,14 @@ func TestIsCheckpointsV2Enabled_True(t *testing.T) {
 	}
 }
 
-func TestIsCheckpointsV2Enabled_V2Only(t *testing.T) {
+func TestIsCheckpointsV2Enabled_CheckpointsVersion2(t *testing.T) {
 	t.Parallel()
 	s := &EntireSettings{
 		Enabled:         true,
-		StrategyOptions: map[string]any{"checkpoints_v2_only": true},
+		StrategyOptions: map[string]any{"checkpoints_version": 2},
 	}
 	if !s.IsCheckpointsV2Enabled() {
-		t.Error("expected IsCheckpointsV2Enabled to be true when checkpoints_v2_only is enabled")
+		t.Error("expected IsCheckpointsV2Enabled to be true when checkpoints_version is 2")
 	}
 }
 
@@ -788,33 +788,34 @@ func TestIsCheckpointsV2Enabled_LocalOverride(t *testing.T) {
 	}
 }
 
-func TestIsCheckpointsV2OnlyEnabled_DefaultsFalse(t *testing.T) {
+func TestCheckpointsVersion(t *testing.T) {
 	t.Parallel()
-	s := &EntireSettings{Enabled: true}
-	if s.IsCheckpointsV2OnlyEnabled() {
-		t.Error("expected IsCheckpointsV2OnlyEnabled to default to false")
-	}
-}
 
-func TestIsCheckpointsV2OnlyEnabled_True(t *testing.T) {
-	t.Parallel()
-	s := &EntireSettings{
-		Enabled:         true,
-		StrategyOptions: map[string]any{"checkpoints_v2_only": true},
-	}
-	if !s.IsCheckpointsV2OnlyEnabled() {
-		t.Error("expected IsCheckpointsV2OnlyEnabled to be true")
+	tests := []struct {
+		name string
+		opts map[string]any
+		want int
+	}{
+		{"unset defaults to one", nil, 1},
+		{"empty options defaults to one", map[string]any{}, 1},
+		{"integer 2", map[string]any{"checkpoints_version": 2}, 2},
+		{"float 2 from json", map[string]any{"checkpoints_version": float64(2)}, 2},
+		{"integer 3 falls back to default", map[string]any{"checkpoints_version": 3}, 1},
+		{"zero falls back to default", map[string]any{"checkpoints_version": 0}, 1},
+		{"negative falls back to default", map[string]any{"checkpoints_version": -1}, 1},
+		{"non-integer float falls back to default", map[string]any{"checkpoints_version": 2.5}, 1},
+		{"string 2", map[string]any{"checkpoints_version": "2"}, 2},
+		{"bool falls back to default", map[string]any{"checkpoints_version": true}, 1},
 	}
-}
 
-func TestIsCheckpointsV2OnlyEnabled_WrongType(t *testing.T) {
-	t.Parallel()
-	s := &EntireSettings{
-		Enabled:         true,
-		StrategyOptions: map[string]any{"checkpoints_v2_only": "yes"},
-	}
-	if s.IsCheckpointsV2OnlyEnabled() {
-		t.Error("expected IsCheckpointsV2OnlyEnabled to be false for non-bool value")
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			s := &EntireSettings{StrategyOptions: tt.opts}
+			if got := s.CheckpointsVersion(); got != tt.want {
+				t.Errorf("CheckpointsVersion() = %d, want %d", got, tt.want)
+			}
+		})
 	}
 }
 
@@ -834,7 +835,7 @@ func TestIsPushV2RefsEnabled_RequiresBothFlags(t *testing.T) {
 		opts     map[string]any
 		expected bool
 	}{
-		{"v2 only supersedes both", map[string]any{"checkpoints_v2": false, "push_v2_refs": false, "checkpoints_v2_only": true}, true},
+		{"checkpoints_version 2 supersedes both", map[string]any{"checkpoints_v2": false, "push_v2_refs": false, "checkpoints_version": 2}, true},
 		{"both true", map[string]any{"checkpoints_v2": true, "push_v2_refs": true}, true},
 		{"only checkpoints_v2", map[string]any{"checkpoints_v2": true}, false},
 		{"only push_v2_refs", map[string]any{"push_v2_refs": true}, false},

cmd/entire/cli/strategy/checkpoint_remote.go

@@ -83,9 +83,9 @@ func resolvePushSettings(ctx context.Context, pushRemoteName string) pushSetting
 
 	ps.checkpointURL = checkpointURL
 
-	// Skip the v1 metadata-branch fetch entirely in v2-only mode — there is no
-	// v1 branch being written or pushed, so there is nothing to sync.
-	if !s.IsCheckpointsV2OnlyEnabled() {
+	// Skip the v1 metadata-branch fetch entirely when checkpoints_version is 2 —
+	// there is no v1 branch being written or pushed, so there is nothing to sync.
+	if s.CheckpointsVersion() != 2 {
 		// If the v1 checkpoint branch doesn't exist locally, try to fetch it from the URL.
 		// This is a one-time operation — once the branch exists locally, subsequent pushes
 		// skip the fetch entirely. Only fetch the metadata branch; trails are always pushed

cmd/entire/cli/strategy/manual_commit_condensation.go

@@ -254,12 +254,12 @@ func (s *ManualCommitStrategy) CondenseSession(ctx context.Context, repo *git.Re
 
 	compactTranscriptDuration := buildCompactTranscript(ctx, ag, redactedTranscript, state, &writeOpts)
 
-	v2Only := settings.IsCheckpointsV2OnlyEnabled(ctx)
+	v2 := settings.CheckpointsVersion(ctx) == 2
 
 	// Write checkpoint metadata to the primary store.
 	writeV1Start := time.Now()
 	writeCtx, writeCommittedSpan := perf.Start(ctx, "write_committed_v1")
-	if !v2Only {
+	if !v2 {
 		if err := store.WriteCommitted(writeCtx, writeOpts); err != nil {
 			writeCommittedSpan.RecordError(err)
 			writeCommittedSpan.End()
@@ -271,7 +271,7 @@ func (s *ManualCommitStrategy) CondenseSession(ctx context.Context, repo *git.Re
 
 	writeV2Start := time.Now()
 	writeV2Ctx, writeCommittedV2Span := perf.Start(ctx, "write_committed_v2")
-	if v2Only {
+	if v2 {
 		if err := writeCommittedV2(writeV2Ctx, repo, writeOpts); err != nil {
 			writeCommittedV2Span.RecordError(err)
 			writeCommittedV2Span.End()

cmd/entire/cli/strategy/manual_commit_hooks.go

@@ -2745,7 +2745,7 @@ func (s *ManualCommitStrategy) finalizeAllTurnCheckpoints(ctx context.Context, s
 	}
 
 	store := checkpoint.NewGitStore(repo)
-	v2Only := settings.IsCheckpointsV2OnlyEnabled(logCtx)
+	v2 := settings.CheckpointsVersion(logCtx) == 2
 
 	// Evaluate v2 flag once before the loop to avoid re-reading settings per checkpoint
 	var v2Store *checkpoint.V2GitStore
@@ -2790,7 +2790,7 @@ func (s *ManualCommitStrategy) finalizeAllTurnCheckpoints(ctx context.Context, s
 				content *checkpoint.SessionContent
 				readErr error
 			)
-			if v2Only {
+			if v2 {
 				content, readErr = v2Store.ReadSessionContentByID(ctx, cpID, state.SessionID)
 			} else {
 				content, readErr = store.ReadSessionContentByID(ctx, cpID, state.SessionID)
@@ -2812,7 +2812,7 @@ func (s *ManualCommitStrategy) finalizeAllTurnCheckpoints(ctx context.Context, s
 			updateOpts.CompactTranscript = compactTranscriptForV2(logCtx, finalAg, redactedTranscript, startLine)
 		}
 
-		if !v2Only {
+		if !v2 {
 			updateErr := store.UpdateCommitted(ctx, updateOpts)
 			if updateErr != nil {
 				logging.Warn(logCtx, "finalize: failed to update checkpoint",
@@ -2830,7 +2830,7 @@ func (s *ManualCommitStrategy) finalizeAllTurnCheckpoints(ctx context.Context, s
 					slog.String("checkpoint_id", cpIDStr),
 					slog.String("error", v2Err.Error()),
 				}
-				if v2Only {
+				if v2 {
 					logging.Warn(logCtx, "finalize: failed to update checkpoint in v2", attrs...)
 					errCount++
 					continue