@arnilo/prism-tools 0.0.0-stage → 0.13.0

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

@@ -0,0 +1,147 @@
+/** Finite defaults and hard caps for the disposable Docker sandbox reference. */
+
+export const DEFAULT_STARTUP_TIMEOUT_MS = 30_000;
+export const HARD_STARTUP_TIMEOUT_MS = 120_000;
+export const DEFAULT_WALL_TIME_MS = 20 * 60_000;
+export const HARD_WALL_TIME_MS = 30 * 60_000;
+export const DEFAULT_IDLE_TIMEOUT_MS = 5 * 60_000;
+export const HARD_IDLE_TIMEOUT_MS = 15 * 60_000;
+
+export const DEFAULT_CPUS = 2;
+export const HARD_CPUS = 8;
+export const DEFAULT_MEMORY_BYTES = 2 * 1024 ** 3;
+export const HARD_MEMORY_BYTES = 16 * 1024 ** 3;
+export const DEFAULT_MAX_PIDS = 256;
+export const HARD_MAX_PIDS = 1_024;
+export const DEFAULT_MAX_FDS = 1_024;
+export const HARD_MAX_FDS = 8_192;
+
+export const DEFAULT_WORKSPACE_BYTES = 1024 ** 3;
+export const HARD_WORKSPACE_BYTES = 8 * 1024 ** 3;
+export const DEFAULT_TMP_BYTES = 256 * 1024 ** 2;
+export const HARD_TMP_BYTES = 2 * 1024 ** 3;
+export const DEFAULT_DOWNLOAD_BYTES = 64 * 1024 ** 2;
+export const HARD_DOWNLOAD_BYTES = 512 * 1024 ** 2;
+
+export const DEFAULT_MAX_COMMANDS = 100;
+export const HARD_MAX_COMMANDS = 256;
+export const DEFAULT_MAX_CONCURRENT_EXECS = 1;
+export const HARD_MAX_CONCURRENT_EXECS = 8;
+
+export const DEFAULT_MAX_ENV_NAMES = 64;
+export const HARD_MAX_ENV_NAMES = 256;
+export const DEFAULT_MAX_ENV_BYTES = 64 * 1024;
+export const HARD_MAX_ENV_BYTES = 256 * 1024;
+
+export const DEFAULT_MAX_EXPORT_ENTRIES = 50_000;
+export const HARD_MAX_EXPORT_ENTRIES = 250_000;
+export const DEFAULT_MAX_EXPORT_BYTES = 256 * 1024 ** 2;
+export const HARD_MAX_EXPORT_BYTES = 2 * 1024 ** 3;
+export const DEFAULT_MAX_RETAINED_ARTIFACTS = 16;
+export const HARD_MAX_RETAINED_ARTIFACTS = 64;
+
+export const DEFAULT_STOP_GRACE_MS = 5_000;
+export const HARD_STOP_GRACE_MS = 30_000;
+export const DEFAULT_CLEANUP_DEADLINE_MS = 30_000;
+export const HARD_CLEANUP_DEADLINE_MS = 120_000;
+
+export const DEFAULT_MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+export const HARD_MAX_OUTPUT_BYTES = 1024 * 1024 * 1024;
+
+export interface DockerSandboxLimitOptions {
+  readonly startupTimeoutMs?: number;
+  readonly wallTimeMs?: number;
+  readonly idleTimeoutMs?: number;
+  readonly cpus?: number;
+  readonly memoryBytes?: number;
+  readonly maxPids?: number;
+  readonly maxFds?: number;
+  readonly workspaceBytes?: number;
+  readonly tmpBytes?: number;
+  readonly downloadBytes?: number;
+  readonly maxCommands?: number;
+  readonly maxConcurrentExecs?: number;
+  readonly maxEnvNames?: number;
+  readonly maxEnvBytes?: number;
+  readonly maxExportEntries?: number;
+  readonly maxExportBytes?: number;
+  readonly maxRetainedArtifacts?: number;
+  readonly stopGraceMs?: number;
+  readonly cleanupDeadlineMs?: number;
+  readonly maxOutputBytes?: number;
+}
+
+export interface ResolvedDockerSandboxLimits {
+  readonly startupTimeoutMs: number;
+  readonly wallTimeMs: number;
+  readonly idleTimeoutMs: number;
+  readonly cpus: number;
+  readonly memoryBytes: number;
+  readonly maxPids: number;
+  readonly maxFds: number;
+  readonly workspaceBytes: number;
+  readonly tmpBytes: number;
+  readonly downloadBytes: number;
+  readonly maxCommands: number;
+  readonly maxConcurrentExecs: number;
+  readonly maxEnvNames: number;
+  readonly maxEnvBytes: number;
+  readonly maxExportEntries: number;
+  readonly maxExportEntriesHard: number;
+  readonly maxExportBytes: number;
+  readonly maxRetainedArtifacts: number;
+  readonly stopGraceMs: number;
+  readonly cleanupDeadlineMs: number;
+  readonly maxOutputBytes: number;
+}
+
+const SPECS = {
+  startupTimeoutMs: [DEFAULT_STARTUP_TIMEOUT_MS, HARD_STARTUP_TIMEOUT_MS],
+  wallTimeMs: [DEFAULT_WALL_TIME_MS, HARD_WALL_TIME_MS],
+  idleTimeoutMs: [DEFAULT_IDLE_TIMEOUT_MS, HARD_IDLE_TIMEOUT_MS],
+  memoryBytes: [DEFAULT_MEMORY_BYTES, HARD_MEMORY_BYTES],
+  maxPids: [DEFAULT_MAX_PIDS, HARD_MAX_PIDS],
+  maxFds: [DEFAULT_MAX_FDS, HARD_MAX_FDS],
+  workspaceBytes: [DEFAULT_WORKSPACE_BYTES, HARD_WORKSPACE_BYTES],
+  tmpBytes: [DEFAULT_TMP_BYTES, HARD_TMP_BYTES],
+  downloadBytes: [DEFAULT_DOWNLOAD_BYTES, HARD_DOWNLOAD_BYTES],
+  maxCommands: [DEFAULT_MAX_COMMANDS, HARD_MAX_COMMANDS],
+  maxConcurrentExecs: [DEFAULT_MAX_CONCURRENT_EXECS, HARD_MAX_CONCURRENT_EXECS],
+  maxEnvNames: [DEFAULT_MAX_ENV_NAMES, HARD_MAX_ENV_NAMES],
+  maxEnvBytes: [DEFAULT_MAX_ENV_BYTES, HARD_MAX_ENV_BYTES],
+  maxExportEntries: [DEFAULT_MAX_EXPORT_ENTRIES, HARD_MAX_EXPORT_ENTRIES],
+  maxExportBytes: [DEFAULT_MAX_EXPORT_BYTES, HARD_MAX_EXPORT_BYTES],
+  maxRetainedArtifacts: [DEFAULT_MAX_RETAINED_ARTIFACTS, HARD_MAX_RETAINED_ARTIFACTS],
+  stopGraceMs: [DEFAULT_STOP_GRACE_MS, HARD_STOP_GRACE_MS],
+  cleanupDeadlineMs: [DEFAULT_CLEANUP_DEADLINE_MS, HARD_CLEANUP_DEADLINE_MS],
+  maxOutputBytes: [DEFAULT_MAX_OUTPUT_BYTES, HARD_MAX_OUTPUT_BYTES],
+} as const;
+
+export function validateSandboxLimit(name: string, value: number, hardCap: number): number {
+  if (!Number.isSafeInteger(value) || value < 1 || value > hardCap) {
+    throw new RangeError(`${name} must be a positive safe integer at most ${hardCap}`);
+  }
+  return value;
+}
+
+function validateCpus(value: number): number {
+  if (!Number.isFinite(value) || value <= 0 || value > HARD_CPUS) {
+    throw new RangeError(`cpus must be a finite number greater than 0 and at most ${HARD_CPUS}`);
+  }
+  return value;
+}
+
+export function resolveDockerSandboxLimits(input: DockerSandboxLimitOptions = {}): ResolvedDockerSandboxLimits {
+  const resolved = Object.fromEntries(
+    Object.entries(SPECS).map(([name, [fallback, hardCap]]) => {
+      const value = input[name as keyof DockerSandboxLimitOptions] ?? fallback;
+      return [name, validateSandboxLimit(name, value as number, hardCap)];
+    }),
+  ) as Omit<ResolvedDockerSandboxLimits, "cpus" | "maxExportEntriesHard">;
+
+  return {
+    ...resolved,
+    cpus: validateCpus(input.cpus ?? DEFAULT_CPUS),
+    maxExportEntriesHard: HARD_MAX_EXPORT_ENTRIES,
+  };
+}

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

