@anionex/dsh-turn-rewind 0.1.1 → 0.2.0

package/lib/engine.js

@@ -2,10 +2,12 @@ import { randomBytes } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { lstat, realpath } from 'node:fs/promises';
+import { createDeadline } from './deadline.js';
 import { ChangeLedgerError, errorMessage } from './errors.js';
-import { discoverRepository, sameRepositoryFence } from './git.js';
-import { ensureSafeParents, expandHome, isNodeError, isWithin, pruneEmptyParents, removeRestoreTarget, replaceRegularFile, replaceSymbolicLink, resolveWorkspacePath, validateRelativePath, } from './path-utils.js';
-import { captureStableTree, diffTrees, entriesEqual } from './snapshot.js';
+import { discoverRepository, discoverRepositoryRoot, ensureGitWorktreeIdentity, resolveGitWorktreeRoot, sameRepositoryFence, } from './git.js';
+import { captureGitTurnCheckpoint, deleteGitCheckpoint, deleteGitCheckpointRef, publishGitCheckpoint, readGitBlob, verifyGitCheckpoint, } from './git-checkpoint.js';
+import { assertSafeParents, ensureSafeParents, expandHome, isNodeError, isWithin, pruneEmptyParents, removeRestoreTarget, replaceRegularFile, replaceSymbolicLink, resolveWorkspacePath, validateRelativePath, } from './path-utils.js';
+import { captureSnapshotEntry, captureStableTree, diffTrees, entriesEqual } from './snapshot.js';
 import { LedgerStore } from './store.js';
 import { LEDGER_FORMAT_VERSION, } from './types.js';
 const DEFAULTS = {
@@ -16,30 +18,158 @@ const DEFAULTS = {
     maxSnapshotBytes: 512 * 1024 * 1024,
     planTtlMs: 15 * 60 * 1_000,
     staleLockMs: 30_000,
+    turnCheckpointMode: 'legacy',
+    turnCheckpointTimeoutMs: 5_000,
+    turnCheckpointMaxNewBytes: 32 * 1024 * 1024,
+    turnCheckpointTrust: 'fast',
 };
 /** Persistent workspace change-set engine, independent of the DSH tool adapter. */
 export class ChangeLedgerEngine {
-    config;
+    currentConfig;
     store;
     plans = new Map();
     activePlans = new Set();
     ready;
     /** Build an engine and start crash-journal reconciliation. */
     constructor(config = {}) {
-        this.config = resolveConfig(config);
-        this.store = new LedgerStore(this.config);
-        this.ready = this.store.initialize();
+        this.currentConfig = resolveConfig(config);
+        this.store = new LedgerStore(this.currentConfig);
+        this.ready = this.initializeStore();
+    }
+    /** Currently resolved configuration; runtime-tunable fields update in place. */
+    get config() {
+        return this.currentConfig;
+    }
+    /**
+     * Swap runtime-tunable configuration (limits, modes, timeouts, trust) in place.
+     * The storage root must never move once the engine owns locks and journals.
+     */
+    updateConfig(config) {
+        const resolved = resolveConfig(config);
+        if (resolved.storageDir !== this.currentConfig.storageDir) {
+            throw new ChangeLedgerError('INVALID_CONFIG', 'storageDir cannot change while the engine is running');
+        }
+        Object.assign(this.currentConfig, resolved);
     }
     /** Wait for startup reconciliation and return the number of interrupted journals found. */
     async initialize() {
         return this.ready;
     }
+    async initializeStore() {
+        const restoredOperations = await this.store.initialize();
+        return restoredOperations + await this.reconcileGitCheckpointJournals();
+    }
+    async acquireWorkspace(workspace, signal) {
+        const identity = await ensureGitWorktreeIdentity(workspace, signal);
+        if (identity.root !== workspace) {
+            throw new ChangeLedgerError('GIT_ROOT_INVALID', `workspace moved while acquiring its lock: ${JSON.stringify(workspace)}`);
+        }
+        return this.store.acquire(workspace, identity.lockPath, {
+            commonDir: identity.commonDir,
+            gitDir: identity.gitDir,
+            worktreeId: identity.worktreeId,
+        }, signal);
+    }
+    async reconcileGitCheckpointJournals() {
+        let reconciled = 0;
+        for (const journal of await this.store.listGitCheckpointJournals()) {
+            const workspace = await resolveGitWorktreeRoot(journal.commonDir, journal.worktreeId, journal.workspace);
+            const activeJournal = workspace === journal.workspace ? journal : { ...journal, workspace };
+            const release = await this.acquireWorkspace(workspace);
+            try {
+                const manifest = await this.tryReadManifest(workspace, journal.restorePointId);
+                if (journal.action === 'publish') {
+                    if (manifest === undefined) {
+                        await deleteGitCheckpointRef(workspace, journal.ref, journal.commit, this.config.storageDir);
+                    }
+                    else {
+                        assertJournalMatchesManifest(activeJournal, manifest);
+                        await verifyGitCheckpoint(manifest);
+                    }
+                }
+                else {
+                    if (manifest !== undefined) {
+                        assertJournalMatchesManifest(activeJournal, manifest);
+                        await this.store.deleteManifest(workspace, journal.restorePointId);
+                    }
+                    await deleteGitCheckpointRef(workspace, journal.ref, journal.commit, this.config.storageDir);
+                }
+                await this.store.deleteGitCheckpointJournal(workspace, journal.restorePointId);
+                reconciled += 1;
+            }
+            finally {
+                await release();
+            }
+        }
+        return reconciled;
+    }
+    async publishGitManifest(manifest, signal) {
+        let journalWritten = false;
+        try {
+            await this.store.writeGitCheckpointJournal('publish', manifest);
+            journalWritten = true;
+            await publishGitCheckpoint(manifest, this.config.storageDir, signal);
+            await verifyGitCheckpoint(manifest, signal);
+            await this.store.writeManifest(manifest);
+        }
+        catch (error) {
+            if (!journalWritten)
+                throw error;
+            const persisted = await this.tryReadManifest(manifest.workspace, manifest.id);
+            if (persisted !== undefined) {
+                assertJournalMatchesManifest({
+                    version: 1,
+                    action: 'publish',
+                    storeId: manifest.git.storeId,
+                    workspace: manifest.workspace,
+                    commonDir: manifest.repository.commonDir,
+                    worktreeId: manifest.git.worktreeId,
+                    restorePointId: manifest.id,
+                    ref: manifest.git.ref,
+                    commit: manifest.git.commit,
+                    createdAt: manifest.createdAt,
+                }, persisted);
+                await verifyGitCheckpoint(persisted, signal);
+                await this.store.deleteGitCheckpointJournal(manifest.workspace, manifest.id).catch(() => undefined);
+                return;
+            }
+            try {
+                await deleteGitCheckpoint(manifest, this.config.storageDir);
+                await this.store.deleteGitCheckpointJournal(manifest.workspace, manifest.id);
+            }
+            catch (cleanupError) {
+                throw new ChangeLedgerError('SNAPSHOT_CLEANUP_FAILED', `Git checkpoint publication failed (${errorMessage(error)}) and journaled ref cleanup also failed (${errorMessage(cleanupError)})`, { cause: error });
+            }
+            throw error;
+        }
+        await this.store.deleteGitCheckpointJournal(manifest.workspace, manifest.id).catch(() => undefined);
+    }
+    async deleteManifestWithGit(manifest, signal) {
+        if (manifest.version === LEDGER_FORMAT_VERSION) {
+            await this.store.deleteManifest(manifest.workspace, manifest.id);
+            return;
+        }
+        await this.store.writeGitCheckpointJournal('delete', manifest);
+        await this.store.deleteManifest(manifest.workspace, manifest.id);
+        await deleteGitCheckpoint(manifest, this.config.storageDir, signal);
+        await this.store.deleteGitCheckpointJournal(manifest.workspace, manifest.id);
+    }
+    async tryReadManifest(workspace, id) {
+        try {
+            return await this.store.readManifest(workspace, id);
+        }
+        catch (error) {
+            if (error instanceof ChangeLedgerError && error.code === 'RESTORE_POINT_NOT_FOUND')
+                return undefined;
+            throw error;
+        }
+    }
     /** Create a durable restore point for the current Git worktree. */
     async create(options) {
         await this.ready;
         const source = await discoverRepository(options.cwd, options.signal);
         await this.assertStorageSeparated(source.state.root);
-        const release = await this.store.acquire(source.state.root);
+        const release = await this.acquireWorkspace(source.state.root, options.signal);
         try {
             const label = normalizeLabel(options.label);
             const manifest = await this.createLocked({
@@ -57,42 +187,132 @@ export class ChangeLedgerEngine {
     }
     /** Capture project files before one DSH turn begins its first step. */
     async createTurnCheckpoint(options) {
-        await this.ready;
-        if (!Number.isSafeInteger(options.turn) || options.turn < 0) {
-            throw new ChangeLedgerError('INVALID_ARGUMENTS', 'turn must be a non-negative safe integer');
+        const deadline = createDeadline(this.config.turnCheckpointTimeoutMs);
+        const signal = options.signal === undefined ? deadline.signal : AbortSignal.any([options.signal, deadline.signal]);
+        try {
+            try {
+                await waitWithSignal(this.ready, signal);
+            }
+            catch (error) {
+                throw checkpointDeadlineError(error, this.config.turnCheckpointTimeoutMs, deadline.signal, options.signal);
+            }
+            if (this.config.turnCheckpointMode === 'off') {
+                throw new ChangeLedgerError('TURN_CHECKPOINT_DISABLED', 'automatic turn checkpoints are disabled');
+            }
+            if (!Number.isSafeInteger(options.turn) || options.turn < 0) {
+                throw new ChangeLedgerError('INVALID_ARGUMENTS', 'turn must be a non-negative safe integer');
+            }
+            if (!Number.isSafeInteger(options.turnStartSeq) || options.turnStartSeq < 0) {
+                throw new ChangeLedgerError('INVALID_ARGUMENTS', 'turnStartSeq must be a non-negative safe integer');
+            }
+            try {
+                const source = await discoverRepository(options.cwd, signal);
+                await this.assertStorageSeparated(source.state.root);
+                const release = await this.acquireWorkspace(source.state.root, signal);
+                try {
+                    const existing = await waitWithSignal(this.store.listManifests(source.state.root, signal), signal);
+                    const duplicate = existing.find(manifest => manifest.kind === 'turn'
+                        && manifest.sessionId === options.sessionId
+                        && manifest.turn === options.turn
+                        && manifest.turnStartSeq === options.turnStartSeq);
+                    if (duplicate !== undefined) {
+                        if (duplicate.version === 2)
+                            await verifyGitCheckpoint(duplicate, signal);
+                        await this.store.deleteTurnCheckpointSkip(source.state.root, options.sessionId, options.turn, options.turnStartSeq).catch(() => undefined);
+                        return summarize(duplicate);
+                    }
+                    throwIfAborted(signal);
+                    let manifest;
+                    if (this.config.turnCheckpointMode === 'legacy') {
+                        manifest = await this.createLocked({
+                            cwd: source.state.root,
+                            kind: 'turn',
+                            sessionId: options.sessionId,
+                            label: `Before turn ${String(options.turn)} checkpoint`,
+                            turn: options.turn,
+                            turnStartSeq: options.turnStartSeq,
+                            signal,
+                            deferGarbageCollection: true,
+                        });
+                    }
+                    else {
+                        const id = makeId('rp');
+                        const captured = (await captureGitTurnCheckpoint({
+                            cwd: source.state.root,
+                            id,
+                            sessionId: options.sessionId,
+                            turn: options.turn,
+                            turnStartSeq: options.turnStartSeq,
+                            config: this.config,
+                            signal,
+                        })).manifest;
+                        await this.publishGitManifest(captured, signal);
+                        manifest = captured;
+                    }
+                    await this.store.deleteTurnCheckpointSkip(source.state.root, options.sessionId, options.turn, options.turnStartSeq).catch(() => undefined);
+                    if (!signal.aborted) {
+                        const checkpoints = [...existing.filter(point => point.kind === 'turn' && point.sessionId === options.sessionId), manifest]
+                            .sort((left, right) => right.createdAt - left.createdAt || right.id.localeCompare(left.id));
+                        for (const stale of checkpoints.slice(this.config.maxTurnCheckpointsPerSession)) {
+                            if (signal.aborted)
+                                break;
+                            if (await this.store.isReferencedByRecovery(source.state.root, stale.id))
+                                continue;
+                            await this.deleteManifestWithGit(stale, signal).catch(() => undefined);
+                        }
+                    }
+                    return summarize(manifest);
+                }
+                finally {
+                    await release();
+                }
+            }
+            catch (error) {
+                throw checkpointDeadlineError(error, this.config.turnCheckpointTimeoutMs, deadline.signal, options.signal);
+            }
         }
-        if (!Number.isSafeInteger(options.turnStartSeq) || options.turnStartSeq < 0) {
-            throw new ChangeLedgerError('INVALID_ARGUMENTS', 'turnStartSeq must be a non-negative safe integer');
+        finally {
+            deadline.cancel();
         }
-        const source = await discoverRepository(options.cwd, options.signal);
-        await this.assertStorageSeparated(source.state.root);
-        const release = await this.store.acquire(source.state.root);
+    }
+    /** Persist one bounded automatic-checkpoint skip without blocking a later turn retry. */
+    async recordTurnCheckpointSkip(options) {
+        await waitWithSignal(this.ready, options.signal);
+        const workspace = await discoverRepositoryRoot(options.cwd, options.signal);
+        await this.assertStorageSeparated(workspace);
+        const release = await this.acquireWorkspace(workspace, options.signal);
         try {
-            const existing = await this.store.listManifests(source.state.root);
-            const duplicate = existing.find(manifest => manifest.kind === 'turn'
+            throwIfAborted(options.signal);
+            const existing = (await this.store.listManifests(workspace, options.signal)).some(manifest => manifest.kind === 'turn'
                 && manifest.sessionId === options.sessionId
                 && manifest.turn === options.turn
                 && manifest.turnStartSeq === options.turnStartSeq);
-            if (duplicate !== undefined)
-                return summarize(duplicate);
-            const manifest = await this.createLocked({
-                cwd: source.state.root,
-                kind: 'turn',
+            if (existing) {
+                await this.store.deleteTurnCheckpointSkip(workspace, options.sessionId, options.turn, options.turnStartSeq);
+                return;
+            }
+            await this.store.writeTurnCheckpointSkip(workspace, {
+                version: 1,
                 sessionId: options.sessionId,
-                label: `Before turn ${String(options.turn)} checkpoint`,
                 turn: options.turn,
                 turnStartSeq: options.turnStartSeq,
-                ...(options.signal === undefined ? {} : { signal: options.signal }),
+                reason: options.reason.slice(0, 2_000),
+                createdAt: Date.now(),
             });
-            const checkpoints = [...existing.filter(point => point.kind === 'turn' && point.sessionId === options.sessionId), manifest]
-                .sort((left, right) => right.createdAt - left.createdAt || right.id.localeCompare(left.id));
-            for (const stale of checkpoints.slice(this.config.maxTurnCheckpointsPerSession)) {
-                if (await this.store.isReferencedByRecovery(source.state.root, stale.id))
-                    continue;
-                await this.store.deleteManifest(source.state.root, stale.id);
-            }
-            await this.store.collectGarbage(source.state.root);
-            return summarize(manifest);
+        }
+        finally {
+            await release();
+        }
+    }
+    /** Read a durable skip marker for one exact prompt boundary. */
+    async findTurnCheckpointSkip(options) {
+        await this.ready;
+        const workspace = await discoverRepositoryRoot(options.cwd, options.signal);
+        await this.assertStorageSeparated(workspace);
+        const release = await this.acquireWorkspace(workspace, options.signal);
+        try {
+            const skip = await this.store.readTurnCheckpointSkip(workspace, options.sessionId, options.turn, options.turnStartSeq);
+            return skip === undefined ? undefined : { reason: skip.reason };
         }
         finally {
             await release();
@@ -103,42 +323,72 @@ export class ChangeLedgerEngine {
         await this.ready;
         const source = await discoverRepository(options.cwd, options.signal);
         await this.assertStorageSeparated(source.state.root);
-        const manifest = (await this.store.listManifests(source.state.root)).find(point => point.kind === 'turn'
-            && point.sessionId === options.sessionId
-            && point.turn === options.turn
-            && point.turnStartSeq !== undefined);
-        return manifest === undefined ? undefined : summarize(manifest);
+        const release = await this.acquireWorkspace(source.state.root, options.signal);
+        try {
+            const manifest = (await this.store.listManifests(source.state.root)).find(point => point.kind === 'turn'
+                && point.sessionId === options.sessionId
+                && point.turn === options.turn
+                && point.turnStartSeq !== undefined);
+            if (manifest?.version === 2)
+                await verifyGitCheckpoint(manifest, options.signal);
+            return manifest === undefined ? undefined : summarize(manifest);
+        }
+        finally {
+            await release();
+        }
     }
     /** List restore points for the current worktree. */
     async list(options) {
         await this.ready;
         const source = await discoverRepository(options.cwd, options.signal);
         await this.assertStorageSeparated(source.state.root);
-        const manifests = await this.store.listManifests(source.state.root);
-        return manifests
-            .filter((manifest) => manifest.kind === 'user'
-            || (manifest.kind === 'rescue' && options.includeRescue === true)
-            || (manifest.kind === 'turn' && options.includeTurnCheckpoints === true))
-            .map(summarize);
+        const release = await this.acquireWorkspace(source.state.root, options.signal);
+        try {
+            const manifests = await this.store.listManifests(source.state.root);
+            return manifests
+                .filter((manifest) => manifest.kind === 'user'
+                || (manifest.kind === 'rescue' && options.includeRescue === true)
+                || (manifest.kind === 'turn' && options.includeTurnCheckpoints === true))
+                .map(summarize);
+        }
+        finally {
+            await release();
+        }
     }
     /** Compare one restore point with the current worktree. */
     async inspect(options) {
         await this.ready;
         const source = await discoverRepository(options.cwd, options.signal);
         await this.assertStorageSeparated(source.state.root);
-        const manifest = await this.store.readManifest(source.state.root, options.restorePointId);
-        const current = await captureStableTree({ cwd: source.state.root, config: this.config, ...(options.signal === undefined ? {} : { signal: options.signal }) });
-        return {
-            restorePoint: summarize(manifest),
-            currentTreeHash: current.treeHash,
-            currentRepository: current.source.state,
-            ...(current.source.state.head === undefined ? {} : { currentHead: current.source.state.head }),
-            ...(current.source.state.branch === undefined ? {} : { currentBranch: current.source.state.branch }),
-            ...(current.source.state.operation === undefined ? {} : { currentOperation: current.source.state.operation }),
-            headChanged: repositoryHeadChanged(manifest.repository, current.source.state),
-            operationChanged: manifest.repository.operation !== current.source.state.operation,
-            changes: diffTrees(manifest.entries, current.entries),
-        };
+        const release = await this.acquireWorkspace(source.state.root, options.signal);
+        try {
+            const manifest = await this.store.readManifest(source.state.root, options.restorePointId);
+            if (manifest.version === 2)
+                await verifyGitCheckpoint(manifest, options.signal);
+            const current = await captureStableTree({
+                cwd: source.state.root,
+                config: this.config,
+                ...(manifest.version === 2 ? { gitObjectFormat: manifest.git.objectFormat } : {}),
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
+            });
+            const currentEntries = manifest.version === 2 ? current.gitEntries : current.entries;
+            if (currentEntries === undefined)
+                throw new ChangeLedgerError('STATE_CORRUPT', 'Git comparison entries are unavailable');
+            return {
+                restorePoint: summarize(manifest),
+                currentTreeHash: current.treeHash,
+                currentRepository: current.source.state,
+                ...(current.source.state.head === undefined ? {} : { currentHead: current.source.state.head }),
+                ...(current.source.state.branch === undefined ? {} : { currentBranch: current.source.state.branch }),
+                ...(current.source.state.operation === undefined ? {} : { currentOperation: current.source.state.operation }),
+                headChanged: repositoryHeadChanged(manifest.repository, current.source.state),
+                operationChanged: manifest.repository.operation !== current.source.state.operation,
+                changes: diffTrees(manifest.entries, current.entries, manifest.entries, currentEntries),
+            };
+        }
+        finally {
+            await release();
+        }
     }
     /** Produce an expiring, exact confirmation plan for a restore. */
     async planRestore(options) {
@@ -146,41 +396,57 @@ export class ChangeLedgerEngine {
         this.expirePlans();
         const source = await discoverRepository(options.cwd, options.signal);
         await this.assertStorageSeparated(source.state.root);
-        const manifest = await this.store.readManifest(source.state.root, options.restorePointId);
-        const current = await captureStableTree({ cwd: source.state.root, config: this.config, ...(options.signal === undefined ? {} : { signal: options.signal }) });
-        if (options.expectedCurrentTreeHash !== undefined && options.expectedCurrentTreeHash !== current.treeHash) {
-            throw new ChangeLedgerError('PLAN_STALE', 'workspace changed after inspection; inspect and plan again');
-        }
-        if (options.expectedRepository !== undefined && !sameRepositoryFence(options.expectedRepository, current.source.state)) {
-            throw new ChangeLedgerError('PLAN_STALE_REPOSITORY', 'Git repository state changed after inspection; inspect and plan again');
-        }
-        assertRepositoryCompatible(manifest, current.source.state, options.allowHeadChange === true);
-        const changes = diffTrees(manifest.entries, current.entries);
-        if (changes.length === 0) {
-            throw new ChangeLedgerError('NO_CHANGES', `workspace already matches restore point ${manifest.id}`);
-        }
-        const selected = selectChanges(changes, options.paths);
-        await assertNoUnmanagedRestoreConflicts(source.state.root, manifest.entries, current.entries, selected.map((change) => change.path));
-        const expected = Object.create(null);
-        for (const change of selected)
-            expected[change.path] = current.entries[change.path] ?? null;
-        const now = Date.now();
-        const plan = {
-            id: makeId('plan'),
-            restorePointId: manifest.id,
-            workspace: manifest.workspace,
-            repository: current.source.state,
-            ...(options.sessionId === undefined ? {} : { sessionId: options.sessionId }),
-            createdAt: now,
-            expiresAt: now + this.config.planTtlMs,
-            confirmation: `RESTORE-${randomBytes(4).toString('hex').toUpperCase()}`,
-            allowHeadChange: options.allowHeadChange === true,
-            paths: selected.map((change) => change.path),
-            changes: selected,
-            expected,
-        };
-        this.plans.set(plan.id, plan);
-        return clonePlan(plan);
+        const release = await this.acquireWorkspace(source.state.root, options.signal);
+        try {
+            const manifest = await this.store.readManifest(source.state.root, options.restorePointId);
+            if (manifest.version === 2)
+                await verifyGitCheckpoint(manifest, options.signal);
+            const current = await captureStableTree({
+                cwd: source.state.root,
+                config: this.config,
+                ...(manifest.version === 2 ? { gitObjectFormat: manifest.git.objectFormat } : {}),
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
+            });
+            const currentEntries = manifest.version === 2 ? current.gitEntries : current.entries;
+            if (currentEntries === undefined)
+                throw new ChangeLedgerError('STATE_CORRUPT', 'Git comparison entries are unavailable');
+            if (options.expectedCurrentTreeHash !== undefined && options.expectedCurrentTreeHash !== current.treeHash) {
+                throw new ChangeLedgerError('PLAN_STALE', 'workspace changed after inspection; inspect and plan again');
+            }
+            if (options.expectedRepository !== undefined && !sameRepositoryFence(options.expectedRepository, current.source.state)) {
+                throw new ChangeLedgerError('PLAN_STALE_REPOSITORY', 'Git repository state changed after inspection; inspect and plan again');
+            }
+            assertRepositoryCompatible(manifest, current.source.state, options.allowHeadChange === true);
+            const changes = diffTrees(manifest.entries, current.entries, manifest.entries, currentEntries);
+            if (changes.length === 0) {
+                throw new ChangeLedgerError('NO_CHANGES', `workspace already matches restore point ${manifest.id}`);
+            }
+            const selected = selectChanges(changes, options.paths);
+            await assertNoUnmanagedRestoreConflicts(source.state.root, manifest.entries, current.entries, selected.map((change) => change.path));
+            const expected = Object.create(null);
+            for (const change of selected)
+                expected[change.path] = current.entries[change.path] ?? null;
+            const now = Date.now();
+            const plan = {
+                id: makeId('plan'),
+                restorePointId: manifest.id,
+                workspace: manifest.workspace,
+                repository: current.source.state,
+                ...(options.sessionId === undefined ? {} : { sessionId: options.sessionId }),
+                createdAt: now,
+                expiresAt: now + this.config.planTtlMs,
+                confirmation: `RESTORE-${randomBytes(4).toString('hex').toUpperCase()}`,
+                allowHeadChange: options.allowHeadChange === true,
+                paths: selected.map((change) => change.path),
+                changes: selected,
+                expected,
+            };
+            this.plans.set(plan.id, plan);
+            return clonePlan(plan);
+        }
+        finally {
+            await release();
+        }
     }
     /** Apply one approved restore plan, creating a durable rescue point first. */
     async applyRestore(options) {
@@ -201,9 +467,11 @@ export class ChangeLedgerEngine {
         this.activePlans.add(plan.id);
         try {
             await this.assertStorageSeparated(plan.workspace);
-            const release = await this.store.acquire(plan.workspace);
+            const release = await this.acquireWorkspace(plan.workspace, options.signal);
             try {
                 const manifest = await this.store.readManifest(plan.workspace, plan.restorePointId);
+                if (manifest.version === 2)
+                    await verifyGitCheckpoint(manifest, options.signal);
                 const current = await captureStableTree({ cwd: plan.workspace, config: this.config, ...(options.signal === undefined ? {} : { signal: options.signal }) });
                 assertRepositoryCompatible(manifest, current.source.state, plan.allowHeadChange);
                 assertPlanRepositoryFresh(plan.repository, current.source.state);
@@ -239,8 +507,8 @@ export class ChangeLedgerEngine {
                 };
                 await this.store.writeOperation(operation);
                 try {
-                    await this.restorePaths(plan.workspace, manifest.entries, plan.paths, options.signal);
-                    await this.verifyPaths(plan.workspace, manifest.entries, plan.paths, options.signal);
+                    await this.restorePaths(plan.workspace, manifest.entries, plan.paths, options.signal, plan.expected);
+                    await this.verifyPaths(plan.workspace, manifest.entries, plan.paths, options.signal, manifest.version === 2 ? manifest.git.objectFormat : undefined);
                 }
                 catch (error) {
                     const primaryError = errorMessage(error);
@@ -324,13 +592,13 @@ export class ChangeLedgerEngine {
         }
         const source = await discoverRepository(options.cwd, options.signal);
         await this.assertStorageSeparated(source.state.root);
-        const release = await this.store.acquire(source.state.root);
+        const release = await this.acquireWorkspace(source.state.root, options.signal);
         try {
-            await this.store.readManifest(source.state.root, options.restorePointId);
+            const manifest = await this.store.readManifest(source.state.root, options.restorePointId);
             if (await this.store.isReferencedByRecovery(source.state.root, options.restorePointId)) {
                 throw new ChangeLedgerError('RECOVERY_REFERENCE', 'restore point is required by an incomplete recovery journal');
             }
-            await this.store.deleteManifest(source.state.root, options.restorePointId);
+            await this.deleteManifestWithGit(manifest, options.signal);
             const gc = await this.store.collectGarbage(source.state.root);
             return { restorePointId: options.restorePointId, ...gc };
         }
@@ -343,18 +611,146 @@ export class ChangeLedgerEngine {
         await this.ready;
         const source = await discoverRepository(options.cwd, options.signal);
         await this.assertStorageSeparated(source.state.root);
-        return (await this.store.listOperations(source.state.root))
-            .filter((operation) => operation.state === 'interrupted' || operation.state === 'recovery-required')
-            .map((operation) => ({
-            operationId: operation.id,
-            restorePointId: operation.restorePointId,
-            rescuePointId: operation.rescuePointId,
-            state: operation.state,
-            paths: operation.paths,
-            startedAt: operation.startedAt,
-            ...(operation.error === undefined ? {} : { error: operation.error }),
-            ...(operation.rollbackError === undefined ? {} : { rollbackError: operation.rollbackError }),
-        }));
+        const release = await this.acquireWorkspace(source.state.root, options.signal);
+        try {
+            return (await this.store.listOperations(source.state.root))
+                .filter((operation) => operation.state === 'interrupted' || operation.state === 'recovery-required')
+                .map((operation) => ({
+                operationId: operation.id,
+                restorePointId: operation.restorePointId,
+                rescuePointId: operation.rescuePointId,
+                state: operation.state,
+                paths: operation.paths,
+                startedAt: operation.startedAt,
+                ...(operation.error === undefined ? {} : { error: operation.error }),
+                ...(operation.rollbackError === undefined ? {} : { rollbackError: operation.rollbackError }),
+            }));
+        }
+        finally {
+            await release();
+        }
+    }
+    /** Inventory every workspace this storage root has ever persisted state for. */
+    async listWorkspaces(options = {}) {
+        await this.ready;
+        const groups = new Map();
+        const groupOf = (workspace) => {
+            const existing = groups.get(workspace);
+            if (existing !== undefined)
+                return existing;
+            const created = { restorePoints: [], recoveryCount: 0 };
+            groups.set(workspace, created);
+            return created;
+        };
+        for (const workspaceDir of await this.store.listWorkspaceDirs(options.signal)) {
+            for (const manifest of await this.store.listManifestsInDir(workspaceDir, options.signal)) {
+                groupOf(manifest.workspace).restorePoints.push(summarize(manifest));
+            }
+            for (const operation of await this.store.listOperationsInDir(workspaceDir, options.signal)) {
+                if (operation.state === 'interrupted' || operation.state === 'recovery-required') {
+                    groupOf(operation.workspace).recoveryCount += 1;
+                }
+            }
+        }
+        return [...groups.entries()]
+            .map(([workspace, group]) => ({
+            workspace,
+            restorePoints: [...group.restorePoints].sort((left, right) => right.createdAt - left.createdAt || right.id.localeCompare(left.id)),
+            totalBytes: group.restorePoints.reduce((total, point) => total + point.totalBytes, 0),
+            recoveryCount: group.recoveryCount,
+        }))
+            .sort((left, right) => left.workspace.localeCompare(right.workspace));
+    }
+    /** Delete unprotected restore points recorded for one workspace and collect unused blobs. */
+    async purgeWorkspace(options) {
+        await this.ready;
+        const restorePointIds = options.restorePointIds === undefined ? undefined : new Set(options.restorePointIds);
+        const targetDirs = new Set();
+        for (const workspaceDir of await this.store.listWorkspaceDirs(options.signal)) {
+            for (const manifest of await this.store.listManifestsInDir(workspaceDir, options.signal)) {
+                if (manifest.workspace === options.workspace
+                    && (restorePointIds === undefined || restorePointIds.has(manifest.id))) {
+                    targetDirs.add(workspaceDir);
+                }
+            }
+            for (const operation of await this.store.listOperationsInDir(workspaceDir, options.signal)) {
+                if (operation.workspace === options.workspace)
+                    targetDirs.add(workspaceDir);
+            }
+        }
+        let deletedRestorePoints = 0;
+        let retainedRestorePoints = 0;
+        let deletedBlobs = 0;
+        let retainedBlobs = 0;
+        for (const workspaceDir of targetDirs) {
+            const result = await this.purgeWorkspaceDir(workspaceDir, options.workspace, restorePointIds, options.signal);
+            deletedRestorePoints += result.deletedRestorePoints;
+            retainedRestorePoints += result.retainedRestorePoints;
+            deletedBlobs += result.deletedBlobs;
+            retainedBlobs += result.retainedBlobs;
+        }
+        return { workspace: options.workspace, deletedRestorePoints, retainedRestorePoints, deletedBlobs, retainedBlobs };
+    }
+    async purgeWorkspaceDir(workspaceDir, workspace, restorePointIds, signal) {
+        // A live repository needs both its shared Git lock and durable directory lock.
+        // A missing path, or one now nested under a different repository, cannot expose
+        // its old Git namespace but still takes the durable lock before storage cleanup.
+        let liveRepository = false;
+        let release;
+        try {
+            const root = await discoverRepositoryRoot(workspace, signal);
+            if (root === workspace) {
+                await this.assertStorageSeparated(root);
+                release = await this.acquireWorkspace(root, signal);
+                liveRepository = true;
+            }
+            else {
+                release = await this.store.acquireWorkspaceDir(workspaceDir, workspace, signal);
+            }
+        }
+        catch (error) {
+            if (!(error instanceof ChangeLedgerError) || error.code !== 'WORKSPACE_NOT_FOUND')
+                throw error;
+            release = await this.store.acquireWorkspaceDir(workspaceDir, workspace, signal);
+        }
+        let deletedRestorePoints = 0;
+        let retainedRestorePoints = 0;
+        try {
+            const manifests = (await this.store.listManifestsInDir(workspaceDir, signal))
+                .filter((manifest) => manifest.workspace === workspace
+                && (restorePointIds === undefined || restorePointIds.has(manifest.id)));
+            const protectedIds = new Set();
+            for (const operation of await this.store.listOperationsInDir(workspaceDir, signal)) {
+                if (operation.state === 'running' || operation.state === 'rollback-running'
+                    || operation.state === 'interrupted' || operation.state === 'recovery-required') {
+                    protectedIds.add(operation.restorePointId);
+                    protectedIds.add(operation.rescuePointId);
+                }
+            }
+            for (const journal of await this.store.listGitCheckpointJournalsInDir(workspaceDir, signal)) {
+                protectedIds.add(journal.restorePointId);
+            }
+            for (const manifest of manifests) {
+                if (protectedIds.has(manifest.id)) {
+                    retainedRestorePoints += 1;
+                    continue;
+                }
+                if (liveRepository) {
+                    await this.deleteManifestWithGit(manifest, signal);
+                }
+                else {
+                    await this.store.deleteManifestInDir(workspaceDir, manifest.id);
+                }
+                deletedRestorePoints += 1;
+            }
+            if (restorePointIds === undefined)
+                await this.store.clearTurnOutcomesInDir(workspaceDir);
+            const gc = await this.store.collectGarbageInDir(workspaceDir, signal);
+            return { deletedRestorePoints, retainedRestorePoints, ...gc };
+        }
+        finally {
+            await release();
+        }
     }
     async createLocked(options) {
         const existing = await this.store.listManifests(options.cwd);
@@ -362,6 +758,11 @@ export class ChangeLedgerEngine {
         if (options.kind !== 'turn' && durableUserPoints.length >= this.config.maxRestorePoints) {
             throw new ChangeLedgerError('RESTORE_POINT_LIMIT', `workspace already has ${durableUserPoints.length} user/rescue restore points; configured maximum is ${this.config.maxRestorePoints}`);
         }
+        if (options.deferGarbageCollection === true) {
+            await this.store.reconcileSnapshotCleanup(options.cwd, options.signal);
+            throwIfAborted(options.signal);
+            await this.store.writeSnapshotCleanup(options.cwd);
+        }
         try {
             const tree = await captureStableTree({
                 cwd: options.cwd,
@@ -388,13 +789,20 @@ export class ChangeLedgerEngine {
                 entries: tree.entries,
                 restoreCount: 0,
             };
-            await this.store.collectGarbage(options.cwd, Object.values(manifest.entries)
-                .filter((entry) => entry.kind === 'file')
-                .map((entry) => entry.blob));
+            if (options.deferGarbageCollection !== true) {
+                await this.store.collectGarbage(options.cwd, Object.values(manifest.entries)
+                    .filter((entry) => entry.kind === 'file' && entry.provider !== 'git')
+                    .map((entry) => entry.blob));
+            }
             await this.store.writeManifest(manifest);
+            if (options.deferGarbageCollection === true) {
+                await this.store.deleteSnapshotCleanup(options.cwd).catch(() => undefined);
+            }
             return manifest;
         }
         catch (error) {
+            if (options.deferGarbageCollection === true)
+                throw error;
             try {
                 await this.store.collectGarbage(options.cwd);
             }
@@ -404,11 +812,14 @@ export class ChangeLedgerEngine {
             throw error;
         }
     }
-    async restorePaths(workspace, desiredEntries, paths, signal) {
+    async restorePaths(workspace, desiredEntries, paths, signal, expectedEntries) {
         const deletions = paths.filter((path) => desiredEntries[path] === undefined).sort(compareDeepestFirst);
         for (const path of deletions) {
             throwIfAborted(signal);
             const target = resolveWorkspacePath(workspace, path);
+            if (expectedEntries !== undefined)
+                await this.assertPathFresh(workspace, path, expectedEntries[path], signal);
+            await assertSafeParents(workspace, target);
             await removeRestoreTarget(target);
             await pruneEmptyParents(workspace, target);
         }
@@ -419,6 +830,8 @@ export class ChangeLedgerEngine {
             if (entry === undefined)
                 continue;
             const target = resolveWorkspacePath(workspace, path);
+            if (expectedEntries !== undefined)
+                await this.assertPathFresh(workspace, path, expectedEntries[path], signal);
             await ensureSafeParents(workspace, target);
             try {
                 const info = await lstat(target);
@@ -430,10 +843,16 @@ export class ChangeLedgerEngine {
                     throw error;
             }
             if (entry.kind === 'file') {
-                const content = await this.store.readBlob(workspace, entry.blob);
+                const content = entry.provider === 'git'
+                    ? await readGitBlob(workspace, entry.blob, entry.size, signal)
+                    : await this.store.readBlob(workspace, entry.blob);
                 if (content.length !== entry.size) {
                     throw new ChangeLedgerError('BLOB_CORRUPT', `blob ${entry.blob} has unexpected size for ${JSON.stringify(path)}`);
                 }
+                if (expectedEntries !== undefined)
+                    await this.assertPathFresh(workspace, path, expectedEntries[path], signal);
+                else
+                    await assertSafeParents(workspace, target);
                 await replaceRegularFile(target, content, entry.mode);
             }
             else {
@@ -441,13 +860,44 @@ export class ChangeLedgerEngine {
             }
         }
     }
-    async verifyPaths(workspace, desiredEntries, paths, signal) {
-        const current = await captureStableTree({ cwd: workspace, config: this.config, ...(signal === undefined ? {} : { signal }) });
-        for (const path of paths) {
-            if (!entriesEqual(desiredEntries[path], current.entries[path])) {
-                throw new ChangeLedgerError('RESTORE_VERIFY_FAILED', `restored path did not match its expected snapshot: ${JSON.stringify(path)}`);
+    async assertPathFresh(workspace, path, expected, signal) {
+        const target = resolveWorkspacePath(workspace, path);
+        await assertSafeParents(workspace, target);
+        let current;
+        try {
+            current = await captureSnapshotEntry(workspace, path, this.config.maxFileBytes, signal);
+        }
+        catch (error) {
+            if (error instanceof ChangeLedgerError && error.code === 'UNSUPPORTED_FILE_TYPE') {
+                throw new ChangeLedgerError('PLAN_STALE', `workspace path changed type after planning: ${JSON.stringify(path)}`, { cause: error });
             }
+            throw error;
+        }
+        if (!entriesEqual(expected === null ? undefined : expected, current)) {
+            throw new ChangeLedgerError('PLAN_STALE', `workspace changed immediately before restore at ${JSON.stringify(path)}; inspect and plan again`);
+        }
+    }
+    async verifyPaths(workspace, desiredEntries, paths, signal, gitObjectFormat) {
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            const first = await this.captureSelectedEntries(workspace, paths, signal, gitObjectFormat);
+            const second = await this.captureSelectedEntries(workspace, paths, signal, gitObjectFormat);
+            if (!paths.every(path => entriesEqual(first.get(path), second.get(path))))
+                continue;
+            for (const path of paths) {
+                if (!entriesEqual(desiredEntries[path], second.get(path))) {
+                    throw new ChangeLedgerError('RESTORE_VERIFY_FAILED', `restored path did not match its expected snapshot: ${JSON.stringify(path)}`);
+                }
+            }
+            return;
+        }
+        throw new ChangeLedgerError('RESTORE_VERIFY_FAILED', 'restored paths did not remain stable during post-verification');
+    }
+    async captureSelectedEntries(workspace, paths, signal, gitObjectFormat) {
+        const entries = new Map();
+        for (const path of paths) {
+            entries.set(path, await captureSnapshotEntry(workspace, path, this.config.maxFileBytes, signal, gitObjectFormat));
         }
+        return entries;
     }
     async assertStorageSeparated(workspace) {
         const storage = await realpath(resolve(this.config.storageDir));
@@ -481,10 +931,15 @@ export function resolveConfig(config) {
         maxSnapshotBytes: positiveInteger(config.maxSnapshotBytes ?? DEFAULTS.maxSnapshotBytes, 'maxSnapshotBytes'),
         planTtlMs: positiveInteger(config.planTtlMs ?? DEFAULTS.planTtlMs, 'planTtlMs'),
         staleLockMs: positiveInteger(config.staleLockMs ?? DEFAULTS.staleLockMs, 'staleLockMs'),
+        turnCheckpointMode: checkpointMode(config.turnCheckpointMode ?? DEFAULTS.turnCheckpointMode),
+        turnCheckpointTimeoutMs: positiveInteger(config.turnCheckpointTimeoutMs ?? DEFAULTS.turnCheckpointTimeoutMs, 'turnCheckpointTimeoutMs'),
+        turnCheckpointMaxNewBytes: positiveInteger(config.turnCheckpointMaxNewBytes ?? DEFAULTS.turnCheckpointMaxNewBytes, 'turnCheckpointMaxNewBytes'),
+        turnCheckpointTrust: checkpointTrust(config.turnCheckpointTrust ?? DEFAULTS.turnCheckpointTrust),
     };
 }
 function summarize(manifest) {
     return {
+        format: manifest.version,
         id: manifest.id,
         kind: manifest.kind,
         workspace: manifest.workspace,
@@ -504,6 +959,7 @@ function summarize(manifest) {
         ...(manifest.repository.branch === undefined ? {} : { branch: manifest.repository.branch }),
         ...(manifest.repository.operation === undefined ? {} : { operation: manifest.repository.operation }),
         stagedPathCount: manifest.repository.stagedPaths.length,
+        ...(manifest.version === 2 ? { trust: manifest.git.trust } : {}),
     };
 }
 function assertRepositoryCompatible(manifest, current, allowHeadChange) {
@@ -529,6 +985,18 @@ function assertPlanRepositoryFresh(planned, current) {
         throw new ChangeLedgerError('PLAN_STALE_REPOSITORY', 'Git repository state changed after restore planning; inspect and plan again');
     }
 }
+function assertJournalMatchesManifest(journal, manifest) {
+    if (manifest.version !== 2
+        || manifest.workspace !== journal.workspace
+        || manifest.id !== journal.restorePointId
+        || manifest.repository.commonDir !== journal.commonDir
+        || manifest.git.storeId !== journal.storeId
+        || manifest.git.worktreeId !== journal.worktreeId
+        || manifest.git.ref !== journal.ref
+        || manifest.git.commit !== journal.commit) {
+        throw new ChangeLedgerError('STATE_CORRUPT', `Git checkpoint journal does not match restore point ${journal.restorePointId}`);
+    }
+}
 function selectChanges(changes, requested) {
     if (requested === undefined || requested.length === 0)
         return [...changes];
@@ -601,10 +1069,43 @@ function requireNonEmptyString(value, name) {
     }
     return value;
 }
+function checkpointMode(value) {
+    if (value !== 'off' && value !== 'git-native' && value !== 'legacy') {
+        throw new ChangeLedgerError('INVALID_CONFIG', 'turnCheckpointMode must be off, git-native, or legacy');
+    }
+    return value;
+}
+function checkpointTrust(value) {
+    if (value !== 'fast' && value !== 'strict') {
+        throw new ChangeLedgerError('INVALID_CONFIG', 'turnCheckpointTrust must be fast or strict');
+    }
+    return value;
+}
 function throwIfAborted(signal) {
     if (signal?.aborted === true)
         throw signal.reason;
 }
+async function waitWithSignal(promise, signal) {
+    if (signal === undefined)
+        return promise;
+    signal.throwIfAborted();
+    let rejectAbort;
+    const aborted = new Promise((_resolve, reject) => { rejectAbort = reject; });
+    const onAbort = () => rejectAbort?.(signal.reason);
+    signal.addEventListener('abort', onAbort, { once: true });
+    try {
+        return await Promise.race([promise, aborted]);
+    }
+    finally {
+        signal.removeEventListener('abort', onAbort);
+    }
+}
+function checkpointDeadlineError(error, timeoutMs, deadline, callerSignal) {
+    if (callerSignal?.aborted !== true && deadline.aborted) {
+        return new ChangeLedgerError('TURN_CHECKPOINT_TIMEOUT', `automatic checkpoint exceeded ${timeoutMs} ms`, { cause: error });
+    }
+    return error;
+}
 function depth(path) {
     return path.split('/').length;
 }