claude-dev-env 2.2.0 → 2.3.0

package/scripts/dev_env_scripts_constants/claude_chain_usage_constants.py

@@ -0,0 +1,58 @@
+"""Named constants for the claude chain weekly-usage report tool.
+
+Per the project's configuration conventions, every scalar and structural
+constant the usage reporter needs lives here rather than inline in the module.
+"""
+
+from __future__ import annotations
+
+FULL_WEEKLY_PERCENT: float = 100.0
+"""Percent scale ceiling for weekly utilization (remaining = this minus used)."""
+
+USAGE_PAUSE_SKILL_DIRECTORY_NAME: str = "skills"
+"""Package-root directory name that holds skill trees (sibling of ``scripts/``)."""
+
+USAGE_PAUSE_SKILL_NAME: str = "usage-pause"
+"""Skill directory name under ``skills/`` that owns the OAuth usage probe."""
+
+USAGE_PAUSE_SCRIPTS_DIRECTORY_NAME: str = "scripts"
+"""Directory under the usage-pause skill that holds the OAuth probe module."""
+
+RESOLVE_USAGE_WINDOW_MODULE_NAME: str = "resolve_usage_window"
+"""Module name of the usage-pause OAuth probe loader."""
+
+RESOLVE_USAGE_WINDOW_FILENAME: str = "resolve_usage_window.py"
+"""Filename of the usage-pause OAuth probe module on disk."""
+
+JSON_ACCOUNTS_KEY: str = "accounts"
+"""Top-level key in the CLI JSON report holding the per-account list."""
+
+JSON_COMMAND_KEY: str = "command"
+"""Per-account JSON key naming the chain binary."""
+
+JSON_WEEKLY_REMAINING_PERCENT_KEY: str = "weekly_remaining_percent"
+"""Per-account JSON key for remaining weekly usage percent (or null)."""
+
+JSON_ERROR_KEY: str = "error"
+"""Per-account JSON key carrying the unmeasurable-reason string."""
+
+CLI_CONFIG_PATH_FLAG: str = "--config-path"
+"""CLI flag that overrides the chain configuration file path."""
+
+NO_ACCESS_TOKEN_ERROR_TEMPLATE: str = (
+    "no usable bearer token from the OAuth credential file at {credentials_path}"
+)
+"""Error when the entry credential file yields no usable OAuth bearer."""
+
+WEEKLY_UTILIZATION_MISSING_ERROR: str = (
+    "usage response carried no weekly utilization"
+)
+"""Error when the OAuth usage payload has no readable seven_day utilization."""
+
+USAGE_PROBE_FAILED_ERROR_TEMPLATE: str = "usage probe failed: {error}"
+"""Error when the OAuth usage HTTP probe raises."""
+
+RESOLVE_USAGE_WINDOW_MISSING_ERROR_TEMPLATE: str = (
+    "usage-pause probe module not found at {module_path}"
+)
+"""Error when the resolve_usage_window script cannot be located on disk."""

package/scripts/dev_env_scripts_constants/code_review_constants.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 CODE_REVIEW_SLASH_COMMAND: str = "/code-review"
 """Built-in Claude Code slash command that runs the repository review."""
 
-CODE_REVIEW_EFFORT: str = "high"
+CODE_REVIEW_EFFORT: str = "xhigh"
 """Effort level passed to the built-in review slash command."""
 
 CODE_REVIEW_FIX_FLAG: str = "--fix"

package/scripts/dev_env_scripts_constants/timing.py

@@ -13,5 +13,5 @@ DEFAULT_POLL_INTERVAL: int = 30
 WORKER_STAGGER_SECONDS: int = 15
 """Seconds between staggered headless grok worker process starts in a batch."""
 
-DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS: int = 600
+DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS: int = 2400
 """Default timeout applied to one headless `/code-review` chain invocation, in seconds."""

package/scripts/test_claude_chain_runner.py

@@ -14,6 +14,7 @@ if str(_SCRIPTS_DIR) not in sys.path:
     sys.path.insert(0, str(_SCRIPTS_DIR))
 
 import claude_chain_runner as runner  # noqa: E402
