startup.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/startup.py
 
"""
Interactive REPL bootstrap — the session-selection menu and helpers.
 
Purpose
-------
:func:`startup_session_prompt` is the front door the human sees at
``oc_chat`` launch when no session was specified on the command
line: continue the most recently modified session, choose another
saved one, start fresh, or quit. Together with the four internal
helpers (:func:`_load_session_by_meta`,
:func:`_show_history_snippet`, :func:`_ingest_context_file`,
:func:`_create_new_session`) it owns everything that happens
between argparse and the first call to
:func:`oc_chat.core.react_loop.run_turn`.
 
Sub-agents skip all of this — they receive a constructed
:class:`ChatSession` directly. Splitting startup out of
``oc_chat/main.py`` is the single change that makes headless usage
trivial; the upcoming :class:`Agent` abstraction (G.6.C) reuses the
helpers here only when an interactive shell wants them.
 
Responsibilities
----------------
- :func:`startup_session_prompt` — public entry point. Shows the
  startup menu, returns a :class:`ChatSession` ready for the REPL.
- :func:`_load_session_by_meta` — hydrate a saved session
  (metadata + chat log) into a usable :class:`ChatSession`.
- :func:`_show_history_snippet` — print the trailing N user /
  assistant messages as a context-recall aid (currently unused;
  kept for the option to re-enable it on session reload).
- :func:`_read_workspace_file` — read an ``include_files`` entry for
  prompt composition, hardened to the sandbox + protected-read class
  (M8 F73; WU-2b).
- :func:`_create_new_session` — lane/model drill-down, name prompt,
  and :class:`ChatSession` construction.
- :func:`_pick_lane_and_model` — the plan-217 picker as the
  new-session lane/model choice (plan 220 P1); the flat
  ``Available models:`` list it replaces is retired outright.
- :func:`confirm_quit_or_continue` / :func:`_quit_confirmer` /
  :func:`_interruptible` — the pre-session Ctrl+C state machine
  (plan 220 P3).
- :func:`_show_block` — emit a run of lines as ONE section so the
  startup render is single-spaced (plan 220 P2).
- :func:`_render_provider_lanes` / :func:`_lane_rows` — the opening
  menu's provider-lane panel (plan 215 T3): every catalogue-backed
  lane with its FREE/PAID badge, its honest verification tier, and
  its key-availability marker.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 — lifecycle events (menu shown, session loaded / created).
    L3 — semantic details (model selection, name resolution).
    L4 — deep tracing.
 
Contracts
---------
- *version* is passed in by the caller (``main()``) rather than
  resolved here. This keeps :mod:`oc_chat.core.startup` free of an
  inverse dependency on :mod:`oc_chat.main` (where ``_VERSION`` is
  bound at import time today; G.6.C relocates it to
  ``oc_chat/core/_version.py``).
- ``include_files`` ingestion is best-effort and sandbox-clamped
  (M8 F73; WU-2b): a missing / binary / absolute / escaping /
  secret-class file is logged and skipped, never raised and never
  inserted into the provider-bound prompt.
- Quitting the menu (option 4, EOF on the prompt, or a CONFIRMED
  Ctrl+C) raises :class:`SystemExit(0)` — caller's ``except
  SystemExit`` is the intended exit path for OC Chat.
- **No interrupt sequence ends inside a session (plan 220 P3).** A
  Ctrl+C at any pre-session prompt asks ``Quit OC Chat? (y/N)``;
  ``N`` re-shows that same prompt unchanged, ``y`` and a second
  interrupt both exit. Every branch therefore leads either back to
  the prompt the operator interrupted or out of the program — never
  onward — which is the property TUI-02 finding 3 was filed against.
  The in-turn two-stage Ctrl+C machinery
  (:mod:`oc_chat.core.session_transition`, the SIGINT handler) is
  SEPARATE and untouched: it governs a session that already exists.
- **One presenter call per section (plan 220 P2).** Every presenter
  opens ``show_info`` with a blank line, so a menu emitted row by
  row is a double-spaced menu. Sections go through
  :func:`_show_block`; blank lines then separate sections only.
- The plan-215 lane panel is ADDITIVE and duck-typed: it renders
  nothing when no catalogue-backed provider is registered, so a
  deepseek/ollama-only install produces a byte-identical menu.
  ``startup`` never imports a provider bundle, and it reads only the
  PRESENCE of an API-key env var, never its value.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.tools.filesystem (lazy; read_prompt_file — hardened include_files / system_prompt_file read, M8 F73)
- oc_chat.core.persistence (lazy; session metadata and chat-log save/load)
- oc_chat.core.session (ChatSession, CANONICAL_POLICY, helpers)
- oc_chat.core.git_helpers (lazy; branch/status for the messages[1] environment block)
- oc_chat.core.lane_tree (section_text and vendor_detail - single-spaced menu sections and the chosen model's vendor detail)
- oc_ui.terminal.formatting (fmt_model_caps and fmt_tokens_or_size - the model and volume columns of the saved-session tables)
- oc_chat.core.client_interface (lazy; ClientInterface, for type hints only)
- oc_chat.core.external_content_gate (lazy; seed_record_binding - binds a resumed session id to its canonical record)
- oc_chat.core.lane_overlay (lazy; register_overlay_lanes and OverlayError - operator-added overlay lanes at startup)
- oc_chat.core.lane_picker (lazy; run_lane_picker - the lane and model drill-down for a new session and menu option 6)
- oc_chat.core.models (lazy; ModelManager, for type hints only)
- oc_chat.core.prompt_layers (lazy; session_anchors_block - the self-location block injected with the project tree)
- oc_chat.core.provider_plugin (lazy; the provider registry behind the lane panel, and ProviderPlugin for type hints)
- oc_chat.core.provider_secrets (lazy; apply_to_environ - sidecar API keys into the environment before the lane panel renders)
- oc_chat.core.provider_wizard (lazy; run_add_provider_wizard - the Add provider menu entry)
- oc_chat.core.settings (lazy; the active mode profile, runtime settings, mode name and system prompt for new sessions and the variable context)
- oc_ui.presenter_base (lazy; Presenter, for type hints only)
- oc_ui.terminal.input (lazy; read_single_key - single-key menu choices, and PromptDriver for type hints)
- tzlocal (lazy; the optional IANA timezone name for the environment block)
"""
from __future__ import annotations
 
import os
from datetime import datetime
from pathlib import Path
from typing import TYPE_CHECKING
 
from oc_diagnostics import _dbg
 
