dsh-git-worktree 0.8.0 → 0.9.2

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA0BH,2FAA2F;AAC3F,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,IAAI,CAA0B;IAEvC;;;OAGG;IACH,YAAY,IAA8B,EAAE,OAAe;QACzD,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;QAClC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AA6GD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACnC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,CAAC,MAAM,0BAA0B,CAAA;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzD,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAA;AACnE,OAAO,EAAE,+BAA+B,EAAE,MAAM,mCAAmC,CAAA;AACnF,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,EAAE,gCAAgC,EAAE,MAAM,6BAA6B,CAAA;AAC9E,OAAO,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAA;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAA;AACvD,OAAO,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAA;AAC1E,OAAO,EAAE,iCAAiC,EAAE,MAAM,iCAAiC,CAAA;AACnF,OAAO,EAAE,iCAAiC,EAAE,MAAM,+BAA+B,CAAA;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAA;AAElE,cAAc,uBAAuB,CAAA;AAErC,MAAM,IAAI,GAAG,cAAc,CAAA;AAC3B,sEAAsE;AACtE,0EAA0E;AAC1E,+EAA+E;AAC/E,MAAM,CAAC,MAAM,MAAM,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAA;AAE3F,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;CACrB,CAAC,CAAA;AAEF,SAAS,eAAe,CAAC,MAA6B;IACpD,IAAI,MAAM,CAAC,QAAQ;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IACpD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC,CAAA;IACpE,OAAO,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,kBAAkB,CAAC,CAAA;AAClD,CAAC;AAED,MAAM,iCAAiC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;AAExD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,GAAY,EAAE,SAAgC,EAAE;IAC1E,MAAM,+BAA+B,CAAC,GAAG,CAAC,CAAA;IAC1C,MAAM,QAAQ,GAAG,eAAe,CAAC,MAAM,CAAC,CAAA;IACxC,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACxC,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,EAAE,oBAAoB,CAAC,CAAA;IACtD,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAEzC,MAAM,MAAM,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAA;IACvC,MAAM,GAAG,GAAG,gBAAgB,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,CAAC,CAAA;IAChD,MAAM,KAAK,GAAG,mBAAmB,EAAE,CAAA;IACnC,MAAM,QAAQ,GAAG,IAAI,0BAA0B,CAAC,IAAI,CAAC,QAAQ,EAAE,wBAAwB,CAAC,CAAC,CAAA;IACzF,MAAM,MAAM,GAAG,2BAA2B,CAAC;QACzC,MAAM;QACN,GAAG;QACH,KAAK;QACL,QAAQ;QACR,WAAW,EAAE,gCAAgC,EAAE;QAC/C,oBAAoB,EAAE,QAAQ;QAC9B,gBAAgB,EAAE,UAAU;KAC7B,CAAC,CAAA;IAEF,IAAI,sBAAsB,CAAC,GAAG,EAAE,iCAAiC,CAAC;QAChE,MAAM;QACN,MAAM;QACN,KAAK;QACL,QAAQ;QACR,GAAG;QACH,UAAU,EAAE,iCAAiC,EAAE;KAChD,CAAC,CAAC,CAAA;IAEH,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;IAC1B,uBAAuB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;IACpC,4BAA4B,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;IAEzC,wEAAwE;IACxE,yEAAyE;IACzE,qCAAqC;IACrC,MAAM,gBAAgB,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;QACnD,KAAK,MAAM,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACtC,OAAO,CAAC,IAAI,CAAC,sCAAsC,EAAE,KAAK,CAAC,CAAA;QAC7D,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IACF,MAAM,cAAc,GAAG,WAAW,CAAC,GAAG,EAAE;QACtC,KAAK,MAAM,CAAC,sBAAsB,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACnD,OAAO,CAAC,IAAI,CAAC,0DAA0D,EAAE,KAAK,CAAC,CAAA;QACjF,CAAC,CAAC,CAAA;IACJ,CAAC,EAAE,iCAAiC,CAAC,CAAA;IACrC,cAAc,CAAC,KAAK,EAAE,EAAE,CAAA;IACxB,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE;QACpB,gBAAgB,EAAE,CAAA;QAClB,aAAa,CAAC,cAAc,CAAC,CAAA;IAC/B,CAAC,CAAC,CAAA;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/ports.d.ts

