agent-bios 0.1.0 → 0.3.0

package/scripts/agent-launch.py

@@ -10,6 +10,7 @@ import json
 import os
 import pathlib
 import shutil
+import subprocess
 import sys
 import textwrap
 import tomllib
@@ -18,6 +19,9 @@ from typing import Any, NoReturn
 
 
 TIER_ORDER = ("frontier", "helm", "workhorse", "sweep")
+# Tiers projected as spawnable subagents. HELM is the main role, never a
+# spawnable worker — registering it invited helm-as-subagent misuse.
+SPAWNABLE_TIERS = ("frontier", "workhorse", "sweep")
 EFFORT_ORDER = ("low", "medium", "high", "xhigh", "max", "ultra")
 HOST_EFFORTS = {
     "codex": {"low", "medium", "high", "xhigh", "max", "ultra"},
@@ -40,6 +44,15 @@ EFFORT_DESCRIPTIONS = {
 }
 CUSTOM_PRESET = "__custom__"
 OTHER_MODEL = "__other_model__"
+# User-saved presets live beside the deployed config, in a file the installer
+# neither deploys nor verifies, so they survive `agent-bios install`.
+USER_PRESETS_NAME = "presets.local.toml"
+USER_PRESETS_HEADER = (
+    "# agent-launch user presets, written by the launcher's save action.\n"
+    "# agent-bios install never deploys or verifies this file, so presets here\n"
+    "# survive upgrades. Shipped presets live in the deployed profiles.toml and\n"
+    "# are overridden by a preset of the same name here.\n"
+)
 
 
 @dataclass(frozen=True)
@@ -55,21 +68,55 @@ REVIEW_SETUPS = {
     "none": {
         "label": "None",
         "requirements": {"codex": (), "claude": ()},
+        "description": "No review route. Fastest; you review it yourself.",
         "contract": "No additional review route requested.",
     },
     "native-panel": {
         "label": "Native panel",
         "requirements": {"codex": (), "claude": ()},
+        "description": (
+            "Subagents review from different angles. Broad coverage, no dependency; "
+            "same-model reviewers share the main's blind spots."
+        ),
         "contract": "Use native multi-perspective subagents when review gates fire.",
     },
+    "slash-review": {
+        "label": "Slash review",
+        "requirements": {"codex": (), "claude": ()},
+        "description": {
+            "claude": (
+                "The built-in /code-review command (add `ultra` for the deep cloud pass). "
+                "Cheapest good diff review; same-family, so it is a weaker check than cross."
+            ),
+            "codex": (
+                "The built-in /review command. Cheapest good diff review; same-family, "
+                "so it is a weaker check than cross."
+            ),
+        },
+        "contract": {
+            "claude": (
+                "Use Claude Code's built-in /code-review when review gates fire; use "
+                "/code-review ultra for a deep multi-agent pass on high-risk changes."
+            ),
+            "codex": "Use Codex's built-in /review when review gates fire.",
+        },
+    },
     "onto": {
         "label": "onto-mcp",
         "requirements": {"codex": ("onto",), "claude": ("onto",)},
+        "description": (
+            "Structured multi-lens review through onto-mcp. Best for concept/ontology "
+            "and design work; needs onto installed."
+        ),
         "contract": "Use onto-mcp as the structured review lens when review gates fire.",
     },
     "ultracode": {
         "label": "Ultracode",
         "requirements": {"codex": ("ultracode",), "claude": ("ultracode",)},
+        "description": (
+            "Workflow-orchestrated review fanned out over many agents. Best for "
+            "exhaustive audits; slowest and most expensive."
+        ),
         "contract": (
             "Run the configured Ultracode CLI as a Codex-backed review route when "
             "review gates fire."
@@ -81,6 +128,10 @@ REVIEW_SETUPS = {
             "codex": ("onto", "ultracode"),
             "claude": ("onto", "ultracode"),
         },
+        "description": (
+            "onto + native + Ultracode together, acting on their union. Widest net for "
+            "risky work; missing routes degrade rather than fail."
+        ),
         "contract": {
             "codex": "Use onto plus native and Codex-backed Ultracode review kinds; act on their union.",
             "claude": "Use onto plus native multi-perspective and Codex-backed Ultracode review kinds; act on their union.",
@@ -96,12 +147,18 @@ REVIEW_SETUPS = {
 REVIEW_ROUTES = {
     "none": (),
     "native-panel": ("native",),
+    "slash-review": ("slash",),
     "onto": ("onto",),
     "ultracode": ("ultracode",),
     "hybrid": ("onto", "native", "ultracode"),
 }
+# Routes that are host-native review commands: they always resolve (no capability
+# to install) but run on the main's own family, so cross-family mode cannot dispatch
+# them to the opposite family and labels them PROPOSED instead.
+SAME_FAMILY_ROUTES = {"slash"}
 ROUTE_LABELS = {
     "native": "native same-model multi-perspective review",
+    "slash": "host-native slash-command review",
     "onto": "onto structured-lens review",
     "ultracode": "Codex-backed Ultracode review",
 }
@@ -153,6 +210,28 @@ def default_config_path() -> pathlib.Path:
     return pathlib.Path(__file__).resolve().parent.parent / "config/agent-launch.toml"
 
 
+def user_presets_path(config_path: pathlib.Path) -> pathlib.Path:
+    return config_path.with_name(USER_PRESETS_NAME)
+
+
+def load_user_presets(path: pathlib.Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    try:
+        data = tomllib.loads(path.read_text())
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise LaunchError(f"cannot load user presets {path}: {exc}") from exc
+    unexpected = sorted(set(data) - {"presets"})
+    if unexpected:
+        raise LaunchError(
+            f"{path} may only define [presets.*]; found: {', '.join(unexpected)}"
+        )
+    presets = data.get("presets", {})
+    if not isinstance(presets, dict):
+        raise LaunchError(f"[presets] must be a table in {path}")
+    return presets
+
+
 def load_config(path: pathlib.Path) -> dict[str, Any]:
     try:
         data = tomllib.loads(path.read_text())
@@ -163,12 +242,17 @@ def load_config(path: pathlib.Path) -> dict[str, Any]:
     for key in ("backends", "hosts", "presets"):
         if not isinstance(data.get(key), dict) or not data[key]:
             raise LaunchError(f"config requires non-empty [{key}]")
+    # Merged before the preset checks below so user presets face the same validation.
+    data["presets"].update(load_user_presets(user_presets_path(path)))
     capabilities = data.get("capabilities", {})
     if not isinstance(capabilities, dict):
         raise LaunchError("[capabilities] must be a table")
     for name, capability in capabilities.items():
         if not isinstance(capability, dict):
             raise LaunchError(f"capability must be a table: {name}")
+        hint = capability.get("install")
+        if hint is not None and (not isinstance(hint, str) or not hint):
+            raise LaunchError(f"capabilities.{name}.install must be a non-empty string")
     onto = capabilities.get("onto")
     if onto is not None and (
         not isinstance(onto.get("command"), str) or not onto["command"]
@@ -304,7 +388,7 @@ def route_availability(plan: dict[str, Any]) -> dict[str, bool]:
     a mounted onto plus a review_onto pin to flip its family."""
     capabilities = plan.get("capabilities", {})
     if plan.get("review_family", "cross") == "same":
-        available = {"native": bool(plan["delegation"])}
+        available = {"native": bool(plan["delegation"]), "slash": True}
         for route, capability in (("onto", "onto"), ("ultracode", "ultracode")):
             available[route] = _resolves(capabilities.get(capability, {}).get("command", ""))
         return available
@@ -313,11 +397,26 @@ def route_availability(plan: dict[str, Any]) -> dict[str, bool]:
     )
     return {
         "native": cross_native_command(plan) is not None,
+        # The host's own review command exists, but only for its own family; the
+        # cross branch of effective_review routes it to the PROPOSED floor.
+        "slash": True,
         "onto": onto_ok,
         "ultracode": cross_ultracode_command(plan) is not None,
     }
 
 
+def install_hint(plan: dict[str, Any], routes: list[str]) -> str:
+    """One-line install guidance for the capability-backed routes that are missing.
+    Empty when a route has no capability, no configured install, or is already there."""
+    capabilities = plan.get("capabilities", {})
+    hints = []
+    for route in routes:
+        hint = capabilities.get(route, {}).get("install")
+        if hint and hint not in hints:
+            hints.append(hint)
+    return f"; install: {' && '.join(hints)}" if hints else ""
+
+
 def effective_review(plan: dict[str, Any]) -> tuple[list[str], list[str], str | None]:
     """Resolve the requested review setup to the routes that can actually run.
 
@@ -325,9 +424,11 @@ def effective_review(plan: dict[str, Any]) -> tuple[list[str], list[str], str |
     reproduces the earlier degrade-to-native behavior (floor None; a dropped
     external route degrades to native in effective; native requires delegation).
     In cross-family mode the effective routes run on the opposite family; when no
-    cross route resolves and delegation is on, floor='native' marks a same-family
-    PROPOSED fallback, and a requested non-none setup with no cross route and no
-    fallback (delegation off) fails closed."""
+    cross route resolves the floor names the same-family route that runs instead,
+    labeled PROPOSED — a SAME_FAMILY_ROUTES route floors as itself (it needs no
+    delegation, being the host's own command), otherwise 'native' when delegation
+    is on. A requested non-none setup with no cross route and no fallback
+    (delegation off) fails closed."""
     requested = plan["review_setup"]
     if requested not in REVIEW_ROUTES:
         raise LaunchError(f"unknown review setup: {requested!r}")
@@ -341,11 +442,24 @@ def effective_review(plan: dict[str, Any]) -> tuple[list[str], list[str], str |
         if dropped and "native" not in effective and plan["delegation"]:
             effective.append("native")
         return effective, dropped, None
-    effective = [route for route in wanted if available[route]]
+    # A same-family route cannot be dispatched cross-family, so it is never
+    # "effective" here; it becomes the PROPOSED floor below instead.
+    effective = [
+        route
+        for route in wanted
+        if available[route] and route not in SAME_FAMILY_ROUTES
+    ]
     dropped = [route for route in wanted if not available[route]]
     floor = None
     if not effective and requested != "none":
-        if plan["delegation"]:
+        same_family = [
+            route
+            for route in wanted
+            if route in SAME_FAMILY_ROUTES and available[route]
+        ]
+        if same_family:
+            floor = same_family[0]
+        elif plan["delegation"]:
             floor = "native"
         else:
             raise LaunchError(
@@ -429,6 +543,7 @@ _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 rich.text import Text
     from textual import work
     from textual.app import App
     from textual.binding import Binding
@@ -459,7 +574,7 @@ def _build_app_class():
 
     app_css = """
     Screen { background: $surface; }
-    #al-title { color: $accent; text-style: bold; padding: 0 1; }
+    #al-title { background: $primary; color: black; text-style: bold; padding: 0 1; }
     #al-setup {
         border: round $primary; border-title-color: $primary;
         border-title-style: bold; padding: 0 1; height: auto;
@@ -468,6 +583,10 @@ def _build_app_class():
         border: round $secondary; border-title-color: $secondary;
         border-title-style: bold; padding: 0 1; height: 5;
     }
+    #al-learning-title { background: $warning; color: black; text-style: bold; padding: 0 1; }
+    #al-learning {
+        border: round $warning; padding: 0 1; height: auto;
+    }
     #al-hdr { color: $text-muted; text-style: bold; padding: 0 1; }
     OptionList { height: 1fr; border: none; padding: 0 1; }
     #al-footer { color: $text-muted; dock: bottom; padding: 0 1; background: $panel; }
@@ -486,7 +605,9 @@ def _build_app_class():
             Binding("ctrl+c", "cancel", "cancel", priority=True),
         ]
 
-        def __init__(self, title, options, default, allow_back, plan, preview=None):
+        def __init__(
+            self, title, options, default, allow_back, plan, preview=None, learning=None
+        ):
             super().__init__()
             self._title = title
             self._options = options
@@ -494,10 +615,14 @@ def _build_app_class():
             self._allow_back = allow_back
             self._plan = plan
             self._preview = preview
+            self._learning = learning
 
         def compose(self):
             yield Static(self._title, id="al-title")
             yield setup_panel(self._plan)
+            if self._learning:
+                yield Static("Session Learning", id="al-learning-title")
+                yield Static("\n".join(self._learning), id="al-learning")
             detail = Static("", id="al-detail")
             detail.border_title = "About highlighted option"
             yield detail
@@ -507,6 +632,19 @@ def _build_app_class():
             option_list = OptionList()
             for option in self._options:
                 label = option.label + ("" if option.enabled else "  [unavailable]")
+                if option.value == LEARNING_HUB:
+                    # The learning area is a different kind of destination than
+                    # the launch presets: separated, marked, and warning-toned
+                    # to match its status panel.
+                    option_list.add_option(None)
+                    option_list.add_option(
+                        Option(
+                            Text(f"◆ {label}", style="bold yellow"),
+                            id=option.value,
+                            disabled=not option.enabled,
+                        )
+                    )
+                    continue
                 option_list.add_option(
                     Option(label, id=option.value, disabled=not option.enabled)
                 )
@@ -665,10 +803,13 @@ class TextualUI:
         default: str,
         allow_back: bool,
         preview=None,
+        learning_lines: list[str] | None = None,
     ) -> str:
         result = self.app.call_from_thread(
             self.app.push_screen_wait,
-            self._menu_screen(title, options, default, allow_back, self.plan, preview),
+            self._menu_screen(
+                title, options, default, allow_back, self.plan, preview, learning_lines
+            ),
         )
         if result == _UI_BACK:
             raise BackRequested
@@ -704,13 +845,26 @@ def run_textual_flow(
 
 
 def choose_lines(
-    title: str, options: list[MenuOption], default: str, allow_back: bool
+    title: str,
+    options: list[MenuOption],
+    default: str,
+    allow_back: bool,
+    learning_lines: list[str] | None = None,
 ) -> str:
     print(f"\n{title}")
+    if learning_lines:
+        print("  -- Session Learning --")
+        for line in learning_lines:
+            print(f"  {line}")
+        print("  --")
     for index, option in enumerate(options, 1):
         marker = "" if option.enabled else " [unavailable]"
         selected = " *" if option.value == default and option.enabled else ""
-        print(f"  {index}. {option.label}{marker}{selected} - {option.description}")
+        label = option.label
+        if option.value == LEARNING_HUB:
+            print("  " + "-" * 30)
+            label = f"◆ {label}"
+        print(f"  {index}. {label}{marker}{selected} - {option.description}")
         if not option.enabled:
             print(f"     Unavailable: {option.unavailable_reason}")
     while True:
@@ -744,12 +898,13 @@ def choose(
     ui: TextualUI | None = None,
     allow_back: bool = False,
     preview=None,
+    learning_lines: list[str] | None = None,
 ) -> str:
     if not any(option.enabled for option in options):
         raise LaunchError(f"no available options for {title}")
     if ui is not None:
-        return ui.choose(title, options, default, allow_back, preview)
-    return choose_lines(title, options, default, allow_back)
+        return ui.choose(title, options, default, allow_back, preview, learning_lines)
+    return choose_lines(title, options, default, allow_back, learning_lines)
 
 
 def read_input(prompt: str) -> str:
@@ -840,6 +995,12 @@ def build_plan(config: dict[str, Any], host: str, preset_name: str) -> dict[str,
     label = preset.get("label", preset_name)
     if not isinstance(label, str) or not label:
         raise LaunchError(f"invalid label in preset {preset_name}")
+    mission = preset.get("mission")
+    if mission is not None and (not isinstance(mission, str) or not mission):
+        raise LaunchError(f"presets.{preset_name}.mission must be a non-empty string")
+    trigger = preset.get("trigger")
+    if trigger is not None and (not isinstance(trigger, str) or not trigger):
+        raise LaunchError(f"presets.{preset_name}.trigger must be a non-empty string")
     review_family = preset.get("review_family", "cross")
     review_host = REVIEW_HOST[host]
     opposite = config.get("hosts", {}).get(review_host)
@@ -878,12 +1039,16 @@ def build_plan(config: dict[str, Any], host: str, preset_name: str) -> dict[str,
         "review_backend": review_backend,
         "agent_templates": copy.deepcopy(config["hosts"][host].get("agent_templates")),
         "capabilities": copy.deepcopy(config.get("capabilities", {})),
+        "mission": mission,
+        "trigger": trigger,
     }
 
 
 def review_description(host: str, name: str) -> str:
-    contract = REVIEW_SETUPS[name]["contract"]
-    return contract[host] if isinstance(contract, dict) else contract
+    """The user-facing one-liner for the menu: what the setup is for and what it
+    costs. Distinct from ["contract"], which is the instruction sent to the agent."""
+    description = REVIEW_SETUPS[name]["description"]
+    return description[host] if isinstance(description, dict) else description
 
 
 def effort_options(host: str, model: str) -> list[MenuOption]:
@@ -1001,13 +1166,19 @@ def save_preset(
         )
     fields, tier_overrides = preset_from_plan(plan, config, name)
     block = render_preset_block(name, fields, tier_overrides)
-    text = remove_preset_block(config_path.read_text(), name).rstrip("\n") + "\n\n" + block
-    temporary = config_path.with_name(f".{config_path.name}.{os.getpid()}.tmp")
+    target = user_presets_path(config_path)
+    try:
+        kept = remove_preset_block(target.read_text(), name).rstrip("\n")
+    except FileNotFoundError:
+        kept = USER_PRESETS_HEADER.rstrip("\n")
+    text = kept + "\n\n" + block
+    temporary = target.with_name(f".{target.name}.{os.getpid()}.tmp")
     try:
+        target.parent.mkdir(parents=True, exist_ok=True)
         temporary.write_text(text)
-        os.replace(temporary, config_path)
+        os.replace(temporary, target)
     except OSError as exc:
-        raise LaunchError(f"cannot save preset to {config_path}: {exc}") from exc
+        raise LaunchError(f"cannot save preset to {target}: {exc}") from exc
 
 
 def customize(
@@ -1033,7 +1204,10 @@ def customize(
         ]
         if missing:
             note = "degrades to same-family native (PROPOSED)" if cross else "degrades to native"
-            description = f"{description} ({', '.join(missing)} unavailable now; {note})"
+            description = (
+                f"{description} ({', '.join(missing)} unavailable now; {note}"
+                f"{install_hint(plan, missing)})"
+            )
         review_options.append(MenuOption(name, spec["label"], description))
     if plan["host"] == "codex":
         policies = [
@@ -1265,6 +1439,215 @@ def customize(
             raise KeyboardInterrupt
 
 
+LEARNING_HUB = "__learning__"
+LEARNING_PRESET = "session-learning"
+LEARNING_STATUS_PATH = pathlib.Path(
+    os.environ.get(
+        "AGENT_BIOS_LEARNING_STATUS",
+        str(pathlib.Path.home() / ".local/share/agent-bios/learning-status.json"),
+    )
+)
+
+
+def load_learning_status() -> dict[str, Any] | None:
+    try:
+        return json.loads(LEARNING_STATUS_PATH.read_text())
+    except (OSError, ValueError):
+        return None
+
+
+def learning_summary_lines(status: dict[str, Any] | None) -> list[str]:
+    """Panel body for the Session Learning area: which learning content is
+    live, through which mechanisms, and whether the corpus is rolled back."""
+    if status is None:
+        return ["learning status not projected yet — run: agent-bios install"]
+    current = status.get("current_version", "?")
+    latest = status.get("latest_version", "?")
+    head = f"Applied version  {current}"
+    if status.get("rolled_back_to"):
+        head += f"  (ROLLED BACK; latest is {latest})"
+    layers = status.get("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 "none"
+    by_status = status.get("summary", {}).get("by_status", {})
+    return [
+        head,
+        f"Mechanisms       {layer_text}",
+        f"Ledger           placed {by_status.get('placed', 0)} · "
+        f"incubating {by_status.get('incubating', 0) + by_status.get('incubating-G', 0)} · "
+        f"versions {len(status.get('versions', []))}",
+    ]
+
+
+def _learning_info(ui: TextualUI | None, title: str, lines: list[str]) -> None:
+    """Info screen in both UIs: options carry the content; only exit is back."""
+    options = [MenuOption("back", "Back", "Return to Session Learning.")]
+    try:
+        choose(title, options, "back", ui, allow_back=True, learning_lines=lines)
+    except BackRequested:
+        pass
+
+
+def _learning_rollback(status: dict[str, Any], version: str, ui: TextualUI | None) -> None:
+    confirm = choose(
+        f"Roll back learning corpus to {version}?",
+        [
+            MenuOption(
+                "cancel", "Cancel", "Keep the currently deployed learning content."
+            ),
+            MenuOption(
+                "rollback",
+                f"Roll back to {version}",
+                "Re-deploys globals/guides/hooks as of that learning version. "
+                "System deployment (launcher, wrappers) stays current. Roll "
+                "forward again by selecting the latest version.",
+            ),
+        ],
+        "cancel",
+        ui,
+        allow_back=True,
+    )
+    if confirm != "rollback":
+        return
+    script = pathlib.Path(status["repo"]) / "scripts/session-learning/learning-state.py"
+    result = subprocess.run(
+        [sys.executable, str(script), "rollback", "--version", version],
+        capture_output=True,
+        text=True,
+    )
+    output = (result.stdout + result.stderr).strip().splitlines()
+    tail = output[-1] if output else ""
+    verdict = "Rollback complete." if result.returncode == 0 else "Rollback FAILED."
+    _learning_info(ui, verdict, [tail] if tail else [])
+
+
+def _learning_versions(ui: TextualUI | None) -> None:
+    while True:
+        status = load_learning_status()
+        if status is None:
+            _learning_info(ui, "Versions & rollback", learning_summary_lines(None))
+            return
+        current = status.get("current_version")
+        options = []
+        for v in reversed(status.get("versions", [])):
+            name = v["version"]
+            label = f"{name} (current)" if name == current else name
+            options.append(
+                MenuOption(
+                    name,
+                    label,
+                    f"closed {v.get('closed', '?')} · commit {v.get('commit', '')[:12]} · "
+                    f"{v.get('summary', '')}",
+                )
+            )
+        options.append(MenuOption("back", "Back", "Return to Session Learning."))
+        try:
+            selected = choose(
+                "Versions & rollback",
+                options,
+                options[0].value,
+                ui,
+                allow_back=True,
+                learning_lines=learning_summary_lines(status),
+            )
+        except BackRequested:
+            return
+        if selected == "back":
+            return
+        if selected == current:
+            _learning_info(
+                ui,
+                f"{selected} is the currently applied version",
+                ["Select a different version to roll back or forward."],
+            )
+            continue
+        _learning_rollback(status, selected, ui)
+
+
+def _learning_packages(ui: TextualUI | None) -> None:
+    """v1: the corpus ships as a single core package; the list shape is ready
+    for the domain-packaging backlog to populate with real packages."""
+    status = load_learning_status()
+    if status is None:
+        _learning_info(ui, "Learning packages", learning_summary_lines(None))
+        return
+    layers = status.get("summary", {}).get("placed_by_layer", {})
+    options = [
+        MenuOption(
+            "core",
+            f"core corpus @ {status.get('current_version', '?')}",
+            "All learning domains in one package until domain packaging "
+            f"lands (backlog). Layers: {json.dumps(layers, separators=(', ', ' '))}. "
+            "Per-domain selection, versions, and rollback will appear here.",
+        ),
+        MenuOption("back", "Back", "Return to Session Learning."),
+    ]
+    try:
+        choose(
+            "Learning packages",
+            options,
+            "back",
+            ui,
+            allow_back=True,
+            learning_lines=learning_summary_lines(status),
+        )
+    except BackRequested:
+        pass
+
+
+def learning_hub(config: dict[str, Any], ui: TextualUI | None) -> str:
+    """Session Learning area: status, packages, versions/rollback, session start.
+
+    Returns "start" to launch the learning-session preset, "back" otherwise.
+    """
+    while True:
+        status = load_learning_status()
+        options = [
+            MenuOption(
+                "start",
+                "Start a learning session",
+                "Launch with the Session learning preset: the mission line "
+                "directs the session to the workflow guide and the SSOT.",
+                enabled=LEARNING_PRESET in config["presets"],
+                unavailable_reason=f"preset {LEARNING_PRESET!r} not configured",
+            ),
+            MenuOption(
+                "packages",
+                "Learning packages",
+                "What learning content is applied, as installable packages "
+                "(v1: single core corpus).",
+            ),
+            MenuOption(
+                "versions",
+                "Versions & rollback",
+                "Learning content versions (distinct from system deployment); "
+                "roll the corpus back or forward.",
+            ),
+            MenuOption("back", "Back", "Return to the launch menu."),
+        ]
+        try:
+            selected = choose(
+                "Session Learning",
+                options,
+                "start",
+                ui,
+                allow_back=True,
+                learning_lines=learning_summary_lines(status),
+            )
+        except BackRequested:
+            return "back"
+        if selected == "back":
+            return "back"
+        if selected == "start":
+            return "start"
+        if selected == "packages":
+            _learning_packages(ui)
+        elif selected == "versions":
+            _learning_versions(ui)
+
+
 def select_plan(
     config: dict[str, Any],
     host: str,
@@ -1295,21 +1678,44 @@ def select_plan(
                     "Open a settings hub for tiers, review setup, policy, and final confirmation.",
                 )
             )
+            options.append(
+                MenuOption(
+                    LEARNING_HUB,
+                    "Enter Session Learning Mode",
+                    "Learning-refinement mode: applied versions and mechanisms, "
+                    "packages, rollback — and start a dedicated learning session "
+                    "(preselected on entry).",
+                )
+            )
             default = "balanced" if "balanced" in presets else next(iter(presets))
             if ui is not None:
                 ui.set_plan(build_plan(config, host, default))
+
+            def preview_name(value: str) -> str:
+                if value == CUSTOM_PRESET:
+                    return default
+                if value == LEARNING_HUB:
+                    return LEARNING_PRESET if LEARNING_PRESET in presets else default
+                return value
+
             selected = choose(
                 "Preset",
                 options,
                 default,
                 ui,
-                preview=lambda value: build_plan(
-                    config, host, default if value == CUSTOM_PRESET else value
-                ),
+                preview=lambda value: build_plan(config, host, preview_name(value)),
+                learning_lines=learning_summary_lines(load_learning_status()),
             )
             if selected == CUSTOM_PRESET:
                 selected_name = default
                 selected_custom = True
+            elif selected == LEARNING_HUB:
+                if learning_hub(config, ui) != "start":
+                    continue
+                if LEARNING_PRESET not in presets:
+                    raise LaunchError(f"preset {LEARNING_PRESET!r} missing from config")
+                selected_name = LEARNING_PRESET
+                selected_custom = False
             else:
                 selected_name = selected
         if selected_name not in presets:
@@ -1347,7 +1753,7 @@ def codex_agent_configs(
     if not isinstance(templates, dict):
         raise LaunchError("Codex delegation requires [hosts.codex.agent_templates]")
     rendered: dict[str, tuple[str, str]] = {}
-    for tier in ("frontier", "workhorse", "sweep"):
+    for tier in SPAWNABLE_TIERS:
         source_value = templates.get(tier)
         if not isinstance(source_value, str) or not source_value:
             raise LaunchError(f"Codex agent template missing: {tier}")
@@ -1471,6 +1877,15 @@ def _cross_review_route(
             "No cross-family route resolved at launch; using same-family native "
             "subagent review labeled PROPOSED (family collapse)."
         )
+    elif floor:
+        setup_contract = REVIEW_SETUPS[plan["review_setup"]]["contract"]
+        if isinstance(setup_contract, dict):
+            setup_contract = setup_contract[plan["host"]]
+        parts.append(
+            f"This review route runs on this main's own family, so it cannot be "
+            f"dispatched cross-family; its verdicts are PROPOSED (family collapse). "
+            f"{setup_contract}"
+        )
     parts.append(
         "Cross-family reviewers are dispatched as read-only subprocesses, not "
         "CLI-native subagents; spawning them needs this main's execution policy to "
@@ -1500,7 +1915,12 @@ def run_contract(plan: dict[str, Any]) -> str:
         if plan["host"] == "codex"
         else "Main and child model/effort defaults are CLI-projected."
     )
+    mission = plan.get("mission")
+    if mission and plan.get("trigger"):
+        mission = mission.replace("{trigger}", plan["trigger"])
+    mission_prefix = f"Mission: {mission} " if mission else ""
     return (
+        f"{mission_prefix}"
         f"LaunchPlan: main={plan['main_tier']} ({plan['tiers'][plan['main_tier']]['model']}/"
         f"{tier_effort(plan, plan['main_tier'])}); tiers: {bindings}. "
         f"Delegation={'on' if plan['delegation'] else 'off'}. Review family={family}. "
@@ -1513,7 +1933,7 @@ def run_contract(plan: dict[str, Any]) -> str:
 
 def claude_agents(plan: dict[str, Any]) -> str:
     roles = {}
-    for tier in TIER_ORDER:
+    for tier in SPAWNABLE_TIERS:
         binding = plan["tiers"][tier]
         roles[tier] = {
             "description": f"{tier.upper()} tier: {binding['model']} at {tier_effort(plan, tier)}",
@@ -1615,13 +2035,13 @@ def print_summary(
         if effective:
             review_display += f" via {'+'.join(effective)}"
         if dropped:
-            review_display += f" (dropped {','.join(dropped)})"
-        if floor == "native":
-            review_display += " → same-family native PROPOSED"
+            review_display += f" (dropped {','.join(dropped)}{install_hint(plan, dropped)})"
+        if floor:
+            review_display += f" → same-family {floor} PROPOSED"
     elif dropped:
         review_display += (
             f" → effective {'+'.join(effective) or 'none'} "
-            f"({','.join(dropped)} unavailable)"
+            f"({','.join(dropped)} unavailable{install_hint(plan, dropped)})"
         )
     print(
         f"  Review setup   {review_display} · "
@@ -1652,6 +2072,49 @@ def print_summary(
         print("  Argv           " + json.dumps([command, *args]), file=stream)
 
 
+SESSION_LEARNING_STATE = pathlib.Path(
+    os.environ.get(
+        "AGENT_BIOS_SESSION_LEARNING_STATE",
+        str(pathlib.Path.home() / ".local/share/agent-bios/session-learning-state.json"),
+    )
+)
+
+
+def _line_count(path: pathlib.Path) -> int:
+    try:
+        with path.open("rb") as fh:
+            return sum(chunk.count(b"\n") for chunk in iter(lambda: fh.read(1 << 20), b""))
+    except OSError:
+        return 0
+
+
+def session_learning_nudge(config: dict[str, Any]) -> str | None:
+    """Nudge when enough sessions accumulated since the last mining window.
+
+    The baseline is written by scripts/session-learning/update-state.py at
+    window close; provider history line counts are a cheap proxy for new
+    sessions. No state file means no nudge.
+    """
+    try:
+        state = json.loads(SESSION_LEARNING_STATE.read_text())
+        baseline = int(state["history_lines_total"])
+    except (OSError, ValueError, KeyError, TypeError):
+        return None
+    settings = config.get("session_learning", {})
+    threshold = settings.get("nudge_after", 250) if isinstance(settings, dict) else 250
+    current = _line_count(pathlib.Path.home() / ".claude/history.jsonl") + _line_count(
+        pathlib.Path.home() / ".codex/history.jsonl"
+    )
+    delta = current - baseline
+    if delta < threshold:
+        return None
+    return (
+        f"session-learning due: ~{delta} new session entries since "
+        f"{state.get('window_end', '?')} (threshold {threshold}) — launch the "
+        "Session learning preset to run the next mining window"
+    )
+
+
 def parse_args(argv: list[str]) -> argparse.Namespace:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--config", type=pathlib.Path, default=default_config_path())
@@ -1681,6 +2144,12 @@ def main(argv: list[str]) -> int:
     config_path = args.config.expanduser()
     config = load_config(config_path)
     command, passthrough = resolve_backend(config, args.host)
+    nudge = session_learning_nudge(config)
+    if nudge:
+        print(f"agent-launch: {nudge}", file=sys.stderr)
+        nudged = config["presets"].get("session-learning")
+        if isinstance(nudged, dict):
+            nudged["description"] = f"{nudged.get('description', '')} ⚠ {nudge}".strip()
     tty = sys.stdin.isatty() and sys.stdout.isatty()
     if not tty and args.dry_run and not args.preset and not args.custom:
         if "balanced" not in config["presets"]:
@@ -1718,6 +2187,12 @@ def main(argv: list[str]) -> int:
     projected = [*project_args(plan, materialize_agents=not args.dry_run), *args.forward]
     summary_stream = sys.stdout if tty or args.dry_run else sys.stderr
     print_summary(plan, command, projected, summary_stream, bool(args.forward))
+    trigger = plan.get("trigger")
+    if trigger:
+        # Black-on-yellow to match the Session Learning identity; the session
+        # waits for this exact phrase before starting the workflow.
+        line = f'  Once the session is up, type "{trigger}" to begin the learning workflow.  '
+        print(f"\n\x1b[1;30;43m{line}\x1b[0m", file=summary_stream)
     if args.dry_run:
         print(json.dumps([command, *projected], ensure_ascii=False))
         return 0