claude-dev-env 8.49.0 → 8.49.2

package/.agents/skills/second-account-workers/SKILL.md

@@ -22,7 +22,8 @@ JSON list of profile names, with the first choice first. Names use letters,
 digits, hyphens, and underscores. The worker uses the existing second profile
 when the file is absent. When the file exists, its list sets the full order.
 Keep `main` and `wait` out of the list because they name picker decisions.
-The picker tries each profile after checking the main account's expiring usage.
+The picker ranks main and every extra profile by room left and picks the one
+with the most.
 For direct picker calls, `--second-config-dir` sets the first extra profile and
 each `--extra-config-dir` adds another in the order given.
 Picker JSON prints `config_dir` for the choice and meters under `main`, `second`,

package/docs/second-claude-account.md

@@ -36,17 +36,19 @@ Claude refreshes it on each run.
 
 ## Which account a job uses
 
-The main account belongs to the person who works on it, so a job borrows it only
-to spend leftover usage that expires soon.
+The broker ranks every Claude account that has room and picks the one with the
+most room left. An account's room is the smaller of its 5-hour and weekly
+percent left. A resumed session stays on its account while that account has
+room.
 
-| Condition | Account |
+| Account | Has room while |
 |---|---|
-| Main week resets within 24 hours, main under 90% of its week, main under 50% of its 5-hour window | main |
-| Otherwise, second under 95% of its week and under 90% of its 5-hour window | second |
-| Second meter unreadable | wait until the meter can be read |
-| Otherwise | wait, with the next reset time |
+| main | under 90% of its week and under 50% of its 5-hour window |
+| second and each extra profile | under 95% of its week and under 90% of its 5-hour window |
 
