claude-dev-env 1.92.1 → 1.93.1

package/_shared/pr-loop/scripts/reviews_disabled.py

@@ -1,8 +1,16 @@
-"""Shared helper for the CLAUDE_REVIEWS_DISABLED opt-out gate.
+"""Decide which PR reviewers run from the opt-out and opt-in env token lists.
 
-Both ``skills/bugteam/scripts/bugteam_preflight.py`` and
-``_shared/pr-loop/scripts/preflight.py`` consume this helper so the parsing
-rules and disabled-token taxonomy live in exactly one place.
+::
+
+    enabled lists bugbot, disabled empty    -> bugbot   ok:   runs
+    no lists set                            -> bugbot   flag: off (default)
+    enabled lists bugbot, disabled bugbot   -> bugbot   flag: off (opt-out wins)
+    disabled empty                          -> bugteam  ok:   runs
+    disabled lists copilot                  -> copilot  flag: off
+
+Bugbot is off by default and runs only when the enabled list names it.
+Bugteam and copilot run by default and stop only when the disabled list
+names them; both lists parse case-insensitively and tolerate whitespace.
 """
 
 from __future__ import annotations
@@ -17,6 +25,7 @@ from pr_loop_shared_constants.reviews_disabled_constants import (
     CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN,
     CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME,
     CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR,
+    CLAUDE_REVIEWS_ENABLED_ENV_VAR_NAME,
     EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV,
 )
 
@@ -27,18 +36,24 @@ __all__ = [
     "CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN",
     "CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME",
     "CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR",
+    "CLAUDE_REVIEWS_ENABLED_ENV_VAR_NAME",
     "EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV",
     "is_bugbot_disabled_via_env",
+    "is_bugbot_opted_out_via_env",
     "is_bugteam_disabled_via_env",
     "is_copilot_disabled_via_env",
     "main",
 ]
 
 
-def _is_reviewer_disabled_via_env(reviewer_token: str) -> bool:
-    """Check whether CLAUDE_REVIEWS_DISABLED lists the given reviewer token.
+def _is_reviewer_listed_in_env(
+    environment_variable_name: str, reviewer_token: str
+) -> bool:
+    """Check whether an environment variable lists the given reviewer token.
 
     Args:
+        environment_variable_name: The environment variable to read, either
+            the reviews-disabled or the reviews-enabled variable name.
         reviewer_token: The reviewer token to look for, already lowercase
             (for example the bugteam or bugbot token constant).
 
@@ -46,16 +61,14 @@ def _is_reviewer_disabled_via_env(reviewer_token: str) -> bool:
         True when the env var contains ``reviewer_token`` as one of its
         comma-separated entries (case-insensitive, whitespace-tolerant).
     """
