Coverage for src/governed_harness/runtime/process_runner.py: 83%
230 statements
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
1from __future__ import annotations
3import contextlib
4import os
5import shutil
6import signal
7import subprocess # nosec B404 - the governed runner: resolved executable, no shell
8import sys
9import threading
10import time
11from collections.abc import Iterable, Mapping
12from dataclasses import dataclass, replace
13from pathlib import Path
14from typing import IO, Protocol
16from governed_harness.capabilities.authorizer import (
17 CapabilityAuthorizer,
18 CapabilityDenied,
19 contained_path,
20)
21from governed_harness.domain.enums import ResultStatus
22from governed_harness.domain.models import Actor, CapabilityGrant
23from governed_harness.runtime.cancellation import CancellationToken
26@dataclass(frozen=True)
27class CommandSpec:
28 argv: tuple[str, ...]
29 cwd: Path
30 timeout_seconds: float
31 allowed_environment: tuple[str, ...] = ()
32 max_output_bytes: int = 1_000_000
33 stdin: bytes | None = None
34 sandbox_prefix: tuple[str, ...] = ()
35 """Confinement wrapper (``runtime.agentSandbox``) placed before ``argv`` after authorization:
36 the capability grant applies to the command itself, the wrapper is the harness's own."""
39@dataclass(frozen=True)
40class ProcessResult:
41 status: ResultStatus
42 exit_code: int | None
43 stdout: bytes
44 stderr: bytes
45 timed_out: bool
46 cancelled: bool
47 duration_ms: int
48 stdout_truncated: bool = False
49 stderr_truncated: bool = False
50 executable: str | None = None
51 """The program that was started: the absolute path a bare command name resolved to on
52 Windows, the name as written elsewhere."""
55def resolve_executable(argv0: str, *, exclude: Iterable[Path] = ()) -> str:
56 """On Windows, resolve a bare command name through PATH and PATHEXT (``npm`` is
57 ``npm.cmd``), which CreateProcess does not do; elsewhere return it unchanged. Authorization
58 always applies to the name as written in the command.
60 The search never looks in the current directory, in a relative PATH entry or in an
61 ``exclude`` directory (the workspace): ``shutil.which`` on Windows looks in the current
62 directory first, so a ``python.bat`` written by the agent in the workspace ran instead of
63 Python (F12). A name with a directory part (``./gradlew``) is taken as written. A bare name
64 found nowhere raises ``FileNotFoundError`` (what starting a missing program raises) instead
65 of letting CreateProcess search the current directory."""
66 if sys.platform != "win32":
67 return argv0
68 if os.path.dirname(argv0): 68 ↛ 69line 68 didn't jump to line 69 because the condition on line 68 was never true
69 return shutil.which(argv0) or argv0
70 for directory in _search_path(exclude):
71 found = shutil.which(os.path.join(directory, argv0))
72 if found:
73 return found
74 raise FileNotFoundError(
75 f"{argv0} was not found on PATH (the working directory is not searched)"
76 )
79def find_executable(argv0: str) -> str | None:
80 """The program ``argv0`` starts, as :func:`resolve_executable` finds it on Windows (never
81 in the current directory) and ``shutil.which`` elsewhere; ``None`` when there is none."""
82 if sys.platform != "win32": 82 ↛ 84line 82 didn't jump to line 84 because the condition on line 82 was always true
83 return shutil.which(argv0)
84 try:
85 found = resolve_executable(argv0)
86 except FileNotFoundError:
87 return None
88 return found if os.path.dirname(argv0) == "" or os.path.exists(found) else None
91def _search_path(exclude: Iterable[Path]) -> list[str]:
92 """The absolute PATH entries, without the current directory and the excluded ones."""
93 skipped = {_normalized(Path.cwd()), *(_normalized(item) for item in exclude)}
94 entries: list[str] = []
95 for entry in os.environ.get("PATH", "").split(os.pathsep):
96 entry = entry.strip().strip('"')
97 if not entry or not os.path.isabs(entry) or _normalized(Path(entry)) in skipped:
98 continue
99 entries.append(entry)
100 return entries
103def _normalized(path: Path) -> str:
104 try:
105 resolved = path.resolve(strict=False)
106 except OSError:
107 resolved = path
108 return os.path.normcase(str(resolved))
111_READ_CHUNK_BYTES = 65536
112_POLL_SECONDS = 0.05
113_READER_JOIN_SECONDS = 5.0
116class _BoundedReader(threading.Thread):
117 """Drains a pipe, keeping only the first ``limit`` bytes."""
119 def __init__(self, stream: IO[bytes], limit: int) -> None:
120 super().__init__(daemon=True)
121 self._stream = stream
122 self._limit = limit
123 self._chunks: list[bytes] = []
124 self._kept = 0
125 self.truncated = False
127 def run(self) -> None:
128 try:
129 descriptor = self._stream.fileno()
130 while chunk := os.read(descriptor, _READ_CHUNK_BYTES):
131 room = self._limit - self._kept
132 if room > 0:
133 self._chunks.append(chunk[:room])
134 self._kept += min(len(chunk), room)
135 if len(chunk) > max(room, 0):
136 self.truncated = True
137 except (OSError, ValueError):
138 pass # the pipe was closed while reading; keep what was read
139 finally:
140 self._stream.close()
142 def data(self) -> bytes:
143 return b"".join(self._chunks)
146def _write_stdin(stream: IO[bytes], data: bytes) -> None:
147 # A child that exits without reading its input closes the pipe; that is not an error here.
148 with contextlib.suppress(OSError, ValueError):
149 stream.write(data)
150 with contextlib.suppress(OSError):
151 stream.close()
154class ProcessObserver(Protocol):
155 """Told about every process the runner starts and finishes (``governance.workspaceLease``
156 records the process groups so that a recovery can terminate what a killed harness left)."""
158 def started(self, pid: int, argv: tuple[str, ...]) -> None:
159 """Record that process ``pid`` started with ``argv``."""
161 def finished(self, pid: int) -> None:
162 """Record that process ``pid`` finished."""
165class SafeProcessRunner:
166 def __init__(
167 self,
168 workspace_root: Path,
169 authorizer: CapabilityAuthorizer | None = None,
170 *,
171 observer: ProcessObserver | None = None,
172 terminate_on_exit: bool = False,
173 ) -> None:
174 """``terminate_on_exit``: when the harness itself is interrupted while it waits
175 (``KeyboardInterrupt``, or ``SystemExit`` from a ``SIGTERM`` handler), terminate the
176 child's process group before the exception propagates."""
177 self.workspace_root = workspace_root.resolve(strict=True)
178 self.authorizer = authorizer or CapabilityAuthorizer()
179 self.observer = observer
180 self.terminate_on_exit = terminate_on_exit
182 def _authorize(self, spec: CommandSpec, actor: Actor, grants: list[CapabilityGrant]) -> Path:
183 """Check the command against the grants and the policies before it starts; returns the
184 working directory, contained in the workspace."""
185 if not spec.argv or any("\x00" in part for part in (*spec.argv, *spec.sandbox_prefix)): 185 ↛ 186line 185 didn't jump to line 186 because the condition on line 185 was never true
186 raise ValueError("argv must be a non-empty, NUL-free vector")
187 try:
188 self.authorizer.authorize_command(actor=actor, argv=spec.argv, grants=grants)
189 except CapabilityDenied as error:
190 from governed_harness.capabilities.phase import current_policy
192 policy = current_policy()
193 if policy is not None:
194 # governance.phaseCapabilities (#87): an agent's refused command is a finding
195 # and blocks the phase.
196 policy.refuse(actor, spec.argv, error)
197 raise
198 cwd = contained_path(self.workspace_root, spec.cwd)
199 from governed_harness.capabilities.repository import current_destructive
201 destructive = current_destructive()
202 if destructive is not None:
203 # governance.applyRepositoryPolicies, destructiveActionsDefault: deny (#5).
204 destructive.check(spec.argv, cwd, actor, grants)
205 return cwd
207 def run(
208 self,
209 spec: CommandSpec,
210 *,
211 actor: Actor,
212 grants: list[CapabilityGrant],
213 extra_env: Mapping[str, str] | None = None,
214 cancellation: CancellationToken | None = None,
215 ) -> ProcessResult:
216 cwd = self._authorize(spec, actor, grants)
217 environment = self._environment(spec, extra_env)
218 executable = resolve_executable(spec.argv[0], exclude=(self.workspace_root, cwd))
219 start = time.perf_counter()
220 process = subprocess.Popen( # nosec B603 - executable resolved and checked by policy, shell=False
221 [*spec.sandbox_prefix, executable, *spec.argv[1:]],
222 cwd=cwd,
223 env=environment,
224 stdin=subprocess.PIPE if spec.stdin is not None else subprocess.DEVNULL,
225 stdout=subprocess.PIPE,
226 stderr=subprocess.PIPE,
227 shell=False,
228 start_new_session=sys.platform != "win32",
229 )
230 if self.observer is not None:
231 self.observer.started(process.pid, spec.argv)
232 try:
233 return replace(self._wait(process, spec, start, cancellation), executable=executable)
234 except BaseException:
235 if self.terminate_on_exit:
236 self._terminate(process)
237 if sys.platform != "win32":
238 # The leader may be gone while its children still run in its group.
239 with contextlib.suppress(ProcessLookupError, PermissionError):
240 os.killpg(process.pid, signal.SIGKILL)
241 with contextlib.suppress(subprocess.TimeoutExpired):
242 process.wait(timeout=_READER_JOIN_SECONDS)
243 raise
244 finally:
245 if self.observer is not None and process.poll() is not None:
246 self.observer.finished(process.pid)
248 def _wait(
249 self,
250 process: subprocess.Popen[bytes],
251 spec: CommandSpec,
252 start: float,
253 cancellation: CancellationToken | None,
254 ) -> ProcessResult:
255 if process.stdout is None or process.stderr is None: # not reached: both are pipes 255 ↛ 256line 255 didn't jump to line 256 because the condition on line 255 was never true
256 raise RuntimeError("the process was started without its output pipes")
257 # Read both streams while the process runs and keep at most max_output_bytes of each;
258 # the rest is drained and discarded, so memory stays bounded whatever the output size.
259 readers = [
260 _BoundedReader(process.stdout, spec.max_output_bytes),
261 _BoundedReader(process.stderr, spec.max_output_bytes),
262 ]
263 for reader in readers:
264 reader.start()
265 writer = self._start_writer(process, spec)
266 deadline = start + spec.timeout_seconds
267 timed_out, cancelled = self._poll(process, readers, cancellation, deadline)
268 process.wait()
269 if writer is not None:
270 writer.join(timeout=_READER_JOIN_SECONDS)
271 for reader in readers:
272 reader.join(timeout=_READER_JOIN_SECONDS)
273 duration_ms = max(0, round((time.perf_counter() - start) * 1000))
274 stdout, stderr = readers[0].data(), readers[1].data()
275 stdout_truncated, stderr_truncated = readers[0].truncated, readers[1].truncated
276 return ProcessResult(
277 status=_result_status(cancelled, timed_out, process.returncode),
278 exit_code=process.returncode,
279 stdout=stdout,
280 stderr=stderr,
281 timed_out=timed_out,
282 cancelled=cancelled,
283 duration_ms=duration_ms,
284 stdout_truncated=stdout_truncated,
285 stderr_truncated=stderr_truncated,
286 )
288 @staticmethod
289 def _start_writer(
290 process: subprocess.Popen[bytes], spec: CommandSpec
291 ) -> threading.Thread | None:
292 """Start the thread that writes ``spec.stdin``; ``None`` without input."""
293 if spec.stdin is None:
294 return None
295 if process.stdin is None: # not reached: stdin is a pipe when there is input 295 ↛ 296line 295 didn't jump to line 296 because the condition on line 295 was never true
296 raise RuntimeError("the process was started without its input pipe")
297 writer = threading.Thread(
298 target=_write_stdin, args=(process.stdin, spec.stdin), daemon=True
299 )
300 writer.start()
301 return writer
303 def _poll(
304 self,
305 process: subprocess.Popen[bytes],
306 readers: list[_BoundedReader],
307 cancellation: CancellationToken | None,
308 deadline: float,
309 ) -> tuple[bool, bool]:
310 """Wait until the process exits, is cancelled or reaches the deadline; whether it timed
311 out and whether it was cancelled."""
312 while True:
313 # Joining the readers returns as soon as the child closes its output (normally when
314 # it exits), without the growing sleep intervals of Popen.wait(timeout=...).
315 for reader in readers:
316 reader.join(timeout=_POLL_SECONDS)
317 if not any(reader.is_alive() for reader in readers) and _exited(process):
318 return False, False
319 if cancellation and cancellation.cancelled: 319 ↛ 320line 319 didn't jump to line 320 because the condition on line 319 was never true
320 self._terminate(process)
321 return False, True
322 if time.perf_counter() >= deadline:
323 self._terminate(process)
324 return True, False
326 @staticmethod
327 def _terminate(process: subprocess.Popen[bytes]) -> None:
328 if process.poll() is not None: 328 ↛ 329line 328 didn't jump to line 329 because the condition on line 328 was never true
329 return
330 try:
331 if sys.platform == "win32": 331 ↛ 332line 331 didn't jump to line 332 because the condition on line 331 was never true
332 process.terminate()
333 else:
334 os.killpg(process.pid, signal.SIGTERM)
335 process.wait(timeout=1.0)
336 except (ProcessLookupError, subprocess.TimeoutExpired):
337 # Still running after SIGTERM: kill it; a process group that is already gone is fine.
338 with contextlib.suppress(ProcessLookupError):
339 if sys.platform == "win32":
340 process.kill()
341 else:
342 os.killpg(process.pid, signal.SIGKILL)
344 @staticmethod
345 def _environment(spec: CommandSpec, extra_env: Mapping[str, str] | None) -> dict[str, str]:
346 environment = {
347 name: os.environ[name] for name in spec.allowed_environment if name in os.environ
348 }
349 # Preserve only minimal executable lookup and locale by default.
350 names = ["PATH", "HOME", "SYSTEMROOT", "TMPDIR", "TEMP", "LANG", "LC_ALL"]
351 if sys.platform == "win32":
352 # Windows has no HOME outside Git Bash: Python's ``Path.home()`` (an agent provider
353 # started without HOME) reads USERPROFILE, or HOMEDRIVE and HOMEPATH.
354 names += ["USERPROFILE", "HOMEDRIVE", "HOMEPATH"]
355 for name in names:
356 if name in os.environ:
357 environment.setdefault(name, os.environ[name])
358 if extra_env:
359 unknown = set(extra_env) - set(spec.allowed_environment)
360 if unknown: 360 ↛ 361line 360 didn't jump to line 361 because the condition on line 360 was never true
361 raise ValueError(f"environment variables not authorized: {sorted(unknown)}")
362 environment.update(extra_env)
363 return environment
366def _exited(process: subprocess.Popen[bytes]) -> bool:
367 """Whether the process exits within a poll interval once its streams are closed."""
368 try:
369 process.wait(timeout=_POLL_SECONDS)
370 except subprocess.TimeoutExpired:
371 return False # the streams are closed but the process still runs
372 return True
375def _result_status(cancelled: bool, timed_out: bool, returncode: int) -> ResultStatus:
376 if cancelled: 376 ↛ 377line 376 didn't jump to line 377 because the condition on line 376 was never true
377 return ResultStatus.CANCELLED
378 if timed_out:
379 return ResultStatus.TIMED_OUT
380 if returncode == 0:
381 return ResultStatus.PASSED
382 return ResultStatus.FAILED