claude-dev-env 2.2.1 → 2.3.0

package/hooks/blocking/verification_verdict_store.py

@@ -13,6 +13,7 @@ and reading/writing verdict files.
 from __future__ import annotations
 
 import ast
+import datetime
 import hashlib
 import json
 import re
@@ -20,6 +21,7 @@ import subprocess
 import sys
 import time
 from pathlib import Path
+from collections.abc import Mapping
 
 blocking_directory = str(Path(__file__).resolve().parent)
 if blocking_directory not in sys.path:
@@ -45,6 +47,15 @@ from config.verified_commit_constants import (
     ALL_FALLBACK_BASE_REFERENCES,
     EMPTY_SURFACE_GUARD_MESSAGE,
     GIT_TIMEOUT_SECONDS,
+    LEDGER_KEY_ALL_PASS,
+    LEDGER_KEY_BRANCH,
+    LEDGER_KEY_FINDING_CHECK_NAMES,
+    LEDGER_KEY_FINDING_COUNT,
+    LEDGER_KEY_MANIFEST_HASH,
+    LEDGER_KEY_MINTED_FROM_AGENT_ID,
+    LEDGER_KEY_REPO_ROOT,
+    LEDGER_KEY_TIMESTAMP,
+    LOGS_DIRECTORY_NAME,
     MANIFEST_HASH_CLI_FLAG,
     MANIFEST_HASH_FOR_BRANCH_CLI_FLAG,
     MINIMUM_STATUS_FIELD_COUNT,
@@ -65,10 +76,12 @@ from config.verified_commit_constants import (
     VERDICT_DIRECTORY_NAME,
     VERDICT_FENCE_PATTERN,
     VERDICT_FILE_GLOB,
+    VERDICT_FINDING_CHECK_KEY,
     VERDICT_JSON_INDENT,
     VERDICT_KEY_ALL_PASS,
     VERDICT_KEY_FINDINGS,
     VERDICT_KEY_MANIFEST_SHA256,
+    VERIFIER_VERDICTS_JSONL_FILENAME,
     WORKTREE_LIST_BRANCH_PREFIX,
     WORKTREE_LIST_PATH_PREFIX,
 )
@@ -654,6 +667,74 @@ def workflow_verdict_covers_surface(
     return False
 
 
+def _finding_check_names(all_findings: list) -> list[str]:
+    """Collect the ``check`` name from each finding mapping that carries one.
+
+    Args:
+        all_findings: The verifier's findings list (empty when clean).
+
+    Returns:
+        Ordered list of non-empty check name strings; entries without a
+        string ``check`` field are omitted.
+    """
+    all_check_names: list[str] = []
+    for each_finding in all_findings:
+        if not isinstance(each_finding, Mapping):
+            continue
+        check_name = each_finding.get(VERDICT_FINDING_CHECK_KEY)
+        if isinstance(check_name, str) and check_name:
+            all_check_names.append(check_name)
+    return all_check_names
+
+
+def _append_verdict_ledger_row(
+    repo_root: str,
+    bound_manifest_sha256: str,
+    is_all_pass: bool,
+    all_findings: list,
+    minted_from_agent_id: str,
+) -> None:
+    """Append one fail-safe JSONL row for a minted verdict.
+
+    Writes to ``~/.claude/logs/verifier-verdicts.jsonl``. Swallows home
+    resolution and IO errors so a ledger failure never changes the mint.
+
+    Args:
+        repo_root: The repository top-level directory.
+        bound_manifest_sha256: Hash of the surface the verdict covers.
+        is_all_pass: Whether the verifier reported a clean verdict.
+        all_findings: The verifier's findings list (empty when clean).
+        minted_from_agent_id: The subagent invocation id, kept for audit.
+    """
+    try:
+        home_directory = Path.home()
+    except RuntimeError:
+        return
+    try:
+        ledger_path = (
+            home_directory
+            / CLAUDE_HOME_DIRECTORY_NAME
+            / LOGS_DIRECTORY_NAME
+            / VERIFIER_VERDICTS_JSONL_FILENAME
+        )
+        ledger_path.parent.mkdir(parents=True, exist_ok=True)
+        branch_name = _head_branch_name(repo_root)
+        ledger_row = {
+            LEDGER_KEY_TIMESTAMP: datetime.datetime.now(datetime.timezone.utc).isoformat(),
+            LEDGER_KEY_REPO_ROOT: repo_root,
+            LEDGER_KEY_BRANCH: branch_name,
+            LEDGER_KEY_MANIFEST_HASH: bound_manifest_sha256,
+            LEDGER_KEY_ALL_PASS: is_all_pass,
+            LEDGER_KEY_FINDING_COUNT: len(all_findings),
+            LEDGER_KEY_FINDING_CHECK_NAMES: _finding_check_names(all_findings),
+            LEDGER_KEY_MINTED_FROM_AGENT_ID: minted_from_agent_id,
+        }
+        with ledger_path.open("a", encoding="utf-8") as ledger_file:
+            ledger_file.write(json.dumps(ledger_row) + "\n")
+    except OSError:
+        return
+
+
 def write_verdict(
     repo_root: str,
     bound_manifest_sha256: str,
@@ -663,6 +744,9 @@ def write_verdict(
 ) -> Path:
     """Write a verdict file binding a verification outcome to a surface hash.
 
+    Also appends one durable JSONL ledger row under the Claude logs directory.
+    A ledger write failure never changes the mint outcome.
+
     Args:
         repo_root: The repository top-level directory.
         bound_manifest_sha256: Hash of the surface manifest the verdict covers.
@@ -686,6 +770,13 @@ def write_verdict(
     verdict_file.write_text(
         json.dumps(verdict_record, indent=VERDICT_JSON_INDENT), encoding="utf-8"
     )
+    _append_verdict_ledger_row(
+        repo_root,
+        bound_manifest_sha256,
+        is_all_pass,
+        all_findings,
+        minted_from_agent_id,
+    )
     return verdict_file
 
 

package/package.json

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

package/scripts/CLAUDE.md

@@ -6,7 +6,8 @@ Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each s
 
 | File | Purpose |
 |---|---|
-| `claude_chain_runner.py` | Runs a `claude` invocation through a config-driven fallback chain (`~/.claude/claude-chain.json`): the leading binary serves the call, and only a usage-limit failure falls over to the next logged-in binary; usable as an imported module (`run_claude`) or a CLI. Copy `claude-chain.example.json` to `~/.claude/claude-chain.json` and list your binaries in fallback order |
+| `claude_chain_runner.py` | Runs a `claude` invocation through a usage-ranked fallback chain (`~/.claude/claude-chain.json`): probes weekly remaining once via `claude_chain_usage` / the usage-pause OAuth probe, tries the highest-remaining account first, and falls over to the next ranked binary only on a usage-limit failure; usable as an imported module (`run_claude`) or a CLI. Copy `claude-chain.example.json` to `~/.claude/claude-chain.json` and list your account binaries. Optional per-entry `credentials_path` names that account's OAuth credentials file for the usage probe |
+| `claude_chain_usage.py` | Reports remaining weekly usage for every account in `~/.claude/claude-chain.json` via the usage-pause OAuth probe; prints JSON (`accounts` with `weekly_remaining_percent` or null plus `error`); importable `report_chain_weekly_usage` and `rank_accounts_by_weekly_remaining` (highest remaining first, ties keep config order, unmeasurable last). The chain runner consumes this ranking for try order |
 | `gh_artifact_upload.py` | Uploads a file to a repo's durable `artifacts` prerelease under a timestamped asset name and prints the permanent download URL a GitHub post can link |
 | `grok_headless_runner.py` | Runs one worker as headless `grok`: builds argv, mints a unique leader socket, captures streams, kills on timeout with grace, classifies ok/usage_limit/auth_failure/timeout/error; imported by `spawn_grok_batch.py` |
 | `grok_worker_preflight.py` | Soft gate for the headless grok tier: binary on PATH, `grok models` auth, install manifest + role agents, opt-in cached live ping; non-zero exit is fallthrough, not failure |

package/scripts/claude-chain.example.json

@@ -1,8 +1,20 @@
 {
   "chain": [
     { "command": "claude", "extra_args": [] },
-    { "command": "claude-1", "extra_args": [] },
-    { "command": "claude-2", "extra_args": [] },
-    { "command": "claude-3", "extra_args": [] }
+    {
+      "command": "claude-1",
+      "extra_args": [],
+      "credentials_path": "/path/to/account-1/.credentials.json"
+    },
+    {
+      "command": "claude-2",
+      "extra_args": [],
+      "credentials_path": "/path/to/account-2/.credentials.json"
+    },
+    {
+      "command": "claude-3",
+      "extra_args": [],
+      "credentials_path": "/path/to/account-3/.credentials.json"
+    }
   ]
 }

package/scripts/claude_chain_runner.py

@@ -1,23 +1,25 @@
 #!/usr/bin/env python3
-"""Run a ``claude`` invocation through a config-driven fallback chain.
+"""Run a ``claude`` invocation through a usage-ranked fallback chain.
 
 An automation that shells out to a single ``claude -p ...`` fails outright when
 that account hits a usage limit. Other logged-in installs sit idle meanwhile.
-This module runs the leading binary in the chain. It falls over to the next
-binary only on a usage-limit failure. Every other outcome returns to the caller
-unchanged.
+This module probes remaining weekly usage once per call, ranks chain accounts
+highest remaining first, and tries that order. It falls over to the next
+ranked binary only on a usage-limit failure. Every other outcome returns to
+the caller unchanged.
 
 The chain lives in ``~/.claude/claude-chain.json``. Copy the committed
-``claude-chain.example.json`` template there and list your binaries in fallback
-order::
+``claude-chain.example.json`` template there and list your account binaries.
+Try order comes from weekly remaining via ``claude_chain_usage`` (usage-pause
+OAuth probe), not from list position alone::
 
     {"chain": [{"command": "claude", "extra_args": []},
                {"command": "claude-ev", "extra_args": []}]}
 
-A usage-limited primary falls over to the second binary::
+A usage-limited first try falls over to the next ranked binary::
 
-    primary claude     -> exit 1, "usage limit reached"  (falls over)
-    fallback claude-ev -> exit 0                          (served)
+    first try (highest remaining)  -> exit 1, "usage limit reached"  (falls over)
+    next ranked binary             -> exit 0                          (served)
 
 When stdin is piped (not a TTY), the runner reads it once and forwards the
 same text to every chain attempt so a piped ``-p`` charter body reaches each
@@ -33,13 +35,19 @@ Import ``run_claude`` for the outcome object, or run the module as a CLI::
 from __future__ import annotations
 
 import argparse
+import importlib
 import io
 import json
 import subprocess
 import sys
+from collections.abc import Callable, Sequence
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TextIO
+from types import ModuleType
+from typing import Protocol, TextIO
+
+if __name__ == "__main__":
+    sys.modules.setdefault("claude_chain_runner", sys.modules[__name__])
 
 from dev_env_scripts_constants.claude_chain_constants import (
     ALL_USAGE_LIMIT_SIGNATURES,
@@ -53,6 +61,7 @@ from dev_env_scripts_constants.claude_chain_constants import (
     CHAIN_CONFIG_ERROR_EXIT_CODE,
     CHAIN_EXHAUSTED_EXIT_CODE,
     CHAIN_EXHAUSTED_MESSAGE_TEMPLATE,
+    CHAIN_USAGE_MODULE_NAME,
     CLAUDE_HOME_SUBDIRECTORY,
     CLI_ARGUMENTS_SEPARATOR,
     CLI_TIMEOUT_FLAG,
@@ -61,7 +70,9 @@ from dev_env_scripts_constants.claude_chain_constants import (
     CONFIG_CHAIN_KEY,
     CONFIG_CHAIN_NOT_LIST_REASON,
     CONFIG_COMMAND_KEY,
+    CONFIG_CREDENTIALS_PATH_KEY,
     CONFIG_ENTRY_COMMAND_MISSING_REASON,
+    CONFIG_ENTRY_CREDENTIALS_PATH_INVALID_REASON,
     CONFIG_ENTRY_EXTRA_ARGS_INVALID_REASON,
     CONFIG_ENTRY_NOT_OBJECT_REASON,
     CONFIG_EXTRA_ARGS_KEY,
@@ -84,10 +95,16 @@ class ChainConfigurationError(Exception):
 
 @dataclass(frozen=True)
 class ChainEntry:
-    """One binary in the fallback chain and its per-account extra arguments."""
+    """One binary in the fallback chain and its per-account extra arguments.
+
+    ``credentials_path`` is an optional path to that account's OAuth credentials
+    file. The subprocess walk does not pass it; weekly-usage ranking reads it
+    when present.
+    """
 
     command: str
     extra_args: tuple[str, ...]
+    credentials_path: str | None = None
 
 
 @dataclass(frozen=True)
@@ -104,8 +121,8 @@ class ChainInvocationOutcome:
 
     ``served_command`` names the binary whose response is returned. It is
     ``None`` when no binary served the call: every entry was usage-limited or
-    missing, the invocation timed out, or the primary binary was absent. The
-    ``attempts`` trail records every binary tried and how it resolved.
+    missing, or the invocation timed out. The ``attempts`` trail records every
+    binary tried and how it resolved.
     """
 
     served_command: str | None
@@ -115,9 +132,31 @@ class ChainInvocationOutcome:
     attempts: tuple[ChainAttempt, ...]
 
 
+class WeeklyUsageAccountReport(Protocol):
+    """Minimal account-report surface the runner needs for ranking and mapping."""
+
+    command: str
+
+
 chain_subprocess_runner = subprocess.run
 
 
+def _load_chain_usage_module() -> ModuleType:
+    return importlib.import_module(CHAIN_USAGE_MODULE_NAME)
+
+
+def _default_chain_weekly_usage_reporter(
+    *, config_path: Path
+) -> list[WeeklyUsageAccountReport]:
+    usage_module = _load_chain_usage_module()
+    return usage_module.report_chain_weekly_usage(config_path=config_path)
+
+
+chain_weekly_usage_reporter: Callable[..., list[WeeklyUsageAccountReport]] = (
+    _default_chain_weekly_usage_reporter
+)
+
+
 def chain_config_path() -> Path:
     """Return the path to the per-user chain configuration file."""
     return Path.home() / CLAUDE_HOME_SUBDIRECTORY / CONFIG_FILENAME
@@ -141,6 +180,18 @@ def _coerce_extra_args(raw_extra_args: object, config_path: Path) -> tuple[str,
     return tuple(raw_extra_args)
 
 
+def _coerce_credentials_path(
+    raw_credentials_path: object, config_path: Path
+) -> str | None:
+    if raw_credentials_path is None:
+        return None
+    if not isinstance(raw_credentials_path, str) or not raw_credentials_path:
+        raise _invalid_shape_error(
+            config_path, CONFIG_ENTRY_CREDENTIALS_PATH_INVALID_REASON
+        )
+    return raw_credentials_path
+
+
 def _parse_chain_entry(raw_entry: object, config_path: Path) -> ChainEntry:
     if not isinstance(raw_entry, dict):
         raise _invalid_shape_error(config_path, CONFIG_ENTRY_NOT_OBJECT_REASON)
@@ -150,7 +201,14 @@ def _parse_chain_entry(raw_entry: object, config_path: Path) -> ChainEntry:
     extra_args = _coerce_extra_args(
         raw_entry.get(CONFIG_EXTRA_ARGS_KEY, []), config_path
     )
-    return ChainEntry(command=command, extra_args=extra_args)
+    credentials_path = _coerce_credentials_path(
+        raw_entry.get(CONFIG_CREDENTIALS_PATH_KEY), config_path
+    )
+    return ChainEntry(
+        command=command,
+        extra_args=extra_args,
+        credentials_path=credentials_path,
+    )
 
 
 def _parse_chain_entries(parsed_config: object, config_path: Path) -> list[ChainEntry]:
@@ -212,6 +270,33 @@ def _build_invocation(entry: ChainEntry, all_claude_arguments: list[str]) -> lis
     return [entry.command, *all_claude_arguments, *entry.extra_args]
 
 
+def _entries_ranked_by_weekly_remaining(
+    all_entries: list[ChainEntry],
+    all_usage_reports: Sequence[WeeklyUsageAccountReport],
+) -> list[ChainEntry]:
+    usage_module = _load_chain_usage_module()
+    entries_by_command: dict[str, list[ChainEntry]] = {}
+    for each_entry in all_entries:
+        entries_by_command.setdefault(each_entry.command, []).append(each_entry)
+    all_ranked_reports = usage_module.rank_accounts_by_weekly_remaining(
+        list(all_usage_reports)
+    )
+    ranked_entries: list[ChainEntry] = []
+    seen_commands: set[str] = set()
+    for each_report in all_ranked_reports:
+        if each_report.command in seen_commands:
+            continue
+        matched_entries = entries_by_command.get(each_report.command)
+        if matched_entries is None:
+            continue
+        seen_commands.add(each_report.command)
+        ranked_entries.extend(matched_entries)
+    for each_entry in all_entries:
+        if each_entry.command not in seen_commands:
+            ranked_entries.append(each_entry)
+    return ranked_entries
+
+
 def _is_usage_limit_failure(completion: subprocess.CompletedProcess[str]) -> bool:
     combined_text = f"{completion.stdout}{completion.stderr}".lower()
     return any(
@@ -291,21 +376,40 @@ def _classify_completion(
     return _served_outcome(entry.command, completion, all_attempts)
 
 
+def _ranked_entries_or_config_order(
+    all_entries: list[ChainEntry],
+    config_path: Path,
+) -> list[ChainEntry]:
+    try:
+        all_usage_reports = chain_weekly_usage_reporter(config_path=config_path)
+        return _entries_ranked_by_weekly_remaining(
+            all_entries, all_usage_reports
+        )
+    except (ImportError, AttributeError):
+        return list(all_entries)
+
+
 def run_claude(
     all_claude_arguments: list[str],
     *,
     timeout_seconds: int,
     stdin_text: str | None = None,
 ) -> ChainInvocationOutcome:
-    """Run *all_claude_arguments* through the configured fallback chain.
+    """Run *all_claude_arguments* through the usage-ranked fallback chain.
+
+    ::
+
+        highest remaining usage-limited, next ranked ok
+            -> served_command=next ranked, returncode=0
+        first try nonzero without usage-limit signature
+            -> served_command=first try (no fallover)
+        stdin_text set
+            -> same text on every attempt's stdin
 
-    The leading binary serves the call. Only a usage-limit failure (a non-zero
-    exit whose output carries a usage-limit signature) falls over to the next
-    binary. A missing fallback binary is skipped and the walk continues. A
-    timeout, a missing primary binary, or a non-zero exit without a usage-limit
-    signature stops the walk and returns that outcome unchanged. When
-    *stdin_text* is set, that same text is supplied as stdin on every chain
-    attempt.
+    Probes weekly remaining once, ranks highest first, then walks that order.
+    Only a usage-limit failure falls over. Missing binaries are skipped and the
+    walk continues; timeout and other nonzero exits stop. When usage ranking
+    infrastructure fails to load, the walk uses config order instead.
 
     Args:
         all_claude_arguments: Arguments passed after the binary name, such as
@@ -321,11 +425,12 @@ def run_claude(
     Raises:
         ChainConfigurationError: When the chain configuration cannot be loaded.
     """
-    all_entries = load_chain(chain_config_path())
+    config_path = chain_config_path()
+    all_entries = load_chain(config_path)
+    all_ranked_entries = _ranked_entries_or_config_order(all_entries, config_path)
     all_attempts: list[ChainAttempt] = []
     last_usage_limited: subprocess.CompletedProcess[str] | None = None
-    for each_index, each_entry in enumerate(all_entries):
-        is_primary = each_index == 0
+    for each_entry in all_ranked_entries:
         try:
             completion = chain_subprocess_runner(
                 _build_invocation(each_entry, all_claude_arguments),
@@ -346,8 +451,6 @@ def run_claude(
             all_attempts.append(
                 ChainAttempt(each_entry.command, ATTEMPT_STATUS_EXECUTABLE_NOT_FOUND)
             )
-            if is_primary:
-                return _no_process_outcome(all_attempts, None)
             continue
         terminal_outcome = _classify_completion(each_entry, completion, all_attempts)
         if terminal_outcome is not None: