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

package/bin/reconcile-host

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# `sudo adl reconcile --host NAME [--mode plan|apply]` -- one full pass of what
+# the 12-hourly job does (the job's program is `adl reconcile`, which runs this),
+# also run on demand:
+#
+#   1. tools: this package's bin/sync-and-reconcile (run through bash, never
+#      executed directly: bun leaves every shipped file but the `bin` targets
+#      without an exec bit) with `--source npm --device NAME --owner OWNER`
+#      (package update with bun, then tools reconcile). `--source npm` names
+#      the registry the package comes from, not the installer. The owner is the
+#      device's `administrator` in this package's
+#      manifest (bin/lib/fleet-host.sh, the lookup bin/setup shares). --mode is
+#      forwarded only when given, so the default is apply.
+#   2. repositories: `adl maintain --location <repo_location> --expect-user
+#      OWNER`, the package's own bin/adl, run AS THE ADMINISTRATOR -- never as
+#      root. sudo resets PATH to its secure_path, which has neither Homebrew nor
+#      /usr/local/bin, so PATH is always handed over explicitly with `env PATH=`
+#      (every sudo -u call that ends up running adl, git or bun must); the
+#      owner's bun bin directory (~/.bun/bin) is on it, after /usr/local/bin.
+#      --mode plan becomes --dry-run.
+#
+# Both steps always run (a failed tools step does not hide a repository problem,
+# and vice versa); the exit code is the first failure's, and each failure is
+# reported as an ERROR line. A host that declares no repo_location skips step 2
+# with a log line.
+#
+# ADL_SETUP_TEST_ROOT is the same single test switch bin/setup has: unset in
+# every real run; when set it only keeps the caller's PATH so `id`, `uname` and
+# `sudo` can be stubbed (packages/fleet/tests/reconcile-host.test.ts).
+
+if [[ -n "${ADL_SETUP_TEST_ROOT:-}" ]]; then
+  export PATH="${PATH:-/usr/bin:/bin}"
+else
+  export PATH="/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+fi
+
+host=""
+mode=""
+while [[ "$#" -gt 0 ]]; do
+  case "$1" in
+    --host) host="${2:-}"; shift 2 ;;
+    --mode) mode="${2:-}"; shift 2 ;;
+    *) echo "ERROR unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+[[ -n "$host" ]] || { echo "ERROR usage: sudo adl reconcile --host NAME [--mode plan|apply]" >&2; exit 2; }
+if [[ -n "$mode" && "$mode" != plan && "$mode" != apply ]]; then
+  echo "ERROR unsupported mode: $mode (expected plan or apply)" >&2
+  exit 2
+fi
+[[ "$(id -u)" -eq 0 ]] || { echo "ERROR adl reconcile must run as root: sudo adl reconcile --host $host" >&2; exit 1; }
+
+script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+package_dir="$(cd -- "$script_dir/.." && pwd)"
+# shellcheck source=lib/fleet-host.sh
+source "$script_dir/lib/fleet-host.sh"
+fleet_host_resolve "adl reconcile" "$package_dir/packages/fleet/manifest.json" "$host" || exit $?
+owner="$fleet_host_owner"
+repo_location="$fleet_host_repo_location"
+branch_max_age_days="$fleet_host_branch_max_age_days"
+
+# shellcheck source=lib/adl-package.sh
+source "$script_dir/lib/adl-package.sh"
+[[ -f "$script_dir/sync-and-reconcile" ]] || { echo "ERROR adl reconcile: package scheduler script is missing: $script_dir/sync-and-reconcile" >&2; exit 1; }
+
+# One lock around both steps: an on-demand run overlapping the timer must not
+# run a second repository pass after its tools step lost sync's own lock.
+if [[ -n "${ADL_SETUP_TEST_ROOT:-}" ]]; then
+  lock_dir="${ADL_SETUP_TEST_ROOT%/}/adl-reconcile.lock"
+else
+  lock_dir=/var/run/adl-reconcile.lock
+fi
+adl_lock_acquire "$lock_dir" "adl reconcile: another reconcile is running" || exit 1
+trap 'rm -rf -- "$lock_dir"' EXIT
+
+# 1. tools
+sync_args=(--source npm --device "$host" --owner "$owner")
+if [[ -n "$mode" ]]; then sync_args+=(--mode "$mode"); fi
+tools_rc=0
+bash "$script_dir/sync-and-reconcile" "${sync_args[@]}" || tools_rc=$?
+if [[ "$tools_rc" -ne 0 ]]; then
+  echo "ERROR global-tools: tools reconcile failed (exit $tools_rc)" >&2
+fi
+
+# 2. repositories
+repos_rc=0
+if [[ -z "$repo_location" ]]; then
+  echo "global-tools: repo maintenance skipped: $host declares no repo_location"
+else
+  adl_bin="$package_dir/bin/adl"
+  if [[ ! -x "$adl_bin" ]]; then
+    echo "ERROR global-tools: package adl is missing or not executable: $adl_bin" >&2
+    repos_rc=1
+  else
+    case "$fleet_host_platform" in
+      mac) repo_os=Darwin ;;
+      *) repo_os=Linux ;;
+    esac
+    if ! owner_home="$(adl_owner_home "$owner")"; then
+      echo "ERROR global-tools: cannot resolve the home directory of $owner" >&2
+      exit 1
+    fi
+    owner_path="$(adl_owner_path "$repo_os" "$owner_home")"
+    maintain_args=(maintain --location "$repo_location" --expect-user "$owner")
+    # config.repo_maintain.branch_max_age_days in this package's manifest, never an environment variable.
+    if [[ -n "$branch_max_age_days" ]]; then maintain_args+=(--branch-max-age-days "$branch_max_age_days"); fi
+    if [[ "$mode" == plan ]]; then maintain_args+=(--dry-run); fi
+    # /usr/local/bin first (see adl_owner_path): git must resolve to the managed
+    # controller, which routes Azure DevOps traffic through the agent identity;
+    # Homebrew's git would bypass it.
+    sudo -u "$owner" -H env PATH="$owner_path" "$adl_bin" "${maintain_args[@]}" || repos_rc=$?
+    if [[ "$repos_rc" -ne 0 ]]; then
+      echo "ERROR global-tools: repository maintenance failed (exit $repos_rc)" >&2
+    fi
+  fi
+fi
+
+if [[ "$tools_rc" -ne 0 ]]; then exit "$tools_rc"; fi
+exit "$repos_rc"

