agent-bios 0.13.0 → 0.15.0

package/compose/write-update-cache.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Write the update-check cache atomically.
+
+The launcher READS this file on every start and never writes it, so a half-written
+cache is a crash in the TUI rather than a stale badge — hence os.replace over a
+temp file in the same directory, not a plain open-and-write.
+
+`latest` is omitted when the lookup failed; `checked_at` is written regardless, so
+an offline machine records its attempt and waits out the interval instead of
+retrying on every launch. Absence of `latest` therefore means "asked, no answer",
+which the launcher must not render as "up to date".
+"""
+import json
+import os
+import sys
+import tempfile
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 5:
+        print("usage: write-update-cache.py <out> <checked_at> <latest|''> <current>",
+              file=sys.stderr)
+        return 2
+    out, checked_at, latest, current = argv[1], argv[2], argv[3], argv[4]
+    try:
+        checked = int(checked_at)
+    except ValueError:
+        print(f"checked_at is not an integer: {checked_at!r}", file=sys.stderr)
+        return 2
+    payload: dict[str, object] = {"checked_at": checked}
+    if current:
+        payload["current"] = current
+    if latest:
+        payload["latest"] = latest
+    directory = os.path.dirname(out) or "."
+    os.makedirs(directory, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=directory, prefix=".update-check.")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(payload, handle)
+        os.replace(tmp, out)
+    except BaseException:
+        # A temp file left in the state dir would be swept by nothing.
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/install.sh

@@ -13,6 +13,7 @@
 #   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 update --check   cache the registry's latest version for the TUI badge
 #   agent-bios uninstall   remove deployed files and the zsh hook
 #   agent-bios help
 #
@@ -68,6 +69,21 @@ 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'
+# .zshrc is the only file this installer WRITES, but it is not the only file zsh reads, and a
+# user who moves the line to .zshenv (where non-interactive shells see it too) had every
+# question about it answered wrongly: `status` said "zsh hook absent" while the integration was
+# demonstrably running, `uninstall` said there was nothing to remove, and the next `install`
+# appended a second copy to .zshrc. Detection therefore looks everywhere zsh would; ownership
+# stays with .zshrc alone.
+ZSH_HOOK_FILES="${ZDOTDIR:-$HOME}/.zshrc ${ZDOTDIR:-$HOME}/.zshenv ${ZDOTDIR:-$HOME}/.zprofile"
+
+# Echo every startup file that carries the hook line, one per line, or nothing.
+zsh_hook_locations() {
+  local f
+  for f in $ZSH_HOOK_FILES; do
+    if [ -f "$f" ] && grep -qF "$HOOK_MARK" "$f"; then printf '%s\n' "$f"; fi
+  done
+}
 
 DRY_RUN=0
 BACKUP_DIR=""
@@ -80,6 +96,13 @@ CLEANUP_FAILED=0
 # 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
+# Set when the required corpus-status projection could not be written. Deferred rather than
+# returned on the spot: the projection runs AFTER the corpus is deployed, and returning
+# there would fire the EXIT trap and restore the PREVIOUS manifest — leaving the new corpus
+# on disk with the record naming the old one, which is the split state above. The manifest
+# is completed first so it describes what is really there, and the command then exits
+# non-zero. The files, the record, and the exit code then each say something true.
+PROJECTION_FAILED=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
@@ -390,8 +413,11 @@ assemble_corpus() {
 }
 
 add_zsh_hook() {
-  if [ -f "$ZSHRC" ] && grep -qF "$HOOK_MARK" "$ZSHRC"; then
-    info "zsh hook present  $ZSHRC"
+  local found
+  found="$(zsh_hook_locations)"
+  if [ -n "$found" ]; then
+    # Appending beside an existing copy would source the integration twice per shell.
+    info "zsh hook present  $(printf '%s' "$found" | tr '\n' ' ')"
     return
   fi
   if [ "$DRY_RUN" = 1 ]; then info "[dry-run] append zsh hook to $ZSHRC"; return; fi
@@ -689,8 +715,13 @@ PY
 }
 
 remove_zsh_hook() {
+  local other
+  # Named, never edited: a line this installer did not write is the user's, and uninstall
+  # removing it would be editing a file it does not own.
+  other="$(zsh_hook_locations | grep -vF "$ZSHRC" || true)"
+  [ -n "$other" ] && info "zsh hook also in $(printf '%s' "$other" | tr '\n' ' ') — left in place (not written by this installer)"
   if [ ! -f "$ZSHRC" ] || ! grep -qF "$HOOK_MARK" "$ZSHRC"; then
-    info "no zsh hook to remove"
+    info "no zsh hook to remove  $ZSHRC"
     return
   fi
   if [ "$DRY_RUN" = 1 ]; then info "[dry-run] remove zsh hook from $ZSHRC"; return; fi
@@ -836,12 +867,36 @@ cmd_install() {
   # 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.
+  #
+  # The projection is REQUIRED, not best-effort. It used to be neither: stderr and the
+  # exit status were both discarded and every failure printed one guess of a note —
+  # "versions.json/ledger missing?" — which was wrong for the failure that actually
+  # happened. `compose/corpus-state.py` was not in the npm package at all, so a real
+  # npm install rewrote the corpus, updated selection.json and version.json, passed
+  # verification, exited 0, and left corpus-status.json stale from a previous
+  # deployment. The launcher's corpus panel reads that file, so the machine reported a
+  # selection the successful run had not recorded. A command that deploys the launcher
+  # and advertises its panel cannot call that a success.
+  #
+  # The script now ships and degrades honestly in an npm layout (domains real,
+  # version/ledger reported unavailable), so the remaining failures are real ones:
+  # an unwritable destination, an invalid status, a missing interpreter. Those fail
+  # the install, and the reason reaches the operator instead of /dev/null.
   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?)"
+    local projection_log
+    projection_log="$(mktemp -t corpus-projection)"
+    if python3 "$REPO/compose/corpus-state.py" project --repo "$REPO" >"$projection_log" 2>&1; then
+      info "corpus-status projected"
+      rm -f "$projection_log"
+    else
+      log "corpus-status projection FAILED — the launcher's corpus panel would report a"
+      log "selection this run did not record. Its own output:"
+      sed 's/^/    /' "$projection_log"
+      log "    full output: $projection_log"
+      PROJECTION_FAILED=1
+    fi
   fi
   # Deploy/system version marker for the launcher's TUI version line, read from
   # package.json (version + releaseDate) — distinct from the corpus content
@@ -894,7 +949,13 @@ PY
     # 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."
+    # Withheld when the projection failed: the run below reports INSTALL INCOMPLETE and
+    # exits non-zero, and printing "Done." first told the operator both things in the
+    # same breath. The manifest is already complete by here, which is the point — the
+    # files really are deployed; what failed is the record of WHICH selection they are.
+    if [ "$PROJECTION_FAILED" != 1 ]; then
+      log "Done. Open a new shell (or: source \"$ZSHRC\") to activate the zero-arg launcher."
+    fi
     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):"
@@ -905,6 +966,13 @@ PY
     # 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
+    if [ "$PROJECTION_FAILED" = 1 ]; then
+      log ""
+      log "INSTALL INCOMPLETE: the corpus is deployed and the manifest records it, but the"
+      log "corpus-status projection failed above — the launcher's panel would describe a"
+      log "state this run did not record. Fix the cause and re-run: agent-bios install"
+      exit 1
+    fi
   else
     log "VERIFY FAILED after install — see messages above"
     exit 1
@@ -975,6 +1043,13 @@ 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
+  # Evidence, never a verdict: a shadow that was repaired is the mechanism working.
+  shell_shadow_summary
+  # Not `whence -v`: a function redefined at preexec carries no "from FILE" annotation,
+  # so in exactly the shell the reassert repaired, whence reads as "not ours". And not a
+  # substring of the body either — a foreign body can quote it. Byte-equality with the
+  # body the interception captured when it was sourced is the same test the reassert runs.
+  info "live check (run in the terminal you use): [[ \"\$functions[claude]\" == \"\$_agent_launch_body[claude]\" ]] && print OURS   → expect OURS"
   # 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
@@ -1055,7 +1130,19 @@ PY
     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
+  #
+  # Not from inside the install-scenario suite, though. That suite points REPO at its own
+  # checkout and writes only into a sandbox HOME, so the tree this gate would judge is the
+  # very tree the umbrella that launched the suite already judged — and the suite performs
+  # twelve verifies. Measured 2026-08-31: 3m37s each, 43m22s of a 50m26s commit, 86% of it,
+  # for twelve re-derivations of one unchanged answer that no assertion in
+  # gates/test-install-guides.sh reads. The skip announces itself, because a leg that goes
+  # quiet is how a suite reports clean over something it never ran. The payload and
+  # prompting-target gates above are deliberately NOT skipped: at 0.16s together they buy
+  # back no time, and running them keeps proving that verify still wires its gates up.
+  if [ "${AGENT_BIOS_IN_INSTALL_TEST:-0}" = 1 ]; then
+    info "SKIP: repo mirror parity — the umbrella running this suite already judged this tree"
+  elif [ -d "$REPO/ko" ] && [ -x "$REPO/gates/check-parity.sh" ]; then
     # 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-
@@ -1273,6 +1360,9 @@ archive_and_purge() {
     # the file keeps the thing that names it. Everything else goes either way.
     if [ "${UNBACKED:-0}" -eq 0 ]; then
       rm -rf "$STATE_DIR"
+    else
+      # The dir survives for the manifest's sake; the shell-shadow evidence is not that.
+      rm -f "$STATE_DIR/shell-shadow.log"
     fi
     rm -rf "$HOME/.cache/agent-launch" \
            "${AGENT_LAUNCH_VENV:-$HOME/.local/share/agent-launch}"
@@ -1372,8 +1462,22 @@ cmd_onboard() {
     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 SUCCESS record is strict; the two failure records above stay tolerant. The
+  # asymmetry is the point: a swallowed failure-record rides a run that is already
+  # exiting non-zero and reporting why, while a swallowed success-record is how
+  # onboarding prints a completed summary over a status file that never learned the
+  # selection was applied. That is the state this whole change exists to remove, so it
+  # cannot be the one still guarded by `|| true`.
+  record_log="$(mktemp -t corpus-record-apply)"
+  if ! python3 "$REPO/compose/corpus-state.py" record-apply \
+       --requested "$sel" --outcome applied >"$record_log" 2>&1; then
+    log "ONBOARDING INCOMPLETE: the corpus applied, but recording that outcome failed —"
+    log "the corpus panel would not show this selection as applied. Its own output:"
+    sed 's/^/    /' "$record_log"
+    log "    full output: $record_log"
+    exit 1
+  fi
+  rm -f "$record_log"
   # 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
@@ -1528,10 +1632,89 @@ cmd_status() {
            "$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
+  zsh_found="$(zsh_hook_locations)"
+  if [ -z "$zsh_found" ]; then
+    info "zsh hook absent"
+  elif printf '%s\n' "$zsh_found" | grep -qxF "$ZSHRC"; then
+    info "zsh hook present  $(printf '%s' "$zsh_found" | tr '\n' ' ')"
+  else
+    # Present and working, but somewhere this installer will neither update nor remove.
+    info "zsh hook present  $(printf '%s' "$zsh_found" | tr '\n' ' ')  (unmanaged location: not $ZSHRC)"
+  fi
+  shell_shadow_summary
+}
+
+# The interception in launch/agent-launch.zsh reasserts `claude`/`codex` at preexec when a
+# tool redefined them after the rc files (cmux does, on its first precmd) and appends one
+# line per shadowed host per shell to $STATE_DIR/shell-shadow.log. That log is the only
+# evidence of shadowing status/verify can read: a child shell cannot reproduce the
+# terminal's own bootstrap, so a canary run from here would report PASS while the live
+# shell is shadowed — which is why there is none.
+shell_shadow_summary() {
+  local f="$STATE_DIR/shell-shadow.log" n last
+  # A dir that cannot be written records nothing, and "nothing" must not read as "clean" —
+  # so this branch is exclusive: no "no shadowing observed" beside it.
+  if [ -L "$f" ] || { [ -e "$f" ] && [ ! -f "$f" ]; }; then
+    info "shell interception: evidence log is not a regular file ($f) — nothing is recorded there, so absence here is not evidence"
+  elif { [ -d "$STATE_DIR" ] && [ ! -w "$STATE_DIR" ]; } || { [ -e "$f" ] && [ ! -w "$f" ]; }; then
+    info "shell interception: evidence log not writable ($f) — a shadowing cannot be recorded, so absence here is not evidence"
+  elif [ -s "$f" ]; then
+    # One line is one host's FIRST observation in one shell, never a count of repairs: a
+    # tool that redefines on every prompt is repaired on every command and logged once.
+    n=$(wc -l <"$f" | tr -d ' ')
+    # Control bytes are stripped again on display: the log is written by a shell the
+    # user does not fully own, and a terminal-control sequence in a "foreign body" field
+    # could repaint this very line.
+    last=$(tail -n 1 "$f" | tr -d '\000-\010\013-\037\177')
+    info "shell interception: shadowing observed $n time(s) (first observation per host per shell), last $(printf '%s' "$last" | cut -f1) — $(printf '%s' "$last" | cut -f2) was shadowed by: $(printf '%s' "$last" | cut -f4-)"
+  else
+    info "shell interception: no shadowing observed"
+  fi
+}
+
+# The update check is a READ of a public version number: it sends the package name
+# and nothing derived from this machine, which is the same class as provision-venv's
+# PyPI fetch and the onboard model probe — see ENDPOINTS.md "Zero egress by default",
+# whose claim is scoped to DATA egress. It delegates to `npm view` rather than naming
+# a registry, so a private registry, a proxy, and the user's auth all keep working and
+# no shipped file carries a URL (gates/check-endpoints.py forbids that outright).
+#
+# `checked_at` is written even when the lookup FAILS. An offline machine that recorded
+# nothing would retry on every launch, which is the opposite of once a day.
+refresh_update_cache() {
+  if [ "${AGENT_BIOS_UPDATE_CHECK:-1}" = "0" ]; then
+    log "update check disabled (AGENT_BIOS_UPDATE_CHECK=0)"
+    return 0
+  fi
+  local name latest now out
+  name="$(json_field "$REPO/package.json" name)" || return 1
+  [ -n "$name" ] || return 1
+  now="$(date +%s)"
+  latest=""
+  if command -v npm >/dev/null 2>&1; then
+    # `|| latest=""` is not defensive noise: this file runs under `set -euo pipefail`,
+    # so an npm that exits non-zero (offline, firewalled, private registry down) makes
+    # the PIPELINE fail and `set -e` abort the function before it can record the
+    # attempt — turning every offline launch into a retry and `update --check` into
+    # exit 1. Caught by I16's failing-registry stub, not by review.
+    latest="$(npm view "$name" version 2>/dev/null | tr -d '[:space:]')" || latest=""
+  fi
+  mkdir -p "$STATE_DIR" || return 1
+  out="$STATE_DIR/update-check.json"
+  # Atomic: a half-written cache read by the launcher is a crash in the TUI.
+  python3 "$REPO/compose/write-update-cache.py" "$out" "$now" "$latest" "$(source_version)" || return 1
+  if [ -n "$latest" ]; then
+    log "update check: latest $latest (installed $(source_version))"
+  else
+    log "update check: could not reach the registry; recorded the attempt"
+  fi
 }
 
 cmd_update() {
+  if [ "${UPDATE_CHECK_ONLY:-0}" = 1 ]; then
+    refresh_update_cache
+    return $?
+  fi
   if [ -e "$REPO/.git" ]; then
     log "Updating from git..."
     run git -C "$REPO" pull --ff-only
@@ -1559,6 +1742,9 @@ agent-bios — deploy the Claude/Codex instruction SSOT into $HOME (by copy).
   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 update --check   ask the registry for the latest version and cache it
+                      for the launcher's badge; sends the package name and nothing
+                      else, runs at most daily, AGENT_BIOS_UPDATE_CHECK=0 disables it
   agent-bios uninstall   remove deployed files and the zsh hook
   agent-bios help
 
@@ -1624,6 +1810,7 @@ DOMAINS_SET=0
 while [ $# -gt 0 ]; do
   case "$1" in
     --dry-run) DRY_RUN=1 ;;
+    --check) UPDATE_CHECK_ONLY=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; } ;;

package/launch/agent-launch.py

@@ -16,6 +16,7 @@ import string
 import subprocess
 import sys
 import tempfile
+import time
 import unicodedata
 import textwrap
 import tomllib
@@ -7622,6 +7623,94 @@ VERSION_INFO_PATH = pathlib.Path(
     )
 )
 
+UPDATE_CHECK_PATH = pathlib.Path(
+    os.environ.get(
+        "AGENT_BIOS_UPDATE_CHECK_STATE",
+        str(pathlib.Path.home() / ".local/share/agent-bios/update-check.json"),
+    )
+)
+
+# Once a day. The launcher never performs the lookup itself — it reads this cache and
+# at most SPAWNS the installer, detached, to refresh it. Two reasons, both load-bearing:
+# `npm view` routinely takes seconds and a launcher that blocks on the network is worse
+# than one that shows a stale badge, and the network operation belongs to the component
+# that already owns fetch-corpus (ENDPOINTS.md) rather than to the UI.
+UPDATE_CHECK_INTERVAL_S = 24 * 60 * 60
+
+
+def _version_tuple(text: str) -> tuple[int, ...] | None:
+    """Numeric release prefix, or None when it is not one.
+
+    Deliberately refuses anything it does not fully understand rather than guessing:
+    a prerelease like 1.2.3-rc1 returns None, so it is never compared and never
+    announced. Announcing an upgrade to a version the user cannot get is worse than
+    announcing nothing."""
+    parts = text.strip().split(".")
+    if not (2 <= len(parts) <= 4):
+        return None
+    out = []
+    for part in parts:
+        if not part.isdigit():
+            return None
+        out.append(int(part))
+    return tuple(out)
+
+
+def read_update_cache() -> dict | None:
+    try:
+        data = json.loads(UPDATE_CHECK_PATH.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def update_available(deployed: str | None, cache: dict | None) -> str | None:
+    """The version to announce, or None.
+
+    None whenever anything is unknown — no cache, a cache whose lookup failed (it
+    carries checked_at but no latest), an unparseable version on either side, or a
+    latest that is not strictly greater. `latest` missing means "asked, no answer",
+    which must not read as "up to date"; it simply says nothing."""
+    if not deployed or not cache:
+        return None
+    latest = cache.get("latest")
+    if not isinstance(latest, str):
+        return None
+    here, there = _version_tuple(deployed), _version_tuple(latest)
+    if here is None or there is None:
+        return None
+    return latest if there > here else None
+
+
+def update_check_due(cache: dict | None, now: float) -> bool:
+    if os.environ.get("AGENT_BIOS_UPDATE_CHECK") == "0":
+        return False
+    if cache is None:
+        return True
+    checked = cache.get("checked_at")
+    if not isinstance(checked, (int, float)):
+        return True
+    return (now - checked) >= UPDATE_CHECK_INTERVAL_S
+
+
+def spawn_update_check() -> None:
+    """Fire and forget. Every failure here is silent BY DESIGN — a background
+    refresh that reported its own problems would interrupt a launch to say something
+    the user did not ask for and cannot act on."""
+    installer = shutil.which("agent-bios")
+    if not installer:
+        return
+    try:
+        subprocess.Popen(
+            [installer, "update", "--check"],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,
+        )
+    except OSError:
+        pass
+
 
 def load_corpus_status() -> dict[str, Any] | None:
     """The corpus status projection, or None when the file is unreadable or is not
