dsh-git-worktree 0.1.0

package/lib/session-checkout-module.js

@@ -0,0 +1,2122 @@
+import { realpathSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { SessionCheckoutError } from './index.js';
+const UNVERSIONED_OID = 'unversioned';
+const UNVERSIONED_REF = 'WORKING_TREE';
+const RETENTION_24H_MS = 24 * 60 * 60 * 1000;
+const RETENTION_3D_MS = 3 * RETENTION_24H_MS;
+const CLEANUP_IDENTITY_CHANGED_MESSAGE = 'Worktree 的 Git 身份或路径已变化，未执行清理。';
+const CLEANUP_RESIDUE_MESSAGE = 'Git Worktree 已解除注册，仅剩物理目录残余；可重试清理环境。';
+const TRANSIENT_CLEANUP_RETRY_DELAYS_MS = [100, 300, 800];
+/**
+ * 单个 checkout 清理/维护操作的启动收敛超时。
+ * Windows 上 Worktree 被外部进程（如残留 Agent 运行）占用时，git/fs 操作可能无限期挂起；
+ * 启动收敛必须在有限时间内继续，不能因为一个损坏记录卡住整个应用启动。
+ */
+const CHECKOUT_CLEANUP_TIMEOUT_MS = 30_000;
+async function withCleanupTimeout(checkoutId, operation) {
+    let timeoutHandle;
+    try {
+        return await Promise.race([
+            operation(),
+            new Promise((resolve) => {
+                timeoutHandle = setTimeout(() => {
+                    console.warn(`[session-checkout] ${checkoutId.slice(0, 8)} 清理超时（${CHECKOUT_CLEANUP_TIMEOUT_MS}ms），已跳过本次收敛`);
+                    resolve(null);
+                }, CHECKOUT_CLEANUP_TIMEOUT_MS);
+            }),
+        ]);
+    }
+    finally {
+        if (timeoutHandle)
+            clearTimeout(timeoutHandle);
+    }
+}
+function cleanupReasonForMessage(message) {
+    if (message.includes('提交后出现了新修改'))
+        return 'modified_after_finalize';
+    if (message.includes('解除注册') || message.includes('目录残余'))
+        return 'detached_residue';
+    if (message.includes('quarantine'))
+        return 'quarantine_busy';
+    if (message.includes('身份') || message.includes('记录') || message.includes('Local index'))
+        return 'identity_changed';
+    return 'directory_busy';
+}
+function isTransientCleanupError(error) {
+    const code = typeof error === 'object' && error !== null && 'code' in error
+        ? String(error.code ?? '')
+        : '';
+    const message = error instanceof Error ? error.message : String(error);
+    return /^(EBUSY|EPERM|EACCES|ENOTEMPTY)$/i.test(code)
+        || /EBUSY|EPERM|EACCES|ENOTEMPTY|being used|access is denied|permission denied/i.test(message);
+}
+async function retryTransientCleanup(operation) {
+    let lastError;
+    for (let attempt = 0; attempt <= TRANSIENT_CLEANUP_RETRY_DELAYS_MS.length; attempt += 1) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error;
+            if (!isTransientCleanupError(error) || attempt === TRANSIENT_CLEANUP_RETRY_DELAYS_MS.length)
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, TRANSIENT_CLEANUP_RETRY_DELAYS_MS[attempt] ?? 0));
+        }
+    }
+    throw lastError;
+}
+function retentionExpiresAt(mode, retainedAt) {
+    if (mode === 'retain_24h')
+        return retainedAt + RETENTION_24H_MS;
+    if (mode === 'retain_3d')
+        return retainedAt + RETENTION_3D_MS;
+    return null;
+}
+function pathForIdentity(path) {
+    try {
+        return realpathSync.native(resolve(path)).replace(/\\/g, '/');
+    }
+    catch {
+        return resolve(path).replace(/\\/g, '/');
+    }
+}
+function pathsEqual(left, right) {
+    const normalizedLeft = pathForIdentity(left);
+    const normalizedRight = pathForIdentity(right);
+    return process.platform === 'win32'
+        ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+        : normalizedLeft === normalizedRight;
+}
+/** canonical 路径与 registry 原始路径比较时不得再次 realpath，否则 Junction 会冒充原目录。 */
+function resolvedPathsEqual(left, right) {
+    const normalizedLeft = resolve(left).replace(/\\/g, '/');
+    const normalizedRight = resolve(right).replace(/\\/g, '/');
+    return process.platform === 'win32'
+        ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+        : normalizedLeft === normalizedRight;
+}
+export function createSessionCheckoutModule(dependencies) {
+    function requireSession(sessionId) {
+        const session = dependencies.lookup.getSession(sessionId);
+        if (!session)
+            throw new SessionCheckoutError('session_not_found', `会话不存在: ${sessionId}`);
+        return session;
+    }
+    async function resolveSessionProject(sessionId) {
+        const session = requireSession(sessionId);
+        if (!session.projectId)
+            throw new SessionCheckoutError('project_not_found', '会话尚未关联项目');
+        const project = dependencies.lookup.getProject(session.projectId);
+        if (!project)
+            throw new SessionCheckoutError('project_not_found', `项目不存在: ${session.projectId}`);
+        if (!dependencies.files.exists(project.root)) {
+            throw new SessionCheckoutError('project_root_missing', `项目根目录不存在: ${project.name}`);
+        }
+        return { session, project };
+    }
+    async function inspectLocal(binding) {
+        const project = dependencies.lookup.getProject(binding.projectId);
+        if (!project || !dependencies.files.exists(project.root))
+            return recoveryView(binding);
+        const snapshot = await dependencies.git.inspect(project.root);
+        const current = snapshot
+            ? { branch: snapshot.branch, oid: snapshot.headOid }
+            : { branch: null, oid: UNVERSIONED_OID };
+        const status = snapshot ? await dependencies.git.status(project.root) : { dirty: false };
+        return {
+            project: { id: binding.projectId, name: project.name },
+            checkout: {
+                id: `local:${binding.projectId}`,
+                kind: 'local',
+                label: 'Local Checkout',
+                phase: 'ready',
+            },
+            source: { ref: binding.sourceRef, oid: binding.sourceOid },
+            current,
+            ownership: binding.inheritedFromSessionId ? 'inherited' : 'owner',
+            dirty: status.dirty,
+            revision: binding.revision,
+        };
+    }
+    function projectDelivery(record, commitInLocalHistory = null) {
+        const delivery = record.delivery;
+        const projectProof = (proof) => proof
+            ? {
+                localBranch: proof.localBranch,
+                localHeadBefore: proof.localHeadBefore,
+                localHeadAfter: proof.localHeadAfter,
+                changedFiles: [...proof.changedFiles],
+                commitInLocalHistory,
+            }
+            : undefined;
+        if (delivery.state === 'working')
+            return delivery;
+        if (delivery.state === 'ready_for_review')
+            return { state: delivery.state, review: delivery.review };
+        if (delivery.state === 'finalized') {
+            return {
+                state: delivery.state,
+                review: delivery.review,
+                commitOid: delivery.commitOid,
+                ...(projectProof(delivery.proof) ? { proof: projectProof(delivery.proof) } : {}),
+                cleanup: delivery.cleanup,
+                ...(delivery.cleanupMessage ? { cleanupMessage: delivery.cleanupMessage } : {}),
+            };
+        }
+        if (delivery.state === 'retained') {
+            return {
+                state: delivery.state,
+                review: delivery.review,
+                commitOid: delivery.commitOid,
+                ...(projectProof(delivery.proof) ? { proof: projectProof(delivery.proof) } : {}),
+                retention: delivery.retention,
+                retainedAt: delivery.retainedAt,
+                expiresAt: delivery.expiresAt,
+                cleanup: delivery.cleanup,
+                ...(delivery.cleanupMessage ? { cleanupMessage: delivery.cleanupMessage } : {}),
+            };
+        }
+        if (delivery.state === 'delivered') {
+            const deliveredProof = projectProof(delivery.proof);
+            return {
+                state: delivery.state,
+                iteration: delivery.iteration,
+                commitOid: delivery.commitOid,
+                deliveredAt: delivery.deliveredAt,
+                ...(deliveredProof ? { proof: deliveredProof } : {}),
+            };
+        }
+        return delivery;
+    }
+    function bindingForManagedRecord(record) {
+        const persisted = dependencies.registry.read().sessionBindings[record.ownerSessionId];
+        if (persisted?.target.kind === 'isolated' && persisted.target.checkoutId === record.checkoutId)
+            return persisted;
+        return {
+            sessionId: record.ownerSessionId,
+            projectId: record.projectId,
+            projectName: record.projectName,
+            target: { kind: 'isolated', checkoutId: record.checkoutId },
+            ownerSessionId: record.ownerSessionId,
+            sourceRef: record.sourceRef,
+            sourceOid: record.baseOid,
+            revision: record.revision,
+        };
+    }
+    function recoveryView(binding, record, dirty = false) {
+        const phase = record?.phase === 'discarded' ? 'discarded' : 'recovery_required';
+        return {
+            project: { id: binding.projectId, name: binding.projectName },
+            checkout: {
+                id: record?.checkoutId ?? (binding.target.kind === 'isolated' ? binding.target.checkoutId : `local:${binding.projectId}`),
+                kind: binding.target.kind === 'isolated' ? 'isolated' : 'local',
+                label: binding.target.kind === 'isolated' ? 'Isolated Checkout' : 'Local Checkout',
+                phase,
+            },
+            source: { ref: binding.sourceRef, oid: binding.sourceOid },
+            current: { branch: null, oid: binding.sourceOid },
+            ownership: binding.inheritedFromSessionId ? 'inherited' : 'owner',
+            dirty,
+            revision: record?.revision ?? binding.revision,
+            ...(record ? { delivery: projectDelivery(record) } : {}),
+        };
+    }
+    async function validateCommittedLocalCheckout(binding, record) {
+        if (binding.target.kind !== 'isolated'
+            || binding.target.checkoutId !== record.checkoutId
+            || binding.projectId !== record.projectId
+            || binding.ownerSessionId !== record.ownerSessionId)
+            return undefined;
+        try {
+            const project = dependencies.lookup.getProject(record.projectId);
+            if (!project || !dependencies.files.exists(project.root) || !dependencies.files.exists(record.localRoot))
+                return undefined;
+            const canonicalProjectRoot = await dependencies.files.canonicalize(project.root);
+            const canonicalLocalRoot = await dependencies.files.canonicalize(record.localRoot);
+            if (!pathsEqual(canonicalProjectRoot, canonicalLocalRoot))
+                return undefined;
+            const snapshot = await dependencies.git.inspect(canonicalLocalRoot);
+            if (!snapshot || !pathsEqual(snapshot.commonDir, record.gitCommonDir))
+                return undefined;
+            return { canonicalLocalRoot, snapshot };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async function committedFollowupView(binding, record) {
+        if (record.delivery.state !== 'finalized'
+            && record.delivery.state !== 'retained'
+            && record.delivery.state !== 'delivered')
+            return recoveryView(binding, record, true);
+        const local = await validateCommittedLocalCheckout(binding, record);
+        if (!local)
+            return recoveryView(binding, record, true);
+        const localSnapshot = local.snapshot;
+        let commitInLocalHistory = null;
+        if (record.delivery.commitOid) {
+            try {
+                commitInLocalHistory = await dependencies.git.isAncestor(local.canonicalLocalRoot, record.delivery.commitOid, localSnapshot.headOid);
+            }
+            catch {
+                commitInLocalHistory = null;
+            }
+        }
+        const delivery = projectDelivery(record, commitInLocalHistory);
+        if (!delivery || (delivery.state !== 'finalized' && delivery.state !== 'retained' && delivery.state !== 'delivered')) {
+            return recoveryView(binding, record, true);
+        }
+        return {
+            project: { id: record.projectId, name: record.projectName },
+            checkout: {
+                id: record.checkoutId,
+                kind: 'isolated',
+                label: 'Isolated Checkout',
+                // Commit 已是权威交付事实；残余环境异常只能影响 cleanup，不能降级整个会话。
+                phase: delivery.state === 'retained' ? 'retained' : delivery.state === 'delivered' ? 'discarded' : 'finalized',
+            },
+            source: { ref: record.sourceRef, oid: record.baseOid },
+            current: {
+                branch: localSnapshot.branch,
+                oid: localSnapshot.headOid,
+            },
+            ownership: binding.inheritedFromSessionId ? 'inherited' : 'owner',
+            dirty: true,
+            revision: record.revision,
+            delivery,
+        };
+    }
+    function markRecoveryRequired(record) {
+        if (record.phase === 'recovery_required' || record.phase === 'discarded')
+            return record;
+        const registry = dependencies.registry.read();
+        const current = registry.managedCheckouts[record.checkoutId];
+        if (!current)
+            return record;
+        if (current.revision !== record.revision || current.phase !== record.phase)
+            return current;
+        const recovered = {
+            ...current,
+            phase: 'recovery_required',
+            revision: current.revision + 1,
+        };
+        registry.managedCheckouts[record.checkoutId] = recovered;
+        registry.revision += 1;
+        dependencies.registry.write(registry);
+        return recovered;
+    }
+    async function validateManagedCheckoutDetailed(binding, record, requireCreateBase) {
+        if (binding.target.kind !== 'isolated'
+            || binding.target.checkoutId !== record.checkoutId
+            || binding.projectId !== record.projectId
+            || binding.ownerSessionId !== record.ownerSessionId
+            || !dependencies.files.exists(record.managedRoot))
+            return { status: 'invalid' };
+        try {
+            const canonicalManagedRoot = await dependencies.files.canonicalize(record.managedRoot);
+            const canonicalManagedGitRoot = await dependencies.files.canonicalize(record.managedGitRoot);
+            const canonicalLocalRoot = await dependencies.files.canonicalize(record.localRoot);
+            const project = dependencies.lookup.getProject(record.projectId);
+            if (project) {
+                if (!dependencies.files.exists(project.root))
+                    return { status: 'invalid' };
+                const canonicalProjectRoot = await dependencies.files.canonicalize(project.root);
+                if (!pathsEqual(canonicalProjectRoot, canonicalLocalRoot))
+                    return { status: 'invalid' };
+            }
+            const snapshot = await dependencies.git.inspect(canonicalManagedRoot);
+            const localSnapshot = await dependencies.git.inspect(canonicalLocalRoot);
+            if (!snapshot || !localSnapshot)
+                return { status: 'invalid' };
+            const projectRelativePath = relative(localSnapshot.root, canonicalLocalRoot);
+            if (projectRelativePath.startsWith('..')
+                || isAbsolute(projectRelativePath)
+                || !resolvedPathsEqual(canonicalManagedRoot, record.managedRoot)
+                || !resolvedPathsEqual(canonicalManagedGitRoot, record.managedGitRoot)
+                || !resolvedPathsEqual(canonicalLocalRoot, record.localRoot)
+                || !pathsEqual(snapshot.root, canonicalManagedGitRoot)
+                || !pathsEqual(snapshot.commonDir, record.gitCommonDir)
+                || !pathsEqual(localSnapshot.commonDir, record.gitCommonDir)
+                || !pathsEqual(resolve(snapshot.root, projectRelativePath), canonicalManagedRoot)
+                || (!requireCreateBase && !pathsEqual(snapshot.gitDir, record.gitDir))
+                || (requireCreateBase && snapshot.headOid !== record.baseOid))
+                return { status: 'invalid' };
+            const status = await dependencies.git.status(canonicalManagedRoot);
+            return {
+                status: 'valid',
+                checkout: { canonicalManagedRoot, canonicalManagedGitRoot, snapshot, status },
+            };
+        }
+        catch {
+            // Git 子进程超时、杀毒软件占用等瞬时 I/O 故障不能永久污染健康 Worktree。
+            return { status: 'unavailable' };
+        }
+    }
+    async function validateManagedCheckout(binding, record, requireCreateBase) {
+        const result = await validateManagedCheckoutDetailed(binding, record, requireCreateBase);
+        return result.status === 'valid' ? result.checkout : undefined;
+    }
+    function directoryIdentitiesEqual(left, right) {
+        return left.device === right.device && left.inode === right.inode && left.birthtimeNs === right.birthtimeNs;
+    }
+    function hasCleanupRemovalReceipt(record) {
+        return record.journal?.operation === 'cleanup'
+            && record.journal.step === 'removing_worktree'
+            && record.journal.managedDirectoryIdentity !== undefined;
+    }
+    function hasLegacyCleanupResidueEvidence(record) {
+        if (record.journal !== null)
+            return false;
+        if (record.delivery.state !== 'finalized' && record.delivery.state !== 'retained')
+            return false;
+        if (record.delivery.cleanup !== 'blocked')
+            return false;
+        if (record.delivery.cleanupMessage !== CLEANUP_IDENTITY_CHANGED_MESSAGE)
+            return false;
+        const checkoutIdentity = record.checkoutId.replace(/[^a-zA-Z0-9]/g, '').slice(0, 8);
+        return checkoutIdentity.length > 0 && basename(record.managedGitRoot).endsWith(`--${checkoutIdentity}`);
+    }
+    async function validateCleanupLocalIdentity(record) {
+        if (!dependencies.files.exists(record.localRoot))
+            return undefined;
+        const project = dependencies.lookup.getProject(record.projectId);
+        if (!project || !dependencies.files.exists(project.root))
+            return undefined;
+        try {
+            const canonicalLocalRoot = await dependencies.files.canonicalize(record.localRoot);
+            const canonicalProjectRoot = await dependencies.files.canonicalize(project.root);
+            if (!resolvedPathsEqual(canonicalLocalRoot, record.localRoot) || !pathsEqual(canonicalProjectRoot, canonicalLocalRoot))
+                return undefined;
+            const localSnapshot = await dependencies.git.inspect(canonicalLocalRoot);
+            if (!localSnapshot || !pathsEqual(localSnapshot.commonDir, record.gitCommonDir))
+                return undefined;
+            const projectRelativePath = relative(localSnapshot.root, canonicalLocalRoot);
+            if (projectRelativePath.startsWith('..') || isAbsolute(projectRelativePath))
+                return undefined;
+            return localSnapshot;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async function validateDetachedCleanupResidue(record, allowLegacyResidue = false) {
+        if (record.delivery.state !== 'finalized' && record.delivery.state !== 'retained')
+            return undefined;
+        const receipt = hasCleanupRemovalReceipt(record);
+        const legacy = allowLegacyResidue && hasLegacyCleanupResidueEvidence(record);
+        if (!receipt && !legacy)
+            return undefined;
+        if (!dependencies.files.exists(record.managedGitRoot) || dependencies.files.exists(record.gitDir))
+            return undefined;
+        try {
+            const localSnapshot = await validateCleanupLocalIdentity(record);
+            if (!localSnapshot)
+                return undefined;
+            const canonicalManagedGitRoot = await dependencies.files.canonicalize(record.managedGitRoot);
+            if (!resolvedPathsEqual(canonicalManagedGitRoot, record.managedGitRoot))
+                return undefined;
+            const projectRelativePath = relative(localSnapshot.root, record.localRoot);
+            const expectedManagedRoot = resolve(canonicalManagedGitRoot, projectRelativePath);
+            if (!pathsEqual(expectedManagedRoot, record.managedRoot))
+                return undefined;
+            if (dependencies.files.exists(record.managedRoot)) {
+                const canonicalManagedRoot = await dependencies.files.canonicalize(record.managedRoot);
+                if (!resolvedPathsEqual(canonicalManagedRoot, record.managedRoot) || !pathsEqual(canonicalManagedRoot, expectedManagedRoot))
+                    return undefined;
+            }
+            const managedSnapshot = await dependencies.git.inspect(canonicalManagedGitRoot);
+            if (managedSnapshot)
+                return undefined;
+            const containingWorktreeRoot = await dependencies.git.findContainingWorktreeRoot(canonicalManagedGitRoot);
+            if (containingWorktreeRoot)
+                return undefined;
+            const directoryIdentity = await dependencies.files.inspectDirectoryIdentity(canonicalManagedGitRoot);
+            if (!directoryIdentity)
+                return undefined;
+            const expectedIdentity = record.journal?.operation === 'cleanup'
+                ? record.journal.managedDirectoryIdentity
+                : undefined;
+            if (expectedIdentity && !directoryIdentitiesEqual(directoryIdentity, expectedIdentity))
+                return undefined;
+            return { canonicalManagedGitRoot, directoryIdentity };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async function validateCleanupQuarantine(record) {
+        const journal = record.journal?.operation === 'cleanup' ? record.journal : undefined;
+        const quarantinePath = journal?.cleanupQuarantinePath;
+        const expectedIdentity = journal?.managedDirectoryIdentity;
+        if (!quarantinePath || !expectedIdentity || !dependencies.files.exists(quarantinePath))
+            return undefined;
+        const expectedName = `.dsh-wt-cleanup--${record.checkoutId.replace(/[^a-zA-Z0-9]/g, '').slice(0, 8)}--${journal.operationId}`;
+        if (!resolvedPathsEqual(dirname(quarantinePath), dirname(record.managedGitRoot)) || basename(quarantinePath) !== expectedName)
+            return undefined;
+        try {
+            if (!await validateCleanupLocalIdentity(record))
+                return undefined;
+            const canonicalQuarantinePath = await dependencies.files.canonicalize(quarantinePath);
+            if (!resolvedPathsEqual(canonicalQuarantinePath, quarantinePath))
+                return undefined;
+            const identity = await dependencies.files.inspectDirectoryIdentity(canonicalQuarantinePath);
+            if (!identity || !directoryIdentitiesEqual(identity, expectedIdentity))
+                return undefined;
+            return canonicalQuarantinePath;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async function inspectIsolated(binding, persistRecovery = true) {
+        if (binding.target.kind !== 'isolated')
+            return recoveryView(binding);
+        const registry = dependencies.registry.read();
+        let record = registry.managedCheckouts[binding.target.checkoutId];
+        if (!record)
+            return recoveryView(binding);
+        if (record.projectId !== binding.projectId
+            || record.ownerSessionId !== binding.ownerSessionId) {
+            if (persistRecovery)
+                record = markRecoveryRequired(record);
+            return recoveryView(binding, record);
+        }
+        if (record.phase === 'discarded') {
+            if (record.delivery.state === 'delivered')
+                return committedFollowupView(binding, record);
+            return {
+                ...recoveryView(binding, record),
+                checkout: {
+                    id: record.checkoutId,
+                    kind: 'isolated',
+                    label: 'Isolated Checkout',
+                    phase: 'discarded',
+                },
+            };
+        }
+        let prefetchedValidation;
+        if (record.phase === 'recovery_required'
+            && record.journal === null
+            && dependencies.files.exists(record.managedRoot)) {
+            const recoveryValidation = await validateManagedCheckoutDetailed(binding, record, false);
+            if (recoveryValidation.status === 'valid' && persistRecovery) {
+                const restored = updateManagedCheckout(record.checkoutId, (current) => ({
+                    ...current,
+                    managedRoot: recoveryValidation.checkout.canonicalManagedRoot,
+                    managedGitRoot: recoveryValidation.checkout.canonicalManagedGitRoot,
+                    gitDir: recoveryValidation.checkout.snapshot.gitDir,
+                    phase: 'ready',
+                    revision: current.revision + 1,
+                }));
+                if (restored) {
+                    record = restored;
+                    prefetchedValidation = recoveryValidation.checkout;
+                }
+            }
+        }
+        if ((record.phase !== 'ready' && record.phase !== 'finalized' && record.phase !== 'retained') || !dependencies.files.exists(record.managedRoot)) {
+            if (record.delivery.state === 'finalized' || record.delivery.state === 'retained') {
+                return committedFollowupView(binding, record);
+            }
+            if (persistRecovery)
+                record = markRecoveryRequired(record);
+            let dirty = false;
+            if (dependencies.files.exists(record.managedRoot)) {
+                try {
+                    dirty = (await dependencies.git.status(record.managedRoot)).dirty;
+                }
+                catch {
+                    dirty = true;
+                }
+            }
+            return recoveryView(binding, record, dirty);
+        }
+        const validation = prefetchedValidation
+            ? { status: 'valid', checkout: prefetchedValidation }
+            : await validateManagedCheckoutDetailed(binding, record, false);
+        if (validation.status !== 'valid') {
+            if (record.delivery.state === 'finalized' || record.delivery.state === 'retained') {
+                return committedFollowupView(binding, record);
+            }
+            // 只有确定的身份/路径不匹配才持久进入 recovery；瞬时 Git/I/O 故障允许下一次 inspect 直接重试。
+            if (persistRecovery && validation.status === 'invalid')
+                record = markRecoveryRequired(record);
+            return recoveryView(binding, record);
+        }
+        const { snapshot, status } = validation.checkout;
+        const delivery = projectDelivery(record);
+        return {
+            project: { id: record.projectId, name: record.projectName },
+            checkout: {
+                id: record.checkoutId,
+                kind: 'isolated',
+                label: 'Isolated Checkout',
+                phase: record.phase,
+            },
+            source: { ref: record.sourceRef, oid: record.baseOid },
+            current: { branch: snapshot.branch, oid: snapshot.headOid },
+            ownership: binding.inheritedFromSessionId ? 'inherited' : 'owner',
+            dirty: status.dirty,
+            revision: record.revision,
+            delivery,
+        };
+    }
+    function getPersistedBinding(sessionId) {
+        return dependencies.registry.read().sessionBindings[sessionId];
+    }
+    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');
+            }
+            return persisted;
+        }
+        throw new SessionCheckoutError('target_unselected', '会话尚未选择 Session Target');
+    }
+    let bindingQueue = Promise.resolve();
+    let activeBindingOperation = null;
+    let activeBindingOperationDone = Promise.resolve();
+    let pendingMaintenanceOperations = 0;
+    let maintenanceReady;
+    let signalMaintenanceReady = () => undefined;
+    let activeMaintenanceInspects = 0;
+    let maintenanceInspectsDrained = Promise.resolve();
+    let signalMaintenanceInspectsDrained = () => undefined;
+    function prepareMaintenanceReadySignal() {
+        maintenanceReady = new Promise((resolveReady) => { signalMaintenanceReady = resolveReady; });
+    }
+    function beginMaintenanceInspect() {
+        if (activeMaintenanceInspects === 0) {
+            maintenanceInspectsDrained = new Promise((resolveDrained) => {
+                signalMaintenanceInspectsDrained = resolveDrained;
+            });
+        }
+        activeMaintenanceInspects += 1;
+    }
+    function finishMaintenanceInspect() {
+        activeMaintenanceInspects -= 1;
+        if (activeMaintenanceInspects === 0)
+            signalMaintenanceInspectsDrained();
+    }
+    async function withBindingLock(operation, options = {}) {
+        const maintenance = options.allowConcurrentInspect === true;
+        if (maintenance) {
+            pendingMaintenanceOperations += 1;
+            if (pendingMaintenanceOperations === 1)
+                prepareMaintenanceReadySignal();
+        }
+        const previous = bindingQueue;
+        let release = () => undefined;
+        bindingQueue = new Promise((resolveLock) => { release = resolveLock; });
+        await previous.catch(() => undefined);
+        let signalOperationDone = () => undefined;
+        activeBindingOperationDone = new Promise((resolveDone) => { signalOperationDone = resolveDone; });
+        activeBindingOperation = maintenance ? 'maintenance' : 'exclusive';
+        if (maintenance)
+            signalMaintenanceReady();
+        try {
+            return await operation();
+        }
+        finally {
+            if (maintenance) {
+                // 先关闭新的只读旁路，再等待已启动 inspect 结束，之后 mutation 才能接管队列。
+                activeBindingOperation = 'maintenance_draining';
+                if (activeMaintenanceInspects > 0)
+                    await maintenanceInspectsDrained;
+                pendingMaintenanceOperations -= 1;
+                if (pendingMaintenanceOperations > 0)
+                    prepareMaintenanceReadySignal();
+                else
+                    maintenanceReady = undefined;
+            }
+            activeBindingOperation = null;
+            signalOperationDone();
+            release();
+        }
+    }
+    async function inspectTarget(sessionId, persistRecovery = true) {
+        const binding = await resolveBinding(sessionId);
+        if (binding.target.kind === 'local')
+            return inspectLocal(binding);
+        return inspectIsolated(binding, persistRecovery);
+    }
+    async function inspectDuringMaintenance(sessionId) {
+        if (activeBindingOperation !== 'maintenance')
+            return inspectAvailable(sessionId);
+        beginMaintenanceInspect();
+        try {
+            // 后台 reconcile/retention cleanup 可能因 Windows 文件占用持续数十秒。
+            // 此时 inspect 只读取权威快照，不写 registry，避免一个历史 Worktree 阻塞所有会话。
+            return await inspectTarget(sessionId, false);
+        }
+        finally {
+            finishMaintenanceInspect();
+        }
+    }
+    async function inspectAvailable(sessionId) {
+        while (true) {
+            if (activeBindingOperation === 'maintenance')
+                return inspectDuringMaintenance(sessionId);
+            if (activeBindingOperation === 'maintenance_draining') {
+                const operationDone = activeBindingOperationDone;
+                await operationDone.catch(() => undefined);
+                continue;
+            }
+            if (pendingMaintenanceOperations > 0 && maintenanceReady) {
+                // maintenance 可能排在当前交互操作之后；等它真正取得锁后再走只读旁路，
+                // 避免 inspect 被预先排到 maintenance 后面，也避免与当前交互 mutation 并发。
+                await maintenanceReady;
+                continue;
+            }
+            return withBindingLock(() => inspectTarget(sessionId, true));
+        }
+    }
+    async function reconcile() {
+        const registry = dependencies.registry.read();
+        const recoveryRequiredCheckoutIds = [];
+        const orphanedCheckoutIds = [];
+        const dirtyOrphanedCheckoutIds = [];
+        const finalizedCheckoutIds = [];
+        let changed = false;
+        for (const [checkoutId, current] of Object.entries(registry.managedCheckouts)) {
+            if (current.phase === 'discarded')
+                continue;
+            let record = current;
+            if (current.delivery.state === 'finalized') {
+                // 兼容旧版本曾把 cleanup 残余错误持久化为 recovery_required；Commit 事实优先，继续收口资源即可。
+                finalizedCheckoutIds.push(checkoutId);
+                continue;
+            }
+            if (current.phase === 'mutating'
+                && (current.journal?.operation === 'apply' || current.journal?.operation === 'finish')
+                && current.journal.step === 'planning') {
+                // planning 阶段尚未触碰 Local，可安全重试。
+                record = {
+                    ...current,
+                    phase: 'ready',
+                    journal: null,
+                    revision: current.revision + 1,
+                };
+                registry.managedCheckouts[checkoutId] = record;
+                registry.revision += 1;
+                changed = true;
+            }
+            else if (current.phase === 'preparing' || current.phase === 'mutating') {
+                record = {
+                    ...current,
+                    phase: 'recovery_required',
+                    revision: current.revision + 1,
+                };
+                registry.managedCheckouts[checkoutId] = record;
+                registry.revision += 1;
+                recoveryRequiredCheckoutIds.push(checkoutId);
+                changed = true;
+            }
+            else if (current.phase === 'recovery_required') {
+                recoveryRequiredCheckoutIds.push(checkoutId);
+            }
+            if (dependencies.lookup.getSession(record.ownerSessionId))
+                continue;
+            orphanedCheckoutIds.push(checkoutId);
+            let dirty = true;
+            if (dependencies.files.exists(record.managedRoot)) {
+                try {
+                    dirty = (await dependencies.git.status(record.managedRoot)).dirty;
+                }
+                catch {
+                    dirty = true;
+                }
+            }
+            if (dirty)
+                dirtyOrphanedCheckoutIds.push(checkoutId);
+        }
+        if (changed)
+            dependencies.registry.write(registry);
+        for (const checkoutId of finalizedCheckoutIds) {
+            const current = dependencies.registry.read().managedCheckouts[checkoutId];
+            if (current?.delivery.state === 'finalized') {
+                // 启动收敛不受单个卡死记录阻塞：超时后跳过，下次启动再试。
+                await withCleanupTimeout(checkoutId, () => cleanupFinalized(current));
+            }
+        }
+        await cleanupExpiredRetained();
+        const currentRegistry = dependencies.registry.read();
+        return {
+            recoveryRequiredCheckoutIds,
+            orphanedCheckoutIds,
+            dirtyOrphanedCheckoutIds,
+            retainedCheckoutCount: Object.values(currentRegistry.managedCheckouts)
+                .filter((record) => record.phase !== 'discarded')
+                .length,
+        };
+    }
+    function operationError(code, message, target) {
+        return { status: 'error', code, message, ...(target ? { target } : {}) };
+    }
+    function updateManagedCheckout(checkoutId, update) {
+        const registry = dependencies.registry.read();
+        const current = registry.managedCheckouts[checkoutId];
+        if (!current)
+            return undefined;
+        const next = update(current);
+        registry.managedCheckouts[checkoutId] = next;
+        registry.revision += 1;
+        dependencies.registry.write(registry);
+        return next;
+    }
+    async function markReadyForReviewTarget(sessionId, input) {
+        const binding = await resolveBinding(sessionId);
+        if (binding.ownerSessionId !== sessionId || binding.target.kind !== 'isolated') {
+            throw new SessionCheckoutError('not_owner', '只有 owner Isolated 会话可以准备验收');
+        }
+        const summary = input.summary.trim();
+        const suggestedCommitMessage = input.suggestedCommitMessage.trim();
+        if (!summary || !suggestedCommitMessage || input.tests.length > 20) {
+            throw new SessionCheckoutError('invalid_input', '验收摘要、提交信息或验证项目无效');
+        }
+        const record = dependencies.registry.read().managedCheckouts[binding.target.checkoutId];
+        if (!record)
+            throw new SessionCheckoutError('checkout_missing', 'Isolated Checkout 记录不存在');
+        if (record.phase !== 'ready') {
+            throw new SessionCheckoutError('operation_not_allowed', `当前 ${record.phase}/${record.delivery.state} 状态不能准备验收`);
+        }
+        const inspected = await inspectIsolated(binding);
+        if (inspected.checkout.phase !== 'ready') {
+            throw new SessionCheckoutError('recovery_required', 'Isolated Checkout 身份无法确认，需要恢复');
+        }
+        const snapshot = await dependencies.applyEngine.inspectReview({
+            baseOid: record.applyBaseOid ?? record.baseOid,
+            isolatedPath: record.managedRoot,
+            localPath: record.localRoot,
+        });
+        if (snapshot.status === 'error') {
+            throw new SessionCheckoutError(snapshot.error.code, snapshot.error.message);
+        }
+        const reviewId = dependencies.createCheckoutId();
+        updateManagedCheckout(record.checkoutId, (current) => ({
+            ...current,
+            delivery: {
+                state: 'ready_for_review',
+                review: {
+                    reviewId,
+                    iteration: current.delivery.state === 'working'
+                        ? current.delivery.iteration
+                        : current.delivery.state === 'delivered'
+                            ? current.delivery.iteration + 1
+                            : current.delivery.review.iteration,
+                    preparedAt: Date.now(),
+                    ...(input.detailsMarkdown?.trim() ? { detailsMarkdown: input.detailsMarkdown.trim() } : {}),
+                    summary,
+                    validationStatus: input.validationStatus,
+                    ...(input.validationSummary?.trim() ? { validationSummary: input.validationSummary.trim() } : {}),
+                    tests: input.tests.map((test) => ({
+                        command: test.command.trim(),
+                        status: test.status,
+                        ...(test.summary?.trim() ? { summary: test.summary.trim() } : {}),
+                    })),
+                    changedFiles: [...snapshot.changedFiles],
+                    suggestedCommitMessage,
+                    isolatedFingerprint: snapshot.isolatedFingerprint,
+                    isolatedHeadOid: snapshot.isolatedHeadOid,
+                },
+            },
+            revision: current.revision + 1,
+        }));
+        return inspectIsolated(binding);
+    }
+    async function operateApply(input, binding) {
+        if (binding.ownerSessionId !== input.sessionId) {
+            return operationError('not_owner', '继承 Session Target 的会话不能执行 Apply');
+        }
+        if (binding.target.kind !== 'isolated') {
+            return operationError('operation_not_allowed', 'Local Checkout 不支持 Apply');
+        }
+        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') {
+            return operationError('operation_not_allowed', `当前 ${record.phase}/${record.delivery.state} 状态不能 Apply`, 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.phase !== 'ready') {
+            return operationError('recovery_required', 'Isolated Checkout 状态已变化，需要恢复');
+        }
+        const startedAt = Date.now();
+        const operationId = dependencies.createCheckoutId();
+        const applyBaseOid = record.applyBaseOid ?? record.baseOid;
+        const applying = updateManagedCheckout(record.checkoutId, (current) => ({
+            ...current,
+            phase: 'mutating',
+            journal: { operation: 'apply', operationId, step: 'planning', startedAt, baseOid: applyBaseOid },
+            revision: current.revision + 1,
+        }));
+        if (!applying)
+            return operationError('checkout_missing', 'Isolated Checkout 记录不存在');
+        const planResult = await dependencies.applyEngine.plan({
+            baseOid: applyBaseOid,
+            isolatedPath: applying.managedRoot,
+            localPath: applying.localRoot,
+        });
+        if (planResult.status === 'conflict') {
+            updateManagedCheckout(applying.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(applying.checkoutId, (current) => ({ ...current, phase: 'ready', journal: null, revision: current.revision + 1 }));
+            return operationError(planResult.error.code, planResult.error.message, await inspectIsolated(binding));
+        }
+        if (applying.delivery.state === 'ready_for_review'
+            && planResult.plan.isolatedFingerprint !== applying.delivery.review.isolatedFingerprint) {
+            updateManagedCheckout(applying.checkoutId, (current) => ({
+                ...current,
+                phase: 'ready',
+                delivery: { state: 'working', iteration: applying.delivery.state === 'ready_for_review' ? applying.delivery.review.iteration : 1 },
+                journal: null,
+                revision: current.revision + 1,
+            }));
+            return operationError('stale_isolated', 'Worktree 在标记可验收后又发生变化，请重新准备验收', await inspectIsolated(binding));
+        }
+        if (planResult.plan.changedFiles.length === 0) {
+            updateManagedCheckout(applying.checkoutId, (current) => ({ ...current, phase: 'ready', journal: null, revision: current.revision + 1 }));
+            return { status: 'applied', target: await inspectIsolated(binding), changedFiles: [] };
+        }
+        const iteration = applying.delivery.state === 'working'
+            ? applying.delivery.iteration
+            : applying.delivery.state === 'delivered'
+                ? applying.delivery.iteration + 1
+                : applying.delivery.review.iteration;
+        const review = applying.delivery.state === 'ready_for_review'
+            ? applying.delivery.review
+            : {
+                reviewId: operationId,
+                iteration,
+                preparedAt: startedAt,
+                summary: 'Worktree 修改已通过 ApplyWorktree 同步到 Local 验收',
+                validationStatus: 'not_run',
+                tests: [],
+                changedFiles: [...planResult.plan.changedFiles],
+                suggestedCommitMessage: 'chore: 提交 Worktree 修改',
+                isolatedFingerprint: planResult.plan.isolatedFingerprint,
+                isolatedHeadOid: planResult.plan.isolatedHeadOid,
+            };
+        updateManagedCheckout(applying.checkoutId, (current) => ({
+            ...current,
+            delivery: { state: 'ready_for_review', review },
+            journal: {
+                operation: 'apply',
+                operationId,
+                step: 'writing_local',
+                startedAt,
+                baseOid: applyBaseOid,
+                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 result = await dependencies.applyEngine.apply(planResult.plan);
+        if (result.status === 'error') {
+            if (result.error.code === 'invalid_plan'
+                || result.error.code === 'stale_local'
+                || result.error.code === 'stale_isolated') {
+                // 这些错误码可证明未触碰 Local，恢复 ready；git_error 交由 reconcile 兜底 recovery_required。
+                updateManagedCheckout(applying.checkoutId, (checkout) => ({ ...checkout, phase: 'ready', journal: null, revision: checkout.revision + 1 }));
+            }
+            return operationError(result.error.code, result.error.message, await inspectIsolated(binding));
+        }
+        updateManagedCheckout(applying.checkoutId, (current) => ({
+            ...current,
+            applyBaseOid: result.nextBaseOid,
+            phase: 'ready',
+            journal: null,
+            revision: current.revision + 1,
+        }));
+        return { status: 'applied', target: await inspectIsolated(binding), changedFiles: result.changedFiles };
+    }
+    function holdsProjectAcceptanceSlot(record) {
+        return record.journal?.operation === 'apply' || record.journal?.operation === 'finish';
+    }
+    function findProjectAcceptanceHolder(record) {
+        return Object.values(dependencies.registry.read().managedCheckouts).find((candidate) => (candidate.checkoutId !== record.checkoutId
+            && candidate.phase !== 'discarded'
+            && pathsEqual(candidate.localRoot, record.localRoot)
+            && holdsProjectAcceptanceSlot(candidate)));
+    }
+    function blockedPreflight(record, reason, message) {
+        return {
+            status: 'blocked',
+            localModified: false,
+            checkoutId: record?.checkoutId ?? '',
+            reviewId: record?.delivery.state === 'ready_for_review' ? record.delivery.review.reviewId : null,
+            revision: record?.revision ?? 0,
+            reason,
+            message,
+        };
+    }
+    async function preflightTarget(sessionId, expectedRevision) {
+        const binding = await resolveBinding(sessionId);
+        if (binding.ownerSessionId !== sessionId || binding.target.kind !== 'isolated') {
+            return blockedPreflight(undefined, 'not_owner', '只有 owner Isolated 会话可以执行同步预检');
+        }
+        const record = dependencies.registry.read().managedCheckouts[binding.target.checkoutId];
+        if (!record)
+            return blockedPreflight(undefined, 'checkout_unavailable', 'Isolated Checkout 记录不存在');
+        if (record.revision !== expectedRevision) {
+            return blockedPreflight(record, 'stale_target', 'Session Target 已变化，请刷新后重新预检');
+        }
+        if (record.phase !== 'ready' || record.delivery.state !== 'ready_for_review') {
+            return blockedPreflight(record, 'not_ready_for_review', '当前 Worktree 尚未处于可验收状态');
+        }
+        if (findProjectAcceptanceHolder(record)) {
+            return blockedPreflight(record, 'project_acceptance_busy', '另一个任务正在占用该项目的 Local 验收槽位');
+        }
+        const validated = await validateManagedCheckoutDetailed(binding, record, false);
+        if (validated.status !== 'valid') {
+            return blockedPreflight(record, 'checkout_unavailable', 'Worktree 身份、路径或 Git 状态暂时无法确认');
+        }
+        const review = record.delivery.review;
+        const result = await dependencies.applyEngine.preflight({
+            baseOid: record.applyBaseOid ?? record.baseOid,
+            isolatedPath: validated.checkout.canonicalManagedRoot,
+            localPath: record.localRoot,
+        });
+        const current = dependencies.registry.read().managedCheckouts[record.checkoutId];
+        if (!current
+            || current.revision !== expectedRevision
+            || current.delivery.state !== 'ready_for_review'
+            || current.delivery.review.reviewId !== review.reviewId)
+            return blockedPreflight(current, 'stale_target', 'Session Target 在预检期间发生变化，请刷新后重试');
+        if (result.status === 'error') {
+            return blockedPreflight(current, result.error.code === 'stale_isolated' ? 'stale_isolated' : 'git_error', result.error.message);
+        }
+        const isolatedFingerprint = result.status === 'ready'
+            ? result.plan.isolatedFingerprint
+            : result.isolatedFingerprint;
+        if (isolatedFingerprint !== review.isolatedFingerprint) {
+            return blockedPreflight(current, 'stale_isolated', 'Worktree 在准备验收后发生变化，请重新生成验收结果');
+        }
+        const localBranch = result.status === 'ready' && result.plan.localHeadRef?.startsWith('refs/heads/')
+            ? result.plan.localHeadRef.slice('refs/heads/'.length)
+            : validated.checkout.snapshot.branch;
+        const common = {
+            localModified: false,
+            checkoutId: record.checkoutId,
+            reviewId: review.reviewId,
+            revision: expectedRevision,
+            configuredBaseOid: record.baseOid,
+            effectiveBaseOid: result.status === 'ready' ? result.plan.effectiveBaseOid : result.effectiveBaseOid,
+            baseStrategy: result.status === 'ready' ? result.plan.baseStrategy : result.baseStrategy,
+            localBranch,
+            localHeadOid: result.status === 'ready' ? result.plan.localHeadOid : result.localHeadOid,
+            isolatedHeadOid: result.status === 'ready' ? result.plan.isolatedHeadOid : result.isolatedHeadOid,
+            changedFiles: result.status === 'ready' ? [...result.plan.changedFiles] : [...review.changedFiles],
+        };
+        if (result.status === 'conflict') {
+            return { ...common, status: 'conflict', conflictingFiles: [...result.conflictingFiles] };
+        }
+        const status = result.plan.changedFiles.length === 0
+            ? 'already_in_local'
+            : result.plan.localHeadOid !== record.baseOid
+                ? 'local_advanced'
+                : 'ready';
+        return { ...common, status };
+    }
+    function retainFinalized(record, retention) {
+        if (record.delivery.state !== 'finalized')
+            return undefined;
+        const retainedAt = Date.now();
+        return updateManagedCheckout(record.checkoutId, (current) => {
+            if (current.delivery.state !== 'finalized')
+                return current;
+            return {
+                ...current,
+                phase: 'retained',
+                delivery: {
+                    state: 'retained',
+                    review: current.delivery.review,
+                    commitOid: current.delivery.commitOid,
+                    ...(current.delivery.proof ? { proof: current.delivery.proof } : {}),
+                    isolatedFingerprint: current.delivery.isolatedFingerprint,
+                    retention,
+                    retainedAt,
+                    expiresAt: retentionExpiresAt(retention, retainedAt),
+                    cleanup: 'scheduled',
+                },
+                journal: null,
+                revision: current.revision + 1,
+            };
+        });
+    }
+    async function cleanupFinalized(record, options = {}) {
+        const block = (message, reason = cleanupReasonForMessage(message)) => {
+            updateManagedCheckout(record.checkoutId, (current) => {
+                const journal = current.journal?.operation === 'cleanup' ? current.journal : null;
+                if (current.delivery.state === 'finalized') {
+                    return {
+                        ...current,
+                        phase: 'finalized',
+                        delivery: { ...current.delivery, cleanup: 'blocked', cleanupMessage: message },
+                        journal,
+                        revision: current.revision + 1,
+                    };
+                }
+                if (current.delivery.state === 'retained') {
+                    return {
+                        ...current,
+                        phase: 'retained',
+                        delivery: { ...current.delivery, cleanup: 'blocked', cleanupMessage: message },
+                        journal,
+                        revision: current.revision + 1,
+                    };
+                }
+                return current;
+            });
+            return { cleaned: false, message, reason };
+        };
+        if (record.delivery.state !== 'finalized' && record.delivery.state !== 'retained') {
+            return block('Worktree 交付状态不完整，未执行清理。');
+        }
+        if ((record.delivery.state === 'finalized' || record.delivery.state === 'retained')
+            && record.delivery.cleanup === 'blocked'
+            && record.delivery.cleanupMessage?.includes('Local index')) {
+            return block(record.delivery.cleanupMessage);
+        }
+        if (hasLegacyCleanupResidueEvidence(record) && !options.allowLegacyResidue && dependencies.files.exists(record.managedGitRoot)) {
+            return { cleaned: false, message: CLEANUP_RESIDUE_MESSAGE, reason: 'detached_residue' };
+        }
+        const registry = dependencies.registry.read();
+        const persistedBinding = registry.sessionBindings[record.ownerSessionId];
+        const binding = persistedBinding?.target.kind === 'isolated'
+            && persistedBinding.target.checkoutId === record.checkoutId
+            ? persistedBinding
+            : bindingForManagedRecord(record);
+        const beginRemoval = (currentRecord, managedDirectoryIdentity) => {
+            if (hasCleanupRemovalReceipt(currentRecord))
+                return currentRecord;
+            return updateManagedCheckout(currentRecord.checkoutId, (current) => ({
+                ...current,
+                journal: {
+                    operation: 'cleanup',
+                    operationId: dependencies.createCheckoutId(),
+                    step: 'removing_worktree',
+                    startedAt: Date.now(),
+                    commitOid: current.delivery.state === 'finalized' || current.delivery.state === 'retained'
+                        ? current.delivery.commitOid ?? undefined
+                        : undefined,
+                    isolatedFingerprint: current.delivery.state === 'finalized' || current.delivery.state === 'retained'
+                        ? current.delivery.isolatedFingerprint
+                        : undefined,
+                    managedDirectoryIdentity,
+                },
+                revision: current.revision + 1,
+            }));
+        };
+        const quarantineAndRemove = async (currentRecord, residue) => {
+            const journal = currentRecord.journal?.operation === 'cleanup' ? currentRecord.journal : undefined;
+            if (!journal?.managedDirectoryIdentity)
+                throw new SessionCheckoutError('checkout_mismatch', 'Worktree cleanup receipt 不完整');
+            const quarantinePath = journal.cleanupQuarantinePath ?? join(dirname(currentRecord.managedGitRoot), `.dsh-wt-cleanup--${currentRecord.checkoutId.replace(/[^a-zA-Z0-9]/g, '').slice(0, 8)}--${journal.operationId}`);
+            const quarantining = journal.cleanupQuarantinePath
+                ? currentRecord
+                : updateManagedCheckout(currentRecord.checkoutId, (current) => ({
+                    ...current,
+                    journal: current.journal?.operation === 'cleanup'
+                        ? { ...current.journal, cleanupQuarantinePath: quarantinePath }
+                        : current.journal,
+                    revision: current.revision + 1,
+                }));
+            if (!quarantining)
+                throw new SessionCheckoutError('checkout_missing', 'Worktree 记录在 quarantine 前丢失');
+            if (!dependencies.files.exists(quarantinePath)) {
+                await retryTransientCleanup(() => dependencies.files.quarantineDirectoryTree(residue.canonicalManagedGitRoot, residue.directoryIdentity, quarantinePath));
+            }
+            const validatedQuarantine = await validateCleanupQuarantine(quarantining);
+            if (!validatedQuarantine)
+                throw new SessionCheckoutError('checkout_mismatch', 'Worktree quarantine 身份无法验证');
+            await retryTransientCleanup(() => dependencies.files.removeDirectoryTree(validatedQuarantine));
+        };
+        try {
+            const existingQuarantine = await validateCleanupQuarantine(record);
+            if (existingQuarantine) {
+                await retryTransientCleanup(() => dependencies.files.removeDirectoryTree(existingQuarantine));
+            }
+            else if (record.journal?.operation === 'cleanup' && record.journal.cleanupQuarantinePath && dependencies.files.exists(record.journal.cleanupQuarantinePath)) {
+                return block(CLEANUP_IDENTITY_CHANGED_MESSAGE);
+            }
+            else if (dependencies.files.exists(record.managedGitRoot)) {
+                const validated = dependencies.files.exists(record.managedRoot)
+                    ? await validateManagedCheckout(binding, record, false)
+                    : undefined;
+                if (validated) {
+                    const snapshot = await dependencies.applyEngine.inspectReview({
+                        baseOid: record.applyBaseOid ?? record.baseOid,
+                        isolatedPath: record.managedRoot,
+                        localPath: record.localRoot,
+                    });
+                    if (snapshot.status !== 'ready' || snapshot.isolatedFingerprint !== record.delivery.isolatedFingerprint) {
+                        return block('Worktree 在提交后出现了新修改，未执行清理。');
+                    }
+                    const directoryIdentity = await dependencies.files.inspectDirectoryIdentity(validated.canonicalManagedGitRoot);
+                    if (!directoryIdentity)
+                        return block(CLEANUP_IDENTITY_CHANGED_MESSAGE);
+                    const removing = beginRemoval(record, directoryIdentity);
+                    if (!removing)
+                        return block('Worktree 记录在清理前丢失，未执行清理。');
+                    await retryTransientCleanup(() => dependencies.git.removeWorktree(removing.localRoot, removing.managedGitRoot));
+                    if (dependencies.files.exists(removing.managedGitRoot)) {
+                        const residue = await validateDetachedCleanupResidue(removing);
+                        if (!residue)
+                            return block(CLEANUP_IDENTITY_CHANGED_MESSAGE);
+                        await quarantineAndRemove(removing, residue);
+                    }
+                }
+                else {
+                    const residue = await validateDetachedCleanupResidue(record, options.allowLegacyResidue === true);
+                    if (!residue)
+                        return block(CLEANUP_IDENTITY_CHANGED_MESSAGE);
+                    const removing = beginRemoval(record, residue.directoryIdentity);
+                    if (!removing)
+                        return block('Worktree 记录在清理前丢失，未执行清理。');
+                    const revalidatedResidue = await validateDetachedCleanupResidue(removing);
+                    if (!revalidatedResidue)
+                        return block(CLEANUP_IDENTITY_CHANGED_MESSAGE);
+                    await quarantineAndRemove(removing, revalidatedResidue);
+                }
+            }
+            await releaseApplyBaseBestEffort(record);
+            updateManagedCheckout(record.checkoutId, (current) => {
+                if (current.delivery.state !== 'finalized' && current.delivery.state !== 'retained')
+                    return current;
+                return {
+                    ...current,
+                    phase: 'discarded',
+                    delivery: {
+                        state: 'delivered',
+                        iteration: current.delivery.review.iteration,
+                        commitOid: current.delivery.commitOid,
+                        ...(current.delivery.proof ? { proof: current.delivery.proof } : {}),
+                        deliveredAt: Date.now(),
+                    },
+                    journal: null,
+                    revision: current.revision + 1,
+                };
+            });
+            return { cleaned: true };
+        }
+        catch (error) {
+            console.warn('[session-checkout] finalized Worktree cleanup failed:', error);
+            const failureRecord = dependencies.registry.read().managedCheckouts[record.checkoutId] ?? record;
+            const quarantineBusy = failureRecord.journal?.operation === 'cleanup' && Boolean(failureRecord.journal.cleanupQuarantinePath);
+            const reason = quarantineBusy ? 'quarantine_busy' : 'directory_busy';
+            const message = quarantineBusy
+                ? 'Worktree 已安全移入 quarantine，但目录仍被进程占用；dsh-git-worktree 会在同一清理授权内有限重试。'
+                : 'Worktree 目录仍被进程占用或 Windows 暂时拒绝删除；dsh-git-worktree 已完成有限重试，可稍后重试清理。';
+            updateManagedCheckout(record.checkoutId, (current) => {
+                const journal = current.journal?.operation === 'cleanup' ? current.journal : null;
+                if (current.delivery.state === 'finalized') {
+                    return { ...current, phase: 'finalized', delivery: { ...current.delivery, cleanup: 'pending', cleanupMessage: message }, journal, revision: current.revision + 1 };
+                }
+                if (current.delivery.state === 'retained') {
+                    return { ...current, phase: 'retained', delivery: { ...current.delivery, cleanup: 'blocked', cleanupMessage: message }, journal, revision: current.revision + 1 };
+                }
+                return current;
+            });
+            return { cleaned: false, message, reason };
+        }
+    }
+    async function operateRetryCleanup(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.delivery.state !== 'finalized' && record.delivery.state !== 'retained') {
+            return operationError('operation_not_allowed', '当前没有待重试的 Worktree 清理', await inspectIsolated(binding));
+        }
+        const cleanup = await cleanupFinalized(record, { allowLegacyResidue: true });
+        return {
+            status: 'finished',
+            target: await inspectIsolated(binding),
+            changedFiles: [...record.delivery.review.changedFiles],
+            commitOid: record.delivery.commitOid,
+            cleanup: cleanup.cleaned ? 'discarded' : 'pending',
+            ...(cleanup.message ? { cleanupMessage: cleanup.message } : {}),
+            ...(cleanup.reason ? { cleanupReason: cleanup.reason } : {}),
+        };
+    }
+    async function operateFinish(input, binding) {
+        if (binding.ownerSessionId !== input.sessionId) {
+            return operationError('not_owner', '继承 Session Target 的会话不能执行 Finish');
+        }
+        if (binding.target.kind !== 'isolated') {
+            return operationError('operation_not_allowed', 'Local Checkout 不支持 Finish');
+        }
+        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') {
+            return operationError('operation_not_allowed', `当前 ${record.phase}/${record.delivery.state} 状态不能直接 Finish`, 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.phase !== 'ready') {
+            return operationError('recovery_required', 'Isolated Checkout 状态已变化，需要恢复');
+        }
+        const startedAt = Date.now();
+        const operationId = dependencies.createCheckoutId();
+        const applyBaseOid = record.applyBaseOid ?? record.baseOid;
+        const applying = updateManagedCheckout(record.checkoutId, (current) => ({
+            ...current,
+            phase: 'mutating',
+            journal: {
+                operation: 'finish',
+                operationId,
+                step: 'planning',
+                startedAt,
+                baseOid: applyBaseOid,
+            },
+            revision: current.revision + 1,
+        }));
+        if (!applying)
+            return operationError('checkout_missing', 'Isolated Checkout 记录不存在');
+        const planResult = await dependencies.applyEngine.plan({
+            baseOid: applyBaseOid,
+            isolatedPath: applying.managedRoot,
+            localPath: applying.localRoot,
+        });
+        if (planResult.status === 'conflict') {
+            updateManagedCheckout(applying.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(applying.checkoutId, (current) => ({
+                ...current,
+                phase: 'ready',
+                journal: null,
+                revision: current.revision + 1,
+            }));
+            return operationError(planResult.error.code, planResult.error.message, await inspectIsolated(binding));
+        }
+        const iteration = applying.delivery.state === 'working'
+            ? applying.delivery.iteration
+            : applying.delivery.state === 'delivered'
+                ? applying.delivery.iteration + 1
+                : applying.delivery.review.iteration;
+        const review = applying.delivery.state === 'ready_for_review'
+            ? applying.delivery.review
+            : {
+                reviewId: operationId,
+                iteration,
+                preparedAt: startedAt,
+                summary: '跳过 Local 验收并直接提交',
+                validationStatus: 'not_run',
+                tests: [],
+                changedFiles: [...planResult.plan.changedFiles],
+                suggestedCommitMessage: input.commitMessage,
+                isolatedFingerprint: planResult.plan.isolatedFingerprint,
+                isolatedHeadOid: planResult.plan.isolatedHeadOid,
+            };
+        updateManagedCheckout(applying.checkoutId, (current) => ({
+            ...current,
+            delivery: { state: 'ready_for_review', review },
+            journal: {
+                operation: 'finish',
+                operationId,
+                step: 'writing_local',
+                startedAt,
+                baseOid: applyBaseOid,
+                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 finishResult = await dependencies.applyEngine.finish(planResult.plan, {
+            commitMessage: input.commitMessage,
+        });
+        if (finishResult.status === 'error') {
+            if (finishResult.error.code === 'invalid_plan'
+                || finishResult.error.code === 'stale_local'
+                || finishResult.error.code === 'stale_isolated'
+                || finishResult.error.code === 'invalid_input'
+                || finishResult.error.code === 'operation_not_allowed'
+                || finishResult.error.code === 'commit_isolation_conflict') {
+                // 这些错误码可证明未触碰 Local，恢复 ready；git_error 交由 reconcile 兜底 recovery_required。
+                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)
+                        : null,
+                    localHeadBefore: planResult.plan.localHeadOid,
+                    localHeadAfter: finishResult.commitOid ?? planResult.plan.localHeadOid,
+                    changedFiles: [...finishResult.changedFiles],
+                },
+                isolatedFingerprint: planResult.plan.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: finishResult.changedFiles,
+                commitOid: finishResult.commitOid,
+                cleanup: 'retained',
+            };
+        }
+        const cleanup = await cleanupFinalized(finalized);
+        return {
+            status: 'finished',
+            target: await inspectIsolated(binding),
+            changedFiles: finishResult.changedFiles,
+            commitOid: finishResult.commitOid,
+            cleanup: cleanup.cleaned ? 'discarded' : 'pending',
+            ...(cleanup.message ? { cleanupMessage: cleanup.message } : {}),
+            ...(cleanup.reason ? { cleanupReason: cleanup.reason } : {}),
+        };
+    }
+    async function releaseApplyBaseBestEffort(record) {
+        try {
+            await dependencies.git.releaseApplyBase(record.localRoot, record.checkoutId);
+            await dependencies.git.releaseInternalArtifacts(record.localRoot, record.checkoutId);
+        }
+        catch {
+            // checkout 删除优先；内部无 ref artifact 的清理失败不能阻止 owner 明确收口。
+            console.warn('[session-checkout] 清理内部 Session Checkout refs 失败，已保守保留不可见引用');
+        }
+    }
+    async function operateDiscard(input, binding) {
+        if (binding.ownerSessionId !== input.sessionId) {
+            return operationError('not_owner', '继承 Session Target 的会话不能执行 Discard');
+        }
+        if (binding.target.kind !== 'isolated') {
+            return operationError('operation_not_allowed', 'Local Checkout 不支持 Discard');
+        }
+        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 === 'recovery_required' && !dependencies.files.exists(record.managedRoot)) {
+            await releaseApplyBaseBestEffort(record);
+            updateManagedCheckout(record.checkoutId, (current) => ({
+                ...current,
+                phase: 'discarded',
+                journal: null,
+                revision: current.revision + 1,
+            }));
+            return { status: 'discarded', target: await inspectIsolated(binding) };
+        }
+        if (record.phase !== 'ready' && record.phase !== 'recovery_required') {
+            return operationError('operation_not_allowed', `当前 ${record.phase} 状态不能 Discard`, await inspectIsolated(binding));
+        }
+        let inspected;
+        let dirty = true;
+        if (record.phase === 'ready') {
+            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.phase !== 'ready') {
+                return operationError('recovery_required', 'Isolated Checkout 状态已变化，需要恢复');
+            }
+            dirty = (await dependencies.git.status(record.managedRoot)).dirty;
+        }
+        else {
+            try {
+                dirty = (await dependencies.git.status(record.managedRoot)).dirty;
+            }
+            catch {
+                dirty = true;
+            }
+            inspected = recoveryView(binding, record, dirty);
+        }
+        if (dirty && !input.confirmDirty) {
+            return operationError('dirty_confirmation_required', 'Isolated Checkout 含未提交修改或状态无法确认，需要明确确认', inspected);
+        }
+        try {
+            await dependencies.git.removeWorktree(record.localRoot, record.managedGitRoot);
+        }
+        catch {
+            return operationError('git_operation_failed', '删除 managed checkout 失败', await inspectIsolated(binding));
+        }
+        await releaseApplyBaseBestEffort(record);
+        updateManagedCheckout(record.checkoutId, (current) => ({
+            ...current,
+            phase: 'discarded',
+            journal: null,
+            revision: current.revision + 1,
+        }));
+        return { status: 'discarded', target: await inspectIsolated(binding) };
+    }
+    async function operateRecover(input, binding) {
+        if (binding.ownerSessionId !== input.sessionId) {
+            return operationError('not_owner', '继承 Session Target 的会话不能执行 Recover');
+        }
+        if (binding.target.kind !== 'isolated') {
+            return operationError('operation_not_allowed', 'Local Checkout 不支持 Recover');
+        }
+        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 recoverCreate = record.journal?.operation === 'create';
+        if ((record.journal !== null && !recoverCreate) || record.phase === 'mutating') {
+            return operationError('recovery_unsafe', 'Apply 是否已修改 Local 无法安全确认；不会自动重试或猜测成功', await inspectIsolated(binding));
+        }
+        if (!dependencies.files.exists(record.managedRoot)) {
+            return operationError('recovery_required', 'Isolated Checkout 缺失，只能由 owner 明确 Discard 收口');
+        }
+        const validated = await validateManagedCheckout(binding, record, recoverCreate);
+        if (!validated) {
+            return operationError('recovery_unsafe', 'Isolated Checkout 的路径、Git 身份、项目、HEAD 或状态无法完整确认');
+        }
+        updateManagedCheckout(record.checkoutId, (current) => ({
+            ...current,
+            managedRoot: validated.canonicalManagedRoot,
+            managedGitRoot: validated.canonicalManagedGitRoot,
+            gitDir: validated.snapshot.gitDir,
+            phase: 'ready',
+            journal: null,
+            revision: current.revision + 1,
+        }));
+        return { status: 'recovered', target: await inspectIsolated(binding) };
+    }
+    async function operateTarget(input) {
+        try {
+            const binding = await resolveBinding(input.sessionId);
+            if (input.action === 'apply')
+                return await operateApply(input, binding);
+            if (input.action === 'finish')
+                return await operateFinish(input, binding);
+            if (input.action === 'retry_cleanup')
+                return await operateRetryCleanup(input, binding);
+            if (input.action === 'discard')
+                return await operateDiscard(input, binding);
+            if (input.action === 'recover')
+                return await operateRecover(input, binding);
+            const exhaustive = input;
+            return exhaustive;
+        }
+        catch (error) {
+            if (error instanceof SessionCheckoutError)
+                return operationError(error.code, error.message);
+            throw error;
+        }
+    }
+    function managedIteration(record) {
+        if (record.delivery.state === 'working' || record.delivery.state === 'delivered')
+            return record.delivery.iteration;
+        return record.delivery.review.iteration;
+    }
+    function managedUpdatedAt(record) {
+        if (record.delivery.state === 'working')
+            return record.journal?.startedAt ?? 0;
+        if (record.delivery.state === 'ready_for_review')
+            return record.delivery.review.preparedAt;
+        if (record.delivery.state === 'finalized')
+            return record.delivery.finalizedAt;
+        if (record.delivery.state === 'retained')
+            return record.delivery.retainedAt;
+        return record.delivery.deliveredAt;
+    }
+    async function summarizeManagedWorktree(record, includeDiagnostics = false) {
+        // 快速列表必须保守且不扫描 Git/磁盘；只有后台单项诊断完成后才开放清理。
+        let dirty = true;
+        let cleanupResidue = false;
+        let approximateBytes = null;
+        if (includeDiagnostics) {
+            if (record.delivery.state === 'finalized' || record.delivery.state === 'retained') {
+                const quarantine = await validateCleanupQuarantine(record);
+                const residue = quarantine ? undefined : await validateDetachedCleanupResidue(record, true);
+                if (quarantine || residue) {
+                    cleanupResidue = true;
+                    dirty = false;
+                }
+                else if (dependencies.files.exists(record.managedRoot)) {
+                    try {
+                        const snapshot = await dependencies.applyEngine.inspectReview({
+                            baseOid: record.applyBaseOid ?? record.baseOid,
+                            isolatedPath: record.managedRoot,
+                            localPath: record.localRoot,
+                        });
+                        dirty = snapshot.status !== 'ready' || snapshot.isolatedFingerprint !== record.delivery.isolatedFingerprint;
+                    }
+                    catch {
+                        dirty = true;
+                    }
+                }
+            }
+            else if (dependencies.files.exists(record.managedRoot)) {
+                try {
+                    dirty = (await dependencies.git.status(record.managedRoot)).dirty;
+                }
+                catch {
+                    dirty = true;
+                }
+            }
+            const physicalRoot = record.journal?.operation === 'cleanup' && record.journal.cleanupQuarantinePath
+                ? record.journal.cleanupQuarantinePath
+                : record.managedGitRoot;
+            if (dependencies.files.exists(physicalRoot)) {
+                try {
+                    approximateBytes = await dependencies.files.measureDirectoryBytes(physicalRoot);
+                }
+                catch {
+                    approximateBytes = null;
+                }
+            }
+        }
+        const delivery = record.delivery;
+        const state = record.phase === 'recovery_required'
+            ? 'needs_attention'
+            : delivery.state === 'retained'
+                ? 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';
+        const commitOid = delivery.state === 'finalized' || delivery.state === 'retained' || delivery.state === 'delivered'
+            ? delivery.commitOid
+            : null;
+        const cleanupMessage = cleanupResidue
+            ? CLEANUP_RESIDUE_MESSAGE
+            : delivery.state === 'finalized' || delivery.state === 'retained'
+                ? delivery.cleanupMessage
+                : undefined;
+        const cleanupReason = cleanupMessage ? cleanupReasonForMessage(cleanupMessage) : undefined;
+        return {
+            checkoutId: record.checkoutId,
+            revision: record.revision,
+            ownerSessionId: record.ownerSessionId,
+            ownerSessionTitle: dependencies.lookup.getSession(record.ownerSessionId)?.title?.trim() || '已删除的 Agent 会话',
+            project: { id: record.projectId, name: record.projectName },
+            iteration: managedIteration(record),
+            state,
+            phase: record.phase,
+            dirty,
+            commitOid,
+            ...(delivery.state === 'retained' ? {
+                retention: delivery.retention,
+                retainedAt: delivery.retainedAt,
+                expiresAt: delivery.expiresAt,
+            } : {}),
+            ...(cleanupMessage ? { cleanupMessage } : {}),
+            ...(cleanupReason ? { cleanupReason } : {}),
+            approximateBytes,
+            updatedAt: managedUpdatedAt(record),
+            canCleanup: includeDiagnostics && (delivery.state === 'retained' || delivery.state === 'finalized') && !dirty,
+        };
+    }
+    function cleanupBlocked(reason, message, revision) {
+        return { eligibility: 'blocked', reason, message, inspectedRevision: revision };
+    }
+    async function inspectCleanupForRecord(record) {
+        if (record.delivery.state === 'working')
+            return cleanupBlocked('working', '当前轮次仍在修改，尚未形成可清理的交付环境。', record.revision);
+        if (record.delivery.state === 'ready_for_review')
+            return cleanupBlocked('review_pending', '当前轮次正在等待验收，不能清理。', record.revision);
+        if (record.delivery.state === 'delivered' || record.phase === 'discarded') {
+            return cleanupBlocked('unknown', 'Worktree 已交付并解除管理，无需再次清理。', record.revision);
+        }
+        if (record.delivery.commitOid && record.delivery.proof) {
+            const local = await validateCommittedLocalCheckout(bindingForManagedRecord(record), record);
+            if (!local)
+                return cleanupBlocked('identity_mismatch', 'Local checkout identity 无法验证，不能证明本轮交付仍存在。', record.revision);
+            try {
+                const delivered = await dependencies.git.isAncestor(local.canonicalLocalRoot, record.delivery.commitOid, local.snapshot.headOid);
+                if (!delivered)
+                    return cleanupBlocked('identity_mismatch', '本轮交付 commit 已不在 Local 历史中，不能清理环境。', record.revision);
+            }
+            catch {
+                return cleanupBlocked('unknown', '无法验证本轮交付 commit 是否仍在 Local 历史中。', record.revision);
+            }
+        }
+        const quarantine = await validateCleanupQuarantine(record);
+        const residue = quarantine ? undefined : await validateDetachedCleanupResidue(record, true);
+        if (record.journal?.operation === 'cleanup' && record.journal.cleanupQuarantinePath && !quarantine) {
+            return cleanupBlocked('identity_mismatch', '清理目录身份无法重新验证，已保留环境。', record.revision);
+        }
+        if (!quarantine && !residue && dependencies.files.exists(record.managedRoot)) {
+            const binding = bindingForManagedRecord(record);
+            const validated = await validateManagedCheckout(binding, record, false);
+            if (!validated)
+                return cleanupBlocked('identity_mismatch', 'Worktree checkout identity 无法验证，已保留环境。', record.revision);
+            try {
+                const snapshot = await dependencies.applyEngine.inspectReview({
+                    baseOid: record.applyBaseOid ?? record.baseOid,
+                    isolatedPath: record.managedRoot,
+                    localPath: record.localRoot,
+                });
+                if (snapshot.status !== 'ready' || snapshot.isolatedFingerprint !== record.delivery.isolatedFingerprint) {
+                    return cleanupBlocked('uncommitted_changes', '提交或保留后检测到新增修改，不能批量清理。', record.revision);
+                }
+            }
+            catch {
+                return cleanupBlocked('unknown', '无法证明 Worktree 当前状态安全，已保留环境。', record.revision);
+            }
+        }
+        if (record.delivery.cleanup === 'blocked' || record.delivery.cleanup === 'pending') {
+            const cleanupMessage = record.delivery.cleanupMessage ?? '上次清理未完成，可重新校验后重试。';
+            if (cleanupReasonForMessage(cleanupMessage) === 'identity_changed')
+                return cleanupBlocked('identity_mismatch', cleanupMessage, record.revision);
+            if (cleanupReasonForMessage(cleanupMessage) === 'modified_after_finalize')
+                return cleanupBlocked('uncommitted_changes', cleanupMessage, record.revision);
+        }
+        if (record.delivery.state === 'retained'
+            && (record.delivery.retention === 'retain_manual' || record.delivery.expiresAt === null || record.delivery.expiresAt > Date.now())) {
+            return { eligibility: 'retained', reason: 'retention_active', message: record.delivery.retention === 'retain_manual' ? '按用户选择手动保留。' : '保留期限尚未到期。', inspectedRevision: record.revision };
+        }
+        return { eligibility: 'safe', reason: 'cleanup_failed', message: record.delivery.cleanupMessage ?? '已通过只读安全巡检，可以清理。', inspectedRevision: record.revision };
+    }
+    async function inspectManagedWorktreeCleanup(input = {}) {
+        const records = Object.values(dependencies.registry.read().managedCheckouts)
+            .filter((record) => record.phase !== 'discarded')
+            .filter((record) => !input.projectId || record.projectId === input.projectId)
+            .filter((record) => !input.checkoutId || record.checkoutId === input.checkoutId);
+        const summaries = await Promise.all(records.map(async (record) => ({
+            ...(await summarizeManagedWorktree(record, true)),
+            cleanup: await inspectCleanupForRecord(record),
+        })));
+        return summaries
+            .filter((summary) => !input.needsAttention || summary.cleanup?.eligibility === 'blocked')
+            .sort((left, right) => right.updatedAt - left.updatedAt);
+    }
+    async function bulkCleanupManagedWorktrees(candidates) {
+        const cleaned = [];
+        const retained = [];
+        const uniqueCandidates = [...new Map(candidates.map((candidate) => [candidate.checkoutId, candidate])).values()]
+            .sort((left, right) => left.checkoutId.localeCompare(right.checkoutId));
+        for (const candidate of uniqueCandidates) {
+            const record = dependencies.registry.read().managedCheckouts[candidate.checkoutId];
+            if (!record || record.phase === 'discarded')
+                continue;
+            if (record.revision !== candidate.expectedRevision) {
+                retained.push({
+                    checkoutId: record.checkoutId,
+                    iteration: managedIteration(record),
+                    cleanup: cleanupBlocked('unknown', 'Worktree revision 已变化，未执行清理。', record.revision),
+                });
+                continue;
+            }
+            const inspection = await inspectCleanupForRecord(record);
+            if (inspection.eligibility !== 'safe') {
+                retained.push({ checkoutId: record.checkoutId, iteration: managedIteration(record), cleanup: inspection });
+                continue;
+            }
+            const latest = dependencies.registry.read().managedCheckouts[candidate.checkoutId];
+            if (!latest || latest.revision !== candidate.expectedRevision) {
+                retained.push({
+                    checkoutId: record.checkoutId,
+                    iteration: managedIteration(record),
+                    cleanup: cleanupBlocked('unknown', 'Worktree 在清理前发生变化，未执行清理。', latest?.revision ?? record.revision),
+                });
+                continue;
+            }
+            const result = await cleanupFinalized(latest, { allowLegacyResidue: true });
+            const updated = dependencies.registry.read().managedCheckouts[candidate.checkoutId];
+            if (result.cleaned) {
+                cleaned.push({
+                    checkoutId: record.checkoutId,
+                    iteration: managedIteration(record),
+                    commitOid: record.delivery.state === 'finalized' || record.delivery.state === 'retained' ? record.delivery.commitOid : null,
+                });
+            }
+            else if (updated) {
+                retained.push({
+                    checkoutId: updated.checkoutId,
+                    iteration: managedIteration(updated),
+                    cleanup: await inspectCleanupForRecord(updated),
+                });
+            }
+        }
+        return { cleaned, retained };
+    }
+    async function listManagedWorktrees(input = {}) {
+        const records = Object.values(dependencies.registry.read().managedCheckouts)
+            .filter((record) => record.phase !== 'discarded')
+            .filter((record) => !input.projectId || record.projectId === input.projectId)
+            .filter((record) => !input.checkoutId || record.checkoutId === input.checkoutId);
+        const summaries = await Promise.all(records.map((record) => summarizeManagedWorktree(record, input.includeDiagnostics === true)));
+        return summaries
+            .filter((summary) => !input.needsAttention || summary.state === 'needs_attention' || summary.state === 'cleanup_pending')
+            .sort((left, right) => right.updatedAt - left.updatedAt);
+    }
+    async function manageManagedWorktree(input) {
+        const record = dependencies.registry.read().managedCheckouts[input.checkoutId];
+        if (!record)
+            throw new SessionCheckoutError('checkout_missing', 'Worktree 记录不存在');
+        if (record.revision !== input.expectedRevision)
+            throw new SessionCheckoutError('stale_target', 'Worktree 状态已变化，请刷新后重试');
+        if (input.action === 'discard') {
+            const result = await operateTarget({
+                action: 'discard',
+                sessionId: record.ownerSessionId,
+                expectedRevision: input.expectedRevision,
+                confirmDirty: input.confirmDirty === true,
+            });
+            if (result.status === 'error')
+                throw new SessionCheckoutError(result.code, result.message);
+            const updated = dependencies.registry.read().managedCheckouts[record.checkoutId];
+            if (!updated)
+                throw new SessionCheckoutError('checkout_missing', 'Worktree 记录不存在');
+            return summarizeManagedWorktree(updated);
+        }
+        if (input.action === 'set_retention') {
+            if (record.phase !== 'retained' || record.delivery.state !== 'retained' || !input.retention) {
+                throw new SessionCheckoutError('operation_not_allowed', '只有已保留的冻结 Worktree 可以调整保留期限');
+            }
+            const retainedAt = Date.now();
+            const updated = updateManagedCheckout(record.checkoutId, (current) => {
+                if (current.delivery.state !== 'retained')
+                    return current;
+                return {
+                    ...current,
+                    delivery: {
+                        ...current.delivery,
+                        retention: input.retention,
+                        retainedAt,
+                        expiresAt: retentionExpiresAt(input.retention, retainedAt),
+                        cleanup: 'scheduled',
+                        cleanupMessage: undefined,
+                    },
+                    revision: current.revision + 1,
+                };
+            });
+            if (!updated)
+                throw new SessionCheckoutError('checkout_missing', 'Worktree 记录不存在');
+            return summarizeManagedWorktree(updated);
+        }
+        if (record.delivery.state !== 'retained' && record.delivery.state !== 'finalized') {
+            throw new SessionCheckoutError('operation_not_allowed', '当前 Worktree 不处于可清理状态');
+        }
+        await cleanupFinalized(record, { allowLegacyResidue: true });
+        const updated = dependencies.registry.read().managedCheckouts[record.checkoutId];
+        if (!updated)
+            throw new SessionCheckoutError('checkout_missing', 'Worktree 记录不存在');
+        return summarizeManagedWorktree(updated);
+    }
+    async function resolveManagedRoot(checkoutId) {
+        const record = dependencies.registry.read().managedCheckouts[checkoutId];
+        if (!record || record.phase === 'discarded')
+            throw new SessionCheckoutError('checkout_missing', 'Worktree 目录已不存在');
+        const validated = await validateManagedCheckout(bindingForManagedRecord(record), record, false);
+        if (!validated)
+            throw new SessionCheckoutError('checkout_mismatch', 'Worktree 目录身份无法验证');
+        return validated.canonicalManagedRoot;
+    }
+    async function cleanupExpiredRetained(now = Date.now()) {
+        const expired = Object.values(dependencies.registry.read().managedCheckouts).filter((record) => (record.phase === 'retained'
+            && record.delivery.state === 'retained'
+            && record.delivery.cleanup === 'scheduled'
+            && record.delivery.expiresAt !== null
+            && record.delivery.expiresAt <= now));
+        const cleaned = [];
+        for (const record of expired) {
+            try {
+                // 到期保留清理同样受收敛超时保护，避免单个占用记录卡住后续启动。
+                const result = await withCleanupTimeout(record.checkoutId, () => cleanupFinalized(record));
+                if (result?.cleaned)
+                    cleaned.push(record.checkoutId);
+            }
+            catch (error) {
+                console.warn(`[session-checkout] expired retained Worktree cleanup skipped: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        return cleaned;
+    }
+    async function bindTarget(sessionId, choice, createAttempt = 0, requestStartedAt = Date.now()) {
+        const session = requireSession(sessionId);
+        let nextIteration = 1;
+        let replacedDeliveredBinding;
+        const existing = getPersistedBinding(sessionId);
+        if (existing) {
+            if (choice.kind === 'local' && existing.target.kind === 'local') {
+                return inspectLocal(existing);
+            }
+            if (choice.kind === 'isolated' && existing.target.kind === 'isolated') {
+                const existingView = await inspectIsolated(existing);
+                const registry = dependencies.registry.read();
+                const existingRecord = registry.managedCheckouts[existing.target.checkoutId];
+                if (existingView.ownership === 'owner'
+                    && existingRecord
+                    && ((existingView.checkout.phase === 'discarded' && existingRecord.delivery.state === 'delivered')
+                        || (existingView.checkout.phase === 'finalized' && existingRecord.delivery.state === 'finalized')
+                        || (existingView.checkout.phase === 'retained' && existingRecord.delivery.state === 'retained'))) {
+                    nextIteration = managedIteration(existingRecord) + 1;
+                    replacedDeliveredBinding = {
+                        ...existing,
+                        target: { ...existing.target },
+                    };
+                    delete registry.sessionBindings[sessionId];
+                    registry.revision += 1;
+                    dependencies.registry.write(registry);
+                }
+                else {
+                    return existingView;
+                }
+            }
+            if (!(choice.kind === 'isolated' && existing.target.kind === 'isolated' && nextIteration > 1)) {
+                throw new SessionCheckoutError('target_already_bound', '会话已经绑定 Session Target，不能切换');
+            }
+        }
+        const { project } = await resolveSessionProject(sessionId);
+        const snapshot = await dependencies.git.inspect(project.root);
+        if (choice.kind === 'local') {
+            const binding = {
+                sessionId,
+                projectId: project.id,
+                projectName: project.name,
+                target: { kind: 'local' },
+                ownerSessionId: sessionId,
+                sourceRef: snapshot?.headRef ?? UNVERSIONED_REF,
+                sourceOid: snapshot?.headOid ?? UNVERSIONED_OID,
+                revision: 1,
+            };
+            const registry = dependencies.registry.read();
+            registry.sessionBindings[sessionId] = binding;
+            registry.revision += 1;
+            dependencies.registry.write(registry);
+            return inspectLocal(binding);
+        }
+        if (!snapshot) {
+            throw new SessionCheckoutError('not_git_repository', '非 Git 项目不能创建 Isolated Checkout');
+        }
+        // managed Worktree 不再使用全局数量硬上限；生命周期通过交付后清理收口。
+        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 projectRelativePath = relative(localGitRoot, localRoot);
+        if (projectRelativePath.startsWith('..') || isAbsolute(projectRelativePath)) {
+            throw new SessionCheckoutError('checkout_mismatch', '项目根目录不在其 Git checkout 内');
+        }
+        const managedRoot = join(managedGitRoot, projectRelativePath);
+        const record = {
+            checkoutId,
+            projectId: project.id,
+            projectName: project.name,
+            ownerSessionId: sessionId,
+            localRoot,
+            managedRoot: resolve(managedRoot),
+            managedGitRoot: resolve(managedGitRoot),
+            gitCommonDir: snapshot.commonDir,
+            gitDir: '',
+            baseOid: snapshot.headOid,
+            sourceRef: snapshot.headRef,
+            phase: 'preparing',
+            delivery: { state: 'working', iteration: nextIteration },
+            journal: {
+                operation: 'create',
+                operationId: dependencies.createCheckoutId(),
+                step: 'creating_worktree',
+                startedAt: Date.now(),
+            },
+            revision: 1,
+        };
+        const binding = {
+            sessionId,
+            projectId: project.id,
+            projectName: project.name,
+            target: { kind: 'isolated', checkoutId },
+            ownerSessionId: sessionId,
+            sourceRef: snapshot.headRef,
+            sourceOid: snapshot.headOid,
+            revision: 1,
+        };
+        const preparingRegistry = dependencies.registry.read();
+        preparingRegistry.sessionBindings[sessionId] = binding;
+        preparingRegistry.managedCheckouts[checkoutId] = record;
+        preparingRegistry.revision += 1;
+        dependencies.registry.write(preparingRegistry);
+        try {
+            await dependencies.git.createDetachedWorktree(localGitRoot, managedGitRoot, snapshot.headOid);
+            const canonicalManagedGitRoot = await dependencies.files.canonicalize(managedGitRoot);
+            const canonicalManagedRoot = await dependencies.files.canonicalize(managedRoot);
+            const created = await dependencies.git.inspect(canonicalManagedRoot);
+            if (!created
+                || !pathsEqual(created.root, canonicalManagedGitRoot)
+                || !pathsEqual(created.commonDir, snapshot.commonDir)) {
+                throw new SessionCheckoutError('checkout_mismatch', '新建 checkout 的 Git common dir 不匹配');
+            }
+            const readyRegistry = dependencies.registry.read();
+            const readyRecord = {
+                ...record,
+                managedRoot: canonicalManagedRoot,
+                managedGitRoot: canonicalManagedGitRoot,
+                gitDir: created.gitDir,
+                phase: 'ready',
+                journal: null,
+                revision: record.revision + 1,
+            };
+            readyRegistry.managedCheckouts[checkoutId] = readyRecord;
+            readyRegistry.revision += 1;
+            dependencies.registry.write(readyRegistry);
+            return inspectIsolated(binding);
+        }
+        catch (error) {
+            let partialCheckout = null;
+            try {
+                // 仓库内布局下，残余目录会被 git 识别为上层主仓库 checkout；
+                // 有效 worktree 必须带 .git 文件（git worktree add 创建），否则视为残余。
+                if (dependencies.files.exists(join(managedGitRoot, '.git'))) {
+                    partialCheckout = await dependencies.git.inspect(managedRoot);
+                }
+            }
+            catch {
+                partialCheckout = null;
+            }
+            if (partialCheckout) {
+                markRecoveryRequired(record);
+                throw error;
+            }
+            let residueRemoved = false;
+            try {
+                residueRemoved = dependencies.files.removeEmptyDirectoryTree(managedGitRoot);
+            }
+            catch {
+                residueRemoved = false;
+            }
+            if (!residueRemoved) {
+                markRecoveryRequired(record);
+                throw new SessionCheckoutError('recovery_required', 'Worktree 创建失败且残余目录包含未知内容，已保留现场，请查看原因或改用新会话');
+            }
+            const failedRegistry = dependencies.registry.read();
+            delete failedRegistry.managedCheckouts[checkoutId];
+            const currentBinding = failedRegistry.sessionBindings[sessionId];
+            if (currentBinding?.target.kind === 'isolated' && currentBinding.target.checkoutId === checkoutId) {
+                if (replacedDeliveredBinding) {
+                    failedRegistry.sessionBindings[sessionId] = replacedDeliveredBinding;
+                }
+                else {
+                    delete failedRegistry.sessionBindings[sessionId];
+                }
+            }
+            failedRegistry.revision += 1;
+            dependencies.registry.write(failedRegistry);
+            if (createAttempt < 1) {
+                return bindTarget(sessionId, choice, createAttempt + 1, requestStartedAt);
+            }
+            throw new SessionCheckoutError('git_operation_failed', 'Worktree 创建失败，已安全清理残余目录，可直接重试');
+        }
+    }
+    return {
+        inspect: inspectAvailable,
+        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));
+        },
+        beginNextIteration: (sessionId) => {
+            const requestStartedAt = Date.now();
+            return withBindingLock(() => bindTarget(sessionId, { kind: 'isolated' }, 0, requestStartedAt));
+        },
+        markReadyForReview: (sessionId, input) => withBindingLock(() => markReadyForReviewTarget(sessionId, input)),
+        operate: (input) => withBindingLock(() => operateTarget(input)),
+        // 只读管理列表不占用全局 mutation lock；慢速目录诊断与用户操作互不阻塞。
+        listManagedWorktrees,
+        inspectManagedWorktreeCleanup,
+        bulkCleanupManagedWorktrees: (candidates) => withBindingLock(() => bulkCleanupManagedWorktrees(candidates)),
+        manageManagedWorktree: (input) => withBindingLock(() => manageManagedWorktree(input)),
+        resolveManagedRoot: (checkoutId) => withBindingLock(() => resolveManagedRoot(checkoutId)),
+        cleanupExpiredRetained: (now) => withBindingLock(() => cleanupExpiredRetained(now), { allowConcurrentInspect: true }),
+        reconcile: () => withBindingLock(reconcile, { allowConcurrentInspect: true }),
+    };
+}
+//# sourceMappingURL=session-checkout-module.js.map