package/bin/setup

@@ -0,0 +1,219 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# `sudo adl setup --host NAME` -- the whole onboarding of a host after
+# `bun install -g @amsterdamdatalabs/adl-agent-control` (run as the device's
+# administrator):
+#
+#   1. check this is THE package the job manages (the one in the owner's bun
+#      global directory), that its bin/adl is there, and that the `adl` the
+#      owner gets on PATH is this package and not a different one that shadows it
+#   2. run the first reconcile: `<this package>/bin/adl reconcile --host NAME`
+#   3. only if that succeeded, arm the job that re-runs the same command every
+#      12 hours
+#
+# A host that cannot reconcile is never left with a timer that fails unseen.
+# The job's program is the package's own bin/adl, not a shell script: on macOS
+# the one-time Full Disk Access grant (needed to read the repositories under the
+# host's repo_location) goes to that binary, and the launchd/systemd job and
+# `sudo adl reconcile --host NAME` are then literally the same command.
+#
+# Everything comes from this package: it locates itself from its own path and
+# reads packages/fleet/manifest.json beside it (no git checkout, no source
+# flag -- the published package is the only source). The account the job runs
+# bun as is the device's `administrator` in that manifest; there is no owner
+# flag. The package's scripts are run through bash, never executed directly:
+# bun leaves every shipped file but the `bin` targets without an exec bit.
+#
+# ADL_SETUP_TEST_ROOT is the one test switch (packages/fleet/tests/setup.test.ts):
+# unset in every real run. When set it relocates the system paths under that
+# directory and keeps the caller's PATH so the system commands can be stubbed.
+
+if [[ -n "${ADL_SETUP_TEST_ROOT:-}" ]]; then
+  export PATH="${PATH:-/usr/bin:/bin}"
+  # The sourced sync-and-reconcile has its own test switch; one switch here
+  # drives both, so a test sets only ADL_SETUP_TEST_ROOT.
+  export SYNC_AND_RECONCILE_TEST_ROOT="$ADL_SETUP_TEST_ROOT"
+else
+  export PATH="/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+fi
+
+host=""
+while [[ "$#" -gt 0 ]]; do
+  case "$1" in
+    --host) host="${2:-}"; shift 2 ;;
+    *) echo "ERROR unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+[[ -n "$host" ]] || { echo "ERROR usage: sudo adl setup --host NAME" >&2; exit 2; }
+[[ "$(id -u)" -eq 0 ]] || { echo "ERROR adl setup must run as root: sudo adl setup --host $host" >&2; exit 1; }
+
+script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+package_dir="$(cd -- "$script_dir/.." && pwd)"
+package_dir_real="$(cd -P -- "$script_dir/.." && pwd -P)"
+# shellcheck source=lib/fleet-host.sh
+source "$script_dir/lib/fleet-host.sh"
+fleet_host_resolve "adl setup" "$package_dir/packages/fleet/manifest.json" "$host" || exit $?
+owner="$fleet_host_owner"
+minute="$fleet_host_minute"
+
+# The job keeps THE package installed in the owner's bun global directory up to
+# date and reconciles from it. This must be that package, or the host would be
+# armed to manage a different copy than the one the operator just ran. Ask for
+# the location the way the job does (bin/lib/adl-package.sh, shared with
+# sync-and-reconcile), and compare real paths.
+# shellcheck source=lib/adl-package.sh
+source "$script_dir/lib/adl-package.sh"
+os_name="$(uname -s)"
+owner_home="$(adl_owner_home "$owner")" || {
+  echo "ERROR adl setup: cannot resolve the home directory of $owner" >&2
+  exit 1
+}
+managed_dir="$(adl_platform_package_dir "$(adl_global_node_modules "$owner_home")" "$os_name" "$(uname -m)")" || exit 1
+managed_real="$(cd -P -- "$managed_dir" 2>/dev/null && pwd -P)" || managed_real=""
+if [[ -z "$managed_real" || "$package_dir_real" != "$managed_real" ]]; then
+  {
+    echo "ERROR adl setup: this package ($package_dir_real) is not the package the scheduled job manages ($managed_dir)."
+    echo "ERROR adl setup: install it where the job looks, as $owner, then run setup again:"
+    echo "ERROR adl setup:   bun install -g @amsterdamdatalabs/adl-agent-control"
+  } >&2
+  exit 1
+fi
+
+adl_bin="$package_dir_real/bin/adl"
+[[ -x "$adl_bin" ]] || { echo "ERROR adl setup: the package adl is missing or not executable: $package_dir/bin/adl" >&2; exit 1; }
+adl_check_adl_not_shadowed "$owner" "$os_name" "$owner_home" "$package_dir_real" "adl setup" || exit 1
+
+if [[ -n "${ADL_SETUP_TEST_ROOT:-}" ]]; then
+  system_root="${ADL_SETUP_TEST_ROOT%/}"
+else
+  system_root=""
+fi
+legacy_adl_sync="$system_root/usr/local/libexec/adl-sync"
+launch_daemons_dir="$system_root/Library/LaunchDaemons"
+systemd_dir="$system_root/etc/systemd/system"
+brew_prefix="$system_root/home/linuxbrew/.linuxbrew"
+
+# Preflight that must hold before the first reconcile: the Linux job runs
+# Homebrew as a non-root owner, and that owner needs git's safe.directory for
+# the brew repositories or every `brew update` inside the reconcile fails.
+if [[ "$fleet_host_platform" == linux ]]; then
+  if [[ -d "$brew_prefix" ]]; then
+    brew_owner="$(stat -c '%U' "$brew_prefix")"
+    [[ "$brew_owner" != root ]] || {
+      echo "ERROR Homebrew prefix must be owned by a non-root account: /home/linuxbrew/.linuxbrew" >&2
+      exit 1
+    }
+  else
+    echo "ERROR Homebrew prefix missing: /home/linuxbrew/.linuxbrew" >&2
+    exit 1
+  fi
+  for brew_repo in \
+    "$brew_prefix/Homebrew" \
+    "$brew_prefix/Homebrew/Library/Taps/adl-tan-theta/homebrew-tap"; do
+    [[ -d "$brew_repo/.git" ]] || continue
+    if ! (cd /tmp && sudo -u "$brew_owner" -H git config --global --get-all safe.directory 2>/dev/null) | grep -Fxq "$brew_repo"; then
+      (cd /tmp && sudo -u "$brew_owner" -H git config --global --add safe.directory "$brew_repo")
+    fi
+  done
+fi
+
+mkdir -p "$system_root/var/lib/adl" "$system_root/var/log/adl"
+
+echo "adl setup: first reconcile for $host (owner $owner)"
+reconcile_rc=0
+"$adl_bin" reconcile --host "$host" || reconcile_rc=$?
+if [[ "$reconcile_rc" -ne 0 ]]; then
+  echo "ERROR adl setup: first reconcile failed (exit $reconcile_rc); scheduler NOT armed. Fix the failure and re-run: sudo adl setup --host $host" >&2
+  exit "$reconcile_rc"
+fi
+
+case "$fleet_host_platform" in
+  mac)
+    mkdir -p "$launch_daemons_dir"
+    plist="$launch_daemons_dir/com.adl.global-tools.plist"
+    {
+      printf '%s\n' '<?xml version="1.0" encoding="UTF-8"?>'
+      printf '%s\n' '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">'
+      printf '%s\n' '<plist version="1.0"><dict>'
+      printf '%s\n' '<key>Label</key><string>com.adl.global-tools</string>'
+      printf '%s\n' '<key>ProgramArguments</key><array>'
+      printf '<string>%s</string>\n' "$adl_bin"
+      printf '%s\n' '<string>reconcile</string>'
+      printf '<string>--host</string><string>%s</string>\n' "$host"
+      printf '%s\n' '</array>'
+      printf '%s\n' '<key>StartCalendarInterval</key><array>'
+      for hour in 0 12; do printf '<dict><key>Hour</key><integer>%s</integer><key>Minute</key><integer>%s</integer></dict>\n' "$hour" "$minute"; done
+      printf '%s\n' '</array><key>ProcessType</key><string>Background</string>'
+      printf '%s\n' '<key>StandardOutPath</key><string>/var/log/adl/stdout.log</string>'
+      printf '%s\n' '<key>StandardErrorPath</key><string>/var/log/adl/stderr.log</string>'
+      printf '%s\n' '</dict></plist>'
+    } >"$plist"
+    chown root:wheel "$plist"
+    chmod 0644 "$plist"
+    plutil -lint "$plist"
+    # bootout fails when the job is not loaded, so ask first instead of
+    # swallowing the error: a bootout that fails on a loaded job must stop us.
+    if launchctl print system/com.adl.global-tools >/dev/null 2>&1; then
+      launchctl bootout system/com.adl.global-tools
+      # bootout returns before launchd has finished unloading, and a
+      # bootstrap in that window fails with an I/O error. Wait until the
+      # label is really gone, bounded, and fail loud if it is not.
+      unloaded=0
+      for _ in 1 2 3 4 5 6 7 8 9 10; do
+        if ! launchctl print system/com.adl.global-tools >/dev/null 2>&1; then unloaded=1; break; fi
+        sleep 0.5
+      done
+      [[ "$unloaded" -eq 1 ]] || {
+        echo "ERROR adl setup: com.adl.global-tools is still loaded after bootout (waited 5s); not bootstrapping. Run: sudo launchctl bootout system/com.adl.global-tools" >&2
+        exit 1
+      }
+    fi
+    launchctl bootstrap system "$plist"
+    ;;
+  linux)
+    mkdir -p "$systemd_dir"
+    cat > "$systemd_dir/adl-global-tools.service" <<EOF
+[Unit]
+Description=Reconcile Adl global tools and repositories (adl reconcile)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+ExecStart=$adl_bin reconcile --host $host
+StandardOutput=append:/var/log/adl/stdout.log
+StandardError=append:/var/log/adl/stderr.log
+Nice=10
+IOSchedulingClass=best-effort
+IOSchedulingPriority=7
+TimeoutStartSec=3h
+EOF
+    cat > "$systemd_dir/adl-global-tools.timer" <<EOF
+[Unit]
+Description=Run Adl global-tool reconciliation every 12 hours
+
+[Timer]
+OnCalendar=*-*-* 00,12:$minute:00
+Persistent=true
+Unit=adl-global-tools.service
+
+[Install]
+WantedBy=timers.target
+EOF
+    systemctl daemon-reload
+    systemctl enable --now adl-global-tools.timer
+    # enable --now leaves an already-active timer on its old schedule.
+    systemctl restart adl-global-tools.timer
+    ;;
+esac
+
+# The job used to run a copy of bin/sync-and-reconcile installed here. Its
+# definition now points at the package's adl, so the copy is dead weight that
+# would keep running stale update logic if anyone invoked it.
+if [[ -e "$legacy_adl_sync" ]]; then
+  rm -f -- "$legacy_adl_sync"
+  echo "adl setup: removed the legacy scheduler copy $legacy_adl_sync"
+fi
+
+echo "adl setup: $host reconciled and armed (every 12 hours at minute $minute); run on demand with: sudo adl reconcile --host $host"

