okstra 0.147.0 → 0.148.0

package/runtime/python/okstra_ctl/codex_dispatch.py

@@ -1,10 +1,8 @@
-"""Codex lead CLI-worker dispatcher.
+"""CLI-wrapper dispatcher for a Codex-hosted Okstra lead.
 
-This module is intentionally narrower than the Claude Code team dispatcher. It
-reads an already-prepared Codex run manifest and dispatches only workers that
-have a CLI wrapper path. `report-writer` is supported only through explicit
-Codex opt-in because the prepared manifest still records a Claude-side model by
-default.
+The prepared assignment's ``runner`` field is authoritative. Native Codex
+assignments stay in the host session; this module runs only ``cli-wrapper``
+assignments through their registered provider wrappers.
 """
 from __future__ import annotations
 
@@ -64,12 +62,10 @@ from .report_finalize import (
 )
 from .wrapper_status import status_path_for_prompt
 from .worker_prompt_body import REPORT_WRITER_WORKER_ID
+from .models import provider_wrappers
 
 
-SUPPORTED_CLI_WORKERS = {
-    "codex": "okstra-codex-exec.sh",
-    "antigravity": "okstra-antigravity-exec.sh",
-}
+SUPPORTED_CLI_WORKERS = provider_wrappers("analyser")
 MAX_WORKER_ATTEMPTS = 2
 
 
@@ -120,8 +116,6 @@ def build_dispatch_plan(
     okstra_bin: Path | None = None,
     requested_workers: Sequence[str] = (),
     idle_timeout_seconds: int = 600,
-    enable_codex_report_writer: bool = False,
-    report_writer_codex_model: str = "",
     dispatch_kind: str = "initial",
     jobs_file: Path | None = None,
 ) -> DispatchPlan:
@@ -129,7 +123,6 @@ def build_dispatch_plan(
         project_root,
         run_manifest_path,
         requested_workers,
-        enable_codex_report_writer=enable_codex_report_writer,
         select_roster=jobs_file is None,
     )
     if jobs_file is not None:
@@ -148,7 +141,6 @@ def build_dispatch_plan(
             workspace_root=workspace_root,
             team_state=inputs.team_state,
             selected_workers=inputs.selected_workers,
-            report_writer_codex_model=report_writer_codex_model,
         )
         workers = _build_selected_worker_dispatches(
             project_root=inputs.project_root,
@@ -204,35 +196,34 @@ def _load_dispatch_inputs(
     run_manifest_path: Path,
     requested_workers: Sequence[str],
     *,
-    enable_codex_report_writer: bool,
     select_roster: bool = True,
 ) -> _DispatchInputs:
     project_root = project_root.resolve()
     manifest_path = _resolve_project_path(project_root, str(run_manifest_path))
     manifest = _load_json_object(manifest_path, "run manifest")
     _validate_codex_manifest(manifest, manifest_path)
+    team_state_path = _resolve_required_path(project_root, manifest, "teamStatePath")
+    team_state = _load_json_object(team_state_path, "team-state")
     selected_workers = (
         tuple(
             _select_workers(
                 manifest,
+                team_state,
                 requested_workers,
-                enable_codex_report_writer=enable_codex_report_writer,
             )
         )
         if select_roster
         else ()
     )
-    team_state_path = _resolve_required_path(project_root, manifest, "teamStatePath")
-    team_state = _load_json_object(team_state_path, "team-state")
     if select_roster:
         _mark_skipped_workers(
             team_state_path,
             team_state,
             _skipped_worker_reasons(
                 manifest,
+                team_state,
                 selected_workers,
                 requested_workers,
-                enable_codex_report_writer=enable_codex_report_writer,
             ),
         )
     active_context = _load_optional_json_object(
@@ -257,16 +248,11 @@ def _materialize_selected_worker_prompts(
     workspace_root: Path,
     team_state: Mapping[str, Any],
     selected_workers: Sequence[str],
-    report_writer_codex_model: str,
 ) -> tuple[tuple[InitialPromptWorkerRequest, ...], tuple[Path, ...]]:
     worker_requests = tuple(
         InitialPromptWorkerRequest(
             worker_id=worker_id,
-            model=_requested_worker_model(
-                worker_id,
-                team_state,
-                report_writer_codex_model,
-            ),
+            model=_requested_worker_model(worker_id, team_state),
         )
         for worker_id in selected_workers
     )
@@ -472,8 +458,6 @@ def main(argv: Sequence[str] | None = None) -> int:
             okstra_bin=Path(args.okstra_bin) if args.okstra_bin else None,
             requested_workers=_parse_workers(args.workers),
             idle_timeout_seconds=idle_timeout_seconds,
-            enable_codex_report_writer=args.enable_codex_report_writer,
-            report_writer_codex_model=args.report_writer_codex_model,
             dispatch_kind=args.dispatch_kind,
             jobs_file=Path(args.jobs_file) if args.jobs_file else None,
         )
@@ -500,8 +484,6 @@ def _parser() -> argparse.ArgumentParser:
     parser.add_argument("--workers", default="")
     parser.add_argument("--dry-run", action="store_true")
     parser.add_argument("--idle-timeout-seconds", default="600")
-    parser.add_argument("--enable-codex-report-writer", action="store_true")
-    parser.add_argument("--report-writer-codex-model", default="")
     parser.add_argument("--dispatch-kind", default="initial")
     parser.add_argument("--jobs-file", default="")
     return parser
@@ -520,6 +502,8 @@ def _build_worker_dispatch(
     model_execution_value: str,
     prompt_path: Path,
 ) -> WorkerJob:
+    worker_state = _worker_state(team_state, worker_id)
+    provider = _assigned_provider(worker_state, worker_id)
     if worker_id == REPORT_WRITER_WORKER_ID:
         return _build_report_writer_dispatch(
             project_root=project_root,
@@ -530,17 +514,17 @@ def _build_worker_dispatch(
             idle_timeout_seconds=idle_timeout_seconds,
             model_execution_value=model_execution_value,
             prompt_path=prompt_path,
+            provider=provider,
         )
-    worker_state = _worker_state(team_state, worker_id)
     result_path = _resolve_project_path(
         project_root, _require_string(worker_state, "resultPath")
     )
-    wrapper = _resolve_wrapper(worker_id, workspace_root, okstra_bin)
+    wrapper = _resolve_wrapper(provider, workspace_root, okstra_bin)
     worktree_path = _worktree_path(manifest, active_context)
     role = _pane_role(prompt_path)
     return WorkerJob(
         worker_id=worker_id,
-        provider=worker_id,
+        provider=provider,
         backend=BACKEND_CLI_WRAPPER,
         project_root=project_root,
         model_execution_value=model_execution_value,
@@ -566,6 +550,7 @@ def _build_report_writer_dispatch(
     idle_timeout_seconds: int,
     model_execution_value: str,
     prompt_path: Path,
+    provider: str,
 ) -> WorkerJob:
     worker_state = _worker_state(team_state, REPORT_WRITER_WORKER_ID)
     data_json_path = _final_report_data_path(
@@ -577,12 +562,11 @@ def _build_report_writer_dispatch(
     )
     return WorkerJob(
         worker_id=REPORT_WRITER_WORKER_ID,
-        # codex 경로의 report-writer 는 claude 가 아니라 codex wrapper 로 돈다.
-        provider="codex",
+        provider=provider,
         backend=BACKEND_CLI_WRAPPER,
         project_root=project_root,
         model_execution_value=model_execution_value,
-        wrapper_path=_resolve_wrapper("codex", workspace_root, okstra_bin),
+        wrapper_path=_resolve_wrapper(provider, workspace_root, okstra_bin),
         prompt_path=prompt_path,
         result_path=data_json_path,
         worker_result_path=worker_result_path,
@@ -608,46 +592,26 @@ def _validate_codex_manifest(manifest: Mapping[str, Any], path: Path) -> None:
 def _requested_worker_model(
     worker_id: str,
     team_state: Mapping[str, Any],
-    report_writer_codex_model: str,
 ) -> str:
-    if worker_id != REPORT_WRITER_WORKER_ID:
-        return _require_string(
-            _worker_state(team_state, worker_id),
-            "modelExecutionValue",
-        )
-    model = report_writer_codex_model.strip()
-    if model:
-        return model
-    raise DispatchError(
-        "Codex report-writer dispatch requires --report-writer-codex-model"
-    )
+    state = _worker_state(team_state, worker_id)
+    return _require_string(state, "modelExecutionValue")
 
 
 def _select_workers(
     manifest: Mapping[str, Any],
+    team_state: Mapping[str, Any],
     requested_workers: Sequence[str],
-    *,
-    enable_codex_report_writer: bool,
 ) -> list[str]:
     recommended = _string_list(manifest.get("recommendedWorkers"))
     if not recommended:
         raise DispatchError("run manifest has no recommendedWorkers entries")
-    supported_workers = _supported_codex_dispatch_workers(
-        enable_codex_report_writer=enable_codex_report_writer
-    )
+    dispatchable = _dispatchable_workers(recommended, team_state)
     if not requested_workers:
-        selected = [worker for worker in recommended if worker in supported_workers]
+        selected = [worker for worker in recommended if worker in dispatchable]
         if selected:
             return selected
-        if REPORT_WRITER_WORKER_ID in recommended and not enable_codex_report_writer:
-            raise DispatchError(
-                "report-writer requires --enable-codex-report-writer because it "
-                "runs through the Codex wrapper instead of Claude Agent"
-            )
-        supported = ", ".join(sorted(supported_workers))
         raise DispatchError(
-            "run roster has no Codex-dispatch supported worker(s) "
-            f"(CLI dispatcher supports: {supported})"
+            "run roster has no cli-wrapper assignments for codex-dispatch"
         )
 
     selected = list(requested_workers)
@@ -656,17 +620,18 @@ def _select_workers(
         raise DispatchError(
             "requested worker(s) are not in this run roster: " + ", ".join(unknown)
         )
-    if REPORT_WRITER_WORKER_ID in selected and not enable_codex_report_writer:
-        raise DispatchError(
-            "report-writer requires --enable-codex-report-writer because it "
-            "runs through the Codex wrapper instead of Claude Agent"
-        )
-    unsupported = [
+    native = [
         worker for worker in selected
-        if worker not in supported_workers
+        if _assigned_runner(_worker_state(team_state, worker)) == "native-session"
     ]
+    if native:
+        raise DispatchError(
+            "requested worker(s) use runner=native-session and must be dispatched "
+            "by the current Codex host: " + ", ".join(native)
+        )
+    unsupported = [worker for worker in selected if worker not in dispatchable]
     if unsupported:
-        supported = ", ".join(sorted(supported_workers))
+        supported = ", ".join(sorted(dispatchable))
         raise DispatchError(
             "unsupported Codex lead worker(s): "
             + ", ".join(unsupported)
@@ -675,19 +640,37 @@ def _select_workers(
     return selected
 
 
-def _supported_codex_dispatch_workers(*, enable_codex_report_writer: bool) -> set[str]:
-    supported = set(SUPPORTED_CLI_WORKERS)
-    if enable_codex_report_writer:
-        supported.add(REPORT_WRITER_WORKER_ID)
-    return supported
+def _assigned_provider(worker_state: Mapping[str, Any], worker_id: str) -> str:
+    provider = _string_value(worker_state.get("provider"))
+    if provider:
+        return provider
+    return "codex" if worker_id == REPORT_WRITER_WORKER_ID else worker_id
+
+
+def _assigned_runner(worker_state: Mapping[str, Any]) -> str:
+    return _string_value(worker_state.get("runner")) or BACKEND_CLI_WRAPPER
+
+
+def _dispatchable_workers(
+    recommended: Sequence[str], team_state: Mapping[str, Any],
+) -> set[str]:
+    dispatchable = set()
+    for worker_id in recommended:
+        state = _worker_state(team_state, worker_id)
+        provider = _assigned_provider(state, worker_id)
+        if (
+            _assigned_runner(state) == BACKEND_CLI_WRAPPER
+            and provider in SUPPORTED_CLI_WORKERS
+        ):
+            dispatchable.add(worker_id)
+    return dispatchable
 
 
 def _skipped_worker_reasons(
     manifest: Mapping[str, Any],
+    team_state: Mapping[str, Any],
     selected_workers: Sequence[str],
     requested_workers: Sequence[str],
-    *,
-    enable_codex_report_writer: bool,
 ) -> dict[str, str]:
     recommended = _string_list(manifest.get("recommendedWorkers"))
     selected = set(selected_workers)
@@ -696,24 +679,22 @@ def _skipped_worker_reasons(
             worker_id: "skipped by Codex dispatch: worker was not requested in this invocation"
             for worker_id in recommended
             if worker_id not in selected
+            and _assigned_runner(_worker_state(team_state, worker_id))
+            == BACKEND_CLI_WRAPPER
         }
 
-    supported = _supported_codex_dispatch_workers(
-        enable_codex_report_writer=enable_codex_report_writer
-    )
+    supported = _dispatchable_workers(recommended, team_state)
     reasons = {}
     for worker_id in recommended:
         if worker_id in selected:
             continue
-        if worker_id == REPORT_WRITER_WORKER_ID and not enable_codex_report_writer:
-            reasons[worker_id] = (
-                "skipped by Codex dispatch default: report-writer requires "
-                "--enable-codex-report-writer and --report-writer-codex-model"
-            )
-        elif worker_id not in supported:
+        state = _worker_state(team_state, worker_id)
+        if _assigned_runner(state) == "native-session":
+            continue
+        if worker_id not in supported:
             reasons[worker_id] = (
-                "skipped by Codex dispatch default: worker is not supported by "
-                "the Codex CLI dispatcher"
+                "skipped by Codex dispatch default: assigned provider has no "
+                "registered CLI wrapper"
             )
         else:
             reasons[worker_id] = "skipped by Codex dispatch default"

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -135,8 +135,6 @@ def build_dispatch_plan(
     okstra_bin: Path | None = None,
     requested_workers: Sequence[str] = (),
     idle_timeout_seconds: int = 600,
-    enable_report_writer: bool = False,
-    report_writer_model: str = "",
     required_lead_runtime: str | None = None,
     default_backend: str = BACKEND_CLI_WRAPPER,
     supported_worker_wrappers: Mapping[str, str],
@@ -171,8 +169,6 @@ def build_dispatch_plan(
             team_state,
             active_context,
             requested_workers,
-            enable_report_writer,
-            report_writer_model,
             options,
         )
     return DispatchPlan(
@@ -240,11 +236,9 @@ def _jobs_from_roster(
     team_state: Mapping[str, Any],
     active_context: Mapping[str, Any],
     requested_workers: Sequence[str],
-    enable_report_writer: bool,
-    report_writer_model: str,
     options: _BuildOptions,
 ) -> list[WorkerJob]:
-    selected = _select_workers(manifest, requested_workers, enable_report_writer, options)
+    selected = _select_workers(manifest, requested_workers, options)
     _mark_roster_skips(project_root, manifest, team_state, selected, requested_workers, options)
     worker_facts, prompt_paths = _materialize_roster_prompts(
         project_root,
@@ -253,7 +247,6 @@ def _jobs_from_roster(
         manifest,
         team_state,
         selected,
-        report_writer_model,
         options,
     )
     return [
@@ -273,15 +266,12 @@ def _jobs_from_roster(
 def _select_workers(
     manifest: Mapping[str, Any],
     requested_workers: Sequence[str],
-    enable_report_writer: bool,
     options: _BuildOptions,
 ) -> list[str]:
     recommended = _string_list(manifest.get("recommendedWorkers"))
     if not recommended:
         raise DispatchError("run manifest has no recommendedWorkers entries")
     supported = set(options.supported_worker_wrappers)
-    if not enable_report_writer and not requested_workers:
-        supported.discard(REPORT_WRITER_WORKER_ID)
     selected = list(requested_workers) if requested_workers else [w for w in recommended if w in supported]
     unknown = [worker for worker in selected if worker not in recommended]
     if unknown:
@@ -336,11 +326,10 @@ def _materialize_roster_prompts(
     manifest: Mapping[str, Any],
     team_state: Mapping[str, Any],
     selected: Sequence[str],
-    report_writer_model: str,
     options: _BuildOptions,
 ) -> tuple[tuple[_RosterWorkerFacts, ...], tuple[Path, ...]]:
     worker_facts = tuple(
-        _roster_worker_facts(team_state, worker_id, report_writer_model)
+        _roster_worker_facts(team_state, worker_id)
         for worker_id in selected
     )
     try:
@@ -364,13 +353,12 @@ def _materialize_roster_prompts(
 def _roster_worker_facts(
     team_state: Mapping[str, Any],
     worker_id: str,
-    report_writer_model: str,
 ) -> _RosterWorkerFacts:
     state = _worker_state(team_state, worker_id)
     return _RosterWorkerFacts(
         worker_id=worker_id,
-        model=_model_for_worker(worker_id, state, report_writer_model),
-        provider=_provider_for_worker(worker_id),
+        model=_require_string(state, "modelExecutionValue"),
+        provider=_string_value(state.get("provider")) or _provider_for_worker(worker_id),
         result_path=_require_string(state, "resultPath"),
         role=_string_value(state.get("role")) or "worker",
     )
@@ -771,12 +759,6 @@ def _provider_for_worker(worker_id: str) -> str:
     return worker_id
 
 
-def _model_for_worker(worker_id: str, state: Mapping[str, Any], report_writer_model: str) -> str:
-    if worker_id == REPORT_WRITER_WORKER_ID and report_writer_model.strip():
-        return report_writer_model.strip()
-    return _require_string(state, "modelExecutionValue")
-
-
 def _result_path_for_worker(worker_id: str, result_path: Path, manifest: Mapping[str, Any], project_root: Path) -> Path:
     if worker_id != REPORT_WRITER_WORKER_ID:
         return result_path

package/runtime/python/okstra_ctl/lead_events.py

@@ -1,4 +1,4 @@
-"""Structured JSONL events emitted by non-Claude lead runtimes."""
+"""Structured JSONL events emitted by artifact-accounted lead runtimes."""
 from __future__ import annotations
 
 import json

package/runtime/python/okstra_ctl/lead_runtime.py

@@ -24,8 +24,8 @@ class LeadRuntimeInfo:
         }
 
 
-ALLOWED_LEAD_RUNTIMES = ("claude-code", "codex", "external")
-ARTIFACT_ONLY_LEAD_RUNTIMES = frozenset({"codex", "external"})
+ALLOWED_LEAD_RUNTIMES = ("claude-code", "codex", "antigravity", "external")
+ARTIFACT_ONLY_LEAD_RUNTIMES = frozenset({"codex", "antigravity", "external"})
 
 _LEAD_RUNTIMES = {
     "claude-code": LeadRuntimeInfo(
@@ -50,6 +50,17 @@ _LEAD_RUNTIMES = {
         has_claude_session=False,
         adapter_contract_relative_path="lead/adapters/codex.md",
     ),
+    "antigravity": LeadRuntimeInfo(
+        runtime="antigravity",
+        agent="antigravity",
+        agent_label="Antigravity CLI",
+        role="Antigravity lead",
+        adapter_name="antigravity",
+        adapter_dispatch_mode="render-only",
+        session_accounting="artifact-only",
+        has_claude_session=False,
+        adapter_contract_relative_path="lead/adapters/antigravity.md",
+    ),
     "external": LeadRuntimeInfo(
         runtime="external",
         agent="external",

package/runtime/python/okstra_ctl/models.py

@@ -6,14 +6,14 @@ role default = one ROLE_DEFAULTS line here.
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Optional
+from typing import Mapping, Optional
 
 
 @dataclass(frozen=True)
 class ModelSpec:
     display: str
     execution: str
-    pricing: Optional[tuple] = None   # codex only: (input, cached_input, output) USD/1M
+    pricing: Optional[tuple[float, float, float]] = None
     in_picker: bool = False           # exposed in the wizard 3-option picker
 
 
@@ -31,6 +31,8 @@ CLAUDE = {
     "opus-4-6": ModelSpec("opus-4-6", "claude-opus-4-6"),
     "claude-opus-4-6": ModelSpec("opus-4-6", "claude-opus-4-6"),
     "sonnet": ModelSpec("sonnet", "sonnet", in_picker=True),
+    "sonnet-5": ModelSpec("sonnet-5", "claude-sonnet-5", in_picker=True),
+    "claude-sonnet-5": ModelSpec("sonnet-5", "claude-sonnet-5"),
     "sonnet-4-6": ModelSpec("sonnet-4-6", "claude-sonnet-4-6"),
     "claude-sonnet-4-6": ModelSpec("sonnet-4-6", "claude-sonnet-4-6"),
     "haiku": ModelSpec("haiku", "haiku", in_picker=True),
@@ -47,6 +49,8 @@ CLAUDE = {
 ANTIGRAVITY = {
     "gemini-3.1-pro": ModelSpec("Gemini 3.1 Pro", "gemini-3.1-pro", in_picker=True),
     "gemini 3.1 pro": ModelSpec("Gemini 3.1 Pro", "gemini-3.1-pro"),
+    "gemini-3.6-flash": ModelSpec("Gemini 3.6 Flash", "gemini-3.6-flash", in_picker=True),
+    "gemini 3.6 flash": ModelSpec("Gemini 3.6 Flash", "gemini-3.6-flash"),
     "gemini-3.5-flash": ModelSpec("Gemini 3.5 Flash", "gemini-3.5-flash", in_picker=True),
     "gemini 3.5 flash": ModelSpec("Gemini 3.5 Flash", "gemini-3.5-flash"),
 }
@@ -61,12 +65,111 @@ CODEX = {
     "gpt-5.2": ModelSpec("gpt-5.2", "gpt-5.2", (1.75, 0.175, 14.0)),
     "codex-auto-review": ModelSpec("codex-auto-review", "codex-auto-review"),
 }
-PROVIDER_MAPPINGS = {"claude": CLAUDE, "antigravity": ANTIGRAVITY, "codex": CODEX}
+GROK = {
+    "grok-build-0.1": ModelSpec(
+        "grok-build-0.1", "grok-build-0.1", (1.00, 0.20, 2.00), in_picker=True,
+    ),
+    "grok-4.5": ModelSpec(
+        "grok-4.5", "grok-4.5", (2.00, 0.30, 6.00), in_picker=True,
+    ),
+}
+KIMI = {
+    "kimi-k2.7-code": ModelSpec(
+        "Kimi K2.7 Code", "kimi-k2.7-code", (0.95, 0.19, 4.00), in_picker=True,
+    ),
+    "kimi k2.7 code": ModelSpec("Kimi K2.7 Code", "kimi-k2.7-code"),
+    "kimi-for-coding": ModelSpec(
+        "Kimi K2.7 Code", "kimi-for-coding", in_picker=True,
+    ),
+    "kimi-k3": ModelSpec(
+        "Kimi K3", "kimi-k3", (3.00, 0.30, 15.00), in_picker=True,
+    ),
+    "kimi k3": ModelSpec("Kimi K3", "kimi-k3"),
+    "k3": ModelSpec("Kimi K3", "k3", in_picker=True),
+    "k3-256k": ModelSpec("Kimi K3 256K", "k3-256k", in_picker=True),
+    "kimi k3 256k": ModelSpec("Kimi K3 256K", "k3-256k"),
+}
+
+ANALYSIS_ROLES = frozenset({"analyser", "critic"})
+IMPLEMENTATION_ROLES = frozenset({"executor", "verifier"})
+
+
+@dataclass(frozen=True)
+class ProviderSpec:
+    provider: str
+    display_label: str
+    models: Mapping[str, ModelSpec]
+    default_models: Mapping[str, str]
+    wrapper: str
+    supported_roles: frozenset[str]
 
-# ROLE-keyed (not provider): 1:1 with run.py recommended_role_models. "lead" uses
-# the claude provider; "report-writer" resolves via the claude provider too.
-# report-writer defaults below the lead tier on purpose: it does not vote in
-# convergence, and its wall-clock is dominated by sheer report generation.
+
+PROVIDERS = {
+    "claude": ProviderSpec(
+        provider="claude",
+        display_label="Claude",
+        models=CLAUDE,
+        default_models={
+            "lead": "opus",
+            "analyser": "opus",
+            "critic": "opus",
+            "executor": "opus",
+            "verifier": "opus",
+            "report-writer": "sonnet",
+        },
+        wrapper="okstra-claude-exec.sh",
+        supported_roles=frozenset(
+            {"lead", "analyser", "critic", "executor", "verifier", "report-writer"}
+        ),
+    ),
+    "antigravity": ProviderSpec(
+        provider="antigravity",
+        display_label="Antigravity",
+        models=ANTIGRAVITY,
+        default_models={role: "gemini-3.1-pro" for role in (
+            "lead", "analyser", "critic", "executor", "verifier",
+        )},
+        wrapper="okstra-antigravity-exec.sh",
+        supported_roles=frozenset(
+            {"lead", "analyser", "critic", "executor", "verifier"}
+        ),
+    ),
+    "codex": ProviderSpec(
+        provider="codex",
+        display_label="Codex",
+        models=CODEX,
+        default_models={role: "gpt-5.6-sol" for role in (
+            "lead", "analyser", "critic", "executor", "verifier", "report-writer",
+        )},
+        wrapper="okstra-codex-exec.sh",
+        supported_roles=frozenset(
+            {"lead", "analyser", "critic", "executor", "verifier", "report-writer"}
+        ),
+    ),
+    "grok": ProviderSpec(
+        provider="grok",
+        display_label="Grok",
+        models=GROK,
+        default_models={"analyser": "grok-build-0.1", "critic": "grok-4.5"},
+        wrapper="okstra-grok-exec.sh",
+        supported_roles=ANALYSIS_ROLES,
+    ),
+    "kimi": ProviderSpec(
+        provider="kimi",
+        display_label="Kimi",
+        models=KIMI,
+        default_models={"analyser": "kimi-k2.7-code", "critic": "kimi-k3"},
+        wrapper="okstra-kimi-exec.sh",
+        supported_roles=ANALYSIS_ROLES,
+    ),
+}
+
+PROVIDER_MAPPINGS = {
+    provider: spec.models for provider, spec in PROVIDERS.items()
+}
+
+# Legacy role-keyed compatibility defaults. Canonical assignments resolve a
+# provider first and then use ProviderSpec.default_models for that role.
 ROLE_DEFAULTS = {
     "lead": "opus", "claude": "opus", "codex": "gpt-5.6-sol",
     "antigravity": "gemini-3.1-pro", "report-writer": "sonnet",
@@ -83,6 +186,51 @@ class UnknownModelError(ValueError):
     """raw_value 가 provider mapping 에 등록되어 있지 않을 때 발생."""
 
 
+class UnknownProviderError(ValueError):
+    """Raised when a requested provider is absent from the registry."""
+
+
+def provider_spec(provider: str) -> ProviderSpec:
+    """Return one registered provider or fail before assignment/dispatch."""
+    normalized = (provider or "").strip().lower()
+    try:
+        return PROVIDERS[normalized]
+    except KeyError as exc:
+        allowed = ", ".join(PROVIDERS)
+        raise UnknownProviderError(
+            f"unknown provider {provider!r}. Allowed values: {allowed}"
+        ) from exc
+
+
+def provider_ids(role: str | None = None) -> list[str]:
+    """Registered provider ids, optionally filtered by functional role."""
+    if not role:
+        return list(PROVIDERS)
+    return [
+        provider for provider, spec in PROVIDERS.items()
+        if role in spec.supported_roles
+    ]
+
+
+def provider_supports_role(provider: str, role: str) -> bool:
+    """Whether the provider has passed the registry gate for a role."""
+    return role in provider_spec(provider).supported_roles
+
+
+def provider_wrappers(role: str | None = None) -> dict[str, str]:
+    """Provider-to-wrapper mapping derived from capability entries."""
+    return {
+        provider: PROVIDERS[provider].wrapper
+        for provider in provider_ids(role)
+        if PROVIDERS[provider].wrapper
+    }
+
+
+def provider_default_model(provider: str, role: str) -> Optional[str]:
+    """Resolve a provider's explicit default for one functional role."""
+    return provider_spec(provider).default_models.get(role)
+
+
 def resolve_model_metadata(
     *, provider: str, raw_value: str, default_display: str, default_execution: str,
 ) -> ModelAssignment:
@@ -120,6 +268,6 @@ def default_model(role: str) -> Optional[str]:
 
 
 def catalog_pricing(provider: str) -> dict:
-    """Selectable-model pricing for a provider (codex only carries pricing)."""
+    """Selectable-model pricing as (input, cached input, output) USD/1M."""
     mapping = PROVIDER_MAPPINGS.get(provider, {})
     return {alias: spec.pricing for alias, spec in mapping.items() if spec.pricing is not None}