@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.6 → 0.1.8

package/bin/reconcile

@@ -180,6 +180,12 @@ collect_lean_ctx_observe_strip_backups() {
       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"
 }
@@ -456,28 +462,15 @@ run_npm() {
   fi
 }
 
-# Whether a read-only, owner-scoped query (brew_query, npm_installed_version)
-# can run without asking for privilege reconcile does not already have. Apply
-# mode always runs as real root (checked elsewhere), which can sudo -u any
-# administrator with no password. A plan/audit preview run has no such
-# guarantee -- $administrator on a Linux VPS device is "root", and previewing
-# that device's plan from an unprivileged account must not demand a sudo
-# password it may not have; it falls back to the pre-2026-09-28 unconditional
-# message instead. Self-administered devices (m3: administrator=tarunrana)
-# need no escalation at all, so their preview can query for real.
-can_query_as_administrator() {
-  [[ "$(id -un)" == "$administrator" ]] || [[ "$(id -u)" -eq 0 ]]
-}
-
 # Read-only Homebrew query, run exactly like run_brew's real mutations (same
 # owner, cwd, and stdin) but never a mutation itself. A named function so
 # tests can stub just this, instead of having to fake sudo's own argument
 # parsing the way a raw inline `sudo -u ... "$brew_bin" ...` would require.
-# Apply-mode only (see can_query_as_administrator): `brew list`/`brew
-# outdated` have been observed to take minutes under real load on a
-# contended box (Homebrew's own auto-update against a large git checkout),
-# so a plan preview never calls this -- it would turn a "quick look" into a
-# slow, load-dependent one for every brew formula on the device.
+# Apply-mode only: `brew list`/`brew outdated` have been observed to take
+# minutes under real load on a contended box (Homebrew's own auto-update
+# against a large git checkout), so a plan preview never calls this -- it
+# would turn a "quick look" into a slow, load-dependent one for every brew
+# formula on the device.
 brew_query() {
   (cd /tmp && sudo -u "$brew_owner" -H "$brew_bin" "$@" </dev/null)
 }
@@ -800,6 +793,27 @@ install_surface_policy_file() {
   echo "installed required surface policy: $target"
 }
 
+# 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
+# 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
+# after that boundary (never "v" floating anywhere: found in review,
+# 2026-09-28, `(^|[ v])` treated a bare "v" as equivalent to a space no
+# matter what preceded it, so "tool dev0.39.3"/"tool rev0.39.3" -- where the
+# "v" belongs to "dev"/"rev", not a version prefix -- silently matched and
+# would have skipped a real upgrade). The RIGHT boundary is a space or a
+# string end and never accepts "v", or "0.39.3" would incorrectly match
+# inside "0.39.30". Dots in the version are escaped so they match literally,
+# not "any character," in the regex below.
+release_archive_version_matches() {
+  local version_line="$1" version="$2" escaped
+  escaped="$(printf '%s' "$version" | sed 's/[.[\*^$()+?{}|]/\\&/g')"
+  grep -Eq "(^| )v?${escaped}( |\$)" <<<"$version_line"
+}
+
 # Resolves the release tag GitHub's own "latest" redirect currently points
 # at, without touching the api.github.com REST API (unauthenticated calls
 # there are rate-limited per source IP; this fleet's shared egress IP already
@@ -813,65 +827,33 @@ resolve_latest_release_tag() {
   basename "$location"
 }
 
