dsh-git-worktree 0.4.0 → 0.6.0

package/lib/console-contract.d.ts

@@ -7,7 +7,7 @@
  * re-validates project, owner, cwd, revision and review identity at execution.
  * @module dsh-git-worktree/console-contract
  */
-import { type SessionCheckoutErrorCode, type SessionCheckoutPhase, type WorktreeRetentionMode, type WorktreeApplyPreflightView, type WorktreeAcceptanceBlockerView, type WorktreeDeliveryProofView, type WorktreeValidationItem, type WorktreeValidationStatus } from './types.js';
+import { type SessionCheckoutErrorCode, type SessionCheckoutPhase, type WorktreeRetentionMode, type WorktreeApplyPreflightView, type WorktreePreviewRecoveryPreflightView, type WorktreePreviewRecoveryProof, type WorktreeAcceptanceBlockerView, type WorktreeDeliveryProofView, type WorktreeValidationItem, type WorktreeValidationStatus, type WorktreeCheckpointView } from './types.js';
 export declare const WORKTREE_CONSOLE_TARGET_STATES: readonly ["local", "creating", "working", "ready_for_review", "preview_active", "preview_detached", "retained", "cleanup_pending", "recovery_required", "delivered"];
 export type WorktreeConsoleTargetState = typeof WORKTREE_CONSOLE_TARGET_STATES[number];
 export type WorktreeConsoleDeliveryState = 'working' | 'ready_for_review' | 'preview_active' | 'preview_detached' | 'finalized' | 'retained' | 'delivered';
