claude-dev-env 8.79.0 → 8.80.0

package/hooks/hooks_constants/test_shell_command_wrappers.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import base64
+
 import pytest
 
 from hooks_constants import shell_command_wrappers
@@ -31,6 +33,29 @@ def test_should_return_only_the_command_when_no_wrapper_runs() -> None:
     assert shell_command_wrappers.all_wrapped_command_texts("git push") == ["git push"]
 
 
+@pytest.mark.parametrize(
+    "command",
+    [
+        "git push",
+        'bash -c "git add -A && git push"; echo done',
+        "bash -c \"pwsh -Command 'git push; git status'\"",
+        "sudo bash -c 'gh pr list' | head",
+        'echo "$(git push)"',
+        "x=`git push`",
+    ],
+)
+def test_should_return_the_segments_of_every_wrapped_command_text(command: str) -> None:
+    all_segments_from_texts = [
+        each_segment
+        for each_text in shell_command_wrappers.all_wrapped_command_texts(command)
+        for each_segment, _following_operator in (
+            shell_command_wrappers.pipeline_segments_for_command(each_text)
+        )
+    ]
+    all_segments = shell_command_wrappers.all_wrapped_command_segments(command)
+    assert sorted(all_segments) == sorted(all_segments_from_texts)
+
+
 @pytest.mark.parametrize(
     ("all_segment_tokens", "expected_program_and_arguments"),
     [
@@ -50,6 +75,13 @@ def test_should_return_only_the_command_when_no_wrapper_runs() -> None:
         (["time", "sudo", "git", "push"], ("git", ["push"])),
         (["'/usr/bin/git'", "push"], ("git", ["push"])),
         (["VAR=x"], ("", [])),
+        (["if", "git", "push"], ("git", ["push"])),
+        (["then", "git", "push"], ("git", ["push"])),
+        (["if", "!", "git", "push"], ("git", ["push"])),
+        (["while", "git", "push"], ("git", ["push"])),
+        (["command", "git", "push"], ("git", ["push"])),
+        (["command", "-p", "git", "push"], ("git", ["push"])),
+        (["exec", "-a", "name", "git", "push"], ("git", ["push"])),
     ],
 )
 def test_should_return_the_program_past_its_wrappers(
@@ -59,3 +91,96 @@ def test_should_return_the_program_past_its_wrappers(
         shell_command_wrappers.segment_program_and_arguments(all_segment_tokens)
         == expected_program_and_arguments
     )
+
+
+@pytest.mark.parametrize(
+    ("command", "all_expected_texts"),
+    [
+        ('echo "$(gh pr list)"', ["gh pr list"]),
+        ("x=`git push`", ["git push"]),
+        ("echo $(echo $(git push))", ["echo $(git push)"]),
+        ("echo $(cat <(ls))", ["cat <(ls)"]),
+        ("echo \"$(printf ')'; git push)\"", ["printf ')'; git push"]),
+        ('echo $(echo "$(git push)")', ['echo "$(git push)"']),
+        ("x=`echo \\`git push\\``", ["echo `git push`"]),
+        ("echo '$(gh pr list)'", []),
+        ("echo \\$(gh pr list)", []),
+        ("git push", []),
+    ],
+)
+def test_should_return_each_command_substitution_body_outside_single_quotes(
+    command: str, all_expected_texts: list[str]
+) -> None:
+    assert shell_command_wrappers.all_command_substitution_texts(command) == all_expected_texts
+
+
+def test_should_unwrap_a_command_substitution_in_turn() -> None:
+    all_command_texts = shell_command_wrappers.all_wrapped_command_texts(
+        "echo \"$(bash -c 'git push')\""
+    )
+    assert "bash -c 'git push'" in all_command_texts
+    assert "git push" in all_command_texts
+
+
+_ENCODED_GIT_PUSH = base64.b64encode("git push".encode("utf-16-le")).decode()
+
+
+@pytest.mark.parametrize(
+    ("all_segment_tokens", "expected_inner_command"),
+    [
+        (["eval", "git push"], "git push"),
+        (["eval", "git", "push"], "git push"),
+        (["Invoke-Expression", "'git push'"], "git push"),
+        (["iex", '"git push"'], "git push"),
+        (["find", ".", "-exec", "git", "push", ";"], "git push"),
+        (["find", ".", "-execdir", "git", "push", "{}", "+"], "git push {}"),
+        (["pwsh", "-EncodedCommand", _ENCODED_GIT_PUSH], "git push"),
+        (["powershell.exe", "-enc", _ENCODED_GIT_PUSH], "git push"),
+        (["pwsh", "-e", _ENCODED_GIT_PUSH], "git push"),
+        (["pwsh", "-ec", _ENCODED_GIT_PUSH], "git push"),
+        (["pwsh", "-e", "not-base64!"], None),
+        (["find", ".", "-exec", "true", ";", "-exec", "git", "push", ";"], "true ; git push"),
+        (["-exec", "git", "push", "\\"], "git push \\"),
+        (["pwsh", "-e", f"'{_ENCODED_GIT_PUSH[:8]} {_ENCODED_GIT_PUSH[8:]}'"], "git push"),
+        (["Start-Process", "git", "-ArgumentList", "'push'"], "git push"),
+        (
+            ["Start-Process", "-FilePath", "git", "-ArgumentList", "push,origin", "-Wait"],
+            "git push origin",
+        ),
+        (["saps", "git", "-WorkingDirectory", "C:/repo", "-ArgumentList", "push"], "git push"),
+        (["Start-Process", "-FilePath:git", "-ArgumentList:'push'"], "git push"),
+        (["Start-Process", "git", "-WorkingDirectory:C:/repo", "-ArgumentList:push"], "git push"),
+        (["find", ".", "-name", "x"], None),
+        (["git", "push"], None),
+    ],
+)
+def test_should_return_the_command_an_evaluating_program_runs(
+    all_segment_tokens: list[str], expected_inner_command: str | None
+) -> None:
+    assert (
+        shell_command_wrappers.evaluated_inner_command(all_segment_tokens) == expected_inner_command
+    )
+
+
+def test_should_unwrap_an_evaluated_command_in_turn() -> None:
+    assert "git push" in shell_command_wrappers.all_wrapped_command_texts('eval "git push"')
+
+
+def test_should_read_a_quoted_value_that_spans_lines() -> None:
+    command = f'pwsh -EncodedCommand "{_ENCODED_GIT_PUSH[:8]}\n{_ENCODED_GIT_PUSH[8:]}"'
+    assert "git push" in shell_command_wrappers.all_wrapped_command_texts(command)
+
+
+def test_should_stop_unwrapping_past_the_depth_limit_without_error() -> None:
+    nesting_depth = 1000
+    command = "echo " + "$(" * nesting_depth + "git push" + ")" * nesting_depth
+    all_command_texts = shell_command_wrappers.all_wrapped_command_texts(command)
+    assert all_command_texts[0] == command
+    assert len(all_command_texts) <= nesting_depth
+
+
+def test_should_parse_a_repeated_inner_command_once() -> None:
+    all_command_texts = shell_command_wrappers.all_wrapped_command_texts(
+        'bash -c "git push"; bash -c "git push"'
+    )
+    assert all_command_texts.count("git push") == 1

package/hooks/test_conftest.py

@@ -9,7 +9,7 @@ import sys
 from hooks_constants.harness_scratchpad_constants import (
     CLAUDE_SESSION_ID_ENVIRONMENT_VARIABLE_NAME,
 )
-from hooks_constants.headless_claude_broker_gate_constants import CLOUD_SESSION_ENV_VAR
+from hooks_constants.cloud_session_constants import CLOUD_SESSION_ENV_VAR
 
 
 def test_live_session_id_is_absent_inside_each_test() -> None:

package/package.json

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

package/scripts/account_broker_support.py

@@ -43,9 +43,6 @@ from dev_env_scripts_constants.account_broker_constants import (
     JobOutcome,
     LOGIN_REFRESH_TIMEOUT_SECONDS,
     METER_READ_ATTEMPTS,
-    METER_READ_DELAY_FACTOR,
-    METER_READ_FIRST_DELAY_SECONDS,
-    METER_READ_MAX_DELAY_SECONDS,
     Meters,
     Product,
     ProductAdapter,
@@ -54,6 +51,7 @@ from dev_env_scripts_constants.account_broker_constants import (
     REPORT_INDENT_SPACES,
     SubprocessRunner,
     codex_usage_limit_signatures,
+    meter_read_delay_seconds,
     parse_utc_time,
     utc_time_text,
 )
@@ -70,7 +68,6 @@ from dev_env_scripts_constants.codex_account_constants import (
     CODEX_ACCOUNT_LAUNCHERS_FILE_NAME,
     CODEX_ACCOUNT_PROFILES_ENVIRONMENT_VARIABLE,
     CODEX_HOME_ENVIRONMENT_VARIABLE,
-    WEEKLY_WINDOW_MINUTES,
 )
 from dev_env_scripts_constants.shared_tree_constants import CLAUDE_CONFIG_DIR_ENV_VAR
 from shared_tree_paths import resolve_shared_process_tree_scripts_directory
@@ -303,14 +300,13 @@ def read_codex_account_meters(account: Account) -> Meters:
 
     Raises:
         CodexMeterUnreadError: The meter read failed.
-        OSError: No Codex executable was found.
+        CodexExecutableNotFoundError: No Codex executable was found, so
+            read_meters_with_backoff stops without a retry.
     """
     codex_path = codex_account_meters.resolve_codex_path(None)
     usage = codex_account_meters.read_codex_meters(codex_path, account.home)
-    weekly = [window for window in usage.all_windows if window.duration_minutes is None or window.duration_minutes >= WEEKLY_WINDOW_MINUTES]
-    short = [window for window in usage.all_windows if window.duration_minutes is not None and window.duration_minutes < WEEKLY_WINDOW_MINUTES]
-    weekly_window = max(weekly, key=lambda window: window.used_percent) if weekly else None
-    short_window = max(short, key=lambda window: window.used_percent) if short else None
+    short_window = usage.short_window
+    weekly_window = usage.weekly_window
     return Meters(
         usage.short_window_percent_left,
         short_window.resets_at if short_window else None,
@@ -328,14 +324,17 @@ def read_meters_with_backoff(read_meters: Callable[[Account], Meters | None], ac
 
     Returns:
         The meters from the first read that succeeds, or None with the last
-        failure text once every attempt failed.
+        failure text once every attempt failed. A missing Codex executable
+        fails at once, without a retry.
     """
     unread_reason = None
     for each_attempt in range(METER_READ_ATTEMPTS):
         if each_attempt:
-            time.sleep(min(METER_READ_FIRST_DELAY_SECONDS * METER_READ_DELAY_FACTOR ** (each_attempt - 1), METER_READ_MAX_DELAY_SECONDS))
+            time.sleep(meter_read_delay_seconds(each_attempt))
         try:
             return read_meters(account), None
+        except codex_account_meters.CodexExecutableNotFoundError as error:
+            return None, str(error)
         except (
             codex_account_meters.CodexMeterUnreadError,
             WeeklyUtilizationProbeError,

package/scripts/codex_account_meters.py

@@ -3,14 +3,17 @@
 
 Codex reports usage through ``codex app-server`` and the JSON-RPC method
 ``account/rateLimits/read``. The reply names up to two windows, a short one
-(5 hours) and a weekly one. The account's room is the smaller of the two::
+(5 hours) and a weekly one. The account broker counts the account's room as
+the smaller of the two::
 
     5-hour window 30% used, week 85% used  -> 15% left
     week window only, 40% used             -> 60% left
     no window, error reply, no reply       -> CodexMeterUnreadError
 
-Every failure raises ``CodexMeterUnreadError``. The caller decides what an
-unread account means; this module never guesses a number.
+Every read failure raises ``CodexMeterUnreadError``. A missing Codex
+executable raises ``CodexExecutableNotFoundError`` from ``resolve_codex_path``.
+The caller decides what an unread account means; this module never guesses a
+number.
 """
 
 from __future__ import annotations
@@ -69,6 +72,10 @@ class CodexMeterUnreadError(Exception):
     """Raised when one account's rate-limit windows cannot be read."""
 
 
+class CodexExecutableNotFoundError(FileNotFoundError):
+    """Raised when no Codex executable is on PATH or at its install path."""
+
+
 @dataclass(frozen=True)
 class UsageWindow:
     """One rate-limit window: its length, the percent used, and when it resets."""
@@ -77,56 +84,36 @@ class UsageWindow:
     used_percent: float
     resets_at: datetime | None
 
+    @property
+    def is_short(self) -> bool:
+        """Whether the window reports a length shorter than a week. A window with no length counts as weekly."""
+        return self.duration_minutes is not None and self.duration_minutes < WEEKLY_WINDOW_MINUTES
+
 
 @dataclass(frozen=True)
 class CodexAccountMeters:
-    """One account's windows, with percent_left, short_window_percent_left and resets_before_room."""
+    """One account's windows, with its tightest short window and its tightest weekly window."""
 
     all_windows: tuple[UsageWindow, ...]
 
     @property
-    def percent_left(self) -> float:
-        """Room left in the tightest window, from 0 to 100."""
-        most_used = max(each_window.used_percent for each_window in self.all_windows)
-        return max(0.0, FULL_PERCENT - most_used)
+    def short_window(self) -> UsageWindow | None:
+        """The most used window shorter than a week, or None when the account has none."""
+        all_short_windows = [each_window for each_window in self.all_windows if each_window.is_short]
+        return max(all_short_windows, key=lambda each_window: each_window.used_percent, default=None)
+
+    @property
+    def weekly_window(self) -> UsageWindow | None:
+        """The most used window of a week or of no reported length, or None when the account has none."""
+        all_weekly_windows = [each_window for each_window in self.all_windows if not each_window.is_short]
+        return max(all_weekly_windows, key=lambda each_window: each_window.used_percent, default=None)
 
     @property
     def short_window_percent_left(self) -> float | None:
         """Room left in the windows shorter than a week, or None when the account has none."""
-        all_short_used = [
-            each_window.used_percent
-            for each_window in self.all_windows
-            if each_window.duration_minutes is not None
-            and each_window.duration_minutes < WEEKLY_WINDOW_MINUTES
-        ]
-        if not all_short_used:
-            return None
-        return max(0.0, FULL_PERCENT - max(all_short_used))
-
-    def resets_before_room(self, minimum_percent_left: float) -> datetime | None:
-        """When every window that holds the account at or under a bar has reset.
-
-        Args:
-            minimum_percent_left: The percent left the account must pass.
-
-        Returns:
-            The latest reset among the blocking windows, or None when one
-            carries no reset time or none blocks.
-        """
-        all_blocking = [
-            each_window
-            for each_window in self.all_windows
-            if FULL_PERCENT - each_window.used_percent <= minimum_percent_left
-        ]
-        if not all_blocking or any(
-            each_window.resets_at is None for each_window in all_blocking
-        ):
+        if self.short_window is None:
             return None
-        return max(
-            each_window.resets_at
-            for each_window in all_blocking
-            if each_window.resets_at is not None
-        )
+        return FULL_PERCENT - self.short_window.used_percent
 
 
 def _finite_number(raw_number: object) -> float | None:
@@ -396,7 +383,7 @@ def resolve_codex_path(explicit_path: Path | None) -> Path:
         The named path, else ``codex`` on PATH, else a known install path.
 
     Raises:
-        FileNotFoundError: No Codex executable was found.
+        CodexExecutableNotFoundError: No Codex executable was found.
     """
     if explicit_path is not None:
         return explicit_path
@@ -407,4 +394,4 @@ def resolve_codex_path(explicit_path: Path | None) -> Path:
         candidate = Path.home().joinpath(*each_parts)
         if candidate.is_file():
             return candidate
-    raise FileNotFoundError("no codex executable on PATH or at its install path")
+    raise CodexExecutableNotFoundError("no codex executable on PATH or at its install path")

package/scripts/dev_env_scripts_constants/account_broker_constants.py

@@ -112,6 +112,11 @@ def codex_usage_limit_signatures() -> tuple[str, ...]:
     return module.ALL_USAGE_LIMIT_MARKERS
 
 
+def meter_read_delay_seconds(attempt_index: int) -> float:
+    """Seconds to wait before a meter read retry, where the first retry has index 1."""
+    return min(METER_READ_FIRST_DELAY_SECONDS * METER_READ_DELAY_FACTOR ** (attempt_index - 1), METER_READ_MAX_DELAY_SECONDS)
+
+
 def utc_time_text(moment: datetime | None) -> str | None:
     return moment.astimezone(timezone.utc).isoformat() if moment is not None else None
 
@@ -217,16 +222,26 @@ class ProductAdapter:
     usage_limit_signatures: tuple[str, ...]
 
 
+def _is_at_or_under(room: float | None, floor: float) -> bool:
+    return room is not None and room <= floor
+
+
+def _claude_blocking_flags(meters: Meters, is_main: bool) -> tuple[bool, bool]:
+    session_key, weekly_key = (
+        ("main_session_used_ceiling", "main_weekly_used_ceiling")
+        if is_main
+        else ("extra_session_used_ceiling", "extra_weekly_used_ceiling")
+    )
+    return (
+        _is_at_or_under(meters.session_percent_left, FULL_PERCENT - ALL_CLAUDE_FLOORS[session_key]),
+        _is_at_or_under(meters.weekly_percent_left, FULL_PERCENT - ALL_CLAUDE_FLOORS[weekly_key]),
+    )
+
+
 def _claude_extra_tier(meters: Meters | None) -> str | None:
     if meters is None or meters.tightest_percent_left is None:
         return None
-    if (
-        meters.weekly_percent_left is not None
-        and meters.weekly_percent_left <= FULL_PERCENT - ALL_CLAUDE_FLOORS["extra_weekly_used_ceiling"]
-    ) or (
-        meters.session_percent_left is not None
-        and meters.session_percent_left <= FULL_PERCENT - ALL_CLAUDE_FLOORS["extra_session_used_ceiling"]
-    ):
+    if any(_claude_blocking_flags(meters, is_main=False)):
         return None
     return "normal"
 
@@ -253,24 +268,19 @@ def _account_reset(reading: Reading, is_spent: bool = False) -> datetime | None:
         return None
     if is_spent:
         return min((reset for reset in (meters.session_resets_at, meters.weekly_resets_at) if reset is not None), default=None)
-    is_claude_main = reading.account.product is Product.CLAUDE and reading.account.is_main
-    if is_claude_main:
-        blocking = (
-            (meters.session_percent_left, FULL_PERCENT - ALL_CLAUDE_FLOORS["main_session_used_ceiling"], meters.session_resets_at),
-            (meters.weekly_percent_left, FULL_PERCENT - ALL_CLAUDE_FLOORS["main_weekly_used_ceiling"], meters.weekly_resets_at),
-        )
-    elif reading.account.product is Product.CLAUDE:
-        blocking = (
-            (meters.session_percent_left, FULL_PERCENT - ALL_CLAUDE_FLOORS["extra_session_used_ceiling"], meters.session_resets_at),
-            (meters.weekly_percent_left, FULL_PERCENT - ALL_CLAUDE_FLOORS["extra_weekly_used_ceiling"], meters.weekly_resets_at),
-        )
+    if reading.account.product is Product.CLAUDE:
+        all_blocking_flags = _claude_blocking_flags(meters, reading.account.is_main)
     else:
-        blocking = (
-            (meters.session_percent_left, ALL_CODEX_FLOORS["luna_short_minimum_left"], meters.session_resets_at),
-            (meters.weekly_percent_left, ALL_CODEX_FLOORS["luna_stop_left"], meters.weekly_resets_at),
+        all_blocking_flags = (
+            meters.session_percent_left is not None and meters.session_percent_left < ALL_CODEX_FLOORS["luna_short_minimum_left"],
+            _is_at_or_under(meters.weekly_percent_left, ALL_CODEX_FLOORS["luna_stop_left"]),
         )
-    all_blocking_resets = [reset for room, floor, reset in blocking if room is not None and room <= floor and reset is not None]
-    return max(all_blocking_resets, default=None)
+    all_resets = (meters.session_resets_at, meters.weekly_resets_at)
+    all_blocking_resets = [reset for is_blocking, reset in zip(all_blocking_flags, all_resets) if is_blocking]
+    all_known_resets = [reset for reset in all_blocking_resets if reset is not None]
+    if len(all_known_resets) < len(all_blocking_resets):
+        return None
+    return max(all_known_resets, default=None)
 
 
 def _rank_key(reading: Reading) -> tuple[bool, int, float]:
@@ -284,8 +294,7 @@ def _main_has_room(meters: Meters | None) -> bool:
         meters is not None
         and meters.session_percent_left is not None
         and meters.weekly_percent_left is not None
-        and meters.session_percent_left > FULL_PERCENT - ALL_CLAUDE_FLOORS["main_session_used_ceiling"]
-        and meters.weekly_percent_left > FULL_PERCENT - ALL_CLAUDE_FLOORS["main_weekly_used_ceiling"]
+        and not any(_claude_blocking_flags(meters, is_main=True))
     )
 
 

package/scripts/dev_env_scripts_constants/claude_account_constants.py

@@ -181,15 +181,6 @@ REASON_ALL_EXTRAS_WAIT_TEMPLATE: str = (
 )
 """Reason when every configured extra profile is blocked."""
 
-REASON_WAIT_TEMPLATE: str = (
-    "second account is at {weekly_used_percent:.0f}% of its week"
-    " and {session_used_percent:.0f}% of its 5-hour window; next reset {next_reset}"
-)
-"""Reason when neither account has room."""
-
-UNKNOWN_RESET_TEXT: str = "unknown"
-"""Reset text when the blocking meter carries no reset time."""
-
 JSON_ACCOUNT_KEY: str = "account"
 """Picker JSON key naming the chosen account."""
 

package/scripts/dev_env_scripts_constants/codex_account_constants.py

@@ -174,26 +174,8 @@ EXIT_CODE_ROOM: int = 0
 EXIT_CODE_NO_ROOM: int = 3
 """Check answer: the account is at or below the floor, or its meter is unread."""
 
-REASON_NORMAL_TEMPLATE: str = "{account} has {percent_left:.0f}% left"
-"""Reason when an account takes the job at its normal model."""
-
-REASON_LUNA_TEMPLATE: str = (
-    "every account is at or under {bar:.0f}% left; {account} has"
-    " {percent_left:.0f}% and runs Luna until {stop:.0f}%"
-)
-"""Reason when the job falls back to Luna."""
-
-REASON_WAIT_TEMPLATE: str = "no account has room; {account} resets first, at {reset}"
-"""Reason when every account is out of room."""
-
-REASON_WAIT_UNREAD: str = "no account meter could be read"
-"""Reason when no account's meter reads at all."""
-
 UNREAD_NOT_SIGNED_IN: str = "not signed in"
 """Unread reason when the account's Codex home holds no sign-in."""
 
-UNKNOWN_RESET_TEXT: str = "an unknown time"
-"""Reset text when no blocking window carries a reset time."""
-
 TEXT_ENCODING: str = "utf-8"
 """Encoding for the server pipes and the JSON reports."""

package/scripts/dev_env_scripts_constants/test_account_broker_constants.py

@@ -189,3 +189,45 @@ def test_should_treat_accounts_that_differ_only_in_profile_as_one_account() -> N
     home = Path("/profiles/first")
 
     assert Account(Product.CLAUDE, "first", home, profile="first") == Account(Product.CLAUDE, "first", home)
+
+
+def _codex_reading(meters: broker_constants.Meters) -> broker_constants.Reading:
+    return broker_constants.Reading(Account(Product.CODEX, "codex-1", Path("/profiles/codex-1")), meters)
+
+
+def test_should_let_a_codex_account_at_the_short_window_floor_take_luna() -> None:
+    weekly_reset = datetime(2026, 10, 4, tzinfo=timezone.utc)
+    session_reset = weekly_reset + timedelta(hours=4)
+    meters = broker_constants.Meters(
+        LUNA_TIER_SHORT_WINDOW_MINIMUM_PERCENT_LEFT, session_reset, LUNA_TIER_STOP_PERCENT_LEFT / 2, weekly_reset
+    )
+
+    assert broker_constants._codex_tier(
+        dataclasses.replace(meters, weekly_percent_left=NORMAL_TIER_MINIMUM_PERCENT_LEFT)
+    ) == "luna"
+    assert broker_constants._account_reset(_codex_reading(meters)) == weekly_reset
+
+
+def test_should_name_no_codex_reset_when_a_blocking_window_has_none() -> None:
+    session_reset = datetime(2026, 10, 3, 2, tzinfo=timezone.utc)
+    meters = broker_constants.Meters(
+        LUNA_TIER_SHORT_WINDOW_MINIMUM_PERCENT_LEFT / 2, session_reset, LUNA_TIER_STOP_PERCENT_LEFT / 2, None
+    )
+
+    assert broker_constants._account_reset(_codex_reading(meters)) is None
+
+
+def test_should_name_the_latest_codex_reset_when_every_blocking_window_has_one() -> None:
+    session_reset = datetime(2026, 10, 3, 2, tzinfo=timezone.utc)
+    weekly_reset = datetime(2026, 10, 4, tzinfo=timezone.utc)
+    meters = broker_constants.Meters(
+        LUNA_TIER_SHORT_WINDOW_MINIMUM_PERCENT_LEFT / 2, session_reset, LUNA_TIER_STOP_PERCENT_LEFT / 2, weekly_reset
+    )
+
+    assert broker_constants._account_reset(_codex_reading(meters)) == weekly_reset
+
+
+def test_should_double_the_meter_read_delay_up_to_its_cap() -> None:
+    all_delays = [broker_constants.meter_read_delay_seconds(each_attempt) for each_attempt in range(1, 6)]
+
+    assert all_delays == [1.0, 2.0, 4.0, 8.0, 8.0]

package/scripts/dev_env_scripts_constants/test_codex_account_constants.py

@@ -0,0 +1,119 @@
+"""The Codex account constants match what docs/codex-accounts.md tells the reader."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from dev_env_scripts_constants import codex_account_constants as constants
+from dev_env_scripts_constants.account_broker_constants import METER_READ_ATTEMPTS, meter_read_delay_seconds
+from dev_env_scripts_constants.claude_account_constants import ALL_LAUNCHER_DIRECTORY_RELATIVE_PARTS
+
+CODEX_ACCOUNTS_DOC_PATH = Path(__file__).resolve().parents[2] / "docs" / "codex-accounts.md"
+SECTION_HEADING_PREFIX = "## "
+CHOOSE_COMMAND_SUFFIX = "choose --product codex"
+CODE_FENCE = "```"
+
+
+def documented_section_lines(heading: str) -> list[str]:
+    all_doc_lines = CODEX_ACCOUNTS_DOC_PATH.read_text(encoding="utf-8").splitlines()
+    heading_index = all_doc_lines.index(SECTION_HEADING_PREFIX + heading)
+    all_section_lines: list[str] = []
+    for each_line in all_doc_lines[heading_index + 1 :]:
+        if each_line.startswith(SECTION_HEADING_PREFIX):
+            break
+        all_section_lines.append(each_line)
+    return all_section_lines
+
+
+def documented_section(heading: str) -> str:
+    return " ".join(" ".join(documented_section_lines(heading)).split())
+
+
+def documented_choose_sample() -> dict[str, Any]:
+    all_section_lines = documented_section_lines("Which account a job uses")
+    command_index = next(
+        index for index, each_line in enumerate(all_section_lines) if each_line.endswith(CHOOSE_COMMAND_SUFFIX)
+    )
+    fence_index = all_section_lines.index(CODE_FENCE, command_index)
+    return json.loads("\n".join(all_section_lines[command_index + 1 : fence_index]))
+
+
+def documented_list(all_names: list[str]) -> str:
+    *all_leading_names, last_name = [f"`{each_name}`" for each_name in all_names]
+    if not all_leading_names:
+        return last_name
+    return ", ".join(all_leading_names) + f" and {last_name}"
+
+
+def documented_percent(percent: float) -> str:
+    return f"{percent:g}%"
+
+
+def test_fallback_roster_matches_the_documented_accounts() -> None:
+    expected_sentence = (
+        "When neither exists, the accounts are "
+        + documented_list(list(constants.ALL_CODEX_ACCOUNT_NAMES))
+        + "."
+    )
+    assert expected_sentence in documented_section("Names and order")
+
+
+def test_shared_home_entries_match_the_documented_list() -> None:
+    expected_sentence = "They are " + documented_list(sorted(constants.ALL_SHARED_CODEX_HOME_NAMES)) + "."
+    assert expected_sentence in documented_section("Sign in once")
+
+
+def test_sign_in_file_stays_per_account() -> None:
+    expected_sentence = f"The sign-in lives in that folder's `{constants.CODEX_AUTH_FILE_NAME}`."
+    assert expected_sentence in documented_section("Sign in once")
+    assert constants.CODEX_AUTH_FILE_NAME not in constants.ALL_SHARED_CODEX_HOME_NAMES
+
+
+def test_launcher_matches_the_documented_name_directory_and_variable() -> None:
+    launcher_file_name = constants.CODEX_LAUNCHER_PROGRAM.file_name_template.format(profile_name="<name>")
+    launcher_directory = "/".join(["~", *ALL_LAUNCHER_DIRECTORY_RELATIVE_PARTS])
+    expected_sentence = (
+        f"Each roster account gets a launcher, `{launcher_file_name}`, in `{launcher_directory}`. "
+        f"It sets `{constants.CODEX_LAUNCHER_PROGRAM.environment_variable}` to that account's home "
+        f"and runs Codex with every argument"
+    )
+    assert expected_sentence in documented_section("Named launchers")
+
+
+def test_tier_bars_match_the_documented_table() -> None:
+    normal_bar = documented_percent(constants.NORMAL_TIER_MINIMUM_PERCENT_LEFT)
+    luna_stop = documented_percent(constants.LUNA_TIER_STOP_PERCENT_LEFT)
+    luna_short_window_floor = documented_percent(constants.LUNA_TIER_SHORT_WINDOW_MINIMUM_PERCENT_LEFT)
+    all_expected_rows = [
+        f"| One or more accounts with more than {normal_bar} left | `{constants.TIER_NORMAL}` on the account with the most room |",
+        f"| No account over {normal_bar}, one or more over {luna_stop} | `{constants.TIER_LUNA}` on the account with the most room |",
+        f"| An account that reports a window shorter than a week, such as the 5-hour window, with under {luna_short_window_floor} of that window left | never takes `{constants.TIER_LUNA}` |",
+        f"| No account over {luna_stop} | `{constants.TIER_WAIT}`, naming the next reset when known |",
+    ]
+    section_text = documented_section("Which account a job uses")
+    for each_row in all_expected_rows:
+        assert each_row in section_text
+
+
+def test_meter_retries_match_the_documented_table() -> None:
+    all_delays = [meter_read_delay_seconds(each_attempt) for each_attempt in range(1, METER_READ_ATTEMPTS)]
+    all_delay_texts = [f"{each_delay:g} second" + ("" if each_delay == 1 else "s") for each_delay in all_delays]
+    expected_row = (
+        f"| A meter read fails | The broker reads it again, up to {METER_READ_ATTEMPTS} reads, "
+        f"waiting {' and then '.join(all_delay_texts)} |"
+    )
+    assert expected_row in documented_section("Which account a job uses")
+
+
+def test_documented_choose_sample_runs_normal_on_the_tightest_window() -> None:
+    sample = documented_choose_sample()
+    decision = sample["decision"]
+    chosen_meters = next(
+        each_account["meters"] for each_account in sample["accounts"] if each_account["name"] == decision["account"]
+    )
+    room = min(chosen_meters["session_percent_left"], chosen_meters["weekly_percent_left"])
+    assert decision["tier"] == constants.TIER_NORMAL
+    assert room > constants.NORMAL_TIER_MINIMUM_PERCENT_LEFT
+    assert decision["reason"] == f"{decision['account']} has {room:g}% left"