claude-dev-env 8.75.2 → 8.75.4

package/hooks/hooks_constants/test_artifact_template_pointer_constants.py

@@ -1,16 +1,23 @@
 """Behavioral tests for the artifact template pointer's path."""
 
-from hooks_constants.artifact_template_pointer_constants import (
-    ARTIFACT_TEMPLATE_PATH,
-    HTML_PLAN_TEMPLATE_README_PATH,
-)
+from hooks_constants import artifact_template_pointer_constants
 
 
 def test_template_path_names_the_packaged_template_file() -> None:
-    assert ARTIFACT_TEMPLATE_PATH.is_file()
-    assert ARTIFACT_TEMPLATE_PATH.parent.joinpath("README.md").is_file()
+    assert artifact_template_pointer_constants.ARTIFACT_TEMPLATE_PATH.is_file()
+    assert artifact_template_pointer_constants.ARTIFACT_TEMPLATE_PATH.parent.joinpath("README.md").is_file()
 
 
 def test_html_plan_readme_path_names_the_packaged_readme_and_house_stylesheet() -> None:
-    assert HTML_PLAN_TEMPLATE_README_PATH.is_file()
-    assert HTML_PLAN_TEMPLATE_README_PATH.parent.joinpath("house.css").is_file()
+    assert artifact_template_pointer_constants.HTML_PLAN_TEMPLATE_README_PATH.is_file()
+    assert artifact_template_pointer_constants.HTML_PLAN_TEMPLATE_README_PATH.parent.joinpath("house.css").is_file()
+
+
+def test_every_exported_name_resolves_to_a_module_attribute() -> None:
+    all_missing_names = [
+        each_name
+        for each_name in artifact_template_pointer_constants.__all__
+        if not hasattr(artifact_template_pointer_constants, each_name)
+    ]
+
+    assert all_missing_names == []

package/hooks/hooks_constants/test_image_read_size_gate_constants.py

@@ -0,0 +1,61 @@
+"""Behavioral tests for the image_read_size_gate header offsets and refusal text."""
+
+from __future__ import annotations
+
+import struct
+
+from image_read_size_gate import image_size
+
+from hooks_constants.image_read_size_gate_constants import (
+    AGENT_COPY_SCRIPT_PATH,
+    ALL_GIF_SIGNATURES,
+    JPEG_MARKER_PREFIX,
+    JPEG_SIGNATURE,
+    MAXIMUM_LONG_EDGE_PIXELS,
+    OVERSIZED_IMAGE_REASON_TEMPLATE,
+    PNG_SIGNATURE,
+)
+
+BASELINE_FRAME_MARKER = 0xC0
+SAMPLE_PRECISION = 8
+
+
+def test_png_offsets_read_the_width_and_height_from_the_ihdr_chunk() -> None:
+    ihdr_length = struct.pack(">I", 13)
+    png_header = PNG_SIGNATURE + ihdr_length + b"IHDR" + struct.pack(">II", 1440, 2560)
+
+    assert image_size(png_header) == (1440, 2560)
+
+
+def test_gif_offsets_read_the_little_endian_logical_screen_size() -> None:
+    for each_signature in ALL_GIF_SIGNATURES:
+        gif_header = each_signature + struct.pack("<HH", 640, 480)
+
+        assert image_size(gif_header) == (640, 480)
+
+
+def test_jpeg_frame_offsets_read_height_then_width_from_a_baseline_frame() -> None:
+    frame_segment = bytes([JPEG_MARKER_PREFIX, BASELINE_FRAME_MARKER]) + struct.pack(
+        ">HBHH", 17, SAMPLE_PRECISION, 2560, 1440
+    )
+
+    assert image_size(JPEG_SIGNATURE + frame_segment) == (1440, 2560)
+
+
+def test_agent_copy_script_path_names_the_packaged_script() -> None:
+    assert AGENT_COPY_SCRIPT_PATH.is_file()
+    assert AGENT_COPY_SCRIPT_PATH.name == "agent_image_copy.py"
+
+
+def test_reason_template_names_the_size_the_cap_and_the_copy_command() -> None:
+    reason = OVERSIZED_IMAGE_REASON_TEMPLATE.format(
+        width=1500,
+        height=2700,
+        maximum_edge=MAXIMUM_LONG_EDGE_PIXELS,
+        script_path=AGENT_COPY_SCRIPT_PATH,
+        image_path="/tmp/shot.png",
+    )
+
+    assert "1500x2700" in reason
+    assert f"{MAXIMUM_LONG_EDGE_PIXELS} pixels" in reason
+    assert f'python3 "{AGENT_COPY_SCRIPT_PATH}" "/tmp/shot.png"' in reason

package/hooks/hooks_constants/test_post_tool_use_context.py

@@ -3,10 +3,12 @@
 from __future__ import annotations
 
 import json