@@ -0,0 +1,308 @@
+import { createHash, type Hash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, opendir, realpath } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import { Readable } from "node:stream";
+
+export interface TarBounds {
+  readonly maxEntries: number;
+  readonly maxBytes: number;
+}
+
+export interface TarExportSummary {
+  readonly sha256: string;
+  readonly entryCount: number;
+  readonly byteCount: number;
+}
+
+export class SandboxTarError extends Error {
+  readonly code = "ERR_PRISM_SANDBOX_TAR";
+  constructor(message: string) {
+    super(message);
+    this.name = "SandboxTarError";
+  }
+}
+
+const BLOCK = 512;
+
+function encodeOctal(value: number, length: number): Buffer {
+  const body = value.toString(8).padStart(length - 1, "0");
+  return Buffer.from(`${body}\0`, "utf8");
+}
+
+function checksumHeader(header: Buffer): number {
+  let sum = 0;
+  for (let i = 0; i < header.length; i++) sum += header[i];
+  return sum;
+}
+
+function writeUstarHeader(opts: { name: string; size: number; mode: number; mtimeSec: number; type: "0" | "5" }): Buffer {
+  if (Buffer.byteLength(opts.name, "utf8") > 100) {
+    throw new SandboxTarError(`tar path exceeds 100 UTF-8 bytes: ${opts.name}`);
+  }
+  const header = Buffer.alloc(BLOCK, 0);
+  header.write(opts.name, 0, 100, "utf8");
+  encodeOctal(opts.mode & 0o7777, 8).copy(header, 100);
+  encodeOctal(0, 8).copy(header, 108);
+  encodeOctal(0, 8).copy(header, 116);
+  encodeOctal(opts.size, 12).copy(header, 124);
+  encodeOctal(opts.mtimeSec, 12).copy(header, 136);
+  header.write("        ", 148, 8, "utf8");
+  header.write(opts.type, 156, 1, "utf8");
+  header.write("ustar\0", 257, 6, "utf8");
+  header.write("00", 263, 2, "utf8");
+  const sum = checksumHeader(header);
+  const checksum = Buffer.from(`${sum.toString(8).padStart(6, "0")}\0 `, "utf8");
+  checksum.copy(header, 148);
+  return header;
+}
+
+function padToBlock(size: number): number {
+  const rem = size % BLOCK;
+  return rem === 0 ? 0 : BLOCK - rem;
+}
+
+interface WalkEntry {
+  readonly abs: string;
+  readonly rel: string;
+  readonly size: number;
+  readonly mode: number;
+  readonly dir: boolean;
+}
+
+async function* walkRegularFiles(root: string, bounds: TarBounds): AsyncGenerator<WalkEntry> {
+  const rootReal = await realpath(root);
+  let entries = 0;
+  let bytes = 0;
+
+  async function* visit(dirReal: string): AsyncGenerator<WalkEntry> {
+    const handle = await opendir(dirReal);
+    try {
+      for await (const dirent of handle) {
+        const abs = join(dirReal, dirent.name);
+        const st = await lstat(abs);
+        if (st.isSymbolicLink()) {
+          throw new SandboxTarError(`symlink rejected during sandbox import: ${abs}`);
+        }
+        if (st.isFIFO() || st.isSocket() || st.isCharacterDevice() || st.isBlockDevice()) {
+          throw new SandboxTarError(`special file rejected during sandbox import: ${abs}`);
+        }
+        const relToRoot = relative(rootReal, abs);
+        if (relToRoot.startsWith("..") || relToRoot.includes(`..${sep}`)) {
+          throw new SandboxTarError(`path escape rejected during sandbox import: ${abs}`);
+        }
+        const rel = relToRoot.split(sep).join("/");
+        entries += 1;
+        if (entries > bounds.maxEntries) {
+          throw new SandboxTarError(`import exceeded max entries (${bounds.maxEntries})`);
+        }
+        if (st.isDirectory()) {
+          if (rel !== "") {
+            yield { abs, rel: `${rel}/`, size: 0, mode: st.mode, dir: true };
+          }
+          const childReal = await realpath(abs);
+          if (relative(rootReal, childReal).startsWith("..")) {
+            throw new SandboxTarError(`directory escape rejected during sandbox import: ${abs}`);
+          }
+          yield* visit(childReal);
+          continue;
+        }
+        if (!st.isFile()) {
+          throw new SandboxTarError(`unsupported file type during sandbox import: ${abs}`);
+        }
+        bytes += st.size;
+        if (bytes > bounds.maxBytes) {
+          throw new SandboxTarError(`import exceeded max bytes (${bounds.maxBytes})`);
+        }
+        yield { abs, rel, size: st.size, mode: st.mode, dir: false };
+      }
+    } finally {
+      await handle.close().catch(() => undefined);
+    }
+  }
+
+  yield* visit(rootReal);
+}
+
+async function* importTarBlocks(sourceRoot: string, bounds: TarBounds): AsyncGenerator<Buffer> {
+  const mtimeSec = Math.floor(Date.now() / 1000);
+  for await (const entry of walkRegularFiles(sourceRoot, bounds)) {
+    if (entry.dir) {
+      yield writeUstarHeader({
+        name: entry.rel.endsWith("/") ? entry.rel : `${entry.rel}/`,
+        size: 0,
+        mode: entry.mode,
+        mtimeSec,
+        type: "5",
+      });
+      continue;
+    }
+    yield writeUstarHeader({
+      name: entry.rel,
+      size: entry.size,
+      mode: entry.mode,
+      mtimeSec,
+      type: "0",
+    });
+    const file = createReadStream(entry.abs);
+    for await (const chunk of file) {
+      yield Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    }
+    const padding = padToBlock(entry.size);
+    if (padding > 0) yield Buffer.alloc(padding, 0);
+  }
+  yield Buffer.alloc(BLOCK * 2, 0);
+}
+
+/** Create a bounded ustar stream from a host directory. Rejects symlinks/devices/escapes. */
+export function createImportTarStream(sourceRoot: string, bounds: TarBounds): Readable {
+  return Readable.from(importTarBlocks(sourceRoot, bounds));
+}
+
+function parseOctal(buf: Buffer): number {
+  const text = buf.toString("utf8").replace(/\0/g, "").trim();
+  if (!text) return 0;
+  return Number.parseInt(text, 8);
+}
+
+/**
+ * Consume a ustar stream, enforce entry/byte bounds, and compute SHA-256 of the raw bytes.
+ * Rejects absolute paths, `..` segments, and non-file/dir entry types.
+ */
+export async function summarizeTarStream(stream: AsyncIterable<Buffer>, bounds: TarBounds): Promise<TarExportSummary> {
+  const hash: Hash = createHash("sha256");
+  // ponytail: chunk-array accumulator — O(1) append per stream chunk, no whole-pending
+  // re-concat (the 0.2.4 `pending = Buffer.concat([pending, chunk])` was O(input * chunks)).
+  // 512B headers copy once each (contiguous); file data is advanced past (drop) without
+  // copying since the hash already consumed each chunk via `hash.update`. Total copying O(input).
+  const acc = { chunks: [] as Buffer[], offset: 0, retained: 0 };
+  let entryCount = 0;
+  let byteCount = 0;
+  let fileRemaining = 0;
+  let skipPadding = 0;
+  let sawZeroBlock = false;
+  let finished = false;
+
+  const peekAt = (start: number, n: number): Buffer => {
+    const out = Buffer.allocUnsafe(n);
+    let written = 0;
+    let i = 0;
+    let off = acc.offset;
+    let skip = start;
+    while (skip > 0) {
+      const c = acc.chunks[i];
+      const avail = c.length - off;
+      if (skip >= avail) {
+        skip -= avail;
+        i++;
+        off = 0;
+      } else {
+        off += skip;
+        skip = 0;
+      }
+    }
+    while (written < n) {
+      const c = acc.chunks[i];
+      const take = Math.min(c.length - off, n - written);
+      c.copy(out, written, off, off + take);
+      written += take;
+      i++;
+      off = 0;
+    }
+    return out;
+  };
+  const drop = (n: number): void => {
+    let remaining = n;
+    while (remaining > 0 && acc.chunks.length > 0) {
+      const first = acc.chunks[0];
+      const avail = first.length - acc.offset;
+      if (remaining >= avail) {
+        remaining -= avail;
+        acc.chunks.shift();
+        acc.offset = 0;
+      } else {
+        acc.offset += remaining;
+        remaining = 0;
+      }
+    }
+    acc.retained -= n;
+  };
+  const take = (n: number): Buffer | undefined => {
+    if (acc.retained < n) return undefined;
+    const out = peekAt(0, n);
+    drop(n);
+    return out;
+  };
+
+  for await (const chunk of stream) {
+    hash.update(chunk);
+    byteCount += chunk.byteLength;
+    if (byteCount > bounds.maxBytes) {
+      throw new SandboxTarError(`export exceeded max bytes (${bounds.maxBytes})`);
+    }
+    if (finished) continue;
+    acc.chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    acc.retained += chunk.length;
+
+    while (true) {
+      if (fileRemaining > 0) {
+        if (acc.retained === 0) break;
+        const n = Math.min(fileRemaining, acc.retained);
+        drop(n);
+        fileRemaining -= n;
+        if (fileRemaining === 0 && skipPadding > 0) {
+          if (acc.retained < skipPadding) break;
+          drop(skipPadding);
+          skipPadding = 0;
+        }
+        continue;
+      }
+
+      const header = take(BLOCK);
+      if (!header) break;
+      if (header.every((b) => b === 0)) {
+        if (sawZeroBlock) {
+          finished = true;
+          acc.chunks = [];
+          acc.offset = 0;
+          acc.retained = 0;
+          break;
+        }
+        sawZeroBlock = true;
+        continue;
+      }
+      sawZeroBlock = false;
+      const name = header.subarray(0, 100).toString("utf8").replace(/\0/g, "");
+      const size = parseOctal(header.subarray(124, 136));
+      const typeFlag = String.fromCharCode(header[156] ?? 0);
+      if (!name || name.startsWith("/") || name.split("/").includes("..")) {
+        throw new SandboxTarError(`unsafe tar path rejected: ${name || "<empty>"}`);
+      }
+      if (typeFlag !== "0" && typeFlag !== "\0" && typeFlag !== "5") {
+        throw new SandboxTarError(`unsupported tar entry type '${typeFlag}' for ${name}`);
+      }
+      entryCount += 1;
+      if (entryCount > bounds.maxEntries) {
+        throw new SandboxTarError(`export exceeded max entries (${bounds.maxEntries})`);
+      }
+      if (typeFlag === "5") continue;
+      fileRemaining = size;
+      skipPadding = padToBlock(size);
+    }
+  }
+
+  return {
+    sha256: hash.digest("hex"),
+    entryCount,
+    byteCount,
+  };
+}
+
+export function resolveUnderRoot(root: string, candidate: string): string {
+  const resolved = resolve(root, candidate);
+  const rel = relative(resolve(root), resolved);
+  if (rel.startsWith("..") || rel.includes(`..${sep}`)) {
+    throw new SandboxTarError(`path escapes root: ${candidate}`);
+  }
+  return resolved;
+}