from oc_chat.core.lane_tree import section_text, vendor_detail
from oc_chat.core.session import (
    ChatSession,
    CANONICAL_POLICY,
    apply_session_metadata_fields,
    build_system_prompt,
    ensure_system_includes_tool_reference,
    _migrate_legacy_system_prompt,
)
from oc_ui.terminal.formatting import fmt_model_caps, fmt_tokens_or_size
 
if TYPE_CHECKING:
    from typing import Callable
 
    from oc_chat.core.client_interface import ClientInterface
    from oc_chat.core.models import ModelManager
    from oc_chat.core.provider_plugin import ProviderPlugin
    from oc_ui.presenter_base import Presenter
    from oc_ui.terminal.input import PromptDriver
 
 
_dbg("OC_CHAT.MAIN", "module", "loaded", 4)
 
 
def _load_session_by_meta(
    meta: dict,
    presenter: "Presenter",
    tool_schemas: list | None = None,
) -> ChatSession:
    """Load a full :class:`ChatSession` from a session metadata dict.
 
    Reads the metadata and the latest chat log to populate messages,
    stats, model, reasoning effort, and associated log paths.
    """
    func = "_load_session_by_meta"
    from oc_chat.core.external_content_gate import seed_record_binding
    from oc_chat.core.persistence import (
        DEFAULT_SESSIONS_DIR, canonical_record_locator, load_chat_log,
    )
    from oc_chat.core.session import TokenStats
 
    name = meta["name"]
    # Plan 135 §3.5/§4.7: set the persisted model via the constructor — model
    # writes go through ChatSession.set_model, never a raw attribute assignment.
    # The variable context is refreshed in place after messages hydrate (below).
    model = meta.get("model")
    session = ChatSession(name=name, model=model) if model else ChatSession(name=name)
    session.reasoning_effort = meta.get("reasoning_effort", session.reasoning_effort)
    session.chat_logs = meta.get("chat_logs", [])
    session.stats = TokenStats.from_dict(meta.get("stats", {}))
    session.filepath = meta.get("filepath", None)
    session.created = name.split("_", 1)[1] if "_" in name else "unknown"
    session.ui_prefs = dict(meta.get("ui", {}) or {})
    apply_session_metadata_fields(session, meta)
    # Plan 152 R11-10 — seed the id -> canonical-record binding at this resume
    # activation site. Without it, a process that starts on a COPIED record and
    # establishes external-content trust would later accept the ORIGINAL record
    # presenting the same id WITHOUT rotating that trust; "a fresh process starts
    # with an empty trust set" stops applying once trust precedes the first live
    # load. This is the one authorised addition here — the metadata call above and
    # its sandbox projection are deliberately unchanged.
    # ``filepath`` is the meta path synthesised by ``list_sessions``; the locator
    # is its owning session DIRECTORY. Fall back to the store path for the bare
    # -metadata callers that carry no filepath. Read-only: nothing is created.
    _record = session.filepath or str(Path(DEFAULT_SESSIONS_DIR) / name)
    seed_record_binding(session.session_id, canonical_record_locator(Path(_record)))
    session.dirty = False
 
    # Load the most-recent chat log inside the session directory.
    try:
        log_data = load_chat_log(name)
        session.messages = log_data.get("messages", session.messages)
    except FileNotFoundError as e:
        # VALIDATION_ERROR — metadata exists but log is missing on disk; start with fresh context
        _dbg("OC_CHAT.MAIN", func, f"VALIDATION_ERROR: {name}: {type(e).__name__}: {e}", 3)
        presenter.show_info(
            f"[Note: Session '{name}' has no chat log on disk. Starting with fresh context.]"
        )
    except Exception as exc:
        # SYSTEM_ERROR — a chat log exists but couldn't be parsed; flag load_failed so saves
        # don't overwrite the on-disk file, then surface to the user.
        _dbg("OC_CHAT.MAIN", func,
             f"SYSTEM_ERROR: parse {name}: {type(exc).__name__}: {exc}", 1, override=True)
        session.load_failed = True
        presenter.show_error(
            f"[Warning: Could not parse chat log for session '{name}' ({exc}). "
            f"On-disk chat log will NOT be overwritten on save until reload succeeds.]"
        )
 
    presenter.show_info(
        f"Loaded session '{name}' — "
        f"{session.stats.message_count} messages, "
        f"{session.stats.tool_call_count} tool calls, "
        f"{session.stats.total_tokens:,} tokens "
        f"(model: {session.model})"
    )
    # Plan 135 §4.3: convert any legacy embedded-schema messages[0] (saved by a
    # pre-135 build) to the slim policy + compact reference, then ensure the
    # reference is present. Both steps are idempotent on already-migrated sessions.
    _migrate_legacy_system_prompt(session, tool_schemas)
    ensure_system_includes_tool_reference(session, tool_schemas)
 
    # Plan 135 §3.5: refresh the loaded variable context IN PLACE (preserves all
    # conversation history; no index-shifting pop + re-append). Inject only when
    # the saved session predates variable context (no sentinel anywhere).
    from oc_chat.core.session import VARIABLE_CONTEXT_SENTINEL
    has_varctx = any(
        m.get("role") == "user"
        and (m.get("content") or "").startswith(VARIABLE_CONTEXT_SENTINEL)
        for m in session.messages
    )
    if has_varctx:
        refresh_variable_context(session)
    else:
        _inject_variable_context(session)
 
    # _show_history_snippet(session, presenter, n=3)
    return session
 
 
def _show_history_snippet(session: ChatSession, presenter: "Presenter", n: int = 3) -> None:
    """Display the last *n* user/assistant messages as a context-recall aid.
 
    Tool messages and system prompts are skipped; very long content is
    truncated to keep the snippet scannable.
    """
    visible = [m for m in session.messages if m.get("role") in ("user", "assistant")]
    if not visible:
        return
    trailing = visible[-n:]
    omitted = len(visible) - len(trailing)
    header = f"(... {omitted} earlier message(s); last {len(trailing)} shown:)" if omitted else \
             f"(showing last {len(trailing)} message(s):)"
    presenter.show_info(f"\n{header}")
    for m in trailing:
        role = m.get("role", "?")
        content = (m.get("content") or "").strip()
        if not content:
            continue
        first_line = content.splitlines()[0]
        if len(first_line) > 100:
            first_line = first_line[:97] + "…"
        label = "You" if role == "user" else "Assistant"
        presenter.show_info(f"  {label:<10} {first_line}")
 
 
