claude-dev-env 2.7.0 → 2.8.0

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,8 +18,7 @@ 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",
     )
 """
@@ -24,17 +26,30 @@ Import ``run_headless_worker`` for the outcome object::
 from __future__ import annotations
 
 import subprocess
+import sys
 import uuid
 from dataclasses import dataclass
 from pathlib import Path
 
-from dev_env_scripts_constants.grok_worker_constants import (
+_shared_process_tree_scripts_directory = (
+    Path(__file__).resolve().parents[1] / "_shared" / "process-tree" / "scripts"
+)
+if str(_shared_process_tree_scripts_directory) not in sys.path:
+    sys.path.insert(0, str(_shared_process_tree_scripts_directory))
+
+from process_tree_kill import (  # noqa: E402
+    should_start_new_session,
+    terminate_process_tree,
+)
+
+from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
     AGENT_FLAG,
     ALL_AUTH_FAILURE_SIGNATURES,
     ALL_USAGE_LIMIT_SIGNATURES,
     ALWAYS_APPROVE_FLAG,
     CLASSIFICATION_AUTH_FAILURE,
     CLASSIFICATION_ERROR,
+    CLASSIFICATION_KILL_FAILED,
     CLASSIFICATION_OK,
     CLASSIFICATION_STREAM_JOIN_SEPARATOR,
     CLASSIFICATION_TIMEOUT,
@@ -43,26 +58,41 @@ 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,
     PROMPT_FILE_FLAG,
     TIMEOUT_RETURN_CODE,
     UTF8_DECODE_ERRORS,
     UTF8_ENCODING,
+    WORKER_SPEC_TIMEOUT_KEY,
 )
 
 runner_popen = subprocess.Popen
 
 
+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)
 class GrokRunnerOutcome:
     """Outcome of one headless grok worker invocation.
@@ -90,7 +120,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 +133,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 +207,110 @@ def _resolve_returncode(process: subprocess.Popen[str]) -> int:
     return TIMEOUT_RETURN_CODE
 
 
