Expand checkpoints v2 validation coverage

.github/workflows/e2e-checkpoints-v2.yml

@@ -0,0 +1,51 @@
+name: E2E Checkpoints V2
+
+on:
+  workflow_dispatch:
+    inputs:
+      agent:
+        description: "Agent to run"
+        required: true
+        default: "vogon"
+        type: choice
+        options:
+          - vogon
+          - claude-code
+          - opencode
+          - gemini-cli
+          - factoryai-droid
+          - cursor-cli
+          - copilot-cli
+          - roger-roger
+          - codex
+      checkpoints_mode:
+        description: "Checkpoints mode to run"
+        required: true
+        default: "v2-dual-write"
+        type: choice
+        options:
+          - v2-dual-write
+          - v2-only
+
+jobs:
+  e2e-checkpoints-v2:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+
+      - name: Setup Keyring
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gnome-keyring
+          echo 'somecredstorepass' | gnome-keyring-daemon --unlock
+
+      - uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4
+
+      - name: E2E Canary (Checkpoints V2)
+        env:
+          E2E_AGENT: ${{ inputs.agent }}
+          E2E_CHECKPOINTS_MODE: ${{ inputs.checkpoints_mode }}
+        run: mise run test:e2e:canary

cmd/entire/cli/attach_test.go

@@ -226,6 +226,63 @@ func TestAttach_V2DualWriteEnabled(t *testing.T) {
 	}
 }
 
