claude-dev-env 2.5.0 → 2.7.1

package/scripts/dev_env_scripts_constants/grok_worker_constants.py

@@ -203,9 +203,6 @@ CLASSIFICATION_STREAM_JOIN_SEPARATOR: str = "\n"
 DEFAULT_WORKER_TIMEOUT_SECONDS: int = 600
 """Default timeout applied to one headless worker invocation, in seconds."""
 
-DEFAULT_WORKER_MAX_TURNS: int = 8
-"""Default max-turns value applied to one headless worker invocation."""
-
 TIMEOUT_RETURN_CODE: int = -1
 """Return code recorded on the outcome when a timed-out process leaves no return code."""
 
@@ -216,13 +213,88 @@ LAUNCH_FAILURE_STDERR_PREFIX: str = "failed to launch: "
 """Prefix for the non-empty stderr diagnostic returned on a launch OSError."""
 
 KILL_GRACE_TIMEOUT_SECONDS: int = 10
-"""Seconds to wait for a killed process to reap its pipes before giving up on its streams."""
+"""Seconds to wait for a killed process to reap its pipes before giving up on its streams.
+
+Gates the drain that follows a kill. ``PROCESS_TREE_KILL_TIMEOUT_SECONDS``
+gates the kill command itself, so the two bound different operations.
+"""
+
+MAXIMUM_WORKER_TIMEOUT_SECONDS: int = 5400
+"""Ceiling the batch launcher puts on a worker's ``timeout_seconds`` (90 minutes).
+
+Enforced at three sites: the batch launcher refuses an over-ceiling
+specification while parsing it, ``run_headless_worker`` refuses one from any
+caller, and ``resolve_worker_spawn`` refuses one before its preflight so the
+bound holds on every tier. A worker that reaches this ceiling is killed and
+classified ``CLASSIFICATION_TIMEOUT``.
+"""
+
+MAXIMUM_WORKER_TIMEOUT_ERROR_TEMPLATE: str = (
+    "worker {field_name} {requested_seconds} exceeds "
+    "MAXIMUM_WORKER_TIMEOUT_SECONDS ({maximum_seconds})"
+)
+"""Rejection message for an over-ceiling timeout, shared by the batch parse and the runner."""
+
+WINDOWS_OS_NAME: str = "nt"
+"""``os.name`` value that selects the Windows branch of the process-tree kill."""
+
+WINDOWS_TASKKILL_COMMAND: str = "taskkill"
+"""Windows command that ends a process by id."""
+
+WINDOWS_TASKKILL_TREE_FLAG: str = "/T"
+"""``taskkill`` flag that extends the kill to every descendant process."""
+
+WINDOWS_TASKKILL_FORCE_FLAG: str = "/F"
+"""``taskkill`` flag that forces termination rather than requesting it."""
+
+WINDOWS_TASKKILL_PID_FLAG: str = "/PID"
+"""``taskkill`` flag that names the target process id."""
+
+PROCESS_TREE_KILL_TIMEOUT_SECONDS: int = 10
+"""Seconds allowed for the tree-kill command itself before it is abandoned.
+
+Gates the kill command. ``KILL_GRACE_TIMEOUT_SECONDS`` gates the drain that
+follows a kill, so the two bound different operations.
+"""
 
 MIN_WORKER_TIMEOUT_SECONDS: int = 1
