agent-bios 0.14.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
 #
@@ -95,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
@@ -859,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
@@ -917,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):"
@@ -928,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
@@ -1417,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
@@ -1613,7 +1672,49 @@ shell_shadow_summary() {
   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
@@ -1641,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
 
@@ -1706,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/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}"

package/launch/i18n/ja.toml

@@ -165,6 +165,7 @@
 "panel.domains.label" = "ドメイン"
 "panel.rolled-back" = "(ロールバック済み。最新は {latest})"
 "panel.layers.none" = "なし"
+"panel.unavailable" = "パッケージ導入では取得不可"
 "panel.ledger.value" = "配置 {placed} · インキュベート {incubating} · バージョン {versions}"
 "panel.domains.unset" = "(未選択)"
 "panel.last-apply" = "⚠ 最終適用 {outcome} @ {at} — 要求: {requested}"

package/launch/i18n/ko.toml

@@ -165,6 +165,7 @@
 "panel.domains.label" = "도메인"
 "panel.rolled-back" = "(롤백됨. 최신은 {latest})"
 "panel.layers.none" = "없음"
+"panel.unavailable" = "패키지 설치에서는 확인 불가"
 "panel.ledger.value" = "배치 {placed} · 인큐베이팅 {incubating} · 버전 {versions}"
 "panel.domains.unset" = "(아직 선택 안 함)"
 "panel.last-apply" = "⚠ 마지막 적용 {outcome} @ {at} — 요청: {requested}"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-bios",
-  "version": "0.14.0",
-  "releaseDate": "2026-08-31",
+  "version": "0.15.0",
+  "releaseDate": "2026-09-01",
   "description": "A thin, low-level instruction layer for LLM CLI agents: one set of principles and behavior whichever model you run. Deploys into $HOME by copy via an explicit `agent-bios install`.",
   "bin": {
     "agent-bios": "install.sh"
@@ -29,6 +29,8 @@
     "compose/assemble.py",
     "compose/prune-backups.py",
     "compose/check-domains.py",
+    "compose/corpus-state.py",
+    "compose/write-update-cache.py",
     "compose/canary.sh",
     "launch/check-prompting-targets.sh",
     "learn/check-learning.py",

package/provenance.json

@@ -1 +1 @@
-{"commit":"db5e745b6f832a02b43556889c14ce1396688177","committedAt":"2026-08-31T13:13:32+09:00","dirty":false}
+{"commit":"ff09dd50ec264eee660513f8a6768d3481a4e9c8","committedAt":"2026-09-01T14:37:00+09:00","dirty":false}