def _read_workspace_file(filepath: str) -> str | None:
    """Best-effort read of an ``include_files`` entry for prompt composition.
 
    Hardened to the effective sandbox root + protected-read class (M8 F73; M8.0
    WU-2b): an absolute path, a sandbox escape, or a secret-class file is refused
    and never inserted into the provider-bound prompt. Returns the file's
    (secret-redacted) text, or ``None`` when missing / empty / refused.
    """
    func = "_read_workspace_file"
    try:
        from oc_chat.tools.filesystem import read_prompt_file
        return read_prompt_file(filepath)
    except PermissionError as exc:
        _dbg("OC_CHAT.MAIN", func, f"refused prompt-composition read {filepath!r}: {exc}", 2)
        return None
    except (OSError, UnicodeDecodeError):
        return None
 
 
def _local_tz_name() -> str:
    """Best-effort local timezone name (no fabrication).
 
    Prefers an IANA name via the optional ``tzlocal`` dependency; otherwise
    falls back to the system's local tzname. The ISO datetime in the ``Date:``
    field already carries the numeric UTC offset, so this is supplementary.
    """
    try:  # optional — only if the environment ships tzlocal
        from tzlocal import get_localzone_name  # type: ignore[import-not-found]
 
        name = get_localzone_name()
        if name:
            return name
    except Exception:  # noqa: BLE001 — degrade to the stdlib name, never raise
        pass
    return datetime.now().astimezone().tzname() or "UTC"
 
 
#: Canonical render order for the messages[1] ``## Environment`` block (plan 135
#: §3.5). Rendering follows this order regardless of the mode's ``env_fields``
#: list order so the variable layer stays stable across renders.
_ENV_FIELD_ORDER: tuple[str, ...] = (
    "date", "timezone", "cwd", "branch", "git", "model", "mode",
)
 
 
def _render_environment_block(session: ChatSession, profile: dict) -> str | None:
    """Render the active mode's ``## Environment`` sublayer, or ``None`` (plan 135 §3.5).
 
    Emits only the fields named in the mode's ``env_fields`` (in the canonical
    ``_ENV_FIELD_ORDER``). Volatile facts live here in ``messages[1]`` — never in
    the immutable ``messages[0]`` prefix. Git facts come from :mod:`git_helpers`
    (short-timeout, never raises). Returns ``None`` when ``include_env`` is false
    or no recognised fields are selected.
    """
    func = "_render_environment_block"
    if not profile.get("include_env", False):
        return None
    selected = {str(f).strip() for f in (profile.get("env_fields") or [])}
    if not selected:
        return None
 
    from oc_chat.core.git_helpers import git_current_branch, git_status_summary
    from oc_chat.core.settings import runtime_mode
 
    renderers = {
        "date": lambda: f"Date: {datetime.now().astimezone().replace(microsecond=0).isoformat()}",
        "timezone": lambda: f"Timezone: {_local_tz_name()}",
        "cwd": lambda: f"CWD: {Path.cwd()}",
        "branch": lambda: f"Git branch: {git_current_branch()}",
        "git": lambda: f"Git status: {git_status_summary()}",
        "model": lambda: f"Model: {session.model}",
        "mode": lambda: f"Mode: {runtime_mode()}",
    }
    lines = [renderers[f]() for f in _ENV_FIELD_ORDER if f in selected]
    if not lines:
        _dbg("OC_CHAT.MAIN", func, f"env_fields had no recognised field: {sorted(selected)}", 3)
        return None
    return "## Environment\n" + "\n".join(lines)
 
 
def _compose_variable_context(session: ChatSession) -> str | None:
    """Compose the full ``messages[1]`` content (sentinel + env + tree + files).
 
    Mode-driven (plan 133/135): the active mode's profile decides the optional
    ``## Environment`` block (date/cwd/branch/git/model/mode per ``env_fields``),
    whether to inject the project tree, and which files (``include_files``) to
    ingest. Returns ``None`` when the active mode contributes nothing beyond the
    sentinel (a context-free mode). All volatile facts live here, never in the
    immutable ``messages[0]`` prefix.
    """
    func = "_compose_variable_context"
    from oc_chat.core.session import VARIABLE_CONTEXT_SENTINEL, generate_project_tree
    from oc_chat.core.settings import active_profile, runtime_settings
 
    profile = active_profile()
    settings = runtime_settings()
    parts: list[str] = [VARIABLE_CONTEXT_SENTINEL]
 
    env_block = _render_environment_block(session, profile)
    if env_block:
        parts.append(env_block)
 
    if profile.get("include_project_tree"):
        pt = settings.project_tree
        tree = generate_project_tree(
            max_depth=int(pt.get("max_depth", 2)),
            exclude_dirs=pt.get("exclude_dirs"),
            exclude_suffixes=pt.get("exclude_suffixes"),
            stub_dirs=pt.get("stub_dirs"),
            honor_gitignore=pt.get("honor_gitignore"),
            work_dir=pt.get("work_dir"),
        )
        if tree:
            parts.append(tree)
        # Plan 157 (gate-wired): the session-anchors block rides WITH the
        # project tree — every tree-injecting mode gets self-location (mining
        # finding F8: workers could not answer "where am I?"); context-free
        # modes stay context-free.
        from oc_chat.core.prompt_layers import session_anchors_block
        parts.append(session_anchors_block())
 
    for filepath in (profile.get("include_files") or []):
        filepath = str(filepath).strip()
        if not filepath:
            continue
        content = _read_workspace_file(filepath)
        if content:
            parts.append(f"[{filepath} — auto-ingested at session start]\n\n{content}")
        else:
            _dbg("OC_CHAT.MAIN", func, f"include_files: {filepath!r} not found / empty", 3)
 
    if len(parts) <= 1:  # nothing beyond the sentinel
        return None
    return "\n\n".join(parts)
 
 
def _inject_variable_context(session: ChatSession) -> None:
    """Append the active mode's variable context as a user message at ``[1]``.
 
    No-op when the active mode contributes nothing (context-free mode). Used on
    session create/load; for in-place refresh on model switch see
    :func:`refresh_variable_context`.
    """
    content = _compose_variable_context(session)
    if content is not None:
        session.messages.append({"role": "user", "content": content})
        session.dirty = True
 
 