package/bin/shell-path-policy

@@ -1,9 +1,15 @@
 #!/usr/bin/env bash
 # Managed by adl global-tools.
 # Keep /usr/local/bin first in interactive shells so manifest-owned front
-# controllers win over Homebrew and system executables on every host.
+# controllers win over Homebrew and system executables on every host. The
+# administrator's bun bin directory comes right after it (Tarun, 2026-10-01):
+# hosts install the adl package with `bun install -g`, which links `adl` into
+# $HOME/.bun/bin, and humans and agents must be able to run it (root on Linux:
+# /root/.bun/bin). It stays behind /usr/local/bin so the managed git wins.
 set -euo pipefail
 
+managed_path_line='export PATH="/usr/local/bin:$HOME/.bun/bin${PATH:+:$PATH}"'
+
 usage() {
   echo 'usage: shell-path-policy --home ABSOLUTE_PATH --platform mac|linux --mode plan|apply [--owner USER]' >&2
   exit 2
@@ -35,10 +41,14 @@ upsert_block() {
   mkdir -p -- "$(dirname -- "$file")"
   temp="$file.adl-new"
   if [[ -e "$file" ]]; then
+    # Trailing blank lines are dropped with the block: the append below puts one
+    # blank line back in front of it, so a re-run is byte-identical, not one line longer.
     awk -v begin="$begin" -v end="$end" '
       $0 == begin { inside = 1; next }
       $0 == end { inside = 0; next }
-      !inside { print }
+      inside { next }
+      /^$/ { blanks++; next }
+      { while (blanks > 0) { print ""; blanks-- } print }
     ' "$file" >"$temp"
   else
     : >"$temp"
@@ -50,14 +60,14 @@ upsert_block() {
 
 if [[ "$platform" == mac ]]; then
   upsert_block "$home/.zshenv" '# BEGIN ADL GLOBAL PATH' '# END ADL GLOBAL PATH' \
-    'export PATH="/usr/local/bin${PATH:+:$PATH}"'
+    "$managed_path_line"
   exit 0
 fi
 
 upsert_block "$home/.bashenv" '# BEGIN ADL GLOBAL PATH ENV' '# END ADL GLOBAL PATH ENV' \
-  'export PATH="/usr/local/bin${PATH:+:$PATH}"'
+  "$managed_path_line"
 upsert_block "$home/.zshenv" '# BEGIN ADL GLOBAL PATH ENV' '# END ADL GLOBAL PATH ENV' \
-  'export PATH="/usr/local/bin${PATH:+:$PATH}"'
+  "$managed_path_line"
 for shell_file in "$home/.bashrc" "$home/.bash_profile" "$home/.profile"; do
   upsert_block "$shell_file" '# BEGIN ADL GLOBAL PATH SOURCE' '# END ADL GLOBAL PATH SOURCE' \
     'if [[ -r "$HOME/.bashenv" ]]; then . "$HOME/.bashenv"; fi'

package/bin/sync-and-reconcile

@@ -7,20 +7,26 @@ else
   export PATH="/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"
 fi
 
-# Scheduled sync downloads the ADL platform package and executes its own
-# reconcile command. Checkout mode is an explicit developer-only bypass.
+# Scheduled sync installs the published ADL package with bun (as the device's
+# administrator) and runs that package's own reconcile. Checkout mode is an
+# explicit developer-only bypass. Package layout and owner lookups are in
+# lib/adl-package.sh, shared with bin/setup and bin/reconcile.
+_sync_and_reconcile_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/adl-package.sh
+source "$_sync_and_reconcile_dir/lib/adl-package.sh"
+
 sync_and_reconcile_platform() {
   case "$(uname -s)" in
     Darwin) printf '%s\n' mac ;;
     Linux) printf '%s\n' linux ;;
-    *) echo "unsupported operating system for scheduled sync: $(uname -s)" >&2; return 1 ;;
+    *) echo "ERROR unsupported operating system for scheduled sync: $(uname -s)" >&2; return 1 ;;
   esac
 }
 
 require_linux_automation_root() {
   local platform="$1" owner="$2"
   if [[ "$platform" == linux && "$owner" != root ]]; then
-    echo "global-tools: Linux scheduled sync must run as root; got --owner $owner" >&2
+    echo "ERROR global-tools: Linux scheduled sync must run as root; got --owner $owner" >&2
     return 1
   fi
 }
