claude-dev-env 2.7.0 → 2.8.0

package/scripts/test_invoke_code_review.py

@@ -15,11 +15,37 @@ import pytest
 import invoke_code_review as invoker
 from claude_chain_runner import ChainConfigurationError, ChainInvocationOutcome
 from _code_review_test_support import FIXTURE_SESSION_OPUS
+from dev_env_scripts_constants.claude_chain_constants import TERMINAL_STATUS_SERVED
 from dev_env_scripts_constants.code_review_constants import (
+    ALL_FINDING_SEVERITIES,
+    ALL_LOOP_TERMINALS,
+    ALL_RETAINED_VERIFICATION_VERDICTS,
     DEFAULT_CODE_REVIEW_EFFORT,
+    FINDING_FIELD_SEVERITY,
+    FINDING_FIELD_VERDICT,
     PERMISSION_MODE_ACCEPT_EDITS,
     PERMISSION_MODE_BYPASS,
+    RESULT_KEY_DRAFT_PRESERVED,
+    RESULT_KEY_REVIEWED_HEAD_COUNT,
+    RESULT_KEY_SURVIVING_FINDINGS,
+    RESULT_KEY_TERMINAL,
     REVIEW_PERMISSION_MODE,
+    SEVERITY_BLOCKER,
+    SEVERITY_HIGH,
+    SEVERITY_LOW,
+    SEVERITY_MEDIUM,
+    SEVERITY_NIT,
+    TERMINAL_ADVISOR_BLOCKED,
+    TERMINAL_CLEAN,
+    TERMINAL_NITS_FIXED,
+    VERDICT_CONFIRMED,
+    VERDICT_PLAUSIBLE,
+    VERDICT_REFUTED,
+    all_findings_carry_severity_and_verdict,
+    encode_review_loop_terminal_result,
+    is_nits_only_findings,
+    record_reviewed_head,
+    resolve_review_loop_terminal,
 )
 
 
@@ -66,6 +92,7 @@ def _serve_a_refusing_binary(
         stdout=EMPTY_REVIEW_STDOUT,
         stderr=REVIEW_BINARY_REFUSAL_TEXT,
         attempts=(),
+        terminal_status=TERMINAL_STATUS_SERVED,
     )
 
 
