Implementation Plan: Eliminate Silent Discard of stream_idle_timeout_ms in Codex Builders (#4076)

Trecek · claude · web-flow · commit 7f63bc343cd1 · 2026-06-11T22:33:44.000Z
## Summary Add a `process_idle_timeout_ms: int = 0` field to the `CmdSpec` frozen dataclass, wire it through both Codex builder methods (`build_skill_session_cmd` and `build_food_truck_cmd`), and add an override path in `_headless_execute.py` so the existing idle watchdog respects the CmdSpec-carried value. This eliminates the silent `noqa: F841` discard of `stream_idle_timeout_ms` in the Codex backend, making stuck Codex sessions killable by the existing `_watch_stdout_idle` coroutine. ## Implementation Plan Plan file: `/home/talon/projects/autoskillit-runs/impl-20260611-142225-008330/.autoskillit/temp/make-plan/t5_p1_a6_wp1_eliminate_silent_discard_plan_2026-06-11_143500.md` Closes #4003 🤖 Generated with [Claude Code](https://claude.com/claude-code) via AutoSkillit  ## Token Usage Summary | Step | Model | count | uncached | output | cache_read | peak_ctx | turns | cache_write | time | |------|-------|-------|----------|--------|------------|----------|-------|-------------|------| | plan* | opus[1m] | 1 | 83 | 28.7k | 1.5M | 115.0k | 57 | 100.9k | 13m 19s | | verify* | sonnet | 1 | 62 | 18.6k | 324.1k | 74.1k | 21 | 53.2k | 8m 21s | | implement* | MiniMax-M3 | 1 | 2.2M | 11.7k | 0 | 0 | 67 | 0 | 6m 37s | | fix* | sonnet | 1 | 190 | 10.7k | 1.7M | 98.2k | 63 | 77.3k | 8m 12s | | audit_impl* | sonnet | 1 | 52 | 8.2k | 207.1k | 42.1k | 15 | 31.0k | 4m 58s | | prepare_pr* | MiniMax-M3 | 1 | 197.8k | 3.0k | 0 | 0 | 12 | 0 | 1m 2s | | compose_pr* | MiniMax-M3 | 1 | 251.0k | 1.8k | 0 | 0 | 15 | 0 | 49s | | **Total** | | | 2.7M | 82.5k | 3.8M | 115.0k | | 262.4k | 43m 21s | \* *Step used a non-Anthropic provider; caching behavior may differ.* ## Token Efficiency | Step | LoC Changed | cache_read/LoC | cache_write/LoC | output/LoC | |------|-------------|----------------|-----------------|------------| | plan | 0 | — | — | — | | verify | 0 | — | — | — | | implement | 217 | 0.0 | 0.0 | 53.9 | | fix | 12 | 145016.6 | 6439.9 | 890.7 | | audit_impl | 0 | — | — | — | | prepare_pr | 0 | — | — | — | | compose_pr | 0 | — | — | — | | **Total** | **229** | 16390.1 | 1145.7 | 360.5 | ## Model Usage Breakdown | Model | steps | uncached | output | cache_read | cache_write | time | |-------|-------|----------|--------|------------|-------------|------| | opus[1m] | 1 | 83 | 28.7k | 1.5M | 100.9k | 13m 19s | | sonnet | 3 | 304 | 37.4k | 2.3M | 161.5k | 21m 32s | | MiniMax-M3 | 3 | 2.7M | 16.4k | 0 | 0 | 8m 29s | --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
diff --git a/src/autoskillit/core/types/_type_backend.py b/src/autoskillit/core/types/_type_backend.py
@@ -263,6 +263,7 @@ class CmdSpec:
     cwd: str = ""
     origin: CmdOrigin | None = None
     is_resume: bool = False
+    process_idle_timeout_ms: int = 0
 
 
 @dataclass(frozen=True, slots=True)
diff --git a/src/autoskillit/execution/backends/codex.py b/src/autoskillit/execution/backends/codex.py
@@ -626,7 +626,7 @@ def build_skill_session_cmd(
             output_format = config.output_format  # noqa: F841  # no-op: --json is unconditional for Codex
             add_dirs = config.add_dirs
             exit_after_stop_delay_ms = config.exit_after_stop_delay_ms  # noqa: F841  # no-op: Claude-only
-            stream_idle_timeout_ms = config.stream_idle_timeout_ms  # noqa: F841  # no-op: Claude-only
+            stream_idle_timeout_ms = config.stream_idle_timeout_ms
             scenario_step_name = config.scenario_step_name
             temp_dir_relpath = config.temp_dir_relpath
             allowed_write_prefix = config.allowed_write_prefix
@@ -724,7 +724,13 @@ def build_skill_session_cmd(
             cmd.append(resume_session_id)
         cmd.append(prompt)
 
-        return CmdSpec(cmd=tuple(cmd), env=env, cwd=cwd, is_resume=bool(resume_session_id))
+        return CmdSpec(
+            cmd=tuple(cmd),
+            env=env,
+            cwd=cwd,
+            is_resume=bool(resume_session_id),
+            process_idle_timeout_ms=stream_idle_timeout_ms,
+        )
 
     def build_food_truck_cmd(
         self,
@@ -750,7 +756,6 @@ def build_food_truck_cmd(
         _plugin_source = plugin_source  # noqa: F841  # no-op: Codex has no --plugin-dir
         _output_format = output_format  # noqa: F841  # no-op: --json is unconditional
         _exit_ms = exit_after_stop_delay_ms  # noqa: F841  # no-op: Claude-only
-        _stream_ms = stream_idle_timeout_ms  # noqa: F841  # no-op: Claude-only
 
         if resume_session_id:
             effective_prompt = _compose_resume_prompt(
@@ -823,7 +828,13 @@ def build_food_truck_cmd(
             cmd.append(resume_session_id)
         cmd.append(prompt)
 
-        return CmdSpec(cmd=tuple(cmd), env=env, cwd=cwd, is_resume=bool(resume_session_id))
+        return CmdSpec(
+            cmd=tuple(cmd),
+            env=env,
+            cwd=cwd,
+            is_resume=bool(resume_session_id),
+            process_idle_timeout_ms=stream_idle_timeout_ms,
+        )
 
     def build_interactive_cmd(
         self,
diff --git a/src/autoskillit/execution/headless/_headless_execute.py b/src/autoskillit/execution/headless/_headless_execute.py
@@ -140,6 +140,10 @@ async def _execute_claude_headless(
         else:
             _raw_idle = float(cfg.idle_output_timeout)
     effective_idle: float | None = _raw_idle if _raw_idle > 0.0 else None
+    if spec.process_idle_timeout_ms > 0:
+        _spec_idle = spec.process_idle_timeout_ms / 1000.0
+        if effective_idle is None or _spec_idle < effective_idle:
+            effective_idle = _spec_idle
 
     current_provider_name: str = provider_name
     fallback_activated: bool = False
diff --git a/tests/_test_filter.py b/tests/_test_filter.py
@@ -649,7 +649,7 @@ class ImportContext(enum.StrEnum):
             "execution/test_headless_result_write_reconciliation.py",
             "execution/test_planner_write_isolation.py",
             "execution/test_session_log_flush.py",
-            # execution/ — fixture-mediated pipeline dependents (15 files):
+            # execution/ — fixture-mediated pipeline dependents (16 files):
             # These use minimal_ctx or tool_ctx fixtures which import
             # autoskillit.pipeline at call time. Validated by REQ-GUARD-007.
             "execution/test_backend_dispatch.py",
@@ -662,6 +662,7 @@ class ImportContext(enum.StrEnum):
             "execution/test_headless_dispatch.py",
             "execution/test_headless_env_injection.py",
             "execution/test_headless_env_scrub.py",
+            "execution/test_headless_execute.py",
             "execution/test_headless_provider_fallback.py",
             "execution/test_headless_synthesis.py",
             "execution/test_idle_output_env.py",
diff --git a/tests/arch/test_cascade_map_guard.py b/tests/arch/test_cascade_map_guard.py
@@ -680,6 +680,7 @@ def test_every_file_level_entry_references_existing_test(self) -> None:
             "execution/test_headless_dispatch.py",
             "execution/test_headless_env_injection.py",
             "execution/test_headless_env_scrub.py",
+            "execution/test_headless_execute.py",
             "execution/test_headless_provider_fallback.py",
             "execution/test_headless_synthesis.py",
             "execution/test_idle_output_env.py",
diff --git a/tests/arch/test_execution_source_split.py b/tests/arch/test_execution_source_split.py
@@ -18,7 +18,7 @@
 HEADLESS_SIZE_BUDGETS = {
     "headless/__init__.py": 490,
     "headless/_headless_helpers.py": 220,
-    "headless/_headless_execute.py": 610,
+    "headless/_headless_execute.py": 616,
     "headless/_headless_recovery.py": 370,
     "headless/_headless_path_tokens.py": 190,
     "headless/_headless_result.py": 865,
diff --git a/tests/arch/test_subpackage_isolation.py b/tests/arch/test_subpackage_isolation.py
@@ -979,7 +979,7 @@ def test_data_directories_are_not_python_packages() -> None:
         "dispatch gate add defense-in-depth checks",
     ),
     "execution/backends/codex.py": (
-        1045,
+        1060,
         "REQ-CNST-010-E9: Codex backend — skill_sigil capability threading adds multi-line "
         "keyword args to _ensure_skill_prefix call sites and _has_prefix guard; "
         "write_guard_tool_names env injection adds 7 lines to _codex_exec_extras; "
@@ -989,7 +989,9 @@ def test_data_directories_are_not_python_packages() -> None:
         "promoted from locate_session parameter to frozen dataclass field (3 net lines: "
         "field declaration, blank line between field and method, SessionLocator in import block)"
         "; project_log_dir method added to CodexSessionLocator (+3 net lines)"
-        "; session_log_path method added to CodexSessionLocator (+5 net lines)",
+        "; session_log_path method added to CodexSessionLocator (+5 net lines)"
+        "; process_idle_timeout_ms field wired through build_skill_session_cmd and "
+        "build_food_truck_cmd CmdSpec constructors (+8 net lines)",
     ),
 }
 
diff --git a/tests/core/test_backend_dataclasses.py b/tests/core/test_backend_dataclasses.py
@@ -23,7 +23,7 @@ def test_cmd_spec_fields():
     from autoskillit.core import CmdSpec
 
     fields = {f.name for f in dataclasses.fields(CmdSpec)}
-    assert fields == {"cmd", "env", "cwd", "origin", "is_resume"}
+    assert fields == {"cmd", "env", "cwd", "origin", "is_resume", "process_idle_timeout_ms"}
 
 
 def test_cmd_spec_is_resume_default():
@@ -33,6 +33,13 @@ def test_cmd_spec_is_resume_default():
     assert spec.is_resume is False
 
 
+def test_cmd_spec_process_idle_timeout_default():
+    from autoskillit.core import CmdSpec
+
+    spec = CmdSpec(cmd=(), env={})
+    assert spec.process_idle_timeout_ms == 0
+
+
 def test_cmd_spec_env_accepts_mapping():
     from collections.abc import Mapping
 
diff --git a/tests/execution/backends/test_codex_backend.py b/tests/execution/backends/test_codex_backend.py
@@ -626,6 +626,13 @@ def test_claude_only_params_accepted_but_ignored(self) -> None:
         assert "--plugin-dir" not in cmd_str
         assert "CLAUDE_CODE_EXIT_AFTER_STOP_DELAY" not in spec.env
         assert "CLAUDE_STREAM_IDLE_TIMEOUT_MS" not in spec.env
+        assert spec.process_idle_timeout_ms == 3000
+
+    def test_stream_idle_timeout_routed_to_cmdspec(self) -> None:
+        spec = CodexBackend().build_skill_session_cmd(
+            **{**self.BASE, "stream_idle_timeout_ms": 30000}
+        )
+        assert spec.process_idle_timeout_ms == 30000
 
     def test_cwd_set(self) -> None:
         spec = CodexBackend().build_skill_session_cmd(
@@ -1078,6 +1085,12 @@ def test_bypass_hook_trust_present_in_food_truck_cmd(self) -> None:
         spec = CodexBackend().build_food_truck_cmd(**self.BASE)
         assert "--dangerously-bypass-hook-trust" in spec.cmd
 
+    def test_stream_idle_timeout_routed_to_cmdspec(self) -> None:
+        spec = CodexBackend().build_food_truck_cmd(
+            **{**self.BASE, "stream_idle_timeout_ms": 60000}
+        )
+        assert spec.process_idle_timeout_ms == 60000
+
 
 class TestCodexEnsurePreLaunchConfigValidation:
     @pytest.fixture(autouse=True)
@@ -1516,6 +1529,73 @@ def test_conventions_skills_subdir(self) -> None:
         assert CodexBackend().conventions.skills_subdir == Path("skills")
 
 
+class TestClaudeCodeBackendProcessIdleDefault:
+    def test_claude_code_backend_process_idle_default_zero(self) -> None:
+        from autoskillit.execution.backends.claude import ClaudeCodeBackend
+
+        spec = ClaudeCodeBackend().build_skill_session_cmd(
+            "/test-skill",
+            cwd="/work",
+            completion_marker="%%DONE%%",
+        )
+        assert spec.process_idle_timeout_ms == 0
+
+
+class TestCodexDiscardDispositions:
+    """Document the complete noqa:F841 discard disposition picture in codex.py.
+
+    stream_idle_timeout_ms -> routed to CmdSpec.process_idle_timeout_ms (P1-A6-WP1).
+    plugin_source, output_format, exit_after_stop_delay_ms -> intentional
+    no-op discards (P2-A2 scope).
+    """
+
+    def test_stream_idle_timeout_routed_in_skill_builder(self) -> None:
+        spec = CodexBackend().build_skill_session_cmd(
+            skill_command="/test",
+            cwd="/work",
+            completion_marker="%%DONE%%",
+            stream_idle_timeout_ms=10000,
+        )
+        assert spec.process_idle_timeout_ms == 10000
+
+    def test_stream_idle_timeout_routed_in_food_truck_builder(self) -> None:
+        spec = CodexBackend().build_food_truck_cmd(
+            orchestrator_prompt="go",
+            plugin_source=DirectInstall(plugin_dir=Path("/pkg")),
+            cwd="/work",
+            completion_marker="%%DONE%%",
+            stream_idle_timeout_ms=20000,
+        )
+        assert spec.process_idle_timeout_ms == 20000
+
+    def test_exit_after_stop_delay_still_discarded(self) -> None:
+        spec = CodexBackend().build_skill_session_cmd(
+            skill_command="/test",
+            cwd="/work",
+            completion_marker="%%DONE%%",
+            exit_after_stop_delay_ms=5000,
+        )
+        assert "CLAUDE_CODE_EXIT_AFTER_STOP_DELAY" not in spec.env
+
+    def test_plugin_source_still_discarded(self) -> None:
+        spec = CodexBackend().build_skill_session_cmd(
+            skill_command="/test",
+            cwd="/work",
+            completion_marker="%%DONE%%",
+            plugin_source=DirectInstall(plugin_dir=Path("/pkg")),
+        )
+        assert "--plugin-dir" not in " ".join(spec.cmd)
+
+    def test_output_format_still_discarded(self) -> None:
+        spec = CodexBackend().build_skill_session_cmd(
+            skill_command="/test",
+            cwd="/work",
+            completion_marker="%%DONE%%",
+            output_format=OutputFormat.STREAM_JSON,
+        )
+        assert "--json" in spec.cmd
+
+
 class TestCodexBackendSetupSessionDir:
     @pytest.fixture(autouse=True)
     def _setup_dirs(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
diff --git a/tests/execution/test_headless_execute.py b/tests/execution/test_headless_execute.py
@@ -2,13 +2,35 @@
 
 from __future__ import annotations
 
+import json
+from pathlib import Path
+
 import pytest
 
 from autoskillit.core import CmdSpec
+from autoskillit.core.types import SubprocessResult, TerminationReason
 
 pytestmark = [pytest.mark.layer("execution"), pytest.mark.small]
 
 
+def _success_result() -> SubprocessResult:
+    return SubprocessResult(
+        returncode=0,
+        stdout=json.dumps(
+            {
+                "type": "result",
+                "subtype": "success",
+                "is_error": False,
+                "result": "done",
+                "session_id": "sess-idle-test",
+            }
+        ),
+        stderr="",
+        termination=TerminationReason.NATURAL_EXIT,
+        pid=12345,
+    )
+
+
 def test_assert_headless_cmd_passes_with_p_flag() -> None:
     from autoskillit.execution.headless._headless_helpers import assert_headless_cmd
 
@@ -32,3 +54,85 @@ def test_assert_headless_cmd_empty_cmd_no_error() -> None:
     from autoskillit.execution.headless._headless_helpers import assert_headless_cmd
 
     assert_headless_cmd(CmdSpec(cmd=(), env={}))
+
+
+class TestProcessIdleTimeoutOverride:
+    """Tests for CmdSpec.process_idle_timeout_ms overriding effective_idle."""
+
+    @pytest.mark.anyio
+    async def test_spec_idle_used_when_caller_supplies_none(
+        self, minimal_ctx, tmp_path: Path, monkeypatch
+    ) -> None:
+        from autoskillit.execution.headless import run_headless_core
+        from tests.execution.conftest import _mock_backend
+        from tests.fakes import MockSubprocessRunner
+
+        monkeypatch.delenv("AUTOSKILLIT_IDLE_OUTPUT_TIMEOUT", raising=False)
+        runner = MockSubprocessRunner()
+        runner.set_default(_success_result())
+        minimal_ctx.runner = runner
+        backend = _mock_backend(pty_required=True, channel_b_capable=True)
+        backend.build_skill_session_cmd.return_value = CmdSpec(
+            cmd=("claude", "-p", "test"),
+            env={},
+            process_idle_timeout_ms=30000,
+        )
+        minimal_ctx.backend = backend
+
+        await run_headless_core("/test foo", str(tmp_path), minimal_ctx)
+
+        assert runner.call_args_list, "runner was never called"
+        _cmd, _cwd, _timeout, kwargs = runner.call_args_list[0]
+        assert kwargs.get("idle_output_timeout") == 30.0
+
+    @pytest.mark.anyio
+    async def test_spec_idle_overrides_when_smaller(
+        self, minimal_ctx, tmp_path: Path, monkeypatch
+    ) -> None:
+        from autoskillit.execution.headless import run_headless_core
+        from tests.execution.conftest import _mock_backend
+        from tests.fakes import MockSubprocessRunner
+
+        monkeypatch.setenv("AUTOSKILLIT_IDLE_OUTPUT_TIMEOUT", "45")
+        runner = MockSubprocessRunner()
+        runner.set_default(_success_result())
+        minimal_ctx.runner = runner
+        backend = _mock_backend(pty_required=True, channel_b_capable=True)
+        backend.build_skill_session_cmd.return_value = CmdSpec(
+            cmd=("claude", "-p", "test"),
+            env={},
+            process_idle_timeout_ms=15000,
+        )
+        minimal_ctx.backend = backend
+
+        await run_headless_core("/test foo", str(tmp_path), minimal_ctx)
+
+        assert runner.call_args_list, "runner was never called"
+        _cmd, _cwd, _timeout, kwargs = runner.call_args_list[0]
+        assert kwargs.get("idle_output_timeout") == 15.0
+
+    @pytest.mark.anyio
+    async def test_zero_spec_idle_leaves_effective_unaffected(
+        self, minimal_ctx, tmp_path: Path, monkeypatch
+    ) -> None:
+        from autoskillit.execution.headless import run_headless_core
+        from tests.execution.conftest import _mock_backend
+        from tests.fakes import MockSubprocessRunner
+
+        monkeypatch.setenv("AUTOSKILLIT_IDLE_OUTPUT_TIMEOUT", "30")
+        runner = MockSubprocessRunner()
+        runner.set_default(_success_result())
+        minimal_ctx.runner = runner
+        backend = _mock_backend(pty_required=True, channel_b_capable=True)
+        backend.build_skill_session_cmd.return_value = CmdSpec(
+            cmd=("claude", "-p", "test"),
+            env={},
+            process_idle_timeout_ms=0,
+        )
+        minimal_ctx.backend = backend
+
+        await run_headless_core("/test foo", str(tmp_path), minimal_ctx)
+
+        assert runner.call_args_list, "runner was never called"
+        _cmd, _cwd, _timeout, kwargs = runner.call_args_list[0]
+        assert kwargs.get("idle_output_timeout") == 30.0