@@ -7653,7 +7742,12 @@ def version_label() -> str | None:
     if not version:
         return None
     released = info.get("releaseDate")
-    return f"agent-bios v{version} · {released}" if released else f"agent-bios v{version}"
+    label = f"agent-bios v{version} · {released}" if released else f"agent-bios v{version}"
+    cache = read_update_cache()
+    if update_check_due(cache, time.time()):
+        spawn_update_check()
+    newer = update_available(version, cache)
+    return f"{label} · update v{newer} available" if newer else label
 
 
 def display_width(text: str) -> int:
@@ -7723,21 +7817,33 @@ def _corpus_summary_lines(status: dict[str, Any] | None) -> list[str]:
     def row(label: str, value: str) -> str:
         return label + " " * max(1, column - display_width(label)) + value
 
+    # `versions is None` is the projection saying "this install cannot know" — a packaged
+    # install has no author version/ledger registry (compose/corpus-state.py). It is not
+    # `[]`, which would mean a checkout whose registry is genuinely empty, and it must not
+    # render as `0 placed · 0 versions`: a fabricated zero is worse than a blank, because
+    # a reader cannot tell it from a real count. The domain rows below stay real, which is
+    # the whole point of degrading rather than withholding the projection.
+    unavailable = status.get("versions") is None
+    summary = status.get("summary") or {}
     current = status.get("current_version", "?")
     latest = status.get("latest_version", "?")
