claude-dev-env 8.25.0 → 8.26.0

package/hooks/hooks_constants/local_identity.py

@@ -1,19 +1,17 @@
-"""Resolve local identity values for NAS ssh and PII exempt-repo hooks.
+"""Resolve local identity values for the PII hooks.
 
-The enforcer hooks ship into ``~/.claude/`` and cannot read a repository file,
-so they read real machine values from the environment or a git-ignored file in
-the Claude home directory. This module supplies NAS host/user/port, the two
-NAS deny messages that quote those values, and the owner/repo slug set used by
-``pii_exempt_repository_slugs`` (``CLAUDE_PII_EXEMPT_REPOS`` /
-``pii_exempt_repositories``). The committed NAS defaults are placeholders.
+The hooks ship into ``~/.claude/`` and cannot read a repository file, so they
+read machine values from the environment or a git-ignored file in the Claude
+home directory. This module supplies the NAS host the PII scanner allowlists
+and the owner/repo slug set used by ``pii_exempt_repository_slugs``
+(``CLAUDE_PII_EXEMPT_REPOS`` / ``pii_exempt_repositories``). The committed NAS
+host default is a placeholder.
 
 ::
 
     CLAUDE_NAS_HOST set to a host              ->  nas_host() returns that host
-    CLAUDE_NAS_SSH_PORT set to 2200            ->  nas_ssh_port() returns 2200
     CLAUDE_PII_EXEMPT_REPOS="Owner/repo"       ->  {"owner/repo"}
     (env unset, no file)                       ->  nas_host() == "nas.example.local"
-                                                   nas_ssh_port() == 22
                                                    pii_exempt_repository_slugs() == frozenset()
 
 Each value comes from its environment variable, then
@@ -32,19 +30,11 @@ PII_EXEMPT_REPOS_ENV_VAR = "CLAUDE_PII_EXEMPT_REPOS"
 PII_EXEMPT_REPOS_JSON_KEY = "pii_exempt_repositories"
 PII_EXEMPT_REPOS_SEPARATOR = ","
 PII_ALLOWLISTED_VALUES_JSON_KEY = "pii_allowlisted_values"
-NAS_SSH_USER_ENV_VAR = "CLAUDE_NAS_SSH_USER"
-NAS_SSH_PORT_ENV_VAR = "CLAUDE_NAS_SSH_PORT"
 NAS_JSON_KEY = "nas"
 NAS_HOST_JSON_KEY = "host"
-NAS_SSH_USER_JSON_KEY = "ssh_user"
-NAS_SSH_PORT_JSON_KEY = "ssh_port"
 CLAUDE_HOME_DIRECTORY_NAME = ".claude"
 LOCAL_IDENTITY_FILE_NAME = "local-identity.json"
 PLACEHOLDER_NAS_HOST = "nas.example.local"
-PLACEHOLDER_NAS_SSH_USER = "operator"
-PLACEHOLDER_NAS_SSH_PORT = 22
-OPENSSH_INVOCATION_EXAMPLE_BINARY = '"/c/Windows/System32/OpenSSH/ssh.exe"'
-NAS_SSH_RULE_REFERENCE = "~/.claude/rules/nas-ssh-invocation.md"
 
 
 def _local_identity_file_path() -> Path:
@@ -178,106 +168,3 @@ def nas_host() -> str:
     if isinstance(stored_host, str) and stored_host:
         return stored_host
     return PLACEHOLDER_NAS_HOST
