claude-dev-env 2.2.1 → 2.4.0

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:

package/scripts/claude_chain_usage.py

@@ -0,0 +1,346 @@
+#!/usr/bin/env python3
+"""Report remaining weekly usage for every account in the Claude chain.
+
+Loads ``~/.claude/claude-chain.json`` (or a path the caller names), probes each
+entry's weekly utilization through the usage-pause OAuth endpoint, and prints a
+JSON report. Ranking is available as an importable helper; ``run_claude``
+consumes that ranking to choose try order.
+
+::
+
+    python claude_chain_usage.py
+    {"accounts": [
+      {"command": "claude", "weekly_remaining_percent": 58.0},
+      {"command": "claude-ev", "weekly_remaining_percent": null, "error": "..."}
+    ]}
+"""
+
+from __future__ import annotations
+
+import argparse
+import http.client
+import importlib.util
+import json
+import sys
+import urllib.error
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from types import ModuleType
+
+from dev_env_scripts_constants.claude_chain_constants import CHAIN_CONFIG_ERROR_EXIT_CODE
+from dev_env_scripts_constants.claude_chain_usage_constants import (
+    CLI_CONFIG_PATH_FLAG,
+    FULL_WEEKLY_PERCENT,
+    JSON_ACCOUNTS_KEY,
+    JSON_COMMAND_KEY,
+    JSON_ERROR_KEY,
+    JSON_WEEKLY_REMAINING_PERCENT_KEY,
+    NO_ACCESS_TOKEN_ERROR_TEMPLATE,
+    RESOLVE_USAGE_WINDOW_FILENAME,
+    RESOLVE_USAGE_WINDOW_MISSING_ERROR_TEMPLATE,
+    RESOLVE_USAGE_WINDOW_MODULE_NAME,
+    USAGE_PAUSE_SCRIPTS_DIRECTORY_NAME,
+    USAGE_PAUSE_SKILL_DIRECTORY_NAME,
+    USAGE_PAUSE_SKILL_NAME,
+    USAGE_PROBE_FAILED_ERROR_TEMPLATE,
+    WEEKLY_UTILIZATION_MISSING_ERROR,
+)
+
+import claude_chain_runner as chain_runner
+
+WeeklyUtilizationProbe = Callable[[Path], float]
+
+
+class WeeklyUtilizationProbeError(Exception):
+    """Raised when the weekly_utilization_probe cannot measure one account."""
+
+
+@dataclass(frozen=True)
+class AccountUsageReport:
+    """One chain account's remaining weekly usage, or the reason it is unknown."""
+
+    command: str
+    weekly_remaining_percent: float | None
+    error: str | None = None
+
+
+def _default_credentials_path() -> Path:
+    usage_window_resolver = _load_resolve_usage_window_module()
+    return Path.home().joinpath(
+        *usage_window_resolver.ALL_CREDENTIALS_RELATIVE_PATH_PARTS
+    )
+
+
+def _credentials_path_for_entry(entry: chain_runner.ChainEntry) -> Path:
+    if entry.credentials_path is None:
+        return _default_credentials_path()
+    return Path(entry.credentials_path).expanduser()
+
+
+def _usage_pause_scripts_directory() -> Path:
+    package_root = Path(__file__).resolve().parent.parent
+    return (
+        package_root
+        / USAGE_PAUSE_SKILL_DIRECTORY_NAME
+        / USAGE_PAUSE_SKILL_NAME
+        / USAGE_PAUSE_SCRIPTS_DIRECTORY_NAME
+    )
+
+
+def _discard_sys_path_entry(path_text: str) -> None:
+    if path_text in sys.path:
+        sys.path.remove(path_text)
+
+
+def _load_resolve_usage_window_module() -> ModuleType:
+    already_loaded = sys.modules.get(RESOLVE_USAGE_WINDOW_MODULE_NAME)
+    if already_loaded is not None:
+        return already_loaded
+    scripts_directory = _usage_pause_scripts_directory()
+    module_path = scripts_directory / RESOLVE_USAGE_WINDOW_FILENAME
+    if not module_path.is_file():
+        raise WeeklyUtilizationProbeError(
+            RESOLVE_USAGE_WINDOW_MISSING_ERROR_TEMPLATE.format(
+                module_path=module_path
+            )
+        )
+    scripts_directory_text = str(scripts_directory)
+    was_path_inserted = False
+    if scripts_directory_text not in sys.path:
+        sys.path.insert(0, scripts_directory_text)
+        was_path_inserted = True
+    is_module_ready = False
+    try:
+        module_specification = importlib.util.spec_from_file_location(
+            RESOLVE_USAGE_WINDOW_MODULE_NAME, module_path
+        )
+        if module_specification is None or module_specification.loader is None:
+            raise WeeklyUtilizationProbeError(
+                RESOLVE_USAGE_WINDOW_MISSING_ERROR_TEMPLATE.format(
+                    module_path=module_path
+                )
+            )
+        loaded_module = importlib.util.module_from_spec(module_specification)
+        sys.modules[RESOLVE_USAGE_WINDOW_MODULE_NAME] = loaded_module
+        module_specification.loader.exec_module(loaded_module)
+        is_module_ready = True
+    finally:
+        if not is_module_ready:
+            sys.modules.pop(RESOLVE_USAGE_WINDOW_MODULE_NAME, None)
+        if was_path_inserted:
+            _discard_sys_path_entry(scripts_directory_text)
+    return loaded_module
+
+
+def _probe_weekly_utilization(credentials_path: Path) -> float:
+    usage_window_resolver = _load_resolve_usage_window_module()
+    now = datetime.now().astimezone()
+    try:
+        access_token = usage_window_resolver.read_oauth_access_token(
+            credentials_path, now
+        )
+        if access_token is None:
+            raise WeeklyUtilizationProbeError(
+                NO_ACCESS_TOKEN_ERROR_TEMPLATE.format(credentials_path=credentials_path)
+            )
+        usage_payload = usage_window_resolver._fetch_usage_payload(access_token)
+    except WeeklyUtilizationProbeError:
+        raise
+    except (
+        urllib.error.URLError,
+        http.client.HTTPException,
+        TimeoutError,
+        OSError,
+        ValueError,
+    ) as probe_error:
+        raise WeeklyUtilizationProbeError(
+            USAGE_PROBE_FAILED_ERROR_TEMPLATE.format(error=probe_error)
+        ) from probe_error
+    usage_windows = usage_window_resolver.extract_usage_windows(usage_payload)
+    if usage_windows.weekly_utilization is None:
+        raise WeeklyUtilizationProbeError(WEEKLY_UTILIZATION_MISSING_ERROR)
+    return float(usage_windows.weekly_utilization)
+
+
+weekly_utilization_probe: WeeklyUtilizationProbe = _probe_weekly_utilization
+
+
+def weekly_remaining_from_utilization(weekly_utilization: float) -> float:
+    """Convert weekly utilization percent into remaining weekly percent.
+
+    ::
+
+        weekly_remaining_from_utilization(42.0) -> 58.0
+        weekly_remaining_from_utilization(9.0)  -> 91.0
+
+    Args:
+        weekly_utilization: Used weekly capacity on the 0–100 scale.
+
+    Returns:
+        Remaining weekly capacity on the same 0–100 scale.
+    """
+    return FULL_WEEKLY_PERCENT - weekly_utilization
+
+
+def _report_for_entry(
+    entry: chain_runner.ChainEntry,
+    active_probe: WeeklyUtilizationProbe,
+) -> AccountUsageReport:
+    try:
+        credentials_path = _credentials_path_for_entry(entry)
+        weekly_utilization = active_probe(credentials_path)
+    except (WeeklyUtilizationProbeError, ImportError, AttributeError) as probe_error:
+        return AccountUsageReport(
+            command=entry.command,
+            weekly_remaining_percent=None,
+            error=str(probe_error),
+        )
+    return AccountUsageReport(
+        command=entry.command,
+        weekly_remaining_percent=weekly_remaining_from_utilization(
+            weekly_utilization
+        ),
+    )
+
+
+def report_chain_weekly_usage(*, config_path: Path) -> list[AccountUsageReport]:
+    """Report remaining weekly usage for every account in the chain config.
+
+    ::
+
+        report_chain_weekly_usage(config_path=Path("chain.json"))
+        -> [AccountUsageReport("claude", 58.0), ...]
+
+    Uses the module-level ``weekly_utilization_probe`` (tests rebind it).
+
+    Args:
+        config_path: Chain configuration file to load.
+
+    Returns:
+        One report per chain entry, in config order.
+
+    Raises:
+        ChainConfigurationError: When the chain configuration cannot be loaded.
+    """
+    all_entries = chain_runner.load_chain(config_path)
+    return [
+        _report_for_entry(each_entry, weekly_utilization_probe)
+        for each_entry in all_entries
+    ]
+
+
+def _nulls_last_remaining_rank(report: AccountUsageReport) -> tuple[int, float]:
+    if report.weekly_remaining_percent is None:
+        return (1, 0.0)
+    return (0, -report.weekly_remaining_percent)
+
+
+def rank_accounts_by_weekly_remaining(
+    all_reports: list[AccountUsageReport],
+) -> list[AccountUsageReport]:
+    """Order reports by remaining weekly usage, highest first.
+
+    ::
+
+        [40%, 70%, null, 70%] -> [70% (earlier), 70% (later), 40%, null]
+
+    Ties keep config order. Unmeasurable accounts (null remaining) sort last.
+
+    Args:
+        all_reports: Reports in chain-config order.
+
+    Returns:
+        A new list ordered by remaining weekly percent descending.
+    """
+    return sorted(all_reports, key=_nulls_last_remaining_rank)
+
+
+def _account_report_to_json_mapping(
+    report: AccountUsageReport,
+) -> dict[str, str | float | None]:
+    if report.weekly_remaining_percent is None:
+        return {
+            JSON_COMMAND_KEY: report.command,
+            JSON_WEEKLY_REMAINING_PERCENT_KEY: None,
+            JSON_ERROR_KEY: report.error,
+        }
+    return {
+        JSON_COMMAND_KEY: report.command,
+        JSON_WEEKLY_REMAINING_PERCENT_KEY: report.weekly_remaining_percent,
+    }
+
+
+def reports_to_json_payload(
+    all_reports: list[AccountUsageReport],
+) -> dict[str, list[dict[str, str | float | None]]]:
+    """Build the CLI JSON payload for a list of account reports.
+
+    ::
+
+        reports_to_json_payload([AccountUsageReport("claude", 58.0)])
+        -> {"accounts": [{"command": "claude", "weekly_remaining_percent": 58.0}]}
+
+    Args:
+        all_reports: Reports in the order they should appear in the payload.
+
+    Returns:
+        The ``{"accounts": [...]}`` envelope.
+    """
+    return {
+        JSON_ACCOUNTS_KEY: [
+            _account_report_to_json_mapping(each_report)
+            for each_report in all_reports
+        ]
+    }
+
+
+def _build_argument_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Report remaining weekly usage for every account in the Claude chain."
+        )
+    )
+    parser.add_argument(
+        CLI_CONFIG_PATH_FLAG,
+        dest="config_path",
+        default=None,
+        help="Path to claude-chain.json; defaults to the per-user chain config.",
+    )
+    return parser
+
+
+def main(all_command_arguments: list[str]) -> int:
+    """Probe the chain and print the weekly-usage JSON report on stdout.
+
+    ::
+
+        main(["--config-path", "chain.json"]) -> 0  # JSON on stdout
+        main(["--config-path", "missing.json"]) -> 3  # error on stderr
+
+    Args:
+        all_command_arguments: The argument vector after the program name.
+
+    Returns:
+        Zero on success, or the chain-config error exit code when the config
+        cannot be loaded.
+    """
+    parser = _build_argument_parser()
+    parsed_arguments = parser.parse_args(all_command_arguments)
+    resolved_config_path = (
+        Path(parsed_arguments.config_path)
+        if parsed_arguments.config_path is not None
+        else chain_runner.chain_config_path()
+    )
+    try:
+        all_reports = report_chain_weekly_usage(config_path=resolved_config_path)
+    except chain_runner.ChainConfigurationError as configuration_error:
+        print(str(configuration_error), file=sys.stderr)
+        return CHAIN_CONFIG_ERROR_EXIT_CODE
+    print(json.dumps(reports_to_json_payload(all_reports), ensure_ascii=True))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/codec_forwarding_test_support.py

