@runuai/host 0.9.14 → 0.9.43

package/lib/standard-image.ts

@@ -18,16 +18,38 @@
 
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import {
+  MAINTENANCE_CONTAINER_LABEL,
+  recycleAppleRuntimeServices,
+} from "./apple-runtime-recycle";
 import { detectEngine } from "./engines";
+import {
+  appleContainerRuntimeBinding,
+  claimContainerRuntimeForMaintenance,
+  containerRuntimeStandardAssetsRoot,
+  containerRuntimeStandardImageRoot,
+  pinnedContainerRuntimeProvider,
+} from "./container-runtime";
+import { KeyedPromiseTail } from "./keyed-promise-tail";
 
 /** Pinned, host-wide constants (must match task-up.sh and the compose gen). */
 export const STANDARD_IMAGE_TAG = "uai-standard:dev";
 export const ASDF_DATA_VOLUME = "uai-asdf-data";
 
+/**
+ * The shared-volume agent CLIs belong to this exact HOME-default Node. A
+ * future default bump cannot transparently roll stopped containers: their
+ * baked /home/node/.tool-versions still names the old CLI-owning candidate.
+ * Changing this value therefore requires an explicit volume migration or
+ * container-recreation release slice, not an ordinary image refresh.
+ */
+export const STANDARD_DEFAULT_NODE_VERSION = "22.11.0";
+
 /**
  * Runtimes the standard image's asdf plugins can satisfy, with a sensible set
  * of advertised versions per kind (ADR-021 `runtimes`). These are the
@@ -43,7 +65,14 @@ export const STANDARD_RUNTIMES: ReadonlyArray<{
   kind: string;
   availableVersions: string[];
 }> = [
-  { kind: "node", availableVersions: ["22.11.0", "20.18.0", "18.20.4"] },
+  {
+    kind: "node",
+    availableVersions: [
+      STANDARD_DEFAULT_NODE_VERSION,
+      "20.18.0",
+      "18.20.4",
+    ],
+  },
   { kind: "python", availableVersions: ["3.12.4", "3.11.9"] },
   { kind: "go", availableVersions: ["1.23.2", "1.22.8"] },
   { kind: "ruby", availableVersions: ["3.3.5", "3.2.5"] },
@@ -91,6 +120,16 @@ export function configuredOptionalEngines(): {
   };
 }
 
+type OptionalEngineConfiguration = ReturnType<
+  typeof configuredOptionalEngines
+>;
+
+function optionalEngineConfigurationKey(
+  engines: OptionalEngineConfiguration,
+): string {
+  return JSON.stringify(engines);
+}
+
 async function hashBuildContext(extra = ""): Promise<string | null> {
   try {
     const root = standardImageDir();
@@ -123,23 +162,103 @@ async function hashBuildContext(extra = ""): Promise<string | null> {
 
 /** Absolute path to the standard image build context. */
 function standardImageDir(): string {
+  const providerRoot = containerRuntimeStandardImageRoot();
+  if (providerRoot !== null) return providerRoot;
   const here = dirname(fileURLToPath(import.meta.url));
   // lib/standard-image.ts -> host-agent/ -> images/standard
   return resolve(here, "..", "images", "standard");
 }
 
+/** Absolute packaged path used to bind the materializer over rolling images
+ * that predate the baked executable. Resolution is deterministic; callers get
+ * the ordinary Docker bind/open error if a package install is corrupt. */
+export function standardImageRuntimeMaterializerPath(): string {
+  return join(
+    standardContainerAssetsDir(),
+    "uai-materialize-runtimes",
+  );
+}
+
+/** Absolute packaged Corepack pin bound over both rolling and derived images. */
+export function standardImageCorepackVersionPath(): string {
+  return join(standardContainerAssetsDir(), "corepack-version");
+}
+
+/** ADR-106: the retired bundled-VM fallback exposed a provider-specific
+ * asset root; every current backend uses the package's ordinary
+ * build-context assets, so the runtime override below is always null. */
+function standardContainerAssetsDir(): string {
+  return (
+    containerRuntimeStandardAssetsRoot() ?? join(standardImageDir(), "container")
+  );
+}
+
 interface RunResult {
   code: number | null;
   stdout: string;
   stderr: string;
 }
 
-/** Run a command to completion, capturing stdio. Never rejects. */
-function run(command: string, args: string[]): Promise<RunResult> {
+const SHORT_DOCKER_TIMEOUT_MS = 30_000;
+const CLI_MAINTENANCE_TIMEOUT_MS = 10 * 60_000;
+const IMAGE_BUILD_TIMEOUT_MS = 15 * 60_000;
+const TERMINATE_GRACE_MS = 5_000;
+export const ASDF_MAINTENANCE_LOCK_PATH =
+  "/opt/asdf-data/.uai-maintenance.lock";
+const ASDF_MAINTENANCE_LOCK_WAIT_SECONDS = 300;
+const ASDF_MAINTENANCE_INTERNAL_TIMEOUT_SECONDS = 570;
+
+/** The selected container engine for image/volume maintenance (ADR-106).
+ * Resolved per call: the runtime pin settles before ensureStandardImage runs,
+ * but an HMR reload must not strand a stale CLI path. The docker fallback
+ * covers the pre-selection window, where docker-only behavior is historical. */
+function selectedEngine(): { command: string; apple: boolean } {
+  // The PIN, not the readiness-gated identity: this runs during activation
+  // while the public state is still `checking`, and falling back to docker
+  // there deadlocks a Docker-free Mac.
+  if (pinnedContainerRuntimeProvider() === "apple-container") {
+    const binding = appleContainerRuntimeBinding();
+    if (binding !== null) {
+      return { command: binding.containerCliPath, apple: true };
+    }
+  }
+  return { command: "docker", apple: false };
+}
+
+/** Run a command to completion, capturing stdio. Never rejects and never
+ * waits forever: standard-image maintenance is an activation prerequisite,
+ * so an unbounded Docker/npm child would strand the entire host in checking. */
+function run(
+  command: string,
+  args: string[],
+  timeoutMs = SHORT_DOCKER_TIMEOUT_MS,
+): Promise<RunResult> {
   return new Promise<RunResult>((resolveRun) => {
     let stdout = "";
     let stderr = "";
+    let settled = false;
+    let killTimer: NodeJS.Timeout | null = null;
     const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+    const settle = (code: number | null): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeoutTimer);
+      if (killTimer) clearTimeout(killTimer);
+      resolveRun({ code, stdout, stderr });
+    };
+    const timeoutTimer = setTimeout(() => {
+      stderr += `${stderr && !stderr.endsWith("\n") ? "\n" : ""}${command} timed out after ${timeoutMs}ms`;
+      child.kill("SIGTERM");
+      killTimer = setTimeout(() => {
+        child.kill("SIGKILL");
+        // SIGKILL should always produce close, but do not let a broken child
+        // handle defeat the host-wide readiness bound.
+        const settleTimer = setTimeout(() => settle(null), 1_000);
+        settleTimer.unref();
+      }, TERMINATE_GRACE_MS);
+      killTimer.unref();
+    }, timeoutMs);
+    timeoutTimer.unref();
     child.stdout?.setEncoding("utf8");
     child.stderr?.setEncoding("utf8");
     child.stdout?.on("data", (chunk: string) => {
@@ -149,14 +268,220 @@ function run(command: string, args: string[]): Promise<RunResult> {
       stderr += chunk;
     });
     child.on("error", (err: Error) => {
-      resolveRun({ code: null, stdout, stderr: stderr + err.message });
+      stderr += err.message;
+      settle(null);
     });
     child.on("close", (code) => {
-      resolveRun({ code, stdout, stderr });
+      settle(code);
     });
   });
 }
 
