agent-bios 0.2.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"},
@@ -539,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
@@ -569,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;
@@ -578,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; }
@@ -596,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
@@ -604,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
@@ -617,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)
                 )
@@ -775,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
@@ -814,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:
@@ -854,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:
@@ -950,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)
@@ -988,6 +1039,8 @@ 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,
     }
 
 
@@ -1386,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,
@@ -1416,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:
@@ -1468,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}")
@@ -1630,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}. "
@@ -1643,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)}",
@@ -1782,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())
@@ -1811,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"]:
@@ -1848,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

package/scripts/check-parity.sh

@@ -111,6 +111,8 @@ current-state dashboard|claude/CLAUDE.md|claude/guides/implementation-map.md
 Verification Menus|claude/CLAUDE.md|claude/guides/coding-staged-workflow.md
 real Microsoft Excel engine|claude/CLAUDE.md|claude/guides/coding-staged-workflow.md
 severity contract|README.md|claude/guides/coding-staged-workflow.md
+Ambient state|claude/CLAUDE.md|claude/guides/tooling-gotchas.md
+the full lifecycle of what you create|claude/CLAUDE.md|claude/guides/tooling-gotchas.md
 ANCHORS
 
 # The launcher's Textual preflight UI tests need the managed venv (textual).
@@ -264,6 +266,33 @@ for filename, (expected_name, expected_model, expected_effort) in expected_agent
             f"want {expected_effort!r}"
         )
 
+# codex/config-additions.toml is the additive fragment install merges into the
+# live ~/.codex/config.toml; its agent entries are projections of the canonical
+# codex/agents/*.toml templates and must not drift from them.
+fragment_path = pathlib.Path("codex/config-additions.toml")
+if not fragment_path.is_file():
+    mark_fail("required file missing: codex/config-additions.toml")
+else:
+    fragment = tomllib.loads(fragment_path.read_text())
+    if fragment.get("features", {}).get("multi_agent") is not True:
+        mark_fail("config-additions must set features.multi_agent = true")
+    fragment_agents = fragment.get("agents", {})
+    if set(fragment_agents) != {"frontier", "workhorse", "sweep"}:
+        mark_fail(
+            "config-additions agents must be exactly the spawnable tiers "
+            f"(no helm): {sorted(fragment_agents)}"
+        )
+    for tier, spec in fragment_agents.items():
+        template_path = agent_dir / f"{tier}.toml"
+        template = tomllib.loads(template_path.read_text()) if template_path.is_file() else {}
+        if spec.get("description") != template.get("description"):
+            mark_fail(f"config-additions {tier} description drifted from {template_path}")
+        if spec.get("config_file") != f"${{CODEX_HOME}}/agents/{tier}.toml":
+            mark_fail(
+                f"config-additions {tier} config_file must be "
+                f"${{CODEX_HOME}}/agents/{tier}.toml"
+        )
+
 
 def table_row(path, slot):
     for raw_line in path.read_text().splitlines():
@@ -522,7 +551,7 @@ if launcher.is_file() and launch_profile:
             def set_plan(self, plan):
                 self.plan = plan
 
-            def choose(self, title, options, default, allow_back, preview=None):
+            def choose(self, title, options, default, allow_back, preview=None, learning_lines=None):
                 if title == "Preset":
                     if preview is not None:
                         balanced = launcher_module.setup_summary_lines(preview("balanced"))
@@ -748,6 +777,7 @@ if launcher.is_file() and launch_profile:
             (b"Esc cancel | q cancel", b"\x1b[B"),
             (b"hybrid onto", b"\x1b[B"),
             (b"high-volume", b"\x1b[B"),
+            (b"learning-refinement", b"\x1b[B"),
             (b"Open a settings hub", b"\r"),
         )
         down = b"\x1b[B"
