@runuai/host 0.9.14 → 0.9.42

package/lib/container-runtime.ts

@@ -0,0 +1,1338 @@
+/**
+ * Container-runtime detection and process-wide selection (ADR-101/ADR-106).
+ *
+ * The Docker paths keep the selected endpoint in `DOCKER_HOST` so every
+ * docker-invoking module follows the same daemon. ADR-106 adds the bundled
+ * Apple container backend, preferred wherever it can run: `auto` resolves the
+ * durable stateful-provider claim first, then the eligible bundled runtime,
+ * then ambient Docker — and the process pin plus the minted installation
+ * identity keep a wiped or replaced toolchain state fail-closed, exactly like
+ * a replaced Docker daemon at the same socket.
+ */
+
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { readFile as fsReadFile, writeFile as fsWriteFile } from "node:fs/promises";
+import { release as osRelease } from "node:os";
+import path from "node:path";
+
+import { dockerCli, type DockerResult } from "./docker-exec";
+import { env } from "./env";
+import { claimManagedRuntimeCapabilityFloor } from "./managed-runtime";
+import {
+  fileRuntimeProviderStateStore,
+  runtimeProviderStatePath,
+  type RuntimeProviderStateStore,
+} from "./runtime-provider-state";
+
+export type RuntimePreference = "auto" | "docker" | "apple-container";
+
+export type ContainerRuntimeState =
+  | {
+      status: "checking";
+      preference: RuntimePreference;
+      /** Human-readable activation phase (boot visibility; ADR-106 smoke). */
+      detail?: string;
+    }
+  | {
+      status: "ready";
+      preference: "auto" | "docker";
+      provider: "docker";
+    }
+  | {
+      status: "ready";
+      preference: "auto" | "apple-container";
+      provider: "apple-container";
+    }
+  | {
+      status: "no-runtime";
+      preference: RuntimePreference;
+      message: string;
+      action: string;
+    };
+
+export const RUNTIME_RECHECK_COMMAND = "uai-host runtime recheck";
+const RUNTIME_RESTART_COMMAND = "uai-host restart";
+
+const NO_RUNTIME_MESSAGE =
+  "No working container runtime was found. Install or start Docker, then run " +
+  `\`${RUNTIME_RECHECK_COMMAND}\`.`;
+const APPLE_RUNTIME_UNAVAILABLE_MESSAGE =
+  "The bundled Apple container runtime could not be started. " +
+  `Run \`${RUNTIME_RECHECK_COMMAND}\` to retry, or set UAI_RUNTIME=docker ` +
+  `and run \`${RUNTIME_RESTART_COMMAND}\` to use Docker instead.`;
+const PINNED_RUNTIME_UNAVAILABLE_MESSAGE =
+  "The Docker runtime selected for this Uai Host process is not responding. " +
+  `Start it and run \`${RUNTIME_RECHECK_COMMAND}\`. ` +
+  `To use a different Docker context or endpoint, run \`${RUNTIME_RESTART_COMMAND}\` ` +
+  "after selecting it.";
+
+let state: ContainerRuntimeState = {
+  status: "checking",
+  preference: runtimePreference(process.env.UAI_RUNTIME),
+};
+let operational = false;
+let activationRequired = false;
+let readinessEpoch = 0;
+
+type RuntimeChangeListener = (
+  next: ContainerRuntimeState,
+  previous: ContainerRuntimeState,
+) => void;
+
+const listeners = new Set<RuntimeChangeListener>();
+let detectionInFlight: Promise<ContainerRuntimeState> | null = null;
+// Once a local endpoint answers, every Docker/Compose child in this process
+// must stay on it. Switching a live host to another daemon strands the first
+// daemon's containers, images, and volumes and makes taskDown target the wrong
+// machine. A service restart is the deliberate endpoint-switch boundary.
+let pinnedDockerHost: string | null = null;
+let pinnedRuntimeProvider: "docker" | "apple-container" | null = null;
+let pinnedDockerEngineId: string | null = null;
+function defaultRuntimeProviderStateStore(): RuntimeProviderStateStore {
+  // Resolve env lazily. Several consumers import standard-image/runtime code
+  // under narrow env mocks, and module import must remain side-effect free.
+  const store = fileRuntimeProviderStateStore(
+    runtimeProviderStatePath(env.dataDir),
+  );
+  return {
+    read: () => store.read(),
+    claim: async (provider) => {
+      // The version-independent rollback guard must commit under the managed
+      // operation lock before the provider marker. A crash between them is
+      // conservative (capability-1 rollback stays disabled) and owns no
+      // provider resources; the inverse order could strand state on an old
+      // runtime.
+      // Apple provider state is only usable by a capability-3 generation
+      // (bundled CLI + kernel). Floor 2 would let an interrupted rollback
+      // resurrect a Lima-era generation over preserved Apple state.
+      await claimManagedRuntimeCapabilityFloor(3);
+      return store.claim(provider);
+    },
+  };
+}
+
+interface OperationalWaiter {
+  epoch: number;
+  finish: (operational: boolean) => void;
+  timer: NodeJS.Timeout;
+}
+
+const operationalWaiters = new Set<OperationalWaiter>();
+
+interface DockerSelection {
+  host: string;
+}
+
+export interface DockerDaemonProof {
+  /** Docker Engine's stable daemon identity (`docker info .ID`). */
+  engineId: string;
+  serverVersion: string;
+}
+
+export interface RuntimeDetectionDeps {
+  preference?: RuntimePreference;
+  dockerInfo?: (selection?: DockerSelection) => Promise<DockerResult>;
+  /** Test seam for the context/endpoint resolver. */
+  dockerSelection?: () => Promise<DockerSelection | null>;
+  /** Bundled Apple container seam; `undefined` uses the registered binding. */
+  appleRuntime?: AppleRuntimeBinding | null;
+  /** Test seam for bounded bundled-CLI invocations. */
+  appleCli?: (
+    args: readonly string[],
+    options: { timeoutMs: number; maxOutputBytes: number },
+  ) => Promise<{ status: number | null; stdout: string; stderr: string }>;
+  /** Test seam for the minted installation identity. */
+  appleInstallationId?: {
+    read: (endpoint: string) => Promise<string | null>;
+    mint: (endpoint: string) => Promise<string>;
+  };
+  /** Test seam for the durable-row selection guard. */
+  appleSelectionGuard?:
+    | ((endpoint: string) => boolean | Promise<boolean>)
+    | null;
+  /** Test seam; production always uses os.release() (Darwin 25 = macOS 26). */
+  darwinRelease?: string;
+  /** Durable task-state ownership seam. */
+  providerStateStore?: RuntimeProviderStateStore;
+  /** Test seam; production always uses process.platform. */
+  platform?: NodeJS.Platform;
+}
+
+interface RuntimeAutoRecheckOptions extends RuntimeDetectionDeps {
+  /** Fast first retry covers Docker Desktop / OrbStack boot ordering. */
+  firstDelayMs?: number;
+  /** Later retries stay cheap while a daemon or desktop app starts. */
+  intervalMs?: number;
+  /** Bound background probing; an explicit recheck remains available later. */
+  maxAttempts?: number;
+}
+
+/** Parse an operator override without letting a typo silently pick a backend. */
+export function runtimePreference(value: string | undefined): RuntimePreference {
+  return value === "docker" || value === "apple-container" ? value : "auto";
+}
+
+/** Authenticated bundled Apple container toolchain (ADR-106). */
+export interface AppleRuntimeBinding {
+  /** Absolute path of the signed bundled `container` CLI. */
+  readonly containerCliPath: string;
+  /** Absolute path of the pinned guest kernel staged in the bundle. */
+  readonly kernelPath: string;
+}
+
+let appleRuntime: AppleRuntimeBinding | null = null;
+
+/** Register the bundled Apple container toolchain from the active signed
+ * runtime. A source checkout, Intel Mac, or Linux archive registers null and
+ * keeps apple-container selection fail-closed. */
+export function setAppleContainerRuntime(
+  binding: AppleRuntimeBinding | null,
+): void {
+  if (
+    pinnedRuntimeProvider !== null &&
+    (binding === null) !== (appleRuntime === null)
+  ) {
+    throw new Error(
+      "the Apple container runtime cannot change after container runtime selection",
+    );
+  }
+  appleRuntime = binding;
+}
+
+/** The active apple-container selection's toolchain, for provider binding. */
+export function appleContainerRuntimeBinding(): AppleRuntimeBinding | null {
+  return pinnedRuntimeProvider === "apple-container" ? appleRuntime : null;
+}
+
+let appleSelectionGuard:
+  | ((endpoint: string) => boolean | Promise<boolean>)
+  | null = null;
+
+/** Register the durable task/environment preflight for apple-container
+ * selection. Docker rows never wrote a stateful claim (they won `auto` by
+ * default before ADR-106), so this guard is how an existing Docker host
+ * keeps its rows: rows pinned elsewhere make `auto` fall through to Docker
+ * instead of activating the bundled runtime over foreign state. */
+export function setAppleContainerSelectionGuard(
+  guard: ((endpoint: string) => boolean | Promise<boolean>) | null,
+): void {
+  appleSelectionGuard = guard;
+}
+
+/** A copy suitable for capability advertisements and command guards. */
+export function containerRuntimeState(): ContainerRuntimeState {
+  if (state.status === "checking" && activationPhase !== null) {
+    return { ...state, detail: activationPhase };
+  }
+  return { ...state };
+}
+
+let activationPhase: string | null = null;
+
+/** Publish the current activation phase for status surfaces and the log. A
+ * silent multi-minute boot (image build, volume seed, CLI reconcile) is
+ * indistinguishable from a wedge without this. */
+export function publishActivationPhase(phase: string | null): void {
+  activationPhase = phase;
+  if (phase !== null) console.log(`[host-agent] activation: ${phase}`);
+}
+
+/** Exact machine identity persisted by TaskEnvironment records. An injected
+ * test probe that never resolved a local endpoint intentionally has no durable
+ * identity; production selection always pins one before reporting ready. */
+/** The pinned backend, independent of the public readiness state. Boot-time
+ * maintenance (standard image, volume seeding, writable-container quarantine)
+ * runs while the public state is deliberately `checking`; gating its engine
+ * selection on readiness deadlocks a Docker-free Mac (found live 2026-08-15:
+ * activation could never complete because its own maintenance fell back to a
+ * docker binary that does not exist). */
+export function pinnedContainerRuntimeProvider():
+  | "docker"
+  | "apple-container"
+  | null {
+  return pinnedRuntimeProvider;
+}
+
+/** Pin-based identity, independent of readiness/operational state. Teardown
+ * and reconstruction must work while the runtime is still `checking`:
+ * removing load is how a degraded host heals, and the live 2026-08-16 ring —
+ * task holds the shared volume → maintenance cannot attach → never
+ * operational → teardown refused → task never dies — was closed by exactly
+ * this. The locator comparison downstream still requires an exact match. */
+export function pinnedContainerRuntimeMachineIdentity(): {
+  backend: "docker" | "apple-container";
+  endpoint: string;
+  engineId: string;
+} | null {
+  if (
+    pinnedRuntimeProvider === null ||
+    pinnedDockerHost === null ||
+    pinnedDockerEngineId === null
+  ) {
+    return null;
+  }
+  return {
+    backend: pinnedRuntimeProvider,
+    endpoint: pinnedDockerHost,
+    engineId: pinnedDockerEngineId,
+  };
+}
+
+/** Failure message for TEARDOWN admission: only a truly absent/unpinned
+ * runtime refuses teardown. `checking` with a pin admits it. */
+export function containerRuntimeTeardownProblem(): string | null {
+  if (state.status === "no-runtime") return state.message;
+  if (pinnedContainerRuntimeMachineIdentity() === null) {
+    return (
+      "The container runtime has not selected a backend yet. " +
+      "Retry after runtime detection completes."
+    );
+  }
+  return null;
+}
+
+export function containerRuntimeMachineIdentity(): {
+  backend: "docker" | "apple-container";
+  endpoint: string;
+  engineId: string;
+} | null {
+  if (
+    state.status !== "ready" ||
+    pinnedRuntimeProvider === null ||
+    pinnedDockerHost === null ||
+    pinnedDockerEngineId === null ||
+    state.provider !== pinnedRuntimeProvider
+  ) {
+    return null;
+  }
+  return {
+    backend: pinnedRuntimeProvider,
+    endpoint: pinnedDockerHost,
+    engineId: pinnedDockerEngineId,
+  };
+}
+
+/** ADR-106: provider-specific asset roots belonged to the retired bundled-VM
+ * fallback; ambient Docker and apple-container both use the package context. */
+export function containerRuntimeStandardAssetsRoot(): string | null {
+  return null;
+}
+
+export function containerRuntimeStandardImageRoot(): string | null {
+  return null;
+}
+
+export function containerRuntimeBindRoot(): string | null {
+  return null;
+}
+
+/** Public/control-plane view: detected is not usable until maintenance and
+ * persisted-task recovery have crossed their readiness fence. */
+export function containerRuntimeCapabilityState(): ContainerRuntimeState {
+  if (state.status === "ready" && !operational) {
+    return { status: "checking", preference: state.preference };
+  }
+  return containerRuntimeState();
+}
+
+/** Complete one readiness transition after image maintenance + recovery. */
+export function markContainerRuntimeOperational(
+  expectedEpoch = readinessEpoch,
+): boolean {
+  if (state.status !== "ready" || expectedEpoch !== readinessEpoch) return false;
+  operational = true;
+  activationRequired = false;
+  settleOperationalWaiters();
+  return true;
+}
+
+/** Fail closed while a known-ready daemon is being revalidated. Explicit
+ * operator recovery can also invalidate the generation so ready-to-ready
+ * probes still run maintenance and persisted-task recovery. */
+export function suspendContainerRuntime(
+  invalidateGeneration = false,
+): number | null {
+  if (state.status !== "ready") return null;
+  if (!operational && !invalidateGeneration) return null;
+  operational = false;
+  if (invalidateGeneration) {
+    readinessEpoch += 1;
+    activationRequired = true;
+    settleOperationalWaiters();
+  }
+  return readinessEpoch;
+}
+
+/** Token for work that must not survive a daemon readiness transition. */
+export function containerRuntimeReadinessEpoch(): number {
+  return readinessEpoch;
+}
+
+export function containerRuntimeEpochIsCurrent(epoch: number): boolean {
+  return epoch === readinessEpoch && state.status === "ready";
+}
+
+/** Command-scoped fence: the exact generation is still current AND the
+ * runtime is operational right now. Plain suspension (connection
+ * revalidation) keeps the epoch and ready status while operational drops —
+ * a pass fenced only on the epoch would keep mutating against an
+ * unverified daemon. */
+export function containerRuntimeGenerationOperational(epoch: number): boolean {
+  return epoch === readinessEpoch && state.status === "ready" && operational;
+}
+
+/** Whether a ready verdict must cross maintenance/recovery before use. */
+export function containerRuntimeActivationRequired(): boolean {
+  return state.status === "ready" && activationRequired;
+}
+
+/**
+ * Wait for image maintenance and persisted-task recovery to release one exact
+ * runtime generation. A later daemon/provider generation resolves false; it
+ * can never accidentally release a task admitted for the older backend.
+ */
+export function waitForContainerRuntimeOperational(
+  expectedEpoch = readinessEpoch,
+  timeoutMs = 15 * 60_000,
+): Promise<boolean> {
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+    return Promise.reject(new Error("runtime operational timeout is invalid"));
+  }
+  if (expectedEpoch !== readinessEpoch || state.status !== "ready") {
+    return Promise.resolve(false);
+  }
+  if (operational) return Promise.resolve(true);
+  if (timeoutMs === 0) return Promise.resolve(false);
+
+  return new Promise<boolean>((resolve) => {
+    const waiter: OperationalWaiter = {
+      epoch: expectedEpoch,
+      finish: resolve,
+      timer: setTimeout(() => {
+        if (!operationalWaiters.delete(waiter)) return;
+        resolve(false);
+      }, timeoutMs),
+    };
+    operationalWaiters.add(waiter);
+  });
+}
+
+/**
+ * Claim apple-container as stateful before task-up performs its first
+ * container mutation. Docker needs no marker because it wins `auto` by
+ * default. A stale generation after the fsync is conservative (future `auto`
+ * stays on the bundled runtime), never unsafe.
+ */
+/**
+ * Claim apple-container as stateful before ACTIVATION's first mutation
+ * (shared-volume create, image build) — which happens before any task
+ * exists. Uninstall reads an absent marker as "nothing to tear down", so a
+ * zero-task install→activate→uninstall previously skipped Apple cleanup
+ * entirely (review 2026-08-18 round 4). No readiness gate: activation
+ * maintenance runs while the public state is still `checking` by design.
+ */
+export async function claimContainerRuntimeForMaintenance(
+  store: RuntimeProviderStateStore = defaultRuntimeProviderStateStore(),
+): Promise<void> {
+  // The full claim commits a rollback guard under the managed operation
+  // lock — once per host lifetime is its job. Every later activation pass
+  // takes the cheap read-skip.
+  if ((await store.read())?.statefulProvider === "apple-container") return;
+  await store.claim("apple-container");
+}
+
+export async function claimContainerRuntimeForTask(
+  expectedEpoch = readinessEpoch,
+  store: RuntimeProviderStateStore = defaultRuntimeProviderStateStore(),
+): Promise<boolean> {
+  if (
+    expectedEpoch !== readinessEpoch ||
+    state.status !== "ready" ||
+    !operational
+  ) {
+    return false;
+  }
+  if (state.provider === "docker") return true;
+  await store.claim("apple-container");
+  return (
+    expectedEpoch === readinessEpoch &&
+    state.status === "ready" &&
+    state.provider === "apple-container" &&
+    operational
+  );
+}
+
+/** Explicit operator recovery: invalidate even a stale ready verdict before
+ * probing so a healthy ready-to-ready result still requires a full activation
+ * and persisted-task recovery pass. */
+export async function forceContainerRuntimeRecheck(
+  deps: RuntimeDetectionDeps = {},
+): Promise<{ state: ContainerRuntimeState; epoch: number | null }> {
+  // Gate new work synchronously, but do not invalidate the generation until
+  // an older ordinary probe has settled. Invalidating first would let that
+  // probe's ready-to-ready publication start maintenance for an intermediate
+  // epoch while this forced refresh was still waiting for the shared detector.
+  if (state.status === "ready") suspendContainerRuntime();
+  // A forced request must not get absorbed by an older ordinary probe. Wait
+  // for it, invalidate its final verdict exactly once, then run the refresh.
+  if (detectionInFlight) await detectionInFlight;
+  const forcedEpoch =
+    state.status === "ready" ? suspendContainerRuntime(true) : null;
+  // Re-probe the process pin. Never clear DOCKER_HOST or consult a newly
+  // selected ambient context here: even a short async gap would let unrelated
+  // Docker work escape to another daemon. Switching endpoints requires a
+  // service restart and is explained by the degraded-state message.
+  const next = await initializeContainerRuntime(deps);
+  return {
+    state: next,
+    epoch:
+      next.status === "ready"
+        ? (forcedEpoch ?? containerRuntimeReadinessEpoch())
+        : null,
+  };
+}
+
+/** Subscribe to successful rechecks; used to refresh the capability frame. */
+export function onContainerRuntimeChange(
+  listener: RuntimeChangeListener,
+): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/**
+ * Quarantine a selected backend after durable environment reconstruction
+ * proves it is not the machine those tasks belong to. The process pin is
+ * retained so no later recheck can escape to a different daemon; only a host
+ * restart after explicit operator repair can change it.
+ */
+export function rejectContainerRuntimeSelection(
+  message: string,
+  action = RUNTIME_RESTART_COMMAND,
+): void {
+  const safeMessage = message.trim();
+  const safeAction = action.trim();
+  publishContainerRuntimeState(
+    {
+      status: "no-runtime",
+      preference: state.preference,
+      message:
+        safeMessage.length > 0 && safeMessage.length <= 1_000
+          ? safeMessage
+          : "The selected container runtime does not match persisted task state.",
+      action:
+        safeAction.length > 0 && safeAction.length <= 200
+          ? safeAction
+          : RUNTIME_RESTART_COMMAND,
+    },
+    true,
+  );
+}
+
+/**
+ * Detect and apply the process-wide runtime selection.
+ *
+ * Never throws: a missing CLI, stopped daemon, or probe timeout is a normal
+ * degraded-host state, not a reason to crash-loop the service.
+ */
+export function initializeContainerRuntime(
+  deps: RuntimeDetectionDeps = {},
+): Promise<ContainerRuntimeState> {
+  // The bounded background retry and an operator-triggered recheck can land
+  // together. Join them so a slower stale failure cannot overwrite a newer
+  // ready verdict (and so only one `docker info` process runs at a time).
+  if (detectionInFlight) return detectionInFlight;
+  const running = detectContainerRuntime(deps)
+    .then(publishContainerRuntimeState)
+    .finally(() => {
+      if (detectionInFlight === running) detectionInFlight = null;
+    });
+  detectionInFlight = running;
+  return running;
+}
+
+/**
+ * Task-admission entrypoint: repeat ordinary detection so a task that raced
+ * host boot still gets a runtime. Runtime activation is intentionally owned
+ * by the existing state-change listener; callers can wait on its exact epoch
+ * with waitForContainerRuntimeOperational.
+ */
+export async function ensureContainerRuntimeForTask(
+  deps: RuntimeDetectionDeps = {},
+): Promise<ContainerRuntimeState> {
+  // ADR-106: apple-container activation (service start, kernel install,
+  // identity mint) happens inside ordinary detection, so a task needs no
+  // separate lazy-provisioning path.
+  return initializeContainerRuntime(deps);
+}
+
+export function startContainerRuntimeAutoRecheck(
+  options: RuntimeAutoRecheckOptions = {},
+): () => void {
+  if (
+    state.status !== "no-runtime" ||
+    state.action === RUNTIME_RESTART_COMMAND ||
+    (options.maxAttempts ?? 45) <= 0
+  ) {
+    return () => {};
+  }
+
+  const firstDelayMs = options.firstDelayMs ?? 5_000;
+  const intervalMs = options.intervalMs ?? 20_000;
+  const maxAttempts = options.maxAttempts ?? 45;
+  let attempts = 0;
+  let stopped = false;
+  let timer: NodeJS.Timeout | null = null;
+
+  const schedule = (delayMs: number): void => {
+    timer = setTimeout(() => {
+      timer = null;
+      if (stopped || state.status === "ready") return;
+      attempts += 1;
+      void initializeContainerRuntime(options).then((next) => {
+        if (stopped || next.status === "ready" || attempts >= maxAttempts) {
+          return;
+        }
+        schedule(intervalMs);
+      });
+    }, delayMs);
+    timer.unref?.();
+  };
+
+  schedule(firstDelayMs);
+  return () => {
+    stopped = true;
+    if (timer) clearTimeout(timer);
+    timer = null;
+  };
+}
+
+/** Pure detection seam kept injectable for deterministic startup tests. */
+interface AppleSystemProbe {
+  readonly endpoint: string;
+  readonly installationId: string;
+}
+
+const APPLE_INSTALLATION_ID_FILE = "uai-installation-id";
+const APPLE_INSTALLATION_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{7,63}$/;
+
+function defaultAppleCli(
+  binding: AppleRuntimeBinding,
+): NonNullable<RuntimeDetectionDeps["appleCli"]> {
+  return (args, options) =>
+    new Promise((resolve) => {
+      const child = spawn(binding.containerCliPath, [...args], {
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      const stdout: Buffer[] = [];
+      const stderr: Buffer[] = [];
+      let bytes = 0;
+      // A SIGKILLed CLI normally closes at once, but an unreapable child
+      // must never strand boot/recheck/activation on a promise that only
+      // settles on close.
+      const killAndSettle = (): void => {
+        child.kill("SIGKILL");
+        const settle = setTimeout(() => finish(null), 5_000);
+        settle.unref?.();
+      };
+      const collect = (target: Buffer[]) => (chunk: Buffer) => {
+        bytes += chunk.length;
+        if (bytes > options.maxOutputBytes) killAndSettle();
+        else target.push(chunk);
+      };
+      child.stdout.on("data", collect(stdout));
+      child.stderr.on("data", collect(stderr));
+      const timer = setTimeout(killAndSettle, options.timeoutMs);
+      timer.unref?.();
+      let settled = false;
+      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"),
+        });
+      };
+      child.once("error", () => finish(null));
+      child.once("close", (code) => finish(code));
+    });
+}
+
+function defaultAppleInstallationId(): NonNullable<
+  RuntimeDetectionDeps["appleInstallationId"]
+> {
+  return {
+    async read(endpoint) {
+      try {
+        const raw = (
+          await fsReadFile(path.join(endpoint, APPLE_INSTALLATION_ID_FILE), "utf8")
+        ).trim();
+        return APPLE_INSTALLATION_ID.test(raw) ? raw : null;
+      } catch {
+        return null;
+      }
+    },
+    async mint(endpoint) {
+      const id = randomUUID();
+      await fsWriteFile(
+        path.join(endpoint, APPLE_INSTALLATION_ID_FILE),
+        `${id}\n`,
+        { mode: 0o600, flag: "wx" },
+      );
+      return id;
+    },
+  };
+}
+
+function parseAppleSystemStatus(
+  stdout: string,
+): { running: boolean; appRoot: string } | null {
+  let running = false;
+  let appRoot: string | null = null;
+  for (const line of stdout.split("\n")) {
+    if (/^status\s+/.test(line)) {
+      running = line.replace(/^status\s+/, "").trim() === "running";
+    } else if (/^appRoot\s+/.test(line)) {
+      appRoot = line.replace(/^appRoot\s+/, "").trim().replace(/\/$/, "");
+    }
+  }
+  if (appRoot === null || !appRoot.startsWith("/")) return null;
+  return { running, appRoot };
+}
+
+function selectedAppleRuntime(
+  deps: RuntimeDetectionDeps,
+): AppleRuntimeBinding | null {
+  return deps.appleRuntime === undefined ? appleRuntime : deps.appleRuntime;
+}
+
+function appleRuntimeEligible(deps: RuntimeDetectionDeps): boolean {
+  if ((deps.platform ?? process.platform) !== "darwin") return false;
+  // Darwin kernel 25 shipped with macOS 26 — the toolchain's floor. The
+  // artifact itself is arm64-only, so architecture is settled upstream.
+  const release = deps.darwinRelease ?? osRelease();
+  return Number.parseInt(release.split(".")[0] ?? "0", 10) >= 25;
+}
+
+/** Prove the per-user toolchain state and its minted installation identity
+ * WITHOUT starting anything — the pinned-runtime recheck path. */
+async function probeAppleSystem(
+  deps: RuntimeDetectionDeps,
+): Promise<AppleSystemProbe | null> {
+  const binding = selectedAppleRuntime(deps);
+  if (binding === null || !appleRuntimeEligible(deps)) return null;
+  const cli = deps.appleCli ?? defaultAppleCli(binding);
+  const status = await cli(["system", "status"], {
+    timeoutMs: 15_000,
+    maxOutputBytes: 64 * 1024,
+  });
+  if (status.status !== 0) return null;
+  const parsed = parseAppleSystemStatus(status.stdout);
+  if (parsed === null || !parsed.running) return null;
+  const ids = deps.appleInstallationId ?? defaultAppleInstallationId();
+  const installationId = await ids.read(parsed.appRoot);
+  if (installationId === null) return null;
+  return { endpoint: parsed.appRoot, installationId };
+}
+
+/**
+ * Activate and select the bundled Apple container runtime: start the user
+ * services when they are down, install the pinned guest kernel and mint the
+ * durable installation identity on first activation, then pin the process to
+ * (apple-container, state root, installation id). Returns null when the
+ * backend is ineligible or activation fails — `auto` falls through to Docker.
+ */
+async function probeAndSelectApple(
+  preference: "auto" | "apple-container",
+  deps: RuntimeDetectionDeps,
+): Promise<ContainerRuntimeState | null> {
+  const binding = selectedAppleRuntime(deps);
+  if (binding === null || !appleRuntimeEligible(deps)) return null;
+  const cli = deps.appleCli ?? defaultAppleCli(binding);
+  const ids = deps.appleInstallationId ?? defaultAppleInstallationId();
+
+  let status = await cli(["system", "status"], {
+    timeoutMs: 15_000,
+    maxOutputBytes: 64 * 1024,
+  });
+  let parsed = status.status === 0 ? parseAppleSystemStatus(status.stdout) : null;
+  if (parsed === null || !parsed.running) {
+    const started = await cli(["system", "start"], {
+      timeoutMs: 120_000,
+      maxOutputBytes: 256 * 1024,
+    });
+    if (started.status !== 0) return null;
+    status = await cli(["system", "status"], {
+      timeoutMs: 15_000,
+      maxOutputBytes: 64 * 1024,
+    });
+    parsed = status.status === 0 ? parseAppleSystemStatus(status.stdout) : null;
+    if (parsed === null || !parsed.running) return null;
+  }
+
+  // Durable rows pinned to another backend keep their machine: fall through
+  // (auto reaches Docker) rather than activating over foreign state. The
+  // exact engine-identity fence still runs before maintenance either way.
+  const guard =
+    deps.appleSelectionGuard === undefined
+      ? appleSelectionGuard
+      : deps.appleSelectionGuard;
+  if (guard) {
+    try {
+      if ((await guard(parsed.appRoot)) !== true) return null;
+    } catch {
+      return null;
+    }
+  }
+
+  let installationId = await ids.read(parsed.appRoot);
+  if (installationId === null) {
+    // First activation of this state root: the guest kernel must be in place
+    // before any container can boot, and the identity is minted only after
+    // the kernel install succeeded so a crash re-runs both.
+    const kernel = await cli(
+      ["system", "kernel", "set", "--binary", binding.kernelPath],
+      { timeoutMs: 60_000, maxOutputBytes: 256 * 1024 },
+    );
+    if (kernel.status !== 0) return null;
+    try {
+      installationId = await ids.mint(parsed.appRoot);
+    } catch {
+      installationId = await ids.read(parsed.appRoot);
+      if (installationId === null) return null;
+    }
+  }
+
+  if (
+    !pinRuntime(
+      "apple-container",
+      parsed.appRoot,
+      installationId,
+      binding.containerCliPath,
+    )
+  ) {
+    return detectPinnedRuntime(preference, deps);
+  }
+  return { status: "ready", preference, provider: "apple-container" };
+}
+
+export async function detectContainerRuntime(
+  deps: RuntimeDetectionDeps = {},
+): Promise<ContainerRuntimeState> {
+  const configured = process.env.UAI_RUNTIME;
+  if (
+    deps.preference === undefined &&
+    configured !== undefined &&
+    configured !== "auto" &&
+    configured !== "docker" &&
+    configured !== "apple-container"
+  ) {
+    return {
+      status: "no-runtime",
+      preference: "auto",
+      message:
+        "UAI_RUNTIME has an invalid value. " +
+        "Use `auto`, `docker`, or `apple-container`, then restart Uai Host.",
+      action: RUNTIME_RESTART_COMMAND,
+    };
+  }
+  const preference =
+    deps.preference ?? runtimePreference(process.env.UAI_RUNTIME);
+
+  // The selected provider/endpoint is immutable for this process. Rechecks
+  // may restart the same toolchain services or prove the same ambient
+  // daemon, but cannot cross the boundary while task/credential work may
+  // still be in flight.
+  if (pinnedDockerHost && pinnedRuntimeProvider) {
+    return detectPinnedRuntime(preference, deps);
+  }
+
+  const store =
+    deps.providerStateStore ?? defaultRuntimeProviderStateStore();
+
+  if (preference === "apple-container") {
+    return (
+      (await probeAndSelectApple(preference, deps)) ??
+      appleUnavailable(preference, selectedAppleRuntime(deps) === null, deps)
+    );
+  }
+
+  if (preference === "auto") {
+    let stickyApple = false;
+    try {
+      stickyApple =
+        (await store.read())?.statefulProvider === "apple-container";
+    } catch {
+      return {
+        status: "no-runtime",
+        preference,
+        message:
+          "Uai Host could not validate its durable container-runtime selection. " +
+          "Repair the local runtime state, then restart Uai Host.",
+        action: RUNTIME_RESTART_COMMAND,
+      };
+    }
+    if (stickyApple) {
+      // The bundled runtime owns durable task state: never silently move
+      // that state to an ambient daemon, even when activation fails.
+      return (
+        (await probeAndSelectApple(preference, deps)) ??
+        appleUnavailable(preference, selectedAppleRuntime(deps) === null, deps)
+      );
+    }
+    // ADR-106: prefer the bundled runtime wherever it can run — ambient
+    // Docker existing is not a reason to skip it. A failed activation falls
+    // through to Docker rather than degrading a machine that has one.
+    const selected = await probeAndSelectApple(preference, deps);
+    if (selected !== null) return selected;
+  }
+
+  return detectAmbientDocker(preference, deps);
+}
+
+function appleUnavailable(
+  preference: RuntimePreference,
+  unbundled: boolean,
+  deps: RuntimeDetectionDeps,
+): ContainerRuntimeState {
+  const eligible = appleRuntimeEligible(deps);
+  return {
+    status: "no-runtime",
+    preference,
+    message: unbundled
+      ? "The bundled Apple container runtime is not part of this installation. " +
+        "Install the standalone runtime on Apple Silicon with macOS 26 or newer, " +
+        `or set UAI_RUNTIME=docker and run \`${RUNTIME_RESTART_COMMAND}\`.`
+      : eligible
+        ? APPLE_RUNTIME_UNAVAILABLE_MESSAGE
+        : "The bundled Apple container runtime needs Apple Silicon and " +
+          "macOS 26 or newer. Use Docker on this machine: set " +
+          `UAI_RUNTIME=docker and run \`${RUNTIME_RESTART_COMMAND}\`.`,
+    action: RUNTIME_RECHECK_COMMAND,
+  };
+}
+
+async function detectAmbientDocker(
+  preference: "auto" | "docker",
+  deps: RuntimeDetectionDeps,
+): Promise<ContainerRuntimeState> {
+  // A successful ambient `docker info` is not a durable selection: collapse a
+  // named context to its exact local endpoint before publishing DOCKER_HOST.
+  const selection =
+    deps.dockerSelection !== undefined
+      ? await deps.dockerSelection()
+      : deps.dockerInfo === undefined
+        ? await resolveDockerSelection()
+        : null;
+  if (selection && !isLocalDockerEndpoint(selection.host)) {
+    return {
+      status: "no-runtime",
+      preference,
+      message:
+        "The selected Docker endpoint is remote. " +
+        "Uai Host requires a local Unix-socket daemon for workspace mounts and loopback tunnels. " +
+        `Select a local Docker context, then run \`${RUNTIME_RESTART_COMMAND}\`.`,
+      action: RUNTIME_RESTART_COMMAND,
+    };
+  }
+
+  if (deps.dockerInfo === undefined && selection === null) {
+    return {
+      status: "no-runtime",
+      preference,
+      message:
+        "Uai Host could not resolve the selected Docker context to a local endpoint. " +
+        `Select a local Docker context and run \`${RUNTIME_RECHECK_COMMAND}\`.`,
+      action: RUNTIME_RECHECK_COMMAND,
+    };
+  }
+
+  const proof = await probeDocker(selection, deps);
+  if (proof !== null) {
+    if (selection) {
+      if (!pinRuntime("docker", selection.host, proof.engineId)) {
+        return pinnedRuntimeUnavailable(preference);
+      }
+    }
+    return { status: "ready", preference, provider: "docker" };
+  }
+  return {
+    status: "no-runtime",
+    preference,
+    message:
+      preference === "docker"
+        ? "No working Docker runtime was found. Install or start Docker, then run " +
+          `\`${RUNTIME_RECHECK_COMMAND}\`.`
+        : NO_RUNTIME_MESSAGE,
+    action: RUNTIME_RECHECK_COMMAND,
+  };
+}
+
+async function detectPinnedRuntime(
+  preference: RuntimePreference,
+  deps: RuntimeDetectionDeps,
+): Promise<ContainerRuntimeState> {
+  const provider = pinnedRuntimeProvider!;
+  const host = pinnedDockerHost!;
+  if (
+    (preference === "docker" && provider !== "docker") ||
+    (preference === "apple-container" && provider !== "apple-container")
+  ) {
+    return pinnedRuntimeUnavailable(preference);
+  }
+
+  if (provider === "apple-container") {
+    // Re-prove the same per-user state root and the same minted installation
+    // id; a wiped or replaced toolchain state must fail closed exactly like a
+    // replaced Docker daemon at the same socket.
+    const probe = await probeAppleSystem(deps);
+    if (
+      probe === null ||
+      probe.endpoint !== host ||
+      pinnedDockerEngineId === null ||
+      probe.installationId !== pinnedDockerEngineId
+    ) {
+      return pinnedRuntimeUnavailable(preference);
+    }
+    applyPinnedAppleRuntimeEnvironment(pinnedAppleCliPath);
+    return {
+      status: "ready",
+      preference: preference === "auto" ? "auto" : "apple-container",
+      provider,
+    };
+  }
+
+  applyPinnedDockerHost(host);
+  const proof = await probeDocker({ host }, deps);
+  if (
+    proof === null ||
+    pinnedDockerEngineId === null ||
+    proof.engineId !== pinnedDockerEngineId
+  ) {
+    return pinnedRuntimeUnavailable(preference);
+  }
+  return {
+    status: "ready",
+    preference: preference === "auto" ? "auto" : "docker",
+    provider: "docker",
+  };
+}
+
+/** Read-only TOCTOU fence for work that inspected daemon-owned resources.
+ * Unlike a normal recheck this does not publish state or run a controller
+ * transition; its caller must quarantine the selection when null is returned. */
+export async function reprobeContainerRuntimeMachineIdentity(
+  deps: Pick<
+    RuntimeDetectionDeps,
+    | "dockerInfo"
+    | "appleRuntime"
+    | "appleCli"
+    | "appleInstallationId"
+    | "darwinRelease"
+  > = {},
+): Promise<ReturnType<typeof containerRuntimeMachineIdentity>> {
+  if (
+    state.status !== "ready" ||
+    pinnedRuntimeProvider === null ||
+    pinnedDockerHost === null ||
+    pinnedDockerEngineId === null
+  ) {
+    return null;
+  }
+  if (pinnedRuntimeProvider === "apple-container") {
+    // The pinned endpoint is the per-user state root, not a Docker socket:
+    // publishing it as DOCKER_HOST (and clearing the script selection
+    // variables) would both fail this fence and corrupt the process
+    // environment for every agent script. Re-prove the same state root and
+    // minted installation id through the Apple probe instead.
+    const probe = await probeAppleSystem(deps);
+    if (
+      probe === null ||
+      probe.endpoint !== pinnedDockerHost ||
+      probe.installationId !== pinnedDockerEngineId
+    ) {
+      return null;
+    }
+    applyPinnedAppleRuntimeEnvironment(pinnedAppleCliPath);
+    return {
+      backend: pinnedRuntimeProvider,
+      endpoint: pinnedDockerHost,
+      engineId: pinnedDockerEngineId,
+    };
+  }
+  applyPinnedDockerHost(pinnedDockerHost);
+  const proof = await probeDocker({ host: pinnedDockerHost }, deps);
+  if (proof?.engineId !== pinnedDockerEngineId) return null;
+  return {
+    backend: pinnedRuntimeProvider,
+    endpoint: pinnedDockerHost,
+    engineId: pinnedDockerEngineId,
+  };
+}
+
+async function probeDocker(
+  selection: DockerSelection | null,
+  deps: RuntimeDetectionDeps,
+): Promise<DockerDaemonProof | null> {
+  const dockerInfo =
+    deps.dockerInfo ??
+    ((selected?: DockerSelection) =>
+      dockerCli(
+        [
+          "--host",
+          selected!.host,
+          "info",
+          "--format",
+          "{{.ID}}\t{{.ServerVersion}}",
+        ],
+        { timeoutMs: 10_000, maxOutputBytes: 4_096 },
+      ));
+  try {
+    return parseDockerDaemonProof(await dockerInfo(selection ?? undefined));
+  } catch {
+    return null;
+  }
+}
+
+/** Strict parser for the one atomic identity/liveness probe. Trimming is
+ * deliberately forbidden: a second record, CRLF ambiguity, or whitespace in
+ * either identity component is not a daemon proof. */
+export function parseDockerDaemonProof(
+  result: DockerResult | null,
+): DockerDaemonProof | null {
+  if (
+    result?.status !== 0 ||
+    result.outputTruncated === true ||
+    Buffer.byteLength(result.stdout) > 4_096
+  ) {
+    return null;
+  }
+  const match = /^([A-Za-z0-9][A-Za-z0-9:._-]{0,511})\t([!-~]{1,128})\n$/.exec(
+    result.stdout,
+  );
+  if (!match) return null;
+  return { engineId: match[1]!, serverVersion: match[2]! };
+}
+
+async function resolveDockerSelection(): Promise<DockerSelection | null> {
+  const configuredContext = process.env.DOCKER_CONTEXT?.trim();
+  const configuredHost = process.env.DOCKER_HOST?.trim();
+  // Docker gives an explicit context precedence over DOCKER_HOST, so resolve
+  // that same selection before collapsing it to the immutable local endpoint.
+  if (!configuredContext && configuredHost) return { host: configuredHost };
+
+  let context = configuredContext;
+  if (!context) {
+    const shown = await dockerCli(["context", "show"], { timeoutMs: 10_000 });
+    if (shown.status !== 0) return null;
+    context = shown.stdout.trim();
+  }
+  if (!context) return null;
+  const inspected = await dockerCli(
+    [
+      "context",
+      "inspect",
+      context,
+      "--format",
+      "{{.Endpoints.docker.Host}}",
+    ],
+    { timeoutMs: 10_000 },
+  );
+  const host = inspected.stdout.trim();
+  return inspected.status === 0 && host ? { host } : null;
+}
+
+function applyPinnedDockerHost(host: string): DockerSelection {
+  process.env.DOCKER_HOST = host;
+  // DOCKER_CONTEXT takes precedence over DOCKER_HOST. Clear it after resolving
+  // the named context so `docker context use` cannot retarget later children.
+  delete process.env.DOCKER_CONTEXT;
+  // A Docker selection must never leave a stale Apple pin visible to the
+  // agent scripts, which consume the backend through these variables.
+  delete process.env.UAI_TASK_RUNTIME;
+  delete process.env.UAI_CONTAINER_CLI;
+  return { host };
+}
+
+/** Publish the Apple selection to the agent scripts (task-up/down/status
+ * branch on UAI_TASK_RUNTIME and exec the bundled CLI at UAI_CONTAINER_CLI).
+ * The scripts fail closed on a missing/unexecutable CLI path, so an absent
+ * binding deletes the variable rather than inventing a fallback. */
+function applyPinnedAppleRuntimeEnvironment(cliPath: string | null): void {
+  process.env.UAI_TASK_RUNTIME = "apple-container";
+  if (cliPath !== null && cliPath.length > 0) {
+    process.env.UAI_CONTAINER_CLI = cliPath;
+  } else {
+    delete process.env.UAI_CONTAINER_CLI;
+  }
+}
+
+let pinnedAppleCliPath: string | null = null;
+
+function pinRuntime(
+  provider: "docker" | "apple-container",
+  host: string,
+  engineId: string,
+  appleCliPath?: string,
+): boolean {
+  if (
+    (pinnedDockerHost !== null && pinnedDockerHost !== host) ||
+    (pinnedRuntimeProvider !== null && pinnedRuntimeProvider !== provider) ||
+    (pinnedDockerEngineId !== null && pinnedDockerEngineId !== engineId)
+  ) {
+    if (pinnedDockerHost && pinnedRuntimeProvider === "docker") {
+      applyPinnedDockerHost(pinnedDockerHost);
+    } else if (pinnedDockerHost && pinnedRuntimeProvider === "apple-container") {
+      applyPinnedAppleRuntimeEnvironment(pinnedAppleCliPath);
+    }
+    return false;
+  }
+  pinnedDockerHost = host;
+  pinnedRuntimeProvider = provider;
+  pinnedDockerEngineId = engineId;
+  // apple-container has no Docker socket: the endpoint pin is the per-user
+  // state root; DOCKER_HOST is deliberately left untouched while the script
+  // selection variables are published instead.
+  if (provider === "docker") {
+    applyPinnedDockerHost(host);
+  } else {
+    pinnedAppleCliPath = appleCliPath ?? pinnedAppleCliPath;
+    applyPinnedAppleRuntimeEnvironment(pinnedAppleCliPath);
+  }
+  return true;
+}
+
+function isLocalDockerEndpoint(host: string): boolean {
+  if (
+    host.length > 4_096 ||
+    !host.startsWith("unix:///") ||
+    /[\0\r\n]/.test(host) ||
+    host.includes("?") ||
+    host.includes("#")
+  ) {
+    return false;
+  }
+  return host.slice("unix://".length).startsWith("/");
+}
+
+function pinnedRuntimeUnavailable(
+  preference: RuntimePreference,
+): ContainerRuntimeState {
+  return {
+    status: "no-runtime",
+    preference,
+    message:
+      pinnedRuntimeProvider === "apple-container"
+        ? "The Apple container runtime selected for this Uai Host process is " +
+          `not responding. Run \`${RUNTIME_RECHECK_COMMAND}\` to repair it. ` +
+          "To switch providers, set UAI_RUNTIME explicitly and run " +
+          `\`${RUNTIME_RESTART_COMMAND}\`.`
+        : PINNED_RUNTIME_UNAVAILABLE_MESSAGE,
+    action: RUNTIME_RECHECK_COMMAND,
+  };
+}
+
+
+function publishContainerRuntimeState(
+  next: ContainerRuntimeState,
+  forceInvalidateGeneration = false,
+): ContainerRuntimeState {
+  const previous = containerRuntimeState();
+  const previousProvider =
+    previous.status === "ready" ? previous.provider : null;
+  const nextProvider = next.status === "ready" ? next.provider : null;
+  if (
+    forceInvalidateGeneration ||
+    (previous.status === "ready") !== (next.status === "ready") ||
+    (previousProvider !== null &&
+      nextProvider !== null &&
+      previousProvider !== nextProvider)
+  ) {
+    readinessEpoch += 1;
+  }
+  if (
+    next.status === "ready" &&
+    (previous.status !== "ready" || previousProvider !== nextProvider)
+  ) {
+    activationRequired = true;
+  }
+  if (
+    next.status !== "ready" ||
+    previous.status !== "ready" ||
+    previousProvider !== nextProvider
+  ) {
+    operational = false;
+  }
+  state = next;
+  settleOperationalWaiters();
+  for (const listener of listeners) {
+    try {
+      listener(containerRuntimeState(), previous);
+    } catch (error) {
+      console.warn(
+        `[host-agent] container runtime listener failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+  return containerRuntimeState();
+}
+
+function settleOperationalWaiters(): void {
+  for (const waiter of operationalWaiters) {
+    if (waiter.epoch === readinessEpoch && state.status === "ready") {
+      if (!operational) continue;
+      operationalWaiters.delete(waiter);
+      clearTimeout(waiter.timer);
+      waiter.finish(true);
+      continue;
+    }
+    operationalWaiters.delete(waiter);
+    clearTimeout(waiter.timer);
+    waiter.finish(false);
+  }
+}
+
+/** @internal Test isolation for the process-lifetime selection invariant. */
+export function resetContainerRuntimeSelectionForTests(): void {
+  if (process.env.NODE_ENV !== "test") {
+    throw new Error("runtime selection reset is test-only");
+  }
+  pinnedDockerHost = null;
+  pinnedRuntimeProvider = null;
+  pinnedDockerEngineId = null;
+  appleRuntime = null;
+  operational = false;
+  activationRequired = false;
+  state = {
+    status: "checking",
+    preference: runtimePreference(process.env.UAI_RUNTIME),
+  };
+  for (const waiter of operationalWaiters) {
+    operationalWaiters.delete(waiter);
+    clearTimeout(waiter.timer);
+    waiter.finish(false);
+  }
+}
+
+/** Human-facing task failure, or null while the host can attempt Docker work. */
+export function containerRuntimeProblem(): string | null {
+  if (state.status === "no-runtime") return state.message;
+  if (state.status !== "ready" || !operational) {
+    return (
+      "The container runtime is still preparing this host. " +
+      "Retry after runtime recovery completes."
+    );
+  }
+  return null;
+}
+
+/** Expensive repair/recovery work belongs only to a genuine readiness edge. */
+export function containerRuntimeBecameReady(
+  next: ContainerRuntimeState,
+  previous: ContainerRuntimeState,
+): boolean {
+  return next.status === "ready" && previous.status !== "ready";
+}