open-managed-agents 0.1.0

package/dist/src/control-plane/sessions/pi/sandbox/docker.js

@@ -0,0 +1,1589 @@
+import { createHash, randomUUID } from "node:crypto";
+import { spawn, spawnSync } from "node:child_process";
+import { mkdir, mkdtemp, open, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { posix } from "node:path";
+import { join as joinHostPath } from "node:path";
+import { CMA_GLOB_READY_MARKER, CmaGlobReadinessFilter, CmaGlobStreamCollector, cmaGlobToRipgrepGlob, compileCmaGlob, } from "./cma-glob.js";
+import { CMA_GREP_READY_MARKER, CmaGrepStreamCollector, } from "./cma-grep.js";
+import { matchGlob } from "./glob.js";
+import { createEgressSidecar, egressProxyUrl, reapEgressSidecars, } from "./docker-egress.js";
+import { createSandboxInvocationStats, createSandboxToolDefinitions, recordSandboxInvocation, } from "./provider.js";
+import { MAX_SESSION_OUTPUT_BYTES, MAX_SESSION_OUTPUT_FILE_BYTES, MAX_SESSION_OUTPUT_FILES, } from "../../../files/types.js";
+import { DEFAULT_OMA_SANDBOX_IMAGE } from "./image.js";
+export const DEFAULT_DOCKER_SANDBOX_IMAGE = DEFAULT_OMA_SANDBOX_IMAGE;
+const DEFAULT_WORKSPACE = "/workspace";
+const DEFAULT_UPLOADS_PATH = "/mnt/session/uploads";
+const DEFAULT_OUTPUTS_PATH = "/mnt/session/outputs";
+const DEFAULT_SKILLS_PATH = "/workspace/skills";
+const DEFAULT_MEMORY = "1g";
+const DEFAULT_CPUS = "1";
+const DEFAULT_PIDS_LIMIT = "128";
+const DEFAULT_TMPFS_SIZE = "256m";
+const DEFAULT_OUTPUTS_TMPFS_SIZE = "100m";
+const DEFAULT_OPERATION_TIMEOUT_MS = 10_000;
+export const DEFAULT_DOCKER_STARTUP_TIMEOUT_MS = 5 * 60_000;
+const SANDBOX_LABEL_KEY = "open-managed-agents.sandbox";
+const SANDBOX_LABEL_VALUE = "docker-local";
+const OWNER_LABEL_KEY = "open-managed-agents.owner";
+const OWNER_LABEL_VALUE = "open-managed-agents";
+const BASH_DISPATCH_PREFIX = "__OMA_DISPATCHED__:";
+const BASH_TERMINAL_PREFIX = "__OMA_TERMINAL__:";
+export function createDockerSandboxProviderFactory(opts = {}) {
+    const { egress: egressConfig, ...baseOpts } = opts;
+    let swept = false;
+    let sweepPromise;
+    return async (workspaceId, sessionId, context) => {
+        if (!swept && opts.reapStaleContainersOlderThanMs !== undefined) {
+            const olderThanMs = opts.reapStaleContainersOlderThanMs;
+            sweepPromise ??= reapDockerSandboxContainers({
+                dockerCommand: opts.dockerCommand,
+                olderThanMs,
+            }).then((count) => {
+                if (count > 0)
+                    opts.onReaped?.(count);
+                // Same startup sweep reaps egress sidecars a crash orphaned:
+                // containers, their --internal networks, and stale temp roots.
+                reapEgressSidecars({ dockerCommand: opts.dockerCommand, olderThanMs });
+                swept = true;
+            }, (error) => {
+                sweepPromise = undefined;
+                throw error;
+            });
+            await sweepPromise;
+        }
+        const egress = egressConfig
+            ? await createSessionEgress(workspaceId, sessionId, egressConfig, baseOpts, context)
+            : undefined;
+        try {
+            return await createDockerSandboxProvider(workspaceId, sessionId, {
+                ...baseOpts,
+                ...(egress === undefined ? {} : { egress }),
+            });
+        }
+        catch (error) {
+            // createDockerSandboxProvider disposes on its own run failure, but a
+            // throw before that point (option validation) would leak the sidecar.
+            // dispose() is idempotent, so the overlap is harmless.
+            egress?.dispose();
+            throw error;
+        }
+    };
+}
+/**
+ * Resolve the session's egress bundle and, when the environment grants
+ * egress, stand up the per-session sidecar (plan 0117e-3). Returns undefined
+ * for a no-egress environment — the sandbox stays at --network none.
+ */
+async function createSessionEgress(workspaceId, sessionId, egressConfig, baseOpts, context) {
+    const resolved = await egressConfig.resolveEgressBundle(workspaceId, sessionId, context);
+    if (resolved === undefined)
+        return undefined;
+    const sidecar = await createEgressSidecar({
+        dockerCommand: baseOpts.dockerCommand ?? "docker",
+        sessionId,
+        bundle: resolved.bundle,
+        sidecarImage: egressConfig.sidecarImage,
+        ...(egressConfig.sidecarRepoMount === undefined
+            ? {}
+            : { sidecarRepoMount: egressConfig.sidecarRepoMount }),
+        operationTimeoutMs: baseOpts.operationTimeoutMs ?? DEFAULT_OPERATION_TIMEOUT_MS,
+    });
+    return {
+        wiring: {
+            networkName: sidecar.networkName,
+            caCertDirHostPath: sidecar.sharedDirHostPath,
+            proxyUrl: egressProxyUrl(sidecar),
+            sandboxEnv: resolved.sandboxEnv,
+        },
+        dispose: sidecar.dispose,
+    };
+}
+export async function createDockerSandboxProvider(workspaceId, sessionId, opts = {}) {
+    const resolved = resolveDockerOptions(opts);
+    const containerName = dockerContainerName(resolved.containerNamePrefix, workspaceId, sessionId);
+    try {
+        await dockerChecked(resolved.dockerCommand, buildDockerRunArgs({
+            containerName,
+            workspacePath: resolved.workspacePath,
+            uploadsPath: resolved.uploadsPath,
+            outputsPath: resolved.outputsPath,
+            image: resolved.image,
+            memory: resolved.memory,
+            cpus: resolved.cpus,
+            pidsLimit: resolved.pidsLimit,
+            tmpfsSize: resolved.tmpfsSize,
+            outputsTmpfsSize: resolved.outputsTmpfsSize,
+            egress: opts.egress?.wiring,
+            labels: {
+                [SANDBOX_LABEL_KEY]: SANDBOX_LABEL_VALUE,
+                [OWNER_LABEL_KEY]: OWNER_LABEL_VALUE,
+                "open-managed-agents.workspace-id": workspaceId,
+                "open-managed-agents.session-id": sessionId,
+                "open-managed-agents.created-at": new Date().toISOString(),
+                ...resolved.extraLabels,
+            },
+        }), { timeoutMs: resolved.startupTimeoutMs });
+    }
+    catch (error) {
+        // Sandbox creation failed after the sidecar was already stood up. The
+        // provider whose dispose() tears the sidecar down is never returned, so
+        // dispose here — else the sidecar container and its resolved-secret bundle
+        // on disk leak.
+        opts.egress?.dispose();
+        throw error;
+    }
+    const invocations = createSandboxInvocationStats();
+    const disposed = { value: false };
+    const activeDockerExecPids = new Set();
+    let disposeAttempted = false;
+    let poisoned = false;
+    let poisonPromise;
+    const disposeInfrastructure = () => {
+        if (disposeAttempted)
+            return;
+        disposeAttempted = true;
+        disposed.value = true;
+        for (const pid of activeDockerExecPids)
+            killProcessGroup(pid);
+        forceRemoveDockerContainer(resolved.dockerCommand, containerName);
+        opts.egress?.dispose();
+    };
+    const poisonInfrastructure = () => {
+        poisoned = true;
+        disposed.value = true;
+        if (poisonPromise)
+            return poisonPromise;
+        poisonPromise = (async () => {
+            for (const pid of activeDockerExecPids)
+                killProcessGroup(pid);
+            await removeDockerContainerChecked(resolved.dockerCommand, containerName, resolved.operationTimeoutMs);
+            disposeAttempted = true;
+            opts.egress?.dispose();
+        })();
+        return poisonPromise;
+    };
+    const dockerShell = (command, execOpts = {}) => dockerChecked(resolved.dockerCommand, buildDockerExecShellArgs(containerName, command.script, command.args, {
+        interactive: command.interactive ?? command.input !== undefined,
+        timeoutSeconds: execOpts.guestTimeout === false
+            ? undefined
+            : (execOpts.timeoutMs ?? resolved.operationTimeoutMs) / 1000,
+        workdir: resolved.workspacePath,
+    }), {
+        ...execOpts,
+        input: execOpts.input ?? command.input,
+        activePids: activeDockerExecPids,
+        timeoutMs: execOpts.timeoutMs ?? resolved.operationTimeoutMs,
+    });
+    const dockerExists = async (absolutePath) => {
+        const command = buildDockerExistsCommand(absolutePath);
+        const result = await dockerExec(resolved.dockerCommand, buildDockerExecShellArgs(containerName, command.script, command.args, {
+            timeoutSeconds: resolved.operationTimeoutMs / 1000,
+            workdir: resolved.workspacePath,
+        }), {
+            activePids: activeDockerExecPids,
+            timeoutMs: resolved.operationTimeoutMs,
+        });
+        if (result.exitCode === 0)
+            return true;
+        throwIfUnexpectedBoundedExit(result, "docker exists", new Set([1]));
+        return false;
+    };
+    await dockerShell(buildDockerCmaGrepPreflightCommand(), {
+        timeoutMs: 3_000,
+        guestTimeout: false,
+    });
+    const materializeFileResources = async (mounts) => {
+        if (mounts.length === 0)
+            return;
+        recordSandboxNotDisposed(disposed);
+        for (const kind of ["upload", "skill"]) {
+            const selected = mounts.filter((mount) => mount.kind === kind);
+            if (selected.length === 0)
+                continue;
+            const destination = kind === "upload" ? resolved.uploadsPath : DEFAULT_SKILLS_PATH;
+            const tempRoot = await mkdtemp(joinHostPath(tmpdir(), "oma-session-mounts-"));
+            try {
+                if (kind === "skill") {
+                    await dockerChecked(resolved.dockerCommand, ["exec", "--user", "65534:65534", containerName, "chmod", "711", resolved.workspacePath], { timeoutMs: resolved.operationTimeoutMs });
+                }
+                for (const mount of selected) {
+                    const relativePath = assertInsideMountRoot(mount.mountPath, destination);
+                    await writeMountFile(tempRoot, relativePath, mount);
+                }
+                // Docker exec timeout only owns the local Docker CLI process; the
+                // caller must dispose the container on materialization failure so any
+                // in-container tar/chown work cannot leak a half-mounted sandbox.
+                await dockerChecked(resolved.dockerCommand, buildDockerExtractIntoContainerArgs(containerName, destination), {
+                    input: createTarArchive(tempRoot),
+                    timeoutMs: resolved.operationTimeoutMs,
+                });
+                await dockerChecked(resolved.dockerCommand, kind === "upload" ? buildDockerNormalizeUploadsArgs(containerName, destination) : buildDockerNormalizeSkillsArgs(containerName, destination), { timeoutMs: resolved.operationTimeoutMs });
+            }
+            finally {
+                if (kind === "skill") {
+                    await dockerChecked(resolved.dockerCommand, ["exec", "--user", "65534:65534", containerName, "chmod", "700", resolved.workspacePath], { timeoutMs: resolved.operationTimeoutMs });
+                }
+                await rm(tempRoot, { force: true, recursive: true });
+            }
+        }
+    };
+    const collectOutputFiles = async () => {
+        recordSandboxNotDisposed(disposed);
+        const listing = await dockerShell(buildDockerOutputListingCommand(resolved.outputsPath, {
+            maxFiles: resolved.maxOutputFiles,
+            maxFileBytes: resolved.maxOutputFileBytes,
+            maxBytes: resolved.maxOutputBytes,
+        }));
+        const records = parseOutputListing(listing.stdout);
+        return records.map((record) => {
+            const absolutePath = assertInsideDockerOutputPath(posix.join(resolved.outputsPath, record.relativePath), resolved.outputsPath);
+            return {
+                relativePath: record.relativePath,
+                filename: posix.basename(record.relativePath),
+                mimeType: mimeTypeForFilename(record.relativePath),
+                sizeBytes: record.sizeBytes,
+                sha256: record.sha256,
+                bytes: dockerOutputBytes(() => dockerShell(buildDockerReadFileCommand(absolutePath), {
+                    maxStdoutBytes: resolved.maxOutputFileBytes,
+                })),
+            };
+        });
+    };
+    const readOps = {
+        access: async (absolutePath) => {
+            recordSandboxInvocation(invocations, disposed, "read");
+            const path = assertInsideDockerWorkspace(absolutePath, resolved.workspacePath);
+            await dockerShell(buildDockerFileAccessCommand(path, "read"));
+        },
+        readFile: async (absolutePath) => {
+            recordSandboxInvocation(invocations, disposed, "read");
+            const path = assertInsideDockerWorkspace(absolutePath, resolved.workspacePath);
+            return (await dockerShell(buildDockerReadFileCommand(path))).stdout;
+        },
+    };
+    const writeOps = {
+        mkdir: async (dir) => {
+            recordSandboxInvocation(invocations, disposed, "write");
+            const path = assertInsideDockerWorkspace(dir, resolved.workspacePath);
+            await dockerShell(buildDockerMkdirCommand(path));
+        },
+        writeFile: async (absolutePath, content) => {
+            recordSandboxInvocation(invocations, disposed, "write");
+            const path = assertInsideDockerWorkspace(absolutePath, resolved.workspacePath);
+            await dockerShell(buildDockerWriteFileCommand(path, content));
+        },
+    };
+    const editOps = {
+        access: async (absolutePath) => {
+            recordSandboxInvocation(invocations, disposed, "edit");
+            const path = assertInsideDockerWorkspace(absolutePath, resolved.workspacePath);
+            await dockerShell(buildDockerFileAccessCommand(path, "edit"));
+        },
+        readFile: async (absolutePath) => {
+            recordSandboxInvocation(invocations, disposed, "edit");
+            const path = assertInsideDockerWorkspace(absolutePath, resolved.workspacePath);
+            return (await dockerShell(buildDockerReadFileCommand(path))).stdout;
+        },
+        writeFile: async (absolutePath, content) => {
+            recordSandboxInvocation(invocations, disposed, "edit");
+            const path = assertInsideDockerWorkspace(absolutePath, resolved.workspacePath);
+            await dockerShell(buildDockerWriteFileCommand(path, content));
+        },
+    };
+    const findOps = {
+        exists: async (absolutePath) => {
+            recordSandboxInvocation(invocations, disposed, "find");
+            const path = assertInsideDockerWorkspace(absolutePath, resolved.workspacePath);
+            return dockerExists(path);
+        },
+        glob: async (pattern, cwd, options) => {
+            recordSandboxInvocation(invocations, disposed, "find");
+            const root = assertInsideDockerWorkspace(cwd, resolved.workspacePath);
+            const result = await dockerShell(buildDockerGlobEnumerationCommand(root, options.ignore));
+            const files = result.stdout
+                .toString("utf8")
+                .split("\n")
+                .filter(Boolean);
+            return matchGlob(files, pattern, {
+                ignore: options.ignore,
+                limit: options.limit,
+            }).map((rel) => posix.join(root, rel));
+        },
+    };
+    const globOps = {
+        glob: async ({ pattern, cwd, signal, maxMatches, maxRawBytes, maxOutputBytes, outputBase, timeoutMs }) => {
+            recordSandboxInvocation(invocations, disposed, "glob");
+            const root = assertInsideDockerWorkspace(cwd, resolved.workspacePath);
+            if (signal.aborted)
+                throw new Error("Operation aborted");
+            const controller = new AbortController();
+            const ownershipToken = `oma-glob-${randomUUID()}`;
+            const protocolBytes = Buffer.byteLength(CMA_GLOB_READY_MARKER, "utf8") + 1;
+            const abortFromCaller = () => controller.abort();
+            signal.addEventListener("abort", abortFromCaller, { once: true });
+            let streamError;
+            const readiness = new CmaGlobReadinessFilter(CMA_GLOB_READY_MARKER);
+            const collector = new CmaGlobStreamCollector(compileCmaGlob(pattern), {
+                root,
+                maxMatches,
+                maxRawBytes,
+                maxOutputBytes,
+                join: posix.join,
+                formatForOutput: outputBase === undefined
+                    ? undefined
+                    : (absolutePath) => posix.relative(outputBase, absolutePath),
+                onLimit: () => controller.abort(),
+            });
+            try {
+                await dockerShell(buildDockerCmaGlobEnumerationCommand(root, ownershipToken), {
+                    signal: controller.signal,
+                    timeoutMs,
+                    guestTimeout: false,
+                    // Transport framing is bounded separately; the collector applies the
+                    // caller-visible raw filename limit after removing readiness bytes.
+                    // Node may deliver readiness plus more than the public raw allowance
+                    // in one pipe chunk. Leave one bounded chunk of transport slack so
+                    // the readiness filter and collector, rather than the transport,
+                    // classify that data. The collector still enforces maxRawBytes.
+                    maxStdoutBytes: maxRawBytes + protocolBytes + 64 * 1024,
+                    maxCombinedBytes: maxRawBytes + protocolBytes + 128 * 1024,
+                    onStdout: (chunk) => {
+                        try {
+                            const filenames = readiness.push(chunk);
+                            if (filenames)
+                                collector.push(filenames);
+                        }
+                        catch (error) {
+                            streamError = error;
+                            controller.abort();
+                        }
+                    },
+                });
+                if (streamError)
+                    throw streamError;
+                if (signal.aborted)
+                    throw new Error("Operation aborted");
+                readiness.assertReady();
+                collector.finish();
+            }
+            catch (error) {
+                if (streamError)
+                    throw streamError;
+                if (signal.aborted)
+                    throw new Error("Operation aborted");
+                if (!collector.limitReached)
+                    throw error;
+            }
+            finally {
+                try {
+                    if (!readiness.ready) {
+                        // Any terminal path before a positive dispatch acknowledgement is
+                        // ambiguous. Verified container removal is the only fail-closed
+                        // guarantee that delayed guest work cannot appear afterward.
+                        await poisonInfrastructure();
+                    }
+                    else {
+                        try {
+                            await dockerShell(buildDockerCmaGlobCleanupCommand(ownershipToken), {
+                                timeoutMs: 3_000,
+                                guestTimeout: false,
+                            });
+                        }
+                        catch (cleanupError) {
+                            // Readiness proves dispatch, not successful termination. If the
+                            // token-scoped cleanup cannot prove the guest process is gone,
+                            // destroy the isolation boundary before returning the error.
+                            await poisonInfrastructure();
+                            throw cleanupError;
+                        }
+                    }
+                }
+                finally {
+                    signal.removeEventListener("abort", abortFromCaller);
+                }
+            }
+            if (signal.aborted)
+                throw new Error("Operation aborted");
+            return collector.matches;
+        },
+    };
+    const grepOps = {
+        grep: async ({ pattern, cwd, signal, glob, headLimit, maxRawBytes, maxOutputBytes, outputBase, timeoutMs }) => {
+            recordSandboxInvocation(invocations, disposed, "grep");
+            const root = assertInsideDockerSearchRoot(cwd, [
+                resolved.workspacePath,
+                resolved.uploadsPath,
+                DEFAULT_SKILLS_PATH,
+            ]);
+            if (signal.aborted)
+                throw new Error("Operation aborted");
+            const controller = new AbortController();
+            const protocolBytes = Buffer.byteLength(CMA_GREP_READY_MARKER, "utf8") + 1;
+            const abortFromCaller = () => controller.abort();
+            signal.addEventListener("abort", abortFromCaller, { once: true });
+            let streamError;
+            const ownershipToken = `oma-grep-${randomUUID()}`;
+            const readiness = new CmaGlobReadinessFilter(CMA_GREP_READY_MARKER);
+            const collector = new CmaGrepStreamCollector({
+                root,
+                maxMatches: headLimit,
+                maxRawBytes,
+                maxOutputBytes,
+                join: posix.join,
+                formatForOutput: outputBase === undefined
+                    ? undefined
+                    : (absolutePath) => posix.relative(outputBase, absolutePath),
+                onLimit: () => controller.abort(),
+            });
+            try {
+                try {
+                    await dockerShell(buildDockerCmaGrepSearchCommand(root, ownershipToken, pattern, glob), {
+                        signal: controller.signal,
+                        timeoutMs,
+                        guestTimeout: false,
+                        maxStdoutBytes: maxRawBytes + protocolBytes + 64 * 1024,
+                        maxCombinedBytes: maxRawBytes + protocolBytes + 128 * 1024,
+                        onStdout: (chunk) => {
+                            try {
+                                const filenames = readiness.push(chunk);
+                                if (filenames)
+                                    collector.push(filenames);
+                            }
+                            catch (error) {
+                                streamError = error;
+                                controller.abort();
+                            }
+                        },
+                    });
+                    if (streamError)
+                        throw streamError;
+                    if (signal.aborted)
+                        throw new Error("Operation aborted");
+                    readiness.assertReady();
+                    collector.finish();
+                }
+                catch (error) {
+                    if (streamError)
+                        throw streamError;
+                    if (signal.aborted)
+                        throw new Error("Operation aborted");
+                    if (!collector.limitReached)
+                        throw error;
+                }
+                finally {
+                    if (!readiness.ready) {
+                        await poisonInfrastructure();
+                    }
+                    else {
+                        try {
+                            await dockerShell(buildDockerCmaGrepCleanupCommand(ownershipToken), {
+                                timeoutMs: 3_000,
+                                guestTimeout: false,
+                            });
+                        }
+                        catch (cleanupError) {
+                            await poisonInfrastructure();
+                            throw cleanupError;
+                        }
+                    }
+                }
+                if (signal.aborted)
+                    throw new Error("Operation aborted");
+                return collector.matches;
+            }
+            finally {
+                signal.removeEventListener("abort", abortFromCaller);
+            }
+        },
+    };
+    const lsOps = {
+        exists: async (absolutePath) => {
+            recordSandboxInvocation(invocations, disposed, "ls");
+            const path = assertInsideDockerWorkspace(absolutePath, resolved.workspacePath);
+            return dockerExists(path);
+        },
+        stat: async (absolutePath) => {
+            recordSandboxInvocation(invocations, disposed, "ls");
+            const path = assertInsideDockerWorkspace(absolutePath, resolved.workspacePath);
+            const result = await dockerShell(buildDockerStatCommand(path));
+            const kind = result.stdout.toString("utf8");
+            return { isDirectory: () => kind === "directory" };
+        },
+        readdir: async (absolutePath) => {
+            recordSandboxInvocation(invocations, disposed, "ls");
+            const path = assertInsideDockerWorkspace(absolutePath, resolved.workspacePath);
+            const result = await dockerShell(buildDockerReaddirCommand(path));
+            return result.stdout.toString("utf8").split("\n").filter(Boolean);
+        },
+    };
+    const bashOps = {
+        exec: async (command, cwd, options) => {
+            recordSandboxInvocation(invocations, disposed, "bash");
+            const path = assertInsideDockerWorkspace(cwd, resolved.workspacePath);
+            const timeoutSeconds = options.timeout !== undefined && options.timeout > 0
+                ? options.timeout
+                : resolved.operationTimeoutMs / 1000;
+            const execId = randomExecId();
+            const dispatchToken = randomExecId();
+            const pidFile = posix.join(resolved.workspacePath, `.oma-exec-${execId}.pid`);
+            const shellCommand = buildDockerBashCommand(command, timeoutSeconds, pidFile, dispatchToken);
+            const dispatchFilter = createBashDispatchFilter(dispatchToken);
+            try {
+                const result = await dockerExec(resolved.dockerCommand, buildDockerExecShellArgs(containerName, shellCommand.script, shellCommand.args, {
+                    workdir: path,
+                    env: filterDockerEnv(options.env ?? {}, resolved.envAllowlist),
+                }), {
+                    activePids: activeDockerExecPids,
+                    onAbort: () => {
+                        killInContainerProcessGroup(resolved.dockerCommand, containerName, pidFile);
+                    },
+                    onStderr: (chunk) => {
+                        const forwarded = dispatchFilter.stderr(chunk);
+                        if (forwarded.length > 0)
+                            options.onData(forwarded);
+                    },
+                    onStdout: (chunk) => {
+                        const forwarded = dispatchFilter.stdout(chunk);
+                        if (forwarded.length > 0)
+                            options.onData(forwarded);
+                    },
+                    signal: options.signal,
+                    timeoutMs: Math.ceil(timeoutSeconds * 1000) + 2_000,
+                });
+                if (!dispatchFilter.dispatchSeen()) {
+                    throw new Error("docker bash failed before command dispatch");
+                }
+                const terminal = dispatchFilter.terminalRecord();
+                if (terminal === undefined) {
+                    throw new Error("docker bash failed before command completion");
+                }
+                if (result.exitCode !==
+                    (terminal.kind === "timeout" ? 137 : terminal.exitCode)) {
+                    throw new Error("docker bash exit disagreed with command completion");
+                }
+                if (terminal.kind === "timeout") {
+                    throw new DockerTimeoutError();
+                }
+                return { exitCode: terminal.exitCode };
+            }
+            catch (error) {
+                if (error instanceof DockerTimeoutError) {
+                    throw new Error(`timeout:${timeoutSeconds}`);
+                }
+                throw error;
+            }
+        },
+    };
+    const operations = {
+        bash: bashOps,
+        read: readOps,
+        write: writeOps,
+        edit: editOps,
+        find: findOps,
+        glob: globOps,
+        grep: grepOps,
+        ls: lsOps,
+    };
+    return {
+        cwd: resolved.workspacePath,
+        collectOutputFiles,
+        invocations,
+        materializeFileResources,
+        operations,
+        toolNames: new Set(["bash", "read", "write", "edit", "glob", "grep", "ls"]),
+        tools: createSandboxToolDefinitions(resolved.workspacePath, operations, invocations, disposed),
+        isPoisoned: () => poisoned,
+        dispose: disposeInfrastructure,
+    };
+}
+const SANDBOX_CA_MOUNT = "/etc/oma";
+const SANDBOX_CA_CERT_PATH = "/etc/oma/ca.crt";
+export function buildDockerRunArgs(opts) {
+    assertTmpfsMemoryHeadroom(opts.memory, opts.tmpfsSize, opts.outputsTmpfsSize ?? opts.tmpfsSize, opts.tmpfsSize);
+    const labels = Object.entries(opts.labels ?? {}).flatMap(([key, value]) => [
+        "--label",
+        `${key}=${value}`,
+    ]);
+    const uploadsPath = opts.uploadsPath ?? DEFAULT_UPLOADS_PATH;
+    const outputsPath = opts.outputsPath ?? DEFAULT_OUTPUTS_PATH;
+    const outputsTmpfsSize = opts.outputsTmpfsSize ?? DEFAULT_OUTPUTS_TMPFS_SIZE;
+    // Default deny (ADR 0016 §2): no egress wiring -> --network none, no proxy.
+    const network = opts.egress ? opts.egress.networkName : "none";
+    const egressArgs = opts.egress ? buildEgressRunArgs(opts.egress) : [];
+    return [
+        "run",
+        "-d",
+        "--name",
+        opts.containerName,
+        ...labels,
+        "--network",
+        network,
+        ...egressArgs,
+        "--cpus",
+        opts.cpus,
+        "--memory",
+        opts.memory,
+        "--pids-limit",
+        opts.pidsLimit,
+        "--cap-drop",
+        "ALL",
+        "--security-opt",
+        "no-new-privileges",
+        "--read-only",
+        "--tmpfs",
+        `${opts.workspacePath}:rw,exec,nosuid,nodev,uid=65534,gid=65534,mode=700,size=${opts.tmpfsSize}`,
+        "--tmpfs",
+        `${uploadsPath}:rw,nosuid,nodev,noexec,mode=755,size=${opts.tmpfsSize}`,
+        "--tmpfs",
+        `${outputsPath}:rw,nosuid,nodev,noexec,uid=65534,gid=65534,mode=700,size=${outputsTmpfsSize}`,
+        "--tmpfs",
+        `${DEFAULT_SKILLS_PATH}:rw,exec,nosuid,nodev,uid=0,gid=0,mode=755,size=${opts.tmpfsSize}`,
+        "--workdir",
+        opts.workspacePath,
+        "--user",
+        "65534:65534",
+        opts.image,
+        "tail",
+        "-f",
+        "/dev/null",
+    ];
+}
+// Trust bundle + proxy env for an egress-granted sandbox. The trust vars point
+// at the sidecar's CA so the proxy can terminate TLS; the proxy vars route the
+// sandbox's HTTP clients through it. Trust/proxy vars win over sentinels so a
+// user-named sentinel cannot shadow the boundary wiring.
+function buildEgressRunArgs(egress) {
+    const env = {
+        ...egress.sandboxEnv,
+        SSL_CERT_FILE: SANDBOX_CA_CERT_PATH,
+        NODE_EXTRA_CA_CERTS: SANDBOX_CA_CERT_PATH,
+        GIT_SSL_CAINFO: SANDBOX_CA_CERT_PATH,
+        CURL_CA_BUNDLE: SANDBOX_CA_CERT_PATH,
+        REQUESTS_CA_BUNDLE: SANDBOX_CA_CERT_PATH,
+        // Git/libcurl does not reliably negotiate the sidecar's Basic proxy auth
+        // from the URL alone and otherwise reports "Proxy CONNECT aborted". Pin
+        // only the proxy auth method; the credential remains the per-session URL.
+        GIT_CONFIG_COUNT: "1",
+        GIT_CONFIG_KEY_0: "http.proxyAuthMethod",
+        GIT_CONFIG_VALUE_0: "basic",
+        HTTPS_PROXY: egress.proxyUrl,
+        HTTP_PROXY: egress.proxyUrl,
+        https_proxy: egress.proxyUrl,
+        http_proxy: egress.proxyUrl,
+    };
+    return [
+        "-v",
+        `${egress.caCertDirHostPath}:${SANDBOX_CA_MOUNT}:ro`,
+        ...Object.entries(env).flatMap(([k, v]) => ["--env", `${k}=${v}`]),
+    ];
+}
+export function buildDockerExtractIntoContainerArgs(containerName, destinationDirectory) {
+    return [
+        "exec",
+        "-i",
+        "--user",
+        "0:0",
+        containerName,
+        "tar",
+        "--no-same-owner",
+        "-C",
+        destinationDirectory,
+        "-xf",
+        "-",
+    ];
+}
+export function buildDockerNormalizeUploadsArgs(containerName, uploadsPath) {
+    return [
+        "exec",
+        "--user",
+        "0:0",
+        containerName,
+        "sh",
+        "-c",
+        "chown -R 0:0 \"$1\" && find \"$1\" -type d -exec chmod 755 {} + && find \"$1\" -type f -exec chmod 644 {} +",
+        "sh",
+        uploadsPath,
+    ];
+}
+export function buildDockerNormalizeSkillsArgs(containerName, skillsPath) {
+    return ["exec", "--user", "0:0", containerName, "sh", "-c", "chown -R 0:0 \"$1\" && find \"$1\" -type d -exec chmod 755 {} + && find \"$1\" -type f -exec chmod 644 {} + && find \"$1\" -path '*/scripts/*' -type f -exec chmod 755 {} +", "sh", skillsPath];
+}
+export function buildDockerExecShellArgs(containerName, script, args, opts = {}) {
+    const out = ["exec"];
+    if (opts.interactive)
+        out.push("-i");
+    if (opts.workdir)
+        out.push("--workdir", opts.workdir);
+    for (const [key, value] of Object.entries(opts.env ?? {})) {
+        if (value !== undefined)
+            out.push("--env", `${key}=${value}`);
+    }
+    if (opts.timeoutSeconds !== undefined && opts.timeoutSeconds > 0) {
+        out.push(containerName, "bash", "-lc", "timeout -s KILL \"$1\" bash -lc \"$2\" bash \"${@:3}\"", "bash", String(opts.timeoutSeconds), script, ...args);
+    }
+    else {
+        out.push(containerName, "bash", "-lc", script, "bash", ...args);
+    }
+    return out;
+}
+export function buildDockerBashCommand(command, timeoutSeconds, pidFile, dispatchToken = "") {
+    return {
+        script: [
+            "pidfile=\"$1\"",
+            "timeout_secs=\"$2\"",
+            "command=\"$3\"",
+            "dispatch_token=\"$4\"",
+            "printf '%s\\n' \"__OMA_DISPATCHED__:${dispatch_token}\"",
+            "terminal_exit() { printf '%s\\n' \"__OMA_TERMINAL__:${dispatch_token}:exit:$1\"; }",
+            "terminal_timeout() { printf '%s\\n' \"__OMA_TERMINAL__:${dispatch_token}:timeout:137\"; }",
+            "timer_file=\"${pidfile}.timer\"",
+            "rm -f \"$timer_file\"",
+            "setsid bash -lc \"$command\" &",
+            "pid=$!",
+            "printf '%s' \"$pid\" > \"$pidfile\"",
+            "setsid sleep \"$timeout_secs\" &",
+            "timer=$!",
+            "printf '%s' \"$timer\" > \"$timer_file\"",
+            "wait -n -p completed \"$pid\" \"$timer\"",
+            "status=$?",
+            "if [ \"${completed:-}\" = \"$timer\" ]; then",
+            "  kill -KILL \"-$pid\" 2>/dev/null || kill -KILL \"$pid\" 2>/dev/null || true",
+            "  wait \"$pid\" 2>/dev/null || true",
+            "  rm -f \"$pidfile\" \"$timer_file\"",
+            "  terminal_timeout",
+            "  exit 137",
+            "fi",
+            "kill \"$timer\" 2>/dev/null || true",
+            "wait \"$timer\" 2>/dev/null || true",
+            "rm -f \"$pidfile\" \"$timer_file\"",
+            "terminal_exit \"$status\"",
+            "exit \"$status\"",
+        ].join("\n"),
+        args: [pidFile, String(timeoutSeconds), command, dispatchToken],
+    };
+}
+export function buildDockerFileAccessCommand(absolutePath, mode) {
+    return {
+        script: mode === "read"
+            ? "test -r \"$1\" -a -f \"$1\""
+            : "test -r \"$1\" -a -w \"$1\" -a -f \"$1\"",
+        args: [absolutePath],
+    };
+}
+export function buildDockerReadFileCommand(absolutePath) {
+    return { script: "cat \"$1\"", args: [absolutePath] };
+}
+export function buildDockerWriteFileCommand(absolutePath, content) {
+    return {
+        script: "cat > \"$1\"",
+        args: [absolutePath],
+        input: content,
+        interactive: true,
+    };
+}
+export function buildDockerMkdirCommand(dir) {
+    return { script: "mkdir -p \"$1\"", args: [dir] };
+}
+export function buildDockerExistsCommand(absolutePath) {
+    return { script: "test -e \"$1\"", args: [absolutePath] };
+}
+export function buildDockerStatCommand(absolutePath) {
+    return {
+        script: "if [ -d \"$1\" ]; then printf directory; elif [ -e \"$1\" ]; then printf file; else exit 1; fi",
+        args: [absolutePath],
+    };
+}
+export function buildDockerReaddirCommand(absolutePath) {
+    return { script: "ls -1A \"$1\"", args: [absolutePath] };
+}
+export function buildDockerCmaGlobCleanupCommand(ownershipToken) {
+    return {
+        script: [
+            "pids=''",
+            "for f in /proc/[0-9]*/environ; do",
+            "  pid=${f#/proc/}; pid=${pid%/environ}",
+            "  if tr '\\0' '\\n' < \"$f\" 2>/dev/null | grep -Fqx \"OMA_GLOB_OWNER=$1\"; then",
+            "    start=$(awk '{print $22}' \"/proc/$pid/stat\" 2>/dev/null || true)",
+            "    case \"$start\" in ''|*[!0-9]*) :;; *) pids=\"$pids $pid:$start\";; esac",
+            "  fi",
+            "done",
+            "for entry in $pids; do",
+            "  pid=${entry%%:*}; start=${entry#*:}",
+            "  current=$(awk '{print $22}' \"/proc/$pid/stat\" 2>/dev/null || true)",
+            "  if [ \"$current\" = \"$start\" ] && tr '\\0' '\\n' < \"/proc/$pid/environ\" 2>/dev/null | grep -Fqx \"OMA_GLOB_OWNER=$1\"; then",
+            "    kill -KILL \"-$pid\" 2>/dev/null || kill -KILL \"$pid\" 2>/dev/null || true",
+            "  fi",
+            "done",
+            "attempt=0",
+            "while [ -n \"$pids\" ] && [ \"$attempt\" -lt 40 ]; do",
+            "  remaining=''",
+            "  for entry in $pids; do",
+            "    pid=${entry%%:*}; start=${entry#*:}",
+            "    current=$(awk '{print $22}' \"/proc/$pid/stat\" 2>/dev/null || true)",
+            "    if [ \"$current\" = \"$start\" ] && tr '\\0' '\\n' < \"/proc/$pid/environ\" 2>/dev/null | grep -Fqx \"OMA_GLOB_OWNER=$1\"; then remaining=\"$remaining $entry\"; fi",
+            "  done",
+            "  pids=$remaining",
+            "  [ -z \"$pids\" ] && break",
+            "  attempt=$((attempt + 1)); sleep 0.05",
+            "done",
+            "[ -z \"$pids\" ]",
+        ].join("\n"),
+        args: [ownershipToken],
+    };
+}
+export function buildDockerCmaGrepCleanupCommand(ownershipToken) {
+    return {
+        script: [
+            "pids=''",
+            "for f in /proc/[0-9]*/environ; do",
+            "  pid=${f#/proc/}; pid=${pid%/environ}",
+            "  if tr '\\0' '\\n' < \"$f\" 2>/dev/null | grep -Fqx \"OMA_GREP_OWNER=$1\"; then",
+            "    start=$(awk '{print $22}' \"/proc/$pid/stat\" 2>/dev/null || true)",
+            "    case \"$start\" in ''|*[!0-9]*) :;; *) pids=\"$pids $pid:$start\";; esac",
+            "  fi",
+            "done",
+            "for entry in $pids; do",
+            "  pid=${entry%%:*}; start=${entry#*:}",
+            "  current=$(awk '{print $22}' \"/proc/$pid/stat\" 2>/dev/null || true)",
+            "  if [ \"$current\" = \"$start\" ] && tr '\\0' '\\n' < \"/proc/$pid/environ\" 2>/dev/null | grep -Fqx \"OMA_GREP_OWNER=$1\"; then",
+            "    kill -KILL \"-$pid\" 2>/dev/null || kill -KILL \"$pid\" 2>/dev/null || true",
+            "  fi",
+            "done",
+            "attempt=0",
+            "while [ -n \"$pids\" ] && [ \"$attempt\" -lt 40 ]; do",
+            "  remaining=''",
+            "  for entry in $pids; do",
+            "    pid=${entry%%:*}; start=${entry#*:}",
+            "    current=$(awk '{print $22}' \"/proc/$pid/stat\" 2>/dev/null || true)",
+            "    if [ \"$current\" = \"$start\" ] && tr '\\0' '\\n' < \"/proc/$pid/environ\" 2>/dev/null | grep -Fqx \"OMA_GREP_OWNER=$1\"; then remaining=\"$remaining $entry\"; fi",
+            "  done",
+            "  pids=$remaining",
+            "  [ -z \"$pids\" ] && break",
+            "  attempt=$((attempt + 1)); sleep 0.05",
+            "done",
+            "[ -z \"$pids\" ]",
+        ].join("\n"),
+        args: [ownershipToken],
+    };
+}
+export function buildDockerCmaGrepPreflightCommand() {
+    return {
+        script: [
+            "set -eu",
+            "dir=\".oma-grep-preflight-$$\"",
+            "mkdir \"$dir\"",
+            "trap 'rm -rf \"$dir\"' EXIT",
+            "printf 'needle\\n' > \"$dir/text.txt\"",
+            "printf 'other\\n' > \"$dir/no-match.txt\"",
+            "printf '\\0needle\\0tail' > \"$dir/binary.bin\"",
+            "LC_ALL=C rg --no-config --files-with-matches --null -- 'needle' \"$dir/text.txt\" | grep -Fq \"$dir/text.txt\"",
+            "set +e",
+            "LC_ALL=C rg --no-config --files-with-matches --null -- 'needle' \"$dir/no-match.txt\" >/dev/null 2>&1",
+            "code=$?",
+            "set -e",
+            "[ \"$code\" -eq 1 ]",
+            "set +e",
+            "LC_ALL=C rg --no-config --files-with-matches --null -- '[' \"$dir/text.txt\" >/dev/null 2>&1",
+            "code=$?",
+            "set -e",
+            "[ \"$code\" -ne 0 ] && [ \"$code\" -ne 1 ]",
+            "last=$(LC_ALL=C rg --no-config --files-with-matches --null -- 'needle' \"$dir/text.txt\" | tail -c 1 | od -An -tu1)",
+            "[ \"$(printf '%s' \"$last\" | tr -d ' ')\" = 0 ]",
+            "LC_ALL=C rg --no-config -qaU -- '\\x00' \"$dir/binary.bin\"",
+            "set +e",
+            "LC_ALL=C rg --no-config -qaU -- '\\x00' \"$dir/text.txt\"",
+            "code=$?",
+            "set -e",
+            "[ \"$code\" -eq 1 ]",
+        ].join("\n"),
+        args: [],
+    };
+}
+export function buildDockerCmaGrepSearchCommand(root, ownershipToken, pattern, glob) {
+    const ripgrepGlob = glob === undefined ? "" : cmaGlobToRipgrepGlob(glob);
+    return {
+        script: [
+            "set -eu",
+            "exec setsid env \"OMA_GREP_OWNER=$2\" bash -c '",
+            "set -euo pipefail",
+            "printf \"%s\\0\" __OMA_GREP_READY__",
+            "emit_text_matches() {",
+            "  while IFS= read -r -d \"\" path; do",
+            "    set +e",
+            "    LC_ALL=C rg --no-config -qaU -- \"\\x00\" \"$path\"",
+            "    binary_code=$?",
+            "    set -e",
+            "    if [ \"$binary_code\" -eq 1 ]; then printf \"%s\\0\" \"$path\"; elif [ \"$binary_code\" -ne 0 ]; then exit \"$binary_code\"; fi",
+            "  done",
+            "}",
+            "set +e",
+            "if [ -n \"$3\" ]; then",
+            "  LC_ALL=C rg --no-config --hidden --no-ignore --color never --files-with-matches --null --glob \"$3\" -- \"$2\" \"$1\" | emit_text_matches",
+            "else",
+            "  LC_ALL=C rg --no-config --hidden --no-ignore --color never --files-with-matches --null -- \"$2\" \"$1\" | emit_text_matches",
+            "fi",
+            "code=$?",
+            "[ \"$code\" -eq 0 ] || [ \"$code\" -eq 1 ]",
+            "' oma-rg \"$1\" \"$3\" \"$4\"",
+        ].join("\n"),
+        args: [root, ownershipToken, pattern, ripgrepGlob],
+    };
+}
+export function buildDockerCmaGlobEnumerationCommand(root, ownershipToken) {
+    return {
+        script: [
+            "set -eu",
+            "setsid env \"OMA_GLOB_OWNER=$2\" sh -c 'set -eu; printf \"%s\\0\" __OMA_GLOB_READY__; cd \"$1\"; exec find . -type f -print0' \"$2\" \"$1\" &",
+            "child=$!",
+            "wait \"$child\"",
+        ].join("\n"),
+        args: [root, ownershipToken],
+    };
+}
+export function buildDockerGlobEnumerationCommand(root, ignore = []) {
+    const prunedDirectoryNames = directoryNamesPrunedByIgnoreGlobs(ignore);
+    return {
+        script: [
+            "cd \"$1\"",
+            "shift",
+            "if [ \"$#\" -eq 0 ]; then",
+            "  find . -type f | sed 's#^./##' | sort",
+            "else",
+            "  find . \\( -type d \\( \"$@\" \\) -prune \\) -o -type f -print | sed 's#^./##' | sort",
+            "fi",
+        ].join("\n"),
+        args: [
+            root,
+            ...prunedDirectoryNames.flatMap((name, index) => index === 0 ? ["-name", name] : ["-o", "-name", name]),
+        ],
+    };
+}
+export function buildDockerOutputListingCommand(outputRoot, limits = {
+    maxFiles: MAX_SESSION_OUTPUT_FILES,
+    maxFileBytes: MAX_SESSION_OUTPUT_FILE_BYTES,
+    maxBytes: MAX_SESSION_OUTPUT_BYTES,
+}) {
+    return {
+        script: [
+            "root=\"$1\"",
+            "max_files=\"$2\"",
+            "max_file_bytes=\"$3\"",
+            "max_bytes=\"$4\"",
+            "if [ ! -d \"$root\" ]; then exit 0; fi",
+            "cd \"$root\"",
+            "count=0",
+            "total=0",
+            "find . -type f -print0 | sort -z | while IFS= read -r -d '' file; do",
+            "  rel=\"${file#./}\"",
+            "  size=$(wc -c < \"$file\")",
+            "  count=$((count + 1))",
+            "  if [ \"$count\" -gt \"$max_files\" ]; then",
+            "    printf 'session output file count exceeds %s\\n' \"$max_files\" >&2",
+            "    exit 42",
+            "  fi",
+            "  if [ \"$size\" -gt \"$max_file_bytes\" ]; then",
+            "    printf 'session output file exceeds %s bytes: %s\\n' \"$max_file_bytes\" \"$rel\" >&2",
+            "    exit 42",
+            "  fi",
+            "  total=$((total + size))",
+            "  if [ \"$total\" -gt \"$max_bytes\" ]; then",
+            "    printf 'session output bytes exceed %s\\n' \"$max_bytes\" >&2",
+            "    exit 42",
+            "  fi",
+            "  sha=$(sha256sum \"$file\" | awk '{print $1}')",
+            "  printf '%s\\0%s\\0%s\\0' \"$rel\" \"$size\" \"$sha\"",
+            "done",
+        ].join("\n"),
+        args: [
+            outputRoot,
+            String(limits.maxFiles),
+            String(limits.maxFileBytes),
+            String(limits.maxBytes),
+        ],
+    };
+}
+export function directoryNamesPrunedByIgnoreGlobs(ignore) {
+    const names = new Set();
+    for (const pattern of ignore) {
+        const normalized = pattern.replaceAll("\\", "/");
+        const match = /(?:^|\/)([^/*?[\]{}!]+)\/\*\*$/.exec(normalized);
+        if (match?.[1])
+            names.add(match[1]);
+    }
+    return [...names].sort();
+}
+export function assertInsideDockerWorkspace(absolutePath, workspacePath = DEFAULT_WORKSPACE) {
+    if (!posix.isAbsolute(absolutePath)) {
+        throw new Error(`Sandbox path must be absolute: ${absolutePath}`);
+    }
+    const root = posix.resolve(workspacePath);
+    const path = posix.resolve(absolutePath);
+    const rel = posix.relative(root, path);
+    if (rel === "" || (!rel.startsWith("..") && !posix.isAbsolute(rel))) {
+        return path;
+    }
+    throw new Error(`Sandbox path escapes workspace: ${absolutePath}`);
+}
+export function assertInsideDockerSearchRoot(absolutePath, roots) {
+    if (!posix.isAbsolute(absolutePath)) {
+        throw new Error(`Sandbox search path must be absolute: ${absolutePath}`);
+    }
+    const path = posix.resolve(absolutePath);
+    for (const rootPath of roots) {
+        const root = posix.resolve(rootPath);
+        const rel = posix.relative(root, path);
+        if (rel === "" || (!rel.startsWith("..") && !posix.isAbsolute(rel))) {
+            return path;
+        }
+    }
+    throw new Error(`Sandbox search path escapes approved roots: ${absolutePath}`);
+}
+export function assertInsideUploadsPath(absolutePath, uploadsPath = DEFAULT_UPLOADS_PATH) {
+    if (!posix.isAbsolute(absolutePath)) {
+        throw new Error(`Session file mount path must be absolute: ${absolutePath}`);
+    }
+    const root = posix.resolve(uploadsPath);
+    const path = posix.resolve(absolutePath);
+    const rel = posix.relative(root, path);
+    if (rel !== "" && !rel.startsWith("..") && !posix.isAbsolute(rel)) {
+        return rel;
+    }
+    throw new Error(`Session file mount path escapes uploads root: ${absolutePath}`);
+}
+function assertInsideMountRoot(absolutePath, rootPath) {
+    if (!posix.isAbsolute(absolutePath))
+        throw new Error(`Session file mount path must be absolute: ${absolutePath}`);
+    const root = posix.resolve(rootPath);
+    const rel = posix.relative(root, posix.resolve(absolutePath));
+    if (rel !== "" && !rel.startsWith("..") && !posix.isAbsolute(rel))
+        return rel;
+    throw new Error(`Session file mount path escapes ${rootPath}: ${absolutePath}`);
+}
+export function assertInsideDockerOutputPath(absolutePath, outputsPath = DEFAULT_OUTPUTS_PATH) {
+    if (!posix.isAbsolute(absolutePath)) {
+        throw new Error(`Session output path must be absolute: ${absolutePath}`);
+    }
+    const root = posix.resolve(outputsPath);
+    const path = posix.resolve(absolutePath);
+    const rel = posix.relative(root, path);
+    if (rel !== "" && !rel.startsWith("..") && !posix.isAbsolute(rel)) {
+        return path;
+    }
+    throw new Error(`Session output path escapes outputs root: ${absolutePath}`);
+}
+function parseOutputListing(stdout) {
+    if (stdout.length === 0)
+        return [];
+    const fields = stdout.toString("utf8").split("\0");
+    if (fields.at(-1) === "")
+        fields.pop();
+    if (fields.length % 3 !== 0) {
+        throw new Error("Docker output listing returned malformed records");
+    }
+    const out = [];
+    for (let index = 0; index < fields.length; index += 3) {
+        const relativePath = fields[index];
+        const sizeBytes = Number(fields[index + 1]);
+        const sha256 = fields[index + 2];
+        if (relativePath.length === 0 ||
+            posix.isAbsolute(relativePath) ||
+            relativePath.split("/").includes("..")) {
+            throw new Error(`Unsafe session output path: ${relativePath}`);
+        }
+        if (!Number.isSafeInteger(sizeBytes) || sizeBytes < 0) {
+            throw new Error(`Invalid session output size: ${relativePath}`);
+        }
+        if (!/^[0-9a-f]{64}$/i.test(sha256)) {
+            throw new Error(`Invalid session output checksum: ${relativePath}`);
+        }
+        out.push({ relativePath, sizeBytes, sha256 });
+    }
+    return out;
+}
+function mimeTypeForFilename(filename) {
+    const lower = filename.toLowerCase();
+    if (lower.endsWith(".txt"))
+        return "text/plain";
+    if (lower.endsWith(".json"))
+        return "application/json";
+    if (lower.endsWith(".csv"))
+        return "text/csv";
+    if (lower.endsWith(".html") || lower.endsWith(".htm"))
+        return "text/html";
+    if (lower.endsWith(".md"))
+        return "text/markdown";
+    if (lower.endsWith(".pptx")) {
+        return "application/vnd.openxmlformats-officedocument.presentationml.presentation";
+    }
+    if (lower.endsWith(".png"))
+        return "image/png";
+    if (lower.endsWith(".jpg") || lower.endsWith(".jpeg"))
+        return "image/jpeg";
+    if (lower.endsWith(".pdf"))
+        return "application/pdf";
+    return "application/octet-stream";
+}
+async function* dockerOutputBytes(read) {
+    yield (await read()).stdout;
+}
+async function writeMountFile(tempRoot, relativePath, mount) {
+    const segments = relativePath.split("/");
+    const filePath = joinHostPath(tempRoot, ...segments);
+    await mkdir(joinHostPath(tempRoot, ...segments.slice(0, -1)), {
+        recursive: true,
+        mode: 0o755,
+    });
+    const handle = await open(filePath, "w", 0o644);
+    const hash = createHash("sha256");
+    let size = 0;
+    try {
+        for await (const chunk of chunksForMount(mount.bytes)) {
+            const buffer = Buffer.from(chunk);
+            size += buffer.byteLength;
+            hash.update(buffer);
+            await handle.write(buffer);
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    const sha256 = hash.digest("hex");
+    if (size !== mount.sizeBytes) {
+        throw new Error(`Session file mount ${mount.snapshotFileId} size mismatch: expected ${mount.sizeBytes}, got ${size}`);
+    }
+    if (sha256 !== mount.sha256) {
+        throw new Error(`Session file mount ${mount.snapshotFileId} failed integrity validation`);
+    }
+}
+async function* chunksForMount(bytes) {
+    if (bytes instanceof Uint8Array) {
+        yield bytes;
+        return;
+    }
+    yield* bytes;
+}
+function createTarArchive(sourceDirectory) {
+    const result = spawnSync("tar", ["-C", sourceDirectory, "-cf", "-", "."], {
+        encoding: "buffer",
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (result.status !== 0) {
+        throw new Error(`tar archive failed with ${result.status}: ${result.stderr.toString("utf8")}`);
+    }
+    return result.stdout;
+}
+export function filterDockerEnv(source, allowlist) {
+    const out = {};
+    for (const key of allowlist) {
+        if (source[key] !== undefined)
+            out[key] = source[key];
+    }
+    return out;
+}
+export async function reapDockerSandboxContainers(opts) {
+    const dockerCommand = opts.dockerCommand ?? "docker";
+    const listed = await dockerChecked(dockerCommand, [
+        "ps",
+        "-aq",
+        "--filter",
+        `label=${SANDBOX_LABEL_KEY}=${SANDBOX_LABEL_VALUE}`,
+        "--filter",
+        `label=${OWNER_LABEL_KEY}=${OWNER_LABEL_VALUE}`,
+        ...(opts.labelFilters?.flatMap((label) => [
+            "--filter",
+            `label=${label}`,
+        ]) ?? []),
+    ]);
+    const ids = listed.stdout.toString("utf8").split("\n").filter(Boolean);
+    if (ids.length === 0)
+        return 0;
+    const now = opts.now?.() ?? Date.now();
+    const expired = [];
+    for (const id of ids) {
+        const inspected = await dockerChecked(dockerCommand, [
+            "inspect",
+            id,
+            "--format",
+            "{{json .Created}}",
+        ]);
+        const created = JSON.parse(inspected.stdout.toString("utf8"));
+        if (now - new Date(created).getTime() >= opts.olderThanMs) {
+            expired.push(id);
+        }
+    }
+    if (expired.length === 0)
+        return 0;
+    await dockerChecked(dockerCommand, ["rm", "-f", ...expired]);
+    return expired.length;
+}
+function resolveDockerOptions(opts) {
+    return {
+        image: opts.image ?? DEFAULT_DOCKER_SANDBOX_IMAGE,
+        dockerCommand: opts.dockerCommand ?? "docker",
+        workspacePath: opts.workspacePath ?? DEFAULT_WORKSPACE,
+        uploadsPath: DEFAULT_UPLOADS_PATH,
+        outputsPath: DEFAULT_OUTPUTS_PATH,
+        envAllowlist: new Set(opts.envAllowlist ?? []),
+        operationTimeoutMs: opts.operationTimeoutMs ?? DEFAULT_OPERATION_TIMEOUT_MS,
+        startupTimeoutMs: opts.startupTimeoutMs ?? DEFAULT_DOCKER_STARTUP_TIMEOUT_MS,
+        containerNamePrefix: opts.containerNamePrefix ?? "oma-sandbox",
+        memory: opts.memory ?? DEFAULT_MEMORY,
+        cpus: opts.cpus ?? DEFAULT_CPUS,
+        pidsLimit: opts.pidsLimit ?? DEFAULT_PIDS_LIMIT,
+        tmpfsSize: opts.tmpfsSize ?? DEFAULT_TMPFS_SIZE,
+        outputsTmpfsSize: opts.outputsTmpfsSize ?? DEFAULT_OUTPUTS_TMPFS_SIZE,
+        maxOutputFiles: opts.maxOutputFiles ?? MAX_SESSION_OUTPUT_FILES,
+        maxOutputFileBytes: opts.maxOutputFileBytes ?? MAX_SESSION_OUTPUT_FILE_BYTES,
+        maxOutputBytes: opts.maxOutputBytes ?? MAX_SESSION_OUTPUT_BYTES,
+        extraLabels: opts.extraLabels ?? {},
+    };
+}
+function assertTmpfsMemoryHeadroom(memory, tmpfsSize, outputsTmpfsSize, skillsTmpfsSize) {
+    const memoryBytes = parseDockerByteSize(memory, "memory");
+    const tmpfsBytes = parseDockerByteSize(tmpfsSize, "tmpfsSize");
+    const outputTmpfsBytes = parseDockerByteSize(outputsTmpfsSize, "outputsTmpfsSize");
+    const skillsTmpfsBytes = parseDockerByteSize(skillsTmpfsSize, "skillsTmpfsSize");
+    if (tmpfsBytes * 2 + outputTmpfsBytes + skillsTmpfsBytes < memoryBytes)
+        return;
+    throw new Error("Docker sandbox memory must exceed workspace tmpfs plus uploads tmpfs plus outputs tmpfs plus skills tmpfs");
+}
+function parseDockerByteSize(value, label) {
+    const match = /^([1-9][0-9]*)([bkmg])?$/i.exec(value);
+    if (!match) {
+        throw new Error(`Docker sandbox ${label} must use bytes or a k/m/g suffix: ${value}`);
+    }
+    const amount = Number(match[1]);
+    const unit = (match[2] ?? "b").toLowerCase();
+    const multiplier = unit === "g"
+        ? 1024 * 1024 * 1024
+        : unit === "m"
+            ? 1024 * 1024
+            : unit === "k"
+                ? 1024
+                : 1;
+    return amount * multiplier;
+}
+function dockerContainerName(prefix, workspaceId, sessionId) {
+    const suffix = Math.random().toString(36).slice(2, 8);
+    return [
+        sanitizeDockerNamePart(prefix),
+        sanitizeDockerNamePart(workspaceId),
+        sanitizeDockerNamePart(sessionId),
+        Date.now().toString(36),
+        suffix,
+    ].join("-");
+}
+function sanitizeDockerNamePart(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9_.-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48) || "x";
+}
+function randomExecId() {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function recordSandboxNotDisposed(disposed) {
+    if (disposed.value)
+        throw new Error("Sandbox provider is disposed");
+}
+function bashDispatchSentinel(token) {
+    return Buffer.from(`${BASH_DISPATCH_PREFIX}${token}\n`);
+}
+function bashTerminalPrefix(token) {
+    return Buffer.from(`${BASH_TERMINAL_PREFIX}${token}:`);
+}
+export function createBashDispatchFilter(token) {
+    const dispatchSentinel = bashDispatchSentinel(token);
+    const terminalPrefix = bashTerminalPrefix(token);
+    let dispatchSeen = false;
+    let terminalRecord;
+    let terminalCandidate = Buffer.alloc(0);
+    let pendingStdout = Buffer.alloc(0);
+    let pendingStderr = Buffer.alloc(0);
+    const filterAfterDispatch = (chunk) => {
+        pendingStdout = Buffer.concat([pendingStdout, chunk]);
+        const index = pendingStdout.indexOf(terminalPrefix);
+        if (index >= 0) {
+            const lineEnd = pendingStdout.indexOf("\n", index);
+            if (lineEnd < 0) {
+                const out = pendingStdout.subarray(0, index);
+                pendingStdout = pendingStdout.subarray(index);
+                return out;
+            }
+            const line = pendingStdout.subarray(index, lineEnd).toString("utf8");
+            terminalRecord = parseBashTerminalRecord(line, token);
+            const out = Buffer.concat([
+                pendingStdout.subarray(0, index),
+                pendingStdout.subarray(lineEnd + 1),
+            ]);
+            pendingStdout = Buffer.alloc(0);
+            return out;
+        }
+        if (terminalCandidate.length > 0) {
+            const combined = Buffer.concat([terminalCandidate, pendingStdout]);
+            if (isPrefixOf(combined, terminalPrefix)) {
+                terminalCandidate = combined;
+                pendingStdout = Buffer.alloc(0);
+                return Buffer.alloc(0);
+            }
+            const out = combined;
+            terminalCandidate = Buffer.alloc(0);
+            pendingStdout = Buffer.alloc(0);
+            return out;
+        }
+        const candidateStart = findTerminalPrefixCandidateStart(pendingStdout, terminalPrefix);
+        if (candidateStart < 0) {
+            const out = pendingStdout;
+            pendingStdout = Buffer.alloc(0);
+            return out;
+        }
+        const candidate = pendingStdout.subarray(candidateStart);
+        if (isPrefixOf(candidate, terminalPrefix)) {
+            const out = pendingStdout.subarray(0, candidateStart);
+            terminalCandidate = candidate;
+            pendingStdout = Buffer.alloc(0);
+            return out;
+        }
+        const out = pendingStdout;
+        pendingStdout = Buffer.alloc(0);
+        return out;
+    };
+    return {
+        dispatchSeen: () => dispatchSeen,
+        terminalRecord: () => terminalRecord,
+        stderr: (chunk) => {
+            if (dispatchSeen)
+                return chunk;
+            pendingStderr = Buffer.concat([pendingStderr, chunk]);
+            return Buffer.alloc(0);
+        },
+        stdout: (chunk) => {
+            if (dispatchSeen)
+                return filterAfterDispatch(chunk);
+            pendingStdout = Buffer.concat([pendingStdout, chunk]);
+            const index = pendingStdout.indexOf(dispatchSentinel);
+            if (index < 0)
+                return Buffer.alloc(0);
+            dispatchSeen = true;
+            const afterDispatch = Buffer.concat([
+                pendingStdout.subarray(0, index),
+                pendingStderr,
+                pendingStdout.subarray(index + dispatchSentinel.length),
+            ]);
+            pendingStdout = Buffer.alloc(0);
+            pendingStderr = Buffer.alloc(0);
+            return filterAfterDispatch(afterDispatch);
+        },
+    };
+}
+function parseBashTerminalRecord(line, token) {
+    const prefix = `${BASH_TERMINAL_PREFIX}${token}:`;
+    if (!line.startsWith(prefix))
+        return undefined;
+    const payload = line.slice(prefix.length);
+    const [kind, exitCodeText, extra] = payload.split(":");
+    if (extra !== undefined || !/^(0|[1-9][0-9]*)$/.test(exitCodeText ?? "")) {
+        return undefined;
+    }
+    const exitCode = Number(exitCodeText);
+    if (kind === "exit")
+        return { kind, exitCode };
+    if (kind === "timeout")
+        return { kind, exitCode };
+    return undefined;
+}
+function findTerminalPrefixCandidateStart(buffer, terminalPrefix) {
+    for (let index = 0; index < buffer.length; index += 1) {
+        if (buffer[index] === terminalPrefix[0])
+            return index;
+    }
+    return -1;
+}
+function isPrefixOf(candidate, value) {
+    if (candidate.length > value.length)
+        return false;
+    return value.subarray(0, candidate.length).equals(candidate);
+}
+function filterDockerEnvObject(env) {
+    const out = {};
+    for (const [key, value] of Object.entries(env ?? {})) {
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+async function dockerChecked(dockerCommand, args, opts = {}) {
+    const result = await dockerExec(dockerCommand, args, opts);
+    if (result.exitCode !== 0) {
+        throw new Error(`docker ${args.join(" ")} failed with ${result.exitCode}: ${result.stderr.toString("utf8") || result.stdout.toString("utf8")}`);
+    }
+    return result;
+}
+function throwIfUnexpectedBoundedExit(result, context, normalNonZeroExitCodes) {
+    if (result.exitCode !== null &&
+        normalNonZeroExitCodes.has(result.exitCode) &&
+        result.stderr.length === 0) {
+        return;
+    }
+    throw new Error(`${context} failed with ${result.exitCode}: ${result.stderr.toString("utf8") || result.stdout.toString("utf8")}`);
+}
+async function dockerExec(dockerCommand, args, opts = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(dockerCommand, args, {
+            detached: true,
+            env: filterDockerEnvObject(process.env),
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        if (child.pid !== undefined)
+            opts.activePids?.add(child.pid);
+        const stdout = [];
+        const stderr = [];
+        let stdoutBytes = 0;
+        let combinedBytes = 0;
+        let settled = false;
+        let terminalError;
+        let timer;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            if (child.pid !== undefined)
+                opts.activePids?.delete(child.pid);
+            opts.signal?.removeEventListener("abort", onAbort);
+            fn();
+        };
+        const kill = () => {
+            if (child.pid === undefined)
+                return;
+            killProcessGroup(child.pid);
+            if (!child.killed)
+                child.kill();
+        };
+        const terminate = (error) => {
+            if (terminalError || settled)
+                return;
+            terminalError = error;
+            kill();
+        };
+        const onAbort = () => {
+            opts.onAbort?.();
+            terminate(new Error("aborted"));
+        };
+        const chargeCombinedOutput = (chunk) => {
+            combinedBytes += chunk.byteLength;
+            if (opts.maxCombinedBytes !== undefined && combinedBytes > opts.maxCombinedBytes) {
+                terminate(new Error(`docker output exceeded ${opts.maxCombinedBytes} bytes`));
+                return false;
+            }
+            return true;
+        };
+        child.stdout.on("data", (chunk) => {
+            if (!chargeCombinedOutput(chunk))
+                return;
+            const maxStdoutBytes = opts.maxStdoutBytes;
+            const nextStdoutBytes = stdoutBytes + chunk.byteLength;
+            if (maxStdoutBytes !== undefined &&
+                nextStdoutBytes > maxStdoutBytes) {
+                terminate(new Error(`docker stdout exceeded ${maxStdoutBytes} bytes`));
+                return;
+            }
+            stdoutBytes = nextStdoutBytes;
+            stdout.push(chunk);
+            opts.onStdout?.(chunk);
+            opts.onData?.(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            if (!chargeCombinedOutput(chunk))
+                return;
+            stderr.push(chunk);
+            opts.onStderr?.(chunk);
+            opts.onData?.(chunk);
+        });
+        child.on("error", (error) => settle(() => reject(error)));
+        child.on("close", (exitCode) => settle(() => {
+            if (terminalError)
+                reject(terminalError);
+            else
+                resolve({
+                    stdout: Buffer.concat(stdout),
+                    stderr: Buffer.concat(stderr),
+                    exitCode,
+                });
+        }));
+        if (opts.signal?.aborted)
+            onAbort();
+        else
+            opts.signal?.addEventListener("abort", onAbort, { once: true });
+        if (opts.timeoutMs !== undefined && opts.timeoutMs > 0) {
+            timer = setTimeout(() => {
+                opts.onAbort?.();
+                terminate(new DockerTimeoutError());
+            }, opts.timeoutMs);
+        }
+        if (opts.input !== undefined)
+            child.stdin.end(opts.input);
+        else
+            child.stdin.end();
+    });
+}
+function killProcessGroup(pid) {
+    try {
+        process.kill(-pid);
+    }
+    catch {
+        // The Docker CLI process may already have exited.
+    }
+}
+class DockerTimeoutError extends Error {
+    constructor() {
+        super("Docker operation timed out");
+    }
+}
+function killInContainerProcessGroup(dockerCommand, containerName, pidFile) {
+    spawnSync(dockerCommand, buildDockerExecShellArgs(containerName, [
+        "pidfile=\"$1\"",
+        "timerfile=\"${pidfile}.timer\"",
+        "for _ in $(seq 1 50); do",
+        "  [ -f \"$pidfile\" ] && break",
+        "  sleep 0.01",
+        "done",
+        "if [ -f \"$timerfile\" ]; then",
+        "  timer=$(cat \"$timerfile\")",
+        "  kill -KILL \"$timer\" 2>/dev/null || true",
+        "fi",
+        "if [ -f \"$pidfile\" ]; then",
+        "  pid=$(cat \"$pidfile\")",
+        "  kill -KILL \"-$pid\" 2>/dev/null || kill -KILL \"$pid\" 2>/dev/null || true",
+        "  for _ in $(seq 1 50); do",
+        "    kill -0 \"$pid\" 2>/dev/null || break",
+        "    sleep 0.02",
+        "  done",
+        "  rm -f \"$pidfile\" \"$timerfile\"",
+        "fi",
+    ].join("\n"), [pidFile]), { stdio: "ignore" });
+}
+function forceRemoveDockerContainer(dockerCommand, containerName) {
+    spawnSync(dockerCommand, ["rm", "-f", containerName], { stdio: "ignore" });
+}
+async function removeDockerContainerChecked(dockerCommand, containerName, timeoutMs) {
+    let lastError;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const result = await dockerExec(dockerCommand, ["rm", "-f", containerName], { timeoutMs });
+            if (result.exitCode === 0)
+                return;
+            const detail = Buffer.concat([result.stderr, result.stdout]).toString("utf8");
+            if (/no such (?:container|object)/i.test(detail))
+                return;
+            lastError = new Error(`docker rm -f ${containerName} failed with ${result.exitCode}: ${detail}`);
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw new Error(`Failed to remove poisoned Docker sandbox ${containerName}`, { cause: lastError });
+}