+from unittest.mock import patch
 
 import pytest
 
 from hooks_constants.post_tool_use_context import write_post_tool_use_context_to_stdout
+from hooks_constants.test_stdout_flush_support import FlushRecordingStream
 
 
 def test_should_write_the_post_tool_use_payload_carrying_the_context_text(
@@ -20,3 +22,14 @@ def test_should_write_the_post_tool_use_payload_carrying_the_context_text(
             "additionalContext": "=== PR DONE CHECKLIST ===",
         }
     }
+
+
+def test_should_flush_the_whole_payload_so_the_dispatcher_reads_it_before_exit() -> None:
+    recording_stream = FlushRecordingStream()
+    with patch("sys.stdout", recording_stream):
+        write_post_tool_use_context_to_stdout('line one\nline "two"')
+
+    assert recording_stream.flushed_text
+    assert json.loads(recording_stream.flushed_text[-1])["hookSpecificOutput"]["additionalContext"] == (
+        'line one\nline "two"'
+    )

package/hooks/hooks_constants/test_pre_tool_use_allow_output.py

@@ -7,6 +7,7 @@ from io import StringIO
 from unittest.mock import patch
 
 from hooks_constants.pre_tool_use_allow_output import write_pre_tool_use_allow_to_stdout
+from hooks_constants.test_stdout_flush_support import FlushRecordingStream
 
 
 def _emitted_payload(updated_tool_input: dict[str, object]) -> dict[str, object]:
@@ -25,3 +26,13 @@ def test_emitter_writes_an_allow_decision_carrying_the_updated_input() -> None:
             "updatedInput": {"command": "git status", "description": "check"},
         }
     }
+
+
+def test_emitter_flushes_the_whole_payload_with_nested_input_intact() -> None:
+    nested_input = {"command": "echo hi", "options": {"timeout": 5, "flags": ["-n"]}}
+    recording_stream = FlushRecordingStream()
+    with patch("sys.stdout", recording_stream):
+        write_pre_tool_use_allow_to_stdout(nested_input)
+
+    assert recording_stream.flushed_text
+    assert json.loads(recording_stream.flushed_text[-1])["hookSpecificOutput"]["updatedInput"] == nested_input

package/hooks/hooks_constants/test_stdout_flush_support.py

