@moondeck/station 0.0.1 → 1.0.1

package/lib/task-environment/docker.ts

@@ -0,0 +1,1344 @@
+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 { isLaunchSecretEnvName } from "../engine-credential-env";
+import {
+  hostWorkspaceRead,
+  hostWorkspaceWrite,
+} from "./workspace-files";
+import { taskDir } from "../env";
+import { PREVIEW_SIDECAR_TASK_LABEL } from "../preview-sidecar";
+import { assertSafeHostTaskId } from "../task-identity";
+import { applyProjectEnvProfile } from "../runtime-authority";
+import { rootAnchoredRequest } from "./anchor";
+import {
+  assertTaskEnvironmentExecRequest,
+  assertTaskEnvironmentProcessRequest,
+  assertTaskEnvironmentSessionRequest,
+  type TaskEnvironmentCallOptions,
+  type TaskEnvironmentReadOptions,
+  type TaskEnvironmentCopyRequest,
+  type TaskEnvironmentDescriptor,
+  type TaskEnvironmentDetachedSessionRequest,
+  type TaskEnvironmentExecRequest,
+  type TaskEnvironmentExecResult,
+  type TaskEnvironmentHandle,
+  type TaskEnvironmentLocator,
+  type TaskEnvironmentPort,
+  type TaskEnvironmentProcess,
+  type TaskEnvironmentProcessExit,
+  type ProjectEnvMode,
+  type TaskEnvironmentProvider,
+  type TaskEnvironmentRecoveryContext,
+  type TaskEnvironmentRecoveryResult,
+  type TaskEnvironmentSessionRequest,
+  type TaskEnvironmentSpawnRequest,
+  type TaskEnvironmentStatus,
+} from "./types";
+import type { TaskWriteEnvironment } from "../credential-consumers/task-files";
+
+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,
+    envMode?: ProjectEnvMode,
+    runtimeEnvironment?: () => TaskWriteEnvironment,
+  ) => 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,
+        request.envMode ?? "loader",
+        // ADR-154 §12: the container as task-up has created it, for the
+        // runtime-ready writes before uai-init.
+        () => new DockerTaskEnvironmentHandle(preparedLocator, resolved, request.envMode ?? "loader"),
+      );
+      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,
+          request.envMode ?? "loader",
+        ),
+        result,
+      };
+    },
+    async reconstruct(locator, envMode = "baked") {
+      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, envMode);
+    },
+  };
+}
+
+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;
+  /** ADR-154 §6: anchored requests start under the engine supervisor. */
+  readonly anchors = true;
+  readonly #value: DockerTaskEnvironmentLocatorValue;
+
+  constructor(
+    locator: TaskEnvironmentLocator,
+    private readonly deps: Required<
+      Omit<
+        DockerTaskEnvironmentDeps,
+        "recover" | "recoveryDriver" | "taskStatus"
+      >
+    > &
+      Pick<
+        DockerTaskEnvironmentDeps,
+        "recover" | "recoveryDriver" | "taskStatus"
+      >,
+    envMode: ProjectEnvMode,
+  ) {
+    this.#value = parseDockerTaskEnvironmentLocator(locator);
+    this.durableIdentity = this.#value.containerName;
+    this.descriptor = {
+      taskId: this.#value.taskId,
+      locator,
+      envMode,
+      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 }),
+    };
+  }
+
+  async readWorkspaceFile(filePath: string, options?: TaskEnvironmentReadOptions): Promise<Uint8Array | null> {
+    options?.admit?.();
+    return hostWorkspaceRead(
+      this.descriptor,
+      path.join(this.#value.hostWorktreePath, "workspace"),
+      filePath,
+      options,
+    );
+  }
+
+  async writeWorkspaceFile(filePath: string, bytes: Uint8Array, options?: TaskEnvironmentCallOptions): Promise<void> {
+    options?.admit?.();
+    await hostWorkspaceWrite(
+      this.descriptor,
+      path.join(this.#value.hostWorktreePath, "workspace"),
+      filePath,
+      bytes,
+    );
+  }
+
+  exec(request: TaskEnvironmentExecRequest): Promise<TaskEnvironmentExecResult> {
+    assertTaskEnvironmentExecRequest(request);
+    const { privileged, ...unprivileged } = request;
+    const profiled = applyProjectEnvProfile(
+      rootAnchoredRequest(unprivileged),
+      this.descriptor.envMode ?? "baked",
+      "/usr/bin/zsh",
+    );
+    request.admit?.();
+    const invocation = dockerExecArgs(
+      this.#value.containerName,
+      profiled,
+      "interactive",
+      privileged === true,
+    );
+    return capturedCliExec(
+      this.deps.spawn,
+      "docker",
+      invocation.args,
+      profiled,
+      invocation.env,
+    );
+  }
+
+  async spawn(
+    request: TaskEnvironmentSpawnRequest,
+  ): Promise<TaskEnvironmentProcess> {
+    assertTaskEnvironmentProcessRequest(request);
+    const profiled = applyProjectEnvProfile(
+      rootAnchoredRequest(request),
+      this.descriptor.envMode ?? "baked",
+      "/usr/bin/zsh",
+    );
+    const invocation = dockerExecArgs(this.#value.containerName, profiled);
+    request.admit?.();
+    return streamingCliExec(
+      this.deps.spawn,
+      "docker",
+      invocation.args,
+      profiled,
+      invocation.env,
+    );
+  }
+
+  async spawnSession(
+    request: TaskEnvironmentSessionRequest,
+  ): Promise<TaskEnvironmentProcess> {
+    assertTaskEnvironmentSessionRequest(request);
+    const profiled = applyProjectEnvProfile(
+      rootAnchoredRequest(request),
+      this.descriptor.envMode ?? "baked",
+      "/usr/bin/zsh",
+    );
+    const invocation = dockerExecArgs(this.#value.containerName, profiled);
+    request.admit?.();
+    return streamingCliExec(
+      this.deps.spawn,
+      "docker",
+      invocation.args,
+      profiled,
+      invocation.env,
+    );
+  }
+
+  async launchDetachedSession(
+    request: TaskEnvironmentDetachedSessionRequest,
+  ): Promise<TaskEnvironmentExecResult> {
+    assertTaskEnvironmentSessionRequest(request);
+    const profiled = applyProjectEnvProfile(
+      rootAnchoredRequest(request),
+      this.descriptor.envMode ?? "baked",
+      "/usr/bin/zsh",
+    );
+    const invocation = dockerExecArgs(
+      this.#value.containerName,
+      profiled,
+      "detached",
+    );
+    request.admit?.();
+    const result = await this.deps.docker(invocation.args, {
+      timeoutMs: request.launchTimeoutMs,
+      maxOutputBytes: request.maxOutputBytes,
+      ...(invocation.env === undefined ? {} : { env: invocation.env }),
+    });
+    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,
+          ];
+    request.admit?.();
+    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");
+  }
+
+  /**
+   * The boot sweep's way into a stopped app container (types.ts). After a
+   * reboot every task container is Exited, and `docker exec` into one fails,
+   * so its credential files, in the container's writable layer, could never
+   * be proven gone and the runner stayed in `checking` (2026-10-30). Only
+   * the exact app container starts, by id, never the compose project. On the
+   * standard image its command is `sleep infinity` under Docker's own init,
+   * and everything else in a task (uai-init, the editor, engines, the
+   * forwarder) is a later `docker exec` of the runner's. A project's `extra`
+   * Dockerfile lines can still make a derived image run its own code on a
+   * plain start, so the start is refused on any sign of it (`#startRefusal`).
+   */
+  async runStoppedForCleanup<T>(
+    work: () => Promise<T>,
+    oweStop: (containerId: string) => void | Promise<void>,
+  ): Promise<T> {
+    const before = await this.#inspectApp(this.#value.containerName);
+    if (before.kind !== "found") {
+      throw new Error(`the stopped task environment cannot be started for cleanup: ${before.detail}`);
+    }
+    const refusal = await this.#startRefusal(before.container);
+    if (refusal !== null) {
+      throw new Error(`the task environment is not started for cleanup: ${refusal}`);
+    }
+    const { id } = before.container;
+    // Durable before the start: a crash, a start that timed out yet started
+    // it, or a stop that fails below all leave it owed.
+    await oweStop(id);
+    let value: T | undefined;
+    let failed = false;
+    let failure: unknown;
+    try {
+      const started = await this.deps.docker(["start", id], {
+        timeoutMs: 60_000,
+        maxOutputBytes: 64 * 1024,
+      });
+      requireDockerSuccess(started, "start the stopped task environment for cleanup");
+      const running = await this.#inspectApp(id);
+      if (
+        running.kind !== "found" ||
+        running.container.id !== id ||
+        running.container.state !== "running"
+      ) {
+        throw new Error("the task environment did not start for cleanup");
+      }
+      value = await work();
+    } catch (error) {
+      failed = true;
+      failure = error;
+    }
+    // Whatever happened above (a start that reported failure may still have
+    // started it), it goes back to stopped.
+    if (!(await this.settleCleanupStart(id))) {
+      throw new Error(
+        "the task environment could not be proven stopped again after cleanup" +
+          (failed ? `; the cleanup itself failed: ${boundedErrorMessage(failure)}` : ""),
+      );
+    }
+    if (failed) throw failure;
+    return value as T;
+  }
+
+  async settleCleanupStart(containerId: string): Promise<boolean> {
+    if (!/^[0-9a-f]{64}$/.test(containerId)) return false;
+    const state = await this.#containerStateById(containerId);
+    if (state === null) return false;
+    if (state === "absent" || state === "exited" || state === "created" || state === "dead") {
+      return true;
+    }
+    if (state !== "running" && state !== "paused" && state !== "restarting") return false;
+    const stopped = await this.deps.docker(["stop", "--time", "10", containerId], {
+      timeoutMs: 60_000,
+      maxOutputBytes: 64 * 1024,
+    });
+    if (stopped.status !== 0) return false;
+    const after = await this.#containerStateById(containerId);
+    return after === "absent" || after === "exited";
+  }
+
+  /** Exactly this container's state by its full id; `absent` only when the
+   *  daemon answered and listed none; null when it did not answer. */
+  async #containerStateById(containerId: string): Promise<string | null> {
+    const result = await this.deps.docker(
+      ["ps", "-a", "--no-trunc", "--filter", `id=${containerId}`, "--format", "{{.ID}}\t{{.State}}"],
+      { timeoutMs: 30_000, maxOutputBytes: 64 * 1024 },
+    );
+    if (result.status !== 0) return null;
+    const rows = result.stdout
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((line) => line.split("\t"));
+    if (rows.length === 0) return "absent";
+    if (rows.length !== 1 || rows[0]![0] !== containerId || typeof rows[0]![1] !== "string") return null;
+    return rows[0]![1].toLowerCase();
+  }
+
+  /**
+   * Why this container may not be started for cleanup, or null. Each
+   * refusal keeps the cleanup failed and the runner pending, as before.
+   * - not `exited`/`created`: paused, restarting or running is not "stopped".
+   * - its own command not `sleep infinity`, or an entrypoint: it would run
+   *   something of the image's.
+   * - an enabled healthcheck, its own or its image's: Docker runs it, project
+   *   code, on its interval as soon as the container starts (a derived
+   *   image's HEALTHCHECK, or one inherited from its base).
+   * - a restart policy other than `no`: Docker could start it again after
+   *   the cleanup stopped it (on a daemon restart, or `unless-stopped`).
+   * - init other than the runner's `init: true` (task-up.sh, since
+   *   2026-05-29): every app container the runner made has Docker's own
+   *   init as PID 1; one without it was not made by the runner's compose.
+   * - auto-remove: `docker stop` would delete the container and its
+   *   writable layer, a destroy outside teardown.
+   */
+  async #startRefusal(container: InspectedApp): Promise<string | null> {
+    if (container.state !== "exited" && container.state !== "created") {
+      return `it is ${container.state}, not stopped`;
+    }
+    if (!container.idle) return "its own command is not the idle one";
+    if (container.restartPolicy !== "no" && container.restartPolicy !== "") {
+      return `its restart policy is ${container.restartPolicy || "unknown"}, not no`;
+    }
+    if (container.init !== true) return "it does not run the station's init";
+    if (container.autoRemove !== false) return "it is removed when it stops";
+    if (container.healthcheck === "enabled") return "it has a healthcheck, which would run the project's code";
+    if (container.healthcheck === "unknown") return "its healthcheck could not be read";
+    if (container.healthcheck === "inherit") {
+      const image = await this.#imageHealthcheck(container.image);
+      if (image === "enabled") return "its image has a healthcheck, which would run the project's code";
+      if (image !== "disabled") return "its image's healthcheck could not be read";
+    }
+    return null;
+  }
+
+  async #imageHealthcheck(image: string | null): Promise<HealthcheckState> {
+    if (image === null) return "unknown";
+    const result = await this.deps.docker(["image", "inspect", image], {
+      timeoutMs: 30_000,
+      maxOutputBytes: 1024 * 1024,
+    });
+    if (result.status !== 0) return "unknown";
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(result.stdout);
+    } catch {
+      return "unknown";
+    }
+    const record = Array.isArray(parsed) && parsed.length === 1 ? (parsed[0] as Record<string, unknown>) : null;
+    if (record === null) return "unknown";
+    const config = record.Config as Record<string, unknown> | null | undefined;
+    if (config === undefined) return "unknown";
+    // An image's own empty or absent test inherits nothing further here:
+    // its build already merged its base's.
+    const state = healthcheckState(config?.Healthcheck);
+    return state === "inherit" ? "disabled" : state;
+  }
+
+  /** The exact app container, by name or id, bound to this locator. */
+  async #inspectApp(ref: string): Promise<
+    | { kind: "found"; container: InspectedApp }
+    | { kind: "refused"; detail: string }
+  > {
+    const result = await this.deps.docker(["container", "inspect", ref], {
+      timeoutMs: 30_000,
+      maxOutputBytes: 1024 * 1024,
+    });
+    if (result.status !== 0) {
+      return { kind: "refused", detail: boundedDockerFailure(result, "inspect the task environment") };
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(result.stdout);
+    } catch {
+      return { kind: "refused", detail: "task environment inspection was not JSON" };
+    }
+    const container = Array.isArray(parsed) && parsed.length === 1 ? (parsed[0] as Record<string, unknown>) : null;
+    const config = container?.Config as Record<string, unknown> | undefined;
+    const labels = config?.Labels as Record<string, unknown> | undefined;
+    const stateRecord = container?.State as Record<string, unknown> | undefined;
+    const hostConfig = container?.HostConfig as Record<string, unknown> | undefined;
+    const restartPolicy = hostConfig?.RestartPolicy as Record<string, unknown> | undefined;
+    const id = container?.Id;
+    const state = stateRecord?.Status;
+    if (
+      typeof id !== "string" ||
+      !/^[0-9a-f]{64}$/.test(id) ||
+      container?.Name !== `/${this.#value.containerName}` ||
+      labels?.["com.docker.compose.project"] !== this.#value.composeProject ||
+      labels?.["com.docker.compose.service"] !== "app" ||
+      (labels?.[PREVIEW_SIDECAR_TASK_LABEL] ?? "") !== "" ||
+      typeof state !== "string"
+    ) {
+      return { kind: "refused", detail: "task environment inspection did not name this task's app container" };
+    }
+    const entrypoint = config?.Entrypoint;
+    const cmd = config?.Cmd;
+    const idle =
+      (entrypoint === null || entrypoint === undefined ||
+        (Array.isArray(entrypoint) && entrypoint.length === 0)) &&
+      Array.isArray(cmd) &&
+      cmd.length === 2 &&
+      cmd[0] === "sleep" &&
+      cmd[1] === "infinity";
+    const image = container?.Image;
+    return {
+      kind: "found",
+      container: {
+        id,
+        state,
+        idle,
+        healthcheck: healthcheckState(config?.Healthcheck),
+        image: typeof image === "string" && image.length > 0 ? image : null,
+        restartPolicy: typeof restartPolicy?.Name === "string" ? restartPolicy.Name : "unknown",
+        init: typeof hostConfig?.Init === "boolean" ? hostConfig.Init : null,
+        autoRemove: typeof hostConfig?.AutoRemove === "boolean" ? hostConfig.AutoRemove : null,
+      },
+    };
+  }
+
+  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);
+}
+
+/** The argv of one `docker exec`, and the environment the docker CLI must run
+ * with to resolve the credentials it names (cliExecEnv). */
+function dockerExecArgs(
+  containerName: string,
+  request:
+    | TaskEnvironmentExecRequest
+    | TaskEnvironmentSpawnRequest
+    | TaskEnvironmentSessionRequest
+    | TaskEnvironmentDetachedSessionRequest,
+  mode: "interactive" | "detached" = "interactive",
+  /** Passed only by exec(), after assertTaskEnvironmentExecRequest. */
+  privileged = false,
+): { args: string[]; env: NodeJS.ProcessEnv | undefined } {
+  const args = ["exec", mode === "detached" ? "-d" : "-i"];
+  if (privileged) args.push("--privileged");
+  if (request.cwd) args.push("--workdir", request.cwd);
+  if (request.user) args.push("--user", request.user);
+  const execEnv = cliExecEnv(request);
+  args.push(...execEnv.args, containerName, ...request.argv);
+  return { args, env: execEnv.env };
+}
+
+/**
+ * The `--env` options of one exec, for a CLI that resolves a bare
+ * `--env NAME` from its own environment (docker, Apple `container`), and the
+ * environment the CLI child must then run with.
+ *
+ * An engine credential, or an agent's task token under any of its names, is
+ * named bare and its value set in that child's environment only, so it never
+ * lands on the runner's argv, which every local user can read with `ps`
+ * (ADR-154 §6). The request's value wins over the
+ * runner's own variable of the same name (an owned runner may still carry a
+ * legacy CLAUDE_CODE_OAUTH_TOKEN), and a credential the request does not
+ * carry is never named here; a name in `inheritEnv` still forwards the
+ * runner's own value, as that field promises. Every other entry keeps its
+ * `NAME=value` form: in the child's environment, a task's HOME or PATH would
+ * steer the CLI's own config and credential-helper lookup. With no
+ * credential, `env` is undefined and the child inherits the runner's
+ * environment as before.
+ */
+export function cliExecEnv(request: {
+  inheritEnv?: readonly string[];
+  env?: Readonly<Record<string, string>>;
+}): { args: string[]; env: NodeJS.ProcessEnv | undefined } {
+  const args: string[] = [];
+  for (const name of request.inheritEnv ?? []) {
+    if (process.env[name] !== undefined) args.push("--env", name);
+  }
+  const credentials: Record<string, string> = {};
+  for (const [name, value] of Object.entries(request.env ?? {}).sort(([a], [b]) =>
+    a.localeCompare(b),
+  )) {
+    if (isLaunchSecretEnvName(name)) {
+      args.push("--env", name);
+      credentials[name] = value;
+    } else {
+      args.push("--env", `${name}=${value}`);
+    }
+  }
+  return {
+    args,
+    env:
+      Object.keys(credentials).length === 0
+        ? undefined
+        : { ...process.env, ...credentials },
+  };
+}
+
+/** 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,
+  /** The child's own environment, when it must differ from the runner's
+   * (cliExecEnv). */
+  env?: NodeJS.ProcessEnv,
+): Promise<TaskEnvironmentExecResult> {
+  return new Promise((resolve) => {
+    const child = spawn(command, [...args], {
+      stdio: ["pipe", "pipe", "pipe"],
+      ...(env === undefined ? {} : { env }),
+    }) 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,
+  /** As for capturedCliExec. */
+  env?: NodeJS.ProcessEnv,
+): TaskEnvironmentProcess {
+  const child = spawn(command, [...args], {
+    stdio: ["pipe", "pipe", "pipe"],
+    ...(env === undefined ? {} : { env }),
+  }) 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,
+    ...(state === "paused" || state === "restarting" ? { frozen: true as const } : {}),
+  };
+}
+
+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}` : ""}`);
+}
+
+/** What `docker container inspect` says of an app container that the boot
+ *  sweep may start for cleanup (`#startRefusal`). */
+interface InspectedApp {
+  id: string;
+  state: string;
+  idle: boolean;
+  healthcheck: HealthcheckState;
+  image: string | null;
+  restartPolicy: string;
+  init: boolean | null;
+  autoRemove: boolean | null;
+}
+
+/** `disabled`: no test, or `["NONE"]`. `inherit`: a container's absent or
+ *  empty test, which Docker reads as "the image's". */
+type HealthcheckState = "enabled" | "disabled" | "inherit" | "unknown";
+
+function healthcheckState(healthcheck: unknown): HealthcheckState {
+  if (healthcheck === undefined || healthcheck === null) return "inherit";
+  if (typeof healthcheck !== "object" || Array.isArray(healthcheck)) return "unknown";
+  const test = (healthcheck as Record<string, unknown>).Test;
+  if (test === undefined || test === null) return "inherit";
+  if (!Array.isArray(test)) return "unknown";
+  if (test.length === 0) return "inherit";
+  if (test.length === 1 && test[0] === "NONE") return "disabled";
+  return "enabled";
+}
+
+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);
+}