claude-dev-env 2.7.0 → 2.7.1

package/_shared/pr-loop/worker-spawn.md

@@ -73,10 +73,12 @@ plus the process exit code.
 
 `resolve_worker_spawn(...)` takes keyword-only arguments:
 `role`, `prompt_file`, `working_directory`, `timeout_seconds`,
-`is_claude_tier_enabled`, `run_state_directory`, `max_turns`.
+`is_claude_tier_enabled`, `run_state_directory`.
 `encode_spawn_outcome` turns a `SpawnOutcome` into the same JSON shape the CLI
 prints.
 
+The grok tier runs with no turn cap; `timeout_seconds` is its only bound.
+
 ## JSON result shape
 
 Stdout is one JSON object:

package/package.json

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

package/scripts/CLAUDE.md

@@ -9,13 +9,13 @@ Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each s
 | `claude_chain_runner.py` | Runs a `claude` invocation through a usage-ranked fallback chain (`~/.claude/claude-chain.json`): probes weekly remaining once via `claude_chain_usage` / the usage-pause OAuth probe, tries the highest-remaining account first, and falls over to the next ranked binary only on a usage-limit failure; usable as an imported module (`run_claude`) or a CLI. Copy `claude-chain.example.json` to `~/.claude/claude-chain.json` and list your account binaries. Optional per-entry `credentials_path` names that account's OAuth credentials file for the usage probe |
 | `claude_chain_usage.py` | Reports remaining weekly usage for every account in `~/.claude/claude-chain.json` via the usage-pause OAuth probe; prints JSON (`accounts` with `weekly_remaining_percent` or null plus `error`); importable `report_chain_weekly_usage` and `rank_accounts_by_weekly_remaining` (highest remaining first, ties keep config order, unmeasurable last). The chain runner consumes this ranking for try 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 |
-| `grok_headless_runner.py` | Runs one worker as headless `grok`: builds argv, mints a unique leader socket, captures streams, kills on timeout with grace, classifies ok/usage_limit/auth_failure/timeout/error; imported by `spawn_grok_batch.py` |
+| `grok_headless_runner.py` | Runs one worker as headless `grok`: builds argv with no turn cap (the timeout is the only bound), mints a unique leader socket, captures streams, refuses a timeout that is missing, below `MIN_WORKER_TIMEOUT_SECONDS`, or above the `MAXIMUM_WORKER_TIMEOUT_SECONDS` (5400) ceiling, kills the whole process tree on timeout with grace and retries the kill-and-drain round once, classifies ok/usage_limit/auth_failure/timeout/kill_failed/error; exports `require_timeout_within_bounds` so a dispatcher can apply the same bounds without launching; imported by `spawn_grok_batch.py` and `resolve_worker_spawn.py` |
 | `grok_worker_preflight.py` | Soft gate for the headless grok tier: binary on PATH, `grok models` auth, install manifest + role agents, opt-in cached live ping; non-zero exit is fallthrough, not failure |
 | `setup_project_paths.py` | One-time bootstrap: discovers git repos via `es.exe` (Everything) and writes `~/.claude/project-paths.json`; never hardcodes scan roots |
-| `spawn_grok_batch.py` | Launches a fleet of headless grok workers from a JSON batch spec: gates once through the preflight, assembles each prompt from part files, staggers starts, runs each through `grok_headless_runner.py`, and emits one batch summary JSON |
+| `spawn_grok_batch.py` | Launches a fleet of headless grok workers from a JSON batch spec: gates once through the preflight, refuses a spec whose `timeout_seconds` exceeds `MAXIMUM_WORKER_TIMEOUT_SECONDS` (5400) rather than clamping it, assembles each prompt from part files, staggers starts, runs each through `grok_headless_runner.py`, and emits one batch summary JSON |
 | `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 |
-| `resolve_worker_spawn.py` | Dispatches a worker role through grok then claude fallback tiers (preflight, headless grok, `claude_agent_required` handoff, optional claude headless); protocol: [`../_shared/pr-loop/worker-spawn.md`](../_shared/pr-loop/worker-spawn.md) |
+| `resolve_worker_spawn.py` | Dispatches a worker role through grok then claude fallback tiers (preflight, headless grok, `claude_agent_required` handoff, optional claude headless); applies `require_timeout_within_bounds` before the preflight, so an out-of-bounds `--timeout-seconds` prints a `timeout_out_of_bounds` outcome and exits 3 on every tier; protocol: [`../_shared/pr-loop/worker-spawn.md`](../_shared/pr-loop/worker-spawn.md) |
 
 ## PowerShell scripts
 

package/scripts/dev_env_scripts_constants/CLAUDE.md

@@ -10,7 +10,7 @@ Named constants for scripts in `scripts/`. Follows the project convention that t
 | `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 (including optional `credentials_path`), invalid-shape reason text, config-error and exhausted-chain message templates, and CLI exit codes; `invoke_code_review.py` and `resolve_worker_spawn.py` - the text-codec keyword names and the `collect_forwarded_text_codec` helper that forwards them to the subprocess runner for text-mode capture |
 | `claude_chain_usage_constants.py` | `claude_chain_usage.py` - full weekly percent scale, usage-pause skill path segments, CLI config-path flag, JSON report keys, and probe error message templates |
-| `grok_worker_constants.py` | `grok_worker_preflight.py`, `grok_headless_runner.py`, and `spawn_grok_batch.py` - the `grok` binary name and CLI flags, model and subcommand tokens, leader-socket and scratch-file name parts, auth and usage-limit signature lists, outcome classifications, fallthrough reasons, tool-profile names and prompt headers, timeouts and turn caps (including launch-failure return code and post-kill grace), ping-cache keys and TTL, batch-spec and summary JSON keys, the prompt-part and report-stream join separators, and the CLI launch-error stderr prefix |
+| `grok_worker_constants.py` | `grok_worker_preflight.py`, `grok_headless_runner.py`, `spawn_grok_batch.py`, and `resolve_worker_spawn.py` - the `grok` binary name and CLI flags, model and subcommand tokens, leader-socket and scratch-file name parts, auth and usage-limit signature lists, outcome classifications, fallthrough reasons, tool-profile names and prompt headers, worker timeouts (default, plus the floor and the `MAXIMUM_WORKER_TIMEOUT_SECONDS` ceiling that the batch spec parse, the headless runner, and the spawn dispatcher all enforce, each bound carrying one rejection template shared by those sites, plus launch-failure return code and post-kill grace), the process-tree kill command, its flags, its attempt limit and kill-failed classification, the preflight ping's single-turn cap, ping-cache keys and TTL, batch-spec and summary JSON keys, the prompt-part and report-stream join separators, and the CLI launch-error stderr prefix |
 | `code_review_constants.py` | `invoke_code_review.py` - the `/code-review ultra --fix` prompt, opus model alias, permission-mode flag and value, result mode and JSON keys, session-model CLI flag, git dirty-check tokens, and in-session return markers |
 | `__init__.py` | Empty package marker |
 

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/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(