Add Go v2 checkpoint migration tool

cmd/entire/cli/checkpoint/checkpoint.go

@@ -212,6 +212,10 @@ type WriteCommittedOptions struct {
 	// the original v1 checkpoint time in v2 metadata.
 	CreatedAt time.Time
 
+	// CommitTime is the optional git author/committer timestamp for the
+	// metadata-branch commit. When zero, writers use the current time.
+	CommitTime time.Time
+
 	// Strategy is the name of the strategy that created this checkpoint
 	Strategy string
 

cmd/entire/cli/checkpoint/committed.go

@@ -117,7 +117,11 @@ func (s *GitStore) WriteCommitted(ctx context.Context, opts WriteCommittedOption
 	}
 
 	commitMsg := s.buildCommitMessage(opts, taskMetadataPath)
-	newCommitHash, err := s.createCommit(ctx, newTreeHash, parentHash, commitMsg, opts.AuthorName, opts.AuthorEmail)
+	commitTime := opts.CommitTime
+	if commitTime.IsZero() {
+		commitTime = time.Now()
+	}
+	newCommitHash, err := s.createCommitAt(ctx, newTreeHash, parentHash, commitMsg, opts.AuthorName, opts.AuthorEmail, commitTime)
 	if err != nil {
 		return err
 	}
@@ -1932,11 +1936,14 @@ func GetGitAuthorFromRepo(repo *git.Repository) (name, email string) {
 // CreateCommit creates a git commit object with the given tree, parent, message, and author.
 // If parentHash is ZeroHash, the commit is created without a parent (orphan commit).
 func CreateCommit(ctx context.Context, repo *git.Repository, treeHash, parentHash plumbing.Hash, message, authorName, authorEmail string) (plumbing.Hash, error) {
-	now := time.Now()
+	return createCommitObject(ctx, repo, treeHash, parentHash, message, authorName, authorEmail, time.Now())
+}
+
+func createCommitObject(ctx context.Context, repo *git.Repository, treeHash, parentHash plumbing.Hash, message, authorName, authorEmail string, commitTime time.Time) (plumbing.Hash, error) {
 	sig := object.Signature{
 		Name:  authorName,
 		Email: authorEmail,
-		When:  now,
+		When:  commitTime,
 	}
 
 	commit := &object.Commit{

cmd/entire/cli/checkpoint/committed_commit_time_test.go

@@ -0,0 +1,133 @@
+package checkpoint
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"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/redact"
+
+	"github.com/go-git/go-git/v6"
+	"github.com/go-git/go-git/v6/plumbing"
+	"github.com/go-git/go-git/v6/plumbing/object"
+	"github.com/stretchr/testify/require"
+)
+
+const (
+	commitTimeStrategy   = "manual-commit"
+	commitTimeTestAuthor = "Test"
+	commitTimeTestEmail  = "test@example.com"
+)
+
+func TestWriteCommitted_CommitTime(t *testing.T) {
+	t.Parallel()
+
+	repo, store := setupCommittedCommitTimeRepo(t)
+	commitTime := time.Date(2024, 3, 2, 1, 2, 3, 0, time.UTC)
+
+	err := store.WriteCommitted(context.Background(), WriteCommittedOptions{
+		CheckpointID: id.MustCheckpointID("a1b2c3d4e5f6"),
+		SessionID:    "session-commit-time",
+		CreatedAt:    time.Date(2024, 3, 1, 1, 2, 3, 0, time.UTC),
+		CommitTime:   commitTime,
+		Strategy:     commitTimeStrategy,
+		Transcript:   redact.AlreadyRedacted([]byte("transcript line\n")),
+		AuthorName:   "Migration",
+		AuthorEmail:  "migration@example.com",
+	})
+	require.NoError(t, err)
+
+	commit := metadataHeadCommit(t, repo)
+	require.True(t, commit.Author.When.Equal(commitTime), "author time = %s, want %s", commit.Author.When, commitTime)
+	require.True(t, commit.Committer.When.Equal(commitTime), "committer time = %s, want %s", commit.Committer.When, commitTime)
+}
+
+func TestWriteCommitted_ZeroCommitTimeUsesCurrentTime(t *testing.T) {
+	t.Parallel()
+
+	repo, store := setupCommittedCommitTimeRepo(t)
+	createdAt := time.Date(2020, 1, 2, 3, 4, 5, 0, time.UTC)
+	before := time.Now().Add(-time.Second)
+
+	err := store.WriteCommitted(context.Background(), WriteCommittedOptions{
+		CheckpointID: id.MustCheckpointID("b2c3d4e5f6a1"),
+		SessionID:    "session-current-time",
+		CreatedAt:    createdAt,
+		Strategy:     commitTimeStrategy,
+		Transcript:   redact.AlreadyRedacted([]byte("transcript line\n")),
+		AuthorName:   commitTimeTestAuthor,
+		AuthorEmail:  commitTimeTestEmail,
+	})
+	require.NoError(t, err)
+	after := time.Now().Add(time.Second)
+
+	commit := metadataHeadCommit(t, repo)
+	require.False(t, commit.Author.When.Equal(createdAt), "zero CommitTime should not reuse CreatedAt as the commit timestamp")
+	require.False(t, commit.Author.When.Before(before), "author time = %s, want no earlier than %s", commit.Author.When, before)
+	require.False(t, commit.Author.When.After(after), "author time = %s, want no later than %s", commit.Author.When, after)
+	require.True(t, commit.Committer.When.Equal(commit.Author.When), "committer time = %s, want author time %s", commit.Committer.When, commit.Author.When)
+}
+
+func TestV2WriteCommitted_CommitTime(t *testing.T) {
+	t.Parallel()
+
+	repo, _ := setupCommittedCommitTimeRepo(t)
+	store := NewV2GitStore(repo)
+	commitTime := time.Date(2024, 4, 5, 6, 7, 8, 0, time.UTC)
+
+	err := store.WriteCommitted(context.Background(), WriteCommittedOptions{
+		CheckpointID: id.MustCheckpointID("c3d4e5f6a1b2"),
+		SessionID:    "session-v2-commit-time",
+		CreatedAt:    time.Date(2024, 4, 1, 2, 3, 4, 0, time.UTC),
+		CommitTime:   commitTime,
+		Strategy:     commitTimeStrategy,
+		Transcript:   redact.AlreadyRedacted([]byte("transcript line\n")),
+		AuthorName:   "Migration",
+		AuthorEmail:  "migration@example.com",
+	})
+	require.NoError(t, err)
+
+	mainCommit := refHeadCommit(t, repo, plumbing.ReferenceName(paths.V2MainRefName))
+	fullCommit := refHeadCommit(t, repo, plumbing.ReferenceName(paths.V2FullCurrentRefName))
+	for _, commit := range []*object.Commit{mainCommit, fullCommit} {
+		require.True(t, commit.Author.When.Equal(commitTime), "author time = %s, want %s", commit.Author.When, commitTime)
+		require.True(t, commit.Committer.When.Equal(commitTime), "committer time = %s, want %s", commit.Committer.When, commitTime)
+	}
+}
+
+func setupCommittedCommitTimeRepo(t *testing.T) (*git.Repository, *GitStore) {
+	t.Helper()
+
+	dir := t.TempDir()
+	testutil.InitRepo(t, dir)
+
+	repo, err := git.PlainOpen(dir)
+	require.NoError(t, err)
+
+	testutil.WriteFile(t, dir, "README.md", "# Test\n")
+	testutil.GitAdd(t, dir, "README.md")
+	testutil.GitCommit(t, dir, "initial commit")
+
+	return repo, NewGitStore(repo)
+}
+
+func metadataHeadCommit(t *testing.T, repo *git.Repository) *object.Commit {
+	t.Helper()
+
+	return refHeadCommit(t, repo, plumbing.NewBranchReferenceName(paths.MetadataBranchName))
+}
+
+func refHeadCommit(t *testing.T, repo *git.Repository, refName plumbing.ReferenceName) *object.Commit {
+	t.Helper()
+
+	ref, err := repo.Reference(refName, true)
+	require.NoError(t, err)
+
+	commit, err := repo.CommitObject(ref.Hash())
+	require.NoError(t, err)
+
+	return commit
+}

cmd/entire/cli/checkpoint/temporary.go

@@ -849,6 +849,10 @@ func (s *GitStore) createCommit(ctx context.Context, treeHash, parentHash plumbi
 	return CreateCommit(ctx, s.repo, treeHash, parentHash, message, authorName, authorEmail)
 }
 
+func (s *GitStore) createCommitAt(ctx context.Context, treeHash, parentHash plumbing.Hash, message, authorName, authorEmail string, commitTime time.Time) (plumbing.Hash, error) {
+	return createCommitObject(ctx, s.repo, treeHash, parentHash, message, authorName, authorEmail, commitTime)
+}
+
 // Helper functions extracted from strategy/common.go
 // These are exported for use by strategy package (push_common.go, session_test.go)
 

cmd/entire/cli/checkpoint/v2_committed.go

@@ -10,6 +10,7 @@ import (
 	"os"
 	"strconv"
 	"strings"
+	"time"
 
 	"github.com/entireio/cli/cmd/entire/cli/agent"
 	"github.com/entireio/cli/cmd/entire/cli/agent/types"
@@ -141,7 +142,14 @@ func (s *V2GitStore) WriteCommittedMainBatch(ctx context.Context, batch []WriteC
 			authorEmail = fallbackEmail
 		}
 	}
-	return s.updateRef(ctx, refName, rootTreeHash, parentHash, commitMsg, authorName, authorEmail)
+	return s.updateRefAt(ctx, refName, rootTreeHash, parentHash, commitMsg, authorName, authorEmail, commitTimeForWrite(last))
+}
+
+func commitTimeForWrite(opts WriteCommittedOptions) time.Time {
+	if opts.CommitTime.IsZero() {
+		return time.Now()
+	}
+	return opts.CommitTime
 }
 
 func (s *V2GitStore) existingMainCheckpointIDs(ctx context.Context, rootTreeHash plumbing.Hash) (map[id.CheckpointID]struct{}, error) {
@@ -353,7 +361,7 @@ func (s *V2GitStore) UpdateCommitted(ctx context.Context, opts UpdateCommittedOp
 }
 
 // fullSessionArtifacts describes where a checkpoint session's raw transcript
-// artifacts live on the v2 /full/current ref.
+// artifacts live on a v2 /full ref.
 type fullSessionArtifacts struct {
 	RefName       plumbing.ReferenceName
 	Found         bool
@@ -362,7 +370,7 @@ type fullSessionArtifacts struct {
 }
 
 // HasFullSessionArtifacts reports whether the raw transcript and content hash
-// for a checkpoint session exist in the local v2 /full/current ref.
+// for a checkpoint session exist in the local v2 /full refs.
 func (s *V2GitStore) HasFullSessionArtifacts(checkpointID id.CheckpointID, sessionIndex int) (bool, error) {
 	artifacts, err := s.findFullSessionArtifacts(checkpointID, sessionIndex)
 	if err != nil {
@@ -401,13 +409,13 @@ func (s *V2GitStore) findFullSessionArtifacts(checkpointID id.CheckpointID, sess
 	return fullSessionArtifacts{}, nil
 }
 
-// FullSessionArtifactsIndex answers "does this session have complete /full/current
+// FullSessionArtifactsIndex answers "does this session have complete /full
 // artifacts?" with an O(1) map lookup. Build it once via
 // BuildFullSessionArtifactsIndex.
 type FullSessionArtifactsIndex map[string]struct{}
 
 // Has reports whether the given session has a complete pair of
-// raw_transcript and raw_transcript_hash.txt entries in /full/current.
+// raw_transcript and raw_transcript_hash.txt entries in a /full ref.
 func (idx FullSessionArtifactsIndex) Has(checkpointID id.CheckpointID, sessionIndex int) bool {
 	if idx == nil {
 		return false
@@ -420,7 +428,7 @@ func fullArtifactsIndexKey(checkpointID id.CheckpointID, sessionIndex int) strin
 	return string(checkpointID) + "/" + strconv.Itoa(sessionIndex)
 }
 
-// BuildFullSessionArtifactsIndex walks the /full/current ref's tree once and
+// BuildFullSessionArtifactsIndex walks the local /full refs once and
 // records sessions whose subtree contains both raw_transcript[/.NNN] and
 // raw_transcript_hash.txt. Amortizes per-session HasFullSessionArtifacts
 // calls across the rest of the run.
@@ -511,7 +519,17 @@ func sessionHasCompleteFullArtifacts(entries []object.TreeEntry) bool {
 }
 
 func (s *V2GitStore) fullRefSearchOrder() ([]plumbing.ReferenceName, error) {
-	return []plumbing.ReferenceName{plumbing.ReferenceName(paths.V2FullCurrentRefName)}, nil
+	archived, err := s.listArchivedFullRefs()
+	if err != nil {
+		return nil, err
+	}
+
+	refNames := make([]plumbing.ReferenceName, 0, len(archived)+1)
+	refNames = append(refNames, plumbing.ReferenceName(paths.V2FullCurrentRefName))
+	for i := len(archived) - 1; i >= 0; i-- {
+		refNames = append(refNames, archived[i])
+	}
+	return refNames, nil
 }
 
 func (s *V2GitStore) inspectFullSessionArtifacts(refName plumbing.ReferenceName, checkpointID id.CheckpointID, sessionIndex int) (fullSessionArtifacts, error) {
@@ -668,18 +686,12 @@ func (s *V2GitStore) updateCommittedMain(ctx context.Context, opts UpdateCommitt
 func (s *V2GitStore) updateCommittedFullTranscript(ctx context.Context, opts UpdateCommittedOptions, sessionIndex int) error {
 	refName := plumbing.ReferenceName(paths.V2FullCurrentRefName)
 
-	existing, findErr := s.findFullSessionArtifacts(opts.CheckpointID, sessionIndex)
-	if findErr != nil {
-		return findErr
-	}
-	if existing.Found {
-		refName = existing.RefName
+	if _, err := s.inspectFullSessionArtifacts(refName, opts.CheckpointID, sessionIndex); err != nil {
+		return err
 	}
 
-	if refName == plumbing.ReferenceName(paths.V2FullCurrentRefName) {
-		if err := s.ensureRef(ctx, refName); err != nil {
-			return fmt.Errorf("failed to ensure /full/current ref: %w", err)
-		}
+	if err := s.ensureRef(ctx, refName); err != nil {
+		return fmt.Errorf("failed to ensure /full/current ref: %w", err)
 	}
 
 	parentHash, rootTreeHash, err := s.GetRefState(refName)
@@ -802,7 +814,7 @@ func (s *V2GitStore) writeCommittedMain(ctx context.Context, opts WriteCommitted
 	}
 
 	commitMsg := fmt.Sprintf("Checkpoint: %s\n", opts.CheckpointID)
-	if err := s.updateRef(ctx, refName, newTreeHash, parentHash, commitMsg, opts.AuthorName, opts.AuthorEmail); err != nil {
+	if err := s.updateRefAt(ctx, refName, newTreeHash, parentHash, commitMsg, opts.AuthorName, opts.AuthorEmail, commitTimeForWrite(opts)); err != nil {
 		return 0, err
 	}
 	return sessionIndex, nil
@@ -1053,7 +1065,7 @@ func (s *V2GitStore) writeCommittedFullTranscript(ctx context.Context, opts Writ
 	}
 
 	commitMsg := fmt.Sprintf("Checkpoint: %s\n", opts.CheckpointID)
-	if err := s.updateRef(ctx, refName, newTreeHash, parentHash, commitMsg, opts.AuthorName, opts.AuthorEmail); err != nil {
+	if err := s.updateRefAt(ctx, refName, newTreeHash, parentHash, commitMsg, opts.AuthorName, opts.AuthorEmail, commitTimeForWrite(opts)); err != nil {
 		return err
 	}
 

cmd/entire/cli/checkpoint/v2_read.go

@@ -260,7 +260,7 @@ func (s *V2GitStore) ReadSessionPrompts(ctx context.Context, checkpointID id.Che
 }
 
 // ReadSessionContent reads a session's metadata and prompts from the v2 /main ref,
-// and the raw transcript (raw_transcript) from /full/current.
+// and the raw transcript (raw_transcript) from local or remote /full refs.
 // This is the v2 equivalent of GitStore.ReadSessionContent — it reads the raw agent
 // transcript, not the compact transcript.jsonl. Used by resume and RestoreLogsOnly.
 // Returns ErrNoTranscript if the session exists but no raw transcript is available.

cmd/entire/cli/checkpoint/v2_store.go

@@ -7,6 +7,7 @@ import (
 	"log/slog"
 	"os/exec"
 	"strings"
+	"time"
 
 	"github.com/entireio/cli/cmd/entire/cli/logging"
 
@@ -130,7 +131,11 @@ func commitTreeHashViaCLI(ctx context.Context, commitHash plumbing.Hash) (plumbi
 
 // updateRef creates a new commit on a ref with the given tree, updating the ref to point to it.
 func (s *V2GitStore) updateRef(ctx context.Context, refName plumbing.ReferenceName, treeHash, parentHash plumbing.Hash, message, authorName, authorEmail string) error {
-	commitHash, err := CreateCommit(ctx, s.repo, treeHash, parentHash, message, authorName, authorEmail)
+	return s.updateRefAt(ctx, refName, treeHash, parentHash, message, authorName, authorEmail, time.Now())
+}
+
+func (s *V2GitStore) updateRefAt(ctx context.Context, refName plumbing.ReferenceName, treeHash, parentHash plumbing.Hash, message, authorName, authorEmail string, commitTime time.Time) error {
+	commitHash, err := createCommitObject(ctx, s.repo, treeHash, parentHash, message, authorName, authorEmail, commitTime)
 	if err != nil {
 		return fmt.Errorf("failed to create commit: %w", err)
 	}