claude-dev-env 8.38.3 → 8.39.0

package/_shared/advisor/reference/astra-rung.md

@@ -14,26 +14,26 @@ A Windows `setx` write only updates the persisted user environment; only a proce
 
 `ADVISOR_EFFORT` selects Codex `model_reasoning_effort` for Astra: `low`, `medium`, `high`, `xhigh`, or `max`. The policy default is `medium`, which sends `model_reasoning_effort="medium"`. Astra Xhigh and Max requests route to Medium. Pass `--effort <level>` on the helper to set effort for that Astra run without changing the environment. An unset value uses the policy default. An unknown value blocks advisor routing.
 
-Every fallback reply carries a `fallback_kind` field. `declined` means policy closed the rung (flag off, or the account picker named no Codex account on the `normal` tier). `broken` means the Astra path itself failed (missing executable, spawn error, timeout, malformed reply). A `broken` fallback is a defect to report.
+Every fallback reply carries a `fallback_kind` field. `declined` means policy closed the rung (flag off, or the account broker named no Codex account on the `normal` tier). `broken` means the Astra path itself failed (missing executable, spawn error, timeout, malformed reply). A `broken` fallback is a defect to report.
 
 ## Preflight
 
-Flag on: the helper asks the Codex account picker for an account first.
+Flag on: the helper asks the account broker for a Codex account first.
 
 ```
-python ~/.claude/scripts/codex_account_choice.py choose
+python ~/.claude/scripts/account_broker.py choose --product codex
 ```
 
-**GOTCHA. Picker path.** `codex_astra_advisor.resolve_account_picker_path` builds the picker path from the helper's own location: two directories above `_shared/advisor/scripts`, then `scripts/codex_account_choice.py`. Installed, that is `~/.claude/scripts/codex_account_choice.py`. Do not hunt other copies. Repo home: `packages/claude-dev-env/scripts/`. The accounts, their order, and sign-in steps are in [`codex-accounts.md`](../../../docs/codex-accounts.md).
+**Broker path.** `codex_astra_advisor.resolve_account_broker_path` builds the broker path from the helper's own location: two directories above `_shared/advisor/scripts`, then `scripts/account_broker.py`. Installed, that is `~/.claude/scripts/account_broker.py`. Repo home: `packages/claude-dev-env/scripts/`. The accounts, their order, and sign-in steps are in [`codex-accounts.md`](../../../docs/codex-accounts.md).
 
-The shared entry point is `~/.claude/_shared/advisor/scripts/codex_astra_advisor.py`. It runs the picker and owns Astra bind or resume parsing. Bind with `python ~/.claude/_shared/advisor/scripts/codex_astra_advisor.py --bind --enable-astra --cwd <repo-root>` and pipe the charter on stdin. Resume with `--resume <session_id>` and pipe the delta consult on stdin.
+The shared entry point is `~/.claude/_shared/advisor/scripts/codex_astra_advisor.py`. It runs the broker and owns Astra bind or resume parsing. Bind with `python ~/.claude/_shared/advisor/scripts/codex_astra_advisor.py --bind --enable-astra --cwd <repo-root>` and pipe the charter on stdin. Resume with `--resume <session_id>` and pipe the delta consult on stdin.
 
-The gate passes only when the picker exits 0 and answers `tier: normal` with a `codex_home` and a finite `percent_left`. The helper then runs Codex with `CODEX_HOME` set to that `codex_home`. A `luna` or `wait` answer fails closed when Opus did not bind.
+The gate passes only when the broker exits 0 and answers `decision.tier: normal` with a `decision.home` and finite session or weekly room in the `accounts` entry whose `name` and `home` match. With no roster configured, `accounts` is empty and the gate passes on `decision.home` alone. The helper then runs Codex with `CODEX_HOME` set to `decision.home`. A `luna` or `wait` answer, including exit 3 with a wait answer, declines the preflight when Opus did not bind.
 
 ## Branches
 
 **Preflight pass.** Bind one Codex CLI session at `gpt-6-astra` with `model_reasoning_effort` set from the policy-selected `ADVISOR_EFFORT` value, `--sandbox read-only`, and JSON output. The helper receives the standing-reviewer charter on stdin and returns only parsed ENDORSE / CORRECTION / PLAN / STOP guidance with a session ID.
 
