@tickernelz/paperclip-pro-adapter-utils 2026.1006.0 → 2026.1006.2

package/dist/git-workspace-sync.js

@@ -3,6 +3,9 @@ import { execFile } from "node:child_process";
 import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { createWorkspaceManifest, workspacePaths, WorkspaceNulParser } from "./workspace-manifest.js";
+import { runWorkspaceGitProcess } from "./workspace-git-stream.js";
+import { preserveWorkspaceRestoreErrorDiagnostic, withWorkspaceRestoreGitCommand } from "./workspace-restore-diagnostics.js";
 export const PROJECT_REPOSITORIES_DIR = ".paperclip-repositories";
 let expensiveWorkspaceGitExecutor = null;
 /**
@@ -20,7 +23,7 @@ export const WORKSPACE_GIT_SCAN_SATURATED_CODE = "workspace_git_scan_saturated";
 /**
  * Lets a host process apply its process-wide admission policy to the adapter
  * package's full-tree Git walks. Standalone adapter-utils consumers retain the
- * existing timeout/buffer-bounded fallback.
+ * streaming process fallback for filename scans.
  */
 export function setExpensiveWorkspaceGitExecutor(executor) {
     expensiveWorkspaceGitExecutor = executor;
@@ -72,33 +75,36 @@ async function runExpensiveWorkspaceGit(localDir, args, operation, options) {
             timeout: options.timeout,
             maxBuffer: options.maxBuffer,
             env: options.env,
+            onStdout: options.onStdout,
+            signal: options.signal,
         });
     }
+    if (options.onStdout)
+        return runWorkspaceGitProcess({
+            cwd: localDir, args, timeoutMs: options.timeout, maxStdoutBytes: options.maxBuffer,
+            maxStderrBytes: options.maxBuffer, onStdout: options.onStdout, signal: options.signal, env: options.env,
+        });
     return await runLocalGit(localDir, args, options);
 }