-def _timeout_outcome(process: subprocess.Popen[str]) -> GrokRunnerOutcome:
-    process.kill()
-    try:
-        captured_stdout, captured_stderr = process.communicate(
-            timeout=KILL_GRACE_TIMEOUT_SECONDS
+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 +357,7 @@ def _invoke_process(
             text=True,
             encoding=UTF8_ENCODING,
             errors=UTF8_DECODE_ERRORS,
+            start_new_session=should_start_new_session(),
         )
     except FileNotFoundError:
         return _missing_binary_outcome()
@@ -254,7 +378,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 +385,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 +403,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 +417,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(

package/scripts/spawn_grok_batch.py

@@ -26,6 +26,7 @@ from pathlib import Path
 
 from dev_env_scripts_constants.grok_worker_constants import (
     ALL_KNOWN_TOOL_PROFILES,
+    ALL_KNOWN_WORKER_SPEC_KEYS,
     BATCH_LAUNCH_ERROR_STDERR_PREFIX,
     BATCH_SPEC_ROLE_KEY,
     BATCH_SPEC_SHOULD_PING_KEY,
@@ -38,14 +39,15 @@ from dev_env_scripts_constants.grok_worker_constants import (
     DEBUG_FILENAME_PREFIX,
     DEBUG_FILENAME_SUFFIX,
     DEFAULT_ROLE,
-    DEFAULT_WORKER_MAX_TURNS,
     DEFAULT_WORKER_TIMEOUT_SECONDS,
     DISABLE_WEB_SEARCH_FLAG,
     DISALLOWED_TOOLS_FLAG,
     LEADER_SOCKET_FILENAME_PREFIX,
     LEADER_SOCKET_FILENAME_SUFFIX,
-    MIN_WORKER_MAX_TURNS,
+    MAXIMUM_WORKER_TIMEOUT_ERROR_TEMPLATE,
+    MAXIMUM_WORKER_TIMEOUT_SECONDS,
     MIN_WORKER_TIMEOUT_SECONDS,
+    MINIMUM_WORKER_TIMEOUT_ERROR_TEMPLATE,
     OUTPUT_FILENAME_PREFIX,
     OUTPUT_FILENAME_SUFFIX,
     PROMPT_FILENAME_PREFIX,
@@ -69,12 +71,13 @@ from dev_env_scripts_constants.grok_worker_constants import (
     SUMMARY_WORKERS_KEY,
     TOOL_PROFILE_BUILD,
     TOOL_PROFILE_READONLY,
+    UNKNOWN_WORKER_KEY_ERROR_TEMPLATE,
     UTF8_ENCODING,
     WORKER_EXCEPTION_RETURN_CODE,
     WORKER_SPEC_AGENT_NAME_KEY,
     WORKER_SPEC_CWD_KEY,
     WORKER_SPEC_IS_REPO_ONLY_KEY,
-    WORKER_SPEC_MAX_TURNS_KEY,
+    WORKER_SPEC_KEY_JOIN_SEPARATOR,
     WORKER_SPEC_PROMPT_PARTS_KEY,
     WORKER_SPEC_ROLE_NAME_KEY,
     WORKER_SPEC_TIMEOUT_KEY,
@@ -89,6 +92,38 @@ batch_headless_runner = run_headless_worker
 batch_preflight = run_preflight
 
 
+def _require_known_worker_keys(all_worker_fields: dict[str, object]) -> None:
+    """Reject a worker entry carrying a key the launcher does not accept.
+
+    ::
+
+        {"role_name": "lens", ..., "timeout_second": <seconds>}
+        flag: unknown worker key(s): timeout_second; accepted keys: agent_name, ...
+
+    A dropped key reads as a setting that took effect. Naming it here makes
+    that a startup error rather than a silent gap.
+
+    Args:
+        all_worker_fields: One raw worker entry straight from the JSON spec.
+
+    Raises:
+        ValueError: When the entry carries any key outside the accepted set.
+    """
+    all_unknown_keys = set(all_worker_fields) - ALL_KNOWN_WORKER_SPEC_KEYS
+    if not all_unknown_keys:
+        return
+    joined_unknown = WORKER_SPEC_KEY_JOIN_SEPARATOR.join(sorted(all_unknown_keys))
+    joined_accepted = WORKER_SPEC_KEY_JOIN_SEPARATOR.join(
+        sorted(ALL_KNOWN_WORKER_SPEC_KEYS)
+    )
+    raise ValueError(
+        UNKNOWN_WORKER_KEY_ERROR_TEMPLATE.format(
+            unknown_keys=joined_unknown,
+            accepted_keys=joined_accepted,
+        )
+    )
+
+
 @dataclass(frozen=True)
 class WorkerSpec:
     """One worker entry from a batch specification."""
@@ -99,7 +134,6 @@ class WorkerSpec:
     tool_profile: str
     timeout_seconds: int
     is_repo_only: bool = False
-    max_turns: int = DEFAULT_WORKER_MAX_TURNS
     agent_name: str | None = None
 
 
@@ -248,18 +282,50 @@ def _require_worker_field(
     return all_worker_fields[field_name]
 
 
-def _require_int_at_least(
-    raw_field: object, field_name: str, minimum_accepted: int
-) -> int:
-    parsed_integer = _require_int(raw_field, field_name)
-    if parsed_integer < minimum_accepted:
+def _require_timeout_within_bounds(raw_field: object) -> int:
+    """Accept a worker timeout inside the bounds; refuse anything outside them.
+
+    ::
+
+        0     flag: ValueError naming MIN_WORKER_TIMEOUT_SECONDS
+        5401  flag: ValueError naming MAXIMUM_WORKER_TIMEOUT_SECONDS
+        5400  ok:   returned untouched
+        30    ok:   returned untouched
+
+    Rejecting here rather than clamping keeps the fault where the operator
+    wrote it. The runner repeats the check for callers that skip the parse.
+
+    Args:
+        raw_field: The parsed ``timeout_seconds`` value from the specification.
+
+    Returns:
+        The accepted timeout in seconds, unchanged.
+
+    Raises:
+        ValueError: When the value is not an int, or falls outside the bounds.
+    """
+    timeout_seconds = _require_int(raw_field, WORKER_SPEC_TIMEOUT_KEY)
+    if timeout_seconds < MIN_WORKER_TIMEOUT_SECONDS:
+        raise ValueError(
+            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 ValueError(
-            f"worker {field_name} must be >= {minimum_accepted}"
+            MAXIMUM_WORKER_TIMEOUT_ERROR_TEMPLATE.format(
+                field_name=WORKER_SPEC_TIMEOUT_KEY,
+                requested_seconds=timeout_seconds,
+                maximum_seconds=MAXIMUM_WORKER_TIMEOUT_SECONDS,
+            )
         )
-    return parsed_integer
+    return timeout_seconds
 
 
 def _parse_worker_entry(all_worker_fields: dict[str, object]) -> WorkerSpec:
+    _require_known_worker_keys(all_worker_fields)
     role_name = _require_string(
         _require_worker_field(all_worker_fields, WORKER_SPEC_ROLE_NAME_KEY),
         WORKER_SPEC_ROLE_NAME_KEY,
@@ -275,22 +341,15 @@ def _parse_worker_entry(all_worker_fields: dict[str, object]) -> WorkerSpec:
         _require_worker_field(all_worker_fields, WORKER_SPEC_TOOL_PROFILE_KEY),
         WORKER_SPEC_TOOL_PROFILE_KEY,
     )
-    timeout_seconds = _require_int_at_least(
+    timeout_seconds = _require_timeout_within_bounds(
         all_worker_fields.get(
             WORKER_SPEC_TIMEOUT_KEY, DEFAULT_WORKER_TIMEOUT_SECONDS
-        ),
-        WORKER_SPEC_TIMEOUT_KEY,
-        MIN_WORKER_TIMEOUT_SECONDS,
+        )
     )
     is_repo_only = _require_bool(
         all_worker_fields.get(WORKER_SPEC_IS_REPO_ONLY_KEY, False),
         WORKER_SPEC_IS_REPO_ONLY_KEY,
     )
-    max_turns = _require_int_at_least(
-        all_worker_fields.get(WORKER_SPEC_MAX_TURNS_KEY, DEFAULT_WORKER_MAX_TURNS),
-        WORKER_SPEC_MAX_TURNS_KEY,
-        MIN_WORKER_MAX_TURNS,
-    )
     agent_name = all_worker_fields.get(WORKER_SPEC_AGENT_NAME_KEY)
     if not isinstance(all_prompt_parts, list) or not all_prompt_parts:
         raise ValueError("worker prompt_parts must be a non-empty list")
@@ -311,7 +370,6 @@ def _parse_worker_entry(all_worker_fields: dict[str, object]) -> WorkerSpec:
         tool_profile=tool_profile,
         timeout_seconds=timeout_seconds,
         is_repo_only=is_repo_only,
-        max_turns=max_turns,
         agent_name=agent_name,
     )
 
@@ -326,7 +384,8 @@ def load_batch_spec(specification_path: Path) -> BatchSpec:
         The validated batch specification.
 
     Raises:
-        ValueError: When the JSON shape is invalid or a required field is wrong.
+        ValueError: When the JSON shape is invalid, a required field is wrong,
+            or a worker entry carries a key outside the accepted set.
         OSError: When the specification file cannot be read.
         json.JSONDecodeError: When the file is not valid JSON.
     """
@@ -423,7 +482,6 @@ def _invoke_worker(
         prompt_file=scratch_paths.prompt_path,
         working_directory=worker_spec.working_directory,
         run_state_directory=run_state_directory,
-        max_turns=worker_spec.max_turns,
         timeout_seconds=worker_spec.timeout_seconds,
         agent_name=worker_spec.agent_name,
         leader_socket_path=scratch_paths.leader_socket_path,