@@ -19,7 +19,14 @@ export interface SessionCheckoutProjectRecord {
     name: string;
     root: string;
 }
+export interface SidebarDirectoryMembership {
+    managedRoot: string;
+    workspaceIds: string[];
+    sessionIds: string[];
+}
 export interface SessionCheckoutLookupPort {
+    /** Read-only navigation evidence; never used to authorize a checkout operation. */
+    getSidebarMemberships?(managedRoots: readonly string[]): Promise<SidebarDirectoryMembership[]>;
     getSession(sessionId: string): SessionCheckoutSessionRecord | undefined;
     getProject(projectId: string): SessionCheckoutProjectRecord | undefined;
 }
@@ -31,14 +38,22 @@ export interface GitCheckoutSnapshot {
     headOid: string;
     headRef: string;
 }
+export interface InitialCommitPreflight {
+    kind: 'ready' | 'empty' | 'files';
+    fingerprint: string;
+    snapshot: GitCheckoutSnapshot;
+}
 export interface SessionCheckoutGitPort {
+    /** Optional for third-party ports; unsupported ports must not initialize. */
+    preflightInitialCommit?(root: string): Promise<InitialCommitPreflight>;
+    initializeEmptyRepository?(root: string, fingerprint: string, assertAuthorized?: () => Promise<void>): Promise<string>;
     inspect(root: string): Promise<GitCheckoutSnapshot | null>;
     /** Top-level of the Git checkout containing the directory; does not require a HEAD. */
     findContainingWorktreeRoot(root: string): Promise<string | null>;
     status(root: string): Promise<{
         dirty: boolean;
     }>;
-    createDetachedWorktree(localRoot: string, managedRoot: string, baseOid: string): Promise<void>;
+    createDetachedWorktree(localRoot: string, managedRoot: string, baseOid: string, saveEvidence?: (evidence: WorktreeCreationEvidence) => void): Promise<void>;
     /** Deletion after the host verified checkout identity and the full fingerprint including untracked. */
     removeWorktree(localRoot: string, managedRoot: string): Promise<void>;
     retainApplyBase(localRoot: string, checkoutId: string, oid: string): Promise<void>;
@@ -84,9 +99,23 @@ interface ManagedCheckoutJournalBase {
     operationId: string;
     startedAt: number;
 }
+export interface WorktreeCreationEvidence {
+    root: string;
+    rootIdentity: DirectoryIdentity;
+    parentIdentity: DirectoryIdentity;
+    commonDir: string;
+    commonIdentity: DirectoryIdentity;
+    lockReason: string;
+    gitDir?: string;
+    gitIdentity?: DirectoryIdentity;
+    metadataFingerprint?: string;
+    indexFingerprint?: string;
+    quarantinePath?: string;
+}
 export interface ManagedCheckoutCreateJournal extends ManagedCheckoutJournalBase {
     operation: 'create';
     step: 'creating_worktree';
+    creation?: WorktreeCreationEvidence;
 }
 export interface ManagedCheckoutMutationJournal extends ManagedCheckoutJournalBase {
     operation: 'apply' | 'preview' | 'checkpoint' | 'rollback_preview' | 'finish' | 'finalize_preview' | 'cleanup';

package/lib/session-checkout-apply.d.ts

@@ -1,3 +1,4 @@
+import { type ProjectSkillStore } from './adapters/project-skills.js';
 import type { ApplyBaseStrategy } from './types.js';
 export interface ApplyPlanInput {
     baseOid: string;
@@ -227,6 +228,7 @@ export interface SessionCheckoutApplyEngine {
     }): Promise<FinishResult>;
 }
 export interface SessionCheckoutApplyEngineOptions {
+    projectSkills?: ProjectSkillStore;
     /** 测试/宿主 seam：在最后一次 Local fingerprint 校验前执行。 */
     beforeFinalLocalValidation?(): Promise<void> | void;
     /** 测试/宿主 seam：在 Local 写入完成、独立写后验证开始前执行。 */

package/lib/session-checkout-apply.js

@@ -1,3 +1,4 @@
+import { trackedSkillPaths } from './adapters/project-skills.js';
 import { hostMessage } from './i18n/host.js';
 import { spawn } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
@@ -18,7 +19,11 @@ 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], {
+        // Review/delivery must support the same Windows paths as initial creation.
+        const child = spawn('git', [
+            ...(process.platform === 'win32' ? ['-c', 'core.longpaths=true'] : []),
+            '-c', 'core.quotePath=false', ...args,
+        ], {
             cwd,
             env: {
                 ...process.env,
@@ -145,7 +150,7 @@ function snapshotFingerprint(headOid, headRef, indexEntries, treeOid) {
         .update(treeOid)
         .digest('hex');
 }
-async function captureSnapshot(checkoutPath, indexPath, objectDirectory, sourceObjects) {
+async function captureSnapshot(checkoutPath, indexPath, objectDirectory, sourceObjects, projectSkills) {
     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] });
@@ -176,8 +181,16 @@ async function captureSnapshot(checkoutPath, indexPath, objectDirectory, sourceO
     const indexTreeOid = stdoutText(await runGit(checkoutPath, ['write-tree'], { env }));
     // 先还原真实 index 的 staged 语义，再叠加 working tree，得到完整最终状态。
     await runGit(checkoutPath, ['add', '-A', '--', '.'], { env });
+    let carried = null;
+    if (await projectSkills?.paths(checkoutPath)) {
+        const headPaths = (await runGit(checkoutPath, ['ls-tree', '-r', '--name-only', '-z', headOid])).stdout;
+        carried = await projectSkills.state(checkoutPath, trackedSkillPaths(indexEntries, headPaths));
+        if (carried?.paths.length)
+            await runGit(checkoutPath, ['update-index', '--force-remove', '-z', '--stdin'], { env, input: Buffer.from(carried.paths.join('\0') + '\0') });
+    }
     const treeOid = stdoutText(await runGit(checkoutPath, ['write-tree'], { env }));
-    const fingerprint = snapshotFingerprint(headOid, headRef, indexEntries, treeOid);
+    const primaryFingerprint = snapshotFingerprint(headOid, headRef, indexEntries, treeOid);
+    const fingerprint = carried?.paths.length ? createHash('sha256').update(primaryFingerprint).update(carried.fingerprint).digest('hex') : primaryFingerprint;
     return { fingerprint, headOid, headRef, headTreeOid, indexTreeOid, treeOid, indexEntries };
 }
 async function createSnapshotCommit(checkoutPath, treeOid, parentOid, objectDirectory, sourceObjects, label) {
@@ -527,6 +540,9 @@ class DefaultSessionCheckoutApplyEngine {
     constructor(options) {
         this.options = options;
     }
+    captureSnapshot(checkoutPath, indexPath, objectDirectory, sourceObjects) {
+        return captureSnapshot(checkoutPath, indexPath, objectDirectory, sourceObjects, this.options.projectSkills);
+    }
     async checkpoint(input) {
         const commitMessage = input.commitMessage.trim();
         if (!commitMessage || commitMessage.length > 500 || !OID_PATTERN.test(input.expectedHeadOid) || !input.expectedFingerprint.trim()) {
@@ -543,7 +559,7 @@ class DefaultSessionCheckoutApplyEngine {
             if (projectPathPrefix === null) {
                 return { status: 'error', error: { code: 'invalid_input', message: hostMessage('theCheckpointProjectDirectoryDoesNotBelongToThe') } };
             }
-            const snapshot = await captureSnapshot(isolatedGitRoot, join(tempRoot, 'checkpoint.index'), null, null);
+            const snapshot = await this.captureSnapshot(isolatedGitRoot, join(tempRoot, 'checkpoint.index'), null, null);
             if (snapshot.headRef !== null) {
                 return { status: 'error', error: { code: 'operation_not_allowed', message: hostMessage('checkpointCanOnlyWriteToADetachedManagedWorktree') } };
             }
@@ -571,7 +587,7 @@ class DefaultSessionCheckoutApplyEngine {
             await indexLock.close();
             await copyFile(finalIndexPath, adjacentIndex);
             await this.options.beforeFinalIsolatedValidation?.();
-            const finalSnapshot = await captureSnapshot(isolatedGitRoot, join(tempRoot, 'final-checkpoint.index'), null, null);
+            const finalSnapshot = await this.captureSnapshot(isolatedGitRoot, join(tempRoot, 'final-checkpoint.index'), null, null);
             if (finalSnapshot.headOid !== snapshot.headOid || finalSnapshot.fingerprint !== snapshot.fingerprint) {
                 return { status: 'error', error: { code: 'stale_isolated', message: hostMessage('worktreeChangedBeforeSavingTheCheckpointPrepareTheReview') } };
             }
@@ -612,7 +628,7 @@ class DefaultSessionCheckoutApplyEngine {
             }
             try {
                 await this.options.afterIsolatedWriteBeforeVerification?.();
-                const completed = await captureSnapshot(isolatedGitRoot, join(tempRoot, 'completed.index'), null, null);
+                const completed = await this.captureSnapshot(isolatedGitRoot, join(tempRoot, 'completed.index'), null, null);
                 if (completed.headOid !== commitOid
                     || completed.headRef !== null
                     || completed.headTreeOid !== snapshot.treeOid
@@ -676,7 +692,7 @@ class DefaultSessionCheckoutApplyEngine {
             const targetTreeOid = stdoutText(await runGit(isolatedGitRoot, ['rev-parse', `${input.commitOid}^{tree}`]));
             const existingLock = await inspectIndexFileTree(isolatedGitRoot, indexLockPath);
             const markerOwned = await checkpointLockMarkerOwned(indexLockMarker, input.commitOid);
-            const snapshot = await captureSnapshot(isolatedGitRoot, join(tempRoot, 'current.index'), null, null);
+            const snapshot = await this.captureSnapshot(isolatedGitRoot, join(tempRoot, 'current.index'), null, null);
             if (snapshot.headRef !== null) {
                 return { status: 'error', error: { code: 'stale_isolated', message: hostMessage('worktreeNoLongerHasADetachedHEAD') } };
             }
@@ -720,7 +736,7 @@ class DefaultSessionCheckoutApplyEngine {
                 await copyFile(cleanIndexPath, indexLockPath);
             }
             await this.options.beforeFinalIsolatedValidation?.();
-            const lockedSnapshot = await captureSnapshot(isolatedGitRoot, join(tempRoot, 'locked-current.index'), null, null);
+            const lockedSnapshot = await this.captureSnapshot(isolatedGitRoot, join(tempRoot, 'locked-current.index'), null, null);
             if (lockedSnapshot.headOid !== snapshot.headOid
                 || lockedSnapshot.fingerprint !== snapshot.fingerprint
                 || (lockedSnapshot.indexTreeOid !== input.expectedIndexTreeOid && lockedSnapshot.indexTreeOid !== lockedSnapshot.headTreeOid)) {
@@ -730,7 +746,7 @@ class DefaultSessionCheckoutApplyEngine {
             ownedIndexLock = null;
             await removeBestEffort(indexLockMarker);
             ownedLockMarker = null;
-            const completed = await captureSnapshot(isolatedGitRoot, join(tempRoot, 'completed.index'), null, null);
+            const completed = await this.captureSnapshot(isolatedGitRoot, join(tempRoot, 'completed.index'), null, null);
             if (completed.headOid !== input.commitOid
                 || completed.headRef !== null
                 || completed.indexTreeOid !== completed.headTreeOid
@@ -771,7 +787,7 @@ class DefaultSessionCheckoutApplyEngine {
                 return { status: 'error', error: { code: 'invalid_input', message: hostMessage('theLocalAndIsolatedProjectSubdirectoriesDoNotMatch') } };
             }
             await runGit(localGitRoot, ['cat-file', '-e', `${input.baseOid}^{commit}`]);
-            const isolated = await captureSnapshot(isolatedGitRoot, join(tempRoot, 'isolated.index'), objectDirectory, localObjects);
+            const isolated = await this.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: hostMessage('isolatedContainsChangesOutsideTheProjectRootAReview') } };
@@ -819,8 +835,8 @@ class DefaultSessionCheckoutApplyEngine {
                 return { status: 'error', error: { code: 'invalid_input', message: hostMessage('theLocalAndIsolatedProjectSubdirectoriesDoNotMatch') } };
             }
             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 local = await this.captureSnapshot(localGitRoot, join(tempRoot, 'local.index'), objectDirectory, localObjects);
+            const isolated = await this.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))) {
@@ -892,23 +908,23 @@ class DefaultSessionCheckoutApplyEngine {
             if (!pathsMatch(sourceObjects, stored.scope.sourceObjects)) {
                 return { status: 'error', error: { code: 'invalid_plan', message: hostMessage('theApplyPlanSGitRepositoryIdentityHasChanged') } };
             }
-            const local = await captureSnapshot(stored.scope.localGitRoot, join(tempRoot, 'local.index'), objectDirectory, sourceObjects);
+            const local = await this.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: hostMessage('localChangedAfterPlanningRecalculateThePlan') } };
             }
-            const isolated = await captureSnapshot(stored.scope.isolatedGitRoot, join(tempRoot, 'isolated.index'), objectDirectory, sourceObjects);
+            const isolated = await this.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: hostMessage('isolatedChangedAfterPlanningRecalculateThePlan') } };
             }
             // 将已审核的 Isolated 最终状态写成无 ref 的内部 commit，供同一 checkout 后续 Apply 去重。
             // 使用独立 index，不改变 Isolated 的真实 staged/working tree。
-            const persistentIsolated = await captureSnapshot(stored.scope.isolatedGitRoot, join(tempRoot, 'persistent-isolated.index'), null, null);
+            const persistentIsolated = await this.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: hostMessage('isolatedChangedAfterPlanningRecalculateThePlan') } };
             }
             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);
+            const finalLocal = await this.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',
@@ -946,18 +962,18 @@ class DefaultSessionCheckoutApplyEngine {
             if (!pathsMatch(sourceObjects, stored.scope.sourceObjects)) {
                 return { status: 'error', error: { code: 'invalid_plan', message: hostMessage('thePreviewPlanSGitRepositoryIdentityHasChanged') } };
             }
-            const local = await captureSnapshot(stored.scope.localGitRoot, join(tempRoot, 'local.index'), objectDirectory, sourceObjects);
+            const local = await this.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: hostMessage('localChangedAfterPlanningRecalculateThePlan') } };
             }
-            const isolated = await captureSnapshot(stored.scope.isolatedGitRoot, join(tempRoot, 'isolated.index'), objectDirectory, sourceObjects);
+            const isolated = await this.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: hostMessage('isolatedChangedAfterPlanningRecalculateThePlan') } };
             }
