claude-dev-env 8.48.7 → 8.49.1

package/.agents/skills/pull-request/SKILL.md

@@ -205,6 +205,9 @@ The recovery command restores the named account and deletes only that record.
   `--confirm-inactive` before recovery.
 - Normal pull request actions never call `gh auth switch`. If that command
   appears outside explicit recovery, stop.
+- `gh auth switch`, `login`, and `logout` change the account for every session
+  on the machine, and a PreToolUse hook denies them. Scope another account to
+  one command: `GH_TOKEN=$(gh auth token -u <account>) gh <command>`.
 - GitHub CLI output can contain account data. The command captures account
   lookup and recovery output and prints only generic errors.
 

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/hooks/blocking/gh_global_account_switch_gate.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""PreToolUse gate: keep agents from changing the global GitHub CLI account.
+
+``gh auth switch``, ``gh auth login``, and ``gh auth logout`` write the shared
+gh configuration, so they change the active account for every session on the
+machine. A command segment whose program is ``gh`` and whose arguments start
+with one of those subcommands is denied, and the deny reason names the
+per-command ``GH_TOKEN`` form to run instead. The program is read past wrappers
+and chained commands, so ``cd x && gh auth switch`` and ``bash -c "gh auth
+logout"`` are denied too. ``gh auth status``, ``gh auth token``, and quoted text
+that only mentions the words pass.
+
+Hosted by ``blocking/bash_pre_tool_use_dispatcher.py`` for the Bash and
+PowerShell tools.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+try:
+    _hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+    if _hooks_root_directory not in sys.path:
+        sys.path.insert(0, _hooks_root_directory)
+    from hooks_constants.bash_pre_tool_use_dispatcher_constants import (
+        ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+        DENY_DECISION,
+        HOOK_EVENT_NAME,
+    )
+    from hooks_constants.gh_global_account_switch_gate_constants import (
+        ALL_GLOBAL_ACCOUNT_CHANGING_COMMAND_PATHS,
+        GATE_HOOK_NAME,
+        GH_COMMAND_PATH_LENGTH,
+        GH_PROGRAM_NAME,
+        GLOBAL_ACCOUNT_CHANGE_DENY_REASON,
+    )
+    from hooks_constants.hook_block_logger import log_hook_block
+    from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+    from hooks_constants.shell_command_pipeline import pipeline_segments_for_command
+    from hooks_constants.shell_command_wrappers import (
+        all_wrapped_command_texts,
+        segment_program_and_arguments,
+    )
+except ImportError as import_error:
+    raise ImportError(
+        "The gh global account switch gate cannot import its dependencies; "
+        "ensure the hooks directory is importable."
+    ) from import_error
+
+
+def _changes_global_gh_account(all_segment_tokens: list[str]) -> bool:
+    """Return True when a segment runs gh auth switch, login, or logout.
+
+    Args:
+        all_segment_tokens: One command segment's shell tokens.
+    """
+    program_name, all_arguments = segment_program_and_arguments(all_segment_tokens)
+    command_path = tuple(all_arguments[:GH_COMMAND_PATH_LENGTH])
+    return program_name.lower() == GH_PROGRAM_NAME and command_path in ALL_GLOBAL_ACCOUNT_CHANGING_COMMAND_PATHS
+
+
+def changes_global_gh_account(command: str) -> bool:
+    """Return True when any command segment changes the machine-wide gh account.
+
+    ::
+
+        gh auth switch -u <account>                          -> True
+        git fetch && gh auth login                           -> True
+        GH_TOKEN=$(gh auth token -u <account>) gh repo list  -> False
+        git commit -m "never run gh auth switch"             -> False
+
+    Args:
+        command: The shell command text the agent is about to run.
+    """
+    return any(
+        _changes_global_gh_account(each_segment)
+        for each_text in all_wrapped_command_texts(command)
+        for each_segment, _each_following_operator in pipeline_segments_for_command(each_text)
+    )
+
+
+def main() -> None:
+    """Deny a command that changes the global gh account, or stay quiet."""
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    if hook_payload is None:
+        return
+    tool_name = hook_payload.get("tool_name")
+    if tool_name not in ALL_BASH_AND_POWERSHELL_TOOL_NAMES:
+        return
+    tool_input = hook_payload.get("tool_input")
+    if not isinstance(tool_input, dict):
+        return
+    command = tool_input.get("command", "")
+    if not isinstance(command, str) or not changes_global_gh_account(command):
+        return
+    log_hook_block(
+        GATE_HOOK_NAME, HOOK_EVENT_NAME, GLOBAL_ACCOUNT_CHANGE_DENY_REASON, str(tool_name), command
+    )
+    sys.stdout.write(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": HOOK_EVENT_NAME,
+                    "permissionDecision": DENY_DECISION,
+                    "permissionDecisionReason": GLOBAL_ACCOUNT_CHANGE_DENY_REASON,
+                }
+            }
+        )
+    )
+    sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/test_bash_dispatcher_interpreter_starts.py