-    reviews_disabled_token_separator = CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR
-    disabled_reviewers_text = os.environ.get(CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME, "")
-    all_disabled_tokens = frozenset(
+    reviews_token_separator = CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR
+    listed_reviewers_text = os.environ.get(environment_variable_name, "")
+    all_listed_tokens = frozenset(
         each_raw_token.strip().lower()
-        for each_raw_token in disabled_reviewers_text.split(
-            reviews_disabled_token_separator
-        )
+        for each_raw_token in listed_reviewers_text.split(reviews_token_separator)
         if each_raw_token.strip()
     )
-    return reviewer_token in all_disabled_tokens
+    return reviewer_token in all_listed_tokens
 
 
 def is_bugteam_disabled_via_env() -> bool:
@@ -64,16 +77,45 @@ def is_bugteam_disabled_via_env() -> bool:
     Returns:
         True when the env var lists the ``bugteam`` token.
     """
-    return _is_reviewer_disabled_via_env(CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN)
+    return _is_reviewer_listed_in_env(
+        CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME, CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN
+    )
 
 
 def is_bugbot_disabled_via_env() -> bool:
+    """Check whether Cursor Bugbot is disabled for this run.
+
+    Cursor Bugbot is off by default. It runs only when
+    ``CLAUDE_REVIEWS_ENABLED`` lists ``bugbot``, and a ``bugbot`` token in
+    ``CLAUDE_REVIEWS_DISABLED`` forces it off even when the opt-in lists it.
+
+    Returns:
+        True when ``CLAUDE_REVIEWS_DISABLED`` lists ``bugbot`` or when
+        ``CLAUDE_REVIEWS_ENABLED`` does not list ``bugbot``.
+    """
+    is_opted_out = _is_reviewer_listed_in_env(
+        CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME, CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN
+    )
+    is_opted_in = _is_reviewer_listed_in_env(
+        CLAUDE_REVIEWS_ENABLED_ENV_VAR_NAME, CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN
+    )
+    return is_opted_out or not is_opted_in
+
+
+def is_bugbot_opted_out_via_env() -> bool:
     """Check whether CLAUDE_REVIEWS_DISABLED opts Cursor Bugbot out.
 
+    The opt-out forces Bugbot off even when ``CLAUDE_REVIEWS_ENABLED`` lists
+    ``bugbot``. This reports only the opt-out signal, where
+    ``is_bugbot_disabled_via_env`` also reports off for the default case in
+    which neither env var names ``bugbot``.
+
     Returns:
-        True when the env var lists the ``bugbot`` token.
+        True when ``CLAUDE_REVIEWS_DISABLED`` lists the ``bugbot`` token.
     """
-    return _is_reviewer_disabled_via_env(CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN)
+    return _is_reviewer_listed_in_env(
+        CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME, CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN
+    )
 
 
 def is_copilot_disabled_via_env() -> bool:
@@ -82,11 +124,13 @@ def is_copilot_disabled_via_env() -> bool:
     Returns:
         True when the env var lists the ``copilot`` token.
     """
-    return _is_reviewer_disabled_via_env(CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN)
+    return _is_reviewer_listed_in_env(
+        CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME, CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN
+    )
 
 
 def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
-    """Parse command-line arguments for the reviewer opt-out check.
+    """Parse command-line arguments for the reviewer opt-out and opt-in gate check.
 
     Args:
         all_argv: Argument list excluding the program name, typically
@@ -105,19 +149,19 @@ def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
             CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN,
             CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN,
         ],
-        help="Reviewer token to test against CLAUDE_REVIEWS_DISABLED",
+        help="Reviewer token to test against the CLAUDE_REVIEWS_DISABLED / CLAUDE_REVIEWS_ENABLED gates",
     )
     return parser.parse_args(all_argv)
 
 
 def main(all_arguments: list[str]) -> int:
-    """Exit 0 when the named reviewer is disabled via CLAUDE_REVIEWS_DISABLED.
+    """Exit 0 when the named reviewer is disabled for this run.
 
     Args:
         all_arguments: Argument list excluding the program name.
 
     Returns:
-        0 when the named reviewer is opted out by the env var, 1 otherwise.
+        0 when the named reviewer is disabled for this run, 1 otherwise.
     """
     arguments = parse_arguments(all_arguments)
     disabled_checker_by_reviewer = {

package/_shared/pr-loop/scripts/terminology_sweep.py

@@ -1,22 +1,24 @@
 """Flag a prose term that names a code identifier a hair differently.
 
-A change adds the field ``premium_interactions`` while the same branch's docs
-call it the ``premium-request`` budget: one thing, two names, and a reader who
-searches one never finds the other.
+A change adds the field ``premium_request_interactions`` while the same
+branch's docs call it the ``premium-request-budget`` field: one thing, two
+names, and a reader who searches one never finds the other.
 
 ::
 
-    code adds:  premium_interactions            the identifier
-    prose adds: the premium-request budget       a hyphenated term
-    flag: premium-request  vs  premium_interactions  -- shared first word, tail diverges
-    ok:   premium-interactions                   -- exact hyphen form, agrees
-    ok:   read-only,  test files,  to a file     -- English compound, plural, or stopword
+    code adds:  premium_request_interactions            the identifier
+    prose adds: the premium-request-budget field         a hyphenated term
+    flag: premium-request-budget  vs  premium_request_interactions  -- only the final word differs
+    ok:   premium-request-interactions                   -- exact hyphen form, agrees
+    ok:   premium-report-total  vs  premium_request_interactions  -- an earlier word differs, ordinary prose
 
 The sweep reads a unified diff, collects the multi-word identifiers added on
 code lines, and scans each added prose line for a hyphen or space variant that