def refresh_variable_context(session: ChatSession) -> None:
    """Re-render the sentinel-marked ``messages[1]`` in place (plan 135 §3.5).
 
    Locates the variable-context message by ``VARIABLE_CONTEXT_SENTINEL`` and
    replaces ONLY that message, preserving all conversation history. No-op when
    no sentinel-marked message exists — never inserts into an active conversation
    (that would shift indices). The choke-point :meth:`ChatSession.set_model`
    calls this so ``Model:`` (and the git/dirty facts) stay accurate after a
    ``/model`` / ``/pro`` / ``/flash`` / resume switch.
    """
    from oc_chat.core.session import VARIABLE_CONTEXT_SENTINEL
 
    sentinel = VARIABLE_CONTEXT_SENTINEL
    idx = next(
        (
            i for i, m in enumerate(session.messages)
            if m.get("role") == "user"
            and (m.get("content") or "").startswith(sentinel)
        ),
        None,
    )
    if idx is None:
        return  # no variable context to refresh — do not insert one
    content = _compose_variable_context(session)
    if content is None:
        return  # mode now contributes nothing; leave the existing message intact
    if session.messages[idx].get("content") != content:
        session.messages[idx]["content"] = content
        session.dirty = True
 
 
def migrate_session_model(
    session: ChatSession,
    provider: "ProviderPlugin",
    presenter: "Presenter | None" = None,
    *,
    capture: bool = False,
) -> "str | None":
    """Migrate a retired session model id to its replacement on load (plan 135 §4.6).
 
    Provider-agnostic: delegates to ``provider.migrate_model_id``. On a hit it
    switches through the :meth:`ChatSession.set_model` choke-point (which refreshes
    the env block) and surfaces the provider's distinct one-line notice. No-op for
    live model ids — the common case, with zero overhead.
 
    ``capture`` (plan 152-b D2) is passed ONLY by the load/switch transition
    seam, which hydrates a CANDIDATE during PREPARE where the presenter must stay
    silent. When ``capture=True`` the notice is RETURNED instead of shown (and the
    seam replays it post-commit), and ``presenter`` may be ``None``. The default
    (``capture=False``) is byte-compatible: it calls ``presenter.show_info`` and
    returns ``None``, exactly as before, for its three non-seam callers.
    """
    func = "migrate_session_model"
    result = provider.migrate_model_id(session.model)
    if result is None:
        return None
    new_id, notice = result
    session.set_model(new_id)
    _dbg("OC_CHAT.MAIN", func, f"migrated retired session model -> {new_id}", 2)
    if capture:
        return notice
    if presenter is not None:
        presenter.show_info(notice)
    return None
 
 
def _pick_lane_and_model(
    presenter: "Presenter",
    prompt_driver: "PromptDriver | None",
    model_manager: "ModelManager | None",
    lane_switch: "Callable[[object], object] | None",
    on_interrupt: "Callable[[], None]",
) -> "str | None":
    """Choose the new session's lane and model through the plan-217 picker.
 
    Plan 220 P1 / TUI-02 finding 1. What used to stand here was a flat
    ``Available models:`` list — 396 rows deep on the OpenRouter lane,
    which is a list nobody reads and a keystroke nobody can undo. The
    drill-down is the same one ``[6]`` and ``/lane`` already use, so the
    new-session choice and the mid-session switch are one surface with one
    set of habits, and the flat list is retired rather than merely bypassed.
 
    Returns the chosen model id, or ``None`` when the operator abandoned
    the traversal or the lane refused the switch. Both are DECISIONS, not
    absences, so the caller goes back to the menu instead of defaulting
    into a session — the fall-through half of finding 3.
    """
    func = "_pick_lane_and_model"
    from oc_chat.core.lane_picker import run_lane_picker
 
    selection = run_lane_picker(
        presenter, prompt_driver=prompt_driver, on_interrupt=on_interrupt
    )
    if selection is None:
        _dbg("OC_CHAT.MAIN", func, "picker abandoned - no new session", 2)
        return None
 
    if lane_switch is not None:
        try:
            lane_switch(selection)
        except Exception as exc:  # noqa: BLE001 — a refused lane must not kill startup
            # EXTERNAL_ERROR / VALIDATION_ERROR (S6 L2/L3) depending on the
            # lane's complaint; either way nothing was installed and the
            # opening menu is still usable.
            _dbg("OC_CHAT.MAIN", func,
                 f"lane switch refused: {type(exc).__name__}: {exc}", 2, override=True)
            presenter.show_error(f"  Could not switch lane: {exc}")
            return None
    elif model_manager is not None and hasattr(model_manager, "ensure"):
        # No applier wired (a headless or directly-constructed caller): the
        # active lane cannot be swapped, but the model registry can still
        # learn the id the session is about to be created on.
        model_manager.ensure(selection.model_id)
 
    detail = vendor_detail(selection.model_id)
    presenter.show_info(
        f"Lane: {selection.lane_name}  model: {selection.model_id}"
        + (f"  ({detail})" if detail else "")
    )
    _dbg("OC_CHAT.MAIN", func,
         f"new session lane={selection.lane_name} model={selection.model_id}", 2)
    return selection.model_id
 
 