@@ -141,3 +168,274 @@ def test_host_profile_failure_reports_its_reason_on_stderr(
     captured_streams = capsys.readouterr()
     assert outcome.is_stamp_minted is False
     assert HOST_PROFILE_FAILURE_TEXT in captured_streams.err
+
+
+HEAD_SHA_ONE: str = "aaa111"
+HEAD_SHA_TWO: str = "bbb222"
+HEAD_SHA_THREE: str = "ccc333"
+HEAD_SHA_FOUR: str = "ddd444"
+FINDING_FILE_PATH: str = "pkg/module.py"
+FINDING_LINE_NUMBER: int = 12
+FINDING_SUMMARY_TEXT: str = "example finding"
+
+
+def _retained_finding(
+    *,
+    severity: str,
+    verdict: str = VERDICT_CONFIRMED,
+) -> dict[str, object]:
+    return {
+        "file": FINDING_FILE_PATH,
+        "line": FINDING_LINE_NUMBER,
+        "summary": FINDING_SUMMARY_TEXT,
+        FINDING_FIELD_SEVERITY: severity,
+        FINDING_FIELD_VERDICT: verdict,
+    }
+
+
+def test_severity_vocabulary_is_the_frozen_five_token_set() -> None:
+    assert ALL_FINDING_SEVERITIES == (
+        SEVERITY_BLOCKER,
+        SEVERITY_HIGH,
+        SEVERITY_MEDIUM,
+        SEVERITY_LOW,
+        SEVERITY_NIT,
+    )
+    assert ALL_FINDING_SEVERITIES == (
+        "blocker",
+        "high",
+        "medium",
+        "low",
+        "nit",
+    )
+
+
+def test_loop_terminals_are_the_frozen_three_token_set() -> None:
+    assert ALL_LOOP_TERMINALS == (
+        TERMINAL_CLEAN,
+        TERMINAL_NITS_FIXED,
+        TERMINAL_ADVISOR_BLOCKED,
+    )
+
+
+def test_retained_finding_requires_severity_and_verification_verdict() -> None:
+    complete_finding = _retained_finding(severity=SEVERITY_HIGH)
+    missing_severity = {
+        "file": FINDING_FILE_PATH,
+        "line": FINDING_LINE_NUMBER,
+        FINDING_FIELD_VERDICT: VERDICT_CONFIRMED,
+    }
+    missing_verdict = {
+        "file": FINDING_FILE_PATH,
+        "line": FINDING_LINE_NUMBER,
+        FINDING_FIELD_SEVERITY: SEVERITY_HIGH,
+    }
+    refuted_finding = _retained_finding(
+        severity=SEVERITY_LOW,
+        verdict=VERDICT_REFUTED,
+    )
+
+    assert all_findings_carry_severity_and_verdict([complete_finding]) is True
+    assert all_findings_carry_severity_and_verdict([missing_severity]) is False
+    assert all_findings_carry_severity_and_verdict([missing_verdict]) is False
+    assert all_findings_carry_severity_and_verdict([refuted_finding]) is False
+    assert VERDICT_CONFIRMED in ALL_RETAINED_VERIFICATION_VERDICTS
+    assert VERDICT_PLAUSIBLE in ALL_RETAINED_VERIFICATION_VERDICTS
+    assert VERDICT_REFUTED not in ALL_RETAINED_VERIFICATION_VERDICTS
+
+
+def test_review_of_new_head_increments_reviewed_head_count_once() -> None:
+    after_first = record_reviewed_head((), HEAD_SHA_ONE)
+    after_same_head = record_reviewed_head(after_first, HEAD_SHA_ONE)
+    after_second = record_reviewed_head(after_same_head, HEAD_SHA_TWO)
+
+    assert after_first == (HEAD_SHA_ONE,)
+    assert after_same_head == (HEAD_SHA_ONE,)
+    assert after_second == (HEAD_SHA_ONE, HEAD_SHA_TWO)
+    assert len(after_second) == 2
+
+
+def test_empty_findings_return_clean() -> None:
+    terminal_status = resolve_review_loop_terminal(
+        all_findings=(),
+        reviewed_head_count=1,
+        is_gates_passed=True,
+        is_nits_applied=False,
+    )
+
+    assert terminal_status == TERMINAL_CLEAN
+
+
+def test_empty_findings_continue_when_gates_have_not_passed() -> None:
+    terminal_status = resolve_review_loop_terminal(
+        all_findings=(),
+        reviewed_head_count=1,
+        is_gates_passed=False,
+        is_nits_applied=False,
+    )
+
+    assert terminal_status is None
+
+
+def test_nits_only_round_returns_nits_fixed_after_gates() -> None:
+    all_nits = (
+        _retained_finding(severity=SEVERITY_NIT),
+        _retained_finding(severity=SEVERITY_NIT, verdict=VERDICT_PLAUSIBLE),
+    )
+
+    assert is_nits_only_findings(all_nits) is True
+    terminal_status = resolve_review_loop_terminal(
+        all_findings=all_nits,
+        reviewed_head_count=1,
+        is_gates_passed=True,
+        is_nits_applied=True,
+    )
+
+    assert terminal_status == TERMINAL_NITS_FIXED
+
+
+def test_nits_without_retained_verdict_do_not_return_nits_fixed() -> None:
+    severity_only_nit = {
+        "file": FINDING_FILE_PATH,
+        "line": FINDING_LINE_NUMBER,
+        "summary": FINDING_SUMMARY_TEXT,
+        FINDING_FIELD_SEVERITY: SEVERITY_NIT,
+    }
+
+    assert is_nits_only_findings((severity_only_nit,)) is True
+    assert all_findings_carry_severity_and_verdict((severity_only_nit,)) is False
+    terminal_status = resolve_review_loop_terminal(
+        all_findings=(severity_only_nit,),
+        reviewed_head_count=1,
+        is_gates_passed=True,
+        is_nits_applied=True,
+    )
+
+    assert terminal_status is None
+
+
+def test_open_non_nit_findings_continue_at_any_head_count() -> None:
+    all_findings = (
+        _retained_finding(severity=SEVERITY_HIGH),
+        _retained_finding(severity=SEVERITY_NIT),
+    )
+    all_heads = record_reviewed_head((), HEAD_SHA_ONE)
+    all_heads = record_reviewed_head(all_heads, HEAD_SHA_TWO)
+    all_heads = record_reviewed_head(all_heads, HEAD_SHA_THREE)
+    all_heads = record_reviewed_head(all_heads, HEAD_SHA_FOUR)
+
+    assert len(all_heads) == 4
+    terminal_status = resolve_review_loop_terminal(
+        all_findings=all_findings,
+        reviewed_head_count=len(all_heads),
+        is_gates_passed=True,
+        is_nits_applied=False,
+    )
+
+    assert terminal_status is None
+
+
+def test_unclassified_findings_continue_when_advisor_is_reachable() -> None:
+    unclassified_finding = {
+        "file": FINDING_FILE_PATH,
+        "line": FINDING_LINE_NUMBER,
+        "summary": FINDING_SUMMARY_TEXT,
+        FINDING_FIELD_VERDICT: VERDICT_CONFIRMED,
+    }
+
+    terminal_status = resolve_review_loop_terminal(
+        all_findings=(unclassified_finding,),
+        reviewed_head_count=5,
+        is_gates_passed=True,
+        is_nits_applied=False,
+    )
+
+    assert terminal_status is None
+
+
+def test_nits_only_returns_nits_fixed_at_any_head_count() -> None:
+    all_nits = (_retained_finding(severity=SEVERITY_NIT),)
+
+    terminal_status = resolve_review_loop_terminal(
+        all_findings=all_nits,
+        reviewed_head_count=5,
+        is_gates_passed=True,
+        is_nits_applied=True,
+    )
+
+    assert terminal_status == TERMINAL_NITS_FIXED
+
+
+def test_advisor_unreachable_with_unclassified_returns_advisor_blocked() -> None:
+    unclassified_finding = {
+        "file": FINDING_FILE_PATH,
+        "line": FINDING_LINE_NUMBER,
+        FINDING_FIELD_VERDICT: VERDICT_CONFIRMED,
+    }
+
+    terminal_status = resolve_review_loop_terminal(
+        all_findings=(unclassified_finding,),
+        reviewed_head_count=1,
+        is_gates_passed=False,
+        is_nits_applied=False,
+        is_advisor_unreachable=True,
+    )
+
+    assert terminal_status == TERMINAL_ADVISOR_BLOCKED
+
+
+def test_terminal_serialization_preserves_draft_and_findings() -> None:
+    surviving_finding = _retained_finding(severity=SEVERITY_MEDIUM)
+    encoded_payload = encode_review_loop_terminal_result(
+        terminal=TERMINAL_ADVISOR_BLOCKED,
+        all_surviving_findings=(surviving_finding,),
+        reviewed_head_count=4,
+        is_draft_preserved=True,
+    )
+
+    assert encoded_payload[RESULT_KEY_TERMINAL] == TERMINAL_ADVISOR_BLOCKED
+    assert encoded_payload[RESULT_KEY_DRAFT_PRESERVED] is True
+    assert encoded_payload[RESULT_KEY_REVIEWED_HEAD_COUNT] == 4
+    assert encoded_payload[RESULT_KEY_SURVIVING_FINDINGS] == [surviving_finding]
+
+
+def test_advisor_blocked_forces_draft_preserved_when_caller_passes_false() -> None:
+    surviving_finding = _retained_finding(severity=SEVERITY_HIGH)
+    advisor_blocked_payload = encode_review_loop_terminal_result(
+        terminal=TERMINAL_ADVISOR_BLOCKED,
+        all_surviving_findings=(surviving_finding,),
+        reviewed_head_count=1,
+        is_draft_preserved=False,
+    )
+    clean_payload = encode_review_loop_terminal_result(
+        terminal=TERMINAL_CLEAN,
+        all_surviving_findings=(),
+        reviewed_head_count=1,
+        is_draft_preserved=False,
+    )
+
+    assert advisor_blocked_payload[RESULT_KEY_DRAFT_PRESERVED] is True
+    assert clean_payload[RESULT_KEY_DRAFT_PRESERVED] is False
+
+
+def test_fourth_and_later_heads_are_recorded() -> None:
+    all_heads = (HEAD_SHA_ONE, HEAD_SHA_TWO, HEAD_SHA_THREE)
+    after_fourth = record_reviewed_head(all_heads, HEAD_SHA_FOUR)
+
+    assert after_fourth == (
+        HEAD_SHA_ONE,
+        HEAD_SHA_TWO,
+        HEAD_SHA_THREE,
+        HEAD_SHA_FOUR,
+    )
+    assert len(after_fourth) == 4
+
+
+def test_mixed_severities_are_not_nits_only() -> None:
+    all_findings = (
+        _retained_finding(severity=SEVERITY_NIT),
+        _retained_finding(severity=SEVERITY_BLOCKER),
+    )
+
+    assert is_nits_only_findings(all_findings) is False
+    assert is_nits_only_findings(()) is False

package/scripts/test_resolve_worker_spawn.py

@@ -23,6 +23,10 @@ from claude_chain_runner import (  # noqa: E402
     ChainConfigurationError,
     ChainInvocationOutcome,
 )
+from dev_env_scripts_constants.claude_chain_constants import (  # noqa: E402
+    TERMINAL_STATUS_CHAIN_EXHAUSTED,
+    TERMINAL_STATUS_SERVED,
+)
 from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
     AGENT_FLAG,
     ALL_AGENT_FILENAMES_BY_ROLE,
@@ -35,17 +39,20 @@ from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
     CLI_TIMEOUT_FLAG,
     CLASSIFICATION_AUTH_FAILURE,
     CLASSIFICATION_OK,
+    CLASSIFICATION_TIMEOUT,
     CLASSIFICATION_USAGE_LIMIT,
     CWD_FLAG,
     DEFAULT_ROLE,
-    DEFAULT_SPAWN_MAX_TURNS,
     DEFAULT_WORKER_TIMEOUT_SECONDS,
+    MAXIMUM_WORKER_TIMEOUT_SECONDS,
+    MIN_WORKER_TIMEOUT_SECONDS,
     OUTPUT_FORMAT_FLAG,
     OUTPUT_FORMAT_JSON,
     PROMPT_FILE_FLAG,
     REASON_CLAUDE_AGENT_REQUIRED,
     REASON_GROK_AUTH_FAILED,
     REASON_PROMPT_FILE_MISSING,
+    REASON_TIMEOUT_OUT_OF_BOUNDS,
     RESULT_KEY_ATTEMPTS,
     RESULT_KEY_OK,
     RESULT_KEY_OUTPUT,
@@ -59,11 +66,16 @@ from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
     TIER_CLAUDE_HEADLESS,
     TIER_GROK,
 )
