@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/bin/reconcile

@@ -0,0 +1,2648 @@
+#!/usr/bin/env bash
+
+# Bash version gate -- runs FIRST, before `set -euo pipefail`, before the
+# PATH export, before any argument parsing, before any state change. This
+# script relies on `"${arr[@]}"` expansions over arrays that are legitimately
+# empty in production (e.g. system_root_args when RECONCILE_TEST_SYSTEM_ROOT
+# is unset, which is every real run). Under bash < 4.4's `set -u`, expanding
+# an EMPTY array with `[@]`/`[*]` throws "unbound variable" instead of
+# expanding to nothing -- fixed in bash 4.4 (2016). macOS ships /bin/bash
+# 3.2.57 (the last GPLv2 release Apple will ship) and never upgrades it;
+# `sudo`'s secure_path can select that 3.2 over a newer Homebrew bash even
+# when one is installed and on the invoking user's own PATH, so a real
+# `sudo bin/reconcile ...` run can hit this after this run had already
+# deleted state (manifest entries) -- a partial, not a clean, failure. Two
+# independent fixes, belt-and-suspenders, deliberately not just one:
+#   1. THIS gate: if the running bash is older than 4.4, re-exec the very
+#      same invocation (same $0, same args) under the first known-newer bash
+#      found on this machine, or fail loudly and exit BEFORE anything else
+#      runs if none is found -- never a silent continue under the old bash.
+#   2. Every remaining empty-array expansion in this script is ALSO guarded
+#      with the `${a[@]+"${a[@]}"}` idiom (see e.g. system_root_args below),
+#      so behaviour is correct even if this gate were ever bypassed.
+# RECONCILE_REEXEC_BASH marks "this process is already the re-exec'd child"
+# so a re-exec under a bash that ALSO happens to be <4.4 (a broken/ancient
+# Homebrew bash, say) can't loop forever -- it just proceeds to the normal
+# version check failure below instead.
+# RECONCILE_TEST_BASH_CANDIDATES (test-only, unset in every real run) is a
+# space-separated override of the candidate list below, so a test can force
+# either branch (found vs not-found) hermetically, without depending on
+# whether THIS machine happens to have Homebrew bash installed.
+if [[ -z "${RECONCILE_REEXEC_BASH:-}" ]]; then
+  reconcile_bash_major="${BASH_VERSINFO[0]:-0}"
+  reconcile_bash_minor="${BASH_VERSINFO[1]:-0}"
+  if [[ "$reconcile_bash_major" -lt 4 || ( "$reconcile_bash_major" -eq 4 && "$reconcile_bash_minor" -lt 4 ) ]]; then
+    reconcile_bash_candidates="${RECONCILE_TEST_BASH_CANDIDATES:-/opt/homebrew/bin/bash /usr/local/bin/bash /home/linuxbrew/.linuxbrew/bin/bash}"
+    reconcile_newer_bash=""
+    for reconcile_bash_candidate in $reconcile_bash_candidates; do
+      if [[ -x "$reconcile_bash_candidate" ]]; then
+        reconcile_newer_bash="$reconcile_bash_candidate"
+        break
+      fi
+    done
+    if [[ -n "$reconcile_newer_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
+    exit 1
+  fi
+fi
+
+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
+  exit 2
+}
+
+device=""
+mode="audit"
+manifest=""
+state_dir="/var/lib/adl"
+platform_override=""
+source_mode="npm"
+# A plain variable, not a hardcoded literal in write_one_repo_dir/
+# 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.
+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
+# run -- production reconcile never sets this, so `--root` is never passed
+# and behaviour is byte-identical. When set (packages/fleet/tests/
+# test-manifest.sh only), forwarded as `--root <dir>` to every plan AND apply
+# invocation of both scripts below, so a test never reads or writes the real
+# `/Library/Application Support/...` or `/etc/...` paths.
+reconcile_test_system_root_args=()
+if [[ -n "${RECONCILE_TEST_SYSTEM_ROOT:-}" ]]; then
+  reconcile_test_system_root_args=(--root "$RECONCILE_TEST_SYSTEM_ROOT")
+fi
+while [[ "$#" -gt 0 ]]; do
+  case "$1" in
+    --device) device="${2:-}"; shift 2 ;;
+    --mode) mode="${2:-}"; shift 2 ;;
+    --manifest) manifest="${2:-}"; shift 2 ;;
+    --state-dir) state_dir="${2:-}"; shift 2 ;;
+    --platform) platform_override="${2:-}"; shift 2 ;;
+    --source) source_mode="${2:-}"; shift 2 ;;
+    *) usage ;;
+  esac
+done
+[[ -n "$device" ]] || usage
+[[ "$mode" == audit || "$mode" == plan || "$mode" == apply ]] || usage
+[[ "$source_mode" == npm || "$source_mode" == checkout ]] || usage
+
+# Tool ids whose install/build failed in a way that was recorded and
+# continued past, rather than aborting the whole reconciliation (see
+# install_one_tool / build_one_bun_tool / install_one_embedding_model_tool /
+# write_one_shim below). Populated only in apply mode -- every other mode's
+# tool-loop bodies only print "would ..." and never fail.
+failed_tools=()
+
+# Every backup THIS run actually created (apply mode) or would create (plan
+# mode), as "<original path> -> <backup path>" strings -- printed as one
+# 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
+# (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
+# (recorded directly; it runs in this same process, so no output-parsing is
+# needed). managed-settings, default-agent-file, vscode-settings,
+# surface-policy, and global-agents do not back anything up
+# before overwriting -- see this file's own header comment on each call site,
+# and packages/fleet/tests/test-manifest.sh's backups-summary tests, for the
+# full accounting of which steps do and do not.
+backups=()
+
+record_backup() {
+  backups+=("$1 -> $2")
+}
+
+# Every backup path in this codebase has the shape
+# "<original-path>.pre-<label>-<UTC compact timestamp>" (kimi-hooks:
+# backupPath() in packages/agent-settings/src/kimi-hooks.ts;
+# write_one_repo_script below uses the same shape). Recovering the original
+# by stripping exactly that trailing segment means a backup-creating step's
+# own note text never has to repeat the original path a second time just so
+# this summary can report it.
+strip_backup_suffix() {
+  local backup="$1"
+  if [[ "$backup" =~ ^(.*)\.pre-[a-z0-9-]+-[0-9]{8}T[0-9]{6}Z$ ]]; then
+    printf '%s\n' "${BASH_REMATCH[1]}"
+  else
+    printf '%s\n' "$backup"
+  fi
+}
+
+# Scans a captured step's stdout for kimi-hooks' own "... backed up ... to
+# <path>" sentence and records it. A no-op on plan-mode output (kimi-hooks
+# --mode plan never writes, so it never emits this note).
+collect_kimi_hooks_backups() {
+  local text="$1" line backup
+  while IFS= read -r line; do
+    if [[ "$line" =~ ^kimi-hooks:\ backed\ up\ previous\ config\ to\ (.+)$ ]]; then
+      backup="${BASH_REMATCH[1]}"
+      record_backup "$(strip_backup_suffix "$backup")" "$backup"
+    fi
+  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"
+    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
+# backupPath() or any other sweep-owned logic (Tarun, 2026-09-28: a separate
+# change added the sweep's own "global-surface-sweep: backups this run:" /
+# "... no files changed; no backups" lines in
+# packages/agent-settings/src/global-surface-sweep.ts). Its "backups this
+# run:" block is followed by two-space-indented "<original> -> <backup>"
+# lines -- already in exactly this file's own record_backup shape.
+collect_sweep_backups() {
+  local text="$1" line in_block=0 original backup
+  while IFS= read -r line; do
+    if [[ "$line" == "global-surface-sweep: backups this run:" ]]; then
+      in_block=1
+      continue
+    fi
+    if [[ "$in_block" -eq 1 ]]; then
+      if [[ "$line" =~ ^\ \ (.+)\ -\>\ (.+)$ ]]; then
+        original="${BASH_REMATCH[1]}"
+        backup="${BASH_REMATCH[2]}"
+        record_backup "$original" "$backup"
+        continue
+      fi
+      in_block=0
+    fi
+  done <<<"$text"
+}
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+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
+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
+    exit 2
+  fi
+  if [[ "$source_mode" == checkout && ! -e "$repo_root/.git" ]]; then
+    echo "checkout source mode requires a Git checkout" >&2
+    exit 2
+  fi
+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 ;;
+esac
+if [[ -n "$platform_override" ]]; then
+  # Applying as a foreign platform would install the wrong platform's tools, so
+  # the override stays refused -- EXCEPT under RECONCILE_SOURCE_ONLY=1, which
+  # returns below before any loop or post-pass runs. Nothing is applied in that
+  # mode, so there is nothing for the guard to protect, and without this a test
+  # exercising a mac device in apply mode is silently macOS-only: on the Linux
+  # 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
+    exit 2
+  fi
+  [[ "$platform_override" == mac || "$platform_override" == linux ]] || usage
+  platform="$platform_override"
+fi
+
+jq -e --arg platform "$platform" --arg device "$device" '.[$platform].devices[$device]' "$manifest" >/dev/null || {
+  echo "device $device is not declared under $platform" >&2
+  exit 1
+}
+
+resolved_file="$(mktemp)"
+previous_resolved_file="$(mktemp)"
+trap 'rm -f "$resolved_file" "$previous_resolved_file"' EXIT
+jq --arg platform "$platform" --arg device "$device" \
+  '.[$platform].common.tools * .[$platform].devices[$device].tools' "$manifest" >"$resolved_file"
+
+applied_manifest="$state_dir/applied-manifest.json"
+have_previous=0
+if [[ -f "$applied_manifest" ]] && jq -e --arg platform "$platform" --arg device "$device" '.[$platform].devices[$device]' "$applied_manifest" >/dev/null 2>&1; then
+  jq --arg platform "$platform" --arg device "$device" \
+    '.[$platform].common.tools * .[$platform].devices[$device].tools' "$applied_manifest" >"$previous_resolved_file"
+  have_previous=1
+else
+  printf '{}\n' >"$previous_resolved_file"
+fi
+
+administrator="$(jq -r --arg platform "$platform" --arg device "$device" '.[$platform].devices[$device].administrator' "$manifest")"
+administrator_home="$(jq -r --arg platform "$platform" --arg device "$device" '.[$platform].devices[$device].home' "$manifest")"
+minimum_free_gib="$(jq -r --arg platform "$platform" --arg device "$device" '.[$platform].devices[$device].minimum_free_gib' "$manifest")"
+if [[ "$platform" == mac ]]; then
+  brew_bin=/opt/homebrew/bin/brew
+else
+  brew_bin=/home/linuxbrew/.linuxbrew/bin/brew
+fi
+
+path_owner() {
+  local path="$1" owner
+  if owner="$(stat -f '%Su' "$path" 2>/dev/null)"; then
+    printf '%s\n' "$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
+    return 1
+  fi
+}
+
+resolve_brew_owner() {
+  local target_platform="$1" target_mode="$2" prefix="$3" target_administrator="$4" owner
+  if [[ "$target_platform" == mac ]]; then
+    printf '%s\n' "$target_administrator"
+    return 0
+  fi
+  if [[ ! -d "$prefix" ]]; then
+    if [[ "$target_mode" == apply ]]; then
+      echo "Homebrew prefix missing: $prefix" >&2
+      return 1
+    fi
+    printf '%s\n' '<unresolved-linuxbrew-owner>'
+    return 0
+  fi
+  owner="$(path_owner "$prefix")" || return 1
+  if [[ "$owner" == root ]]; then
+    echo "Homebrew prefix must be owned by a non-root account: $prefix" >&2
+    return 1
+  fi
+  printf '%s\n' "$owner"
+}
+
+brew_owner="$(resolve_brew_owner "$platform" "$mode" "${brew_bin%/bin/brew}" "$administrator")" || exit 1
+git_config_user="$administrator"
+
+run_brew() {
+  if [[ "$mode" != apply ]]; then
+    printf 'would run brew as %s: %q' "$brew_owner" "$brew_bin"
+    printf ' %q' "$@"
+    printf '\n'
+    return 0
+  fi
+  [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
+  (cd /tmp && sudo -u "$brew_owner" -H env NONINTERACTIVE=1 PATH="${brew_bin%/*}:/usr/bin:/bin" "$brew_bin" "$@" </dev/null)
+}
+
+# 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
+# exactly the machine this exists to protect. Temporarily enable Bash job
+# control so the backgrounded command gets its own process group, then send
+# SIGTERM-then-SIGKILL to that whole group at the deadline. This covers child
+# processes (brew helpers or self-updaters) as well as the wrapper subshell and
+# prevents them from continuing after reconcile reports a timeout. Restore the
+# caller's original job-control setting before returning. Exit 124 distinguishes
+# a timeout from the command's own failure. Per-call-site timeouts let
+# packages/fleet/tests/test-manifest.sh exercise this branch in real time
+# (e.g. RECONCILE_BREW_UPGRADE_TIMEOUT_SECONDS=1) rather than waiting out the
+# real 20-minute default below.
+run_with_timeout() {
+  local timeout_seconds="$1"
+  shift
+  local status=0
+  local monitor_was_enabled=false
+  case $- in *m*) monitor_was_enabled=true ;; esac
+  set -m
+  ( "$@" ) &
+  local pid=$!
+  if [[ "$monitor_was_enabled" != true ]]; then
+    set +m
+  fi
+  local waited=0
+  while kill -0 "$pid" 2>/dev/null; do
+    if [[ "$waited" -ge "$timeout_seconds" ]]; then
+      kill -TERM -- "-$pid" 2>/dev/null || true
+      sleep 1
+      kill -KILL -- "-$pid" 2>/dev/null || true
+      wait "$pid" 2>/dev/null || :
+      return 124
+    fi
+    sleep 1
+    waited=$((waited + 1))
+  done
+  wait "$pid" || status=$?
+  return "$status"
+}
+
+# Timeouts for the two long-running, network-dependent steps this decision
+# adds (brew upgrade, and each agent-surface CLI update below): generous
+# defaults for a real run (20 minutes, 5 minutes), overridable per-call-site
+# so test-manifest.sh can exercise the "hung command" branch in real time
+# instead of waiting out either default for real.
+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.
+run_brew_upgrade_all() {
+  if [[ "$mode" != apply ]]; then
+    echo "would run: brew upgrade (all outdated formulae and casks)"
+    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
+    return 1
+  }
+  outdated_casks="$(brew_query outdated --cask --quiet)" || {
+    echo "brew outdated --cask check failed" >&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 ' ')"
+  if [[ "$formulae_count" -eq 0 && "$casks_count" -eq 0 ]]; then
+    echo "brew upgrade: nothing outdated"
+    return 0
+  fi
+  local upgrade_output 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.
+  upgrade_output="$(run_with_timeout "$BREW_UPGRADE_ALL_TIMEOUT_SECONDS" run_brew upgrade 2>&1)" || upgrade_status=$?
+  printf '%s\n' "$upgrade_output"
+  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
+  fi
+  echo "brew upgrade: $formulae_count formulae, $casks_count casks were outdated before upgrade"
+  return 0
+}
+
+run_apt() {
+  if [[ "$mode" != apply ]]; then
+    printf 'would run apt-get:'
+    printf ' %q' "$@"
+    printf '\n'
+    return 0
+  fi
+  [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
+  env DEBIAN_FRONTEND=noninteractive apt-get "$@" </dev/null
+}
+
+# npm and pip both resolve through whichever PATH prefix brew's own tools use
+# (node/npm are Homebrew formulas already; python3 ships with the OS or CLT on
+# every device this reconciler targets), so they share brew_bin's directory
+# rather than needing their own resolution.
+run_npm() {
+  if [[ "$mode" != apply ]]; then
+    printf 'would run npm as %s: npm' "$administrator"
+    printf ' %q' "$@"
+    printf '\n'
+    return 0
+  fi
+  [[ "$(id -u)" -eq 0 ]] || { echo "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
+    (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" npm "$@" </dev/null)
+  fi
+}
+
+# Whether a read-only, owner-scoped query (brew_query, npm_installed_version)
+# can run without asking for privilege reconcile does not already have. Apply
+# mode always runs as real root (checked elsewhere), which can sudo -u any
+# administrator with no password. A plan/audit preview run has no such
+# guarantee -- $administrator on a Linux VPS device is "root", and previewing
+# that device's plan from an unprivileged account must not demand a sudo
+# password it may not have; it falls back to the pre-2026-09-28 unconditional
+# message instead. Self-administered devices (m3: administrator=tarunrana)
+# need no escalation at all, so their preview can query for real.
+can_query_as_administrator() {
+  [[ "$(id -un)" == "$administrator" ]] || [[ "$(id -u)" -eq 0 ]]
+}
+
+# Read-only Homebrew query, run exactly like run_brew's real mutations (same
+# owner, cwd, and stdin) but never a mutation itself. A named function so
+# tests can stub just this, instead of having to fake sudo's own argument
+# parsing the way a raw inline `sudo -u ... "$brew_bin" ...` would require.
+# Apply-mode only (see can_query_as_administrator): `brew list`/`brew
+# outdated` have been observed to take minutes under real load on a
+# contended box (Homebrew's own auto-update against a large git checkout),
+# so a plan preview never calls this -- it would turn a "quick look" into a
+# slow, load-dependent one for every brew formula on the device.
+brew_query() {
+  (cd /tmp && sudo -u "$brew_owner" -H "$brew_bin" "$@" </dev/null)
+}
+
+# Read-only global npm version lookups, run with the same user/PATH (and, on
+# Linux, the same npm_config_prefix) as run_npm's real mutations, so a lookup
+# never disagrees with what an install would actually see. Both are named
+# functions for the same stubbing reason as brew_query above.
+#
+# npm ls -g's own exit code is NOT a reliable failure signal: it exits 1 for
+# the completely ordinary case of "this package is not installed" (valid,
+# parseable JSON either way) -- treating that as an error would turn "not
+# installed yet" into a false alarm. A REAL failure (npm itself could not
+# run: missing binary, sudo denied, corrupt output) instead fails to produce
+# parseable JSON at all, which is the actual signal this checks for.
+npm_installed_version() {
+  local package="$1" json
+  if [[ "$platform" == linux ]]; then
+    json="$(cd /tmp && sudo -u "$administrator" -H env npm_config_prefix=/usr/local PATH="${brew_bin%/*}:/usr/bin:/bin" npm ls -g --depth=0 --json "$package" </dev/null 2>/dev/null)"
+  else
+    json="$(cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" npm ls -g --depth=0 --json "$package" </dev/null 2>/dev/null)"
+  fi
+  jq -e . >/dev/null 2>&1 <<<"$json" || return 1
+  jq -r --arg pkg "$package" '.dependencies[$pkg].version // empty' <<<"$json"
+}
+
+# Unlike `npm ls -g`, `npm view <pkg> version` DOES fail (real, non-zero exit)
+# for a genuinely missing/unpublished package -- verified live 2026-09-28
+# (404 from the registry) -- so its own exit code is trusted directly here.
+npm_latest_version() {
+  local package="$1"
+  if [[ "$platform" == linux ]]; then
+    (cd /tmp && sudo -u "$administrator" -H env npm_config_prefix=/usr/local PATH="${brew_bin%/*}:/usr/bin:/bin" npm view "$package" version </dev/null 2>/dev/null)
+  else
+    (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" npm view "$package" version </dev/null 2>/dev/null)
+  fi
+}
+
+npm_global_root() {
+  [[ "$mode" == apply ]] || return 1
+  if [[ "$platform" == linux ]]; then
+    (cd /tmp && sudo -u "$administrator" -H env npm_config_prefix=/usr/local PATH="${brew_bin%/*}:/usr/bin:/bin" npm root -g </dev/null)
+  else
+    (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" npm root -g </dev/null)
+  fi
+}
+
+npm_global_executable_path() {
+  local executable="$1"
+  sudo -u "$administrator" -H env PATH="/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/local/bin:/usr/bin:/bin" \
+    /bin/sh -c 'command -v "$1"' /bin/sh "$executable" 2>/dev/null
+}
+
+canonical_parent_path() {
+  local path="$1" parent base
+  parent="${path%/*}"
+  base="${path##*/}"
+  (cd -P "$parent" && printf '%s/%s\n' "$PWD" "$base")
+}
+
+# A successful npm exit code alone does not prove that the command now belongs
+# to npm: Linux has both legacy Bun binaries and npm shims in /usr/local/bin.
+# Confirm the package's declared bin target owns the command before accepting
+# the install.
+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
+    return 1
+  }
+  package_manifest="$npm_root/$package/package.json"
+  [[ -f "$package_manifest" ]] || {
+    echo "npm package metadata missing: $package_manifest" >&2
+    return 1
+  }
+  bin_relative="$(jq -r --arg executable "$executable" '
+    if (.bin | type) == "string" then .bin
+    elif (.bin | type) == "object" then .bin[$executable] // empty
+    else empty
+    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
+    return 1
+  }
+  actual_path="$(npm_global_executable_path "$executable")" || {
+    echo "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
+    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
+    return 1
+  }
+  actual_link="$(readlink "$actual_path")" || return 1
+  if [[ "$actual_link" == /* ]]; then
+    actual_target="$(canonical_parent_path "$actual_link")" || return 1
+  else
+    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
+    return 1
+  }
+}
+
+run_pip() {
+  if [[ "$mode" != apply ]]; then
+    printf 'would run pip as %s: python3 -m pip' "$administrator"
+    printf ' %q' "$@"
+    printf '\n'
+    return 0
+  fi
+  [[ "$(id -u)" -eq 0 ]] || { echo "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
+    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
+    exit 1
+  }
+  printf '%s/bin/%s\n' "${user_base%/}" "$executable"
+}
+
+ensure_global_pip_executable() {
+  local executable="$1"
+  local target="/usr/local/bin/$executable"
+  if [[ "$mode" != apply ]]; then
+    echo "would expose pip executable globally: $target"
+    return 0
+  fi
+  [[ "$(id -u)" -eq 0 ]] || { echo "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; }
+  if [[ -L "$target" ]]; then
+    existing_source="$(readlink "$target")"
+    if [[ "$existing_source" == "$source" ]]; then
+      echo "global pip executable already points to $source"
+      return 0
+    fi
+    case "$existing_source" in
+      "$user_home"/*/bin/"$executable") ;;
+      *) echo "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
+    exit 1
+  fi
+  ln -sfn "$source" "$target"
+  echo "exposed pip executable globally: $target -> $source"
+}
+
+remove_global_pip_executable() {
+  local executable="$1"
+  local target="/usr/local/bin/$executable"
+  if [[ "$mode" != apply ]]; then
+    echo "would remove global pip executable: $target"
+    return 0
+  fi
+  [[ "$(id -u)" -eq 0 ]] || { echo "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; }
+  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 ;;
+  esac
+}
+
+# Git as the checkout's owner: launchd runs apply as root against a
+# user-owned checkout, and Git's ownership guard rejects that unless the
+# lookup runs as its owner. Plan/audit runs already are that user.
+repo_git() {
+  if [[ "$(id -u)" -eq 0 ]]; then
+    sudo -u "$administrator" -H git -C "$repo_root" "$@"
+  else
+    git -C "$repo_root" "$@"
+  fi
+}
+
+# az374 (npm-sourced reconcile): true only on a live Git clone of this
+# repository (today's dev/CI shape, and every existing test fixture below).
+# False once the fleet job's source is the published npm package --
+# $repo_root is then the installed package directory itself, with no .git,
+# and IS the release artifact rather than something to ask git about.
+repo_root_is_git() {
+  [[ -e "$repo_root/.git" ]]
+}
+
+# Content identity for a source directory when there is no git to ask
+# (repo_root_is_git is false): every tracked-equivalent file's path and bytes,
+# hashed in a path-sorted, platform-independent order so the result does not
+# depend on directory read order between Darwin and Linux. Deliberately plain
+# `find | sort` (newline-delimited, no GNU-only `-print0`/`sort -z`) -- these
+# are our own source trees, not adversarial input, and this runs on Darwin
+# (BSD find/sort, no -z) as well as Linux.
+content_tree_hash() {
+  local dir="$1" f
+  (
+    cd "$dir" && find . -type f | LC_ALL=C sort | while IFS= read -r f; do
+      "${sha256_cmd[@]+"${sha256_cmd[@]}"}" "$f"
+    done
+  ) | "${sha256_cmd[@]+"${sha256_cmd[@]}"}" | awk '{print $1}'
+}
+
+# The content identity of a bun-compile tool: the git tree hash of its
+# source directory at HEAD. It changes whenever any tracked file under that
+# directory changes -- code, package.json, and bun.lock (every bun-compile
+# source keeps its lockfile inside its own directory) -- and never for
+# commits elsewhere in the repository. HEAD, not the working tree: the
+# scheduled wrapper resets the checkout to origin/main before reconcile begins.
+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
+      return 1
+    }
+  else
+    [[ -d "$repo_root/$source_dir" ]] || {
+      echo "bun-compile source missing from installed package: $repo_root/$source_dir" >&2
+      return 1
+    }
+    hash="$(content_tree_hash "$repo_root/$source_dir")"
+  fi
+  printf '%s\n' "$hash"
+}
+
+bun_source_hash_file() {
+  printf '%s/bun-compile/%s.source-hash\n' "$state_dir" "$1"
+}
+
+run_bun_compile() {
+  local package="$1"
+  local source_hash="$2"
+  local source_dir="$3"
+  local entry="$4"
+  local target="$5"
+  if [[ "$mode" != apply ]]; then
+    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; }
+  [[ "$source_dir" != /* && "$source_dir" != *..* ]] || {
+    echo "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; }
+  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; }
+  (cd "$project_dir" && "$bun_bin" install --frozen-lockfile)
+  bun_compile_build "$bun_bin" "$project_dir/$entry" "$target"
+}
+
+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"
+    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; }
+  (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
+# $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.
+atomic_install_executable() {
+  local src="$1"
+  local dest="$2"
+  install -m 0755 "$src" "$dest.new"
+  mv -f "$dest.new" "$dest"
+}
+
+install_surface_policy_file() {
+  local source="$repo_root/packages/agent-settings/surface-policy.json"
+  local target="/etc/adl/surface-policy.json"
+  if [[ "$mode" != apply ]]; then
+    echo "would install required surface policy: $source -> $target"
+    return 0
+  fi
+  [[ -f "$source" ]] || { echo "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
+    return 1
+  }
+  mkdir -p /etc/adl
+  install -m 0644 "$source" "$target.new"
+  mv -f "$target.new" "$target"
+  echo "installed required surface policy: $target"
+}
+
+# Resolves the release tag GitHub's own "latest" redirect currently points
+# at, without touching the api.github.com REST API (unauthenticated calls
+# there are rate-limited per source IP; this fleet's shared egress IP already
+# exhausts that limit under routine use). `.../releases/latest` 302s to
+# `.../releases/tag/vTAG`; the tag is just that redirect's last path segment.
+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; }
+  basename "$location"
+}
+
+run_release_archive() {
+  local package="$1"
+  local version="$2"
+  local url="$3"
+  local expected_sha256="$4"
+  local archive_executable="$5"
+  local target="$6"
+  if [[ "$mode" != apply ]]; then
+    printf 'would install pinned release archive: %s %s -> %s\n' "$package" "$version" "$target"
+    return 0
+  fi
+  [[ "$(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; }
+  [[ "$archive_executable" != /* && "$archive_executable" != *..* ]] || {
+    echo "unsafe archive executable path: $archive_executable" >&2
+    exit 1
+  }
+
+  (
+    local release_dir archive_file extract_dir actual_sha256
+    release_dir="$(mktemp -d)"
+    trap 'rm -rf "$release_dir"' EXIT
+    archive_file="$release_dir/release.tar.gz"
+    extract_dir="$release_dir/extract"
+    mkdir -p "$extract_dir"
+    curl --proto '=https' --proto-redir '=https' -fsSL --retry 3 -o "$archive_file" "$url"
+    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 ;;
+    esac
+    [[ "$actual_sha256" == "$expected_sha256" ]] || {
+      echo "checksum mismatch for $package $version" >&2
+      exit 1
+    }
+    tar -xzf "$archive_file" -C "$extract_dir" "$archive_executable"
+    [[ -f "$extract_dir/$archive_executable" ]] || {
+      echo "archive executable missing: $archive_executable" >&2
+      exit 1
+    }
+    atomic_install_executable "$extract_dir/$archive_executable" "$target"
+  )
+}
+
+# Like run_release_archive, but never pins a version or checksum in the
+# manifest: it always installs whatever GitHub's own "latest" alias currently
+# serves, verified against the checksums file published *in that same
+# release* (never a value carried over from a previous run or hardcoded
+# here) -- fails loud, installs nothing, if that checksums asset is missing
+# or doesn't list our asset. `.../releases/latest/download/<name>` is GitHub's
+# own stable alias for "the matching asset of whatever release is latest
+# right now", so the download itself never needs the resolved tag.
+run_release_archive_latest() {
+  local package="$1"
+  local repo="$2"
+  local asset="$3"
+  local checksums_asset="$4"
+  local archive_executable="$5"
+  local target="$6"
+  [[ "$(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; }
+  [[ "$archive_executable" != /* && "$archive_executable" != *..* ]] || {
+    echo "unsafe archive executable path: $archive_executable" >&2
+    exit 1
+  }
+
+  (
+    local release_dir archive_file checksums_file extract_dir actual_sha256 expected_sha256
+    release_dir="$(mktemp -d)"
+    trap 'rm -rf "$release_dir"' EXIT
+    archive_file="$release_dir/release.tar.gz"
+    checksums_file="$release_dir/checksums"
+    extract_dir="$release_dir/extract"
+    mkdir -p "$extract_dir"
+    curl --proto '=https' --proto-redir '=https' -fsSL --retry 3 \
+      -o "$checksums_file" "https://github.com/$repo/releases/latest/download/$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
+      exit 1
+    }
+    curl --proto '=https' --proto-redir '=https' -fsSL --retry 3 \
+      -o "$archive_file" "https://github.com/$repo/releases/latest/download/$asset"
+    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 ;;
+    esac
+    [[ "$actual_sha256" == "$expected_sha256" ]] || {
+      echo "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
+      exit 1
+    }
+    atomic_install_executable "$extract_dir/$archive_executable" "$target"
+  )
+}
+
+# global_surface_sweep.remove_unprotected wiring: when false, the sweep only
+# ever plans/reports (mode=audit) even during an apply run -- it never
+# deletes. When true (the historical, still-default behavior), an apply run
+# enforces (removes) unprotected candidates. Plan/audit reconcile runs are
+# always audit-only regardless of this flag, since they never mutate anything.
+resolve_surface_mode() {
+  local run_mode="$1" remove_unprotected="$2"
+  if [[ "$run_mode" == apply && "$remove_unprotected" == true ]]; then
+    printf 'enforce\n'
+  else
+    printf 'audit\n'
+  fi
+}
+
+# Shims run in their own pass, strictly after every real tool above has been
+# installed, upgraded, and PATH-verified — never interleaved by key order.
+# `keys[]` is alphabetical, and relying on a shim's id happening to sort after
+# its target is exactly the kind of implicit-ordering accident this project
+# elsewhere replaced with an explicit dependency graph; a real pass boundary
+# does not need one.
+#
+# install_one_tool is called as the condition of `if ! install_one_tool ...`
+# below, which -- under `set -e` -- exempts every command it runs (including
+# ones nested in the functions it calls) from aborting the script on
+# failure: a single failing tool (a flaky brew mirror, an npm 403, a
+# yanked release asset) is recorded and the loop moves on to the next tool,
+# so the sweep/kimi-hooks/global-agents/health post-passes below still run.
+# A hard `exit` inside run_brew/run_npm/etc. (e.g. "apply mode must run as
+# 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_version npm_spec npm_allow_scripts npm_target_version npm_installed_ver npm_plan_installed brew_outdated_output brew_installed_version
+  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")"
+  if [[ "$tool_id" == adl && "$source_mode" == checkout ]]; then
+    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; }
+    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"
+      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"
+    return 0
+  fi
+  echo "ensure latest stable: $tool_id ($manager:$package)"
+  case "$manager" in
+    brew)
+      # 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
+      # that cost once, for real, and only when it would otherwise blindly
+      # 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
+        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
+          if [[ -z "$brew_outdated_output" ]]; then
+            brew_installed_version="$(brew_query list --formula --versions "$package" | awk '{print $2}')"
+            echo "already latest: $tool_id (brew:$package $brew_installed_version)"
+          else
+            run_brew upgrade "$package" || rc=1
+          fi
+        else
+          echo "$tool_id: brew outdated check failed for $package" >&2
+          rc=1
+        fi
+      else
+        run_brew install "$package" || rc=1
+      fi
+      ;;
+    apt)
+      run_apt install -y "$package" || rc=1
+      ;;
+    npm)
+      # An entry's optional .version pins the installed release (e.g.
+      # adl-agent-id, Handoff 5 2026-09-26 H4) rather than tracking whatever
+      # npm resolves as latest for update_policy=latest-stable. Ownership
+      # verification below still uses the bare package name: npm's global
+      # tree and package.json are keyed by package, never by the requested
+      # version spec.
+      npm_version="$(jq -r --arg id "$tool_id" '.[$id].version // empty' "$resolved_file")"
+      npm_spec="$package"
+      [[ -z "$npm_version" ]] || npm_spec="$package@$npm_version"
+      # Only @amsterdamdatalabs/enact-docs-search's manifest entry carries
+      # this (docs/operations/global-tools.md Topic 2, decided 2026-09-28):
+      # its own dependencies' install scripts, explicitly reviewed and
+      # allowed, never a global `npm config set allow-scripts`.
+      npm_allow_scripts="$(jq -r --arg id "$tool_id" '(.[$id].allow_scripts // []) | join(",")' "$resolved_file")"
+      if [[ "$mode" != apply ]]; then
+        if is_in_place_bun_to_npm_migration "$tool_id"; then
+          previous_executable="$(jq -r --arg id "$tool_id" '.[$id].executable' "$previous_resolved_file")"
+          echo "would remove retired Bun compilation before npm install: $tool_id ($previous_executable and $(bun_source_hash_file "$tool_id"))"
+        fi
+        # A pinned version is a pure local/offline fact: compare it against
+        # the real global install (npm_installed_version, no network) and say
+        # so honestly. An UNPINNED entry's "latest stable" is not knowable
+        # without a per-package registry round trip (npm_latest_version) --
+        # doing that here would make a plan preview slow and network-bound
+        # for every unpinned npm tool on the device, so it keeps today's
+        # conservative message instead of guessing. Either way, only query
+        # when it needs no new sudo privilege (can_query_as_administrator) --
+        # a preview run must not demand a password a different device's real
+        # administrator would need.
+        if [[ -n "$npm_version" ]] && can_query_as_administrator; then
+          if npm_plan_installed="$(npm_installed_version "$package")"; then
+            if [[ -n "$npm_plan_installed" && "$npm_plan_installed" == "$npm_version" ]]; then
+              echo "already latest: $tool_id (npm:$package@$npm_plan_installed)"
+            else
+              echo "would install or upgrade npm package: $npm_spec"
+            fi
+          else
+            echo "would install or upgrade npm package: $npm_spec (installed version not checked: npm ls -g failed)"
+          fi
+        else
+          echo "would install or upgrade npm package: $npm_spec"
+        fi
+      else
+        if is_in_place_bun_to_npm_migration "$tool_id"; then
+          migrating_from_bun=1
+          prepare_in_place_bun_to_npm_migration "$tool_id" || rc=1
+        fi
+        if [[ "$rc" -eq 0 ]]; then
+          if [[ -n "$npm_version" ]]; then
+            npm_target_version="$npm_version"
+          elif ! npm_target_version="$(npm_latest_version "$package")"; then
+            echo "$tool_id: npm view could not resolve the latest version of $package" >&2
+            rc=1
+          fi
+        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
+            rc=1
+          elif [[ -n "$npm_installed_ver" && "$npm_installed_ver" == "$npm_target_version" ]]; then
+            echo "already latest: $tool_id (npm:$package@$npm_installed_ver)"
+          elif [[ -n "$npm_allow_scripts" ]]; then
+            run_npm install -g --no-audit --no-fund --allow-scripts="$npm_allow_scripts" "$npm_spec" || rc=1
+            [[ "$rc" -ne 0 || "$migrating_from_bun" -eq 0 ]] || npm_package_owns_executable "$package" "$executable" || rc=1
+          else
+            run_npm install -g --no-audit --no-fund "$npm_spec" || rc=1
+            [[ "$rc" -ne 0 || "$migrating_from_bun" -eq 0 ]] || npm_package_owns_executable "$package" "$executable" || rc=1
+          fi
+        fi
+      fi
+      ;;
+    pip)
+      if [[ "$mode" != apply ]]; then
+        echo "would install or upgrade pip package: $package"
+      elif run_pip show "$package" >/dev/null 2>&1; then
+        run_pip install --user --break-system-packages --upgrade "$package" || rc=1
+      else
+        run_pip install --user --break-system-packages "$package" || rc=1
+      fi
+      [[ "$rc" -eq 0 ]] && { ensure_global_pip_executable "$executable" || rc=1; }
+      ;;
+    release-archive)
+      local version url sha256 archive_executable
+      version="$(jq -r --arg id "$tool_id" '.[$id].version' "$resolved_file")"
+      url="$(jq -r --arg id "$tool_id" '.[$id].url' "$resolved_file")"
+      sha256="$(jq -r --arg id "$tool_id" '.[$id].sha256' "$resolved_file")"
+      archive_executable="$(jq -r --arg id "$tool_id" '.[$id].archive_executable' "$resolved_file")"
+      if [[ "$mode" == apply && -x "$executable" ]] &&
+        "$executable" version 2>/dev/null | head -n 1 | grep -Fq "v$version"; then
+        echo "pinned release already installed: $package $version"
+      else
+        run_release_archive "$package" "$version" "$url" "$sha256" "$archive_executable" "$executable" || rc=1
+      fi
+      ;;
+    release-archive-latest)
+      local repo asset checksums_asset archive_executable latest_tag latest_version
+      repo="$(jq -r --arg id "$tool_id" '.[$id].repo' "$resolved_file")"
+      asset="$(jq -r --arg id "$tool_id" '.[$id].asset' "$resolved_file")"
+      checksums_asset="$(jq -r --arg id "$tool_id" '.[$id].checksums_asset // "SHA256SUMS"' "$resolved_file")"
+      archive_executable="$(jq -r --arg id "$tool_id" '.[$id].archive_executable' "$resolved_file")"
+      if [[ "$mode" != apply ]]; then
+        echo "would install latest release archive: $package ($repo) -> $executable"
+      else
+        latest_tag="$(resolve_latest_release_tag "$repo")" || { rc=1; latest_tag=""; }
+        if [[ "$rc" -eq 0 ]]; then
+          latest_version="${latest_tag#v}"
+          if [[ -x "$executable" ]] && "$executable" --version 2>/dev/null | head -n 1 | grep -Fq " $latest_version "; then
+            echo "latest release already installed: $package $latest_version"
+          else
+            run_release_archive_latest "$package" "$repo" "$asset" "$checksums_asset" "$archive_executable" "$executable" || rc=1
+          fi
+        fi
+      fi
+      ;;
+    *) echo "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; }
+    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; }
+    fi
+  fi
+  return "$rc"
+}
+
+# A retired Bun binary and an npm command can have the same logical tool id
+# and command name. The prior applied manifest is the only authority for this
+# one-time migration; never infer it from an executable that might already be
+# owned by npm.
+is_in_place_bun_to_npm_migration() {
+  local tool_id="$1" previous_manager previous_executable current_manager current_executable current_basename
+  [[ "$have_previous" -eq 1 ]] || return 1
+  previous_manager="$(jq -r --arg id "$tool_id" '.[$id].manager // empty' "$previous_resolved_file")"
+  previous_executable="$(jq -r --arg id "$tool_id" '.[$id].executable // empty' "$previous_resolved_file")"
+  current_manager="$(jq -r --arg id "$tool_id" '.[$id].manager // empty' "$resolved_file")"
+  current_executable="$(jq -r --arg id "$tool_id" '.[$id].executable // empty' "$resolved_file")"
+  current_basename="${current_executable##*/}"
+  [[ "$previous_manager" == bun-compile && "$current_manager" == npm &&
+    "$previous_executable" =~ ^/usr/local/bin/[A-Za-z0-9][A-Za-z0-9._-]*$ &&
+    "${previous_executable##*/}" == "$current_basename" ]]
+}
+
+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
+    return 1
+  }
+  [[ "$executable" =~ ^/usr/local/bin/[A-Za-z0-9][A-Za-z0-9._-]*$ ]] || {
+    echo "refusing unsafe retired Bun binary removal target: $executable" >&2
+    return 1
+  }
+  hash_file="$(bun_source_hash_file "$tool_id")"
+  rm -f -- "$executable" || return 1
+  rm -f -- "$hash_file" || return 1
+  echo "removed retired Bun compilation: $tool_id ($executable and $hash_file)"
+}
+
+# A regular retired binary is removed before npm runs. If sync already installed
+# npm, preserve its verified symlink and remove only the old Bun source marker.
+prepare_in_place_bun_to_npm_migration() {
+  local tool_id="$1" previous_executable migration_path package executable hash_file
+  is_in_place_bun_to_npm_migration "$tool_id" || return 0
+  previous_executable="$(jq -r --arg id "$tool_id" '.[$id].executable' "$previous_resolved_file")"
+  migration_path="$previous_executable"
+  if [[ "${RECONCILE_SOURCE_ONLY:-0}" == 1 && -n "${RECONCILE_TEST_COMMAND_ROOT:-}" ]]; then
+    migration_path="${RECONCILE_TEST_COMMAND_ROOT%/}/${previous_executable##*/}"
+  fi
+  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
+    }
+    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)"
+  else
+    remove_retired_bun_compilation "$tool_id" "$previous_executable"
+  fi
+}
+
+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
+      return 0
+    fi
+  done
+  return 1
+}
+
+# bun-compile builds a standalone binary with `bun build --compile` from a
+# repo-relative TypeScript subproject. It runs in its own pass, strictly
+# after every brew/apt/npm/pip tool above (including bun itself) has been
+# installed and PATH-verified — an alphabetically-earlier tool ID (e.g.
+# "azure-devops-mcp" before "bun") must never race bun's own install, the
+# same ordering guarantee the shim pass already gives real tools below.
+# Same continue-on-failure contract as install_one_tool above: a failed
+# build (e.g. adl) is recorded, not fatal here -- the post-passes
+# that depend on it (kimi-hooks) discover it missing and fail loud there.
+#
+# Idempotency is content-addressed, never a manual version string: the
+# binary is rebuilt unless it exists AND the source tree hash recorded beside
+# it ($state_dir/bun-compile/<tool>.source-hash, written only after a
+# successful build) equals the current bun_source_hash. Plan mode makes the
+# same comparison, so it reports exactly what apply would do.
+build_one_bun_tool() {
+  local tool_id="$1" package executable source_dir entry source_hash hash_file rc=0
+  package="$(jq -r --arg id "$tool_id" '.[$id].package' "$resolved_file")"
+  executable="$(jq -r --arg id "$tool_id" '.[$id].executable' "$resolved_file")"
+  source_dir="$(jq -r --arg id "$tool_id" '.[$id].source' "$resolved_file")"
+  entry="$(jq -r --arg id "$tool_id" '.[$id].entry' "$resolved_file")"
+  echo "ensure bun binary: $tool_id (bun-compile:$package)"
+  source_hash="$(bun_source_hash "$source_dir")" || return 1
+  hash_file="$(bun_source_hash_file "$tool_id")"
+  if [[ -x "$executable" && -f "$hash_file" && "$(cat "$hash_file")" == "$source_hash" ]]; then
+    echo "bun binary already up to date: $package (source $source_hash)"
+    return 0
+  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; }
+  fi
+  if [[ "$mode" == apply && "$rc" -eq 0 ]]; then
+    mkdir -p "${hash_file%/*}"
+    printf '%s\n' "$source_hash" >"$hash_file.new"
+    mv -f "$hash_file.new" "$hash_file"
+    echo "built bun binary: $package (source $source_hash)"
+  fi
+  return "$rc"
+}
+
+build_checkout_adl() {
+  local source_dir="apps/cli" entry="src/main.ts" target="/usr/local/bin/adl" source_hash hash_file rc=0
+  source_hash="$(content_tree_hash "$repo_root/$source_dir")" || return 1
+  hash_file="$(bun_source_hash_file adl)"
+  if [[ -x "$target" && -f "$hash_file" && "$(cat "$hash_file")" == "$source_hash" ]]; then
+    echo "checkout Adl binary already up to date (source $source_hash)"
+    return 0
+  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; }
+    if [[ "$rc" -eq 0 ]]; then
+      mkdir -p "${hash_file%/*}"
+      printf '%s\n' "$source_hash" >"$hash_file.new"
+      mv -f "$hash_file.new" "$hash_file"
+      echo "built checkout Adl binary: $target (source $source_hash)"
+    fi
+  fi
+  return "$rc"
+}
+
+# embedding-model installs the adl-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
+# installer resolve the same HOME. It downloads only when the artifact does
+# not already verify against
+# the manifest's pinned SHA-256 hashes, so a healthy install is a fast no-op.
+# Same continue-on-failure contract as the passes above.
+install_one_embedding_model_tool() {
+  local tool_id="$1" package spec_json rc=0
+  package="$(jq -r --arg id "$tool_id" '.[$id].package' "$resolved_file")"
+  spec_json="$(jq -c --arg id "$tool_id" '.[$id]' "$resolved_file")"
+  echo "ensure embedding model: $tool_id (embedding-model:$package)"
+  run_embedding_model "$package" "$spec_json" || rc=1
+  return "$rc"
+}
+
+# A shim is a thin wrapper at a fixed /usr/local/bin path that execs whatever
+# `package` (its target's real executable name) resolves to on the
+# administrator's PATH right now. It carries no version of its own — it only
+# exists so a short, stable alias (e.g. `crg`) survives however the
+# underlying tool is actually distributed. Same continue-on-failure contract:
+# a shim can legitimately fail if the tool it targets failed to install
+# above, and that should not stop the remaining shims or the post-passes.
+write_one_shim() {
+  local tool_id="$1" package executable target_path content alias_name resolved_alias rc=0
+  package="$(jq -r --arg id "$tool_id" '.[$id].package' "$resolved_file")"
+  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
+    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; }
+  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; }
+  content="#!/bin/sh
+# Generated by global-tools -- do not edit.
+exec '$target_path' \"\$@\"
+"
+  if [[ -f "$executable" ]] && [[ "$(cat "$executable")" == "$content" ]]; then
+    echo "shim already points to $target_path"
+  else
+    printf '%s' "$content" >"$executable"
+    chmod 0755 "$executable"
+    echo "wrote shim: $executable -> $target_path"
+  fi
+  # Writing the file to /usr/local/bin is not the same claim as "an agent can
+  # type the bare alias and it runs" — the same standard of proof every real
+  # tool above is held to, not a weaker one just because this is our own file.
+  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
+    rc=1
+  }
+  return "$rc"
+}
+
+managed_repo_script_marker='# Managed by adl global-tools.'
+# The rename from Enact to adl (2026-09-27) changed this marker line, but
+# left every already-installed /usr/local/bin script carrying the OLD line
+# untouched. Recognising only the current marker made reconcile treat those
+# 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
+# /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.
+managed_repo_script_legacy_marker='# Managed by Enact global-tools.'
+
+is_managed_repo_script() {
+  local executable="$1"
+  [[ -f "$executable" && ! -L "$executable" ]] || return 1
+  grep -Fqx "$managed_repo_script_marker" "$executable" ||
+    grep -Fqx "$managed_repo_script_legacy_marker" "$executable"
+}
+
+atomic_install_managed_repo_script() {
+  local source="$1" executable="$2" temp
+  temp="$(mktemp "$(dirname "$executable")/.$(basename "$executable").tmp.XXXXXX")"
+  if ! install -m 0755 "$source" "$temp"; then
+    rm -f -- "$temp"
+    return 1
+  fi
+  mv -f -- "$temp" "$executable"
+}
+
+# A repo-script is copied into /usr/local/bin rather than linked back to the
+# reconciler checkout. The checkout is forcibly reset by sync-and-reconcile,
+# so a symlink would make every interactive command depend on a mutable tree.
+write_one_repo_script() {
+  local tool_id="$1" package executable source source_path alias_name resolved_alias rc=0
+  package="$(jq -r --arg id "$tool_id" '.[$id].package' "$resolved_file")"
+  executable="$(jq -r --arg id "$tool_id" '.[$id].executable' "$resolved_file")"
+  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
+    return 1
+  }
+  [[ "$source" != /* && "$source" != *..* ]] || {
+    echo "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
+    return 1
+  }
+  if [[ "$mode" != apply ]]; then
+    echo "would install managed repo script: $source_path -> $executable"
+    # 2026-09-28 (backups-this-run summary): preview the one new backup step
+    # below, so a plan run's "would back up" list matches what apply would
+    # really do -- only when there is an existing, DIFFERENT file to replace;
+    # a fresh install backs up nothing, same as apply's own guard below.
+    if [[ -e "$executable" ]] && ! cmp -s "$source_path" "$executable" 2>/dev/null; then
+      echo "would back up managed repo script: $executable"
+    fi
+    return 0
+  fi
+  [[ "$(id -u)" -eq 0 ]] || { echo "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
+      return 1
+    }
+  fi
+  if cmp -s "$source_path" "$executable"; then
+    echo "managed repo script already current: $executable"
+  else
+    # 2026-09-28: this step previously overwrote a managed script in place
+    # with no backup at all (bin/reconcile was the one place among the
+    # backups-this-run audit that both created the overwrite AND was small
+    # enough to fix here directly -- see docs cited in the final report for
+    # every other step that still does not back up).
+    if [[ -e "$executable" ]]; then
+      local repo_script_backup
+      repo_script_backup="${executable}.pre-repo-script-$(date -u +%Y%m%dT%H%M%SZ)"
+      if cp -p "$executable" "$repo_script_backup"; then
+        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
+        return 1
+      fi
+    fi
+    atomic_install_managed_repo_script "$source_path" "$executable" || return 1
+    echo "installed managed repo script: $source_path -> $executable"
+  fi
+  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
+    rc=1
+  }
+  return "$rc"
+}
+
+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
+    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
+    return 1
+  }
+  rm -f -- "$executable"
+}
+
+# The content identity of a repo-dir source: the git tree hash of its source
+# directory at HEAD -- same idea as bun_source_hash above, kept as its own
+# small function only so a failure names "repo-dir", not "bun-compile".
+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
+      return 1
+    }
+  else
+    hash="$(content_tree_hash "$repo_root/$source_dir")"
+  fi
+  printf '%s\n' "$hash"
+}
+
+managed_repo_dir_marker='.adl-managed-repo-dir'
+
+# repo-dir deploys a whole tracked directory VERBATIM (adl-m3-finish item
+# 2/3): unlike a `bun-compile` binary, `adl repo controls` needs real files
+# on disk at a fixed path -- packages/repo-controls' own bundled hook
+# scripts, vendored CI assets, and uv-managed Python compliance engine, none
+# of which a single compiled binary can embed and still have readFileSync()
+# find (their paths are computed from `import.meta.dir`, meaningless once
+# embedded). Most repo-dir sources (repo-controls itself, and its one
+# cross-package runtime import into agent-hooks' log writer) are plain
+# TypeScript with zero external package imports at runtime (grepped
+# 2026-09-27 -- only `node:` and relative imports, one of which crosses into
+# a SIBLING repo-dir package, which is exactly why the deploy preserves each
+# source's position relative to its own `packages/` siblings rather than
+# flattening everything into one path) and so need no install step at all;
+# `npmInstall` below is for the ones that are not.
+#
+# Content-addressed like bun-compile: a marker file inside the deployed
+# directory records the source git-tree hash, so an unchanged source is
+# never re-synced. The sync itself is `git archive HEAD:<source> | tar -x`
+# into a fresh temp directory, then an atomic same-filesystem rename over
+# the previous target -- so a reader never observes a half-written tree, and
+# a failed sync never clobbers a working one.
+#
+# npmInstall (optional, default false): a source that DOES import real npm
+# packages at runtime (unlike repo-controls) needs them materialized after
+# the copy. Deliberately plain `bun install`, never `--frozen-lockfile`: the
+# archived copy is isolated from this monorepo's one workspace-root
+# `bun.lock` (repo-controls and every sibling package share it, none commits
+# its own), so there is no local lockfile here to freeze against -- this
+# resolves fresh from the registry, same "latest-stable, unpinned unless a
+# version is given" contract every plain `npm` manager entry in this
+# manifest already has. Also runs the package's own `build` script when it
+# declares one (see run_repo_dir_sync) -- a source like agent-skills ships
+# no `dist/` in git, so `bun install` alone is not enough to make it run.
+
+# The actual sync action, factored out so tests can stub it -- same shape as
+# run_bun_compile above, and for the same reason: the real action needs root
+# (it writes under /usr/local/libexec) and, when npmInstall is set, the
+# network, neither of which a hash/marker/removal-orchestration test should
+# 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; }
+  if repo_root_is_git; then
+    repo_git archive "HEAD:$source" | tar -x -C "$build_dir"
+  else
+    # az374: no live Git clone -- repo_root IS the release artifact (the
+    # npm-installed package), so the source directory already on disk is the
+    # canonical content. Copy it verbatim instead of asking git for it.
+    cp -R "$repo_root/$source/." "$build_dir/"
+  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; }
+    # 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,
+    # run-validate, run-repo-install, run-repo-doctor), so `bun install`
+    # alone leaves it unable to run ANY subcommand, not just the ones this
+    # deploy happens to exercise. Building is therefore not optional: run
+    # 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; }
+    fi
+  fi
+}
+
+# The synced tree is code, not secrets, and must be readable/executable by
+# every user on the box, not just root -- write_one_repo_dir runs as root
+# (apply mode), and `mktemp -d` always creates its directory 0700 regardless
+# of the invoking shell's (or systemd unit's) umask, confirmed empirically
+# (`umask 022; mktemp -d` still yields drwx------). Left unfixed, the
+# deployed target directory stays root-only forever, and a normal user
+# cannot even `stat` the installed entry point -- exactly the "adl:
+# repo-controls is not installed" failure filed 2026-09-28.
+#
+# True (exit 0) when anything under $dir does not yet have the normalized
+# mode: directories 0755, files 0644, EXCEPT a file that already has any
+# executable bit (the entry script itself, a node_modules/.bin shebang
+# script, ...), which normalizes to 0755 instead of losing its executable
+# bit. Symlinks (e.g. node_modules/.bin) are left alone -- `find -type
+# d`/`-type f` do not match them, and their own permission bits are not what
+# gates access; the file they point at is walked (and normalized)
+# separately. Shared by normalize_repo_dir_permissions (apply) and
+# write_one_repo_dir's plan-mode report below, so the two never disagree on
+# what "needs fixing" means. `-print -quit` stops at the first offender --
+# this only needs a yes/no, not the full list.
+repo_dir_permissions_need_fix() {
+  local dir="$1"
+  [[ -n "$(find "$dir" -type d ! -perm 0755 -print -quit)" ]] && return 0
+  [[ -n "$(find "$dir" -type f \( -perm -0100 -o -perm -0010 -o -perm -0001 \) ! -perm 0755 -print -quit)" ]] && return 0
+  [[ -n "$(find "$dir" -type f ! \( -perm -0100 -o -perm -0010 -o -perm -0001 \) ! -perm 0644 -print -quit)" ]] && return 0
+  return 1
+}
+
+# Actually fixes the modes described above. `! -perm` in every clause means
+# an entry whose mode is already correct is never chmod'd -- cheap to call
+# even on a large, already-current tree, whether that tree is a brand-new
+# mktemp -d build (this fresh-sync path) or a long-installed target that
+# predates this fix (write_one_repo_dir's already-current path, below).
+# Silent when nothing needed fixing; a target that DID need repair -- the
+# 2026-09-28 bug, where agent-hooks/agent-skills stayed 0700 forever because
+# they were already current and this function only ever ran on a fresh sync
+# -- logs one line so a fleet run shows what it repaired.
+normalize_repo_dir_permissions() {
+  local dir="$1"
+  if repo_dir_permissions_need_fix "$dir"; then
+    find "$dir" -type d ! -perm 0755 -exec chmod 0755 {} +
+    find "$dir" -type f \( -perm -0100 -o -perm -0010 -o -perm -0001 \) ! -perm 0755 -exec chmod 0755 {} +
+    find "$dir" -type f ! \( -perm -0100 -o -perm -0010 -o -perm -0001 \) ! -perm 0644 -exec chmod 0644 {} +
+    echo "repo dir permissions normalized: $dir"
+  fi
+}
+
+write_one_repo_dir() {
+  local tool_id="$1" package source target executable rc=0 source_hash marker_file installed_hash source_path build_dir npm_install
+  package="$(jq -r --arg id "$tool_id" '.[$id].package' "$resolved_file")"
+  source="$(jq -r --arg id "$tool_id" '.[$id].source' "$resolved_file")"
+  target="$(jq -r --arg id "$tool_id" '.[$id].target' "$resolved_file")"
+  executable="$(jq -r --arg id "$tool_id" '.[$id].executable' "$resolved_file")"
+  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
+    return 1
+  }
+  [[ "$source" != /* && "$source" != *..* ]] || {
+    echo "unsafe repo-dir source: $source" >&2
+    return 1
+  }
+  source_path="$repo_root/$source"
+  [[ -d "$source_path" ]] || {
+    echo "repo-dir source missing: $source_path" >&2
+    return 1
+  }
+  source_hash="$(repo_dir_source_hash "$source")" || return 1
+  # Whether a (re)sync is needed is read-only (marker file + hash compare,
+  # both already computed without root above) -- decided up front, BEFORE
+  # branching on mode, so plan mode can tell "would sync" apart from
+  # "already current, but permissions need repair" instead of reporting
+  # "would sync" unconditionally regardless of actual target state.
+  marker_file="$target/$managed_repo_dir_marker"
+  installed_hash=""
+  [[ -f "$marker_file" ]] && installed_hash="$(cat "$marker_file")"
+  if [[ "$installed_hash" != "$source_hash" || ! -e "$target/$executable" ]]; then
+    if [[ "$mode" != apply ]]; then
+      echo "would sync repo dir: $source -> $target (source $source_hash)"
+      return 0
+    fi
+    build_dir="$(mktemp -d)"
+    run_repo_dir_sync "$tool_id" "$source" "$build_dir" "$npm_install" || return 1
+    printf '%s\n' "$source_hash" >"$build_dir/$managed_repo_dir_marker"
+    normalize_repo_dir_permissions "$build_dir"
+    mkdir -p "$(dirname "$target")"
+    rm -rf -- "$target.new"
+    mv "$build_dir" "$target.new"
+    rm -rf -- "$target"
+    mv "$target.new" "$target"
+    echo "synced repo dir: $source -> $target ($source_hash)"
+  else
+    echo "repo dir already current: $target ($source_hash)"
+    # 2026-09-28 bug: a target that is already current never went through
+    # run_repo_dir_sync (and its normalize_repo_dir_permissions call) on
+    # THIS run, so a mode wrong from before this fix existed -- 0700 from an
+    # old mktemp -d that was never chmod'd -- stayed wrong forever, no
+    # matter how many times reconcile ran. Every already-current target
+    # must also get checked/repaired here, apply mode fixing it for real,
+    # plan mode only reporting it, exactly like the sync-needed branch
+    # above never touches disk in plan mode either.
+    if [[ "$mode" == apply ]]; then
+      normalize_repo_dir_permissions "$target"
+    elif repo_dir_permissions_need_fix "$target"; then
+      echo "would normalize repo dir permissions: $target"
+    fi
+  fi
+  [[ -e "$target/$executable" ]] || {
+    echo "$tool_id repo dir installed but entry missing: $target/$executable" >&2
+    rc=1
+  }
+  return "$rc"
+}
+
+remove_one_repo_dir() {
+  local target="$1"
+  [[ "$target" == "$repo_dir_libexec_root"/* ]] || {
+    echo "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
+    return 1
+  }
+  rm -rf -- "$target"
+}
+
+# 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
+# run replaces applied-manifest.json with the current manifest. Only the two
+# Azure LFS keys owned by global-tools are removed; unrelated config survives.
+run_legacy_git_config() {
+  local legacy_user="$1" config_file="$2"
+  shift 2
+  (cd /tmp && sudo -u "$legacy_user" -H git config --file "$config_file" "$@" </dev/null)
+}
+
+cleanup_legacy_linux_git_config() {
+  [[ "$platform" == linux && "$have_previous" -eq 1 ]] || return 0
+  local legacy_user legacy_home config_file key rc
+  legacy_user="$(jq -r --arg device "$device" '.linux.devices[$device].brew_user // empty' "$applied_manifest")"
+  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
+    return 1
+  }
+  config_file="$legacy_home/.gitconfig"
+  [[ -f "$config_file" ]] || return 0
+  for key in \
+    'lfs.ssh://ssh.dev.azure.com/.sshtransfer' \
+    'lfs.https://ssh.dev.azure.com/.locksverify'; do
+    rc=0
+    run_legacy_git_config "$legacy_user" "$config_file" --get-all "$key" >/dev/null 2>&1 || rc=$?
+    if [[ "$rc" -eq 1 ]]; then
+      continue
+    fi
+    [[ "$rc" -eq 0 ]] || {
+      echo "failed to inspect legacy global git config: $key in $config_file (exit $rc)" >&2
+      return "$rc"
+    }
+    if [[ "$mode" != apply ]]; then
+      echo "would remove legacy global git config: $key from $config_file"
+    else
+      run_legacy_git_config "$legacy_user" "$config_file" --unset-all "$key" || return 1
+      echo "removed legacy global git config: $key from $config_file"
+    fi
+  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"
+}
+
+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")
+}
+
+# default-agent-file.ts and managed-settings.ts (Claude/Codex) MUST run
+# before install_one_tool's tool loop further down has any chance to install
+# bun itself: test-manifest.sh pins the ordering ("default-agent file mode=plan"
+# prints before the first "ensure latest stable:" tool line) so a human reading
+# a plan top to bottom sees "who this machine is" before "what it installs" --
+# so moving this section after the tool loop is not an option. That means on a
+# host where bun genuinely is not on PATH yet (a fresh Debian 13 container,
+# 2026-09-28, before any tool has ever been installed), this section cannot
+# wait for bun to arrive. Fail loudly and by name instead of a raw
+# "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
+    return 1
+  }
+}
+
+# Agent surface CLIs (Tarun, 2026-09-28): claude, kimi, opencode, cursor's
+# `agent`, and Codex (Homebrew cask on Macs) are declared per device.
+# Native surfaces use the three helpers below; the cask path uses brew_query
+# and run_brew. Tests stub those boundaries so no real sudo, Homebrew, or
+# system path is touched.
+#
+# 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"
+
+# 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
+# /root/codex, a loose binary of unknown install provenance never looked up
+# on PATH) wins when given; otherwise the command name is resolved on the
+# administrator's own PATH, exactly the way it would run interactively.
+# Prints nothing (not a failure) when nothing resolves -- the caller reports
+# "not installed" and moves on, the same non-fatal shape as write_one_shim's
+# own "shim target not yet on PATH" case.
+resolve_surface_executable() {
+  local command_name="$1" executable_override="$2"
+  if [[ -n "$executable_override" ]]; then
+    [[ -x "$executable_override" ]] && printf '%s\n' "$executable_override"
+    return 0
+  fi
+  [[ -n "$command_name" ]] || return 0
+  sudo -u "$administrator" -H env PATH="$surface_cli_search_path" /bin/sh -c 'command -v "$1"' /bin/sh "$command_name" 2>/dev/null
+}
+
+# First line of `<resolved> --version`, as the administrator -- every surface
+# CLI here (claude, codex, kimi, opencode, cursor's agent) supports --version.
+surface_cli_version() {
+  local resolved="$1"
+  sudo -u "$administrator" -H "$resolved" --version 2>/dev/null | head -n 1
+}
+
+# The real update mutation: runs the resolved executable with its declared
+# update_args, as the administrator, on the same extended PATH surfaces are
+# resolved against (an update command may itself shell out to a sibling
+# tool -- opencode's own upgrade path does exactly this for its npm install
+# case, confirmed against the CLI's own documented self-detection).
+run_surface_update() {
+  local resolved="$1"
+  shift
+  sudo -u "$administrator" -H env PATH="$surface_cli_search_path" "$resolved" "$@" </dev/null
+}
+
+# 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
+# reaching that call). A surface not resolved on PATH (or whose declared
+# `executable` is missing/not executable) is reported "not installed" and
+# treated as a non-failure: the same posture kimi-hooks and vscode-settings
+# already take toward a surface that was never set up on this host.
+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" == brew ]]; then
+    if [[ "$mode" != apply ]]; then
+      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; }
+    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
+      return 1
+    fi
+    if awk -v cask="$name" '$1 == cask { found = 1 } END { exit !found }' <<<"$installed_casks"; then
+      cask_action=(upgrade --cask "$name")
+    else
+      cask_action=(install --cask "$name")
+    fi
+    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
+      return 1
+    elif [[ "$update_status" -ne 0 ]]; then
+      echo "surface update failed: $name (exit $update_status)" >&2
+      return 1
+    fi
+    if [[ "${cask_action[0]}" == install ]]; then
+      echo "surface $name: Homebrew cask installed"
+    else
+      echo "surface $name: Homebrew cask upgrade command completed"
+    fi
+    return 0
+  fi
+  if [[ "$mode" != apply ]]; then
+    if [[ "$report_only" == true ]]; then
+      echo "would report surface (no update): $name"
+    else
+      echo "would check and update surface: $name ($command_name ${update_args[*]+"${update_args[*]}"})"
+    fi
+    return 0
+  fi
+  [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
+  local resolved
+  resolved="$(resolve_surface_executable "$command_name" "$executable_override")"
+  if [[ -z "$resolved" ]]; then
+    echo "surface not installed: $name"
+    return 0
+  fi
+  if [[ "$report_only" == true ]]; then
+    local ver
+    ver="$(surface_cli_version "$resolved")"
+    echo "surface $name: report-only, currently ${ver:-unknown}"
+    return 0
+  fi
+  local old_version new_version update_output update_status=0
+  old_version="$(surface_cli_version "$resolved")"
+  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
+    return 1
+  elif [[ "$update_status" -ne 0 ]]; then
+    echo "surface update failed: $name (exit $update_status)" >&2
+    return 1
+  fi
+  new_version="$(surface_cli_version "$resolved")"
+  if [[ "$old_version" == "$new_version" ]]; then
+    echo "surface $name: already latest (${new_version:-unknown})"
+  else
+    echo "surface $name: ${old_version:-unknown} -> ${new_version:-unknown}"
+  fi
+  return 0
+}
+
+# Loops over this device's declared surface_clis (absent or empty -> silently
+# does nothing, same convention as launch_agents/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() {
+  local count
+  count="$(jq -r --arg platform "$platform" --arg device "$device" \
+    '((.[$platform].devices[$device].surface_clis // []) | length)' "$manifest")"
+  [[ "$count" -gt 0 ]] || return 0
+  local i name manager command_name executable_override report_only update_args
+  for ((i = 0; i < count; i++)); do
+    name="$(jq -r --argjson i "$i" --arg platform "$platform" --arg device "$device" \
+      '.[$platform].devices[$device].surface_clis[$i].name' "$manifest")"
+    manager="$(jq -r --argjson i "$i" --arg platform "$platform" --arg device "$device" \
+      '.[$platform].devices[$device].surface_clis[$i].manager // "native"' "$manifest")"
+    command_name="$(jq -r --argjson i "$i" --arg platform "$platform" --arg device "$device" \
+      '.[$platform].devices[$device].surface_clis[$i].command // empty' "$manifest")"
+    executable_override="$(jq -r --argjson i "$i" --arg platform "$platform" --arg device "$device" \
+      '.[$platform].devices[$device].surface_clis[$i].executable // empty' "$manifest")"
+    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 ! 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
+      failed_tools+=("surface-$name")
+    fi
+  done
+}
+
+# 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
+# point) without running any of the real tool loops or post-passes below --
+# lets packages/fleet/tests/test-manifest.sh call install_one_tool,
+# build_one_bun_tool, install_one_embedding_model_tool, write_one_shim,
+# write_one_repo_script, write_one_repo_dir, require_bun_for_identity_files,
+# reconcile_one_surface_cli, run_brew_upgrade_all, and resolve_surface_mode
+# directly against a disposable fixture manifest, with run_brew/run_npm/etc.
+# stubbed out, and with no real root/brew/sudo access required.
+if [[ "${RECONCILE_SOURCE_ONLY:-0}" == "1" ]]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+echo "global-tools: device=$device platform=$platform mode=$mode"
+
+# Scratch reclamation used to run right here, before anything else -- moved
+# 2026-09-28 (see below, after the repo-script loop) because that position
+# broke every host's first-ever apply run. See that comment for why.
+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
+  [[ "$mode" != apply ]] || exit 1
+fi
+
+if [[ "$mode" == apply ]]; then
+  mkdir -p "$state_dir"
+fi
+
+if ! install_surface_policy_file; then
+  echo "global-tools: TOOL INSTALL FAILED: surface-policy-file" >&2
+  failed_tools+=("surface-policy-file")
+fi
+
+require_bun_for_identity_files || exit 1
+
+# The machine's default adl identity (docs/architecture/cli-design.md, "Machine default
+# agent — the one source"): one root-owned file, written before anything
+# 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
+# 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
+  echo "global-tools: default-agent file mode=plan device=$device -> $default_agent"
+  bun "$repo_root/packages/fleet/src/default-agent-file.ts" --agent "$default_agent" --platform "$platform" --mode plan ${reconcile_test_system_root_args[@]+"${reconcile_test_system_root_args[@]}"}
+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
+    failed_tools+=("default-agent-file")
+  fi
+fi
+
+# The managed baseline hook artifacts (adl items 10/17): Claude's
+# managed-settings.json (rendered with this device's env.ADL_AGENT_ID_AGENT)
+# and Codex's requirements.toml + managed_config.toml. See
+# packages/fleet/src/managed-settings.ts for the full contract and why Codex
+# needs two files. Same continue-on-failure contract as the tool passes
+# below: recorded, not fatal, so the remaining passes still run.
+if [[ "$mode" != apply ]]; then
+  echo "global-tools: managed settings mode=plan device=$device -> $default_agent"
+  bun "$repo_root/packages/fleet/src/managed-settings.ts" --agent "$default_agent" --platform "$platform" --mode plan ${reconcile_test_system_root_args[@]+"${reconcile_test_system_root_args[@]}"}
+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
+    failed_tools+=("managed-settings")
+  fi
+fi
+
+if jq -e 'to_entries | any(.value.manager == "brew")' "$resolved_file" >/dev/null; then
+  run_brew update
+  # Tarun, 2026-09-28: `brew update` alone never upgrades anything -- it only
+  # refreshes the formula/cask index. The live m3 run this decision came from
+  # printed "You have 84 outdated formulae and 4 outdated casks installed" for
+  # the FIRST time reconcile had ever surfaced that number, because nothing
+  # downstream of `brew update` ever runs a blanket `brew upgrade`: the
+  # per-tool loop below only upgrades a formula that is BOTH manifest-declared
+  # AND already installed-but-outdated (install_one_tool's own brew branch),
+  # so anything not named in the manifest just accumulates outdated versions
+  # forever. Declared per device (brew_upgrade_all), not implied by having any
+  # brew tools at all, so a device can opt out explicitly instead of by
+  # omission.
+  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
+      failed_tools+=("brew-upgrade-all")
+    fi
+  fi
+fi
+
+if [[ "$platform" == linux && "$(jq -r '.linux.common.os_upgrade // false' "$manifest")" == true ]]; then
+  run_apt update
+  run_apt -y full-upgrade
+fi
+
+while IFS= read -r tool_id; do
+  if ! install_one_tool "$tool_id"; then
+    echo "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")
+
+# An ordinary package failure can be reported after the remaining passes. An
+# in-place Bun-to-npm migration cannot: its old command path was deliberately
+# removed before npm ran, so stop before any hook deployer or state writer can
+# treat the failed transition as usable.
+if [[ "$mode" == apply ]] && failed_in_place_npm_migration; then
+  exit 1
+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
+    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
+    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
+    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
+    failed_tools+=("$tool_id")
+  fi
+done < <(jq -r 'to_entries[] | select(.value.manager == "repo-script") | .key' "$resolved_file")
+
+# Scratch reclamation (Tarun, 2026-09-28: moved from right after "global-tools:
+# device=..." above, before ANYTHING else had run). That original position
+# broke every host's first-ever apply run: scratch-reap's own fetch check
+# needs a working identity to fetch with -- the default-agent file, plus
+# adl-agent-id/agent-vault/adl resolving on PATH (git-ado's own network path,
+# require_agent_identity in bin/git-ado:228-253, fails closed without all
+# three there; git-ado itself is invoked by a path relative to the checkout/
+# installed package, never a PATH lookup, so its own install position does
+# not matter) -- and on a brand-new machine none of those exist yet that
+# early in the run. Confirmed live on strato-vps-1's dry-run plan
+# (.scratchpad/cutover/strato-dryrun.log:52-57, 210): "scratch-reap:
+# default-agent file missing or empty; run reconcile once to install it
+# before fetching", and the whole plan exited non-zero as a result. Running
+# here instead -- after default-agent-file/managed-settings (the identity
+# steps, above) and after adl-agent-id/agent-vault/adl install (the main tool
+# loop above) -- means scratch-reap's fetch authenticates as THIS run's
+# identity, not a nonexistent prior one. bun (a brew-managed tool, installed
+# in the main tool loop above) is also this run's fresh install now, never a
+# stale one.
+#
+# Trade-off accepted with this move: this pass used to run BEFORE the
+# free-space gate near the top of this file, deliberately, so a host that
+# filled up with scratch build artifacts could still reclaim them through
+# THIS run even on a short disk (31 GB reclaimed this way on strato-vps-1,
+# 2026-09-15). Running after the gate instead means a host that is
+# critically low on disk no longer gets that same-run rescue; reconcile is
+# idempotent and safe to retry, so it still recovers on a LATER run once the
+# gate's own failure is investigated, just not within this one. Fixing every
+# host's first-ever run outright is judged the bigger win -- every
+# established host has already passed its first run and keeps behaving
+# exactly as before.
+#
+# Only devices that declare scratch_repos are touched. A developer machine's
+# scratch worktrees are working state; silence there is the correct default.
+if [[ "$(jq -r '.config.scratch_reap.enabled // false' "$manifest")" == true ]]; then
+  scratch_repos=()
+  while IFS= read -r scratch_repo; do
+    if [[ -n "$scratch_repo" ]]; then
+      scratch_repos+=("$scratch_repo")
+    fi
+  done < <(jq -r --arg platform "$platform" --arg device "$device" \
+    '.[$platform].devices[$device].scratch_repos // [] | .[]' "$manifest")
+
+  if [[ "${#scratch_repos[@]}" -eq 0 ]]; then
+    echo "global-tools: scratch reap skipped: $device declares no scratch_repos"
+  elif ! command -v bun >/dev/null 2>&1; then
+    echo "global-tools: scratch reap skipped: bun is not installed yet on this host"
+  else
+    scratch_reap_args=()
+    for scratch_repo in "${scratch_repos[@]}"; do
+      scratch_reap_args+=(--repo "$scratch_repo")
+    done
+    scratch_reap_mode=plan
+    if [[ "$mode" == apply ]]; then
+      scratch_reap_mode=apply
+    fi
+    scratch_reap_idle_days="$(jq -r '.config.scratch_reap.idle_days' "$manifest")"
+    scratch_reap_days="$(jq -r '.config.scratch_reap.reap_days' "$manifest")"
+    if [[ "$(jq -r '.config.scratch_reap.remove_worktrees' "$manifest")" == true ]]; then
+      scratch_reap_args+=(--remove-worktrees)
+    fi
+    # First-time host, plan mode: the default-agent step above (always run
+    # before this one) only WRITES the default-agent file in apply mode --
+    # its own --mode plan never writes. So on a host that has never had a
+    # real reconcile apply yet, the file genuinely does not exist when
+    # scratch-reap's fetch needs it here, and would otherwise refuse the
+    # whole plan over a file THIS SAME run's apply step would go on to
+    # install. Tell scratch-reap that, so it can defer instead of refusing
+    # -- but only when this device actually has a default_agent declared
+    # (i.e. an apply run really would install one); apply mode is untouched
+    # (the file already exists there by the time this step runs).
+    if [[ "$scratch_reap_mode" == plan && -n "$default_agent" && "$default_agent" != null ]]; then
+      scratch_reap_args+=(--default-agent-pending)
+    fi
+    echo "global-tools: scratch reap mode=$scratch_reap_mode repos=${scratch_repos[*]}"
+    # Recorded and continued past, exactly like a failed tool install: the only
+    # way this exits non-zero is a fetch it could not complete, which makes it
+    # 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" \
+      "${scratch_reap_args[@]}" \
+      --mode "$scratch_reap_mode" \
+      --idle-days "$scratch_reap_idle_days" \
+      --reap-days "$scratch_reap_days" || scratch_reap_failed=1
+  fi
+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
+    failed_tools+=("$tool_id")
+  fi
+done < <(jq -r 'to_entries[] | select(.value.manager == "repo-dir") | .key' "$resolved_file")
+
+# Agent surface CLIs (Tarun, 2026-09-28): claude/kimi/opencode/cursor's
+# `agent`, plus Codex as a Homebrew cask on m3/m5, are declared per device in
+# surface_clis and updated in the same run. Runs after every real tool pass
+# above so a surface that shells
+# out to a just-installed tool (or that IS the just-upgraded tool, on a
+# device where brew_upgrade_all also fired) sees this run's state, not a
+# stale one.
+reconcile_surface_clis
+
+if [[ "$have_previous" -eq 1 ]]; then
+  while IFS= read -r tool_id; do
+    [[ -n "$tool_id" ]] || continue
+    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
+      exit 1
+    fi
+    manager="$(jq -r --arg id "$tool_id" '.[$id].manager' "$previous_resolved_file")"
+    package="$(jq -r --arg id "$tool_id" '.[$id].package' "$previous_resolved_file")"
+    executable="$(jq -r --arg id "$tool_id" '.[$id].executable' "$previous_resolved_file")"
+    if is_in_place_bun_to_npm_migration "$tool_id"; then
+      if [[ "$mode" == apply ]]; then
+        echo "retired Bun compilation already removed for npm migration: $tool_id"
+      fi
+      continue
+    fi
+    if jq -e --arg manager "$manager" --arg package "$package" 'to_entries | any(.value.manager == $manager and .value.package == $package)' "$resolved_file" >/dev/null; then
+      echo "retain shared package after entry deletion: $manager:$package"
+      continue
+    fi
+    echo "explicit manifest deletion: uninstall $tool_id ($manager:$package)"
+    case "$manager" in
+      brew) run_brew uninstall "$package" ;;
+      apt) run_apt remove -y "$package" ;;
+      npm) run_npm uninstall -g "$package" ;;
+      pip)
+        run_pip uninstall --break-system-packages -y "$package"
+        remove_global_pip_executable "$executable"
+        ;;
+      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
+        ;;
+      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
+        ;;
+      shim)
+        [[ "$executable" == /usr/local/bin/* ]] || {
+          echo "refusing unsafe shim removal target: $executable" >&2
+          exit 1
+        }
+        if [[ "$mode" == apply ]]; then
+          rm -f -- "$executable"
+        else
+          echo "would remove shim: $executable"
+        fi
+        ;;
+      repo-script)
+        if [[ "$mode" == apply ]]; then
+          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
+            exit 1
+          }
+          echo "would remove managed repo script: $executable"
+        fi
+        ;;
+      repo-dir)
+        removed_repo_dir_target="$(jq -r --arg id "$tool_id" '.[$id].target' "$previous_resolved_file")"
+        if [[ "$mode" == apply ]]; then
+          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
+            exit 1
+          }
+          echo "would remove repo dir: $removed_repo_dir_target"
+        fi
+        ;;
+      bun-compile)
+        [[ "$executable" == /usr/local/bin/* ]] || {
+          echo "refusing unsafe bun binary removal target: $executable" >&2
+          exit 1
+        }
+        if [[ "$mode" == apply ]]; then
+          rm -f -- "$executable"
+        else
+          echo "would remove bun binary: $executable"
+        fi
+        ;;
+      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; }
+          (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)"
+        fi
+        ;;
+      *) echo "unsupported manager in previous manifest: $manager" >&2; exit 1 ;;
+    esac
+  # 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)
+  # -- 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.
+  done < <(jq -r --slurpfile current "$resolved_file" '
+    keys[] as $id
+    | ($current[0][$id]) as $cur
+    | select(($cur == null) or ($cur.manager != .[$id].manager) or ($cur.package != .[$id].package))
+    | $id
+  ' "$previous_resolved_file")
+fi
+
+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
+    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
+      return 1
+    fi
+  done
+  if [[ "$mode" != apply ]]; then
+    if [[ "$source_mode" == checkout ]]; then
+      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}"
+    return 0
+  fi
+  bun_bin="$(command -v bun || true)"
+  [[ -n "$bun_bin" ]] || { echo "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
+      return 1
+    }
+  fi
+  local system_root_args=()
+  if [[ -n "${RECONCILE_TEST_SYSTEM_ROOT:-}" ]]; then
+    system_root_args+=(--system-root "$RECONCILE_TEST_SYSTEM_ROOT")
+  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
+  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
+  failed_tools+=("shell-path-policy")
+fi
+
+if ! reconcile_git_global_config; then
+  echo "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
+  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
+fi
+
+if [[ "$mode" == apply ]]; then
+  "$script_dir/health-check" "$device"
+fi
+
+if [[ "$(jq -r '.config.global_surface_sweep.enabled' "$manifest")" == true ]]; then
+  remove_unprotected="$(jq -r '.config.global_surface_sweep.remove_unprotected' "$manifest")"
+  surface_mode="$(resolve_surface_mode "$mode" "$remove_unprotected")"
+  echo "global-tools: global surface sweep mode=$surface_mode home=$administrator_home (remove_unprotected=$remove_unprotected)"
+  # stdout captured (then re-printed) so this run's combined backups summary
+  # (2026-09-28) can fold in the sweep's OWN already-computed "backups this
+  # run:" lines -- collect_sweep_backups parses them verbatim; it never
+  # 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" \
+    --home "$administrator_home" \
+    --mode "$surface_mode" \
+    --state-dir "$state_dir")" || sweep_status=$?
+  printf '%s\n' "$sweep_output"
+  collect_sweep_backups "$sweep_output"
+  [[ "$sweep_status" -eq 0 ]] || exit "$sweep_status"
+fi
+
+# Agent surfaces and other per-user state belong to the administrator. On the
+# Linux VPS devices that is root; the current manifest carries no second user
+# or home.
+#
+# Kimi hooks, surface policy, VS Code settings, and global agent instructions
+# are the machine-global per-user deployers below. They must land in the
+# administrator's real HOME, so apply runs privilege-dropped as
+# $administrator (`sudo -u -H`). On Linux that user is root already; it is
+# never a secondary account. Plan/audit modes only read and run directly
+# against the manifest-declared $administrator_home. global-surface-sweep just
+# above runs as the reconcile invoker but also targets administrator_home and
+# preserves each rewritten file's owner and mode.
+kimi_hooks_enabled="$(jq -r '.config.kimi_hooks.enabled // false' "$manifest")"
+surface_policy_enabled="$(jq -r '.config.surface_policy.enabled // false' "$manifest")"
+global_agents_enabled="$(jq -r '.config.global_agents.enabled // false' "$manifest")"
+vscode_settings_enabled="$(jq -r '.config.vscode_settings.enabled // false' "$manifest")"
+
+if [[ "$kimi_hooks_enabled" == true ]]; then
+  # Kimi is optional per host: skip loudly instead of creating a
+  # ~/.kimi-code directory (and a config file inside it) on a machine that
+  # never installed Kimi Code.
+  kimi_present=0
+  if command -v kimi >/dev/null 2>&1 || [[ -d "$administrator_home/.kimi-code" ]]; then
+    kimi_present=1
+  fi
+  if [[ "$kimi_present" -eq 0 ]]; 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
+  else
+    # Ordering: adl (bun-compile pass, above) must already resolve as
+    # a bare command before we write TOML entries that reference it -- Kimi
+    # spawns the hook commands verbatim ("adl hook pre-tool-use
+    # --host=kimi", never an absolute path). `adl hook` folds in the old
+    # standalone hook binary into the one `adl` binary (item 15/P4,
+    # 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
+      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
+      exit 1
+    }
+    echo "global-tools: kimi hooks mode=apply home=$administrator_home (as $administrator)"
+    # Never --force: an automated run must not overwrite a hand-edited
+    # managed block. A drifted block makes kimi-hooks exit non-zero with a
+    # clear message, which aborts this reconciliation exactly like a failure
+    # in any apply-mode step above already does -- retryable, not silently
+    # skipped or silently overwritten.
+    #
+    # stdout is captured (then re-printed below) so its own "backed up
+    # previous config to ..." note (2026-09-28: bin/reconcile's own
+    # backups-this-run summary, collect_kimi_hooks_backups) can be collected;
+    # stderr is left unredirected, so a real failure's diagnostic still
+    # 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=$?
+    printf '%s\n' "$kimi_hooks_output"
+    collect_kimi_hooks_backups "$kimi_hooks_output"
+    [[ "$kimi_hooks_status" -eq 0 ]] || exit "$kimi_hooks_status"
+  fi
+fi
+
+# OpenCode now discovers the canonical hook carrier from each managed
+# project's `.opencode/plugins/` directory. Remove the superseded global
+# carrier on every reconciliation; it would otherwise be auto-loaded too and
+# 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
+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"
+  "$script_dir/lean-ctx-observe-strip" --home "$administrator_home" --mode plan
+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"
+fi
+
+# surface-policy re-asserts each host's permission MODE from the single source
+# packages/agent-settings/surface-policy.json, so every machine converges on one
+# declared posture instead of drifting per-host (m5 ran Claude "acceptEdits"
+# against Codex "never"/"danger-full-access" before this existed).
+#
+# Same privilege-drop contract as kimi-hooks above: these are per-user config
+# files in the invoking user's own HOME, never root's.
+#
+# No "is this surface installed" pre-check is needed here, unlike kimi-hooks:
+# surface-policy never CREATES a config file. A surface with no config is
+# reported skipped and left alone, which is what keeps this from re-installing
+# a surface the global sweep spent its whole existence removing.
+#
+# Deliberately not fatal on drift: this writes one or two scalar keys rather
+# than a delimited managed block, so there is no "drifted region" to refuse --
+# a hand-edited mode is simply overwritten by the declared posture, which is
+# the entire point of re-asserting it every cycle.
+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
+  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)
+  fi
+fi
+
+# VS Code keeps distinct settings files for the default profile and every
+# named profile. The deployer patches the two fleet-owned root booleans in all
+# of them without reserialising JSONC, and skips a host whose stable VS Code
+# User directory does not exist. Like every user-surface deployer, it targets
+# the administrator's HOME, never a Linux CI account.
+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
+  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)
+  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
+  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)
+  fi
+fi
+
+# One combined block for every backup this run created (apply) or would
+# create (plan/audit) -- see backups=() and record_backup's own header
+# comment near the top of this file for what feeds it and what does not.
+if [[ "${#backups[@]}" -gt 0 ]]; then
+  if [[ "$mode" == apply ]]; then
+    echo "global-tools: backups this run:"
+  else
+    echo "global-tools: would back up this run:"
+  fi
+  for backup_entry in "${backups[@]}"; do
+    echo "  $backup_entry"
+  done
+else
+  echo "global-tools: no backups this run"
+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
+      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
+      exit 1
+    }
+    applied_commit="npm:$applied_npm_version"
+  fi
+  install -m 0644 "$manifest" "$applied_manifest.new"
+  mv "$applied_manifest.new" "$applied_manifest"
+  printf '%s\n' "$applied_commit" >"$state_dir/applied-commit"
+  printf '%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >"$state_dir/last-success"
+  echo "global-tools: reconciliation complete"
+else
+  echo "global-tools: $mode complete; no state changed"
+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,
+# and health-check all completed (or failed loud on their own terms) before
+# 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
+  exit 1
+fi
+
+if [[ "$scratch_reap_failed" -eq 1 ]]; then
+  echo "global-tools: scratch reap could not verify remotes; worktree removal was refused" >&2
+  exit 1
+fi