def _create_new_session(
    presenter: "Presenter",
    tool_schemas: list | None = None,
    prompt_driver: "PromptDriver | None" = None,
    model_manager: "ModelManager | None" = None,
    client: "ClientInterface | None" = None,
    *,
    model: str = "",
    lane_switch: "Callable[[object], object] | None" = None,
    on_interrupt: "Callable[[], None] | None" = None,
) -> "ChatSession | None":
    """Pick a lane and model in the picker, name the session, and build it.
 
    Plan 220 P1: the model choice is :func:`_pick_lane_and_model` now, so
    ``client`` is no longer used to fetch a live list at startup — the
    picker refreshes on its explicit action only. The parameter stays for
    the callers that already pass it.
 
    *model* names the model outright and SKIPS the picker (plan 220 P1).
    It exists for the non-interactive caller that already knows its answer
    — :func:`oc_chat.benchmarks.runner._compose_session`, which composes a
    measured session through this real path. Before 220 that caller said so
    by scripting the flat list's prompt with a canned driver; with the list
    retired, scripting an interactive drill-down instead would be both
    fragile and a lie about what it wants. Saying it directly is the honest
    form, and it keeps the benchmark composing through the same function
    the REPL does rather than a divergent copy.
 
    Returns ``None`` when the operator abandoned the lane choice: there is
    no model to open a session on, and inventing one is precisely the
    fall-through TUI-02 finding 3 is about.
    """
    func = "_create_new_session"
    from oc_chat.core.session import _auto_name
 
    if on_interrupt is None:
        on_interrupt = _quit_confirmer(presenter, prompt_driver)
 
    if model:
        selected_model = model
        _dbg("OC_CHAT.MAIN", func, f"model supplied by caller: {model!r}", 3)
    else:
        selected_model = _pick_lane_and_model(
            presenter, prompt_driver, model_manager, lane_switch, on_interrupt
        )
    if selected_model is None:
        return None
 
    def _read_name() -> str:
        return _read_line(
            prompt_driver,
            "Enter a name for the new session (or press Enter for auto-generated): ",
        )
 
    name = _interruptible(_read_name, on_interrupt).strip()
    if not name:
        name = _auto_name()
        presenter.show_info(f"Using auto-generated name: {name}")
 
    # Compose the system prompt per the active mode's profile (plan 133):
    # persona + tools are gated; the variable context (tree + files) is added
    # by _inject_variable_context, also mode-driven.
    from oc_chat.core.settings import (
        active_profile, runtime_settings, runtime_mode, resolve_system_prompt,
    )
    profile = active_profile()
    settings = runtime_settings()
    base = resolve_system_prompt(settings, default=CANONICAL_POLICY) if profile.get("include_persona") else ""
    schemas = tool_schemas if profile.get("include_tools") else None
    system_text = build_system_prompt(base, schemas)
    session = ChatSession(
        name=name,
        messages=[{"role": "system", "content": system_text}],
        model=selected_model,
    )
    session.created = name.split("_", 1)[1] if "_" in name else "unknown"
    for w in settings.drain_warnings():
        presenter.show_info(f"[settings] {w}")
    _dbg("OC_CHAT.MAIN", func, f"new session={name} model={selected_model} mode={runtime_mode()}", 2)
    presenter.show_info(f"Starting new session: {name} (model: {session.model}, mode: {runtime_mode()})")
    _inject_variable_context(session)
    return session
 
 
def _menu_key(prompt_driver, prompt_text: str, *, valid: str, default: str) -> str:
    """Read a single-key menu choice (no Enter needed); Enter → *default*.
 
    Engages raw single-key mode on an interactive TTY; otherwise falls back to a
    line read via *prompt_driver* (or :func:`input`) so tests / pipes / headless
    runs stay behaviour-identical. *valid* restricts the accepted keys.
 
    Plan 220 P3 — THE swallow point. On the fallback path a
    :class:`~oc_ui.terminal.input.PromptDriver` reports a Ctrl+C by
    RETURNING ``None``, which :func:`read_single_key` then read as an empty
    line and this function turned into *default*. That is how an interrupt
    became a selection, and how two of them walked the operator into a
    session. ``None`` is now raised as the :class:`KeyboardInterrupt` it
    always was; every pre-session caller answers it through
    :func:`confirm_quit_or_continue`.
    """
    from oc_ui.terminal.input import read_single_key
 
    def _fallback() -> str:
        if prompt_driver is not None:
            raw = prompt_driver.read_user_input(None, prompt_text="")
            if raw is None:
                raise KeyboardInterrupt
            return raw
        return input("")
 
    key = read_single_key(prompt_text, valid=valid, fallback=_fallback)
    return key or default
 
 
def _read_line(prompt_driver, prompt_text: str) -> str:
    """Read one line at a pre-session prompt; a cancel raises, never defaults.
 
    The line-read twin of :func:`_menu_key`'s fallback, and the same fix:
    ``read_user_input`` returns ``None`` for a Ctrl+C at a menu prompt, and
    every pre-session caller used to coalesce that with an empty line via
    ``or ""``. An empty line means "take the default"; an interrupt means
    the opposite, and conflating them is TUI-02 finding 3.
    """
    if prompt_driver is None:
        return input(prompt_text)
    raw = prompt_driver.read_user_input(None, prompt_text=prompt_text)
    if raw is None:
        raise KeyboardInterrupt
    return raw
 
 
def confirm_quit_or_continue(
    presenter: "Presenter", prompt_driver: "PromptDriver | None"
) -> None:
    """Answer a pre-session Ctrl+C with ``Quit OC Chat? (y/N)`` (plan 220 P3).
 
    Returns on ``N`` / a bare Enter, and the caller then re-shows the prompt
    that was interrupted with its state untouched — an interrupt asks a
    question, it never answers one.
 
    Raises :class:`SystemExit(0)` on ``y``, and also on a second interrupt
    or an EOF at the confirmation itself: the safe direction out of an
    interrupted pre-session prompt is OUT of the program, never onward into
    a session. That asymmetry is the whole point of the finding — the
    operator could press Ctrl+C repeatedly and end up in a chat.
 
    Public because ``main`` owns two pre-session prompts of its own (the
    crash auto-reload and the incomplete-tail recovery) and must answer an
    interrupt at them the same way this module does.
    """
    func = "confirm_quit_or_continue"
    try:
        answer = _read_line(prompt_driver, "Quit OC Chat? (y/N): ").strip().lower()
    except (EOFError, KeyboardInterrupt):
        _dbg("OC_CHAT.MAIN", func, "interrupt at the quit confirmation - exiting", 2)
        presenter.show_info("Exiting.")
        raise SystemExit(0)
    if answer in ("y", "yes"):
        _dbg("OC_CHAT.MAIN", func, "quit confirmed at a pre-session prompt", 2)
        presenter.show_info("Goodbye!")
        raise SystemExit(0)
    _dbg("OC_CHAT.MAIN", func, "quit declined - re-showing the interrupted prompt", 3)
 
 
def _quit_confirmer(
    presenter: "Presenter", prompt_driver: "PromptDriver | None"
) -> "Callable[[], None]":
    """Bind :func:`confirm_quit_or_continue` to this menu's presenter/driver."""
 
    def _handler() -> None:
        confirm_quit_or_continue(presenter, prompt_driver)
 
    return _handler
 
 
def _interruptible(read: "Callable[[], str]", on_interrupt: "Callable[[], None]") -> str:
    """Run *read*; a Ctrl+C is answered by *on_interrupt*, then re-asked.
 
    *read* is re-invoked rather than resumed, which is what makes "``N``
    re-shows the interrupted prompt UNCHANGED" structural: the closure is
    the prompt, so re-running it cannot disagree with what was on screen.
    """
    while True:
        try:
            return read()
        except KeyboardInterrupt:
            on_interrupt()
 
 