-An unreadable main meter never picks main.
+When no account has room, the job waits until the next account reset, or for one
+hour when no reset is known. An unreadable meter never picks its account, and
+the wait reason names each account whose meter could not be read.
 
 ```
 python packages/claude-dev-env/scripts/account_broker.py choose --product claude

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.49.0",
+    "version": "8.49.2",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/scripts/account_broker.py

@@ -65,7 +65,6 @@ def choose_from_readings(
     now: datetime,
     all_spent_accounts: frozenset[Account] = frozenset(),
     preferred_command: str | None = None,
-    adapter: ProductAdapter | None = None,
     all_spent_resets: Mapping[Account, datetime] | None = None,
 ) -> Decision:
     """Choose an account or a wait.
@@ -80,10 +79,9 @@ def choose_from_readings(
     if product is Product.CODEX and not all_readings:
         home = Path(os.environ.get(CODEX_HOME_ENVIRONMENT_VARIABLE) or Path.home() / MAIN_CODEX_HOME_DIRECTORY_NAME).resolve()
         return Decision("run", Account(product, "default", home, True), None, "no roster is configured", TIER_NORMAL)
-    active = adapter or all_product_adapters[product]
     all_available = [each_reading for each_reading in all_readings if each_reading.account not in all_spent_accounts]
     selected = (
-        _choose_claude(all_available, now, preferred_command, active.main_guard)
+        _choose_claude(all_available, preferred_command)
         if product is Product.CLAUDE
         else _choose_codex(all_available)
     )
@@ -238,7 +236,7 @@ def _wait_outcome(context: _RunContext, decision: Decision) -> JobOutcome:
     if all_attempt_statuses == {"start_failed"}:
         return JobOutcome(COMMAND_MISSING_EXIT_CODE, "", "", None, tuple(context.all_attempts), "start_failed", None, None)
     status = "exhausted" if context.all_attempts else "wait"
-    return JobOutcome(WAIT_EXIT_CODE, "", "", None, tuple(context.all_attempts), status, None, decision.resets_at)
+    return JobOutcome(WAIT_EXIT_CODE, "", "", None, tuple(context.all_attempts), status, None, decision.resets_at, decision.reason)
 
 
 def _record_spent_attempt(context: _RunContext, account: Account, status: str, returncode: int | None) -> None:
@@ -314,7 +312,7 @@ def _execute(
 ) -> tuple[JobOutcome, Report]:
     context = _prepare_run(product, all_argv, now, timeout_seconds, stdin_text, cwd, encoding, errors)
     while True:
-        picked = choose_from_readings(product, context.all_readings, now=now, all_spent_accounts=frozenset(context.all_spent_accounts), preferred_command=context.preferred_command, adapter=context.active, all_spent_resets=context.all_spent_resets)
+        picked = choose_from_readings(product, context.all_readings, now=now, all_spent_accounts=frozenset(context.all_spent_accounts), preferred_command=context.preferred_command, all_spent_resets=context.all_spent_resets)
         decision = _with_outside_spent_marks(picked, _outside_roster_resets(product, context.all_readings, context.all_state, now))
         context.report.events.append({"type": "pick", "decision": decision_payload(decision)})
         if decision.account is None:

package/scripts/account_broker_support.py

@@ -212,8 +212,8 @@ def read_codex_account_meters(account: Account) -> Meters | 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),
+    Product.CLAUDE: ProductAdapter(load_claude_accounts, read_claude_meters, CLAUDE_CONFIG_DIR_ENV_VAR, ALL_USAGE_LIMIT_SIGNATURES),
+    Product.CODEX: ProductAdapter(load_codex_accounts, read_codex_account_meters, CODEX_HOME_ENVIRONMENT_VARIABLE, codex_usage_limit_signatures()),
 }
 
 

package/scripts/claude_account_worker.py

@@ -70,9 +70,9 @@ def _invocation(*, model: str | None, permission_mode: str) -> list[str]:
 
 
 def _wait_reason(outcome: JobOutcome) -> str:
-    if outcome.wait_reset_at is None:
+    if outcome.wait_reason is None:
         return "no account has room"
-    return f"no account has room; next reset at {outcome.wait_reset_at.isoformat()}"
+    return outcome.wait_reason
 
 
 def run_worker(

package/scripts/dev_env_scripts_constants/account_broker_constants.py

@@ -15,7 +15,6 @@ 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,
@@ -39,7 +38,6 @@ from shared_tree_paths import resolve_shared_scripts_directory
 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,
 }
@@ -57,7 +55,6 @@ BROKER_STATE_DIRECTORY_NAME = "account-broker"
 BROKER_STATE_FILE_NAME = "state.json"
 BROKER_STATE_TEMP_SUFFIX = ".json"
 BROKER_STATE_LOCK_SUFFIX = ".lock"
-SECONDS_PER_HOUR = 3600
 ALL_BATCH_FILE_EXTENSIONS = frozenset({".bat", ".cmd"})
 CMD_SHELL_METACHARACTERS = "&|<>^%!\"\r\n"
 ALL_PARENT_CLAUDE_SESSION_VARIABLES: frozenset[str] = frozenset({
@@ -180,6 +177,7 @@ class JobOutcome:
     status: str
     session_id: str | None
     wait_reset_at: datetime | None
+    wait_reason: str | None = None
 
 
 @dataclass
@@ -201,22 +199,6 @@ class ProductAdapter:
     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:
@@ -272,8 +254,6 @@ def _account_reset(reading: Reading, is_spent: bool = False) -> datetime | None:
             (meters.weekly_percent_left, ALL_CODEX_FLOORS["luna_stop_left"], meters.weekly_resets_at),
         )
     all_blocking_resets = [reset for room, floor, reset in blocking if room is not None and room <= floor and reset is not None]
-    if is_claude_main and meters.weekly_resets_at is not None:
-        all_blocking_resets.append(meters.weekly_resets_at - ALL_CLAUDE_FLOORS["main_spend_window"])
     return max(all_blocking_resets, default=None)
 
 
@@ -292,23 +272,22 @@ def _main_has_room(meters: Meters | None) -> bool:
     )
 
 
-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:
+def _claude_has_room(reading: Reading) -> bool:
+    if reading.account.is_main:
+        return _main_has_room(reading.meters)
+    return _claude_extra_tier(reading.meters) is not None
+
+
+def _choose_claude(all_available: Sequence[Reading], preferred_command: str | None) -> Decision | None:
+    all_with_room = [each_reading for each_reading in all_available if _claude_has_room(each_reading)]
+    for each_reading in all_with_room:
         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:
+        if preferred_command is not None and is_bound:
             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
+    roomiest = min(all_with_room, key=_rank_key, default=None)
+    if roomiest is None:
+        return None
+    return Decision("run", roomiest.account, None, f"{roomiest.account.name} has {roomiest.meters.tightest_percent_left:g}% left", TIER_NORMAL)
 
 
 def _choose_codex(all_available: Sequence[Reading]) -> Decision | None:
@@ -327,14 +306,38 @@ def _choose_codex_tier(all_candidates: Sequence[Reading], tier: str) -> Decision
     return None
 
 
+@dataclass(frozen=True)
+class _RetryTime:
+    at: datetime
+    is_known_reset: bool
+
+
+def _wait_reason(all_unreadable_names: Sequence[str], is_every_account_unreadable: bool, soonest: _RetryTime) -> str:
+    next_event = "reset" if soonest.is_known_reset else "check"
+    next_text = f"next {next_event} at {utc_time_text(soonest.at)}"
+    if not all_unreadable_names:
+        return f"no account has room; {next_text}"
+    unreadable_text = ", ".join(all_unreadable_names)
+    if is_every_account_unreadable:
+        return f"no account meter could be read ({unreadable_text}); {next_text}"
+    return f"no readable account has room; meter unreadable for {unreadable_text}; {next_text}"
+
+
 def _wait_decision(
     all_readings: Sequence[Reading], now: datetime, all_spent_accounts: frozenset[Account], all_spent_resets: Mapping[Account, datetime]
 ) -> Decision:
-    all_resets = []
+    next_check = _RetryTime(now + timedelta(hours=1), is_known_reset=False)
+    all_retry_times = []
     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")
+        all_retry_times.append(_RetryTime(reset, is_known_reset=True) if reset is not None and reset > now else next_check)
+    soonest = min(all_retry_times, key=lambda each_retry_time: each_retry_time.at, default=next_check)
+    all_unreadable_names = [
+        each_reading.account.name
+        for each_reading in all_readings
+        if each_reading.meters is None and each_reading.account not in all_spent_accounts
+    ]
+    is_every_account_unreadable = len(all_unreadable_names) == len(all_readings)
+    return Decision("wait", None, soonest.at, _wait_reason(all_unreadable_names, is_every_account_unreadable, soonest), "wait")

package/scripts/dev_env_scripts_constants/claude_account_constants.py

@@ -9,7 +9,6 @@ main account so its owner never runs out.
 from __future__ import annotations
 
 from dataclasses import dataclass
-from datetime import timedelta
 
 from dev_env_scripts_constants.shared_tree_constants import CLAUDE_CONFIG_DIR_ENV_VAR
 
@@ -128,9 +127,6 @@ WINDOWS_OS_NAME: str = "nt"
 TEXT_ENCODING: str = "utf-8"
 """Encoding for the launcher file and the JSON reports."""
 
-MAIN_SPEND_WINDOW: timedelta = timedelta(hours=24)
-"""Main takes jobs only when its weekly window resets within this span."""
-
 MAIN_WEEKLY_USED_CEILING_PERCENT: float = 90.0
 """Main takes jobs only while its weekly use is under this percent."""
 
@@ -146,9 +142,6 @@ SECOND_SESSION_USED_CEILING_PERCENT: float = 90.0
 FULL_PERCENT: float = 100.0
 """Percent scale ceiling, so remaining is this minus used."""
 
-SECONDS_PER_HOUR: int = 3600
-"""Seconds in one hour, for reason text that names hours until a reset."""
-
 CHOICE_MAIN: str = "main"
 """Picker answer: run the job on the main account."""
 
@@ -158,11 +151,6 @@ CHOICE_SECOND: str = "second"
 CHOICE_WAIT: str = "wait"
 """Picker answer: neither account has room, so the job waits."""
 
-REASON_MAIN_EXPIRING_TEMPLATE: str = (
-    "main week resets in {hours_until_reset} hours with {remaining_percent:.0f}% left"
-)
-"""Reason when main spends leftover usage that expires soon."""
-
 REASON_SECOND_HAS_ROOM_TEMPLATE: str = (
     "second account has {weekly_remaining_percent:.0f}% of its week"
     " and {session_remaining_percent:.0f}% of its 5-hour window left"

package/scripts/dev_env_scripts_constants/test_account_broker_constants.py

@@ -23,7 +23,6 @@ from dev_env_scripts_constants.account_broker_constants import (
 )
 from dev_env_scripts_constants.claude_account_constants import (
     MAIN_SESSION_USED_CEILING_PERCENT,
-    MAIN_SPEND_WINDOW,
     MAIN_WEEKLY_USED_CEILING_PERCENT,
     SECOND_SESSION_USED_CEILING_PERCENT,
     SECOND_WEEKLY_USED_CEILING_PERCENT,
@@ -41,7 +40,6 @@ def test_should_keep_claude_floors_tied_to_the_account_ceilings() -> None:
     assert 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,
     }

package/scripts/test_account_broker.py

@@ -10,6 +10,7 @@ from pathlib import Path
 import pytest
 
 import account_broker
+import claude_account_worker
 from account_broker import (
     Account,
     Meters,
@@ -71,7 +72,6 @@ def _adapter(accounts: tuple[Account, ...], meters: dict[str, Meters | None]) ->
         read_meters=lambda account: meters[account.name],
         environment_variable="CODEX_HOME",
         usage_limit_signatures=("rate limit",),
-        main_guard=False,
     )
 
 
@@ -112,7 +112,6 @@ def test_should_keep_list_order_when_tighter_windows_tie() -> None:
 @pytest.mark.parametrize(
     ("weekly_reset", "weekly_left", "short_left"),
     (
-        (NOW + timedelta(days=3), 20, 80),
         (NOW + timedelta(hours=4), 10, 80),
         (NOW + timedelta(hours=4), 20, 50),
     ),
@@ -131,24 +130,80 @@ def test_should_guard_main_at_each_limit(
     assert decision.account == extra.account
 
 
-def test_should_prioritize_main_when_its_guard_passes() -> None:
+def test_should_pick_main_when_it_has_more_room_than_every_extra() -> None:
     main = Reading(
         _account("main", Product.CLAUDE, main=True),
-        _meters(80, 20, weekly_reset=NOW + timedelta(hours=4)),
+        _meters(80, 80, weekly_reset=NOW + timedelta(days=5)),
+    )
+    extras = (
+        Reading(_account("second", Product.CLAUDE), _meters(60, 60)),
+        Reading(_account("third", Product.CLAUDE), _meters(40, 40)),
+    )
+
+    decision = choose_from_readings(Product.CLAUDE, (*extras, main), now=NOW)
+
+    assert decision.action == "run"
+    assert decision.account == main.account
+
+
+def test_should_pick_an_extra_with_more_room_than_main() -> None:
+    main = Reading(
+        _account("main", Product.CLAUDE, main=True),
+        _meters(60, 60, weekly_reset=NOW + timedelta(hours=4)),
     )
     extra = Reading(_account("extra", Product.CLAUDE), _meters(90, 90))
 
     decision = choose_from_readings(Product.CLAUDE, (main, extra), now=NOW)
 
+    assert decision.account == extra.account
+
+
+@pytest.mark.parametrize(("main_short_left", "expected_name"), ((51, "main"), (50, "extra")))
+def test_should_pick_main_only_while_under_its_5_hour_ceiling(
+    main_short_left: float, expected_name: str
+) -> None:
+    main = Reading(
+        _account("main", Product.CLAUDE, main=True),
+        _meters(main_short_left, 95, weekly_reset=NOW + timedelta(days=5)),
+    )
+    extra = Reading(_account("extra", Product.CLAUDE), _meters(20, 20))
+
+    decision = choose_from_readings(Product.CLAUDE, (main, extra), now=NOW)
+
+    assert decision.account.name == expected_name
+
+
+def test_should_pick_main_when_it_is_the_only_readable_account() -> None:
+    main = Reading(
+        _account("main", Product.CLAUDE, main=True),
+        _meters(80, 80, weekly_reset=NOW + timedelta(days=5)),
+    )
+    unread = Reading(_account("extra", Product.CLAUDE), None)
+
+    decision = choose_from_readings(Product.CLAUDE, (unread, main), now=NOW)
+
+    assert decision.action == "run"
     assert decision.account == main.account
 
 
+def test_should_wait_for_main_5_hour_reset_while_its_week_resets_days_away() -> None:
+    short_reset = NOW + timedelta(hours=2)
+    main = Reading(
+        _account("main", Product.CLAUDE, main=True),
+        _meters(40, 50, short_reset=short_reset, weekly_reset=NOW + timedelta(days=3)),
+    )
+
+    decision = choose_from_readings(Product.CLAUDE, (main,), now=NOW)
+
+    assert decision.action == "wait"
+    assert decision.resets_at == short_reset
+
+
 @pytest.mark.parametrize(
     ("short_left", "weekly_left", "weekly_reset", "expected_reset"),
     (
         (40, 20, NOW + timedelta(hours=4), NOW + timedelta(hours=2)),
         (80, 5, NOW + timedelta(hours=4), NOW + timedelta(hours=4)),
-        (80, 50, NOW + timedelta(days=3), NOW + timedelta(days=2)),
     ),
 )
 def test_should_wait_for_the_meter_or_window_that_blocks_main(
@@ -339,6 +394,104 @@ def test_should_wait_when_all_meter_reads_fail() -> None:
     assert decision.resets_at == NOW + timedelta(hours=1)
 
 
+_MAIN_CLAUDE = _account("main", Product.CLAUDE, main=True)
+_EV_CLAUDE = _account("ev", Product.CLAUDE)
+
+
+@pytest.mark.parametrize(
+    ("readings", "spent_resets", "expected_reason", "expected_resets_at"),
+    (
+        pytest.param(
+            (Reading(_MAIN_CLAUDE, None), Reading(_EV_CLAUDE, None)),
+            {},
+            "no account meter could be read (main, ev); next check at 2026-10-03T01:00:00+00:00",
+            NOW + timedelta(hours=1),
+            id="every-meter-unreadable",
+        ),
+        pytest.param(
+            (Reading(_MAIN_CLAUDE, _meters(40, 50, short_reset=NOW + timedelta(minutes=30))), Reading(_EV_CLAUDE, None)),
+            {},
+            "no readable account has room; meter unreadable for ev; next reset at 2026-10-03T00:30:00+00:00",
+            NOW + timedelta(minutes=30),
+            id="unreadable-beside-a-reset-before-the-check",
+        ),
+        pytest.param(
+            (Reading(_MAIN_CLAUDE, _meters(40, 50, short_reset=NOW + timedelta(hours=2))), Reading(_EV_CLAUDE, None)),
+            {},
+            "no readable account has room; meter unreadable for ev; next check at 2026-10-03T01:00:00+00:00",
+            NOW + timedelta(hours=1),
+            id="unreadable-beside-a-reset-after-the-check",
+        ),
+        pytest.param(
+            (Reading(_MAIN_CLAUDE, _meters(80, 80)), Reading(_EV_CLAUDE, None)),
+            {_MAIN_CLAUDE: NOW + timedelta(minutes=30)},
+            "no readable account has room; meter unreadable for ev; next reset at 2026-10-03T00:30:00+00:00",
+            NOW + timedelta(minutes=30),
+            id="unreadable-beside-a-spent-account",
+        ),
+        pytest.param(
+            (
+                Reading(_MAIN_CLAUDE, _meters(40, 50, short_reset=NOW + timedelta(hours=2))),
+                Reading(_EV_CLAUDE, _meters(5, 80, short_reset=NOW + timedelta(hours=3))),
+            ),
+            {},
+            "no account has room; next reset at 2026-10-03T02:00:00+00:00",
+            NOW + timedelta(hours=2),
+            id="every-meter-read-with-known-resets",
+        ),
+        pytest.param(
+            (Reading(_MAIN_CLAUDE, Meters(40, None, 50, None)),),
+            {},
+            "no account has room; next check at 2026-10-03T01:00:00+00:00",
+            NOW + timedelta(hours=1),
+            id="every-meter-read-without-a-known-reset",
+        ),
+    ),
+)
+def test_should_name_what_the_broker_knows_in_the_wait_reason(
+    readings: tuple[Reading, ...],
+    spent_resets: dict[Account, datetime],
+    expected_reason: str,
+    expected_resets_at: datetime,
+) -> None:
+    decision = choose_from_readings(
+        Product.CLAUDE,
+        readings,
+        now=NOW,
+        all_spent_accounts=frozenset(spent_resets),
+        all_spent_resets=spent_resets,
+    )
+
+    assert decision.action == "wait"
+    assert decision.reason == expected_reason
+    assert decision.resets_at == expected_resets_at
+
+
+def test_should_carry_the_unreadable_meter_reason_into_the_worker_report(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    adapter = _adapter((_MAIN_CLAUDE, _EV_CLAUDE), {"main": None, "ev": None})
+    monkeypatch.setitem(account_broker.all_product_adapters, Product.CLAUDE, adapter)
+    prompt_file = tmp_path / "brief.md"
+    prompt_file.write_text("standalone brief", encoding="utf-8")
+    report_file = tmp_path / "report.json"
+
+    with account_broker.override_subprocess_runner(lambda command, **options: pytest.fail("a waiting job ran")):
+        exit_code = claude_account_worker.run_worker(
+            prompt_file=prompt_file,
+            cwd=tmp_path,
+            report_file=report_file,
+            model=None,
+            permission_mode="auto",
+            timeout_minutes=60,
+        )
+
+    report = json.loads(report_file.read_text(encoding="utf-8"))
+    assert exit_code == WAIT_EXIT_CODE
+    assert report["account"] == "wait"
+    assert report["reason"].startswith("no account meter could be read")
+
+
 def test_should_replay_stdin_bytes_and_only_print_served_stdout(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str]
 ) -> None:
@@ -542,7 +695,7 @@ def test_should_list_accounts_without_reading_meters(
     monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None:
     account = _account("listed")
-    adapter = ProductAdapter(lambda: (account,), lambda _: pytest.fail("meter read"), "CODEX_HOME", (), False)
+    adapter = ProductAdapter(lambda: (account,), lambda _: pytest.fail("meter read"), "CODEX_HOME", ())
     monkeypatch.setitem(account_broker.all_product_adapters, Product.CODEX, adapter)
 
     assert account_broker.main(("accounts", "--product", "codex")) == 0
@@ -573,7 +726,7 @@ def test_should_reuse_meter_cache_for_60_seconds() -> None:
         calls.append(selected.name)
         return _meters(80, 80)
 
-    adapter = ProductAdapter(lambda: (account,), read_meter, "CODEX_HOME", (), False)
+    adapter = ProductAdapter(lambda: (account,), read_meter, "CODEX_HOME", ())
     state = account_broker._load_state(account_broker.broker_state_path())
 
     account_broker.read_accounts(Product.CODEX, adapter, all_state=state, now=NOW)

package/scripts/test_account_broker_support.py

@@ -88,7 +88,7 @@ def test_should_cache_account_reading_under_injected_state_path(
         seen.append(selected.name)
         return Meters(80.0, None, 80.0, None)
 
-    adapter = ProductAdapter(lambda: (account,), reader, "CODEX_HOME", (), False)
+    adapter = ProductAdapter(lambda: (account,), reader, "CODEX_HOME", ())
     state = support._load_state(support.broker_state_path())
     now = datetime(2026, 10, 3, tzinfo=timezone.utc)
 

package/scripts/test_agent_merge_check.py

@@ -2,16 +2,10 @@
 
 from __future__ import annotations
 
-import sys
 import urllib.parse
-from pathlib import Path
 
 import pytest
 
-_SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
-if str(_SCRIPTS_DIRECTORY) not in sys.path:
-    sys.path.insert(0, str(_SCRIPTS_DIRECTORY))
-
 import agent_merge_check
 from dev_env_scripts_constants.agent_merge_check_constants import (
     BEHIND_HOLD_REASON,

package/scripts/test_claude_account_worker.py

@@ -23,6 +23,7 @@ def _outcome(
     account_name: str | None = "extra_2",
     status: str = "served",
     wait_reset_at: datetime | None = None,
+    wait_reason: str | None = None,
 ) -> JobOutcome:
     return JobOutcome(
         returncode,
@@ -33,6 +34,7 @@ def _outcome(
         status,
         None,
         wait_reset_at,
+        wait_reason,
     )
 
 
@@ -86,20 +88,28 @@ def test_should_send_prompt_and_flags_to_broker(
     assert captured["timeout_seconds"] == 3600
 
 
-def test_should_report_wait_with_reset_and_exit_three(
+def test_should_report_the_broker_wait_reason_and_exit_three(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:
     reset_at = datetime(2026, 10, 4, 12, tzinfo=timezone.utc)
+    broker_reason = f"no readable account has room; meter unreadable for ev; next check at {reset_at.isoformat()}"
     exit_code, report, captured = _run_worker(
         monkeypatch,
         tmp_path,
-        _outcome(stdout="", returncode=WAIT_EXIT_CODE, account_name=None, status="wait", wait_reset_at=reset_at),
+        _outcome(
+            stdout="",
+            returncode=WAIT_EXIT_CODE,
+            account_name=None,
+            status="wait",
+            wait_reset_at=reset_at,
+            wait_reason=broker_reason,
+        ),
     )
 
     assert exit_code == WAIT_EXIT_CODE
     assert report["account"] == "wait"
     assert report["wait_reset_at"] == reset_at.isoformat()
-    assert report["reason"] == f"no account has room; next reset at {reset_at.isoformat()}"
+    assert report["reason"] == broker_reason
     assert report["is_error"] is False
     assert captured["product"] is Product.CLAUDE
 

package/scripts/test_resolve_worker_spawn.py

@@ -1118,7 +1118,6 @@ def test_usage_limit_fallover_delivers_full_prompt_to_each_account(
         lambda account: Meters(80, reset_at, 80, reset_at),
         "CLAUDE_CONFIG_DIR",
         ("usage limit",),
-        False,
     )
     observed: list[tuple[str, bytes]] = []