agent-bios 0.18.0 → 0.19.0

package/install.sh

@@ -1,32 +1,19 @@
 #!/usr/bin/env bash
 # agent-bios installer.
 #
-# Deploys the single-source-of-truth (globals, scoped guides, Codex agent
-# templates, Codex wrappers, the launch profile/shell/bin, a managed Textual
-# venv, and the zsh hook) into $HOME by COPY — idempotent, backed up before
-# overwrite, and reversible. Distributed as an npm bin; the actual $HOME
-# deployment is this explicit command (never a postinstall side effect).
+# Stores the corpus and runtime privately for explicitly activated sessions.
+# Native global instructions and host discovery paths remain user-owned.
+# AGENT_BIOS_LEGACY_INSTALL=1 selects the compatibility deployer.
 #
-# Usage:
-#   agent-bios install     deploy into this environment (backs up + verifies)
-#   agent-bios verify      check the deployed state matches the source
-#   agent-bios status      show what is installed and where
-#   agent-bios 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
-#
-# Flags: --dry-run (print actions, change nothing).
-# Env overrides: CLAUDE_CONFIG_DIR, CODEX_HOME, AGENT_LAUNCH_VENV, ZDOTDIR.
+# Usage: agent-bios help
+# Private roots: AGENT_BIOS_STATE_DIR, AGENT_BIOS_CORPUS_DIR.
+# Host/runtime overrides: CLAUDE_CONFIG_DIR, CODEX_HOME, AGENT_LAUNCH_VENV, ZDOTDIR.
 set -euo pipefail
 
-# This installer is non-interactive: every input arrives as a subcommand, flag,
-# or env var. Detach stdin so no child (the codex-helm dry-run, pip, git) can
-# block forever on an inherited idle stdin — that is what hangs an install under
-# CI, pipes, and background runs, where stdin stays open but never delivers.
-# `learn` is the one subcommand whose payload IS stdin, so keep the caller's on
-# fd 3 first and hand it back only there; every other path still sees /dev/null.
+# Preserve caller input for explicit interactive setup and payload commands;
+# dependency and compatibility child processes receive /dev/null by default.
+# Preserve caller input on fd 3 for payload-bearing subcommands (learn, corpus,
+# understand, and cost); other child processes see /dev/null.
 # The braces matter. `exec` with redirections and no command applies them to the
 # SHELL, permanently — so the bare `exec 3<&0 2>/dev/null` this used to be sent
 # every later error message on this script's stderr to /dev/null: bash's own