@@ -2,8 +2,9 @@
 
 A Bash tool call starts one interpreter, the dispatcher's own. Each roster
 entry then runs in that process through runpy, so the roster's exact content is
-the chain's cost after that single start. The roster holds the MSYS rewriter and
-the headless Claude broker gate; any other hook added here fails this test.
+the chain's cost after that single start. The roster holds the MSYS rewriter,
+the headless Claude broker gate, and the gh global account gate; any other hook
+added here fails this test.
 """
 
 import sys
@@ -21,7 +22,7 @@ from hooks_constants.bash_pre_tool_use_dispatcher_constants import (
 )
 
 
-def test_bash_roster_starts_only_the_msys_rewriter_and_the_broker_gate() -> None:
+def test_bash_roster_starts_only_the_msys_rewriter_and_the_two_gates() -> None:
     assert ALL_BASH_HOSTED_HOOK_ENTRIES == (
         BashHostedHookEntry(
             script_relative_path="blocking/msys_rev_path_rewriter.py",
@@ -31,4 +32,8 @@ def test_bash_roster_starts_only_the_msys_rewriter_and_the_broker_gate() -> None
             script_relative_path="blocking/headless_claude_broker_gate.py",
             applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
         ),
+        BashHostedHookEntry(
+            script_relative_path="blocking/gh_global_account_switch_gate.py",
+            applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+        ),
     )

package/hooks/blocking/test_gh_global_account_switch_gate.py

@@ -0,0 +1,100 @@
+"""Tests for gh_global_account_switch_gate, which keeps the global gh account fixed."""
+
+from __future__ import annotations
+
+import json
+from io import StringIO
+from unittest.mock import patch
+
+import pytest
+
+import gh_global_account_switch_gate as gate
+
+
+def _stdout_from_main(payload: dict[str, object]) -> str:
+    """Return what main() wrote to stdout for one hook payload."""
+    captured_stdout = StringIO()
+    with (
+        patch("sys.stdin", StringIO(json.dumps(payload))),
+        patch("sys.stdout", captured_stdout),
+        patch.object(gate, "log_hook_block"),
+    ):
+        gate.main()
+    return captured_stdout.getvalue()
+
+
+@pytest.mark.parametrize(
+    "command",
+    [
+        "gh auth switch",
+        "gh auth switch -u account-a",
+        "gh auth login",
+        "gh auth login --with-token",
+        "gh auth logout -u account-b",
+        "gh.exe auth switch -u account-b",
+        "cd repo && gh auth switch -u account-a",
+        "gh auth status; gh auth switch -u account-a",
+        "gh auth status || gh auth login",
+        'bash -c "gh auth switch -u account-a"',
+        'pwsh -Command "gh auth logout"',
+        "& gh auth switch",
+        "sudo gh auth switch --user account-b",
+    ],
+)
+def test_global_account_change_is_detected(command: str) -> None:
+    assert gate.changes_global_gh_account(command) is True
+
+
+@pytest.mark.parametrize(
+    "command",
+    [
+        "gh auth status",
+        "gh auth status --active",
+        "gh auth token -u account-a",
+        "GH_TOKEN=$(gh auth token -u account-a) gh repo list",
+        "$env:GH_TOKEN = gh auth token -u account-a; gh repo list; Remove-Item Env:GH_TOKEN",
+        "gh pr view 12",
+        "gh api user",
+        "gh",
+        'git commit -m "never call gh auth switch"',
+        'echo "gh auth switch"',
+        'grep -rn "gh auth login" docs',
+        "git switch main",
+    ],
+)
+def test_read_only_and_unrelated_commands_pass(command: str) -> None:
+    assert gate.changes_global_gh_account(command) is False
+
+
+def test_bash_payload_with_switch_is_denied_with_the_scoped_token_forms() -> None:
+    decision = json.loads(
+        _stdout_from_main(
+            {"tool_name": "Bash", "tool_input": {"command": "gh auth switch -u account-a"}}
+        )
+    )
+    specific_output = decision["hookSpecificOutput"]
+    assert specific_output["permissionDecision"] == "deny"
+    reason = specific_output["permissionDecisionReason"]
+    assert "GH_TOKEN=$(gh auth token -u <account>) gh <command>" in reason
+    assert (
+        "$env:GH_TOKEN = gh auth token -u <account>; gh <command>; Remove-Item Env:GH_TOKEN"
+        in reason
+    )
+
+
+def test_powershell_payload_with_logout_is_denied() -> None:
+    decision = json.loads(
+        _stdout_from_main({"tool_name": "PowerShell", "tool_input": {"command": "gh auth logout"}})
+    )
+    assert decision["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_scoped_token_payload_emits_nothing() -> None:
+    scoped_command = "GH_TOKEN=$(gh auth token -u account-b) gh repo list"
+    assert _stdout_from_main({"tool_name": "Bash", "tool_input": {"command": scoped_command}}) == ""
+
+
+def test_other_tool_payload_emits_nothing() -> None:
+    assert (
+        _stdout_from_main({"tool_name": "Write", "tool_input": {"command": "gh auth switch"}}) == ""
+    )

package/hooks/hooks_constants/bash_pre_tool_use_dispatcher_constants.py

@@ -63,4 +63,8 @@ ALL_BASH_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = (
         script_relative_path="blocking/headless_claude_broker_gate.py",
         applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
     ),
+    BashHostedHookEntry(
+        script_relative_path="blocking/gh_global_account_switch_gate.py",
+        applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+    ),
 )

package/hooks/hooks_constants/gh_global_account_switch_gate_constants.py

@@ -0,0 +1,33 @@
+"""Constants for the gate that keeps agents from changing the global gh account.
+
+Holds the GitHub CLI program name, the ``gh auth`` command paths that change the
+account every session on the machine uses and their word count, the hook name
+the block log records, and the deny message that names the per-command token
+form to run instead.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "GH_PROGRAM_NAME",
+    "GH_COMMAND_PATH_LENGTH",
+    "ALL_GLOBAL_ACCOUNT_CHANGING_COMMAND_PATHS",
+    "GATE_HOOK_NAME",
+    "GLOBAL_ACCOUNT_CHANGE_DENY_REASON",
+]
+
+GH_PROGRAM_NAME: str = "gh"
+GH_COMMAND_PATH_LENGTH: int = 2
+ALL_GLOBAL_ACCOUNT_CHANGING_COMMAND_PATHS: frozenset[tuple[str, ...]] = frozenset(
+    {("auth", "switch"), ("auth", "login"), ("auth", "logout")}
+)
+GATE_HOOK_NAME: str = "gh_global_account_switch_gate.py"
+GLOBAL_ACCOUNT_CHANGE_DENY_REASON: str = (
+    "BLOCKED: gh auth switch, login, and logout change the active GitHub CLI account "
+    "for every session on this machine, so other running agents lose access. "
+    "Scope the other signed-in account to one command instead. "
+    "Bash: GH_TOKEN=$(gh auth token -u <account>) gh <command>. "
+    "PowerShell: $env:GH_TOKEN = gh auth token -u <account>; gh <command>; Remove-Item Env:GH_TOKEN. "
+    "Run gh auth status to list the signed-in accounts. "
+    "Signing an account in or out is a step for the user to run."
+)

package/hooks/hooks_constants/test_bash_pre_tool_use_dispatcher_constants.py

@@ -12,7 +12,7 @@ ALL_BASH_AND_POWERSHELL_TOOL_NAMES = ALL_CONSTANT_BINDINGS["ALL_BASH_AND_POWERSH
 BashHostedHookEntry = ALL_CONSTANT_BINDINGS["BashHostedHookEntry"]
 
 
-def test_roster_hosts_only_the_msys_rewriter_and_the_broker_gate() -> None:
+def test_roster_hosts_the_msys_rewriter_the_broker_gate_and_the_gh_account_gate() -> None:
     assert ALL_BASH_HOSTED_HOOK_ENTRIES == (
         BashHostedHookEntry(
             script_relative_path="blocking/msys_rev_path_rewriter.py",
@@ -22,4 +22,8 @@ def test_roster_hosts_only_the_msys_rewriter_and_the_broker_gate() -> None:
             script_relative_path="blocking/headless_claude_broker_gate.py",
             applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
         ),
+        BashHostedHookEntry(
+            script_relative_path="blocking/gh_global_account_switch_gate.py",
+            applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+        ),
     )

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.48.7",
+    "version": "8.49.1",
     "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_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]] = []