-shares an identifier's leading word but diverges after it. It spares ordinary
-prose: English compound tails, singular/plural forms, stopword windows, and
-words that are themselves tokens of another introduced identifier.
+renames only the final word of an identifier: it agrees on every earlier word
+and differs on the last. A term that diverges in any earlier word, or shares
+only one leading word, is ordinary prose. It also spares English compound
+tails, singular/plural forms, stopword windows, and words that are themselves
+tokens of another introduced identifier.
 """
 
 import argparse
@@ -345,6 +347,47 @@ def _tuples_match_ignoring_plural(
     )
 
 
+def _diverges_only_in_final_token(
+    candidate_tuple: IdentifierTuple, identifier_tuple: IdentifierTuple
+) -> bool:
+    """Return whether two equal-length tuples agree on every token but the last.
+
+    ::
+
+        candidate:  ("premium", "request", "budget")
+        identifier: ("premium", "request", "interactions")
+        flag: every earlier token agrees, so the prose renames the final word
+        ok:   ("premium", "report", "total")  -- an earlier token diverges too
+
+    A near-miss renames a single trailing word of an identifier, so every token
+    before the last agrees by an exact or singular/plural match while the final
+    token differs. A tuple no longer than the two-token identifier minimum
+    cannot carry two agreeing leading tokens, so it never qualifies.
+
+    Args:
+        candidate_tuple: The prose term's lowercase token tuple.
+        identifier_tuple: An introduced identifier's lowercase token tuple.
+
+    Returns:
+        True when both tuples run longer than the two-token identifier minimum,
+        share the same length, agree by exact or singular/plural match on every
+        token but the last, and differ on the final token.
+    """
+    if (
+        len(candidate_tuple) <= MINIMUM_IDENTIFIER_TOKEN_COUNT
+        or len(candidate_tuple) != len(identifier_tuple)
+    ):
+        return False
+    if _tokens_are_plural_variants(candidate_tuple[-1], identifier_tuple[-1]):
+        return False
+    return all(
+        _tokens_are_plural_variants(each_candidate_token, each_identifier_token)
+        for each_candidate_token, each_identifier_token in zip(
+            candidate_tuple[:-1], identifier_tuple[:-1]
+        )
+    )
+
+
 def _word_is_identifier_vocabulary(
     prose_word: str, all_identifier_tokens: frozenset[str]
 ) -> bool:
@@ -391,16 +434,19 @@ def _near_miss_identifier(
             lines, used to spare prose built from real code vocabulary.
 
     Returns:
-        The first identifier sharing the candidate's leading token and length
-        but differing in a later token. None marks the candidate ordinary
-        prose instead, on any of these grounds: it matches an identifier
-        exactly; it shares no prefix with one; it ends in a common English
-        compound tail word (``read-only``, ``data-driven``); it contains an
-        English stopword (``to a``, ``each image``); it differs from the
-        identifier only by a singular/plural form of one or more tokens
-        (``test files`` against ``test_file``); or every diverging word is
-        itself a token of some introduced identifier (``target box`` when
-        ``box_height`` is also in the diff).
+        The first identifier the candidate renames in only its final token. Such a
+        candidate agrees on every earlier token, matches the identifier's
+        length, and differs on the last token. None marks the candidate
+        ordinary prose instead, on any of these grounds: it matches an
+        identifier exactly; it diverges in a token before the last
+        (``premium report total`` against ``premium_request_interactions``);
+        it holds no more than the two-token identifier minimum; it ends in a
+        common English compound tail word (``read-only``, ``data-driven``); it
+        contains an English stopword (``to a``, ``each image``); it differs
+        from the identifier only by a singular/plural form of one or more
+        tokens (``test files`` against ``test_file``); or every diverging word
+        is itself a token of some introduced identifier (``target width box``
+        when ``box_height`` is also in the diff).
     """
     if not candidate_tuple or candidate_tuple in all_identifier_tuples:
         return None
