@moondeck/station 0.0.0-stage → 1.0.0

package/lib/standard-image.ts

@@ -0,0 +1,1697 @@
+/**
+ * Standard-image build pipeline (ADR-022 / docs/runtime.md).
+ *
+ * Every host builds exactly one standard image (`moondeck-standard:dev`) and
+ * caches it. `ensureStandardImage()` runs at startup and on the owned-host
+ * hourly maintenance schedule (local build failures back off):
+ *
+ *   1. `docker volume create moondeck-asdf-data` — the host-wide asdf data volume
+ *      that caches lazily-installed runtime versions across tasks (idempotent;
+ *      `docker volume create` is a no-op if the volume already exists).
+ *   2. `docker image inspect moondeck-standard:dev` — if it resolves, the image is
+ *      present and we skip the build. Otherwise `docker build` it from
+ *      `host-agent/images/standard/`.
+ *
+ * Best-effort: any failure (docker missing, daemon down, build error) is
+ * logged and swallowed so the host process still boots and serves tunnels.
+ * task-up surfaces the real error to the user if a build is genuinely needed.
+ */
+
+import { spawn } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  appleOneOffNeedsWatch,
+  appleOneOffRunArgs,
+  askRuntimeOwnerOnce,
+  newAppleOneOff,
+  settleAppleOneOff,
+  watchAppleOneOff,
+} from "./apple-one-off";
+import { recycleAppleRuntimeServices, type AppleRecycleOutcome } from "./apple-runtime-recycle";
+import { detectEngine } from "./engines";
+import { hasStoredEngineAccounts } from "./engine-accounts";
+import {
+  appleContainerRuntimeBinding,
+  claimContainerRuntimeForMaintenance,
+  containerRuntimeStandardAssetsRoot,
+  containerRuntimeStandardImageRoot,
+  pinnedContainerRuntimeProvider,
+  requestContainerRuntimeRecheck,
+} from "./container-runtime";
+import { KeyedPromiseTail } from "./keyed-promise-tail";
+import {
+  CONTEXT_HASH_LABEL,
+  hashStandardImageContext,
+  parseStandardImagePin,
+  STANDARD_IMAGE_PIN_BASENAME,
+  type StandardImagePin,
+  standardImagePullCommands,
+  standardImagePullDigest,
+} from "./standard-image-pin";
+import { sidecarMode } from "./sidecar";
+import { StandardImageCleanup, StandardImageBuildBackoff } from "./standard-image-cleanup";
+
+/** Pinned, host-wide constants (must match task-up.sh and the compose gen). */
+export const STANDARD_IMAGE_TAG = "moondeck-standard:dev";
+export const ASDF_DATA_VOLUME = "moondeck-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";
+
+/** Exact Codex CLI release exposed to task runtimes through the shared volume. */
+export const STANDARD_CODEX_CLI_VERSION = "0.164.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
+ * versions the cloud's task-creation picker hints; asdf will lazily install
+ * any of them on first use (docs/runtime.md). The first entry of each list is
+ * the root `/etc/.tool-versions` default baked into the image.
+ *
+ * KEEP IN SYNC with host-agent/images/standard/ (the asdf plugins and the
+ * root tool-versions). Treat that directory as authoritative for the numbers;
+ * this list is the advertisement surface.
+ */
+export const STANDARD_RUNTIMES: ReadonlyArray<{
+  kind: string;
+  availableVersions: string[];
+}> = [
+  {
+    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"] },
+  { kind: "rust", availableVersions: ["1.81.0"] },
+];
+
+/** A fresh, mutable copy of the advertised runtimes for the capability frame. */
+export function standardRuntimes(): Array<{
+  kind: string;
+  availableVersions: string[];
+}> {
+  return STANDARD_RUNTIMES.map((r) => ({
+    kind: r.kind,
+    availableVersions: [...r.availableVersions],
+  }));
+}
+
+/**
+ * Which OPTIONAL agent CLIs the operator has actually configured — so the
+ * image installs only those, not every engine on every host. Delegates to
+ * engines.ts detection so every connect flavor counts: kimi's copied cred
+ * file, grok's login file OR a pasted XAI_API_KEY, cursor's CURSOR_API_KEY
+ * (claude/codex are always baked). Folded into the build hash below, so
+ * connecting a new engine triggers a rebuild.
+ */
+export function configuredOptionalEngines(): {
+  kimi: boolean;
+  grok: boolean;
+  cursor: boolean;
+  opencode: boolean;
+} {
+  // A stored account (a workspace's, on a shared host; a labeled extra on an
+  // owned one) needs the CLI in the image just like the host's own sign-in
+  // does — without this a grok/cursor account existed but its tasks exited
+  // 127 for a missing binary.
+  const on = (kind: "kimi" | "grok" | "cursor" | "opencode"): boolean =>
+    detectEngine(kind) || hasStoredEngineAccounts(kind);
+  return {
+    kimi: on("kimi"),
+    grok: on("grok"),
+    cursor: on("cursor"),
+    opencode: on("opencode"),
+  };
+}
+
+type OptionalEngineConfiguration = ReturnType<
+  typeof configuredOptionalEngines
+>;
+
+function optionalEngineConfigurationKey(
+  engines: OptionalEngineConfiguration,
+): string {
+  return JSON.stringify(engines);
+}
+
+// Build args (which optional engines are installed) are part of the image
+// identity — a config change must invalidate the label so it rebuilds. The
+// walk-and-hash itself lives in standard-image-pin.ts so CI computes the
+// identical identity (ADR-114).
+function hashBuildContext(extra = ""): Promise<string | null> {
+  return hashStandardImageContext(standardImageDir(), extra);
+}
+
+/** The packaged digest pin (ADR-114) at `agent/images/standard-image.pin.json`,
+ * one level above the build context so it never perturbs the context hash.
+ * Absent in dev checkouts and npm installs — those keep the local build.
+ * `UAI_IMAGE_PULL=0` is the operator kill switch back to local semantics. */
+async function readStandardImagePin(): Promise<StandardImagePin | null> {
+  if (process.env.UAI_IMAGE_PULL === "0") return null;
+  let raw: string;
+  try {
+    raw = await readFile(
+      resolve(standardImageDir(), "..", STANDARD_IMAGE_PIN_BASENAME),
+      "utf8",
+    );
+  } catch {
+    return null;
+  }
+  const pin = parseStandardImagePin(raw);
+  if (pin === null) {
+    console.warn(
+      "[host-agent] packaged standard-image pin is malformed; using the local build path",
+    );
+  }
+  return pin;
+}
+
+/** 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;
+}
+
+const SHORT_DOCKER_TIMEOUT_MS = 30_000;
+const CLI_MAINTENANCE_TIMEOUT_MS = 10 * 60_000;
+// Overridable ceiling: the hard-coded 15 minutes looped a fanless Air forever
+// (live 2026-08-19 — every attempt died at 15:00 and the activation driver
+// silently restarted it). Slow hardware needs a bigger window, not a loop.
+const IMAGE_BUILD_TIMEOUT_MS = imageBuildTimeoutMs();
+function imageBuildTimeoutMs(): number {
+  const minutes = Number(process.env.UAI_IMAGE_BUILD_TIMEOUT_MINUTES ?? "");
+  if (Number.isFinite(minutes) && minutes >= 1) {
+    return Math.min(minutes, 240) * 60_000;
+  }
+  return 15 * 60_000;
+}
+const IMAGE_PULL_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 };
+}
+
+/** The most bytes of each stream a standard-image command keeps; the rest is
+ *  read and dropped, so a child that writes without end holds no more of the
+ *  runner's memory than this. */
+const RUN_CAPTURE_BYTES = 8 * 1024 * 1024;
+
+/** One stream, kept to at most RUN_CAPTURE_BYTES of its encoded bytes; the
+ *  runner's own diagnostics go through the same bound. */
+class BoundedCapture {
+  #chunks: Buffer[] = [];
+  #bytes = 0;
+  #lastByte: number | null = null;
+
+  add(chunk: Buffer | string): void {
+    const bytes = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+    if (bytes.length === 0 || this.#bytes >= RUN_CAPTURE_BYTES) return;
+    const kept = bytes.subarray(0, RUN_CAPTURE_BYTES - this.#bytes);
+    this.#chunks.push(kept);
+    this.#bytes += kept.length;
+    this.#lastByte = kept[kept.length - 1]!;
+  }
+
+  /** A line of the runner's own, on a line of its own. */
+  addLine(line: string): void {
+    this.add(`${this.#lastByte !== null && this.#lastByte !== 0x0a ? "\n" : ""}${line}`);
+  }
+
+  /** What it kept, as text that keeps the bound too: a character the
+   *  bound cut, or bytes that are not UTF-8, decode to a three-byte
+   *  replacement character, so past the bound the text ends at its last
+   *  whole character. */
+  text(): string {
+    const text = Buffer.concat(this.#chunks).toString("utf8");
+    if (Buffer.byteLength(text, "utf8") <= RUN_CAPTURE_BYTES) return text;
+    const encoded = Buffer.from(text, "utf8");
+    let end = RUN_CAPTURE_BYTES;
+    // Back to the first byte of the character the bound cuts.
+    while (end > 0 && (encoded[end]! & 0xc0) === 0x80) end -= 1;
+    return encoded.subarray(0, end).toString("utf8");
+  }
+}
+
+/** Run a command to completion, capturing stdio, at most RUN_CAPTURE_BYTES
+ * of each. 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) => {
+    const stdout = new BoundedCapture();
+    const stderr = new BoundedCapture();
+    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: stdout.text(), stderr: stderr.text() });
+    };
+    const timeoutTimer = setTimeout(() => {
+      stderr.addLine(`${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?.on("data", (chunk: Buffer) => {
+      stdout.add(chunk);
+    });
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr.add(chunk);
+    });
+    child.on("error", (err: Error) => {
+      stderr.add(err.message);
+      settle(null);
+    });
+    child.on("close", (code) => {
+      settle(code);
+    });
+  });
+}
+
+/** Narrow process-level seam for the timeout regression test. */
+export const runStandardImageCommandForTest = run;
+
+/** 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). So the container is named and marked Uai's
+ * (apple-one-off.ts), and a failed run is settled: its container proven
+ * gone, deleted until it is, the runtime's services recycled when it will
+ * not go; a run whose client never reported its end is watched a while
+ * longer for a container created late. 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 run reports a distinctive
+ * retryable failure. Within the runtime's current activation, the runtime
+ * services are first recycled in place (see apple-runtime-recycle.ts), and
+ * the activation recovers every task after, its retry loop re-running
+ * maintenance against the fresh runtime. Within an activation that is no
+ * longer current, nothing restarts the runtime: the current one is coming,
+ * with its own maintenance and recovery. Outside any (the hourly pass, a
+ * task's start, an engine's sign-in), nothing restarts the runtime either:
+ * its owner is asked to recheck it, whose activation does (#p2jdax).
+ */
+async function runMaintenanceContainer(
+  engine: { command: string; apple: boolean },
+  purpose: string,
+  argsAfterRun: string[],
+  timeoutMs: number,
+  activation: ActivationIsCurrent | null,
+): Promise<RunResult> {
+  if (!engine.apple) {
+    return run(engine.command, ["run", ...argsAfterRun], timeoutMs);
+  }
+  const oneOff = newAppleOneOff(purpose);
+  const { name } = oneOff;
+  const cli = (args: string[], cliTimeoutMs: number) => run(engine.command, args, cliTimeoutMs);
+  // The remedy outside activation, and for a watch (which outlives any
+  // activation): ask the runtime's owner, once for this run.
+  const askOwner = askRuntimeOwnerOnce(
+    requestContainerRuntimeRecheck,
+    `maintenance container ${name} found the Apple runtime wedged, or could not be removed`,
+  );
+  // The remedy within an activation: the runtime's services restarted, only
+  // while that activation is current.
+  const notCurrent = "its activation is no longer the current one";
+  const restart = async (): Promise<AppleRecycleOutcome> =>
+    activation?.() ? recycleAppleRuntimeServices({ cli }) : { recycled: false, reason: notCurrent };
+  let wedgedUnremedied = false;
+  let runSettled = false;
+  const running = run(
+    engine.command,
+    // Its labels are what authorize deleting this container later (here, by
+    // its run's token; in the recycle sweep, by Uai's) — a name alone is
+    // forgeable.
+    ["run", ...appleOneOffRunArgs(oneOff), ...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;
+    if (activation === null || !activation()) {
+      wedgedUnremedied = true;
+      const reason = activation === null ? (await askOwner()).reason : notCurrent;
+      return {
+        code: null,
+        stdout: "",
+        stderr: `apple container runtime is wedged; ${reason} — retry this operation`,
+      };
+    }
+    const outcome = await restart();
+    // 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) {
+    const watched = { cli, recycle: askOwner };
+    if (wedgedUnremedied) {
+      // Nothing can be deleted until a current activation has restarted the
+      // runtime: its name is only watched, and this pass (which that
+      // activation's own may wait behind) ends now.
+      void watchAppleOneOff(watched, oneOff, { lateCreation: true });
+      return result;
+    }
+    // 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): only a positive label proof
+    // authorizes deleting it, and an unobservable one is never recycled for.
+    const settled = await settleAppleOneOff(
+      { cli, recycle: activation ? restart : askOwner },
+      oneOff,
+    );
+    // Unproven, or its client never reported its end (the container may yet
+    // be created): watched until it is settled.
+    const lateCreation = result.code === null;
+    if (appleOneOffNeedsWatch(settled, lateCreation)) void watchAppleOneOff(watched, oneOff, { lateCreation });
+  }
+  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
+ * seeded before a CLI was added (or before a version bump) can be missing it —
+ * e.g. a stale volume with `codex` but no `claude`, which makes `claude` exit
+ * 127 in every task container. Reconciled on each host start.
+ */
+const VOLUME_AGENT_CLIS: {
+  bin: string;
+  pkg: string;
+  version: string;
+  expectedVersionOutput?: string;
+}[] = [
+  { bin: "claude", pkg: "@anthropic-ai/claude-code", version: "latest" },
+  {
+    bin: "codex",
+    pkg: "@openai/codex",
+    version: STANDARD_CODEX_CLI_VERSION,
+    expectedVersionOutput: `codex-cli ${STANDARD_CODEX_CLI_VERSION}`,
+  },
+];
+
+/**
+ * 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 probeVolumeAgentClis(activation: ActivationIsCurrent | null): Promise<string[] | null> {
+  const checks = VOLUME_AGENT_CLIS.map((cli) => {
+    const missing = `echo "UAI_MISSING:${cli.bin}"`;
+    if (cli.expectedVersionOutput === undefined) {
+      return `"${cli.bin}" --version >/dev/null 2>&1 || ${missing}`;
+    }
+    return (
+      `version="$("${cli.bin}" --version 2>/dev/null)" && ` +
+      `[ "$version" = "${cli.expectedVersionOutput}" ] || ${missing}`
+    );
+  }).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
+  // maps it to an installed exe — passes `command -v` (the file is present and
+  // executable) yet aborts at runtime with "unknown command: codex. Perhaps
+  // you have to reshim?" (exit 1). That made a broken codex/claude read as
+  // "present," so the self-heal skipped it and every task/resume spawn failed,
+  // restart after restart (live 2026-07-22). Running the bin is the only probe
+  // that catches a stale shim. `-w /home/node` so asdf resolves the node
+  // 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 runMaintenanceContainer(selectedEngine(), "cli-probe", [
+    "--rm",
+    "-w",
+    "/home/node",
+    "-v",
+    `${ASDF_DATA_VOLUME}:/opt/asdf-data:ro`,
+    STANDARD_IMAGE_TAG,
+    "/bin/bash",
+    "-c",
+    checks,
+  ], SHORT_DOCKER_TIMEOUT_MS, activation);
+  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 null;
+  }
+  return check.stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.startsWith("UAI_MISSING:"))
+    .map((l) => l.slice("UAI_MISSING:".length));
+}
+
+/**
+ * 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(activation: ActivationIsCurrent | null): 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",
+    "-v",
+    `${ASDF_DATA_VOLUME}:/opt/asdf-data`,
+    STANDARD_IMAGE_TAG,
+    "/usr/bin/timeout",
+    "--signal=TERM",
+    "--kill-after=10s",
+    `${ASDF_MAINTENANCE_INTERNAL_TIMEOUT_SECONDS}s`,
+    "/bin/bash",
+    "-c",
+    command,
+  ], CLI_MAINTENANCE_TIMEOUT_MS, activation);
+  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;
+}
+
+/**
+ * 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.
+ */
+/** 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(
+    (cli) => `${cli.pkg}@${cli.version}`,
+  ).join(" ");
+  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)"; ` +
+    `required_codex="${STANDARD_CODEX_CLI_VERSION}"; ` +
+    `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; ` +
+    // Legacy images could seed individual shims as root even though the
+    // directory itself was later repaired. asdf 0.14 then prints permission
+    // errors while reshim quietly leaves the old executable behind; task
+    // materialization can appear successful but the next CLI launch is stale
+    // or non-executable. The trusted root maintenance transaction repairs only
+    // the flat, regular-file shim set before dropping to node for every asdf
+    // mutation. Anything else is ambiguous volume content and fails closed.
+    `repair_shim_metadata() { ` +
+    `unsafe_shim_entry="$(/usr/bin/find "$shims_root" -xdev -mindepth 1 ` +
+    `-maxdepth 1 ! -type f -print -quit)"; ` +
+    `[ -z "$unsafe_shim_entry" ] || fail unsafe-shim-entry; ` +
+    `/usr/bin/find "$shims_root" -xdev -mindepth 1 -maxdepth 1 -type f ` +
+    `-exec /usr/bin/chown node:node -- {} + ` +
+    `|| fail repair-shim-owner; ` +
+    `/usr/bin/find "$shims_root" -xdev -mindepth 1 -maxdepth 1 -type f ` +
+    `-exec /usr/bin/chmod 0755 -- {} + ` +
+    `|| fail repair-shim-mode; }; ` +
+    `repair_shim_metadata; ` +
+    `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; ` +
+    `if [ "$b" = codex ] && ` +
+    `[ "$direct_version" != "codex-cli $required_codex" ]; then return 1; fi; ` +
+    `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'; version='latest';; ` +
+    `codex) pkg='@openai/codex'; scope='@openai'; package_name='codex'; ` +
+    `version="$required_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@$version" ${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 [ "$b" = codex ] && ` +
+    `[ "$version" != "codex-cli $required_codex" ]; then ` +
+    `echo "UAI_STILL_BROKEN:$b-version" >&2; failed=1; continue; fi; ` +
+    `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(activation: ActivationIsCurrent | null): Promise<boolean> {
+  const missingBefore = await probeVolumeAgentClis(activation);
+  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",
+    "-u",
+    "root",
+    "-w",
+    "/home/node",
+    "-v",
+    `${ASDF_DATA_VOLUME}:/opt/asdf-data`,
+    "-v",
+    `${standardImageCorepackVersionPath()}:/usr/local/share/uai/corepack-version:ro`,
+    STANDARD_IMAGE_TAG,
+    "/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, activation);
+  if (reconcile.code === 0) {
+    console.log(
+      `[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] 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,
+        codexVersion: STANDARD_CODEX_CLI_VERSION,
+        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; codexVersion?: unknown };
+    return (
+      raw?.schemaVersion === 1 &&
+      raw.codexVersion === STANDARD_CODEX_CLI_VERSION
+    );
+  } 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
+ * factory awaits this before spawning a CLI, so a boot-time resume never races
+ * the CLI auto-upgrade's brief remove-then-reinstall window — the "No codex
+ * executable found for nodejs X" (exit 2) resume failure. Post-boot it is
+ * already resolved, so the await is a no-op.
+ */
+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)}`,
+    );
+  }
+}
+
+/** ADR-133 sidecar mode: the agent CLIs are baked into the task machine's
+ * image, so there is no standard-image pass to wait on — boot declares them
+ * ready. Never called on a host that owns a container runtime. */
+export function declareAgentClisReady(): void {
+  markAgentClisReady();
+}
+
+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
+ * image inspect` fails or the content hash is stale. Never throws — returns
+ * `{ ok, error? }` so the caller decides (boot: fire-and-forget; taskUp:
+ * surface the reason). Resolves `agentClisReady` on every exit path.
+ */
+export function ensureStandardImage(
+  opts: {
+    maxAgeMs?: number;
+    /** Only the runtime's activation passes this, answering whether it is
+     *  still the current activation: within it alone, and only while it is
+     *  current, may a wedged Apple runtime's services be restarted, since
+     *  its recovery follows its maintenance. Every other pass asks the
+     *  runtime's owner for that activation instead (#p2jdax). */
+    withinActivation?: ActivationIsCurrent;
+  } = {},
+): Promise<StandardImageResult> {
+  // ADR-133 sidecar mode: a task machine has no container image to keep —
+  // its agent CLIs are baked into the machine image. Live 2026-09-10
+  // (hostless smoke 4): task-up refused with "could not prepare the host
+  // base image moondeck-standard:dev … Docker is not available".
+  if (sidecarMode()) {
+    markAgentClisReady();
+    return Promise.resolve({ ok: true });
+  }
+  // A task-up passes maxAgeMs: a pass that succeeded recently for the same
+  // engine configuration is reused instead of spending ~15 s spinning a
+  // maintenance container per task (live 2026-09-09: 16 s of every task
+  // start). The hourly schedule (main.ts) and the boot pass keep it fresh.
+  const engines = configuredOptionalEngines();
+  const key = optionalEngineConfigurationKey(engines);
+  const recent = lastOkByKey.get(key);
+  if (
+    opts.maxAgeMs !== undefined &&
+    recent !== undefined &&
+    Date.now() - recent.at <= opts.maxAgeMs
+  ) {
+    markAgentClisReady();
+    return Promise.resolve(recent.result);
+  }
+  // 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. The
+  // activation's pass never joins one begun outside it (which may not
+  // restart the runtime): it runs after it, as its own.
+  const activation = opts.withinActivation ?? null;
+  return ensureQueue.run(activation ? `activation:${key}` : key, () =>
+    ensureStandardImageInner(engines, activation)
+      .then((result) => {
+        if (result.ok) lastOkByKey.set(key, { at: Date.now(), result });
+        else lastOkByKey.delete(key);
+        return result;
+      })
+      .finally(() => {
+        // Always signal — even a docker-down bail — so agent spawns never hang
+        // waiting on a reconcile that will not happen this boot.
+        markAgentClisReady();
+      }),
+  );
+}
+
+/** Last successful pass per engine configuration (in-process). */
+const lastOkByKey = new Map<string, { at: number; result: StandardImageResult }>();
+
+/** The runtime's activation, asked whether it is still the current one: what
+ *  alone may restart a wedged Apple runtime's services (#p2jdax). */
+export type ActivationIsCurrent = () => boolean;
+
+/** Tests: forget every remembered pass. */
+export function resetStandardImageMemo(): void {
+  lastOkByKey.clear();
+  buildBackoff.clear();
+}
+
+const buildBackoff = new StandardImageBuildBackoff();
+const imageCleanup = new StandardImageCleanup(async () => {
+  const { env } = await import("./env");
+  return resolve(env.dataDir, "standard-image-seen.json");
+});
+
+/** The owned-host schedule (docs/agent-notes.md, "image maintenance"). */
+export const MAINTENANCE_INTERVAL_MS = 60 * 60_000;
+
+async function ensureStandardImageInner(
+  engines: OptionalEngineConfiguration,
+  activation: ActivationIsCurrent | null,
+): 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()}`,
+    );
+    // If docker itself is unavailable, the image step will also fail; bail
+    // early so we don't double-log a confusing build error.
+    if (vol.code === null) {
+      return { ok: false, error: "Docker is not available on this host." };
+    }
+  }
+
+  // 2. Ensure the image is built AND current. "Present" is not enough — a
+  //    Dockerfile change used to no-op forever because we only built when
+  //    inspect failed (found live 2026-07-08: ADR-053's baked packages never
+  //    landed). The build context is content-hashed into an image label;
+  //    a mismatch triggers a rebuild (layer cache keeps it cheap).
+  let imageReady = false;
+  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 engineArgs = [
+    "--build-arg",
+    `INSTALL_KIMI=${engines.kimi ? 1 : 0}`,
+    "--build-arg",
+    `INSTALL_GROK=${engines.grok ? 1 : 0}`,
+    "--build-arg",
+    `INSTALL_CURSOR=${engines.cursor ? 1 : 0}`,
+    "--build-arg",
+    `INSTALL_OPENCODE=${engines.opencode ? 1 : 0}`,
+  ];
+  const contextHash = await hashBuildContext(
+    `kimi=${engines.kimi ? 1 : 0};grok=${engines.grok ? 1 : 0};cursor=${engines.cursor ? 1 : 0};opencode=${engines.opencode ? 1 : 0}`,
+  );
+  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] container runtime unavailable; skipping standard image " +
+        "build. Tasks will fail until it is running.",
+    );
+    return {
+      ok: false,
+      error: "The container runtime is not available on this host.",
+    };
+  }
+  if (inspect.code !== 0) labeledHash = null;
+
+  // ADR-114: when the payload pins a prebuilt digest, the pin decides image
+  // identity — the label must equal the PIN's context hash (the CI superset
+  // hash, not this host's per-config hash, which would disagree by design
+  // and rebuild forever). Any pull-path failure falls through to the local
+  // build below, so offline and registry-down hosts behave exactly as today.
+  const previousImageId = engine.apple ? null : await imageCleanup.observe(run);
+  const pin = await readStandardImagePin();
+  if (pin !== null) {
+    if (inspect.code === 0 && labeledHash === pin.contextHash) {
+      console.log(
+        `[host-agent] standard image ${STANDARD_IMAGE_TAG} current (pinned)`,
+      );
+      imageReady = true;
+    } else {
+      const pullDigest = standardImagePullDigest(pin);
+      console.log(
+        `[host-agent] pulling standard image ${pin.ref}@${pullDigest}`,
+      );
+      const commands = standardImagePullCommands(
+        pin,
+        STANDARD_IMAGE_TAG,
+        engine.apple,
+      );
+      const pulled = await run(
+        engine.command,
+        commands.pull,
+        IMAGE_PULL_TIMEOUT_MS,
+      );
+      if (pulled.code === 0) {
+        const tagged = await run(engine.command, commands.tag);
+        if (tagged.code === 0) {
+          console.log(
+            `[host-agent] pulled standard image ${STANDARD_IMAGE_TAG} (${pullDigest.slice(0, 19)}…)`,
+          );
+          imageReady = true;
+        } else {
+          console.warn(
+            "[host-agent] pulled standard image could not be tagged; " +
+              `falling back to a local build. ${tagged.stderr.trim()}`,
+          );
+        }
+      } else {
+        console.warn(
+          "[host-agent] standard image pull failed; falling back to a " +
+            `local build. ${pulled.stderr.trim()}`,
+        );
+      }
+    }
+  }
+
+  if (imageReady) {
+    // Pinned image adopted — skip the local-hash decision entirely.
+  } else if (inspect.code === 0 && contextHash !== null && labeledHash === contextHash) {
+    console.log(`[host-agent] standard image ${STANDARD_IMAGE_TAG} current`);
+    imageReady = true;
+  } else if (inspect.code === 0 && contextHash === null) {
+    // Can't hash (packaged install without the context?) — keep the image.
+    console.log(`[host-agent] standard image ${STANDARD_IMAGE_TAG} present`);
+    imageReady = true;
+  } else {
+    const context = standardImageDir();
+    const buildKey = `${contextHash ?? "unavailable"}:${JSON.stringify(engines)}:${pin?.contextHash ?? "local"}`;
+    const deferred = engine.apple || labeledHash === null ? null : buildBackoff.remaining(buildKey);
+    if (!deferred) {
+      console.log(
+        inspect.code === 0
+          ? `[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 = deferred ? { code: 1, stdout: "", stderr: `${deferred.error}\nStandard image build deferred until ${new Date(deferred.retryAt).toISOString()}.` } : await run(engine.command, [
+      "build",
+      ...(engine.apple ? [] : ["--force-rm"]),
+      "-t",
+      STANDARD_IMAGE_TAG,
+      ...engineArgs,
+      ...(contextHash !== null
+        ? ["--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;
+      buildBackoff.clear();
+    } else {
+      buildError =
+        build.stderr.trim() ||
+        `docker build exited ${build.code ?? "spawn error"}`;
+      if (!deferred && !engine.apple) buildBackoff.failed(buildKey, buildError);
+      console.warn(
+        deferred ? `[host-agent] ${buildError}` :
+        `[host-agent] standard image build failed (exit ${build.code ?? "spawn"}); ` +
+          "continuing. Tasks needing the image will surface this error.\n" +
+          buildError,
+      );
+      // A stale-but-working image is better than none.
+      imageReady = labeledHash !== null;
+    }
+  }
+
+  // Revisit ids durably observed under the standard tag across restarts.
+  // Inherited labels never authorize sweeping task/compose images.
+  if (imageReady && !engine.apple) await imageCleanup.sweep(run, previousImageId);
+
+  // 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) {
+    // 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, activation);
+      // 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, activation);
+        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(activation);
+        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(activation);
+    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: `${buildError ? `${buildError} ` : ""}Could not prepare shared runtime maintenance lock ${ASDF_MAINTENANCE_LOCK_PATH}.`,
+      };
+    }
+    if (!(await reconcileVolumeAgentClis(activation))) {
+      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:
+          `${buildError ? `${buildError} ` : ""}Shared runtime maintenance failed; agent CLIs or Corepack did not pass execution proof.`,
+      };
+    }
+    return { ok: true };
+  }
+  return {
+    ok: false,
+    error:
+      buildError ??
+      "the standard base image (moondeck-standard:dev) is not built and no build error was captured.",
+  };
+}