dsh-git-worktree 0.1.0

package/lib/session-checkout-apply.js

@@ -0,0 +1,753 @@
+/**
+ * dsh-git-worktree apply engine, ported from Domi's session-checkout-apply
+ * with the Local preview surface removed (preview/rollback/finalize). The
+ * remaining surface is the deterministic merge pipeline: plan (conflict
+ * detection with ancestry-aware base selection), apply (patch Local with a
+ * verified plan), and finish (commit the task delta onto Local HEAD while
+ * preserving the user's own staged and working state). All merge computation
+ * runs in temporary checkouts over shared object stores; only the final
+ * verified patch touches the real Local worktree, and ref/index updates use
+ * CAS so a crash leaves a recoverable journal.
+ *
+ * Ports note: `runGit` still spawns git directly (plugin code is trusted host
+ * code, not sandboxed agent code); tests inject a real git in temp repos.
+ * @module dsh-git-worktree/session-checkout-apply
+ */
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { copyFile, mkdir, mkdtemp, rename, rm, unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { delimiter, isAbsolute, join, relative, resolve } from 'node:path';
+class GitCommandFailure extends Error {
+    args;
+    result;
+    constructor(args, result) {
+        super(result.stderr || `git 命令退出码为 ${result.exitCode}`);
+        this.args = args;
+        this.result = result;
+    }
+}
+const GIT_TIMEOUT_MS = 30_000;
+const OID_PATTERN = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
+async function runGit(cwd, args, options = {}) {
+    return await new Promise((resolveResult, reject) => {
+        const child = spawn('git', ['-c', 'core.quotePath=false', ...args], {
+            cwd,
+            env: {
+                ...process.env,
+                GIT_TERMINAL_PROMPT: '0',
+                ...options.env,
+            },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let settled = false;
+        const finish = (error, result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            if (error)
+                reject(error);
+            else if (result)
+                resolveResult(result);
+        };
+        child.stdout.on('data', (chunk) => stdoutChunks.push(chunk));
+        child.stderr.on('data', (chunk) => stderrChunks.push(chunk));
+        child.on('error', (error) => finish(error));
+        child.on('close', (exitCode) => {
+            const result = {
+                exitCode: exitCode ?? -1,
+                stdout: Buffer.concat(stdoutChunks),
+                stderr: Buffer.concat(stderrChunks).toString('utf8').trim(),
+            };
+            const allowed = options.allowedExitCodes ?? [0];
+            finish(allowed.includes(result.exitCode) ? null : new GitCommandFailure(args, result), result);
+        });
+        const timeout = setTimeout(() => {
+            child.kill('SIGTERM');
+            finish(new Error(`git 命令超时：${args[0] ?? 'unknown'}`));
+        }, GIT_TIMEOUT_MS);
+        if (options.input !== undefined)
+            child.stdin.end(options.input);
+        else
+            child.stdin.end();
+    });
+}
+function stdoutText(result) {
+    return result.stdout.toString('utf8').trim();
+}
+function parseNullSeparated(output) {
+    return output
+        .toString('utf8')
+        .split('\0')
+        .filter((value) => value.length > 0);
+}
+function gitObjectEnvironment(objectDirectory, sourceObjectDirectory) {
+    const existingAlternates = process.env.GIT_ALTERNATE_OBJECT_DIRECTORIES;
+    return {
+        GIT_OBJECT_DIRECTORY: objectDirectory,
+        GIT_ALTERNATE_OBJECT_DIRECTORIES: [sourceObjectDirectory, existingAlternates]
+            .filter((value) => Boolean(value))
+            .join(delimiter),
+    };
+}
+async function sourceObjectDirectory(checkoutPath) {
+    const output = stdoutText(await runGit(checkoutPath, ['rev-parse', '--path-format=absolute', '--git-path', 'objects']));
+    return resolve(checkoutPath, output);
+}
+async function resolveGitRoot(checkoutPath) {
+    const output = stdoutText(await runGit(checkoutPath, ['rev-parse', '--show-toplevel']));
+    return resolve(checkoutPath, output);
+}
+function canonicalExistingPath(path) {
+    try {
+        return realpathSync.native(resolve(path));
+    }
+    catch {
+        return resolve(path);
+    }
+}
+function projectPrefix(gitRoot, projectRoot) {
+    const prefix = relative(canonicalExistingPath(gitRoot), canonicalExistingPath(projectRoot))
+        .replace(/\\/g, '/')
+        .replace(/\/$/, '');
+    if (prefix === '..' || prefix.startsWith('../') || isAbsolute(prefix))
+        return null;
+    return prefix;
+}
+function isProjectPath(repoPath, prefix) {
+    return !prefix || repoPath.startsWith(`${prefix}/`);
+}
+function toProjectPath(repoPath, prefix) {
+    return prefix ? repoPath.slice(prefix.length + 1) : repoPath;
+}
+async function isAncestor(checkoutPath, olderOid, newerOid) {
+    const result = await runGit(checkoutPath, ['merge-base', '--is-ancestor', olderOid, newerOid], { allowedExitCodes: [0, 1] });
+    return result.exitCode === 0;
+}
+async function selectEffectiveApplyBase(checkoutPath, recordedBaseOid, localHeadOid, isolatedHeadOid) {
+    // recorded base 必须能证明位于两侧真实提交历史中，才允许利用 ancestry 前移。
+    // 上次 Apply 的内部 snapshot 通常不在任一分支历史中，因此第二次 Apply 会保守使用 recorded base。
+    const recordedInLocal = await isAncestor(checkoutPath, recordedBaseOid, localHeadOid);
+    const recordedInIsolated = await isAncestor(checkoutPath, recordedBaseOid, isolatedHeadOid);
+    if (!recordedInLocal || !recordedInIsolated) {
+        return { oid: recordedBaseOid, strategy: 'recorded_base' };
+    }
+    if (await isAncestor(checkoutPath, localHeadOid, isolatedHeadOid)) {
+        return { oid: localHeadOid, strategy: 'isolated_contains_local_head' };
+    }
+    if (await isAncestor(checkoutPath, isolatedHeadOid, localHeadOid)) {
+        return { oid: isolatedHeadOid, strategy: 'local_contains_isolated_head' };
+    }
+    return { oid: recordedBaseOid, strategy: 'recorded_base' };
+}
+async function changedTreePaths(checkoutPath, baseOid, treeOid, objectDirectory, sourceObjects) {
+    const result = await runGit(checkoutPath, ['diff', '--name-only', '-z', '--no-ext-diff', '--no-renames', baseOid, treeOid, '--'], { env: gitObjectEnvironment(objectDirectory, sourceObjects) });
+    return parseNullSeparated(result.stdout);
+}
+async function captureSnapshot(checkoutPath, indexPath, objectDirectory, sourceObjects) {
+    const headOid = stdoutText(await runGit(checkoutPath, ['rev-parse', 'HEAD']));
+    const headTreeOid = stdoutText(await runGit(checkoutPath, ['rev-parse', `${headOid}^{tree}`]));
+    const symbolic = await runGit(checkoutPath, ['symbolic-ref', '--quiet', 'HEAD'], { allowedExitCodes: [0, 1] });
+    const headRef = symbolic.exitCode === 0 ? stdoutText(symbolic) : null;
+    const indexEntries = (await runGit(checkoutPath, ['ls-files', '--stage', '-z'])).stdout;
+    const stagedPatch = (await runGit(checkoutPath, [
+        'diff',
+        '--cached',
+        '--binary',
+        '--full-index',
+        '--no-ext-diff',
+        '--no-textconv',
+        '--no-renames',
+        headOid,
+        '--',
+    ])).stdout;
+    const env = {
+        ...(objectDirectory && sourceObjects ? gitObjectEnvironment(objectDirectory, sourceObjects) : {}),
+        GIT_INDEX_FILE: indexPath,
+    };
+    await runGit(checkoutPath, ['read-tree', headOid], { env });
+    if (stagedPatch.length > 0) {
+        await runGit(checkoutPath, ['apply', '--cached', '--binary', '--whitespace=nowarn'], {
+            env,
+            input: stagedPatch,
+        });
+    }
+    const indexTreeOid = stdoutText(await runGit(checkoutPath, ['write-tree'], { env }));
+    // 先还原真实 index 的 staged 语义，再叠加 working tree，得到完整最终状态。
+    await runGit(checkoutPath, ['add', '-A', '--', '.'], { env });
+    const treeOid = stdoutText(await runGit(checkoutPath, ['write-tree'], { env }));
+    const fingerprint = createHash('sha256')
+        .update(headOid)
+        .update('\0')
+        .update(headRef ?? 'DETACHED')
+        .update('\0')
+        .update(indexEntries)
+        .update('\0')
+        .update(treeOid)
+        .digest('hex');
+    return { fingerprint, headOid, headRef, headTreeOid, indexTreeOid, treeOid };
+}
+async function createSnapshotCommit(checkoutPath, treeOid, parentOid, objectDirectory, sourceObjects, label) {
+    const args = ['commit-tree', treeOid, ...(parentOid ? ['-p', parentOid] : [])];
+    const result = await runGit(checkoutPath, args, {
+        env: {
+            ...(objectDirectory && sourceObjects ? gitObjectEnvironment(objectDirectory, sourceObjects) : {}),
+            GIT_AUTHOR_NAME: 'dsh-git-worktree Apply',
+            GIT_AUTHOR_EMAIL: 'dsh-worktree-apply@localhost',
+            GIT_COMMITTER_NAME: 'dsh-git-worktree Apply',
+            GIT_COMMITTER_EMAIL: 'dsh-worktree-apply@localhost',
+        },
+        input: `${label}\n`,
+    });
+    return stdoutText(result);
+}
+async function computeMerge(tempRoot, sourceObjects, objectDirectory, baseOid, local, isolated, checkoutPath, projectPathPrefix) {
+    const localCommit = await createSnapshotCommit(checkoutPath, local.treeOid, baseOid, objectDirectory, sourceObjects, 'Local snapshot');
+    const isolatedCommit = await createSnapshotCommit(checkoutPath, isolated.treeOid, baseOid, objectDirectory, sourceObjects, 'Isolated snapshot');
+    const mergePath = join(tempRoot, 'merge checkout');
+    const hooksPath = join(tempRoot, 'disabled hooks');
+    await mkdir(mergePath, { recursive: true });
+    await mkdir(hooksPath, { recursive: true });
+    await runGit(mergePath, ['init', '--template=']);
+    await runGit(mergePath, ['config', 'core.autocrlf', 'false']);
+    await runGit(mergePath, ['config', 'core.hooksPath', hooksPath]);
+    await runGit(mergePath, ['config', 'user.name', 'dsh-git-worktree Apply']);
+    await runGit(mergePath, ['config', 'user.email', 'dsh-worktree-apply@localhost']);
+    const mergeEnv = {
+        GIT_ALTERNATE_OBJECT_DIRECTORIES: [objectDirectory, sourceObjects].join(delimiter),
+    };
+    await runGit(mergePath, ['checkout', '--detach', localCommit], { env: mergeEnv });
+    const merge = await runGit(mergePath, ['merge', '--no-commit', '--no-ff', isolatedCommit], {
+        env: mergeEnv,
+        allowedExitCodes: [0, 1],
+    });
+    if (merge.exitCode === 1) {
+        const conflicts = await runGit(mergePath, ['diff', '--name-only', '--diff-filter=U', '-z'], { env: mergeEnv });
+        const conflictingFiles = parseNullSeparated(conflicts.stdout)
+            .filter((path) => isProjectPath(path, projectPathPrefix))
+            .map((path) => toProjectPath(path, projectPathPrefix))
+            .sort();
+        if (conflictingFiles.length === 0)
+            throw new GitCommandFailure(['merge'], merge);
+        return { status: 'conflict', conflictingFiles };
+    }
+    const mergedTree = stdoutText(await runGit(mergePath, ['write-tree'], { env: mergeEnv }));
+    const changed = await runGit(mergePath, ['diff', '--name-only', '-z', '--no-ext-diff', '--no-renames', local.treeOid, mergedTree, '--'], { env: mergeEnv });
+    const patch = (await runGit(mergePath, [
+        'diff',
+        '--binary',
+        '--full-index',
+        '--no-ext-diff',
+        '--no-textconv',
+        '--no-renames',
+        local.treeOid,
+        mergedTree,
+        '--',
+    ], { env: mergeEnv })).stdout;
+    const changedFiles = parseNullSeparated(changed.stdout)
+        .filter((path) => isProjectPath(path, projectPathPrefix))
+        .map((path) => toProjectPath(path, projectPathPrefix))
+        .sort();
+    const centralIndex = join(tempRoot, 'merged-central.index');
+    const centralEnv = {
+        ...gitObjectEnvironment(objectDirectory, sourceObjects),
+        GIT_INDEX_FILE: centralIndex,
+    };
+    await runGit(checkoutPath, ['read-tree', local.treeOid], { env: centralEnv });
+    if (patch.length > 0) {
+        await runGit(checkoutPath, ['apply', '--cached', '--binary', '--whitespace=nowarn'], {
+            env: centralEnv,
+            input: patch,
+        });
+    }
+    const centralMergedTree = stdoutText(await runGit(checkoutPath, ['write-tree'], { env: centralEnv }));
+    return { status: 'ready', changedFiles, patch, mergedTreeOid: centralMergedTree };
+}
+async function computeTreeMerge(tempRoot, sourceObjects, objectDirectory, checkoutPath, label, baseTreeOid, oursTreeOid, theirsTreeOid) {
+    const baseCommit = await createSnapshotCommit(checkoutPath, baseTreeOid, null, objectDirectory, sourceObjects, `${label} base`);
+    const oursCommit = await createSnapshotCommit(checkoutPath, oursTreeOid, baseCommit, objectDirectory, sourceObjects, `${label} ours`);
+    const theirsCommit = await createSnapshotCommit(checkoutPath, theirsTreeOid, baseCommit, objectDirectory, sourceObjects, `${label} theirs`);
+    const mergePath = join(tempRoot, label.replace(/[^a-z0-9_-]+/gi, '-'));
+    const hooksPath = join(tempRoot, `${label}-disabled-hooks`.replace(/[^a-z0-9_-]+/gi, '-'));
+    await mkdir(mergePath, { recursive: true });
+    await mkdir(hooksPath, { recursive: true });
+    await runGit(mergePath, ['init', '--template=']);
+    await runGit(mergePath, ['config', 'core.autocrlf', 'false']);
+    await runGit(mergePath, ['config', 'core.hooksPath', hooksPath]);
+    await runGit(mergePath, ['config', 'user.name', 'dsh-git-worktree Apply']);
+    await runGit(mergePath, ['config', 'user.email', 'dsh-worktree-apply@localhost']);
+    const env = {
+        GIT_ALTERNATE_OBJECT_DIRECTORIES: [objectDirectory, sourceObjects].join(delimiter),
+    };
+    await runGit(mergePath, ['checkout', '--detach', oursCommit], { env });
+    const merge = await runGit(mergePath, ['merge', '--no-commit', '--no-ff', theirsCommit], {
+        env,
+        allowedExitCodes: [0, 1],
+    });
+    if (merge.exitCode === 1) {
+        const conflicts = await runGit(mergePath, ['diff', '--name-only', '--diff-filter=U', '-z'], { env });
+        const conflictingFiles = parseNullSeparated(conflicts.stdout).sort();
+        if (conflictingFiles.length === 0)
+            throw new GitCommandFailure(['merge'], merge);
+        return { status: 'conflict', conflictingFiles };
+    }
+    const mergedTreeOid = stdoutText(await runGit(mergePath, ['write-tree'], { env }));
+    const mergedPatch = (await runGit(mergePath, [
+        'diff',
+        '--binary',
+        '--full-index',
+        '--no-ext-diff',
+        '--no-textconv',
+        '--no-renames',
+        oursTreeOid,
+        mergedTreeOid,
+        '--',
+    ], { env })).stdout;
+    const centralIndex = join(tempRoot, `${label}-central.index`.replace(/[^a-z0-9_.-]+/gi, '-'));
+    const centralEnv = {
+        ...gitObjectEnvironment(objectDirectory, sourceObjects),
+        GIT_INDEX_FILE: centralIndex,
+    };
+    await runGit(checkoutPath, ['read-tree', oursTreeOid], { env: centralEnv });
+    if (mergedPatch.length > 0) {
+        await runGit(checkoutPath, ['apply', '--cached', '--binary', '--whitespace=nowarn'], {
+            env: centralEnv,
+            input: mergedPatch,
+        });
+    }
+    return { status: 'ready', treeOid: stdoutText(await runGit(checkoutPath, ['write-tree'], { env: centralEnv })) };
+}
+async function treePatch(checkoutPath, fromTreeOid, toTreeOid, objectDirectory, sourceObjects) {
+    return (await runGit(checkoutPath, [
+        'diff',
+        '--binary',
+        '--full-index',
+        '--no-ext-diff',
+        '--no-textconv',
+        '--no-renames',
+        fromTreeOid,
+        toTreeOid,
+        '--',
+    ], { env: gitObjectEnvironment(objectDirectory, sourceObjects) })).stdout;
+}
+function pathsMatch(left, right) {
+    const normalizedLeft = canonicalExistingPath(left);
+    const normalizedRight = canonicalExistingPath(right);
+    return process.platform === 'win32'
+        ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+        : normalizedLeft === normalizedRight;
+}
+function planMatches(stored, supplied) {
+    return stored.revision === supplied.revision
+        && stored.localFingerprint === supplied.localFingerprint
+        && stored.isolatedFingerprint === supplied.isolatedFingerprint
+        && stored.effectiveBaseOid === supplied.effectiveBaseOid
+        && stored.baseStrategy === supplied.baseStrategy
+        && stored.localHeadOid === supplied.localHeadOid
+        && stored.localHeadRef === supplied.localHeadRef
+        && stored.isolatedHeadOid === supplied.isolatedHeadOid
+        && stored.changedFiles.length === supplied.changedFiles.length
+        && stored.changedFiles.every((path, index) => path === supplied.changedFiles[index]);
+}
+async function prepareIndexFromPatch(checkoutPath, indexPath, baseOid, patch) {
+    const env = { GIT_INDEX_FILE: indexPath };
+    await runGit(checkoutPath, ['read-tree', baseOid], { env });
+    if (patch.length > 0) {
+        await runGit(checkoutPath, ['apply', '--cached', '--binary', '--whitespace=nowarn'], { env, input: patch });
+    }
+    return stdoutText(await runGit(checkoutPath, ['write-tree'], { env }));
+}
+async function createUserCommit(checkoutPath, treeOid, parentOid, commitMessage) {
+    return stdoutText(await runGit(checkoutPath, ['commit-tree', treeOid, '-p', parentOid], { input: `${commitMessage.trim()}\n` }));
+}
+async function resolveIndexPath(checkoutPath) {
+    return resolve(checkoutPath, stdoutText(await runGit(checkoutPath, ['rev-parse', '--path-format=absolute', '--git-path', 'index'])));
+}
+async function removeBestEffort(path) {
+    if (!path)
+        return;
+    try {
+        await unlink(path);
+    }
+    catch {
+        // 临时 index 不存在或已完成 rename 时无需处理。
+    }
+}
+class DefaultSessionCheckoutApplyEngine {
+    options;
+    plans = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    async inspectReview(input) {
+        if (!OID_PATTERN.test(input.baseOid)) {
+            return { status: 'error', error: { code: 'invalid_input', message: 'Session Base OID 格式无效' } };
+        }
+        let tempRoot = null;
+        try {
+            tempRoot = await mkdtemp(join(tmpdir(), 'dsh-wt-review-'));
+            const objectDirectory = join(tempRoot, 'objects');
+            await mkdir(objectDirectory, { recursive: true });
+            const localGitRoot = await resolveGitRoot(input.localPath);
+            const isolatedGitRoot = await resolveGitRoot(input.isolatedPath);
+            const localObjects = await sourceObjectDirectory(localGitRoot);
+            const isolatedObjects = await sourceObjectDirectory(isolatedGitRoot);
+            if (!pathsMatch(localObjects, isolatedObjects)) {
+                return { status: 'error', error: { code: 'invalid_input', message: 'Local 与 Isolated 不属于同一 Git 仓库' } };
+            }
+            const localPrefix = projectPrefix(localGitRoot, input.localPath);
+            const isolatedPrefix = projectPrefix(isolatedGitRoot, input.isolatedPath);
+            if (localPrefix === null || isolatedPrefix === null || localPrefix !== isolatedPrefix) {
+                return { status: 'error', error: { code: 'invalid_input', message: 'Local 与 Isolated 的项目子目录不一致' } };
+            }
+            await runGit(localGitRoot, ['cat-file', '-e', `${input.baseOid}^{commit}`]);
+            const isolated = await captureSnapshot(isolatedGitRoot, join(tempRoot, 'isolated.index'), objectDirectory, localObjects);
+            const changedFiles = await changedTreePaths(isolatedGitRoot, input.baseOid, isolated.treeOid, objectDirectory, localObjects);
+            if (changedFiles.some((path) => !isProjectPath(path, localPrefix))) {
+                return { status: 'error', error: { code: 'invalid_input', message: 'Isolated 包含项目根目录外的变更，不能准备验收' } };
+            }
+            return {
+                status: 'ready',
+                isolatedFingerprint: isolated.fingerprint,
+                isolatedHeadOid: isolated.headOid,
+                changedFiles: changedFiles.map((path) => toProjectPath(path, localPrefix)).sort(),
+            };
+        }
+        catch (error) {
+            return { status: 'error', error: { code: 'git_error', message: this.errorMessage(error) } };
+        }
+        finally {
+            if (tempRoot)
+                await this.cleanup(tempRoot);
+        }
+    }
+    async preflight(input) {
+        return this.calculatePlan(input, false);
+    }
+    async plan(input) {
+        return this.calculatePlan(input, true);
+    }
+    async calculatePlan(input, persistPlan) {
+        if (!OID_PATTERN.test(input.baseOid)) {
+            return { status: 'error', error: { code: 'invalid_input', message: 'Session Base OID 格式无效' } };
+        }
+        let tempRoot = null;
+        try {
+            tempRoot = await mkdtemp(join(tmpdir(), 'dsh-wt-plan-'));
+            const objectDirectory = join(tempRoot, 'objects');
+            await mkdir(objectDirectory, { recursive: true });
+            const localGitRoot = await resolveGitRoot(input.localPath);
+            const isolatedGitRoot = await resolveGitRoot(input.isolatedPath);
+            const localObjects = await sourceObjectDirectory(localGitRoot);
+            const isolatedObjects = await sourceObjectDirectory(isolatedGitRoot);
+            if (!pathsMatch(localObjects, isolatedObjects)) {
+                return { status: 'error', error: { code: 'invalid_input', message: 'Local 与 Isolated 不属于同一 Git 仓库' } };
+            }
+            const localPrefix = projectPrefix(localGitRoot, input.localPath);
+            const isolatedPrefix = projectPrefix(isolatedGitRoot, input.isolatedPath);
+            if (localPrefix === null || isolatedPrefix === null || localPrefix !== isolatedPrefix) {
+                return { status: 'error', error: { code: 'invalid_input', message: 'Local 与 Isolated 的项目子目录不一致' } };
+            }
+            await runGit(localGitRoot, ['cat-file', '-e', `${input.baseOid}^{commit}`]);
+            const local = await captureSnapshot(localGitRoot, join(tempRoot, 'local.index'), objectDirectory, localObjects);
+            const isolated = await captureSnapshot(isolatedGitRoot, join(tempRoot, 'isolated.index'), objectDirectory, localObjects);
+            const effectiveBase = await selectEffectiveApplyBase(localGitRoot, input.baseOid, local.headOid, isolated.headOid);
+            const isolatedChangedPaths = await changedTreePaths(isolatedGitRoot, effectiveBase.oid, isolated.treeOid, objectDirectory, localObjects);
+            if (isolatedChangedPaths.some((path) => !isProjectPath(path, localPrefix))) {
+                return {
+                    status: 'error',
+                    error: { code: 'invalid_input', message: 'Isolated 包含项目根目录外的变更，已拒绝 Apply' },
+                };
+            }
+            const merge = await computeMerge(tempRoot, localObjects, objectDirectory, effectiveBase.oid, local, isolated, localGitRoot, localPrefix);
+            const revision = randomUUID();
+            if (merge.status === 'conflict') {
+                return {
+                    status: 'conflict',
+                    revision,
+                    localFingerprint: local.fingerprint,
+                    isolatedFingerprint: isolated.fingerprint,
+                    effectiveBaseOid: effectiveBase.oid,
+                    baseStrategy: effectiveBase.strategy,
+                    localHeadOid: local.headOid,
+                    isolatedHeadOid: isolated.headOid,
+                    conflictingFiles: merge.conflictingFiles,
+                };
+            }
+            const plan = {
+                revision,
+                localFingerprint: local.fingerprint,
+                isolatedFingerprint: isolated.fingerprint,
+                effectiveBaseOid: effectiveBase.oid,
+                baseStrategy: effectiveBase.strategy,
+                localHeadOid: local.headOid,
+                localHeadRef: local.headRef,
+                isolatedHeadOid: isolated.headOid,
+                changedFiles: merge.changedFiles,
+            };
+            if (persistPlan) {
+                this.plans.set(revision, {
+                    input: { ...input },
+                    patch: merge.patch,
+                    plan: { ...plan, changedFiles: [...plan.changedFiles] },
+                    scope: {
+                        isolatedGitRoot,
+                        localGitRoot,
+                        projectPrefix: localPrefix,
+                        sourceObjects: localObjects,
+                    },
+                });
+            }
+            return { status: 'ready', plan: { ...plan, changedFiles: [...plan.changedFiles] } };
+        }
+        catch (error) {
+            return { status: 'error', error: { code: 'git_error', message: this.errorMessage(error) } };
+        }
+        finally {
+            if (tempRoot)
+                await this.cleanup(tempRoot);
+        }
+    }
+    async apply(plan) {
+        const stored = this.plans.get(plan.revision);
+        if (!stored || !planMatches(stored.plan, plan)) {
+            return { status: 'error', error: { code: 'invalid_plan', message: 'Apply plan 不存在、已使用或已被修改' } };
+        }
+        let tempRoot = null;
+        try {
+            tempRoot = await mkdtemp(join(tmpdir(), 'dsh-wt-apply-'));
+            const objectDirectory = join(tempRoot, 'objects');
+            await mkdir(objectDirectory, { recursive: true });
+            const sourceObjects = await sourceObjectDirectory(stored.scope.localGitRoot);
+            if (!pathsMatch(sourceObjects, stored.scope.sourceObjects)) {
+                return { status: 'error', error: { code: 'invalid_plan', message: 'Apply plan 的 Git 仓库身份已变化' } };
+            }
+            const local = await captureSnapshot(stored.scope.localGitRoot, join(tempRoot, 'local.index'), objectDirectory, sourceObjects);
+            if (local.headOid !== stored.plan.localHeadOid || local.fingerprint !== stored.plan.localFingerprint) {
+                return { status: 'error', error: { code: 'stale_local', message: 'Local 在 plan 后发生变化，请重新计算' } };
+            }
+            const isolated = await captureSnapshot(stored.scope.isolatedGitRoot, join(tempRoot, 'isolated.index'), objectDirectory, sourceObjects);
+            if (isolated.headOid !== stored.plan.isolatedHeadOid || isolated.fingerprint !== stored.plan.isolatedFingerprint) {
+                return { status: 'error', error: { code: 'stale_isolated', message: 'Isolated 在 plan 后发生变化，请重新计算' } };
+            }
+            // 将已审核的 Isolated 最终状态写成无 ref 的内部 commit，供同一 checkout 后续 Apply 去重。
+            // 使用独立 index，不改变 Isolated 的真实 staged/working tree。
+            const persistentIsolated = await captureSnapshot(stored.scope.isolatedGitRoot, join(tempRoot, 'persistent-isolated.index'), null, null);
+            if (persistentIsolated.fingerprint !== stored.plan.isolatedFingerprint) {
+                return { status: 'error', error: { code: 'stale_isolated', message: 'Isolated 在 plan 后发生变化，请重新计算' } };
+            }
+            const nextBaseOid = await createSnapshotCommit(stored.scope.isolatedGitRoot, persistentIsolated.treeOid, stored.plan.effectiveBaseOid, null, null, 'Applied Isolated snapshot');
+            await this.options.beforeFinalLocalValidation?.();
+            const finalLocal = await captureSnapshot(stored.scope.localGitRoot, join(tempRoot, 'final-local.index'), objectDirectory, sourceObjects);
+            if (finalLocal.headOid !== stored.plan.localHeadOid || finalLocal.fingerprint !== stored.plan.localFingerprint) {
+                return {
+                    status: 'error',
+                    error: { code: 'stale_local', message: 'Local 在 Apply 写入前发生变化，请重新计算' },
+                };
+            }
+            if (stored.patch.length > 0) {
+                await runGit(stored.scope.localGitRoot, ['apply', '--binary', '--whitespace=nowarn'], { input: stored.patch });
+            }
+            this.plans.delete(plan.revision);
+            return { status: 'applied', changedFiles: [...stored.plan.changedFiles], nextBaseOid };
+        }
+        catch (error) {
+            return { status: 'error', error: { code: 'git_error', message: this.errorMessage(error) } };
+        }
+        finally {
+            if (tempRoot)
+                await this.cleanup(tempRoot);
+        }
+    }
+    async finish(plan, options) {
+        const stored = this.plans.get(plan.revision);
+        if (!stored || !planMatches(stored.plan, plan)) {
+            return { status: 'error', error: { code: 'invalid_plan', message: 'Finish plan 不存在、已使用或已被修改' } };
+        }
+        const commitMessage = options.commitMessage.trim();
+        if (!commitMessage) {
+            return { status: 'error', error: { code: 'invalid_input', message: '提交信息不能为空' } };
+        }
+        if (!stored.plan.localHeadRef?.startsWith('refs/heads/')) {
+            return {
+                status: 'error',
+                error: { code: 'operation_not_allowed', message: 'Local 当前不是普通分支，不能自动创建任务提交' },
+            };
+        }
+        let tempRoot = null;
+        let adjacentIndex = null;
+        try {
+            tempRoot = await mkdtemp(join(tmpdir(), 'dsh-wt-finish-'));
+            const objectDirectory = join(tempRoot, 'objects');
+            await mkdir(objectDirectory, { recursive: true });
+            const sourceObjects = await sourceObjectDirectory(stored.scope.localGitRoot);
+            if (!pathsMatch(sourceObjects, stored.scope.sourceObjects)) {
+                return { status: 'error', error: { code: 'invalid_plan', message: 'Finish plan 的 Git 仓库身份已变化' } };
+            }
+            const local = await captureSnapshot(stored.scope.localGitRoot, join(tempRoot, 'local.index'), objectDirectory, sourceObjects);
+            if (local.headOid !== stored.plan.localHeadOid
+                || local.headRef !== stored.plan.localHeadRef
+                || local.fingerprint !== stored.plan.localFingerprint) {
+                return { status: 'error', error: { code: 'stale_local', message: 'Local 在 plan 后发生变化，请重新计算' } };
+            }
+            const isolated = await captureSnapshot(stored.scope.isolatedGitRoot, join(tempRoot, 'isolated.index'), objectDirectory, sourceObjects);
+            if (isolated.headOid !== stored.plan.isolatedHeadOid || isolated.fingerprint !== stored.plan.isolatedFingerprint) {
+                return { status: 'error', error: { code: 'stale_isolated', message: 'Isolated 在 plan 后发生变化，请重新计算' } };
+            }
+            const merge = await computeMerge(tempRoot, sourceObjects, objectDirectory, stored.plan.effectiveBaseOid, local, isolated, stored.scope.localGitRoot, stored.scope.projectPrefix);
+            if (merge.status === 'conflict') {
+                return {
+                    status: 'error',
+                    error: { code: 'invalid_plan', message: 'Finish 复验得到与已审核 plan 不一致的冲突' },
+                };
+            }
+            if (merge.changedFiles.length !== stored.plan.changedFiles.length
+                || merge.changedFiles.some((path, index) => path !== stored.plan.changedFiles[index])) {
+                return { status: 'error', error: { code: 'invalid_plan', message: 'Finish 复验的文件集合已变化' } };
+            }
+            const persistentIsolated = await captureSnapshot(stored.scope.isolatedGitRoot, join(tempRoot, 'persistent-isolated.index'), null, null);
+            if (persistentIsolated.fingerprint !== stored.plan.isolatedFingerprint) {
+                return { status: 'error', error: { code: 'stale_isolated', message: 'Isolated 在 plan 后发生变化，请重新计算' } };
+            }
+            const nextBaseOid = await createSnapshotCommit(stored.scope.isolatedGitRoot, persistentIsolated.treeOid, stored.plan.effectiveBaseOid, null, null, 'Finished Isolated snapshot');
+            if (merge.changedFiles.length === 0) {
+                await this.options.beforeFinalLocalValidation?.();
+                const finalLocal = await captureSnapshot(stored.scope.localGitRoot, join(tempRoot, 'final-local.index'), objectDirectory, sourceObjects);
+                if (finalLocal.fingerprint !== stored.plan.localFingerprint) {
+                    return { status: 'error', error: { code: 'stale_local', message: 'Local 在 Finish 前发生变化，请重新计算' } };
+                }
+                this.plans.delete(plan.revision);
+                return { status: 'finished', changedFiles: [], commitOid: null, nextBaseOid };
+            }
+            // C = H + (M - L)：把任务增量从完整 Local 快照 L 中剥离，重放到旧 HEAD H。
+            const taskTree = await computeTreeMerge(tempRoot, sourceObjects, objectDirectory, stored.scope.localGitRoot, 'finish-task-isolation', local.treeOid, local.headTreeOid, merge.mergedTreeOid);
+            if (taskTree.status === 'conflict') {
+                return {
+                    status: 'error',
+                    error: {
+                        code: 'commit_isolation_conflict',
+                        message: `任务增量无法与 Local 原有修改可靠拆分：${taskTree.conflictingFiles.join('、')}`,
+                    },
+                };
+            }
+            // S' = C + (S - H)：在任务提交 C 上恢复用户原有 staged 状态。
+            const finalIndexTree = await computeTreeMerge(tempRoot, sourceObjects, objectDirectory, stored.scope.localGitRoot, 'finish-index-preservation', local.headTreeOid, taskTree.treeOid, local.indexTreeOid);
+            if (finalIndexTree.status === 'conflict') {
+                return {
+                    status: 'error',
+                    error: {
+                        code: 'commit_isolation_conflict',
+                        message: `任务提交与 Local 原有 staged 修改无法可靠分离：${finalIndexTree.conflictingFiles.join('、')}`,
+                    },
+                };
+            }
+            const taskPatch = await treePatch(stored.scope.localGitRoot, local.headTreeOid, taskTree.treeOid, objectDirectory, sourceObjects);
+            const finalIndexPatch = await treePatch(stored.scope.localGitRoot, taskTree.treeOid, finalIndexTree.treeOid, objectDirectory, sourceObjects);
+            const taskIndexPath = join(tempRoot, 'task-commit.index');
+            const actualTaskTreeOid = await prepareIndexFromPatch(stored.scope.localGitRoot, taskIndexPath, local.headOid, taskPatch);
+            const commitOid = await createUserCommit(stored.scope.localGitRoot, actualTaskTreeOid, local.headOid, commitMessage);
+            const finalIndexPath = join(tempRoot, 'preserved-local.index');
+            await prepareIndexFromPatch(stored.scope.localGitRoot, finalIndexPath, commitOid, finalIndexPatch);
+            await this.options.beforeFinalLocalValidation?.();
+            const finalLocal = await captureSnapshot(stored.scope.localGitRoot, join(tempRoot, 'final-local-validation.index'), objectDirectory, sourceObjects);
+            if (finalLocal.headOid !== stored.plan.localHeadOid
+                || finalLocal.headRef !== stored.plan.localHeadRef
+                || finalLocal.fingerprint !== stored.plan.localFingerprint) {
+                return { status: 'error', error: { code: 'stale_local', message: 'Local 在 Finish 写入前发生变化，请重新计算' } };
+            }
+            const realIndexPath = await resolveIndexPath(stored.scope.localGitRoot);
+            adjacentIndex = `${realIndexPath}.dsh-wt-${randomUUID()}`;
+            await copyFile(finalIndexPath, adjacentIndex);
+            let worktreePatched = false;
+            let refUpdated = false;
+            try {
+                if (merge.patch.length > 0) {
+                    await runGit(stored.scope.localGitRoot, ['apply', '--binary', '--whitespace=nowarn'], { input: merge.patch });
+                    worktreePatched = true;
+                }
+                await runGit(stored.scope.localGitRoot, [
+                    'update-ref',
+                    stored.plan.localHeadRef,
+                    commitOid,
+                    local.headOid,
+                ]);
+                refUpdated = true;
+                await rename(adjacentIndex, realIndexPath);
+                adjacentIndex = null;
+            }
+            catch (error) {
+                const rollbackErrors = [];
+                if (refUpdated) {
+                    try {
+                        await runGit(stored.scope.localGitRoot, [
+                            'update-ref',
+                            stored.plan.localHeadRef,
+                            local.headOid,
+                            commitOid,
+                        ]);
+                    }
+                    catch (rollbackError) {
+                        rollbackErrors.push(`ref: ${this.errorMessage(rollbackError)}`);
+                    }
+                }
+                if (worktreePatched) {
+                    try {
+                        await runGit(stored.scope.localGitRoot, ['apply', '-R', '--binary', '--whitespace=nowarn'], { input: merge.patch });
+                    }
+                    catch (rollbackError) {
+                        rollbackErrors.push(`worktree: ${this.errorMessage(rollbackError)}`);
+                    }
+                }
+                const detail = this.errorMessage(error);
+                if (rollbackErrors.length > 0) {
+                    return {
+                        status: 'error',
+                        error: {
+                            code: 'git_error',
+                            message: `Finish 写入失败且无法证明完整回滚：${detail}；${rollbackErrors.join('；')}`,
+                        },
+                    };
+                }
+                return { status: 'error', error: { code: 'git_error', message: `Finish 写入失败，已回滚：${detail}` } };
+            }
+            this.plans.delete(plan.revision);
+            return {
+                status: 'finished',
+                changedFiles: [...stored.plan.changedFiles],
+                commitOid,
+                nextBaseOid,
+            };
+        }
+        catch (error) {
+            return { status: 'error', error: { code: 'git_error', message: this.errorMessage(error) } };
+        }
+        finally {
+            await removeBestEffort(adjacentIndex);
+            if (tempRoot)
+                await this.cleanup(tempRoot);
+        }
+    }
+    errorMessage(error) {
+        if (error instanceof GitCommandFailure) {
+            return `Git 操作失败（${error.args[0] ?? 'unknown'}）：${error.message}`;
+        }
+        return error instanceof Error ? error.message : '未知 Git 错误';
+    }
+    async cleanup(path) {
+        try {
+            await rm(path, { recursive: true, force: true, maxRetries: 2 });
+        }
+        catch (error) {
+            // 清理失败不能掩盖 plan/apply 的主结果。
+            console.warn('[session-checkout-apply] 临时目录清理失败：', error);
+        }
+    }
+}
+export function createSessionCheckoutApplyEngine(options = {}) {
+    return new DefaultSessionCheckoutApplyEngine(options);
+}
+//# sourceMappingURL=session-checkout-apply.js.map