@runuai/host 0.9.13 → 0.9.42

package/images/standard/container/uai-materialize-runtimes

@@ -0,0 +1,1527 @@
+#!/bin/bash
+# Materialize project-declared runtimes into /opt/asdf-data.
+#
+# Host contract: run as `node` with /opt/asdf-data writable. On Docker that
+# is the shared host-wide volume, mounted read-write in a dedicated
+# maintenance container with /workspace read-only. On the Apple runtime
+# (ADR-108) this runs INSIDE the app container, where /opt/asdf-data is the
+# task's in-guest overlay (shared read-only lower + task-private upper) —
+# installs land in the task's own layer and the shared volume is never
+# written on the task path. The host supplies the total operation timeout;
+# this executable supplies the bounded volume lock (cross-process on Docker,
+# per-task on the overlay, which is exactly the exclusion each case needs).
+#
+# UAI_MATERIALIZE_VERIFY_ONLY=1 (ADR-106): the same validation and positive
+# execution proofs with ZERO volume mutations — no install, no repair, no
+# reshim, no Corepack preparation — against /opt/asdf-data mounted READ-ONLY.
+# Apple block volumes refuse a writable attach while any task container holds
+# them, so a task starting next to running tasks can only verify; the host
+# escalates to the writable pass when this one reports something missing.
+# Every mutation below is individually gated so a verify pass that would need
+# one fails loudly instead of writing.
+
+set -euo pipefail
+
+readonly WORKSPACE=/workspace
+readonly PROJECT_ALLOWLIST=/run/uai/runtime-projects
+readonly COREPACK_VERSION_FILE=/usr/local/share/uai/corepack-version
+readonly ASDF_SH=/opt/asdf/asdf.sh
+readonly ASDF_DATA=/opt/asdf-data
+readonly LOCK_PATH="$ASDF_DATA/.uai-maintenance.lock"
+readonly CONTROL_PATH=/opt/asdf/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+readonly APP_PATH="$ASDF_DATA/shims:$CONTROL_PATH"
+readonly FLOCK_BIN=/usr/bin/flock
+readonly REALPATH_BIN=/usr/bin/realpath
+readonly RM_BIN=/usr/bin/rm
+readonly LOCK_WAIT_SECONDS=300
+readonly PNPM_FALLBACK_VERSION=10.15.0
+readonly YARN_FALLBACK_VERSION=4.9.2
+readonly NPM_REGISTRY=https://registry.npmjs.org/
+readonly NPM_USERCONFIG=/dev/null
+readonly NPM_GLOBALCONFIG=/dev/uai-empty-npmrc
+readonly MAX_ALLOWLIST_BYTES=1048576
+readonly MAX_MANIFEST_BYTES=65536
+
+log() {
+  printf 'uai-materialize-runtimes: %s\n' "$*" >&2
+}
+
+fail() {
+  log "error: $*"
+  exit 1
+}
+
+if [ "$#" -ne 0 ]; then
+  fail "this host-controlled executable accepts no arguments"
+fi
+readonly VERIFY_ONLY="${UAI_MATERIALIZE_VERIFY_ONLY:-0}"
+case "$VERIFY_ONLY" in
+  0|1) ;;
+  *) fail "UAI_MATERIALIZE_VERIFY_ONLY must be 0 or 1" ;;
+esac
+export HOME=/home/node
+export ASDF_DIR=/opt/asdf
+export ASDF_DATA_DIR="$ASDF_DATA"
+export ASDF_CONFIG_FILE=/dev/null
+export ASDF_DEFAULT_TOOL_VERSIONS_FILENAME=.tool-versions
+export PATH="$CONTROL_PATH"
+export COREPACK_DEFAULT_TO_LATEST=0
+export COREPACK_ENABLE_AUTO_PIN=0
+export COREPACK_ENABLE_DOWNLOAD_PROMPT=0
+export COREPACK_ENV_FILE=0
+export COREPACK_ENABLE_PROJECT_SPEC=1
+export COREPACK_ENABLE_STRICT=1
+export COREPACK_ENABLE_UNSAFE_CUSTOM_URLS=0
+export COREPACK_INTEGRITY_CHECK=1
+export COREPACK_NPM_REGISTRY=https://registry.npmjs.org
+unset NODE_OPTIONS NPM_CONFIG_PREFIX NPM_CONFIG_REGISTRY \
+  NPM_CONFIG_USERCONFIG NPM_CONFIG_GLOBALCONFIG \
+  npm_config_prefix npm_config_registry npm_config_userconfig \
+  npm_config_globalconfig
+unset COREPACK_ENABLE_NETWORK
+if [ -L "$COREPACK_VERSION_FILE" ] || [ ! -f "$COREPACK_VERSION_FILE" ]; then
+  fail "$COREPACK_VERSION_FILE must be a regular, non-symbolic-link host asset"
+fi
+corepack_version=$(sed -n '1p' "$COREPACK_VERSION_FILE")
+[[ "$corepack_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] \
+  || fail "$COREPACK_VERSION_FILE does not contain a trusted exact version"
+if ! printf '%s\n' "$corepack_version" \
+  | cmp -s - "$COREPACK_VERSION_FILE"; then
+  fail "$COREPACK_VERSION_FILE must contain exactly one canonical version line"
+fi
+readonly COREPACK_VERSION=$corepack_version
+unset corepack_version
+if [ "$(id -un)" != node ]; then
+  fail "must run as the node user"
+fi
+if [ ! -d "$WORKSPACE" ]; then
+  fail "$WORKSPACE is missing (the host must mount the task workspace read-only)"
+fi
+if [ -e "$WORKSPACE/.tool-versions" ] || [ -L "$WORKSPACE/.tool-versions" ]; then
+  fail "$WORKSPACE/.tool-versions is forbidden because it is outside the selected-project authority"
+fi
+if [ ! -r "$ASDF_SH" ]; then
+  fail "asdf is unavailable at $ASDF_SH"
+fi
+if [ "$VERIFY_ONLY" = 1 ]; then
+  if [ ! -d "$ASDF_DATA" ] || [ ! -r "$ASDF_DATA" ]; then
+    fail "$ASDF_DATA is not a readable shared asdf volume"
+  fi
+elif [ ! -d "$ASDF_DATA" ] || [ ! -w "$ASDF_DATA" ]; then
+  fail "$ASDF_DATA is not a writable shared asdf volume"
+fi
+[ ! -e "$NPM_GLOBALCONFIG" ] \
+  || fail "trusted empty npm config path $NPM_GLOBALCONFIG unexpectedly exists"
+[ -x "$FLOCK_BIN" ] || fail "flock is unavailable at $FLOCK_BIN"
+[ -x "$REALPATH_BIN" ] || fail "realpath is unavailable at $REALPATH_BIN"
+[ -x "$RM_BIN" ] || fail "rm is unavailable at $RM_BIN"
+
+declare -a projects=()
+declare -a manifests=()
+# `/workspace` also carries control/shared directories such as `.uai` and
+# `files`, so filesystem discovery cannot prove the complete selected-project
+# set. The host binds its persisted selection as a fixed, read-only allowlist.
+# Snapshot a bounded prefix before parsing so a read error cannot look like a
+# clean EOF or silently produce a partial proof set.
+if [ -L "$PROJECT_ALLOWLIST" ] || [ ! -f "$PROJECT_ALLOWLIST" ]; then
+  fail "$PROJECT_ALLOWLIST must be a regular, non-symbolic-link host allowlist"
+fi
+allowlist_snapshot=$(mktemp)
+cleanup() {
+  rm -f -- "$allowlist_snapshot"
+}
+trap cleanup EXIT
+if ! dd if="$PROJECT_ALLOWLIST" of="$allowlist_snapshot" \
+  bs=$((MAX_ALLOWLIST_BYTES + 1)) count=1 status=none; then
+  fail "could not read $PROJECT_ALLOWLIST"
+fi
+allowlist_bytes=$(wc -c < "$allowlist_snapshot")
+[ "$allowlist_bytes" -gt 0 ] \
+  || fail "$PROJECT_ALLOWLIST must name at least one selected project"
+[ "$allowlist_bytes" -le "$MAX_ALLOWLIST_BYTES" ] \
+  || fail "$PROJECT_ALLOWLIST exceeds the ${MAX_ALLOWLIST_BYTES}-byte limit"
+if LC_ALL=C grep -q '[[:cntrl:]]' "$allowlist_snapshot"; then
+  fail "$PROJECT_ALLOWLIST contains a control character"
+fi
+
+declare -A seen_projects=()
+while IFS= read -r slug || [ -n "$slug" ]; do
+  [[ "$slug" =~ ^[a-z0-9-]{1,64}$ ]] \
+    || fail "$PROJECT_ALLOWLIST contains an invalid project slug"
+  [ -z "${seen_projects[$slug]:-}" ] \
+    || fail "$PROJECT_ALLOWLIST contains duplicate project slug '$slug'"
+  seen_projects[$slug]=1
+  entry="$WORKSPACE/$slug"
+  if [ -L "$entry" ] || [ ! -d "$entry" ]; then
+    fail "selected project '$slug' is not a real one-level workspace directory"
+  fi
+  if [ -L "$entry/.git" ] \
+    || { [ ! -f "$entry/.git" ] && [ ! -d "$entry/.git" ]; }; then
+    fail "selected project '$slug' lacks a regular, non-symbolic-link Git marker"
+  fi
+  projects+=("$entry")
+done < "$allowlist_snapshot"
+[ "${#projects[@]}" -gt 0 ] \
+  || fail "$PROJECT_ALLOWLIST did not contain a selected project"
+
+for project in "${projects[@]}"; do
+  manifest="$project/.tool-versions"
+  [ -e "$manifest" ] || [ -L "$manifest" ] || continue
+  if [ -L "$manifest" ] || [ ! -f "$manifest" ]; then
+    fail "$manifest must be a regular, non-symbolic-link .tool-versions file"
+  fi
+  manifests+=("$manifest")
+done
+
+trim_spaces() {
+  local value=$1
+  value="${value#"${value%%[! ]*}"}"
+  value="${value%"${value##*[! ]}"}"
+  printf '%s' "$value"
+}
+
+reject_dot_segments() {
+  local value=$1 manifest=$2 line_number=$3
+  case "/$value/" in
+    *'/../'*|*'/./'*|*'//'*)
+      fail "$manifest:$line_number contains an unsafe version path segment"
+      ;;
+  esac
+}
+
+validate_version() {
+  local version=$1 project=$2 manifest=$3 line_number=$4
+  local suffix resolved project_resolved
+
+  case "$version" in
+    system)
+      return
+      ;;
+    path:*)
+      suffix=${version#path:}
+      [ -n "$suffix" ] || fail "$manifest:$line_number has an empty path: version"
+      case "$suffix" in
+        /*|'~'*)
+          fail "$manifest:$line_number path: versions must stay inside their project"
+          ;;
+      esac
+      resolved=$(cd "$project" && "$REALPATH_BIN" -e -- "$suffix" 2>/dev/null) \
+        || fail "$manifest:$line_number path:$suffix does not resolve"
+      project_resolved=$("$REALPATH_BIN" -e -- "$project") \
+        || fail "$manifest:$line_number project directory does not resolve"
+      [ -d "$resolved" ] \
+        || fail "$manifest:$line_number path:$suffix is not a directory"
+      case "$resolved" in
+        "$project_resolved"|"$project_resolved"/*) ;;
+        *) fail "$manifest:$line_number path:$suffix escapes its project" ;;
+      esac
+      return
+      ;;
+    ref:*)
+      suffix=${version#ref:}
+      [ -n "$suffix" ] || fail "$manifest:$line_number has an empty ref: version"
+      case "$suffix" in
+        */*)
+          fail "$manifest:$line_number ref: versions must use one cache path segment"
+          ;;
+      esac
+      [[ "$suffix" =~ ^[[:alnum:]][[:alnum:].+_@/-]*$ ]] \
+        || fail "$manifest:$line_number has a malformed ref: version"
+      reject_dot_segments "$suffix" "$manifest" "$line_number"
+      return
+      ;;
+  esac
+
+  case "$version" in
+    ref-*)
+      # asdf 0.14.1 stores `ref:foo` at `ref-foo`; accepting a normal
+      # `ref-foo` selector would alias the same destructive repair target.
+      fail "$manifest:$line_number normal versions may not use the reserved ref- prefix"
+      ;;
+    */*)
+      # `foo` and `foo/bar` would be ancestor/descendant cache entries; a
+      # repair of the former could delete the latter.
+      fail "$manifest:$line_number managed versions must use one cache path segment"
+      ;;
+  esac
+  [[ "$version" =~ ^[[:alnum:]][[:alnum:].+_@/-]*$ ]] \
+    || fail "$manifest:$line_number has a malformed version '$version'"
+  reject_dot_segments "$version" "$manifest" "$line_number"
+}
+
+# Parse and validate the complete manifest before passing any field to asdf.
+# ASDF remains the resolution authority; this parser only rejects shapes that
+# are ambiguous or could be interpreted as command/path injection.
+validate_manifest() {
+  local manifest=$1 project line line_number=0 tool version bytes
+  local -a fields=()
+  local -A seen_tools=()
+
+  project=$(dirname "$manifest")
+  bytes=$(wc -c < "$manifest")
+  [ "$bytes" -le "$MAX_MANIFEST_BYTES" ] \
+    || fail "$manifest exceeds the ${MAX_MANIFEST_BYTES}-byte limit"
+  if LC_ALL=C grep -q '[[:cntrl:]]' "$manifest"; then
+    fail "$manifest contains a control character (tabs and CRLF are not accepted)"
+  fi
+
+  while IFS= read -r line || [ -n "$line" ]; do
+    line_number=$((line_number + 1))
+    line=${line%%#*}
+    line=$(trim_spaces "$line")
+    [ -n "$line" ] || continue
+    read -r -a fields <<< "$line"
+    [ "${#fields[@]}" -ge 2 ] \
+      || fail "$manifest:$line_number must declare a tool and at least one version"
+    tool=${fields[0]}
+    [[ "$tool" =~ ^[a-z0-9][a-z0-9_-]*$ ]] \
+      || fail "$manifest:$line_number has a malformed tool name '$tool'"
+    case "$tool" in
+      nodejs|python|golang|ruby|rust) ;;
+      pnpm|yarn)
+        # Not asdf plugins here: package managers are Corepack's domain
+        # (live 2026-08-17 — the asdf-pnpm convention is common enough that
+        # refusing it broke a real monorepo). One plain pinned version;
+        # project_package_manager consumes it below.
+        [ "${#fields[@]}" -eq 2 ] \
+          || fail "$manifest:$line_number must pin exactly one $tool version"
+        [[ "${fields[1]}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]] \
+          || fail "$manifest:$line_number must pin an exact $tool version (Corepack manages package managers)"
+        ;;
+      *) fail "$manifest:$line_number requests unsupported asdf plugin '$tool'" ;;
+    esac
+    [ -z "${seen_tools[$tool]:-}" ] \
+      || fail "$manifest:$line_number declares '$tool' more than once"
+    seen_tools[$tool]=1
+    case "$tool" in
+      pnpm|yarn) continue ;;
+    esac
+    for version in "${fields[@]:1}"; do
+      validate_version "$version" "$project" "$manifest" "$line_number"
+    done
+  done < "$manifest"
+}
+
+# The pnpm/yarn pin from a project's .tool-versions, if any — the asdf-world
+# spelling of what package.json's packageManager states. Corepack authority
+# order: packageManager field, then this, then lockfile fallback.
+tool_versions_package_manager() {
+  local project=$1 line line_number=0
+  local -a fields=()
+  TOOL_VERSIONS_PM_MANAGER=""
+  TOOL_VERSIONS_PM_VERSION=""
+  [ -f "$project/.tool-versions" ] || return 0
+  while IFS= read -r line || [ -n "$line" ]; do
+    line_number=$((line_number + 1))
+    line=${line%%#*}
+    line=$(trim_spaces "$line")
+    [ -n "$line" ] || continue
+    read -r -a fields <<< "$line"
+    case "${fields[0]}" in
+      pnpm|yarn)
+        TOOL_VERSIONS_PM_MANAGER=${fields[0]}
+        TOOL_VERSIONS_PM_VERSION=${fields[1]:-}
+        return 0
+        ;;
+    esac
+  done < "$project/.tool-versions"
+}
+
+for manifest in "${manifests[@]}"; do
+  validate_manifest "$manifest"
+done
+
+# Do not inherit a derived image's ASDF_<TOOL>_VERSION overrides: the checked
+# manifest mounted by the host is the authority for this operation.
+unset_tool_override() {
+  local tool=$1 variable
+  variable="ASDF_$(printf '%s' "$tool" | tr '[:lower:]-' '[:upper:]_')_VERSION"
+  unset "$variable"
+}
+
+for baked_tool in nodejs python golang ruby rust; do
+  unset_tool_override "$baked_tool"
+done
+
+project_package_manager() {
+  local project=$1 spec="" manager="" is_fallback=0
+  local has_dev_engines_manager=0 has_supported_package_manager=0
+  PROJECT_PACKAGE_MANAGER=""
+  PROJECT_PACKAGE_MANAGER_SPEC=""
+  PROJECT_PACKAGE_MANAGER_IS_FALLBACK=0
+
+  if [ -f "$project/package.json" ]; then
+    jq -e 'type == "object"' "$project/package.json" >/dev/null 2>&1 \
+      || fail "$(basename "$project") has an invalid package.json"
+    spec=$(jq -r \
+      'if (.packageManager | type) == "string" then .packageManager else "" end' \
+      "$project/package.json")
+    manager=${spec%%@*}
+    case "$manager" in
+      pnpm|yarn) has_supported_package_manager=1 ;;
+    esac
+    if jq -e \
+      '(.devEngines? | type) == "object" and (.devEngines | has("packageManager"))' \
+      "$project/package.json" >/dev/null; then
+      has_dev_engines_manager=1
+    fi
+    if [ "$has_dev_engines_manager" -eq 1 ] \
+      && [ "$has_supported_package_manager" -ne 1 ]; then
+      fail "$(basename "$project") devEngines.packageManager requires an exact safe pnpm/yarn packageManager field"
+    fi
+  fi
+  if [ -z "$manager" ]; then
+    # The asdf-world pin (`pnpm 9.12.0` in .tool-versions) beats the generic
+    # lockfile fallback: it names an exact version the project chose.
+    tool_versions_package_manager "$project"
+    if [ -n "$TOOL_VERSIONS_PM_MANAGER" ]; then
+      manager=$TOOL_VERSIONS_PM_MANAGER
+      spec="$manager@$TOOL_VERSIONS_PM_VERSION"
+      is_fallback=1
+    fi
+  else
+    tool_versions_package_manager "$project"
+    if [ -n "$TOOL_VERSIONS_PM_MANAGER" ] \
+      && [ "${spec%%+*}" != "$TOOL_VERSIONS_PM_MANAGER@$TOOL_VERSIONS_PM_VERSION" ]; then
+      log "$(basename "$project"): package.json packageManager ($spec) wins over .tool-versions ($TOOL_VERSIONS_PM_MANAGER $TOOL_VERSIONS_PM_VERSION)"
+    fi
+  fi
+  if [ -z "$manager" ]; then
+    if [ -f "$project/pnpm-lock.yaml" ]; then
+      manager=pnpm
+      spec="pnpm@$PNPM_FALLBACK_VERSION"
+      is_fallback=1
+    elif [ -f "$project/yarn.lock" ]; then
+      manager=yarn
+      spec="yarn@$YARN_FALLBACK_VERSION"
+      is_fallback=1
+    fi
+  fi
+  case "$manager" in
+    pnpm|yarn)
+      if ! [[ "$spec" =~ ^(pnpm|yarn)@[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?(\+sha(224|256|384|512)\.[0-9A-Za-z_+/=-]+)?$ ]]; then
+        fail "$(basename "$project") packageManager must pin an exact safe $manager version"
+      fi
+      PROJECT_PACKAGE_MANAGER=$manager
+      PROJECT_PACKAGE_MANAGER_SPEC=$spec
+      PROJECT_PACKAGE_MANAGER_IS_FALLBACK=$is_fallback
+      ;;
+  esac
+}
+
+tool_executable() {
+  case "$1" in
+    nodejs) printf node ;;
+    python) printf python ;;
+    golang) printf go ;;
+    ruby) printf ruby ;;
+    rust) printf rustc ;;
+    *) return 1 ;;
+  esac
+}
+
+selected_executable() {
+  local tool=$1 version=$2 project=$3 executable=$4 variable
+  SELECTED_EXECUTABLE=""
+  case "$version" in
+    system)
+      SELECTED_EXECUTABLE=$(PATH="$CONTROL_PATH" command -v "$executable" 2>/dev/null) \
+        || return 1
+      ;;
+    *)
+      # The plugin, not Uai, owns executable layout (golang includes both
+      # `bin` and `go/bin`). Path selections are explicitly reshimmed under the
+      # shared lock, so ASDF can resolve that plugin-aware layout without
+      # writing to the external tree itself.
+      variable="ASDF_$(printf '%s' "$tool" | tr '[:lower:]-' '[:upper:]_')_VERSION"
+      SELECTED_EXECUTABLE=$(cd "$project" && env "$variable=$version" \
+        asdf which "$executable" 2>/dev/null) \
+        || return 1
+      ;;
+  esac
+}
+
+run_tool_version_probe() {
+  local tool=$1 executable=$2 project=$3 output
+  TOOL_VERSION_OUTPUT=""
+  case "$tool" in
+    golang)
+      output=$(cd "$project" && PATH="$CONTROL_PATH" \
+        "$executable" version 2>&1) || return 1
+      ;;
+    *)
+      output=$(cd "$project" && PATH="$CONTROL_PATH" \
+        "$executable" --version 2>&1) || return 1
+      ;;
+  esac
+  TOOL_VERSION_OUTPUT=${output%%$'\n'*}
+  [ -n "$TOOL_VERSION_OUTPUT" ]
+}
+
+resolve_app_shim() {
+  local executable=$1 resolved
+  APP_SHIM=""
+  resolved=$(PATH="$APP_PATH" command -v "$executable" 2>/dev/null) \
+    || return 1
+  [ "$resolved" = "$ASDF_DATA/shims/$executable" ] \
+    || return 1
+  [ ! -L "$resolved" ] && [ -f "$resolved" ] && [ -x "$resolved" ] \
+    || return 1
+  APP_SHIM=$resolved
+}
+
+run_tool_shim_version_probe() {
+  local tool=$1 executable=$2 project=$3 output
+  TOOL_VERSION_OUTPUT=""
+  resolve_app_shim "$executable" || return 1
+  # ASDF shims use `#!/usr/bin/env bash`; execute the already-resolved shim
+  # with the control PATH so another shared `bash` shim cannot intercept it.
+  case "$tool" in
+    golang)
+      output=$(cd "$project" && PATH="$CONTROL_PATH" \
+        "$APP_SHIM" version 2>&1) || return 1
+      ;;
+    *)
+      output=$(cd "$project" && PATH="$CONTROL_PATH" \
+        "$APP_SHIM" --version 2>&1) || return 1
+      ;;
+  esac
+  TOOL_VERSION_OUTPUT=${output%%$'\n'*}
+  [ -n "$TOOL_VERSION_OUTPUT" ]
+}
+
+run_node_shim_probe() {
+  local project=$1 node_version=$2 executable=$3
+  shift 3
+  resolve_app_shim "$executable" || return 1
+  (cd "$project" && PATH="$CONTROL_PATH" \
+    ASDF_NODEJS_VERSION="$node_version" "$APP_SHIM" "$@")
+}
+
+# BEGIN UAI_MANAGED_VERSION_PROOF
+managed_executable_is_contained() {
+  local version=$1 executable=$2 real_executable
+  case "$version" in
+    system|path:*) return 0 ;;
+  esac
+  [ -n "${MANAGED_INSTALL_PATH:-}" ] || return 1
+  [ -f "$executable" ] && [ -x "$executable" ] || return 1
+  real_executable=$("$REALPATH_BIN" -e -- "$executable" 2>/dev/null) || return 1
+  case "$real_executable" in
+    "$MANAGED_INSTALL_PATH"/*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+normalize_tool_version_output() {
+  local tool=$1 output=$2
+  NORMALIZED_TOOL_VERSION=""
+  case "$tool" in
+    nodejs)
+      [[ "$output" =~ ^v([^[:space:]]+) ]] || return 1
+      NORMALIZED_TOOL_VERSION=${BASH_REMATCH[1]}
+      ;;
+    python)
+      [[ "$output" =~ ^Python[[:space:]]+([^[:space:]]+) ]] || return 1
+      NORMALIZED_TOOL_VERSION=${BASH_REMATCH[1]}
+      ;;
+    golang)
+      [[ "$output" =~ ^go[[:space:]]+version[[:space:]]+go([^[:space:]]+) ]] \
+        || return 1
+      NORMALIZED_TOOL_VERSION=${BASH_REMATCH[1]}
+      ;;
+    ruby)
+      [[ "$output" =~ ^ruby[[:space:]]+([^[:space:]]+) ]] || return 1
+      NORMALIZED_TOOL_VERSION=${BASH_REMATCH[1]}
+      if [[ "$NORMALIZED_TOOL_VERSION" =~ ^([0-9]+\.[0-9]+\.[0-9]+)p[0-9]+$ ]]; then
+        NORMALIZED_TOOL_VERSION=${BASH_REMATCH[1]}
+      fi
+      ;;
+    rust)
+      [[ "$output" =~ ^rustc[[:space:]]+([^[:space:]]+) ]] || return 1
+      NORMALIZED_TOOL_VERSION=${BASH_REMATCH[1]}
+      ;;
+    *) return 1 ;;
+  esac
+}
+
+tool_selection_requires_exact_output() {
+  local tool=$1 version=$2 numeric='[0-9]+\.[0-9]+\.[0-9]+'
+  case "$version" in
+    system|path:*|ref:*) return 1 ;;
+  esac
+  case "$tool" in
+    nodejs)
+      [[ "$version" =~ ^${numeric}(-rc\.[0-9]+)?$ ]]
+      ;;
+    python)
+      [[ "$version" =~ ^${numeric}((a|b|rc)[0-9]+)?$ ]]
+      ;;
+    ruby)
+      [[ "$version" =~ ^${numeric}(-(preview|rc)[0-9]+)?$ ]]
+      ;;
+    golang|rust)
+      [[ "$version" =~ ^${numeric}$ ]]
+      ;;
+    *) return 1 ;;
+  esac
+}
+
+tool_output_matches_selection() {
+  local tool=$1 version=$2 output=$3 expected
+  # Moving/plugin-specific aliases (for example Python's free-threaded `t`
+  # suffix or Ruby `-dev`) remain execution+containment proved. Plain releases
+  # and the deliberately enumerated prerelease forms must report exactly.
+  tool_selection_requires_exact_output "$tool" "$version" || return 0
+  normalize_tool_version_output "$tool" "$output" || return 1
+  expected=$version
+  if [ "$tool" = ruby ]; then
+    expected=${expected/-preview/preview}
+    expected=${expected/-rc/rc}
+  fi
+  [ "$NORMALIZED_TOOL_VERSION" = "$expected" ]
+}
+# END UAI_MANAGED_VERSION_PROOF
+
+selection_is_proven() {
+  local tool=$1 version=$2 project=$3 executable variable reported npm_candidate npm_report
+  SELECTION_PROOF_ERROR=""
+  executable=$(tool_executable "$tool") \
+    || {
+      SELECTION_PROOF_ERROR="no executable proof is defined for supported plugin $tool"
+      return 1
+    }
+  variable="ASDF_$(printf '%s' "$tool" | tr '[:lower:]-' '[:upper:]_')_VERSION"
+  export "$variable=$version"
+  if ! (cd "$project" && asdf current "$tool" >/dev/null); then
+    SELECTION_PROOF_ERROR="ASDF could not resolve $tool $version in $(basename "$project")"
+    unset "$variable"
+    return 1
+  fi
+  if ! selected_executable "$tool" "$version" "$project" "$executable"; then
+    SELECTION_PROOF_ERROR="$tool $version did not resolve executable '$executable'"
+    unset "$variable"
+    return 1
+  fi
+  if ! managed_executable_is_contained "$version" "$SELECTED_EXECUTABLE"; then
+    SELECTION_PROOF_ERROR="$tool $version executable escapes its exact managed install directory"
+    unset "$variable"
+    return 1
+  fi
+  if ! run_tool_version_probe "$tool" "$SELECTED_EXECUTABLE" "$project"; then
+    SELECTION_PROOF_ERROR="$tool $version executable '$executable' failed its version probe"
+    unset "$variable"
+    return 1
+  fi
+  reported=$TOOL_VERSION_OUTPUT
+  if ! tool_output_matches_selection "$tool" "$version" "$reported"; then
+    SELECTION_PROOF_ERROR="$tool $version executable reported '$reported'"
+    unset "$variable"
+    return 1
+  fi
+  if [ "$tool" = nodejs ]; then
+    case "$version" in
+      system|path:*) ;;
+      *)
+        npm_candidate="$MANAGED_INSTALL_PATH/bin/npm"
+        if ! managed_executable_is_contained "$version" "$npm_candidate" \
+          || ! npm_report=$(cd "$project" \
+            && PATH="$MANAGED_INSTALL_PATH/bin:$CONTROL_PATH" \
+            "$npm_candidate" --version 2>&1) \
+          || [ -z "$npm_report" ]; then
+          SELECTION_PROOF_ERROR="nodejs $version has no contained runnable npm"
+          unset "$variable"
+          return 1
+        fi
+        ;;
+    esac
+  fi
+  # Execute through the same shim-first PATH the app receives. This catches a
+  # direct `asdf which` success whose shim was lost by a later global reshim.
+  if ! run_tool_shim_version_probe "$tool" "$executable" "$project"; then
+    SELECTION_PROOF_ERROR="$tool $version shim '$executable' failed its version probe"
+    unset "$variable"
+    return 1
+  fi
+  reported=$TOOL_VERSION_OUTPUT
+  if ! tool_output_matches_selection "$tool" "$version" "$reported"; then
+    SELECTION_PROOF_ERROR="$tool $version shim reported '$reported'"
+    unset "$variable"
+    return 1
+  fi
+  unset "$variable"
+  return 0
+}
+
+prove_selection() {
+  local tool=$1 version=$2 project=$3 source=$4
+  case "$version" in
+    system|path:*) ;;
+    *) managed_install_path "$tool" "$version" "$project" "$source" ;;
+  esac
+  selection_is_proven "$tool" "$version" "$project" \
+    || fail "$SELECTION_PROOF_ERROR"
+}
+
+# BEGIN UAI_MANAGED_INSTALL_REPAIR
+# asdf 0.14.1 considers any existing install directory complete, even when a
+# daemon/container death left it empty. A managed selection that fails the
+# positive executable proof gets one exact-directory repair under the global
+# maintenance lock. system/path selections never enter this code.
+managed_install_location() {
+  local tool=$1 version=$2 project=$3 source=$4 suffix component
+  local installs_root lexical_installs_root real_installs_root
+  local root lexical_root real_root candidate lexical_candidate real_candidate
+
+  case "$tool" in
+    nodejs|python|golang|ruby|rust) ;;
+    *) fail "refusing to repair unsupported asdf plugin '$tool'" ;;
+  esac
+  case "$version" in
+    system|path:*) fail "refusing to repair external $tool $version" ;;
+  esac
+  # Revalidate at the destructive boundary instead of relying only on the
+  # earlier parser pass.
+  validate_version "$version" "$project" "$source" 0
+  case "$version" in
+    ref:*)
+      suffix=${version#ref:}
+      component="ref-$suffix"
+      ;;
+    *) component=$version ;;
+  esac
+
+  installs_root="$ASDF_DATA/installs"
+  if [ -L "$installs_root" ] || [ ! -d "$installs_root" ]; then
+    fail "managed installs root $installs_root is not a real directory"
+  fi
+  lexical_installs_root=$("$REALPATH_BIN" -m -s -- "$installs_root") \
+    || fail "could not normalize managed installs root $installs_root"
+  real_installs_root=$("$REALPATH_BIN" -e -- "$installs_root") \
+    || fail "could not resolve managed installs root $installs_root"
+  [ "$real_installs_root" = "$lexical_installs_root" ] \
+    || fail "managed installs root $installs_root traverses a symbolic link"
+
+  root="$installs_root/$tool"
+  lexical_root=$("$REALPATH_BIN" -m -s -- "$root") \
+    || fail "could not normalize managed install root $root"
+  case "$lexical_root" in
+    "$lexical_installs_root"/*) ;;
+    *) fail "managed install root $root escapes $lexical_installs_root" ;;
+  esac
+  if [ -e "$root" ] || [ -L "$root" ]; then
+    if [ -L "$root" ] || [ ! -d "$root" ]; then
+      fail "managed install root $root is not a real directory"
+    fi
+    real_root=$("$REALPATH_BIN" -e -- "$root") \
+      || fail "could not resolve managed install root $root"
+    [ "$real_root" = "$lexical_root" ] \
+      || fail "managed install root $root traverses a symbolic link"
+  fi
+
+  candidate="$root/$component"
+  lexical_candidate=$("$REALPATH_BIN" -m -s -- "$candidate") \
+    || fail "could not normalize managed install path for $tool $version"
+  case "$lexical_candidate" in
+    "$lexical_root"/*) ;;
+    *) fail "managed install path for $tool $version escapes $lexical_root" ;;
+  esac
+  MANAGED_INSTALL_EXISTS=0
+  if [ -e "$candidate" ] || [ -L "$candidate" ]; then
+    if [ -L "$candidate" ] || [ ! -d "$candidate" ]; then
+      fail "managed install path for $tool $version is not a real directory"
+    fi
+    real_candidate=$("$REALPATH_BIN" -e -- "$candidate") \
+      || fail "could not resolve managed install path for $tool $version"
+    [ "$real_candidate" = "$lexical_candidate" ] \
+      || fail "managed install path for $tool $version traverses a symbolic link"
+    MANAGED_INSTALL_EXISTS=1
+  fi
+
+  MANAGED_INSTALL_PATH=$lexical_candidate
+}
+
+managed_install_path() {
+  managed_install_location "$@"
+  [ "$MANAGED_INSTALL_EXISTS" -eq 1 ] \
+    || fail "failed $1 $2 proof but its exact managed install directory is missing"
+}
+
+is_default_node_version() {
+  local requested=$1 line version
+  local -a fields=()
+  while IFS= read -r line || [ -n "$line" ]; do
+    line=${line%%#*}
+    line=$(trim_spaces "$line")
+    case "$line" in
+      nodejs' '*)
+        read -r -a fields <<< "$line"
+        for version in "${fields[@]:1}"; do
+          [ "$version" != "$requested" ] || return 0
+        done
+        ;;
+    esac
+  done < /home/node/.tool-versions
+  return 1
+}
+
+prove_or_repair_managed_selection() {
+  local tool=$1 version=$2 project=$3 source=$4 initial_error failed_path
+  case "$version" in
+    system|path:*)
+      selection_is_proven "$tool" "$version" "$project" \
+        || fail "$SELECTION_PROOF_ERROR"
+      return 0
+      ;;
+  esac
+
+  # Validate even a healthy-looking cache entry before ASDF resolution: asdf
+  # follows an install-directory symlink and can otherwise prove the wrong
+  # runtime version under the requested selector.
+  managed_install_path "$tool" "$version" "$project" "$source"
+  if selection_is_proven "$tool" "$version" "$project"; then
+    return 0
+  fi
+  initial_error=$SELECTION_PROOF_ERROR
+  # ${VERIFY_ONLY:-0}: this block is extracted into a standalone test harness
+  # that runs it without the script preamble.
+  if [ "${VERIFY_ONLY:-0}" = 1 ]; then
+    fail "$initial_error (verify-only pass makes no repairs)"
+  fi
+  failed_path=$MANAGED_INSTALL_PATH
+  if [ "$tool" = nodejs ] && is_default_node_version "$version"; then
+    fail "$initial_error; refusing to remove the host-default Node candidate because boot maintenance owns its CLI/Corepack invariant"
+  fi
+  # Candidate-controlled probes ran after the initial path check. Re-resolve
+  # every parent immediately at the destructive boundary and require the same
+  # exact target before removing anything.
+  managed_install_path "$tool" "$version" "$project" "$source"
+  [ "$MANAGED_INSTALL_PATH" = "$failed_path" ] \
+    || fail "managed install path for $tool $version changed during proof"
+  log "$initial_error; removing incomplete exact cache entry $MANAGED_INSTALL_PATH and retrying once"
+  rm -rf --one-file-system -- "${MANAGED_INSTALL_PATH:?}" \
+    || fail "could not remove incomplete $tool $version install"
+  if [ -e "$MANAGED_INSTALL_PATH" ] || [ -L "$MANAGED_INSTALL_PATH" ]; then
+    fail "incomplete $tool $version install still exists after repair removal"
+  fi
+  (cd "$project" && run_asdf_install "$tool" "$version") \
+    || fail "asdf reinstall failed for $tool $version in $(basename "$project")"
+  managed_install_path "$tool" "$version" "$project" "$source"
+  (cd "$project" && run_asdf_reshim "$tool" "$version") \
+    || fail "asdf reshim failed after repairing $tool $version"
+  managed_install_path "$tool" "$version" "$project" "$source"
+  selection_is_proven "$tool" "$version" "$project" \
+    || fail "$SELECTION_PROOF_ERROR after one exact-directory repair"
+}
+# END UAI_MANAGED_INSTALL_REPAIR
+
+resolve_node_context_executable() {
+  local project=$1 node_version=$2 source=$3 executable=$4 candidate
+  NODE_CONTEXT_EXECUTABLE=""
+  case "$node_version" in
+    system|path:*)
+      selected_executable nodejs "$node_version" "$project" "$executable" \
+        || return 1
+      NODE_CONTEXT_EXECUTABLE=$SELECTED_EXECUTABLE
+      return 0
+      ;;
+  esac
+
+  managed_install_path nodejs "$node_version" "$project" "$source"
+  if [ "$executable" = npm ]; then
+    # asdf-nodejs intentionally reports a plugin-owned wrapper for `asdf which
+    # npm`; maintenance must execute the selected runtime's own npm instead.
+    candidate="$MANAGED_INSTALL_PATH/bin/npm"
+    managed_executable_is_contained "$node_version" "$candidate" || return 1
+    NODE_CONTEXT_EXECUTABLE=$candidate
+    return 0
+  fi
+  selected_executable nodejs "$node_version" "$project" "$executable" \
+    || return 1
+  managed_executable_is_contained "$node_version" "$SELECTED_EXECUTABLE" \
+    || return 1
+  NODE_CONTEXT_EXECUTABLE=$SELECTED_EXECUTABLE
+}
+
+# BEGIN UAI_MANAGED_NODE_PROCESS_CONTEXT
+managed_node_process_context_is_selected() {
+  local project=$1 node_version=$2 report reported_version reported_executable
+  report=$(cd "$project" \
+    && PATH="$MANAGED_INSTALL_PATH/bin:$CONTROL_PATH" \
+      /usr/bin/env node -p 'process.version + "\t" + process.execPath' 2>/dev/null) \
+    || return 1
+  case "$report" in
+    *$'\t'*) ;;
+    *) return 1 ;;
+  esac
+  reported_version=${report%%$'\t'*}
+  reported_executable=${report#*$'\t'}
+  managed_executable_is_contained "$node_version" "$reported_executable" \
+    || return 1
+  tool_output_matches_selection nodejs "$node_version" "$reported_version"
+}
+# END UAI_MANAGED_NODE_PROCESS_CONTEXT
+
+execute_in_node_context() {
+  local executable=$1 project=$2 node_version=$3 suffix resolved
+  shift 3
+  case "$node_version" in
+    system)
+      (cd "$project" && PATH="$CONTROL_PATH" "$executable" "$@")
+      ;;
+    path:*)
+      suffix=${node_version#path:}
+      resolved=$(cd "$project" && "$REALPATH_BIN" -e -- "$suffix") || return 1
+      (cd "$project" && PATH="$resolved/bin:$CONTROL_PATH" "$executable" "$@")
+      ;;
+    *)
+      managed_node_process_context_is_selected "$project" "$node_version" \
+        || return 1
+      (cd "$project" && PATH="$MANAGED_INSTALL_PATH/bin:$CONTROL_PATH" \
+        ASDF_NODEJS_VERSION="$node_version" \
+        "$executable" "$@")
+      ;;
+  esac
+}
+
+corepack_version_is_usable() {
+  local corepack_bin=$1 project=$2 node_version=$3 version
+  version=$(execute_in_node_context \
+    "$corepack_bin" "$project" "$node_version" --version 2>/dev/null) \
+    || return 1
+  [ "$version" = "$COREPACK_VERSION" ]
+}
+
+# BEGIN UAI_MANAGED_COREPACK_REPAIR
+reinstall_managed_corepack() {
+  local project=$1 node_version=$2 source_manifest=$3 manager=$4
+  local npm_bin corepack_bin
+  resolve_node_context_executable \
+    "$project" "$node_version" "$source_manifest" npm \
+    || fail "nodejs $node_version has no contained npm for Corepack repair"
+  npm_bin=$NODE_CONTEXT_EXECUTABLE
+  log "reinstalling corepack@$COREPACK_VERSION inside nodejs $node_version"
+  (cd / && PATH="$MANAGED_INSTALL_PATH/bin:$CONTROL_PATH" \
+    ASDF_NODEJS_VERSION="$node_version" \
+    "$npm_bin" install -g --force "corepack@$COREPACK_VERSION" \
+    --no-audit --no-fund \
+    --registry="$NPM_REGISTRY" \
+    --userconfig="$NPM_USERCONFIG" \
+    --globalconfig="$NPM_GLOBALCONFIG") \
+    || fail "could not reinstall corepack@$COREPACK_VERSION for nodejs $node_version"
+  managed_install_path nodejs "$node_version" "$project" "$source_manifest"
+  run_asdf_reshim nodejs "$node_version" \
+    || fail "could not reshim nodejs $node_version after Corepack reinstall"
+  managed_install_path nodejs "$node_version" "$project" "$source_manifest"
+  resolve_node_context_executable \
+    "$project" "$node_version" "$source_manifest" corepack \
+    || fail "reinstalled Corepack escaped nodejs $node_version"
+  corepack_bin=$NODE_CONTEXT_EXECUTABLE
+  corepack_version_is_usable "$corepack_bin" "$project" "$node_version" \
+    || fail "reinstalled Corepack failed proof for nodejs $node_version"
+  execute_in_node_context \
+    "$corepack_bin" "$project" "$node_version" disable "$manager" \
+    || fail "reinstalled Corepack could not clear the stale $manager launcher"
+  managed_install_path nodejs "$node_version" "$project" "$source_manifest"
+}
+
+prepare_managed_package_manager_once() {
+  local project=$1 node_version=$2 manager=$3 spec=$4 is_fallback=$5
+  local source_manifest=$6 corepack_bin manager_bin actual expected
+  COREPACK_PREPARATION_ERROR=""
+
+  if ! resolve_node_context_executable \
+    "$project" "$node_version" "$source_manifest" corepack; then
+    COREPACK_PREPARATION_ERROR="Corepack is not contained in nodejs $node_version"
+    return 1
+  fi
+  corepack_bin=$NODE_CONTEXT_EXECUTABLE
+  if ! corepack_version_is_usable "$corepack_bin" "$project" "$node_version"; then
+    COREPACK_PREPARATION_ERROR="Corepack version proof failed in nodejs $node_version"
+    return 1
+  fi
+  if [ "$is_fallback" -eq 1 ]; then
+    if ! execute_in_node_context \
+      "$corepack_bin" "$project" "$node_version" install --global "$spec"; then
+      COREPACK_PREPARATION_ERROR="Corepack could not install fallback $spec"
+      return 1
+    fi
+  elif ! execute_in_node_context \
+    "$corepack_bin" "$project" "$node_version" \
+    install --global --cache-only "$spec"; then
+    COREPACK_PREPARATION_ERROR="Corepack could not cache exact $spec"
+    return 1
+  fi
+
+  if ! resolve_node_context_executable \
+    "$project" "$node_version" "$source_manifest" corepack; then
+    COREPACK_PREPARATION_ERROR="Corepack escaped nodejs $node_version after cache preparation"
+    return 1
+  fi
+  corepack_bin=$NODE_CONTEXT_EXECUTABLE
+  if ! execute_in_node_context \
+    "$corepack_bin" "$project" "$node_version" enable "$manager"; then
+    COREPACK_PREPARATION_ERROR="Corepack could not enable $manager"
+    return 1
+  fi
+  managed_install_path nodejs "$node_version" "$project" "$source_manifest"
+  if ! run_asdf_reshim nodejs "$node_version"; then
+    COREPACK_PREPARATION_ERROR="asdf could not reshim $manager for nodejs $node_version"
+    return 1
+  fi
+  managed_install_path nodejs "$node_version" "$project" "$source_manifest"
+  if ! resolve_node_context_executable \
+    "$project" "$node_version" "$source_manifest" corepack; then
+    COREPACK_PREPARATION_ERROR="Corepack escaped nodejs $node_version after final reshim"
+    return 1
+  fi
+  corepack_bin=$NODE_CONTEXT_EXECUTABLE
+  if ! corepack_version_is_usable "$corepack_bin" "$project" "$node_version"; then
+    COREPACK_PREPARATION_ERROR="Corepack failed final version proof in nodejs $node_version"
+    return 1
+  fi
+  if ! resolve_node_context_executable \
+    "$project" "$node_version" "$source_manifest" "$manager"; then
+    COREPACK_PREPARATION_ERROR="$manager is not contained in nodejs $node_version"
+    return 1
+  fi
+  manager_bin=$NODE_CONTEXT_EXECUTABLE
+  if ! actual=$(execute_in_node_context \
+    "$manager_bin" "$project" "$node_version" --version); then
+    COREPACK_PREPARATION_ERROR="$manager is not executable in nodejs $node_version"
+    return 1
+  fi
+  expected=${spec#"$manager"@}
+  expected=${expected%%+*}
+  if [ "$actual" != "$expected" ]; then
+    COREPACK_PREPARATION_ERROR="$manager resolved $actual instead of $expected"
+    return 1
+  fi
+  return 0
+}
+
+prepare_package_manager() {
+  local project=$1 node_version=$2 manager=$3 spec=$4 is_fallback=$5
+  local source_manifest=$6
+  local corepack_bin manager_bin actual expected initial_error
+  local corepack_repaired=0
+
+  case "$node_version" in
+    system|path:*)
+      resolve_node_context_executable \
+        "$project" "$node_version" "$source_manifest" corepack \
+        || fail "external nodejs $node_version must already provide Corepack for $manager"
+      corepack_bin=$NODE_CONTEXT_EXECUTABLE
+      corepack_version_is_usable "$corepack_bin" "$project" "$node_version" || fail \
+        "external nodejs $node_version has obsolete Corepack; Uai will not mutate external runtimes"
+      resolve_node_context_executable \
+        "$project" "$node_version" "$source_manifest" "$manager" \
+        || fail "external nodejs $node_version must already provide $manager; Uai will not mutate it"
+      manager_bin=$NODE_CONTEXT_EXECUTABLE
+      actual=$(execute_in_node_context \
+        "$manager_bin" "$project" "$node_version" --version) \
+        || fail "$manager is not executable for external nodejs $node_version"
+      expected=${spec#"$manager"@}
+      expected=${expected%%+*}
+      [ "$actual" = "$expected" ] || fail \
+        "$manager resolved $actual instead of packageManager version $expected for $(basename "$project")"
+      return
+      ;;
+  esac
+
+  resolve_node_context_executable \
+    "$project" "$node_version" "$source_manifest" npm \
+    || fail "nodejs $node_version installed without a contained runnable npm"
+  if resolve_node_context_executable \
+    "$project" "$node_version" "$source_manifest" corepack; then
+    corepack_bin=$NODE_CONTEXT_EXECUTABLE
+  else
+    corepack_bin=""
+  fi
+  if [ -z "$corepack_bin" ] \
+    || ! corepack_version_is_usable "$corepack_bin" "$project" "$node_version"; then
+    log "Corepack is missing or failed its exact proof in nodejs $node_version; performing one exact Corepack repair"
+    reinstall_managed_corepack \
+      "$project" "$node_version" "$source_manifest" "$manager"
+    corepack_repaired=1
+  fi
+
+  log "enabling Corepack $manager for nodejs $node_version"
+  if prepare_managed_package_manager_once \
+    "$project" "$node_version" "$manager" "$spec" "$is_fallback" \
+    "$source_manifest"; then
+    return 0
+  fi
+  initial_error=$COREPACK_PREPARATION_ERROR
+  if [ "$corepack_repaired" -eq 1 ]; then
+    fail "$initial_error after one exact Corepack repair"
+  fi
+  log "$initial_error; performing one exact Corepack repair and retry"
+  reinstall_managed_corepack \
+    "$project" "$node_version" "$source_manifest" "$manager"
+  prepare_managed_package_manager_once \
+    "$project" "$node_version" "$manager" "$spec" "$is_fallback" \
+    "$source_manifest" \
+    || fail "$COREPACK_PREPARATION_ERROR after one exact Corepack repair (initial: $initial_error)"
+}
+# END UAI_MANAGED_COREPACK_REPAIR
+
+materialize_manifest() {
+  local manifest=$1 project line tool version line_number=0
+  local -a fields=()
+
+  project=$(dirname "$manifest")
+  project_package_manager "$project"
+  while IFS= read -r line || [ -n "$line" ]; do
+    line_number=$((line_number + 1))
+    line=${line%%#*}
+    line=$(trim_spaces "$line")
+    [ -n "$line" ] || continue
+    read -r -a fields <<< "$line"
+    tool=${fields[0]}
+    case "$tool" in
+      pnpm|yarn) continue ;; # Corepack-managed; see project_package_manager.
+    esac
+    unset_tool_override "$tool"
+    asdf plugin list | grep -Fqx -- "$tool" \
+      || fail "$manifest:$line_number requests unsupported asdf plugin '$tool'"
+
+    for version in "${fields[@]:1}"; do
+      case "$version" in
+        system) ;;
+        path:*)
+          if [ "$VERIFY_ONLY" = 1 ]; then
+            # Shims either already exist (the later shim probe proves them) or
+            # the verify pass fails and the host escalates to the writable one.
+            log "verify-only: skipping shim creation for external $tool $version"
+          else
+            (cd "$project" && run_asdf_reshim "$tool" "$version") \
+              || fail "could not create ASDF shims for external $tool $version"
+          fi
+          ;;
+        *)
+          if [ "$tool" = nodejs ] && is_default_node_version "$version"; then
+            # Boot maintenance exclusively owns the default Node candidate and
+            # its globally installed agent CLIs/Corepack. Do not create or
+            # alter it after a failed boot transaction.
+            managed_install_location \
+              "$tool" "$version" "$project" "$manifest"
+            [ "$MANAGED_INSTALL_EXISTS" -eq 1 ] \
+              || fail "host-default nodejs $version is missing; standard-image boot maintenance must repair it before task runtime materialization"
+            log "proving host-default $tool $version for $(basename "$project")"
+          elif [ "$VERIFY_ONLY" = 1 ]; then
+            managed_install_location \
+              "$tool" "$version" "$project" "$manifest"
+            [ "$MANAGED_INSTALL_EXISTS" -eq 1 ] \
+              || fail "$tool $version is not installed on the shared runtime volume (verify-only pass makes no installs)"
+            log "verifying $tool $version for $(basename "$project")"
+          else
+            managed_install_location \
+              "$tool" "$version" "$project" "$manifest"
+            log "installing $tool $version for $(basename "$project")"
+            (cd "$project" && run_asdf_install "$tool" "$version") \
+              || fail "asdf install failed for $tool $version in $(basename "$project")"
+          fi
+          ;;
+      esac
+    done
+    for version in "${fields[@]:1}"; do
+      prove_or_repair_managed_selection \
+        "$tool" "$version" "$project" "$manifest"
+    done
+
+  done < "$manifest"
+}
+
+manifest_declares_tool() {
+  local manifest=$1 tool=$2 line
+  [ -f "$manifest" ] || return 1
+  while IFS= read -r line || [ -n "$line" ]; do
+    line=${line%%#*}
+    line=$(trim_spaces "$line")
+    case "$line" in
+      "$tool"' '*) return 0 ;;
+    esac
+  done < "$manifest"
+  return 1
+}
+
+materialize_fallback_runtimes() {
+  local project=$1 defaults=/home/node/.tool-versions manifest line tool version
+  local -a fields=()
+  manifest="$project/.tool-versions"
+  while IFS= read -r line || [ -n "$line" ]; do
+    line=${line%%#*}
+    line=$(trim_spaces "$line")
+    [ -n "$line" ] || continue
+    read -r -a fields <<< "$line"
+    tool=${fields[0]}
+    if manifest_declares_tool "$manifest" "$tool"; then
+      continue
+    fi
+    asdf plugin list | grep -Fqx -- "$tool" \
+      || fail "$defaults requests unavailable fallback plugin '$tool'"
+    for version in "${fields[@]:1}"; do
+      case "$version" in
+        system) ;;
+        path:*)
+          if [ "$VERIFY_ONLY" = 1 ]; then
+            log "verify-only: skipping shim creation for fallback external $tool $version"
+          else
+            (cd "$project" && run_asdf_reshim "$tool" "$version") \
+              || fail "could not create ASDF shims for fallback external $tool $version"
+          fi
+          ;;
+        *)
+          if [ "$tool" = nodejs ] && is_default_node_version "$version"; then
+            # The standard-image transaction must restore Node/npm plus its
+            # CLI/Corepack invariant as one crash-retryable unit.
+            managed_install_location \
+              "$tool" "$version" "$project" "$defaults"
+            [ "$MANAGED_INSTALL_EXISTS" -eq 1 ] \
+              || fail "fallback host-default nodejs $version is missing; standard-image boot maintenance must repair it before task runtime materialization"
+            log "proving fallback host-default $tool $version for $(basename "$project")"
+          elif [ "$VERIFY_ONLY" = 1 ]; then
+            managed_install_location \
+              "$tool" "$version" "$project" "$defaults"
+            [ "$MANAGED_INSTALL_EXISTS" -eq 1 ] \
+              || fail "fallback $tool $version is not installed on the shared runtime volume (verify-only pass makes no installs)"
+            log "verifying fallback $tool $version for $(basename "$project")"
+          else
+            managed_install_location \
+              "$tool" "$version" "$project" "$defaults"
+            log "installing fallback $tool $version for $(basename "$project")"
+            (cd "$project" && run_asdf_install "$tool" "$version") \
+              || fail "asdf install failed for fallback $tool $version in $(basename "$project")"
+          fi
+          ;;
+      esac
+      prove_or_repair_managed_selection \
+        "$tool" "$version" "$project" "$defaults"
+    done
+  done < "$defaults"
+}
+
+default_node_versions() {
+  local defaults=/home/node/.tool-versions line
+  local -a fields=()
+  DEFAULT_NODE_VERSIONS=()
+  if [ -L "$defaults" ] || [ ! -f "$defaults" ]; then
+    fail "effective default Node manifest $defaults is not a regular file"
+  fi
+  while IFS= read -r line || [ -n "$line" ]; do
+    line=${line%%#*}
+    line=$(trim_spaces "$line")
+    case "$line" in
+      nodejs' '*)
+        read -r -a fields <<< "$line"
+        for version in "${fields[@]:1}"; do
+          validate_version "$version" /home/node "$defaults" 1
+          DEFAULT_NODE_VERSIONS+=("$version")
+        done
+        ;;
+    esac
+  done < "$defaults"
+  [ "${#DEFAULT_NODE_VERSIONS[@]}" -gt 0 ] \
+    || fail "$defaults does not declare an effective default Node runtime"
+}
+
+effective_node_versions() {
+  local project=$1 manifest="$project/.tool-versions" line
+  local -a fields=()
+  EFFECTIVE_NODE_VERSIONS=()
+  EFFECTIVE_NODE_SOURCE=""
+  if manifest_declares_tool "$manifest" nodejs; then
+    EFFECTIVE_NODE_SOURCE=$manifest
+    while IFS= read -r line || [ -n "$line" ]; do
+      line=${line%%#*}
+      line=$(trim_spaces "$line")
+      case "$line" in
+        nodejs' '*)
+          read -r -a fields <<< "$line"
+          EFFECTIVE_NODE_VERSIONS=("${fields[@]:1}")
+          break
+          ;;
+      esac
+    done < "$manifest"
+  else
+    default_node_versions
+    EFFECTIVE_NODE_VERSIONS=("${DEFAULT_NODE_VERSIONS[@]}")
+    EFFECTIVE_NODE_SOURCE=/home/node/.tool-versions
+  fi
+  [ "${#EFFECTIVE_NODE_VERSIONS[@]}" -gt 0 ] \
+    || fail "could not determine effective Node versions for $(basename "$project")"
+}
+
+project_uses_npm() {
+  local project=$1 manager=""
+  [ -f "$project/package.json" ] || return 1
+  manager=$(jq -r '.packageManager // ""' "$project/package.json" \
+    | sed 's/@.*//')
+  if [ -z "$manager" ]; then
+    if [ -f "$project/pnpm-lock.yaml" ]; then
+      manager=pnpm
+    elif [ -f "$project/yarn.lock" ]; then
+      manager=yarn
+    elif [ -f "$project/bun.lockb" ] || [ -f "$project/bun.lock" ]; then
+      manager=bun
+    else
+      manager=npm
+    fi
+  fi
+  case "$manager" in
+    pnpm|yarn|bun) return 1 ;;
+    *) return 0 ;;
+  esac
+}
+
+prove_project_npm() {
+  local project=$1 version npm_bin actual shim_actual
+  project_uses_npm "$project" || return 0
+  effective_node_versions "$project"
+  for version in "${EFFECTIVE_NODE_VERSIONS[@]}"; do
+    resolve_node_context_executable \
+      "$project" "$version" "$EFFECTIVE_NODE_SOURCE" npm \
+      || fail "npm did not resolve inside effective nodejs $version in $(basename "$project")"
+    npm_bin=$NODE_CONTEXT_EXECUTABLE
+    actual=$(execute_in_node_context \
+      "$npm_bin" "$project" "$version" --version) \
+      || fail "npm execution failed for effective nodejs $version in $(basename "$project")"
+    [ -n "$actual" ] \
+      || fail "npm returned no version for effective nodejs $version in $(basename "$project")"
+    shim_actual=$(run_node_shim_probe \
+      "$project" "$version" npm --version) \
+      || fail "npm shim execution failed for effective nodejs $version in $(basename "$project")"
+    [ -n "$shim_actual" ] \
+      || fail "npm shim returned no version for effective nodejs $version in $(basename "$project")"
+  done
+}
+
+prepare_project_package_manager() {
+  local project=$1 version
+  project_package_manager "$project"
+  [ -n "$PROJECT_PACKAGE_MANAGER" ] || return 0
+  effective_node_versions "$project"
+  for version in "${EFFECTIVE_NODE_VERSIONS[@]}"; do
+    prepare_package_manager "$project" "$version" \
+      "$PROJECT_PACKAGE_MANAGER" "$PROJECT_PACKAGE_MANAGER_SPEC" \
+      "$PROJECT_PACKAGE_MANAGER_IS_FALLBACK" "$EFFECTIVE_NODE_SOURCE"
+  done
+}
+
+prove_project_package_manager() {
+  local project=$1 version manager_bin actual shim_actual expected
+  project_package_manager "$project"
+  [ -n "$PROJECT_PACKAGE_MANAGER" ] || return 0
+  effective_node_versions "$project"
+  expected=${PROJECT_PACKAGE_MANAGER_SPEC#"$PROJECT_PACKAGE_MANAGER"@}
+  expected=${expected%%+*}
+  for version in "${EFFECTIVE_NODE_VERSIONS[@]}"; do
+    resolve_node_context_executable \
+      "$project" "$version" "$EFFECTIVE_NODE_SOURCE" \
+      "$PROJECT_PACKAGE_MANAGER" \
+      || fail "final $PROJECT_PACKAGE_MANAGER proof could not resolve inside nodejs $version"
+    manager_bin=$NODE_CONTEXT_EXECUTABLE
+    actual=$(execute_in_node_context \
+      "$manager_bin" "$project" "$version" --version) \
+      || fail "final $PROJECT_PACKAGE_MANAGER execution proof failed for nodejs $version"
+    [ "$actual" = "$expected" ] || fail \
+      "$PROJECT_PACKAGE_MANAGER resolved $actual instead of $expected after final reshim"
+    shim_actual=$(run_node_shim_probe \
+      "$project" "$version" "$PROJECT_PACKAGE_MANAGER" --version) \
+      || fail "final $PROJECT_PACKAGE_MANAGER shim execution failed for nodejs $version"
+    [ "$shim_actual" = "$expected" ] || fail \
+      "$PROJECT_PACKAGE_MANAGER shim resolved $shim_actual instead of $expected"
+  done
+}
+
+prove_fallback_runtimes() {
+  local project=$1 defaults=/home/node/.tool-versions manifest line tool version
+  local -a fields=()
+  manifest="$project/.tool-versions"
+  while IFS= read -r line || [ -n "$line" ]; do
+    line=${line%%#*}
+    line=$(trim_spaces "$line")
+    [ -n "$line" ] || continue
+    read -r -a fields <<< "$line"
+    tool=${fields[0]}
+    if manifest_declares_tool "$manifest" "$tool"; then
+      continue
+    fi
+    for version in "${fields[@]:1}"; do
+      prove_selection "$tool" "$version" "$project" "$defaults"
+    done
+  done < "$defaults"
+}
+
+# Validate fallback and package-manager declarations before any shared-volume
+# mutation. Every real project has effective home defaults even with no file.
+validate_manifest /home/node/.tool-versions
+for project in "${projects[@]}"; do
+  project_package_manager "$project"
+done
+
+# Fresh image-seeded volumes already carry this root-owned, node-writable
+# regular file. Legacy volumes are repaired by standard-image boot maintenance.
+if [ -L "$LOCK_PATH" ]; then
+  fail "$LOCK_PATH is a symbolic link"
+fi
+if [ "$VERIFY_ONLY" = 1 ]; then
+  # A verify pass cannot create the lock on a read-only volume. Take a SHARED
+  # flock when the file exists (readers must not serialize behind each other,
+  # and must still wait out a writer on runtimes where one is possible); a
+  # missing lock file only occurs on a legacy volume, where the read-only
+  # attachment itself excludes every Apple writer.
+  if [ -e "$LOCK_PATH" ]; then
+    [ -f "$LOCK_PATH" ] || fail "$LOCK_PATH is not a regular lock file"
+    exec 9< "$LOCK_PATH" || fail "could not open $LOCK_PATH"
+    if ! "$FLOCK_BIN" --shared --timeout "$LOCK_WAIT_SECONDS" 9; then
+      fail "timed out after ${LOCK_WAIT_SECONDS}s waiting for shared asdf maintenance"
+    fi
+  else
+    log "verify-only: $LOCK_PATH is absent on the read-only volume; proceeding without it"
+  fi
+else
+  if [ ! -e "$LOCK_PATH" ]; then
+    old_umask=$(umask)
+    umask 002
+    : > "$LOCK_PATH" || fail "could not create $LOCK_PATH"
+    umask "$old_umask"
+  fi
+  if [ ! -f "$LOCK_PATH" ]; then
+    fail "$LOCK_PATH is not a regular lock file"
+  fi
+  exec 9< "$LOCK_PATH" || fail "could not open $LOCK_PATH"
+  if ! "$FLOCK_BIN" --exclusive --timeout "$LOCK_WAIT_SECONDS" 9; then
+    fail "timed out after ${LOCK_WAIT_SECONDS}s waiting for shared asdf maintenance"
+  fi
+fi
+
+# BEGIN UAI_FORBIDDEN_INTERPRETER_SHIM
+validate_shims_root() {
+  local shims_root="$ASDF_DATA/shims" lexical resolved
+  if [ -L "$shims_root" ] || [ ! -d "$shims_root" ]; then
+    fail "shared asdf shims root is not a real directory"
+  fi
+  lexical=$("$REALPATH_BIN" -m -s -- "$shims_root") \
+    || fail "could not normalize shared asdf shims root"
+  resolved=$("$REALPATH_BIN" -e -- "$shims_root") \
+    || fail "could not resolve shared asdf shims root"
+  [ "$lexical" = "$resolved" ] \
+    || fail "shared asdf shims root traverses a symbolic link"
+  SHIMS_ROOT=$lexical
+}
+
+clear_forbidden_interpreter_shim() {
+  local fail_if_found=$1 candidate
+  validate_shims_root
+  candidate="$SHIMS_ROOT/bash"
+  # Every asdf shim uses `#!/usr/bin/env bash`. A shared shim named `bash`
+  # would recursively intercept every app command and previously could also
+  # intercept maintenance itself. It is not an advertised runtime executable.
+  if [ ! -e "$candidate" ] && [ ! -L "$candidate" ]; then
+    return 0
+  fi
+  [ ! -d "$candidate" ] \
+    || fail "forbidden shared asdf bash shim is a directory; refusing recursive cleanup"
+  "$RM_BIN" -f -- "$candidate" \
+    || fail "could not remove the exact forbidden shared asdf bash shim"
+  [ ! -e "$candidate" ] && [ ! -L "$candidate" ] \
+    || fail "forbidden shared asdf bash shim survived exact cleanup"
+  log "removed forbidden shared asdf bash shim"
+  [ "$fail_if_found" -eq 0 ] || return 1
+}
+
+run_asdf_reshim() {
+  local reshim_status=0 shim_status=0
+  asdf reshim "$@" || reshim_status=$?
+  clear_forbidden_interpreter_shim 1 || shim_status=$?
+  [ "$shim_status" -eq 0 ] || return 1
+  return "$reshim_status"
+}
+
+run_asdf_install() {
+  local install_status=0 shim_status=0
+  asdf install "$@" || install_status=$?
+  # asdf 0.14.1 reshims internally after a successful install. Always inspect
+  # and clean that side effect, including when the install later reports an
+  # error, before returning control to an actionable caller failure.
+  clear_forbidden_interpreter_shim 1 || shim_status=$?
+  [ "$shim_status" -eq 0 ] || return 1
+  return "$install_status"
+}
+# END UAI_FORBIDDEN_INTERPRETER_SHIM
+
+# A prior killed run may have created this exact stale shim. Clean it while
+# holding the real volume lock, before sourcing or executing any ASDF shim.
+clear_forbidden_interpreter_shim 0
+
+# Sourcing asdf prepends the shared shims directory. Do it only after the
+# volume lock is held, retain its shell function, then restore the trusted
+# control-plane PATH. App/shim parity is opted into only at explicit probes.
+# shellcheck disable=SC1091
+. "$ASDF_SH"
+export PATH="$CONTROL_PATH"
+command -v asdf >/dev/null 2>&1 || fail "asdf did not initialize"
+
+export COREPACK_HOME="$ASDF_DATA/corepack"
+# A verify pass only reads the Corepack cache; a missing directory then fails
+# the package-manager proofs below, which is the correct escalation signal.
+[ "$VERIFY_ONLY" = 1 ] || mkdir -p "$COREPACK_HOME"
+for manifest in "${manifests[@]}"; do
+  # Revalidate after acquiring the lock, then perform this caller's own full
+  # install and proof. A prior concurrent materializer is never success for us.
+  validate_manifest "$manifest"
+  materialize_manifest "$manifest"
+done
+for project in "${projects[@]}"; do
+  materialize_fallback_runtimes "$project"
+done
+
+# Rebuild shared shims after runtime installs, then prepare package managers.
+# Corepack preparation may reshim selected Node versions itself; every runtime
+# and manager is therefore re-executed below only after the last mutation.
+if [ "$VERIFY_ONLY" = 1 ]; then
+  # Nothing was mutated, so there is nothing to reshim or prepare; the proofs
+  # below still execute every runtime and manager through the existing shims.
+  log "verify-only: skipping reshim and package-manager preparation"
+else
+  run_asdf_reshim || fail "final asdf reshim failed"
+  for project in "${projects[@]}"; do
+    prepare_project_package_manager "$project"
+  done
+  clear_forbidden_interpreter_shim 1 \
+    || fail "a runtime recreated the forbidden shared asdf bash shim"
+fi
+
+# From here on, package-manager execution is a cache-only postcondition. The
+# app receives the same setting, so a missing exact/fallback artifact fails now
+# instead of downloading later after the shared cache becomes read-only.
+export COREPACK_ENABLE_NETWORK=0
+for manifest in "${manifests[@]}"; do
+  project=$(dirname "$manifest")
+  while IFS= read -r line || [ -n "$line" ]; do
+    line=${line%%#*}
+    line=$(trim_spaces "$line")
+    [ -n "$line" ] || continue
+    read -r -a fields <<< "$line"
+    case "${fields[0]}" in
+      pnpm|yarn) continue ;; # proven via prove_project_package_manager below
+    esac
+    unset_tool_override "${fields[0]}"
+    for version in "${fields[@]:1}"; do
+      prove_selection "${fields[0]}" "$version" "$project" "$manifest"
+    done
+  done < "$manifest"
+done
+for project in "${projects[@]}"; do
+  prove_fallback_runtimes "$project"
+  prove_project_npm "$project"
+  prove_project_package_manager "$project"
+done
+
+if [ "$VERIFY_ONLY" = 1 ]; then
+  log "runtime verification complete for ${#projects[@]} project(s) (no volume changes)"
+else
+  log "runtime materialization complete for ${#projects[@]} project(s)"
+fi