@@ -1098,10 +1128,11 @@ if launcher.is_file() and launch_profile:
         # TERM=dumb routes to numbered prompts (textual renders on any usable
         # terminal, so the numbered fallback is gated on TERM/non-TTY/textual
         # availability, not a terminfo probe). 'b' is the numbered back command.
+        custom_number = str(len(fake_data["presets"]) + 1).encode()
         transcript, picker_status = run_picker_scenario(
             "numbered fallback (TERM=dumb)",
             (
-                (b"Open a settings hub", b"4\n"),
+                (b"Open a settings hub", custom_number + b"\n"),
                 (b"Custom settings", b"b\n"),
                 (b"HELM default for everyday work", b"1\n"),
             ),
@@ -1114,6 +1145,28 @@ if launcher.is_file() and launch_profile:
         ):
             mark_fail("agent-launch numbered fallback (TERM=dumb) did not preserve numbered back")
 
+        # Session Learning hub: enter, render status, back out, launch balanced.
+        learning_number = str(len(fake_data["presets"]) + 2).encode()
+        transcript, picker_status = run_picker_scenario(
+            "numbered learning hub (TERM=dumb)",
+            (
+                (b"Session Learning", learning_number + b"\n"),
+                (b"Versions & rollback", b"4\n"),
+                (b"HELM default for everyday work", b"1\n"),
+            ),
+            term="dumb",
+        )
+        learning_panel_rendered = (
+            b"Applied version" in transcript or b"not projected yet" in transcript
+        )
+        if (
+            picker_status != 0
+            or b"Traceback" in transcript
+            or not learning_panel_rendered
+            or b"Preset         Balanced" not in transcript
+        ):
+            mark_fail("agent-launch numbered learning hub did not render or return")
+
         passed = invoke([
             sys.executable, str(launcher), "--no-tui", "codex", "--", "exec", "--json", "probe"
         ], env=env)
@@ -1421,7 +1474,16 @@ if launcher.is_file() and launch_profile:
             except (ValueError, IndexError, json.JSONDecodeError) as exc:
                 mark_fail(f"agent-launch Claude --agents projection is not valid JSON: {exc}")
             else:
-                for tier, (model, effort) in expected_claude_tiers.items():
+                expected_spawnable = {
+                    tier: expected_claude_tiers[tier]
+                    for tier in ("frontier", "workhorse", "sweep")
+                }
+                if set(agents_arg) != set(expected_spawnable):
+                    mark_fail(
+                        "Claude --agents must project exactly the spawnable tiers "
+                        f"(HELM is the main, never a subagent): {sorted(agents_arg)}"
+                    )
+                for tier, (model, effort) in expected_spawnable.items():
                     role = agents_arg.get(tier, {})
                     if role.get("model") != model or role.get("effort") != effort:
                         mark_fail(f"agent-launch Claude {tier} role projection drifted: {role!r}")

package/scripts/codex-helm.sh

@@ -268,9 +268,27 @@ EOF
 EOF
 }
 
+# Review packets must carry the whole subject: range-based diffs silently omit
+# staged-but-uncommitted changes and untracked files, so the dispatcher itself
+# appends the subject tree's actual state to the packet.
+scope_note=""
+if [ "$mode" = "review" ] && { [ -n "$cd_dir" ] || [ "$reach" != "hermetic" ]; }; then
+  scope_root="${cd_dir:-$PWD}"
+  if git -C "$scope_root" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    scope_status="$(git -C "$scope_root" status --porcelain 2>/dev/null || true)"
+    if [ -n "$scope_status" ]; then
+      scope_note="Review scope manifest (dispatcher-generated \`git status --porcelain\` of the subject tree; uncommitted/untracked entries are part of the review subject unless the task says otherwise):
+$scope_status"
+      echo "codex-helm: subject tree has uncommitted/untracked entries; scope manifest appended to the packet" >&2
+    fi
+  fi
+fi
+
 final_prompt="$(build_preamble)
 
-User task:
+${scope_note:+$scope_note
+
+}User task:
 $user_prompt"
 
 cleanup_dirs=()