+/** Narrow process-level seam for the timeout regression test. */
+export const runStandardImageCommandForTest = run;
+
+let maintenanceContainerSeq = 0;
+
+/** How long a maintenance run may sit without its container reaching
+ * `running` before the wedge sensor passes judgment. Long HEALTHY operations
+ * (reconcile's npm installs, the seed copy) are past `running` within
+ * seconds, so this discriminates cleanly. Env-overridable for tests. */
+function wedgeProbeDelayMs(): number {
+  const raw = Number(process.env.UAI_APPLE_WEDGE_PROBE_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : 60_000;
+}
+
+/** Post-recycle grace for the hung CLI client before a synthesized result. */
+function wedgeGraceMs(): number {
+  const raw = Number(process.env.UAI_APPLE_WEDGE_GRACE_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : 10_000;
+}
+
+function delayMs(ms: number): Promise<void> {
+  return new Promise((resolveDelay) => {
+    const timer = setTimeout(resolveDelay, ms);
+    timer.unref();
+  });
+}
+
+/**
+ * One DEFINITIVE observation of the named container: a successful, parseable
+ * inspect reporting a non-running state. Anything else — inspect failure,
+ * unparseable output, missing state, or `running` — is NOT evidence of a
+ * wedge and must stand the sensor down (the old fall-through treated
+ * uncertainty as wedge evidence, which authorizes a service recycle on a
+ * guess).
+ */
+async function appleContainerDefinitivelyNotRunning(
+  engine: { command: string },
+  name: string,
+): Promise<boolean> {
+  const inspected = await run(engine.command, ["inspect", name], 15_000);
+  if (inspected.code !== 0) return false;
+  try {
+    const parsed = JSON.parse(inspected.stdout) as Array<{
+      id?: unknown;
+      status?: { state?: unknown };
+    }>;
+    if (!Array.isArray(parsed) || parsed.length !== 1) return false;
+    if (parsed[0]?.id !== name) return false;
+    const state = parsed[0]?.status?.state;
+    return typeof state === "string" && state !== "running";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The wedge signature, judged live: the named container has NOT reached
+ * `running` (definitively — see above) while the control plane still answers
+ * a `list`, observed STABLY: a second exact inspection after the list (and a
+ * short settle) must repeat the non-running verdict immediately before any
+ * recycle is authorized, closing the window where the container starts while
+ * the list is in flight. A dead apiserver fails the `list` too (that is an
+ * outage, not a wedge, and recycling on it would be a guess).
+ */
+async function appleWedgeVerdict(
+  engine: { command: string },
+  name: string,
+): Promise<boolean> {
+  if (!(await appleContainerDefinitivelyNotRunning(engine, name))) {
+    return false;
+  }
+  const listed = await run(engine.command, ["list", "--format", "json"], 15_000);
+  if (listed.code !== 0) return false;
+  await delayMs(Math.min(5_000, wedgeProbeDelayMs()));
+  return appleContainerDefinitivelyNotRunning(engine, name);
+}
+
+/**
+ * Run a maintenance container with corpse hygiene on the Apple runtime.
+ *
+ * `container run --rm` only removes a container that STARTED. A run refused
+ * at start time (the exclusive-volume attach, most commonly) leaves a
+ * created-never-started container behind, and those corpses wedge the
+ * runtime's apiserver (observed live 2026-08-16, twice: run/delete hang
+ * while list still answers). Naming the container makes the corpse
+ * addressable, so a failed run is followed by a bounded best-effort
+ * `delete --force` of that exact name. Docker's `--rm` is reliable and its
+ * containers are not corpse-prone, so the Docker path passes through.
+ *
+ * Every apple run doubles as the WEDGE SENSOR (the owner's "this needs to
+ * be automatic"): if the container has not reached `running` after the
+ * probe delay while `list` still answers, the runtime services are recycled
+ * in place (see apple-runtime-recycle.ts) and the run reports a distinctive
+ * retryable failure — the activation retry loop then re-runs maintenance
+ * against the fresh runtime.
+ */
+async function runMaintenanceContainer(
+  engine: { command: string; apple: boolean },
+  purpose: string,
+  argsAfterRun: string[],
+  timeoutMs: number,
+): Promise<RunResult> {
+  if (!engine.apple) {
+    return run(engine.command, ["run", ...argsAfterRun], timeoutMs);
+  }
+  maintenanceContainerSeq += 1;
+  const name = `uai-maint-${purpose}-${process.pid}-${maintenanceContainerSeq}`;
+  let runSettled = false;
+  const running = run(
+    engine.command,
+    // The ownership label is what authorizes the recycle sweep (and only the
+    // sweep) to delete this container later — a name alone is forgeable.
+    ["run", "--name", name, "-l", `${MAINTENANCE_CONTAINER_LABEL}=1`, ...argsAfterRun],
+    timeoutMs,
+  ).then((outcome) => {
+    runSettled = true;
+    return outcome;
+  });
+  const sensed = (async (): Promise<RunResult | null> => {
+    await delayMs(wedgeProbeDelayMs());
+    if (runSettled) return null;
+    if (!(await appleWedgeVerdict(engine, name))) return null;
+    if (runSettled) return null;
+    const outcome = await recycleAppleRuntimeServices({
+      cli: (args, cliTimeoutMs) => run(engine.command, args, cliTimeoutMs),
+    });
+    // The hung CLI client may exit once its apiserver dies; give it a short
+    // grace so a real result wins, then synthesize the retryable failure.
+    const graced = await Promise.race([
+      running,
+      delayMs(wedgeGraceMs()).then(() => null),
+    ]);
+    if (graced) return graced;
+    return {
+      code: null,
+      stdout: "",
+      stderr: outcome.recycled
+        ? "apple container runtime was wedged; runtime services were recycled — retry this operation"
+        : `apple container runtime is wedged and the automatic recycle did not recover it: ${outcome.reason}`,
+    };
+  })();
+  const result = await Promise.race([
+    running,
+    sensed.then((synthesized) => synthesized ?? running),
+  ]);
+  if (result.code !== 0) {
+    // The run may have failed BECAUSE this generated name already existed —
+    // then the container is not ours and the ownership label was never
+    // applied (review 2026-08-18 round 3). Deletion requires a positive
+    // label proof; an absent container is done; anything uncertain is left
+    // untouched and reported.
+    const inspected = await run(engine.command, ["inspect", name], 15_000);
+    let verdict: "ours" | "absent" | "foreign" | "unknown" = "unknown";
+    if (
+      inspected.code !== 0 &&
+      inspected.stdout.trim() === "" &&
+      inspected.stderr
+        .split("\n")
+        .some((line) => line.trim() === `Error: container not found: ${name}`)
+    ) {
+      verdict = "absent";
+    } else if (inspected.code === 0) {
+      try {
+        const parsed = JSON.parse(inspected.stdout) as Array<{
+          id?: unknown;
+          configuration?: { labels?: Record<string, unknown> };
+        }>;
+        if (Array.isArray(parsed) && parsed.length === 1 && parsed[0]?.id === name) {
+          verdict =
+            parsed[0]?.configuration?.labels?.[MAINTENANCE_CONTAINER_LABEL] === "1"
+              ? "ours"
+              : "foreign";
+        }
+      } catch {
+        verdict = "unknown";
+      }
+    }
+    if (verdict === "ours") {
+      const removed = await run(
+        engine.command,
+        ["delete", "--force", name],
+        30_000,
+      );
+      if (removed.code !== 0) {
+        console.warn(
+          `[host-agent] could not remove maintenance container ${name} after a ` +
+            `failed run (exit ${removed.code ?? "spawn"}); a created-never-started ` +
+            `container can wedge the Apple runtime. ${removed.stderr.trim().slice(0, 200)}`,
+        );
+      }
+    } else if (verdict === "foreign") {
+      console.warn(
+        `[host-agent] a container named ${name} exists WITHOUT Uai's maintenance ` +
+          "ownership label — the failed run likely collided with it; leaving it untouched",
+      );
+    } else if (verdict === "unknown") {
+      console.warn(
+        `[host-agent] could not prove ownership of maintenance container ${name} ` +
+          `after a failed run; leaving it untouched (inspect exit ${inspected.code ?? "spawn"})`,
+      );
+    }
+  }
+  return result;
+}
+
 /**
  * Agent CLIs that MUST exist inside the shared asdf volume. The volume mounts
  * over /opt/asdf-data and shadows the image's baked-in shims, so a volume
@@ -170,13 +495,11 @@ const VOLUME_AGENT_CLIS: { bin: string; pkg: string }[] = [
 ];
 
 /**
- * Self-heal the shared asdf volume: ensure each agent CLI resolves inside it,
- * installing + reshimming any that are missing. Cheap when healthy (one
- * container that just lists absent bins); only pays the npm cost on repair.
- * A fresh/empty volume is seeded from the image by Docker on first mount, so
- * this is a no-op there — it only fixes pre-existing stale volumes.
+ * Cheap, non-mutating diagnostic probe. This is never the authoritative final
+ * proof: another process can begin maintenance after a read-only check. The
+ * locked reconcile below always performs its own proof before releasing.
  */
-async function ensureVolumeAgentClis(): Promise<void> {
+async function probeVolumeAgentClis(): Promise<string[] | null> {
   const bins = VOLUME_AGENT_CLIS.map((c) => c.bin).join(" ");
   // Probe by EXECUTING each bin (`--version`), not `command -v`. A stale asdf
   // shim — the shim file survives in the volume but the reshim DB no longer
@@ -189,154 +512,534 @@ async function ensureVolumeAgentClis(): Promise<void> {
   // version from /home/node/.tool-versions — the same one the repair installs
   // against — and the sentinel prefix keeps login-shell noise from being
   // misread as a missing bin.
-  const check = await run("docker", [
-    "run",
+  const check = await runMaintenanceContainer(selectedEngine(), "cli-probe", [
     "--rm",
     "-w",
     "/home/node",
     "-v",
-    `${ASDF_DATA_VOLUME}:/opt/asdf-data`,
+    `${ASDF_DATA_VOLUME}:/opt/asdf-data:ro`,
     STANDARD_IMAGE_TAG,
-    "bash",
-    "-lc",
+    "/bin/bash",
+    "-c",
     `for b in ${bins}; do "$b" --version >/dev/null 2>&1 || echo "UAI_MISSING:$b"; done`,
-  ]);
+  ], SHORT_DOCKER_TIMEOUT_MS);
   if (check.code !== 0) {
     console.warn(
       `[host-agent] could not check agent CLIs in ${ASDF_DATA_VOLUME} (exit ` +
         `${check.code ?? "spawn"}); continuing. ${check.stderr.trim()}`,
     );
-    return;
+    return null;
   }
-  const missing = check.stdout
+  return check.stdout
     .split("\n")
     .map((l) => l.trim())
     .filter((l) => l.startsWith("UAI_MISSING:"))
     .map((l) => l.slice("UAI_MISSING:".length));
-  if (missing.length === 0) return;
+}
 
-  const pkgs = VOLUME_AGENT_CLIS.filter((c) => missing.includes(c.bin))
-    .map((c) => c.pkg)
-    .join(" ");
-  console.log(
-    `[host-agent] repairing ${ASDF_DATA_VOLUME}: agent CLI(s) [${missing.join(", ")}] ` +
-      `broken/missing in the shared volume — reshim + install ${pkgs}`,
-  );
-  const repair = await run("docker", [
-    "run",
+/**
+ * Create/repair the shared lock as a regular node-writable file. The lock is
+ * seeded into fresh volumes by the image. Legacy volumes can contain a 0644
+ * root-created file; opening it read-only permits flock, then metadata repair
+ * occurs while holding that same inode (never replace it under a waiter).
+ */
+async function prepareAsdfMaintenanceLock(): Promise<boolean> {
+  const command =
+    `set -eu; lock=${ASDF_MAINTENANCE_LOCK_PATH}; ` +
+    `if [ -L "$lock" ]; then echo "unsafe symlink lock: $lock" >&2; exit 1; fi; ` +
+    `if [ ! -e "$lock" ]; then umask 002; : > "$lock"; fi; ` +
+    `if [ ! -f "$lock" ]; then echo "lock is not regular: $lock" >&2; exit 1; fi; ` +
+    `exec 9<"$lock"; /usr/bin/flock --exclusive --timeout ${ASDF_MAINTENANCE_LOCK_WAIT_SECONDS} 9; ` +
+    `/usr/bin/chown node:node "$lock"; /usr/bin/chmod 0664 "$lock"`;
+  const result = await runMaintenanceContainer(selectedEngine(), "lock", [
     "--rm",
     "-u",
     "root",
-    // Run from /home/node so asdf resolves the node version from
-    // /home/node/.tool-versions. As root HOME is /root (no .tool-versions),
-    // and without a version asdf's npm shim aborts ("No version is set for
-    // command npm", exit 126). root can still write the volume from here.
-    "-w",
-    "/home/node",
     "-v",
     `${ASDF_DATA_VOLUME}:/opt/asdf-data`,
     STANDARD_IMAGE_TAG,
-    "bash",
-    "-lc",
-    // Reshim FIRST and with `;` (not `&&`): the common failure is a stale shim
-    // over an already-installed package, which a bare reshim fixes offline —
-    // gating it behind a network `npm install` (which may be down) would leave
-    // it broken. Then install to cover a genuinely-missing package, and reshim
-    // again for the freshly-installed one. Every step runs regardless of the
-    // previous one's exit. Final loop re-probes by execution so the exit code
-    // (and the log below) reflect whether the bins ACTUALLY run now, not just
-    // the trailing reshim's own exit.
-    `asdf reshim nodejs; npm install -g ${pkgs}; asdf reshim nodejs; ` +
-      `for b in ${bins}; do "$b" --version >/dev/null 2>&1 || ` +
-      `{ echo "UAI_STILL_BROKEN:$b" >&2; exit 1; }; done`,
-  ]);
-  if (repair.code === 0) {
-    console.log(
-      `[host-agent] ${ASDF_DATA_VOLUME} repaired — installed [${missing.join(", ")}]`,
-    );
-  } else {
-    console.warn(
-      `[host-agent] failed to repair ${ASDF_DATA_VOLUME} (exit ${repair.code ?? "spawn"}); ` +
-        `tasks may be missing [${missing.join(", ")}].\n${repair.stderr.trim()}`,
-    );
-  }
+    "/usr/bin/timeout",
+    "--signal=TERM",
+    "--kill-after=10s",
+    `${ASDF_MAINTENANCE_INTERNAL_TIMEOUT_SECONDS}s`,
+    "/bin/bash",
+    "-c",
+    command,
+  ], CLI_MAINTENANCE_TIMEOUT_MS);
+  if (result.code === 0) return true;
+  lastMaintenanceStderr = result.stderr;
+  console.warn(
+    `[host-agent] could not prepare ${ASDF_MAINTENANCE_LOCK_PATH} (exit ` +
+      `${result.code ?? "spawn"}): ${result.stderr.trim()}`,
+  );
+  return false;
 }
 
 /**
- * Upgrade the shared volume's agent CLIs to latest — once per HOST START, not
- * per task. Per-task installs would add npm latency to every task-up, race
- * concurrent starts on the shared volume, and give a broken vendor release a
- * fleet-wide blast radius with no rollback; host restarts are the deliberate
- * update moment (sessions respawn then anyway, and a bad release is one
- * `UAI_AGENT_CLI_AUTOUPDATE=0` + manual pin away from contained). Running
- * sessions keep their already-loaded process; new spawns pick up the new bin.
- * Best-effort: an offline registry just logs and keeps the current versions.
+ * One cross-process transaction owns upgrade, repair, Corepack repair, reshim,
+ * and the authoritative execution proof. A waiter always acquires the lock and
+ * performs its own full operation; a concurrent holder is never treated as
+ * success. The in-container timeout survives a disconnected Docker client and
+ * remains strictly inside the host-side child timeout.
  */
-async function upgradeVolumeAgentClis(): Promise<void> {
-  if (process.env.UAI_AGENT_CLI_AUTOUPDATE === "0") {
-    console.log("[host-agent] agent CLI auto-update disabled (UAI_AGENT_CLI_AUTOUPDATE=0)");
-    return;
-  }
+/** Build the single locked maintenance program. Exported only so focused
+ * tests can assert the crash-repair and proof contract without duplicating
+ * this security-sensitive shell in a fixture. */
+export function standardImageVolumeMaintenanceCommandForTest(
+  autoUpdate: boolean,
+): string {
   const pkgs = VOLUME_AGENT_CLIS.map((c) => `${c.pkg}@latest`).join(" ");
-  const bins = VOLUME_AGENT_CLIS.map((c) => c.bin);
-  // npm's in-place upgrade renames the old package dir, which fails with
-  // ENOTEMPTY while (or right after) live sessions held it open through the
-  // volume. Fallback: remove the scoped dirs and install fresh — safe at host
-  // start, when the previous sessions' execs are gone.
-  const scopeDirs = "/opt/asdf-data/installs/nodejs/*/lib/node_modules/@anthropic-ai /opt/asdf-data/installs/nodejs/*/lib/node_modules/@openai";
-  const upgrade = await run("docker", [
-    "run",
+  const trustedNpmFlags =
+    "--registry=https://registry.npmjs.org/ --userconfig=/dev/null " +
+    "--globalconfig=/dev/uai-empty-npmrc";
+  return (
+    `set -u; upgrade=${autoUpdate ? 1 : 0}; ` +
+    `fail() { echo "UAI_STILL_BROKEN:$1" >&2; exit 1; }; ` +
+    `export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin; ` +
+    `export HOME=/home/node ASDF_DIR=/opt/asdf ASDF_DATA_DIR=/opt/asdf-data ` +
+    `ASDF_CONFIG_FILE=/dev/null ASDF_DEFAULT_TOOL_VERSIONS_FILENAME=.tool-versions ` +
+    `COREPACK_HOME=/opt/asdf-data/corepack COREPACK_DEFAULT_TO_LATEST=0 ` +
+    `COREPACK_ENABLE_AUTO_PIN=0 COREPACK_ENABLE_DOWNLOAD_PROMPT=0 ` +
+    `COREPACK_ENV_FILE=0 COREPACK_ENABLE_PROJECT_SPEC=1 COREPACK_ENABLE_STRICT=1 ` +
+    `COREPACK_ENABLE_UNSAFE_CUSTOM_URLS=0 COREPACK_INTEGRITY_CHECK=1 ` +
+    `COREPACK_ENABLE_NETWORK=0 COREPACK_NPM_REGISTRY=https://registry.npmjs.org; ` +
+    `default_node="$(/usr/bin/awk '$1 == "nodejs" { print $2; exit }' /home/node/.tool-versions)"; ` +
+    `if ! printf '%s' "$default_node" | /usr/bin/grep -Eq '^[0-9]+\\.[0-9]+\\.[0-9]+$'; then ` +
+    `fail default-node; fi; ` +
+    `[ "$default_node" = "${STANDARD_DEFAULT_NODE_VERSION}" ] || ` +
+    `fail default-node-release-migration-required; ` +
+    `export ASDF_NODEJS_VERSION="$default_node"; ` +
+    `if [ -e /dev/uai-empty-npmrc ] || [ -L /dev/uai-empty-npmrc ]; then ` +
+    `fail unsafe-npm-config; fi; ` +
+    `installs_root="$ASDF_DATA_DIR/installs"; node_root="$installs_root/nodejs"; ` +
+    `candidate="$node_root/$default_node"; shims_root="$ASDF_DATA_DIR/shims"; ` +
+    `corepack_root="$COREPACK_HOME"; ` +
+    `ensure_real_dir() { path="$1"; label="$2"; ` +
+    `if [ -L "$path" ] || { [ -e "$path" ] && [ ! -d "$path" ]; }; then ` +
+    `fail "unsafe-$label"; fi; ` +
+    `if [ ! -d "$path" ]; then /usr/bin/install -d -o node -g node -m 0775 "$path" ` +
+    `|| fail "create-$label"; fi; ` +
+    `lexical="$(/usr/bin/realpath -m -s -- "$path")"; ` +
+    `resolved="$(/usr/bin/realpath -e -- "$path")" ` +
+    `|| fail "resolve-$label"; [ "$lexical" = "$resolved" ] ` +
+    `|| fail "escaped-$label"; /usr/bin/chown node:node "$path" ` +
+    `|| fail "owner-$label"; /usr/bin/chmod u+rwx,g+rwx "$path" ` +
+    `|| fail "mode-$label"; }; ` +
+    `ensure_real_dir "$ASDF_DATA_DIR" asdf-data; ` +
+    `ensure_real_dir "$installs_root" installs-root; ` +
+    `ensure_real_dir "$node_root" node-root; ` +
+    `ensure_real_dir "$shims_root" shims-root; ` +
+    `ensure_real_dir "$corepack_root" corepack-root; ` +
+    `candidate_is_safe() { ` +
+    `lexical_candidate="$(/usr/bin/realpath -m -s -- "$candidate")" ` +
+    `|| return 1; [ "$lexical_candidate" = "$node_root/$default_node" ] ` +
+    `|| return 1; if [ -e "$candidate" ] || [ -L "$candidate" ]; then ` +
+    `[ ! -L "$candidate" ] && [ -d "$candidate" ] || return 1; ` +
+    `resolved_candidate="$(/usr/bin/realpath -e -- "$candidate")" ` +
+    `|| return 1; ` +
+    `[ "$resolved_candidate" = "$lexical_candidate" ] || return 1; fi; }; ` +
+    `contained_executable() { root="$1"; executable="$2"; ` +
+    `[ -f "$executable" ] && [ -x "$executable" ] || return 1; ` +
+    `real_executable="$(/usr/bin/realpath -e -- "$executable")" ` +
+    `|| return 1; ` +
+    `case "$real_executable" in "$root"/*) return 0 ;; *) return 1 ;; esac; }; ` +
+    `contained_real_dir() { root="$1"; path="$2"; ` +
+    `[ ! -L "$path" ] && [ -d "$path" ] || return 1; ` +
+    `lexical_path="$(/usr/bin/realpath -m -s -- "$path")" || return 1; ` +
+    `real_path="$(/usr/bin/realpath -e -- "$path")" || return 1; ` +
+    `case "$lexical_path" in "$root"/*) ;; *) return 1 ;; esac; ` +
+    `[ "$real_path" = "$lexical_path" ]; }; ` +
+    `npm_prefix_is_safe() { contained_real_dir "$candidate" "$candidate/bin" ` +
+    `&& contained_real_dir "$candidate" "$candidate/lib" ` +
+    `&& contained_real_dir "$candidate" "$candidate/lib/node_modules"; }; ` +
+    `scope_is_safe_or_absent() { scope="$1"; ` +
+    `if [ -e "$scope" ] || [ -L "$scope" ]; then ` +
+    `contained_real_dir "$candidate" "$scope"; fi; }; ` +
+    `as_node() { /usr/bin/setpriv --reuid=node --regid=node --init-groups ` +
+    `/usr/bin/env -i HOME="$HOME" ASDF_DIR="$ASDF_DIR" ` +
+    `ASDF_DATA_DIR="$ASDF_DATA_DIR" ASDF_CONFIG_FILE=/dev/null ` +
+    `ASDF_DEFAULT_TOOL_VERSIONS_FILENAME=.tool-versions ` +
+    `ASDF_NODEJS_VERSION="$default_node" COREPACK_HOME="$COREPACK_HOME" ` +
+    `COREPACK_DEFAULT_TO_LATEST=0 COREPACK_ENABLE_AUTO_PIN=0 ` +
+    `COREPACK_ENABLE_DOWNLOAD_PROMPT=0 COREPACK_ENV_FILE=0 ` +
+    `COREPACK_ENABLE_PROJECT_SPEC=1 COREPACK_ENABLE_STRICT=1 ` +
+    `COREPACK_ENABLE_UNSAFE_CUSTOM_URLS=0 COREPACK_INTEGRITY_CHECK=1 ` +
+    `COREPACK_ENABLE_NETWORK=0 COREPACK_NPM_REGISTRY=https://registry.npmjs.org ` +
+    `NPM_CONFIG_PREFIX="$candidate" ` +
+    `PATH="$candidate/bin:/opt/asdf/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ` +
+    `"$@"; }; ` +
+    `as_node_control() { /usr/bin/setpriv --reuid=node --regid=node --init-groups ` +
+    `/usr/bin/env -i HOME="$HOME" ASDF_DIR="$ASDF_DIR" ` +
+    `ASDF_DATA_DIR="$ASDF_DATA_DIR" ASDF_CONFIG_FILE=/dev/null ` +
+    `ASDF_DEFAULT_TOOL_VERSIONS_FILENAME=.tool-versions ` +
+    `ASDF_NODEJS_VERSION="$default_node" COREPACK_HOME="$COREPACK_HOME" ` +
+    `COREPACK_DEFAULT_TO_LATEST=0 COREPACK_ENABLE_AUTO_PIN=0 ` +
+    `COREPACK_ENABLE_DOWNLOAD_PROMPT=0 COREPACK_ENV_FILE=0 ` +
+    `COREPACK_ENABLE_PROJECT_SPEC=1 COREPACK_ENABLE_STRICT=1 ` +
+    `COREPACK_ENABLE_UNSAFE_CUSTOM_URLS=0 COREPACK_INTEGRITY_CHECK=1 ` +
+    `COREPACK_ENABLE_NETWORK=0 COREPACK_NPM_REGISTRY=https://registry.npmjs.org ` +
+    `PATH="/opt/asdf/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ` +
+    `"$@"; }; ` +
+    `clear_forbidden_shared_bash_shim() { fail_if_found="$1"; ` +
+    `bash_shim="$shims_root/bash"; bash_shim_found=0; ` +
+    `if [ -e "$bash_shim" ] || [ -L "$bash_shim" ]; then ` +
+    `bash_shim_found=1; ` +
+    `[ ! -d "$bash_shim" ] || fail unsafe-runtime-bash-shim-directory; ` +
+    `as_node /usr/bin/rm -f -- "$bash_shim" ` +
+    `|| fail remove-runtime-bash-shim; fi; ` +
+    `[ ! -e "$bash_shim" ] && [ ! -L "$bash_shim" ] ` +
+    `|| fail unsafe-runtime-bash-shim; ` +
+    `if [ "$fail_if_found" -ne 0 ] && [ "$bash_shim_found" -ne 0 ]; then ` +
+    `return 1; fi; }; ` +
+    `clear_forbidden_candidate_bash() { fail_if_found="$1"; ` +
+    `candidate_bash="$candidate/bin/bash"; candidate_bash_found=''; ` +
+    `if [ -e "$candidate_bash" ] || [ -L "$candidate_bash" ]; then ` +
+    `candidate_bash_found=1; [ ! -d "$candidate_bash" ] ` +
+    `|| fail unsafe-default-bash-directory; ` +
+    `as_node /usr/bin/rm -f -- "$candidate_bash" ` +
+    `|| fail remove-default-bash; fi; ` +
+    `[ ! -e "$candidate_bash" ] && [ ! -L "$candidate_bash" ] ` +
+    `|| fail unsafe-default-bash; ` +
+    `if [ "$fail_if_found" -ne 0 ] && [ -n "$candidate_bash_found" ]; then ` +
+    `return 1; fi; }; ` +
+    `run_asdf_install() { asdf_status=0; shim_status=0; ` +
+    `as_node_control /opt/asdf/bin/asdf install "$@" || asdf_status=$?; ` +
+    `clear_forbidden_shared_bash_shim 1 || shim_status=$?; ` +
+    `[ "$shim_status" -eq 0 ] || return 1; return "$asdf_status"; }; ` +
+    `run_asdf_reshim() { asdf_status=0; shim_status=0; ` +
+    `as_node_control /opt/asdf/bin/asdf reshim "$@" || asdf_status=$?; ` +
+    `clear_forbidden_shared_bash_shim 1 || shim_status=$?; ` +
+    `[ "$shim_status" -eq 0 ] || return 1; return "$asdf_status"; }; ` +
+    `reject_runtime_bash_shims() { ` +
+    `bash_cleanup_status=0; clear_forbidden_candidate_bash 1 ` +
+    `|| bash_cleanup_status=1; ` +
+    `clear_forbidden_shared_bash_shim 1 || bash_cleanup_status=1; ` +
+    `[ "$bash_cleanup_status" -eq 0 ] || fail unsafe-runtime-bash-shim; }; ` +
+    `node_write_probe() { writable="$1"; ` +
+    `probe="$(as_node /usr/bin/mktemp -d "$writable/.uai-write-probe.XXXXXX")" ` +
+    `|| return 1; case "$probe" in "$writable"/.uai-write-probe.*) ;; ` +
+    `*) return 1 ;; esac; as_node /usr/bin/rmdir "$probe"; }; ` +
+    `candidate_owned_by_node() { ` +
+    `[ -z "$(/usr/bin/find "$candidate" -xdev ! -user node -print -quit)" ] ` +
+    `&& [ -z "$(/usr/bin/find "$candidate" -xdev -type d ! -perm -u+w -print -quit)" ]; }; ` +
+    `prove_default_node() { candidate_is_safe && [ -d "$candidate" ] ` +
+    `&& [ ! -e "$candidate/bin/bash" ] && [ ! -L "$candidate/bin/bash" ] ` +
+    `&& contained_executable "$candidate" "$candidate/bin/node" ` +
+    `&& [ "$(as_node "$candidate/bin/node" --version 2>/dev/null)" = "v$default_node" ] ` +
+    `&& contained_executable "$candidate" "$candidate/bin/npm" ` +
+    `&& [ -n "$(as_node "$candidate/bin/npm" --version 2>/dev/null)" ] ` +
+    `&& npm_prefix_is_safe && candidate_owned_by_node ` +
+    `&& node_write_probe "$candidate/bin"; }; ` +
+    `clear_forbidden_shared_bash_shim 0; ` +
+    `if ! prove_default_node; then candidate_is_safe || fail unsafe-default-candidate; ` +
+    `/usr/bin/rm -rf --one-file-system -- "$candidate" ` +
+    `|| fail remove-default-candidate; ` +
+    `run_asdf_install nodejs "$default_node" ` +
+    `|| fail install-default-node; prove_default_node || fail repaired-default-node; fi; ` +
+    `npm_bin="$candidate/bin/npm"; cd / || fail chdir; ` +
+    `if [ "$upgrade" = 1 ]; then ` +
+    `npm_prefix_is_safe || fail unsafe-npm-prefix; ` +
+    `if ! as_node "$npm_bin" install -g ${pkgs} ${trustedNpmFlags} ` +
+    `>/tmp/uai-cli-upgrade.out 2>&1; then ` +
+    `if /usr/bin/grep -qi 'ENOTEMPTY' /tmp/uai-cli-upgrade.out; then ` +
+    `scope_is_safe_or_absent "$candidate/lib/node_modules/@anthropic-ai" ` +
+    `&& scope_is_safe_or_absent "$candidate/lib/node_modules/@openai" ` +
+    `|| fail unsafe-cli-scope; ` +
+    `as_node /usr/bin/rm -rf --one-file-system -- ` +
+    `"$candidate/lib/node_modules/@anthropic-ai" ` +
+    `"$candidate/lib/node_modules/@openai"; ` +
+    `if ! as_node "$npm_bin" install -g ${pkgs} ${trustedNpmFlags} ` +
+    `>/tmp/uai-cli-upgrade-retry.out 2>&1; then ` +
+    `echo 'UAI_CLI_UPDATE_DEFERRED:bulk-retry' >&2; fi; ` +
+    `else echo 'UAI_CLI_UPDATE_DEFERRED:bulk' >&2; fi; fi; fi; ` +
+    // Reshim first so an installed package behind a stale shim can recover
+    // without network access. Only bins that still fail are reinstalled.
+    `if ! run_asdf_reshim nodejs "$default_node" ` +
+    `>/dev/null 2>&1; then echo 'UAI_CLI_RESHIM_DEFERRED:initial' >&2; fi; ` +
+    `cli_ready_once() { b="$1"; ` +
+    `contained_executable "$candidate" "$candidate/bin/$b" || return 1; ` +
+    `direct_version="$(as_node "$candidate/bin/$b" --version 2>/dev/null ` +
+    `| /usr/bin/head -1)"; [ -n "$direct_version" ] || return 1; ` +
+    `shim="$shims_root/$b"; [ ! -L "$shim" ] && [ -f "$shim" ] ` +
+    `&& [ -x "$shim" ] || return 1; ` +
+    `shim_version="$(as_node "$shim" --version 2>/dev/null ` +
+    `| /usr/bin/head -1)"; [ "$shim_version" = "$direct_version" ]; }; ` +
+    `repair_cli_once() { b="$1"; case "$b" in ` +
+    `claude) pkg='@anthropic-ai/claude-code'; scope='@anthropic-ai'; ` +
+    `package_name='claude-code';; ` +
+    `codex) pkg='@openai/codex'; scope='@openai'; package_name='codex';; ` +
+    `*) return 1;; esac; ` +
+    `package_path="$candidate/lib/node_modules/$scope/$package_name"; ` +
+    `npm_prefix_is_safe || return 1; ` +
+    `scope_is_safe_or_absent "$candidate/lib/node_modules/$scope" ` +
+    `|| return 1; ` +
+    `as_node /usr/bin/rm -rf --one-file-system -- ` +
+    `"$candidate/bin/$b" "$package_path" || return 1; ` +
+    `as_node "$npm_bin" install -g --force "$pkg@latest" ${trustedNpmFlags} ` +
+    `>/dev/null 2>&1 || return 1; ` +
+    `run_asdf_reshim nodejs "$default_node" ` +
+    `>/dev/null 2>&1 || return 1; cli_ready_once "$b"; }; ` +
+    `for b in claude codex; do if ! cli_ready_once "$b"; then ` +
+    `repair_cli_once "$b" || fail "$b-repair"; fi; done; ` +
+    // Node <=22's bundled Corepack has obsolete registry signing keys. The
+    // host-packaged pin is compatible with every advertised Node default.
+    `required_corepack="$(/usr/bin/sed -n '1p' /usr/local/share/uai/corepack-version)"; ` +
+    `printf '%s' "$required_corepack" | /usr/bin/grep -Eq '^[0-9]+\\.[0-9]+\\.[0-9]+$' || { ` +
+    `echo 'UAI_STILL_BROKEN:corepack-pin' >&2; exit 1; }; ` +
+    `corepack_ready_once() { ` +
+    `contained_executable "$candidate" "$candidate/bin/corepack" || return 1; ` +
+    `[ "$(as_node "$candidate/bin/corepack" --version 2>/dev/null)" = "$required_corepack" ] ` +
+    `|| return 1; as_node "$candidate/bin/corepack" enable >/dev/null 2>&1 ` +
+    `|| return 1; run_asdf_reshim nodejs "$default_node" ` +
+    `>/dev/null 2>&1 || return 1; ` +
+    `corepack_shim="$shims_root/corepack"; [ ! -L "$corepack_shim" ] ` +
+    `&& [ -f "$corepack_shim" ] && [ -x "$corepack_shim" ] || return 1; ` +
+    `[ "$(as_node "$corepack_shim" --version 2>/dev/null)" = "$required_corepack" ]; }; ` +
+    `repair_corepack_once() { ` +
+    `npm_prefix_is_safe || return 1; ` +
+    `as_node /usr/bin/rm -rf --one-file-system -- ` +
+    `"$candidate/lib/node_modules/corepack" "$candidate/bin/corepack" ` +
+    `"$candidate/bin/pnpm" "$candidate/bin/pnpx" "$candidate/bin/yarn" ` +
+    `"$candidate/bin/yarnpkg" || return 1; ` +
+    `as_node "$npm_bin" install -g --force "corepack@$required_corepack" ` +
+    `--no-audit --no-fund ${trustedNpmFlags} >/dev/null 2>&1 || return 1; ` +
+    `run_asdf_reshim nodejs "$default_node" >/dev/null 2>&1 ` +
+    `|| return 1; contained_executable "$candidate" "$candidate/bin/corepack" ` +
+    `|| return 1; as_node "$candidate/bin/corepack" disable >/dev/null 2>&1 ` +
+    `|| return 1; as_node "$candidate/bin/corepack" enable >/dev/null 2>&1 ` +
+    `|| return 1; run_asdf_reshim nodejs "$default_node" ` +
+    `>/dev/null 2>&1 || return 1; corepack_ready_once; }; ` +
+    `if ! corepack_ready_once; then repair_corepack_once ` +
+    `|| fail corepack-repair; fi; reject_runtime_bash_shims; failed=0; ` +
+    `prove_default_node || { echo "UAI_STILL_BROKEN:default-node-final" >&2; failed=1; }; ` +
+    `for b in claude codex; do ` +
+    `if ! contained_executable "$candidate" "$candidate/bin/$b"; then ` +
+    `echo "UAI_STILL_BROKEN:$b-contained" >&2; failed=1; continue; fi; ` +
+    `version="$(as_node "$candidate/bin/$b" --version 2>/dev/null | /usr/bin/head -1)"; ` +
+    `shim="$shims_root/$b"; if [ -L "$shim" ] || [ ! -f "$shim" ] ` +
+    `|| [ ! -x "$shim" ]; then echo "UAI_STILL_BROKEN:$b-shim" >&2; ` +
+    `failed=1; continue; fi; ` +
+    `shim_version="$(as_node "$shim" --version 2>/dev/null | /usr/bin/head -1)"; ` +
+    `if [ -z "$version" ] || [ "$shim_version" != "$version" ]; then ` +
+    `echo "UAI_STILL_BROKEN:$b" >&2; failed=1; ` +
+    `else printf '%s ' "$version"; fi; done; ` +
+    `node_shim="$shims_root/node"; ` +
+    `[ ! -L "$node_shim" ] && [ -f "$node_shim" ] && [ -x "$node_shim" ] ` +
+    `|| { echo "UAI_STILL_BROKEN:node-shim-file" >&2; failed=1; }; ` +
+    `shim_node="$(as_node "$node_shim" --version 2>/dev/null || true)"; ` +
+    `[ "$shim_node" = "v$default_node" ] || { ` +
+    `echo "UAI_STILL_BROKEN:node-shim" >&2; failed=1; }; ` +
+    `npm_shim="$shims_root/npm"; ` +
+    `[ ! -L "$npm_shim" ] && [ -f "$npm_shim" ] && [ -x "$npm_shim" ] ` +
+    `|| { echo "UAI_STILL_BROKEN:npm-shim-file" >&2; failed=1; }; ` +
+    `shim_npm="$(as_node "$npm_shim" --version 2>/dev/null || true)"; ` +
+    `[ -n "$shim_npm" ] || { echo "UAI_STILL_BROKEN:npm-shim" >&2; failed=1; }; ` +
+    `if ! corepack_ready_once; then echo "UAI_STILL_BROKEN:corepack-final" >&2; ` +
+    `failed=1; else printf 'corepack %s' "$required_corepack"; fi; ` +
+    `node_write_probe "$candidate/bin" || { ` +
+    `echo "UAI_STILL_BROKEN:default-node-owner" >&2; failed=1; }; ` +
+    `node_write_probe "$shims_root" || { ` +
+    `echo "UAI_STILL_BROKEN:shims-owner" >&2; failed=1; }; ` +
+    `node_write_probe "$corepack_root" || { ` +
+    `echo "UAI_STILL_BROKEN:corepack-owner" >&2; failed=1; }; ` +
+    `exit "$failed"`
+  );
+}
+
+async function reconcileVolumeAgentClis(): Promise<boolean> {
+  const missingBefore = await probeVolumeAgentClis();
+  if (missingBefore?.length) {
+    console.log(
+      `[host-agent] repairing ${ASDF_DATA_VOLUME}: agent CLI(s) ` +
+        `[${missingBefore.join(", ")}] failed their execution probe`,
+    );
+  }
+
+  const autoUpdate = process.env.UAI_AGENT_CLI_AUTOUPDATE !== "0";
+  if (!autoUpdate) {
+    console.log(
+      "[host-agent] agent CLI auto-update disabled (UAI_AGENT_CLI_AUTOUPDATE=0)",
+    );
+  }
+  const command = standardImageVolumeMaintenanceCommandForTest(autoUpdate);
+  const reconcile = await runMaintenanceContainer(selectedEngine(), "reconcile", [
     "--rm",
-    // The container NAME is the mutex: overlapping boots (or a crash-looping
-    // service) must never race two npm installs on the shared volume — that
-    // once left it with no `claude` at all (2026-07-13). Docker rejects the
-    // duplicate name; we treat that as "already upgrading, skip".
-    "--name",
-    "uai-cli-upgrade",
     "-u",
     "root",
     "-w",
     "/home/node",
     "-v",
     `${ASDF_DATA_VOLUME}:/opt/asdf-data`,
+    "-v",
+    `${standardImageCorepackVersionPath()}:/usr/local/share/uai/corepack-version:ro`,
     STANDARD_IMAGE_TAG,
-    "bash",
-    "-lc",
-    // Reshim is its OWN statement (`;`, not `&&`) so it ALWAYS runs after the
-    // install attempts — with `&& reshim`, the `|| { rm -rf; reinstall; }`
-    // fallback's exit code could skip the reshim, leaving a stale `codex`/
-    // `claude` shim ("No <cli> executable found for nodejs …") even though the
-    // bin installed fine (hit codex live 2026-07-16). Reshim is idempotent and
-    // cheap, so running it unconditionally is strictly safer.
-    `npm install -g ${pkgs} >/dev/null 2>&1 || { rm -rf ${scopeDirs}; npm install -g ${pkgs} >/dev/null 2>&1; }; ` +
-      `asdf reshim nodejs >/dev/null 2>&1; ` +
-      bins.map((b) => `printf '%s ' "$(${b} --version 2>/dev/null | head -1)"`).join("; "),
-  ]);
-  if (upgrade.code !== 0 && /already in use/i.test(upgrade.stderr)) {
-    console.log("[host-agent] agent CLI upgrade already running — skipped");
-    return;
-  }
-  if (upgrade.code === 0) {
+    "/usr/bin/timeout",
+    "--signal=TERM",
+    "--kill-after=10s",
+    `${ASDF_MAINTENANCE_INTERNAL_TIMEOUT_SECONDS}s`,
+    "/usr/bin/flock",
+    "--exclusive",
+    "--timeout",
+    `${ASDF_MAINTENANCE_LOCK_WAIT_SECONDS}`,
+    ASDF_MAINTENANCE_LOCK_PATH,
+    "/bin/bash",
+    "-c",
+    command,
+  ], CLI_MAINTENANCE_TIMEOUT_MS);
+  if (reconcile.code === 0) {
     console.log(
-      `[host-agent] agent CLIs current on ${ASDF_DATA_VOLUME}: ${upgrade.stdout.trim()}`,
+      `[host-agent] agent CLIs and Corepack current on ${ASDF_DATA_VOLUME}: ` +
+        reconcile.stdout.trim(),
     );
+    await writeVolumeReconcileProof();
+    return true;
   } else {
+    lastMaintenanceStderr = reconcile.stderr;
     console.warn(
-      `[host-agent] agent CLI upgrade skipped (exit ${upgrade.code ?? "spawn"}) — ` +
-        `tasks keep the volume's current versions. ${upgrade.stderr.trim().slice(0, 200)}`,
+      `[host-agent] failed to reconcile ${ASDF_DATA_VOLUME} (exit ` +
+        `${reconcile.code ?? "spawn"}); task runtimes are not ready. ` +
+        reconcile.stderr.trim().slice(0, 500),
     );
+    return false;
   }
 }
 
+/** Durable evidence that the shared volume completed a full reconcile at
+ * least once on this host. Apple volumes are block devices with EXCLUSIVE
+ * writable attachments, so boot maintenance cannot re-prove the volume while
+ * running task containers hold it read-only — and blocking activation on
+ * that (the 2026-08-16 ring) froze hosts and blocked the very teardowns that
+ * would free the volume. With this proof on disk, a busy volume defers
+ * maintenance instead of failing it. */
+let lastMaintenanceStderr = "";
+
+async function volumeReconcileProofPath(): Promise<string> {
+  // Lazy env resolve: module import must stay side-effect free (see
+  // defaultRuntimeProviderStateStore). Dynamic import, not require — a bare
+  // require cannot resolve the TypeScript module outside the tsx runtime,
+  // which silently read as "no proof" and disabled deferral.
+  const { env } = await import("./env");
+  return resolve(env.dataDir, "runtime-volume-proof.json");
+}
+
+async function writeVolumeReconcileProof(): Promise<void> {
+  try {
+    writeFileSync(
+      await volumeReconcileProofPath(),
+      `${JSON.stringify({ schemaVersion: 1, provedAt: Date.now() })}\n`,
+      { mode: 0o600 },
+    );
+  } catch (error) {
+    console.warn(
+      `[host-agent] could not persist the shared-volume reconcile proof: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+}
+
+async function volumeReconcileProofExists(): Promise<boolean> {
+  try {
+    const raw = JSON.parse(
+      readFileSync(await volumeReconcileProofPath(), "utf8"),
+    ) as { schemaVersion?: unknown };
+    return raw?.schemaVersion === 1;
+  } catch {
+    return false;
+  }
+}
+
+const VOLUME_ATTACH_BUSY_SIGNATURE = "storage device attachment is invalid";
+
+/**
+ * Whether task containers hold the shared volume — tri-state per container,
+ * never fail-open: `running` holds, exact `stopped` is released (a stopped
+ * VM releases its block attachments — proven live 2026-08-17, when a full
+ * writable reconcile succeeded next to a stopped task container), and EVERY
+ * other observation (starting, stopping, creating, a missing or foreign
+ * state string, an unreadable inventory) is `unknown` — a task acquiring or
+ * releasing the volume mid-transition must never read as permission for a
+ * writer (review 2026-08-18 round 2). `held` dominates `unknown` dominates
+ * `free`; writers require a positive `free`.
+ */
+async function sharedVolumeHolders(engine: {
+  command: string;
+  apple: boolean;
+}): Promise<"held" | "free" | "unknown"> {
+  const listed = await run(
+    engine.command,
+    ["list", "--all", "--format", "json"],
+    30_000,
+  );
+  if (listed.code !== 0) return "unknown";
+  try {
+    const parsed = JSON.parse(listed.stdout) as Array<{
+      configuration?: {
+        id?: unknown;
+        mounts?: Array<{ type?: { volume?: { name?: unknown } } }>;
+      };
+      status?: { state?: unknown };
+    }>;
+    if (!Array.isArray(parsed)) return "unknown";
+    let verdict: "held" | "free" | "unknown" = "free";
+    for (const item of parsed) {
+      // A holder is a container whose CONFIGURED MOUNTS include the shared
+      // volume — physical attachment, not a name shape (review 2026-08-18
+      // round 3: an unrelated task-*-app container with no attachment
+      // fenced activation forever, and the holder-remedy sweep — which
+      // correctly matches by mount — could not clear it). A row whose
+      // mounts cannot be read might hold the volume, so it is `unknown`.
+      const mounts = item?.configuration?.mounts;
+      if (!Array.isArray(mounts)) {
+        verdict = "unknown";
+        continue;
+      }
+      const holds = mounts.some(
+        (mount) => mount?.type?.volume?.name === ASDF_DATA_VOLUME,
+      );
+      if (!holds) continue;
+      const state = item?.status?.state;
+      if (state === "running") return "held";
+      if (state !== "stopped") verdict = "unknown";
+    }
+    return verdict;
+  } catch {
+    return "unknown";
+  }
+}
+
+/** Backstop for the race the proof-first check cannot close: a task container
+ * appearing between the check and the attach. Admits deferral only on the
+ * exact busy signature, with the same proof requirement. */
+async function volumeBusyDeferral(
+  engine: { command: string; apple: boolean },
+  stderr: string,
+): Promise<boolean> {
+  if (!engine.apple) return false;
+  if (!stderr.includes(VOLUME_ATTACH_BUSY_SIGNATURE)) return false;
+  if (!(await volumeReconcileProofExists())) return false;
+  return (await sharedVolumeHolders(engine)) === "held";
+}
+
 /** Outcome of ensureStandardImage — `error` carries WHY when not ready, so
  *  the taskUp path can surface a build failure to the cloud (not just the host
  *  log). Callers that only fire-and-forget at boot ignore the return. */
 export interface StandardImageResult {
   ok: boolean;
   error?: string;
+  /** A non-writer escape the activation driver can perform before retrying:
+   * lifecycle-stop the running task containers holding the shared volume
+   * (resumable), because the volume needs a repair they block and cannot
+   * safely use. */
+  remedy?: "stop-volume-holders";
 }
 
+type AgentClisReadyListener = () => void;
+
+let agentClisReadyLatched = false;
 let signalClisReady: (() => void) | null = null;
+const agentClisReadyListeners = new Set<AgentClisReadyListener>();
+const ensureQueue = new KeyedPromiseTail<StandardImageResult>();
 /**
  * Resolves once ensureStandardImage has reconciled the shared-volume agent CLIs
  * at least once (or bailed because docker is down / the build failed). The agent
@@ -349,6 +1052,55 @@ export const agentClisReady: Promise<void> = new Promise<void>((resolve) => {
   signalClisReady = resolve;
 });
 
+/** Whether this process has completed its one boot-time CLI maintenance pass.
+ * This is intentionally a one-way boot latch, not a claim that no later
+ * operator-triggered image work is in flight. */
+export function areAgentClisReady(): boolean {
+  return agentClisReadyLatched;
+}
+
+/** Subscribe to the one readiness edge. A late subscriber is notified in a
+ * microtask so registration never re-enters its caller. */
+export function onAgentClisReady(
+  listener: AgentClisReadyListener,
+): () => void {
+  if (agentClisReadyLatched) {
+    let cancelled = false;
+    queueMicrotask(() => {
+      if (!cancelled) notifyAgentClisReadyListener(listener);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }
+  agentClisReadyListeners.add(listener);
+  return () => agentClisReadyListeners.delete(listener);
+}
+
+function notifyAgentClisReadyListener(listener: AgentClisReadyListener): void {
+  try {
+    listener();
+  } catch (error) {
+    console.warn(
+      `[host-agent] agent CLI readiness listener failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+function markAgentClisReady(): void {
+  if (agentClisReadyLatched) return;
+  // Publish the synchronous capability state before resolving the promise:
+  // every waiter and listener must observe `true` after the readiness edge.
+  agentClisReadyLatched = true;
+  signalClisReady?.();
+  signalClisReady = null;
+  const listeners = [...agentClisReadyListeners];
+  agentClisReadyListeners.clear();
+  for (const listener of listeners) {
+    notifyAgentClisReadyListener(listener);
+  }
+}
+
 /**
  * Ensure the standard image and the shared asdf data volume exist, and that the
  * agent CLIs are present inside the volume. Builds the image only when `docker
@@ -356,21 +1108,52 @@ export const agentClisReady: Promise<void> = new Promise<void>((resolve) => {
  * `{ ok, error? }` so the caller decides (boot: fire-and-forget; taskUp:
  * surface the reason). Resolves `agentClisReady` on every exit path.
  */
-export async function ensureStandardImage(): Promise<StandardImageResult> {
-  try {
-    return await ensureStandardImageInner();
-  } finally {
-    // Always signal — even a docker-down bail — so agent spawns never hang
-    // waiting on a reconcile that will not happen this boot.
-    signalClisReady?.();
-    signalClisReady = null;
-  }
+export function ensureStandardImage(): Promise<StandardImageResult> {
+  // Startup, runtime recovery, and a newly-arrived task can all discover the
+  // same daemon transition. One shared volume repair/build must own that
+  // window; concurrent maintenance containers can otherwise replace the same
+  // CLI shims underneath each other and defeat agentClisReady's fence.
+  const engines = configuredOptionalEngines();
+  return ensureQueue.run(optionalEngineConfigurationKey(engines), () =>
+    ensureStandardImageInner(engines).finally(() => {
+      // Always signal — even a docker-down bail — so agent spawns never hang
+      // waiting on a reconcile that will not happen this boot.
+      markAgentClisReady();
+    }),
+  );
 }
 
-async function ensureStandardImageInner(): Promise<StandardImageResult> {
-  // 1. Shared asdf data volume — idempotent.
-  const vol = await run("docker", ["volume", "create", ASDF_DATA_VOLUME]);
-  if (vol.code !== 0) {
+async function ensureStandardImageInner(
+  engines: OptionalEngineConfiguration,
+): Promise<StandardImageResult> {
+  // 1. Shared asdf data volume — idempotent under Docker; the Apple CLI
+  //    errors on an existing name, which is the same healthy outcome.
+  const engine = selectedEngine();
+  console.log(
+    `[host-agent] standard-image maintenance starting (engine: ${engine.apple ? "apple-container" : "docker"})`,
+  );
+  if (engine.apple) {
+    // The volume create below is the FIRST apple mutation on a host — before
+    // any task exists — and uninstall reads an absent provider-claim marker
+    // as "nothing to tear down". Claim durably before mutating, or a
+    // zero-task install→activate→uninstall skips Apple cleanup (review
+    // 2026-08-18 round 4).
+    try {
+      await claimContainerRuntimeForMaintenance();
+    } catch (error) {
+      return {
+        ok: false,
+        error:
+          "Could not durably record the Apple container runtime claim " +
+          `before provisioning: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  }
+  const vol = await run(engine.command, ["volume", "create", ASDF_DATA_VOLUME]);
+  if (
+    vol.code !== 0 &&
+    !(engine.apple && vol.stderr.includes("already exists"))
+  ) {
     console.warn(
       `[host-agent] could not create asdf data volume (${ASDF_DATA_VOLUME}); ` +
         `continuing. ${vol.stderr.trim()}`,
@@ -391,7 +1174,6 @@ async function ensureStandardImageInner(): Promise<StandardImageResult> {
   let buildError: string | null = null;
   // Install only the optional engines the operator has configured; the flags
   // are build args AND part of the content hash (so a new login rebuilds).
-  const engines = configuredOptionalEngines();
   const engineArgs = [
     "--build-arg",
     `INSTALL_KIMI=${engines.kimi ? 1 : 0}`,
@@ -405,21 +1187,52 @@ async function ensureStandardImageInner(): Promise<StandardImageResult> {
   const contextHash = await hashBuildContext(
     `kimi=${engines.kimi ? 1 : 0};grok=${engines.grok ? 1 : 0};cursor=${engines.cursor ? 1 : 0};opencode=${engines.opencode ? 1 : 0}`,
   );
-  const inspect = await run("docker", [
-    "image",
-    "inspect",
-    "-f",
-    `{{index .Config.Labels "${CONTEXT_HASH_LABEL}"}}`,
-    STANDARD_IMAGE_TAG,
-  ]);
+  let inspect: RunResult;
+  let labeledHash: string | null = null;
+  if (engine.apple) {
+    // The Apple CLI has no --format; labels live in the single variant's OCI
+    // config. A malformed answer counts as "absent" and triggers a rebuild.
+    inspect = await run(engine.command, [
+      "image",
+      "inspect",
+      STANDARD_IMAGE_TAG,
+    ]);
+    if (inspect.code === 0) {
+      try {
+        const parsed = JSON.parse(inspect.stdout) as Array<{
+          variants?: Array<{
+            config?: { config?: { Labels?: Record<string, string> } };
+          }>;
+        }>;
+        labeledHash =
+          parsed[0]?.variants?.[0]?.config?.config?.Labels?.[
+            CONTEXT_HASH_LABEL
+          ] ?? "";
+      } catch {
+        inspect = { ...inspect, code: 1 };
+      }
+    }
+  } else {
+    inspect = await run("docker", [
+      "image",
+      "inspect",
+      "-f",
+      `{{index .Config.Labels "${CONTEXT_HASH_LABEL}"}}`,
+      STANDARD_IMAGE_TAG,
+    ]);
+    labeledHash = inspect.code === 0 ? inspect.stdout.trim() : null;
+  }
   if (inspect.code === null) {
     console.warn(
-      "[host-agent] docker unavailable; skipping standard image build. " +
-        "Tasks will fail until docker is running.",
+      "[host-agent] container runtime unavailable; skipping standard image " +
+        "build. Tasks will fail until it is running.",
     );
-    return { ok: false, error: "Docker is not available on this host." };
+    return {
+      ok: false,
+      error: "The container runtime is not available on this host.",
+    };
   }
-  const labeledHash = inspect.code === 0 ? inspect.stdout.trim() : null;
+  if (inspect.code !== 0) labeledHash = null;
   if (inspect.code === 0 && contextHash !== null && labeledHash === contextHash) {
     console.log(`[host-agent] standard image ${STANDARD_IMAGE_TAG} current`);
     imageReady = true;
@@ -434,7 +1247,7 @@ async function ensureStandardImageInner(): Promise<StandardImageResult> {
         ? `[host-agent] standard image ${STANDARD_IMAGE_TAG} stale (context changed) — rebuilding from ${context}`
         : `[host-agent] building standard image ${STANDARD_IMAGE_TAG} from ${context}`,
     );
-    const build = await run("docker", [
+    const build = await run(engine.command, [
       "build",
       "-t",
       STANDARD_IMAGE_TAG,
@@ -443,7 +1256,7 @@ async function ensureStandardImageInner(): Promise<StandardImageResult> {
         ? ["--label", `${CONTEXT_HASH_LABEL}=${contextHash}`]
         : []),
       context,
-    ]);
+    ], IMAGE_BUILD_TIMEOUT_MS);
     if (build.code === 0) {
       console.log(`[host-agent] built standard image ${STANDARD_IMAGE_TAG}`);
       imageReady = true;
@@ -461,15 +1274,165 @@ async function ensureStandardImageInner(): Promise<StandardImageResult> {
     }
   }
 
-  // 3. Reconcile the agent CLIs in the shared volume (it shadows the image's
-  //    shims, so a stale volume can be missing one — the claude-127 bug).
-  //    Upgrade FIRST, self-heal LAST: the upgrade's `rm -rf`+reinstall fallback
-  //    can leave a stale shim (a failed reinstall over a removed package), so
-  //    ensureVolumeAgentClis must be the final word — it verifies every bin
-  //    actually runs and repairs whatever the upgrade left broken.
+  // 3. Reconcile every Uai-owned writer under the volume-global flock. Lock
+  //    bootstrap/permission repair precedes the single upgrade→repair→proof
+  //    transaction so node-run task materializers can acquire legacy volumes.
   if (imageReady) {
-    await upgradeVolumeAgentClis();
-    await ensureVolumeAgentClis();
+    // Docker populates a fresh named volume from the image's directory
+    // content on first mount; the Apple runtime mounts it empty (ADR-106,
+    // found live 2026-08-15: every asdf plugin/shim the image bakes into
+    // /opt/asdf-data was missing, so CLI reconcile looped on "No such
+    // plugin: nodejs"). Replicate the Docker semantics explicitly: when the
+    // volume lacks the plugins tree, copy the image's /opt/asdf-data into it
+    // once, ownership preserved. Idempotent — the copied tree is the marker.
+    if (engine.apple) {
+      // Probe at a path the image does NOT contain: mounted over
+      // /opt/asdf-data, a silently-failed volume mount would expose the
+      // image's own baked tree and fake a "seeded" answer. At a neutral
+      // mountpoint the plugins tree can only come from the volume itself,
+      // and any mount failure lands on the safe side (reseeding is
+      // idempotent).
+      const seeded = await runMaintenanceContainer(engine, "seed-probe", [
+        "--rm",
+        "-v",
+        `${ASDF_DATA_VOLUME}:/uai-volume-probe:ro`,
+        STANDARD_IMAGE_TAG,
+        "/usr/bin/test",
+        "-d",
+        "/uai-volume-probe/plugins",
+      ], CLI_MAINTENANCE_TIMEOUT_MS);
+      // Only `/usr/bin/test`'s own exit 1 means "not seeded". Everything else
+      // — a host-side deadline kill (null), an in-container SIGTERM/SIGKILL
+      // (143/137: live 2026-08-17, a wedged apiserver let the probe run ten
+      // minutes before dying 143), or any CLI failure — answers neither way,
+      // and must never trigger a reseed of a volume that may be full and in
+      // use.
+      if (seeded.code !== 0 && seeded.code !== 1) {
+        return {
+          ok: false,
+          error:
+            "The container runtime did not answer while checking the shared " +
+            `runtime volume (probe exit ${seeded.code ?? "killed"}).`,
+        };
+      }
+      if (seeded.code === 0) {
+        console.log(
+          `[host-agent] shared runtime volume ${ASDF_DATA_VOLUME} is seeded`,
+        );
+      }
+      // The positive no-holder proof comes BEFORE every writable attachment
+      // — including the seeder. A doomed writable attach both fails the
+      // operation and can mint the corpse that wedges the apiserver, so a
+      // writer requires a positive `free`; `unknown` (unreadable inventory)
+      // must never read as permission.
+      const holders = await sharedVolumeHolders(engine);
+      if (seeded.code !== 0) {
+        if (holders !== "free") {
+          return {
+            ok: false,
+            error:
+              holders === "held"
+                ? `The shared runtime volume ${ASDF_DATA_VOLUME} is unseeded while task containers are running; it cannot be seeded safely until they stop.`
+                : "Could not determine whether task containers hold the shared runtime volume; retrying before any writable attachment.",
+          };
+        }
+        console.log(
+          `[host-agent] seeding ${ASDF_DATA_VOLUME} from the standard image (probe exit ${seeded.code}; Apple volumes mount empty)`,
+        );
+        const seed = await runMaintenanceContainer(engine, "seed", [
+          "--rm",
+          "--user",
+          "root",
+          "-v",
+          `${ASDF_DATA_VOLUME}:/uai-seed-target`,
+          STANDARD_IMAGE_TAG,
+          "/bin/sh",
+          "-c",
+          "cp -a /opt/asdf-data/. /uai-seed-target/ && chown -R node:node /uai-seed-target",
+        ], CLI_MAINTENANCE_TIMEOUT_MS);
+        if (seed.code !== 0) {
+          return {
+            ok: false,
+            error: `Could not seed the shared runtime volume from the standard image (exit ${seed.code ?? "spawn"}).`,
+          };
+        }
+      } else if (holders === "held") {
+        // Proof-first deferral: while running task containers hold the
+        // volume, a writable attach can only fail (and mint a corpse) —
+        // don't attempt it. The stderr-signature deferrals below remain as
+        // the backstop for a task appearing between this check and the
+        // attach.
+        if (await volumeReconcileProofExists()) {
+          console.log(
+            `[host-agent] shared runtime volume ${ASDF_DATA_VOLUME} is held by task containers; deferring maintenance (prior reconcile proof present)`,
+          );
+          return { ok: true };
+        }
+        // First-proof bootstrap. A host with no persisted proof (fresh file,
+        // or upgraded from a version whose proof write failed silently —
+        // live 2026-08-17 on 0.9.26) would otherwise be stuck in a ring: the
+        // proof needs a full reconcile, the reconcile needs the writable
+        // volume, and the volume stays held for as long as tasks run. The
+        // read-only CLI probe attaches fine next to tasks, and EXECUTING
+        // every agent CLI is the same positive evidence the full reconcile
+        // ends with — enough to defer on, and worth persisting as the proof.
+        const missing = await probeVolumeAgentClis();
+        if (missing !== null && missing.length === 0) {
+          await writeVolumeReconcileProof();
+          console.log(
+            `[host-agent] read-only agent-CLI probe passed while task containers hold ${ASDF_DATA_VOLUME}; recording the reconcile proof and deferring maintenance`,
+          );
+          return { ok: true };
+        }
+        // No proof and a failed probe, while tasks hold the volume: a
+        // writable attach here can only fail and mint a corpse, and simply
+        // retrying strands activation forever (review 2026-08-18 round 2 —
+        // recovery, which could settle the holders, runs only after
+        // maintenance succeeds). Ask the activation driver to lifecycle-stop
+        // the holder tasks (resumable) so the next attempt can repair the
+        // volume they cannot safely use anyway.
+        return {
+          ok: false,
+          error:
+            `The shared runtime volume ${ASDF_DATA_VOLUME} needs repair ` +
+            `(agent CLIs failed their probe${missing === null ? "" : `: ${missing.join(", ")} missing`}) ` +
+            "while running tasks hold it; stopping the holder tasks so maintenance can repair it.",
+          remedy: "stop-volume-holders",
+        };
+      } else if (holders === "unknown") {
+        return {
+          ok: false,
+          error:
+            "Could not determine whether task containers hold the shared runtime volume; retrying before any writable attachment.",
+        };
+      }
+    }
+    const lockPrepared = await prepareAsdfMaintenanceLock();
+    if (!lockPrepared) {
+      if (await volumeBusyDeferral(engine, lastMaintenanceStderr)) {
+        console.log(
+          `[host-agent] shared runtime volume ${ASDF_DATA_VOLUME} is held by running task containers; deferring maintenance (prior reconcile proof present)`,
+        );
+        return { ok: true };
+      }
+      return {
+        ok: false,
+        error: `Could not prepare shared runtime maintenance lock ${ASDF_MAINTENANCE_LOCK_PATH}.`,
+      };
+    }
+    if (!(await reconcileVolumeAgentClis())) {
+      if (await volumeBusyDeferral(engine, lastMaintenanceStderr)) {
+        console.log(
+          `[host-agent] shared runtime volume ${ASDF_DATA_VOLUME} is held by running task containers; deferring maintenance (prior reconcile proof present)`,
+        );
+        return { ok: true };
+      }
+      return {
+        ok: false,
+        error:
+          "Shared runtime maintenance failed; agent CLIs or Corepack did not pass execution proof.",
+      };
+    }
     return { ok: true };
   }
   return {