@@ -0,0 +1,17 @@
+"""Shared stdout stand-in for hook emitter tests that check flush behavior."""
+
+from __future__ import annotations
+
+from io import StringIO
+
+
+class FlushRecordingStream(StringIO):
+    """StringIO that records the full buffer text at each flush call."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.flushed_text: list[str] = []
+
+    def flush(self) -> None:
+        self.flushed_text.append(self.getvalue())
+        super().flush()

package/hooks/hooks_constants/test_visual_reply_rules_constants.py

@@ -1,3 +1,6 @@
+import json
+import re
+
 from hooks_constants import visual_reply_rules_constants as constants
 
 
@@ -13,3 +16,28 @@ def test_tracker_number_pattern_reads_items_issues_and_cards() -> None:
     assert [
         each.group(0) for each in constants.TRACKER_NUMBER_PATTERN.finditer("issue 5735, item #6, card 2")
     ] == ["issue 5735", "item #6", "card 2"]
+
+
+def test_rule_key_constants_name_rules_in_the_shipped_rule_list() -> None:
+    rules_document = json.loads(constants.RULES_FILE_PATH.read_text(encoding=constants.RULES_FILE_ENCODING))
+    all_shipped_keys = {each_rule[constants.RULE_KEY_FIELD] for each_rule in rules_document[constants.RULES_LIST_KEY]}
+
+    assert {
+        constants.NO_PICTURE_RULE_KEY,
+        constants.ABBREVIATIONS_RULE_KEY,
+        constants.ONE_ITEM_RULE_KEY,
+    } <= all_shipped_keys
+    assert constants.ALLOWED_CAPITALIZED_WORDS_KEY in rules_document
+    assert constants.LOWERCASE_ABBREVIATIONS_KEY in rules_document
+
+
+def test_lowercase_abbreviation_template_matches_the_word_on_its_own_only() -> None:
+    pattern = re.compile(constants.LOWERCASE_ABBREVIATION_TEMPLATE.format(abbreviation=re.escape("repo")))
+
+    assert pattern.findall("the repo, my repos, a repo2 tag") == ["repo"]
+
+
+def test_widget_anchor_pattern_matches_a_link_and_skips_other_tags() -> None:
+    assert constants.WIDGET_ANCHOR_PATTERN.search('<A class="x" HREF="https://example.com">')
+    assert constants.WIDGET_ANCHOR_PATTERN.search('<abbr title="a">') is None
+    assert constants.WIDGET_ANCHOR_PATTERN.search("<a>no link</a>") is None

package/package.json

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

package/scripts/account_broker_support.py

@@ -12,6 +12,7 @@ import subprocess
 import sys
 import tempfile
 import threading
+import time
 from contextlib import contextmanager
 from datetime import datetime, timezone
 from pathlib import Path, PureWindowsPath
@@ -28,15 +29,23 @@ from claude_account_profile import default_profile_home, validate_profile_name
 from claude_chain_usage import WeeklyUtilizationProbeError, probe_account_meters
 from dev_env_scripts_constants.account_broker_constants import (
     ALL_BATCH_FILE_EXTENSIONS,
+    ALL_CLAUDE_BINARY_CANDIDATE_RELATIVE_PARTS,
+    ALL_LOGIN_REFRESH_ARGUMENTS,
     BROKER_STATE_DIRECTORY_NAME,
     BROKER_STATE_FILE_NAME,
     BROKER_STATE_LOCK_SUFFIX,
     BROKER_STATE_TEMP_SUFFIX,
     Account,
     BrokerConfigurationError,
+    CLAUDE_BINARY_NAME,
     CMD_SHELL_METACHARACTERS,
     Decision,
     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,
@@ -203,6 +212,54 @@ def load_codex_accounts() -> tuple[Account, ...]:
     return tuple(Account(Product.CODEX, name, (profiles_root / name).resolve()) for name in names)
 
 
+def resolve_claude_path() -> Path | None:
+    """Find the Claude Code CLI.
+
+    Returns:
+        ``claude`` on PATH, else a known install path, else None.
+    """
+    on_path = shutil.which(CLAUDE_BINARY_NAME)
+    if on_path is not None:
+        return Path(on_path)
+    for each_parts in ALL_CLAUDE_BINARY_CANDIDATE_RELATIVE_PARTS:
+        candidate = Path.home().joinpath(*each_parts)
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def refresh_claude_login(account_home: Path) -> bool:
+    """Run one small CLI call so the CLI refreshes an expired login.
+
+    ::
+
+        ev token expired  ->  claude -p ok, CLAUDE_CONFIG_DIR=<ev home>  ->  new token saved
+
+    The CLI saves a new access token before it sends the request.
+
+    Args:
+        account_home: The account's Claude config folder.
+
+    Returns:
+        True when the call ran, False when no CLI was found or the call could not start.
+    """
+    claude_path = resolve_claude_path()
+    if claude_path is None:
+        return False
+    refresh_environment = {**os.environ, CLAUDE_CONFIG_DIR_ENV_VAR: str(account_home)}
+    try:
+        subprocess.run(
+            [str(claude_path), *ALL_LOGIN_REFRESH_ARGUMENTS],
+            env=refresh_environment,
+            capture_output=True,
+            timeout=LOGIN_REFRESH_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return True
+
+
 def read_claude_meters(account: Account) -> Meters | None:
     """Probe one Claude account.
 
@@ -210,12 +267,13 @@ def read_claude_meters(account: Account) -> Meters | None:
         account: Account whose meter is read.
 
     Returns:
-        Its meters, or None when the probe fails.
+        Its meters.
+
+    Raises:
+        WeeklyUtilizationProbeError: The usage meters could not be measured.
+        OSError: The credentials file could not be read.
     """
-    try:
-        usage = probe_account_meters(account.home / CREDENTIALS_FILE_NAME)
-    except (WeeklyUtilizationProbeError, OSError):
-        return None
+    usage = probe_account_meters(account.home / CREDENTIALS_FILE_NAME, refresh_claude_login)
     return Meters(
         FULL_PERCENT - usage.session_utilization if usage.session_utilization is not None else None,
         usage.session_resets_at,
@@ -231,17 +289,14 @@ def read_codex_account_meters(account: Account) -> Meters:
         account: Account whose meter is read.
 
     Returns:
-        Its meters, read again once when the first read fails.
+        Its meters.
 
     Raises:
-        CodexMeterUnreadError: Both reads failed; the message is the second failure.
+        CodexMeterUnreadError: The meter read failed.
         OSError: No Codex executable was found.
     """
     codex_path = codex_account_meters.resolve_codex_path(None)
-    try:
-        usage = codex_account_meters.read_codex_meters(codex_path, account.home)
-    except codex_account_meters.CodexMeterUnreadError:
-        usage = codex_account_meters.read_codex_meters(codex_path, account.home)
+    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
@@ -254,6 +309,35 @@ def read_codex_account_meters(account: Account) -> Meters:
     )
 
 
