claude-dev-env 2.9.0 → 2.11.0

package/_shared/advisor/scripts/codex_sol_advisor.py

@@ -0,0 +1,449 @@
+"""Bind and consult a read-only Codex CLI session at Sol xhigh."""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import math
+import os
+import subprocess
+import sys
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+_scripts_directory = Path(__file__).resolve().parent
+_config_directory = _scripts_directory / "config"
+_config_directory_text = str(_config_directory)
+if _config_directory_text not in sys.path:
+    sys.path.insert(0, _config_directory_text)
+
+from advisor_scripts_constants.sol_advisor_constants import (  # noqa: E402
+    CODEX_CONFIG_FLAG,
+    CODEX_EXECUTABLE,
+    CODEX_EXEC_SUBCOMMAND,
+    CODEX_JSON_FLAG,
+    CODEX_MODEL_FLAG,
+    CODEX_PROMPT_FROM_STDIN,
+    CODEX_READ_ONLY_SANDBOX,
+    CODEX_REASONING_CONFIG,
+    CODEX_RESUME_SUBCOMMAND,
+    CODEX_SANDBOX_FLAG,
+    CLAUDE_CONFIG_DIRECTORY_NAME,
+    SOL_BIND_FAILURE_REASON,
+    SOL_CODEX_TIMEOUT_REASON,
+    SOL_CODEX_TIMEOUT_SECONDS,
+    SOL_ENV_VAR,
+    SOL_INVALID_SIGNAL_REASON,
+    SOL_MALFORMED_JSONL_REASON,
+    SOL_MISSING_SESSION_REASON,
+    SOL_PREFLIGHT_FAILURE_REASON,
+    SOL_PROBE_TIMEOUT_REASON,
+    SOL_REPLY_FAILURE_REASON,
+    SOL_SESSION_ID_METAVAR,
+    ALL_SOL_TRUTHY_VALUES,
+    SOL_USAGE_PROBE_TIMEOUT_SECONDS,
+)
+from advisor_scripts_constants.advisor_route_constants import (  # noqa: E402
+    ADVISOR_CODEX_MODEL_ID,
+    ADVISOR_FALLBACK_RESULT,
+    ADVISOR_FALLBACK_TIER,
+    ADVISOR_MODEL_TIER,
+    ALL_ADVISOR_GUIDANCE_SIGNALS,
+    CODEX_BIND_SUCCESS_TOKEN,
+    SPAWN_OUTCOME_KEY,
+)
+
+
+@dataclass(frozen=True)
+class SolPreflight:
+    """Record the weekly-meter decision made before a Sol attempt."""
+
+    eligible: bool
+    percent_left: float | None
+    reason: str
+
+
+@dataclass(frozen=True)
+class CodexSolAdvisorReply:
+    """Record a parsed Codex advisor response or an explicit fallback."""
+
+    session_id: str | None
+    guidance: str | None
+    successful: bool
+    reason: str | None
+    is_fallback: bool
+    signal: str | None
+    sol_enabled: bool
+    selected_tier: str
+    outcome: str
+
+
+def _preflight_fallback(
+    reason: str, percent_left: float | None
+) -> SolPreflight:
+    return SolPreflight(False, percent_left, reason)
+
+
+def _reply_fallback(
+    reason: str,
+    is_sol_enabled: bool,
+) -> CodexSolAdvisorReply:
+    return CodexSolAdvisorReply(
+        session_id=None,
+        guidance=None,
+        successful=False,
+        reason=reason,
+        is_fallback=True,
+        signal=None,
+        sol_enabled=is_sol_enabled,
+        selected_tier=ADVISOR_FALLBACK_TIER,
+        outcome=ADVISOR_FALLBACK_RESULT,
+    )
+
+
+def _reply_success(
+    session_id: str,
+    guidance: str,
+    signal: str,
+) -> CodexSolAdvisorReply:
+    return CodexSolAdvisorReply(
+        session_id=session_id,
+        guidance=guidance,
+        successful=True,
+        reason=None,
+        is_fallback=False,
+        signal=signal,
+        sol_enabled=True,
+        selected_tier=ADVISOR_MODEL_TIER,
+        outcome=CODEX_BIND_SUCCESS_TOKEN,
+    )
+
+
+def is_sol_advisor_enabled(
+    setting_by_name: Mapping[str, str] | None,
+) -> bool:
+    """Return whether the optional Sol xhigh rung is enabled.
+
+    Args:
+        setting_by_name: Optional environment-like settings mapping.
+
+    Returns:
+        Whether the Sol feature flag contains a recognized truthy value.
+    """
+    resolved_setting_by_name = os.environ if setting_by_name is None else setting_by_name
+    return (
+        resolved_setting_by_name.get(SOL_ENV_VAR, "").strip().lower()
+        in ALL_SOL_TRUTHY_VALUES
+    )
+
+
+def resolve_usage_probe_path(home_directory: Path) -> Path:
+    """Return the installed Codex weekly usage probe path.
+
+    Args:
+        home_directory: Home directory used to construct the path.
+
+    Returns:
+        The path to the installed weekly usage probe.
+    """
+    return (
+        home_directory
+        / CLAUDE_CONFIG_DIRECTORY_NAME
+        / "skills"
+        / "codex-review"
+        / "scripts"
+        / "codex_usage_probe.py"
+    )
+
+
+def _load_usage_gate(probe_path: Path) -> Callable[[float], bool]:
+    probe_directory = str(probe_path.parent)
+    if probe_directory not in sys.path:
+        sys.path.insert(0, probe_directory)
+    usage_probe_module = importlib.import_module("codex_usage_probe")
+    return usage_probe_module.is_codex_review_required
+
+
+def _parse_probe_percent(stdout_text: str) -> tuple[float | None, str | None]:
+    try:
+        usage_report = json.loads(stdout_text)
+    except (TypeError, json.JSONDecodeError):
+        return None, "usage report is malformed"
+    if not isinstance(usage_report, dict):
+        return None, "usage report is malformed"
+    raw_percent_left = usage_report.get("percent_left")
+    if raw_percent_left is None:
+        return None, "usage meter is unknown"
+    if isinstance(raw_percent_left, bool) or not isinstance(
+        raw_percent_left, (int, float)
+    ):
+        return None, "usage meter is malformed"
+    percent_left = float(raw_percent_left)
+    if not math.isfinite(percent_left):
+        return None, "usage meter is malformed"
+    return percent_left, None
+
+
+def run_sol_preflight(
+    probe_path: Path,
+    process_runner: Callable[..., subprocess.CompletedProcess[str]],
+) -> SolPreflight:
+    """Run the existing usage probe and require a finite meter above its gate.
+
+    Args:
+        probe_path: Path to the installed usage probe.
+        process_runner: Callable used to execute the probe.
+
+    Returns:
+        The usage-meter eligibility decision and any fallback reason.
+    """
+    try:
+        completed_process = process_runner(
+            [sys.executable, str(probe_path)],
+            capture_output=True,
+            text=True,
+            check=False,
+            shell=False,
+            timeout=SOL_USAGE_PROBE_TIMEOUT_SECONDS,
+        )
+        if completed_process.returncode != 0:
+            return _preflight_fallback(
+                f"{SOL_PREFLIGHT_FAILURE_REASON}: probe exit {completed_process.returncode}",
+                None,
+            )
+        percent_left, parse_reason = _parse_probe_percent(completed_process.stdout)
+        if parse_reason is not None:
+            return _preflight_fallback(
+                f"{SOL_PREFLIGHT_FAILURE_REASON}: {parse_reason}", None
+            )
+        usage_gate = _load_usage_gate(probe_path)
+        if not callable(usage_gate) or percent_left is None:
+            return _preflight_fallback(
+                f"{SOL_PREFLIGHT_FAILURE_REASON}: usage meter is unknown", None
+            )
+        usage_gate = _load_usage_gate(probe_path)
+        if not usage_gate(percent_left):
+            return _preflight_fallback(
+                f"{SOL_PREFLIGHT_FAILURE_REASON}: usage meter is at or below the gate",
+                percent_left,
+            )
+    except subprocess.TimeoutExpired as probe_error:
+        return _preflight_fallback(f"{SOL_PROBE_TIMEOUT_REASON}: {probe_error}", None)
+    except (
+        OSError,
+        subprocess.SubprocessError,
+        ImportError,
+        AttributeError,
+        TypeError,
+        ValueError,
+    ) as probe_error:
+        return _preflight_fallback(
+            f"{SOL_PREFLIGHT_FAILURE_REASON}: {probe_error}", None
+        )
+    return SolPreflight(True, percent_left, "usage meter is above the Sol gate")
+
+
+def build_codex_arguments(session_id: str | None = None) -> list[str]:
+    """Build the installed CLI's shell-free bind or resume argv.
+
+    Args:
+        session_id: Optional existing session to resume.
+
+    Returns:
+        The shell-free Codex command argument vector.
+    """
+    command_arguments = [
+        CODEX_EXECUTABLE,
+        CODEX_EXEC_SUBCOMMAND,
+        CODEX_MODEL_FLAG,
+        ADVISOR_CODEX_MODEL_ID,
+        CODEX_CONFIG_FLAG,
+        CODEX_REASONING_CONFIG,
+        CODEX_SANDBOX_FLAG,
+        CODEX_READ_ONLY_SANDBOX,
+        CODEX_JSON_FLAG,
+    ]
+    if session_id is not None:
+        command_arguments.extend([CODEX_RESUME_SUBCOMMAND, session_id])
+    command_arguments.append(CODEX_PROMPT_FROM_STDIN)
+    return command_arguments
+
+
+def _guidance_signal(guidance: str) -> str | None:
+    for each_line in guidance.splitlines():
+        stripped_line = each_line.strip()
+        if not stripped_line:
+            continue
+        return stripped_line if stripped_line in ALL_ADVISOR_GUIDANCE_SIGNALS else None
+    return None
+
+
+def parse_codex_jsonl_reply(
+    jsonl_text: str,
+    existing_session_id: str | None,
+    is_sol_enabled: bool,
+) -> CodexSolAdvisorReply:
+    """Parse strict Codex JSONL into a session id and final guidance.
+
+    Args:
+        jsonl_text: JSONL emitted by the Codex CLI.
+        existing_session_id: Optional session id required on resume.
+        is_sol_enabled: Whether the attempted route had Sol enabled.
+
+    Returns:
+        The parsed guidance or an explicit Fable fallback reply.
+    """
+    discovered_session_id: str | None = None
+    final_guidance: str | None = None
+    try:
+        for each_line in jsonl_text.splitlines():
+            if not each_line.strip():
+                continue
+            event = json.loads(each_line)
+            if not isinstance(event, dict):
+                return _reply_fallback(SOL_MALFORMED_JSONL_REASON, is_sol_enabled)
+            if event.get("type") == "thread.started":
+                thread_id = event.get("thread_id")
+                if isinstance(thread_id, str) and thread_id.strip():
+                    discovered_session_id = thread_id.strip()
+            completed_event = event.get("item")
+            if (
+                event.get("type") == "item.completed"
+                and isinstance(completed_event, dict)
+                and completed_event.get("type") == "agent_message"
+                and isinstance(completed_event.get("text"), str)
+            ):
+                final_guidance = completed_event["text"].strip()
+    except (TypeError, json.JSONDecodeError):
+        return _reply_fallback(SOL_MALFORMED_JSONL_REASON, is_sol_enabled)
+    if discovered_session_id is None:
+        return _reply_fallback(SOL_MISSING_SESSION_REASON, is_sol_enabled)
+    if (
+        existing_session_id is not None
+        and discovered_session_id != existing_session_id
+    ):
+        return _reply_fallback(SOL_MISSING_SESSION_REASON, is_sol_enabled)
+    if not final_guidance:
+        return _reply_fallback(SOL_REPLY_FAILURE_REASON, is_sol_enabled)
+    guidance_signal = _guidance_signal(final_guidance)
+    if guidance_signal is None:
+        return _reply_fallback(SOL_INVALID_SIGNAL_REASON, is_sol_enabled)
+    return _reply_success(discovered_session_id, final_guidance, guidance_signal)
+
+
+def run_codex_sol_advisor(
+    prompt: str,
+    working_directory: Path,
+    preflight: SolPreflight | None,
+    probe_path: Path | None,
+    setting_by_name: Mapping[str, str] | None,
+    session_id: str | None,
+    process_runner: Callable[..., subprocess.CompletedProcess[str]],
+) -> CodexSolAdvisorReply:
+    """Run one usage-gated read-only Sol bind or resume attempt.
+
+    Args:
+        prompt: Advisor charter or delta consult sent to Codex.
+        working_directory: Repository directory supplied to the CLI.
+        preflight: Optional precomputed usage-meter decision.
+        probe_path: Optional installed usage-probe path.
+        setting_by_name: Optional environment-like settings mapping.
+        session_id: Existing session id for a resume attempt.
+        process_runner: Callable used to execute the probe and Codex.
+
+    Returns:
+        The parsed Sol guidance or an explicit Fable fallback reply.
+    """
+    is_sol_enabled = is_sol_advisor_enabled(setting_by_name)
+    if not is_sol_enabled:
+        return _reply_fallback("Sol advisor flag is disabled", False)
+    resolved_preflight = (
+        run_sol_preflight(
+            probe_path=(
+                resolve_usage_probe_path(Path.home())
+                if probe_path is None
+                else probe_path
+            ),
+            process_runner=process_runner,
+        )
+        if preflight is None
+        else preflight
+    )
+    if not resolved_preflight.eligible:
+        return _reply_fallback(resolved_preflight.reason, is_sol_enabled)
+    try:
+        completed_process = process_runner(
+            build_codex_arguments(session_id=session_id),
+            cwd=str(working_directory),
+            input=prompt,
+            capture_output=True,
+            text=True,
+            check=False,
+            shell=False,
+            timeout=SOL_CODEX_TIMEOUT_SECONDS,
+        )
+    except subprocess.TimeoutExpired as bind_error:
+        return _reply_fallback(
+            f"{SOL_CODEX_TIMEOUT_REASON}: {bind_error}", is_sol_enabled
+        )
+    except (OSError, subprocess.SubprocessError) as bind_error:
+        return _reply_fallback(
+            f"{SOL_BIND_FAILURE_REASON}: {bind_error}", is_sol_enabled
+        )
+    if completed_process.returncode != 0:
+        return _reply_fallback(
+            f"{SOL_BIND_FAILURE_REASON}: process exit {completed_process.returncode}",
+            is_sol_enabled,
+        )
+    return parse_codex_jsonl_reply(
+        completed_process.stdout,
+        existing_session_id=session_id,
+        is_sol_enabled=is_sol_enabled,
+    )
+
+
+def build_argument_parser() -> argparse.ArgumentParser:
+    """Build the command-line parser for Sol bind and resume.
+
+    Returns:
+        The parser for the helper's bind and resume modes.
+    """
+    argument_parser = argparse.ArgumentParser(
+        description="Bind or consult a read-only Codex Sol xhigh advisor."
+    )
+    mode_group = argument_parser.add_mutually_exclusive_group(required=True)
+    mode_group.add_argument("--bind", action="store_true")
+    mode_group.add_argument("--resume", metavar=SOL_SESSION_ID_METAVAR)
+    argument_parser.add_argument("--cwd", required=True, type=Path)
+    return argument_parser
+
+
+def main(all_cli_arguments: Sequence[str]) -> int:
+    """Run one bind or resume from stdin and print a JSON response.
+
+    Args:
+        all_cli_arguments: Command-line arguments without the program name.
+
+    Returns:
+        Zero for a successful Sol response, or one for an explicit fallback.
+    """
+    parsed_arguments = build_argument_parser().parse_args(list(all_cli_arguments))
+    advisor_reply = run_codex_sol_advisor(
+        prompt=sys.stdin.read(),
+        working_directory=parsed_arguments.cwd,
+        preflight=None,
+        probe_path=None,
+        setting_by_name=os.environ,
+        session_id=parsed_arguments.resume if not parsed_arguments.bind else None,
+        process_runner=subprocess.run,
+    )
+    reply_payload = asdict(advisor_reply)
+    reply_payload[SPAWN_OUTCOME_KEY] = reply_payload.pop("outcome")
+    print(json.dumps(reply_payload, sort_keys=True))
+    return 0 if advisor_reply.successful else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/_shared/advisor/scripts/config/advisor_scripts_constants/advisor_route_constants.py

