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

package/dist/sandbox-managed-runtime.js

@@ -2,13 +2,15 @@ import { execFile as execFileCallback } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { constants as fsConstants, createReadStream, promises as fs, } from "node:fs";
 import os from "node:os";
+import { workspacePaths, workspacePathMatcher, writeWorkspacePaths, isPathManifest } from "./workspace-manifest.js";
 import path from "node:path";
 import { promisify } from "node:util";
-import { buildRemoteGitDeltaBundleScript, isMissingGitPrerequisiteError, createImportedGitRef, createRemoteGitExportRef, deleteLocalGitRef, fetchGitBundleIntoLocalRef, GIT_ARCHIVE_EXCLUDES, integrateImportedGitHead, readGitWorkspaceSnapshot, ReferencedSourceIgnoreScanLimitExceededError, readReferencedSourceGitIgnoredPaths, resetLocalGitIndexToHead, withShallowGitWorkspaceClone, WORKSPACE_GIT_SCAN_SATURATED_CODE, } from "./git-workspace-sync.js";
-import { captureDirectorySnapshot, mergeDirectoryWithBaseline, } from "./workspace-restore-merge.js";
+import { buildRemoteGitDeltaBundleScript, isMissingGitPrerequisiteError, createImportedGitRef, createRemoteGitExportRef, deleteLocalGitRef, fetchGitBundleIntoLocalRef, GIT_ARCHIVE_EXCLUDES, integrateImportedGitHead, readGitWorkspaceSnapshot, disposeGitWorkspaceSnapshot, ReferencedSourceIgnoreScanLimitExceededError, readReferencedSourceGitIgnoredPaths, resetLocalGitIndexToHead, withShallowGitWorkspaceClone, WORKSPACE_GIT_SCAN_SATURATED_CODE, } from "./git-workspace-sync.js";
+import { captureDirectorySnapshot, disposeDirectorySnapshot, selectDirectorySnapshot, mergeDirectoryWithBaseline, } from "./workspace-restore-merge.js";
 import { createRuntimeProgressReporter, } from "./runtime-progress.js";
 import { isRelativePathOrDescendant, shouldExcludePath } from "./exclude-patterns.js";
 import { scheduleSyncOperations, SYNC_OPERATION_CONCURRENCY_LIMIT, } from "./sync-operation-schedule.js";
