stageflow 0.36.0 → 0.40.0

package/dist/runstore/sqlite/migrations/index.js

@@ -11,6 +11,8 @@ import { MIGRATION_009 } from "./009-trigger-next-run.js";
 import { MIGRATION_010 } from "./010-trigger-adapter-state.js";
 import { MIGRATION_011 } from "./011-email-dispatch-key.js";
 import { MIGRATION_012 } from "./012-trigger-fires.js";
+import { MIGRATION_013 } from "./013-agents.js";
+import { MIGRATION_014 } from "./014-agent-deliveries.js";
 const DEFAULT_MIGRATIONS = [
     MIGRATION_001,
     MIGRATION_002,
@@ -24,6 +26,8 @@ const DEFAULT_MIGRATIONS = [
     MIGRATION_010,
     MIGRATION_011,
     MIGRATION_012,
+    MIGRATION_013,
+    MIGRATION_014,
 ];
 export const CURRENT_SCHEMA_VERSION = DEFAULT_MIGRATIONS[DEFAULT_MIGRATIONS.length - 1].version;
 function throwStoreSchemaTooNew(db, version, maxKnown) {

package/dist/runtime/gitCheckoutCapability.d.ts

@@ -1,4 +1,5 @@
 import type { CheckoutCapability } from "./completionCheckRunner.js";
+export declare function runGit(root: string, args: string[]): Promise<Buffer>;
 /**
  * Git-backed checkout observation. It fingerprints tracked and untracked
  * files before the agent runs, so pre-existing changes are not attributed to

package/dist/runtime/gitCheckoutCapability.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { lstat, readFile, readlink } from "node:fs/promises";
 import path from "node:path";
 import { runGit as execGit } from "../git/exec.js";
-async function runGit(root, args) {
+export async function runGit(root, args) {
     const result = await execGit({
         cwd: root,
         args,

package/dist/runtime/gitWorktreeCheckout.d.ts

@@ -0,0 +1,22 @@
+import { sanitizeContainerNameSegment } from "./sandboxContainer.js";
+export declare const sanitizeBranchForPath: typeof sanitizeContainerNameSegment;
+export declare function defaultBranchNameForTask(taskId: string): string;
+export declare function worktreePathFor(projectRoot: string, branch: string): string;
+/**
+ * Ensures a git worktree checked out to `branch` (creating the branch from
+ * `base` if it doesn't exist yet) exists at a deterministic path derived
+ * from the branch name, and returns that path.
+ *
+ * Deterministic (not per-run/random) on purpose: `resolveAndValidateCheckout`
+ * is called twice per run start (runManager.ts, for the checkout lease key,
+ * then pipelineRunner.ts, for the durable run record) — a random path would
+ * create two worktrees for one run. A stable path also means rerunning the
+ * same task/branch reuses the same worktree, matching the "leave it in
+ * place" behavior an operator gets from making one by hand.
+ */
+export declare function ensureWorktreeCheckout(params: {
+    projectRoot: string;
+    branch?: string;
+    base?: string;
+    taskId: string;
+}): Promise<string>;

package/dist/runtime/gitWorktreeCheckout.js

@@ -0,0 +1,120 @@
+import { access, mkdir, realpath } from "node:fs/promises";
+import path from "node:path";
+import { runGit } from "./gitCheckoutCapability.js";
+import { sanitizeContainerNameSegment } from "./sandboxContainer.js";
+/**
+ * Auto-created worktrees live as siblings of the project root (not nested
+ * inside it) — the same place `examples/ship-feature/README.md` already
+ * tells operators to put a hand-made one, just automated.
+ */
+const WORKTREES_DIR_NAME = ".stageflow-worktrees";
+export const sanitizeBranchForPath = sanitizeContainerNameSegment;
+export function defaultBranchNameForTask(taskId) {
+    return `stageflow/${sanitizeBranchForPath(taskId)}`;
+}
+export function worktreePathFor(projectRoot, branch) {
+    return path.join(path.dirname(projectRoot), WORKTREES_DIR_NAME, sanitizeBranchForPath(branch));
+}
+async function git(projectRoot, args) {
+    const stdout = await runGit(projectRoot, args);
+    return stdout.toString("utf8");
+}
+async function registeredWorktreePaths(projectRoot) {
+    const stdout = await git(projectRoot, ["worktree", "list", "--porcelain"]);
+    const paths = new Set();
+    for (const line of stdout.split("\n")) {
+        const match = /^worktree (.+)$/.exec(line);
+        if (match)
+            paths.add(match[1]);
+    }
+    return paths;
+}
+async function branchExists(projectRoot, branch) {
+    try {
+        await git(projectRoot, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function pathExists(target) {
+    try {
+        await access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// A ref/branch value starting with `-` can get reinterpreted by git as a
+// flag instead of a literal name (e.g. `-b --upload-pack=...`) — task YAML
+// is operator-authored, not attacker input, but rejecting this outright is
+// free and closes the class of mistake/footgun entirely.
+function assertNotFlagLike(value, label) {
+    if (value.startsWith("-")) {
+        throw new Error(`Invalid ${label} "${value}": must not start with "-"`);
+    }
+}
+/**
+ * Ensures a git worktree checked out to `branch` (creating the branch from
+ * `base` if it doesn't exist yet) exists at a deterministic path derived
+ * from the branch name, and returns that path.
+ *
+ * Deterministic (not per-run/random) on purpose: `resolveAndValidateCheckout`
+ * is called twice per run start (runManager.ts, for the checkout lease key,
+ * then pipelineRunner.ts, for the durable run record) — a random path would
+ * create two worktrees for one run. A stable path also means rerunning the
+ * same task/branch reuses the same worktree, matching the "leave it in
+ * place" behavior an operator gets from making one by hand.
+ */
+export async function ensureWorktreeCheckout(params) {
+    // `git worktree list --porcelain` reports canonicalized paths (symlinks
+    // resolved, e.g. macOS's /var -> /private/var) — realpath the project
+    // root up front so every path this function builds or compares matches
+    // what git itself reports, instead of drifting apart on a symlinked tmp
+    // dir or similar.
+    const projectRoot = await realpath(params.projectRoot);
+    const branch = params.branch ?? defaultBranchNameForTask(params.taskId);
+    assertNotFlagLike(branch, "checkout.branch");
+    if (params.base !== undefined)
+        assertNotFlagLike(params.base, "checkout.base");
+    const targetPath = worktreePathFor(projectRoot, branch);
+    const registered = await registeredWorktreePaths(projectRoot);
+    if (registered.has(targetPath)) {
+        if (await pathExists(targetPath)) {
+            return targetPath;
+        }
+        // Registered but the directory is gone (e.g. deleted with `rm -rf`
+        // instead of `git worktree remove`) — clear the stale registration so
+        // `worktree add` below doesn't refuse to reuse the path.
+        await git(projectRoot, ["worktree", "prune"]);
+    }
+    else if (await pathExists(targetPath)) {
+        throw new Error(`Worktree path already exists but is not a registered git worktree: ${targetPath}. Remove it or use a different branch name.`);
+    }
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    if (await branchExists(projectRoot, branch)) {
+        await git(projectRoot, ["worktree", "add", targetPath, branch]);
+    }
+    else {
+        await git(projectRoot, [
+            "worktree",
+            "add",
+            targetPath,
+            "-b",
+            branch,
+            params.base ?? "HEAD",
+        ]);
+    }
+    // Two concurrent run-starts auto-creating the same branch/worktree can
+    // race inside `git worktree add` itself — for the "branch already
+    // exists" path this has been observed to exit 0 while leaving no
+    // directory behind (the loser silently no-ops instead of erroring).
+    // Turn that into a loud, unambiguous failure rather than handing back a
+    // "successful" path that doesn't exist.
+    if (!(await pathExists(targetPath))) {
+        throw new Error(`git worktree add reported success but ${targetPath} does not exist — likely a concurrent worktree creation for the same branch ("${branch}"); retry.`);
+    }
+    return targetPath;
+}

package/dist/runtime/sandboxContainer.d.ts

@@ -0,0 +1,62 @@
+export declare const SANDBOX_CONTAINER_IMAGE_ENV = "STAGEFLOW_STAGE_CONTAINER_IMAGE";
+export declare const SANDBOX_CONTAINER_DOCKER_BIN_ENV = "STAGEFLOW_STAGE_CONTAINER_DOCKER_BIN";
+/** Docker container names allow only `[a-zA-Z0-9_.-]`. */
+export declare function sanitizeContainerNameSegment(value: string): string;
+export declare function buildContainerName(input: {
+    runId: string;
+    stageId: string;
+    attempt?: number;
+}, suffix: string): string;
+export type SandboxContainerOptions = {
+    image: string;
+    dockerBin: string;
+};
+export declare function resolveSandboxContainerOptions(env: Record<string, string | undefined>, override?: {
+    image: string;
+    dockerBin?: string;
+}): SandboxContainerOptions | undefined;
+/** Fixed path inside the sandbox. The daemon owns the volume; we never pass it a path from this process. */
+export declare const SANDBOX_MOUNT_PATH = "/workspace";
+export declare function sandboxVolumeName(containerName: string): string;
+export declare function buildStartContainerArgs(params: {
+    image: string;
+    containerName: string;
+}): string[];
+export declare function startSandboxContainer(params: {
+    image: string;
+    runId: string;
+    stageId: string;
+    attempt?: number;
+    dockerBin?: string;
+}): Promise<{
+    containerName: string;
+}>;
+export declare function stopSandboxContainer(params: {
+    containerName: string;
+    dockerBin?: string;
+}): Promise<void>;
+export type SandboxExecResult = {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+};
+export declare function execInSandboxContainer(params: {
+    containerName: string;
+    command: string;
+    dockerBin?: string;
+    timeoutMs?: number;
+}): Promise<SandboxExecResult>;
+export declare function copyToSandboxContainer(params: {
+    containerName: string;
+    hostPath: string;
+    containerPath: string;
+    dockerBin?: string;
+    contents?: boolean;
+}): Promise<void>;
+export declare function copyFromSandboxContainer(params: {
+    containerName: string;
+    containerPath: string;
+    hostPath: string;
+    dockerBin?: string;
+    contents?: boolean;
+}): Promise<void>;

package/dist/runtime/sandboxContainer.js

@@ -0,0 +1,151 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { promisify } from "node:util";
+export const SANDBOX_CONTAINER_IMAGE_ENV = "STAGEFLOW_STAGE_CONTAINER_IMAGE";
+export const SANDBOX_CONTAINER_DOCKER_BIN_ENV = "STAGEFLOW_STAGE_CONTAINER_DOCKER_BIN";
+const execFileAsync = promisify(execFile);
+/** Docker container names allow only `[a-zA-Z0-9_.-]`. */
+export function sanitizeContainerNameSegment(value) {
+    return value.replace(/[^a-zA-Z0-9_.-]/g, "-");
+}
+export function buildContainerName(input, suffix) {
+    const runId = sanitizeContainerNameSegment(input.runId);
+    const stageId = sanitizeContainerNameSegment(input.stageId);
+    const attempt = input.attempt ?? 1;
+    return `stageflow-${runId}-${stageId}-${attempt}-${suffix}`;
+}
+export function resolveSandboxContainerOptions(env, override) {
+    if (override) {
+        if (!override.image || override.image.trim() === "") {
+            throw new Error("sandboxContainer: image must be a non-empty string");
+        }
+        return { image: override.image, dockerBin: override.dockerBin || "docker" };
+    }
+    const image = env[SANDBOX_CONTAINER_IMAGE_ENV];
+    if (!image || image.trim() === "")
+        return undefined;
+    return {
+        image,
+        dockerBin: env[SANDBOX_CONTAINER_DOCKER_BIN_ENV] || "docker",
+    };
+}
+/** Fixed path inside the sandbox. The daemon owns the volume; we never pass it a path from this process. */
+export const SANDBOX_MOUNT_PATH = "/workspace";
+export function sandboxVolumeName(containerName) {
+    const safe = containerName.replace(/[^A-Za-z0-9_.-]/g, "_");
+    return `sf-bash-${safe}`;
+}
+export function buildStartContainerArgs(params) {
+    const { image, containerName } = params;
+    return [
+        "run",
+        "-d",
+        "--name",
+        containerName,
+        "-v",
+        `${sandboxVolumeName(containerName)}:${SANDBOX_MOUNT_PATH}`,
+        "-w",
+        SANDBOX_MOUNT_PATH,
+        image,
+        "sleep",
+        "infinity",
+    ];
+}
+function errorMessage(err) {
+    if (err && typeof err === "object" && "stderr" in err) {
+        const stderr = err.stderr;
+        if (typeof stderr === "string" && stderr.trim().length > 0)
+            return stderr;
+    }
+    return err instanceof Error ? err.message : String(err);
+}
+export async function startSandboxContainer(params) {
+    const containerName = buildContainerName({ runId: params.runId, stageId: params.stageId, attempt: params.attempt }, randomUUID().slice(0, 8));
+    const args = buildStartContainerArgs({
+        image: params.image,
+        containerName,
+    });
+    try {
+        await execFileAsync(params.dockerBin ?? "docker", args);
+    }
+    catch (err) {
+        throw new Error(`failed to start sandbox container: ${errorMessage(err)}`);
+    }
+    return { containerName };
+}
+const NO_SUCH_CONTAINER_PATTERN = /no such container/i;
+const NO_SUCH_VOLUME_PATTERN = /no such volume/i;
+export async function stopSandboxContainer(params) {
+    try {
+        await execFileAsync(params.dockerBin ?? "docker", [
+            "rm",
+            "-f",
+            params.containerName,
+        ]);
+    }
+    catch (err) {
+        const stderr = stderrOf(err);
+        if (!NO_SUCH_CONTAINER_PATTERN.test(stderr)) {
+            throw new Error(`failed to stop sandbox container: ${errorMessage(err)}`);
+        }
+    }
+    try {
+        await execFileAsync(params.dockerBin ?? "docker", [
+            "volume",
+            "rm",
+            sandboxVolumeName(params.containerName),
+        ]);
+    }
+    catch (err) {
+        const stderr = stderrOf(err);
+        if (NO_SUCH_VOLUME_PATTERN.test(stderr))
+            return;
+        throw new Error(`failed to remove sandbox volume: ${errorMessage(err)}`);
+    }
+}
+function stderrOf(err) {
+    if (err && typeof err === "object" && "stderr" in err) {
+        return String(err.stderr ?? "");
+    }
+    return "";
+}
+export async function execInSandboxContainer(params) {
+    const args = ["exec", "-w", SANDBOX_MOUNT_PATH, params.containerName, "bash", "-c", params.command];
+    try {
+        const { stdout, stderr } = await execFileAsync(params.dockerBin ?? "docker", args, {
+            maxBuffer: 8 * 1024 * 1024,
+            ...(params.timeoutMs !== undefined ? { timeout: params.timeoutMs } : {}),
+        });
+        return { stdout, stderr, exitCode: 0 };
+    }
+    catch (err) {
+        const e = err;
+        // `code` is a number only for a completed exec that exited non-zero.
+        // Anything else (ENOENT for a missing docker binary, the container
+        // having been removed mid-exec, etc.) is an infra failure, not a
+        // command result — rethrow so callers don't mistake it for "the
+        // command ran and exited 1".
+        if (typeof e.code !== "number") {
+            throw new Error(`failed to exec in sandbox container: ${errorMessage(err)}`);
+        }
+        return { stdout: e.stdout ?? "", stderr: e.stderr ?? "", exitCode: e.code };
+    }
+}
+export async function copyToSandboxContainer(params) {
+    const src = params.contents ? `${params.hostPath}/.` : params.hostPath;
+    await dockerCp(params.dockerBin, src, `${params.containerName}:${params.containerPath}`, "into");
+}
+export async function copyFromSandboxContainer(params) {
+    const src = params.contents
+        ? `${params.containerName}:${params.containerPath}/.`
+        : `${params.containerName}:${params.containerPath}`;
+    await dockerCp(params.dockerBin, src, params.hostPath, "from");
+}
+async function dockerCp(dockerBin, src, dest, direction) {
+    try {
+        await execFileAsync(dockerBin ?? "docker", ["cp", src, dest]);
+    }
+    catch (err) {
+        throw new Error(`failed to copy ${direction} sandbox: ${errorMessage(err)}`);
+    }
+}

package/dist/runtime/sandboxDesk.d.ts

@@ -0,0 +1,28 @@
+export type SandboxDeskRole = "artifacts" | "envelope" | "checkout" | "grant" | "work";
+export type SandboxDeskBinding = {
+    role: SandboxDeskRole;
+    hostPath: string;
+    containerPath: string;
+    shape: "directory" | "file" | "mirror";
+    copyIn: boolean;
+    copyOut: boolean;
+    optional: boolean;
+};
+export type SandboxDesk = {
+    bindings: readonly SandboxDeskBinding[];
+};
+export declare function buildSandboxDesk(input: {
+    attemptDir: string;
+    checkoutRoot?: string;
+    grantedPaths?: readonly string[];
+}): SandboxDesk;
+export declare function populateSandboxDesk(params: {
+    containerName: string;
+    dockerBin?: string;
+    desk: SandboxDesk;
+}): Promise<void>;
+export declare function syncSandboxDesk(params: {
+    containerName: string;
+    dockerBin?: string;
+    desk: SandboxDesk;
+}): Promise<void>;

package/dist/runtime/sandboxDesk.js

@@ -0,0 +1,242 @@
+import { randomBytes } from "node:crypto";
+import { access, mkdir, rename, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { copyFromSandboxContainer, copyToSandboxContainer, execInSandboxContainer, SANDBOX_MOUNT_PATH, } from "./sandboxContainer.js";
+import { shellQuote } from "./sandboxFiles.js";
+export function buildSandboxDesk(input) {
+    const attemptDir = input.attemptDir;
+    const bindings = [
+        {
+            role: "artifacts",
+            hostPath: path.join(attemptDir, "artifacts"),
+            containerPath: `${SANDBOX_MOUNT_PATH}/artifacts`,
+            shape: "directory",
+            copyIn: true,
+            copyOut: false,
+            optional: true,
+        },
+        {
+            role: "envelope",
+            hostPath: path.join(attemptDir, "envelope.json"),
+            containerPath: `${SANDBOX_MOUNT_PATH}/envelope.json`,
+            shape: "file",
+            copyIn: true,
+            copyOut: false,
+            optional: true,
+        },
+    ];
+    const checkout = input.checkoutRoot?.trim();
+    if (checkout) {
+        bindings.push({
+            role: "checkout",
+            hostPath: checkout,
+            containerPath: `${SANDBOX_MOUNT_PATH}/checkout`,
+            shape: "directory",
+            copyIn: true,
+            copyOut: true,
+            optional: false,
+        });
+    }
+    const grants = input.grantedPaths ?? [];
+    for (let index = 0; index < grants.length; index += 1) {
+        const hostPath = grants[index];
+        bindings.push({
+            role: "grant",
+            hostPath,
+            containerPath: `${SANDBOX_MOUNT_PATH}/grants/${grantSegment(index, hostPath)}`,
+            shape: "mirror",
+            copyIn: true,
+            copyOut: true,
+            optional: false,
+        });
+    }
+    bindings.push({
+        role: "work",
+        hostPath: path.join(attemptDir, "work"),
+        containerPath: `${SANDBOX_MOUNT_PATH}/work`,
+        shape: "directory",
+        copyIn: false,
+        copyOut: true,
+        optional: true,
+    });
+    return { bindings };
+}
+function grantSegment(index, hostPath) {
+    const base = path.basename(hostPath).replace(/[^A-Za-z0-9_.-]/g, "_");
+    const safe = base.length > 0 && base !== "." && base !== ".." ? base : "path";
+    return `${index}-${safe}`;
+}
+async function pathExists(target) {
+    try {
+        await access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function populateSandboxDesk(params) {
+    const dirs = new Set([
+        `${SANDBOX_MOUNT_PATH}/artifacts`,
+        `${SANDBOX_MOUNT_PATH}/work`,
+        `${SANDBOX_MOUNT_PATH}/grants`,
+    ]);
+    for (const binding of params.desk.bindings) {
+        if (binding.role === "checkout" || binding.shape === "mirror") {
+            dirs.add(binding.containerPath);
+        }
+    }
+    const made = await execInSandboxContainer({
+        containerName: params.containerName,
+        dockerBin: params.dockerBin,
+        command: `mkdir -p -- ${[...dirs].map(shellQuote).join(" ")}`,
+    });
+    if (made.exitCode !== 0) {
+        throw new Error(`failed to prepare sandbox desk: ${made.stderr.trim() || made.stdout.trim() || `exit ${made.exitCode}`}`);
+    }
+    for (const binding of params.desk.bindings) {
+        if (!binding.copyIn)
+            continue;
+        if (!(await pathExists(binding.hostPath))) {
+            if (binding.optional)
+                continue;
+            throw new Error(`sandbox desk source missing: ${binding.hostPath}`);
+        }
+        await copyBindingIn(params, binding);
+    }
+}
+export async function syncSandboxDesk(params) {
+    for (const binding of params.desk.bindings) {
+        if (!binding.copyOut)
+            continue;
+        await copyBindingOut(params, binding);
+    }
+}
+async function copyBindingIn(params, binding) {
+    if (binding.shape === "file") {
+        await copyToSandboxContainer({
+            containerName: params.containerName,
+            dockerBin: params.dockerBin,
+            hostPath: binding.hostPath,
+            containerPath: binding.containerPath,
+        });
+        return;
+    }
+    if (binding.shape === "directory") {
+        await copyToSandboxContainer({
+            containerName: params.containerName,
+            dockerBin: params.dockerBin,
+            hostPath: binding.hostPath,
+            containerPath: binding.containerPath,
+            contents: true,
+        });
+        return;
+    }
+    const info = await stat(binding.hostPath);
+    if (info.isDirectory()) {
+        await copyToSandboxContainer({
+            containerName: params.containerName,
+            dockerBin: params.dockerBin,
+            hostPath: binding.hostPath,
+            containerPath: binding.containerPath,
+            contents: true,
+        });
+        return;
+    }
+    await copyToSandboxContainer({
+        containerName: params.containerName,
+        dockerBin: params.dockerBin,
+        hostPath: binding.hostPath,
+        containerPath: path.posix.join(binding.containerPath, path.basename(binding.hostPath)),
+    });
+}
+async function copyBindingOut(params, binding) {
+    if (binding.role === "checkout" || binding.role === "work") {
+        await mirrorDirectoryFromContainer(params, binding.containerPath, binding.hostPath);
+        return;
+    }
+    if (binding.shape === "directory") {
+        await mkdir(binding.hostPath, { recursive: true });
+        await copyFromSandboxContainer({
+            containerName: params.containerName,
+            dockerBin: params.dockerBin,
+            containerPath: binding.containerPath,
+            hostPath: binding.hostPath,
+            contents: true,
+        });
+        return;
+    }
+    const info = await stat(binding.hostPath);
+    if (info.isDirectory()) {
+        await mkdir(binding.hostPath, { recursive: true });
+        await copyFromSandboxContainer({
+            containerName: params.containerName,
+            dockerBin: params.dockerBin,
+            containerPath: binding.containerPath,
+            hostPath: binding.hostPath,
+            contents: true,
+        });
+        return;
+    }
+    await mkdir(path.dirname(binding.hostPath), { recursive: true });
+    await copyFromSandboxContainer({
+        containerName: params.containerName,
+        dockerBin: params.dockerBin,
+        containerPath: path.posix.join(binding.containerPath, path.basename(binding.hostPath)),
+        hostPath: binding.hostPath,
+    });
+}
+async function mirrorDirectoryFromContainer(params, containerPath, hostPath) {
+    let probe;
+    try {
+        probe = await execInSandboxContainer({
+            containerName: params.containerName,
+            dockerBin: params.dockerBin,
+            command: `test -d ${shellQuote(containerPath)}`,
+        });
+    }
+    catch (err) {
+        throw new Error(`sandbox desk directory unavailable, not replacing ${hostPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (probe.exitCode !== 0) {
+        throw new Error(`sandbox desk directory missing, not replacing ${hostPath}`);
+    }
+    await mkdir(path.dirname(hostPath), { recursive: true });
+    const staging = path.join(path.dirname(hostPath), `.${path.basename(hostPath)}.sf-sync-${randomBytes(4).toString("hex")}`);
+    await mkdir(staging);
+    try {
+        await copyFromSandboxContainer({
+            containerName: params.containerName,
+            dockerBin: params.dockerBin,
+            containerPath,
+            hostPath: staging,
+            contents: true,
+        });
+        await replaceDirectory(hostPath, staging);
+    }
+    catch (err) {
+        await rm(staging, { recursive: true, force: true });
+        throw err;
+    }
+}
+async function replaceDirectory(hostPath, staging) {
+    const backup = path.join(path.dirname(hostPath), `.${path.basename(hostPath)}.sf-sync-bak-${randomBytes(4).toString("hex")}`);
+    let hostMoved = false;
+    try {
+        if (await pathExists(hostPath)) {
+            await rename(hostPath, backup);
+            hostMoved = true;
+        }
+        await rename(staging, hostPath);
+        hostMoved = false;
+    }
+    catch (err) {
+        if (hostMoved && !(await pathExists(hostPath)) && (await pathExists(backup))) {
+            await rename(backup, hostPath);
+        }
+        throw err;
+    }
+    if (await pathExists(backup)) {
+        await rm(backup, { recursive: true, force: true });
+    }
+}

package/dist/runtime/sandboxFiles.d.ts

@@ -0,0 +1,20 @@
+import { type SandboxExecResult } from "./sandboxContainer.js";
+export declare class SandboxPathError extends Error {
+    constructor(message: string);
+}
+export declare function shellQuote(value: string): string;
+/** Resolve a tool path onto the sandbox mount. Host absolutes and `..` escapes are rejected. */
+export declare function confineSandboxPath(inputPath: string): string;
+export type SandboxFileTarget = {
+    containerName: string;
+    dockerBin?: string;
+};
+export declare function readSandboxFile(target: SandboxFileTarget, inputPath: string): Promise<string>;
+export declare function writeSandboxFile(target: SandboxFileTarget, inputPath: string, content: string): Promise<void>;
+export declare function editSandboxFile(target: SandboxFileTarget, inputPath: string, edits: readonly {
+    oldText: string;
+    newText: string;
+}[]): Promise<void>;
+export declare function sliceSandboxLines(text: string, offset?: number, limit?: number): string;
+export declare function formatSandboxBashResult(result: SandboxExecResult): string;
+export declare function runSandboxBash(target: SandboxFileTarget, command: string, timeoutMs?: number): Promise<string>;