@ai-hero/sandcastle 0.1.8 → 0.2.0

package/dist/createSandbox.d.ts

@@ -0,0 +1,82 @@
+import { Layer } from "effect";
+import type { AgentProvider } from "./AgentProvider.js";
+import { type PromptArgs } from "./PromptArgumentSubstitution.js";
+import type { LoggingOption } from "./run.js";
+import { Sandbox as SandboxTag } from "./SandboxFactory.js";
+export interface CreateSandboxOptions {
+    /** Explicit branch for the worktree (required). */
+    readonly branch: string;
+    /** Docker image name to use for the sandbox (default: sandcastle:<repo-dir-name>). */
+    readonly imageName?: string;
+    /** One-time setup hooks to run when the sandbox is first created. */
+    readonly hooks?: {
+        readonly onSandboxReady?: ReadonlyArray<{
+            command: string;
+        }>;
+    };
+    /** Paths relative to the host repo root to copy into the worktree at creation time. */
+    readonly copyToSandbox?: string[];
+    /** @internal Test-only overrides to bypass Docker. */
+    readonly _test?: {
+        readonly hostRepoDir?: string;
+        readonly buildSandboxLayer?: (sandboxDir: string) => Layer.Layer<SandboxTag>;
+    };
+}
+export interface SandboxRunOptions {
+    /** Agent provider to use (e.g. claudeCode("claude-opus-4-6")). */
+    readonly agent: AgentProvider;
+    /** Inline prompt string (mutually exclusive with promptFile). */
+    readonly prompt?: string;
+    /** Path to a prompt file (mutually exclusive with prompt). */
+    readonly promptFile?: string;
+    /** Key-value map for {{KEY}} placeholder substitution in prompts. */
+    readonly promptArgs?: PromptArgs;
+    /** Maximum iterations to run (default: 1). */
+    readonly maxIterations?: number;
+    /** Substring(s) the agent emits to stop the iteration loop early. */
+    readonly completionSignal?: string | string[];
+    /** Idle timeout in seconds. Default: 600. */
+    readonly idleTimeoutSeconds?: number;
+    /** Display name for this run. */
+    readonly name?: string;
+    /** Logging mode. */
+    readonly logging?: LoggingOption;
+}
+export interface SandboxRunResult {
+    /** Number of iterations the agent completed during this run. */
+    readonly iterationsRun: number;
+    /** The matched completion signal string, or undefined if none fired. */
+    readonly completionSignal?: string;
+    /** Combined stdout output from all agent iterations. */
+    readonly stdout: string;
+    /** List of commits made by the agent during the run. */
+    readonly commits: {
+        sha: string;
+    }[];
+    /** Path to the log file, if logging was drained to a file. */
+    readonly logFilePath?: string;
+}
+export interface CloseResult {
+    /** Host path to the preserved worktree, set when the worktree had uncommitted changes. */
+    readonly preservedWorktreePath?: string;
+}
+export interface Sandbox {
+    /** The branch the worktree is on. */
+    readonly branch: string;
+    /** Host path to the worktree. */
+    readonly worktreePath: string;
+    /** Invoke an agent inside the existing sandbox. */
+    run(options: SandboxRunOptions): Promise<SandboxRunResult>;
+    /** Tear down the container and worktree. */
+    close(): Promise<CloseResult>;
+    /** Auto teardown via `await using`. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Eagerly creates a git worktree on the provided explicit branch and starts
+ * a Docker container (or local sandbox in test mode) with the worktree
+ * bind-mounted. Returns a Sandbox handle that can be reused across multiple
+ * `run()` calls.
+ */
+export declare const createSandbox: (options: CreateSandboxOptions) => Promise<Sandbox>;
+//# sourceMappingURL=createSandbox.d.ts.map

package/dist/createSandbox.d.ts.map

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

package/dist/createSandbox.js

@@ -0,0 +1,192 @@
+import { NodeContext, NodeFileSystem } from "@effect/platform-node";
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { Effect, Layer, Ref } from "effect";
+import { Display, FileDisplay, SilentDisplay, } from "./Display.js";
+import { startContainer, removeContainer, chownInContainer, } from "./DockerLifecycle.js";
+import { resolveEnv } from "./EnvResolver.js";
+import { orchestrate } from "./Orchestrator.js";
+import { substitutePromptArgs, validateNoBuiltInArgOverride, BUILT_IN_PROMPT_ARG_KEYS, } from "./PromptArgumentSubstitution.js";
+import { resolvePrompt } from "./PromptResolver.js";
+import { buildLogFilename, defaultImageName, printFileDisplayStartup, } from "./run.js";
+import { Sandbox as SandboxTag, SandboxFactory, SANDBOX_WORKSPACE_DIR, makeDockerSandboxLayer, } from "./SandboxFactory.js";
+import * as WorktreeManager from "./WorktreeManager.js";
+import { copyToSandbox } from "./CopyToSandbox.js";
+/**
+ * Eagerly creates a git worktree on the provided explicit branch and starts
+ * a Docker container (or local sandbox in test mode) with the worktree
+ * bind-mounted. Returns a Sandbox handle that can be reused across multiple
+ * `run()` calls.
+ */
+export const createSandbox = async (options) => {
+    const hostRepoDir = options._test?.hostRepoDir ?? process.cwd();
+    const { branch } = options;
+    const isTestMode = !!options._test?.buildSandboxLayer;
+    // 1. Prune stale worktrees + create worktree on the explicit branch
+    const worktreeInfo = await Effect.runPromise(WorktreeManager.pruneStale(hostRepoDir)
+        .pipe(Effect.catchAll(() => Effect.void))
+        .pipe(Effect.andThen(WorktreeManager.create(hostRepoDir, { branch })))
+        .pipe(Effect.provide(NodeContext.layer)));
+    const worktreePath = worktreeInfo.path;
+    // 2. Copy files if requested
+    if (options.copyToSandbox && options.copyToSandbox.length > 0) {
+        await Effect.runPromise(copyToSandbox(options.copyToSandbox, hostRepoDir, worktreePath));
+    }
+    // 3. Start container (Docker mode) or create local sandbox layer (test mode)
+    let containerName;
+    let sandboxLayer;
+    let sandboxRepoDir;
+    if (isTestMode) {
+        sandboxLayer = options._test.buildSandboxLayer(worktreePath);
+        sandboxRepoDir = worktreePath;
+    }
+    else {
+        containerName = `sandcastle-${randomUUID()}`;
+        const resolvedImageName = options.imageName ?? defaultImageName(hostRepoDir);
+        const env = await Effect.runPromise(resolveEnv(hostRepoDir).pipe(Effect.provide(NodeContext.layer)));
+        const gitDir = join(hostRepoDir, ".git");
+        const volumeMounts = [
+            `${worktreePath}:${SANDBOX_WORKSPACE_DIR}`,
+            `${gitDir}:${gitDir}`,
+        ];
+        const hostUid = process.getuid?.() ?? 1000;
+        const hostGid = process.getgid?.() ?? 1000;
+        await Effect.runPromise(startContainer(containerName, resolvedImageName, { ...env, HOME: "/home/agent" }, {
+            volumeMounts,
+            workdir: SANDBOX_WORKSPACE_DIR,
+            user: `${hostUid}:${hostGid}`,
+        }).pipe(Effect.andThen(chownInContainer(containerName, `${hostUid}:${hostGid}`, "/home/agent"))));
+        sandboxLayer = makeDockerSandboxLayer(containerName);
+        sandboxRepoDir = SANDBOX_WORKSPACE_DIR;
+    }
+    // 4. Run onSandboxReady hooks
+    if (options.hooks?.onSandboxReady?.length) {
+        await Effect.runPromise(Effect.gen(function* () {
+            const sandbox = yield* SandboxTag;
+            yield* sandbox.exec(`git config --global --add safe.directory "${sandboxRepoDir}"`);
+            for (const hook of options.hooks.onSandboxReady) {
+                yield* sandbox.exec(hook.command, { cwd: sandboxRepoDir });
+            }
+        }).pipe(Effect.provide(sandboxLayer)));
+    }
+    // 5. Set up signal handlers
+    let closed = false;
+    const forceCleanup = () => {
+        if (containerName) {
+            try {
+                execFileSync("docker", ["rm", "-f", containerName], {
+                    stdio: "ignore",
+                });
+            }
+            catch { }
+        }
+        console.error(`\nWorktree preserved at ${worktreePath}`);
+        console.error(`  To review: cd ${worktreePath}`);
+        console.error(`  To clean up: git worktree remove --force ${worktreePath}`);
+    };
+    const onSignal = () => {
+        forceCleanup();
+        process.exit(1);
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    // 6. Build close function
+    const doClose = async () => {
+        if (closed)
+            return { preservedWorktreePath: undefined };
+        closed = true;
+        // Remove container
+        if (containerName) {
+            await Effect.runPromise(removeContainer(containerName).pipe(Effect.orDie));
+        }
+        // Check for uncommitted changes
+        const isDirty = await Effect.runPromise(WorktreeManager.hasUncommittedChanges(worktreePath).pipe(Effect.catchAll(() => Effect.succeed(false))));
+        if (isDirty) {
+            return { preservedWorktreePath: worktreePath };
+        }
+        // Remove worktree
+        await Effect.runPromise(WorktreeManager.remove(worktreePath).pipe(Effect.catchAll(() => Effect.void)));
+        return { preservedWorktreePath: undefined };
+    };
+    // 7. Return the Sandbox handle
+    const sandboxHandle = {
+        branch,
+        worktreePath,
+        run: async (runOptions) => {
+            const { agent: provider, prompt, promptFile, maxIterations = 1, } = runOptions;
+            // Resolve prompt
+            const rawPrompt = await Effect.runPromise(resolvePrompt({ prompt, promptFile }).pipe(Effect.provide(NodeContext.layer)));
+            // Resolve prompt arguments
+            const userArgs = runOptions.promptArgs ?? {};
+            const currentHostBranch = await Effect.runPromise(WorktreeManager.getCurrentBranch(hostRepoDir));
+            const displayRef = Ref.unsafeMake([]);
+            const silentDisplayLayer = SilentDisplay.layer(displayRef);
+            const resolvedPrompt = await Effect.runPromise(Effect.gen(function* () {
+                yield* validateNoBuiltInArgOverride(userArgs);
+                const effectiveArgs = {
+                    SOURCE_BRANCH: branch,
+                    TARGET_BRANCH: currentHostBranch,
+                    ...userArgs,
+                };
+                const builtInArgKeysSet = new Set(BUILT_IN_PROMPT_ARG_KEYS);
+                return yield* substitutePromptArgs(rawPrompt, effectiveArgs, builtInArgKeysSet);
+            }).pipe(Effect.provide(silentDisplayLayer)));
+            // Resolve logging
+            const resolvedLogging = runOptions.logging ?? {
+                type: "file",
+                path: join(hostRepoDir, ".sandcastle", "logs", buildLogFilename(branch, undefined, runOptions.name)),
+            };
+            const runDisplayLayer = resolvedLogging.type === "file"
+                ? (() => {
+                    printFileDisplayStartup({
+                        logPath: resolvedLogging.path,
+                        agentName: runOptions.name,
+                        branch,
+                    });
+                    return Layer.provide(FileDisplay.layer(resolvedLogging.path), NodeFileSystem.layer);
+                })()
+                : silentDisplayLayer;
+            // Build a SandboxFactory that reuses the existing container/sandbox
+            const reuseFactoryLayer = Layer.succeed(SandboxFactory, {
+                withSandbox: (makeEffect) => makeEffect({ hostWorktreePath: worktreePath }).pipe(Effect.provide(sandboxLayer), Effect.map((value) => ({
+                    value,
+                    preservedWorktreePath: undefined,
+                }))),
+            });
+            const runLayer = Layer.merge(reuseFactoryLayer, runDisplayLayer);
+            const result = await Effect.runPromise(Effect.gen(function* () {
+                const display = yield* Display;
+                yield* display.intro(runOptions.name ?? "sandcastle");
+                return yield* orchestrate({
+                    hostRepoDir,
+                    sandboxRepoDir,
+                    iterations: maxIterations,
+                    prompt: resolvedPrompt,
+                    branch,
+                    provider,
+                    completionSignal: runOptions.completionSignal,
+                    idleTimeoutSeconds: runOptions.idleTimeoutSeconds,
+                    name: runOptions.name,
+                });
+            }).pipe(Effect.provide(runLayer)));
+            return {
+                iterationsRun: result.iterationsRun,
+                completionSignal: result.completionSignal,
+                stdout: result.stdout,
+                commits: result.commits,
+                logFilePath: resolvedLogging.type === "file" ? resolvedLogging.path : undefined,
+            };
+        },
+        close: async () => {
+            process.removeListener("SIGINT", onSignal);
+            process.removeListener("SIGTERM", onSignal);
+            return doClose();
+        },
+        [Symbol.asyncDispose]: async () => {
+            await sandboxHandle.close();
+        },
+    };
+    return sandboxHandle;
+};
+//# sourceMappingURL=createSandbox.js.map

package/dist/createSandbox.js.map

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

package/dist/index.d.ts

@@ -1,4 +1,8 @@
 export { run } from "./run.js";
-export type { RunOptions, RunResult, LoggingOption } from "./run.js";
+export type { RunOptions, RunResult, LoggingOption, WorktreeMode, } from "./run.js";
+export { createSandbox } from "./createSandbox.js";
+export type { CreateSandboxOptions, Sandbox, SandboxRunOptions, SandboxRunResult, CloseResult, } from "./createSandbox.js";
 export type { PromptArgs } from "./PromptArgumentSubstitution.js";
+export { claudeCode, codex, pi } from "./AgentProvider.js";
+export type { AgentProvider } from "./AgentProvider.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACrE,YAAY,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,YAAY,EACV,UAAU,EACV,SAAS,EACT,aAAa,EACb,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EACV,oBAAoB,EACpB,OAAO,EACP,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,oBAAoB,CAAC;AAC3D,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -1,2 +1,4 @@
 export { run } from "./run.js";
+export { createSandbox } from "./createSandbox.js";
+export { claudeCode, codex, pi } from "./AgentProvider.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAO/B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AASnD,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/run.d.ts

@@ -1,3 +1,4 @@
+import type { AgentProvider } from "./AgentProvider.js";
 import { type Severity } from "./Display.js";
 import { type PromptArgs } from "./PromptArgumentSubstitution.js";
 /** Default maximum number of iterations for a run. */
@@ -35,7 +36,6 @@ export interface RunSummaryRowsOptions {
     readonly imageName: string;
     readonly maxIterations: number;
     readonly branch: string;
-    readonly model?: string;
 }
 /**
  * Build the summary rows for a run, used in both terminal mode and
@@ -66,7 +66,23 @@ export type LoggingOption =
  | {
     readonly type: "stdout";
 };
+/**
+ * Worktree mode discriminated union.
+ * - `none`: bind-mounts host working directory directly; no worktree, no merge step.
+ * - `temp-branch`: creates a temporary worktree/branch, merges back, deletes the temp branch (default).
+ * - `branch`: creates a worktree on an explicit branch; commits stay on that branch.
+ */
+export type WorktreeMode = {
+    readonly mode: "none";
+} | {
+    readonly mode: "temp-branch";
+} | {
+    readonly mode: "branch";
+    readonly branch: string;
+};
 export interface RunOptions {
+    /** Agent provider to use (e.g. claudeCode("claude-opus-4-6")) */
+    readonly agent: AgentProvider;
     /** Inline prompt string (mutually exclusive with promptFile) */
     readonly prompt?: string;
     /** Path to a prompt file (mutually exclusive with prompt) */
@@ -79,10 +95,8 @@ export interface RunOptions {
             command: string;
         }>;
     };
-    /** Target branch name for sandbox work */
-    readonly branch?: string;
-    /** Model to use for the agent (default: claude-opus-4-6) */
-    readonly model?: string;
+    /** Worktree mode for sandbox work. Defaults to `{ mode: 'temp-branch' }` when omitted. */
+    readonly worktree?: WorktreeMode;
     /** Docker image name to use for the sandbox (default: sandcastle:<repo-dir-name>) */
     readonly imageName?: string;
     /** Key-value map for {{KEY}} placeholder substitution in prompts */
@@ -91,7 +105,7 @@ export interface RunOptions {
     readonly logging?: LoggingOption;
     /** Substring(s) the agent emits to stop the iteration loop early. Matched via `includes` against agent output. (default: `"<promise>COMPLETE</promise>"`) */
     readonly completionSignal?: string | string[];
-    /** Idle timeout in seconds. If the agent produces no output for this long, it fails. Default: 300 (5 minutes) */
+    /** Idle timeout in seconds. If the agent produces no output for this long, it fails. Default: 600 (10 minutes) */
     readonly idleTimeoutSeconds?: number;
     /** Optional name for the run, shown as a prefix in log output */
     readonly name?: string;

package/dist/run.d.ts.map

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

package/dist/run.js

@@ -2,7 +2,6 @@ import { NodeContext, NodeFileSystem } from "@effect/platform-node";
 import path, { join } from "node:path";
 import { styleText } from "node:util";
 import { Effect, Layer } from "effect";
-import { getAgentProvider } from "./AgentProvider.js";
 import { ClackDisplay, Display, FileDisplay, } from "./Display.js";
 import { orchestrate } from "./Orchestrator.js";
 import { resolvePrompt } from "./PromptResolver.js";
@@ -59,17 +58,12 @@ export const buildLogFilename = (resolvedBranch, targetBranch, name) => {
  * log-to-file mode. When a custom name is provided it appears as the
  * Agent value instead of the internal provider name.
  */
-export const buildRunSummaryRows = (options) => {
-    const rows = {
-        Agent: options.name ?? options.agentName,
-        Image: options.imageName,
-        "Max iterations": String(options.maxIterations),
-        Branch: options.branch,
-    };
-    if (options.model)
-        rows["Model"] = options.model;
-    return rows;
-};
+export const buildRunSummaryRows = (options) => ({
+    Agent: options.name ?? options.agentName,
+    Image: options.imageName,
+    "Max iterations": String(options.maxIterations),
+    Branch: options.branch,
+});
 /**
  * Build the completion status message for a run, used in both terminal mode
  * and log-to-file mode to record the final outcome.
@@ -87,29 +81,39 @@ export const buildCompletionMessage = (completionSignal, iterationsRun) => {
     };
 };
 export const run = async (options) => {
-    const { prompt, promptFile, maxIterations = DEFAULT_MAX_ITERATIONS, hooks, branch, model, } = options;
+    const { prompt, promptFile, maxIterations = DEFAULT_MAX_ITERATIONS, hooks, agent: provider, } = options;
+    // Resolve worktree mode: default to temp-branch when omitted
+    const worktreeMode = options.worktree ?? {
+        mode: "temp-branch",
+    };
+    // Validate: copyToSandbox is incompatible with mode: 'none'
+    if (worktreeMode.mode === "none" &&
+        options.copyToSandbox &&
+        options.copyToSandbox.length > 0) {
+        throw new Error("copyToSandbox is not supported with worktree mode 'none'. " +
+            "In mode 'none' the host working directory is bind-mounted directly.");
+    }
+    // Extract explicit branch when in branch mode, undefined for temp-branch/none mode
+    const branch = worktreeMode.mode === "branch" ? worktreeMode.branch : undefined;
     const hostRepoDir = process.cwd();
     // Resolve prompt
     const rawPrompt = await Effect.runPromise(resolvePrompt({ prompt, promptFile }).pipe(Effect.provide(NodeContext.layer)));
-    // Resolve model: explicit option > default
-    const resolvedModel = model;
-    // Agent is hardcoded to claude-code (agent selection is not part of the public API)
-    const agentName = "claude-code";
-    const provider = getAgentProvider(agentName);
+    const agentName = provider.name;
     // Resolve image name: explicit option > default
     const resolvedImageName = options.imageName ?? defaultImageName(hostRepoDir);
     // Resolve env vars
     const env = await Effect.runPromise(resolveEnv(hostRepoDir).pipe(Effect.provide(NodeContext.layer)));
-    // When no branch is provided, generate a temporary branch name.
-    // This names the log file after the temp branch and also directs
-    // the sandbox to work on that branch (instead of the current host branch).
-    const resolvedBranch = branch ?? generateTempBranchName(agentName);
     // Always capture the host's current branch for the TARGET_BRANCH built-in
     // prompt argument. When using a temp branch, it also prefixes the log filename.
     const currentHostBranch = await Effect.runPromise(getCurrentBranch(hostRepoDir));
+    // When in temp-branch mode, generate a temporary branch name.
+    // In none mode, use the host's current branch directly (no worktree).
+    const resolvedBranch = worktreeMode.mode === "none"
+        ? currentHostBranch
+        : (branch ?? generateTempBranchName(options.name));
     // When using a temp branch, prefix the log filename with the target branch
     // (the host's current branch) so developers can tell which branch was targeted.
-    const targetBranch = branch === undefined ? currentHostBranch : undefined;
+    const targetBranch = worktreeMode.mode === "temp-branch" ? currentHostBranch : undefined;
     // Resolve logging option
     const resolvedLogging = options.logging ?? {
         type: "file",
@@ -129,11 +133,9 @@ export const run = async (options) => {
         imageName: resolvedImageName,
         env,
         hostRepoDir,
-        // Pass explicit branch only — when undefined, WorktreeManager creates a temp branch
-        // and SandboxLifecycle cherry-picks commits onto the host's current branch
-        branch,
+        worktree: worktreeMode,
         copyToSandbox: options.copyToSandbox,
-        agentName,
+        name: options.name,
     }), NodeFileSystem.layer, displayLayer));
     const runLayer = Layer.merge(factoryLayer, displayLayer);
     const result = await Effect.runPromise(Effect.gen(function* () {
@@ -145,14 +147,14 @@ export const run = async (options) => {
             imageName: resolvedImageName,
             maxIterations,
             branch: resolvedBranch,
-            model: resolvedModel,
         });
         yield* d.summary("Sandcastle Run", rows);
         // Validate that the user has not provided built-in prompt argument keys
         const userArgs = options.promptArgs ?? {};
         yield* validateNoBuiltInArgOverride(userArgs);
         // Build effective args: built-in args merged with user-provided args.
-        // Built-in keys are silenced so they don't trigger unused-arg warnings.
+        // In none mode, resolvedBranch is already currentHostBranch, so
+        // SOURCE_BRANCH and TARGET_BRANCH both resolve to the host's current branch.
         const effectiveArgs = {
             SOURCE_BRANCH: resolvedBranch,
             TARGET_BRANCH: currentHostBranch,
@@ -160,14 +162,17 @@ export const run = async (options) => {
         };
         const builtInArgKeysSet = new Set(BUILT_IN_PROMPT_ARG_KEYS);
         const resolvedPrompt = yield* substitutePromptArgs(rawPrompt, effectiveArgs, builtInArgKeysSet);
+        // In none mode, pass the host branch so SandboxLifecycle skips the merge step.
+        // In temp-branch mode, branch is undefined (triggers merge). In branch mode, it's the explicit branch.
+        const orchestrateBranch = worktreeMode.mode === "none" ? currentHostBranch : branch;
         const orchestrateResult = yield* orchestrate({
             hostRepoDir,
             sandboxRepoDir: SANDBOX_WORKSPACE_DIR,
             iterations: maxIterations,
             hooks,
             prompt: resolvedPrompt,
-            branch,
-            model: resolvedModel,
+            branch: orchestrateBranch,
+            provider,
             completionSignal: options.completionSignal,
             idleTimeoutSeconds: options.idleTimeoutSeconds,
             name: options.name,

package/dist/run.js.map

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

package/dist/templates/blank/.env.example

@@ -0,0 +1,4 @@
+# Anthropic API key
+ANTHROPIC_API_KEY=
+# GitHub personal access token
+GH_TOKEN=

package/dist/templates/blank/main.ts

@@ -1,9 +1,10 @@
-import { run } from "@ai-hero/sandcastle";
+import { run, claudeCode } from "@ai-hero/sandcastle";
 
 // Blank template: customize this to build your own orchestration.
 // Run this with: npx tsx .sandcastle/main.ts
 // Or add to package.json scripts: "sandcastle": "npx tsx .sandcastle/main.ts"
 
 await run({
+  agent: claudeCode("claude-opus-4-6"),
   promptFile: "./.sandcastle/prompt.md",
 });

package/dist/templates/parallel-planner/.env.example

@@ -0,0 +1,4 @@
+# Anthropic API key
+ANTHROPIC_API_KEY=
+# GitHub personal access token
+GH_TOKEN=

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

@@ -61,7 +61,7 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
     // not write code.
     maxIterations: 1,
     // Opus for planning: dependency analysis benefits from deeper reasoning.
-    model: "claude-opus-4-6",
+    agent: sandcastle.claudeCode("claude-opus-4-6"),
     promptFile: "./.sandcastle/plan-prompt.md",
   });
 
@@ -109,7 +109,7 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
         // Give each agent plenty of room to implement and iterate on tests.
         maxIterations: 100,
         // Sonnet for execution: fast and capable enough for typical issue work.
-        model: "claude-sonnet-4-6",
+        agent: sandcastle.claudeCode("claude-sonnet-4-6"),
         promptFile: "./.sandcastle/implement-prompt.md",
         // Prompt arguments substitute {{ISSUE_NUMBER}}, {{ISSUE_TITLE}},
         // and {{BRANCH}} placeholders in implement-prompt.md before the
@@ -120,7 +120,7 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
           BRANCH: issue.branch,
         },
         // Each agent starts on its own branch.
-        branch: issue.branch,
+        worktree: { mode: "branch", branch: issue.branch },
       }),
     ),
   );
@@ -182,7 +182,7 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
     name: "merger",
     maxIterations: 10,
     // Sonnet is sufficient for merge conflict resolution.
-    model: "claude-sonnet-4-6",
+    agent: sandcastle.claudeCode("claude-sonnet-4-6"),
     promptFile: "./.sandcastle/merge-prompt.md",
     promptArgs: {
       // A markdown list of branch names, one per line.

package/dist/templates/sequential-reviewer/.env.example

@@ -0,0 +1,4 @@
+# Anthropic API key
+ANTHROPIC_API_KEY=
+# GitHub personal access token
+GH_TOKEN=