@runuai/host 0.9.14 → 0.9.43

package/lib/task-environment/docker.ts

@@ -0,0 +1,956 @@
+import {
+  spawn as nodeSpawn,
+  type ChildProcessWithoutNullStreams,
+} from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+import {
+  AgentError,
+  agent,
+  type TaskDownResult,
+  type TaskStatusResult,
+  type TaskUpCredentials,
+  type TaskLaunchInput,
+  type TaskUpResult,
+} from "../agent";
+import { dockerCli, type DockerResult } from "../docker-exec";
+import { taskDir } from "../env";
+import { PREVIEW_SIDECAR_TASK_LABEL } from "../preview-sidecar";
+import { assertSafeHostTaskId } from "../task-identity";
+import {
+  assertTaskEnvironmentProcessRequest,
+  assertTaskEnvironmentSessionRequest,
+  type TaskEnvironmentCopyRequest,
+  type TaskEnvironmentDescriptor,
+  type TaskEnvironmentDetachedSessionRequest,
+  type TaskEnvironmentExecRequest,
+  type TaskEnvironmentExecResult,
+  type TaskEnvironmentHandle,
+  type TaskEnvironmentLocator,
+  type TaskEnvironmentPort,
+  type TaskEnvironmentProcess,
+  type TaskEnvironmentProcessExit,
+  type TaskEnvironmentProvider,
+  type TaskEnvironmentRecoveryContext,
+  type TaskEnvironmentRecoveryResult,
+  type TaskEnvironmentSessionRequest,
+  type TaskEnvironmentSpawnRequest,
+  type TaskEnvironmentStatus,
+} from "./types";
+
+export const DOCKER_TASK_ENVIRONMENT_PROVIDER = "docker-compose";
+const DOCKER_LOCATOR_SCHEMA_VERSION = 2;
+const MAX_LOCATOR_COMPONENT = 512;
+
+export type DockerMachineBackend = "docker";
+
+export interface DockerMachineIdentity {
+  backend: DockerMachineBackend;
+  /** Stable process/durable endpoint identity, never a credential-bearing URL. */
+  endpoint: string;
+  /** Stable Docker daemon `.ID`, proved atomically with server liveness. */
+  engineId: string;
+}
+
+interface DockerTaskEnvironmentLocatorValue {
+  schemaVersion: typeof DOCKER_LOCATOR_SCHEMA_VERSION;
+  taskId: string;
+  composeProject: string;
+  containerName: string;
+  hostWorktreePath: string;
+  machine: DockerMachineIdentity;
+  codeServerPort?: number;
+  previewPorts?: Array<{ name: string; hostPort: number }>;
+  initWarning?: string;
+}
+
+export interface DockerTaskEnvironmentDeps {
+  taskUp?: (
+    input: TaskLaunchInput,
+    credentials?: TaskUpCredentials,
+  ) => Promise<TaskUpResult>;
+  taskEnvironmentDown?: (taskId: string) => Promise<TaskDownResult>;
+  taskStatus?: (taskId: string) => Promise<TaskStatusResult>;
+  docker?: typeof dockerCli;
+  spawn?: typeof nodeSpawn;
+  machineIdentity: () => DockerMachineIdentity;
+  /** Full L4/L5-aware recovery hook. Absence intentionally does not start. */
+  recover?: DockerTaskEnvironmentRecoveryDriver;
+  /** Late-bound production seam avoids an orchestrator/provider import cycle
+   * while letting tests supply an instance-local recovery implementation. */
+  recoveryDriver?: () => DockerTaskEnvironmentRecoveryDriver | null;
+}
+
+export type DockerTaskEnvironmentRecoveryDriver = (
+  descriptor: TaskEnvironmentDescriptor,
+  context: TaskEnvironmentRecoveryContext,
+) => Promise<TaskEnvironmentRecoveryResult>;
+
+export function createDockerTaskEnvironmentProvider(
+  deps: DockerTaskEnvironmentDeps,
+): TaskEnvironmentProvider<
+  TaskLaunchInput,
+  TaskUpCredentials,
+  TaskUpResult,
+  TaskDownResult
+> {
+  const resolved = {
+    taskUp: deps.taskUp ?? agent.taskUp,
+    taskEnvironmentDown:
+      deps.taskEnvironmentDown ?? agent.taskEnvironmentDown,
+    taskStatus: deps.taskStatus,
+    docker: deps.docker ?? dockerCli,
+    spawn: deps.spawn ?? nodeSpawn,
+    machineIdentity: deps.machineIdentity,
+    recover: deps.recover,
+    recoveryDriver: deps.recoveryDriver,
+  };
+
+  return {
+    kind: DOCKER_TASK_ENVIRONMENT_PROVIDER,
+    async provision(request) {
+      if (request.taskId !== request.input.task.id) {
+        throw new Error("task environment provision identity mismatch");
+      }
+      const machine = validateMachineIdentity(resolved.machineIdentity());
+      const preparedLocator = dockerTaskEnvironmentPreparedLocator(
+        request.taskId,
+        machine,
+      );
+      await request.onPrepared?.(preparedLocator);
+      const result = await resolved.taskUp(request.input, request.credentials);
+      const prepared = parseDockerTaskEnvironmentLocator(preparedLocator);
+      // task-up composes its worktree path in shell from the operator's
+      // UAI_WORKSPACE_ROOT verbatim, so a benign trailing slash would fail a
+      // strict string compare AFTER the stack is already up. Resolve before
+      // comparing; a path that differs after resolution (wrong directory,
+      // unexpanded `~`) still fails closed.
+      if (
+        result.composeProject !== prepared.composeProject ||
+        path.resolve(result.worktreePath) !== prepared.hostWorktreePath
+      ) {
+        throw new Error(
+          "task environment returned an unexpected Compose project or worktree path",
+        );
+      }
+      const locator = dockerTaskEnvironmentLocator(
+        request.taskId,
+        // Persist the canonical resolved path, not the shell-composed spelling.
+        { ...result, worktreePath: prepared.hostWorktreePath },
+        machine,
+      );
+      return {
+        handle: new DockerTaskEnvironmentHandle(locator, resolved),
+        result,
+      };
+    },
+    async reconstruct(locator) {
+      const persisted = parseDockerTaskEnvironmentLocator(locator);
+      const current = validateMachineIdentity(resolved.machineIdentity());
+      if (
+        persisted.machine.backend !== current.backend ||
+        persisted.machine.endpoint !== current.endpoint ||
+        persisted.machine.engineId !== current.engineId
+      ) {
+        throw new Error(
+          "task environment belongs to a different container backend",
+        );
+      }
+      return new DockerTaskEnvironmentHandle(locator, resolved);
+    },
+  };
+}
+
+export function dockerTaskEnvironmentLocator(
+  taskId: string,
+  result: TaskUpResult,
+  machine: DockerMachineIdentity,
+): TaskEnvironmentLocator {
+  assertSafeHostTaskId(taskId);
+  const composeProject = `task-${taskId}`;
+  if (result.composeProject !== composeProject) {
+    throw new Error("task environment returned an unexpected Compose project");
+  }
+  const value: DockerTaskEnvironmentLocatorValue = {
+    schemaVersion: DOCKER_LOCATOR_SCHEMA_VERSION,
+    taskId,
+    composeProject,
+    containerName: `${composeProject}-app-1`,
+    hostWorktreePath: result.worktreePath,
+    machine: validateMachineIdentity(machine),
+    ...(result.codeServerPort === undefined
+      ? {}
+      : { codeServerPort: result.codeServerPort }),
+    ...(result.previewPorts === undefined
+      ? {}
+      : { previewPorts: result.previewPorts }),
+    ...(result.initWarning === undefined
+      ? {}
+      : { initWarning: result.initWarning }),
+  };
+  validateDockerLocatorValue(value);
+  return {
+    schemaVersion: 1,
+    provider: DOCKER_TASK_ENVIRONMENT_PROVIDER,
+    value,
+  };
+}
+
+/** Deterministic crash-recovery identity, derived solely from admitted host
+ * configuration and task id. Never accept a worktree path from the caller. */
+export function dockerTaskEnvironmentPreparedLocator(
+  taskId: string,
+  machine: DockerMachineIdentity,
+): TaskEnvironmentLocator {
+  assertSafeHostTaskId(taskId);
+  const composeProject = `task-${taskId}`;
+  const value: DockerTaskEnvironmentLocatorValue = {
+    schemaVersion: DOCKER_LOCATOR_SCHEMA_VERSION,
+    taskId,
+    composeProject,
+    containerName: `${composeProject}-app-1`,
+    hostWorktreePath: taskDir(taskId),
+    machine: validateMachineIdentity(machine),
+  };
+  validateDockerLocatorValue(value);
+  return {
+    schemaVersion: 1,
+    provider: DOCKER_TASK_ENVIRONMENT_PROVIDER,
+    value,
+  };
+}
+
+export function parseDockerTaskEnvironmentLocator(
+  locator: TaskEnvironmentLocator,
+): DockerTaskEnvironmentLocatorValue {
+  if (
+    locator.schemaVersion !== 1 ||
+    locator.provider !== DOCKER_TASK_ENVIRONMENT_PROVIDER
+  ) {
+    throw new Error("task environment locator does not belong to Docker Compose");
+  }
+  return validateDockerLocatorValue(locator.value);
+}
+
+class DockerTaskEnvironmentHandle
+  implements TaskEnvironmentHandle<TaskDownResult>
+{
+  readonly descriptor: TaskEnvironmentDescriptor;
+  readonly durableIdentity: string;
+  readonly #value: DockerTaskEnvironmentLocatorValue;
+
+  constructor(
+    locator: TaskEnvironmentLocator,
+    private readonly deps: Required<
+      Omit<
+        DockerTaskEnvironmentDeps,
+        "recover" | "recoveryDriver" | "taskStatus"
+      >
+    > &
+      Pick<
+        DockerTaskEnvironmentDeps,
+        "recover" | "recoveryDriver" | "taskStatus"
+      >,
+  ) {
+    this.#value = parseDockerTaskEnvironmentLocator(locator);
+    this.durableIdentity = this.#value.containerName;
+    this.descriptor = {
+      taskId: this.#value.taskId,
+      locator,
+      workspacePath: "/workspace",
+      ...(this.#value.codeServerPort === undefined
+        ? {}
+        : { codeServerPort: this.#value.codeServerPort }),
+      ...(this.#value.previewPorts === undefined
+        ? {}
+        : { previewPorts: this.#value.previewPorts }),
+      ...(this.#value.initWarning === undefined
+        ? {}
+        : { initWarning: this.#value.initWarning }),
+    };
+  }
+
+  exec(request: TaskEnvironmentExecRequest): Promise<TaskEnvironmentExecResult> {
+    assertTaskEnvironmentProcessRequest(request);
+    return capturedCliExec(
+      this.deps.spawn,
+      "docker",
+      dockerExecArgs(this.#value.containerName, request),
+      request,
+    );
+  }
+
+  async spawn(
+    request: TaskEnvironmentSpawnRequest,
+  ): Promise<TaskEnvironmentProcess> {
+    assertTaskEnvironmentProcessRequest(request);
+    return streamingCliExec(
+      this.deps.spawn,
+      "docker",
+      dockerExecArgs(this.#value.containerName, request),
+      request,
+    );
+  }
+
+  async spawnSession(
+    request: TaskEnvironmentSessionRequest,
+  ): Promise<TaskEnvironmentProcess> {
+    assertTaskEnvironmentSessionRequest(request);
+    return streamingCliExec(
+      this.deps.spawn,
+      "docker",
+      dockerExecArgs(this.#value.containerName, request),
+      request,
+    );
+  }
+
+  async launchDetachedSession(
+    request: TaskEnvironmentDetachedSessionRequest,
+  ): Promise<TaskEnvironmentExecResult> {
+    assertTaskEnvironmentSessionRequest(request);
+    const result = await this.deps.docker(
+      dockerExecArgs(this.#value.containerName, request, "detached"),
+      {
+        timeoutMs: request.launchTimeoutMs,
+        maxOutputBytes: request.maxOutputBytes,
+      },
+    );
+    return {
+      exitCode: result.status,
+      signal: null,
+      stdout: Buffer.from(result.stdout),
+      stderr: Buffer.from(result.stderr),
+      stdoutTruncated: result.outputTruncated === true,
+      stderrTruncated: result.outputTruncated === true,
+    };
+  }
+
+  async copy(request: TaskEnvironmentCopyRequest): Promise<void> {
+    validateCopyRequest(request);
+    const args =
+      request.direction === "into"
+        ? [
+            "cp",
+            request.source,
+            `${this.#value.containerName}:${request.destination}`,
+          ]
+        : [
+            "cp",
+            `${this.#value.containerName}:${request.source}`,
+            request.destination,
+          ];
+    const result = await this.deps.docker(args, {
+      timeoutMs: 120_000,
+      maxOutputBytes: 1024 * 1024,
+    });
+    requireDockerSuccess(result, "copy task environment data");
+  }
+
+  async ports(): Promise<TaskEnvironmentPort[]> {
+    const result = await this.deps.docker(
+      ["port", this.#value.containerName],
+      { timeoutMs: 10_000, maxOutputBytes: 256 * 1024 },
+    );
+    requireDockerSuccess(result, "inspect task environment ports");
+    return parseDockerPorts(result.stdout);
+  }
+
+  async status(): Promise<TaskEnvironmentStatus> {
+    if (this.deps.taskStatus) {
+      return taskStatusToEnvironmentStatus(
+        await this.deps.taskStatus(this.#value.taskId),
+      );
+    }
+    return inspectDockerTaskEnvironmentStatus(this.deps.docker, this.#value);
+  }
+
+  async recover(
+    context: TaskEnvironmentRecoveryContext,
+  ): Promise<TaskEnvironmentRecoveryResult> {
+    const recover = this.deps.recover ?? this.deps.recoveryDriver?.();
+    if (recover) {
+      return recover(this.descriptor, context);
+    }
+    const status = await this.status();
+    return status.state === "unknown"
+      ? { outcome: "deferred", detail: status.detail }
+      : { outcome: "recovered", status };
+  }
+
+  async stop(): Promise<void> {
+    // Stop the whole Compose project (app + sidecars) while keeping every
+    // container, volume, and the worktree so the task can be resumed. The
+    // label filter is scoped by the locator's project, which provision
+    // derived from the admitted task id.
+    const listed = await this.deps.docker(
+      [
+        "ps",
+        "-q",
+        "--filter",
+        `label=com.docker.compose.project=${this.#value.composeProject}`,
+      ],
+      { timeoutMs: 30_000, maxOutputBytes: 256 * 1024 },
+    );
+    requireDockerSuccess(listed, "list task environment containers");
+    const ids = listed.stdout
+      .split("\n")
+      .map((id) => id.trim())
+      .filter(Boolean);
+    if (ids.length === 0) return;
+    const stopped = await this.deps.docker(["stop", ...ids], {
+      timeoutMs: 60_000,
+      maxOutputBytes: 256 * 1024,
+    });
+    requireDockerSuccess(stopped, "stop task environment containers");
+  }
+
+  async teardown(): Promise<TaskDownResult> {
+    const result = await this.deps.taskEnvironmentDown(this.#value.taskId);
+    let status: TaskEnvironmentStatus;
+    try {
+      status = await this.status();
+    } catch (error) {
+      // Preserve structured agent failures so the host command boundary can
+      // still poison a vanished daemon. Other provider errors remain an
+      // explicit lack of absence proof.
+      if (AgentError.is(error)) throw error;
+      throw new Error(
+        `task environment teardown is unconfirmed: ${boundedErrorMessage(error)}`,
+      );
+    }
+    if (status.state !== "absent") {
+      throw new Error(
+        status.state === "unknown"
+          ? `task environment teardown is unconfirmed: ${status.detail}`
+          : `task environment teardown left the task ${status.state}`,
+      );
+    }
+    return result;
+  }
+}
+
+function validateDockerLocatorValue(
+  value: unknown,
+): DockerTaskEnvironmentLocatorValue {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Docker task environment locator must be an object");
+  }
+  const record = value as Record<string, unknown>;
+  const allowed = new Set([
+    "schemaVersion",
+    "taskId",
+    "composeProject",
+    "containerName",
+    "hostWorktreePath",
+    "machine",
+    "codeServerPort",
+    "previewPorts",
+    "initWarning",
+  ]);
+  if (Object.keys(record).some((key) => !allowed.has(key))) {
+    throw new Error("Docker task environment locator has unexpected fields");
+  }
+  if (record.schemaVersion !== DOCKER_LOCATOR_SCHEMA_VERSION) {
+    throw new Error("unsupported Docker task environment locator schema");
+  }
+  const taskId = exactComponent(record.taskId, "task id");
+  if (!/^[a-z0-9][a-z0-9_-]{0,127}$/.test(taskId)) {
+    throw new Error("Docker task environment task id is invalid");
+  }
+  const composeProject = exactComponent(record.composeProject, "Compose project");
+  const containerName = exactComponent(record.containerName, "container name");
+  if (
+    composeProject !== `task-${taskId}` ||
+    containerName !== `${composeProject}-app-1`
+  ) {
+    throw new Error("Docker task environment identity is inconsistent");
+  }
+  const hostWorktreePath = exactComponent(
+    record.hostWorktreePath,
+    "host worktree path",
+  );
+  if (
+    !path.isAbsolute(hostWorktreePath) ||
+    path.resolve(hostWorktreePath) !== hostWorktreePath ||
+    /[\r\n]/.test(hostWorktreePath)
+  ) {
+    throw new Error("Docker task environment worktree path must be absolute");
+  }
+  const machine = validateMachineIdentity(record.machine);
+  const codeServerPort = optionalPort(record.codeServerPort, "code server port");
+  const previewPorts = validatePreviewPorts(record.previewPorts);
+  const initWarning =
+    record.initWarning === undefined
+      ? undefined
+      : exactComponent(record.initWarning, "init warning", 4096);
+  return {
+    schemaVersion: DOCKER_LOCATOR_SCHEMA_VERSION,
+    taskId,
+    composeProject,
+    containerName,
+    hostWorktreePath,
+    machine,
+    ...(codeServerPort === undefined ? {} : { codeServerPort }),
+    ...(previewPorts === undefined ? {} : { previewPorts }),
+    ...(initWarning === undefined ? {} : { initWarning }),
+  };
+}
+
+function validateMachineIdentity(value: unknown): DockerMachineIdentity {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Docker machine identity must be an object");
+  }
+  const record = value as Record<string, unknown>;
+  if (
+    Object.keys(record).sort().join("\0") !==
+    "backend\0endpoint\0engineId"
+  ) {
+    throw new Error("Docker machine identity has unexpected fields");
+  }
+  if (record.backend !== "docker") {
+    throw new Error("Docker machine backend is invalid");
+  }
+  const endpoint = exactComponent(record.endpoint, "Docker endpoint", 2048);
+  const socketPath = endpoint.slice("unix://".length);
+  if (
+    !endpoint.startsWith("unix:///") ||
+    /[@?#\r\n]/.test(endpoint) ||
+    !path.isAbsolute(socketPath) ||
+    path.resolve(socketPath) !== socketPath
+  ) {
+    throw new Error("Docker machine endpoint must be a local Unix socket");
+  }
+  const engineId = exactComponent(record.engineId, "Docker engine id", 512);
+  if (!/^[A-Za-z0-9][A-Za-z0-9:._-]*$/.test(engineId)) {
+    throw new Error("Docker engine id is invalid");
+  }
+  return { backend: record.backend, endpoint, engineId };
+}
+
+function validatePreviewPorts(
+  value: unknown,
+): Array<{ name: string; hostPort: number }> | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.length > 64) {
+    throw new Error("Docker task environment preview ports are invalid");
+  }
+  return value.map((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error("Docker task environment preview port is invalid");
+    }
+    const record = entry as Record<string, unknown>;
+    if (Object.keys(record).sort().join("\0") !== "hostPort\0name") {
+      throw new Error("Docker task environment preview port has unexpected fields");
+    }
+    return {
+      name: exactComponent(record.name, "preview port name"),
+      hostPort: requiredPort(record.hostPort, "preview host port"),
+    };
+  });
+}
+
+function exactComponent(
+  value: unknown,
+  name: string,
+  max = MAX_LOCATOR_COMPONENT,
+): string {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > max ||
+    value.includes("\0")
+  ) {
+    throw new Error(`${name} is invalid`);
+  }
+  return value;
+}
+
+function optionalPort(value: unknown, name: string): number | undefined {
+  return value === undefined ? undefined : requiredPort(value, name);
+}
+
+function requiredPort(value: unknown, name: string): number {
+  if (!Number.isInteger(value) || Number(value) < 1 || Number(value) > 65_535) {
+    throw new Error(`${name} is invalid`);
+  }
+  return Number(value);
+}
+
+function dockerExecArgs(
+  containerName: string,
+  request:
+    | TaskEnvironmentExecRequest
+    | TaskEnvironmentSpawnRequest
+    | TaskEnvironmentSessionRequest
+    | TaskEnvironmentDetachedSessionRequest,
+  mode: "interactive" | "detached" = "interactive",
+): string[] {
+  const args = ["exec", mode === "detached" ? "-d" : "-i"];
+  if (request.cwd) args.push("--workdir", request.cwd);
+  if (request.user) args.push("--user", request.user);
+  for (const name of request.inheritEnv ?? []) {
+    if (process.env[name] !== undefined) args.push("--env", name);
+  }
+  for (const [name, value] of Object.entries(request.env ?? {}).sort(([a], [b]) =>
+    a.localeCompare(b),
+  )) {
+    args.push("--env", `${name}=${value}`);
+  }
+  args.push(containerName, ...request.argv);
+  return args;
+}
+
+/** Bounded one-shot exec, generalized over the CLI so the Apple container
+ * provider reuses the exact truncation/timeout/exit-mapping semantics. */
+export function capturedCliExec(
+  spawn: typeof nodeSpawn,
+  command: string,
+  args: readonly string[],
+  request: TaskEnvironmentExecRequest,
+): Promise<TaskEnvironmentExecResult> {
+  return new Promise((resolve) => {
+    const child = spawn(command, [...args], {
+      stdio: ["pipe", "pipe", "pipe"],
+    }) as ChildProcessWithoutNullStreams;
+    let stdout: Buffer[] = [];
+    let stderr: Buffer[] = [];
+    let retained = 0;
+    let stdoutTruncated = false;
+    let stderrTruncated = false;
+    let settled = false;
+    const append = (kind: "stdout" | "stderr", chunk: Buffer): void => {
+      if (settled) return;
+      const remaining = Math.max(0, request.maxOutputBytes - retained);
+      const kept = remaining === 0 ? Buffer.alloc(0) : chunk.subarray(0, remaining);
+      if (kept.length > 0) {
+        if (kind === "stdout") stdout.push(kept);
+        else stderr.push(kept);
+        retained += kept.length;
+      }
+      if (kept.length !== chunk.length) {
+        if (kind === "stdout") stdoutTruncated = true;
+        else stderrTruncated = true;
+        child.kill("SIGKILL");
+        // Same bounded settlement as the deadline kill: never wait forever
+        // on close after an overflow kill.
+        const settle = setTimeout(() => finish(null, "SIGKILL"), 5_000);
+        settle.unref?.();
+      }
+    };
+    child.stdout.on("data", (chunk: Buffer) => append("stdout", Buffer.from(chunk)));
+    child.stderr.on("data", (chunk: Buffer) => append("stderr", Buffer.from(chunk)));
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      // Settle even if the killed child never emits close (unreapable state);
+      // the caller's own deadline already expired.
+      const settle = setTimeout(() => finish(null, "SIGKILL"), 5_000);
+      settle.unref?.();
+    }, request.timeoutMs);
+    timer.unref?.();
+    const finish = (exitCode: number | null, signal: NodeJS.Signals | null): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({
+        exitCode,
+        signal,
+        stdout: Buffer.concat(stdout),
+        stderr: Buffer.concat(stderr),
+        stdoutTruncated,
+        stderrTruncated,
+      });
+      stdout = [];
+      stderr = [];
+    };
+    child.once("error", (error) => {
+      stderr.push(Buffer.from(error.message));
+      finish(null, null);
+    });
+    child.once("close", finish);
+    child.stdin.on("error", () => {});
+    child.stdin.end(request.stdin);
+  });
+}
+
+/** Streaming exec, generalized over the CLI for the same reason. */
+export function streamingCliExec(
+  spawn: typeof nodeSpawn,
+  command: string,
+  args: readonly string[],
+  request: TaskEnvironmentSpawnRequest | TaskEnvironmentSessionRequest,
+): TaskEnvironmentProcess {
+  const child = spawn(command, [...args], {
+    stdio: ["pipe", "pipe", "pipe"],
+  }) as ChildProcessWithoutNullStreams;
+  // Every kill forces settlement within a bounded grace, like the captured
+  // runner: a wedged client must not leave an agent session's completion
+  // pending indefinitely.
+  let forceSettle: (() => void) | null = null;
+  const killAndSettle = (): void => {
+    child.kill("SIGKILL");
+    const settle = setTimeout(() => forceSettle?.(), 5_000);
+    settle.unref?.();
+  };
+  const budget = new SharedOutputBudget(request.maxOutputBytes, killAndSettle);
+  const stdout = new BoundedByteQueue(budget);
+  const stderr = new BoundedByteQueue(budget);
+  child.stdout.on("data", (chunk: Buffer) => stdout.push(Buffer.from(chunk)));
+  child.stderr.on("data", (chunk: Buffer) => stderr.push(Buffer.from(chunk)));
+  const timer =
+    "timeoutMs" in request
+      ? setTimeout(killAndSettle, request.timeoutMs)
+      : null;
+  timer?.unref?.();
+  const completion = new Promise<TaskEnvironmentProcessExit>((resolve) => {
+    let settled = false;
+    const finish = (exitCode: number | null, signal: NodeJS.Signals | null): void => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      stdout.end();
+      stderr.end();
+      resolve({ exitCode, signal });
+    };
+    forceSettle = () => finish(null, "SIGKILL");
+    child.once("error", () => finish(null, null));
+    child.once("close", finish);
+  });
+  child.stdin.on("error", () => {});
+  return {
+    stdout,
+    stderr,
+    completion,
+    write: (chunk) => writeChildInput(child, chunk),
+    closeInput: async () => {
+      child.stdin.end();
+    },
+    terminate: async (signal = "SIGTERM") => {
+      child.kill(signal);
+    },
+  };
+}
+
+function writeChildInput(
+  child: ChildProcessWithoutNullStreams,
+  chunk: Uint8Array,
+): Promise<void> {
+  if (child.stdin.destroyed || !child.stdin.writable) {
+    return Promise.reject(new Error("task environment process input is closed"));
+  }
+  return new Promise((resolve, reject) => {
+    const onError = (error: Error): void => {
+      child.stdin.off("drain", onDrain);
+      reject(error);
+    };
+    const onDrain = (): void => {
+      child.stdin.off("error", onError);
+      resolve();
+    };
+    child.stdin.once("error", onError);
+    if (child.stdin.write(chunk)) {
+      child.stdin.off("error", onError);
+      resolve();
+    } else {
+      child.stdin.once("drain", onDrain);
+    }
+  });
+}
+
+class SharedOutputBudget {
+  #bytes = 0;
+  #overflowed = false;
+
+  constructor(
+    private readonly maxBytes: number,
+    private readonly onOverflow: () => void,
+  ) {}
+
+  retain(bytes: number): boolean {
+    if (this.#overflowed || this.#bytes + bytes > this.maxBytes) {
+      if (!this.#overflowed) {
+        this.#overflowed = true;
+        this.onOverflow();
+      }
+      return false;
+    }
+    this.#bytes += bytes;
+    return true;
+  }
+
+  release(bytes: number): void {
+    this.#bytes = Math.max(0, this.#bytes - bytes);
+  }
+}
+
+class BoundedByteQueue implements AsyncIterable<Uint8Array> {
+  readonly #chunks: Buffer[] = [];
+  readonly #waiters: Array<
+    (result: IteratorResult<Uint8Array>) => void
+  > = [];
+  #ended = false;
+
+  constructor(private readonly budget: SharedOutputBudget) {}
+
+  push(chunk: Buffer): void {
+    if (this.#ended || chunk.length === 0 || !this.budget.retain(chunk.length)) return;
+    const waiter = this.#waiters.shift();
+    if (waiter) {
+      this.budget.release(chunk.length);
+      waiter({ done: false, value: chunk });
+    } else {
+      this.#chunks.push(chunk);
+    }
+  }
+
+  end(): void {
+    if (this.#ended) return;
+    this.#ended = true;
+    for (const waiter of this.#waiters.splice(0)) {
+      waiter({ done: true, value: undefined });
+    }
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<Uint8Array> {
+    return {
+      next: () => {
+        const chunk = this.#chunks.shift();
+        if (chunk) {
+          this.budget.release(chunk.length);
+          return Promise.resolve({ done: false as const, value: chunk });
+        }
+        if (this.#ended) {
+          return Promise.resolve({ done: true as const, value: undefined });
+        }
+        return new Promise((resolve) => this.#waiters.push(resolve));
+      },
+    };
+  }
+}
+
+function validateCopyRequest(request: TaskEnvironmentCopyRequest): void {
+  for (const path of [request.source, request.destination]) {
+    if (!path.startsWith("/") || path.includes("\0") || path.includes(":")) {
+      throw new Error("task environment copy paths must be absolute and unambiguous");
+    }
+  }
+}
+
+function parseDockerPorts(stdout: string): TaskEnvironmentPort[] {
+  const ports: TaskEnvironmentPort[] = [];
+  for (const line of stdout.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const match = /^(\d+)(?:\/(?:tcp|udp))? -> 127\.0\.0\.1:(\d+)$/.exec(
+      line.trim(),
+    );
+    if (!match) {
+      throw new Error("task environment published a non-loopback or malformed port");
+    }
+    ports.push({
+      containerPort: requiredPort(Number(match[1]), "container port"),
+      host: "127.0.0.1",
+      hostPort: requiredPort(Number(match[2]), "host port"),
+    });
+  }
+  return ports;
+}
+
+function taskStatusToEnvironmentStatus(
+  status: TaskStatusResult,
+): TaskEnvironmentStatus {
+  return {
+    state: status.composeRunning
+      ? "running"
+      : status.containers.length > 0 || status.worktreePresent
+        ? "stopped"
+        : "absent",
+    instances: [...status.containers],
+    workspacePresent: status.worktreePresent,
+  };
+}
+
+// The fourth column is the preview-sidecar marker: a sidecar wearing the
+// task's compose labels must read as "not the app", not as malformed
+// identity data — the latter turned a healthy running task's status into
+// "unknown" (live 2026-08-18).
+const DOCKER_STATUS_FORMAT =
+  `{{.Names}}\t{{.Label "com.docker.compose.project"}}\t{{.State}}\t{{.Label "${PREVIEW_SIDECAR_TASK_LABEL}"}}`;
+
+async function inspectDockerTaskEnvironmentStatus(
+  docker: typeof dockerCli,
+  environment: DockerTaskEnvironmentLocatorValue,
+): Promise<TaskEnvironmentStatus> {
+  const result = await docker(
+    [
+      "ps",
+      "--all",
+      "--filter",
+      `label=com.docker.compose.project=${environment.composeProject}`,
+      "--filter",
+      "label=com.docker.compose.service=app",
+      "--format",
+      DOCKER_STATUS_FORMAT,
+    ],
+    { timeoutMs: 30_000, maxOutputBytes: 256 * 1024 },
+  );
+  if (result.status !== 0) {
+    return {
+      state: "unknown",
+      detail: boundedDockerFailure(result, "inspect task environment"),
+    };
+  }
+
+  let state: string | undefined;
+  for (const raw of result.stdout.split(/\r?\n/)) {
+    // No trim before splitting: the app row's LAST column (the sidecar
+    // marker) is empty, and trimming would eat its tab and shift the shape.
+    if (!raw.trim()) continue;
+    const [name, project, candidateState, sidecar, ...extra] = raw.split("\t");
+    // A preview sidecar wearing the task's compose labels is not the app
+    // container; skipping it keeps a healthy task from reading as unknown.
+    if (sidecar !== undefined && sidecar !== "") continue;
+    if (
+      state !== undefined ||
+      name !== environment.containerName ||
+      project !== environment.composeProject ||
+      !candidateState ||
+      !candidateState.trim() ||
+      sidecar === undefined ||
+      extra.length > 0
+    ) {
+      return {
+        state: "unknown",
+        detail: "task environment inventory returned malformed identity data",
+      };
+    }
+    state = candidateState.trim();
+  }
+  const workspacePresent = existsSync(environment.hostWorktreePath);
+  if (state === undefined) {
+    return {
+      state: workspacePresent ? "stopped" : "absent",
+      instances: [],
+      workspacePresent,
+    };
+  }
+  return {
+    state: state === "running" ? "running" : "stopped",
+    instances: [environment.containerName],
+    workspacePresent,
+  };
+}
+
+function requireDockerSuccess(result: DockerResult, operation: string): void {
+  if (result.status === 0) return;
+  const detail = (result.stderr || result.stdout).trim().slice(0, 512);
+  throw new Error(`${operation} failed${detail ? `: ${detail}` : ""}`);
+}
+
+function boundedDockerFailure(result: DockerResult, operation: string): string {
+  const detail = (result.stderr || result.stdout).trim().slice(0, 512);
+  return `${operation} failed${detail ? `: ${detail}` : ""}`;
+}
+
+function boundedErrorMessage(error: unknown): string {
+  return (error instanceof Error ? error.message : String(error)).slice(0, 512);
+}