-"""Minimum accepted worker timeout_seconds in a batch specification."""
+"""Minimum accepted worker timeout_seconds, in seconds.
 
-MIN_WORKER_MAX_TURNS: int = 1
-"""Minimum accepted worker max_turns in a batch specification."""
+Enforced at the same three sites as ``MAXIMUM_WORKER_TIMEOUT_SECONDS``.
+"""
+
+MINIMUM_WORKER_TIMEOUT_ERROR_TEMPLATE: str = (
+    "worker {field_name} {requested_seconds} is below "
+    "MIN_WORKER_TIMEOUT_SECONDS ({minimum_seconds})"
+)
+"""Rejection message for a below-floor timeout, shared by the batch parse and the runner."""
+
+CLASSIFICATION_KILL_FAILED: str = "kill_failed"
+"""Outcome classification when a timed-out worker's streams never drain.
+
+Distinct from ``CLASSIFICATION_TIMEOUT``: that worker's tree was cleared, this
+one's was not, so a caller can tell an abandoned process tree from a stopped
+one.
+"""
+
+KILL_FAILED_RETURN_CODE: int = -4
+"""Return code recorded when a timed-out worker's streams never drain."""
+
+KILL_FAILED_STDERR_TEMPLATE: str = (
+    "worker timed out and its streams never drained across {attempt_count} "
+    "kill-and-drain attempts; process {process_identifier} may still be running"
+)
+"""Stderr diagnostic naming the surviving process id after every attempt fails."""
+
+PROCESS_TREE_KILL_ATTEMPT_LIMIT: int = 2
+"""Kill-and-drain rounds run on a timed-out worker before the kill is reported failed.
+
+Each round issues the tree kill while the worker process is still alive, then
+waits ``KILL_GRACE_TIMEOUT_SECONDS`` for the streams to drain.
+"""
+
+REASON_TIMEOUT_OUT_OF_BOUNDS: str = "timeout_out_of_bounds"
+"""Dispatcher attempt reason when the requested timeout is below the floor or above the ceiling."""
 
 WORKER_EXCEPTION_RETURN_CODE: int = -3
 """Return code recorded on a WorkerReport when the worker body raises before a process runs.
@@ -321,9 +393,6 @@ WORKER_SPEC_TIMEOUT_KEY: str = "timeout_seconds"
 WORKER_SPEC_IS_REPO_ONLY_KEY: str = "is_repo_only"
 """JSON key for whether a readonly worker also disables web search."""
 
-WORKER_SPEC_MAX_TURNS_KEY: str = "max_turns"
-"""JSON key for one worker's max-turns cap."""
-
 WORKER_SPEC_AGENT_NAME_KEY: str = "agent_name"
 """JSON key for one worker's optional agent definition name."""
 
@@ -389,9 +458,6 @@ REASON_CLAUDE_AGENT_REQUIRED: str = "claude_agent_required"
 REASON_PROMPT_FILE_MISSING: str = "prompt_file_missing"
 """Config reason when the dispatcher CLI prompt file path is absent or unreadable."""
 
-DEFAULT_SPAWN_MAX_TURNS: int = 8
-"""Default max-turns applied to the headless grok worker when the caller names none."""
-
 SPAWN_SERVED_EXIT_CODE: int = 0
 """CLI exit code when a dispatcher tier served the call."""
 

package/scripts/grok_headless_runner.py

@@ -3,9 +3,12 @@
 
 Builds a headless argv, mints a unique ``--leader-socket`` path under the
 caller-supplied run state directory, captures stdout/stderr/returncode, kills
-the process on timeout, and classifies failures via signature lists in
+the process tree on timeout, and classifies failures via signature lists in
 ``dev_env_scripts_constants.grok_worker_constants``.
 
+The timeout is the only bound on a worker's length; the argv carries no turn
+cap.
+
 Dual-match policy matches preflight: when both usage and auth signatures appear
 in the same streams, auth wins (``CLASSIFICATION_AUTH_FAILURE``).
 
@@ -15,14 +18,15 @@ Import ``run_headless_worker`` for the outcome object::
         prompt_file=path,
         working_directory=cwd,
         run_state_directory=run_dir,