-from grok_headless_runner import GrokRunnerOutcome  # noqa: E402
+import grok_headless_runner  # noqa: E402
+from grok_headless_runner import (  # noqa: E402
+    GrokRunnerOutcome,
+    run_headless_worker,
+)
 from grok_worker_preflight import PreflightOutcome  # noqa: E402
 
 HOST_PROFILE_CLAUDE = "Claude"
 HOST_PROFILE_THIRD_PARTY = "ThirdParty"
+NON_POSITIVE_TIMEOUT_SECONDS = 0
 
 FIXTURE_GROK_STDOUT = '{"tier":"grok","status":"done"}'
 FIXTURE_CLAUDE_STDOUT = '{"tier":"claude","status":"done"}'
@@ -72,6 +84,7 @@ FIXTURE_GROK_RETURNCODE = 0
 FIXTURE_CLAUDE_RETURNCODE = 0
 FIXTURE_FAILED_RETURNCODE = 1
 FIXTURE_ROLE = "code-quality-agent"
+MIN_WORKER_TIMEOUT_SECONDS_CONSTANT_NAME = "MIN_WORKER_TIMEOUT_SECONDS"
 LARGE_PROMPT_CHARACTER_COUNT = 40000
 WINDOWS_SAFE_ARGV_ELEMENT_CEILING = 8192
 EXPECTED_PRIMARY_AGENT_FOR_DEFAULT_ROLE = Path(
@@ -124,6 +137,7 @@ def _claude_served(
         stdout=stdout,
         stderr="",
         attempts=(ChainAttempt(command="claude", status="served"),),
+        terminal_status=TERMINAL_STATUS_SERVED,
     )
 
 
@@ -134,6 +148,7 @@ def _claude_exhausted() -> ChainInvocationOutcome:
         stdout="",
         stderr="usage limit reached",
         attempts=(ChainAttempt(command="claude", status="usage_limited"),),
+        terminal_status=TERMINAL_STATUS_CHAIN_EXHAUSTED,
     )
 
 
