okstra 0.121.1 → 0.123.0

package/runtime/python/okstra_ctl/incremental_carry.py

@@ -1,53 +1,326 @@
-"""Merge carried-forward plan-item verdicts from the prior run into the
-current incremental re-run's data.json. Plan items the current run did not
-re-verify keep their prior verdict, tagged so the report shows they are
-carried forward and unchanged.
-"""
+"""Merge safe carried-forward planning artifacts into an incremental re-run."""
 from __future__ import annotations
 
 import argparse
+import copy
 import json
+import re
 import sys
 from pathlib import Path
 
 
+PREP_VERDICT_RE = re.compile(r"^P-Prep-S([1-9][0-9]*)-")
+
+
 class CarryError(Exception):
     """Carry merge refused — schema drift or structural mismatch."""
 
 
-def merge_carried_forward(prev: dict, cur: dict, prev_seq: str = "previous") -> dict:
+def _planning(data: dict) -> dict:
+    planning = data.get("implementationPlanning", {})
+    if not isinstance(planning, dict):
+        raise CarryError("implementationPlanning must be an object")
+    return planning
+
+
+def _indexed_rows(rows: object, *, key: str, label: str) -> dict:
+    if not isinstance(rows, list):
+        raise CarryError(f"{label} must be an array")
+    indexed = {}
+    for row in rows:
+        if not isinstance(row, dict) or key not in row:
+            raise CarryError(f"{label} contains a row without {key}")
+        identity = row[key]
+        if identity in indexed:
+            raise CarryError(f"{label} contains duplicate {key} {identity!r}")
+        indexed[identity] = row
+    return indexed
+
+
+def _stage_rows(planning: dict, *, snapshot: str) -> dict[int, dict]:
+    rows = _indexed_rows(
+        planning.get("stages", []), key="stage", label=f"{snapshot} stages",
+    )
+    try:
+        return {int(stage): row for stage, row in rows.items()}
+    except (TypeError, ValueError) as exc:
+        raise CarryError(f"{snapshot} stages contains an invalid stage number") from exc
+
+
+def _prep_items(planning: dict, *, snapshot: str) -> dict[str, dict]:
+    preparation = planning.get("designPreparation", {})
+    if not isinstance(preparation, dict):
+        raise CarryError(f"{snapshot} designPreparation must be an object")
+    return _indexed_rows(
+        preparation.get("items", []),
+        key="id",
+        label=f"{snapshot} designPreparation.items",
+    )
+
+
+def _stage_refs(item: dict, *, label: str) -> set[int]:
+    refs = item.get("stageRefs")
+    if not isinstance(refs, list) or not refs:
+        raise CarryError(f"{label} has invalid stageRefs")
+    try:
+        parsed = {int(stage) for stage in refs}
+    except (TypeError, ValueError) as exc:
+        raise CarryError(f"{label} has invalid stageRefs") from exc
+    if any(stage < 1 for stage in parsed):
+        raise CarryError(f"{label} has invalid stageRefs")
+    return parsed
+
+
+def _canonical(value: dict, *, ignore_carry_marker: bool = False) -> str:
+    comparable = copy.deepcopy(value)
+    if ignore_carry_marker:
+        comparable.pop("carriedForwardFromSeq", None)
+    return json.dumps(comparable, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+def _prep_verdict_stage(item: dict) -> int | None:
+    match = PREP_VERDICT_RE.match(str(item.get("id", "")))
+    return int(match.group(1)) if match else None
+
+
+def _merge_legacy_plan_items(prev_planning: dict, cur_planning: dict, prev_seq: str) -> None:
+    prev_items = prev_planning.get("planBodyVerification", {}).get("planItems", [])
+    cur_pbv = cur_planning.setdefault("planBodyVerification", {})
+    cur_items = cur_pbv.setdefault("planItems", [])
+    current_ids = {item["id"] for item in cur_items}
+    for item in prev_items:
+        if item["id"] not in current_ids:
+            carried = copy.deepcopy(item)
+            carried["carriedForwardFromSeq"] = str(prev_seq)
+            cur_items.append(carried)
+    cur_items.sort(key=lambda item: item["id"])
+
+
+def _validate_stage_sets(
+    prev_stages: dict[int, dict],
+    cur_stages: dict[int, dict],
+    carry_stages: set[int],
+    reverify_stages: set[int],
+) -> None:
+    overlap = carry_stages & reverify_stages
+    if overlap:
+        raise CarryError(f"carry/reverify stage sets overlap: {sorted(overlap)}")
+    missing_prior = carry_stages - set(prev_stages)
+    if missing_prior:
+        raise CarryError(f"carry stage(s) missing from prior snapshot: {sorted(missing_prior)}")
+    missing_current = reverify_stages - set(cur_stages)
+    if missing_current:
+        raise CarryError(
+            f"reverify stage(s) missing from current snapshot: {sorted(missing_current)}"
+        )
+
+
+def _merge_stage_rows(
+    cur_planning: dict,
+    prev_stages: dict[int, dict],
+    cur_stages: dict[int, dict],
+    carry_stages: set[int],
+    reverify_stages: set[int],
+) -> None:
+    merged = [copy.deepcopy(prev_stages[stage]) for stage in carry_stages]
+    merged.extend(copy.deepcopy(cur_stages[stage]) for stage in reverify_stages)
+    merged.sort(key=lambda row: int(row["stage"]))
+    cur_planning["stages"] = merged
+
+
+def _merge_prep_items(
+    prev_planning: dict,
+    cur_planning: dict,
+    carry_stages: set[int],
+    reverify_stages: set[int],
+) -> None:
+    prev_items = _prep_items(prev_planning, snapshot="prior")
+    cur_items = _prep_items(cur_planning, snapshot="current")
+    scoped_stages = carry_stages | reverify_stages
+    carried: dict[str, dict] = {}
+    for item_id, item in prev_items.items():
+        refs = _stage_refs(item, label=f"prior PREP item {item_id}")
+        if refs & carry_stages and refs & reverify_stages:
+            raise CarryError(f"prior PREP item {item_id} crosses carry and reverify stages")
+        if not refs <= scoped_stages:
+            raise CarryError(f"prior PREP item {item_id} falls outside carry/reverify scope")
+        if refs <= carry_stages:
+            duplicate = cur_items.get(item_id)
+            if duplicate is not None and _canonical(duplicate) != _canonical(item):
+                raise CarryError(f"carry-owned PREP item {item_id} conflicts with current")
+            carried[item_id] = copy.deepcopy(item)
+
+    retained: dict[str, dict] = {}
+    for item_id, item in cur_items.items():
+        refs = _stage_refs(item, label=f"current PREP item {item_id}")
+        if refs & carry_stages and refs & reverify_stages:
+            raise CarryError(f"current PREP item {item_id} crosses carry and reverify stages")
+        if not refs <= scoped_stages:
+            raise CarryError(f"current PREP item {item_id} falls outside carry/reverify scope")
+        if refs & carry_stages and not refs & reverify_stages:
+            previous = prev_items.get(item_id)
+            if previous is None:
+                raise CarryError(f"current PREP item {item_id} is a carry-stage scope leak")
+            previous_refs = _stage_refs(
+                previous,
+                label=f"prior PREP item {item_id}",
+            )
+            if previous_refs != refs:
+                raise CarryError(
+                    f"current PREP item {item_id} changes stage ownership"
+                )
+            continue
+        retained[item_id] = copy.deepcopy(item)
+    retained.update(carried)
+
+    preparation = cur_planning.setdefault("designPreparation", {})
+    preparation["items"] = [retained[item_id] for item_id in sorted(retained)]
+
+
+def _merge_non_prep_verdicts(
+    prev_items: dict[str, dict],
+    cur_items: dict[str, dict],
+    prev_seq: str,
+) -> list[dict]:
+    merged = {
+        item_id: copy.deepcopy(item)
+        for item_id, item in cur_items.items()
+        if _prep_verdict_stage(item) is None
+    }
+    for item_id, item in prev_items.items():
+        if _prep_verdict_stage(item) is None and item_id not in merged:
+            carried = copy.deepcopy(item)
+            carried["carriedForwardFromSeq"] = str(prev_seq)
+            merged[item_id] = carried
+    return list(merged.values())
+
+
+def _merge_prep_verdicts(
+    prev_items: dict[str, dict],
+    cur_items: dict[str, dict],
+    carry_stages: set[int],
+    reverify_stages: set[int],
+    prev_seq: str,
+) -> list[dict]:
+    merged = []
+    scoped_stages = carry_stages | reverify_stages
+    for item_id, item in cur_items.items():
+        stage = _prep_verdict_stage(item)
+        if stage is None:
+            continue
+        if stage not in scoped_stages:
+            raise CarryError(f"current PREP verdict {item_id} falls outside carry/reverify scope")
+        if stage in carry_stages:
+            previous = prev_items.get(item_id)
+            if previous is None:
+                raise CarryError(f"current PREP verdict {item_id} is a carry-stage scope leak")
+            if _canonical(previous, ignore_carry_marker=True) != _canonical(
+                item, ignore_carry_marker=True,
+            ):
+                raise CarryError(f"carry-owned PREP verdict {item_id} conflicts with current")
+        else:
+            merged.append(copy.deepcopy(item))
+
+    for item_id, item in prev_items.items():
+        stage = _prep_verdict_stage(item)
+        if stage is None:
+            continue
+        if stage not in scoped_stages:
+            raise CarryError(f"prior PREP verdict {item_id} falls outside carry/reverify scope")
+        if stage in carry_stages:
+            carried = copy.deepcopy(item)
+            carried["carriedForwardFromSeq"] = str(prev_seq)
+            merged.append(carried)
+    return merged
+
+
+def _merge_stage_aware(
+    prev_planning: dict,
+    cur_planning: dict,
+    prev_seq: str,
+    carry_stages: set[int],
+    reverify_stages: set[int],
+) -> None:
+    prev_stages = _stage_rows(prev_planning, snapshot="prior")
+    cur_stages = _stage_rows(cur_planning, snapshot="current")
+    _validate_stage_sets(prev_stages, cur_stages, carry_stages, reverify_stages)
+    _merge_stage_rows(
+        cur_planning, prev_stages, cur_stages, carry_stages, reverify_stages,
+    )
+    _merge_prep_items(prev_planning, cur_planning, carry_stages, reverify_stages)
+
+    prev_pbv = prev_planning.get("planBodyVerification", {})
+    cur_pbv = cur_planning.setdefault("planBodyVerification", {})
+    prev_items = _indexed_rows(
+        prev_pbv.get("planItems", []), key="id", label="prior planItems",
+    )
+    cur_items = _indexed_rows(
+        cur_pbv.get("planItems", []), key="id", label="current planItems",
+    )
+    merged = _merge_non_prep_verdicts(prev_items, cur_items, prev_seq)
+    merged.extend(_merge_prep_verdicts(
+        prev_items, cur_items, carry_stages, reverify_stages, prev_seq,
+    ))
+    merged.sort(key=lambda item: item["id"])
+    cur_pbv["planItems"] = merged
+
+
+def merge_carried_forward(
+    prev: dict,
+    cur: dict,
+    prev_seq: str = "previous",
+    carry_stages: set[int] | None = None,
+    reverify_stages: set[int] | None = None,
+) -> dict:
     if prev.get("schemaVersion") != cur.get("schemaVersion"):
         raise CarryError(
             f"schemaVersion drift {prev.get('schemaVersion')!r} != {cur.get('schemaVersion')!r}; "
             "cannot carry forward — caller must fall back to full"
         )
-    prev_pbv = prev.get("implementationPlanning", {}).get("planBodyVerification", {})
-    cur_ip = cur.setdefault("implementationPlanning", {})
-    cur_pbv = cur_ip.setdefault("planBodyVerification", {})
-    cur_items = cur_pbv.setdefault("planItems", [])
-    reverified_ids = {i["id"] for i in cur_items}
-    for item in prev_pbv.get("planItems", []):
-        if item["id"] in reverified_ids:
-            continue
-        carried = dict(item)
-        carried["carriedForwardFromSeq"] = str(prev_seq)
-        cur_items.append(carried)
-    cur_items.sort(key=lambda i: i["id"])
+    prev_planning = _planning(prev)
+    cur_planning = cur.setdefault("implementationPlanning", {})
+    if (carry_stages is None) != (reverify_stages is None):
+        raise CarryError("carry_stages and reverify_stages must be provided together")
+    if carry_stages is None:
+        _merge_legacy_plan_items(prev_planning, cur_planning, prev_seq)
+    else:
+        _merge_stage_aware(
+            prev_planning, cur_planning, prev_seq, carry_stages, reverify_stages,
+        )
     return cur
 
 
+def _parse_stage_csv(value: str | None, *, option: str) -> set[int] | None:
+    if value is None:
+        return None
+    try:
+        return {int(token.strip()) for token in value.split(",") if token.strip()}
+    except ValueError as exc:
+        raise CarryError(f"{option} contains an invalid stage number") from exc
+
+
 def main(argv: list[str]) -> int:
     ap = argparse.ArgumentParser(prog="okstra incremental-carry")
     ap.add_argument("--prev-data", required=True, help="prior run final-report data.json")
     ap.add_argument("--cur-data", required=True, help="current incremental re-run data.json")
     ap.add_argument("--prev-seq", required=True, help="prior run seq, tagged onto carried items")
+    ap.add_argument("--carry-stages", default=None, help="comma-separated carried stage numbers")
+    ap.add_argument("--reverify-stages", default=None, help="comma-separated reverified stage numbers")
     ap.add_argument("--out", required=True, help="path to write the merged data.json")
     args = ap.parse_args(argv)
 
     prev = json.loads(Path(args.prev_data).read_text(encoding="utf-8"))
     cur = json.loads(Path(args.cur_data).read_text(encoding="utf-8"))
     try:
-        merged = merge_carried_forward(prev, cur, prev_seq=args.prev_seq)
+        merged = merge_carried_forward(
+            prev,
+            cur,
+            prev_seq=args.prev_seq,
+            carry_stages=_parse_stage_csv(args.carry_stages, option="--carry-stages"),
+            reverify_stages=_parse_stage_csv(
+                args.reverify_stages, option="--reverify-stages",
+            ),
+        )
     except CarryError as exc:
         print(f"carry refused: {exc}", file=sys.stderr)
         return 1
@@ -57,10 +330,10 @@ def main(argv: list[str]) -> int:
     )
     carried = sum(
         1
-        for i in merged.get("implementationPlanning", {})
+        for item in merged.get("implementationPlanning", {})
         .get("planBodyVerification", {})
         .get("planItems", [])
-        if i.get("carriedForwardFromSeq") == str(args.prev_seq)
+        if item.get("carriedForwardFromSeq") == str(args.prev_seq)
     )
     print(f"merged {carried} carried-forward plan item(s) from seq {args.prev_seq} -> {args.out}")
     return 0

