benchflow 0.6.7.dev1829__tar.gz → 0.6.7.dev1831__tar.gz

{benchflow-0.6.7.dev1829 → benchflow-0.6.7.dev1831}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: benchflow
-Version: 0.6.7.dev1829
+Version: 0.6.7.dev1831
 Summary: Multi-turn agent benchmarking with ACP — run any agent, any model, any provider.
 Project-URL: Homepage, https://github.com/benchflow-ai/benchflow
 Project-URL: Repository, https://github.com/benchflow-ai/benchflow

{benchflow-0.6.7.dev1829 → benchflow-0.6.7.dev1831}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "benchflow"
-version = "0.6.7.dev1829"
+version = "0.6.7.dev1831"
 description = "Multi-turn agent benchmarking with ACP — run any agent, any model, any provider."
 readme = "README.md"
 requires-python = ">=3.12"

{benchflow-0.6.7.dev1829 → benchflow-0.6.7.dev1831}/src/benchflow/acp/container_transport.py

@@ -6,12 +6,58 @@ from pathlib import Path
 from typing import Any, TextIO
 
 from benchflow.sandbox.process import LiveProcess
+from benchflow.sandbox.process._base import _ANSI_CSI_RE, _ANSI_OSC_RE
 
 from .transport import Transport, decode_json_rpc_message
 
 logger = logging.getLogger(__name__)
 
 
