agent-lifecycle-kit 2.17.0__tar.gz → 2.18.0__tar.gz

{agent_lifecycle_kit-2.17.0/src/agent_lifecycle_kit.egg-info → agent_lifecycle_kit-2.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-lifecycle-kit
-Version: 2.17.0
+Version: 2.18.0
 Summary: Provider-neutral lifecycle control layer that helps coding agents plan, execute, validate, and prove software tasks to completion.
 Author: Agent Lifecycle Kit contributors
 License: Apache-2.0
@@ -41,9 +41,9 @@ and secret handling stay in adapters or host-local profiles.
 ALK provides a verifiable finish for external-agent work with proportionate control. It adds only the checks and evidence needed for the task; most of the time remains for research, implementation and product verification.
 
 ## Quick start
-Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.17 strengthens [workflow validation and recovery](docs/reference/workflow-completeness.md). Release 2.16 introduced cumulative accounting within verified host capabilities; see [retention maintenance](docs/operations/retention-maintenance.md).
+Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.18 bounds process/Git diagnostics, hardens signing and distinguishes OpenCode 1.x/2.x compatibility ([adapter notes](docs/adapters/opencode.md)); 2.17 strengthens [workflow validation and recovery](docs/reference/workflow-completeness.md). Release 2.16 introduced cumulative accounting within verified host capabilities; see [retention maintenance](docs/operations/retention-maintenance.md).
 
-It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.17.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
+It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.18.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
 
 For a quick start, run:
 

{agent_lifecycle_kit-2.17.0 → agent_lifecycle_kit-2.18.0}/README.md

@@ -19,9 +19,9 @@ and secret handling stay in adapters or host-local profiles.
 ALK provides a verifiable finish for external-agent work with proportionate control. It adds only the checks and evidence needed for the task; most of the time remains for research, implementation and product verification.
 
 ## Quick start
-Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.17 strengthens [workflow validation and recovery](docs/reference/workflow-completeness.md). Release 2.16 introduced cumulative accounting within verified host capabilities; see [retention maintenance](docs/operations/retention-maintenance.md).
+Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.18 bounds process/Git diagnostics, hardens signing and distinguishes OpenCode 1.x/2.x compatibility ([adapter notes](docs/adapters/opencode.md)); 2.17 strengthens [workflow validation and recovery](docs/reference/workflow-completeness.md). Release 2.16 introduced cumulative accounting within verified host capabilities; see [retention maintenance](docs/operations/retention-maintenance.md).
 
-It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.17.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
+It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.18.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
 
 For a quick start, run:
 

{agent_lifecycle_kit-2.17.0 → agent_lifecycle_kit-2.18.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-lifecycle-kit"
-version = "2.17.0"
+version = "2.18.0"
 description = "Provider-neutral lifecycle control layer that helps coding agents plan, execute, validate, and prove software tasks to completion."
 readme = "README.md"
 requires-python = ">=3.11,<3.15"

{agent_lifecycle_kit-2.17.0 → agent_lifecycle_kit-2.18.0}/src/agent_lifecycle/_version.py

@@ -1,3 +1,3 @@
 """Package version."""
 
-__version__ = "2.17.0"
+__version__ = "2.18.0"

{agent_lifecycle_kit-2.17.0 → agent_lifecycle_kit-2.18.0}/src/agent_lifecycle/adapter_sessions/external_check.py

@@ -6,7 +6,6 @@ import hashlib
 import json
 import os
 import shutil
-import subprocess
 from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
@@ -15,6 +14,7 @@ from agent_lifecycle.adapter_sessions.env import resolve_launch_env
 from agent_lifecycle.adapter_sessions.process import run_process
 from agent_lifecycle.adapter_sessions.worktree_identity import capture_git_worktree_identity
 from agent_lifecycle.audit.external_checks import audit_external_check_result
+from agent_lifecycle.changesets.git_io import run_bounded_command
 from agent_lifecycle.contracts import LifecycleError, canonical_digest, read_json_object
 from agent_lifecycle.contracts.external_check_schemas import (
     MAX_ARG_BYTES,
@@ -258,16 +258,13 @@ def _source_snapshot(root: Path, revision: str | None) -> dict[str, Any]:
 
 def _source_paths(root: Path) -> list[str]:
     try:
-        completed = subprocess.run(
+        completed = run_bounded_command(
             ["git", "ls-files", "--cached", "--others", "--exclude-standard", "-z"],
             cwd=root,
-            shell=False,
-            stdin=subprocess.DEVNULL,
-            capture_output=True,
-            timeout=30,
-            check=False,
+            timeout_seconds=30,
+            max_stdout_bytes=MAX_SOURCE_FILE_LIST_BYTES,
         )
-    except (OSError, subprocess.TimeoutExpired) as exc:
+    except (OSError, LifecycleError) as exc:
         raise LifecycleError("external-check-source-unavailable", "source file set could not be captured") from exc
     if completed.returncode != 0 or len(completed.stdout) > MAX_SOURCE_FILE_LIST_BYTES:
         raise LifecycleError("external-check-source-unavailable", "source file set could not be captured")

{agent_lifecycle_kit-2.17.0 → agent_lifecycle_kit-2.18.0}/src/agent_lifecycle/adapter_sessions/process.py

@@ -704,6 +704,8 @@ def run_process(
         attempt_id=attempt_id,
         adapter_id=adapter_id,
         retry=retry,
+        timeout_seconds=timeout_seconds,
+        cleanup_grace_seconds=cleanup_grace_seconds,
     )
     if invalid is not None:
         return invalid

{agent_lifecycle_kit-2.17.0 → agent_lifecycle_kit-2.18.0}/src/agent_lifecycle/adapter_sessions/process_control.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import math
 import subprocess
 import threading
 from typing import Any
@@ -13,6 +14,7 @@ from agent_lifecycle.contracts.process_execution_schemas import build_process_ex
 DEFAULT_OUTPUT_BYTES = 262_144
 DEFAULT_CLEANUP_GRACE_SECONDS = 1.0
 
+
 def _invalid_limit_failure(
     *,
     input_bytes: bytes,
@@ -23,7 +25,32 @@ def _invalid_limit_failure(
     attempt_id: str | None,
     adapter_id: str | None,
     retry: dict[str, Any] | None,
+    timeout_seconds: float,
+    cleanup_grace_seconds: float,
 ) -> dict[str, Any] | None:
+    for name, value in (("timeout", timeout_seconds), ("cleanup-grace", cleanup_grace_seconds)):
+        if (
+            type(value) not in (int, float)
+            or not math.isfinite(value)
+            or value < 0
+            or (name == "timeout" and value == 0)
+        ):
+            return _bounded_failure(
+                f"adapter-process-{name}-invalid",
+                input_bytes=len(input_bytes),
+                output_bytes=0,
+                process_started=False,
+                details={
+                    "reason": (
+                        "positive-finite-limit-required" if name == "timeout" else "nonnegative-finite-limit-required"
+                    )
+                },
+                command_hash=command_hash,
+                operation_id=operation_id,
+                attempt_id=attempt_id,
+                adapter_id=adapter_id,
+                retry=retry,
+            )
     if max_input_bytes is not None and len(input_bytes) > max_input_bytes:
         return _bounded_failure(
             "adapter-process-input-limit",
@@ -52,6 +79,7 @@ def _invalid_limit_failure(
         )
     return None
 
+
 def _build_process_result(
     process: subprocess.Popen[Any],
     *,
@@ -75,8 +103,9 @@ def _build_process_result(
 ) -> dict[str, Any]:
     stdout = capture.captures["stdout"].decode("utf-8", errors="replace")
     stderr = capture.captures["stderr"].decode("utf-8", errors="replace")
-    stdout_tail, stdout_redacted = redact_process_text(stdout[-2000:])
-    stderr_tail, stderr_redacted = redact_process_text(stderr[-2000:])
+    safe_stdout, stdout_redacted = redact_process_text(stdout)
+    safe_stderr, stderr_redacted = redact_process_text(stderr)
+    stdout_tail, stderr_tail = safe_stdout[-2000:], safe_stderr[-2000:]
     blockers = _process_blockers(
         capture.output_limit_exceeded,
         timed_out=timed_out,
@@ -132,6 +161,7 @@ def _build_process_result(
         "blockers": blockers,
     }
 
+
 def _process_blockers(
     output_limit_exceeded: threading.Event,
     *,
@@ -155,6 +185,7 @@ def _process_blockers(
         blockers.append({"code": "adapter-process-cleanup-unverified", "cleanup": cleanup})
     return blockers
 
+
 def _bounded_failure(
     code: str,
     *,

{agent_lifecycle_kit-2.17.0 → agent_lifecycle_kit-2.18.0}/src/agent_lifecycle/adapter_sessions/worktree_identity.py

@@ -4,17 +4,18 @@ from __future__ import annotations
 
 import hashlib
 import os
-import subprocess
 import time
 from pathlib import Path
 from typing import Any
 
+from agent_lifecycle.changesets.git_io import run_bounded_command
 from agent_lifecycle.contracts import LifecycleError, canonical_digest
 
 MAX_UNTRACKED_FILES = 100_000
 MAX_UNTRACKED_BYTES = 4 * 1024 * 1024 * 1024
 MAX_HASH_CHUNK_BYTES = 256 * 1024
 MAX_CAPTURE_SECONDS = 120.0
+MAX_GIT_CAPTURE_BYTES = 128 * 1024 * 1024
 
 
 def capture_git_worktree_identity(project_root: Path) -> dict[str, Any]:
@@ -29,8 +30,8 @@ def capture_git_worktree_identity(project_root: Path) -> dict[str, Any]:
     root = project_root.resolve()
     deadline = time.monotonic() + MAX_CAPTURE_SECONDS
     head = _git_bytes(root, ["rev-parse", "HEAD"], deadline).decode("ascii", errors="strict").strip()
-    staged = _git_bytes(root, ["diff", "--cached", "--binary", "--no-ext-diff"], deadline)
-    unstaged = _git_bytes(root, ["diff", "--binary", "--no-ext-diff"], deadline)
+    staged = _git_bytes(root, ["diff", "--cached", "--binary", "--no-ext-diff", "--no-textconv"], deadline)
+    unstaged = _git_bytes(root, ["diff", "--binary", "--no-ext-diff", "--no-textconv"], deadline)
     submodules = _git_bytes(root, ["submodule", "status", "--recursive"], deadline)
     untracked_raw = _git_bytes(root, ["ls-files", "--others", "--exclude-standard", "-z"], deadline)
     names = sorted(item for item in untracked_raw.split(b"\0") if item)
@@ -131,16 +132,13 @@ def _git_bytes(root: Path, args: list[str], deadline: float) -> bytes:
     if remaining <= 0:
         raise LifecycleError("planning-worktree-identity-timeout", "Git identity capture exceeded its deadline")
     try:
-        result = subprocess.run(
+        result = run_bounded_command(
             ["git", *args],
             cwd=root,
-            shell=False,
-            stdin=subprocess.DEVNULL,
-            capture_output=True,
-            timeout=remaining,
-            check=False,
+            timeout_seconds=remaining,
+            max_stdout_bytes=MAX_GIT_CAPTURE_BYTES,
         )
-    except (OSError, subprocess.TimeoutExpired) as exc:
+    except (OSError, LifecycleError) as exc:
         raise LifecycleError(
             "planning-worktree-identity-failed",
             "Git identity capture failed closed",

{agent_lifecycle_kit-2.17.0 → agent_lifecycle_kit-2.18.0}/src/agent_lifecycle/changesets/git.py

@@ -2,9 +2,9 @@
 
 from __future__ import annotations
 
-import subprocess
 from pathlib import Path
 
+from agent_lifecycle.changesets.git_io import run_bounded_command
 from agent_lifecycle.contracts import LifecycleError
 from agent_lifecycle.contracts.paths import normalize_git_revision, normalize_repo_path
 
@@ -63,20 +63,24 @@ def changed_files(cwd: Path, *, base: str | None = None) -> list[str]:
 def resolve_revision(cwd: Path, revision: str, *, label: str = "revision") -> str:
     value = normalize_git_revision(revision, label=label)
     try:
-        completed = subprocess.run(
+        completed = run_bounded_command(
             ["git", "rev-parse", "--verify", "--end-of-options", f"{value}^{{commit}}"],
             cwd=cwd,
-            check=True,
-            capture_output=True,
-            text=True,
-            timeout=GIT_TIMEOUT_SECONDS,
+            timeout_seconds=GIT_TIMEOUT_SECONDS,
+            max_stdout_bytes=128,
         )
-    except (OSError, subprocess.CalledProcessError, subprocess.TimeoutExpired) as exc:
+    except (OSError, LifecycleError) as exc:
         raise LifecycleError("invalid-git-revision", f"{label}: revision cannot be resolved") from exc
     resolved = completed.stdout.strip().splitlines()
-    if len(resolved) != 1 or not resolved[0]:
+    if completed.returncode or len(resolved) != 1 or len(resolved[0]) not in (40, 64):
         raise LifecycleError("invalid-git-revision", f"{label}: revision cannot be resolved")
-    return resolved[0]
+    try:
+        value = resolved[0].decode("ascii")
+    except UnicodeDecodeError as exc:
+        raise LifecycleError("invalid-git-revision", f"{label}: revision cannot be resolved") from exc
+    if any(char not in "0123456789abcdef" for char in value):
+        raise LifecycleError("invalid-git-revision", f"{label}: revision cannot be resolved")
+    return value
 
 
 def _resolve_revision(cwd: Path, revision: str, *, label: str = "revision") -> str:
@@ -87,21 +91,19 @@ def _resolve_revision(cwd: Path, revision: str, *, label: str = "revision") -> s
 
 def _git_paths(cwd: Path, argv: list[str]) -> list[str]:
     try:
-        completed = subprocess.run(
+        completed = run_bounded_command(
             argv,
             cwd=cwd,
-            check=True,
-            capture_output=True,
-            timeout=GIT_TIMEOUT_SECONDS,
-        )
-    except (OSError, subprocess.CalledProcessError, subprocess.TimeoutExpired) as exc:
-        raise LifecycleError("git-command-failed", f"git command failed: {' '.join(argv)}") from exc
-    if len(completed.stdout) > MAX_GIT_OUTPUT_BYTES:
-        raise LifecycleError(
-            "git-output-limit",
-            "Git changed-file output exceeds the bounded snapshot limit",
-            {"maxBytes": MAX_GIT_OUTPUT_BYTES},
+            timeout_seconds=GIT_TIMEOUT_SECONDS,
+            max_stdout_bytes=MAX_GIT_OUTPUT_BYTES,
         )
+    except LifecycleError as exc:
+        code = "git-output-limit" if exc.code == "bounded-process-output-limit" else "git-command-failed"
+        raise LifecycleError(code, "Git changed-file command failed closed") from exc
+    except OSError as exc:
+        raise LifecycleError("git-command-failed", "Git changed-file command could not start") from exc
+    if completed.returncode:
+        raise LifecycleError("git-command-failed", "Git changed-file command failed")
     paths = []
     for raw in completed.stdout.split(b"\0"):
         if not raw:

agent_lifecycle_kit-2.18.0/src/agent_lifecycle/changesets/git_io.py

@@ -0,0 +1,358 @@
+"""Bounded, interruptible byte transport for local Git and inspection commands.
+
+This module owns pipe reads and its direct subprocess. Adapter lifecycle,
+qualification and process-group attestation remain at their existing owners.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+import queue
+import signal
+import subprocess
+import threading
+import time
+from collections.abc import Callable
+from contextlib import suppress
+from pathlib import Path
+from typing import IO
+
+from agent_lifecycle.contracts import LifecycleError
+
+_CHUNK_BYTES = 65536
+_POLL_SECONDS = 0.02
+_CLEANUP_SECONDS = 0.5
+
+
+def _windows_cleanup(process: subprocess.Popen[bytes]) -> Callable[[], None] | None:
+    """Retain a Job handle so a recursive local command can be reaped as a tree."""
+    if os.name != "nt":
+        return None
+    import ctypes
+    from ctypes import wintypes
+
+    win_dll = getattr(ctypes, "WinDLL", None)
+    if not callable(win_dll):
+        raise LifecycleError("bounded-process-group-unavailable", "Windows group API is unavailable")
+    kernel = win_dll("kernel32", use_last_error=True)
+    kernel.CreateJobObjectW.argtypes = [wintypes.LPVOID, wintypes.LPCWSTR]
+    kernel.CreateJobObjectW.restype = wintypes.HANDLE
+    kernel.AssignProcessToJobObject.argtypes = [wintypes.HANDLE, wintypes.HANDLE]
+    kernel.AssignProcessToJobObject.restype = wintypes.BOOL
+    kernel.TerminateJobObject.argtypes = [wintypes.HANDLE, wintypes.UINT]
+    kernel.TerminateJobObject.restype = wintypes.BOOL
+    kernel.CloseHandle.argtypes = [wintypes.HANDLE]
+    kernel.CloseHandle.restype = wintypes.BOOL
+    handle = kernel.CreateJobObjectW(None, None)
+    if not handle:
+        raise LifecycleError("bounded-process-group-unavailable", "Cannot own the Windows child group")
+    if not kernel.AssignProcessToJobObject(handle, getattr(process, "_handle", None)):
+        kernel.CloseHandle(handle)
+        raise LifecycleError("bounded-process-group-unavailable", "Cannot own the Windows child group")
+
+    def cleanup() -> None:
+        terminated = kernel.TerminateJobObject(handle, 1)
+        closed = kernel.CloseHandle(handle)
+        if not terminated or not closed:
+            raise LifecycleError("bounded-process-cleanup-failed", "Windows child group cleanup failed")
+
+    return cleanup
+
+
+class _PipeReader:
+    def __init__(self, owner: BoundedProcess, stream: IO[bytes], limit: int) -> None:
+        self.owner = owner
+        self.stream = stream
+        self.limit = limit
+        self.chunks: queue.Queue[bytes | None] = queue.Queue(maxsize=2)
+        self.buffer = bytearray()
+        self.eof = False
+        self.thread = threading.Thread(target=self._pump, name="alk-bounded-pipe", daemon=True)
+
+    def _pump(self) -> None:
+        total = 0
+        try:
+            while not self.owner.stopping.is_set():
+                data = os.read(self.stream.fileno(), min(_CHUNK_BYTES, self.limit - total + 1))
+                total += len(data)
+                if total > self.limit:
+                    self.owner.fail("bounded-process-output-limit")
+                    return
+                while not self.owner.stopping.is_set():
+                    try:
+                        self.chunks.put(data or None, timeout=_POLL_SECONDS)
+                        break
+                    except queue.Full:
+                        continue
+                if not data:
+                    return
+        except OSError:
+            if not self.owner.stopping.is_set():
+                self.owner.fail("bounded-process-read-failed")
+
+    def _fill(self) -> None:
+        while not self.eof:
+            self.owner.check()
+            try:
+                chunk = self.chunks.get(timeout=self.owner.remaining())
+            except queue.Empty:
+                continue
+            if chunk is None:
+                self.eof = True
+            else:
+                self.buffer.extend(chunk)
+            return
+
+    def readline(self, max_bytes: int) -> bytes:
+        while True:
+            self.owner.check()
+            end = self.buffer.find(b"\n")
+            size = end + 1 if end >= 0 else len(self.buffer)
+            if size > max_bytes:
+                raise LifecycleError("bounded-process-line-limit", "Process line exceeds its byte limit")
+            if end >= 0 or self.eof:
+                value = bytes(self.buffer[:size])
+                del self.buffer[:size]
+                return value
+            self._fill()
+
+    def read(self, size: int) -> bytes:
+        chunks: list[bytes] = []
+        remaining = size
+        while remaining:
+            self.owner.check()
+            if not self.buffer and not self.eof:
+                self._fill()
+            if not self.buffer:
+                break
+            value = bytes(self.buffer[:remaining])
+            del self.buffer[: len(value)]
+            chunks.append(value)
+            remaining -= len(value)
+        return b"".join(chunks)
+
+    def read_all(self) -> bytes:
+        chunks: list[bytes] = []
+        while True:
+            chunk = self.read(_CHUNK_BYTES)
+            if not chunk:
+                return b"".join(chunks)
+            chunks.append(chunk)
+
+
+class BoundedProcess:
+    """Keep one absolute deadline across a streaming request/response session."""
+
+    def __init__(
+        self,
+        argv: list[str],
+        *,
+        cwd: Path,
+        deadline: float,
+        max_stdout_bytes: int,
+        max_stderr_bytes: int = 65536,
+        writable: bool = False,
+    ) -> None:
+        if type(deadline) not in (int, float) or not math.isfinite(deadline) or deadline <= time.monotonic():
+            raise LifecycleError("bounded-process-timeout", "Process deadline is invalid or expired")
+        if not argv or any(not isinstance(value, str) or "\0" in value for value in argv):
+            raise LifecycleError("bounded-process-argv-invalid", "A shell-free argument vector is required")
+        if any(type(value) is not int or value < 1 for value in (max_stdout_bytes, max_stderr_bytes)):
+            raise LifecycleError("bounded-process-limit-invalid", "Positive byte limits are required")
+        self.deadline = deadline
+        self.closed = False
+        self.stopping = threading.Event()
+        self.failure: str | None = None
+        self.stderr = bytearray()
+        self.max_stderr_bytes = max_stderr_bytes
+        self.writes: queue.Queue[tuple[bytes | None, threading.Event]] = queue.Queue(maxsize=1)
+        env = dict(os.environ)
+        if Path(argv[0]).stem.lower() == "git":
+            env.update(GIT_NO_LAZY_FETCH="1", GIT_TERMINAL_PROMPT="0")
+        self.process = subprocess.Popen(
+            argv,
+            cwd=cwd,
+            env=env,
+            stdin=subprocess.PIPE if writable else subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            shell=False,
+            bufsize=0,
+            start_new_session=os.name == "posix",
+        )
+        self.threads: list[threading.Thread] = []
+        self.windows_cleanup: Callable[[], None] | None = None
+        try:
+            self.windows_cleanup = _windows_cleanup(self.process)
+            assert self.process.stdout is not None
+            self.stdout = _PipeReader(self, self.process.stdout, max_stdout_bytes)
+            self.threads.append(self.stdout.thread)
+            self.stdout.thread.start()
+            reader = threading.Thread(target=self._drain_stderr, name="alk-bounded-stderr", daemon=True)
+            self.threads.append(reader)
+            reader.start()
+            if writable:
+                writer = threading.Thread(target=self._write_requests, name="alk-bounded-input", daemon=True)
+                self.threads.append(writer)
+                writer.start()
+        except BaseException:
+            self.close()
+            raise
+
+    def fail(self, code: str) -> None:
+        if self.failure is None:
+            self.failure = code
+
+    def check(self) -> None:
+        if self.failure:
+            raise LifecycleError(self.failure, "Bounded process transport failed")
+        if time.monotonic() >= self.deadline:
+            raise LifecycleError("bounded-process-timeout", "Process exceeded its deadline")
+
+    def remaining(self) -> float:
+        self.check()
+        return min(_POLL_SECONDS, max(0.0001, self.deadline - time.monotonic()))
+
+    def _drain_stderr(self) -> None:
+        assert self.process.stderr is not None
+        try:
+            while not self.stopping.is_set():
+                data = os.read(
+                    self.process.stderr.fileno(), min(_CHUNK_BYTES, self.max_stderr_bytes - len(self.stderr) + 1)
+                )
+                if not data:
+                    return
+                if len(self.stderr) + len(data) > self.max_stderr_bytes:
+                    self.fail("bounded-process-stderr-limit")
+                    return
+                self.stderr.extend(data)
+        except OSError:
+            if not self.stopping.is_set():
+                self.fail("bounded-process-read-failed")
+
+    def _write_requests(self) -> None:
+        assert self.process.stdin is not None
+        while not self.stopping.is_set():
+            try:
+                data, done = self.writes.get(timeout=_POLL_SECONDS)
+            except queue.Empty:
+                continue
+            try:
+                if data is None:
+                    self.process.stdin.close()
+                    return
+                view = memoryview(data)
+                while view:
+                    written = self.process.stdin.write(view.tobytes())
+                    if not written:
+                        raise BrokenPipeError
+                    view = view[written:]
+                self.process.stdin.flush()
+            except (OSError, ValueError):
+                self.fail("bounded-process-write-failed")
+                return
+            finally:
+                done.set()
+
+    def write_request(self, data: bytes | None) -> None:
+        """Deliver one small batch request, or close its input, under the same clock."""
+        if self.process.stdin is None or (data is not None and len(data) > 1024):
+            raise LifecycleError("bounded-process-request-invalid", "A bounded batch request is required")
+        done = threading.Event()
+        while True:
+            self.check()
+            try:
+                self.writes.put((data, done), timeout=self.remaining())
+                break
+            except queue.Full:
+                continue
+        while not done.wait(self.remaining()):
+            self.check()
+        self.check()
+
+    def wait(self) -> int:
+        while self.process.poll() is None:
+            time.sleep(self.remaining())
+        for thread in self.threads[1:2]:
+            while thread.is_alive():
+                thread.join(self.remaining())
+        self.check()
+        returncode = self.process.returncode
+        assert returncode is not None
+        return returncode
+
+    def close(self) -> None:
+        if self.closed:
+            return
+        self.closed = True
+        self.stopping.set()
+        cleanup_error: LifecycleError | None = None
+        if os.name == "posix":
+            with suppress(ProcessLookupError):
+                try:
+                    os.killpg(self.process.pid, signal.SIGKILL)
+                except PermissionError:
+                    # A reaped child must not prevent closing our descriptors.
+                    # Reader shutdown below still refuses a pipe held by a survivor.
+                    if self.process.poll() is None:
+                        self.process.kill()
+                        cleanup_error = LifecycleError(
+                            "bounded-process-cleanup-failed",
+                            "Child group signal was denied",
+                        )
+        else:
+            if self.windows_cleanup is not None:
+                try:
+                    self.windows_cleanup()
+                except LifecycleError as exc:
+                    cleanup_error = exc
+            if self.process.poll() is None:
+                self.process.kill()
+        try:
+            self.process.wait(timeout=_CLEANUP_SECONDS)
+        except subprocess.TimeoutExpired as exc:
+            raise LifecycleError("bounded-process-cleanup-failed", "Process did not exit during cleanup") from exc
+        deadline = time.monotonic() + _CLEANUP_SECONDS
+        for thread in self.threads:
+            if thread.ident is not None:
+                thread.join(max(0.0, deadline - time.monotonic()))
+        if any(thread.is_alive() for thread in self.threads):
+            raise LifecycleError("bounded-process-cleanup-failed", "Process pipes did not finish during cleanup")
+        for stream in (self.process.stdin, self.process.stdout, self.process.stderr):
+            if stream is not None:
+                stream.close()
+        if cleanup_error is not None:
+            raise cleanup_error
+
+    def __enter__(self) -> BoundedProcess:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+
+def run_bounded_command(
+    argv: list[str],
+    *,
+    cwd: Path,
+    timeout_seconds: float,
+    max_stdout_bytes: int,
+    max_stderr_bytes: int = 65536,
+) -> subprocess.CompletedProcess[bytes]:
+    """Capture a bounded command without allowing communicate() to grow unbounded."""
+    if type(timeout_seconds) not in (int, float) or not math.isfinite(timeout_seconds) or timeout_seconds <= 0:
+        raise LifecycleError("bounded-process-timeout-invalid", "A finite positive timeout is required")
+    with BoundedProcess(
+        argv,
+        cwd=cwd,
+        deadline=time.monotonic() + timeout_seconds,
+        max_stdout_bytes=max_stdout_bytes,
+        max_stderr_bytes=max_stderr_bytes,
+    ) as transport:
+        stdout = transport.stdout.read_all()
+        returncode = transport.wait()
+        return subprocess.CompletedProcess(argv, returncode, stdout, bytes(transport.stderr))
+
+
+__all__ = ["BoundedProcess", "run_bounded_command"]