package/runtime/python/okstra_ctl/incremental_scope.py

@@ -39,6 +39,40 @@ def parse_stage_graph(data: dict) -> list[tuple[int, list[int]]]:
     return [(int(row["stage"]), _parse_depends_on(row.get("dependsOn", ""))) for row in stage_map]
 
 
+def design_prep_impacted_stages(data: dict, item_ids: set[str]) -> set[int]:
+    items = (
+        data.get("implementationPlanning", {})
+        .get("designPreparation", {})
+        .get("items", [])
+    )
+    if not isinstance(items, list):
+        raise ValueError("designPreparation.items must be an array")
+    matched = {
+        str(item.get("id")): item
+        for item in items
+        if isinstance(item, dict) and str(item.get("id")) in item_ids
+    }
+    missing = item_ids - set(matched)
+    if missing:
+        raise ValueError(f"unknown design-prep item(s): {', '.join(sorted(missing))}")
+
+    impacted: set[int] = set()
+    for item_id, item in matched.items():
+        stage_refs = item.get("stageRefs")
+        if not isinstance(stage_refs, list) or not stage_refs:
+            raise ValueError(f"design-prep item {item_id} has invalid stageRefs")
+        try:
+            parsed_refs = {int(stage) for stage in stage_refs}
+        except (TypeError, ValueError) as exc:
+            raise ValueError(
+                f"design-prep item {item_id} has invalid stageRefs"
+            ) from exc
+        if any(stage < 1 for stage in parsed_refs):
+            raise ValueError(f"design-prep item {item_id} has invalid stageRefs")
+        impacted.update(parsed_refs)
+    return impacted
+
+
 def decide_scope(
     *,
     stages: list[tuple[int, list[int]]],
@@ -72,15 +106,27 @@ def main(argv: list[str]) -> int:
     ap.add_argument("--cur-base-sha", required=True)
     ap.add_argument("--prev-base-sha", required=True)
     ap.add_argument("--impacted", default="", help="comma-separated impacted stage numbers")
+    ap.add_argument("--prep-items", default="", help="comma-separated changed PREP item IDs")
     args = ap.parse_args(argv)
 
     data = json.loads(Path(args.prev_data).read_text(encoding="utf-8"))
     stages = parse_stage_graph(data)
-    impacted = {int(t.strip()) for t in args.impacted.split(",") if t.strip()}
-    decision = decide_scope(
-        stages=stages, impacted_stages=impacted,
-        prev_base_sha=args.prev_base_sha, cur_base_sha=args.cur_base_sha,
-    )
+    try:
+        impacted = {int(t.strip()) for t in args.impacted.split(",") if t.strip()}
+        prep_ids = {t.strip() for t in args.prep_items.split(",") if t.strip()}
+        impacted.update(design_prep_impacted_stages(data, prep_ids))
+        unknown_stages = impacted - {stage for stage, _ in stages}
+        if unknown_stages:
+            unknown = ", ".join(str(stage) for stage in sorted(unknown_stages))
+            raise ValueError(f"impacted stage(s) absent from Stage Map: {unknown}")
+        decision = decide_scope(
+            stages=stages, impacted_stages=impacted,
+            prev_base_sha=args.prev_base_sha, cur_base_sha=args.cur_base_sha,
+        )
+    except ValueError as exc:
+        decision = IncrementalDecision(
+            "full", [], [], f"invalid incremental-scope input: {exc}",
+        )
     print(json.dumps(asdict(decision), ensure_ascii=False))
     return 0
 

package/runtime/python/okstra_ctl/lead_runtime.py

@@ -14,6 +14,7 @@ class LeadRuntimeInfo:
     adapter_dispatch_mode: str
     session_accounting: str
     has_claude_session: bool
+    adapter_contract_relative_path: str
 
     def adapter_payload(self) -> dict[str, str]:
         return {
@@ -36,6 +37,7 @@ _LEAD_RUNTIMES = {
         adapter_dispatch_mode="team",
         session_accounting="claude-jsonl",
         has_claude_session=True,
+        adapter_contract_relative_path="lead/adapters/claude-code.md",
     ),
     "codex": LeadRuntimeInfo(
         runtime="codex",
@@ -46,6 +48,7 @@ _LEAD_RUNTIMES = {
         adapter_dispatch_mode="render-only",
         session_accounting="artifact-only",
         has_claude_session=False,
+        adapter_contract_relative_path="lead/adapters/codex.md",
     ),
     "external": LeadRuntimeInfo(
         runtime="external",
@@ -56,6 +59,7 @@ _LEAD_RUNTIMES = {
         adapter_dispatch_mode="render-only",
         session_accounting="artifact-only",
         has_claude_session=False,
+        adapter_contract_relative_path="lead/adapters/external.md",
     ),
 }
 

package/runtime/python/okstra_ctl/material.py

@@ -21,7 +21,7 @@ def build_analysis_material(brief_path: Path, directive: str = "") -> str:
         parts.append("## Directive")
         parts.append("")
         parts.append(
-            "> Free-form directive supplied via `--directive`. Treat as a hard hint that may override default heuristics in lead, workers, and downstream skills (e.g. okstra-schedule's Gantt skip gate)."
+            "> Free-form directive supplied via `--directive`. Treat as a hard hint that may override default heuristics in lead, workers, and downstream skills (e.g. okstra-schedule-gen's Gantt skip gate)."
         )
         parts.append("")
         parts.append(directive)

package/runtime/python/okstra_ctl/model_discovery.py

@@ -0,0 +1,98 @@
+"""Pre-dispatch model-identity normalization for CLI workers.
+
+The catalog (models.py) carries okstra's model identity. Some worker CLIs
+(antigravity `agy`, codex) accept their own spelling of that identity, and it
+drifts across CLI versions / accounts. This module maps a catalog execution
+value + role to the CLI's exact accepted identifier, or hard-fails with the
+CLI's real list. It never substitutes a different model — spelling/effort only.
+"""
+from __future__ import annotations
+
+import subprocess
+from functools import lru_cache
+from pathlib import Path
+
+# Per-role reasoning-effort policy for CLIs that bake effort into the model
+# name (agy). Deterministic — no per-run improvisation.
+# `critic` is intentionally absent: an opt-in critic reuses its worker's
+# execution value (render.py maps critic_choice -> *_WORKER_MODEL_EXECUTION_VALUE),
+# so it inherits the worker's normalized identity + effort. role_effort("critic")
+# returns _DEFAULT_EFFORT, matching the worker it mirrors.
+ROLE_EFFORT = {"worker": "High", "executor": "High"}
+_DEFAULT_EFFORT = "High"
+
+
+class ModelUnavailableError(RuntimeError):
+    """Requested model identity is not offered by the worker CLI on this host."""
+
+
+def role_effort(role: str) -> str:
+    return ROLE_EFFORT.get(role, _DEFAULT_EFFORT)
+
+
+@lru_cache(maxsize=1)
+def agy_models(agy_bin: str = "agy") -> tuple[str, ...]:
+    """Live `agy models` list, or () when agy is unavailable (non-blocking)."""
+    try:
+        proc = subprocess.run(
+            [agy_bin, "models"],
+            capture_output=True, text=True, timeout=20,
+        )
+    except (FileNotFoundError, OSError, subprocess.SubprocessError):
+        return ()
+    if proc.returncode != 0:
+        return ()
+    return tuple(line.strip() for line in proc.stdout.splitlines() if line.strip())
+
+
+def _codex_config_path() -> Path:
+    return Path.home() / ".codex" / "config.toml"
+
+
+def codex_availability(config_path: Path | None = None) -> tuple[str, ...]:
+    """Keys under [tui.model_availability_nux] in codex config, or ()."""
+    path = config_path or _codex_config_path()
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return ()
+    out: list[str] = []
+    in_section = False
+    for raw in lines:
+        line = raw.strip()
+        if line.startswith("[") and line.endswith("]"):
+            in_section = line == "[tui.model_availability_nux]"
+            continue
+        if in_section and "=" in line:
+            key = line.split("=", 1)[0].strip().strip('"')
+            if key:
+                out.append(key)
+    return tuple(out)
+
+
+def normalize_execution_for_dispatch(
+    *, provider: str, execution: str, display: str, role: str,
+) -> str:
+    """Return the CLI-accepted spelling of `execution`, or the value unchanged
+    when discovery is unavailable. Raise ModelUnavailableError when the identity
+    is definitely not offered (never substitute a different model)."""
+    if provider == "codex":
+        available = codex_availability()
+        if not available or execution in available:
+            return execution  # no NUX list → pass through; listed → accepted
+        raise ModelUnavailableError(
+            f"codex model {execution!r} is not available for this account. "
+            f"Available: {', '.join(available)} (no auto-rename — update the catalog)"
+        )
+    if provider != "antigravity":
+        return execution  # claude runs via the Agent tool
+    available = agy_models()
+    if not available:
+        return execution  # discovery unavailable → status quo, wrapper still guards
+    want = f"{display} ({role_effort(role)})"
+    if want in available:
+        return want
+    raise ModelUnavailableError(
+        f"antigravity model {want!r} (from catalog {execution!r}, role {role!r}) "
+        f"is not offered by this agy install. Available: {', '.join(available)}"
+    )

package/runtime/python/okstra_ctl/models.py

@@ -36,8 +36,11 @@ CLAUDE = {
     "claude-haiku-4-5": ModelSpec("haiku-4-5", "claude-haiku-4-5"),
     "claude-haiku-4-5-20251001": ModelSpec("haiku-4-5", "claude-haiku-4-5-20251001"),
 }
-# Execution values stay `gemini-3.x`: the `agy` CLI runs Gemini-family models and
-# accepts those slugs. Only the okstra provider/worker identity is "antigravity".
+# The `agy` CLI accepts DISPLAY names with an effort suffix (e.g.
+# "Gemini 3.1 Pro (High)"), not `gemini-3.x` slugs, and its list is
+# host/version-specific. model_discovery.normalize_execution_for_dispatch maps
+# each ModelSpec.display + role effort to the exact `agy models` identifier at
+# dispatch time. agy also serves Claude/GPT-OSS models on some installs.
 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"),
@@ -45,6 +48,8 @@ ANTIGRAVITY = {
     "gemini 3.5 flash": ModelSpec("Gemini 3.5 Flash", "gemini-3.5-flash"),
 }
 CODEX = {
+    # ChatGPT-account host (agy/codex) serves 5.6 without per-token billing → pricing=None.
+    "gpt-5.6-sol": ModelSpec("gpt-5.6-sol", "gpt-5.6-sol", None, in_picker=True),
     "gpt-5.6": ModelSpec("gpt-5.6", "gpt-5.6", (5.00, 0.50, 30.0), in_picker=True),
     "gpt-5.5": ModelSpec("gpt-5.5", "gpt-5.5", (5.00, 0.50, 30.0), in_picker=True),
     "gpt-5.4": ModelSpec("gpt-5.4", "gpt-5.4", (2.50, 0.25, 15.0), in_picker=True),
@@ -58,7 +63,7 @@ PROVIDER_MAPPINGS = {"claude": CLAUDE, "antigravity": ANTIGRAVITY, "codex": CODE
 # ROLE-keyed (not provider): 1:1 with run.py recommended_role_models. "lead" uses
 # the claude provider; "report-writer" is role-only (None → caller uses lead's).
 ROLE_DEFAULTS = {
-    "lead": "opus", "claude": "opus", "codex": "gpt-5.6",
+    "lead": "opus", "claude": "opus", "codex": "gpt-5.6-sol",
     "antigravity": "gemini-3.1-pro", "report-writer": None,
 }