+def _decode_pty_json_rpc_message(text: str) -> dict[str, Any] | None:
+    """Decode one JSON-RPC message from a line that may carry PTY noise.
+
+    Daytona's PTY transport gives the agent a real terminal, so the shell
+    prompt (with its CSI/OSC escape sequences) can land on the SAME line as
+    the agent's first protocol message — observed on BugSwarm-style images
+    as ``\\x1b[?2004h\\x1b]0;root@…\\x07root@…# \\x1b[?2004l{"jsonrpc":…}``.
+    Whole-line ``json.loads`` fails on that prefix, the response is treated
+    as non-protocol noise, and the handshake "times out" with the completed
+    initialize JSON sitting in the captured agent log — at ANY timeout.
+
+    Recovery is bounded to where the bug lives: :meth:`ContainerTransport.
+    receive` calls this lenient path only until the first successfully
+    decoded protocol message per connection (prompt glue is by construction
+    a pre-first-message PTY phenomenon), and stdio pipes keep the strict
+    whole-line contract in :func:`decode_json_rpc_message`.
+
+    1. fast path — the plain whole-line decode, unchanged;
+    2. retry from the first ``{`` when it is not at position 0 (drops a
+       glued prompt prefix);
+    3. if the line carries ``\\x1b``, strip CSI/OSC sequences (drops escapes
+       trailing or embedded around the JSON) and retry from the first ``{``.
+
+    Every retry still goes through :func:`decode_json_rpc_message`, so the
+    JSON-RPC 2.0 envelope check keeps rejecting agent log lines that merely
+    contain JSON (e.g. ``INFO {"jsonrpc": …}`` with a bad envelope).
+    """
+    message = decode_json_rpc_message(text)
+    if message is not None:
+        return message
+    if "{" not in text:
+        return None
+    brace = text.index("{")
+    if brace:  # brace == 0 would just repeat the whole-line decode
+        message = decode_json_rpc_message(text[brace:])
+        if message is not None:
+            return message
+    if "\x1b" not in text:
+        return None
+    cleaned = _ANSI_CSI_RE.sub("", _ANSI_OSC_RE.sub("", text))
+    if "{" not in cleaned:
+        return None
+    return decode_json_rpc_message(cleaned[cleaned.index("{") :])
+
+
 class ContainerTransport(Transport):
     """ACP transport that speaks to an agent running inside a sandbox.
 
@@ -34,6 +80,12 @@ class ContainerTransport(Transport):
         self._cwd = cwd
         self._agent_log_path = agent_log_path
         self._agent_log_file: TextIO | None = None
+        # First-message latch: the lenient PTY-noise decode applies only
+        # until the first successfully decoded protocol message (prompt glue
+        # is a startup phenomenon). Afterwards the strict whole-line decode
+        # rules, so an agent echoing valid protocol envelopes into its logs
+        # mid-session can never impersonate protocol traffic.
+        self._saw_protocol = False
 
     async def start(self) -> None:
         """Start the agent process inside the sandbox."""
@@ -65,8 +117,12 @@ class ContainerTransport(Transport):
             text = line.decode(errors="replace").strip()
             if not text:
                 continue
-            message = decode_json_rpc_message(text)
+            if self._saw_protocol:
+                message = decode_json_rpc_message(text)
+            else:
+                message = _decode_pty_json_rpc_message(text)
             if message is not None:
+                self._saw_protocol = True
                 return message
             # Capture non-protocol output (agent debug logs, errors, warnings).
             if self._agent_log_path:

{benchflow-0.6.7.dev1829 → benchflow-0.6.7.dev1831}/src/benchflow/acp/runtime.py

@@ -6,10 +6,11 @@ Owns the live agent-side of a run:
     - execute_prompts: send each prompt through the session, capture the
       ACP-native trajectory, and report tool-call counts
 
-The one allowed horizontal phase import in this refactor lives here:
-``from benchflow.sandbox.lockdown import build_priv_drop_cmd``. connect_acp wraps
-the agent launch command in the sandbox user's privilege-drop prefix
-before handing it to the transport. It is a single pure-function call
+The allowed horizontal phase imports in this refactor live here:
+``from benchflow.sandbox.lockdown import build_priv_drop_cmd`` (connect_acp
+wraps the agent launch command in the sandbox user's privilege-drop prefix
+before handing it to the transport) and the shared timeout-env parser from
+``benchflow.sandbox.process._base``. Both are single pure-function calls
 with no shared state — not a coupling of concerns.
 
 Does not own:
@@ -46,6 +47,7 @@ from benchflow.sandbox.lockdown import (
     build_priv_drop_cmd,
     enforce_agent_egress_firewall,
 )
+from benchflow.sandbox.process._base import _timeout_sec_from_env
 from benchflow.trajectories._capture import _capture_session_trajectory
 
 # Re-exported for backwards compatibility — tests and downstream code
@@ -65,10 +67,27 @@ logger = logging.getLogger(__name__)
 _ACP_CONNECT_MAX_RETRIES = 3
 _ACP_CONNECT_BASE_DELAY = 2.0
 _PROMPT_CANCEL_DRAIN_TIMEOUT_SEC = 0.25
-_ACP_HANDSHAKE_TIMEOUT_SEC = 60
+_ACP_HANDSHAKE_TIMEOUT_ENV = "BENCHFLOW_ACP_HANDSHAKE_TIMEOUT"
+_ACP_HANDSHAKE_TIMEOUT_DEFAULT_SEC = 60.0
 _OPENHANDS_DISABLE_SUBAGENTS_ENV = "BENCHFLOW_OPENHANDS_DISABLE_SUBAGENTS"
 
 
+def _acp_handshake_timeout_sec() -> float:
+    """Effective timeout for the pre-prompt ACP handshake, in seconds.
+
+    Agent startup cost scales with the task image — heavyweight images
+    (workspace scanning, kernel prep) can push the ``initialize`` response
+    past the 60s default, so operators can override it with
+    ``BENCHFLOW_ACP_HANDSHAKE_TIMEOUT`` (seconds). Parsing (use-time read,
+    positive-float validation, warn-and-fall-back) is shared with the other
+    transport timeout knobs in :mod:`benchflow.sandbox.process._base`.
+    """
+    return _timeout_sec_from_env(
+        _ACP_HANDSHAKE_TIMEOUT_ENV,
+        _ACP_HANDSHAKE_TIMEOUT_DEFAULT_SEC,
+    )
+
+
 async def _prepare_openhands_direct_execution(
     env,
     *,
@@ -129,13 +148,11 @@ async def _prepare_openhands_direct_execution(
 
 
 async def _wait_for_acp_handshake(awaitable, *, phase: str):
+    timeout_sec = _acp_handshake_timeout_sec()
     try:
-        return await asyncio.wait_for(awaitable, timeout=_ACP_HANDSHAKE_TIMEOUT_SEC)
+        return await asyncio.wait_for(awaitable, timeout=timeout_sec)
     except TimeoutError as e:
-        msg = (
-            f"ACP {phase} timed out after {_ACP_HANDSHAKE_TIMEOUT_SEC}s "
-            "before the first prompt"
-        )
+        msg = f"ACP {phase} timed out after {timeout_sec:g}s before the first prompt"
         raise TransportClosedError(
             msg,
             TransportClosedDiagnostic(

{benchflow-0.6.7.dev1829 → benchflow-0.6.7.dev1831}/src/benchflow/sandbox/process/_base.py

@@ -23,6 +23,7 @@ from __future__ import annotations
 import asyncio
 import contextlib
 import logging
+import os
 import re
 from abc import ABC, abstractmethod
 
@@ -33,6 +34,41 @@ _DIAG_TRUNCATE = 2000  # max chars for diagnostic stderr in error messages
 _BOOTSTRAP_DONE = "__BENCHFLOW_BOOTSTRAP_DONE__"
 _ENV_KEY_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
 
+# Terminal control sequences a PTY-backed transport can interleave with
+# protocol output: ECMA-48 CSI (parameter bytes 0x30-0x3F, intermediate
+# bytes 0x20-0x2F, one final byte 0x40-0x7E) and OSC (BEL- or ST-terminated,
+# e.g. the ``\x1b]0;<title>\x07`` window-title update shell prompts emit).
+# One canonical pair — the AgentCore stdout chunker and the ACP container
+# transport must not drift apart on what counts as terminal noise.
+_ANSI_CSI_PATTERN = r"\x1b\[[0-?]*[ -/]*[@-~]"
+_ANSI_OSC_PATTERN = r"\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)"
+_ANSI_CSI_RE = re.compile(_ANSI_CSI_PATTERN)
+_ANSI_OSC_RE = re.compile(_ANSI_OSC_PATTERN)
+_ANSI_CSI_RE_BYTES = re.compile(_ANSI_CSI_PATTERN.encode())
+_ANSI_OSC_RE_BYTES = re.compile(_ANSI_OSC_PATTERN.encode())
+
+
+def _timeout_sec_from_env(env_var: str, default: float) -> float:
+    """Read a positive seconds value from *env_var*, else *default*.
+
+    The one parser for operator-tunable timeout knobs on this plane (PTY
+    readline timeouts, the ACP handshake window). Read at use time so
+    long-lived processes and tests see env changes. Unset or empty means
+    the default; non-numeric, non-positive, or NaN values warn and fall
+    back rather than disabling or breaking the guarded wait.
+    """
+    raw = os.environ.get(env_var)
+    if raw is None or not raw.strip():
+        return default
+    try:
+        value = float(raw)
+    except ValueError:
+        value = float("nan")
+    if not value > 0:  # also rejects NaN
+        logger.warning("Invalid %s=%r; using default %.0fs", env_var, raw, default)
+        return default
+    return value
+
 
 async def drain_oversized_line(reader: asyncio.StreamReader) -> int:
     """Drain an oversized line from *reader* after a buffer overflow.