@@ -0,0 +1,21 @@
+"""Shared advisor_route_constants for advisor selection and replies."""
+
+from __future__ import annotations
+
+ADVISOR_MODEL_TIER: str = "Sol"
+ADVISOR_CODEX_MODEL_ID: str = "gpt-5.6-sol"
+ADVISOR_FALLBACK_TIER: str = "Fable"
+ADVISOR_FALLBACK_RESULT: str = "fable"
+ALL_ADVISOR_GUIDANCE_SIGNALS: frozenset[str] = frozenset(
+    {"ENDORSE", "CORRECTION", "PLAN", "STOP"}
+)
+
+TIER_KEY: str = "tier"
+SPAWN_OUTCOME_KEY: str = "result"
+SPAWN_SUCCESS_TOKEN: str = "spawned"
+CLI_BIND_SUCCESS_TOKEN: str = "cli"
+CODEX_BIND_SUCCESS_TOKEN: str = "codex"
+
+ALL_CODEX_MODEL_ID_BY_TIER: dict[str, str] = {
+    ADVISOR_MODEL_TIER: ADVISOR_CODEX_MODEL_ID,
+}

package/_shared/advisor/scripts/config/advisor_scripts_constants/model_tier_run_validator_constants.py

@@ -1,17 +1,11 @@
 """Constants for the model-tier-run validator and CLI / Agent alias map.
 
 They name the parts of a spawn-walk log: the tier ladder (strongest
-first), the two host profiles, the spawn-log dict keys, and the tokens
-that mark a bind.
+first), the two host profiles, and the validation messages. Shared log
+keys and bind-result tokens live in ``advisor_route_constants``.
 
 ::
 
-    attempt = {"tier": "Opus", "result": "spawned"}
-                       ^^^^^^           ^^^^^^^^^
-                       a ladder tier    SPAWN_SUCCESS_TOKEN
-    ok:   "cli" marks a CLI Claude-chain bind (CLI_BIND_SUCCESS_TOKEN)
-    flag: any other result token counts as no bind
-
 The alias map turns each tier into its short CLI / Agent name (``opus``,
 ``third-party``), never a dated full model ID.
 
@@ -24,6 +18,11 @@ Host-profile detection (see ``detect_host_profile``):
 
 from __future__ import annotations
 
+from advisor_scripts_constants.advisor_route_constants import (
+    ADVISOR_FALLBACK_TIER,
+    ADVISOR_MODEL_TIER,
+)
+
 HOST_PROFILE_CLAUDE: str = "Claude"
 HOST_PROFILE_THIRD_PARTY: str = "ThirdParty"
 ALL_HOST_PROFILES: tuple[str, ...] = (
@@ -31,32 +30,35 @@ ALL_HOST_PROFILES: tuple[str, ...] = (
     HOST_PROFILE_THIRD_PARTY,
 )
 
-ALL_MODEL_TIERS: tuple[str, ...] = ("Fable", "Opus", "Sonnet", "Haiku")
+ALL_MODEL_TIERS: tuple[str, ...] = (
+    ADVISOR_FALLBACK_TIER,
+    "Opus",
+    "Sonnet",
+    "Haiku",
+)
 THIRD_PARTY_MODEL_TIER: str = "ThirdParty"
-ALL_KNOWN_TIER_NAMES: tuple[str, ...] = (*ALL_MODEL_TIERS, THIRD_PARTY_MODEL_TIER)
+ALL_KNOWN_TIER_NAMES: tuple[str, ...] = (
+    ADVISOR_MODEL_TIER,
+    *ALL_MODEL_TIERS,
+    THIRD_PARTY_MODEL_TIER,
+)
 THIRD_PARTY_CLI_ADVISOR_FLOOR_TIER: str = "Opus"
 
 ADVISOR_SENDMESSAGE_REPLY_WAIT_SECONDS: int = 120
 
 ALL_CLI_MODEL_ID_BY_TIER: dict[str, str] = {
-    "Fable": "fable",
+    ADVISOR_FALLBACK_TIER: "fable",
     "Opus": "opus",
     "Sonnet": "sonnet",
     "Haiku": "haiku",
     THIRD_PARTY_MODEL_TIER: "third-party",
 }
-
 HOST_PROFILE_ENV_VAR: str = "ADVISOR_HOST_PROFILE"
 THIRD_PARTY_ENV_VAR: str = "THIRD_PARTY"
 ALL_THIRD_PARTY_TRUTHY_VALUES: frozenset[str] = frozenset(
     {"1", "true", "yes", "on"}
 )
 
-TIER_KEY: str = "tier"
-SPAWN_OUTCOME_KEY: str = "result"
-SPAWN_SUCCESS_TOKEN: str = "spawned"
-CLI_BIND_SUCCESS_TOKEN: str = "cli"
-
 UNKNOWN_OWN_TIER_MESSAGE: str = "own_tier is not a known model tier"
 UNKNOWN_LADDER_NAME_ERROR: str = "ladder name is not a known model tier: {!r}"
 UNKNOWN_HOST_PROFILE_ERROR: str = "host profile is not a known profile: {!r}"

package/_shared/advisor/scripts/config/advisor_scripts_constants/sol_advisor_constants.py

@@ -0,0 +1,28 @@
+"""Constants for the optional Codex Sol xhigh advisor bind."""
+
+from __future__ import annotations
+
+CODEX_EXECUTABLE: str = "codex"
+CODEX_READ_ONLY_SANDBOX: str = "read-only"
+CODEX_JSON_FLAG: str = "--json"
+CODEX_MODEL_FLAG: str = "--model"
+CODEX_CONFIG_FLAG: str = "--config"
+CODEX_REASONING_CONFIG: str = 'model_reasoning_effort="xhigh"'
+CODEX_PROMPT_FROM_STDIN: str = "-"
+CODEX_EXEC_SUBCOMMAND: str = "exec"
+CODEX_RESUME_SUBCOMMAND: str = "resume"
+CODEX_SANDBOX_FLAG: str = "--sandbox"
+CLAUDE_CONFIG_DIRECTORY_NAME: str = ".claude"
+SOL_SESSION_ID_METAVAR: str = "SESSION_ID"
+SOL_CODEX_TIMEOUT_SECONDS: float = 120.0
+SOL_USAGE_PROBE_TIMEOUT_SECONDS: float = 30.0
+SOL_ENV_VAR: str = "ADVISOR_SOL_XHIGH"
+ALL_SOL_TRUTHY_VALUES: frozenset[str] = frozenset({"1", "true", "yes", "on"})
+SOL_PREFLIGHT_FAILURE_REASON: str = "sol preflight did not establish an eligible Codex meter"
+SOL_BIND_FAILURE_REASON: str = "Codex Sol xhigh bind failed"
+SOL_REPLY_FAILURE_REASON: str = "Codex Sol xhigh returned no advisor guidance"
+SOL_PROBE_TIMEOUT_REASON: str = "Codex Sol meter check timed out"
+SOL_CODEX_TIMEOUT_REASON: str = "Codex Sol xhigh request timed out"
+SOL_MALFORMED_JSONL_REASON: str = "Codex Sol xhigh returned malformed JSONL"
+SOL_MISSING_SESSION_REASON: str = "Codex Sol xhigh returned no session id"
+SOL_INVALID_SIGNAL_REASON: str = "Codex Sol xhigh returned an invalid guidance signal"

package/_shared/advisor/scripts/model_tier_run_validator.py

@@ -52,7 +52,6 @@ from advisor_scripts_constants.model_tier_run_validator_constants import (  # no
     ATTEMPT_ORDER_MISMATCH_MESSAGE,
     ATTEMPT_TIER_OUT_OF_SLICE_MESSAGE,
     CANDIDATE_TIERS_MISMATCH_MESSAGE,
-    CLI_BIND_SUCCESS_TOKEN,
     CLI_INVALID_JSON_EXIT_CODE,
     CLI_MISSING_PATH_EXIT_CODE,
     CLI_SUCCESS_EXIT_CODE,
@@ -62,13 +61,18 @@ from advisor_scripts_constants.model_tier_run_validator_constants import (  # no
     MISSING_FALLBACK_REASON_MESSAGE,
     SELECTED_TIER_MISMATCH_MESSAGE,
     SELECTED_TIER_NOT_NULL_MESSAGE,
-    SPAWN_OUTCOME_KEY,
-    SPAWN_SUCCESS_TOKEN,
     THIRD_PARTY_CLI_ADVISOR_FLOOR_TIER,
     THIRD_PARTY_MODEL_TIER,
-    TIER_KEY,
     UNKNOWN_OWN_TIER_MESSAGE,
 )
+from advisor_scripts_constants.advisor_route_constants import (  # noqa: E402
+    ADVISOR_MODEL_TIER,
+    CODEX_BIND_SUCCESS_TOKEN,
+    CLI_BIND_SUCCESS_TOKEN,
+    SPAWN_OUTCOME_KEY,
+    SPAWN_SUCCESS_TOKEN,
+    TIER_KEY,
+)
 from tier_model_ids import canonical_tier_name  # noqa: E402
 
 
@@ -79,6 +83,7 @@ class ModelTierRun:
     attempts: list[dict[str, str]]
     selected_tier: str | None
     fallback_reason: str | None = None
+    is_sol_enabled: bool = False
 
 
 class ModelTierRunError(ValueError):
@@ -95,15 +100,22 @@ def _canonical_tier_list(all_tier_names: list[str]) -> list[str] | None:
     return all_canonical_tiers
 
 
-def _expected_candidate_tiers(own_tier: str) -> list[str]:
+def _expected_candidate_tiers(
+    own_tier: str, is_sol_enabled: bool = False
+) -> list[str]:
     maybe_canonical_own_tier = canonical_tier_name(own_tier)
     if maybe_canonical_own_tier is None:
         raise ModelTierRunError(f"{UNKNOWN_OWN_TIER_MESSAGE}: {own_tier!r}")
+    if maybe_canonical_own_tier == ADVISOR_MODEL_TIER:
+        raise ModelTierRunError(f"{UNKNOWN_OWN_TIER_MESSAGE}: {own_tier!r}")
     if maybe_canonical_own_tier == THIRD_PARTY_MODEL_TIER:
         floor_index = ALL_MODEL_TIERS.index(THIRD_PARTY_CLI_ADVISOR_FLOOR_TIER)
-        return list(ALL_MODEL_TIERS[: floor_index + 1])
-    floor_index = ALL_MODEL_TIERS.index(maybe_canonical_own_tier)
-    return list(ALL_MODEL_TIERS[: floor_index + 1])
+    else:
+        floor_index = ALL_MODEL_TIERS.index(maybe_canonical_own_tier)
+    all_expected_candidates = list(ALL_MODEL_TIERS[: floor_index + 1])
+    if is_sol_enabled:
+        all_expected_candidates.insert(0, ADVISOR_MODEL_TIER)
+    return all_expected_candidates
 
 
 def _is_successful_attempt_outcome(
@@ -112,6 +124,10 @@ def _is_successful_attempt_outcome(
 ) -> bool:
     if canonical_tier == THIRD_PARTY_MODEL_TIER:
         return False
+    if canonical_tier == ADVISOR_MODEL_TIER:
+        return outcome_token == CODEX_BIND_SUCCESS_TOKEN
+    if outcome_token == CODEX_BIND_SUCCESS_TOKEN:
+        return False
     if outcome_token == SPAWN_SUCCESS_TOKEN:
         return True
     if outcome_token == CLI_BIND_SUCCESS_TOKEN:
@@ -144,7 +160,10 @@ def validate_model_tier_run(run: ModelTierRun) -> None:
     Raises:
         ModelTierRunError: When any invariant is violated.
     """