-            const persistentLocal = await captureSnapshot(stored.scope.localGitRoot, join(tempRoot, 'persistent-local.index'), null, null);
-            const persistentIsolated = await captureSnapshot(stored.scope.isolatedGitRoot, join(tempRoot, 'persistent-isolated.index'), null, null);
+            const persistentLocal = await this.captureSnapshot(stored.scope.localGitRoot, join(tempRoot, 'persistent-local.index'), null, null);
+            const persistentIsolated = await this.captureSnapshot(stored.scope.isolatedGitRoot, join(tempRoot, 'persistent-isolated.index'), null, null);
             if (persistentLocal.fingerprint !== stored.plan.localFingerprint
                 || persistentIsolated.fingerprint !== stored.plan.isolatedFingerprint) {
                 return { status: 'error', error: { code: 'invalid_plan', message: hostMessage('thePersistentPreviewSnapshotDoesNotMatchTheReviewed') } };
@@ -985,7 +1001,7 @@ class DefaultSessionCheckoutApplyEngine {
                 changedFiles: [...stored.plan.changedFiles],
             };
             await this.options.beforeFinalLocalValidation?.();
-            const finalLocal = await captureSnapshot(stored.scope.localGitRoot, join(tempRoot, 'final-local.index'), objectDirectory, sourceObjects);
+            const finalLocal = await this.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: hostMessage('localChangedBeforePreviewWroteItsChangesRecalculateThe') } };
             }
