@ai-hero/sandcastle 0.2.3 → 0.3.0

package/dist/sandboxes/docker.js

@@ -0,0 +1,133 @@
+/**
+ * Docker sandbox provider — wraps DockerLifecycle into a SandboxProvider.
+ *
+ * Usage:
+ *   import { docker } from "sandcastle/sandboxes/docker";
+ *   await run({ agent: claudeCode("claude-opus-4-6"), sandbox: docker() });
+ */
+import { execFile, execFileSync, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline";
+import { Effect } from "effect";
+import { startContainer, removeContainer, chownInContainer, } from "../DockerLifecycle.js";
+import { createBindMountSandboxProvider, } from "../SandboxProvider.js";
+/**
+ * Create a Docker sandbox provider.
+ *
+ * The returned provider creates Docker containers with bind-mounts
+ * for the worktree and git directories.
+ */
+export const docker = (options) => {
+    const configuredImageName = options?.imageName;
+    return createBindMountSandboxProvider({
+        name: "docker",
+        create: async (createOptions) => {
+            const containerName = `sandcastle-${randomUUID()}`;
+            const workspacePath = createOptions.mounts.find((m) => m.hostPath === createOptions.worktreePath)?.sandboxPath ?? "/home/agent/workspace";
+            // Build volume mount strings
+            const volumeMounts = createOptions.mounts.map((m) => {
+                const base = `${m.hostPath}:${m.sandboxPath}`;
+                return m.readonly ? `${base}:ro` : base;
+            });
+            // Resolve image name
+            const imageName = configuredImageName ?? defaultImageName(createOptions.hostRepoPath);
+            const hostUid = process.getuid?.() ?? 1000;
+            const hostGid = process.getgid?.() ?? 1000;
+            // Start container
+            await Effect.runPromise(startContainer(containerName, imageName, {
+                ...createOptions.env,
+                HOME: "/home/agent",
+            }, {
+                volumeMounts,
+                workdir: workspacePath,
+                user: `${hostUid}:${hostGid}`,
+            }).pipe(Effect.andThen(chownInContainer(containerName, `${hostUid}:${hostGid}`, "/home/agent"))));
+            // Set up signal handlers for cleanup
+            const onExit = () => {
+                try {
+                    execFileSync("docker", ["rm", "-f", containerName], {
+                        stdio: "ignore",
+                    });
+                }
+                catch {
+                    /* best-effort */
+                }
+            };
+            const onSignal = () => {
+                onExit();
+                process.exit(1);
+            };
+            process.on("exit", onExit);
+            process.on("SIGINT", onSignal);
+            process.on("SIGTERM", onSignal);
+            const handle = {
+                workspacePath,
+                exec: (command, opts) => new Promise((resolve, reject) => {
+                    const args = ["exec"];
+                    if (opts?.cwd)
+                        args.push("-w", opts.cwd);
+                    args.push(containerName, "sh", "-c", command);
+                    execFile("docker", args, { maxBuffer: 10 * 1024 * 1024 }, (error, stdout, stderr) => {
+                        if (error && error.code === undefined) {
+                            reject(new Error(`docker exec failed: ${error.message}`));
+                        }
+                        else {
+                            resolve({
+                                stdout: stdout.toString(),
+                                stderr: stderr.toString(),
+                                exitCode: typeof error?.code === "number" ? error.code : 0,
+                            });
+                        }
+                    });
+                }),
+                execStreaming: (command, onLine, opts) => new Promise((resolve, reject) => {
+                    const args = ["exec"];
+                    if (opts?.cwd)
+                        args.push("-w", opts.cwd);
+                    args.push(containerName, "sh", "-c", command);
+                    const proc = spawn("docker", args, {
+                        stdio: ["ignore", "pipe", "pipe"],
+                    });
+                    const stdoutChunks = [];
+                    const stderrChunks = [];
+                    const rl = createInterface({ input: proc.stdout });
+                    rl.on("line", (line) => {
+                        stdoutChunks.push(line);
+                        onLine(line);
+                    });
+                    proc.stderr.on("data", (chunk) => {
+                        stderrChunks.push(chunk.toString());
+                    });
+                    proc.on("error", (error) => {
+                        reject(new Error(`docker exec streaming failed: ${error.message}`));
+                    });
+                    proc.on("close", (code) => {
+                        resolve({
+                            stdout: stdoutChunks.join("\n"),
+                            stderr: stderrChunks.join(""),
+                            exitCode: code ?? 0,
+                        });
+                    });
+                }),
+                close: async () => {
+                    process.removeListener("exit", onExit);
+                    process.removeListener("SIGINT", onSignal);
+                    process.removeListener("SIGTERM", onSignal);
+                    await Effect.runPromise(removeContainer(containerName));
+                },
+            };
+            return handle;
+        },
+    });
+};
+/**
+ * Derive the default Docker image name from the repo directory.
+ * Returns `sandcastle:<dir-name>` where dir-name is the last path segment,
+ * lowercased and sanitized for Docker image tag rules.
+ */
+export const defaultImageName = (repoDir) => {
+    const dirName = repoDir.replace(/\/+$/, "").split("/").pop() ?? "local";
+    const sanitized = dirName.toLowerCase().replace(/[^a-z0-9_.-]/g, "-");
+    return `sandcastle:${sanitized}`;
+};
+//# sourceMappingURL=docker.js.map

package/dist/sandboxes/docker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker.js","sourceRoot":"","sources":["../../src/sandboxes/docker.ts"],"names":[],"mappings":"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"}

package/dist/sandboxes/test-isolated.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Filesystem-based test isolated sandbox provider.
+ *
+ * Uses a temp directory on the local filesystem as the "sandbox".
+ * Intended for testing the isolated provider abstraction without
+ * requiring a real remote environment.
+ */
+import { type IsolatedSandboxProvider } from "../SandboxProvider.js";
+/**
+ * Create a filesystem-based test isolated sandbox provider.
+ *
+ * The "sandbox" is a temp directory. `exec` runs shell commands in it,
+ * `copyIn`/`copyOut` copy files between host and the temp dir,
+ * and `close` removes the temp dir.
+ */
+export declare const testIsolated: () => IsolatedSandboxProvider;
+//# sourceMappingURL=test-isolated.d.ts.map

package/dist/sandboxes/test-isolated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-isolated.d.ts","sourceRoot":"","sources":["../../src/sandboxes/test-isolated.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,EAIL,KAAK,uBAAuB,EAC7B,MAAM,uBAAuB,CAAC;AAE/B;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,+BA+FrB,CAAC"}

package/dist/sandboxes/test-isolated.js

@@ -0,0 +1,86 @@
+/**
+ * Filesystem-based test isolated sandbox provider.
+ *
+ * Uses a temp directory on the local filesystem as the "sandbox".
+ * Intended for testing the isolated provider abstraction without
+ * requiring a real remote environment.
+ */
+import { execFile, spawn } from "node:child_process";
+import { copyFile, mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline";
+import { createIsolatedSandboxProvider, } from "../SandboxProvider.js";
+/**
+ * Create a filesystem-based test isolated sandbox provider.
+ *
+ * The "sandbox" is a temp directory. `exec` runs shell commands in it,
+ * `copyIn`/`copyOut` copy files between host and the temp dir,
+ * and `close` removes the temp dir.
+ */
+export const testIsolated = () => createIsolatedSandboxProvider({
+    name: "test-isolated",
+    create: async () => {
+        const sandboxRoot = await mkdtemp(join(tmpdir(), "sandcastle-test-"));
+        const workspacePath = join(sandboxRoot, "workspace");
+        await mkdir(workspacePath, { recursive: true });
+        return {
+            workspacePath,
+            exec: (command, options) => new Promise((resolve, reject) => {
+                execFile("sh", ["-c", command], {
+                    cwd: options?.cwd ?? workspacePath,
+                    maxBuffer: 10 * 1024 * 1024,
+                }, (error, stdout, stderr) => {
+                    if (error && error.code === undefined) {
+                        reject(new Error(`exec failed: ${error.message}`));
+                    }
+                    else {
+                        resolve({
+                            stdout: stdout.toString(),
+                            stderr: stderr.toString(),
+                            exitCode: typeof error?.code === "number" ? error.code : 0,
+                        });
+                    }
+                });
+            }),
+            execStreaming: (command, onLine, options) => new Promise((resolve, reject) => {
+                const proc = spawn("sh", ["-c", command], {
+                    cwd: options?.cwd ?? workspacePath,
+                    stdio: ["ignore", "pipe", "pipe"],
+                });
+                const stdoutChunks = [];
+                const stderrChunks = [];
+                const rl = createInterface({ input: proc.stdout });
+                rl.on("line", (line) => {
+                    stdoutChunks.push(line);
+                    onLine(line);
+                });
+                proc.stderr.on("data", (chunk) => {
+                    stderrChunks.push(chunk.toString());
+                });
+                proc.on("error", (error) => {
+                    reject(new Error(`exec streaming failed: ${error.message}`));
+                });
+                proc.on("close", (code) => {
+                    resolve({
+                        stdout: stdoutChunks.join("\n"),
+                        stderr: stderrChunks.join(""),
+                        exitCode: code ?? 0,
+                    });
+                });
+            }),
+            copyIn: async (hostPath, sandboxPath) => {
+                await mkdir(dirname(sandboxPath), { recursive: true });
+                await copyFile(hostPath, sandboxPath);
+            },
+            copyOut: async (sandboxPath, hostPath) => {
+                await mkdir(dirname(hostPath), { recursive: true });
+                await copyFile(sandboxPath, hostPath);
+            },
+            close: async () => {
+                await rm(sandboxRoot, { recursive: true, force: true });
+            },
+        };
+    },
+});
+//# sourceMappingURL=test-isolated.js.map

package/dist/sandboxes/test-isolated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-isolated.js","sourceRoot":"","sources":["../../src/sandboxes/test-isolated.ts"],"names":[],"mappings":"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"}

package/dist/syncIn.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Sync-in: transfer a host git repo into an isolated sandbox via git bundle.
+ *
+ * Creates a git bundle capturing all refs from the host repo,
+ * copies it into the sandbox via the provider's copyIn, and
+ * clones from the bundle inside the sandbox.
+ */
+import type { IsolatedSandboxHandle } from "./SandboxProvider.js";
+/**
+ * Sync a host git repo into an isolated sandbox.
+ *
+ * 1. `git bundle create --all` on the host
+ * 2. `copyIn` the bundle to the sandbox
+ * 3. `git clone` from the bundle inside the sandbox
+ * 4. Verify HEAD matches
+ *
+ * @returns The branch name that was checked out
+ */
+export declare const syncIn: (hostRepoDir: string, handle: IsolatedSandboxHandle) => Promise<{
+    branch: string;
+}>;
+//# sourceMappingURL=syncIn.d.ts.map

package/dist/syncIn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncIn.d.ts","sourceRoot":"","sources":["../src/syncIn.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAGlE;;;;;;;;;GASG;AACH,eAAO,MAAM,MAAM;;EA0DlB,CAAC"}

package/dist/syncIn.js

@@ -0,0 +1,57 @@
+/**
+ * Sync-in: transfer a host git repo into an isolated sandbox via git bundle.
+ *
+ * Creates a git bundle capturing all refs from the host repo,
+ * copies it into the sandbox via the provider's copyIn, and
+ * clones from the bundle inside the sandbox.
+ */
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execHost, execOk } from "./sandboxExec.js";
+/**
+ * Sync a host git repo into an isolated sandbox.
+ *
+ * 1. `git bundle create --all` on the host
+ * 2. `copyIn` the bundle to the sandbox
+ * 3. `git clone` from the bundle inside the sandbox
+ * 4. Verify HEAD matches
+ *
+ * @returns The branch name that was checked out
+ */
+export const syncIn = async (hostRepoDir, handle) => {
+    // Get current branch from host
+    const branch = (await execHost("git rev-parse --abbrev-ref HEAD", hostRepoDir)).trim();
+    // Create git bundle on host capturing all refs
+    const bundleDir = await mkdtemp(join(tmpdir(), "sandcastle-bundle-"));
+    const bundleHostPath = join(bundleDir, "repo.bundle");
+    try {
+        await execHost(`git bundle create "${bundleHostPath}" --all`, hostRepoDir);
+        // Create temp dir in sandbox and copy bundle in
+        const mkTempResult = await execOk(handle, "mktemp -d -t sandcastle-XXXXXX");
+        const sandboxTmpDir = mkTempResult.stdout.trim();
+        const bundleSandboxPath = `${sandboxTmpDir}/repo.bundle`;
+        await handle.copyIn(bundleHostPath, bundleSandboxPath);
+        // Clone from bundle into the workspace
+        const workspacePath = handle.workspacePath;
+        await execOk(handle, `git clone "${bundleSandboxPath}" "${workspacePath}_clone"`);
+        // Move contents from clone into workspace (git clone requires empty target)
+        await execOk(handle, `rm -rf "${workspacePath}" && mv "${workspacePath}_clone" "${workspacePath}"`);
+        // Checkout the correct branch
+        await execOk(handle, `git checkout "${branch}"`, { cwd: workspacePath });
+        // Clean up sandbox temp files
+        await handle.exec(`rm -rf "${sandboxTmpDir}"`);
+        // Verify sync succeeded
+        const hostHead = (await execHost("git rev-parse HEAD", hostRepoDir)).trim();
+        const sandboxHead = (await execOk(handle, "git rev-parse HEAD", { cwd: workspacePath })).stdout.trim();
+        if (hostHead !== sandboxHead) {
+            throw new Error(`HEAD mismatch after sync-in: host=${hostHead} sandbox=${sandboxHead}`);
+        }
+        return { branch };
+    }
+    finally {
+        // Clean up host-side bundle temp dir
+        await rm(bundleDir, { recursive: true, force: true });
+    }
+};
+//# sourceMappingURL=syncIn.js.map

package/dist/syncIn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncIn.js","sourceRoot":"","sources":["../src/syncIn.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,KAAK,EACzB,WAAmB,EACnB,MAA6B,EACA,EAAE;IAC/B,+BAA+B;IAC/B,MAAM,MAAM,GAAG,CACb,MAAM,QAAQ,CAAC,iCAAiC,EAAE,WAAW,CAAC,CAC/D,CAAC,IAAI,EAAE,CAAC;IAET,+CAA+C;IAC/C,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,oBAAoB,CAAC,CAAC,CAAC;IACtE,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IACtD,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,sBAAsB,cAAc,SAAS,EAAE,WAAW,CAAC,CAAC;QAE3E,gDAAgD;QAChD,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,gCAAgC,CAAC,CAAC;QAC5E,MAAM,aAAa,GAAG,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACjD,MAAM,iBAAiB,GAAG,GAAG,aAAa,cAAc,CAAC;QAEzD,MAAM,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAAC;QAEvD,uCAAuC;QACvC,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC;QAC3C,MAAM,MAAM,CACV,MAAM,EACN,cAAc,iBAAiB,MAAM,aAAa,SAAS,CAC5D,CAAC;QAEF,4EAA4E;QAC5E,MAAM,MAAM,CACV,MAAM,EACN,WAAW,aAAa,YAAY,aAAa,YAAY,aAAa,GAAG,CAC9E,CAAC;QAEF,8BAA8B;QAC9B,MAAM,MAAM,CAAC,MAAM,EAAE,iBAAiB,MAAM,GAAG,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,CAAC;QAEzE,8BAA8B;QAC9B,MAAM,MAAM,CAAC,IAAI,CAAC,WAAW,aAAa,GAAG,CAAC,CAAC;QAE/C,wBAAwB;QACxB,MAAM,QAAQ,GAAG,CAAC,MAAM,QAAQ,CAAC,oBAAoB,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC5E,MAAM,WAAW,GAAG,CAClB,MAAM,MAAM,CAAC,MAAM,EAAE,oBAAoB,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,CACnE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAEhB,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACb,qCAAqC,QAAQ,YAAY,WAAW,EAAE,CACvE,CAAC;QACJ,CAAC;QAED,OAAO,EAAE,MAAM,EAAE,CAAC;IACpB,CAAC;YAAS,CAAC;QACT,qCAAqC;QACrC,MAAM,EAAE,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,CAAC;AACH,CAAC,CAAC"}

package/dist/syncOut.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Sync-out: extract changes from an isolated sandbox back to the host.
+ *
+ * Two-phase approach:
+ * 1. Save phase: eagerly save all artifacts (patches, diff, untracked files)
+ *    to `.sandcastle/patches/<timestamp>/` before attempting to apply.
+ * 2. Apply phase: apply from the saved directory.
+ *    - On success: clean up the patch directory.
+ *    - On failure: preserve the patch directory and print recovery commands.
+ *
+ * Three-prong extraction within each phase:
+ * 1. Committed changes: `git format-patch` + `git am --3way`
+ * 2. Uncommitted changes (staged + unstaged): `git diff HEAD` + `git apply`
+ * 3. Untracked files: `git ls-files --others` + `copyOut` each file
+ */
+import type { IsolatedSandboxHandle } from "./SandboxProvider.js";
+/**
+ * Sync changes from an isolated sandbox back to the host repo.
+ *
+ * Two-phase extraction with artifact persistence:
+ * 1. Save all artifacts to `.sandcastle/patches/<timestamp>/`
+ * 2. Apply from saved directory; on failure, preserve artifacts and print recovery
+ */
+export declare const syncOut: (hostRepoDir: string, handle: IsolatedSandboxHandle) => Promise<void>;
+//# sourceMappingURL=syncOut.d.ts.map

package/dist/syncOut.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncOut.d.ts","sourceRoot":"","sources":["../src/syncOut.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAYH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAyClE;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,uEAkKnB,CAAC"}

package/dist/syncOut.js

@@ -0,0 +1,192 @@
+/**
+ * Sync-out: extract changes from an isolated sandbox back to the host.
+ *
+ * Two-phase approach:
+ * 1. Save phase: eagerly save all artifacts (patches, diff, untracked files)
+ *    to `.sandcastle/patches/<timestamp>/` before attempting to apply.
+ * 2. Apply phase: apply from the saved directory.
+ *    - On success: clean up the patch directory.
+ *    - On failure: preserve the patch directory and print recovery commands.
+ *
+ * Three-prong extraction within each phase:
+ * 1. Committed changes: `git format-patch` + `git am --3way`
+ * 2. Uncommitted changes (staged + unstaged): `git diff HEAD` + `git apply`
+ * 3. Untracked files: `git ls-files --others` + `copyOut` each file
+ */
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, rm, stat, writeFile, } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { buildRecoveryMessage } from "./RecoveryMessage.js";
+import { execHost, execOk } from "./sandboxExec.js";
+/**
+ * Check if a patch file is empty or header-only.
+ * Merge commits produce patches with headers but no diff content.
+ * A patch is considered empty if it has no lines starting with "diff --git".
+ */
+const isEmptyPatch = async (patchPath) => {
+    const info = await stat(patchPath);
+    if (info.size === 0)
+        return true;
+    const content = await readFile(patchPath, "utf-8");
+    return !content.includes("diff --git");
+};
+/**
+ * Generate a YYYYMMDD-HHMMSS timestamp directory name.
+ * Appends a counter suffix (-1, -2, ...) if the directory already exists.
+ */
+const createPatchDir = async (hostRepoDir) => {
+    const now = new Date();
+    const pad = (n) => String(n).padStart(2, "0");
+    const base = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+    const patchesRoot = join(hostRepoDir, ".sandcastle", "patches");
+    await mkdir(patchesRoot, { recursive: true });
+    let dirName = base;
+    let counter = 0;
+    while (existsSync(join(patchesRoot, dirName))) {
+        counter++;
+        dirName = `${base}-${counter}`;
+    }
+    const patchDir = join(patchesRoot, dirName);
+    await mkdir(patchDir, { recursive: true });
+    return patchDir;
+};
+/**
+ * Sync changes from an isolated sandbox back to the host repo.
+ *
+ * Two-phase extraction with artifact persistence:
+ * 1. Save all artifacts to `.sandcastle/patches/<timestamp>/`
+ * 2. Apply from saved directory; on failure, preserve artifacts and print recovery
+ */
+export const syncOut = async (hostRepoDir, handle) => {
+    const workspacePath = handle.workspacePath;
+    const hostHead = (await execHost("git rev-parse HEAD", hostRepoDir)).trim();
+    const sandboxHead = (await execOk(handle, "git rev-parse HEAD", { cwd: workspacePath })).stdout.trim();
+    const hasCommits = hostHead !== sandboxHead;
+    // Check for uncommitted changes
+    const diffResult = await handle.exec("git diff HEAD", { cwd: workspacePath });
+    const hasDiff = diffResult.exitCode === 0 && diffResult.stdout.trim().length > 0;
+    // Check for untracked files
+    const lsFilesResult = await handle.exec("git ls-files --others --exclude-standard", { cwd: workspacePath });
+    const hasUntracked = lsFilesResult.exitCode === 0 && lsFilesResult.stdout.trim().length > 0;
+    const untrackedFiles = hasUntracked
+        ? lsFilesResult.stdout
+            .trim()
+            .split("\n")
+            .filter((f) => f.length > 0)
+        : [];
+    // Nothing to sync
+    if (!hasCommits && !hasDiff && !hasUntracked) {
+        return;
+    }
+    // --- Phase 1: Save all artifacts ---
+    const patchDir = await createPatchDir(hostRepoDir);
+    const relativePatchDir = join(".sandcastle", "patches", basename(patchDir));
+    const nonEmptyPatches = [];
+    // Save committed patches
+    if (hasCommits) {
+        const mkTempResult = await execOk(handle, "mktemp -d -t sandcastle-patches-XXXXXX");
+        const sandboxPatchDir = mkTempResult.stdout.trim();
+        try {
+            await execOk(handle, `git format-patch "${hostHead}..HEAD" -o "${sandboxPatchDir}"`, { cwd: workspacePath });
+            const lsResult = await execOk(handle, `ls -1 "${sandboxPatchDir}"`);
+            const patchNames = lsResult.stdout
+                .trim()
+                .split("\n")
+                .filter((name) => name.length > 0);
+            for (const patchName of patchNames) {
+                const sandboxPatchPath = `${sandboxPatchDir}/${patchName}`;
+                const hostPatchPath = join(patchDir, patchName);
+                await handle.copyOut(sandboxPatchPath, hostPatchPath);
+                if (!(await isEmptyPatch(hostPatchPath))) {
+                    nonEmptyPatches.push(hostPatchPath);
+                }
+            }
+        }
+        finally {
+            await handle.exec(`rm -rf "${sandboxPatchDir}"`);
+        }
+    }
+    // Save uncommitted diff
+    if (hasDiff) {
+        const diffPath = join(patchDir, "changes.patch");
+        await writeFile(diffPath, diffResult.stdout);
+    }
+    // Save untracked files
+    if (hasUntracked) {
+        const untrackedDir = join(patchDir, "untracked");
+        for (const relPath of untrackedFiles) {
+            const sandboxFilePath = `${workspacePath}/${relPath}`;
+            const hostFilePath = join(untrackedDir, relPath);
+            await mkdir(dirname(hostFilePath), { recursive: true });
+            await handle.copyOut(sandboxFilePath, hostFilePath);
+        }
+    }
+    // --- Phase 2: Apply from saved directory ---
+    let failedStep;
+    // Apply committed patches
+    if (nonEmptyPatches.length > 0) {
+        try {
+            await execHost("git am --abort", hostRepoDir).catch(() => { });
+            const patchArgs = nonEmptyPatches.map((p) => `"${p}"`).join(" ");
+            await execHost(`git am --3way ${patchArgs}`, hostRepoDir);
+        }
+        catch {
+            failedStep = "commits";
+        }
+    }
+    // Apply uncommitted diff
+    if (!failedStep && hasDiff) {
+        const diffPath = join(patchDir, "changes.patch");
+        try {
+            await execHost(`git apply "${diffPath}"`, hostRepoDir);
+        }
+        catch {
+            failedStep = "diff";
+        }
+    }
+    // Copy untracked files
+    if (!failedStep && hasUntracked) {
+        try {
+            const untrackedDir = join(patchDir, "untracked");
+            for (const relPath of untrackedFiles) {
+                const srcPath = join(untrackedDir, relPath);
+                const destPath = join(hostRepoDir, relPath);
+                await mkdir(dirname(destPath), { recursive: true });
+                const content = await readFile(srcPath);
+                await writeFile(destPath, content);
+            }
+        }
+        catch {
+            failedStep = "untracked";
+        }
+    }
+    // --- Cleanup or preserve ---
+    if (failedStep) {
+        const msg = buildRecoveryMessage({
+            patchDir: relativePatchDir,
+            failedStep,
+            hasCommits: nonEmptyPatches.length > 0,
+            hasDiff,
+            hasUntracked,
+        });
+        console.error(`\n${msg}`);
+    }
+    else {
+        await rm(patchDir, { recursive: true, force: true });
+        // Clean up empty parent dirs
+        const patchesRoot = join(hostRepoDir, ".sandcastle", "patches");
+        try {
+            const remaining = await readdir(patchesRoot);
+            if (remaining.length === 0) {
+                await rm(join(hostRepoDir, ".sandcastle"), {
+                    recursive: true,
+                    force: true,
+                });
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+};
+//# sourceMappingURL=syncOut.js.map

package/dist/syncOut.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncOut.js","sourceRoot":"","sources":["../src/syncOut.ts"],"names":[],"mappings":"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"}

package/dist/templates/blank/main.mts

@@ -1,4 +1,5 @@
 import { run, claudeCode } from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 // Blank template: customize this to build your own orchestration.
 // Run this with: npx tsx .sandcastle/main.mts
@@ -6,5 +7,6 @@ import { run, claudeCode } from "@ai-hero/sandcastle";
 
 await run({
   agent: claudeCode("claude-opus-4-6"),
+  sandbox: docker(),
   promptFile: "./.sandcastle/prompt.md",
 });

package/dist/templates/parallel-planner/main.mts

@@ -17,6 +17,7 @@
 //   "scripts": { "sandcastle": "npx tsx .sandcastle/main.mts" }
 
 import * as sandcastle from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 // ---------------------------------------------------------------------------
 // Configuration
@@ -56,6 +57,7 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
   const plan = await sandcastle.run({
     hooks,
     copyToSandbox,
+    sandbox: docker(),
     name: "planner",
     // One iteration is enough: the planner just needs to read and reason,
     // not write code.
@@ -105,6 +107,7 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
       sandcastle.run({
         hooks,
         copyToSandbox,
+        sandbox: docker(),
         name: "implementer",
         // Give each agent plenty of room to implement and iterate on tests.
         maxIterations: 100,
@@ -179,6 +182,7 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
   await sandcastle.run({
     hooks,
     copyToSandbox,
+    sandbox: docker(),
     name: "merger",
     maxIterations: 10,
     // Sonnet is sufficient for merge conflict resolution.

package/dist/templates/sequential-reviewer/main.mts

@@ -17,6 +17,7 @@
 //   "scripts": { "sandcastle": "npx tsx .sandcastle/main.mts" }
 
 import * as sandcastle from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 // ---------------------------------------------------------------------------
 // Configuration
@@ -57,6 +58,7 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
   const implement = await sandcastle.run({
     hooks,
     copyToSandbox,
+    sandbox: docker(),
     name: "implementer",
     maxIterations: 100,
     agent: sandcastle.claudeCode("claude-sonnet-4-6"),
@@ -84,6 +86,7 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
   await sandcastle.run({
     hooks,
     copyToSandbox,
+    sandbox: docker(),
     name: "reviewer",
     maxIterations: 10,
     agent: sandcastle.claudeCode("claude-sonnet-4-6"),