+import { recordWorkspaceRestoreDiagnostic, withWorkspaceRestoreDiagnostics, withWorkspaceRestoreStep, } from "./workspace-restore-diagnostics.js";
 const execFile = promisify(execFileCallback);
 const SANDBOX_WORKSPACE_HEAVY_DIR_NAMES = [
     "node_modules",
@@ -289,11 +291,20 @@ function buildWorkspaceTarExtractCommand(input) {
 // sandbox workspace. Every path is shell-quoted; the caller supplies only
 // already-confined relative paths from the git snapshot.
 function buildRemoveDeletedPathsCommand(input) {
-    const quotedPaths = input.deletedPaths.map((entry) => shellQuote(entry)).join(" ");
-    return `cd ${shellQuote(input.remoteDir)} && rm -rf -- ${quotedPaths}`;
+    // NUL input plus bounded xargs batches preserve whitespace and never create
+    // one argument list for the full snapshot. Refuse symlink ancestors.
+    const remove = `for entry do
+    parent=$entry
+    while [ "\${parent#*/}" != "$parent" ]; do
+      parent=\${parent%/*}
+      if [ -L "$parent" ] || { [ -e "$parent" ] && [ ! -d "$parent" ]; }; then exit 42; fi
+    done
+    rm -rf -- "$entry" || exit
+  done`;
+    return `cd ${shellQuote(input.remoteDir)} && xargs -0 -r -n 64 sh -c ${shellQuote(remove)} sh < ${shellQuote(input.manifestPath)} && rm -f -- ${shellQuote(input.manifestPath)}`;
 }
 function buildUniqueStagingPath(input) {
-    return `${input.targetPath}${input.suffix}.${randomUUID()}`;
+    return path.join(path.dirname(input.targetPath), `${input.suffix}.${randomUUID()}`);
 }
 // The workspace stages under `<runtimeRootDir>/workspace-upload.tar` and, for a
 // git-backed workspace, under `<runtimeRootDir>/git-workspace-upload.tar`. Each
@@ -425,49 +436,34 @@ export async function createTarballFromDirectory(input) {
     // entries avoids the self-entry entirely and is portable across GNU/BSD/busybox
     // tar (no GNU-only --no-overwrite-dir needed). --exclude still filters nested
     // matches and any named entry it matches.
-    const entries = (await fs.readdir(input.localDir)).sort((left, right) => left.localeCompare(right));
-    if (entries.length === 0) {
-        // A workspace can legitimately be empty (blank-workspace agent runs). Write a
-        // valid empty tar archive (1024-byte all-zero EOF marker) so extraction is a
-        // clean no-op rather than tar refusing to create an empty archive.
-        await fs.writeFile(input.archivePath, Buffer.alloc(1024));
-        return;
-    }
-    await execTar([
-        "-c",
-        // Prevent macOS bsdtar from embedding LIBARCHIVE.xattr.* PAX extended
-        // headers for extended attributes (e.g. com.apple.provenance). GNU tar on
-        // Linux does not recognise these proprietary headers and fails extraction
-        // with "This does not look like a tar archive". COPYFILE_DISABLE=1 (set in
-        // execTar) already suppresses AppleDouble ._* sidecar files; --no-xattrs
-        // additionally suppresses the inline PAX xattr entries.
-        "--no-xattrs",
-        ...(input.followSymlinks ? ["-h"] : []),
-        "-f",
-        input.archivePath,
-        "-C",
-        input.localDir,
-        ...excludeArgs,
-        "--",
-        ...entries,
-    ]);
+    await withTempDir("paperclip-tar-list-", async (directory) => {
+        const list = path.join(directory, "entries.nul");
+        const file = await fs.open(list, "wx", 0o600);
+        try {
+            for await (const entry of await fs.opendir(input.localDir))
+                await file.writeFile(`${entry.name}\0`);
+        }
+        finally {
+            await file.close();
+        }
+        await execTar(["-c", "--no-xattrs", ...(input.followSymlinks ? ["-h"] : []),
+            "-f", input.archivePath, "-C", input.localDir, ...excludeArgs, "--null", "-T", list]);
+    });
 }
 async function extractTarballToDirectory(input) {
     await fs.mkdir(input.localDir, { recursive: true });
     await execTar(["-xf", input.archivePath, "-C", input.localDir]);
 }
-async function walkDirectory(root, relative = "") {
-    const current = path.join(root, relative);
-    const entries = await fs.readdir(current, { withFileTypes: true }).catch(() => []);
-    const out = [];
-    for (const entry of entries) {
+async function* walkDirectory(root, relative = "", childrenFirst = false) {
+    for await (const entry of await fs.opendir(path.join(root, relative))) {
         const nextRelative = relative ? path.posix.join(relative, entry.name) : entry.name;
-        out.push(nextRelative);
-        if (entry.isDirectory()) {
-            out.push(...(await walkDirectory(root, nextRelative)));
-        }
+        if (!childrenFirst)
+            yield nextRelative;
+        if (entry.isDirectory())
+            yield* walkDirectory(root, nextRelative, childrenFirst);
+        if (childrenFirst)
+            yield nextRelative;
     }
-    return out.sort((left, right) => right.length - left.length);
 }
 async function copyWorkspaceEntry(sourceRoot, targetRoot, relative) {
     const sourcePath = path.join(sourceRoot, relative);
@@ -501,17 +497,19 @@ export async function mirrorDirectory(sourceDir, targetDir, options = {}) {
     await fs.mkdir(targetDir, { recursive: true });
     const preserveAbsent = new Set(options.preserveAbsent ?? []);
     const shouldPreserveAbsent = (relative) => [...preserveAbsent].some((candidate) => isRelativePathOrDescendant(relative, candidate));
-    const sourceEntries = new Set(await walkDirectory(sourceDir));
-    const targetEntries = await walkDirectory(targetDir);
-    for (const relative of targetEntries) {
+    for await (const relative of walkDirectory(targetDir, "", true)) {
         if (shouldPreserveAbsent(relative))
             continue;
-        if (!sourceEntries.has(relative)) {
+        const sourceExists = await fs.lstat(path.join(sourceDir, relative)).then(() => true).catch((error) => {
+            if (error.code === "ENOENT" || error.code === "ENOTDIR")
+                return false;
+            throw error;
+        });
+        if (!sourceExists) {
             await fs.rm(path.join(targetDir, relative), { recursive: true, force: true }).catch(() => undefined);
         }
     }
-    const entries = (await walkDirectory(sourceDir)).sort((left, right) => left.localeCompare(right));
-    for (const relative of entries) {
+    for await (const relative of walkDirectory(sourceDir)) {
         await copyWorkspaceEntry(sourceDir, targetDir, relative);
     }
 }
@@ -532,42 +530,48 @@ async function copySelectedWorkspaceEntries(input) {
         }
     };
     await assertSourceRoot();
-    for (const relative of input.relativePaths) {
-        if (shouldExcludePath(relative, input.exclude))
-            continue;
-        const sourcePath = path.join(sourceDir, relative);
-        const parentSegments = path.relative(sourceDir, path.dirname(sourcePath)).split(path.sep).filter(Boolean);
-        const assertParentDirectory = async () => {
-            // Git selected this path before staging. A replaced ancestor must not
-            // redirect the copy through a symlink, even to another workspace folder.
-            // Inspect types instead of comparing realpath spelling: case-insensitive
-            // filesystems can resolve Git's indexed casing to a renamed directory.
-            let parentPath = sourceDir;
-            for (const segment of parentSegments) {
-                if (segment === "..")
-                    throw new Error(`Workspace overlay directory escapes its root: ${relative}`);
-                parentPath = path.join(parentPath, segment);
-                if (!(await fs.lstat(parentPath)).isDirectory()) {
-                    throw new Error(`Workspace overlay ancestor is not a directory: ${relative}`);
+    const ignored = workspacePathMatcher(input.ignoredPaths);
+    try {
+        for (const relative of workspacePaths(input.relativePaths)) {
+            if (shouldExcludePath(relative, input.exclude) || ignored.matches(relative))
+                continue;
+            const sourcePath = path.join(sourceDir, relative);
+            const parentSegments = path.relative(sourceDir, path.dirname(sourcePath)).split(path.sep).filter(Boolean);
+            const assertParentDirectory = async () => {
+                // Git selected this path before staging. A replaced ancestor must not
+                // redirect the copy through a symlink, even to another workspace folder.
+                // Inspect types instead of comparing realpath spelling: case-insensitive
+                // filesystems can resolve Git's indexed casing to a renamed directory.
+                let parentPath = sourceDir;
+                for (const segment of parentSegments) {
+                    if (segment === "..")
+                        throw new Error(`Workspace overlay directory escapes its root: ${relative}`);
+                    parentPath = path.join(parentPath, segment);
+                    if (!(await fs.lstat(parentPath)).isDirectory()) {
+                        throw new Error(`Workspace overlay ancestor is not a directory: ${relative}`);
+                    }
                 }
+            };
+            // Include root-level entries, and do not treat a missing root as an
+            // ordinary source file that disappeared after the snapshot.
+            await assertSourceRoot();
+            try {
+                await assertParentDirectory();
+                await fs.lstat(sourcePath);
             }
-        };
-        // Include root-level entries, and do not treat a missing root as an
-        // ordinary source file that disappeared after the snapshot.
-        await assertSourceRoot();
-        try {
+            catch (error) {
+                if (error.code === "ENOENT")
+                    continue;
+                throw error;
+            }
+            await copyWorkspaceEntry(sourceDir, input.targetDir, relative);
+            // Do not upload the staged tree if an ancestor changed during the copy.
+            await assertSourceRoot();
             await assertParentDirectory();
-            await fs.lstat(sourcePath);
-        }
-        catch (error) {
-            if (error.code === "ENOENT")
-                continue;
-            throw error;
         }
-        await copyWorkspaceEntry(sourceDir, input.targetDir, relative);
-        // Do not upload the staged tree if an ancestor changed during the copy.
-        await assertSourceRoot();
-        await assertParentDirectory();
+    }
+    finally {
+        ignored.close();
     }
 }
 function toBuffer(bytes) {
@@ -590,17 +594,13 @@ function tarExcludeFlags(exclude) {
     return ["._*", ...(exclude ?? [])].map((entry) => `--exclude ${shellQuote(entry)}`).join(" ");
 }
 function createRemoteTarballFromDirectoryCommand(input) {
-    // Match the local archive path: name top-level entries explicitly so tar
-    // does not include a "." self-entry that it later tries to chmod/utime.
+    const list = `${input.archivePath}.entries`;
     return [
         `mkdir -p ${shellQuote(path.posix.dirname(input.archivePath))}`,
         `cd ${shellQuote(input.remoteDir)}`,
-        "set -- *",
-        `if [ "$#" -eq 1 ] && [ "$1" = "*" ] && [ ! -e "$1" ] && [ ! -L "$1" ]; then set --; fi`,
-        `for entry in .[!.]* ..?*; do [ -e "$entry" ] || [ -L "$entry" ] || continue; set -- "$@" "$entry"; done`,
-        `if [ "$#" -eq 0 ]; then ` +
-            `dd if=/dev/zero of=${shellQuote(input.archivePath)} bs=1024 count=1; ` +
-            `else tar -cf ${shellQuote(input.archivePath)} ${tarExcludeFlags(input.exclude)} -- "$@"; fi`,
+        `find . -mindepth 1 -maxdepth 1 -print0 > ${shellQuote(list)}`,
+        `tar -cf ${shellQuote(input.archivePath)} ${tarExcludeFlags(input.exclude)} --null -T ${shellQuote(list)}`,
+        `rm -f -- ${shellQuote(list)}`,
     ].join(" && ");
 }
 async function emitRuntimeStatus(sink, phase, message) {
@@ -696,193 +696,254 @@ export async function prepareSandboxManagedRuntime(input) {
     // The git enumeration (`git status --ignored`, the HEAD diffs, `ls-files`).
     // It reads git's own bookkeeping to decide what to include/exclude, so it is
     // usually fast, but on a large working tree the `--ignored` walk is not free.
-    const gitSnapshot = syncWorkspace
+    const gitSnapshot = syncWorkspace && input.workspaceFileMode !== "all"
         ? input.workspaceGitSnapshot !== undefined
             ? input.workspaceGitSnapshot
             : await runStepSpan("snapshot.git", () => readGitWorkspaceSnapshot(input.workspaceLocalDir))
         : null;
-    // A selected subfolder has no cloneable Git snapshot, but its parent
-    // repository's ignore rules still govern which files may leave the host.
-    // Use the same bounded, path-relative resolver as referenced project trees.
-    const directoryIgnore = syncWorkspace && !gitSnapshot
-        ? await resolveReferencedSourceIgnore(input.workspaceLocalDir)
-        : null;
-    if (directoryIgnore?.kind === "failed") {
-        throw new Error(`Workspace ignore scan failed: ${directoryIgnore.reason}`);
-    }
-    const gitIgnoredExcludes = gitSnapshot?.ignoredPaths
-        ?? (directoryIgnore?.kind === "git" ? directoryIgnore.ignoredPaths : undefined);
-    const workspaceArchiveExclude = mergeExcludes(SANDBOX_WORKSPACE_HEAVY_DIR_EXCLUDES, [...GIT_ARCHIVE_EXCLUDES], input.workspaceExclude, gitIgnoredExcludes);
-    const restoreExclude = mergeExcludes(SANDBOX_WORKSPACE_HEAVY_DIR_EXCLUDES, [...GIT_ARCHIVE_EXCLUDES], [".paperclip-runtime"], input.preserveAbsentOnRestore, input.workspaceExclude, gitIgnoredExcludes);
-    const repositories = gitSnapshot?.repositories ?? [];
-    const workspaceRestoreExclude = mergeExcludes(restoreExclude, repositories.map((repo) => repo.path));
-    // The baseline "before" snapshot: a recursive walk of the whole workspace that
-    // `lstat`s every entry and SHA-256-hashes every file's bytes. This is the
-    // dominant cost in the pre-`pack` window — it reads the content of every
-    // non-excluded file, serially — so it earns its own span.
-    const baselineSnapshot = syncWorkspace
-        ? (input.workspaceBaseline ??
-            (await runStepSpan("snapshot.baseline", () => captureDirectorySnapshot(input.workspaceLocalDir, {
-                exclude: restoreExclude,
-            }))))
-        : null;
-    // Every inbound staging step delegates to the provider through `client.syncIn`:
-    // the orchestrator no longer inlines `writeFile`+`run` or chooses a transport,
-    // and there is no `usesCustomProvision` native-diversion gate. `syncIn` is
-    // ALWAYS present in production — the command-managed client exposes a native
-    // transport (Daytona/Kubernetes `uploadFiles` + provider-executed post-upload
-    // commands) or a byte-identical base64-tar fallback that reproduces the prior
-    // `writeFile`+`run` sequence. Require it explicitly so a misconfigured client
-    // fails loud rather than silently skipping staging. `syncOut` stays optional
-    // (native-only) with a tar fallback on the restore path below.
-    const syncIn = input.client.syncIn;
-    if (typeof syncIn !== "function") {
-        throw new Error("prepareSandboxManagedRuntime requires a client that exposes syncIn " +
-            "(createCommandManagedRuntimeClient provides a native-or-fallback implementation).");
-    }
-    const nativeSyncOut = typeof input.client.syncOut === "function";
-    let syncOperationSeq = 0;
-    // Opaque, ordered, non-sensitive operation tokens — never a caller/asset id.
-    const nextSyncOperationId = () => `sync-op-${++syncOperationSeq}`;
-    // Remote directory of each additional (referenced) project that stages
-    // successfully, keyed by projectId. A project that fails to stage is absent.
-    const additionalSourceDirs = {};
-    // Each additional (referenced) project whose staging failed, paired with the
-    // failure message. Per-project failure isolation keeps the run and the other
-    // projects going; this list makes each failure a first-class, reported outcome.
-    const additionalSourceFailures = [];
-    // Additional projects stage as plain trees. Drop the heavy build/cache dirs a
-    // reference tree does not need, and `.git` — additional sources never carry
-    // git-history semantics (anchor-only). Each project also drops its OWN
-    // resolved Git-ignored paths (or keeps this fixed set as-is for a non-Git
-    // source) — see `resolveReferencedSourceIgnore` and the per-project merge
-    // below.
-    const additionalSourceBaseExclude = mergeExcludes(SANDBOX_WORKSPACE_HEAVY_DIR_EXCLUDES, [".git"]);
-    // Every delegated post-upload command (extract/wipe/remove-deleted/asset merge)
-    // must run under the run-specific timeout (`spec.timeoutMs`), not the provider
-    // sync client's default timeout — the two can differ, and before staging was
-    // routed through `syncIn` each of these ran via
-    // `client.run(cmd, { timeoutMs: spec.timeoutMs })`. When they mismatch, a
-    // command left without a `timeoutMs` outlives (or is killed under) the wrong
-    // limit. Stamp the run timeout onto every delegated command, preserving any
-    // command that already carries its own explicit timeout.
-    const withRunTimeout = (commands) => commands.map((command) => ({
-        ...command,
-        timeoutMs: command.timeoutMs ?? input.spec.timeoutMs,
-    }));
-    await withTempDir("paperclip-sandbox-sync-", async (tempDir) => {
-        const preservedNames = new Set([
-            ".paperclip-runtime",
-            ...(gitSnapshot ? [".git"] : []),
-            ...(input.preserveAbsentOnRestore ?? []),
-        ]);
-        // Stage one source directory into an isolated remote subdirectory through the
-        // unified `syncIn` seam. Both the workspace/asset tar path and the additional
-        // (referenced) project path use it: build one `SandboxSyncOperation` from the
-        // caller's `files` mappings (a host tarball as a single `file` mapping, or a
-        // whole `directory` mapping), carry any extract/wipe/merge steps as ordered
-        // `postUploadCommands`, confine the operation's source and target to their
-        // own roots (fail-closed), and delegate to `syncIn` (native transfer, or the
-        // base64-tar fallback). `finish` emits the terminal progress line.
-        const stageConfinedSyncIn = async (params) => {
-            const operations = [{
-                    operationId: nextSyncOperationId(),
-                    files: params.files,
-                    ...(params.postUploadCommands
-                        ? { postUploadCommands: withRunTimeout(params.postUploadCommands) }
-                        : {}),
-                }];
-            assertSyncOperationsConfined(operations, {
-                sourceRoots: params.sourceRoots,
-                targetRoots: params.targetRoots,
-            });
-            const upload = makeTransferProgress(input.onProgress, "Syncing", "to", params.progressLabel, { sink: input.onRuntimeProgress, phase: params.statusPhase });
-            const syncResult = await syncIn(operations);
-            // Prefer the transport's own byte total. It is the real count for a
-            // provider that has no host tarball to stat (a referenced project rides
-            // a `directory` mapping). Fall back to the caller-supplied count when
-            // the transport reports 0, so a provider that under-reports still
-            // shows the host-known workspace total.
-            const transferredBytes = sumSyncResultBytes(syncResult);
-            const reportedBytes = transferredBytes > 0 ? transferredBytes : params.progressBytes;
-            await upload.finish(reportedBytes, reportedBytes);
-        };
-        // Build the ordered inbound operation task list. Each task stages one inbound
-        // operation from start to end: it packs the bytes, confines the mappings, and
-        // uploads them. The shared scheduler starts the tasks. When the sync client
-        // permits concurrency, the scheduler keeps at most SYNC_OPERATION_CONCURRENCY_LIMIT
-        // tasks active. When the client does not permit concurrency, the scheduler runs
-        // one task at a time in this order. The scheduler settles every started task
-        // before it returns, so no upload outlives the coordinator and ACP never starts
-        // before the barrier.
-        const inboundTasks = [];
-        // A required-flag list, one entry per task and index-aligned with inboundTasks.
-        // The workspace and each asset are required operations: a rejection is fatal
-        // after the barrier. Each referenced project is a nonfatal operation: its task
-        // records its own failure and never rejects.
-        const inboundTaskIsRequired = [];
-        if (stageWorkspace || prepareWorkspaceSeed) {
-            inboundTaskIsRequired.push(true);
-            inboundTasks.push(() => runStepSpan("stage.workspace", async () => {
-                // A git-backed workspace and a plain workspace both stage through ONE
-                // confined `syncIn` operation. A git-backed workspace carries TWO host tars —
-                // the git-history clone and the working-tree overlay — as two `file` mappings
-                // on the SAME operation, with their extract commands as ordered
-                // `postUploadCommands`. One operation shares one mkdir, one confine guard, one
-                // `uploadFiles`, and one rename exec, so the second `syncIn` round trip is
-                // removed. Build the whole merged file set and command list BEFORE the confine
-                // guard runs (inside `stageConfinedSyncIn`); never append a mapping after it.
-                const workspaceFiles = [];
-                const workspacePostUploadCommands = [];
-                let workspaceUploadBytes = 0;
-                // Build both host tarballs (the git-history tar and the workspace-overlay
-                // tar) inside one host span named `pack`. This span makes the host pack
-                // time visible under the `stage.sync` step, where it is otherwise a hidden
-                // gap with no span. The transfer (`stageConfinedSyncIn`) runs after this
-                // span, so `pack` measures only the host tar-build cost. The runner
-                // defaults to a no-op, so a caller with no injected runner keeps the
-                // current behavior and control flow.
-                await runStepSpan("pack", async () => {
-                    // 1. git-history tar (git-backed workspace only). Both tar targets live under
-                    //    `runtimeRootDir` (`.paperclip-runtime/<adapterKey>`). The git extract
-                    //    wipes the target tree EXCEPT `.paperclip-runtime`, so the overlay tar,
-                    //    which sits under `.paperclip-runtime`, survives to run its own extract.
-                    if (gitSnapshot) {
-                        await emitRuntimeStatus(input.onRuntimeProgress, "git_sync", "Syncing git history to environment");
-                        const gitTarPath = path.join(tempDir, "git-workspace.tar");
-                        const remoteGitTar = path.posix.join(runtimeRootDir, "git-workspace-upload.tar");
-                        if (workspaceInboundMode === "durable_seed") {
-                            const durableGitArchive = input.workspaceDurableSeed?.gitArchivePath;
-                            if (!durableGitArchive) {
-                                throw new Error("workspace_durable_seed_git_missing");
+    let baselineSnapshot = null;
+    const cleanupWorkspaceSnapshot = async () => {
+        await disposeDirectorySnapshot(baselineSnapshot);
+        await disposeGitWorkspaceSnapshot(gitSnapshot);
+    };
+    try {
+        // A selected subfolder has no cloneable Git snapshot, but its parent
+        // repository's ignore rules still govern which files may leave the host.
+        // Use the same bounded, path-relative resolver as referenced project trees.
+        const directoryIgnore = syncWorkspace && !gitSnapshot && input.workspaceFileMode !== "all"
+            ? await resolveReferencedSourceIgnore(input.workspaceLocalDir)
+            : null;
+        if (directoryIgnore?.kind === "failed") {
+            throw new Error(`Workspace ignore scan failed: ${directoryIgnore.reason}`);
+        }
+        const gitIgnoredExcludes = directoryIgnore?.kind === "git" ? directoryIgnore.ignoredPaths : undefined;
+        const workspaceArchiveExclude = mergeExcludes(input.workspaceFileMode === "all" ? [] : SANDBOX_WORKSPACE_HEAVY_DIR_EXCLUDES, input.workspaceFileMode === "all" ? [] : [...GIT_ARCHIVE_EXCLUDES], input.workspaceExclude, gitIgnoredExcludes);
+        const restoreExclude = mergeExcludes(input.workspaceFileMode === "all" ? [] : SANDBOX_WORKSPACE_HEAVY_DIR_EXCLUDES, input.workspaceFileMode === "all" ? [] : [...GIT_ARCHIVE_EXCLUDES], [".paperclip-runtime"], input.preserveAbsentOnRestore, input.workspaceExclude, gitIgnoredExcludes);
+        const repositories = gitSnapshot?.repositories ?? [];
+        const workspaceRestoreExclude = mergeExcludes(restoreExclude, repositories.map((repo) => repo.path));
+        // The baseline "before" snapshot: a recursive walk of the whole workspace that
+        // `lstat`s every entry and SHA-256-hashes every file's bytes. This is the
+        // dominant cost in the pre-`pack` window — it reads the content of every
+        // non-excluded file, serially — so it earns its own span.
+        baselineSnapshot = syncWorkspace
+            ? (input.workspaceBaseline ??
+                (await runStepSpan("snapshot.baseline", () => captureDirectorySnapshot(input.workspaceLocalDir, {
+                    exclude: restoreExclude,
+                    ignoredPaths: gitSnapshot?.ignoredPaths,
+                    diskBacked: true,
+                }))))
+            : null;
+        // Every inbound staging step delegates to the provider through `client.syncIn`:
+        // the orchestrator no longer inlines `writeFile`+`run` or chooses a transport,
+        // and there is no `usesCustomProvision` native-diversion gate. `syncIn` is
+        // ALWAYS present in production — the command-managed client exposes a native
+        // transport (Daytona/Kubernetes `uploadFiles` + provider-executed post-upload
+        // commands) or a byte-identical base64-tar fallback that reproduces the prior
+        // `writeFile`+`run` sequence. Require it explicitly so a misconfigured client
+        // fails loud rather than silently skipping staging. `syncOut` stays optional
+        // (native-only) with a tar fallback on the restore path below.
+        const syncIn = input.client.syncIn;
+        if (typeof syncIn !== "function") {
+            throw new Error("prepareSandboxManagedRuntime requires a client that exposes syncIn " +
+                "(createCommandManagedRuntimeClient provides a native-or-fallback implementation).");
+        }
+        const nativeSyncOut = typeof input.client.syncOut === "function";
+        let syncOperationSeq = 0;
+        // Opaque, ordered, non-sensitive operation tokens — never a caller/asset id.
+        const nextSyncOperationId = () => `sync-op-${++syncOperationSeq}`;
+        // Remote directory of each additional (referenced) project that stages
+        // successfully, keyed by projectId. A project that fails to stage is absent.
+        const additionalSourceDirs = {};
+        // Each additional (referenced) project whose staging failed, paired with the
+        // failure message. Per-project failure isolation keeps the run and the other
+        // projects going; this list makes each failure a first-class, reported outcome.
+        const additionalSourceFailures = [];
+        // Additional projects stage as plain trees. Drop the heavy build/cache dirs a
+        // reference tree does not need, and `.git` — additional sources never carry
+        // git-history semantics (anchor-only). Each project also drops its OWN
+        // resolved Git-ignored paths (or keeps this fixed set as-is for a non-Git
+        // source) — see `resolveReferencedSourceIgnore` and the per-project merge
+        // below.
+        const additionalSourceBaseExclude = mergeExcludes(SANDBOX_WORKSPACE_HEAVY_DIR_EXCLUDES, [".git"]);
+        // Every delegated post-upload command (extract/wipe/remove-deleted/asset merge)
+        // must run under the run-specific timeout (`spec.timeoutMs`), not the provider
+        // sync client's default timeout — the two can differ, and before staging was
+        // routed through `syncIn` each of these ran via
+        // `client.run(cmd, { timeoutMs: spec.timeoutMs })`. When they mismatch, a
+        // command left without a `timeoutMs` outlives (or is killed under) the wrong
+        // limit. Stamp the run timeout onto every delegated command, preserving any
+        // command that already carries its own explicit timeout.
+        const withRunTimeout = (commands) => commands.map((command) => ({
+            ...command,
+            timeoutMs: command.timeoutMs ?? input.spec.timeoutMs,
+        }));
+        await withTempDir("paperclip-sandbox-sync-", async (tempDir) => {
+            const preservedNames = new Set([
+                ".paperclip-runtime",
+                ...(gitSnapshot ? [".git"] : []),
+                ...(input.preserveAbsentOnRestore ?? []),
+            ]);
+            // Stage one source directory into an isolated remote subdirectory through the
+            // unified `syncIn` seam. Both the workspace/asset tar path and the additional
+            // (referenced) project path use it: build one `SandboxSyncOperation` from the
+            // caller's `files` mappings (a host tarball as a single `file` mapping, or a
+            // whole `directory` mapping), carry any extract/wipe/merge steps as ordered
+            // `postUploadCommands`, confine the operation's source and target to their
+            // own roots (fail-closed), and delegate to `syncIn` (native transfer, or the
+            // base64-tar fallback). `finish` emits the terminal progress line.
+            const stageConfinedSyncIn = async (params) => {
+                const operations = [{
+                        operationId: nextSyncOperationId(),
+                        files: params.files,
+                        ...(params.postUploadCommands
+                            ? { postUploadCommands: withRunTimeout(params.postUploadCommands) }
+                            : {}),
+                    }];
+                assertSyncOperationsConfined(operations, {
+                    sourceRoots: params.sourceRoots,
+                    targetRoots: params.targetRoots,
+                });
+                const upload = makeTransferProgress(input.onProgress, "Syncing", "to", params.progressLabel, { sink: input.onRuntimeProgress, phase: params.statusPhase });
+                const syncResult = await syncIn(operations);
+                // Prefer the transport's own byte total. It is the real count for a
+                // provider that has no host tarball to stat (a referenced project rides
+                // a `directory` mapping). Fall back to the caller-supplied count when
+                // the transport reports 0, so a provider that under-reports still
+                // shows the host-known workspace total.
+                const transferredBytes = sumSyncResultBytes(syncResult);
+                const reportedBytes = transferredBytes > 0 ? transferredBytes : params.progressBytes;
+                await upload.finish(reportedBytes, reportedBytes);
+            };
+            // Build the ordered inbound operation task list. Each task stages one inbound
+            // operation from start to end: it packs the bytes, confines the mappings, and
+            // uploads them. The shared scheduler starts the tasks. When the sync client
+            // permits concurrency, the scheduler keeps at most SYNC_OPERATION_CONCURRENCY_LIMIT
+            // tasks active. When the client does not permit concurrency, the scheduler runs
+            // one task at a time in this order. The scheduler settles every started task
+            // before it returns, so no upload outlives the coordinator and ACP never starts
+            // before the barrier.
+            const inboundTasks = [];
+            // A required-flag list, one entry per task and index-aligned with inboundTasks.
+            // The workspace and each asset are required operations: a rejection is fatal
+            // after the barrier. Each referenced project is a nonfatal operation: its task
+            // records its own failure and never rejects.
+            const inboundTaskIsRequired = [];
+            if (stageWorkspace || prepareWorkspaceSeed) {
+                inboundTaskIsRequired.push(true);
+                inboundTasks.push(() => runStepSpan("stage.workspace", async () => {
+                    // A git-backed workspace and a plain workspace both stage through ONE
+                    // confined `syncIn` operation. A git-backed workspace carries TWO host tars —
+                    // the git-history clone and the working-tree overlay — as two `file` mappings
+                    // on the SAME operation, with their extract commands as ordered
+                    // `postUploadCommands`. One operation shares one mkdir, one confine guard, one
+                    // `uploadFiles`, and one rename exec, so the second `syncIn` round trip is
+                    // removed. Build the whole merged file set and command list BEFORE the confine
+                    // guard runs (inside `stageConfinedSyncIn`); never append a mapping after it.
+                    const workspaceFiles = [];
+                    const workspacePostUploadCommands = [];
+                    let workspaceUploadBytes = 0;
+                    // Build both host tarballs (the git-history tar and the workspace-overlay
+                    // tar) inside one host span named `pack`. This span makes the host pack
+                    // time visible under the `stage.sync` step, where it is otherwise a hidden
+                    // gap with no span. The transfer (`stageConfinedSyncIn`) runs after this
+                    // span, so `pack` measures only the host tar-build cost. The runner
+                    // defaults to a no-op, so a caller with no injected runner keeps the
+                    // current behavior and control flow.
+                    await runStepSpan("pack", async () => {
+                        // 1. git-history tar (git-backed workspace only). Both tar targets live under
+                        //    `runtimeRootDir` (`.paperclip-runtime/<adapterKey>`). The git extract
+                        //    wipes the target tree EXCEPT `.paperclip-runtime`, so the overlay tar,
+                        //    which sits under `.paperclip-runtime`, survives to run its own extract.
+                        if (gitSnapshot) {
+                            await emitRuntimeStatus(input.onRuntimeProgress, "git_sync", "Syncing git history to environment");
+                            const gitTarPath = path.join(tempDir, "git-workspace.tar");
+                            const remoteGitTar = path.posix.join(runtimeRootDir, "git-workspace-upload.tar");
+                            if (workspaceInboundMode === "durable_seed") {
+                                const durableGitArchive = input.workspaceDurableSeed?.gitArchivePath;
+                                if (!durableGitArchive) {
+                                    throw new Error("workspace_durable_seed_git_missing");
+                                }
+                                await copyDurableSeedArchive({
+                                    sourcePath: durableGitArchive,
+                                    targetPath: gitTarPath,
+                                    expectedSha256: input.workspaceDurableSeed?.gitArchiveSha256,
+                                });
+                            }
+                            else {
+                                await withShallowGitWorkspaceClone({
+                                    localDir: input.workspaceLocalDir,
+                                    snapshot: gitSnapshot,
+                                }, async (cloneDir) => {
+                                    await createTarballFromDirectory({
+                                        localDir: cloneDir,
+                                        archivePath: gitTarPath,
+                                        exclude: [".paperclip-runtime"],
+                                    });
+                                });
+                                if (input.workspaceDurableSeed?.gitArchivePath) {
+                                    await persistDurableSeedArchive({
+                                        sourcePath: gitTarPath,
+                                        targetPath: input.workspaceDurableSeed.gitArchivePath,
+                                    });
+                                }
                             }
+                            workspaceFiles.push({
+                                sourcePath: gitTarPath,
+                                targetPath: remoteGitTar,
+                                kind: "file",
+                                access: "rw",
+                                writablePath: workspaceRemoteDir,
+                            });
+                            workspacePostUploadCommands.push({
+                                command: buildWorkspaceTarExtractCommand({
+                                    workspaceRemoteDir,
+                                    remoteTar: remoteGitTar,
+                                    wipeExceptNames: [".paperclip-runtime"],
+                                }),
+                            });
+                            workspaceUploadBytes += (await fs.stat(gitTarPath)).size;
+                        }
+                        // 2. workspace-overlay tar. A git-backed overlay merges on top of the just
+                        //    extracted git tree (no wipe); a plain workspace wipes every child except
+                        //    the preserved names first. The extract runs AFTER the git extract.
+                        await emitRuntimeStatus(input.onRuntimeProgress, "config_sync", "Syncing workspace to environment");
+                        const workspaceTarPath = path.join(tempDir, "workspace.tar");
+                        if (workspaceInboundMode === "durable_seed") {
                             await copyDurableSeedArchive({
-                                sourcePath: durableGitArchive,
-                                targetPath: gitTarPath,
-                                expectedSha256: input.workspaceDurableSeed?.gitArchiveSha256,
+                                sourcePath: input.workspaceDurableSeed.workspaceArchivePath,
+                                targetPath: workspaceTarPath,
+                                expectedSha256: input.workspaceDurableSeed.workspaceArchiveSha256,
                             });
                         }
                         else {
-                            await withShallowGitWorkspaceClone({
-                                localDir: input.workspaceLocalDir,
-                                snapshot: gitSnapshot,
-                            }, async (cloneDir) => {
-                                await createTarballFromDirectory({
-                                    localDir: cloneDir,
-                                    archivePath: gitTarPath,
-                                    exclude: [".paperclip-runtime"],
+                            const workspaceArchiveDir = gitSnapshot
+                                ? path.join(tempDir, "workspace-overlay")
+                                : input.workspaceLocalDir;
+                            if (gitSnapshot) {
+                                await copySelectedWorkspaceEntries({
+                                    sourceRoot: workspaceRoot,
+                                    targetDir: workspaceArchiveDir,
+                                    relativePaths: gitSnapshot.overlayPaths,
+                                    ignoredPaths: gitSnapshot.ignoredPaths,
+                                    exclude: workspaceArchiveExclude,
                                 });
+                            }
+                            await createTarballFromDirectory({
+                                localDir: workspaceArchiveDir,
+                                archivePath: workspaceTarPath,
+                                exclude: gitSnapshot ? undefined : workspaceArchiveExclude,
                             });
-                            if (input.workspaceDurableSeed?.gitArchivePath) {
+                            if (input.workspaceDurableSeed) {
                                 await persistDurableSeedArchive({
-                                    sourcePath: gitTarPath,
-                                    targetPath: input.workspaceDurableSeed.gitArchivePath,
+                                    sourcePath: workspaceTarPath,
+                                    targetPath: input.workspaceDurableSeed.workspaceArchivePath,
                                 });
                             }
                         }
+                        const remoteWorkspaceTar = path.posix.join(runtimeRootDir, "workspace-upload.tar");
                         workspaceFiles.push({
-                            sourcePath: gitTarPath,
-                            targetPath: remoteGitTar,
+                            sourcePath: workspaceTarPath,
+                            targetPath: remoteWorkspaceTar,
                             kind: "file",
                             access: "rw",
                             writablePath: workspaceRemoteDir,
@@ -890,498 +951,468 @@ export async function prepareSandboxManagedRuntime(input) {
                         workspacePostUploadCommands.push({
                             command: buildWorkspaceTarExtractCommand({
                                 workspaceRemoteDir,
-                                remoteTar: remoteGitTar,
-                                wipeExceptNames: [".paperclip-runtime"],
+                                remoteTar: remoteWorkspaceTar,
+                                wipeExceptNames: gitSnapshot ? null : [...preservedNames],
                             }),
                         });
-                        workspaceUploadBytes += (await fs.stat(gitTarPath)).size;
-                    }
-                    // 2. workspace-overlay tar. A git-backed overlay merges on top of the just
-                    //    extracted git tree (no wipe); a plain workspace wipes every child except
-                    //    the preserved names first. The extract runs AFTER the git extract.
-                    await emitRuntimeStatus(input.onRuntimeProgress, "config_sync", "Syncing workspace to environment");
-                    const workspaceTarPath = path.join(tempDir, "workspace.tar");
-                    if (workspaceInboundMode === "durable_seed") {
-                        await copyDurableSeedArchive({
-                            sourcePath: input.workspaceDurableSeed.workspaceArchivePath,
-                            targetPath: workspaceTarPath,
-                            expectedSha256: input.workspaceDurableSeed.workspaceArchiveSha256,
-                        });
-                    }
-                    else {
-                        const workspaceArchiveDir = gitSnapshot
-                            ? path.join(tempDir, "workspace-overlay")
-                            : input.workspaceLocalDir;
-                        if (gitSnapshot) {
-                            await copySelectedWorkspaceEntries({
-                                sourceRoot: workspaceRoot,
-                                targetDir: workspaceArchiveDir,
-                                relativePaths: gitSnapshot.overlayPaths,
-                                exclude: workspaceArchiveExclude,
-                            });
-                        }
-                        await createTarballFromDirectory({
-                            localDir: workspaceArchiveDir,
-                            archivePath: workspaceTarPath,
-                            exclude: gitSnapshot ? undefined : workspaceArchiveExclude,
-                        });
-                        if (input.workspaceDurableSeed) {
-                            await persistDurableSeedArchive({
-                                sourcePath: workspaceTarPath,
-                                targetPath: input.workspaceDurableSeed.workspaceArchivePath,
-                            });
+                        // 3. Optional remove-deleted-paths command runs LAST, after both extracts.
+                        if (gitSnapshot && (isPathManifest(gitSnapshot.deletedPaths) ? gitSnapshot.deletedPaths.count : gitSnapshot.deletedPaths.length) > 0) {
+                            const deletedManifest = path.join(tempDir, "deleted.nul");
+                            const remoteDeletedManifest = path.posix.join(runtimeRootDir, "deleted.nul");
+                            await writeWorkspacePaths(gitSnapshot.deletedPaths, deletedManifest);
+                            workspaceFiles.push({ sourcePath: deletedManifest, targetPath: remoteDeletedManifest, kind: "file", access: "rw", writablePath: runtimeRootDir });
+                            workspacePostUploadCommands.push({ command: buildRemoveDeletedPathsCommand({ remoteDir: workspaceRemoteDir, manifestPath: remoteDeletedManifest }) });
                         }
-                    }
-                    const remoteWorkspaceTar = path.posix.join(runtimeRootDir, "workspace-upload.tar");
-                    workspaceFiles.push({
-                        sourcePath: workspaceTarPath,
-                        targetPath: remoteWorkspaceTar,
-                        kind: "file",
-                        access: "rw",
-                        writablePath: workspaceRemoteDir,
+                        workspaceUploadBytes += (await fs.stat(workspaceTarPath)).size;
                     });
-                    workspacePostUploadCommands.push({
-                        command: buildWorkspaceTarExtractCommand({
-                            workspaceRemoteDir,
-                            remoteTar: remoteWorkspaceTar,
-                            wipeExceptNames: gitSnapshot ? null : [...preservedNames],
-                        }),
+                    if (!stageWorkspace)
+                        return;
+                    // One confined `syncIn` for the whole merged workspace file set. The confine
+                    // guard covers every mapping BEFORE any bytes upload (fail-closed): a source
+                    // or target escape in EITHER tar mapping stops the upload of both.
+                    await stageConfinedSyncIn({
+                        files: workspaceFiles,
+                        postUploadCommands: workspacePostUploadCommands,
+                        sourceRoots: [tempDir],
+                        targetRoots: [runtimeRootDir],
+                        progressLabel: "workspace",
+                        statusPhase: "config_sync",
+                        progressBytes: workspaceUploadBytes,
                     });
-                    // 3. Optional remove-deleted-paths command runs LAST, after both extracts.
-                    if (gitSnapshot && gitSnapshot.deletedPaths.length > 0) {
-                        workspacePostUploadCommands.push({
-                            command: buildRemoveDeletedPathsCommand({
-                                remoteDir: workspaceRemoteDir,
-                                deletedPaths: gitSnapshot.deletedPaths,
-                            }),
-                        });
-                    }
-                    workspaceUploadBytes += (await fs.stat(workspaceTarPath)).size;
-                });
-                if (!stageWorkspace)
-                    return;
-                // One confined `syncIn` for the whole merged workspace file set. The confine
-                // guard covers every mapping BEFORE any bytes upload (fail-closed): a source
-                // or target escape in EITHER tar mapping stops the upload of both.
-                await stageConfinedSyncIn({
-                    files: workspaceFiles,
-                    postUploadCommands: workspacePostUploadCommands,
-                    sourceRoots: [tempDir],
-                    targetRoots: [runtimeRootDir],
-                    progressLabel: "workspace",
-                    statusPhase: "config_sync",
-                    progressBytes: workspaceUploadBytes,
-                });
-            }));
-        }
-        for (const asset of input.assets ?? []) {
-            inboundTaskIsRequired.push(true);
-            inboundTasks.push(() => runStepSpan(`stage.asset.${asset.key}`, async () => {
-                await emitRuntimeStatus(input.onRuntimeProgress, "config_sync", "Syncing runtime assets to environment");
-                const remoteAssetDir = path.posix.join(runtimeRootDir, asset.key);
-                const remoteAssetTar = path.posix.join(runtimeRootDir, `${asset.key}-upload.tar`);
-                // Every asset — default OR custom-provisioned (e.g. an adapter credential
-                // merge) — rides one `syncIn` operation: the asset tar plus any staged
-                // helper files as `files` mappings, and the extract/merge command as the
-                // ordered post-upload command. There is no native-diversion gate; a
-                // custom-provisioned asset's bytes now ride native `uploadFiles` and its
-                // command runs as a provider-executed post-upload command.
-                const assetTarPath = path.join(tempDir, `${asset.key}.tar`);
-                await createTarballFromDirectory({
-                    localDir: asset.localDir,
-                    archivePath: assetTarPath,
-                    followSymlinks: asset.followSymlinks,
-                    exclude: asset.exclude,
-                });
-                const files = [
-                    { sourcePath: assetTarPath, targetPath: remoteAssetTar, kind: "file", access: "rw", writablePath: remoteAssetDir },
-                ];
-                // Stage provision helper files (e.g. the merge scripts) into the temp dir
-                // and map them alongside the asset tar so they ride the same native upload.
-                for (const stageFile of asset.provision?.stageFiles ?? []) {
-                    const safeName = stageFile.name;
-                    if (/[\\/]|\.\.(\.|$)/.test(safeName) || safeName === "..") {
-                        throw new Error(`provision stageFile.name must be a simple basename, got: ${safeName}`);
-                    }
-                    const stageBytes = typeof stageFile.contents === "string"
-                        ? Buffer.from(stageFile.contents)
-                        : stageFile.contents;
-                    const stageHostPath = path.join(tempDir, `${asset.key}.stage.${safeName}`);
-                    await fs.writeFile(stageHostPath, stageBytes);
-                    // A stage helper file (for example a merge script) is a read-only input
-                    // that the provision command reads; the agent does not change it and does
-                    // not keep it. So it is `access: "ro"` and never joins the writable set.
-                    files.push({
-                        sourcePath: stageHostPath,
-                        targetPath: path.posix.join(runtimeRootDir, safeName),
-                        kind: "file",
-                        access: "ro",
+                }));
+            }
+            for (const asset of input.assets ?? []) {
+                inboundTaskIsRequired.push(true);
+                inboundTasks.push(() => runStepSpan(`stage.asset.${asset.key}`, async () => {
+                    await emitRuntimeStatus(input.onRuntimeProgress, "config_sync", "Syncing runtime assets to environment");
+                    const remoteAssetDir = path.posix.join(runtimeRootDir, asset.key);
+                    const remoteAssetTar = path.posix.join(runtimeRootDir, `${asset.key}-upload.tar`);
+                    // Every asset — default OR custom-provisioned (e.g. an adapter credential
+                    // merge) — rides one `syncIn` operation: the asset tar plus any staged
+                    // helper files as `files` mappings, and the extract/merge command as the
+                    // ordered post-upload command. There is no native-diversion gate; a
+                    // custom-provisioned asset's bytes now ride native `uploadFiles` and its
+                    // command runs as a provider-executed post-upload command.
+                    const assetTarPath = path.join(tempDir, `${asset.key}.tar`);
+                    await createTarballFromDirectory({
+                        localDir: asset.localDir,
+                        archivePath: assetTarPath,
+                        followSymlinks: asset.followSymlinks,
+                        exclude: asset.exclude,
                     });
-                }
-                const postUploadCommand = asset.provision?.postUploadCommand?.({
-                    assetTarPath: remoteAssetTar,
-                    assetDir: remoteAssetDir,
-                    runtimeRootDir,
-                }) ?? buildDefaultExtractRuntimeAssetCommand({ remoteAssetDir, remoteAssetTar });
-                const assetTarSize = (await fs.stat(assetTarPath)).size;
-                await stageConfinedSyncIn({
-                    files,
-                    postUploadCommands: [{ command: postUploadCommand }],
-                    sourceRoots: [tempDir],
-                    targetRoots: [runtimeRootDir],
-                    progressLabel: asset.key,
-                    statusPhase: "config_sync",
-                    progressBytes: assetTarSize,
-                });
-            }));
-        }
-        // Stage each referenced (additional) project as a plain, read-only tree in
-        // its OWN isolated remote directory (`project-<projectId>`). An additional
-        // project rides one confined `syncIn` directory mapping — a native directory
-        // transfer, or the base64-tar fallback — with source and target confined to
-        // their own roots. No workspace, git-history, or `.paperclip-runtime`
-        // semantics apply; those stay anchor-only. Per-project failure isolation: one
-        // project's confinement or sync failure logs a warning and is skipped, and
-        // the run plus the other projects continue. Only a project that stages
-        // successfully appears in `additionalSourceDirs`.
-        const additionalSourceList = input.additionalSources ?? [];
-        // Record each referenced-project failure in its input-order slot. Slot order
-        // keeps the failure list stable no matter the task completion order under
-        // concurrency.
-        const additionalFailureSlots = additionalSourceList.map(() => null);
-        additionalSourceList.forEach((source, sourceIndex) => {
-            inboundTaskIsRequired.push(false);
-            inboundTasks.push(() => runStepSpan(`stage.project.${source.projectId}`, async () => {
-                const { localPath, projectId, ignoreResolution } = source;
-                const label = `project-${projectId}`;
-                try {
-                    if (!path.posix.isAbsolute(localPath)) {
-                        throw new Error(`additional source localPath is not an absolute path: ${localPath}`);
-                    }
-                    if (projectId.length === 0 ||
-                        projectId.includes("/") ||
-                        projectId.includes("\\") ||
-                        projectId.includes("..")) {
-                        throw new Error(`additional source projectId is not a simple path segment: ${projectId}`);
-                    }
-                    // Fail closed: a project whose ignore resolution failed is not staged
-                    // at all. Shipping it with only the fixed heavy-directory excludes
-                    // would defeat the resolution's purpose.
-                    if (ignoreResolution.kind === "failed") {
-                        throw new Error(`referenced project ignore resolution failed: ${ignoreResolution.reason}`);
+                    const files = [
+                        { sourcePath: assetTarPath, targetPath: remoteAssetTar, kind: "file", access: "rw", writablePath: remoteAssetDir },
+                    ];
+                    // Stage provision helper files (e.g. the merge scripts) into the temp dir
+                    // and map them alongside the asset tar so they ride the same native upload.
+                    for (const stageFile of asset.provision?.stageFiles ?? []) {
+                        const safeName = stageFile.name;
+                        if (/[\\/]|\.\.(\.|$)/.test(safeName) || safeName === "..") {
+                            throw new Error(`provision stageFile.name must be a simple basename, got: ${safeName}`);
+                        }
+                        const stageBytes = typeof stageFile.contents === "string"
+                            ? Buffer.from(stageFile.contents)
+                            : stageFile.contents;
+                        const stageHostPath = path.join(tempDir, `${asset.key}.stage.${safeName}`);
+                        await fs.writeFile(stageHostPath, stageBytes);
+                        // A stage helper file (for example a merge script) is a read-only input
+                        // that the provision command reads; the agent does not change it and does
+                        // not keep it. So it is `access: "ro"` and never joins the writable set.
+                        files.push({
+                            sourcePath: stageHostPath,
+                            targetPath: path.posix.join(runtimeRootDir, safeName),
+                            kind: "file",
+                            access: "ro",
+                        });
                     }
-                    const remoteProjectDir = path.posix.join(runtimeRootDir, label);
-                    const exclude = mergeExcludes(additionalSourceBaseExclude, referencedSourceIgnoreExcludeEntries(ignoreResolution));
-                    await emitRuntimeStatus(input.onRuntimeProgress, "config_sync", "Syncing referenced project to environment");
+                    const postUploadCommand = asset.provision?.postUploadCommand?.({
+                        assetTarPath: remoteAssetTar,
+                        assetDir: remoteAssetDir,
+                        runtimeRootDir,
+                    }) ?? buildDefaultExtractRuntimeAssetCommand({ remoteAssetDir, remoteAssetTar });
+                    const assetTarSize = (await fs.stat(assetTarPath)).size;
                     await stageConfinedSyncIn({
-                        files: [{
-                                sourcePath: localPath,
-                                targetPath: remoteProjectDir,
-                                kind: "directory",
-                                exclude,
-                                access: "ro",
-                            }],
-                        sourceRoots: [localPath],
-                        targetRoots: [remoteProjectDir],
-                        progressLabel: label,
+                        files,
+                        postUploadCommands: [{ command: postUploadCommand }],
+                        sourceRoots: [tempDir],
+                        targetRoots: [runtimeRootDir],
+                        progressLabel: asset.key,
                         statusPhase: "config_sync",
-                        progressBytes: 0,
+                        progressBytes: assetTarSize,
                     });
-                    additionalSourceDirs[projectId] = remoteProjectDir;
-                }
-                catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
-                    // Record the failure as a first-class per-project outcome so the run can count it in the
-                    // requested-vs-synced accounting and surface the reason on the run result and the run log.
-                    // The structured slot carries the reason, so no `console.warn` line is needed here.
-                    additionalFailureSlots[sourceIndex] = { projectId, error: message };
-                }
-            }));
-        });
-        // Run every inbound operation through the shared scheduler. It starts the
-        // tasks under the client's concurrency permission and the bound, and it
-        // settles every started task before it returns. This is the startup barrier:
-        // the coordinator returns only after every upload settles.
-        const inboundResults = await scheduleSyncOperations(inboundTasks, input.client.allowConcurrentSyncOperations === true, SYNC_OPERATION_CONCURRENCY_LIMIT);
-        // Collect the referenced-project failures in stable input order.
-        for (const failure of additionalFailureSlots) {
-            if (failure) {
-                additionalSourceFailures.push(failure);
-            }
-        }
-        // Select a fatal failure in stable operation order. The workspace comes first,
-        // then each asset. A referenced-project task never rejects, so a nonfatal
-        // outcome never appears here. Raise the first required rejection, so two
-        // required failures raise the earlier one.
-        for (let index = 0; index < inboundResults.length; index += 1) {
-            const result = inboundResults[index];
-            if (inboundTaskIsRequired[index] && result.status === "rejected") {
-                throw result.reason;
+                }));
             }
-        }
-    });
-    const assetDirs = Object.fromEntries((input.assets ?? []).map((asset) => [asset.key, path.posix.join(runtimeRootDir, asset.key)]));
-    return {
-        spec: input.spec,
-        workspaceLocalDir: input.workspaceLocalDir,
-        workspaceRemoteDir,
-        runtimeRootDir,
-        assetDirs,
-        additionalSourceDirs,
-        additionalSourceFailures,
-        workspaceSyncSnapshot: syncWorkspace && baselineSnapshot
-            ? { baseline: baselineSnapshot, gitSnapshot }
-            : null,
-        restoreWorkspace: async (onProgress) => {
-            const restoreSink = onProgress ?? input.onProgress;
-            // Build the ordered outbound restore task list. Each task runs one
-            // restore from start to end: the workspace restore, or one asset restore.
-            // The shared scheduler starts the tasks. When the sync client permits
-            // concurrency, the scheduler keeps at most SYNC_OPERATION_CONCURRENCY_LIMIT
-            // tasks active. When the client does not permit concurrency, the scheduler
-            // runs one task at a time in this order. The scheduler settles every
-            // started task before it returns, so lease teardown never starts while an
-            // outbound restore task still writes host data.
-            const outboundTasks = [];
-            // The workspace restore task runs only when the run syncs the workspace.
-            // The task exports the sandbox git history (git-backed workspace), reads
-            // the sandbox workspace back, and merges it into the host workspace root.
-            // The merge is the only outbound write inside the host workspace root.
-            // Every other task writes a disjoint host target: an asset restore writes
-            // its own store outside the workspace root. So the workspace task and the
-            // asset tasks share one parallel set. Keep any future asset that must write
-            // inside the host workspace root out of this set, and run it after the
-            // merge. Each task gets its own restore temp directory, so two concurrent
-            // tasks never share scratch state.
-            if (syncWorkspace) {
-                outboundTasks.push(() => runStepSpan("restore.workspace", async () => {
-                    // Each repository owns its Git history and merge. The parent baseline also
-                    // records child files so restart recovery has their original merge inputs.
-                    for (const repository of repositories) {
-                        const prefix = `${repository.path}/`;
-                        const localDir = path.join(input.workspaceLocalDir, repository.path);
-                        if (await fs.realpath(localDir) !== path.join(await fs.realpath(input.workspaceLocalDir), repository.path)) {
-                            throw new Error("Project repository escaped its workspace");
+            // Stage each referenced (additional) project as a plain, read-only tree in
+            // its OWN isolated remote directory (`project-<projectId>`). An additional
+            // project rides one confined `syncIn` directory mapping — a native directory
+            // transfer, or the base64-tar fallback — with source and target confined to
+            // their own roots. No workspace, git-history, or `.paperclip-runtime`
+            // semantics apply; those stay anchor-only. Per-project failure isolation: one
+            // project's confinement or sync failure logs a warning and is skipped, and
+            // the run plus the other projects continue. Only a project that stages
+            // successfully appears in `additionalSourceDirs`.
+            const additionalSourceList = input.additionalSources ?? [];
+            // Record each referenced-project failure in its input-order slot. Slot order
+            // keeps the failure list stable no matter the task completion order under
+            // concurrency.
+            const additionalFailureSlots = additionalSourceList.map(() => null);
+            additionalSourceList.forEach((source, sourceIndex) => {
+                inboundTaskIsRequired.push(false);
+                inboundTasks.push(() => runStepSpan(`stage.project.${source.projectId}`, async () => {
+                    const { localPath, projectId, ignoreResolution } = source;
+                    const label = `project-${projectId}`;
+                    try {
+                        if (!path.posix.isAbsolute(localPath)) {
+                            throw new Error(`additional source localPath is not an absolute path: ${localPath}`);
+                        }
+                        if (projectId.length === 0 ||
+                            projectId.includes("/") ||
+                            projectId.includes("\\") ||
+                            projectId.includes("..")) {
+                            throw new Error(`additional source projectId is not a simple path segment: ${projectId}`);
                         }
-                        const nestedExclude = mergeExcludes(repository.snapshot.ignoredPaths, baselineSnapshot.exclude.flatMap((entry) => entry.startsWith(prefix) ? [entry.slice(prefix.length)]
-                            : entry.startsWith("*/") ? [entry] : []));
-                        const nested = await prepareSandboxManagedRuntime({
-                            spec: { ...input.spec, remoteCwd: path.posix.join(workspaceRemoteDir, repository.path) },
-                            client: input.client,
-                            adapterKey: input.adapterKey,
-                            workspaceLocalDir: localDir,
-                            workspaceInboundMode: "adopt_remote",
-                            workspaceGitSnapshot: repository.snapshot,
-                            workspaceExclude: nestedExclude,
-                            workspaceBaseline: {
-                                exclude: mergeExcludes(SANDBOX_WORKSPACE_HEAVY_DIR_EXCLUDES, [...GIT_ARCHIVE_EXCLUDES], [".paperclip-runtime"], nestedExclude),
-                                entries: new Map([...baselineSnapshot.entries]
-                                    .filter(([entry]) => entry.startsWith(prefix))
-                                    .map(([entry, value]) => [entry.slice(prefix.length), value])),
-                            },
-                            onRuntimeProgress: input.onRuntimeProgress,
+                        // Fail closed: a project whose ignore resolution failed is not staged
+                        // at all. Shipping it with only the fixed heavy-directory excludes
+                        // would defeat the resolution's purpose.
+                        if (ignoreResolution.kind === "failed") {
+                            throw new Error(`referenced project ignore resolution failed: ${ignoreResolution.reason}`);
+                        }
+                        const remoteProjectDir = path.posix.join(runtimeRootDir, label);
+                        const exclude = mergeExcludes(additionalSourceBaseExclude, referencedSourceIgnoreExcludeEntries(ignoreResolution));
+                        await emitRuntimeStatus(input.onRuntimeProgress, "config_sync", "Syncing referenced project to environment");
+                        await stageConfinedSyncIn({
+                            files: [{
+                                    sourcePath: localPath,
+                                    targetPath: remoteProjectDir,
+                                    kind: "directory",
+                                    exclude,
+                                    access: "ro",
+                                }],
+                            sourceRoots: [localPath],
+                            targetRoots: [remoteProjectDir],
+                            progressLabel: label,
+                            statusPhase: "config_sync",
+                            progressBytes: 0,
                         });
-                        await nested.restoreWorkspace(restoreSink);
+                        additionalSourceDirs[projectId] = remoteProjectDir;
                     }
-                    await withTempDir("paperclip-sandbox-restore-", async (tempDir) => {
-                        let importedRef = null;
-                        let importedHead = null;
-                        let remoteWorkspaceStatus = "dirty";
-                        try {
-                            if (gitSnapshot) {
-                                await emitRuntimeStatus(input.onRuntimeProgress, "export", "Exporting git changes from environment");
-                                importedRef = createImportedGitRef("sandbox");
-                                const remoteGitBundle = path.posix.join(runtimeRootDir, "git-delta.bundle");
-                                const remoteWorkspaceStatusPath = path.posix.join(runtimeRootDir, "workspace-status.txt");
-                                const exportRef = createRemoteGitExportRef("sandbox");
-                                const localBundlePath = path.join(tempDir, "git-delta.bundle");
-                                // Export the sandbox history and import it into the host workspace.
-                                // The delta bundle assumes the host holds the bundle's boundary
-                                // commit; when the host has been reset far enough that it does not,
-                                // the import fails on a missing prerequisite. In that case re-export
-                                // a full, self-contained bundle from the still-live sandbox rather
-                                // than discard the completed run.
-                                const exportAndImport = async (forceFullBundle) => {
-                                    await input.client.run(`sh -c ${shellQuote(buildRemoteGitDeltaBundleScript({
-                                        remoteDir: workspaceRemoteDir,
-                                        baseSha: gitSnapshot.headCommit,
-                                        exportRef,
-                                        bundlePath: remoteGitBundle,
-                                        statusPath: forceFullBundle ? undefined : remoteWorkspaceStatusPath,
-                                        forceFullBundle,
-                                    }))}`, { timeoutMs: input.spec.timeoutMs });
-                                    const gitExport = makeTransferProgress(restoreSink, "Exporting git history", "from", undefined, { sink: input.onRuntimeProgress, phase: "export" });
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        // Record the failure as a first-class per-project outcome so the run can count it in the
+                        // requested-vs-synced accounting and surface the reason on the run result and the run log.
+                        // The structured slot carries the reason, so no `console.warn` line is needed here.
+                        additionalFailureSlots[sourceIndex] = { projectId, error: message };
+                    }
+                }));
+            });
+            // Run every inbound operation through the shared scheduler. It starts the
+            // tasks under the client's concurrency permission and the bound, and it
+            // settles every started task before it returns. This is the startup barrier:
+            // the coordinator returns only after every upload settles.
+            const inboundResults = await scheduleSyncOperations(inboundTasks, input.client.allowConcurrentSyncOperations === true, SYNC_OPERATION_CONCURRENCY_LIMIT);
+            // Collect the referenced-project failures in stable input order.
+            for (const failure of additionalFailureSlots) {
+                if (failure) {
+                    additionalSourceFailures.push(failure);
+                }
+            }
+            // Select a fatal failure in stable operation order. The workspace comes first,
+            // then each asset. A referenced-project task never rejects, so a nonfatal
+            // outcome never appears here. Raise the first required rejection, so two
+            // required failures raise the earlier one.
+            for (let index = 0; index < inboundResults.length; index += 1) {
+                const result = inboundResults[index];
+                if (inboundTaskIsRequired[index] && result.status === "rejected") {
+                    throw result.reason;
+                }
+            }
+        });
+        const assetDirs = Object.fromEntries((input.assets ?? []).map((asset) => [asset.key, path.posix.join(runtimeRootDir, asset.key)]));
+        return {
+            spec: input.spec,
+            workspaceLocalDir: input.workspaceLocalDir,
+            workspaceRemoteDir,
+            runtimeRootDir,
+            assetDirs,
+            additionalSourceDirs,
+            additionalSourceFailures,
+            workspaceSyncSnapshot: syncWorkspace && baselineSnapshot
+                ? { baseline: baselineSnapshot, gitSnapshot }
+                : null,
+            cleanupWorkspaceSnapshot,
+            restoreWorkspace: async (onProgress) => {
+                try {
+                    const restoreSink = onProgress ?? input.onProgress;
+                    // Build the ordered outbound restore task list. Each task runs one
+                    // restore from start to end: the workspace restore, or one asset restore.
+                    // The shared scheduler starts the tasks. When the sync client permits
+                    // concurrency, the scheduler keeps at most SYNC_OPERATION_CONCURRENCY_LIMIT
+                    // tasks active. When the client does not permit concurrency, the scheduler
+                    // runs one task at a time in this order. The scheduler settles every
+                    // started task before it returns, so lease teardown never starts while an
+                    // outbound restore task still writes host data.
+                    const outboundTasks = [];
+                    const outboundDiagnostics = [];
+                    // The workspace restore task runs only when the run syncs the workspace.
+                    // The task exports the sandbox git history (git-backed workspace), reads
+                    // the sandbox workspace back, and merges it into the host workspace root.
+                    // The merge is the only outbound write inside the host workspace root.
+                    // Every other task writes a disjoint host target: an asset restore writes
+                    // its own store outside the workspace root. So the workspace task and the
+                    // asset tasks share one parallel set. Keep any future asset that must write
+                    // inside the host workspace root out of this set, and run it after the
+                    // merge. Each task gets its own restore temp directory, so two concurrent
+                    // tasks never share scratch state.
+                    if (syncWorkspace) {
+                        outboundTasks.push(() => withWorkspaceRestoreDiagnostics("workspace", () => runStepSpan("restore.workspace", async () => {
+                            // Each repository owns its Git history and merge. The parent baseline also
+                            // records child files so restart recovery has their original merge inputs.
+                            for (const repository of repositories) {
+                                const prefix = `${repository.path}/`;
+                                const localDir = path.join(input.workspaceLocalDir, repository.path);
+                                if (await fs.realpath(localDir) !== path.join(await fs.realpath(input.workspaceLocalDir), repository.path)) {
+                                    throw new Error("Project repository escaped its workspace");
+                                }
+                                const nestedExclude = mergeExcludes(baselineSnapshot.exclude.flatMap((entry) => entry.startsWith(prefix) ? [entry.slice(prefix.length)]
+                                    : entry.startsWith("*/") ? [entry] : []));
+                                const nested = await prepareSandboxManagedRuntime({
+                                    spec: { ...input.spec, remoteCwd: path.posix.join(workspaceRemoteDir, repository.path) },
+                                    client: input.client,
+                                    adapterKey: input.adapterKey,
+                                    workspaceLocalDir: localDir,
+                                    workspaceInboundMode: "adopt_remote",
+                                    workspaceGitSnapshot: repository.snapshot,
+                                    workspaceExclude: nestedExclude,
+                                    workspaceBaseline: await selectDirectorySnapshot(baselineSnapshot, {
+                                        prefix,
+                                        exclude: mergeExcludes(SANDBOX_WORKSPACE_HEAVY_DIR_EXCLUDES, [...GIT_ARCHIVE_EXCLUDES], [".paperclip-runtime"], nestedExclude),
+                                        ignoredPaths: repository.snapshot.ignoredPaths,
+                                    }),
+                                    onRuntimeProgress: input.onRuntimeProgress,
+                                });
+                                await nested.restoreWorkspace(restoreSink);
+                            }
+                            await withTempDir("paperclip-sandbox-restore-", async (tempDir) => {
+                                let importedRef = null;
+                                let importedHead = null;
+                                let remoteWorkspaceStatus = "dirty";
+                                try {
+                                    if (gitSnapshot) {
+                                        await emitRuntimeStatus(input.onRuntimeProgress, "export", "Exporting git changes from environment");
+                                        importedRef = createImportedGitRef("sandbox");
+                                        const remoteGitBundle = path.posix.join(runtimeRootDir, "git-delta.bundle");
+                                        const remoteWorkspaceStatusPath = path.posix.join(runtimeRootDir, "workspace-status.txt");
+                                        const exportRef = createRemoteGitExportRef("sandbox");
+                                        const localBundlePath = path.join(tempDir, "git-delta.bundle");
+                                        // Export the sandbox history and import it into the host workspace.
+                                        // The delta bundle assumes the host holds the bundle's boundary
+                                        // commit; when the host has been reset far enough that it does not,
+                                        // the import fails on a missing prerequisite. In that case re-export
+                                        // a full, self-contained bundle from the still-live sandbox rather
+                                        // than discard the completed run.
+                                        const exportAndImport = async (forceFullBundle) => withWorkspaceRestoreStep("git_export", async () => {
+                                            await input.client.run(`sh -c ${shellQuote(buildRemoteGitDeltaBundleScript({
+                                                remoteDir: workspaceRemoteDir,
+                                                baseSha: gitSnapshot.headCommit,
+                                                exportRef,
+                                                bundlePath: remoteGitBundle,
+                                                statusPath: forceFullBundle ? undefined : remoteWorkspaceStatusPath,
+                                                forceFullBundle,
+                                            }))}`, { timeoutMs: input.spec.timeoutMs });
+                                            const gitExport = makeTransferProgress(restoreSink, "Exporting git history", "from", undefined, { sink: input.onRuntimeProgress, phase: "export" });
+                                            if (nativeSyncOut) {
+                                                // Native outbound: the provider copies the bundle straight from
+                                                // the sandbox into the host restore temp directory. This maps to
+                                                // one `kind: "file"` mapping. The host does not buffer the full
+                                                // bundle in RAM and does not move the bytes through the base64
+                                                // read loop. The git import step below reads the bundle from
+                                                // `localBundlePath`. The provider transfer reports its own byte
+                                                // total, so the "Exporting git history" progress still degrades to
+                                                // start-and-finish (mirrors the workspace restore below), but the
+                                                // finish line carries the real transferred byte count.
+                                                const operations = [{
+                                                        operationId: nextSyncOperationId(),
+                                                        files: [{
+                                                                sourcePath: remoteGitBundle,
+                                                                targetPath: localBundlePath,
+                                                                kind: "file",
+                                                            }],
+                                                    }];
+                                                assertSyncOperationsConfined(operations, {
+                                                    sourceRoots: [runtimeRootDir],
+                                                    targetRoots: [tempDir],
+                                                });
+                                                const syncResult = await input.client.syncOut(operations);
+                                                const transferredBytes = sumSyncResultBytes(syncResult);
+                                                await gitExport.finish(transferredBytes, transferredBytes);
+                                            }
+                                            else {
+                                                const bundleBytes = await input.client.readFile(remoteGitBundle, gitExport.options);
+                                                const bundleBuffer = toBuffer(bundleBytes);
+                                                await gitExport.finish(bundleBuffer.byteLength, bundleBuffer.byteLength);
+                                                await fs.writeFile(localBundlePath, bundleBuffer);
+                                            }
+                                            await input.client.remove(remoteGitBundle).catch(() => undefined);
+                                            if (!forceFullBundle) {
+                                                remoteWorkspaceStatus = await input.client.readFile(remoteWorkspaceStatusPath)
+                                                    .then((bytes) => toBuffer(bytes).toString("utf8").trim())
+                                                    .catch(() => "dirty");
+                                                remoteWorkspaceStatus = remoteWorkspaceStatus === "clean" ? "clean" : "dirty";
+                                                await input.client.remove(remoteWorkspaceStatusPath).catch(() => undefined);
+                                            }
+                                            return withWorkspaceRestoreStep("git_import", () => fetchGitBundleIntoLocalRef({
+                                                localDir: input.workspaceLocalDir,
+                                                bundlePath: localBundlePath,
+                                                exportRef,
+                                                importedRef: importedRef,
+                                                baseSha: gitSnapshot.headCommit,
+                                            }));
+                                        });
+                                        try {
+                                            importedHead = await exportAndImport(false);
+                                        }
+                                        catch (error) {
+                                            if (!isMissingGitPrerequisiteError(error))
+                                                throw error;
+                                            importedHead = await exportAndImport(true);
+                                        }
+                                    }
+                                    await emitRuntimeStatus(input.onRuntimeProgress, "restore", "Restoring workspace from environment");
+                                    const extractedDir = path.join(tempDir, "workspace");
                                     if (nativeSyncOut) {
-                                        // Native outbound: the provider copies the bundle straight from
-                                        // the sandbox into the host restore temp directory. This maps to
-                                        // one `kind: "file"` mapping. The host does not buffer the full
-                                        // bundle in RAM and does not move the bytes through the base64
-                                        // read loop. The git import step below reads the bundle from
-                                        // `localBundlePath`. The provider transfer reports its own byte
-                                        // total, so the "Exporting git history" progress still degrades to
-                                        // start-and-finish (mirrors the workspace restore below), but the
+                                        // Native outbound: the provider materializes the sandbox workspace into
+                                        // a fresh host directory. It is a clean destroy-then-replace into a
+                                        // temp dir the orchestrator just created, so it maps exactly to a
+                                        // generic directory file mapping; the host-side baseline merge below is
+                                        // unchanged. The provider transfer reports its own byte total, so the
                                         // finish line carries the real transferred byte count.
                                         const operations = [{
                                                 operationId: nextSyncOperationId(),
                                                 files: [{
-                                                        sourcePath: remoteGitBundle,
-                                                        targetPath: localBundlePath,
-                                                        kind: "file",
+                                                        sourcePath: workspaceRemoteDir,
+                                                        targetPath: extractedDir,
+                                                        kind: "directory",
+                                                        exclude: workspaceRestoreExclude,
                                                     }],
                                             }];
                                         assertSyncOperationsConfined(operations, {
-                                            sourceRoots: [runtimeRootDir],
-                                            targetRoots: [tempDir],
+                                            sourceRoots: [workspaceRemoteDir],
+                                            targetRoots: [extractedDir],
                                         });
-                                        const syncResult = await input.client.syncOut(operations);
+                                        await fs.mkdir(extractedDir, { recursive: true });
+                                        const workspaceRestore = makeTransferProgress(restoreSink, "Restoring", "from", "workspace", { sink: input.onRuntimeProgress, phase: "restore" });
+                                        const syncResult = await withWorkspaceRestoreStep("workspace_transfer", () => input.client.syncOut(operations));
                                         const transferredBytes = sumSyncResultBytes(syncResult);
-                                        await gitExport.finish(transferredBytes, transferredBytes);
+                                        await workspaceRestore.finish(transferredBytes, transferredBytes);
                                     }
                                     else {
-                                        const bundleBytes = await input.client.readFile(remoteGitBundle, gitExport.options);
-                                        const bundleBuffer = toBuffer(bundleBytes);
-                                        await gitExport.finish(bundleBuffer.byteLength, bundleBuffer.byteLength);
-                                        await fs.writeFile(localBundlePath, bundleBuffer);
-                                    }
-                                    await input.client.remove(remoteGitBundle).catch(() => undefined);
-                                    if (!forceFullBundle) {
-                                        remoteWorkspaceStatus = await input.client.readFile(remoteWorkspaceStatusPath)
-                                            .then((bytes) => toBuffer(bytes).toString("utf8").trim())
-                                            .catch(() => "dirty");
-                                        remoteWorkspaceStatus = remoteWorkspaceStatus === "clean" ? "clean" : "dirty";
-                                        await input.client.remove(remoteWorkspaceStatusPath).catch(() => undefined);
-                                    }
-                                    return fetchGitBundleIntoLocalRef({
-                                        localDir: input.workspaceLocalDir,
-                                        bundlePath: localBundlePath,
-                                        exportRef,
-                                        importedRef: importedRef,
-                                        baseSha: gitSnapshot.headCommit,
-                                    });
-                                };
-                                try {
-                                    importedHead = await exportAndImport(false);
-                                }
-                                catch (error) {
-                                    if (!isMissingGitPrerequisiteError(error))
-                                        throw error;
-                                    importedHead = await exportAndImport(true);
-                                }
-                            }
-                            await emitRuntimeStatus(input.onRuntimeProgress, "restore", "Restoring workspace from environment");
-                            const extractedDir = path.join(tempDir, "workspace");
-                            if (nativeSyncOut) {
-                                // Native outbound: the provider materializes the sandbox workspace into
-                                // a fresh host directory. It is a clean destroy-then-replace into a
-                                // temp dir the orchestrator just created, so it maps exactly to a
-                                // generic directory file mapping; the host-side baseline merge below is
-                                // unchanged. The provider transfer reports its own byte total, so the
-                                // finish line carries the real transferred byte count.
-                                const operations = [{
-                                        operationId: nextSyncOperationId(),
-                                        files: [{
-                                                sourcePath: workspaceRemoteDir,
-                                                targetPath: extractedDir,
-                                                kind: "directory",
-                                                exclude: workspaceRestoreExclude,
-                                            }],
-                                    }];
-                                assertSyncOperationsConfined(operations, {
-                                    sourceRoots: [workspaceRemoteDir],
-                                    targetRoots: [extractedDir],
-                                });
-                                await fs.mkdir(extractedDir, { recursive: true });
-                                const workspaceRestore = makeTransferProgress(restoreSink, "Restoring", "from", "workspace", { sink: input.onRuntimeProgress, phase: "restore" });
-                                const syncResult = await input.client.syncOut(operations);
-                                const transferredBytes = sumSyncResultBytes(syncResult);
-                                await workspaceRestore.finish(transferredBytes, transferredBytes);
-                            }
-                            else {
-                                const remoteWorkspaceTar = path.posix.join(runtimeRootDir, "workspace-download.tar");
-                                await input.client.run(`sh -c ${shellQuote(createRemoteTarballFromDirectoryCommand({
-                                    remoteDir: workspaceRemoteDir,
-                                    archivePath: remoteWorkspaceTar,
-                                    exclude: workspaceRestoreExclude,
-                                }))}`, { timeoutMs: input.spec.timeoutMs });
-                                const workspaceRestore = makeTransferProgress(restoreSink, "Restoring", "from", "workspace", { sink: input.onRuntimeProgress, phase: "restore" });
-                                const archiveBytes = await input.client.readFile(remoteWorkspaceTar, workspaceRestore.options);
-                                const archiveBuffer = toBuffer(archiveBytes);
-                                await workspaceRestore.finish(archiveBuffer.byteLength, archiveBuffer.byteLength);
-                                await input.client.remove(remoteWorkspaceTar).catch(() => undefined);
-                                const localArchivePath = path.join(tempDir, "workspace.tar");
-                                await fs.writeFile(localArchivePath, archiveBuffer);
-                                await extractTarballToDirectory({
-                                    archivePath: localArchivePath,
-                                    localDir: extractedDir,
-                                });
-                            }
-                            const gitHeadToIntegrate = importedHead;
-                            await mergeDirectoryWithBaseline({
-                                baseline: repositories.length === 0 ? baselineSnapshot : {
-                                    exclude: workspaceRestoreExclude,
-                                    entries: new Map([...baselineSnapshot.entries].filter(([entry]) => !repositories.some((repo) => entry === repo.path || entry.startsWith(`${repo.path}/`)))),
-                                },
-                                sourceDir: extractedDir,
-                                targetDir: input.workspaceLocalDir,
-                                beforeApply: gitHeadToIntegrate
-                                    ? async () => {
-                                        await integrateImportedGitHead({
-                                            localDir: input.workspaceLocalDir,
-                                            importedHead: gitHeadToIntegrate,
+                                        const remoteWorkspaceTar = path.posix.join(runtimeRootDir, "workspace-download.tar");
+                                        await withWorkspaceRestoreStep("workspace_transfer", () => input.client.run(`sh -c ${shellQuote(createRemoteTarballFromDirectoryCommand({
+                                            remoteDir: workspaceRemoteDir,
+                                            archivePath: remoteWorkspaceTar,
+                                            exclude: workspaceRestoreExclude,
+                                        }))}`, { timeoutMs: input.spec.timeoutMs }));
+                                        const workspaceRestore = makeTransferProgress(restoreSink, "Restoring", "from", "workspace", { sink: input.onRuntimeProgress, phase: "restore" });
+                                        const archiveBytes = await withWorkspaceRestoreStep("workspace_transfer", () => input.client.readFile(remoteWorkspaceTar, workspaceRestore.options));
+                                        const archiveBuffer = toBuffer(archiveBytes);
+                                        await workspaceRestore.finish(archiveBuffer.byteLength, archiveBuffer.byteLength);
+                                        await input.client.remove(remoteWorkspaceTar).catch(() => undefined);
+                                        const localArchivePath = path.join(tempDir, "workspace.tar");
+                                        await withWorkspaceRestoreStep("workspace_extract", async () => {
+                                            await fs.writeFile(localArchivePath, archiveBuffer);
+                                            await extractTarballToDirectory({
+                                                archivePath: localArchivePath,
+                                                localDir: extractedDir,
+                                            });
                                         });
                                     }
-                                    : undefined,
-                                afterApply: gitSnapshot
-                                    ? async () => {
-                                        await resetLocalGitIndexToHead({
-                                            localDir: input.workspaceLocalDir,
-                                            checkWorkingTreeClean: remoteWorkspaceStatus === "clean",
+                                    const gitHeadToIntegrate = importedHead;
+                                    await withWorkspaceRestoreStep("directory_merge", async () => {
+                                        const mergeBaseline = repositories.length === 0 ? baselineSnapshot : await selectDirectorySnapshot(baselineSnapshot, {
+                                            omit: repositories.map((repo) => repo.path), exclude: workspaceRestoreExclude, ignoredPaths: gitSnapshot?.ignoredPaths,
                                         });
+                                        try {
+                                            await mergeDirectoryWithBaseline({
+                                                baseline: mergeBaseline,
+                                                sourceDir: extractedDir,
+                                                targetDir: input.workspaceLocalDir,
+                                                beforeApply: gitHeadToIntegrate
+                                                    ? async () => {
+                                                        await withWorkspaceRestoreStep("git_integration", () => integrateImportedGitHead({
+                                                            localDir: input.workspaceLocalDir,
+                                                            importedHead: gitHeadToIntegrate,
+                                                            baseline: gitSnapshot ?? undefined,
+                                                        }));
+                                                    }
+                                                    : undefined,
+                                                afterApply: gitSnapshot
+                                                    ? async () => {
+                                                        await withWorkspaceRestoreStep("index_reset", () => resetLocalGitIndexToHead({
+                                                            localDir: input.workspaceLocalDir,
+                                                            checkWorkingTreeClean: remoteWorkspaceStatus === "clean",
+                                                        }));
+                                                    }
+                                                    : undefined,
+                                            });
+                                        }
+                                        finally {
+                                            if (mergeBaseline !== baselineSnapshot)
+                                                await disposeDirectorySnapshot(mergeBaseline);
+                                        }
+                                    });
+                                }
+                                finally {
+                                    await emitRuntimeStatus(input.onRuntimeProgress, "finalize", "Finalizing workspace");
+                                    if (importedRef) {
+                                        await withWorkspaceRestoreStep("git_ref_cleanup", () => deleteLocalGitRef({ localDir: input.workspaceLocalDir, ref: importedRef }));
                                     }
-                                    : undefined,
+                                }
                             });
+                        }), restoreSink, (diagnostic) => { outboundDiagnostics[0] = diagnostic; }));
+                    }
+                    // One restore task per asset that has a teardown contribution. Each task
+                    // reads its asset back through `readFile` and writes a disjoint host
+                    // target. Each task gets its own restore temp directory.
+                    for (const asset of input.assets ?? []) {
+                        if (!asset.restore)
+                            continue;
+                        const assetRestore = asset.restore;
+                        const assetKey = asset.key;
+                        const taskIndex = outboundTasks.length;
+                        outboundTasks.push(() => withWorkspaceRestoreDiagnostics("asset", () => runStepSpan(`restore.asset.${assetKey}`, async () => {
+                            await withTempDir("paperclip-sandbox-restore-", async (tempDir) => {
+                                await withWorkspaceRestoreStep("asset_restore", () => assetRestore({
+                                    assetDir: path.posix.join(runtimeRootDir, assetKey),
+                                    readFile: async (remotePath) => toBuffer(await input.client.readFile(remotePath)),
+                                    tempDir,
+                                }));
+                            });
+                        }), restoreSink, (diagnostic) => { outboundDiagnostics[taskIndex] = diagnostic; }));
+                    }
+                    // Run every outbound restore through the shared scheduler. It starts the
+                    // tasks under the client concurrency permission and the bound, and it
+                    // settles every started task before it returns. This is the teardown
+                    // barrier.
+                    const outboundResults = await scheduleSyncOperations(outboundTasks, input.client.allowConcurrentSyncOperations === true, SYNC_OPERATION_CONCURRENCY_LIMIT);
+                    // Every outbound restore is a required operation: a rejection is fatal.
+                    // The workspace comes first, then each asset in order. Raise the first
+                    // rejection in stable task order, so two failures raise the earlier one.
+                    for (const [index, result] of outboundResults.entries()) {
+                        if (result.status === "rejected") {
+                            recordWorkspaceRestoreDiagnostic(result.reason, outboundDiagnostics[index]);
+                            throw result.reason;
                         }
-                        finally {
-                            await emitRuntimeStatus(input.onRuntimeProgress, "finalize", "Finalizing workspace");
-                            if (importedRef) {
-                                await deleteLocalGitRef({ localDir: input.workspaceLocalDir, ref: importedRef });
-                            }
-                        }
-                    });
-                }));
-            }
-            // One restore task per asset that has a teardown contribution. Each task
-            // reads its asset back through `readFile` and writes a disjoint host
-            // target. Each task gets its own restore temp directory.
-            for (const asset of input.assets ?? []) {
-                if (!asset.restore)
-                    continue;
-                const assetRestore = asset.restore;
-                const assetKey = asset.key;
-                outboundTasks.push(() => runStepSpan(`restore.asset.${assetKey}`, async () => {
-                    await withTempDir("paperclip-sandbox-restore-", async (tempDir) => {
-                        await assetRestore({
-                            assetDir: path.posix.join(runtimeRootDir, assetKey),
-                            readFile: async (remotePath) => toBuffer(await input.client.readFile(remotePath)),
-                            tempDir,
-                        });
-                    });
-                }));
-            }
-            // Run every outbound restore through the shared scheduler. It starts the
-            // tasks under the client concurrency permission and the bound, and it
-            // settles every started task before it returns. This is the teardown
-            // barrier.
-            const outboundResults = await scheduleSyncOperations(outboundTasks, input.client.allowConcurrentSyncOperations === true, SYNC_OPERATION_CONCURRENCY_LIMIT);
-            // Every outbound restore is a required operation: a rejection is fatal.
-            // The workspace comes first, then each asset in order. Raise the first
-            // rejection in stable task order, so two failures raise the earlier one.
-            for (const result of outboundResults) {
-                if (result.status === "rejected") {
-                    throw result.reason;
+                    }
                 }
-            }
-        },
-    };
+                finally {
+                    await cleanupWorkspaceSnapshot();
+                }
+            },
+        };
+    }
+    catch (error) {
+        await cleanupWorkspaceSnapshot();
+        throw error;
+    }
 }
 //# sourceMappingURL=sandbox-managed-runtime.js.map