agent-bios 0.1.0 → 0.3.0

package/scripts/check-parity.sh

@@ -111,6 +111,8 @@ current-state dashboard|claude/CLAUDE.md|claude/guides/implementation-map.md
 Verification Menus|claude/CLAUDE.md|claude/guides/coding-staged-workflow.md
 real Microsoft Excel engine|claude/CLAUDE.md|claude/guides/coding-staged-workflow.md
 severity contract|README.md|claude/guides/coding-staged-workflow.md
+Ambient state|claude/CLAUDE.md|claude/guides/tooling-gotchas.md
+the full lifecycle of what you create|claude/CLAUDE.md|claude/guides/tooling-gotchas.md
 ANCHORS
 
 # The launcher's Textual preflight UI tests need the managed venv (textual).
@@ -264,6 +266,33 @@ for filename, (expected_name, expected_model, expected_effort) in expected_agent
             f"want {expected_effort!r}"
         )
 
+# codex/config-additions.toml is the additive fragment install merges into the
+# live ~/.codex/config.toml; its agent entries are projections of the canonical
+# codex/agents/*.toml templates and must not drift from them.
+fragment_path = pathlib.Path("codex/config-additions.toml")
+if not fragment_path.is_file():
+    mark_fail("required file missing: codex/config-additions.toml")
+else:
+    fragment = tomllib.loads(fragment_path.read_text())
+    if fragment.get("features", {}).get("multi_agent") is not True:
+        mark_fail("config-additions must set features.multi_agent = true")
+    fragment_agents = fragment.get("agents", {})
+    if set(fragment_agents) != {"frontier", "workhorse", "sweep"}:
+        mark_fail(
+            "config-additions agents must be exactly the spawnable tiers "
+            f"(no helm): {sorted(fragment_agents)}"
+        )
+    for tier, spec in fragment_agents.items():
+        template_path = agent_dir / f"{tier}.toml"
+        template = tomllib.loads(template_path.read_text()) if template_path.is_file() else {}
+        if spec.get("description") != template.get("description"):
+            mark_fail(f"config-additions {tier} description drifted from {template_path}")
+        if spec.get("config_file") != f"${{CODEX_HOME}}/agents/{tier}.toml":
+            mark_fail(
+                f"config-additions {tier} config_file must be "
+                f"${{CODEX_HOME}}/agents/{tier}.toml"
+        )
+
 
 def table_row(path, slot):
     for raw_line in path.read_text().splitlines():
@@ -522,7 +551,7 @@ if launcher.is_file() and launch_profile:
             def set_plan(self, plan):
                 self.plan = plan
 
-            def choose(self, title, options, default, allow_back, preview=None):
+            def choose(self, title, options, default, allow_back, preview=None, learning_lines=None):
                 if title == "Preset":
                     if preview is not None:
                         balanced = launcher_module.setup_summary_lines(preview("balanced"))
@@ -748,6 +777,7 @@ if launcher.is_file() and launch_profile:
             (b"Esc cancel | q cancel", b"\x1b[B"),
             (b"hybrid onto", b"\x1b[B"),
             (b"high-volume", b"\x1b[B"),
+            (b"learning-refinement", b"\x1b[B"),
             (b"Open a settings hub", b"\r"),
         )
         down = b"\x1b[B"
@@ -1098,10 +1128,11 @@ if launcher.is_file() and launch_profile:
         # TERM=dumb routes to numbered prompts (textual renders on any usable
         # terminal, so the numbered fallback is gated on TERM/non-TTY/textual
         # availability, not a terminfo probe). 'b' is the numbered back command.
+        custom_number = str(len(fake_data["presets"]) + 1).encode()
         transcript, picker_status = run_picker_scenario(
             "numbered fallback (TERM=dumb)",
             (
-                (b"Open a settings hub", b"4\n"),
+                (b"Open a settings hub", custom_number + b"\n"),
                 (b"Custom settings", b"b\n"),
                 (b"HELM default for everyday work", b"1\n"),
             ),
@@ -1114,6 +1145,28 @@ if launcher.is_file() and launch_profile:
         ):
             mark_fail("agent-launch numbered fallback (TERM=dumb) did not preserve numbered back")
 
+        # Session Learning hub: enter, render status, back out, launch balanced.
+        learning_number = str(len(fake_data["presets"]) + 2).encode()
+        transcript, picker_status = run_picker_scenario(
+            "numbered learning hub (TERM=dumb)",
+            (
+                (b"Session Learning", learning_number + b"\n"),
+                (b"Versions & rollback", b"4\n"),
+                (b"HELM default for everyday work", b"1\n"),
+            ),
+            term="dumb",
+        )
+        learning_panel_rendered = (
+            b"Applied version" in transcript or b"not projected yet" in transcript
+        )
+        if (
+            picker_status != 0
+            or b"Traceback" in transcript
+            or not learning_panel_rendered
+            or b"Preset         Balanced" not in transcript
+        ):
+            mark_fail("agent-launch numbered learning hub did not render or return")
+
         passed = invoke([
             sys.executable, str(launcher), "--no-tui", "codex", "--", "exec", "--json", "probe"
         ], env=env)