-
-
-def nas_ssh_user() -> str:
-    """Return the ssh user the enforcer expects for the NAS.
-
-    ::
-
-        CLAUDE_NAS_SSH_USER set to a user  ->  that user
-        (env unset, no file)               ->  "operator"
-
-    The environment variable wins, then the git-ignored file, then the
-    placeholder default.
-
-    Returns:
-        The ssh login name for the NAS.
-    """
-    user_from_environment = os.environ.get(NAS_SSH_USER_ENV_VAR)
-    if user_from_environment:
-        return user_from_environment
-    stored_user = _nas_section_from_local_file().get(NAS_SSH_USER_JSON_KEY)
-    if isinstance(stored_user, str) and stored_user:
-        return stored_user
-    return PLACEHOLDER_NAS_SSH_USER
-
-
-def nas_ssh_port() -> int:
-    """Return the ssh port the enforcer expects for the NAS.
-
-    ::
-
-        CLAUDE_NAS_SSH_PORT set to 2200  ->  2200
-        (env unset, no file)             ->  22
-
-    The environment variable wins, then the git-ignored file, then the
-    placeholder default.
-
-    Returns:
-        The ssh port number for the NAS.
-    """
-    port_from_environment = os.environ.get(NAS_SSH_PORT_ENV_VAR)
-    if port_from_environment and port_from_environment.isdigit():
-        return int(port_from_environment)
-    stored_port = _nas_section_from_local_file().get(NAS_SSH_PORT_JSON_KEY)
-    if isinstance(stored_port, int):
-        return stored_port
-    return PLACEHOLDER_NAS_SSH_PORT
-
-
-def _openssh_invocation_example() -> str:
-    return (
-        f"{OPENSSH_INVOCATION_EXAMPLE_BINARY} -o BatchMode=yes -o ConnectTimeout=10 "
-        f'-p {nas_ssh_port()} {nas_ssh_user()}@{nas_host()} "<cmd>"'
-    )
-
-
-def bare_ssh_binary_deny_message() -> str:
-    """Return the deny message for a bare ssh-family word aimed at the NAS.
-
-    ::
-
-        ssh -p 22 operator@nas.example.local "ls"  ->  this message text
-        (the text quotes the resolved host, user, and port)
-
-    Names the Git Bash MSYS-ssh hang and points at the Windows OpenSSH binary
-    with batch mode on.
-
-    Returns:
-        The full deny-message text for the bare ssh-family case.
-    """
-    return (
-        f"BLOCKED [nas-ssh-binary]: Git Bash's MSYS ssh reads ~/.ssh/id_ed25519 as "
-        f"world-readable through its ACL mapping, rejects the key as bad permissions, "
-        f"and falls back to an interactive password prompt that hangs unattended "
-        f"sessions against the NAS at {nas_host()}.\n\n"
-        f"Use the Windows OpenSSH binary, which authenticates the key without prompting:\n"
-        f"  {_openssh_invocation_example()}\n\n"
-        f"See {NAS_SSH_RULE_REFERENCE} for full guidance."
-    )
-
-
-def missing_batch_mode_deny_message() -> str:
-    """Return the deny message for the OpenSSH binary without batch mode.
-
-    ::
-
-        "..ssh.exe" -p 22 operator@nas.example.local "ls"  ->  this message text
-        (the text quotes the resolved host, user, and port)
-
-    Names the interactive-prompt hang and asks for ``-o BatchMode=yes`` so a key
-    failure exits loudly.
-
-    Returns:
-        The full deny-message text for the missing-batch-mode case.
-    """
-    return (
-        f"BLOCKED [nas-ssh-binary]: this NAS ssh command uses the Windows OpenSSH binary "
-        f"but omits -o BatchMode=yes, so an authentication regression falls back to an "
-        f"interactive password prompt that hangs unattended sessions against the NAS at "
-        f"{nas_host()}.\n\n"
-        f"Add -o BatchMode=yes so a key failure exits loudly rather than prompting:\n"
-        f"  {_openssh_invocation_example()}\n\n"
-        f"See {NAS_SSH_RULE_REFERENCE} for full guidance."
-    )

package/hooks/hooks_constants/test_code_rules_enforcer_constants.py