-        max_turns=8,
-        timeout_seconds=600,
+        timeout_seconds=5400,
         agent_name="code-quality-agent",
     )
 """
 
 from __future__ import annotations
 
+import os
+import signal
 import subprocess
 import uuid
 from dataclasses import dataclass
@@ -35,6 +39,7 @@ from dev_env_scripts_constants.grok_worker_constants import (
     ALWAYS_APPROVE_FLAG,
     CLASSIFICATION_AUTH_FAILURE,
     CLASSIFICATION_ERROR,
+    CLASSIFICATION_KILL_FAILED,
     CLASSIFICATION_OK,
     CLASSIFICATION_STREAM_JOIN_SEPARATOR,
     CLASSIFICATION_TIMEOUT,
@@ -43,24 +48,46 @@ from dev_env_scripts_constants.grok_worker_constants import (
     GROK_BINARY_NAME,
     GROK_BINARY_NOT_FOUND_STDERR,
     GROK_MODEL_PIN,
+    KILL_FAILED_RETURN_CODE,
+    KILL_FAILED_STDERR_TEMPLATE,
     KILL_GRACE_TIMEOUT_SECONDS,
     LAUNCH_FAILURE_RETURN_CODE,
     LAUNCH_FAILURE_STDERR_PREFIX,
     LEADER_SOCKET_FILENAME_PREFIX,
     LEADER_SOCKET_FILENAME_SUFFIX,
     LEADER_SOCKET_FLAG,
-    MAX_TURNS_FLAG,
+    MAXIMUM_WORKER_TIMEOUT_ERROR_TEMPLATE,
+    MAXIMUM_WORKER_TIMEOUT_SECONDS,
+    MIN_WORKER_TIMEOUT_SECONDS,
+    MINIMUM_WORKER_TIMEOUT_ERROR_TEMPLATE,
     MISSING_BINARY_RETURN_CODE,
     MODEL_FLAG,
     OUTPUT_FORMAT_FLAG,
     OUTPUT_FORMAT_JSON,
+    PROCESS_TREE_KILL_ATTEMPT_LIMIT,
+    PROCESS_TREE_KILL_TIMEOUT_SECONDS,
     PROMPT_FILE_FLAG,
     TIMEOUT_RETURN_CODE,
     UTF8_DECODE_ERRORS,
     UTF8_ENCODING,
+    WINDOWS_OS_NAME,
+    WINDOWS_TASKKILL_COMMAND,
+    WINDOWS_TASKKILL_FORCE_FLAG,
+    WINDOWS_TASKKILL_PID_FLAG,
+    WINDOWS_TASKKILL_TREE_FLAG,
+    WORKER_SPEC_TIMEOUT_KEY,
 )
 
 runner_popen = subprocess.Popen
+runner_subprocess_run = subprocess.run
+
+
+class WorkerTimeoutOutOfBoundsError(ValueError):
+    """Raised when a requested worker timeout falls outside the accepted bounds.
+
+    A ``ValueError`` subclass so existing callers that catch ``ValueError``
+    keep working, while a caller that wants only this fault can name it.
+    """
 
 
 @dataclass(frozen=True)
@@ -90,7 +117,6 @@ def _build_invocation(
     *,
     prompt_file: Path,
     working_directory: Path,
-    max_turns: int,
     leader_socket_path: Path,
     agent_name: str | None,
     all_extra_arguments: tuple[str, ...] = (),
@@ -104,8 +130,6 @@ def _build_invocation(
         OUTPUT_FORMAT_FLAG,
         OUTPUT_FORMAT_JSON,
         ALWAYS_APPROVE_FLAG,
-        MAX_TURNS_FLAG,
-        str(max_turns),
         LEADER_SOCKET_FLAG,
         str(leader_socket_path),
     ]
@@ -180,14 +204,180 @@ def _resolve_returncode(process: subprocess.Popen[str]) -> int:
     return TIMEOUT_RETURN_CODE
 
 
-def _timeout_outcome(process: subprocess.Popen[str]) -> GrokRunnerOutcome:
-    process.kill()
+def _kill_windows_process_tree(process_identifier: int) -> None:
+    """End a Windows process and every descendant it started, by process id.
+
+    Swallows taskkill failures so the caller still falls back to
+    ``Popen.kill()`` and a timed drain.
+    """
     try:
-        captured_stdout, captured_stderr = process.communicate(
-            timeout=KILL_GRACE_TIMEOUT_SECONDS
+        runner_subprocess_run(
+            [
+                WINDOWS_TASKKILL_COMMAND,
+                WINDOWS_TASKKILL_TREE_FLAG,
+                WINDOWS_TASKKILL_FORCE_FLAG,
+                WINDOWS_TASKKILL_PID_FLAG,
+                str(process_identifier),
+            ],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+            timeout=PROCESS_TREE_KILL_TIMEOUT_SECONDS,
         )
+    except (subprocess.TimeoutExpired, OSError):
+        return
+
+
+def _kill_posix_process_group(process_identifier: int) -> None:
+    """End a POSIX process group so no grandchild keeps the capture pipe open.
+
+    Reached only through the caller's ``os.name`` branch, so the process-group
+    calls run on the platforms that define them.
+
+    A process id that is already reaped raises ``OSError``; this swallows it and
+    returns, so the caller falls back to ``Popen.kill()``.
+    """
+    try:
+        process_group_identifier = os.getpgid(process_identifier)  # type: ignore[attr-defined] # POSIX-only, reached via the caller's os.name branch
+        os.killpg(process_group_identifier, signal.SIGKILL)  # type: ignore[attr-defined] # POSIX-only, reached via the caller's os.name branch
+    except OSError:
+        return
+
+
+def _kill_process_tree_by_identifier(process_identifier: int) -> None:
+    """Issue the platform's tree kill for one process id, with no liveness check."""
+    if os.name == WINDOWS_OS_NAME:
+        _kill_windows_process_tree(process_identifier)
+        return
+    _kill_posix_process_group(process_identifier)
+
+
+def _terminate_process_tree(process: subprocess.Popen[str]) -> None:
+    """End the worker process and every descendant it spawned.
+
+    ::
+
+        tree kill (taskkill /T or killpg)  ok:   grandchildren die, pipes close
+        Popen.kill() alone                 flag: grandchildren outlive the worker
+
+    Falls back to ``Popen.kill()`` when the direct child survives the tree kill,
+    so the caller never waits on a live process.
+    """
+    if process.poll() is not None:
+        return
+    _kill_process_tree_by_identifier(process.pid)
+    if process.poll() is not None:
+        return
+    try:
+        process.kill()
+    except ProcessLookupError:
+        return
+
+
+def require_timeout_within_bounds(timeout_seconds: int | None) -> None:
+    """Refuse a timeout that is missing, below the floor, or above the ceiling.
+
+    ::
+
+        None or 0  flag: ValueError naming MIN_WORKER_TIMEOUT_SECONDS
+        5401       flag: ValueError naming MAXIMUM_WORKER_TIMEOUT_SECONDS
+        1 .. 5400  ok:   returns
+
+    Public so a dispatcher can apply the same bounds on a path that never
+    reaches ``run_headless_worker``.
+
+    Args:
+        timeout_seconds: The requested per-worker timeout in seconds.
+
+    Raises:
+        WorkerTimeoutOutOfBoundsError: When the value falls outside the bounds.
+    """
+    if timeout_seconds is None or timeout_seconds < MIN_WORKER_TIMEOUT_SECONDS:
+        raise WorkerTimeoutOutOfBoundsError(
+            MINIMUM_WORKER_TIMEOUT_ERROR_TEMPLATE.format(
+                field_name=WORKER_SPEC_TIMEOUT_KEY,
+                requested_seconds=timeout_seconds,
+                minimum_seconds=MIN_WORKER_TIMEOUT_SECONDS,
+            )
+        )
+    if timeout_seconds > MAXIMUM_WORKER_TIMEOUT_SECONDS:
+        raise WorkerTimeoutOutOfBoundsError(
+            MAXIMUM_WORKER_TIMEOUT_ERROR_TEMPLATE.format(
+                field_name=WORKER_SPEC_TIMEOUT_KEY,
+                requested_seconds=timeout_seconds,
+                maximum_seconds=MAXIMUM_WORKER_TIMEOUT_SECONDS,
+            )
+        )
+
+
+def _drain_after_kill(process: subprocess.Popen[str]) -> tuple[str, str] | None:
+    """Read the killed process's streams, or None when the grace window expires."""
+    try:
+        return process.communicate(timeout=KILL_GRACE_TIMEOUT_SECONDS)
     except subprocess.TimeoutExpired:
