@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/bin/lib/lean-ctx-observe-hooks.sh

@@ -0,0 +1,634 @@
+# Shared "strip raw per-user `lean-ctx hook <subcommand>` entries" primitive,
+# sourced by bin/lean-ctx-observe-strip (bin/reconcile's per-device step) and
+# by workflows/scripts/fleet/fleet-cutover.sh's strip_user_lean_ctx_hooks.
+#
+# Scope, in order of decision (all 2026-09-29, all Tarun, relayed through the
+# orchestrator in this same work item):
+#   1. STATUS.md 12p item 13: "That's only for observation layer. We don't
+#      want to send any data to remote." -- retracted the
+#      `/usr/local/bin/lean-ctx hook observe` session-lifecycle hook
+#      everywhere adl manages it.
+#   2. Final decision (supersedes an intermediate "observe only" correction
+#      that itself supersedes an intermediate "every subcommand" widening --
+#      this is the one that stands): lean-ctx hooks are "moved to repo
+#      level" and must be REMOVED FROM GLOBAL. The per-repo carrier already
+#      provides them -- `adl hook lean-ctx pre-tool-use|post-tool-use` (in
+#      each managed repo's own `.claude/settings.json`, `.codex/hooks.json`,
+#      etc., written by `adl hooks deploy`) maps to lean-ctx `rewrite`
+#      (Bash), `redirect` (Read/Grep/Glob/...) and `read-dedup` (PostToolUse
+#      Read) using the REPO's own `LEAN_CTX_*` config -- see
+#      `packages/agent-hooks/src/hooks/lean-ctx/mapping.ts` (CLAUDE routes,
+#      `pre`: rewrite/redirect, `post`: read-dedup). `observe` has no
+#      per-repo carrier at all and is dropped outright. So this strips EVERY
+#      raw, unwrapped `lean-ctx hook <subcommand>` entry found directly in a
+#      per-user config -- observe, rewrite, redirect, read-dedup, and any
+#      other subcommand -- never just observe.
+#
+# This file is the ONE place that knows what "a raw lean-ctx hook entry" is
+# and how to remove it, so bin/reconcile's recurring per-device
+# reconciliation and fleet-cutover.sh's one-time cutover can never drift
+# apart on the answer (before this, fleet-cutover.sh carried its own inline
+# jq queries -- observe-only -- and bin/reconcile had no strip step at all).
+#
+# What is NEVER touched, by construction of the match below:
+#   - `adl hook lean-ctx pre-tool-use|post-tool-use --host=<x>` (the per-repo
+#     carrier itself): the literal word order is "hook lean-ctx", never
+#     "lean-ctx hook" -- the substring this matches never appears in it.
+#   - Orca's own conditional hooks (`~/.orca/agent-hooks/*-hook.sh`): they
+#     never mention "lean-ctx" at all.
+#   - Kimi's per-user hooks (`adl hook lean-ctx ... --host=kimi`, written by
+#     packages/agent-settings/src/kimi-hooks.ts): same "hook lean-ctx" word
+#     order as the adl carrier above -- never matches either.
+#
+# Names below still say "observe" (this strip started as observe-only, and
+# renaming a shared, already-referenced identifier mid-flight risked a
+# missed call site more than it bought clarity) -- read them as "the
+# lean-ctx raw-hook strip", not as scoped to the `observe` subcommand alone;
+# the matching regex is the actual source of truth for scope.
+#
+# Scope -- which per-user files can actually carry a raw lean-ctx hook,
+# checked read-only against a real machine's files and this repo's own
+# docs/tests before writing this (bin/lean-ctx-observe-strip's own header
+# lists the two files this is actually run against):
+#   - `~/.claude/settings.json` and `~/.codex/hooks.json` share the same
+#     JSON `json-hook-map` shape (global-surface-sweep.ts's own term):
+#     `{ hooks: { <Event>: [ { matcher?, hooks: [ { command, ... } ] } ] } }`.
+#     This is the per-user hook shape that carried `lean-ctx hook observe`
+#     (the managed baseline wired it, identically, for Claude and Codex only
+#     -- "both templates" -- packages/agent-settings/managed/README.md's
+#     "lean-ctx `observe` hooks (removed)" section) and is where a real,
+#     live `~/.claude/settings.json` on this machine was found to also carry
+#     raw `rewrite`/`redirect`/`read-dedup` entries -- both files covered
+#     below.
+#   - `~/.cursor/hooks.json` uses a DIFFERENT per-group shape (the group
+#     itself IS the leaf hook -- `{ command, timeout }`, no nested `hooks`
+#     array; see global-surface-sweep.ts's own `json-hook-map` doc comment,
+#     confirmed against this machine's real `~/.cursor/hooks.json`, which
+#     carries no lean-ctx entries at all) -- NOT covered.
+#   - `~/.kimi-code/config.toml`'s hooks are a single flat `[[hooks]]`
+#     array-of-tables (packages/agent-settings/src/kimi-hooks.ts), and every
+#     command it ever writes is wrapped as `adl hook lean-ctx ... --host=kimi`
+#     (confirmed against this machine's real config) -- never a raw
+#     `lean-ctx hook <subcommand>` string -- NOT covered.
+#   - `~/.codex/config.toml` CAN structurally carry the same
+#     `[[hooks.<Event>]]` / `hooks = [{ command = ... }]` shape
+#     (`/etc/codex/requirements.toml`, the admin-tier twin of this exact per-
+#     user schema, proves the shape once carried `observe`), but on this
+#     machine it is empty of any `[hooks.*]` table, and no code path in this
+#     repo writes hooks into a per-user `~/.codex/config.toml` -- the real
+#     per-user Codex hook carrier is `~/.codex/hooks.json`, confirmed live on
+#     this machine with Orca's own entries -- NOT covered; flag for Tarun if
+#     that ever changes.
+#   - `~/.config/opencode/*` has no command-string hook carrier at all --
+#     OpenCode's carrier is a `.opencode/plugins/adl-repo.ts` JS/TS plugin
+#     file, structurally incapable of holding a raw `lean-ctx hook` shell-
+#     command string -- NOT covered.
+#
+# jq is a mandatory bootstrap tool for every caller of this file (checked at
+# each caller's own top), so no jq-availability fallback is needed here.
+
+# lean_ctx_observe_hook_valid <path> -- gate every caller runs before
+# treating <path> as a document to filter. A 0-byte/whitespace-only file
+# (jq's own parse error is silent-ish -- it just complains about no input)
+# and a file carrying two or more concatenated JSON documents (jq's default
+# single-value parse happily reads only the FIRST one and ignores the rest
+# -- exactly the "passes silently" bug this closes) must both be loud
+# failures, not a file that quietly gets treated as "no raw lean-ctx hook
+# entries found". `jq -se` slurps the whole input into an array of every
+# top-level JSON value it can parse: length 0 means empty/whitespace-only,
+# length >1 means more than one document, and a length-1 array whose sole
+# element is not a JSON object (a bare array, string, number, ...) is also
+# rejected -- a per-user hook-map file is always `{ ... }` at the top.
+# Returns non-zero (jq's own parse error, or the printed "false", both
+# treated as invalid) on anything else; callers report that as a loud parse
+# failure exactly like a malformed-JSON file already was.
+lean_ctx_observe_hook_valid() {
+  local path="$1" verdict
+  verdict="$(jq -se 'length == 1 and (.[0] | type) == "object"' "$path" 2>/dev/null)" || return 1
+  [[ "$verdict" == "true" ]]
+}
+
+# lean_ctx_observe_hook_events <path> -- prints a comma-joined list of event
+# names (the `hooks.<Event>` keys) that carry at least one hook group whose
+# command matches "lean-ctx hook <subcommand>" -- a raw, unwrapped
+# invocation of ANY lean-ctx hook subcommand (observe, rewrite, redirect,
+# read-dedup, or any other). The jq `test` is a plain substring match, so
+# any path spelling -- "/usr/local/bin/lean-ctx hook observe",
+# "/Users/x/.local/bin/lean-ctx hook rewrite" -- matches; only the literal,
+# adjacent "lean-ctx hook" phrase matters, which is exactly what
+# distinguishes a raw invocation from the per-repo carrier's
+# "adl hook lean-ctx ... --host=<x>" (reversed word order -- never matches)
+# and from Orca's own hooks (no "lean-ctx" at all -- never matches). Prints
+# nothing (empty string) when there are none. A malformed/unparseable JSON
+# file, a 0-byte/whitespace-only file, or a file carrying more than one JSON
+# document (lean_ctx_observe_hook_valid) is a loud failure (non-zero exit)
+# -- callers must check the exit status and fail, never silently skip a file
+# they could not read.
+lean_ctx_observe_hook_events() {
+  local path="$1"
+  lean_ctx_observe_hook_valid "$path" || return 1
+  jq -r '
+    (.hooks // {}) | to_entries[]
+    | select(.value | type == "array")
+    # `any(...)` collapses to one boolean per event -- an EVENT with two or
+    # more matching groups (a real shape: this machine'"'"'s own
+    # ~/.claude/settings.json PostToolUse carries both a raw observe hook
+    # AND a raw read-dedup hook as separate groups) must still print its key
+    # exactly once. The earlier `select(.value[] | ...)` form used a
+    # generator as the select condition, which jq re-emits the input once
+    # per truthy match -- duplicating the event name in the printed list.
+    | select(.value | any(.[] | .hooks[]?.command? // ""; test("lean-ctx hook")))
+    | .key
+  ' "$path" | paste -sd, -
+}
+
+# lean_ctx_observe_hook_filtered <path> <dst> -- writes the full document,
+# with every hook whose command matches a raw "lean-ctx hook <subcommand>"
+# invocation removed (see lean_ctx_observe_hook_events for exactly what
+# matches and what never does), DIRECTLY to <dst> (jq's own stdout
+# redirected straight to a file -- never captured into a bash variable via
+# `$(...)`, which would silently strip jq's own trailing newline; final
+# review finding 2). jq's output convention (exactly one trailing newline,
+# always) makes this a non-issue for JSON specifically, but writing
+# straight to a file removes the question entirely rather than relying on
+# that convention holding. A hook GROUP is dropped entirely only when
+# it HAD at least one hook and lost every one of them to this strip (never
+# left as an empty `{ hooks: [] }`); an EVENT key is dropped entirely only
+# when it HAD at least one group and lost every one of them the same way
+# (never left as an empty array) -- matching `json-hook-map`'s own
+# convention in global-surface-sweep.ts. Crucially, a group/event that was
+# ALREADY empty before this ran (`{ "hooks": [] }`, `"Notification": []`,
+# neither uncommon -- an editor or another tool can leave one behind) is
+# UNRELATED to this strip and is left exactly as it was, not swept up by the
+# same "empty means drop" rule: the `if ($before_len > 0) and (now empty)
+# then drop` guard below only fires when there was something to remove.
+# Every other top-level key, every other event, every other group and hook
+# (the `adl hook lean-ctx ... --host=<x>` per-repo carrier and Orca's own
+# conditional hook included) is left byte-for-byte untouched, in its
+# original order -- `to_entries | map | from_entries` never reorders JSON
+# object keys, and `.value |= (...)` / `.hooks |= (...)` update in place
+# rather than reconstructing the object, so an unrelated field (e.g. a
+# group's own `matcher`) survives untouched too. Callers must check the exit
+# status (a malformed input file fails loudly, same as
+# lean_ctx_observe_hook_events).
+lean_ctx_observe_hook_filtered() {
+  local path="$1" dst="$2"
+  lean_ctx_observe_hook_valid "$path" || return 1
+  jq '
+    .hooks |= (
+      to_entries
+      | map(
+          if (.value | type) == "array" then
+            (.value | length) as $event_before_len
+            | .value |= (
+                map(
+                  (.hooks // []) as $group_before
+                  | (.hooks |= map(select((.command? // "") | test("lean-ctx hook") | not))) as $filtered_group
+                  | if ($group_before | length) > 0 and (($filtered_group.hooks) | length) == 0
+                    then empty
+                    else $filtered_group
+                    end
+                )
+              )
+            | if ($event_before_len > 0) and ((.value | length) == 0)
+              then empty
+              else .
+              end
+          else
+            .
+          end
+        )
+      | from_entries
+    )
+  ' "$path" > "$dst"
+}
+
+# ---------------------------------------------------------------------------
+# The ONE safe writer both callers use to rewrite a target file in place,
+# replacing each caller's own former `printf ... >"$path.new"; mv -f
+# "$path.new" "$path"` pattern. Three bugs that pattern had, all closed here:
+#
+#   1. Symlinked target: `mv -f` REPLACES the symlink with a regular file --
+#      the inode `$path` used to point at (a dotfile-manager-managed config,
+#      for instance) is left completely unchanged, and `$path` itself stops
+#      being a symlink at all. lean_ctx_observe_hook_resolve_target below
+#      resolves the real target FIRST; the write goes through to that file,
+#      and the symlink survives, still pointing at it, exactly as before.
+#   2. Mode/ownership: a fresh `>` redirection creates its file at whatever
+#      mode the process' umask produces -- a 0600 target file does not stay
+#      0600. lean_ctx_observe_hook_write stats the resolved target's own
+#      mode and owner:group FIRST and chmod/chown's the temp file to match
+#      before the rename.
+#   3. A failing write step reported as success: `strip_one "$path" ||
+#      status=1` (the caller-side idiom both scripts use to keep going
+#      after one target fails) disables `set -e` for everything
+#      strip_one/strip_user_lean_ctx_hooks itself runs -- a later command's
+#      non-zero exit does not abort the function on its own. Every step
+#      below is therefore its own explicit `if`, not a bare statement: a
+#      failure removes the temp file, prints one "FAILED:" line to stderr,
+#      and returns 1 -- never a partial write silently treated as done.
+#
+# Portable across macOS (BSD stat/readlink) and Linux (GNU): no `stat -f`
+# (Linux), `stat -c` (macOS) or `readlink -f` (missing on macOS' BSD
+# readlink) assumed to exist on both.
+# ---------------------------------------------------------------------------
+
+# lean_ctx_observe_hook_resolve_target <path> -- prints the real,
+# non-symlink file <path> should be WRITTEN THROUGH TO: if <path> is a
+# symlink (however many hops deep -- a relative link target is resolved
+# against its own symlink's directory, matching normal filesystem
+# semantics), the final target; otherwise <path> itself, unchanged. Does
+# NOT require the target to already exist (a target that is about to be
+# created for the first time resolves to itself, same as a non-symlink
+# path).
+lean_ctx_observe_hook_resolve_target() {
+  local p="$1" link dir
+  while [[ -L "$p" ]]; do
+    link="$(readlink "$p")"
+    case "$link" in
+      /*) p="$link" ;;
+      *)
+        dir="$(dirname "$p")"
+        p="$dir/$link"
+        ;;
+    esac
+  done
+  printf '%s\n' "$p"
+}
+
+# lean_ctx_observe_hook_stat_mode <path> -- prints <path>'s permission bits
+# as a plain octal string (e.g. "600"), suitable for `chmod` as-is. Tries
+# BSD `stat -f` first (macOS), falls back to GNU `stat -c` (Linux).
+#
+# The two attempts are deliberately captured in SEPARATE command
+# substitutions, not chained as `stat -f ... || stat -c ...` inside one
+# `$(...)`. GNU coreutils' stat also accepts `-f`, but as its OWN flag
+# ("file system status" instead of "file status") -- it does not reject the
+# BSD spelling, it silently does something else: it treats the format string
+# ("%Lp") as a FILE argument, fails on that with a permission error (a
+# non-zero exit, so the naive `||` fallback does still fire), but ALSO
+# prints a multi-line filesystem-info block for "$1" to stdout before it
+# exits. Inside one shared `$(cmd1 || cmd2)`, that stray stdout output is
+# captured right alongside cmd2's real "%a" output, silently corrupting the
+# mode string. Capturing cmd1 in its own `out=$(...)` isolates its stdout
+# from the fallback and only ever uses it when cmd1 itself reported success.
+lean_ctx_observe_hook_stat_mode() {
+  local out
+  if out="$(stat -f '%Lp' "$1" 2>/dev/null)"; then
+    printf '%s\n' "$out"
+    return 0
+  fi
+  stat -c '%a' "$1"
+}
+
+# lean_ctx_observe_hook_stat_owner <path> -- prints "<uid>:<gid>" of <path>,
+# suitable for `chown` as-is. Same BSD-then-GNU portability story, and the
+# same isolated-capture fix as lean_ctx_observe_hook_stat_mode above (GNU
+# stat's own `-f` meaning would otherwise leak a filesystem-info block into
+# the captured value here too).
+lean_ctx_observe_hook_stat_owner() {
+  local out
+  if out="$(stat -f '%u:%g' "$1" 2>/dev/null)"; then
+    printf '%s\n' "$out"
+    return 0
+  fi
+  stat -c '%u:%g' "$1"
+}
+
+# lean_ctx_observe_hook_write <path> <content_src> -- writes the BYTES of
+# <content_src> (a file -- final review finding 2: a bash string argument
+# here, written back with `printf '%s\n'`, silently drops any trailing
+# blank lines the original had and adds a final newline where the original
+# had none; a file-to-file copy has no such normalization) through to
+# <path>'s resolved real target (lean_ctx_observe_hook_resolve_target),
+# preserving that target's existing mode and owner:group, via a same-
+# directory temp file and an atomic rename. Prints nothing on success;
+# prints one "FAILED: ..." line to stderr and returns 1 on any failed step,
+# with the temp file removed either way -- never a half-written target, and
+# never a failure that looks like success to a caller that only checks
+# whether output changed. <path> keeps being a symlink (untouched) when it
+# was one; the file it points to carries the new content.
+#
+# The temp file itself is created with `mktemp` using the portable
+# same-directory dotfile template (`.$(basename).XXXXXX`, works identically
+# under BSD and GNU mktemp -- final review finding 5), not the previous
+# `$resolved.new.$$` -- a PID-suffixed name is predictable, `mktemp`'s is
+# not, and mktemp creates the file atomically (O_EXCL) rather than merely
+# naming one.
+lean_ctx_observe_hook_write() {
+  local path="$1" content_src="$2"
+  local resolved mode owner tmp
+  resolved="$(lean_ctx_observe_hook_resolve_target "$path")"
+  mode="$(lean_ctx_observe_hook_stat_mode "$resolved")" || {
+    echo "FAILED: could not stat mode of $resolved" >&2
+    return 1
+  }
+  owner="$(lean_ctx_observe_hook_stat_owner "$resolved")" || {
+    echo "FAILED: could not stat owner of $resolved" >&2
+    return 1
+  }
+  tmp="$(mktemp "$(dirname "$resolved")/.$(basename "$resolved").XXXXXX" 2>/dev/null)" || {
+    echo "FAILED: mktemp for $resolved failed" >&2
+    return 1
+  }
+  if ! cat "$content_src" >"$tmp" 2>/dev/null; then
+    echo "FAILED: writing $tmp failed" >&2
+    rm -f "$tmp" 2>/dev/null
+    return 1
+  fi
+  if ! chmod "$mode" "$tmp" 2>/dev/null; then
+    echo "FAILED: chmod $mode $tmp failed" >&2
+    rm -f "$tmp" 2>/dev/null
+    return 1
+  fi
+  if ! chown "$owner" "$tmp" 2>/dev/null; then
+    echo "FAILED: chown $owner $tmp failed" >&2
+    rm -f "$tmp" 2>/dev/null
+    return 1
+  fi
+  if ! mv -f "$tmp" "$resolved" 2>/dev/null; then
+    echo "FAILED: mv $tmp -> $resolved failed" >&2
+    rm -f "$tmp" 2>/dev/null
+    return 1
+  fi
+  return 0
+}
+
+# ---------------------------------------------------------------------------
+# Second carrier (2026-09-29, Tarun, relayed through the orchestrator,
+# same STATUS.md 12p item 13): THREE marker-block shapes `lean-ctx setup`
+# writes into shell rc/env files, all confirmed live against a real
+# (throwaway, HOME-overridden) `lean-ctx setup --non-interactive --yes` run
+# of the actually-installed `/usr/local/bin/lean-ctx` (3.10.5) -- byte-level
+# (`python3 -c "open(...,'rb').read()"`), not guessed from the task
+# description, and not assumed unchanged from an earlier, less precise
+# `cat -A` read (that read rendered the em dash below ambiguously; the byte
+# dump settled it as literal UTF-8 U+2014, not the text "\u{2014}"):
+#
+#   1. The universal shell hook, written into `~/.zshenv` and `~/.bashenv`:
+#        # >>> lean-ctx shell hook >>>
+#        ...body...
+#        # <<< lean-ctx shell hook <<<
+#   2. `~/.zshrc`'s OWN differently-shaped block (an em dash, not `>>>`/
+#      `<<<`), sourcing a separate `~/.config/lean-ctx/shell-hook.zsh`:
+#        # lean-ctx shell hook — begin
+#        if [ -f "$HOME/.config/lean-ctx/shell-hook.zsh" ]; then
+#          . "$HOME/.config/lean-ctx/shell-hook.zsh"
+#        fi
+#        # lean-ctx shell hook — end
+#   3. `~/.bashrc` and `~/.zshrc`'s agent-launcher aliases:
+#        # >>> lean-ctx agent aliases >>>
+#        alias claude='LEAN_CTX_AGENT=1 BASH_ENV="$HOME/.bashenv" claude'
+#        ...codebuddy/codex/gemini, same shape...
+#        # <<< lean-ctx agent aliases <<<
+#      Tarun's OWN unmarked aliases in his real `~/.zshrc` (no `LEAN_CTX_
+#      AGENT=1` prefix -- he already hand-edited them once) sit right next
+#      to where a marked block like this would live and MUST survive
+#      byte-for-byte; the strip below matches ONLY the exact marker lines,
+#      never alias syntax in general, so it cannot catch them.
+#
+# `~/.config/lean-ctx/` itself (the directory shape 2 above sources) is
+# deliberately left alone -- Tarun uses the global CLI directly from his
+# own terminal -- flagged in this header and in STATUS.md, not stripped.
+LEAN_CTX_SHELL_HOOK_OPEN_MARKER='# >>> lean-ctx shell hook >>>'
+LEAN_CTX_SHELL_HOOK_CLOSE_MARKER='# <<< lean-ctx shell hook <<<'
+LEAN_CTX_ZSHRC_HOOK_OPEN_MARKER='# lean-ctx shell hook — begin'
+LEAN_CTX_ZSHRC_HOOK_CLOSE_MARKER='# lean-ctx shell hook — end'
+LEAN_CTX_AGENT_ALIASES_OPEN_MARKER='# >>> lean-ctx agent aliases >>>'
+LEAN_CTX_AGENT_ALIASES_CLOSE_MARKER='# <<< lean-ctx agent aliases <<<'
+
+# lean_ctx_shell_rc_scan_and_filter <src> <dst> <report_file> -- the ONE
+# single-pass engine covering all three marker shapes above, replacing an
+# earlier design that chained three separate awk invocations through bash
+# STRING variables (`$(...)` captures). That design had two review findings
+# against it, both closed here:
+#
+#   Finding 2 (byte fidelity): `$(...)` unconditionally strips ALL trailing
+#   newlines from whatever it captures, and the old writer re-added exactly
+#   one via `printf '%s\n'` -- so a file with two trailing blank lines lost
+#   one, and a file with NO trailing newline gained one it never had. This
+#   version never round-trips content through a bash string at all: awk
+#   reads <src> and writes <dst> directly (`awk '...' "$src" > "$dst"`),
+#   which is already byte-exact for everything except awk's own `print`
+#   unconditionally appending an ORS to its LAST output record -- the one
+#   remaining gap, closed by the `had_trailing_nl` flag below (computed
+#   from <src>'s own true last byte, via `tail -c1`, never through a
+#   content-losing capture) and used ONLY for the final `held` value in
+#   END, which by construction is either empty or is exactly <src>'s own
+#   true final record (anything printed earlier, mid-stream, already had
+#   something come after it in the source, so it was always genuinely
+#   newline-terminated and needs no special-casing).
+#
+#   Finding 4 (malformed nesting): a SINGLE pass with one `in_shape` state
+#   (0, or 1/2/3 for "inside shape N's block") can directly detect a
+#   duplicate/nested opening marker (any shape's open line seen while
+#   `in_shape != 0`) and an orphan closing marker (any shape's close line
+#   seen while NOT inside that shape's own block) -- both loud failures,
+#   naming <src> and the 1-based line number, before any write; the old
+#   three-separate-passes design could not see shape 2's open marker while
+#   evaluating shape 1's pass, so nothing could ever have caught this.
+#
+# Finding 3 (silent misses) is also closed here: every marker comparison
+# trims trailing `[ \t\r]` first (a marker line with a trailing space, or
+# from a CRLF file, still matches -- SPACES/TABS/CR are the only ones
+# trimmed; a byte-for-byte different marker string is still a genuine
+# non-match), and any line that MENTIONS "lean-ctx shell hook" or
+# "lean-ctx agent aliases" without exactly matching one of the six known
+# marker lines (open/close x 3 shapes) is ALSO a loud, named failure --
+# closing the silent-miss risk of a near-miss marker (trailing space, wrong
+# case, a stray character) leaving its carrier un-stripped with no signal
+# at all. The trailing-`\r` trim is comparison-only: raw `$0`/`line` (never
+# the trimmed `norm`) is what gets held/printed, so byte-for-byte
+# preservation of surviving content -- CRLF line endings included -- holds
+# for the marker-recognition widening too.
+#
+# Reports which of the three shapes were found via <report_file> (three
+# lines, "1:present"/"1:absent", "2:...", "3:..."), a plain side file (not
+# awk's main output stream, which is the filtered <dst>) the caller reads
+# back to decide what to print and whether anything needs backing up.
+lean_ctx_shell_rc_scan_and_filter() {
+  local src="$1" dst="$2" report_file="$3"
+  local had_trailing_nl=1
+  if [[ -s "$src" ]] && [[ -n "$(tail -c1 "$src" 2>/dev/null)" ]]; then
+    had_trailing_nl=0
+  fi
+  # NOTE: awk variables are openN/closeN, not open/close -- `close` is a
+  # POSIX awk BUILT-IN function name (closes a getline/print stream), and
+  # BSD awk (macOS's /usr/bin/awk) refuses to parse it as a plain variable
+  # -- a real syntax error found by actually running this on macOS.
+  awk \
+    -v srcname="$src" \
+    -v report_file="$report_file" \
+    -v had_trailing_nl="$had_trailing_nl" \
+    -v open1="$LEAN_CTX_SHELL_HOOK_OPEN_MARKER" -v close1="$LEAN_CTX_SHELL_HOOK_CLOSE_MARKER" \
+    -v open2="$LEAN_CTX_ZSHRC_HOOK_OPEN_MARKER" -v close2="$LEAN_CTX_ZSHRC_HOOK_CLOSE_MARKER" \
+    -v open3="$LEAN_CTX_AGENT_ALIASES_OPEN_MARKER" -v close3="$LEAN_CTX_AGENT_ALIASES_CLOSE_MARKER" \
+    '
+    BEGIN { in_shape = 0; have_held = 0; malformed = 0 }
+    {
+      line = $0
+      norm = line
+      sub(/[ \t\r]+$/, "", norm)
+
+      is_open1 = (norm == open1); is_close1 = (norm == close1)
+      is_open2 = (norm == open2); is_close2 = (norm == close2)
+      is_open3 = (norm == open3); is_close3 = (norm == close3)
+      is_any_open = is_open1 || is_open2 || is_open3
+      is_any_close = is_close1 || is_close2 || is_close3
+      is_known_marker = is_any_open || is_any_close
+
+      mentions = (index(norm, "lean-ctx shell hook") > 0) || (index(norm, "lean-ctx agent aliases") > 0)
+      if (mentions && !is_known_marker) {
+        printf "lean-ctx-observe-strip: %s:%d: unrecognized lean-ctx marker-like line (mentions the marker phrase but is not exactly a known marker line): %s\n", srcname, NR, line > "/dev/stderr"
+        malformed = 1
+        exit 1
+      }
+
+      if (in_shape != 0) {
+        if ((in_shape == 1 && is_close1) || (in_shape == 2 && is_close2) || (in_shape == 3 && is_close3)) {
+          in_shape = 0
+          next
+        }
+        if (is_any_open) {
+          printf "lean-ctx-observe-strip: %s:%d: malformed nesting -- an opening marker appears while already inside a lean-ctx marker block: %s\n", srcname, NR, line > "/dev/stderr"
+          malformed = 1
+          exit 1
+        }
+        if (is_any_close) {
+          printf "lean-ctx-observe-strip: %s:%d: malformed marker -- a closing marker for a different lean-ctx block appears here, while a different block is still open: %s\n", srcname, NR, line > "/dev/stderr"
+          malformed = 1
+          exit 1
+        }
+        next
+      }
+
+      if (is_any_close) {
+        printf "lean-ctx-observe-strip: %s:%d: malformed marker -- an orphan closing marker with no matching opening marker: %s\n", srcname, NR, line > "/dev/stderr"
+        malformed = 1
+        exit 1
+      }
+
+      shape = is_open1 ? 1 : (is_open2 ? 2 : (is_open3 ? 3 : 0))
+      if (shape != 0) {
+        held_blank = held
+        sub(/\r$/, "", held_blank)
+        if (have_held && held_blank != "") { print held }
+        have_held = 0
+        in_shape = shape
+        found[shape] = 1
+        next
+      }
+
+      if (have_held) { print held }
+      held = line
+      have_held = 1
+    }
+    END {
+      if (malformed) { exit 1 }
+      if (in_shape != 0) {
+        shape_label = (in_shape == 1) ? "lean-ctx shell hook" : ((in_shape == 2) ? "lean-ctx shell hook (zshrc begin/end form)" : "lean-ctx agent aliases")
+        printf "lean-ctx-observe-strip: %s: unclosed %s marker block -- opening line with no closing line before EOF\n", srcname, shape_label > "/dev/stderr"
+        exit 1
+      }
+      if (have_held) {
+        if (had_trailing_nl) { print held } else { printf "%s", held }
+      }
+      printf "1:%s\n", (found[1] ? "present" : "absent") > report_file
+      printf "2:%s\n", (found[2] ? "present" : "absent") > report_file
+      printf "3:%s\n", (found[3] ? "present" : "absent") > report_file
+      close(report_file)
+    }
+  ' "$src" > "$dst"
+}
+
+# ---------------------------------------------------------------------------
+# Third carrier, same item: global lean-ctx SKILL.md directories written by
+# `lean-ctx setup` (confirmed live, same throwaway run as above, with
+# auto_inject_skills enabled): $HOME/.claude/skills/lean-ctx,
+# $HOME/.codex/skills/lean-ctx, $HOME/.cursor/skills/lean-ctx,
+# $HOME/.config/opencode/skills/lean-ctx, $HOME/.agents/skills/lean-ctx --
+# each a directory whose SKILL.md starts with a YAML frontmatter block
+# whose `name:` key is exactly `lean-ctx` (confirmed verbatim:
+# `---\nname: lean-ctx\ndescription: ...\n---`). Never deleted, only moved
+# (this strip's directory-level unit of change is the whole directory, not
+# individual file content, so there is no write-through-symlink story here
+# the way there is for the JSON and shell-hook carriers above -- a
+# symlinked skill directory is relocated by moving the symlink itself,
+# which correctly leaves whatever real directory it pointed at completely
+# untouched on disk, exactly as "never delete" requires).
+LEAN_CTX_SKILL_FRONTMATTER_NAME='lean-ctx'
+
+# lean_ctx_skill_frontmatter_name <SKILL.md path> -- prints the trimmed,
+# quote-stripped value of the frontmatter `name:` key, or nothing if
+# <path> does not open with a `---` frontmatter fence, or the fence closes
+# before any `name:` key is found. Never fails (a missing/unreadable file
+# is indistinguishable from "no name found" here -- the caller already
+# gates on the file's existence before calling this). Every comparison
+# strips a trailing `\r` first (final review finding 3: a CRLF-saved
+# SKILL.md -- `---\r\n`, `name: lean-ctx\r\n` -- must still be recognized;
+# `$0 == "---"` and the `name:` match would both silently miss a bare
+# trailing `\r` otherwise, reporting "no name found" instead of the real
+# value).
+lean_ctx_skill_frontmatter_name() {
+  local path="$1"
+  awk '
+    {
+      line = $0
+      sub(/\r$/, "", line)
+    }
+    NR == 1 {
+      if (line == "---") { infm = 1; next }
+      exit
+    }
+    infm {
+      if (line == "---") { exit }
+      if (line ~ /^name:[ \t]*/) {
+        val = line
+        sub(/^name:[ \t]*/, "", val)
+        gsub(/^[\"'"'"' \t]+|[\"'"'"' \t]+$/, "", val)
+        print val
+        exit
+      }
+    }
+  ' "$path" 2>/dev/null
+}
+
+# ---------------------------------------------------------------------------
+# Final review finding 5 (defence in depth): bin/reconcile's apply path
+# never runs this script as literal root against another user's home --
+# macOS drops to `sudo -u "$administrator"` first (bin/reconcile:2518, the
+# `--home "$administrator_home"` in that same call is always that SAME
+# administrator's own home); Linux's administrator IS root, with home
+# `/root` (`sudo -u root` is a no-op privilege-wise, and `--home` matches).
+# This guard catches the ONE misuse those two shapes never produce: running
+# this script directly as literal root (EUID 0) with `--home` pointing at
+# a home it does NOT own -- which would write files owned by root into
+# another user's per-user config, silently breaking that user's own tools.
+# ---------------------------------------------------------------------------
+
+# lean_ctx_observe_strip_guard_euid <euid> <home> -- prints a "refusing"
+# message to stderr and returns 1 when <euid> is 0 (root) but <home>'s
+# OWNER uid is not also 0; returns 0 (silent) in every other case,
+# including <euid> != 0 (the ordinary macOS shape -- reconcile has already
+# dropped to the administrator before this script ever runs) and <euid> ==
+# 0 with a root-owned <home> (the ordinary Linux shape -- administrator IS
+# root, home IS /root). A pure function of its two arguments, not of the
+# process' own real $EUID, specifically so it can be exercised directly
+# with fabricated uid/home pairs -- bin/lean-ctx-observe-strip itself calls
+# it with the process' real $EUID, which is the one line that cannot be
+# exercised without actually running as root (not available in this
+# sandboxed test environment; per the review's own instruction, no new env
+# var was invented to fake it -- this function signature, taking the uid as
+# a plain argument, is the seam instead).
+lean_ctx_observe_strip_guard_euid() {
+  local euid="$1" home="$2" owner
+  [[ "$euid" == 0 ]] || return 0
+  owner="$(lean_ctx_observe_hook_stat_owner "$home" 2>/dev/null)" || {
+    echo "lean-ctx-observe-strip: refusing -- running as root (EUID=0) but could not determine the owner of --home $home" >&2
+    return 1
+  }
+  local owner_uid="${owner%%:*}"
+  [[ "$owner_uid" == 0 ]] && return 0
+  echo "lean-ctx-observe-strip: refusing -- running as root (EUID=0) against --home $home, owned by uid $owner_uid, not root. bin/reconcile's apply path always runs this script via 'sudo -u <administrator>' (or, on Linux, as root against root's own /root), so it should never execute as literal root against a non-root user's home. Re-run as that user, or via 'sudo -u <that user> lean-ctx-observe-strip --home $home --mode ...'." >&2
+  return 1
+}

package/bin/managed-settings

@@ -0,0 +1,14 @@
+#!/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"
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(cd "$script_dir/.." && pwd)"
+
+command -v bun >/dev/null 2>&1 || {
+  echo "managed-settings requires bun; reconcile the global-tools manifest first" >&2
+  exit 1
+}
+
+exec bun "$repo_root/packages/fleet/src/managed-settings.ts" "$@"

package/bin/opencode-hooks

@@ -0,0 +1,14 @@
+#!/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"
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(cd "$script_dir/.." && pwd)"
+
+command -v bun >/dev/null 2>&1 || {
+  echo "opencode-hooks requires bun; reconcile the global-tools manifest first" >&2
+  exit 1
+}
+
+exec bun "$repo_root/packages/agent-settings/src/opencode-hooks.ts" "$@"