@@ -35,35 +41,25 @@ parse_sync_source() {
   done
   case "$sync_source" in
     npm|checkout) ;;
-    *) echo "unsupported source: $sync_source" >&2; return 2 ;;
+    *) echo "ERROR unsupported source: $sync_source" >&2; return 2 ;;
   esac
 }
 
-npm_package_spec() {
+adl_package_spec() {
   local policy="$1" version="${2:-}"
   case "$policy" in
     latest-stable) printf '%s@latest\n' '@amsterdamdatalabs/adl-agent-control' ;;
     pinned)
       [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+([-.][0-9A-Za-z.-]+)?$ ]] || {
-        echo "pinned update_policy requires a valid installed package version" >&2
+        echo "ERROR pinned update_policy requires a valid installed package version" >&2
         return 1
       }
       printf '%s@%s\n' '@amsterdamdatalabs/adl-agent-control' "$version"
       ;;
-    *) echo "unsupported update_policy: $policy" >&2; return 1 ;;
+    *) echo "ERROR unsupported update_policy: $policy" >&2; return 1 ;;
   esac
 }
 
-npm_platform_package_dir() {
-  local npm_root="$1" os="$2" arch="$3" platform
-  case "$os:$arch" in
-    Darwin:arm64) platform=darwin-arm64 ;;
-    Linux:x86_64) platform=linux-x64 ;;
-    *) echo "unsupported platform for npm package: $os $arch" >&2; return 1 ;;
-  esac
-  printf '%s/@amsterdamdatalabs/adl-agent-control-%s\n' "${npm_root%/}" "$platform"
-}
-
 prepare_adl_npm_migration() {
   local applied_manifest="$1" device="$2" platform="$3" legacy_adl="$4" hash_file="$5"
   local previous_manager previous_executable
@@ -72,12 +68,12 @@ prepare_adl_npm_migration() {
   previous_executable="$(jq -r --arg platform "$platform" --arg device "$device" '(.[$platform].common.tools // {}) * (.[$platform].devices[$device].tools // {}) | .adl.executable // empty' "$applied_manifest")" || return 1
   [[ "$previous_manager" == bun-compile && "$previous_executable" == /usr/local/bin/adl ]] || return 0
   [[ -f "$legacy_adl" && ! -L "$legacy_adl" ]] || {
-    echo "prior manifest proves adl was a Bun binary, but the expected regular file is missing or is a symlink: $legacy_adl" >&2
+    echo "ERROR prior manifest proves adl was a Bun binary, but the expected regular file is missing or is a symlink: $legacy_adl" >&2
     return 1
   }
   rm -f -- "$legacy_adl"
   rm -f -- "$hash_file"
-  echo "global-tools: removed prior Bun adl binary before npm install: $legacy_adl"
+  echo "global-tools: removed prior Bun adl binary before the package install: $legacy_adl"
 }
 
 if [[ "${SYNC_AND_RECONCILE_SOURCE_ONLY:-0}" == 1 ]]; then
@@ -96,94 +92,84 @@ while [[ "$#" -gt 0 ]]; do
     --repo) repo="${2:-}"; shift 2 ;;
     --owner) owner="${2:-}"; shift 2 ;;
     --mode) mode="${2:-}"; shift 2 ;;