@@ -1421,7 +1474,16 @@ if launcher.is_file() and launch_profile:
             except (ValueError, IndexError, json.JSONDecodeError) as exc:
                 mark_fail(f"agent-launch Claude --agents projection is not valid JSON: {exc}")
             else:
-                for tier, (model, effort) in expected_claude_tiers.items():
+                expected_spawnable = {
+                    tier: expected_claude_tiers[tier]
+                    for tier in ("frontier", "workhorse", "sweep")
+                }
+                if set(agents_arg) != set(expected_spawnable):
+                    mark_fail(
+                        "Claude --agents must project exactly the spawnable tiers "
+                        f"(HELM is the main, never a subagent): {sorted(agents_arg)}"
+                    )
+                for tier, (model, effort) in expected_spawnable.items():
                     role = agents_arg.get(tier, {})
                     if role.get("model") != model or role.get("effort") != effort:
                         mark_fail(f"agent-launch Claude {tier} role projection drifted: {role!r}")
@@ -1585,7 +1647,8 @@ if launcher.is_file() and launch_profile:
             unavailable,
             "agent-launch codex degrade-to-native review",
             (
-                "Review setup   hybrid → effective native (onto,ultracode unavailable)",
+                "Review setup   hybrid → effective native (onto,ultracode unavailable;"
+                " install: npm i -g onto-mcp && npm i -g ultracode-for-codex)",
                 "degraded to native same-model",
                 "fall back to native same-model subagent review",
             ),
@@ -1600,7 +1663,8 @@ if launcher.is_file() and launch_profile:
             unavailable_claude,
             "agent-launch claude degrade-to-native review",
             (
-                "Review setup   hybrid → effective native (onto,ultracode unavailable)",
+                "Review setup   hybrid → effective native (onto,ultracode unavailable;"
+                " install: npm i -g onto-mcp && npm i -g ultracode-for-codex)",
                 "fall back to native same-model subagent review",
             ),
             ("--mcp-config",),
@@ -1637,8 +1701,11 @@ if launcher.is_file() and launch_profile:
             ):
                 mark_fail("saved codex tier override leaked into the claude host")
             launcher_module.save_preset(round_trip, reloaded, save_target, "mysetup")
-            if save_target.read_text().count("[presets.mysetup]") != 1:
+            saved_file = launcher_module.user_presets_path(save_target)
+            if saved_file.read_text().count("[presets.mysetup]") != 1:
                 mark_fail("re-saving a preset duplicated its block")
+            if "[presets.mysetup]" in save_target.read_text():
+                mark_fail("save_preset wrote a user preset into the installer-owned config")
 
         # The Custom hub 'save' action persists the named preset then launches.
         ui_save_target = tmp / "ui-save.toml"

package/scripts/check-prompting-targets.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# Prompting guides are model-version-bound: unlike the rest of the guide set,
+# their rules change when the model changes (the current generation inverted the
+# previous one's advice). So they name concrete models, and this gate keeps that
+# naming honest — it fails when the launch config binds a model no prompting
+# guide covers, which is exactly when the guidance needs re-deriving from the
+# vendor's current docs.
+set -u
+cd "$(dirname "$0")/.." || exit 2
+
+python3 - "$@" <<'PY'
+import pathlib, re, sys, tomllib
+
+config = pathlib.Path("config/agent-launch.toml")
+hosts = tomllib.loads(config.read_text())["hosts"]
+
+# host -> the guide that owns prompting guidance for that host's model family
+OWNERS = {"codex": "gpt-prompting", "claude": "claude-prompting"}
+
+def targets(guide_id):
+    path = pathlib.Path(f"codex/guides/{guide_id}.md")
+    if not path.is_file():
+        sys.exit(f"FAIL: missing prompting guide: {path}")
+    front = re.match(r"---\n(.*?)\n---\n", path.read_text(), re.S)
+    if not front:
+        sys.exit(f"FAIL: missing YAML frontmatter: {path}")
+    block = re.search(r"^targets:\n((?:\s+-\s+\S+\n)+)", front.group(1), re.M)
+    if not block:
+        sys.exit(f"FAIL: {path} declares no targets:")
+    return {line.strip().lstrip("- ").strip() for line in block.group(1).splitlines()}
+
+fail = 0
+for host, guide_id in OWNERS.items():
+    configured = set(hosts.get(host, {}).get("models", []))
+    for tier in hosts.get(host, {}).get("tiers", {}).values():
+        if tier.get("model"):
+            configured.add(tier["model"])
+    if not configured:
+        print(f"FAIL: no models configured for host {host}; nothing to check")
+        fail = 1
+        continue
+    declared = targets(guide_id)
+    stale = sorted(configured - declared)
+    if stale:
+        print(
+            f"FAIL: {guide_id}.md does not cover configured {host} model(s): "
+            f"{', '.join(stale)} — re-derive it from current vendor guidance and "
+            f"update its targets:"
+        )
+        fail = 1
+    else:
+        print(f"  {guide_id}: covers all {len(configured)} configured {host} model(s)")
+    unused = sorted(declared - configured)
+    if unused:
+        print(f"  note: {guide_id} also targets unbound model(s): {', '.join(unused)}")
+
+sys.exit(fail)
+PY
+status=$?
+[ $status -eq 0 ] && echo "PROMPTING TARGETS OK: every configured model is covered" \
+                  || echo "PROMPTING TARGETS FAILED"
+exit $status