@@ -0,0 +1,83 @@
+"""Shared fixtures for text-codec keyword-forwarding behavioral tests."""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Sequence
+
+import claude_chain_runner as chain_runner
+import pytest
+from claude_chain_runner import ChainAttempt, ChainInvocationOutcome
+
+FIXTURE_ENCODING_KEYWORD_NAME = "encoding"
+FIXTURE_ERRORS_KEYWORD_NAME = "errors"
+FIXTURE_CHAIN_ENCODING = "utf-8"
+FIXTURE_CHAIN_ERRORS = "replace"
+FIXTURE_SERVED_COMMAND = "claude"
+
+
+def build_served_outcome(*, chain_stdout: str) -> ChainInvocationOutcome:
+    return ChainInvocationOutcome(
+        served_command=FIXTURE_SERVED_COMMAND,
+        returncode=0,
+        stdout=chain_stdout,
+        stderr="",
+        attempts=(ChainAttempt(command=FIXTURE_SERVED_COMMAND, status="served"),),
+    )
+
+
+def build_recording_runner(
+    all_observed_runner_keywords: dict[str, object],
+    *,
+    chain_stdout: str,
+) -> object:
+    def _recording_runner(
+        all_invocation_tokens: Sequence[str],
+        *all_positionals: object,
+        **all_keywords: object,
+    ) -> subprocess.CompletedProcess[str]:
+        del all_positionals
+        all_observed_runner_keywords.update(all_keywords)
+        return subprocess.CompletedProcess(
+            args=list(all_invocation_tokens),
+            returncode=0,
+            stdout=chain_stdout,
+            stderr="",
+        )
+
+    return _recording_runner
+
+
+def install_codec_seams(
+    monkeypatch: pytest.MonkeyPatch,
+    *,
+    all_chain_codec_keywords: dict[str, str],
+    chain_stdout: str,
+    runner_host: object,
+    runner_attribute_name: str,
+) -> dict[str, object]:
+    all_observed_runner_keywords: dict[str, object] = {}
+
+    def _fake_claude(
+        all_claude_arguments: list[str], *, timeout_seconds: int
+    ) -> ChainInvocationOutcome:
+        chain_runner.chain_subprocess_runner(
+            [FIXTURE_SERVED_COMMAND, *all_claude_arguments],
+            capture_output=True,
+            text=True,
+            timeout=timeout_seconds,
+            check=False,
+            **all_chain_codec_keywords,
+        )
+        return build_served_outcome(chain_stdout=chain_stdout)
+
+    monkeypatch.setattr(
+        chain_runner,
+        "chain_subprocess_runner",
+        build_recording_runner(
+            all_observed_runner_keywords,
+            chain_stdout=chain_stdout,
+        ),
+    )
+    monkeypatch.setattr(runner_host, runner_attribute_name, _fake_claude)
+    return all_observed_runner_keywords