@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/coding/src/security/docker-sandbox.ts

@@ -0,0 +1,1205 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { access, realpath } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { PassThrough } from "node:stream";
+import type { ProcessRecoveryBackend } from "../agent/process/recovery.js";
+import type { ProcessSandboxHandle } from "../agent/process/types.js";
+import {
+  assertAbsoluteExecutable,
+  createSecretRedactor,
+  DockerCliError,
+  type DockerRunner,
+  dockerOutputText,
+  runDockerCli,
+  sha256Hex,
+} from "./docker-cli.js";
+import { type EgressAttestation, EgressError } from "./egress/index.js";
+import type {
+  DisposableSandbox,
+  SandboxCapabilities,
+  SandboxCloseOptions,
+  SandboxExecFileRequest,
+  SandboxExecRequest,
+  SandboxExportMetadata,
+  SandboxProcessHandle,
+  SandboxStatus,
+  SandboxStatusState,
+} from "./sandbox.js";
+import { type DockerSandboxLimitOptions, type ResolvedDockerSandboxLimits, resolveDockerSandboxLimits } from "./sandbox-limits.js";
+import { createImportTarStream, SandboxTarError, summarizeTarStream } from "./sandbox-tar.js";
+import { Semaphore } from "./semaphore.js";
+
+const IMAGE_DIGEST_RE = /@sha256:[a-f0-9]{64}$/i;
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const USER_RE = /^[0-9]{1,10}:[0-9]{1,10}$/;
+const SOURCE_MOUNT = "/source";
+const WORKSPACE_MOUNT = "/workspace";
+const TMP_MOUNT = "/tmp";
+const DOWNLOAD_MOUNT = "/downloads";
+const KEEP_ALIVE = ["sleep", "infinity"] as const;
+
+export type DockerNetworkConfig =
+  | { readonly mode: "none" }
+  | {
+      readonly mode: "custom";
+      /** Pre-created Docker network name. Adapter does not claim DNS/egress containment. */
+      readonly name: string;
+      /**
+       * Optional host attestation that this network forces browser egress through a
+       * controlled proxy/firewall. Required before treating custom networks as browse-ready.
+       * Playwright routing remains defense in depth only.
+       */
+      readonly browserEgress?: {
+        readonly proxyEndpoint: string;
+        readonly denyDirectEgress: true;
+      };
+      /**
+       * Optional allow-list egress attestation from `EgressProxy.attestation()`.
+       * Records proxy enforcement evidence in container labels; the host must
+       * actually restrict the network so the proxy is the only reachable path.
+       */
+      readonly egress?: EgressAttestation;
+    };
+
+/** Validate an allow-list egress attestation; fails closed on malformed evidence. */
+export function assertEgressAttestation(attestation: EgressAttestation): EgressAttestation {
+  if (!attestation || typeof attestation !== "object") {
+    throw new EgressError("ERR_PRISM_EGRESS_ATTESTATION", "egress attestation must be an object");
+  }
+  if (attestation.denyDirectEgress !== true) {
+    throw new EgressError("ERR_PRISM_EGRESS_ATTESTATION", "egress attestation requires denyDirectEgress: true");
+  }
+  if (typeof attestation.policyFingerprint !== "string" || !/^[a-f0-9]{64}$/.test(attestation.policyFingerprint)) {
+    throw new EgressError("ERR_PRISM_EGRESS_ATTESTATION", "egress attestation requires a sha256 policyFingerprint");
+  }
+  if (!Number.isSafeInteger(attestation.policyVersion) || attestation.policyVersion < 0) {
+    throw new EgressError("ERR_PRISM_EGRESS_ATTESTATION", "egress attestation requires a non-negative integer policyVersion");
+  }
+  if (typeof attestation.startedAt !== "string" || Number.isNaN(Date.parse(attestation.startedAt))) {
+    throw new EgressError("ERR_PRISM_EGRESS_ATTESTATION", "egress attestation requires a valid startedAt timestamp");
+  }
+  let proxy: URL;
+  try {
+    proxy = new URL(attestation.proxyEndpoint);
+  } catch {
+    throw new EgressError("ERR_PRISM_EGRESS_ATTESTATION", "egress attestation proxyEndpoint is not a valid URL");
+  }
+  if (proxy.protocol !== "http:" && proxy.protocol !== "https:") {
+    throw new EgressError("ERR_PRISM_EGRESS_ATTESTATION", "egress attestation proxyEndpoint must be http(s)");
+  }
+  return attestation;
+}
+
+/** Compose a custom sandbox network carrying validated egress attestation. */
+export function composeEgressSandboxNetwork(attestation: EgressAttestation, name: string): DockerNetworkConfig {
+  assertEgressAttestation(attestation);
+  if (typeof name !== "string" || name.length === 0 || /[\s\\]/.test(name)) {
+    throw new DockerSandboxError("custom network requires a non-empty name without whitespace");
+  }
+  return { mode: "custom", name, egress: attestation };
+}
+
+/** Fail closed unless the sandbox network is none or carries browser egress attestation. */
+export function assertBrowserSandboxNetwork(network: DockerNetworkConfig | undefined): void {
+  const resolved = network ?? { mode: "none" as const };
+  if (resolved.mode === "none") return;
+  const attestation = resolved.browserEgress;
+  if (attestation?.denyDirectEgress !== true || !attestation.proxyEndpoint) {
+    throw new DockerSandboxError(
+      "custom sandbox network requires browserEgress attestation (proxyEndpoint + denyDirectEgress) before browser use",
+    );
+  }
+  try {
+    const proxy = new URL(attestation.proxyEndpoint);
+    if (proxy.protocol !== "http:" && proxy.protocol !== "https:" && proxy.protocol !== "socks5:") {
+      throw new DockerSandboxError("browserEgress.proxyEndpoint must be http(s) or socks5");
+    }
+  } catch (error) {
+    if (error instanceof DockerSandboxError) throw error;
+    throw new DockerSandboxError("browserEgress.proxyEndpoint is not a valid URL");
+  }
+}
+
+/**
+ * Capabilities established by the validated create options and container
+ * construction: a single coherent workspace tree, container filesystem and
+ * process namespace, network isolation only for mode `none`, egress
+ * restriction only for mode `none` or a custom network carrying a validated
+ * egress attestation, and privilege isolation always false for 0.2.0
+ * (root-in-container without user namespaces is not a reliable claim).
+ */
+export function resolveDockerCapabilities(network: DockerNetworkConfig): SandboxCapabilities {
+  return Object.freeze({
+    workspaceCoherent: true,
+    filesystemIsolated: true,
+    networkIsolated: network.mode === "none",
+    processIsolated: true,
+    privilegeIsolated: false,
+    egressRestricted: network.mode === "none" || (network.mode === "custom" && network.egress !== undefined),
+  });
+}
+
+export interface CreateDockerSandboxOptions {
+  /** Absolute path to the host Docker executable. */
+  readonly docker: string;
+  /** Digest-pinned image reference (`name@sha256:...`). */
+  readonly image: string;
+  /** Absolute host directory imported into the writable workspace. */
+  readonly sourceRoot: string;
+  /** Non-root `uid:gid` inside the container. */
+  readonly user: string;
+  readonly network?: DockerNetworkConfig;
+  readonly limits?: DockerSandboxLimitOptions;
+  /** Exact environment allow-list. Host environment is never inherited. */
+  readonly env?: Readonly<Record<string, string>>;
+  /** Secret canaries redacted from CLI errors. */
+  readonly secrets?: readonly string[];
+  readonly workdir?: string;
+  readonly labels?: Readonly<Record<string, string>>;
+  /** Test seam: replace Docker CLI execution. */
+  readonly runner?: DockerRunner;
+  /** Skip source import (tests only). */
+  readonly skipImport?: boolean;
+}
+
+export class DockerSandboxError extends Error {
+  readonly code = "ERR_PRISM_DOCKER_SANDBOX";
+  constructor(message: string) {
+    super(message);
+    this.name = "DockerSandboxError";
+  }
+}
+
+function formatTmpfs(path: string, sizeBytes: number, mode = "1777"): string {
+  return `${path}:rw,nosuid,size=${sizeBytes},mode=${mode}`;
+}
+
+function validateImage(image: string): string {
+  if (!image || typeof image !== "string") {
+    throw new DockerSandboxError("image is required");
+  }
+  if (!IMAGE_DIGEST_RE.test(image)) {
+    throw new DockerSandboxError("image must be digest-pinned as name@sha256:<64-hex>");
+  }
+  return image;
+}
+
+function validateUser(user: string): string {
+  if (!USER_RE.test(user)) {
+    throw new DockerSandboxError("user must be numeric uid:gid");
+  }
+  const [uid, gid] = user.split(":").map((part) => Number(part));
+  if (uid === 0 || gid === 0) {
+    throw new DockerSandboxError("user must be non-root (uid and gid != 0)");
+  }
+  return user;
+}
+
+function validateEnv(env: Readonly<Record<string, string>> | undefined, limits: ResolvedDockerSandboxLimits): Record<string, string> {
+  const entries = Object.entries(env ?? {});
+  if (entries.length > limits.maxEnvNames) {
+    throw new DockerSandboxError(`env exceeds maxEnvNames (${limits.maxEnvNames})`);
+  }
+  let bytes = 0;
+  const out: Record<string, string> = {};
+  for (const [name, value] of entries) {
+    if (!ENV_NAME_RE.test(name)) {
+      throw new DockerSandboxError(`invalid env name: ${name}`);
+    }
+    if (typeof value !== "string") {
+      throw new DockerSandboxError(`env value for ${name} must be a string`);
+    }
+    bytes += Buffer.byteLength(name, "utf8") + Buffer.byteLength(value, "utf8");
+    if (bytes > limits.maxEnvBytes) {
+      throw new DockerSandboxError(`env exceeds maxEnvBytes (${limits.maxEnvBytes})`);
+    }
+    out[name] = value;
+  }
+  return out;
+}
+
+function validateNetwork(network: DockerNetworkConfig | undefined): DockerNetworkConfig {
+  if (!network || network.mode === "none") return { mode: "none" };
+  if (network.mode !== "custom" || !network.name || /[\s\\]/.test(network.name)) {
+    throw new DockerSandboxError("custom network requires a non-empty name without whitespace");
+  }
+  if (network.egress) assertEgressAttestation(network.egress);
+  return network;
+}
+
+async function validateSourceRoot(sourceRoot: string): Promise<string> {
+  if (!isAbsolute(sourceRoot)) {
+    throw new DockerSandboxError("sourceRoot must be an absolute path");
+  }
+  try {
+    await access(sourceRoot, fsConstants.R_OK);
+  } catch {
+    throw new DockerSandboxError(`sourceRoot is missing or unreadable: ${sourceRoot}`);
+  }
+  return await realpath(sourceRoot);
+}
+
+function buildCreateArgs(input: {
+  image: string;
+  sourceRoot: string;
+  user: string;
+  network: DockerNetworkConfig;
+  limits: ResolvedDockerSandboxLimits;
+  env: Record<string, string>;
+  workdir: string;
+  labels: Record<string, string>;
+}): string[] {
+  const args = [
+    "create",
+    "--pull=never",
+    "--read-only",
+    "--init",
+    "--restart=no",
+    `--user=${input.user}`,
+    `--workdir=${input.workdir}`,
+    `--pids-limit=${input.limits.maxPids}`,
+    `--memory=${input.limits.memoryBytes}`,
+    `--memory-swap=${input.limits.memoryBytes}`,
+    `--cpus=${input.limits.cpus}`,
+    "--ulimit",
+    `nofile=${input.limits.maxFds}:${input.limits.maxFds}`,
+    "--cap-drop=ALL",
+    "--security-opt",
+    "no-new-privileges=true",
+    "--ipc=private",
+    `--stop-timeout=${Math.max(1, Math.ceil(input.limits.stopGraceMs / 1000))}`,
+    `--mount=type=bind,src=${input.sourceRoot},dst=${SOURCE_MOUNT},readonly`,
+    "--tmpfs",
+    formatTmpfs(WORKSPACE_MOUNT, input.limits.workspaceBytes, "1777"),
+    "--tmpfs",
+    formatTmpfs(TMP_MOUNT, input.limits.tmpBytes, "1777"),
+    "--tmpfs",
+    formatTmpfs(DOWNLOAD_MOUNT, input.limits.downloadBytes, "1777"),
+  ];
+
+  if (input.network.mode === "none") args.push("--network=none");
+  else {
+    args.push(`--network=${input.network.name}`);
+    if (input.network.egress) {
+      args.push("--label", `prism.egress.endpoint=${input.network.egress.proxyEndpoint}`);
+      args.push("--label", `prism.egress.fingerprint=${input.network.egress.policyFingerprint}`);
+      args.push("--label", `prism.egress.policyVersion=${input.network.egress.policyVersion}`);
+      args.push("--label", "prism.egress.denyDirect=1");
+    }
+  }
+
+  for (const [key, value] of Object.entries(input.labels)) {
+    args.push("--label", `${key}=${value}`);
+  }
+  for (const [key, value] of Object.entries(input.env)) {
+    args.push("--env", `${key}=${value}`);
+  }
+  args.push(input.image, ...KEEP_ALIVE);
+  return args;
+}
+
+async function preflightDocker(docker: string, runner: DockerRunner, redact: (text: string) => string, timeoutMs: number): Promise<void> {
+  await dockerOutputText(runner, {
+    docker,
+    args: ["version", "--format", "{{.Server.Version}}"],
+    timeoutMs,
+    redact,
+  });
+}
+
+async function importSource(input: {
+  docker: string;
+  containerId: string;
+  user: string;
+  sourceRoot: string;
+  limits: ResolvedDockerSandboxLimits;
+  runner: DockerRunner;
+  redact: (text: string) => string;
+}): Promise<SandboxExportMetadata> {
+  const bounds = {
+    maxEntries: input.limits.maxExportEntries,
+    maxBytes: Math.min(input.limits.workspaceBytes, input.limits.maxExportBytes),
+  };
+  // One FS walk into a capped buffer; hash + docker exec share the same bytes (no second tree walk).
+  // ponytail: full import buffered up to maxExportBytes; stream-tee if peak RSS matters.
+  const chunks: Buffer[] = [];
+  for await (const chunk of createImportTarStream(input.sourceRoot, bounds)) {
+    chunks.push(Buffer.from(chunk));
+  }
+  const buf = Buffer.concat(chunks);
+  const summary = await summarizeTarStream(
+    (async function* () {
+      yield buf;
+    })(),
+    bounds,
+  );
+  const result = await input.runner({
+    docker: input.docker,
+    args: ["exec", "-i", "-u", input.user, "-w", WORKSPACE_MOUNT, input.containerId, "tar", "-xf", "-"],
+    stdin: buf,
+    timeoutMs: input.limits.startupTimeoutMs,
+    maxOutputBytes: 1 * 1024 * 1024,
+    redact: input.redact,
+  });
+  if (result.exitCode !== 0) {
+    const detail = result.stderr.toString("utf8").trim() || `exit ${result.exitCode}`;
+    throw new DockerSandboxError(input.redact(`workspace import failed: ${detail}`));
+  }
+  return {
+    sha256: summary.sha256,
+    entryCount: summary.entryCount,
+    byteCount: summary.byteCount,
+    format: "tar",
+  };
+}
+
+export interface DockerProcessRefData {
+  readonly version: 1;
+  readonly containerId: string;
+  readonly processId: string;
+  readonly commandFingerprint: string;
+  readonly workspace: string;
+}
+
+export function encodeDockerProcessRef(data: DockerProcessRefData): string {
+  const json = JSON.stringify({
+    v: 1,
+    cid: data.containerId,
+    pid: data.processId,
+    fp: data.commandFingerprint,
+    ws: data.workspace,
+  });
+  return `prism-docker-proc:${Buffer.from(json, "utf8").toString("base64url")}`;
+}
+
+export function decodeDockerProcessRef(ref: string): DockerProcessRefData | null {
+  if (!ref.startsWith("prism-docker-proc:")) return null;
+  const raw = ref.slice("prism-docker-proc:".length);
+  try {
+    const json = Buffer.from(raw, "base64url").toString("utf8");
+    const parsed = JSON.parse(json);
+    if (
+      parsed.v !== 1 ||
+      typeof parsed.cid !== "string" ||
+      typeof parsed.pid !== "string" ||
+      typeof parsed.fp !== "string" ||
+      typeof parsed.ws !== "string"
+    ) {
+      return null;
+    }
+    return {
+      version: 1,
+      containerId: parsed.cid,
+      processId: parsed.pid,
+      commandFingerprint: parsed.fp,
+      workspace: parsed.ws,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function computeCommandFingerprint(file: string, args: readonly string[] = []): string {
+  return sha256Hex(JSON.stringify([file, ...args]));
+}
+
+class DockerProcessHandle implements SandboxProcessHandle {
+  private childProcess: ChildProcessWithoutNullStreams | undefined;
+  private readonly stdinStream: PassThrough;
+  private readonly abortController: AbortController;
+  private _exited = false;
+  private _exitCode: number | null = null;
+  private _released = false;
+  private readonly waiters: Array<() => void> = [];
+  readonly ref: string;
+  readonly commandFingerprint: string;
+  readonly workspace: string;
+  readonly processId: string;
+  readonly containerId: string;
+
+  constructor(opts: {
+    readonly processId: string;
+    readonly containerId: string;
+    readonly commandFingerprint: string;
+    readonly workspace: string;
+    readonly ref: string;
+    readonly stdinStream: PassThrough;
+    readonly abortController: AbortController;
+  }) {
+    this.processId = opts.processId;
+    this.containerId = opts.containerId;
+    this.commandFingerprint = opts.commandFingerprint;
+    this.workspace = opts.workspace;
+    this.ref = opts.ref;
+    this.stdinStream = opts.stdinStream;
+    this.abortController = opts.abortController;
+  }
+
+  get pid(): number | undefined {
+    return this.childProcess?.pid;
+  }
+
+  setChild(child: ChildProcessWithoutNullStreams): void {
+    this.childProcess = child;
+  }
+
+  markExited(exitCode: number | null): void {
+    if (this._exited) return;
+    this._exited = true;
+    this._exitCode = exitCode;
+    for (const waiter of this.waiters) waiter();
+    this.waiters.length = 0;
+  }
+
+  get isExited(): boolean {
+    return this._exited;
+  }
+
+  async write(data: Uint8Array | string): Promise<void> {
+    if (this._exited || this._released) {
+      throw new DockerSandboxError("process is not running");
+    }
+    const buf = typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.isBuffer(data) ? data : Buffer.from(data);
+    await new Promise<void>((resolve, reject) => {
+      this.stdinStream.write(buf, (err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+  }
+
+  async signal(name: NodeJS.Signals | number | string): Promise<void> {
+    if (this._exited) {
+      throw new DockerSandboxError("process is not running");
+    }
+    if (name === "SIGKILL" || name === 9) {
+      await this.kill();
+      return;
+    }
+    if (this.childProcess) {
+      try {
+        this.childProcess.kill(name as NodeJS.Signals);
+      } catch {
+        // best effort
+      }
+    }
+  }
+
+  async kill(): Promise<void> {
+    if (this._exited) return;
+    this.abortController.abort();
+    try {
+      this.childProcess?.kill("SIGKILL");
+    } catch {
+      // ignore
+    }
+    try {
+      this.stdinStream.end();
+    } catch {
+      // ignore
+    }
+  }
+
+  async release(): Promise<void> {
+    if (this._exited) return;
+    this._released = true;
+    try {
+      this.stdinStream.end();
+    } catch {
+      // ignore
+    }
+    try {
+      this.childProcess?.unref();
+    } catch {
+      // ignore
+    }
+  }
+
+  async wait(waitOptions?: { timeoutMs?: number; signal?: AbortSignal }): Promise<{ exitCode: number | null }> {
+    if (this._exited) return { exitCode: this._exitCode };
+    return await new Promise<{ exitCode: number | null }>((resolve, reject) => {
+      const onExit = () => {
+        cleanup();
+        resolve({ exitCode: this._exitCode });
+      };
+      const onAbort = () => {
+        cleanup();
+        reject(new DockerSandboxError("wait aborted"));
+      };
+      let timer: NodeJS.Timeout | undefined;
+      const cleanup = () => {
+        if (timer) clearTimeout(timer);
+        waitOptions?.signal?.removeEventListener("abort", onAbort);
+        const idx = this.waiters.indexOf(onExit);
+        if (idx >= 0) this.waiters.splice(idx, 1);
+      };
+      this.waiters.push(onExit);
+      if (waitOptions?.timeoutMs !== undefined) {
+        timer = setTimeout(() => {
+          cleanup();
+          reject(new DockerSandboxError(`wait timed out after ${waitOptions.timeoutMs}ms`));
+        }, waitOptions.timeoutMs);
+      }
+      if (waitOptions?.signal) {
+        if (waitOptions.signal.aborted) onAbort();
+        else waitOptions.signal.addEventListener("abort", onAbort, { once: true });
+      }
+    });
+  }
+}
+
+class DockerSandboxSession implements DisposableSandbox {
+  readonly id: string;
+  readonly capabilities: SandboxCapabilities;
+  readonly importIdentity?: SandboxExportMetadata;
+  readonly labels?: Readonly<Record<string, string>>;
+  private _lastExportIdentity: SandboxExportMetadata | undefined;
+  private state: SandboxStatusState = "running";
+  private commandCount = 0;
+  private retainedArtifacts = 0;
+  private readonly startedAt = Date.now();
+  private lastActivityAt = Date.now();
+  private closing: Promise<SandboxExportMetadata | undefined> | undefined;
+  private readonly execLock: Semaphore;
+  private readonly redact: (text: string) => string;
+  private readonly activeProcesses = new Map<string, DockerProcessHandle>();
+
+  constructor(
+    private readonly opts: {
+      readonly containerId: string;
+      readonly docker: string;
+      readonly image: string;
+      readonly user: string;
+      readonly workdir: string;
+      readonly limits: ResolvedDockerSandboxLimits;
+      readonly runner: DockerRunner;
+      readonly secrets: readonly string[];
+      readonly capabilities: SandboxCapabilities;
+      readonly importIdentity?: SandboxExportMetadata;
+      readonly labels?: Readonly<Record<string, string>>;
+    },
+  ) {
+    this.id = opts.containerId;
+    this.capabilities = opts.capabilities;
+    this.importIdentity = opts.importIdentity;
+    this.labels = opts.labels;
+    this.execLock = new Semaphore(opts.limits.maxConcurrentExecs, DockerSandboxError);
+    this.redact = createSecretRedactor(opts.secrets);
+  }
+
+  get lastExportIdentity(): SandboxExportMetadata | undefined {
+    return this._lastExportIdentity;
+  }
+
+  private touch(): void {
+    this.lastActivityAt = Date.now();
+  }
+
+  private remainingWallMs(): number {
+    return Math.max(1, this.opts.limits.wallTimeMs - (Date.now() - this.startedAt));
+  }
+
+  private assertActive(): void {
+    if (this.state !== "running") throw new DockerSandboxError(`sandbox is ${this.state}`);
+    const now = Date.now();
+    if (now - this.startedAt > this.opts.limits.wallTimeMs) {
+      this.state = "failed";
+      throw new DockerSandboxError("sandbox wall time exceeded");
+    }
+    if (now - this.lastActivityAt > this.opts.limits.idleTimeoutMs) {
+      this.state = "failed";
+      throw new DockerSandboxError("sandbox idle timeout exceeded");
+    }
+  }
+
+  async status(): Promise<SandboxStatus> {
+    return {
+      id: this.opts.containerId,
+      state: this.state,
+      image: this.opts.image,
+      startedAt: this.startedAt,
+      commandCount: this.commandCount,
+      lastActivityAt: this.lastActivityAt,
+      ...(this.importIdentity ? { importIdentity: this.importIdentity } : {}),
+      ...(this._lastExportIdentity ? { lastExportIdentity: this._lastExportIdentity } : {}),
+    };
+  }
+
+  async exec(request: SandboxExecRequest): Promise<{ exitCode: number | null }> {
+    return this.execFile({
+      file: "/bin/sh",
+      args: ["-c", request.command],
+      cwd: request.cwd,
+      env: request.env as Record<string, string> | undefined,
+      onData: request.onData,
+      signal: request.signal,
+      timeout: request.timeout,
+    });
+  }
+
+  async execFile(request: SandboxExecFileRequest): Promise<{ exitCode: number | null }> {
+    this.assertActive();
+    if (!request.file || request.file.includes("\0")) {
+      throw new DockerSandboxError("execFile requires a non-empty file path");
+    }
+    if (!Array.isArray(request.args) || request.args.some((a) => typeof a !== "string" || a.includes("\0"))) {
+      throw new DockerSandboxError("execFile args must be a string array without NUL");
+    }
+    if (this.commandCount >= this.opts.limits.maxCommands) {
+      throw new DockerSandboxError(`sandbox exceeded maxCommands (${this.opts.limits.maxCommands})`);
+    }
+    const release = await this.execLock.acquire(request.signal);
+    this.commandCount += 1;
+    this.touch();
+    try {
+      this.assertActive();
+      const cwd = request.cwd ?? this.opts.workdir;
+      if (!cwd.startsWith("/") || cwd.includes("\0")) {
+        throw new DockerSandboxError("cwd must be an absolute container path");
+      }
+      const args = ["exec", "-u", this.opts.user, "-w", cwd];
+      const extraEnv = validateEnv(request.env, this.opts.limits);
+      for (const [key, value] of Object.entries(extraEnv)) {
+        args.push("-e", `${key}=${value}`);
+      }
+      args.push(this.opts.containerId, request.file, ...request.args);
+      const timeoutMs = request.timeout !== undefined ? Math.min(request.timeout, this.remainingWallMs()) : this.remainingWallMs();
+      let outputBytes = 0;
+      const result = await this.opts.runner({
+        docker: this.opts.docker,
+        args,
+        signal: request.signal,
+        timeoutMs,
+        maxOutputBytes: this.opts.limits.maxOutputBytes,
+        collectStdout: false,
+        collectStderr: false,
+        redact: this.redact,
+        onData: (chunk) => {
+          outputBytes += chunk.byteLength;
+          if (outputBytes > this.opts.limits.maxOutputBytes) {
+            throw new DockerSandboxError(`command output exceeded maxOutputBytes (${this.opts.limits.maxOutputBytes})`);
+          }
+          request.onData?.(chunk);
+        },
+      });
+      this.touch();
+      return { exitCode: result.exitCode };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new DockerSandboxError(this.redact(message));
+    } finally {
+      release();
+    }
+  }
+
+  async startProcess(request: SandboxExecFileRequest): Promise<SandboxProcessHandle> {
+    this.assertActive();
+    const file = request.file ?? (request as unknown as { command?: string }).command;
+    if (!file || file.includes("\0")) {
+      throw new DockerSandboxError("startProcess requires a non-empty file path");
+    }
+    const args = request.args ?? [];
+    if (!Array.isArray(args) || args.some((a) => typeof a !== "string" || a.includes("\0"))) {
+      throw new DockerSandboxError("startProcess args must be a string array without NUL");
+    }
+    if (this.commandCount >= this.opts.limits.maxCommands) {
+      throw new DockerSandboxError(`sandbox exceeded maxCommands (${this.opts.limits.maxCommands})`);
+    }
+
+    const releaseLock = await this.execLock.acquire(request.signal);
+    this.commandCount += 1;
+    this.touch();
+
+    let lockReleased = false;
+    const releaseLockOnce = () => {
+      if (!lockReleased) {
+        lockReleased = true;
+        releaseLock();
+      }
+    };
+
+    try {
+      this.assertActive();
+      const cwd = request.cwd ?? this.opts.workdir;
+      if (!cwd.startsWith("/") || cwd.includes("\0")) {
+        throw new DockerSandboxError("cwd must be an absolute container path");
+      }
+
+      const execArgs = ["exec", "-i", "-u", this.opts.user, "-w", cwd];
+      const extraEnv = validateEnv(request.env, this.opts.limits);
+      for (const [key, value] of Object.entries(extraEnv)) {
+        execArgs.push("-e", `${key}=${value}`);
+      }
+      execArgs.push(this.opts.containerId, file, ...args);
+
+      const processId = randomUUID();
+      const commandFingerprint = computeCommandFingerprint(file, args);
+      const ref = encodeDockerProcessRef({
+        version: 1,
+        containerId: this.opts.containerId,
+        processId,
+        commandFingerprint,
+        workspace: this.opts.workdir,
+      });
+
+      const stdinStream = new PassThrough();
+      const abortController = new AbortController();
+
+      const combinedSignal = request.signal ? AbortSignal.any([request.signal, abortController.signal]) : abortController.signal;
+
+      const handle = new DockerProcessHandle({
+        processId,
+        containerId: this.opts.containerId,
+        commandFingerprint,
+        workspace: this.opts.workdir,
+        ref,
+        stdinStream,
+        abortController,
+      });
+
+      this.activeProcesses.set(processId, handle);
+
+      const timeoutMs = request.timeout !== undefined ? Math.min(request.timeout, this.remainingWallMs()) : this.remainingWallMs();
+
+      let outputBytes = 0;
+      let spawned = false;
+      let resolveSpawn!: () => void;
+      let rejectSpawn!: (err: unknown) => void;
+      const spawnPromise = new Promise<void>((resolve, reject) => {
+        resolveSpawn = () => {
+          if (!spawned) {
+            spawned = true;
+            resolve();
+          }
+        };
+        rejectSpawn = (err) => {
+          if (!spawned) {
+            spawned = true;
+            reject(err);
+          }
+        };
+      });
+
+      const fallbackTimer = setImmediate(() => {
+        resolveSpawn();
+      });
+
+      const runPromise = this.opts.runner({
+        docker: this.opts.docker,
+        args: execArgs,
+        stdin: stdinStream,
+        signal: combinedSignal,
+        timeoutMs,
+        maxOutputBytes: this.opts.limits.maxOutputBytes,
+        collectStdout: false,
+        collectStderr: false,
+        redact: this.redact,
+        onSpawn: (child) => {
+          clearImmediate(fallbackTimer);
+          handle.setChild(child);
+          resolveSpawn();
+        },
+        onData: (chunk) => {
+          outputBytes += chunk.byteLength;
+          if (outputBytes > this.opts.limits.maxOutputBytes) {
+            handle.kill().catch(() => undefined);
+            throw new DockerSandboxError(`command output exceeded maxOutputBytes (${this.opts.limits.maxOutputBytes})`);
+          }
+          request.onData?.(chunk);
+        },
+      });
+
+      runPromise.then(
+        (result) => {
+          clearImmediate(fallbackTimer);
+          resolveSpawn();
+          this.activeProcesses.delete(processId);
+          releaseLockOnce();
+          this.touch();
+          handle.markExited(result.exitCode);
+        },
+        (error) => {
+          clearImmediate(fallbackTimer);
+          rejectSpawn(error);
+          this.activeProcesses.delete(processId);
+          releaseLockOnce();
+          this.touch();
+          const exitCode = handle.isExited ? null : 1;
+          handle.markExited(exitCode);
+        },
+      );
+
+      await spawnPromise;
+      return handle;
+    } catch (error) {
+      releaseLockOnce();
+      const message = error instanceof Error ? error.message : String(error);
+      throw new DockerSandboxError(this.redact(message));
+    }
+  }
+
+  async attachProcess(ref: string): Promise<SandboxProcessHandle | null> {
+    if (this.state !== "running") return null;
+    const decoded = decodeDockerProcessRef(ref);
+    if (!decoded) return null;
+    if (decoded.containerId !== this.opts.containerId) return null;
+    if (decoded.workspace !== this.opts.workdir) return null;
+    const handle = this.activeProcesses.get(decoded.processId);
+    if (!handle || handle.isExited) return null;
+    if (handle.ref !== ref) return null;
+    return handle;
+  }
+
+  async stop(options?: { graceMs?: number; signal?: AbortSignal }): Promise<void> {
+    for (const proc of this.activeProcesses.values()) {
+      await proc.kill().catch(() => undefined);
+    }
+    this.activeProcesses.clear();
+    if (this.state === "removed" || this.state === "stopped") return;
+    const graceMs = Math.min(options?.graceMs ?? this.opts.limits.stopGraceMs, this.opts.limits.stopGraceMs);
+    const seconds = Math.max(1, Math.ceil(graceMs / 1000));
+    const result = await this.opts.runner({
+      docker: this.opts.docker,
+      args: ["stop", "--time", String(seconds), this.opts.containerId],
+      signal: options?.signal,
+      timeoutMs: this.opts.limits.cleanupDeadlineMs,
+      redact: this.redact,
+    });
+    if (result.exitCode !== 0) {
+      const detail = result.stderr.toString("utf8").trim();
+      if (!/no such container/i.test(detail)) {
+        throw new DockerSandboxError(this.redact(detail || "docker stop failed"));
+      }
+    }
+    this.state = "stopped";
+  }
+
+  async kill(options?: { signal?: AbortSignal }): Promise<void> {
+    for (const proc of this.activeProcesses.values()) {
+      await proc.kill().catch(() => undefined);
+    }
+    this.activeProcesses.clear();
+    if (this.state === "removed") return;
+    const result = await this.opts.runner({
+      docker: this.opts.docker,
+      args: ["kill", this.opts.containerId],
+      signal: options?.signal,
+      timeoutMs: this.opts.limits.cleanupDeadlineMs,
+      redact: this.redact,
+    });
+    if (result.exitCode !== 0) {
+      const detail = result.stderr.toString("utf8").trim();
+      if (!/no such container|is not running/i.test(detail)) {
+        throw new DockerSandboxError(this.redact(detail || "docker kill failed"));
+      }
+    }
+    this.state = "stopped";
+  }
+
+  private async remove(signal?: AbortSignal): Promise<void> {
+    if (this.state === "removed") return;
+    const result = await this.opts.runner({
+      docker: this.opts.docker,
+      args: ["rm", "-f", this.opts.containerId],
+      signal,
+      timeoutMs: this.opts.limits.cleanupDeadlineMs,
+      redact: this.redact,
+    });
+    if (result.exitCode !== 0) {
+      const detail = result.stderr.toString("utf8").trim();
+      if (!/no such container/i.test(detail)) {
+        throw new DockerSandboxError(this.redact(`cleanup failed: ${detail || "docker rm failed"}`));
+      }
+    }
+    this.state = "removed";
+  }
+
+  private async exportTwoPass(write: NonNullable<SandboxCloseOptions["export"]>, signal?: AbortSignal): Promise<SandboxExportMetadata> {
+    if (this.retainedArtifacts >= this.opts.limits.maxRetainedArtifacts) {
+      throw new DockerSandboxError(`sandbox exceeded maxRetainedArtifacts (${this.opts.limits.maxRetainedArtifacts})`);
+    }
+
+    const pass1 = new PassThrough();
+    const summaryPromise = summarizeTarStream(pass1, {
+      maxEntries: this.opts.limits.maxExportEntries,
+      maxBytes: this.opts.limits.maxExportBytes,
+    });
+    const run1 = this.opts
+      .runner({
+        docker: this.opts.docker,
+        args: ["exec", "-u", this.opts.user, "-w", WORKSPACE_MOUNT, this.opts.containerId, "tar", "-cf", "-", "."],
+        signal,
+        timeoutMs: this.remainingWallMs(),
+        maxOutputBytes: this.opts.limits.maxExportBytes,
+        collectStdout: false,
+        collectStderr: true,
+        redact: this.redact,
+        onStdout: (chunk) => pass1.write(chunk),
+      })
+      .then((result) => {
+        pass1.end();
+        if (result.exitCode !== 0) {
+          const detail = result.stderr.toString("utf8").trim() || `exit ${result.exitCode}`;
+          throw new DockerSandboxError(this.redact(`export failed: ${detail}`));
+        }
+      });
+    const summary = await summaryPromise;
+    await run1;
+
+    const metadata: SandboxExportMetadata = {
+      sha256: summary.sha256,
+      entryCount: summary.entryCount,
+      byteCount: summary.byteCount,
+      format: "tar",
+    };
+
+    const pass2 = new PassThrough();
+    const hostStream = new PassThrough();
+    const verifyPromise = summarizeTarStream(pass2, {
+      maxEntries: this.opts.limits.maxExportEntries,
+      maxBytes: this.opts.limits.maxExportBytes,
+    });
+    pass2.on("data", (chunk: Buffer) => hostStream.write(chunk));
+    pass2.on("end", () => hostStream.end());
+    pass2.on("error", (error) => hostStream.destroy(error));
+
+    const hostWrite = write(hostStream, metadata);
+    const run2 = this.opts
+      .runner({
+        docker: this.opts.docker,
+        args: ["exec", "-u", this.opts.user, "-w", WORKSPACE_MOUNT, this.opts.containerId, "tar", "-cf", "-", "."],
+        signal,
+        timeoutMs: this.remainingWallMs(),
+        maxOutputBytes: this.opts.limits.maxExportBytes,
+        collectStdout: false,
+        collectStderr: true,
+        redact: this.redact,
+        onStdout: (chunk) => pass2.write(chunk),
+      })
+      .then((result) => {
+        pass2.end();
+        if (result.exitCode !== 0) {
+          const detail = result.stderr.toString("utf8").trim() || `exit ${result.exitCode}`;
+          throw new DockerSandboxError(this.redact(`export failed: ${detail}`));
+        }
+      });
+
+    try {
+      const verify = await verifyPromise;
+      await run2;
+      await hostWrite;
+      if (verify.sha256 !== metadata.sha256 || verify.byteCount !== metadata.byteCount) {
+        throw new DockerSandboxError("export hash mismatch between passes");
+      }
+      this.retainedArtifacts += 1;
+      this._lastExportIdentity = metadata;
+      this.touch();
+      return metadata;
+    } catch (error) {
+      hostStream.destroy(error instanceof Error ? error : new Error(String(error)));
+      const message = error instanceof Error ? error.message : String(error);
+      throw new DockerSandboxError(this.redact(message));
+    }
+  }
+
+  async close(options?: SandboxCloseOptions): Promise<SandboxExportMetadata | undefined> {
+    if (this.closing) return this.closing;
+    this.closing = (async () => {
+      let metadata: SandboxExportMetadata | undefined;
+      try {
+        if (options?.export && this.state === "running") {
+          metadata = await this.exportTwoPass(options.export, options.signal);
+        }
+      } catch (error) {
+        try {
+          await this.stop({ signal: options?.signal });
+        } catch {
+          await this.kill({ signal: options?.signal }).catch(() => undefined);
+        }
+        await this.remove(options?.signal).catch(() => undefined);
+        const message = error instanceof Error ? error.message : String(error);
+        throw new DockerSandboxError(this.redact(message));
+      }
+
+      try {
+        await this.stop({ signal: options?.signal });
+      } catch {
+        await this.kill({ signal: options?.signal });
+      }
+      await this.remove(options?.signal);
+      return metadata;
+    })();
+    return this.closing;
+  }
+}
+
+export async function createDockerSandbox(options: CreateDockerSandboxOptions): Promise<DisposableSandbox> {
+  const docker = await assertAbsoluteExecutable(options.docker, "docker");
+  const image = validateImage(options.image);
+  const user = validateUser(options.user);
+  const limits = resolveDockerSandboxLimits(options.limits);
+  const env = validateEnv(options.env, limits);
+  const network = validateNetwork(options.network);
+  const sourceRoot = await validateSourceRoot(options.sourceRoot);
+  const workdir = options.workdir ?? WORKSPACE_MOUNT;
+  if (!workdir.startsWith("/")) {
+    throw new DockerSandboxError("workdir must be an absolute container path");
+  }
+  const runner = options.runner ?? runDockerCli;
+  const secrets = options.secrets ?? [];
+  const redact = createSecretRedactor(secrets);
+  const sandboxKey = randomUUID();
+  const labels: Record<string, string> = {
+    "prism.sandbox": "1",
+    "prism.sandbox.id": sandboxKey,
+    ...(options.labels ?? {}),
+  };
+  for (const [key, value] of Object.entries(labels)) {
+    if (!key || /[\s=]/.test(key) || value.includes("\n")) {
+      throw new DockerSandboxError("invalid sandbox label");
+    }
+  }
+
+  await preflightDocker(docker, runner, redact, limits.startupTimeoutMs);
+
+  const createArgs = buildCreateArgs({
+    image,
+    sourceRoot,
+    user,
+    network,
+    limits,
+    env,
+    workdir,
+    labels,
+  });
+
+  let containerId = "";
+  try {
+    containerId = (
+      await dockerOutputText(runner, {
+        docker,
+        args: createArgs,
+        timeoutMs: limits.startupTimeoutMs,
+        redact,
+      })
+    ).trim();
+    if (!/^[a-f0-9]{12,64}$/i.test(containerId)) {
+      throw new DockerSandboxError("docker create returned an invalid container id");
+    }
+
+    const start = await runner({
+      docker,
+      args: ["start", containerId],
+      timeoutMs: limits.startupTimeoutMs,
+      redact,
+    });
+    if (start.exitCode !== 0) {
+      throw new DockerSandboxError(redact(start.stderr.toString("utf8").trim() || "docker start failed"));
+    }
+
+    let importIdentity: SandboxExportMetadata | undefined;
+    if (!options.skipImport) {
+      importIdentity = await importSource({
+        docker,
+        containerId,
+        user,
+        sourceRoot,
+        limits,
+        runner,
+        redact,
+      });
+    }
+
+    return new DockerSandboxSession({
+      containerId,
+      docker,
+      image,
+      user,
+      workdir,
+      limits,
+      runner,
+      secrets,
+      capabilities: resolveDockerCapabilities(network),
+      importIdentity,
+      labels,
+    });
+  } catch (error) {
+    if (containerId) {
+      await runner({
+        docker,
+        args: ["rm", "-f", containerId],
+        timeoutMs: limits.cleanupDeadlineMs,
+        redact,
+      }).catch(() => undefined);
+    }
+    if (error instanceof DockerSandboxError || error instanceof DockerCliError || error instanceof SandboxTarError) {
+      throw new DockerSandboxError(redact(error.message));
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    throw new DockerSandboxError(redact(message));
+  }
+}
+
+export interface DockerProcessRecoveryBackendOptions {
+  readonly expectedContainerId?: string;
+  readonly expectedWorkspace?: string;
+  readonly expectedLabels?: Readonly<Record<string, string>>;
+}
+
+export function createDockerProcessRecoveryBackend(
+  sandbox: DisposableSandbox,
+  options?: DockerProcessRecoveryBackendOptions,
+): ProcessRecoveryBackend {
+  return {
+    async attach(ref: string): Promise<ProcessSandboxHandle | null> {
+      if (!sandbox || typeof sandbox.attachProcess !== "function") {
+        return null;
+      }
+      const decoded = decodeDockerProcessRef(ref);
+      if (!decoded) {
+        return null;
+      }
+      if (options?.expectedContainerId && decoded.containerId !== options.expectedContainerId) {
+        return null;
+      }
+      if (options?.expectedWorkspace && decoded.workspace !== options.expectedWorkspace) {
+        return null;
+      }
+      if (options?.expectedLabels && sandbox.labels) {
+        const sandboxLabels = sandbox.labels as Record<string, string>;
+        for (const [key, value] of Object.entries(options.expectedLabels)) {
+          if (sandboxLabels[key] !== value) {
+            return null;
+          }
+        }
+      }
+      const handle = await sandbox.attachProcess(ref);
+      return (handle as unknown as ProcessSandboxHandle) ?? null;
+    },
+  };
+}
+
+/** @internal test helper: build create argv without starting Docker. */
+export function buildDockerCreateArgsForTest(options: Omit<CreateDockerSandboxOptions, "docker" | "runner" | "skipImport">): string[] {
+  const limits = resolveDockerSandboxLimits(options.limits);
+  const env = validateEnv(options.env, limits);
+  const network = validateNetwork(options.network);
+  const user = validateUser(options.user);
+  const image = validateImage(options.image);
+  return buildCreateArgs({
+    image,
+    sourceRoot: options.sourceRoot,
+    user,
+    network,
+    limits,
+    env,
+    workdir: options.workdir ?? WORKSPACE_MOUNT,
+    labels: {
+      "prism.sandbox": "1",
+      "prism.sandbox.id": "test",
+      ...(options.labels ?? {}),
+    },
+  });
+}