@runuai/host 0.9.13 → 0.9.42

package/lib/task-environment/apple-container.ts

@@ -0,0 +1,757 @@
+/**
+ * ADR-106 Apple container TaskEnvironment provider.
+ *
+ * One lightweight VM per task container via Apple's `container` toolchain,
+ * invoked ONLY through the authenticated bundled CLI path resolved from the
+ * capability-3 descriptor — never from PATH. Container IPs are host-routable
+ * over vmnet, so editor/preview routing dials the container address directly
+ * and this provider publishes no host ports at all.
+ *
+ * CLI semantics encoded here were probed against container 1.2.2:
+ * - `inspect <name>` exits 1 with "container not found" for absence and
+ *   otherwise prints a JSON array with {id, status:{state, networks[]},
+ *   configuration:{labels, image, mounts}}; `id` IS the container name.
+ * - `stop` is idempotent (exit 0 for an already-stopped container).
+ * - `cp` uses docker-style `name:path` addressing.
+ * - `exec` supports -i/-d, --env K=V and bare K inheritance, --user,
+ *   --workdir.
+ */
+
+import { spawn as nodeSpawn } from "node:child_process";
+import { lstatSync } from "node:fs";
+import path from "node:path";
+
+import type { TaskDownResult } from "../agent";
+import { assertSafeHostTaskId } from "../task-identity";
+import {
+  capturedCliExec,
+  streamingCliExec,
+} from "./docker";
+import {
+  assertTaskEnvironmentProcessRequest,
+  assertTaskEnvironmentSessionRequest,
+  type TaskEnvironmentCopyRequest,
+  type TaskEnvironmentDescriptor,
+  type TaskEnvironmentDetachedSessionRequest,
+  type TaskEnvironmentExecRequest,
+  type TaskEnvironmentExecResult,
+  type TaskEnvironmentHandle,
+  type TaskEnvironmentLocator,
+  type TaskEnvironmentPort,
+  type TaskEnvironmentProcess,
+  type TaskEnvironmentProvider,
+  type TaskEnvironmentRecoveryContext,
+  type TaskEnvironmentRecoveryResult,
+  type TaskEnvironmentSessionRequest,
+  type TaskEnvironmentSpawnRequest,
+  type TaskEnvironmentStatus,
+} from "./types";
+
+export const APPLE_TASK_ENVIRONMENT_PROVIDER = "apple-container";
+const APPLE_LOCATOR_SCHEMA_VERSION = 1;
+const MAX_LOCATOR_COMPONENT = 512;
+const INSPECT_OUTPUT_LIMIT = 256 * 1024;
+export const APPLE_TASK_LABEL = "com.uai.task";
+
+export interface AppleMachineIdentity {
+  backend: "apple-container";
+  /** The per-user state root that owns every container (application
+   * support directory of the bundled toolchain). */
+  endpoint: string;
+  /** Host-minted durable installation id — the daemon-ID equivalent for a
+   * runtime with no daemon identity of its own. */
+  engineId: string;
+}
+
+interface AppleTaskEnvironmentLocatorValue {
+  schemaVersion: typeof APPLE_LOCATOR_SCHEMA_VERSION;
+  taskId: string;
+  containerName: string;
+  hostWorktreePath: string;
+  machine: AppleMachineIdentity;
+}
+
+export interface AppleCliResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  truncated?: boolean;
+}
+
+export type AppleCliRunner = (
+  args: readonly string[],
+  options: { timeoutMs: number; maxOutputBytes: number },
+) => Promise<AppleCliResult>;
+
+export interface AppleContainerTaskEnvironmentDeps<
+  TInput = never,
+  TCredentials = never,
+  TResult = never,
+> {
+  /** Absolute path of the authenticated bundled `container` CLI. Late-bound
+   * so an HMR reload or runtime re-resolution cannot strand a stale path. */
+  containerCliPath: () => string;
+  machineIdentity: () => AppleMachineIdentity;
+  /** Captured (non-streaming) CLI operations. Tests inject a fake. */
+  run?: AppleCliRunner;
+  spawn?: typeof nodeSpawn;
+  /** Provisioning is wired only where the concrete task-up contract exists
+   * (lib/task-environment/index.ts); this module stays agnostic of it. An
+   * absent group keeps provision() fail-closed. */
+  provisioning?: AppleContainerProvisioningDeps<TInput, TCredentials, TResult>;
+  /** Complete teardown through task-down.sh (container + derived image +
+   * workspace + durable row). Production wiring always supplies it. */
+  taskEnvironmentDown?: (taskId: string) => Promise<TaskDownResult>;
+  /** Late-bound recovery implementation (orchestrator-owned, like Docker's). */
+  recoveryDriver?: () => AppleTaskEnvironmentRecoveryDriver | null;
+}
+
+/** The operational surface every handle needs; provisioning stays separate so
+ * a reconstruct-only registration keeps its narrower obligations. */
+interface ResolvedAppleContainerDeps {
+  containerCliPath: () => string;
+  machineIdentity: () => AppleMachineIdentity;
+  run: AppleCliRunner;
+  spawn: typeof nodeSpawn;
+  taskEnvironmentDown?: (taskId: string) => Promise<TaskDownResult>;
+  recoveryDriver?: () => AppleTaskEnvironmentRecoveryDriver | null;
+}
+
+export type AppleTaskEnvironmentRecoveryDriver = (
+  descriptor: TaskEnvironmentDescriptor,
+  context: TaskEnvironmentRecoveryContext,
+) => Promise<TaskEnvironmentRecoveryResult>;
+
+export interface AppleContainerProvisioningDeps<TInput, TCredentials, TResult> {
+  /** Runs task-up with the selection environment already published by the
+   * runtime pin (UAI_TASK_RUNTIME / UAI_CONTAINER_CLI). */
+  taskUp: (input: TInput, credentials?: TCredentials) => Promise<TResult>;
+  inputTaskId: (input: TInput) => string;
+  /** The host worktree path this task will occupy, derivable before task-up
+   * runs so a crash mid-provision still leaves a recoverable locator. */
+  hostWorktreePath: (taskId: string) => string;
+  resultWorktreePath: (result: TResult) => string;
+}
+
+export function appleTaskContainerName(taskId: string): string {
+  assertSafeHostTaskId(taskId);
+  return `task-${taskId}-app`;
+}
+
+export function createAppleContainerTaskEnvironmentProvider<
+  TInput = never,
+  TCredentials = never,
+  TResult = never,
+>(
+  deps: AppleContainerTaskEnvironmentDeps<TInput, TCredentials, TResult>,
+): TaskEnvironmentProvider<TInput, TCredentials, TResult, TaskDownResult> {
+  const resolved = {
+    containerCliPath: deps.containerCliPath,
+    machineIdentity: deps.machineIdentity,
+    run: deps.run ?? defaultRunner(deps.containerCliPath),
+    spawn: deps.spawn ?? nodeSpawn,
+    taskEnvironmentDown: deps.taskEnvironmentDown,
+    recoveryDriver: deps.recoveryDriver,
+  };
+  const provisioning = deps.provisioning;
+  return {
+    kind: APPLE_TASK_ENVIRONMENT_PROVIDER,
+    async provision(request) {
+      if (provisioning === undefined) {
+        throw new Error("apple-container provisioning is not available yet");
+      }
+      if (request.taskId !== provisioning.inputTaskId(request.input)) {
+        throw new Error("task environment provision identity mismatch");
+      }
+      const machine = validateAppleMachineIdentity(resolved.machineIdentity());
+      const preparedLocator = appleTaskEnvironmentLocator(
+        request.taskId,
+        provisioning.hostWorktreePath(request.taskId),
+        machine,
+      );
+      await request.onPrepared?.(preparedLocator);
+      const result = await provisioning.taskUp(
+        request.input,
+        request.credentials,
+      );
+      const prepared = parseAppleTaskEnvironmentLocator(preparedLocator);
+      // task-up composes its worktree path in shell from the operator's
+      // UAI_WORKSPACE_ROOT verbatim; resolve before comparing so a benign
+      // trailing slash cannot fail the proof after the container is up, while
+      // a genuinely different directory still fails closed.
+      if (
+        path.resolve(provisioning.resultWorktreePath(result)) !==
+        prepared.hostWorktreePath
+      ) {
+        throw new Error(
+          "task environment returned an unexpected worktree path",
+        );
+      }
+      return {
+        handle: new AppleContainerTaskEnvironmentHandle(
+          preparedLocator,
+          resolved,
+        ),
+        result,
+      };
+    },
+    async reconstruct(locator) {
+      const persisted = parseAppleTaskEnvironmentLocator(locator);
+      const current = validateAppleMachineIdentity(resolved.machineIdentity());
+      if (
+        persisted.machine.endpoint !== current.endpoint ||
+        persisted.machine.engineId !== current.engineId
+      ) {
+        throw new Error(
+          "task environment belongs to a different container backend",
+        );
+      }
+      return new AppleContainerTaskEnvironmentHandle(locator, resolved);
+    },
+  };
+}
+
+export function appleTaskEnvironmentLocator(
+  taskId: string,
+  hostWorktreePath: string,
+  machine: AppleMachineIdentity,
+): TaskEnvironmentLocator {
+  const value: AppleTaskEnvironmentLocatorValue = {
+    schemaVersion: APPLE_LOCATOR_SCHEMA_VERSION,
+    taskId,
+    containerName: appleTaskContainerName(taskId),
+    hostWorktreePath,
+    machine: validateAppleMachineIdentity(machine),
+  };
+  validateAppleLocatorValue(value);
+  return {
+    schemaVersion: 1,
+    provider: APPLE_TASK_ENVIRONMENT_PROVIDER,
+    value,
+  };
+}
+
+export function parseAppleTaskEnvironmentLocator(
+  locator: TaskEnvironmentLocator,
+): AppleTaskEnvironmentLocatorValue {
+  if (
+    locator.schemaVersion !== 1 ||
+    locator.provider !== APPLE_TASK_ENVIRONMENT_PROVIDER
+  ) {
+    throw new Error(
+      "task environment locator does not belong to Apple container",
+    );
+  }
+  return validateAppleLocatorValue(locator.value);
+}
+
+class AppleContainerTaskEnvironmentHandle
+  implements TaskEnvironmentHandle<TaskDownResult>
+{
+  readonly descriptor: TaskEnvironmentDescriptor;
+  readonly durableIdentity: string;
+  readonly #value: AppleTaskEnvironmentLocatorValue;
+
+  constructor(
+    locator: TaskEnvironmentLocator,
+    private readonly deps: ResolvedAppleContainerDeps,
+  ) {
+    this.#value = parseAppleTaskEnvironmentLocator(locator);
+    this.durableIdentity = this.#value.containerName;
+    this.descriptor = {
+      taskId: this.#value.taskId,
+      locator,
+      workspacePath: "/workspace",
+    };
+  }
+
+  exec(request: TaskEnvironmentExecRequest): Promise<TaskEnvironmentExecResult> {
+    assertTaskEnvironmentProcessRequest(request);
+    return capturedCliExec(
+      this.deps.spawn,
+      this.deps.containerCliPath(),
+      appleExecArgs(this.#value.containerName, request, "interactive"),
+      request,
+    );
+  }
+
+  async spawn(
+    request: TaskEnvironmentSpawnRequest,
+  ): Promise<TaskEnvironmentProcess> {
+    assertTaskEnvironmentProcessRequest(request);
+    return streamingCliExec(
+      this.deps.spawn,
+      this.deps.containerCliPath(),
+      appleExecArgs(this.#value.containerName, request, "interactive"),
+      request,
+    );
+  }
+
+  async spawnSession(
+    request: TaskEnvironmentSessionRequest,
+  ): Promise<TaskEnvironmentProcess> {
+    assertTaskEnvironmentSessionRequest(request);
+    return streamingCliExec(
+      this.deps.spawn,
+      this.deps.containerCliPath(),
+      appleExecArgs(this.#value.containerName, request, "interactive"),
+      request,
+    );
+  }
+
+  async launchDetachedSession(
+    request: TaskEnvironmentDetachedSessionRequest,
+  ): Promise<TaskEnvironmentExecResult> {
+    assertTaskEnvironmentSessionRequest(request);
+    const result = await this.deps.run(
+      appleExecArgs(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.truncated === true,
+      stderrTruncated: result.truncated === 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.run(args, {
+      timeoutMs: 120_000,
+      maxOutputBytes: 1024 * 1024,
+    });
+    requireCliSuccess(result, "copy task environment data");
+  }
+
+  async ports(): Promise<TaskEnvironmentPort[]> {
+    // Direct-IP model: nothing is published on the host. Editor/preview
+    // routing resolves the container's vmnet address per connection through
+    // the provider-private inspection below.
+    return [];
+  }
+
+  async status(): Promise<TaskEnvironmentStatus> {
+    const inspected = await this.inspect();
+    // Workspace presence is a DISK fact, independent of container state: an
+    // absent container preserves its worktree (the cloud's stopped-vs-error
+    // decision hangs on exactly this), and a present container can have lost
+    // it. Only a real non-symlink directory counts.
+    const workspacePresent = ((): boolean => {
+      try {
+        const stat = lstatSync(
+          path.join(this.#value.hostWorktreePath, "workspace"),
+        );
+        return stat.isDirectory() && !stat.isSymbolicLink();
+      } catch {
+        return false;
+      }
+    })();
+    if (inspected.kind === "absent") {
+      return { state: "absent", instances: [], workspacePresent };
+    }
+    if (inspected.kind === "unknown") {
+      return { state: "unknown", detail: inspected.detail };
+    }
+    if (inspected.taskLabel !== this.#value.taskId) {
+      // A same-name container that does not carry this task's label is a
+      // foreign object, not this environment. It must never be started,
+      // executed into, or treated as evidence of any state.
+      return {
+        state: "unknown",
+        detail: "the task container name is held by a foreign container",
+      };
+    }
+    // Only exact terminal states map. A transitional answer ("starting",
+    // "stopping", ...) reported as stopped would let recovery issue a
+    // redundant start and persist stopped while the container goes live.
+    if (inspected.state !== "running" && inspected.state !== "stopped") {
+      return {
+        state: "unknown",
+        detail: `the task container is in a transitional state (${inspected.state})`,
+      };
+    }
+    return {
+      state: inspected.state,
+      instances: [this.#value.containerName],
+      workspacePresent,
+    };
+  }
+
+  async recover(
+    context: TaskEnvironmentRecoveryContext,
+  ): Promise<TaskEnvironmentRecoveryResult> {
+    const driver = this.deps.recoveryDriver?.();
+    if (driver) return driver(this.descriptor, context);
+    // Without a driver (provider tests), only a live environment may claim
+    // recovery; stopped/absent is deferred so it can never read as healthy.
+    const status = await this.status();
+    if (status.state === "unknown") {
+      return { outcome: "deferred", detail: status.detail };
+    }
+    if (status.state === "running") {
+      return { outcome: "recovered", status };
+    }
+    return {
+      outcome: "deferred",
+      detail: `task environment is ${status.state} and no recovery driver is bound`,
+    };
+  }
+
+  async stop(): Promise<void> {
+    // Idempotent by CLI contract (verified: exit 0 on already-stopped).
+    const result = await this.deps.run(
+      ["stop", this.#value.containerName],
+      { timeoutMs: 60_000, maxOutputBytes: 256 * 1024 },
+    );
+    if (
+      result.status !== 0 &&
+      !isNotFound(result, this.#value.containerName)
+    ) {
+      requireCliSuccess(result, "stop task environment");
+    }
+  }
+
+  async teardown(): Promise<TaskDownResult> {
+    // task-down.sh owns complete destruction — container, derived image, the
+    // task directory with its writable Git data, and the durable row — with
+    // its own name-anchored absence proof. The container-only path below
+    // exists for provider tests; production wiring always injects the script.
+    if (this.deps.taskEnvironmentDown !== undefined) {
+      return this.deps.taskEnvironmentDown(this.#value.taskId);
+    }
+    await this.stop();
+    const removed = await this.deps.run(
+      ["rm", this.#value.containerName],
+      { timeoutMs: 60_000, maxOutputBytes: 256 * 1024 },
+    );
+    const alreadyGone = isNotFound(removed, this.#value.containerName);
+    if (removed.status !== 0 && !alreadyGone) {
+      requireCliSuccess(removed, "remove task environment");
+    }
+    const after = await this.inspect();
+    if (after.kind !== "absent") {
+      throw new Error(
+        after.kind === "unknown"
+          ? `task environment teardown is unconfirmed: ${after.detail}`
+          : "task environment teardown left the container present",
+      );
+    }
+    return alreadyGone ? { alreadyGone: true } : { status: "removed" };
+  }
+
+  /** Provider-private identity-bound inspection: the routing layer uses the
+   * returned vmnet address only together with the task-label proof. */
+  async inspectRoute(): Promise<
+    | { kind: "running"; ipv4Address: string }
+    | { kind: "unavailable" }
+    | { kind: "unknown"; detail: string }
+  > {
+    const inspected = await this.inspect();
+    if (inspected.kind === "absent") return { kind: "unavailable" };
+    if (inspected.kind === "unknown") return inspected;
+    if (
+      inspected.state !== "running" ||
+      inspected.taskLabel !== this.#value.taskId ||
+      inspected.ipv4Address === null
+    ) {
+      return { kind: "unavailable" };
+    }
+    return { kind: "running", ipv4Address: inspected.ipv4Address };
+  }
+
+  async inspect(): Promise<
+    | { kind: "present"; state: string; taskLabel: string | null; ipv4Address: string | null }
+    | { kind: "absent" }
+    | { kind: "unknown"; detail: string }
+  > {
+    const result = await this.deps.run(
+      ["inspect", this.#value.containerName],
+      { timeoutMs: 15_000, maxOutputBytes: INSPECT_OUTPUT_LIMIT },
+    );
+    if (result.status !== 0) {
+      if (isNotFound(result, this.#value.containerName)) {
+        return { kind: "absent" };
+      }
+      return {
+        kind: "unknown",
+        detail: boundedDetail(result.stderr) || "container inspect failed",
+      };
+    }
+    if (result.truncated === true) {
+      return { kind: "unknown", detail: "container inspect output overflowed" };
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(result.stdout);
+    } catch {
+      return { kind: "unknown", detail: "container inspect output is not JSON" };
+    }
+    if (!Array.isArray(parsed) || parsed.length !== 1) {
+      return { kind: "unknown", detail: "container inspect shape is invalid" };
+    }
+    const entry = parsed[0] as {
+      id?: unknown;
+      status?: { state?: unknown; networks?: unknown };
+      configuration?: { labels?: unknown };
+    };
+    if (entry.id !== this.#value.containerName) {
+      return { kind: "unknown", detail: "container inspect identity mismatch" };
+    }
+    const state =
+      typeof entry.status?.state === "string" ? entry.status.state : null;
+    if (state === null) {
+      return { kind: "unknown", detail: "container inspect state is missing" };
+    }
+    const labels = entry.configuration?.labels;
+    const taskLabel =
+      labels && typeof labels === "object" && !Array.isArray(labels)
+        ? typeof (labels as Record<string, unknown>)[APPLE_TASK_LABEL] === "string"
+          ? ((labels as Record<string, unknown>)[APPLE_TASK_LABEL] as string)
+          : null
+        : null;
+    return {
+      kind: "present",
+      state,
+      taskLabel,
+      ipv4Address: firstIpv4(entry.status?.networks),
+    };
+  }
+}
+
+function appleExecArgs(
+  containerName: string,
+  request:
+    | TaskEnvironmentExecRequest
+    | TaskEnvironmentSpawnRequest
+    | TaskEnvironmentSessionRequest
+    | TaskEnvironmentDetachedSessionRequest,
+  mode: "interactive" | "detached",
+): 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(
+    ([left], [right]) => left.localeCompare(right),
+  )) {
+    args.push("--env", `${name}=${value}`);
+  }
+  args.push(containerName, ...request.argv);
+  return args;
+}
+
+export function appleCliRunner(
+  containerCliPath: () => string,
+): AppleCliRunner {
+  return defaultRunner(containerCliPath);
+}
+
+function defaultRunner(containerCliPath: () => string): AppleCliRunner {
+  return (args, options) =>
+    new Promise((resolve) => {
+      const child = nodeSpawn(containerCliPath(), [...args], {
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      const stdout: Buffer[] = [];
+      const stderr: Buffer[] = [];
+      let bytes = 0;
+      let truncated = false;
+      const collect = (target: Buffer[]) => (chunk: Buffer) => {
+        bytes += chunk.length;
+        if (bytes > options.maxOutputBytes) {
+          truncated = true;
+          child.kill("SIGKILL");
+          // The overflow kill needs the same bounded settlement as the
+          // deadline kill: an unreapable child must not strand the caller.
+          const settle = setTimeout(() => finish(null), 5_000);
+          settle.unref?.();
+        } else {
+          target.push(chunk);
+        }
+      };
+      child.stdout.on("data", collect(stdout));
+      child.stderr.on("data", collect(stderr));
+      let settled = false;
+      const timer = setTimeout(() => {
+        child.kill("SIGKILL");
+        // A SIGKILLed CLI normally closes at once, but an unreapable child
+        // must not strand activation/recovery on a promise that never
+        // settles — the caller's deadline has already expired.
+        const settle = setTimeout(() => finish(null), 5_000);
+        settle.unref?.();
+      }, options.timeoutMs);
+      timer.unref?.();
+      const finish = (status: number | null): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve({
+          status,
+          stdout: Buffer.concat(stdout).toString("utf8"),
+          stderr: Buffer.concat(stderr).toString("utf8"),
+          truncated,
+        });
+      };
+      child.once("error", (error) => {
+        stderr.push(Buffer.from(error.message));
+        finish(null);
+      });
+      child.once("close", (code) => finish(code));
+    });
+}
+
+function validateAppleMachineIdentity(
+  value: AppleMachineIdentity,
+): AppleMachineIdentity {
+  if (value.backend !== "apple-container") {
+    throw new Error("Apple container machine backend is invalid");
+  }
+  const endpoint = exactComponent(value.endpoint, "machine endpoint");
+  if (!endpoint.startsWith("/")) {
+    throw new Error("Apple container machine endpoint must be absolute");
+  }
+  const engineId = exactComponent(value.engineId, "installation id");
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(engineId)) {
+    throw new Error("Apple container installation id is invalid");
+  }
+  return { backend: "apple-container", endpoint, engineId };
+}
+
+function validateAppleLocatorValue(
+  value: unknown,
+): AppleTaskEnvironmentLocatorValue {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Apple container locator must be an object");
+  }
+  const record = value as Record<string, unknown>;
+  const allowed = new Set([
+    "schemaVersion",
+    "taskId",
+    "containerName",
+    "hostWorktreePath",
+    "machine",
+  ]);
+  if (Object.keys(record).some((key) => !allowed.has(key))) {
+    throw new Error("Apple container locator has unexpected fields");
+  }
+  if (record.schemaVersion !== APPLE_LOCATOR_SCHEMA_VERSION) {
+    throw new Error("unsupported Apple container locator schema");
+  }
+  const taskId = exactComponent(record.taskId, "task id");
+  assertSafeHostTaskId(taskId);
+  if (record.containerName !== appleTaskContainerName(taskId)) {
+    throw new Error("Apple container locator name does not match its task");
+  }
+  const hostWorktreePath = exactComponent(
+    record.hostWorktreePath,
+    "worktree path",
+    4096,
+  );
+  if (!hostWorktreePath.startsWith("/")) {
+    throw new Error("Apple container locator worktree path must be absolute");
+  }
+  const machine = validateAppleMachineIdentity(
+    record.machine as AppleMachineIdentity,
+  );
+  return {
+    schemaVersion: APPLE_LOCATOR_SCHEMA_VERSION,
+    taskId,
+    containerName: record.containerName,
+    hostWorktreePath,
+    machine,
+  };
+}
+
+function validateCopyRequest(request: TaskEnvironmentCopyRequest): void {
+  if (request.direction !== "into" && request.direction !== "out") {
+    throw new Error("task environment copy direction is invalid");
+  }
+  for (const [label, value] of [
+    ["source", request.source],
+    ["destination", request.destination],
+  ] as const) {
+    if (
+      typeof value !== "string" ||
+      value.length === 0 ||
+      value.length > 4096 ||
+      /[\0\r\n]/.test(value) ||
+      value.includes(":")
+    ) {
+      throw new Error(`task environment copy ${label} is invalid`);
+    }
+  }
+}
+
+function requireCliSuccess(result: AppleCliResult, operation: string): void {
+  if (result.status === 0) return;
+  const detail = boundedDetail(result.stderr || result.stdout);
+  throw new Error(`${operation} failed${detail ? `: ${detail}` : ""}`);
+}
+
+/** The CLI exits nonzero for both a missing container and a broken
+ * apiserver; only the not-found error that names this exact container proves
+ * absence. Anything else is unknown and must never authorize destruction. */
+function isNotFound(result: AppleCliResult, containerName: string): boolean {
+  // Substring matching would let `container not found: <name>-shadow` prove
+  // the absence of <name>. Require the complete bounded error line and no
+  // stdout at all.
+  return (
+    result.status !== 0 &&
+    result.stdout.trim() === "" &&
+    result.stderr
+      .split("\n")
+      .some((line) => line.trim() === `Error: container not found: ${containerName}`)
+  );
+}
+
+function boundedDetail(text: string): string {
+  return text.trim().slice(0, 512);
+}
+
+function firstIpv4(networks: unknown): string | null {
+  if (!Array.isArray(networks)) return null;
+  for (const network of networks) {
+    const address = (network as { ipv4Address?: unknown })?.ipv4Address;
+    if (typeof address === "string") {
+      const bare = address.split("/")[0]!;
+      if (/^\d{1,3}(?:\.\d{1,3}){3}$/.test(bare)) return bare;
+    }
+  }
+  return null;
+}
+
+function exactComponent(
+  value: unknown,
+  label: string,
+  maxLength = MAX_LOCATOR_COMPONENT,
+): string {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > maxLength ||
+    /[\0\r\n]/.test(value)
+  ) {
+    throw new Error(`Apple container ${label} is invalid`);
+  }
+  return value;
+}