phase-loop-runtime 0.2.0__py3-none-any.whl

phase_loop_runtime/advisor_board/config.py

@@ -0,0 +1,225 @@
+"""User-editable board config loader (ABDREG, Phase 2 — lane 4).
+
+Loads ``$XDG_CONFIG_HOME/agent-harness/advisor-boards.toml`` (the FROZEN location,
+``schema.board_config_path``; format frozen by
+``fixtures/advisor-boards.example.toml``) and layers user boards on top of the
+built-in ``presets``. Contract:
+
+* The four built-in presets are always present (base layer); a user ``[[boards]]``
+  with the same ``name`` overrides its preset.
+* ``allow_api_key_fallback`` defaults ``False`` — a board with an ``api_key`` seat
+  and no opt-in is rejected by the ``Board`` schema (never-silent-key).
+* **Unknown keys are a hard error, never a silent drop** — an unrecognised
+  top-level, board, or seat key raises ``BoardConfigError`` naming the key.
+* Every board (presets AND user boards) is validated through the compatibility
+  matrix at load time, so an invalid ``(model, harness)`` pairing (e.g.
+  ``claude:gpt-5.5``) or an over-ceiling effort is rejected at CONFIG TIME with an
+  actionable message (``validation.validate_board``).
+
+A missing config file is not an error: the built-in presets load on their own.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+try:  # Python 3.11+
+    import tomllib  # type: ignore[import-not-found]
+except ModuleNotFoundError:  # Python 3.10 — the requires-python floor
+    import tomli as tomllib  # type: ignore[no-redef]
+
+from .validation import SeatValidationError, validate_board
+from .presets import DEFAULT_BOARD_NAME, PRESETS
+from .schema import (
+    AUTH_LANES,
+    PROVIDER_BACKINGS,
+    Board,
+    Seat,
+    board_config_path,
+)
+
+# Recognised keys — anything else is a hard error (no silent drop).
+_KNOWN_TOP_KEYS: frozenset[str] = frozenset({"default_board", "boards"})
+_KNOWN_BOARD_KEYS: frozenset[str] = frozenset(
+    {"name", "purpose", "allow_api_key_fallback", "seats"}
+)
+_KNOWN_SEAT_KEYS: frozenset[str] = frozenset(
+    {"model", "effort", "harness", "lens", "auth", "backing", "host_leg"}
+)
+
+
+class BoardConfigError(ValueError):
+    """The board config is malformed: an unknown key, a wrong-typed value, a
+    missing required field, or a board that fails matrix validation."""
+
+
+@dataclass(frozen=True)
+class BoardConfig:
+    """Resolved board set: the built-in presets overlaid with the user's boards,
+    plus the resolved ``default_board`` name."""
+
+    boards: dict[str, Board]
+    default_board: str
+
+    def get(self, name: str | None = None) -> Board:
+        """Resolve a board by name; a bare ``advisor-board`` (``name is None``)
+        resolves to ``default_board``. Raises ``BoardConfigError`` naming the
+        available boards for an unknown name."""
+        key = name or self.default_board
+        try:
+            return self.boards[key]
+        except KeyError as exc:
+            available = ", ".join(sorted(self.boards))
+            raise BoardConfigError(
+                f"unknown board {key!r}; available boards: {available}"
+            ) from exc
+
+    def names(self) -> tuple[str, ...]:
+        return tuple(sorted(self.boards))
+
+
+def _reject_unknown(keys, allowed: frozenset[str], where: str) -> None:
+    unknown = sorted(set(keys) - allowed)
+    if unknown:
+        raise BoardConfigError(
+            f"unknown config key(s) {unknown} in {where}; "
+            f"recognised keys: {sorted(allowed)}"
+        )
+
+
+def _require_bool(raw: Mapping[str, Any], key: str, default: bool, where: str) -> bool:
+    """Read a boolean config key STRICTLY: an absent key yields ``default``, a
+    present key MUST be a literal TOML boolean. Never coerce a non-bool scalar —
+    ``bool("false")`` is ``True``, so coercion would silently flip an opt-in gate
+    (e.g. a quoted ``allow_api_key_fallback = "false"`` would enable the api-key
+    fallback). A wrong-typed value is a hard ``BoardConfigError`` naming the key."""
+    if key not in raw:
+        return default
+    value = raw[key]
+    if not isinstance(value, bool):
+        raise BoardConfigError(
+            f"{where}: {key!r} must be a boolean (true/false), got "
+            f"{type(value).__name__} {value!r}"
+        )
+    return value
+
+
+def _parse_seat(raw: Mapping[str, Any], where: str) -> Seat:
+    if not isinstance(raw, Mapping):
+        raise BoardConfigError(f"{where} must be a table, got {type(raw).__name__}")
+    _reject_unknown(raw.keys(), _KNOWN_SEAT_KEYS, where)
+    if "model" not in raw:
+        raise BoardConfigError(f"{where} is missing the required 'model' key")
+    if "effort" not in raw:
+        raise BoardConfigError(f"{where} (model={raw['model']!r}) is missing the required 'effort' key")
+    auth = raw.get("auth", AUTH_LANES[0])
+    backing = raw.get("backing", PROVIDER_BACKINGS[0])
+    try:
+        return Seat(
+            model=str(raw["model"]),
+            effort=str(raw["effort"]),
+            harness=(str(raw["harness"]) if raw.get("harness") is not None else None),
+            lens=(str(raw["lens"]) if raw.get("lens") is not None else None),
+            auth=str(auth),
+            backing=str(backing),
+            host_leg=_require_bool(raw, "host_leg", False, where),
+        )
+    except (ValueError, TypeError) as exc:
+        # Seat.__post_init__ fail-closed validation (bad effort/auth/backing) ->
+        # surface as a config error at load time.
+        raise BoardConfigError(f"{where}: {exc}") from exc
+
+
+def _parse_board(raw: Mapping[str, Any], index: int) -> Board:
+    where = f"boards[{index}]"
+    if not isinstance(raw, Mapping):
+        raise BoardConfigError(f"{where} must be a table, got {type(raw).__name__}")
+    _reject_unknown(raw.keys(), _KNOWN_BOARD_KEYS, where)
+    if "name" not in raw:
+        raise BoardConfigError(f"{where} is missing the required 'name' key")
+    name = str(raw["name"])
+    seats_raw = raw.get("seats", [])
+    if not isinstance(seats_raw, list):
+        raise BoardConfigError(f"board {name!r} 'seats' must be a list of seat tables")
+    seats = tuple(
+        _parse_seat(seat, f"board {name!r} seats[{i}]") for i, seat in enumerate(seats_raw)
+    )
+    try:
+        return Board(
+            name=name,
+            purpose=str(raw.get("purpose", "")),
+            seats=seats,
+            allow_api_key_fallback=_require_bool(
+                raw, "allow_api_key_fallback", False, where
+            ),
+        )
+    except (ValueError, TypeError) as exc:
+        # Board.__post_init__ (e.g. api_key seat without opt-in) -> config error.
+        raise BoardConfigError(f"board {name!r}: {exc}") from exc
+
+
+def load_boards(
+    path: Path | None = None,
+    *,
+    env: Mapping[str, str] | None = None,
+    matrix: Any | None = None,
+    validate: bool = True,
+) -> BoardConfig:
+    """Load the board config, layering user boards over the built-in presets.
+
+    ``path`` defaults to ``board_config_path(env)``. A missing file yields just the
+    presets. ``matrix`` defaults to ``matrix.default_matrix()``; pass ``validate=
+    False`` only for shape-parsing without availability (kept for tests). Raises
+    ``BoardConfigError`` for any unknown key, malformed value, or matrix-invalid
+    board — never a silent drop.
+    """
+    boards: dict[str, Board] = dict(PRESETS)
+    default_board = DEFAULT_BOARD_NAME
+
+    cfg_path = path if path is not None else board_config_path(env)
+    if cfg_path.exists():
+        with open(cfg_path, "rb") as fh:
+            try:
+                data = tomllib.load(fh)
+            except tomllib.TOMLDecodeError as exc:
+                raise BoardConfigError(f"{cfg_path} is not valid TOML: {exc}") from exc
+        _reject_unknown(data.keys(), _KNOWN_TOP_KEYS, str(cfg_path))
+        raw_boards = data.get("boards", [])
+        if not isinstance(raw_boards, list):
+            raise BoardConfigError(f"{cfg_path}: 'boards' must be an array of tables")
+        for i, raw in enumerate(raw_boards):
+            board = _parse_board(raw, i)
+            boards[board.name] = board  # user board overrides a same-named preset
+        if "default_board" in data:
+            default_board = str(data["default_board"])
+
+    if default_board not in boards:
+        available = ", ".join(sorted(boards))
+        raise BoardConfigError(
+            f"default_board {default_board!r} is not a defined board; "
+            f"available boards: {available}"
+        )
+
+    if validate:
+        if matrix is None:
+            from .matrix import default_matrix
+
+            matrix = default_matrix(env=env)
+        for board in boards.values():
+            try:
+                validate_board(board, matrix=matrix)
+            except SeatValidationError as exc:
+                # Surface matrix-level rejections under the config error type so a
+                # caller catches one exception for any load-time failure.
+                raise BoardConfigError(str(exc)) from exc
+
+    return BoardConfig(boards=boards, default_board=default_board)
+
+
+__all__ = [
+    "BoardConfig",
+    "BoardConfigError",
+    "load_boards",
+]

phase_loop_runtime/advisor_board/events.py

@@ -0,0 +1,115 @@
+"""Internal advisor-board event envelope + best-effort forwarding (IF-0-ABDFREEZE-5).
+
+This is OUR event shape — deliberately NOT a guessed Omnigent schema. It freezes
+the observability contract's two load-bearing rules:
+
+* **launcher != observability-plane**: a natively-launched leg stays natively
+  launched and *emits* an ``AdvisorBoardEvent`` into a forwarded stream; it is
+  never relaunched through the gateway for observability's sake.
+* **forwarding is async/best-effort and can NEVER delay or fail the native
+  leg**: ``best_effort_forward`` swallows every sink error and (by contract)
+  hands the event to the sink off the leg's critical path.
+
+The MAPPING from this envelope to a concrete sink (an Omnigent v0.4.0 ingestion
+endpoint, or omniagent-plus's own ui-read-model / state-ledger) is deferred to
+ABDOBS — do NOT freeze against a guessed upstream schema.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+# Bumped only on a breaking change to the envelope; sinks key off it.
+EVENT_SCHEMA_VERSION = "advisor_board.event.v1"
+
+# The frozen event kinds a board leg emits. Board-level bracket the run; seat-level
+# mirror a leg's lifecycle (aligned with the runtime ``runtime.*`` names in
+# agent_runtime_provider.RuntimeEvent, but named in OUR namespace).
+EVENT_KINDS: tuple[str, ...] = (
+    "board.started",
+    "board.completed",
+    "seat.started",
+    "seat.text.delta",
+    "seat.completed",
+    "seat.failed",
+    "seat.skipped",
+)
+
+
+@dataclass(frozen=True)
+class AdvisorBoardEvent:
+    """One observability event from a board run — our envelope, sink-agnostic.
+
+    ``board``          the board name (e.g. ``"default"``).
+    ``seat_key``       the emitting seat's stable identity (``Seat.seat_key``);
+                       empty for ``board.*`` events.
+    ``vendor_family``  the seat's projected vendor family (empty for board events).
+    ``harness``        the seat's execution lane (empty for board events).
+    ``kind``           one of ``EVENT_KINDS``.
+    ``sequence``       monotonic per board run.
+    ``occurred_at``    ISO-8601 UTC timestamp (caller-supplied; frozen field only).
+    ``payload``        kind-specific fields (e.g. ``{"delta": ...}`` /
+                       ``{"status": ...}``); never carries a raw API key.
+    """
+
+    kind: str
+    board: str
+    sequence: int
+    occurred_at: str
+    seat_key: str = ""
+    vendor_family: str = ""
+    harness: str = ""
+    schema_version: str = EVENT_SCHEMA_VERSION
+    payload: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.kind not in EVENT_KINDS:
+            raise ValueError(f"event.kind {self.kind!r} not in {EVENT_KINDS}")
+
+    def to_json(self) -> dict[str, Any]:
+        """Stable serialization for a sink. Field set is the frozen wire contract."""
+        return {
+            "schema_version": self.schema_version,
+            "kind": self.kind,
+            "board": self.board,
+            "seat_key": self.seat_key,
+            "vendor_family": self.vendor_family,
+            "harness": self.harness,
+            "sequence": self.sequence,
+            "occurred_at": self.occurred_at,
+            "payload": dict(self.payload),
+        }
+
+
+@runtime_checkable
+class EventSink(Protocol):
+    """A destination for advisor-board events. The concrete mapping to Omnigent /
+    ui-read-model / state-ledger is ABDOBS; this only fixes the emit surface."""
+
+    def emit(self, event: AdvisorBoardEvent) -> None: ...
+
+
+class NullSink:
+    """Default sink: drops every event. Keeps the ``default`` board's observability
+    a no-op (today's behavior: no forwarding) until ABDOBS wires a real sink."""
+
+    def emit(self, event: AdvisorBoardEvent) -> None:  # noqa: D401 - trivial
+        return None
+
+
+def best_effort_forward(sink: EventSink | None, event: AdvisorBoardEvent) -> bool:
+    """Forward ``event`` to ``sink``, swallowing EVERY error.
+
+    Returns whether the sink accepted the event; a ``None`` sink or any raised
+    exception returns ``False`` WITHOUT propagating — forwarding must never delay
+    or fail the native leg (IF-0-ABDFREEZE-5). The async dispatch (off the leg's
+    critical path) is ABDOBS's to wire; the never-raise guarantee is frozen here.
+    """
+    if sink is None:
+        return False
+    try:
+        sink.emit(event)
+        return True
+    except Exception:  # best-effort: an observability failure NEVER touches the leg
+        return False

phase_loop_runtime/advisor_board/fixtures/advisor-boards.example.toml

@@ -0,0 +1,59 @@
+# Advisor Board config — FROZEN FORMAT (IF-0-ABDFREEZE-1).
+#
+# Location: $XDG_CONFIG_HOME/agent-harness/advisor-boards.toml
+#           (default ~/.config/agent-harness/advisor-boards.toml)
+#
+# This is the on-disk shape ABDREG's loader parses. It is a fixture only — the
+# loader, board presets, and unknown-key validation land in ABDREG (Phase 2).
+# A board is a named, purpose-tagged, OPEN-ENDED list of seats. A seat is a
+# cognition {model, effort, harness?, lens?, auth?, backing?}, model-first: the
+# harness is a defaulted-but-overridable execution lane.
+
+# Optional: the board a bare `advisor-board` invocation resolves to.
+default_board = "default"
+
+# The default board reproduces today's 3-leg panel (byte-for-byte back-compat).
+# Its three seats, in panel-leg order, render to today's exact CLI invocations:
+#   codex  gpt-5.5          effort=max  -> -c model_reasoning_effort=xhigh
+#   gemini "Gemini 3.1 Pro" effort=high -> model "Gemini 3.1 Pro (High)"
+#   claude claude-sonnet-5  effort=max  -> --effort max
+[[boards]]
+name = "default"
+purpose = "premerge-review"
+allow_api_key_fallback = false
+
+  [[boards.seats]]
+  model = "gpt-5.5"
+  effort = "max"
+  harness = "codex"        # optional; omit to resolve via default_lane(model)
+  auth = "subscription"    # subscription (default) | api_key
+  backing = "homebrew"     # homebrew (default) | omnigent
+
+  [[boards.seats]]
+  model = "Gemini 3.1 Pro"
+  effort = "high"
+  harness = "gemini"
+
+  [[boards.seats]]
+  model = "claude-sonnet-5"
+  effort = "max"
+  harness = "claude"
+
+# A purpose-tagged preset with an open-ended seat list (ABDREG ships the real
+# presets: default, code-review, brainstorm, doc-edit, legal-review,
+# legal-strategy-review, legal-brainstorm).
+[[boards]]
+name = "code-review"
+purpose = "code-review"
+allow_api_key_fallback = false
+
+  [[boards.seats]]
+  model = "gpt-5.5"
+  effort = "max"
+  harness = "codex"
+
+  [[boards.seats]]
+  model = "claude-sonnet-5"
+  effort = "max"
+  harness = "claude"
+  lens = "adversarial"     # optional review lens/persona

phase_loop_runtime/advisor_board/fixtures.py

@@ -0,0 +1,91 @@
+"""Shared canonical fixtures (IF-0-ABDFREEZE-2 keystone).
+
+ONE fixture set, importable from both ``src`` and ``tests``, that ABDREG
+populates *from* and ABDRESOLVE / ABDHOME test *against* — so the parallel lanes
+never diverge into a mock-vs-real integration cliff.
+
+The values here are **golden expectations**, deliberately hard-coded (not derived
+from ``panel_invoker``) so a change to today's panel constants trips
+``tests/test_advisor_board_backcompat.py`` instead of silently re-baselining. The
+back-compat proof re-derives each default seat's invocation and asserts it equals
+today's literals in ``panel_invoker`` (``DEFAULT_LEG_MODELS`` +
+``_API_KEY_VARS``).
+"""
+from __future__ import annotations
+
+from .schema import (
+    AUTH_SUBSCRIPTION,
+    BACKING_HOMEBREW,
+    Board,
+    Seat,
+)
+
+# The built-3 panel legs, in ``panel_invoker.PANEL_LEGS`` order — the order the
+# default board's seats MUST preserve for byte-for-byte back-compat.
+CANONICAL_LEG_ORDER: tuple[str, ...] = ("codex", "gemini", "claude")
+
+# The default board's three seats — model-first, effort split out of the model
+# name. These reconstruct today's ``DEFAULT_LEG_MODELS`` under
+# ``harness_mapping.render_seat_invocation``:
+#   codex  gpt-5.5           + effort max  -> ``-c model_reasoning_effort=xhigh``
+#   gemini "Gemini 3.1 Pro"  + effort high -> model ``"Gemini 3.1 Pro (High)"``
+#   claude claude-fable-5    + effort max  -> ``--effort max``
+#
+# The claude seat runs Fable (``claude-fable-5``): pre-merge review is a mid-tier
+# decision where being wrong is expensive, so the default review board reviews on
+# Fable, not on the implementer model ``claude-sonnet-5``. This is byte-pinned to
+# ``panel_invoker.DEFAULT_LEG_MODELS["claude"]`` (also Fable) by the golden proof.
+DEFAULT_SEATS: tuple[Seat, ...] = (
+    Seat(model="gpt-5.5", effort="max", harness="codex",
+         auth=AUTH_SUBSCRIPTION, backing=BACKING_HOMEBREW),
+    Seat(model="Gemini 3.1 Pro", effort="high", harness="gemini",
+         auth=AUTH_SUBSCRIPTION, backing=BACKING_HOMEBREW),
+    Seat(model="claude-fable-5", effort="max", harness="claude",
+         auth=AUTH_SUBSCRIPTION, backing=BACKING_HOMEBREW),
+)
+
+DEFAULT_BOARD: Board = Board(
+    name="default",
+    purpose="premerge-review",
+    seats=DEFAULT_SEATS,
+    allow_api_key_fallback=False,
+)
+
+# Golden literals the default seats must reproduce (cross-checked in the
+# back-compat test against the live ``panel_invoker`` constants).
+DEFAULT_SEAT_RENDERED_MODEL: dict[str, str] = {
+    "codex": "gpt-5.5",
+    "gemini": "Gemini 3.1 Pro (High)",
+    "claude": "claude-fable-5",
+}
+DEFAULT_SEAT_EFFORT_ARGS: dict[str, tuple[str, ...]] = {
+    "codex": ("-c", "model_reasoning_effort=xhigh"),
+    "gemini": (),
+    "claude": ("--effort", "max"),
+}
+
+# Canonical (model x harness) pairs ABDREG's matrix + ABDRESOLVE's validation test
+# against. Same-vendor-across-harness (gpt-5.5 on codex and opencode) is VALID and
+# projects to one family; a cross-vendor mismatch (gpt-5.5 on claude) is INVALID.
+CANONICAL_VALID_PAIRS: tuple[tuple[str, str], ...] = (
+    ("gpt-5.5", "codex"),
+    ("gpt-5.5", "opencode"),
+    ("claude-sonnet-5", "claude"),
+    ("Gemini 3.1 Pro", "gemini"),
+)
+CANONICAL_INVALID_PAIRS: tuple[tuple[str, str], ...] = (
+    ("gpt-5.5", "claude"),        # openai-family model on the claude lane
+    ("claude-sonnet-5", "codex"),  # anthropic model on the codex lane
+)
+
+# A two-same-vendor-seat board: exercises result re-keying (leg -> seat) and the
+# governed reviewer != author disjointness under model-first (both seats project
+# to ``codex``). Used by ABDRESOLVE / ABDHOME.
+TWO_SAME_VENDOR_BOARD: Board = Board(
+    name="two-openai",
+    purpose="brainstorm",
+    seats=(
+        Seat(model="gpt-5.5", effort="high", harness="codex"),
+        Seat(model="gpt-5.5", effort="high", harness="opencode"),
+    ),
+)

phase_loop_runtime/advisor_board/harness_mapping.py

@@ -0,0 +1,125 @@
+"""Per-harness model/effort -> invocation mapping (IF-0-ABDFREEZE-1).
+
+The v5 panel-verification found that **per-leg effort is NOT supported today** —
+it is hard-coded per leg (claude ``--effort max`` panel_invoker.py:324, codex
+``model_reasoning_effort=xhigh`` :992) and for the agy/gemini leg **effort is
+baked into the model-name string** (``"Gemini 3.1 Pro (High)"`` :51/:1016). The
+model-first ``{model, effort}`` split therefore needs a per-harness mapping that
+turns a canonical ``(model, effort)`` back into each harness's actual invocation.
+
+This module freezes that contract. ABDHOME does the plumbing (reaching the real
+CLI arg lists in `panel_invoker`); it codes against ``render_seat_invocation``.
+The freeze is load-bearing for back-compat: the ``default`` board's three seats
+MUST render to today's exact literals —
+
+    claude  -> effort flag        ``--effort max``
+    codex   -> config override    ``-c model_reasoning_effort=xhigh``
+    gemini  -> model-name embed   ``Gemini 3.1 Pro (High)``
+
+— proven by ``tests/test_advisor_board_backcompat.py`` against the live
+`panel_invoker` constants (`DEFAULT_LEG_MODELS`, the codex/claude/agy arg forms).
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .schema import EFFORT_LEVELS
+
+
+class EffortMappingError(NotImplementedError):
+    """Raised when a harness's effort mapping is not frozen here (breadth lanes
+    land in ABDREG/ABDHOME/ABDOMNI)."""
+
+
+# Effort mechanism: HOW the effort reaches the CLI for a harness.
+MECH_FLAG = "flag"          # a dedicated flag, e.g. claude ``--effort <level>``
+MECH_CONFIG = "config"      # a ``-c key=value`` override, e.g. codex reasoning
+MECH_MODEL_NAME = "model_name"  # baked into the model string, e.g. agy/gemini
+
+
+@dataclass(frozen=True)
+class SeatInvocation:
+    """The frozen, harness-specific shape ``(model, effort)`` renders to.
+
+    ``model``        the model string to pass to the CLI (effort-embedded for the
+                     ``model_name`` mechanism; otherwise the model verbatim).
+    ``effort_args``  extra CLI args carrying effort (empty for ``model_name``).
+    ``mechanism``    one of ``MECH_FLAG`` / ``MECH_CONFIG`` / ``MECH_MODEL_NAME``.
+    ``harness``      the execution lane this rendering targets.
+    """
+
+    harness: str
+    model: str
+    effort_args: tuple[str, ...]
+    mechanism: str
+
+
+# canonical effort -> codex ``model_reasoning_effort`` token. codex's max reasoning
+# is ``xhigh`` (panel_invoker.py:992), so canonical ``max`` -> ``xhigh``.
+_CODEX_EFFORT: dict[str, str] = {
+    "low": "low",
+    "medium": "medium",
+    "high": "high",
+    "max": "xhigh",
+}
+
+# canonical effort -> the ``(Word)`` token agy/gemini bakes into the model name
+# (panel_invoker.py:1016 uses ``(High)``).
+_GEMINI_EFFORT_WORD: dict[str, str] = {
+    "low": "Low",
+    "medium": "Medium",
+    "high": "High",
+    "max": "Max",
+}
+
+# strip a trailing ``" (Effort)"`` embed so re-rendering is idempotent when a caller
+# passes an already-baked model string (e.g. ``"Gemini 3.1 Pro (High)"``). Matches
+# ONLY the four canonical effort words (the Title-case tokens ``render_gemini_model``
+# emits) — a model whose name genuinely ends in a parenthetical (e.g.
+# ``"Gemini 3.1 Pro (Preview)"``) is a DIFFERENT model and must be left untouched,
+# never silently rewritten to a lower effort.
+_GEMINI_EMBED_RE = re.compile(r"\s*\((?:Low|Medium|High|Max)\)\s*$")
+
+
+def gemini_base_model(model: str) -> str:
+    """Return the gemini model with any trailing ``(Effort)`` embed removed."""
+    return _GEMINI_EMBED_RE.sub("", model or "").strip()
+
+
+def render_gemini_model(model: str, effort: str) -> str:
+    """``("Gemini 3.1 Pro", "high") -> "Gemini 3.1 Pro (High)"`` — the agy leg's
+    effort-in-the-model-name special case. Idempotent on an already-baked model."""
+    _require_effort(effort)
+    return f"{gemini_base_model(model)} ({_GEMINI_EFFORT_WORD[effort]})"
+
+
+def _require_effort(effort: str) -> None:
+    if effort not in EFFORT_LEVELS:
+        raise ValueError(f"effort {effort!r} not in {EFFORT_LEVELS}")
+
+
+def render_seat_invocation(harness: str, model: str, effort: str) -> SeatInvocation:
+    """Freeze: turn a canonical ``(harness, model, effort)`` into its CLI invocation.
+
+    Only the built-3 homebrew lanes (claude / codex / gemini) are frozen here —
+    they are what the ``default`` board's back-compat proof rides on. Breadth
+    lanes (opencode / pi / cursor / amp) raise ``EffortMappingError`` until
+    ABDREG/ABDHOME/ABDOMNI populate them; a board with an unmapped lane degrades
+    skip-with-warning, never silently drops effort.
+    """
+    _require_effort(effort)
+    lane = (harness or "").lower()
+    if lane == "claude":
+        # panel_invoker.py:322-325 -> ``--model <model> --effort <level>``
+        return SeatInvocation(lane, model, ("--effort", effort), MECH_FLAG)
+    if lane == "codex":
+        # panel_invoker.py:991-992 -> ``--model <model> -c model_reasoning_effort=<tok>``
+        token = _CODEX_EFFORT[effort]
+        return SeatInvocation(lane, model, ("-c", f"model_reasoning_effort={token}"), MECH_CONFIG)
+    if lane == "gemini":
+        # panel_invoker.py:1016 -> effort baked into ``--model "<base> (Word)"``
+        return SeatInvocation(lane, render_gemini_model(model, effort), (), MECH_MODEL_NAME)
+    raise EffortMappingError(
+        f"effort mapping for harness {harness!r} is populated in ABDREG/ABDHOME/ABDOMNI"
+    )