package/scripts/codex-helm.sh

@@ -268,9 +268,27 @@ EOF
 EOF
 }
 
+# Review packets must carry the whole subject: range-based diffs silently omit
+# staged-but-uncommitted changes and untracked files, so the dispatcher itself
+# appends the subject tree's actual state to the packet.
+scope_note=""
+if [ "$mode" = "review" ] && { [ -n "$cd_dir" ] || [ "$reach" != "hermetic" ]; }; then
+  scope_root="${cd_dir:-$PWD}"
+  if git -C "$scope_root" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    scope_status="$(git -C "$scope_root" status --porcelain 2>/dev/null || true)"
+    if [ -n "$scope_status" ]; then
+      scope_note="Review scope manifest (dispatcher-generated \`git status --porcelain\` of the subject tree; uncommitted/untracked entries are part of the review subject unless the task says otherwise):
+$scope_status"
+      echo "codex-helm: subject tree has uncommitted/untracked entries; scope manifest appended to the packet" >&2
+    fi
+  fi
+fi
+
 final_prompt="$(build_preamble)
 
-User task:
+${scope_note:+$scope_note
+
+}User task:
 $user_prompt"
 
 cleanup_dirs=()

package/scripts/codex-run.sh

@@ -167,6 +167,25 @@ if [ "${#extra_c[@]}" -gt 0 ]; then
   for kv in "${extra_c[@]}"; do args+=(-c "$kv"); done
 fi
 
+# Dispatch audit: verifier diversity is only as real as the pinned backing
+# model — an unpinned dispatch inherits config defaults and can silently
+# collapse two "different" reviewers onto one backend. The audit line goes to
+# the log file only; stdout/stderr stay reserved for the codex channels.
+sandbox_label="$sandbox"
+if [ "$bypass_sandbox" -eq 1 ]; then sandbox_label="bypass"; fi
+cmodel=""
+if [ "${#extra_c[@]}" -gt 0 ]; then
+  for kv in "${extra_c[@]}"; do
+    case "$kv" in model=*) cmodel="${kv#model=}" ;; esac
+  done
+fi
+dispatch_note="dispatch profile=$profile model=${model:-INHERITED_DEFAULT}${cmodel:+ c-model-override=$cmodel} effort=${effort:-config-default} sandbox=$sandbox_label"
+if [ -z "$model" ] && [ -z "$cmodel" ]; then
+  echo "codex-run: WARNING: no --model pin; the backing model inherits the active config default" >&2
+fi
+mkdir -p "$real_home/log" 2>/dev/null || true
+printf '%s %s\n' "$(date +%Y-%m-%dT%H:%M:%S%z)" "$dispatch_note" >> "$real_home/log/codex-run-dispatch.log" 2>/dev/null || true
+
 # stdin, stdout, and stderr already match this adapter's channel contract.
 set +e
 CODEX_HOME="$run_home" codex "${args[@]}"

package/scripts/install.sh

@@ -44,6 +44,7 @@ REPO="$(cd "$SELF/.." && pwd)"
 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
