@ai-hero/sandcastle 0.2.4 → 0.3.0

package/README.md

@@ -50,9 +50,11 @@ npx tsx .sandcastle/main.ts
 ```typescript
 // 3. Run the agent via the JS API
 import { run, claudeCode } from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 await run({
   agent: claudeCode("claude-opus-4-6"),
+  sandbox: docker(),
   promptFile: ".sandcastle/prompt.md",
 });
 ```
@@ -63,9 +65,11 @@ Sandcastle exports a programmatic `run()` function for use in scripts, CI pipeli
 
 ```typescript
 import { run, claudeCode } from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 const result = await run({
   agent: claudeCode("claude-opus-4-6"),
+  sandbox: docker(),
   promptFile: ".sandcastle/prompt.md",
 });
 
@@ -78,12 +82,17 @@ console.log(result.branch); // target branch name
 
 ```typescript
 import { run, claudeCode } from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 const result = await run({
   // Agent provider — required. Pass a model string to claudeCode().
   // Optional second arg for provider-specific options like effort level.
   agent: claudeCode("claude-opus-4-6", { effort: "high" }),
 
+  // Sandbox provider — required. Import from "@ai-hero/sandcastle/sandboxes/docker".
+  // Provider-specific config (like imageName) lives inside the provider factory call.
+  sandbox: docker({ imageName: "sandcastle:local" }),
+
   // Prompt source — provide one of these, not both:
   promptFile: ".sandcastle/prompt.md", // path to a prompt file
   // prompt: "Fix issue #42 in this repo", // OR an inline prompt string
@@ -102,9 +111,6 @@ const result = await run({
   // { mode: 'branch', branch } — create a worktree on an explicit branch.
   worktree: { mode: "branch", branch: "agent/fix-42" },
 
-  // Docker image used for the sandbox. Default: "sandcastle:<repo-dir-name>"
-  imageName: "sandcastle:local",
-
   // Display name for this run, shown as a prefix in log output.
   name: "fix-issue-42",
 
@@ -145,9 +151,11 @@ Use `run()` instead when you only need a single one-shot invocation — it handl
 
 ```typescript
 import { createSandbox, claudeCode } from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 await using sandbox = await createSandbox({
   branch: "agent/fix-42",
+  sandbox: docker(),
 });
 
 const result = await sandbox.run({
@@ -162,9 +170,11 @@ console.log(result.commits); // [{ sha: "abc123" }]
 
 ```typescript
 import { createSandbox, claudeCode } from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 await using sandbox = await createSandbox({
   branch: "agent/fix-42",
+  sandbox: docker(),
   hooks: { onSandboxReady: [{ command: "npm install" }] },
 });
 
@@ -191,7 +201,10 @@ Commits from all `run()` calls accumulate on the same branch. The sandbox contai
 #### Manual `close()` with `CloseResult`
 
 ```typescript
-const sandbox = await createSandbox({ branch: "agent/fix-42" });
+const sandbox = await createSandbox({
+  branch: "agent/fix-42",
+  sandbox: docker(),
+});
 // ... run agents ...
 const closeResult = await sandbox.close();
 if (closeResult.preservedWorktreePath) {
@@ -201,12 +214,12 @@ if (closeResult.preservedWorktreePath) {
 
 #### `CreateSandboxOptions`
 
-| Option          | Type     | Default                      | Description                                                         |
-| --------------- | -------- | ---------------------------- | ------------------------------------------------------------------- |
-| `branch`        | string   | —                            | **Required.** Explicit branch for the worktree                      |
-| `imageName`     | string   | `sandcastle:<repo-dir-name>` | Docker image name                                                   |
-| `hooks`         | object   | —                            | Lifecycle hooks (`onSandboxReady`) — run once at creation time      |
-| `copyToSandbox` | string[] | —                            | Host-relative file paths to copy into the worktree at creation time |
+| Option          | Type            | Default | Description                                                         |
+| --------------- | --------------- | ------- | ------------------------------------------------------------------- |
+| `branch`        | string          | —       | **Required.** Explicit branch for the worktree                      |
+| `sandbox`       | SandboxProvider | —       | **Required.** Sandbox provider (e.g. `docker()`)                    |
+| `hooks`         | object          | —       | Lifecycle hooks (`onSandboxReady`) — run once at creation time      |
+| `copyToSandbox` | string[]        | —       | Host-relative file paths to copy into the worktree at creation time |
 
 #### `Sandbox`
 
@@ -397,7 +410,7 @@ Creates the following files:
 
 Errors if `.sandcastle/` already exists to prevent overwriting customizations.
 
-### `sandcastle build-image`
+### `sandcastle docker build-image`
 
 Rebuilds the Docker image from an existing `.sandcastle/` directory. Use this after modifying the Dockerfile.
 
@@ -406,7 +419,7 @@ Rebuilds the Docker image from an existing `.sandcastle/` directory. Use this af
 | `--image-name` | No       | `sandcastle:<repo-dir-name>` | Docker image name                                                                 |
 | `--dockerfile` | No       | —                            | Path to a custom Dockerfile (build context will be the current working directory) |
 
-### `sandcastle remove-image`
+### `sandcastle docker remove-image`
 
 Removes the Docker image.
 
@@ -419,12 +432,12 @@ Removes the Docker image.
 | Option               | Type               | Default                       | Description                                                                                                             |
 | -------------------- | ------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
 | `agent`              | AgentProvider      | —                             | **Required.** Agent provider (e.g. `claudeCode("claude-opus-4-6")`, `pi("claude-sonnet-4-6")`, `codex("gpt-5.4-mini")`) |
+| `sandbox`            | SandboxProvider    | —                             | **Required.** Sandbox provider (e.g. `docker()`, `docker({ imageName: "sandcastle:local" })`)                           |
 | `prompt`             | string             | —                             | Inline prompt (mutually exclusive with `promptFile`)                                                                    |
 | `promptFile`         | string             | —                             | Path to prompt file (mutually exclusive with `prompt`)                                                                  |
 | `maxIterations`      | number             | `1`                           | Maximum iterations to run                                                                                               |
 | `hooks`              | object             | —                             | Lifecycle hooks (`onSandboxReady`)                                                                                      |
 | `worktree`           | WorktreeMode       | `{ mode: 'temp-branch' }`     | Worktree mode: `{ mode: 'none' }`, `{ mode: 'temp-branch' }`, or `{ mode: 'branch', branch }`                           |
-| `imageName`          | string             | `sandcastle:<repo-dir-name>`  | Docker image name for the sandbox                                                                                       |
 | `name`               | string             | —                             | Display name for the run, shown as a prefix in log output                                                               |
 | `promptArgs`         | PromptArgs         | —                             | Key-value map for `{{KEY}}` placeholder substitution                                                                    |
 | `copyToSandbox`      | string[]           | —                             | Host-relative file paths to copy into the worktree before start (not supported with `mode: 'none'`)                     |

package/dist/SandboxFactory.d.ts

@@ -3,6 +3,7 @@ import { FileSystem } from "@effect/platform";
 import type { PlatformError } from "@effect/platform/Error";
 import { CopyError, ExecError, WorktreeError, type DockerError } from "./errors.js";
 import { Display } from "./Display.js";
+import type { SandboxProvider, BindMountSandboxHandle, IsolatedSandboxHandle } from "./SandboxProvider.js";
 export interface ExecResult {
     readonly stdout: string;
     readonly stderr: string;
@@ -21,7 +22,12 @@ export interface SandboxService {
 declare const Sandbox_base: Context.TagClass<Sandbox, "Sandbox", SandboxService>;
 export declare class Sandbox extends Sandbox_base {
 }
-export declare const makeDockerSandboxLayer: (containerName: string) => Layer.Layer<Sandbox, never, never>;
+/**
+ * Wrap a Promise-based sandbox handle into an Effect-based SandboxService layer.
+ * Works with both bind-mount handles (copyIn/copyOut unsupported) and
+ * isolated handles (copyIn/copyOut delegated to the handle).
+ */
+export declare const makeSandboxLayerFromHandle: (handle: BindMountSandboxHandle | IsolatedSandboxHandle) => Layer.Layer<Sandbox, never, never>;
 /** The mount point inside the container where the project worktree is bound. */
 export declare const SANDBOX_WORKSPACE_DIR = "/home/agent/workspace";
 export interface SandboxInfo {
@@ -39,7 +45,6 @@ declare const SandboxFactory_base: Context.TagClass<SandboxFactory, "SandboxFact
 export declare class SandboxFactory extends SandboxFactory_base {
 }
 declare const WorktreeSandboxConfig_base: Context.TagClass<WorktreeSandboxConfig, "WorktreeSandboxConfig", {
-    readonly imageName: string;
     readonly env: Record<string, string>;
     readonly hostRepoDir: string;
     /** Worktree mode: none, temp-branch (default), or explicit branch. */
@@ -48,15 +53,21 @@ declare const WorktreeSandboxConfig_base: Context.TagClass<WorktreeSandboxConfig
     readonly copyToSandbox?: string[] | undefined;
     /** When specified, the run name is included in the auto-generated branch and worktree names. */
     readonly name?: string | undefined;
+    /** Sandbox provider — delegates container lifecycle to the provider. */
+    readonly sandboxProvider: SandboxProvider;
 }>;
 export declare class WorktreeSandboxConfig extends WorktreeSandboxConfig_base {
 }
+export interface MountEntry {
+    readonly hostPath: string;
+    readonly sandboxPath: string;
+}
 /**
- * Resolves the git-related volume mounts needed for the Docker container.
+ * Resolves the git-related mounts needed for the sandbox.
  * Handles both normal repos (where .git is a directory) and worktrees
  * (where .git is a file pointing to the parent repo's .git/worktrees/<name>).
  */
-export declare const resolveGitVolumeMounts: (gitPath: string) => Effect.Effect<string[], PlatformError, FileSystem.FileSystem>;
+export declare const resolveGitMounts: (gitPath: string) => Effect.Effect<MountEntry[], PlatformError, FileSystem.FileSystem>;
 export declare const WorktreeDockerSandboxFactory: {
     layer: Layer.Layer<SandboxFactory, never, Display | FileSystem.FileSystem | WorktreeSandboxConfig>;
 };

package/dist/SandboxFactory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SandboxFactory.d.ts","sourceRoot":"","sources":["../src/SandboxFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAQ,KAAK,EAAE,MAAM,QAAQ,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAK9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAO5D,OAAO,EAEL,SAAS,EACT,SAAS,EAET,aAAa,EACb,KAAK,WAAW,EACjB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,CACb,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,KACvB,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IAE1C,QAAQ,CAAC,aAAa,EAAE,CACtB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EACpC,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,KACvB,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IAE1C,QAAQ,CAAC,MAAM,EAAE,CACf,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,KAChB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAEpC,QAAQ,CAAC,OAAO,EAAE,CAChB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,KACb,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;CACrC;;AAED,qBAAa,OAAQ,SAAQ,YAG1B;CAAG;AA2KN,eAAO,MAAM,sBAAsB,+DAKhC,CAAC;AAEJ,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,6GAA6G;IAC7G,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;CACzC;;2BAK0B,CAAC,EAAE,CAAC,EAAE,CAAC;;AAHlC,qBAAa,cAAe,SAAQ,mBAWjC;CAAG;;;;;IAoBF,sEAAsE;;IAEtE,6FAA6F;;IAE7F,gGAAgG;;;AAVpG,qBAAa,qBAAsB,SAAQ,0BAaxC;CAAG;AA2DN;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,oFAqB/B,CAAC;AACL,eAAO,MAAM,4BAA4B;;CA4OxC,CAAC"}
+{"version":3,"file":"SandboxFactory.d.ts","sourceRoot":"","sources":["../src/SandboxFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAQ,KAAK,EAAE,MAAM,QAAQ,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAEL,SAAS,EACT,SAAS,EAET,aAAa,EACb,KAAK,WAAW,EACjB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,EACV,eAAe,EAEf,sBAAsB,EAEtB,qBAAqB,EACtB,MAAM,sBAAsB,CAAC;AAI9B,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,CACb,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,KACvB,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IAE1C,QAAQ,CAAC,aAAa,EAAE,CACtB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EACpC,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,KACvB,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IAE1C,QAAQ,CAAC,MAAM,EAAE,CACf,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,KAChB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAEpC,QAAQ,CAAC,OAAO,EAAE,CAChB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,KACb,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;CACrC;;AAED,qBAAa,OAAQ,SAAQ,YAG1B;CAAG;AAEN;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,gGAwDnC,CAAC;AAEL,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,6GAA6G;IAC7G,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;CACzC;;2BAK0B,CAAC,EAAE,CAAC,EAAE,CAAC;;AAHlC,qBAAa,cAAe,SAAQ,mBAWjC;CAAG;;;;IAOF,sEAAsE;;IAEtE,6FAA6F;;IAE7F,gGAAgG;;IAEhG,wEAAwE;;;AAX5E,qBAAa,qBAAsB,SAAQ,0BAcxC;CAAG;AAcN,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,wFAwBzB,CAAC;AAuGL,eAAO,MAAM,4BAA4B;;CAiQxC,CAAC"}

package/dist/SandboxFactory.js

@@ -1,140 +1,60 @@
 import { Context, Effect, Exit, Layer } from "effect";
 import { FileSystem } from "@effect/platform";
-import { NodeFileSystem } from "@effect/platform-node";
-import { randomUUID } from "node:crypto";
-import { execFile, execFileSync, spawn } from "node:child_process";
-import { dirname, join, resolve } from "node:path";
-import { createInterface } from "node:readline";
-import { startContainer, removeContainer, chownInContainer, } from "./DockerLifecycle.js";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { AgentError, CopyError, ExecError, TimeoutError, WorktreeError, } from "./errors.js";
 import * as WorktreeManager from "./WorktreeManager.js";
 import { copyToSandbox } from "./CopyToSandbox.js";
 import { Display } from "./Display.js";
+import { syncIn } from "./syncIn.js";
+import { syncOut } from "./syncOut.js";
 export class Sandbox extends Context.Tag("Sandbox")() {
 }
-const makeDockerSandbox = (containerName) => Effect.gen(function* () {
-    const fs = yield* FileSystem.FileSystem;
-    return {
-        exec: (command, options) => Effect.async((resume) => {
-            const args = ["exec"];
-            if (options?.cwd) {
-                args.push("-w", options.cwd);
-            }
-            args.push(containerName, "sh", "-c", command);
-            execFile("docker", args, { maxBuffer: 10 * 1024 * 1024 }, (error, stdout, stderr) => {
-                if (error && error.code === undefined) {
-                    resume(Effect.fail(new ExecError({
-                        command,
-                        message: `docker exec failed: ${error.message}`,
-                    })));
-                }
-                else {
-                    resume(Effect.succeed({
-                        stdout: stdout.toString(),
-                        stderr: stderr.toString(),
-                        exitCode: typeof error?.code === "number"
-                            ? error.code
-                            : 0,
-                    }));
-                }
-            });
+/**
+ * Wrap a Promise-based sandbox handle into an Effect-based SandboxService layer.
+ * Works with both bind-mount handles (copyIn/copyOut unsupported) and
+ * isolated handles (copyIn/copyOut delegated to the handle).
+ */
+export const makeSandboxLayerFromHandle = (handle) => Layer.succeed(Sandbox, {
+    exec: (command, options) => Effect.tryPromise({
+        try: () => handle.exec(command, options),
+        catch: (e) => new ExecError({
+            command,
+            message: `exec failed: ${e instanceof Error ? e.message : String(e)}`,
         }),
-        execStreaming: (command, onStdoutLine, options) => Effect.async((resume) => {
-            const args = ["exec"];
-            if (options?.cwd) {
-                args.push("-w", options.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);
-                onStdoutLine(line);
-            });
-            proc.stderr.on("data", (chunk) => {
-                stderrChunks.push(chunk.toString());
-            });
-            proc.on("error", (error) => {
-                resume(Effect.fail(new ExecError({
-                    command,
-                    message: `docker exec streaming failed: ${error.message}`,
-                })));
-            });
-            proc.on("close", (code) => {
-                resume(Effect.succeed({
-                    stdout: stdoutChunks.join("\n"),
-                    stderr: stderrChunks.join(""),
-                    exitCode: code ?? 0,
-                }));
-            });
+    }),
+    execStreaming: (command, onStdoutLine, options) => Effect.tryPromise({
+        try: () => handle.execStreaming(command, onStdoutLine, options),
+        catch: (e) => new ExecError({
+            command,
+            message: `exec streaming failed: ${e instanceof Error ? e.message : String(e)}`,
         }),
-        copyIn: (hostPath, sandboxPath) => Effect.gen(function* () {
-            const parentDir = dirname(sandboxPath);
-            yield* Effect.async((resume) => {
-                execFile("docker", ["exec", containerName, "mkdir", "-p", parentDir], (error) => {
-                    if (error) {
-                        resume(Effect.fail(new CopyError({
-                            message: `Failed to create dir ${parentDir}: ${error.message}`,
-                        })));
-                    }
-                    else {
-                        resume(Effect.succeed(undefined));
-                    }
-                });
-            });
-            yield* Effect.async((resume) => {
-                execFile("docker", ["cp", hostPath, `${containerName}:${sandboxPath}`], (error) => {
-                    if (error) {
-                        resume(Effect.fail(new CopyError({
-                            message: `Failed to copy ${hostPath} -> ${containerName}:${sandboxPath}: ${error.message}`,
-                        })));
-                    }
-                    else {
-                        resume(Effect.succeed(undefined));
-                    }
-                });
-            });
-        }),
-        copyOut: (sandboxPath, hostPath) => Effect.gen(function* () {
-            yield* fs.makeDirectory(dirname(hostPath), { recursive: true }).pipe(Effect.mapError((error) => new CopyError({
-                message: `Failed to create host dir ${dirname(hostPath)}: ${error}`,
-            })));
-            yield* Effect.async((resume) => {
-                execFile("docker", ["cp", `${containerName}:${sandboxPath}`, hostPath], (error) => {
-                    if (error) {
-                        resume(Effect.fail(new CopyError({
-                            message: `Failed to copy ${containerName}:${sandboxPath} -> ${hostPath}: ${error.message}`,
-                        })));
-                    }
-                    else {
-                        resume(Effect.succeed(undefined));
-                    }
-                });
-            });
-        }),
-    };
+    }),
+    copyIn: "copyIn" in handle
+        ? (hostPath, sandboxPath) => Effect.tryPromise({
+            try: () => handle.copyIn(hostPath, sandboxPath),
+            catch: (e) => new CopyError({
+                message: `copyIn failed: ${e instanceof Error ? e.message : String(e)}`,
+            }),
+        })
+        : () => Effect.fail(new CopyError({
+            message: "copyIn is not supported for bind-mount sandbox providers",
+        })),
+    copyOut: "copyOut" in handle
+        ? (sandboxPath, hostPath) => Effect.tryPromise({
+            try: () => handle.copyOut(sandboxPath, hostPath),
+            catch: (e) => new CopyError({
+                message: `copyOut failed: ${e instanceof Error ? e.message : String(e)}`,
+            }),
+        })
+        : () => Effect.fail(new CopyError({
+            message: "copyOut is not supported for bind-mount sandbox providers",
+        })),
 });
-export const makeDockerSandboxLayer = (containerName) => Layer.effect(Sandbox, makeDockerSandbox(containerName)).pipe(Layer.provide(NodeFileSystem.layer));
 /** The mount point inside the container where the project worktree is bound. */
 export const SANDBOX_WORKSPACE_DIR = "/home/agent/workspace";
 export class SandboxFactory extends Context.Tag("SandboxFactory")() {
 }
-/**
- * Synchronously force-remove a Docker container.
- * Used in process exit handlers where async operations are not possible.
- */
-const forceRemoveContainerSync = (containerName) => {
-    try {
-        execFileSync("docker", ["rm", "-f", containerName], { stdio: "ignore" });
-    }
-    catch {
-        // Best-effort — container may already be gone
-    }
-};
 export class WorktreeSandboxConfig extends Context.Tag("WorktreeSandboxConfig")() {
 }
 /**
@@ -146,93 +66,141 @@ const printWorktreePreservedMessage = (worktreePath, reason) => {
     console.error(`  To clean up: git worktree remove --force ${worktreePath}`);
 };
 /**
- * Start a Docker container with the given volume mounts and return cleanup helpers.
- * Shared between worktree and none modes.
- */
-const startSandboxContainer = (containerName, imageName, env, volumeMounts) => {
-    const cleanupContainerOnly = () => {
-        forceRemoveContainerSync(containerName);
-    };
-    const onSignal = () => {
-        cleanupContainerOnly();
-        process.exit(1);
-    };
-    const hostUid = process.getuid?.() ?? 1000;
-    const hostGid = process.getgid?.() ?? 1000;
-    return startContainer(containerName, imageName, { ...env, HOME: "/home/agent" }, {
-        volumeMounts,
-        workdir: SANDBOX_WORKSPACE_DIR,
-        user: `${hostUid}:${hostGid}`,
-    }).pipe(Effect.andThen(chownInContainer(containerName, `${hostUid}:${hostGid}`, "/home/agent")), Effect.tap(() => Effect.sync(() => {
-        process.on("exit", cleanupContainerOnly);
-        process.on("SIGINT", onSignal);
-        process.on("SIGTERM", onSignal);
-    })), Effect.map(() => ({ cleanupContainerOnly, onSignal })));
-};
-/**
- * Resolves the git-related volume mounts needed for the Docker container.
+ * Resolves the git-related mounts needed for the sandbox.
  * Handles both normal repos (where .git is a directory) and worktrees
  * (where .git is a file pointing to the parent repo's .git/worktrees/<name>).
  */
-export const resolveGitVolumeMounts = (gitPath) => Effect.gen(function* () {
+export const resolveGitMounts = (gitPath) => Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const stat = yield* fs.stat(gitPath);
     if (stat.type === "Directory") {
-        return [`${gitPath}:${gitPath}`];
+        return [{ hostPath: gitPath, sandboxPath: gitPath }];
     }
     // Worktree: .git is a file with "gitdir: <path>"
     const content = (yield* fs.readFileString(gitPath)).trim();
     const match = content.match(/^gitdir:\s*(.+)$/);
     if (!match) {
         // Unrecognized format — fall back to mounting the file as-is
-        return [`${gitPath}:${gitPath}`];
+        return [{ hostPath: gitPath, sandboxPath: gitPath }];
     }
     const gitdirPath = match[1];
     // gitdirPath is like /path/to/repo/.git/worktrees/<name>
     // Mount both the .git file and the parent .git directory
     const parentGitDir = resolve(gitdirPath, "..", "..");
-    return [`${gitPath}:${gitPath}`, `${parentGitDir}:${parentGitDir}`];
+    return [
+        { hostPath: gitPath, sandboxPath: gitPath },
+        { hostPath: parentGitDir, sandboxPath: parentGitDir },
+    ];
 });
+/**
+ * Start a sandbox using the provider abstraction.
+ * Returns the handle, sandbox layer, and workspace path.
+ */
+const startProviderSandbox = (provider, worktreeOrRepoPath, hostRepoDir, env, gitMounts, workspaceDir) => Effect.tryPromise({
+    try: () => {
+        const mounts = [
+            {
+                hostPath: worktreeOrRepoPath,
+                sandboxPath: workspaceDir,
+            },
+            ...gitMounts,
+        ];
+        return provider.create({
+            worktreePath: worktreeOrRepoPath,
+            hostRepoPath: hostRepoDir,
+            mounts,
+            env,
+        });
+    },
+    catch: (e) => new WorktreeError({
+        message: `Provider '${provider.name}' create failed: ${e instanceof Error ? e.message : String(e)}`,
+    }),
+}).pipe(Effect.map((handle) => ({
+    handle,
+    sandboxLayer: makeSandboxLayerFromHandle(handle),
+    workspacePath: handle.workspacePath,
+})));
+/**
+ * Start an isolated sandbox: create handle, sync host repo via git bundle.
+ * Returns the handle, sandbox layer, and workspace path.
+ */
+const startIsolatedProviderSandbox = (provider, hostRepoDir, env, copyPaths) => Effect.tryPromise({
+    try: async () => {
+        const handle = await provider.create({ env });
+        await syncIn(hostRepoDir, handle);
+        if (copyPaths && copyPaths.length > 0) {
+            for (const relativePath of copyPaths) {
+                const hostPath = join(hostRepoDir, relativePath);
+                if (!existsSync(hostPath)) {
+                    continue;
+                }
+                const sandboxPath = join(handle.workspacePath, relativePath);
+                await handle.copyIn(hostPath, sandboxPath);
+            }
+        }
+        return handle;
+    },
+    catch: (e) => new WorktreeError({
+        message: `Isolated provider '${provider.name}' setup failed: ${e instanceof Error ? e.message : String(e)}`,
+    }),
+}).pipe(Effect.map((handle) => ({
+    handle,
+    sandboxLayer: makeSandboxLayerFromHandle(handle),
+    workspacePath: handle.workspacePath,
+})));
 export const WorktreeDockerSandboxFactory = {
     layer: Layer.effect(SandboxFactory, Effect.gen(function* () {
-        const { imageName, env, hostRepoDir, worktree: worktreeMode, copyToSandbox: copyPaths, name, } = yield* WorktreeSandboxConfig;
+        const { env, hostRepoDir, worktree: worktreeMode, copyToSandbox: copyPaths, name, sandboxProvider, } = yield* WorktreeSandboxConfig;
         const isNoneMode = worktreeMode?.mode === "none";
         const branch = worktreeMode?.mode === "branch" ? worktreeMode.branch : undefined;
         const fileSystem = yield* FileSystem.FileSystem;
         const display = yield* Display;
         return {
             withSandbox: (makeEffect) => {
-                const containerName = `sandcastle-${randomUUID()}`;
+                // Isolated providers: skip worktree, sync via git bundle
+                if (sandboxProvider.tag === "isolated") {
+                    return Effect.acquireUseRelease(startIsolatedProviderSandbox(sandboxProvider, hostRepoDir, env, copyPaths), 
+                    // Use
+                    ({ sandboxLayer }) => makeEffect({}).pipe(Effect.provide(sandboxLayer)), 
+                    // Release: sync commits back to host, then close
+                    ({ handle }) => Effect.tryPromise({
+                        try: () => syncOut(hostRepoDir, handle),
+                        catch: (e) => new WorktreeError({
+                            message: `syncOut failed: ${e instanceof Error ? e.message : String(e)}`,
+                        }),
+                    }).pipe(Effect.catchAll((e) => Effect.sync(() => {
+                        console.error(`[sandcastle] Warning: syncOut failed: ${e.message}`);
+                    })), Effect.andThen(Effect.tryPromise({
+                        try: () => handle.close(),
+                        catch: () => undefined,
+                    })), Effect.orDie)).pipe(Effect.map((value) => ({
+                        value,
+                        preservedWorktreePath: undefined,
+                    })));
+                }
                 if (isNoneMode) {
                     // None mode: bind-mount host directory directly, no worktree
                     const gitPath = join(hostRepoDir, ".git");
-                    return resolveGitVolumeMounts(gitPath).pipe(Effect.provideService(FileSystem.FileSystem, fileSystem), Effect.mapError((e) => new WorktreeError({
+                    return resolveGitMounts(gitPath).pipe(Effect.provideService(FileSystem.FileSystem, fileSystem), Effect.mapError((e) => new WorktreeError({
                         message: `Failed to resolve git mounts: ${e}`,
-                    })), Effect.flatMap((gitMounts) => {
-                        const volumeMounts = [
-                            `${hostRepoDir}:${SANDBOX_WORKSPACE_DIR}`,
-                            ...gitMounts,
-                        ];
-                        return Effect.acquireUseRelease(startSandboxContainer(containerName, imageName, env, volumeMounts), 
-                        // Use
-                        () => makeEffect({}).pipe(Effect.provide(makeDockerSandboxLayer(containerName))), 
-                        // Release: remove container only (no worktree to clean up)
-                        ({ cleanupContainerOnly, onSignal }) => Effect.sync(() => {
-                            process.removeListener("exit", cleanupContainerOnly);
-                            process.removeListener("SIGINT", onSignal);
-                            process.removeListener("SIGTERM", onSignal);
-                        }).pipe(Effect.andThen(removeContainer(containerName)), Effect.orDie)).pipe(Effect.map((value) => ({
-                            value,
-                            preservedWorktreePath: undefined,
-                        })));
-                    }));
+                    })), Effect.flatMap((gitMounts) => Effect.acquireUseRelease(startProviderSandbox(sandboxProvider, hostRepoDir, hostRepoDir, env, gitMounts, SANDBOX_WORKSPACE_DIR), 
+                    // Use
+                    ({ sandboxLayer }) => makeEffect({}).pipe(Effect.provide(sandboxLayer)), 
+                    // Release
+                    ({ handle }) => Effect.tryPromise({
+                        try: () => handle.close(),
+                        catch: () => undefined,
+                    }).pipe(Effect.orDie)).pipe(Effect.map((value) => ({
+                        value,
+                        preservedWorktreePath: undefined,
+                    })))));
                 }
                 // Worktree mode (temp-branch or explicit branch)
                 // Populated by the release phase when a worktree is preserved on failure,
                 // so we can attach the path to recognized error types before they propagate.
                 let preservedWorktreePath;
                 return Effect.acquireUseRelease(
-                // Acquire: prune stale worktrees (best-effort), create worktree, then start container
+                // Acquire: prune stale worktrees (best-effort), create worktree, then start sandbox
                 WorktreeManager.pruneStale(hostRepoDir)
                     .pipe(Effect.catchAll((e) => Effect.sync(() => {
                     console.error("[sandcastle] Warning: failed to prune stale worktrees:", e.message);
@@ -246,39 +214,24 @@ export const WorktreeDockerSandboxFactory = {
                     : Effect.succeed(undefined)).pipe(Effect.map(() => worktreeInfo))))
                     .pipe(Effect.flatMap((worktreeInfo) => {
                     const gitPath = join(hostRepoDir, ".git");
-                    return resolveGitVolumeMounts(gitPath).pipe(Effect.provideService(FileSystem.FileSystem, fileSystem), Effect.mapError((e) => new WorktreeError({
+                    return resolveGitMounts(gitPath).pipe(Effect.provideService(FileSystem.FileSystem, fileSystem), Effect.mapError((e) => new WorktreeError({
                         message: `Failed to resolve git mounts: ${e}`,
-                    })), Effect.flatMap((gitMounts) => {
-                        const volumeMounts = [
-                            `${worktreeInfo.path}:${SANDBOX_WORKSPACE_DIR}`,
-                            ...gitMounts,
-                        ];
-                        return startSandboxContainer(containerName, imageName, env, volumeMounts).pipe(Effect.tap(({ cleanupContainerOnly, onSignal }) => Effect.sync(() => {
-                            // Override the default signal handler to also preserve the worktree
-                            process.removeListener("SIGINT", onSignal);
-                            process.removeListener("SIGTERM", onSignal);
-                            const onSignalWithWorktree = () => {
-                                cleanupContainerOnly();
-                                printWorktreePreservedMessage(worktreeInfo.path, `Worktree preserved at ${worktreeInfo.path}`);
-                                process.exit(1);
-                            };
-                            process.on("SIGINT", onSignalWithWorktree);
-                            process.on("SIGTERM", onSignalWithWorktree);
-                        })), Effect.map(({ cleanupContainerOnly, onSignal }) => ({
-                            worktreeInfo,
-                            cleanupContainerOnly,
-                            onSignal,
-                        })));
-                    }));
+                    })), Effect.flatMap((gitMounts) => 
+                    // sandboxProvider is guaranteed bind-mount here
+                    // (isolated providers return early above)
+                    startProviderSandbox(sandboxProvider, worktreeInfo.path, hostRepoDir, env, gitMounts, SANDBOX_WORKSPACE_DIR).pipe(Effect.map(({ handle, sandboxLayer }) => ({
+                        worktreeInfo,
+                        handle,
+                        sandboxLayer,
+                    })))));
                 })), 
                 // Use
-                ({ worktreeInfo }) => makeEffect({ hostWorktreePath: worktreeInfo.path }).pipe(Effect.provide(makeDockerSandboxLayer(containerName))), 
-                // Release: always remove container; remove/preserve worktree based on dirty state.
-                ({ worktreeInfo, cleanupContainerOnly, onSignal }, exit) => Effect.sync(() => {
-                    process.removeListener("exit", cleanupContainerOnly);
-                    process.removeListener("SIGINT", onSignal);
-                    process.removeListener("SIGTERM", onSignal);
-                }).pipe(Effect.andThen(removeContainer(containerName)), Effect.andThen(WorktreeManager.hasUncommittedChanges(worktreeInfo.path).pipe(Effect.catchAll(() => Effect.succeed(false)), Effect.flatMap((isDirty) => {
+                ({ worktreeInfo, sandboxLayer }) => makeEffect({ hostWorktreePath: worktreeInfo.path }).pipe(Effect.provide(sandboxLayer)), 
+                // Release: close provider handle, then remove/preserve worktree based on dirty state.
+                ({ worktreeInfo, handle }, exit) => Effect.tryPromise({
+                    try: () => handle.close(),
+                    catch: () => undefined,
+                }).pipe(Effect.asVoid, Effect.andThen(WorktreeManager.hasUncommittedChanges(worktreeInfo.path).pipe(Effect.catchAll(() => Effect.succeed(false)), Effect.flatMap((isDirty) => {
                     if (isDirty) {
                         preservedWorktreePath = worktreeInfo.path;
                         printWorktreePreservedMessage(worktreeInfo.path, Exit.isSuccess(exit)