-    all_expected_candidates = _expected_candidate_tiers(run.own_tier)
+    all_expected_candidates = _expected_candidate_tiers(
+        run.own_tier,
+        is_sol_enabled=run.is_sol_enabled,
+    )
     maybe_canonical_candidates = _canonical_tier_list(run.candidate_tiers)
     if maybe_canonical_candidates != all_expected_candidates:
         raise ModelTierRunError(CANDIDATE_TIERS_MISMATCH_MESSAGE)
@@ -215,12 +234,16 @@ def load_model_tier_run_from_json_path(from_path: Path) -> ModelTierRun:
         TypeError: When a field has the wrong shape.
     """
     parsed_payload = json.loads(from_path.read_text(encoding="utf-8"))
+    raw_sol_enabled = parsed_payload.get("sol_enabled", False)
+    if not isinstance(raw_sol_enabled, bool):
+        raise TypeError("sol_enabled must be a boolean")
     return ModelTierRun(
         own_tier=parsed_payload["own_tier"],
         candidate_tiers=list(parsed_payload["candidate_tiers"]),
         attempts=list(parsed_payload["attempts"]),
         selected_tier=parsed_payload.get("selected_tier"),
         fallback_reason=parsed_payload.get("fallback_reason"),
+        is_sol_enabled=raw_sol_enabled,
     )