@@ -30,6 +30,8 @@ export interface WorktreeConsoleCapabilities {
     discard: boolean;
     preflight: boolean;
     preview: boolean;
+    /** Save the exact reviewed snapshot as a managed-Worktree-only stage and continue editing. */
+    checkpoint: boolean;
     /** Invalidate an unsynced review and resume the same iteration without touching Local. */
     resumeRevision: boolean;
     rollbackPreview: boolean;
@@ -42,6 +44,8 @@ export interface WorktreeConsoleCapabilities {
     beginNextIteration: boolean;
 }
 export interface WorktreeConsolePreviewRecovery {
+    previewId: string;
+    detachedAt: number;
     reason: 'stale_local' | 'preview_modified';
     attemptedAction: 'rollback_preview' | 'finalize_preview' | 'discard';
 }
@@ -78,6 +82,8 @@ export interface WorktreeConsoleTargetSummary {
     cleanupMessage?: string;
     deliveryProof?: WorktreeConsoleDeliveryProof;
     review?: WorktreeConsoleReviewSummary;
+    checkpoints?: WorktreeCheckpointView[];
+    checkpointGeneration?: string;
     reviewSlot?: 'available' | 'waiting';
     reviewSlotOwnerSessionId?: string;
     reviewSlotHolder?: WorktreeAcceptanceBlockerView;
@@ -91,6 +97,8 @@ export interface WorktreeConsoleTargetDetails extends WorktreeConsoleTargetSumma
     sourceRoot: string | null;
     sourceOid: string;
     currentBranch: string | null;
+    /** Owner-only Host proof for one explicitly authorized recovery continuation. */
+    recoveryContinuation?: WorktreeRecoveryProof;
 }
 export interface WorktreeConsoleCurrentRequest {
     sessionId: string;
@@ -145,17 +153,48 @@ export interface WorktreeConsolePreviewRequest {
     expectedRevision: number;
     expectedReviewId: string;
 }
+export interface WorktreeConsoleCheckpointRequest {
+    sessionId: string;
+    checkoutId: string;
+    expectedRevision: number;
+    expectedReviewId: string;
+    expectedGeneration: string;
+    requestId: string;
+    commitMessage: string;
+}
 export interface WorktreeConsoleResumeRevisionRequest {
     sessionId: string;
     checkoutId: string;
     expectedRevision: number;
     expectedReviewId: string;
+    /** Present only for the explicit conflict-recovery action; Host re-runs conflict preflight under CAS. */
+    conflictContinuation?: WorktreeApplyConflictContinuation;
+}
+export interface WorktreeConsolePreviewRecoveryPreflightRequest {
+    sessionId: string;
+    checkoutId: string;
+    expectedRevision: number;
+    expectedReviewId: string;
+    expectedPreviewId: string;
+}
+export interface WorktreeConsolePreviewRecoveryPreflightResponse {
+    preflight: WorktreePreviewRecoveryPreflightView;
+}
+export interface WorktreeConsolePreparePreviewRecoveryAnalysisRequest extends WorktreeConsolePreviewRecoveryPreflightRequest {
+    recoveryProof: WorktreePreviewRecoveryProof;
+}
+export interface WorktreeConsoleCreatePreviewRecoveryHandoffRequest extends WorktreeConsolePreviewRecoveryPreflightRequest {
+    recoveryProof: WorktreePreviewRecoveryProof;
+}
+export interface WorktreeConsoleCreatePreviewRecoveryHandoffResponse extends WorktreeConsoleCreateResponse {
+    recoveryContinuation: WorktreePreviewRecoveryHandoffProof;
 }
 export interface WorktreeConsoleRollbackPreviewRequest {
     sessionId: string;
     checkoutId: string;
     expectedRevision: number;
     resumeRevision?: boolean;
+    recoveryProof?: WorktreePreviewRecoveryProof;
 }
 export interface WorktreeConsoleFinalizeRequest {
     sessionId: string;
@@ -173,6 +212,7 @@ export interface WorktreeConsoleFinalizePreviewRequest {
     expectedReviewId: string;
     commitMessage: string;
     retention: WorktreeRetentionMode;
+    recoveryProof?: WorktreePreviewRecoveryProof;
 }
 export interface WorktreeConsoleSetRetentionRequest {
     sessionId: string;
@@ -194,6 +234,14 @@ export interface WorktreeConsoleMutationResponse {
     target: WorktreeConsoleTargetSummary;
     changedFiles?: string[];
     commitOid?: string | null;
+    checkpoint?: WorktreeCheckpointView;
+    recoveryContinuation?: WorktreeRecoveryProof;
+}
+export interface WorktreeConsolePrepareRegenerationRequest {
+    sessionId: string;
+    checkoutId: string;
+    expectedRevision: number;
+    expectedReviewId: string;
 }
 export type WorktreeConsoleFileStatus = 'added' | 'modified' | 'deleted' | 'renamed' | 'binary';
 export interface WorktreeConsoleDiffFile {
@@ -220,10 +268,61 @@ export declare const WORKTREE_CONSOLE_ERROR_CODES: readonly ["session_not_found"
 export type WorktreeConsoleErrorCode = SessionCheckoutErrorCode | 'transport_unavailable' | 'malformed_response';
 export type WorktreeConsoleErrorCategory = 'permission' | 'stale' | 'confirmation' | 'recovery' | 'conflict' | 'unavailable' | 'invalid' | 'internal';
 export type WorktreeConsoleRecovery = 'none' | 'refresh' | 'confirm_dirty' | 'open_recovery' | 'retry';
+export interface WorktreeApplyConflictContinuation {
+    kind: 'worktree_apply_conflict';
+    /** Stable identity for Client single-flight and retry within this renderer lifetime. */
+    requestId: string;
+    checkoutId: string;
+    /** Review that remains Ready until the user explicitly resumes it for conflict resolution. */
+    reviewId: string;
+    /** Authoritative revision after the failed real-time write attempt returned to Ready. */
+    revision: number;
+    localHeadOid: string;
+    conflictingFiles: string[];
+}
+export interface WorktreeApplyConflictRecoveryProof {
+    kind: 'worktree_apply_conflict';
+    requestId: string;
+    checkoutId: string;
+    reviewId: string;
+    /** Exact Working revision produced by the Host conflict-resume CAS. */
+    revision: number;
+    localHeadOid: string;
+    conflictingFiles: string[];
+}
+export interface WorktreeReviewRegenerationProof {
+    kind: 'worktree_review_regeneration';
+    requestId: string;
+    checkoutId: string;
+    reviewId: string;
+    revision: number;
+}
+export interface WorktreePreviewRecoveryAnalysisProof {
+    kind: 'worktree_preview_recovery_analysis';
+    requestId: string;
+    checkoutId: string;
+    reviewId: string;
+    previewId: string;
+    revision: number;
+    generation: string;
+}
+export interface WorktreePreviewRecoveryHandoffProof {
+    kind: 'worktree_preview_recovery_handoff';
+    requestId: string;
+    checkoutId: string;
+    sourceCheckoutId: string;
+    reviewId: string;
+    previewId: string;
+    revision: number;
+    generation: string;
+}
+export type WorktreeRecoveryProof = WorktreeApplyConflictRecoveryProof | WorktreeReviewRegenerationProof | WorktreePreviewRecoveryAnalysisProof | WorktreePreviewRecoveryHandoffProof;
+export type WorktreeConsoleContinuation = WorktreeApplyConflictContinuation;
 export interface WorktreeConsoleError {
     code: WorktreeConsoleErrorCode;
     message: string;
     details?: Record<string, string | number | boolean | null>;
+    continuation?: WorktreeConsoleContinuation;
 }
 export type WorktreeConsoleOutcome<T> = {
     ok: true;
@@ -246,8 +345,13 @@ export interface WorktreeConsoleAdapter {
     inspect(request: WorktreeConsoleInspectRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleInspectResponse>>;
     reviewDiff(request: WorktreeConsoleReviewDiffRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleReviewDiffResponse>>;
     preflight(request: WorktreeConsolePreflightRequest): Promise<WorktreeConsoleOutcome<WorktreeConsolePreflightResponse>>;
+    previewRecoveryPreflight(request: WorktreeConsolePreviewRecoveryPreflightRequest): Promise<WorktreeConsoleOutcome<WorktreeConsolePreviewRecoveryPreflightResponse>>;
+    preparePreviewRecoveryAnalysis(request: WorktreeConsolePreparePreviewRecoveryAnalysisRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleMutationResponse>>;
+    createPreviewRecoveryHandoff(request: WorktreeConsoleCreatePreviewRecoveryHandoffRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleCreatePreviewRecoveryHandoffResponse>>;
     preview(request: WorktreeConsolePreviewRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleMutationResponse>>;
+    checkpoint(request: WorktreeConsoleCheckpointRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleMutationResponse>>;
     resumeRevision(request: WorktreeConsoleResumeRevisionRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleMutationResponse>>;
+    prepareReviewRegeneration(request: WorktreeConsolePrepareRegenerationRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleMutationResponse>>;
     rollbackPreview(request: WorktreeConsoleRollbackPreviewRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleMutationResponse>>;
     discard(request: WorktreeConsoleDiscardRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleMutationResponse>>;
     finalize(request: WorktreeConsoleFinalizeRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleMutationResponse>>;

package/lib/console-contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"console-contract.js","sourceRoot":"","sources":["../src/console-contract.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"console-contract.js","sourceRoot":"","sources":["../src/console-contract.ts"],"names":[],"mappings":"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"}

package/lib/console-host/control-plane.d.ts

@@ -1,4 +1,4 @@
-import type { WorktreeConsoleBeginNextIterationRequest, WorktreeConsoleCreateResponse, WorktreeConsoleCurrentResponse, WorktreeConsoleDiscardRequest, WorktreeConsoleFinalizePreviewRequest, WorktreeConsoleFinalizeRequest, WorktreeConsoleInspectResponse, WorktreeConsoleListRequest, WorktreeConsoleListResponse, WorktreeConsoleMutationResponse, WorktreeConsoleOutcome, WorktreeConsolePreflightRequest, WorktreeConsolePreflightResponse, WorktreeConsolePreviewRequest, WorktreeConsoleResumeRevisionRequest, WorktreeConsoleRollbackPreviewRequest, WorktreeConsoleRetryCleanupRequest, WorktreeConsoleReviewDiffRequest, WorktreeConsoleReviewDiffResponse, WorktreeConsoleSetRetentionRequest } from '../console-contract.js';
+import type { WorktreeConsoleBeginNextIterationRequest, WorktreeConsoleCreatePreviewRecoveryHandoffRequest, WorktreeConsoleCreatePreviewRecoveryHandoffResponse, WorktreeConsoleCreateResponse, WorktreeConsoleCheckpointRequest, WorktreeConsoleCurrentResponse, WorktreeConsoleDiscardRequest, WorktreeConsoleFinalizePreviewRequest, WorktreeConsoleFinalizeRequest, WorktreeConsoleInspectResponse, WorktreeConsoleListRequest, WorktreeConsoleListResponse, WorktreeConsoleMutationResponse, WorktreeConsoleOutcome, WorktreeConsolePreflightRequest, WorktreeConsolePreflightResponse, WorktreeConsolePreparePreviewRecoveryAnalysisRequest, WorktreeConsolePreviewRecoveryPreflightRequest, WorktreeConsolePreviewRecoveryPreflightResponse, WorktreeConsolePrepareRegenerationRequest, WorktreeConsolePreviewRequest, WorktreeConsoleResumeRevisionRequest, WorktreeConsoleRollbackPreviewRequest, WorktreeConsoleRetryCleanupRequest, WorktreeConsoleReviewDiffRequest, WorktreeConsoleReviewDiffResponse, WorktreeConsoleSetRetentionRequest } from '../console-contract.js';
 import type { SessionCheckoutFilesPort, SessionCheckoutGitPort, SessionCheckoutLookupPort, SessionCheckoutRegistryPort } from '../ports.js';
 import type { SessionCheckoutModule } from '../index.js';
 import { type WorktreeReviewDiffReader } from './review-diff.js';
@@ -18,8 +18,13 @@ export interface WorktreeConsoleControlPlane {
     inspect(sessionId: string, checkoutId: string): Promise<WorktreeConsoleOutcome<WorktreeConsoleInspectResponse>>;
     reviewDiff(request: WorktreeConsoleReviewDiffRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleReviewDiffResponse>>;
     preflight(request: WorktreeConsolePreflightRequest): Promise<WorktreeConsoleOutcome<WorktreeConsolePreflightResponse>>;
+    previewRecoveryPreflight(request: WorktreeConsolePreviewRecoveryPreflightRequest): Promise<WorktreeConsoleOutcome<WorktreeConsolePreviewRecoveryPreflightResponse>>;
+    preparePreviewRecoveryAnalysis(request: WorktreeConsolePreparePreviewRecoveryAnalysisRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleMutationResponse>>;
+    createPreviewRecoveryHandoff(request: WorktreeConsoleCreatePreviewRecoveryHandoffRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleCreatePreviewRecoveryHandoffResponse>>;
     preview(request: WorktreeConsolePreviewRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleMutationResponse>>;
+    checkpoint(request: WorktreeConsoleCheckpointRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleMutationResponse>>;
     resumeRevision(request: WorktreeConsoleResumeRevisionRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleMutationResponse>>;
+    prepareReviewRegeneration(request: WorktreeConsolePrepareRegenerationRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleMutationResponse>>;
     rollbackPreview(request: WorktreeConsoleRollbackPreviewRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleMutationResponse>>;
     discard(request: WorktreeConsoleDiscardRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleMutationResponse>>;
     finalize(request: WorktreeConsoleFinalizeRequest): Promise<WorktreeConsoleOutcome<WorktreeConsoleMutationResponse>>;

package/lib/console-host/control-plane.js

@@ -16,11 +16,43 @@ function readyReview(record) {
     return record.delivery.review;
 }
 function previewReview(record) {
-    if (record.phase !== 'ready' || record.delivery.state !== 'preview_active') {
+    if (record.phase !== 'ready'
+        || (record.delivery.state !== 'preview_active' && record.delivery.state !== 'preview_detached')) {
         throw domainError('preview_not_active', '当前没有等待验收的 Local Preview');
     }
     return record.delivery.review;
 }
+function safeRecoveryRequestId(value) {
+    return value.length > 0 && value.length <= 500 && !/[\0\r\n]/u.test(value);
+}
+function safeConflictFile(file) {
+    if (!file || file.length > 1000 || /[\0-\x1f\x7f]/u.test(file))
+        return false;
+    if (/^(?:[A-Za-z]:[\\/]|[\\/])/u.test(file))
+        return false;
+    return !file.split(/[\\/]/u).some(segment => segment === '' || segment === '.' || segment === '..');
+}
+function applyConflictContinuation(result, reviewId) {
+    const checkoutId = result.target.checkout.id;
+    const revision = result.target.revision;
+    if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/iu.test(result.localHeadOid)) {
+        throw domainError('git_error', '冲突恢复缺少有效的 Local HEAD 身份');
+    }
+    const localHeadOid = result.localHeadOid;
+    if (result.conflictingFiles.length > 500 || !result.conflictingFiles.every(safeConflictFile)) {
+        throw domainError('git_error', '冲突恢复包含不安全或越界的文件身份');
+    }
+    const conflictingFiles = [...result.conflictingFiles];
+    return {
+        kind: 'worktree_apply_conflict',
+        requestId: `apply-conflict:${checkoutId}:${reviewId}:${revision}:${localHeadOid}`,
+        checkoutId,
+        reviewId,
+        revision,
+        localHeadOid,
+        conflictingFiles,
+    };
+}
 function preflightFailure(view) {
     if (view === undefined)
         return failure('git_error', '当前 SessionCheckoutModule 不支持验收预检');
@@ -202,9 +234,10 @@ export function createWorktreeConsoleControlPlane(options) {
                 reviewSlotHolder: {
                     checkoutId: holder.checkoutId,
                     ownerSessionId: holder.ownerSessionId,
+                    revision: holder.revision,
                     state: holder.delivery.state,
                 },
-                capabilities: { ...target.capabilities, preview: false, finalize: false },
+                capabilities: { ...target.capabilities, preview: false, checkpoint: false, finalize: false },
             } : {}),
         };
     }
@@ -384,6 +417,110 @@ export function createWorktreeConsoleControlPlane(options) {
                 throw domainError('git_error', '当前 SessionCheckoutModule 不支持验收预检');
             return { preflight };
         }),
+        previewRecoveryPreflight: request => outcome(async () => {
+            const record = await authorize(request.sessionId, request.checkoutId);
+            if (record.ownerSessionId !== request.sessionId)
+                throw domainError('not_owner', '只有 owner Isolated Session 可以检查 Preview 恢复');
+            if (record.revision !== request.expectedRevision)
+                throw domainError('stale_target', 'Session Target 已变化，请刷新');
+            if (record.phase !== 'ready'
+                || record.delivery.state !== 'preview_detached'
+                || record.delivery.review.reviewId !== request.expectedReviewId
+                || record.delivery.preview.previewId !== request.expectedPreviewId)
+                throw domainError('stale_target', 'Detached Preview 身份已变化，请刷新');
+            const preflight = await options.module.preflightPreviewRecovery?.(request.sessionId, request.expectedRevision, request.expectedReviewId, request.expectedPreviewId);
+            if (preflight === undefined)
+                throw domainError('git_error', '当前 SessionCheckoutModule 不支持 Preview Recovery 预检');
+            return { preflight };
+        }),
+        preparePreviewRecoveryAnalysis: request => outcome(async () => {
+            const record = await authorize(request.sessionId, request.checkoutId);
+            if (record.ownerSessionId !== request.sessionId
+                || request.recoveryProof.sessionId !== request.sessionId
+                || request.recoveryProof.checkoutId !== request.checkoutId
+                || request.recoveryProof.revision !== request.expectedRevision
+                || request.recoveryProof.reviewId !== request.expectedReviewId
+                || request.recoveryProof.previewId !== request.expectedPreviewId)
+                throw domainError('stale_target', 'Preview Recovery 分析身份不匹配');
+            const prepared = await options.module.preparePreviewRecoveryAnalysis(request.sessionId, request.recoveryProof, `preview-recovery-analysis:${randomUUID()}`);
+            const response = await mutationResponse(request.sessionId, request.checkoutId);
+            return {
+                ...response,
+                recoveryContinuation: {
+                    kind: prepared.kind,
+                    requestId: prepared.requestId,
+                    checkoutId: request.checkoutId,
+                    reviewId: prepared.reviewId,
+                    previewId: prepared.previewId,
+                    revision: prepared.revision,
+                    generation: prepared.generation,
+                },
+            };
+        }),
+        createPreviewRecoveryHandoff: request => outcome(async () => {
+            const record = await authorize(request.sessionId, request.checkoutId);
+            if (record.ownerSessionId !== request.sessionId
+                || request.recoveryProof.sessionId !== request.sessionId
+                || request.recoveryProof.checkoutId !== request.checkoutId
+                || request.recoveryProof.revision !== request.expectedRevision
+                || request.recoveryProof.reviewId !== request.expectedReviewId
+                || request.recoveryProof.previewId !== request.expectedPreviewId)
+                throw domainError('stale_target', 'Preview Recovery handoff 身份不匹配');
+            const targetSessionId = createTargetSessionId();
+            const launch = await options.module.createPreviewRecoveryHandoff(request.sessionId, request.recoveryProof, targetSessionId, `preview-recovery-handoff:${randomUUID()}`);
+            const created = recordOf(options.registry, launch.target.checkout.id);
+            const observed = await observe(created);
+            if (created.ownerSessionId !== targetSessionId
+                || created.recoveryContinuation?.kind !== 'worktree_preview_recovery_handoff'
+                || created.recoveryContinuation.requestId !== launch.continuation.requestId
+                || observed.managedRoot !== launch.managedRoot)
+                throw domainError('checkout_mismatch', 'Recovery handoff Worktree 的 Host 身份校验失败');
+            return {
+                target: projectDetails(created, targetSessionId, observed.managedRoot, observed.snapshot, observed.dirty, false),
+                targetSessionId,
+                managedRoot: launch.managedRoot,
+                recoveryContinuation: {
+                    kind: launch.continuation.kind,
+                    requestId: launch.continuation.requestId,
+                    checkoutId: created.checkoutId,
+                    sourceCheckoutId: launch.continuation.sourceCheckoutId,
+                    reviewId: launch.continuation.reviewId,
+                    previewId: launch.continuation.previewId,
+                    revision: launch.continuation.sourceRevision,
+                    generation: launch.continuation.generation,
+                },
+            };
+        }),
+        checkpoint: request => outcome(async () => {
+            const record = await authorize(request.sessionId, request.checkoutId);
+            if (record.ownerSessionId !== request.sessionId)
+                throw domainError('not_owner', '只有 owner Isolated Session 可以保存阶段');
+            const commitMessage = request.commitMessage.trim();
+            if (!commitMessage || commitMessage.length > 500 || !safeRecoveryRequestId(request.requestId)) {
+                throw domainError('invalid_input', 'Checkpoint Commit Message 或 requestId 无效');
+            }
+            const result = await options.module.operate({
+                action: 'checkpoint',
+                sessionId: request.sessionId,
+                expectedRevision: request.expectedRevision,
+                expectedReviewId: request.expectedReviewId,
+                expectedGeneration: request.expectedGeneration,
+                requestId: request.requestId,
+                commitMessage,
+            });
+            if (result.status === 'error')
+                throw domainError(result.code, result.message);
+            if (result.status === 'preview_detached') {
+                return { ...(await mutationResponse(request.sessionId, request.checkoutId)), changedFiles: [...result.changedFiles] };
+            }
+            if (result.status !== 'checkpointed')
+                throw domainError('operation_not_allowed', 'Checkpoint 返回了非预期状态');
+            const response = await mutationResponse(request.sessionId, request.checkoutId);
+            if (response.target.state !== 'working' || response.target.revision !== result.target.revision) {
+                throw domainError('checkout_mismatch', 'Checkpoint 后 Worktree 状态未收敛到 Working');
+            }
+            return { ...response, checkpoint: result.checkpoint, changedFiles: [...result.changedFiles] };
+        }),
         preview: request => outcome(async () => {
             const record = await authorize(request.sessionId, request.checkoutId);
             if (record.ownerSessionId !== request.sessionId)
@@ -398,8 +535,9 @@ export function createWorktreeConsoleControlPlane(options) {
             });
             if (result.status === 'error')
                 throw domainError(result.code, result.message);
-            if (result.status === 'conflict')
-                throw domainError('apply_conflict', 'Local Preview 预检发现内容冲突');
+            if (result.status === 'conflict') {
+                throw domainError('apply_conflict', 'Local Preview 预检发现内容冲突', applyConflictContinuation(result, review.reviewId));
+            }
             if (result.status !== 'previewed')
                 throw domainError('operation_not_allowed', 'Preview 返回了非预期状态');
             return {
@@ -416,11 +554,73 @@ export function createWorktreeConsoleControlPlane(options) {
             const review = readyReview(record);
             if (review.reviewId !== request.expectedReviewId)
                 throw domainError('stale_target', 'Review 身份已变化，请刷新');
-            const target = await options.module.resumeRevision(request.sessionId, request.expectedRevision, request.expectedReviewId);
+            const requestedRecovery = request.conflictContinuation;
+            if (requestedRecovery && (requestedRecovery.kind !== 'worktree_apply_conflict'
+                || !safeRecoveryRequestId(requestedRecovery.requestId)
+                || requestedRecovery.checkoutId !== request.checkoutId
+                || requestedRecovery.reviewId !== request.expectedReviewId
+                || requestedRecovery.revision !== request.expectedRevision
+                || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/iu.test(requestedRecovery.localHeadOid)
+                || requestedRecovery.conflictingFiles.length > 500
+                || !requestedRecovery.conflictingFiles.every(safeConflictFile)))
+                throw domainError('invalid_input', '冲突恢复请求身份无效');
+            const recovery = requestedRecovery ? {
+                kind: 'worktree_apply_conflict',
+                requestId: `conflict-recovery:${randomUUID()}`,
+                reviewId: request.expectedReviewId,
+                readyRevision: request.expectedRevision,
+                localHeadOid: requestedRecovery.localHeadOid,
+                conflictingFiles: [...requestedRecovery.conflictingFiles],
+            } : undefined;
+            const target = recovery
+                ? await options.module.resumeRevision(request.sessionId, request.expectedRevision, request.expectedReviewId, recovery)
+                : await options.module.resumeRevision(request.sessionId, request.expectedRevision, request.expectedReviewId);
             if (target.checkout.id !== request.checkoutId || target.delivery?.state !== 'working') {
                 throw domainError('checkout_mismatch', '恢复编辑后 Worktree 身份或状态不一致');
             }
-            return mutationResponse(request.sessionId, request.checkoutId);
+            const response = await mutationResponse(request.sessionId, request.checkoutId);
+            if (!requestedRecovery)
+                return response;
+            const current = recordOf(options.registry, request.checkoutId).recoveryContinuation;
+            if (!current
+                || current.kind !== 'worktree_apply_conflict'
+                || current.requestId !== recovery.requestId
+                || current.workingRevision !== response.target.revision)
+                throw domainError('checkout_mismatch', 'Host 未能持久化精确冲突恢复凭证');
+            return {
+                ...response,
+                recoveryContinuation: {
+                    kind: current.kind,
+                    requestId: current.requestId,
+                    checkoutId: request.checkoutId,
+                    reviewId: current.reviewId,
+                    revision: current.workingRevision,
+                    localHeadOid: current.localHeadOid,
+                    conflictingFiles: [...current.conflictingFiles],
+                },
+            };
+        }),
+        prepareReviewRegeneration: request => outcome(async () => {
+            const record = await authorize(request.sessionId, request.checkoutId);
+            if (record.ownerSessionId !== request.sessionId)
+                throw domainError('not_owner', '只有 owner Isolated Session 可以请求重新生成验收结果');
+            if (record.revision !== request.expectedRevision)
+                throw domainError('stale_target', 'Session Target 已变化，请刷新');
+            const review = readyReview(record);
+            if (review.reviewId !== request.expectedReviewId)
+                throw domainError('stale_target', 'Review 身份已变化，请刷新');
+            const prepared = await options.module.prepareReviewRegeneration(request.sessionId, request.expectedRevision, request.expectedReviewId, `review-regeneration:${randomUUID()}`);
+            const response = await mutationResponse(request.sessionId, request.checkoutId);
+            return {
+                ...response,
+                recoveryContinuation: {
+                    kind: prepared.kind,
+                    requestId: prepared.requestId,
+                    checkoutId: request.checkoutId,
+                    reviewId: prepared.reviewId,
+                    revision: prepared.revision,
+                },
+            };
         }),
         rollbackPreview: request => outcome(async () => {
             const record = await authorize(request.sessionId, request.checkoutId);
@@ -431,6 +631,7 @@ export function createWorktreeConsoleControlPlane(options) {
                 sessionId: request.sessionId,
                 expectedRevision: request.expectedRevision,
                 ...(request.resumeRevision === undefined ? {} : { resumeRevision: request.resumeRevision }),
+                ...(request.recoveryProof === undefined ? {} : { recoveryProof: request.recoveryProof }),
             });
             if (result.status === 'error')
                 throw domainError(result.code, result.message);
@@ -496,8 +697,9 @@ export function createWorktreeConsoleControlPlane(options) {
                 });
                 if (result.status === 'error')
                     return failure(result.code, result.message);
-                if (result.status === 'conflict')
-                    return failure('apply_conflict', 'Local 应用发生冲突');
+                if (result.status === 'conflict') {
+                    return failure('apply_conflict', 'Local 应用发生冲突', undefined, applyConflictContinuation(result, review.reviewId));
+                }
                 if (result.status !== 'finished')
                     return failure('operation_not_allowed', 'Finalize 返回了非预期状态');
                 return {
@@ -532,6 +734,7 @@ export function createWorktreeConsoleControlPlane(options) {
                     expectedRevision: request.expectedRevision,
                     commitMessage,
                     retention: request.retention,
+                    ...(request.recoveryProof === undefined ? {} : { recoveryProof: request.recoveryProof }),
                 });
                 if (result.status === 'error')
                     return failure(result.code, result.message);