+func TestAttach_CheckpointsVersion2(t *testing.T) {
+	setupAttachTestRepo(t)
+
+	repoDir := mustGetwd(t)
+	setAttachCheckpointsVersion2Enabled(t, repoDir)
+
+	sessionID := "test-attach-v2-only"
+	setupClaudeTranscript(t, sessionID, `{"type":"user","message":{"role":"user","content":"create hello.txt"},"uuid":"uuid-1"}
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","id":"tu_1","name":"Write","input":{"file_path":"hello.txt","content":"hello"}}]},"uuid":"uuid-2"}
+{"type":"user","message":{"content":[{"type":"tool_result","tool_use_id":"tu_1","content":"wrote file"}]},"uuid":"uuid-3"}
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Done."}]},"uuid":"uuid-4"}
+`)
+
+	var out bytes.Buffer
+	if err := runAttach(context.Background(), &out, sessionID, agent.AgentNameClaudeCode, true); err != nil {
+		t.Fatalf("runAttach failed: %v", err)
+	}
+
+	store, err := session.NewStateStore(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	state, err := store.Load(context.Background(), sessionID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if state == nil || state.LastCheckpointID.IsEmpty() {
+		t.Fatal("expected attach to persist a checkpoint ID")
+	}
+
+	repo, err := git.PlainOpen(repoDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	cpPath := state.LastCheckpointID.Path()
+	if _, found := readFileFromRef(t, repo, paths.MetadataBranchName, cpPath+"/"+paths.MetadataFileName); found {
+		t.Fatalf("did not expect %s metadata for %s when checkpoints_version is 2", paths.MetadataBranchName, cpPath)
+	}
+
+	mainCompact, found := readFileFromRef(t, repo, paths.V2MainRefName, cpPath+"/0/"+paths.CompactTranscriptFileName)
+	if !found {
+		t.Fatalf("expected %s on %s", paths.CompactTranscriptFileName, paths.V2MainRefName)
+	}
+	if !strings.Contains(mainCompact, "create hello.txt") {
+		t.Errorf("compact transcript missing prompt, got:\n%s", mainCompact)
+	}
+
+	fullTranscript, found := readFileFromRef(t, repo, paths.V2FullCurrentRefName, cpPath+"/0/"+paths.V2RawTranscriptFileName)
+	if !found {
+		t.Fatalf("expected %s on %s", paths.V2RawTranscriptFileName, paths.V2FullCurrentRefName)
+	}
+	if !strings.Contains(fullTranscript, "hello.txt") {
+		t.Errorf("raw transcript missing file content, got:\n%s", fullTranscript)
+	}
+}
+
 func TestAttach_V2DualWriteDisabled(t *testing.T) {
 	setupAttachTestRepo(t)
 
@@ -741,6 +798,18 @@ func setAttachCheckpointsV2Enabled(t *testing.T, repoDir string) {
 	}
 }
 
+func setAttachCheckpointsVersion2Enabled(t *testing.T, repoDir string) {
+	t.Helper()
+	entireDir := filepath.Join(repoDir, ".entire")
+	if err := os.MkdirAll(entireDir, 0o750); err != nil {
+		t.Fatal(err)
+	}
+	settingsContent := `{"enabled": true, "strategy_options": {"checkpoints_version": 2}}`
+	if err := os.WriteFile(filepath.Join(entireDir, "settings.json"), []byte(settingsContent), 0o600); err != nil {
+		t.Fatal(err)
+	}
+}
+
 func mustGetwd(t *testing.T) string {
 	t.Helper()
 	dir, err := os.Getwd()

cmd/entire/cli/integration_test/interactive.go

@@ -25,6 +25,7 @@ func (env *TestEnv) RunCommandInteractive(args []string, respond func(ptyFile *o
 	cmd.Dir = env.RepoDir
 	cmd.Env = append(testutil.GitIsolatedEnv(),
 		"ENTIRE_TEST_CLAUDE_PROJECT_DIR="+env.ClaudeProjectDir,
+		"ENTIRE_TEST_TTY=1",
 		"TERM=xterm",
 		"ACCESSIBLE=1", // Required: makes huh read from stdin instead of /dev/tty
 	)

cmd/entire/cli/integration_test/v2_dual_write_test.go

@@ -294,3 +294,64 @@ func TestCheckpointsVersion2_SkipsV1Write(t *testing.T) {
 	assert.True(t, env.RefExists(paths.V2MainRefName), "v2 /main ref should exist")
 	assert.True(t, env.RefExists(paths.V2FullCurrentRefName), "v2 /full/current ref should exist")
 }
+
+// TestCheckpointsVersion2_HookDrivenCommitOnMain verifies the same hook-driven
+// prompt -> stop -> commit flow used by the attach E2E precondition setup. In
+// checkpoints_version: 2 mode, the normal git hook path should still write only
+// v2 refs even when committing on the default branch.
+func TestCheckpointsVersion2_HookDrivenCommitOnMain(t *testing.T) {
+	t.Parallel()
+	env := NewTestEnv(t)
+	defer env.Cleanup()
+
+	env.InitRepo()
+	env.WriteFile("README.md", "# Test")
+	env.WriteFile(".gitignore", ".entire/\n")
+	env.GitAdd("README.md")
+	env.GitAdd(".gitignore")
+	env.GitCommit("Initial commit")
+
+	env.InitEntireWithOptions(map[string]any{
+		"checkpoints_version": 2,
+	})
+
+	// Mirror the E2E flow: enable is committed first, then a normal prompt/stop
+	// cycle produces content that the subsequent user commit condenses.
+	env.GitAdd(".entire/settings.json")
+	env.GitCommit("Enable entire")
+
+	session := env.NewSession()
+	require.NoError(t, env.SimulateUserPromptSubmitWithPrompt(session.ID, "Add existing checkpoint doc"))
+
+	env.WriteFile("docs/existing.md", "# Existing\n\nA short paragraph about existing checkpoints.\n")
+	session.CreateTranscript(
+		"Add existing checkpoint doc",
+		[]FileChange{{Path: "docs/existing.md", Content: "# Existing\n\nA short paragraph about existing checkpoints.\n"}},
+	)
+	require.NoError(t, env.SimulateStop(session.ID, session.TranscriptPath))
+
+	env.GitCommitWithShadowHooks("Add existing checkpoint doc", "docs/existing.md")
+
+	cpIDStr := env.GetLatestCheckpointIDFromHistory()
+	require.NotEmpty(t, cpIDStr, "checkpoint ID should be in commit trailer")
+
+	cpID, err := id.NewCheckpointID(cpIDStr)
+	require.NoError(t, err)
+	cpPath := cpID.Path()
+
+	// v1 should remain absent in strict v2-only mode.
+	_, found := env.ReadFileFromBranch(paths.MetadataBranchName, cpPath+"/"+paths.MetadataFileName)
+	assert.False(t, found, "v1 metadata branch should not be used when checkpoints_version is 2")
+
+	// v2 refs should contain the checkpoint created by the normal hook path.
+	assert.True(t, env.RefExists(paths.V2MainRefName), "v2 /main ref should exist after hook-driven commit")
+	assert.True(t, env.RefExists(paths.V2FullCurrentRefName), "v2 /full/current ref should exist after hook-driven commit")
+
+	mainSummary, found := env.ReadFileFromRef(paths.V2MainRefName, cpPath+"/"+paths.MetadataFileName)
+	require.True(t, found, "v2 /main metadata.json should exist")
+	assert.Contains(t, mainSummary, cpIDStr)
+
+	fullTranscript, found := env.ReadFileFromRef(paths.V2FullCurrentRefName, cpPath+"/0/"+paths.V2RawTranscriptFileName)
+	require.True(t, found, "v2 /full/current raw transcript should exist")
+	assert.Contains(t, fullTranscript, "existing checkpoints")
+}

cmd/entire/cli/integration_test/v2_resume_test.go

@@ -8,6 +8,7 @@ import (
 	"path/filepath"
 	"testing"
 
+	"github.com/entireio/cli/cmd/entire/cli/checkpoint/id"
 	"github.com/entireio/cli/cmd/entire/cli/paths"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -182,3 +183,63 @@ func TestV2Resume_FallsBackToV1(t *testing.T) {
 	assert.Contains(t, output, "Restored session")
 	assert.Contains(t, output, "claude -r")
 }
+
+// TestCheckpointsVersion2Resume_SwitchBranchWithSession verifies that resume
+// works in strict v2-only mode. The session should be restorable from v2 refs
+// even though no v1 committed metadata was written.
+func TestCheckpointsVersion2Resume_SwitchBranchWithSession(t *testing.T) {
+	t.Parallel()
+	env := NewTestEnv(t)
+	defer env.Cleanup()
+
+	env.InitRepo()
+	env.WriteFile("README.md", "# Test")
+	env.WriteFile(".gitignore", ".entire/\n")
+	env.GitAdd("README.md")
+	env.GitAdd(".gitignore")
+	env.GitCommit("Initial commit")
+	env.GitCheckoutNewBranch("feature/v2-only-resume-test")
+
+	env.InitEntireWithOptions(map[string]any{
+		"checkpoints_version": 2,
+	})
+
+	session := env.NewSession()
+	err := env.SimulateUserPromptSubmitWithPrompt(session.ID, "Create hello script in v2 only mode")
+	require.NoError(t, err)
+
+	content := "puts 'Hello from v2-only session'"
+	env.WriteFile("hello_v2_only.rb", content)
+
+	session.CreateTranscript(
+		"Create hello script in v2 only mode",
+		[]FileChange{{Path: "hello_v2_only.rb", Content: content}},
+	)
+	err = env.SimulateStop(session.ID, session.TranscriptPath)
+	require.NoError(t, err)
+
+	env.GitCommitWithShadowHooks("Create hello script in v2 only mode", "hello_v2_only.rb")
+
+	cpIDStr := env.GetLatestCheckpointIDFromHistory()
+	require.NotEmpty(t, cpIDStr, "checkpoint ID should be in commit trailer")
+
+	cpID, err := id.NewCheckpointID(cpIDStr)
+	require.NoError(t, err)
+	_, found := env.ReadFileFromBranch(paths.MetadataBranchName, cpID.Path()+"/"+paths.MetadataFileName)
+	assert.False(t, found, "v1 committed checkpoint metadata should not exist when checkpoints_version is 2")
+
+	featureBranch := env.GetCurrentBranch()
+	env.GitCheckoutBranch("master")
+	assert.Equal(t, "master", env.GetCurrentBranch())
+
+	output, err := env.RunResume(featureBranch)
+	require.NoError(t, err, "resume failed: %s", output)
+
+	assert.Equal(t, featureBranch, env.GetCurrentBranch())
+	assert.Contains(t, output, "Restored session", "output should contain 'Restored session'")
+	assert.Contains(t, output, "claude -r", "output should contain resume command")
+
+	transcriptFiles, err := filepath.Glob(filepath.Join(env.ClaudeProjectDir, "*.jsonl"))
+	require.NoError(t, err)
+	assert.NotEmpty(t, transcriptFiles, "transcript should be restored to Claude project dir")
+}

e2e/agents/vogon.go

@@ -2,10 +2,13 @@ package agents
 
 import (
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
 	"errors"
 	"fmt"
 	"os"
 	"os/exec"
+	"path/filepath"
 	"strings"
 	"time"
 )
@@ -44,6 +47,7 @@ func (v *Vogon) RunPrompt(ctx context.Context, dir string, prompt string, opts .
 	cmd.Dir = dir
 	cmd.Stdin = nil
 	cmd.Env = filterEnv(os.Environ(), "ENTIRE_TEST_TTY")
+	cmd.Env = append(cmd.Env, "HOME="+vogonHomeDir(dir))
 	setupProcessGroup(cmd)
 	cmd.WaitDelay = 5 * time.Second
 
@@ -72,7 +76,7 @@ func (v *Vogon) RunPrompt(ctx context.Context, dir string, prompt string, opts .
 
 func (v *Vogon) StartSession(_ context.Context, dir string) (Session, error) {
 	name := fmt.Sprintf("vogon-test-%d", time.Now().UnixNano())
-	s, err := NewTmuxSession(name, dir, []string{"ENTIRE_TEST_TTY"}, v.Binary())
+	s, err := NewTmuxSession(name, dir, []string{"ENTIRE_TEST_TTY"}, "env", "HOME="+vogonHomeDir(dir), v.Binary())
 	if err != nil {
 		return nil, err
 	}
@@ -86,3 +90,72 @@ func (v *Vogon) StartSession(_ context.Context, dir string) (Session, error) {
 
 	return s, nil
 }
+
+// WriteSessionTranscript creates a deterministic vogon session transcript
+// without firing hooks or mutating the repository. Attach E2E tests use this
+// to prepare a session that `entire attach` can import.
+func (v *Vogon) WriteSessionTranscript(ctx context.Context, dir string, extraEnv []string, sessionID, userPrompt, assistantMessage string) (Output, error) {
+	args := []string{
+		"--write-session",
+		"--session-id", sessionID,
+		"--user-prompt", userPrompt,
+		"--assistant-message", assistantMessage,
+	}
+	displayArgs := []string{
+		"--write-session",
+		"--session-id", sessionID,
+		"--user-prompt", fmt.Sprintf("%q", userPrompt),
+		"--assistant-message", fmt.Sprintf("%q", assistantMessage),
+	}
+
+	cmd := exec.CommandContext(ctx, v.Binary(), args...)
+	cmd.Dir = dir
+	cmd.Stdin = nil
+	cmd.Env = filterEnv(os.Environ(), "ENTIRE_TEST_TTY")
+	cmd.Env = append(cmd.Env, extraEnv...)
+	if !hasEnvVar(extraEnv, "HOME") {
+		cmd.Env = append(cmd.Env, "HOME="+vogonHomeDir(dir))
+	}
+	setupProcessGroup(cmd)
+	cmd.WaitDelay = 5 * time.Second
+
+	var stdout, stderr strings.Builder
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+
+	err := cmd.Run()
+	exitCode := 0
+	if err != nil {
+		exitErr := &exec.ExitError{}
+		if errors.As(err, &exitErr) {
+			exitCode = exitErr.ExitCode()
+		} else {
+			exitCode = -1
+		}
+	}
+
+	return Output{
+		Command:  v.Binary() + " " + strings.Join(displayArgs, " "),
+		Stdout:   stdout.String(),
+		Stderr:   stderr.String(),
+		ExitCode: exitCode,
+	}, err
+}
+
+func vogonHomeDir(dir string) string {
+	sum := sha256.Sum256([]byte(dir))
+	homeDir := filepath.Join(os.TempDir(), "vogon-e2e-home-"+hex.EncodeToString(sum[:6]))
+	if err := os.MkdirAll(homeDir, 0o755); err != nil {
+		panic(fmt.Sprintf("create vogon home %s: %v", homeDir, err))
+	}
+	return homeDir
+}
+
+func hasEnvVar(env []string, key string) bool {
+	for _, entry := range env {
+		if strings.HasPrefix(entry, key+"=") {
+			return true
+		}
+	}
+	return false
+}