claude-dev-env 1.89.0 → 1.92.0

package/hooks/validators/test_run_all_validators_pretooluse.py

@@ -0,0 +1,102 @@
+"""Behavioral tests for the run_all_validators PreToolUse gate mode.
+
+The gate mode validates the proposed post-edit content of the single file a
+Write, Edit, or MultiEdit would produce and emits a PreToolUse deny decision
+when that content violates a validator, rather than grading the whole branch.
+"""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from .run_all_validators import main, run_validators_entrypoint_subprocess
+
+CLEAN_PYTHON_SOURCE = (
+    "def add_two_numbers(first_number: int, second_number: int) -> int:\n"
+    "    return first_number + second_number\n"
+)
+VIOLATING_PYTHON_SOURCE = (
+    "def calculate_total_price(unit_price: int, quantity: int) -> int:\n"
+    "    return unit_price * quantity * 199 * 42\n"
+)
+
+
+def run_gate(payload: dict[str, object]) -> "subprocess.CompletedProcess[str]":
+    return run_validators_entrypoint_subprocess(["--pre-tool-use"], stdin_text=json.dumps(payload))
+
+
+class TestPreToolUseGate:
+    def test_write_with_violating_content_denies(self) -> None:
+        completed = run_gate(
+            {
+                "tool_name": "Write",
+                "tool_input": {
+                    "file_path": "calculate.py",
+                    "content": VIOLATING_PYTHON_SOURCE,
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert '"permissionDecision": "deny"' in completed.stdout
+        assert "Magic Values" in completed.stdout
+
+    def test_write_with_clean_content_allows(self) -> None:
+        completed = run_gate(
+            {
+                "tool_name": "Write",
+                "tool_input": {
+                    "file_path": "add.py",
+                    "content": CLEAN_PYTHON_SOURCE,
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert "deny" not in completed.stdout
+
+    def test_edit_validates_reconstructed_post_edit_content(self, tmp_path: Path) -> None:
+        target_file = tmp_path / "calculate.py"
+        target_file.write_text(CLEAN_PYTHON_SOURCE, encoding="utf-8")
+        completed = run_gate(
+            {
+                "tool_name": "Edit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "old_string": "    return first_number + second_number\n",
+                    "new_string": "    return first_number + second_number + 199 * 42\n",
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert '"permissionDecision": "deny"' in completed.stdout
+
+    def test_unparseable_payload_exits_silently(self) -> None:
+        completed = run_validators_entrypoint_subprocess(
+            ["--pre-tool-use"], stdin_text="not json at all"
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert "deny" not in completed.stdout
+
+
+class TestCliModeRegression:
+    def test_cli_mode_reports_violations_and_exits_one(
+        self, tmp_path: Path, capsys: pytest.CaptureFixture[str]
+    ) -> None:
+        violating_file = tmp_path / "calculate.py"
+        violating_file.write_text(VIOLATING_PYTHON_SOURCE, encoding="utf-8")
+        with patch(
+            "validators.run_all_validators.get_changed_files",
+            return_value=[violating_file],
+        ):
+            original_argv = sys.argv
+            try:
+                sys.argv = ["run_all_validators.py"]
+                exit_code = main()
+            finally:
+                sys.argv = original_argv
+        captured = capsys.readouterr()
+        assert exit_code == 1
+        assert "PRE-PUSH VALIDATOR RESULTS" in captured.out

package/package.json

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

package/rules/CLAUDE.md

@@ -17,6 +17,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | `conservative-action.md` | Research and recommend when intent is ambiguous; act only on explicit request |
 | `context7.md` | Use Context7 MCP to fetch current library docs; always prefer live docs over built-in knowledge |
 | `docstring-prose-matches-implementation.md` | Prose enumerations in docstrings cover every behavior the body applies |
+| `durable-post-artifacts.md` | GitHub post bodies never reference volatile scratch paths; text embeds inline and binary artifacts upload to the `artifacts` release with the permanent URL linked |
 | `explore-thoroughly.md` | Read relevant files and map existing patterns before proposing a change |
 | `file-global-constants.md` | File-global constants need at least two same-file references; otherwise move value to `config/` |
 | `gh-body-file.md` | Use `--body-file` with a temp file for all `gh` commands carrying markdown body content |
@@ -24,6 +25,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | `git-workflow.md` | PR workflow: always create as draft, one commit per review stage, never commit working docs or images |
 | `hook-prose-matches-detector.md` | Hook prose descriptions match what the hook actually detects |
 | `long-horizon-autonomy.md` | Autonomous-run behaviors: act on what you have, do not end on a promise, delegate and keep working |
+| `nas-ssh-invocation.md` | Reach the NAS at `192.168.1.100` through the `System32/OpenSSH` binary with `-o BatchMode=yes`; bare `ssh`/`scp`/`sftp` stalls on an interactive password prompt |
 | `no-cross-skill-duplicate-helpers.md` | No duplicating shared helpers across skills; use `_shared/` |
 | `no-historical-clutter.md` | Documentation describes current state only; no historical or transitional language |
 | `no-inline-destructive-literals.md` | No destructive-command literals in Bash tool command strings, even as data |
@@ -36,6 +38,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | `plain-illustrative-docstrings.md` | Public docstring narrative reads plainly and shows behavior with a diagram block (a `::` example or a doctest), painting a concrete scene a general developer follows on first read; a run-on backstop hook, a prose-wall backstop hook, and Category O9 audit enforce it |
 | `plain-language.md` | Everyday words, short active sentences, lead with the answer |
 | `prompt-workflow-context-controls.md` | Keep prompt-workflow instruction layers small and stable; load heavy skills on demand |
+| `proof-of-work-pr-comments.md` | Every PR carries one five-part proof-of-work comment before it leaves draft; the `pr_description_enforcer` hook audits proof-shaped comments and gates `gh pr ready` |
 | `re-stage-before-commit.md` | Stage the files edited this session before `git commit`; the session edit stage gate denies a commit that leaves a tracked session edit unstaged, with `-a`, a pathspec, a preceding `git add`, and `# partial-commit` as escapes |
 | `research-mode.md` | Three anti-hallucination constraints: say "I don't know", verify with citations, quote for factual grounding |
 | `right-sized-engineering.md` | Simple over clever; functions over classes; concrete over abstract |

package/rules/durable-post-artifacts.md

@@ -0,0 +1,35 @@
+# Durable Post Artifacts
+
+**When this applies:** Any GitHub post that lives on the server — an issue, a pull request, a comment, or a review — created through `gh` (`gh pr create/comment/edit/review`, `gh issue create/comment/edit`) or a GitHub MCP post tool.
+
+## Rule
+
+A post lives forever. Job scratch directories, worktrees, and system temp folders do not — they are cleaned soon after the run that made them. So a post must never point at a path in that scratch. The moment the directory is cleaned, the reference breaks and the reader is left with a dead path.
+
+Handle the two kinds of content differently:
+
+- **Text data** (logs, tables, diffs, stack traces): paste the actual text inline in the post body. Do not link a scratch file that holds it.
+- **Binary artifacts** (images, screenshots, archives): upload the file to the repository's durable `artifacts` release and link the permanent URL. Use the helper:
+
+  ```
+  python3 ~/.claude/scripts/gh_artifact_upload.py <file-path> <owner/repo>
+  ```
+
+  It ensures the repository has a prerelease tagged `artifacts`, uploads the file under a `YYYYMMDD_HHMMSS_<name>` asset name, and prints the permanent download URL. Put that URL in the post.
+
+## Volatile paths that must not appear in a post body
+
+- A job scratch directory (`.claude-editor/jobs/`)
+- A worktree (`.claude/worktrees/`)
+- A system temp location (`AppData\Local\Temp`, `%TEMP%`, `$env:TEMP`, `/tmp/`)
+- The job scratch environment variable (`$CLAUDE_JOB_DIR`)
+
+Both slash directions count.
+
+## Enforcement
+
+The `volatile_path_in_post_blocker` PreToolUse hook reads the body of each `gh` post command and each GitHub MCP post call, scans it for these markers, and blocks the post when it finds one. For a `--body-file`, the hook reads the file and scans its contents, so writing the body to a temp file and passing it with `--body-file` stays allowed — what the hook rejects is a volatile path inside the text that gets posted.
+
+## Why
+
+A comment that cites an artifact under a job's tmp directory reads fine the moment it is posted and breaks a few minutes later, once the job is cleaned. Embedding text inline and linking binary artifacts to a durable release keeps every post readable for as long as it exists.

package/rules/nas-ssh-invocation.md

@@ -0,0 +1,21 @@
+# NAS SSH Invocation Policy
+
+**When this applies:** Any `ssh`, `scp`, or `sftp` command against the NAS at `192.168.1.100`.
+
+## Rule
+
+Reach the NAS through the Windows OpenSSH binary with batch mode on. Git Bash's MSYS `ssh` reads `~/.ssh/id_ed25519` as world-readable through its ACL mapping, rejects the key as bad permissions, offers no key, and falls back to an interactive password prompt. In an unattended session no one answers that prompt, so the session hangs. The `System32/OpenSSH` binary authenticates the same key without a prompt.
+
+Use this form for every NAS ssh command:
+
+```
+"/c/Windows/System32/OpenSSH/ssh.exe" -o BatchMode=yes -o ConnectTimeout=10 -p 9222 jon@192.168.1.100 "<cmd>"
+```
+
+`scp` and `sftp` take the matching `System32/OpenSSH` binary, `-o BatchMode=yes`, and port `9222` (`-P` for `scp`).
+
+`-o BatchMode=yes` is required, not optional: it turns a key-authentication failure into a loud non-zero exit rather than a silent password prompt, so an auth regression surfaces as an error you can read.
+
+## Enforcement
+
+`nas_ssh_binary_enforcer.py` (PreToolUse on Bash) denies a bare `ssh`/`scp`/`sftp` command word aimed at `192.168.1.100` and points at the full-binary form. It also denies the full `System32/OpenSSH` binary to that host when the command omits `-o BatchMode=yes`. Commands to any other host, and commands that mention the address without an ssh-family command word, pass.

package/rules/proof-of-work-pr-comments.md

@@ -0,0 +1,26 @@
+# Proof-of-Work PR Comments
+
+**When this applies:** Every pull request. One comment on the PR carries the proof of the work — posted after `gh pr create` or after a material new commit, and always before the PR leaves draft.
+
+## The standard
+
+A proof comment has five parts:
+
+1. **The exact commands run on real data.** A fenced code block showing the command(s) that produced the artifact — not test output alone.
+2. **Measured outcomes.** Numbers read from the produced artifact — counts, dimensions, hashes, byte sizes, rankings — as a table or a bullet list of facts.
+3. **Plan linkage.** One sentence naming the parent issue or phase the PR advances, with the issue reference (for example: "Advances phase 2 of issue #12").
+4. **Visual evidence for values a human cannot read at a glance.** When the change is visual (the diff touches images, HTML, CSS, or hex color values), embed an image: hex colors as inline swatch images (`![](https://placehold.co/20x20/RRGGBB/RRGGBB.png)`), coordinates as marked-up screenshots, size changes as before/after pairs. A wall of raw values fails the standard even when every value is correct.
+5. **Honest gaps.** State plainly what the offline proof cannot show, and what covers that gap.
+
+## Enforcement
+
+The `pr_description_enforcer` hook enforces the standard at two points:
+
+- **On `gh pr comment`:** a comment body whose heading names proof or verification is audited for the five parts. The audit looks for a fenced code block with content, a table row or bullet line carrying a number, a line pairing an issue reference (`#123`) with a linkage word (issue, phase, plan, parent, advances, milestone, part of), an image embed when the PR diff is visual, and a gap phrase (gap, limitation, cannot, does not show, not shown, unverified, not covered). The block message names each missing part.
+- **On `gh pr ready`:** the hook reads the PR's comments and blocks readying while no comment passes the audit. `gh pr ready --undo` returns a PR to draft and is never blocked.
+
+A `gh` failure (network, auth, missing executable) never blocks — the gate fails open on tooling problems, and the comment audit skips bodies it cannot read.
+
+## Why
+
+A PR body says what changed; the proof comment shows that it worked. Real command output, measured numbers, and a rendered image let a reviewer check the claim in seconds, with no need to re-run the work. Stating the gaps keeps the proof honest: the reviewer knows exactly what still rests on trust and where that is covered. Gating draft-to-ready makes the comment land before review starts, on every machine, whatever the session's habits.

package/scripts/CLAUDE.md

@@ -6,6 +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 |
+| `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 |
 | `setup_project_paths.py` | One-time bootstrap: discovers git repos via `es.exe` (Everything) and writes `~/.claude/project-paths.json`; never hardcodes scan roots |
 | `sweep_empty_dirs.py` | Deletes empty directories older than a configurable age under a given root; runs once (`--once`) or in continuous-watch mode |
 | `sync_to_cursor.py` | Entry point for syncing Claude rules to Cursor `.mdc` files; delegates to the `sync_to_cursor/` package |

package/scripts/claude-chain.example.json

@@ -0,0 +1,8 @@
+{
+  "chain": [
+    { "command": "claude", "extra_args": [] },
+    { "command": "claude-1", "extra_args": [] },
+    { "command": "claude-2", "extra_args": [] },
+    { "command": "claude-3", "extra_args": [] }
+  ]
+}

package/scripts/claude_chain_runner.py

@@ -0,0 +1,400 @@
+#!/usr/bin/env python3
+"""Run a ``claude`` invocation through a config-driven 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.
+
+The chain lives in ``~/.claude/claude-chain.json``. Copy the committed
+``claude-chain.example.json`` template there and list your binaries in fallback
+order::
+
+    {"chain": [{"command": "claude", "extra_args": []},
+               {"command": "claude-ev", "extra_args": []}]}
+
+A usage-limited primary falls over to the second binary::
+
+    primary claude     -> exit 1, "usage limit reached"  (falls over)
+    fallback claude-ev -> exit 0                          (served)
+
+Import ``run_claude`` for the outcome object, or run the module as a CLI::
+
+    python claude_chain_runner.py [--timeout-seconds N] -- <claude args...>
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from dev_env_scripts_constants.claude_chain_constants import (
+    ALL_USAGE_LIMIT_SIGNATURES,
+    ATTEMPT_STATUS_EXECUTABLE_NOT_FOUND,
+    ATTEMPT_STATUS_NONZERO_EXIT,
+    ATTEMPT_STATUS_SERVED,
+    ATTEMPT_STATUS_TIMEOUT,
+    ATTEMPT_STATUS_USAGE_LIMITED,
+    ATTEMPT_SUMMARY_ENTRY_TEMPLATE,
+    ATTEMPT_SUMMARY_JOIN_SEPARATOR,
+    CHAIN_CONFIG_ERROR_EXIT_CODE,
+    CHAIN_EXHAUSTED_EXIT_CODE,
+    CHAIN_EXHAUSTED_MESSAGE_TEMPLATE,
+    CLAUDE_HOME_SUBDIRECTORY,
+    CLI_ARGUMENTS_SEPARATOR,
+    CLI_TIMEOUT_FLAG,
+    CONFIG_CHAIN_EMPTY_REASON,
+    CONFIG_CHAIN_KEY,
+    CONFIG_CHAIN_NOT_LIST_REASON,
+    CONFIG_COMMAND_KEY,
+    CONFIG_ENTRY_COMMAND_MISSING_REASON,
+    CONFIG_ENTRY_EXTRA_ARGS_INVALID_REASON,
+    CONFIG_ENTRY_NOT_OBJECT_REASON,
+    CONFIG_EXTRA_ARGS_KEY,
+    CONFIG_FILENAME,
+    CONFIG_INVALID_SHAPE_MESSAGE_TEMPLATE,
+    CONFIG_MALFORMED_MESSAGE_TEMPLATE,
+    CONFIG_MISSING_MESSAGE_TEMPLATE,
+    CONFIG_NOT_OBJECT_REASON,
+    CONFIG_UNREADABLE_MESSAGE_TEMPLATE,
+    DEFAULT_TIMEOUT_SECONDS,
+    EXAMPLE_CONFIG_FILENAME,
+    NO_COMPLETED_PROCESS_RETURN_CODE,
+    UTF8_ENCODING,
+)
+
+
+class ChainConfigurationError(Exception):
+    """Raised when the chain configuration is missing, unreadable, or malformed."""
+
+
+@dataclass(frozen=True)
+class ChainEntry:
+    """One binary in the fallback chain and its per-account extra arguments."""
+
+    command: str
+    extra_args: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class ChainAttempt:
+    """Record of one binary invocation and how it resolved."""
+
+    command: str
+    status: str
+
+
+@dataclass(frozen=True)
+class ChainInvocationOutcome:
+    """Outcome of walking the chain for one call.
+
+    ``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.
+    """
+
+    served_command: str | None
+    returncode: int
+    stdout: str
+    stderr: str
+    attempts: tuple[ChainAttempt, ...]
+
+
+chain_subprocess_runner = subprocess.run
+
+
+def chain_config_path() -> Path:
+    """Return the path to the per-user chain configuration file."""
+    return Path.home() / CLAUDE_HOME_SUBDIRECTORY / CONFIG_FILENAME
+
+
+def _invalid_shape_error(config_path: Path, reason: str) -> ChainConfigurationError:
+    return ChainConfigurationError(
+        CONFIG_INVALID_SHAPE_MESSAGE_TEMPLATE.format(
+            config_path=config_path,
+            reason=reason,
+            example_filename=EXAMPLE_CONFIG_FILENAME,
+        )
+    )
+
+
+def _coerce_extra_args(raw_extra_args: object, config_path: Path) -> tuple[str, ...]:
+    if not isinstance(raw_extra_args, list) or not all(
+        isinstance(each_argument, str) for each_argument in raw_extra_args
+    ):
+        raise _invalid_shape_error(config_path, CONFIG_ENTRY_EXTRA_ARGS_INVALID_REASON)
+    return tuple(raw_extra_args)
+
+
+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)
+    command = raw_entry.get(CONFIG_COMMAND_KEY)
+    if not isinstance(command, str) or not command:
+        raise _invalid_shape_error(config_path, CONFIG_ENTRY_COMMAND_MISSING_REASON)
+    extra_args = _coerce_extra_args(
+        raw_entry.get(CONFIG_EXTRA_ARGS_KEY, []), config_path
+    )
+    return ChainEntry(command=command, extra_args=extra_args)
+
+
+def _parse_chain_entries(parsed_config: object, config_path: Path) -> list[ChainEntry]:
+    if not isinstance(parsed_config, dict):
+        raise _invalid_shape_error(config_path, CONFIG_NOT_OBJECT_REASON)
+    raw_chain = parsed_config.get(CONFIG_CHAIN_KEY)
+    if not isinstance(raw_chain, list):
+        raise _invalid_shape_error(config_path, CONFIG_CHAIN_NOT_LIST_REASON)
+    if not raw_chain:
+        raise _invalid_shape_error(config_path, CONFIG_CHAIN_EMPTY_REASON)
+    return [
+        _parse_chain_entry(each_raw_entry, config_path) for each_raw_entry in raw_chain
+    ]
+
+
+def load_chain(config_path: Path) -> list[ChainEntry]:
+    """Load the ordered fallback chain from *config_path*.
+
+    Args:
+        config_path: Path to the chain configuration JSON file.
+
+    Returns:
+        The ordered list of chain entries the file declares.
+
+    Raises:
+        ChainConfigurationError: When the file is absent, unreadable, not valid
+            JSON, or does not match the expected shape.
+    """
+    if not config_path.is_file():
+        raise ChainConfigurationError(
+            CONFIG_MISSING_MESSAGE_TEMPLATE.format(
+                config_path=config_path, example_filename=EXAMPLE_CONFIG_FILENAME
+            )
+        )
+    try:
+        raw_text = config_path.read_text(encoding=UTF8_ENCODING)
+    except OSError as read_error:
+        raise ChainConfigurationError(
+            CONFIG_UNREADABLE_MESSAGE_TEMPLATE.format(
+                config_path=config_path,
+                error=read_error,
+                example_filename=EXAMPLE_CONFIG_FILENAME,
+            )
+        ) from read_error
+    try:
+        parsed_config = json.loads(raw_text)
+    except json.JSONDecodeError as decode_error:
+        raise ChainConfigurationError(
+            CONFIG_MALFORMED_MESSAGE_TEMPLATE.format(
+                config_path=config_path,
+                error=decode_error,
+                example_filename=EXAMPLE_CONFIG_FILENAME,
+            )
+        ) from decode_error
+    return _parse_chain_entries(parsed_config, config_path)
+
+
+def _build_invocation(entry: ChainEntry, all_claude_arguments: list[str]) -> list[str]:
+    return [entry.command, *all_claude_arguments, *entry.extra_args]
+
+
+def _is_usage_limit_failure(completion: subprocess.CompletedProcess[str]) -> bool:
+    combined_text = f"{completion.stdout}{completion.stderr}".lower()
+    return any(
+        each_signature in combined_text for each_signature in ALL_USAGE_LIMIT_SIGNATURES
+    )
+
+
+def _served_outcome(
+    served_command: str,
+    completion: subprocess.CompletedProcess[str],
+    all_attempts: list[ChainAttempt],
+) -> ChainInvocationOutcome:
+    return ChainInvocationOutcome(
+        served_command=served_command,
+        returncode=completion.returncode,
+        stdout=completion.stdout,
+        stderr=completion.stderr,
+        attempts=tuple(all_attempts),
+    )
+
+
+def _timeout_streams(
+    timeout_error: subprocess.TimeoutExpired | None,
+) -> tuple[str, str]:
+    if timeout_error is None:
+        return "", ""
+    captured_stdout = (
+        timeout_error.stdout if isinstance(timeout_error.stdout, str) else ""
+    )
+    captured_stderr = (
+        timeout_error.stderr if isinstance(timeout_error.stderr, str) else ""
+    )
+    return captured_stdout, captured_stderr
+
+
+def _no_process_outcome(
+    all_attempts: list[ChainAttempt],
+    timeout_error: subprocess.TimeoutExpired | None,
+) -> ChainInvocationOutcome:
+    captured_stdout, captured_stderr = _timeout_streams(timeout_error)
+    return ChainInvocationOutcome(
+        served_command=None,
+        returncode=NO_COMPLETED_PROCESS_RETURN_CODE,
+        stdout=captured_stdout,
+        stderr=captured_stderr,
+        attempts=tuple(all_attempts),
+    )
+
+
+def _exhausted_outcome(
+    all_attempts: list[ChainAttempt],
+    last_usage_limited: subprocess.CompletedProcess[str] | None,
+) -> ChainInvocationOutcome:
+    if last_usage_limited is None:
+        return _no_process_outcome(all_attempts, None)
+    return ChainInvocationOutcome(
+        served_command=None,
+        returncode=last_usage_limited.returncode,
+        stdout=last_usage_limited.stdout,
+        stderr=last_usage_limited.stderr,
+        attempts=tuple(all_attempts),
+    )
+
+
+def _classify_completion(
+    entry: ChainEntry,
+    completion: subprocess.CompletedProcess[str],
+    all_attempts: list[ChainAttempt],
+) -> ChainInvocationOutcome | None:
+    if completion.returncode == 0:
+        all_attempts.append(ChainAttempt(entry.command, ATTEMPT_STATUS_SERVED))
+        return _served_outcome(entry.command, completion, all_attempts)
+    if _is_usage_limit_failure(completion):
+        all_attempts.append(ChainAttempt(entry.command, ATTEMPT_STATUS_USAGE_LIMITED))
+        return None
+    all_attempts.append(ChainAttempt(entry.command, ATTEMPT_STATUS_NONZERO_EXIT))
+    return _served_outcome(entry.command, completion, all_attempts)
+
+
+def run_claude(
+    all_claude_arguments: list[str], *, timeout_seconds: int
+) -> ChainInvocationOutcome:
+    """Run *all_claude_arguments* through the configured fallback chain.
+
+    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.
+
+    Args:
+        all_claude_arguments: Arguments passed after the binary name, such as
+            ``["-p", prompt, "--strict-mcp-config"]``.
+        timeout_seconds: Timeout applied to each binary invocation.
+
+    Returns:
+        The outcome of the walk, naming the serving binary and the full
+        attempt trail.
+
+    Raises:
+        ChainConfigurationError: When the chain configuration cannot be loaded.
+    """
+    all_entries = load_chain(chain_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
+        try:
+            completion = chain_subprocess_runner(
+                _build_invocation(each_entry, all_claude_arguments),
+                capture_output=True,
+                text=True,
+                timeout=timeout_seconds,
+                check=False,
+            )
+        except subprocess.TimeoutExpired as timeout_error:
+            all_attempts.append(
+                ChainAttempt(each_entry.command, ATTEMPT_STATUS_TIMEOUT)
+            )
+            return _no_process_outcome(all_attempts, timeout_error)
+        except FileNotFoundError:
+            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:
+            return terminal_outcome
+        last_usage_limited = completion
+    return _exhausted_outcome(all_attempts, last_usage_limited)
+
+
+def _build_argument_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Run a claude invocation through the fallback chain."
+    )
+    parser.add_argument(
+        CLI_TIMEOUT_FLAG,
+        dest="timeout_seconds",
+        type=int,
+        default=DEFAULT_TIMEOUT_SECONDS,
+        help="Timeout in seconds applied to each binary invocation.",
+    )
+    parser.add_argument("passthrough", nargs=argparse.REMAINDER)
+    return parser
+
+
+def _strip_leading_separator(all_passthrough: list[str]) -> list[str]:
+    if all_passthrough and all_passthrough[0] == CLI_ARGUMENTS_SEPARATOR:
+        return all_passthrough[1:]
+    return all_passthrough
+
+
+def _exhausted_message(all_attempts: tuple[ChainAttempt, ...]) -> str:
+    attempt_summary = ATTEMPT_SUMMARY_JOIN_SEPARATOR.join(
+        ATTEMPT_SUMMARY_ENTRY_TEMPLATE.format(
+            command=each_attempt.command, status=each_attempt.status
+        )
+        for each_attempt in all_attempts
+    )
+    return CHAIN_EXHAUSTED_MESSAGE_TEMPLATE.format(attempt_summary=attempt_summary)
+
+
+def main(all_command_arguments: list[str]) -> int:
+    """Walk the chain for CLI arguments and return the process exit code.
+
+    Args:
+        all_command_arguments: The argument vector after the program name.
+
+    Returns:
+        The served binary's return code, a distinct code when the chain is
+        exhausted, or a distinct code when the configuration cannot be loaded.
+    """
+    parser = _build_argument_parser()
+    parsed_arguments = parser.parse_args(all_command_arguments)
+    all_claude_arguments = _strip_leading_separator(parsed_arguments.passthrough)
+    try:
+        chain_outcome = run_claude(
+            all_claude_arguments, timeout_seconds=parsed_arguments.timeout_seconds
+        )
+    except ChainConfigurationError as configuration_error:
+        print(str(configuration_error), file=sys.stderr)
+        return CHAIN_CONFIG_ERROR_EXIT_CODE
+    if chain_outcome.served_command is None:
+        print(_exhausted_message(chain_outcome.attempts), file=sys.stderr)
+        return CHAIN_EXHAUSTED_EXIT_CODE
+    sys.stdout.write(chain_outcome.stdout)
+    sys.stderr.write(chain_outcome.stderr)
+    return chain_outcome.returncode
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/dev_env_scripts_constants/CLAUDE.md

@@ -7,6 +7,8 @@ Named constants for scripts in `scripts/`. Follows the project convention that t
 | File | Constants for |
 |---|---|
 | `timing.py` | `sweep_empty_dirs.py` — `DEFAULT_AGE_SECONDS` (smallest age before an empty directory is eligible for removal) and `DEFAULT_POLL_INTERVAL` (seconds between sweep passes in continuous-watch mode) |
+| `gh_artifact_upload_constants.py` | `gh_artifact_upload.py` — the `artifacts` release tag, title, and notes body, the GitHub CLI binary name, the asset-name timestamp format and template, the asset download URL template, the notes-file suffix, and the text encoding |
+| `claude_chain_constants.py` | `claude_chain_runner.py` — the chain config filename and home subdirectory, the usage-limit signature text, the per-binary status labels, the default timeout, CLI flag and separator tokens, config JSON keys, invalid-shape reason text, config-error and exhausted-chain message templates, and CLI exit codes |
 | `__init__.py` | Empty package marker |
 
 ## Convention