def _show_block(presenter: "Presenter", lines: "list[str]") -> None:
    """Emit *lines* as ONE section — single-spaced, one blank line above it.
 
    See :func:`~oc_chat.core.lane_tree.section_text` for why: the blank line
    every presenter opens ``show_info`` with belongs once per SECTION, not
    once per row (plan 220 P2 / TUI-02 finding 2). An empty run shows
    nothing at all, which is what keeps the plan-215 lane panel invisible
    without a catalogue-backed bundle.
    """
    block = section_text(lines)
    if block:
        presenter.show_info(block)
 
 
#: Column widths for the lane panel. Fixed rather than computed so the panel
#: does not reflow when a lane is added or a key is set (plan 215 T3).
_LANE_NAME_W = 18
_LANE_LABEL_W = 30
 
 
def _lane_rows(providers: "list[ProviderPlugin]") -> list:
    """Return the catalogue-backed lane rows among *providers*, in menu order.
 
    Duck-typed on purpose (plan 215 P3): a provider bundle contributes a lane
    row by exposing a ``lane`` attribute carrying the menu metadata. This
    keeps ``startup`` free of any import of the optional bundle — the panel
    simply has nothing to render when the bundle is not installed, which is
    what makes the deepseek/ollama menu byte-identical to its pre-215 render.
 
    Menu order is a PRESENTATION decision owned here, not by the catalogue:
    free lanes first, then alphabetically within each group. The free lanes
    are the ones a new operator can actually try today, so they lead; the
    ordering is total and deterministic, so the panel never reflows because
    a registry happened to enumerate differently.
    """
    rows = []
    for provider in providers:
        lane = getattr(provider, "lane", None)
        if lane is None:
            continue
        if not all(hasattr(lane, f) for f in ("display_label", "free", "verification")):
            continue
        rows.append(lane)
    return sorted(rows, key=lambda lane: (not lane.free, lane.name))
 
 
def _add_provider_available() -> bool:
    """Whether the opening menu should offer the "Add provider" entry (plan 216).
 
    True exactly when a catalogue-backed lane is registered — i.e. when
    there is a catalogue for the wizard to extend. This is not a
    convenience: an overlay row is registered as an
    ``OpenAICompatProvider``, so without the bundle the wizard has nothing
    to write into. It is also what preserves plan 215's additive property
    — a deepseek/ollama-only install grows no fifth menu entry and its
    render stays byte-identical to the pre-215 golden.
    """
    from oc_chat.core.provider_plugin import registry
 
    return bool(_lane_rows([registry.get(name) for name in registry.names()]))
 
 
def _load_provider_overlays(presenter: "Presenter") -> None:
    """Startup hook (plan 216): sidecar keys into the environment, overlay lanes in.
 
    Runs before the lane panel renders so a wizard-added lane shows up
    with its key already marked ``ready``. Both halves are total:
 
    - The sidecar load never raises and never overwrites a variable the
      real environment already carries (P1).
    - A malformed overlay is REPORTED rather than swallowed — a lane the
      operator added must not vanish silently — but it does not stop the
      REPL from starting.
 
    Silent on the common path, which is what keeps the menu golden intact.
    """
    func = "_load_provider_overlays"
    from oc_chat.core.lane_overlay import OverlayError, register_overlay_lanes
    from oc_chat.core.provider_secrets import apply_to_environ
 
    apply_to_environ()
    try:
        registered = register_overlay_lanes()
    except OverlayError as exc:
        # VALIDATION_ERROR — operator-authored data; surface it, keep going.
        presenter.show_error(f"[lane overlay] {exc}")
        return
    if registered:
        _dbg("OC_CHAT.MAIN", func,
             f"overlay contributed {len(registered)} lane(s)", 2)
 
 
def _render_provider_lanes(env: "dict | None" = None) -> list[str]:
    """Render the opening menu's provider-lane panel as a list of lines.
 
    Returns ``[]`` when no catalogue-backed lane is registered, so a install
    without the ``openai_compat`` bundle renders the menu exactly as it did
    before plan 215.
 
    Every registered lane is shown — never hidden (plan 215 P5). A lane whose
    API-key env var is unset is marked ``no key (VAR_NAME)`` and stays
    visible, because a lane the operator cannot see is a lane they cannot fix.
    Badges are read from the catalogue row: ``FREE`` on a free lane, ``PAID``
    otherwise, plus the honest ``verification`` tier (``chat`` until a human
    has run the conformance runner against a live key).
 
    *env* defaults to the live environment; tests pass an explicit mapping.
    Only the PRESENCE of each key variable is read — never its value.
    """
    func = "_render_provider_lanes"
    from oc_chat.core.provider_plugin import registry
 
    environ = os.environ if env is None else env
    providers = [registry.get(name) for name in registry.names()]
    lanes = _lane_rows(providers)
    if not lanes:
        return []
 
    # OCT-LINT: disable=no_hardcoded_secrets reason="Menu header text naming the selection env var; high-entropy English, not a credential"
    lines = ["", "  Provider lanes - select one with OC_CHAT_PROVIDER=<name>:"]
    for lane in lanes:
        badge = "FREE" if lane.free else "PAID"
        # Presence only: the VALUE is never read into the menu, printed, or
        # retained anywhere (plan 215 P6).
        has_key = bool((environ.get(lane.api_key_env_var) or "").strip())
        status = "ready" if has_key else f"no key ({lane.api_key_env_var})"
        lines.append(
            f"    {lane.name:<{_LANE_NAME_W}}{lane.display_label:<{_LANE_LABEL_W}}"
            f"{badge:<6}verified: {lane.verification:<7}{status}"
        )
    lines.append("")
    _dbg("OC_CHAT.MAIN", func, f"rendered {len(lanes)} provider lane(s)", 3)
    return lines
 
 
def _sort_sessions(sessions: list[dict], mode: str) -> list[dict]:
    """Return *sessions* sorted by *mode*.
 
    ``"date"`` (default) → most-recently-modified first; ``"name"`` →
    case-insensitive alphabetical. Date uses the metadata file mtime, the same
    key :func:`startup_session_prompt` uses to pick the most-recent session.
    """
    if mode == "name":
        return sorted(sessions, key=lambda s: s["name"].lower())
    return sorted(sessions, key=lambda s: os.path.getmtime(s["filepath"]), reverse=True)
 
 
