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

phase_loop_runtime/advisor_board/CONTRACTS.md

@@ -0,0 +1,257 @@
+# Advisor Board — Frozen Contracts (Phase 1 ABDFREEZE)
+
+Interface-freeze for the model-first, multi-harness Advisor Board
+(`specs/phase-plans-v5.md`). Everything here is **additive and behavior-neutral**:
+no running path changes, `panel_invoker` is untouched, and the `default` board
+reproduces today's 3-leg panel byte-for-byte. Downstream phases (ABDREG,
+ABDRESOLVE, ABDHOME) code against these interfaces so the fan-out integrates
+without a big-bang.
+
+Where a contract must reproduce today's behavior, the anchor line in
+`phase-loop-runtime/src/phase_loop_runtime/panel_invoker.py` is cited and the
+equivalence is proven by a test (not asserted in prose).
+
+## IF-0-ABDFREEZE-1 — Seat + Board schema (model-first) · `schema.py`, `harness_mapping.py`
+
+- **`Seat{model, effort, harness?, lens?, auth?, backing?, host_leg?}`** — a seat
+  is a cognition; the harness is a defaulted-but-overridable execution *lane*, not
+  the primary key. `effort` is a canonical level in `EFFORT_LEVELS =
+  (low, medium, high, max)`. Frozen dataclass with fail-closed validation.
+- **`Board{name, purpose, seats:[Seat], allow_api_key_fallback=false}`** —
+  named, purpose-tagged, open-ended seat list; rejects api-key seats unless the
+  board opts in.
+- **Config format + location** — `$XDG_CONFIG_HOME/agent-harness/advisor-boards.toml`
+  (`board_config_path()`); shape frozen by `fixtures/advisor-boards.example.toml`.
+  The loader is ABDREG.
+- **Per-harness model/effort mapping** — `render_seat_invocation(harness, model,
+  effort) -> SeatInvocation`. Freezes how `seat.effort` reaches each CLI, incl.
+  the **agy/gemini leg where effort is embedded in the model-name string**
+  (`render_gemini_model`, panel_invoker.py:1016). Built-3 lanes are concrete;
+  breadth lanes raise `EffortMappingError` until ABDREG/ABDHOME/ABDOMNI.
+  Round-trip (proven): claude→`--effort max` (:324), codex→
+  `-c model_reasoning_effort=xhigh` (:992), gemini→`"Gemini 3.1 Pro (High)"` (:1016).
+- **Seat identity for result re-keying** — `Seat.seat_key` is a stable LABEL over
+  every distinguishing field (lane, model, effort, lens), so lens-only-different
+  seats get distinct keys. It is not a guaranteed-unique id — a board may hold two
+  byte-identical seats — so ABDRESOLVE keys results by **seat position** and uses
+  `seat_key` only as the label.
+- **Host-leg identity** — `Seat.host_leg` marker + `identify_host_leg(board,
+  HostContext)`. A seat is the native in-process host leg only when the board runs
+  *inside* that harness (`HostContext.host_harness`). The standalone runner
+  (`host_harness=None`) has no host leg — every leg is a subprocess, exactly as
+  today.
+- **Seat → vendor-family projection** — `vendor_family(model, harness)` /
+  `seat_vendor_family(seat)`, model-first with a harness-lane fallback.
+  Byte-consistent with `governed_review.author_vendor_for_model` (:60-75) and
+  `_EXECUTOR_VENDOR` (:47-53). Two same-vendor seats on different harnesses
+  (`gpt-5.5` on `codex` and on `opencode`) project to the same family, so the
+  governed reviewer≠author disjointness survives model-first. ABDHOME rewires the
+  governed gates onto *this* canonical function (not a copy).
+
+## IF-0-ABDFREEZE-2 — Registry interfaces + shared fixtures · `registries.py`, `fixtures.py`
+
+- **Interfaces (Protocols):** `HarnessRegistry`, `ModelRegistry`,
+  `CompatibilityMatrix` with `is_valid(model, harness) -> (bool,
+  AuthAvailability)` and `default_lane(model) -> str`.
+- **Frozen return types:** `HarnessSpec`, `ModelSpec`, `AuthAvailability`
+  (concrete, so no-silent-key is testable), `MatrixVerdict` alias.
+- **Stubs:** `Stub{Harness,Model}Registry`, `StubCompatibilityMatrix` — raise
+  `NotImplementedError`; no six-harness data (that is ABDREG).
+- **Shared canonical fixtures** (the anti-divergence keystone ABDREG populates
+  *from* and ABDRESOLVE/ABDHOME test *against*): `DEFAULT_BOARD`, `DEFAULT_SEATS`,
+  `CANONICAL_LEG_ORDER`, `CANONICAL_VALID_PAIRS`, `CANONICAL_INVALID_PAIRS`,
+  `TWO_SAME_VENDOR_BOARD`.
+
+## IF-0-ABDFREEZE-3 — Provider-backing selector + auth enforcement · `backing.py`
+
+- **Backing selector** — `select_backing(seat, gateway_available) ->
+  BackingDecision`. Per-seat `homebrew | omnigent`; an `omnigent` seat with no
+  gateway degrades **skip-with-warning** (fail-closed — never a silent homebrew
+  breadth fallback).
+- **Auth = active env scrubbing** — `resolve_seat_env(seat, base_env,
+  allow_api_key_fallback)`, freezing the `_subscription_env` pattern
+  (panel_invoker.py:226-230,348-353): a subscription seat scrubs **every** vendor
+  API-key var; an api-key seat (only behind the board opt-in) scrubs everything
+  then injects **only the seat vendor's** key(s). Never silent — an api-key seat
+  without the opt-in raises.
+- **`VENDOR_API_KEY_VARS`** — the flat `_API_KEY_VARS` tuple re-keyed by vendor
+  family; its union equals today's tuple (proven), so scrubbing stays
+  byte-equivalent.
+
+## IF-0-ABDFREEZE-4 — Back-compat contract · `fixtures.py` + `tests/test_advisor_board_backcompat.py`
+
+- The `default` board (`DEFAULT_BOARD`) resolves to today's three seats in
+  `PANEL_LEGS` order, and each seat renders to today's exact model string + effort
+  args (cross-checked against `panel_invoker.DEFAULT_LEG_MODELS` and the
+  codex/claude/agy arg forms). Full assertions (launch order, payloads, env/auth,
+  timeout/retry, result keys, output formatting, failure semantics, `invoke_panel`
+  API) land in ABDVERIFY; this ships the **scaffold + the default-board fixture**.
+- `advisor-panel` stays a working alias of `advisor-board` — the rename + alias is
+  ABDRESOLVE; this contract only *states* the invariant.
+- **Behavior-neutrality proof:** `git diff` on `panel_invoker.py` is empty and the
+  full existing suite is green (this package is purely additive).
+
+## IF-0-ABDFREEZE-5 — Observability contract · `events.py`
+
+- **Internal envelope** — `AdvisorBoardEvent` (our shape, `EVENT_SCHEMA_VERSION =
+  advisor_board.event.v1`, kinds in `EVENT_KINDS`). NOT a guessed Omnigent schema.
+- **launcher ≠ observability-plane** — a natively-launched leg *emits* into a
+  forwarded stream; it is never relaunched through the gateway for observability.
+- **Forwarding is async/best-effort and can never delay or fail the native leg** —
+  `best_effort_forward(sink, event)` swallows every sink error and never raises;
+  `NullSink` keeps the default board a no-op. The mapping to a concrete sink
+  (Omnigent v0.4.0 endpoint, or omniagent-plus ui-read-model/state-ledger) is
+  deferred to ABDOBS — do not freeze against a guessed upstream schema.
+
+## ABDOBS — Observability forwarding (Phase 6) · `observability.py`, `panel_invoker.invoke_board`
+
+Builds the mapping ABDFREEZE-5 deferred. **Confirmed sink:** omniagent-plus's own
+`state-ledger` / `ui-read-model` (we control it) — NOT an Omnigent HTTP ingestion
+endpoint. v0.4.0's HTTP surface is launcher-centric and exposes **no** ingestion
+endpoint for an externally-launched (native) session, so a native leg is
+*observed*, never relaunched.
+
+- **Envelope → sink mapping** — `map_event_to_runtime_event(event, session_id)`
+  and `map_event_to_ledger_record(event, session_id)` project our
+  `AdvisorBoardEvent` onto omniagent-plus's *own frozen* wire shapes:
+  `runtime_event.v0.1` (`core-contracts/src/events.ts`) inside a
+  `state_ledger_record.v0.1`, kind `runtime_event` (`core-contracts/src/state-ledger.ts`)
+  — exactly what `AuditLedger.appendRuntimeEvent` (`state-ledger/src/audit-ledger.ts`)
+  writes. **A board run projects to a session; each seat projects to a turn.** A
+  per-run `sessionId` is minted (`new_session_id()` — never the board name);
+  `turnId` derives from the seat's frozen `seat_key` label. `redaction` is
+  `metadata_only` (never a raw key; `content_allowed` only for a text delta). A
+  `seat.failed` payload conforms to the full `runtime_failure.v0.1` (`errors.ts`)
+  — all of schema/category/retryable/actor/scope/message are required upstream.
+  NB: the record-level `recordId` / `sequence` are meaningful only for the
+  reference `JsonlLedgerWriter`; the real TS `AppendOnlyStore` ASSIGNS them on
+  append (its `AppendRecordInput` has no `sequence`), so a real binding overrides
+  them. The authoritative, per-session sequence is the `runtime_event` payload's.
+- **Cross-language transport seam** — the ledger is TypeScript, the emit is
+  Python, so the boundary is `LedgerWriter` (a Protocol a real omniagent-plus
+  binding implements over IPC/HTTP/a shared file) + `JsonlLedgerWriter`, a
+  reference transport appending the exact `state_ledger_record.v0.1` records the TS
+  `AppendOnlyStore` ingests. We do **not** reimplement ledger internals
+  (retention / replay / compaction stay TS-side). This is the integration seam.
+- **Async / best-effort (never delays or fails the native leg)** —
+  `AsyncForwardingSink.emit` does a NON-BLOCKING put and returns; a background
+  daemon thread does the real (slow / failing) write via `best_effort_forward`.
+  The never-**raise** guarantee is frozen in `events.py`; the never-**delay**
+  guarantee is here (unbounded queue; a bounded queue drops on full). `BoardObserver`
+  wraps construct+map+enqueue in a swallow-all, so even a bad kind / full queue
+  never touches the leg. `flush()` / `close()` drain deterministically (tests /
+  graceful shutdown only — never on the leg's critical path).
+- **launcher ≠ observability-plane, in code** — every sink here is structurally
+  emit-only (no `create_session` / `send_turn`), so the observability path
+  *cannot* launch a leg. Combined with the frozen `enforce_native_host_leg`
+  (which hard-raises on a gatewayed host leg), the native host leg is observed,
+  never relaunched.
+- **Per-workload boundary (documented + enforced)** — `WORKLOAD_BOARD` =
+  native launch **+ optional forward** (this path); `WORKLOAD_PHASE_EXECUTION` =
+  Omnigent-as-launcher (CS-2.2, out of scope here). `invoke_board(sink=...)` is
+  the ONLY opt-in; `sink=None` builds no envelope (default board byte-neutral).
+  `invoke_panel` is untouched, so the live default panel is byte-neutral by
+  construction.
+- **Key-file note (reviewers):** the phase plan lists
+  `agent_runtime_provider.py`; the emit lands in `panel_invoker.invoke_board`
+  instead, because the envelope's vocabulary is `board.*` / `seat.*` (with
+  `seat_key` / `vendor_family` / `harness`) which only the board seam knows — the
+  provider only knows sessions/turns and cannot populate it. `observability.py`
+  maps our envelope onto the provider-mirrored `runtime_event.v0.1` shape, so the
+  provider layer is still the wire target, just not the emit site.
+
+## ABDPRESET — Board preset library + Fable review-path · `presets.py`, `panel_invoker.py`
+
+The seven built-in presets (`presets.PRESETS`). Every preset self-validates against
+the real matrix at `load_boards()` time (`tests/test_advisor_board_config.py`,
+`tests/test_advisor_board_integration.py`).
+
+- **Review-class = Fable, decoupled from the implementer.** Pre-merge and legal
+  review are mid-tier decisions where being wrong is expensive, so the review-class
+  boards (`default`, `code-review`, `legal-review`, `legal-strategy-review`) seat
+  Fable (`claude-fable-5`) on the claude lane — NOT the implementer model
+  `profiles.CLAUDE_IMPLEMENTER_MODEL` (`claude-sonnet-5`). `panel_invoker.DEFAULT_LEG_MODELS["claude"]`
+  is the SINGLE source of truth for the panel's default claude model: the claude
+  leg builder (`_claude_tui_command`) and the Agent-View attempt both read it, so
+  the *legacy* `invoke_panel` path AND the live governed gates
+  (`governed_review` / `governed_premerge`, which call `invoke_panel` with no model
+  override) review on Fable. `CLAUDE_IMPLEMENTER_MODEL` is untouched — the
+  implementer stays Sonnet. The `default` board (`fixtures.DEFAULT_BOARD`) is
+  byte-pinned to this Fable `invoke_panel` panel by the golden proof
+  (`tests/test_advisor_board_golden.py`); the sole sanctioned delta stays `seat_key`.
+- **`code-review` = three frontier vendors, always.** codex `gpt-5.5`,
+  `Gemini 3.1 Pro`, and `claude-fable-5`, each on the `adversarial` lens (supersedes
+  the prior two-seat codex+sonnet composition).
+- **Divergent-thinking boards keep Sonnet.** `brainstorm` / `doc-edit` /
+  `legal-brainstorm` deliberately retain `claude-sonnet-5` — a diverse voice, a
+  low-stakes copyedit, a cheap aggressive ideation seat — where it is the right tool.
+- **Legal boards (`legal-review`, `legal-strategy-review`, `legal-brainstorm`)**
+  encode the PRIMARY review lens per seat. `lens` / `purpose` are free-form strings
+  (`schema.py`), so the legal lenses/purposes need no enum extension.
+- **Catch-alls for unmodeled tasks (`general`, `solo`).** So the board library is not
+  limited to the pre-modeled domains: `general` is the domain-agnostic top-tier PANEL
+  (three frontier vendors — gpt-5.5/adversarial, Gemini 3.1 Pro/alternative,
+  claude-fable-5/completeness — hand it any task + brief), and `solo` is the
+  single-MEMBER form (one `claude-fable-5` seat) for a quick top-end opinion when a
+  panel is overkill. A ONE-seat board validates + resolves through `invoke_board` like
+  any other (bare/single seats are supported). Both default to TOP-END models: an
+  unanticipated task cannot be assumed low-stakes, so the safe default is frontier —
+  dial down explicitly (a cheaper board) when a task is known-cheap. Their lenses
+  (`adversarial`/`alternative`/`completeness`) and purpose (`general`) are free-form
+  strings, so no enum extension.
+- **Deep-seat FOLLOW-ON (documented, NOT built here).** The richer legal treatment —
+  four lenses per seat, an apex-Opus (`claude-opus-4-8`) seat, a verify-round, and
+  retrieval-grounded citation-verification — is a deliberate follow-on. The current
+  legal boards ship the single-primary-lens-per-seat form; the deep-seat form layers
+  onto the same seat/board schema (no schema change) when built.
+
+## ABDPAR — Concurrent leg execution · `panel_invoker.invoke_board` / `invoke_panel`
+
+`invoke_board` and `invoke_panel` fan their seats/legs out across a bounded
+`ThreadPoolExecutor` (`_run_legs_ordered`), not a sequential loop — legs are blocking
+subprocess I/O (the CLI wait releases the GIL), so wall-clock is `~max(leg)`, not
+`sum(leg)`.
+
+- **Parallel is the DEFAULT (opt-out, not opt-in).** Both entry points take a single
+  `max_concurrency: int | None = None` knob, threaded through the governed gates
+  (`governed_planning_gate` → `run_governed_premerge_loop` → `governed_premerge_for_run`)
+  so a caller CAN request sequential, while the default everywhere stays parallel:
+  - `None` (default) → parallel, bounded by `min(len(seats), 8)`.
+  - `1` → sequential (the opt-in escape hatch — debugging, a rate-limited / throttled
+    provider, a constrained host).
+  - `N` → cap concurrency at `N`.
+  It is the SAME thread-pool path: `max_workers = max(1, min(max_concurrency or len(seats), 8))`,
+  so `max_concurrency=1` degrades to one worker (strictly serial) with no separate
+  sequential branch. `max_concurrency` is a keyword-only, default-valued additive
+  extension to the frozen `invoke_panel` signature (back-compat, like `models` #66).
+
+Frozen invariants (concurrency is a **timing-only** change — never a leg's outcome;
+the golden proves byte-identity):
+
+- **Positional order** — futures are submitted in seat/leg order and read back by
+  index, so `result[i]` corresponds to `seats[i]`/`legs[i]` regardless of finish
+  order. `resolver.key_results_by_seat` re-keys by position and the golden asserts
+  order + content, so this is load-bearing.
+- **Fail-closed per seat** — the extracted per-seat/per-leg body returns a DEGRADED
+  `PanelLegResult` on any exception, so a future's `.result()` never raises and one
+  broken leg can never crash the pool or the board.
+- **Single shared reads before the pool** — the one `GET /v1/harnesses` gateway-catalog
+  fetch and the seat-validation/host-leg checks stay ABOVE the pool (one fetch, shared
+  read); the observability emit stays AFTER, in seat order. Bounded `max_workers =
+  min(len(seats), 8)`.
+- **Proof** — a `threading.Barrier(N)` test proves both directions without real sleeps:
+  the DEFAULT satisfies the barrier (all N legs in-flight at once → all OK), and
+  `max_concurrency=1` makes the same barrier unsatisfiable (one worker → it times out →
+  fail-closed DEGRADED), so the pair discriminates parallel from sequential. A third
+  test confirms sequential mode returns byte-identical ordered results.
+- **Thread-safety of the real leg paths** — the leg execs install NO signal handlers or
+  timers (`signal.signal` / `alarm` / `setitimer` would raise `ValueError: signal only
+  works in main thread` off the main thread); the only `signal.` use is `os.killpg(pid,
+  SIGTERM/SIGKILL)` (a constant, thread-safe), and timeouts run on `select.select(...)`
+  / `subprocess.run(timeout=...)`, not `SIGALRM`. Each leg stages its own temp review
+  dir, so concurrent legs never share filesystem state. Verified: the real `spawn=None`
+  path runs inside worker threads with no signal-in-thread error.
+- **Known edge (untested):** a custom board with two seats on the SAME lane (e.g. two
+  `claude` seats) now runs two concurrent same-lane CLI/PTY sessions — a scenario this
+  fan-out newly enables and nothing yet tests. The `default` board has one claude seat,
+  so it is unaffected.

phase_loop_runtime/advisor_board/__init__.py

@@ -0,0 +1,288 @@
+"""Advisor Board — frozen contracts (Phase 1 ABDFREEZE).
+
+Interface-only preamble for the model-first, multi-harness Advisor Board
+(specs/phase-plans-v5.md). This package ships the typed contracts + importable
+stubs + shared canonical fixtures the parallel fan-out (ABDREG / ABDRESOLVE /
+ABDHOME) codes against. It is ADDITIVE and behavior-neutral: nothing here touches
+the running ``panel_invoker`` path.
+
+Frozen gates (see ``CONTRACTS.md``):
+* IF-0-ABDFREEZE-1 — seat/board schema, config location, per-harness model/effort
+  mapping, host-leg identity, seat -> vendor-family projection (``schema`` +
+  ``harness_mapping``).
+* IF-0-ABDFREEZE-2 — registry interfaces + (model x harness) matrix API + shared
+  canonical fixtures (``registries`` + ``fixtures``).
+* IF-0-ABDFREEZE-3 — provider-backing selector + auth-enforcement (active env
+  scrubbing) contract (``backing``).
+* IF-0-ABDFREEZE-4 — back-compat: the ``default`` board reproduces today's 3-leg
+  behavior (``fixtures.DEFAULT_BOARD`` + the golden-test scaffold).
+* IF-0-ABDFREEZE-5 — internal advisor-board event envelope + best-effort
+  forwarding (``events``); its concrete sink mapping lands in ABDOBS.
+
+ABDOBS (Phase 6) then adds ``observability``: the envelope → omniagent-plus
+state-ledger (``state_ledger_record.v0.1`` / ``runtime_event.v0.1``) mapping, an
+:class:`~observability.AsyncForwardingSink` for off-thread best-effort dispatch,
+and the ``LedgerWriter`` cross-language transport seam. This is the one place the
+package touches ``panel_invoker`` — an OPT-IN ``sink=`` on ``invoke_board``;
+``sink=None`` stays byte-neutral.
+"""
+from __future__ import annotations
+
+from .schema import (
+    AUTH_API_KEY,
+    AUTH_LANES,
+    AUTH_SUBSCRIPTION,
+    BACKING_HOMEBREW,
+    BACKING_OMNIGENT,
+    CONFIG_RELATIVE_PATH,
+    EFFORT_LEVELS,
+    PROVIDER_BACKINGS,
+    Board,
+    HostContext,
+    Seat,
+    board_config_path,
+    identify_host_leg,
+    seat_vendor_family,
+    vendor_family,
+    vendor_of_harness,
+    vendor_of_model,
+)
+from .harness_mapping import (
+    EffortMappingError,
+    MECH_CONFIG,
+    MECH_FLAG,
+    MECH_MODEL_NAME,
+    SeatInvocation,
+    gemini_base_model,
+    render_gemini_model,
+    render_seat_invocation,
+)
+from .registries import (
+    DEFAULT_HARNESS_REGISTRY,
+    DEFAULT_MODEL_REGISTRY,
+    AuthAvailability,
+    CompatibilityMatrix,
+    DefaultHarnessRegistry,
+    DefaultModelRegistry,
+    HarnessRegistry,
+    HarnessSpec,
+    MatrixVerdict,
+    ModelRegistry,
+    ModelSpec,
+    StubCompatibilityMatrix,
+    StubHarnessRegistry,
+    StubModelRegistry,
+    UnknownHarnessError,
+    UnknownModelError,
+)
+from .matrix import (
+    DefaultCompatibilityMatrix,
+    default_matrix,
+)
+from .presets import (
+    DEFAULT_BOARD_NAME,
+    PRESET_NAMES,
+    PRESETS,
+    get_preset,
+)
+from .config import (
+    BoardConfig,
+    BoardConfigError,
+    load_boards,
+)
+from .backing import (
+    VENDOR_API_KEY_VARS,
+    BackingDecision,
+    all_vendor_key_vars,
+    resolve_seat_env,
+    select_backing,
+)
+from .backing_omnigent import (
+    OMNIGENT_FREEZE_TARGET,
+    HARNESS_ENDPOINT,
+    SESSION_ENDPOINTS,
+    VENDOR_KEY_HEADER_PREFIX,
+    OmnigentBacking,
+    OmnigentGatewayUnavailable,
+    OmnigentHttpClient,
+    OmnigentHttpError,
+    SeatRunOutcome,
+    classify_http_failure,
+)
+from .events import (
+    EVENT_KINDS,
+    EVENT_SCHEMA_VERSION,
+    AdvisorBoardEvent,
+    EventSink,
+    NullSink,
+    best_effort_forward,
+)
+from .observability import (
+    LEDGER_RECORD_KIND,
+    LEDGER_RECORD_SCHEMA,
+    RUNTIME_EVENT_SCHEMA,
+    RUNTIME_FAILURE_SCHEMA,
+    WORKLOAD_BOARD,
+    WORKLOAD_PHASE_EXECUTION,
+    AsyncForwardingSink,
+    BoardObserver,
+    CollectingSink,
+    JsonlLedgerWriter,
+    LedgerWriter,
+    StateLedgerSink,
+    map_event_to_ledger_record,
+    map_event_to_runtime_event,
+    new_session_id,
+)
+from .fixtures import (
+    CANONICAL_INVALID_PAIRS,
+    CANONICAL_LEG_ORDER,
+    CANONICAL_VALID_PAIRS,
+    DEFAULT_BOARD,
+    DEFAULT_SEAT_EFFORT_ARGS,
+    DEFAULT_SEAT_RENDERED_MODEL,
+    DEFAULT_SEATS,
+    TWO_SAME_VENDOR_BOARD,
+)
+from .resolver import (
+    BOARD_ALIASES,
+    STANDIN_BOARDS,
+    BoardResolutionError,
+    BoardResolver,
+    SeatSpecError,
+    key_results_by_seat,
+    parse_seat_spec,
+    parse_seats,
+    resolve_board,
+    seat_result_key,
+)
+from .validation import (
+    SeatValidationError,
+    SeatVerdict,
+    validate_board,
+    validate_seat,
+)
+
+__all__ = [
+    # schema
+    "Seat",
+    "Board",
+    "HostContext",
+    "EFFORT_LEVELS",
+    "AUTH_LANES",
+    "AUTH_SUBSCRIPTION",
+    "AUTH_API_KEY",
+    "PROVIDER_BACKINGS",
+    "BACKING_HOMEBREW",
+    "BACKING_OMNIGENT",
+    "CONFIG_RELATIVE_PATH",
+    "board_config_path",
+    "identify_host_leg",
+    "seat_vendor_family",
+    "vendor_family",
+    "vendor_of_harness",
+    "vendor_of_model",
+    # harness mapping
+    "SeatInvocation",
+    "render_seat_invocation",
+    "render_gemini_model",
+    "gemini_base_model",
+    "EffortMappingError",
+    "MECH_FLAG",
+    "MECH_CONFIG",
+    "MECH_MODEL_NAME",
+    # registries
+    "HarnessSpec",
+    "ModelSpec",
+    "AuthAvailability",
+    "MatrixVerdict",
+    "HarnessRegistry",
+    "ModelRegistry",
+    "CompatibilityMatrix",
+    "StubHarnessRegistry",
+    "StubModelRegistry",
+    "StubCompatibilityMatrix",
+    # registries — populated (ABDREG)
+    "DefaultHarnessRegistry",
+    "DefaultModelRegistry",
+    "DEFAULT_HARNESS_REGISTRY",
+    "DEFAULT_MODEL_REGISTRY",
+    "UnknownHarnessError",
+    "UnknownModelError",
+    # matrix (ABDREG) — seat/board validation is exported from validation below
+    "DefaultCompatibilityMatrix",
+    "default_matrix",
+    # presets + config loader (ABDREG)
+    "PRESETS",
+    "PRESET_NAMES",
+    "DEFAULT_BOARD_NAME",
+    "get_preset",
+    "BoardConfig",
+    "BoardConfigError",
+    "load_boards",
+    # backing + auth
+    "VENDOR_API_KEY_VARS",
+    "all_vendor_key_vars",
+    "BackingDecision",
+    "select_backing",
+    "resolve_seat_env",
+    # backing — omnigent transport (ABDOMNI)
+    "OMNIGENT_FREEZE_TARGET",
+    "HARNESS_ENDPOINT",
+    "SESSION_ENDPOINTS",
+    "VENDOR_KEY_HEADER_PREFIX",
+    "OmnigentBacking",
+    "OmnigentHttpClient",
+    "OmnigentHttpError",
+    "OmnigentGatewayUnavailable",
+    "SeatRunOutcome",
+    "classify_http_failure",
+    # events
+    "AdvisorBoardEvent",
+    "EventSink",
+    "NullSink",
+    "best_effort_forward",
+    "EVENT_KINDS",
+    "EVENT_SCHEMA_VERSION",
+    # observability (ABDOBS)
+    "WORKLOAD_BOARD",
+    "WORKLOAD_PHASE_EXECUTION",
+    "LEDGER_RECORD_SCHEMA",
+    "RUNTIME_EVENT_SCHEMA",
+    "RUNTIME_FAILURE_SCHEMA",
+    "LEDGER_RECORD_KIND",
+    "new_session_id",
+    "map_event_to_runtime_event",
+    "map_event_to_ledger_record",
+    "LedgerWriter",
+    "JsonlLedgerWriter",
+    "StateLedgerSink",
+    "CollectingSink",
+    "AsyncForwardingSink",
+    "BoardObserver",
+    # fixtures
+    "DEFAULT_BOARD",
+    "DEFAULT_SEATS",
+    "DEFAULT_SEAT_RENDERED_MODEL",
+    "DEFAULT_SEAT_EFFORT_ARGS",
+    "CANONICAL_LEG_ORDER",
+    "CANONICAL_VALID_PAIRS",
+    "CANONICAL_INVALID_PAIRS",
+    "TWO_SAME_VENDOR_BOARD",
+    # resolver (ABDRESOLVE)
+    "BoardResolver",
+    "resolve_board",
+    "parse_seat_spec",
+    "parse_seats",
+    "SeatSpecError",
+    "BoardResolutionError",
+    "BOARD_ALIASES",
+    "STANDIN_BOARDS",
+    "seat_result_key",
+    "key_results_by_seat",
+    # validation (ABDRESOLVE)
+    "validate_seat",
+    "validate_board",
+    "SeatValidationError",
+    "SeatVerdict",
+]

phase_loop_runtime/advisor_board/backing.py

@@ -0,0 +1,137 @@
+"""Provider-backing selector + auth-enforcement contract (IF-0-ABDFREEZE-3).
+
+Two orthogonal per-seat axes, frozen here:
+
+* **backing** (``homebrew | omnigent``) — the transport. Selected per seat;
+  ``homebrew`` is the default and keeps the built-3 + native host leg.
+* **auth** (``subscription | api_key``) — the credential lane. Subscription is
+  the default; api-key is reachable only behind ``Board.allow_api_key_fallback``.
+
+**No-silent-key is enforced by ACTIVE environment scrubbing**, freezing the
+existing ``_subscription_env`` pattern (panel_invoker.py:226-230,348-353) into a
+per-seat, vendor-keyed contract:
+
+* a **subscription** seat scrubs EVERY vendor API-key var from the subprocess env
+  / gateway payload (identical to ``_subscription_env`` today); and
+* an **api-key fallback** seat scrubs everything, then injects ONLY the seat
+  vendor's key var(s) — never another vendor's, never silently.
+
+``VENDOR_API_KEY_VARS`` is the flat ``panel_invoker._API_KEY_VARS`` tuple
+re-expressed keyed by vendor family, so "inject only the seat vendor's key" is
+expressible. The union of its values equals the current flat tuple (asserted in
+``tests/test_advisor_board_backcompat.py``), so scrubbing stays byte-equivalent.
+The reference env functions below are pure and importable; ABDHOME wires them
+into the real launch/gateway env (this module changes no running path).
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from .schema import (
+    AUTH_API_KEY,
+    AUTH_SUBSCRIPTION,
+    BACKING_HOMEBREW,
+    BACKING_OMNIGENT,
+    PROVIDER_BACKINGS,
+    Seat,
+    seat_vendor_family,
+)
+
+
+# Vendor family -> the provider API-key env var(s) that vendor authenticates with.
+# The UNION of all values MUST equal ``panel_invoker._API_KEY_VARS`` so subscription
+# scrubbing is byte-equivalent to ``_subscription_env`` today.
+VENDOR_API_KEY_VARS: dict[str, tuple[str, ...]] = {
+    "codex": ("OPENAI_API_KEY",),
+    "claude": ("ANTHROPIC_API_KEY",),
+    "gemini": ("GEMINI_API_KEY", "GOOGLE_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"),
+}
+
+
+def all_vendor_key_vars() -> tuple[str, ...]:
+    """Every vendor API-key var (scrub set for a subscription seat)."""
+    seen: list[str] = []
+    for vars_ in VENDOR_API_KEY_VARS.values():
+        for var in vars_:
+            if var not in seen:
+                seen.append(var)
+    return tuple(seen)
+
+
+# --- backing selector -------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class BackingDecision:
+    """Which transport a seat resolves to, and why. Fail-closed: an ``omnigent``
+    seat whose gateway is unavailable degrades to ``skip`` (never a silent
+    homebrew fallback for a breadth harness — hand-writing breadth defeats the
+    Omnigent maintenance-offload, per ABDHOME non-goals)."""
+
+    backing: str
+    skip: bool = False
+    reason: str = ""
+
+
+def select_backing(seat: Seat, *, gateway_available: bool = True) -> BackingDecision:
+    """Freeze the selector contract: honor ``seat.backing``; an ``omnigent`` seat
+    with no gateway degrades skip-with-warning. ABDHOME/ABDOMNI supply the real
+    availability probes; this fixes the DECISION SHAPE they return."""
+    if seat.backing not in PROVIDER_BACKINGS:
+        raise ValueError(f"seat.backing {seat.backing!r} not in {PROVIDER_BACKINGS}")
+    if seat.backing == BACKING_OMNIGENT and not gateway_available:
+        return BackingDecision(BACKING_OMNIGENT, skip=True, reason="omnigent gateway unavailable")
+    return BackingDecision(seat.backing)
+
+
+# --- auth enforcement (active env scrubbing) --------------------------------
+
+
+def resolve_seat_env(
+    seat: Seat,
+    base_env: Mapping[str, str],
+    *,
+    allow_api_key_fallback: bool = False,
+) -> dict[str, str]:
+    """Reference implementation of the frozen no-silent-key env contract.
+
+    * Always scrub EVERY vendor API-key var from a copy of ``base_env`` (the
+      ``_subscription_env`` behavior — a subscription seat ends here).
+    * For an ``api_key`` seat, and ONLY when the board opts in
+      (``allow_api_key_fallback``), re-inject ONLY the seat vendor's key var(s)
+      from ``base_env``. Any other lane / a disallowed board leaves the env
+      scrubbed (fail-closed).
+
+    Raises when a seat requests the api-key lane without the board opt-in, so a
+    silent key can never slip through. Pure and side-effect-free; ABDHOME wires
+    it into the subprocess/gateway env.
+    """
+    env = {k: v for k, v in base_env.items() if k not in all_vendor_key_vars()}
+    if seat.auth == AUTH_SUBSCRIPTION:
+        return env
+    if seat.auth == AUTH_API_KEY:
+        if not allow_api_key_fallback:
+            raise ValueError(
+                f"seat {seat.seat_key} requests the api_key lane but the board did not "
+                "opt in (allow_api_key_fallback=False) — never-silent-key"
+            )
+        vendor = seat_vendor_family(seat)
+        for var in VENDOR_API_KEY_VARS.get(vendor, ()):  # ONLY this vendor's key(s)
+            if var in base_env:
+                env[var] = base_env[var]
+        return env
+    raise ValueError(f"unknown seat.auth {seat.auth!r}")
+
+
+__all__ = [
+    "VENDOR_API_KEY_VARS",
+    "all_vendor_key_vars",
+    "BackingDecision",
+    "select_backing",
+    "resolve_seat_env",
+    "AUTH_SUBSCRIPTION",
+    "AUTH_API_KEY",
+    "BACKING_HOMEBREW",
+    "BACKING_OMNIGENT",
+]