979dbfb fix(recovery): harden durable session invariants · vev

M internal/adapters/noticefile/noticefile.go +2 -7

 	}
 	required := len(line) + len(fragment)
 	if required > cap(line) {
-		capacity := cap(line) * 2
+		capacity := max(cap(line)*2, noticeReadBufferSize)
-		if capacity < noticeReadBufferSize {
+		capacity = min(capacity, maxNoticeRecordSize)
-			capacity = noticeReadBufferSize
-		}
-		if capacity > maxNoticeRecordSize {
-			capacity = maxNoticeRecordSize
-		}
 		grown := make([]byte, len(line), capacity)
 		copy(grown, line)
 		line = grown

M internal/adapters/recoveryfs/journal.go +26 -12

 	if err != nil {
 		return nil, err
 	}
-	entries, readErr := dir.ReadDir(maxDiscardIntents + 1)
+	entries := make([]os.DirEntry, 0, maxDiscardIntents)
-	closeErr := dir.Close()
+	for {
-	if readErr != nil && !errors.Is(readErr, io.EOF) {
+		batch, readErr := dir.ReadDir(maxDiscardIntents + 1)
-		return nil, readErr
+		for _, entry := range batch {
-	}
+			if strings.HasPrefix(entry.Name(), ".intent-") && !entry.IsDir() {
-	if closeErr != nil {
+				continue
-		return nil, closeErr
+			}
+			if entry.IsDir() || !strings.HasPrefix(entry.Name(), "discard-") {
+				_ = dir.Close()
+				return nil, errors.New("recovery journal: invalid transaction entry")
+			}
+			entries = append(entries, entry)
+			if len(entries) > maxDiscardIntents {
+				_ = dir.Close()
+				return nil, errors.New("recovery journal: transaction entry limit exceeded")
+			}
+		}
+		if errors.Is(readErr, io.EOF) {
+			break
+		}
+		if readErr != nil {
+			_ = dir.Close()
+			return nil, readErr
+		}
 	}
-	if len(entries) > maxDiscardIntents {
+	if err := dir.Close(); err != nil {
-		return nil, errors.New("recovery journal: transaction entry limit exceeded")
+		return nil, err
 	}
 	sort.Slice(entries, func(a, b int) bool { return entries[a].Name() < entries[b].Name() })
 	out := make([]domain.DiscardIntent, 0, len(entries))
 		if err := ctx.Err(); err != nil {
 			return nil, err
 		}
-		if entry.IsDir() || !strings.HasPrefix(entry.Name(), "discard-") {
-			return nil, errors.New("recovery journal: invalid transaction entry")
-		}
 		data, err := readFileBounded(filepath.Join(j.dir, entry.Name()), maxDiscardIntentSize)
 		if err != nil {
 			return nil, err

M internal/adapters/recoveryfs/journal_test.go +13 -0


@@ -38,6 +38,7 @@ func TestDiscardCrashMatrix(t *testing.T) {
38	path := j.path(old)	38		path := j.path(old)
39	encoded, err := os.ReadFile(path)	39		encoded, err := os.ReadFile(path)
40	require.NoError(t, err)	40		require.NoError(t, err)
		41	+	t.Cleanup(func() { require.NoError(t, os.WriteFile(path, encoded, 0o600)) })
41	require.NoError(t, os.WriteFile(path, append(encoded, 0), 0o600))	42		require.NoError(t, os.WriteFile(path, append(encoded, 0), 0o600))
42	_, err = j.ListDiscards(ctx)	43		_, err = j.ListDiscards(ctx)
43	require.Error(t, err)	44		require.Error(t, err)

@@ -77,6 +78,18 @@ func TestRecoveryJournalRoundTripAndIdempotentDelete(t *testing.T) {
77	require.Empty(t, got)	78		require.Empty(t, got)
78	}	79		}
79		80
		81	+	func TestRecoveryJournalIgnoresAtomicLeftoversWhenCountingDiscards(t *testing.T) {
		82	+	j := New(t.TempDir())
		83	+	require.NoError(t, os.MkdirAll(j.dir, 0o700))
		84	+	for i := 0; i < maxDiscardIntents+1; i++ {
		85	+	require.NoError(t, os.WriteFile(filepath.Join(j.dir, ".intent-leftover-"+string(rune(0x1000+i))), nil, 0o600))
		86	+	}
		87	+
		88	+	got, err := j.ListDiscards(context.Background())
		89	+	require.NoError(t, err)
		90	+	require.Empty(t, got)
		91	+	}
		92	+
80	func TestRecoveryJournalRejectsMalformedIntent(t *testing.T) {	93		func TestRecoveryJournalRejectsMalformedIntent(t *testing.T) {
81	j := New(t.TempDir())	94		j := New(t.TempDir())
82	require.Error(t, j.SaveDiscard(context.Background(), domain.DiscardIntent{}))	95		require.Error(t, j.SaveDiscard(context.Background(), domain.DiscardIntent{}))

M internal/adapters/snapshot/atomic.go +4 -3

 )
 func (r *Repository) ensureSession(id domain.IncarnationID) error {
+	sessionPath := r.sessionPath(id)
 	for _, directory := range []struct {
 		path  string
 		phase string
 	}{
 		{r.dir, "repository"},
 		{filepath.Join(r.dir, repositorySessionsDir), "sessions"},
-		{r.sessionPath(id), "session"},
+		{sessionPath, "session"},
-		{filepath.Join(r.sessionPath(id), repositoryObjectsDir), "objects"},
+		{filepath.Join(sessionPath, repositoryObjectsDir), "objects"},
-		{filepath.Join(r.sessionPath(id), repositoryGenerations), "generations"},
+		{filepath.Join(sessionPath, repositoryGenerations), "generations"},
 	} {
 		if err := r.ensurePrivateDirectoryPhase(directory.path, directory.phase); err != nil {
 			return fmt.Errorf("create snapshot repository directory: %w", err)

M internal/adapters/snapshot/legacy_load_test.go +0 -4


@@ -69,7 +69,6 @@ func (r *Repository) Load(ctx context.Context, name string) (ports.SnapshotGener
69			69
70		func (r *Repository) load(ctx context.Context, name, key string) (ports.SnapshotGeneration, error) {	70	func (r *Repository) load(ctx context.Context, name, key string) (ports.SnapshotGeneration, error) {
71		preferred, preferredDigest, err := r.readLegacyHead(key)	71	preferred, preferredDigest, err := r.readLegacyHead(key)
72	-	skipped := errors.Is(err, ErrInvalidHEAD)
73		if err != nil && !errors.Is(err, os.ErrNotExist) && !errors.Is(err, ErrInvalidHEAD) {	72	if err != nil && !errors.Is(err, os.ErrNotExist) && !errors.Is(err, ErrInvalidHEAD) {
74		return ports.SnapshotGeneration{}, fmt.Errorf("read snapshot HEAD: %w", err)	73	return ports.SnapshotGeneration{}, fmt.Errorf("read snapshot HEAD: %w", err)
75		}	74	}

@@ -78,7 +77,6 @@ func (r *Repository) load(ctx context.Context, name, key string) (ports.Snapshot
78		if err == nil && sha256.Sum256(got.Manifest) == preferredDigest {	77	if err == nil && sha256.Sum256(got.Manifest) == preferredDigest {
79		return got, nil	78	return got, nil
80		}	79	}
81	-	skipped = true
82		}	80	}
83			81
84		budget := maxDirectoryTraversalEntries	82	budget := maxDirectoryTraversalEntries

@@ -89,10 +87,8 @@ func (r *Repository) load(ctx context.Context, name, key string) (ports.Snapshot
89		for _, generation := range candidates {	87	for _, generation := range candidates {
90		got, err := r.loadGeneration(ctx, name, key, generation)	88	got, err := r.loadGeneration(ctx, name, key, generation)
91		if err != nil {	89	if err != nil {
92	-	skipped = true
93		continue	90	continue
94		}	91	}
95	-	_ = skipped
96		return got, nil	92	return got, nil
97		}	93	}
98		return ports.SnapshotGeneration{}, fmt.Errorf("no complete snapshot generation for %q", name)	94	return ports.SnapshotGeneration{}, fmt.Errorf("no complete snapshot generation for %q", name)

M internal/adapters/snapshot/load_bounds_test.go +10 -7

 	if err := os.MkdirAll(sessions, 0o700); err != nil {
 		t.Fatal(err)
 	}
-	for i := 0; i < maxDirectoryTraversalEntries+1; i++ {
+	for i := range maxDirectoryTraversalEntries + 1 {
 		if err := os.Mkdir(filepath.Join(sessions, fmt.Sprintf("hostile-%05d", i)), 0o700); err != nil {
 			t.Fatal(err)
 		}
 	if err := os.MkdirAll(generations, 0o700); err != nil {
 		t.Fatal(err)
 	}
-	for generation := uint64(1); generation <= uint64(maxDirectoryTraversalEntries+1); generation++ {
+	for i := range maxDirectoryTraversalEntries + 1 {
+		generation := uint64(i + 1)
 		if err := os.WriteFile(filepath.Join(generations, generationFilename(generation)), nil, 0o600); err != nil {
 			t.Fatal(err)
 		}
 func TestRepositoryLoadFallsBackNewestToOldestWithoutGenerationEnumeration(t *testing.T) {
 	repo := NewRepository(privateDir(t))
-	for generation := uint64(1); generation <= 3; generation++ {
+	for i := range 3 {
-		if err := repo.Publish(context.Background(), repositoryPublicationAfter(t, repo, "named", generation, []byte(fmt.Sprintf("state-%d", generation)))); err != nil {
+		generation := uint64(i + 1)
+		if err := repo.Publish(context.Background(), repositoryPublicationAfter(t, repo, "named", generation, fmt.Appendf(nil, "state-%d", generation))); err != nil {
 			t.Fatal(err)
 		}
 	}
 func TestRepositoryMaintainDoesNotCollectBeyondRetainedMetadataBudget(t *testing.T) {
 	repo := NewRepository(privateDir(t))
-	for generation := uint64(1); generation <= uint64(maxMaintenanceMarkedGenerations+1); generation++ {
+	for i := range maxMaintenanceMarkedGenerations + 1 {
-		if err := repo.Publish(context.Background(), repositoryPublicationAfter(t, repo, "named", generation, []byte(fmt.Sprintf("state-%d", generation)))); err != nil {
+		generation := uint64(i + 1)
+		if err := repo.Publish(context.Background(), repositoryPublicationAfter(t, repo, "named", generation, fmt.Appendf(nil, "state-%d", generation))); err != nil {
 			t.Fatal(err)
 		}
 	}
-	for pass := 0; pass < maxMaintenanceMarkedGenerations*3; pass++ {
+	for pass := range maxMaintenanceMarkedGenerations * 3 {
 		if err := repo.Maintain(context.Background()); err != nil {
 			t.Fatal(err)
 		}

M internal/adapters/snapshot/maintenance_delete.go +1 -22


@@ -644,28 +644,7 @@ func (r *Repository) SaveQuarantineDescriptor(ctx context.Context, descriptor do
644			644
645		func quarantineDescriptorsEqual(a, b domain.QuarantineDescriptor) bool {	645		func quarantineDescriptorsEqual(a, b domain.QuarantineDescriptor) bool {
646		return a.OldIncarnation == b.OldIncarnation && a.ReplacementIncarnation == b.ReplacementIncarnation &&	646		return a.OldIncarnation == b.OldIncarnation && a.ReplacementIncarnation == b.ReplacementIncarnation &&
647	-	a.SessionName == b.SessionName && a.Reason == b.Reason && catalogueRecordsEqual(a.OldRecord, b.OldRecord)	647	+	a.SessionName == b.SessionName && a.Reason == b.Reason && a.OldRecord.Equal(b.OldRecord)
648	-	}
649	-
650	-	func catalogueRecordsEqual(a, b domain.CatalogueRecord) bool {
651	-	if a.Name != b.Name \|\| a.IncarnationID != b.IncarnationID \|\| a.Cwd != b.Cwd \|\| a.CreatedAt != b.CreatedAt \|\|
652	-	a.UpdatedAt != b.UpdatedAt \|\| a.LastUsedSeq != b.LastUsedSeq \|\| a.RecoveryState != b.RecoveryState \|\|
653	-	a.DegradedReason != b.DegradedReason \|\| len(a.TabNames) != len(b.TabNames) {
654	-	return false
655	-	}
656	-	for i := range a.TabNames {
657	-	if a.TabNames[i] != b.TabNames[i] {
658	-	return false
659	-	}
660	-	}
661	-	return checkpointRefsEqual(a.Committed, b.Committed) && checkpointRefsEqual(a.Fallbacks[0], b.Fallbacks[0]) && checkpointRefsEqual(a.Fallbacks[1], b.Fallbacks[1])
662	-	}
663	-
664	-	func checkpointRefsEqual(a, b *domain.CheckpointRef) bool {
665	-	if a == nil \|\| b == nil {
666	-	return a == nil && b == nil
667	-	}
668	-	return a == b
669		}	648		}
670			649
671		func (r *Repository) QuarantineIncarnation(ctx context.Context, id domain.IncarnationID) error {	650		func (r *Repository) QuarantineIncarnation(ctx context.Context, id domain.IncarnationID) error {

M internal/adapters/snapshot/maintenance_gc.go +88 -61

 	complete bool
 }
+type retentionEntryKind uint8
+const (
+	retentionManifest retentionEntryKind = iota + 1
+	retentionObject
+)
+type retentionEntryPolicy struct {
+	kind        retentionEntryKind
+	generations map[uint64]ports.SnapshotDigest
+	objects     map[ports.SnapshotDigest]struct{}
+}
+func (p retentionEntryPolicy) delete(entry maintenanceDirEntry) bool {
+	if entry.isDir {
+		return false
+	}
+	switch p.kind {
+	case retentionManifest:
+		generation, canonical := parseGenerationFilename(entry.name)
+		_, retained := p.generations[generation]
+		return canonical && !retained
+	case retentionObject:
+		digest, canonical := parseObjectDigest(entry.name)
+		_, retained := p.objects[digest]
+		return canonical && !retained
+	default:
+		return false
+	}
+}
 type sessionMaintenance struct {
 	lock            *sessionMutex
 	token           string
 // MaintainSession incrementally validates and retains only catalogue-indexed
 // checkpoints. Every incarnation owns its budget and continuation state.
+// processRetentionEntries charges stat-reported size for every entry, requeues
+// the unadmitted suffix, and removes only canonical entries rejected by policy.
+func (r *Repository) processRetentionEntries(ctx context.Context, dir, purpose string, entries []maintenanceDirEntry, budget *ports.MaintenanceBudget, consumedBefore bool, policy retentionEntryPolicy) (bool, error) {
+	for i, entry := range entries {
+		if err := ctx.Err(); err != nil {
+			return false, err
+		}
+		path := filepath.Join(dir, entry.name)
+		info, statErr := r.stat(path)
+		if statErr != nil && !errors.Is(statErr, os.ErrNotExist) {
+			return false, statErr
+		}
+		size := uint64(0)
+		if statErr == nil && info.Size() > 0 {
+			size = uint64(info.Size())
+		}
+		if budget.Entries == 0 || size > budget.Bytes {
+			r.requeueMaintenanceEntries(dir, purpose, entries[i:])
+			if !consumedBefore && i == 0 {
+				return false, ErrMaintenanceBudgetTooSmall
+			}
+			return false, nil
+		}
+		budget.Entries--
+		budget.Bytes -= size
+		if !policy.delete(entry) {
+			continue
+		}
+		if err := r.remove(path); err != nil && !errors.Is(err, os.ErrNotExist) {
+			return false, err
+		}
+		if err := r.syncDirectory(dir); err != nil {
+			return false, err
+		}
+	}
+	return true, nil
+}
 func (r *Repository) MaintainSession(ctx context.Context, plan ports.RetentionPlan, budget ports.MaintenanceBudget) (done bool, err error) {
 	requested := budget
 	if err := ctx.Err(); err != nil {
 		if err != nil {
 			return false, err
 		}
-		for i, entry := range entries {
+		dir := filepath.Join(r.sessionPath(plan.IncarnationID), repositoryGenerations)
-			path := r.manifestPath(plan.IncarnationID, 0)
+		consumedBefore := requested.Entries != budget.Entries || requested.Bytes != budget.Bytes
-			path = filepath.Join(filepath.Dir(path), entry.name)
+		admitted, err := r.processRetentionEntries(ctx, dir, purpose, entries, &budget, consumedBefore, retentionEntryPolicy{kind: retentionManifest, generations: keep})
-			info, statErr := r.stat(path)
+		if err != nil {
-			if statErr != nil && !errors.Is(statErr, os.ErrNotExist) {
+			return false, err
-				return false, statErr
+		}
-			}
+		if !admitted {
-			size := uint64(0)
+			return false, nil
-			if statErr == nil && info.Size() > 0 {
-				size = uint64(info.Size())
-			}
-			if budget.Entries == 0 || size > budget.Bytes {
-				r.requeueMaintenanceEntries(filepath.Dir(path), purpose, entries[i:])
-				return false, nil
-			}
-			budget.Entries--
-			budget.Bytes -= size
-			generation, canonical := parseGenerationFilename(entry.name)
-			if !entry.isDir && canonical {
-				if _, retained := keep[generation]; !retained {
-					if err := r.remove(path); err != nil && !errors.Is(err, os.ErrNotExist) {
-						return false, err
-					}
-					if err := r.syncDirectory(filepath.Dir(path)); err != nil {
-						return false, err
-					}
-				}
-			}
 		}
 		state.manifestsDone = done
 		if len(entries) == 0 && !done {
 			if err != nil {
 				return false, err
 			}
-			for i, entry := range entries {
+			consumedBefore := requested.Entries != budget.Entries || requested.Bytes != budget.Bytes
-				path := filepath.Join(dir, entry.name)
+			admitted, err := r.processRetentionEntries(ctx, dir, objectPurpose, entries, &budget, consumedBefore, retentionEntryPolicy{kind: retentionObject, objects: state.references})
-				info, statErr := r.stat(path)
+			if err != nil {
-				if statErr != nil && !errors.Is(statErr, os.ErrNotExist) {
+				return false, err
-					return false, statErr
+			}
-				}
+			if !admitted {
-				size := uint64(0)
+				return false, nil
-				if statErr == nil && info.Size() > 0 {
-					size = uint64(info.Size())
-				}
-				if budget.Entries == 0 || size > budget.Bytes {
-					r.requeueMaintenanceEntries(dir, objectPurpose, entries[i:])
-					return false, nil
-				}
-				budget.Entries--
-				budget.Bytes -= size
-				digest, canonical := parseObjectDigest(entry.name)
-				if !entry.isDir && canonical {
-					if _, retained := state.references[digest]; !retained {
-						if err := r.remove(path); err != nil && !errors.Is(err, os.ErrNotExist) {
-							return false, err
-						}
-						if err := r.syncDirectory(dir); err != nil {
-							return false, err
-						}
-					}
-				}
 			}
 			if done {
 				state.objectShard = ""
 	return b.String()
 }
-// validateMaintenanceCheckpoint admits every payload by stat-reported size
-// before reading it. It validates directly instead of calling LoadCheckpoint,
-// which would materialize a complete generation before maintenance could
-// enforce its byte budget.
 type validatedMaintenanceCheckpoint struct {
 	refs   map[ports.SnapshotDigest]codec.ObjectRef
 	parent *domain.CheckpointRef
 }
+// validateMaintenanceCheckpoint admits every payload by stat-reported size
+// before reading it. It validates directly instead of calling LoadCheckpoint,
+// which would materialize a complete generation before maintenance could
+// enforce its byte budget.
 func (r *Repository) validateMaintenanceCheckpoint(ctx context.Context, id domain.IncarnationID, ref ports.CheckpointRef, byteBudget uint64) (validatedMaintenanceCheckpoint, uint64, bool, error) {
 	manifestPath := r.manifestPath(id, ref.Generation)
 	info, err := r.stat(manifestPath)
 		byIncarnation[record.IncarnationID] = record
 	}
-	r.maintenanceMu.Lock()
-	defer r.maintenanceMu.Unlock()
 	root := filepath.Join(r.dir, repositorySessionsDir)
 	state := &maintenanceCursor{offset: offset}
 	findingCapacity := maintenanceBatch

M internal/adapters/snapshot/maintenance_test.go +88 -16

@@ -1,6 +1,7 @@
1		package snapshot	1		package snapshot
2			2
3		import (	3		import (
			4	+	"cmp"
4		"context"	5		"context"
5		"crypto/sha256"	6		"crypto/sha256"
6		"encoding/binary"	7		"encoding/binary"

@@ -11,8 +12,10 @@ import (
11		"path/filepath"	12		"path/filepath"
12		"slices"	13		"slices"
13		"strings"	14		"strings"
			15	+	"sync"
14		"syscall"	16		"syscall"
15		"testing"	17		"testing"
			18	+	"time"
16		"unsafe"	19		"unsafe"
17			20
18		"github.com/bnema/vev/internal/domain"	21		"github.com/bnema/vev/internal/domain"

@@ -1043,21 +1046,17 @@ func TestRetentionSlots(t *testing.T) {
1043		}	1046		}
1044			1047
1045		func TestUnresolvedDataPinned(t *testing.T) {	1048		func TestUnresolvedDataPinned(t *testing.T) {
1046	-	for _, state := range []string{"degraded", "deleting", "migration", "transaction"} {	1049	+	repo := NewRepository(privateDir(t))
1047	-	t.Run(state, func(t *testing.T) {	1050	+	publications := publishMaintenanceGenerations(t, repo, "unresolved", 4)
1048	-	repo := NewRepository(privateDir(t))	1051	+	done, err := repo.MaintainSession(context.Background(), ports.RetentionPlan{IncarnationID: publications[0].IncarnationID, PinAll: true}, ports.MaintenanceBudget{Entries: 1, Bytes: 1})
1049	-	publications := publishMaintenanceGenerations(t, repo, state, 4)	1052	+	if err != nil {
1050	-	done, err := repo.MaintainSession(context.Background(), ports.RetentionPlan{IncarnationID: publications[0].IncarnationID, PinAll: true}, ports.MaintenanceBudget{Entries: 1, Bytes: 1})	1053	+	t.Fatal(err)
1051	-	if err != nil {	1054	+	}
1052	-	t.Fatal(err)	1055	+	if !done {
1053	-	}	1056	+	t.Fatal("pinned maintenance did not complete without traversing")
1054	-	if !done {	1057	+	}
1055	-	t.Fatal("pinned maintenance did not complete without traversing")	1058	+	if got := remainingMaintenanceGenerations(t, repo, publications[0].IncarnationID); !slices.Equal(got, []uint64{4, 3, 2, 1}) {
1056	-	}	1059	+	t.Fatalf("pinned generations = %v", got)
1057	-	if got := remainingMaintenanceGenerations(t, repo, publications[0].IncarnationID); !slices.Equal(got, []uint64{4, 3, 2, 1}) {
1058	-	t.Fatalf("pinned generations = %v", got)
1059	-	}
1060	-	})
1061		}	1060		}
1062		}	1061		}
1063			1062

@@ -1094,6 +1093,79 @@ func TestMaintenanceBudgetAdmitsPayloadsBeforeRead(t *testing.T) {
1094		}	1093		}
1095		}	1094		}
1096			1095
			1096	+	func TestMaintainSessionDistinguishesInitialOversizeFromResumableExhaustion(t *testing.T) {
			1097	+	repo := NewRepository(privateDir(t))
			1098	+	publications := publishMaintenanceGenerations(t, repo, "budget-semantics", 2)
			1099	+	plan := ports.RetentionPlan{IncarnationID: publications[0].IncarnationID}
			1100	+	firstInfo, err := os.Stat(repo.manifestPath(plan.IncarnationID, 1))
			1101	+	if err != nil {
			1102	+	t.Fatal(err)
			1103	+	}
			1104	+	secondInfo, err := os.Stat(repo.manifestPath(plan.IncarnationID, 2))
			1105	+	if err != nil {
			1106	+	t.Fatal(err)
			1107	+	}
			1108	+	firstSize, secondSize := uint64(firstInfo.Size()), uint64(secondInfo.Size())
			1109	+
			1110	+	done, err := repo.MaintainSession(context.Background(), plan, ports.MaintenanceBudget{Entries: 2, Bytes: min(firstSize, secondSize) - 1})
			1111	+	if done \|\| !errors.Is(err, ErrMaintenanceBudgetTooSmall) {
			1112	+	t.Fatalf("initial oversized item: done=%v err=%v", done, err)
			1113	+	}
			1114	+
			1115	+	done, err = repo.MaintainSession(context.Background(), plan, ports.MaintenanceBudget{Entries: 2, Bytes: firstSize + secondSize - 1})
			1116	+	if err != nil \|\| done {
			1117	+	t.Fatalf("mid-pass exhaustion must be resumable: done=%v err=%v", done, err)
			1118	+	}
			1119	+	done, err = repo.MaintainSession(context.Background(), plan, ports.MaintenanceBudget{Entries: 64, Bytes: 8 << 20})
			1120	+	if err != nil \|\| !done {
			1121	+	t.Fatalf("resumed maintenance: done=%v err=%v", done, err)
			1122	+	}
			1123	+	}
			1124	+
			1125	+	func TestReconcileDoesNotHoldMaintenanceLockDuringPayloadRead(t *testing.T) {
			1126	+	repo := NewRepository(privateDir(t))
			1127	+	publications := publishMaintenanceGenerations(t, repo, "reconcile-lock", 2)
			1128	+	committed := checkpointRefForPublication(publications[0])
			1129	+	record := domain.CatalogueRecord{Name: "reconcile-lock", IncarnationID: publications[0].IncarnationID, RecoveryState: domain.RecoveryHealthy, Committed: &committed}
			1130	+
			1131	+	entered := make(chan struct{})
			1132	+	release := make(chan struct{})
			1133	+	var releaseOnce sync.Once
			1134	+	defer releaseOnce.Do(func() { close(release) })
			1135	+	repo.hooks.beforeMaintenancePayloadRead = func(string) {
			1136	+	select {
			1137	+	case <-entered:
			1138	+	default:
			1139	+	close(entered)
			1140	+	}
			1141	+	<-release
			1142	+	}
			1143	+	reconcileDone := make(chan error, 1)
			1144	+	go func() {
			1145	+	_, _, err := repo.Reconcile(context.Background(), []domain.CatalogueRecord{record}, ports.ReconcileCursor{}, ports.MaintenanceBudget{Entries: 64, Bytes: 8 << 20})
			1146	+	reconcileDone <- err
			1147	+	}()
			1148	+	<-entered
			1149	+
			1150	+	pinDone := make(chan error, 1)
			1151	+	go func() {
			1152	+	_, err := repo.MaintainSession(context.Background(), ports.RetentionPlan{IncarnationID: record.IncarnationID, PinAll: true}, ports.MaintenanceBudget{Entries: 1, Bytes: 1})
			1153	+	pinDone <- err
			1154	+	}()
			1155	+	select {
			1156	+	case err := <-pinDone:
			1157	+	if err != nil {
			1158	+	t.Fatal(err)
			1159	+	}
			1160	+	case <-time.After(time.Second):
			1161	+	t.Fatal("maintenance lock remained held during reconciliation payload I/O")
			1162	+	}
			1163	+	releaseOnce.Do(func() { close(release) })
			1164	+	if err := <-reconcileDone; err != nil {
			1165	+	t.Fatal(err)
			1166	+	}
			1167	+	}
			1168	+
1097		func TestPerSessionBudgetIsolation(t *testing.T) {	1169		func TestPerSessionBudgetIsolation(t *testing.T) {
1098		repo := NewRepository(privateDir(t))	1170		repo := NewRepository(privateDir(t))
1099		large := publishMaintenanceGenerations(t, repo, "large", 4)	1171		large := publishMaintenanceGenerations(t, repo, "large", 4)

@@ -1149,6 +1221,6 @@ func remainingMaintenanceGenerations(t testing.T, repo Repository, id domain.I
1149		generations = append(generations, generation)	1221		generations = append(generations, generation)
1150		}	1222		}
1151		}	1223		}
1152	-	slices.SortFunc(generations, func(a, b uint64) int { return int(b) - int(a) })	1224	+	slices.SortFunc(generations, func(a, b uint64) int { return cmp.Compare(b, a) })
1153		return generations	1225		return generations
1154		}	1226		}

M internal/adapters/snapshot/migration_v0.go +6 -3

 	objects := make([]legacyObjectV1, 0)
 	add := func(ref codec.ObjectRef) error {
 		if _, ok := seen[ref.Digest]; ok {
-			return errors.New("snapshot: duplicate legacy object digest")
+			return nil
 		}
 		seen[ref.Digest] = struct{}{}
 		objects = append(objects, legacyObjectV1{Kind: uint8(ref.Kind), Digest: ref.Digest, Size: uint64(ref.Size)})
 	if cause == nil {
 		return fmt.Errorf("%w: %s", ports.ErrLegacySnapshotUncertain, operation)
 	}
-	return fmt.Errorf("%w: %s: %v", ports.ErrLegacySnapshotUncertain, operation, cause)
+	return fmt.Errorf("%w: %s: %w", ports.ErrLegacySnapshotUncertain, operation, cause)
 }
 // MigrateV1Checkpoint is the migration-only admission path for an authoritative
 	if manifest.Name != req.LegacyName || manifest.Generation != req.LegacyRef.Generation {
 		return domain.CheckpointRef{}, uncertainLegacyError("manifest identity mismatch", nil)
 	}
-	key, _ := incarnationKey(req.IncarnationID)
+	key, err := incarnationKey(req.IncarnationID)
+	if err != nil {
+		return domain.CheckpointRef{}, err
+	}
 	lock := r.lockSession(key)
 	defer r.unlockSession(lock)
 	if err := r.ensureSession(req.IncarnationID); err != nil {

M internal/adapters/snapshot/migration_v0_test.go +39 -3


@@ -4,6 +4,7 @@ import (
4		"context"	4		"context"
5		"crypto/sha256"	5		"crypto/sha256"
6		"encoding/binary"	6		"encoding/binary"
			7	+	"errors"
7		"fmt"	8		"fmt"
8		"hash/crc32"	9		"hash/crc32"
9		"os"	10		"os"

@@ -37,10 +38,45 @@ func TestLegacyManifestV1(t *testing.T) {
37		require.NoError(t, err)	38		require.NoError(t, err)
38		require.Equal(t, "work", got.Name)	39		require.Equal(t, "work", got.Name)
39		require.Equal(t, uint64(7), got.Generation)	40		require.Equal(t, uint64(7), got.Generation)
40	-	for _, invalid := range [][]byte{encoded[:5], append(append([]byte(nil), encoded...), 0)} {	41	+	for size := range len(encoded) {
41	-	_, err := decodeManifestV1(invalid)	42	+	_, err := decodeManifestV1(encoded[:size])
42	-	require.Error(t, err)	43	+	require.Errorf(t, err, "prefix length %d", size)
43		}	44		}
			45	+	_, err = decodeManifestV1(append(append([]byte(nil), encoded...), 0))
			46	+	require.Error(t, err)
			47	+	}
			48	+
			49	+	func TestLegacyManifestV1DeduplicatesObjectsPreservingFirst(t *testing.T) {
			50	+	chunk, err := codec.MarshalObject(codec.HistoryChunk, []byte("chunk"))
			51	+	require.NoError(t, err)
			52	+	tail, err := codec.MarshalObject(codec.HistoryTail, []byte("tail"))
			53	+	require.NoError(t, err)
			54	+	visible, err := codec.MarshalObject(codec.Visible, []byte("visible"))
			55	+	require.NoError(t, err)
			56	+	chunkRef := codec.ObjectRef{Kind: codec.HistoryChunk, Digest: chunk.Digest, Size: uint32(len(chunk.Data))}
			57	+	manifest := codec.Manifest{Generation: 1, IncarnationID: domain.IncarnationID{1}, Name: "work", Tabs: []codec.ManifestTab{{Cols: 1, Rows: 1, Panes: []codec.ManifestPane{{ID: "p", Sealed: []codec.ObjectRef{chunkRef, chunkRef}, Tail: codec.ObjectRef{Kind: codec.HistoryTail, Digest: tail.Digest, Size: uint32(len(tail.Data))}, Visible: codec.ObjectRef{Kind: codec.Visible, Digest: visible.Digest, Size: uint32(len(visible.Data))}}}}}}
			58	+	modern, err := codec.MarshalManifest(manifest)
			59	+	require.NoError(t, err)
			60	+	body := append([]byte(nil), modern[legacyManifestHeaderSize:]...)
			61	+	body = append(body[:8], body[25:]...)
			62	+	legacy := make([]byte, legacyManifestHeaderSize, legacyManifestHeaderSize+len(body))
			63	+	copy(legacy, "VEVM")
			64	+	binary.BigEndian.PutUint16(legacy[4:6], 1)
			65	+	binary.BigEndian.PutUint32(legacy[8:12], uint32(len(body)))
			66	+	binary.BigEndian.PutUint32(legacy[12:16], crc32.ChecksumIEEE(body))
			67	+	legacy = append(legacy, body...)
			68	+
			69	+	decoded, err := decodeManifestV1(legacy)
			70	+	require.NoError(t, err)
			71	+	require.Len(t, decoded.Objects, 3)
			72	+	require.Equal(t, chunk.Digest, decoded.Objects[0].Digest)
			73	+	}
			74	+
			75	+	func TestUncertainLegacyErrorWrapsSentinelAndCause(t *testing.T) {
			76	+	cause := errors.New("legacy cause")
			77	+	err := uncertainLegacyError("read", cause)
			78	+	require.ErrorIs(t, err, ports.ErrLegacySnapshotUncertain)
			79	+	require.ErrorIs(t, err, cause)
44		}	80		}
45			81
46		func TestHasLegacyState(t *testing.T) {	82		func TestHasLegacyState(t *testing.T) {

M internal/adapters/snapshot/publish_efficiency_test.go +7 -8

 	}
 	second := repositoryPublicationAfter(t, repo, "named", 2, []byte("second"))
 	newTail := second.Objects[0]
-	key := legacyIncarnationID(second.Name).String()
+	path := repo.objectPath(second.IncarnationID, newTail.Digest)
-	if err := os.MkdirAll(filepath.Dir(repo.legacyObjectPath(key, newTail.Digest)), 0o700); err != nil {
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(repo.legacyObjectPath(key, newTail.Digest), newTail.Data, 0o600); err != nil {
+	if err := os.WriteFile(path, newTail.Data, 0o600); err != nil {
 		t.Fatal(err)
 	}
 func seedCompletePublication(t testing.TB, repo *Repository, publication ports.SnapshotPublication) {
 	t.Helper()
-	key := legacyIncarnationID(publication.Name).String()
 	if err := repo.ensureSession(publication.IncarnationID); err != nil {
 		t.Fatal(err)
 	}
 		t.Fatal(err)
 	}
 	for _, object := range publication.Objects {
-		if err := os.MkdirAll(filepath.Dir(repo.legacyObjectPath(key, object.Digest)), 0o700); err != nil {
+		if err := os.MkdirAll(filepath.Dir(repo.objectPath(publication.IncarnationID, object.Digest)), 0o700); err != nil {
 			t.Fatal(err)
 		}
-		if err := os.WriteFile(repo.legacyObjectPath(key, object.Digest), object.Data, 0o600); err != nil {
+		if err := os.WriteFile(repo.objectPath(publication.IncarnationID, object.Digest), object.Data, 0o600); err != nil {
 			t.Fatal(err)
 		}
 	}
-	if err := os.WriteFile(repo.legacyManifestPath(key, publication.Generation), publication.Manifest, 0o600); err != nil {
+	if err := os.WriteFile(repo.manifestPath(publication.IncarnationID, publication.Generation), publication.Manifest, 0o600); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(repo.legacyHeadPath(key), marshalHead(publication.Generation, sha256.Sum256(publication.Manifest)), 0o600); err != nil {
+	if err := os.WriteFile(repo.headPath(publication.IncarnationID), marshalHead(publication.Generation, sha256.Sum256(publication.Manifest)), 0o600); err != nil {
 		t.Fatal(err)
 	}
 	if refs := manifestRefs(manifest); refs == nil {

M internal/adapters/snapshot/reconciliation_test.go +2 -2

 import (
 	"context"
-	"os"
 	"path/filepath"
 	"testing"
 	"github.com/bnema/vev/internal/domain"
 	"github.com/bnema/vev/internal/ports"
 	codec "github.com/bnema/vev/internal/usecase/snapshot"
+	"github.com/bnema/vev/pkg/safedir"
 	"github.com/stretchr/testify/require"
 )
 	sessions := filepath.Join(repo.dir, repositorySessionsDir)
 	for i := byte(20); i < 26; i++ {
 		id := domain.IncarnationID{i}
-		require.NoError(t, os.Mkdir(filepath.Join(sessions, id.String()), 0o700))
+		require.NoError(t, safedir.EnsurePrivate(filepath.Join(sessions, id.String())))
 	}
 	cursor := ports.ReconcileCursor{}

M internal/adapters/snapshot/recovery_crash_test.go +16 -7

 	"github.com/bnema/vev/internal/persist"
 	"github.com/bnema/vev/internal/ports"
 	"github.com/bnema/vev/internal/usecase/recovery"
+	"github.com/bnema/vev/pkg/safedir"
 	"github.com/stretchr/testify/require"
 )
 			record := domain.CatalogueRecord{Name: "work", IncarnationID: oldID, RecoveryState: domain.RecoveryFresh}
 			require.NoError(t, catalogue.Create(record))
 			sessionPath := repository.sessionPath(oldID)
-			require.NoError(t, os.MkdirAll(sessionPath, 0o700))
+			require.NoError(t, safedir.EnsurePrivate(sessionPath))
 			require.NoError(t, os.WriteFile(filepath.Join(sessionPath, "durable"), []byte("old namespace"), 0o600))
 			require.NoError(t, os.WriteFile(filepath.Join(h.snapshotDir, filenameForName(record.Name)), []byte("old legacy"), 0o600))
 			tc.inject(repository)
 			// Simulate a new process: none of the adapter or coordinator state survives.
 			catalogue, repository, journal = h.open(t)
 			require.NoError(t, recovery.NewCoordinator(catalogue, repository, journal, nil).Recover(ctx))
-			_, exists := catalogue.Record(record.Name)
+			_, exists, err := catalogue.Record(record.Name)
+			require.NoError(t, err)
 			require.False(t, exists)
 			require.NoDirExists(t, repository.sessionPath(oldID))
 			require.Equal(t, []byte("old namespace"), mustReadCrashFile(t, filepath.Join(h.snapshotDir, "quarantine", oldID.String(), "snapshot", "durable")))
 			require.NoError(t, err)
 			require.Equal(t, newID, created.IncarnationID)
 			newPath := repository.sessionPath(newID)
-			require.NoError(t, os.MkdirAll(newPath, 0o700))
+			require.NoError(t, safedir.EnsurePrivate(newPath))
 			require.NoError(t, os.WriteFile(filepath.Join(newPath, "durable"), []byte("new namespace"), 0o600))
 			require.NoError(t, catalogue.Close())
 			catalogue, repository, journal = h.open(t)
 			require.NoError(t, recovery.NewCoordinator(catalogue, repository, journal, nil).Recover(ctx))
-			got, exists := catalogue.Record(record.Name)
+			got, exists, err := catalogue.Record(record.Name)
+			require.NoError(t, err)
 			require.True(t, exists)
 			require.Equal(t, newID, got.IncarnationID)
 			require.Equal(t, []byte("new namespace"), mustReadCrashFile(t, filepath.Join(repository.sessionPath(newID), "durable")))
 	interruptedID := domain.IncarnationID{3}
 	_, err := recovery.NewCoordinator(rejectCreateCatalogue{Catalogue: catalogue}, repository, journal, bytes.NewReader(interruptedID[:])).Create(ctx, domain.CatalogueRecord{Name: "work"})
 	require.ErrorIs(t, err, errDeletionBoundaryCrash)
-	require.Empty(t, catalogue.Records())
+	records, err := catalogue.Records()
+	require.NoError(t, err)
+	require.Empty(t, records)
 	require.NoDirExists(t, filepath.Join(h.snapshotDir, repositorySessionsDir))
 	require.NoError(t, catalogue.Close())
 	catalogue, repository, journal = h.open(t)
 	require.NoError(t, recovery.NewCoordinator(catalogue, repository, journal, nil).Recover(ctx))
-	require.Empty(t, catalogue.Records())
+	records, err = catalogue.Records()
+	require.NoError(t, err)
+	require.Empty(t, records)
 	require.NoDirExists(t, repository.sessionPath(interruptedID))
 	retryID := domain.IncarnationID{4}
 	created, err := recovery.NewCoordinator(catalogue, repository, journal, bytes.NewReader(retryID[:])).Create(ctx, domain.CatalogueRecord{Name: "work"})
 	require.NoError(t, err)
 	require.Equal(t, retryID, created.IncarnationID)
-	require.Len(t, catalogue.Records(), 1)
+	records, err = catalogue.Records()
+	require.NoError(t, err)
+	require.Len(t, records, 1)
 	require.NoDirExists(t, repository.sessionPath(interruptedID))
 	require.NoError(t, catalogue.Close())
 }

M internal/adapters/snapshot/recovery_observability_test.go +58 -20


@@ -14,25 +14,63 @@ import (
14		)	14		)
15			15
16		func TestGCBudgetDiagnostic(t *testing.T) {	16		func TestGCBudgetDiagnostic(t *testing.T) {
17	-	var buffer bytes.Buffer	17	+	for _, tc := range []struct {
18	-	log := slog.New(slog.NewJSONHandler(&buffer, nil))	18	+	name string
19	-	repository := NewRepository(t.TempDir(), log)	19	+	arrange func(testing.T, Repository) ports.RetentionPlan
20	-	id := domain.IncarnationID{1}	20	+	budget ports.MaintenanceBudget
21	-	done, err := repository.MaintainSession(context.Background(), ports.RetentionPlan{	21	+	wantDone bool
22	-	IncarnationID: id,	22	+	wantExhausted bool
23	-	Keep: []ports.CheckpointRef{{Generation: 3}, {Generation: 2}, {Generation: 1}},	23	+	wantConsumption bool
24	-	}, ports.MaintenanceBudget{})	24	+	}{
25	-	require.NoError(t, err)	25	+	{
26	-	require.False(t, done)	26	+	name: "exhausted",
			27	+	arrange: func(_ testing.T, _ Repository) ports.RetentionPlan {
			28	+	return ports.RetentionPlan{IncarnationID: domain.IncarnationID{1}, Keep: []ports.CheckpointRef{{Generation: 3}, {Generation: 2}, {Generation: 1}}}
			29	+	},
			30	+	wantExhausted: true,
			31	+	},
			32	+	{
			33	+	name: "sufficient",
			34	+	arrange: func(t testing.T, repository Repository) ports.RetentionPlan {
			35	+	publication := publishMaintenanceGenerations(t, repository, "diagnostic", 1)[0]
			36	+	return ports.RetentionPlan{IncarnationID: publication.IncarnationID}
			37	+	},
			38	+	budget: ports.MaintenanceBudget{Entries: 64, Bytes: 8 << 20},
			39	+	wantDone: true,
			40	+	wantConsumption: true,
			41	+	},
			42	+	} {
			43	+	t.Run(tc.name, func(t *testing.T) {
			44	+	var buffer bytes.Buffer
			45	+	log := slog.New(slog.NewJSONHandler(&buffer, nil))
			46	+	repository := NewRepository(privateDir(t), log)
			47	+	plan := tc.arrange(t, repository)
			48	+	buffer.Reset()
27			49
28	-	scanner := bufio.NewScanner(bytes.NewReader(buffer.Bytes()))	50	+	done, err := repository.MaintainSession(context.Background(), plan, tc.budget)
29	-	require.True(t, scanner.Scan())	51	+	require.NoError(t, err)
30	-	var entry map[string]any	52	+	require.Equal(t, tc.wantDone, done)
31	-	require.NoError(t, json.Unmarshal(scanner.Bytes(), &entry))	53	+
32	-	require.NoError(t, scanner.Err())	54	+	scanner := bufio.NewScanner(bytes.NewReader(buffer.Bytes()))
33	-	require.Equal(t, "snapshot_maintenance_progress", entry["msg"])	55	+	require.True(t, scanner.Scan())
34	-	require.Equal(t, id.String(), entry["incarnation"])	56	+	var entry map[string]any
35	-	require.EqualValues(t, 3, entry["retained"])	57	+	require.NoError(t, json.Unmarshal(scanner.Bytes(), &entry))
36	-	require.Contains(t, entry, "cursor")	58	+	require.NoError(t, scanner.Err())
37	-	require.Equal(t, true, entry["budget_exhausted"])	59	+	require.Equal(t, "snapshot_maintenance_progress", entry["msg"])
			60	+	require.Equal(t, plan.IncarnationID.String(), entry["incarnation"])
			61	+	require.Contains(t, entry, "cursor")
			62	+	require.Equal(t, tc.wantExhausted, entry["budget_exhausted"])
			63	+	consumedEntries, entriesOK := entry["consumed_entries"].(float64)
			64	+	consumedBytes, bytesOK := entry["consumed_bytes"].(float64)
			65	+	require.True(t, entriesOK)
			66	+	require.True(t, bytesOK)
			67	+	if tc.wantConsumption {
			68	+	require.Positive(t, consumedEntries)
			69	+	require.Positive(t, consumedBytes)
			70	+	} else {
			71	+	require.Zero(t, consumedEntries)
			72	+	require.Zero(t, consumedBytes)
			73	+	}
			74	+	})
			75	+	}
38		}	76		}

M internal/app/daemon_integration_test.go +27 -18

 	errs := make(chan error, clients)
 	var wg sync.WaitGroup
 	for range clients {
-		wg.Add(1)
+		wg.Go(func() {
-		go func() {
-			defer wg.Done()
 			_, err := ensureDaemonWithLifecycle(context.Background(), dir, dial, func() error {
 				spawns.Add(1)
 				return nil
 			}, cfg)
 			errs <- err
-		}()
+		})
 	}
 	require.Never(t, func() bool { return spawns.Load() != 0 }, 50*time.Millisecond, time.Millisecond)
 	close(ready)
 		closed:    make(chan struct{}),
 	}
 	repository := snapshot.NewRepository(filepath.Join(stateDir, "snapshots"))
-	shutdownClock := newLifecycleShutdownClock()
+	shutdownClock := newLifecycleShutdownClock(t)
 	reconciler := &lifecycleBlockingReconciler{
 		entered:  make(chan struct{}),
 		release:  make(chan struct{}),
 				pty.NewFactory(),
 				shutdownClock,
 				discardLog(),
-				daemon.WithSnapshotRepository(repository, nil),
+				daemon.WithSnapshotRepository(repository),
 				daemon.WithDurableMaintenance(catalogue, repository, reconciler, nil),
 				daemon.WithCatalogue(catalogue, nil),
 			)
 	releaseRestore := func() { releaseOnce.Do(func() { close(blocking.release) }) }
 	t.Cleanup(releaseRestore)
-	shutdownClock := newLifecycleShutdownClock()
+	shutdownClock := newLifecycleShutdownClock(t)
 	ctx, cancel := context.WithCancel(context.Background())
 	t.Cleanup(cancel)
 	listenerReady := make(chan struct{})
 				discardLog(),
 				daemon.WithShell("/bin/cat", nil),
 				daemon.WithCatalogue(opened.Catalogue, opened.Records),
-				daemon.WithSnapshotRepository(blocking, nil),
+				daemon.WithSnapshotRepository(blocking),
 			)
 			return d.Serve(ctx, listener)
 		})
 		discardLog(),
 		daemon.WithShell("/bin/cat", nil),
 		daemon.WithCatalogue(opened.Catalogue, opened.Records),
-		daemon.WithSnapshotRepository(repository, nil),
+		daemon.WithSnapshotRepository(repository),
 		daemon.WithRecoveryCoordinator(coordinator),
 	)
 	served := make(chan error, 1)
 	tr, _ := attach(t, runtimeDir, ports.IntentNew, name, domain.Size{Cols: 80, Rows: 24})
 	require.NoError(t, tr.Send(ports.Frame{Type: ports.MsgInput, Payload: ports.MarshalInput(ports.Input{Data: []byte("checkpoint me\n")})}))
 	require.Eventually(t, func() bool {
-		record, ok := opened.Catalogue.Record(name)
+		record, ok, _ := opened.Catalogue.Record(name)
 		return ok && record.RecoveryState == domain.RecoveryHealthy && record.Committed != nil
 	}, 5*time.Second, 10*time.Millisecond, "session never committed a checkpoint")
 	require.NoError(t, tr.Close())
 	t.Helper()
 	runtimeDir := filepath.Join(t.TempDir(), "runtime")
 	stateDir := filepath.Join(t.TempDir(), "state")
-	shutdownClock := newLifecycleShutdownClock()
+	shutdownClock := newLifecycleShutdownClock(t)
 	repository := newLifecycleBlockingRepository()
 	ctx, cancel := context.WithCancel(context.Background())
 	t.Cleanup(cancel)
 				shutdownClock,
 				discardLog(),
 				daemon.WithShell("/bin/cat", nil),
-				daemon.WithSnapshotRepository(repository, nil),
+				daemon.WithSnapshotRepository(repository),
 			)
 			return d.Serve(ctx, observed)
 		})
 }
 type lifecycleShutdownClock struct {
+	t      *testing.T
 	base   ports.Clock
 	timers chan *lifecycleManualTimer
 }
-func newLifecycleShutdownClock() *lifecycleShutdownClock {
+func newLifecycleShutdownClock(t *testing.T) *lifecycleShutdownClock {
-	return &lifecycleShutdownClock{base: clock.New(), timers: make(chan *lifecycleManualTimer, 4)}
+	t.Helper()
+	return &lifecycleShutdownClock{t: t, base: clock.New(), timers: make(chan *lifecycleManualTimer, 4)}
 }
 func (c *lifecycleShutdownClock) Now() time.Time { return c.base.Now() }
 func (c *lifecycleShutdownClock) NewTimer(delay time.Duration) ports.Timer {
-	if delay != time.Second {
+	if delay != daemon.SnapshotShutdownTimeout() {
 		return c.base.NewTimer(delay)
 	}
-	timer := &lifecycleManualTimer{ch: make(chan time.Time, 1)}
+	timer := &lifecycleManualTimer{t: c.t, ch: make(chan time.Time, 1)}
-	c.timers <- timer
+	select {
+	case c.timers <- timer:
+	default:
+		c.t.Errorf("unexpected additional snapshot shutdown timer with delay %s", delay)
+		timer.fire()
+	}
 	return timer
 }
 }
 type lifecycleManualTimer struct {
+	t       *testing.T
 	ch      chan time.Time
 	stopped atomic.Bool
 }
 func (t *lifecycleManualTimer) C() <-chan time.Time { return t.ch }
-func (t *lifecycleManualTimer) Reset(time.Duration) bool {
+func (t *lifecycleManualTimer) Reset(delay time.Duration) bool {
+	if delay != daemon.SnapshotShutdownTimeout() {
+		t.t.Errorf("snapshot shutdown timer reset with delay %s, want %s", delay, daemon.SnapshotShutdownTimeout())
+	}
 	t.stopped.Store(false)
 	return false
 }

M internal/app/durable_crash_matrix_test.go +7 -7


@@ -132,7 +132,7 @@ func TestDurableTransactionCrashMatrix(t *testing.T) {
132		require.NoError(t, catalogue.Close())	132		require.NoError(t, catalogue.Close())
133			133
134		h.recoverTwice(t, func(catalogue persist.Persister, _ snapshot.Repository, _ *recoveryfs.Journal) {	134		h.recoverTwice(t, func(catalogue persist.Persister, _ snapshot.Repository, _ *recoveryfs.Journal) {
135	-	record, exists := catalogue.Record("work")	135	+	record, exists, _ := catalogue.Record("work")
136		require.True(t, exists)	136		require.True(t, exists)
137		require.Equal(t, domain.IncarnationID{1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, record.IncarnationID)	137		require.Equal(t, domain.IncarnationID{1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, record.IncarnationID)
138		require.Equal(t, domain.RecoveryFresh, record.RecoveryState)	138		require.Equal(t, domain.RecoveryFresh, record.RecoveryState)

@@ -160,7 +160,7 @@ func TestDurableTransactionCrashMatrix(t *testing.T) {
160			160
161		ref := domain.CheckpointRef{Generation: 1, ManifestDigest: sha256.Sum256(publication.Manifest)}	161		ref := domain.CheckpointRef{Generation: 1, ManifestDigest: sha256.Sum256(publication.Manifest)}
162		h.recoverTwice(t, func(catalogue persist.Persister, repository snapshot.Repository, _ *recoveryfs.Journal) {	162		h.recoverTwice(t, func(catalogue persist.Persister, repository snapshot.Repository, _ *recoveryfs.Journal) {
163	-	stored, exists := catalogue.Record(record.Name)	163	+	stored, exists, _ := catalogue.Record(record.Name)
164		require.True(t, exists)	164		require.True(t, exists)
165		if boundaryName == "snapshot-publish" {	165		if boundaryName == "snapshot-publish" {
166		require.Equal(t, domain.RecoveryFresh, stored.RecoveryState)	166		require.Equal(t, domain.RecoveryFresh, stored.RecoveryState)

@@ -189,8 +189,8 @@ func TestDurableTransactionCrashMatrix(t *testing.T) {
189		require.NoError(t, catalogue.Close())	189		require.NoError(t, catalogue.Close())
190			190
191		h.recoverTwice(t, func(catalogue persist.Persister, _ snapshot.Repository, _ *recoveryfs.Journal) {	191		h.recoverTwice(t, func(catalogue persist.Persister, _ snapshot.Repository, _ *recoveryfs.Journal) {
192	-	_, oldExists := catalogue.Record("old")	192	+	_, oldExists, _ := catalogue.Record("old")
193	-	renamed, newExists := catalogue.Record("new")	193	+	renamed, newExists, _ := catalogue.Record("new")
194		require.False(t, oldExists)	194		require.False(t, oldExists)
195		require.True(t, newExists)	195		require.True(t, newExists)
196		require.Equal(t, record.IncarnationID, renamed.IncarnationID)	196		require.Equal(t, record.IncarnationID, renamed.IncarnationID)

@@ -228,7 +228,7 @@ func TestDurableTransactionCrashMatrix(t *testing.T) {
228		require.NoError(t, catalogue.Close())	228		require.NoError(t, catalogue.Close())
229			229
230		h.recoverTwice(t, func(catalogue persist.Persister, repository snapshot.Repository, _ *recoveryfs.Journal) {	230		h.recoverTwice(t, func(catalogue persist.Persister, repository snapshot.Repository, _ *recoveryfs.Journal) {
231	-	_, exists := catalogue.Record(record.Name)	231	+	_, exists, _ := catalogue.Record(record.Name)
232		require.False(t, exists)	232		require.False(t, exists)
233		assertNoTombstones(t, repository)	233		assertNoTombstones(t, repository)
234		require.NoDirExists(t, filepath.Join(h.snapshotDir, "sessions", record.IncarnationID.String()))	234		require.NoDirExists(t, filepath.Join(h.snapshotDir, "sessions", record.IncarnationID.String()))

@@ -275,7 +275,7 @@ func TestDurableDiscardCrashMatrix(t *testing.T) {
275		require.NoError(t, catalogue.Close())	275		require.NoError(t, catalogue.Close())
276			276
277		h.recoverTwice(t, func(catalogue persist.Persister, _ snapshot.Repository, journal *recoveryfs.Journal) {	277		h.recoverTwice(t, func(catalogue persist.Persister, _ snapshot.Repository, journal *recoveryfs.Journal) {
278	-	got, exists := catalogue.Record(old.Name)	278	+	got, exists, _ := catalogue.Record(old.Name)
279		require.True(t, exists)	279		require.True(t, exists)
280		require.Equal(t, newID, got.IncarnationID)	280		require.Equal(t, newID, got.IncarnationID)
281		require.Equal(t, domain.RecoveryFresh, got.RecoveryState)	281		require.Equal(t, domain.RecoveryFresh, got.RecoveryState)

@@ -312,7 +312,7 @@ func TestDeletionRecoveryProtectsReusedNameFilesystemBytes(t *testing.T) {
312		require.NoError(t, catalogue.Close())	312		require.NoError(t, catalogue.Close())
313			313
314		h.recoverTwice(t, func(catalogue persist.Persister, repository snapshot.Repository, _ *recoveryfs.Journal) {	314		h.recoverTwice(t, func(catalogue persist.Persister, repository snapshot.Repository, _ *recoveryfs.Journal) {
315	-	got, exists := catalogue.Record("work")	315	+	got, exists, _ := catalogue.Record("work")
316		require.True(t, exists)	316		require.True(t, exists)
317		require.Equal(t, replacement, got)	317		require.Equal(t, replacement, got)
318		require.Equal(t, replacementBytes, readTree(t, replacementPath))	318		require.Equal(t, replacementBytes, readTree(t, replacementPath))

M internal/app/offline_kill_retry_test.go +39 -46


@@ -14,50 +14,43 @@ import (
14		)	14		)
15			15
16		func TestRunKillOfflineUsesIncarnationDeletionProtocol(t *testing.T) {	16		func TestRunKillOfflineUsesIncarnationDeletionProtocol(t *testing.T) {
17	-	stateRoot, runtimeRoot := t.TempDir(), t.TempDir()	17	+	tests := []struct {
18	-	t.Setenv("XDG_STATE_HOME", stateRoot)	18	+	name string
19	-	t.Setenv("XDG_RUNTIME_DIR", runtimeRoot)	19	+	crashHook func(*testing.T, string)
20	-		20	+	}{
21	-	id := domain.IncarnationID{1}	21	+	{name: "normal"},
22	-	p := newTestPersister(t, filepath.Join(stateRoot, "vev"))	22	+	{
23	-	now := time.Now().UnixNano()	23	+	name: ".prev crash hook",
24	-	require.NoError(t, p.Save(persist.Record{Name: "named", IncarnationID: id, Cwd: t.TempDir(), CreatedAt: now, UpdatedAt: now, RecoveryState: domain.RecoveryFresh}))	24	+	crashHook: func(t *testing.T, stateDir string) {
25	-	require.NoError(t, p.Close())	25	+	t.Helper()
26	-	source := filepath.Join(stateRoot, "vev", "snapshots", "sessions", id.String())	26	+	storePath := persist.StorePath(stateDir)
27	-	require.NoError(t, os.MkdirAll(source, 0o700))	27	+	require.NoError(t, os.Rename(storePath, storePath+".prev"))
28	-	require.NoError(t, os.WriteFile(filepath.Join(source, "sentinel"), []byte("durable"), 0o600))	28	+	},
29	-		29	+	},
30	-	require.NoError(t, runKill(context.Background(), "named", false, false))	30	+	}
31	-	require.NoFileExists(t, filepath.Join(source, "sentinel"))	31	+
32	-	require.FileExists(t, filepath.Join(stateRoot, "vev", "snapshots", "quarantine", id.String(), "snapshot", "sentinel"))	32	+	for _, tt := range tests {
33	-	}	33	+	t.Run(tt.name, func(t *testing.T) {
34	-		34	+	stateRoot, runtimeRoot := t.TempDir(), t.TempDir()
35	-	// TestRunKillOfflineFindsSessionWhenOnlyPrevCandidateExists covers the same	35	+	t.Setenv("XDG_STATE_HOME", stateRoot)
36	-	// bug class as persist.LoadCatalogueReadOnly's fresh-install regression: a	36	+	t.Setenv("XDG_RUNTIME_DIR", runtimeRoot)
37	-	// crash mid-compaction can leave sessions.kv absent with only a .prev (or	37	+	stateDir := filepath.Join(stateRoot, "vev")
38	-	// .next) candidate on disk. `vev kill <name>` must still find and delete the	38	+
39	-	// session rather than reporting "no such session" from a bare os.Stat	39	+	id := domain.IncarnationID{1}
40	-	// precheck on the fixed sessions.kv path.	40	+	p := newTestPersister(t, stateDir)
41	-	func TestRunKillOfflineFindsSessionWhenOnlyPrevCandidateExists(t *testing.T) {	41	+	now := time.Now().UnixNano()
42	-	stateRoot, runtimeRoot := t.TempDir(), t.TempDir()	42	+	require.NoError(t, p.Save(persist.Record{Name: "named", IncarnationID: id, Cwd: t.TempDir(), CreatedAt: now, UpdatedAt: now, RecoveryState: domain.RecoveryFresh}))
43	-	t.Setenv("XDG_STATE_HOME", stateRoot)	43	+	require.NoError(t, p.Close())
44	-	t.Setenv("XDG_RUNTIME_DIR", runtimeRoot)	44	+	source := filepath.Join(stateDir, "snapshots", "sessions", id.String())
45	-		45	+	require.NoError(t, os.MkdirAll(source, 0o700))
46	-	id := domain.IncarnationID{1}	46	+	require.NoError(t, os.WriteFile(filepath.Join(source, "sentinel"), []byte("durable"), 0o600))
47	-	p := newTestPersister(t, filepath.Join(stateRoot, "vev"))	47	+	if tt.crashHook != nil {
48	-	now := time.Now().UnixNano()	48	+	tt.crashHook(t, stateDir)
49	-	require.NoError(t, p.Save(persist.Record{Name: "crashed", IncarnationID: id, Cwd: t.TempDir(), CreatedAt: now, UpdatedAt: now, RecoveryState: domain.RecoveryFresh}))	49	+	}
50	-	require.NoError(t, p.Close())	50	+
51	-	source := filepath.Join(stateRoot, "vev", "snapshots", "sessions", id.String())	51	+	require.NoError(t, runKill(context.Background(), "named", false, false))
52	-	require.NoError(t, os.MkdirAll(source, 0o700))	52	+	require.NoFileExists(t, filepath.Join(source, "sentinel"))
53	-	require.NoError(t, os.WriteFile(filepath.Join(source, "sentinel"), []byte("durable"), 0o600))	53	+	require.FileExists(t, filepath.Join(stateDir, "snapshots", "quarantine", id.String(), "snapshot", "sentinel"))
54	-		54	+	})
55	-	// Simulate a crash mid-compaction: current renamed away to .prev, no	55	+	}
56	-	// sessions.kv on disk at all.
57	-	storePath := persist.StorePath(filepath.Join(stateRoot, "vev"))
58	-	require.NoError(t, os.Rename(storePath, storePath+".prev"))
59	-
60	-	require.NoError(t, runKill(context.Background(), "crashed", false, false))
61	-	require.NoFileExists(t, filepath.Join(source, "sentinel"))
62	-	require.FileExists(t, filepath.Join(stateRoot, "vev", "snapshots", "quarantine", id.String(), "snapshot", "sentinel"))
63		}	56		}

M internal/app/run.go +29 -8

 // fencedRecoveries resolves each conflict against the post-recovery catalogue
 // so a fenced session is reported with the incarnation it actually holds now.
-func fencedRecoveries(conflicts []recovery.RecoveryConflict, catalogue ports.Catalogue) []fencedRecoveryIdentity {
+func fencedRecoveries(conflicts []recovery.RecoveryConflict, catalogue ports.Catalogue) ([]fencedRecoveryIdentity, error) {
 	fenced := make([]fencedRecoveryIdentity, 0, len(conflicts))
 	for _, conflict := range conflicts {
 		identity := fencedRecoveryIdentity{name: conflict.Session, kind: conflict.Kind, reasonCode: fencedRecoveryReasonCode(conflict.Err)}
 		if catalogue != nil {
-			if record, ok := catalogue.Record(conflict.Session); ok {
+			record, ok, err := catalogue.Record(conflict.Session)
+			if err != nil {
+				return nil, err
+			}
+			if ok {
 				identity.id = record.IncarnationID
 			}
 		}
 		fenced = append(fenced, identity)
 	}
-	return fenced
+	return fenced, nil
 }
 func fencedRecoveryReasonCode(err error) string {
 	return runDaemonOwnedWithLogger(ctx, log)
 }
+func recoverAuthoritativeCatalogue(ctx context.Context, coordinator *recovery.Coordinator, catalogue ports.Catalogue) ([]domain.CatalogueRecord, error) {
+	if err := coordinator.Recover(ctx); err != nil {
+		return nil, err
+	}
+	return catalogue.Records()
+}
 func runDaemonOwnedWithLogger(ctx context.Context, log *slog.Logger) (retErr error) {
 	clk := clock.New()
 	observer, observerCloser, err := newPerformanceTrace(clk)
 	daemonOpts = append(daemonOpts, daemon.WithBarScriptCommandRunner(shellcmd.New()))
 	daemonOpts = append(daemonOpts, daemon.WithProcessInspector(platform.NewProcessInspector()), daemon.WithDirOrHome(platform.DirOrHome))
 	snapshotRepository := snapshotadapter.NewRepository(snapshotDir(), log)
-	daemonOpts = append(daemonOpts, daemon.WithSnapshotRepository(snapshotRepository, snapshotRepository))
+	daemonOpts = append(daemonOpts, daemon.WithSnapshotRepository(snapshotRepository))
 	noticeStore := noticefile.New(platform.StateDir())
 	daemonOpts = append(daemonOpts, daemon.WithNoticeStore(noticeStore))
 	storePath := persist.StorePath(platform.StateDir())
 		return errors.Join(fmt.Errorf("vev: inspect durable session transactions: %w", err), opened.Catalogue.Close())
 	}
 	coordinator := recovery.NewCoordinator(opened.Catalogue, snapshotRepository, journal, rand.Reader)
-	if err := coordinator.Recover(ctx); err != nil {
+	// Recovery may roll catalogue changes forward, so reload the authoritative
-		return errors.Join(fmt.Errorf("vev: recover durable session transactions: %w", err), opened.Catalogue.Close())
+	// snapshot before constructing runtime reservations. A failed reload aborts
+	// startup rather than treating durable sessions as absent.
+	recoveredRecords, err := recoverAuthoritativeCatalogue(ctx, coordinator, opened.Catalogue)
+	if err != nil {
+		return errors.Join(fmt.Errorf("vev: recover and reload durable session transactions: %w", err), opened.Catalogue.Close())
 	}
+	opened.Records = recoveredRecords
 	// Recovery fences a session instead of failing startup when only that
 	// session's durable state is self-inconsistent. The daemon then comes up
 	// looking healthy, so every fenced session must be reported and persisted.
-	fenced := fencedRecoveries(coordinator.Conflicts(), opened.Catalogue)
+	fenced, err := fencedRecoveries(coordinator.Conflicts(), opened.Catalogue)
+	if err != nil {
+		return errors.Join(fmt.Errorf("vev: read fenced recovery identities: %w", err), opened.Catalogue.Close())
+	}
 	logFencedRecoveries(log, fenced)
 	if err := persistTransactionRecoveryNotices(noticeStore, pendingRecoveries, clk.Now()); err != nil {
 		log.Error("transaction_recovery_notice_failed", "err", err)
 	}
 	defer func() { retErr = errors.Join(retErr, opened.Catalogue.Close()) }()
-	if _, ok := opened.Catalogue.Record(name); !ok {
+	if _, ok, err := opened.Catalogue.Record(name); err != nil {
+		return fmt.Errorf("vev: reading stored session: %w", err)
+	} else if !ok {
 		return fmt.Errorf("vev: no such session: %s", name)
 	}
 	coordinator := recovery.NewCoordinator(opened.Catalogue, repository, recoveryfs.New(platform.StateDir()), rand.Reader)

M internal/app/run_test.go +52 -19

 	"time"
 	"github.com/bnema/vev/internal/adapters/lifecycle"
+	"github.com/bnema/vev/internal/adapters/noticefile"
 	"github.com/bnema/vev/internal/adapters/recoveryfs"
 	"github.com/bnema/vev/internal/adapters/snapshot"
 	"github.com/bnema/vev/internal/domain"
 	require.Equal(t, "clean", recovered["outcome"])
 	require.NotContains(t, eventNames(entries), "interrupted_transaction_fenced")
-	logBuffer.Reset()
-	log.Error("catalogue_validation_failed", "path", "/state/vev/sessions.kv", "reason_code", "corrupt")
-	require.NotContains(t, eventNames(decodeJSONLogs(t, logBuffer.Bytes())), "daemon_startup_complete")
 	require.NotContains(t, fmt.Sprint(requireEvent(t, entries, "interrupted_transaction_recovery_complete")), "terminal contents")
 	require.Equal(t, domain.NoticeSnapshotRestore, recoveryNotice.Code)
 	require.Equal(t, domain.SessionID(domain.IncarnationID{9}.String()), recoveryNotice.SessionID)
 // A session-scoped conflict no longer aborts startup, so the daemon comes up
 // looking healthy. Startup must therefore name the fenced session in the log,
 // persist a notice for it, and never report the recovery as clean.
+func TestStartupReloadsCatalogueAfterRolledForwardDeletion(t *testing.T) {
+	ctx := t.Context()
+	stateDir := filepath.Join(t.TempDir(), "vev")
+	catalogue := newTestPersister(t, stateDir)
+	t.Cleanup(func() { _ = catalogue.Close() })
+	repository := snapshot.NewRepository(filepath.Join(stateDir, "snapshots"))
+	record := domain.CatalogueRecord{
+		Name: "work", IncarnationID: domain.IncarnationID{9}, Cwd: t.TempDir(),
+		CreatedAt: 1, UpdatedAt: 1, RecoveryState: domain.RecoveryDeleting,
+	}
+	require.NoError(t, catalogue.Save(record))
+	coordinator := recovery.NewCoordinator(catalogue, repository, recoveryfs.New(stateDir), rand.Reader)
+	records, err := recoverAuthoritativeCatalogue(ctx, coordinator, catalogue)
+	require.NoError(t, err)
+	require.Empty(t, records, "daemon startup must not retain the pre-recovery reservation")
+	_, exists, err := catalogue.Record(record.Name)
+	require.NoError(t, err)
+	require.False(t, exists, "rolled-forward deletion must remain absent in authoritative state")
+}
 func TestFencedRecoveryObservability(t *testing.T) {
 	ctx := context.Background()
 	stateDir := filepath.Join(t.TempDir(), "vev")
 	coordinator := recovery.NewCoordinator(catalogue, repository, recoveryfs.New(stateDir), rand.Reader)
 	require.NoError(t, coordinator.Recover(ctx), "a session-scoped conflict must not abort startup")
-	fenced := fencedRecoveries(coordinator.Conflicts(), catalogue)
+	fenced, err := fencedRecoveries(coordinator.Conflicts(), catalogue)
+	require.NoError(t, err)
 	require.Equal(t, []fencedRecoveryIdentity{{
 		name: live.Name, id: live.IncarnationID, kind: "deletion-tombstone", reasonCode: "deletion-tombstone-conflict",
 	}}, fenced)
 	log := slog.New(slog.NewJSONHandler(&logBuffer, nil))
 	logFencedRecoveries(log, fenced)
 	logTransactionRecovery(log, 1, len(fenced))
-	logStartupRecoveryCounts(log, catalogue.Records(), 0)
+	records, err := catalogue.Records()
+	require.NoError(t, err)
+	logStartupRecoveryCounts(log, records, 0)
 	entries := decodeJSONLogs(t, logBuffer.Bytes())
 	event := requireEvent(t, entries, "interrupted_transaction_fenced")
 	require.Equal(t, "fenced", recovered["outcome"])
 	require.Contains(t, eventNames(entries), "daemon_startup_complete")
-	store := portsmocks.NewMockNoticeStore(t)
+	store := noticefile.New(stateDir)
-	var notice domain.Notification
-	store.EXPECT().Append(mock.Anything).Run(func(n domain.Notification) { notice = n }).Return(nil).Once()
 	require.NoError(t, persistFencedRecoveryNotices(store, fenced, time.Unix(1, 0)))
+	reopened := noticefile.New(stateDir)
+	pending, err := reopened.Claim()
+	require.NoError(t, err)
+	require.Len(t, pending, 1)
+	notice := pending[0]
 	require.Equal(t, domain.NoticeSnapshotRestore, notice.Code)
 	require.Equal(t, domain.NoticeWarn, notice.Severity)
 	require.Equal(t, domain.SessionID(live.IncarnationID.String()), notice.SessionID)
 	require.Contains(t, notice.Details, "session="+live.Name)
 	require.Contains(t, notice.Details, "reason_code=deletion-tombstone-conflict")
+	require.NoError(t, reopened.Ack())
-	degraded, ok := catalogue.Record(live.Name)
+	degraded, ok, err := catalogue.Record(live.Name)
+	require.NoError(t, err)
 	require.True(t, ok)
 	require.Equal(t, domain.RecoveryDegraded, degraded.RecoveryState)
 }
 		stateDir := filepath.Join(stateRoot, "vev")
 		t.Setenv("XDG_RUNTIME_DIR", runtimeRoot)
 		t.Setenv("XDG_STATE_HOME", stateRoot)
-		ctx, cancel := context.WithCancel(context.Background())
+		ctx, cancel := context.WithCancel(t.Context())
-		defer cancel()
+		result := make(chan error, 1)
 		go func() {
-			for {
+			result <- runWithLifecycleOwner(ctx, runtimeDir, stateDir, runDaemonOwned)
-				if _, err := os.Stat(filepath.Join(runtimeDir, "daemon.sock")); err == nil {
-					cancel()
-					return
-				}
-				time.Sleep(time.Millisecond)
-			}
 		}()
+		t.Cleanup(func() {
+			cancel()
+			select {
+			case err := <-result:
+				require.NoError(t, err)
+			case <-time.After(5 * time.Second):
+				t.Error("daemon lifecycle did not stop after cancellation")
+			}
+		})
-		require.NoError(t, runWithLifecycleOwner(ctx, runtimeDir, stateDir, runDaemonOwned))
+		require.Eventually(t, func() bool {
+			_, err := os.Stat(filepath.Join(runtimeDir, "daemon.sock"))
+			return err == nil
+		}, 5*time.Second, time.Millisecond, "daemon socket was not published")
 		require.FileExists(t, persist.StorePath(stateDir))
 	})

M internal/app/spawn.go +45 -49

 	total:   5 * time.Second,
 }
-func waitForLifecycleAvailability(ctx context.Context, runtimeDir string, cfg backoffConfig) (lifecycleOwnership, error) {
+func retryAttempts[T any](ctx context.Context, cfg backoffConfig, attempt func() (T, bool, error)) (T, error) {
 	deadline := time.Now().Add(cfg.total)
 	backoff := cfg.initial
 	for {
 		if err := ctx.Err(); err != nil {
-			return nil, err
+			var zero T
+			return zero, err
 		}
-		owner, err := daemonLifecycleProbe.TryAcquire(runtimeDir)
+		result, done, err := attempt()
-		if err == nil {
+		if err != nil {
-			return owner, nil
+			var zero T
+			return zero, err
 		}
-		if !errors.Is(err, lifecycle.ErrBusy) {
+		if done {
-			return nil, err
+			return result, nil
 		}
 		if !time.Now().Before(deadline) {
-			return nil, ErrDaemonUnreachable
+			var zero T
+			return zero, ErrDaemonUnreachable
 		}
 		if err := waitBackoff(ctx, backoff); err != nil {
-			return nil, err
+			var zero T
+			return zero, err
 		}
 		if backoff *= 2; backoff > cfg.max {
 			backoff = cfg.max
 	}
 }
-func waitForDaemonOrLifecycle(ctx context.Context, dir string, dial dialFunc, cfg backoffConfig) (ports.Transport, lifecycleOwnership, error) {
+func waitForLifecycleAvailability(ctx context.Context, runtimeDir string, cfg backoffConfig) (lifecycleOwnership, error) {
-	deadline := time.Now().Add(cfg.total)
+	return retryAttempts(ctx, cfg, func() (lifecycleOwnership, bool, error) {
-	backoff := cfg.initial
+		owner, err := daemonLifecycleProbe.TryAcquire(runtimeDir)
-	for {
+		if err == nil {
-		if err := ctx.Err(); err != nil {
+			return owner, true, nil
-			return nil, nil, err
+		}
+		if !errors.Is(err, lifecycle.ErrBusy) {
+			return nil, false, err
 		}
+		return nil, false, nil
+	})
+}
+type daemonOrLifecycle struct {
+	transport ports.Transport
+	owner     lifecycleOwnership
+}
+func waitForDaemonOrLifecycle(ctx context.Context, dir string, dial dialFunc, cfg backoffConfig) (ports.Transport, lifecycleOwnership, error) {
+	result, err := retryAttempts(ctx, cfg, func() (daemonOrLifecycle, bool, error) {
 		if transport, err := dial(ctx, dir); err == nil {
-			return transport, nil, nil
+			return daemonOrLifecycle{transport: transport}, true, nil
 		}
 		owner, err := daemonLifecycleProbe.TryAcquire(dir)
 		if err == nil {
-			return nil, owner, nil
+			return daemonOrLifecycle{owner: owner}, true, nil
 		}
 		if !errors.Is(err, lifecycle.ErrBusy) {
-			return nil, nil, err
+			return daemonOrLifecycle{}, false, err
 		}
-		if !time.Now().Before(deadline) {
+		return daemonOrLifecycle{}, false, nil
-			return nil, nil, ErrDaemonUnreachable
+	})
-		}
+	return result.transport, result.owner, err
-		if err := waitBackoff(ctx, backoff); err != nil {
-			return nil, nil, err
-		}
-		if backoff *= 2; backoff > cfg.max {
-			backoff = cfg.max
-		}
-	}
 }
 func waitBackoff(ctx context.Context, duration time.Duration) error {
 // retryDial dials repeatedly with exponential backoff until the daemon
 // answers, the context is cancelled, or the total budget is exhausted.
 func retryDial(ctx context.Context, dir string, dial dialFunc, cfg backoffConfig) (ports.Transport, error) {
-	deadline := time.Now().Add(cfg.total)
+	transport, err := retryAttempts(ctx, cfg, func() (ports.Transport, bool, error) {
-	backoff := cfg.initial
+		transport, err := dial(ctx, dir)
-	for {
+		return transport, err == nil, nil
-		if err := ctx.Err(); err != nil {
+	})
-			return nil, err
+	if errors.Is(err, ErrDaemonUnreachable) {
-		}
+		slog.Error("daemon did not become reachable before retry budget expired", "socket_dir", dir, "budget", cfg.total)
-		if t, err := dial(ctx, dir); err == nil {
-			return t, nil
-		}
-		if !time.Now().Before(deadline) {
-			slog.Error("daemon did not become reachable before retry budget expired", "socket_dir", dir, "budget", cfg.total)
-			return nil, ErrDaemonUnreachable
-		}
-		select {
-		case <-ctx.Done():
-			return nil, ctx.Err()
-		case <-time.After(backoff):
-		}
-		if backoff *= 2; backoff > cfg.max {
-			backoff = cfg.max
-		}
 	}
+	return transport, err
 }
 // realDial is the production dialer.

M internal/app/spawn_test.go +15 -0


@@ -258,6 +258,21 @@ func TestAcquireSpawnLockTakesOverStaleLock(t *testing.T) {
258	release()	258		release()
259	}	259		}
260		260
		261	+	func TestRetryAttemptsChecksOperationErrorBeforeDeadline(t *testing.T) {
		262	+	attemptErr := errors.New("attempt failed")
		263	+	calls := 0
		264	+	_, err := retryAttempts(context.Background(), backoffConfig{}, func() (struct{}, bool, error) {
		265	+	calls++
		266	+	return struct{}{}, false, attemptErr
		267	+	})
		268	+	if !errors.Is(err, attemptErr) {
		269	+	t.Fatalf("retryAttempts error = %v, want %v", err, attemptErr)
		270	+	}
		271	+	if calls != 1 {
		272	+	t.Fatalf("attempt called %d times, want 1", calls)
		273	+	}
		274	+	}
		275	+
261	func TestRetryDialSucceedsAfterTransientFailures(t *testing.T) {	276		func TestRetryDialSucceedsAfterTransientFailures(t *testing.T) {
262	want := portsmocks.NewMockTransport(t)	277		want := portsmocks.NewMockTransport(t)
263	var calls atomic.Int32	278		var calls atomic.Int32

M internal/domain/recovery.go +19 -0


@@ -5,6 +5,7 @@ import (
5	"errors"	5		"errors"
6	"fmt"	6		"fmt"
7	"io"	7		"io"
		8	+	"slices"
8	"strings"	9		"strings"
9	)	10		)
10		11

@@ -44,6 +45,24 @@ type CatalogueRecord struct {
44		45
45	// CatalogueMetadataUpdate changes mutable runtime metadata for one catalogue	46		// CatalogueMetadataUpdate changes mutable runtime metadata for one catalogue
46	// incarnation without carrying authority-owned recovery or checkpoint fields.	47		// incarnation without carrying authority-owned recovery or checkpoint fields.
		48	+	// Equal reports canonical value equality between checkpoint references.
		49	+	func (r CheckpointRef) Equal(other CheckpointRef) bool {
		50	+	if r == nil \|\| other == nil {
		51	+	return r == nil && other == nil
		52	+	}
		53	+	return r == other
		54	+	}
		55	+
		56	+	// Equal reports canonical value equality, including ordered tab names and
		57	+	// pointed-to checkpoint values rather than pointer identity.
		58	+	func (r CatalogueRecord) Equal(other CatalogueRecord) bool {
		59	+	return r.Name == other.Name && r.IncarnationID == other.IncarnationID && r.Cwd == other.Cwd &&
		60	+	r.CreatedAt == other.CreatedAt && r.UpdatedAt == other.UpdatedAt && r.LastUsedSeq == other.LastUsedSeq &&
		61	+	slices.Equal(r.TabNames, other.TabNames) && r.RecoveryState == other.RecoveryState &&
		62	+	r.Committed.Equal(other.Committed) && r.Fallbacks[0].Equal(other.Fallbacks[0]) &&
		63	+	r.Fallbacks[1].Equal(other.Fallbacks[1]) && r.DegradedReason == other.DegradedReason
		64	+	}
		65	+
47	type CatalogueMetadataUpdate struct {	66		type CatalogueMetadataUpdate struct {
48	Name string	67		Name string
49	IncarnationID IncarnationID	68		IncarnationID IncarnationID

M internal/domain/recovery_test.go +22 -1


@@ -22,7 +22,12 @@ func TestIncarnationIDText(t *testing.T) {
22		var decoded IncarnationID	22		var decoded IncarnationID
23		require.NoError(t, decoded.UnmarshalText(text))	23		require.NoError(t, decoded.UnmarshalText(text))
24		require.Equal(t, id, decoded)	24		require.Equal(t, id, decoded)
25	-	require.Error(t, decoded.UnmarshalText([]byte("AB")))	25	+	require.Error(t, decoded.UnmarshalText([]byte("AB0000000000000000000000000000CD")))
			26	+
			27	+	_, err = (IncarnationID{}).MarshalText()
			28	+	require.Error(t, err)
			29	+	require.Error(t, decoded.UnmarshalText([]byte("00000000000000000000000000000000")))
			30	+	require.Equal(t, id, decoded, "rejected zero text must not mutate the receiver")
26		}	31		}
27			32
28		func TestCatalogueRecordValidate(t *testing.T) {	33		func TestCatalogueRecordValidate(t *testing.T) {

@@ -50,6 +55,7 @@ func TestCatalogueRecordValidate(t *testing.T) {
50		{name: "zero checkpoint generation", record: CatalogueRecord{Name: "work", IncarnationID: IncarnationID{1}, RecoveryState: RecoveryHealthy, Committed: &CheckpointRef{ManifestDigest: [32]byte{1}}}},	55		{name: "zero checkpoint generation", record: CatalogueRecord{Name: "work", IncarnationID: IncarnationID{1}, RecoveryState: RecoveryHealthy, Committed: &CheckpointRef{ManifestDigest: [32]byte{1}}}},
51		{name: "zero checkpoint digest", record: CatalogueRecord{Name: "work", IncarnationID: IncarnationID{1}, RecoveryState: RecoveryHealthy, Committed: &CheckpointRef{Generation: 7}}},	56		{name: "zero checkpoint digest", record: CatalogueRecord{Name: "work", IncarnationID: IncarnationID{1}, RecoveryState: RecoveryHealthy, Committed: &CheckpointRef{Generation: 7}}},
52		{name: "second fallback without first", record: CatalogueRecord{Name: "work", IncarnationID: IncarnationID{1}, RecoveryState: RecoveryHealthy, Committed: validRef, Fallbacks: [2]*CheckpointRef{nil, {Generation: 6, ManifestDigest: [32]byte{2}}}}},	57		{name: "second fallback without first", record: CatalogueRecord{Name: "work", IncarnationID: IncarnationID{1}, RecoveryState: RecoveryHealthy, Committed: validRef, Fallbacks: [2]*CheckpointRef{nil, {Generation: 6, ManifestDigest: [32]byte{2}}}}},
			58	+	{name: "fallback newer than committed", record: CatalogueRecord{Name: "work", IncarnationID: IncarnationID{1}, RecoveryState: RecoveryHealthy, Committed: &CheckpointRef{Generation: 6, ManifestDigest: [32]byte{1}}, Fallbacks: [2]*CheckpointRef{{Generation: 7, ManifestDigest: [32]byte{2}}}}},
53		}	59		}
54		for _, tt := range tests {	60		for _, tt := range tests {
55		t.Run(tt.name, func(t *testing.T) {	61		t.Run(tt.name, func(t *testing.T) {

@@ -58,6 +64,21 @@ func TestCatalogueRecordValidate(t *testing.T) {
58		}	64		}
59		}	65		}
60			66
			67	+	func TestCatalogueRecordEqualUsesCheckpointValuesAndOrderedTabs(t *testing.T) {
			68	+	committed := CheckpointRef{Generation: 2, ManifestDigest: [32]byte{2}}
			69	+	left := CatalogueRecord{Name: "work", IncarnationID: IncarnationID{1}, TabNames: []string{"shell", "logs"}, RecoveryState: RecoveryHealthy, Committed: &committed}
			70	+	right := left
			71	+	right.TabNames = append([]string(nil), left.TabNames...)
			72	+	copy := committed
			73	+	right.Committed = &copy
			74	+	require.True(t, left.Equal(right))
			75	+
			76	+	right.TabNames[0], right.TabNames[1] = right.TabNames[1], right.TabNames[0]
			77	+	require.False(t, left.Equal(right))
			78	+	require.True(t, (*CheckpointRef)(nil).Equal(nil))
			79	+	require.False(t, left.Committed.Equal(nil))
			80	+	}
			81	+
61		func TestDeletionTombstoneValidate(t *testing.T) {	82		func TestDeletionTombstoneValidate(t *testing.T) {
62		tests := []struct {	83		tests := []struct {
63		name string	84		name string

M internal/persist/catalogue_test.go +31 -3

 			got, err := decodeRecordValue(record.Name, encoded)
 			require.NoError(t, err)
 			require.Equal(t, record, got)
+			for prefix := range len(encoded) {
+				_, err := decodeRecordValue(record.Name, encoded[:prefix])
+				require.Error(t, err, "prefix length %d", prefix)
+			}
 			require.Error(t, func() error { _, err := decodeRecordValue(record.Name, append(encoded, 0)); return err }())
 		})
 	}
 }
+func TestDecodeRecordValueWrapsMalformedAndValidationErrors(t *testing.T) {
+	encoded, err := encodeRecordValue(validRecord("work", 1))
+	require.NoError(t, err)
+	const recoveryStateOffset = 4 + 2 + 16 + 4 + 8 + 8 + 8 + 4
+	encoded[recoveryStateOffset] = 99
+	_, err = decodeRecordValue("work", encoded)
+	require.ErrorIs(t, err, errMalformedRecord)
+	joined, ok := err.(interface{ Unwrap() []error })
+	require.True(t, ok)
+	require.Len(t, joined.Unwrap(), 2)
+	require.ErrorContains(t, joined.Unwrap()[1], "invalid recovery state")
+}
 func testCatalogueDuplicateIncarnations(t *testing.T) {
 	id := domain.IncarnationID{1}
 	require.Error(t, validateUniqueIncarnations([]domain.CatalogueRecord{
 	next := domain.CatalogueRecord{Name: "work", IncarnationID: original.IncarnationID, Cwd: "/new", UpdatedAt: 22, LastUsedSeq: 23, TabNames: []string{"editor", "logs"}}
 	update := next.MetadataUpdate()
 	require.NoError(t, p.UpdateMetadata(update))
-	got, ok := p.Record("work")
+	got, ok, err := p.Record("work")
+	require.NoError(t, err)
 	require.True(t, ok)
 	expected := original
 	expected.Cwd, expected.UpdatedAt, expected.LastUsedSeq, expected.TabNames = next.Cwd, next.UpdatedAt, next.LastUsedSeq, next.TabNames
 		Name: "work", IncarnationID: original.IncarnationID, LastUsedSeq: &lastUsedSeq,
 	}))
 	expected.LastUsedSeq = lastUsedSeq
-	partiallyUpdated, ok := p.Record("work")
+	partiallyUpdated, ok, err := p.Record("work")
+	require.NoError(t, err)
 	require.True(t, ok)
 	require.Equal(t, expected, partiallyUpdated, "a partial metadata update must not clear other mutable or authority-owned fields")
 	stale := update
 	stale.IncarnationID = domain.IncarnationID{2}
 	require.Error(t, p.UpdateMetadata(stale))
-	unchanged, ok := p.Record("work")
+	unchanged, ok, err := p.Record("work")
+	require.NoError(t, err)
 	require.True(t, ok)
 	require.Equal(t, expected, unchanged)
 }
 				writeCandidate(t, StorePath(dir)+".next", want)
 			},
 		},
+		{
+			// Crash before a new installation publishes .next as current.
+			name: "next-only-recovers-from-next",
+			write: func(t *testing.T, dir string, want domain.CatalogueRecord) {
+				writeCandidate(t, StorePath(dir)+".next", want)
+			},
+		},
 		{
 			// Crash leaves only a predecessor behind; no current, no successor.
 			name: "prev-only-recovers-from-prev",

M internal/persist/migration.go +21 -5

 	"errors"
 	"fmt"
 	"io"
+	"log/slog"
 	"os"
 	"path/filepath"
 	"sort"
 	StateDir          string
 	Random            io.Reader
 	SnapshotMigration ports.SnapshotMigration
+	// Logger receives full adapter causes; durable degraded reasons are sanitized.
+	Logger *slog.Logger
 	// Fault is a test-only crash seam called after named durable boundaries.
 	Fault func(string) error
 }
 	catalogueFormatName           = "durable-session-v1.format"
 	migrationRecordMagic          = "VEVJ"
 	migrationRecordVersion uint16 = 1
+	migrationDegradedLegacySnapshotUncertain = "legacy_snapshot_uncertain"
+	migrationDegradedReasonMaxBytes          = 64
 )
 func OpenOrMigrate(ctx context.Context, deps OpenDeps) (OpenResult, error) {
 				if !errors.Is(err, ports.ErrLegacySnapshotUncertain) {
 					return OpenResult{}, fmt.Errorf("persist: migrate legacy snapshot %q: %w", legacy.Name, err)
 				}
+				migrationLogger(deps).Error("legacy snapshot migration uncertain", "session", legacy.Name, "err", err)
 				if ref.Generation != 0 && ref.ManifestDigest != ([32]byte{}) {
 					legacyRef := ref
 					record.Validated[legacy.Name] = &legacyRef
 				}
-				record.Degraded[legacy.Name] = err.Error()
+				record.Degraded[legacy.Name] = migrationDegradedLegacySnapshotUncertain
 			}
 			if err := writeMigrationRecord(intent, record); err != nil {
 				return OpenResult{}, err
 	return OpenResult{Catalogue: catalogue, Records: opened, Migrated: true}, nil
 }
+func migrationLogger(deps OpenDeps) *slog.Logger {
+	if deps.Logger != nil {
+		return deps.Logger
+	}
+	return slog.Default()
+}
 func migrationBoundary(deps OpenDeps, name string) error {
 	if deps.Fault != nil {
 		return deps.Fault(name)
 	if len(a) != len(b) {
 		return false
 	}
-	sort.Slice(a, func(i, j int) bool { return a[i].Name < a[j].Name })
+	left := append([]domain.CatalogueRecord(nil), a...)
-	sort.Slice(b, func(i, j int) bool { return b[i].Name < b[j].Name })
+	right := append([]domain.CatalogueRecord(nil), b...)
-	for i := range a {
+	sort.Slice(left, func(i, j int) bool { return left[i].Name < left[j].Name })
-		if a[i].Name != b[i].Name || a[i].IncarnationID != b[i].IncarnationID || a[i].RecoveryState != b[i].RecoveryState {
+	sort.Slice(right, func(i, j int) bool { return right[i].Name < right[j].Name })
+	for i := range left {
+		if !left[i].Equal(right[i]) {
 			return false
 		}
 	}

M internal/persist/migration_test.go +67 -15

 package persist
 import (
+	"bytes"
 	"context"
 	"crypto/sha256"
 	"encoding/binary"
 	"errors"
 	"io"
+	"log/slog"
 	"os"
 	"path/filepath"
 	"strconv"
+	"strings"
 	"testing"
 	"github.com/bnema/vev/internal/domain"
 	"github.com/bnema/vev/internal/ports"
 	"github.com/bnema/vev/pkg/kv"
+	"github.com/bnema/vev/pkg/safedir"
 	"github.com/stretchr/testify/require"
 )
 type migrationStub struct {
 	legacy      bool
+	probePaths  []string
 	probeErr    error
 	heads       map[string]domain.CheckpointRef
 	migrateErr  map[string]error
 	sources     map[string]string
 }
-func (s *migrationStub) HasLegacyState(context.Context) (bool, error) { return s.legacy, s.probeErr }
+func (s *migrationStub) HasLegacyState(context.Context) (bool, error) {
+	if s.probeErr != nil || s.legacy {
+		return s.legacy, s.probeErr
+	}
+	for _, path := range s.probePaths {
+		if _, err := os.Stat(path); err == nil {
+			return true, nil
+		} else if !errors.Is(err, os.ErrNotExist) {
+			return false, err
+		}
+	}
+	return false, nil
+}
 func (s *migrationStub) ReadLegacyHEAD(_ context.Context, name string) (domain.CheckpointRef, error) {
 	if source := s.sources[name]; source != "" {
 		if _, err := os.Stat(source); err != nil {
 func writeLegacyCatalogue(t *testing.T, dir string, records ...legacyCatalogueRecordV0) string {
 	t.Helper()
 	require.NoError(t, os.Chmod(dir, 0o700))
-	require.NoError(t, os.MkdirAll(dir, 0o700))
+	require.NoError(t, safedir.EnsurePrivate(dir))
 	store, err := kv.Open(StorePath(dir))
 	require.NoError(t, err)
 	for _, record := range records {
 			}
 			uncertain := recordByName(t, result.Records, "uncertain")
 			require.Equal(t, domain.RecoveryDegraded, uncertain.RecoveryState)
-			require.Contains(t, uncertain.DegradedReason, "corrupt legacy manifest")
+			require.Equal(t, migrationDegradedLegacySnapshotUncertain, uncertain.DegradedReason)
 			require.NoError(t, result.Catalogue.Close())
 			reopened, err := OpenOrMigrate(context.Background(), OpenDeps{StateDir: dir, Random: io.LimitReader(&countingReader{}, 0), SnapshotMigration: restarted})
 	dir := t.TempDir()
 	legacy := writeLegacyCatalogue(t, dir, legacyCatalogueRecordV0{Name: "broken", Cwd: "/tmp"})
 	ref := domain.CheckpointRef{Generation: 1, ManifestDigest: [32]byte{1}}
-	result, err := OpenOrMigrate(context.Background(), OpenDeps{StateDir: dir, Random: &countingReader{}, SnapshotMigration: &migrationStub{heads: map[string]domain.CheckpointRef{"broken": ref}, migrateErr: map[string]error{"broken": errors.Join(ports.ErrLegacySnapshotUncertain, errors.New("invalid legacy manifest"))}}})
+	adapterCause := strings.Repeat("sensitive-adapter-detail", 64)
+	var logs bytes.Buffer
+	logger := slog.New(slog.NewTextHandler(&logs, nil))
+	result, err := OpenOrMigrate(context.Background(), OpenDeps{StateDir: dir, Random: &countingReader{}, SnapshotMigration: &migrationStub{heads: map[string]domain.CheckpointRef{"broken": ref}, migrateErr: map[string]error{"broken": errors.Join(ports.ErrLegacySnapshotUncertain, errors.New(adapterCause))}}, Logger: logger})
 	require.NoError(t, err)
 	require.NoError(t, result.Catalogue.Close())
 	require.FileExists(t, legacy)
 	require.Equal(t, domain.RecoveryDegraded, result.Records[0].RecoveryState)
-	require.NotEmpty(t, result.Records[0].DegradedReason)
+	require.Equal(t, migrationDegradedLegacySnapshotUncertain, result.Records[0].DegradedReason)
+	require.LessOrEqual(t, len(result.Records[0].DegradedReason), migrationDegradedReasonMaxBytes)
+	require.NotContains(t, result.Records[0].DegradedReason, adapterCause)
+	require.Contains(t, logs.String(), adapterCause, "the full adapter cause must remain diagnosable")
 	failClosedDir := t.TempDir()
 	writeLegacyCatalogue(t, failClosedDir, legacyCatalogueRecordV0{Name: "work", Cwd: "/tmp"})
 func TestOpenOrMigrateLegacyProbe(t *testing.T) {
 	probeErr := errors.New("probe uncertain")
 	for _, tc := range []struct {
-		name    string
+		name       string
-		stub    *migrationStub
+		stub       *migrationStub
-		wantNew bool
+		arrange    func(t *testing.T, dir string, stub *migrationStub)
-		wantErr error
+		wantNew    bool
+		wantLegacy bool
+		wantErr    error
 	}{
-		{"proven absent", &migrationStub{}, true, nil},
+		{name: "proven absent", stub: &migrationStub{}, wantNew: true},
-		{"legacy blob", &migrationStub{legacy: true}, false, nil},
+		{name: "legacy blob", stub: &migrationStub{}, wantLegacy: true, arrange: func(t *testing.T, dir string, stub *migrationStub) {
-		{"incremental namespace", &migrationStub{legacy: true}, false, nil},
+			path := filepath.Join(dir, "legacy.snapshot")
-		{"probe error", &migrationStub{probeErr: probeErr}, false, probeErr},
+			require.NoError(t, os.WriteFile(path, []byte("legacy"), 0o600))
+			stub.probePaths = []string{path}
+		}},
+		{name: "incremental namespace", stub: &migrationStub{}, wantLegacy: true, arrange: func(t *testing.T, dir string, stub *migrationStub) {
+			path := filepath.Join(dir, "snapshots")
+			require.NoError(t, safedir.EnsurePrivate(path))
+			stub.probePaths = []string{path}
+		}},
+		{name: "probe error", stub: &migrationStub{probeErr: probeErr}, wantErr: probeErr},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
 			dir := t.TempDir()
 			require.NoError(t, os.Chmod(dir, 0o700))
+			if tc.arrange != nil {
+				tc.arrange(t, dir, tc.stub)
+			}
 			result, err := OpenOrMigrate(context.Background(), OpenDeps{StateDir: dir, Random: &countingReader{}, SnapshotMigration: tc.stub})
 			if tc.wantErr != nil {
 				require.ErrorIs(t, err, tc.wantErr)
-			} else if tc.stub.legacy {
+			} else if tc.wantLegacy {
 				require.Error(t, err)
 			} else {
 				require.NoError(t, err)
 					require.NoError(t, reopened.Catalogue.Close())
 				}
 			}
-			if tc.stub.legacy || tc.wantErr != nil {
+			if tc.wantLegacy || tc.wantErr != nil {
 				_, statErr := os.Stat(StorePath(dir))
 				require.ErrorIs(t, statErr, os.ErrNotExist)
 			}
 	}
 }
+func TestCatalogueRecordsEqualIsCompleteAndNonMutating(t *testing.T) {
+	committed := &domain.CheckpointRef{Generation: 2, ManifestDigest: [32]byte{2}}
+	left := []domain.CatalogueRecord{
+		{Name: "z", IncarnationID: domain.IncarnationID{1}, Cwd: "/old", CreatedAt: 1, UpdatedAt: 2, LastUsedSeq: 3, TabNames: []string{"shell"}, RecoveryState: domain.RecoveryHealthy, Committed: committed},
+		validRecord("a", 2),
+	}
+	right := []domain.CatalogueRecord{left[1], left[0]}
+	leftOrder, rightOrder := left[0].Name, right[0].Name
+	require.True(t, catalogueRecordsEqual(left, right))
+	require.Equal(t, leftOrder, left[0].Name)
+	require.Equal(t, rightOrder, right[0].Name)
+	right[1].Cwd = "/different"
+	require.False(t, catalogueRecordsEqual(left, right), "installed catalogue validation must compare every record field")
+}
 func TestAtomicMigrationWriteRemovesTempAfterRenameFailure(t *testing.T) {
 	dir := t.TempDir()
 	target := filepath.Join(dir, "target")

M internal/persist/persist.go +13 -55

 import (
 	"errors"
 	"fmt"
-	"log/slog"
-	"os"
 	"path/filepath"
 	"sort"
 	"sync"
 type Persister struct {
 	store ports.Store
 	mu    sync.Mutex
-	log   *slog.Logger
-}
-// Option configures a Persister at construction time.
-type Option func(*Persister)
-// WithLogger directs diagnostics for failures that ports.Catalogue has no
-// error return for (see Records) to log instead of the default logger.
-func WithLogger(log *slog.Logger) Option {
-	return func(p *Persister) { p.log = log }
-}
-// logger returns a nil-safe logger, defaulting to slog.Default() when no
-// logger was configured.
-func (p *Persister) logger() *slog.Logger {
-	if p != nil && p.log != nil {
-		return p.log
-	}
-	return slog.Default()
 }
 // KVStore adapts the reusable WAL implementation to the persistence port.
 	p, _, err := openCurrentCatalogue(dir, false)
 	return p, err
 }
-func New(store ports.Store, opts ...Option) *Persister {
+func New(store ports.Store) *Persister { return &Persister{store: store} }
-	p := &Persister{store: store}
-	for _, opt := range opts {
-		opt(p)
-	}
-	return p
-}
 func openCurrentCatalogue(dir string, createProvenEmpty bool) (*Persister, []domain.CatalogueRecord, error) {
 	path := StorePath(dir)
-	absent := true
+	present, err := catalogueCandidatesPresent(path)
-	for _, candidate := range []string{path, path + ".next", path + ".prev"} {
+	if err != nil {
-		_, err := os.Stat(candidate)
+		return nil, nil, err
-		if err == nil {
-			absent = false
-			continue
-		}
-		if !errors.Is(err, os.ErrNotExist) {
-			return nil, nil, err
-		}
 	}
-	if absent && !createProvenEmpty {
+	if !present && !createProvenEmpty {
 		return nil, nil, fmt.Errorf("%w: no catalogue candidates", errPersistenceUnavailable)
 	}
 	store, err := OpenStore(path)
 	return p.applyLocked(map[string]*domain.CatalogueRecord{record.Name: &record})
 }
-// Records satisfies ports.Catalogue, whose signature has no error return. A
+func (p *Persister) Records() ([]domain.CatalogueRecord, error) { return p.LoadCatalogue() }
-// load failure (unavailable store, or a malformed record surfaced by
+func (p *Persister) Record(name string) (domain.CatalogueRecord, bool, error) {
-// decodeAll) must not silently look like an empty catalogue, so it is logged
-// here instead of being swallowed.
-func (p *Persister) Records() []domain.CatalogueRecord {
-	records, err := p.LoadCatalogue()
-	if err != nil {
-		p.logger().Error("persist: loading catalogue records failed", "err", err)
-		return []domain.CatalogueRecord{}
-	}
-	return records
-}
-func (p *Persister) Record(name string) (domain.CatalogueRecord, bool) {
 	if p == nil || p.store == nil {
-		return domain.CatalogueRecord{}, false
+		return domain.CatalogueRecord{}, false, errPersistenceUnavailable
 	}
 	p.mu.Lock()
 	defer p.mu.Unlock()
 	value, ok := p.store.Get([]byte(name))
 	if !ok {
-		return domain.CatalogueRecord{}, false
+		return domain.CatalogueRecord{}, false, nil
 	}
 	record, err := decodeRecordValue(name, value)
-	return record, err == nil
+	if err != nil {
+		return domain.CatalogueRecord{}, false, err
+	}
+	return record, true, nil
 }
 func (p *Persister) Apply(records map[string]*domain.CatalogueRecord) error {
 	if p == nil {

M internal/persist/persist_test.go +22 -47

 package persist
 import (
-	"bytes"
 	"errors"
-	"log/slog"
 	"path/filepath"
 	"testing"
 	p := New(store)
 	one := validRecord("one", 1)
 	require.NoError(t, p.Replace("one", one))
+	require.Contains(t, state, "one")
 	renamed := one
 	renamed.Name = "renamed"
+	renamed.Cwd = "/renamed"
 	require.NoError(t, p.Rename("one", renamed))
+	require.NotContains(t, state, "one")
+	encoded, ok := state["renamed"]
+	require.True(t, ok)
+	got, err := decodeRecordValue("renamed", encoded)
+	require.NoError(t, err)
+	require.Equal(t, renamed, got)
 }
 func TestCatalogueBatchFailureDoesNotSync(t *testing.T) {
 	require.NoError(t, err)
 	require.Empty(t, records)
 	require.NoError(t, p.Close())
-	require.Empty(t, p.Records())
+	got, err := p.Records()
+	require.NoError(t, err)
+	require.Empty(t, got)
 }
 // TestCatalogueUnavailableStoreErrors covers a non-nil Persister with no
 	records, err := p.LoadAll()
 	require.ErrorIs(t, err, errPersistenceUnavailable)
 	require.Empty(t, records)
-	require.Empty(t, p.Records())
+	got, err := p.Records()
+	require.ErrorIs(t, err, errPersistenceUnavailable)
+	require.Empty(t, got)
 	require.NoError(t, p.Close())
 }
-// TestCatalogueRecordsMakesLoadFailureObservable covers Records(), which
+func TestCatalogueRecordsPropagatesMalformedRecord(t *testing.T) {
-// ports.Catalogue.Records() gives no error return for: a load failure must
+	store := portsmocks.NewMockStore(t)
-// not silently look like an empty catalogue to every caller. Records()
+	store.EXPECT().Range(mock.Anything).Run(func(fn func([]byte, []byte) bool) {
-// degrades to an empty slice but must emit the underlying error through its
+		fn([]byte("bad"), []byte{0, 1})
-// (nil-safe, optional) logger rather than swallowing it outright.
+	})
-func TestCatalogueRecordsMakesLoadFailureObservable(t *testing.T) {
+	records, err := New(store).Records()
-	tests := []struct {
+	require.Error(t, err)
-		name  string
+	require.Empty(t, records)
-		build func(t *testing.T, log *slog.Logger) *Persister
-	}{
-		{
-			name: "unavailable-store",
-			build: func(t *testing.T, log *slog.Logger) *Persister {
-				return New(nil, WithLogger(log))
-			},
-		},
-		{
-			name: "malformed-record",
-			build: func(t *testing.T, log *slog.Logger) *Persister {
-				store := portsmocks.NewMockStore(t)
-				store.EXPECT().Range(mock.Anything).Run(func(fn func([]byte, []byte) bool) {
-					fn([]byte("bad"), []byte{0, 1})
-				})
-				return New(store, WithLogger(log))
-			},
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			var buf bytes.Buffer
-			p := tt.build(t, slog.New(slog.NewTextHandler(&buf, nil)))
-			require.Empty(t, p.Records())
-			require.Contains(t, buf.String(), "loading catalogue records failed")
-		})
-	}
-}
-// TestCatalogueRecordsDefaultsToSlogDefaultLogger covers the nil-safe logger
-// fallback: a Persister built without WithLogger must not panic when a load
-// failure needs to be reported.
-func TestCatalogueRecordsDefaultsToSlogDefaultLogger(t *testing.T) {
-	p := New(nil)
-	require.NotPanics(t, func() { require.Empty(t, p.Records()) })
 }

M internal/persist/record.go +6 -4

 	buf = append(buf, catalogueMagic[:]...)
 	buf = binary.BigEndian.AppendUint16(buf, catalogueRecordVersion)
 	buf = append(buf, record.IncarnationID[:]...)
-	buf = appendString(buf, record.Cwd)
+	var err error
+	buf, err = appendCheckedString(buf, record.Cwd)
+	if err != nil {
+		return nil, err
+	}
 	buf = binary.BigEndian.AppendUint64(buf, uint64(record.CreatedAt))
 	buf = binary.BigEndian.AppendUint64(buf, uint64(record.UpdatedAt))
 	buf = binary.BigEndian.AppendUint64(buf, record.LastUsedSeq)
 	}
 	buf = binary.BigEndian.AppendUint32(buf, uint32(len(record.TabNames)))
 	for _, name := range record.TabNames {
-		var err error
 		buf, err = appendCheckedString(buf, name)
 		if err != nil {
 			return nil, err
 	buf = appendRef(buf, record.Committed)
 	buf = appendRef(buf, record.Fallbacks[0])
 	buf = appendRef(buf, record.Fallbacks[1])
-	var err error
 	buf, err = appendCheckedString(buf, record.DegradedReason)
 	return buf, err
 }
 		return domain.CatalogueRecord{}, errMalformedRecord
 	}
 	if err := record.Validate(); err != nil {
-		return domain.CatalogueRecord{}, fmt.Errorf("%w: %v", errMalformedRecord, err)
+		return domain.CatalogueRecord{}, errors.Join(errMalformedRecord, fmt.Errorf("persist: invalid catalogue record: %w", err))
 	}
 	return record, nil
 }

M internal/ports/mocks/recovery_mock.go +26 -11

 }
 // Record provides a mock function for the type MockCatalogue
-func (_mock *MockCatalogue) Record(s string) (domain.CatalogueRecord, bool) {
+func (_mock *MockCatalogue) Record(s string) (domain.CatalogueRecord, bool, error) {
 	ret := _mock.Called(s)
 	if len(ret) == 0 {
 	var r0 domain.CatalogueRecord
 	var r1 bool
-	if returnFunc, ok := ret.Get(0).(func(string) (domain.CatalogueRecord, bool)); ok {
+	var r2 error
+	if returnFunc, ok := ret.Get(0).(func(string) (domain.CatalogueRecord, bool, error)); ok {
 		return returnFunc(s)
 	}
 	if returnFunc, ok := ret.Get(0).(func(string) domain.CatalogueRecord); ok {
 	} else {
 		r1 = ret.Get(1).(bool)
 	}
-	return r0, r1
+	if returnFunc, ok := ret.Get(2).(func(string) error); ok {
+		r2 = returnFunc(s)
+	} else {
+		r2 = ret.Error(2)
+	}
+	return r0, r1, r2
 }
 // MockCatalogue_Record_Call is a *mock.Call that shadows Run/Return methods with type explicit version for method 'Record'
 	return _c
 }
-func (_c *MockCatalogue_Record_Call) Return(catalogueRecord domain.CatalogueRecord, b bool) *MockCatalogue_Record_Call {
+func (_c *MockCatalogue_Record_Call) Return(catalogueRecord domain.CatalogueRecord, b bool, err error) *MockCatalogue_Record_Call {
-	_c.Call.Return(catalogueRecord, b)
+	_c.Call.Return(catalogueRecord, b, err)
 	return _c
 }
-func (_c *MockCatalogue_Record_Call) RunAndReturn(run func(s string) (domain.CatalogueRecord, bool)) *MockCatalogue_Record_Call {
+func (_c *MockCatalogue_Record_Call) RunAndReturn(run func(s string) (domain.CatalogueRecord, bool, error)) *MockCatalogue_Record_Call {
 	_c.Call.Return(run)
 	return _c
 }
 // Records provides a mock function for the type MockCatalogue
-func (_mock *MockCatalogue) Records() []domain.CatalogueRecord {
+func (_mock *MockCatalogue) Records() ([]domain.CatalogueRecord, error) {
 	ret := _mock.Called()
 	if len(ret) == 0 {
 	}
 	var r0 []domain.CatalogueRecord
+	var r1 error
+	if returnFunc, ok := ret.Get(0).(func() ([]domain.CatalogueRecord, error)); ok {
+		return returnFunc()
+	}
 	if returnFunc, ok := ret.Get(0).(func() []domain.CatalogueRecord); ok {
 		r0 = returnFunc()
 	} else {
 			r0 = ret.Get(0).([]domain.CatalogueRecord)
 		}
 	}
-	return r0
+	if returnFunc, ok := ret.Get(1).(func() error); ok {
+		r1 = returnFunc()
+	} else {
+		r1 = ret.Error(1)
+	}
+	return r0, r1
 }
 // MockCatalogue_Records_Call is a *mock.Call that shadows Run/Return methods with type explicit version for method 'Records'
 	return _c
 }
-func (_c *MockCatalogue_Records_Call) Return(catalogueRecords []domain.CatalogueRecord) *MockCatalogue_Records_Call {
+func (_c *MockCatalogue_Records_Call) Return(catalogueRecords []domain.CatalogueRecord, err error) *MockCatalogue_Records_Call {
-	_c.Call.Return(catalogueRecords)
+	_c.Call.Return(catalogueRecords, err)
 	return _c
 }
-func (_c *MockCatalogue_Records_Call) RunAndReturn(run func() []domain.CatalogueRecord) *MockCatalogue_Records_Call {
+func (_c *MockCatalogue_Records_Call) RunAndReturn(run func() ([]domain.CatalogueRecord, error)) *MockCatalogue_Records_Call {
 	_c.Call.Return(run)
 	return _c
 }

M internal/ports/recovery.go +2 -2


@@ -157,8 +157,8 @@ type DegradedRecoveryCoordinator interface {
157		}	157		}
158			158
159		type Catalogue interface {	159		type Catalogue interface {
160	-	Records() []domain.CatalogueRecord	160	+	Records() ([]domain.CatalogueRecord, error)
161	-	Record(string) (domain.CatalogueRecord, bool)	161	+	Record(string) (domain.CatalogueRecord, bool, error)
162		Create(domain.CatalogueRecord) error	162		Create(domain.CatalogueRecord) error
163		UpdateMetadata(domain.CatalogueMetadataUpdate) error	163		UpdateMetadata(domain.CatalogueMetadataUpdate) error
164		Replace(string, domain.CatalogueRecord) error	164		Replace(string, domain.CatalogueRecord) error

M internal/ports/store.go +5 -0


@@ -21,6 +21,11 @@ type Store interface {
21	Get(key []byte) ([]byte, bool)	21		Get(key []byte) ([]byte, bool)
22	Set(key, val []byte) error	22		Set(key, val []byte) error
23	Delete(key []byte) error	23		Delete(key []byte) error
		24	+	// Batch applies all changes atomically to in-memory state: an error leaves
		25	+	// every prior value unchanged. Implementations repair or discard any torn
		26	+	// WAL batch during replay so no partial batch becomes visible after restart.
		27	+	// Batch does not retain StoreChange key or value slices; the caller owns and
		28	+	// may mutate them after Batch returns.
24	Batch([]StoreChange) error	29		Batch([]StoreChange) error
25	// Range iterates key/value pairs; fn returning false stops iteration early.	30		// Range iterates key/value pairs; fn returning false stops iteration early.
26	// Each key and value is a stable copy owned by the caller, which may retain	31		// Each key and value is a stable copy owned by the caller, which may retain

M internal/ports/wire_test.go +21 -6


@@ -744,12 +744,27 @@ func TestKillGoldenAndRoundTrip(t *testing.T) {
744		}	744		}
745			745
746		func TestSessionInfoRecoveryState(t *testing.T) {	746		func TestSessionInfoRecoveryState(t *testing.T) {
747	-	payload := MarshalSessions(Sessions{Sessions: []SessionInfo{{Name: "broken", State: SessionDegraded}}})	747	+	tests := []struct {
748	-	got, err := UnmarshalSessions(payload)	748	+	name string
749	-	require.NoError(t, err)	749	+	state SessionState
750	-	require.Equal(t, SessionDegraded, got.Sessions[0].State)	750	+	want []byte
751	-	assertAllPrefixesFail(t, payload, UnmarshalSessions)	751	+	}{
752	-	assertTrailingGarbageFails(t, payload, UnmarshalSessions)	752	+	{name: "running", state: SessionRunning, want: []byte{0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 1}},
			753	+	{name: "stopped", state: SessionStopped, want: []byte{0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 2}},
			754	+	{name: "restoring", state: SessionRestoring, want: []byte{0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 3}},
			755	+	{name: "degraded", state: SessionDegraded, want: []byte{0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 4}},
			756	+	}
			757	+	for _, tt := range tests {
			758	+	t.Run(tt.name, func(t *testing.T) {
			759	+	payload := MarshalSessions(Sessions{Sessions: []SessionInfo{{State: tt.state}}})
			760	+	require.Equal(t, tt.want, payload)
			761	+	got, err := UnmarshalSessions(payload)
			762	+	require.NoError(t, err)
			763	+	require.Equal(t, tt.state, got.Sessions[0].State)
			764	+	assertAllPrefixesFail(t, payload, UnmarshalSessions)
			765	+	assertTrailingGarbageFails(t, payload, UnmarshalSessions)
			766	+	})
			767	+	}
753		}	768		}
754			769
755		func TestSessionsGoldenAndRoundTrip(t *testing.T) {	770		func TestSessionsGoldenAndRoundTrip(t *testing.T) {

M internal/usecase/command/command.go +12 -3

 // ErrInvalidArguments reports arguments that do not have the exact command format.
 var ErrInvalidArguments = errors.New("invalid command arguments")
-// ParsePositiveDecimal accepts exactly one base-10 positive decimal value.
+// ParsePositiveUint64 accepts exactly one base-10 positive decimal value.
 // It deliberately rejects signs, whitespace, zero, and non-canonical forms.
-func ParsePositiveDecimal(args []string) (int, error) {
+func ParsePositiveUint64(args []string) (uint64, error) {
 	if len(args) != 1 || args[0] == "" || (len(args[0]) > 1 && args[0][0] == '0') {
 		return 0, ErrInvalidArguments
 	}
 			return 0, ErrInvalidArguments
 		}
 	}
-	n, err := strconv.Atoi(args[0])
+	n, err := strconv.ParseUint(args[0], 10, 64)
 	if err != nil || n < 1 {
 		return 0, ErrInvalidArguments
 	}
 	return n, nil
 }
+// ParsePositiveDecimal parses a positive decimal that must fit the platform int.
+func ParsePositiveDecimal(args []string) (int, error) {
+	n, err := ParsePositiveUint64(args)
+	if err != nil || n > uint64(^uint(0)>>1) {
+		return 0, ErrInvalidArguments
+	}
+	return int(n), nil
+}
 // Context is the set of application actions available to commands.
 type Context interface {
 	CreateTab() error

M internal/usecase/command/command_test.go +11 -0


@@ -5,6 +5,17 @@ import (
5	"testing"	5		"testing"
6	)	6		)
7		7
		8	+	func TestParsePositiveUint64(t *testing.T) {
		9	+	const maxUint64 = "18446744073709551615"
		10	+	got, err := ParsePositiveUint64([]string{maxUint64})
		11	+	if err != nil \|\| got != ^uint64(0) {
		12	+	t.Fatalf("ParsePositiveUint64(max) = %d, %v", got, err)
		13	+	}
		14	+	if _, err := ParsePositiveUint64([]string{"18446744073709551616"}); !errors.Is(err, ErrInvalidArguments) {
		15	+	t.Fatalf("ParsePositiveUint64(overflow) error = %v", err)
		16	+	}
		17	+	}
		18	+
8	func TestParsePositiveDecimal(t *testing.T) {	19		func TestParsePositiveDecimal(t *testing.T) {
9	for _, tt := range []struct {	20		for _, tt := range []struct {
10	name string	21		name string

M internal/usecase/command/registry.go +6 -3

 package command
-import "strings"
+import (
+	"path/filepath"
+	"strings"
+)
 // Registry returns all palette and control commands in stable display order.
 func Registry() []Command {
 			case len(args) == 1 && (args[0] == "retry" || args[0] == "discard"):
 				action = args[0]
 			case len(args) == 2 && args[0] == "restore":
-				if _, err := ParsePositiveDecimal(args[1:]); err != nil {
+				if _, err := ParsePositiveUint64(args[1:]); err != nil {
 					return ControlResult{}, ErrInvalidArguments
 				}
 				action, argument = args[0], args[1]
-			case len(args) == 2 && args[0] == "export" && args[1] != "":
+			case len(args) == 2 && args[0] == "export" && filepath.IsAbs(args[1]):
 				action, argument = args[0], args[1]
 			default:
 				return ControlResult{}, ErrInvalidArguments

M internal/usecase/command/registry_test.go +22 -6

 	}{
 		{args: []string{"retry"}, wantCall: "session-recovery:retry:"},
 		{args: []string{"restore", "7"}, wantCall: "session-recovery:restore:7"},
+		{args: []string{"restore", "18446744073709551615"}, wantCall: "session-recovery:restore:18446744073709551615"},
 		{args: []string{"export", "/tmp/export"}, wantCall: "session-recovery:export:/tmp/export"},
 		{args: []string{"discard"}, wantCall: "session-recovery:discard:"},
+		{args: nil, wantErr: ErrInvalidArguments},
+		{args: []string{"retry", "extra"}, wantErr: ErrInvalidArguments},
+		{args: []string{"restore"}, wantErr: ErrInvalidArguments},
 		{args: []string{"restore", "0"}, wantErr: ErrInvalidArguments},
+		{args: []string{"restore", "01"}, wantErr: ErrInvalidArguments},
+		{args: []string{"restore", "18446744073709551616"}, wantErr: ErrInvalidArguments},
+		{args: []string{"export", "relative/path"}, wantErr: ErrInvalidArguments},
+		{args: []string{"export"}, wantErr: ErrInvalidArguments},
+		{args: []string{"discard", "extra"}, wantErr: ErrInvalidArguments},
 		{args: []string{"unknown"}, wantErr: ErrInvalidArguments},
 	}
 	for _, test := range tests {
-		ctx := &controlSpy{}
+		ctx := &controlSpy{recoveryOutput: "recovery output"}
-		_, err := cmd.Control(ctx, test.args, ControlOptions{})
+		got, err := cmd.Control(ctx, test.args, ControlOptions{})
-		if !errors.Is(err, test.wantErr) || ctx.call != test.wantCall {
+		wantOutput := ""
-			t.Errorf("args %v: call/error = %q/%v, want %q/%v", test.args, ctx.call, err, test.wantCall, test.wantErr)
+		if test.wantCall != "" {
+			wantOutput = ctx.recoveryOutput
+		}
+		if !errors.Is(err, test.wantErr) || ctx.call != test.wantCall || got.Output != wantOutput {
+			t.Errorf("args %v: call/output/error = %q/%q/%v, want %q/%q/%v", test.args, ctx.call, got.Output, err, test.wantCall, wantOutput, test.wantErr)
 		}
 	}
 }
 	}
 }
-type controlSpy struct{ call string }
+type controlSpy struct {
+	call           string
+	recoveryOutput string
+}
 func (s *controlSpy) record(call string) error          { s.call = call; return nil }
 func (s *controlSpy) CreateTab() error                  { return s.record("new-tab") }
 	return s.record("toast:" + level + ":" + message)
 }
 func (s *controlSpy) SessionRecovery(action, argument string) (string, error) {
-	return "", s.record("session-recovery:" + action + ":" + argument)
+	return s.recoveryOutput, s.record("session-recovery:" + action + ":" + argument)
 }
 func (s *controlSpy) ListSessions(json bool) (string, error) {
 	_ = s.record("list-sessions:" + strconv.FormatBool(json))

M internal/usecase/daemon/catalogue.go +56 -11


@@ -7,30 +7,75 @@ import (
7		// Catalogue helpers keep persistence optional for ephemeral and focused unit	7		// Catalogue helpers keep persistence optional for ephemeral and focused unit
8		// tests while ensuring every durable named-session mutation uses the authority	8		// tests while ensuring every durable named-session mutation uses the authority
9		// port when one is configured.	9		// port when one is configured.
10	-	func (d *Daemon) catalogueRecord(name string) (domain.CatalogueRecord, bool) {	10	+	func (d *Daemon) catalogueRecord(name string) (domain.CatalogueRecord, bool, error) {
11		if d == nil \|\| d.catalogue == nil {	11		if d == nil \|\| d.catalogue == nil {
12	-	return domain.CatalogueRecord{}, false	12	+	return domain.CatalogueRecord{}, false, nil
13		}	13		}
14		return d.catalogue.Record(name)	14		return d.catalogue.Record(name)
15		}	15		}
16			16
17	-	func (d *Daemon) createCatalogueRecord(record domain.CatalogueRecord) error {	17	+	func (d *Daemon) updateCatalogueMetadata(update domain.CatalogueMetadataUpdate) error {
18		if d == nil \|\| d.catalogue == nil {	18		if d == nil \|\| d.catalogue == nil {
19		return nil	19		return nil
20		}	20		}
21	-	return d.catalogue.Create(record)	21	+	return d.catalogue.UpdateMetadata(update)
22		}	22		}
23			23
24	-	func (d *Daemon) updateCatalogueMetadata(update domain.CatalogueMetadataUpdate) error {	24	+	// persistSessionMetadata serializes authority writes without holding daemon or
25	-	if d == nil \|\| d.catalogue == nil {	25	+	// session state locks during I/O. Only a successfully committed newer revision
			26	+	// subsumes an older caller. Failed revisions retain their rollback until later
			27	+	// failed mutations have unwound, keeping live metadata at the durable boundary.
			28	+	func (d Daemon) persistSessionMetadata(sess session, version uint64, update domain.CatalogueMetadataUpdate, rollback func() bool) error {
			29	+	if sess == nil {
26		return nil	30		return nil
27		}	31		}
28	-	return d.catalogue.UpdateMetadata(update)	32	+	sess.metadataPersistMu.Lock()
29	-	}	33	+	defer sess.metadataPersistMu.Unlock()
30			34
31	-	func (d *Daemon) deleteCatalogueRecord(name string) error {	35	+	if sess.metadataDurableVersion >= version {
32	-	if d == nil \|\| d.catalogue == nil {
33		return nil	36		return nil
34		}	37		}
35	-	return d.catalogue.Delete(name)	38	+	if err := d.updateCatalogueMetadata(update); err != nil {
			39	+	if sess.metadataFailedRollbacks == nil {
			40	+	sess.metadataFailedRollbacks = make(map[uint64]func() bool)
			41	+	}
			42	+	sess.metadataFailedRollbacks[version] = rollback
			43	+	// A later mutation may have been reserved while authority I/O blocked.
			44	+	// It must settle before an older failed mutation can be unwound.
			45	+	sess.mu.Lock()
			46	+	current := sess.metadataVersion
			47	+	sess.mu.Unlock()
			48	+	if current > sess.metadataLiveVersion {
			49	+	sess.metadataLiveVersion = current
			50	+	}
			51	+	sess.reconcileFailedMetadataLocked()
			52	+	return err
			53	+	}
			54	+
			55	+	sess.metadataDurableVersion = version
			56	+	for failedVersion := range sess.metadataFailedRollbacks {
			57	+	if failedVersion <= version {
			58	+	delete(sess.metadataFailedRollbacks, failedVersion)
			59	+	}
			60	+	}
			61	+	return nil
			62	+	}
			63	+
			64	+	// reconcileFailedMetadataLocked unwinds only a contiguous failed suffix. An
			65	+	// older failure remains pending while a newer mutation is still writing.
			66	+	// Rollbacks run only after authority I/O has returned and acquire state locks in
			67	+	// the daemon-before-session order.
			68	+	func (s *session) reconcileFailedMetadataLocked() {
			69	+	for s.metadataLiveVersion > s.metadataDurableVersion {
			70	+	version := s.metadataLiveVersion
			71	+	rollback, failed := s.metadataFailedRollbacks[version]
			72	+	if !failed {
			73	+	return
			74	+	}
			75	+	if rollback != nil && !rollback() {
			76	+	return
			77	+	}
			78	+	delete(s.metadataFailedRollbacks, version)
			79	+	s.metadataLiveVersion--
			80	+	}
36		}	81		}

M internal/usecase/daemon/control.go +37 -22

 	"errors"
 	"fmt"
 	"os"
+	"path/filepath"
+	"slices"
 	"sort"
 	"strconv"
 	"strings"
 		_ = tr.Send(frameCommandResult(ports.CommandResult{Code: ports.ErrInternal, Text: "malformed command request"}))
 		return
 	}
-	_ = tr.Send(frameCommandResult(d.dispatchCommand(request)))
+	_ = tr.Send(frameCommandResult(d.dispatchCommand(d.serveCtx, request)))
 }
 func frameCommandResult(result ports.CommandResult) ports.Frame {
 	return ports.Frame{Type: ports.MsgCommandResult, Payload: ports.MarshalCommandResult(result)}
 }
-func (d *Daemon) dispatchCommand(request ports.CommandRequest) ports.CommandResult {
+func (d *Daemon) dispatchCommand(ctx context.Context, request ports.CommandRequest) ports.CommandResult {
 	cmd, ok := command.BySlug(request.Slug)
 	if !ok {
 		return commandFailure(ports.ErrUnknownCommand, "unknown command: "+request.Slug)
 		return commandFailure(ports.ErrNotScriptable, request.Slug+" requires an attached client")
 	}
 	if cmd.Target == command.TargetNone && !request.Self {
-		return d.runControl(cmd, controlExec{d: d, recoveryName: request.TargetSession}, request)
+		return d.runControl(cmd, controlExec{ctx: ctx, d: d, recoveryName: request.TargetSession}, request)
 	}
 	sess, code, text := d.resolveTargetSession(request)
 	if code != 0 {
 		return commandFailure(code, text)
 	}
-	return d.runControl(cmd, controlExec{d: d, sess: sess, tab: tb, target: daemonActionTarget{session: sess, tab: tb, pane: pane}}, request)
+	return d.runControl(cmd, controlExec{ctx: ctx, d: d, sess: sess, tab: tb, target: daemonActionTarget{session: sess, tab: tb, pane: pane}}, request)
 }
 func (d *Daemon) runControl(cmd command.Command, exec controlExec, request ports.CommandRequest) ports.CommandResult {
 	}
 	target.session.mu.Lock()
 	defer target.session.mu.Unlock()
-	foundTab := false
+	if !slices.Contains(target.session.tabs, target.tab) {
-	for _, tb := range target.session.tabs {
-		if tb == target.tab {
-			foundTab = true
-			break
-		}
-	}
-	if !foundTab {
 		return false
 	}
 	target.tab.mu.Lock()
 // controlExec implements command.ControlContext against resolved daemon-owned
 // targets. It deliberately contains no attached-client state.
 type controlExec struct {
+	ctx          context.Context
 	d            *Daemon
 	sess         *session
 	tab          *tab
 	if e.d == nil || e.d.degradedRecovery == nil || e.recoveryName == "" {
 		return "", command.ErrInvalidArguments
 	}
-	ctx := context.Background()
+	ctx := e.ctx
+	if ctx == nil {
+		ctx = e.d.serveCtx
+	}
 	switch action {
 	case "retry":
 		if err := e.d.degradedRecovery.Retry(ctx, e.recoveryName); err != nil {
 		if err != nil || generation == 0 {
 			return "", command.ErrInvalidArguments
 		}
-		record, ok := e.d.catalogue.Record(e.recoveryName)
+		record, ok, err := e.d.catalogue.Record(e.recoveryName)
+		if err != nil {
+			return "", err
+		}
 		if !ok {
 			return "", errors.New("session recovery record not found")
 		}
 		}
 		return "", errors.New("requested recovery fallback is not available")
 	case "export":
+		if !filepath.IsAbs(argument) {
+			return "", command.ErrInvalidArguments
+		}
 		file, err := os.OpenFile(argument, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
 		if err != nil {
 			return "", err
 	if e.d.catalogue == nil {
 		return errors.New("durable session catalogue unavailable")
 	}
-	record, ok := e.d.catalogue.Record(e.recoveryName)
+	record, ok, err := e.d.catalogue.Record(e.recoveryName)
+	if err != nil {
+		return err
+	}
 	if !ok {
 		return errors.New("session recovery record not found")
 	}
 	done := make(chan struct{})
 	e.d.mu.Lock()
-	if entry, exists := e.d.stopped[record.Name]; exists {
+	entry, exists := e.d.stopped[record.Name]
-		entry.record = record
+	if !exists || entry.incarnation != record.IncarnationID {
-		entry.state = runtimeRestoring
+		e.d.mu.Unlock()
-		entry.restoreDone = done
+		return errors.New("session recovery runtime record not found")
-		e.d.stopped[record.Name] = entry
+	}
-	}
+	if entry.purging || entry.state != runtimeDegraded {
+		e.d.mu.Unlock()
+		return errors.New("session recovery is not available in the current state")
+	}
+	entry.record = record
+	entry.state = runtimeRestoring
+	entry.restoreDone = done
+	e.d.stopped[record.Name] = entry
 	e.d.mu.Unlock()
-	err := e.d.restoreRecord(ctx, record)
+	err = e.d.restoreRecord(ctx, record)
 	e.d.finishRecordRestore(record, err, done)
 	return err
 }

M internal/usecase/daemon/daemon.go +72 -70

 	"log/slog"
 	"math"
 	"os"
+	"reflect"
 	"sort"
 	"sync"
 	"sync/atomic"
 	"time"
 	"github.com/bnema/vev/internal/domain"
-	"github.com/bnema/vev/internal/persist"
 	"github.com/bnema/vev/internal/ports"
 	"github.com/bnema/vev/internal/usecase/keys"
 )
 	mu       sync.Mutex
 	sessions map[domain.SessionID]*session
 	stopped  map[string]stoppedSession
+	// creating reserves names while durable creation I/O runs without mu.
+	creating map[string]struct{}
 	nextID   uint64
 	// lastAllocatedCreatedAt is the named-session lifecycle timestamp high-water
 	// mark. It is guarded by mu and prevents a wall-clock regression from
 	shell                          string
 	shellArgs                      []string
 	shellOverride                  bool
-	persist                        *persist.Persister
 	persistEnabled                 bool
 	catalogue                      ports.Catalogue
 	catalogueRecords               []domain.CatalogueRecord
 	catalogueRecordsProvided       bool
-	// snapshotRepository is the sole checkpoint contract. legacySnapshots is
+	// snapshotRepository is the sole checkpoint contract.
-	// read-only migration input and is never used for new writes.
 	snapshotRepository      ports.SnapshotRepository
 	checkpointRecovery      ports.CheckpointCoordinator
 	lifecycleRecovery       ports.SessionLifecycleCoordinator
 	// records, so it is a durable writer and is guarded by snapshotWorkerMu with
 	// the other two.
 	restoreWorkerDone chan struct{}
-	legacySnapshots   ports.LegacySnapshotSource
 	snapsEnabled      bool
 	noticeStore       ports.NoticeStore
 	snapshotJobs      chan *snapshotCapture
+	// snapshotAdmitted contains every capture accepted by either worker queue,
+	// including captures buffered in snapshotJobs. Guarded by snapshotWorkerMu.
+	snapshotAdmitted map[*snapshotCapture]struct{}
 	// snapshotWake wakes the repository scheduler when a session becomes dirty
 	// or an attempt completes. It is never closed and producers only send
 	// non-blockingly.
 	}
 }
-// WithStore enables persisted named session metadata. A nil store keeps the
-// daemon in no-op persistence mode.
-func WithStore(store ports.Store) Option {
-	return func(d *Daemon) {
-		d.persist = persist.New(store)
-		d.catalogue = d.persist
-		d.persistEnabled = store != nil
-	}
-}
 // WithCatalogue installs the singular catalogue and the strictly opened
 // records that define the daemon's expected-session registry at startup.
 func WithCatalogue(catalogue ports.Catalogue, records []domain.CatalogueRecord) Option {
 	}
 }
-// WithSnapshotRepository enables content-addressed incremental snapshots. The
+// WithSnapshotRepository enables content-addressed incremental snapshots.
-// legacy source is read-only migration input and is never used for new writes.
+func WithSnapshotRepository(repository ports.SnapshotRepository) Option {
-func WithSnapshotRepository(repository any, legacy ports.LegacySnapshotSource) Option {
 	return func(d *Daemon) {
-		if repository == nil {
+		if isNilSnapshotRepository(repository) {
 			return
 		}
-		typed, ok := repository.(ports.SnapshotRepository)
+		d.snapshotRepository = repository
-		if !ok {
-			// Pre-incarnation test repositories are intentionally not admitted to
-			// normal runtime paths. They remain accepted by this option only so
-			// package-level legacy tests can exercise their isolated helpers.
-			return
-		}
-		d.snapshotRepository = typed
-		d.legacySnapshots = legacy
 		d.snapsEnabled = true
 	}
 }
+func isNilSnapshotRepository(repository ports.SnapshotRepository) bool {
+	if repository == nil {
+		return true
+	}
+	value := reflect.ValueOf(repository)
+	switch value.Kind() {
+	case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice:
+		return value.IsNil()
+	default:
+		return false
+	}
+}
 // WithNoticeStore enables persisting undeliverable notices across daemon
 // restarts. A nil store keeps the daemon in no-op notice-persistence mode.
 func WithNoticeStore(store ports.NoticeStore) Option {
 }
 func (d *Daemon) nowUnixNano() int64 {
+	if d == nil || d.clock == nil {
+		return time.Now().UnixNano()
+	}
 	return d.clock.Now().UnixNano()
 }
 		shell = "/bin/sh"
 	}
 	d := &Daemon{
-		sessions:        make(map[domain.SessionID]*session),
+		sessions:         make(map[domain.SessionID]*session),
-		stopped:         make(map[string]stoppedSession),
+		stopped:          make(map[string]stoppedSession),
-		parked:          make(map[uint64]*parkedAttachment),
+		creating:         make(map[string]struct{}),
-		ptys:            ptys,
+		parked:           make(map[uint64]*parkedAttachment),
-		clock:           clock,
+		ptys:             ptys,
-		log:             log,
+		clock:            clock,
-		baseEnv:         os.Environ(),
+		log:              log,
-		shell:           shell,
+		baseEnv:          os.Environ(),
-		persist:         persist.New(nil),
+		shell:            shell,
-		dirOrHome:       dirOrHome,
+		dirOrHome:        dirOrHome,
-		done:            make(chan struct{}),
+		done:             make(chan struct{}),
-		restoreDone:     make(chan struct{}),
+		restoreDone:      make(chan struct{}),
-		animWake:        make(chan struct{}, 1),
+		animWake:         make(chan struct{}, 1),
-		snapshotJobs:    make(chan *snapshotCapture, snapshotQueueCapacity),
+		snapshotJobs:     make(chan *snapshotCapture, snapshotQueueCapacity),
-		snapshotWake:    make(chan struct{}, 1),
+		snapshotAdmitted: make(map[*snapshotCapture]struct{}),
-		notices:         newNoticeCenter(),
+		snapshotWake:     make(chan struct{}, 1),
-		resumeParkGrace: defaultResumeParkGrace,
+		notices:          newNoticeCenter(),
+		resumeParkGrace:  defaultResumeParkGrace,
 		barScripts: &barScriptState{
 			cfg:         barConfigFromDomain(domain.Defaults().Bar),
 			outputs:     make(map[domain.SessionID]barScriptOutputs),
 	for _, o := range opts {
 		o(d)
 	}
-	if d.persist == nil {
-		d.persist = persist.New(nil)
-	}
 	if d.dirOrHome == nil {
 		d.dirOrHome = dirOrHome
 	}
 		d.restoreProcessAllowlist.Store(&allow)
 	}
 	records := d.catalogueRecords
-	// Only attempt the load when persistence is actually configured
-	// (d.persistEnabled tracks the same store-is-non-nil condition
-	// persist.Persister uses to distinguish "no store" from "load failed").
-	// Without this gate, the default no-persistence Daemon (persist.New(nil))
-	// would log a false-alarm "loading persisted sessions failed" warning on
-	// every construction: nothing failed, persistence simply isn't enabled.
-	if !d.catalogueRecordsProvided && d.persistEnabled {
-		var err error
-		records, err = d.persist.LoadAll()
-		if err != nil {
-			d.log.Warn("loading persisted sessions failed", "err", err)
-			return d
-		}
-	}
 	var maxSeq uint64
 	var maxCreatedAt int64
 	hasCreatedAt := false
 	var closeErr error
 	if d.catalogue != nil {
 		closeErr = d.catalogue.Close()
-	} else {
-		closeErr = d.persist.Close()
 	}
 	if closeErr != nil {
 		d.log.Warn("closing session persister failed", "err", closeErr)
 	for _, s := range snapshot {
 		// Cancellation and PTY closure must not wait behind a teardown owner that
 		// is blocked in snapshot publication or purge work.
+		s.mu.Lock()
+		name := s.name
+		ephemeral := s.ephemeral
+		s.mu.Unlock()
 		s.stopInMemoryLifecycle()
 		if err := d.killSessionWithSnapshotDeadline(s, reason, false, deadline); err != nil {
 			checkpointIncomplete = true
 			d.log.Error("closing session with unpersisted terminal state", "err", err)
 		}
+		if !ephemeral && deadline != nil {
+			select {
+			case <-deadline.Done():
+				checkpointIncomplete = true
+				d.persistShutdownSnapshotFailure(name, context.DeadlineExceeded)
+			default:
+			}
+		}
 	}
 	return checkpointIncomplete
 }
 	if deadline == nil {
 		return ctx, cancel
 	}
+	select {
+	case <-deadline.Done():
+		cancel()
+		return ctx, cancel
+	default:
+	}
 	stop := make(chan struct{})
 	go func() {
 		select {
 		}
 		state := ports.SessionStopped
 		if stopped.purging {
+			// Purge is the dominant externally visible state: restoration must
+			// never make a deletion-reserved record appear attachable.
 			state = ports.SessionDegraded
-		}
+		} else {
-		switch stopped.state {
+			switch stopped.state {
-		case runtimeRestoring:
+			case runtimeRestoring:
-			state = ports.SessionRestoring
+				state = ports.SessionRestoring
-		case runtimeDegraded, runtimeDeleting:
+			case runtimeDegraded, runtimeDeleting:
-			state = ports.SessionDegraded
+				state = ports.SessionDegraded
+			}
 		}
 		infos = append(infos, ports.SessionInfo{Name: name, State: state})
 	}

A internal/usecase/daemon/durable_authority_test.go +49 -0

@@ -0,0 +1,49 @@
	1	+	package daemon
	2	+
	3	+	import (
	4	+	"context"
	5	+	"crypto/rand"
	6	+
	7	+	"github.com/bnema/vev/internal/domain"
	8	+	"github.com/bnema/vev/internal/persist"
	9	+	"github.com/bnema/vev/internal/ports"
	10	+	recoveryusecase "github.com/bnema/vev/internal/usecase/recovery"
	11	+	)
	12	+
	13	+	type testLifecycleRepository struct{ ports.SnapshotRepository }
	14	+
	15	+	func (testLifecycleRepository) WriteDeletionTombstone(context.Context, domain.DeletionTombstone) error {
	16	+	return nil
	17	+	}
	18	+	func (testLifecycleRepository) QuarantineDeletionSources(context.Context, domain.DeletionTombstone, bool) error {
	19	+	return nil
	20	+	}
	21	+	func (testLifecycleRepository) DeleteDeletionTombstone(context.Context, domain.IncarnationID) error {
	22	+	return nil
	23	+	}
	24	+
	25	+	// WithStore is package-test composition glue. Production injects the same
	26	+	// recovery coordinator explicitly from internal/app.
	27	+	func WithStore(store ports.Store) Option {
	28	+	return func(d *Daemon) {
	29	+	if store == nil {
	30	+	return
	31	+	}
	32	+	catalogue := persist.New(store)
	33	+	records, err := catalogue.Records()
	34	+	if err != nil {
	35	+	return
	36	+	}
	37	+	d.catalogue = catalogue
	38	+	d.persistEnabled = true
	39	+	d.catalogueRecords = records
	40	+	d.catalogueRecordsProvided = true
	41	+	repository := d.snapshotRepository
	42	+	if repository == nil {
	43	+	repository = testLifecycleRepository{}
	44	+	}
	45	+	authority := recoveryusecase.NewCoordinator(catalogue, repository, nil, rand.Reader)
	46	+	d.lifecycleRecovery = authority
	47	+	d.checkpointRecovery = authority
	48	+	}
	49	+	}

M internal/usecase/daemon/durable_recovery_test.go +126 -24

 	"github.com/bnema/vev/internal/domain"
 	"github.com/bnema/vev/internal/ports"
+	portsmocks "github.com/bnema/vev/internal/ports/mocks"
+	"github.com/bnema/vev/internal/usecase/command"
 	recoveryusecase "github.com/bnema/vev/internal/usecase/recovery"
 	snapcodec "github.com/bnema/vev/internal/usecase/snapshot"
 )
 	return catalogue
 }
-func (c *durableRecoveryCatalogue) Records() []domain.CatalogueRecord {
+func (c *durableRecoveryCatalogue) Records() ([]domain.CatalogueRecord, error) {
 	c.mu.Lock()
 	defer c.mu.Unlock()
 	records := make([]domain.CatalogueRecord, 0, len(c.records))
 	for _, record := range c.records {
 		records = append(records, record)
 	}
-	return records
+	return records, nil
 }
-func (c *durableRecoveryCatalogue) Record(name string) (domain.CatalogueRecord, bool) {
+func (c *durableRecoveryCatalogue) Record(name string) (domain.CatalogueRecord, bool, error) {
 	c.mu.Lock()
 	defer c.mu.Unlock()
 	record, ok := c.records[name]
-	return record, ok
+	return record, ok, nil
+}
+func mustDurableRecords(t *testing.T, c *durableRecoveryCatalogue) []domain.CatalogueRecord {
+	t.Helper()
+	records, err := c.Records()
+	require.NoError(t, err)
+	return records
 }
 func (c *durableRecoveryCatalogue) Replace(name string, record domain.CatalogueRecord) error {
 func (r *durableRecoveryRepository) LoadCheckpoint(_ context.Context, id domain.IncarnationID, name string, ref ports.CheckpointRef) (ports.SnapshotGeneration, error) {
 	r.mu.Lock()
 	defer r.mu.Unlock()
+	if r.loads == nil {
+		r.loads = make(map[string]int)
+	}
 	r.loads[name]++
 	if err := r.errors[name]; err != nil {
 		return ports.SnapshotGeneration{}, err
 	if r.repairErr != nil {
 		return r.repairErr
 	}
+	if r.repairs == nil {
+		r.repairs = make(map[string]domain.CheckpointRef)
+	}
 	r.repairs[id.String()] = ref
 	return nil
 }
 	t.Helper()
 	catalogue := newDurableRecoveryCatalogue(records)
 	coordinator := recoveryusecase.NewCoordinator(catalogue, repository, nil, nil)
-	d := New(nil, stubClock{}, slog.New(slog.NewTextHandler(io.Discard, nil)), WithCatalogue(catalogue, records), WithSnapshotRepository(repository, nil), WithCheckpointCoordinator(coordinator))
+	d := New(nil, stubClock{}, slog.New(slog.NewTextHandler(io.Discard, nil)), WithCatalogue(catalogue, records), WithSnapshotRepository(repository), WithCheckpointCoordinator(coordinator))
 	d.serveCtx, d.serveCancel = context.WithCancel(context.Background())
 	t.Cleanup(d.serveCancel)
 	return d, catalogue
 	catalogue := newDurableRecoveryCatalogue([]domain.CatalogueRecord{prior})
 	repository := &durableRecoveryRepository{}
 	coordinator := recoveryusecase.NewCoordinator(catalogue, repository, nil, nil)
-	d := New(nil, stubClock{}, slog.New(slog.NewTextHandler(io.Discard, nil)), WithCatalogue(catalogue, []domain.CatalogueRecord{prior}), WithSnapshotRepository(repository, nil), WithCheckpointCoordinator(coordinator))
+	d := New(nil, stubClock{}, slog.New(slog.NewTextHandler(io.Discard, nil)), WithCatalogue(catalogue, []domain.CatalogueRecord{prior}), WithSnapshotRepository(repository), WithCheckpointCoordinator(coordinator))
 	startSnapshotEncodeWorker(t, d)
 	sess := newSnapshotTestSession(t, prior.Name, false, prior.Cwd)
 	require.True(t, d.scheduleFinalSnapshot(sess))
 	awaitSnapshotIdle(t, sess)
-	got, ok := catalogue.Record(prior.Name)
+	got, ok, _ := catalogue.Record(prior.Name)
 	require.True(t, ok)
 	require.Equal(t, prior, got, "a timed-out final checkpoint must not change authoritative bytes")
 	require.Equal(t, priorRef, *sess.snapshotPublishedCheckpoint)
 	emptyDaemon, emptyCatalogue := newDurableRecoveryDaemon(t, nil, &durableRecoveryRepository{})
 	emptyDone := make(chan struct{})
 	go func() {
-		emptyDaemon.restoreCatalogue(context.Background(), emptyCatalogue.Records())
+		emptyDaemon.restoreCatalogue(context.Background(), mustDurableRecords(t, emptyCatalogue))
 		close(emptyDone)
 	}()
 	select {
 	}
 	d, catalogue := newDurableRecoveryDaemon(t, []domain.CatalogueRecord{healthy, broken}, repository)
-	d.restoreCatalogue(context.Background(), catalogue.Records())
+	d.restoreCatalogue(context.Background(), mustDurableRecords(t, catalogue))
 	require.Equal(t, runtimeHealthy, d.stopped[healthy.Name].state)
 	require.Equal(t, runtimeDegraded, d.stopped[broken.Name].state)
 			t.Fatalf("restore completion for %q was not closed", name)
 		}
 	}
-	degraded, ok := catalogue.Record(broken.Name)
+	degraded, ok, _ := catalogue.Record(broken.Name)
 	require.True(t, ok)
 	require.Equal(t, domain.RecoveryDegraded, degraded.RecoveryState)
 	require.Equal(t, 1, repository.loads[healthy.Name])
 		repairs:     make(map[string]domain.CheckpointRef),
 	}
 	fallbackDaemon, fallbackCatalogue := newDurableRecoveryDaemon(t, []domain.CatalogueRecord{fallback}, fallbackRepository)
-	fallbackDaemon.restoreCatalogue(context.Background(), fallbackCatalogue.Records())
+	fallbackDaemon.restoreCatalogue(context.Background(), mustDurableRecords(t, fallbackCatalogue))
-	promoted, ok := fallbackCatalogue.Record(fallback.Name)
+	promoted, ok, _ := fallbackCatalogue.Record(fallback.Name)
 	require.True(t, ok)
 	require.Equal(t, fallbackRef, *promoted.Committed)
 	require.Equal(t, runtimeHealthy, fallbackDaemon.stopped[fallback.Name].state)
 	}
 	d, catalogue := newDurableRecoveryDaemon(t, []domain.CatalogueRecord{record}, repository)
-	d.restoreCatalogue(context.Background(), catalogue.Records())
+	d.restoreCatalogue(context.Background(), mustDurableRecords(t, catalogue))
-	committed, ok := catalogue.Record(record.Name)
+	committed, ok, _ := catalogue.Record(record.Name)
 	require.True(t, ok)
 	require.Equal(t, domain.RecoveryHealthy, committed.RecoveryState)
 	require.Equal(t, fallbackRef, *committed.Committed)
 	repository.repairErr = nil
 	next, _ := newDurableRecoveryDaemon(t, []domain.CatalogueRecord{committed}, repository)
-	next.restoreCatalogue(context.Background(), catalogue.Records())
+	next.restoreCatalogue(context.Background(), mustDurableRecords(t, catalogue))
 	require.Equal(t, runtimeHealthy, next.stopped[record.Name].state)
 	require.Equal(t, 2, repository.repairCalls, "the next startup retries the pending HEAD repair")
 	require.Equal(t, fallbackRef, repository.repairs[record.IncarnationID.String()])
 	}
 	d, catalogue := newDurableRecoveryDaemon(t, records, repository)
-	d.restoreCatalogue(context.Background(), catalogue.Records())
+	d.restoreCatalogue(context.Background(), mustDurableRecords(t, catalogue))
 	require.Len(t, d.stopped, count)
 	for _, record := range records {
 	// The repository may contain any number of stale entries; restoration has no
 	// discovery API and therefore performs exactly one direct catalogue lookup.
-	d.restoreCatalogue(context.Background(), catalogue.Records())
+	d.restoreCatalogue(context.Background(), mustDurableRecords(t, catalogue))
 	require.Equal(t, runtimeHealthy, d.stopped[record.Name].state)
 	require.Equal(t, 1, repository.loads[record.Name])
 	repository := &durableRecoveryRepository{generations: map[string]ports.SnapshotGeneration{record.Name: generation}, errors: make(map[string]error), loads: make(map[string]int), repairs: make(map[string]domain.CheckpointRef)}
 	d, catalogue := newDurableRecoveryDaemon(t, []domain.CatalogueRecord{record}, repository)
-	d.restoreCatalogue(context.Background(), catalogue.Records())
+	d.restoreCatalogue(context.Background(), mustDurableRecords(t, catalogue))
 	require.Equal(t, runtimeDegraded, d.stopped[record.Name].state)
-	got, _ := catalogue.Record(record.Name)
+	got, _, _ := catalogue.Record(record.Name)
 	require.Equal(t, domain.RecoveryDegraded, got.RecoveryState)
 }
 	return s.record, nil
 }
+type contextRecoveryStub struct {
+	explicitRecoveryStub
+	wantKey any
+	want    any
+	seen    bool
+	err     error
+}
+func (s *contextRecoveryStub) Retry(ctx context.Context, _ string) error {
+	s.seen = ctx.Value(s.wantKey) == s.want
+	return s.err
+}
+func TestSessionRecoveryUsesIncomingCommandContext(t *testing.T) {
+	type contextKey struct{}
+	key := contextKey{}
+	ctx := context.WithValue(t.Context(), key, "request")
+	wantErr := errors.New("stop after context capture")
+	stub := &contextRecoveryStub{wantKey: key, want: "request", err: wantErr}
+	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
+	d.degradedRecovery = stub
+	_, err := (controlExec{ctx: ctx, d: d, recoveryName: "work"}).SessionRecovery("retry", "")
+	require.ErrorIs(t, err, wantErr)
+	require.True(t, stub.seen)
+}
+func TestExplicitRecoveryRejectsConcurrentRestore(t *testing.T) {
+	record := durableRecoveryRecord(0)
+	record.RecoveryState = domain.RecoveryDegraded
+	record.DegradedReason = "checkpoint validation failed"
+	d, _ := newDurableRecoveryDaemon(t, []domain.CatalogueRecord{record}, &durableRecoveryRepository{})
+	d.mu.Lock()
+	entry := d.stopped[record.Name]
+	entry.state = runtimeRestoring
+	originalDone := entry.restoreDone
+	d.stopped[record.Name] = entry
+	d.mu.Unlock()
+	err := (controlExec{d: d, recoveryName: record.Name}).restoreExplicitRecovery(t.Context())
+	require.ErrorContains(t, err, "current state")
+	d.mu.Lock()
+	require.Equal(t, originalDone, d.stopped[record.Name].restoreDone)
+	d.mu.Unlock()
+}
+func TestSessionRecoveryExportRequiresAbsolutePath(t *testing.T) {
+	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
+	d.degradedRecovery = explicitRecoveryStub{}
+	_, err := (controlExec{ctx: t.Context(), d: d, recoveryName: "work"}).SessionRecovery("export", "relative.snapshot")
+	require.ErrorIs(t, err, command.ErrInvalidArguments)
+}
 func TestSessionRecoveryCommand(t *testing.T) {
 	degraded := durableRecoveryRecord(2)
 	degraded.RecoveryState = domain.RecoveryDegraded
 	}, listed.Sessions)
 }
+func TestListPurgingDominatesRestoringState(t *testing.T) {
+	record := durableRecoveryRecord(0)
+	d, _ := newDurableRecoveryDaemon(t, []domain.CatalogueRecord{record}, &durableRecoveryRepository{})
+	d.mu.Lock()
+	entry := d.stopped[record.Name]
+	entry.purging = true
+	entry.state = runtimeRestoring
+	d.stopped[record.Name] = entry
+	d.mu.Unlock()
+	listed := listSessions(t, d)
+	require.Equal(t, []ports.SessionInfo{{Name: record.Name, State: ports.SessionDegraded}}, listed.Sessions)
+}
 func TestAttachWaitsForRestore(t *testing.T) {
 	record := durableRecoveryRecord(0)
 	factory := &recoveryCountingPTYFactory{}
 	require.Zero(t, factory.calls.Load())
 	d.setStoppedRecovery(record, runtimeDegraded)
-	closeRuntimeRestoreDone(d.recordRestoreDone(record.Name))
+	d.mu.Lock()
+	closeRuntimeRestoreDoneLocked(d.stopped[record.Name].restoreDone)
+	d.mu.Unlock()
 	var protocolError *protoErr
 	require.ErrorAs(t, <-result, &protocolError)
 	require.Equal(t, ports.ErrSessionDegraded, protocolError.code)
 	restoreCtx, cancelRestore := context.WithCancel(context.Background())
 	restored := make(chan struct{})
 	go func() {
-		d.restoreCatalogue(restoreCtx, catalogue.Records())
+		d.restoreCatalogue(restoreCtx, mustDurableRecords(t, catalogue))
 		close(restored)
 	}()
 	<-repository.started
 	default:
 		t.Fatal("restore completion was not signaled")
 	}
-	committed, _ := catalogue.Record(record.Name)
+	committed, _, _ := catalogue.Record(record.Name)
 	require.Equal(t, entry.record, committed)
 }
 func TestWaitForTargetRestoreRejectsClosedRestoringChannel(t *testing.T) {
 	record := durableRecoveryRecord(0)
 	d, _ := newDurableRecoveryDaemon(t, []domain.CatalogueRecord{record}, &durableRecoveryRepository{})
-	closeRuntimeRestoreDone(d.stopped[record.Name].restoreDone)
+	d.mu.Lock()
+	closeRuntimeRestoreDoneLocked(d.stopped[record.Name].restoreDone)
+	d.mu.Unlock()
 	result := make(chan error, 1)
 	go func() { result <- d.waitForTargetRestore(record.Name) }()
 	require.Zero(t, factory.calls.Load())
 }
+func TestRestoreUnavailableReleasesPerRecordWaiters(t *testing.T) {
+	record := durableRecoveryRecord(0)
+	d, _ := newDurableRecoveryDaemon(t, []domain.CatalogueRecord{record}, nil)
+	d.closeRestoreDone()
+	d.mu.Lock()
+	entry := d.stopped[record.Name]
+	d.mu.Unlock()
+	require.Equal(t, runtimeDegraded, entry.state)
+	select {
+	case <-entry.restoreDone:
+	default:
+		t.Fatal("per-record restore waiter remained blocked when repository was unavailable")
+	}
+}
 func TestCatalogueRestoreDegradedVisible(t *testing.T) {
 	record := durableRecoveryRecord(0)
 	record.RecoveryState = domain.RecoveryDegraded
 	repository := &durableRecoveryRepository{generations: make(map[string]ports.SnapshotGeneration), errors: make(map[string]error), loads: make(map[string]int), repairs: make(map[string]domain.CheckpointRef)}
 	d, catalogue := newDurableRecoveryDaemon(t, []domain.CatalogueRecord{record}, repository)
-	d.restoreCatalogue(context.Background(), catalogue.Records())
+	d.restoreCatalogue(context.Background(), mustDurableRecords(t, catalogue))
 	require.Equal(t, runtimeDegraded, d.stopped[record.Name].state)
 	require.Zero(t, repository.loads[record.Name])

D internal/usecase/daemon/legacy_snapshot_test.go +0 -8

@@ -1,8 +0,0 @@
1	-	package daemon
2	-
3	-	import "context"
4	-
5	-	// importLegacySnapshots is retained only for tests covering the retired
6	-	// pre-migration bridge. Normal runtime legacy decoding lives exclusively in
7	-	// the snapshot migration adapter.
8	-	func (d *Daemon) importLegacySnapshots(context.Context) {}

M internal/usecase/daemon/maintenance.go +33 -8

 	Step(context.Context, ports.ReconcileCursor) (ports.ReconcileCursor, []ports.ReconcileDecision, error)
 }
+// maintenanceDependencies is exclusively owned by runDurableMaintenance's
+// single goroutine after startup. Shutdown joins that goroutine before these
+// cursor and repair sets can be observed or reused.
 type maintenanceDependencies struct {
 	catalogue       ports.Catalogue
 	repository      ports.SnapshotRepository
 	case <-d.restoreDone:
 	}
 	for {
-		d.runDurableMaintenanceTick(ctx)
+		incomplete := d.runDurableMaintenanceTick(ctx)
+		if ctx.Err() != nil {
+			return
+		}
+		if incomplete {
+			continue
+		}
 		timer := d.clock.NewTimer(maintenanceInterval)
 		select {
 		case <-ctx.Done():
 	}
 }
-func (d *Daemon) runDurableMaintenanceTick(ctx context.Context) {
+// runDurableMaintenanceTick reports whether bounded work remains and should be
+// continued immediately rather than delayed until the periodic interval.
+func (d *Daemon) runDurableMaintenanceTick(ctx context.Context) bool {
 	deps := &d.maintenance
 	if deps.catalogue == nil || deps.repository == nil || deps.reconciler == nil {
-		return
+		return false
 	}
 	// Reconcile before collection. Until a complete top-level scan reaches EOF,
 	next, decisions, err := deps.reconciler.Step(ctx, deps.cursor)
 	if err != nil {
 		d.log.Warn("durable_reconciliation_tick", "action", "scan", "cursor", deps.cursor.DirectoryCookie, "done", false, "err", err)
-		return
+		return false
 	}
 	deps.cursor = next
 	for _, decision := range decisions {
-		record, ok := deps.catalogue.Record(decision.Name)
+		record, ok, err := deps.catalogue.Record(decision.Name)
+		if err != nil {
+			d.log.Warn("durable_reconciliation_tick", "action", "catalogue-read", "done", false, "err", err)
+			return false
+		}
 		if ok && !decision.RetentionResolved {
 			deps.repairUncertain[record.IncarnationID] = struct{}{}
 		}
 	}
 	d.log.Info("durable_reconciliation_tick", "action", "scan", "cursor", next.DirectoryCookie, "done", next.DirectoryCookie == 0, "err", nil)
 	if next.DirectoryCookie != 0 {
-		return
+		return true
 	}
-	for _, record := range deps.catalogue.Records() {
+	records, err := deps.catalogue.Records()
+	if err != nil {
+		d.log.Warn("durable_maintenance_tick", "action", "catalogue-read", "done", false, "err", err)
+		return false
+	}
+	incomplete := false
+	for _, record := range records {
 		if err := ctx.Err(); err != nil {
-			return
+			return false
 		}
 		_, unresolved := deps.unresolved[record.IncarnationID]
 		_, uncertainRepair := deps.repairUncertain[record.IncarnationID]
 		restoring := d.incarnationRestoring(record.IncarnationID)
 		plan := retentionPlan(record, unresolved || uncertainRepair, restoring)
 		done, err := deps.repository.MaintainSession(ctx, plan, ports.MaintenanceBudget{Entries: maintenanceEntries, Bytes: maintenanceBytes})
+		if err == nil && !done {
+			incomplete = true
+		}
 		d.log.Info("durable_maintenance_session",
 			"incarnation", record.IncarnationID.String(),
 			"action", "retention",
 		)
 	}
 	clear(deps.repairUncertain)
+	return incomplete
 }
 func (d *Daemon) incarnationRestoring(id domain.IncarnationID) bool {

M internal/usecase/daemon/maintenance_test.go +4 -4


@@ -28,7 +28,7 @@ func (r *cursorMaintenanceReconciler) Step(_ context.Context, cursor ports.Recon
28		func TestProductionMaintenanceUsesCatalogueAndResumesCursor(t *testing.T) {	28		func TestProductionMaintenanceUsesCatalogueAndResumesCursor(t *testing.T) {
29		record := domain.CatalogueRecord{Name: "work", IncarnationID: domain.IncarnationID{1}, RecoveryState: domain.RecoveryFresh}	29		record := domain.CatalogueRecord{Name: "work", IncarnationID: domain.IncarnationID{1}, RecoveryState: domain.RecoveryFresh}
30		catalogue := portsmocks.NewMockCatalogue(t)	30		catalogue := portsmocks.NewMockCatalogue(t)
31	-	catalogue.EXPECT().Records().Return([]domain.CatalogueRecord{record}).Once()	31	+	catalogue.EXPECT().Records().Return([]domain.CatalogueRecord{record}, nil).Once()
32		repository := portsmocks.NewMockSnapshotRepository(t)	32		repository := portsmocks.NewMockSnapshotRepository(t)
33		repository.EXPECT().MaintainSession(mock.Anything, mock.MatchedBy(func(plan ports.RetentionPlan) bool {	33		repository.EXPECT().MaintainSession(mock.Anything, mock.MatchedBy(func(plan ports.RetentionPlan) bool {
34		return plan.IncarnationID == record.IncarnationID && !plan.PinAll && len(plan.Keep) == 0	34		return plan.IncarnationID == record.IncarnationID && !plan.PinAll && len(plan.Keep) == 0

@@ -37,9 +37,9 @@ func TestProductionMaintenanceUsesCatalogueAndResumesCursor(t *testing.T) {
37		d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})	37		d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
38		WithDurableMaintenance(catalogue, repository, reconciler, nil)(d)	38		WithDurableMaintenance(catalogue, repository, reconciler, nil)(d)
39			39
40	-	d.runDurableMaintenanceTick(context.Background())	40	+	require.True(t, d.runDurableMaintenanceTick(context.Background()), "partial reconciliation must continue immediately")
41	-	d.runDurableMaintenanceTick(context.Background())	41	+	require.False(t, d.runDurableMaintenanceTick(context.Background()))
42	-	d.runDurableMaintenanceTick(context.Background())	42	+	require.True(t, d.runDurableMaintenanceTick(context.Background()), "the next partial pass must also continue immediately")
43		if len(reconciler.seen) != 3 \|\| reconciler.seen[0].DirectoryCookie != 0 \|\| reconciler.seen[1].DirectoryCookie != 7 \|\| reconciler.seen[2].DirectoryCookie != 0 {	43		if len(reconciler.seen) != 3 \|\| reconciler.seen[0].DirectoryCookie != 0 \|\| reconciler.seen[1].DirectoryCookie != 7 \|\| reconciler.seen[2].DirectoryCookie != 0 {
44		t.Fatalf("reconciliation cursors = %v, want [0 7 0]", reconciler.seen)	44		t.Fatalf("reconciliation cursors = %v, want [0 7 0]", reconciler.seen)
45		}	45		}

A internal/usecase/daemon/metadata_order_test.go +285 -0

@@ -0,0 +1,285 @@
	1	+	package daemon
	2	+
	3	+	import (
	4	+	"errors"
	5	+	"sync"
	6	+	"testing"
	7	+	"time"
	8	+
	9	+	"github.com/stretchr/testify/require"
	10	+
	11	+	"github.com/bnema/vev/internal/domain"
	12	+	"github.com/bnema/vev/internal/ports"
	13	+	)
	14	+
	15	+	type blockingMetadataCatalogue struct {
	16	+	ports.Catalogue
	17	+
	18	+	mu sync.Mutex
	19	+	calls int
	20	+	firstStarted chan struct{}
	21	+	releaseFirst chan struct{}
	22	+	firstErr error
	23	+	secondErr error
	24	+	}
	25	+
	26	+	func (c *blockingMetadataCatalogue) UpdateMetadata(update domain.CatalogueMetadataUpdate) error {
	27	+	c.mu.Lock()
	28	+	c.calls++
	29	+	call := c.calls
	30	+	c.mu.Unlock()
	31	+	if call == 1 {
	32	+	close(c.firstStarted)
	33	+	<-c.releaseFirst
	34	+	if c.firstErr != nil {
	35	+	return c.firstErr
	36	+	}
	37	+	}
	38	+	if call == 2 && c.secondErr != nil {
	39	+	return c.secondErr
	40	+	}
	41	+	return c.Catalogue.UpdateMetadata(update)
	42	+	}
	43	+
	44	+	func newBlockingCatalogue(sess session, firstErr error) (durableRecoveryCatalogue, *blockingMetadataCatalogue) {
	45	+	record := sess.persistRecordLocked(sess.createdAt)
	46	+	catalogue := newDurableRecoveryCatalogue([]domain.CatalogueRecord{record})
	47	+	return catalogue, &blockingMetadataCatalogue{
	48	+	Catalogue: catalogue,
	49	+	firstStarted: make(chan struct{}),
	50	+	releaseFirst: make(chan struct{}),
	51	+	firstErr: firstErr,
	52	+	}
	53	+	}
	54	+
	55	+	func TestMetadataWritesPreserveLaterMutationWhenFirstWriteIsBlocked(t *testing.T) {
	56	+	firstFailure := errors.New("first metadata write failed")
	57	+	for _, tt := range []struct {
	58	+	name string
	59	+	firstErr error
	60	+	}{
	61	+	{name: "delayed success"},
	62	+	{name: "delayed failure does not roll back newer state", firstErr: firstFailure},
	63	+	} {
	64	+	t.Run(tt.name, func(t *testing.T) {
	65	+	sess := newSnapshotTestSession(t, "work", false, "/work")
	66	+	catalogue, blocking := newBlockingCatalogue(sess, tt.firstErr)
	67	+	d := newTestDaemon(t, nil, stubClock{})
	68	+	d.catalogue = blocking
	69	+	d.sessions[sess.id] = sess
	70	+
	71	+	firstDone := make(chan error, 1)
	72	+	go func() { firstDone <- d.renameTab(sess, sess.tabs[0], "first") }()
	73	+	select {
	74	+	case <-blocking.firstStarted:
	75	+	case <-time.After(testWaitTimeout):
	76	+	t.Fatal("first metadata write did not block")
	77	+	}
	78	+
	79	+	secondDone := make(chan error, 1)
	80	+	go func() { secondDone <- d.renameTab(sess, sess.tabs[0], "second") }()
	81	+	require.Eventually(t, func() bool {
	82	+	sess.mu.Lock()
	83	+	defer sess.mu.Unlock()
	84	+	return sess.tabs[0].name == "second"
	85	+	}, testWaitTimeout, time.Millisecond, "later mutation did not proceed while storage was blocked")
	86	+
	87	+	close(blocking.releaseFirst)
	88	+	firstResult := <-firstDone
	89	+	if tt.firstErr == nil {
	90	+	require.NoError(t, firstResult)
	91	+	} else {
	92	+	require.ErrorIs(t, firstResult, tt.firstErr, "an in-memory revision cannot subsume a failed durable write")
	93	+	}
	94	+	require.NoError(t, <-secondDone)
	95	+
	96	+	persisted, ok, err := catalogue.Record("work")
	97	+	require.NoError(t, err)
	98	+	require.True(t, ok)
	99	+	require.Equal(t, []string{"second"}, persisted.TabNames)
	100	+	require.Equal(t, "second", sess.tabs[0].name)
	101	+	})
	102	+	}
	103	+	}
	104	+
	105	+	func TestTwoConsecutiveMetadataFailuresAreBothReported(t *testing.T) {
	106	+	firstFailure := errors.New("first metadata write failed")
	107	+	secondFailure := errors.New("second metadata write failed")
	108	+	sess := newSnapshotTestSession(t, "work", false, "/work")
	109	+	catalogue, blocking := newBlockingCatalogue(sess, firstFailure)
	110	+	blocking.secondErr = secondFailure
	111	+	close(blocking.releaseFirst)
	112	+	d := newTestDaemon(t, nil, stubClock{})
	113	+	d.catalogue = blocking
	114	+	d.sessions[sess.id] = sess
	115	+
	116	+	require.ErrorIs(t, d.renameTab(sess, sess.tabs[0], "first"), firstFailure)
	117	+	require.ErrorIs(t, d.renameTab(sess, sess.tabs[0], "second"), secondFailure)
	118	+
	119	+	persisted, ok, err := catalogue.Record("work")
	120	+	require.NoError(t, err)
	121	+	require.True(t, ok)
	122	+	require.Empty(t, persisted.TabNames)
	123	+	sess.mu.Lock()
	124	+	require.Empty(t, sess.tabs[0].name)
	125	+	sess.mu.Unlock()
	126	+	}
	127	+
	128	+	func TestConsecutiveMetadataFailuresRestoreDurableState(t *testing.T) {
	129	+	firstFailure := errors.New("first metadata write failed")
	130	+	secondFailure := errors.New("second metadata write failed")
	131	+	sess := newSnapshotTestSession(t, "work", false, "/work")
	132	+	catalogue, blocking := newBlockingCatalogue(sess, firstFailure)
	133	+	blocking.secondErr = secondFailure
	134	+	d := newTestDaemon(t, nil, stubClock{})
	135	+	d.catalogue = blocking
	136	+	d.sessions[sess.id] = sess
	137	+
	138	+	firstDone := make(chan error, 1)
	139	+	go func() { firstDone <- d.renameTab(sess, sess.tabs[0], "first") }()
	140	+	select {
	141	+	case <-blocking.firstStarted:
	142	+	case <-time.After(testWaitTimeout):
	143	+	t.Fatal("first metadata write did not block")
	144	+	}
	145	+	secondDone := make(chan error, 1)
	146	+	go func() { secondDone <- d.renameTab(sess, sess.tabs[0], "second") }()
	147	+	require.Eventually(t, func() bool {
	148	+	sess.mu.Lock()
	149	+	defer sess.mu.Unlock()
	150	+	return sess.tabs[0].name == "second"
	151	+	}, testWaitTimeout, time.Millisecond)
	152	+
	153	+	close(blocking.releaseFirst)
	154	+	require.ErrorIs(t, <-firstDone, firstFailure)
	155	+	require.ErrorIs(t, <-secondDone, secondFailure)
	156	+
	157	+	persisted, ok, err := catalogue.Record("work")
	158	+	require.NoError(t, err)
	159	+	require.True(t, ok)
	160	+	require.Empty(t, persisted.TabNames)
	161	+	sess.mu.Lock()
	162	+	require.Empty(t, sess.tabs[0].name)
	163	+	sess.mu.Unlock()
	164	+	}
	165	+
	166	+	func TestNewerMetadataFailureDoesNotSkipOlderSnapshot(t *testing.T) {
	167	+	failure := errors.New("newer metadata write failed")
	168	+	sess := newSnapshotTestSession(t, "work", false, "/work")
	169	+	catalogue := newDurableRecoveryCatalogue([]domain.CatalogueRecord{sess.persistRecordLocked(sess.createdAt)})
	170	+	blocking := &blockingMetadataCatalogue{
	171	+	Catalogue: catalogue,
	172	+	firstStarted: make(chan struct{}),
	173	+	releaseFirst: make(chan struct{}),
	174	+	firstErr: failure,
	175	+	}
	176	+	close(blocking.releaseFirst)
	177	+	d := newTestDaemon(t, nil, stubClock{})
	178	+	d.catalogue = blocking
	179	+	d.sessions[sess.id] = sess
	180	+	tb := sess.tabs[0]
	181	+
	182	+	sess.mu.Lock()
	183	+	tb.name = "first"
	184	+	firstRecord, firstVersion := sess.nextPersistRecordLocked(sess.createdAt + 1)
	185	+	tb.name = "second"
	186	+	secondRecord, secondVersion := sess.nextPersistRecordLocked(sess.createdAt + 2)
	187	+	sess.mu.Unlock()
	188	+
	189	+	secondRollback := func() bool {
	190	+	sess.mu.Lock()
	191	+	defer sess.mu.Unlock()
	192	+	if tb.name != "second" {
	193	+	return false
	194	+	}
	195	+	tb.name = "first"
	196	+	return true
	197	+	}
	198	+	firstRollback := func() bool {
	199	+	sess.mu.Lock()
	200	+	defer sess.mu.Unlock()
	201	+	if tb.name != "first" {
	202	+	return false
	203	+	}
	204	+	tb.name = ""
	205	+	return true
	206	+	}
	207	+
	208	+	require.ErrorIs(t, d.persistSessionMetadata(sess, secondVersion, secondRecord.MetadataUpdate(), secondRollback), failure)
	209	+	require.NoError(t, d.persistSessionMetadata(sess, firstVersion, firstRecord.MetadataUpdate(), firstRollback))
	210	+
	211	+	persisted, ok, err := catalogue.Record("work")
	212	+	require.NoError(t, err)
	213	+	require.True(t, ok)
	214	+	require.Equal(t, []string{"first"}, persisted.TabNames)
	215	+	sess.mu.Lock()
	216	+	require.Equal(t, "first", tb.name)
	217	+	sess.mu.Unlock()
	218	+	}
	219	+
	220	+	func TestLatestMetadataFailureRollsBackRename(t *testing.T) {
	221	+	failure := errors.New("metadata write failed")
	222	+	sess := newSnapshotTestSession(t, "work", false, "/work")
	223	+	catalogue, blocking := newBlockingCatalogue(sess, failure)
	224	+	d := newTestDaemon(t, nil, stubClock{})
	225	+	d.catalogue = blocking
	226	+	d.sessions[sess.id] = sess
	227	+
	228	+	done := make(chan error, 1)
	229	+	go func() { done <- d.renameTab(sess, sess.tabs[0], "failed") }()
	230	+	select {
	231	+	case <-blocking.firstStarted:
	232	+	case <-time.After(testWaitTimeout):
	233	+	t.Fatal("metadata write did not block")
	234	+	}
	235	+	close(blocking.releaseFirst)
	236	+	require.ErrorIs(t, <-done, failure)
	237	+
	238	+	persisted, ok, err := catalogue.Record("work")
	239	+	require.NoError(t, err)
	240	+	require.True(t, ok)
	241	+	require.Empty(t, persisted.TabNames)
	242	+	require.Empty(t, sess.tabs[0].name)
	243	+	}
	244	+
	245	+	func TestBlockedCwdWriteCannotOverwriteLaterTabMetadata(t *testing.T) {
	246	+	sess := newSnapshotTestSession(t, "work", false, "/work")
	247	+	catalogue, blocking := newBlockingCatalogue(sess, nil)
	248	+	d := newTestDaemon(t, nil, stubClock{})
	249	+	d.catalogue = blocking
	250	+	d.sessions[sess.id] = sess
	251	+	d.procCwd = func(int) (string, error) { return "/later-cwd", nil }
	252	+
	253	+	cwdDone := make(chan struct{})
	254	+	go func() {
	255	+	d.refreshSessionCwd(sess)
	256	+	close(cwdDone)
	257	+	}()
	258	+	select {
	259	+	case <-blocking.firstStarted:
	260	+	case <-time.After(testWaitTimeout):
	261	+	t.Fatal("cwd metadata write did not block")
	262	+	}
	263	+
	264	+	renameDone := make(chan error, 1)
	265	+	go func() { renameDone <- d.renameTab(sess, sess.tabs[0], "later-tab") }()
	266	+	require.Eventually(t, func() bool {
	267	+	sess.mu.Lock()
	268	+	defer sess.mu.Unlock()
	269	+	return sess.tabs[0].name == "later-tab"
	270	+	}, testWaitTimeout, time.Millisecond)
	271	+
	272	+	close(blocking.releaseFirst)
	273	+	select {
	274	+	case <-cwdDone:
	275	+	case <-time.After(testWaitTimeout):
	276	+	t.Fatal("cwd refresh deadlocked")
	277	+	}
	278	+	require.NoError(t, <-renameDone)
	279	+
	280	+	persisted, ok, err := catalogue.Record("work")
	281	+	require.NoError(t, err)
	282	+	require.True(t, ok)
	283	+	require.Equal(t, "/later-cwd", persisted.Cwd)
	284	+	require.Equal(t, []string{"later-tab"}, persisted.TabNames)
	285	+	}

M internal/usecase/daemon/performance_benchmark_test.go +3 -3


@@ -638,7 +638,7 @@ func publishBenchmarkSnapshot(b testing.TB, fixture *performanceFixture, generat
638			638
639		func mutateBenchmarkVisible(fixture *performanceFixture, operation int) {	639		func mutateBenchmarkVisible(fixture *performanceFixture, operation int) {
640		fixture.activePane.mu.Lock()	640		fixture.activePane.mu.Lock()
641	-	fixture.activePane.screen.Write([]byte(fmt.Sprintf("\x1b[1;1Hvisible-%08d", operation)))	641	+	fixture.activePane.screen.Write(fmt.Appendf(nil, "\x1b[1;1Hvisible-%08d", operation))
642		fixture.activePane.mu.Unlock()	642		fixture.activePane.mu.Unlock()
643		}	643		}
644			644

@@ -653,7 +653,7 @@ func mutateBenchmarkTail(fixture *performanceFixture, operation int) {
653		}	653		}
654			654
655		func mutateBenchmarkSealedChunk(fixture *performanceFixture, operation int) {	655		func mutateBenchmarkSealedChunk(fixture *performanceFixture, operation int) {
656	-	for row := 0; row < 256; row++ {	656	+	for row := range 256 {
657		mutateBenchmarkTail(fixture, operation*256+row)	657		mutateBenchmarkTail(fixture, operation*256+row)
658		}	658		}
659		}	659		}

@@ -1065,7 +1065,7 @@ func newPerformanceFixtureWithCleanup(t testing.TB, config performanceConfig, re
1065		liveWrites: [][]byte{[]byte("\x1b[1;1HA\x1b[2;2HA"), []byte("\x1b[1;1HB\x1b[2;2HB")},	1065		liveWrites: [][]byte{[]byte("\x1b[1;1HA\x1b[2;2HA"), []byte("\x1b[1;1HB\x1b[2;2HB")},
1066		resizeSizes: [2]domain.Size{{Cols: 100, Rows: 30}, config.size},	1066		resizeSizes: [2]domain.Size{{Cols: 100, Rows: 30}, config.size},
1067		}	1067		}
1068	-	WithSnapshotRepository(fixture.snapshots, nil)(d)	1068	+	WithSnapshotRepository(fixture.snapshots)(d)
1069		d.startSnapshotEncodeWorker()	1069		d.startSnapshotEncodeWorker()
1070		if registerCleanup {	1070		if registerCleanup {
1071		t.Cleanup(d.stopSnapshotEncodeWorker)	1071		t.Cleanup(d.stopSnapshotEncodeWorker)

M internal/usecase/daemon/picker_test.go +27 -34

 // --- test doubles -----------------------------------------------------------
-// failingDeleteStore is a ports.Store whose Delete always fails, used to
-// exercise the picker's kill-target error path without disturbing the
-// generated mock's default Delete expectation.
-type failingDeleteStore struct{ err error }
-func (failingDeleteStore) Get([]byte) ([]byte, bool) { return nil, false }
-func (failingDeleteStore) Set([]byte, []byte) error  { return nil }
-func (s failingDeleteStore) Batch(changes []ports.StoreChange) error {
-	for _, change := range changes {
-		if change.Delete {
-			return s.err
-		}
-	}
-	return nil
-}
-func (s failingDeleteStore) Delete([]byte) error        { return s.err }
-func (failingDeleteStore) Range(func(k, v []byte) bool) {}
-func (failingDeleteStore) Sync() error                  { return nil }
-func (failingDeleteStore) Close() error                 { return nil }
 type refusingSnapshotDeleteRepository struct {
 	noOpSnapshotRepository
 	err error
 	d.mu.Lock()
 	delete(d.stopped, record.Name)
 	d.sessions[target.id] = target
+	closeRuntimeRestoreDoneLocked(done)
 	d.mu.Unlock()
-	closeRuntimeRestoreDone(done)
 	require.NoError(t, <-result)
 	require.Same(t, target, ac.currentSession())
 	catalogue := newDurableRecoveryCatalogue([]domain.CatalogueRecord{record})
 	coordinator := recoveryusecase.NewCoordinator(catalogue, repository, nil, nil)
 	WithCatalogue(catalogue, []domain.CatalogueRecord{record})(d)
-	WithSnapshotRepository(repository, nil)(d)
+	WithSnapshotRepository(repository)(d)
 	WithCheckpointCoordinator(coordinator)(d)
 	restoreCtx, cancelRestore := context.WithCancel(context.Background())
 	restored := make(chan struct{})
 	go func() {
-		d.restoreCatalogue(restoreCtx, catalogue.Records())
+		d.restoreCatalogue(restoreCtx, mustDurableRecords(t, catalogue))
 		close(restored)
 	}()
 	<-repository.started
 	d, from, ac, sends, releases := newRecentNavigationTestSessions(t)
 	defer releaseAll(releases)
 	cause := errors.New("snapshot delete refused")
-	WithSnapshotRepository(refusingSnapshotDeleteRepository{err: cause}, nil)(d)
+	WithSnapshotRepository(refusingSnapshotDeleteRepository{err: cause})(d)
 	target := d.sessions[domain.SessionID("recent")]
+	store, _ := newMockStore(t)
+	WithStore(store)(d)
+	target.mu.Lock()
+	if target.incarnation == (domain.IncarnationID{}) {
+		target.incarnation = domain.IncarnationID{1}
+	}
+	record := target.persistRecordLocked(1)
+	target.mu.Unlock()
+	record.RecoveryState = domain.RecoveryFresh
+	require.NoError(t, d.catalogue.Create(record))
 	d.enterPicker(from, ac)
 	awaitFrame(t, sends, ports.MsgOutput)
 	defer release()
 	d, from, ac, sends := newManualSessionWithPTYs(t, p)
 	cause := errors.New("delete failed")
-	WithStore(failingDeleteStore{err: cause})(d)
+	store, state := newMockStore(t)
-	d.stopped["stopped"] = stoppedSession{name: "stopped", cwd: "/tmp/stopped", createdAt: 7}
+	WithStore(store)(d)
+	record := domain.CatalogueRecord{Name: "stopped", IncarnationID: domain.IncarnationID{1}, Cwd: "/tmp/stopped", CreatedAt: 7, RecoveryState: domain.RecoveryFresh}
+	require.NoError(t, d.catalogue.Create(record))
+	state.mu.Lock()
+	state.deleteErr = func(string) error { return cause }
+	state.mu.Unlock()
+	d.stopped["stopped"] = stoppedSession{name: "stopped", cwd: "/tmp/stopped", createdAt: 7, incarnation: record.IncarnationID, record: record}
 	d.enterPicker(from, ac)
 	awaitFrame(t, sends, ports.MsgOutput)
 	toasts := awaitToastCount(t, ac, 1)
 	require.Equal(t, domain.NoticePersistDelete, toasts[0].Code)
-	views, _ := d.pickerViews(from)
+	d.mu.Lock()
-	var stillListed bool
+	stopped, retained := d.stopped["stopped"]
-	for _, v := range views {
+	d.mu.Unlock()
-		if v.Stopped && v.Name == "stopped" {
+	require.True(t, retained, "failed deletion must retain the reserved name")
-			stillListed = true
+	require.True(t, stopped.purging, "an uncertain deletion stays fenced from restore")
-		}
-	}
-	require.True(t, stillListed, "entry must remain listed after refreshPicker when the delete failed")
 }

M internal/usecase/daemon/recovery_observability.go +6 -1

 func (d *Daemon) logStartupRecoveryCounts(restoring int) {
 	var records []domain.CatalogueRecord
 	if d.catalogue != nil {
-		records = d.catalogue.Records()
+		var err error
+		records, err = d.catalogue.Records()
+		if err != nil {
+			d.log.Error("daemon_startup_catalogue_read_failed", "err", err)
+			return
+		}
 	} else {
 		d.mu.Lock()
 		records = make([]domain.CatalogueRecord, 0, len(d.stopped))

M internal/usecase/daemon/render_capture.go +37 -12


@@ -17,15 +17,21 @@ import (
17		// capture/compose/emit transaction holds that attachment's sendMu, so these	17		// capture/compose/emit transaction holds that attachment's sendMu, so these
18		// buffers cannot be observed or reused before emission completes.	18		// buffers cannot be observed or reused before emission completes.
19		type renderCaptureScratch struct {	19		type renderCaptureScratch struct {
20	-	state capturedRenderState	20	+	state capturedRenderState
21	-	panes []capturedPaneRenderState	21	+	panes []capturedPaneRenderState
22	-	placements []layout.Placement	22	+	placements []layout.Placement
23	-	dividers []layout.Divider	23	+	dividers []layout.Divider
24	-	statusTabs []statusTab	24	+	layoutTab *tab
25	-	mru []recentSession	25	+	layoutGeneration uint64
26	-	ranked []rankedRecent	26	+	layoutArea domain.Rect
27	-	titleIDs []layout.PaneID	27	+	layoutFocus layout.PaneID
28	-	receipts []damageReceipt	28	+	layoutFingerprint string
			29	+	layoutValid bool
			30	+	statusTabs []statusTab
			31	+	mru []recentSession
			32	+	ranked []rankedRecent
			33	+	titleIDs []layout.PaneID
			34	+	receipts []damageReceipt
29		}	35		}
30			36
31		type damageReceipt struct {	37		type damageReceipt struct {

@@ -225,9 +231,28 @@ func capturePrimaryRenderState(
225			231
226		tb.mu.Lock()	232		tb.mu.Lock()
227		defer tb.mu.Unlock()	233		defer tb.mu.Unlock()
228	-	layoutSnap := solveTabLayoutLocked(tb)	234	+	area := domain.Rect{Width: tb.size.Cols, Height: tb.size.Rows}
229	-	scratch.placements = append(scratch.placements[:0], layoutSnap.placements...)	235	+	var focus layout.PaneID
230	-	scratch.dividers = append(scratch.dividers[:0], layoutSnap.dividers...)	236	+	if tb.tree != nil {
			237	+	focus = tb.tree.Focus
			238	+	}
			239	+	layoutSnap := tabLayoutSnapshot{
			240	+	area: area, focus: focus, placements: scratch.placements,
			241	+	dividers: scratch.dividers, fingerprint: scratch.layoutFingerprint, ok: scratch.layoutValid,
			242	+	}
			243	+	if scratch.layoutTab != tb \|\| scratch.layoutGeneration != tb.layoutGeneration \|\| scratch.layoutArea != area \|\| scratch.layoutFocus != focus {
			244	+	layoutSnap = solveTabLayoutLocked(tb)
			245	+	scratch.placements = append(scratch.placements[:0], layoutSnap.placements...)
			246	+	scratch.dividers = append(scratch.dividers[:0], layoutSnap.dividers...)
			247	+	scratch.layoutTab = tb
			248	+	scratch.layoutGeneration = tb.layoutGeneration
			249	+	scratch.layoutArea = area
			250	+	scratch.layoutFocus = focus
			251	+	scratch.layoutFingerprint = layoutSnap.fingerprint
			252	+	scratch.layoutValid = layoutSnap.ok
			253	+	layoutSnap.placements = scratch.placements
			254	+	layoutSnap.dividers = scratch.dividers
			255	+	}
231		state := &scratch.state	256		state := &scratch.state
232		*state = capturedRenderState{	257		*state = capturedRenderState{
233		attachment: ac, lease: lease, reset: reset, bars: bars, theme: bars.theme,	258		attachment: ac, lease: lease, reset: reset, bars: bars, theme: bars.theme,

M internal/usecase/daemon/session.go +263 -126

 	"time"
 	"github.com/bnema/vev/internal/domain"
-	"github.com/bnema/vev/internal/persist"
 	"github.com/bnema/vev/internal/ports"
 	"github.com/bnema/vev/internal/usecase/layout"
 )
 	// tab, or pane locks. The owner performs teardown without holding teardownMu;
 	// duplicate daemon-shutdown callers can therefore bound their ownership wait
 	// with Serve's shared snapshot deadline.
-	teardownMu             sync.Mutex
+	teardownMu        sync.Mutex
-	teardownActive         bool
+	teardownActive    bool
-	teardownDone           chan struct{}
+	teardownDone      chan struct{}
-	teardownWaiters        uint
+	teardownWaiters   uint
-	teardownChanged        chan struct{}
+	teardownChanged   chan struct{}
-	lifecycleStopOnce      sync.Once
+	lifecycleStopOnce sync.Once
-	mu                     sync.Mutex // guards tabs, active, client, clipFiles, and clipboard queue state
+	mu                sync.Mutex // guards tabs, active, client, clipFiles, and clipboard queue state
-	themeMu                sync.Mutex
+	// metadataPersistMu serializes authority writes and post-I/O rollback. State
-	tabs                   []*tab
+	// mutation paths must release d.mu and mu before acquiring it. After durable
-	active                 int
+	// I/O completes it may acquire d.mu then mu to reconcile failed revisions.
-	client                 *attachedClient
+	metadataPersistMu       sync.Mutex
-	clipboardQueue         []clipboardForward
+	metadataVersion         uint64                 // guarded by mu; every durable metadata snapshot receives a revision
-	clipboardWorkerRunning bool
+	metadataDurableVersion  uint64                 // guarded by metadataPersistMu
-	renameInProgress       bool
+	metadataLiveVersion     uint64                 // rollback cursor guarded by metadataPersistMu
-	cwd                    string
+	metadataFailedRollbacks map[uint64]func() bool // guarded by metadataPersistMu
-	terminal               terminalEnv
+	themeMu                 sync.Mutex
+	tabs                    []*tab
+	active                  int
+	client                  *attachedClient
+	clipboardQueue          []clipboardForward
+	clipboardWorkerRunning  bool
+	renameInProgress        bool
+	renameDone              chan struct{}
+	cwd                     string
+	terminal                terminalEnv
 	// env is the authoritative immutable environment snapshot for future PTY children.
 	// It is guarded by mu and is always copied on ingress and egress.
 	env          []string
 	}
 	seq := d.mruSeq.Add(1)
 	updated := false
+	var previous uint64
 	for {
 		old := sess.mruAt.Load()
 		if old >= seq {
 			return
 		}
 		if sess.mruAt.CompareAndSwap(old, seq) {
+			previous = old
 			updated = true
 			break
 		}
 	}
 	sess.mu.Lock()
 	name := sess.name
-	incarnation := sess.incarnation
 	ephemeral := sess.ephemeral
+	var record domain.CatalogueRecord
+	var version uint64
+	if !ephemeral {
+		record, version = sess.nextPersistRecordLocked(max(d.nowUnixNano(), sess.createdAt, int64(1)))
+	}
 	sess.mu.Unlock()
 	if !ephemeral {
-		if err := d.updateCatalogueMetadata(domain.CatalogueMetadataUpdate{Name: name, IncarnationID: incarnation, LastUsedSeq: &seq}); err != nil {
+		rollback := func() bool {
+			return sess.mruAt.CompareAndSwap(seq, previous)
+		}
+		if err := d.persistSessionMetadata(sess, version, record.MetadataUpdate(), rollback); err != nil {
 			d.log.Warn("touching persisted session recency failed", "err", err, "session", name)
 		}
 	}
 }
 func (d *Daemon) createSessionLocked(name string, ephemeral bool, cwd string, sz domain.Size, term terminalEnv, env []string, restoredTabNames ...[]string) (*session, error) {
+	// Historical focused tests call this helper directly. Acquire mu for those
+	// callers while preserving the production contract that an owning caller
+	// receives it still locked on return.
+	acquiredMu := d.mu.TryLock()
+	if acquiredMu {
+		defer d.mu.Unlock()
+	}
 	env = copyEnvironment(env)
+	if _, reserved := d.creating[name]; reserved {
+		return nil, errSessionNameInUse
+	}
+	d.creating[name] = struct{}{}
+	defer delete(d.creating, name)
 	stopped, resuming := d.stopped[name]
+	var authoritative domain.CatalogueRecord
+	var authoritativeExists bool
+	if !ephemeral && resuming && d.persistEnabled {
+		d.mu.Unlock()
+		var err error
+		authoritative, authoritativeExists, err = d.catalogueRecord(name)
+		d.mu.Lock()
+		if err != nil {
+			return nil, domain.UserErr(domain.NoticeSessionSpawn, "couldn't read session catalogue", err)
+		}
+	}
 	var createdAt int64
 	var incarnation domain.IncarnationID
 	if !ephemeral {
 			// the persisted identity rather than receive a fresh timestamp.
 			createdAt = stopped.createdAt
 			incarnation = stopped.incarnation
-			if authoritative, ok := d.catalogueRecord(name); ok {
+			if authoritativeExists {
-				incarnation = authoritative.IncarnationID
 				createdAt = authoritative.CreatedAt
+				incarnation = authoritative.IncarnationID
 			}
 			if createdAt > d.lastAllocatedCreatedAt {
 				d.lastAllocatedCreatedAt = createdAt
 	if !ephemeral && resuming {
 		lastUsedSeq = stopped.lastUsedSeq
 	}
+	if lastUsedSeq == 0 {
+		lastUsedSeq = d.mruSeq.Add(1)
+	}
 	sess := &session{
 		id:           id,
 		name:         name,
 	sess.snapEligible.Store(!ephemeral && name != "")
 	if !ephemeral {
 		if d.persistEnabled {
-			record := persist.Record{Name: name, IncarnationID: incarnation, Cwd: cwd, CreatedAt: createdAt, UpdatedAt: createdAt, LastUsedSeq: lastUsedSeq, TabNames: names, RecoveryState: domain.RecoveryFresh}
+			record := domain.CatalogueRecord{Name: name, IncarnationID: incarnation, Cwd: cwd, CreatedAt: createdAt, UpdatedAt: createdAt, LastUsedSeq: lastUsedSeq, TabNames: names, RecoveryState: domain.RecoveryFresh}
+			if d.lifecycleRecovery == nil {
+				closeTabs(tabs)
+				cancel()
+				return nil, domain.UserErr(domain.NoticeSessionSpawn, "couldn't create session", errors.New("durable session authority is not configured"))
+			}
+			// The name reservation remains visible while durable authority I/O runs,
+			// but daemon/session mutexes are released so storage cannot block routing.
+			d.mu.Unlock()
 			var err error
-			if resuming {
+			if resuming && authoritativeExists {
-				if _, ok := d.catalogueRecord(name); ok {
+				err = d.updateCatalogueMetadata(record.MetadataUpdate())
-					err = d.updateCatalogueMetadata(record.MetadataUpdate())
-				} else if d.lifecycleRecovery != nil {
-					record, err = d.lifecycleRecovery.Create(context.Background(), record)
-				} else {
-					err = d.createCatalogueRecord(record)
-				}
-			} else if d.lifecycleRecovery != nil {
-				record, err = d.lifecycleRecovery.Create(context.Background(), record)
 			} else {
-				err = d.createCatalogueRecord(record)
+				record, err = d.lifecycleRecovery.Create(d.serveCtx, record)
 			}
+			d.mu.Lock()
 			if err != nil {
 				closeTabs(tabs)
 				cancel()
 				return nil, domain.UserErr(domain.NoticeSessionSpawn, "couldn't create session", err)
 			}
+			if d.closing {
+				// Creation lost its race with shutdown. Roll back a newly committed
+				// authority record without holding mu; resumed metadata remains owned
+				// by the existing stopped lifecycle.
+				if !resuming {
+					d.mu.Unlock()
+					rollbackCtx, rollbackCancel := context.WithTimeout(context.WithoutCancel(d.serveCtx), snapshotFinalFlushTimeout)
+					rollbackErr := d.lifecycleRecovery.Delete(rollbackCtx, name)
+					rollbackCancel()
+					d.mu.Lock()
+					if rollbackErr != nil {
+						d.log.Warn("rolling back session creation during shutdown failed", "session", name, "err", rollbackErr)
+					}
+				}
+				closeTabs(tabs)
+				cancel()
+				return nil, errors.New("daemon is shutting down")
+			}
 			sess.incarnation = record.IncarnationID
 		}
 		delete(d.stopped, name)
 	}
 	d.sessions[id] = sess
-	if lastUsedSeq == 0 {
-		d.touchMRU(sess)
-	}
 	d.log.Info("session created", "session", name, "id", id, "ephemeral", ephemeral)
 	for i, tb := range tabs {
 		d.log.Info("tab created", "session", name, "tab", i)
 	sess.tabs = append(sess.tabs, tb)
 	sess.active = len(sess.tabs) - 1
 	tabIndex := sess.active
-	record := sess.persistRecordLocked(time.Now().UnixNano())
+	record, metadataVersion := sess.nextPersistRecordLocked(max(d.nowUnixNano(), sess.createdAt, int64(1)))
 	ephemeral := sess.ephemeral
+	sess.mu.Unlock()
+	d.mu.Unlock()
 	if !ephemeral {
-		if err := d.updateCatalogueMetadata(record.MetadataUpdate()); err != nil {
+		rollback := func() bool {
-			sess.tabs = sess.tabs[:len(sess.tabs)-1]
+			d.mu.Lock()
-			sess.active = oldActive
+			defer d.mu.Unlock()
+			if d.sessions[sess.id] != sess {
+				return true
+			}
+			sess.mu.Lock()
+			if !slices.Contains(sess.tabs, tb) {
+				sess.mu.Unlock()
+				return true
+			}
+			if sess.tabs[len(sess.tabs)-1] != tb {
+				sess.mu.Unlock()
+				return false
+			}
+			sess.tabs = slices.DeleteFunc(sess.tabs, func(candidate *tab) bool { return candidate == tb })
+			sess.active = min(oldActive, len(sess.tabs)-1)
+			sess.mu.Unlock()
 			if tb.cancel != nil {
 				tb.cancel()
 			}
-			sess.mu.Unlock()
-			d.mu.Unlock()
 			_ = pty.Close()
+			return true
+		}
+		if err := d.persistSessionMetadata(sess, metadataVersion, record.MetadataUpdate(), rollback); err != nil {
 			return err
 		}
 	}
-	sess.mu.Unlock()
 	d.log.Info("tab created", "session", name, "tab", tabIndex)
 	d.startTabGoroutines(sess, tb)
-	d.mu.Unlock()
 	d.activateTab(sess, tb)
 	markSnapshotDirty(sess)
 	return nil
 		}
 	}
 	lastUsedSeq := sess.mruAt.Load()
-	record := sess.persistRecordLocked(d.nowUnixNano())
+	record := sess.persistRecordLocked(max(d.nowUnixNano(), sess.createdAt, int64(1)))
 	record.Name = name
 	record.CreatedAt = createdAt
 	record.LastUsedSeq = lastUsedSeq
 	sess.renameInProgress = true
+	sess.renameDone = make(chan struct{})
 	sess.mu.Unlock()
 	d.mu.Unlock()
 	rollback := func(err error) error {
 		sess.mu.Lock()
 		sess.renameInProgress = false
+		if sess.renameDone != nil {
+			close(sess.renameDone)
+			sess.renameDone = nil
+		}
 		sess.mu.Unlock()
 		return err
 	}
 	// Durable named renames are one atomic catalogue batch. The incarnation-keyed
 	// snapshot namespace is intentionally untouched.
 	if (wasEphemeral || oldName != name) && d.persistEnabled {
-		if d.lifecycleRecovery != nil {
+		if d.lifecycleRecovery == nil {
+			return rollback(errors.New("durable session authority is not configured"))
+		}
+		{
 			var committed domain.CatalogueRecord
 			var err error
 			if wasEphemeral {
-				committed, err = d.lifecycleRecovery.Create(context.Background(), record)
+				committed, err = d.lifecycleRecovery.Create(d.serveCtx, record)
 			} else {
-				committed, err = d.lifecycleRecovery.Rename(context.Background(), oldName, name)
+				committed, err = d.lifecycleRecovery.Rename(d.serveCtx, oldName, name)
 			}
 			if err != nil {
 				return rollback(err)
 			}
 			record = committed
-		} else if wasEphemeral {
-			if err := d.createCatalogueRecord(record); err != nil {
-				return rollback(err)
-			}
-		} else {
-			if current, ok := d.catalogueRecord(oldName); ok {
-				current.Name = name
-				current.Cwd = record.Cwd
-				current.UpdatedAt = record.UpdatedAt
-				current.LastUsedSeq = record.LastUsedSeq
-				current.TabNames = append([]string(nil), record.TabNames...)
-				record = current
-			}
-			if err := d.catalogue.Rename(oldName, record); err != nil {
-				return rollback(err)
-			}
 		}
 	}
 	sess.incarnation = record.IncarnationID
 	sess.ephemeral = false
 	sess.renameInProgress = false
+	if sess.renameDone != nil {
+		close(sess.renameDone)
+		sess.renameDone = nil
+	}
 	sess.snapEligible.Store(name != "")
 	sess.mu.Unlock()
 	d.mu.Unlock()
 	}
 	oldName := tb.name
 	tb.name = name
-	record := sess.persistRecordLocked(time.Now().UnixNano())
+	record, metadataVersion := sess.nextPersistRecordLocked(max(d.nowUnixNano(), sess.createdAt, int64(1)))
 	ephemeral := sess.ephemeral
-	if !ephemeral {
-		if err := d.updateCatalogueMetadata(record.MetadataUpdate()); err != nil {
-			tb.name = oldName
-			sess.mu.Unlock()
-			d.mu.Unlock()
-			return err
-		}
-	}
 	sess.mu.Unlock()
 	d.mu.Unlock()
+	if ephemeral {
+		return nil
+	}
+	rollback := func() bool {
+		d.mu.Lock()
+		defer d.mu.Unlock()
+		if d.sessions[sess.id] != sess {
+			return true
+		}
+		sess.mu.Lock()
+		defer sess.mu.Unlock()
+		if !slices.Contains(sess.tabs, tb) {
+			return true
+		}
+		if tb.name != name {
+			return false
+		}
+		tb.name = oldName
+		return true
+	}
+	if err := d.persistSessionMetadata(sess, metadataVersion, record.MetadataUpdate(), rollback); err != nil {
+		return err
+	}
 	return nil
 }
-func (s *session) persistRecordLocked(updatedAt int64) persist.Record {
+func (s *session) nextPersistRecordLocked(updatedAt int64) (domain.CatalogueRecord, uint64) {
+	s.metadataVersion++
+	return s.persistRecordLocked(updatedAt), s.metadataVersion
+}
+func (s *session) persistRecordLocked(updatedAt int64) domain.CatalogueRecord {
 	createdAt := s.createdAt
 	tabNames := make([]string, len(s.tabs))
 	lastCustom := -1
 	} else {
 		tabNames = tabNames[:lastCustom+1]
 	}
-	return persist.Record{Name: s.name, IncarnationID: s.incarnation, Cwd: s.cwd, CreatedAt: createdAt, UpdatedAt: updatedAt, LastUsedSeq: s.mruAt.Load(), TabNames: tabNames, RecoveryState: domain.RecoveryFresh}
+	return domain.CatalogueRecord{Name: s.name, IncarnationID: s.incarnation, Cwd: s.cwd, CreatedAt: createdAt, UpdatedAt: updatedAt, LastUsedSeq: s.mruAt.Load(), TabNames: tabNames, RecoveryState: domain.RecoveryFresh}
 }
 func (d *Daemon) closeTab(sess *session, tb *tab, repaint bool) error {
 		return nil
 	}
 	ringing := tb.attention
+	oldActive := sess.active
 	wasActive := idx == sess.active
 	sess.tabs = append(sess.tabs[:idx], sess.tabs[idx+1:]...)
+	tabsAfterClose := len(sess.tabs)
 	if sess.active >= len(sess.tabs) {
 		sess.active = len(sess.tabs) - 1
 	} else if idx < sess.active {
 	destination := sess.tabs[sess.active]
 	ac := sess.client
 	name := sess.name
-	record := sess.persistRecordLocked(time.Now().UnixNano())
+	record, metadataVersion := sess.nextPersistRecordLocked(max(d.nowUnixNano(), sess.createdAt, int64(1)))
 	ephemeral := sess.ephemeral
+	sess.mu.Unlock()
+	d.mu.Unlock()
 	if !ephemeral {
-		if err := d.updateCatalogueMetadata(record.MetadataUpdate()); err != nil {
+		rollback := func() bool {
+			d.mu.Lock()
+			defer d.mu.Unlock()
+			if d.sessions[sess.id] != sess {
+				return true
+			}
+			sess.mu.Lock()
+			defer sess.mu.Unlock()
+			if slices.Contains(sess.tabs, tb) {
+				return true
+			}
+			if len(sess.tabs) != tabsAfterClose {
+				return false
+			}
+			sess.tabs = slices.Insert(sess.tabs, min(idx, len(sess.tabs)), tb)
+			sess.active = min(oldActive, len(sess.tabs)-1)
+			return true
+		}
+		if err := d.persistSessionMetadata(sess, metadataVersion, record.MetadataUpdate(), rollback); err != nil {
 			d.log.Warn("persisting closed tab failed", "err", err, "session", name)
+			return err
 		}
 	}
-	sess.mu.Unlock()
-	d.mu.Unlock()
 	d.log.Info("tab closed", "session", name)
 	markSnapshotDirty(sess)
 // beginSnapshotPurge commits a logical named-session kill before its live
 // identity or persisted metadata is removed. It never runs under daemon or
 // session locks.
-func (d *Daemon) beginSnapshotPurge(name string, incarnation domain.IncarnationID) error {
+func (d *Daemon) beginSnapshotPurge(_ string, _ domain.IncarnationID) error {
-	if d.lifecycleRecovery != nil {
+	if d.persistEnabled && d.lifecycleRecovery == nil {
-		// The lifecycle coordinator performs the complete ordered protocol after
+		return errors.New("durable session authority is not configured")
-		// snapshot writers have joined.
-		return nil
-	}
-	if d.snapshotRepository == nil || name == "" {
-		return nil
 	}
-	return d.snapshotRepository.WriteDeletionTombstone(context.Background(), domain.DeletionTombstone{Name: name, IncarnationID: incarnation})
+	// The lifecycle coordinator performs the complete ordered protocol after
+	// snapshot writers have joined.
+	return nil
 }
 // finishSnapshotPurge deletes both independently durable snapshot sources,
 // then metadata, and only then clears the tombstone. Any failure deliberately
 // leaves the marker in place so startup cannot restore or import the name and
 // a later live/offline kill can retry the idempotent source deletes.
-func (d *Daemon) finishSnapshotPurge(name string, incarnation domain.IncarnationID) error {
+func (d *Daemon) finishSnapshotPurge(ctx context.Context, name string, _ domain.IncarnationID) error {
-	if d.lifecycleRecovery != nil {
+	if !d.persistEnabled {
-		return d.lifecycleRecovery.Delete(context.Background(), name)
+		return nil
-	}
-	if d.snapshotRepository == nil {
-		return d.deleteCatalogueRecord(name)
 	}
-	if err := d.snapshotRepository.QuarantineDeletionSources(context.Background(), domain.DeletionTombstone{Name: name, IncarnationID: incarnation}, false); err != nil {
+	if d.lifecycleRecovery == nil {
-		return err
+		return errors.New("durable session authority is not configured")
 	}
-	if err := d.deleteCatalogueRecord(name); err != nil {
+	if ctx == nil {
-		return err
+		ctx = d.serveCtx
 	}
-	return d.snapshotRepository.DeleteDeletionTombstone(context.Background(), incarnation)
+	purgeCtx, cancel := context.WithTimeout(ctx, snapshotFinalFlushTimeout)
+	defer cancel()
+	return d.lifecycleRecovery.Delete(purgeCtx, name)
 }
 // retryStoppedPurge completes a previously closed session's durable purge.
 // It keeps the stopped record hidden until all sources and metadata cross their
 // deletion boundaries.
 func (d *Daemon) retryStoppedPurge(name string) error {
+	return d.retryStoppedPurgeContext(d.serveCtx, name)
+}
+func (d *Daemon) retryStoppedPurgeContext(ctx context.Context, name string) error {
 	d.mu.Lock()
 	stopped, ok := d.stopped[name]
 	if !ok {
 		d.mu.Unlock()
 		return nil
 	}
-	// Without a repository there is no restore/import source to fence, so the
-	// stopped record retains the metadata-only deletion behavior.
-	if d.snapshotRepository == nil {
-		d.mu.Unlock()
-		if err := d.deleteCatalogueRecord(name); err != nil {
-			return err
-		}
-		d.mu.Lock()
-		delete(d.stopped, name)
-		d.mu.Unlock()
-		return nil
-	}
 	stopped.purging = true
 	d.stopped[name] = stopped
 	d.mu.Unlock()
 	if err := d.beginSnapshotPurge(name, stopped.incarnation); err != nil {
 		return err
 	}
-	if err := d.finishSnapshotPurge(name, stopped.incarnation); err != nil {
+	if err := d.finishSnapshotPurge(ctx, name, stopped.incarnation); err != nil {
 		return err
 	}
 	d.mu.Lock()
 	}
 	defer sess.finishTeardown()
+	// A rename reserves durable identity while coordinator I/O runs unlocked.
+	// Teardown waits for that reservation before selecting the purge name.
+	sess.mu.Lock()
+	renameDone := sess.renameDone
+	sess.mu.Unlock()
+	if renameDone != nil {
+		if deadline == nil {
+			<-renameDone
+		} else {
+			select {
+			case <-renameDone:
+			case <-deadline.Done():
+				return context.DeadlineExceeded
+			}
+		}
+	}
 	d.mu.Lock()
 	current := d.sessions[sess.id]
 	d.mu.Unlock()
 	sess.mu.Lock()
 	isEphemeral := sess.ephemeral
 	name := sess.name
+	incarnation := sess.incarnation
 	sess.mu.Unlock()
 	// Commit the tombstone before changing live identity or metadata. A
 	// repository delete must never race an older publication that could recreate
 	// the just-quarantined name. Do not hold daemon or session locks while
 	// tombstoning or joining: a repository implementation may block on I/O.
 	if purge && !isEphemeral {
-		if err := d.beginSnapshotPurge(name, sess.incarnation); err != nil {
+		if err := d.beginSnapshotPurge(name, incarnation); err != nil {
 			return err
 		}
 		if d.snapshotRepository != nil {
 	ephemeral := sess.ephemeral
 	sess.mu.Unlock()
 	if !ephemeral {
-		stopped := stoppedSession{name: stoppedName, cwd: stoppedCwd, createdAt: createdAt, incarnation: sess.incarnation, lastUsedSeq: sess.mruAt.Load(), tabNames: tabNames, purging: purge}
+		stopped := stoppedSession{name: stoppedName, cwd: stoppedCwd, createdAt: createdAt, incarnation: incarnation, lastUsedSeq: sess.mruAt.Load(), tabNames: tabNames, purging: purge}
 		d.stopped[stoppedName] = stopped
 	}
 	empty := len(d.sessions) == 0
 	// tombstone and hidden stopped record when any source or metadata operation
 	// fails; retryStoppedPurge (including a repeated live kill) resumes safely.
 	if !ephemeral && purge {
-		if err := d.finishSnapshotPurge(stoppedName, sess.incarnation); err != nil {
+		if err := d.finishSnapshotPurge(d.serveCtx, stoppedName, incarnation); err != nil {
 			purgeErr = errors.Join(purgeErr, err)
 			d.log.Warn("finishing session snapshot purge failed", "err", err, "session", stoppedName)
 		} else {
 	if d.findByNameLocked(name) != nil {
 		return true
 	}
-	_, ok := d.stopped[name]
+	if _, ok := d.stopped[name]; ok {
-	return ok
+		return true
+	}
+	_, reserved := d.creating[name]
+	return reserved
 }
 func (d *Daemon) cwdSampler(ctx context.Context) {
 		d.mu.Unlock()
 		return
 	}
+	oldCwd := sess.cwd
 	sess.cwd = cwd
 	name := sess.name
-	incarnation := sess.incarnation
 	ephemeral := sess.ephemeral
+	var record domain.CatalogueRecord
+	var metadataVersion uint64
+	if !ephemeral {
+		record, metadataVersion = sess.nextPersistRecordLocked(max(d.nowUnixNano(), sess.createdAt, int64(1)))
+	}
 	sess.mu.Unlock()
+	d.mu.Unlock()
 	if !ephemeral {
-		updatedAt := time.Now().UnixNano()
+		rollback := func() bool {
-		if err := d.updateCatalogueMetadata(domain.CatalogueMetadataUpdate{Name: name, IncarnationID: incarnation, Cwd: &cwd, UpdatedAt: &updatedAt}); err != nil {
+			d.mu.Lock()
+			defer d.mu.Unlock()
+			if d.sessions[sess.id] != sess {
+				return true
+			}
+			sess.mu.Lock()
+			defer sess.mu.Unlock()
+			if sess.cwd != cwd {
+				return false
+			}
+			sess.cwd = oldCwd
+			return true
+		}
+		if err := d.persistSessionMetadata(sess, metadataVersion, record.MetadataUpdate(), rollback); err != nil {
 			d.log.Warn("touching persisted session cwd failed", "err", err, "session", name)
+			return
 		}
 		markSnapshotDirty(sess)
 	}
-	d.mu.Unlock()
 }
 // childEnv retains the daemon-environment helper for daemon-local legacy callers.
 }
 func environmentEntry(entry string) (name, value string, ok bool) {
-	i := strings.IndexByte(entry, '=')
+	name, value, ok = strings.Cut(entry, "=")
-	if i < 0 {
+	return name, value, ok
-		return "", "", false
-	}
-	return entry[:i], entry[i+1:], true
 }
 func (d *Daemon) ptyCommand(env []string) (string, []string) {

M internal/usecase/daemon/session_purge_control_test.go +5 -20

 	"errors"
 	"testing"
-	"github.com/stretchr/testify/mock"
 	"github.com/stretchr/testify/require"
-	"github.com/bnema/vev/internal/ports"
+	"github.com/bnema/vev/internal/domain"
 	portsmocks "github.com/bnema/vev/internal/ports/mocks"
 )
-func TestHandleKillStoppedUsesDurableBothSourcePurge(t *testing.T) {
-	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
-	repository := &retryablePurgeRepository{legacyErr: errors.New("legacy delete failed")}
-	WithSnapshotRepository(repository, repository)(d)
-	d.stopped["work"] = stoppedSession{name: "work"}
-	transport := portsmocks.NewMockTransport(t)
-	transport.EXPECT().Send(mock.Anything).Return(nil).Once()
-	transport.EXPECT().Close().Return(nil).Once()
-	d.handleKill(transport, ports.Frame{Type: ports.MsgKill, Payload: ports.MarshalKill(ports.Kill{Name: "work"})})
-	require.Equal(t, []string{"tombstone", "incremental", "legacy"}, repository.calls)
-	require.True(t, repository.tombstoned["work"])
-	require.True(t, d.stopped["work"].purging)
-}
 func TestStoppedPurgeMetadataFailureRemainsFencedForRetry(t *testing.T) {
 	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
 	repository := &retryablePurgeRepository{}
-	WithSnapshotRepository(repository, repository)(d)
+	WithSnapshotRepository(repository)(d)
 	store, state := newMockStore(t)
 	WithStore(store)(d)
+	record := domain.CatalogueRecord{Name: "work", IncarnationID: domain.IncarnationID{1}, RecoveryState: domain.RecoveryFresh}
+	require.NoError(t, d.catalogue.Create(record))
 	metadataErr := errors.New("metadata delete failed")
 	state.mu.Lock()
 	state.deleteErr = func(string) error { return metadataErr }
 	state.mu.Unlock()
-	d.stopped["work"] = stoppedSession{name: "work"}
+	d.stopped["work"] = stoppedSession{name: "work", incarnation: record.IncarnationID, record: record}
 	require.ErrorIs(t, d.retryStoppedPurge("work"), metadataErr)
 	require.True(t, repository.tombstoned["work"])

M internal/usecase/daemon/session_purge_retry_test.go +20 -4

 	legacyErr      error
 	tombstoned     map[string]bool
 	calls          []string
+	deadlineScoped []bool
 }
 func (r *retryablePurgeRepository) Publish(context.Context, ports.SnapshotPublication) error {
 	return nil
 }
-func (r *retryablePurgeRepository) WriteDeletionTombstone(_ context.Context, tombstone domain.DeletionTombstone) error {
+func (r *retryablePurgeRepository) WriteDeletionTombstone(ctx context.Context, tombstone domain.DeletionTombstone) error {
+	_, hasDeadline := ctx.Deadline()
+	r.deadlineScoped = append(r.deadlineScoped, hasDeadline)
 	if r.tombstoned == nil {
 		r.tombstoned = make(map[string]bool)
 	}
 	r.tombstoned[tombstone.Name] = true
 	return nil
 }
-func (r *retryablePurgeRepository) QuarantineDeletionSources(_ context.Context, tombstone domain.DeletionTombstone, _ bool) error {
+func (r *retryablePurgeRepository) QuarantineDeletionSources(ctx context.Context, tombstone domain.DeletionTombstone, _ bool) error {
+	_, hasDeadline := ctx.Deadline()
+	r.deadlineScoped = append(r.deadlineScoped, hasDeadline)
 	r.calls = append(r.calls, "incremental", "legacy")
 	if r.incrementalErr != nil {
 		return r.incrementalErr
 	}
 	return r.legacyErr
 }
-func (r *retryablePurgeRepository) DeleteDeletionTombstone(_ context.Context, _ domain.IncarnationID) error {
+func (r *retryablePurgeRepository) DeleteDeletionTombstone(ctx context.Context, _ domain.IncarnationID) error {
+	_, hasDeadline := ctx.Deadline()
+	r.deadlineScoped = append(r.deadlineScoped, hasDeadline)
 	r.calls = append(r.calls, "clear tombstone")
 	for name := range r.tombstoned {
 		delete(r.tombstoned, name)
 		t.Run(tt.name, func(t *testing.T) {
 			d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
 			repository := &retryablePurgeRepository{incrementalErr: tt.incremental, legacyErr: tt.legacy}
-			WithSnapshotRepository(repository, repository)(d)
+			WithSnapshotRepository(repository)(d)
+			store, _ := newMockStore(t)
+			WithStore(store)(d)
 			sess := newSnapshotTestSession(t, "work", false, "/work")
+			record := sess.persistRecordLocked(1)
+			record.RecoveryState = domain.RecoveryFresh
+			require.NoError(t, d.catalogue.Create(record))
 			pty, ok := sess.tabs[0].panes["pane-1"].pty.(*portsmocks.MockPTY)
 			require.True(t, ok, "snapshot test pane must use MockPTY")
 			pty.EXPECT().Close().Return(nil).Once()
 			require.NoError(t, d.retryStoppedPurge("work"))
 			require.False(t, repository.tombstoned["work"])
 			require.Equal(t, []string{"tombstone", "incremental", "legacy", "tombstone", "incremental", "legacy", "clear tombstone"}, repository.calls)
+			require.NotEmpty(t, repository.deadlineScoped)
+			for _, scoped := range repository.deadlineScoped {
+				require.True(t, scoped, "every purge repository call must receive a deadline-scoped context")
+			}
 			d.mu.Lock()
 			_, ok = d.stopped["work"]
 			d.mu.Unlock()

M internal/usecase/daemon/session_rename_purge_test.go +26 -29

@@ -1,43 +1,40 @@
1		package daemon	1		package daemon
2			2
3		import (	3		import (
			4	+	"errors"
4		"testing"	5		"testing"
5			6
6		"github.com/stretchr/testify/require"	7		"github.com/stretchr/testify/require"
7			8
8		"github.com/bnema/vev/internal/domain"	9		"github.com/bnema/vev/internal/domain"
			10	+	"github.com/bnema/vev/internal/persist"
9		portsmocks "github.com/bnema/vev/internal/ports/mocks"	11		portsmocks "github.com/bnema/vev/internal/ports/mocks"
10		)	12		)
11			13
12		func TestRenamePreservesIncarnationSnapshotSources(t *testing.T) {	14		func TestRenamePreservesIncarnationSnapshotSources(t *testing.T) {
13	-	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})	15	+	legacyDeleteErr := errors.New("legacy delete failed")
14	-	repository := &retryablePurgeRepository{}	16	+	for _, tt := range []struct {
15	-	WithSnapshotRepository(repository, repository)(d)	17	+	name string
16	-	store, state := newMockStore(t)	18	+	legacyErr error
17	-	WithStore(store)(d)	19	+	}{
18	-	sess := newSnapshotTestSession(t, "old", false, "/work")	20	+	{name: "snapshot sources available"},
19	-	d.sessions = map[domain.SessionID]*session{sess.id: sess}	21	+	{name: "unrelated legacy source delete would fail", legacyErr: legacyDeleteErr},
20	-	require.NoError(t, d.persist.Save(sess.persistRecordLocked(1)))	22	+	} {
			23	+	t.Run(tt.name, func(t *testing.T) {
			24	+	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
			25	+	repository := &retryablePurgeRepository{legacyErr: tt.legacyErr}
			26	+	WithSnapshotRepository(repository)(d)
			27	+	store, state := newMockStore(t)
			28	+	WithStore(store)(d)
			29	+	sess := newSnapshotTestSession(t, "old", false, "/work")
			30	+	d.sessions = map[domain.SessionID]*session{sess.id: sess}
			31	+	require.NoError(t, d.catalogue.(*persist.Persister).Save(sess.persistRecordLocked(1)))
21			32
22	-	require.NoError(t, d.renameSession(sess, "new"))	33	+	require.NoError(t, d.renameSession(sess, "new"))
23	-	require.Empty(t, repository.calls, "rename must not touch incarnation-keyed snapshot storage")	34	+	require.Empty(t, repository.calls, "rename must not invoke source deletion, including a failing legacy source")
24	-	require.False(t, state.has("old"))	35	+	require.False(t, state.has("old"))
25	-	require.True(t, state.has("new"))	36	+	require.True(t, state.has("new"))
26	-	require.Equal(t, sess.incarnation, state.record(t, "new").IncarnationID)	37	+	require.Equal(t, sess.incarnation, state.record(t, "new").IncarnationID)
27	-	}	38	+	})
28	-		39	+	}
29	-	func TestRenameIgnoresUnrelatedLegacySourceFailure(t *testing.T) {
30	-	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
31	-	repository := &retryablePurgeRepository{}
32	-	WithSnapshotRepository(repository, repository)(d)
33	-	store, state := newMockStore(t)
34	-	WithStore(store)(d)
35	-	sess := newSnapshotTestSession(t, "old", false, "/work")
36	-	d.sessions = map[domain.SessionID]*session{sess.id: sess}
37	-	require.NoError(t, d.persist.Save(sess.persistRecordLocked(1)))
38	-
39	-	require.NoError(t, d.renameSession(sess, "new"))
40	-	require.Empty(t, repository.calls)
41	-	require.False(t, state.has("old"))
42	-	require.True(t, state.has("new"))
43		}	40		}

M internal/usecase/daemon/session_test.go +54 -28

 func (s newStaticStore) Set(_, _ []byte) error { return nil }
 func (s newStaticStore) Delete(_ []byte) error { return nil }
 func (s newStaticStore) Batch(changes []ports.StoreChange) error {
-	for _, change := range changes {
+	if len(changes) == 0 {
+		return errors.New("empty batch")
+	}
+	prepared := make([]ports.StoreChange, len(changes))
+	seen := make(map[string]struct{}, len(changes))
+	for i, change := range changes {
+		key := string(change.Key)
+		if _, exists := seen[key]; exists {
+			return errors.New("duplicate batch key")
+		}
+		if change.Delete && len(change.Value) != 0 {
+			return errors.New("delete batch change has value")
+		}
+		seen[key] = struct{}{}
+		prepared[i] = ports.StoreChange{Key: append([]byte(nil), change.Key...), Value: append([]byte(nil), change.Value...), Delete: change.Delete}
+	}
+	for _, change := range prepared {
 		if change.Delete {
 			delete(s, string(change.Key))
 		} else {
-			s[string(change.Key)] = append([]byte(nil), change.Value...)
+			s[string(change.Key)] = change.Value
 		}
 	}
 	return nil
 	store, _ := newMockStore(t)
 	seed := New(nil, stubClock{}, slog.New(slog.NewTextHandler(io.Discard, nil)), WithStore(store))
 	incarnation := domain.IncarnationID{1}
-	require.NoError(t, seed.persist.Save(persist.Record{Name: "work", IncarnationID: incarnation, Cwd: "/tmp/work", CreatedAt: 7, UpdatedAt: 8, LastUsedSeq: 9, RecoveryState: domain.RecoveryFresh}))
+	require.NoError(t, seed.catalogue.(*persist.Persister).Save(persist.Record{Name: "work", IncarnationID: incarnation, Cwd: "/tmp/work", CreatedAt: 7, UpdatedAt: 8, LastUsedSeq: 9, RecoveryState: domain.RecoveryFresh}))
 	d := New(nil, stubClock{}, slog.New(slog.NewTextHandler(io.Discard, nil)), WithStore(store))
 	d.mu.Lock()
 	stopped := d.stopped["work"]
 	d.mu.Unlock()
-	require.Equal(t, stoppedSession{name: "work", cwd: "/tmp/work", createdAt: 7, incarnation: incarnation, lastUsedSeq: 9}, stopped)
+	require.Equal(t, "work", stopped.name)
+	require.Equal(t, "/tmp/work", stopped.cwd)
+	require.Equal(t, int64(7), stopped.createdAt)
+	require.Equal(t, incarnation, stopped.incarnation)
+	require.Equal(t, uint64(9), stopped.lastUsedSeq)
+	require.Equal(t, domain.RecoveryFresh, stopped.record.RecoveryState)
+	require.Equal(t, runtimeFresh, stopped.state)
+	require.NotNil(t, stopped.restoreDone)
 	require.Equal(t, uint64(9), d.mruSeq.Load())
 }
 // TestDaemonNewWithoutPersistenceLogsNoLoadWarning covers the default,
 // persistence-free construction path (no WithStore/WithCatalogue option):
-// d.persist is the persist.New(nil) sentinel, so LoadAll now returns
+// d.catalogue.(*persist.Persister) is the persist.New(nil) sentinel, so LoadAll now returns
 // errPersistenceUnavailable instead of an empty slice. That must not surface
 // as a "loading persisted sessions failed" warning, since nothing failed —
 // persistence simply was never configured.
 	require.NotContains(t, logBuf.String(), "loading persisted sessions failed")
 }
-// TestDaemonNewWithConfiguredStoreStillLogsLoadFailure is the inverse of the
-// above: when persistence IS configured (a real store via WithStore) and the
-// load genuinely fails (an undecodable catalogue record here), the warning
-// must still fire.
-func TestDaemonNewWithConfiguredStoreStillLogsLoadFailure(t *testing.T) {
-	store, state := newMockStore(t)
-	state.data["bad"] = []byte{0, 1} // not a valid encoded catalogue record
-	var logBuf strings.Builder
-	d := New(nil, stubClock{}, slog.New(slog.NewTextHandler(&logBuf, nil)), WithStore(store))
-	require.NotNil(t, d)
-	require.True(t, d.persistEnabled)
-	require.Contains(t, logBuf.String(), "loading persisted sessions failed")
-}
 func TestTouchMRUConcurrentUpdatesRemainMonotonic(t *testing.T) {
 	d := &Daemon{}
 	sess := &session{}
 	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
 	WithStore(store)(d)
 	named := &session{name: "work", tabs: []*tab{{}}, createdAt: 1, incarnation: domain.IncarnationID{1}}
-	require.NoError(t, d.persist.Save(persist.Record{Name: "work", IncarnationID: named.incarnation, Cwd: "/work", CreatedAt: 1, UpdatedAt: 1, RecoveryState: domain.RecoveryFresh}))
+	require.NoError(t, d.catalogue.(*persist.Persister).Save(persist.Record{Name: "work", IncarnationID: named.incarnation, Cwd: "/work", CreatedAt: 1, UpdatedAt: 1, RecoveryState: domain.RecoveryFresh}))
 	d.touchMRU(named)
 	require.Equal(t, named.mruAt.Load(), state.record(t, "work").LastUsedSeq)
 	require.NoError(t, err)
 	require.NoError(t, d.renameTab(sess, sess.tabs[0], "shell"))
-	records, err := d.persist.LoadAll()
+	records, err := d.catalogue.(*persist.Persister).LoadAll()
 	require.NoError(t, err)
 	require.Len(t, records, 1)
 	require.Equal(t, "work", records[0].Name)
 	require.Equal(t, []string{"shell"}, records[0].TabNames)
 }
+func TestRenameTabDoesNotHoldDaemonOrSessionMutexDuringCatalogueIO(t *testing.T) {
+	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
+	sess := newSnapshotTestSession(t, "work", false, "/work")
+	d.sessions[sess.id] = sess
+	catalogue := portsmocks.NewMockCatalogue(t)
+	WithCatalogue(catalogue, nil)(d)
+	catalogue.EXPECT().UpdateMetadata(mock.Anything).RunAndReturn(func(domain.CatalogueMetadataUpdate) error {
+		require.True(t, d.mu.TryLock(), "daemon mutex held during catalogue I/O")
+		d.mu.Unlock()
+		require.True(t, sess.mu.TryLock(), "session mutex held during catalogue I/O")
+		sess.mu.Unlock()
+		return nil
+	}).Once()
+	require.NoError(t, d.renameTab(sess, sess.tabs[0], "shell"))
+}
 func TestTabNamePersistenceTracksTabIndexShifts(t *testing.T) {
 	tests := []struct {
 		name       string
 			}
 			require.NoError(t, d.closeTab(sess, sess.tabs[tt.closeIndex], false))
-			records, err := d.persist.LoadAll()
+			records, err := d.catalogue.(*persist.Persister).LoadAll()
 			require.NoError(t, err)
 			require.Len(t, records, 1)
 			require.Equal(t, tt.want, records[0].TabNames)
 	require.Equal(t, "shell", sess.tabs[0].name)
 	require.False(t, state.has("0"))
-	records, err := d.persist.LoadAll()
+	records, err := d.catalogue.(*persist.Persister).LoadAll()
 	require.NoError(t, err)
 	require.Empty(t, records)
 }
 	store, _ := newMockStore(t)
 	d := newTestDaemon(t, newFactorySeq(t, p1, p2), stubClock{})
 	WithStore(store)(d)
-	require.NoError(t, d.persist.Save(persist.Record{Name: "work", IncarnationID: domain.IncarnationID{1}, Cwd: "/tmp/work", CreatedAt: 7, UpdatedAt: 8, TabNames: []string{"shell", "logs"}, RecoveryState: domain.RecoveryFresh}))
+	require.NoError(t, d.catalogue.(*persist.Persister).Save(persist.Record{Name: "work", IncarnationID: domain.IncarnationID{1}, Cwd: "/tmp/work", CreatedAt: 7, UpdatedAt: 8, TabNames: []string{"shell", "logs"}, RecoveryState: domain.RecoveryFresh}))
 	d.stopped["work"] = stoppedSession{name: "work", cwd: "/tmp/work", createdAt: 7, tabNames: []string{"shell", "logs"}}
 	tr := portsmocks.NewMockTransport(t)
 	tr.EXPECT().Send(mock.Anything).Return(nil).Maybe()
 		defer release()
 		store := portsmocks.NewMockStore(t)
 		var attempted map[string][]byte
-		store.EXPECT().Range(mock.Anything).Run(func(func([]byte, []byte) bool) {}).Twice()
+		store.EXPECT().Range(mock.Anything).Run(func(func([]byte, []byte) bool) {}).Times(3)
-		store.EXPECT().Get([]byte("named")).Return(nil, false).Twice()
+		store.EXPECT().Get([]byte("named")).Return(nil, false).Times(4)
 		store.EXPECT().Batch(mock.Anything).RunAndReturn(func(changes []ports.StoreChange) error {
 			attempted = make(map[string][]byte, len(changes))
 			for _, change := range changes {
 	store, state := newMockStore(t)
 	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
 	WithStore(store)(d)
-	require.NoError(t, d.persist.Save(persist.Record{Name: "old", IncarnationID: domain.IncarnationID{1}, Cwd: "/tmp", CreatedAt: 1, UpdatedAt: 1, RecoveryState: domain.RecoveryFresh}))
+	require.NoError(t, d.catalogue.(*persist.Persister).Save(persist.Record{Name: "old", IncarnationID: domain.IncarnationID{1}, Cwd: "/tmp", CreatedAt: 1, UpdatedAt: 1, RecoveryState: domain.RecoveryFresh}))
 	d.stopped["old"] = stoppedSession{name: "old", cwd: "/tmp", createdAt: 1}
 	require.NoError(t, d.killPickerTarget(picker.Target{Name: "old", Stopped: true}))
 	require.False(t, state.has("old"))
 func TestNamedSessionLifecycleTimestampStartsAfterPersistedHighWaterMark(t *testing.T) {
 	store, _ := newMockStore(t)
 	seed := New(nil, stubClock{}, slog.New(slog.NewTextHandler(io.Discard, nil)), WithStore(store))
-	require.NoError(t, seed.persist.Save(persist.Record{Name: "old", IncarnationID: domain.IncarnationID{1}, Cwd: "/tmp", CreatedAt: 900, UpdatedAt: 900, RecoveryState: domain.RecoveryFresh}))
+	require.NoError(t, seed.catalogue.(*persist.Persister).Save(persist.Record{Name: "old", IncarnationID: domain.IncarnationID{1}, Cwd: "/tmp", CreatedAt: 900, UpdatedAt: 900, RecoveryState: domain.RecoveryFresh}))
 	p, release := newBlockingPTY(t)
 	defer release()

M internal/usecase/daemon/snapshot.go +6 -0


@@ -47,6 +47,9 @@ type snapshotCapture struct {
47	publicationContext context.Context	47		publicationContext context.Context
48	sealedRefs map[*vt.HistoryChunk]snapcodec.ObjectRef // set by the single encoder worker	48		sealedRefs map[*vt.HistoryChunk]snapcodec.ObjectRef // set by the single encoder worker
49	coordinatorDiscarded bool // guarded by session.snapshotMu	49		coordinatorDiscarded bool // guarded by session.snapshotMu
		50	+	// normalWorkerAdmitted is set before snapshotJobs admission and immutable
		51	+	// until completion; final-queue captures leave it false.
		52	+	normalWorkerAdmitted bool
50	finishOnce sync.Once	53		finishOnce sync.Once
51	}	54		}
52		55

@@ -98,3 +101,6 @@ const (
98	snapshotInterval = 2 * time.Minute	101		snapshotInterval = 2 * time.Minute
99	snapshotFinalFlushTimeout = time.Second	102		snapshotFinalFlushTimeout = time.Second
100	)	103		)
		104	+
		105	+	// SnapshotShutdownTimeout reports the shared final-checkpoint shutdown budget.
		106	+	func SnapshotShutdownTimeout() time.Duration { return snapshotFinalFlushTimeout }

M internal/usecase/daemon/snapshot_coordinator.go +13 -0


@@ -108,6 +108,14 @@ func (d Daemon) waitForSnapshotGenerationWithDeadline(sess session, generation
108	return d.waitForSnapshotGeneration(sess, generation)	108		return d.waitForSnapshotGeneration(sess, generation)
109	}	109		}
110	for {	110		for {
		111	+	// Once the shared deadline is observable, timeout wins even if publication
		112	+	// completion becomes ready concurrently. This preserves the timed-out
		113	+	// session identity and avoids nondeterministic success after the budget.
		114	+	select {
		115	+	case <-deadline.Done():
		116	+	return false
		117	+	default:
		118	+	}
111	sess.snapshotMu.Lock()	119		sess.snapshotMu.Lock()
112	published := sess.snapshotPublishedMutationRevision >= generation	120		published := sess.snapshotPublishedMutationRevision >= generation
113	changed := sess.snapshotChangeLocked()	121		changed := sess.snapshotChangeLocked()

@@ -207,6 +215,11 @@ func (d Daemon) finishSnapshotCapture(capture snapshotCapture, succeeded bool)
207	capture.session.signalSnapshotChangedLocked()	215		capture.session.signalSnapshotChangedLocked()
208	wake := capture.session.snapshotWake	216		wake := capture.session.snapshotWake
209	capture.session.snapshotMu.Unlock()	217		capture.session.snapshotMu.Unlock()
		218	+	if capture.normalWorkerAdmitted {
		219	+	d.snapshotWorkerMu.Lock()
		220	+	delete(d.snapshotAdmitted, capture)
		221	+	d.snapshotWorkerMu.Unlock()
		222	+	}
210	if wake != nil {	223		if wake != nil {
211	select {	224		select {
212	case wake <- struct{}{}:	225		case wake <- struct{}{}:

M internal/usecase/daemon/snapshot_generation_test.go +2 -2


@@ -17,7 +17,7 @@ import (
17		func TestSnapshotMultipleMutationsPublishNextRepositoryGeneration(t *testing.T) {	17		func TestSnapshotMultipleMutationsPublishNextRepositoryGeneration(t *testing.T) {
18		d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})	18		d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
19		repository := portsmocks.NewMockSnapshotRepository(t)	19		repository := portsmocks.NewMockSnapshotRepository(t)
20	-	WithSnapshotRepository(repository, nil)(d)	20	+	WithSnapshotRepository(repository)(d)
21		startSnapshotEncodeWorker(t, d)	21		startSnapshotEncodeWorker(t, d)
22			22
23		publications := make(chan ports.SnapshotPublication, 1)	23		publications := make(chan ports.SnapshotPublication, 1)

@@ -44,7 +44,7 @@ func TestSnapshotMultipleMutationsPublishNextRepositoryGeneration(t *testing.T)
44		func TestSnapshotRetryKeepsRepositoryGeneration(t *testing.T) {	44		func TestSnapshotRetryKeepsRepositoryGeneration(t *testing.T) {
45		d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})	45		d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
46		repository := portsmocks.NewMockSnapshotRepository(t)	46		repository := portsmocks.NewMockSnapshotRepository(t)
47	-	WithSnapshotRepository(repository, nil)(d)	47	+	WithSnapshotRepository(repository)(d)
48		startSnapshotEncodeWorker(t, d)	48		startSnapshotEncodeWorker(t, d)
49			49
50		publications := make(chan ports.SnapshotPublication, 2)	50		publications := make(chan ports.SnapshotPublication, 2)

D internal/usecase/daemon/snapshot_import_test.go +0 -163

@@ -1,163 +0,0 @@
1	-	package daemon
2	-
3	-	import (
4	-	"context"
5	-	"encoding/base64"
6	-	"errors"
7	-	"os"
8	-	"path/filepath"
9	-	"testing"
10	-
11	-	"github.com/stretchr/testify/require"
12	-
13	-	"github.com/bnema/vev/internal/ports"
14	-	snapcodec "github.com/bnema/vev/internal/usecase/snapshot"
15	-	)
16	-
17	-	type snapshotAcceptanceLegacySource struct {
18	-	blobs []ports.LegacySnapshot
19	-	loadCalls int
20	-	deleteCalls []string
21	-	deleteErr error
22	-	}
23	-
24	-	func (s *snapshotAcceptanceLegacySource) LoadLegacy(ctx context.Context) ([]ports.LegacySnapshot, error) {
25	-	if err := ctx.Err(); err != nil {
26	-	return nil, err
27	-	}
28	-	s.loadCalls++
29	-	out := make([]ports.LegacySnapshot, len(s.blobs))
30	-	for i, blob := range s.blobs {
31	-	out[i] = ports.LegacySnapshot{Name: blob.Name, Data: append([]byte(nil), blob.Data...)}
32	-	}
33	-	return out, nil
34	-	}
35	-
36	-	func (s *snapshotAcceptanceLegacySource) DeleteVerifiedLegacy(ctx context.Context, blob ports.LegacySnapshot) error {
37	-	return s.DeleteLegacy(ctx, blob.Name)
38	-	}
39	-
40	-	func (s *snapshotAcceptanceLegacySource) DeleteLegacy(ctx context.Context, name string) error {
41	-	if err := ctx.Err(); err != nil {
42	-	return err
43	-	}
44	-	s.deleteCalls = append(s.deleteCalls, name)
45	-	if s.deleteErr != nil {
46	-	return s.deleteErr
47	-	}
48	-	for i, blob := range s.blobs {
49	-	if blob.Name == name {
50	-	s.blobs = append(s.blobs[:i], s.blobs[i+1:]...)
51	-	break
52	-	}
53	-	}
54	-	return nil
55	-	}
56	-
57	-	func legacyAcceptanceSnapshot(t *testing.T) snapcodec.Session {
58	-	t.Helper()
59	-	data, err := os.ReadFile(filepath.Join("testdata", "legacy-v3-empty.b64"))
60	-	require.NoError(t, err)
61	-	encoded, err := base64.StdEncoding.DecodeString(string(data))
62	-	require.NoError(t, err)
63	-	snapshot, err := snapcodec.Unmarshal(encoded)
64	-	require.NoError(t, err)
65	-	return snapshot
66	-	}
67	-
68	-	func legacyAcceptanceBlob(t *testing.T, snapshot snapcodec.Session) ports.LegacySnapshot {
69	-	t.Helper()
70	-	fixture := legacyAcceptanceSnapshot(t)
71	-	require.Equal(t, fixture, snapshot, "legacy fixture must be the imported session")
72	-	data, err := os.ReadFile(filepath.Join("testdata", "legacy-v3-empty.b64"))
73	-	require.NoError(t, err)
74	-	encoded, err := base64.StdEncoding.DecodeString(string(data))
75	-	require.NoError(t, err)
76	-	return ports.LegacySnapshot{Name: snapshot.Name, Data: encoded}
77	-	}
78	-
79	-	func TestLegacyPublicationMarshalObjectErrorsIdentifyPaneAndStage(t *testing.T) {
80	-	for _, tt := range []struct {
81	-	name string
82	-	mutate func(*snapcodec.Pane)
83	-	stage string
84	-	}{
85	-	{name: "sealed chunk", mutate: func(pane *snapcodec.Pane) { pane.SealedChunks = [][]byte{nil} }, stage: "sealed chunk 0"},
86	-	{name: "tail", mutate: func(pane *snapcodec.Pane) { pane.Tail = nil }, stage: "tail"},
87	-	{name: "visible", mutate: func(pane *snapcodec.Pane) { pane.Visible = nil }, stage: "visible"},
88	-	} {
89	-	t.Run(tt.name, func(t *testing.T) {
90	-	pane := snapcodec.Pane{ID: "pane-1", StableID: "pane-stable", Tail: []byte("tail"), Visible: []byte("visible")}
91	-	tt.mutate(&pane)
92	-	snapshot := snapcodec.Session{Name: "legacy", Tabs: []snapcodec.Tab{{StableID: "tab-1", Panes: []snapcodec.Pane{pane}}}}
93	-
94	-	_, err := legacyPublication(snapshot)
95	-	require.Error(t, err)
96	-	require.ErrorContains(t, err, `tab "tab-1"`)
97	-	require.ErrorContains(t, err, `pane "pane-1"`)
98	-	require.ErrorContains(t, err, tt.stage)
99	-	require.ErrorContains(t, err, "marshal object")
100	-	})
101	-	}
102	-	}
103	-
104	-	func TestImportLegacySnapshotsIsRetiredRuntimeNoop(t *testing.T) {
105	-	snapshot := legacyAcceptanceSnapshot(t)
106	-	repository := &snapshotAcceptanceRepository{generations: make(map[string]ports.SnapshotGeneration)}
107	-	legacy := &snapshotAcceptanceLegacySource{blobs: []ports.LegacySnapshot{legacyAcceptanceBlob(t, snapshot)}}
108	-	d := newTestDaemon(t, nil, stubClock{})
109	-	WithSnapshotRepository(repository, legacy)(d)
110	-
111	-	d.importLegacySnapshots(context.Background())
112	-
113	-	// Migration is adapter-owned. The daemon must never name-scan, publish, or
114	-	// delete a legacy source during normal recovery.
115	-	require.Empty(t, repository.publishes)
116	-	require.Empty(t, legacy.deleteCalls)
117	-	require.Len(t, legacy.blobs, 1)
118	-	}
119	-
120	-	func TestImportLegacyExistingIncrementalSkipsLegacy(t *testing.T) {
121	-	snapshot := legacyAcceptanceSnapshot(t)
122	-	repository := &snapshotAcceptanceRepository{names: []string{snapshot.Name}, generations: make(map[string]ports.SnapshotGeneration)}
123	-	legacy := &snapshotAcceptanceLegacySource{blobs: []ports.LegacySnapshot{legacyAcceptanceBlob(t, snapshot)}}
124	-	d := newTestDaemon(t, nil, stubClock{})
125	-	WithSnapshotRepository(repository, legacy)(d)
126	-
127	-	d.importLegacySnapshots(context.Background())
128	-
129	-	require.Empty(t, repository.publishes)
130	-	require.Empty(t, legacy.deleteCalls)
131	-	require.Len(t, legacy.blobs, 1)
132	-	}
133	-
134	-	func TestImportLegacyRetainsSourceUntilExactReloadVerification(t *testing.T) {
135	-	snapshot := legacyAcceptanceSnapshot(t)
136	-	for _, test := range []struct {
137	-	name string
138	-	publish error
139	-	load error
140	-	mutate func(ports.SnapshotGeneration, ports.SnapshotPublication) ports.SnapshotGeneration
141	-	}{
142	-	{"publish failure", errors.New("publish failed"), nil, nil},
143	-	{"reload failure", nil, errors.New("reload failed"), nil},
144	-	{"manifest metadata mismatch", nil, nil, func(g ports.SnapshotGeneration, _ ports.SnapshotPublication) ports.SnapshotGeneration {
145	-	g.Generation++
146	-	return g
147	-	}},
148	-	{"manifest bytes mismatch", nil, nil, func(g ports.SnapshotGeneration, _ ports.SnapshotPublication) ports.SnapshotGeneration {
149	-	g.Manifest[len(g.Manifest)-1] ^= 1
150	-	return g
151	-	}},
152	-	} {
153	-	t.Run(test.name, func(t *testing.T) {
154	-	repository := &snapshotAcceptanceRepository{generations: make(map[string]ports.SnapshotGeneration), publishErr: test.publish, loadErr: test.load, loadMutate: test.mutate}
155	-	legacy := &snapshotAcceptanceLegacySource{blobs: []ports.LegacySnapshot{legacyAcceptanceBlob(t, snapshot)}}
156	-	d := newTestDaemon(t, nil, stubClock{})
157	-	WithSnapshotRepository(repository, legacy)(d)
158	-	d.importLegacySnapshots(context.Background())
159	-	require.Empty(t, legacy.deleteCalls)
160	-	require.Len(t, legacy.blobs, 1)
161	-	})
162	-	}
163	-	}

M internal/usecase/daemon/snapshot_queue.go +6 -0


@@ -107,10 +107,16 @@ func (d Daemon) enqueueSnapshotCapture(capture snapshotCapture) bool {
107	if d.snapshotWorkerClosing \|\| d.snapshotWorkerCancel == nil \|\| d.snapshotWorkerCtx == nil \|\| d.snapshotWorkerCtx.Err() != nil {	107		if d.snapshotWorkerClosing \|\| d.snapshotWorkerCancel == nil \|\| d.snapshotWorkerCtx == nil \|\| d.snapshotWorkerCtx.Err() != nil {
108	return false	108		return false
109	}	109		}
		110	+	capture.normalWorkerAdmitted = true
110	select {	111		select {
111	case d.snapshotJobs <- capture:	112		case d.snapshotJobs <- capture:
		113	+	if d.snapshotAdmitted == nil {
		114	+	d.snapshotAdmitted = make(map[*snapshotCapture]struct{})
		115	+	}
		116	+	d.snapshotAdmitted[capture] = struct{}{}
112	return true	117		return true
113	default:	118		default:
		119	+	capture.normalWorkerAdmitted = false
114	return false	120		return false
115	}	121		}
116	}	122		}

M internal/usecase/daemon/snapshot_restore.go +23 -6

 import (
 	"context"
 	"crypto/rand"
+	"errors"
 	"fmt"
 	"math"
 )
 func (d *Daemon) closeRestoreDone() {
+	d.mu.Lock()
+	for name, entry := range d.stopped {
+		if entry.state != runtimeRestoring {
+			continue
+		}
+		entry.state = runtimeDegraded
+		entry.record.RecoveryState = domain.RecoveryDegraded
+		if entry.record.DegradedReason == "" {
+			entry.record.DegradedReason = "restore unavailable"
+		}
+		d.stopped[name] = entry
+		closeRuntimeRestoreDoneLocked(entry.restoreDone)
+	}
+	d.mu.Unlock()
 	d.restoreOnce.Do(func() { close(d.restoreDone) })
 }
 			}
 		}
 	}
-	// An existing catalogue checkpoint already authorizes this runtime. Only a
+	// Restoration is catalogue-authorized. Missing or unreadable authority is a
-	// legacy snapshot without a catalogue record creates fresh metadata here.
+	// hard failure; migration creates catalogue records before daemon startup.
 	if d.persistEnabled {
-		if _, ok := d.catalogueRecord(sess.name); !ok {
+		_, ok, err := d.catalogueRecord(sess.name)
-			if err := d.createCatalogueRecord(sess.persistRecordLocked(sess.createdAt)); err != nil {
+		if err != nil {
-				return false, err
+			return false, err
-			}
+		}
+		if !ok {
+			return false, errors.New("snapshot: restored session is absent from catalogue")
 		}
 	}
 	d.mu.Lock()

R internal/usecase/daemon/snapshot_legacy_import.go → internal/usecase/daemon/snapshot_restore_fixture_test.go +2 -3 renamed, 91% similar

 	snapcodec "github.com/bnema/vev/internal/usecase/snapshot"
 )
-func legacyPublication(snapshot snapcodec.Session) (ports.SnapshotPublication, error) {
+func acceptancePublication(snapshot snapcodec.Session) (ports.SnapshotPublication, error) {
-	// Legacy payloads have no durable identity; this test-only conversion uses
+	// acceptancePublication converts a restore fixture to repository form.
-	// the fixture's stable synthetic identity.
 	incarnation := domain.IncarnationID{1}
 	manifest := snapcodec.Manifest{Generation: 1, IncarnationID: incarnation, Name: snapshot.Name, CreatedAt: snapshot.CreatedAt, Active: snapshot.Active, Tabs: make([]snapcodec.ManifestTab, 0, len(snapshot.Tabs))}
 	objects := make([]ports.SnapshotObject, 0)

M internal/usecase/daemon/snapshot_restore_incremental.go +53 -10

 	if d.catalogue == nil {
 		return
 	}
-	d.restoreCatalogue(ctx, d.catalogue.Records())
+	records, err := d.catalogue.Records()
+	if err != nil {
+		d.log.Error("loading catalogue for snapshot restoration failed", "err", err)
+		return
+	}
+	d.restoreCatalogue(ctx, records)
 }
 // restoreCatalogue gives every expected record an independent bounded job.
 	return d.stopped[name].restoreDone
 }
-func closeRuntimeRestoreDone(done chan struct{}) {
+// closeRuntimeRestoreDoneLocked closes a per-record restoration barrier.
+// Caller must hold d.mu so state transition and waiter release are atomic.
+func closeRuntimeRestoreDoneLocked(done chan struct{}) {
 	if done == nil {
 		return
 	}
 func (d *Daemon) finishRecordRestore(record domain.CatalogueRecord, restoreErr error, done chan struct{}) {
 	if restoreErr != nil {
+		catalogueReadable := true
 		if d.catalogue != nil {
-			if current, ok := d.catalogue.Record(record.Name); ok && current.IncarnationID == record.IncarnationID {
+			current, ok, readErr := d.catalogue.Record(record.Name)
+			if readErr != nil {
+				catalogueReadable = false
+				d.log.Error("reading catalogue before degradation failed", "session", record.Name, "err", readErr)
+			} else if ok && current.IncarnationID == record.IncarnationID {
 				record = current
 			}
 		}
 		if errors.Is(restoreErr, context.Canceled) || errors.Is(restoreErr, context.DeadlineExceeded) {
 			record.DegradedReason = "restore interrupted"
 		}
-		if d.catalogue != nil {
+		if d.catalogue != nil && catalogueReadable {
 			if err := d.catalogue.Replace(record.Name, record); err != nil {
 				d.log.Error("marking session degraded failed", "session", record.Name, "err", err)
 			}
 			entry.tabNames = append([]string(nil), record.TabNames...)
 			d.stopped[record.Name] = entry
 		}
-		closeRuntimeRestoreDone(done)
+		closeRuntimeRestoreDoneLocked(done)
 	}
 	d.mu.Unlock()
 	if restoreErr != nil {
 	var selectedGeneration ports.SnapshotGeneration
 	var selectedSnapshot snapcodec.Session
 	selectedIndex := -1
+	selectedFallback := false
 	for i, candidate := range candidates {
+		fallback := record.Committed == nil || i > 0
 		generation, err := d.snapshotRepository.LoadCheckpoint(ctx, record.IncarnationID, record.Name, candidate)
 		if err != nil {
 			if ctxErr := ctx.Err(); ctxErr != nil {
 				return ctxErr
 			}
+			d.logRejectedRestoreCandidate(record, candidate, fallback, "load-failed", err)
 			continue
 		}
-		snapshot, err := sessionFromGeneration(generation)
+		snapshot, decodeErr := sessionFromGeneration(generation)
-		if err != nil || generation.IncarnationID != record.IncarnationID || generation.Name != record.Name || generation.Generation != candidate.Generation {
+		if decodeErr != nil {
+			d.logRejectedRestoreCandidate(record, candidate, fallback, "decode-failed", decodeErr)
 			continue
 		}
-		selected, selectedGeneration, selectedSnapshot, selectedIndex = candidate, generation, snapshot, i
+		if generation.IncarnationID != record.IncarnationID {
+			d.logRejectedRestoreCandidate(record, candidate, fallback, "incarnation-mismatch", nil)
+			continue
+		}
+		if generation.Name != record.Name {
+			d.logRejectedRestoreCandidate(record, candidate, fallback, "name-mismatch", nil)
+			continue
+		}
+		if generation.Generation != candidate.Generation {
+			d.logRejectedRestoreCandidate(record, candidate, fallback, "generation-mismatch", nil)
+			continue
+		}
+		selected, selectedGeneration, selectedSnapshot, selectedIndex, selectedFallback = candidate, generation, snapshot, i, fallback
 		break
 	}
 	if selectedIndex < 0 {
 		return errors.New("snapshot: no catalogue checkpoint validated")
 	}
-	if selectedIndex > 0 {
+	if selectedFallback {
 		if d.checkpointRecovery == nil {
 			return errors.New("snapshot: checkpoint coordinator unavailable for fallback promotion")
 		}
 		return err
 	}
 	d.setStoppedRecovery(record, runtimeHealthy)
-	d.logSessionRestoreComplete(record, selected.Generation, selectedIndex > 0)
+	d.logSessionRestoreComplete(record, selected.Generation, selectedFallback)
 	return nil
 }
+func (d *Daemon) logRejectedRestoreCandidate(record domain.CatalogueRecord, candidate domain.CheckpointRef, fallback bool, reason string, err error) {
+	kind := "committed"
+	if fallback {
+		kind = "fallback"
+	}
+	d.log.Warn("snapshot_restore_candidate_rejected",
+		"session", record.Name,
+		"incarnation", record.IncarnationID.String(),
+		"generation", candidate.Generation,
+		"candidate", kind,
+		"reason_code", reason,
+		"err", err,
+	)
+}
 func checkpointCandidates(record domain.CatalogueRecord) []domain.CheckpointRef {
 	candidates := make([]domain.CheckpointRef, 0, 3)
 	if record.Committed != nil {

M internal/usecase/daemon/snapshot_restore_test.go +6 -7

 func acceptanceGeneration(t *testing.T, snapshot snapcodec.Session, generation uint64) ports.SnapshotGeneration {
 	t.Helper()
-	publication, err := legacyPublication(snapshot)
+	publication, err := acceptancePublication(snapshot)
 	require.NoError(t, err)
 	manifest, err := snapcodec.UnmarshalManifest(publication.Manifest)
 	require.NoError(t, err)
 	repository := &snapshotAcceptanceRepository{names: []string{snapshot.Name}, generations: map[string]ports.SnapshotGeneration{snapshot.Name: generation}}
 	pty, release := newBlockingPTY(t)
 	d := newTestDaemon(t, newFactory(t, pty), stubClock{})
-	store, _ := newMockStore(t)
-	WithStore(store)(d)
 	checkpoint := domain.CheckpointRef{Generation: generation.Generation, ManifestDigest: snapcodec.ManifestDigest(generation.Manifest)}
 	record := domain.CatalogueRecord{Name: snapshot.Name, IncarnationID: generation.IncarnationID, Cwd: "/snapshot/cwd", CreatedAt: int64(snapshot.CreatedAt), RecoveryState: domain.RecoveryHealthy, Committed: &checkpoint}
 	catalogue := newDurableRecoveryCatalogue([]domain.CatalogueRecord{record})
 	WithCatalogue(catalogue, []domain.CatalogueRecord{record})(d)
-	WithSnapshotRepository(repository, nil)(d)
+	WithSnapshotRepository(repository)(d)
+	WithRecoveryCoordinator(recoveryusecase.NewCoordinator(catalogue, repository, nil, nil))(d)
 	t.Cleanup(func() { release(); d.sessWg.Wait() })
 	d.restoreIncrementalSnapshots(context.Background())
 	d := newTestDaemon(t, newFactory(t, pty), stubClock{})
 	coordinator := recoveryusecase.NewCoordinator(catalogue, repository, nil, nil)
 	WithCatalogue(catalogue, []domain.CatalogueRecord{record})(d)
-	WithSnapshotRepository(repository, nil)(d)
+	WithSnapshotRepository(repository)(d)
 	WithCheckpointCoordinator(coordinator)(d)
 	t.Cleanup(func() { release(); d.sessWg.Wait() })
 	updates := catalogue.MetadataUpdates()
 	require.Len(t, updates, 1, "the authoritative Catalogue port must receive restored-session metadata updates")
 	require.Equal(t, record.IncarnationID, updates[0].IncarnationID)
-	updated, ok := catalogue.Record(record.Name)
+	updated, ok, _ := catalogue.Record(record.Name)
 	require.True(t, ok)
 	require.Equal(t, record.IncarnationID, updated.IncarnationID)
 	require.Equal(t, record.RecoveryState, updated.RecoveryState)
 	require.Empty(t, failure)
 	require.Len(t, repository.publishes, 1)
 	require.Equal(t, record.Committed, repository.publishes[0].ParentCheckpoint)
-	published, ok := catalogue.Record(record.Name)
+	published, ok, _ := catalogue.Record(record.Name)
 	require.True(t, ok)
 	require.Equal(t, uint64(10), published.Committed.Generation)
 	require.Equal(t, committed, *published.Fallbacks[0])

M internal/usecase/daemon/snapshot_scheduler_test.go +27 -21

 func TestSnapshotCoordinatorQuarantineCancelsPublicationBeforeDelete(t *testing.T) {
 	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
 	repository := portsmocks.NewMockSnapshotRepository(t)
-	WithSnapshotRepository(repository, nil)(d)
+	WithSnapshotRepository(repository)(d)
 	startSnapshotEncodeWorker(t, d)
 	started := make(chan struct{})
 func TestSnapshotCoordinatorQuarantineJoinsInFlightPublication(t *testing.T) {
 	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
 	repository := portsmocks.NewMockSnapshotRepository(t)
-	WithSnapshotRepository(repository, nil)(d)
+	WithSnapshotRepository(repository)(d)
 	startSnapshotEncodeWorker(t, d)
 	started := make(chan struct{})
 func TestForcedSnapshotSchedulesSuccessorAfterRoutineInFlight(t *testing.T) {
 	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
 	repository := portsmocks.NewMockSnapshotRepository(t)
-	WithSnapshotRepository(repository, nil)(d)
+	WithSnapshotRepository(repository)(d)
 	startSnapshotEncodeWorker(t, d)
 	started := make(chan struct{})
 func TestForcedSnapshotSchedulesSuccessorForRoutineCaptureQueuedBehindWorker(t *testing.T) {
 	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
 	repository := portsmocks.NewMockSnapshotRepository(t)
-	WithSnapshotRepository(repository, nil)(d)
+	WithSnapshotRepository(repository)(d)
 	startSnapshotEncodeWorker(t, d)
 	blockerStarted := make(chan struct{})
 func TestMultipleForcedSnapshotsCoalesceToOneSuccessor(t *testing.T) {
 	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
 	repository := portsmocks.NewMockSnapshotRepository(t)
-	WithSnapshotRepository(repository, nil)(d)
+	WithSnapshotRepository(repository)(d)
 	startSnapshotEncodeWorker(t, d)
 	started := make(chan struct{})
 	clock := newSnapshotDeadlineClock()
 	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), clock)
 	repository := portsmocks.NewMockSnapshotRepository(t)
-	WithSnapshotRepository(repository, nil)(d)
+	WithSnapshotRepository(repository)(d)
 	notices := portsmocks.NewMockNoticeStore(t)
 	WithNoticeStore(notices)(d)
 	startSnapshotEncodeWorker(t, d)
 	clock := newServeShutdownClock()
 	d := newTestDaemon(t, newFactory(t, pty), clock)
 	repository := portsmocks.NewMockSnapshotRepository(t)
-	WithSnapshotRepository(repository, nil)(d)
+	WithSnapshotRepository(repository)(d)
 	publicationStarted := make(chan struct{})
 	releasePublication := make(chan struct{})
 	tr, sends, _ := newConn(t, mustHello(ports.IntentNew, "work", domain.Size{Cols: 80, Rows: 24}))
 	listener := serveSnapshotListener(t, tr)
-	ctx, cancel := context.WithCancel(context.Background())
+	ctx, cancel := context.WithCancel(t.Context())
 	defer cancel()
 	served := make(chan error, 1)
 	go func() { served <- d.Serve(ctx, listener) }()
 func TestConcurrentSessionTeardownPublishesOneFinalSnapshot(t *testing.T) {
 	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
 	repository := portsmocks.NewMockSnapshotRepository(t)
-	WithSnapshotRepository(repository, nil)(d)
+	WithSnapshotRepository(repository)(d)
 	startSnapshotEncodeWorker(t, d)
 	publicationStarted := make(chan struct{})
 	defer releasePTY()
 	d := newTestDaemon(t, newFactory(t, p), stubClock{})
 	repository := portsmocks.NewMockSnapshotRepository(t)
-	WithSnapshotRepository(repository, nil)(d)
+	WithSnapshotRepository(repository)(d)
 	published := make(chan ports.SnapshotPublication, 2)
 	allowTerminalPublication := make(chan struct{})
 	tr, sends, _ := newConn(t, mustHello(ports.IntentNew, "work", domain.Size{Cols: 80, Rows: 24}))
 	l := serveSnapshotListener(t, tr)
-	ctx, cancel := context.WithCancel(context.Background())
+	ctx, cancel := context.WithCancel(t.Context())
 	defer cancel()
 	served := make(chan error, 1)
 	go func() { served <- d.Serve(ctx, l) }()
 	clock := newServeShutdownClock()
 	d := newTestDaemon(t, newFactory(t, p), clock)
 	repository := portsmocks.NewMockSnapshotRepository(t)
-	WithSnapshotRepository(repository, nil)(d)
+	WithSnapshotRepository(repository)(d)
 	noticeStore := portsmocks.NewMockNoticeStore(t)
 	WithNoticeStore(noticeStore)(d)
 	noticeStore.EXPECT().Claim().Return(nil, nil).Maybe()
 	noticeStore.EXPECT().Ack().Return(nil).Maybe()
+	noticePersisted := make(chan struct{})
 	noticeStore.EXPECT().Append(mock.MatchedBy(func(n domain.Notification) bool {
 		return n.Code == domain.NoticeSnapshotWrite && n.Severity == domain.NoticeError
-	})).Return(nil).Once()
+	})).Run(func(domain.Notification) { close(noticePersisted) }).Return(nil).Once()
 	firstPublicationCompleted := make(chan struct{})
 	terminalPublicationStarted := make(chan struct{})
 	tr, sends, _ := newConn(t, mustHello(ports.IntentNew, "work", domain.Size{Cols: 80, Rows: 24}))
 	l := serveSnapshotListener(t, tr)
-	ctx, cancel := context.WithCancel(context.Background())
+	ctx, cancel := context.WithCancel(t.Context())
 	defer cancel()
 	served := make(chan error, 1)
 	go func() { served <- d.Serve(ctx, l) }()
 	d.snapshotWorkerMu.Unlock()
 	require.NotNil(t, workerDone)
 	clock.nextFinalTimer(t).fire()
+	select {
+	case <-noticePersisted:
+	case <-time.After(testWaitTimeout):
+		t.Fatal("shutdown timeout notice was not persisted before the writer join")
+	}
 	select {
 	case err := <-served:
 	clock := &snapshotSchedulerClock{now: time.Unix(100, 0)}
 	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), clock)
 	repository := portsmocks.NewMockSnapshotRepository(t)
-	WithSnapshotRepository(repository, nil)(d)
+	WithSnapshotRepository(repository)(d)
 	startSnapshotEncodeWorker(t, d)
 	var publishes atomic.Int32
 	clock := newDeterministicSnapshotClock(now)
 	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), clock)
 	repository := portsmocks.NewMockSnapshotRepository(t)
-	WithSnapshotRepository(repository, nil)(d)
+	WithSnapshotRepository(repository)(d)
 	for _, tt := range []struct {
 		name             string
 	now := time.Unix(100, 0)
 	clock := newDeterministicSnapshotClock(now)
 	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), clock)
-	WithSnapshotRepository(portsmocks.NewMockSnapshotRepository(t), nil)(d)
+	WithSnapshotRepository(portsmocks.NewMockSnapshotRepository(t))(d)
 	t.Run("no prior attempt is immediately eligible", func(t *testing.T) {
 		published := make(chan ports.SnapshotPublication, 1)
 		repository := portsmocks.NewMockSnapshotRepository(t)
-		WithSnapshotRepository(repository, nil)(d)
+		WithSnapshotRepository(repository)(d)
 		startSnapshotEncodeWorker(t, d)
 		repository.EXPECT().Publish(mock.Anything, mock.Anything).RunAndReturn(func(_ context.Context, publication ports.SnapshotPublication) error {
 			published <- publication
 	clock := newDeterministicSnapshotClock(now)
 	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), clock)
 	repository := portsmocks.NewMockSnapshotRepository(t)
-	WithSnapshotRepository(repository, nil)(d)
+	WithSnapshotRepository(repository)(d)
 	startSnapshotEncodeWorker(t, d)
 	started := make(chan struct{})
 	clock := newDeterministicSnapshotClock(now)
 	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), clock)
 	repository := portsmocks.NewMockSnapshotRepository(t)
-	WithSnapshotRepository(repository, nil)(d)
+	WithSnapshotRepository(repository)(d)
 	startSnapshotEncodeWorker(t, d)
 	published := make(chan ports.SnapshotPublication, 1)
 	later.snapshotNextEligibleAt = now.Add(10 * time.Minute)
 	d.sessions[later.id] = later
-	ctx, cancel := context.WithCancel(context.Background())
+	ctx, cancel := context.WithCancel(t.Context())
 	done := make(chan struct{})
 	go func() {
 		d.snapshotRepositorySaver(ctx)

M internal/usecase/daemon/snapshot_test.go +39 -1


@@ -17,10 +17,45 @@ import (
17			17
18		// TestSnapshotWorkerPublishesContentAddressedCapture verifies that all new	18		// TestSnapshotWorkerPublishesContentAddressedCapture verifies that all new
19		// checkpoints use the repository publication contract.	19		// checkpoints use the repository publication contract.
			20	+	func TestWithSnapshotRepositoryRejectsTypedNil(t *testing.T) {
			21	+	var repository *snapshotAcceptanceRepository
			22	+	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
			23	+
			24	+	WithSnapshotRepository(repository)(d)
			25	+
			26	+	require.Nil(t, d.snapshotRepository)
			27	+	require.False(t, d.snapsEnabled)
			28	+	}
			29	+
			30	+	func TestDurableWriterFailureNamesIncludesBufferedCapture(t *testing.T) {
			31	+	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
			32	+	capture := &snapshotCapture{name: "work", session: newSnapshotTestSession(t, "work", false, "/work")}
			33	+	d.snapshotWorkerMu.Lock()
			34	+	d.snapshotAdmitted[capture] = struct{}{}
			35	+	d.snapshotJobs <- capture
			36	+	d.snapshotWorkerMu.Unlock()
			37	+
			38	+	require.Equal(t, []string{"work"}, d.durableWriterFailureNames())
			39	+	}
			40	+
			41	+	func TestCheckpointPublicationWithoutCommittedRefFailsCapture(t *testing.T) {
			42	+	d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
			43	+	WithSnapshotRepository(portsmocks.NewMockSnapshotRepository(t))(d)
			44	+	coordinator := portsmocks.NewMockCheckpointCoordinator(t)
			45	+	WithCheckpointCoordinator(coordinator)(d)
			46	+	startSnapshotEncodeWorker(t, d)
			47	+	coordinator.EXPECT().PublishCheckpoint(mock.Anything, "work", mock.Anything).Return(domain.CatalogueRecord{Name: "work"}, nil).Once()
			48	+
			49	+	sess := newSnapshotTestSession(t, "work", false, "/work")
			50	+	require.True(t, d.captureSession(sess))
			51	+	awaitSnapshotIdle(t, sess)
			52	+	require.True(t, sess.snapDirty.Load(), "nil committed publication must remain retryable")
			53	+	}
			54	+
20		func TestSnapshotWorkerPublishesContentAddressedCapture(t *testing.T) {	55		func TestSnapshotWorkerPublishesContentAddressedCapture(t *testing.T) {
21		d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})	56		d := newTestDaemon(t, portsmocks.NewMockPTYFactory(t), stubClock{})
22		repository := portsmocks.NewMockSnapshotRepository(t)	57		repository := portsmocks.NewMockSnapshotRepository(t)
23	-	WithSnapshotRepository(repository, nil)(d)	58	+	WithSnapshotRepository(repository)(d)
24		startSnapshotEncodeWorker(t, d)	59		startSnapshotEncodeWorker(t, d)
25			60
26		repository.EXPECT().Publish(mock.Anything, mock.MatchedBy(func(p ports.SnapshotPublication) bool {	61		repository.EXPECT().Publish(mock.Anything, mock.MatchedBy(func(p ports.SnapshotPublication) bool {

@@ -57,6 +92,9 @@ func newSnapshotTestSession(t *testing.T, name string, ephemeral bool, cwd strin
57		// focused test sinks that only need to observe publication or deletion calls.	92		// focused test sinks that only need to observe publication or deletion calls.
58		type noOpSnapshotRepository struct{}	93		type noOpSnapshotRepository struct{}
59			94
			95	+	var _ ports.SnapshotRepository = noOpSnapshotRepository{}
			96	+
			97	+	func (noOpSnapshotRepository) Publish(context.Context, ports.SnapshotPublication) error { return nil }
60		func (noOpSnapshotRepository) LoadCheckpoint(context.Context, domain.IncarnationID, string, ports.CheckpointRef) (ports.SnapshotGeneration, error) {	98		func (noOpSnapshotRepository) LoadCheckpoint(context.Context, domain.IncarnationID, string, ports.CheckpointRef) (ports.SnapshotGeneration, error) {
61		return ports.SnapshotGeneration{}, errors.New("unused")	99		return ports.SnapshotGeneration{}, errors.New("unused")
62		}	100		}

M internal/usecase/daemon/snapshot_worker.go +18 -3

 import (
 	"context"
+	"errors"
 	"sort"
 	"github.com/bnema/vev/internal/domain"
 			if d.checkpointRecovery != nil {
 				var record domain.CatalogueRecord
 				record, err = d.checkpointRecovery.PublishCheckpoint(publicationContext, capture.name, publication)
-				if err == nil && record.Committed != nil {
+				if err == nil {
-					capture.checkpoint = *record.Committed
+					if record.Committed == nil {
+						err = errors.New("snapshot: checkpoint publication returned no committed checkpoint")
+					} else {
+						capture.checkpoint = *record.Committed
+					}
 				}
 			} else {
 				err = d.snapshotRepository.Publish(publicationContext, publication)
 	case <-done:
 		return nil
 	case <-ctx.Done():
+		// Snapshot identity before cancellation can let a cooperative worker clear
+		// its in-flight capture. The caller persists timeout notices before the
+		// unconditional ownership join.
+		names := d.durableWriterFailureNames()
 		cancel()
-		return d.durableWriterFailureNames()
+		return names
 	}
 }
 	return cancel, d.snapshotWorkerDone
 }
+// durableWriterFailureNames includes admitted buffered captures as well as the
+// active and final queues. snapshotAdmitted tracks normal captures from queue
+// admission through completion, so worker dequeue cannot make one disappear.
 func (d *Daemon) durableWriterFailureNames() []string {
 	d.snapshotWorkerMu.Lock()
 	defer d.snapshotWorkerMu.Unlock()
 	for _, capture := range d.snapshotFinalJobs {
 		add(capture)
 	}
+	for capture := range d.snapshotAdmitted {
+		add(capture)
+	}
 	names := make([]string, 0, len(seen))
 	for name := range seen {
 		names = append(names, name)

M internal/usecase/recovery/checkpoint.go +12 -15

 	unlock := c.locks.Lock([]string{name})
 	defer unlock()
-	record, ok := c.catalogue.Record(name)
+	record, ok, err := c.catalogue.Record(name)
+	if err != nil {
+		return domain.CatalogueRecord{}, err
+	}
 	if !ok {
 		return domain.CatalogueRecord{}, ErrCheckpointRecordNotFound
 	}
 }
 func (c *Coordinator) promoteFallbackLocked(ctx context.Context, name string, ref domain.CheckpointRef) (ports.FallbackPromotionOutcome, error) {
-	record, ok := c.catalogue.Record(name)
+	record, ok, err := c.catalogue.Record(name)
+	if err != nil {
+		return ports.FallbackPromotionOutcome{}, err
+	}
 	if !ok {
 		return ports.FallbackPromotionOutcome{}, ErrCheckpointRecordNotFound
 	}
 	if err != nil {
 		return err
 	}
-	if generation.IncarnationID != record.IncarnationID || generation.Name != record.Name || generation.Generation != ref.Generation ||
+	return validateLoadedGeneration(record, ref, generation)
-		sha256.Sum256(generation.Manifest) != ref.ManifestDigest {
-		return ErrCheckpointConflict
-	}
-	return nil
 }
-func equalCheckpointRefs(a, b *domain.CheckpointRef) bool {
+func equalCheckpointRefs(a, b *domain.CheckpointRef) bool { return a.Equal(b) }
-	if a == nil || b == nil {
-		return a == nil && b == nil
-	}
-	return *a == *b
-}
 func copyCheckpointRef(ref *domain.CheckpointRef) *domain.CheckpointRef {
 	if ref == nil {
 		return nil
 	}
-	copy := *ref
+	cloned := *ref
-	return &copy
+	return &cloned
 }

M internal/usecase/recovery/checkpoint_test.go +28 -26


@@ -20,13 +20,15 @@ type checkpointCatalogue struct {
20		events *[]string	20		events *[]string
21		}	21		}
22			22
23	-	func (c *checkpointCatalogue) Records() []domain.CatalogueRecord {	23	+	func (c *checkpointCatalogue) Records() ([]domain.CatalogueRecord, error) {
24	-	return []domain.CatalogueRecord{c.record}	24	+	c.mu.Lock()
			25	+	defer c.mu.Unlock()
			26	+	return []domain.CatalogueRecord{c.record}, nil
25		}	27		}
26	-	func (c *checkpointCatalogue) Record(name string) (domain.CatalogueRecord, bool) {	28	+	func (c *checkpointCatalogue) Record(name string) (domain.CatalogueRecord, bool, error) {
27		c.mu.Lock()	29		c.mu.Lock()
28		defer c.mu.Unlock()	30		defer c.mu.Unlock()
29	-	return c.record, c.record.Name == name	31	+	return c.record, c.record.Name == name, nil
30		}	32		}
31		func (c *checkpointCatalogue) Create(domain.CatalogueRecord) error { return nil }	33		func (c *checkpointCatalogue) Create(domain.CatalogueRecord) error { return nil }
32		func (c *checkpointCatalogue) UpdateMetadata(domain.CatalogueMetadataUpdate) error {	34		func (c *checkpointCatalogue) UpdateMetadata(domain.CatalogueMetadataUpdate) error {

@@ -127,33 +129,33 @@ func runCheckpointCommit(t testing.T, count int) (domain.CatalogueRecord, chec
127		catalogue.record, err = coordinator.PublishCheckpoint(context.Background(), "work", checkpointPublication(catalogue.record, generation))	129		catalogue.record, err = coordinator.PublishCheckpoint(context.Background(), "work", checkpointPublication(catalogue.record, generation))
128		require.NoError(t, err)	130		require.NoError(t, err)
129		}	131		}
130	-	for i := 0; i < count; i++ {	132	+	for i := range count {
131		require.Equal(t, []string{"repository", "catalogue"}, events[i2:i2+2])	133		require.Equal(t, []string{"repository", "catalogue"}, events[i2:i2+2])
132		}	134		}
133		return catalogue.record, catalogue, repository	135		return catalogue.record, catalogue, repository
134		}	136		}
135			137
136	-	func TestCheckpointCommitFirst(t *testing.T) {	138	+	func TestCheckpointCommits(t *testing.T) {
137	-	record, catalogue, _ := runCheckpointCommit(t, 1)	139	+	for _, tc := range []struct {
138	-	require.Equal(t, uint64(1), record.Committed.Generation)	140	+	name string
139	-	require.Empty(t, populatedGenerations(record.Fallbacks))	141	+	count int
140	-	require.Equal(t, 1, catalogue.replaces)	142	+	wantCommitted uint64
141	-	}	143	+	wantFallbacks []uint64
142	-		144	+	}{
143	-	func TestCheckpointCommitSecond(t *testing.T) {	145	+	{name: "first", count: 1, wantCommitted: 1},
144	-	record, catalogue, _ := runCheckpointCommit(t, 2)	146	+	{name: "second", count: 2, wantCommitted: 2, wantFallbacks: []uint64{1}},
145	-	require.Equal(t, uint64(2), record.Committed.Generation)	147	+	{name: "third", count: 3, wantCommitted: 3, wantFallbacks: []uint64{2, 1}},
146	-	require.Equal(t, []uint64{1}, populatedGenerations(record.Fallbacks))	148	+	{name: "fourth", count: 4, wantCommitted: 4, wantFallbacks: []uint64{3, 2}},
147	-	require.Equal(t, 2, catalogue.replaces)	149	+	} {
148	-	}	150	+	t.Run(tc.name, func(t *testing.T) {
149	-		151	+	record, catalogue, _ := runCheckpointCommit(t, tc.count)
150	-	func TestCheckpointCommitThird(t *testing.T) {	152	+	require.Equal(t, tc.wantCommitted, record.Committed.Generation)
151	-	record, catalogue, _ := runCheckpointCommit(t, 4)	153	+	require.Equal(t, tc.wantFallbacks, populatedGenerations(record.Fallbacks))
152	-	require.Equal(t, uint64(4), record.Committed.Generation)	154	+	require.Equal(t, domain.RecoveryHealthy, record.RecoveryState)
153	-	require.Equal(t, []uint64{3, 2}, populatedGenerations(record.Fallbacks))	155	+	require.Empty(t, record.DegradedReason)
154	-	require.Equal(t, domain.RecoveryHealthy, record.RecoveryState)	156	+	require.Equal(t, tc.count, catalogue.replaces)
155	-	require.Empty(t, record.DegradedReason)	157	+	})
156	-	require.Equal(t, 4, catalogue.replaces)	158	+	}
157		}	159		}
158			160
159		func TestCheckpointCommitThirdPromotesOnlyValidatedDirectFallbacks(t *testing.T) {	161		func TestCheckpointCommitThirdPromotesOnlyValidatedDirectFallbacks(t *testing.T) {

M internal/usecase/recovery/coordinator.go +32 -8

 	}
 	unlock := c.locks.Lock([]string{record.Name})
 	defer unlock()
-	if _, exists := c.catalogue.Record(record.Name); exists {
+	if _, exists, err := c.catalogue.Record(record.Name); err != nil {
+		return domain.CatalogueRecord{}, err
+	} else if exists {
 		return domain.CatalogueRecord{}, fmt.Errorf("recovery: session %q already exists", record.Name)
 	}
 	id, err := domain.NewIncarnationID(c.random)
 	}
 	unlock := c.locks.Lock([]string{oldName, newName})
 	defer unlock()
-	record, ok := c.catalogue.Record(oldName)
+	record, ok, err := c.catalogue.Record(oldName)
+	if err != nil {
+		return domain.CatalogueRecord{}, err
+	}
 	if !ok {
 		return domain.CatalogueRecord{}, fmt.Errorf("recovery: session %q not found", oldName)
 	}
-	if existing, exists := c.catalogue.Record(newName); exists && (newName != oldName || existing.IncarnationID != record.IncarnationID) {
+	if existing, exists, err := c.catalogue.Record(newName); err != nil {
+		return domain.CatalogueRecord{}, err
+	} else if exists && (newName != oldName || existing.IncarnationID != record.IncarnationID) {
 		return domain.CatalogueRecord{}, fmt.Errorf("recovery: session %q already exists", newName)
 	}
 	record.Name = newName
 	}
 	unlock := c.locks.Lock([]string{name})
 	defer unlock()
-	record, ok := c.catalogue.Record(name)
+	record, ok, err := c.catalogue.Record(name)
+	if err != nil {
+		return err
+	}
 	if !ok {
 		return nil
 	}
 			}
 		}
 	}
-	for _, candidate := range c.catalogue.Records() {
+	records, err := c.catalogue.Records()
+	if err != nil {
+		return err
+	}
+	for _, candidate := range records {
 		if candidate.RecoveryState != domain.RecoveryDeleting {
 			continue
 		}
 		unlock := c.locks.Lock([]string{candidate.Name})
 		var deleteErr error
-		current, ok := c.catalogue.Record(candidate.Name)
+		current, ok, readErr := c.catalogue.Record(candidate.Name)
+		if readErr != nil {
+			unlock()
+			return readErr
+		}
 		if ok && current.IncarnationID == candidate.IncarnationID && current.RecoveryState == domain.RecoveryDeleting {
 			deleteErr = c.deleteLocked(ctx, current)
 		}
 	unlock := c.locks.Lock([]string{name})
 	defer unlock()
-	record, ok := c.catalogue.Record(name)
+	record, ok, err := c.catalogue.Record(name)
+	if err != nil {
+		return err
+	}
 	if !ok || record.RecoveryState != domain.RecoveryHealthy {
 		// Fresh records cannot represent degraded state (it requires a committed
 		// checkpoint), and deleting or already degraded records must keep the
 	}
 	unlock := c.locks.Lock([]string{tombstone.Name})
 	defer unlock()
-	record, exists := c.catalogue.Record(tombstone.Name)
+	record, exists, err := c.catalogue.Record(tombstone.Name)
+	if err != nil {
+		return err
+	}
 	includeLegacyName := true
 	if exists {
 		switch {

M internal/usecase/recovery/discard.go +25 -15

 	}
 	unlock := c.locks.Lock([]string{name})
 	defer unlock()
-	record, ok := c.catalogue.Record(name)
+	record, ok, err := c.catalogue.Record(name)
+	if err != nil {
+		return err
+	}
 	if !ok {
 		return ErrRecoveryRecordNotFound
 	}
 	}
 	unlock := c.locks.Lock([]string{name})
 	defer unlock()
-	record, ok := c.catalogue.Record(name)
+	record, ok, err := c.catalogue.Record(name)
+	if err != nil {
+		return err
+	}
 	if !ok {
 		return ErrRecoveryRecordNotFound
 	}
 	}
 	unlock := c.locks.Lock([]string{name})
 	defer unlock()
-	record, ok := c.catalogue.Record(name)
+	record, ok, err := c.catalogue.Record(name)
+	if err != nil {
+		return err
+	}
 	if !ok {
 		return ErrRecoveryRecordNotFound
 	}
 	}
 	unlock := c.locks.Lock([]string{name})
 	defer unlock()
-	record, ok := c.catalogue.Record(name)
+	record, ok, err := c.catalogue.Record(name)
+	if err != nil {
+		return domain.CatalogueRecord{}, err
+	}
 	if !ok {
 		return domain.CatalogueRecord{}, ErrRecoveryRecordNotFound
 	}
 	if err := validateDiscardIntent(intent); err != nil {
 		return err
 	}
-	current, ok := c.catalogue.Record(intent.SessionName)
+	current, ok, err := c.catalogue.Record(intent.SessionName)
+	if err != nil {
+		return err
+	}
 	if !ok {
-		return fmt.Errorf("%w: missing session %q", ErrDiscardConflict, intent.SessionName)
+		// Catalogue deletion is terminal for this session identity. There is no
+		// live record to replace or quarantine, so retaining the intent would
+		// manufacture a permanent startup conflict.
+		return c.journal.DeleteDiscard(ctx, intent.OldIncarnation)
 	}
 	next := freshReplacement(intent)
 	if err := next.Validate(); err != nil {
 	}
 	switch current.IncarnationID {
 	case intent.OldIncarnation:
-		if !catalogueRecordsEqual(current, intent.OldRecord) {
+		if !current.Equal(intent.OldRecord) {
 			return fmt.Errorf("%w: old record changed", ErrDiscardConflict)
 		}
 	case intent.NewIncarnation:
 	next.DegradedReason = ""
 	return next
 }
-func catalogueRecordsEqual(a, b domain.CatalogueRecord) bool {
-	return a.Name == b.Name && a.IncarnationID == b.IncarnationID && a.Cwd == b.Cwd &&
-		a.CreatedAt == b.CreatedAt && a.UpdatedAt == b.UpdatedAt && a.LastUsedSeq == b.LastUsedSeq &&
-		slices.Equal(a.TabNames, b.TabNames) && a.RecoveryState == b.RecoveryState &&
-		equalCheckpointRefs(a.Committed, b.Committed) && equalCheckpointRefs(a.Fallbacks[0], b.Fallbacks[0]) &&
-		equalCheckpointRefs(a.Fallbacks[1], b.Fallbacks[1]) && a.DegradedReason == b.DegradedReason
-}

M internal/usecase/recovery/reconcile.go +26 -5

 	if err := ctx.Err(); err != nil {
 		return cursor, nil, err
 	}
-	next, findings, err := r.repository.Reconcile(ctx, r.catalogue.Records(), cursor, r.budget)
+	records, err := r.catalogue.Records()
+	if err != nil {
+		return cursor, nil, err
+	}
+	next, findings, err := r.repository.Reconcile(ctx, records, cursor, r.budget)
 	if err != nil {
 		return cursor, nil, err
 	}
 	decisions := make([]ports.ReconcileDecision, 0, len(findings))
+	consumed := ports.MaintenanceBudget{}
 	for _, finding := range findings {
-		if finding.Consumed.Entries > r.budget.Entries || finding.Consumed.Bytes > r.budget.Bytes {
+		// Compare against the remainder before adding. This both enforces the
+		// page-wide budget and avoids uint64 wraparound.
+		if finding.Consumed.Entries > r.budget.Entries-consumed.Entries ||
+			finding.Consumed.Bytes > r.budget.Bytes-consumed.Bytes {
 			return cursor, nil, errors.New("recovery: repository exceeded reconciliation budget")
 		}
-		record, ok := r.catalogue.Record(finding.Candidate.Name)
+		consumed.Entries += finding.Consumed.Entries
+		consumed.Bytes += finding.Consumed.Bytes
+		record, ok, err := r.catalogue.Record(finding.Candidate.Name)
+		if err != nil {
+			return cursor, nil, err
+		}
 		if !ok {
 			record = domain.CatalogueRecord{}
 		}
 		decision := classifyFinding(record, finding)
 		if decision.Kind == ports.ReconcileAdopt {
 			if _, err := r.coordinator.PublishReconciledCheckpoint(ctx, finding.Candidate.Name, finding.Candidate, finding.AncestorChain); err != nil {
-				return cursor, nil, err
+				if !errors.Is(err, ErrCheckpointConflict) && !errors.Is(err, ErrCheckpointRecordNotFound) {
+					return cursor, nil, err
+				}
+				decision.Kind = ports.ReconcileDefer
+				decision.ReasonCode = "catalogue-conflict"
+				decision.RetentionResolved = false
 			}
 		}
 		decisions = append(decisions, decision)
 	if err := ctx.Err(); err != nil {
 		return domain.CatalogueRecord{}, err
 	}
-	record, ok := c.catalogue.Record(name)
+	record, ok, err := c.catalogue.Record(name)
+	if err != nil {
+		return domain.CatalogueRecord{}, err
+	}
 	if !ok {
 		return domain.CatalogueRecord{}, ErrCheckpointRecordNotFound
 	}

M internal/usecase/recovery/reconcile_test.go +77 -0


@@ -24,6 +24,33 @@ type reconcilePage struct {
24	err error	24		err error
25	}	25		}
26		26
		27	+	type reconcileConflictCatalogue struct {
		28	+	*transactionCatalogue
		29	+	stale domain.CatalogueRecord
		30	+	reads int
		31	+	}
		32	+
		33	+	func (c *reconcileConflictCatalogue) Records() ([]domain.CatalogueRecord, error) {
		34	+	records, err := c.transactionCatalogue.Records()
		35	+	if err != nil {
		36	+	return nil, err
		37	+	}
		38	+	for i := range records {
		39	+	if records[i].Name == c.stale.Name {
		40	+	records[i] = c.stale
		41	+	}
		42	+	}
		43	+	return records, nil
		44	+	}
		45	+
		46	+	func (c *reconcileConflictCatalogue) Record(name string) (domain.CatalogueRecord, bool, error) {
		47	+	if name == c.stale.Name && c.reads == 0 {
		48	+	c.reads++
		49	+	return c.stale, true, nil
		50	+	}
		51	+	return c.transactionCatalogue.Record(name)
		52	+	}
		53	+
27	func (r *reconcileRepository) Reconcile(_ context.Context, _ []domain.CatalogueRecord, cursor ports.ReconcileCursor, budget ports.MaintenanceBudget) (ports.ReconcileCursor, []ports.ReconcileFinding, error) {	54		func (r *reconcileRepository) Reconcile(_ context.Context, _ []domain.CatalogueRecord, cursor ports.ReconcileCursor, budget ports.MaintenanceBudget) (ports.ReconcileCursor, []ports.ReconcileFinding, error) {
28	r.seenCursors = append(r.seenCursors, cursor)	55		r.seenCursors = append(r.seenCursors, cursor)
29	r.seenBudgets = append(r.seenBudgets, budget)	56		r.seenBudgets = append(r.seenBudgets, budget)

@@ -64,6 +91,56 @@ func TestReconciliationCursor(t *testing.T) {
64	require.Equal(t, []ports.MaintenanceBudget{{Entries: 2, Bytes: 32}, {Entries: 2, Bytes: 32}}, repository.seenBudgets)	91		require.Equal(t, []ports.MaintenanceBudget{{Entries: 2, Bytes: 32}, {Entries: 2, Bytes: 32}}, repository.seenBudgets)
65	}	92		}
66		93
		94	+	func TestReconciliationRejectsCumulativeAndOverflowingBudgets(t *testing.T) {
		95	+	record := healthyReconcileRecord()
		96	+	finding := ports.ReconcileFinding{Status: ports.ReconcileBudgetExhausted, Candidate: ports.ReconcileCandidate{Name: record.Name}}
		97	+	for _, tc := range []struct {
		98	+	name string
		99	+	budget ports.MaintenanceBudget
		100	+	consumed []ports.MaintenanceBudget
		101	+	}{
		102	+	{name: "cumulative entries", budget: ports.MaintenanceBudget{Entries: 3, Bytes: 10}, consumed: []ports.MaintenanceBudget{{Entries: 2, Bytes: 1}, {Entries: 2, Bytes: 1}}},
		103	+	{name: "cumulative bytes", budget: ports.MaintenanceBudget{Entries: 10, Bytes: 3}, consumed: []ports.MaintenanceBudget{{Entries: 1, Bytes: 2}, {Entries: 1, Bytes: 2}}},
		104	+	{name: "overflow safe", budget: ports.MaintenanceBudget{Entries: ^uint64(0), Bytes: ^uint64(0)}, consumed: []ports.MaintenanceBudget{{Entries: ^uint64(0), Bytes: ^uint64(0)}, {Entries: 1, Bytes: 1}}},
		105	+	} {
		106	+	t.Run(tc.name, func(t *testing.T) {
		107	+	findings := make([]ports.ReconcileFinding, len(tc.consumed))
		108	+	for i, usage := range tc.consumed {
		109	+	findings[i] = finding
		110	+	findings[i].Consumed = usage
		111	+	}
		112	+	repository := &reconcileRepository{pages: map[uint64]reconcilePage{0: {findings: findings}}}
		113	+	catalogue := &checkpointCatalogue{record: record}
		114	+	reconciler := NewReconciler(NewCoordinator(catalogue, repository, nil, nil), catalogue, repository, tc.budget)
		115	+	_, _, err := reconciler.Step(context.Background(), ports.ReconcileCursor{})
		116	+	require.EqualError(t, err, "recovery: repository exceeded reconciliation budget")
		117	+	})
		118	+	}
		119	+	}
		120	+
		121	+	func TestReconciliationDefersConflictAndContinues(t *testing.T) {
		122	+	first := healthyReconcileRecord()
		123	+	first.Name = "first"
		124	+	staleRecord := first
		125	+	stale := forwardCandidate(staleRecord, 2, staleRecord.Committed)
		126	+	first = shiftedCheckpoint(first, domain.CheckpointRef{Generation: 2, ManifestDigest: [32]byte{9}})
		127	+	second := healthyReconcileRecord()
		128	+	second.Name = "second"
		129	+	adoptable := forwardCandidate(second, 2, second.Committed)
		130	+	catalogue := &reconcileConflictCatalogue{transactionCatalogue: newTransactionCatalogue(first, second), stale: staleRecord}
		131	+	repository := &reconcileRepository{pages: map[uint64]reconcilePage{0: {findings: []ports.ReconcileFinding{
		132	+	{Kind: ports.ReconcileForwardOrphan, Status: ports.ReconcileValidated, Candidate: stale, Consumed: ports.MaintenanceBudget{Entries: 1, Bytes: 1}},
		133	+	{Kind: ports.ReconcileForwardOrphan, Status: ports.ReconcileValidated, Candidate: adoptable, Consumed: ports.MaintenanceBudget{Entries: 1, Bytes: 1}},
		134	+	}}}}
		135	+	reconciler := NewReconciler(NewCoordinator(catalogue, repository, nil, nil), catalogue, repository, ports.MaintenanceBudget{Entries: 2, Bytes: 2})
		136	+
		137	+	_, decisions, err := reconciler.Step(context.Background(), ports.ReconcileCursor{})
		138	+	require.NoError(t, err)
		139	+	require.Equal(t, []ports.ReconcileDecisionKind{ports.ReconcileDefer, ports.ReconcileAdopt}, []ports.ReconcileDecisionKind{decisions[0].Kind, decisions[1].Kind})
		140	+	require.Equal(t, "catalogue-conflict", decisions[0].ReasonCode)
		141	+	require.Equal(t, adoptable.Ref, *catalogue.records[second.Name].Committed)
		142	+	}
		143	+
67	func TestForwardOrphanAdoption(t *testing.T) {	144		func TestForwardOrphanAdoption(t *testing.T) {
68	for _, tc := range []struct {	145		for _, tc := range []struct {
69	name string	146		name string

M internal/usecase/recovery/transactions_test.go +21 -10

 	return catalogue
 }
-func (c *transactionCatalogue) Records() []domain.CatalogueRecord {
+func (c *transactionCatalogue) Records() ([]domain.CatalogueRecord, error) {
 	c.mu.Lock()
 	defer c.mu.Unlock()
 	out := make([]domain.CatalogueRecord, 0, len(c.records))
 	for _, record := range c.records {
 		out = append(out, record)
 	}
-	return out
+	return out, nil
 }
-func (c *transactionCatalogue) Record(name string) (domain.CatalogueRecord, bool) {
+func (c *transactionCatalogue) Record(name string) (domain.CatalogueRecord, bool, error) {
 	c.mu.Lock()
 	defer c.mu.Unlock()
 	record, ok := c.records[name]
-	return record, ok
+	return record, ok, nil
 }
 func (c *transactionCatalogue) Create(record domain.CatalogueRecord) error {
 	c.mu.Lock()
 	fallback := *record.Fallbacks[0]
 	catalogue := newTransactionCatalogue(record)
 	repository := newTransactionRepository()
-	repository.generations[fallback] = ports.SnapshotGeneration{
+	manifest := []byte("fallback")
-		IncarnationID: record.IncarnationID, Name: record.Name, Generation: fallback.Generation,
+	fallback.ManifestDigest = checkpointDigest(manifest)
-		Manifest: []byte("fallback"),
-	}
-	fallback.ManifestDigest = checkpointDigest(repository.generations[*record.Fallbacks[0]].Manifest)
 	record.Fallbacks[0] = &fallback
 	catalogue.records[record.Name] = record
 	repository.generations[fallback] = ports.SnapshotGeneration{
 		IncarnationID: record.IncarnationID, Name: record.Name, Generation: fallback.Generation,
-		Manifest: []byte("fallback"),
+		Manifest: manifest,
 	}
 	coordinator := NewCoordinator(catalogue, repository, newTransactionJournal(), nil)
 // A third incarnation still fails closed for that session: its intent and
 // record are retained untouched, but startup is no longer aborted.
+func TestDiscardRecoveryRemovesIntentWhenCatalogueRecordIsAbsent(t *testing.T) {
+	old := degradedTransactionRecord()
+	intent := domain.DiscardIntent{OldRecord: old, OldIncarnation: old.IncarnationID, NewIncarnation: domain.IncarnationID{2}, SessionName: old.Name, Reason: "discard"}
+	catalogue := newTransactionCatalogue()
+	journal := newTransactionJournal()
+	journal.intents[old.IncarnationID] = intent
+	coordinator := NewCoordinator(catalogue, newTransactionRepository(), journal, nil)
+	require.NoError(t, coordinator.Recover(context.Background()))
+	require.NotContains(t, journal.intents, old.IncarnationID)
+	require.Equal(t, []string{"delete-intent"}, journal.events)
+	require.Empty(t, coordinator.Conflicts())
+}
 func TestDiscardIncarnationConflict(t *testing.T) {
 	old := degradedTransactionRecord()
 	intent := domain.DiscardIntent{OldRecord: old, OldIncarnation: old.IncarnationID, NewIncarnation: domain.IncarnationID{2}, SessionName: old.Name, Reason: "discard"}

M internal/usecase/snapshot/manifest_preflight.go +4 -1

 	if err != nil {
 		return err
 	}
-	if generation == 0 || len(r.b) < len(domain.IncarnationID{}) {
+	if generation == 0 {
+		return fmt.Errorf("%w: manifest generation", ErrInvalidData)
+	}
+	if len(r.b) < len(domain.IncarnationID{}) {
 		return ErrShortPayload
 	}
 	var incarnationID domain.IncarnationID

M internal/usecase/snapshot/manifest_preflight_test.go +55 -3


@@ -40,6 +40,7 @@ func TestManifestEnvelopePreflightParity(t *testing.T) {
40		if err != nil {	40		if err != nil {
41		t.Fatal(err)	41		t.Fatal(err)
42		}	42		}
			43	+	nameOffset, nodeKindOffset := manifestFieldOffsets(t, encoded)
43		mutations := []struct {	44		mutations := []struct {
44		name string	45		name string
45		edit func([]byte) []byte	46		edit func([]byte) []byte

@@ -51,9 +52,21 @@ func TestManifestEnvelopePreflightParity(t *testing.T) {
51		{"body length", func(b []byte) []byte { binary.BigEndian.PutUint32(b[8:12], uint32(len(b))); return b }},	52		{"body length", func(b []byte) []byte { binary.BigEndian.PutUint32(b[8:12], uint32(len(b))); return b }},
52		{"crc", func(b []byte) []byte { b[12] ^= 1; return b }},	53		{"crc", func(b []byte) []byte { b[12] ^= 1; return b }},
53		{"trailing", func(b []byte) []byte { return append(b, 0) }},	54		{"trailing", func(b []byte) []byte { return append(b, 0) }},
54	-	{"body name", func(b []byte) []byte { b[26] ^= 1; binary.BigEndian.PutUint32(b[12:16], checksum(b[16:])); return b }},	55	+	{"body name", func(b []byte) []byte {
55	-	{"body generation", func(b []byte) []byte { b[16] ^= 1; binary.BigEndian.PutUint32(b[12:16], checksum(b[16:])); return b }},	56	+	b[nameOffset] = 0
56	-	{"body node kind", func(b []byte) []byte { b[65] = 99; binary.BigEndian.PutUint32(b[12:16], checksum(b[16:])); return b }},	57	+	binary.BigEndian.PutUint32(b[12:16], checksum(b[16:]))
			58	+	return b
			59	+	}},
			60	+	{"body generation", func(b []byte) []byte {
			61	+	clear(b[manifestHeaderSize : manifestHeaderSize+8])
			62	+	binary.BigEndian.PutUint32(b[12:16], checksum(b[16:]))
			63	+	return b
			64	+	}},
			65	+	{"body node kind", func(b []byte) []byte {
			66	+	b[nodeKindOffset] = 99
			67	+	binary.BigEndian.PutUint32(b[12:16], checksum(b[16:]))
			68	+	return b
			69	+	}},
57		}	70		}
58		for _, tc := range mutations {	71		for _, tc := range mutations {
59		t.Run(tc.name, func(t *testing.T) {	72		t.Run(tc.name, func(t *testing.T) {

@@ -68,6 +81,45 @@ func TestManifestEnvelopePreflightParity(t *testing.T) {
68		}	81		}
69		}	82		}
70			83
			84	+	func manifestFieldOffsets(t *testing.T, encoded []byte) (nameOffset, nodeKindOffset int) {
			85	+	t.Helper()
			86	+	r := payloadReader{b: encoded[manifestHeaderSize:]}
			87	+	must := func(err error) {
			88	+	if err != nil {
			89	+	t.Fatal(err)
			90	+	}
			91	+	}
			92	+	_, err := r.getUint64()
			93	+	must(err)
			94	+	r.b = r.b[len(domain.IncarnationID{}):]
			95	+	_, err = r.getUint8()
			96	+	must(err)
			97	+	nameLengthOffset := len(encoded) - len(r.b)
			98	+	name, err := r.getString()
			99	+	must(err)
			100	+	nameOffset = nameLengthOffset + 2
			101	+	if len(name) == 0 {
			102	+	t.Fatal("test manifest has empty name")
			103	+	}
			104	+	_, err = r.getUint64()
			105	+	must(err)
			106	+	_, err = r.getUint16()
			107	+	must(err)
			108	+	_, err = r.getUint16()
			109	+	must(err)
			110	+	_, err = r.getString()
			111	+	must(err)
			112	+	_, err = r.getUint16()
			113	+	must(err)
			114	+	_, err = r.getUint16()
			115	+	must(err)
			116	+	_, err = r.getUint64()
			117	+	must(err)
			118	+	_, err = r.getString()
			119	+	must(err)
			120	+	return nameOffset, len(encoded) - len(r.b)
			121	+	}
			122	+
71		func TestManifestObjectRefKinds(t *testing.T) {	123		func TestManifestObjectRefKinds(t *testing.T) {
72		for _, tc := range []struct {	124		for _, tc := range []struct {
73		name string	125		name string

M pkg/kv/codec.go +12 -7

 	// place by Open; nothing ever writes this framing again.
 	legacyHeaderLen = 8
-	// Current framing. Every file starts with fileMagic plus a uint16 format
+	// Current framing. Every file starts with fileMagic, a uint16 format
-	// version, and every record carries a self-verifying header:
+	// version, and CRC32 over that six-byte identity. Every record carries a
+	// self-verifying header:
 	//
 	//	[0:4]   payload length, big endian
 	//	[4:8]   CRC32(payload)
 	// The header checksum is what makes the length trustworthy: a corrupt
 	// length now fails closed instead of masquerading as a torn tail and
 	// silently truncating every record that follows it.
-	recordHeaderLen = 12
+	recordHeaderLen   = 12
-	fileMagicLen    = 4
+	fileMagicLen      = 4
-	fileHeaderLen   = fileMagicLen + 2
+	fileHeaderV1Len   = fileMagicLen + 2
-	formatVersion   = 1
+	fileHeaderBodyLen = fileHeaderV1Len
+	fileHeaderLen     = fileHeaderBodyLen + 4
+	formatVersionV1   = 1
+	formatVersion     = 2
 	// maxPayloadLen bounds any allocation driven by a length field. Catalogue
 	// records and batches are orders of magnitude smaller than this.
 func fileHeader() []byte {
 	buf := make([]byte, fileHeaderLen)
 	copy(buf, fileMagic[:])
-	binary.BigEndian.PutUint16(buf[fileMagicLen:], formatVersion)
+	binary.BigEndian.PutUint16(buf[fileMagicLen:fileHeaderBodyLen], formatVersion)
+	binary.BigEndian.PutUint32(buf[fileHeaderBodyLen:], crc32.ChecksumIEEE(buf[:fileHeaderBodyLen]))
 	return buf
 }

M pkg/kv/kv.go +100 -48

 	// formatLegacy is a file written before the record header carried its own
 	// checksum. It is read with the original semantics and upgraded at Open.
 	formatLegacy walFormat = iota
+	// formatCurrentV1 is the released VEVK v1 framing with its six-byte file
+	// header. Its record headers are identical to the current format.
+	formatCurrentV1
 	formatCurrent
 )
 func (f walFormat) headerLen() int64 {
-	if f == formatCurrent {
+	if f != formatLegacy {
 		return recordHeaderLen
 	}
 	return legacyHeaderLen
 }
+func (f walFormat) fileHeaderLen() int64 {
+	switch f {
+	case formatCurrentV1:
+		return fileHeaderV1Len
+	case formatCurrent:
+		return fileHeaderLen
+	default:
+		return 0
+	}
+}
 type headerStatus uint8
 const (
 	if err != nil {
 		return ReplayResult{}, err
 	}
-	result := ReplayResult{Data: make(map[string][]byte), EntrySize: make(map[string]int64), Format: format}
+	result := ReplayResult{Data: make(map[string][]byte), EntrySize: make(map[string]int64), Format: format, LastGood: format.fileHeaderLen()}
-	if format == formatCurrent {
-		result.LastGood = fileHeaderLen
-	}
 	for {
 		header, status, err := readRecordHeader(f, format, fileSize, result.LastGood)
 		if err != nil {
 			records = []record{rec}
 		}
 		if err != nil {
-			return ReplayResult{}, fmt.Errorf("%w: invalid record at offset %d: %v", ErrCorruptWAL, result.LastGood, err)
+			return ReplayResult{}, fmt.Errorf("%w: invalid record at offset %d: %w", ErrCorruptWAL, result.LastGood, err)
 		}
 		size := format.headerLen() + int64(len(payload))
 		applyRecords(result.Data, result.EntrySize, &result.Live, records, size)
 // readFileFormat consumes the file header when one is present and leaves the
 // reader positioned at the first record either way.
 func readFileFormat(f io.ReadSeeker, fileSize int64) (walFormat, error) {
-	if fileSize < fileHeaderLen {
+	if fileSize == 0 {
 		return formatLegacy, nil
 	}
-	header := make([]byte, fileHeaderLen)
+	probeLen := min(fileSize, int64(fileHeaderLen))
-	if _, err := io.ReadFull(f, header); err != nil {
+	probe := make([]byte, probeLen)
+	if _, err := io.ReadFull(f, probe); err != nil {
 		return formatLegacy, err
 	}
-	if !bytes.Equal(header[:fileMagicLen], fileMagic[:]) {
+	if fileSize < fileMagicLen {
+		if bytes.Equal(probe, fileMagic[:len(probe)]) {
+			return formatLegacy, fmt.Errorf("%w: incomplete VEVK header", ErrCorruptWAL)
+		}
 		if _, err := f.Seek(0, io.SeekStart); err != nil {
 			return formatLegacy, err
 		}
 		return formatLegacy, nil
 	}
-	if version := binary.BigEndian.Uint16(header[fileMagicLen:]); version != formatVersion {
+	if !bytes.Equal(probe[:fileMagicLen], fileMagic[:]) {
+		// A complete v2 identity checksum authenticates the intended magic as
+		// well as the version. Detect it before legacy replay so damage to the
+		// first magic byte cannot masquerade as a small legacy length and be
+		// truncated or compacted away.
+		if len(probe) == fileHeaderLen &&
+			binary.BigEndian.Uint16(probe[fileMagicLen:fileHeaderBodyLen]) == formatVersion &&
+			binary.BigEndian.Uint32(probe[fileHeaderBodyLen:]) == binary.BigEndian.Uint32(fileHeader()[fileHeaderBodyLen:]) {
+			return formatLegacy, fmt.Errorf("%w: damaged VEVK v2 magic", ErrCorruptWAL)
+		}
+		if _, err := f.Seek(0, io.SeekStart); err != nil {
+			return formatLegacy, err
+		}
+		return formatLegacy, nil
+	}
+	if fileSize < fileHeaderV1Len {
+		return formatLegacy, fmt.Errorf("%w: incomplete VEVK header", ErrCorruptWAL)
+	}
+	prefix := probe[:fileHeaderV1Len]
+	if _, err := f.Seek(fileHeaderV1Len, io.SeekStart); err != nil {
+		return formatLegacy, err
+	}
+	switch version := binary.BigEndian.Uint16(prefix[fileMagicLen:]); version {
+	case formatVersionV1:
+		return formatCurrentV1, nil
+	case formatVersion:
+		checksum := make([]byte, fileHeaderLen-fileHeaderV1Len)
+		if _, err := io.ReadFull(f, checksum); err != nil {
+			return formatLegacy, fmt.Errorf("%w: incomplete VEVK v2 header", ErrCorruptWAL)
+		}
+		if crc32.ChecksumIEEE(prefix) != binary.BigEndian.Uint32(checksum) {
+			return formatLegacy, fmt.Errorf("%w: file header checksum mismatch", ErrCorruptWAL)
+		}
+		return formatCurrent, nil
+	default:
 		return formatLegacy, fmt.Errorf("%w: unsupported format version %d", ErrCorruptWAL, version)
 	}
-	return formatCurrent, nil
 }
 type recordHeader struct {
 		payloadLen: binary.BigEndian.Uint32(buf[0:4]),
 		payloadCRC: binary.BigEndian.Uint32(buf[4:8]),
 	}
-	if format == formatCurrent {
+	if format != formatLegacy {
 		if crc32.ChecksumIEEE(buf[0:8]) != binary.BigEndian.Uint32(buf[8:recordHeaderLen]) {
 			return recordHeader{}, headerOK, fmt.Errorf("%w: record header CRC mismatch at offset %d", ErrCorruptWAL, offset)
 		}
 		// The length is now trustworthy, so an implausible one is corruption
 		// rather than a short tail. Checked before any allocation.
-		if header.payloadLen > maxPayloadLen {
+	}
-			return recordHeader{}, headerOK, fmt.Errorf("%w: record length %d exceeds maximum at offset %d", ErrCorruptWAL, header.payloadLen, offset)
+	// Every framing is allocation-bounded. In legacy framing an oversized
-		}
+	// declaration remains corruption rather than driving an attacker-sized
+	// allocation; ordinary short tails retain their released truncation semantics.
+	if header.payloadLen > maxPayloadLen {
+		return recordHeader{}, headerOK, fmt.Errorf("%w: record length %d exceeds maximum at offset %d", ErrCorruptWAL, header.payloadLen, offset)
 	}
 	if int64(header.payloadLen) > fileSize-offset-format.headerLen() {
 		return recordHeader{}, headerTorn, nil
 			setCount++
 		}
 	}
-	setSize := size
+	setSize, remainder := size, int64(0)
 	if setCount > 1 {
-		setSize = size / setCount
+		setSize, remainder = size/setCount, size%setCount
 	}
 	for _, rec := range records {
 		key := string(rec.key)
 			*live -= old
 		}
 		if rec.op == opSet {
+			entrySize := setSize
+			if remainder > 0 {
+				entrySize++
+				remainder--
+			}
 			data[key] = append([]byte(nil), rec.value...)
-			sizes[key] = setSize
+			sizes[key] = entrySize
-			*live += setSize
+			*live += entrySize
 		} else {
 			delete(data, key)
 			delete(sizes, key)
 }
 func recoverCompaction(path string, hooks fsHooks) error {
-	_, currentExists, currentErr := candidate(path)
+	currentResult, currentExists, currentErr := candidate(path)
 	nextResult, nextExists, nextErr := candidate(path + ".next")
 	_, prevExists, prevErr := candidate(path + ".prev")
 	if nextErr == nil && nextResult.TornTail {
 	}
 	dir := filepath.Dir(path)
 	if currentExists && currentErr == nil {
+		if currentResult.TornTail && prevExists {
+			// A predecessor proves compaction was in flight. The torn current is
+			// ambiguous, so preserve both candidates and fail closed rather than
+			// truncating current and deleting the last complete predecessor.
+			return fmt.Errorf("%w: torn current with predecessor", ErrCorruptWAL)
+		}
 		if nextExists {
 			if err := hooks.Remove(path + ".next"); err != nil {
 				return err
 		return nil
 	}
 	if currentExists && currentErr != nil {
-		if !prevExists || prevErr != nil {
+		// Corruption does not prove which bytes are disposable. Preserve every
-			return fmt.Errorf("%w: no valid current or predecessor", ErrCorruptWAL)
+		// candidate for diagnosis/recovery instead of deleting current or a valid
-		}
+		// predecessor and fail closed.
-		if err := hooks.Remove(path); err != nil {
+		return fmt.Errorf("%w: invalid current candidate", ErrCorruptWAL)
-			return err
+	}
-		}
+	if !currentExists && (nextExists || prevExists) {
-		if err := hooks.Rename(path+".prev", path); err != nil {
+		// A complete .next is the newest fully published compaction candidate and
-			return err
+		// wins even when .prev exists but is corrupt. Otherwise a complete .prev
-		}
+		// is the only safe rollback. Invalid candidates are never selected.
-		if err := hooks.SyncDir(dir); err != nil {
+		source := ""
-			return err
-		}
-		if nextExists {
-			if err := hooks.Remove(path + ".next"); err != nil {
-				return err
-			}
-			return hooks.SyncDir(dir)
-		}
-		return nil
-	}
-	if !currentExists && prevExists {
-		if prevErr != nil {
-			return fmt.Errorf("%w: invalid predecessor", ErrCorruptWAL)
-		}
-		source := path + ".prev"
 		if nextExists && nextErr == nil {
 			source = path + ".next"
+		} else if prevExists && prevErr == nil {
+			source = path + ".prev"
+		}
+		if source == "" {
+			return fmt.Errorf("%w: no valid current, successor, or predecessor", ErrCorruptWAL)
 		}
 		if err := hooks.Rename(source, path); err != nil {
 			return err
 		}
 		return hooks.SyncDir(dir)
 	}
-	if nextExists || (currentExists && currentErr != nil) || (prevExists && prevErr != nil) {
+	if currentExists && currentErr != nil {
-		return fmt.Errorf("%w: no valid current or predecessor", ErrCorruptWAL)
+		return fmt.Errorf("%w: no valid current", ErrCorruptWAL)
 	}
 	return nil
 }

M pkg/kv/kv_test.go +168 -19


@@ -4,7 +4,9 @@ import (
4		"bytes"	4		"bytes"
5		"encoding/binary"	5		"encoding/binary"
6		"errors"	6		"errors"
			7	+	"fmt"
7		"hash/crc32"	8		"hash/crc32"
			9	+	"maps"
8		"os"	10		"os"
9		"path/filepath"	11		"path/filepath"
10		"reflect"	12		"reflect"

@@ -26,6 +28,17 @@ func currentFile(records ...[]byte) []byte {
26		return buf	28		return buf
27		}	29		}
28			30
			31	+	// v1File is the previously released VEVK framing: magic and uint16 version,
			32	+	// followed directly by the same self-checksummed records used today.
			33	+	func v1File(records ...[]byte) []byte {
			34	+	buf := append([]byte(nil), fileMagic[:]...)
			35	+	buf = binary.BigEndian.AppendUint16(buf, formatVersionV1)
			36	+	for _, record := range records {
			37	+	buf = append(buf, record...)
			38	+	}
			39	+	return buf
			40	+	}
			41	+
29		// legacyFile reproduces the framing written by the released version: no file	42		// legacyFile reproduces the framing written by the released version: no file
30		// header, and a record header of length plus payload CRC only. Compatibility	43		// header, and a record header of length plus payload CRC only. Compatibility
31		// with these files is a hard requirement, so the fixture stays in the tests.	44		// with these files is a hard requirement, so the fixture stays in the tests.

@@ -378,6 +391,34 @@ func TestRecoverCompactionCleansStaleNextRegardlessOfPrev(t *testing.T) {
378		}	391		}
379		}	392		}
380			393
			394	+	func TestReplayPreservesWrappedDecodeCause(t *testing.T) {
			395	+	path := privatePath(t)
			396	+	writeFile(t, path, currentFile(rawRecord([]byte{0xff, 0, 0})))
			397	+	f, err := os.Open(path)
			398	+	if err != nil {
			399	+	t.Fatal(err)
			400	+	}
			401	+	defer func() { _ = f.Close() }()
			402	+	_, err = replayFile(f)
			403	+	if !errors.Is(err, ErrCorruptWAL) \|\| !errors.Is(err, errBadRecord) {
			404	+	t.Fatalf("replayFile error = %v, want wrapped ErrCorruptWAL and errBadRecord", err)
			405	+	}
			406	+	}
			407	+
			408	+	func TestBatchLiveSizeAccountsForRemainderExactly(t *testing.T) {
			409	+	data := map[string][]byte{}
			410	+	sizes := map[string]int64{}
			411	+	var live int64
			412	+	applyRecords(data, sizes, &live, []record{
			413	+	{op: opSet, key: []byte("a"), value: []byte("one")},
			414	+	{op: opSet, key: []byte("b"), value: []byte("two")},
			415	+	{op: opSet, key: []byte("c"), value: []byte("three")},
			416	+	}, 10)
			417	+	if live != 10 \|\| sizes["a"]+sizes["b"]+sizes["c"] != 10 {
			418	+	t.Fatalf("live sizes = %v, live = %d, want exact total 10", sizes, live)
			419	+	}
			420	+	}
			421	+
381		func TestDecodeBatchRejectsImpossibleCountBeforeAllocating(t *testing.T) {	422		func TestDecodeBatchRejectsImpossibleCountBeforeAllocating(t *testing.T) {
382		payload := []byte{opBatch, 0xff, 0xff, 0xff, 0xff}	423		payload := []byte{opBatch, 0xff, 0xff, 0xff, 0xff}
383		allocs := testing.AllocsPerRun(10, func() {	424		allocs := testing.AllocsPerRun(10, func() {

@@ -429,14 +470,17 @@ func TestCompactionRecoveryMatrix(t *testing.T) {
429		name string	470		name string
430		current, next, prev []byte	471		current, next, prev []byte
431		want string	472		want string
			473	+	wantErr bool
432		}{	474		}{
433		{name: "current-alone", current: oldFile, want: "old"},	475		{name: "current-alone", current: oldFile, want: "old"},
434		{name: "current-next", current: oldFile, next: newFile, want: "old"},	476		{name: "current-next", current: oldFile, next: newFile, want: "old"},
435		{name: "prev-next", prev: oldFile, next: newFile, want: "new"},	477		{name: "prev-next", prev: oldFile, next: newFile, want: "new"},
436	-	{name: "prev-invalid-next", prev: oldFile, next: currentFile(rawRecord([]byte{0xff, 0, 0})), want: "old"},	478	+	{name: "next-alone", next: newFile, want: "new"},
			479	+	{name: "invalid-prev-valid-next", prev: currentFile(rawRecord([]byte{0xff, 0, 0})), next: newFile, want: "new"},
			480	+	{name: "valid-prev-invalid-next", prev: oldFile, next: currentFile(rawRecord([]byte{0xff, 0, 0})), want: "old"},
437		{name: "prev-torn-next", prev: oldFile, next: newFile[:len(newFile)-1], want: "old"},	481		{name: "prev-torn-next", prev: oldFile, next: newFile[:len(newFile)-1], want: "old"},
438		{name: "current-prev", current: newFile, prev: oldFile, want: "new"},	482		{name: "current-prev", current: newFile, prev: oldFile, want: "new"},
439	-	{name: "invalid-current-prev", current: currentFile(rawRecord([]byte{0xff, 0, 0})), prev: oldFile, want: "old"},	483	+	{name: "invalid-current-prev", current: currentFile(rawRecord([]byte{0xff, 0, 0})), prev: oldFile, wantErr: true},
440		{name: "prev-alone", prev: oldFile, want: "old"},	484		{name: "prev-alone", prev: oldFile, want: "old"},
441		}	485		}
442		for _, tt := range tests {	486		for _, tt := range tests {

@@ -452,7 +496,18 @@ func TestCompactionRecoveryMatrix(t *testing.T) {
452		}	496		}
453		}	497		}
454		}	498		}
455	-	if err := recoverCompaction(path, defaultFSHooks()); err != nil {	499	+	before := candidateBytes(t, path)
			500	+	err := recoverCompaction(path, defaultFSHooks())
			501	+	if tt.wantErr {
			502	+	if !errors.Is(err, ErrCorruptWAL) {
			503	+	t.Fatalf("recoverCompaction error = %v, want ErrCorruptWAL", err)
			504	+	}
			505	+	if got := candidateBytes(t, path); !reflect.DeepEqual(got, before) {
			506	+	t.Fatalf("uncertain candidates changed: got %#v, want %#v", got, before)
			507	+	}
			508	+	return
			509	+	}
			510	+	if err != nil {
456		t.Fatal(err)	511		t.Fatal(err)
457		}	512		}
458		got, err := Replay(path)	513		got, err := Replay(path)

@@ -701,25 +756,85 @@ func rawBatchPayload(changes []BatchChange) []byte {
701		return payload	756		return payload
702		}	757		}
703			758
704	-	// An oversized length must never drive an allocation. In a legacy file the	759	+	// An oversized length must never drive an allocation. Legacy framing is
705	-	// length is unprotected, so it stays a torn tail; in the current format the	760	+	// accepted only after complete strict replay, while the current header checksum
706	-	// header checksum proves the length was written that way, which is corruption.	761	+	// proves an oversized length was written that way; both fail closed.
			762	+	func TestCorruptedCurrentHeaderNeverFallsBackToLegacyOrDeletesPredecessor(t *testing.T) {
			763	+	record, _ := encodeRecord(opSet, []byte("version"), []byte("current"))
			764	+	previous, _ := encodeRecord(opSet, []byte("version"), []byte("previous"))
			765	+
			766	+	tests := []struct {
			767	+	name string
			768	+	current []byte
			769	+	standalone bool
			770	+	}{
			771	+	{name: "torn file header", current: append([]byte(nil), fileHeader()[:fileHeaderLen-1]...), standalone: true},
			772	+	{name: "torn current record", current: currentFile(record)[:fileHeaderLen+recordHeaderLen+1]},
			773	+	}
			774	+	for i := range fileMagicLen {
			775	+	corrupted := currentFile(record)
			776	+	corrupted[i] = 0
			777	+	tests = append(tests, struct {
			778	+	name string
			779	+	current []byte
			780	+	standalone bool
			781	+	}{name: fmt.Sprintf("corrupted magic byte %d", i), current: corrupted, standalone: true})
			782	+	}
			783	+	for length := 1; length < fileHeaderLen; length++ {
			784	+	tests = append(tests, struct {
			785	+	name string
			786	+	current []byte
			787	+	standalone bool
			788	+	}{name: fmt.Sprintf("torn header prefix %d", length), current: append([]byte(nil), fileHeader()[:length]...), standalone: true})
			789	+	}
			790	+
			791	+	for _, tt := range tests {
			792	+	t.Run(tt.name, func(t *testing.T) {
			793	+	for _, withCandidates := range []bool{false, true} {
			794	+	if !withCandidates && !tt.standalone {
			795	+	continue
			796	+	}
			797	+	name := "standalone"
			798	+	if withCandidates {
			799	+	name = "with candidates"
			800	+	}
			801	+	t.Run(name, func(t *testing.T) {
			802	+	path := privatePath(t)
			803	+	writeFile(t, path, tt.current)
			804	+	if withCandidates {
			805	+	if err := os.WriteFile(path+".prev", currentFile(previous), 0o600); err != nil {
			806	+	t.Fatal(err)
			807	+	}
			808	+	if err := os.WriteFile(path+".next", currentFile(record), 0o600); err != nil {
			809	+	t.Fatal(err)
			810	+	}
			811	+	}
			812	+	before := candidateBytes(t, path)
			813	+	if _, err := Open(path); !errors.Is(err, ErrCorruptWAL) {
			814	+	t.Fatalf("Open error = %v, want ErrCorruptWAL", err)
			815	+	}
			816	+	if got := candidateBytes(t, path); !reflect.DeepEqual(got, before) {
			817	+	t.Fatalf("candidates changed: got %#v, want %#v", got, before)
			818	+	}
			819	+	})
			820	+	}
			821	+	})
			822	+	}
			823	+	}
			824	+
707		func TestReplayRejectsOversizedLengthWithoutAllocating(t *testing.T) {	825		func TestReplayRejectsOversizedLengthWithoutAllocating(t *testing.T) {
708		first, _ := encodeRecord(opSet, []byte("a"), []byte("one"))	826		first, _ := encodeRecord(opSet, []byte("a"), []byte("one"))
709		legacyHeader := make([]byte, legacyHeaderLen)	827		legacyHeader := make([]byte, legacyHeaderLen)
710		binary.BigEndian.PutUint32(legacyHeader[0:4], 1<<31)	828		binary.BigEndian.PutUint32(legacyHeader[0:4], 1<<31)
711			829
712	-	t.Run("legacy length is a torn tail", func(t *testing.T) {	830	+	t.Run("legacy incomplete record fails closed", func(t *testing.T) {
713		path := privatePath(t)	831		path := privatePath(t)
714	-	writeFile(t, path, append(legacyFile(first), legacyHeader...))	832	+	wal := append(legacyFile(first), legacyHeader...)
715	-	s, err := Open(path)	833	+	writeFile(t, path, wal)
716	-	if err != nil {	834	+	if _, err := Open(path); !errors.Is(err, ErrCorruptWAL) {
717	-	t.Fatal(err)	835	+	t.Fatalf("Open error = %v, want ErrCorruptWAL", err)
718	-	}
719	-	defer closeStore(t, s)
720	-	if got, ok := s.Get([]byte("a")); !ok \|\| string(got) != "one" {
721	-	t.Fatalf("good record missing before bad length: %q %v", got, ok)
722		}	836		}
			837	+	requireFileBytes(t, path, wal)
723		})	838		})
724			839
725		t.Run("current oversized length fails closed", func(t *testing.T) {	840		t.Run("current oversized length fails closed", func(t *testing.T) {

@@ -851,13 +966,49 @@ func TestCurrentFormatReplayDecisionTable(t *testing.T) {
851			966
852		// A file written by the released version must keep working: it opens with the	967		// A file written by the released version must keep working: it opens with the
853		// original semantics, is upgraded in place, and reopens identically.	968		// original semantics, is upgraded in place, and reopens identically.
			969	+	func TestVEVKV1FileOpensAndUpgradesInPlace(t *testing.T) {
			970	+	setA, _ := encodeRecord(opSet, []byte("a"), []byte("one"))
			971	+	setB, _ := encodeRecord(opSet, []byte("b"), bytes.Repeat([]byte("x"), 1<<20))
			972	+	for _, tc := range []struct {
			973	+	name string
			974	+	wal []byte
			975	+	}{
			976	+	{name: "ordinary catalogue payload", wal: v1File(setA)},
			977	+	{name: "prior large catalogue payload", wal: v1File(setB)},
			978	+	} {
			979	+	t.Run(tc.name, func(t *testing.T) {
			980	+	path := privatePath(t)
			981	+	writeFile(t, path, tc.wal)
			982	+	store, err := Open(path)
			983	+	if err != nil {
			984	+	t.Fatal(err)
			985	+	}
			986	+	closeStore(t, store)
			987	+	upgraded, err := os.ReadFile(path)
			988	+	if err != nil {
			989	+	t.Fatal(err)
			990	+	}
			991	+	if !bytes.Equal(upgraded[:fileHeaderLen], fileHeader()) {
			992	+	t.Fatalf("upgraded header = %x, want %x", upgraded[:fileHeaderLen], fileHeader())
			993	+	}
			994	+	})
			995	+	}
			996	+	}
			997	+
			998	+	func TestVEVKV1RejectsOversizedRecordBeforeAllocation(t *testing.T) {
			999	+	path := privatePath(t)
			1000	+	writeFile(t, path, v1File(oversizedRecordHeader(maxPayloadLen+1)))
			1001	+	if _, err := Open(path); !errors.Is(err, ErrCorruptWAL) {
			1002	+	t.Fatalf("Open error = %v, want ErrCorruptWAL", err)
			1003	+	}
			1004	+	}
			1005	+
854		func TestLegacyFileOpensAndUpgradesInPlace(t *testing.T) {	1006		func TestLegacyFileOpensAndUpgradesInPlace(t *testing.T) {
855		setA, _ := encodeRecord(opSet, []byte("a"), []byte("one"))	1007		setA, _ := encodeRecord(opSet, []byte("a"), []byte("one"))
856		setB, _ := encodeRecord(opSet, []byte("b"), []byte("two"))	1008		setB, _ := encodeRecord(opSet, []byte("b"), []byte("two"))
857		replaceA, _ := encodeRecord(opSet, []byte("a"), []byte("uno"))	1009		replaceA, _ := encodeRecord(opSet, []byte("a"), []byte("uno"))
858		delB, _ := encodeRecord(opDel, []byte("b"), nil)	1010		delB, _ := encodeRecord(opDel, []byte("b"), nil)
859		torn, _ := encodeRecord(opSet, []byte("c"), []byte("three"))	1011		torn, _ := encodeRecord(opSet, []byte("c"), []byte("three"))
860	-
861		tests := []struct {	1012		tests := []struct {
862		name string	1013		name string
863		wal []byte	1014		wal []byte

@@ -896,9 +1047,7 @@ func TestLegacyFileOpensAndUpgradesInPlace(t *testing.T) {
896		}	1047		}
897		defer closeStore(t, reopened)	1048		defer closeStore(t, reopened)
898		want := map[string]string{"added": "after-upgrade"}	1049		want := map[string]string{"added": "after-upgrade"}
899	-	for k, v := range tt.want {	1050	+	maps.Copy(want, tt.want)
900	-	want[k] = v
901	-	}
902		requireContents(t, reopened, want)	1051		requireContents(t, reopened, want)
903		replayed, err := Replay(path)	1052		replayed, err := Replay(path)
904		if err != nil {	1053		if err != nil {