@@ -125,6 +126,259 @@ migrate_state() {
   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. config/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/config/agent-launch.toml" <<'PY'
+import sys, tomllib
+for name, cap in tomllib.load(open(sys.argv[1], "rb")).get("capabilities", {}).items():
+    print("\t".join((name, cap.get("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)"
+      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/config/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"
@@ -147,14 +401,22 @@ cmd_install() {
   log "Deploying agent-bios from $REPO"
   deploy_file "$REPO/claude/CLAUDE.md" "$CLAUDE_DIR/CLAUDE.md"
   deploy_glob "$REPO/claude/guides" "*.md" "$CLAUDE_DIR/guides"
+  deploy_glob "$REPO/claude/agents" "*.md" "$CLAUDE_DIR/agents"
+  deploy_glob "$REPO/claude/hooks" "*.py" "$CLAUDE_DIR/hooks" "+x"
   deploy_file "$REPO/codex/AGENTS.md" "$CODEX_DIR/AGENTS.md"
   deploy_glob "$REPO/codex/guides" "*.md" "$CODEX_DIR/guides"
   deploy_glob "$REPO/codex/agents" "*.toml" "$CODEX_DIR/agents"
+  codex_config_additions merge || exit 1
   deploy_file "$REPO/scripts/codex-run.sh"  "$CODEX_DIR/bin/codex-run"  "+x"
   deploy_file "$REPO/scripts/codex-helm.sh" "$CODEX_DIR/bin/codex-helm" "+x"
+  migrate_user_presets || exit 1   # must precede the deploy below, which overwrites profiles.toml
   deploy_file "$REPO/config/agent-launch.toml" "$LAUNCH_DIR/profiles.toml"
   deploy_file "$REPO/shell/agent-launch.zsh"   "$LAUNCH_DIR/shell.zsh"
   deploy_file "$REPO/scripts/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
@@ -162,12 +424,19 @@ cmd_install() {
       || log "warning: venv provisioning failed (numbered-prompt fallback applies)"
   fi
   add_zsh_hook
+  if python3 "$REPO/scripts/session-learning/learning-state.py" project --repo "$REPO" >/dev/null 2>&1; then
+    info "learning-status projected"
+  else
+    log "note: learning-status projection unavailable (versions.json/ledger missing?)"
+  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."
-    [ -n "$BACKUP_DIR" ] && [ -d "$BACKUP_DIR" ] && log "Replaced files were backed up under $BACKUP_DIR"
+    # 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
   else
     log "VERIFY FAILED after install — see messages above"
     exit 1
@@ -185,6 +454,8 @@ cmd_verify() {
   verify_match "$REPO/config/agent-launch.toml" "$LAUNCH_DIR/profiles.toml"   || fail=1
   verify_match "$REPO/shell/agent-launch.zsh"  "$LAUNCH_DIR/shell.zsh"        || fail=1
   for gp in "$REPO"/claude/guides/*.md; do verify_present "$CLAUDE_DIR/guides/$(basename "$gp")" || fail=1; done
+  for gp in "$REPO"/claude/agents/*.md; do verify_present "$CLAUDE_DIR/agents/$(basename "$gp")" || fail=1; done
+  for gp in "$REPO"/claude/hooks/*.py;  do verify_present "$CLAUDE_DIR/hooks/$(basename "$gp")"  || fail=1; done
   for gp in "$REPO"/codex/guides/*.md;  do verify_present "$CODEX_DIR/guides/$(basename "$gp")"  || fail=1; done
   python3 - "$CODEX_DIR/agents" <<'PY' && info "agent TOMLs OK" || fail=1
 import sys, pathlib, tomllib
@@ -195,6 +466,7 @@ 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"
@@ -212,11 +484,22 @@ PY
   if [ -d "$REPO/ko" ] && [ -x "$REPO/scripts/check-parity.sh" ]; then
     if "$REPO/scripts/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/scripts/check-prompting-targets.sh" ]; then
+    if "$REPO/scripts/check-prompting-targets.sh" >/dev/null 2>&1; then
+      info "prompting targets OK"
+    else
+      log "prompting guides do not cover a configured model; run scripts/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"
   if [ -f "$MANIFEST" ]; then
     local f
     while IFS= read -r f; do
@@ -234,7 +517,7 @@ cmd_uninstall() {
     done
   fi
   local d
-  for d in "$CLAUDE_DIR/guides" "$CODEX_DIR/guides" "$CODEX_DIR/agents" "$CODEX_DIR/bin" "$LAUNCH_DIR"; do
+  for d in "$CLAUDE_DIR/guides" "$CLAUDE_DIR/agents" "$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
@@ -284,7 +567,12 @@ agent-bios — deploy the Claude/Codex instruction SSOT into $HOME (by copy).
   agent-bios uninstall   remove deployed files and the zsh hook
   agent-bios help
 
-Flags: --dry-run   print actions without changing anything
+Flags: --dry-run       print actions without changing anything
+       --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.
+                      Known: onto, ultracode. 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
 }
@@ -292,11 +580,15 @@ EOF
 # ---- dispatch ------------------------------------------------------------
 CMD="${1:-help}"
 if [ $# -gt 0 ]; then shift; fi
-for a in "$@"; do
-  case "$a" in
+WITH=""
+while [ $# -gt 0 ]; do
+  case "$1" in
     --dry-run) DRY_RUN=1 ;;
-    *) log "unknown flag: $a"; exit 2 ;;
+    --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; } ;;
+    *) log "unknown flag: $1"; exit 2 ;;
   esac
+  shift
 done
 
 case "$CMD" in