+def read_meters_with_backoff(read_meters: Callable[[Account], Meters | None], account: Account) -> tuple[Meters | None, str | None]:
+    """Read one account's meters, retrying a failed read with exponential backoff.
+
+    Args:
+        read_meters: The product's meter reader.
+        account: Account whose meter is read.
+
+    Returns:
+        The meters from the first read that succeeds, or None with the last
+        failure text once every attempt failed.
+    """
+    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))
+        try:
+            return read_meters(account), None
+        except (
+            codex_account_meters.CodexMeterUnreadError,
+            WeeklyUtilizationProbeError,
+            OSError,
+            ValueError,
+            RuntimeError,
+            subprocess.SubprocessError,
+        ) as error:
+            unread_reason = str(error) or type(error).__name__
+    return None, unread_reason
+
+
 all_product_adapters = {
     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()),
@@ -409,12 +493,7 @@ def _read_one_account(account: Account, adapter: ProductAdapter, all_cache: dict
     if isinstance(cached, dict) and isinstance(cached.get("read_at"), (int, float)) and 0 <= now.timestamp() - cached["read_at"] < 60:
         cached_reason = cached.get("unread_reason")
         return Reading(account, _meters_from_payload(cached.get("meters")), cached_reason if isinstance(cached_reason, str) else None), False
-    unread_reason = None
-    try:
-        meters = adapter.read_meters(account)
-    except (codex_account_meters.CodexMeterUnreadError, OSError, ValueError, RuntimeError, subprocess.SubprocessError) as error:
-        meters = None
-        unread_reason = str(error) or type(error).__name__
+    meters, unread_reason = read_meters_with_backoff(adapter.read_meters, account)
     all_cache[key] = {"read_at": now.timestamp(), "meters": _meter_payload(meters), "unread_reason": unread_reason}
     return Reading(account, meters, unread_reason), True
 

package/scripts/claude_chain_usage.py

@@ -10,6 +10,7 @@ from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
 from types import ModuleType
+from typing import Callable
 
 from dev_env_scripts_constants.claude_chain_usage_constants import (
     NO_ACCESS_TOKEN_ERROR_TEMPLATE,
@@ -111,13 +112,17 @@ class AccountUsageMeters:
 
 
 def _read_access_token(
-    usage_window_resolver: ModuleType, credentials_path: Path, now: datetime
+    usage_window_resolver: ModuleType,
+    credentials_path: Path,
+    now: datetime,
+    refresh_login: Callable[[Path], object] | None = None,
 ) -> str | None:
     """Return the bearer token that reads one account's meters.
 
     ::
 
         credential file holds a token                ->  that token
+        token expired, refresh_login saves a new one ->  the new token
         no token, the session's own credential path  ->  the session ingress token
         no token, another account's credential path  ->  None
 
@@ -128,6 +133,8 @@ def _read_access_token(
         usage_window_resolver: The loaded usage-pause resolver module.
         credentials_path: The account's CLI credential file.
         now: The current time, for the token expiry check.
+        refresh_login: Called with the account home when the stored token is
+            unusable, so a fresh token can be saved before one more read.
 
     Returns:
         A bearer token, or None when the account has none.
@@ -135,6 +142,11 @@ def _read_access_token(
     file_token = usage_window_resolver.read_oauth_access_token(credentials_path, now)
     if file_token is not None:
         return file_token
+    if refresh_login is not None and credentials_path.is_file():
+        refresh_login(credentials_path.parent)
+        refreshed_token = usage_window_resolver.read_oauth_access_token(credentials_path, datetime.now().astimezone())
+        if refreshed_token is not None:
+            return refreshed_token
     session_credentials_path = usage_window_resolver.default_credentials_path()
     if credentials_path.resolve() != session_credentials_path.resolve():
         return None
@@ -142,11 +154,13 @@ def _read_access_token(
 
 
 def _fetch_account_usage_payload(
-    usage_window_resolver: ModuleType, credentials_path: Path
+    usage_window_resolver: ModuleType,
+    credentials_path: Path,
+    refresh_login: Callable[[Path], object] | None,
 ) -> dict[str, object]:
     now = datetime.now().astimezone()
     try:
-        access_token = _read_access_token(usage_window_resolver, credentials_path, now)
+        access_token = _read_access_token(usage_window_resolver, credentials_path, now, refresh_login)
         if access_token is None:
             raise WeeklyUtilizationProbeError(
                 NO_ACCESS_TOKEN_ERROR_TEMPLATE.format(credentials_path=credentials_path)
@@ -166,10 +180,21 @@ def _fetch_account_usage_payload(
         ) from probe_error
 
 
-def probe_account_meters(credentials_path: Path) -> AccountUsageMeters:
-    """Read short and weekly usage meters for one account."""
+def probe_account_meters(
+    credentials_path: Path, refresh_login: Callable[[Path], object] | None = None
+) -> AccountUsageMeters:
+    """Read short and weekly usage meters for one account.
+
+    Args:
+        credentials_path: The account's CLI credential file.
+        refresh_login: Called with the account home when the stored token is
+            unusable, before one more token read.
+
+    Returns:
+        The account's meters.
+    """
     usage_window_resolver = _load_resolve_usage_window_module()
-    usage_payload = _fetch_account_usage_payload(usage_window_resolver, credentials_path)
+    usage_payload = _fetch_account_usage_payload(usage_window_resolver, credentials_path, refresh_login)
     usage_windows = usage_window_resolver.extract_usage_windows(usage_payload)
     return AccountUsageMeters(
         session_utilization=usage_windows.session_utilization,

package/scripts/dev_env_scripts_constants/account_broker_constants.py

@@ -48,6 +48,10 @@ ALL_CODEX_FLOORS = {
     "luna_short_minimum_left": LUNA_TIER_SHORT_WINDOW_MINIMUM_PERCENT_LEFT,
 }
 
+METER_READ_ATTEMPTS = 3
+METER_READ_FIRST_DELAY_SECONDS = 1.0
+METER_READ_DELAY_FACTOR = 2.0
+METER_READ_MAX_DELAY_SECONDS = 8.0
 WAIT_EXIT_CODE = 3
 COMMAND_MISSING_EXIT_CODE = 127
 TIMEOUT_EXIT_CODE = 124
@@ -58,6 +62,13 @@ BROKER_STATE_TEMP_SUFFIX = ".json"
 BROKER_STATE_LOCK_SUFFIX = ".lock"
 ALL_BATCH_FILE_EXTENSIONS = frozenset({".bat", ".cmd"})
 CMD_SHELL_METACHARACTERS = "&|<>^%!\"\r\n"
+CLAUDE_BINARY_NAME = "claude"
+ALL_CLAUDE_BINARY_CANDIDATE_RELATIVE_PARTS: tuple[tuple[str, ...], ...] = (
+    (".local", "bin", "claude.exe"),
+    (".local", "bin", "claude"),
+)
+ALL_LOGIN_REFRESH_ARGUMENTS: tuple[str, ...] = ("-p", "ok", "--model", "haiku")
+LOGIN_REFRESH_TIMEOUT_SECONDS = 120.0
 ALL_PARENT_CLAUDE_SESSION_VARIABLES: frozenset[str] = frozenset({
     "CLAUDE_CODE_SESSION_ID",
     "CLAUDE_CODE_REMOTE",

package/scripts/dev_env_scripts_constants/test_account_broker_constants.py

@@ -97,12 +97,22 @@ def test_parse_utc_time_rejects_values_without_a_timezone(timestamp: object) ->
     assert broker_constants.parse_utc_time(timestamp) is None
 
 
+def test_tightest_percent_left_should_take_the_lower_known_window() -> None:
+    reset = datetime(2026, 10, 3, tzinfo=timezone.utc)
+
+    assert broker_constants.Meters(30.0, reset, 70.0, reset).tightest_percent_left == 30.0
+    assert broker_constants.Meters(80.0, reset, 20.0, reset).tightest_percent_left == 20.0
+    assert broker_constants.Meters(None, None, 45.0, reset).tightest_percent_left == 45.0
+    assert broker_constants.Meters(None, None, None, None).tightest_percent_left is None
+
+
 def test_parse_utc_time_converts_an_offset_timestamp() -> None:
     parsed = broker_constants.parse_utc_time("2026-10-03T07:30:00-04:00")
 
     assert parsed is not None
     assert parsed.isoformat() == "2026-10-03T11:30:00+00:00"
 
+
 def _create_directory_link(*, from_link: Path, to_target: Path) -> None:
     if sys.platform.startswith("win32"):
         importlib.import_module("_winapi").CreateJunction(

package/scripts/test_account_broker.py

@@ -10,6 +10,7 @@ from pathlib import Path
 import pytest
 
 import account_broker
+import account_broker_support
 import claude_account_worker
 from account_broker import (
     Account,
@@ -75,7 +76,8 @@ def _adapter(accounts: tuple[Account, ...], meters: dict[str, Meters | None]) ->
     )
 
 
-def test_should_name_the_unread_account_and_its_reason_when_no_account_has_room() -> None:
+def test_should_name_the_unread_account_and_its_reason_when_no_account_has_room(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(account_broker_support.time, "sleep", lambda _: None)
     codex_3 = _account("codex-3")
     codex_4 = _account("codex-4")
 
@@ -1232,3 +1234,28 @@ def test_should_hand_the_live_log_to_the_subprocess_runner(tmp_path: Path, monke
 
     assert outcome.returncode == 0
     assert captured_options["live_log"] == live_log
+
+
+def test_decision_payload_should_name_the_chosen_account_and_its_home() -> None:
+    account = _account("codex-2")
+    decision = account_broker.Decision("run", account, None, "most room", "normal")
+
+    assert account_broker.decision_payload(decision) == {
+        "action": "run",
+        "account": "codex-2",
+        "home": str(Path("/profiles") / "codex-2"),
+        "reason": "most room",
+        "tier": "normal",
+        "resets_at": None,
+    }
+
+
+def test_decision_payload_should_leave_the_account_empty_and_give_the_reset_for_a_wait() -> None:
+    reset = datetime(2026, 10, 3, 4, 0, tzinfo=timezone(timedelta(hours=-4)))
+    decision = account_broker.Decision("wait", None, reset, "no account has room", "wait")
+
+    payload = account_broker.decision_payload(decision)
+
+    assert payload["account"] is None
+    assert payload["home"] is None
+    assert payload["resets_at"] == "2026-10-03T08:00:00+00:00"

package/scripts/test_account_broker_support.py

@@ -114,10 +114,13 @@ def test_should_read_claude_meters_through_injected_probe(
         weekly_utilization=30.0,
         weekly_resets_at=None,
     )
-    monkeypatch.setattr(support, "probe_account_meters", lambda _: usage)
+    all_refresh_helpers: list[object] = []
+    monkeypatch.setattr(support, "probe_account_meters", lambda _, refresh_login: all_refresh_helpers.append(refresh_login) or usage)
 
     meters = support.read_claude_meters(Account(Product.CLAUDE, "one", tmp_path))
 
+    assert all_refresh_helpers == [support.refresh_claude_login]
+
     assert meters.session_percent_left == 80.0
     assert meters.weekly_percent_left == 70.0
 
@@ -154,40 +157,113 @@ def _codex_meter_reads(
     return all_homes_read
 
 
-def test_should_read_codex_meters_again_after_one_failed_read(
+def _claude_meter_reads(monkeypatch: pytest.MonkeyPatch, all_outcomes: list[object]) -> list[Path]:
+    all_paths_read: list[Path] = []
+
+    def probe_account_meters(credentials_path: Path, refresh_login: object) -> object:
+        all_paths_read.append(credentials_path)
+        outcome = all_outcomes.pop(0)
+        if isinstance(outcome, Exception):
+            raise outcome
+        return outcome
+
+    monkeypatch.setattr(support, "probe_account_meters", probe_account_meters)
+    return all_paths_read
+
+
+def _recorded_sleeps(monkeypatch: pytest.MonkeyPatch) -> list[float]:
+    all_delays: list[float] = []
+    monkeypatch.setattr(support.time, "sleep", all_delays.append)
+    return all_delays
+
+
+def _first_reading(monkeypatch: pytest.MonkeyPatch, tmp_path: Path, account: Account, read_meters: object) -> object:
+    monkeypatch.setattr(support, "broker_state_path", lambda: tmp_path / "broker" / "state.json")
+    adapter = ProductAdapter(lambda: (account,), read_meters, "HOME", ())
+    state = support._load_state(support.broker_state_path())
+    now = datetime(2026, 10, 3, tzinfo=timezone.utc)
+    return support.read_accounts(account.product, adapter, all_state=state, now=now)[0], adapter, state, now
+
+
+def test_should_read_claude_meters_after_transient_failures_with_growing_delays(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    usage = SimpleNamespace(session_utilization=20.0, session_resets_at=None, weekly_utilization=30.0, weekly_resets_at=None)
+    unread = support.WeeklyUtilizationProbeError("usage endpoint timed out")
+    all_paths_read = _claude_meter_reads(monkeypatch, [unread, unread, usage])
+    all_delays = _recorded_sleeps(monkeypatch)
+
+    reading = _first_reading(monkeypatch, tmp_path, Account(Product.CLAUDE, "org-jon", tmp_path), support.read_claude_meters)[0]
+
+    assert reading.meters is not None
+    assert reading.meters.weekly_percent_left == 70.0
+    assert reading.unread_reason is None
+    assert len(all_paths_read) == 3
+    assert all_delays == [1.0, 2.0]
+
+
+def test_should_read_codex_meters_after_transient_failures_with_growing_delays(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:
     weekly = SimpleNamespace(duration_minutes=10080, used_percent=30.0, resets_at=None)
     usage = SimpleNamespace(all_windows=(weekly,), short_window_percent_left=None)
     unread = support.codex_account_meters.CodexMeterUnreadError("codex app-server sent no rate-limit reply")
-    all_homes_read = _codex_meter_reads(monkeypatch, tmp_path, [unread, usage])
+    all_homes_read = _codex_meter_reads(monkeypatch, tmp_path, [unread, unread, usage])
+    all_delays = _recorded_sleeps(monkeypatch)
 
-    meters = support.read_codex_account_meters(Account(Product.CODEX, "one", tmp_path))
+    reading = _first_reading(monkeypatch, tmp_path, Account(Product.CODEX, "one", tmp_path), support.read_codex_account_meters)[0]
 
-    assert meters is not None
-    assert meters.weekly_percent_left == 70.0
-    assert all_homes_read == [tmp_path, tmp_path]
+    assert reading.meters is not None
+    assert reading.meters.weekly_percent_left == 70.0
+    assert all_homes_read == [tmp_path, tmp_path, tmp_path]
+    assert all_delays == [1.0, 2.0]
 
 
-def test_should_keep_the_unread_reason_after_two_failed_codex_reads(
+def test_should_keep_the_unread_reason_after_every_claude_read_fails(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    all_failures = [support.WeeklyUtilizationProbeError(f"usage endpoint failed {each_number}") for each_number in range(3)]
+    all_paths_read = _claude_meter_reads(monkeypatch, all_failures)
+    all_delays = _recorded_sleeps(monkeypatch)
+
+    reading, adapter, state, now = _first_reading(monkeypatch, tmp_path, Account(Product.CLAUDE, "org-jon", tmp_path), support.read_claude_meters)
+    cached_reading = support.read_accounts(Product.CLAUDE, adapter, all_state=state, now=now)[0]
+
+    assert reading.meters is None
+    assert reading.unread_reason == "usage endpoint failed 2"
+    assert cached_reading.unread_reason == "usage endpoint failed 2"
+    assert len(all_paths_read) == 3
+    assert all_delays == [1.0, 2.0]
+
+
+def test_should_keep_the_unread_reason_after_every_codex_read_fails(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:
-    monkeypatch.setattr(support, "broker_state_path", lambda: tmp_path / "broker" / "state.json")
     first_unread = support.codex_account_meters.CodexMeterUnreadError("codex app-server failed: timed out")
-    second_unread = support.codex_account_meters.CodexMeterUnreadError("codex app-server sent no rate-limit reply")
-    all_homes_read = _codex_meter_reads(monkeypatch, tmp_path, [first_unread, second_unread])
-    account = Account(Product.CODEX, "codex-3", tmp_path)
-    adapter = ProductAdapter(lambda: (account,), support.read_codex_account_meters, "CODEX_HOME", ())
-    state = support._load_state(support.broker_state_path())
-    now = datetime(2026, 10, 3, tzinfo=timezone.utc)
+    last_unread = support.codex_account_meters.CodexMeterUnreadError("codex app-server sent no rate-limit reply")
+    all_homes_read = _codex_meter_reads(monkeypatch, tmp_path, [first_unread, first_unread, last_unread])
+    _recorded_sleeps(monkeypatch)
 
-    first_reading = support.read_accounts(Product.CODEX, adapter, all_state=state, now=now)[0]
+    reading, adapter, state, now = _first_reading(monkeypatch, tmp_path, Account(Product.CODEX, "codex-3", tmp_path), support.read_codex_account_meters)
     cached_reading = support.read_accounts(Product.CODEX, adapter, all_state=state, now=now)[0]
 
-    assert first_reading.meters is None
-    assert first_reading.unread_reason == "codex app-server sent no rate-limit reply"
+    assert reading.meters is None
+    assert reading.unread_reason == "codex app-server sent no rate-limit reply"
     assert cached_reading.unread_reason == "codex app-server sent no rate-limit reply"
-    assert all_homes_read == [tmp_path, tmp_path]
+    assert all_homes_read == [tmp_path, tmp_path, tmp_path]
+
+
+def test_should_cap_the_meter_read_delay(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setattr(support, "METER_READ_ATTEMPTS", 6)
+    all_delays = _recorded_sleeps(monkeypatch)
+    all_failures = [support.WeeklyUtilizationProbeError("down") for _ in range(6)]
+    _claude_meter_reads(monkeypatch, all_failures)
+
+    meters, unread_reason = support.read_meters_with_backoff(support.read_claude_meters, Account(Product.CLAUDE, "one", tmp_path))
+
+    assert meters is None
+    assert unread_reason == "down"
+    assert all_delays == [1.0, 2.0, 4.0, 8.0, 8.0]
 
 
 def test_should_cache_account_reading_under_injected_state_path(
@@ -443,3 +519,35 @@ def test_should_match_order_names_to_an_account_named_by_its_windows_launcher_pa
     ranked = support._with_priorities((launcher_account,), ("claude-org-jon", "claude-editor"))
 
     assert ranked[0].priority == 1
+
+
+def test_should_run_the_cli_against_the_account_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    all_calls: list[tuple[list[str], str]] = []
+
+    def fake_run(command: list[str], **keyword_arguments: object) -> subprocess.CompletedProcess[bytes]:
+        environment = keyword_arguments["env"]
+        assert isinstance(environment, dict)
+        all_calls.append((command, environment["CLAUDE_CONFIG_DIR"]))
+        return subprocess.CompletedProcess(command, 0)
+
+    monkeypatch.setattr(support, "resolve_claude_path", lambda: Path("claude"))
+    monkeypatch.setattr(support.subprocess, "run", fake_run)
+
+    assert support.refresh_claude_login(tmp_path) is True
+    assert all_calls == [(["claude", "-p", "ok", "--model", "haiku"], str(tmp_path))]
+
+
+def test_should_skip_the_refresh_without_a_cli(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setattr(support, "resolve_claude_path", lambda: None)
+
+    assert support.refresh_claude_login(tmp_path) is False
+
+
+def test_should_find_the_cli_in_the_local_bin_folder(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    local_claude = tmp_path / ".local" / "bin" / "claude"
+    local_claude.parent.mkdir(parents=True)
+    local_claude.write_text("", encoding="utf-8")
+    monkeypatch.setattr(support.shutil, "which", lambda name: None)
+    monkeypatch.setattr(support.Path, "home", classmethod(lambda cls: tmp_path))
+
+    assert support.resolve_claude_path() == local_claude

package/scripts/test_claude_account_profile.py

@@ -389,3 +389,17 @@ def test_should_create_named_profile_and_launcher_without_changes_on_repeat(
 def test_should_reject_unsafe_profile_names(profile_name: str) -> None:
     with pytest.raises(ValueError):
         profile.default_profile_home(profile_name)
+
+
+def test_sync_report_payload_should_list_each_entry_under_its_own_key() -> None:
+    report = profile.ProfileSyncReport(
+        all_linked=("CLAUDE.md", "skills"),
+        all_moved_aside=("settings.json",),
+        all_unlinked=("rules",),
+    )
+
+    assert profile.sync_report_payload(report) == {
+        "linked": ["CLAUDE.md", "skills"],
+        "moved_aside": ["settings.json"],
+        "unlinked": ["rules"],
+    }

package/scripts/test_claude_account_worker_process.py

@@ -65,3 +65,22 @@ def test_should_pass_the_live_log_to_the_runner_when_one_is_named(tmp_path: Path
     )
 
     assert captured_options["live_log"] == live_log
+
+
+def test_should_measure_the_time_the_runner_spends_on_the_job(tmp_path: Path) -> None:
+    current_seconds = [50.0]
+
+    def slow_runner(product: Product, argv: list[str], **options: object) -> JobOutcome:
+        current_seconds[0] += 42.0
+        return JobOutcome(0, "{}", "", "main", (), "served", None, None)
+
+    _, elapsed_seconds = invoke_worker(
+        all_arguments=["claude", "-p"],
+        cwd=tmp_path,
+        prompt_text="brief",
+        timeout_minutes=1,
+        runner=slow_runner,
+        monotonic_clock=lambda: current_seconds[0],
+    )
+
+    assert elapsed_seconds == 42.0

package/scripts/test_claude_chain_usage.py

@@ -191,3 +191,55 @@ def test_usage_module_imports_without_picker() -> None:
     )
 
     assert completed.returncode == 0, completed.stderr
+
+
+def _expiring_resolver(all_tokens: list[str | None], all_fetched_tokens: list[str]) -> object:
+    class Windows:
+        session_utilization = 10.0
+        session_resets_at = None
+        weekly_utilization = 40.0
+        weekly_resets_at = None
+
+    class Resolver:
+        def read_oauth_access_token(self, credentials_path: Path, now: datetime) -> str | None:
+            return all_tokens.pop(0)
+
+        def default_credentials_path(self) -> Path:
+            return Path("session") / ".credentials.json"
+
+        def read_session_ingress_token(self) -> None:
+            return None
+
+        def _fetch_usage_payload(self, access_token: str) -> dict[str, object]:
+            all_fetched_tokens.append(access_token)
+            return {}
+
+        def extract_usage_windows(self, payload: dict[str, object]) -> Windows:
+            return Windows()
+
+    return Resolver()
+
+
+def test_should_refresh_an_expired_login_and_read_the_meter(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    account_home = tmp_path / "ev"
+    account_home.mkdir()
+    credentials_path = account_home / ".credentials.json"
+    credentials_path.write_text("{}", encoding="utf-8")
+    all_refreshed_homes: list[Path] = []
+    all_fetched_tokens: list[str] = []
+    monkeypatch.setattr(usage, "_load_resolve_usage_window_module", lambda: _expiring_resolver([None, "fresh-token"], all_fetched_tokens))
+
+    meters = usage.probe_account_meters(credentials_path, all_refreshed_homes.append)
+
+    assert all_refreshed_homes == [account_home]
+    assert all_fetched_tokens == ["fresh-token"]
+    assert meters.weekly_utilization == 40.0
+
+
+def test_should_report_no_token_when_the_refresh_saves_none(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    credentials_path = tmp_path / ".credentials.json"
+    credentials_path.write_text("{}", encoding="utf-8")
+    monkeypatch.setattr(usage, "_load_resolve_usage_window_module", lambda: _expiring_resolver([None, None], []))
+
+    with pytest.raises(usage.WeeklyUtilizationProbeError, match="bearer token"):
+        usage.probe_account_meters(credentials_path, lambda home: True)