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

package/bin/adl

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/bin/adl
-size: 82875872 bytes
-sha256: b562edfda0f280940a2b5874874f83c22bde7fe8cd5b9d8159c003f4b53e1f5c
+size: 82920928 bytes
+sha256: ecd5111c7bc2c06d56361450a0d97b8280f6d300f879714a0bd23d2c534ec61b

package/bin/lean-ctx-observe-strip

@@ -10,7 +10,7 @@ export PATH="/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/us
 # the per-repo carrier (`adl hook lean-ctx pre-tool-use|post-tool-use`,
 # written by `adl hooks deploy`) already provides rewrite/redirect/
 # read-dedup with the repo's own config, and `observe` has no per-repo
-# carrier at all and is dropped outright. Five carriers, all written by
+# carrier at all and is dropped outright. Six carriers, all written by
 # `lean-ctx setup`, are covered ("fix all the lean-ctx issues" -- Tarun,
 # 2026-09-29 -- widened this from an initial two-of-five scope):
 #   1. Raw, unwrapped `lean-ctx hook <subcommand>` entries -- observe,
@@ -33,6 +33,20 @@ export PATH="/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/us
 #      at $HOME/.claude/skills/lean-ctx, .codex/skills/lean-ctx,
 #      .cursor/skills/lean-ctx, .config/opencode/skills/lean-ctx,
 #      .agents/skills/lean-ctx.
+#   6. Global lean-ctx hook SCRIPTS: every entry named `lean-ctx-*` directly
+#      under $HOME/.claude/hooks (lean-ctx-rewrite.sh, lean-ctx-redirect.sh,
+#      their -native counterparts, and any .bak copies). Added 2026-09-30
+#      because of lean-ctx's own startup refresh gate (proven from v3.10.5
+#      source, rust/src/hooks/mod.rs): refresh_installed_hooks() re-writes
+#      the global Claude hooks whenever hooks_installed_for("claude", home)
+#      is true, i.e. <claude_dir>/hooks/lean-ctx-rewrite.sh EXISTS or
+#      <claude_dir>/settings.json contains the substring `lean-ctx`.
+#      Stripping settings.json (shape 1) alone leaves the scripts behind and
+#      the gate armed, so the carrier rewrites the global hooks on its next
+#      start. Only names starting with `lean-ctx-` are touched; every other
+#      file there (enact-*, code-simplifier.mjs, lib/, symlinks to other
+#      repos) is left alone. Scope is $HOME/.claude only -- CLAUDE_CONFIG_DIR
+#      is deliberately not consulted (the tool takes --home explicitly).
 # `adl hook lean-ctx ...` (the per-repo carrier) and Orca's own hooks are
 # never touched -- see bin/lib/lean-ctx-observe-hooks.sh's own header for
 # exactly why the match can never catch either, and for the full "which
@@ -42,7 +56,7 @@ export PATH="/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/us
 # that same header, not stripped. Run by bin/reconcile on every
 # reconciliation (plan AND apply, exactly like bin/kimi-hooks /
 # bin/opencode-hooks) so a hand-edited or Orca-reinstalled per-user config
-# never lets any of the five carriers creep back in unnoticed.
+# never lets any of the six carriers creep back in unnoticed.
 #
 # Usage: lean-ctx-observe-strip --home ABSOLUTE_PATH --mode plan|apply
 #
@@ -66,7 +80,11 @@ export PATH="/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/us
 #          not exist, is reported and left alone. A skill directory is
 #          moved (never deleted) only when its SKILL.md frontmatter says
 #          `name: lean-ctx`; any other content there is left alone and