+import claude_chain_usage as chain_usage  # noqa: E402
 from dev_env_scripts_constants.claude_chain_constants import (  # noqa: E402
     ALL_USAGE_LIMIT_SIGNATURES,
     ATTEMPT_STATUS_EXECUTABLE_NOT_FOUND,
@@ -51,6 +52,10 @@ from dev_env_scripts_constants.claude_chain_constants import (  # noqa: E402
 
 _A_SIGNATURE = ALL_USAGE_LIMIT_SIGNATURES[0]
 _PROMPT_ARGUMENTS = ["-p", "hello"]
+_EQUAL_WEEKLY_REMAINING_PERCENT = 50.0
+_HIGH_WEEKLY_REMAINING_PERCENT = 90.0
+_MID_WEEKLY_REMAINING_PERCENT = 50.0
+_LOW_WEEKLY_REMAINING_PERCENT = 10.0
 
 
 def _completed(command, returncode, stdout="", stderr=""):
@@ -74,6 +79,43 @@ def _write_chain_config(tmp_path, chain_entries):
     return config_file
 
 
+def _config_order_usage_reporter(
+    *, config_path: Path
+) -> list[chain_usage.AccountUsageReport]:
+    all_entries = runner.load_chain(config_path)
+    return [
+        chain_usage.AccountUsageReport(
+            command=each_entry.command,
+            weekly_remaining_percent=_EQUAL_WEEKLY_REMAINING_PERCENT,
+        )
+        for each_entry in all_entries
+    ]
+
+
+def _usage_reporter_from_remaining(
+    remaining_percent_by_command: dict[str, float | None],
+):
+    call_count = {"count": 0}
+
+    def active_reporter(
+        *, config_path: Path
+    ) -> list[chain_usage.AccountUsageReport]:
+        call_count["count"] += 1
+        all_entries = runner.load_chain(config_path)
+        return [
+            chain_usage.AccountUsageReport(
+                command=each_entry.command,
+                weekly_remaining_percent=remaining_percent_by_command[
+                    each_entry.command
+                ],
+            )
+            for each_entry in all_entries
+        ]
+
+    active_reporter.call_count = call_count
+    return active_reporter
+
+
 class _Recorder:
     def __init__(self, behavior_by_command):
         self.behavior_by_command = behavior_by_command
@@ -100,14 +142,364 @@ def _install_tty_stdin(monkeypatch):
     monkeypatch.setattr(runner.sys, "stdin", _TtyStdin())
 
 
-def _install(monkeypatch, config_file, behavior_by_command):
+def _install(
+    monkeypatch,
+    config_file,
+    behavior_by_command,
+    *,
+    weekly_usage_reporter=None,
+):
     recorder = _Recorder(behavior_by_command)
     monkeypatch.setattr(runner, "chain_config_path", lambda: config_file)
     monkeypatch.setattr(runner, "chain_subprocess_runner", recorder)
+    active_reporter = (
+        weekly_usage_reporter
+        if weekly_usage_reporter is not None
+        else _config_order_usage_reporter
+    )
+    monkeypatch.setattr(runner, "chain_weekly_usage_reporter", active_reporter)
     _install_tty_stdin(monkeypatch)
     return recorder
 
 
+def test_highest_weekly_remaining_is_tried_first(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude"), _entry("claude-ev")])
+    usage_reporter = _usage_reporter_from_remaining(
+        {
+            "claude": _LOW_WEEKLY_REMAINING_PERCENT,
+            "claude-ev": _HIGH_WEEKLY_REMAINING_PERCENT,
+        }
+    )
+    recorder = _install(
+        monkeypatch,
+        config_file,
+        {
+            "claude": _completed("claude", 0, stdout="from-claude"),
+            "claude-ev": _completed("claude-ev", 0, stdout="from-ev"),
+        },
+        weekly_usage_reporter=usage_reporter,
+    )
+    chain_result = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert chain_result.served_command == "claude-ev"
+    assert chain_result.returncode == 0
+    assert chain_result.stdout == "from-ev"
+    assert recorder.invocations[0][0] == "claude-ev"
+    assert [each_attempt.command for each_attempt in chain_result.attempts] == [
+        "claude-ev"
+    ]
+    assert chain_result.attempts[0].status == ATTEMPT_STATUS_SERVED
+
+
+def test_usage_limit_failsover_remaining_ranked_accounts(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(
+        tmp_path, [_entry("claude"), _entry("claude-ev"), _entry("claude-editor")]
+    )
+    usage_reporter = _usage_reporter_from_remaining(
+        {
+            "claude": _MID_WEEKLY_REMAINING_PERCENT,
+            "claude-ev": _HIGH_WEEKLY_REMAINING_PERCENT,
+            "claude-editor": _LOW_WEEKLY_REMAINING_PERCENT,
+        }
+    )
+    _install(
+        monkeypatch,
+        config_file,
+        {
+            "claude-ev": _completed("claude-ev", 1, stderr=_A_SIGNATURE),
+            "claude": _completed("claude", 0, stdout="ok"),
+            "claude-editor": _completed("claude-editor", 0, stdout="should not run"),
+        },
+        weekly_usage_reporter=usage_reporter,
+    )
+    chain_result = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert chain_result.served_command == "claude"
+    assert chain_result.returncode == 0
+    assert [each_attempt.command for each_attempt in chain_result.attempts] == [
+        "claude-ev",
+        "claude",
+    ]
+    assert chain_result.attempts[0].status == ATTEMPT_STATUS_USAGE_LIMITED
+    assert chain_result.attempts[1].status == ATTEMPT_STATUS_SERVED
+
+
+def test_non_usage_error_on_highest_ranked_stops_without_rest(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude"), _entry("claude-ev")])
+    usage_reporter = _usage_reporter_from_remaining(
+        {
+            "claude": _LOW_WEEKLY_REMAINING_PERCENT,
+            "claude-ev": _HIGH_WEEKLY_REMAINING_PERCENT,
+        }
+    )
+    _install(
+        monkeypatch,
+        config_file,
+        {
+            "claude-ev": _completed("claude-ev", 2, stderr="unknown flag"),
+            "claude": _completed("claude", 0, stdout="should not run"),
+        },
+        weekly_usage_reporter=usage_reporter,
+    )
+    chain_result = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert chain_result.served_command == "claude-ev"
+    assert chain_result.returncode == 2
+    assert len(chain_result.attempts) == 1
+    assert chain_result.attempts[0].status == ATTEMPT_STATUS_NONZERO_EXIT
+
+
+def test_weekly_usage_probe_runs_once_per_run_claude(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude"), _entry("claude-ev")])
+    usage_reporter = _usage_reporter_from_remaining(
+        {
+            "claude": _HIGH_WEEKLY_REMAINING_PERCENT,
+            "claude-ev": _LOW_WEEKLY_REMAINING_PERCENT,
+        }
+    )
+    _install(
+        monkeypatch,
+        config_file,
+        {
+            "claude": _completed("claude", 1, stderr=_A_SIGNATURE),
+            "claude-ev": _completed("claude-ev", 0, stdout="ok"),
+        },
+        weekly_usage_reporter=usage_reporter,
+    )
+    runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert usage_reporter.call_count["count"] == 1
+
+
+def test_usage_reporter_import_failure_falls_back_to_config_order(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude"), _entry("claude-ev")])
+
+    def broken_usage_reporter(
+        *, config_path: Path
+    ) -> list[chain_usage.AccountUsageReport]:
+        raise ImportError("claude_chain_usage unavailable")
+
+    recorder = _install(
+        monkeypatch,
+        config_file,
+        {
+            "claude": _completed("claude", 0, stdout="from-claude"),
+            "claude-ev": _completed("claude-ev", 0, stdout="from-ev"),
+        },
+        weekly_usage_reporter=broken_usage_reporter,
+    )
+    chain_result = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert chain_result.served_command == "claude"
+    assert chain_result.returncode == 0
+    assert chain_result.stdout == "from-claude"
+    assert recorder.invocations[0][0] == "claude"
+    assert [each_attempt.command for each_attempt in chain_result.attempts] == [
+        "claude"
+    ]
+
+
+def test_missing_high_remaining_binary_falls_through_to_lower_remaining(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude"), _entry("claude-ev")])
+    usage_reporter = _usage_reporter_from_remaining(
+        {
+            "claude": _LOW_WEEKLY_REMAINING_PERCENT,
+            "claude-ev": _HIGH_WEEKLY_REMAINING_PERCENT,
+        }
+    )
+    _install(
+        monkeypatch,
+        config_file,
+        {
+            "claude-ev": FileNotFoundError(),
+            "claude": _completed("claude", 0, stdout="from-claude"),
+        },
+        weekly_usage_reporter=usage_reporter,
+    )
+    chain_result = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert chain_result.served_command == "claude"
+    assert chain_result.returncode == 0
+    assert chain_result.stdout == "from-claude"
+    assert [each_attempt.command for each_attempt in chain_result.attempts] == [
+        "claude-ev",
+        "claude",
+    ]
+    assert [each_attempt.status for each_attempt in chain_result.attempts] == [
+        ATTEMPT_STATUS_EXECUTABLE_NOT_FOUND,
+        ATTEMPT_STATUS_SERVED,
+    ]
+
+
+def test_all_missing_binaries_exhausts_chain(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude"), _entry("claude-ev")])
+    usage_reporter = _usage_reporter_from_remaining(
+        {
+            "claude": _LOW_WEEKLY_REMAINING_PERCENT,
+            "claude-ev": _HIGH_WEEKLY_REMAINING_PERCENT,
+        }
+    )
+    _install(
+        monkeypatch,
+        config_file,
+        {
+            "claude-ev": FileNotFoundError(),
+            "claude": FileNotFoundError(),
+        },
+        weekly_usage_reporter=usage_reporter,
+    )
+    chain_result = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert chain_result.served_command is None
+    assert chain_result.returncode == NO_COMPLETED_PROCESS_RETURN_CODE
+    assert [each_attempt.command for each_attempt in chain_result.attempts] == [
+        "claude-ev",
+        "claude",
+    ]
+    assert [each_attempt.status for each_attempt in chain_result.attempts] == [
+        ATTEMPT_STATUS_EXECUTABLE_NOT_FOUND,
+        ATTEMPT_STATUS_EXECUTABLE_NOT_FOUND,
+    ]
+
+
+def test_missing_later_ranked_binary_is_skipped(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(
+        tmp_path, [_entry("claude"), _entry("claude-ev"), _entry("claude-editor")]
+    )
+    usage_reporter = _usage_reporter_from_remaining(
+        {
+            "claude": _MID_WEEKLY_REMAINING_PERCENT,
+            "claude-ev": _HIGH_WEEKLY_REMAINING_PERCENT,
+            "claude-editor": _LOW_WEEKLY_REMAINING_PERCENT,
+        }
+    )
+    _install(
+        monkeypatch,
+        config_file,
+        {
+            "claude-ev": _completed("claude-ev", 1, stderr=_A_SIGNATURE),
+            "claude": FileNotFoundError(),
+            "claude-editor": _completed("claude-editor", 0, stdout="done"),
+        },
+        weekly_usage_reporter=usage_reporter,
+    )
+    chain_result = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert chain_result.served_command == "claude-editor"
+    assert [each_attempt.command for each_attempt in chain_result.attempts] == [
+        "claude-ev",
+        "claude",
+        "claude-editor",
+    ]
+    assert [each_attempt.status for each_attempt in chain_result.attempts] == [
+        ATTEMPT_STATUS_USAGE_LIMITED,
+        ATTEMPT_STATUS_EXECUTABLE_NOT_FOUND,
+        ATTEMPT_STATUS_SERVED,
+    ]
+
+
+def test_ranked_walk_preserves_extra_args_for_mapped_entry(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(
+        tmp_path,
+        [
+            _entry("claude", extra_args=["--account", "primary"]),
+            _entry("claude-ev", extra_args=["--account", "ev"]),
+        ],
+    )
+    usage_reporter = _usage_reporter_from_remaining(
+        {
+            "claude": _LOW_WEEKLY_REMAINING_PERCENT,
+            "claude-ev": _HIGH_WEEKLY_REMAINING_PERCENT,
+        }
+    )
+    recorder = _install(
+        monkeypatch,
+        config_file,
+        {"claude-ev": _completed("claude-ev", 0)},
+        weekly_usage_reporter=usage_reporter,
+    )
+    runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert recorder.invocations[0] == [
+        "claude-ev",
+        "-p",
+        "hello",
+        "--account",
+        "ev",
+    ]
+
+
+def test_duplicate_command_entries_are_both_walked(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(
+        tmp_path,
+        [
+            _entry("claude", extra_args=["--account", "primary"]),
+            _entry("claude", extra_args=["--account", "secondary"]),
+        ],
+    )
+    usage_reporter = _usage_reporter_from_remaining(
+        {"claude": _HIGH_WEEKLY_REMAINING_PERCENT}
+    )
+    recorder = _install(
+        monkeypatch,
+        config_file,
+        {"claude": _completed("claude", 1, stderr=_A_SIGNATURE)},
+        weekly_usage_reporter=usage_reporter,
+    )
+    chain_result = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert [each_invocation[-1] for each_invocation in recorder.invocations] == [
+        "primary",
+        "secondary",
+    ]
+    assert [each_attempt.status for each_attempt in chain_result.attempts] == [
+        ATTEMPT_STATUS_USAGE_LIMITED,
+        ATTEMPT_STATUS_USAGE_LIMITED,
+    ]
+
+
+def test_entry_absent_from_usage_report_is_still_walked(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude"), _entry("claude-ev")])
+
+    def partial_usage_reporter(
+        *, config_path: Path
+    ) -> list[chain_usage.AccountUsageReport]:
+        return [
+            chain_usage.AccountUsageReport(
+                command="claude-ev",
+                weekly_remaining_percent=_HIGH_WEEKLY_REMAINING_PERCENT,
+            )
+        ]
+
+    _install(
+        monkeypatch,
+        config_file,
+        {
+            "claude-ev": _completed("claude-ev", 1, stderr=_A_SIGNATURE),
+            "claude": _completed("claude", 0, stdout="ok"),
+        },
+        weekly_usage_reporter=partial_usage_reporter,
+    )
+    chain_result = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert chain_result.served_command == "claude"
+    assert [each_attempt.command for each_attempt in chain_result.attempts] == [
+        "claude-ev",
+        "claude",
+    ]
+
+
 def test_usage_limited_primary_falls_over_to_second(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:
@@ -170,7 +562,7 @@ def test_timeout_on_primary_does_not_fall_over(
     assert chain_result.attempts[0].status == ATTEMPT_STATUS_TIMEOUT
 
 
-def test_missing_primary_binary_does_not_fall_over(
+def test_missing_primary_binary_falls_through_to_next(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:
     config_file = _write_chain_config(tmp_path, [_entry("claude"), _entry("claude-ev")])
@@ -179,13 +571,21 @@ def test_missing_primary_binary_does_not_fall_over(
         config_file,
         {
             "claude": FileNotFoundError(),
-            "claude-ev": _completed("claude-ev", 0),
+            "claude-ev": _completed("claude-ev", 0, stdout="from-ev"),
         },
     )
     chain_result = runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
-    assert chain_result.served_command is None
-    assert len(chain_result.attempts) == 1
-    assert chain_result.attempts[0].status == ATTEMPT_STATUS_EXECUTABLE_NOT_FOUND
+    assert chain_result.served_command == "claude-ev"
+    assert chain_result.returncode == 0
+    assert chain_result.stdout == "from-ev"
+    assert [each_attempt.command for each_attempt in chain_result.attempts] == [
+        "claude",
+        "claude-ev",
+    ]
+    assert [each_attempt.status for each_attempt in chain_result.attempts] == [
+        ATTEMPT_STATUS_EXECUTABLE_NOT_FOUND,
+        ATTEMPT_STATUS_SERVED,
+    ]
 
 
 def test_missing_fallback_binary_is_skipped_and_walk_continues(
@@ -530,6 +930,9 @@ def test_real_subprocess_capture_replaces_undecodable_bytes(
 ) -> None:
     config_file = _write_chain_config(tmp_path, [_entry(sys.executable)])
     monkeypatch.setattr(runner, "chain_config_path", lambda: config_file)
+    monkeypatch.setattr(
+        runner, "chain_weekly_usage_reporter", _config_order_usage_reporter
+    )
     child_code = 'import sys; sys.stdout.buffer.write(b"ok \\x90 end")'
     chain_result = runner.run_claude(["-c", child_code], timeout_seconds=60)
     assert chain_result.served_command == sys.executable
@@ -542,6 +945,9 @@ def test_real_subprocess_capture_preserves_utf8_text(
 ) -> None:
     config_file = _write_chain_config(tmp_path, [_entry(sys.executable)])
     monkeypatch.setattr(runner, "chain_config_path", lambda: config_file)
+    monkeypatch.setattr(
+        runner, "chain_weekly_usage_reporter", _config_order_usage_reporter
+    )
     child_code = 'import sys; sys.stdout.buffer.write("report ✅ done".encode("utf-8"))'
     chain_result = runner.run_claude(["-c", child_code], timeout_seconds=60)
     assert chain_result.served_command == sys.executable