iCode-TUI 0.29.1__py3-none-any.whl

chrys/service/acp_client/errors.py

@@ -0,0 +1,224 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Total, phase-aware ACP client error classification."""
+
+from __future__ import annotations
+
+import asyncio
+import errno
+from enum import StrEnum
+from typing import Any
+
+from acp.exceptions import RequestError
+
+from chrys.foundation.platform.files import surrogate_safe_text
+from chrys.foundation.platform.process import MissingWorkingDirectoryError
+
+_DETERMINISTIC_REQUEST_CODES = frozenset({-32700, -32600, -32601, -32602, -32002})
+_AUTH_REQUIRED_CODE = -32000
+_INTERNAL_ERROR_CODE = -32603
+# ETXTBSY is deliberately absent: it clears when the concurrent writer of the
+# executable finishes, so the same launch can succeed on retry.
+_DETERMINISTIC_ERRNOS = frozenset(
+    {
+        errno.E2BIG,
+        errno.EACCES,
+        errno.EINVAL,
+        errno.EISDIR,
+        errno.ELOOP,
+        errno.ENAMETOOLONG,
+        errno.ENOENT,
+        errno.ENOEXEC,
+        errno.ENOTDIR,
+        errno.EPERM,
+    }
+)
+_DETERMINISTIC_WINERRORS = frozenset({2, 3, 5, 10, 87, 123, 193, 203, 206, 216, 267, 740})
+
+
+class AcpOperation(StrEnum):
+    """Protocol operation being classified."""
+
+    SPAWN = "spawn"
+    INITIALIZE = "initialize"
+    NEW_SESSION = "session/new"
+    SET_MODE = "session/set_mode"
+    SET_MODEL = "session/set_model"
+    SET_CONFIG_OPTION = "session/set_config_option"
+    PROMPT = "session/prompt"
+    CLOSE_SESSION = "session/close"
+
+
+class AcpClientError(RuntimeError):
+    """Base for sanitized client failures safe to expose to model-visible code."""
+
+    def __init__(self, detail: str, *, cause: BaseException | None = None) -> None:
+        super().__init__(_sanitize_detail(detail))
+        self.detail = _sanitize_detail(detail)
+        self.cause = cause
+
+
+class AcpConfigError(AcpClientError):
+    """Deterministic configuration or protocol incompatibility."""
+
+
+class AcpSpawnError(AcpClientError):
+    """Deterministic process launch failure."""
+
+
+class AcpConnectError(AcpClientError):
+    """Transient failure in the provably stateless connect window."""
+
+
+class AcpTransportError(AcpClientError):
+    """Ambiguous post-stateful transport or protocol failure."""
+
+    def __init__(
+        self,
+        detail: str,
+        *,
+        cause: BaseException | None = None,
+        usage: Any | None = None,
+    ) -> None:
+        super().__init__(detail, cause=cause)
+        self.usage = usage
+
+
+class AcpIdleTimeoutError(AcpTransportError):
+    """Prompt inactivity timeout while no human decision is outstanding."""
+
+
+class AcpAuthRequiredError(AcpClientError):
+    """The remote requires an authentication method Chrys cannot perform."""
+
+    def __init__(
+        self,
+        detail: str = "The ACP agent requires authentication.",
+        *,
+        method_names: tuple[str, ...] = (),
+        cause: BaseException | None = None,
+    ) -> None:
+        super().__init__(detail, cause=cause)
+        self.method_names = method_names
+
+
+class AcpRefusalError(AcpClientError):
+    """Terminal remote refusal, distinct from a transport pause."""
+
+
+def _sanitize_detail(detail: str) -> str:
+    line = str(detail).replace("\r", " ").replace("\n", " ").strip()
+    if not line:
+        return "ACP operation failed."
+    return line[:500]
+
+
+def _request_auth_methods(error: RequestError) -> tuple[str, ...]:
+    data = error.data
+    if not isinstance(data, dict):
+        return ()
+    raw_methods = data.get("authMethods", data.get("auth_methods", data.get("methods", ())))
+    if not isinstance(raw_methods, list | tuple):
+        return ()
+    names: list[str] = []
+    for item in raw_methods:
+        if isinstance(item, str):
+            value = item
+        elif isinstance(item, dict):
+            value = item.get("name", item.get("id"))
+            if not isinstance(value, str):
+                continue
+        else:
+            continue
+        sanitized = value.replace("\r", " ").replace("\n", " ").strip()[:100]
+        if sanitized:
+            names.append(sanitized)
+    return tuple(names)
+
+
+def is_remote_error(error: AcpClientError) -> bool:
+    """Return whether the remote agent itself answered with the JSON-RPC error behind *error*."""
+    return isinstance(error.cause, RequestError)
+
+
+def is_deterministic_request_error(error: RequestError) -> bool:
+    """Return whether retrying the same request cannot change its rejection."""
+    return type(error.code) is int and error.code in _DETERMINISTIC_REQUEST_CODES
+
+
+def is_best_effort_option_rejection(error: RequestError) -> bool:
+    """Return whether a configured option may be skipped under best-effort policy."""
+    return type(error.code) is int and error.code in {-32601, -32602}
+
+
+def classify_spawn_error(error: BaseException) -> AcpSpawnError | AcpConnectError:
+    """Classify every subprocess-boundary failure as deterministic or transient."""
+    if isinstance(error, TypeError | ValueError):
+        return AcpSpawnError("The ACP process launch configuration is invalid.", cause=error)
+    if isinstance(error, MissingWorkingDirectoryError):
+        return AcpSpawnError(
+            f"The ACP agent's working directory no longer exists: {surrogate_safe_text(error.path)}", cause=error
+        )
+    if isinstance(error, OSError):
+        winerror = getattr(error, "winerror", None)
+        if error.errno in _DETERMINISTIC_ERRNOS or winerror in _DETERMINISTIC_WINERRORS:
+            return AcpSpawnError("The ACP process could not be launched with this configuration.", cause=error)
+        return AcpConnectError("The ACP process could not be started due to a transient system error.", cause=error)
+    return AcpConnectError("The ACP process could not be started.", cause=error)
+
+
+def classify_protocol_frame_error(
+    error: BaseException,
+    *,
+    stateful: bool,
+    complete: bool,
+) -> AcpConfigError | AcpConnectError | AcpTransportError:
+    """Classify a syntactically invalid complete line versus EOF-truncated frame."""
+    if stateful:
+        return AcpTransportError("The ACP agent sent an invalid protocol frame.", cause=error)
+    if complete:
+        return AcpConfigError("The ACP executable did not produce valid ACP JSON-RPC.", cause=error)
+    return AcpConnectError("The ACP process ended while writing a protocol frame.", cause=error)
+
+
+def classify_acp_error(
+    error: BaseException,
+    *,
+    operation: AcpOperation,
+    stateful: bool,
+) -> AcpClientError:
+    """Map every known SDK/validation/transport failure to one settled policy class."""
+    if isinstance(error, AcpClientError):
+        return error
+    if operation is AcpOperation.SPAWN:
+        return classify_spawn_error(error)
+    if isinstance(error, RequestError):
+        if type(error.code) is int and error.code == _AUTH_REQUIRED_CODE:
+            return AcpAuthRequiredError(method_names=_request_auth_methods(error), cause=error)
+        if is_deterministic_request_error(error):
+            return AcpConfigError(f"The ACP agent rejected {operation.value}.", cause=error)
+        if type(error.code) is int and error.code == _INTERNAL_ERROR_CODE:
+            if stateful:
+                return AcpTransportError(f"The ACP agent failed during {operation.value}.", cause=error)
+            return AcpConnectError(f"The ACP agent failed during {operation.value}.", cause=error)
+        if stateful:
+            return AcpTransportError(f"The ACP agent returned an unknown error during {operation.value}.", cause=error)
+        return AcpConnectError(f"The ACP agent returned an unknown error during {operation.value}.", cause=error)
+    if _is_validation_error(error):
+        if operation is AcpOperation.INITIALIZE:
+            return AcpConfigError("The ACP agent returned an incompatible initialize response.", cause=error)
+        if stateful:
+            return AcpTransportError(f"The ACP agent returned a malformed {operation.value} response.", cause=error)
+        return AcpConnectError(f"The ACP agent returned a malformed {operation.value} response.", cause=error)
+    if isinstance(error, TimeoutError | ConnectionError | EOFError | OSError | asyncio.CancelledError):
+        if stateful:
+            return AcpTransportError(f"The ACP transport failed during {operation.value}.", cause=error)
+        return AcpConnectError(f"The ACP transport failed during {operation.value}.", cause=error)
+    if stateful:
+        return AcpTransportError(f"The ACP client failed during {operation.value}.", cause=error)
+    return AcpConnectError(f"The ACP client failed during {operation.value}.", cause=error)
+
+
+def _is_validation_error(error: BaseException) -> bool:
+    error_type = type(error)
+    return error_type.__name__ == "ValidationError" and error_type.__module__.startswith("pydantic")

chrys/service/acp_client/protocol.py

@@ -0,0 +1,220 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""ACP protocol validation and retained payload caps."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+import math
+from typing import Any, Literal
+
+from chrys.foundation.text.images import MAX_IMAGE_BYTES
+from chrys.foundation.util.unicode_scalars import find_unpaired_surrogate
+
+_MAX_PAYLOAD_BYTES = 1024 * 1024
+_MAX_PAYLOAD_DEPTH = 32
+_MAX_COLLECTION_ITEMS = 4_096
+_MAX_STRING_CHARS = 256 * 1024
+_MAX_BASE64_IMAGE_CHARS = ((MAX_IMAGE_BYTES + 2) // 3) * 4
+_MAX_REQUEST_ID_CHARS = 4_096
+_MAX_METHOD_CHARS = 1_024
+
+_PERMISSION_METHOD = "session/request_permission"
+_ASK_USER_METHOD = "_chrys/request_input"
+
+
+def validate_json_scalar_tree(value: Any) -> None:
+    """Validate every JSON key, value, and sequence element recursively."""
+    if value is None or type(value) in {bool, int}:
+        return
+    if type(value) is float:
+        if not math.isfinite(value):
+            raise ValueError("JSON numbers must be finite.")
+        return
+    if type(value) is str:
+        _validate_surrogates(value)
+        return
+    if type(value) is dict:
+        for key, item in value.items():
+            if type(key) is not str:
+                raise ValueError("JSON object keys must be strings.")
+            _validate_surrogates(key)
+            validate_json_scalar_tree(item)
+        return
+    if type(value) in {list, tuple}:
+        for item in value:
+            validate_json_scalar_tree(item)
+        return
+    raise ValueError(f"Unsupported JSON value type: {type(value).__name__}")
+
+
+def _validate_surrogates(value: str) -> None:
+    if find_unpaired_surrogate(value) >= 0:
+        raise ValueError("JSON strings cannot contain unpaired surrogates.")
+
+
+def encode_protocol_json(value: Any) -> bytes:
+    """Encode a protocol-bound value after the shared scalar validation pass."""
+    validate_json_scalar_tree(value)
+    return json.dumps(value, separators=(",", ":"), ensure_ascii=True, allow_nan=False).encode("utf-8")
+
+
+def parse_protocol_json(raw: bytes) -> Any:
+    """Parse one JSON value while rejecting JavaScript non-finite constants."""
+
+    def reject_constant(value: str) -> None:
+        raise ValueError(f"Invalid JSON numeric constant: {value}")
+
+    parsed = json.loads(raw, parse_constant=reject_constant)
+    validate_json_scalar_tree(parsed)
+    return parsed
+
+
+_ENVELOPE_MEMBERS = frozenset({"jsonrpc", "id", "method", "params", "result", "error"})
+
+
+def validate_json_rpc_envelope(message: Any) -> Literal["request", "notification", "response"]:
+    """Validate the strict JSON-RPC envelope accepted by the SDK-facing reader."""
+    if type(message) is not dict:
+        raise ValueError("JSON-RPC frame root must be an object.")
+    # The per-kind caps run on params/result only, and the SDK re-parses the
+    # complete frame; an unknown top-level member would ride around both.
+    if not _ENVELOPE_MEMBERS.issuperset(message):
+        raise ValueError("JSON-RPC frame contains unknown envelope members.")
+    if message.get("jsonrpc") != "2.0" or type(message.get("jsonrpc")) is not str:
+        raise ValueError("JSON-RPC frame must declare version 2.0.")
+
+    has_id = "id" in message
+    has_method = "method" in message
+    has_result = "result" in message
+    has_error = "error" in message
+
+    if has_id and type(message["id"]) not in {str, int}:
+        raise ValueError("JSON-RPC ids must be exact strings or integers.")
+    # Ids and methods are retained (inbound map keys, outgoing records) and
+    # echoed into response frames, so they carry their own §7.4-style caps.
+    if has_id and type(message["id"]) is str and len(message["id"]) > _MAX_REQUEST_ID_CHARS:
+        raise ValueError("JSON-RPC id exceeds the retained-field cap.")
+    if has_id and type(message["id"]) is int and not -(1 << 63) <= message["id"] < 1 << 63:
+        raise ValueError("JSON-RPC id exceeds the interoperable integer range.")
+    if has_method and type(message["method"]) is not str:
+        raise ValueError("JSON-RPC methods must be strings.")
+    if has_method and len(message["method"]) > _MAX_METHOD_CHARS:
+        raise ValueError("JSON-RPC method exceeds the retained-field cap.")
+    if "params" in message:
+        if not has_method:
+            raise ValueError("JSON-RPC responses cannot contain params.")
+        if type(message["params"]) is not dict:
+            raise ValueError("JSON-RPC params must be an object.")
+
+    if has_method:
+        if has_result or has_error:
+            raise ValueError("JSON-RPC requests cannot contain result or error.")
+        return "request" if has_id else "notification"
+
+    if not has_id or has_result == has_error:
+        raise ValueError("JSON-RPC responses require an id and exactly one of result or error.")
+    if has_error:
+        error = message["error"]
+        if type(error) is not dict:
+            raise ValueError("JSON-RPC error must be an object.")
+        if type(error.get("code")) is not int or type(error.get("message")) is not str:
+            raise ValueError("JSON-RPC error requires an exact integer code and string message.")
+    return "response"
+
+
+def _measure_payload(value: Any, *, depth: int = 0) -> tuple[int, int]:
+    if depth > _MAX_PAYLOAD_DEPTH:
+        raise ValueError("ACP payload nesting is too deep.")
+    if type(value) is str:
+        if len(value) > _MAX_STRING_CHARS:
+            raise ValueError("ACP payload string is too large.")
+        return len(value.encode("utf-8", errors="surrogatepass")), 1
+    if type(value) is dict:
+        if len(value) > _MAX_COLLECTION_ITEMS:
+            raise ValueError("ACP payload object has too many fields.")
+        total = 0
+        items = 1
+        for key, item in value.items():
+            if len(key) > _MAX_STRING_CHARS:
+                raise ValueError("ACP payload string is too large.")
+            total += len(key.encode("utf-8", errors="surrogatepass"))
+            child_bytes, child_items = _measure_payload(item, depth=depth + 1)
+            total += child_bytes
+            items += child_items
+        return total, items
+    if type(value) in {list, tuple}:
+        if len(value) > _MAX_COLLECTION_ITEMS:
+            raise ValueError("ACP payload sequence has too many items.")
+        total = 0
+        items = 1
+        for item in value:
+            child_bytes, child_items = _measure_payload(item, depth=depth + 1)
+            total += child_bytes
+            items += child_items
+        return total, items
+    return 16, 1
+
+
+def _validate_payload_caps(value: Any) -> None:
+    _total_bytes, total_items = _measure_payload(value)
+    # Per-collection checks alone admit 4096-wide children at every level;
+    # the aggregate bound is what actually caps the retained object count.
+    if total_items > _MAX_COLLECTION_ITEMS:
+        raise ValueError("ACP payload has too many items in total.")
+    if len(encode_protocol_json(value)) > _MAX_PAYLOAD_BYTES:
+        raise ValueError("ACP retained payload exceeds the byte limit.")
+
+
+def _validate_update_image_data(data: str) -> None:
+    """Validate one image payload before exempting its encoding overhead."""
+    if not data:
+        raise ValueError("ACP image payload is empty.")
+    if len(data) > _MAX_BASE64_IMAGE_CHARS:
+        raise ValueError("ACP image payload exceeds the supported size limit.")
+    try:
+        decoded = base64.b64decode(data, validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise ValueError("ACP image payload is not valid base64.") from exc
+    if not decoded:
+        raise ValueError("ACP image payload is empty.")
+    if len(decoded) > MAX_IMAGE_BYTES:
+        raise ValueError("ACP image payload exceeds the supported size limit.")
+
+
+def _payload_without_tool_image_data(value: Any) -> Any:
+    """Replace validated tool-image encodings for retained-cap accounting."""
+    if type(value) is not dict:
+        return value
+    update = value.get("update")
+    if type(update) is not dict or update.get("sessionUpdate") not in {"tool_call", "tool_call_update"}:
+        return value
+    content = update.get("content")
+    if type(content) is not list:
+        return value
+
+    bounded_content: list[Any] | None = None
+    for index, item in enumerate(content):
+        if type(item) is not dict or item.get("type") != "content":
+            continue
+        block = item.get("content")
+        if type(block) is not dict or block.get("type") != "image" or type(block.get("mimeType")) is not str:
+            continue
+        data = block.get("data")
+        if type(data) is not str:
+            continue
+        _validate_update_image_data(data)
+        if bounded_content is None:
+            bounded_content = list(content)
+        bounded_content[index] = {**item, "content": {**block, "data": ""}}
+
+    if bounded_content is None:
+        return value
+    return {**value, "update": {**update, "content": bounded_content}}
+
+
+def _validate_update_payload_caps(value: Any) -> None:
+    """Apply retained caps while excluding validated tool-image encoding overhead."""
+    _validate_payload_caps(_payload_without_tool_image_data(value))

chrys/service/acp_client/spawn.py

@@ -0,0 +1,239 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Owned ACP process spawning, environment hygiene, and bounded stderr capture."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import errno
+import math
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import BinaryIO
+
+from acp import default_environment
+
+from chrys.foundation.platform.files import SecureFileError, secure_open_owner_only
+from chrys.foundation.platform.process import ManagedStdioProcess, spawn_managed_stdio_process
+
+from .errors import AcpClientError, AcpConfigError, classify_spawn_error
+from .spec import AcpAgentSpec
+
+ACP_STDIO_LIMIT_BYTES = 50 * 1024 * 1024
+STDERR_LOG_QUOTA_BYTES = 5 * 1024 * 1024
+STDERR_TAIL_BYTES = 4 * 1024
+_STDERR_DRAIN_TIMEOUT_SECONDS = 2.0
+DEPTH_ENV_VAR = "CHRYS_ACP_SUBAGENT_DEPTH"
+
+
+def _validate_exact_spawn_string(value: object, *, field: str) -> str:
+    if type(value) is not str:
+        raise AcpConfigError(f"ACP {field} must be a string.")
+    if "\x00" in value:
+        raise AcpConfigError(f"ACP {field} cannot contain NUL.")
+    return value
+
+
+def build_child_environment(spec: AcpAgentSpec) -> dict[str, str]:
+    """Build a case-fold-deduplicated trimmed environment for one child."""
+    if type(spec.depth) is not int or spec.depth < 0:
+        raise AcpConfigError("ACP recursion depth must be a non-negative integer.")
+
+    base = default_environment()
+    canonical_by_fold = {key.casefold(): key for key in base}
+    merged: dict[str, str] = {}
+    present_by_fold: dict[str, str] = {}
+
+    def overlay(key: object, value: object, *, preserve_base_case: bool) -> None:
+        key_text = _validate_exact_spawn_string(key, field="environment key")
+        value_text = _validate_exact_spawn_string(value, field=f"environment value for {key_text!r}")
+        if not key_text or "=" in key_text:
+            raise AcpConfigError("ACP environment keys must be non-empty and cannot contain '='.")
+        folded = key_text.casefold()
+        previous = present_by_fold.get(folded)
+        if previous is not None:
+            merged.pop(previous, None)
+        output_key = canonical_by_fold.get(folded, key_text) if preserve_base_case else key_text
+        merged[output_key] = value_text
+        present_by_fold[folded] = output_key
+
+    for key, value in base.items():
+        overlay(key, value, preserve_base_case=True)
+    for key, value in spec.env.items():
+        overlay(key, value, preserve_base_case=True)
+    overlay(DEPTH_ENV_VAR, str(spec.depth + 1), preserve_base_case=False)
+    return merged
+
+
+def validate_agent_spec(spec: AcpAgentSpec) -> None:
+    """Fail closed on malformed values that reach the process/protocol boundary."""
+    _validate_exact_spawn_string(spec.command, field="command")
+    cwd = _validate_exact_spawn_string(spec.cwd, field="cwd")
+    if not os.path.isabs(cwd):
+        raise AcpConfigError("ACP cwd must be absolute.")
+    for arg in spec.args:
+        _validate_exact_spawn_string(arg, field="argument")
+    for key, value in spec.env.items():
+        _validate_exact_spawn_string(key, field="environment key")
+        _validate_exact_spawn_string(value, field=f"environment value for {key!r}")
+    if type(spec.handshake_timeout_seconds) not in {int, float} or not math.isfinite(spec.handshake_timeout_seconds):
+        raise AcpConfigError("ACP handshake timeout must be finite.")
+    if spec.handshake_timeout_seconds <= 0:
+        raise AcpConfigError("ACP handshake timeout must be greater than zero.")
+    if type(spec.idle_timeout_seconds) not in {int, float} or not math.isfinite(spec.idle_timeout_seconds):
+        raise AcpConfigError("ACP idle timeout must be finite.")
+    if spec.idle_timeout_seconds < 0:
+        raise AcpConfigError("ACP idle timeout cannot be negative.")
+    if type(spec.best_effort_options) is not bool:
+        raise AcpConfigError("ACP best-effort option mode must be a boolean.")
+    if type(spec.session_mode) is not str or type(spec.model_id) is not str:
+        raise AcpConfigError("ACP session mode and model id must be strings.")
+    for root in spec.additional_directories:
+        directory = _validate_exact_spawn_string(root, field="additional workspace directory")
+        # ACP requires every additional workspace root to be absolute; a
+        # relative value would resolve agent-dependently.
+        if not os.path.isabs(directory):
+            raise AcpConfigError("ACP additional workspace directories must be absolute.")
+    for option_id, value in spec.config_options.items():
+        if type(option_id) is not str or not option_id:
+            raise AcpConfigError("ACP config option ids must be non-empty strings.")
+        if type(value) not in {str, bool}:
+            raise AcpConfigError("ACP config option values must be exact strings or booleans.")
+    if type(spec.depth) is not int or spec.depth < 0:
+        raise AcpConfigError("ACP recursion depth must be a non-negative integer.")
+
+
+class StderrCapture:
+    """Quota-bounded owner-only stderr log plus a small diagnostics tail."""
+
+    def __init__(self, reader: asyncio.StreamReader, path: Path) -> None:
+        self._reader = reader
+        self._path = path
+        self._tail = bytearray()
+        self._written_bytes = 0
+        self._dropped_bytes = 0
+        self._task: asyncio.Task[None] | None = None
+        self._file: BinaryIO | None = None
+
+    @property
+    def tail(self) -> str:
+        return bytes(self._tail).decode("utf-8", errors="replace")
+
+    @property
+    def dropped_bytes(self) -> int:
+        return self._dropped_bytes
+
+    def start(self) -> None:
+        if self._task is not None:
+            raise RuntimeError("stderr capture already started")
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            fd = secure_open_owner_only(self._path, write=True, create=True, truncate=True)
+        except SecureFileError as exc:
+            if exc.errno not in {errno.EEXIST, 80, 183}:
+                raise
+            fd = secure_open_owner_only(self._path, write=True, truncate=True)
+        self._file = os.fdopen(fd, "wb", closefd=True)
+        self._task = asyncio.create_task(self._run(), name="chrys.acp.stderr")
+
+    async def _run(self) -> None:
+        try:
+            while chunk := await self._reader.read(64 * 1024):
+                self._tail.extend(chunk)
+                if len(self._tail) > STDERR_TAIL_BYTES:
+                    del self._tail[:-STDERR_TAIL_BYTES]
+                remaining = STDERR_LOG_QUOTA_BYTES - self._written_bytes
+                if remaining <= 0 or self._file is None:
+                    self._dropped_bytes += len(chunk)
+                    continue
+                payload = chunk[:remaining]
+                try:
+                    written = self._file.write(payload)
+                except OSError:
+                    self._dropped_bytes += len(chunk)
+                    self._close_file()
+                    continue
+                self._written_bytes += written
+                self._dropped_bytes += len(chunk) - written
+        finally:
+            self._close_file()
+
+    def _close_file(self) -> None:
+        if self._file is not None:
+            with contextlib.suppress(OSError):
+                self._file.flush()
+            with contextlib.suppress(OSError):
+                os.fsync(self._file.fileno())
+            with contextlib.suppress(OSError):
+                self._file.close()
+            self._file = None
+
+    async def stop(self) -> None:
+        task = self._task
+        if task is None:
+            return
+        # Bounded drain before cancel: the child is already dead or dying when
+        # the close ladder gets here, so EOF arrives promptly — cancelling
+        # first would discard flushed-but-unread final diagnostics.
+        with contextlib.suppress(asyncio.CancelledError, Exception):
+            await asyncio.wait({task}, timeout=_STDERR_DRAIN_TIMEOUT_SECONDS)
+        if not task.done():
+            task.cancel()
+        with contextlib.suppress(asyncio.CancelledError, Exception):
+            await task
+        self._task = None
+
+
+@dataclass(slots=True)
+class AcpSpawnResult:
+    """Spawned process and its owned stderr diagnostic capture."""
+
+    process: ManagedStdioProcess
+    stderr: StderrCapture
+
+    @property
+    def stderr_tail(self) -> str:
+        return self.stderr.tail
+
+
+async def spawn_acp_process(spec: AcpAgentSpec) -> AcpSpawnResult:
+    """Launch the resolved ACP command with an owned process tree and streams."""
+    validate_agent_spec(spec)
+    command = _validate_exact_spawn_string(spec.command, field="command")
+    cwd = _validate_exact_spawn_string(spec.cwd, field="cwd")
+    args = tuple(_validate_exact_spawn_string(arg, field="argument") for arg in spec.args)
+    parent_env = dict(os.environ)
+    env = build_child_environment(spec)
+    try:
+        process = await spawn_managed_stdio_process(
+            command,
+            *args,
+            cwd=cwd,
+            env=env,
+            limit=ACP_STDIO_LIMIT_BYTES,
+            parent_env=parent_env,
+        )
+    except asyncio.CancelledError:
+        raise
+    except AcpClientError:
+        raise
+    except BaseException as exc:
+        raise classify_spawn_error(exc) from exc
+
+    capture = StderrCapture(process.stderr, spec.stderr_log_path)
+    try:
+        capture.start()
+    except BaseException as exc:
+        process.kill_tree()
+        try:
+            # Cancellation during this wait must still release the transports:
+            # the caller has no AcpSpawnResult yet, so its rollback cannot
+            # reach the process handles this function still owns.
+            with contextlib.suppress(Exception):
+                await asyncio.wait_for(process.wait(), timeout=2)
+        finally:
+            process.close_transports()
+        raise AcpConfigError("The ACP stderr log could not be created securely.", cause=exc) from exc
+    return AcpSpawnResult(process=process, stderr=capture)