dsh-git-worktree 0.1.2 → 0.2.0

package/lib/session-checkout-module.js

@@ -1,6 +1,7 @@
 import { realpathSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { SessionCheckoutError } from './index.js';
+import { createManagedWorktreePathCandidates, createManagedWorktreeRepositoryKey, } from './managed-worktree-path.js';
 const UNVERSIONED_OID = 'unversioned';
 const UNVERSIONED_REF = 'WORKING_TREE';
 const RETENTION_24H_MS = 24 * 60 * 60 * 1000;
@@ -154,6 +155,19 @@ export function createSessionCheckoutModule(dependencies) {
             return delivery;
         if (delivery.state === 'ready_for_review')
             return { state: delivery.state, review: delivery.review };
+        if (delivery.state === 'preview_active') {
+            return { state: delivery.state, review: delivery.review, previewedAt: delivery.preview.previewedAt };
+        }
+        if (delivery.state === 'preview_detached') {
+            return {
+                state: delivery.state,
+                review: delivery.review,
+                previewedAt: delivery.preview.previewedAt,
+                detachedAt: delivery.detachedAt,
+                reason: delivery.reason,
+                attemptedAction: delivery.attemptedAction,
+            };
+        }
         if (delivery.state === 'finalized') {
             return {
                 state: delivery.state,
@@ -546,6 +560,12 @@ export function createSessionCheckoutModule(dependencies) {
         }
         const { snapshot, status } = validation.checkout;
         const delivery = projectDelivery(record);
+        const activePreview = delivery?.state === 'ready_for_review'
+            ? Object.values(registry.managedCheckouts).find((candidate) => (candidate.checkoutId !== record.checkoutId
+                && candidate.phase !== 'discarded'
+                && pathsEqual(candidate.localRoot, record.localRoot)
+                && holdsProjectAcceptanceSlot(candidate)))
+            : undefined;
         return {
             project: { id: record.projectId, name: record.projectName },
             checkout: {
@@ -560,17 +580,114 @@ export function createSessionCheckoutModule(dependencies) {
             dirty: status.dirty,
             revision: record.revision,
             delivery,
+            ...(delivery?.state === 'ready_for_review'
+                ? {
+                    reviewSlot: activePreview ? 'waiting' : 'available',
+                    ...(activePreview ? { reviewSlotOwnerSessionId: activePreview.ownerSessionId } : {}),
+                }
+                : {}),
         };
     }
     function getPersistedBinding(sessionId) {
         return dependencies.registry.read().sessionBindings[sessionId];
     }
+    function runtimeContext(sessionId) {
+        const registry = dependencies.registry.read();
+        const binding = registry.sessionBindings[sessionId];
+        if (!binding)
+            return '';
+        if (binding.target.kind === 'local') {
+            const projectPreview = Object.values(registry.managedCheckouts)
+                .filter((record) => record.projectId === binding.projectId && record.phase !== 'discarded')
+                .filter((record) => record.delivery.state === 'preview_active'
+                || record.delivery.state === 'preview_detached')
+                .sort((left, right) => managedUpdatedAt(right) - managedUpdatedAt(left))[0];
+            const pending = projectPreview ?? Object.values(registry.managedCheckouts)
+                .filter((record) => record.sourceSessionId === sessionId && record.phase !== 'discarded')
+                .filter((record) => record.delivery.state === 'working'
+                || record.delivery.state === 'ready_for_review'
+                || record.delivery.state === 'preview_active'
+                || record.delivery.state === 'preview_detached'
+                || record.phase === 'preparing'
+                || record.phase === 'mutating'
+                || 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.';
+            }
+            if (pending.delivery.state === 'preview_active') {
+                return [
+                    'Session Target: Local Checkout (Worktree Preview active).',
+                    `Managed checkout ${pending.checkoutId} has a reversible Preview in this Local boundary.`,
+                    'Do not modify project files or run repository-changing commands. Only the user may accept, rollback, or discard the Preview through the Worktree acceptance UI.',
+                ].join('\n');
+            }
+            if (pending.delivery.state === 'preview_detached') {
+                return [
+                    'Session Target: Local Checkout (Worktree Preview recovery required).',
+                    `Managed checkout ${pending.checkoutId} still has preserved Preview recovery evidence.`,
+                    'Do not modify project files or attempt automatic cleanup. The user must retry rollback; the Worktree stays preserved until rollback succeeds.',
+                ].join('\n');
+            }
+            return [
+                'Session Target: Local Checkout (handoff pending).',
+                `Managed checkout ${pending.checkoutId} is reserved for Session ${pending.ownerSessionId}.`,
+                'Stop code modifications in this Local Session. Ask the user to open the isolated Session from the Worktree card.',
+            ].join('\n');
+        }
+        if (binding.target.kind !== 'isolated')
+            return 'Session Target is unselected. Do not mutate project files until a target is chosen.';
+        const record = registry.managedCheckouts[binding.target.checkoutId];
+        if (!record)
+            return 'Session Target: Isolated Checkout record missing. Stop mutations and request recovery.';
+        if (record.phase === 'recovery_required') {
+            return `Session Target: Isolated Checkout ${record.checkoutId} requires recovery. Do not modify Local or clean up automatically.`;
+        }
+        const lines = [
+            `Session Target: Isolated Checkout ${record.checkoutId}.`,
+            `Authoritative cwd: ${record.managedRoot}`,
+            `Original Local boundary: ${record.localRoot}`,
+            'Make task changes only in the authoritative cwd; never write directly to the Original Local boundary.',
+        ];
+        if (record.delivery.state === 'ready_for_review') {
+            lines.push('Delivery state: Ready for Review. The model must stop; only the user may preview, directly finish, discard, or clean up through the Worktree acceptance UI.');
+        }
+        else if (record.delivery.state === 'preview_active') {
+            lines.push('Delivery state: Local Preview active. The model must remain read-only; only the user may accept and commit, rollback, or discard through the Worktree acceptance UI.');
+        }
+        else if (record.delivery.state === 'preview_detached') {
+            lines.push('Delivery state: Preview detached after Local drift. Do not mutate Local or the Worktree; the user must retry rollback, and Discard remains blocked until recovery succeeds.');
+        }
+        else if (record.delivery.state === 'working') {
+            lines.push('Delivery state: Working. When implementation and validation are complete, put the complete report only in worktree_ready_for_review and call it as the final model tool. Do not duplicate that report in ordinary assistant prose; at most one short sentence may point the user to the bottom acceptance bar.');
+        }
+        else {
+            lines.push(`Delivery state: ${record.delivery.state}. Treat this Session as terminal unless the user starts a new iteration.`);
+        }
+        return lines.join('\n');
+    }
     async function resolveBinding(sessionId) {
         const session = requireSession(sessionId);
         const persisted = getPersistedBinding(sessionId);
         if (persisted) {
             if (session.projectId !== persisted.projectId) {
-                throw new SessionCheckoutError('project_mismatch', '会话当前项目与已绑定 Session Target 不一致，已停止访问 checkout');
+                const record = persisted.target.kind === 'isolated'
+                    ? dependencies.registry.read().managedCheckouts[persisted.target.checkoutId]
+                    : undefined;
+                const workspace = session.projectId ? dependencies.lookup.getProject(session.projectId) : undefined;
+                let isolatedWorkspaceMatches = false;
+                if (record && workspace && dependencies.files.exists(workspace.root)) {
+                    try {
+                        const workspaceRoot = await dependencies.files.canonicalize(workspace.root);
+                        isolatedWorkspaceMatches = pathsEqual(workspaceRoot, record.managedRoot);
+                    }
+                    catch {
+                        isolatedWorkspaceMatches = false;
+                    }
+                }
+                if (!isolatedWorkspaceMatches) {
+                    throw new SessionCheckoutError('project_mismatch', '会话当前 Workspace 与已绑定 Session Target 不一致，已停止访问 checkout');
+                }
             }
             return persisted;
         }
@@ -691,9 +808,109 @@ export function createSessionCheckoutModule(dependencies) {
                 continue;
             }
             if (current.phase === 'mutating'
-                && (current.journal?.operation === 'apply' || current.journal?.operation === 'finish')
+                && (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],
+                                },
+                                isolatedFingerprint: current.delivery.preview.isolatedFingerprint,
+                                finalizedAt: recoveredAt,
+                                cleanup: 'blocked',
+                                cleanupMessage: 'Commit 已创建，但进程在 Local index 完成前中断；请确认 Local 状态后再处理 Worktree。',
+                            },
+                            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],
+                                },
+                                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: 'ready',
+                        journal: null,
+                        revision: current.revision + 1,
+                    };
+                }
+                registry.managedCheckouts[checkoutId] = record;
+                registry.revision += 1;
+                changed = true;
+            }
+            else if (current.phase === 'mutating'
+                && current.journal?.operation === 'preview'
+                && (current.journal.step === 'planning'
+                    || (current.journal.step === 'writing_local' && current.delivery.state === 'ready_for_review'))) {
+                // Preview receipt 尚未保留，apply patch 也尚未执行；可证明 Local 未被触碰。
+                record = {
+                    ...current,
+                    phase: 'ready',
+                    journal: null,
+                    revision: current.revision + 1,
+                };
+                registry.managedCheckouts[checkoutId] = record;
+                registry.revision += 1;
+                changed = true;
+            }
+            else if (current.phase === 'mutating'
+                && (current.journal?.operation === 'finalize_preview' || current.journal?.operation === 'finish')
                 && current.journal.step === 'planning') {
-                // planning 阶段尚未触碰 Local，可安全重试。
+                // Finalize 的 branch/index 写入发生在 updating_ref 之后；planning 中断可安全重试。
+                record = {
+                    ...current,
+                    phase: 'ready',
+                    journal: null,
+                    revision: current.revision + 1,
+                };
+                registry.managedCheckouts[checkoutId] = record;
+                registry.revision += 1;
+                changed = true;
+            }
+            else if (current.phase === 'mutating'
+                && (current.journal?.operation === 'preview' || current.journal?.operation === 'finish')
+                && current.journal.step === 'artifacts_retained'
+                && current.delivery.state === 'preview_active') {
                 record = {
                     ...current,
                     phase: 'ready',
@@ -780,7 +997,7 @@ export function createSessionCheckoutModule(dependencies) {
         const record = dependencies.registry.read().managedCheckouts[binding.target.checkoutId];
         if (!record)
             throw new SessionCheckoutError('checkout_missing', 'Isolated Checkout 记录不存在');
-        if (record.phase !== 'ready') {
+        if (record.phase !== 'ready' || record.delivery.state === 'preview_active' || record.delivery.state === 'preview_detached') {
             throw new SessionCheckoutError('operation_not_allowed', `当前 ${record.phase}/${record.delivery.state} 状态不能准备验收`);
         }
         const inspected = await inspectIsolated(binding);
@@ -964,7 +1181,11 @@ export function createSessionCheckoutModule(dependencies) {
         return { status: 'applied', target: await inspectIsolated(binding), changedFiles: result.changedFiles };
     }
     function holdsProjectAcceptanceSlot(record) {
-        return record.journal?.operation === 'apply' || record.journal?.operation === 'finish';
+        return record.delivery.state === 'preview_active'
+            || record.journal?.operation === 'preview'
+            || record.journal?.operation === 'rollback_preview'
+            || record.journal?.operation === 'finalize_preview'
+            || record.journal?.operation === 'finish';
     }
     function findProjectAcceptanceHolder(record) {
         return Object.values(dependencies.registry.read().managedCheckouts).find((candidate) => (candidate.checkoutId !== record.checkoutId
@@ -972,6 +1193,21 @@ export function createSessionCheckoutModule(dependencies) {
             && pathsEqual(candidate.localRoot, record.localRoot)
             && holdsProjectAcceptanceSlot(candidate)));
     }
+    async function retainPreviewArtifacts(record, receipt) {
+        const prefix = `previews/${receipt.previewId}`;
+        await dependencies.git.retainInternalArtifact(record.localRoot, record.checkoutId, `${prefix}/local-working`, receipt.localWorkingTreeOid);
+        await dependencies.git.retainInternalArtifact(record.localRoot, record.checkoutId, `${prefix}/local-index`, receipt.localIndexTreeOid);
+        await dependencies.git.retainInternalArtifact(record.localRoot, record.checkoutId, `${prefix}/preview-working`, receipt.previewWorkingTreeOid);
+        await dependencies.git.retainInternalArtifact(record.localRoot, record.checkoutId, `${prefix}/isolated-snapshot`, receipt.isolatedSnapshotOid);
+    }
+    async function releasePreviewArtifactsBestEffort(record, previewId) {
+        try {
+            await dependencies.git.releaseInternalArtifacts(record.localRoot, record.checkoutId, `previews/${previewId}`);
+        }
+        catch {
+            console.warn('[session-checkout] 清理 Preview refs 失败，已保守保留不可见引用');
+        }
+    }
     function blockedPreflight(record, reason, message) {
         return {
             status: 'blocked',
@@ -1051,6 +1287,244 @@ export function createSessionCheckoutModule(dependencies) {
                 : 'ready';
         return { ...common, status };
     }
+    async function operatePreview(input, binding) {
+        if (binding.ownerSessionId !== input.sessionId || binding.target.kind !== 'isolated') {
+            return operationError('not_owner', '只有 owner Isolated 会话可以同步验收');
+        }
+        let record = dependencies.registry.read().managedCheckouts[binding.target.checkoutId];
+        if (!record)
+            return operationError('checkout_missing', 'Isolated Checkout 记录不存在');
+        if (record.revision !== input.expectedRevision) {
+            return operationError('stale_target', 'Session Target 已变化，请刷新后重试', await inspectIsolated(binding));
+        }
+        if (record.phase !== 'ready' || record.delivery.state !== 'ready_for_review') {
+            return operationError('operation_not_allowed', '当前 Worktree 尚未处于可验收状态', await inspectIsolated(binding));
+        }
+        const holder = findProjectAcceptanceHolder(record);
+        if (holder) {
+            return operationError('project_acceptance_busy', `同一项目已有验收任务正在占用 Local：${holder.projectName}`, 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.delivery.state !== 'ready_for_review') {
+            return operationError('stale_target', '验收状态已变化，请刷新后重试');
+        }
+        const review = record.delivery.review;
+        const operationId = dependencies.createCheckoutId();
+        const previewId = dependencies.createCheckoutId();
+        const startedAt = Date.now();
+        const applyBaseOid = record.applyBaseOid ?? record.baseOid;
+        const mutating = updateManagedCheckout(record.checkoutId, (current) => ({
+            ...current,
+            phase: 'mutating',
+            journal: {
+                operation: 'preview',
+                operationId,
+                step: 'planning',
+                startedAt,
+                baseOid: applyBaseOid,
+                previewId,
+                reviewId: review.reviewId,
+            },
+            revision: current.revision + 1,
+        }));
+        if (!mutating)
+            return operationError('checkout_missing', 'Isolated Checkout 记录不存在');
+        const planResult = await dependencies.applyEngine.plan({
+            baseOid: applyBaseOid,
+            isolatedPath: mutating.managedRoot,
+            localPath: mutating.localRoot,
+        });
+        if (planResult.status === 'conflict') {
+            updateManagedCheckout(mutating.checkoutId, (current) => ({ ...current, phase: 'ready', journal: null, revision: current.revision + 1 }));
+            return {
+                status: 'conflict',
+                code: 'apply_conflict',
+                reason: 'content_conflict',
+                target: await inspectIsolated(binding),
+                baseStrategy: planResult.baseStrategy,
+                effectiveBaseOid: planResult.effectiveBaseOid,
+                localHeadOid: planResult.localHeadOid,
+                isolatedHeadOid: planResult.isolatedHeadOid,
+                canRetryAfterRefresh: false,
+                conflictingFiles: planResult.conflictingFiles,
+            };
+        }
+        if (planResult.status === 'error') {
+            updateManagedCheckout(mutating.checkoutId, (current) => ({ ...current, phase: 'ready', journal: null, revision: current.revision + 1 }));
+            return operationError(planResult.error.code, planResult.error.message, await inspectIsolated(binding));
+        }
+        if (planResult.plan.isolatedFingerprint !== review.isolatedFingerprint) {
+            updateManagedCheckout(mutating.checkoutId, (current) => ({
+                ...current,
+                phase: 'ready',
+                delivery: { state: 'working', iteration: review.iteration },
+                journal: null,
+                revision: current.revision + 1,
+            }));
+            return operationError('stale_isolated', 'Worktree 在标记可验收后又发生变化，请重新准备验收', await inspectIsolated(binding));
+        }
+        updateManagedCheckout(mutating.checkoutId, (current) => ({
+            ...current,
+            journal: {
+                operation: 'preview',
+                operationId,
+                step: 'writing_local',
+                startedAt,
+                baseOid: applyBaseOid,
+                previewId,
+                reviewId: review.reviewId,
+                planRevision: planResult.plan.revision,
+                localFingerprint: planResult.plan.localFingerprint,
+                isolatedFingerprint: planResult.plan.isolatedFingerprint,
+                effectiveBaseOid: planResult.plan.effectiveBaseOid,
+                baseStrategy: planResult.plan.baseStrategy,
+                localHeadOid: planResult.plan.localHeadOid,
+                isolatedHeadOid: planResult.plan.isolatedHeadOid,
+                changedFiles: [...planResult.plan.changedFiles],
+            },
+            revision: current.revision + 1,
+        }));
+        const previewResult = await dependencies.applyEngine.preview(planResult.plan, {
+            previewId,
+            reviewId: review.reviewId,
+            iteration: review.iteration,
+            beforeWrite: async (receipt) => {
+                await retainPreviewArtifacts(mutating, receipt);
+                updateManagedCheckout(mutating.checkoutId, (current) => ({
+                    ...current,
+                    delivery: { state: 'preview_active', review, preview: receipt },
+                    journal: current.journal?.operation === 'preview'
+                        ? { ...current.journal, step: 'artifacts_retained' }
+                        : current.journal,
+                    revision: current.revision + 1,
+                }));
+            },
+        });
+        if (previewResult.status === 'error') {
+            const current = dependencies.registry.read().managedCheckouts[mutating.checkoutId];
+            const definitelyUnchanged = previewResult.error.code === 'stale_local'
+                || previewResult.error.code === 'stale_isolated'
+                || previewResult.error.code === 'invalid_plan'
+                || previewResult.error.code === 'invalid_input'
+                || current?.journal?.step === 'writing_local';
+            if (current?.journal?.step === 'writing_local')
+                await releasePreviewArtifactsBestEffort(mutating, previewId);
+            if (definitelyUnchanged || current?.journal?.step === 'artifacts_retained') {
+                updateManagedCheckout(mutating.checkoutId, (checkout) => ({ ...checkout, phase: 'ready', journal: null, revision: checkout.revision + 1 }));
+            }
+            return operationError(previewResult.error.code, previewResult.error.message, await inspectIsolated(binding));
+        }
+        const receipt = previewResult.receipt;
+        updateManagedCheckout(mutating.checkoutId, (current) => ({
+            ...current,
+            phase: 'ready',
+            delivery: { state: 'preview_active', review, preview: receipt },
+            journal: null,
+            revision: current.revision + 1,
+        }));
+        return { status: 'previewed', target: await inspectIsolated(binding), changedFiles: previewResult.changedFiles };
+    }
+    async function detachPreviewAfterLocalDrift(record, binding, reason, attemptedAction) {
+        if (record.delivery.state !== 'preview_active') {
+            return operationError('preview_not_active', '当前没有可解除的 Local Preview', await inspectIsolated(binding));
+        }
+        const { review, preview } = record.delivery;
+        const detached = updateManagedCheckout(record.checkoutId, (current) => {
+            if (current.delivery.state !== 'preview_active')
+                return current;
+            return {
+                ...current,
+                phase: 'ready',
+                delivery: {
+                    state: 'preview_detached',
+                    review: current.delivery.review,
+                    preview: current.delivery.preview,
+                    detachedAt: Date.now(),
+                    reason,
+                    attemptedAction,
+                },
+                journal: null,
+                revision: current.revision + 1,
+            };
+        });
+        if (!detached || detached.delivery.state !== 'preview_detached') {
+            return operationError('stale_target', 'Preview 状态已变化，请刷新后重试', await inspectIsolated(binding));
+        }
+        return {
+            status: 'preview_detached',
+            target: await inspectIsolated(binding),
+            changedFiles: [...preview.changedFiles],
+            reason,
+            attemptedAction,
+        };
+    }
+    async function operateRollbackPreview(input, binding) {
+        if (binding.ownerSessionId !== input.sessionId || binding.target.kind !== 'isolated') {
+            return operationError('not_owner', '只有 owner Isolated 会话可以撤回验收');
+        }
+        const record = dependencies.registry.read().managedCheckouts[binding.target.checkoutId];
+        if (!record)
+            return operationError('checkout_missing', 'Isolated Checkout 记录不存在');
+        if (record.revision !== input.expectedRevision) {
+            return operationError('stale_target', 'Session Target 已变化，请刷新后重试', await inspectIsolated(binding));
+        }
+        const retryingRecovery = record.phase === 'recovery_required'
+            && record.delivery.state === 'preview_active'
+            && record.journal?.operation === 'rollback_preview';
+        if ((record.phase !== 'ready' && !retryingRecovery)
+            || (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';
+        const resumeRevision = input.resumeRevision ?? (retryingRecovery && record.journal?.operation === 'rollback_preview'
+            ? record.journal.resumeRevision ?? false
+            : false);
+        const { preview, review } = record.delivery;
+        const operationId = dependencies.createCheckoutId();
+        const startedAt = Date.now();
+        updateManagedCheckout(record.checkoutId, (current) => ({
+            ...current,
+            phase: 'mutating',
+            journal: {
+                operation: 'rollback_preview',
+                operationId,
+                step: 'planning',
+                startedAt,
+                previewId: preview.previewId,
+                reviewId: review.reviewId,
+                resumeRevision,
+            },
+            revision: current.revision + 1,
+        }));
+        const result = await dependencies.applyEngine.rollback({ localPath: record.localRoot, receipt: preview });
+        if (result.status === 'error') {
+            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 }));
+            }
+            else if (result.error.code === 'invalid_input') {
+                updateManagedCheckout(record.checkoutId, (current) => ({ ...current, phase: 'ready', journal: null, revision: current.revision + 1 }));
+            }
+            return operationError(result.error.code, result.error.message, await inspectIsolated(binding));
+        }
+        updateManagedCheckout(record.checkoutId, (current) => ({
+            ...current,
+            phase: 'ready',
+            delivery: resumeRevision
+                ? { state: 'working', iteration: review.iteration }
+                : { state: 'ready_for_review', review },
+            journal: null,
+            revision: current.revision + 1,
+        }));
+        await releasePreviewArtifactsBestEffort(record, preview.previewId);
+        return { status: 'preview_rolled_back', target: await inspectIsolated(binding), changedFiles: result.changedFiles };
+    }
     function retainFinalized(record, retention) {
         if (record.delivery.state !== 'finalized')
             return undefined;
@@ -1254,6 +1728,100 @@ export function createSessionCheckoutModule(dependencies) {
             return { cleaned: false, message, reason };
         }
     }
+    async function operateFinalizePreview(input, binding) {
+        if (binding.ownerSessionId !== input.sessionId || binding.target.kind !== 'isolated') {
+            return operationError('not_owner', '只有 owner Isolated 会话可以完成验收提交');
+        }
+        const record = dependencies.registry.read().managedCheckouts[binding.target.checkoutId];
+        if (!record)
+            return operationError('checkout_missing', 'Isolated Checkout 记录不存在');
+        if (record.revision !== input.expectedRevision) {
+            return operationError('stale_target', 'Session Target 已变化，请刷新后重试', await inspectIsolated(binding));
+        }
+        if (record.phase !== 'ready' || record.delivery.state !== 'preview_active') {
+            return operationError('preview_not_active', '当前没有等待验收的 Local Preview', await inspectIsolated(binding));
+        }
+        // Harness plugin does not expose Domi collaborator checkout inheritance.
+        const { preview, review } = record.delivery;
+        const operationId = dependencies.createCheckoutId();
+        const startedAt = Date.now();
+        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' },
+            revision: current.revision + 1,
+        }));
+        const result = await dependencies.applyEngine.finalize({
+            localPath: record.localRoot,
+            receipt: preview,
+            commitMessage: input.commitMessage,
+            beforeCommit: async (commitOid) => {
+                updateManagedCheckout(record.checkoutId, (current) => ({
+                    ...current,
+                    journal: current.journal?.operation === 'finalize_preview'
+                        ? { ...current.journal, step: 'updating_ref', commitOid }
+                        : current.journal,
+                    revision: current.revision + 1,
+                }));
+            },
+        });
+        if (result.status === 'error') {
+            if (result.error.code === 'stale_local' || result.error.code === 'preview_modified') {
+                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 }));
+            }
+            return operationError(result.error.code, result.error.message, await inspectIsolated(binding));
+        }
+        const finalized = updateManagedCheckout(record.checkoutId, (current) => ({
+            ...current,
+            phase: 'finalized',
+            delivery: {
+                state: 'finalized',
+                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,
+                    changedFiles: [...result.changedFiles],
+                },
+                isolatedFingerprint: preview.isolatedFingerprint,
+                finalizedAt: Date.now(),
+                cleanup: 'pending',
+            },
+            journal: null,
+            revision: current.revision + 1,
+        }));
+        if (!finalized)
+            return operationError('checkout_missing', '提交已创建，但 Checkout 记录丢失');
+        const retention = input.retention ?? 'cleanup';
+        if (retention !== 'cleanup') {
+            const retained = retainFinalized(finalized, retention);
+            if (!retained)
+                return operationError('checkout_missing', '提交已创建，但保留 Worktree 状态写入失败');
+            return {
+                status: 'finished',
+                target: await inspectIsolated(binding),
+                changedFiles: result.changedFiles,
+                commitOid: result.commitOid,
+                cleanup: 'retained',
+            };
+        }
+        const cleanup = await cleanupFinalized(finalized);
+        return {
+            status: 'finished',
+            target: await inspectIsolated(binding),
+            changedFiles: result.changedFiles,
+            commitOid: result.commitOid,
+            cleanup: cleanup.cleaned ? 'discarded' : 'pending',
+            ...(cleanup.message ? { cleanupMessage: cleanup.message } : {}),
+            ...(cleanup.reason ? { cleanupReason: cleanup.reason } : {}),
+        };
+    }
     async function operateRetryCleanup(input, binding) {
         if (binding.ownerSessionId !== input.sessionId || binding.target.kind !== 'isolated') {
             return operationError('not_owner', '只有 owner Isolated 会话可以重试清理');
@@ -1291,7 +1859,14 @@ export function createSessionCheckoutModule(dependencies) {
         if (record.revision !== input.expectedRevision) {
             return operationError('stale_target', 'Session Target 已变化，请刷新后重试', await inspectIsolated(binding));
         }
-        if (record.phase !== 'ready') {
+        if (input.expectedReviewId !== undefined && (record.delivery.state !== 'ready_for_review'
+            || record.delivery.review.reviewId !== input.expectedReviewId)) {
+            return operationError('stale_target', '该验收卡已不是当前 Review，请刷新并确认最新交付', await inspectIsolated(binding));
+        }
+        if (record.applyBaseOid && (record.delivery.state === 'working' || record.delivery.state === 'ready_for_review')) {
+            return operationError('operation_not_allowed', '该历史 Worktree 已通过旧版 Apply 写入 Local；为避免遗漏或重复提交，已禁止自动 Finish，请先人工核对 Local 后再清理记录。', await inspectIsolated(binding));
+        }
+        if (record.phase !== 'ready' || record.delivery.state === 'preview_active' || record.delivery.state === 'preview_detached') {
             return operationError('operation_not_allowed', `当前 ${record.phase}/${record.delivery.state} 状态不能直接 Finish`, await inspectIsolated(binding));
         }
         const holder = findProjectAcceptanceHolder(record);
@@ -1357,6 +1932,21 @@ export function createSessionCheckoutModule(dependencies) {
             }));
             return operationError(planResult.error.code, planResult.error.message, await inspectIsolated(binding));
         }
+        if (input.expectedReviewId !== undefined
+            && applying.delivery.state === 'ready_for_review'
+            && (applying.delivery.review.reviewId !== input.expectedReviewId
+                || planResult.plan.isolatedFingerprint !== applying.delivery.review.isolatedFingerprint
+                || planResult.plan.isolatedHeadOid !== applying.delivery.review.isolatedHeadOid)) {
+            const reviewIteration = applying.delivery.review.iteration;
+            updateManagedCheckout(applying.checkoutId, (current) => ({
+                ...current,
+                phase: 'ready',
+                delivery: { state: 'working', iteration: reviewIteration },
+                journal: null,
+                revision: current.revision + 1,
+            }));
+            return operationError('stale_isolated', 'Worktree 在验收后又发生变化，请重新准备验收', await inspectIsolated(binding));
+        }
         const iteration = applying.delivery.state === 'working'
             ? applying.delivery.iteration
             : applying.delivery.state === 'delivered'
@@ -1376,6 +1966,7 @@ export function createSessionCheckoutModule(dependencies) {
                 isolatedFingerprint: planResult.plan.isolatedFingerprint,
                 isolatedHeadOid: planResult.plan.isolatedHeadOid,
             };
+        const previewId = dependencies.createCheckoutId();
         updateManagedCheckout(applying.checkoutId, (current) => ({
             ...current,
             delivery: { state: 'ready_for_review', review },
@@ -1396,38 +1987,89 @@ export function createSessionCheckoutModule(dependencies) {
             },
             revision: current.revision + 1,
         }));
-        const finishResult = await dependencies.applyEngine.finish(planResult.plan, {
+        const previewResult = await dependencies.applyEngine.preview(planResult.plan, {
+            previewId,
+            reviewId: review.reviewId,
+            iteration: review.iteration,
+            beforeWrite: async (receipt) => {
+                await retainPreviewArtifacts(applying, receipt);
+                updateManagedCheckout(applying.checkoutId, (current) => ({
+                    ...current,
+                    delivery: { state: 'preview_active', review, preview: receipt },
+                    journal: current.journal?.operation === 'finish'
+                        ? { ...current.journal, step: 'artifacts_retained', previewId, reviewId: review.reviewId }
+                        : current.journal,
+                    revision: current.revision + 1,
+                }));
+            },
+        });
+        if (previewResult.status === 'error') {
+            const current = dependencies.registry.read().managedCheckouts[applying.checkoutId];
+            if (current?.journal?.step === 'writing_local') {
+                await releasePreviewArtifactsBestEffort(applying, previewId);
+                updateManagedCheckout(applying.checkoutId, (checkout) => ({ ...checkout, phase: 'ready', journal: null, revision: checkout.revision + 1 }));
+            }
+            return operationError(previewResult.error.code, previewResult.error.message, await inspectIsolated(binding));
+        }
+        const receipt = previewResult.receipt;
+        updateManagedCheckout(applying.checkoutId, (current) => ({
+            ...current,
+            phase: 'mutating',
+            delivery: { state: 'preview_active', review, preview: receipt },
+            journal: {
+                operation: 'finish',
+                operationId,
+                step: 'planning',
+                startedAt,
+                previewId,
+                reviewId: review.reviewId,
+                isolatedFingerprint: receipt.isolatedFingerprint,
+                retention: input.retention ?? 'cleanup',
+                changedFiles: [...receipt.changedFiles],
+            },
+            revision: current.revision + 1,
+        }));
+        const finishResult = await dependencies.applyEngine.finalize({
+            localPath: applying.localRoot,
+            receipt,
             commitMessage: input.commitMessage,
+            beforeCommit: async (commitOid) => {
+                updateManagedCheckout(applying.checkoutId, (current) => ({
+                    ...current,
+                    journal: current.journal?.operation === 'finish'
+                        ? { ...current.journal, step: 'updating_ref', commitOid }
+                        : current.journal,
+                    revision: current.revision + 1,
+                }));
+            },
         });
         if (finishResult.status === 'error') {
-            if (finishResult.error.code === 'invalid_plan'
-                || finishResult.error.code === 'stale_local'
-                || finishResult.error.code === 'stale_isolated'
+            const safePreview = finishResult.error.code === 'stale_local'
+                || finishResult.error.code === 'preview_modified'
                 || finishResult.error.code === 'invalid_input'
-                || finishResult.error.code === 'operation_not_allowed'
-                || finishResult.error.code === 'commit_isolation_conflict') {
-                // 这些错误码可证明未触碰 Local，恢复 ready；git_error 交由 reconcile 兜底 recovery_required。
+                || finishResult.error.code === 'commit_isolation_conflict'
+                || finishResult.error.code === 'operation_not_allowed';
+            if (safePreview) {
                 updateManagedCheckout(applying.checkoutId, (current) => ({ ...current, phase: 'ready', journal: null, revision: current.revision + 1 }));
             }
             return operationError(finishResult.error.code, finishResult.error.message, await inspectIsolated(binding));
         }
         const finalized = updateManagedCheckout(applying.checkoutId, (current) => ({
             ...current,
-            applyBaseOid: finishResult.nextBaseOid,
             phase: 'finalized',
             delivery: {
                 state: 'finalized',
                 review,
                 commitOid: finishResult.commitOid,
                 proof: {
-                    localBranch: planResult.plan.localHeadRef?.startsWith('refs/heads/')
-                        ? planResult.plan.localHeadRef.slice('refs/heads/'.length)
+                    localBranch: receipt.localHeadRef?.startsWith('refs/heads/')
+                        ? receipt.localHeadRef.slice('refs/heads/'.length)
                         : null,
-                    localHeadBefore: planResult.plan.localHeadOid,
-                    localHeadAfter: finishResult.commitOid ?? planResult.plan.localHeadOid,
+                    localHeadBefore: receipt.localHeadOid,
+                    localHeadAfter: finishResult.commitOid ?? receipt.localHeadOid,
                     changedFiles: [...finishResult.changedFiles],
                 },
-                isolatedFingerprint: planResult.plan.isolatedFingerprint,
+                isolatedFingerprint: receipt.isolatedFingerprint,
                 finalizedAt: Date.now(),
                 cleanup: 'pending',
             },
@@ -1484,6 +2126,40 @@ export function createSessionCheckoutModule(dependencies) {
         if (record.revision !== input.expectedRevision) {
             return operationError('stale_target', 'Session Target 已变化，请刷新后重试', await inspectIsolated(binding));
         }
+        if (record.delivery.state === 'preview_detached') {
+            return operationError('preview_modified', 'Local Preview 已因漂移进入 detached 恢复态；为保留恢复证据，不能删除 Worktree。请先成功撤回 Preview。', await inspectIsolated(binding));
+        }
+        if (record.applyBaseOid && (record.delivery.state === 'working' || record.delivery.state === 'ready_for_review')) {
+            return operationError('operation_not_allowed', '该历史 Worktree 已通过旧版 Apply 写入 Local；不会自动 Discard，请先人工核对 Local 的未提交修改。', await inspectIsolated(binding));
+        }
+        if (record.delivery.state === 'preview_active') {
+            if (!input.rollbackPreview) {
+                return operationError('preview_not_active', 'Local 正在验收本任务；放弃任务前必须先安全撤回 Preview', await inspectIsolated(binding));
+            }
+            const rollback = await dependencies.applyEngine.rollback({
+                localPath: record.localRoot,
+                receipt: record.delivery.preview,
+            });
+            if (rollback.status === 'error') {
+                if (rollback.error.code === 'stale_local' || rollback.error.code === 'preview_modified') {
+                    return detachPreviewAfterLocalDrift(record, binding, rollback.error.code, 'discard');
+                }
+                return operationError(rollback.error.code, rollback.error.message, await inspectIsolated(binding));
+            }
+            const previewId = record.delivery.preview.previewId;
+            const iteration = record.delivery.review.iteration;
+            const rolledBack = updateManagedCheckout(record.checkoutId, (current) => ({
+                ...current,
+                delivery: { state: 'working', iteration },
+                journal: null,
+                revision: current.revision + 1,
+            }));
+            if (!rolledBack)
+                return operationError('checkout_missing', 'Isolated Checkout 记录不存在');
+            await releasePreviewArtifactsBestEffort(record, previewId);
+            record = rolledBack;
+        }
+        // Harness plugin has no inherited collaborator checkout ownership.
         if (record.phase === 'recovery_required' && !dependencies.files.exists(record.managedRoot)) {
             await releaseApplyBaseBestEffort(record);
             updateManagedCheckout(record.checkoutId, (current) => ({
@@ -1579,6 +2255,12 @@ export function createSessionCheckoutModule(dependencies) {
                 return await operateApply(input, binding);
             if (input.action === 'finish')
                 return await operateFinish(input, binding);
+            if (input.action === 'preview')
+                return await operatePreview(input, binding);
+            if (input.action === 'rollback_preview')
+                return await operateRollbackPreview(input, binding);
+            if (input.action === 'finalize_preview')
+                return await operateFinalizePreview(input, binding);
             if (input.action === 'retry_cleanup')
                 return await operateRetryCleanup(input, binding);
             if (input.action === 'discard')
@@ -1604,6 +2286,10 @@ export function createSessionCheckoutModule(dependencies) {
             return record.journal?.startedAt ?? 0;
         if (record.delivery.state === 'ready_for_review')
             return record.delivery.review.preparedAt;
+        if (record.delivery.state === 'preview_active')
+            return record.delivery.preview.previewedAt;
+        if (record.delivery.state === 'preview_detached')
+            return record.delivery.detachedAt;
         if (record.delivery.state === 'finalized')
             return record.delivery.finalizedAt;
         if (record.delivery.state === 'retained')
@@ -1664,11 +2350,15 @@ export function createSessionCheckoutModule(dependencies) {
                 ? delivery.cleanup === 'blocked' ? 'needs_attention' : 'retained'
                 : delivery.state === 'finalized'
                     ? delivery.cleanup === 'blocked' ? 'needs_attention' : 'cleanup_pending'
-                    : delivery.state === 'ready_for_review'
-                        ? 'ready_for_review'
-                        : delivery.state === 'delivered'
-                            ? 'delivered'
-                            : 'working';
+                    : delivery.state === 'preview_active'
+                        ? 'preview_active'
+                        : delivery.state === 'preview_detached'
+                            ? 'needs_attention'
+                            : delivery.state === 'ready_for_review'
+                                ? 'ready_for_review'
+                                : delivery.state === 'delivered'
+                                    ? 'delivered'
+                                    : 'working';
         const commitOid = delivery.state === 'finalized' || delivery.state === 'retained' || delivery.state === 'delivered'
             ? delivery.commitOid
             : null;
@@ -1709,6 +2399,9 @@ export function createSessionCheckoutModule(dependencies) {
             return cleanupBlocked('working', '当前轮次仍在修改，尚未形成可清理的交付环境。', record.revision);
         if (record.delivery.state === 'ready_for_review')
             return cleanupBlocked('review_pending', '当前轮次正在等待验收，不能清理。', record.revision);
+        if (record.delivery.state === 'preview_active' || record.delivery.state === 'preview_detached') {
+            return cleanupBlocked('preview_active', 'Local Preview 尚未完成安全收口，不能清理。', record.revision);
+        }
         if (record.delivery.state === 'delivered' || record.phase === 'discarded') {
             return cleanupBlocked('unknown', 'Worktree 已交付并解除管理，无需再次清理。', record.revision);
         }
@@ -1835,6 +2528,37 @@ export function createSessionCheckoutModule(dependencies) {
             .filter((summary) => !input.needsAttention || summary.state === 'needs_attention' || summary.state === 'cleanup_pending')
             .sort((left, right) => right.updatedAt - left.updatedAt);
     }
+    async function listManagedWorktreesForSession(sessionId, input = {}) {
+        const session = requireSession(sessionId);
+        const persisted = getPersistedBinding(sessionId);
+        const projectId = persisted?.projectId ?? session.projectId;
+        if (!projectId)
+            throw new SessionCheckoutError('project_not_found', '会话尚未关联项目');
+        const allowedCheckoutIds = new Set(Object.values(dependencies.registry.read().managedCheckouts)
+            .filter((record) => record.projectId === projectId)
+            .filter((record) => record.ownerSessionId === sessionId || record.sourceSessionId === sessionId)
+            .map((record) => record.checkoutId));
+        const summaries = await listManagedWorktrees({ ...input, projectId });
+        return summaries.filter((summary) => allowedCheckoutIds.has(summary.checkoutId));
+    }
+    async function manageManagedWorktreeForSession(sessionId, input) {
+        requireSession(sessionId);
+        const record = dependencies.registry.read().managedCheckouts[input.checkoutId];
+        if (!record)
+            throw new SessionCheckoutError('checkout_missing', 'Worktree 记录不存在');
+        if (record.ownerSessionId !== sessionId && record.sourceSessionId !== sessionId) {
+            throw new SessionCheckoutError('not_owner', '当前 Session 无权管理该 Worktree');
+        }
+        if (record.ownerSessionId !== sessionId && dependencies.lookup.getSession(record.ownerSessionId)) {
+            throw new SessionCheckoutError('not_owner', 'Owner Session 已接管该 Worktree，只有 owner 可以管理');
+        }
+        const persisted = getPersistedBinding(sessionId);
+        const callerProjectId = persisted?.projectId ?? dependencies.lookup.getSession(sessionId)?.projectId;
+        if (callerProjectId !== record.projectId) {
+            throw new SessionCheckoutError('project_mismatch', '当前 Session 与 Worktree 不属于同一原始项目');
+        }
+        return manageManagedWorktree(input);
+    }
     async function manageManagedWorktree(input) {
         const record = dependencies.registry.read().managedCheckouts[input.checkoutId];
         if (!record)
@@ -1842,12 +2566,15 @@ export function createSessionCheckoutModule(dependencies) {
         if (record.revision !== input.expectedRevision)
             throw new SessionCheckoutError('stale_target', 'Worktree 状态已变化，请刷新后重试');
         if (input.action === 'discard') {
-            const result = await operateTarget({
+            // Caller authorization is performed by the scoped wrapper (or a trusted Host manager).
+            // The reserved owner Session may not exist yet, so do not re-resolve it through lookup.
+            const result = await operateDiscard({
                 action: 'discard',
                 sessionId: record.ownerSessionId,
                 expectedRevision: input.expectedRevision,
                 confirmDirty: input.confirmDirty === true,
-            });
+                ...(input.rollbackPreview === undefined ? {} : { rollbackPreview: input.rollbackPreview }),
+            }, bindingForManagedRecord(record));
             if (result.status === 'error')
                 throw new SessionCheckoutError(result.code, result.message);
             const updated = dependencies.registry.read().managedCheckouts[record.checkoutId];
@@ -1918,8 +2645,8 @@ export function createSessionCheckoutModule(dependencies) {
         }
         return cleaned;
     }
-    async function bindTarget(sessionId, choice, createAttempt = 0, requestStartedAt = Date.now()) {
-        const session = requireSession(sessionId);
+    async function bindTarget(sessionId, choice, createAttempt = 0, requestStartedAt = Date.now(), sourceSessionId = sessionId) {
+        const session = requireSession(sourceSessionId);
         let nextIteration = 1;
         let replacedDeliveredBinding;
         const existing = getPersistedBinding(sessionId);
@@ -1953,7 +2680,7 @@ export function createSessionCheckoutModule(dependencies) {
                 throw new SessionCheckoutError('target_already_bound', '会话已经绑定 Session Target，不能切换');
             }
         }
-        const { project } = await resolveSessionProject(sessionId);
+        const { project } = await resolveSessionProject(sourceSessionId);
         const snapshot = await dependencies.git.inspect(project.root);
         if (choice.kind === 'local') {
             const binding = {
@@ -1979,9 +2706,75 @@ export function createSessionCheckoutModule(dependencies) {
         const checkoutId = dependencies.createCheckoutId();
         const localRoot = await dependencies.files.canonicalize(project.root);
         const localGitRoot = await dependencies.files.canonicalize(snapshot.root);
-        // DSH workspace-write 沙箱只允许项目根目录内写入，worktree 必须放在仓库内部。
-        const managedGitRoot = join(localGitRoot, '.dsh-worktrees');
-        dependencies.files.ensureDirectory(dirname(managedGitRoot));
+        const repositoryKey = createManagedWorktreeRepositoryKey(localGitRoot);
+        const pathCandidates = [8, 12, 32].map(identityLength => createManagedWorktreePathCandidates({
+            localGitRoot,
+            managedCheckoutsRoot: dependencies.managedCheckoutsRoot,
+            repositoryKey,
+            checkoutId,
+            identityLength,
+        }));
+        // Prefer one repository-owned sibling container so Local never sees its
+        // managed worktrees as untracked. A container that is a file/symlink is
+        // untrusted and falls back without modification. Existing child paths
+        // are never reused or cleaned: extend the trusted checkout identity.
+        const outerContainingRoot = await dependencies.git.findContainingWorktreeRoot(dirname(localGitRoot));
+        const siblingWouldPolluteOuter = outerContainingRoot !== null && !pathsEqual(outerContainingRoot, localGitRoot);
+        const usingSibling = createAttempt === 0 && !siblingWouldPolluteOuter;
+        const managedContainer = usingSibling
+            ? pathCandidates[0].siblingContainer
+            : pathCandidates[0].fallbackContainer;
+        const knownContainer = Object.values(dependencies.registry.read().managedCheckouts)
+            .some(record => pathsEqual(dirname(record.managedGitRoot), managedContainer));
+        const containerExisted = dependencies.files.exists(managedContainer);
+        let containerIdentity = containerExisted
+            ? await dependencies.files.inspectDirectoryIdentity(managedContainer)
+            : null;
+        if (containerExisted && containerIdentity !== null && !knownContainer) {
+            // A same-named directory with unknown content is not ours. An empty
+            // directory has no user bytes to preserve, so remove/recreate it as the
+            // ownership boundary; a non-empty tree is left untouched and rejected.
+            let reclaimedEmpty = false;
+            try {
+                reclaimedEmpty = dependencies.files.removeEmptyDirectoryTree(managedContainer);
+            }
+            catch { /* fail closed below */ }
+            if (!reclaimedEmpty)
+                containerIdentity = null;
+            else {
+                try {
+                    dependencies.files.ensureDirectory(managedContainer);
+                    containerIdentity = await dependencies.files.inspectDirectoryIdentity(managedContainer);
+                }
+                catch {
+                    containerIdentity = null;
+                }
+            }
+        }
+        else if (!containerExisted) {
+            try {
+                dependencies.files.ensureDirectory(managedContainer);
+                containerIdentity = await dependencies.files.inspectDirectoryIdentity(managedContainer);
+            }
+            catch {
+                containerIdentity = null;
+            }
+        }
+        if (containerIdentity === null) {
+            if (usingSibling) {
+                return bindTarget(sessionId, choice, createAttempt + 1, requestStartedAt, sourceSessionId);
+            }
+            throw new SessionCheckoutError('checkout_mismatch', 'Worktree 回退容器不是可信目录，未创建或修改任何 checkout');
+        }
+        const managedGitRoot = pathCandidates
+            .map(candidate => usingSibling ? candidate.siblingRoot : candidate.fallbackRoot)
+            .find(candidate => !dependencies.files.exists(candidate));
+        if (managedGitRoot === undefined) {
+            if (usingSibling) {
+                return bindTarget(sessionId, choice, createAttempt + 1, requestStartedAt, sourceSessionId);
+            }
+            throw new SessionCheckoutError('checkout_mismatch', 'Worktree Checkout identity 路径均已存在，拒绝覆盖未知目录');
+        }
         const projectRelativePath = relative(localGitRoot, localRoot);
         if (projectRelativePath.startsWith('..') || isAbsolute(projectRelativePath)) {
             throw new SessionCheckoutError('checkout_mismatch', '项目根目录不在其 Git checkout 内');
@@ -1992,6 +2785,7 @@ export function createSessionCheckoutModule(dependencies) {
             projectId: project.id,
             projectName: project.name,
             ownerSessionId: sessionId,
+            sourceSessionId,
             localRoot,
             managedRoot: resolve(managedRoot),
             managedGitRoot: resolve(managedGitRoot),
@@ -2090,19 +2884,43 @@ export function createSessionCheckoutModule(dependencies) {
             failedRegistry.revision += 1;
             dependencies.registry.write(failedRegistry);
             if (createAttempt < 1) {
-                return bindTarget(sessionId, choice, createAttempt + 1, requestStartedAt);
+                return bindTarget(sessionId, choice, createAttempt + 1, requestStartedAt, sourceSessionId);
             }
             throw new SessionCheckoutError('git_operation_failed', 'Worktree 创建失败，已安全清理残余目录，可直接重试');
         }
     }
     return {
         inspect: inspectAvailable,
+        runtimeContext,
         preflight: (sessionId, expectedRevision) => withBindingLock(() => preflightTarget(sessionId, expectedRevision)),
         runExclusiveSessionMutation: (sessionId, operation) => withBindingLock(async () => (operation(await inspectTarget(sessionId, true)))),
         bind: (sessionId, choice) => {
             const requestStartedAt = Date.now();
             return withBindingLock(() => bindTarget(sessionId, choice, 0, requestStartedAt));
         },
+        createIsolatedTarget: (sourceSessionId, targetSessionId) => withBindingLock(async () => {
+            if (!targetSessionId || targetSessionId === sourceSessionId) {
+                throw new SessionCheckoutError('invalid_input', 'Isolated Target 必须使用独立的预分配 Session ID');
+            }
+            if (dependencies.lookup.getSession(targetSessionId) && !getPersistedBinding(targetSessionId)) {
+                throw new SessionCheckoutError('target_already_bound', '目标 Session ID 已被其他 Workspace 使用');
+            }
+            const sourceBinding = getPersistedBinding(sourceSessionId);
+            if (!sourceBinding) {
+                await bindTarget(sourceSessionId, { kind: 'local' });
+            }
+            else if (sourceBinding.target.kind !== 'local') {
+                throw new SessionCheckoutError('operation_not_allowed', '只能从 Local Session 创建新的 Isolated Target');
+            }
+            const target = await bindTarget(targetSessionId, { kind: 'isolated' }, 0, Date.now(), sourceSessionId);
+            const binding = getPersistedBinding(targetSessionId);
+            const record = binding?.target.kind === 'isolated'
+                ? dependencies.registry.read().managedCheckouts[binding.target.checkoutId]
+                : undefined;
+            if (!record)
+                throw new SessionCheckoutError('checkout_missing', 'Isolated Target 创建后记录缺失');
+            return { targetSessionId, managedRoot: record.managedRoot, target };
+        }),
         beginNextIteration: (sessionId) => {
             const requestStartedAt = Date.now();
             return withBindingLock(() => bindTarget(sessionId, { kind: 'isolated' }, 0, requestStartedAt));
@@ -2111,6 +2929,8 @@ export function createSessionCheckoutModule(dependencies) {
         operate: (input) => withBindingLock(() => operateTarget(input)),
         // 只读管理列表不占用全局 mutation lock；慢速目录诊断与用户操作互不阻塞。
         listManagedWorktrees,
+        listManagedWorktreesForSession,
+        manageManagedWorktreeForSession: (sessionId, input) => withBindingLock(() => manageManagedWorktreeForSession(sessionId, input)),
         inspectManagedWorktreeCleanup,
         bulkCleanupManagedWorktrees: (candidates) => withBindingLock(() => bulkCleanupManagedWorktrees(candidates)),
         manageManagedWorktree: (input) => withBindingLock(() => manageManagedWorktree(input)),