@@ -17,7 +17,6 @@ if str(_HOOKS_ROOT) not in sys.path:
     sys.path.insert(0, str(_HOOKS_ROOT))
 
 from hooks_constants.code_rules_enforcer_constants import (
-    ALL_FREE_FORM_EXEMPT_COMMENT_BODIES,
     ALL_VALIDATION_PHASES,
     CONFIG_DIRECTORY_SEGMENT,
     CONSTANTS_MODULE_SUFFIX,
@@ -27,7 +26,6 @@ from hooks_constants.code_rules_enforcer_constants import (
     JSDOC_RETURNS_STRUCTURED_OBJECT_PROMISE_PATTERN,
     RETURN_CALL_OPENING_PARENTHESIS_PATTERN,
     SCHEMA_OPTIONS_PROPERTY_KEY_PATTERN,
-    STEALTH_KEEP_COMMENT_MARKER,
     UNKNOWN_VALIDATION_PHASE_MESSAGE_TEMPLATE,
     apply_edits,
     edits_for_tool,
@@ -108,10 +106,6 @@ def test_constants_module_suffix_and_config_directory_segment_are_defined() -> N
     assert CONFIG_DIRECTORY_SEGMENT == "config"
 
 
-def test_free_form_exempt_comment_bodies_include_stealth_keep_marker() -> None:
-    assert STEALTH_KEEP_COMMENT_MARKER in ALL_FREE_FORM_EXEMPT_COMMENT_BODIES
-
-
 def test_validation_phase_constants_are_reexported_and_render() -> None:
     assert ALL_VALIDATION_PHASES == {EDIT_LANE_PHASE, FULL_GATE_PHASE}
     rendered_message = UNKNOWN_VALIDATION_PHASE_MESSAGE_TEMPLATE.format(

package/hooks/hooks_constants/test_local_identity.py

@@ -1,4 +1,4 @@
-"""Tests for the NAS local-identity loader used by the ssh enforcer hook."""
+"""Tests for the local-identity loader used by the PII hooks."""
 
 from __future__ import annotations
 
@@ -14,7 +14,7 @@ except ImportError:
     sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
     from hooks_constants import local_identity
 
-ALL_NAS_ENV_VARS = ("CLAUDE_NAS_HOST", "CLAUDE_NAS_SSH_USER", "CLAUDE_NAS_SSH_PORT")
+ALL_NAS_ENV_VARS = ("CLAUDE_NAS_HOST",)
 
 
 def _clear_nas_env() -> None:
@@ -23,30 +23,20 @@ def _clear_nas_env() -> None:
 
 
 class TestNasValuesFromEnvironment:
-    def should_read_host_user_and_port_from_the_environment(self) -> None:
-        with patch.dict(
-            os.environ,
-            {
-                "CLAUDE_NAS_HOST": "10.0.0.5",
-                "CLAUDE_NAS_SSH_USER": "tester",
-                "CLAUDE_NAS_SSH_PORT": "2200",
-            },
-            clear=False,
-        ):
+    def should_read_host_from_the_environment(self) -> None:
+        with patch.dict(os.environ, {"CLAUDE_NAS_HOST": "10.0.0.5"}, clear=False):
             assert local_identity.nas_host() == "10.0.0.5"
-            assert local_identity.nas_ssh_user() == "tester"
-            assert local_identity.nas_ssh_port() == 2200
 
 
 class TestNasValuesFromLocalFile:
-    def should_read_host_user_and_port_from_the_local_identity_file(
+    def should_read_host_from_the_local_identity_file(
         self, tmp_path: Path
     ) -> None:
         claude_home = tmp_path / ".claude"
         claude_home.mkdir()
         (claude_home / "local-identity.json").write_text(
             json.dumps(
-                {"nas": {"host": "10.1.1.9", "ssh_user": "fileuser", "ssh_port": 2222}}
+                {"nas": {"host": "10.1.1.9"}}
             ),
             encoding="utf-8",
         )
@@ -54,18 +44,14 @@ class TestNasValuesFromLocalFile:
             _clear_nas_env()
             with patch.object(Path, "home", return_value=tmp_path):
                 assert local_identity.nas_host() == "10.1.1.9"
-                assert local_identity.nas_ssh_user() == "fileuser"
-                assert local_identity.nas_ssh_port() == 2222
 
 
 class TestNasValuesPlaceholderDefault:
-    def should_return_placeholders_when_no_env_and_no_file(self, tmp_path: Path) -> None:
+    def should_return_placeholder_when_no_env_and_no_file(self, tmp_path: Path) -> None:
         with patch.dict(os.environ, {}, clear=False):
             _clear_nas_env()
             with patch.object(Path, "home", return_value=tmp_path):
                 assert local_identity.nas_host() == "nas.example.local"
-                assert local_identity.nas_ssh_user() == "operator"
-                assert local_identity.nas_ssh_port() == 22
 
 
 class TestPiiExemptRepositorySlugs:
@@ -234,25 +220,3 @@ class TestLocalIdentityPathOverride:
         ), patch.object(Path, "home", return_value=tmp_path):
             _clear_nas_env()
             assert local_identity.nas_host() == "10.9.9.9"
-
-
-class TestDenyMessagesQuoteTheResolvedHost:
-    def should_include_the_resolved_host_and_port_in_the_bare_binary_message(
-        self,
-    ) -> None:
-        with patch.dict(
-            os.environ,
-            {"CLAUDE_NAS_HOST": "10.0.0.5", "CLAUDE_NAS_SSH_PORT": "2200"},
-            clear=False,
-        ):
-            os.environ.pop("CLAUDE_NAS_SSH_USER", None)
-            message = local_identity.bare_ssh_binary_deny_message()
-            assert "10.0.0.5" in message
-            assert "-p 2200" in message
-            assert "BatchMode=yes" in message
-
-    def should_include_the_resolved_host_in_the_missing_batch_mode_message(self) -> None:
-        with patch.dict(os.environ, {"CLAUDE_NAS_HOST": "10.0.0.5"}, clear=False):
-            message = local_identity.missing_batch_mode_deny_message()
-            assert "10.0.0.5" in message
-            assert "BatchMode=yes" in message

package/hooks/hooks_constants/thread_spawn_pace_hook_constants.py

@@ -0,0 +1,45 @@
+"""Constants for the thread spawn pace PreToolUse hook.
+
+Groups: the usage-pace script it runs, the reshape values for an over-pace
+spawn, and the hook output keys and messages.
+"""
+
+from __future__ import annotations
+
+USAGE_PACE_SCRIPT_ENV_VAR = "COORDINATOR_USAGE_PACE_SCRIPT"
+USAGE_PACE_SCRIPT_FILE_NAME = "usage_pace.py"
+USAGE_PACE_TIMEOUT_SECONDS = 15
+
+TOOL_INPUT_KEY = "tool_input"
+THREAD_MODEL_WHEN_OVER_PACE = "claude-sonnet-5-5"
+THREAD_EFFORT_WHEN_OVER_PACE = "medium"
+MODEL_INPUT_KEY = "model"
+EFFORT_INPUT_KEY = "effort"
+INSTRUCTIONS_INPUT_KEY = "instructions"
+INSTRUCTIONS_MAXIMUM_BYTES = 8192
+INSTRUCTIONS_SEPARATOR = "\n\n"
+INSTRUCTIONS_ENCODING = "utf-8"
+FABLE_ADVISOR_LINE = (
+    "Mandatory Fable advisor: usage is over pace, so this thread runs on "
+    "Sonnet 5.5 at medium effort. Invoke /team-advisor before substantive "
+    "work and bind a Fable advisor through it. Consult that advisor again "
+    "before you report done, and name its verdict in your report."
+)
+
+PERMISSION_DENY = "deny"
+PERMISSION_DECISION_REASON_KEY = "permissionDecisionReason"
+ADDITIONAL_CONTEXT_KEY = "additionalContext"
+NOT_AN_OBJECT_REASON = "start_thread_session input is not a JSON object"
+NO_INSTRUCTIONS_REASON = "start_thread_session input has no instructions text"
+OVER_BYTE_CAP_REASON_TEMPLATE = (
+    "usage is over pace and the brief plus the mandatory Fable advisor line is "
+    "{reshaped_byte_count} bytes, over the {maximum_bytes}-byte cap; "
+    "shorten the instructions by {excess_byte_count} bytes"
+)
+RESHAPE_CONTEXT_PREFIX = (
+    "Usage over pace or unreadable: this thread spawn now runs on "
+    "claude-sonnet-5-5 at medium effort with a mandatory Fable advisor line. "
+    "Pace verdict: "
+)
+PACE_VERDICT_CONTEXT_MAXIMUM_CHARACTERS = 600
+LAUNCH_FAILURE_ERROR_TEMPLATE = "usage pace did not finish: {failure_type}"

package/hooks/hooks_constants/usage_pace_constants.py

@@ -0,0 +1,49 @@
+"""Constants for the usage-pace reader that the thread spawn pace hook runs.
+
+Groups: the OAuth usage endpoint probe, the token and certificate sources,
+the rate windows and their lengths, the exit codes, and the JSON keys of the
+verdict.
+"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+
+USAGE_ENDPOINT_URL = "https://api.anthropic.com/api/oauth/usage"
+ANTHROPIC_BETA_HEADER = "anthropic-beta"
+USAGE_BETA_VALUE = "oauth-2025-04-20"
+AUTHORIZATION_HEADER = "Authorization"
+BEARER_PREFIX = "Bearer "
+CONTENT_TYPE_HEADER_NAME = "Content-Type"
+CONTENT_TYPE_JSON = "application/json"
+PROBE_TIMEOUT_SECONDS = 8
+
+INGRESS_BEARER_FILE_ENV_VAR = "CLAUDE_SESSION_INGRESS_TOKEN_FILE"
+SSL_CERT_FILE_ENV_VAR = "SSL_CERT_FILE"
+CONTAINER_PROXY_CA_BUNDLE_PATH = "/root/.ccr/ca-bundle.crt"
+
+UTILIZATION_KEY = "utilization"
+RESETS_AT_KEY = "resets_at"
+ISO_UTC_SUFFIX = "Z"
+ISO_UTC_OFFSET = "+00:00"
+ALL_RATE_WINDOW_LENGTHS = (
+    ("five_hour", timedelta(hours=5)),
+    ("seven_day", timedelta(days=7)),
+)
+PERCENT_SCALE = 100.0
+PERCENT_DECIMAL_PLACES = 1
+MINIMUM_ELAPSED_PERCENT_FOR_PACE = 10.0
+
+EXIT_CODE_OVER_PACE = 0
+EXIT_CODE_UNDER_PACE = 1
+EXIT_CODE_UNREADABLE = 2
+
+RESULT_KEY_OVER_PACE = "over_pace"
+RESULT_KEY_CHECKED_AT = "checked_at"
+RESULT_KEY_WINDOWS = "windows"
+RESULT_KEY_ERROR = "error"
+WINDOW_KEY_NAME = "window"
+WINDOW_KEY_USED_PERCENT = "used_percent"
+WINDOW_KEY_ELAPSED_PERCENT = "elapsed_percent"
+WINDOW_KEY_RESETS_AT = "resets_at"
+WINDOW_KEY_OVER_PACE = "over_pace"

package/hooks/routing/conftest.py

@@ -0,0 +1,10 @@
+"""Add hooks/routing and hooks/ to sys.path for every test collected under this directory."""
+
+import sys
+from pathlib import Path
+
+_ROUTING_DIRECTORY = str(Path(__file__).resolve().parent)
+_HOOKS_DIRECTORY = str(Path(_ROUTING_DIRECTORY).parent)
+for each_directory in (_ROUTING_DIRECTORY, _HOOKS_DIRECTORY):
+    if each_directory not in sys.path:
+        sys.path.insert(0, each_directory)

package/hooks/routing/test_thread_spawn_pace_hook.py

@@ -0,0 +1,139 @@
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+from hooks_constants.thread_spawn_pace_hook_constants import FABLE_ADVISOR_LINE
+
+HOOK_SCRIPT = Path(__file__).resolve().parent / "thread_spawn_pace_hook.py"
+SPAWN_INPUT = {
+    "thread_id": "cmsg_example",
+    "title": "Example thread",
+    "ack": "Starting on the example first.",
+    "instructions": "Do the example task.",
+    "context_message_ids": ["cmsg_example"],
+}
+
+
+def _write_pace_stub(
+    tmp_path: Path, exit_code: int, verdict: dict[str, object]
+) -> Path:
+    stub_path = tmp_path / f"pace_stub_{exit_code}.py"
+    stub_path.write_text(
+        f"import sys\nprint({json.dumps(json.dumps(verdict))})\nsys.exit({exit_code})\n",
+        encoding="utf-8",
+    )
+    return stub_path
+
+
+def _run_hook(pace_script: Path, tool_input: object) -> str:
+    hook_payload = {
+        "hook_event_name": "PreToolUse",
+        "tool_name": "mcp__hearthbot__start_thread_session",
+        "tool_input": tool_input,
+    }
+    completed = subprocess.run(
+        [sys.executable, str(HOOK_SCRIPT)],
+        input=json.dumps(hook_payload),
+        capture_output=True,
+        text=True,
+        env={**os.environ, "COORDINATOR_USAGE_PACE_SCRIPT": str(pace_script)},
+        check=True,
+    )
+    return completed.stdout
+
+
+def _hook_specific_output(stdout: str) -> dict[str, object]:
+    return json.loads(stdout)["hookSpecificOutput"]
+
+
+def _assert_reshaped(stdout: str) -> None:
+    decision = _hook_specific_output(stdout)
+    assert decision["hookEventName"] == "PreToolUse"
+    assert decision["permissionDecision"] == "allow"
+    assert decision["updatedInput"] == {
+        **SPAWN_INPUT,
+        "model": "claude-sonnet-5-5",
+        "effort": "medium",
+        "instructions": f"Do the example task.\n\n{FABLE_ADVISOR_LINE}",
+    }
+
+
+def test_should_reshape_the_spawn_when_usage_is_over_pace(tmp_path: Path) -> None:
+    _assert_reshaped(
+        _run_hook(_write_pace_stub(tmp_path, 0, {"over_pace": True}), SPAWN_INPUT)
+    )
+
+
+def test_should_pass_the_spawn_through_unchanged_when_usage_is_under_pace(
+    tmp_path: Path,
+) -> None:
+    assert (
+        _run_hook(_write_pace_stub(tmp_path, 1, {"over_pace": False}), SPAWN_INPUT)
+        == ""
+    )
+
+
+def test_should_reshape_the_spawn_when_usage_is_unreadable(tmp_path: Path) -> None:
+    _assert_reshaped(
+        _run_hook(
+            _write_pace_stub(tmp_path, 2, {"over_pace": None, "error": "x"}),
+            SPAWN_INPUT,
+        )
+    )
+
+
+def test_should_reshape_the_spawn_when_the_pace_script_is_missing(
+    tmp_path: Path,
+) -> None:
+    _assert_reshaped(_run_hook(tmp_path / "absent.py", SPAWN_INPUT))
+
+
+def test_should_append_the_advisor_line_once(tmp_path: Path) -> None:
+    already_reshaped = {
+        **SPAWN_INPUT,
+        "instructions": f"Do the example task.\n\n{FABLE_ADVISOR_LINE}",
+    }
+    stdout = _run_hook(
+        _write_pace_stub(tmp_path, 0, {"over_pace": True}), already_reshaped
+    )
+    assert (
+        _hook_specific_output(stdout)["updatedInput"]["instructions"].count(
+            FABLE_ADVISOR_LINE
+        )
+        == 1
+    )
+
+
+@pytest.mark.parametrize(
+    ("tool_input", "reason"),
+    [
+        (["not", "an", "object"], "start_thread_session input is not a JSON object"),
+        ({"title": "No brief"}, "start_thread_session input has no instructions text"),
+    ],
+)
+def test_should_deny_a_spawn_it_cannot_reshape(
+    tmp_path: Path, tool_input: object, reason: str
+) -> None:
+    decision = _hook_specific_output(
+        _run_hook(_write_pace_stub(tmp_path, 0, {"over_pace": True}), tool_input)
+    )
+    assert decision["permissionDecision"] == "deny"
+    assert decision["permissionDecisionReason"] == reason
+    assert "updatedInput" not in decision
+
+
+def test_should_deny_a_brief_the_advisor_line_would_push_past_the_byte_cap(
+    tmp_path: Path,
+) -> None:
+    full_brief = {**SPAWN_INPUT, "instructions": "x" * 8100}
+    decision = _hook_specific_output(
+        _run_hook(_write_pace_stub(tmp_path, 0, {"over_pace": True}), full_brief)
+    )
+    assert decision["permissionDecision"] == "deny"
+    over_by = 8100 + 2 + len(FABLE_ADVISOR_LINE.encode("utf-8")) - 8192
+    assert decision["permissionDecisionReason"].endswith(
+        f"shorten the instructions by {over_by} bytes"
+    )

package/hooks/routing/test_usage_pace.py

@@ -0,0 +1,142 @@
+import json
+import subprocess
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import pytest
+from usage_pace import (
+    UsageUnreadable,
+    build_verdict,
+    measure_account_pace,
+    measure_window_pace,
+)
+
+USAGE_PACE_SCRIPT = Path(__file__).resolve().parent / "usage_pace.py"
+NOW = datetime(2026, 9, 29, 13, 57, 40, tzinfo=timezone.utc)
+FIVE_HOUR_RESET = "2026-09-29T18:50:00+00:00"
+WEEKLY_RESET = "2026-10-03T20:00:00+00:00"
+
+
+def _payload(five_hour_used: float, weekly_used: float) -> dict[str, object]:
+    return {
+        "five_hour": {"utilization": five_hour_used, "resets_at": FIVE_HOUR_RESET},
+        "seven_day": {"utilization": weekly_used, "resets_at": WEEKLY_RESET},
+        "seven_day_opus": None,
+    }
+
+
+def _run_script(tmp_path: Path, payload: object) -> tuple[int, dict[str, object]]:
+    payload_path = tmp_path / "usage.json"
+    payload_path.write_text(json.dumps(payload), encoding="utf-8")
+    completed = subprocess.run(
+        [
+            sys.executable,
+            str(USAGE_PACE_SCRIPT),
+            "--payload-file",
+            str(payload_path),
+            "--now",
+            NOW.isoformat(),
+        ],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return completed.returncode, json.loads(completed.stdout)
+
+
+def test_should_hold_a_window_clear_before_ten_percent_of_it_has_elapsed() -> None:
+    pace = measure_window_pace(
+        "five_hour",
+        timedelta(hours=5),
+        {"utilization": 3.0, "resets_at": FIVE_HOUR_RESET},
+        NOW,
+    )
+    assert pace.elapsed_percent == 2.6
+    assert pace.over_pace is False
+
+
+def test_should_flag_a_window_whose_spend_runs_ahead_of_the_clock_past_the_floor() -> (
+    None
+):
+    pace = measure_window_pace(
+        "five_hour",
+        timedelta(hours=5),
+        {"utilization": 50.0, "resets_at": "2026-09-29T17:00:00+00:00"},
+        NOW,
+    )
+    assert pace.elapsed_percent == 39.2
+    assert pace.over_pace is True
+
+
+def test_should_clear_a_window_whose_spend_trails_the_clock() -> None:
+    pace = measure_window_pace(
+        "seven_day",
+        timedelta(days=7),
+        {"utilization": 20.0, "resets_at": WEEKLY_RESET},
+        NOW,
+    )
+    assert pace.elapsed_percent == 39.3
+    assert pace.over_pace is False
+
+
+def test_should_clamp_elapsed_time_to_the_window_length() -> None:
+    long_past_reset = measure_window_pace(
+        "five_hour",
+        timedelta(hours=5),
+        {"utilization": 99.0, "resets_at": "2026-09-29T10:00:00Z"},
+        NOW,
+    )
+    assert long_past_reset.elapsed_percent == 100.0
+    assert long_past_reset.over_pace is False
+
+
+def test_should_report_over_pace_when_any_window_runs_ahead() -> None:
+    verdict = build_verdict(measure_account_pace(_payload(1.0, 93.0), NOW), NOW)
+    assert verdict["over_pace"] is True
+    assert [each["over_pace"] for each in verdict["windows"]] == [False, True]
+
+
+def test_should_report_under_pace_when_every_window_trails() -> None:
+    verdict = build_verdict(measure_account_pace(_payload(1.0, 20.0), NOW), NOW)
+    assert verdict["over_pace"] is False
+
+
+@pytest.mark.parametrize(
+    "broken_payload",
+    [
+        {"seven_day": {"utilization": 20.0, "resets_at": WEEKLY_RESET}},
+        {
+            "five_hour": {"utilization": None, "resets_at": FIVE_HOUR_RESET},
+            "seven_day": {"utilization": 1.0, "resets_at": WEEKLY_RESET},
+        },
+        {
+            "five_hour": {"utilization": 1.0, "resets_at": "soon"},
+            "seven_day": {"utilization": 1.0, "resets_at": WEEKLY_RESET},
+        },
+    ],
+)
+def test_should_treat_a_missing_or_unreadable_window_as_unreadable(
+    broken_payload: dict[str, object],
+) -> None:
+    with pytest.raises(UsageUnreadable):
+        measure_account_pace(broken_payload, NOW)
+
+
+def test_should_exit_zero_with_the_verdict_when_over_pace(tmp_path: Path) -> None:
+    exit_code, verdict = _run_script(tmp_path, _payload(3.0, 93.0))
+    assert exit_code == 0
+    assert verdict["over_pace"] is True
+
+
+def test_should_exit_one_when_under_pace(tmp_path: Path) -> None:
+    exit_code, verdict = _run_script(tmp_path, _payload(1.0, 20.0))
+    assert exit_code == 1
+    assert verdict["over_pace"] is False
+
+
+def test_should_exit_two_with_a_null_verdict_when_unreadable(tmp_path: Path) -> None:
+    exit_code, verdict = _run_script(tmp_path, {"five_hour": None})
+    assert exit_code == 2
+    assert verdict["over_pace"] is None
+    assert verdict["error"] == "usage response has no five_hour window"