dsh-git-worktree 0.3.2 → 0.6.0

package/lib/session-checkout-apply.js

@@ -1,7 +1,7 @@
 import { spawn } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
 import { realpathSync } from 'node:fs';
-import { copyFile, mkdir, mkdtemp, rename, rm, unlink } from 'node:fs/promises';
+import { copyFile, mkdir, mkdtemp, open, readFile, rename, rm, unlink, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { delimiter, isAbsolute, join, relative, resolve } from 'node:path';
 class GitCommandFailure extends Error {
@@ -130,9 +130,20 @@ async function selectEffectiveApplyBase(checkoutPath, recordedBaseOid, localHead
     return { oid: recordedBaseOid, strategy: 'recorded_base' };
 }
 async function changedTreePaths(checkoutPath, baseOid, treeOid, objectDirectory, sourceObjects) {
-    const result = await runGit(checkoutPath, ['diff', '--name-only', '-z', '--no-ext-diff', '--no-renames', baseOid, treeOid, '--'], { env: gitObjectEnvironment(objectDirectory, sourceObjects) });
+    const result = await runGit(checkoutPath, ['diff', '--name-only', '-z', '--no-ext-diff', '--no-renames', baseOid, treeOid, '--'], { env: objectDirectory && sourceObjects ? gitObjectEnvironment(objectDirectory, sourceObjects) : undefined });
     return parseNullSeparated(result.stdout);
 }
+function snapshotFingerprint(headOid, headRef, indexEntries, treeOid) {
+    return createHash('sha256')
+        .update(headOid)
+        .update('\0')
+        .update(headRef ?? 'DETACHED')
+        .update('\0')
+        .update(indexEntries)
+        .update('\0')
+        .update(treeOid)
+        .digest('hex');
+}
 async function captureSnapshot(checkoutPath, indexPath, objectDirectory, sourceObjects) {
     const headOid = stdoutText(await runGit(checkoutPath, ['rev-parse', 'HEAD']));
     const headTreeOid = stdoutText(await runGit(checkoutPath, ['rev-parse', `${headOid}^{tree}`]));
@@ -165,16 +176,8 @@ async function captureSnapshot(checkoutPath, indexPath, objectDirectory, sourceO
     // 先还原真实 index 的 staged 语义，再叠加 working tree，得到完整最终状态。
     await runGit(checkoutPath, ['add', '-A', '--', '.'], { env });
     const treeOid = stdoutText(await runGit(checkoutPath, ['write-tree'], { env }));
-    const fingerprint = createHash('sha256')
-        .update(headOid)
-        .update('\0')
-        .update(headRef ?? 'DETACHED')
-        .update('\0')
-        .update(indexEntries)
-        .update('\0')
-        .update(treeOid)
-        .digest('hex');
-    return { fingerprint, headOid, headRef, headTreeOid, indexTreeOid, treeOid };
+    const fingerprint = snapshotFingerprint(headOid, headRef, indexEntries, treeOid);
+    return { fingerprint, headOid, headRef, headTreeOid, indexTreeOid, treeOid, indexEntries };
 }
 async function createSnapshotCommit(checkoutPath, treeOid, parentOid, objectDirectory, sourceObjects, label) {
     const args = ['commit-tree', treeOid, ...(parentOid ? ['-p', parentOid] : [])];
@@ -349,9 +352,135 @@ async function prepareIndexFromPatch(checkoutPath, indexPath, baseOid, patch) {
 async function createUserCommit(checkoutPath, treeOid, parentOid, commitMessage) {
     return stdoutText(await runGit(checkoutPath, ['commit-tree', treeOid, '-p', parentOid], { input: `${commitMessage.trim()}\n` }));
 }
+async function prepareRollbackAssessment(tempRoot, sourceObjects, objectDirectory, localGitRoot, current, receipt) {
+    if (current.headRef !== receipt.localHeadRef) {
+        return { status: 'blocked', code: 'stale_local', message: 'Local branch 已变化，不能自动撤回 Preview' };
+    }
+    if (current.headOid !== receipt.localHeadOid && !await isAncestor(localGitRoot, receipt.localHeadOid, current.headOid)) {
+        return { status: 'blocked', code: 'stale_local', message: 'Local HEAD 不是 Preview 基线的安全快进，不能自动撤回' };
+    }
+    let rollbackBaselineTreeOid = receipt.localWorkingTreeOid;
+    let expectedPreviewTreeOid = receipt.previewWorkingTreeOid;
+    if (current.headOid !== receipt.localHeadOid) {
+        const receiptHeadTreeOid = stdoutText(await runGit(localGitRoot, ['rev-parse', `${receipt.localHeadOid}^{tree}`]));
+        const advancedBaseline = await computeTreeMerge(tempRoot, sourceObjects, objectDirectory, localGitRoot, 'preview-rollback-advanced-baseline', receiptHeadTreeOid, current.headTreeOid, receipt.localWorkingTreeOid);
+        if (advancedBaseline.status === 'conflict') {
+            return {
+                status: 'blocked', code: 'preview_modified',
+                message: `Local 新提交与 Preview 前的本地修改冲突，无法安全撤回：${advancedBaseline.conflictingFiles.join('、')}`,
+                conflictingFiles: [...advancedBaseline.conflictingFiles],
+            };
+        }
+        const previewAbsence = await computeTreeMerge(tempRoot, sourceObjects, objectDirectory, localGitRoot, 'preview-rollback-preview-absence', receipt.previewWorkingTreeOid, advancedBaseline.treeOid, receipt.localWorkingTreeOid);
+        if (previewAbsence.status === 'conflict') {
+            return {
+                status: 'blocked', code: 'preview_modified',
+                message: `Local 新提交与 Preview 任务增量冲突，无法安全撤回：${previewAbsence.conflictingFiles.join('、')}`,
+                conflictingFiles: [...previewAbsence.conflictingFiles],
+            };
+        }
+        if (previewAbsence.treeOid !== advancedBaseline.treeOid) {
+            return {
+                status: 'blocked', code: 'preview_modified',
+                message: 'Local 新提交已经包含部分或全部 Preview 增量，不能通过撤回工作区改动来改写已提交历史',
+            };
+        }
+        const advancedPreview = await computeTreeMerge(tempRoot, sourceObjects, objectDirectory, localGitRoot, 'preview-rollback-advanced-preview', receipt.localWorkingTreeOid, advancedBaseline.treeOid, receipt.previewWorkingTreeOid);
+        if (advancedPreview.status === 'conflict') {
+            return {
+                status: 'blocked', code: 'preview_modified',
+                message: `Local 新提交与 Preview 任务增量冲突，无法安全撤回：${advancedPreview.conflictingFiles.join('、')}`,
+                conflictingFiles: [...advancedPreview.conflictingFiles],
+            };
+        }
+        rollbackBaselineTreeOid = advancedBaseline.treeOid;
+        expectedPreviewTreeOid = advancedPreview.treeOid;
+    }
+    const rollbackTree = await computeTreeMerge(tempRoot, sourceObjects, objectDirectory, localGitRoot, 'preview-rollback', expectedPreviewTreeOid, current.treeOid, rollbackBaselineTreeOid);
+    if (rollbackTree.status === 'conflict') {
+        return {
+            status: 'blocked', code: 'preview_modified',
+            message: `Local 在 Preview 区域出现额外修改，无法安全撤回：${rollbackTree.conflictingFiles.join('、')}`,
+            conflictingFiles: [...rollbackTree.conflictingFiles],
+        };
+    }
+    return { status: 'safe', targetTreeOid: rollbackTree.treeOid };
+}
+async function prepareFinalizeAssessment(tempRoot, sourceObjects, objectDirectory, localGitRoot, current, receipt) {
+    if (!receipt.localHeadRef?.startsWith('refs/heads/')) {
+        return { status: 'blocked', code: 'operation_not_allowed', message: 'Local 当前不是普通分支，不能自动创建任务提交' };
+    }
+    if (current.headRef !== receipt.localHeadRef) {
+        return { status: 'blocked', code: 'stale_local', message: 'Local branch 已变化，不能完成 Preview 提交' };
+    }
+    if (current.headOid !== receipt.localHeadOid && !await isAncestor(localGitRoot, receipt.localHeadOid, current.headOid)) {
+        return { status: 'blocked', code: 'stale_local', message: 'Local HEAD 不是 Preview 基线的安全快进，不能完成 Preview 提交' };
+    }
+    const previewRemoval = await computeTreeMerge(tempRoot, sourceObjects, objectDirectory, localGitRoot, 'preview-finalize-separation', receipt.previewWorkingTreeOid, current.treeOid, receipt.localWorkingTreeOid);
+    if (previewRemoval.status === 'conflict') {
+        return {
+            status: 'blocked', code: 'preview_modified',
+            message: `Local 在 Preview 区域出现额外修改，无法可靠提交：${previewRemoval.conflictingFiles.join('、')}`,
+            conflictingFiles: [...previewRemoval.conflictingFiles],
+        };
+    }
+    const taskTree = await computeTreeMerge(tempRoot, sourceObjects, objectDirectory, localGitRoot, 'preview-task-isolation', receipt.localWorkingTreeOid, current.headTreeOid, receipt.previewWorkingTreeOid);
+    if (taskTree.status === 'conflict') {
+        return {
+            status: 'blocked', code: 'commit_isolation_conflict',
+            message: `Preview 任务增量无法与最新 Local HEAD 可靠拆分：${taskTree.conflictingFiles.join('、')}`,
+            conflictingFiles: [...taskTree.conflictingFiles],
+        };
+    }
+    if (taskTree.treeOid === current.headTreeOid && receipt.changedFiles.length > 0) {
+        return {
+            status: 'blocked', code: 'preview_modified',
+            message: 'Preview 任务增量已经进入 Local HEAD；不会创建重复或空提交',
+        };
+    }
+    const finalIndexTree = await computeTreeMerge(tempRoot, sourceObjects, objectDirectory, localGitRoot, 'preview-index-preservation', current.headTreeOid, taskTree.treeOid, current.indexTreeOid);
+    if (finalIndexTree.status === 'conflict') {
+        return {
+            status: 'blocked', code: 'commit_isolation_conflict',
+            message: `Preview 提交与 Local staged 修改无法可靠分离：${finalIndexTree.conflictingFiles.join('、')}`,
+            conflictingFiles: [...finalIndexTree.conflictingFiles],
+        };
+    }
+    return {
+        status: 'safe', taskTreeOid: taskTree.treeOid, finalIndexTreeOid: finalIndexTree.treeOid,
+        expectedWorkingTreeOid: current.treeOid,
+        commitRequired: receipt.changedFiles.length > 0 && taskTree.treeOid !== current.headTreeOid,
+    };
+}
 async function resolveIndexPath(checkoutPath) {
     return resolve(checkoutPath, stdoutText(await runGit(checkoutPath, ['rev-parse', '--path-format=absolute', '--git-path', 'index'])));
 }
+async function inspectIndexFileTree(checkoutPath, indexPath) {
+    try {
+        const handle = await open(indexPath, 'r');
+        await handle.close();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { exists: false };
+        throw error;
+    }
+    try {
+        const treeOid = stdoutText(await runGit(checkoutPath, ['write-tree'], { env: { GIT_INDEX_FILE: indexPath } }));
+        return { exists: true, treeOid };
+    }
+    catch {
+        return { exists: true, treeOid: null };
+    }
+}
+async function checkpointLockMarkerOwned(markerPath, commitOid) {
+    try {
+        return (await readFile(markerPath, 'utf8')).trim() === commitOid;
+    }
+    catch {
+        return false;
+    }
+}
 async function removeBestEffort(path) {
     if (!path)
         return;
@@ -362,12 +491,263 @@ async function removeBestEffort(path) {
         // 临时 index 不存在或已完成 rename 时无需处理。
     }
 }
+async function writeIndexLock(indexPath, contents) {
+    const lockPath = `${indexPath}.lock`;
+    let handle = null;
+    try {
+        handle = await open(lockPath, 'wx');
+        await handle.writeFile(contents);
+        await handle.sync();
+        await handle.close();
+        handle = null;
+        return lockPath;
+    }
+    catch (error) {
+        try {
+            await handle?.close();
+        }
+        catch {
+            // 原始错误优先；finally 会清理由本次调用创建的 lock。
+        }
+        if (handle)
+            await removeBestEffort(lockPath);
+        throw error;
+    }
+}
+function isIndexLockContention(error) {
+    return error !== null
+        && typeof error === 'object'
+        && 'code' in error
+        && error.code === 'EEXIST';
+}
 class DefaultSessionCheckoutApplyEngine {
     options;
     plans = new Map();
     constructor(options) {
         this.options = options;
     }
+    async checkpoint(input) {
+        const commitMessage = input.commitMessage.trim();
+        if (!commitMessage || commitMessage.length > 500 || !OID_PATTERN.test(input.expectedHeadOid) || !input.expectedFingerprint.trim()) {
+            return { status: 'error', error: { code: 'invalid_input', message: 'Checkpoint 输入无效' } };
+        }
+        let tempRoot = null;
+        let adjacentIndex = null;
+        let indexLockMarker = null;
+        let preserveRecoveryEvidence = false;
+        try {
+            tempRoot = await mkdtemp(join(tmpdir(), 'dsh-checkpoint-'));
+            const isolatedGitRoot = await resolveGitRoot(input.isolatedPath);
+            const projectPathPrefix = projectPrefix(isolatedGitRoot, input.isolatedPath);
+            if (projectPathPrefix === null) {
+                return { status: 'error', error: { code: 'invalid_input', message: 'Checkpoint 项目目录不属于当前 Worktree' } };
+            }
+            const snapshot = await captureSnapshot(isolatedGitRoot, join(tempRoot, 'checkpoint.index'), null, null);
+            if (snapshot.headRef !== null) {
+                return { status: 'error', error: { code: 'operation_not_allowed', message: 'Checkpoint 只允许写入 detached managed Worktree' } };
+            }
+            if (snapshot.headOid !== input.expectedHeadOid || snapshot.fingerprint !== input.expectedFingerprint) {
+                return { status: 'error', error: { code: 'stale_isolated', message: 'Worktree 在准备验收后发生变化，不能保存阶段' } };
+            }
+            const changedPaths = await changedTreePaths(isolatedGitRoot, snapshot.headOid, snapshot.treeOid, null, null);
+            if (changedPaths.some((path) => !isProjectPath(path, projectPathPrefix))) {
+                return { status: 'error', error: { code: 'invalid_input', message: 'Worktree 包含项目根目录外的变更，不能保存阶段' } };
+            }
+            const changedFiles = changedPaths.map((path) => toProjectPath(path, projectPathPrefix)).sort();
+            if (changedFiles.length === 0) {
+                return { status: 'error', error: { code: 'operation_not_allowed', message: '当前阶段没有可保存的新修改' } };
+            }
+            const commitOid = await createUserCommit(isolatedGitRoot, snapshot.treeOid, snapshot.headOid, commitMessage);
+            await input.beforeCommit?.({ commitOid, parentOid: snapshot.headOid, indexTreeOid: snapshot.indexTreeOid, changedFiles });
+            const finalIndexPath = join(tempRoot, 'clean.index');
+            await prepareIndexFromPatch(isolatedGitRoot, finalIndexPath, commitOid, Buffer.alloc(0));
+            const realIndexPath = await resolveIndexPath(isolatedGitRoot);
+            const indexLockPath = `${realIndexPath}.lock`;
+            indexLockMarker = `${indexLockPath}.dsh-${commitOid}`;
+            await writeFile(indexLockMarker, `${commitOid}\n`, { flag: 'wx' });
+            const indexLock = await open(indexLockPath, 'wx');
+            adjacentIndex = indexLockPath;
+            await indexLock.close();
+            await copyFile(finalIndexPath, adjacentIndex);
+            await this.options.beforeFinalIsolatedValidation?.();
+            const finalSnapshot = await captureSnapshot(isolatedGitRoot, join(tempRoot, 'final-checkpoint.index'), null, null);
+            if (finalSnapshot.headOid !== snapshot.headOid || finalSnapshot.fingerprint !== snapshot.fingerprint) {
+                return { status: 'error', error: { code: 'stale_isolated', message: 'Worktree 在保存阶段前发生变化，请重新准备验收' } };
+            }
+            let headUpdated = false;
+            try {
+                await runGit(isolatedGitRoot, ['update-ref', '--no-deref', 'HEAD', commitOid, snapshot.headOid]);
+                headUpdated = true;
+                await rename(adjacentIndex, realIndexPath);
+                adjacentIndex = null;
+                await removeBestEffort(indexLockMarker);
+                indexLockMarker = null;
+            }
+            catch (error) {
+                if (headUpdated) {
+                    try {
+                        await runGit(isolatedGitRoot, ['update-ref', '--no-deref', 'HEAD', snapshot.headOid, commitOid]);
+                    }
+                    catch (rollbackError) {
+                        preserveRecoveryEvidence = true;
+                        return {
+                            status: 'error',
+                            error: {
+                                code: 'git_error',
+                                message: `Checkpoint index 写入失败且 HEAD 无法回滚：${this.errorMessage(error)}；${this.errorMessage(rollbackError)}`,
+                                recoveryState: 'uncertain',
+                            },
+                        };
+                    }
+                }
+                return {
+                    status: 'error',
+                    error: {
+                        code: 'git_error',
+                        message: `Checkpoint 写入失败，已回滚：${this.errorMessage(error)}`,
+                        recoveryState: 'unchanged',
+                    },
+                };
+            }
+            try {
+                await this.options.afterIsolatedWriteBeforeVerification?.();
+                const completed = await captureSnapshot(isolatedGitRoot, join(tempRoot, 'completed.index'), null, null);
+                if (completed.headOid !== commitOid
+                    || completed.headRef !== null
+                    || completed.headTreeOid !== snapshot.treeOid
+                    || completed.indexTreeOid !== snapshot.treeOid
+                    || completed.treeOid !== snapshot.treeOid) {
+                    return {
+                        status: 'error',
+                        error: { code: 'git_error', message: 'Checkpoint 已写入，但 Worktree 未收敛到 clean 状态', recoveryState: 'uncertain' },
+                    };
+                }
+                return {
+                    status: 'checkpointed',
+                    commitOid,
+                    parentOid: snapshot.headOid,
+                    changedFiles,
+                    isolatedFingerprint: completed.fingerprint,
+                };
+            }
+            catch (error) {
+                return {
+                    status: 'error',
+                    error: {
+                        code: 'git_error',
+                        message: `Checkpoint 写后无法完成验证，需要保留现场确认：${this.errorMessage(error)}`,
+                        recoveryState: 'uncertain',
+                    },
+                };
+            }
+        }
+        catch (error) {
+            const stale = isIndexLockContention(error);
+            return {
+                status: 'error',
+                error: stale
+                    ? { code: 'stale_isolated', message: 'Worktree index 正在被其他 Git 操作更新，请重试' }
+                    : { code: 'git_error', message: this.errorMessage(error) },
+            };
+        }
+        finally {
+            if (!preserveRecoveryEvidence) {
+                await removeBestEffort(adjacentIndex);
+                await removeBestEffort(indexLockMarker);
+            }
+            if (tempRoot)
+                await this.cleanup(tempRoot);
+        }
+    }
+    async recoverCheckpoint(input) {
+        if (!OID_PATTERN.test(input.commitOid) || !OID_PATTERN.test(input.parentOid) || !OID_PATTERN.test(input.expectedIndexTreeOid)) {
+            return { status: 'error', error: { code: 'invalid_input', message: 'Checkpoint 恢复 OID 无效' } };
+        }
+        let tempRoot = null;
+        let ownedIndexLock = null;
+        let ownedLockMarker = null;
+        try {
+            tempRoot = await mkdtemp(join(tmpdir(), 'dsh-checkpoint-recovery-'));
+            const isolatedGitRoot = await resolveGitRoot(input.isolatedPath);
+            const realIndexPath = await resolveIndexPath(isolatedGitRoot);
+            const indexLockPath = `${realIndexPath}.lock`;
+            const indexLockMarker = `${indexLockPath}.dsh-${input.commitOid}`;
+            const targetTreeOid = stdoutText(await runGit(isolatedGitRoot, ['rev-parse', `${input.commitOid}^{tree}`]));
+            const existingLock = await inspectIndexFileTree(isolatedGitRoot, indexLockPath);
+            const markerOwned = await checkpointLockMarkerOwned(indexLockMarker, input.commitOid);
+            const snapshot = await captureSnapshot(isolatedGitRoot, join(tempRoot, 'current.index'), null, null);
+            if (snapshot.headRef !== null) {
+                return { status: 'error', error: { code: 'stale_isolated', message: 'Worktree 已不再是 detached HEAD' } };
+            }
+            if (snapshot.headOid === input.parentOid) {
+                if (existingLock.exists) {
+                    if (!markerOwned || (existingLock.treeOid !== null && existingLock.treeOid !== targetTreeOid)) {
+                        return { status: 'error', error: { code: 'stale_isolated', message: '遗留 index.lock 无法证明属于当前 Checkpoint，已保留现场' } };
+                    }
+                    await unlink(indexLockPath);
+                }
+                if (markerOwned)
+                    await unlink(indexLockMarker);
+                return { status: 'checkpoint_aborted', isolatedFingerprint: snapshot.fingerprint };
+            }
+            if (snapshot.headOid !== input.commitOid) {
+                return { status: 'error', error: { code: 'stale_isolated', message: 'Worktree HEAD 与待恢复 Checkpoint 不一致' } };
+            }
+            if (snapshot.treeOid !== snapshot.headTreeOid) {
+                return { status: 'error', error: { code: 'stale_isolated', message: 'Worktree 在 Checkpoint 中断后出现新修改，不能自动恢复 index' } };
+            }
+            if (snapshot.indexTreeOid !== input.expectedIndexTreeOid && snapshot.indexTreeOid !== snapshot.headTreeOid) {
+                return { status: 'error', error: { code: 'stale_isolated', message: 'Checkpoint 中断后 index 出现新 staged 修改，不能自动覆盖' } };
+            }
+            const cleanIndexPath = join(tempRoot, 'clean.index');
+            await prepareIndexFromPatch(isolatedGitRoot, cleanIndexPath, input.commitOid, Buffer.alloc(0));
+            if (existingLock.exists) {
+                if (!markerOwned || (existingLock.treeOid !== null && existingLock.treeOid !== targetTreeOid)) {
+                    return { status: 'error', error: { code: 'stale_isolated', message: '遗留 index.lock 与 Checkpoint 目标不一致，已保留现场' } };
+                }
+                if (existingLock.treeOid === null)
+                    await copyFile(cleanIndexPath, indexLockPath);
+            }
+            else {
+                if (!markerOwned) {
+                    await writeFile(indexLockMarker, `${input.commitOid}\n`, { flag: 'wx' });
+                    ownedLockMarker = indexLockMarker;
+                }
+                const indexLock = await open(indexLockPath, 'wx');
+                ownedIndexLock = indexLockPath;
+                await indexLock.close();
+                await copyFile(cleanIndexPath, indexLockPath);
+            }
+            await this.options.beforeFinalIsolatedValidation?.();
+            const lockedSnapshot = await captureSnapshot(isolatedGitRoot, join(tempRoot, 'locked-current.index'), null, null);
+            if (lockedSnapshot.headOid !== snapshot.headOid
+                || lockedSnapshot.fingerprint !== snapshot.fingerprint
+                || (lockedSnapshot.indexTreeOid !== input.expectedIndexTreeOid && lockedSnapshot.indexTreeOid !== lockedSnapshot.headTreeOid)) {
+                return { status: 'error', error: { code: 'stale_isolated', message: 'Checkpoint 恢复加锁前 Worktree 或 index 已变化' } };
+            }
+            await rename(indexLockPath, realIndexPath);
+            ownedIndexLock = null;
+            await removeBestEffort(indexLockMarker);
+            ownedLockMarker = null;
+            const completed = await captureSnapshot(isolatedGitRoot, join(tempRoot, 'completed.index'), null, null);
+            if (completed.headOid !== input.commitOid
+                || completed.headRef !== null
+                || completed.indexTreeOid !== completed.headTreeOid
+                || completed.treeOid !== completed.headTreeOid) {
+                return { status: 'error', error: { code: 'git_error', message: 'Checkpoint index 恢复后仍未收敛到 clean 状态', recoveryState: 'uncertain' } };
+            }
+            return { status: 'checkpoint_recovered', isolatedFingerprint: completed.fingerprint };
+        }
+        catch (error) {
+            return { status: 'error', error: { code: 'git_error', message: this.errorMessage(error), recoveryState: 'uncertain' } };
+        }
+        finally {
+            await removeBestEffort(ownedIndexLock);
+            await removeBestEffort(ownedLockMarker);
+            if (tempRoot)
+                await this.cleanup(tempRoot);
+        }
+    }
     async inspectReview(input) {
         if (!OID_PATTERN.test(input.baseOid)) {
             return { status: 'error', error: { code: 'invalid_input', message: 'Session Base OID 格式无效' } };
@@ -634,6 +1014,36 @@ class DefaultSessionCheckoutApplyEngine {
                 await this.cleanup(tempRoot);
         }
     }
+    async assessPreviewRecovery(input) {
+        let tempRoot = null;
+        try {
+            tempRoot = await mkdtemp(join(tmpdir(), 'domi-preview-recovery-preflight-'));
+            const localGitRoot = await resolveGitRoot(input.localPath);
+            const objectDirectory = join(tempRoot, 'objects');
+            await mkdir(objectDirectory, { recursive: true });
+            const sourceObjects = await sourceObjectDirectory(localGitRoot);
+            const current = await captureSnapshot(localGitRoot, join(tempRoot, 'current.index'), objectDirectory, sourceObjects);
+            const rollback = await prepareRollbackAssessment(tempRoot, sourceObjects, objectDirectory, localGitRoot, current, input.receipt);
+            const finalize = await prepareFinalizeAssessment(tempRoot, sourceObjects, objectDirectory, localGitRoot, current, input.receipt);
+            return {
+                localFingerprint: current.fingerprint,
+                localHeadOid: current.headOid,
+                localHeadRef: current.headRef,
+                localHeadTreeOid: current.headTreeOid,
+                localIndexTreeOid: current.indexTreeOid,
+                localWorkingTreeOid: current.treeOid,
+                rollback,
+                finalize,
+            };
+        }
+        catch (error) {
+            return { status: 'error', error: { code: 'git_error', message: this.errorMessage(error) } };
+        }
+        finally {
+            if (tempRoot)
+                await this.cleanup(tempRoot);
+        }
+    }
     async rollback(input) {
         let tempRoot = null;
         try {
@@ -643,86 +1053,52 @@ class DefaultSessionCheckoutApplyEngine {
             await mkdir(objectDirectory, { recursive: true });
             const sourceObjects = await sourceObjectDirectory(localGitRoot);
             const current = await captureSnapshot(localGitRoot, join(tempRoot, 'current.index'), objectDirectory, sourceObjects);
-            if (current.headRef !== input.receipt.localHeadRef) {
-                return { status: 'error', error: { code: 'stale_local', message: 'Local branch 已变化，不能自动撤回 Preview' } };
-            }
-            if (current.headOid !== input.receipt.localHeadOid
-                && !await isAncestor(localGitRoot, input.receipt.localHeadOid, current.headOid)) {
-                return { status: 'error', error: { code: 'stale_local', message: 'Local HEAD 不是 Preview 基线的安全快进，不能自动撤回' } };
-            }
-            let rollbackBaselineTreeOid = input.receipt.localWorkingTreeOid;
-            let expectedPreviewTreeOid = input.receipt.previewWorkingTreeOid;
-            if (current.headOid !== input.receipt.localHeadOid) {
-                const receiptHeadTreeOid = stdoutText(await runGit(localGitRoot, ['rev-parse', `${input.receipt.localHeadOid}^{tree}`]));
-                const advancedBaseline = await computeTreeMerge(tempRoot, sourceObjects, objectDirectory, localGitRoot, 'preview-rollback-advanced-baseline', receiptHeadTreeOid, current.headTreeOid, input.receipt.localWorkingTreeOid);
-                if (advancedBaseline.status === 'conflict') {
-                    return {
-                        status: 'error',
-                        error: {
-                            code: 'preview_modified',
-                            message: `Local 新提交与 Preview 前的本地修改冲突，无法安全撤回：${advancedBaseline.conflictingFiles.join('、')}`,
-                        },
-                    };
-                }
-                const previewAbsence = await computeTreeMerge(tempRoot, sourceObjects, objectDirectory, localGitRoot, 'preview-rollback-preview-absence', input.receipt.previewWorkingTreeOid, advancedBaseline.treeOid, input.receipt.localWorkingTreeOid);
-                if (previewAbsence.status === 'conflict') {
-                    return {
-                        status: 'error',
-                        error: {
-                            code: 'preview_modified',
-                            message: `Local 新提交与 Preview 任务增量冲突，无法安全撤回：${previewAbsence.conflictingFiles.join('、')}`,
-                        },
-                    };
-                }
-                if (previewAbsence.treeOid !== advancedBaseline.treeOid) {
-                    return {
-                        status: 'error',
-                        error: {
-                            code: 'preview_modified',
-                            message: 'Local 新提交已经包含部分或全部 Preview 增量，不能通过撤回工作区改动来改写已提交历史',
-                        },
-                    };
-                }
-                const advancedPreview = await computeTreeMerge(tempRoot, sourceObjects, objectDirectory, localGitRoot, 'preview-rollback-advanced-preview', input.receipt.localWorkingTreeOid, advancedBaseline.treeOid, input.receipt.previewWorkingTreeOid);
-                if (advancedPreview.status === 'conflict') {
-                    return {
-                        status: 'error',
-                        error: {
-                            code: 'preview_modified',
-                            message: `Local 新提交与 Preview 任务增量冲突，无法安全撤回：${advancedPreview.conflictingFiles.join('、')}`,
-                        },
-                    };
-                }
-                rollbackBaselineTreeOid = advancedBaseline.treeOid;
-                expectedPreviewTreeOid = advancedPreview.treeOid;
+            const assessment = await prepareRollbackAssessment(tempRoot, sourceObjects, objectDirectory, localGitRoot, current, input.receipt);
+            if (assessment.status === 'blocked') {
+                return { status: 'error', error: { code: assessment.code, message: assessment.message } };
             }
-            const rollbackTree = await computeTreeMerge(tempRoot, sourceObjects, objectDirectory, localGitRoot, 'preview-rollback', expectedPreviewTreeOid, current.treeOid, rollbackBaselineTreeOid);
-            if (rollbackTree.status === 'conflict') {
-                return {
-                    status: 'error',
-                    error: {
-                        code: 'preview_modified',
-                        message: `Local 在 Preview 区域出现额外修改，无法安全撤回：${rollbackTree.conflictingFiles.join('、')}`,
-                    },
-                };
-            }
-            const rollbackPatch = await treePatch(localGitRoot, current.treeOid, rollbackTree.treeOid, objectDirectory, sourceObjects);
+            const rollbackPatch = await treePatch(localGitRoot, current.treeOid, assessment.targetTreeOid, objectDirectory, sourceObjects);
+            // Journal persistence may await registry I/O, so it must happen before the authoritative
+            // final Local CAS. From the snapshot below to git apply there is no callback/yield seam.
+            await input.beforeWrite?.();
             await this.options.beforeFinalLocalValidation?.();
             const finalLocal = await captureSnapshot(localGitRoot, join(tempRoot, 'final-local.index'), objectDirectory, sourceObjects);
-            if (finalLocal.fingerprint !== current.fingerprint || finalLocal.headOid !== current.headOid) {
+            if (finalLocal.fingerprint !== current.fingerprint
+                || finalLocal.headOid !== current.headOid
+                || finalLocal.headRef !== current.headRef) {
                 return { status: 'error', error: { code: 'stale_local', message: 'Local 在撤回 Preview 前发生变化，请重试' } };
             }
             if (rollbackPatch.length > 0) {
                 await runGit(localGitRoot, ['apply', '--binary', '--whitespace=nowarn'], { input: rollbackPatch });
             }
-            const rolledBack = await captureSnapshot(localGitRoot, join(tempRoot, 'rolled-back.index'), null, null);
+            let rolledBack;
+            try {
+                await this.options.afterLocalWriteBeforeVerification?.();
+                rolledBack = await captureSnapshot(localGitRoot, join(tempRoot, 'rolled-back.index'), null, null);
+            }
+            catch (error) {
+                return {
+                    status: 'error',
+                    error: {
+                        code: 'git_error',
+                        message: `Preview 撤回写后无法完成验证，需要保留现场确认：${this.errorMessage(error)}`,
+                        recoveryState: 'uncertain',
+                    },
+                };
+            }
+            const expectedFingerprint = snapshotFingerprint(current.headOid, current.headRef, current.indexEntries, assessment.targetTreeOid);
             if (rolledBack.headOid !== current.headOid
                 || rolledBack.headRef !== current.headRef
                 || rolledBack.indexTreeOid !== current.indexTreeOid
-                || rolledBack.treeOid !== rollbackTree.treeOid) {
+                || rolledBack.treeOid !== assessment.targetTreeOid
+                || rolledBack.fingerprint !== expectedFingerprint) {
                 return {
                     status: 'error',
-                    error: { code: 'git_error', message: 'Preview 撤回后的 Local snapshot 与安全恢复结果不一致，需要保留现场确认' },
+                    error: {
+                        code: 'git_error',
+                        message: 'Preview 撤回后的 Local snapshot 与安全恢复结果不一致，需要保留现场确认',
+                        recoveryState: 'uncertain',
+                    },
                 };
             }
             return { status: 'preview_rolled_back', changedFiles: [...input.receipt.changedFiles] };
@@ -740,11 +1116,10 @@ class DefaultSessionCheckoutApplyEngine {
         if (!commitMessage) {
             return { status: 'error', error: { code: 'invalid_input', message: '提交信息不能为空' } };
         }
-        if (!input.receipt.localHeadRef?.startsWith('refs/heads/')) {
-            return { status: 'error', error: { code: 'operation_not_allowed', message: 'Local 当前不是普通分支，不能自动创建任务提交' } };
-        }
         let tempRoot = null;
-        let adjacentIndex = null;
+        let ownedIndexLock = null;
+        let backupIndex = null;
+        let preserveBackup = false;
         try {
             tempRoot = await mkdtemp(join(tmpdir(), 'domi-preview-finalize-'));
             const localGitRoot = await resolveGitRoot(input.localPath);
@@ -752,23 +1127,18 @@ class DefaultSessionCheckoutApplyEngine {
             await mkdir(objectDirectory, { recursive: true });
             const sourceObjects = await sourceObjectDirectory(localGitRoot);
             const current = await captureSnapshot(localGitRoot, join(tempRoot, 'current.index'), objectDirectory, sourceObjects);
-            if (current.headOid !== input.receipt.localHeadOid || current.headRef !== input.receipt.localHeadRef) {
-                return { status: 'error', error: { code: 'stale_local', message: 'Local branch/HEAD 已变化，不能完成 Preview 提交' } };
-            }
-            const previewRemoval = await computeTreeMerge(tempRoot, sourceObjects, objectDirectory, localGitRoot, 'preview-finalize-separation', input.receipt.previewWorkingTreeOid, current.treeOid, input.receipt.localWorkingTreeOid);
-            if (previewRemoval.status === 'conflict') {
-                return {
-                    status: 'error',
-                    error: {
-                        code: 'preview_modified',
-                        message: `Local 在 Preview 区域出现额外修改，无法可靠提交：${previewRemoval.conflictingFiles.join('、')}`,
-                    },
-                };
+            const realIndexPath = await resolveIndexPath(localGitRoot);
+            const originalIndexBytes = await readFile(realIndexPath);
+            const assessment = await prepareFinalizeAssessment(tempRoot, sourceObjects, objectDirectory, localGitRoot, current, input.receipt);
+            if (assessment.status === 'blocked') {
+                return { status: 'error', error: { code: assessment.code, message: assessment.message } };
             }
-            if (input.receipt.changedFiles.length === 0) {
+            if (!assessment.commitRequired) {
                 await this.options.beforeFinalLocalValidation?.();
                 const finalLocal = await captureSnapshot(localGitRoot, join(tempRoot, 'final-empty.index'), objectDirectory, sourceObjects);
-                if (finalLocal.fingerprint !== current.fingerprint) {
+                if (finalLocal.headOid !== current.headOid
+                    || finalLocal.headRef !== current.headRef
+                    || finalLocal.fingerprint !== current.fingerprint) {
                     return { status: 'error', error: { code: 'stale_local', message: 'Local 在完成 Preview 前发生变化，请重试' } };
                 }
                 return {
@@ -778,77 +1148,172 @@ class DefaultSessionCheckoutApplyEngine {
                     nextBaseOid: input.receipt.isolatedSnapshotOid,
                 };
             }
-            const taskTree = await computeTreeMerge(tempRoot, sourceObjects, objectDirectory, localGitRoot, 'preview-task-isolation', input.receipt.localWorkingTreeOid, current.headTreeOid, input.receipt.previewWorkingTreeOid);
-            if (taskTree.status === 'conflict') {
-                return {
-                    status: 'error',
-                    error: {
-                        code: 'commit_isolation_conflict',
-                        message: `Preview 任务增量无法与 Local HEAD 可靠拆分：${taskTree.conflictingFiles.join('、')}`,
-                    },
-                };
-            }
-            const finalIndexTree = await computeTreeMerge(tempRoot, sourceObjects, objectDirectory, localGitRoot, 'preview-index-preservation', current.headTreeOid, taskTree.treeOid, current.indexTreeOid);
-            if (finalIndexTree.status === 'conflict') {
-                return {
-                    status: 'error',
-                    error: {
-                        code: 'commit_isolation_conflict',
-                        message: `Preview 提交与 Local staged 修改无法可靠分离：${finalIndexTree.conflictingFiles.join('、')}`,
-                    },
-                };
-            }
-            const taskPatch = await treePatch(localGitRoot, current.headTreeOid, taskTree.treeOid, objectDirectory, sourceObjects);
-            const finalIndexPatch = await treePatch(localGitRoot, taskTree.treeOid, finalIndexTree.treeOid, objectDirectory, sourceObjects);
+            const taskPatch = await treePatch(localGitRoot, current.headTreeOid, assessment.taskTreeOid, objectDirectory, sourceObjects);
+            const finalIndexPatch = await treePatch(localGitRoot, assessment.taskTreeOid, assessment.finalIndexTreeOid, objectDirectory, sourceObjects);
             const actualTaskTreeOid = await prepareIndexFromPatch(localGitRoot, join(tempRoot, 'task.index'), current.headOid, taskPatch);
+            if (actualTaskTreeOid !== assessment.taskTreeOid) {
+                return { status: 'error', error: { code: 'git_error', message: 'Preview 任务提交 tree 与恢复评估不一致' } };
+            }
             const commitOid = await createUserCommit(localGitRoot, actualTaskTreeOid, current.headOid, commitMessage);
             const finalIndexPath = join(tempRoot, 'final.index');
-            await prepareIndexFromPatch(localGitRoot, finalIndexPath, commitOid, finalIndexPatch);
+            const actualFinalIndexTreeOid = await prepareIndexFromPatch(localGitRoot, finalIndexPath, commitOid, finalIndexPatch);
+            if (actualFinalIndexTreeOid !== assessment.finalIndexTreeOid) {
+                return { status: 'error', error: { code: 'git_error', message: 'Preview 最终 index tree 与恢复评估不一致' } };
+            }
+            const expectedIndexEntries = (await runGit(localGitRoot, ['ls-files', '--stage', '-z'], { env: { GIT_INDEX_FILE: finalIndexPath } })).stdout;
+            const intendedIndexBytes = await readFile(finalIndexPath);
+            const expectedFingerprint = snapshotFingerprint(commitOid, current.headRef, expectedIndexEntries, assessment.expectedWorkingTreeOid);
             await input.beforeCommit?.(commitOid);
+            const branchRef = current.headRef;
+            if (!branchRef?.startsWith('refs/heads/')) {
+                return { status: 'error', error: { code: 'operation_not_allowed', message: 'Local 当前不是普通分支，不能自动创建任务提交' } };
+            }
+            backupIndex = `${realIndexPath}.domi-backup-${randomUUID()}`;
+            await copyFile(realIndexPath, backupIndex);
             await this.options.beforeFinalLocalValidation?.();
+            try {
+                // Use Git's canonical index.lock protocol. While this lock exists, concurrent git add/reset
+                // cannot mutate the real index between the authoritative snapshot and our atomic replacement.
+                ownedIndexLock = await writeIndexLock(realIndexPath, intendedIndexBytes);
+            }
+            catch (error) {
+                if (isIndexLockContention(error)) {
+                    return { status: 'error', error: { code: 'stale_local', message: 'Local index 正在被其他 Git 操作更新，请重试' } };
+                }
+                throw error;
+            }
             const finalLocal = await captureSnapshot(localGitRoot, join(tempRoot, 'final-local.index'), objectDirectory, sourceObjects);
-            if (finalLocal.fingerprint !== current.fingerprint || finalLocal.headOid !== current.headOid) {
+            const finalIndexBytes = await readFile(realIndexPath);
+            if (finalLocal.headOid !== current.headOid
+                || finalLocal.headRef !== current.headRef
+                || finalLocal.fingerprint !== current.fingerprint
+                || !finalIndexBytes.equals(originalIndexBytes)) {
                 return { status: 'error', error: { code: 'stale_local', message: 'Local 在 Preview 提交写入前发生变化，请重试' } };
             }
-            const realIndexPath = await resolveIndexPath(localGitRoot);
-            adjacentIndex = `${realIndexPath}.domi-${randomUUID()}`;
-            await copyFile(finalIndexPath, adjacentIndex);
             let refUpdated = false;
+            let indexReplaced = false;
+            let writeError = null;
             try {
-                await runGit(localGitRoot, ['update-ref', input.receipt.localHeadRef, commitOid, current.headOid]);
+                await runGit(localGitRoot, ['update-ref', branchRef, commitOid, current.headOid]);
                 refUpdated = true;
-                await rename(adjacentIndex, realIndexPath);
-                adjacentIndex = null;
+                await rename(ownedIndexLock, realIndexPath);
+                ownedIndexLock = null;
+                indexReplaced = true;
             }
             catch (error) {
-                if (refUpdated) {
-                    try {
-                        await runGit(localGitRoot, ['update-ref', input.receipt.localHeadRef, current.headOid, commitOid]);
-                    }
-                    catch (rollbackError) {
+                writeError = error;
+            }
+            if (!writeError) {
+                try {
+                    await this.options.afterLocalWriteBeforeVerification?.();
+                    const committed = await captureSnapshot(localGitRoot, join(tempRoot, 'committed.index'), null, null);
+                    const committedIndexBytes = await readFile(realIndexPath);
+                    if (committed.headOid === commitOid
+                        && committed.headRef === branchRef
+                        && committed.indexTreeOid === assessment.finalIndexTreeOid
+                        && committed.treeOid === assessment.expectedWorkingTreeOid
+                        && committed.fingerprint === expectedFingerprint
+                        && committedIndexBytes.equals(intendedIndexBytes)) {
+                        await removeBestEffort(backupIndex);
+                        backupIndex = null;
                         return {
-                            status: 'error',
-                            error: {
-                                code: 'git_error',
-                                message: `Preview 提交写入失败且 ref 无法回滚：${this.errorMessage(error)}；${this.errorMessage(rollbackError)}`,
-                            },
+                            status: 'finished',
+                            changedFiles: [...input.receipt.changedFiles],
+                            commitOid,
+                            nextBaseOid: input.receipt.isolatedSnapshotOid,
                         };
                     }
+                    writeError = new Error('Preview 提交写后验证失败');
+                }
+                catch (error) {
+                    writeError = error;
+                }
+            }
+            const rollbackErrors = [];
+            if (refUpdated && !indexReplaced && ownedIndexLock) {
+                // The ref moved but the index replacement did not. We still own index.lock, so no Git
+                // index writer can race the ref CAS rollback; the real index is already the original one.
+                try {
+                    await runGit(localGitRoot, ['update-ref', branchRef, current.headOid, commitOid]);
+                    refUpdated = false;
+                    await removeBestEffort(ownedIndexLock);
+                    ownedIndexLock = null;
+                }
+                catch (error) {
+                    rollbackErrors.push(`ref: ${this.errorMessage(error)}`);
+                }
+            }
+            else if (refUpdated && indexReplaced && backupIndex) {
+                // Compensation is itself a CAS transaction. Never restore the old backup over an index
+                // that changed after Domi's write; preserve both the user's index and our backup instead.
+                try {
+                    const backupBytes = await readFile(backupIndex);
+                    ownedIndexLock = await writeIndexLock(realIndexPath, backupBytes);
+                    const currentIndexBytes = await readFile(realIndexPath);
+                    if (!currentIndexBytes.equals(intendedIndexBytes)) {
+                        rollbackErrors.push('index: Local index 在 Preview 写入后发生变化，拒绝覆盖并发 staged 状态');
+                    }
+                    else {
+                        await runGit(localGitRoot, ['update-ref', branchRef, current.headOid, commitOid]);
+                        refUpdated = false;
+                        await rename(ownedIndexLock, realIndexPath);
+                        ownedIndexLock = null;
+                        indexReplaced = false;
+                    }
                 }
-                return { status: 'error', error: { code: 'git_error', message: `Preview 提交写入失败，已回滚：${this.errorMessage(error)}` } };
+                catch (error) {
+                    rollbackErrors.push(`compensation: ${this.errorMessage(error)}`);
+                }
+            }
+            else if (refUpdated) {
+                rollbackErrors.push('ref: 缺少可验证的 index 补偿证据，拒绝部分回滚');
+            }
+            let restored = false;
+            if (rollbackErrors.length === 0) {
+                try {
+                    const restoredLocal = await captureSnapshot(localGitRoot, join(tempRoot, 'restored.index'), null, null);
+                    const restoredIndexBytes = await readFile(realIndexPath);
+                    restored = restoredLocal.headOid === current.headOid
+                        && restoredLocal.headRef === current.headRef
+                        && restoredLocal.indexTreeOid === current.indexTreeOid
+                        && restoredLocal.treeOid === current.treeOid
+                        && restoredLocal.fingerprint === current.fingerprint
+                        && restoredIndexBytes.equals(originalIndexBytes);
+                }
+                catch (error) {
+                    rollbackErrors.push(`verification: ${this.errorMessage(error)}`);
+                }
+            }
+            if (restored) {
+                await removeBestEffort(backupIndex);
+                backupIndex = null;
+                return {
+                    status: 'error',
+                    error: {
+                        code: 'git_error',
+                        message: `Preview 提交写入未能验证，已完整回滚：${this.errorMessage(writeError)}`,
+                        recoveryState: 'unchanged',
+                    },
+                };
             }
+            preserveBackup = true;
+            const rollbackDetail = rollbackErrors.length > 0 ? `；${rollbackErrors.join('；')}` : '';
             return {
-                status: 'finished',
-                changedFiles: [...input.receipt.changedFiles],
-                commitOid,
-                nextBaseOid: input.receipt.isolatedSnapshotOid,
+                status: 'error',
+                error: {
+                    code: 'git_error',
+                    message: `Preview 提交写入后无法证明成功或完整回滚，需要保留现场确认：${this.errorMessage(writeError)}${rollbackDetail}`,
+                    recoveryState: 'uncertain',
+                },
             };
         }
         catch (error) {
             return { status: 'error', error: { code: 'git_error', message: this.errorMessage(error) } };
         }
         finally {
-            await removeBestEffort(adjacentIndex);
+            await removeBestEffort(ownedIndexLock);
+            if (!preserveBackup)
+                await removeBestEffort(backupIndex);
             if (tempRoot)
                 await this.cleanup(tempRoot);
         }