Fix migration retry-safety: reconcile sessions, preserve task metadata

- Narrow transcript deletion in updateCommittedFullTranscript to only
  remove transcript-specific files, preserving tasks/ metadata
- Reconcile missing tail sessions by comparing v1 vs v2 session counts
- Restore task metadata unconditionally during repair (idempotent via
  MergeKeepExisting)
- Add regression tests for partial migration retry, task metadata
  preservation, task metadata restoration, and archive-aware repair

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Entire-Checkpoint: 758494ac2835

Author: peyton-alt

cmd/entire/cli/checkpoint/v2_committed.go

@@ -207,9 +207,17 @@ func (s *V2GitStore) updateCommittedFullTranscript(ctx context.Context, opts Upd
 		return err
 	}
 
-	// Clear existing transcript entries at this session path before writing new ones
+	// Clear existing transcript entries at this session path before writing new ones.
+	// Only delete transcript-specific files (full.jsonl, chunks, content_hash.txt),
+	// preserving other entries like tasks/ metadata.
 	for key := range entries {
-		if strings.HasPrefix(key, sessionPath) {
+		if !strings.HasPrefix(key, sessionPath) {
+			continue
+		}
+		relName := key[len(sessionPath):]
+		if relName == paths.ContentHashFileName ||
+			relName == paths.TranscriptFileName ||
+			strings.HasPrefix(relName, paths.TranscriptFileName+".") {
 			delete(entries, key)
 		}
 	}

cmd/entire/cli/migrate.go

@@ -234,8 +234,21 @@ func migrateOneCheckpoint(ctx context.Context, repo *git.Repository, v1Store *ch
 func repairPartialV2Checkpoint(ctx context.Context, repo *git.Repository, v1Store *checkpoint.GitStore, v2Store *checkpoint.V2GitStore, info checkpoint.CommittedInfo, v2Summary *checkpoint.CheckpointSummary) (bool, error) {
 	repaired := false
 
-	// Spot-check already present sessions: ensure required /full/current artifacts exist.
+	// Load v1 summary once for reconciliation and task metadata repair.
+	v1Summary, err := v1Store.ReadCommitted(ctx, info.CheckpointID)
+	if err != nil {
+		return false, fmt.Errorf("failed to read v1 summary: %w", err)
+	}
+	if v1Summary == nil {
+		return false, nil
+	}
+
 	existingSessionCount := len(v2Summary.Sessions)
+
+	// Phase 1: Repair existing sessions with missing /full/current artifacts.
+	// Always check /full/current specifically — archived generations may not be
+	// pushed to remotes, so transcripts must exist in /full/current to be available
+	// on other clones.
 	for sessionIdx := range existingSessionCount {
 		ok, checkErr := hasCurrentFullSessionArtifacts(repo, v2Store, info.CheckpointID, sessionIdx)
 		if checkErr != nil {
@@ -267,6 +280,35 @@ func repairPartialV2Checkpoint(ctx context.Context, repo *git.Repository, v1Stor
 		repaired = true
 	}
 
+	// Phase 2: Append any v1 sessions that were never written to v2.
+	for sessionIdx := existingSessionCount; sessionIdx < len(v1Summary.Sessions); sessionIdx++ {
+		content, readErr := v1Store.ReadSessionContent(ctx, info.CheckpointID, sessionIdx)
+		if readErr != nil {
+			return false, fmt.Errorf("failed to read v1 session %d for reconciliation: %w", sessionIdx, readErr)
+		}
+
+		opts := buildMigrateWriteOpts(content, info)
+		if compacted := tryCompactTranscript(ctx, content.Transcript, content.Metadata); compacted != nil {
+			opts.CompactTranscript = compacted
+		}
+
+		if writeErr := v2Store.WriteCommitted(ctx, opts); writeErr != nil {
+			return false, fmt.Errorf("failed to write missing v2 session %d: %w", sessionIdx, writeErr)
+		}
+		repaired = true
+	}
+
+	// Phase 3: Restore task metadata unconditionally (idempotent via MergeKeepExisting).
+	// This handles both newly appended task sessions and existing sessions whose
+	// tasks/ subtree was deleted by a prior bad run. If no v1 sessions have task
+	// metadata, copyTaskMetadataToV2 returns nil after finding no tasks/ dirs.
+	if taskErr := copyTaskMetadataToV2(repo, v1Store, v2Store, info.CheckpointID, v1Summary); taskErr != nil {
+		logging.Warn(ctx, "failed to copy task metadata during repair",
+			slog.String("checkpoint_id", string(info.CheckpointID)),
+			slog.String("error", taskErr.Error()),
+		)
+	}
+
 	return repaired, nil
 }
 

cmd/entire/cli/migrate_test.go

@@ -390,7 +390,8 @@ func TestMigrateCheckpointsV2_RepairsCurrentFullEvenWhenArchiveExists(t *testing
 	require.NoError(t, archivedReadErr)
 	assert.NotEmpty(t, archivedRead.Transcript)
 
-	// Re-run migration: should still repair /full/current.
+	// Re-run migration: should still repair /full/current even though archive has the transcript.
+	// Archived generations may not be pushed to remotes, so /full/current must have it.
 	var rerun bytes.Buffer
 	result2, rerunErr := migrateCheckpointsV2(context.Background(), repo, v1Store, v2Store, &rerun)
 	require.NoError(t, rerunErr)
@@ -455,6 +456,184 @@ func TestBuildMigrateWriteOpts_PromptSeparatorRoundTrip(t *testing.T) {
 	assert.Equal(t, "second prompt", opts.Prompts[1])
 }
 
+func TestMigrateCheckpointsV2_RepairAppendsMissingSessions(t *testing.T) {
+	t.Parallel()
+	repo := initMigrateTestRepo(t)
+	v1Store, v2Store := newMigrateStores(repo)
+
+	cpID := id.MustCheckpointID("aabb11223344")
+
+	// Write 3 sessions to v1.
+	for i := range 3 {
+		writeV1Checkpoint(t, v1Store, cpID, "session-reconcile-"+strconv.Itoa(i),
+			[]byte("{\"type\":\"assistant\",\"message\":\"session "+strconv.Itoa(i)+"\"}\n"),
+			[]string{"prompt " + strconv.Itoa(i)},
+		)
+	}
+
+	// Simulate partial migration: write only the first session to v2.
+	content0, err := v1Store.ReadSessionContent(context.Background(), cpID, 0)
+	require.NoError(t, err)
+	require.NoError(t, v2Store.WriteCommitted(context.Background(), checkpoint.WriteCommittedOptions{
+		CheckpointID: cpID,
+		SessionID:    content0.Metadata.SessionID,
+		Strategy:     "manual-commit",
+		Transcript:   content0.Transcript,
+		Prompts:      checkpoint.SplitPromptContent(content0.Prompts),
+		AuthorName:   "Test",
+		AuthorEmail:  "test@test.com",
+	}))
+
+	// Verify v2 currently has only 1 session.
+	before, readErr := v2Store.ReadCommitted(context.Background(), cpID)
+	require.NoError(t, readErr)
+	require.Len(t, before.Sessions, 1, "precondition: v2 should have 1 session before repair")
+
+	// Rerun migration — should reconcile and append the missing sessions.
+	var stdout bytes.Buffer
+	result, migrateErr := migrateCheckpointsV2(context.Background(), repo, v1Store, v2Store, &stdout)
+	require.NoError(t, migrateErr)
+	assert.Equal(t, 1, result.migrated)
+	assert.Contains(t, stdout.String(), "repaired partial v2 checkpoint state")
+
+	after, readAfterErr := v2Store.ReadCommitted(context.Background(), cpID)
+	require.NoError(t, readAfterErr)
+	assert.Len(t, after.Sessions, 3, "all 3 v1 sessions should exist in v2 after reconciliation")
+}
+
+func TestMigrateCheckpointsV2_RepairPreservesTaskMetadata(t *testing.T) {
+	t.Parallel()
+	repo := initMigrateTestRepo(t)
+	v1Store, v2Store := newMigrateStores(repo)
+
+	cpID := id.MustCheckpointID("cc11dd22ee33")
+	err := v1Store.WriteCommitted(context.Background(), checkpoint.WriteCommittedOptions{
+		CheckpointID: cpID,
+		SessionID:    "session-task-preserve-001",
+		Strategy:     "manual-commit",
+		Transcript:   []byte("{\"type\":\"assistant\",\"message\":\"task work\"}\n"),
+		Prompts:      []string{"task prompt"},
+		IsTask:       true,
+		ToolUseID:    "toolu_preserve01",
+		AuthorName:   "Test",
+		AuthorEmail:  "test@test.com",
+	})
+	require.NoError(t, err)
+
+	// Full migration including task metadata.
+	var initialRun bytes.Buffer
+	result1, migrateErr := migrateCheckpointsV2(context.Background(), repo, v1Store, v2Store, &initialRun)
+	require.NoError(t, migrateErr)
+	assert.Equal(t, 1, result1.migrated)
+
+	// Verify task metadata was written to /full/current.
+	_, rootTreeHash, refErr := v2Store.GetRefState(plumbing.ReferenceName(paths.V2FullCurrentRefName))
+	require.NoError(t, refErr)
+	rootTree, treeErr := repo.TreeObject(rootTreeHash)
+	require.NoError(t, treeErr)
+	_, taskFileErr := rootTree.File(cpID.Path() + "/0/tasks/toolu_preserve01/checkpoint.json")
+	require.NoError(t, taskFileErr, "precondition: task metadata should exist before repair")
+
+	// Simulate interrupted migration by removing transcript files only.
+	removeV2SessionTranscriptFiles(t, repo, v2Store, cpID, 0)
+
+	// Rerun migration — triggers repair.
+	var rerun bytes.Buffer
+	result2, rerunErr := migrateCheckpointsV2(context.Background(), repo, v1Store, v2Store, &rerun)
+	require.NoError(t, rerunErr)
+	assert.Equal(t, 1, result2.migrated)
+	assert.Contains(t, rerun.String(), "repaired partial v2 checkpoint state")
+
+	// Verify transcript was restored.
+	content, readErr := v2Store.ReadSessionContent(context.Background(), cpID, 0)
+	require.NoError(t, readErr)
+	assert.NotEmpty(t, content.Transcript, "transcript should be restored")
+
+	// Verify task metadata was NOT erased during repair.
+	_, rootTreeHash2, refErr2 := v2Store.GetRefState(plumbing.ReferenceName(paths.V2FullCurrentRefName))
+	require.NoError(t, refErr2)
+	rootTree2, treeErr2 := repo.TreeObject(rootTreeHash2)
+	require.NoError(t, treeErr2)
+	_, taskFileErr2 := rootTree2.File(cpID.Path() + "/0/tasks/toolu_preserve01/checkpoint.json")
+	require.NoError(t, taskFileErr2, "task metadata must survive transcript repair")
+}
+
+func TestMigrateCheckpointsV2_RepairRestoresDeletedTaskMetadata(t *testing.T) {
+	t.Parallel()
+	repo := initMigrateTestRepo(t)
+	v1Store, v2Store := newMigrateStores(repo)
+
+	cpID := id.MustCheckpointID("ee22ff334455")
+	err := v1Store.WriteCommitted(context.Background(), checkpoint.WriteCommittedOptions{
+		CheckpointID: cpID,
+		SessionID:    "session-task-restore-001",
+		Strategy:     "manual-commit",
+		Transcript:   []byte("{\"type\":\"assistant\",\"message\":\"task work\"}\n"),
+		Prompts:      []string{"task prompt"},
+		IsTask:       true,
+		ToolUseID:    "toolu_restore01",
+		AuthorName:   "Test",
+		AuthorEmail:  "test@test.com",
+	})
+	require.NoError(t, err)
+
+	// Full migration.
+	var initialRun bytes.Buffer
+	result1, migrateErr := migrateCheckpointsV2(context.Background(), repo, v1Store, v2Store, &initialRun)
+	require.NoError(t, migrateErr)
+	assert.Equal(t, 1, result1.migrated)
+
+	// Simulate prior bad run: delete ONLY tasks/ subtree (transcripts are intact).
+	// This tests that task metadata is restored even when no transcript repair is needed.
+	removeV2TaskMetadata(t, repo, v2Store, cpID, 0)
+
+	// Verify tasks/ is actually gone.
+	_, rootTreeHash, refErr := v2Store.GetRefState(plumbing.ReferenceName(paths.V2FullCurrentRefName))
+	require.NoError(t, refErr)
+	rootTree, treeErr := repo.TreeObject(rootTreeHash)
+	require.NoError(t, treeErr)
+	_, taskGoneErr := rootTree.File(cpID.Path() + "/0/tasks/toolu_restore01/checkpoint.json")
+	require.Error(t, taskGoneErr, "precondition: task metadata should be gone")
+
+	// Rerun migration — transcripts are fine, but task metadata should be restored.
+	var rerun bytes.Buffer
+	_, rerunErr := migrateCheckpointsV2(context.Background(), repo, v1Store, v2Store, &rerun)
+	require.NoError(t, rerunErr)
+
+	// Verify task metadata was restored.
+	_, rootTreeHash2, refErr2 := v2Store.GetRefState(plumbing.ReferenceName(paths.V2FullCurrentRefName))
+	require.NoError(t, refErr2)
+	rootTree2, treeErr2 := repo.TreeObject(rootTreeHash2)
+	require.NoError(t, treeErr2)
+	_, taskFileErr := rootTree2.File(cpID.Path() + "/0/tasks/toolu_restore01/checkpoint.json")
+	require.NoError(t, taskFileErr, "task metadata must be restored even when transcripts are intact")
+}
+
+// removeV2TaskMetadata deletes the tasks/ subtree from a session in /full/current.
+func removeV2TaskMetadata(t *testing.T, repo *git.Repository, v2Store *checkpoint.V2GitStore, cpID id.CheckpointID, sessionIdx int) {
+	t.Helper()
+
+	refName := plumbing.ReferenceName(paths.V2FullCurrentRefName)
+	parentHash, rootTreeHash, err := v2Store.GetRefState(refName)
+	require.NoError(t, err)
+
+	newRootHash, updateErr := checkpoint.UpdateSubtree(
+		repo,
+		rootTreeHash,
+		[]string{string(cpID[:2]), string(cpID[2:]), strconv.Itoa(sessionIdx)},
+		nil,
+		checkpoint.UpdateSubtreeOptions{
+			MergeMode:   checkpoint.MergeKeepExisting,
+			DeleteNames: []string{"tasks"},
+		},
+	)
+	require.NoError(t, updateErr)
+
+	commitHash, commitErr := checkpoint.CreateCommit(repo, newRootHash, parentHash, "test: remove task metadata\n", "Test", "test@test.com")
+	require.NoError(t, commitErr)
+	require.NoError(t, repo.Storer.SetReference(plumbing.NewHashReference(refName, commitHash)))
+}
+
 func TestSpliceTasksTreeToV2_MergesTaskDirectories(t *testing.T) {
 	t.Parallel()