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

1from __future__ import annotations 

2 

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 

15 

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 

24 

25 

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.""" 

37 

38 

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.""" 

53 

54 

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. 

59 

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 ) 

77 

78 

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 

89 

90 

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 

101 

102 

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)) 

109 

110 

111_READ_CHUNK_BYTES = 65536 

112_POLL_SECONDS = 0.05 

113_READER_JOIN_SECONDS = 5.0 

114 

115 

116class _BoundedReader(threading.Thread): 

117 """Drains a pipe, keeping only the first ``limit`` bytes.""" 

118 

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 

126 

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() 

141 

142 def data(self) -> bytes: 

143 return b"".join(self._chunks) 

144 

145 

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() 

152 

153 

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).""" 

157 

158 def started(self, pid: int, argv: tuple[str, ...]) -> None: 

159 """Record that process ``pid`` started with ``argv``.""" 

160 

161 def finished(self, pid: int) -> None: 

162 """Record that process ``pid`` finished.""" 

163 

164 

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 

181 

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 

191 

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 

200 

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 

206 

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) 

247 

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 ) 

287 

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 

302 

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 

325 

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) 

343 

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 

364 

365 

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 

373 

374 

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