@@ -261,7 +276,6 @@ def test_grok_ok_serves_tier_one(
         timeout_seconds=DEFAULT_WORKER_TIMEOUT_SECONDS,
         is_claude_tier_enabled=False,
         run_state_directory=run_state_directory,
-        max_turns=DEFAULT_SPAWN_MAX_TURNS,
     )
 
     assert spawn_outcome.is_ok is True
@@ -297,7 +311,6 @@ def test_grok_usage_limited_on_claude_host_requires_agent(
         timeout_seconds=DEFAULT_WORKER_TIMEOUT_SECONDS,
         is_claude_tier_enabled=False,
         run_state_directory=run_state_directory,
-        max_turns=DEFAULT_SPAWN_MAX_TURNS,
     )
 
     assert spawn_outcome.is_ok is False
@@ -313,6 +326,128 @@ def test_grok_usage_limited_on_claude_host_requires_agent(
     assert spawn_outcome.all_attempts[1].reason == REASON_CLAUDE_AGENT_REQUIRED
 
 
+def test_out_of_bounds_timeout_is_reported_as_config_not_worker_failure(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """A refused timeout prints a structured outcome and exits 3, never a traceback.
+
+    ::
+
+        --timeout-seconds 0     ok: reason timeout_out_of_bounds, exit 3
+        --timeout-seconds 5401  ok: reason timeout_out_of_bounds, exit 3
+    """
+    prompt_file, working_directory, run_state_directory = _paths(tmp_path)
+    _install_seams(monkeypatch, grok_outcome=_grok_ok())
+    monkeypatch.setattr(
+        dispatcher, "spawn_grok_runner", grok_headless_runner.run_headless_worker
+    )
+
+    for each_refused_timeout in (
+        NON_POSITIVE_TIMEOUT_SECONDS,
+        MAXIMUM_WORKER_TIMEOUT_SECONDS + 1,
+    ):
+        exit_code = dispatcher.main(
+            [
+                CLI_ROLE_FLAG,
+                FIXTURE_ROLE,
+                PROMPT_FILE_FLAG,
+                str(prompt_file),
+                CWD_FLAG,
+                str(working_directory),
+                CLI_TIMEOUT_FLAG,
+                str(each_refused_timeout),
+                CLI_RUN_STATE_DIR_FLAG,
+                str(run_state_directory),
+            ]
+        )
+        parsed_payload = json.loads(capsys.readouterr().out)
+        all_attempt_reasons = [
+            each_attempt[ATTEMPT_KEY_REASON]
+            for each_attempt in parsed_payload[RESULT_KEY_ATTEMPTS]
+        ]
+
+        assert exit_code == SPAWN_CONFIG_ERROR_EXIT_CODE, each_refused_timeout
+        assert parsed_payload[RESULT_KEY_OK] is False, each_refused_timeout
+        assert parsed_payload[RESULT_KEY_TIER_USED] is None, each_refused_timeout
+        assert REASON_TIMEOUT_OUT_OF_BOUNDS in all_attempt_reasons, each_refused_timeout
+
+
+def test_out_of_bounds_timeout_is_refused_when_the_grok_tier_is_unreachable(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """The bounds hold on a host whose preflight never reaches the grok runner.
+
+    ::
+
+        preflight unusable, --timeout-seconds 5401
+            ok: reason timeout_out_of_bounds, exit 3, no tier invoked
+    """
+    prompt_file, working_directory, run_state_directory = _paths(tmp_path)
+    call_log = _install_seams(
+        monkeypatch,
+        preflight_outcome=_fallthrough_preflight(REASON_GROK_AUTH_FAILED),
+        claude_outcome=_claude_served(),
+    )
+
+    exit_code = dispatcher.main(
+        [
+            CLI_ROLE_FLAG,
+            FIXTURE_ROLE,
+            PROMPT_FILE_FLAG,
+            str(prompt_file),
+            CWD_FLAG,
+            str(working_directory),
+            CLI_TIMEOUT_FLAG,
+            str(MAXIMUM_WORKER_TIMEOUT_SECONDS + 1),
+            CLI_RUN_STATE_DIR_FLAG,
+            str(run_state_directory),
+        ]
+    )
+    parsed_payload = json.loads(capsys.readouterr().out)
+    all_attempt_reasons = [
+        each_attempt[ATTEMPT_KEY_REASON]
+        for each_attempt in parsed_payload[RESULT_KEY_ATTEMPTS]
+    ]
+
+    assert exit_code == SPAWN_CONFIG_ERROR_EXIT_CODE
+    assert REASON_TIMEOUT_OUT_OF_BOUNDS in all_attempt_reasons
+    assert call_log.preflight_calls == 0
+    assert call_log.claude_calls == 0
+
+
+def test_timed_out_grok_worker_is_recorded_as_timeout_not_served(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    """A killed worker reaches the dispatcher's trail as timeout, never as served.
+
+    ::
+
+        grok tier times out  ok: attempt reason timeout, tier_used moves on
+    """
+    prompt_file, working_directory, run_state_directory = _paths(tmp_path)
+    call_log = _install_seams(
+        monkeypatch,
+        grok_outcome=_grok_failure(CLASSIFICATION_TIMEOUT),
+        claude_outcome=_claude_served(),
+        host_profile=HOST_PROFILE_THIRD_PARTY,
+    )
+
+    spawn_outcome = dispatcher.resolve_worker_spawn(
+        role=FIXTURE_ROLE,
+        prompt_file=prompt_file,
+        working_directory=working_directory,
+        timeout_seconds=DEFAULT_WORKER_TIMEOUT_SECONDS,
+        is_claude_tier_enabled=False,
+        run_state_directory=run_state_directory,
+    )
+
+    assert call_log.grok_calls == 1
+    assert spawn_outcome.all_attempts[0].tier == TIER_GROK
+    assert spawn_outcome.all_attempts[0].is_ok is False
+    assert spawn_outcome.all_attempts[0].reason == CLASSIFICATION_TIMEOUT
+    assert spawn_outcome.tier_used != TIER_GROK
+
+
 def test_grok_auth_failed_on_third_party_runs_tier_three(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:
@@ -331,7 +466,6 @@ def test_grok_auth_failed_on_third_party_runs_tier_three(
         timeout_seconds=DEFAULT_WORKER_TIMEOUT_SECONDS,
         is_claude_tier_enabled=False,
         run_state_directory=run_state_directory,
-        max_turns=DEFAULT_SPAWN_MAX_TURNS,
     )
 
     assert spawn_outcome.is_ok is True
@@ -423,6 +557,40 @@ def test_config_error_returns_exit_three(
     assert parsed_payload[RESULT_KEY_RETURNCODE] == SPAWN_CONFIG_ERROR_EXIT_CODE
 
 
+def test_below_floor_timeout_returns_json_config_exit(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """A below-floor timeout reads as a config error, not an escaping traceback."""
+    prompt_file, working_directory, run_state_directory = _paths(tmp_path)
+    _install_seams(monkeypatch, grok_outcome=_grok_ok())
+    monkeypatch.setattr(dispatcher, "spawn_grok_runner", run_headless_worker)
+    below_floor_timeout_seconds = MIN_WORKER_TIMEOUT_SECONDS - 1
+
+    exit_code = dispatcher.main(
+        [
+            CLI_ROLE_FLAG,
+            FIXTURE_ROLE,
+            PROMPT_FILE_FLAG,
+            str(prompt_file),
+            CWD_FLAG,
+            str(working_directory),
+            CLI_TIMEOUT_FLAG,
+            str(below_floor_timeout_seconds),
+            CLI_RUN_STATE_DIR_FLAG,
+            str(run_state_directory),
+        ]
+    )
+
+    assert exit_code == SPAWN_CONFIG_ERROR_EXIT_CODE
+    captured = capsys.readouterr()
+    assert captured.err == ""
+    parsed_payload = json.loads(captured.out)
+    assert parsed_payload[RESULT_KEY_OK] is False
+    assert parsed_payload[RESULT_KEY_TIER_USED] is None
+    assert parsed_payload[RESULT_KEY_RETURNCODE] == SPAWN_CONFIG_ERROR_EXIT_CODE
+    assert MIN_WORKER_TIMEOUT_SECONDS_CONSTANT_NAME in parsed_payload[RESULT_KEY_OUTPUT]
+
+
 def test_attempts_array_ordering_across_tiers(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:
@@ -441,7 +609,6 @@ def test_attempts_array_ordering_across_tiers(
         timeout_seconds=DEFAULT_WORKER_TIMEOUT_SECONDS,
         is_claude_tier_enabled=True,
         run_state_directory=run_state_directory,
-        max_turns=DEFAULT_SPAWN_MAX_TURNS,
     )
 
     all_tiers = [each_attempt.tier for each_attempt in spawn_outcome.all_attempts]
@@ -515,7 +682,6 @@ def test_preflight_fallthrough_skips_grok_runner(
         timeout_seconds=DEFAULT_WORKER_TIMEOUT_SECONDS,
         is_claude_tier_enabled=False,
         run_state_directory=run_state_directory,
-        max_turns=DEFAULT_SPAWN_MAX_TURNS,
     )
 
     assert call_log.grok_calls == 0
@@ -533,9 +699,15 @@ def test_detect_host_profile_is_consumed_not_reimplemented() -> None:
     assert "THIRD_PARTY" not in source_text
 
 
-def test_default_max_turns_reaches_grok_kwargs(
+def test_dispatcher_grok_invocation_carries_no_turn_cap(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str]
 ) -> None:
+    """The dispatcher hands the runner no turn cap; the timeout is the only bound.
+
+    ::
+
+        grok tier kwargs  ok: timeout_seconds present, max_turns absent
+    """
     prompt_file, working_directory, run_state_directory = _paths(tmp_path)
     call_log = _install_seams(
         monkeypatch,
@@ -559,7 +731,10 @@ def test_default_max_turns_reaches_grok_kwargs(
 
     assert exit_code == SPAWN_SERVED_EXIT_CODE
     assert call_log.grok_keyword_arguments is not None
-    assert call_log.grok_keyword_arguments["max_turns"] == DEFAULT_SPAWN_MAX_TURNS
+    assert "max_turns" not in call_log.grok_keyword_arguments
+    assert call_log.grok_keyword_arguments["timeout_seconds"] == (
+        DEFAULT_WORKER_TIMEOUT_SECONDS
+    )
     parsed_payload = json.loads(capsys.readouterr().out)
     assert parsed_payload[RESULT_KEY_OK] is True
 
@@ -645,7 +820,6 @@ def test_default_role_maps_to_primary_agent_stem(
         timeout_seconds=DEFAULT_WORKER_TIMEOUT_SECONDS,
         is_claude_tier_enabled=False,
         run_state_directory=run_state_directory,
-        max_turns=DEFAULT_SPAWN_MAX_TURNS,
     )
 
     assert spawn_outcome.is_ok is True
@@ -674,7 +848,6 @@ def test_tier_three_argv_includes_agent_for_default_role(
         timeout_seconds=DEFAULT_WORKER_TIMEOUT_SECONDS,
         is_claude_tier_enabled=False,
         run_state_directory=run_state_directory,
-        max_turns=DEFAULT_SPAWN_MAX_TURNS,
     )
 
     assert spawn_outcome.tier_used == TIER_CLAUDE_HEADLESS
@@ -708,7 +881,6 @@ def test_large_prompt_stays_out_of_claude_argv(
         timeout_seconds=DEFAULT_WORKER_TIMEOUT_SECONDS,
         is_claude_tier_enabled=False,
         run_state_directory=run_state_directory,
-        max_turns=DEFAULT_SPAWN_MAX_TURNS,
     )
 
     assert spawn_outcome.tier_used == TIER_CLAUDE_HEADLESS
@@ -926,8 +1098,7 @@ def test_headless_chain_runner_lock_serializes_distinct_cwds(
                 timeout_seconds=DEFAULT_WORKER_TIMEOUT_SECONDS,
                 is_claude_tier_enabled=False,
                 run_state_directory=run_state_directory,
-                max_turns=DEFAULT_SPAWN_MAX_TURNS,
-            )
+                    )
         except (OSError, RuntimeError, ValueError, AssertionError) as raised_error:
             all_errors.append(raised_error)
 
@@ -1005,7 +1176,6 @@ def test_usage_limit_fallover_delivers_full_prompt_to_each_binary(
         timeout_seconds=DEFAULT_WORKER_TIMEOUT_SECONDS,
         is_claude_tier_enabled=False,
         run_state_directory=run_state_directory,
-        max_turns=DEFAULT_SPAWN_MAX_TURNS,
     )
 
     assert prompt_text_by_command["claude"] == FIXTURE_PROMPT_TEXT