agent-bios 0.10.0 → 0.12.0

package/install.sh

@@ -11,6 +11,7 @@
 #   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 cost        the session cost / context meter, from any directory
 #   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
@@ -70,6 +71,18 @@ HOOK_MARK='agent-launch/shell.zsh'
 
 DRY_RUN=0
 BACKUP_DIR=""
+# Set when uninstall could not undo the spans the assembler merged into files we do not own.
+# Global for the same reason UNBACKED is: the closing summary must not claim a clean removal
+# that did not happen.
+CLEANUP_FAILED=0
+# Set when the assembler reported the user-owned entry file needs a line added by hand. That
+# is an outstanding ACTION, not a failed deployment: everything else really did land, and
+# treating it as a failure made cmd_install exit 1 and the EXIT trap restore the previous
+# manifest — leaving the new corpus on disk with the record saying the old one was deployed.
+ENTRY_NEEDS_ACTION=0
+# Deployed files uninstall could not back up, so did not delete. Global rather than local
+# because the closing summary must not claim a clean removal that did not happen.
+UNBACKED=0
 
 log()  { printf '%s\n' "$*"; }
 info() { printf '  %s\n' "$*"; }
@@ -117,6 +130,115 @@ deploy_glob() {
   done
 }
 
+# A subtree, file by file, so every file lands in the manifest by its own name — the
+# ownership rule the hooks fix settled on. Skills need this: a skill is a directory
+# (SKILL.md plus free subdirectories) that lands in a directory the host scans and other
+# tools populate, so nothing may claim it by path prefix, and uninstall removes exactly
+# the names we wrote. `find -type f`, not a glob: subdirectories are the format.
+deploy_tree() {
+  local srcdir="$1" dstdir="$2" f rel
+  [ -d "$srcdir" ] || { log "source tree missing: $srcdir"; return 1; }
+  while IFS= read -r f; do
+    rel="${f#"$srcdir"/}"
+    deploy_file "$f" "$dstdir/$rel"
+  done < <(find "$srcdir" -type f | LC_ALL=C sort)
+}
+
+# The skills we ship: every subdirectory of the repo's claude/skills/. One tree serves both
+# hosts — the format is identical (SKILL.md + name/description frontmatter + free
+# subdirectories) and the body names no host path — so the same files land under each
+# host's skills directory. Iterated here rather than listed, so a second skill ships by
+# being added to the tree. This is the SHIPPED set — what the tree carries; what a given
+# machine RECEIVES is the selected set below.
+shipped_skills() {
+  local d
+  for d in "$REPO/claude/skills"/*/; do
+    [ -f "$d/SKILL.md" ] || continue
+    basename "$d"
+  done
+}
+
+# The selection, as the assembler receives it: an explicit --domains, else the saved
+# selection.json, else every domain (what "full" means). One function so the corpus and
+# the skills are always answered from the same selection — a skill decided from a
+# different reading than the bundle would ship a package the bundle disagrees with.
+selection_args() {   # -> SEL_ARGS
+  SEL_ARGS=()
+  if [ "${DOMAINS_SET:-0}" = 1 ]; then
+    SEL_ARGS=(--domains "$DOMAINS_ARG")
+  elif [ ! -f "$STATE_DIR/selection.json" ]; then
+    SEL_ARGS=(--domains "$(all_domains_csv)")
+  fi
+}
+
+# The skills this selection delivers, by name. Skills are classified in
+# compose/domains.json like guides, hooks and agents, and the assembler owns the rule
+# that turns a classification and a selection into a delivered set; this asks it rather
+# than reading domains.json here, so there is one owner of "who gets what". Deploy,
+# prune and verify all iterate THIS list; a skill the tree ships but the selection does
+# not cover is treated exactly like a file a later release withdrew.
+selected_skills() {
+  selection_args
+  python3 "$REPO/compose/assemble.py" --selected-skills --state-dir "$STATE_DIR" \
+    ${SEL_ARGS[@]+"${SEL_ARGS[@]}"}
+}
+
+# Membership in the selected set, for the loops that iterate the shipped one. Refuses to
+# answer before the set is resolved: an unset variable read as "nothing selected" would
+# make prune remove every skill and verify demand every absence — the fail-open shape.
+skill_selected() {   # $1: skill name; reads SELECTED_SKILLS
+  [ -n "${SELECTED_SKILLS+x}" ] || { log "BUG: skill selection read before it was resolved"; exit 1; }
+  case " $(printf '%s' "$SELECTED_SKILLS" | tr '\n' ' ') " in *" $1 "*) return 0 ;; esac
+  return 1
+}
+
+# Our skill directories, and only ours: `$CLAUDE_DIR/skills` and `$CODEX_DIR/skills` are
+# the hosts' shared scan directories, holding other tools' skills, and are never touched.
+# Deepest first, so a skill's subdirectories go before the skill itself; rmdir throughout,
+# so a directory holding anything we did not write is left, visibly.
+rmdir_skill_dirs() {
+  local skill="$1" sd d
+  for sd in "$CLAUDE_DIR/skills/$skill" "$CODEX_DIR/skills/$skill"; do
+    [ -d "$sd" ] || continue
+    while IFS= read -r d; do
+      rmdir "$d" 2>/dev/null && info "removed empty  $d" || true
+    done < <(find "$sd" -depth -type d)
+  done
+}
+
+# A skill file the PREVIOUS install wrote and this release no longer ships is ours by the
+# prior manifest and would otherwise stay on disk unowned: the rebuilt manifest stops
+# naming it, verify enumerates only current files, and the host keeps loading it. So the
+# prior manifest is read for paths under either host's skills root that no shipped file
+# maps to, and those are removed — backed up like any overwrite — before the deploy.
+# Only skill paths: every other deploy target is a fixed name a later release overwrites
+# in place. Only names the manifest proves we wrote.
+prune_stale_skills() {
+  local prior="$PRIOR_MANIFEST" f skill rel touched=""
+  [ "$DRY_RUN" = 1 ] && prior="$MANIFEST"
+  [ -f "$prior" ] || return 0
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    case "$f" in
+      "$CLAUDE_DIR/skills/"*) rel="${f#"$CLAUDE_DIR/skills/"}" ;;
+      "$CODEX_DIR/skills/"*)  rel="${f#"$CODEX_DIR/skills/"}" ;;
+      *) continue ;;
+    esac
+    skill="${rel%%/*}"; rel="${rel#*/}"
+    # Still shipped AND still selected: only that combination keeps a prior file. A
+    # deselected skill's files are stale exactly like a withdrawn release's — the host
+    # would go on loading them for a package the user no longer takes.
+    [ -f "$REPO/claude/skills/$skill/$rel" ] && skill_selected "$skill" && continue
+    [ -f "$f" ] || continue
+    if [ -n "$BACKUP_DIR" ] && [ "$DRY_RUN" != 1 ]; then
+      mkdir -p "$(dirname "$BACKUP_DIR$f")" && cp "$f" "$BACKUP_DIR$f"
+    fi
+    run rm -f "$f"; [ "$DRY_RUN" = 1 ] || info "removed stale skill file  $f"
+    case " $touched " in *" $skill "*) ;; *) touched="$touched $skill" ;; esac
+  done < "$prior"
+  for skill in $touched; do rmdir_skill_dirs "$skill"; 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
@@ -207,15 +329,17 @@ prune_withheld() {
 # 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.
+all_domains_csv() {
+  python3 -c "import json,sys;print(','.join(sorted(json.load(open(sys.argv[1]))['domains'])))" \
+    "$REPO/compose/domains.json"
+}
+
 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
+  # 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 (selection_args).
+  selection_args
+  args+=(${SEL_ARGS[@]+"${SEL_ARGS[@]}"})
   [ "$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"
@@ -223,24 +347,46 @@ assemble_corpus() {
   [ -f "$prior" ] && args+=(--prior-manifest "$prior")
   python3 "$REPO/compose/assemble.py" "${args[@]}" || rc=$?
   if [ "$rc" = 2 ]; then
+    ENTRY_NEEDS_ACTION=1
     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
+    # The ownership rule is the assembler's, and it is one rule for every destination: the
+    # name exists in our source tree (compose/assemble.py copy_filtered — "it is not in
+    # src_dir, so it is never a candidate"). `central/` was exempted as "ours whole" and
+    # scanned, which claimed whatever a user had put there — and uninstall removes whatever
+    # the manifest names, so the assembler's care was undone one step later. That is the
+    # same defect this comment records having fixed for the SHARED $CODEX_DIR/guides; the
+    # directory being ours by convention did not make the scan a different mistake.
+    # bundle.md is generated rather than copied, so it has no source name and is ours
+    # unconditionally.
+    local g dst sub s
+    if [ -f "$CLAUDE_DIR/central/bundle.md" ]; then
+      printf '%s\n' "$CLAUDE_DIR/central/bundle.md" >> "$MANIFEST"
+    fi
+    for sub in guides hooks agents; do
+      for s in "$REPO"/claude/"$sub"/*; do
+        [ -f "$s" ] || continue
+        dst="$CLAUDE_DIR/central/$sub/$(basename "$s")"
+        # if-form for the reason spelled out below: a trailing false status becomes the
+        # loop's, then the function's, and the install dies silently after ASSEMBLED.
+        if [ -f "$dst" ]; then printf '%s\n' "$dst" >> "$MANIFEST"; fi
+      done
+    done
     for g in "$REPO"/codex/guides/*.md; do
       [ -f "$g" ] || continue
       dst="$CODEX_DIR/guides/$(basename "$g")"
-      [ -f "$dst" ] && printf '%s\n' "$dst" >> "$MANIFEST"
+      # if-form, not `[ -f ] && printf`: when the alphabetically LAST guide is
+      # not deployed (a partial domain selection on a fresh machine), the
+      # compound's false status became the loop's, the loop's became the
+      # function's, and the install died silently right after ASSEMBLED —
+      # a latent first-user bug the I9 scenario exposed.
+      if [ -f "$dst" ]; then printf '%s\n' "$dst" >> "$MANIFEST"; fi
     done
   fi
+  return 0
 }
 
 add_zsh_hook() {
@@ -560,7 +706,18 @@ 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")
+  # The SAME three-way assemble_corpus resolves, because these two must be answering one
+  # question. Naming only the selection file made a fresh `--dry-run` preview migration as
+  # "skipped" — a dry run deliberately does not write selection.json, while the real run
+  # writes it moments earlier and then migrates for real. A preview that reports the
+  # opposite of what the run does is worse than no preview.
+  if [ "${DOMAINS_SET:-0}" = 1 ]; then
+    sel=(--domains "$DOMAINS_ARG")
+  elif [ -f "$STATE_DIR/selection.json" ]; then
+    sel=(--selection-file "$STATE_DIR/selection.json")
+  else
+    sel=(--domains "$(all_domains_csv)")
+  fi
   [ "$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.
@@ -579,6 +736,18 @@ cmd_install() {
     BACKUP_DIR="$STATE_DIR/backups/$(date +%Y%m%d-%H%M%S)"
     [ -f "$MANIFEST" ] && cp "$MANIFEST" "$PRIOR_MANIFEST"
     : > "$MANIFEST"
+    # The manifest is emptied here and refilled as files are deployed, so between this
+    # line and a completed install it does not describe what is on disk. An install that
+    # fails in between — `--domains no-such-domain` is enough — left it EMPTY, and
+    # `uninstall` consumes it: it removed nothing, exited 0, and told the user the
+    # uninstall had succeeded while all fifty deployed files were still there. A
+    # destructive command reporting success for doing nothing is the worst reading in
+    # this file, so the prior manifest goes back unless the install reaches the end.
+    INSTALL_COMPLETED=0
+    trap 'if [ "${INSTALL_COMPLETED:-0}" != 1 ] && [ -f "$PRIOR_MANIFEST" ]; then
+            cp "$PRIOR_MANIFEST" "$MANIFEST"
+            log "install did not complete; restored the previous manifest so uninstall still knows what was deployed"
+          fi' EXIT
   fi
   log "Deploying agent-bios from $REPO"
   # Refuse loudly before doing any work: an unreadable declaration must not degrade
@@ -591,6 +760,16 @@ cmd_install() {
   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"
+  # Resolved once, before the prune that reads it: an assembler that cannot answer must
+  # stop the install here, not let `for skill in $(...)` iterate an empty answer and
+  # deploy nothing while reporting success.
+  SELECTED_SKILLS="$(selected_skills)" || { log "could not resolve the selected skills"; exit 1; }
+  prune_stale_skills
+  local skill
+  for skill in $SELECTED_SKILLS; do
+    deploy_tree "$REPO/claude/skills/$skill" "$CLAUDE_DIR/skills/$skill" || exit 1
+    deploy_tree "$REPO/claude/skills/$skill" "$CODEX_DIR/skills/$skill" || exit 1
+  done
   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"
@@ -601,7 +780,45 @@ cmd_install() {
   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"
+  # UI text catalogs: deploy-managed siblings of the config, one per language.
+  # The launcher resolves them from the config path, so the deployed home is
+  # $LAUNCH_DIR/i18n exactly as the checkout's is launch/i18n.
+  #
+  # The launcher goes FIRST, and the order is chosen for how an interrupted
+  # install FAILS rather than for how much it breaks. The deployed launcher keeps
+  # no catalog beside itself -- it lives in $BIN_DIR while the catalogs live under
+  # $LAUNCH_DIR -- so it renders whatever is deployed, and the two orders leave
+  # opposite states:
+  #
+  #   launcher first  -> new launcher, old catalogs: keys it added render as their
+  #                      own names AND t() prints "the deployed catalogs are older
+  #                      than this launcher; run: agent-bios install". Loud, and
+  #                      the message is the fix.
+  #   catalogs first  -> old launcher, new catalogs: a value whose SHAPE changed
+  #                      renders its template. Measured on the 1ba2d82 launcher
+  #                      against these catalogs, the checklist drew
+  #                      "선택 적용{pending}" with no diagnostic at all.
+  #
+  # The second is less broken and entirely silent, which is the worse trade: a
+  # user cannot act on what does not announce itself. This ordering was briefly
+  # the other way round on the claim that spare keys are harmless; they are, but
+  # changed values are not, and four keys in this change altered shape.
+  #
+  # The loudness is contingent, not structural, and narrower than an earlier version
+  # of this comment claimed: the notice fires only for a key the FIRST SCREEN itself
+  # requests and the old catalogs lack. Adding keys anywhere is not enough. This
+  # release adds four and the root screen requests none of them — they are reached
+  # from the registration wizard and the corpus screens — so for this release the
+  # ordering buys no diagnostic at all, only the smaller blast radius of a launcher
+  # that is newer than its catalogs rather than older. The shape-changed keys are
+  # silent in that direction too: an old value with no slot formats to itself and the
+  # argument simply vanishes. Keep the order for the blast radius; do not rely on the
+  # diagnostic unless a release actually adds a root-screen key.
   deploy_file "$REPO/launch/agent-launch.py"  "$BIN_DIR/agent-launch" "+x"
+  local lang
+  for lang in en ko ja; do
+    deploy_file "$REPO/launch/i18n/$lang.toml" "$LAUNCH_DIR/i18n/$lang.toml"
+  done
   log ""
   log "Optional dependencies (missing ones only degrade the routes that need them)..."
   handle_capabilities "$WITH" || exit 1
@@ -613,7 +830,15 @@ cmd_install() {
       || 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
+  # Guarded, because this WRITES. The projection takes a lock and rewrites
+  # corpus-status.json, and it sat outside the dry-run branch above — so
+  # `install --dry-run` changed the file whose whole purpose is to describe what is
+  # deployed, against this script's own `--dry-run  print actions without changing
+  # anything` and README's identical sentence. A dry run that edits state is worse than
+  # no dry run: it is consulted precisely when the user is unwilling to touch anything.
+  if [ "$DRY_RUN" = 1 ]; then
+    info "[dry-run] project corpus-status"
+  elif 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?)"
@@ -653,10 +878,29 @@ PY
     fi
   fi
   log ""
+  if [ "$DRY_RUN" = 1 ]; then
+    # A dry run wrote nothing, so there is nothing of THIS plan to verify. Running the live
+    # verifier anyway made a valid preview exit 1 on any machine where the planned files are
+    # not already present — which is every fresh one, the case a preview is most for. On an
+    # installed machine it is no better: it would be reporting on the previous install while
+    # standing where a verdict on the plan just printed belongs.
+    INSTALL_COMPLETED=1
+    log "[dry-run] nothing was written, so nothing is verified — re-run without --dry-run to install."
+    return 0
+  fi
   log "Verifying deployment..."
   if cmd_verify; then
+    # Reached the end: the manifest now describes what is actually deployed, so the
+    # restore armed above must not fire.
+    INSTALL_COMPLETED=1
     log ""
     log "Done. Open a new shell (or: source \"$ZSHRC\") to activate the zero-arg launcher."
+    if [ "${ENTRY_NEEDS_ACTION:-0}" = 1 ]; then
+      log ""
+      log "ONE STEP LEFT: add this line to $CLAUDE_DIR/CLAUDE.md (yours; we never rewrite it):"
+      log "  @central/bundle.md"
+      log "Until then the deployed corpus will not load."
+    fi
     # 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
@@ -695,6 +939,12 @@ cmd_verify() {
   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"
+  elif [ "${ENTRY_NEEDS_ACTION:-0}" = 1 ]; then
+    # The install that just ran said this, and said it because the file is the user's and is
+    # never rewritten. Failing on it a second time turned a deployment that fully succeeded
+    # into one whose record was rolled back. Standalone `agent-bios verify` has this unset,
+    # so it still reports a corpus that is not loading as the failure it is.
+    log "ACTION NEEDED: add '@central/bundle.md' to $CLAUDE_DIR/CLAUDE.md — everything else deployed"
   else
     log "entry $CLAUDE_DIR/CLAUDE.md lacks '@central/bundle.md' — central corpus is NOT loading"; fail=1
   fi
@@ -725,6 +975,14 @@ cmd_verify() {
   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
+  # The catalogs were the one deploy-managed artifact nothing verified, which is
+  # the state that renders key names on screen: the deployed launcher keeps no
+  # catalog beside itself, so whatever is here IS the UI text. Byte-identity, the
+  # same bar as its siblings above.
+  local lang
+  for lang in en ko ja; do
+    verify_match "$REPO/launch/i18n/$lang.toml" "$LAUNCH_DIR/i18n/$lang.toml" || fail=1
+  done
   python3 - "$CODEX_DIR/agents" <<'PY' && info "agent TOMLs OK" || fail=1
 import sys, pathlib, tomllib
 root = pathlib.Path(sys.argv[1])
@@ -735,6 +993,26 @@ for p in sorted(root.glob("*.toml")):
     tomllib.loads(p.read_text())
 PY
   codex_config_additions check || fail=1
+  # Every file of every SELECTED skill, byte-identical on both hosts — the same bar as the
+  # launcher and its catalogs, because a skill's SKILL.md IS what the host reads. A skill
+  # the selection does not deliver must be absent on both hosts, or the host is loading a
+  # package the user did not take.
+  local skill sf rel
+  SELECTED_SKILLS="$(selected_skills)" || { log "could not resolve the selected skills"; fail=1; }
+  for skill in $(shipped_skills); do
+    if skill_selected "$skill"; then
+      while IFS= read -r sf; do
+        rel="${sf#"$REPO/claude/skills/$skill"/}"
+        verify_match "$sf" "$CLAUDE_DIR/skills/$skill/$rel" || fail=1
+        verify_match "$sf" "$CODEX_DIR/skills/$skill/$rel"  || fail=1
+      done < <(find "$REPO/claude/skills/$skill" -type f | LC_ALL=C sort)
+    else
+      for sf in "$CLAUDE_DIR/skills/$skill/SKILL.md" "$CODEX_DIR/skills/$skill/SKILL.md"; do
+        if [ -f "$sf" ]; then log "deselected skill still deployed  $sf"; fail=1
+        else info "absent (deselected)  $sf"; fi
+      done
+    fi
+  done
   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"
@@ -778,7 +1056,20 @@ PY
   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
+    # Output kept, not discarded — the third place in this repo where a gate's own
+    # explanation went to /dev/null and left "it failed" as the entire report. The umbrella
+    # and the install-scenario harness each learned this after a failure cost an eleven-
+    # minute re-run that came back green; verify is where a USER meets it, with no clone to
+    # re-run from.
+    parity_log="$(mktemp -t verify-parity)"
+    if "$REPO/gates/check-parity.sh" >"$parity_log" 2>&1; then
+      info "repo mirror parity OK"; rm -f "$parity_log"
+    else
+      log "repo mirror parity FAILED"
+      grep -a 'FAIL' "$parity_log" | head -10 | sed 's/^/    /'
+      log "    full output: $parity_log"
+      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.
@@ -801,10 +1092,14 @@ cmd_uninstall() {
   # 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
+    # The failure is recorded, not only printed. A warning scrolls past and the summary at
+    # the end went on saying "nothing of ours is left on this machine" — while the spans this
+    # step exists to remove were still in the user's settings.json, now pointing at hook files
+    # the next step deletes. A warning nobody reads is how the two came to disagree.
     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"
+      || { CLEANUP_FAILED=1; 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
@@ -814,15 +1109,37 @@ cmd_uninstall() {
     # 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
+    UNBACKED=0
     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"
+      [ -f "$f" ] || continue
+      if [ -n "$BACKUP_DIR" ] && [ "$DRY_RUN" != 1 ]; then
+        # The rule archive_and_purge applies below, applied here too: only what verifiably
+        # reached a copy may be deleted. The mkdir and the cp both fail silently — a full
+        # disk, a name already taken by a file — and the `&&` chain's result was never read,
+        # so the deployed file was removed anyway and reached neither the backup nor the
+        # archive built from it. Size equality, not cp's status, because the question is
+        # whether it can be restored.
+        if ! { mkdir -p "$(dirname "$BACKUP_DIR$f")" 2>/dev/null \
+               && cp "$f" "$BACKUP_DIR$f" 2>/dev/null \
+               && [ "$(wc -c <"$f" 2>/dev/null)" = "$(wc -c <"$BACKUP_DIR$f" 2>/dev/null)" ]; }; then
+          rm -f "$BACKUP_DIR$f" 2>/dev/null   # a partial copy must not look backed up
+          UNBACKED=$((UNBACKED + 1))
+          log "warning: could not back up $f — leaving it in place"
+          continue
+        fi
       fi
-      [ -f "$f" ] && { run rm -f "$f"; [ "$DRY_RUN" = 1 ] || info "removed  $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"
+    # The manifest survives whenever something it names is still on disk: it is the only
+    # record of what to finish removing, and deleting it would strand those files unowned.
+    if [ "$UNBACKED" -gt 0 ]; then
+      log "warning: $UNBACKED deployed file(s) could not be backed up and were LEFT ON DISK;"
+      log "         keeping $MANIFEST so a later uninstall can finish the job"
+    else
+      [ "$DRY_RUN" = 1 ] || rm -f "$MANIFEST"
+    fi
   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
@@ -837,6 +1154,27 @@ cmd_uninstall() {
              "$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
+    # Skills: only the names the shipped tree carries, mirrored under each host's skills
+    # directory, and only where the file IS ours — byte-identical to what this package
+    # ships. Without a manifest, sameness of content is the one ownership evidence left:
+    # a user who authored their own `skills/repo-charter/SKILL.md` before ever installing
+    # would otherwise lose it here with no backup. Never the directory wholesale either —
+    # a sibling skill of theirs shares the parent.
+    local skill sf rel
+    for skill in $(shipped_skills); do
+      while IFS= read -r sf; do
+        rel="${sf#"$REPO/claude/skills/$skill"/}"
+        for p in "$CLAUDE_DIR/skills/$skill/$rel" "$CODEX_DIR/skills/$skill/$rel"; do
+          if [ -f "$p" ]; then
+            if cmp -s "$sf" "$p"; then
+              run rm -f "$p"; [ "$DRY_RUN" = 1 ] || info "removed  $p"
+            else
+              log "kept     $p (differs from the shipped file and no manifest says we wrote it)"
+            fi
+          fi
+        done
+      done < <(find "$REPO/claude/skills/$skill" -type f | LC_ALL=C sort)
+    done
   fi
   local d
   # `central/` and its subdirectories are entirely ours — the assembler creates them and the
@@ -850,10 +1188,24 @@ cmd_uninstall() {
            "$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
+  local skill
+  for skill in $(shipped_skills); do rmdir_skill_dirs "$skill"; done
   remove_zsh_hook
   archive_and_purge
   log ""
-  log "Uninstalled: deployed files, the zsh hook, state, backups, cache, and the managed venv."
+  if [ "${UNBACKED:-0}" -gt 0 ]; then
+    log "Uninstalled: the zsh hook, state, backups, cache, and the managed venv — and every"
+    log "deployed file EXCEPT the $UNBACKED named above, which had no recoverable copy."
+  else
+    log "Uninstalled: deployed files, the zsh hook, state, backups, cache, and the managed venv."
+  fi
+  if [ "${CLEANUP_FAILED:-0}" = 1 ]; then
+    log ""
+    log "NOT removed: the registrations and instruction region this repo merged into files you"
+    log "own — see the warning above. Re-run uninstall once that is resolved, or remove the"
+    log "agent-bios entries from settings.json and the marked AGENTS.md region by hand."
+    return 1
+  fi
 }
 
 # Uninstall is a SECURITY operation — nothing of ours may survive it on the machine. That
@@ -915,13 +1267,31 @@ archive_and_purge() {
     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" \
+    # The state dir holds the manifest, and the manifest is the only record of what is still
+    # deployed. When cmd_uninstall left a file behind because it could not be backed up,
+    # purging that record here would strand the file unowned — so the same rule that keeps
+    # the file keeps the thing that names it. Everything else goes either way.
+    if [ "${UNBACKED:-0}" -eq 0 ]; then
+      rm -rf "$STATE_DIR"
+    fi
+    rm -rf "$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."
+    elif [ "${UNBACKED:-0}" -gt 0 ]; then
+      # Not "nothing of ours is left": cmd_uninstall said the opposite a moment ago, and two
+      # lines of the same summary disagreeing is how an operator stops reading either.
+      log "Move it somewhere central or delete it. $UNBACKED deployed file(s) and the manifest"
+      log "naming them are still on this machine — re-run uninstall once the copy can be made."
+    elif [ "${CLEANUP_FAILED:-0}" = 1 ]; then
+      # The spans merged into files the user owns are still there — cmd_uninstall says so a
+      # few lines below, and this line saying the opposite in the same summary is how an
+      # operator learns to read neither.
+      log "Move it somewhere central or delete it. What this repo merged into files you own"
+      log "could not be removed — see the warning above."
     else
       log "Move it somewhere central or delete it — nothing of ours is left on this machine."
     fi
@@ -966,14 +1336,44 @@ cmd_onboard() {
   fi
   DOMAINS_ARG="$sel"; DOMAINS_SET=1
   log "selection: ${sel:-<core+infra only>}"
-  cmd_install
+  # Subshelled so a failing install can still record its outcome: the launcher's
+  # corpus checklist reads `last_apply` from corpus-status.json, and an exit with
+  # nothing recorded reads as "nothing happened". cmd_install's shell state stays
+  # in the subshell; everything after here uses only top-level globals.
+  local apply_rc=0
+  # NOT `( cmd_install ) || apply_rc=$?`: a command list that tests the subshell
+  # suppresses errexit for everything inside it, so an unguarded failure in
+  # cmd_install would run through to a zero return (probed on bash 3.2/5.x).
+  # Toggling -e around a STANDALONE subshell keeps errexit live inside while the
+  # outer shell survives to record the outcome.
+  set +e
+  ( set -e; cmd_install )
+  apply_rc=$?
+  set -e
+  if [ "$apply_rc" -ne 0 ]; then
+    python3 "$REPO/compose/corpus-state.py" record-apply \
+      --requested "$sel" --outcome install_failed >/dev/null 2>&1 || true
+    exit "$apply_rc"
+  fi
   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" || {
+  local canary_rc=0
+  bash "$REPO/compose/canary.sh" || canary_rc=$?
+  if [ "$canary_rc" -ne 0 ]; then
+    # rc=1 is a real probe that answered "not loading"; rc=3 is "could not
+    # probe" (no CLI/auth). Both leave the apply unproven, so both record as
+    # canary_failed — the tail carries which, so the panel's loud line does
+    # not send the operator to debug imports over an auth problem.
+    python3 "$REPO/compose/corpus-state.py" record-apply \
+      --requested "$sel" --outcome canary_failed \
+      --error-tail "canary exit $canary_rc$([ "$canary_rc" = 3 ] && printf ' (could not probe)')" \
+      >/dev/null 2>&1 || true
     log "ONBOARDING INCOMPLETE: the bundle is installed but not loading — fix the cause above and re-run: agent-bios verify"
     exit 1
-  }
+  fi
+  python3 "$REPO/compose/corpus-state.py" record-apply \
+    --requested "$sel" --outcome applied >/dev/null 2>&1 || true
   # 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
@@ -1053,7 +1453,7 @@ drift_state() {  # prints: match | drift | unknown
   # (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; branding the unprovable as drift made D-20260809-7954fd'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" ] \
@@ -1106,7 +1506,7 @@ cmd_status() {
         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
+      # The absence is the finding: D-20260809-7954fd 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"
@@ -1156,6 +1556,8 @@ agent-bios — deploy the Claude/Codex instruction SSOT into $HOME (by copy).
                          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 cost        the session cost / context meter (session-cost.py), from any
+                         directory: agent-bios cost [--context [--budget N]] <transcript>
   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
@@ -1205,6 +1607,16 @@ if [ "$CMD" = "learn" ]; then
   [ -f "$collector" ] || { log "learn: collector missing at $collector"; exit 1; }
   exec python3 "$collector" "$@" <&3
 fi
+# `cost` is the same shape for the same reason: the guides tell an installed user to
+# measure with session-cost.py, and on a packaged install that file lives inside the
+# npm package where no PATH reaches it — the instruction resolved to "command not
+# found" everywhere but a clone. Its arguments (--context, --budget, transcript
+# paths) are the meter's, so it bypasses the flag parser below.
+if [ "$CMD" = "cost" ]; then
+  meter="$REPO/session-cost.py"
+  [ -f "$meter" ] || { log "cost: meter missing at $meter"; exit 1; }
+  exec python3 "$meter" "$@" <&3
+fi
 
 WITH=""
 DOMAINS_ARG=""