-#          reported. Refuses outright (before touching anything) when run
+#          reported. The `lean-ctx-*` hook scripts under ~/.claude/hooks are
+#          moved (never deleted) into a sibling
+#          `hooks.pre-lean-ctx-observe-strip-<UTC ts>/` directory OUTSIDE
+#          the scanned hooks/ directory, exactly like a skill directory's
+#          backup, and reported one line per file. Refuses outright (before touching anything) when run
 #          as literal root (EUID 0) against a --home it does not own --
 #          bin/reconcile's apply path never does this itself; see
 #          lean_ctx_observe_strip_guard_euid in the shared lib.
@@ -348,6 +366,60 @@ strip_skill_dir_one() {
   return 0
 }
 
+# strip_hook_scripts_one <hooks-dir> -- shape 6 (see the header): moves every
+# entry named `lean-ctx-*` directly under <hooks-dir> into a sibling
+# `<hooks-dir>.pre-lean-ctx-observe-strip-<UTC ts>/` directory (OUTSIDE the
+# scanned hooks/ directory, same reasoning as strip_skill_dir_one), so
+# lean-ctx's refresh gate (`hooks/lean-ctx-rewrite.sh` exists) is disarmed.
+# Matches by name prefix only, never by content; a symlink named
+# `lean-ctx-*` is moved as the link itself (mv never follows it). Nothing
+# else in <hooks-dir> is read or touched. Each file is reported as
+# "backed up previous hook script <original> to <backup>" (two explicit
+# paths, like the skill-directory note -- the backup path does not end in
+# `.pre-<label>-<timestamp>`, so bin/reconcile cannot recover the original
+# by suffix-stripping).
+strip_hook_scripts_one() {
+  local hooks_dir="$1" entry
+  local found=()
+  if [[ -d "$hooks_dir" ]]; then
+    for entry in "$hooks_dir"/lean-ctx-*; do
+      if [[ -e "$entry" || -L "$entry" ]]; then
+        found+=("$entry")
+      fi
+    done
+  fi
+  if [[ "${#found[@]}" -eq 0 ]]; then
+    echo "lean-ctx-observe-strip: $hooks_dir/lean-ctx-*: not present -- nothing to strip"
+    return 0
+  fi
+  for entry in "${found[@]}"; do
+    echo "lean-ctx-observe-strip: $entry: found lean-ctx hook script"
+    if [[ "$mode" != apply ]]; then
+      echo "lean-ctx-observe-strip: would move $entry to a timestamped backup location outside $hooks_dir"
+    fi
+  done
+  [[ "$mode" == apply ]] || return 0
+
+  local backup_root
+  backup_root="${hooks_dir}.pre-lean-ctx-observe-strip-$(date -u +%Y%m%dT%H%M%SZ)"
+  if ! mkdir "$backup_root" 2>/dev/null; then
+    echo "lean-ctx-observe-strip: $hooks_dir: FAILED to create backup location $backup_root -- not modified" >&2
+    return 1
+  fi
+  local backup rc=0
+  for entry in "${found[@]}"; do
+    backup="$backup_root/$(basename "$entry")"
+    if ! mv "$entry" "$backup"; then
+      echo "lean-ctx-observe-strip: $entry: FAILED to move to $backup -- not modified" >&2
+      rc=1
+      continue
+    fi
+    echo "lean-ctx-observe-strip: backed up previous hook script $entry to $backup"
+    echo "lean-ctx-observe-strip: moved lean-ctx hook script $entry to $backup"
+  done
+  return "$rc"
+}
+
 status=0
 for target in "${targets[@]}"; do
   strip_one "$target" || status=1
@@ -358,4 +430,5 @@ done
 for target in "${skill_dir_targets[@]}"; do
   strip_skill_dir_one "$target" || status=1
 done
+strip_hook_scripts_one "$home/.claude/hooks" || status=1
 exit "$status"

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"
 }
@@ -1979,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
@@ -2017,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
@@ -2045,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"
@@ -2056,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
 }
 
@@ -2692,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,

package/bin/validate-manifest