package/coding/src/security/sandbox.ts

@@ -0,0 +1,179 @@
+import type { Readable } from "node:stream";
+import type { BashOperations } from "../agent/index.js";
+
+export interface SandboxExecRequest {
+  readonly command: string;
+  readonly cwd: string;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly onData?: (data: Buffer) => void;
+  readonly signal?: AbortSignal;
+  readonly timeout?: number;
+}
+
+export interface SandboxExecFileRequest {
+  readonly file: string;
+  readonly args: readonly string[];
+  readonly cwd?: string;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly onData?: (data: Buffer) => void;
+  readonly signal?: AbortSignal;
+  /** Wall timeout in milliseconds. */
+  readonly timeout?: number;
+}
+
+export type SandboxStatusState = "running" | "stopped" | "removed" | "failed";
+
+/** Vendor snapshot kind. `filesystem` drops RAM/processes on resume; `memory` restores them. */
+export type SandboxSnapshotKind = "memory" | "filesystem";
+
+export interface SandboxPauseResult {
+  readonly kind: SandboxSnapshotKind;
+  readonly state: "paused";
+}
+
+export interface SandboxStatus {
+  readonly id: string;
+  readonly state: SandboxStatusState;
+  readonly image: string;
+  readonly startedAt: number;
+  readonly lastActivityAt: number;
+  readonly commandCount: number;
+  /** Content identity of the imported workspace tree (when import ran). */
+  readonly importIdentity?: SandboxExportMetadata;
+  /** Content identity of the last successful close export (resume check). */
+  readonly lastExportIdentity?: SandboxExportMetadata;
+  /** Set when `state` is `stopped` because the backend paused rather than exited. */
+  readonly snapshot?: { readonly kind: SandboxSnapshotKind };
+}
+
+export interface SandboxExportMetadata {
+  readonly sha256: string;
+  readonly entryCount: number;
+  readonly byteCount: number;
+  readonly format: "tar";
+}
+
+export interface SandboxCloseOptions {
+  /**
+   * Host-owned artifact writer. Receives a bounded tar stream plus finalized
+   * SHA-256/entry/byte metadata. Partial failures must discard the host artifact.
+   */
+  readonly export?: (stream: Readable, metadata: SandboxExportMetadata) => Promise<void>;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Explicit isolation/coherence capabilities of a sandbox backend or composition.
+ *
+ * Every field is a claim that MUST hold before security-sensitive host policy
+ * may rely on it. Omission (or invalid metadata) resolves every field false —
+ * a backend can never gain a capability by omission or by interface shape.
+ *
+ * `workspaceCoherent`: shell, filesystem, and repository tools observe one
+ * workspace tree. `filesystemIsolated`: sandbox processes cannot touch the
+ * host filesystem. `networkIsolated`: no reachable network (or only an
+ * isolated one). `processIsolated`: sandbox processes run in a separate
+ * process namespace. `privilegeIsolated`: sandbox processes cannot obtain
+ * host privileges (root-in-container without user namespaces is NOT reliable).
+ * `egressRestricted`: any network egress is forced through a controlled
+ * proxy/firewall (a dedicated field because `networkIsolated` cannot represent
+ * custom networks that exist but have proxy-constrained egress).
+ */
+export interface SandboxCapabilities {
+  readonly workspaceCoherent: boolean;
+  readonly filesystemIsolated: boolean;
+  readonly networkIsolated: boolean;
+  readonly processIsolated: boolean;
+  readonly privilegeIsolated: boolean;
+  readonly egressRestricted: boolean;
+}
+
+export interface SandboxAdapter {
+  exec(request: SandboxExecRequest): Promise<{ exitCode: number | null }>;
+  /**
+   * Optional host attestation of isolation controls. Omitted metadata (or
+   * malformed/non-boolean/unknown fields) resolves every capability false;
+   * this is host attestation, never verified by Prism.
+   */
+  readonly capabilities?: Readonly<SandboxCapabilities>;
+}
+
+/**
+ * Disposable sandbox lifecycle used by the Docker/OCI reference adapter.
+ * Extends the shell-only `SandboxAdapter` with typed exec, status, and cleanup.
+ */
+/**
+ * Long-running process handle inside a disposable sandbox.
+ * Optional on {@link DisposableSandbox.startProcess}; absence = one-shot-only adapter.
+ */
+export interface SandboxProcessHandle {
+  readonly pid?: number;
+  write(data: Uint8Array): Promise<void>;
+  signal(name: string): Promise<void>;
+  kill(): Promise<void>;
+  release(): Promise<void>;
+  wait(options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<{ exitCode: number | null }>;
+  /** Opaque non-secret reattachment ref for durable process recovery. */
+  readonly ref?: string;
+}
+
+export interface DisposableSandbox extends SandboxAdapter {
+  readonly id: string;
+  readonly labels?: Readonly<Record<string, string>>;
+  /** Present after workspace import; content hash only (no secrets). */
+  readonly importIdentity?: SandboxExportMetadata;
+  /** Present after a successful `close({ export })`; use for resume hash checks. */
+  readonly lastExportIdentity?: SandboxExportMetadata;
+  execFile(request: SandboxExecFileRequest): Promise<{ exitCode: number | null }>;
+  status(): Promise<SandboxStatus>;
+  stop(options?: { graceMs?: number; signal?: AbortSignal }): Promise<void>;
+  kill(options?: { signal?: AbortSignal }): Promise<void>;
+  close(options?: SandboxCloseOptions): Promise<SandboxExportMetadata | undefined>;
+  /**
+   * Optional long-running process capability. Detected, never assumed.
+   * Absence → ProcessSessions.start over this sandbox fails closed with ERR_PRISM_PROCESS_UNSUPPORTED.
+   */
+  startProcess?(request: SandboxExecFileRequest): Promise<SandboxProcessHandle>;
+  /**
+   * Optional process reattachment capability for durable recovery.
+   * Resolves an attested backend ref to an existing live handle; returns null otherwise.
+   */
+  attachProcess?(ref: string): Promise<SandboxProcessHandle | null>;
+  /**
+   * Optional snapshot/pause. Detected, never assumed.
+   * `keepMemory: false` is filesystem-only: resume reboots and running processes are gone.
+   * A refused pause must leave the sandbox running (or unknown) — never claim paused.
+   */
+  pause?(options?: { keepMemory?: boolean; signal?: AbortSignal }): Promise<SandboxPauseResult>;
+  /** Explicit resume after pause. Must not run as a side effect of exec/connect. */
+  resume?(options?: { signal?: AbortSignal }): Promise<void>;
+}
+
+export class SandboxExecutionError extends Error {
+  readonly code = "ERR_PRISM_SANDBOX_EXECUTION";
+  constructor(message: string) {
+    super(message);
+    this.name = "SandboxExecutionError";
+  }
+}
+
+/** Map a host-owned sandbox adapter to coding-agent `BashOperations`. */
+export function createSandboxBashOperations(adapter: SandboxAdapter): BashOperations {
+  return {
+    exec: async (command, cwd, options) => {
+      try {
+        return await adapter.exec({
+          command,
+          cwd,
+          env: options.env,
+          onData: options.onData,
+          signal: options.signal,
+          timeout: options.timeout,
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new SandboxExecutionError(message);
+      }
+    },
+  };
+}

package/coding/src/security/semaphore.ts

@@ -0,0 +1,55 @@
+/**
+ * FIFO counting semaphore shared by the native/docker sandbox, the egress proxy,
+ * and the check runner concurrency caps.
+ *
+ * Contract:
+ * - `acquire` resolves with a release callback; call it exactly once per successful
+ *   acquire. Releasing an unheld slot is ignored (the active count floors at zero).
+ * - Waiters wake in submission order (FIFO).
+ * - With an `AbortSignal`, an aborted wait rejects with the caller's sandbox error
+ *   class and drops its waiter, so an aborted waiter never consumes a slot; the
+ *   abort listener is detached on both wake and abort.
+ *
+ * Internal to the coding-tools security surface — intentionally absent from `./security/index.ts`.
+ */
+
+const ABORT_MESSAGE = "sandbox operation aborted";
+
+export class Semaphore {
+  private active = 0;
+  private readonly waiters: Array<() => void> = [];
+
+  constructor(
+    private readonly max: number,
+    private readonly abortError: new (message: string) => Error = Error,
+  ) {}
+
+  async acquire(signal?: AbortSignal): Promise<() => void> {
+    if (signal?.aborted) throw new this.abortError(ABORT_MESSAGE);
+    if (this.active < this.max) {
+      this.active += 1;
+      return () => this.release();
+    }
+    await new Promise<void>((resolve, reject) => {
+      const waiter = () => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+      };
+      const onAbort = () => {
+        const idx = this.waiters.indexOf(waiter);
+        if (idx >= 0) this.waiters.splice(idx, 1);
+        reject(new this.abortError(ABORT_MESSAGE));
+      };
+      this.waiters.push(waiter);
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+    this.active += 1;
+    return () => this.release();
+  }
+
+  /** Release a held slot and wake the next FIFO waiter. Safe to call more than once. */
+  release(): void {
+    this.active = Math.max(0, this.active - 1);
+    this.waiters.shift()?.();
+  }
+}