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

package/bin/adl

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/bin/adl
-size: 82949600 bytes
-sha256: b0711f880f163524abb11d00eb61e134b582627c11fe70bb96ea2d91133b3fbb
+size: 82912736 bytes
+sha256: 1a2ae55423977502b4d00c4c8ba08eac8d3c2d4d9388c934b0ea1f7ff80efe72

package/bin/git

@@ -117,7 +117,7 @@ done
 (( command_index >= 0 )) || exec "$real_git" ${args[@]+"${args[@]}"}
 command_name="${args[command_index]}"
 
-# L1 worktree guard (STATUS.md item 2, docs/operations/worktree-guard.md): refuse
+# L1 worktree guard (docs/operations/worktree-guard.md): refuse
 # `git worktree add` when the repository already has 3 checkouts, including
 # the main folder. Runs BEFORE the network-command routing below because it
 # applies to every command line, not only Azure DevOps ones, and to humans
@@ -567,22 +567,21 @@ case "$command_name" in
     done
     ;;
   lfs)
-    # GAP (second independent review, 2026-09-29), fix REVISED (third
-    # independent review, 2026-09-29, item 3): `git lfs push|pull|fetch`
-    # against an Azure DevOps remote used to reach the real `git-lfs`
-    # binary (a SEPARATE executable git dispatches to via PATH, never
-    # through THIS controller's own real_git exec) with no identity at all.
-    # The FIRST fix refused this outright here in bin/git -- but that also
-    # refused it in Tarun's OWN marked human terminal, a regression: his
-    # real credential helper has always handled `git lfs` fine, and the
-    # human path never involved git-ado's unverified header mechanism in
-    # the first place. Routing through git-ado instead lets IT apply the
-    # SAME policy it applies to every other verb: human (TTY+marker) passes
-    # through unchanged (unaffected by any of this); the agent identity
-    # path refuses with a clear message (git-lfs's own HTTP credential
-    # resolution has not been verified to honor git-ado's
-    # `http.<url>.extraHeader` mechanism); no identity and no human marker
-    # refuses, exactly as for every other verb.
+    # GAP (second independent review, 2026-09-29): `git lfs push|pull|fetch`
+    # against an Azure DevOps remote reaches the real `git-lfs` binary (a
+    # SEPARATE executable git dispatches to via PATH, never through THIS
+    # controller's own real_git exec) with no identity at all, so it is routed
+    # through git-ado like every other network verb. git-ado applies the one
+    # policy: human (TTY+marker) passes through unchanged; an agent identity
+    # authenticates with the same `http.<url>.extraHeader` GIT_CONFIG_*
+    # mechanism as `git push` (proved to be honored by git-lfs, with no fallback
+    # to the human credential helper, in packages/repo-controls/tests/
+    # lfs-credential-boundary.test.ts -- it was refused for agents until that
+    # proof existed); no identity and no human marker is refused, as for every
+    # other verb. Other `git lfs` subcommands -- notably `pre-push`,
+    # `post-checkout`, `post-commit` and `post-merge`, which the projected hooks
+    # run inside a `git push` that already carries the header -- never reach
+    # the network through here and are not routed.
     lfs_sub=''
     lfs_sub_index=-1
     for ((index = command_index + 1; index < ${#args[@]}; index += 1)); do

package/bin/git-ado

@@ -15,16 +15,17 @@
 # three Entra service principals: agent-tarun, agent-vivek, agent-reviewer.
 # Agents never see a secret.
 #
-#   HUMAN PATH (STATUS.md 12p decision 1: fail closed, the human opts in).
+#   HUMAN PATH (fail closed: the human opts in; Tarun, 2026-09-29).
 #   An unset/empty ADL_AGENT_ID_AGENT is passed through to the human's own
 #   credential helper (Git Credential Manager, etc.) ONLY when BOTH stdin is
 #   a real terminal AND ADL_HUMAN_AZDO is the exact string "1" -- Tarun
-#   exports it from his own `.zshrc` (decision 1c: "its not only git, its
-#   azdo" -- the marker governs every human Azure DevOps path, not only this
-#   script). Otherwise this script refuses outright, by name, before
+#   exports it from his own `.zshrc` ("its not only git, its azdo": the
+#   marker governs every human Azure DevOps path, not only this script;
+#   `adl run` strips it from a child's environment and the adl hook denies
+#   any agent command that sets it). Otherwise this script refuses outright, by name, before
 #   touching git at all: the earlier "unset means human" rule relied
 #   entirely on the adl hook denying an agent's Azure DevOps network git
-#   command that omits ADL_AGENT_ID_AGENT (H2 rule 1) -- a host the hook
+#   command that omits ADL_AGENT_ID_AGENT -- a host the hook
 #   cannot rewrite on, or a chained/opaque shell shape the hook's walker
 #   misses, reached THIS script with no agent identity and no TTY, and used
 #   to be treated as human regardless. `adl id whoami`
@@ -311,10 +312,10 @@ ado_host="$(printf '%s' "$remote_url" | tr '[:upper:]' '[:lower:]')"
 ado_host="${ado_host#https://}"
 ado_host="${ado_host%%/*}"
 
-# HUMAN PASS-THROUGH (STATUS.md 12p decision 1: fail closed, the human opts
-# in). Unset or empty ADL_AGENT_ID_AGENT passes through to the real git
+# HUMAN PASS-THROUGH (fail closed: the human opts in; Tarun, 2026-09-29).
+# Unset or empty ADL_AGENT_ID_AGENT passes through to the real git
 # UNCHANGED only when this is also a marked human terminal: stdin is a real
-# tty AND ADL_HUMAN_AZDO is the exact string "1" (decision 1b/1c). Anything
+# tty AND ADL_HUMAN_AZDO is the exact string "1". Anything
 # else with no agent identity -- no marker, no tty, or both -- is refused
 # outright, by name, before touching git at all. This is the ONE place that
 # check is made in bash; `isMarkedHumanAzdoCaller` in
@@ -333,22 +334,22 @@ fi
 # AGENT PATH.
 require_agent_identity "$ADL_AGENT_ID_AGENT" || exit 1
 
-# THIRD independent review (2026-09-29), item 3: `git lfs push|pull|fetch`
-# reaches here too now that `is_network_command_name` includes `lfs` (fixing
-# the live bug above) -- but git-lfs is a SEPARATE binary whose HTTP
-# credential resolution has not been verified to honor the
-# `http.<url>.extraHeader` mechanism the agent path below relies on (unlike
-# git itself, which this script's own tests prove reads it). Minting a
-# token and injecting a header git-lfs might silently ignore -- falling
-# back to ITS OWN Basic-auth `git credential fill` flow, bypassing the
-# identity model entirely -- is worse than refusing outright. The human
-# path above is UNAFFECTED: it execs the real git unchanged regardless of
-# `$git_command`, exactly like every other verb, so Tarun's own marked
-# terminal keeps using `git lfs` via his real credential helper as before.
-if [[ "$git_command" == "lfs" ]]; then
-  printf 'git-ado: git lfs against Azure DevOps remote %s is refused for the agent identity path (fail closed): git-lfs is a separate binary whose HTTP credential resolution has not been verified to honor this header mechanism. Run the underlying git fetch/push through git-ado directly, or ask Tarun to confirm LFS support before removing this refusal.\n' "$remote_url" >&2
-  exit 1
-fi
+# `git lfs push|pull|fetch` reaches here too (`is_network_command_name`
+# includes `lfs`) and takes the SAME agent path as every other verb. It used to
+# be refused (independent review, 2026-09-29, item 3) because git-lfs is a
+# SEPARATE binary whose HTTP credential resolution had never been verified to
+# honor the `http.<url>.extraHeader` mechanism below; if it ignored the header
+# it would fall back to `git credential fill`, i.e. Git Credential Manager,
+# i.e. the HUMAN. That doubt is settled by a test, not an assumption:
+# packages/repo-controls/tests/lfs-credential-boundary.test.ts runs real
+# git-lfs (3.8.0) against a local LFS endpoint that requires the Bearer token
+# and a credential helper that records every call, with exactly this
+# GIT_CONFIG_COUNT/KEY_n/VALUE_n mechanism: every request carried the header
+# and the helper was never called (and, as the control, was called when the
+# header was absent). The same proof covers the pre-push hook's
+# `git lfs pre-push` (packages/repo-controls/src/lfs.ts), which inherits this
+# environment from the `git push` this script runs. Had it failed, this would
+# still be a refusal; it must become one again if that test ever goes red.
 
 # adl-agent-id mints the session and runs `agent-vault run -- <child>`. The
 # child asks `adl id token` for this agent's Entra token over the proxy

package/bin/git-defaults

@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+# Managed by adl global-tools.
+#
+# Every host's human git setup is identical and kept that way by the 12-hourly
+# reconcile (Tarun, 2026-10-01): no manual `git config` on any machine. This
+# script sets the administrator's GLOBAL git config from the manifest:
+#
+#   config.git_global_config                    shared by every host
+#   <platform>.common.git_global_config         added for that platform only
+#   <platform>.devices.<device>.git_user        user.name / user.email
+#
+# A value is a string (single-valued key) or an ordered array of strings
+# (multi-valued key: the empty-reset-then-helper pattern of credential.helper).
+# A key is rewritten only when its current values differ from the declared
+# ordered list: single-valued via `git config --global KEY VALUE`, multi-valued
+# via `--unset-all` then `--add` for each value in order. Keys the manifest does
+# not declare (including any GitHub or gist credential helper a human set) are
+# never read, changed or removed.
+#
+# Git Credential Manager is installed by the human (macOS: `brew install --cask
+# git-credential-manager`; Linux: the .deb or tarball) -- reconcile never
+# installs it. The one placeholder a value may carry, {git-credential-manager},
+# is resolved at run time as the administrator (`command -v` on the explicit
+# PATH below, which covers /usr/local/bin, /usr/local/share/gcm-core and the
+# Homebrew/linuxbrew bins). When it is not installed, every key that needs it is
+# skipped and left as it is, with one loud WARN; the next reconcile after the
+# install sets it. Nothing is ever written that points at a missing executable.
+#
+# Headless Linux has no keychain, so the manifest's Linux common config sets
+# GCM's credentialStore=cache (an in-memory credential cache daemon) with a
+# one-week timeout instead of the macOS keychain.
+#
+# Git runs as the administrator (`sudo -u ADMIN -H env PATH=... git ...`) so
+# ~/.gitconfig stays user-owned. Apply is invoked by bin/reconcile as root. Plan
+# mode only reads, through sudo when run as root and as the caller otherwise.
+set -euo pipefail
+
+usage() {
+  echo 'usage: git-defaults --manifest FILE --platform mac|linux --device NAME --mode plan|apply --administrator USER [--path-dirs DIR:DIR...]' >&2
+  exit 2
+}
+
+manifest=''
+platform=''
+device=''
+mode=''
+administrator=''
+# /usr/local/share/gcm-core comes first so a macOS cask install resolves to the
+# real GCM path rather than its /usr/local/bin symlink. --path-dirs exists for
+# tests; a real run never passes it.
+path_dirs='/usr/local/share/gcm-core:/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/bin:/bin:/usr/sbin:/sbin'
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --manifest) manifest="${2:-}"; shift 2 ;;
+    --platform) platform="${2:-}"; shift 2 ;;
+    --device) device="${2:-}"; shift 2 ;;
+    --mode) mode="${2:-}"; shift 2 ;;
+    --administrator) administrator="${2:-}"; shift 2 ;;
+    --path-dirs) path_dirs="${2:-}"; shift 2 ;;
+    *) usage ;;
+  esac
+done
+[[ -n "$manifest" && -f "$manifest" ]] || usage
+[[ "$platform" == mac || "$platform" == linux ]] || usage
+[[ -n "$device" && -n "$administrator" && -n "$path_dirs" ]] || usage
+[[ "$mode" == plan || "$mode" == apply ]] || usage
+
+as_administrator() {
+  if [[ "$mode" == apply || "$(id -u)" -eq 0 ]]; then
+    (cd /tmp && sudo -u "$administrator" -H env PATH="$path_dirs" "$@" </dev/null)
+  else
+    (cd /tmp && env PATH="$path_dirs" "$@" </dev/null)
+  fi
+}
+
+scratch="$(mktemp -d "${TMPDIR:-/tmp}/git-defaults.XXXXXX")"
+trap 'rm -rf -- "$scratch"' EXIT
+
+# Current values of $1 into the global `current` array, in file order. Exit 1
+# from git means the key is unset; any other failure is real and propagates.
+read_current() {
+  local key="$1" rc=0 value
+  current=()
+  as_administrator git config --global -z --get-all "$key" >"$scratch/values" || rc=$?
+  if [[ "$rc" -eq 1 ]]; then
+    return 0
+  fi
+  [[ "$rc" -eq 0 ]] || { echo "ERROR git-config: git config --global --get-all $key failed (exit $rc)" >&2; return "$rc"; }
+  while IFS= read -r -d '' value; do
+    current+=("$value")
+  done <"$scratch/values"
+}
+
+gcm_path=''
+gcm_resolved=0
+resolve_gcm() {
+  [[ "$gcm_resolved" -eq 0 ]] || return 0
+  gcm_resolved=1
+  local found rc=0
+  found="$(as_administrator sh -c 'command -v git-credential-manager')" || rc=$?
+  if [[ "$rc" -eq 0 && "$found" == /* ]]; then
+    gcm_path="$found"
+    return 0
+  fi
+  echo "WARN git-config: git-credential-manager not installed on $device; credential helper not changed (install it, then the next reconcile sets it)" >&2
+}
+
+declared="$(jq -r --arg platform "$platform" --arg device "$device" '
+  . as $m
+  | ($m[$platform].devices[$device].git_user // error("git-config: device \($device) has no git_user in the manifest")) as $user
+  | ($m.config.git_global_config + ($m[$platform].common.git_global_config // {})
+     + {"user.name": $user.name, "user.email": $user.email})
+  | to_entries[]
+  | [.key, (.value | if type == "array" then . else [.] end | tojson)]
+  | @tsv
+' "$manifest")"
+
+changed=0
+while IFS=$'\t' read -r key values_json; do
+  [[ -n "$key" ]] || continue
+  wanted=()
+  needs_gcm=0
+  while IFS= read -r value; do
+    [[ "$value" != *'{git-credential-manager}'* ]] || needs_gcm=1
+    wanted+=("$value")
+  done < <(jq -r '.[]' <<<"$values_json")
+  if [[ "$needs_gcm" -eq 1 ]]; then
+    resolve_gcm
+    [[ -n "$gcm_path" ]] || continue
+    for index in "${!wanted[@]}"; do
+      wanted[index]="${wanted[index]//'{git-credential-manager}'/"$gcm_path"}"
+    done
+  fi
+
+  read_current "$key"
+  same=0
+  if [[ "${#current[@]}" -eq "${#wanted[@]}" ]]; then
+    same=1
+    for index in "${!wanted[@]}"; do
+      [[ "${current[index]}" == "${wanted[index]}" ]] || same=0
+    done
+  fi
+  if [[ "$same" -eq 1 ]]; then
+    echo "git-config: already set $key"
+    continue
+  fi
+
+  if [[ "${#wanted[@]}" -eq 1 ]]; then
+    shown="${wanted[0]}"
+  else
+    shown="$(jq -nc '$ARGS.positional' --args -- "${wanted[@]}")"
+  fi
+  if [[ "$mode" != apply ]]; then
+    echo "git-config: would set $key=$shown"
+    continue
+  fi
+  if [[ "${#wanted[@]}" -eq 1 && "${#current[@]}" -le 1 ]]; then
+    as_administrator git config --global "$key" "${wanted[0]}"
+  else
+    if [[ "${#current[@]}" -gt 0 ]]; then
+      as_administrator git config --global --unset-all "$key"
+    fi
+    for value in "${wanted[@]}"; do
+      as_administrator git config --global --add "$key" "$value"
+    done
+  fi
+  echo "git-config: set $key=$shown"
+  changed=$((changed + 1))
+done <<<"$declared"
+
+if [[ "$mode" == apply ]]; then
+  echo "git-config: $changed key(s) changed on $device"
+fi

package/bin/health-check

@@ -21,7 +21,14 @@ case "$device" in
       grep -q 'state = running'
     ;;
   hostinger-vps-1)
-    systemctl is-active --quiet docker tailscaled enact-agent-vault
+    # One unit per call: `systemctl is-active` given several units exits 0 when at
+    # least one is active, so a combined call cannot see a single unit being down.
+    for unit_name in docker tailscaled; do
+      systemctl is-active --quiet "$unit_name" || {
+        echo "required service is not active: $unit_name" >&2
+        exit 1
+      }
+    done
     for container_name in nordvpn-exit-gluetun-1 nordvpn-exit-tailscale-1 traefik-traefik-1; do
       [[ "$(docker inspect -f '{{.State.Running}}' "$container_name" 2>/dev/null)" == true ]] || {
         echo "required container is not running: $container_name" >&2

package/bin/kimi-hooks

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-export PATH="/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+export PATH="/usr/local/bin:${HOME:-}/.bun/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"
 
 script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 repo_root="$(cd "$script_dir/.." && pwd)"

package/bin/lib/adl-package.sh

@@ -0,0 +1,257 @@
+# Where the published adl package lives on a host, and how to prove it is the
+# `adl` the owner gets. Sourced (never executed) by bin/sync-and-reconcile,
+# bin/setup, bin/reconcile-host and bin/reconcile, so the scheduled job, the
+# onboarding command and the reconcile itself all ask the same question the
+# same way.
+#
+# Hosts install with bun (Tarun, 2026-10-01): `bun install -g
+# @amsterdamdatalabs/adl-agent-control`, run as the device's `administrator`.
+# Measured with bun 1.4.2 (packages: workflows/scripts/release/tests/
+# bun-global-install.test.ts): bun HOISTS the platform package as a SIBLING of
+# the wrapper, unlike npm, which nests it inside the wrapper:
+#
+#   $HOME/.bun/install/global/node_modules/@amsterdamdatalabs/
+#     adl-agent-control/                 the wrapper (bin/adl.js)
+#     adl-agent-control-<os>-<arch>/     the platform package this job runs from
+#   $HOME/.bun/bin/adl                   -> the wrapper's bin/adl.js
+#
+# bun marks ONLY `bin`-field targets executable; every other shipped file stays
+# 0644, so nothing here ever executes a shipped script directly (always
+# `bash <script>`) or checks it with -x.
+#
+# The owner's bun is found through Homebrew (macOS /opt/homebrew, Linux
+# /home/linuxbrew/.linuxbrew), exactly as the owner's other global tools are.
+
+adl_wrapper_package='@amsterdamdatalabs/adl-agent-control'
+
+adl_brew_bin_dir() {
+  case "$1" in
+    Darwin) printf '%s\n' /opt/homebrew/bin ;;
+    Linux) printf '%s\n' /home/linuxbrew/.linuxbrew/bin ;;
+    *) echo "ERROR unsupported operating system for the adl package: $1" >&2; return 1 ;;
+  esac
+}
+
+# PATH for the bun calls the job makes as the owner (install, nothing else).
+adl_bun_path() {
+  local brew
+  brew="$(adl_brew_bin_dir "$1")" || return 1
+  printf '%s:/usr/bin:/bin\n' "$brew"
+}
+
+# PATH the owner gets when it runs `adl` (the repo step, and the shadow check).
+# /usr/local/bin stays FIRST: git must resolve to the managed front controller,
+# which routes Azure DevOps traffic through the agent identity; Homebrew's git
+# would bypass it. The owner's bun bin directory comes next, then Homebrew.
+adl_owner_path() {
+  local os="$1" home="$2" brew
+  brew="$(adl_brew_bin_dir "$os")" || return 1
+  printf '/usr/local/bin:%s/.bun/bin:%s:/usr/bin:/bin\n' "${home%/}" "$brew"
+}
+
+# The owner's home directory, asked of the owner (never guessed from the name).
+adl_owner_home() {
+  local owner="$1" home
+  home="$(cd /tmp && sudo -u "$owner" -H /bin/sh -c 'printf "%s" "$HOME"')" || return 1
+  [[ "$home" == /* ]] || { echo "ERROR cannot resolve the home directory of $owner" >&2; return 1; }
+  printf '%s\n' "${home%/}"
+}
+
+# bun's global package directory for an owner home. `bun pm bin -g` errors on a
+# host that has never run `bun add -g`, so the path is derived, and pinned in
+# the install call below with an explicit BUN_INSTALL.
+adl_global_node_modules() {
+  printf '%s/.bun/install/global/node_modules\n' "${1%/}"
+}
+
+adl_platform_package_dir() {
+  local global_node_modules="$1" os="$2" arch="$3" platform
+  case "$os:$arch" in
+    Darwin:arm64) platform=darwin-arm64 ;;
+    Linux:x86_64) platform=linux-x64 ;;
+    *) echo "ERROR unsupported platform for the adl package: $os $arch" >&2; return 1 ;;
+  esac
+  # bun hoists the platform package next to the wrapper; it is not nested.
+  printf '%s/%s-%s\n' "${global_node_modules%/}" "$adl_wrapper_package" "$platform"
+}
+
+# Real path of a file, following every symlink (macOS has no `readlink -f` on
+# older releases, and the owner's command is always a symlink).
+adl_realpath() {
+  local path="$1" link dir
+  while [[ -L "$path" ]]; do
+    link="$(readlink "$path")" || return 1
+    case "$link" in
+      /*) path="$link" ;;
+      *) path="$(dirname -- "$path")/$link" ;;
+    esac
+  done
+  dir="$(cd -P -- "$(dirname -- "$path")" 2>/dev/null && pwd -P)" || return 1
+  printf '%s/%s\n' "$dir" "$(basename -- "$path")"
+}
+
+# The registry's `latest` for the package, asked of the owner. `bun pm view`
+# needs a package.json in its working directory (measured with bun 1.4.2), and the
+# owner's bun global directory always has one once the package is installed.
+# Prints the version, or an error and a non-zero status: a failed lookup is never
+# guessed around.
+adl_registry_latest() {
+  local owner="$1" os="$2" home="$3" bun_path answer
+  bun_path="$(adl_bun_path "$os")" || return 1
+  answer="$(sudo -u "$owner" -H env PATH="$bun_path" BUN_INSTALL="${home%/}/.bun" /bin/sh -c 'cd "$1" && bun pm view "$2" version' sh "${home%/}/.bun/install/global" "$adl_wrapper_package")" || return 1
+  answer="$(printf '%s' "$answer" | tr -d '[:space:]')"
+  [[ "$answer" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]] || {
+    echo "ERROR the registry answered '$answer' for $adl_wrapper_package, which is not a release version" >&2
+    return 1
+  }
+  printf '%s\n' "$answer"
+}
+
+# Compares two release versions (x.y.z with an optional -prerelease): prints -1, 0
+# or 1 for A older than, equal to, or newer than B. Semver ordering: components
+# numerically (0.1.9 < 0.1.10), a pre-release is older than its release, and
+# pre-release identifiers compare numerically when both are numbers, numbers
+# before words, else by text. A value that is not a version is an error.
+adl_semver_compare() {
+  local a="$1" b="$2" re='^([0-9]+)\.([0-9]+)\.([0-9]+)(-([0-9A-Za-z.-]+))?$' i x y pre_a pre_b
+  local -a core_a core_b ids_a ids_b
+  [[ "$a" =~ $re ]] || { echo "ERROR not a release version: '$a'" >&2; return 1; }
+  core_a=("${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}" "${BASH_REMATCH[3]}")
+  pre_a="${BASH_REMATCH[5]:-}"
+  [[ "$b" =~ $re ]] || { echo "ERROR not a release version: '$b'" >&2; return 1; }
+  core_b=("${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}" "${BASH_REMATCH[3]}")
+  pre_b="${BASH_REMATCH[5]:-}"
+  for i in 0 1 2; do
+    if ((10#${core_a[i]} > 10#${core_b[i]})); then printf '1\n'; return 0; fi
+    if ((10#${core_a[i]} < 10#${core_b[i]})); then printf -- '-1\n'; return 0; fi
+  done
+  if [[ -z "$pre_a" && -z "$pre_b" ]]; then printf '0\n'; return 0; fi
+  if [[ -z "$pre_a" ]]; then printf '1\n'; return 0; fi
+  if [[ -z "$pre_b" ]]; then printf -- '-1\n'; return 0; fi
+  IFS=. read -r -a ids_a <<<"$pre_a"
+  IFS=. read -r -a ids_b <<<"$pre_b"
+  for ((i = 0; i < ${#ids_a[@]} || i < ${#ids_b[@]}; i++)); do
+    if ((i >= ${#ids_a[@]})); then printf -- '-1\n'; return 0; fi
+    if ((i >= ${#ids_b[@]})); then printf '1\n'; return 0; fi
+    x="${ids_a[i]}"
+    y="${ids_b[i]}"
+    if [[ "$x" =~ ^[0-9]+$ && "$y" =~ ^[0-9]+$ ]]; then
+      if ((10#$x > 10#$y)); then printf '1\n'; return 0; fi
+      if ((10#$x < 10#$y)); then printf -- '-1\n'; return 0; fi
+    elif [[ "$x" =~ ^[0-9]+$ ]]; then
+      printf -- '-1\n'; return 0
+    elif [[ "$y" =~ ^[0-9]+$ ]]; then
+      printf '1\n'; return 0
+    elif [[ "$x" < "$y" ]]; then
+      printf -- '-1\n'; return 0
+    elif [[ "$x" > "$y" ]]; then
+      printf '1\n'; return 0
+    fi
+  done
+  printf '0\n'
+}
+
+# Runs `bun add --global SPEC` as the owner, pinned to the owner's ~/.bun.
+adl_bun_add_global() {
+  local owner="$1" os="$2" home="$3" spec="$4" bun_path
+  bun_path="$(adl_bun_path "$os")" || return 1
+  # cd /tmp: the caller's working directory may be unreadable to the owner (root's home), and sudo then fails.
+  (cd /tmp && sudo -u "$owner" -H env PATH="$bun_path" BUN_INSTALL="${home%/}/.bun" bun add --global "$spec")
+}
+
+# The `adl` the owner gets must be THIS package: a different one earlier on the
+# owner's PATH (a legacy compiled /usr/local/bin/adl from before the package
+# existed is the real case) would keep running instead of the package the job
+# keeps up to date. Accepts the package's own bin/adl, or the wrapper's
+# bin/adl.js that sits beside it (the link `bun install -g` puts on PATH).
+#   adl_check_adl_not_shadowed OWNER OS OWNER_HOME PACKAGE_REAL_DIR CONTEXT
+adl_check_adl_not_shadowed() {
+  local owner="$1" os="$2" home="$3" package_real="$4" context="$5" path resolved real wrapper_real
+  path="$(adl_owner_path "$os" "$home")" || return 1
+  resolved="$(cd /tmp && sudo -u "$owner" -H env PATH="$path" /bin/sh -c 'command -v adl' 2>/dev/null)" || resolved=""
+  if [[ -z "$resolved" ]]; then
+    {
+      echo "ERROR $context: $owner has no 'adl' on PATH ($path)."
+      echo "ERROR $context: expected ${home%/}/.bun/bin/adl from: bun install -g $adl_wrapper_package (run as $owner)"
+    } >&2
+    return 1
+  fi
+  real="$(adl_realpath "$resolved")" || real="$resolved"
+  wrapper_real="$(adl_realpath "$(dirname -- "$package_real")/$(basename -- "$adl_wrapper_package")/bin/adl.js" 2>/dev/null)" || wrapper_real=""
+  if [[ "$real" == "$package_real/bin/adl" || ( -n "$wrapper_real" && "$real" == "$wrapper_real" ) ]]; then
+    return 0
+  fi
+  {
+    echo "ERROR $context: $owner's 'adl' is $resolved (-> $real), not this package's ($package_real/bin/adl)."
+    echo "ERROR $context: a different adl shadows the package, so the job would keep updating one adl while $owner runs another."
+    echo "ERROR $context: move it aside (never delete it), then run this again:"
+    echo "ERROR $context:   sudo mv $resolved $resolved.legacy-$(date +%Y%m%d)"
+  } >&2
+  return 1
+}
+
+# ---------------------------------------------------------------------------------------------
+# The two reconcile locks (/var/run/adl-reconcile.lock, /var/run/adl-sync.lock) are mkdir locks.
+# A run that is killed or hangs used to leave the directory behind, and every later `adl setup` /
+# `adl reconcile` then refused "another reconcile is running" forever (m5, 2026-10-01). The holder
+# now records its pid and start time in the lock directory:
+#   - pid running with the same start time -> refused, naming the pid;
+#   - pid gone, or running with a different start time (the pid was reused) -> stale;
+#   - no pid file (the old format, or a holder killed between mkdir and the write) -> stale only
+#     when older than the longest a run may take, 3 hours (the systemd unit's TimeoutStartSec).
+# A stale lock is renamed aside and only then re-created with mkdir, so two takers cannot both win.
+# Prints WARN on stderr when it takes over; returns 1 (after an ERROR naming the holder) when the
+# lock is held. The caller removes the directory on exit.
+#   adl_lock_acquire LOCK_DIR "what is running" 
+adl_lock_max_age_seconds=10800
+
+adl_lock_start_time() {
+  ps -p "$1" -o lstart= 2>/dev/null | sed -e 's/^ *//' -e 's/ *$//'
+}
+
+adl_lock_mtime() {
+  stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null
+}
+
+adl_lock_write_holder() {
+  printf '%s\n' "$$" >"$1/pid"
+  printf '%s\n' "$(adl_lock_start_time "$$")" >"$1/started"
+}
+
+adl_lock_acquire() {
+  local lock="$1" running="$2" pid="" recorded_start="" actual_start reason="" now mtime aside
+  if mkdir "$lock" 2>/dev/null; then
+    adl_lock_write_holder "$lock"
+    return 0
+  fi
+  [[ -d "$lock" ]] && pid="$(tr -d '[:space:]' 2>/dev/null <"$lock/pid" || true)"
+  if [[ "$pid" =~ ^[0-9]+$ ]]; then
+    if kill -0 "$pid" 2>/dev/null; then
+      recorded_start="$(tr -d '\n' <"$lock/started" 2>/dev/null | sed -e 's/^ *//' -e 's/ *$//' || true)"
+      actual_start="$(adl_lock_start_time "$pid")"
+      if [[ -z "$recorded_start" || "$recorded_start" == "$actual_start" ]]; then
+        echo "ERROR $running (lock: $lock, pid $pid)" >&2
+        return 1
+      fi
+    fi
+    reason="pid $pid not running"
+  else
+    now="$(date +%s)"
+    mtime="$(adl_lock_mtime "$lock")" || mtime="$now"
+    if (( now - mtime < adl_lock_max_age_seconds )); then
+      echo "ERROR $running (lock: $lock, no pid recorded; it is treated as stale after 3h)" >&2
+      return 1
+    fi
+    reason="no pid recorded, older than 3h"
+  fi
+  echo "WARN adl reconcile: removing stale lock $lock ($reason)" >&2
+  aside="$lock.stale.$$"
+  mv -- "$lock" "$aside" 2>/dev/null || true
+  command rm -rf -- "$aside"
+  if mkdir "$lock" 2>/dev/null; then
+    adl_lock_write_holder "$lock"
+    return 0
+  fi
+  echo "ERROR $running (lock: $lock, taken by another run while removing the stale one)" >&2
+  return 1
+}

package/bin/lib/fleet-host.sh

@@ -10,8 +10,9 @@
 #
 # fleet_host_resolve COMMAND MANIFEST HOST
 #   On success sets fleet_host_platform (mac|linux), fleet_host_owner,
-#   fleet_host_minute and fleet_host_repo_location (empty when the device
-#   declares none). On failure prints one `ERROR COMMAND: ...` line to stderr
+#   fleet_host_minute, fleet_host_repo_location (empty when the device
+#   declares none) and fleet_host_branch_max_age_days (the manifest's
+#   config.repo_maintain.branch_max_age_days; empty when the manifest has none). On failure prints one `ERROR COMMAND: ...` line to stderr
 #   and returns 2 (unknown host) or 1 (unreadable manifest, bad entry, or the
 #   host belongs to the other operating system).
 
@@ -22,13 +23,15 @@ fleet_host_resolve() {
   fleet_host_owner=""
   fleet_host_minute=""
   fleet_host_repo_location=""
+  fleet_host_branch_max_age_days=""
 
   [[ -f "$manifest" ]] || { echo "ERROR $command: fleet manifest missing: $manifest" >&2; return 1; }
 
   row="$(jq -r --arg host "$host" '
-    [ ("mac", "linux") as $platform
+    (.config // {}) as $config
+    | [ ("mac", "linux") as $platform
       | (.[$platform].devices // {}) | to_entries[] | select(.key == $host)
-      | [$platform, (.value.administrator // ""), ((.value.schedule_minute // "") | tostring), (.value.repo_location // "")]
+      | [$platform, (.value.administrator // ""), ((.value.schedule_minute // "") | tostring), (.value.repo_location // ""), ((($config.repo_maintain.branch_max_age_days) // "") | tostring)]
       | join("\u001f") ] | first // empty
   ' "$manifest")" || { echo "ERROR $command: cannot read fleet manifest: $manifest" >&2; return 1; }
 
@@ -43,7 +46,7 @@ fleet_host_resolve() {
 
   # A non-whitespace delimiter (unit separator): `read` collapses runs of a
   # whitespace IFS such as tab, which would shift a later field into an empty one.
-  IFS=$'\x1f' read -r fleet_host_platform fleet_host_owner fleet_host_minute fleet_host_repo_location <<<"$row"
+  IFS=$'\x1f' read -r fleet_host_platform fleet_host_owner fleet_host_minute fleet_host_repo_location fleet_host_branch_max_age_days <<<"$row"
   [[ -n "$fleet_host_owner" ]] || { echo "ERROR $command: host '$host' has no administrator in $manifest" >&2; return 1; }
   [[ "$fleet_host_minute" =~ ^[0-9]+$ ]] || { echo "ERROR $command: host '$host' has no schedule_minute in $manifest" >&2; return 1; }