def _choose_saved_session(
    sessions: list[dict],
    presenter: "Presenter",
    model_manager: "ModelManager | None",
    tool_schemas: list | None,
    prompt_driver: "PromptDriver | None",
    on_interrupt: "Callable[[], None] | None" = None,
) -> "ChatSession | None":
    """Option 3 — list the saved sessions (sortable) and load the chosen one.
 
    Returns the loaded :class:`ChatSession`, or ``None`` to go back to the main
    menu. The list defaults to most-recent-first; ``n`` re-sorts by name and
    ``d`` back to date (the displayed ``#`` always indexes the shown order).
 
    Plan 220: the table is one section (P2), and a Ctrl+C at its prompt is a
    pre-session interrupt like any other (P3) — a bare Enter is what means
    "back", and an interrupt must not be quietly read as one.
    """
    from oc_chat.core.persistence import session_exists
 
    if on_interrupt is None:
        on_interrupt = _quit_confirmer(presenter, prompt_driver)
 
    sort_mode = "date"
    while True:
        ordered = _sort_sessions(sessions, sort_mode)
        sort_label = "name (A–Z)" if sort_mode == "name" else "date (newest first)"
        lines = [
            "",
            f"Saved sessions — sorted by {sort_label}:",
            f"{'#':>3}  {'Name':<30} {'Model':<34} {'Msgs':>4} {'Tools':>5} "
            f"{'Volume':>14}  Last Modified",
            "-" * 112,
        ]
        for i, s in enumerate(ordered, 1):
            stats = s["stats"]
            size = s.get("chat_log_size_bytes", 0)
            model_label = fmt_model_caps(
                s["model"], s.get("reasoning_effort", "high"), model_manager
            )
            if len(model_label) > 34:
                model_label = model_label[:33] + "…"
            vol = fmt_tokens_or_size(stats, size)
            lines.append(
                f"{i:>3}  {s['name']:<30} {model_label:<34} "
                f"{stats.message_count:>4} {stats.tool_call_count:>5} "
                f"{vol:>14}  {s['last_modified']}"
            )
        lines.append("")
        _show_block(presenter, lines)
 
        prompt = "Enter session # or name · 'n'=sort by name · 'd'=by date · Enter=back: "
 
        def _read_choice() -> str:
            return _read_line(prompt_driver, prompt)
 
        try:
            raw = _interruptible(_read_choice, on_interrupt).strip()
        except EOFError:
            # A closed stdin is not an operator decision — go back, silently.
            return None
 
        if not raw:
            presenter.show_info("Returning to session selection menu...")
            return None
 
        low = raw.lower()
        if low == "n":
            sort_mode = "name"
            continue
        if low == "d":
            sort_mode = "date"
            continue
 
        # Numeric shortcut: 1–3 digit number indexes the displayed (sorted) table.
        if raw.isdigit() and len(raw) <= 3:
            idx = int(raw)
            if 1 <= idx <= len(ordered):
                return _load_session_by_meta(ordered[idx - 1], presenter, tool_schemas)
            presenter.show_info(f"  No session at index {idx} (range 1–{len(ordered)}).")
            continue
 
        if not session_exists(raw):
            presenter.show_info(f"Session '{raw}' not found. (Enter to go back.)")
            continue
        match = next((s for s in ordered if s["name"] == raw), None)
        if match:
            return _load_session_by_meta(match, presenter, tool_schemas)
 
 
def _run_lane_picker_entry(
    presenter: "Presenter",
    prompt_driver: "PromptDriver | None",
    lane_switch: "Callable[[object], object] | None",
    on_interrupt: "Callable[[], None] | None" = None,
) -> "tuple[ModelManager | None, ClientInterface | None] | None":
    """Menu option 6 (plan 217 T4): drill down to a lane + model, then switch.
 
    Returns the ``(model_manager, client)`` pair the applier rebuilt, so the
    caller can rebind its own locals — a stale ``model_manager`` here would
    make the very next new-session prompt list the OLD lane's models.
    ``None`` means nothing changed: the operator abandoned the picker, or
    the switch was refused.
 
    The picker itself mutates nothing (plan 217 P4); everything that does
    happens inside *lane_switch*, which is only ever reached with a
    confirmed selection.
    """
    func = "_run_lane_picker_entry"
    from oc_chat.core.lane_picker import run_lane_picker
 
    selection = run_lane_picker(
        presenter, prompt_driver=prompt_driver, on_interrupt=on_interrupt
    )
    if selection is None or lane_switch is None:
        return None
    try:
        rebuilt = lane_switch(selection)
    except Exception as exc:  # noqa: BLE001 — a refused switch must not kill the menu
        # EXTERNAL_ERROR / VALIDATION_ERROR (S6 L2/L3) depending on the lane's
        # complaint; either way the old lane is intact and the menu carries on.
        _dbg("OC_CHAT.MAIN", func,
             f"lane switch refused: {type(exc).__name__}: {exc}", 2, override=True)
        presenter.show_error(f"  Could not switch lane: {exc}")
        return None
    presenter.show_info(
        f"  Lane set to {selection.lane_name} (model: {selection.model_id})."
    )
    _dbg("OC_CHAT.MAIN", func,
         f"switched to {selection.lane_name}/{selection.model_id}", 2)
    return rebuilt  # type: ignore[return-value]
 
 
