@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.12 → 0.1.28

package/bin/reconcile

@@ -110,9 +110,7 @@ failed_tools=()
 # block at the very end, just before "global-tools: reconciliation complete"
 # (Tarun, 2026-09-28). Collected from every step that backs something up
 # before overwriting/removing a file: kimi-hooks (parsed from its own
-# captured "backed up previous config to <path>" note), lean-ctx-observe-strip
-# (2026-09-29, STATUS.md 12p item 13 final scope -- same note shape, parsed
-# by collect_lean_ctx_observe_strip_backups), the global surface sweep
+# captured "backed up previous config to <path>" note), the global surface sweep
 # (parsed from ITS OWN already-printed "global-surface-sweep: backups
 # this run:" block -- never recomputed here, per Tarun's instruction not to
 # duplicate that package's backup logic), and write_one_repo_script below
@@ -157,39 +155,6 @@ collect_kimi_hooks_backups() {
   done <<<"$text"
 }
 
-# Same shape as collect_kimi_hooks_backups, for bin/lean-ctx-observe-strip's
-# own "lean-ctx-observe-strip: backed up previous config to <path>" note --
-# unlike kimi-hooks (always exactly one config file), this step can strip
-# multiple JSON/shell-rc targets in one run, so the loop below (like
-# collect_sweep_backups) records every match, not just the first.
-#
-# A skill-directory backup gets a SECOND, distinct line shape: "backed up
-# previous skill directory <original> to <backup>" (final review finding
-# 1: its backup path is a SIBLING of the scanned skills/ directory, e.g.
-# ".codex/skills.pre-lean-ctx-observe-strip-<ts>/lean-ctx" -- it no longer
-# ends in ".pre-<label>-<timestamp>", so strip_backup_suffix's regex can't
-# recover the original path from it; that note states BOTH paths directly
-# instead, and is matched here as its own case rather than forced through
-# the single-path regex above).
-collect_lean_ctx_observe_strip_backups() {
-  local text="$1" line backup original
-  while IFS= read -r line; do
-    if [[ "$line" =~ ^lean-ctx-observe-strip:\ backed\ up\ previous\ config\ to\ (.+)$ ]]; then
-      backup="${BASH_REMATCH[1]}"
-      record_backup "$(strip_backup_suffix "$backup")" "$backup"
-    elif [[ "$line" =~ ^lean-ctx-observe-strip:\ backed\ up\ previous\ skill\ directory\ (.+)\ to\ (.+)$ ]]; then
-      original="${BASH_REMATCH[1]}"
-      backup="${BASH_REMATCH[2]}"
-      record_backup "$original" "$backup"
-    elif [[ "$line" =~ ^lean-ctx-observe-strip:\ backed\ up\ previous\ hook\ script\ (.+)\ to\ (.+)$ ]]; then
-      # ~/.claude/hooks/lean-ctx-* scripts: same two-path shape as a skill
-      # directory (sibling "hooks.pre-lean-ctx-observe-strip-<ts>/" backup).
-      original="${BASH_REMATCH[1]}"
-      backup="${BASH_REMATCH[2]}"
-      record_backup "$original" "$backup"
-    fi
-  done <<<"$text"
-}
 
 # Folds the global-surface-sweep's OWN already-computed and already-printed
 # backup lines into this run's combined summary, without recomputing
@@ -223,7 +188,9 @@ repo_root="$(cd "$script_dir/.." && pwd)"
 manifest="${manifest:-$repo_root/packages/fleet/manifest.json}"
 # shellcheck source=lib/bun-compile-build.sh
 source "$script_dir/lib/bun-compile-build.sh"
-"$script_dir/validate-manifest" "$manifest" >/dev/null
+# shellcheck source=lib/adl-package.sh
+source "$script_dir/lib/adl-package.sh"
+"$BASH" "$script_dir/validate-manifest" "$manifest" >/dev/null
 if [[ "${RECONCILE_SOURCE_ONLY:-0}" != "1" ]]; then
   if [[ "$source_mode" == npm && -e "$repo_root/.git" ]]; then
     echo "ERROR npm source mode requires an installed package root; use --source checkout for a Git checkout" >&2
