@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.10 → 0.1.26

package/bin/reconcile

@@ -44,7 +44,7 @@ if [[ -z "${RECONCILE_REEXEC_BASH:-}" ]]; then
       export RECONCILE_REEXEC_BASH=1
       exec "$reconcile_newer_bash" "$0" "$@"
     fi
-    echo "bin/reconcile requires bash >= 4.4 (this run is bash ${BASH_VERSION:-unknown} -- empty-array expansions are unsafe under set -u before 4.4). No newer bash was found at: $reconcile_bash_candidates. Install one (e.g. 'brew install bash') and re-run, or put a newer bash earlier on PATH -- refusing to start rather than risk an 'unbound variable' abort mid-run after state has already changed." >&2
+    echo "ERROR bin/reconcile requires bash >= 4.4 (this run is bash ${BASH_VERSION:-unknown} -- empty-array expansions are unsafe under set -u before 4.4). No newer bash was found at: $reconcile_bash_candidates. Install one (e.g. 'brew install bash') and re-run, or put a newer bash earlier on PATH -- refusing to start rather than risk an 'unbound variable' abort mid-run after state has already changed." >&2
     exit 1
   fi
 fi
@@ -54,7 +54,7 @@ set -euo pipefail
 export PATH="/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"
 
 usage() {
-  echo "usage: reconcile --device NAME [--source npm|checkout] [--mode audit|plan|apply] [--manifest PATH] [--state-dir PATH] [--platform mac|linux]" >&2
+  echo "ERROR usage: reconcile --device NAME [--source npm|checkout] [--mode audit|plan|apply] [--manifest PATH] [--state-dir PATH] [--platform mac|linux]" >&2
   exit 2
 }
 
@@ -68,8 +68,9 @@ source_mode="npm"
 # remove_one_repo_dir themselves, so packages/fleet/tests/test-manifest.sh
 # can point it at a disposable test_root directory (RECONCILE_SOURCE_ONLY=1)
 # and exercise the real sync/removal mechanics without root or a real
-# /usr/local. Matches packages/fleet/src/launch-agents.ts's
-# DEFAULT_LIBEXEC_DIR in production.
+# /usr/local. The production value is the libexec dir the apps/cli
+# commands (repo-controls, skills, hooks, settings) resolve the projected
+# payload from.
 repo_dir_libexec_root="/usr/local/libexec/adl"
 # Test-only escape hatch for default-agent-file.ts / managed-settings.ts's own
 # `--root` (both already accept it; see their headers). Unset in every real
@@ -109,9 +110,7 @@ failed_tools=()
 # block at the very end, just before "global-tools: reconciliation complete"
 # (Tarun, 2026-09-28). Collected from every step that backs something up
 # before overwriting/removing a file: kimi-hooks (parsed from its own
-# captured "backed up previous config to <path>" note), lean-ctx-observe-strip
-# (2026-09-29, STATUS.md 12p item 13 final scope -- same note shape, parsed
-# by collect_lean_ctx_observe_strip_backups), the global surface sweep
+# captured "backed up previous config to <path>" note), the global surface sweep
 # (parsed from ITS OWN already-printed "global-surface-sweep: backups
 # this run:" block -- never recomputed here, per Tarun's instruction not to
 # duplicate that package's backup logic), and write_one_repo_script below
@@ -156,39 +155,6 @@ collect_kimi_hooks_backups() {
   done <<<"$text"
 }
 
-# Same shape as collect_kimi_hooks_backups, for bin/lean-ctx-observe-strip's
-# own "lean-ctx-observe-strip: backed up previous config to <path>" note --
-# unlike kimi-hooks (always exactly one config file), this step can strip
-# multiple JSON/shell-rc targets in one run, so the loop below (like
-# collect_sweep_backups) records every match, not just the first.
-#
-# A skill-directory backup gets a SECOND, distinct line shape: "backed up
-# previous skill directory <original> to <backup>" (final review finding
-# 1: its backup path is a SIBLING of the scanned skills/ directory, e.g.
-# ".codex/skills.pre-lean-ctx-observe-strip-<ts>/lean-ctx" -- it no longer
-# ends in ".pre-<label>-<timestamp>", so strip_backup_suffix's regex can't
-# recover the original path from it; that note states BOTH paths directly
-# instead, and is matched here as its own case rather than forced through
-# the single-path regex above).
-collect_lean_ctx_observe_strip_backups() {
-  local text="$1" line backup original
-  while IFS= read -r line; do
-    if [[ "$line" =~ ^lean-ctx-observe-strip:\ backed\ up\ previous\ config\ to\ (.+)$ ]]; then
-      backup="${BASH_REMATCH[1]}"
-      record_backup "$(strip_backup_suffix "$backup")" "$backup"
-    elif [[ "$line" =~ ^lean-ctx-observe-strip:\ backed\ up\ previous\ skill\ directory\ (.+)\ to\ (.+)$ ]]; then
-      original="${BASH_REMATCH[1]}"
-      backup="${BASH_REMATCH[2]}"
-      record_backup "$original" "$backup"
-    elif [[ "$line" =~ ^lean-ctx-observe-strip:\ backed\ up\ previous\ hook\ script\ (.+)\ to\ (.+)$ ]]; then
-      # ~/.claude/hooks/lean-ctx-* scripts: same two-path shape as a skill
-      # directory (sibling "hooks.pre-lean-ctx-observe-strip-<ts>/" backup).
-      original="${BASH_REMATCH[1]}"
-      backup="${BASH_REMATCH[2]}"
-      record_backup "$original" "$backup"
-    fi
-  done <<<"$text"
-}
 
 # Folds the global-surface-sweep's OWN already-computed and already-printed
 # backup lines into this run's combined summary, without recomputing
@@ -222,14 +188,16 @@ repo_root="$(cd "$script_dir/.." && pwd)"
 manifest="${manifest:-$repo_root/packages/fleet/manifest.json}"
 # shellcheck source=lib/bun-compile-build.sh
 source "$script_dir/lib/bun-compile-build.sh"
-"$script_dir/validate-manifest" "$manifest" >/dev/null
+# shellcheck source=lib/adl-package.sh
+source "$script_dir/lib/adl-package.sh"
+"$BASH" "$script_dir/validate-manifest" "$manifest" >/dev/null
 if [[ "${RECONCILE_SOURCE_ONLY:-0}" != "1" ]]; then
   if [[ "$source_mode" == npm && -e "$repo_root/.git" ]]; then
-    echo "npm source mode requires an installed package root; use --source checkout for a Git checkout" >&2
+    echo "ERROR npm source mode requires an installed package root; use --source checkout for a Git checkout" >&2
     exit 2
   fi
   if [[ "$source_mode" == checkout && ! -e "$repo_root/.git" ]]; then
-    echo "checkout source mode requires a Git checkout" >&2
+    echo "ERROR checkout source mode requires a Git checkout" >&2
     exit 2
   fi
 fi
@@ -237,7 +205,7 @@ fi
 case "$(uname -s)" in
   Darwin) platform=mac; sha256_cmd=(shasum -a 256) ;;
   Linux) platform=linux; sha256_cmd=(sha256sum) ;;
-  *) echo "unsupported operating system: $(uname -s)" >&2; exit 1 ;;
+  *) echo "ERROR unsupported operating system: $(uname -s)" >&2; exit 1 ;;
 esac
 if [[ -n "$platform_override" ]]; then
   # Applying as a foreign platform would install the wrong platform's tools, so
@@ -248,7 +216,7 @@ if [[ -n "$platform_override" ]]; then
   # agents of the mixed CI pool it dies with "device m3 is not declared under
   # linux" (build 4226).
   if [[ "$mode" == apply && "${RECONCILE_SOURCE_ONLY:-0}" != "1" ]]; then
-    echo "--platform cannot override the host in apply mode" >&2
+    echo "ERROR --platform cannot override the host in apply mode" >&2
     exit 2
   fi
   [[ "$platform_override" == mac || "$platform_override" == linux ]] || usage
@@ -256,7 +224,7 @@ if [[ -n "$platform_override" ]]; then
 fi
 
 jq -e --arg platform "$platform" --arg device "$device" '.[$platform].devices[$device]' "$manifest" >/dev/null || {
-  echo "device $device is not declared under $platform" >&2
+  echo "ERROR device $device is not declared under $platform" >&2
   exit 1
 }
 
@@ -292,7 +260,7 @@ path_owner() {
   elif owner="$(stat -c '%U' "$path" 2>/dev/null)"; then
     printf '%s\n' "$owner"
   else
-    echo "cannot determine owner of Homebrew prefix: $path" >&2
+    echo "ERROR cannot determine owner of Homebrew prefix: $path" >&2
     return 1
   fi
 }