@@ -1745,7 +1732,7 @@ cmd_update() {
     if [ "${AGENT_BIOS_LEGACY_INSTALL:-0}" = 1 ]; then
       cmd_install
     else
-      python3 "$REPO/compose/corpus_install.py" --repo "$REPO" install
+      python3 "$REPO/compose/corpus_install.py" --repo "$REPO" install --non-interactive
     fi
   else
     log "Installed as an npm package. Update with:"
@@ -1760,9 +1747,22 @@ usage() {
   cat <<'EOF'
 agent-bios — manage private corpus content for explicitly activated sessions.
 
-  agent-bios install     store a private runtime and corpus baseline
+  agent-bios install                 open the Textual installation wizard
+  agent-bios install --non-interactive --corpus none   store runtime with no active corpus
+  agent-bios install --corpus selected --select @scope/package   select only that corpus
   agent-bios onboard     select domains for future activated sessions
+  agent-bios setup start             report setup languages, execution target, and conversation guide
+  agent-bios setup inspect --language ko   inspect dependencies and corpus choices as JSON
+  agent-bios setup discover --project-root /path/to/project   list eligible instruction sources
+  agent-bios setup plan --language ko --input request.json    preview selected setup effects as JSON
+  agent-bios setup apply --input review.json --review-id ID --yes   apply the accepted review
+  agent-bios setup status --review-id ID    inspect a recorded setup outcome
+  agent-bios setup resume --review-id ID    re-probe and prepare a fresh review without applying
   agent-bios corpus      open Corpus Studio; list/show/plan/apply also work non-TTY
+  agent-bios import      discover/capture/review local instructions; --help lists source-preserving steps
+  agent-bios app         register an explicit Codex app bridge or manage per-task corpus input
+  agent-bios app session use   return selected corpus as context for this Codex app task
+  agent-bios app session off   stop future delivery; earlier context requires a new task to exclude
   agent-bios understand  list corpus learning bundles; --help shows session/discovery commands
   agent-bios shell       show the optional zsh connection status
   agent-bios shell restore   make bare claude/codex open the launcher TUI
@@ -1795,18 +1795,21 @@ AGENTS.md/CLAUDE.md. Restore/remove it from the TUI's Shell connection menu or
 the commands above. After restoring, open a new terminal or reload .zshrc.
 
 Flags: --dry-run       print actions without changing anything
-       --domains a,b  assemble ONLY the named domain packages (plus core+infra);
-                      with onboard, 'none' means core+infra only. The selection
-                      persists in the state dir and later installs/updates reuse
-                      it. Default (no flag, no saved selection) selects every
-                      domain — one install shape, "full" is just everything
-                      selected.
-       --with a,b     also install the named optional dependencies (install only).
-                      Without it, install offers each missing one when the terminal
-                      is interactive, and otherwise just prints its install line.
-                      Missing ones are not fatal — they only degrade the review
-                      routes that need them.
-Env:   CLAUDE_CONFIG_DIR, CODEX_HOME, AGENT_LAUNCH_VENV, ZDOTDIR
+       --interactive open the Textual installation wizard (default)
+       --non-interactive opt out of the wizard and return JSON; required without a terminal
+       --corpus / --select seed wizard choices; --dry-run previews without Apply
+       --corpus none  deliver no corpus, including core and management bootstrap
+       --corpus all   select all corpus; --corpus selected uses repeated --select targets
+                      Library assets remain in the private runtime; these choices govern delivery.
+       --domains a,b  select named domains for future activated snapshots, plus
+                      implicit core+infra; '--domains none' keeps that core-only meaning. Saved selections
+                      survive installs/updates. Without a saved selection or flag,
+                      installation selects every domain.
+       --with a,b     optional dependency installation in explicit legacy mode only;
+                      private installation rejects this option.
+Env:   AGENT_BIOS_STATE_DIR, AGENT_BIOS_CORPUS_DIR (private runtime and user roots)
+       CLAUDE_CONFIG_DIR, CODEX_HOME (native host configuration)
+       AGENT_LAUNCH_VENV, ZDOTDIR
 EOF
   # DERIVED, not typed: the hardcoded pair went stale the moment a capability was renamed,
   # and the name it still advertised selected a different capability than the one that
@@ -1814,11 +1817,10 @@ EOF
   local known; known=$(capability_table 2>/dev/null | cut -f1 | tr '\n' ' ')
   [ -n "$known" ] && printf '       --with names: %s\n' "${known% }"
 
-  # Recovery exists in both modes at different granularity, and naming the wrong one is worse
-  # than naming none: a clone can roll the corpus back to a registered mining window, while an
-  # npm install has no git history to read and rolls the whole package back by version instead.
-  # Derived from which install this is, for the same reason --with names is.
-  if [ -e "$REPO/.git" ]; then
+  if [ "${AGENT_BIOS_LEGACY_INSTALL:-0}" != 1 ]; then
+    printf '\nRecover: agent-bios corpus history --json; submit an operation=rollback request\n'
+    printf '         through agent-bios corpus plan/apply for a baseline_ref or history_id.\n'
+  elif [ -e "$REPO/.git" ]; then
     printf '\nRecover: python3 %s/compose/corpus-state.py list, then rollback --version V\n' "$REPO"
   else
     printf '\nRecover: npm install -g agent-bios@<older-version> && agent-bios install\n'
@@ -1829,9 +1831,9 @@ EOF
 CMD="${1:-help}"
 if [ $# -gt 0 ]; then shift; fi
 
-# Private installation is the new user path. The explicit legacy flag exists only
-# while maintained install fixtures and pre-migration environments exercise the old
-# writer. No private operation falls through to a global writer.
+# Private installation is the default path. The explicit legacy flag selects
+# compatibility installation and its regression fixtures. No private operation
+# falls through to a global writer.
 if [ "$CMD" = "corpus" ]; then
   exec python3 "$REPO/compose/corpus.py" --repo "$REPO" "$@" <&3
 fi
@@ -1841,9 +1843,28 @@ fi
 if [ "$CMD" = "understand" ]; then
   exec python3 "$REPO/compose/corpus_understand.py" --repo "$REPO" "$@" <&3
 fi
+if [ "$CMD" = "app" ]; then
+  exec python3 "$REPO/compose/corpus_app.py" --repo "$REPO" "$@" <&3
+fi
+if [ "$CMD" = "import" ]; then
+  exec python3 "$REPO/compose/corpus_import.py" --repo "$REPO" "$@" <&3
+fi
+if [ "$CMD" = "setup" ]; then
+  if ! command -v python3 >/dev/null 2>&1 || ! python3 -c 'import sys; sys.exit(sys.version_info < (3, 11))' </dev/null; then
+    log "Python 3.11 or newer is required for conversation setup."
+    log "Install Python with your operating system package manager, then rerun this command."
+    exit 1
+  fi
+  exec python3 "$REPO/compose/corpus_setup_cli.py" --repo "$REPO" "$@" <&3
+fi
 if [ "${AGENT_BIOS_LEGACY_INSTALL:-0}" != 1 ]; then
   case "$CMD" in
     install|onboard|verify|status|uninstall|migrate|reset)
+      if ! command -v python3 >/dev/null 2>&1 || ! python3 -c 'import sys; sys.exit(sys.version_info < (3, 11))' </dev/null; then
+        log "Python 3.11 or newer is required for the installer and dependency chooser."
+        log "Install Python with your operating system package manager, then rerun this command."
+        exit 1
+      fi
       exec python3 "$REPO/compose/corpus_install.py" --repo "$REPO" "$CMD" "$@" <&3
       ;;
   esac
@@ -1857,7 +1878,15 @@ fi
 if [ "$CMD" = "learn" ]; then
   collector="$REPO/learn/collect-learning.py"
   [ -f "$collector" ] || { log "learn: collector missing at $collector"; exit 1; }
-  exec python3 "$collector" "$@" <&3
+  learning_python="python3"
+  if ! python3 -c 'from jsonschema import Draft202012Validator' </dev/null >/dev/null 2>&1; then
+    learning_python="${AGENT_LAUNCH_VENV:-$HOME/.local/share/agent-launch/venv}/bin/python"
+    if [ ! -x "$learning_python" ] || ! "$learning_python" -c 'from jsonschema import Draft202012Validator' </dev/null >/dev/null 2>&1; then
+      log "learn: JSON Schema support is missing; select jsonschema in agent-bios install --interactive."
+      exit 1
+    fi
+  fi
+  exec "$learning_python" "$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

package/launch/agent-launch.py

@@ -1421,6 +1421,18 @@ def parse_capability_offers(name: str, raw: Any) -> tuple:
     return tuple(parsed)
 
 
+def review_wrapper_command(host: str, name: str) -> str | None:
+    """Resolve a review adapter from the active private package or native installation."""
+    if private_corpus_enabled():
+        path = corpus_package_root() / "wrappers" / f"{name}.sh"
+    elif host == "codex":
+        path = expand_config_path(f"${{CODEX_HOME}}/bin/{name}")
+    else:
+        home = os.environ.get("CLAUDE_CONFIG_DIR") or str(pathlib.Path.home() / ".claude")
+        path = pathlib.Path(home) / "bin" / name
+    return str(path.absolute()) if path.is_file() and os.access(path, os.X_OK) else None
+
+
 def host_dispatch_command(host: str, config: dict[str, Any]) -> str | None:
     """The absolute command that spawns a fresh, exactly-pinned, read-only session on
     `host`, or None when this machine cannot.
@@ -1430,23 +1442,12 @@ def host_dispatch_command(host: str, config: dict[str, Any]) -> str | None:
     named the reviewer's seat but never said how to reach it — the launched agent was
     told to run isolated passes on a model with no way to spawn them."""
     if host == "codex":
-        path = expand_config_path("${CODEX_HOME}/bin/codex-run")
-        return str(path.absolute()) if path.is_file() and os.access(path, os.X_OK) else None
+        return review_wrapper_command("codex", "codex-run")
     if host == "claude":
-        # The twin of the branch above, and the asymmetry it removes was silent: the
-        # codex host dispatched through our adapter while the claude host dispatched the
-        # bare binary, so half of every cross-family review had nowhere to report from.
-        #
-        # Falls THROUGH rather than returning None when the adapter is absent, which is
-        # the difference from codex: there, codex-run is the only route that can pin a
-        # seat, so its absence really is no route. Here the bare binary is a working
-        # dispatch that simply cannot produce a receipt, and taking the panel away from
-        # a machine that has not deployed the adapter yet would be a worse trade than
-        # the missing evidence. An un-updated install keeps exactly today's behaviour.
-        home = os.environ.get("CLAUDE_CONFIG_DIR") or str(pathlib.Path.home() / ".claude")
-        adapter = pathlib.Path(home) / "bin" / "claude-run"
-        if adapter.is_file() and os.access(adapter, os.X_OK):
-            return str(adapter.absolute())
+        # The bare Claude backend remains a usable fallback without adapter receipts.
+        adapter = review_wrapper_command("claude", "claude-run")
+        if adapter is not None:
+            return adapter
     backend = config.get("backends", {}).get(host, {})
     try:
         return resolve_command(backend.get("command", ""))
@@ -4116,7 +4117,12 @@ def expand_config_path(value: str) -> pathlib.Path:
     return pathlib.Path(os.path.expandvars(os.path.expanduser(expanded)))
 
 
+_UI_RUNTIME_RELEASE: Callable[[], None] | None = None
+
+
 def exec_backend(command: str, args: list[str], env: dict[str, str] | None = None) -> NoReturn:
+    if _UI_RUNTIME_RELEASE is not None:
+        _UI_RUNTIME_RELEASE()
     os.execve(command, [command, *args], os.environ.copy() if env is None else env)
 
 
@@ -4564,11 +4570,9 @@ def _resolves(value: str) -> bool:
 
 def cross_native_command(plan: dict[str, Any]) -> str | None:
     """Absolute command a cross-family main dispatches to for native review, or
-    None if unresolvable. The codex reviewer wrapper lives off PATH under
-    CODEX_HOME/bin; the claude reviewer is the claude backend on PATH."""
+    None if unresolvable. Codex uses the active review adapter; Claude uses its backend."""
     if plan["review_host"] == "codex":
-        path = expand_config_path("${CODEX_HOME}/bin/codex-run")
-        return str(path.absolute()) if path.is_file() and os.access(path, os.X_OK) else None
+        return review_wrapper_command("codex", "codex-run")
     try:
         return resolve_command(plan["review_backend"])
     except LaunchError:
@@ -4576,11 +4580,10 @@ def cross_native_command(plan: dict[str, Any]) -> str | None:
 
 
 def cross_helm_command(plan: dict[str, Any]) -> str | None:
-    """The codex fan-out reviewer wrapper (hybrid), off PATH under CODEX_HOME/bin."""
+    """The Codex fan-out reviewer adapter from the active installation."""
     if plan["review_host"] != "codex":
         return None
-    path = expand_config_path("${CODEX_HOME}/bin/codex-helm")
-    return str(path) if path.is_file() and os.access(path, os.X_OK) else None
+    return review_wrapper_command("codex", "codex-helm")
 
 
 def cross_ultracode_command(plan: dict[str, Any]) -> str | None:
@@ -4857,11 +4860,54 @@ def setup_summary_lines(plan: dict[str, Any] | None) -> list[str]:
     return lines
 
 
+def _activate_cli_ui_runtime() -> bool:
+    """Use the package's offline UI bundle; standalone compatibility copies keep their runtime."""
+    global _UI_RUNTIME_RELEASE
+    source = pathlib.Path(__file__).resolve().parents[1]
+    if os.environ.get("AGENT_BIOS_PACKAGE_ROOT") or private_corpus_enabled():
+        root = corpus_package_root()
+    elif (source / "compose/corpus_store.py").is_file():
+        root = source
+    else:
+        return False
+    loader = root / "compose/corpus_ui_runtime.py"
+    if loader.is_symlink() or not loader.is_file():
+        raise LaunchError("bundled UI runtime loader is missing or unsafe; reinstall the agent-bios package")
+    module_root = str(root / "compose")
+    if module_root not in sys.path:
+        sys.path.insert(0, module_root)
+    try:
+        from corpus_ui_runtime import activate_ui_runtime, release_ui_runtime
+        activate_ui_runtime(root)
+    except (ImportError, OSError, RuntimeError) as exc:
+        raise LaunchError(f"bundled terminal UI could not start: {exc}") from exc
+    _UI_RUNTIME_RELEASE = release_ui_runtime
+    return True
+
+
+def _textual_api() -> tuple[Any, ...]:
+    """Import the public UI APIs used by this launcher without starting an app."""
+    from textual import work
+    from textual.app import App
+    from textual.binding import Binding
+    from textual.containers import Horizontal, Vertical, VerticalScroll
+    from textual.screen import ModalScreen
+    from textual.widgets import Input, OptionList, Static
+    from textual.widgets.option_list import Option
+    from rich.text import Text
+    from textual.theme import Theme
+    return (work, App, Binding, Horizontal, Vertical, VerticalScroll, ModalScreen,
+            Input, OptionList, Static, Option, Text, Theme)
+
+
 def textual_importable() -> bool:
     try:
-        import textual  # noqa: F401
-    except Exception:
-        return False
+        _textual_api()
+    except ImportError as exc:
+        if any(exc.name == name or (exc.name or "").startswith(name + ".")
+               for name in ("textual", "rich")):
+            return False
+        raise
     return True
 
 
@@ -4926,15 +4972,8 @@ _UI_CANCEL = "\x00cancel"
 def _build_app_class():
     """Import textual lazily and build the App/Screen classes, so importing this
     module and every non-interactive path stays free of the textual dependency."""
-    from textual import work
-    from textual.app import App
-    from textual.binding import Binding
-    from textual.containers import Horizontal, Vertical, VerticalScroll
-    from textual.screen import ModalScreen
-    from textual.widgets import Input, OptionList, Static
-    from textual.widgets.option_list import Option
-    from rich.text import Text
-    from textual.theme import Theme
+    (work, App, Binding, Horizontal, Vertical, VerticalScroll, ModalScreen,
+     Input, OptionList, Static, Option, Text, Theme) = _textual_api()
 
     # Host-matched palettes so the preflight reads as the CLI it launches.
     # Both are taken from the host's own artifact: Codex from its ~/.codex dark
@@ -8913,9 +8952,10 @@ def run_corpus_apply(selection: list[str]) -> None:
     this function only streams it and reports the exit."""
     status = load_corpus_status() or {}
     domains = ",".join(selection) if selection else "none"
+    interaction = [] if os.environ.get("AGENT_BIOS_LEGACY_INSTALL") == "1" else ["--non-interactive"]
     front = shutil.which("agent-bios")
     if front:
-        argv = [front, "onboard", "--domains", domains]
+        argv = [front, "onboard", *interaction, "--domains", domains]
     else:
         # isinstance, not truthiness: `repo` is whatever the JSON holds, and a non-string
         # truthy value reached pathlib.Path() and raised TypeError out of the apply path.
@@ -8928,11 +8968,11 @@ def run_corpus_apply(selection: list[str]) -> None:
         if installer is None or not installer.is_file():
             print(
                 "agent-launch: no agent-bios on PATH and no usable repo in "
-                f"corpus-status.json; run manually: agent-bios onboard --domains {domains}",
+                f"corpus-status.json; run manually: agent-bios onboard {' '.join(interaction)} --domains {domains}",
                 file=sys.stderr,
             )
             return
-        argv = ["bash", str(installer), "onboard", "--domains", domains]
+        argv = ["bash", str(installer), "onboard", *interaction, "--domains", domains]
     print(f"\nagent-launch: applying corpus selection: {' '.join(argv)}\n", flush=True)
     proc = subprocess.run(argv)
     if proc.returncode != 0:
@@ -11008,7 +11048,7 @@ def _tolerate_narrow_stdout() -> None:
             pass
 
 
-def main(argv: list[str]) -> int:
+def main(argv: list[str], *, bundled_ui: bool = False) -> int:
     _tolerate_narrow_stdout()
     args = parse_args(drop_check_adapter_separator(argv))
     if args.corpus:
@@ -11142,14 +11182,18 @@ def main(argv: list[str]) -> int:
         and not rich_ui_declined
         and os.environ.get("TERM", "") not in {"", "dumb"}
     )
-    if use_textual and not textual_importable():
-        maybe_reexec_into_venv()
+    if use_textual:
+        bundled = bundled_ui and _activate_cli_ui_runtime()
         if not textual_importable():
-            use_textual = False
-            print(
-                "agent-launch: rich terminal UI unavailable; using numbered prompts.",
-                file=sys.stderr,
-            )
+            if bundled:
+                raise LaunchError("bundled UI APIs are unavailable; reinstall the agent-bios package")
+            maybe_reexec_into_venv()
+            if not textual_importable():
+                use_textual = False
+                print(
+                    "agent-launch: rich terminal UI unavailable; using numbered prompts.",
+                    file=sys.stderr,
+                )
     while True:
         try:
             if args.understand:
@@ -11289,7 +11333,7 @@ def main(argv: list[str]) -> int:
 
 if __name__ == "__main__":
     try:
-        raise SystemExit(main(sys.argv[1:]))
+        raise SystemExit(main(sys.argv[1:], bundled_ui=True))
     except LaunchError as exc:
         print(f"agent-launch: {exc}", file=sys.stderr)
         raise SystemExit(2)

package/launch/provision-venv.sh

@@ -1,28 +1,59 @@
 #!/usr/bin/env bash
-# Provision the managed virtualenv that backs the agent-launch Textual preflight.
-#
-# The interactive launcher re-execs into this venv (launch/agent-launch.py ->
-# maybe_reexec_into_venv). It is an enhancement, not a hard dependency: when the
-# venv is missing or broken, the launcher falls back to numbered prompts, and
-# every direct / non-TTY / --no-tui path keeps running under the system
-# interpreter untouched. Re-run this after upgrading Python or the pin below.
+# Provision selected dependencies in the managed agent-bios virtualenv.
+# No argument installs Textual for terminal interfaces. --learning-only installs
+# the JSON Schema validator used by learn. Existing other packages are preserved.
 #
 #   AGENT_LAUNCH_VENV   override the venv location (default below)
 #   AGENT_LAUNCH_PYTHON python used to create the venv (default: python3)
 set -eu
 
 TEXTUAL_PIN="textual==8.2.8"
+JSONSCHEMA_PIN="jsonschema==4.26.0"
 VENV="${AGENT_LAUNCH_VENV:-$HOME/.local/share/agent-launch/venv}"
 PYTHON="${AGENT_LAUNCH_PYTHON:-python3}"
+PACKAGES=("$TEXTUAL_PIN")
+case "${1:-}" in
+  "") [ "$#" -eq 0 ] || { printf 'usage: provision-venv.sh [--learning-only]\n' >&2; exit 2; } ;;
+  --learning-only) [ "$#" -eq 1 ] || { printf 'usage: provision-venv.sh [--learning-only]\n' >&2; exit 2; }; PACKAGES=("$JSONSCHEMA_PIN") ;;
+  *) printf 'usage: provision-venv.sh [--learning-only]\n' >&2; exit 2 ;;
+esac
+
+runtime_python_ready() {
+  "$1" -c 'import sys; sys.exit("agent-bios requires Python 3.11+; select it with AGENT_LAUNCH_PYTHON and use a new AGENT_LAUNCH_VENV path for an incompatible existing environment" if sys.version_info < (3, 11) else 0)'
+}
+
+pinned_ready() {
+  "$VENV/bin/python" - "${PACKAGES[@]}" <<'PY'
+import importlib
+import importlib.metadata
+import sys
+for spec in sys.argv[1:]:
+    name, expected = spec.split("==", 1)
+    importlib.import_module(name)
+    if name == "jsonschema":
+        from jsonschema import Draft202012Validator
+    actual = importlib.metadata.version(name)
+    if actual != expected:
+        raise SystemExit(f"{name}: expected {expected}, found {actual}")
+    print(f"  {name} {actual} | python {sys.version.split()[0]}")
+PY
+}
 
-if [ -x "$VENV/bin/python" ] && "$VENV/bin/python" -c 'import textual' 2>/dev/null; then
+if [ -x "$VENV/bin/python" ]; then
+  runtime_python_ready "$VENV/bin/python"
+else
+  runtime_python_ready "$PYTHON"
+fi
+
+if [ -x "$VENV/bin/python" ] && pinned_ready >/dev/null 2>&1; then
   printf 'agent-launch venv already provisioned: %s\n' "$VENV"
-  "$VENV/bin/python" -c 'import textual, sys; print("  textual", textual.__version__, "| python", sys.version.split()[0])'
+  pinned_ready
   exit 0
 fi
 
 printf 'Provisioning agent-launch venv at %s ...\n' "$VENV"
-"$PYTHON" -m venv "$VENV"
-"$VENV/bin/python" -m pip install --quiet --upgrade pip
-"$VENV/bin/python" -m pip install --quiet "$TEXTUAL_PIN"
-"$VENV/bin/python" -c 'import textual, sys; print("Ready: textual", textual.__version__, "| python", sys.version.split()[0])'
+if [ ! -x "$VENV/bin/python" ]; then
+  "$PYTHON" -m venv "$VENV"
+fi
+"$VENV/bin/python" -m pip install --quiet --force-reinstall "${PACKAGES[@]}"
+pinned_ready

package/learn/collect-learning.py

@@ -23,7 +23,9 @@ never patches the payload to make it pass (runtime enforces, does not reason).
 
 Input:  the semantic payload as one JSON object on stdin.
 Host:   --host claude|codex (default: the tool prefix of supporting_sessions[0]).
-Home:   --config-dir, else $CLAUDE_CONFIG_DIR / $CODEX_HOME by host, else ~/.claude / ~/.codex.
+Private storage: $AGENT_BIOS_CORPUS_DIR, else ~/.config/agent-bios/corpus.
+Legacy storage: --config-dir, else $CLAUDE_CONFIG_DIR / $CODEX_HOME by host.
+--config-dir requires AGENT_BIOS_LEGACY_INSTALL=1; it cannot relocate private capture.
 After the local writes it best-effort uploads not-yet-delivered records to
 {base}/api/ingest/learnings via a host-private watermark over events.jsonl. The base and
 token resolve from the agent-bios-owned slot ~/.config/agent-bios/{ingest-url,
@@ -298,12 +300,12 @@ def apply_codex(home, bullet, dry):
 APPLY = {"claude": apply_claude, "codex": apply_codex}
 
 
-# ── Phase 2 transport: watermark upload over the durable learnings.jsonl ───────
+# ── Phase 2 transport: watermark upload over durable learning records ───────
 #
 # collect-learning runs on-demand (per `learn!`), so the upload piggybacks here:
 # after the local writes, best-effort POST any not-yet-settled records to
 # {ingest-url}/api/ingest/learnings and record which learning_ids are settled in
-# a small state file (the watermark). The durable learnings.jsonl is the single
+# a small state file (the watermark). The durable event log is the single
 # source and is never capped, so nothing is lost across a multi-day server outage
 # — unsettled records simply retry on the next `learn!`. A 2xx (incl. a duplicate
 # re-send, which the server dedups by learning_id) settles a record; 400/413
@@ -1143,11 +1145,13 @@ def _self_test():
 
 
 def main():
+    sys.dont_write_bytecode = True
     ap = argparse.ArgumentParser(description="Submit a session learning (learn!).")
     ap.add_argument("--host", choices=sorted(HOSTS),
                     help="session host (default: tool prefix of supporting_sessions[0])")
     ap.add_argument("--config-dir", default=None,
-                    help="config home (default: $CLAUDE_CONFIG_DIR / $CODEX_HOME by host)")
+                    help="legacy host home only (requires AGENT_BIOS_LEGACY_INSTALL=1); "
+                         "private capture uses AGENT_BIOS_CORPUS_DIR")
     ap.add_argument("--dry-run", action="store_true",
                     help="validate and print actions; write nothing")
     ap.add_argument("--no-upload", action="store_true",
@@ -1160,6 +1164,11 @@ def main():
         _self_test()
         return
 
+    legacy = os.environ.get("AGENT_BIOS_LEGACY_INSTALL") == "1"
+    if args.config_dir is not None and not legacy:
+        ap.error("--config-dir applies only to AGENT_BIOS_LEGACY_INSTALL=1; "
+                 "set AGENT_BIOS_CORPUS_DIR to relocate private learning storage")
+
     payload = read_payload()
     host = resolve_host(args.host, payload)
     home = resolve_home(host, args.config_dir)
@@ -1173,7 +1182,7 @@ def main():
         sys.exit(1)
 
     dry = args.dry_run
-    if os.environ.get("AGENT_BIOS_LEGACY_INSTALL") != "1":
+    if not legacy:
         # Capture is an immutable private source. Model-visible projections are
         # composed when an activated session is started, never written globally.
         sys.path.insert(0, str(REPO / "compose"))

package/learn/learning.schema.json

@@ -21,14 +21,14 @@
     "learning_id": {
       "type": "string",
       "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
-      "description": "Client-generated UUID for this learning, lowercase canonical form (tooling must lowercase, e.g. macOS uuidgen emits uppercase). Owned by learn/collect-learning.py, never hand-authored. Idempotency key for the pending-learnings.jsonl bounded retry in Phase 2. Distinct from the ledger's `id` (a curator-assigned short id like 'S3-07'); this is the light-flow record's own key.",
+      "description": "Client-generated UUID for this learning, lowercase canonical form (tooling must lowercase, e.g. macOS uuidgen emits uppercase). Owned by learn/collect-learning.py, never hand-authored. Idempotency key for the bounded upload retry over the host-qualified events.jsonl. Distinct from the ledger's `id` (a curator-assigned short id like 'S3-07'); this is the light-flow record's own key.",
       "$comment": "Ledger entries use `id`; the light-flow record's own key is `learning_id` (the artifact is a learning — LEXICON.md — so it is not `distill_id`, which would collide with the heavy session-distill pipeline)."
     },
     "lesson": {
       "type": "string",
       "minLength": 8,
       "maxLength": 2000,
-      "description": "The learning as prose — the same text that landed in the user's ~/.claude/personal/learnings.md. Ledger-compatible with entries[].lesson."
+      "description": "The captured lesson prose stored in the private corpus's host-qualified events.jsonl and supplied to future selected, activated-session snapshots. Ledger-compatible with entries[].lesson."
     },
     "domain": {
       "type": "string",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-bios",
-  "version": "0.18.0",
-  "releaseDate": "2026-09-11",
+  "version": "0.19.0",
+  "releaseDate": "2026-09-13",
   "description": "A thin, low-level instruction layer for LLM CLI agents: one set of principles and behavior whichever model you run. Stores a private, editable corpus for explicitly activated sessions.",
   "bin": {
     "agent-bios": "install.sh"
@@ -39,9 +39,19 @@
     "compose/corpus_catalog.py",
     "compose/corpus_session.py",
     "compose/corpus_install.py",
+    "compose/corpus_setup.py",
+    "compose/corpus_setup_cli.py",
+    "compose/corpus_setup_i18n.py",
+    "compose/corpus_setup_ui.py",
+    "compose/corpus_ui_runtime.py",
+    "compose/ui_runtime/",
+    "compose/corpus_import.py",
+    "compose/corpus_app.py",
+    "compose/app_bridge/",
     "compose/corpus_transaction.py",
     "compose/corpus_understand.py",
     "compose/bootstrap/",
+    "compose/setup/START.md",
     "launch/check-prompting-targets.sh",
     "learn/check-learning.py",
     "learn/collect-learning.py",
@@ -53,7 +63,9 @@
     "install.sh",
     "launch/provision-venv.sh",
     "session-cost.py",
+    "docs/",
     "README.md",
+    "INSTALL.md",
     "DEPENDENCIES.md",
     "provenance.json"
   ],

package/provenance.json

@@ -1 +1 @@
-{"commit":"588260e5b60f52f0f58b47e8d2ef7ae567b382a6","committedAt":"2026-09-11T21:09:27+09:00","dirty":false}
+{"commit":"35c75ca6ee0c7ecd3ed67c58dc48b854bc2d8b8e","committedAt":"2026-09-13T14:12:08+09:00","dirty":false}