-    *) echo "unknown argument: $1" >&2; exit 2 ;;
+    *) echo "ERROR unknown argument: $1" >&2; exit 2 ;;
   esac
 done
 case "$sync_source" in
   npm|checkout) ;;
-  *) echo "unsupported source: $sync_source" >&2; exit 2 ;;
+  *) echo "ERROR unsupported source: $sync_source" >&2; exit 2 ;;
 esac
 [[ -n "$device" && -n "$owner" ]] || {
-  echo "usage: sync-and-reconcile [--source npm|checkout] --device NAME --owner USER [--repo PATH] [--mode audit|plan|apply]" >&2
+  echo "ERROR usage: sync-and-reconcile [--source npm|checkout] --device NAME --owner USER [--repo PATH] [--mode audit|plan|apply]" >&2
   exit 2
 }
 [[ "$mode" == audit || "$mode" == plan || "$mode" == apply ]] || {
-  echo "unsupported reconcile mode: $mode" >&2
+  echo "ERROR unsupported reconcile mode: $mode" >&2
   exit 2
 }
 if [[ "$sync_source" == checkout && -z "$repo" ]]; then
-  echo "checkout source requires --repo PATH" >&2
+  echo "ERROR checkout source requires --repo PATH" >&2
   exit 2
 fi
 if [[ "$sync_source" == npm && -n "$repo" ]]; then