@@ -305,7 +273,7 @@ resolve_brew_owner() {
   fi
   if [[ ! -d "$prefix" ]]; then
     if [[ "$target_mode" == apply ]]; then
-      echo "Homebrew prefix missing: $prefix" >&2
+      echo "ERROR Homebrew prefix missing: $prefix" >&2
       return 1
     fi
     printf '%s\n' '<unresolved-linuxbrew-owner>'
@@ -313,7 +281,7 @@ resolve_brew_owner() {
   fi
   owner="$(path_owner "$prefix")" || return 1
   if [[ "$owner" == root ]]; then
-    echo "Homebrew prefix must be owned by a non-root account: $prefix" >&2
+    echo "ERROR Homebrew prefix must be owned by a non-root account: $prefix" >&2
     return 1
   fi
   printf '%s\n' "$owner"
@@ -329,10 +297,25 @@ run_brew() {
     printf '\n'
     return 0
   fi
-  [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
+  [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
+  if [[ -n "${brew_noninteractive_dir:-}" ]]; then
+    # The upgrade step: no sudo Homebrew spawns may prompt (see run_brew_upgrade_all).
+    (cd /tmp && sudo -u "$brew_owner" -H env -u SUDO_ASKPASS NONINTERACTIVE=1 HOMEBREW_NO_SUDO=1 HOMEBREW_NO_ENV_HINTS=1 PATH="$brew_noninteractive_dir:${brew_bin%/*}:/usr/bin:/bin" "$brew_bin" "$@" </dev/null)
+    return
+  fi
   (cd /tmp && sudo -u "$brew_owner" -H env NONINTERACTIVE=1 PATH="${brew_bin%/*}:/usr/bin:/bin" "$brew_bin" "$@" </dev/null)
 }
 
+# A directory holding a `sudo` that can never prompt: it execs /usr/bin/sudo -n. Put first on the
+# PATH of the brew upgrade step, for anything that calls sudo by name.
+make_brew_noninteractive_shim() {
+  local dir
+  dir="$(mktemp -d "${TMPDIR:-/tmp}/adl-brew-sudo-shim.XXXXXX")" || return 1
+  printf '#!/bin/sh\nexec /usr/bin/sudo -n "$@"\n' >"$dir/sudo"
+  chmod 0755 "$dir" "$dir/sudo"
+  printf '%s\n' "$dir"
+}
+
 # Portable command timeout: neither GNU coreutils' `timeout` nor its `gtimeout`
 # alias is installed by default on a fresh mac (this manifest installs
 # neither), so a real `command -v timeout` gate would silently do nothing on
@@ -382,52 +365,126 @@ run_with_timeout() {
 BREW_UPGRADE_ALL_TIMEOUT_SECONDS="${RECONCILE_BREW_UPGRADE_TIMEOUT_SECONDS:-1200}"
 SURFACE_UPDATE_TIMEOUT_SECONDS="${RECONCILE_SURFACE_UPDATE_TIMEOUT_SECONDS:-300}"
 
-# Upgrades every outdated Homebrew formula AND cask in one call -- never a
-# per-package list, so a formula outdated for reasons unrelated to this
-# manifest (installed once by hand, or a transitive dependency of a manifest
-# formula) still converges instead of accumulating outdated versions forever
-# (item 1, 2026-09-28: `brew update` alone, the only brew-wide step that ran
-# before this, never upgrades anything). Gated by the manifest's own
-# brew_upgrade_all switch at the call site below, not inside this function --
-# this function always does the real (or plan-mode preview) work when called.
+# brew's output for a cask whose upgrade needed sudo but was not allowed to ask: Homebrew refusing
+# ("sudo is disabled by HOMEBREW_NO_SUDO."), or sudo -n failing fast. It never blocks.
+brew_output_needs_password() {
+  grep -Eiq 'sudo is disabled by HOMEBREW_NO_SUDO|sudo: .*(password|terminal|tty|askpass)|^Password:' <<<"$1"
+}
+
+# Upgrades the outdated Homebrew formulae and casks, from ONE `brew outdated --json=v2` (the
+# formulae and casks, with installed and available versions). A formula outdated for reasons
+# unrelated to this manifest (installed once by hand, or a transitive dependency of a manifest
+# formula) still converges instead of accumulating outdated versions forever (item 1,
+# 2026-09-28: `brew update` alone, the only brew-wide step that ran before this, never upgrades
+# anything). Gated by the manifest's own brew_upgrade_all switch at the call site below, not
+# inside this function -- this function always does the real (or plan-mode preview) work when
+# called.
+#
+# Two rules from the live tests (Tarun, 2026-10-01):
+#  - config.brew_upgrade_exclude names packages that are never upgraded here (git: every Homebrew
+#    git upgrade installs an ad-hoc-signed binary at a new Cellar path and re-prompts the
+#    osxkeychain ACL). Not a `brew pin`, not a version pin: an outdated excluded package is one
+#    info line, and the rest is upgraded BY NAME.
+#  - a reconcile NEVER prompts, terminal or not (m5, 2026-10-01: an interactive `sudo adl setup`
+#    got a nested, echoing `Password:` from the visual-studio-code cask's sudo inside brew inside
+#    our sudo -u). Every brew call here runs with stdin /dev/null, SUDO_ASKPASS unset,
+#    HOMEBREW_NO_SUDO=1 (brew refuses before spawning sudo) and a PATH-shimmed `sudo -n`. Casks are
+#    upgraded one at a time; one that needs a password is reported as a WARN with the command to
+#    run by hand and is not a failed tool. A failing formula, or a cask that fails for any other
+#    reason, still fails loud.
 run_brew_upgrade_all() {
+  if [[ "$mode" != apply ]]; then
+    run_brew_upgrade_all_body
+    return
+  fi
+  local status=0
+  brew_noninteractive_dir="$(make_brew_noninteractive_shim)" || { echo "ERROR could not create the brew sudo shim" >&2; return 1; }
+  run_brew_upgrade_all_body || status=$?
+  command rm -rf -- "$brew_noninteractive_dir"
+  brew_noninteractive_dir=""
+  return "$status"
+}
+
+run_brew_upgrade_all_body() {
   if [[ "$mode" != apply ]]; then
     echo "would run: brew upgrade (all outdated formulae and casks)"
+    local planned_excludes
+    planned_excludes="$(jq -r '(.config.brew_upgrade_exclude // []) | join(", ")' "$manifest")"
+    if [[ -n "$planned_excludes" ]]; then
+      echo "brew upgrade excludes (config.brew_upgrade_exclude): $planned_excludes"
+    fi
     return 0
   fi
-  [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
-  local outdated_formulae outdated_casks formulae_count casks_count
-  outdated_formulae="$(brew_query outdated --formula --quiet)" || {
-    echo "brew outdated --formula check failed" >&2
+  [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
+  local outdated_json excluded_names line kind name installed available
+  local -a formulae=() casks=()
+  local skipped=0
+  outdated_json="$(brew_query outdated --json=v2)" || {
+    echo "ERROR brew outdated check failed" >&2
     return 1
   }
-  outdated_casks="$(brew_query outdated --cask --quiet)" || {
-    echo "brew outdated --cask check failed" >&2
+  jq -e '(.formulae | type == "array") and (.casks | type == "array")' >/dev/null 2>&1 <<<"$outdated_json" || {
+    echo "ERROR brew outdated --json=v2 did not print formulae and casks" >&2
     return 1
   }
-  formulae_count=0
-  [[ -z "$outdated_formulae" ]] || formulae_count="$(wc -l <<<"$outdated_formulae" | tr -d ' ')"
-  casks_count=0
-  [[ -z "$outdated_casks" ]] || casks_count="$(wc -l <<<"$outdated_casks" | tr -d ' ')"
+  excluded_names="$(jq -r '(.config.brew_upgrade_exclude // [])[]' "$manifest")"
+  while IFS=$'\t' read -r kind name installed available; do
+    [[ -n "$name" ]] || continue
+    if [[ -n "$excluded_names" ]] && grep -Fxq -- "$name" <<<"$excluded_names"; then
+      echo "global-tools: brew upgrade skips excluded: $name ($installed → $available)"
+      skipped=$((skipped + 1))
+      continue
+    fi
+    if [[ "$kind" == formula ]]; then formulae+=("$name"); else casks+=("$name"); fi
+  done < <(jq -r '
+    def versions: if type == "array" then join(", ") else tostring end;
+    (.formulae[]? | ["formula", .name, (.installed_versions | versions), .current_version]),
+    (.casks[]? | ["cask", .name, (.installed_versions | versions), .current_version]) | @tsv
+  ' <<<"$outdated_json")
+  local formulae_count="${#formulae[@]}" casks_count="${#casks[@]}"
   if [[ "$formulae_count" -eq 0 && "$casks_count" -eq 0 ]]; then
-    echo "brew upgrade: nothing outdated"
+    if [[ "$skipped" -gt 0 ]]; then
+      echo "brew upgrade: nothing left to upgrade after $skipped excluded"
+    else
+      echo "brew upgrade: nothing outdated"
+    fi
     return 0
   fi
-  local upgrade_status=0
   # Routed through run_brew itself (same owner/cwd/stdin wiring as every
   # other brew mutation in this file), bounded by run_with_timeout so a
   # network-stalled `brew upgrade` cannot hang the rest of this run forever.
   # brew's output streams live -- never captured and printed at the end,
   # which left a long upgrade silent for minutes and looking stuck.
   echo "brew upgrade: $formulae_count formulae, $casks_count casks outdated; upgrading (timeout ${BREW_UPGRADE_ALL_TIMEOUT_SECONDS}s)"
-  run_with_timeout "$BREW_UPGRADE_ALL_TIMEOUT_SECONDS" run_brew upgrade 2>&1 || upgrade_status=$?
-  if [[ "$upgrade_status" -eq 124 ]]; then
-    echo "brew upgrade timed out after ${BREW_UPGRADE_ALL_TIMEOUT_SECONDS}s" >&2
-    return 1
-  elif [[ "$upgrade_status" -ne 0 ]]; then
-    echo "brew upgrade failed (exit $upgrade_status)" >&2
-    return 1
+  local upgrade_status=0
+  local failed=0 cask cask_output
+  if [[ "$formulae_count" -gt 0 ]]; then
+    run_with_timeout "$BREW_UPGRADE_ALL_TIMEOUT_SECONDS" run_brew upgrade --formula "${formulae[@]}" 2>&1 || upgrade_status=$?
+    if [[ "$upgrade_status" -eq 124 ]]; then
+      echo "ERROR brew upgrade timed out after ${BREW_UPGRADE_ALL_TIMEOUT_SECONDS}s" >&2
+      return 1
+    elif [[ "$upgrade_status" -ne 0 ]]; then
+      echo "ERROR brew upgrade failed (exit $upgrade_status)" >&2
+      failed=1
+    fi
   fi
+  for cask in ${casks[@]+"${casks[@]}"}; do
+    upgrade_status=0
+    cask_output="$(run_with_timeout "$BREW_UPGRADE_ALL_TIMEOUT_SECONDS" run_brew upgrade --cask "$cask" 2>&1)" || upgrade_status=$?
+    [[ -z "$cask_output" ]] || printf '%s\n' "$cask_output"
+    if [[ "$upgrade_status" -eq 124 ]]; then
+      echo "ERROR brew upgrade timed out after ${BREW_UPGRADE_ALL_TIMEOUT_SECONDS}s ($cask)" >&2
+      return 1
+    elif [[ "$upgrade_status" -ne 0 ]]; then
+      if brew_output_needs_password "$cask_output"; then
+        echo "WARN brew: $cask needs an interactive password to upgrade; run: brew upgrade --cask $cask" >&2
+      else
+        echo "ERROR brew upgrade failed (exit $upgrade_status): $cask" >&2
+        failed=1
+      fi
+    fi
+  done
+  [[ "$failed" -eq 0 ]] || return 1
   echo "brew upgrade: $formulae_count formulae, $casks_count casks were outdated before upgrade"
   return 0
 }
@@ -439,7 +496,7 @@ run_apt() {
     printf '\n'
     return 0
   fi
-  [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
+  [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
   env DEBIAN_FRONTEND=noninteractive apt-get "$@" </dev/null
 }
 
@@ -454,7 +511,7 @@ run_npm() {
     printf '\n'
     return 0
   fi
-  [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
+  [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
   if [[ "$platform" == linux ]]; then
     (cd /tmp && sudo -u "$administrator" -H env npm_config_prefix=/usr/local PATH="${brew_bin%/*}:/usr/bin:/bin" npm "$@" </dev/null)
   else
@@ -538,12 +595,12 @@ canonical_parent_path() {
 npm_package_owns_executable() {
   local package="$1" executable="$2" npm_root package_manifest bin_relative actual_path actual_link expected_target actual_target
   npm_root="$(npm_global_root)" || {
-    echo "could not resolve npm global root for $package" >&2
+    echo "ERROR could not resolve npm global root for $package" >&2
     return 1
   }
   package_manifest="$npm_root/$package/package.json"
   [[ -f "$package_manifest" ]] || {
-    echo "npm package metadata missing: $package_manifest" >&2
+    echo "ERROR npm package metadata missing: $package_manifest" >&2
     return 1
   }
   bin_relative="$(jq -r --arg executable "$executable" '
@@ -553,20 +610,20 @@ npm_package_owns_executable() {
     end
   ' "$package_manifest")"
   [[ -n "$bin_relative" && "$bin_relative" != /* && "$bin_relative" != .. && "$bin_relative" != ../* && "$bin_relative" != */../* && "$bin_relative" != */.. ]] || {
-    echo "npm package $package does not declare a safe bin target for $executable" >&2
+    echo "ERROR npm package $package does not declare a safe bin target for $executable" >&2
     return 1
   }
   actual_path="$(npm_global_executable_path "$executable")" || {
-    echo "npm executable missing from global PATH: $executable" >&2
+    echo "ERROR npm executable missing from global PATH: $executable" >&2
     return 1
   }
   [[ -L "$actual_path" ]] || {
-    echo "npm executable is not an npm-managed symlink: $actual_path" >&2
+    echo "ERROR npm executable is not an npm-managed symlink: $actual_path" >&2
     return 1
   }
   expected_target="$(canonical_parent_path "$npm_root/$package/$bin_relative")" || return 1
   [[ -f "$expected_target" && -x "$expected_target" ]] || {
-    echo "npm package $package bin target is not an executable file: $expected_target" >&2
+    echo "ERROR npm package $package bin target is not an executable file: $expected_target" >&2
     return 1
   }
   actual_link="$(readlink "$actual_path")" || return 1
@@ -576,11 +633,27 @@ npm_package_owns_executable() {
     actual_target="$(canonical_parent_path "${actual_path%/*}/$actual_link")" || return 1
   fi
   [[ "$actual_target" == "$expected_target" ]] || {
-    echo "npm executable $executable is not owned by $package" >&2
+    echo "ERROR npm executable $executable is not owned by $package" >&2
     return 1
   }
 }
 
+# The published package is installed with bun (Tarun, 2026-10-01). Package mode
+# proves the administrator's `adl` IS this package (bin/lib/adl-package.sh, the
+# check bin/setup runs too): a different adl earlier on the administrator's PATH
+# -- a legacy compiled /usr/local/bin/adl from before the package existed -- would
+# keep running instead of the package this job updates, so it fails loud here with
+# the one-line fix instead of being silently tolerated.
+adl_package_owns_executable() {
+  local os package_real
+  case "$platform" in
+    mac) os=Darwin ;;
+    *) os=Linux ;;
+  esac
+  package_real="$(cd -P -- "$repo_root" && pwd -P)" || return 1
+  adl_check_adl_not_shadowed "$administrator" "$os" "$administrator_home" "$package_real" "global-tools"
+}
+
 run_pip() {
   if [[ "$mode" != apply ]]; then
     printf 'would run pip as %s: python3 -m pip' "$administrator"
@@ -588,21 +661,21 @@ run_pip() {
     printf '\n'
     return 0
   fi
-  [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
+  [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
   (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" python3 -m pip "$@" </dev/null)
 }
 
 pip_user_executable() {
   local executable="$1"
   [[ "$executable" != */* ]] || {
-    echo "pip executable must be a command name, not a path: $executable" >&2
+    echo "ERROR pip executable must be a command name, not a path: $executable" >&2
     exit 1
   }
   local user_base user_home
   user_home="$(cd /tmp && sudo -u "$administrator" -H /bin/sh -c 'printf "%s\n" "$HOME"')"
   user_base="$(cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" python3 -m site --user-base)"
   [[ "$user_base" == "$user_home" || "$user_base" == "$user_home"/* ]] || {
-    echo "pip user base is outside the declared administrator home: $user_base" >&2
+    echo "ERROR pip user base is outside the declared administrator home: $user_base" >&2
     exit 1
   }
   printf '%s/bin/%s\n' "${user_base%/}" "$executable"
@@ -615,11 +688,11 @@ ensure_global_pip_executable() {
     echo "would expose pip executable globally: $target"
     return 0
   fi
-  [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
+  [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
   local source existing_source user_home
   source="$(pip_user_executable "$executable")"
   user_home="$(cd /tmp && sudo -u "$administrator" -H /bin/sh -c 'printf "%s\n" "$HOME"')"
-  [[ -x "$source" ]] || { echo "pip executable missing after install: $source" >&2; exit 1; }
+  [[ -x "$source" ]] || { echo "ERROR pip executable missing after install: $source" >&2; exit 1; }
   if [[ -L "$target" ]]; then
     existing_source="$(readlink "$target")"
     if [[ "$existing_source" == "$source" ]]; then
@@ -628,10 +701,10 @@ ensure_global_pip_executable() {
     fi
     case "$existing_source" in
       "$user_home"/*/bin/"$executable") ;;
-      *) echo "refusing to replace unrelated symlink: $target -> $existing_source" >&2; exit 1 ;;
+      *) echo "ERROR refusing to replace unrelated symlink: $target -> $existing_source" >&2; exit 1 ;;
     esac
   elif [[ -e "$target" ]]; then
-    echo "refusing to replace unrelated global executable: $target" >&2
+    echo "ERROR refusing to replace unrelated global executable: $target" >&2
     exit 1
   fi
   ln -sfn "$source" "$target"
@@ -645,17 +718,17 @@ remove_global_pip_executable() {
     echo "would remove global pip executable: $target"
     return 0
   fi
-  [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
+  [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
   if [[ ! -e "$target" && ! -L "$target" ]]; then
     return 0
   fi
-  [[ -L "$target" ]] || { echo "refusing to remove unrelated global executable: $target" >&2; exit 1; }
+  [[ -L "$target" ]] || { echo "ERROR refusing to remove unrelated global executable: $target" >&2; exit 1; }
   local source user_home
   source="$(readlink "$target")"
   user_home="$(cd /tmp && sudo -u "$administrator" -H /bin/sh -c 'printf "%s\n" "$HOME"')"
   case "$source" in
     "$user_home"/*/bin/"$executable") rm -f -- "$target" ;;
-    *) echo "refusing to remove unrelated symlink: $target -> $source" >&2; exit 1 ;;
+    *) echo "ERROR refusing to remove unrelated symlink: $target -> $source" >&2; exit 1 ;;
   esac
 }
 
@@ -705,12 +778,12 @@ bun_source_hash() {
   local source_dir="$1" hash
   if repo_root_is_git; then
     hash="$(repo_git rev-parse --verify --quiet "HEAD:$source_dir")" || {
-      echo "bun-compile source is not tracked at HEAD: $source_dir" >&2
+      echo "ERROR bun-compile source is not tracked at HEAD: $source_dir" >&2
       return 1
     }
   else
     [[ -d "$repo_root/$source_dir" ]] || {
-      echo "bun-compile source missing from installed package: $repo_root/$source_dir" >&2
+      echo "ERROR bun-compile source missing from installed package: $repo_root/$source_dir" >&2
       return 1
     }
     hash="$(content_tree_hash "$repo_root/$source_dir")"
@@ -732,17 +805,17 @@ run_bun_compile() {
     printf 'would build and install bun binary: %s -> %s (source %s)\n' "$package" "$target" "$source_hash"
     return 0
   fi
-  [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
-  [[ "$target" == /usr/local/bin/* ]] || { echo "bun-compile target must be under /usr/local/bin: $target" >&2; exit 1; }
+  [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
+  [[ "$target" == /usr/local/bin/* ]] || { echo "ERROR bun-compile target must be under /usr/local/bin: $target" >&2; exit 1; }
   [[ "$source_dir" != /* && "$source_dir" != *..* ]] || {
-    echo "unsafe bun-compile source path: $source_dir" >&2
+    echo "ERROR unsafe bun-compile source path: $source_dir" >&2
     exit 1
   }
   local project_dir="$repo_root/$source_dir"
-  [[ -d "$project_dir" ]] || { echo "bun-compile source missing: $project_dir" >&2; exit 1; }
+  [[ -d "$project_dir" ]] || { echo "ERROR bun-compile source missing: $project_dir" >&2; exit 1; }
   local bun_bin
   bun_bin="$(command -v bun || true)"
-  [[ -n "$bun_bin" ]] || { echo "bun-compile requires bun on PATH; ensure bun installs before this tool" >&2; exit 1; }
+  [[ -n "$bun_bin" ]] || { echo "ERROR bun-compile requires bun on PATH; ensure bun installs before this tool" >&2; exit 1; }
   (cd "$project_dir" && "$bun_bin" install --frozen-lockfile)
   bun_compile_build "$bun_bin" "$project_dir/$entry" "$target"
 }
@@ -751,20 +824,19 @@ run_embedding_model() {
   local package="$1"
   local spec_json="$2"
   if [[ "$mode" != apply ]]; then
-    printf 'would install embedding model: %s as %s -> ~/.cache/adl-embedding/model\n' "$package" "$administrator"
+    printf 'would install embedding model: %s as %s -> ~/.cache/enact-embedding/model\n' "$package" "$administrator"
     return 0
   fi
-  [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
-  command -v bun >/dev/null 2>&1 || { echo "embedding-model requires bun; ensure bun installs before this tool" >&2; exit 1; }
+  [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
+  command -v bun >/dev/null 2>&1 || { echo "ERROR embedding-model requires bun; ensure bun installs before this tool" >&2; exit 1; }
   (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
     bun "$repo_root/packages/fleet/src/install-embedding-model.ts" install --spec "$spec_json" </dev/null)
 }
 
 # Installs $src as $dest via a same-directory temp-file + rename, never a
 # direct in-place write -- so a concurrent reader (including the next agent
-# shell's `command -v $dest`, per the lean-ctx incident this fixed: an
-# in-place npm postinstall rewrite left the shim executing but printing
-# "binary not found" for ~44s on every scheduled reconcile) can never observe
+# shell's `command -v $dest`, which could otherwise observe an executable
+# partway through an in-place rewrite) can never observe
 # $dest existing but only partially written. `mv` within the same directory
 # is a single rename(2) on both Darwin and Linux -- atomic by construction,
 # not by scheduling luck.
@@ -782,9 +854,9 @@ install_surface_policy_file() {
     echo "would install required surface policy: $source -> $target"
     return 0
   fi
-  [[ -f "$source" ]] || { echo "surface policy source missing: $source" >&2; return 1; }
+  [[ -f "$source" ]] || { echo "ERROR surface policy source missing: $source" >&2; return 1; }
   jq -e '(.deny.paths | arrays) and (.deny.nativeTools | arrays)' "$source" >/dev/null || {
-    echo "surface policy source is invalid: $source" >&2
+    echo "ERROR surface policy source is invalid: $source" >&2
     return 1
   }
   mkdir -p /etc/adl
@@ -795,8 +867,8 @@ install_surface_policy_file() {
 
 # A resolved release version against the first line of a release-archive-
 # latest tool's own `--version` output. Different tools format that line
-# differently -- lean-ctx: "lean-ctx 3.10.5 (official, ...)" (version padded
-# by spaces on both sides); agent-vault: "agent-vault version 0.39.3" (flush
+# differently -- some include parenthetical metadata; agent-vault prints
+# "agent-vault version 0.39.3" (flush
 # against the end of the line, no trailing space); a plain "vX.Y.Z" line
 # with no separating space before the version at all -- so the LEFT boundary
 # is a string start or a real space, with an OPTIONAL literal "v" directly
@@ -823,7 +895,7 @@ resolve_latest_release_tag() {
   local repo="$1"
   local location
   location="$(curl --proto '=https' --proto-redir '=https' -fsS -o /dev/null -w '%{redirect_url}' "https://github.com/$repo/releases/latest")"
-  [[ -n "$location" ]] || { echo "could not resolve latest release tag for $repo" >&2; exit 1; }
+  [[ -n "$location" ]] || { echo "ERROR could not resolve latest release tag for $repo" >&2; exit 1; }
   basename "$location"
 }
 
@@ -854,10 +926,10 @@ run_release_archive_latest() {
   local checksums_asset="$5"
   local archive_executable="$6"
   local target="$7"
-  [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
-  [[ "$target" == /usr/local/bin/* ]] || { echo "release archive target must be under /usr/local/bin: $target" >&2; exit 1; }
+  [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
+  [[ "$target" == /usr/local/bin/* ]] || { echo "ERROR release archive target must be under /usr/local/bin: $target" >&2; exit 1; }
   [[ "$archive_executable" != /* && "$archive_executable" != *..* ]] || {
-    echo "unsafe archive executable path: $archive_executable" >&2
+    echo "ERROR unsafe archive executable path: $archive_executable" >&2
     exit 1
   }
 
@@ -872,7 +944,7 @@ run_release_archive_latest() {
     curl --proto '=https' --proto-redir '=https' -fsSL --retry 3 \
       -o "$checksums_file" "https://github.com/$repo/releases/download/$tag/$checksums_asset"
     expected_sha256="$(awk -v want="$asset" '$2 == want { print $1; found = 1 } END { exit !found }' "$checksums_file")" || {
-      echo "no published checksum for $asset in $repo's $checksums_asset -- refusing to install unverified bytes" >&2
+      echo "ERROR no published checksum for $asset in $repo's $checksums_asset -- refusing to install unverified bytes" >&2
       exit 1
     }
     curl --proto '=https' --proto-redir '=https' -fsSL --retry 3 \
@@ -880,15 +952,15 @@ run_release_archive_latest() {
     case "$(uname -s)" in
       Darwin) actual_sha256="$(shasum -a 256 "$archive_file" | awk '{print $1}')" ;;
       Linux) actual_sha256="$(sha256sum "$archive_file" | awk '{print $1}')" ;;
-      *) echo "unsupported operating system for release archive" >&2; exit 1 ;;
+      *) echo "ERROR unsupported operating system for release archive" >&2; exit 1 ;;
     esac
     [[ "$actual_sha256" == "$expected_sha256" ]] || {
-      echo "checksum mismatch for $package (latest): expected $expected_sha256 from published $checksums_asset, got $actual_sha256" >&2
+      echo "ERROR checksum mismatch for $package (latest): expected $expected_sha256 from published $checksums_asset, got $actual_sha256" >&2
       exit 1
     }
     tar -xzf "$archive_file" -C "$extract_dir" "$archive_executable"
     [[ -f "$extract_dir/$archive_executable" ]] || {
-      echo "archive executable missing: $archive_executable" >&2
+      echo "ERROR archive executable missing: $archive_executable" >&2
       exit 1
     }
     atomic_install_executable "$extract_dir/$archive_executable" "$target"
@@ -926,7 +998,7 @@ resolve_surface_mode() {
 # root") is a real environment fault, not a flaky install, and still
 # aborts immediately -- `exit` is unconditional and is never caught here.
 install_one_tool() {
-  local tool_id="$1" manager package executable previous_executable migrating_from_bun=0 rc=0 npm_spec npm_allow_scripts npm_target_version npm_installed_ver brew_outdated_output brew_installed_version
+  local tool_id="$1" manager package executable previous_executable migrating_from_bun=0 rc=0 npm_spec npm_allow_scripts npm_target_version npm_installed_ver brew_outdated_output brew_installed_version trust_kind
   manager="$(jq -r --arg id "$tool_id" '.[$id].manager' "$resolved_file")"
   package="$(jq -r --arg id "$tool_id" '.[$id].package' "$resolved_file")"
   executable="$(jq -r --arg id "$tool_id" '.[$id].executable' "$resolved_file")"
@@ -934,25 +1006,82 @@ install_one_tool() {
     echo "ensure Adl from explicit checkout source: $repo_root"
     build_checkout_adl || rc=1
     if [[ "$mode" == apply && "$rc" -eq 0 ]]; then
-      command -v "$executable" >/dev/null 2>&1 || { echo "checkout Adl executable missing from PATH: $executable" >&2; rc=1; }
+      command -v "$executable" >/dev/null 2>&1 || { echo "ERROR checkout Adl executable missing from PATH: $executable" >&2; rc=1; }
     fi
     return "$rc"
   fi
   if [[ "$tool_id" == adl && "$source_mode" == npm ]]; then
     if [[ "$mode" != apply ]]; then
-      echo "would use installed npm package payload: $repo_root"
+      echo "would use installed package payload: $repo_root"
       return 0
     fi
     if is_in_place_bun_to_npm_migration "$tool_id"; then
       prepare_in_place_bun_to_npm_migration "$tool_id" || return 1
     fi
-    npm_package_owns_executable "$package" "$executable" || return 1
-    echo "using installed npm package payload: $repo_root"
+    adl_package_owns_executable || return 1
+    echo "using installed package payload: $repo_root"
     return 0
   fi
   echo "ensure latest stable: $tool_id ($manager:$package)"
   case "$manager" in
     brew)
+      # Optional declared tap (manifest .tap, owner/repo): fully-qualified
+      # package names (e.g. stablyai/orca/orca) refuse to resolve until their
+      # tap exists, and Homebrew will not auto-tap a non-core tap for a
+      # noninteractive caller — so reconcile taps it first, idempotently.
+      # Tarun 2026-10-02: orca is brew-managed from Stably's own tap; that
+      # cask is auto_updates, so the per-tool path installs-if-missing and
+      # the in-app updater owns versioning — no version is ever pinned here.
+      tap="$(jq -r --arg id "$tool_id" '.[$id].tap // ""' "$resolved_file")"
+      if [[ "$rc" -eq 0 && -n "$tap" ]]; then
+        [[ "$tap" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || {
+          echo "ERROR refusing unsafe brew tap name for $tool_id: $tap" >&2
+          rc=1
+        }
+      fi
+      if [[ "$rc" -eq 0 && -n "$tap" && "$mode" == apply ]]; then
+        brew_query tap | grep -Fqx "$tap" || run_brew tap "$tap" || {
+          echo "ERROR $tool_id: brew tap $tap failed" >&2
+          rc=1
+        }
+      fi
+      # Homebrew >=6 tap trust (brew 7.0.7 on this fleet; the 2026-10 orca
+      # install failure was exactly this refusal): a command that must load an
+      # untrusted non-core tap FAILS until trust is granted, noninteractively
+      # or not. Grant ITEM-level trust for the declared package only --
+      # brew's own automation guidance is `brew trust --formula|--cask
+      # owner/repo/item`, never the whole tap. Gated on the same declared
+      # .tap as the tap step above: that manifest field is the reviewed trust
+      # boundary, and a bare core package (curl, ripgrep) needs no grant.
+      if [[ "$rc" -eq 0 && -n "$tap" && "$mode" == apply ]]; then
+        # The kind is resolved, never guessed: a fully-qualified name is
+        # loadable exactly as one of formula/cask once its tap exists.
+        if brew_query info --formula "$package" >/dev/null 2>&1; then
+          trust_kind=formula
+        elif brew_query info --cask "$package" >/dev/null 2>&1; then
+          trust_kind=cask
+        else
+          echo "ERROR $tool_id: cannot determine whether $package is a formula or a cask — refusing to guess its trust kind" >&2
+          rc=1
+        fi
+        # `brew trust` (list) prints each granted item on its own line,
+        # indented under a "Trusted formulae:"/"Trusted casks:" header
+        # (verified on brew 7.0.7) -- trim, then exact-line match so a
+        # whole-tap grant ("Trusted taps: owner/repo") can never satisfy the
+        # item check.
+        if [[ "$rc" -eq 0 ]]; then
+          brew_query trust | awk '{$1=$1};1' | grep -Fqx "$package" || run_brew trust "--$trust_kind" "$package" || {
+            echo "ERROR $tool_id: brew trust --$trust_kind $package failed" >&2
+            rc=1
+          }
+        fi
+      elif [[ "$rc" -eq 0 && -n "$tap" ]]; then
+        # Plan mode: brew_query is apply-only (see its own header comment),
+        # so the kind is not resolved for a preview -- name the grant anyway.
+        echo "would trust Homebrew item: $package (formula|cask)"
+      fi
+      if [[ "$rc" -ne 0 ]]; then
+        :
       # Plan mode's message is intentionally unconditional (see brew_query's
       # own comment for why: a real up-to-date check is slow enough on a
       # loaded box to defeat the point of a quick preview). Apply mode pays
@@ -960,7 +1089,7 @@ install_one_tool() {
       # run `brew upgrade` on an already-current formula -- which brew itself
       # accepts silently (prints "Warning: <pkg> <ver> already installed" and
       # exits 0), the exact per-run noise this replaces.
-      if [[ "$mode" != apply ]]; then
+      elif [[ "$mode" != apply ]]; then
         echo "would install or upgrade Homebrew formula: $package"
       elif brew_query list --formula "$package" >/dev/null 2>&1; then
         if brew_outdated_output="$(brew_query outdated --formula --quiet "$package")"; then
@@ -971,7 +1100,7 @@ install_one_tool() {
             run_brew upgrade "$package" || rc=1
           fi
         else
-          echo "$tool_id: brew outdated check failed for $package" >&2
+          echo "ERROR $tool_id: brew outdated check failed for $package" >&2
           rc=1
         fi
       else
@@ -1012,12 +1141,12 @@ install_one_tool() {
           prepare_in_place_bun_to_npm_migration "$tool_id" || rc=1
         fi
         if [[ "$rc" -eq 0 ]] && ! npm_target_version="$(npm_latest_version "$package")"; then
-          echo "$tool_id: npm view could not resolve the latest version of $package" >&2
+          echo "ERROR $tool_id: npm view could not resolve the latest version of $package" >&2
           rc=1
         fi
         if [[ "$rc" -eq 0 ]]; then
           if ! npm_installed_ver="$(npm_installed_version "$package")"; then
-            echo "$tool_id: npm ls -g could not inspect the global install of $package" >&2
+            echo "ERROR $tool_id: npm ls -g could not inspect the global install of $package" >&2
             rc=1
           elif [[ -n "$npm_installed_ver" && "$npm_installed_ver" == "$npm_target_version" ]]; then
             echo "already latest: $tool_id (npm:$package@$npm_installed_ver)"
@@ -1053,10 +1182,8 @@ install_one_tool() {
         latest_tag="$(resolve_latest_release_tag "$repo")" || { rc=1; latest_tag=""; }
         if [[ "$rc" -eq 0 ]]; then
           latest_version="${latest_tag#v}"
-          # A release whose asset filename bakes in the version (agent-vault:
-          # agent-vault_<ver>_darwin_arm64.tar.gz) declares "{version}" in
-          # .asset/.checksums_asset; lean-ctx's own asset names carry no
-          # version at all, so this is a no-op substring replace for it.
+          # A release whose asset filename bakes in the version declares
+          # "{version}" in .asset/.checksums_asset; otherwise this is a no-op.
           resolved_asset="${asset//\{version\}/$latest_version}"
           resolved_checksums_asset="${checksums_asset//\{version\}/$latest_version}"
           if [[ -x "$executable" ]] &&
@@ -1068,15 +1195,15 @@ install_one_tool() {
         fi
       fi
       ;;
-    *) echo "unsupported manager: $manager" >&2; rc=1 ;;
+    *) echo "ERROR unsupported manager: $manager" >&2; rc=1 ;;
   esac
   if [[ "$mode" == apply && "$rc" -eq 0 ]]; then
     if [[ "$executable" == /* ]]; then
-      [[ -x "$executable" ]] || { echo "$tool_id executable missing: $executable" >&2; rc=1; }
+      [[ -x "$executable" ]] || { echo "ERROR $tool_id executable missing: $executable" >&2; rc=1; }
     else
       local executable_path
       executable_path="$(sudo -u "$administrator" -H env PATH="/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/local/bin:/usr/bin:/bin" /bin/sh -c "command -v '$executable'" 2>/dev/null || true)"
-      [[ -n "$executable_path" ]] || { echo "$tool_id executable missing from global PATH: $executable" >&2; rc=1; }
+      [[ -n "$executable_path" ]] || { echo "ERROR $tool_id executable missing from global PATH: $executable" >&2; rc=1; }
     fi
   fi
   return "$rc"
@@ -1102,11 +1229,11 @@ is_in_place_bun_to_npm_migration() {
 remove_retired_bun_compilation() {
   local tool_id="$1" executable="$2" hash_file
   [[ "$tool_id" =~ ^[A-Za-z0-9][A-Za-z0-9._-]*$ ]] || {
-    echo "unsafe retired Bun compilation tool id: $tool_id" >&2
+    echo "ERROR unsafe retired Bun compilation tool id: $tool_id" >&2
     return 1
   }
   [[ "$executable" =~ ^/usr/local/bin/[A-Za-z0-9][A-Za-z0-9._-]*$ ]] || {
-    echo "refusing unsafe retired Bun binary removal target: $executable" >&2
+    echo "ERROR refusing unsafe retired Bun binary removal target: $executable" >&2
     return 1
   }
   hash_file="$(bun_source_hash_file "$tool_id")"
@@ -1128,10 +1255,17 @@ prepare_in_place_bun_to_npm_migration() {
   if [[ -L "$migration_path" ]]; then
     package="$(jq -r --arg id "$tool_id" '.[$id].package' "$resolved_file")"
     executable="$(jq -r --arg id "$tool_id" '.[$id].executable' "$resolved_file")"
-    npm_package_owns_executable "$package" "$executable" || {
-      echo "refusing to remove an executable symlink not owned by npm: $previous_executable" >&2
-      return 1
-    }
+    if [[ "$tool_id" == adl && "$source_mode" == npm ]]; then
+      adl_package_owns_executable || {
+        echo "ERROR refusing to remove an executable symlink not owned by the installed package: $previous_executable" >&2
+        return 1
+      }
+    else
+      npm_package_owns_executable "$package" "$executable" || {
+        echo "ERROR refusing to remove an executable symlink not owned by npm: $previous_executable" >&2
+        return 1
+      }
+    fi
     hash_file="$(bun_source_hash_file "$tool_id")"
     rm -f -- "$hash_file" || return 1
     echo "retained npm-owned executable and removed retired Bun marker: $previous_executable ($hash_file)"
@@ -1144,7 +1278,7 @@ failed_in_place_npm_migration() {
   local tool_id
   for tool_id in ${failed_tools[@]+"${failed_tools[@]}"}; do
     if is_in_place_bun_to_npm_migration "$tool_id"; then
-      echo "global-tools: npm migration failed for $tool_id; retired Bun command was removed and reconciliation must stop" >&2
+      echo "ERROR global-tools: npm migration failed for $tool_id; retired Bun command was removed and reconciliation must stop" >&2
       return 0
     fi
   done
@@ -1181,7 +1315,7 @@ build_one_bun_tool() {
   fi
   run_bun_compile "$package" "$source_hash" "$source_dir" "$entry" "$executable" || rc=1
   if [[ "$mode" == apply && "$rc" -eq 0 ]]; then
-    [[ -x "$executable" ]] || { echo "$tool_id executable missing: $executable" >&2; rc=1; }
+    [[ -x "$executable" ]] || { echo "ERROR $tool_id executable missing: $executable" >&2; rc=1; }
   fi
   if [[ "$mode" == apply && "$rc" -eq 0 ]]; then
     mkdir -p "${hash_file%/*}"
@@ -1202,7 +1336,7 @@ build_checkout_adl() {
   fi
   run_bun_compile adl "$source_hash" "$source_dir" "$entry" "$target" || rc=1
   if [[ "$mode" == apply && "$rc" -eq 0 ]]; then
-    [[ -x "$target" ]] || { echo "checkout Adl executable missing: $target" >&2; rc=1; }
+    [[ -x "$target" ]] || { echo "ERROR checkout Adl executable missing: $target" >&2; rc=1; }
     if [[ "$rc" -eq 0 ]]; then
       mkdir -p "${hash_file%/*}"
       printf '%s\n' "$source_hash" >"$hash_file.new"
@@ -1213,7 +1347,7 @@ build_checkout_adl() {
   return "$rc"
 }
 
-# embedding-model installs the adl-embedding static (Model2Vec) artifact
+# embedding-model installs the enact-embedding static (Model2Vec) artifact
 # that adl hook's (the folded-in hook engine's) skill-match hook loads
 # from the administrator's cache.
 # It runs as the declared administrator (root on Linux) so the hook and
@@ -1243,16 +1377,16 @@ write_one_shim() {
   executable="$(jq -r --arg id "$tool_id" '.[$id].executable' "$resolved_file")"
   echo "ensure shim: $tool_id (shim:$package -> $executable)"
   [[ "$executable" == /usr/local/bin/* ]] || {
-    echo "refusing unsafe shim target: $executable" >&2
+    echo "ERROR refusing unsafe shim target: $executable" >&2
     return 1
   }
   if [[ "$mode" != apply ]]; then
     echo "would write shim: $executable -> $package"
     return 0
   fi
-  [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
+  [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
   target_path="$(sudo -u "$administrator" -H env PATH="/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/local/bin:/usr/bin:/bin" /bin/sh -c "command -v '$package'" 2>/dev/null || true)"
-  [[ -n "$target_path" ]] || { echo "shim target not yet on PATH: $package" >&2; return 1; }
+  [[ -n "$target_path" ]] || { echo "ERROR shim target not yet on PATH: $package" >&2; return 1; }
   content="#!/bin/sh
 # Generated by global-tools -- do not edit.
 exec '$target_path' \"\$@\"
@@ -1270,7 +1404,7 @@ exec '$target_path' \"\$@\"
   alias_name="$(basename "$executable")"
   resolved_alias="$(sudo -u "$administrator" -H env PATH="/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/local/bin:/usr/bin:/bin" /bin/sh -c "command -v '$alias_name'" 2>/dev/null || true)"
   [[ "$resolved_alias" == "$executable" ]] || {
-    echo "$tool_id shim written but not resolving from global PATH as '$alias_name' (got: ${resolved_alias:-nothing})" >&2
+    echo "ERROR $tool_id shim written but not resolving from global PATH as '$alias_name' (got: ${resolved_alias:-nothing})" >&2
     rc=1
   }
   return "$rc"
@@ -1283,7 +1417,7 @@ managed_repo_script_marker='# Managed by adl global-tools.'
 # real, previously-self-installed files as "unmanaged", so apply mode refused
 # to update them ("refusing to replace unmanaged or symlinked managed script
 # target") instead of replacing them with the renamed source -- seen live on
-# M3's `fleet-cutover.sh --apply` for /usr/local/bin/git and
+# M3's `packages/fleet/scripts/fleet-cutover.sh --apply` for /usr/local/bin/git and
 # /usr/local/bin/git-ado. A target carrying EITHER line is this writer's own
 # prior output and must still be treated as managed; a target carrying
 # neither (or a symlink) must keep being refused.
@@ -1316,16 +1450,18 @@ write_one_repo_script() {
   source="$(jq -r --arg id "$tool_id" '.[$id].source' "$resolved_file")"
   echo "ensure managed repo script: $tool_id (repo-script:$package -> $executable)"
   [[ "$executable" =~ ^/usr/local/bin/[A-Za-z0-9][A-Za-z0-9._-]*$ ]] || {
-    echo "unsafe managed script target: $executable" >&2
+    echo "ERROR unsafe managed script target: $executable" >&2
     return 1
   }
   [[ "$source" != /* && "$source" != *..* ]] || {
-    echo "unsafe managed script source: $source" >&2
+    echo "ERROR unsafe managed script source: $source" >&2
     return 1
   }
   source_path="$repo_root/$source"
-  [[ -f "$source_path" && ! -L "$source_path" && -x "$source_path" ]] || {
-    echo "managed script source must be an executable regular non-symlink file: $source_path" >&2
+  # -f, not -x: bun leaves every shipped file but the `bin` targets 0644, and the
+  # copy below is installed 0755.
+  [[ -f "$source_path" && ! -L "$source_path" ]] || {
+    echo "ERROR managed script source must be a regular non-symlink file: $source_path" >&2
     return 1
   }
   if [[ "$mode" != apply ]]; then
@@ -1339,10 +1475,10 @@ write_one_repo_script() {
     fi
     return 0
   fi
-  [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
+  [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
   if [[ -e "$executable" || -L "$executable" ]]; then
     is_managed_repo_script "$executable" || {
-      echo "refusing to replace unmanaged or symlinked managed script target: $executable" >&2
+      echo "ERROR refusing to replace unmanaged or symlinked managed script target: $executable" >&2
       return 1
     }
   fi
@@ -1361,7 +1497,7 @@ write_one_repo_script() {
         echo "backed up previous managed repo script to $repo_script_backup"
         record_backup "$executable" "$repo_script_backup"
       else
-        echo "could not back up managed repo script before replacing it: $executable" >&2
+        echo "ERROR could not back up managed repo script before replacing it: $executable" >&2
         return 1
       fi
     fi
@@ -1371,7 +1507,7 @@ write_one_repo_script() {
   alias_name="$(basename "$executable")"
   resolved_alias="$(sudo -u "$administrator" -H env PATH="/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/bin:/bin" /bin/sh -c 'command -v "$1"' sh "$alias_name" 2>/dev/null || true)"
   [[ "$resolved_alias" == "$executable" ]] || {
-    echo "$tool_id managed script installed but not resolving from global PATH as '$alias_name' (got: ${resolved_alias:-nothing})" >&2
+    echo "ERROR $tool_id managed script installed but not resolving from global PATH as '$alias_name' (got: ${resolved_alias:-nothing})" >&2
     rc=1
   }
   return "$rc"
@@ -1380,14 +1516,14 @@ write_one_repo_script() {
 remove_one_repo_script() {
   local executable="$1"
   [[ "$executable" =~ ^/usr/local/bin/[A-Za-z0-9][A-Za-z0-9._-]*$ ]] || {
-    echo "refusing unsafe managed script removal target: $executable" >&2
+    echo "ERROR refusing unsafe managed script removal target: $executable" >&2
     return 1
   }
   if [[ ! -e "$executable" && ! -L "$executable" ]]; then
     return 0
   fi
   is_managed_repo_script "$executable" || {
-    echo "refusing to remove unmanaged or symlinked managed script target: $executable" >&2
+    echo "ERROR refusing to remove unmanaged or symlinked managed script target: $executable" >&2
     return 1
   }
   rm -f -- "$executable"
@@ -1400,7 +1536,7 @@ repo_dir_source_hash() {
   local source_dir="$1" hash
   if repo_root_is_git; then
     hash="$(repo_git rev-parse --verify --quiet "HEAD:$source_dir")" || {
-      echo "repo-dir source is not tracked at HEAD: $source_dir" >&2
+      echo "ERROR repo-dir source is not tracked at HEAD: $source_dir" >&2
       return 1
     }
   else
@@ -1452,7 +1588,7 @@ managed_repo_dir_marker='.adl-managed-repo-dir'
 # have to provide.
 run_repo_dir_sync() {
   local tool_id="$1" source="$2" build_dir="$3" npm_install="$4" bun_bin
-  [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
+  [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
   if repo_root_is_git; then
     repo_git archive "HEAD:$source" | tar -x -C "$build_dir"
   else
@@ -1463,8 +1599,8 @@ run_repo_dir_sync() {
   fi
   if [[ "$npm_install" == true ]]; then
     bun_bin="$(command -v bun || true)"
-    [[ -n "$bun_bin" ]] || { echo "repo-dir $tool_id requires bun on PATH for npmInstall; ensure bun installs before this tool" >&2; return 1; }
-    (cd "$build_dir" && "$bun_bin" install) || { echo "repo-dir $tool_id: bun install failed" >&2; return 1; }
+    [[ -n "$bun_bin" ]] || { echo "ERROR repo-dir $tool_id requires bun on PATH for npmInstall; ensure bun installs before this tool" >&2; return 1; }
+    (cd "$build_dir" && "$bun_bin" install) || { echo "ERROR repo-dir $tool_id: bun install failed" >&2; return 1; }
     # agent-skills (the only npmInstall:true source today) ships no `dist/`
     # in git -- every one of its script entry points imports from
     # `../../dist/index.js` (confirmed empirically, all four: run-sync,
@@ -1474,7 +1610,7 @@ run_repo_dir_sync() {
     # the package's own declared `build` script, exactly as a developer
     # would, whenever the synced package.json has one.
     if [[ "$(jq -r '.scripts.build // empty' "$build_dir/package.json" 2>/dev/null)" != "" ]]; then
-      (cd "$build_dir" && "$bun_bin" run build) || { echo "repo-dir $tool_id: bun run build failed" >&2; return 1; }
+      (cd "$build_dir" && "$bun_bin" run build) || { echo "ERROR repo-dir $tool_id: bun run build failed" >&2; return 1; }
     fi
   fi
 }
@@ -1535,16 +1671,16 @@ write_one_repo_dir() {
   npm_install="$(jq -r --arg id "$tool_id" '.[$id].npmInstall // false' "$resolved_file")"
   echo "ensure repo dir: $tool_id (repo-dir:$package -> $target)"
   [[ "$target" == "$repo_dir_libexec_root"/* ]] || {
-    echo "unsafe repo-dir target: $target" >&2
+    echo "ERROR unsafe repo-dir target: $target" >&2
     return 1
   }
   [[ "$source" != /* && "$source" != *..* ]] || {
-    echo "unsafe repo-dir source: $source" >&2
+    echo "ERROR unsafe repo-dir source: $source" >&2
     return 1
   }
   source_path="$repo_root/$source"
   [[ -d "$source_path" ]] || {
-    echo "repo-dir source missing: $source_path" >&2
+    echo "ERROR repo-dir source missing: $source_path" >&2
     return 1
   }
   source_hash="$(repo_dir_source_hash "$source")" || return 1
@@ -1588,7 +1724,7 @@ write_one_repo_dir() {
     fi
   fi
   [[ -e "$target/$executable" ]] || {
-    echo "$tool_id repo dir installed but entry missing: $target/$executable" >&2
+    echo "ERROR $tool_id repo dir installed but entry missing: $target/$executable" >&2
     rc=1
   }
   return "$rc"
@@ -1597,12 +1733,12 @@ write_one_repo_dir() {
 remove_one_repo_dir() {
   local target="$1"
   [[ "$target" == "$repo_dir_libexec_root"/* ]] || {
-    echo "refusing unsafe repo-dir removal target: $target" >&2
+    echo "ERROR refusing unsafe repo-dir removal target: $target" >&2
     return 1
   }
   [[ -e "$target" ]] || return 0
   [[ -f "$target/$managed_repo_dir_marker" ]] || {
-    echo "refusing to remove unmanaged repo dir: $target" >&2
+    echo "ERROR refusing to remove unmanaged repo dir: $target" >&2
     return 1
   }
   rm -rf -- "$target"
@@ -1680,10 +1816,31 @@ executable_claimed_by_current_manifest() {
 # into its own function, like install_one_tool, so
 # packages/fleet/tests/test-manifest.sh can exercise it directly through the
 # RECONCILE_SOURCE_ONLY seam instead of only through a real apply run.
+remove_release_archive_executable() {
+  local executable="$1" label="$2" target="$executable"
+  [[ "$executable" =~ ^/usr/local/bin/[A-Za-z0-9][A-Za-z0-9._-]*$ ]] || {
+    echo "ERROR refusing unsafe release archive removal target: $executable" >&2
+    return 1
+  }
+  if [[ "${RECONCILE_SOURCE_ONLY:-0}" == 1 && -n "${RECONCILE_TEST_COMMAND_ROOT:-}" ]]; then
+    target="${RECONCILE_TEST_COMMAND_ROOT%/}/${executable##*/}"
+  fi
+  if [[ "$mode" == apply ]]; then
+    rm -f -- "$target" || return 1
+    [[ ! -e "$target" && ! -L "$target" ]] || {
+      echo "ERROR release archive executable remains after removal: $target" >&2
+      return 1
+    }
+    echo "removed $label release executable: $executable"
+  else
+    echo "would remove $label release executable: $executable"
+  fi
+}
+
 remove_one_manifest_entry() {
   local tool_id="$1" manager package executable removed_repo_dir_target
   if jq -e --arg id "$tool_id" '.config.protected_tools | index($id)' "$manifest" >/dev/null; then
-    echo "refusing to remove protected bootstrap tool: $tool_id" >&2
+    echo "ERROR refusing to remove protected bootstrap tool: $tool_id" >&2
     exit 1
   fi
   manager="$(jq -r --arg id "$tool_id" '.[$id].manager' "$previous_resolved_file")"
@@ -1734,30 +1891,14 @@ remove_one_manifest_entry() {
     # still cleanly uninstall it the next time it reconciles; previous
     # state is read straight from disk, never re-validated.
     release-archive)
-      [[ "$executable" == /usr/local/bin/* ]] || {
-        echo "refusing unsafe release archive removal target: $executable" >&2
-        exit 1
-      }
-      if [[ "$mode" == apply ]]; then
-        rm -f -- "$executable"
-      else
-        echo "would remove pinned release executable: $executable"
-      fi
+      remove_release_archive_executable "$executable" pinned
       ;;
     release-archive-latest)
-      [[ "$executable" == /usr/local/bin/* ]] || {
-        echo "refusing unsafe release archive removal target: $executable" >&2
-        exit 1
-      }
-      if [[ "$mode" == apply ]]; then
-        rm -f -- "$executable"
-      else
-        echo "would remove latest release executable: $executable"
-      fi
+      remove_release_archive_executable "$executable" latest
       ;;
     shim)
       [[ "$executable" == /usr/local/bin/* ]] || {
-        echo "refusing unsafe shim removal target: $executable" >&2
+        echo "ERROR refusing unsafe shim removal target: $executable" >&2
         exit 1
       }
       if [[ "$mode" == apply ]]; then
@@ -1771,7 +1912,7 @@ remove_one_manifest_entry() {
         remove_one_repo_script "$executable"
       else
         [[ "$executable" =~ ^/usr/local/bin/[A-Za-z0-9][A-Za-z0-9._-]*$ ]] || {
-          echo "refusing unsafe managed script removal target: $executable" >&2
+          echo "ERROR refusing unsafe managed script removal target: $executable" >&2
           exit 1
         }
         echo "would remove managed repo script: $executable"
@@ -1783,7 +1924,7 @@ remove_one_manifest_entry() {
         remove_one_repo_dir "$removed_repo_dir_target"
       else
         [[ "$removed_repo_dir_target" == "$repo_dir_libexec_root"/* ]] || {
-          echo "refusing unsafe repo-dir removal target: $removed_repo_dir_target" >&2
+          echo "ERROR refusing unsafe repo-dir removal target: $removed_repo_dir_target" >&2
           exit 1
         }
         echo "would remove repo dir: $removed_repo_dir_target"
@@ -1791,7 +1932,7 @@ remove_one_manifest_entry() {
       ;;
     bun-compile)
       [[ "$executable" == /usr/local/bin/* ]] || {
-        echo "refusing unsafe bun binary removal target: $executable" >&2
+        echo "ERROR refusing unsafe bun binary removal target: $executable" >&2
         exit 1
       }
       if [[ "$mode" == apply ]]; then
@@ -1802,34 +1943,18 @@ remove_one_manifest_entry() {
       ;;
     embedding-model)
       if [[ "$mode" == apply ]]; then
-        [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
-        command -v bun >/dev/null 2>&1 || { echo "embedding-model requires bun; ensure bun installs before this tool" >&2; exit 1; }
+        [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
+        command -v bun >/dev/null 2>&1 || { echo "ERROR embedding-model requires bun; ensure bun installs before this tool" >&2; exit 1; }
         (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
           bun "$repo_root/packages/fleet/src/install-embedding-model.ts" uninstall </dev/null)
       else
-        echo "would remove embedding model cache: ~/.cache/adl-embedding/model (as $administrator)"
+        echo "would remove embedding model cache: ~/.cache/enact-embedding/model (as $administrator)"
       fi
       ;;
-    *) echo "unsupported manager in previous manifest: $manager" >&2; exit 1 ;;
+    *) echo "ERROR unsupported manager in previous manifest: $manager" >&2; exit 1 ;;
   esac
 }
 
-# config.git_global_config: global git config for the administrator (the
-# account whose HOME the per-user deployers below also write to). Apply runs git as
-# that user (sudo -u -H) so ~/.gitconfig stays user-owned; plan/audit only
-# read, as whoever invoked reconcile. Motivating entries: Azure DevOps SSH
-# has no Git LFS support, and git-lfs's default pure-SSH `git-lfs-transfer`
-# probe hangs forever against ssh.dev.azure.com, stalling every `git push` in
-# the LFS pre-push hook.
-run_git_config_global() {
-  if [[ "$mode" == apply ]]; then
-    [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
-    (cd /tmp && sudo -u "$git_config_user" -H git config --global "$@" </dev/null)
-  else
-    git config --global "$@" </dev/null
-  fi
-}
-
 # One-release migration for Linux state written by the retired two-user
 # contract. The previous applied manifest is the authority for the former
 # account and home, so no legacy identity remains configured after a successful
@@ -1848,7 +1973,7 @@ cleanup_legacy_linux_git_config() {
   legacy_home="$(jq -r --arg device "$device" '.linux.devices[$device].brew_user_home // empty' "$applied_manifest")"
   [[ -n "$legacy_user" && -n "$legacy_home" ]] || return 0
   [[ "$legacy_home" == /* && "$legacy_home" != / ]] || {
-    echo "invalid legacy per-user home in applied manifest: $legacy_home" >&2
+    echo "ERROR invalid legacy per-user home in applied manifest: $legacy_home" >&2
     return 1
   }
   config_file="$legacy_home/.gitconfig"
@@ -1862,7 +1987,7 @@ cleanup_legacy_linux_git_config() {
       continue
     fi
     [[ "$rc" -eq 0 ]] || {
-      echo "failed to inspect legacy global git config: $key in $config_file (exit $rc)" >&2
+      echo "ERROR failed to inspect legacy global git config: $key in $config_file (exit $rc)" >&2
       return "$rc"
     }
     if [[ "$mode" != apply ]]; then
@@ -1874,49 +1999,18 @@ cleanup_legacy_linux_git_config() {
   done
 }
 
-# Prints the current global value of $1, or nothing when unset. git config
-# --get exits 1 for a missing key; any other failure is real and propagates.
-git_global_config_value() {
-  local key="$1" value rc=0
-  value="$(run_git_config_global --get "$key")" || rc=$?
-  if [[ "$rc" -eq 1 ]]; then
-    return 0
-  fi
-  [[ "$rc" -eq 0 ]] || { echo "git config --global --get $key failed (exit $rc)" >&2; return "$rc"; }
-  printf '%s\n' "$value"
-}
-
+# config.git_global_config + <platform>.common.git_global_config + the device's
+# git_user: the administrator's global git config, identical on every host
+# (Tarun, 2026-10-01). All logic lives in bin/git-defaults; undeclared keys are
+# never touched. Motivating entries: Azure DevOps SSH has no Git LFS support
+# (git-lfs's pure-SSH probe hangs against ssh.dev.azure.com), and GCM is the
+# credential helper on every host.
 reconcile_git_global_config() {
-  local key value current
-  while IFS=$'\t' read -r key value; do
-    [[ -n "$key" ]] || continue
-    current="$(git_global_config_value "$key")" || return 1
-    if [[ "$current" == "$value" ]]; then
-      echo "global git config already set: $key=$value"
-    elif [[ "$mode" != apply ]]; then
-      echo "would set global git config: $key=$value"
-    else
-      run_git_config_global "$key" "$value" || return 1
-      echo "set global git config: $key=$value"
-    fi
-  done < <(jq -r '.config.git_global_config | to_entries[] | [.key, .value] | @tsv' "$manifest")
-
-  [[ "$have_previous" -eq 1 ]] || return 0
-  while IFS= read -r key; do
-    [[ -n "$key" ]] || continue
-    current="$(git_global_config_value "$key")" || return 1
-    [[ -n "$current" ]] || continue
-    if [[ "$mode" != apply ]]; then
-      echo "would unset global git config (explicit manifest deletion): $key"
-    else
-      run_git_config_global --unset-all "$key" || return 1
-      echo "explicit manifest deletion: unset global git config $key"
-    fi
-  done < <(jq -r --slurpfile current "$manifest" '
-    (.config.git_global_config // {}) | keys[] as $key
-    | select(($current[0].config.git_global_config | has($key)) | not)
-    | $key
-  ' "$applied_manifest")
+  if [[ "$mode" == apply ]]; then
+    [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
+  fi
+  "$BASH" "$repo_root/bin/git-defaults" --manifest "$manifest" --platform "$platform" \
+    --device "$device" --mode "$mode" --administrator "$git_config_user"
 }
 
 # default-agent-file.ts and managed-settings.ts (Claude/Codex) MUST run
@@ -1931,7 +2025,7 @@ reconcile_git_global_config() {
 # "bun: command not found" abort with no explanation.
 require_bun_for_identity_files() {
   command -v bun >/dev/null 2>&1 || {
-    echo "global-tools: bun is required before default-agent-file/managed-settings; install bun first, then re-run reconcile" >&2
+    echo "ERROR global-tools: bun is required before default-agent-file/managed-settings; install bun first, then re-run reconcile" >&2
     return 1
   }
 }
@@ -1945,9 +2039,11 @@ require_bun_for_identity_files() {
 # The PATH searched for a surface command intentionally extends past the
 # usual brew/system directories into the per-user install locations these
 # specific CLIs' own installers use (claude's and cursor's native installers,
-# kimi's and opencode's curl-script installers) -- none of those are on the
-# plain system PATH this file uses elsewhere for brew/npm/pip.
-surface_cli_search_path="$administrator_home/.local/bin:$administrator_home/.kimi-code/bin:$administrator_home/.opencode/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/local/bin:/usr/bin:/bin"
+# kimi's curl-script installer) -- none of those are on the plain system PATH
+# this file uses elsewhere for brew/npm/pip. opencode is the exception (Tarun,
+# 2026-10-01): it comes from the npm registry through bun, so bun's global bin
+# directory is searched instead of the retired native ~/.opencode/bin.
+surface_cli_search_path="$administrator_home/.local/bin:$administrator_home/.kimi-code/bin:$administrator_home/.bun/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/local/bin:/usr/bin:/bin"
 
 # Resolves a surface to the real executable that will be run: an explicit
 # manifest `executable` (a fixed, known path -- e.g. hostinger's report-only
@@ -2016,6 +2112,173 @@ surface_update_error_reason() {
   fi
 }
 
+# bun-managed surface (Tarun, 2026-10-01, "we are not on GitHub"): opencode is installed and updated
+# from the npm registry package `opencode-ai` with `bun add -g opencode-ai@latest`, run as the
+# administrator -- never `opencode upgrade`, which asks the unauthenticated GitHub REST API for its
+# latest release and 403s under the fleet's shared-IP rate limit. Named so tests can stub the one
+# boundary that touches the machine; adl_bun_add_global (bin/lib/adl-package.sh) is the same call
+# the adl package install uses (the administrator's own ~/.bun, bun found through Homebrew).
+run_surface_bun_add() {
+  local spec="$1" os
+  case "$platform" in
+    mac) os=Darwin ;;
+    linux) os=Linux ;;
+    *) echo "ERROR unsupported platform for a bun surface: $platform" >&2; return 1 ;;
+  esac
+  adl_bun_add_global "$administrator" "$os" "$administrator_home" "$spec" </dev/null
+}
+
+# Finds every OTHER copy of a bun-managed surface command: each directory on the surface search
+# path plus the native installer's ~/.opencode/bin. Prints one TAB-separated record per distinct
+# copy, `kind<TAB>path<TAB>detail`, where kind is
+#   native       <home>/.opencode/bin/<command> (a regular executable the native installer wrote;
+#                path is the bin DIRECTORY that is moved aside)
+#   brew         a symlink into <this host's Homebrew prefix>/Cellar/<command>/<version>/bin/<command>
+#   npm          a symlink into <prefix>/lib/node_modules/<package>/bin/<command>.exe whose
+#                package.json names <package> (detail is the prefix)
+#   unrecognised anything else (detail is where it really points)
+# A copy is retired only when it is positively one of the first three; the bun install itself is
+# skipped. Several PATH entries that reach one real file (/bin -> usr/bin) count once.
+classify_surface_copies() {
+  local command_name="$1" package="$2" bun_exe="$3"
+  local dirs=() dir path real bun_real seen=" " native_bin="$administrator_home/.opencode/bin" prefix pkg_dir brew_prefix
+  brew_prefix="$(cd -P -- "${brew_bin%/bin/brew}" 2>/dev/null && pwd -P)" || brew_prefix="${brew_bin%/bin/brew}"
+  IFS=: read -r -a dirs <<<"$surface_cli_search_path"
+  dirs+=("$native_bin")
+  bun_real="$(adl_realpath "$bun_exe" 2>/dev/null)" || bun_real="$bun_exe"
+  for dir in "${dirs[@]}"; do
+    [[ -n "$dir" ]] || continue
+    path="$dir/$command_name"
+    [[ -e "$path" || -L "$path" ]] || continue
+    real="$(adl_realpath "$path" 2>/dev/null)" || real="$path"
+    [[ "$real" != "$bun_real" ]] || continue
+    case "$seen" in *" $real "*) continue ;; esac
+    seen="$seen$real "
+    if [[ "$path" == "$native_bin/$command_name" && -f "$path" && ! -L "$path" && -x "$path" ]]; then
+      printf 'native\t%s\t%s\n' "$native_bin" "$path"
+    elif [[ "$real" =~ ^(.*)/Cellar/${command_name}/[^/]+/bin/${command_name}$ && "${BASH_REMATCH[1]}" == "$brew_prefix" ]]; then
+      printf 'brew\t%s\t%s\n' "$path" "${BASH_REMATCH[1]}"
+    elif [[ "$real" =~ ^(.*)/lib/node_modules/${package}/bin/${command_name}\.exe$ ]]; then
+      prefix="${BASH_REMATCH[1]}"
+      pkg_dir="$prefix/lib/node_modules/$package"
+      if [[ -f "$pkg_dir/package.json" ]] && jq -e --arg name "$package" '.name == $name' "$pkg_dir/package.json" >/dev/null 2>&1; then
+        printf 'npm\t%s\t%s\n' "$path" "$prefix"
+      else
+        printf 'unrecognised\t%s\t%s\n' "$path" "$real"
+      fi
+    else
+      printf 'unrecognised\t%s\t%s\n' "$path" "$real"
+    fi
+  done
+}
+
+# Retires every other copy of a bun-managed surface so the host has exactly one, idempotently:
+# the native installer's ~/.opencode/bin is moved ASIDE under <state dir>/retired-opencode/<UTC
+# stamp>/native-bin (never deleted; ~/.opencode's own plugin files and ~/.config/opencode are not
+# touched), a Homebrew formula goes through `brew uninstall` as the Homebrew owner (run_brew, never
+# sudo brew), and an npm global goes through `npm uninstall -g --prefix <its real prefix>`. Anything
+# not positively identified is an ERROR and NOTHING is removed. Plan mode lists what apply would do.
+retire_other_surface_copies() {
+  local name="$1" command_name="$2" package="$3" bun_exe="$4"
+  local kinds=() paths=() details=() kind path detail i unrecognised=0 aside=""
+  while IFS=$'\t' read -r kind path detail; do
+    [[ -n "$kind" ]] || continue
+    kinds+=("$kind"); paths+=("$path"); details+=("$detail")
+  done < <(classify_surface_copies "$command_name" "$package" "$bun_exe")
+  [[ "${#kinds[@]}" -gt 0 ]] || return 0
+  for ((i = 0; i < ${#kinds[@]}; i++)); do
+    [[ "${kinds[i]}" == unrecognised ]] || continue
+    unrecognised=1
+    if [[ "$mode" != apply ]]; then
+      echo "global-tools: would FAIL: unrecognised $command_name at ${paths[i]} (-> ${details[i]}); not a copy reconcile knows how to retire"
+    else
+      echo "ERROR surface $name: unrecognised $command_name at ${paths[i]} (-> ${details[i]}); not a copy reconcile knows how to retire, so nothing was removed" >&2
+    fi
+  done
+  if [[ "$unrecognised" -eq 1 ]]; then
+    [[ "$mode" != apply ]] || return 1
+    return 0
+  fi
+  if [[ "$mode" != apply ]]; then
+    for ((i = 0; i < ${#kinds[@]}; i++)); do
+      case "${kinds[i]}" in
+        native) echo "global-tools: would retire $command_name copy: move ${paths[i]} aside (native installer)" ;;
+        brew) echo "global-tools: would retire $command_name copy: brew uninstall $command_name (Homebrew formula, ${paths[i]})" ;;
+        npm) echo "global-tools: would retire $command_name copy: npm uninstall -g --prefix ${details[i]} $package (${paths[i]})" ;;
+      esac
+    done
+    return 0
+  fi
+  for ((i = 0; i < ${#kinds[@]}; i++)); do
+    case "${kinds[i]}" in
+      native)
+        [[ -n "$aside" ]] || aside="$state_dir/retired-$command_name/$(date -u +%Y%m%dT%H%M%SZ)"
+        mkdir -p -- "$aside" || return 1
+        mv -- "${paths[i]}" "$aside/native-bin" || { echo "ERROR surface $name: could not move ${paths[i]} aside to $aside" >&2; return 1; }
+        echo "global-tools: retiring $command_name copy: moved ${paths[i]} aside to $aside/native-bin"
+        ;;
+      brew)
+        run_brew uninstall "$command_name" || { echo "ERROR surface $name: brew uninstall $command_name failed" >&2; return 1; }
+        [[ ! -e "${paths[i]}" && ! -L "${paths[i]}" ]] || { echo "ERROR surface $name: ${paths[i]} is still present after brew uninstall $command_name" >&2; return 1; }
+        echo "global-tools: retiring $command_name copy: brew uninstalled $command_name (${paths[i]})"
+        ;;
+      npm)
+        run_npm uninstall -g --prefix "${details[i]}" "$package" || { echo "ERROR surface $name: npm uninstall -g $package failed" >&2; return 1; }
+        [[ ! -e "${paths[i]}" && ! -L "${paths[i]}" ]] || { echo "ERROR surface $name: ${paths[i]} is still present after npm uninstall -g $package" >&2; return 1; }
+        echo "global-tools: retiring $command_name copy: npm uninstalled $package from ${details[i]} (${paths[i]})"
+        ;;
+    esac
+  done
+}
+
+# Installs or updates a bun-managed surface (see run_surface_bun_add): one `bun add -g
+# <package>@latest` covers both "absent" and "present", then the other copies are retired and the
+# command the administrator's PATH resolves is checked to be bun's. Fails loud at every step; a
+# version is never pinned.
+reconcile_bun_surface_cli() {
+  local name="$1" command_name="$2" package="$3"
+  local bun_exe="$administrator_home/.bun/bin/$command_name" spec="$package@latest"
+  local old_version="" new_version update_output update_status=0 resolved
+  if [[ "$mode" != apply ]]; then
+    echo "would install or update surface from the npm registry: $name (bun add -g $spec as $administrator)"
+    retire_other_surface_copies "$name" "$command_name" "$package" "$bun_exe"
+    return 0
+  fi
+  [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
+  if [[ -x "$bun_exe" ]]; then old_version="$(surface_cli_version "$bun_exe")"; fi
+  update_output="$(run_with_timeout "$SURFACE_UPDATE_TIMEOUT_SECONDS" run_surface_bun_add "$spec" 2>&1)" || update_status=$?
+  printf '%s\n' "$update_output"
+  if [[ "$update_status" -eq 124 ]]; then
+    echo "ERROR surface update timed out: $name" >&2
+    return 1
+  elif [[ "$update_status" -ne 0 ]]; then
+    echo "ERROR surface update failed: $name (exit $update_status)" >&2
+    return 1
+  fi
+  # opencode-ai's bin is a stub that exits 1 until its postinstall puts the platform binary in
+  # place, and bun skips an untrusted package's postinstall: a bun add that "succeeded" but left
+  # a command that cannot report its version is not an install.
+  new_version="$(surface_cli_version "$bun_exe")"
+  if [[ -z "$new_version" ]]; then
+    echo "ERROR surface $name: bun add -g $spec succeeded but '$bun_exe --version' printed nothing; the package's postinstall did not run (check 'bun pm default-trusted' lists $package, or add it to the global trustedDependencies)" >&2
+    return 1
+  fi
+  retire_other_surface_copies "$name" "$command_name" "$package" "$bun_exe" || return 1
+  resolved="$(resolve_surface_executable "$command_name" "")"
+  if [[ "$resolved" != "$bun_exe" ]]; then
+    echo "ERROR surface $name: $command_name on ${administrator}'s PATH is ${resolved:-missing}, not the bun-installed $bun_exe" >&2
+    return 1
+  fi
+  if [[ -z "$old_version" ]]; then
+    echo "surface $name: installed $new_version ($package from the npm registry)"
+  elif [[ "$old_version" != "$new_version" ]]; then
+    echo "surface $name: $old_version -> $new_version"
+  else
+    echo "surface $name: already latest ($new_version)"
+  fi
+  return 0
+}
+
 # Reconciles one declared surface_clis entry. report_only (hostinger's loose
 # /root/codex, unknown install method) is version-reported only -- run_surface_update
 # is never called for it, by construction (this branch returns before
@@ -2027,17 +2290,35 @@ reconcile_one_surface_cli() {
   local name="$1" command_name="$2" executable_override="$3" report_only="$4" manager="$5"
   shift 5
   local update_args=("$@")
+  if [[ "$manager" == bun ]]; then
+    # For a bun surface the one trailing argument is the npm registry package, not an update argv.
+    reconcile_bun_surface_cli "$name" "$command_name" "${update_args[0]}"
+    return
+  fi
   if [[ "$manager" == brew ]]; then
     if [[ "$mode" != apply ]]; then
+      if [[ "$name" == */* ]]; then
+        echo "would trust Homebrew item: $name (cask)"
+      fi
       echo "would ensure Homebrew cask: $name (brew install --cask $name; brew upgrade --cask $name)"
       return 0
     fi
-    [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
+    [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
+    # A fully-qualified cask name comes from a non-core tap, which Homebrew
+    # >=6 refuses to load until the ITEM is trusted (same tap-trust grant as
+    # the per-tool brew path in install_one_tool; the kind is certain here).
+    # Bare names are core casks, trusted by default -- no grant.
+    if [[ "$name" == */* ]]; then
+      brew_query trust | awk '{$1=$1};1' | grep -Fqx "$name" || run_brew trust --cask "$name" || {
+        echo "ERROR surface $name: brew trust --cask $name failed" >&2
+        return 1
+      }
+    fi
     local installed_casks query_status=0 cask_action=() update_output update_status=0
     installed_casks="$(brew_query list --cask --versions 2>&1)" || query_status=$?
     if [[ "$query_status" -ne 0 ]]; then
-      printf '%s\n' "$installed_casks" >&2
-      echo "brew list --cask --versions failed for surface $name (exit $query_status)" >&2
+      printf 'ERROR brew list --cask --versions output: %s\n' "$installed_casks" >&2
+      echo "ERROR brew list --cask --versions failed for surface $name (exit $query_status)" >&2
       return 1
     fi
     if awk -v cask="$name" '$1 == cask { found = 1 } END { exit !found }' <<<"$installed_casks"; then
@@ -2048,10 +2329,10 @@ reconcile_one_surface_cli() {
     update_output="$(run_with_timeout "$SURFACE_UPDATE_TIMEOUT_SECONDS" run_brew ${cask_action[@]+"${cask_action[@]}"} 2>&1)" || update_status=$?
     printf '%s\n' "$update_output"
     if [[ "$update_status" -eq 124 ]]; then
-      echo "surface update timed out: $name" >&2
+      echo "ERROR surface update timed out: $name" >&2
       return 1
     elif [[ "$update_status" -ne 0 ]]; then
-      echo "surface update failed: $name (exit $update_status)" >&2
+      echo "ERROR surface update failed: $name (exit $update_status)" >&2
       return 1
     fi
     # Same broadened check as the native/npm path below (independent
@@ -2068,9 +2349,9 @@ reconcile_one_surface_cli() {
       # coordinator pass, 2026-09-30): the same `cask_action[0]` that already
       # picks the real brew argv above also names which one failed.
       if [[ "${cask_action[0]}" == install ]]; then
-        echo "surface $name: cask install failed ($update_error_line)" >&2
+        echo "ERROR surface $name: cask install failed ($update_error_line)" >&2
       else
-        echo "surface $name: cask upgrade failed ($update_error_line)" >&2
+        echo "ERROR surface $name: cask upgrade failed ($update_error_line)" >&2
       fi
       return 1
     fi
@@ -2089,7 +2370,7 @@ reconcile_one_surface_cli() {
     fi
     return 0
   fi
-  [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
+  [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
   local resolved
   resolved="$(resolve_surface_executable "$command_name" "$executable_override")"
   if [[ -z "$resolved" ]]; then
@@ -2107,10 +2388,10 @@ reconcile_one_surface_cli() {
   update_output="$(run_with_timeout "$SURFACE_UPDATE_TIMEOUT_SECONDS" run_surface_update "$resolved" ${update_args[@]+"${update_args[@]}"} 2>&1)" || update_status=$?
   printf '%s\n' "$update_output"
   if [[ "$update_status" -eq 124 ]]; then
-    echo "surface update timed out: $name" >&2
+    echo "ERROR surface update timed out: $name" >&2
     return 1
   elif [[ "$update_status" -ne 0 ]]; then
-    echo "surface update failed: $name (exit $update_status)" >&2
+    echo "ERROR surface update failed: $name (exit $update_status)" >&2
     return 1
   fi
   # A surface's update command can exit 0 while its own output says the
@@ -2139,7 +2420,7 @@ reconcile_one_surface_cli() {
   new_version="$(surface_cli_version "$resolved")"
   update_error_line="$(surface_update_error_reason "$update_output")"
   if [[ -z "$new_version" ]]; then
-    echo "surface $name: update ran but version unreadable (${update_error_line:-"--version produced no output"}); was ${old_version:-unknown}" >&2
+    echo "WARN surface $name: update ran but version unreadable (${update_error_line:-"--version produced no output"}); was ${old_version:-unknown}" >&2
     return 1
   fi
   if [[ "$old_version" != "$new_version" ]]; then
@@ -2151,7 +2432,7 @@ reconcile_one_surface_cli() {
     return 0
   fi
   if [[ -n "$update_error_line" ]]; then
-    echo "surface $name: update check failed ($update_error_line); kept ${old_version:-unknown}" >&2
+    echo "WARN surface $name: update check failed ($update_error_line); kept ${old_version:-unknown}" >&2
     return 1
   fi
   echo "surface $name: already latest ($new_version)"
@@ -2159,7 +2440,7 @@ reconcile_one_surface_cli() {
 }
 
 # Loops over this device's declared surface_clis (absent or empty -> silently
-# does nothing, same convention as launch_agents/scratch_repos). A failure is
+# does nothing, same convention as scratch_repos). A failure is
 # collected into failed_tools by id "surface-<name>", exactly like every other
 # apply-mode step's continue-on-failure contract in this file.
 reconcile_surface_clis() {
@@ -2180,17 +2461,88 @@ reconcile_surface_clis() {
     report_only="$(jq -r --argjson i "$i" --arg platform "$platform" --arg device "$device" \
       '.[$platform].devices[$device].surface_clis[$i].report_only // false' "$manifest")"
     update_args=()
-    while IFS= read -r arg; do
-      [[ -n "$arg" ]] && update_args+=("$arg")
-    done < <(jq -r --argjson i "$i" --arg platform "$platform" --arg device "$device" \
-      '.[$platform].devices[$device].surface_clis[$i].update_args // [] | .[]' "$manifest")
+    if [[ "$manager" == bun ]]; then
+      update_args+=("$(jq -r --argjson i "$i" --arg platform "$platform" --arg device "$device" \
+        '.[$platform].devices[$device].surface_clis[$i].package // empty' "$manifest")")
+    else
+      while IFS= read -r arg; do
+        [[ -n "$arg" ]] && update_args+=("$arg")
+      done < <(jq -r --argjson i "$i" --arg platform "$platform" --arg device "$device" \
+        '.[$platform].devices[$device].surface_clis[$i].update_args // [] | .[]' "$manifest")
+    fi
     if ! reconcile_one_surface_cli "$name" "$command_name" "$executable_override" "$report_only" "$manager" ${update_args[@]+"${update_args[@]}"}; then
-      echo "global-tools: TOOL INSTALL FAILED: surface-$name" >&2
+      echo "ERROR global-tools: TOOL INSTALL FAILED: surface-$name" >&2
       failed_tools+=("surface-$name")
     fi
   done
 }
 
+# retire_git_maintain (2026-09-30, Tarun: "one binary controlling everything"):
+# the git-maintain user LaunchAgent (com.adl.git-maintain) and its compiled
+# binary are retired; repository maintenance is `adl reconcile`'s own step
+# (bin/reconcile-host -> `adl maintain`). M3 and M5 already have the agent
+# installed and loaded, so this cleans it up actively rather than leaving a
+# job that scans ~/Documents on its own timer:
+#   - boot out gui/<administrator uid>/com.adl.git-maintain if loaded, and fail
+#     loud if it is still loaded afterwards (nothing is moved in that case);
+#   - move the plist, the compiled binary and its source-hash marker ASIDE
+#     (never deleted) under <state dir>/retired-git-maintain/<UTC stamp>/,
+#     logging each one.
+# Already gone means no change and no output; plan/audit only list what they
+# would do; Linux never had it. Returns non-zero (after an ERROR line) on a
+# failure; the caller records it like any other failed step.
+retire_git_maintain() {
+  [[ "$platform" == mac ]] || return 0
+  local label=com.adl.git-maintain uid loaded=0 path aside
+  local leftovers=()
+  local agent_plist="$administrator_home/Library/LaunchAgents/$label.plist"
+  local binary="$repo_dir_libexec_root/git-maintain"
+  local hash_marker="$state_dir/launch-agents/git-maintain.source-hash"
+
+  if uid="$(id -u "$administrator" 2>/dev/null)"; then
+    if launchctl print "gui/$uid/$label" >/dev/null 2>&1; then loaded=1; fi
+  elif [[ "$mode" == apply ]]; then
+    echo "ERROR global-tools: cannot resolve the uid of $administrator to retire git-maintain" >&2
+    return 1
+  else
+    # plan/audit on a machine without that account (a test, a preview): the
+    # leftover files can still be listed, but there is nothing to ask launchd.
+    uid="<uid of $administrator>"
+  fi
+  for path in "$agent_plist" "$binary" "$hash_marker"; do
+    if [[ -e "$path" || -L "$path" ]]; then leftovers+=("$path"); fi
+  done
+  if [[ "$loaded" -eq 0 && "${#leftovers[@]}" -eq 0 ]]; then return 0; fi
+
+  if [[ "$mode" != apply ]]; then
+    if [[ "$loaded" -eq 1 ]]; then echo "global-tools: would retire git-maintain: boot out gui/$uid/$label"; fi
+    for path in ${leftovers[@]+"${leftovers[@]}"}; do
+      echo "global-tools: would retire git-maintain: move $path aside"
+    done
+    return 0
+  fi
+
+  if [[ "$loaded" -eq 1 ]]; then
+    if ! launchctl bootout "gui/$uid/$label"; then
+      echo "ERROR global-tools: could not boot out gui/$uid/$label; git-maintain is not retired" >&2
+      return 1
+    fi
+    if launchctl print "gui/$uid/$label" >/dev/null 2>&1; then
+      echo "ERROR global-tools: gui/$uid/$label is still loaded after bootout; git-maintain is not retired" >&2
+      return 1
+    fi
+    echo "global-tools: retiring git-maintain: booted out gui/$uid/$label"
+  fi
+  if [[ "${#leftovers[@]}" -gt 0 ]]; then
+    aside="$state_dir/retired-git-maintain/$(date -u +%Y%m%dT%H%M%SZ)"
+    mkdir -p -- "$aside"
+    for path in "${leftovers[@]}"; do
+      mv -- "$path" "$aside/" || { echo "ERROR global-tools: could not move $path aside to $aside" >&2; return 1; }
+      echo "global-tools: retiring git-maintain: moved $path aside to $aside"
+    done
+  fi
+}
+
 # Test-only escape hatch: source this script with RECONCILE_SOURCE_ONLY=1 to
 # load every function definition above (and the arg-parsing / manifest
 # validation / platform-and-tool-resolution state already computed by this
@@ -2215,7 +2567,7 @@ scratch_reap_failed=0
 available_kib="$(df -Pk / | awk 'NR == 2 {print $4}')"
 required_kib="$((minimum_free_gib * 1024 * 1024))"
 if [[ "$available_kib" -lt "$required_kib" ]]; then
-  echo "global-tools: only $((available_kib / 1024 / 1024)) GiB free; $minimum_free_gib GiB required" >&2
+  echo "ERROR global-tools: only $((available_kib / 1024 / 1024)) GiB free; $minimum_free_gib GiB required" >&2
   [[ "$mode" != apply ]] || exit 1
 fi
 
@@ -2224,7 +2576,7 @@ if [[ "$mode" == apply ]]; then
 fi
 
 if ! install_surface_policy_file; then
-  echo "global-tools: TOOL INSTALL FAILED: surface-policy-file" >&2
+  echo "ERROR global-tools: TOOL INSTALL FAILED: surface-policy-file" >&2
   failed_tools+=("surface-policy-file")
 fi
 
@@ -2235,7 +2587,7 @@ require_bun_for_identity_files || exit 1
 # below that could read it (kimi-hooks resolves adl the same way; this
 # is the identity every consumer -- `adl run`, the managed-settings render
 # below, and host automation's git-ado call -- reads instead of its own
-# copy). Runs for real in plan mode too (like launch-agents.ts): default-agent-file.ts's
+# copy). Runs for real in plan mode too (like the other plan-safe steps): default-agent-file.ts's
 # own --mode plan never writes, so this is safe to run unconditionally.
 default_agent="$(jq -r --arg platform "$platform" --arg device "$device" '.[$platform].devices[$device].default_agent' "$manifest")"
 if [[ "$mode" != apply ]]; then
@@ -2244,7 +2596,7 @@ if [[ "$mode" != apply ]]; then
 else
   echo "global-tools: default-agent file mode=apply device=$device -> $default_agent"
   if ! bun "$repo_root/packages/fleet/src/default-agent-file.ts" --agent "$default_agent" --platform "$platform" --mode apply ${reconcile_test_system_root_args[@]+"${reconcile_test_system_root_args[@]}"}; then
-    echo "global-tools: TOOL INSTALL FAILED: default-agent-file" >&2
+    echo "ERROR global-tools: TOOL INSTALL FAILED: default-agent-file" >&2
     failed_tools+=("default-agent-file")
   fi
 fi
@@ -2261,7 +2613,7 @@ if [[ "$mode" != apply ]]; then
 else
   echo "global-tools: managed settings mode=apply device=$device -> $default_agent"
   if ! bun "$repo_root/packages/fleet/src/managed-settings.ts" --agent "$default_agent" --platform "$platform" --mode apply ${reconcile_test_system_root_args[@]+"${reconcile_test_system_root_args[@]}"}; then
-    echo "global-tools: TOOL INSTALL FAILED: managed-settings" >&2
+    echo "ERROR global-tools: TOOL INSTALL FAILED: managed-settings" >&2
     failed_tools+=("managed-settings")
   fi
 fi
@@ -2282,7 +2634,7 @@ if jq -e 'to_entries | any(.value.manager == "brew")' "$resolved_file" >/dev/nul
   brew_upgrade_all="$(jq -r --arg platform "$platform" --arg device "$device" '.[$platform].devices[$device].brew_upgrade_all // false' "$manifest")"
   if [[ "$brew_upgrade_all" == true ]]; then
     if ! run_brew_upgrade_all; then
-      echo "global-tools: TOOL INSTALL FAILED: brew-upgrade-all" >&2
+      echo "ERROR global-tools: TOOL INSTALL FAILED: brew-upgrade-all" >&2
       failed_tools+=("brew-upgrade-all")
     fi
   fi
@@ -2295,7 +2647,7 @@ fi
 
 while IFS= read -r tool_id; do
   if ! install_one_tool "$tool_id"; then
-    echo "global-tools: TOOL INSTALL FAILED: $tool_id" >&2
+    echo "ERROR global-tools: TOOL INSTALL FAILED: $tool_id" >&2
     failed_tools+=("$tool_id")
   fi
 done < <(jq -r 'to_entries[] | select(.value.manager != "shim" and .value.manager != "repo-script" and .value.manager != "repo-dir" and .value.manager != "bun-compile" and .value.manager != "embedding-model") | .key' "$resolved_file")
@@ -2310,28 +2662,28 @@ fi
 
 while IFS= read -r tool_id; do
   if ! build_one_bun_tool "$tool_id"; then
-    echo "global-tools: TOOL INSTALL FAILED: $tool_id" >&2
+    echo "ERROR global-tools: TOOL INSTALL FAILED: $tool_id" >&2
     failed_tools+=("$tool_id")
   fi
 done < <(jq -r 'to_entries[] | select(.value.manager == "bun-compile") | .key' "$resolved_file")
 
 while IFS= read -r tool_id; do
   if ! install_one_embedding_model_tool "$tool_id"; then
-    echo "global-tools: TOOL INSTALL FAILED: $tool_id" >&2
+    echo "ERROR global-tools: TOOL INSTALL FAILED: $tool_id" >&2
     failed_tools+=("$tool_id")
   fi
 done < <(jq -r 'to_entries[] | select(.value.manager == "embedding-model") | .key' "$resolved_file")
 
 while IFS= read -r tool_id; do
   if ! write_one_shim "$tool_id"; then
-    echo "global-tools: TOOL INSTALL FAILED: $tool_id" >&2
+    echo "ERROR global-tools: TOOL INSTALL FAILED: $tool_id" >&2
     failed_tools+=("$tool_id")
   fi
 done < <(jq -r 'to_entries[] | select(.value.manager == "shim") | .key' "$resolved_file")
 
 while IFS= read -r tool_id; do
   if ! write_one_repo_script "$tool_id"; then
-    echo "global-tools: TOOL INSTALL FAILED: $tool_id" >&2
+    echo "ERROR global-tools: TOOL INSTALL FAILED: $tool_id" >&2
     failed_tools+=("$tool_id")
   fi
 done < <(jq -r 'to_entries[] | select(.value.manager == "repo-script") | .key' "$resolved_file")
@@ -2416,7 +2768,7 @@ if [[ "$(jq -r '.config.scratch_reap.enabled // false' "$manifest")" == true ]];
     # REFUSE to remove worktrees. That is the safe direction, so it must not
     # abort the fleet's update -- but it must not vanish either, or the
     # published-HEAD gate rots with nothing ever reporting it.
-    "$script_dir/scratch-reap" \
+    "$BASH" "$script_dir/scratch-reap" \
       "${scratch_reap_args[@]}" \
       --mode "$scratch_reap_mode" \
       --idle-days "$scratch_reap_idle_days" \
@@ -2426,7 +2778,7 @@ fi
 
 while IFS= read -r tool_id; do
   if ! write_one_repo_dir "$tool_id"; then
-    echo "global-tools: TOOL INSTALL FAILED: $tool_id" >&2
+    echo "ERROR global-tools: TOOL INSTALL FAILED: $tool_id" >&2
     failed_tools+=("$tool_id")
   fi
 done < <(jq -r 'to_entries[] | select(.value.manager == "repo-dir") | .key' "$resolved_file")
@@ -2445,15 +2797,10 @@ if [[ "$have_previous" -eq 1 ]]; then
     [[ -n "$tool_id" ]] || continue
     remove_one_manifest_entry "$tool_id"
   # Selects an id when it was deleted outright (absent from the current
-  # manifest) OR retained but migrated to a different manager/package (e.g.
-  # lean-ctx moving from npm:lean-ctx-bin to release-archive-latest:lean-ctx)
+  # manifest) OR retained but migrated to a different manager/package
   # -- a plain "id no longer present" check would silently leave the OLD
   # manager's install in place forever whenever an id survives a manager
-  # change, which for lean-ctx meant the stale npm package (and the
-  # /opt/homebrew/bin/lean-ctx shim it owns) would never be uninstalled, and
-  # that shim's earlier position on PATH than /usr/local/bin would keep
-  # `command -v lean-ctx` resolving to it instead of the new release binary
-  # no matter how many times reconcile ran.
+  # change, even though the current declaration points to a different install.
   done < <(jq -r --slurpfile current "$resolved_file" '
     keys[] as $id
     | ($current[0][$id]) as $cur
@@ -2466,12 +2813,12 @@ project_adl_package_payload() {
   local adl_package bun_bin
   adl_package="$(jq -r '.adl.package // empty' "$resolved_file")"
   [[ "$adl_package" == @amsterdamdatalabs/adl-agent-control ]] || {
-    echo "Adl package projection requires the published wrapper entry" >&2
+    echo "ERROR Adl package projection requires the published wrapper entry" >&2
     return 1
   }
   for failed_tool in ${failed_tools[@]+"${failed_tools[@]}"}; do
     if [[ "$failed_tool" == adl ]]; then
-      echo "skipping Adl payload projection because Adl source verification failed" >&2
+      echo "WARN skipping Adl payload projection because Adl source verification failed" >&2
       return 1
     fi
   done
@@ -2480,13 +2827,16 @@ project_adl_package_payload() {
       echo "would build agent-skills payload from checkout"
     fi
     echo "would project Adl package payload from $repo_root to /usr/local/libexec/adl and /usr/local/bin/git{,-ado}"
+    if [[ "$source_mode" == npm ]]; then
+      echo "would link /usr/local/bin/adl to $repo_root/bin/adl"
+    fi
     return 0
   fi
   bun_bin="$(command -v bun || true)"
-  [[ -n "$bun_bin" ]] || { echo "Adl package projection requires bun on PATH" >&2; return 1; }
+  [[ -n "$bun_bin" ]] || { echo "ERROR Adl package projection requires bun on PATH" >&2; return 1; }
   if [[ "$source_mode" == checkout ]]; then
     (cd "$repo_root/packages/agent-skills" && "$bun_bin" run build) || {
-      echo "could not build agent-skills payload from checkout" >&2
+      echo "ERROR could not build agent-skills payload from checkout" >&2
       return 1
     }
   fi
@@ -2494,59 +2844,48 @@ project_adl_package_payload() {
   if [[ -n "${RECONCILE_TEST_SYSTEM_ROOT:-}" ]]; then
     system_root_args+=(--system-root "$RECONCILE_TEST_SYSTEM_ROOT")
   fi
+  # Package mode also links /usr/local/bin/adl to this package's own bin/adl:
+  # bun links adl into the owner's ~/.bun/bin only, yet bin/git-ado, the MCP
+  # server command and the managed surface hooks run a bare `adl`.
+  if [[ "$source_mode" == npm ]]; then
+    system_root_args+=(--link-adl)
+  fi
   "$bun_bin" "$repo_root/packages/fleet/src/install-adl-package.ts" install \
     --package-root "$repo_root" ${system_root_args[@]+"${system_root_args[@]}"}
 }
 
 if ! project_adl_package_payload; then
-  echo "global-tools: TOOL INSTALL FAILED: adl-package-projection" >&2
+  echo "ERROR global-tools: TOOL INSTALL FAILED: adl-package-projection" >&2
   failed_tools+=("adl-package-projection")
 fi
 
 # Same continue-on-failure contract as the tool passes above: runs after git
 # itself is installed/upgraded, and a failure is recorded, not fatal.
-if ! "$repo_root/bin/shell-path-policy" --home "$administrator_home" --platform "$platform" --mode "$mode" --owner "$administrator"; then
-  echo "global-tools: TOOL INSTALL FAILED: shell-path-policy" >&2
+if ! "$BASH" "$repo_root/bin/shell-path-policy" --home "$administrator_home" --platform "$platform" --mode "$mode" --owner "$administrator"; then
+  echo "ERROR global-tools: TOOL INSTALL FAILED: shell-path-policy" >&2
   failed_tools+=("shell-path-policy")
 fi
 
 if ! reconcile_git_global_config; then
-  echo "global-tools: TOOL INSTALL FAILED: git-global-config" >&2
+  echo "ERROR global-tools: TOOL INSTALL FAILED: git-global-config" >&2
   failed_tools+=("git-global-config")
 fi
 cleanup_legacy_linux_git_config || {
-  echo "global-tools: legacy Linux git config cleanup failed" >&2
+  echo "ERROR global-tools: legacy Linux git config cleanup failed" >&2
   exit 1
 }
 
-# launch_agents (mac only; validate-manifest rejects them on linux): user
-# LaunchAgents adl owns -- see packages/fleet/src/launch-agents.ts. Runs
-# before the global surface sweep, whose LaunchAgent protection is derived
-# from these same manifest declarations. Apply runs as root (it installs the
-# compiles each job into its own signed binary under
-# /usr/local/libexec/adl, writes the administrator's plist owned by
-# that user, and bootstraps gui/<uid>); plan only prints. Same
-# continue-on-failure contract as the tool passes above.
-if [[ "$platform" == mac ]] && jq -e --arg device "$device" \
-  '((.mac.common.launch_agents // {}) + (.mac.devices[$device].launch_agents // {})) | length > 0' "$manifest" >/dev/null; then
-  launch_agents_args=(--manifest "$manifest" --platform "$platform" --device "$device" --home "$administrator_home" --state-dir "$state_dir")
-  if [[ "$have_previous" -eq 1 ]]; then
-    launch_agents_args+=(--previous-manifest "$applied_manifest")
-  fi
-  if [[ "$mode" == apply ]]; then
-    echo "global-tools: launch agents mode=apply home=$administrator_home (for $administrator)"
-    if ! bun "$repo_root/packages/fleet/src/launch-agents.ts" --mode apply "${launch_agents_args[@]}"; then
-      echo "global-tools: TOOL INSTALL FAILED: launch-agents" >&2
-      failed_tools+=("launch-agents")
-    fi
-  else
-    echo "global-tools: launch agents mode=plan home=$administrator_home"
-    bun "$repo_root/packages/fleet/src/launch-agents.ts" --mode plan "${launch_agents_args[@]}"
-  fi
+# git-maintain is retired: clean it up where it is still installed (mac), ahead
+# of the global surface sweep, which would otherwise see its leftover
+# LaunchAgent as an approval-gated candidate. Same continue-on-failure
+# contract as the tool passes above.
+if ! retire_git_maintain; then
+  echo "ERROR global-tools: TOOL INSTALL FAILED: git-maintain-retire" >&2
+  failed_tools+=("git-maintain-retire")
 fi
 
 if [[ "$mode" == apply ]]; then
-  "$script_dir/health-check" "$device"
+  "$BASH" "$script_dir/health-check" "$device"
 fi
 
 if [[ "$(jq -r '.config.global_surface_sweep.enabled' "$manifest")" == true ]]; then
@@ -2559,7 +2898,7 @@ if [[ "$(jq -r '.config.global_surface_sweep.enabled' "$manifest")" == true ]];
   # recomputes the sweep's own backupPath() logic. stderr is left
   # unredirected so a real failure still streams live as before.
   sweep_status=0
-  sweep_output="$("$script_dir/global-surface-sweep" \
+  sweep_output="$("$BASH" "$script_dir/global-surface-sweep" \
     --home "$administrator_home" \
     --mode "$surface_mode" \
     --state-dir "$state_dir")" || sweep_status=$?
@@ -2597,7 +2936,7 @@ if [[ "$kimi_hooks_enabled" == true ]]; then
     echo "global-tools: kimi-hooks skipped: kimi not installed"
   elif [[ "$mode" != apply ]]; then
     echo "global-tools: kimi hooks mode=plan home=$administrator_home"
-    "$script_dir/kimi-hooks" --home "$administrator_home" --mode plan
+    "$BASH" "$script_dir/kimi-hooks" --home "$administrator_home" --mode plan
   else
     # Ordering: adl (bun-compile pass, above) must already resolve as
     # a bare command before we write TOML entries that reference it -- Kimi
@@ -2607,12 +2946,12 @@ if [[ "$kimi_hooks_enabled" == true ]]; then
     # docs/specs/two-branch-standard-2026-09-27.md) -- hard cut, no compat
     # shim: there is no standalone hook executable to resolve any more.
     adl_executable="$(jq -r '."adl".executable' "$resolved_file")"
-    if ! adl_resolved="$(sudo -u "$administrator" -H env PATH="/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/local/bin:/usr/bin:/bin" /bin/sh -c "command -v '$adl_executable'" 2>/dev/null)"; then
-      echo "global-tools: could not resolve adl from the administrator PATH" >&2
+    if ! adl_resolved="$(sudo -u "$administrator" -H env PATH="/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/local/bin:$administrator_home/.bun/bin:/usr/bin:/bin" /bin/sh -c "command -v '$adl_executable'" 2>/dev/null)"; then
+      echo "ERROR global-tools: could not resolve adl from the administrator PATH" >&2
       exit 1
     fi
     [[ -n "$adl_resolved" && -x "$adl_resolved" ]] || {
-      echo "global-tools: kimi-hooks requires adl on PATH ($adl_executable); bun-compile installation must succeed first" >&2
+      echo "ERROR global-tools: kimi-hooks requires adl on PATH ($adl_executable); the adl package installation must succeed first" >&2
       exit 1
     }
     echo "global-tools: kimi hooks mode=apply home=$administrator_home (as $administrator)"
@@ -2629,7 +2968,7 @@ if [[ "$kimi_hooks_enabled" == true ]]; then
     # streams live exactly as before.
     kimi_hooks_status=0
     kimi_hooks_output="$(cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
-      "$script_dir/kimi-hooks" --home "$administrator_home" --mode apply)" || kimi_hooks_status=$?
+      "$BASH" "$script_dir/kimi-hooks" --home "$administrator_home" --mode apply)" || kimi_hooks_status=$?
     printf '%s\n' "$kimi_hooks_output"
     collect_kimi_hooks_backups "$kimi_hooks_output"
     [[ "$kimi_hooks_status" -eq 0 ]] || exit "$kimi_hooks_status"
@@ -2642,50 +2981,11 @@ fi
 # run the same hook contract twice. The exact old path remains Enact-owned.
 if [[ "$mode" != apply ]]; then
   echo "global-tools: retired OpenCode carrier mode=plan home=$administrator_home"
-  "$script_dir/opencode-hooks" --home "$administrator_home" --mode plan
+  "$BASH" "$script_dir/opencode-hooks" --home "$administrator_home" --mode plan
 else
   echo "global-tools: retired OpenCode carrier mode=remove home=$administrator_home (as $administrator)"
   (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
-    "$script_dir/opencode-hooks" --home "$administrator_home" --mode remove)
-fi
-
-# STATUS.md 12p item 13, final scope (2026-09-29): lean-ctx hooks are "moved
-# to repo level" and must be REMOVED FROM GLOBAL -- the per-repo carrier
-# (`adl hook lean-ctx pre-tool-use|post-tool-use --host=<x>`, written by
-# `adl hooks deploy`) already provides them with the repo's own config, so
-# any raw, unwrapped `lean-ctx hook <subcommand>` entry left in a per-user
-# config (observe, rewrite, redirect, read-dedup, any other) is retracted
-# global wiring, never the per-repo carrier or Orca's own hooks -- see
-# bin/lib/lean-ctx-observe-hooks.sh's header for the full decision trail and
-# exactly which per-user files can carry one. Unconditional, like the
-# retired OpenCode carrier cleanup just above: not a manifest-gated optional
-# feature, a standing cleanup that runs every reconciliation so a
-# hand-edited or Orca-reinstalled per-user config never lets this creep back
-# in unnoticed.
-if [[ "$mode" != apply ]]; then
-  echo "global-tools: lean-ctx observe/raw-hook strip mode=plan home=$administrator_home"
-  # Plan runs either unprivileged (the administrator's own shell) or under
-  # sudo (fleet-cutover.sh's plan). As root it must drop to the administrator
-  # exactly like apply: lean-ctx-observe-strip refuses root against a
-  # non-root home (m5 cutover plan, 2026-09-29).
-  if [[ "$EUID" -eq 0 && "$administrator" != root ]]; then
-    (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
-      "$script_dir/lean-ctx-observe-strip" --home "$administrator_home" --mode plan)
-  else
-    "$script_dir/lean-ctx-observe-strip" --home "$administrator_home" --mode plan
-  fi
-else
-  echo "global-tools: lean-ctx observe/raw-hook strip mode=apply home=$administrator_home (as $administrator)"
-  # stdout captured (then re-printed) so its own "backed up previous config
-  # to ..." note(s) can be folded into this run's combined backups list,
-  # exactly like kimi-hooks above; stderr left unredirected so a real
-  # failure (a file that fails to parse) still streams live.
-  lean_ctx_observe_strip_status=0
-  lean_ctx_observe_strip_output="$(cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
-    "$script_dir/lean-ctx-observe-strip" --home "$administrator_home" --mode apply)" || lean_ctx_observe_strip_status=$?
-  printf '%s\n' "$lean_ctx_observe_strip_output"
-  collect_lean_ctx_observe_strip_backups "$lean_ctx_observe_strip_output"
-  [[ "$lean_ctx_observe_strip_status" -eq 0 ]] || exit "$lean_ctx_observe_strip_status"
+    "$BASH" "$script_dir/opencode-hooks" --home "$administrator_home" --mode remove)
 fi
 
 # surface-policy re-asserts each host's permission MODE from the single source
@@ -2708,11 +3008,11 @@ fi
 if [[ "$surface_policy_enabled" == true ]]; then
   if [[ "$mode" != apply ]]; then
     echo "global-tools: surface policy mode=plan home=$administrator_home"
-    "$script_dir/surface-policy" --home "$administrator_home" --mode plan
+    "$BASH" "$script_dir/surface-policy" --home "$administrator_home" --mode plan
   else
     echo "global-tools: surface policy mode=apply home=$administrator_home (as $administrator)"
     (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
-      "$script_dir/surface-policy" --home "$administrator_home" --mode apply)
+      "$BASH" "$script_dir/surface-policy" --home "$administrator_home" --mode apply)
   fi
 fi
 
@@ -2724,24 +3024,24 @@ fi
 if [[ "$vscode_settings_enabled" == true ]]; then
   if [[ "$mode" != apply ]]; then
     echo "global-tools: VS Code settings mode=plan home=$administrator_home"
-    "$script_dir/vscode-settings" --home "$administrator_home" --platform "$platform" --mode plan
+    "$BASH" "$script_dir/vscode-settings" --home "$administrator_home" --platform "$platform" --mode plan
   else
     echo "global-tools: VS Code settings mode=apply home=$administrator_home (as $administrator)"
     (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
-      "$script_dir/vscode-settings" --home "$administrator_home" --platform "$platform" --mode apply)
+      "$BASH" "$script_dir/vscode-settings" --home "$administrator_home" --platform "$platform" --mode apply)
   fi
 fi
 
 if [[ "$global_agents_enabled" == true ]]; then
   if [[ "$mode" != apply ]]; then
     echo "global-tools: global agents mode=status home=$administrator_home"
-    "$script_dir/global-agents" --home "$administrator_home" --mode status
+    "$BASH" "$script_dir/global-agents" --home "$administrator_home" --mode status
   else
     echo "global-tools: global agents mode=deploy home=$administrator_home (as $administrator)"
     # The exact target files are authoritative global artifacts. Drift is
     # replaced from GLOBAL-AGENTS.md with no backup or leave-in-place branch.
     (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
-      "$script_dir/global-agents" --home "$administrator_home" --mode deploy)
+      "$BASH" "$script_dir/global-agents" --home "$administrator_home" --mode deploy)
   fi
 fi
 
@@ -2764,14 +3064,14 @@ fi
 if [[ "$mode" == apply ]]; then
   if repo_root_is_git; then
     applied_commit="$(sudo -u "$administrator" -H git -C "$repo_root" rev-parse HEAD)" || {
-      echo "could not resolve checkout commit for applied manifest identity" >&2
+      echo "ERROR could not resolve checkout commit for applied manifest identity" >&2
       exit 1
     }
   else
     # az374: the installed npm package's own version is the identity of what
     # was applied -- there is no commit to ask for.
     applied_npm_version="$(jq -er '.version | select(type == "string" and length > 0)' "$repo_root/package.json")" || {
-      echo "installed Adl package has no valid version: $repo_root/package.json" >&2
+      echo "ERROR installed Adl package has no valid version: $repo_root/package.json" >&2
       exit 1
     }
     applied_commit="npm:$applied_npm_version"
@@ -2785,83 +3085,6 @@ else
   echo "global-tools: $mode complete; no state changed"
 fi
 
-# git_maintain_repos (2026-09-30, arm-only decision the same day): an
-# explicit, closed list of repositories this device's own checkout lives
-# at OUTSIDE any recursively-scanned home directory -- the Linux VPSes'
-# root-owned /opt/adl-azdo is the confirmed case for both strato-vps-1 and
-# hostinger-vps-1 (STATUS.md's 2026-09-29 first-deployment record;
-# hostinger's own fleet-cutover --apply landed 2026-09-29T23:43Z, confirmed
-# the same day). git-maintain's own scheduling (packages/fleet/src/
-# launch-agents.ts: a dedicated compiled binary, ad-hoc signed, run by a
-# launchd LaunchAgent under TCC) is macOS-only by construction, so it never
-# reaches these checkouts on its own. This runs the job directly, on
-# reconcile's own schedule (every platform this script runs on already has
-# one), passing each declared path as `--repo` argv -- never a recursive
-# scan of a shared parent like `/opt` (which also holds unrelated,
-# explicitly off-limits directories), and never a new environment
-# variable: the list itself comes only from the manifest, and
-# GIT_MAINTAIN_DRY below is this job's own pre-existing dry/real contract,
-# driven by reconcile's own --mode exactly like every other step in this
-# file, not a knob an operator sets by hand. Absent or empty (every mac
-# device today) is a silent no-op, the same convention
-# launch_agents/scratch_repos/surface_clis already use.
-#
-# ARM-ONLY, always, on this path (independent review, 2026-09-30): the full
-# job on this SAME checkout `bin/reconcile` runs from turned out to be new,
-# unapproved, root-run behaviour once actually reasoned through, not merely
-# a self-checkout read/write ordering hazard -- see the `--arm-only`
-# decision recorded in jobs/git-maintain/src/main.ts's own header comment
-# for the full list (a silent fast-forward-driven auto-deploy of
-# `origin/integration`/main with no approval gate, colliding with
-# fleet-cutover.sh re-reading fleet-retire-list.json from this same
-# checkout after reconcile runs, `git branch -D` as root, and a fetch that
-# still runs even in dry/plan/audit mode and exits 0 on its own failure).
-# `--arm-only` narrows this call to ONLY `armHooks`: no fetch, no
-# fast-forward, no branch prune, no bundle-refresh installer, no network,
-# and no Azure DevOps identity resolution. The only remaining write is
-# `.git/config`'s `core.hooksPath`, real only in apply mode
-# (GIT_MAINTAIN_DRY=1 below makes it a `[dry] would arm ...` log line and
-# nothing else, in both plan AND audit mode). That is never a tracked file
-# this script (or anything downstream of it) reads, so arm-only has no
-# self-checkout read/write ordering hazard left to avoid -- this step stays
-# in this late position anyway, unchanged from the full-job version: it is
-# still the simplest place for it, and there is no reason to special-case
-# arm-only's position just because its own hazard is gone.
-git_maintain_repos=()
-while IFS= read -r repo; do
-  [[ -n "$repo" ]] && git_maintain_repos+=("$repo")
-done < <(jq -r --arg platform "$platform" --arg device "$device" \
-  '.[$platform].devices[$device].git_maintain_repos // [] | .[]' "$manifest")
-if [[ "${#git_maintain_repos[@]}" -gt 0 ]]; then
-  git_maintain_repo_args=(--arm-only)
-  for repo in "${git_maintain_repos[@]}"; do
-    git_maintain_repo_args+=(--repo "$repo")
-  done
-  # Unlike default-agent-file.ts/managed-settings.ts's plan branches earlier
-  # in this file (which never fail, by construction, so they run
-  # unguarded), this job's dry pass still validates each declared path is a
-  # real repo -- a genuine failure mode even in a non-apply mode, e.g. a
-  # declared checkout that has not been cloned yet. So every non-apply mode
-  # is guarded exactly like apply mode here, deliberately deviating from
-  # those sibling steps: report it, collect it, never let it abort the rest
-  # of this script under this file's own `set -e`. `$mode` (plan OR audit)
-  # is reported verbatim -- audit is a real, distinct reconcile mode, never
-  # relabeled "plan".
-  if [[ "$mode" != apply ]]; then
-    echo "global-tools: git-maintain (declared repos, arm-only) mode=$mode device=$device -> ${git_maintain_repos[*]}"
-    if ! GIT_MAINTAIN_DRY=1 bun "$repo_root/packages/fleet/jobs/git-maintain/src/main.ts" "${git_maintain_repo_args[@]}"; then
-      echo "global-tools: TOOL INSTALL FAILED: git-maintain-repos" >&2
-      failed_tools+=("git-maintain-repos")
-    fi
-  else
-    echo "global-tools: git-maintain (declared repos, arm-only) mode=apply device=$device -> ${git_maintain_repos[*]}"
-    if ! bun "$repo_root/packages/fleet/jobs/git-maintain/src/main.ts" "${git_maintain_repo_args[@]}"; then
-      echo "global-tools: TOOL INSTALL FAILED: git-maintain-repos" >&2
-      failed_tools+=("git-maintain-repos")
-    fi
-  fi
-fi
-
 # A recorded, continued-past tool failure (install_one_tool /
 # build_one_bun_tool / install_one_embedding_model_tool / write_one_shim)
 # still lets every post-pass above run -- sweep, kimi-hooks, global-agents,
@@ -2869,11 +3092,11 @@ fi
 # this point. The non-zero exit here is the only signal a caller (cron,
 # systemd, CI) needs that something needs attention.
 if [[ "${#failed_tools[@]}" -gt 0 ]]; then
-  echo "global-tools: FAILED to install/build ${#failed_tools[@]} tool(s): ${failed_tools[*]}" >&2
+  echo "ERROR global-tools: FAILED to install/build ${#failed_tools[@]} tool(s): ${failed_tools[*]}" >&2
   exit 1
 fi
 
 if [[ "$scratch_reap_failed" -eq 1 ]]; then
-  echo "global-tools: scratch reap could not verify remotes; worktree removal was refused" >&2
+  echo "ERROR global-tools: scratch reap could not verify remotes; worktree removal was refused" >&2
   exit 1
 fi