-**Preflight fail.** A picker failure, non-zero exit, timeout, malformed answer, or a `luna` or `wait` tier fails closed when Opus did not bind.
+**Preflight fail.** A broker failure other than exit 3 with a wait answer, timeout, malformed answer, or a `luna` or `wait` tier fails closed when Opus did not bind.
 
 The helper owns the Astra attempt and returns an explicit fallback result. The consuming advisor path owns the Opus bind. Apply the same gate to every Astra attempt, including resume.

package/_shared/advisor/scripts/codex_astra_advisor.py

@@ -30,7 +30,7 @@ from advisor_scripts_constants.advisor_route_constants import (
 )
 from advisor_scripts_constants.astra_advisor_constants import (
     ADVISOR_CODEX_EXECUTABLE_ENV_VAR,
-    ALL_ACCOUNT_PICKER_RELATIVE_PARTS,
+    ALL_ACCOUNT_BROKER_RELATIVE_PARTS,
     ALL_ASTRA_TRUTHY_VALUES,
     ASTRA_BIND_FAILURE_REASON,
     ASTRA_CODEX_TIMEOUT_REASON,
@@ -174,18 +174,18 @@ def resolve_advisor_effort(all_settings: Mapping[str, str] | None) -> str:
     return resolve_advisor_pair(all_settings, None)[1]
 
 
-def resolve_account_picker_path() -> Path:
-    """Return the Codex account picker in the scripts directory beside this shared tree.
+def resolve_account_broker_path() -> Path:
+    """Return the account broker in the scripts directory beside this shared tree.
 
     ::
 
-        ~/.claude/_shared/advisor/scripts  ->  ~/.claude/scripts/codex_account_choice.py
+        ~/.claude/_shared/advisor/scripts  ->  ~/.claude/scripts/account_broker.py
 
     Returns:
-        Path to ``codex_account_choice.py``.
+        Path to ``account_broker.py``.
     """
     shared_root = _scripts_directory.parents[SHARED_PACKAGE_ROOT_PARENT_INDEX]
-    return shared_root.joinpath(*ALL_ACCOUNT_PICKER_RELATIVE_PARTS)
+    return shared_root.joinpath(*ALL_ACCOUNT_BROKER_RELATIVE_PARTS)
 
 
 def resolve_codex_executable(all_settings: Mapping[str, str] | None) -> str | None:
@@ -237,12 +237,12 @@ def build_codex_arguments(
 
 def _resolve_preflight(
     preflight: AstraPreflight | None,
-    picker_path: Path | None,
+    broker_path: Path | None,
     process_runner: Callable[..., subprocess.CompletedProcess[str]],
 ) -> AstraPreflight:
     if preflight is not None:
         return preflight
-    resolved_path = resolve_account_picker_path() if picker_path is None else picker_path
+    resolved_path = resolve_account_broker_path() if broker_path is None else broker_path
     return run_astra_preflight(resolved_path, process_runner)
 
 
@@ -331,7 +331,7 @@ def run_codex_astra_advisor(
     prompt: str,
     working_directory: Path,
     preflight: AstraPreflight | None,
-    picker_path: Path | None,
+    broker_path: Path | None,
     setting_by_name: Mapping[str, str] | None,
     session_id: str | None,
     process_runner: Callable[..., subprocess.CompletedProcess[str]],
@@ -341,11 +341,11 @@ def run_codex_astra_advisor(
     Args:
         prompt: Advisor prompt text.
         working_directory: Working directory for Codex.
-        preflight: Account picker result, or None to run the picker.
-        picker_path: Account picker path, or None for the one beside this shared tree.
+        preflight: Account broker result, or None to run the broker.
+        broker_path: Account broker path, or None for the one beside this shared tree.
         setting_by_name: Environment mapping, or None to read os.environ.
         session_id: Session to resume, or None for a new bind.
-        process_runner: Callable that runs the picker and Codex.
+        process_runner: Callable that runs the broker and Codex.
 
     Returns:
         Advisor reply, or a fallback.
@@ -355,7 +355,7 @@ def run_codex_astra_advisor(
     executable = resolve_codex_executable(setting_by_name)
     if executable is None:
         return build_fallback_reply(ASTRA_EXECUTABLE_NOT_FOUND_REASON, True)
-    resolved_preflight = _resolve_preflight(preflight, picker_path, process_runner)
+    resolved_preflight = _resolve_preflight(preflight, broker_path, process_runner)
     return _run_enabled_advisor(prompt, working_directory, setting_by_name, session_id, executable, resolved_preflight, process_runner)
 
 

package/_shared/advisor/scripts/codex_astra_preflight.py

@@ -1,4 +1,4 @@
-"""Ask the Codex account picker for an account before an Astra advisor request."""
+"""Ask the account broker for a Codex account before an Astra advisor request."""
 
 from __future__ import annotations
 
@@ -11,9 +11,12 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from advisor_scripts_constants.astra_advisor_constants import (
-    ACCOUNT_PICKER_CHOOSE_COMMAND,
+    ACCOUNT_BROKER_CHOOSE_COMMAND,
     ASTRA_ACCOUNT_PICK_TIMEOUT_REASON,
+    ALL_BROKER_ACCEPTED_EXIT_CODES,
+    ALL_BROKER_METER_PERCENT_KEYS,
     ASTRA_ACCOUNT_PICK_TIMEOUT_SECONDS,
+    BROKER_WAIT_EXIT_CODE,
     ASTRA_FALLBACK_KIND_BROKEN,
     ASTRA_FALLBACK_KIND_DECLINED,
     ASTRA_PREFLIGHT_FAILURE_REASON,
@@ -49,25 +52,51 @@ def _finite_percent(raw_percent: object) -> float | None:
 
 
 def _preflight_from_answer(field_by_name: dict[str, object]) -> AstraPreflight:
-    if not isinstance(field_by_name.get("tier"), str):
-        return _broken("picker answer is malformed")
-    if field_by_name["tier"] != CODEX_TIER_NORMAL:
-        reason = f"{ASTRA_PREFLIGHT_FAILURE_REASON}: no Codex account has room ({field_by_name.get('reason')})"
+    decision = field_by_name.get("decision")
+    if not isinstance(decision, dict) or not isinstance(decision.get("tier"), str):
+        return _broken("broker answer is malformed")
+    if decision["tier"] != CODEX_TIER_NORMAL:
+        reason = f"{ASTRA_PREFLIGHT_FAILURE_REASON}: no Codex account has room ({decision.get('reason')})"
         return _preflight_fallback(reason, None, ASTRA_FALLBACK_KIND_DECLINED)
-    codex_home = field_by_name.get("codex_home")
-    percent_left = _finite_percent(field_by_name.get("percent_left"))
-    if not isinstance(codex_home, str) or not codex_home or percent_left is None:
-        return _broken("picker answer names no Codex home with room")
-    reason = f"{field_by_name.get('account')} has {percent_left:.0f}% left"
-    return AstraPreflight(True, percent_left, reason, codex_home=Path(codex_home))
-
-
-def _run_picker(
-    picker_path: Path,
+    codex_home = decision.get("home")
+    account = decision.get("account")
+    accounts = field_by_name.get("accounts")
+    reason = decision.get("reason")
+    if not isinstance(codex_home, str) or not codex_home or not isinstance(account, str) or not isinstance(accounts, list):
+        return _broken("broker answer names no Codex home with room")
+    if not isinstance(reason, str):
+        return _broken("broker answer is malformed")
+    if not accounts:
+        return AstraPreflight(True, None, reason, codex_home=Path(codex_home))
+    chosen = next(
+        (
+            entry
+            for entry in accounts
+            if isinstance(entry, dict)
+            and entry.get("name") == account
+            and entry.get("home") == codex_home
+        ),
+        None,
+    )
+    meters = chosen.get("meters") if isinstance(chosen, dict) else None
+    if not isinstance(meters, dict):
+        return _broken("broker answer names no Codex home with room")
+    all_percent_left = [
+        percent
+        for key in ALL_BROKER_METER_PERCENT_KEYS
+        if (percent := _finite_percent(meters.get(key))) is not None
+    ]
+    if not all_percent_left:
+        return _broken("broker answer names no Codex home with room")
+    return AstraPreflight(True, min(all_percent_left), reason, codex_home=Path(codex_home))
+
+
+def _run_broker(
+    broker_path: Path,
     process_runner: Callable[..., subprocess.CompletedProcess[str]],
 ) -> subprocess.CompletedProcess[str]:
     return process_runner(
-        [sys.executable, str(picker_path), ACCOUNT_PICKER_CHOOSE_COMMAND],
+        [sys.executable, str(broker_path), ACCOUNT_BROKER_CHOOSE_COMMAND, "--product", "codex"],
         capture_output=True,
         text=True,
         check=False,
@@ -76,39 +105,39 @@ def _run_picker(
     )
 
 
-def _preflight_from_picker(completed: subprocess.CompletedProcess[str]) -> AstraPreflight:
-    if completed.returncode != 0:
-        return _broken(f"picker exit {completed.returncode}")
+def _preflight_from_broker(completed: subprocess.CompletedProcess[str]) -> AstraPreflight:
+    if completed.returncode not in ALL_BROKER_ACCEPTED_EXIT_CODES:
+        return _broken(f"broker exit {completed.returncode}")
     try:
         answer = json.loads(completed.stdout)
     except (TypeError, json.JSONDecodeError):
-        return _broken("picker answer is malformed")
+        return _broken("broker answer is malformed")
     if not isinstance(answer, dict):
-        return _broken("picker answer is malformed")
+        return _broken("broker answer is malformed")
+    if completed.returncode == BROKER_WAIT_EXIT_CODE:
+        decision = answer.get("decision")
+        if not isinstance(decision, dict) or not isinstance(decision.get("tier"), str):
+            return _broken("broker answer is malformed")
+        reason = f"{ASTRA_PREFLIGHT_FAILURE_REASON}: no Codex account has room ({decision.get('reason')})"
+        return _preflight_fallback(reason, None, ASTRA_FALLBACK_KIND_DECLINED)
     return _preflight_from_answer(answer)
 
 
 def run_astra_preflight(
-    picker_path: Path,
+    broker_path: Path,
     process_runner: Callable[..., subprocess.CompletedProcess[str]],
 ) -> AstraPreflight:
-    """Run the Codex account picker and decide whether Astra may bind.
-
-    ::
-
-        tier normal, codex-2, 62% left  -> eligible, codex_home of codex-2
-        tier luna or wait               -> declined
-        picker exit 1, bad JSON, timeout -> broken
+    """Run the Codex account broker and decide whether Astra may bind.
 
     Args:
-        picker_path: Path to ``codex_account_choice.py``.
-        process_runner: Callable that runs the picker.
+        broker_path: Path to ``account_broker.py``.
+        process_runner: Callable that runs the broker.
 
     Returns:
         Eligibility, the chosen account's percent left and Codex home, reason, and fallback kind.
     """
     try:
-        return _preflight_from_picker(_run_picker(picker_path, process_runner))
+        return _preflight_from_broker(_run_broker(broker_path, process_runner))
     except subprocess.TimeoutExpired as error:
         return _preflight_fallback(
             f"{ASTRA_ACCOUNT_PICK_TIMEOUT_REASON}: {error}", None, ASTRA_FALLBACK_KIND_BROKEN

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

@@ -14,10 +14,13 @@ CODEX_EXEC_SUBCOMMAND: str = "exec"
 CODEX_RESUME_SUBCOMMAND: str = "resume"
 CODEX_SANDBOX_FLAG: str = "--sandbox"
 CODEX_HOME_ENV_VAR: str = "CODEX_HOME"
-ALL_ACCOUNT_PICKER_RELATIVE_PARTS: tuple[str, ...] = ("scripts", "codex_account_choice.py")
+ALL_ACCOUNT_BROKER_RELATIVE_PARTS: tuple[str, ...] = ("scripts", "account_broker.py")
 SHARED_PACKAGE_ROOT_PARENT_INDEX: int = 2
-ACCOUNT_PICKER_CHOOSE_COMMAND: str = "choose"
+ACCOUNT_BROKER_CHOOSE_COMMAND: str = "choose"
 CODEX_TIER_NORMAL: str = "normal"
+BROKER_WAIT_EXIT_CODE: int = 3
+ALL_BROKER_ACCEPTED_EXIT_CODES: tuple[int, ...] = (0, BROKER_WAIT_EXIT_CODE)
+ALL_BROKER_METER_PERCENT_KEYS: tuple[str, ...] = ("session_percent_left", "weekly_percent_left")
 ASTRA_SESSION_ID_METAVAR: str = "SESSION_ID"
 ASTRA_CODEX_TIMEOUT_SECONDS: float = 120.0
 ASTRA_ACCOUNT_PICK_TIMEOUT_SECONDS: float = 150.0

package/_shared/advisor/scripts/tests/test_codex_astra_advisor.py

@@ -31,14 +31,28 @@ def _load_astra_module() -> ModuleType:
 astra_advisor = _load_astra_module()
 
 SCRIPTS_ROOT = Path(__file__).parent.parent
-PICKER_PATH = SCRIPTS_ROOT.parents[2] / "scripts" / "codex_account_choice.py"
+BROKER_PATH = SCRIPTS_ROOT.parents[2] / "scripts" / "account_broker.py"
 PICKED_CODEX_HOME = Path("codex-profiles") / "codex-2"
 NORMAL_ANSWER = {
-    "tier": "normal",
-    "account": "codex-2",
-    "codex_home": str(PICKED_CODEX_HOME),
-    "percent_left": 90,
-    "reason": "codex-2 has 90% left",
+    "decision": {
+        "action": "run",
+        "tier": "normal",
+        "account": "codex-2",
+        "home": str(PICKED_CODEX_HOME),
+        "resets_at": None,
+        "reason": "codex-2 has 90% left",
+    },
+    "accounts": [{
+        "name": "codex-2",
+        "home": str(PICKED_CODEX_HOME),
+        "is_main": False,
+        "meters": {
+            "session_percent_left": 90,
+            "session_resets_at": None,
+            "weekly_percent_left": 95,
+            "weekly_resets_at": None,
+        },
+    }],
 }
 ENABLED_SETTINGS = {astra_advisor.ASTRA_ENV_VAR: "1"}
 
@@ -48,9 +62,9 @@ def _codex_on_search_path(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr(astra_advisor.shutil, "which", lambda name: "codex")
 
 
-def _pick(payload: object, returncode: int = 0) -> subprocess.CompletedProcess[str]:
+def _broker_answer(payload: object, returncode: int = 0) -> subprocess.CompletedProcess[str]:
     return subprocess.CompletedProcess(
-        [sys.executable, str(PICKER_PATH), "choose"],
+        [sys.executable, str(BROKER_PATH), "choose", "--product", "codex"],
         returncode,
         json.dumps(payload),
         "",
@@ -83,7 +97,7 @@ def _two_step_runner(
         if all_call_keywords is not None:
             all_call_keywords.append(kwargs)
         if len(all_calls) == 1:
-            return _pick(NORMAL_ANSWER)
+            return _broker_answer(NORMAL_ANSWER)
         return subprocess.CompletedProcess(arguments, 0, _events(guidance=guidance), "")
     return runner
 
@@ -165,26 +179,26 @@ def test_argument_parser_accepts_astra_and_rejects_sol() -> None:
         parser.parse_args(["--bind", "--cwd", ".", "--enable-sol"])
 
 
-def test_account_picker_path_names_the_packaged_picker() -> None:
-    path = astra_advisor.resolve_account_picker_path()
-    assert path == PICKER_PATH.resolve()
+def test_should_resolve_packaged_account_broker_path() -> None:
+    path = astra_advisor.resolve_account_broker_path()
+    assert path == BROKER_PATH.resolve()
     assert path.is_file()
 
 
-def test_preflight_runs_the_picker_choose_command() -> None:
+def test_should_run_broker_choose_command_for_codex_preflight() -> None:
     all_calls: list[list[str]] = []
 
     def runner(arguments: list[str], **kwargs: object) -> subprocess.CompletedProcess[str]:
         all_calls.append(arguments)
-        return _pick(NORMAL_ANSWER)
+        return _broker_answer(NORMAL_ANSWER)
 
-    astra_advisor.run_astra_preflight(PICKER_PATH, runner)
-    assert all_calls == [[sys.executable, str(PICKER_PATH), "choose"]]
+    astra_advisor.run_astra_preflight(BROKER_PATH, runner)
+    assert all_calls == [[sys.executable, str(BROKER_PATH), "choose", "--product", "codex"]]
 
 
-def test_preflight_accepts_the_normal_tier_and_keeps_its_codex_home() -> None:
+def test_should_accept_normal_tier_and_keep_its_codex_home() -> None:
     preflight = astra_advisor.run_astra_preflight(
-        PICKER_PATH, lambda arguments, **kwargs: _pick(NORMAL_ANSWER)
+        BROKER_PATH, lambda arguments, **kwargs: _broker_answer(NORMAL_ANSWER)
     )
     assert preflight.eligible
     assert preflight.percent_left == 90
@@ -192,10 +206,13 @@ def test_preflight_accepts_the_normal_tier_and_keeps_its_codex_home() -> None:
 
 
 @pytest.mark.parametrize("tier", ["luna", "wait"])
-def test_preflight_declines_a_tier_without_room(tier: str) -> None:
-    answer = {**NORMAL_ANSWER, "tier": tier, "reason": "every account is low"}
+def test_should_decline_a_tier_without_room(tier: str) -> None:
+    answer = {
+        **NORMAL_ANSWER,
+        "decision": {**NORMAL_ANSWER["decision"], "tier": tier, "reason": "every account is low"},
+    }
     preflight = astra_advisor.run_astra_preflight(
-        PICKER_PATH, lambda arguments, **kwargs: _pick(answer)
+        BROKER_PATH, lambda arguments, **kwargs: _broker_answer(answer)
     )
     assert not preflight.eligible
     assert preflight.fallback_kind == astra_advisor.ASTRA_FALLBACK_KIND_DECLINED
@@ -205,23 +222,37 @@ def test_preflight_declines_a_tier_without_room(tier: str) -> None:
 @pytest.mark.parametrize(
     "payload",
     [
-        {"tier": None},
-        {**NORMAL_ANSWER, "codex_home": None},
-        {**NORMAL_ANSWER, "percent_left": "90"},
+        {"decision": {"tier": None}},
+        {**NORMAL_ANSWER, "decision": {**NORMAL_ANSWER["decision"], "home": None}},
+        {
+            **NORMAL_ANSWER,
+            "accounts": [{
+                "name": "codex-2",
+                "home": str(PICKED_CODEX_HOME),
+                "meters": {"session_percent_left": "90"},
+            }],
+        },
+        {
+            **NORMAL_ANSWER,
+            "accounts": [{
+                **NORMAL_ANSWER["accounts"][0],
+                "home": "codex-profiles/codex-1",
+            }],
+        },
         ["bad"],
     ],
 )
-def test_preflight_rejects_a_malformed_answer(payload: object) -> None:
+def test_should_reject_a_malformed_broker_answer(payload: object) -> None:
     preflight = astra_advisor.run_astra_preflight(
-        PICKER_PATH, lambda arguments, **kwargs: _pick(payload)
+        BROKER_PATH, lambda arguments, **kwargs: _broker_answer(payload)
     )
     assert not preflight.eligible
     assert preflight.fallback_kind == astra_advisor.ASTRA_FALLBACK_KIND_BROKEN
 
 
-def test_preflight_rejects_a_failed_picker() -> None:
+def test_should_reject_failed_broker_preflight() -> None:
     preflight = astra_advisor.run_astra_preflight(
-        PICKER_PATH, lambda arguments, **kwargs: _pick(NORMAL_ANSWER, returncode=1)
+        BROKER_PATH, lambda arguments, **kwargs: _broker_answer(NORMAL_ANSWER, returncode=1)
     )
     assert not preflight.eligible
     assert preflight.fallback_kind == astra_advisor.ASTRA_FALLBACK_KIND_BROKEN
@@ -250,14 +281,14 @@ def test_jsonl_parser_falls_back_for_invalid_reply(jsonl_text: str) -> None:
     assert not reply.successful
 
 
-def test_bind_runs_picker_then_codex_under_the_chosen_home() -> None:
+def test_should_bind_under_the_broker_chosen_home() -> None:
     calls: list[list[str]] = []
     all_call_keywords: list[dict[str, object]] = []
     reply = astra_advisor.run_codex_astra_advisor(
         "consult",
         Path("."),
         None,
-        PICKER_PATH,
+        BROKER_PATH,
         ENABLED_SETTINGS,
         None,
         _two_step_runner(calls, all_call_keywords=all_call_keywords),
@@ -282,7 +313,7 @@ def test_bind_routes_astra_xhigh_to_the_policy_effort() -> None:
         "consult",
         Path("."),
         None,
-        PICKER_PATH,
+        BROKER_PATH,
         settings,
         None,
         _two_step_runner(calls),
@@ -309,7 +340,7 @@ def test_disabled_flag_returns_declined_fallback() -> None:
 def test_missing_codex_returns_broken_fallback(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr(astra_advisor.shutil, "which", lambda name: None)
     reply = astra_advisor.run_codex_astra_advisor(
-        "consult", Path("."), None, PICKER_PATH, ENABLED_SETTINGS, None, subprocess.run
+        "consult", Path("."), None, BROKER_PATH, ENABLED_SETTINGS, None, subprocess.run
     )
     assert reply.is_fallback
     assert reply.fallback_kind == astra_advisor.ASTRA_FALLBACK_KIND_BROKEN
@@ -321,7 +352,7 @@ def test_resume_uses_existing_session() -> None:
         "resume",
         Path("."),
         None,
-        PICKER_PATH,
+        BROKER_PATH,
         ENABLED_SETTINGS,
         "thread-1",
         _two_step_runner(calls, "ENDORSE\nready"),

package/_shared/advisor/scripts/tests/test_codex_astra_preflight.py

@@ -3,22 +3,144 @@
 import json
 import subprocess
 import sys
+from datetime import datetime, timezone
 from pathlib import Path
 
+import pytest
+
 SCRIPTS_ROOT = Path(__file__).parent.parent
 sys.path.insert(0, str(SCRIPTS_ROOT / "config"))
 sys.path.insert(0, str(SCRIPTS_ROOT))
+sys.path.insert(0, str(SCRIPTS_ROOT.parents[2] / "scripts"))
 
+from account_broker import choose_from_readings, decision_payload, readings_payload
 from codex_astra_preflight import run_astra_preflight
+from dev_env_scripts_constants.account_broker_constants import (
+    Account,
+    Decision,
+    Meters,
+    Product,
+    Reading,
+)
+
+
+def test_should_accept_broker_normal_answer_and_use_tighter_meter(tmp_path: Path) -> None:
+    broker_path = tmp_path / "account_broker.py"
+    home = tmp_path / "codex-2"
+    answer = {
+        "decision": {
+            "action": "run",
+            "account": "codex-2",
+            "home": str(home),
+            "resets_at": None,
+            "reason": "codex-2 has 42% left",
+            "tier": "normal",
+        },
+        "accounts": [
+            {
+                "name": "codex-2",
+                "home": str(home),
+                "is_main": False,
+                "meters": {
+                    "session_percent_left": 72,
+                    "session_resets_at": None,
+                    "weekly_percent_left": 42,
+                    "weekly_resets_at": None,
+                },
+            }
+        ],
+    }
+    calls: list[list[str]] = []
+
+    def process_runner(arguments: list[str], **kwargs: object) -> subprocess.CompletedProcess[str]:
+        calls.append(arguments)
+        return subprocess.CompletedProcess(arguments, 0, json.dumps(answer), "")
+
+    preflight = run_astra_preflight(broker_path, process_runner)
+
+    assert calls == [[sys.executable, str(broker_path), "choose", "--product", "codex"]]
+    assert preflight.eligible
+    assert preflight.percent_left == 42
+    assert preflight.codex_home == home
+
+
+def test_should_decline_broker_wait_answer_on_exit_three(tmp_path: Path) -> None:
+    broker_path = tmp_path / "account_broker.py"
+    answer = {
+        "decision": {
+            "action": "wait",
+            "account": None,
+            "home": None,
+            "resets_at": None,
+            "reason": "no account has room",
+            "tier": "wait",
+        },
+        "accounts": [],
+    }
 
+    def process_runner(arguments: list[str], **kwargs: object) -> subprocess.CompletedProcess[str]:
+        return subprocess.CompletedProcess(arguments, 3, json.dumps(answer), "")
 
-def test_run_astra_preflight_rejects_picker_failure(tmp_path: Path) -> None:
-    picker_path = tmp_path / "codex_account_choice.py"
+    preflight = run_astra_preflight(broker_path, process_runner)
+
+    assert not preflight.eligible
+    assert preflight.fallback_kind == "declined"
+    assert "no account has room" in preflight.reason
+
+
+def test_should_reject_malformed_broker_answer_on_exit_three(tmp_path: Path) -> None:
+    broker_path = tmp_path / "account_broker.py"
+
+    def process_runner(arguments: list[str], **kwargs: object) -> subprocess.CompletedProcess[str]:
+        return subprocess.CompletedProcess(arguments, 3, "not json", "")
+
+    preflight = run_astra_preflight(broker_path, process_runner)
+
+    assert not preflight.eligible
+    assert preflight.fallback_kind == "broken"
+
+
+def test_should_reject_broker_failure(tmp_path: Path) -> None:
+    broker_path = tmp_path / "account_broker.py"
 
     def process_runner(*args: object, **kwargs: object) -> subprocess.CompletedProcess[str]:
         return subprocess.CompletedProcess([], 1, json.dumps({}), "")
 
-    preflight = run_astra_preflight(picker_path, process_runner)
+    preflight = run_astra_preflight(broker_path, process_runner)
 
     assert not preflight.eligible
     assert preflight.fallback_kind == "broken"
+
+
+def test_should_accept_the_answer_the_broker_serializes(tmp_path: Path) -> None:
+    account = Account(Product.CODEX, "codex-2", tmp_path / "codex-2")
+    reading = Reading(account, Meters(72.0, None, 42.0, None))
+    decision = Decision("run", account, None, "codex-2 has 42% left", "normal")
+    answer = {"decision": decision_payload(decision), "accounts": readings_payload([reading])}
+
+    def process_runner(arguments: list[str], **kwargs: object) -> subprocess.CompletedProcess[str]:
+        return subprocess.CompletedProcess(arguments, 0, json.dumps(answer), "")
+
+    preflight = run_astra_preflight(tmp_path / "account_broker.py", process_runner)
+
+    assert preflight.eligible
+    assert preflight.percent_left == 42
+    assert preflight.codex_home == tmp_path / "codex-2"
+
+
+def test_should_bind_the_default_home_when_no_roster_is_configured(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    default_home = tmp_path / ".codex"
+    monkeypatch.setenv("CODEX_HOME", str(default_home))
+    decision = choose_from_readings(Product.CODEX, [], now=datetime.now(timezone.utc))
+    answer = {"decision": decision_payload(decision), "accounts": readings_payload([])}
+
+    def process_runner(arguments: list[str], **kwargs: object) -> subprocess.CompletedProcess[str]:
+        return subprocess.CompletedProcess(arguments, 0, json.dumps(answer), "")
+
+    preflight = run_astra_preflight(tmp_path / "account_broker.py", process_runner)
+
+    assert preflight.eligible
+    assert preflight.percent_left is None
+    assert preflight.codex_home == default_home.resolve()