dsh-git-worktree 0.4.0 → 0.7.1

package/lib/session-checkout-module.js

@@ -1,6 +1,8 @@
+import { createHash } from 'node:crypto';
 import { realpathSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { SessionCheckoutError } from './index.js';
+import { checkpointGenerationForRecord } from './checkpoint.js';
 import { createManagedWorktreePathCandidates, createManagedWorktreeRepositoryKey, } from './managed-worktree-path.js';
 const UNVERSIONED_OID = 'unversioned';
 const UNVERSIONED_REF = 'WORKING_TREE';
@@ -140,6 +142,26 @@ export function createSessionCheckoutModule(dependencies) {
             revision: binding.revision,
         };
     }
+    function projectPreviousReview(review) {
+        return {
+            reviewId: review.reviewId,
+            iteration: review.iteration,
+            summary: review.summary,
+            suggestedCommitMessage: review.suggestedCommitMessage,
+            changedFiles: review.changedFiles.slice(0, 50),
+        };
+    }
+    function projectCheckpoint(checkpoint) {
+        return {
+            checkpointId: checkpoint.checkpointId,
+            sequence: checkpoint.sequence,
+            reviewId: checkpoint.reviewId,
+            createdAt: checkpoint.createdAt,
+            summary: checkpoint.summary,
+            validationStatus: checkpoint.validationStatus,
+            changedFiles: [...checkpoint.changedFiles],
+        };
+    }
     function projectDelivery(record, commitInLocalHistory = null) {
         const delivery = record.delivery;
         const projectProof = (proof) => proof
@@ -236,6 +258,8 @@ export function createSessionCheckoutModule(dependencies) {
             dirty,
             revision: record?.revision ?? binding.revision,
             ...(record ? { delivery: projectDelivery(record) } : {}),
+            ...((record?.checkpoints?.length ?? 0) > 0 ? { checkpoints: record.checkpoints.map(projectCheckpoint) } : {}),
+            ...(record && checkpointGenerationForRecord(record) ? { checkpointGeneration: checkpointGenerationForRecord(record) } : {}),
         };
     }
     async function validateCommittedLocalCheckout(binding, record) {
@@ -322,6 +346,29 @@ export function createSessionCheckoutModule(dependencies) {
         dependencies.registry.write(registry);
         return recovered;
     }
+    async function checkpointHeadInvariantHolds(record, managedRoot, headOid) {
+        const checkpoints = record.checkpoints ?? [];
+        if (checkpoints.length === 0)
+            return true;
+        const checkpointIds = new Set();
+        const reviewIds = new Set();
+        for (let index = 0; index < checkpoints.length; index += 1) {
+            const checkpoint = checkpoints[index];
+            if (checkpoint.sequence !== index + 1
+                || checkpointIds.has(checkpoint.checkpointId)
+                || reviewIds.has(checkpoint.reviewId))
+                return false;
+            checkpointIds.add(checkpoint.checkpointId);
+            reviewIds.add(checkpoint.reviewId);
+            if (await dependencies.git.readInternalArtifact(record.localRoot, record.checkoutId, `checkpoints/${checkpoint.checkpointId}`) !== checkpoint.commitOid)
+                return false;
+            if (!(await dependencies.git.isAncestor(managedRoot, checkpoint.parentOid, checkpoint.commitOid)))
+                return false;
+            if (index > 0 && !(await dependencies.git.isAncestor(managedRoot, checkpoints[index - 1].commitOid, checkpoint.parentOid)))
+                return false;
+        }
+        return dependencies.git.isAncestor(managedRoot, checkpoints[checkpoints.length - 1].commitOid, headOid);
+    }
     async function validateManagedCheckoutDetailed(binding, record, requireCreateBase) {
         if (binding.target.kind !== 'isolated'
             || binding.target.checkoutId !== record.checkoutId
@@ -356,7 +403,8 @@ export function createSessionCheckoutModule(dependencies) {
                 || !pathsEqual(localSnapshot.commonDir, record.gitCommonDir)
                 || !pathsEqual(resolve(snapshot.root, projectRelativePath), canonicalManagedRoot)
                 || (!requireCreateBase && !pathsEqual(snapshot.gitDir, record.gitDir))
-                || (requireCreateBase && snapshot.headOid !== record.baseOid))
+                || (requireCreateBase && snapshot.headOid !== record.baseOid)
+                || (!requireCreateBase && !(await checkpointHeadInvariantHolds(record, canonicalManagedRoot, snapshot.headOid))))
                 return { status: 'invalid' };
             const status = await dependencies.git.status(canonicalManagedRoot);
             return {
@@ -582,6 +630,8 @@ export function createSessionCheckoutModule(dependencies) {
             dirty: status.dirty,
             revision: record.revision,
             delivery,
+            ...((record.checkpoints?.length ?? 0) > 0 ? { checkpoints: record.checkpoints.map(projectCheckpoint) } : {}),
+            ...(checkpointGenerationForRecord(record) ? { checkpointGeneration: checkpointGenerationForRecord(record) } : {}),
             ...(delivery?.state === 'ready_for_review'
                 ? {
                     reviewSlot: activePreview ? 'waiting' : 'available',
@@ -615,7 +665,11 @@ export function createSessionCheckoutModule(dependencies) {
                 || record.phase === 'recovery_required')
                 .sort((left, right) => managedUpdatedAt(right) - managedUpdatedAt(left))[0];
             if (!pending) {
-                return 'Session Target: Local Checkout. No isolated target is active for this Session.';
+                return [
+                    'Session Target: Local Checkout. No isolated target is active for this Session.',
+                    'Complete ordinary Local work in the current cwd and finish with an ordinary assistant reply.',
+                    'Do not call Worktree-only tools such as worktree_ready_for_review, worktree_resume_revision, or worktree_begin_next_iteration unless this Session first selects an Isolated Checkout.',
+                ].join('\n');
             }
             if (pending.delivery.state === 'preview_active') {
                 return [
@@ -651,6 +705,9 @@ export function createSessionCheckoutModule(dependencies) {
             `Original Local boundary: ${record.localRoot}`,
             'Make task changes only in the authoritative cwd; never write directly to the Original Local boundary.',
         ];
+        if ((record.checkpoints?.length ?? 0) > 0) {
+            lines.push(`Saved Worktree checkpoints: ${record.checkpoints.length}. They remain unpublished to Local.`, 'Final review and commit wording must summarize the cumulative diff from the original delivery base to the final Worktree snapshot. Do not manually reset, rewrite, or publish checkpoint commits.');
+        }
         if (record.delivery.state === 'ready_for_review') {
             lines.push('Delivery state: Ready for Review, not yet synchronized to Local. Continue ordinary discussion and answer questions without changing this Review. If the user requests new code or file changes, call worktree_resume_revision first, then continue the requested work in this same Session; do not ask the user to click a recovery control and do not synchronize Local. Until that tool succeeds, treat the Worktree as read-only. The user may still preview, directly finish, or discard through the Worktree acceptance UI.');
         }
@@ -846,78 +903,96 @@ export function createSessionCheckoutModule(dependencies) {
             }
             if (current.phase === 'mutating'
                 && (current.journal?.operation === 'finalize_preview' || current.journal?.operation === 'finish')
-                && current.journal.step === 'updating_ref'
-                && typeof current.journal.commitOid === 'string'
-                && current.delivery.state === 'preview_active') {
-                const local = await dependencies.git.inspect(current.localRoot);
-                if (local?.headOid === current.journal.commitOid) {
-                    const retention = current.journal.retention ?? 'cleanup';
-                    const recoveredAt = Date.now();
-                    record = retention === 'cleanup'
-                        ? {
-                            ...current,
-                            phase: 'finalized',
-                            delivery: {
-                                state: 'finalized',
-                                review: current.delivery.review,
-                                commitOid: current.journal.commitOid,
-                                proof: {
-                                    localBranch: current.delivery.preview.localHeadRef?.startsWith('refs/heads/')
-                                        ? current.delivery.preview.localHeadRef.slice('refs/heads/'.length)
-                                        : null,
-                                    localHeadBefore: current.delivery.preview.localHeadOid,
-                                    localHeadAfter: current.journal.commitOid,
-                                    changedFiles: [...current.delivery.preview.changedFiles],
-                                    validationStatus: current.delivery.review.validationStatus,
-                                    ...(current.delivery.review.validationSummary === undefined
-                                        ? {}
-                                        : { validationSummary: current.delivery.review.validationSummary }),
-                                },
-                                isolatedFingerprint: current.delivery.preview.isolatedFingerprint,
-                                finalizedAt: recoveredAt,
-                                cleanup: 'blocked',
-                                cleanupMessage: 'Commit 已创建，但进程在 Local index 完成前中断；请确认 Local 状态后再处理 Worktree。',
-                            },
-                            journal: null,
-                            revision: current.revision + 1,
+                && (current.journal.step === 'updating_ref' || current.journal.step === 'replacing_index')) {
+                // HEAD/ref alone cannot prove that the adjacent index replacement and working-tree preservation completed.
+                // Preserve delivery, receipt, retained artifacts and journal until an explicit recovery path can verify all facts.
+                record = {
+                    ...current,
+                    phase: 'recovery_required',
+                    revision: current.revision + 1,
+                };
+                registry.managedCheckouts[checkoutId] = record;
+                registry.revision += 1;
+                recoveryRequiredCheckoutIds.push(checkoutId);
+                changed = true;
+            }
+            else if ((current.phase === 'mutating' || current.phase === 'recovery_required')
+                && current.journal?.operation === 'checkpoint'
+                && current.delivery.state === 'ready_for_review') {
+                const journal = current.journal;
+                if (journal.step === 'planning') {
+                    record = { ...current, phase: 'ready', journal: null, revision: current.revision + 1 };
+                }
+                else if (journal.step === 'updating_ref'
+                    && typeof journal.commitOid === 'string'
+                    && typeof journal.parentOid === 'string'
+                    && typeof journal.checkpointId === 'string'
+                    && typeof journal.checkpointSequence === 'number'
+                    && typeof journal.checkpointRequestId === 'string'
+                    && typeof journal.checkpointRequestedRevision === 'number'
+                    && typeof journal.recoveryGeneration === 'string'
+                    && typeof journal.checkpointMessage === 'string'
+                    && typeof journal.checkpointIndexTreeOid === 'string'
+                    && Array.isArray(journal.changedFiles)) {
+                    const recovered = await dependencies.applyEngine.recoverCheckpoint({
+                        isolatedPath: current.managedRoot,
+                        commitOid: journal.commitOid,
+                        parentOid: journal.parentOid,
+                        expectedIndexTreeOid: journal.checkpointIndexTreeOid,
+                    });
+                    if (recovered.status === 'checkpoint_aborted') {
+                        try {
+                            await dependencies.git.releaseInternalArtifacts(current.localRoot, current.checkoutId, `checkpoints/${journal.checkpointId}`);
+                        }
+                        catch {
+                            console.warn('[session-checkout] 清理未生效 Checkpoint ref 失败，已保守保留不可见引用');
+                        }
+                        record = { ...current, phase: 'ready', journal: null, revision: current.revision + 1 };
+                    }
+                    else if (recovered.status === 'checkpoint_recovered') {
+                        const retained = await dependencies.git.readInternalArtifact(current.localRoot, current.checkoutId, `checkpoints/${journal.checkpointId}`);
+                        if (retained !== journal.commitOid) {
+                            record = { ...current, phase: 'recovery_required', revision: current.revision + 1 };
+                            recoveryRequiredCheckoutIds.push(checkoutId);
+                        }
+                        else {
+                            const review = current.delivery.review;
+                            const checkpoint = {
+                                checkpointId: journal.checkpointId,
+                                sequence: journal.checkpointSequence,
+                                reviewId: review.reviewId,
+                                requestId: journal.checkpointRequestId,
+                                requestedRevision: journal.checkpointRequestedRevision,
+                                generation: journal.recoveryGeneration,
+                                iteration: review.iteration,
+                                createdAt: journal.startedAt,
+                                commitOid: journal.commitOid,
+                                parentOid: journal.parentOid,
+                                summary: review.summary,
+                                commitMessage: journal.checkpointMessage,
+                                validationStatus: review.validationStatus,
+                                changedFiles: [...journal.changedFiles],
+                            };
+                            record = {
+                                ...current,
+                                phase: 'ready',
+                                previousReview: projectPreviousReview(review),
+                                checkpoints: [...(current.checkpoints ?? []), checkpoint],
+                                delivery: { state: 'working', iteration: review.iteration },
+                                recoveryContinuation: undefined,
+                                journal: null,
+                                revision: current.revision + 1,
+                            };
                         }
-                        : {
-                            ...current,
-                            phase: 'retained',
-                            delivery: {
-                                state: 'retained',
-                                review: current.delivery.review,
-                                commitOid: current.journal.commitOid,
-                                proof: {
-                                    localBranch: current.delivery.preview.localHeadRef?.startsWith('refs/heads/')
-                                        ? current.delivery.preview.localHeadRef.slice('refs/heads/'.length)
-                                        : null,
-                                    localHeadBefore: current.delivery.preview.localHeadOid,
-                                    localHeadAfter: current.journal.commitOid,
-                                    changedFiles: [...current.delivery.preview.changedFiles],
-                                    validationStatus: current.delivery.review.validationStatus,
-                                    ...(current.delivery.review.validationSummary === undefined
-                                        ? {}
-                                        : { validationSummary: current.delivery.review.validationSummary }),
-                                },
-                                isolatedFingerprint: current.delivery.preview.isolatedFingerprint,
-                                retention,
-                                retainedAt: recoveredAt,
-                                expiresAt: retentionExpiresAt(retention, recoveredAt),
-                                cleanup: 'blocked',
-                                cleanupMessage: 'Commit 已创建并保留 Worktree，但进程在 Local index 完成前中断；请确认 Local 状态。',
-                            },
-                            journal: null,
-                            revision: current.revision + 1,
-                        };
+                    }
+                    else {
+                        record = { ...current, phase: 'recovery_required', revision: current.revision + 1 };
+                        recoveryRequiredCheckoutIds.push(checkoutId);
+                    }
                 }
                 else {
-                    record = {
-                        ...current,
-                        phase: 'ready',
-                        journal: null,
-                        revision: current.revision + 1,
-                    };
+                    record = { ...current, phase: 'recovery_required', revision: current.revision + 1 };
+                    recoveryRequiredCheckoutIds.push(checkoutId);
                 }
                 registry.managedCheckouts[checkoutId] = record;
                 registry.revision += 1;
@@ -1058,38 +1133,271 @@ export function createSessionCheckoutModule(dependencies) {
             throw new SessionCheckoutError(snapshot.error.code, snapshot.error.message);
         }
         const reviewId = dependencies.createCheckoutId();
-        updateManagedCheckout(record.checkoutId, (current) => ({
-            ...current,
-            delivery: {
-                state: 'ready_for_review',
-                review: {
-                    reviewId,
-                    iteration: current.delivery.state === 'working'
-                        ? current.delivery.iteration
-                        : current.delivery.state === 'delivered'
-                            ? current.delivery.iteration + 1
-                            : current.delivery.review.iteration,
-                    preparedAt: Date.now(),
-                    ...(input.detailsMarkdown?.trim() ? { detailsMarkdown: input.detailsMarkdown.trim() } : {}),
-                    summary,
-                    validationStatus: input.validationStatus,
-                    ...(input.validationSummary?.trim() ? { validationSummary: input.validationSummary.trim() } : {}),
-                    tests: input.tests.map((test) => ({
-                        command: test.command.trim(),
-                        status: test.status,
-                        ...(test.summary?.trim() ? { summary: test.summary.trim() } : {}),
-                    })),
-                    changedFiles: [...snapshot.changedFiles],
-                    suggestedCommitMessage,
-                    isolatedFingerprint: snapshot.isolatedFingerprint,
-                    isolatedHeadOid: snapshot.isolatedHeadOid,
+        updateManagedCheckout(record.checkoutId, (current) => {
+            const { recoveryContinuation: _recovery, ...withoutRecovery } = current;
+            return {
+                ...withoutRecovery,
+                ...(current.delivery.state !== 'working' && current.delivery.state !== 'delivered'
+                    ? { previousReview: projectPreviousReview(current.delivery.review) }
+                    : {}),
+                delivery: {
+                    state: 'ready_for_review',
+                    review: {
+                        reviewId,
+                        iteration: current.delivery.state === 'working'
+                            ? current.delivery.iteration
+                            : current.delivery.state === 'delivered'
+                                ? current.delivery.iteration + 1
+                                : current.delivery.review.iteration,
+                        preparedAt: Date.now(),
+                        ...(input.detailsMarkdown?.trim() ? { detailsMarkdown: input.detailsMarkdown.trim() } : {}),
+                        summary,
+                        validationStatus: input.validationStatus,
+                        ...(input.validationSummary?.trim() ? { validationSummary: input.validationSummary.trim() } : {}),
+                        tests: input.tests.map((test) => ({
+                            command: test.command.trim(),
+                            status: test.status,
+                            ...(test.summary?.trim() ? { summary: test.summary.trim() } : {}),
+                        })),
+                        changedFiles: [...snapshot.changedFiles],
+                        suggestedCommitMessage,
+                        isolatedFingerprint: snapshot.isolatedFingerprint,
+                        isolatedHeadOid: snapshot.isolatedHeadOid,
+                    },
+                },
+                revision: current.revision + 1,
+            };
+        });
+        return inspectIsolated(binding);
+    }
+    async function operateCheckpoint(input, binding) {
+        if (binding.ownerSessionId !== input.sessionId || binding.target.kind !== 'isolated') {
+            return operationError('not_owner', '只有 owner Isolated 会话可以保存阶段');
+        }
+        const commitMessage = input.commitMessage.trim();
+        if (!commitMessage
+            || commitMessage.length > 500
+            || !input.expectedReviewId.trim()
+            || !/^[0-9a-f]{64}$/u.test(input.expectedGeneration)
+            || !input.requestId.trim()
+            || input.requestId.length > 200
+            || /[\0\r\n]/u.test(input.requestId))
+            return operationError('invalid_input', 'Checkpoint 请求或 Commit Message 无效');
+        let record = dependencies.registry.read().managedCheckouts[binding.target.checkoutId];
+        if (!record)
+            return operationError('checkout_missing', 'Isolated Checkout 记录不存在');
+        const previousRequest = record.checkpoints?.find(checkpoint => checkpoint.requestId === input.requestId);
+        if (previousRequest) {
+            const exactReplay = record.delivery.state === 'working'
+                && record.checkpoints?.at(-1)?.checkpointId === previousRequest.checkpointId
+                && previousRequest.reviewId === input.expectedReviewId
+                && previousRequest.requestedRevision === input.expectedRevision
+                && previousRequest.generation === input.expectedGeneration
+                && previousRequest.commitMessage === commitMessage;
+            if (!exactReplay)
+                return operationError('stale_target', 'Checkpoint requestId 已被其他状态使用，请刷新');
+            return {
+                status: 'checkpointed',
+                target: await inspectIsolated(binding),
+                checkpoint: projectCheckpoint(previousRequest),
+                changedFiles: [...previousRequest.changedFiles],
+            };
+        }
+        if (record.revision !== input.expectedRevision) {
+            return operationError('stale_target', 'Session Target 已变化，请刷新后重试', await inspectIsolated(binding));
+        }
+        if (record.phase !== 'ready' || (record.delivery.state !== 'ready_for_review' && record.delivery.state !== 'preview_active')) {
+            return operationError('operation_not_allowed', `当前 ${record.phase}/${record.delivery.state} 状态不能保存阶段`, await inspectIsolated(binding));
+        }
+        if (record.delivery.review.reviewId !== input.expectedReviewId || checkpointGenerationForRecord(record) !== input.expectedGeneration) {
+            return operationError('stale_target', 'Checkpoint Review 或 generation 已变化，请刷新后重试', await inspectIsolated(binding));
+        }
+        const holder = findProjectAcceptanceHolder(record);
+        if (holder) {
+            return operationError('project_acceptance_busy', '另一个任务正在占用该项目的 Local 验收槽位', await inspectIsolated(binding));
+        }
+        const inspected = await inspectIsolated(binding);
+        if (inspected.checkout.phase !== 'ready') {
+            return operationError('recovery_required', 'Isolated Checkout 身份无法确认，需要恢复', inspected);
+        }
+        record = dependencies.registry.read().managedCheckouts[record.checkoutId];
+        if (!record
+            || record.revision !== input.expectedRevision
+            || record.phase !== 'ready'
+            || (record.delivery.state !== 'ready_for_review' && record.delivery.state !== 'preview_active')
+            || record.delivery.review.reviewId !== input.expectedReviewId
+            || checkpointGenerationForRecord(record) !== input.expectedGeneration)
+            return operationError('stale_target', 'Checkpoint 状态在 Host CAS 前发生变化，请刷新后重试');
+        if (record.delivery.state === 'preview_active') {
+            const { preview, review } = record.delivery;
+            const rollbackOperationId = dependencies.createCheckoutId();
+            updateManagedCheckout(record.checkoutId, (current) => ({
+                ...current,
+                phase: 'mutating',
+                journal: {
+                    operation: 'rollback_preview',
+                    operationId: rollbackOperationId,
+                    step: 'planning',
+                    startedAt: Date.now(),
+                    previewId: preview.previewId,
+                    reviewId: review.reviewId,
+                    resumeRevision: false,
+                },
+                revision: current.revision + 1,
+            }));
+            const rollback = await dependencies.applyEngine.rollback({
+                localPath: record.localRoot,
+                receipt: preview,
+                beforeWrite: async () => {
+                    updateManagedCheckout(record.checkoutId, (current) => ({
+                        ...current,
+                        journal: current.journal?.operation === 'rollback_preview'
+                            ? { ...current.journal, step: 'writing_local' }
+                            : current.journal,
+                        revision: current.revision + 1,
+                    }));
                 },
+            });
+            if (rollback.status === 'error') {
+                const current = dependencies.registry.read().managedCheckouts[record.checkoutId];
+                const writeStarted = current?.journal?.operation === 'rollback_preview' && current.journal.step === 'writing_local';
+                if (rollback.error.code === 'stale_local' || rollback.error.code === 'preview_modified') {
+                    return detachPreviewAfterLocalDrift(record, binding, rollback.error.code, 'rollback_preview');
+                }
+                if (!writeStarted || (rollback.error.code === 'git_error' && rollback.error.recoveryState === 'unchanged')) {
+                    updateManagedCheckout(record.checkoutId, (currentRecord) => ({ ...currentRecord, phase: 'ready', journal: null, revision: currentRecord.revision + 1 }));
+                }
+                else {
+                    updateManagedCheckout(record.checkoutId, (currentRecord) => ({ ...currentRecord, phase: 'recovery_required', revision: currentRecord.revision + 1 }));
+                }
+                return operationError(rollback.error.code, rollback.error.message, await inspectIsolated(binding));
+            }
+            const restored = updateManagedCheckout(record.checkoutId, (current) => ({
+                ...current,
+                phase: 'ready',
+                delivery: { state: 'ready_for_review', review },
+                journal: null,
+                revision: current.revision + 1,
+            }));
+            if (!restored)
+                return operationError('checkout_missing', 'Preview 已撤回，但 Checkout 记录丢失');
+            await releasePreviewArtifactsBestEffort(record, preview.previewId);
+            record = restored;
+        }
+        if (record.delivery.state !== 'ready_for_review') {
+            return operationError('operation_not_allowed', '当前没有可保存的验收阶段', await inspectIsolated(binding));
+        }
+        const review = record.delivery.review;
+        const checkpointId = dependencies.createCheckoutId();
+        const checkpointSequence = (record.checkpoints?.length ?? 0) + 1;
+        const operationId = dependencies.createCheckoutId();
+        const startedAt = Date.now();
+        const mutating = updateManagedCheckout(record.checkoutId, (current) => ({
+            ...current,
+            phase: 'mutating',
+            journal: {
+                operation: 'checkpoint',
+                operationId,
+                step: 'planning',
+                startedAt,
+                reviewId: review.reviewId,
+                checkpointId,
+                checkpointSequence,
+                checkpointRequestId: input.requestId,
+                checkpointRequestedRevision: input.expectedRevision,
+                checkpointMessage: commitMessage,
+                recoveryGeneration: input.expectedGeneration,
+                isolatedFingerprint: review.isolatedFingerprint,
+                isolatedHeadOid: review.isolatedHeadOid,
             },
             revision: current.revision + 1,
         }));
-        return inspectIsolated(binding);
+        if (!mutating)
+            return operationError('checkout_missing', 'Isolated Checkout 记录不存在');
+        const result = await dependencies.applyEngine.checkpoint({
+            isolatedPath: mutating.managedRoot,
+            expectedFingerprint: review.isolatedFingerprint,
+            expectedHeadOid: review.isolatedHeadOid,
+            commitMessage,
+            beforeCommit: async (prepared) => {
+                const journaled = updateManagedCheckout(mutating.checkoutId, (current) => ({
+                    ...current,
+                    journal: current.journal?.operation === 'checkpoint'
+                        ? {
+                            ...current.journal,
+                            step: 'updating_ref',
+                            commitOid: prepared.commitOid,
+                            parentOid: prepared.parentOid,
+                            checkpointIndexTreeOid: prepared.indexTreeOid,
+                            changedFiles: [...prepared.changedFiles],
+                        }
+                        : current.journal,
+                    revision: current.revision + 1,
+                }));
+                if (!journaled?.journal || journaled.journal.operation !== 'checkpoint' || journaled.journal.commitOid !== prepared.commitOid) {
+                    throw new SessionCheckoutError('stale_target', 'Checkpoint journal 在保留内部 ref 前发生变化');
+                }
+                await dependencies.git.retainInternalArtifact(mutating.localRoot, mutating.checkoutId, `checkpoints/${checkpointId}`, prepared.commitOid);
+            },
+        });
+        if (result.status === 'error') {
+            const current = dependencies.registry.read().managedCheckouts[mutating.checkoutId];
+            const commitPrepared = current?.journal?.operation === 'checkpoint' && typeof current.journal.commitOid === 'string';
+            if (!commitPrepared) {
+                updateManagedCheckout(mutating.checkoutId, (checkout) => ({
+                    ...checkout,
+                    phase: 'ready',
+                    ...(result.error.code === 'stale_isolated' ? { previousReview: projectPreviousReview(review) } : {}),
+                    delivery: result.error.code === 'stale_isolated'
+                        ? { state: 'working', iteration: review.iteration }
+                        : { state: 'ready_for_review', review },
+                    journal: null,
+                    revision: checkout.revision + 1,
+                }));
+            }
+            else {
+                updateManagedCheckout(mutating.checkoutId, (checkout) => ({ ...checkout, phase: 'recovery_required', revision: checkout.revision + 1 }));
+            }
+            return operationError(result.error.code, result.error.message, await inspectIsolated(binding, false));
+        }
+        const checkpoint = {
+            checkpointId,
+            sequence: checkpointSequence,
+            reviewId: review.reviewId,
+            requestId: input.requestId,
+            requestedRevision: input.expectedRevision,
+            generation: input.expectedGeneration,
+            iteration: review.iteration,
+            createdAt: startedAt,
+            commitOid: result.commitOid,
+            parentOid: result.parentOid,
+            summary: review.summary,
+            commitMessage,
+            validationStatus: review.validationStatus,
+            changedFiles: [...result.changedFiles],
+        };
+        const completed = updateManagedCheckout(mutating.checkoutId, (current) => {
+            const { recoveryContinuation: _continuation, ...withoutContinuation } = current;
+            return {
+                ...withoutContinuation,
+                phase: 'ready',
+                previousReview: projectPreviousReview(review),
+                checkpoints: [...(current.checkpoints ?? []), checkpoint],
+                delivery: { state: 'working', iteration: review.iteration },
+                journal: null,
+                revision: current.revision + 1,
+            };
+        });
+        if (!completed)
+            return operationError('checkout_missing', 'Checkpoint 已创建，但 Checkout 记录丢失');
+        return {
+            status: 'checkpointed',
+            target: await inspectIsolated(binding),
+            checkpoint: projectCheckpoint(checkpoint),
+            changedFiles: [...checkpoint.changedFiles],
+        };
     }
-    async function resumeRevisionTarget(sessionId, expectedRevision, expectedReviewId) {
+    async function resumeRevisionTarget(sessionId, expectedRevision, expectedReviewId, recovery) {
         const binding = await resolveBinding(sessionId);
         if (binding.ownerSessionId !== sessionId || binding.target.kind !== 'isolated') {
             throw new SessionCheckoutError('not_owner', '只有 owner Isolated 会话可以恢复编辑');
@@ -1118,14 +1426,131 @@ export function createSessionCheckoutModule(dependencies) {
             || record.delivery.review.reviewId !== expectedReviewId) {
             throw new SessionCheckoutError('stale_target', '验收状态在恢复编辑前发生变化，请刷新后重试');
         }
-        const iteration = record.delivery.review.iteration;
-        updateManagedCheckout(record.checkoutId, (current) => ({
-            ...current,
-            delivery: { state: 'working', iteration },
-            revision: current.revision + 1,
-        }));
+        if (recovery) {
+            const preflight = await preflightTarget(sessionId, expectedRevision);
+            const sameFiles = preflight.status === 'conflict'
+                && preflight.conflictingFiles.length === recovery.conflictingFiles.length
+                && preflight.conflictingFiles.every((file, index) => file === recovery.conflictingFiles[index]);
+            if (recovery.kind !== 'worktree_apply_conflict'
+                || recovery.reviewId !== expectedReviewId
+                || recovery.readyRevision !== expectedRevision
+                || preflight.status !== 'conflict'
+                || preflight.localHeadOid !== recovery.localHeadOid
+                || !sameFiles)
+                throw new SessionCheckoutError('stale_target', '冲突恢复身份在 Host CAS 前已变化，请重新预检');
+            record = dependencies.registry.read().managedCheckouts[record.checkoutId];
+            if (!record
+                || record.revision !== expectedRevision
+                || record.delivery.state !== 'ready_for_review'
+                || record.delivery.review.reviewId !== expectedReviewId)
+                throw new SessionCheckoutError('stale_target', '验收状态在冲突恢复前发生变化，请刷新后重试');
+        }
+        const reviewBeforeResume = record.delivery.review;
+        const iteration = reviewBeforeResume.iteration;
+        updateManagedCheckout(record.checkoutId, (current) => {
+            const { recoveryContinuation: _previousRecovery, ...withoutRecovery } = current;
+            return {
+                ...withoutRecovery,
+                previousReview: projectPreviousReview(reviewBeforeResume),
+                ...(recovery ? {
+                    recoveryContinuation: { ...recovery, workingRevision: current.revision + 1 },
+                } : {}),
+                delivery: { state: 'working', iteration },
+                revision: current.revision + 1,
+            };
+        });
         return inspectIsolated(binding);
     }
+    async function prepareReviewRegenerationTarget(sessionId, expectedRevision, expectedReviewId, requestId) {
+        const binding = await resolveBinding(sessionId);
+        if (binding.ownerSessionId !== sessionId || binding.target.kind !== 'isolated') {
+            throw new SessionCheckoutError('not_owner', '只有 owner Isolated 会话可以请求重新生成验收结果');
+        }
+        const preflight = await preflightTarget(sessionId, expectedRevision);
+        if (preflight.status !== 'blocked'
+            || preflight.reason !== 'stale_isolated'
+            || preflight.checkoutId !== binding.target.checkoutId
+            || preflight.reviewId !== expectedReviewId
+            || preflight.revision !== expectedRevision)
+            throw new SessionCheckoutError('stale_target', '只读验收再生成身份在 Host 授权前已变化');
+        const continuation = {
+            kind: 'worktree_review_regeneration', requestId, reviewId: expectedReviewId, revision: expectedRevision,
+        };
+        const updated = updateManagedCheckout(binding.target.checkoutId, (current) => {
+            if (current.revision !== expectedRevision
+                || current.delivery.state !== 'ready_for_review'
+                || current.delivery.review.reviewId !== expectedReviewId)
+                throw new SessionCheckoutError('stale_target', 'Ready Review 在只读授权前发生变化');
+            return { ...current, recoveryContinuation: continuation };
+        });
+        if (!updated)
+            throw new SessionCheckoutError('checkout_missing', 'Isolated Checkout 记录不存在');
+        return continuation;
+    }
+    async function preparePreviewRecoveryAnalysisTarget(sessionId, proof, requestId) {
+        const recovery = await preflightPreviewRecoveryTarget(sessionId, proof.revision, proof.reviewId, proof.previewId);
+        if (recovery.status !== 'assessed' || !recoveryProofMatches(proof, recovery.proof)) {
+            throw new SessionCheckoutError('stale_target', 'Detached Preview Recovery proof 已变化，请重新检查');
+        }
+        const continuation = {
+            kind: 'worktree_preview_recovery_analysis',
+            requestId,
+            reviewId: proof.reviewId,
+            previewId: proof.previewId,
+            revision: proof.revision,
+            generation: proof.generation,
+        };
+        const updated = updateManagedCheckout(proof.checkoutId, (current) => {
+            if (current.ownerSessionId !== sessionId
+                || current.revision !== proof.revision
+                || current.delivery.state !== 'preview_detached'
+                || current.delivery.review.reviewId !== proof.reviewId
+                || current.delivery.preview.previewId !== proof.previewId)
+                throw new SessionCheckoutError('stale_target', 'Detached Preview 在分析授权前发生变化');
+            return { ...current, recoveryContinuation: continuation };
+        });
+        if (!updated)
+            throw new SessionCheckoutError('checkout_missing', 'Isolated Checkout 记录不存在');
+        return continuation;
+    }
+    async function createPreviewRecoveryHandoffTarget(sessionId, proof, targetSessionId, requestId) {
+        if (!targetSessionId || targetSessionId === sessionId) {
+            throw new SessionCheckoutError('invalid_input', 'Recovery handoff 必须使用新的预分配 Session ID');
+        }
+        if (dependencies.lookup.getSession(targetSessionId) || getPersistedBinding(targetSessionId)) {
+            throw new SessionCheckoutError('target_already_bound', 'Recovery handoff Session ID 已被占用');
+        }
+        const recovery = await preflightPreviewRecoveryTarget(sessionId, proof.revision, proof.reviewId, proof.previewId);
+        if (recovery.status !== 'assessed' || !recoveryProofMatches(proof, recovery.proof)) {
+            throw new SessionCheckoutError('stale_target', 'Detached Preview Recovery proof 已变化，请重新检查');
+        }
+        const source = dependencies.registry.read().managedCheckouts[proof.checkoutId];
+        if (!source || source.ownerSessionId !== sessionId || source.delivery.state !== 'preview_detached') {
+            throw new SessionCheckoutError('stale_target', '旧 Detached Preview 身份已变化');
+        }
+        const originSessionId = source.sourceSessionId ?? source.ownerSessionId;
+        if (!dependencies.lookup.getSession(originSessionId)) {
+            throw new SessionCheckoutError('session_not_found', '原始 source Session 不可用，未创建 handoff Worktree');
+        }
+        const target = await bindTarget(targetSessionId, { kind: 'isolated' }, 0, Date.now(), originSessionId);
+        const binding = getPersistedBinding(targetSessionId);
+        const created = binding?.target.kind === 'isolated'
+            ? dependencies.registry.read().managedCheckouts[binding.target.checkoutId]
+            : undefined;
+        if (!created)
+            throw new SessionCheckoutError('checkout_missing', 'Recovery handoff Worktree 创建后记录缺失');
+        const continuation = {
+            kind: 'worktree_preview_recovery_handoff',
+            requestId,
+            sourceCheckoutId: source.checkoutId,
+            reviewId: proof.reviewId,
+            previewId: proof.previewId,
+            sourceRevision: proof.revision,
+            generation: proof.generation,
+        };
+        updateManagedCheckout(created.checkoutId, (current) => ({ ...current, recoveryContinuation: continuation }));
+        return { targetSessionId, managedRoot: created.managedRoot, target, continuation };
+    }
     async function operateApply(input, binding) {
         if (binding.ownerSessionId !== input.sessionId) {
             return operationError('not_owner', '继承 Session Target 的会话不能执行 Apply');
@@ -1215,7 +1640,7 @@ export function createSessionCheckoutModule(dependencies) {
                 reviewId: operationId,
                 iteration,
                 preparedAt: startedAt,
-                summary: 'Worktree 修改已通过 ApplyWorktree 同步到 Local 验收',
+                summary: 'Worktree 修改已通过 ApplyWorktree 写入 Local Preview',
                 validationStatus: 'not_run',
                 tests: [],
                 changedFiles: [...planResult.plan.changedFiles],
@@ -1290,6 +1715,137 @@ export function createSessionCheckoutModule(dependencies) {
             console.warn('[session-checkout] 清理 Preview refs 失败，已保守保留不可见引用');
         }
     }
+    async function previewArtifactsMatch(record, receipt) {
+        const prefix = `previews/${receipt.previewId}`;
+        const expected = [
+            [`${prefix}/local-working`, receipt.localWorkingTreeOid],
+            [`${prefix}/local-index`, receipt.localIndexTreeOid],
+            [`${prefix}/preview-working`, receipt.previewWorkingTreeOid],
+            [`${prefix}/isolated-snapshot`, receipt.isolatedSnapshotOid],
+        ];
+        for (const [name, oid] of expected) {
+            if (await dependencies.git.readInternalArtifact(record.localRoot, record.checkoutId, name) !== oid)
+                return false;
+        }
+        return true;
+    }
+    function blockedPreviewRecovery(record, reason, message) {
+        const delivery = record?.delivery;
+        const detached = delivery?.state === 'preview_detached' ? delivery : undefined;
+        return {
+            status: 'blocked',
+            localModified: false,
+            checkoutId: record?.checkoutId ?? '',
+            reviewId: detached?.review.reviewId ?? null,
+            previewId: detached?.preview.previewId ?? null,
+            revision: record?.revision ?? 0,
+            reason,
+            message,
+        };
+    }
+    function canonicalJson(value) {
+        if (Array.isArray(value))
+            return `[${value.map(canonicalJson).join(',')}]`;
+        if (value !== null && typeof value === 'object') {
+            const entries = Object.entries(value)
+                .filter(([, entry]) => entry !== undefined)
+                .sort(([left], [right]) => left.localeCompare(right));
+            return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(',')}}`;
+        }
+        return JSON.stringify(value);
+    }
+    function sha256Facts(value) {
+        return createHash('sha256').update(canonicalJson(value)).digest('hex');
+    }
+    function recoveryGeneration(facts) {
+        return sha256Facts(facts);
+    }
+    async function preflightPreviewRecoveryTarget(sessionId, expectedRevision, expectedReviewId, expectedPreviewId) {
+        const binding = await resolveBinding(sessionId);
+        if (binding.ownerSessionId !== sessionId || binding.target.kind !== 'isolated') {
+            return blockedPreviewRecovery(undefined, 'not_owner', '只有 owner Isolated 会话可以检查 Preview 恢复');
+        }
+        const record = dependencies.registry.read().managedCheckouts[binding.target.checkoutId];
+        if (!record)
+            return blockedPreviewRecovery(undefined, 'checkout_unavailable', 'Isolated Checkout 记录不存在');
+        if (record.revision !== expectedRevision) {
+            return blockedPreviewRecovery(record, 'stale_target', 'Session Target 已变化，请刷新后重新检查');
+        }
+        if (record.phase !== 'ready'
+            || record.delivery.state !== 'preview_detached'
+            || record.delivery.review.reviewId !== expectedReviewId
+            || record.delivery.preview.previewId !== expectedPreviewId) {
+            return blockedPreviewRecovery(record, 'not_preview_detached', '当前并非指定的 detached Preview 恢复状态');
+        }
+        const validated = await validateManagedCheckoutDetailed(binding, record, false);
+        if (validated.status !== 'valid') {
+            return blockedPreviewRecovery(record, 'checkout_unavailable', 'Worktree 身份、路径或 Git 状态暂时无法确认');
+        }
+        const { review, preview } = record.delivery;
+        try {
+            if (!await previewArtifactsMatch(record, preview)) {
+                return blockedPreviewRecovery(record, 'artifacts_missing', 'Preview retained artifacts 缺失或与 receipt 不一致');
+            }
+            const assessment = await dependencies.applyEngine.assessPreviewRecovery({
+                localPath: record.localRoot,
+                receipt: preview,
+            });
+            if ('error' in assessment) {
+                return blockedPreviewRecovery(record, 'git_error', assessment.error.message);
+            }
+            const holder = findProjectAcceptanceHolder(record);
+            const blocker = holder
+                ? { checkoutId: holder.checkoutId, ownerSessionId: holder.ownerSessionId, revision: holder.revision, state: holder.delivery.state }
+                : undefined;
+            const rollback = holder
+                ? { status: 'blocked', code: 'project_acceptance_busy', message: '另一个任务正在占用该项目的 Local 验收槽位' }
+                : assessment.rollback;
+            const finalize = holder
+                ? { status: 'blocked', code: 'project_acceptance_busy', message: '另一个任务正在占用该项目的 Local 验收槽位' }
+                : assessment.finalize;
+            const facts = {
+                sessionId,
+                checkoutId: record.checkoutId,
+                reviewId: review.reviewId,
+                previewId: preview.previewId,
+                revision: record.revision,
+                receiptFingerprint: sha256Facts(preview),
+                localFingerprint: assessment.localFingerprint,
+                localHeadOid: assessment.localHeadOid,
+                localHeadRef: assessment.localHeadRef,
+                localHeadTreeOid: assessment.localHeadTreeOid,
+                localIndexTreeOid: assessment.localIndexTreeOid,
+                localWorkingTreeOid: assessment.localWorkingTreeOid,
+                rollback,
+                finalize,
+                ...(blocker ? { blocker } : {}),
+            };
+            const current = dependencies.registry.read().managedCheckouts[record.checkoutId];
+            if (!current
+                || current.revision !== record.revision
+                || current.phase !== 'ready'
+                || current.delivery.state !== 'preview_detached'
+                || current.delivery.review.reviewId !== review.reviewId
+                || current.delivery.preview.previewId !== preview.previewId) {
+                return blockedPreviewRecovery(current, 'stale_target', 'Preview 恢复状态在检查期间发生变化');
+            }
+            if (!await previewArtifactsMatch(current, current.delivery.preview)) {
+                return blockedPreviewRecovery(current, 'artifacts_missing', 'Preview retained artifacts 在检查期间发生变化');
+            }
+            const proof = { ...facts, generation: recoveryGeneration(facts) };
+            return { status: 'assessed', localModified: false, proof };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Preview 恢复检查失败';
+            return blockedPreviewRecovery(record, 'git_error', message);
+        }
+    }
+    function recoveryProofMatches(left, right) {
+        if (left === undefined)
+            return false;
+        const { generation: leftGeneration, ...leftFacts } = left;
+        return leftGeneration === recoveryGeneration(leftFacts) && leftGeneration === right.generation;
+    }
     function blockedPreflight(record, reason, message, blocker) {
         return {
             status: 'blocked',
@@ -1303,6 +1859,7 @@ export function createSessionCheckoutModule(dependencies) {
                 blocker: {
                     checkoutId: blocker.checkoutId,
                     ownerSessionId: blocker.ownerSessionId,
+                    revision: blocker.revision,
                     state: blocker.delivery.state,
                 },
             }),
@@ -1575,6 +2132,18 @@ export function createSessionCheckoutModule(dependencies) {
             return operationError('preview_not_active', '当前没有可撤回的 Local Preview', await inspectIsolated(binding));
         }
         const retryingDetached = record.delivery.state === 'preview_detached';
+        if (retryingDetached) {
+            const recovery = await preflightPreviewRecoveryTarget(input.sessionId, input.expectedRevision, record.delivery.review.reviewId, record.delivery.preview.previewId);
+            if (recovery.status !== 'assessed') {
+                return operationError('stale_target', recovery.message, await inspectIsolated(binding));
+            }
+            if (!recoveryProofMatches(input.recoveryProof, recovery.proof)) {
+                return operationError('stale_target', 'Preview Recovery proof 已过期或不匹配，请重新检查', await inspectIsolated(binding));
+            }
+            if (recovery.proof.rollback.status !== 'safe') {
+                return operationError(recovery.proof.rollback.code, recovery.proof.rollback.message, await inspectIsolated(binding));
+            }
+        }
         const resumeRevision = input.resumeRevision ?? (retryingRecovery && record.journal?.operation === 'rollback_preview'
             ? record.journal.resumeRevision ?? false
             : false);
@@ -1592,19 +2161,39 @@ export function createSessionCheckoutModule(dependencies) {
                 previewId: preview.previewId,
                 reviewId: review.reviewId,
                 resumeRevision,
+                ...(input.recoveryProof ? { recoveryGeneration: input.recoveryProof.generation } : {}),
             },
             revision: current.revision + 1,
         }));
-        const result = await dependencies.applyEngine.rollback({ localPath: record.localRoot, receipt: preview });
+        const result = await dependencies.applyEngine.rollback({
+            localPath: record.localRoot,
+            receipt: preview,
+            beforeWrite: async () => {
+                updateManagedCheckout(record.checkoutId, (current) => ({
+                    ...current,
+                    journal: current.journal?.operation === 'rollback_preview'
+                        ? { ...current.journal, step: 'writing_local' }
+                        : current.journal,
+                    revision: current.revision + 1,
+                }));
+            },
+        });
         if (result.status === 'error') {
+            const current = dependencies.registry.read().managedCheckouts[record.checkoutId];
+            const writeStarted = current?.journal?.operation === 'rollback_preview' && current.journal.step === 'writing_local';
             if (result.error.code === 'stale_local' || result.error.code === 'preview_modified') {
                 if (!retryingDetached) {
                     return detachPreviewAfterLocalDrift(record, binding, result.error.code, 'rollback_preview');
                 }
-                updateManagedCheckout(record.checkoutId, (current) => ({ ...current, phase: 'ready', journal: null, revision: current.revision + 1 }));
+                updateManagedCheckout(record.checkoutId, (checkout) => ({ ...checkout, phase: 'ready', journal: null, revision: checkout.revision + 1 }));
+            }
+            else if (result.error.code === 'invalid_input'
+                || !writeStarted
+                || (result.error.code === 'git_error' && result.error.recoveryState === 'unchanged')) {
+                updateManagedCheckout(record.checkoutId, (checkout) => ({ ...checkout, phase: 'ready', journal: null, revision: checkout.revision + 1 }));
             }
-            else if (result.error.code === 'invalid_input') {
-                updateManagedCheckout(record.checkoutId, (current) => ({ ...current, phase: 'ready', journal: null, revision: current.revision + 1 }));
+            else {
+                updateManagedCheckout(record.checkoutId, (checkout) => ({ ...checkout, phase: 'recovery_required', revision: checkout.revision + 1 }));
             }
             return operationError(result.error.code, result.error.message, await inspectIsolated(binding));
         }
@@ -1833,9 +2422,23 @@ export function createSessionCheckoutModule(dependencies) {
         if (record.revision !== input.expectedRevision) {
             return operationError('stale_target', 'Session Target 已变化，请刷新后重试', await inspectIsolated(binding));
         }
-        if (record.phase !== 'ready' || record.delivery.state !== 'preview_active') {
+        if (record.phase !== 'ready'
+            || (record.delivery.state !== 'preview_active' && record.delivery.state !== 'preview_detached')) {
             return operationError('preview_not_active', '当前没有等待验收的 Local Preview', await inspectIsolated(binding));
         }
+        const retryingDetached = record.delivery.state === 'preview_detached';
+        if (retryingDetached) {
+            const recovery = await preflightPreviewRecoveryTarget(input.sessionId, input.expectedRevision, record.delivery.review.reviewId, record.delivery.preview.previewId);
+            if (recovery.status !== 'assessed') {
+                return operationError('stale_target', recovery.message, await inspectIsolated(binding));
+            }
+            if (!recoveryProofMatches(input.recoveryProof, recovery.proof)) {
+                return operationError('stale_target', 'Preview Recovery proof 已过期或不匹配，请重新检查', await inspectIsolated(binding));
+            }
+            if (recovery.proof.finalize.status !== 'safe') {
+                return operationError(recovery.proof.finalize.code, recovery.proof.finalize.message, await inspectIsolated(binding));
+            }
+        }
         // Harness plugin does not expose Domi collaborator checkout inheritance.
         const { preview, review } = record.delivery;
         const operationId = dependencies.createCheckoutId();
@@ -1843,7 +2446,16 @@ export function createSessionCheckoutModule(dependencies) {
         updateManagedCheckout(record.checkoutId, (current) => ({
             ...current,
             phase: 'mutating',
-            journal: { operation: 'finalize_preview', operationId, step: 'planning', startedAt, previewId: preview.previewId, reviewId: review.reviewId, retention: input.retention ?? 'cleanup' },
+            journal: {
+                operation: 'finalize_preview',
+                operationId,
+                step: 'planning',
+                startedAt,
+                previewId: preview.previewId,
+                reviewId: review.reviewId,
+                retention: input.retention ?? 'cleanup',
+                ...(input.recoveryProof ? { recoveryGeneration: input.recoveryProof.generation } : {}),
+            },
             revision: current.revision + 1,
         }));
         const result = await dependencies.applyEngine.finalize({
@@ -1861,11 +2473,22 @@ export function createSessionCheckoutModule(dependencies) {
             },
         });
         if (result.status === 'error') {
-            if (result.error.code === 'stale_local' || result.error.code === 'preview_modified') {
+            if ((result.error.code === 'stale_local' || result.error.code === 'preview_modified') && !retryingDetached) {
                 return detachPreviewAfterLocalDrift(record, binding, result.error.code, 'finalize_preview');
             }
-            if (result.error.code === 'commit_isolation_conflict' || result.error.code === 'operation_not_allowed' || result.error.code === 'invalid_input') {
-                updateManagedCheckout(record.checkoutId, (current) => ({ ...current, phase: 'ready', journal: null, revision: current.revision + 1 }));
+            const current = dependencies.registry.read().managedCheckouts[record.checkoutId];
+            const writeStarted = current?.journal?.operation === 'finalize_preview' && current.journal.step === 'updating_ref';
+            if (result.error.code === 'commit_isolation_conflict'
+                || result.error.code === 'operation_not_allowed'
+                || result.error.code === 'invalid_input'
+                || result.error.code === 'stale_local'
+                || result.error.code === 'preview_modified'
+                || !writeStarted
+                || (result.error.code === 'git_error' && result.error.recoveryState === 'unchanged')) {
+                updateManagedCheckout(record.checkoutId, (checkout) => ({ ...checkout, phase: 'ready', journal: null, revision: checkout.revision + 1 }));
+            }
+            else {
+                updateManagedCheckout(record.checkoutId, (checkout) => ({ ...checkout, phase: 'recovery_required', revision: checkout.revision + 1 }));
             }
             return operationError(result.error.code, result.error.message, await inspectIsolated(binding));
         }
@@ -1877,11 +2500,13 @@ export function createSessionCheckoutModule(dependencies) {
                 review,
                 commitOid: result.commitOid,
                 proof: {
-                    localBranch: preview.localHeadRef?.startsWith('refs/heads/')
-                        ? preview.localHeadRef.slice('refs/heads/'.length)
-                        : null,
-                    localHeadBefore: preview.localHeadOid,
-                    localHeadAfter: result.commitOid ?? preview.localHeadOid,
+                    localBranch: input.recoveryProof?.localHeadRef?.startsWith('refs/heads/')
+                        ? input.recoveryProof.localHeadRef.slice('refs/heads/'.length)
+                        : preview.localHeadRef?.startsWith('refs/heads/')
+                            ? preview.localHeadRef.slice('refs/heads/'.length)
+                            : null,
+                    localHeadBefore: input.recoveryProof?.localHeadOid ?? preview.localHeadOid,
+                    localHeadAfter: result.commitOid ?? input.recoveryProof?.localHeadOid ?? preview.localHeadOid,
                     changedFiles: [...result.changedFiles],
                     validationStatus: review.validationStatus,
                     ...(review.validationSummary === undefined ? {} : { validationSummary: review.validationSummary }),
@@ -2233,7 +2858,7 @@ export function createSessionCheckoutModule(dependencies) {
         }
         if (record.delivery.state === 'preview_active') {
             if (!input.rollbackPreview) {
-                return operationError('preview_not_active', 'Local 正在验收本任务；放弃任务前必须先安全撤回 Preview', await inspectIsolated(binding));
+                return operationError('preview_not_active', '本任务正在 Local 预览；放弃任务前必须先安全撤回 Preview', await inspectIsolated(binding));
             }
             const rollback = await dependencies.applyEngine.rollback({
                 localPath: record.localRoot,
@@ -2283,11 +2908,11 @@ export function createSessionCheckoutModule(dependencies) {
             if (!record || record.phase !== 'ready') {
                 return operationError('recovery_required', 'Isolated Checkout 状态已变化，需要恢复');
             }
-            dirty = (await dependencies.git.status(record.managedRoot)).dirty;
+            dirty = (await dependencies.git.status(record.managedRoot)).dirty || (record.checkpoints?.length ?? 0) > 0;
         }
         else {
             try {
-                dirty = (await dependencies.git.status(record.managedRoot)).dirty;
+                dirty = (await dependencies.git.status(record.managedRoot)).dirty || (record.checkpoints?.length ?? 0) > 0;
             }
             catch {
                 dirty = true;
@@ -2295,7 +2920,10 @@ export function createSessionCheckoutModule(dependencies) {
             inspected = recoveryView(binding, record, dirty);
         }
         if (dirty && !input.confirmDirty) {
-            return operationError('dirty_confirmation_required', 'Isolated Checkout 含未提交修改或状态无法确认，需要明确确认', inspected);
+            const checkpointDetail = (record.checkpoints?.length ?? 0) > 0
+                ? `；确认后会永久删除 ${record.checkpoints.length} 个尚未交付到 Local 的阶段`
+                : '';
+            return operationError('dirty_confirmation_required', `Isolated Checkout 含未提交修改、未交付阶段或状态无法确认，需要明确确认${checkpointDetail}`, inspected);
         }
         try {
             await dependencies.git.removeWorktree(record.localRoot, record.managedGitRoot);
@@ -2356,6 +2984,8 @@ export function createSessionCheckoutModule(dependencies) {
                 return await operateFinish(input, binding);
             if (input.action === 'preview')
                 return await operatePreview(input, binding);
+            if (input.action === 'checkpoint')
+                return await operateCheckpoint(input, binding);
             if (input.action === 'rollback_preview')
                 return await operateRollbackPreview(input, binding);
             if (input.action === 'finalize_preview')
@@ -2478,6 +3108,7 @@ export function createSessionCheckoutModule(dependencies) {
             phase: record.phase,
             dirty,
             commitOid,
+            ...((record.checkpoints?.length ?? 0) > 0 ? { checkpointCount: record.checkpoints.length } : {}),
             ...(delivery.state === 'retained' ? {
                 retention: delivery.retention,
                 retainedAt: delivery.retainedAt,
@@ -3164,6 +3795,7 @@ export function createSessionCheckoutModule(dependencies) {
         inspect: inspectAvailable,
         runtimeContext,
         preflight: (sessionId, expectedRevision) => withBindingLock(() => preflightTarget(sessionId, expectedRevision)),
+        preflightPreviewRecovery: (sessionId, expectedRevision, expectedReviewId, expectedPreviewId) => withBindingLock(() => preflightPreviewRecoveryTarget(sessionId, expectedRevision, expectedReviewId, expectedPreviewId), { allowConcurrentInspect: true }),
         runExclusiveSessionMutation: (sessionId, operation) => withBindingLock(async () => (operation(await inspectTarget(sessionId, true)))),
         bind: (sessionId, choice) => {
             const requestStartedAt = Date.now();
@@ -3193,7 +3825,10 @@ export function createSessionCheckoutModule(dependencies) {
             return { targetSessionId, managedRoot: record.managedRoot, target };
         }),
         beginNextIteration: (sessionId, expectedRevision) => withBindingLock(() => beginNextIterationTarget(sessionId, expectedRevision)),
-        resumeRevision: (sessionId, expectedRevision, expectedReviewId) => withBindingLock(() => resumeRevisionTarget(sessionId, expectedRevision, expectedReviewId)),
+        resumeRevision: (sessionId, expectedRevision, expectedReviewId, recovery) => withBindingLock(() => resumeRevisionTarget(sessionId, expectedRevision, expectedReviewId, recovery)),
+        prepareReviewRegeneration: (sessionId, expectedRevision, expectedReviewId, requestId) => withBindingLock(() => prepareReviewRegenerationTarget(sessionId, expectedRevision, expectedReviewId, requestId)),
+        preparePreviewRecoveryAnalysis: (sessionId, proof, requestId) => withBindingLock(() => preparePreviewRecoveryAnalysisTarget(sessionId, proof, requestId)),
+        createPreviewRecoveryHandoff: (sessionId, proof, targetSessionId, requestId) => withBindingLock(() => createPreviewRecoveryHandoffTarget(sessionId, proof, targetSessionId, requestId)),
         markReadyForReview: (sessionId, input) => withBindingLock(() => markReadyForReviewTarget(sessionId, input)),
         operate: (input) => withBindingLock(() => operateTarget(input)),
         // 只读管理列表不占用全局 mutation lock；慢速目录诊断与用户操作互不阻塞。