@@ -43,10 +43,28 @@ if ! jq -e '
     all(.minimum_free_gib >= 1) and
     all((.home | type) == "string" and (.home | startswith("/"))) and
     all((.default_agent | type) == "string" and (.default_agent | test("^agent-[a-z0-9-]+$"))) and
-    all((keys - ["administrator", "default_agent", "home", "launch_agents", "minimum_free_gib", "schedule_minute", "scratch_repos", "brew_upgrade_all", "surface_clis", "tools"] | length) == 0) and
+    all((keys - ["administrator", "default_agent", "home", "launch_agents", "minimum_free_gib", "schedule_minute", "scratch_repos", "brew_upgrade_all", "surface_clis", "git_maintain_repos", "tools"] | length) == 0) and
     all((.scratch_repos // []) | type == "array" and (. | unique | length) == length and
       all(type == "string" and startswith("/") and . != "/" and
         (endswith("/") | not) and (contains("..") | not) and (test("\\s") | not))) and
+    # git_maintain_repos (2026-09-30): an explicit, closed list of
+    # repositories bin/reconcile passes to git-maintain via --repo argv --
+    # never a recursive scan root, deliberately, since these devices own
+    # checkouts that sit at a fixed path outside any device home (the Linux
+    # VPSes use /opt/adl-azdo) and a recursive scan of a shared parent like
+    # /opt would also walk into unrelated, explicitly off-limits
+    # directories. The azagent/vsts.agent substring bans are exactly that
+    # guard, enforced at the schema layer (case-insensitively -- a manifest
+    # value could be typed AzAgent2 as easily as azagent2) so a mistyped or
+    # copy-pasted entry can never point there. git-maintain itself refuses
+    # the same names again, case-insensitively and by realpath too, at the
+    # point of actual use (jobs/git-maintain/src/main.ts,
+    # isForbiddenAzurePipelinesPath) -- this schema check alone only ever
+    # sees the manifest literal string, never what a symlink resolves to.
+    all((.git_maintain_repos // []) | type == "array" and (. | unique | length) == length and
+      all(type == "string" and startswith("/") and . != "/" and
+        (endswith("/") | not) and (contains("..") | not) and (test("\\s") | not) and
+        (ascii_downcase | contains("azagent") | not) and (ascii_downcase | contains("vsts.agent") | not))) and
     all((.brew_upgrade_all // false) | type == "boolean") and
     all(
       (.surface_clis // []) as $surfaces |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amsterdamdatalabs/adl-agent-control-linux-x64",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "adl CLI binary for linux/x64 (agent identity + Azure DevOps front door — see docs/architecture/cli-design.md)",
   "license": "UNLICENSED",
   "os": [

package/packages/agent-hooks/src/deploy/deploy.ts

@@ -15,7 +15,7 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { renderOpencodePlugin } from './opencode-template.ts'
-import { mergeCursorHooksFile, mergeJsonHooksFile } from './json-merge.ts'
+import { type AmbiguousPairConflict, mergeCursorHooksFile, mergeJsonHooksFile, type RestoredHook } from './json-merge.ts'
 import {
   legacyFileHash,
   type LegacyLockDoc,
@@ -37,6 +37,18 @@ export interface DeployHooksOptions {
   readonly profile?: HookDeployProfile
   /** Defaults to loading `profile.source` relative to `dirname(assetsDir)`. */
   readonly hooksDoc?: CanonicalHooksDoc
+  /**
+   * Computes the exact same written/unchanged/conflicts result WITHOUT
+   * writing anything — not the target files, not the lock, not the legacy
+   * lock (independent review, 2026-09-29: `adl install --dry-run` used to
+   * run this for real against a throwaway `cpSync` sandbox instead, which
+   * risked rewriting symlinks to absolute paths, copying `node_modules`,
+   * and touching a worktree's real `.git`; a real plan mode has none of
+   * that). Every filesystem WRITE below is gated on `!dryRun`; every READ
+   * (existing file content, the current lock) still runs for real, since
+   * an accurate plan needs the real current state.
+   */
+  readonly dryRun?: boolean
 }
 
 export interface HookConflict {
@@ -44,11 +56,41 @@ export interface HookConflict {
   readonly reason: string
 }
 
+/** One hook healed via the PAIR fallback (not hash, not the legacy channel) this run — see json-merge.ts's `RestoredHook` for the full rationale (2026-09-30, round 5, finding 2). */
+export interface RestoredHookReport {
+  readonly file: string
+  readonly event: string
+  readonly command: string
+  readonly matcher?: string
+}
+
+function makeRestoredReport(file: string, hook: RestoredHook & { readonly event: string }): RestoredHookReport {
+  return hook.matcher !== undefined ? { file, event: hook.event, command: hook.command, matcher: hook.matcher } : { file, event: hook.event, command: hook.command }
+}
+
+function ambiguousConflictReason(c: AmbiguousPairConflict): string {
+  const matcherPart = c.matcher !== undefined ? ` (matcher "${c.matcher}")` : ' (no matcher)'
+  return `ambiguous duplicate adl-owned hook in event '${c.event}': more than one unverified candidate for "${c.command}"${matcherPart}; neither healed, left untouched — resolve by hand`
+}
+
 export interface DeployHooksResult {
   readonly written: readonly string[]
   readonly unchanged: readonly string[]
   readonly conflicts: readonly HookConflict[]
   readonly lockPath: string
+  /**
+   * Surface files whose lock entry moved from the legacy
+   * (`ownedCommands`-only) shape to the content-addressed one
+   * (`ownedEntries`) on THIS run (independent review, 2026-09-30, finding
+   * 7). This can be non-empty even when the surface's own `written`/
+   * `unchanged` outcome looks like nothing happened — the deployed JSON
+   * file can stay byte-identical while the LOCK itself is rewritten, and
+   * that rewrite deserves its own truthful line in the CLI's output
+   * rather than being folded silently into "unchanged".
+   */
+  readonly lockMigrated: readonly string[]
+  /** Hooks healed via the pair fallback this run, named explicitly (round 5, finding 2) so deploy's own output, doctor's preview, and `adl install` can all say "restored adl hook <event>/<matcher>/<command> — local changes to it were replaced". */
+  readonly restored: readonly RestoredHookReport[]
 }
 
 function readExistingJson(path: string): Record<string, unknown> | undefined {
@@ -65,14 +107,15 @@ function readExistingJson(path: string): Record<string, unknown> | undefined {
   return doc as Record<string, unknown>
 }
 
-function writeJsonIfChanged(path: string, content: Record<string, unknown>, changed: boolean): void {
-  if (!changed) return
+function writeJsonIfChanged(path: string, content: Record<string, unknown>, changed: boolean, dryRun: boolean): void {
+  if (!changed || dryRun) return
   mkdirSync(dirname(path), { recursive: true })
   writeFileSync(path, `${JSON.stringify(content, null, 2)}\n`)
 }
 
 export function deployHooks(options: DeployHooksOptions): DeployHooksResult {
   const { assetsDir, targetRepo } = options
+  const dryRun = options.dryRun === true
 
   if (!existsSync(assetsDir) || !statSync(assetsDir).isDirectory()) {
     throw new Error(`agent-hooks assets directory not found: ${assetsDir}`)
@@ -91,19 +134,21 @@ export function deployHooks(options: DeployHooksOptions): DeployHooksResult {
   const written: string[] = []
   const unchanged: string[] = []
   const conflicts: HookConflict[] = []
+  const lockMigrated: string[] = []
+  const restored: RestoredHookReport[] = []
   const takeover = { any: false }
 
   for (const surface of profile.surfaces) {
-    deploySurface(surface, { assetsDir, targetRepo, hooksDoc, lock, legacyDoc, takeover, newEntries, written, unchanged, conflicts })
+    deploySurface(surface, { assetsDir, targetRepo, hooksDoc, lock, legacyDoc, takeover, newEntries, written, unchanged, conflicts, lockMigrated, restored, dryRun })
   }
 
-  writeLock(targetRepo, { version: 1, entries: newEntries })
+  if (!dryRun) writeLock(targetRepo, { version: 1, entries: newEntries })
 
   // Once anything was actually taken over, this package's own bookkeeping in
   // the legacy lock is stale — ownership has fully moved to the lock just
   // written above. A legacy lock present but untouched by any takeover (no
   // hash matched, or this repo never had one) is left exactly as found.
-  if (takeover.any && legacyDoc !== undefined && legacyLockPath !== undefined) {
+  if (!dryRun && takeover.any && legacyDoc !== undefined && legacyLockPath !== undefined) {
     const opencodeSurface = profile.surfaces.find((s) => s.format === 'opencode-plugin')
     if (opencodeSurface !== undefined) stripLegacyOwnership(legacyDoc, legacyLockPath, opencodeSurface.file)
   }
@@ -113,6 +158,8 @@ export function deployHooks(options: DeployHooksOptions): DeployHooksResult {
     unchanged: unchanged.sort(),
     conflicts: conflicts.sort((a, b) => a.file.localeCompare(b.file)),
     lockPath: lockPathFor(targetRepo),
+    lockMigrated: lockMigrated.sort(),
+    restored,
   }
 }
 
@@ -129,6 +176,9 @@ interface DeploySurfaceContext {
   readonly written: string[]
   readonly unchanged: string[]
   readonly conflicts: HookConflict[]
+  readonly lockMigrated: string[]
+  readonly restored: RestoredHookReport[]
+  readonly dryRun: boolean
 }
 
 function deploySurface(surface: HookSurface, ctx: DeploySurfaceContext): void {
@@ -147,8 +197,10 @@ function deploySurface(surface: HookSurface, ctx: DeploySurfaceContext): void {
     const rendered = renderOpencodePlugin({ assetsDir: ctx.assetsDir, surface, hooksDoc: ctx.hooksDoc })
     const changed = !exists || readFileSync(targetAbs, 'utf8') !== rendered
     if (changed) {
-      mkdirSync(dirname(targetAbs), { recursive: true })
-      writeFileSync(targetAbs, rendered)
+      if (!ctx.dryRun) {
+        mkdirSync(dirname(targetAbs), { recursive: true })
+        writeFileSync(targetAbs, rendered)
+      }
       ctx.written.push(surface.file)
     } else {
       ctx.unchanged.push(surface.file)
@@ -157,25 +209,53 @@ function deploySurface(surface: HookSurface, ctx: DeploySurfaceContext): void {
     return
   }
 
-  const ownOwned = prevEntry !== undefined && prevEntry.format === surface.format ? prevEntry.ownedCommands : {}
+  // Ownership is content-addressed (json-merge.ts's own header, second
+  // independent review 2026-09-29): `recordedEntries` is THIS package's own
+  // prior write, read straight from the lock as hash+command pairs, never
+  // derived from command text alone. A lock with no `ownedEntries` at all
+  // (every repo enrolled before this fix) has no hashes to give — for
+  // exactly this one transitional deploy, its OLD `ownedCommands` feeds the
+  // command-anywhere fallback channel instead, unioned with
+  // `legacyTakeover.ownedByEvent` (the pre-agent-hooks engine's own
+  // hash-verified takeover signal — a different legacy source, same
+  // "command text is the only proof we have" shape).
+  const sameFormatPrev = prevEntry !== undefined && prevEntry.format === surface.format ? prevEntry : undefined
+  const isLegacyShapedLock = sameFormatPrev !== undefined && sameFormatPrev.ownedEntries === undefined
+  // Independent review, 2026-09-30, finding 7: this transitional deploy
+  // rewrites the LOCK from the legacy (`ownedCommands`-only) shape to the
+  // content-addressed one — report it, since the deployed JSON file can
+  // stay byte-identical while that rewrite happens underneath it.
+  if (isLegacyShapedLock) ctx.lockMigrated.push(surface.file)
+  const recordedEntries = sameFormatPrev?.ownedEntries ?? {}
+  const ownCommandsLegacyFallback = isLegacyShapedLock ? sameFormatPrev.ownedCommands : {}
   const existingRaw = readExistingJson(targetAbs)
   const legacyTakeover = legacyTakeoverForJsonHooksSurface(existingRaw, ctx.legacyDoc, surface.file)
   if (legacyTakeover.matched) ctx.takeover.any = true
-  const previousOwned = unionOwnedCommands(ownOwned, legacyTakeover.ownedByEvent)
+  const legacyCommandsAnywhere = unionOwnedCommands(ownCommandsLegacyFallback, legacyTakeover.ownedByEvent)
 
   if (surface.format === 'cursor-hooks-v1') {
     const desired = renderCursorEntries(ctx.hooksDoc, surface)
-    const { fileContent, ownedCommands, changed } = mergeCursorHooksFile(existingRaw, desired, previousOwned)
-    writeJsonIfChanged(targetAbs, fileContent, changed)
-    ;(changed ? ctx.written : ctx.unchanged).push(surface.file)
-    ctx.newEntries[surface.file] = { format: 'cursor-hooks-v1', ownedCommands }
+    const { fileContent, ownedCommands, ownedEntries, changed, restored, ambiguousConflicts } = mergeCursorHooksFile(existingRaw, desired, recordedEntries, legacyCommandsAnywhere)
+    writeJsonIfChanged(targetAbs, fileContent, changed, ctx.dryRun)
+    // Independent review, 2026-09-30, round 5, finding 4: a legacy lock
+    // migration rewrites the LOCK for real even when this surface's own
+    // deployed content stays byte-identical — count that as "written",
+    // not "unchanged", so a caller reading these two arrays (which is
+    // exactly what "up to date (no changes)" and "written: N" do) never
+    // reports a pure no-op when something real did change on disk.
+    ;(changed || isLegacyShapedLock ? ctx.written : ctx.unchanged).push(surface.file)
+    ctx.newEntries[surface.file] = { format: 'cursor-hooks-v1', ownedCommands, ownedEntries }
+    for (const hook of restored) ctx.restored.push(makeRestoredReport(surface.file, hook))
+    for (const conflict of ambiguousConflicts) ctx.conflicts.push({ file: surface.file, reason: ambiguousConflictReason(conflict) })
     return
   }
 
   // claude-settings | codex-hooks
   const desired = renderJsonHooksGroups(ctx.hooksDoc, surface)
-  const { fileContent, ownedCommands, changed } = mergeJsonHooksFile(existingRaw, desired, previousOwned)
-  writeJsonIfChanged(targetAbs, fileContent, changed)
-  ;(changed ? ctx.written : ctx.unchanged).push(surface.file)
-  ctx.newEntries[surface.file] = { format: surface.format, ownedCommands }
+  const { fileContent, ownedCommands, ownedEntries, changed, restored, ambiguousConflicts } = mergeJsonHooksFile(existingRaw, desired, recordedEntries, legacyCommandsAnywhere)
+  writeJsonIfChanged(targetAbs, fileContent, changed, ctx.dryRun)
+  ;(changed || isLegacyShapedLock ? ctx.written : ctx.unchanged).push(surface.file)
+  ctx.newEntries[surface.file] = { format: surface.format, ownedCommands, ownedEntries }
+  for (const hook of restored) ctx.restored.push(makeRestoredReport(surface.file, hook))
+  for (const conflict of ambiguousConflicts) ctx.conflicts.push({ file: surface.file, reason: ambiguousConflictReason(conflict) })
 }