-export async function readGitWorkspaceSnapshot(localDir, includeRepositories = true) {
+const ownedSnapshots = new WeakMap();
+export async function disposeGitWorkspaceSnapshot(snapshot) {
+    if (!snapshot)
+        return;
+    const ownedDirectory = ownedSnapshots.get(snapshot);
+    if (!ownedDirectory)
+        return;
+    ownedSnapshots.delete(snapshot);
+    for (const repository of snapshot.repositories ?? [])
+        await disposeGitWorkspaceSnapshot(repository.snapshot);
+    await fs.rm(ownedDirectory, { recursive: true, force: true });
+}
+/** Snapshot deadlines include disk backpressure. Operators can allow up to 24h. */
+export function workspaceSnapshotTimeoutMs() {
+    const configured = Number(process.env.PAPERCLIP_WORKSPACE_GIT_SNAPSHOT_TIMEOUT_MS);
+    return Number.isFinite(configured) && configured >= 1000 ? Math.min(configured, 86_400_000) : 30 * 60_000;
+}
+export async function readGitWorkspaceSnapshot(localDir, includeRepositories = true, options = {}) {
     const repositories = [];
-    if (includeRepositories) {
-        const root = path.join(localDir, PROJECT_REPOSITORIES_DIR);
-        const rootStat = await fs.lstat(root).catch((error) => {
-            if (error.code === "ENOENT")
-                return null;
-            throw error;
-        });
-        if (rootStat) {
-            if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
-                throw new Error("Invalid project repositories directory");
-            for (const entry of (await fs.readdir(root, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
-                if (!entry.isDirectory() || !/^[a-zA-Z0-9_-]+$/.test(entry.name))
-                    throw new Error("Invalid project repository directory");
-                const relative = `${PROJECT_REPOSITORIES_DIR}/${entry.name}`;
-                const snapshot = await readGitWorkspaceSnapshot(path.join(localDir, relative), false);
-                if (!snapshot)
-                    throw new Error(`Project repository is not a Git checkout: ${relative}`);
-                repositories.push({ path: relative, snapshot });
-            }
-        }
-    }
     // Only repository discovery may report an ordinary directory. A failed
     // snapshot of a confirmed repository must never fall back to directory sync.
     let insideWorkTree;
@@ -129,64 +135,106 @@ export async function readGitWorkspaceSnapshot(localDir, includeRepositories = t
     ]);
     if (workspacePath !== repositoryPath)
         return null;
-    const [headCommitResult, branchResult, overlayDiffResult, untrackedResult, deletedResult, ignoredResult] = await Promise.all([
-        runLocalGit(localDir, ["rev-parse", "HEAD"], {
-            timeout: 10_000,
-            maxBuffer: 16 * 1024,
-        }),
-        runLocalGit(localDir, ["rev-parse", "--abbrev-ref", "HEAD"], {
-            timeout: 10_000,
-            maxBuffer: 16 * 1024,
-        }),
-        runExpensiveWorkspaceGit(localDir, ["diff", "--name-only", "-z", "--diff-filter=ACMRTUXB", "HEAD", "--"], "adapter_sync.overlay_diff", {
-            timeout: 10_000,
-            maxBuffer: 1024 * 1024,
-        }),
-        // A generated output tree can exceed 1 MiB of filenames with only a few
-        // thousand files. Keep the explicit file snapshot (and a finite bound):
-        // collapsing directories would let later files enter the staging copy.
-        runExpensiveWorkspaceGit(localDir, ["ls-files", "--others", "--exclude-standard", "-z"], "adapter_sync.untracked_files", {
-            timeout: 10_000,
-            maxBuffer: 32 * 1024 * 1024,
-        }),
-        runExpensiveWorkspaceGit(localDir, ["diff", "--name-only", "-z", "--diff-filter=D", "HEAD", "--"], "adapter_sync.deleted_files", {
-            timeout: 10_000,
-            maxBuffer: 256 * 1024,
-        }),
-        // Collapse ignored directories instead of walking their contents, and
-        // avoid producing unrelated tracked/untracked status records.
-        runExpensiveWorkspaceGit(localDir, ["ls-files", "--others", "--ignored", "--exclude-standard", "--directory", "-z"], "adapter_sync.ignored_files", {
-            timeout: 10_000,
-            maxBuffer: 1024 * 1024,
-        }),
-    ]);
-    const branchName = branchResult.stdout.trim();
-    // `-z` already delimits each record with a NUL byte, so a leading or
-    // trailing space in a record is part of the path itself, not padding to
-    // remove — trimming it would resolve to a path that does not exist. A
-    // length check finds the one genuinely empty record `-z` appends after
-    // the last NUL, without eating a real path's own leading or trailing
-    // whitespace. This applies to all four NUL-delimited outputs below (the
-    // overlay diff, the untracked list, the deleted list, and the ignored
-    // list); `branchName` and `headCommit` come from non-`-z` commands and
-    // keep their own `.trim()` above and below, which is safe.
-    const splitNul = (value) => value.split("\0").filter((entry) => entry.length > 0);
-    return {
-        headCommit: headCommitResult.stdout.trim(),
-        branchName: branchName && branchName !== "HEAD" ? branchName : null,
-        overlayPaths: [...new Set([...splitNul(overlayDiffResult.stdout), ...splitNul(untrackedResult.stdout),
-                ...repositories.flatMap((repo) => repo.snapshot.overlayPaths.map((entry) => `${repo.path}/${entry}`))])]
-            .sort((left, right) => left.localeCompare(right)),
-        deletedPaths: [...new Set([...splitNul(deletedResult.stdout),
-                ...repositories.flatMap((repo) => repo.snapshot.deletedPaths.map((entry) => `${repo.path}/${entry}`))])]
-            .sort((left, right) => left.localeCompare(right)),
-        ignoredPaths: [...splitNul(ignoredResult.stdout)
-                .map((entry) => entry.replace(/\/+$/, ""))
-                .filter((entry) => Boolean(entry) && !(repositories.length > 0 && entry === PROJECT_REPOSITORIES_DIR)),
-            ...repositories.flatMap((repo) => repo.snapshot.ignoredPaths.map((entry) => `${repo.path}/${entry}`))]
-            .sort((left, right) => left.localeCompare(right)),
-        ...(repositories.length > 0 ? { repositories } : {}),
-    };
+    const writer = await createWorkspaceManifest();
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    options.signal?.addEventListener("abort", abort, { once: true });
+    if (options.signal?.aborted)
+        abort();
+    try {
+        if (includeRepositories) {
+            const root = path.join(localDir, PROJECT_REPOSITORIES_DIR);
+            const rootStat = await fs.lstat(root).catch((error) => {
+                if (error.code === "ENOENT")
+                    return null;
+                throw error;
+            });
+            if (rootStat) {
+                if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+                    throw new Error("Invalid project repositories directory");
+                for await (const entry of await fs.opendir(root)) {
+                    if (!entry.isDirectory() || !/^[a-zA-Z0-9_-]+$/.test(entry.name))
+                        throw new Error("Invalid project repository directory");
+                    const relative = `${PROJECT_REPOSITORIES_DIR}/${entry.name}`;
+                    const snapshot = await readGitWorkspaceSnapshot(path.join(localDir, relative), false, options);
+                    if (!snapshot)
+                        throw new Error(`Project repository is not a Git checkout: ${relative}`);
+                    repositories.push({ path: relative, snapshot });
+                }
+            }
+        }
+        const scan = async (args, operation, category) => {
+            const parser = new WorkspaceNulParser((record) => {
+                const relative = category === "ignored" ? record.replace(/\/+$/, "") : record;
+                if (category === "ignored" && repositories.length && relative === PROJECT_REPOSITORIES_DIR)
+                    return;
+                // Managed children have their own exact file selections. Never stage a
+                // parent Git directory record that could admit files created later.
+                if (repositories.some((repo) => relative === repo.path || relative.startsWith(`${repo.path}/`)))
+                    return;
+                writer.add(category, relative);
+            });
+            const result = await runExpensiveWorkspaceGit(localDir, args, operation, {
+                timeout: workspaceSnapshotTimeoutMs(), maxBuffer: 64 * 1024,
+                signal: controller.signal,
+                onStdout: (chunk) => writer.batch(() => parser.write(chunk)),
+            });
+            if (result.stdout)
+                throw new Error("Workspace Git executor did not stream stdout");
+            try {
+                parser.finish();
+            }
+            catch (error) {
+                throw Object.assign(error, { code: "workspace_git_scan_failed" });
+            }
+        };
+        // Cancellation is followed by an all-settled barrier BEFORE storage cleanup.
+        const tasks = [
+            runLocalGit(localDir, ["rev-parse", "HEAD"], { timeout: 10_000, maxBuffer: 16 * 1024 }),
+            runLocalGit(localDir, ["rev-parse", "--abbrev-ref", "HEAD"], { timeout: 10_000, maxBuffer: 16 * 1024 }),
+            scan(["diff", "--name-only", "-z", "--diff-filter=ACMRTUXB", "HEAD", "--"], "adapter_sync.overlay_diff", "overlay"),
+            scan(["ls-files", "--others", "--exclude-standard", "-z"], "adapter_sync.untracked_files", "overlay"),
+            scan(["diff", "--name-only", "-z", "--diff-filter=D", "HEAD", "--"], "adapter_sync.deleted_files", "deleted"),
+            scan(["ls-files", "--others", "--ignored", "--exclude-standard", "--directory", "-z"], "adapter_sync.ignored_files", "ignored"),
+        ];
+        let firstError;
+        const settled = await Promise.allSettled(tasks.map((task) => task.catch((error) => {
+            if (firstError === undefined)
+                firstError = error;
+            controller.abort();
+            throw error;
+        })));
+        if (firstError !== undefined)
+            throw firstError;
+        if (controller.signal.aborted)
+            throw Object.assign(new Error("Workspace snapshot cancelled"), { code: "workspace_git_scan_cancelled" });
+        for (const repo of repositories) {
+            for (const [category, paths] of [["overlay", repo.snapshot.overlayPaths], ["deleted", repo.snapshot.deletedPaths], ["ignored", repo.snapshot.ignoredPaths]]) {
+                for (const relative of workspacePaths(paths))
+                    writer.add(category, `${repo.path}/${relative}`);
+            }
+        }
+        const head = settled[0].value.stdout.trim();
+        const branch = settled[1].value.stdout.trim();
+        const snapshot = {
+            headCommit: head, branchName: branch && branch !== "HEAD" ? branch : null,
+            overlayPaths: writer.paths("overlay"), deletedPaths: writer.paths("deleted"), ignoredPaths: writer.paths("ignored"),
+            ...(repositories.length ? { repositories } : {}),
+        };
+        writer.close();
+        ownedSnapshots.set(snapshot, path.dirname(writer.filePath));
+        return snapshot;
+    }
+    catch (error) {
+        writer.close(false);
+        for (const repo of repositories)
+            await disposeGitWorkspaceSnapshot(repo.snapshot);
+        await fs.rm(path.dirname(writer.filePath), { recursive: true, force: true });
+        throw error;
+    }
+    finally {
+        options.signal?.removeEventListener("abort", abort);
+    }
 }
 /**
  * Build the environment for a hardened, read-only Git invocation against a
@@ -433,6 +481,21 @@ export async function readSanitizedOriginRemoteUrl(localDir) {
         return null;
     }
 }
+async function copyCloneTree(source, target) {
+    await fs.mkdir(target, { recursive: true });
+    for await (const entry of await fs.opendir(source)) {
+        const from = path.join(source, entry.name);
+        const to = path.join(target, entry.name);
+        if (entry.isDirectory())
+            await copyCloneTree(from, to);
+        else if (entry.isSymbolicLink())
+            await fs.symlink(await fs.readlink(from), to);
+        else {
+            await fs.copyFile(from, to);
+            await fs.chmod(to, (await fs.stat(from)).mode);
+        }
+    }
+}
 export async function withShallowGitWorkspaceClone(input, fn) {
     const cloneDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-git-workspace-"));
     const tempRef = `refs/paperclip/git-sync/import/${randomUUID()}`;
@@ -481,10 +544,7 @@ export async function withShallowGitWorkspaceClone(input, fn) {
                 // Preserve repository-relative links. fs.cp otherwise rewrites them to
                 // absolute paths into nestedClone, which is deleted after this callback
                 // and is outside the workspace when the sandbox restores its files.
-                await fs.cp(nestedClone, path.join(cloneDir, repository.path), {
-                    recursive: true,
-                    verbatimSymlinks: true,
-                });
+                await copyCloneTree(nestedClone, path.join(cloneDir, repository.path));
             });
         }
         if (input.snapshot.repositories?.length) {
@@ -586,6 +646,12 @@ export function buildRemoteGitDeltaBundleScript(input) {
                 `  bundle_base=""`,
                 "fi",
             ]),
+        // An empty bundle means "still at baseSha" to the importer. A reset to an
+        // older ancestor has no delta commits either, but must carry its new tip.
+        // Use the full-bundle path so Git advertises that tip instead of losing it.
+        `if [ -n "$bundle_base" ] && [ "$bundle_base" != ${baseSha} ] && [ "$bundle_base" = "$(git -C ${remoteDir} rev-parse HEAD)" ]; then`,
+        `  bundle_base=""`,
+        "fi",
         `if [ -n "$bundle_base" ]; then`,
         `  commit_count=$(git -C ${remoteDir} rev-list --count HEAD --not "$bundle_base")`,
         "else",
@@ -603,16 +669,22 @@ export function buildRemoteGitDeltaBundleScript(input) {
         "fi",
         statusPath
             ? [
-                `if [ -z "$(git -C ${remoteDir} status --porcelain=v1 --untracked-files=normal)" ]; then`,
+                `git -C ${remoteDir} status --porcelain=v1 --untracked-files=normal -z > ${shellQuote(`${input.statusPath}.git-status`)}`,
+                `if [ ! -s ${shellQuote(`${input.statusPath}.git-status`)} ]; then`,
                 `  printf clean > ${statusPath}`,
                 "else",
                 `  printf dirty > ${statusPath}`,
                 "fi",
+                `rm -f -- ${shellQuote(`${input.statusPath}.git-status`)}`,
             ].join("\n")
             : "",
         input.catBundle ? `cat ${bundlePath}` : "",
     ].filter(Boolean).join("\n");
 }
+// Labels are fixed at the integration call sites, never derived from Git arguments.
+function runIntegrationGit(command, ...args) {
+    return withWorkspaceRestoreGitCommand(command, () => runLocalGit(...args));
+}
 /**
  * Preserve imported work whose history does not connect to the local one.
  *
@@ -629,11 +701,11 @@ export function buildRemoteGitDeltaBundleScript(input) {
  * branch ref to the returned commit.
  */
 export async function createUnrelatedHistoryGraftCommit(input) {
-    const importedTree = (await runLocalGit(input.localDir, ["rev-parse", `${input.importedHead}^{tree}`], {
+    const importedTree = (await runIntegrationGit("rev_parse", input.localDir, ["rev-parse", `${input.importedHead}^{tree}`], {
         timeout: 10_000,
         maxBuffer: 16 * 1024,
     })).stdout.trim();
-    const importedMessage = (await runLocalGit(input.localDir, ["log", "-1", "--format=%B", input.importedHead], {
+    const importedMessage = (await runIntegrationGit("log", input.localDir, ["log", "-1", "--format=%B", input.importedHead], {
         timeout: 10_000,
         maxBuffer: 256 * 1024,
     })).stdout;
@@ -642,31 +714,96 @@ export async function createUnrelatedHistoryGraftCommit(input) {
         "",
         `(${input.syncLabel} graft ${input.importedHead.slice(0, 12)}: imported history shares no ancestor with ${input.currentHead.slice(0, 12)})`,
     ].join("\n");
-    const graftCommit = await runLocalGit(input.localDir, [...GIT_SYNC_COMMIT_IDENTITY_ARGS, "commit-tree", importedTree, "-p", input.currentHead, "-m", message], {
+    const graftCommit = await runIntegrationGit("commit_tree", input.localDir, [...GIT_SYNC_COMMIT_IDENTITY_ARGS, "commit-tree", importedTree, "-p", input.currentHead, "-m", message], {
         timeout: 60_000,
         maxBuffer: 64 * 1024,
     });
     return graftCommit.stdout.trim();
 }
+async function updateLocalGitHead(input) {
+    // Prepare the ref transaction before checking the symbolic HEAD identity.
+    // Git holds HEAD.lock (and the branch lock when attached) until commit/abort,
+    // so a checkout cannot redirect the write after this check. --no-deref also
+    // prevents a detached write from following a newly attached branch.
+    await withWorkspaceRestoreGitCommand("update_ref", () => new Promise((resolve, reject) => {
+        let identityError;
+        let prepared = false;
+        let output = "";
+        const child = execFile("git", ["-C", input.localDir, "update-ref", "--stdin"], {
+            timeout: 15_000,
+            maxBuffer: 64 * 1024,
+        }, (error, stdout, stderr) => {
+            if (identityError)
+                reject(identityError);
+            else if (error)
+                reject(Object.assign(error, { stdout, stderr }));
+            else if (!stdout.includes("commit: ok\n"))
+                reject(new Error("Git HEAD transaction did not commit."));
+            else
+                resolve();
+        });
+        // Early Git errors close stdin; the process callback reports the error.
+        child.stdin.on("error", () => { });
+        child.stdout.on("data", (chunk) => {
+            output += chunk.toString();
+            if (prepared || !output.includes("prepare: ok\n"))
+                return;
+            prepared = true;
+            void (async () => {
+                try {
+                    const branchName = (await runIntegrationGit("symbolic_ref", input.localDir, ["symbolic-ref", "--quiet", "--short", "HEAD"], {
+                        timeout: 10_000,
+                    }).catch((error) => {
+                        if (error.code === 1)
+                            return { stdout: "" };
+                        throw error;
+                    })).stdout.trim() || null;
+                    if (branchName !== input.branchName) {
+                        throw new Error("Workspace branch changed while remote work was running.");
+                    }
+                    child.stdin.end("commit\n");
+                }
+                catch (error) {
+                    identityError = error;
+                    child.stdin.end("abort\n");
+                }
+            })();
+        });
+        child.stdin.write([
+            "start",
+            ...(input.branchName === null ? ["option no-deref"] : []),
+            `update HEAD ${input.newHead} ${input.oldHead}`,
+            "prepare",
+            "",
+        ].join("\n"));
+    }));
+}
 export async function integrateImportedGitHead(input) {
     const isConcurrentRefUpdateError = (error) => {
         const message = error instanceof Error ? error.message : String(error);
         return message.includes("cannot lock ref") && message.includes("expected");
     };
     for (let attempt = 0; attempt < 5; attempt += 1) {
-        const snapshot = await readGitWorkspaceSnapshot(input.localDir);
-        if (!snapshot)
-            return;
+        const snapshot = {
+            headCommit: (await runIntegrationGit("rev_parse", input.localDir, ["rev-parse", "HEAD"])).stdout.trim(),
+            branchName: (await runIntegrationGit("symbolic_ref", input.localDir, ["symbolic-ref", "--quiet", "--short", "HEAD"]).catch((error) => {
+                if (error.code === 1)
+                    return { stdout: "" };
+                throw error;
+            })).stdout.trim() || null,
+        };
+        if (input.baseline && snapshot.branchName !== input.baseline.branchName) {
+            throw new Error("Workspace branch changed while remote work was running.");
+        }
         const currentHead = snapshot.headCommit;
         if (!currentHead || currentHead === input.importedHead)
             return;
-        const headRef = snapshot.branchName ? `refs/heads/${snapshot.branchName}` : "HEAD";
         // `git merge-base` exits 1 when the commits share no ancestor — the only
         // outcome that authorizes the graft fallback below. Every other failure
         // (timeout, missing object, repository error) must keep failing the
         // integration instead of silently rewriting the tip.
         let noCommonAncestor = false;
-        const mergeBase = await runLocalGit(input.localDir, ["merge-base", currentHead, input.importedHead], {
+        const mergeBase = await runIntegrationGit("merge_base", input.localDir, ["merge-base", currentHead, input.importedHead], {
             timeout: 10_000,
             maxBuffer: 16 * 1024,
         }).catch((error) => {
@@ -674,14 +811,15 @@ export async function integrateImportedGitHead(input) {
             return null;
         });
         const mergeBaseHead = mergeBase?.stdout.trim() ?? "";
-        if (mergeBaseHead === input.importedHead) {
-            return;
-        }
-        if (mergeBaseHead === currentHead) {
+        // A rebase/amend rewrites the sandbox tip without a concurrent host edit.
+        // Adopt that history when the host still matches the run's starting tip;
+        // merging the old and rewritten commits can reintroduce resolved conflicts.
+        // Keep the expected-old-value check: if the host advances during this write,
+        // retry against its new tip and use the normal concurrent-history path.
+        if (mergeBaseHead === currentHead || (mergeBaseHead && currentHead === input.baseline?.headCommit)) {
             try {
-                await runLocalGit(input.localDir, ["update-ref", headRef, input.importedHead, currentHead], {
-                    timeout: 10_000,
-                    maxBuffer: 16 * 1024,
+                await updateLocalGitHead({
+                    localDir: input.localDir, newHead: input.importedHead, oldHead: currentHead, branchName: snapshot.branchName,
                 });
                 return;
             }
@@ -691,7 +829,13 @@ export async function integrateImportedGitHead(input) {
                 throw error;
             }
         }
+        if (mergeBaseHead === input.importedHead) {
+            return;
+        }
         if (noCommonAncestor) {
+            if (input.baseline && currentHead !== input.baseline.headCommit) {
+                throw new Error("Cannot restore unrelated remote history after the host advanced.");
+            }
             // No common ancestor — merging is impossible and failing here would
             // discard the imported work. Graft it onto the current head instead;
             // see createUnrelatedHistoryGraftCommit.
@@ -702,9 +846,8 @@ export async function integrateImportedGitHead(input) {
                 syncLabel: "Paperclip remote git sync",
             });
             try {
-                await runLocalGit(input.localDir, ["update-ref", headRef, graftCommit, currentHead], {
-                    timeout: 10_000,
-                    maxBuffer: 16 * 1024,
+                await updateLocalGitHead({
+                    localDir: input.localDir, newHead: graftCommit, oldHead: currentHead, branchName: snapshot.branchName,
                 });
                 return;
             }
@@ -716,20 +859,20 @@ export async function integrateImportedGitHead(input) {
         }
         let mergedTree;
         try {
-            mergedTree = await runLocalGit(input.localDir, ["merge-tree", "--write-tree", currentHead, input.importedHead], {
+            mergedTree = await runIntegrationGit("merge_tree", input.localDir, ["merge-tree", "--write-tree", currentHead, input.importedHead], {
                 timeout: 60_000,
                 maxBuffer: 256 * 1024,
             });
         }
         catch (error) {
             const reason = error instanceof Error ? error.message : String(error);
-            throw new Error(`Failed to merge concurrent remote git histories for ${currentHead.slice(0, 12)} and ${input.importedHead.slice(0, 12)}: ${reason}`);
+            throw preserveWorkspaceRestoreErrorDiagnostic(new Error(`Failed to merge concurrent remote git histories for ${currentHead.slice(0, 12)} and ${input.importedHead.slice(0, 12)}: ${reason}`), error);
         }
         const mergedTreeId = mergedTree.stdout.trim().split("\n")[0]?.trim() ?? "";
         if (!mergedTreeId) {
             throw new Error("Failed to compute a merged git tree for workspace restore.");
         }
-        const mergeCommit = await runLocalGit(input.localDir, [
+        const mergeCommit = await runIntegrationGit("commit_tree", input.localDir, [
             ...GIT_SYNC_COMMIT_IDENTITY_ARGS,
             "commit-tree",
             mergedTreeId,
@@ -744,9 +887,8 @@ export async function integrateImportedGitHead(input) {
             maxBuffer: 64 * 1024,
         });
         try {
-            await runLocalGit(input.localDir, ["update-ref", headRef, mergeCommit.stdout.trim(), currentHead], {
-                timeout: 10_000,
-                maxBuffer: 16 * 1024,
+            await updateLocalGitHead({
+                localDir: input.localDir, newHead: mergeCommit.stdout.trim(), oldHead: currentHead, branchName: snapshot.branchName,
             });
             return;
         }
@@ -773,22 +915,23 @@ export async function resetLocalGitIndexToHead(input) {
                 error.stdout,
             ].filter((value) => typeof value === "string" && value.trim().length > 0).join("\n")
             : String(error);
-        throw new Error(`Failed to reset local git index to HEAD after workspace restore: ${detail}`);
+        throw preserveWorkspaceRestoreErrorDiagnostic(new Error(`Failed to reset local git index to HEAD after workspace restore: ${detail}`), error);
     }
-    const stagedDiff = await runLocalGit(input.localDir, ["diff", "--cached", "--name-status", "HEAD", "--"], {
-        timeout: 10_000,
-        maxBuffer: 1024 * 1024,
-    });
-    if (stagedDiff.stdout.trim().length > 0) {
-        throw new Error(`Workspace restore left staged git index changes after reset:\n${stagedDiff.stdout.trim()}`);
+    const hasDiff = async (args) => {
+        try {
+            await runLocalGit(input.localDir, args, { timeout: workspaceSnapshotTimeoutMs(), maxBuffer: 64 * 1024 });
+            return false;
+        }
+        catch (error) {
+            if (error.code === 1)
+                return true;
+            throw error;
+        }
+    };
+    if (await hasDiff(["diff", "--quiet", "--cached", "HEAD", "--"])) {
+        throw new Error("Workspace restore left staged git index changes after reset");
     }
-    if (!input.checkWorkingTreeClean)
-        return;
-    const workingTreeDiff = await runLocalGit(input.localDir, ["diff", "--name-status", "HEAD", "--"], {
-        timeout: 10_000,
-        maxBuffer: 1024 * 1024,
-    });
-    if (workingTreeDiff.stdout.trim().length > 0) {
+    if (input.checkWorkingTreeClean && await hasDiff(["diff", "--quiet", "HEAD", "--"])) {
         console.warn("[paperclip] Workspace restore preserved local working tree changes after clean sandbox restore.");
     }
 }