agent-bios 0.9.8 → 0.10.0

package/install.sh

@@ -0,0 +1,1233 @@
+#!/usr/bin/env bash
+# agent-bios installer.
+#
+# Deploys the single-source-of-truth (globals, scoped guides, Codex agent
+# templates, Codex wrappers, the launch profile/shell/bin, a managed Textual
+# venv, and the zsh hook) into $HOME by COPY — idempotent, backed up before
+# overwrite, and reversible. Distributed as an npm bin; the actual $HOME
+# deployment is this explicit command (never a postinstall side effect).
+#
+# Usage:
+#   agent-bios install     deploy into this environment (backs up + verifies)
+#   agent-bios verify      check the deployed state matches the source
+#   agent-bios status      show what is installed and where
+#   agent-bios update      git pull + reinstall (clone), or print the npm update line
+#   agent-bios uninstall   remove deployed files and the zsh hook
+#   agent-bios help
+#
+# Flags: --dry-run (print actions, change nothing).
+# Env overrides: CLAUDE_CONFIG_DIR, CODEX_HOME, AGENT_LAUNCH_VENV, ZDOTDIR.
+set -euo pipefail
+
+# This installer is non-interactive: every input arrives as a subcommand, flag,
+# or env var. Detach stdin so no child (the codex-helm dry-run, pip, git) can
+# block forever on an inherited idle stdin — that is what hangs an install under
+# CI, pipes, and background runs, where stdin stays open but never delivers.
+# `learn` is the one subcommand whose payload IS stdin, so keep the caller's on
+# fd 3 first and hand it back only there; every other path still sees /dev/null.
+# The braces matter. `exec` with redirections and no command applies them to the
+# SHELL, permanently — so the bare `exec 3<&0 2>/dev/null` this used to be sent
+# every later error message on this script's stderr to /dev/null: bash's own
+# set -e diagnostics, python tracebacks from deployed steps, and any `>&2` an
+# author writes. Only stdout survived, which is why a failing install could stop
+# with no reason on screen. The group scopes the suppression to the one command
+# whose error is expected when a caller closed fd 0.
+{ exec 3<&0; } 2>/dev/null || exec 3</dev/null   # tolerate a caller that closed fd 0
+exec </dev/null
+
+# Resolve this script through symlinks before locating the package: npm links the
+# bin into node_modules/.bin and the global bin dir, so $0 is a link and its
+# dirname is the link's directory, not the package. Without this the source tree
+# resolves to the bin dir's parent (e.g. /opt/homebrew) and every deploy fails.
+SOURCE="${BASH_SOURCE[0]}"
+while [ -L "$SOURCE" ]; do
+  LINKDIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  case "$SOURCE" in
+    /*) ;;
+    *) SOURCE="$LINKDIR/$SOURCE" ;;
+  esac
+done
+SELF="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+REPO="$SELF"
+
+CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+CODEX_DIR="${CODEX_HOME:-$HOME/.codex}"
+LAUNCH_DIR="$HOME/.config/agent-launch"
+USER_PRESETS_NAME="presets.local.toml"  # user-owned; never deployed or verified
+BIN_DIR="$HOME/.local/bin"
+STATE_DIR="$HOME/.local/share/agent-bios"
+LEGACY_STATE_DIR="$HOME/.local/share/agent-dotfiles"  # pre-rename state; migrated on first run
+MANIFEST="$STATE_DIR/manifest.txt"
+# The manifest is truncated at the start of every install, so what the PREVIOUS one deployed
+# must be preserved before that happens. It is the only record that a file now on disk was
+# written by us rather than authored by the user, and seed_entry needs exactly that to tell a
+# previous release's deployed entry from someone's own CLAUDE.md.
+PRIOR_MANIFEST="$STATE_DIR/manifest.prev.txt"
+ZSHRC="${ZDOTDIR:-$HOME}/.zshrc"
+ZSH_HOOK='[ -r "$HOME/.config/agent-launch/shell.zsh" ] && source "$HOME/.config/agent-launch/shell.zsh"'
+HOOK_MARK='agent-launch/shell.zsh'
+
+DRY_RUN=0
+BACKUP_DIR=""
+
+log()  { printf '%s\n' "$*"; }
+info() { printf '  %s\n' "$*"; }
+run()  { if [ "$DRY_RUN" = 1 ]; then printf '  [dry-run] %s\n' "$*"; else "$@"; fi; }
+
+# ---- prerequisites -------------------------------------------------------
+check_prereqs() {
+  local ok=0
+  command -v git >/dev/null 2>&1 || { log "missing prerequisite: git"; ok=1; }
+  command -v python3 >/dev/null 2>&1 || { log "missing prerequisite: python3"; ok=1; }
+  if command -v python3 >/dev/null 2>&1; then
+    python3 -c 'import sys; sys.exit(0 if sys.version_info>=(3,11) else 1)' 2>/dev/null \
+      || { log "python3 >= 3.11 required (tomllib)"; ok=1; }
+  fi
+  command -v zsh >/dev/null 2>&1 || log "note: zsh not found; the shell hook targets zsh"
+  command -v codex >/dev/null 2>&1 || log "note: codex CLI not found; Codex-side steps will be skipped"
+  command -v claude >/dev/null 2>&1 || log "note: claude CLI not found"
+  return $ok
+}
+
+# ---- copy with backup + manifest ----------------------------------------
+deploy_file() {
+  local src="$1" dst="$2" mode="${3:-}"
+  [ -f "$src" ] || { log "source missing: $src"; return 1; }
+  if [ -f "$dst" ] && cmp -s "$src" "$dst"; then
+    info "unchanged  $dst"
+  else
+    if [ -f "$dst" ] && [ -n "$BACKUP_DIR" ]; then
+      run mkdir -p "$(dirname "$BACKUP_DIR$dst")"
+      run cp "$dst" "$BACKUP_DIR$dst"
+    fi
+    run mkdir -p "$(dirname "$dst")"
+    run cp "$src" "$dst"
+    if [ -n "$mode" ]; then run chmod "$mode" "$dst"; fi
+    [ "$DRY_RUN" = 1 ] || info "installed  $dst"
+  fi
+  [ "$DRY_RUN" = 1 ] || printf '%s\n' "$dst" >> "$MANIFEST"
+}
+
+deploy_glob() {
+  local srcdir="$1" pat="$2" dstdir="$3" mode="${4:-}" f
+  for f in "$srcdir"/$pat; do
+    [ -f "$f" ] || continue
+    deploy_file "$f" "$dstdir/$(basename "$f")" "$mode"
+  done
+}
+
+# Backups are made on every install and every uninstall, and nothing used to remove them — 23
+# directories in two weeks on the first machine measured, plus loose `.bak-*` files sitting in
+# the user's own config dirs. Pruning runs AFTER the new copy exists, never before, so a failed
+# run cannot leave the user with neither the change nor its backup.
+prune_backups() {
+  [ -f "$REPO/compose/prune-backups.py" ] || return 0
+  python3 "$REPO/compose/prune-backups.py" --state-dir "$STATE_DIR" \
+    --claude-dir "$CLAUDE_DIR" --codex-dir "$CODEX_DIR" \
+    $([ "$DRY_RUN" = 1 ] && echo --dry-run) || log "note: backup pruning skipped"
+}
+
+# Guides whose frontmatter declares `audience: author`. They document steps only
+# the corpus author can perform and name paths that exist in a checkout and
+# nowhere else, so they are never installed. compose/assemble.py owns the
+# declaration and withholds them from the destinations it writes; this asks it
+# rather than keeping a second parser. Both callers below need that same answer
+# for ground the assembler never writes — the sweep of the pre-unification
+# $CLAUDE_DIR/guides, and verify's check that the absence holds in all three
+# directories. Absence of the assembler degrades to withholding nothing.
+# Fails LOUD, never open. An empty answer here means "withhold nothing", so
+# swallowing an unreadable declaration would deploy exactly the guides this rule
+# exists to hold back — the fail-open shape of every other degrade-on-absence
+# fallback in this file, but inverted. compose/assemble.py ships, so its absence
+# is a broken payload rather than a configuration a user might have.
+author_only_guides() {
+  local out
+  if ! out=$(python3 - "$REPO" <<'PY'
+import pathlib, sys
+root = pathlib.Path(sys.argv[1])
+sys.path.insert(0, str(root / "compose"))
+try:
+    from assemble import author_only
+except ImportError as exc:
+    raise SystemExit(f"compose/assemble.py owns the audience declaration and "
+                     f"could not be imported ({exc})")
+guides = root / "claude" / "guides"
+if not guides.is_dir():
+    raise SystemExit(f"{guides} is missing; the payload is incomplete")
+for p in sorted(guides.glob("*.md")):
+    if author_only(p):
+        print(p.name)
+PY
+  ); then
+    # stderr, not stdout: every caller reads this function through a command
+    # substitution, so anything printed normally would be captured INTO the
+    # variable instead of reaching the operator — and `exit` here would leave
+    # only the subshell, letting the caller proceed with the error text as its
+    # list of withheld guides. The caller checks the status and exits itself.
+    log "cannot read which guides are author-only — refusing to deploy rather than" >&2
+    log "  shipping them by default. compose/assemble.py owns that declaration and" >&2
+    log "  must be present; reinstall the package." >&2
+    return 1
+  fi
+  printf '%s\n' "$out"
+}
+
+# Remove a withheld guide from a directory this installer deploys into, backing it
+# up first exactly as deploy_file backs up a file it is about to overwrite. An
+# unconditional rm would delete a same-named file this installer never wrote, and
+# a shared or symlinked guides directory makes that somebody's own file.
+prune_withheld() {
+  local dstdir="$1" base
+  printf '%s\n' "$WITHHELD_GUIDES" | while IFS= read -r base; do
+    [ -n "$base" ] || continue
+    [ -f "$dstdir/$base" ] || continue
+    if [ -n "$BACKUP_DIR" ]; then
+      run mkdir -p "$(dirname "$BACKUP_DIR$dstdir/$base")"
+      run cp "$dstdir/$base" "$BACKUP_DIR$dstdir/$base"
+    fi
+    run rm -f "$dstdir/$base"
+    [ "$DRY_RUN" = 1 ] || info "withheld (audience: author), removed stale copy: $dstdir/$base"
+  done
+}
+
+# ---- corpus deploy -------------------------------------------------------
+# assemble.py owns the corpus surfaces (central tree, entry seeding, codex marker region,
+# settings merge). The entry CLAUDE.md and AGENTS.md are NOT manifested — the entry is
+# user-owned after seeding and AGENTS.md holds a personal region — so uninstall removes our
+# central tree and marked regions and leaves the user's file itself alone.
+# There is ONE install shape. There used to be two: a "full" deploy that wrote the corpus into
+# the entry file, and a packaged one that assembled selected domains under `central/` and left the
+# entry file to the user. They differed in the thing that matters most — who owns the entry file —
+# so the same path was ours in one mode and theirs in the other, and no rule about user-owned
+# content could be true of both. Full mode is now "every domain selected": the same assembly, the
+# same ownership, one set of answers.
+#
+# What this buys, in the order the questions were asked: the user's own additions live in a file
+# we never rewrite, so they are separately versioned by construction; a package can be added or
+# dropped later by re-assembling, with no need to know which bytes came from where; and uninstall
+# can take everything of ours because nothing of theirs is mixed into it.
+assemble_corpus() {
+  local args=(--claude-dir "$CLAUDE_DIR" --codex-dir "$CODEX_DIR" --state-dir "$STATE_DIR") rc=0
+  if [ "${DOMAINS_SET:-0}" = 1 ]; then
+    args+=(--domains "$DOMAINS_ARG")
+  elif [ ! -f "$STATE_DIR/selection.json" ]; then
+    # No flag and no saved selection: install everything. This is what "full" meant, expressed as
+    # a selection so it goes down the same path as every other one.
+    args+=(--domains "$(python3 -c "import json,sys;print(','.join(sorted(json.load(open(sys.argv[1]))['domains'])))" "$REPO/compose/domains.json")")
+  fi
+  [ "$DRY_RUN" = 1 ] && args+=(--dry-run)
+  # A dry run never truncated the manifest, so the live one still describes the last install.
+  local prior="$PRIOR_MANIFEST"
+  [ "$DRY_RUN" = 1 ] && prior="$MANIFEST"
+  [ -f "$prior" ] && args+=(--prior-manifest "$prior")
+  python3 "$REPO/compose/assemble.py" "${args[@]}" || rc=$?
+  if [ "$rc" = 2 ]; then
+    log "entry file needs user action (import line missing); central content will not load until it is added"
+  elif [ "$rc" != 0 ]; then
+    return 1
+  fi
+  if [ "$DRY_RUN" != 1 ]; then
+    # `central/` is ours whole, so scanning it is right. `$CODEX_DIR/guides` is SHARED — the
+    # user and other tools keep files there, and the assembler deliberately leaves any name it
+    # did not deploy alone. Scanning that directory claimed those files anyway, and uninstall
+    # removes whatever the manifest names, so the protection was undone one step later. The
+    # ownership rule is the assembler's: the name exists in our source tree.
+    find "$CLAUDE_DIR/central" -type f 2>/dev/null >> "$MANIFEST"
+    local g dst
+    for g in "$REPO"/codex/guides/*.md; do
+      [ -f "$g" ] || continue
+      dst="$CODEX_DIR/guides/$(basename "$g")"
+      [ -f "$dst" ] && printf '%s\n' "$dst" >> "$MANIFEST"
+    done
+  fi
+}
+
+add_zsh_hook() {
+  if [ -f "$ZSHRC" ] && grep -qF "$HOOK_MARK" "$ZSHRC"; then
+    info "zsh hook present  $ZSHRC"
+    return
+  fi
+  if [ "$DRY_RUN" = 1 ]; then info "[dry-run] append zsh hook to $ZSHRC"; return; fi
+  printf '%s\n' "$ZSH_HOOK" >> "$ZSHRC"
+  info "added zsh hook  $ZSHRC"
+}
+
+# Carry state written under the pre-rename directory so an existing install keeps
+# its manifest and backups instead of stranding them.
+migrate_state() {
+  if [ -d "$STATE_DIR" ] || [ ! -d "$LEGACY_STATE_DIR" ]; then
+    return
+  fi
+  if [ "$DRY_RUN" = 1 ]; then
+    info "[dry-run] migrate state $LEGACY_STATE_DIR -> $STATE_DIR"
+    return
+  fi
+  mkdir -p "$(dirname "$STATE_DIR")"
+  mv "$LEGACY_STATE_DIR" "$STATE_DIR" && info "migrated state  $LEGACY_STATE_DIR -> $STATE_DIR"
+}
+
+# ---- codex live-config additions -----------------------------------------
+# The live ~/.codex/config.toml is user/runtime-owned; agent-bios never
+# deploys or overwrites it. codex/config-additions.toml declares the only
+# content agent-bios manages there — one marked [agents.*] block plus a tagged
+# features.multi_agent line — and this helper merges (install), checks
+# (verify), or removes (uninstall) exactly that content, backed up and
+# tomllib-validated before any write. Modes: merge | check | remove.
+codex_config_additions() {
+  AB_MODE="$1" AB_CODEX_DIR="$CODEX_DIR" AB_FRAGMENT="$REPO/codex/config-additions.toml" \
+  AB_BACKUP="${BACKUP_DIR:-}" AB_DRY="$DRY_RUN" python3 - <<'PY'
+import os, pathlib, sys, tomllib
+
+mode = os.environ["AB_MODE"]
+codex_dir = pathlib.Path(os.environ["AB_CODEX_DIR"])
+fragment_path = pathlib.Path(os.environ["AB_FRAGMENT"])
+backup_root = os.environ.get("AB_BACKUP", "")
+dry = os.environ.get("AB_DRY") == "1"
+target = codex_dir / "config.toml"
+BEGIN = "# >>> agent-bios additions >>>"
+END = "# <<< agent-bios additions <<<"
+TAG = "# agent-bios"
+
+def info(msg): print(f"  {msg}")
+def fail(msg): print(msg); sys.exit(1)
+
+frag_text = fragment_path.read_text().replace("${CODEX_HOME}", str(codex_dir))
+want_agents = tomllib.loads(frag_text)["agents"]
+live_text = target.read_text() if target.is_file() else ""
+try:
+    live = tomllib.loads(live_text) if live_text else {}
+except Exception as exc:
+    fail(f"live codex config does not parse; not touching it: {target} ({exc})")
+
+def state_ok():
+    if live.get("features", {}).get("multi_agent") is not True:
+        return False
+    return all(
+        live.get("agents", {}).get(name, {}).get(key) == spec[key]
+        for name, spec in want_agents.items()
+        for key in ("description", "config_file")
+    )
+
+if mode == "check":
+    problems = []
+    if live.get("features", {}).get("multi_agent") is not True:
+        problems.append("features.multi_agent is not true")
+    for name, spec in want_agents.items():
+        if live.get("agents", {}).get(name, {}).get("config_file") != spec["config_file"]:
+            problems.append(f"agents.{name}.config_file drifted or missing")
+        elif not pathlib.Path(spec["config_file"]).is_file():
+            problems.append(f"agents.{name} template missing: {spec['config_file']}")
+    if problems:
+        fail(f"codex config additions: {'; '.join(problems)} ({target})")
+    info("codex config additions OK")
+    sys.exit(0)
+
+def strip_managed(text):
+    out, skipping = [], False
+    for line in text.splitlines(keepends=True):
+        s = line.strip()
+        if s == BEGIN: skipping = True; continue
+        if s == END: skipping = False; continue
+        if skipping or s.endswith(TAG): continue
+        out.append(line)
+    return "".join(out)
+
+if mode == "remove":
+    if not target.is_file():
+        sys.exit(0)
+    stripped = strip_managed(live_text)
+    if stripped == live_text:
+        info(f"no agent-bios additions in {target}")
+        sys.exit(0)
+    try:
+        tomllib.loads(stripped)
+    except Exception as exc:
+        fail(f"refusing removal; result would not parse: {exc}")
+    if dry:
+        info(f"[dry-run] remove agent-bios additions from {target}")
+        sys.exit(0)
+    backup = target.with_name(target.name + ".bak-agent-bios-uninstall")
+    backup.write_text(live_text)
+    target.write_text(stripped)
+    info(f"removed additions  {target} (backup: {backup.name})")
+    sys.exit(0)
+
+# mode == merge
+if state_ok():
+    info(f"unchanged  {target} (additions present)")
+    sys.exit(0)
+
+# A drifted [agents.<tier>] outside our markers would become a duplicate
+# table if we appended ours; that conflict needs the user, not a clobber.
+base = strip_managed(live_text)
+base_data = tomllib.loads(base) if base.strip() else {}
+clash = [name for name in want_agents if name in base_data.get("agents", {})]
+if clash:
+    fail(
+        f"unmanaged [agents.{'/'.join(clash)}] with drifted content in {target}; "
+        "align or remove them, then rerun install"
+    )
+
+block_lines = [BEGIN]
+if "features" not in base_data:
+    block_lines += ["[features]", f"multi_agent = true  {TAG}"]
+for name, spec in want_agents.items():
+    block_lines += [
+        f"[agents.{name}]",
+        f'description = "{spec["description"]}"',
+        f'config_file = "{spec["config_file"]}"',
+    ]
+block_lines.append(END)
+block = "\n".join(block_lines) + "\n"
+
+new_text = base
+if "features" in base_data:
+    if base_data["features"].get("multi_agent") is None:
+        lines = new_text.splitlines(keepends=True)
+        for i, line in enumerate(lines):
+            if line.strip() == "[features]":
+                lines.insert(i + 1, f"multi_agent = true  {TAG}\n")
+                break
+        new_text = "".join(lines)
+    elif base_data["features"].get("multi_agent") is not True:
+        info(f"note: features.multi_agent explicitly set in {target}; leaving it")
+if new_text and not new_text.endswith("\n"):
+    new_text += "\n"
+new_text += ("\n" if new_text else "") + block
+
+try:
+    tomllib.loads(new_text)
+except Exception as exc:
+    fail(f"merge result would not parse; live config untouched ({exc})")
+if dry:
+    info(f"[dry-run] merge agent-bios additions into {target}")
+    sys.exit(0)
+if live_text and backup_root:
+    bpath = pathlib.Path(backup_root + str(target))
+    bpath.parent.mkdir(parents=True, exist_ok=True)
+    bpath.write_text(live_text)
+target.parent.mkdir(parents=True, exist_ok=True)
+target.write_text(new_text)
+info(f"merged additions  {target}")
+PY
+}
+
+# ---- optional dependencies -----------------------------------------------
+# Capabilities are optional: a missing one only degrades the review routes that
+# need it. launch/agent-launch.toml is the single source for both the command
+# that gates a route and the install line offered here.
+capability_table() {
+  python3 - "$REPO/launch/agent-launch.toml" <<'PY'
+import sys, tomllib
+# `${backend}` means "the CLI of the host this capability offers on". Resolved HERE because
+# the probe below runs `command -v` on whatever this prints, and the literal sentinel is not
+# a command: the built-in workflow capability reported as unavailable while the launcher ran
+# it perfectly well.
+data = tomllib.load(open(sys.argv[1], "rb"))
+backends = data.get("backends", {})
+for name, cap in data.get("capabilities", {}).items():
+    command = cap.get("command", "")
+    if command == "${backend}":
+        hosts = sorted({h for offer in cap.get("offers", []) for h in offer.get("hosts", [])})
+        command = next(
+            (backends[h]["command"] for h in hosts if backends.get(h, {}).get("command")), ""
+        )
+    print("\t".join((name, command, cap.get("install", ""))))
+PY
+}
+
+install_capability() {
+  local name="$1" line="$2"
+  log "Installing optional dependency $name: $line"
+  if [ "$DRY_RUN" = 1 ]; then info "[dry-run] $line"; return 0; fi
+  if sh -c "$line"; then info "installed  $name"; else log "warning: installing $name failed; routes needing it stay degraded"; fi
+}
+
+handle_capabilities() {
+  local requested="$1" name command line
+  # Fail on a typo rather than silently installing nothing.
+  local known; known=$(capability_table | cut -f1)
+  local want
+  for want in ${requested//,/ }; do
+    printf '%s\n' "$known" | grep -qx "$want" || {
+      log "unknown --with capability: $want (known: $(printf '%s' "$known" | tr '\n' ' '))"; return 1; }
+  done
+  while IFS=$'\t' read -r name command line; do
+    [ -n "$name" ] || continue
+    if command -v "$command" >/dev/null 2>&1; then
+      info "capability present  $name ($command)"
+      # Explicitly requested, already there, and nothing to install: say so, because after
+      # the rename `--with ultracode` names the claude-backed reviewer — which needs no
+      # install — while the tool the user probably meant stays missing and is only hinted
+      # at further down. The request silently no-opped and install still exited 0.
+      if [ -z "$line" ] && printf '%s\n' "${requested//,/ }" | tr ' ' '\n' | grep -qx "$name"; then
+        log "note: $name needs no install (it is the host CLI); nothing was installed for it"
+        local installable
+        installable=$(capability_table | awk -F'\t' -v me="$name" '$1 != me && $3 != "" { print $1 }' | tr '\n' ' ')
+        [ -n "$installable" ] && log "      capabilities that DO install: ${installable% }"
+      fi
+      continue
+    fi
+    if printf '%s\n' "${requested//,/ }" | tr ' ' '\n' | grep -qx "$name"; then
+      [ -n "$line" ] && install_capability "$name" "$line" \
+        || log "note: $name has no configured install line"
+    elif [ -n "$line" ] && [ -t 0 ] && [ "$DRY_RUN" != 1 ]; then
+      printf '  Install optional dependency %s? (%s) [y/N] ' "$name" "$line"
+      local answer=""; read -r answer </dev/tty || answer=""
+      case "$answer" in
+        [yY]*) install_capability "$name" "$line" ;;
+        *) info "skipped  $name — install later: $line" ;;
+      esac
+    else
+      info "optional  $name unavailable; routes needing it degrade${line:+ — install: $line}"
+    fi
+  done <<EOF
+$(capability_table)
+EOF
+}
+
+# Presets the launcher saved into the deployed profiles.toml (pre-split, or by hand)
+# would be lost to the cp below; move them into the user-owned presets file first.
+migrate_user_presets() {
+  local src="$REPO/launch/agent-launch.toml"
+  local dst="$LAUNCH_DIR/profiles.toml"
+  local user="$LAUNCH_DIR/$USER_PRESETS_NAME"
+  [ -f "$dst" ] || return 0
+  python3 - "$src" "$dst" "$user" "$DRY_RUN" <<'PY' || { log "user preset migration failed; not overwriting $LAUNCH_DIR/profiles.toml"; return 1; }
+import os, pathlib, re, sys, tomllib
+
+src, dst, user, dry_run = pathlib.Path(sys.argv[1]), pathlib.Path(sys.argv[2]), pathlib.Path(sys.argv[3]), sys.argv[4] == "1"
+dst_text = dst.read_text()
+shipped = set(tomllib.loads(src.read_text()).get("presets", {}))
+extra = set(tomllib.loads(dst_text).get("presets", {})) - shipped
+if not extra:
+    sys.exit(0)
+existing_text = user.read_text() if user.is_file() else ""
+already = set(tomllib.loads(existing_text).get("presets", {})) if existing_text else set()
+move = sorted(extra - already)
+for name in sorted(extra & already):
+    print(f"  kept in {user.name}  {name} (already saved there)")
+if not move:
+    sys.exit(0)
+
+header = re.compile(r'^\[presets\.(?:"([^"]+)"|([A-Za-z0-9][A-Za-z0-9_-]*))(?:[.\]])')
+blocks, current = {}, None
+for line in dst_text.splitlines(keepends=True):
+    stripped = line.strip()
+    if stripped.startswith("["):
+        found = header.match(stripped)
+        current = (found.group(1) or found.group(2)) if found else None
+    if current in move:
+        blocks.setdefault(current, []).append(line)
+# Refuse to deploy over a preset we could not carry across, rather than drop it.
+missing = [name for name in move if name not in blocks]
+if missing:
+    sys.exit(f"cannot extract preset block(s) from {dst}: {', '.join(missing)}")
+
+out = existing_text.rstrip("\n") or (
+    "# agent-launch user presets, moved out of profiles.toml by agent-bios install.\n"
+    "# The installer never deploys or verifies this file, so presets here survive upgrades."
+)
+for name in move:
+    out += "\n\n" + "".join(blocks[name]).strip("\n")
+for name in move:
+    print(f"  {'[dry-run] ' if dry_run else ''}moved preset  {name} -> {user}")
+if dry_run:
+    sys.exit(0)
+user.parent.mkdir(parents=True, exist_ok=True)
+temporary = user.with_name(f".{user.name}.{os.getpid()}.tmp")
+temporary.write_text(out + "\n")
+os.replace(temporary, user)
+PY
+}
+
+remove_zsh_hook() {
+  if [ ! -f "$ZSHRC" ] || ! grep -qF "$HOOK_MARK" "$ZSHRC"; then
+    info "no zsh hook to remove"
+    return
+  fi
+  if [ "$DRY_RUN" = 1 ]; then info "[dry-run] remove zsh hook from $ZSHRC"; return; fi
+  grep -vF "$HOOK_MARK" "$ZSHRC" > "$ZSHRC.agent-tmp" && mv "$ZSHRC.agent-tmp" "$ZSHRC"
+  info "removed zsh hook  $ZSHRC"
+}
+
+# Promote -> migrate (collection loop, Phase 4): after the corpus is deployed,
+# clear personal copies of learnings that have been promoted into the shared
+# corpus AND are in this user's assembled bundle. Best-effort: a prune failure
+# (or an absent manifest/script) never fails the install. Runs per host.
+migrate_learnings() {
+  local script="$REPO/learn/migrate-learnings.py"
+  { [ -f "$script" ] && [ -f "$REPO/learn/promotions.json" ]; } || return 0
+  local -a sel dry
+  sel=(--selection-file "$STATE_DIR/selection.json")
+  [ "$DRY_RUN" = 1 ] && dry=(--dry-run) || dry=()
+  # ${dry[@]+...}: expanding an empty array as "${dry[@]}" is an unbound-variable
+  # error under `set -u` on bash 3.2 (macOS default) and would abort the install.
+  python3 "$script" --host claude --config-dir "$CLAUDE_DIR" "${sel[@]}" ${dry[@]+"${dry[@]}"} \
+    || info "learnings migrate (claude) skipped"
+  python3 "$script" --host codex --config-dir "$CODEX_DIR" "${sel[@]}" ${dry[@]+"${dry[@]}"} \
+    || info "learnings migrate (codex) skipped"
+}
+
+# ---- subcommands ---------------------------------------------------------
+cmd_install() {
+  check_prereqs || { log "resolve the prerequisites above and retry"; exit 1; }
+  migrate_state
+  if [ "$DRY_RUN" != 1 ]; then
+    mkdir -p "$STATE_DIR"
+    BACKUP_DIR="$STATE_DIR/backups/$(date +%Y%m%d-%H%M%S)"
+    [ -f "$MANIFEST" ] && cp "$MANIFEST" "$PRIOR_MANIFEST"
+    : > "$MANIFEST"
+  fi
+  log "Deploying agent-bios from $REPO"
+  # Refuse loudly before doing any work: an unreadable declaration must not degrade
+  # into withholding nothing, which is the fail-open shape this rule exists to avoid.
+  WITHHELD_GUIDES="$(author_only_guides)" || exit 1
+  assemble_corpus || exit 1
+  # assemble.py withholds author-only guides and prunes the destinations it writes.
+  # $CLAUDE_DIR/guides is not one of them — it is where the pre-unification full
+  # install put guides, so a machine that installed then would keep its copy for good.
+  prune_withheld "$CLAUDE_DIR/guides"
+  migrate_learnings   # Phase 4: clear personal copies now absorbed by the corpus
+  deploy_glob "$REPO/codex/agents" "*.toml" "$CODEX_DIR/agents"
+  codex_config_additions merge || exit 1
+  deploy_file "$REPO/wrappers/codex-run.sh"  "$CODEX_DIR/bin/codex-run"  "+x"
+  deploy_file "$REPO/wrappers/codex-helm.sh" "$CODEX_DIR/bin/codex-helm" "+x"
+  # The claude-side adapter lands under CLAUDE_DIR for the same reason its codex twin
+  # lands under CODEX_DIR: each is that host's, and a single shared bin would make the
+  # two families' review routes indistinguishable from their install paths.
+  deploy_file "$REPO/wrappers/claude-run.sh" "$CLAUDE_DIR/bin/claude-run" "+x"
+  migrate_user_presets || exit 1   # must precede the deploy below, which overwrites profiles.toml
+  deploy_file "$REPO/launch/agent-launch.toml" "$LAUNCH_DIR/profiles.toml"
+  deploy_file "$REPO/launch/agent-launch.zsh"   "$LAUNCH_DIR/shell.zsh"
+  deploy_file "$REPO/launch/agent-launch.py"  "$BIN_DIR/agent-launch" "+x"
+  log ""
+  log "Optional dependencies (missing ones only degrade the routes that need them)..."
+  handle_capabilities "$WITH" || exit 1
+  log ""
+  if [ "$DRY_RUN" = 1 ]; then
+    info "[dry-run] provision managed Textual venv"
+  else
+    bash "$REPO/launch/provision-venv.sh" && info "managed venv OK" \
+      || log "warning: venv provisioning failed (numbered-prompt fallback applies)"
+  fi
+  add_zsh_hook
+  if python3 "$REPO/compose/corpus-state.py" project --repo "$REPO" >/dev/null 2>&1; then
+    info "corpus-status projected"
+  else
+    log "note: corpus-status projection unavailable (versions.json/ledger missing?)"
+  fi
+  # Deploy/system version marker for the launcher's TUI version line, read from
+  # package.json (version + releaseDate) — distinct from the corpus content
+  # version. Best-effort: a failure here never fails the install.
+  if [ "$DRY_RUN" != 1 ]; then
+    if python3 - "$REPO/package.json" "$STATE_DIR/version.json" "$REPO/provenance.json" \
+         "$([ -e "$REPO/.git" ] && echo clone || echo package)" <<'PY' 2>/dev/null
+import json, os, sys
+pkg = json.load(open(sys.argv[1]))
+out = {"version": pkg.get("version"), "releaseDate": pkg.get("releaseDate"),
+       "source": sys.argv[4]}
+# Publication provenance rides along ONLY for a package-layout source: in a
+# clone, git itself is the live provenance and a provenance.json on disk is by
+# definition residue (a failed pack's leftover stamp) — ingesting it once let a
+# clone deployment of commit B carry a stale label A into the state marker.
+if sys.argv[4] == "package" and os.path.isfile(sys.argv[3]):
+    try:
+        prov = json.load(open(sys.argv[3]))
+        if prov.get("commit"):
+            out["commit"] = prov["commit"]
+        if prov.get("dirty"):
+            out["dirty"] = True
+    except Exception:
+        pass
+with open(sys.argv[2], "w") as f:
+    json.dump(out, f)
+    f.write("\n")
+PY
+    then
+      printf '%s\n' "$STATE_DIR/version.json" >> "$MANIFEST"
+      info "version marker written ($STATE_DIR/version.json)"
+    else
+      log "note: version marker not written (package.json unreadable)"
+    fi
+  fi
+  log ""
+  log "Verifying deployment..."
+  if cmd_verify; then
+    log ""
+    log "Done. Open a new shell (or: source \"$ZSHRC\") to activate the zero-arg launcher."
+    # An untouched backup dir means nothing was replaced; that healthy state
+    # must not become a nonzero exit under set -e.
+    { [ -n "$BACKUP_DIR" ] && [ -d "$BACKUP_DIR" ] && log "Replaced files were backed up under $BACKUP_DIR"; } || true
+    prune_backups
+  else
+    log "VERIFY FAILED after install — see messages above"
+    exit 1
+  fi
+}
+
+verify_match()   { if cmp -s "$1" "$2"; then info "match    $2"; else log "MISMATCH/absent  $2"; return 1; fi; }
+verify_present() { if [ -f "$1" ]; then return 0; else log "missing  $1"; return 1; fi; }
+
+cmd_verify() {
+  local fail=0 gp gb
+  if [ ! -e "$REPO/.git" ] && [ "$(drift_state)" = "drift" ]; then
+    log "deploy drift: $(drift_detail) — run: agent-bios install"
+    fail=1
+  fi
+  # Not mode-specific: an author-only guide must be absent from EVERY directory any
+  # install writes, including the one the pre-unification full install owned.
+  local verify_withheld
+  verify_withheld="$(author_only_guides)" || return 1
+  for gb in $verify_withheld; do
+    for gp in "$CLAUDE_DIR/guides/$gb" "$CLAUDE_DIR/central/guides/$gb" "$CODEX_DIR/guides/$gb"; do
+      if [ -f "$gp" ]; then
+        log "author-only guide is still installed: $gp"; fail=1
+      fi
+    done
+  done
+  [ -n "$verify_withheld" ] && info "author-only guides withheld: $(printf '%s' "$verify_withheld" | tr '\n' ' ')"
+  # Corpus surfaces are selection-derived, not repo-identical, so verify reads the assembled
+  # shape rather than byte-comparing against the repo. The entry file is user-owned — READ-check
+  # the import line, never rewrite it.
+  python3 "$REPO/compose/check-domains.py" >/dev/null 2>&1 && info "domains gate OK" || { log "domains gate FAILED"; fail=1; }
+  verify_present "$CLAUDE_DIR/central/bundle.md" || fail=1
+  if grep -qF '@central/bundle.md' "$CLAUDE_DIR/CLAUDE.md" 2>/dev/null; then
+    info "entry import line present"
+  else
+    log "entry $CLAUDE_DIR/CLAUDE.md lacks '@central/bundle.md' — central corpus is NOT loading"; fail=1
+  fi
+  if grep -qF 'agent-bios:central:start' "$CODEX_DIR/AGENTS.md" 2>/dev/null; then
+    info "codex central region present"
+  else
+    log "codex AGENTS.md central region missing"; fail=1
+  fi
+  # Every capability must probe as a real command. `${backend}` reaching this table means
+  # the sentinel was not resolved, and the probe below would then report a capability the
+  # launcher can run perfectly well as unavailable.
+  if capability_table | awk -F'\t' '$2 == "" || $2 == "${backend}" { print; found=1 } END { exit !found }' >/dev/null 2>&1; then
+    log "capability table has an unresolved or empty command — the installer would misreport it"; fail=1
+  else
+    info "capability commands resolve"
+  fi
+  # The help's --with list must BE the capability table, not a copy of it: the copy went
+  # stale on the first rename and advertised a name that selects a different capability
+  # than the one carrying the install line.
+  local advertised table
+  advertised=$(usage 2>/dev/null | sed -n 's/^ *--with names: //p')
+  table=$(capability_table 2>/dev/null | cut -f1 | tr '\n' ' ')
+  if [ "$advertised" = "${table% }" ]; then
+    info "--with help matches the capability table"
+  else
+    log "--with help advertises '$advertised' but the capabilities are '${table% }'"; fail=1
+  fi
+  verify_match "$REPO/launch/agent-launch.py" "$BIN_DIR/agent-launch"        || fail=1
+  verify_match "$REPO/launch/agent-launch.toml" "$LAUNCH_DIR/profiles.toml"   || fail=1
+  verify_match "$REPO/launch/agent-launch.zsh"  "$LAUNCH_DIR/shell.zsh"        || fail=1
+  python3 - "$CODEX_DIR/agents" <<'PY' && info "agent TOMLs OK" || fail=1
+import sys, pathlib, tomllib
+root = pathlib.Path(sys.argv[1])
+required = {"frontier.toml", "workhorse.toml", "sweep.toml", "reviewer.toml"}
+missing = required - {p.name for p in root.glob("*.toml")}
+assert not missing, f"missing agent TOMLs in {root}: {sorted(missing)}"
+for p in sorted(root.glob("*.toml")):
+    tomllib.loads(p.read_text())
+PY
+  codex_config_additions check || fail=1
+  if command -v codex >/dev/null 2>&1 && [ -x "$CODEX_DIR/bin/codex-helm" ]; then
+    if "$CODEX_DIR/bin/codex-helm" --dry-run --mode review "probe" >/dev/null 2>&1; then
+      info "codex-helm dry-run OK"
+    else
+      log "codex-helm dry-run FAILED"; fail=1
+    fi
+  fi
+  # Existence first, because the guard below is written as `if executable` and a MISSING
+  # adapter would satisfy it by never running — a deploy target whose only check skips
+  # itself when the deploy failed is not checked at all.
+  verify_present "$CLAUDE_DIR/bin/claude-run" || fail=1
+  # Then WHICH version landed, because this file is on the panel's dispatch path now and
+  # an older copy would dispatch reviews that quietly emit nothing. The earlier check
+  # here asserted that an unpinned dispatch is refused; that guard was deliberately
+  # removed when the adapter went live — refusing turned "the review ran unpinned" into
+  # "the review did not run" — so asserting it would now fail against correct behaviour.
+  # `--help` is the only probe that reaches no network: an unpinned run warns and then
+  # dispatches for real.
+  if [ -x "$CLAUDE_DIR/bin/claude-run" ]; then
+    if "$CLAUDE_DIR/bin/claude-run" --help 2>/dev/null | grep -q 'REVIEW_RECEIPT_DIR'; then
+      info "claude-run is receipt-aware"
+    else
+      log "claude-run predates the receipt contract — reviews through it emit nothing"; fail=1
+    fi
+  fi
+  local vpy="${AGENT_LAUNCH_VENV:-$HOME/.local/share/agent-launch/venv}/bin/python"
+  if [ -x "$vpy" ] && "$vpy" -c 'import textual' 2>/dev/null; then
+    info "managed venv (textual) OK"
+  else
+    log "note: managed venv/textual unavailable (numbered-prompt fallback applies)"
+  fi
+  # A file this installer executes but never ships is invisible from a clone and
+  # fatal on npm, so the payload gate runs wherever it exists (maintainer-side).
+  if [ -x "$REPO/gates/check-package.sh" ]; then
+    if "$REPO/gates/check-package.sh" >/dev/null 2>&1; then
+      info "npm payload OK"
+    else
+      log "npm payload incomplete; run gates/check-package.sh"
+      fail=1
+    fi
+  fi
+  # Repo-internal mirror parity is a maintainer gate; only meaningful from a clone.
+  if [ -d "$REPO/ko" ] && [ -x "$REPO/gates/check-parity.sh" ]; then
+    if "$REPO/gates/check-parity.sh" >/dev/null 2>&1; then info "repo mirror parity OK"; else log "repo mirror parity FAILED"; fail=1; fi
+  fi
+  # Prompting guides name concrete models, so they go stale on a model change
+  # rather than degrading quietly; this checks them against the launch config.
+  if [ -x "$REPO/launch/check-prompting-targets.sh" ]; then
+    if "$REPO/launch/check-prompting-targets.sh" >/dev/null 2>&1; then
+      info "prompting targets OK"
+    else
+      log "prompting guides do not cover a configured model; run launch/check-prompting-targets.sh"
+      fail=1
+    fi
+  fi
+  return $fail
+}
+
+cmd_uninstall() {
+  migrate_state
+  codex_config_additions remove || log "warning: could not remove codex config additions"
+  # The assembler's two spans in files we do not own — settings registrations and the AGENTS.md
+  # central region — are merged in and were never removed here, so uninstall used to leave hooks
+  # invoking deleted files and instructions pointing at deleted guides. It reads ownership the
+  # same way the merge wrote it, so it cannot reach past what we put there.
+  if [ -f "$REPO/compose/assemble.py" ]; then
+    python3 "$REPO/compose/assemble.py" --remove-owned --claude-dir "$CLAUDE_DIR" \
+      --codex-dir "$CODEX_DIR" --state-dir "$STATE_DIR" ${DRY_RUN:+} \
+      $([ "$DRY_RUN" = 1 ] && echo --dry-run) \
+      || log "warning: could not remove assembler-owned regions"
+  fi
+  if [ -f "$MANIFEST" ]; then
+    # Back up before deleting, the way install backs up before overwriting. Full mode deploys the
+    # entry CLAUDE.md/AGENTS.md as ordinary targets, so they are manifested and removed here —
+    # correct, since in that mode the entry file IS the corpus. What was wrong is that anything a
+    # user added to it disappeared with no copy, while the same file overwritten during install
+    # would have been backed up. Removal is symmetric with deployment; recoverability now is too.
+    [ "$DRY_RUN" = 1 ] || { mkdir -p "$STATE_DIR"; BACKUP_DIR="$STATE_DIR/backups/uninstall-$(date +%Y%m%d-%H%M%S)"; }
+    local f
+    while IFS= read -r f; do
+      [ -n "$f" ] || continue
+      if [ -f "$f" ] && [ -n "$BACKUP_DIR" ] && [ "$DRY_RUN" != 1 ]; then
+        mkdir -p "$(dirname "$BACKUP_DIR$f")" && cp "$f" "$BACKUP_DIR$f"
+      fi
+      [ -f "$f" ] && { run rm -f "$f"; [ "$DRY_RUN" = 1 ] || info "removed  $f"; }
+    done < "$MANIFEST"
+    { [ -n "$BACKUP_DIR" ] && [ -d "$BACKUP_DIR" ] && info "staged for the archive: $BACKUP_DIR"; } || true
+    [ "$DRY_RUN" = 1 ] || rm -f "$MANIFEST"
+  else
+    log "no manifest at $MANIFEST; removing known deploy targets"
+    # The two entry files are deliberately NOT in this list. `$CLAUDE_DIR/CLAUDE.md` is seeded
+    # once and the user's thereafter, and `$CODEX_DIR/AGENTS.md` is ours only between the central
+    # markers, which --remove-owned above already took. This branch runs precisely when state is
+    # missing or agent-bios was never installed here, so nothing says we wrote either file —
+    # and deleting them whole destroyed personal instructions with no copy at all, since
+    # BACKUP_DIR is set only on the manifest path above.
+    local p
+    for p in "$CODEX_DIR/bin/codex-run" "$CODEX_DIR/bin/codex-helm" \
+             "$CLAUDE_DIR/bin/claude-run" \
+             "$LAUNCH_DIR/profiles.toml" "$LAUNCH_DIR/shell.zsh" "$BIN_DIR/agent-launch"; do
+      [ -f "$p" ] && { run rm -f "$p"; [ "$DRY_RUN" = 1 ] || info "removed  $p"; }
+    done
+  fi
+  local d
+  # `central/` and its subdirectories are entirely ours — the assembler creates them and the
+  # manifest covers every file inside — so they belong in this sweep. They were missing from it,
+  # which left three empty directories in the user's config dir after a "leave no trace" removal.
+  # rmdir, never rm -rf: a directory that is not empty is one we did not fully account for, and
+  # the right answer then is to leave it and be visibly incomplete.
+  for d in "$CLAUDE_DIR/central/guides" "$CLAUDE_DIR/central/hooks" "$CLAUDE_DIR/central/agents" \
+           "$CLAUDE_DIR/central" \
+           "$CLAUDE_DIR/guides" "$CLAUDE_DIR/agents" "$CLAUDE_DIR/bin" \
+           "$CODEX_DIR/guides" "$CODEX_DIR/agents" "$CODEX_DIR/bin" "$LAUNCH_DIR"; do
+    [ -d "$d" ] && rmdir "$d" 2>/dev/null && info "removed empty  $d" || true
+  done
+  remove_zsh_hook
+  archive_and_purge
+  log ""
+  log "Uninstalled: deployed files, the zsh hook, state, backups, cache, and the managed venv."
+}
+
+# Uninstall is a SECURITY operation — nothing of ours may survive it on the machine. That
+# conflicts with never destroying what a user added, because full mode writes the corpus into an
+# entry file they then edit, so removal takes their work with it. One artifact settles both:
+# everything removed leaves as a single archive that can be handed off or deleted in one act,
+# and every managed location is then purged. The archive lands in $HOME, outside every path we
+# manage, because a copy inside a directory we are about to delete is not a copy.
+#
+# Order is the safety property: archive first, verify the archive exists, purge only then. A
+# failed archive leaves the machine untouched rather than clean and empty-handed.
+archive_and_purge() {
+  local ts stage rel out list staged skipped
+  ts="$(date +%Y%m%d-%H%M%S)"
+  out="${AGENT_BIOS_UNINSTALL_ARCHIVE:-$HOME}/agent-bios-uninstall-$ts.tar.gz"
+  if [ "$DRY_RUN" = 1 ]; then
+    info "[dry-run] archive removed content to $out, then purge $STATE_DIR, the cache and the venv"
+    return 0
+  fi
+  stage="$(mktemp -d)" || { log "warning: no temp dir; leaving state in place"; return 0; }
+  list="$(mktemp)" || { rm -rf "$stage"; log "warning: no temp file; leaving state in place"; return 0; }
+  [ -d "$STATE_DIR" ] && cp -R "$STATE_DIR" "$stage/state" 2>/dev/null
+  # WHICH loose copies are ours is compose/prune-backups.py's question — it deletes them too, on
+  # the retention path, and a rule written in both places drifts on one side. `*.bak-*` was the
+  # match here, which also claims a `notes.bak-old` the user saved by hand; these sit in
+  # directories we share with them and with other tools, so the name must carry the ownership.
+  if [ -f "$REPO/compose/prune-backups.py" ]; then
+    python3 "$REPO/compose/prune-backups.py" --list-owned \
+      --claude-dir "$CLAUDE_DIR" --codex-dir "$CODEX_DIR" >"$list" 2>/dev/null || : >"$list"
+  else
+    log "note: compose/prune-backups.py is absent, so loose backup copies are left where they are"
+  fi
+  # Staged UNDER their absolute path, the way deploy_file backs up to "$BACKUP_DIR$dst".
+  # Flattening them into one directory let two same-named copies from the two host trees
+  # collide, and the loser was then deleted with nothing in the archive to restore it from.
+  # Only what verifiably reached the stage may be deleted later. Every failure mode here is
+  # silent — a full temp filesystem, an unreadable source, a directory that cannot be created —
+  # and purging from the ORIGINAL list removed files the archive does not contain. Size equality
+  # rather than cp's exit status alone, because the question is whether the archive can restore
+  # it, not whether the copy was attempted.
+  staged="$(mktemp)" || { rm -f "$list"; rm -rf "$stage"
+                          log "warning: no temp file; leaving state in place"; return 0; }
+  skipped=0
+  while IFS= read -r -d '' rel; do
+    if mkdir -p "$(dirname "$stage/loose$rel")" 2>/dev/null \
+       && cp "$rel" "$stage/loose$rel" 2>/dev/null \
+       && [ "$(wc -c <"$rel" 2>/dev/null)" = "$(wc -c <"$stage/loose$rel" 2>/dev/null)" ]; then
+      printf '%s\0' "$rel" >> "$staged"
+    else
+      skipped=$((skipped + 1))
+      rm -f "$stage/loose$rel" 2>/dev/null   # a partial copy must not look archived
+      log "warning: could not stage $rel — leaving it in place"
+    fi
+  done <"$list"
+  if tar czf "$out" -C "$stage" . 2>/dev/null && [ -s "$out" ]; then
+    # Only here, with the archive written and non-empty, is removing the originals recoverable.
+    # Deleting them before the tar meant a failed archive took the backups with it — while the
+    # warning below told the operator they had been left in place.
+    while IFS= read -r -d '' rel; do rm -f "$rel" 2>/dev/null; done <"$staged"
+    rm -f "$list" "$staged"
+    rm -rf "$stage"
+    rm -rf "$STATE_DIR" "$HOME/.cache/agent-launch" \
+           "${AGENT_LAUNCH_VENV:-$HOME/.local/share/agent-launch}"
+    log ""
+    log "Everything removed is in ONE archive:  $out"
+    if [ "$skipped" -gt 0 ]; then
+      log "Move it somewhere central or delete it. $skipped backup copy(ies) could not be staged,"
+      log "so they were LEFT ON DISK rather than deleted with nothing to restore them from."
+    else
+      log "Move it somewhere central or delete it — nothing of ours is left on this machine."
+    fi
+  else
+    rm -f "$list" "$staged"
+    rm -rf "$stage"
+    log "warning: could not write $out — state, backups and the venv were left in place rather"
+    log "         than deleted with no copy. Re-run once the archive path is writable."
+  fi
+}
+
+cmd_onboard() {
+  log "agent-bios onboarding — pick your domain packages (core + infra always install)"
+  local names=() line i=1 choice sel="" n picks
+  while IFS= read -r line; do names+=("$line"); done \
+    < <(python3 -c "import json;print('\n'.join(sorted(json.load(open('$REPO/compose/domains.json'))['domains'])))")
+  [ "${#names[@]}" -ge 1 ] || { log "no domains found in compose/domains.json"; exit 1; }
+  if [ "$DOMAINS_SET" = 1 ]; then
+    # Non-interactive path, per this installer's input contract (stdin is
+    # detached at the top of the script): selection arrives as domain names.
+    [ "$DOMAINS_ARG" = none ] && DOMAINS_ARG=""
+    sel="$DOMAINS_ARG"
+  elif ( : </dev/tty ) 2>/dev/null; then
+    for line in "${names[@]}"; do info "$i) $line"; i=$((i+1)); done
+    printf 'Select by number, comma-separated (empty = core+infra only): '
+    read -r choice </dev/tty || choice=""
+    if [ -n "$choice" ]; then
+      # bash 3.2 + set -u: expanding an EMPTY array errors, so split only
+      # when there is input; empty input means core+infra only.
+      IFS=',' read -ra picks <<<"$choice"
+      for n in "${picks[@]}"; do
+        n="${n// /}"; [ -n "$n" ] || continue
+        case "$n" in (*[!0-9]*) log "invalid selection: $n"; exit 2 ;; esac
+        [ "$n" -ge 1 ] && [ "$n" -le "${#names[@]}" ] || { log "selection out of range: $n"; exit 2; }
+        sel="$sel${sel:+,}${names[$((n-1))]}"
+      done
+    fi
+  else
+    log "onboard needs a terminal or an explicit selection — run:"
+    log "  agent-bios onboard --domains a,b   (or --domains none for core+infra only)"
+    exit 2
+  fi
+  DOMAINS_ARG="$sel"; DOMAINS_SET=1
+  log "selection: ${sel:-<core+infra only>}"
+  cmd_install
+  log ""
+  log "Activation canary (proves the bundle loads in a live session)..."
+  if [ "$DRY_RUN" = 1 ]; then info "[dry-run] skip canary probe"; return; fi
+  bash "$REPO/compose/canary.sh" || {
+    log "ONBOARDING INCOMPLETE: the bundle is installed but not loading — fix the cause above and re-run: agent-bios verify"
+    exit 1
+  }
+  # The prune is authorized by the canary's proof, and cmd_install ran before the canary existed
+  # for this bundle rev — so it kept everything. Now that loading is proven, run it for real.
+  migrate_learnings
+}
+
+# ---- deploy-chain drift ---------------------------------------------------
+# A repo edit is inert until it is published AND globally installed AND
+# deployed. The middle two are checkable: the installer stamps the package
+# version it deployed into the state dir, so a stamp older than the package now
+# running means someone updated the package and never re-deployed. Reading the
+# registry cannot see this, which is why it went unnoticed three times.
+json_field() {  # $1=file $2=key
+  [ -f "$1" ] || return 1
+  python3 -c 'import json,sys
+try:
+    v=json.load(open(sys.argv[1])).get(sys.argv[2])
+except Exception:
+    sys.exit(1)
+sys.exit(0) if v is None else print(v)' "$1" "$2" 2>/dev/null
+}
+
+deployed_version() { json_field "$STATE_DIR/version.json" version; }
+source_version()   { json_field "$REPO/package.json" version; }
+
+json_true() {  # exit 0 iff $2 in $1 is JSON true — json.dump writes '"k": true'
+  # with a space, so byte-matching a compact spelling read the real writer's
+  # output as false forever.
+  [ -f "$1" ] || return 1
+  python3 -c 'import json,sys
+try:
+    v=json.load(open(sys.argv[1])).get(sys.argv[2])
+except Exception:
+    sys.exit(1)
+sys.exit(0 if v is True else 1)' "$1" "$2" 2>/dev/null
+}
+
+current_commit() {  # the CURRENT side's commit: git HEAD in a clone, the stamp in a package
+  # A clone's provenance is its live HEAD — a provenance.json on its disk is a
+  # failed pack's residue, and reading it once let a stale label A match a
+  # checkout sitting at B.
+  if [ -e "$REPO/.git" ]; then
+    git -C "$REPO" rev-parse HEAD 2>/dev/null || true
+  else
+    json_field "$REPO/provenance.json" commit 2>/dev/null || true
+  fi
+}
+
+current_dirty() {  # exit 0 iff the current side is a dirty-stamped PACKAGE artifact
+  [ ! -e "$REPO/.git" ] && json_true "$REPO/provenance.json" dirty
+}
+
+drift_state() {  # prints: match | drift | unknown
+  local d s dc sc
+  d="$(deployed_version)" || { echo unknown; return; }
+  s="$(source_version)"   || { echo unknown; return; }
+  [ -n "$d" ] && [ -n "$s" ] || { echo unknown; return; }
+  [ "$d" = "$s" ] || { echo drift; return; }
+  # Same VERSION is not same SOURCE: two locally packed tarballs keep one
+  # version across different commits (npm pack is an accommodated flow), and
+  # the commit was persisted into version.json exactly so this comparison
+  # could read it. Judged only when both sides carry one — a clone deploy
+  # stamps no commit, and half a comparison is none.
+  dc="$(json_field "$STATE_DIR/version.json" commit 2>/dev/null || true)"
+  sc="$(current_commit)"
+  # Dirt is judged BEFORE the commit comparison: a dirty artifact's bytes are
+  # described by no commit, so differing commit labels prove nothing about
+  # differing payloads — unknown, not drift, or npm-layout verify fails on a
+  # mismatch nobody proved.
+  if json_true "$STATE_DIR/version.json" dirty || current_dirty; then
+    echo unknown; return
+  fi
+  if [ -n "$dc" ] && [ -n "$sc" ] && [ "$dc" != "$sc" ]; then
+    echo drift; return
+  fi
+  # UNPROVABLE is not drift: an unbound side (npm layout without a commit — a
+  # lifecycle-disabled pack, or the hook's materialized tree) and a DIRTY side
+  # (bytes no commit describes; parsed via json_true, never byte-matched,
+  # because json.dump's spacing defeated the compact grep) both make the
+  # correspondence unprovable. Drift is a PROVEN mismatch and makes verify
+  # fail; branding the unprovable as drift made D-0050's accepted install path
+  # fail its own verification. Clone deployments stay version-compared — git
+  # itself is their live provenance, and they persist no commit by design.
+  if [ "$(json_field "$STATE_DIR/version.json" source 2>/dev/null || true)" = "package" ] \
+     && [ -z "$dc" ]; then
+    echo unknown; return
+  fi
+  if [ ! -e "$REPO/.git" ] && [ -z "$sc" ]; then
+    echo unknown; return
+  fi
+  echo match
+}
+
+drift_detail() {  # one line naming WHAT drifted: versions, or commits behind one version
+  local d s dc sc
+  d="$(deployed_version)"; s="$(source_version)"
+  dc="$(json_field "$STATE_DIR/version.json" commit 2>/dev/null || true)"
+  sc="$(current_commit)"
+  if [ "$d" = "$s" ] && { json_true "$STATE_DIR/version.json" dirty || current_dirty; }; then
+    printf 'a DIRTY-packed artifact is involved — its bytes are described by no commit; a clean-pack redeploy restores a provable match'
+  elif [ "$d" = "$s" ] && [ -n "$dc" ] && [ -n "$sc" ] && [ "$dc" != "$sc" ]; then
+    printf 'deployed commit %s but this source is at %s (both version %s)' "$dc" "$sc" "$s"
+  elif [ "$(json_field "$STATE_DIR/version.json" source 2>/dev/null || true)" = "package" ] \
+       && [ -z "$dc" ]; then
+    printf 'the deployed artifact is UNBOUND (packed with lifecycle scripts disabled) — its bytes are proven by no commit; a bound redeploy restores a provable match'
+  elif [ ! -e "$REPO/.git" ] && [ -z "$sc" ]; then
+    printf 'this package is UNBOUND (no provenance) — its bytes are proven by no commit'
+  else
+    printf 'deployed %s but this package is %s' "$d" "$s"
+  fi
+}
+
+cmd_status() {
+  local version p
+  if [ -e "$REPO/.git" ]; then
+    version="$(git -C "$REPO" describe --tags --always --dirty 2>/dev/null || git -C "$REPO" rev-parse --short HEAD 2>/dev/null || echo '?')"
+    log "agent-bios  (git clone: $version)"
+  elif [ -f "$REPO/package.json" ]; then
+    version="$(node -e "try{process.stdout.write(require('$REPO/package.json').version)}catch(e){process.stdout.write('?')}" 2>/dev/null || echo '?')"
+    log "agent-bios  (npm package: $version)"
+    if [ -f "$REPO/provenance.json" ]; then
+      local built_from
+      # Tolerated, never trusted: a malformed stamp used to kill status via
+      # set -e mid-output, and a well-formed one with no commit passed in
+      # silence — both are UNBOUND states, not absences of the question.
+      built_from="$(json_field "$REPO/provenance.json" commit 2>/dev/null || true)"
+      if [ -n "$built_from" ]; then
+        info "built from commit ${built_from}$(
+          grep -q '"dirty":true' "$REPO/provenance.json" && printf ' (DIRTY tree at pack time)')"
+      else
+        info "UNBOUND  provenance.json is unreadable or names no commit — this artifact is not usably bound"
+      fi
+    else
+      # The absence is the finding: D-0050 accepts lifecycle-disabled packs as
+      # residual BECAUSE this line makes an unbound artifact visible — a silent
+      # skip here would unmake that decision's premise.
+      info "UNBOUND  no provenance stamp — packed with lifecycle scripts disabled, or a pre-provenance release; this artifact names no commit"
+    fi
+  else
+    log "agent-bios"
+  fi
+  log "  source:  $REPO"
+  case "$(drift_state)" in
+    match)   info "deployed version $(deployed_version) (matches this package)" ;;
+    drift)   log  "DRIFT    $(drift_detail) — run: agent-bios install" ;;
+    unknown) if [ -f "$STATE_DIR/version.json" ]; then
+               info "correspondence unprovable: $(drift_detail)"
+             else
+               info "deployed version unknown (no state marker yet)"
+             fi ;;
+  esac
+  for p in "$CLAUDE_DIR/CLAUDE.md" "$CODEX_DIR/AGENTS.md" "$BIN_DIR/agent-launch" \
+           "$LAUNCH_DIR/profiles.toml" "$LAUNCH_DIR/shell.zsh"; do
+    if [ -e "$p" ]; then info "present  $p"; else info "MISSING  $p"; fi
+  done
+  if [ -f "$ZSHRC" ] && grep -qF "$HOOK_MARK" "$ZSHRC"; then info "zsh hook present"; else info "zsh hook absent"; fi
+}
+
+cmd_update() {
+  if [ -e "$REPO/.git" ]; then
+    log "Updating from git..."
+    run git -C "$REPO" pull --ff-only
+    cmd_install
+  else
+    log "Installed as an npm package. Update with:"
+    log "  npm install -g agent-bios@latest && agent-bios install"
+    log "Then confirm what actually landed — right after a publish the cached"
+    log "packument can serve the PREVIOUS version at exit 0:"
+    log "  agent-bios status   # must show the version you expected, and no DRIFT"
+  fi
+}
+
+usage() {
+  cat <<'EOF'
+agent-bios — deploy the Claude/Codex instruction SSOT into $HOME (by copy).
+
+  agent-bios install     deploy into this environment (backs up + verifies)
+  agent-bios onboard     interactive domain selection + install + activation canary
+  agent-bios verify      check the deployed state matches the source
+  agent-bios learn       submit a session learning (reads the JSON record on
+                         stdin; this is what the learn! flow calls, and it
+                         works from any directory, unlike a repo-relative path)
+  agent-bios status      show what is installed and where
+  agent-bios update      git pull + reinstall (clone), or print the npm update line
+  agent-bios uninstall   remove deployed files and the zsh hook
+  agent-bios help
+
+Flags: --dry-run       print actions without changing anything
+       --domains a,b  assemble ONLY the named domain packages (plus core+infra);
+                      with onboard, 'none' means core+infra only. The selection
+                      persists in the state dir and later installs/updates reuse
+                      it. Default (no flag, no saved selection) selects every
+                      domain — one install shape, "full" is just everything
+                      selected.
+       --with a,b     also install the named optional dependencies (install only).
+                      Without it, install offers each missing one when the terminal
+                      is interactive, and otherwise just prints its install line.
+                      Missing ones are not fatal — they only degrade the review
+                      routes that need them.
+Env:   CLAUDE_CONFIG_DIR, CODEX_HOME, AGENT_LAUNCH_VENV, ZDOTDIR
+EOF
+  # DERIVED, not typed: the hardcoded pair went stale the moment a capability was renamed,
+  # and the name it still advertised selected a different capability than the one that
+  # carries the install line.
+  local known; known=$(capability_table 2>/dev/null | cut -f1 | tr '\n' ' ')
+  [ -n "$known" ] && printf '       --with names: %s\n' "${known% }"
+
+  # Recovery exists in both modes at different granularity, and naming the wrong one is worse
+  # than naming none: a clone can roll the corpus back to a registered mining window, while an
+  # npm install has no git history to read and rolls the whole package back by version instead.
+  # Derived from which install this is, for the same reason --with names is.
+  if [ -e "$REPO/.git" ]; then
+    printf '\nRecover: python3 %s/compose/corpus-state.py list, then rollback --version V\n' "$REPO"
+  else
+    printf '\nRecover: npm install -g agent-bios@<older-version> && agent-bios install\n'
+  fi
+}
+
+# ---- dispatch ------------------------------------------------------------
+CMD="${1:-help}"
+if [ $# -gt 0 ]; then shift; fi
+
+# `learn` forwards its arguments and stdin straight to the collector, so it must
+# bypass the flag parser below (which rejects anything it does not know). This
+# subcommand is the only PATH-reachable entry to capture: the corpus guide used
+# to invoke learn/collect-learning.py relative to the cwd, which works from a
+# clone and silently fails for every other install.
+if [ "$CMD" = "learn" ]; then
+  collector="$REPO/learn/collect-learning.py"
+  [ -f "$collector" ] || { log "learn: collector missing at $collector"; exit 1; }
+  exec python3 "$collector" "$@" <&3
+fi
+
+WITH=""
+DOMAINS_ARG=""
+DOMAINS_SET=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dry-run) DRY_RUN=1 ;;
+    --with) shift; WITH="${1:-}"; [ -n "$WITH" ] || { log "--with needs a comma-separated capability list"; exit 2; } ;;
+    --with=*) WITH="${1#--with=}"; [ -n "$WITH" ] || { log "--with needs a comma-separated capability list"; exit 2; } ;;
+    --domains) shift; DOMAINS_ARG="${1:-}"; DOMAINS_SET=1; [ -n "$DOMAINS_ARG" ] || { log "--domains needs a comma-separated domain list (use onboard for core-only)"; exit 2; } ;;
+    --domains=*) DOMAINS_ARG="${1#--domains=}"; DOMAINS_SET=1; [ -n "$DOMAINS_ARG" ] || { log "--domains needs a comma-separated domain list (use onboard for core-only)"; exit 2; } ;;
+    *) log "unknown flag: $1"; exit 2 ;;
+  esac
+  shift
+done
+
+case "$CMD" in
+  install)   cmd_install ;;
+  onboard)   cmd_onboard ;;
+  update)    cmd_update ;;
+  uninstall) cmd_uninstall ;;
+  verify)    if cmd_verify; then log "VERIFY OK"; else log "VERIFY FAILED"; exit 1; fi ;;
+  status)    cmd_status ;;
+  help|-h|--help) usage ;;
+  *) log "unknown command: $CMD"; usage; exit 2 ;;
+esac