def startup_session_prompt(
    presenter: "Presenter",
    *,
    version: str,
    model_manager: "ModelManager | None" = None,
    tool_schemas: list | None = None,
    prompt_driver: "PromptDriver | None" = None,
    client: "ClientInterface | None" = None,
    lane_switch: "Callable[[object], object] | None" = None,
) -> ChatSession:
    """Present the startup session-selection menu at OC Chat launch.
 
    If saved sessions exist, the user can:
      1. Start a brand-new session (the default — a bare Enter picks it).
      2. Resume the most recently modified session.
      3. Choose another saved session (sortable by date or name).
      4. Quit OC Chat.
      5. Add a provider (only with a catalogue-backed lane registered).
      6. Choose a lane and model (only with both a lane AND *lane_switch*).
 
    Menu choices read as a single keypress on an interactive TTY (no Enter
    needed); Enter alone selects option 1. If no sessions exist, the user is
    taken directly to the new-session lane picker and name prompt.
 
    Plan 220: option 1 (and the no-sessions path) drill down through the
    plan-217 picker rather than printing a flat model list (P1); the menu
    is emitted as ONE section so it renders single-spaced (P2); and a
    Ctrl+C at ANY prompt below asks ``Quit OC Chat? (y/N)`` instead of
    firing a default (P3). The invariant those three protect together is
    that no interrupt sequence, of any length, ends inside a session.
 
    *lane_switch* (plan 217 T4) applies a confirmed
    :class:`~oc_chat.core.lane_picker.LaneSelection` and returns the
    rebuilt ``(model_manager, client)`` pair. It is supplied by ``main()``,
    which owns the :class:`~oc_chat.core.agent.Agent` whose engine objects
    the switch replaces. Entry 6 is offered ONLY when it is present: a
    caller that cannot apply a switch must not offer to make one.
 
    Returns a :class:`ChatSession` ready for the REPL — either loaded
    from disk (with full message history) or freshly created.
    """
    func = "startup_session_prompt"
    from oc_chat.core.persistence import list_sessions
 
    sessions = list_sessions()
 
    # Plan 220 P3: one handler for every pre-session prompt below, so a
    # Ctrl+C means the same thing at all of them.
    on_interrupt = _quit_confirmer(presenter, prompt_driver)
 
    # Plan 216: sidecar keys into the environment and overlay lanes into the
    # registry, BEFORE the panel renders — a lane the wizard added last run
    # comes back marked 'ready' rather than 'no key'. Silent on the common path.
    _load_provider_overlays(presenter)
 
    # Plan 215 T3: the provider-lane panel. Empty (and therefore invisible)
    # unless a catalogue-backed bundle is installed, so the menu below is
    # unchanged for a deepseek/ollama-only install.
    _show_block(presenter, _render_provider_lanes())
 
    if not sessions:
        _dbg("OC_CHAT.MAIN", func, "no existing sessions — going straight to new-session prompt", 2)
        presenter.show_info("No existing sessions found.")
        created = _create_new_session(
            presenter, tool_schemas, prompt_driver=prompt_driver,
            model_manager=model_manager, client=client,
            lane_switch=lane_switch, on_interrupt=on_interrupt,
        )
        if created is not None:
            return created
        # The lane choice was abandoned and there is no menu to fall back
        # to on a fresh install. Guessing a lane here is the fall-through
        # this plan exists to remove, so the honest move is out (P1/P3).
        _dbg("OC_CHAT.MAIN", func, "no lane chosen and no saved session - exiting", 2)
        presenter.show_info("No lane chosen — nothing to open. Goodbye!")
        raise SystemExit(0)
 
    # Find the most recent session by metadata file modification time
    most_recent = max(sessions, key=lambda s: os.path.getmtime(s["filepath"]))
 
    mr_stats   = most_recent["stats"]
    mr_size    = most_recent.get("chat_log_size_bytes", 0)
    mr_volume  = fmt_tokens_or_size(mr_stats, mr_size)
    mr_model   = fmt_model_caps(
        most_recent["model"],
        most_recent.get("reasoning_effort", "high"),
        model_manager,
        verbose=True,
    )
 
    # Plan 220 P2: the whole menu is ONE section. Emitted row by row it
    # picked up a blank line per row from the presenter — the double
    # spacing TUI-02 filed as finding 2.
    menu = [
        "=" * 60,
        f"  OC Chat — v{version}",
        "=" * 60,
        "  [1] Start a new session",
        "  [2] Resume previous session",
        f"      → {most_recent['name']}  "
        f"msgs: {mr_stats.message_count}, tools: {mr_stats.tool_call_count}, "
        f"{mr_volume}",
        f"        model: {mr_model}",
        f"        last modified: {most_recent['last_modified']}",
        f"  [3] Choose another saved session ({len(sessions)} available)",
        "  [4] Quit OC Chat",
    ]
    # Plan 216 T3: offered only when a catalogue-backed lane is registered, so
    # the four-entry menu above stays byte-identical without the bundle.
    add_provider = _add_provider_available()
    if add_provider:
        menu.append("  [5] Add provider (onboard a new lane)")
    # Plan 217 P5: the picker appears only where lanes exist AND the caller can
    # apply a switch, so the four-entry menu stays byte-identical without the
    # bundle — the same additive property plan 215 established and 216 kept.
    pick_lane = add_provider and lane_switch is not None
    if pick_lane:
        menu.append("  [6] Choose lane and model (switch provider)")
    _show_block(presenter, menu)
 
    last_entry = 6 if pick_lane else (5 if add_provider else 4)
    valid_keys = "".join(str(n) for n in range(1, last_entry + 1))
 
    def _read_choice() -> str:
        # Plan 220 P2: the prompt is indented to the menu's own column and
        # sits directly under the last entry. It is the menu's question, so
        # it belongs to the menu's section — a blank line between them would
        # be the very separator this plan is reclaiming.
        return _menu_key(
            prompt_driver,
            f"  Choice (1-{last_entry}) [1]: ",
            valid=valid_keys,
            default="1",
        )
 
    while True:
        try:
            # Plan 220 P3: EOF still exits — a closed stdin leaves nobody to
            # confirm with. A Ctrl+C is the opposite case and is asked about.
            choice = _interruptible(_read_choice, on_interrupt)
        except EOFError:
            presenter.show_info("Exiting.")
            raise SystemExit(0)
 
        if choice == "1":
            created = _create_new_session(
                presenter, tool_schemas, prompt_driver=prompt_driver,
                model_manager=model_manager, client=client,
                lane_switch=lane_switch, on_interrupt=on_interrupt,
            )
            if created is not None:
                return created
            # None → the lane choice was abandoned or refused; back to the
            # menu prompt. Never a session on a model nobody picked.
 
        elif choice == "2":
            return _load_session_by_meta(most_recent, presenter, tool_schemas)
 
        elif choice == "3":
            selected = _choose_saved_session(
                sessions, presenter, model_manager, tool_schemas, prompt_driver,
                on_interrupt,
            )
            if selected is not None:
                return selected
            # None → user chose "back"; redisplay the menu prompt.
 
        elif choice == "4":
            presenter.show_info("Goodbye!")
            raise SystemExit(0)
 
        elif choice == "5" and add_provider:
            # Plan 216 P5: run the wizard, then re-render the lane panel so the
            # new lane is visible immediately, and fall back to the menu prompt.
            from oc_chat.core.provider_wizard import run_add_provider_wizard
 
            added = run_add_provider_wizard(presenter, prompt_driver=prompt_driver)
            if added is not None:
                _load_provider_overlays(presenter)
                _show_block(presenter, _render_provider_lanes())
 
        elif choice == "6" and pick_lane:
            # Plan 217 T4: drill down, then rebind the locals the switch
            # rebuilt so option 1 below prompts against the NEW lane.
            rebuilt = _run_lane_picker_entry(
                presenter, prompt_driver, lane_switch, on_interrupt
            )
            if rebuilt is not None:
                model_manager, client = rebuilt
 
        else:
            presenter.show_info(f"Invalid choice. Please enter 1-{last_entry}.")