{benchflow-0.6.7.dev1829 → benchflow-0.6.7.dev1831}/src/benchflow/sandbox/process/agentcore.py

@@ -19,12 +19,17 @@ from __future__ import annotations
 import asyncio
 import contextlib
 import logging
-import re
 import shlex
 import uuid
 from typing import Any
 
-from benchflow.sandbox.process._base import _ENV_KEY_RE, LiveProcess
+from benchflow.sandbox.process._base import (
+    _ANSI_CSI_RE_BYTES,
+    _ANSI_OSC_RE_BYTES,
+    _ENV_KEY_RE,
+    LiveProcess,
+    _timeout_sec_from_env,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -38,26 +43,10 @@ _READER_ENDED = object()
 _START_MARKER_TIMEOUT_SEC = 180
 _READLINE_TIMEOUT_ENV = "BENCHFLOW_AGENTCORE_READLINE_TIMEOUT"
 _READLINE_TIMEOUT_DEFAULT_SEC = 900.0
-_ANSI_CSI_RE = re.compile(rb"\x1b\[[0-?]*[ -/]*[@-~]")
 
 
 def _readline_timeout_sec() -> float:
-    import os
-
-    value = os.environ.get(_READLINE_TIMEOUT_ENV)
-    if value is None:
-        return _READLINE_TIMEOUT_DEFAULT_SEC
-    try:
-        timeout = float(value)
-    except ValueError:
-        logger.warning(
-            "Invalid %s=%r; using default %.0fs",
-            _READLINE_TIMEOUT_ENV,
-            value,
-            _READLINE_TIMEOUT_DEFAULT_SEC,
-        )
-        return _READLINE_TIMEOUT_DEFAULT_SEC
-    return timeout if timeout > 0 else _READLINE_TIMEOUT_DEFAULT_SEC
+    return _timeout_sec_from_env(_READLINE_TIMEOUT_ENV, _READLINE_TIMEOUT_DEFAULT_SEC)
 
 
 class AgentCoreProcess(LiveProcess):
@@ -119,9 +108,12 @@ class AgentCoreProcess(LiveProcess):
                     line, self._partial = self._partial.split(b"\n", 1)
                     # Bash/readline emits bracketed-paste CSI sequences when a
                     # command takes over the PTY, including a standalone
-                    # ``ESC[?2004l`` *after* the startup marker. Those bytes
-                    # are terminal state, never ACP JSON-RPC.
-                    line = _ANSI_CSI_RE.sub(b"", line.replace(b"\r", b""))
+                    # ``ESC[?2004l`` *after* the startup marker, and shell
+                    # prompts emit OSC window-title updates. Those bytes are
+                    # terminal state, never ACP JSON-RPC.
+                    line = line.replace(b"\r", b"")
+                    line = _ANSI_OSC_RE_BYTES.sub(b"", line)
+                    line = _ANSI_CSI_RE_BYTES.sub(b"", line)
                     if line:
                         await self._line_buffer.put(line + b"\n")
         except asyncio.CancelledError:
@@ -308,8 +300,10 @@ class AgentCoreProcess(LiveProcess):
             # before echo suppression takes effect. Substring matching accepts
             # that echoed command and releases startup too early, putting the
             # prompt/command noise into ACP's JSON-RPC stream. The real marker
-            # is its own line, possibly wrapped in bracketed-paste ANSI codes.
-            text = _ANSI_CSI_RE.sub(b"", line).decode(errors="replace").strip()
+            # is its own line, possibly wrapped in bracketed-paste ANSI codes
+            # or an OSC window-title update from the shell prompt.
+            cleaned = _ANSI_CSI_RE_BYTES.sub(b"", _ANSI_OSC_RE_BYTES.sub(b"", line))
+            text = cleaned.decode(errors="replace").strip()
             if text == marker:
                 return
 

{benchflow-0.6.7.dev1829 → benchflow-0.6.7.dev1831}/src/benchflow/sandbox/process/daytona.py

@@ -18,6 +18,7 @@ from benchflow.sandbox.process._base import (
     _ENV_KEY_RE,
     LiveProcess,
     SubprocessLiveProcess,
+    _timeout_sec_from_env,
 )
 
 logger = logging.getLogger(__name__)
@@ -30,22 +31,10 @@ _DAYTONA_SSH_SERVER_ALIVE_COUNT_MAX = 12
 
 
 def _daytona_pty_readline_timeout_sec() -> float:
-    value = os.environ.get(_DAYTONA_PTY_READLINE_TIMEOUT_ENV)
-    if value is None:
-        return _DAYTONA_PTY_READLINE_TIMEOUT_DEFAULT_SEC
-    try:
-        timeout = float(value)
-    except ValueError:
-        logger.warning(
-            "Invalid %s=%r; using default %.0fs",
-            _DAYTONA_PTY_READLINE_TIMEOUT_ENV,
-            value,
-            _DAYTONA_PTY_READLINE_TIMEOUT_DEFAULT_SEC,
-        )
-        return _DAYTONA_PTY_READLINE_TIMEOUT_DEFAULT_SEC
-    if timeout <= 0:
-        return _DAYTONA_PTY_READLINE_TIMEOUT_DEFAULT_SEC
-    return timeout
+    return _timeout_sec_from_env(
+        _DAYTONA_PTY_READLINE_TIMEOUT_ENV,
+        _DAYTONA_PTY_READLINE_TIMEOUT_DEFAULT_SEC,
+    )
 
 
 async def _cleanup_daytona_remote_env_file(

{benchflow-0.6.7.dev1829 → benchflow-0.6.7.dev1831}/tests/test_acp.py

@@ -613,6 +613,132 @@ class TestTransportProtocolFiltering:
         )
 
 
+class TestContainerTransportPtyNoise:
+    """PTY-glued shell noise must not hide a protocol message on the same line.
+
+    Daytona's PTY transport gives the agent a real terminal; on BugSwarm-style
+    images the shell prompt (bracketed-paste CSI + OSC window title) lands on
+    the SAME pty line as the agent's initialize response. Whole-line json.loads
+    fails, the response is filed as non-protocol noise, and the handshake
+    "times out" at ANY window with the completed JSON sitting in the agent log
+    (observed 6/6 on fix-build-agentops at both 60s and 300s).
+    """
+
+    # Exact shape captured from the failing run's agent/prime_agent.txt:
+    # bracketed-paste on, OSC 0 window title, prompt, bracketed-paste off,
+    # then the agent's initialize response glued on the same line.
+    PROMPT_GLUED_INIT = (
+        b"\x1b[?2004h"
+        b"\x1b]0;root@9ec4903f-9479-4754-9039-d1b5a544cb28: /home/github/build\x07"
+        b"root@9ec4903f-9479-4754-9039-d1b5a544cb28:/home/github/build# "
+        b"\x1b[?2004l"
+        b'{"jsonrpc": "2.0", "id": 100001, "result": {"protocolVersion": 1}}\n'
+    )
+
+    @pytest.mark.asyncio
+    async def test_prompt_glued_initialize_response_decodes(self, tmp_path) -> None:
+        fake_process = AsyncMock()
+        fake_process.readline = AsyncMock(return_value=self.PROMPT_GLUED_INIT)
+        agent_log = tmp_path / "agent" / "prime_agent.txt"
+        transport = ContainerTransport(
+            container_process=fake_process,
+            command="agent acp",
+            agent_log_path=agent_log,
+        )
+
+        await transport.start()
+        try:
+            msg = await asyncio.wait_for(transport.receive(), timeout=5)
+        finally:
+            await transport.close()
+
+        assert msg == {
+            "jsonrpc": "2.0",
+            "id": 100001,
+            "result": {"protocolVersion": 1},
+        }
+        # Decoded as protocol — nothing should be filed as noise.
+        assert not agent_log.exists()
+
+    def test_json_trailed_by_ansi_escapes_decodes(self) -> None:
+        """The CSI/OSC strip path recovers JSON with trailing escape noise."""
+        from benchflow.acp.container_transport import _decode_pty_json_rpc_message
+
+        line = '\x1b[?2004l{"jsonrpc": "2.0", "id": 7, "result": {}}\x1b[K'
+        assert _decode_pty_json_rpc_message(line) == {
+            "jsonrpc": "2.0",
+            "id": 7,
+            "result": {},
+        }
+
+    def test_log_line_with_invalid_envelope_still_rejected(self) -> None:
+        """A log line that merely contains JSON must stay non-protocol noise."""
+        from benchflow.acp.container_transport import _decode_pty_json_rpc_message
+
+        # Valid JSON after the first "{", but not a valid JSON-RPC envelope
+        # (no method, no result/error) — the envelope check must still reject.
+        assert (
+            _decode_pty_json_rpc_message('INFO {"jsonrpc": "2.0", "note": "boot"}')
+            is None
+        )
+        assert _decode_pty_json_rpc_message("plain log line, no json") is None
+
+    def test_plain_json_fast_path_unchanged(self) -> None:
+        from benchflow.acp.container_transport import _decode_pty_json_rpc_message
+
+        assert _decode_pty_json_rpc_message(
+            '{"jsonrpc": "2.0", "id": 1, "result": {"ok": true}}'
+        ) == {"jsonrpc": "2.0", "id": 1, "result": {"ok": True}}
+
+    def test_valid_envelope_after_log_prefix_decodes_pre_latch(self) -> None:
+        """Deliberate edge, documented: pre-latch, a log line that embeds a
+        COMPLETE valid JSON-RPC envelope decodes as protocol. That is the
+        exact shape of the prompt-glued handshake bug; before the first
+        protocol message it cannot be told apart from the real thing.
+        """
+        from benchflow.acp.container_transport import _decode_pty_json_rpc_message
+
+        assert _decode_pty_json_rpc_message(
+            'INFO sent {"jsonrpc": "2.0", "id": 3, "result": {}}'
+        ) == {"jsonrpc": "2.0", "id": 3, "result": {}}
+
+    @pytest.mark.asyncio
+    async def test_lenient_decode_latches_off_after_first_protocol_message(
+        self, tmp_path
+    ) -> None:
+        """After the first decoded protocol message the strict whole-line
+        decode rules: the same prefix-glued valid envelope that decodes
+        pre-latch is filed as noise post-latch, so a mid-session agent
+        echoing protocol envelopes into its logs cannot impersonate traffic.
+        """
+        glued_log = b'INFO sent {"jsonrpc": "2.0", "id": 3, "result": {}}\n'
+        fake_process = AsyncMock()
+        fake_process.readline = AsyncMock(
+            side_effect=[
+                self.PROMPT_GLUED_INIT,  # lenient path decodes; latch sets
+                glued_log,  # post-latch: strict decode files it as noise
+                b'{"jsonrpc": "2.0", "id": 4, "result": {"ok": true}}\n',
+            ]
+        )
+        agent_log = tmp_path / "agent" / "prime_agent.txt"
+        transport = ContainerTransport(
+            container_process=fake_process,
+            command="agent acp",
+            agent_log_path=agent_log,
+        )
+
+        await transport.start()
+        try:
+            first = await asyncio.wait_for(transport.receive(), timeout=5)
+            second = await asyncio.wait_for(transport.receive(), timeout=5)
+        finally:
+            await transport.close()
+
+        assert first["id"] == 100001
+        assert second == {"jsonrpc": "2.0", "id": 4, "result": {"ok": True}}
+        assert "INFO sent" in agent_log.read_text()
+
+
 class TestACPInterleaving:
     """Test that _read_until_response handles interleaved notifications and agent requests."""
 
@@ -914,6 +1040,55 @@ class TestIdleTimeoutDiagnostics:
         assert exc_info.value.trajectory[1]["status"] == ToolCallStatus.PENDING.value
 
 
+class TestAcpHandshakeTimeout:
+    """The pre-prompt handshake timeout is env-configurable at use time.
+
+    A fixed 60s is wrong for heavyweight task images — agent startup scales
+    with the image (workspace scanning, kernel prep), and on such images the
+    ``initialize`` response deterministically lands after the window. The
+    override is read per call (not cached at import) so long-lived processes
+    and these tests see env changes.
+    """
+
+    def test_default_is_60s_without_env(self, monkeypatch) -> None:
+        from benchflow.acp.runtime import _acp_handshake_timeout_sec
+
+        monkeypatch.delenv("BENCHFLOW_ACP_HANDSHAKE_TIMEOUT", raising=False)
+        assert _acp_handshake_timeout_sec() == 60.0
+
+    def test_env_override_is_honored(self, monkeypatch) -> None:
+        from benchflow.acp.runtime import _acp_handshake_timeout_sec
+
+        monkeypatch.setenv("BENCHFLOW_ACP_HANDSHAKE_TIMEOUT", "300")
+        assert _acp_handshake_timeout_sec() == 300.0
+        # Float values are accepted too.
+        monkeypatch.setenv("BENCHFLOW_ACP_HANDSHAKE_TIMEOUT", "90.5")
+        assert _acp_handshake_timeout_sec() == 90.5
+
+    @pytest.mark.parametrize("garbage", ["banana", "", "  ", "-5", "0", "nan"])
+    def test_garbage_or_non_positive_falls_back_to_default(
+        self, monkeypatch, garbage
+    ) -> None:
+        from benchflow.acp.runtime import _acp_handshake_timeout_sec
+
+        monkeypatch.setenv("BENCHFLOW_ACP_HANDSHAKE_TIMEOUT", garbage)
+        assert _acp_handshake_timeout_sec() == 60.0
+
+    @pytest.mark.asyncio
+    async def test_timeout_error_carries_effective_value(self, monkeypatch) -> None:
+        """The TransportClosedError message interpolates the EFFECTIVE timeout."""
+        from benchflow.acp.runtime import _wait_for_acp_handshake
+        from benchflow.diagnostics import TransportClosedError
+
+        monkeypatch.setenv("BENCHFLOW_ACP_HANDSHAKE_TIMEOUT", "0.05")
+
+        with pytest.raises(TransportClosedError) as exc_info:
+            await _wait_for_acp_handshake(asyncio.Future(), phase="initialize")
+
+        assert "timed out after 0.05s before the first prompt" in str(exc_info.value)
+        assert exc_info.value.diagnostic.transport_diagnosis == "acp_initialize_timeout"
+
+
 class TestConnectAcpModelSelection:
     """Verify connect_acp passes the right model string to set_model."""