-        captured_stdout, captured_stderr = "", ""
+        return None
+
+
+def _kill_and_drain_within_attempt_limit(
+    process: subprocess.Popen[str],
+) -> tuple[str, str] | None:
+    """Kill the process tree and drain it, retrying up to the attempt limit.
+
+    ::
+
+        attempt 1 drains         ok:   streams, one attempt made
+        attempt 1 times out,
+        attempt 2 drains         ok:   streams, two attempts made
+        every attempt times out  flag: None
+
+    A tree kill that returns without taking leaves the drain waiting on a live
+    pipe, so a timed-out drain is followed by another kill-and-drain round.
+    ``_terminate_process_tree`` re-issues the kill only while the worker
+    process is still alive; once it has exited, the next round is a second
+    drain window for the descendants still holding the pipe open.
+
+    Args:
+        process: The timed-out worker process to kill and read.
+
+    Returns:
+        The captured stdout and stderr, or None when every attempt timed out.
+    """
+    attempts_made = 0
+    while attempts_made < PROCESS_TREE_KILL_ATTEMPT_LIMIT:
+        _terminate_process_tree(process)
+        all_captured_streams = _drain_after_kill(process)
+        if all_captured_streams is not None:
+            return all_captured_streams
+        attempts_made += 1
+    return None
+
+
+def _kill_failed_outcome(process: subprocess.Popen[str]) -> GrokRunnerOutcome:
+    diagnostic_text = KILL_FAILED_STDERR_TEMPLATE.format(
+        attempt_count=PROCESS_TREE_KILL_ATTEMPT_LIMIT,
+        process_identifier=process.pid,
+    )
+    return GrokRunnerOutcome(
+        is_ok=False,
+        returncode=KILL_FAILED_RETURN_CODE,
+        classification=CLASSIFICATION_KILL_FAILED,
+        stdout="",
+        stderr=diagnostic_text,
+    )
+
+
+def _timeout_outcome(process: subprocess.Popen[str]) -> GrokRunnerOutcome:
+    """Kill a timed-out worker's tree, then classify what the kill achieved.
+
+    ::
+
+        drain clears on attempt 1 or 2  ok:   classification timeout
+        both attempts leave it draining flag: classification kill_failed
+    """
+    all_captured_streams = _kill_and_drain_within_attempt_limit(process)
+    if all_captured_streams is None:
+        return _kill_failed_outcome(process)
+    captured_stdout, captured_stderr = all_captured_streams
     stdout_text = _normalize_stream(captured_stdout)
     stderr_text = _normalize_stream(captured_stderr)
     returncode = _resolve_returncode(process)