-  echo "npm source does not accept --repo; use --source checkout for a checkout path" >&2
+  echo "ERROR npm source does not accept --repo; use --source checkout for a checkout path" >&2
   exit 2
 fi
 
 if [[ -n "${SYNC_AND_RECONCILE_TEST_ROOT:-}" ]]; then
   lock_dir="${SYNC_AND_RECONCILE_TEST_ROOT%/}/adl-sync.lock"
-  scheduler_path="${SYNC_AND_RECONCILE_TEST_ROOT%/}/scheduler"
 else
   lock_dir=/var/run/adl-sync.lock
-  scheduler_path=/usr/local/libexec/adl-sync
-fi
-if ! mkdir "$lock_dir" 2>/dev/null; then
-  echo "global-tools: another reconciliation is running (lock: $lock_dir)" >&2
-  exit 1
 fi
-trap 'rmdir "$lock_dir" 2>/dev/null || true' EXIT
+adl_lock_acquire "$lock_dir" "global-tools: another reconciliation is running" || exit 1
+trap 'rm -rf -- "$lock_dir"' EXIT
 
 host_platform="$(sync_and_reconcile_platform)"
 require_linux_automation_root "$host_platform" "$owner" || exit 1
 
 if [[ "$sync_source" == checkout ]]; then