-run_release_archive() {
-  local package="$1"
-  local version="$2"
-  local url="$3"
-  local expected_sha256="$4"
-  local archive_executable="$5"
-  local target="$6"
-  if [[ "$mode" != apply ]]; then
-    printf 'would install pinned release archive: %s %s -> %s\n' "$package" "$version" "$target"
-    return 0
-  fi
-  [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
-  [[ "$target" == /usr/local/bin/* ]] || { echo "release archive target must be under /usr/local/bin: $target" >&2; exit 1; }
-  [[ "$archive_executable" != /* && "$archive_executable" != *..* ]] || {
-    echo "unsafe archive executable path: $archive_executable" >&2
-    exit 1
-  }
-
-  (
-    local release_dir archive_file extract_dir actual_sha256
-    release_dir="$(mktemp -d)"
-    trap 'rm -rf "$release_dir"' EXIT
-    archive_file="$release_dir/release.tar.gz"
-    extract_dir="$release_dir/extract"
-    mkdir -p "$extract_dir"
-    curl --proto '=https' --proto-redir '=https' -fsSL --retry 3 -o "$archive_file" "$url"
-    case "$(uname -s)" in
-      Darwin) actual_sha256="$(shasum -a 256 "$archive_file" | awk '{print $1}')" ;;
-      Linux) actual_sha256="$(sha256sum "$archive_file" | awk '{print $1}')" ;;
-      *) echo "unsupported operating system for release archive" >&2; exit 1 ;;
-    esac
-    [[ "$actual_sha256" == "$expected_sha256" ]] || {
-      echo "checksum mismatch for $package $version" >&2
-      exit 1
-    }
-    tar -xzf "$archive_file" -C "$extract_dir" "$archive_executable"
-    [[ -f "$extract_dir/$archive_executable" ]] || {
-      echo "archive executable missing: $archive_executable" >&2
-      exit 1
-    }
-    atomic_install_executable "$extract_dir/$archive_executable" "$target"
-  )
-}
-
-# Like run_release_archive, but never pins a version or checksum in the
-# manifest: it always installs whatever GitHub's own "latest" alias currently
-# serves, verified against the checksums file published *in that same
-# release* (never a value carried over from a previous run or hardcoded
-# here) -- fails loud, installs nothing, if that checksums asset is missing
-# or doesn't list our asset. `.../releases/latest/download/<name>` is GitHub's
-# own stable alias for "the matching asset of whatever release is latest
-# right now", so the download itself never needs the resolved tag.
+# A GitHub release archive, installed under /usr/local/bin, verified against
+# a checksum published *in that same release* (never a value carried over
+# from a previous run or hardcoded here) -- fails loud, installs nothing, if
+# the checksums asset is missing or doesn't list our asset. It always
+# installs whatever GitHub's own "latest" release was when install_one_tool
+# resolved $tag (resolve_latest_release_tag), fetched with $tag pinned into
+# BOTH download URLs -- `.../releases/download/<tag>/<name>`, never through
+# GitHub's separate "always whatever is latest right now" alias for the
+# downloads themselves. Fixed 2026-09-29 (review): that alias re-resolves on
+# every request, so a release published between the tag resolve and the
+# archive download would otherwise serve the checksums file from one release
+# and the archive from a newer one -- silently mixing versions past the
+# checksum check (which would still "pass" against whichever checksums file
+# actually got fetched). Pinning both fetches to the one $tag closes that
+# window.
+# Tarun, 2026-09-29 (hard rule): versions are never pinned in the manifest --
+# this replaced the old pinned run_release_archive (fixed version + url +
+# sha256), which validate-manifest no longer accepts on any manager; $tag
+# here is resolved fresh every run, never carried over or hardcoded.
 run_release_archive_latest() {
   local package="$1"
   local repo="$2"
-  local asset="$3"
-  local checksums_asset="$4"
-  local archive_executable="$5"
-  local target="$6"
+  local tag="$3"
+  local asset="$4"
+  local checksums_asset="$5"
+  local archive_executable="$6"
+  local target="$7"
   [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
   [[ "$target" == /usr/local/bin/* ]] || { echo "release archive target must be under /usr/local/bin: $target" >&2; exit 1; }
   [[ "$archive_executable" != /* && "$archive_executable" != *..* ]] || {
@@ -888,13 +870,13 @@ run_release_archive_latest() {
     extract_dir="$release_dir/extract"
     mkdir -p "$extract_dir"
     curl --proto '=https' --proto-redir '=https' -fsSL --retry 3 \
-      -o "$checksums_file" "https://github.com/$repo/releases/latest/download/$checksums_asset"
+      -o "$checksums_file" "https://github.com/$repo/releases/download/$tag/$checksums_asset"
     expected_sha256="$(awk -v want="$asset" '$2 == want { print $1; found = 1 } END { exit !found }' "$checksums_file")" || {
       echo "no published checksum for $asset in $repo's $checksums_asset -- refusing to install unverified bytes" >&2
       exit 1
     }
     curl --proto '=https' --proto-redir '=https' -fsSL --retry 3 \
-      -o "$archive_file" "https://github.com/$repo/releases/latest/download/$asset"
+      -o "$archive_file" "https://github.com/$repo/releases/download/$tag/$asset"
     case "$(uname -s)" in
       Darwin) actual_sha256="$(shasum -a 256 "$archive_file" | awk '{print $1}')" ;;
       Linux) actual_sha256="$(sha256sum "$archive_file" | awk '{print $1}')" ;;
@@ -944,7 +926,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_version npm_spec npm_allow_scripts npm_target_version npm_installed_ver npm_plan_installed 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
   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")"
@@ -1000,15 +982,14 @@ install_one_tool() {
       run_apt install -y "$package" || rc=1
       ;;
     npm)
-      # An entry's optional .version pins the installed release (e.g.
-      # adl-agent-id, Handoff 5 2026-09-26 H4) rather than tracking whatever
-      # npm resolves as latest for update_policy=latest-stable. Ownership
+      # Tarun, 2026-09-29 (hard rule): versions are never pinned -- every
+      # fleet tool installs latest stable. npm entries never carry a
+      # .version (validate-manifest rejects one outright); $npm_spec stays a
+      # separate variable from $package only because the exact run_npm
+      # invocation below is asserted at the source level. Ownership
       # verification below still uses the bare package name: npm's global
-      # tree and package.json are keyed by package, never by the requested
-      # version spec.
-      npm_version="$(jq -r --arg id "$tool_id" '.[$id].version // empty' "$resolved_file")"
+      # tree and package.json are keyed by package, never by a version spec.
       npm_spec="$package"
-      [[ -z "$npm_version" ]] || npm_spec="$package@$npm_version"
       # Only @amsterdamdatalabs/enact-docs-search's manifest entry carries
       # this (docs/operations/global-tools.md Topic 2, decided 2026-09-28):
       # its own dependencies' install scripts, explicitly reviewed and
@@ -1019,41 +1000,20 @@ install_one_tool() {
           previous_executable="$(jq -r --arg id "$tool_id" '.[$id].executable' "$previous_resolved_file")"
           echo "would remove retired Bun compilation before npm install: $tool_id ($previous_executable and $(bun_source_hash_file "$tool_id"))"
         fi
-        # A pinned version is a pure local/offline fact: compare it against
-        # the real global install (npm_installed_version, no network) and say
-        # so honestly. An UNPINNED entry's "latest stable" is not knowable
-        # without a per-package registry round trip (npm_latest_version) --
-        # doing that here would make a plan preview slow and network-bound
-        # for every unpinned npm tool on the device, so it keeps today's
-        # conservative message instead of guessing. Either way, only query
-        # when it needs no new sudo privilege (can_query_as_administrator) --
-        # a preview run must not demand a password a different device's real
-        # administrator would need.
-        if [[ -n "$npm_version" ]] && can_query_as_administrator; then
-          if npm_plan_installed="$(npm_installed_version "$package")"; then
-            if [[ -n "$npm_plan_installed" && "$npm_plan_installed" == "$npm_version" ]]; then
-              echo "already latest: $tool_id (npm:$package@$npm_plan_installed)"
-            else
-              echo "would install or upgrade npm package: $npm_spec"
-            fi
-          else
-            echo "would install or upgrade npm package: $npm_spec (installed version not checked: npm ls -g failed)"
-          fi
-        else
-          echo "would install or upgrade npm package: $npm_spec"
-        fi
+        # "latest stable" is not knowable without a per-package registry
+        # round trip (npm_latest_version) -- doing that here would make a
+        # plan preview slow and network-bound for every npm tool on the
+        # device, so plan mode always prints this unconditional message
+        # instead of guessing.
+        echo "would install or upgrade npm package: $npm_spec"
       else
         if is_in_place_bun_to_npm_migration "$tool_id"; then
           migrating_from_bun=1
           prepare_in_place_bun_to_npm_migration "$tool_id" || rc=1
         fi
-        if [[ "$rc" -eq 0 ]]; then
-          if [[ -n "$npm_version" ]]; then
-            npm_target_version="$npm_version"
-          elif ! npm_target_version="$(npm_latest_version "$package")"; then
-            echo "$tool_id: npm view could not resolve the latest version of $package" >&2
-            rc=1
-          fi
+        if [[ "$rc" -eq 0 ]] && ! npm_target_version="$(npm_latest_version "$package")"; then
+          echo "$tool_id: npm view could not resolve the latest version of $package" >&2
+          rc=1
         fi
         if [[ "$rc" -eq 0 ]]; then
           if ! npm_installed_ver="$(npm_installed_version "$package")"; then
@@ -1081,21 +1041,8 @@ install_one_tool() {
       fi
       [[ "$rc" -eq 0 ]] && { ensure_global_pip_executable "$executable" || rc=1; }
       ;;
-    release-archive)
-      local version url sha256 archive_executable
-      version="$(jq -r --arg id "$tool_id" '.[$id].version' "$resolved_file")"
-      url="$(jq -r --arg id "$tool_id" '.[$id].url' "$resolved_file")"
-      sha256="$(jq -r --arg id "$tool_id" '.[$id].sha256' "$resolved_file")"
-      archive_executable="$(jq -r --arg id "$tool_id" '.[$id].archive_executable' "$resolved_file")"
-      if [[ "$mode" == apply && -x "$executable" ]] &&
-        "$executable" version 2>/dev/null | head -n 1 | grep -Fq "v$version"; then
-        echo "pinned release already installed: $package $version"
-      else
-        run_release_archive "$package" "$version" "$url" "$sha256" "$archive_executable" "$executable" || rc=1
-      fi
-      ;;
     release-archive-latest)
-      local repo asset checksums_asset archive_executable latest_tag latest_version
+      local repo asset checksums_asset archive_executable latest_tag latest_version resolved_asset resolved_checksums_asset
       repo="$(jq -r --arg id "$tool_id" '.[$id].repo' "$resolved_file")"
       asset="$(jq -r --arg id "$tool_id" '.[$id].asset' "$resolved_file")"
       checksums_asset="$(jq -r --arg id "$tool_id" '.[$id].checksums_asset // "SHA256SUMS"' "$resolved_file")"
@@ -1106,10 +1053,17 @@ install_one_tool() {
         latest_tag="$(resolve_latest_release_tag "$repo")" || { rc=1; latest_tag=""; }
         if [[ "$rc" -eq 0 ]]; then
           latest_version="${latest_tag#v}"
-          if [[ -x "$executable" ]] && "$executable" --version 2>/dev/null | head -n 1 | grep -Fq " $latest_version "; then
+          # 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.
+          resolved_asset="${asset//\{version\}/$latest_version}"
+          resolved_checksums_asset="${checksums_asset//\{version\}/$latest_version}"
+          if [[ -x "$executable" ]] &&
+            release_archive_version_matches "$("$executable" --version 2>/dev/null | head -n 1)" "$latest_version"; then
             echo "latest release already installed: $package $latest_version"
           else
-            run_release_archive_latest "$package" "$repo" "$asset" "$checksums_asset" "$archive_executable" "$executable" || rc=1
+            run_release_archive_latest "$package" "$repo" "$latest_tag" "$resolved_asset" "$resolved_checksums_asset" "$archive_executable" "$executable" || rc=1
           fi
         fi
       fi
@@ -1654,6 +1608,212 @@ remove_one_repo_dir() {
   rm -rf -- "$target"
 }
 
+# Lexical-only path normalization: collapses repeated slashes ("//" ->
+# "/") and current-dir segments ("/./" -> "/"), and drops one trailing
+# slash. Never resolves ".." or symlinks, and never touches the filesystem
+# -- the target frequently doesn't exist yet when this runs. Second review
+# pass, 2026-09-29: without this, "/usr/local/bin//agent-vault" and
+# "/usr/local/bin/agent-vault" compare unequal even though they name the
+# same real file, silently defeating executable_claimed_by_current_manifest
+# below (the guard would say "not claimed" and let the old manager's `rm -f`
+# through) -- previous_resolved_file is never validated, so a malformed
+# path there is exactly the case this guard exists to protect against.
+normalize_manifest_path() {
+  local path="$1"
+  while [[ "$path" == *//* ]]; do path="${path//\/\//\/}"; done
+  while [[ "$path" == */./* ]]; do path="${path//\/.\//\/}"; done
+  path="${path%/}"
+  printf '%s\n' "$path"
+}
+
+# A previous entry's executable path can be EXACTLY the path a CURRENT
+# entry now owns -- e.g. agent-vault-cli migrating release-archive ->
+# release-archive-latest, both /usr/local/bin/agent-vault. Bug found in
+# review, 2026-09-29: the install loop runs BEFORE the removal loop below
+# and already wrote/verified that binary; "retain shared package after
+# entry deletion" only skips removal when manager+package are BOTH
+# unchanged, so a manager-only change (exactly this migration) still
+# selects the id for removal, and the OLD manager's case arm then does a
+# plain `rm -f` on the path the install pass upstream just installed.
+# Checked by executable path, not by tool_id/manager/package, because that
+# is the one thing the filesystem actually cares about -- both sides
+# normalized first (see normalize_manifest_path) so a malformed legacy path
+# in previous_resolved_file still compares equal to a clean one.
+#
+# Second review pass, 2026-09-29 (bare-name executables): most managers
+# store an ABSOLUTE path in .executable (release-archive-latest, shim,
+# bun-compile, repo-script all require the /usr/local/bin/ prefix), but pip,
+# npm, and brew store a bare command name instead -- pip's own
+# ensure_global_pip_executable/remove_global_pip_executable ALWAYS place (or
+# remove) that name as a fixed /usr/local/bin/<name> symlink regardless of
+# the pip package name, so a bare pip .executable maps there and IS
+# compared. npm and brew do not get the same treatment: their real install
+# location depends on the device's own npm global prefix / Homebrew prefix,
+# resolved only through a live `command -v` PATH search
+# (npm_global_executable_path) that varies by platform -- never a single
+# fixed path this function can compute without shelling out. A migration
+# INTO an npm or brew entry is not detected here and the old manager's real
+# removal proceeds exactly as before this fix. That gap is narrower than it
+# looks: npm and brew each remove through their OWN package manager (`npm
+# uninstall -g`, `brew uninstall`), never the raw `rm -f` this guard
+# protects, so nothing here relies on rm to leave an npm/brew-owned file
+# alone in the first place.
+executable_claimed_by_current_manifest() {
+  local target="$1" normalized_target normalized_current current_manager current_executable
+  normalized_target="$(normalize_manifest_path "$target")"
+  while IFS=$'\t' read -r current_manager current_executable; do
+    [[ -n "$current_executable" ]] || continue
+    if [[ "$current_executable" == /* ]]; then
+      normalized_current="$(normalize_manifest_path "$current_executable")"
+    elif [[ "$current_manager" == pip ]]; then
+      normalized_current="$(normalize_manifest_path "/usr/local/bin/$current_executable")"
+    else
+      continue
+    fi
+    [[ "$normalized_current" == "$normalized_target" ]] && return 0
+  done < <(jq -r '.[] | [.manager, .executable] | @tsv' "$resolved_file")
+  return 1
+}
+
+# Uninstalls a single previously-applied tool the CURRENT manifest no longer
+# declares (or has migrated to a different manager/package) -- extracted
+# 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_one_manifest_entry() {
+  local tool_id="$1" manager package executable removed_repo_dir_target
+  if jq -e --arg id "$tool_id" '.config.protected_tools | index($id)' "$manifest" >/dev/null; then
+    echo "refusing to remove protected bootstrap tool: $tool_id" >&2
+    exit 1
+  fi
+  manager="$(jq -r --arg id "$tool_id" '.[$id].manager' "$previous_resolved_file")"
+  package="$(jq -r --arg id "$tool_id" '.[$id].package' "$previous_resolved_file")"
+  executable="$(jq -r --arg id "$tool_id" '.[$id].executable' "$previous_resolved_file")"
+  if is_in_place_bun_to_npm_migration "$tool_id"; then
+    if [[ "$mode" == apply ]]; then
+      echo "retired Bun compilation already removed for npm migration: $tool_id"
+    fi
+    return 0
+  fi
+  if jq -e --arg manager "$manager" --arg package "$package" 'to_entries | any(.value.manager == $manager and .value.package == $package)' "$resolved_file" >/dev/null; then
+    echo "retain shared package after entry deletion: $manager:$package"
+    return 0
+  fi
+  # Truthfulness fix (second review pass, 2026-09-29): for the managers that
+  # remove via a raw filesystem `rm -f` on a fixed path (never their own
+  # package manager's uninstall command), check executable_claimed_by_
+  # current_manifest BEFORE claiming an "uninstall" happened at all. The
+  # log line printed below this case is the only outcome a human or another
+  # tool sees; printing "explicit manifest deletion: uninstall ..." and only
+  # THEN discovering the file is retained (as this used to) makes the log
+  # lie about what just happened, exactly backwards from "log the decision
+  # as the outcome."
+  case "$manager" in
+    release-archive | release-archive-latest | shim | bun-compile)
+      if executable_claimed_by_current_manifest "$executable"; then
+        echo "retain $tool_id ($manager:$package): $executable is still declared by the current manifest"
+        return 0
+      fi
+      ;;
+  esac
+  echo "explicit manifest deletion: uninstall $tool_id ($manager:$package)"
+  case "$manager" in
+    brew) run_brew uninstall "$package" ;;
+    apt) run_apt remove -y "$package" ;;
+    npm) run_npm uninstall -g "$package" ;;
+    pip)
+      run_pip uninstall --break-system-packages -y "$package"
+      remove_global_pip_executable "$executable"
+      ;;
+    # "release-archive" (pinned version+url+sha256) is retired from
+    # validate-manifest's accepted managers (Tarun, 2026-09-29: versions
+    # are never pinned) -- no CURRENT manifest.json can declare one, so
+    # install_one_tool no longer has a case for it. This removal arm stays
+    # so a device whose applied-manifest.json still remembers an old
+    # release-archive entry (agent-vault-cli, before this change) can
+    # still cleanly uninstall it the next time it reconciles; previous
+    # state is read straight from disk, never re-validated.
+    release-archive)
+      [[ "$executable" == /usr/local/bin/* ]] || {
+        echo "refusing unsafe release archive removal target: $executable" >&2
+        exit 1
+      }
+      if [[ "$mode" == apply ]]; then
+        rm -f -- "$executable"
+      else
+        echo "would remove pinned release executable: $executable"
+      fi
+      ;;
+    release-archive-latest)
+      [[ "$executable" == /usr/local/bin/* ]] || {
+        echo "refusing unsafe release archive removal target: $executable" >&2
+        exit 1
+      }
+      if [[ "$mode" == apply ]]; then
+        rm -f -- "$executable"
+      else
+        echo "would remove latest release executable: $executable"
+      fi
+      ;;
+    shim)
+      [[ "$executable" == /usr/local/bin/* ]] || {
+        echo "refusing unsafe shim removal target: $executable" >&2
+        exit 1
+      }
+      if [[ "$mode" == apply ]]; then
+        rm -f -- "$executable"
+      else
+        echo "would remove shim: $executable"
+      fi
+      ;;
+    repo-script)
+      if [[ "$mode" == apply ]]; then
+        remove_one_repo_script "$executable"
+      else
+        [[ "$executable" =~ ^/usr/local/bin/[A-Za-z0-9][A-Za-z0-9._-]*$ ]] || {
+          echo "refusing unsafe managed script removal target: $executable" >&2
+          exit 1
+        }
+        echo "would remove managed repo script: $executable"
+      fi
+      ;;
+    repo-dir)
+      removed_repo_dir_target="$(jq -r --arg id "$tool_id" '.[$id].target' "$previous_resolved_file")"
+      if [[ "$mode" == apply ]]; then
+        remove_one_repo_dir "$removed_repo_dir_target"
+      else
+        [[ "$removed_repo_dir_target" == "$repo_dir_libexec_root"/* ]] || {
+          echo "refusing unsafe repo-dir removal target: $removed_repo_dir_target" >&2
+          exit 1
+        }
+        echo "would remove repo dir: $removed_repo_dir_target"
+      fi
+      ;;
+    bun-compile)
+      [[ "$executable" == /usr/local/bin/* ]] || {
+        echo "refusing unsafe bun binary removal target: $executable" >&2
+        exit 1
+      }
+      if [[ "$mode" == apply ]]; then
+        rm -f -- "$executable"
+      else
+        echo "would remove bun binary: $executable"
+      fi
+      ;;
+    embedding-model)
+      if [[ "$mode" == apply ]]; then
+        [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
+        command -v bun >/dev/null 2>&1 || { echo "embedding-model requires bun; ensure bun installs before this tool" >&2; exit 1; }
+        (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
+          bun "$repo_root/packages/fleet/src/install-embedding-model.ts" uninstall </dev/null)
+      else
+        echo "would remove embedding model cache: ~/.cache/adl-embedding/model (as $administrator)"
+      fi
+      ;;
+    *) echo "unsupported manager in previous manifest: $manager" >&2; exit 1 ;;
+  esac
+}
+
 # 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
@@ -1825,6 +1985,37 @@ run_surface_update() {
   sudo -u "$administrator" -H env PATH="$surface_cli_search_path" "$resolved" "$@" </dev/null
 }
 
+# Extracts an update command's own reported failure reason from its
+# captured output, or prints nothing (empty) if none is found. Confirmed
+# live for kimi on strato and hostinger-vps-1 (2026-09-30): `kimi upgrade`
+# printed "error: failed to check for updates: CDN /latest returned HTTP
+# 521" and still exited 0. Broadened by independent review the same day:
+# optional leading whitespace before the marker, ANSI color codes stripped
+# first (real CLIs colorize their own output), and any of
+# "error:"/"Error:"/"ERROR:"/"✖ error:" -- case-insensitive by
+# construction (POSIX bracket character classes, not a sed `-I`/`I` flag,
+# which BSD sed does not support). Applied identically to every surface's
+# update path, native/npm and Homebrew-cask alike, rather than one
+# per-surface parser.
+#
+# Never `cmd1 | cmd2` piped straight into the caller's assignment: see the
+# inner `if var=$(grep ...); then` below (not `grep | sed`) for why -- under
+# this file's `set -euo pipefail`, grep's ordinary "no match" exit would
+# otherwise abort the run on every surface that DIDN'T report an error. An
+# `if`-tested command is exempt from that abort by design; the function's
+# OWN exit status is therefore never meaningful (an `if` with no `else`
+# always returns 0), so callers check the printed string's emptiness, never
+# this function's exit status.
+surface_update_error_reason() {
+  local output="$1" plain line
+  # LC_ALL=C: the strip is bytewise. Under en_US.UTF-8 glibc resolves [@-~]
+  # by collation, so the escape's final letter would never match.
+  plain="$(LC_ALL=C sed -E $'s/\x1b\\[[0-9;]*[@-~]//g' <<<"$output")"
+  if line="$(grep -m1 -iE '^[[:space:]]*(✖[[:space:]]*)?error:' <<<"$plain")"; then
+    sed -E 's/^[[:space:]]*(✖[[:space:]]*)?[eE][rR][rR][oO][rR]:[[:space:]]*//' <<<"$line"
+  fi
+}
+
 # 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
@@ -1863,6 +2054,26 @@ reconcile_one_surface_cli() {
       echo "surface update failed: $name (exit $update_status)" >&2
       return 1
     fi
+    # Same broadened check as the native/npm path below (independent
+    # review, 2026-09-30): brew itself can exit 0 while its own output
+    # reports a real problem. No install/upgrade claim without checking
+    # for one first -- Homebrew has no version comparison in this branch
+    # (it acts on cask PRESENCE, not a read version), so there is no
+    # "version changed" success case to weigh it against here; any error
+    # line found is a hard failure.
+    local update_error_line
+    update_error_line="$(surface_update_error_reason "$update_output")"
+    if [[ -n "$update_error_line" ]]; then
+      # Install vs upgrade distinguished in the failure wording too (second
+      # coordinator pass, 2026-09-30): the same `cask_action[0]` that already
+      # picks the real brew argv above also names which one failed.
+      if [[ "${cask_action[0]}" == install ]]; then
+        echo "surface $name: cask install failed ($update_error_line)" >&2
+      else
+        echo "surface $name: cask upgrade failed ($update_error_line)" >&2
+      fi
+      return 1
+    fi
     if [[ "${cask_action[0]}" == install ]]; then
       echo "surface $name: Homebrew cask installed"
     else
@@ -1891,7 +2102,7 @@ reconcile_one_surface_cli() {
     echo "surface $name: report-only, currently ${ver:-unknown}"
     return 0
   fi
-  local old_version new_version update_output update_status=0
+  local old_version new_version update_output update_status=0 update_error_line
   old_version="$(surface_cli_version "$resolved")"
   update_output="$(run_with_timeout "$SURFACE_UPDATE_TIMEOUT_SECONDS" run_surface_update "$resolved" ${update_args[@]+"${update_args[@]}"} 2>&1)" || update_status=$?
   printf '%s\n' "$update_output"
@@ -1902,12 +2113,48 @@ reconcile_one_surface_cli() {
     echo "surface update failed: $name (exit $update_status)" >&2
     return 1
   fi
+  # A surface's update command can exit 0 while its own output says the
+  # check itself failed -- confirmed live for kimi (strato + hostinger,
+  # 2026-09-30): `kimi upgrade` printed
+  # "error: failed to check for updates: CDN /latest returned HTTP 521" and
+  # still exited 0 (AGENTS.md: no silent fallback). Read new_version BEFORE
+  # judging anything (independent review, 2026-09-30): a version CHANGE is
+  # proof positive the update happened, which outranks an error line the
+  # command also printed (e.g. a flaky post-install self-check after a
+  # real, successful install) -- reported as a note on the success line,
+  # never a failure. Only an UNCHANGED version with an error line is the
+  # case this whole check exists for: the command claimed nothing changed,
+  # and said why, and that is reported as a failure -- wording "update
+  # check failed", not "could not check for updates", since the reported
+  # reason may not even be about the check itself (kept generic rather than
+  # asserting which).
+  #
+  # An EMPTY new_version (second coordinator pass, 2026-09-30: the binary
+  # broke, or --version now produces no output) must never count as
+  # "updated" just because empty differs from a non-empty old_version --
+  # that used to read as "surface X: 1.2.3 -> unknown", an arrow-style
+  # SUCCESS line for a version we cannot actually confirm. Checked before
+  # the "changed" branch below, so only a REAL, non-empty, different
+  # version ever reaches it.
   new_version="$(surface_cli_version "$resolved")"
-  if [[ "$old_version" == "$new_version" ]]; then
-    echo "surface $name: already latest (${new_version:-unknown})"
-  else
-    echo "surface $name: ${old_version:-unknown} -> ${new_version:-unknown}"
+  update_error_line="$(surface_update_error_reason "$update_output")"
+  if [[ -z "$new_version" ]]; then
+    echo "surface $name: update ran but version unreadable (${update_error_line:-"--version produced no output"}); was ${old_version:-unknown}" >&2
+    return 1
   fi
+  if [[ "$old_version" != "$new_version" ]]; then
+    if [[ -n "$update_error_line" ]]; then
+      echo "surface $name: updated ${old_version:-unknown} -> $new_version (reported: $update_error_line)"
+    else
+      echo "surface $name: ${old_version:-unknown} -> $new_version"
+    fi
+    return 0
+  fi
+  if [[ -n "$update_error_line" ]]; then
+    echo "surface $name: update check failed ($update_error_line); kept ${old_version:-unknown}" >&2
+    return 1
+  fi
+  echo "surface $name: already latest ($new_version)"
   return 0
 }
 
@@ -2196,111 +2443,7 @@ reconcile_surface_clis
 if [[ "$have_previous" -eq 1 ]]; then
   while IFS= read -r tool_id; do
     [[ -n "$tool_id" ]] || continue
-    if jq -e --arg id "$tool_id" '.config.protected_tools | index($id)' "$manifest" >/dev/null; then
-      echo "refusing to remove protected bootstrap tool: $tool_id" >&2
-      exit 1
-    fi
-    manager="$(jq -r --arg id "$tool_id" '.[$id].manager' "$previous_resolved_file")"
-    package="$(jq -r --arg id "$tool_id" '.[$id].package' "$previous_resolved_file")"
-    executable="$(jq -r --arg id "$tool_id" '.[$id].executable' "$previous_resolved_file")"
-    if is_in_place_bun_to_npm_migration "$tool_id"; then
-      if [[ "$mode" == apply ]]; then
-        echo "retired Bun compilation already removed for npm migration: $tool_id"
-      fi
-      continue
-    fi
-    if jq -e --arg manager "$manager" --arg package "$package" 'to_entries | any(.value.manager == $manager and .value.package == $package)' "$resolved_file" >/dev/null; then
-      echo "retain shared package after entry deletion: $manager:$package"
-      continue
-    fi
-    echo "explicit manifest deletion: uninstall $tool_id ($manager:$package)"
-    case "$manager" in
-      brew) run_brew uninstall "$package" ;;
-      apt) run_apt remove -y "$package" ;;
-      npm) run_npm uninstall -g "$package" ;;
-      pip)
-        run_pip uninstall --break-system-packages -y "$package"
-        remove_global_pip_executable "$executable"
-        ;;
-      release-archive)
-        [[ "$executable" == /usr/local/bin/* ]] || {
-          echo "refusing unsafe release archive removal target: $executable" >&2
-          exit 1
-        }
-        if [[ "$mode" == apply ]]; then
-          rm -f -- "$executable"
-        else
-          echo "would remove pinned release executable: $executable"
-        fi
-        ;;
-      release-archive-latest)
-        [[ "$executable" == /usr/local/bin/* ]] || {
-          echo "refusing unsafe release archive removal target: $executable" >&2
-          exit 1
-        }
-        if [[ "$mode" == apply ]]; then
-          rm -f -- "$executable"
-        else
-          echo "would remove latest release executable: $executable"
-        fi
-        ;;
-      shim)
-        [[ "$executable" == /usr/local/bin/* ]] || {
-          echo "refusing unsafe shim removal target: $executable" >&2
-          exit 1
-        }
-        if [[ "$mode" == apply ]]; then
-          rm -f -- "$executable"
-        else
-          echo "would remove shim: $executable"
-        fi
-        ;;
-      repo-script)
-        if [[ "$mode" == apply ]]; then
-          remove_one_repo_script "$executable"
-        else
-          [[ "$executable" =~ ^/usr/local/bin/[A-Za-z0-9][A-Za-z0-9._-]*$ ]] || {
-            echo "refusing unsafe managed script removal target: $executable" >&2
-            exit 1
-          }
-          echo "would remove managed repo script: $executable"
-        fi
-        ;;
-      repo-dir)
-        removed_repo_dir_target="$(jq -r --arg id "$tool_id" '.[$id].target' "$previous_resolved_file")"
-        if [[ "$mode" == apply ]]; then
-          remove_one_repo_dir "$removed_repo_dir_target"
-        else
-          [[ "$removed_repo_dir_target" == "$repo_dir_libexec_root"/* ]] || {
-            echo "refusing unsafe repo-dir removal target: $removed_repo_dir_target" >&2
-            exit 1
-          }
-          echo "would remove repo dir: $removed_repo_dir_target"
-        fi
-        ;;
-      bun-compile)
-        [[ "$executable" == /usr/local/bin/* ]] || {
-          echo "refusing unsafe bun binary removal target: $executable" >&2
-          exit 1
-        }
-        if [[ "$mode" == apply ]]; then
-          rm -f -- "$executable"
-        else
-          echo "would remove bun binary: $executable"
-        fi
-        ;;
-      embedding-model)
-        if [[ "$mode" == apply ]]; then
-          [[ "$(id -u)" -eq 0 ]] || { echo "apply mode must run as root" >&2; exit 1; }
-          command -v bun >/dev/null 2>&1 || { echo "embedding-model requires bun; ensure bun installs before this tool" >&2; exit 1; }
-          (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
-            bun "$repo_root/packages/fleet/src/install-embedding-model.ts" uninstall </dev/null)
-        else
-          echo "would remove embedding model cache: ~/.cache/adl-embedding/model (as $administrator)"
-        fi
-        ;;
-      *) echo "unsupported manager in previous manifest: $manager" >&2; exit 1 ;;
-    esac
+    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)
@@ -2642,6 +2785,83 @@ else
   echo "global-tools: $mode complete; no state changed"
 fi
 
+# git_maintain_repos (2026-09-30, arm-only decision the same day): an
+# explicit, closed list of repositories this device's own checkout lives
+# at OUTSIDE any recursively-scanned home directory -- the Linux VPSes'
+# root-owned /opt/adl-azdo is the confirmed case for both strato-vps-1 and
+# hostinger-vps-1 (STATUS.md's 2026-09-29 first-deployment record;
+# hostinger's own fleet-cutover --apply landed 2026-09-29T23:43Z, confirmed
+# the same day). git-maintain's own scheduling (packages/fleet/src/
+# launch-agents.ts: a dedicated compiled binary, ad-hoc signed, run by a
+# launchd LaunchAgent under TCC) is macOS-only by construction, so it never
+# reaches these checkouts on its own. This runs the job directly, on
+# reconcile's own schedule (every platform this script runs on already has
+# one), passing each declared path as `--repo` argv -- never a recursive
+# scan of a shared parent like `/opt` (which also holds unrelated,
+# explicitly off-limits directories), and never a new environment
+# variable: the list itself comes only from the manifest, and
+# GIT_MAINTAIN_DRY below is this job's own pre-existing dry/real contract,
+# driven by reconcile's own --mode exactly like every other step in this
+# file, not a knob an operator sets by hand. Absent or empty (every mac
+# device today) is a silent no-op, the same convention
+# launch_agents/scratch_repos/surface_clis already use.
+#
+# ARM-ONLY, always, on this path (independent review, 2026-09-30): the full
+# job on this SAME checkout `bin/reconcile` runs from turned out to be new,
+# unapproved, root-run behaviour once actually reasoned through, not merely
+# a self-checkout read/write ordering hazard -- see the `--arm-only`
+# decision recorded in jobs/git-maintain/src/main.ts's own header comment
+# for the full list (a silent fast-forward-driven auto-deploy of
+# `origin/integration`/main with no approval gate, colliding with
+# fleet-cutover.sh re-reading fleet-retire-list.json from this same
+# checkout after reconcile runs, `git branch -D` as root, and a fetch that
+# still runs even in dry/plan/audit mode and exits 0 on its own failure).
+# `--arm-only` narrows this call to ONLY `armHooks`: no fetch, no
+# fast-forward, no branch prune, no bundle-refresh installer, no network,
+# and no Azure DevOps identity resolution. The only remaining write is
+# `.git/config`'s `core.hooksPath`, real only in apply mode
+# (GIT_MAINTAIN_DRY=1 below makes it a `[dry] would arm ...` log line and
+# nothing else, in both plan AND audit mode). That is never a tracked file
+# this script (or anything downstream of it) reads, so arm-only has no
+# self-checkout read/write ordering hazard left to avoid -- this step stays
+# in this late position anyway, unchanged from the full-job version: it is
+# still the simplest place for it, and there is no reason to special-case
+# arm-only's position just because its own hazard is gone.
+git_maintain_repos=()
+while IFS= read -r repo; do
+  [[ -n "$repo" ]] && git_maintain_repos+=("$repo")
+done < <(jq -r --arg platform "$platform" --arg device "$device" \
+  '.[$platform].devices[$device].git_maintain_repos // [] | .[]' "$manifest")
+if [[ "${#git_maintain_repos[@]}" -gt 0 ]]; then
+  git_maintain_repo_args=(--arm-only)
+  for repo in "${git_maintain_repos[@]}"; do
+    git_maintain_repo_args+=(--repo "$repo")
+  done
+  # Unlike default-agent-file.ts/managed-settings.ts's plan branches earlier
+  # in this file (which never fail, by construction, so they run
+  # unguarded), this job's dry pass still validates each declared path is a
+  # real repo -- a genuine failure mode even in a non-apply mode, e.g. a
+  # declared checkout that has not been cloned yet. So every non-apply mode
+  # is guarded exactly like apply mode here, deliberately deviating from
+  # those sibling steps: report it, collect it, never let it abort the rest
+  # of this script under this file's own `set -e`. `$mode` (plan OR audit)
+  # is reported verbatim -- audit is a real, distinct reconcile mode, never
+  # relabeled "plan".
+  if [[ "$mode" != apply ]]; then
+    echo "global-tools: git-maintain (declared repos, arm-only) mode=$mode device=$device -> ${git_maintain_repos[*]}"
+    if ! GIT_MAINTAIN_DRY=1 bun "$repo_root/packages/fleet/jobs/git-maintain/src/main.ts" "${git_maintain_repo_args[@]}"; then
+      echo "global-tools: TOOL INSTALL FAILED: git-maintain-repos" >&2
+      failed_tools+=("git-maintain-repos")
+    fi
+  else
+    echo "global-tools: git-maintain (declared repos, arm-only) mode=apply device=$device -> ${git_maintain_repos[*]}"
+    if ! bun "$repo_root/packages/fleet/jobs/git-maintain/src/main.ts" "${git_maintain_repo_args[@]}"; then
+      echo "global-tools: TOOL INSTALL FAILED: git-maintain-repos" >&2
+      failed_tools+=("git-maintain-repos")
+    fi
+  fi
+fi
+
 # A recorded, continued-past tool failure (install_one_tool /
 # build_one_bun_tool / install_one_embedding_model_tool / write_one_shim)
 # still lets every post-pass above run -- sweep, kimi-hooks, global-agents,