@@ -331,9 +298,24 @@ run_brew() {
     return 0
   fi
   [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
+  if [[ -n "${brew_noninteractive_dir:-}" ]]; then
+    # The upgrade step: no sudo Homebrew spawns may prompt (see run_brew_upgrade_all).
+    (cd /tmp && sudo -u "$brew_owner" -H env -u SUDO_ASKPASS NONINTERACTIVE=1 HOMEBREW_NO_SUDO=1 HOMEBREW_NO_ENV_HINTS=1 PATH="$brew_noninteractive_dir:${brew_bin%/*}:/usr/bin:/bin" "$brew_bin" "$@" </dev/null)
+    return
+  fi
   (cd /tmp && sudo -u "$brew_owner" -H env NONINTERACTIVE=1 PATH="${brew_bin%/*}:/usr/bin:/bin" "$brew_bin" "$@" </dev/null)
 }
 
+# A directory holding a `sudo` that can never prompt: it execs /usr/bin/sudo -n. Put first on the
+# PATH of the brew upgrade step, for anything that calls sudo by name.
+make_brew_noninteractive_shim() {
+  local dir
+  dir="$(mktemp -d "${TMPDIR:-/tmp}/adl-brew-sudo-shim.XXXXXX")" || return 1
+  printf '#!/bin/sh\nexec /usr/bin/sudo -n "$@"\n' >"$dir/sudo"
+  chmod 0755 "$dir" "$dir/sudo"
+  printf '%s\n' "$dir"
+}
+
 # Portable command timeout: neither GNU coreutils' `timeout` nor its `gtimeout`
 # alias is installed by default on a fresh mac (this manifest installs
 # neither), so a real `command -v timeout` gate would silently do nothing on
@@ -383,52 +365,126 @@ run_with_timeout() {
 BREW_UPGRADE_ALL_TIMEOUT_SECONDS="${RECONCILE_BREW_UPGRADE_TIMEOUT_SECONDS:-1200}"
 SURFACE_UPDATE_TIMEOUT_SECONDS="${RECONCILE_SURFACE_UPDATE_TIMEOUT_SECONDS:-300}"
 
-# Upgrades every outdated Homebrew formula AND cask in one call -- never a
-# per-package list, so a formula outdated for reasons unrelated to this
-# manifest (installed once by hand, or a transitive dependency of a manifest
-# formula) still converges instead of accumulating outdated versions forever
-# (item 1, 2026-09-28: `brew update` alone, the only brew-wide step that ran
-# before this, never upgrades anything). Gated by the manifest's own
-# brew_upgrade_all switch at the call site below, not inside this function --
-# this function always does the real (or plan-mode preview) work when called.
+# brew's output for a cask whose upgrade needed sudo but was not allowed to ask: Homebrew refusing
+# ("sudo is disabled by HOMEBREW_NO_SUDO."), or sudo -n failing fast. It never blocks.
+brew_output_needs_password() {
+  grep -Eiq 'sudo is disabled by HOMEBREW_NO_SUDO|sudo: .*(password|terminal|tty|askpass)|^Password:' <<<"$1"
+}
+
+# Upgrades the outdated Homebrew formulae and casks, from ONE `brew outdated --json=v2` (the
+# formulae and casks, with installed and available versions). A formula outdated for reasons
+# unrelated to this manifest (installed once by hand, or a transitive dependency of a manifest
+# formula) still converges instead of accumulating outdated versions forever (item 1,
+# 2026-09-28: `brew update` alone, the only brew-wide step that ran before this, never upgrades
+# anything). Gated by the manifest's own brew_upgrade_all switch at the call site below, not
+# inside this function -- this function always does the real (or plan-mode preview) work when
+# called.
+#
+# Two rules from the live tests (Tarun, 2026-10-01):
+#  - config.brew_upgrade_exclude names packages that are never upgraded here (git: every Homebrew
+#    git upgrade installs an ad-hoc-signed binary at a new Cellar path and re-prompts the
+#    osxkeychain ACL). Not a `brew pin`, not a version pin: an outdated excluded package is one
+#    info line, and the rest is upgraded BY NAME.
+#  - a reconcile NEVER prompts, terminal or not (m5, 2026-10-01: an interactive `sudo adl setup`
+#    got a nested, echoing `Password:` from the visual-studio-code cask's sudo inside brew inside
+#    our sudo -u). Every brew call here runs with stdin /dev/null, SUDO_ASKPASS unset,
+#    HOMEBREW_NO_SUDO=1 (brew refuses before spawning sudo) and a PATH-shimmed `sudo -n`. Casks are
+#    upgraded one at a time; one that needs a password is reported as a WARN with the command to
+#    run by hand and is not a failed tool. A failing formula, or a cask that fails for any other
+#    reason, still fails loud.
 run_brew_upgrade_all() {
+  if [[ "$mode" != apply ]]; then
+    run_brew_upgrade_all_body
+    return
+  fi
+  local status=0
+  brew_noninteractive_dir="$(make_brew_noninteractive_shim)" || { echo "ERROR could not create the brew sudo shim" >&2; return 1; }
+  run_brew_upgrade_all_body || status=$?
+  command rm -rf -- "$brew_noninteractive_dir"
+  brew_noninteractive_dir=""
+  return "$status"
+}
+
+run_brew_upgrade_all_body() {
   if [[ "$mode" != apply ]]; then
     echo "would run: brew upgrade (all outdated formulae and casks)"
+    local planned_excludes
+    planned_excludes="$(jq -r '(.config.brew_upgrade_exclude // []) | join(", ")' "$manifest")"
+    if [[ -n "$planned_excludes" ]]; then
+      echo "brew upgrade excludes (config.brew_upgrade_exclude): $planned_excludes"
+    fi
     return 0
   fi
   [[ "$(id -u)" -eq 0 ]] || { echo "ERROR 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 "ERROR brew outdated --formula check failed" >&2
+  local outdated_json excluded_names line kind name installed available
+  local -a formulae=() casks=()
+  local skipped=0
+  outdated_json="$(brew_query outdated --json=v2)" || {
+    echo "ERROR brew outdated check failed" >&2
     return 1
   }
-  outdated_casks="$(brew_query outdated --cask --quiet)" || {
-    echo "ERROR brew outdated --cask check failed" >&2
+  jq -e '(.formulae | type == "array") and (.casks | type == "array")' >/dev/null 2>&1 <<<"$outdated_json" || {
+    echo "ERROR brew outdated --json=v2 did not print formulae and casks" >&2
     return 1
   }
-  formulae_count=0
-  [[ -z "$outdated_formulae" ]] || formulae_count="$(wc -l <<<"$outdated_formulae" | tr -d ' ')"
-  casks_count=0
-  [[ -z "$outdated_casks" ]] || casks_count="$(wc -l <<<"$outdated_casks" | tr -d ' ')"
+  excluded_names="$(jq -r '(.config.brew_upgrade_exclude // [])[]' "$manifest")"
+  while IFS=$'\t' read -r kind name installed available; do
+    [[ -n "$name" ]] || continue
+    if [[ -n "$excluded_names" ]] && grep -Fxq -- "$name" <<<"$excluded_names"; then
+      echo "global-tools: brew upgrade skips excluded: $name ($installed → $available)"
+      skipped=$((skipped + 1))
+      continue
+    fi
+    if [[ "$kind" == formula ]]; then formulae+=("$name"); else casks+=("$name"); fi
+  done < <(jq -r '
+    def versions: if type == "array" then join(", ") else tostring end;
+    (.formulae[]? | ["formula", .name, (.installed_versions | versions), .current_version]),
+    (.casks[]? | ["cask", .name, (.installed_versions | versions), .current_version]) | @tsv
+  ' <<<"$outdated_json")
+  local formulae_count="${#formulae[@]}" casks_count="${#casks[@]}"
   if [[ "$formulae_count" -eq 0 && "$casks_count" -eq 0 ]]; then
-    echo "brew upgrade: nothing outdated"
+    if [[ "$skipped" -gt 0 ]]; then
+      echo "brew upgrade: nothing left to upgrade after $skipped excluded"
+    else
+      echo "brew upgrade: nothing outdated"
+    fi
     return 0
   fi
-  local upgrade_status=0
   # Routed through run_brew itself (same owner/cwd/stdin wiring as every
   # other brew mutation in this file), bounded by run_with_timeout so a
   # network-stalled `brew upgrade` cannot hang the rest of this run forever.
   # brew's output streams live -- never captured and printed at the end,
   # which left a long upgrade silent for minutes and looking stuck.
   echo "brew upgrade: $formulae_count formulae, $casks_count casks outdated; upgrading (timeout ${BREW_UPGRADE_ALL_TIMEOUT_SECONDS}s)"
-  run_with_timeout "$BREW_UPGRADE_ALL_TIMEOUT_SECONDS" run_brew upgrade 2>&1 || upgrade_status=$?
-  if [[ "$upgrade_status" -eq 124 ]]; then
-    echo "ERROR brew upgrade timed out after ${BREW_UPGRADE_ALL_TIMEOUT_SECONDS}s" >&2
-    return 1
-  elif [[ "$upgrade_status" -ne 0 ]]; then
-    echo "ERROR brew upgrade failed (exit $upgrade_status)" >&2
-    return 1
+  local upgrade_status=0
+  local failed=0 cask cask_output
+  if [[ "$formulae_count" -gt 0 ]]; then
+    run_with_timeout "$BREW_UPGRADE_ALL_TIMEOUT_SECONDS" run_brew upgrade --formula "${formulae[@]}" 2>&1 || upgrade_status=$?
+    if [[ "$upgrade_status" -eq 124 ]]; then
+      echo "ERROR brew upgrade timed out after ${BREW_UPGRADE_ALL_TIMEOUT_SECONDS}s" >&2
+      return 1
+    elif [[ "$upgrade_status" -ne 0 ]]; then
+      echo "ERROR brew upgrade failed (exit $upgrade_status)" >&2
+      failed=1
+    fi
   fi
+  for cask in ${casks[@]+"${casks[@]}"}; do
+    upgrade_status=0
+    cask_output="$(run_with_timeout "$BREW_UPGRADE_ALL_TIMEOUT_SECONDS" run_brew upgrade --cask "$cask" 2>&1)" || upgrade_status=$?
+    [[ -z "$cask_output" ]] || printf '%s\n' "$cask_output"
+    if [[ "$upgrade_status" -eq 124 ]]; then
+      echo "ERROR brew upgrade timed out after ${BREW_UPGRADE_ALL_TIMEOUT_SECONDS}s ($cask)" >&2
+      return 1
+    elif [[ "$upgrade_status" -ne 0 ]]; then
+      if brew_output_needs_password "$cask_output"; then
+        echo "WARN brew: $cask needs an interactive password to upgrade; run: brew upgrade --cask $cask" >&2
+      else
+        echo "ERROR brew upgrade failed (exit $upgrade_status): $cask" >&2
+        failed=1
+      fi
+    fi
+  done
+  [[ "$failed" -eq 0 ]] || return 1
   echo "brew upgrade: $formulae_count formulae, $casks_count casks were outdated before upgrade"
   return 0
 }
@@ -582,6 +638,22 @@ npm_package_owns_executable() {
   }
 }
 
+# The published package is installed with bun (Tarun, 2026-10-01). Package mode
+# proves the administrator's `adl` IS this package (bin/lib/adl-package.sh, the
+# check bin/setup runs too): a different adl earlier on the administrator's PATH
+# -- a legacy compiled /usr/local/bin/adl from before the package existed -- would
+# keep running instead of the package this job updates, so it fails loud here with
+# the one-line fix instead of being silently tolerated.
+adl_package_owns_executable() {
+  local os package_real
+  case "$platform" in
+    mac) os=Darwin ;;
+    *) os=Linux ;;
+  esac
+  package_real="$(cd -P -- "$repo_root" && pwd -P)" || return 1
+  adl_check_adl_not_shadowed "$administrator" "$os" "$administrator_home" "$package_real" "global-tools"
+}
+
 run_pip() {
   if [[ "$mode" != apply ]]; then
     printf 'would run pip as %s: python3 -m pip' "$administrator"
@@ -752,7 +824,7 @@ run_embedding_model() {
   local package="$1"
   local spec_json="$2"
   if [[ "$mode" != apply ]]; then
-    printf 'would install embedding model: %s as %s -> ~/.cache/adl-embedding/model\n' "$package" "$administrator"
+    printf 'would install embedding model: %s as %s -> ~/.cache/enact-embedding/model\n' "$package" "$administrator"
     return 0
   fi
   [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
@@ -763,9 +835,8 @@ run_embedding_model() {
 
 # Installs $src as $dest via a same-directory temp-file + rename, never a
 # direct in-place write -- so a concurrent reader (including the next agent
-# shell's `command -v $dest`, per the lean-ctx incident this fixed: an
-# in-place npm postinstall rewrite left the shim executing but printing
-# "binary not found" for ~44s on every scheduled reconcile) can never observe
+# shell's `command -v $dest`, which could otherwise observe an executable
+# partway through an in-place rewrite) can never observe
 # $dest existing but only partially written. `mv` within the same directory
 # is a single rename(2) on both Darwin and Linux -- atomic by construction,
 # not by scheduling luck.
@@ -796,8 +867,8 @@ install_surface_policy_file() {
 
 # A resolved release version against the first line of a release-archive-
 # latest tool's own `--version` output. Different tools format that line
-# differently -- lean-ctx: "lean-ctx 3.10.5 (official, ...)" (version padded
-# by spaces on both sides); agent-vault: "agent-vault version 0.39.3" (flush
+# differently -- some include parenthetical metadata; agent-vault prints
+# "agent-vault version 0.39.3" (flush
 # against the end of the line, no trailing space); a plain "vX.Y.Z" line
 # with no separating space before the version at all -- so the LEFT boundary
 # is a string start or a real space, with an OPTIONAL literal "v" directly
@@ -927,7 +998,7 @@ resolve_surface_mode() {
 # root") is a real environment fault, not a flaky install, and still
 # aborts immediately -- `exit` is unconditional and is never caught here.
 install_one_tool() {
-  local tool_id="$1" manager package executable previous_executable migrating_from_bun=0 rc=0 npm_spec npm_allow_scripts npm_target_version npm_installed_ver brew_outdated_output brew_installed_version
+  local tool_id="$1" manager package executable previous_executable migrating_from_bun=0 rc=0 npm_spec npm_allow_scripts npm_target_version npm_installed_ver brew_outdated_output brew_installed_version trust_kind
   manager="$(jq -r --arg id "$tool_id" '.[$id].manager' "$resolved_file")"
   package="$(jq -r --arg id "$tool_id" '.[$id].package' "$resolved_file")"
   executable="$(jq -r --arg id "$tool_id" '.[$id].executable' "$resolved_file")"
@@ -941,19 +1012,76 @@ install_one_tool() {
   fi
   if [[ "$tool_id" == adl && "$source_mode" == npm ]]; then
     if [[ "$mode" != apply ]]; then
-      echo "would use installed npm package payload: $repo_root"
+      echo "would use installed package payload: $repo_root"
       return 0
     fi
     if is_in_place_bun_to_npm_migration "$tool_id"; then
       prepare_in_place_bun_to_npm_migration "$tool_id" || return 1
     fi
-    npm_package_owns_executable "$package" "$executable" || return 1
-    echo "using installed npm package payload: $repo_root"
+    adl_package_owns_executable || return 1
+    echo "using installed package payload: $repo_root"
     return 0
   fi
   echo "ensure latest stable: $tool_id ($manager:$package)"
   case "$manager" in
     brew)
+      # Optional declared tap (manifest .tap, owner/repo): fully-qualified
+      # package names (e.g. stablyai/orca/orca) refuse to resolve until their
+      # tap exists, and Homebrew will not auto-tap a non-core tap for a
+      # noninteractive caller — so reconcile taps it first, idempotently.
+      # Tarun 2026-10-02: orca is brew-managed from Stably's own tap; that
+      # cask is auto_updates, so the per-tool path installs-if-missing and
+      # the in-app updater owns versioning — no version is ever pinned here.
+      tap="$(jq -r --arg id "$tool_id" '.[$id].tap // ""' "$resolved_file")"
+      if [[ "$rc" -eq 0 && -n "$tap" ]]; then
+        [[ "$tap" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || {
+          echo "ERROR refusing unsafe brew tap name for $tool_id: $tap" >&2
+          rc=1
+        }
+      fi
+      if [[ "$rc" -eq 0 && -n "$tap" && "$mode" == apply ]]; then
+        brew_query tap | grep -Fqx "$tap" || run_brew tap "$tap" || {
+          echo "ERROR $tool_id: brew tap $tap failed" >&2
+          rc=1
+        }
+      fi
+      # Homebrew >=6 tap trust (brew 7.0.7 on this fleet; the 2026-10 orca
+      # install failure was exactly this refusal): a command that must load an
+      # untrusted non-core tap FAILS until trust is granted, noninteractively
+      # or not. Grant ITEM-level trust for the declared package only --
+      # brew's own automation guidance is `brew trust --formula|--cask
+      # owner/repo/item`, never the whole tap. Gated on the same declared
+      # .tap as the tap step above: that manifest field is the reviewed trust
+      # boundary, and a bare core package (curl, ripgrep) needs no grant.
+      if [[ "$rc" -eq 0 && -n "$tap" && "$mode" == apply ]]; then
+        # The kind is resolved, never guessed: a fully-qualified name is
+        # loadable exactly as one of formula/cask once its tap exists.
+        if brew_query info --formula "$package" >/dev/null 2>&1; then
+          trust_kind=formula
+        elif brew_query info --cask "$package" >/dev/null 2>&1; then
+          trust_kind=cask
+        else
+          echo "ERROR $tool_id: cannot determine whether $package is a formula or a cask — refusing to guess its trust kind" >&2
+          rc=1
+        fi
+        # `brew trust` (list) prints each granted item on its own line,
+        # indented under a "Trusted formulae:"/"Trusted casks:" header
+        # (verified on brew 7.0.7) -- trim, then exact-line match so a
+        # whole-tap grant ("Trusted taps: owner/repo") can never satisfy the
+        # item check.
+        if [[ "$rc" -eq 0 ]]; then
+          brew_query trust | awk '{$1=$1};1' | grep -Fqx "$package" || run_brew trust "--$trust_kind" "$package" || {
+            echo "ERROR $tool_id: brew trust --$trust_kind $package failed" >&2
+            rc=1
+          }
+        fi
+      elif [[ "$rc" -eq 0 && -n "$tap" ]]; then
+        # Plan mode: brew_query is apply-only (see its own header comment),
+        # so the kind is not resolved for a preview -- name the grant anyway.
+        echo "would trust Homebrew item: $package (formula|cask)"
+      fi
+      if [[ "$rc" -ne 0 ]]; then
+        :
       # Plan mode's message is intentionally unconditional (see brew_query's
       # own comment for why: a real up-to-date check is slow enough on a
       # loaded box to defeat the point of a quick preview). Apply mode pays
@@ -961,7 +1089,7 @@ install_one_tool() {
       # run `brew upgrade` on an already-current formula -- which brew itself
       # accepts silently (prints "Warning: <pkg> <ver> already installed" and
       # exits 0), the exact per-run noise this replaces.
-      if [[ "$mode" != apply ]]; then
+      elif [[ "$mode" != apply ]]; then
         echo "would install or upgrade Homebrew formula: $package"
       elif brew_query list --formula "$package" >/dev/null 2>&1; then
         if brew_outdated_output="$(brew_query outdated --formula --quiet "$package")"; then
@@ -1054,10 +1182,8 @@ install_one_tool() {
         latest_tag="$(resolve_latest_release_tag "$repo")" || { rc=1; latest_tag=""; }
         if [[ "$rc" -eq 0 ]]; then
           latest_version="${latest_tag#v}"
-          # A release whose asset filename bakes in the version (agent-vault:
-          # agent-vault_<ver>_darwin_arm64.tar.gz) declares "{version}" in
-          # .asset/.checksums_asset; lean-ctx's own asset names carry no
-          # version at all, so this is a no-op substring replace for it.
+          # A release whose asset filename bakes in the version declares
+          # "{version}" in .asset/.checksums_asset; otherwise this is a no-op.
           resolved_asset="${asset//\{version\}/$latest_version}"
           resolved_checksums_asset="${checksums_asset//\{version\}/$latest_version}"
           if [[ -x "$executable" ]] &&
@@ -1129,10 +1255,17 @@ prepare_in_place_bun_to_npm_migration() {
   if [[ -L "$migration_path" ]]; then
     package="$(jq -r --arg id "$tool_id" '.[$id].package' "$resolved_file")"
     executable="$(jq -r --arg id "$tool_id" '.[$id].executable' "$resolved_file")"
-    npm_package_owns_executable "$package" "$executable" || {
-      echo "ERROR refusing to remove an executable symlink not owned by npm: $previous_executable" >&2
-      return 1
-    }
+    if [[ "$tool_id" == adl && "$source_mode" == npm ]]; then
+      adl_package_owns_executable || {
+        echo "ERROR refusing to remove an executable symlink not owned by the installed package: $previous_executable" >&2
+        return 1
+      }
+    else
+      npm_package_owns_executable "$package" "$executable" || {
+        echo "ERROR refusing to remove an executable symlink not owned by npm: $previous_executable" >&2
+        return 1
+      }
+    fi
     hash_file="$(bun_source_hash_file "$tool_id")"
     rm -f -- "$hash_file" || return 1
     echo "retained npm-owned executable and removed retired Bun marker: $previous_executable ($hash_file)"
@@ -1214,7 +1347,7 @@ build_checkout_adl() {
   return "$rc"
 }
 
-# embedding-model installs the adl-embedding static (Model2Vec) artifact
+# embedding-model installs the enact-embedding static (Model2Vec) artifact
 # that adl hook's (the folded-in hook engine's) skill-match hook loads
 # from the administrator's cache.
 # It runs as the declared administrator (root on Linux) so the hook and
@@ -1284,7 +1417,7 @@ managed_repo_script_marker='# Managed by adl global-tools.'
 # real, previously-self-installed files as "unmanaged", so apply mode refused
 # to update them ("refusing to replace unmanaged or symlinked managed script
 # target") instead of replacing them with the renamed source -- seen live on
-# M3's `fleet-cutover.sh --apply` for /usr/local/bin/git and
+# M3's `packages/fleet/scripts/fleet-cutover.sh --apply` for /usr/local/bin/git and
 # /usr/local/bin/git-ado. A target carrying EITHER line is this writer's own
 # prior output and must still be treated as managed; a target carrying
 # neither (or a symlink) must keep being refused.
@@ -1325,8 +1458,10 @@ write_one_repo_script() {
     return 1
   }
   source_path="$repo_root/$source"
-  [[ -f "$source_path" && ! -L "$source_path" && -x "$source_path" ]] || {
-    echo "ERROR managed script source must be an executable regular non-symlink file: $source_path" >&2
+  # -f, not -x: bun leaves every shipped file but the `bin` targets 0644, and the
+  # copy below is installed 0755.
+  [[ -f "$source_path" && ! -L "$source_path" ]] || {
+    echo "ERROR managed script source must be a regular non-symlink file: $source_path" >&2
     return 1
   }
   if [[ "$mode" != apply ]]; then
@@ -1681,6 +1816,27 @@ executable_claimed_by_current_manifest() {
 # into its own function, like install_one_tool, so
 # packages/fleet/tests/test-manifest.sh can exercise it directly through the
 # RECONCILE_SOURCE_ONLY seam instead of only through a real apply run.
+remove_release_archive_executable() {
+  local executable="$1" label="$2" target="$executable"
+  [[ "$executable" =~ ^/usr/local/bin/[A-Za-z0-9][A-Za-z0-9._-]*$ ]] || {
+    echo "ERROR refusing unsafe release archive removal target: $executable" >&2
+    return 1
+  }
+  if [[ "${RECONCILE_SOURCE_ONLY:-0}" == 1 && -n "${RECONCILE_TEST_COMMAND_ROOT:-}" ]]; then
+    target="${RECONCILE_TEST_COMMAND_ROOT%/}/${executable##*/}"
+  fi
+  if [[ "$mode" == apply ]]; then
+    rm -f -- "$target" || return 1
+    [[ ! -e "$target" && ! -L "$target" ]] || {
+      echo "ERROR release archive executable remains after removal: $target" >&2
+      return 1
+    }
+    echo "removed $label release executable: $executable"
+  else
+    echo "would remove $label release executable: $executable"
+  fi
+}
+
 remove_one_manifest_entry() {
   local tool_id="$1" manager package executable removed_repo_dir_target
   if jq -e --arg id "$tool_id" '.config.protected_tools | index($id)' "$manifest" >/dev/null; then
@@ -1735,26 +1891,10 @@ remove_one_manifest_entry() {
     # still cleanly uninstall it the next time it reconciles; previous
     # state is read straight from disk, never re-validated.
     release-archive)
-      [[ "$executable" == /usr/local/bin/* ]] || {
-        echo "ERROR refusing unsafe release archive removal target: $executable" >&2
-        exit 1
-      }
-      if [[ "$mode" == apply ]]; then
-        rm -f -- "$executable"
-      else
-        echo "would remove pinned release executable: $executable"
-      fi
+      remove_release_archive_executable "$executable" pinned
       ;;
     release-archive-latest)
-      [[ "$executable" == /usr/local/bin/* ]] || {
-        echo "ERROR refusing unsafe release archive removal target: $executable" >&2
-        exit 1
-      }
-      if [[ "$mode" == apply ]]; then
-        rm -f -- "$executable"
-      else
-        echo "would remove latest release executable: $executable"
-      fi
+      remove_release_archive_executable "$executable" latest
       ;;
     shim)
       [[ "$executable" == /usr/local/bin/* ]] || {
@@ -1808,29 +1948,13 @@ remove_one_manifest_entry() {
         (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
           bun "$repo_root/packages/fleet/src/install-embedding-model.ts" uninstall </dev/null)
       else
-        echo "would remove embedding model cache: ~/.cache/adl-embedding/model (as $administrator)"
+        echo "would remove embedding model cache: ~/.cache/enact-embedding/model (as $administrator)"
       fi
       ;;
     *) echo "ERROR unsupported manager in previous manifest: $manager" >&2; exit 1 ;;
   esac
 }
 
-# config.git_global_config: global git config for the administrator (the
-# account whose HOME the per-user deployers below also write to). Apply runs git as
-# that user (sudo -u -H) so ~/.gitconfig stays user-owned; plan/audit only
-# read, as whoever invoked reconcile. Motivating entries: Azure DevOps SSH
-# has no Git LFS support, and git-lfs's default pure-SSH `git-lfs-transfer`
-# probe hangs forever against ssh.dev.azure.com, stalling every `git push` in
-# the LFS pre-push hook.
-run_git_config_global() {
-  if [[ "$mode" == apply ]]; then
-    [[ "$(id -u)" -eq 0 ]] || { echo "ERROR 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
@@ -1875,49 +1999,18 @@ cleanup_legacy_linux_git_config() {
   done
 }
 
-# Prints the current global value of $1, or nothing when unset. git config
-# --get exits 1 for a missing key; any other failure is real and propagates.
-git_global_config_value() {
-  local key="$1" value rc=0
-  value="$(run_git_config_global --get "$key")" || rc=$?
-  if [[ "$rc" -eq 1 ]]; then
-    return 0
-  fi
-  [[ "$rc" -eq 0 ]] || { echo "ERROR git config --global --get $key failed (exit $rc)" >&2; return "$rc"; }
-  printf '%s\n' "$value"
-}
-
+# config.git_global_config + <platform>.common.git_global_config + the device's
+# git_user: the administrator's global git config, identical on every host
+# (Tarun, 2026-10-01). All logic lives in bin/git-defaults; undeclared keys are
+# never touched. Motivating entries: Azure DevOps SSH has no Git LFS support
+# (git-lfs's pure-SSH probe hangs against ssh.dev.azure.com), and GCM is the
+# credential helper on every host.
 reconcile_git_global_config() {
-  local key value current
-  while IFS=$'\t' read -r key value; do
-    [[ -n "$key" ]] || continue
-    current="$(git_global_config_value "$key")" || return 1
-    if [[ "$current" == "$value" ]]; then
-      echo "global git config already set: $key=$value"
-    elif [[ "$mode" != apply ]]; then
-      echo "would set global git config: $key=$value"
-    else
-      run_git_config_global "$key" "$value" || return 1
-      echo "set global git config: $key=$value"
-    fi
-  done < <(jq -r '.config.git_global_config | to_entries[] | [.key, .value] | @tsv' "$manifest")
-
-  [[ "$have_previous" -eq 1 ]] || return 0
-  while IFS= read -r key; do
-    [[ -n "$key" ]] || continue
-    current="$(git_global_config_value "$key")" || return 1
-    [[ -n "$current" ]] || continue
-    if [[ "$mode" != apply ]]; then
-      echo "would unset global git config (explicit manifest deletion): $key"
-    else
-      run_git_config_global --unset-all "$key" || return 1
-      echo "explicit manifest deletion: unset global git config $key"
-    fi
-  done < <(jq -r --slurpfile current "$manifest" '
-    (.config.git_global_config // {}) | keys[] as $key
-    | select(($current[0].config.git_global_config | has($key)) | not)
-    | $key
-  ' "$applied_manifest")
+  if [[ "$mode" == apply ]]; then
+    [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
+  fi
+  "$BASH" "$repo_root/bin/git-defaults" --manifest "$manifest" --platform "$platform" \
+    --device "$device" --mode "$mode" --administrator "$git_config_user"
 }
 
 # default-agent-file.ts and managed-settings.ts (Claude/Codex) MUST run
@@ -1946,9 +2039,11 @@ require_bun_for_identity_files() {
 # The PATH searched for a surface command intentionally extends past the
 # usual brew/system directories into the per-user install locations these
 # specific CLIs' own installers use (claude's and cursor's native installers,
-# kimi's and opencode's curl-script installers) -- none of those are on the
-# plain system PATH this file uses elsewhere for brew/npm/pip.
-surface_cli_search_path="$administrator_home/.local/bin:$administrator_home/.kimi-code/bin:$administrator_home/.opencode/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/local/bin:/usr/bin:/bin"
+# kimi's curl-script installer) -- none of those are on the plain system PATH
+# this file uses elsewhere for brew/npm/pip. opencode is the exception (Tarun,
+# 2026-10-01): it comes from the npm registry through bun, so bun's global bin
+# directory is searched instead of the retired native ~/.opencode/bin.
+surface_cli_search_path="$administrator_home/.local/bin:$administrator_home/.kimi-code/bin:$administrator_home/.bun/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/local/bin:/usr/bin:/bin"
 
 # Resolves a surface to the real executable that will be run: an explicit
 # manifest `executable` (a fixed, known path -- e.g. hostinger's report-only
@@ -2017,6 +2112,173 @@ surface_update_error_reason() {
   fi
 }
 
+# bun-managed surface (Tarun, 2026-10-01, "we are not on GitHub"): opencode is installed and updated
+# from the npm registry package `opencode-ai` with `bun add -g opencode-ai@latest`, run as the
+# administrator -- never `opencode upgrade`, which asks the unauthenticated GitHub REST API for its
+# latest release and 403s under the fleet's shared-IP rate limit. Named so tests can stub the one
+# boundary that touches the machine; adl_bun_add_global (bin/lib/adl-package.sh) is the same call
+# the adl package install uses (the administrator's own ~/.bun, bun found through Homebrew).
+run_surface_bun_add() {
+  local spec="$1" os
+  case "$platform" in
+    mac) os=Darwin ;;
+    linux) os=Linux ;;
+    *) echo "ERROR unsupported platform for a bun surface: $platform" >&2; return 1 ;;
+  esac
+  adl_bun_add_global "$administrator" "$os" "$administrator_home" "$spec" </dev/null
+}
+
+# Finds every OTHER copy of a bun-managed surface command: each directory on the surface search
+# path plus the native installer's ~/.opencode/bin. Prints one TAB-separated record per distinct
+# copy, `kind<TAB>path<TAB>detail`, where kind is
+#   native       <home>/.opencode/bin/<command> (a regular executable the native installer wrote;
+#                path is the bin DIRECTORY that is moved aside)
+#   brew         a symlink into <this host's Homebrew prefix>/Cellar/<command>/<version>/bin/<command>
+#   npm          a symlink into <prefix>/lib/node_modules/<package>/bin/<command>.exe whose
+#                package.json names <package> (detail is the prefix)
+#   unrecognised anything else (detail is where it really points)
+# A copy is retired only when it is positively one of the first three; the bun install itself is
+# skipped. Several PATH entries that reach one real file (/bin -> usr/bin) count once.
+classify_surface_copies() {
+  local command_name="$1" package="$2" bun_exe="$3"
+  local dirs=() dir path real bun_real seen=" " native_bin="$administrator_home/.opencode/bin" prefix pkg_dir brew_prefix
+  brew_prefix="$(cd -P -- "${brew_bin%/bin/brew}" 2>/dev/null && pwd -P)" || brew_prefix="${brew_bin%/bin/brew}"
+  IFS=: read -r -a dirs <<<"$surface_cli_search_path"
+  dirs+=("$native_bin")
+  bun_real="$(adl_realpath "$bun_exe" 2>/dev/null)" || bun_real="$bun_exe"
+  for dir in "${dirs[@]}"; do
+    [[ -n "$dir" ]] || continue
+    path="$dir/$command_name"
+    [[ -e "$path" || -L "$path" ]] || continue
+    real="$(adl_realpath "$path" 2>/dev/null)" || real="$path"
+    [[ "$real" != "$bun_real" ]] || continue
+    case "$seen" in *" $real "*) continue ;; esac
+    seen="$seen$real "
+    if [[ "$path" == "$native_bin/$command_name" && -f "$path" && ! -L "$path" && -x "$path" ]]; then
+      printf 'native\t%s\t%s\n' "$native_bin" "$path"
+    elif [[ "$real" =~ ^(.*)/Cellar/${command_name}/[^/]+/bin/${command_name}$ && "${BASH_REMATCH[1]}" == "$brew_prefix" ]]; then
+      printf 'brew\t%s\t%s\n' "$path" "${BASH_REMATCH[1]}"
+    elif [[ "$real" =~ ^(.*)/lib/node_modules/${package}/bin/${command_name}\.exe$ ]]; then
+      prefix="${BASH_REMATCH[1]}"
+      pkg_dir="$prefix/lib/node_modules/$package"
+      if [[ -f "$pkg_dir/package.json" ]] && jq -e --arg name "$package" '.name == $name' "$pkg_dir/package.json" >/dev/null 2>&1; then
+        printf 'npm\t%s\t%s\n' "$path" "$prefix"
+      else
+        printf 'unrecognised\t%s\t%s\n' "$path" "$real"
+      fi
+    else
+      printf 'unrecognised\t%s\t%s\n' "$path" "$real"
+    fi
+  done
+}
+
+# Retires every other copy of a bun-managed surface so the host has exactly one, idempotently:
+# the native installer's ~/.opencode/bin is moved ASIDE under <state dir>/retired-opencode/<UTC
+# stamp>/native-bin (never deleted; ~/.opencode's own plugin files and ~/.config/opencode are not
+# touched), a Homebrew formula goes through `brew uninstall` as the Homebrew owner (run_brew, never
+# sudo brew), and an npm global goes through `npm uninstall -g --prefix <its real prefix>`. Anything
+# not positively identified is an ERROR and NOTHING is removed. Plan mode lists what apply would do.
+retire_other_surface_copies() {
+  local name="$1" command_name="$2" package="$3" bun_exe="$4"
+  local kinds=() paths=() details=() kind path detail i unrecognised=0 aside=""
+  while IFS=$'\t' read -r kind path detail; do
+    [[ -n "$kind" ]] || continue
+    kinds+=("$kind"); paths+=("$path"); details+=("$detail")
+  done < <(classify_surface_copies "$command_name" "$package" "$bun_exe")
+  [[ "${#kinds[@]}" -gt 0 ]] || return 0
+  for ((i = 0; i < ${#kinds[@]}; i++)); do
+    [[ "${kinds[i]}" == unrecognised ]] || continue
+    unrecognised=1
+    if [[ "$mode" != apply ]]; then
+      echo "global-tools: would FAIL: unrecognised $command_name at ${paths[i]} (-> ${details[i]}); not a copy reconcile knows how to retire"
+    else
+      echo "ERROR surface $name: unrecognised $command_name at ${paths[i]} (-> ${details[i]}); not a copy reconcile knows how to retire, so nothing was removed" >&2
+    fi
+  done
+  if [[ "$unrecognised" -eq 1 ]]; then
+    [[ "$mode" != apply ]] || return 1
+    return 0
+  fi
+  if [[ "$mode" != apply ]]; then
+    for ((i = 0; i < ${#kinds[@]}; i++)); do
+      case "${kinds[i]}" in
+        native) echo "global-tools: would retire $command_name copy: move ${paths[i]} aside (native installer)" ;;
+        brew) echo "global-tools: would retire $command_name copy: brew uninstall $command_name (Homebrew formula, ${paths[i]})" ;;
+        npm) echo "global-tools: would retire $command_name copy: npm uninstall -g --prefix ${details[i]} $package (${paths[i]})" ;;
+      esac
+    done
+    return 0
+  fi
+  for ((i = 0; i < ${#kinds[@]}; i++)); do
+    case "${kinds[i]}" in
+      native)
+        [[ -n "$aside" ]] || aside="$state_dir/retired-$command_name/$(date -u +%Y%m%dT%H%M%SZ)"
+        mkdir -p -- "$aside" || return 1
+        mv -- "${paths[i]}" "$aside/native-bin" || { echo "ERROR surface $name: could not move ${paths[i]} aside to $aside" >&2; return 1; }
+        echo "global-tools: retiring $command_name copy: moved ${paths[i]} aside to $aside/native-bin"
+        ;;
+      brew)
+        run_brew uninstall "$command_name" || { echo "ERROR surface $name: brew uninstall $command_name failed" >&2; return 1; }
+        [[ ! -e "${paths[i]}" && ! -L "${paths[i]}" ]] || { echo "ERROR surface $name: ${paths[i]} is still present after brew uninstall $command_name" >&2; return 1; }
+        echo "global-tools: retiring $command_name copy: brew uninstalled $command_name (${paths[i]})"
+        ;;
+      npm)
+        run_npm uninstall -g --prefix "${details[i]}" "$package" || { echo "ERROR surface $name: npm uninstall -g $package failed" >&2; return 1; }
+        [[ ! -e "${paths[i]}" && ! -L "${paths[i]}" ]] || { echo "ERROR surface $name: ${paths[i]} is still present after npm uninstall -g $package" >&2; return 1; }
+        echo "global-tools: retiring $command_name copy: npm uninstalled $package from ${details[i]} (${paths[i]})"
+        ;;
+    esac
+  done
+}
+
+# Installs or updates a bun-managed surface (see run_surface_bun_add): one `bun add -g
+# <package>@latest` covers both "absent" and "present", then the other copies are retired and the
+# command the administrator's PATH resolves is checked to be bun's. Fails loud at every step; a
+# version is never pinned.
+reconcile_bun_surface_cli() {
+  local name="$1" command_name="$2" package="$3"
+  local bun_exe="$administrator_home/.bun/bin/$command_name" spec="$package@latest"
+  local old_version="" new_version update_output update_status=0 resolved
+  if [[ "$mode" != apply ]]; then
+    echo "would install or update surface from the npm registry: $name (bun add -g $spec as $administrator)"
+    retire_other_surface_copies "$name" "$command_name" "$package" "$bun_exe"
+    return 0
+  fi
+  [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
+  if [[ -x "$bun_exe" ]]; then old_version="$(surface_cli_version "$bun_exe")"; fi
+  update_output="$(run_with_timeout "$SURFACE_UPDATE_TIMEOUT_SECONDS" run_surface_bun_add "$spec" 2>&1)" || update_status=$?
+  printf '%s\n' "$update_output"
+  if [[ "$update_status" -eq 124 ]]; then
+    echo "ERROR surface update timed out: $name" >&2
+    return 1
+  elif [[ "$update_status" -ne 0 ]]; then
+    echo "ERROR surface update failed: $name (exit $update_status)" >&2
+    return 1
+  fi
+  # opencode-ai's bin is a stub that exits 1 until its postinstall puts the platform binary in
+  # place, and bun skips an untrusted package's postinstall: a bun add that "succeeded" but left
+  # a command that cannot report its version is not an install.
+  new_version="$(surface_cli_version "$bun_exe")"
+  if [[ -z "$new_version" ]]; then
+    echo "ERROR surface $name: bun add -g $spec succeeded but '$bun_exe --version' printed nothing; the package's postinstall did not run (check 'bun pm default-trusted' lists $package, or add it to the global trustedDependencies)" >&2
+    return 1
+  fi
+  retire_other_surface_copies "$name" "$command_name" "$package" "$bun_exe" || return 1
+  resolved="$(resolve_surface_executable "$command_name" "")"
+  if [[ "$resolved" != "$bun_exe" ]]; then
+    echo "ERROR surface $name: $command_name on ${administrator}'s PATH is ${resolved:-missing}, not the bun-installed $bun_exe" >&2
+    return 1
+  fi
+  if [[ -z "$old_version" ]]; then
+    echo "surface $name: installed $new_version ($package from the npm registry)"
+  elif [[ "$old_version" != "$new_version" ]]; then
+    echo "surface $name: $old_version -> $new_version"
+  else
+    echo "surface $name: already latest ($new_version)"
+  fi
+  return 0
+}
+
 # Reconciles one declared surface_clis entry. report_only (hostinger's loose
 # /root/codex, unknown install method) is version-reported only -- run_surface_update
 # is never called for it, by construction (this branch returns before
@@ -2028,12 +2290,30 @@ reconcile_one_surface_cli() {
   local name="$1" command_name="$2" executable_override="$3" report_only="$4" manager="$5"
   shift 5
   local update_args=("$@")
+  if [[ "$manager" == bun ]]; then
+    # For a bun surface the one trailing argument is the npm registry package, not an update argv.
+    reconcile_bun_surface_cli "$name" "$command_name" "${update_args[0]}"
+    return
+  fi
   if [[ "$manager" == brew ]]; then
     if [[ "$mode" != apply ]]; then
+      if [[ "$name" == */* ]]; then
+        echo "would trust Homebrew item: $name (cask)"
+      fi
       echo "would ensure Homebrew cask: $name (brew install --cask $name; brew upgrade --cask $name)"
       return 0
     fi
     [[ "$(id -u)" -eq 0 ]] || { echo "ERROR apply mode must run as root" >&2; exit 1; }
+    # A fully-qualified cask name comes from a non-core tap, which Homebrew
+    # >=6 refuses to load until the ITEM is trusted (same tap-trust grant as
+    # the per-tool brew path in install_one_tool; the kind is certain here).
+    # Bare names are core casks, trusted by default -- no grant.
+    if [[ "$name" == */* ]]; then
+      brew_query trust | awk '{$1=$1};1' | grep -Fqx "$name" || run_brew trust --cask "$name" || {
+        echo "ERROR surface $name: brew trust --cask $name failed" >&2
+        return 1
+      }
+    fi
     local installed_casks query_status=0 cask_action=() update_output update_status=0
     installed_casks="$(brew_query list --cask --versions 2>&1)" || query_status=$?
     if [[ "$query_status" -ne 0 ]]; then
@@ -2181,10 +2461,15 @@ reconcile_surface_clis() {
     report_only="$(jq -r --argjson i "$i" --arg platform "$platform" --arg device "$device" \
       '.[$platform].devices[$device].surface_clis[$i].report_only // false' "$manifest")"
     update_args=()
-    while IFS= read -r arg; do
-      [[ -n "$arg" ]] && update_args+=("$arg")
-    done < <(jq -r --argjson i "$i" --arg platform "$platform" --arg device "$device" \
-      '.[$platform].devices[$device].surface_clis[$i].update_args // [] | .[]' "$manifest")
+    if [[ "$manager" == bun ]]; then
+      update_args+=("$(jq -r --argjson i "$i" --arg platform "$platform" --arg device "$device" \
+        '.[$platform].devices[$device].surface_clis[$i].package // empty' "$manifest")")
+    else
+      while IFS= read -r arg; do
+        [[ -n "$arg" ]] && update_args+=("$arg")
+      done < <(jq -r --argjson i "$i" --arg platform "$platform" --arg device "$device" \
+        '.[$platform].devices[$device].surface_clis[$i].update_args // [] | .[]' "$manifest")
+    fi
     if ! reconcile_one_surface_cli "$name" "$command_name" "$executable_override" "$report_only" "$manager" ${update_args[@]+"${update_args[@]}"}; then
       echo "ERROR global-tools: TOOL INSTALL FAILED: surface-$name" >&2
       failed_tools+=("surface-$name")
@@ -2483,7 +2768,7 @@ if [[ "$(jq -r '.config.scratch_reap.enabled // false' "$manifest")" == true ]];
     # REFUSE to remove worktrees. That is the safe direction, so it must not
     # abort the fleet's update -- but it must not vanish either, or the
     # published-HEAD gate rots with nothing ever reporting it.
-    "$script_dir/scratch-reap" \
+    "$BASH" "$script_dir/scratch-reap" \
       "${scratch_reap_args[@]}" \
       --mode "$scratch_reap_mode" \
       --idle-days "$scratch_reap_idle_days" \
@@ -2512,15 +2797,10 @@ if [[ "$have_previous" -eq 1 ]]; then
     [[ -n "$tool_id" ]] || continue
     remove_one_manifest_entry "$tool_id"
   # Selects an id when it was deleted outright (absent from the current
-  # manifest) OR retained but migrated to a different manager/package (e.g.
-  # lean-ctx moving from npm:lean-ctx-bin to release-archive-latest:lean-ctx)
+  # manifest) OR retained but migrated to a different manager/package
   # -- a plain "id no longer present" check would silently leave the OLD
   # manager's install in place forever whenever an id survives a manager
-  # change, which for lean-ctx meant the stale npm package (and the
-  # /opt/homebrew/bin/lean-ctx shim it owns) would never be uninstalled, and
-  # that shim's earlier position on PATH than /usr/local/bin would keep
-  # `command -v lean-ctx` resolving to it instead of the new release binary
-  # no matter how many times reconcile ran.
+  # change, even though the current declaration points to a different install.
   done < <(jq -r --slurpfile current "$resolved_file" '
     keys[] as $id
     | ($current[0][$id]) as $cur
@@ -2547,6 +2827,9 @@ project_adl_package_payload() {
       echo "would build agent-skills payload from checkout"
     fi
     echo "would project Adl package payload from $repo_root to /usr/local/libexec/adl and /usr/local/bin/git{,-ado}"
+    if [[ "$source_mode" == npm ]]; then
+      echo "would link /usr/local/bin/adl to $repo_root/bin/adl"
+    fi
     return 0
   fi
   bun_bin="$(command -v bun || true)"
@@ -2561,6 +2844,12 @@ project_adl_package_payload() {
   if [[ -n "${RECONCILE_TEST_SYSTEM_ROOT:-}" ]]; then
     system_root_args+=(--system-root "$RECONCILE_TEST_SYSTEM_ROOT")
   fi
+  # Package mode also links /usr/local/bin/adl to this package's own bin/adl:
+  # bun links adl into the owner's ~/.bun/bin only, yet bin/git-ado, the MCP
+  # server command and the managed surface hooks run a bare `adl`.
+  if [[ "$source_mode" == npm ]]; then
+    system_root_args+=(--link-adl)
+  fi
   "$bun_bin" "$repo_root/packages/fleet/src/install-adl-package.ts" install \
     --package-root "$repo_root" ${system_root_args[@]+"${system_root_args[@]}"}
 }
@@ -2572,7 +2861,7 @@ 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
+if ! "$BASH" "$repo_root/bin/shell-path-policy" --home "$administrator_home" --platform "$platform" --mode "$mode" --owner "$administrator"; then
   echo "ERROR global-tools: TOOL INSTALL FAILED: shell-path-policy" >&2
   failed_tools+=("shell-path-policy")
 fi
@@ -2596,7 +2885,7 @@ if ! retire_git_maintain; then
 fi
 
 if [[ "$mode" == apply ]]; then
-  "$script_dir/health-check" "$device"
+  "$BASH" "$script_dir/health-check" "$device"
 fi
 
 if [[ "$(jq -r '.config.global_surface_sweep.enabled' "$manifest")" == true ]]; then
@@ -2609,7 +2898,7 @@ if [[ "$(jq -r '.config.global_surface_sweep.enabled' "$manifest")" == true ]];
   # recomputes the sweep's own backupPath() logic. stderr is left
   # unredirected so a real failure still streams live as before.
   sweep_status=0
-  sweep_output="$("$script_dir/global-surface-sweep" \
+  sweep_output="$("$BASH" "$script_dir/global-surface-sweep" \
     --home "$administrator_home" \
     --mode "$surface_mode" \
     --state-dir "$state_dir")" || sweep_status=$?
@@ -2647,7 +2936,7 @@ if [[ "$kimi_hooks_enabled" == true ]]; then
     echo "global-tools: kimi-hooks skipped: kimi not installed"
   elif [[ "$mode" != apply ]]; then
     echo "global-tools: kimi hooks mode=plan home=$administrator_home"
-    "$script_dir/kimi-hooks" --home "$administrator_home" --mode plan
+    "$BASH" "$script_dir/kimi-hooks" --home "$administrator_home" --mode plan
   else
     # Ordering: adl (bun-compile pass, above) must already resolve as
     # a bare command before we write TOML entries that reference it -- Kimi
@@ -2657,12 +2946,12 @@ if [[ "$kimi_hooks_enabled" == true ]]; then
     # docs/specs/two-branch-standard-2026-09-27.md) -- hard cut, no compat
     # shim: there is no standalone hook executable to resolve any more.
     adl_executable="$(jq -r '."adl".executable' "$resolved_file")"
-    if ! adl_resolved="$(sudo -u "$administrator" -H env PATH="/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/local/bin:/usr/bin:/bin" /bin/sh -c "command -v '$adl_executable'" 2>/dev/null)"; then
+    if ! adl_resolved="$(sudo -u "$administrator" -H env PATH="/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/local/bin:$administrator_home/.bun/bin:/usr/bin:/bin" /bin/sh -c "command -v '$adl_executable'" 2>/dev/null)"; then
       echo "ERROR global-tools: could not resolve adl from the administrator PATH" >&2
       exit 1
     fi
     [[ -n "$adl_resolved" && -x "$adl_resolved" ]] || {
-      echo "ERROR global-tools: kimi-hooks requires adl on PATH ($adl_executable); bun-compile installation must succeed first" >&2
+      echo "ERROR global-tools: kimi-hooks requires adl on PATH ($adl_executable); the adl package installation must succeed first" >&2
       exit 1
     }
     echo "global-tools: kimi hooks mode=apply home=$administrator_home (as $administrator)"
@@ -2679,7 +2968,7 @@ if [[ "$kimi_hooks_enabled" == true ]]; then
     # streams live exactly as before.
     kimi_hooks_status=0
     kimi_hooks_output="$(cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
-      "$script_dir/kimi-hooks" --home "$administrator_home" --mode apply)" || kimi_hooks_status=$?
+      "$BASH" "$script_dir/kimi-hooks" --home "$administrator_home" --mode apply)" || kimi_hooks_status=$?
     printf '%s\n' "$kimi_hooks_output"
     collect_kimi_hooks_backups "$kimi_hooks_output"
     [[ "$kimi_hooks_status" -eq 0 ]] || exit "$kimi_hooks_status"
@@ -2692,50 +2981,11 @@ fi
 # run the same hook contract twice. The exact old path remains Enact-owned.
 if [[ "$mode" != apply ]]; then
   echo "global-tools: retired OpenCode carrier mode=plan home=$administrator_home"
-  "$script_dir/opencode-hooks" --home "$administrator_home" --mode plan
+  "$BASH" "$script_dir/opencode-hooks" --home "$administrator_home" --mode plan
 else
   echo "global-tools: retired OpenCode carrier mode=remove home=$administrator_home (as $administrator)"
   (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
-    "$script_dir/opencode-hooks" --home "$administrator_home" --mode remove)
-fi
-
-# STATUS.md 12p item 13, final scope (2026-09-29): lean-ctx hooks are "moved
-# to repo level" and must be REMOVED FROM GLOBAL -- the per-repo carrier
-# (`adl hook lean-ctx pre-tool-use|post-tool-use --host=<x>`, written by
-# `adl hooks deploy`) already provides them with the repo's own config, so
-# any raw, unwrapped `lean-ctx hook <subcommand>` entry left in a per-user
-# config (observe, rewrite, redirect, read-dedup, any other) is retracted
-# global wiring, never the per-repo carrier or Orca's own hooks -- see
-# bin/lib/lean-ctx-observe-hooks.sh's header for the full decision trail and
-# exactly which per-user files can carry one. Unconditional, like the
-# retired OpenCode carrier cleanup just above: not a manifest-gated optional
-# feature, a standing cleanup that runs every reconciliation so a
-# hand-edited or Orca-reinstalled per-user config never lets this creep back
-# in unnoticed.
-if [[ "$mode" != apply ]]; then
-  echo "global-tools: lean-ctx observe/raw-hook strip mode=plan home=$administrator_home"
-  # Plan runs either unprivileged (the administrator's own shell) or under
-  # sudo (fleet-cutover.sh's plan). As root it must drop to the administrator
-  # exactly like apply: lean-ctx-observe-strip refuses root against a
-  # non-root home (m5 cutover plan, 2026-09-29).
-  if [[ "$EUID" -eq 0 && "$administrator" != root ]]; then
-    (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
-      "$script_dir/lean-ctx-observe-strip" --home "$administrator_home" --mode plan)
-  else
-    "$script_dir/lean-ctx-observe-strip" --home "$administrator_home" --mode plan
-  fi
-else
-  echo "global-tools: lean-ctx observe/raw-hook strip mode=apply home=$administrator_home (as $administrator)"
-  # stdout captured (then re-printed) so its own "backed up previous config
-  # to ..." note(s) can be folded into this run's combined backups list,
-  # exactly like kimi-hooks above; stderr left unredirected so a real
-  # failure (a file that fails to parse) still streams live.
-  lean_ctx_observe_strip_status=0
-  lean_ctx_observe_strip_output="$(cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
-    "$script_dir/lean-ctx-observe-strip" --home "$administrator_home" --mode apply)" || lean_ctx_observe_strip_status=$?
-  printf '%s\n' "$lean_ctx_observe_strip_output"
-  collect_lean_ctx_observe_strip_backups "$lean_ctx_observe_strip_output"
-  [[ "$lean_ctx_observe_strip_status" -eq 0 ]] || exit "$lean_ctx_observe_strip_status"
+    "$BASH" "$script_dir/opencode-hooks" --home "$administrator_home" --mode remove)
 fi
 
 # surface-policy re-asserts each host's permission MODE from the single source
@@ -2758,11 +3008,11 @@ fi
 if [[ "$surface_policy_enabled" == true ]]; then
   if [[ "$mode" != apply ]]; then
     echo "global-tools: surface policy mode=plan home=$administrator_home"
-    "$script_dir/surface-policy" --home "$administrator_home" --mode plan
+    "$BASH" "$script_dir/surface-policy" --home "$administrator_home" --mode plan
   else
     echo "global-tools: surface policy mode=apply home=$administrator_home (as $administrator)"
     (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
-      "$script_dir/surface-policy" --home "$administrator_home" --mode apply)
+      "$BASH" "$script_dir/surface-policy" --home "$administrator_home" --mode apply)
   fi
 fi
 
@@ -2774,24 +3024,24 @@ fi
 if [[ "$vscode_settings_enabled" == true ]]; then
   if [[ "$mode" != apply ]]; then
     echo "global-tools: VS Code settings mode=plan home=$administrator_home"
-    "$script_dir/vscode-settings" --home "$administrator_home" --platform "$platform" --mode plan
+    "$BASH" "$script_dir/vscode-settings" --home "$administrator_home" --platform "$platform" --mode plan
   else
     echo "global-tools: VS Code settings mode=apply home=$administrator_home (as $administrator)"
     (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
-      "$script_dir/vscode-settings" --home "$administrator_home" --platform "$platform" --mode apply)
+      "$BASH" "$script_dir/vscode-settings" --home "$administrator_home" --platform "$platform" --mode apply)
   fi
 fi
 
 if [[ "$global_agents_enabled" == true ]]; then
   if [[ "$mode" != apply ]]; then
     echo "global-tools: global agents mode=status home=$administrator_home"
-    "$script_dir/global-agents" --home "$administrator_home" --mode status
+    "$BASH" "$script_dir/global-agents" --home "$administrator_home" --mode status
   else
     echo "global-tools: global agents mode=deploy home=$administrator_home (as $administrator)"
     # The exact target files are authoritative global artifacts. Drift is
     # replaced from GLOBAL-AGENTS.md with no backup or leave-in-place branch.
     (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
-      "$script_dir/global-agents" --home "$administrator_home" --mode deploy)
+      "$BASH" "$script_dir/global-agents" --home "$administrator_home" --mode deploy)
   fi
 fi