@@ -993,7 +1009,7 @@ class DefaultSessionCheckoutApplyEngine {
             if (stored.patch.length > 0) {
                 await runGit(stored.scope.localGitRoot, ['apply', '--binary', '--whitespace=nowarn'], { input: stored.patch });
             }
-            const previewedLocal = await captureSnapshot(stored.scope.localGitRoot, join(tempRoot, 'previewed-local.index'), null, null);
+            const previewedLocal = await this.captureSnapshot(stored.scope.localGitRoot, join(tempRoot, 'previewed-local.index'), null, null);
             if (previewedLocal.treeOid !== previewWorkingTreeOid) {
                 return {
                     status: 'error',
@@ -1023,7 +1039,7 @@ class DefaultSessionCheckoutApplyEngine {
             const objectDirectory = join(tempRoot, 'objects');
             await mkdir(objectDirectory, { recursive: true });
             const sourceObjects = await sourceObjectDirectory(localGitRoot);
-            const current = await captureSnapshot(localGitRoot, join(tempRoot, 'current.index'), objectDirectory, sourceObjects);
+            const current = await this.captureSnapshot(localGitRoot, join(tempRoot, 'current.index'), objectDirectory, sourceObjects);
             const rollback = await prepareRollbackAssessment(tempRoot, sourceObjects, objectDirectory, localGitRoot, current, input.receipt);
             const finalize = await prepareFinalizeAssessment(tempRoot, sourceObjects, objectDirectory, localGitRoot, current, input.receipt);
             return {
@@ -1053,7 +1069,7 @@ class DefaultSessionCheckoutApplyEngine {
             const objectDirectory = join(tempRoot, 'objects');
             await mkdir(objectDirectory, { recursive: true });
             const sourceObjects = await sourceObjectDirectory(localGitRoot);
-            const current = await captureSnapshot(localGitRoot, join(tempRoot, 'current.index'), objectDirectory, sourceObjects);
+            const current = await this.captureSnapshot(localGitRoot, join(tempRoot, 'current.index'), objectDirectory, sourceObjects);
             const assessment = await prepareRollbackAssessment(tempRoot, sourceObjects, objectDirectory, localGitRoot, current, input.receipt);
             if (assessment.status === 'blocked') {
                 return { status: 'error', error: { code: assessment.code, message: assessment.message } };
@@ -1063,7 +1079,7 @@ class DefaultSessionCheckoutApplyEngine {
             // final Local CAS. From the snapshot below to git apply there is no callback/yield seam.
             await input.beforeWrite?.();
             await this.options.beforeFinalLocalValidation?.();
-            const finalLocal = await captureSnapshot(localGitRoot, join(tempRoot, 'final-local.index'), objectDirectory, sourceObjects);
+            const finalLocal = await this.captureSnapshot(localGitRoot, join(tempRoot, 'final-local.index'), objectDirectory, sourceObjects);
             if (finalLocal.fingerprint !== current.fingerprint
                 || finalLocal.headOid !== current.headOid
                 || finalLocal.headRef !== current.headRef) {
@@ -1075,7 +1091,7 @@ class DefaultSessionCheckoutApplyEngine {
             let rolledBack;
             try {
                 await this.options.afterLocalWriteBeforeVerification?.();
-                rolledBack = await captureSnapshot(localGitRoot, join(tempRoot, 'rolled-back.index'), null, null);
+                rolledBack = await this.captureSnapshot(localGitRoot, join(tempRoot, 'rolled-back.index'), null, null);
             }
             catch (error) {
                 return {
@@ -1127,7 +1143,7 @@ class DefaultSessionCheckoutApplyEngine {
             const objectDirectory = join(tempRoot, 'objects');
             await mkdir(objectDirectory, { recursive: true });
             const sourceObjects = await sourceObjectDirectory(localGitRoot);
-            const current = await captureSnapshot(localGitRoot, join(tempRoot, 'current.index'), objectDirectory, sourceObjects);
+            const current = await this.captureSnapshot(localGitRoot, join(tempRoot, 'current.index'), objectDirectory, sourceObjects);
             const realIndexPath = await resolveIndexPath(localGitRoot);
             const originalIndexBytes = await readFile(realIndexPath);
             const assessment = await prepareFinalizeAssessment(tempRoot, sourceObjects, objectDirectory, localGitRoot, current, input.receipt);
@@ -1136,7 +1152,7 @@ class DefaultSessionCheckoutApplyEngine {
             }
             if (!assessment.commitRequired) {
                 await this.options.beforeFinalLocalValidation?.();
-                const finalLocal = await captureSnapshot(localGitRoot, join(tempRoot, 'final-empty.index'), objectDirectory, sourceObjects);
+                const finalLocal = await this.captureSnapshot(localGitRoot, join(tempRoot, 'final-empty.index'), objectDirectory, sourceObjects);
                 if (finalLocal.headOid !== current.headOid
                     || finalLocal.headRef !== current.headRef
                     || finalLocal.fingerprint !== current.fingerprint) {
@@ -1183,7 +1199,7 @@ class DefaultSessionCheckoutApplyEngine {
                 }
                 throw error;
             }
-            const finalLocal = await captureSnapshot(localGitRoot, join(tempRoot, 'final-local.index'), objectDirectory, sourceObjects);
+            const finalLocal = await this.captureSnapshot(localGitRoot, join(tempRoot, 'final-local.index'), objectDirectory, sourceObjects);
             const finalIndexBytes = await readFile(realIndexPath);
             if (finalLocal.headOid !== current.headOid
                 || finalLocal.headRef !== current.headRef
@@ -1207,7 +1223,7 @@ class DefaultSessionCheckoutApplyEngine {
             if (!writeError) {
                 try {
                     await this.options.afterLocalWriteBeforeVerification?.();
-                    const committed = await captureSnapshot(localGitRoot, join(tempRoot, 'committed.index'), null, null);
+                    const committed = await this.captureSnapshot(localGitRoot, join(tempRoot, 'committed.index'), null, null);
                     const committedIndexBytes = await readFile(realIndexPath);
                     if (committed.headOid === commitOid
                         && committed.headRef === branchRef
@@ -1272,7 +1288,7 @@ class DefaultSessionCheckoutApplyEngine {
             let restored = false;
             if (rollbackErrors.length === 0) {
                 try {
-                    const restoredLocal = await captureSnapshot(localGitRoot, join(tempRoot, 'restored.index'), null, null);
+                    const restoredLocal = await this.captureSnapshot(localGitRoot, join(tempRoot, 'restored.index'), null, null);
                     const restoredIndexBytes = await readFile(realIndexPath);
                     restored = restoredLocal.headOid === current.headOid
                         && restoredLocal.headRef === current.headRef
@@ -1344,13 +1360,13 @@ class DefaultSessionCheckoutApplyEngine {
             if (!pathsMatch(sourceObjects, stored.scope.sourceObjects)) {
                 return { status: 'error', error: { code: 'invalid_plan', message: hostMessage('theFinishPlanSGitRepositoryIdentityHasChanged') } };
             }
-            const local = await captureSnapshot(stored.scope.localGitRoot, join(tempRoot, 'local.index'), objectDirectory, sourceObjects);
+            const local = await this.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: hostMessage('localChangedAfterPlanningRecalculateThePlan') } };
             }
-            const isolated = await captureSnapshot(stored.scope.isolatedGitRoot, join(tempRoot, 'isolated.index'), objectDirectory, sourceObjects);
+            const isolated = await this.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: hostMessage('isolatedChangedAfterPlanningRecalculateThePlan') } };
             }
@@ -1365,14 +1381,14 @@ class DefaultSessionCheckoutApplyEngine {
                 || merge.changedFiles.some((path, index) => path !== stored.plan.changedFiles[index])) {
                 return { status: 'error', error: { code: 'invalid_plan', message: hostMessage('theFileSetChangedDuringFinishRevalidation') } };
             }
-            const persistentIsolated = await captureSnapshot(stored.scope.isolatedGitRoot, join(tempRoot, 'persistent-isolated.index'), null, null);
+            const persistentIsolated = await this.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: hostMessage('isolatedChangedAfterPlanningRecalculateThePlan') } };
             }
             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);
+                const finalLocal = await this.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: hostMessage('localChangedBeforeFinishRecalculateThePlan') } };
                 }
@@ -1409,7 +1425,7 @@ class DefaultSessionCheckoutApplyEngine {
             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);
+            const finalLocal = await this.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) {