-  [[ -e "$repo/.git" ]] || { echo "developer checkout missing: $repo" >&2; exit 1; }
+  [[ -e "$repo/.git" ]] || { echo "ERROR developer checkout missing: $repo" >&2; exit 1; }
   manifest="$repo/packages/fleet/manifest.json"
-  [[ -f "$manifest" ]] || { echo "developer checkout manifest missing: $manifest" >&2; exit 1; }
-  [[ -x "$repo/bin/reconcile" ]] || { echo "developer checkout reconcile is missing: $repo/bin/reconcile" >&2; exit 1; }
+  [[ -f "$manifest" ]] || { echo "ERROR developer checkout manifest missing: $manifest" >&2; exit 1; }
+  [[ -f "$repo/bin/reconcile" ]] || { echo "ERROR developer checkout reconcile is missing: $repo/bin/reconcile" >&2; exit 1; }
   echo "global-tools: source=checkout (developer mode)"
   reconcile_dir="$repo/bin"
 else
   os="$(uname -s)"
   arch="$(uname -m)"
-  case "$os" in
-    Darwin) npm_path=/opt/homebrew/bin:/usr/bin:/bin ;;
-    Linux) npm_path=/home/linuxbrew/.linuxbrew/bin:/usr/bin:/bin ;;
-    *) echo "unsupported operating system for npm package: $os" >&2; exit 1 ;;
-  esac
-  npm_env=(PATH="$npm_path")
-  if [[ "$os" == Linux ]]; then npm_env=(npm_config_prefix=/usr/local PATH="$npm_path"); fi
-  npm_root="$(sudo -u "$owner" -H env "${npm_env[@]}" npm root -g)" || {
-    echo "cannot resolve the global npm root as $owner" >&2
-    exit 1
-  }
-  [[ "$npm_root" == /*/lib/node_modules ]] || {
-    echo "global npm root has an unsupported path: $npm_root" >&2
+  owner_home="$(adl_owner_home "$owner")" || {
+    echo "ERROR cannot resolve the home directory of $owner" >&2
     exit 1
   }
-  npm_prefix="${npm_root%/lib/node_modules}"
-  platform_dir="$(npm_platform_package_dir "$npm_root" "$os" "$arch")" || exit 1
+  global_node_modules="$(adl_global_node_modules "$owner_home")"
+  platform_dir="$(adl_platform_package_dir "$global_node_modules" "$os" "$arch")" || exit 1
   installed_manifest="$platform_dir/packages/fleet/manifest.json"
   package_spec=""
+  update_policy=""
+  installed_version=""
   if [[ -f "$installed_manifest" ]]; then
+    [[ -f "$platform_dir/package.json" ]] && installed_version="$(jq -er '.version | select(type == "string")' "$platform_dir/package.json")" || {
+      echo "ERROR installed adl package has no readable version: $platform_dir/package.json" >&2
+      exit 1
+    }
     update_policy="$(jq -er '.config.update_policy | select(type == "string")' "$installed_manifest")" || {
-      echo "installed adl package manifest has no config.update_policy: $installed_manifest" >&2
+      echo "ERROR installed adl package manifest has no config.update_policy: $installed_manifest" >&2
       exit 1
     }
     case "$update_policy" in
-      latest-stable) package_spec="$(npm_package_spec latest-stable)" ;;
+      latest-stable) package_spec="$(adl_package_spec latest-stable)" ;;
       pinned)
         pinned_version="$(jq -er --arg platform "$host_platform" '.[$platform].common.tools.adl.version | select(type == "string")' "$installed_manifest")" || {
-          echo "installed adl package manifest requires a version for pinned update_policy: $installed_manifest" >&2
+          echo "ERROR installed adl package manifest requires a version for pinned update_policy: $installed_manifest" >&2
           exit 1
         }
-        package_spec="$(npm_package_spec pinned "$pinned_version")" || exit 1
+        package_spec="$(adl_package_spec pinned "$pinned_version")" || exit 1
         ;;
-      *) package_spec="$(npm_package_spec "$update_policy")" || exit 1 ;;
+      *) package_spec="$(adl_package_spec "$update_policy")" || exit 1 ;;
     esac
   else
-    package_spec="$(npm_package_spec latest-stable)"
-    echo "global-tools: bootstrapping adl package from npm latest tag"
+    package_spec="$(adl_package_spec latest-stable)"
+    echo "global-tools: bootstrapping adl package from the registry latest tag"
   fi
 
   if [[ -n "${SYNC_AND_RECONCILE_TEST_ROOT:-}" ]]; then
@@ -198,18 +184,43 @@ else
   fi
   prepare_adl_npm_migration "$applied_manifest" "$device" "$host_platform" "$legacy_adl" "$legacy_hash"
 
-  sudo -u "$owner" -H env "${npm_env[@]}" npm install --global --prefix "$npm_prefix" --no-audit --no-fund "$package_spec"
-  [[ -d "$platform_dir" ]] || { echo "npm install did not create the platform package: $platform_dir" >&2; exit 1; }
+  # NEVER DOWNGRADE (Tarun, 2026-10-01): under latest-stable the installed package is
+  # compared with the registry's `latest` first. Newer installed (a local pre-release
+  # build) and equal are kept; only an older one is updated. A lookup that fails stops
+  # the run loudly. A first install has nothing to compare, and a pinned policy installs
+  # exactly its pin.
+  skip_install=0
+  if [[ -n "$installed_version" && "$update_policy" == latest-stable ]]; then
+    registry_latest="$(adl_registry_latest "$owner" "$os" "$owner_home")" || {
+      echo "ERROR cannot read the registry latest of $adl_wrapper_package; not updating and not reconciling (run again when the registry is reachable)" >&2
+      exit 1
+    }
+    version_order="$(adl_semver_compare "$installed_version" "$registry_latest")" || exit 1
+    case "$version_order" in
+      1)
+        echo "global-tools: installed $installed_version is newer than registry latest $registry_latest; keeping it"
+        skip_install=1
+        ;;
+      0)
+        echo "global-tools: installed $installed_version is already the registry latest; no update needed"
+        skip_install=1
+        ;;
+      *) echo "global-tools: updating adl package $installed_version -> $registry_latest" ;;
+    esac
+  fi
+  if [[ "$skip_install" -eq 0 ]]; then
+    adl_bun_add_global "$owner" "$os" "$owner_home" "$package_spec"
+  fi
+  [[ -d "$platform_dir" ]] || { echo "ERROR bun add did not create the platform package: $platform_dir" >&2; exit 1; }
   installed_manifest="$platform_dir/packages/fleet/manifest.json"
-  [[ -f "$installed_manifest" ]] || { echo "installed adl package manifest missing: $installed_manifest" >&2; exit 1; }
-  [[ -x "$platform_dir/bin/reconcile" ]] || { echo "installed adl package reconcile is missing: $platform_dir/bin/reconcile" >&2; exit 1; }
-  [[ -x "$platform_dir/bin/sync-and-reconcile" ]] || { echo "installed adl package scheduler is missing: $platform_dir/bin/sync-and-reconcile" >&2; exit 1; }
-  [[ -x "$platform_dir/bin/validate-manifest" ]] || { echo "installed adl package manifest validator is missing: $platform_dir/bin/validate-manifest" >&2; exit 1; }
-  "$platform_dir/bin/validate-manifest" "$installed_manifest"
-  install -m 0755 "$platform_dir/bin/sync-and-reconcile" "$scheduler_path.new"
-  mv "$scheduler_path.new" "$scheduler_path"
+  [[ -f "$installed_manifest" ]] || { echo "ERROR installed adl package manifest missing: $installed_manifest" >&2; exit 1; }
+  # bun leaves every shipped file but the `bin` targets 0644, so the package's
+  # scripts are checked with -f and run through bash, never executed directly.
+  [[ -f "$platform_dir/bin/reconcile" ]] || { echo "ERROR installed adl package reconcile is missing: $platform_dir/bin/reconcile" >&2; exit 1; }
+  [[ -f "$platform_dir/bin/validate-manifest" ]] || { echo "ERROR installed adl package manifest validator is missing: $platform_dir/bin/validate-manifest" >&2; exit 1; }
+  bash "$platform_dir/bin/validate-manifest" "$installed_manifest"
   reconcile_dir="$platform_dir/bin"
 fi
 
-PATH="$reconcile_dir:$PATH" "$reconcile_dir/reconcile" \
+PATH="$reconcile_dir:$PATH" bash "$reconcile_dir/reconcile" \
   --device "$device" --source "$sync_source" --mode "$mode"