-    head = row(labels[0], str(current))
+    # `str(current)` printed the literal "None" on a checkout whose registry exists but
+    # holds no version — pre-existing, and visible the moment the row above it learned to
+    # say "unavailable". A known absence reads as none; an unknown one says so.
+    head = row(labels[0], t("panel.unavailable") if unavailable
+               else str(current) if current else t("panel.layers.none"))
     if status.get("rolled_back_to"):
         head += "  " + t("panel.rolled-back").format(latest=latest)
-    layers = status.get("summary", {}).get("placed_by_layer", {})
+    layers = summary.get("placed_by_layer", {})
     order = ("global", "guide", "hook", "enforcement", "gate")
     layer_text = " · ".join(
         f"{name} {layers[name]}" for name in order if layers.get(name)
     ) or t("panel.layers.none")
-    by_status = status.get("summary", {}).get("by_status", {})
+    by_status = summary.get("by_status", {})
     lines = [
         head,
-        row(labels[1], layer_text),
-        row(labels[2], t("panel.ledger.value").format(
+        row(labels[1], t("panel.unavailable") if unavailable else layer_text),
+        row(labels[2], t("panel.unavailable") if unavailable else t("panel.ledger.value").format(
             placed=by_status.get("placed", 0),
             incubating=by_status.get("incubating", 0) + by_status.get("incubating-G", 0),
             versions=len(status_list(status.get("versions"))),

package/launch/agent-launch.zsh

@@ -1,3 +1,10 @@
+# Alias expansion is OFF while this file is parsed and restored to what it was at the
+# end: zsh expands aliases at parse time, inside function bodies too, so an alias named
+# `builtin`, `command`, or `claude` that exists when this file is sourced would be baked
+# into the functions below and the real binary never reached.
+[[ -o aliases ]] && _agent_launch_aliases_were=1 || _agent_launch_aliases_were=0
+setopt no_aliases
+
 # Interactive zero-argument entrypoints use agent-launch. Every argument-bearing
 # or non-TTY call skips profile projection; Claude retains its direct-path
 # permission-bypass default.
@@ -31,13 +38,109 @@ _agent_launch_dispatch() {
   fi
 }
 
-unalias codex 2>/dev/null
-unalias claude 2>/dev/null
+# The entrypoints are (re)defined from one place so the reassert below installs the
+# same thing the initial source did. The top-level unalias stays: zsh expands aliases
+# while PARSING the function below, so an alias named `claude` that exists when this
+# file is sourced would turn its `claude() {` into a parse error and leave the alias in
+# control. The inner unalias handles an alias that arrives later, at reassert time.
+# `no_err_return`: a missing alias makes `unalias` return 1, and under ERR_RETURN that
+# would end the function before either entrypoint is defined.
+unalias codex 2>/dev/null || :
+unalias claude 2>/dev/null || :
+_agent_launch_define() {
+  setopt localoptions no_err_return no_err_exit
+  unalias codex 2>/dev/null
+  unalias claude 2>/dev/null
+  codex() { _agent_launch_dispatch codex "$@"; }
+  claude() { _agent_launch_dispatch claude "$@"; }
+  return 0
+}
+_agent_launch_define
+
+# Reassert the entrypoints right before each command runs. "Last definer wins" is
+# the shell's rule, and a terminal or tool that defines `claude` after the rc files
+# (cmux does, on its first precmd — deliberately, "in case user startup replaced
+# them") would otherwise win in silence: bare `claude` skips the preflight while
+# `codex` keeps working. preexec runs after every precmd, whatever the registration
+# order, so for a prompt-hook shadower the check is the last word at the only moment
+# that matters. Two things it does not do, on purpose: it does not fight a hook that
+# runs after it in preexec (that tool wins; the shadow log names it), and it cannot
+# repair the command already parsed when the shadow is an alias — aliases expand at
+# parse time, so an alias shadow is repaired from the next command on. The downstream
+# stays `builtin command <host>`, so a tool that also owns a PATH shim (cmux) keeps its
+# own injection.
+#
+# Ownership is byte-equality with the body captured at source time, never a marker
+# string: a foreign function that quotes the marker would otherwise pass as ours.
+zmodload -i zsh/parameter 2>/dev/null
+typeset -gA _agent_launch_body _agent_launch_shadow_noted
+_agent_launch_body[claude]="${functions[claude]}"
+_agent_launch_body[codex]="${functions[codex]}"
 
-codex() {
-  _agent_launch_dispatch codex "$@"
+# Evidence, not repair: one line per host per shell, into the state dir agent-bios
+# already owns — what `agent-bios status`/`verify` read. Never creates the dir (no
+# install, no log). The "noted" flag is set only after the append succeeded, so a
+# directory that cannot be written is retried on the next command instead of being
+# recorded as "no shadowing observed". Tabs and newlines are stripped from every field
+# so a hostile TERM_PROGRAM or function body cannot forge a second row.
+_agent_launch_note_shadow() {
+  setopt localoptions extendedglob noksharrays no_err_return no_err_exit
+  local host="$1" foreign="$2" state="$HOME/.local/share/agent-bios" first prog stamp
+  [[ -n "${_agent_launch_shadow_noted[$host]-}" || ! -d "$state" ]] && return 0
+  # Only a regular, non-symlinked file is evidence: a log pointing at /dev/null would
+  # take the write, set the flag, and keep nothing.
+  [[ -e "$state/shell-shadow.log" && ( -L "$state/shell-shadow.log" || ! -f "$state/shell-shadow.log" ) ]] && return 0
+  first="${foreign%%$'\n'*}"
+  first="${first##[[:space:]]#}"
+  first="${first//[[:cntrl:]]/ }"
+  prog="${TERM_PROGRAM:-unknown}"
+  prog="${prog//[[:cntrl:]]/ }"
+  # `builtin command`: a shell function named `date` must not write this field.
+  stamp="$(builtin command date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null)"
+  stamp="${stamp//[[:cntrl:]]/ }"
+  # `builtin printf`: a shell function named printf could report success and write nothing.
+  if builtin printf '%s\t%s\t%s\t%s\n' "${stamp:-<unknown>}" "$host" "$prog" \
+       "${first:-<undefined>}" >> "$state/shell-shadow.log" 2>/dev/null; then
+    _agent_launch_shadow_noted[$host]=1
+  fi
+  return 0
 }
 
-claude() {
-  _agent_launch_dispatch claude "$@"
+_agent_launch_reassert() {
+  setopt localoptions noksharrays no_err_return no_err_exit
+  local host foreign entry
+  local -a shadowed
+  for host in claude codex; do
+    foreign=""
+    # Existence, not non-emptiness: `alias claude=''` is a shadow that erases the command
+    # word. Global aliases live in $galiases, not $aliases; `unalias` removes either.
+    if (( ${+aliases[$host]} )); then
+      foreign="alias $host=${aliases[$host]}"
+    elif (( ${+galiases[$host]} )); then
+      foreign="alias -g $host=${galiases[$host]}"
+    elif [[ "${functions[$host]-}" != "${_agent_launch_body[$host]}" ]]; then
+      foreign="${functions[$host]-<undefined>}"
+    fi
+    [[ -n "$foreign" ]] && shadowed+=("${host}"$'\t'"${foreign}")
+  done
+  (( $#shadowed )) || return 0
+  # Repair first, then record: a failure to write evidence must never leave the
+  # foreign definition in place for the command about to run.
+  _agent_launch_define
+  for entry in "${shadowed[@]}"; do
+    _agent_launch_note_shadow "${entry%%$'\t'*}" "${entry#*$'\t'}"
+  done
+  return 0
 }
+# Registered on precmd as well: a tool that redefines the names in a preexec that runs
+# after ours wins for that command, but its definition is still in place when the next
+# prompt is drawn — precmd is where that shadow is observed and logged, so "recorded, not
+# fought" holds for the case the preexec pass cannot see.
+autoload -Uz add-zsh-hook
+add-zsh-hook -d preexec _agent_launch_reassert 2>/dev/null
+add-zsh-hook -d precmd _agent_launch_reassert 2>/dev/null
+add-zsh-hook preexec _agent_launch_reassert
+add-zsh-hook precmd _agent_launch_reassert
+
+(( _agent_launch_aliases_were )) && setopt aliases
+unset _agent_launch_aliases_were

package/launch/i18n/en.toml

@@ -169,6 +169,7 @@
 "panel.domains.label" = "Domains"
 "panel.rolled-back" = "(ROLLED BACK; latest is {latest})"
 "panel.layers.none" = "none"
+"panel.unavailable" = "unavailable in a packaged install"
 "panel.ledger.value" = "placed {placed} · incubating {incubating} · versions {versions}"
 "panel.domains.unset" = "(none selected yet)"
 "panel.last-apply" = "⚠ LAST APPLY {outcome} at {at} — requested: {requested}"