claude-dev-env 8.37.2 → 8.38.0

package/scripts/account_broker_support.py

@@ -0,0 +1,377 @@
+"""Choose and run Claude or Codex jobs through one account roster."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import tempfile
+import threading
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Iterator, Sequence
+
+import codex_account_choice
+import codex_account_meters
+from claude_account_profile import default_profile_home, validate_profile_name
+from claude_chain_usage import WeeklyUtilizationProbeError, probe_account_meters
+from dev_env_scripts_constants.account_broker_constants import (
+    BROKER_STATE_DIRECTORY_NAME,
+    BROKER_STATE_FILE_NAME,
+    BROKER_STATE_TEMP_SUFFIX,
+    Account,
+    BrokerConfigurationError,
+    Decision,
+    JobOutcome,
+    Meters,
+    Product,
+    ProductAdapter,
+    Reading,
+    Report,
+    REPORT_INDENT_SPACES,
+    SubprocessRunner,
+    codex_usage_limit_signatures,
+    parse_utc_time,
+    utc_time_text,
+)
+from dev_env_scripts_constants.claude_account_constants import (
+    CREDENTIALS_FILE_NAME,
+    EXTRA_PROFILES_FILE_NAME,
+    FULL_PERCENT,
+    MAIN_CLAUDE_HOME_DIRECTORY_NAME,
+)
+from dev_env_scripts_constants.claude_chain_constants import ALL_USAGE_LIMIT_SIGNATURES
+from dev_env_scripts_constants.codex_account_constants import (
+    CODEX_ACCOUNT_LAUNCHERS_FILE_NAME,
+    CODEX_ACCOUNT_PROFILES_ENVIRONMENT_VARIABLE,
+    CODEX_HOME_ENVIRONMENT_VARIABLE,
+    WEEKLY_WINDOW_MINUTES,
+)
+from dev_env_scripts_constants.shared_tree_constants import CLAUDE_CONFIG_DIR_ENV_VAR
+
+
+def _read_list(path: Path) -> object:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise BrokerConfigurationError(f"cannot read account list {path}: {error}") from error
+
+
+def _chain_entry(raw_entry: object, main_home: Path, chain_path: Path) -> Account:
+    if not isinstance(raw_entry, dict):
+        raise BrokerConfigurationError(f"invalid account list {chain_path}")
+    command = raw_entry.get("command")
+    credential = raw_entry.get("credentials_path")
+    extra_args = raw_entry.get("extra_args", [])
+    if not isinstance(command, str) or not command:
+        raise BrokerConfigurationError(f"invalid account list {chain_path}")
+    if credential is not None and (not isinstance(credential, str) or not credential):
+        raise BrokerConfigurationError(f"invalid account list {chain_path}")
+    if not isinstance(extra_args, list) or any(not isinstance(each_arg, str) for each_arg in extra_args):
+        raise BrokerConfigurationError(f"invalid account list {chain_path}")
+    home = Path(credential).expanduser().parent.resolve() if credential else main_home
+    return Account(Product.CLAUDE, command, home, command=command)
+
+
+def _chain_entries(chain_path: Path, main_home: Path) -> tuple[Account, ...]:
+    if not chain_path.exists():
+        return ()
+    document = _read_list(chain_path)
+    all_entries = document.get("chain") if isinstance(document, dict) else None
+    if not isinstance(all_entries, list) or not all_entries:
+        raise BrokerConfigurationError(f"invalid account list {chain_path}")
+    return tuple(_chain_entry(each_entry, main_home, chain_path) for each_entry in all_entries)
+
+
+def _extra_homes(main_home: Path) -> tuple[Path, ...]:
+    extras_path = main_home / EXTRA_PROFILES_FILE_NAME
+    if not extras_path.exists():
+        return (default_profile_home(),)
+    all_names = _read_list(extras_path)
+    if not isinstance(all_names, list) or not all_names or any(not isinstance(each_name, str) for each_name in all_names):
+        raise BrokerConfigurationError(f"invalid account list {extras_path}")
+    if len({each_name.casefold() for each_name in all_names}) != len(all_names):
+        raise BrokerConfigurationError(f"duplicate account in {extras_path}")
+    try:
+        return tuple(default_profile_home(validate_profile_name(each_name)) for each_name in all_names)
+    except ValueError as error:
+        raise BrokerConfigurationError(f"invalid account list {extras_path}: {error}") from error
+
+
+def _append_claude_account(
+    all_accounts: list[Account], all_seen: set[str], account: Account, main_home: Path
+) -> None:
+    key = str(account.home).casefold()
+    if key == str(main_home).casefold():
+        all_accounts[0] = Account(Product.CLAUDE, "main", main_home, True, account.command)
+    elif key not in all_seen:
+        all_accounts.append(account)
+        all_seen.add(key)
+
+
+def load_claude_accounts() -> tuple[Account, ...]:
+    """Read the Claude account roster.
+
+    Returns:
+        Main and additional accounts in configured order.
+
+    Raises:
+        BrokerConfigurationError: An account list is unreadable.
+    """
+    main_home = (Path.home() / MAIN_CLAUDE_HOME_DIRECTORY_NAME).resolve()
+    all_accounts = [Account(Product.CLAUDE, "main", main_home, True, "claude")]
+    all_seen = {str(main_home).casefold()}
+    for each_entry in _chain_entries(main_home / "claude-chain.json", main_home):
+        _append_claude_account(all_accounts, all_seen, each_entry, main_home)
+    for each_home in _extra_homes(main_home):
+        home = each_home.resolve()
+        _append_claude_account(all_accounts, all_seen, Account(Product.CLAUDE, home.name, home, command=home.name), main_home)
+    return tuple(all_accounts)
+
+
+def load_codex_accounts() -> tuple[Account, ...]:
+    """Read the Codex account roster.
+
+    Returns:
+        Configured accounts, or an empty tuple when none are configured.
+
+    Raises:
+        BrokerConfigurationError: The configured roster is unreadable.
+    """
+    profiles_root = codex_account_choice.default_profiles_root().resolve()
+    roster_path = profiles_root / CODEX_ACCOUNT_LAUNCHERS_FILE_NAME
+    configured = bool(os.environ.get(CODEX_ACCOUNT_PROFILES_ENVIRONMENT_VARIABLE, "").strip())
+    if not configured and not roster_path.exists():
+        return ()
+    if not configured and _read_list(roster_path) == []:
+        return ()
+    try:
+        names = codex_account_choice.codex_account_names(profiles_root)
+    except (OSError, ValueError) as error:
+        raise BrokerConfigurationError(f"cannot read account list {roster_path}: {error}") from error
+    return tuple(Account(Product.CODEX, name, (profiles_root / name).resolve()) for name in names)
+
+
+def read_claude_meters(account: Account) -> Meters | None:
+    """Probe one Claude account.
+
+    Args:
+        account: Account whose meter is read.
+
+    Returns:
+        Its meters, or None when the probe fails.
+    """
+    try:
+        usage = probe_account_meters(account.home / CREDENTIALS_FILE_NAME)
+    except (WeeklyUtilizationProbeError, OSError):
+        return None
+    return Meters(
+        FULL_PERCENT - usage.session_utilization if usage.session_utilization is not None else None,
+        usage.session_resets_at,
+        FULL_PERCENT - usage.weekly_utilization if usage.weekly_utilization is not None else None,
+        usage.weekly_resets_at,
+    )
+
+
+def read_codex_account_meters(account: Account) -> Meters | None:
+    """Probe one Codex account.
+
+    Args:
+        account: Account whose meter is read.
+
+    Returns:
+        Its meters, or None when the probe fails.
+    """
+    try:
+        codex_path = codex_account_meters.resolve_codex_path(None)
+        usage = codex_account_meters.read_codex_meters(codex_path, account.home)
+    except (codex_account_meters.CodexMeterUnreadError, OSError):
+        return None
+    weekly = [window for window in usage.all_windows if window.duration_minutes is None or window.duration_minutes >= WEEKLY_WINDOW_MINUTES]
+    short = [window for window in usage.all_windows if window.duration_minutes is not None and window.duration_minutes < WEEKLY_WINDOW_MINUTES]
+    weekly_window = max(weekly, key=lambda window: window.used_percent) if weekly else None
+    short_window = max(short, key=lambda window: window.used_percent) if short else None
+    return Meters(
+        usage.short_window_percent_left,
+        short_window.resets_at if short_window else None,
+        FULL_PERCENT - weekly_window.used_percent if weekly_window else None,
+        weekly_window.resets_at if weekly_window else None,
+    )
+
+
+all_product_adapters = {
+    Product.CLAUDE: ProductAdapter(load_claude_accounts, read_claude_meters, CLAUDE_CONFIG_DIR_ENV_VAR, ALL_USAGE_LIMIT_SIGNATURES, True),
+    Product.CODEX: ProductAdapter(load_codex_accounts, read_codex_account_meters, CODEX_HOME_ENVIRONMENT_VARIABLE, codex_usage_limit_signatures(), False),
+}
+
+
+def broker_state_path() -> Path:
+    return Path.home() / MAIN_CLAUDE_HOME_DIRECTORY_NAME / BROKER_STATE_DIRECTORY_NAME / BROKER_STATE_FILE_NAME
+
+
+def _load_state(path: Path) -> dict[str, object]:
+    if not path.exists():
+        return {"meters": {}, "spent": {}, "affinity": {}}
+    try:
+        parsed_state = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return {"meters": {}, "spent": {}, "affinity": {}}
+    if not isinstance(parsed_state, dict):
+        return {"meters": {}, "spent": {}, "affinity": {}}
+    return {key: parsed_state.get(key) if isinstance(parsed_state.get(key), dict) else {} for key in ("meters", "spent", "affinity")}
+
+
+def _save_state(path: Path, all_state: dict[str, object]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary_name: str | None = None
+    try:
+        with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", dir=path.parent, prefix="state-", suffix=BROKER_STATE_TEMP_SUFFIX, delete=False, newline="\n") as stream:
+            temporary_name = stream.name
+            json.dump(all_state, stream, indent=REPORT_INDENT_SPACES, sort_keys=True)
+            stream.write("\n")
+        os.replace(temporary_name, path)
+    finally:
+        if temporary_name is not None and os.path.exists(temporary_name):
+            os.unlink(temporary_name)
+
+
+def _state_key(account: Account) -> str:
+    return f"{account.product.value}:{account.name}:{account.home}"
+
+
+def _meter_payload(meters: Meters | None) -> dict[str, object] | None:
+    if meters is None:
+        return None
+    return {
+        "session_percent_left": meters.session_percent_left,
+        "session_resets_at": utc_time_text(meters.session_resets_at),
+        "weekly_percent_left": meters.weekly_percent_left,
+        "weekly_resets_at": utc_time_text(meters.weekly_resets_at),
+    }
+
+
+def _meters_from_payload(raw_meters: object) -> Meters | None:
+    if not isinstance(raw_meters, dict):
+        return None
+    all_percentages = (raw_meters.get("session_percent_left"), raw_meters.get("weekly_percent_left"))
+    if any(each_percent is not None and not isinstance(each_percent, (int, float)) for each_percent in all_percentages):
+        return None
+    return Meters(all_percentages[0], parse_utc_time(raw_meters.get("session_resets_at")), all_percentages[1], parse_utc_time(raw_meters.get("weekly_resets_at")))
+
+
+def _read_one_account(account: Account, adapter: ProductAdapter, all_cache: dict[str, object], now: datetime) -> tuple[Reading, bool]:
+    key = _state_key(account)
+    cached = all_cache.get(key)
+    if isinstance(cached, dict) and isinstance(cached.get("read_at"), (int, float)) and 0 <= now.timestamp() - cached["read_at"] < 60:
+        return Reading(account, _meters_from_payload(cached.get("meters"))), False
+    try:
+        meters = adapter.read_meters(account)
+    except (OSError, ValueError, RuntimeError, subprocess.SubprocessError):
+        meters = None
+    all_cache[key] = {"read_at": now.timestamp(), "meters": _meter_payload(meters)}
+    return Reading(account, meters), True
+
+
+def read_accounts(product: Product, adapter: ProductAdapter | None = None, *, all_state: dict[str, object] | None = None, now: datetime | None = None) -> tuple[Reading, ...]:
+    """Read account meters with a 60-second cache.
+
+    Args:
+        product: Product whose accounts are read.
+        adapter: Injected account and meter readers.
+        all_state: Mutable broker state document.
+        now: Clock instant used for cache age.
+
+    Returns:
+        Account readings in roster order.
+    """
+    active = adapter or all_product_adapters[product]
+    current = now or datetime.now(timezone.utc)
+    all_cache = all_state.get("meters", {}) if all_state is not None else {}
+    all_readings: list[Reading] = []
+    is_updated = False
+    for each_account in active.load_accounts():
+        reading, did_read = _read_one_account(each_account, active, all_cache, current)
+        all_readings.append(reading)
+        is_updated = is_updated or did_read
+    if is_updated and all_state is not None:
+        _save_state(broker_state_path(), all_state)
+    return tuple(all_readings)
+
+
+def _session_id_from_json(value: str) -> str | None:
+    try:
+        payload = json.loads(value)
+    except json.JSONDecodeError:
+        return None
+    session_id = payload.get("session_id") if isinstance(payload, dict) else None
+    return session_id if isinstance(session_id, str) and session_id else None
+
+
+def extract_session_id_from_stdout(stdout: str) -> str | None:
+    """Find a session id in JSON or newline-delimited JSON.
+
+    Args:
+        stdout: Captured command output.
+
+    Returns:
+        Session id, if present.
+    """
+    return _session_id_from_json(stdout.strip()) or next(
+        (found for line in stdout.splitlines() if (found := _session_id_from_json(line.strip())) is not None),
+        None,
+    )
+
+
+def _resume_id(all_argv: Sequence[str]) -> str | None:
+    for each_index, each_argument in enumerate(all_argv):
+        if each_argument == "--resume" and each_index + 1 < len(all_argv):
+            candidate = all_argv[each_index + 1]
+            return candidate if candidate and not candidate.startswith("-") else None
+    return None
+
+
+def _run_captured_subprocess(all_argv: Sequence[str], **options: object) -> subprocess.CompletedProcess[str]:
+    encoding = str(options.get("encoding") or "utf-8")
+    errors = str(options.get("errors") or "replace")
+    stdin_bytes = options.get("input")
+    with tempfile.TemporaryFile() as stdout_file, tempfile.TemporaryFile() as stderr_file:
+        completion = subprocess.run(
+            list(all_argv),
+            input=stdin_bytes,
+            stdout=stdout_file,
+            stderr=stderr_file,
+            env=options.get("env"),
+            cwd=options.get("cwd"),
+            timeout=options.get("timeout"),
+            check=False,
+        )
+        stdout_file.seek(0)
+        stderr_file.seek(0)
+        stdout = stdout_file.read().decode(encoding, errors).replace("\r\n", "\n").replace("\r", "\n")
+        stderr = stderr_file.read().decode(encoding, errors).replace("\r\n", "\n").replace("\r", "\n")
+    return subprocess.CompletedProcess(list(all_argv), completion.returncode, stdout, stderr)
+
+
+subprocess_runner: SubprocessRunner = _run_captured_subprocess
+_subprocess_runner_lock = threading.Lock()
+
+
+@contextmanager
+def override_subprocess_runner(runner: SubprocessRunner) -> Iterator[SubprocessRunner]:
+    """Replace the captured subprocess runner within a context.
+
+    Args:
+        runner: Replacement runner.
+
+    Yields:
+        Runner that was active before replacement.
+    """
+    global subprocess_runner
+    with _subprocess_runner_lock:
+        previous = subprocess_runner
+        subprocess_runner = runner
+        try:
+            yield previous
+        finally:
+            subprocess_runner = previous

package/scripts/dev_env_scripts_constants/account_broker_constants.py

@@ -0,0 +1,301 @@
+"""Account floors and command status values for the shared account broker."""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import subprocess
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from enum import Enum
+from pathlib import Path
+from typing import Callable, Mapping, Sequence
+
+from dev_env_scripts_constants.claude_account_constants import (
+    FULL_PERCENT,
+    MAIN_SESSION_USED_CEILING_PERCENT,
+    MAIN_SPEND_WINDOW,
+    MAIN_WEEKLY_USED_CEILING_PERCENT,
+    SECOND_SESSION_USED_CEILING_PERCENT,
+    SECOND_WEEKLY_USED_CEILING_PERCENT,
+)
+from dev_env_scripts_constants.codex_account_constants import (
+    CODEX_HOME_ENVIRONMENT_VARIABLE,
+    LUNA_TIER_SHORT_WINDOW_MINIMUM_PERCENT_LEFT,
+    LUNA_TIER_STOP_PERCENT_LEFT,
+    MAIN_CODEX_HOME_DIRECTORY_NAME,
+    NORMAL_TIER_MINIMUM_PERCENT_LEFT,
+    TIER_LUNA,
+    TIER_NORMAL,
+)
+
+ALL_CLAUDE_FLOORS = {
+    "main_weekly_used_ceiling": MAIN_WEEKLY_USED_CEILING_PERCENT,
+    "main_session_used_ceiling": MAIN_SESSION_USED_CEILING_PERCENT,
+    "main_spend_window": MAIN_SPEND_WINDOW,
+    "extra_weekly_used_ceiling": SECOND_WEEKLY_USED_CEILING_PERCENT,
+    "extra_session_used_ceiling": SECOND_SESSION_USED_CEILING_PERCENT,
+}
+
+ALL_CODEX_FLOORS = {
+    "normal_minimum_left": NORMAL_TIER_MINIMUM_PERCENT_LEFT,
+    "luna_stop_left": LUNA_TIER_STOP_PERCENT_LEFT,
+    "luna_short_minimum_left": LUNA_TIER_SHORT_WINDOW_MINIMUM_PERCENT_LEFT,
+}
+
+WAIT_EXIT_CODE = 3
+COMMAND_MISSING_EXIT_CODE = 127
+REPORT_INDENT_SPACES = 2
+BROKER_STATE_DIRECTORY_NAME = "account-broker"
+BROKER_STATE_FILE_NAME = "state.json"
+BROKER_STATE_TEMP_SUFFIX = ".json"
+SECONDS_PER_HOUR = 3600
+
+
+def codex_usage_limit_signatures() -> tuple[str, ...]:
+    """Load usage limit markers.
+
+    Returns:
+        Markers that identify usage limit responses.
+
+    Raises:
+        ImportError: The marker module cannot be loaded.
+    """
+    constants_path = Path(__file__).resolve().parents[2] / "_shared" / "pr-loop" / "scripts" / "codex_review_scripts_constants" / "classifier_constants.py"
+    specification = importlib.util.spec_from_file_location("account_broker_codex_classifier_constants", constants_path)
+    if specification is None or specification.loader is None:
+        raise ImportError(f"cannot load usage markers from {constants_path}")
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+    return module.ALL_USAGE_LIMIT_MARKERS
+
+
+def utc_time_text(moment: datetime | None) -> str | None:
+    return moment.astimezone(timezone.utc).isoformat() if moment is not None else None
+
+
+def parse_utc_time(timestamp: object) -> datetime | None:
+    """Parse an ISO timestamp as UTC.
+
+    Args:
+        timestamp: Serialized timestamp.
+
+    Returns:
+        UTC timestamp or None.
+    """
+    if not isinstance(timestamp, str):
+        return None
+    try:
+        parsed = datetime.fromisoformat(timestamp)
+    except ValueError:
+        return None
+    return parsed.astimezone(timezone.utc) if parsed.tzinfo is not None else None
+
+
+class Product(str, Enum):
+    CLAUDE = "claude"
+    CODEX = "codex"
+
+
+class BrokerConfigurationError(Exception):
+    """An account list cannot be read."""
+
+
+@dataclass(frozen=True)
+class Account:
+    product: Product
+    name: str
+    home: Path
+    is_main: bool = False
+    command: str | None = None
+
+
+@dataclass(frozen=True)
+class Meters:
+    session_percent_left: float | None
+    session_resets_at: datetime | None
+    weekly_percent_left: float | None
+    weekly_resets_at: datetime | None
+
+    @property
+    def tightest_percent_left(self) -> float | None:
+        all_percentages = (self.session_percent_left, self.weekly_percent_left)
+        return min((each_percent for each_percent in all_percentages if each_percent is not None), default=None)
+
+
+@dataclass(frozen=True)
+class Reading:
+    account: Account
+    meters: Meters | None
+
+
+@dataclass(frozen=True)
+class Decision:
+    action: str
+    account: Account | None
+    resets_at: datetime | None
+    reason: str
+    tier: str | None
+
+
+@dataclass(frozen=True)
+class JobOutcome:
+    returncode: int
+    stdout: str
+    stderr: str
+    account_name: str | None
+    attempts: tuple[tuple[str, str], ...]
+    status: str
+    session_id: str | None
+    wait_reset_at: datetime | None
+
+
+@dataclass
+class Report:
+    product: Product
+    command: list[str]
+    events: list[dict[str, object]] = field(default_factory=list)
+    final_decision: Decision | None = None
+
+
+MeterReader = Callable[[Account], Meters | None]
+AccountLoader = Callable[[], Sequence[Account]]
+SubprocessRunner = Callable[..., subprocess.CompletedProcess[str]]
+
+
+@dataclass(frozen=True)
+class ProductAdapter:
+    load_accounts: AccountLoader
+    read_meters: MeterReader
+    environment_variable: str
+    usage_limit_signatures: tuple[str, ...]
+    main_guard: bool
+
+
+
+def _main_reason(meters: Meters | None, now: datetime) -> str | None:
+    if meters is None or meters.session_percent_left is None or meters.weekly_percent_left is None or meters.weekly_resets_at is None:
+        return None
+    until_reset = meters.weekly_resets_at - now
+    if (
+        until_reset > ALL_CLAUDE_FLOORS["main_spend_window"]
+        or meters.weekly_percent_left <= FULL_PERCENT - ALL_CLAUDE_FLOORS["main_weekly_used_ceiling"]
+        or meters.session_percent_left <= FULL_PERCENT - ALL_CLAUDE_FLOORS["main_session_used_ceiling"]
+    ):
+        return None
+    hours = int(until_reset.total_seconds() // SECONDS_PER_HOUR)
+    return f"main week resets in {hours} hours with {meters.weekly_percent_left:.0f}% left"
+
+
+def _claude_extra_tier(meters: Meters | None) -> str | None:
+    if meters is None or meters.tightest_percent_left is None:
+        return None
+    if (
+        meters.weekly_percent_left is not None
+        and meters.weekly_percent_left <= FULL_PERCENT - ALL_CLAUDE_FLOORS["extra_weekly_used_ceiling"]
+    ) or (
+        meters.session_percent_left is not None
+        and meters.session_percent_left <= FULL_PERCENT - ALL_CLAUDE_FLOORS["extra_session_used_ceiling"]
+    ):
+        return None
+    return "normal"
+
+
+def _codex_tier(meters: Meters | None) -> str | None:
+    if meters is None or meters.tightest_percent_left is None:
+        return None
+    if meters.tightest_percent_left > ALL_CODEX_FLOORS["normal_minimum_left"]:
+        return "normal"
+    if (
+        meters.tightest_percent_left > ALL_CODEX_FLOORS["luna_stop_left"]
+        and (
+            meters.session_percent_left is None
+            or meters.session_percent_left >= ALL_CODEX_FLOORS["luna_short_minimum_left"]
+        )
+    ):
+        return "luna"
+    return None
+
+
+def _account_reset(reading: Reading, is_spent: bool = False) -> datetime | None:
+    meters = reading.meters
+    if meters is None:
+        return None
+    if is_spent:
+        return min((reset for reset in (meters.session_resets_at, meters.weekly_resets_at) if reset is not None), default=None)
+    if reading.account.product is Product.CLAUDE:
+        if reading.account.is_main:
+            return meters.weekly_resets_at
+        blocking = (
+            (meters.session_percent_left, FULL_PERCENT - ALL_CLAUDE_FLOORS["extra_session_used_ceiling"], meters.session_resets_at),
+            (meters.weekly_percent_left, FULL_PERCENT - ALL_CLAUDE_FLOORS["extra_weekly_used_ceiling"], meters.weekly_resets_at),
+        )
+    else:
+        blocking = (
+            (meters.session_percent_left, ALL_CODEX_FLOORS["luna_short_minimum_left"], meters.session_resets_at),
+            (meters.weekly_percent_left, ALL_CODEX_FLOORS["luna_stop_left"], meters.weekly_resets_at),
+        )
+    return max((reset for room, floor, reset in blocking if room is not None and room <= floor and reset is not None), default=None)
+
+
+def _rank_key(reading: Reading) -> float:
+    room = reading.meters.tightest_percent_left if reading.meters else None
+    return -(room if room is not None else -1.0)
+
+
+def _main_has_room(meters: Meters | None) -> bool:
+    return bool(
+        meters is not None
+        and meters.session_percent_left is not None
+        and meters.weekly_percent_left is not None
+        and meters.session_percent_left > FULL_PERCENT - ALL_CLAUDE_FLOORS["main_session_used_ceiling"]
+        and meters.weekly_percent_left > FULL_PERCENT - ALL_CLAUDE_FLOORS["main_weekly_used_ceiling"]
+    )
+
+
+def _choose_claude(
+    all_available: Sequence[Reading], now: datetime, preferred_command: str | None, has_main_guard: bool
+) -> Decision | None:
+    for each_reading in all_available:
+        is_bound = preferred_command in (each_reading.account.command, each_reading.account.name)
+        has_room = _main_has_room(each_reading.meters) if each_reading.account.is_main else bool(_claude_extra_tier(each_reading.meters))
+        if preferred_command is not None and is_bound and has_room:
+            return Decision("run", each_reading.account, None, "resume affinity", TIER_NORMAL)
+    main = next((each_reading for each_reading in all_available if each_reading.account.is_main), None)
+    main_reason = _main_reason(main.meters, now) if main and has_main_guard else None
+    if main is not None and main_reason is not None:
+        return Decision("run", main.account, None, main_reason, TIER_NORMAL)
+    extras = sorted((each_reading for each_reading in all_available if not each_reading.account.is_main), key=_rank_key)
+    for each_reading in extras:
+        if _claude_extra_tier(each_reading.meters):
+            return Decision("run", each_reading.account, None, f"{each_reading.account.name} has {each_reading.meters.tightest_percent_left:g}% left", TIER_NORMAL)
+    return None
+
+
+def _choose_codex(all_available: Sequence[Reading]) -> Decision | None:
+    all_candidates = sorted(all_available, key=_rank_key)
+    for each_tier in (TIER_NORMAL, TIER_LUNA):
+        chosen = _choose_codex_tier(all_candidates, each_tier)
+        if chosen is not None:
+            return chosen
+    return None
+
+
+def _choose_codex_tier(all_candidates: Sequence[Reading], tier: str) -> Decision | None:
+    for each_reading in all_candidates:
+        if _codex_tier(each_reading.meters) == tier:
+            return Decision("run", each_reading.account, None, f"{each_reading.account.name} has {each_reading.meters.tightest_percent_left:g}% left", tier)
+    return None
+
+
+def _wait_decision(
+    all_readings: Sequence[Reading], now: datetime, all_spent_accounts: frozenset[Account], all_spent_resets: Mapping[Account, datetime]
+) -> Decision:
+    all_resets = []
+    for each_reading in all_readings:
+        is_spent = each_reading.account in all_spent_accounts
+        reset = all_spent_resets.get(each_reading.account) if is_spent else None
+        reset = reset or _account_reset(each_reading, is_spent)
+        all_resets.append(reset if reset is not None and reset > now else now + timedelta(hours=1))
+    soonest = min(all_resets, default=now + timedelta(hours=1))
+    return Decision("wait", None, soonest, f"no account has room; next reset at {utc_time_text(soonest)}", "wait")