agent-bios 0.1.0

package/scripts/agent-launch.py

@@ -0,0 +1,1742 @@
+#!/usr/bin/env python3
+"""Interactive preflight launcher for Codex and Claude."""
+
+from __future__ import annotations
+
+import argparse
+import copy
+import hashlib
+import json
+import os
+import pathlib
+import shutil
+import sys
+import textwrap
+import tomllib
+from dataclasses import dataclass
+from typing import Any, NoReturn
+
+
+TIER_ORDER = ("frontier", "helm", "workhorse", "sweep")
+EFFORT_ORDER = ("low", "medium", "high", "xhigh", "max", "ultra")
+HOST_EFFORTS = {
+    "codex": {"low", "medium", "high", "xhigh", "max", "ultra"},
+    "claude": {"low", "medium", "high", "xhigh", "max"},
+}
+
+TIER_DESCRIPTIONS = {
+    "frontier": "Highest-capability specialist for hard, high-impact work and deep review.",
+    "helm": "Primary orchestrator for planning, delegation, integration, and final decisions.",
+    "workhorse": "Cost-conscious executor for high-volume implementation and analysis.",
+    "sweep": "Fast, low-cost worker for narrow searches, checks, and mechanical tasks.",
+}
+EFFORT_DESCRIPTIONS = {
+    "low": "Minimize reasoning cost and latency for straightforward work.",
+    "medium": "Use moderate reasoning for routine work with some ambiguity.",
+    "high": "Spend more reasoning on complex implementation and analysis.",
+    "xhigh": "Use deeper reasoning for difficult coordination and high-impact decisions.",
+    "max": "Use the host's strongest standard reasoning mode for frontier work.",
+    "ultra": "Use Codex Ultra for exceptionally deep, divisible frontier work.",
+}
+CUSTOM_PRESET = "__custom__"
+OTHER_MODEL = "__other_model__"
+
+
+@dataclass(frozen=True)
+class MenuOption:
+    value: str
+    label: str
+    description: str
+    enabled: bool = True
+    unavailable_reason: str = ""
+CODEX_POLICIES = {"bypass", "workspace-write", "read-only"}
+CLAUDE_POLICIES = {"acceptEdits", "auto", "bypassPermissions", "manual", "dontAsk", "plan"}
+REVIEW_SETUPS = {
+    "none": {
+        "label": "None",
+        "requirements": {"codex": (), "claude": ()},
+        "contract": "No additional review route requested.",
+    },
+    "native-panel": {
+        "label": "Native panel",
+        "requirements": {"codex": (), "claude": ()},
+        "contract": "Use native multi-perspective subagents when review gates fire.",
+    },
+    "onto": {
+        "label": "onto-mcp",
+        "requirements": {"codex": ("onto",), "claude": ("onto",)},
+        "contract": "Use onto-mcp as the structured review lens when review gates fire.",
+    },
+    "ultracode": {
+        "label": "Ultracode",
+        "requirements": {"codex": ("ultracode",), "claude": ("ultracode",)},
+        "contract": (
+            "Run the configured Ultracode CLI as a Codex-backed review route when "
+            "review gates fire."
+        ),
+    },
+    "hybrid": {
+        "label": "Hybrid",
+        "requirements": {
+            "codex": ("onto", "ultracode"),
+            "claude": ("onto", "ultracode"),
+        },
+        "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.",
+        },
+    },
+}
+
+# Each review setup decomposes into review routes. "native" is same-model
+# multi-perspective subagent review (needs delegation); "onto"/"ultracode" are
+# external routes gated on a resolvable capability command. A missing external
+# route degrades to native instead of failing closed; only the delegation
+# contradiction (native required with delegation off) stays fail-closed.
+REVIEW_ROUTES = {
+    "none": (),
+    "native-panel": ("native",),
+    "onto": ("onto",),
+    "ultracode": ("ultracode",),
+    "hybrid": ("onto", "native", "ultracode"),
+}
+ROUTE_LABELS = {
+    "native": "native same-model multi-perspective review",
+    "onto": "onto structured-lens review",
+    "ultracode": "Codex-backed Ultracode review",
+}
+# review_family selects whether review runs on the opposite model family (cross,
+# the default) or the same family as the main (same, today's projection).
+REVIEW_FAMILIES = {"cross", "same"}
+# onto llmOverride provider enum (onto MCP tool schema, settings-chain).
+ONTO_PROVIDERS = {"openai", "anthropic", "grok", "lmstudio"}
+# The opposite model family for cross review, keyed on the launch host.
+REVIEW_HOST = {"codex": "claude", "claude": "codex"}
+
+
+class LaunchError(RuntimeError):
+    pass
+
+
+class BackRequested(RuntimeError):
+    pass
+
+
+def resolve_command(value: str) -> str:
+    expanded = os.path.expanduser(value)
+    if os.path.sep in expanded:
+        command = expanded if pathlib.Path(expanded).is_file() and os.access(expanded, os.X_OK) else None
+    else:
+        command = shutil.which(expanded)
+    if not command:
+        raise LaunchError(f"executable not found: {value}")
+    return command
+
+
+def expand_config_path(value: str) -> pathlib.Path:
+    codex_home = os.environ.get("CODEX_HOME", str(pathlib.Path.home() / ".codex"))
+    expanded = value.replace("${CODEX_HOME}", codex_home)
+    return pathlib.Path(os.path.expandvars(os.path.expanduser(expanded)))
+
+
+def exec_backend(command: str, args: list[str], env: dict[str, str] | None = None) -> NoReturn:
+    os.execve(command, [command, *args], os.environ.copy() if env is None else env)
+
+
+def default_config_path() -> pathlib.Path:
+    explicit = os.environ.get("AGENT_LAUNCH_CONFIG")
+    if explicit:
+        return pathlib.Path(explicit).expanduser()
+    installed = pathlib.Path.home() / ".config/agent-launch/profiles.toml"
+    if installed.is_file():
+        return installed
+    return pathlib.Path(__file__).resolve().parent.parent / "config/agent-launch.toml"
+
+
+def load_config(path: pathlib.Path) -> dict[str, Any]:
+    try:
+        data = tomllib.loads(path.read_text())
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise LaunchError(f"cannot load config {path}: {exc}") from exc
+    if type(data.get("schema_version")) is not int or data["schema_version"] != 1:
+        raise LaunchError(f"unsupported schema_version in {path}")
+    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}]")
+    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}")
+    onto = capabilities.get("onto")
+    if onto is not None and (
+        not isinstance(onto.get("command"), str) or not onto["command"]
+    ):
+        raise LaunchError("capabilities.onto.command must be a non-empty string")
+    ultracode = capabilities.get("ultracode")
+    if ultracode is not None and (
+        not isinstance(ultracode.get("command"), str) or not ultracode["command"]
+    ):
+        raise LaunchError("capabilities.ultracode.command must be a non-empty string")
+    for host_name, host_data in data["hosts"].items():
+        if not isinstance(host_data, dict):
+            raise LaunchError(f"host must be a table: {host_name}")
+        models = host_data.get("models")
+        if models is not None and (
+            not isinstance(models, list)
+            or not models
+            or not all(isinstance(model, str) and model for model in models)
+        ):
+            raise LaunchError(
+                f"hosts.{host_name}.models must be a non-empty list of strings"
+            )
+        onto_review = host_data.get("onto_review")
+        if onto_review is not None:
+            if not isinstance(onto_review, dict):
+                raise LaunchError(f"hosts.{host_name}.onto_review must be a table")
+            if onto_review.get("provider") not in ONTO_PROVIDERS:
+                choices = ", ".join(sorted(ONTO_PROVIDERS))
+                raise LaunchError(
+                    f"hosts.{host_name}.onto_review.provider must be one of: {choices}"
+                )
+            if not isinstance(onto_review.get("model"), str) or not onto_review["model"]:
+                raise LaunchError(
+                    f"hosts.{host_name}.onto_review.model must be a non-empty string"
+                )
+    for name, preset in data["presets"].items():
+        if not isinstance(preset, dict):
+            raise LaunchError(f"preset must be a table: {name}")
+        label = preset.get("label")
+        if not isinstance(label, str) or not label:
+            raise LaunchError(f"presets.{name}.label must be a non-empty string")
+        description = preset.get("description")
+        if description is not None and (
+            not isinstance(description, str) or not description
+        ):
+            raise LaunchError(f"presets.{name}.description must be a non-empty string")
+        for field, allowed in (
+            ("codex_execution_policy", CODEX_POLICIES),
+            ("claude_permission_mode", CLAUDE_POLICIES),
+        ):
+            value = preset.get(field)
+            if not isinstance(value, str) or value not in allowed:
+                choices = ", ".join(sorted(allowed))
+                raise LaunchError(f"presets.{name}.{field} must be one of: {choices}")
+        review_family = preset.get("review_family")
+        if review_family is not None and review_family not in REVIEW_FAMILIES:
+            raise LaunchError(f"presets.{name}.review_family must be one of: cross, same")
+    return data
+
+
+def resolve_backend(config: dict[str, Any], host: str) -> tuple[str, list[str]]:
+    try:
+        backend = config["backends"][host]
+        command_value = backend["command"]
+        passthrough_value = backend.get("passthrough_args", [])
+    except (KeyError, TypeError) as exc:
+        raise LaunchError(f"backend is not configured for {host}") from exc
+    if not isinstance(command_value, str) or not command_value:
+        raise LaunchError(f"backend command must be a non-empty string: {host}")
+    command = resolve_command(command_value)
+    if not isinstance(passthrough_value, list) or not all(
+        isinstance(arg, str) for arg in passthrough_value
+    ):
+        raise LaunchError(f"backend passthrough_args must be strings: {host}")
+    return command, passthrough_value
+
+
+def validate_effort(host: str, model: str, effort: Any, context: str) -> str:
+    if not isinstance(effort, str) or effort not in HOST_EFFORTS[host]:
+        raise LaunchError(f"unsupported effort for {context}: {effort!r}")
+    if host == "codex" and model == "gpt-5.6-luna" and effort == "ultra":
+        raise LaunchError(f"unsupported effort for {context}: gpt-5.6-luna/ultra")
+    return effort
+
+
+def _resolves(value: str) -> bool:
+    try:
+        resolve_command(value)
+        return True
+    except LaunchError:
+        return False
+
+
+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."""
+    if plan["review_host"] == "codex":
+        path = expand_config_path("${CODEX_HOME}/bin/codex-run")
+        return str(path) if path.is_file() and os.access(path, os.X_OK) else None
+    try:
+        return resolve_command(plan["review_backend"])
+    except LaunchError:
+        return None
+
+
+def cross_helm_command(plan: dict[str, Any]) -> str | None:
+    """The codex fan-out reviewer wrapper (hybrid), off PATH under CODEX_HOME/bin."""
+    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
+
+
+def cross_ultracode_command(plan: dict[str, Any]) -> str | None:
+    """The cross-family ultracode reviewer command, or None. For a claude main it
+    is the Codex-backed ultracode-for-codex (the $ultracode-for-codex skill); for
+    a codex main it is the claude backend (Claude Code /workflows ultracode)."""
+    if plan["review_host"] == "codex":
+        value = plan.get("capabilities", {}).get("ultracode", {}).get("command", "")
+    else:
+        value = plan["review_backend"]
+    try:
+        return resolve_command(value)
+    except LaunchError:
+        return None
+
+
+def route_availability(plan: dict[str, Any]) -> dict[str, bool]:
+    """Which review routes can run right now. In same-family mode native gates on
+    delegation and onto/ultracode on a resolvable capability. In cross-family mode
+    native/ultracode gate on the opposite-family dispatcher resolving, and onto on
+    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"])}
+        for route, capability in (("onto", "onto"), ("ultracode", "ultracode")):
+            available[route] = _resolves(capabilities.get(capability, {}).get("command", ""))
+        return available
+    onto_ok = _resolves(capabilities.get("onto", {}).get("command", "")) and bool(
+        plan.get("review_onto")
+    )
+    return {
+        "native": cross_native_command(plan) is not None,
+        "onto": onto_ok,
+        "ultracode": cross_ultracode_command(plan) is not None,
+    }
+
+
+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.
+
+    Returns (effective_routes, dropped_routes, floor). In same-family mode this
+    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."""
+    requested = plan["review_setup"]
+    if requested not in REVIEW_ROUTES:
+        raise LaunchError(f"unknown review setup: {requested!r}")
+    wanted = list(REVIEW_ROUTES[requested])
+    available = route_availability(plan)
+    if plan.get("review_family", "cross") == "same":
+        if "native" in wanted and not plan["delegation"]:
+            raise LaunchError(f"review setup {requested!r} requires delegation")
+        effective = [route for route in wanted if available[route]]
+        dropped = [route for route in wanted if not available[route]]
+        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]]
+    dropped = [route for route in wanted if not available[route]]
+    floor = None
+    if not effective and requested != "none":
+        if plan["delegation"]:
+            floor = "native"
+        else:
+            raise LaunchError(
+                f"review setup {requested!r} has no available cross-family route "
+                "and no same-family fallback (delegation off)"
+            )
+    return effective, dropped, floor
+
+
+def setup_summary_lines(plan: dict[str, Any] | None) -> list[str]:
+    if plan is None:
+        return ["No setup selected."]
+    host = plan["host"]
+    execution = (
+        plan["codex_execution_policy"]
+        if host == "codex"
+        else plan["claude_permission_mode"]
+    )
+    lines = [
+        f"Host {host} | Preset {plan['label']}",
+        f"Main {plan['main_tier'].upper()} | Review {plan['review_setup']}",
+        f"Delegation {'on' if plan['delegation'] else 'off'} | Execution {execution}",
+    ]
+    for tier in TIER_ORDER:
+        binding = plan["tiers"][tier]
+        effort = (
+            plan["frontier_effort"] if tier == "frontier" else binding["effort"]
+        )
+        lines.append(f"{tier.upper():<10} {binding['model']} / {effort}")
+    return lines
+
+
+def textual_importable() -> bool:
+    try:
+        import textual  # noqa: F401
+    except Exception:
+        return False
+    return True
+
+
+def venv_python() -> pathlib.Path | None:
+    """Locate a managed venv interpreter that provides textual. AGENT_LAUNCH_VENV
+    overrides the default install location."""
+    roots = []
+    override = os.environ.get("AGENT_LAUNCH_VENV")
+    if override:
+        roots.append(pathlib.Path(override))
+    roots.append(pathlib.Path.home() / ".local/share/agent-launch/venv")
+    for root in roots:
+        interpreter = root.expanduser() / "bin" / "python"
+        if interpreter.is_file() and os.access(interpreter, os.X_OK):
+            return interpreter
+    return None
+
+
+def maybe_reexec_into_venv() -> None:
+    """When textual is not importable under the current interpreter, re-exec once
+    into the managed venv that provides it. Guarded against infinite re-exec and
+    only ever reached on the interactive TUI path, so direct/non-TTY launches keep
+    running under the system interpreter."""
+    if os.environ.get("AGENT_LAUNCH_REEXEC") == "1":
+        return
+    interpreter = venv_python()
+    if interpreter is None:
+        return
+    env = os.environ.copy()
+    env["AGENT_LAUNCH_REEXEC"] = "1"
+    os.execve(str(interpreter), [str(interpreter), *sys.argv], env)
+
+
+# --- Textual preflight UI (optional; the numbered fallback covers its absence) ---
+# select_plan/customize call the same choose()/prompt_text() seam regardless of
+# renderer. TextualUI drives Textual screens from a worker thread via
+# call_from_thread(push_screen_wait), preserving the synchronous controller flow
+# and its BackRequested/KeyboardInterrupt contract.
+
+_UI_BACK = "\x00back"
+_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.screen import ModalScreen
+    from textual.widgets import Input, OptionList, Static
+    from textual.widgets.option_list import Option
+    from textual.theme import Theme
+
+    # 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
+    # appearance theme (accent #339cff, surface #181818, diff #40c977/#fa423e),
+    # Claude from its binary's dark palette (coral #da7756, surface #1a1a19,
+    # ink scale #f9f9f7 / #c3c2b7 / #898781, grid #2c2c2a).
+    host_themes = {
+        "codex": Theme(
+            name="codex", primary="#339cff", secondary="#ad7bf9",
+            accent="#5fb0ff", foreground="#ffffff", background="#141414",
+            surface="#181818", panel="#222222", success="#40c977",
+            warning="#e6a700", error="#fa423e", dark=True,
+        ),
+        "claude": Theme(
+            name="claude", primary="#da7756", secondary="#c3c2b7",
+            accent="#da7756", foreground="#f9f9f7", background="#0d0d0d",
+            surface="#1a1a19", panel="#2c2c2a", success="#0ca30c",
+            warning="#fab219", error="#e06c6c", dark=True,
+        ),
+    }
+
+    app_css = """
+    Screen { background: $surface; }
+    #al-title { color: $accent; text-style: bold; padding: 0 1; }
+    #al-setup {
+        border: round $primary; border-title-color: $primary;
+        border-title-style: bold; padding: 0 1; height: auto;
+    }
+    #al-detail {
+        border: round $secondary; border-title-color: $secondary;
+        border-title-style: bold; padding: 0 1; height: 5;
+    }
+    #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; }
+    Input { margin: 0 1; }
+    """
+
+    def setup_panel(plan):
+        panel = Static("\n".join(setup_summary_lines(plan)), id="al-setup")
+        panel.border_title = "Current setup"
+        return panel
+
+    class MenuScreen(ModalScreen):
+        BINDINGS = [
+            Binding("escape", "back", "back", priority=True),
+            Binding("q", "cancel", "cancel", priority=True),
+            Binding("ctrl+c", "cancel", "cancel", priority=True),
+        ]
+
+        def __init__(self, title, options, default, allow_back, plan, preview=None):
+            super().__init__()
+            self._title = title
+            self._options = options
+            self._default = default
+            self._allow_back = allow_back
+            self._plan = plan
+            self._preview = preview
+
+        def compose(self):
+            yield Static(self._title, id="al-title")
+            yield setup_panel(self._plan)
+            detail = Static("", id="al-detail")
+            detail.border_title = "About highlighted option"
+            yield detail
+            yield Static(
+                f"Options (1-{len(self._options)} of {len(self._options)})", id="al-hdr"
+            )
+            option_list = OptionList()
+            for option in self._options:
+                label = option.label + ("" if option.enabled else "  [unavailable]")
+                option_list.add_option(
+                    Option(label, id=option.value, disabled=not option.enabled)
+                )
+            yield option_list
+            footer = (
+                "Up/Down move | Enter select | Esc back | q cancel"
+                if self._allow_back
+                else "Up/Down move | Enter select | Esc cancel | q cancel"
+            )
+            yield Static(footer, id="al-footer")
+
+        def on_mount(self):
+            option_list = self.query_one(OptionList)
+            index = next(
+                (
+                    position
+                    for position, option in enumerate(self._options)
+                    if option.value == self._default and option.enabled
+                ),
+                next(
+                    (
+                        position
+                        for position, option in enumerate(self._options)
+                        if option.enabled
+                    ),
+                    0,
+                ),
+            )
+            option_list.highlighted = index
+            option_list.focus()
+            self._describe(index)
+
+        def on_option_list_option_highlighted(self, event):
+            self._describe(event.option_index)
+
+        def _describe(self, index):
+            option = self._options[index]
+            detail = option.description
+            if not option.enabled and option.unavailable_reason:
+                detail = f"{detail} Unavailable: {option.unavailable_reason}"
+            self.query_one("#al-detail", Static).update(detail)
+            # Live-preview the highlighted option's effect in the setup panel.
+            if self._preview is not None:
+                try:
+                    preview_plan = self._preview(option.value)
+                    self.query_one("#al-setup", Static).update(
+                        "\n".join(setup_summary_lines(preview_plan))
+                    )
+                except Exception:
+                    pass
+
+        def on_option_list_option_selected(self, event):
+            self.dismiss(event.option.id)
+
+        def action_back(self):
+            self.dismiss(_UI_BACK if self._allow_back else _UI_CANCEL)
+
+        def action_cancel(self):
+            self.dismiss(_UI_CANCEL)
+
+    class InputScreen(ModalScreen):
+        BINDINGS = [
+            Binding("escape", "cancel", "cancel", priority=True),
+            Binding("ctrl+c", "cancel", "cancel", priority=True),
+        ]
+
+        def __init__(self, label, default, plan):
+            super().__init__()
+            self._label = label
+            self._default = default
+            self._plan = plan
+
+        def compose(self):
+            yield Static(self._label, id="al-title")
+            yield setup_panel(self._plan)
+            box = Static(
+                f"Current value: {self._default}\n"
+                "New value (leave blank to keep current):",
+                id="al-detail",
+            )
+            box.border_title = "Edit model"
+            yield box
+            yield Static("", id="al-hdr")
+            yield Input(placeholder="type a model id, or leave blank to keep current")
+            yield Static(
+                "Enter confirm | Esc/Ctrl-C cancel | q + Enter cancel", id="al-footer"
+            )
+
+        def on_mount(self):
+            self.query_one(Input).focus()
+
+        def on_input_submitted(self, event):
+            value = event.value.strip()
+            if value.lower() == "q":
+                self.dismiss(_UI_CANCEL)
+            else:
+                self.dismiss(value or self._default)
+
+        def action_cancel(self):
+            self.dismiss(_UI_CANCEL)
+
+    class PreflightApp(App):
+        ENABLE_COMMAND_PALETTE = False
+        CSS = app_css
+        BINDINGS = [Binding("ctrl+q", "noop", show=False)]
+
+        def __init__(self, config, host, preset_name, custom_requested, config_path):
+            super().__init__()
+            self._flow_args = (config, host, preset_name, custom_requested, config_path)
+            self._host = host
+            self.outcome = None
+
+        def action_noop(self):
+            pass
+
+        def on_mount(self):
+            theme = host_themes.get(self._host)
+            if theme is not None:
+                self.register_theme(theme)
+                self.theme = theme.name
+            self.run_flow()
+
+        @work(thread=True)
+        def run_flow(self):
+            config, host, preset_name, custom_requested, config_path = self._flow_args
+            ui = TextualUI(self, MenuScreen, InputScreen)
+            try:
+                self.outcome = (
+                    "plan",
+                    select_plan(
+                        config, host, preset_name, custom_requested, ui, config_path
+                    ),
+                )
+            except BaseException as exc:  # surfaced to main; re-raised for the exit code
+                self.outcome = ("error", exc)
+            finally:
+                self.call_from_thread(self.exit)
+
+    return PreflightApp
+
+
+class TextualUI:
+    def __init__(self, app, menu_screen, input_screen):
+        self.app = app
+        self._menu_screen = menu_screen
+        self._input_screen = input_screen
+        self.plan: dict[str, Any] | None = None
+
+    def set_plan(self, plan: dict[str, Any]) -> None:
+        self.plan = plan
+
+    def choose(
+        self,
+        title: str,
+        options: list[MenuOption],
+        default: str,
+        allow_back: bool,
+        preview=None,
+    ) -> str:
+        result = self.app.call_from_thread(
+            self.app.push_screen_wait,
+            self._menu_screen(title, options, default, allow_back, self.plan, preview),
+        )
+        if result == _UI_BACK:
+            raise BackRequested
+        if result == _UI_CANCEL:
+            raise KeyboardInterrupt
+        return result
+
+    def prompt_text(self, label: str, default: str) -> str:
+        result = self.app.call_from_thread(
+            self.app.push_screen_wait,
+            self._input_screen(label, default, self.plan),
+        )
+        if result == _UI_CANCEL:
+            raise KeyboardInterrupt
+        return result
+
+
+def run_textual_flow(
+    config: dict[str, Any],
+    host: str,
+    preset_name: str | None,
+    custom_requested: bool,
+    config_path: pathlib.Path,
+) -> dict[str, Any]:
+    app = _build_app_class()(config, host, preset_name, custom_requested, config_path)
+    app.run()
+    if app.outcome is None:
+        raise KeyboardInterrupt
+    kind, value = app.outcome
+    if kind == "error":
+        raise value
+    return value
+
+
+def choose_lines(
+    title: str, options: list[MenuOption], default: str, allow_back: bool
+) -> str:
+    print(f"\n{title}")
+    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}")
+        if not option.enabled:
+            print(f"     Unavailable: {option.unavailable_reason}")
+    while True:
+        actions = "b back | q cancel" if allow_back else "q cancel"
+        raw = read_input(f"Select [{default}] ({actions}): ").strip()
+        if not raw:
+            default_option = next((option for option in options if option.value == default), None)
+            if default_option and default_option.enabled:
+                return default
+            reason = default_option.unavailable_reason if default_option else "unknown option"
+            print(f"Unavailable: {reason}. Select an enabled option.")
+            continue
+        if raw.lower() in {"q", "quit"}:
+            raise KeyboardInterrupt
+        if raw.lower() in {"b", "back"}:
+            if allow_back:
+                raise BackRequested
+            print("No previous menu. Use q to cancel.")
+            continue
+        if raw.isdigit() and 1 <= int(raw) <= len(options):
+            option = options[int(raw) - 1]
+            if option.enabled:
+                return option.value
+            print(f"Unavailable: {option.unavailable_reason}")
+
+
+def choose(
+    title: str,
+    options: list[MenuOption],
+    default: str,
+    ui: TextualUI | None = None,
+    allow_back: bool = False,
+    preview=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)
+
+
+def read_input(prompt: str) -> str:
+    try:
+        return input(prompt)
+    except EOFError as exc:
+        raise LaunchError(
+            "interactive input ended; use --preset NAME for a non-interactive configured launch"
+        ) from exc
+
+
+def prompt_text(label: str, default: str, ui: TextualUI | None = None) -> str:
+    if ui is not None:
+        return ui.prompt_text(label, default)
+    value = read_input(f"{label} [{default}] (q cancel): ").strip()
+    if value.lower() == "q":
+        raise KeyboardInterrupt
+    return value or default
+
+
+def host_models(config: dict[str, Any], host: str, tiers: dict[str, Any]) -> list[str]:
+    """Selectable model catalog for a host: the configured [hosts.<host>].models
+    list when present, else the distinct models already bound to the tiers."""
+    models = config["hosts"][host].get("models")
+    if models:
+        return list(models)
+    catalog: list[str] = []
+    for tier in TIER_ORDER:
+        model = tiers[tier]["model"]
+        if model not in catalog:
+            catalog.append(model)
+    return catalog
+
+
+def build_plan(config: dict[str, Any], host: str, preset_name: str) -> dict[str, Any]:
+    try:
+        preset = copy.deepcopy(config["presets"][preset_name])
+        tiers = copy.deepcopy(config["hosts"][host]["tiers"])
+    except (KeyError, TypeError) as exc:
+        raise LaunchError(f"invalid preset or host binding: {host}/{preset_name}") from exc
+    if not isinstance(preset, dict) or not isinstance(tiers, dict):
+        raise LaunchError(f"invalid preset or host binding: {host}/{preset_name}")
+    if set(tiers) != set(TIER_ORDER):
+        raise LaunchError(f"{host} tiers must be exactly: {', '.join(TIER_ORDER)}")
+    for tier, binding in tiers.items():
+        if not isinstance(binding, dict):
+            raise LaunchError(f"invalid binding: {host}.{tier}")
+        model = binding.get("model")
+        if not isinstance(model, str) or not model:
+            raise LaunchError(f"invalid binding: {host}.{tier}")
+        validate_effort(host, model, binding.get("effort"), f"{host}.{tier}")
+    all_overrides = preset.get("tier_overrides", {})
+    if not isinstance(all_overrides, dict):
+        raise LaunchError(f"tier_overrides must be a table in preset {preset_name}")
+    host_overrides = all_overrides.get(host, {})
+    if not isinstance(host_overrides, dict):
+        raise LaunchError(f"tier_overrides.{host} must be a table in preset {preset_name}")
+    for tier, override in host_overrides.items():
+        if tier not in tiers:
+            raise LaunchError(f"unknown tier in {preset_name}.tier_overrides.{host}: {tier}")
+        if not isinstance(override, dict):
+            raise LaunchError(f"tier override must be a table: {preset_name}.tier_overrides.{host}.{tier}")
+        override_model = override.get("model", tiers[tier]["model"])
+        if not isinstance(override_model, str) or not override_model:
+            raise LaunchError(f"invalid override model: {preset_name}.tier_overrides.{host}.{tier}")
+        override_effort = override.get("effort", tiers[tier]["effort"])
+        validate_effort(host, override_model, override_effort, f"{preset_name}.tier_overrides.{host}.{tier}")
+        tiers[tier] = {"model": override_model, "effort": override_effort}
+    main_tier = preset.get("main_tier")
+    if not isinstance(main_tier, str) or main_tier not in tiers:
+        raise LaunchError(f"invalid main_tier in preset {preset_name}: {main_tier}")
+    frontier_effort = preset.get("frontier_effort", tiers["frontier"]["effort"])
+    if isinstance(frontier_effort, dict):
+        frontier_effort = frontier_effort.get(host)
+    validate_effort(host, tiers["frontier"]["model"], frontier_effort, f"{preset_name}.frontier")
+    delegation = preset.get("delegation", True)
+    if not isinstance(delegation, bool):
+        raise LaunchError(f"delegation must be boolean in preset {preset_name}")
+    review_setup = preset.get("review_setup", "none")
+    if not isinstance(review_setup, str) or review_setup not in REVIEW_SETUPS:
+        raise LaunchError(f"unknown review setup in preset {preset_name}: {review_setup!r}")
+    codex_policy = preset.get("codex_execution_policy")
+    claude_policy = preset.get("claude_permission_mode")
+    if not isinstance(codex_policy, str) or codex_policy not in CODEX_POLICIES:
+        raise LaunchError(f"invalid Codex policy in preset {preset_name}: {codex_policy!r}")
+    if not isinstance(claude_policy, str) or claude_policy not in CLAUDE_POLICIES:
+        raise LaunchError(f"invalid Claude policy in preset {preset_name}: {claude_policy!r}")
+    label = preset.get("label", preset_name)
+    if not isinstance(label, str) or not label:
+        raise LaunchError(f"invalid label in preset {preset_name}")
+    review_family = preset.get("review_family", "cross")
+    review_host = REVIEW_HOST[host]
+    opposite = config.get("hosts", {}).get(review_host)
+    opposite_backend = config.get("backends", {}).get(review_host, {})
+    if (
+        not isinstance(opposite, dict)
+        or not isinstance(opposite.get("tiers"), dict)
+        or not isinstance(opposite_backend, dict)
+        or not opposite_backend.get("command")
+    ):
+        # Cross review needs the opposite host + backend; without them fall back to
+        # same-family review (surfaced as review_family=same) rather than crashing.
+        review_family = "same"
+        review_tiers, review_onto, review_backend = {}, None, ""
+    else:
+        review_tiers = copy.deepcopy(opposite["tiers"])
+        review_onto = copy.deepcopy(opposite.get("onto_review"))
+        review_backend = opposite_backend["command"]
+    return {
+        "host": host,
+        "preset": preset_name,
+        "label": label,
+        "description": preset.get("description", f"Launch the {label} preset."),
+        "main_tier": main_tier,
+        "frontier_effort": frontier_effort,
+        "review_setup": review_setup,
+        "delegation": delegation,
+        "codex_execution_policy": codex_policy,
+        "claude_permission_mode": claude_policy,
+        "tiers": tiers,
+        "available_models": host_models(config, host, tiers),
+        "review_family": review_family,
+        "review_host": review_host,
+        "review_tiers": review_tiers,
+        "review_onto": review_onto,
+        "review_backend": review_backend,
+        "agent_templates": copy.deepcopy(config["hosts"][host].get("agent_templates")),
+        "capabilities": copy.deepcopy(config.get("capabilities", {})),
+    }
+
+
+def review_description(host: str, name: str) -> str:
+    contract = REVIEW_SETUPS[name]["contract"]
+    return contract[host] if isinstance(contract, dict) else contract
+
+
+def effort_options(host: str, model: str) -> list[MenuOption]:
+    options = []
+    for effort in EFFORT_ORDER:
+        enabled = effort in HOST_EFFORTS[host]
+        reason = f"not supported by {host}" if not enabled else ""
+        if enabled and host == "codex" and model == "gpt-5.6-luna" and effort == "ultra":
+            enabled = False
+            reason = "not supported by gpt-5.6-luna"
+        options.append(
+            MenuOption(effort, effort, EFFORT_DESCRIPTIONS[effort], enabled, reason)
+        )
+    return options
+
+
+def model_options(plan: dict[str, Any]) -> list[MenuOption]:
+    options = [
+        MenuOption(model, model, f"Use {model} as this tier's model.")
+        for model in plan["available_models"]
+    ]
+    options.append(
+        MenuOption(
+            OTHER_MODEL,
+            "Other (enter a model id)",
+            "Type any model id the backend accepts, even if it is not in the catalog.",
+        )
+    )
+    return options
+
+
+def valid_preset_name(name: str) -> bool:
+    return bool(name) and name[0].isalnum() and all(
+        character.isalnum() or character in "-_" for character in name
+    )
+
+
+def preset_from_plan(
+    plan: dict[str, Any], config: dict[str, Any], name: str
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Project the plan into a saveable named preset plus host-scoped tier
+    overrides. Only tier bindings that differ from the host defaults are recorded,
+    scoped to the plan's host so the preset stays correct on the other host, which
+    falls back to its own defaults."""
+    host = plan["host"]
+    default_tiers = config["hosts"][host]["tiers"]
+    fields = {
+        "label": name,
+        "description": "Saved custom launch setup.",
+        "main_tier": plan["main_tier"],
+        "review_setup": plan["review_setup"],
+        "review_family": plan.get("review_family", "cross"),
+        "delegation": plan["delegation"],
+        "codex_execution_policy": plan["codex_execution_policy"],
+        "claude_permission_mode": plan["claude_permission_mode"],
+    }
+    overrides: dict[str, dict[str, str]] = {}
+    for tier in TIER_ORDER:
+        override: dict[str, str] = {}
+        if plan["tiers"][tier]["model"] != default_tiers[tier]["model"]:
+            override["model"] = plan["tiers"][tier]["model"]
+        if tier_effort(plan, tier) != default_tiers[tier]["effort"]:
+            override["effort"] = tier_effort(plan, tier)
+        if override:
+            overrides[tier] = override
+    return fields, ({host: overrides} if overrides else {})
+
+
+def _toml_scalar(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False)
+    raise LaunchError(f"cannot serialize preset value: {value!r}")
+
+
+def render_preset_block(
+    name: str, fields: dict[str, Any], tier_overrides: dict[str, Any]
+) -> str:
+    lines = [f"[presets.{name}]"]
+    for key, value in fields.items():
+        lines.append(f"{key} = {_toml_scalar(value)}")
+    for host, tiers in tier_overrides.items():
+        for tier, override in tiers.items():
+            lines.append("")
+            lines.append(f"[presets.{name}.tier_overrides.{host}.{tier}]")
+            for key, value in override.items():
+                lines.append(f"{key} = {_toml_scalar(value)}")
+    return "\n".join(lines) + "\n"
+
+
+def remove_preset_block(text: str, name: str) -> str:
+    """Drop an existing [presets.<name>] table and its sub-tables, leaving the
+    rest of the file (other presets, comments, host bindings) intact."""
+    exact = f"[presets.{name}]"
+    sub_prefix = f"[presets.{name}."
+    kept = []
+    skipping = False
+    for line in text.splitlines(keepends=True):
+        header = line.strip()
+        if header.startswith("["):
+            skipping = header == exact or header.startswith(sub_prefix)
+        if skipping:
+            continue
+        kept.append(line)
+    return "".join(kept)
+
+
+def save_preset(
+    plan: dict[str, Any], config: dict[str, Any], config_path: pathlib.Path, name: str
+) -> None:
+    if not valid_preset_name(name):
+        raise LaunchError(
+            "preset name must start alphanumeric and use only letters, digits, '-' or '_'"
+        )
+    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")
+    try:
+        temporary.write_text(text)
+        os.replace(temporary, config_path)
+    except OSError as exc:
+        raise LaunchError(f"cannot save preset to {config_path}: {exc}") from exc
+
+
+def customize(
+    plan: dict[str, Any],
+    config: dict[str, Any],
+    config_path: pathlib.Path,
+    ui: TextualUI | None = None,
+) -> None:
+    tier_options = [
+        MenuOption(tier, tier.upper(), TIER_DESCRIPTIONS[tier]) for tier in TIER_ORDER
+    ]
+    available_routes = route_availability(plan)
+    cross = plan.get("review_family", "cross") == "cross"
+    review_options = []
+    for name, spec in REVIEW_SETUPS.items():
+        description = review_description(plan["host"], name)
+        if cross and name != "none":
+            description = f"Runs cross-family on {plan['review_host']} models. {description}"
+        missing = [
+            route
+            for route in REVIEW_ROUTES[name]
+            if route in ("onto", "ultracode") and not available_routes[route]
+        ]
+        if missing:
+            note = "degrades to same-family native (PROPOSED)" if cross else "degrades to native"
+            description = f"{description} ({', '.join(missing)} unavailable now; {note})"
+        review_options.append(MenuOption(name, spec["label"], description))
+    if plan["host"] == "codex":
+        policies = [
+            MenuOption(
+                "bypass",
+                "Bypass approvals and sandbox",
+                "Run without Codex approval or sandbox restrictions.",
+            ),
+            MenuOption(
+                "workspace-write",
+                "Workspace write sandbox",
+                "Allow workspace writes under Codex's workspace-write sandbox.",
+            ),
+            MenuOption(
+                "read-only",
+                "Read-only sandbox",
+                "Allow inspection while blocking file writes through the Codex sandbox.",
+            ),
+        ]
+        policy_field = "codex_execution_policy"
+        policy_title = "Codex execution policy"
+    else:
+        policies = [
+            MenuOption(
+                "bypassPermissions",
+                "Bypass permissions",
+                "Skip Claude permission prompts; this is not an OS sandbox setting.",
+            ),
+            MenuOption(
+                "acceptEdits",
+                "Accept edits",
+                "Automatically accept file edits while retaining other permission checks.",
+            ),
+            MenuOption(
+                "auto",
+                "Auto permissions",
+                "Use Claude's automatic permission mode.",
+            ),
+            MenuOption(
+                "manual",
+                "Manual permissions",
+                "Ask before actions according to Claude's manual permission flow.",
+            ),
+            MenuOption(
+                "dontAsk",
+                "Do not ask",
+                "Use Claude's dontAsk permission mode.",
+            ),
+            MenuOption(
+                "plan",
+                "Plan mode",
+                "Start Claude in planning mode without direct implementation.",
+            ),
+        ]
+        policy_field = "claude_permission_mode"
+        policy_title = "Claude permission mode (not an OS sandbox)"
+    selected_action = "main"
+    while True:
+        policy_label = next(
+            option.label for option in policies if option.value == plan[policy_field]
+        )
+        hub_options = [
+            MenuOption(
+                "main",
+                f"Main tier: {plan['main_tier'].upper()}",
+                "Choose the primary orchestrator used for this session.",
+            ),
+            MenuOption(
+                "review",
+                f"Review setup: {REVIEW_SETUPS[plan['review_setup']]['label']}",
+                "Choose the review routes requested when review gates fire.",
+            ),
+            MenuOption(
+                "policy",
+                f"Execution policy: {policy_label}",
+                "Choose the host-specific permission or sandbox behavior.",
+            ),
+        ]
+        for tier in TIER_ORDER:
+            binding = plan["tiers"][tier]
+            hub_options.append(
+                MenuOption(
+                    f"tier:{tier}",
+                    f"{tier.upper()}: {binding['model']} / {tier_effort(plan, tier)}",
+                    f"Edit the {tier.upper()} model and reasoning effort, then return here.",
+                )
+            )
+        hub_options += [
+            MenuOption(
+                "save",
+                "Save these settings globally and start",
+                "Save this setup as a named preset in your user config for reuse elsewhere, then launch.",
+            ),
+            MenuOption(
+                "start",
+                "Start with these settings",
+                "Confirm the complete setup shown above and continue to launch.",
+            ),
+            MenuOption(
+                "exit",
+                "Exit without launching",
+                "Discard this launch and return to the shell.",
+            ),
+        ]
+
+        try:
+            action = choose(
+                "Custom settings",
+                hub_options,
+                selected_action,
+                ui,
+                allow_back=True,
+            )
+        except BackRequested:
+            raise
+        selected_action = action
+
+        try:
+            if action == "main":
+                plan["main_tier"] = choose(
+                    "Main tier",
+                    tier_options,
+                    plan["main_tier"],
+                    ui,
+                    allow_back=True,
+                    preview=lambda value: {**plan, "main_tier": value},
+                )
+            elif action == "review":
+                plan["review_setup"] = choose(
+                    "Review setup",
+                    review_options,
+                    plan["review_setup"],
+                    ui,
+                    allow_back=True,
+                    preview=lambda value: {**plan, "review_setup": value},
+                )
+            elif action == "policy":
+                plan[policy_field] = choose(
+                    policy_title,
+                    policies,
+                    plan[policy_field],
+                    ui,
+                    allow_back=True,
+                    preview=lambda value: {**plan, policy_field: value},
+                )
+        except BackRequested:
+            continue
+
+        if action.startswith("tier:"):
+            tier = action.split(":", 1)[1]
+            binding = plan["tiers"][tier]
+            while True:
+                default_model = (
+                    binding["model"]
+                    if binding["model"] in plan["available_models"]
+                    else OTHER_MODEL
+                )
+                try:
+                    chosen_model = choose(
+                        f"{tier.upper()} model",
+                        model_options(plan),
+                        default_model,
+                        ui,
+                        allow_back=True,
+                        preview=lambda value: {
+                            **plan,
+                            "tiers": {
+                                **plan["tiers"],
+                                tier: {
+                                    **binding,
+                                    "model": binding["model"]
+                                    if value == OTHER_MODEL
+                                    else value,
+                                },
+                            },
+                        },
+                    )
+                except BackRequested:
+                    break
+                if chosen_model == OTHER_MODEL:
+                    binding["model"] = prompt_text(
+                        f"{tier.upper()} model", binding["model"], ui
+                    )
+                else:
+                    binding["model"] = chosen_model
+                current_effort = tier_effort(plan, tier)
+                try:
+                    binding["effort"] = choose(
+                        f"{tier.upper()} effort",
+                        effort_options(plan["host"], binding["model"]),
+                        current_effort,
+                        ui,
+                        allow_back=True,
+                        preview=lambda value: {
+                            **plan,
+                            "frontier_effort": value
+                            if tier == "frontier"
+                            else plan["frontier_effort"],
+                            "tiers": {
+                                **plan["tiers"],
+                                tier: {**binding, "effort": value},
+                            },
+                        },
+                    )
+                except BackRequested:
+                    continue
+                break
+            if tier == "frontier":
+                plan["frontier_effort"] = binding["effort"]
+            continue
+
+        if action in ("save", "start"):
+            for tier, binding in plan["tiers"].items():
+                validate_effort(
+                    plan["host"],
+                    binding["model"],
+                    tier_effort(plan, tier),
+                    f"custom.{tier}",
+                )
+            validate_review_setup(plan)
+            if action == "save":
+                name = prompt_text(
+                    "Save as preset name", f"{plan['preset']}-custom", ui
+                )
+                save_preset(plan, config, config_path, name)
+            plan["_launch_confirmed"] = True
+            return
+        if action == "exit":
+            raise KeyboardInterrupt
+
+
+def select_plan(
+    config: dict[str, Any],
+    host: str,
+    preset_name: str | None,
+    custom_requested: bool,
+    ui: TextualUI | None = None,
+    config_path: pathlib.Path | None = None,
+) -> dict[str, Any]:
+    presets = config["presets"]
+    explicit_preset = preset_name
+    show_picker = explicit_preset is None
+    while True:
+        selected_name = explicit_preset
+        selected_custom = custom_requested
+        if show_picker:
+            options = [
+                MenuOption(
+                    name,
+                    data["label"],
+                    data.get("description", f"Launch the {data['label']} preset."),
+                )
+                for name, data in presets.items()
+            ]
+            options.append(
+                MenuOption(
+                    CUSTOM_PRESET,
+                    "Custom",
+                    "Open a settings hub for tiers, review setup, policy, and final confirmation.",
+                )
+            )
+            default = "balanced" if "balanced" in presets else next(iter(presets))
+            if ui is not None:
+                ui.set_plan(build_plan(config, host, default))
+            selected = choose(
+                "Preset",
+                options,
+                default,
+                ui,
+                preview=lambda value: build_plan(
+                    config, host, default if value == CUSTOM_PRESET else value
+                ),
+            )
+            if selected == CUSTOM_PRESET:
+                selected_name = default
+                selected_custom = True
+            else:
+                selected_name = selected
+        if selected_name not in presets:
+            raise LaunchError(f"unknown preset: {selected_name}")
+        plan = build_plan(config, host, selected_name)
+        if selected_custom:
+            plan["label"] = f"Custom ({plan['label']})"
+        if ui is not None:
+            ui.set_plan(plan)
+        if selected_custom:
+            try:
+                customize(plan, config, config_path, ui)
+            except BackRequested:
+                if show_picker:
+                    continue
+                raise KeyboardInterrupt
+        return plan
+
+
+def validate_review_setup(plan: dict[str, Any]) -> None:
+    # Fail-closed only on the delegation contradiction (or an unknown setup); a
+    # missing external capability degrades to native in effective_review rather
+    # than raising here.
+    effective_review(plan)
+
+
+def tier_effort(plan: dict[str, Any], tier: str) -> str:
+    return plan["frontier_effort"] if tier == "frontier" else plan["tiers"][tier]["effort"]
+
+
+def codex_agent_configs(
+    plan: dict[str, Any], materialize: bool
+) -> dict[str, tuple[pathlib.Path, str]]:
+    templates = plan.get("agent_templates")
+    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"):
+        source_value = templates.get(tier)
+        if not isinstance(source_value, str) or not source_value:
+            raise LaunchError(f"Codex agent template missing: {tier}")
+        source = expand_config_path(source_value)
+        try:
+            data = tomllib.loads(source.read_text())
+        except (OSError, tomllib.TOMLDecodeError) as exc:
+            raise LaunchError(f"cannot load Codex agent template {source}: {exc}") from exc
+        description = data.get("description")
+        if not isinstance(description, str) or not description:
+            raise LaunchError(f"Codex agent template requires description: {source}")
+        data["model"] = plan["tiers"][tier]["model"]
+        data["model_reasoning_effort"] = tier_effort(plan, tier)
+        lines = []
+        for key, value in data.items():
+            if not isinstance(value, (str, int, float, bool)):
+                raise LaunchError(f"unsupported Codex agent template value: {source}:{key}")
+            lines.append(f"{key} = {json.dumps(value)}")
+        rendered[tier] = ("\n".join(lines) + "\n", description)
+    digest = hashlib.sha256(
+        json.dumps(rendered, sort_keys=True, separators=(",", ":")).encode()
+    ).hexdigest()[:20]
+    cache_root = pathlib.Path(
+        os.environ.get("XDG_CACHE_HOME", pathlib.Path.home() / ".cache")
+    ) / "agent-launch/codex-agents" / digest
+    if materialize:
+        cache_root.mkdir(parents=True, exist_ok=True)
+    result = {}
+    for tier, (content, description) in rendered.items():
+        target = cache_root / f"{tier}.toml"
+        if materialize and (not target.is_file() or target.read_text() != content):
+            temporary = target.with_name(f".{target.name}.{os.getpid()}.tmp")
+            temporary.write_text(content)
+            temporary.chmod(0o600)
+            os.replace(temporary, target)
+        result[tier] = (target, description)
+    return result
+
+
+def _same_review_route(plan: dict[str, Any], effective: list[str], dropped: list[str]) -> str:
+    requested = plan["review_setup"]
+    if dropped:
+        kept = ", ".join(ROUTE_LABELS[route] for route in effective) or "no additional review route"
+        route = f"{', '.join(dropped)} unavailable at launch; degraded to {kept}."
+    else:
+        route = REVIEW_SETUPS[requested]["contract"]
+        if isinstance(route, dict):
+            route = route[plan["host"]]
+    if "ultracode" in effective:
+        route = f"{route} Ultracode executable: {resolve_command(plan['capabilities']['ultracode']['command'])}."
+    if "ultracode" in REVIEW_ROUTES[requested]:
+        route = (
+            f"{route} If the Codex-backed route is unavailable or unauthenticated "
+            "at use time, fall back to native same-model subagent review."
+        )
+    return route
+
+
+def _cross_review_route(
+    plan: dict[str, Any], effective: list[str], dropped: list[str], floor: str | None
+) -> str:
+    review_host = plan["review_host"]
+    main_family = "Anthropic/Claude" if plan["host"] == "claude" else "OpenAI/Codex"
+    review_family = "OpenAI/Codex" if review_host == "codex" else "Anthropic/Claude"
+    review_bindings = ", ".join(
+        f"{tier}={plan['review_tiers'][tier]['model']}/{plan['review_tiers'][tier]['effort']}"
+        for tier in TIER_ORDER
+        if tier in plan["review_tiers"]
+    )
+    parts = [
+        f"Cross-family review: this main is {main_family}; run EVERY review route on "
+        f"{review_family} ({review_host}) models. Do not use your own same-family "
+        "subagents for primary review — they are the delegation/fallback floor only.",
+        f"Reviewer tier bindings ({review_host}): {review_bindings}.",
+    ]
+    if "native" in effective:
+        native = cross_native_command(plan)
+        if review_host == "codex":
+            helm = cross_helm_command(plan)
+            fanout = f" (or {helm} --mode review for hybrid fan-out)" if helm else ""
+            parts.append(
+                f"native: dispatch {native} --profile hermetic --model <review tier> "
+                f"--effort <e> --sandbox read-only{fanout}, self-contained packet on stdin, "
+                "bounded read-only report."
+            )
+        else:
+            parts.append(
+                f"native: dispatch {native} -p --model <review tier> --effort <e> "
+                "--permission-mode plan --append-system-prompt <read-only reviewer role>, "
+                "self-contained packet, bounded report."
+            )
+    if "onto" in effective:
+        onto = plan["review_onto"]
+        parts.append(
+            f'onto: call onto_review/onto_prepare_review with llmOverride='
+            f'{{"provider":"{onto["provider"]}","model":"{onto["model"]}"}} so onto runs {review_family}.'
+        )
+    if "ultracode" in effective:
+        ultracode = cross_ultracode_command(plan)
+        if review_host == "codex":
+            parts.append(
+                f"ultracode: run {ultracode} (the $ultracode-for-codex Codex skill) "
+                f"for {review_family} workflow-orchestration review."
+            )
+        else:
+            parts.append(
+                f"ultracode: run {ultracode} --effort ultracode -p <self-contained review packet> "
+                f"(Claude Code /workflows ultracode mode, headless) for {review_family} "
+                "workflow-orchestration review."
+            )
+    if dropped:
+        detail = [
+            f"onto (add a [hosts.{review_host}].onto_review pin)"
+            if route == "onto" and not plan.get("review_onto")
+            else route
+            for route in dropped
+        ]
+        parts.append(f"Unavailable cross-family route(s) at launch: {', '.join(detail)}.")
+    if floor == "native":
+        parts.append(
+            "No cross-family route resolved at launch; using same-family native "
+            "subagent review labeled PROPOSED (family collapse)."
+        )
+    parts.append(
+        "Cross-family reviewers are dispatched as read-only subprocesses, not "
+        "CLI-native subagents; spawning them needs this main's execution policy to "
+        "permit subprocesses, so a read-only or restrictive policy blocks the dispatch "
+        "and collapses to same-family native. If a route is unavailable or "
+        "unauthenticated at use time, fall back to native same-model subagent review "
+        "via the configured child agents and label those verdicts PROPOSED (family collapse)."
+    )
+    return " ".join(parts)
+
+
+def run_contract(plan: dict[str, Any]) -> str:
+    bindings = ", ".join(
+        f"{tier}={data['model']}/{tier_effort(plan, tier)}"
+        for tier, data in plan["tiers"].items()
+    )
+    requested = plan["review_setup"]
+    family = plan.get("review_family", "cross")
+    effective, dropped, floor = effective_review(plan)
+    if family == "same":
+        route = _same_review_route(plan, effective, dropped)
+    else:
+        route = _cross_review_route(plan, effective, dropped, floor)
+    authority = (
+        "Main and native child model/effort defaults are config-projected. Use the installed "
+        "codex-run adapter when a separate child root or stricter reach boundary matters."
+        if plan["host"] == "codex"
+        else "Main and child model/effort defaults are CLI-projected."
+    )
+    return (
+        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}. "
+        f"Review setup={requested}: {route} "
+        f"{authority} Forwarded backend arguments are expert overrides and may supersede these "
+        "defaults. Status is configured/requested; completion is not enforced by "
+        "this interactive launcher."
+    )
+
+
+def claude_agents(plan: dict[str, Any]) -> str:
+    roles = {}
+    for tier in TIER_ORDER:
+        binding = plan["tiers"][tier]
+        roles[tier] = {
+            "description": f"{tier.upper()} tier: {binding['model']} at {tier_effort(plan, tier)}",
+            "prompt": (
+                f"Act as the bounded {tier.upper()} role at requested effort "
+                f"{tier_effort(plan, tier)}. Return evidence and verification; stay in scope."
+            ),
+            "model": binding["model"],
+            "effort": tier_effort(plan, tier),
+        }
+    return json.dumps(roles, separators=(",", ":"))
+
+
+def project_args(plan: dict[str, Any], materialize_agents: bool = True) -> list[str]:
+    host = plan["host"]
+    main = plan["tiers"][plan["main_tier"]]
+    main_effort = tier_effort(plan, plan["main_tier"])
+    contract = run_contract(plan)
+    effective_routes, _, _ = effective_review(plan)
+    if host == "codex":
+        args = [
+            "--model", main["model"],
+            "-c", f'model_reasoning_effort="{main_effort}"',
+            "-c", f"developer_instructions={json.dumps(contract)}",
+            "-c", f"features.multi_agent={'true' if plan['delegation'] else 'false'}",
+        ]
+        policy = plan["codex_execution_policy"]
+        policy_args = (
+            ["--dangerously-bypass-approvals-and-sandbox"]
+            if policy == "bypass"
+            else ["--sandbox", policy]
+        )
+        args += policy_args
+        if plan["delegation"]:
+            for tier, (path, description) in codex_agent_configs(plan, materialize_agents).items():
+                args += [
+                    "-c", f"agents.{tier}.description={json.dumps(description)}",
+                    "-c", f"agents.{tier}.config_file={json.dumps(str(path))}",
+                ]
+        if "onto" in effective_routes:
+            onto_command = resolve_command(plan["capabilities"]["onto"]["command"])
+            args += [
+                "-c", "mcp_servers.onto.enabled=true",
+                "-c", f"mcp_servers.onto.command={json.dumps(onto_command)}",
+                "-c", 'mcp_servers.onto.args=["mcp"]',
+            ]
+        return args
+    args = [
+        "--model", main["model"],
+        "--effort", main_effort,
+        "--append-system-prompt", contract,
+    ]
+    if plan["delegation"]:
+        args += ["--agents", claude_agents(plan)]
+    policy = plan["claude_permission_mode"]
+    policy_args = (
+        ["--dangerously-skip-permissions"]
+        if policy == "bypassPermissions"
+        else ["--permission-mode", policy]
+    )
+    args += policy_args
+    if "onto" in effective_routes:
+        onto_command = resolve_command(plan["capabilities"]["onto"]["command"])
+        mcp_config = {
+            "mcpServers": {"onto": {"command": onto_command, "args": ["mcp"]}}
+        }
+        args += [
+            "--mcp-config",
+            json.dumps(mcp_config, separators=(",", ":")),
+        ]
+    return args
+
+
+def print_summary(
+    plan: dict[str, Any],
+    command: str,
+    args: list[str],
+    stream: Any = sys.stdout,
+    forwarded_args: bool = False,
+) -> None:
+    main = plan["tiers"][plan["main_tier"]]
+    print("\nLaunch summary", file=stream)
+    print(f"  Host           {plan['host']}", file=stream)
+    print(f"  Preset         {plan['label']}", file=stream)
+    print(
+        f"  Main           {plan['main_tier'].upper()} · {main['model']} · "
+        f"{tier_effort(plan, plan['main_tier'])}",
+        file=stream,
+    )
+    for tier in TIER_ORDER:
+        binding = plan["tiers"][tier]
+        effort = tier_effort(plan, tier)
+        print(f"  {tier.upper():<14} {binding['model']} · {effort}", file=stream)
+    effective, dropped, floor = effective_review(plan)
+    family = plan.get("review_family", "cross")
+    review_display = plan["review_setup"]
+    if family == "cross":
+        review_display += f" · cross-family review on {plan['review_host']}"
+        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"
+    elif dropped:
+        review_display += (
+            f" → effective {'+'.join(effective) or 'none'} "
+            f"({','.join(dropped)} unavailable)"
+        )
+    print(
+        f"  Review setup   {review_display} · "
+        "configured/requested · completed: not enforced",
+        file=stream,
+    )
+    tier_authority = (
+        "base main + native child model/effort configured"
+        if plan["host"] == "codex"
+        else "base main + child model/effort configured"
+    )
+    print(f"  Tier authority {tier_authority}", file=stream)
+    if forwarded_args:
+        print(
+            "  Overrides      forwarded backend args appended last; may supersede defaults",
+            file=stream,
+        )
+    if plan["host"] == "codex":
+        print(f"  Execution      Codex {plan['codex_execution_policy']}", file=stream)
+    else:
+        print(
+            f"  Execution      Claude {plan['claude_permission_mode']} "
+            "(permission mode, not OS sandbox)",
+            file=stream,
+        )
+    print(f"  Backend        {command}", file=stream)
+    if os.environ.get("AGENT_LAUNCH_DEBUG") == "1":
+        print("  Argv           " + json.dumps([command, *args]), file=stream)
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--config", type=pathlib.Path, default=default_config_path())
+    parser.add_argument(
+        "--no-tui",
+        action="store_true",
+        help="disable the rich terminal preflight; configured-launch flags still apply",
+    )
+    parser.add_argument("--preset", help="launch a named preset without the preset picker")
+    parser.add_argument(
+        "--custom",
+        action="store_true",
+        help="open customization after preset selection",
+    )
+    parser.add_argument("--yes", action="store_true", help="skip launch confirmation")
+    parser.add_argument("--dry-run", action="store_true", help="print projection without launching")
+    parser.add_argument("host", choices=("codex", "claude"))
+    parser.add_argument("forward", nargs=argparse.REMAINDER)
+    args = parser.parse_args(argv)
+    if args.forward[:1] == ["--"]:
+        args.forward = args.forward[1:]
+    return args
+
+
+def main(argv: list[str]) -> int:
+    args = parse_args(argv)
+    config_path = args.config.expanduser()
+    config = load_config(config_path)
+    command, passthrough = resolve_backend(config, args.host)
+    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"]:
+            raise LaunchError(
+                "bare non-TTY --dry-run requires a 'balanced' preset; use --preset NAME"
+            )
+        args.preset = "balanced"
+    bypass = args.no_tui or bool(args.forward) or os.environ.get("AGENT_LAUNCH_TUI") == "0"
+    if (bypass or not tty) and not args.preset and not args.custom and not args.dry_run:
+        exec_backend(command, [*passthrough, *args.forward])
+
+    interactive_setup = not args.preset or args.custom
+    use_textual = (
+        interactive_setup
+        and tty
+        and os.environ.get("TERM", "") not in {"", "dumb"}
+    )
+    if use_textual and not textual_importable():
+        maybe_reexec_into_venv()
+        if not textual_importable():
+            use_textual = False
+            print(
+                "agent-launch: rich terminal UI unavailable; using numbered prompts.",
+                file=sys.stderr,
+            )
+    if use_textual:
+        plan = run_textual_flow(
+            config, args.host, args.preset, args.custom, config_path
+        )
+    else:
+        plan = select_plan(
+            config, args.host, args.preset, args.custom, config_path=config_path
+        )
+    validate_review_setup(plan)
+    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))
+    if args.dry_run:
+        print(json.dumps([command, *projected], ensure_ascii=False))
+        return 0
+    if tty and not args.yes and not plan.get("_launch_confirmed", False):
+        confirmation = read_input("Launch? [Y/n/q]: ").strip().lower()
+        if confirmation in {"n", "no", "q", "quit"}:
+            return 130
+    env = os.environ.copy()
+    env["AGENT_LAUNCH_ACTIVE"] = "1"
+    summary_stream.flush()
+    exec_backend(command, projected, env)
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main(sys.argv[1:]))
+    except LaunchError as exc:
+        print(f"agent-launch: {exc}", file=sys.stderr)
+        raise SystemExit(2)
+    except KeyboardInterrupt:
+        print("\nCancelled.", file=sys.stderr)
+        raise SystemExit(130)