@@ -415,6 +461,8 @@ def _near_miss_identifier(
             continue
         if _tuples_match_ignoring_plural(each_identifier, candidate_tuple):
             continue
+        if not _diverges_only_in_final_token(candidate_tuple, each_identifier):
+            continue
         diverging_words = [
             each_word
             for each_word, each_token in zip(candidate_tuple, each_identifier)

package/_shared/pr-loop/scripts/tests/CLAUDE.md

@@ -32,7 +32,7 @@ pytest suite for the scripts and constants in `_shared/pr-loop/scripts/`. Each t
 
 ## Fixtures
 
-`fixtures/copilot_internal_user_jonecho.json` — a captured `gh api
+`fixtures/copilot_internal_user_example.json` — a captured `gh api
 copilot_internal/user` response driving `test_copilot_quota.py`.
 
 ## Running

package/_shared/pr-loop/scripts/tests/fixtures/{copilot_internal_user_jonecho.json → copilot_internal_user_example.json}

@@ -1,5 +1,5 @@
 {
-  "login": "jonecho",
+  "login": "example-user",
   "access_type_sku": "plus_monthly_subscriber_quota",
   "assigned_date": "2026-05-09T14:08:29-04:00",
   "can_signup_for_limited": false,

package/_shared/pr-loop/scripts/tests/test_agent_config_carveout.py

@@ -336,7 +336,7 @@ def test_is_trust_entry_rejects_cross_project_path_suffix_collision() -> None:
     short_project_path = "/projects/foo"
     trust_prefix = "Trusted local workspace:"
     longer_unrelated_path_entry = (
-        "Trusted local workspace: /Users/jon/projects/foo/.claude/** unrelated path"
+        "Trusted local workspace: /Users/example/projects/foo/.claude/** unrelated path"
     )
     assert (
         common_module.is_trust_entry_for_project(

package/_shared/pr-loop/scripts/tests/test_code_rules_gate.py

@@ -337,11 +337,11 @@ def test_main_staged_mode_passes_when_only_terminology_findings_exist(
     commit_all_files(temporary_git_repository, "initial")
     write_file(
         temporary_git_repository / "quota.py",
-        "first_count = 1\npremium_interactions = 1\n",
+        "first_count = 1\npremium_request_interactions = 1\n",
     )
     write_file(
         temporary_git_repository / "README.md",
-        "The premium-request budget gates the run.\n",
+        "The premium-request-budget field gates the run.\n",
     )
     stage_file(temporary_git_repository, "quota.py")
     stage_file(temporary_git_repository, "README.md")
@@ -2043,6 +2043,88 @@ def test_run_staged_test_files_zero_when_staged_conftest_collects_no_tests(
     assert gate_module.run_staged_test_files(temporary_git_repository) == 0
 
 
+def test_staged_pytest_skipped_below_minimum_python(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Below the minimum Python, the staged pytest step is skipped, not run.
+
+    A staged test that would fail returns a zero exit code because the older
+    interpreter cannot run its newer-API calls, so the environment gap does not
+    block the commit.
+    """
+    write_file(
+        temporary_git_repository / "test_needs_new_python.py",
+        "def test_intentionally_fails() -> None:\n    assert False\n",
+    )
+    stage_file(temporary_git_repository, "test_needs_new_python.py")
+    monkeypatch.setattr(gate_module, "MINIMUM_STAGED_PYTEST_PYTHON_MAJOR", 99)
+
+    exit_code = gate_module._staged_pytest_exit_code_for_current_python(
+        temporary_git_repository
+    )
+
+    captured = capsys.readouterr()
+    assert exit_code == 0
+    assert "skipping the staged pytest step" in captured.err
+
+
+def test_staged_pytest_runs_at_or_above_minimum_python(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """At or above the minimum Python, the staged pytest step runs and a failing
+    staged test blocks with a non-zero exit code.
+    """
+    write_file(
+        temporary_git_repository / "test_fails.py",
+        "def test_intentionally_fails() -> None:\n    assert False\n",
+    )
+    stage_file(temporary_git_repository, "test_fails.py")
+    monkeypatch.setattr(gate_module, "MINIMUM_STAGED_PYTEST_PYTHON_MAJOR", 2)
+
+    exit_code = gate_module._staged_pytest_exit_code_for_current_python(
+        temporary_git_repository
+    )
+
+    assert exit_code != 0
+
+
+def test_main_staged_skips_pytest_but_runs_code_rules_below_minimum_python(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """The version guard skips only the staged pytest step. A staged code-rules
+    violation still blocks the commit, so the two checks stay independent.
+    """
+    write_file(temporary_git_repository / "module.py", "first_count = 1\n")
+    commit_all_files(temporary_git_repository, "initial")
+    write_file(
+        temporary_git_repository / "module.py",
+        "first_count = 1\n"
+        "def compute_total(operand: int) -> int:\n"
+        "    result = operand + 1\n"
+        "    return result\n",
+    )
+    write_file(
+        temporary_git_repository / "test_fails.py",
+        "def test_intentionally_fails() -> None:\n    assert False\n",
+    )
+    stage_file(temporary_git_repository, "module.py")
+    stage_file(temporary_git_repository, "test_fails.py")
+    monkeypatch.setattr(gate_module, "MINIMUM_STAGED_PYTEST_PYTHON_MAJOR", 99)
+    monkeypatch.chdir(temporary_git_repository)
+
+    exit_code = gate_module.main(["--staged"])
+
+    captured = capsys.readouterr()
+    assert exit_code == 1
+    assert "skipping the staged pytest step" in captured.err
+    assert "result" in captured.err
+
+
 def test_hunk_header_pattern_captures_new_start_and_count() -> None:
     header_match = gate_module.hunk_header_pattern().match("@@ -12,3 +45,6 @@ def scope")
     assert header_match is not None
@@ -2578,3 +2660,211 @@ def test_run_staged_test_files_fails_when_one_group_fails(
     assert exit_code != 0
     captured_error = capsys.readouterr().err
     assert "failing_skill" in captured_error
+
+
+def test_resolve_gate_python_executable_prefers_env_var_over_venv(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    relative_segments = (
+        gate_module.ALL_WINDOWS_VENV_PYTHON_RELATIVE_PATH_SEGMENTS
+        if os.name == "nt"
+        else gate_module.ALL_POSIX_VENV_PYTHON_RELATIVE_PATH_SEGMENTS
+    )
+    venv_python = tmp_path.joinpath(".venv", *relative_segments)
+    venv_python.parent.mkdir(parents=True)
+    venv_python.write_text("", encoding="utf-8")
+    monkeypatch.setenv("CODE_RULES_GATE_PYTHON", "/configured/python")
+
+    resolved = gate_module._resolve_gate_python_executable(tmp_path)
+
+    assert resolved == "/configured/python"
+
+
+def test_resolve_gate_python_executable_falls_back_to_project_venv(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("CODE_RULES_GATE_PYTHON", raising=False)
+    relative_segments = (
+        gate_module.ALL_WINDOWS_VENV_PYTHON_RELATIVE_PATH_SEGMENTS
+        if os.name == "nt"
+        else gate_module.ALL_POSIX_VENV_PYTHON_RELATIVE_PATH_SEGMENTS
+    )
+    venv_python = tmp_path.joinpath(".venv", *relative_segments)
+    venv_python.parent.mkdir(parents=True)
+    venv_python.write_text("", encoding="utf-8")
+
+    resolved = gate_module._resolve_gate_python_executable(tmp_path)
+
+    assert resolved == str(venv_python)
+
+
+def test_resolve_gate_python_executable_falls_back_to_sys_executable(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("CODE_RULES_GATE_PYTHON", raising=False)
+
+    resolved = gate_module._resolve_gate_python_executable(tmp_path)
+
+    assert resolved == sys.executable
+
+
+def test_staged_pytest_environment_prepends_configured_pythonpath(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CODE_RULES_GATE_PYTHONPATH", "/configured/site-packages")
+    monkeypatch.setenv("PYTHONPATH", "/already/on/path")
+
+    environment = gate_module._staged_pytest_environment()
+
+    assert environment["PYTHONPATH"] == os.pathsep.join(
+        ["/configured/site-packages", "/already/on/path"]
+    )
+
+
+def _record_pytest_invocations(
+    monkeypatch: pytest.MonkeyPatch, *, all_exit_codes: list[int]
+) -> list[list[str]]:
+    """Patch subprocess.run to record each pytest argv and return staged exit codes."""
+    all_recorded_commands: list[list[str]] = []
+    all_remaining_exit_codes = list(all_exit_codes)
+
+    def _fake_subprocess_run(
+        all_command: list[str], **_keyword_arguments: object
+    ) -> subprocess.CompletedProcess[bytes]:
+        all_recorded_commands.append(list(all_command))
+        exit_code = all_remaining_exit_codes.pop(0) if all_remaining_exit_codes else 0
+        return subprocess.CompletedProcess(all_command, exit_code, b"", b"")
+
+    monkeypatch.setattr(gate_module.subprocess, "run", _fake_subprocess_run)
+    return all_recorded_commands
+
+
+def _staged_test_paths_under(group_root: Path, path_count: int) -> list[Path]:
+    return [
+        group_root
+        / "tests"
+        / "subpackage_with_a_realistically_long_directory_name"
+        / f"test_module_with_a_realistically_long_name_{each_index:04d}.py"
+        for each_index in range(path_count)
+    ]
+
+
+def _path_arguments_of(all_pytest_command: list[str]) -> list[str]:
+    fixed_prefix_length = len(gate_module.ALL_PYTEST_MODULE_INVOCATION) + 1
+    return all_pytest_command[fixed_prefix_length:]
+
+
+def test_run_pytest_for_group_batches_a_large_staged_set_under_the_budget(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """WinError 206: a staged set whose joined argv passes Windows' 32767-character
+    command-line limit crashed the gate and denied the commit. The paths must be
+    split across several pytest invocations, none of them over the budget.
+    """
+    all_recorded_commands = _record_pytest_invocations(monkeypatch, all_exit_codes=[])
+    all_test_paths = _staged_test_paths_under(tmp_path, 800)
+
+    exit_code = gate_module._run_pytest_for_group(tmp_path, all_test_paths, tmp_path)
+
+    assert exit_code == 0
+    assert len(all_recorded_commands) > 1, (
+        "a staged set wider than the command-line budget must be split across "
+        "several pytest invocations rather than passed in one oversized argv"
+    )
+    for each_command in all_recorded_commands:
+        assert (
+            len(" ".join(each_command))
+            <= gate_module.MAXIMUM_STAGED_PYTEST_COMMAND_LINE_CHARACTERS
+        )
+    all_batched_arguments = [
+        each_argument
+        for each_command in all_recorded_commands
+        for each_argument in _path_arguments_of(each_command)
+    ]
+    assert len(all_batched_arguments) == len(all_test_paths)
+
+
+def test_run_pytest_for_group_passes_paths_relative_to_the_group_root(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """group_root is already the subprocess cwd, so each path argument is passed
+    relative to it - the shortening that keeps a large staged set under the limit.
+    """
+    all_recorded_commands = _record_pytest_invocations(monkeypatch, all_exit_codes=[])
+    test_path = tmp_path / "tests" / "test_relative.py"
+
+    gate_module._run_pytest_for_group(tmp_path, [test_path], tmp_path)
+
+    assert _path_arguments_of(all_recorded_commands[0]) == [
+        str(Path("tests") / "test_relative.py")
+    ]
+
+
+def test_run_pytest_for_group_passes_an_outside_path_absolute(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    all_recorded_commands = _record_pytest_invocations(monkeypatch, all_exit_codes=[])
+    group_root = tmp_path / "group"
+    outside_path = tmp_path / "elsewhere" / "test_outside.py"
+
+    gate_module._run_pytest_for_group(group_root, [outside_path], tmp_path)
+
+    assert _path_arguments_of(all_recorded_commands[0]) == [str(outside_path)]
+
+
+def test_run_pytest_for_group_runs_one_invocation_for_a_small_staged_set(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    all_recorded_commands = _record_pytest_invocations(monkeypatch, all_exit_codes=[])
+    all_test_paths = _staged_test_paths_under(tmp_path, 3)
+
+    exit_code = gate_module._run_pytest_for_group(tmp_path, all_test_paths, tmp_path)
+
+    assert exit_code == 0
+    assert len(all_recorded_commands) == 1, (
+        "a staged set that fits the budget must behave exactly as before: "
+        "one pytest invocation carrying every path"
+    )
+
+
+def test_run_pytest_for_group_surfaces_the_first_failing_batch_exit_code(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A failure in any batch must surface, and every batch must still run so the
+    operator sees the whole staged-test picture rather than the first failure alone.
+    """
+    all_recorded_commands = _record_pytest_invocations(
+        monkeypatch, all_exit_codes=[0, 1, 2]
+    )
+    all_test_paths = _staged_test_paths_under(tmp_path, 800)
+
+    exit_code = gate_module._run_pytest_for_group(tmp_path, all_test_paths, tmp_path)
+
+    assert exit_code == 1
+    assert len(all_recorded_commands) >= 3
+
+
+def test_run_pytest_for_group_treats_no_tests_collected_as_a_pass_per_batch(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _record_pytest_invocations(
+        monkeypatch,
+        all_exit_codes=[gate_module.PYTEST_NO_TESTS_COLLECTED_EXIT_CODE, 0],
+    )
+    all_test_paths = _staged_test_paths_under(tmp_path, 800)
+
+    exit_code = gate_module._run_pytest_for_group(tmp_path, all_test_paths, tmp_path)
+
+    assert exit_code == 0, (
+        "a batch that collects no tests is not a failure; only a real pytest "
+        "failure exit code may block the commit"
+    )