@@ -234,6 +424,7 @@ def _invoke_process(
             text=True,
             encoding=UTF8_ENCODING,
             errors=UTF8_DECODE_ERRORS,
+            start_new_session=os.name != WINDOWS_OS_NAME,
         )
     except FileNotFoundError:
         return _missing_binary_outcome()
@@ -254,7 +445,6 @@ def run_headless_worker(
     prompt_file: Path,
     working_directory: Path,
     run_state_directory: Path,
-    max_turns: int,
     timeout_seconds: int,
     agent_name: str | None = None,
     leader_socket_path: Path | None = None,
@@ -262,13 +452,16 @@ def run_headless_worker(
 ) -> GrokRunnerOutcome:
     """Run one headless grok worker and classify the process outcome.
 
+    The timeout is the worker's only bound; the argv carries no turn cap.
+
     Args:
         prompt_file: Path to the prompt file passed via ``--prompt-file``.
         working_directory: Working directory passed via ``--cwd``.
         run_state_directory: Run-scoped directory the leader socket is minted
             under. Read only when ``leader_socket_path`` is omitted.
-        max_turns: Maximum agent turns passed via ``--max-turns``.
-        timeout_seconds: Seconds before the process is killed on expiry.
+        timeout_seconds: Seconds before the process tree is killed on expiry.
+            Must sit between ``MIN_WORKER_TIMEOUT_SECONDS`` and
+            ``MAXIMUM_WORKER_TIMEOUT_SECONDS`` inclusive.
         agent_name: Optional role agent name passed via ``--agent``.
         leader_socket_path: Optional pre-minted leader socket path. When omitted,
             a unique path is minted under ``run_state_directory``.
@@ -277,7 +470,12 @@ def run_headless_worker(
 
     Returns:
         The classified outcome including return code and captured streams.
+
+    Raises:
+        WorkerTimeoutOutOfBoundsError: When ``timeout_seconds`` is missing,
+            below the floor, or above the ceiling.
     """
+    require_timeout_within_bounds(timeout_seconds)
     resolved_leader_socket_path = (
         leader_socket_path
         if leader_socket_path is not None
@@ -286,7 +484,6 @@ def run_headless_worker(
     all_arguments = _build_invocation(
         prompt_file=prompt_file,
         working_directory=working_directory,
-        max_turns=max_turns,
         leader_socket_path=resolved_leader_socket_path,
         agent_name=agent_name,
         all_extra_arguments=all_extra_arguments,

package/scripts/invoke_code_review.py

@@ -8,7 +8,8 @@ Mode decision::
     host=ThirdParty, any model        -> mode chain
 
 Chain mode runs ``run_claude`` with argv from ``build_code_review_arguments``
-(single-turn prompt, model opus, json output, bypassPermissions).
+(single-turn prompt, model opus, json output, and the permission mode this
+caller is allowed to ask the review binary for).
 
 cwd is the PR working tree and stdin is redirected from the empty stream so
 the spawn does not wait for interactive input. Result JSON on stdout only::
@@ -80,7 +81,7 @@ from dev_env_scripts_constants.code_review_constants import (  # noqa: E402
     MAXIMUM_STAMP_MINT_PASSES,
     MODE_CHAIN,
     MODE_IN_SESSION,
-    PERMISSION_MODE_BYPASS,
+    REVIEW_PERMISSION_MODE as PERMISSION_MODE_BYPASS,
     PERMISSION_MODE_FLAG,
     RECORD_STAMP_FLAG,
     RESULT_KEY_BOUND_HASH,
@@ -418,6 +419,7 @@ def is_code_review_clean_stamp_allowed(review_outcome: CodeReviewOutcome) -> boo
         return False
     return True
 
+
 def _run_claude_with_empty_stdin(
     all_claude_arguments: list[str],
     *,
@@ -495,6 +497,7 @@ def _failure_code_review_outcome(returncode: int) -> CodeReviewOutcome:
         is_dirty_tree=False,
     )
 
+
 def _run_chain_review(
     *,
     working_directory: Path,
@@ -507,6 +510,8 @@ def _run_chain_review(
         timeout_seconds=timeout_seconds,
         working_directory=working_directory,
     )
+    if chain_outcome.returncode != SUCCESSFUL_REVIEW_RETURNCODE and chain_outcome.stderr:
+        sys.stderr.write(chain_outcome.stderr.strip() + "\n")
     return _chain_outcome(chain_outcome, working_directory=working_directory)
 
 
@@ -869,9 +874,11 @@ def _mint_or_config_outcome(
             timeout_seconds=timeout_seconds,
             effort=effort,
         )
-    except ChainConfigurationError:
+    except ChainConfigurationError as configuration_error:
+        sys.stderr.write(str(configuration_error) + "\n")
         return _no_mint_outcome(CHAIN_CONFIG_ERROR_EXIT_CODE)
-    except ValueError:
+    except ValueError as host_profile_error:
+        sys.stderr.write(str(host_profile_error) + "\n")
         return _no_mint_outcome(HOST_PROFILE_ERROR_RETURNCODE)
 
 

package/scripts/resolve_worker_spawn.py

@@ -65,7 +65,6 @@ from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
     CLI_TIMEOUT_FLAG,
     CWD_FLAG,
     DEFAULT_ROLE,
-    DEFAULT_SPAWN_MAX_TURNS,
     DEFAULT_WORKER_TIMEOUT_SECONDS,
     EMPTY_OUTPUT,
     OUTPUT_FORMAT_FLAG,
@@ -73,6 +72,7 @@ from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
     PROMPT_FILE_FLAG,
     REASON_CLAUDE_AGENT_REQUIRED,
     REASON_PROMPT_FILE_MISSING,
+    REASON_TIMEOUT_OUT_OF_BOUNDS,
     RESULT_KEY_ATTEMPTS,
     RESULT_KEY_OK,
     RESULT_KEY_OUTPUT,
@@ -87,7 +87,12 @@ from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
     TIER_GROK,
     UTF8_ENCODING,
 )
-from grok_headless_runner import GrokRunnerOutcome, run_headless_worker  # noqa: E402
+from grok_headless_runner import (  # noqa: E402
+    GrokRunnerOutcome,
+    WorkerTimeoutOutOfBoundsError,
+    require_timeout_within_bounds,
+    run_headless_worker,
+)
 from grok_worker_preflight import PreflightOutcome, run_preflight  # noqa: E402
 from tier_model_ids import detect_host_profile  # noqa: E402
 
@@ -336,7 +341,6 @@ def _run_tier_grok(
     prompt_file: Path,
     working_directory: Path,
     run_state_directory: Path,
-    max_turns: int,
     timeout_seconds: int,
 ) -> GrokRunnerOutcome:
     agent_name = _primary_agent_name_for_role(role)
@@ -344,7 +348,6 @@ def _run_tier_grok(
         prompt_file=prompt_file,
         working_directory=working_directory,
         run_state_directory=run_state_directory,
-        max_turns=max_turns,
         timeout_seconds=timeout_seconds,
         agent_name=agent_name,
     )
@@ -418,10 +421,13 @@ def resolve_worker_spawn(
     timeout_seconds: int,
     is_claude_tier_enabled: bool,
     run_state_directory: Path,
-    max_turns: int,
 ) -> SpawnOutcome:
     """Walk the worker-spawn tiers and return the structured outcome.
 
+    The timeout bounds each tier; no turn cap reaches the headless grok worker.
+    The bounds check runs before the preflight, so a refused timeout is refused
+    on the claude tier too, not only on the path that reaches the grok runner.
+
     Args:
         role: Worker role name for preflight; mapped to a primary agent stem.
         prompt_file: Path to the prompt file for headless workers.
@@ -429,11 +435,16 @@ def resolve_worker_spawn(
         timeout_seconds: Timeout applied to each tier invocation.
         is_claude_tier_enabled: When True, allow tier 3 on a Claude host.
         run_state_directory: Run-scoped directory for leader sockets and cache.
-        max_turns: Maximum agent turns for the headless grok worker.
 
     Returns:
         The dispatcher outcome including the ordered attempts trail.
+
+    Raises:
+        WorkerTimeoutOutOfBoundsError: When ``timeout_seconds`` is missing,
+            below the floor, or above the ceiling. The CLI maps this to the
+            config-error exit code.
     """
+    require_timeout_within_bounds(timeout_seconds)
     preflight_outcome: PreflightOutcome = spawn_preflight_runner(
         role=role,
         should_ping=False,
@@ -454,7 +465,6 @@ def resolve_worker_spawn(
         prompt_file=prompt_file,
         working_directory=working_directory,
         run_state_directory=run_state_directory,
-        max_turns=max_turns,
         timeout_seconds=timeout_seconds,
     )
     if grok_outcome.is_ok:
@@ -552,7 +562,7 @@ def _exit_code_for_outcome(
     return SPAWN_SERVED_EXIT_CODE
 
 
-def _config_error_outcome(configuration_error: ChainConfigurationError) -> SpawnOutcome:
+def _config_error_outcome(configuration_error: Exception) -> SpawnOutcome:
     return SpawnOutcome(
         tier_used=None,
         is_ok=False,
@@ -574,6 +584,34 @@ def _missing_prompt_file_outcome() -> SpawnOutcome:
     )
 
 
+def _timeout_out_of_bounds_outcome(
+    bounds_error: WorkerTimeoutOutOfBoundsError,
+) -> SpawnOutcome:
+    """Report a refused timeout as a config fault rather than a worker failure.
+
+    ::
+
+        --timeout-seconds 0     ok: attempts[0].reason timeout_out_of_bounds
+        --timeout-seconds 5401  ok: attempts[0].reason timeout_out_of_bounds
+
+    Args:
+        bounds_error: The refusal raised by the headless runner.
+
+    Returns:
+        A config-error outcome whose attempt reason names the violation.
+    """
+    return SpawnOutcome(
+        tier_used=None,
+        is_ok=False,
+        all_attempts=(
+            _attempt(TIER_GROK, is_ok=False, reason=REASON_TIMEOUT_OUT_OF_BOUNDS),
+        ),
+        captured_stdout=str(bounds_error),
+        returncode=SPAWN_CONFIG_ERROR_EXIT_CODE,
+        is_config_error=True,
+    )
+
+
 def _write_spawn_outcome_and_exit_code(
     spawn_outcome: SpawnOutcome, *, is_config_error: bool
 ) -> int:
@@ -588,6 +626,12 @@ def _write_spawn_outcome_and_exit_code(
 def main(all_command_arguments: list[str]) -> int:
     """Run the dispatcher for CLI arguments and print the JSON outcome.
 
+    A timeout outside the accepted bounds is a config fault: the run prints a
+    structured outcome whose attempt reason is ``timeout_out_of_bounds`` and
+    exits ``3``, rather than raising out of the CLI. A chain misconfiguration,
+    or an unknown host profile refused by ``detect_host_profile``, prints the
+    same exit code with the refusal text as its output.
+
     Args:
         all_command_arguments: The argument vector after the program name.
 
@@ -612,9 +656,11 @@ def main(all_command_arguments: list[str]) -> int:
             timeout_seconds=parsed_arguments.timeout_seconds,
             is_claude_tier_enabled=parsed_arguments.is_claude_tier_enabled,
             run_state_directory=run_state_directory,
-            max_turns=DEFAULT_SPAWN_MAX_TURNS,
         )
-    except ChainConfigurationError as configuration_error:
+    except WorkerTimeoutOutOfBoundsError as bounds_error:
+        is_config_error = True
+        spawn_outcome = _timeout_out_of_bounds_outcome(bounds_error)
+    except (ChainConfigurationError, ValueError) as configuration_error:
         is_config_error = True
         spawn_outcome = _config_error_outcome(configuration_error)
     return _write_spawn_outcome_and_exit_code(