@yahyahammad/venastine 0.2.0 → 0.3.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (129) hide show
  1. package/.env.example +19 -14
  2. package/CONFIG_ARCHITECTURE.md +2002 -0
  3. package/NOTICE +1 -1
  4. package/README.md +233 -94
  5. package/agents/builtin/build.md +73 -0
  6. package/agents/builtin/general.md +80 -0
  7. package/agents/builtin/plan.md +23 -5
  8. package/agents/builtin/test.md +65 -0
  9. package/agents/builtin/writer.md +67 -0
  10. package/agents/manager.py +261 -195
  11. package/agents/subagent_tool.py +277 -43
  12. package/agents/tui_commands.py +7 -12
  13. package/bin/venastine.mjs +528 -382
  14. package/bin/venastine.py +71 -0
  15. package/cli_commands.py +835 -0
  16. package/config.py +95 -1198
  17. package/config.yaml +1090 -0
  18. package/config_edit.py +1301 -0
  19. package/config_schema.py +966 -0
  20. package/config_update.py +749 -0
  21. package/core/agent_activity.py +158 -20
  22. package/core/ansi.py +452 -0
  23. package/core/approval.py +27 -5
  24. package/core/call_view.py +364 -0
  25. package/core/cancel.py +121 -0
  26. package/core/chatgpt_auth.py +747 -0
  27. package/core/claims_view.py +107 -0
  28. package/core/client.py +1238 -82
  29. package/core/commands.py +454 -0
  30. package/core/compaction.py +830 -66
  31. package/core/config_loader.py +516 -97
  32. package/core/connect.py +686 -0
  33. package/core/events.py +68 -6
  34. package/core/file_mentions.py +280 -0
  35. package/core/interaction.py +87 -4
  36. package/core/line_pattern.py +128 -0
  37. package/core/loop.py +1516 -440
  38. package/core/memory.py +120 -8
  39. package/core/pipeline_models.py +23 -9
  40. package/core/provider_errors.py +234 -0
  41. package/core/reasoning/confidence_scoring.py +70 -54
  42. package/core/reasoning/json_retry.py +19 -1
  43. package/core/reasoning/orchestrator.py +232 -53
  44. package/core/reasoning/output_writer.py +90 -31
  45. package/core/reasoning/payload_validation.py +133 -7
  46. package/core/reasoning/pipeline_storage.py +427 -361
  47. package/core/reasoning/review.py +659 -615
  48. package/core/reasoning/scholar.py +38 -14
  49. package/core/reasoning/source_corpus.py +110 -4
  50. package/core/replay.py +158 -26
  51. package/core/session.py +36 -12
  52. package/core/session_view.py +259 -0
  53. package/core/session_wake.py +259 -0
  54. package/core/shell_sessions.py +1553 -0
  55. package/core/workspace_trust.py +1 -1
  56. package/credentials.py +308 -180
  57. package/database.py +82 -1
  58. package/{PRIVACY.md → docs/PRIVACY.md} +19 -7
  59. package/docs/SECURITY.md +108 -0
  60. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  61. package/env_secrets.py +118 -77
  62. package/json_store.py +236 -16
  63. package/logging_setup.py +121 -11
  64. package/main.py +1671 -199
  65. package/mcp_client/client.py +257 -23
  66. package/mcp_client/config.py +484 -379
  67. package/mcp_client/registration.py +163 -2
  68. package/memories/manager.py +15 -0
  69. package/memories/tui_commands.py +7 -12
  70. package/package.json +234 -4
  71. package/project_init/config_files.py +4 -0
  72. package/project_init/generator.py +201 -37
  73. package/project_init/manifest.py +418 -406
  74. package/project_init/tui_commands.py +7 -4
  75. package/prompts/revalidate.md +1 -1
  76. package/prompts/revise.md +17 -15
  77. package/prompts/system_prompts.py +64 -10
  78. package/providers.json.example +94 -92
  79. package/pyproject.toml +51 -2
  80. package/requirements.txt +252 -29
  81. package/safety/policy_enforcement.py +353 -17
  82. package/security/askpass.py +419 -0
  83. package/security/capability.py +37 -7
  84. package/security/confine.py +484 -0
  85. package/security/hosted.py +182 -0
  86. package/security/permissions.py +54 -7
  87. package/security/posture.py +124 -12
  88. package/security/protected_paths.py +198 -6
  89. package/security/sandbox.py +3262 -139
  90. package/security/secrets.py +855 -0
  91. package/skills/tui_commands.py +3 -4
  92. package/storage.py +368 -35
  93. package/tools/base.py +465 -305
  94. package/tools/builtin/_math_common.py +306 -16
  95. package/tools/builtin/_net_common.py +267 -61
  96. package/tools/builtin/arxiv.py +681 -223
  97. package/tools/builtin/ask_user.py +231 -213
  98. package/tools/builtin/discrete_math.py +35 -4
  99. package/tools/builtin/fetch_url.py +239 -21
  100. package/tools/builtin/file_ops.py +341 -33
  101. package/tools/builtin/geometry.py +184 -148
  102. package/tools/builtin/get_time.py +2 -2
  103. package/tools/builtin/linear_algebra.py +66 -23
  104. package/tools/builtin/load_skill.py +10 -0
  105. package/tools/builtin/logic.py +171 -12
  106. package/tools/builtin/pin.py +46 -12
  107. package/tools/builtin/probability_stats.py +224 -228
  108. package/tools/builtin/project_docs.py +80 -21
  109. package/tools/builtin/remember.py +21 -4
  110. package/tools/builtin/shell.py +586 -67
  111. package/tools/builtin/shell_sessions.py +613 -0
  112. package/tools/builtin/symbolic_math.py +80 -10
  113. package/tools/builtin/todo.py +5 -3
  114. package/tools/builtin/web_search.py +329 -151
  115. package/tools/context.py +23 -0
  116. package/tools/isolation.py +387 -314
  117. package/tools/registry.py +347 -30
  118. package/tui/app.py +4645 -438
  119. package/tui/app.tcss +185 -2
  120. package/tui/commands.py +10 -154
  121. package/tui/diffs.py +286 -265
  122. package/tui/hosted_driver.py +102 -0
  123. package/tui/markdown.py +60 -10
  124. package/tui/meters.py +103 -7
  125. package/tui/screens.py +346 -92
  126. package/tui/themes.py +59 -19
  127. package/tui/widgets.py +1575 -111
  128. package/SECURITY.md +0 -88
  129. package/THIRD_PARTY_NOTICES.md +0 -100
@@ -3,10 +3,11 @@ security/sandbox.py
3
3
 
4
4
  Cross-platform command sandboxing with two backends:
5
5
 
6
- 1. **Docker** (default) — strong isolation via container namespaces.
7
- The workspace is mounted as a volume so output files appear on the
8
- host seamlessly. Network is disabled unless the command matches
9
- config.NETWORK_ALLOWED_COMMANDS.
6
+ 1. **A container** (default) — strong isolation via container namespaces,
7
+ run by Docker, or by Podman when Docker cannot run one (ROADMAP_v3
8
+ §49, SS22). The workspace is mounted as a volume so output files
9
+ appear on the host seamlessly. Network is disabled unless the command
10
+ matches config.NETWORK_ALLOWED_COMMANDS.
10
11
 
11
12
  2. **Subprocess + hardening** (fallback) — weak isolation. Requires
12
13
  explicit opt-in via config.ALLOW_INSECURE_SANDBOX_FALLBACK.
@@ -14,10 +15,40 @@ Cross-platform command sandboxing with two backends:
14
15
  workspace). Network cannot be restricted. CPU/memory limits are
15
16
  Unix-only (rlimit); Windows relies on wall-clock timeout only.
16
17
 
18
+ 3. **WSL** (ROADMAP_v3 §49, slice 3) — a real Linux userland, and NO
19
+ isolation at all. Requires explicit opt-in via
20
+ config.ALLOW_WSL_BACKEND, and the agent asks for it per call. It is
21
+ not a weaker container; it is the user's own machine with a POSIX
22
+ front on it: the harness's own config.yaml is writable from there,
23
+ `~/.config` is writable, and Windows interop survives an emptied
24
+ environment (measured), so a command can start `cmd.exe` with the
25
+ user's full authority. `containment_for` answers UNCONTAINED for
26
+ every tier on this backend (SS1).
27
+
28
+ 4. **SSH** (ROADMAP_v3 §49, slice 4) — a command on ANOTHER machine, and
29
+ the least inspectable backend there is. Requires explicit opt-in via
30
+ config.ALLOW_SSH_BACKEND, and the agent asks for it per call. What
31
+ makes it different in kind from WSL rather than in degree: this
32
+ process cannot `lstat` the remote filesystem, so every local question
33
+ about a path is being asked about the wrong machine. NOTHING on this
34
+ route is auto-approved (SS48) — not even a read-only command, which
35
+ every other backend runs unasked. Authentication is a key or an agent
36
+ and this harness never holds a secret (SS47); the host key is pinned
37
+ in config and a changed one is refused (SS49).
38
+
17
39
  Inert commands (read-only inspection from config.INERT_COMMANDS with
18
- no shell metacharacters and no path-qualified binary) bypass both
19
- backends and run via a lightweight subprocess with a scrubbed
20
- environment and timeout — no Docker or fallback config needed.
40
+ no shell metacharacters and no path-qualified binary) run in the
41
+ container as an argv with no shell, and on the host only when no
42
+ container runtime is available (ROADMAP_v2 §46, EP5). This docstring said
43
+ they bypassed both backends, which stopped being true at EP5.
44
+
45
+ THE WORD "docker" IN THIS MODULE'S NAMES MEANS THE CONTAINER ROUTE,
46
+ whichever runtime serves it: `is_docker_available`, `_run_docker`, the
47
+ `docker_available` parameter and `config.SANDBOX_DOCKER_IMAGE` all kept
48
+ their names when Podman arrived. Renaming the config key would break
49
+ config_update.py's merge of a user's own value across an npm update, and
50
+ the function names are patched at about thirty-five test sites. What the
51
+ route runs is `known_runtime()`.
21
52
 
22
53
  This module is intentionally separate from tools/builtin/shell.py so
23
54
  that other tools needing safe command execution can reuse it.
@@ -25,18 +56,27 @@ that other tools needing safe command execution can reuse it.
25
56
 
26
57
  from __future__ import annotations
27
58
 
59
+ import atexit
60
+ import contextlib
28
61
  import functools
62
+ import json
29
63
  import logging
30
64
  import os
31
65
  import platform
32
66
  import re
33
67
  import shlex
68
+ import shutil
69
+ import signal
34
70
  import subprocess
71
+ import tempfile
72
+ import threading
35
73
  import uuid
36
- from typing import Callable, Optional
74
+ from collections.abc import Callable
75
+ from dataclasses import dataclass
76
+ from typing import Optional
37
77
 
38
78
  import config
39
- from security import posture, protected_paths
79
+ from security import askpass, posture, protected_paths, secrets
40
80
  from security.capability import (
41
81
  CONTAINED,
42
82
  UNAVAILABLE,
@@ -72,7 +112,7 @@ def detect_shell() -> str:
72
112
  if platform.system() == "Windows":
73
113
  for candidate in ("pwsh", "powershell"):
74
114
  try:
75
- subprocess.run(
115
+ subprocess.run( # nosec B603 - shell probe: argv is three literals plus a candidate from the tuple above
76
116
  [candidate, "-NoProfile", "-Command", "exit 0"],
77
117
  capture_output=True, timeout=5,
78
118
  )
@@ -84,42 +124,1455 @@ def detect_shell() -> str:
84
124
 
85
125
 
86
126
  # ---------------------------------------------------------------------------
87
- # ---- Docker availability --------------------------------------------------
127
+ # ---- Container runtime ----------------------------------------------------
88
128
  # ---------------------------------------------------------------------------
89
129
 
130
+ DOCKER = "docker"
131
+ PODMAN = "podman"
132
+
133
+ # The cgroup controllers the container argv's limits need: --cpus, --memory
134
+ # and --pids-limit. A rootless runtime without all three delegated to the
135
+ # user cannot bind those flags (ROADMAP_v3 §49, SS24).
136
+ _LIMIT_CONTROLLERS = frozenset({"cpu", "memory", "pids"})
137
+
138
+ # A key in Podman's `info` output that Docker's never carries -- measured
139
+ # against podman 5.7.0 and Docker Desktop's CLI in batch 93. It is how a
140
+ # `docker` command that is really Podman (the podman-docker shim) is
141
+ # recognised without a second subprocess on the ordinary Docker path, so
142
+ # that SS24's check cannot be skipped by the name alone.
143
+ _PODMAN_INFO_MARKER = "buildahVersion"
144
+
145
+
146
+ @dataclass(frozen=True)
147
+ class RuntimeProbe:
148
+ """What the one probe per process found (SS22).
149
+
150
+ `name` is the CLI that runs the sandbox, or None. `reason` says why it
151
+ is None, for the unavailable message. `refused` marks the case worth a
152
+ WARNING: a runtime WAS there and was turned away because it cannot
153
+ enforce the limits, which a user can fix and would not otherwise learn.
154
+ """
155
+
156
+ name: Optional[str]
157
+ reason: str = ""
158
+ refused: bool = False
159
+
160
+
161
+ _runtime_probe: Optional[RuntimeProbe] = None
162
+ _runtime_lock = threading.Lock()
163
+
164
+
165
+ def _run_info(argv: list[str]) -> Optional[subprocess.CompletedProcess]:
166
+ """One `info` call, or None when the CLI is missing or does not answer
167
+ within the probe's 10s."""
168
+ try:
169
+ return subprocess.run(argv, capture_output=True, text=True, # nosec B603 - container-runtime `info` probe; callers build argv from the runtime name and literals
170
+ timeout=10)
171
+ except (OSError, subprocess.TimeoutExpired):
172
+ return None
173
+
174
+
175
+ def _why_podman_cannot_limit(cli: str) -> str:
176
+ """Why the Podman behind *cli* cannot enforce the sandbox's resource
177
+ limits, or "" when it can (SS24).
178
+
179
+ ROOTLESS is the only case that can fail. A rootful runtime owns the
180
+ cgroup tree and binds the flags on either cgroup version; a rootless one
181
+ needs cgroups v2 AND the three controllers delegated to the user, and on
182
+ cgroups v1 Podman accepts `--memory` with a warning and ignores it -- a
183
+ container with no pids limit is a fork bomb that reaches the host.
184
+
185
+ Fails CLOSED on anything unreadable. Not knowing whether the limits bind
186
+ is not a reason to assume they do.
187
+ """
188
+ result = _run_info([cli, "info", "--format", "{{json .}}"])
189
+ if result is None or result.returncode != 0:
190
+ return (f"`{cli} info` would not report its cgroup setup, so whether "
191
+ f"it can enforce the sandbox's limits is unknown")
192
+ try:
193
+ host = json.loads(result.stdout)["host"]
194
+ rootless = bool(host["security"]["rootless"])
195
+ version = host.get("cgroupVersion")
196
+ controllers = set(host.get("cgroupControllers") or ())
197
+ except (ValueError, TypeError, KeyError, AttributeError):
198
+ return (f"`{cli} info` could not be read, so whether it can enforce "
199
+ f"the sandbox's limits is unknown")
200
+ if not rootless:
201
+ return ""
202
+ if version != "v2":
203
+ return (f"rootless Podman on cgroups {version or 'of unknown version'} "
204
+ f"cannot enforce the sandbox's memory, CPU and process "
205
+ f"limits; move the host to cgroups v2")
206
+ missing = sorted(_LIMIT_CONTROLLERS - controllers)
207
+ if missing:
208
+ return (f"rootless Podman has no delegated {', '.join(missing)} "
209
+ f"cgroup controller, so the sandbox's limits would not "
210
+ f"bind; delegate cpu, memory and pids to your user")
211
+ return ""
212
+
213
+
214
+ def _probe_container_runtime() -> RuntimeProbe:
215
+ """Docker first, then Podman (SS22). Uncached -- `_probe()` memoises it.
216
+
217
+ Docker wins whenever it answers, which is the only behaviour anyone had
218
+ before Podman was supported. Podman is asked only when Docker is not
219
+ installed or its daemon does not answer, and is used only if it can
220
+ enforce the limits (SS24).
221
+ """
222
+ docker = _run_info([DOCKER, "info"])
223
+ if docker is not None and docker.returncode == 0:
224
+ if (isinstance(docker.stdout, str)
225
+ and _PODMAN_INFO_MARKER in docker.stdout):
226
+ why = _why_podman_cannot_limit(DOCKER)
227
+ if why:
228
+ return RuntimeProbe(None, f"`docker` is Podman here, and "
229
+ f"{why}", refused=True)
230
+ return RuntimeProbe(DOCKER)
231
+
232
+ docker_why = ("Docker is not installed or did not answer"
233
+ if docker is None else "Docker's daemon did not answer")
234
+ podman = _run_info([PODMAN, "info"])
235
+ if podman is None:
236
+ return RuntimeProbe(None, f"{docker_why}, and Podman is not "
237
+ f"installed or did not answer")
238
+ if podman.returncode != 0:
239
+ return RuntimeProbe(None, f"{docker_why}, and Podman did not answer "
240
+ f"(is its machine running?)")
241
+ why = _why_podman_cannot_limit(PODMAN)
242
+ if why:
243
+ return RuntimeProbe(None, f"{docker_why}, and {why}", refused=True)
244
+ return RuntimeProbe(PODMAN)
245
+
246
+
247
+ def _probe() -> RuntimeProbe:
248
+ """The probe, run at most once per process.
249
+
250
+ Memoised for the process, and worth it -- but NOT for the reason this
251
+ module used to give (audit #21). §18's headless callability filter
252
+ never reaches here: `schemas()` and `headless_hidden()` call
253
+ `_advertised()` first, which asks `is_tool_allowed`, and `shell` ships
254
+ permission `False` (measured by making the probe raise on entry: a full
255
+ `schemas(callable_only=True)` build reached it zero times). What the memo
256
+ is for is `shell.run()` and `_shell_approval_check`, on the path a user
257
+ takes after enabling `shell`: whether a runtime can run the sandbox does
258
+ not change meaningfully inside one process, a wrong answer costs a
259
+ restart, and each uncached probe costs up to 10s per CLI when a daemon
260
+ is unresponsive.
261
+
262
+ A lock rather than lru_cache, because two threads asking at once must
263
+ get ONE probe -- a parallel batch of subagents each calling `shell` --
264
+ and because the memo now carries the reason alongside the answer.
265
+ """
266
+ global _runtime_probe
267
+ with _runtime_lock:
268
+ if _runtime_probe is None:
269
+ _runtime_probe = _probe_container_runtime()
270
+ if _runtime_probe.refused:
271
+ logger.warning("No container runtime can run the sandbox: %s",
272
+ _runtime_probe.reason)
273
+ elif _runtime_probe.name == PODMAN:
274
+ logger.info("Container runtime: podman (Docker cannot run "
275
+ "the sandbox)")
276
+ return _runtime_probe
277
+
278
+
279
+ def container_runtime() -> Optional[str]:
280
+ """The CLI that runs the sandbox -- "docker", "podman" -- or None."""
281
+ return _probe().name
282
+
283
+
284
+ def known_runtime() -> str:
285
+ """The CLI a container route invokes, read WITHOUT probing.
286
+
287
+ Every production path reaches a container route through
288
+ `is_docker_available()`, which runs the probe, so by then this is the
289
+ real answer. A caller that hands `run_sandboxed` `docker_available=True`
290
+ without probing -- only tests do -- gets Docker's CLI, which is what
291
+ every argv test asserts. Probing here instead would run real `docker`
292
+ and `podman` subprocesses inside a test that patched the availability
293
+ answer, and GitHub's runners ship Podman, so the argv would change
294
+ under CI.
295
+ """
296
+ probe = _runtime_probe
297
+ return probe.name if probe is not None and probe.name else DOCKER
298
+
299
+
300
+ def _known_unavailable_reason() -> str:
301
+ """Why no runtime can run the sandbox, if the probe has said; never
302
+ probes, for `known_runtime()`'s reason."""
303
+ probe = _runtime_probe
304
+ return probe.reason if probe is not None and probe.name is None else ""
305
+
306
+
307
+ def _reset_runtime_probe() -> None:
308
+ """Forget the probe's answer. Tests only.
309
+
310
+ The memo above is SESSION-GLOBAL, so this is called from
311
+ `tests/conftest.py`'s `isolate_sandbox_probes` before every test and
312
+ not only by the two classes that test the detector (TECHNICAL_DEBT
313
+ 27). Until batch 107 it was the latter alone, and the first test
314
+ anywhere to reach a live probe decided the answer for every test
315
+ after it -- on Windows as well as WSL, so whether the suite passed
316
+ depended on whether a daemon happened to be running.
317
+ """
318
+ global _runtime_probe
319
+ with _runtime_lock:
320
+ _runtime_probe = None
321
+
90
322
 
91
- @functools.lru_cache(maxsize=1)
92
323
  def is_docker_available() -> bool:
93
- """Probe whether the Docker daemon is reachable.
94
-
95
- Cached for the process, and worth keeping cached -- but NOT for the
96
- reason this docstring used to give (audit #21).
97
-
98
- It said §18's headless callability filter reaches here via shell's
99
- approval_check on every schema build, costing roughly two `docker
100
- info` subprocesses per _run(). It cannot: `schemas()` and
101
- `headless_hidden()` both call `_advertised()` FIRST, `_advertised`
102
- calls `is_tool_allowed`, and `shell` is permission `False` -- so the
103
- filter never reaches approval_needed for it. Measured by making this
104
- probe raise on entry: a full `schemas(callable_only=True)` build
105
- reached it ZERO times.
106
-
107
- What the cache is actually for is `shell.run()` and
108
- `_shell_approval_check`, which both call this on the path a user
109
- takes after enabling `shell` in config.py. Docker's availability does
110
- not change meaningfully inside one process; a wrong answer costs a
111
- restart, and each uncached probe costs up to the 10s timeout when the
112
- daemon is unresponsive. So the cache stays -- it matters the moment
113
- the tool is enabled, which is the only moment anything here runs.
324
+ """Whether a container runtime can run the sandbox: Docker, or Podman
325
+ when Docker cannot (ROADMAP_v3 §49, SS22).
326
+
327
+ The name predates Podman and is kept, like `_run_docker`'s -- see the
328
+ module docstring. The probe behind it runs once per process.
114
329
  """
330
+ return container_runtime() is not None
331
+
332
+
333
+ # ---------------------------------------------------------------------------
334
+ # ---- The WSL backend (ROADMAP_v3 §49, slice 3, SS35-SS45) ------------------
335
+ # ---------------------------------------------------------------------------
336
+
337
+ BACKEND_CONTAINER = "container"
338
+ BACKEND_WSL = "wsl"
339
+ BACKEND_SSH = "ssh"
340
+ BACKENDS = (BACKEND_CONTAINER, BACKEND_WSL, BACKEND_SSH)
341
+
342
+ WSL = "wsl.exe"
343
+
344
+ # `wsl.exe -l -q` answers in UTF-16LE with CRLF line endings -- measured,
345
+ # and the reason this constant exists rather than a bare `.decode()`. Read
346
+ # as UTF-8 the output is a NUL-riddled string that splits into garbage and
347
+ # matches no distro name, so the probe would report "no distro installed"
348
+ # on a machine with three.
349
+ _WSL_LIST_ENCODING = "utf-16-le"
350
+
351
+
352
+ @dataclass(frozen=True)
353
+ class WslProbe:
354
+ """What the one WSL probe per process found.
355
+
356
+ `distro` is the name every WSL argv will carry, or None. It is always a
357
+ NAME, never the empty string that means "whatever the default is":
358
+ resolving it once here is what lets a refusal say which distro it tried,
359
+ and what stops a default that changes mid-run from moving where a
360
+ command lands. `reason` says why it is None.
361
+ """
362
+
363
+ distro: Optional[str]
364
+ reason: str = ""
365
+
366
+
367
+ _wsl_probe: Optional[WslProbe] = None
368
+ _wsl_lock = threading.Lock()
369
+
370
+
371
+ def _wsl_distros() -> Optional[list[str]]:
372
+ """Every installed distro's name, or None if WSL would not answer."""
115
373
  try:
116
- result = subprocess.run(
117
- ["docker", "info"],
118
- capture_output=True, timeout=10,
119
- )
120
- return result.returncode == 0
121
- except (FileNotFoundError, subprocess.TimeoutExpired):
374
+ result = subprocess.run([WSL, "-l", "-q"], capture_output=True, # nosec B603 - WSL distro list: a module constant and two literal flags
375
+ timeout=10)
376
+ except (OSError, subprocess.TimeoutExpired):
377
+ return None
378
+ if result.returncode != 0:
379
+ return None
380
+ try:
381
+ text = result.stdout.decode(_WSL_LIST_ENCODING)
382
+ except (UnicodeDecodeError, AttributeError):
383
+ return None
384
+ return [name.strip() for name in text.splitlines() if name.strip()]
385
+
386
+
387
+ def _probe_wsl() -> WslProbe:
388
+ """Which distro the WSL backend runs in, or why it cannot. Uncached.
389
+
390
+ A NAME is always resolved, even when `wsl_distro` is empty and WSL's
391
+ own default would do, because a name is what the rest of this module
392
+ needs: `wsl.exe -d NoSuchDistro` exits 4294967295 and writes its
393
+ complaint to STDOUT in UTF-16 (measured), so an unvalidated name fails
394
+ in a way that reads as the command failing rather than the backend
395
+ being misconfigured.
396
+
397
+ The default is taken as the first name `-l -q` lists, which is the
398
+ order `wsl.exe` itself prints and the one `--status` names as the
399
+ default.
400
+ """
401
+ if platform.system() != "Windows":
402
+ return WslProbe(None, "WSL exists only on Windows")
403
+ names = _wsl_distros()
404
+ if names is None:
405
+ return WslProbe(None, "`wsl.exe -l -q` did not answer, so WSL is not "
406
+ "installed or its service is not running")
407
+ if not names:
408
+ return WslProbe(None, "WSL is installed but no distribution is, so "
409
+ "there is nothing to run a command in")
410
+ configured = (config.WSL_DISTRO or "").strip()
411
+ if not configured:
412
+ return WslProbe(names[0])
413
+ for name in names:
414
+ if name.lower() == configured.lower():
415
+ return WslProbe(name)
416
+ return WslProbe(None, f"wsl_distro is {configured!r} and no such "
417
+ f"distribution is installed (found: "
418
+ f"{', '.join(names)})")
419
+
420
+
421
+ def _wsl() -> WslProbe:
422
+ """The WSL probe, run at most once per process and LAZILY.
423
+
424
+ Lazy is the point, not an optimisation: a user who never turns the
425
+ backend on must not pay `wsl.exe -l -q` at launch on a machine where
426
+ WSL's service has to start to answer it. The container probe is eager
427
+ because every shell call needs its answer; this one is reached only
428
+ from a call that asked for WSL.
429
+
430
+ A lock rather than lru_cache for `_probe()`'s reason: two subagents
431
+ calling at once must get one probe, and the memo carries the reason
432
+ beside the answer.
433
+ """
434
+ global _wsl_probe
435
+ with _wsl_lock:
436
+ if _wsl_probe is None:
437
+ _wsl_probe = _probe_wsl()
438
+ if _wsl_probe.distro is None:
439
+ logger.info("WSL backend unavailable: %s", _wsl_probe.reason)
440
+ else:
441
+ logger.info("WSL backend distribution: %s", _wsl_probe.distro)
442
+ return _wsl_probe
443
+
444
+
445
+ def _reset_wsl_probe() -> None:
446
+ """Forget the WSL probe's answer and the workspace translation it
447
+ produced. Tests only -- and BOTH, because the translation names the
448
+ distro that resolved it.
449
+
450
+ Called from `tests/conftest.py`'s `isolate_sandbox_probes` before
451
+ every test (TECHNICAL_DEBT 27). That it owns the lru_cache as well as
452
+ the memo is exactly why the fixture calls this rather than assigning
453
+ `_wsl_probe` itself.
454
+ """
455
+ global _wsl_probe
456
+ with _wsl_lock:
457
+ _wsl_probe = None
458
+ _wsl_workspace_memo.cache_clear()
459
+
460
+
461
+ def wsl_enabled() -> bool:
462
+ """Whether the USER has turned the WSL backend on (SS35).
463
+
464
+ Separate from `wsl_available()` and asked first everywhere, because the
465
+ two refusals say different things: one is "this machine does not allow
466
+ it" and the other is "this machine cannot do it", and a user who sees
467
+ the second when the first is true goes looking for a missing distro.
468
+ Read off the frozen posture, never `config` (UN1).
469
+ """
470
+ return posture.current().allow_wsl_backend
471
+
472
+
473
+ def wsl_available() -> bool:
474
+ """Whether a WSL command could run: enabled AND a distro resolved."""
475
+ return wsl_enabled() and _wsl().distro is not None
476
+
477
+
478
+ def wsl_distro() -> str:
479
+ """The distro a WSL argv names, read WITHOUT probing.
480
+
481
+ `known_runtime()`'s rule, for `known_runtime()`'s reason: a test that
482
+ patches availability must not make the argv builder start a real WSL
483
+ service, and the argv every test asserts is the one with the configured
484
+ name in it.
485
+ """
486
+ probe = _wsl_probe
487
+ if probe is not None and probe.distro:
488
+ return probe.distro
489
+ return (config.WSL_DISTRO or "").strip()
490
+
491
+
492
+ def wsl_unavailable_reason() -> str:
493
+ """Why a WSL call cannot run, as a whole sentence for the model.
494
+
495
+ One copy, for the gate and the two run paths -- `containment_for` and
496
+ `_route` must not describe the same refusal differently (EP6).
497
+ """
498
+ if not wsl_enabled():
499
+ return ("The WSL backend is turned off. A command can only run in "
500
+ "WSL when allow_wsl_backend is true in config.yaml, which "
501
+ "ships false because WSL is not an isolation boundary: a "
502
+ "command there reaches this harness's own files and can "
503
+ "start Windows programs with the user's full authority.")
504
+ reason = _wsl().reason
505
+ return (f"The WSL backend is on, but no command can run: {reason}."
506
+ if reason else "")
507
+
508
+
509
+ class _WslPathUnavailable(Exception):
510
+ """`wslpath` did not answer.
511
+
512
+ Private, and raised for one mechanical reason rather than to be
513
+ handled: it is what keeps a FAILURE out of
514
+ `_wsl_workspace_memo`'s cache. See that function (batch 142,
515
+ batch 142).
516
+ """
517
+
518
+
519
+ @functools.lru_cache(maxsize=8)
520
+ def _wsl_workspace_memo(workspace_dir: str) -> str:
521
+ """The live `wslpath` translation, memoised -- SUCCESSES ONLY.
522
+
523
+ THE FAILURE IS NOT CACHED, and that is why this is a separate
524
+ function instead of a branch. `functools.lru_cache` stores a
525
+ RETURN VALUE and never an exception, so raising makes "only a
526
+ success is remembered" a property of the cache rather than a rule
527
+ the body has to keep. Returning "" from inside the cached
528
+ function instead cached the REFUSAL for the life of the process.
529
+
530
+ Measured (batch 142) with `wslpath` set to fail once and
531
+ then succeed: calls 2 and 3 answered '' from the cache after a
532
+ single `wsl.exe` invocation, so the backend stayed down until the
533
+ user restarted -- and the refusal the model read named a cause
534
+ (a UNC path, an unmounted drive) that was not what happened.
535
+
536
+ CACHED AT ALL, because otherwise every WSL command pays a second
537
+ `wsl.exe` round trip for an answer that cannot change: a
538
+ workspace is bound once per process, and the mount that makes it
539
+ visible is a property of the machine. A `wslpath` that exited
540
+ non-zero or missed its 10s deadline is NOT a property of the
541
+ machine -- the two likeliest causes are the distro's service
542
+ still starting (the state `_probe_wsl`'s own reason text
543
+ anticipates) and a loaded machine missing a deadline, and both
544
+ change by themselves. That is the whole difference in lifetime:
545
+ the round trip worth saving is the one on the happy path, which
546
+ is the one that repeats.
547
+
548
+ The key is *workspace_dir* alone while the answer also depends on
549
+ `wsl_distro()`. Left as a note rather than a key change: the
550
+ distro cannot change inside one process, and `_reset_wsl_probe`
551
+ clears this cache and the distro memo together.
552
+ """
553
+ try:
554
+ result = subprocess.run( # nosec B603 - wslpath translation; the distro name came from WSL itself and the path from config
555
+ [WSL, "-d", wsl_distro(), "-e", "wslpath", "-a", "-u",
556
+ workspace_dir],
557
+ capture_output=True, timeout=10)
558
+ except (OSError, subprocess.TimeoutExpired) as exc:
559
+ raise _WslPathUnavailable(
560
+ "wslpath did not run: %s" % type(exc).__name__) from None
561
+ if result.returncode != 0:
562
+ raise _WslPathUnavailable(
563
+ "wslpath exited %d" % result.returncode)
564
+ translated = result.stdout.decode("utf-8", "replace").strip()
565
+ if not translated:
566
+ raise _WslPathUnavailable("wslpath printed nothing")
567
+ return translated
568
+
569
+
570
+ def _wsl_workspace(workspace_dir: str) -> str:
571
+ """*workspace_dir* as the distro sees it, or "" when it cannot see it.
572
+
573
+ `wsl.exe --cd` takes a Windows path and translates it -- and when it
574
+ CANNOT, it does not fail. Measured: `--cd \\\\127.0.0.1\\C$` exits 0,
575
+ warns on stderr, and runs the command in the user's Linux HOME. A
576
+ command that was approved against one working directory then runs in
577
+ another and reports success, which is the drift EP6 is about, arriving
578
+ through a flag rather than through a branch.
579
+
580
+ So the translation is done HERE, by `wslpath`, whose failure is an exit
581
+ code, and the POSIX path is what `--cd` is given -- measured working,
582
+ `--cd /tmp` runs in /tmp. An empty answer means the route refuses.
583
+
584
+ The caching, and why a failure is not cached, are in
585
+ `_wsl_workspace_memo`. This wrapper is the "" half of the
586
+ contract above: every caller refuses on an empty string, and
587
+ none of them should have to know that the absence arrives as an
588
+ exception so that the cache cannot keep it.
589
+ """
590
+ try:
591
+ return _wsl_workspace_memo(workspace_dir)
592
+ except _WslPathUnavailable as exc:
593
+ logger.debug("wslpath could not translate %r: %s",
594
+ workspace_dir, exc)
595
+ return ""
596
+
597
+
598
+ def _wsl_argv(
599
+ command: str,
600
+ workspace_posix: str,
601
+ *,
602
+ argv_mode: bool,
603
+ session_timeout_s: Optional[int] = None,
604
+ as_root: bool = False,
605
+ ) -> list[str]:
606
+ """The argv that runs *command* in the distro (SS43).
607
+
608
+ `_docker_argv`'s opposite number, and deliberately the same shape: a
609
+ prefix that says WHERE, then either the inert argv or a shell with the
610
+ command as one argument.
611
+
612
+ ARGV MODE IS NOT AN OPTIMISATION (SS39, SS43). An INERT command runs as
613
+ a bare argv with no shell because SS39 -- the classifier learns nothing
614
+ about WSL path forms -- rests on it. `_SHELL_METACHARACTERS` rejects
615
+ `~` and `$`, so those cannot reach an inert command; but `execve` also
616
+ does not expand them, and a shell between the classifier and the
617
+ executor would be a third tokeniser in the gap #157 came through twice.
618
+
619
+ `--norc --noprofile` for the other route, so what runs does not depend
620
+ on a user's `.bashrc` -- the container's property, kept. Measured: the
621
+ shell reports NOT_LOGIN, zero aliases and no BASH_ENV.
622
+
623
+ *workspace_posix* is already translated by `_wsl_workspace`; see there
624
+ for why `--cd` is never handed a Windows path.
625
+
626
+ *as_root* (slice 5b) puts `sudo` outermost and forces the SHELL form.
627
+ Both halves are decisions:
628
+
629
+ SS69 -- sudo wraps the shell, so the WHOLE command line runs as root,
630
+ pipes and redirects included. Prefixing only the first word gives the
631
+ classic half-root surprise (`sudo echo x > /etc/f` writes as the user)
632
+ and would make the approval notice a lie about what was approved.
633
+
634
+ ARGV MODE IS DROPPED HERE, and that does not weaken what it protects.
635
+ Argv mode exists so an AUTO-APPROVED inert command has no shell between
636
+ the classifier and the executor (SS39/SS43). A root command is never
637
+ auto-approved -- SS65/SS67 put an always-ask step above both opt-ins --
638
+ so the property has no work to do, and the guard below needs a shell.
639
+ """
640
+ args = [WSL, "--cd", workspace_posix, "-d", wsl_distro(), "-e"]
641
+ if as_root:
642
+ inner = ["bash", "--norc", "--noprofile", "-c",
643
+ _SUDO_STDIN_GUARD + command]
644
+ else:
645
+ inner = (_inert_argv(command) if argv_mode
646
+ else ["bash", "--norc", "--noprofile", "-c", command])
647
+ if session_timeout_s is not None:
648
+ # The container route's backstop, unchanged in purpose: the harness
649
+ # kills at the timeout and owns the `timed_out` answer, and this is
650
+ # for a harness that is no longer there to kill anything. Measured
651
+ # in the distro: `timeout -k 5 3` over a `sleep 60` exited 124 after
652
+ # 3.2s.
653
+ inner = ["timeout", "-k", str(_KILL_GRACE_S),
654
+ str(session_timeout_s)] + inner
655
+ if as_root:
656
+ # OUTERMOST, so `timeout` runs as root and can kill a root child.
657
+ # Measured both ways: rc 124 at 3s with no process left behind
658
+ # either way, and this order is the one that does not depend on
659
+ # sudo forwarding a signal it has no obligation to forward.
660
+ inner = _sudo_argv() + inner
661
+ return args + inner
662
+
663
+
664
+ # ---------------------------------------------------------------------------
665
+ # ---- The SSH backend (ROADMAP_v3 §49, slice 4, SS46-SS55) ------------------
666
+ # ---------------------------------------------------------------------------
667
+
668
+ # The OS's own OpenSSH, preferred over whatever `PATH` resolves -- SS38's
669
+ # GnuWin32 `cat` on a third route. Measured on the machine this was built
670
+ # on: `shutil.which("ssh")` answers a git-for-Windows MSYS2 build, not this
671
+ # one, and the two are NOT interchangeable. They agree on every happy path
672
+ # (argv, exit codes, streams) and disagree on FAILURES, which is the half a
673
+ # refusal is built out of: a refused connection is `ssh: connect to host
674
+ # ... Connection refused` from the MSYS2 build and `banner exchange:
675
+ # Connection to UNKNOWN port -1: Connection refused` from this one.
676
+ _SSH_SYSTEM_BINARY = os.path.join(
677
+ os.environ.get("SYSTEMROOT", r"C:\Windows"),
678
+ "System32", "OpenSSH", "ssh.exe")
679
+
680
+ # SS52. A remote `cd` that fails must not read as the command failing, so
681
+ # it exits with a code of our choosing and says so on stderr. Both, not
682
+ # either: 125 alone collides with `timeout`'s own vocabulary (124 timed
683
+ # out, 125 timeout itself failed, 126/127 exec problems), and a marker
684
+ # alone could be printed by a command. Measured together over a missing
685
+ # directory and an unreadable one -- rc 125 and the marker, both times.
686
+ _SSH_NO_WORKSPACE_CODE = 125
687
+ _SSH_NO_WORKSPACE_MARKER = "VEN_SSH_NO_WORKSPACE"
688
+
689
+ # Measured: a refused connection answers in 2.1 s and an unroutable host in
690
+ # whatever ConnectTimeout says. Kept short because a wrong host should cost
691
+ # the user a moment, not a minute.
692
+ _SSH_CONNECT_TIMEOUT_S = 10
693
+ # A dead network must end a session rather than hang it. There is no
694
+ # harness-side read deadline on a session's stream, so this is the only
695
+ # thing that ends one whose remote stopped answering.
696
+ _SSH_ALIVE_INTERVAL_S = 15
697
+ _SSH_ALIVE_COUNT_MAX = 3
698
+ # What the identity question is allowed to cost at startup (SS50).
699
+ _SSH_PROBE_TIMEOUT_S = 20
700
+
701
+ # SS50. A remote that is not POSIX would be given `bash --norc --noprofile
702
+ # -c` and a `cd --` guard, and neither means anything on, say, a Windows
703
+ # OpenSSH server whose shell is cmd.exe. The check is what the remote SAYS
704
+ # it is, and a remote that will not say is refused rather than guessed at.
705
+ _SSH_POSIX_SYSTEMS = ("linux", "darwin", "freebsd", "openbsd", "netbsd",
706
+ "dragonfly", "sunos", "aix")
707
+
708
+
709
+ @dataclass(frozen=True)
710
+ class SshProbe:
711
+ """What the one SSH probe per process found.
712
+
713
+ `target` is the `user@host` every SSH argv will carry, or None when no
714
+ command can run. `reason` says why it is None -- composed HERE rather
715
+ than quoted from `ssh`, because `ssh`'s own text is either generic or
716
+ absent: an encrypted key with no agent, an unknown user and no key at
717
+ all all say `Permission denied (publickey)`, and a refused connection
718
+ said nothing at all until `LogLevel=ERROR` was removed. SS36 reached
719
+ the same conclusion about `wsl.exe` exiting 4294967295 in silence.
720
+
721
+ `remote` is what the far end answered about itself, kept so the
722
+ approval notice and the result can DISCLOSE where a command ran
723
+ instead of implying it (SS50).
724
+ """
725
+
726
+ target: Optional[str]
727
+ binary: str = ""
728
+ version: str = ""
729
+ remote: str = ""
730
+ known_hosts: str = ""
731
+ reason: str = ""
732
+
733
+
734
+ _ssh_probe: Optional[SshProbe] = None
735
+ _ssh_lock = threading.Lock()
736
+ _ssh_known_hosts_path: Optional[str] = None
737
+
738
+
739
+ def ssh_enabled() -> bool:
740
+ """Whether the USER has turned the SSH backend on (SS46).
741
+
742
+ Separate from `ssh_available()` and asked first everywhere, for
743
+ `wsl_enabled()`'s reason: "this machine does not allow it" and "this
744
+ machine cannot do it" are different sentences, and a user shown the
745
+ second when the first is true goes looking for a broken network.
746
+ Read off the frozen posture, never `config` (UN1).
747
+ """
748
+ return posture.current().allow_ssh_backend
749
+
750
+
751
+ def _ssh_binary() -> str:
752
+ """The `ssh` this harness runs, resolved explicitly and never from PATH.
753
+
754
+ A configured value wins. Otherwise the OS's own copy, and only if that
755
+ is absent does `PATH` get a say -- which is also what makes this work
756
+ on a POSIX host, where `/usr/bin/ssh` is what `shutil.which` finds.
757
+ """
758
+ configured = (config.SSH_BINARY or "").strip()
759
+ if configured:
760
+ return configured
761
+ if os.path.exists(_SSH_SYSTEM_BINARY):
762
+ return _SSH_SYSTEM_BINARY
763
+ return shutil.which("ssh") or ""
764
+
765
+
766
+ def _write_known_hosts(host_key: str) -> str:
767
+ """Materialise the pinned host key into a file `ssh` will accept (SS49).
768
+
769
+ A file of our own, never `~/.ssh/known_hosts`: the harness's trust set
770
+ is exactly what the user pinned in config, and neither this process nor
771
+ anything else edits the user's. `ssh-keyscan`'s output carries a `#`
772
+ banner comment above the key, so a user who pastes the whole thing gets
773
+ the same result as one who pastes the key line.
774
+ """
775
+ global _ssh_known_hosts_path
776
+ lines = [ln.strip() for ln in host_key.splitlines()]
777
+ lines = [ln for ln in lines if ln and not ln.startswith("#")]
778
+ handle, path = tempfile.mkstemp(prefix="venastine_known_hosts_")
779
+ with os.fdopen(handle, "w", encoding="utf-8", newline="\n") as fh:
780
+ fh.write("\n".join(lines) + "\n")
781
+ _ssh_known_hosts_path = path
782
+ # REMOVED ON EXIT (batch 117). One file per process, not per call --
783
+ # `_ssh_known_hosts()` reuses the path once it is set -- so this never
784
+ # grew unbounded, but every SSH-using run left a
785
+ # `venastine_known_hosts_*` behind in TMPDIR. The only unlink was in
786
+ # `_reset_ssh_probe`, which has no production caller: conftest and
787
+ # test_ssh_backend are the only two files that reach it.
788
+ #
789
+ # The key itself is public, so this is hygiene rather than exposure.
790
+ # Registered per path and ignoring every error: a cleanup that raises
791
+ # during interpreter shutdown turns a tidy-up into a traceback on exit.
792
+ atexit.register(_remove_known_hosts, path)
793
+ return path
794
+
795
+
796
+ def _remove_known_hosts(path: str) -> None:
797
+ """Best-effort unlink of one known_hosts file, for `atexit`.
798
+
799
+ Swallows everything: the file may already be gone (`_reset_ssh_probe`
800
+ in tests), the directory may be read-only, and nothing a process can
801
+ learn at shutdown is worth a traceback on the way out.
802
+ """
803
+ try:
804
+ os.unlink(path)
805
+ except OSError:
806
+ pass # already gone; nothing worth reporting at shutdown
807
+
808
+
809
+ def _ssh_config_reason() -> str:
810
+ """The first thing missing from the configured host, or "".
811
+
812
+ Answered before any IO, so a machine with nothing configured pays
813
+ nothing for the answer, and each sentence says what to put where.
814
+ """
815
+ if not (config.SSH_HOST or "").strip():
816
+ return ("no host is configured. Set `ssh_host` (and `ssh_user`) in "
817
+ "config.yaml")
818
+ if not (config.SSH_USER or "").strip():
819
+ return ("no remote user is configured. Set `ssh_user` in config.yaml")
820
+ if not (config.SSH_REMOTE_WORKSPACE or "").strip():
821
+ # SS52. Not a default, deliberately: a backend that silently picks
822
+ # the remote login home would run approved work somewhere nobody
823
+ # named, and on a machine this process cannot look at.
824
+ return ("no remote working directory is configured. Set "
825
+ "`ssh_remote_workspace` in config.yaml to an absolute path "
826
+ "on the remote host -- it is not defaulted, because a "
827
+ "command that runs somewhere nobody named is the failure "
828
+ "this backend is most able to cause")
829
+ if not (config.SSH_HOST_KEY or "").strip():
830
+ host = (config.SSH_HOST or "").strip()
831
+ port = str(config.SSH_PORT or 22).strip()
832
+ return ("no host key is pinned. Run `ssh-keyscan -p " + port + " "
833
+ + host + "` and put its output in `ssh_host_key` in "
834
+ "config.yaml. It is pinned rather than trusted on first "
835
+ "use so that a host key that CHANGES is refused instead of "
836
+ "quietly accepted")
837
+ if not _ssh_binary():
838
+ return ("no `ssh` program was found. Set `ssh_binary` in "
839
+ "config.yaml to its full path")
840
+ return ""
841
+
842
+
843
+ def _probe_ssh() -> SshProbe:
844
+ """Ask the configured host what it is, once (SS50).
845
+
846
+ Config first and IO second, so the common case -- nothing configured --
847
+ costs no round trip. The identity command runs WITHOUT the `cd` guard:
848
+ a missing remote workspace is a per-command refusal with its own words
849
+ (SS52), and folding it in here would report "the host is unreachable"
850
+ for a directory typo.
851
+ """
852
+ reason = _ssh_config_reason()
853
+ if reason:
854
+ return SshProbe(None, reason=reason)
855
+
856
+ binary = _ssh_binary()
857
+ user = (config.SSH_USER or "").strip()
858
+ host = (config.SSH_HOST or "").strip()
859
+ target = f"{user}@{host}"
860
+ try:
861
+ known = _write_known_hosts(config.SSH_HOST_KEY or "")
862
+ except OSError as exc:
863
+ return SshProbe(None, binary=binary,
864
+ reason=f"the pinned host key could not be written "
865
+ f"to a temporary file ({exc})")
866
+
867
+ version = ""
868
+ try:
869
+ shown = subprocess.run([binary, "-V"], capture_output=True, # nosec B603 - `ssh -V`; the binary was resolved by this probe
870
+ timeout=_SSH_PROBE_TIMEOUT_S)
871
+ version = (shown.stderr or shown.stdout).decode(
872
+ "utf-8", "replace").strip()
873
+ except (OSError, subprocess.TimeoutExpired):
874
+ return SshProbe(None, binary=binary,
875
+ reason=f"`{binary}` could not be run")
876
+
877
+ identity = "uname -s; command -v bash; command -v timeout"
878
+ argv = _ssh_connection_argv(binary, target, known) + [identity]
879
+ try:
880
+ result = subprocess.run(argv, capture_output=True, # nosec B603 - ssh identity probe; the remote command is the literal assembled two lines up
881
+ stdin=subprocess.DEVNULL,
882
+ timeout=_SSH_PROBE_TIMEOUT_S,
883
+ env=_ssh_env())
884
+ except subprocess.TimeoutExpired:
885
+ return SshProbe(None, binary=binary, version=version, known_hosts=known,
886
+ reason=f"{target} did not answer within "
887
+ f"{_SSH_PROBE_TIMEOUT_S}s")
888
+ except OSError as exc:
889
+ return SshProbe(None, binary=binary, version=version, known_hosts=known,
890
+ reason=f"`{binary}` could not be run ({exc})")
891
+
892
+ if result.returncode != 0:
893
+ detail = result.stderr.decode("utf-8", "replace").strip()
894
+ detail = " ".join(detail.split())[:300]
895
+ return SshProbe(
896
+ None, binary=binary, version=version, known_hosts=known,
897
+ reason=_ssh_connect_failure_reason(target, detail))
898
+
899
+ answered = [ln.strip() for ln
900
+ in result.stdout.decode("utf-8", "replace").splitlines()
901
+ if ln.strip()]
902
+ system = answered[0].lower() if answered else ""
903
+ if not any(system.startswith(name) for name in _SSH_POSIX_SYSTEMS):
904
+ return SshProbe(
905
+ None, binary=binary, version=version, known_hosts=known,
906
+ reason=f"{target} answered `uname -s` with "
907
+ f"{answered[0] if answered else '(nothing)'!r}, which "
908
+ f"this backend does not support. Every command it sends "
909
+ f"is a POSIX shell line -- `bash --norc --noprofile -c` "
910
+ f"inside a `cd --` guard -- and none of that means "
911
+ f"anything on a remote whose shell is not POSIX. A "
912
+ f"Windows OpenSSH server is the known case, and it is "
913
+ f"recorded as unmeasured rather than assumed to work")
914
+ missing = [need for need in ("bash", "timeout")
915
+ if not any(need in line for line in answered[1:])]
916
+ if missing:
917
+ return SshProbe(
918
+ None, binary=binary, version=version, known_hosts=known,
919
+ reason=f"{target} is missing {' and '.join(missing)}, which "
920
+ f"this backend needs on the remote: `bash` runs the "
921
+ f"command without the remote user's dotfiles, and "
922
+ f"`timeout` is the only thing that bounds a session "
923
+ f"after this harness has stopped watching it")
924
+
925
+ return SshProbe(target, binary=binary, version=version,
926
+ known_hosts=known, remote=" ".join(answered))
927
+
928
+
929
+ def _ssh_connect_failure_reason(target: str, detail: str) -> str:
930
+ """One sentence for a connection that did not happen, composed here.
931
+
932
+ `ssh`'s own text is the wrong thing to hand a model: measured, every
933
+ authentication failure -- an encrypted key with no agent, an unknown
934
+ user, no key offered at all -- says exactly `Permission denied
935
+ (publickey)`, so quoting it would tell the model the same thing about
936
+ three different fixes. The detail is kept AFTER the interpretation
937
+ rather than instead of it.
938
+ """
939
+ lowered = detail.lower()
940
+ if "permission denied" in lowered:
941
+ return (f"{target} refused the key. The backend only ever offers a "
942
+ f"key (SS47): check `ssh_identity_file`, and if the key is "
943
+ f"encrypted, load it into an agent with `ssh-add` first -- "
944
+ f"this harness never asks for a passphrase and never holds "
945
+ f"one, so an encrypted key with no agent cannot connect. "
946
+ f"ssh said: {detail}")
947
+ if "host key verification failed" in lowered or "known_hosts" in lowered:
948
+ return (f"{target} presented a host key that is not the one pinned "
949
+ f"in `ssh_host_key`. This is refused rather than accepted: "
950
+ f"either the host was rebuilt and the pin needs updating, "
951
+ f"or the connection is not reaching the host you think. "
952
+ f"ssh said: {detail}")
953
+ if "connection refused" in lowered:
954
+ return (f"nothing is listening for SSH at {target}. Check "
955
+ f"`ssh_host` and `ssh_port`. ssh said: {detail}")
956
+ if "timed out" in lowered or "timeout" in lowered:
957
+ return (f"{target} did not answer within {_SSH_CONNECT_TIMEOUT_S}s. "
958
+ f"ssh said: {detail}")
959
+ return f"{target} could not be reached. ssh said: {detail or '(nothing)'}"
960
+
961
+
962
+ def _ssh() -> SshProbe:
963
+ """The memoised answer, probed at most once per process.
964
+
965
+ LAZY, like the WSL probe and for the same reason: a user with the flag
966
+ off must not pay a network round trip at launch for a backend they
967
+ never asked for. Every caller reaches it through `ssh_available()`,
968
+ which asks `ssh_enabled()` first.
969
+ """
970
+ global _ssh_probe
971
+ if _ssh_probe is None:
972
+ with _ssh_lock:
973
+ if _ssh_probe is None:
974
+ _ssh_probe = _probe_ssh()
975
+ return _ssh_probe
976
+
977
+
978
+ def _reset_ssh_probe() -> None:
979
+ """Forget the SSH probe's answer and remove the known_hosts it wrote.
980
+ Tests only -- and both, because the file names the key that resolved.
981
+
982
+ Called from `tests/conftest.py`'s `isolate_sandbox_probes` before
983
+ every test (TECHNICAL_DEBT 27). Like `_reset_wsl_probe`, it owns more
984
+ than the memo, which is why the fixture goes through it.
985
+ """
986
+ global _ssh_probe, _ssh_known_hosts_path
987
+ with _ssh_lock:
988
+ _ssh_probe = None
989
+ if _ssh_known_hosts_path:
990
+ try:
991
+ os.unlink(_ssh_known_hosts_path)
992
+ except OSError:
993
+ pass # already gone; the path is forgotten below either way
994
+ _ssh_known_hosts_path = None
995
+
996
+
997
+ def ssh_available() -> bool:
998
+ """Whether an SSH command could run: enabled AND a host answered AND
999
+ the stored credentials have not already been refused."""
1000
+ if _ssh_auth_rejected:
122
1001
  return False
1002
+ return ssh_enabled() and _ssh().target is not None
1003
+
1004
+
1005
+ def ssh_target() -> str:
1006
+ """The `user@host` an SSH argv names, read WITHOUT probing.
1007
+
1008
+ `wsl_distro()`'s rule, for `wsl_distro()`'s reason: a test that patches
1009
+ availability must not make the argv builder open a real connection, and
1010
+ the argv every test asserts is the one built from the configured names.
1011
+ """
1012
+ probe = _ssh_probe
1013
+ if probe is not None and probe.target:
1014
+ return probe.target
1015
+ user = (config.SSH_USER or "").strip()
1016
+ host = (config.SSH_HOST or "").strip()
1017
+ return f"{user}@{host}" if (user and host) else host
1018
+
1019
+
1020
+ def ssh_unavailable_reason() -> str:
1021
+ """Why an SSH call cannot run, as a whole sentence for the model.
1022
+
1023
+ One copy, for the gate and the two run paths -- `containment_for` and
1024
+ `_route` must not describe the same refusal differently (EP6).
1025
+ """
1026
+ if not ssh_enabled():
1027
+ return ("The SSH backend is turned off. A command can only run on "
1028
+ "a remote host when allow_ssh_backend is true in "
1029
+ "config.yaml, which ships false because a remote host is "
1030
+ "not a sandbox: it is a machine this harness cannot "
1031
+ "inspect, with no isolation, no resource limits, and "
1032
+ "credentials it did not issue.")
1033
+ if _ssh_auth_rejected:
1034
+ return ("The SSH backend is on, but no command can run: "
1035
+ f"{_ssh_auth_rejected}.")
1036
+ reason = _ssh().reason
1037
+ return (f"The SSH backend is on, but no command can run: {reason}."
1038
+ if reason else "")
1039
+
1040
+
1041
+ #: SS60/SS63. Set when a connection that USED stored credentials was
1042
+ #: refused by the server, and never cleared by another attempt. A wrong
1043
+ #: stored password is not a reason to lock the whole store -- that would
1044
+ #: cost the master passphrase over one typo and buy nothing, since an
1045
+ #: attacker is not involved -- but it IS a reason to stop REPLAYING it:
1046
+ #: measured, one refused call makes TWO authentication attempts (the
1047
+ #: keyboard-interactive method and the password method each get their own
1048
+ #: prompt budget), so a harness that retried on every command would walk a
1049
+ #: real account into a lockout at four attempts a call.
1050
+ _ssh_auth_rejected = ""
1051
+
1052
+
1053
+ def _ssh_secret_name(suffix: str) -> str:
1054
+ """Where this host's secrets live (SS58).
1055
+
1056
+ The NAME says which machine it unlocks, and it is built from the
1057
+ configured host rather than from the target, so changing `ssh_user`
1058
+ does not silently orphan the entry the user typed.
1059
+ """
1060
+ return "ssh.%s.%s" % ((config.SSH_HOST or "").strip(), suffix)
1061
+
1062
+
1063
+ def _ssh_stored_secrets() -> dict:
1064
+ """`{askpass logical name -> Secret}` for the configured host.
1065
+
1066
+ Empty means "nothing is stored, or the store is locked", and empty is
1067
+ what keeps slice 4's behaviour EXACTLY as it shipped: `_ssh_connection_argv`
1068
+ reads this and, with nothing here, builds the argv it always built,
1069
+ option for option. A user on key-and-agent auth is not moved by this
1070
+ batch at all.
1071
+
1072
+ Reads through `secrets` rather than holding anything: this module never
1073
+ stores a plaintext, and the `Secret`s handed out live only for the
1074
+ length of one `askpass.serving` block.
1075
+ """
1076
+ if _ssh_auth_rejected:
1077
+ return {}
1078
+ if not (config.SSH_HOST or "").strip():
1079
+ return {}
1080
+ found = {}
1081
+ try:
1082
+ for logical, suffix in ((askpass.KEY_PASSPHRASE, "key_passphrase"),
1083
+ (askpass.LOGIN, "login")):
1084
+ secret = secrets.get(_ssh_secret_name(suffix))
1085
+ if secret is not None:
1086
+ found[logical] = secret
1087
+ except secrets.StoreLocked:
1088
+ # THE one place "the store is not open" is answered, and it is the
1089
+ # handler rather than an `is_unlocked()` check above it. Both were
1090
+ # written; the mutation pass showed the check could be deleted
1091
+ # without breaking anything, because this already answers.
1092
+ #
1093
+ # The handler is the half that survives a RACE, which is why it is
1094
+ # the one kept: the store can lock BETWEEN a check and a read --
1095
+ # the askpass listener refuses on its own thread, and a file that
1096
+ # changed on disk locks inside `secrets.get` itself -- and no
1097
+ # check above can cover that gap. Nothing stored is the safe
1098
+ # reading, and it is also the true one.
1099
+ return {}
1100
+ return found
1101
+
1102
+
1103
+ def _note_ssh_auth_failure(stderr: str, used_secrets: bool) -> None:
1104
+ """Quarantine the stored credentials when the server refused them."""
1105
+ global _ssh_auth_rejected
1106
+ if not used_secrets or _ssh_auth_rejected:
1107
+ return
1108
+ if "Permission denied" not in stderr:
1109
+ return
1110
+ _ssh_auth_rejected = (
1111
+ "the stored credentials for this host were refused by the server. "
1112
+ "They will not be tried again this run, so a wrong value cannot "
1113
+ "walk the account into a lockout. Fix them with `/secrets set "
1114
+ "%s` (or `%s`) and restart"
1115
+ % (_ssh_secret_name("login"), _ssh_secret_name("key_passphrase")))
1116
+ logger.warning("ssh: stored credentials refused; quarantined for this run")
1117
+
1118
+
1119
+ def _reset_ssh_auth_quarantine() -> None:
1120
+ """Tests only."""
1121
+ global _ssh_auth_rejected
1122
+ _ssh_auth_rejected = ""
1123
+
1124
+
1125
+ def _ssh_env() -> dict:
1126
+ """The environment the local `ssh` PROCESS gets.
1127
+
1128
+ `_scrubbed_env()` plus exactly one name, and the distinction is the
1129
+ point: `_SAFE_ENV_KEYS` says what a sandboxed COMMAND may see, and this
1130
+ says what the CLIENT needs to function. Measured, nothing from here
1131
+ crosses to the remote anyway -- an SSH session's environment is twelve
1132
+ variables and every one is the server's -- so widening the shared
1133
+ allowlist for this would have loosened three other routes to fix one.
1134
+
1135
+ WHY `PROGRAMDATA`, and why this was found by running rather than by
1136
+ reading: with `_scrubbed_env()` alone, Windows OpenSSH exits 255 and
1137
+ writes NOTHING to stderr. That is SS36's shape exactly -- a failure
1138
+ with no reason attached -- and it would have been diagnosed as an
1139
+ unreachable host. Bisected over twelve candidate variables (USERNAME,
1140
+ APPDATA, LOCALAPPDATA, SYSTEMDRIVE, PATHEXT and the rest), this is the
1141
+ only one that changes the answer FOR THIS ROUTE; it resolves
1142
+ `%PROGRAMDATA%\\ssh`, which the client reads even under `-F none`.
1143
+
1144
+ PATHEXT is named in that bisection and is now in `_SAFE_ENV_KEYS`
1145
+ anyway, which does not weaken the conclusion above: it was added for the
1146
+ FALLBACK shell, where its absence made `powershell` not wait for an
1147
+ external program, and it still changes nothing about `ssh`. Two routes,
1148
+ two measurements, one variable that happens to appear in both.
1149
+ """
1150
+ env = _scrubbed_env()
1151
+ for name in ("PROGRAMDATA", "ProgramData"):
1152
+ value = os.environ.get(name)
1153
+ if value:
1154
+ env["PROGRAMDATA"] = value
1155
+ break
1156
+ return env
1157
+
1158
+
1159
+ def _ssh_auth_options() -> list[str]:
1160
+ """The authentication options, and THE ONE PLACE that mode is decided.
1161
+
1162
+ Read through `_ssh_connection_argv` by the probe and by `_ssh_argv`
1163
+ alike, so the connection the probe measured is the connection a command
1164
+ gets -- EP6's rule on the half of this route that can now differ.
1165
+
1166
+ WITH NOTHING STORED THIS IS SLICE 4, OPTION FOR OPTION AND IN ORDER.
1167
+ `BatchMode=yes` and publickey-only: an encrypted key with no agent
1168
+ fails in 0.12 s instead of hanging for as long as anyone waits (SS47).
1169
+ A user on key-and-agent auth is not moved by slice 5 at all, and a test
1170
+ pins this list against the literal slice 4 shipped.
1171
+
1172
+ With something stored, `BatchMode` must come OFF -- it suppresses
1173
+ askpass too, so it and a stored secret are mutually exclusive -- and
1174
+ the anti-hang property moves to `SSH_ASKPASS_REQUIRE=force`, which
1175
+ `security/askpass.py` sets and which sends every prompt to a helper
1176
+ that answers immediately (SS63). Measured: `BatchMode=no` with no
1177
+ askpass hung for 20 s on the Windows build; with forced askpass the
1178
+ same call returned in 0.8 s.
1179
+
1180
+ `NumberOfPasswordPrompts=1` bounds the RETRIES within one method. It
1181
+ does NOT bound the number of prompts -- measured, a wrong password
1182
+ still produces two asks, because keyboard-interactive and password are
1183
+ separate methods with separate budgets. That is why the listener
1184
+ bounds its serves rather than serving exactly one, and why a refused
1185
+ call is quarantined rather than retried.
1186
+
1187
+ The preference list is measured too: a server offering both serves
1188
+ `keyboard-interactive`, so naming only `password` would fail against an
1189
+ ordinary sshd while reading as a credential problem.
1190
+ """
1191
+ if _ssh_stored_secrets():
1192
+ return [
1193
+ "-o", "BatchMode=no",
1194
+ "-o", "NumberOfPasswordPrompts=1",
1195
+ "-o", ("PreferredAuthentications="
1196
+ "publickey,keyboard-interactive,password"),
1197
+ ]
1198
+ return [
1199
+ # SS47, and the measurement that justifies the key-only default:
1200
+ # WITHOUT this, an encrypted key with no agent HANGS -- 20 s and
1201
+ # still waiting, because ssh is trying to prompt for a passphrase
1202
+ # on a terminal this process does not own.
1203
+ "-o", "BatchMode=yes",
1204
+ "-o", "PreferredAuthentications=publickey",
1205
+ ]
1206
+
1207
+
1208
+ def _ssh_connection_argv(binary: str, target: str, known: str) -> list[str]:
1209
+ """Everything that says WHERE and WHO, with no command on the end.
1210
+
1211
+ Shared by the probe and `_ssh_argv` so the connection the probe
1212
+ measured is the connection a command gets -- one of the two halves
1213
+ EP6's rule is about, on a route where the probe is the only thing that
1214
+ ever proved the host reachable.
1215
+ """
1216
+ auth = _ssh_auth_options()
1217
+ argv = [
1218
+ binary,
1219
+ # NO DOTFILES, the same property `bash --norc --noprofile` gives on
1220
+ # the far end (SS51). `ssh` otherwise reads a per-user config whose
1221
+ # location this harness CANNOT redirect -- measured: Windows
1222
+ # OpenSSH resolves the user's profile from the login token, so
1223
+ # setting HOME and USERPROFILE does not move it, and a probe that
1224
+ # tried to test the file's influence by redirecting HOME was
1225
+ # measuring nothing. That file can carry `ProxyCommand`,
1226
+ # `LocalCommand` and `SendEnv`, so without this flag what runs is
1227
+ # not what this argv says.
1228
+ "-F", "none",
1229
+ *auth,
1230
+ # SS49. The pin is the whole host-key policy: an unknown key and a
1231
+ # CHANGED key both refuse, and neither can be answered by a prompt
1232
+ # that a headless run has nobody to show.
1233
+ "-o", "StrictHostKeyChecking=yes",
1234
+ "-o", f"UserKnownHostsFile={known}",
1235
+ "-o", f"ConnectTimeout={_SSH_CONNECT_TIMEOUT_S}",
1236
+ "-o", f"ServerAliveInterval={_SSH_ALIVE_INTERVAL_S}",
1237
+ "-o", f"ServerAliveCountMax={_SSH_ALIVE_COUNT_MAX}",
1238
+ ]
1239
+ identity = (config.SSH_IDENTITY_FILE or "").strip()
1240
+ if identity:
1241
+ argv += ["-i", identity]
1242
+ # Only meaningful WITH an identity: it restricts ssh to the keys
1243
+ # this argv named. Omitted when none is configured, because there
1244
+ # it would rule out the agent, which SS47 explicitly allows as the
1245
+ # other way to authenticate without this harness holding a secret.
1246
+ argv += ["-o", "IdentitiesOnly=yes"]
1247
+ argv += ["-p", str(config.SSH_PORT or 22), target]
1248
+ return argv
1249
+
1250
+
1251
+ def _ssh_remote_script(command: str, workspace: str,
1252
+ session_timeout_s: Optional[int] = None,
1253
+ as_root: bool = False) -> str:
1254
+ """The ONE string the remote login shell parses (SS51).
1255
+
1256
+ `ssh` has no `execve` path: it joins its trailing argv with spaces and
1257
+ the remote LOGIN SHELL re-parses the result. So EP5's "argv, no shell"
1258
+ property -- which `_docker_argv` and `_wsl_argv` both keep -- cannot
1259
+ exist here, and pretending otherwise would put a third tokeniser in the
1260
+ gap #157 came through twice. What is possible is exactly one quoting
1261
+ boundary, owned by `shlex.quote`, and that is measured rather than
1262
+ argued: ten adversarial tokens (embedded quotes, backslashes, a
1263
+ trailing backslash, `$(id)`, backticks, a newline, glob characters)
1264
+ round-trip BYTE-IDENTICALLY through `list2cmdline` -> ssh -> the login
1265
+ shell -> `bash -c`.
1266
+
1267
+ It is also the second reason nothing here is auto-approved (SS48): the
1268
+ tier that the other routes may run unasked is the one defined by having
1269
+ no shell between the classifier and the executor, and this route cannot
1270
+ offer that.
1271
+
1272
+ *as_root* (slice 5b) splices `sudo` in front of the runner, INSIDE the
1273
+ one quoting boundary and BEHIND the `cd --` guard -- so a remote
1274
+ workspace that is not there still refuses with 125 and the marker
1275
+ before anything is elevated, and the guard's own failure is still the
1276
+ unprivileged user's. Measured against a real sshd: rc 125 and the
1277
+ marker, with sudo in the script.
1278
+ """
1279
+ runner = ["bash", "--norc", "--noprofile", "-c",
1280
+ _SUDO_STDIN_GUARD + command if as_root else command]
1281
+ if session_timeout_s is not None:
1282
+ # The container and WSL backstop, on a route that needs it MORE.
1283
+ # Measured: killing the local `ssh` does NOT kill the remote
1284
+ # command -- a `sleep 400` survived its client by design, because
1285
+ # without a pty there is no hangup to deliver. This is what bounds
1286
+ # a session whose harness has gone away, and it works with no
1287
+ # client alive (rc 124).
1288
+ runner = ["timeout", "-k", str(_KILL_GRACE_S),
1289
+ str(session_timeout_s)] + runner
1290
+ if as_root:
1291
+ runner = _sudo_argv() + runner
1292
+ quoted = " ".join(shlex.quote(part) for part in runner)
1293
+ return (
1294
+ "cd -- %s || { printf '%%s\\n' %s >&2; exit %d; }; exec %s"
1295
+ % (shlex.quote(workspace), shlex.quote(_SSH_NO_WORKSPACE_MARKER),
1296
+ _SSH_NO_WORKSPACE_CODE, quoted)
1297
+ )
1298
+
1299
+
1300
+ def _ssh_known_hosts() -> str:
1301
+ """The file `StrictHostKeyChecking` is checked against (SS49).
1302
+
1303
+ SELF-SUFFICIENT, and that is a fix rather than a nicety: this used to
1304
+ read the probe's path and fall back to "", which built
1305
+ `UserKnownHostsFile=` with no value -- an argv `ssh` rejects outright
1306
+ with `no argument after keyword`, reported as "the host could not be
1307
+ reached". In production the probe always ran first, so the broken argv
1308
+ was unreachable by luck rather than by construction, and every mocked
1309
+ test handed the builder a path and so asserted the assumption. A LIVE
1310
+ test found it. An argv builder that is correct only when someone else
1311
+ ran first is the coupling EP6 is about.
1312
+ """
1313
+ probe = _ssh_probe
1314
+ if probe is not None and probe.known_hosts:
1315
+ return probe.known_hosts
1316
+ if _ssh_known_hosts_path:
1317
+ return _ssh_known_hosts_path
1318
+ pinned = (config.SSH_HOST_KEY or "").strip()
1319
+ if not pinned:
1320
+ return ""
1321
+ try:
1322
+ return _write_known_hosts(pinned)
1323
+ except OSError:
1324
+ return ""
1325
+
1326
+
1327
+ def _ssh_argv(command: str, *,
1328
+ session_timeout_s: Optional[int] = None,
1329
+ as_root: bool = False) -> list[str]:
1330
+ """The argv that runs *command* on the configured host.
1331
+
1332
+ `_wsl_argv`'s opposite number. There is no `argv_mode` parameter and
1333
+ that absence is the decision: see `_ssh_remote_script`.
1334
+ """
1335
+ probe = _ssh_probe
1336
+ known = _ssh_known_hosts()
1337
+ workspace = (config.SSH_REMOTE_WORKSPACE or "").strip()
1338
+ binary = (probe.binary if probe is not None and probe.binary
1339
+ else _ssh_binary())
1340
+ return _ssh_connection_argv(binary, ssh_target(), known) + [
1341
+ _ssh_remote_script(command, workspace, session_timeout_s, as_root)]
1342
+
1343
+
1344
+ # ---------------------------------------------------------------------------
1345
+ # ---- Root commands (ROADMAP_v3 §49, slice 5b, SS65-SS72) -------------------
1346
+ # ---------------------------------------------------------------------------
1347
+
1348
+ # An ABSOLUTE path, not a PATH lookup: `sudo` is the one binary on these
1349
+ # routes whose identity decides whether the password this harness holds
1350
+ # goes to the real thing. Measured present at this path on the distro
1351
+ # (a symlink to /etc/alternatives/sudo) and on the remote. A host without
1352
+ # it is refused by name rather than served by whatever `PATH` answers.
1353
+ _SUDO_BINARY = "/usr/bin/sudo"
1354
+
1355
+ # `-k` invalidates any cached ticket, so ONE approval buys exactly ONE
1356
+ # authentication and a ticket warmed by an approved command cannot quietly
1357
+ # authorise a later one. That is the whole of what it does here, and the
1358
+ # correction matters: it does NOT stop the password line reaching the
1359
+ # command -- see _SUDO_STDIN_GUARD, where that was measured.
1360
+ #
1361
+ # `-S` reads the password from stdin. `-p ""` empties the prompt, measured
1362
+ # to leave a bare "\n" on stderr with sudo-rs and nothing at all with
1363
+ # classic sudo. `--` ends option parsing so a command starting with a dash
1364
+ # is a command.
1365
+ _SUDO_FLAGS = ("-k", "-S", "-p", "", "--")
1366
+
1367
+ # THE GUARD, and the measurement that produced it (SS72).
1368
+ #
1369
+ # `sudo -S` reads stdin only when it actually has to authenticate. When it
1370
+ # does not -- a NOPASSWD rule, or a cached ticket on an implementation that
1371
+ # honours one -- it reads NOTHING, and the password this harness wrote is
1372
+ # then sitting in the pipe as THE COMMAND'S OWN STANDARD INPUT, where a
1373
+ # `cat`, a `tee` or an interactive installer reads it.
1374
+ #
1375
+ # Measured on both implementations, with `-k` and without it:
1376
+ # sudo-rs 0.2.13 (Ubuntu) NOPASSWD -> the command received the password
1377
+ # Sudo 1.9.17p2 (classic) NOPASSWD -> the command received the password
1378
+ # So `-k` is not the control; this is. The inner shell closes its own stdin
1379
+ # before the command runs, which costs nothing real: every one of these
1380
+ # routes gives a command DEVNULL today, so this preserves the contract
1381
+ # rather than changing it.
1382
+ _SUDO_STDIN_GUARD = "exec 0</dev/null; "
1383
+
1384
+ # Per-backend, for the run. A refused password is not retried (SS71).
1385
+ _sudo_rejected: dict = {}
1386
+
1387
+
1388
+ def _sudo_argv() -> list:
1389
+ """`sudo` and its flags. One copy, two argv builders."""
1390
+ return [_SUDO_BINARY, *_SUDO_FLAGS]
1391
+
1392
+
1393
+ def _sudo_secret_name(backend: str) -> str:
1394
+ """Which entry holds the password for this target (SS58).
1395
+
1396
+ The NAME says which machine it unlocks. Built from the configured
1397
+ distro or host rather than from anything the model sent, so a call
1398
+ cannot name someone else's secret.
1399
+ """
1400
+ if backend == BACKEND_WSL:
1401
+ return "wsl.%s.sudo" % (wsl_distro() or "")
1402
+ if backend == BACKEND_SSH:
1403
+ return "ssh.%s.sudo" % ((config.SSH_HOST or "").strip())
1404
+ return ""
1405
+
1406
+
1407
+ def _sudo_secret(backend: str):
1408
+ """The stored password, or None when there is not one to be had.
1409
+
1410
+ None covers all three of "no entry", "the store is locked" and
1411
+ "quarantined this run", because every one of them means the same thing
1412
+ to a caller: this harness has no password to offer. `sudo_refusal` is
1413
+ what tells them apart for a HUMAN.
1414
+
1415
+ The `StoreLocked` handler rather than an `is_unlocked()` check above
1416
+ it, for `_ssh_stored_secrets`' recorded reason: the store can lock
1417
+ BETWEEN a check and a read, and no check can cover that gap.
1418
+ """
1419
+ name = _sudo_secret_name(backend)
1420
+ if not name or _sudo_rejected.get(backend):
1421
+ return None
1422
+ try:
1423
+ return secrets.get(name)
1424
+ except secrets.StoreLocked:
1425
+ return None
1426
+
1427
+
1428
+ def sudo_refusal(backend: str):
1429
+ """Why a root command cannot run on *backend*, or None (SS66/SS68).
1430
+
1431
+ ONE copy, for the same reason `uncontained_refusal` is one: the gate
1432
+ reads it to answer "there is nothing to approve", and `run_sandboxed`
1433
+ and `start_sandboxed` read it to stop the call. Three sites deciding
1434
+ this separately is the drift #157 came from.
1435
+
1436
+ THE CONTAINER IS REFUSED BECAUSE IT IS ALREADY ROOT -- measured, the
1437
+ pinned image runs as uid 0 and ships no `sudo` at all, so offering it
1438
+ would be a control that does nothing and a prompt about a privilege
1439
+ the command already has.
1440
+
1441
+ THE HOST FALLBACK IS REFUSED AND RECORDED rather than assumed: on
1442
+ Windows the host shell is PowerShell and `sudo.exe` elevates through a
1443
+ UAC consent dialog that cannot take a password on stdin at all. That is
1444
+ a different mechanism and a separate measurement, and guessing at it is
1445
+ how a control gets shipped that does not work.
1446
+
1447
+ NO STORED SECRET IS A REFUSAL, not a prompt (SS68). The store's
1448
+ contents are the opt-in for root, which is why there is no
1449
+ `allow_root_commands` key: a second switch over one decision is the
1450
+ ratchet G3 removed.
1451
+ """
1452
+ if backend == BACKEND_WSL or backend == BACKEND_SSH:
1453
+ quarantined = _sudo_rejected.get(backend)
1454
+ if quarantined:
1455
+ return quarantined
1456
+ if _sudo_secret(backend) is None:
1457
+ name = _sudo_secret_name(backend)
1458
+ return (
1459
+ f"This command asked to run as root, and no sudo password "
1460
+ f"is stored for this target. Nothing is asked and nothing "
1461
+ f"runs, because the stored secret is what turns root on at "
1462
+ f"all. Store it with `/secrets set {name}` (or "
1463
+ f"`--secrets set {name}` outside the app) and run the "
1464
+ f"command again. The store must also be unlocked -- "
1465
+ f"`/secrets status` says whether it is.")
1466
+ return None
1467
+ if backend == BACKEND_CONTAINER:
1468
+ return (
1469
+ "This command asked to run as root, and the container is "
1470
+ "refused for that -- not because it is dangerous there but "
1471
+ "because a command in the container ALREADY runs as root, and "
1472
+ "the image ships no `sudo` at all. Drop `needs_root` and the "
1473
+ "same command has the privileges it was asking for. Root on "
1474
+ "the user's own machine is `backend: \"wsl\"`, and on the "
1475
+ "remote `backend: \"ssh\"`.")
1476
+ return (
1477
+ "This command asked to run as root on a backend that cannot "
1478
+ "offer it. Root runs on WSL and over SSH only.")
1479
+
1480
+
1481
+ def _note_sudo_auth_failure(stderr: str, backend: str,
1482
+ used_secret: bool) -> None:
1483
+ """Quarantine a refused sudo password for the run (SS71).
1484
+
1485
+ `_note_ssh_auth_failure`'s shape and its reason. `passwd_tries`
1486
+ defaults to three, and a model that retries a wrong password walks a
1487
+ real account towards `pam_faillock` on the distributions that have it
1488
+ in the auth stack. The harness stops offering the value and says which
1489
+ entry to fix.
1490
+
1491
+ IT DOES NOT LOCK THE STORE. One wrong password must not cost the
1492
+ master passphrase, which is the trade SS63 already made for SSH.
1493
+ """
1494
+ if not used_secret or _sudo_rejected.get(backend):
1495
+ return
1496
+ if "uthentication fail" not in stderr and "incorrect password" not in stderr:
1497
+ return
1498
+ name = _sudo_secret_name(backend)
1499
+ _sudo_rejected[backend] = (
1500
+ f"The stored sudo password for this target was refused. It will "
1501
+ f"not be tried again this run, so a wrong value cannot walk the "
1502
+ f"account towards a lockout. Fix it with `/secrets set {name}` "
1503
+ f"and restart.")
1504
+ logger.warning("sudo: stored password refused on %s; quarantined for "
1505
+ "this run", backend)
1506
+
1507
+
1508
+ def _reset_sudo_quarantine() -> None:
1509
+ """Tests only."""
1510
+ _sudo_rejected.clear()
1511
+
1512
+
1513
+ def _session_auth_check(backend: str, *, used_ssh_secrets: bool,
1514
+ used_sudo_secret: bool):
1515
+ """The `SessionProcess` auth check for a session on *backend*, or None
1516
+ when it offered nothing a refusal could quarantine (TECHNICAL_DEBT 51,
1517
+ batch 160).
1518
+
1519
+ The two matchers are the one-shot routes' own, called with the
1520
+ session's first output where those routes pass stderr. EACH IS GATED ON
1521
+ THE EXIT CODE HERE, which the one-shot routes do not need: their stderr
1522
+ is one command's, while a session's merged stream is everything the
1523
+ remote program printed for as long as it ran, and "Permission denied"
1524
+ is an ordinary thing for a program to print. A refused SSH login ends
1525
+ with 255 -- ssh's own status, the code `_run_ssh_process` already reads
1526
+ as "never got there" -- and a refused sudo password ends the command
1527
+ non-zero before it starts.
1528
+ """
1529
+ if not (used_ssh_secrets or used_sudo_secret):
1530
+ return None
1531
+
1532
+ def check(code: int, first_output: str) -> None:
1533
+ if used_ssh_secrets and code == 255:
1534
+ _note_ssh_auth_failure(first_output, True)
1535
+ if used_sudo_secret and code != 0:
1536
+ _note_sudo_auth_failure(first_output, backend, True)
1537
+
1538
+ return check
1539
+
1540
+
1541
+ def _sudo_password_line(secret, binary: bool = False):
1542
+ """The one line written to a root command's stdin.
1543
+
1544
+ ONE function for both shapes -- a session's streams are binary and a
1545
+ one-shot's are text -- so the two cannot disagree about the encoding or
1546
+ about the trailing newline, which `sudo -S` needs in order to end the
1547
+ line at all. `reveal()` is the single named accessor SS62 leaves open,
1548
+ which is what makes `grep -rn 'reveal()'` the audit.
1549
+ """
1550
+ line = secret.reveal() + b"\n"
1551
+ return line if binary else line.decode("utf-8")
1552
+
1553
+
1554
+ def _feed_sudo_password(proc, secret) -> None:
1555
+ """Hand a SESSION its password and close the pipe behind it.
1556
+
1557
+ A background session's stdin exists for this one line and nothing else,
1558
+ so it is closed immediately: the command behind `sudo` is left with a
1559
+ closed stdin, which is what every other route already gives it, and
1560
+ what `_SUDO_STDIN_GUARD` enforces from the far side as well.
1561
+ """
1562
+ try:
1563
+ proc.stdin.write(_sudo_password_line(secret, binary=True))
1564
+ proc.stdin.flush()
1565
+ except OSError as exc:
1566
+ # Never the password, and never a raise: sudo then reads nothing
1567
+ # and refuses, which the caller sees as the command's own failure
1568
+ # with sudo's message on stderr.
1569
+ logger.warning("sudo: could not write the password to the session: "
1570
+ "%s", exc.__class__.__name__)
1571
+ finally:
1572
+ try:
1573
+ proc.stdin.close()
1574
+ except OSError:
1575
+ pass # the child already closed its end
123
1576
 
124
1577
 
125
1578
  # ---------------------------------------------------------------------------
@@ -156,17 +1609,118 @@ def is_docker_available() -> bool:
156
1609
  # three are now all rejected. So for any command that reaches the inert
157
1610
  # path, `command.split()` and `shlex.split(command)` are provably the
158
1611
  # same list -- a closure, not a patch, and pinned as one by
159
- # `test_the_two_tokenisers_cannot_disagree`.
1612
+ # `TestTheTwoTokenisersCannotDisagree` in tests/test_shell.py.
1613
+ #
1614
+ # Until batch 108 this cited the same words in lower snake case, as
1615
+ # though the pin were a function -- a name that has never existed, while
1616
+ # the real one is the CLASS, cited correctly by `_within` 140 lines below.
1617
+ # It is the failure `protected_paths.user_config_dir` already recorded
1618
+ # about itself: a reader who greps the name finds nothing and concludes
1619
+ # the closure is unguarded. The dead spelling is described rather than
1620
+ # written out here, because `test_docs_consistency.py` now fails on a
1621
+ # cited test name that resolves to nothing, and a correction note is not
1622
+ # a reason to make the guard start its life with an exception.
160
1623
  _SHELL_METACHARACTERS = re.compile(r"""[;|&$`><(){}!#~'"\\]""")
161
1624
 
162
1625
  # Dangerous flags for commands that remain in INERT_COMMANDS.
1626
+ #
1627
+ # BATCH 117 MADE THIS TABLE TRUE, because it was not. The claim beside
1628
+ # `writes=False` in `classify_command` is that this table "guards the
1629
+ # entries that have a writing mode", and three things were wrong with that:
1630
+ #
1631
+ # * `diff` was the ONLY key that is actually in INERT_COMMANDS, and its
1632
+ # value was an empty frozenset -- `if dangerous:` is falsy for one, so
1633
+ # the consumer skipped it. `find` and `sort` are not on the inert list.
1634
+ # The whole table therefore guarded nothing, while reading as though it
1635
+ # guarded three commands.
1636
+ # * `tree -o FILE` and `date -s TIME` are inert and write. Added below.
1637
+ # * `uniq IN OUT` writes through a POSITIONAL argument, which a table of
1638
+ # FLAGS structurally cannot express. It was dropped from
1639
+ # `config.INERT_COMMANDS` instead -- see the note there. Teaching this
1640
+ # table about positional arguments would make it the shell parser
1641
+ # `_escapes_workspace` explains it must never become (G2).
1642
+ #
1643
+ # `find` and `sort` stay as written: they are defence-in-depth for a future
1644
+ # re-addition, which is what the entries were always for, and keeping them
1645
+ # costs a dict lookup that already happens.
1646
+ #
1647
+ # WHAT THIS IS NOT. `_escapes_workspace` reads every token after the first
1648
+ # as a path, so a write aimed OUTSIDE the workspace is refused there
1649
+ # regardless of this table -- measured: `uniq in.txt /etc/passwd` is caught.
1650
+ # What the table decides is whether an in-workspace write is reported as
1651
+ # `writes=False`, and the workspace is writable by design. So this is about
1652
+ # the profile telling the truth, not about an escape.
163
1653
  # Even though find/sort were removed, this denylist provides
164
1654
  # defense-in-depth for any future additions.
165
1655
  _DANGEROUS_FLAGS: dict[str, frozenset[str]] = {
166
1656
  "find": frozenset({"-delete", "-exec", "-execdir", "-ok", "-okdir", "-fprint", "-fprint0", "-fprintf"}),
167
1657
  "sort": frozenset({"-o", "--output"}),
168
- "diff": frozenset(), # diff is read-only, no dangerous flags
1658
+ # Inert AND able to write, which is the combination that matters:
1659
+ "tree": frozenset({"-o"}),
1660
+ "date": frozenset({"-s", "--set"}),
169
1661
  }
1662
+ # `diff` had an entry of its own here (an empty frozenset) until batch 117.
1663
+ # It needs no guard -- diff has no writing mode -- and an empty set reads
1664
+ # as coverage while providing none, which is exactly how the table came to
1665
+ # look populated while doing nothing.
1666
+
1667
+
1668
+ def _names_dangerous_flag(token: str, dangerous: frozenset) -> bool:
1669
+ """True when *token* is one of *dangerous*, in any spelling the
1670
+ tabled tool's own parser accepts (batch 142).
1671
+
1672
+ Batch 117 made the table true for the spellings it enumerated.
1673
+ The residual was that the PARSER accepts a small language and the
1674
+ table listed three points in it. GNU `date` and `tree` both parse
1675
+ with `getopt_long`, where a short option with a required argument
1676
+ takes it ATTACHED and an unambiguous long-option prefix resolves,
1677
+ so these all reached `tier=INERT, writes=False` and ran with no
1678
+ prompt while the space-separated spelling asked:
1679
+
1680
+ date -s2024-01-01 tree -oout.txt
1681
+ date --s 2024-01-01 date --se=2024-01-01
1682
+
1683
+ THE DIRECTION IS DELIBERATE. A false positive costs a PROMPT and
1684
+ a false negative costs the prompt the tier requires, so this errs
1685
+ toward asking -- which is also why it stays this side of parsing.
1686
+ It reads a token's shape; it does not learn what a flag MEANS,
1687
+ and G2 is why (teaching the classifier which positions are
1688
+ outputs is what got `uniq` removed rather than tabled).
1689
+
1690
+ Four rules, in the order a parser would apply them:
1691
+
1692
+ 1. the whole token, and its head before the first `=` (117).
1693
+ 2. a long option ABBREVIATED: `--s` and `--se` are prefixes of
1694
+ `--set` and resolve to it. Any prefix counts, not only an
1695
+ unambiguous one -- deciding ambiguity needs the tool's whole
1696
+ option list, which is the parsing this must not do.
1697
+ 3. a short option with its argument ATTACHED: `-oFILE`, where
1698
+ the token's first letter is the flag and the rest is the
1699
+ value. Recognised by the token carrying a non-letter.
1700
+ 4. a BUNDLE of short options, `-ao`: purely alphabetic after
1701
+ the dash, so any dangerous letter in it is a flag rather
1702
+ than part of a value. `tree -Pfoo` is flagged by this rule
1703
+ and that is the accepted cost of rule 3's limit: a prompt.
1704
+ """
1705
+ head = token.split("=", 1)[0]
1706
+ if token in dangerous or head in dangerous:
1707
+ return True
1708
+ if head.startswith("--"):
1709
+ # Rule 2. `len(head) > 2` keeps a bare `--` (the end-of-options
1710
+ # marker) from matching every long flag in the set.
1711
+ return len(head) > 2 and any(
1712
+ flag.startswith(head)
1713
+ for flag in dangerous if flag.startswith("--"))
1714
+ if not head.startswith("-") or len(head) < 2:
1715
+ return False
1716
+ shorts = {flag[1] for flag in dangerous
1717
+ if len(flag) == 2 and not flag.startswith("--")}
1718
+ if not shorts:
1719
+ return False
1720
+ letters = head[1:]
1721
+ if letters.isalpha():
1722
+ return bool(shorts.intersection(letters)) # rule 4
1723
+ return letters[0] in shorts # rule 3
170
1724
 
171
1725
 
172
1726
  def _is_inert(command: str) -> bool:
@@ -203,9 +1757,16 @@ def _is_inert(command: str) -> bool:
203
1757
  # Check for dangerous flags on specific commands
204
1758
  dangerous = _DANGEROUS_FLAGS.get(first_word)
205
1759
  if dangerous:
206
- tokens = stripped.split()
207
- if any(t in dangerous for t in tokens):
208
- return False
1760
+ # THE SPELLING FAMILY, NOT A LIST OF SPELLINGS. Batch 117 added
1761
+ # the `=` head because `sort --output=/tmp/x` is one token equal
1762
+ # to neither "-o" nor "--output"; batch 142 added the
1763
+ # other two shapes the same parsers accept, an attached short
1764
+ # argument and an abbreviated long option. The rules and the
1765
+ # reason the direction errs toward asking are in
1766
+ # `_names_dangerous_flag`.
1767
+ for token in stripped.split():
1768
+ if _names_dangerous_flag(token, dangerous):
1769
+ return False
209
1770
  return True
210
1771
 
211
1772
 
@@ -251,8 +1812,30 @@ def _needs_network(command: str, first_word_only: bool) -> bool:
251
1812
  if first_word_only:
252
1813
  tokens = tokens[:1]
253
1814
  allowed = set(config.NETWORK_ALLOWED_COMMANDS)
254
- # Strip path components for matching (e.g. /usr/bin/pip → pip)
255
- return any(os.path.basename(token) in allowed for token in tokens)
1815
+ return any(_network_name(token) in allowed for token in tokens)
1816
+
1817
+
1818
+ def _network_name(token: str) -> str:
1819
+ """A token reduced to the name NETWORK_ALLOWED_COMMANDS is written in.
1820
+
1821
+ Strips the path (`/usr/bin/pip` -> `pip`), then lowercases and drops a
1822
+ `.exe`, because the list is fourteen lowercase bare names and Windows
1823
+ spells several of them otherwise. Batch 117: `curl.exe` matched nothing,
1824
+ so the same program got network on one platform and `--network none` on
1825
+ the other.
1826
+
1827
+ THE OLD BEHAVIOUR FAILED CLOSED, which is why this was a usability
1828
+ defect and not a hole: an unmatched command runs without egress. But it
1829
+ is not harmless either. `network` has two consumers, and
1830
+ `not profile.network` is a CONDITION FOR SKIPPING APPROVAL in
1831
+ `tools/builtin/shell.py` -- so `curl.exe` was both denied the network it
1832
+ needed and eligible for a shortcut that `curl` is not. Matching it makes
1833
+ one program one answer.
1834
+ """
1835
+ name = os.path.basename(token).lower()
1836
+ if name.endswith(".exe"):
1837
+ name = name[:-len(".exe")]
1838
+ return name
256
1839
 
257
1840
 
258
1841
  # ---------------------------------------------------------------------------
@@ -296,13 +1879,61 @@ def _within(root: str, token: str) -> bool:
296
1879
  generative corpus in TestTheTwoTokenisersCannotDisagree, which is what
297
1880
  a generative corpus is for -- no enumerated list of spellings anyone
298
1881
  would write was going to contain `\\;`.
1882
+
1883
+ SS45 extends that same sentence from a path this cannot resolve to a
1884
+ LINK this platform cannot follow, which the text of a token can never
1885
+ reveal. See `_unfollowable_link`.
299
1886
  """
300
1887
  try:
301
1888
  root = os.path.realpath(root)
302
1889
  resolved = os.path.realpath(os.path.join(root, token))
303
1890
  except (OSError, ValueError):
304
1891
  return False
305
- return resolved == root or resolved.startswith(root + os.sep)
1892
+ if not (resolved == root or resolved.startswith(root + os.sep)):
1893
+ return False
1894
+ return not _unfollowable_link(root, resolved)
1895
+
1896
+
1897
+ def _unfollowable_link(root: str, resolved: str) -> bool:
1898
+ """Whether a component of *resolved* below *root* is a link THIS
1899
+ platform cannot follow but another one can (ROADMAP_v3 §49, SS45).
1900
+
1901
+ The hole, measured in batch 101. A symlink created inside the workspace
1902
+ from WSL is stored on an NTFS drive as an LX reparse point
1903
+ (`0xa000001d`), and Windows does not understand it: `os.path.exists` is
1904
+ False, `os.path.islink` is False, and `os.path.realpath` returns the
1905
+ path UNCHANGED rather than following it or raising. So `_within`
1906
+ answered True for a name that reads `/etc/passwd` in the distro --
1907
+ `cat escape` classified INERT, was AUTO-APPROVED, and returned the
1908
+ host's real password file. No amount of analysis of the token's TEXT
1909
+ can see that, because the token is `escape`.
1910
+
1911
+ The rule is the platform's own admission rather than a list of tags:
1912
+ a component that `lexists` and does not `exist` is one whose lstat
1913
+ succeeded and whose stat did not, which for a path means exactly a link
1914
+ that could not be followed. It is deliberately NOT "is a reparse
1915
+ point", because a OneDrive placeholder is a reparse point whose path
1916
+ means precisely what it says, and blocking those would make every
1917
+ INERT command in a synced workspace ask.
1918
+
1919
+ Cheap where it matters: only components BELOW the root are walked, and
1920
+ only after the resolved path has already been found to be inside it, so
1921
+ a token heading somewhere else has returned before this is called.
1922
+
1923
+ On POSIX the case this closes cannot arise -- `realpath` follows a
1924
+ symlink there, so a link out of the workspace has already resolved out
1925
+ of it -- and what remains is a dangling link, where answering "ask"
1926
+ costs a prompt on a command that was going to fail anyway.
1927
+ """
1928
+ rest = resolved[len(root):].strip("\\/")
1929
+ if not rest:
1930
+ return False
1931
+ path = root
1932
+ for part in re.split(r"[\\/]", rest):
1933
+ path = os.path.join(path, part)
1934
+ if os.path.lexists(path) and not os.path.exists(path):
1935
+ return True
1936
+ return False
306
1937
 
307
1938
 
308
1939
  def _escapes_workspace(command: str, workspace_dir: str) -> bool:
@@ -326,12 +1957,32 @@ def _escapes_workspace(command: str, workspace_dir: str) -> bool:
326
1957
  with it. Refusing to parse is only sound while nothing downstream
327
1958
  parses either.
328
1959
 
329
- The `=` clause is the one place a token needs splitting: `--file=/etc/x`
330
- is inside the workspace read whole (there is no such file, but the
331
- join stays under the root) while the path it actually names is not.
332
- Splitting on the first `=` and checking the tail costs nothing and
333
- closes it. Everything else -- absolute paths, `..` escapes, drive
334
- letters, UNC paths -- is caught by reading the token as it stands.
1960
+ TWO PLACES A TOKEN NEEDS SPLITTING, and they are the same place
1961
+ twice -- a path carried inside a flag token rather than beside it.
1962
+
1963
+ `--file=/etc/x` is inside the workspace read whole (there is no
1964
+ such file, but the join stays under the root) while the path it
1965
+ actually names is not. Splitting on the first `=` closes it.
1966
+
1967
+ `-f/etc/x` is the identical shape in the spelling `getopt` calls
1968
+ an attached argument, and it was open until batch 142. MEASURED
1969
+ (batch 142): `tree -o /etc/passwd` escaped and `tree -o/etc/passwd`
1970
+ did not, because a token that does not START with `/` reads as
1971
+ relative and lands under the root. `grep -f FILE` and
1972
+ `file -f FILE` are INERT commands whose short option takes a
1973
+ file, so that was an auto-approved read of a host file -- and
1974
+ `file -f` echoes each unopenable line back, which is the
1975
+ content. So anything after a leading `-x` is checked too.
1976
+
1977
+ THIS IS STILL NOT PARSING. Neither clause asks what a flag MEANS
1978
+ or which one takes an argument; both read a token's shape and hand
1979
+ the tail to the same `_within`. A token like `-la` or `-n5` offers
1980
+ `a` and `5`, which are relative and land inside the workspace --
1981
+ passing for the reason the whole function passes flags, not because
1982
+ anything recognised them.
1983
+
1984
+ Everything else -- absolute paths, `..` escapes, drive letters, UNC
1985
+ paths -- is caught by reading the token as it stands.
335
1986
 
336
1987
  False positives are the designed error direction: `grep /etc/passwd
337
1988
  notes.txt` searches for a STRING that looks like a path, and it will
@@ -341,12 +1992,93 @@ def _escapes_workspace(command: str, workspace_dir: str) -> bool:
341
1992
  for token in command.split()[1:]:
342
1993
  if not _within(workspace_dir, token):
343
1994
  return True
344
- if "=" in token and not _within(workspace_dir, token.split("=", 1)[1]):
1995
+ if "=" in token and not _within(workspace_dir,
1996
+ token.split("=", 1)[1]):
1997
+ return True
1998
+ if (token.startswith("-") and len(token) > 2
1999
+ and not _within(workspace_dir, token[2:])):
345
2000
  return True
346
2001
  return False
347
2002
 
348
2003
 
349
- def classify_command(command: str, workspace_dir: str) -> CommandProfile:
2004
+ def declared_network(params) -> bool:
2005
+ """Whether a tool call DECLARED that it needs the network (§50, NW1).
2006
+
2007
+ THE coercion, and the reason it is a function rather than a `.get()`
2008
+ at each site. The gate runs before Pydantic validates -- `params` is
2009
+ the model's tool-call input verbatim -- so this value can be a string,
2010
+ a number, or absent. If the gate and the runner coerced it
2011
+ differently, one would ask about a networked command and the other
2012
+ would run a non-networked one, which is #157's shape exactly, in the
2013
+ module written to close it.
2014
+
2015
+ Only literal `True` is true, because the flag can only ADD egress
2016
+ (NW2): a lenient coercion would let `"false"` or `0` grant network
2017
+ that nobody asked about. A model that sends `"true"` is refused by
2018
+ `StrictBool` at run time with an error naming the field, and nothing
2019
+ executes -- so the two paths never disagree about what ran.
2020
+ """
2021
+ return isinstance(params, dict) and params.get("requires_network") is True
2022
+
2023
+
2024
+ def declared_backend(params) -> str:
2025
+ """Which backend a tool call ASKED for (ROADMAP_v3 §49, SS35).
2026
+
2027
+ `declared_network`'s sibling, and a function for the same reason: the
2028
+ gate reads the model's tool-call input BEFORE Pydantic has seen it, so
2029
+ this value can be any JSON at all, and a gate and a runner that coerced
2030
+ it differently would ask about a contained command and run an
2031
+ uncontained one -- #157's shape, in the module written to close it.
2032
+
2033
+ ONLY an exact string selects a backend other than the container --
2034
+ `"wsl"` or `"ssh"`. Everything else -- a misspelling, a list, `True`,
2035
+ absent -- is the container, which is the safe direction: the failure
2036
+ mode of a lenient reading is a command running outside the sandbox
2037
+ because the model typed `"WSL "`, and the failure mode of a strict one
2038
+ is a refusal the model can see and fix.
2039
+ `Literal["container", "wsl", "ssh"]` on the param model then refuses
2040
+ anything else at run time, so nothing executes on a disagreement.
2041
+
2042
+ Membership in a tuple would read better and is deliberately NOT used:
2043
+ the container has to remain the answer for every unrecognised value,
2044
+ and `value if value in BACKENDS else BACKEND_CONTAINER` says that in a
2045
+ way that a later edit widening BACKENDS would silently change.
2046
+ """
2047
+ if not isinstance(params, dict):
2048
+ return BACKEND_CONTAINER
2049
+ asked = params.get("backend")
2050
+ if asked == BACKEND_WSL:
2051
+ return BACKEND_WSL
2052
+ if asked == BACKEND_SSH:
2053
+ return BACKEND_SSH
2054
+ return BACKEND_CONTAINER
2055
+
2056
+
2057
+ def declared_root(params) -> bool:
2058
+ """Whether a tool call DECLARED that it needs root (ROADMAP_v3 §49,
2059
+ slice 5b, SS67).
2060
+
2061
+ `declared_network`'s sibling, coerced here for its reason exactly: the
2062
+ gate reads the model's tool-call input BEFORE Pydantic has seen it, so
2063
+ this value can be any JSON at all, and a gate and a runner that coerced
2064
+ it differently would ask about an unprivileged command and run a
2065
+ privileged one -- #157's shape, in the module written to close it.
2066
+
2067
+ Only literal `True`, like `declared_network` and for the same reason in
2068
+ the same direction: a model that sends `"true"` is refused by
2069
+ `StrictBool` at run time with an error naming the field, and NOTHING
2070
+ EXECUTES -- so the two paths never disagree about what ran. A lenient
2071
+ coercion would be the one that could run `sudo` off a string.
2072
+
2073
+ It is NOT the whole root question. `_shell_approval_check` ORs this
2074
+ with a literal `sudo` token in the command text, because a model that
2075
+ simply types `sudo` never sets the flag -- see SS67.
2076
+ """
2077
+ return isinstance(params, dict) and params.get("needs_root") is True
2078
+
2079
+
2080
+ def classify_command(command: str, workspace_dir: str,
2081
+ requires_network: bool = False) -> CommandProfile:
350
2082
  """Measure *command* into a capability set (ROADMAP_v2 §28, G1).
351
2083
 
352
2084
  One classification, two consumers: `_shell_approval_check` reads it to
@@ -354,6 +2086,14 @@ def classify_command(command: str, workspace_dir: str) -> CommandProfile:
354
2086
  decide how to run it. Before §28 those two asked `_is_inert`
355
2087
  separately and never compared answers, which is how a command could be
356
2088
  auto-approved as harmless and then executed on the host (#157).
2089
+
2090
+ *requires_network* is the agent's declaration (§50, NW1), already
2091
+ coerced by `declared_network`. It is OR'd into the network fact and
2092
+ can only ADD egress (NW2) -- a model cannot clear it on `curl` to
2093
+ dodge a prompt, and the single fact keeps its two consumers reading
2094
+ the same value. Nothing new gates it (NW3): a true `network` makes
2095
+ the tier `SANDBOXED_NET`, which `auto_approved` already refuses to
2096
+ cover under `tiered` and `contained` alike.
357
2097
  """
358
2098
  # Totality is a REQUIREMENT here, not defensiveness. This runs inside
359
2099
  # registry.approval_needed(), which is handed the model's tool-call
@@ -367,44 +2107,64 @@ def classify_command(command: str, workspace_dir: str) -> CommandProfile:
367
2107
  #
368
2108
  # UNKNOWN rather than a raise: the gate's job is to answer, and
369
2109
  # `measured=False` already means nobody may skip the human.
2110
+ #
2111
+ # The declaration is OR'd in here too, on a profile the classifier
2112
+ # could not characterise. NW2 says the flag can only ADD egress, with
2113
+ # no exception -- and an exception here would be one more rule to
2114
+ # remember for two profiles that always ask a human anyway.
2115
+ declared = bool(requires_network)
370
2116
  if not isinstance(command, str):
371
2117
  return CommandProfile(
372
2118
  tier=UNKNOWN, measured=False, escapes_workspace=True,
373
- writes=True, network=False,
2119
+ writes=True, runs_code=True, network=declared,
374
2120
  reason=f"command is {type(command).__name__}, not a string")
375
2121
 
376
2122
  stripped = command.strip()
377
2123
  if not stripped:
378
2124
  return CommandProfile(
379
2125
  tier=UNKNOWN, measured=False, escapes_workspace=True,
380
- writes=True, network=False, reason="empty command")
2126
+ writes=True, runs_code=True, network=declared,
2127
+ reason="empty command")
381
2128
 
382
2129
  # Order matters, and only for Q2: `_needs_network` reads every command
383
2130
  # position of a compound command and the FIRST WORD ONLY of an inert
384
2131
  # one, and `_is_inert` is what tells those apart. One call, read twice
385
2132
  # -- not two calls, which is the shape #157 came from.
386
2133
  inert = _is_inert(stripped)
387
- network = _needs_network(stripped, first_word_only=inert)
2134
+ detected = _needs_network(stripped, first_word_only=inert)
2135
+ network = detected or declared
2136
+ # §50's gap register: the prompt should say egress was REQUESTED, not
2137
+ # merely that the tier needs it -- so the reason distinguishes the two
2138
+ # ways the fact became true. Only when the detector did NOT already
2139
+ # recognise the command: when both are true there is one fact and one
2140
+ # sentence, which is what that register's open question settled on.
2141
+ asked_for = ", and the call declared it needs the network" \
2142
+ if declared and not detected else ""
388
2143
 
389
2144
  if inert:
390
2145
  # INERT_COMMANDS is a read-only list and _DANGEROUS_FLAGS guards
391
2146
  # the entries that have a writing mode, so writes=False here is a
392
2147
  # claim about the COMMAND. It says nothing about the arguments,
393
2148
  # which is what the next line is for.
2149
+ #
2150
+ # runs_code=False is the same kind of claim (§48, CE7): nothing on
2151
+ # the list executes its arguments or a file, and an inert command
2152
+ # carries no metacharacters, so there is no second command position
2153
+ # for code to arrive through.
394
2154
  if _escapes_workspace(stripped, workspace_dir):
395
2155
  return CommandProfile(
396
2156
  tier=HOST_READ, measured=True, escapes_workspace=True,
397
- writes=False,
2157
+ writes=False, runs_code=False,
398
2158
  network=network,
399
2159
  reason=(f"reads {stripped.split()[0]!r} with an argument "
400
2160
  f"outside the workspace, which no container "
401
- f"can see"))
2161
+ f"can see" + asked_for))
402
2162
  return CommandProfile(
403
2163
  tier=INERT, measured=True, escapes_workspace=False,
404
- writes=False,
2164
+ writes=False, runs_code=False,
405
2165
  network=network,
406
2166
  reason=(f"read-only {stripped.split()[0]!r}, every argument "
407
- f"inside the workspace"))
2167
+ f"inside the workspace" + asked_for))
408
2168
 
409
2169
  tier = SANDBOXED_NET if network else SANDBOXED
410
2170
  return CommandProfile(
@@ -415,13 +2175,22 @@ def classify_command(command: str, workspace_dir: str) -> CommandProfile:
415
2175
  # rather than assumed True so the record says something real.
416
2176
  escapes_workspace=_escapes_workspace(stripped, workspace_dir),
417
2177
  writes=True,
2178
+ # §48 (CE1). NOT a list of interpreters, and it must not become
2179
+ # one: `python -c` is the obvious case, but `pytest` runs a
2180
+ # conftest.py, `make` runs a Makefile, and `"python"`, `pyth?n`,
2181
+ # `python3.13` and `echo x | python` are all the same call to a
2182
+ # shell. Everything that is not INERT may run code, which is the
2183
+ # only answer this classifier can give without parsing (G2).
2184
+ runs_code=True,
418
2185
  network=network,
419
- reason=("needs network and a sandbox" if network
420
- else "not a read-only command, so it needs a sandbox"))
2186
+ reason=("can run code, and needs network and a sandbox" if detected
2187
+ else "not a read-only command -- it can run code, so it "
2188
+ "runs in a sandbox" + asked_for))
421
2189
 
422
2190
 
423
2191
  def containment_for(
424
2192
  profile: CommandProfile, docker_available: bool,
2193
+ backend: str = BACKEND_CONTAINER,
425
2194
  ) -> str:
426
2195
  """Which containment the backend that will actually run *profile*
427
2196
  provides -- the second half of what the gate needs.
@@ -458,7 +2227,18 @@ def containment_for(
458
2227
  put subprocess IO inside a predicate, and it would move the probe out
459
2228
  from under the callers that pre-compute it for the TOCTOU thread --
460
2229
  the same reason run_sandboxed takes it instead of asking.
2230
+
2231
+ *backend* is what the CALL asked for (SS35). WSL is UNCONTAINED for
2232
+ every tier (SS1) and is answered FIRST, above HOST_READ and above the
2233
+ runtime: a call that asked for WSL is never described by the
2234
+ containment of a backend it did not ask for. When it cannot have WSL
2235
+ the answer is UNAVAILABLE, never another backend's containment -- SS37,
2236
+ and the same shape `_route` uses one function down.
461
2237
  """
2238
+ if backend == BACKEND_WSL:
2239
+ return UNCONTAINED if wsl_available() else UNAVAILABLE
2240
+ if backend == BACKEND_SSH:
2241
+ return UNCONTAINED if ssh_available() else UNAVAILABLE
462
2242
  if profile.tier == HOST_READ:
463
2243
  return UNCONTAINED
464
2244
  if docker_available:
@@ -477,7 +2257,28 @@ def containment_for(
477
2257
  _SAFE_ENV_KEYS = frozenset({
478
2258
  "PATH", "HOME", "USERPROFILE", "SYSTEMROOT", "TEMP", "TMP",
479
2259
  "LANG", "LC_ALL", "TERM", "SHELL", "COMSPEC", "WINDIR",
2260
+ "PATHEXT",
480
2261
  })
2262
+ # WHY `PATHEXT`, and why this was found by running rather than by reading:
2263
+ # without it, `powershell -c "& 'prog' args"` STARTS the external program and
2264
+ # returns immediately instead of waiting for it. Measured on the fallback
2265
+ # route against a program that appends a line a second for five seconds and
2266
+ # exits non-zero: 0.37s, `return_code=0`, empty stdout, and ZERO lines
2267
+ # written by the time `run_sandboxed` returned -- with the work still running
2268
+ # six seconds later. With `PATHEXT` restored and nothing else changed: 5.26s,
2269
+ # the real exit code, the real output, all five lines done. So the model was
2270
+ # being told every build, install and test suite on this route had succeeded
2271
+ # and produced nothing, while it was only just starting; and because the
2272
+ # shell was gone before it, `SANDBOX_TIMEOUT_SECONDS` bounded nothing and a
2273
+ # session's `kill()` short-circuited on an already-exited shell.
2274
+ #
2275
+ # PATHEXT names extensions, not paths, so it leaks nothing this allowlist is
2276
+ # protecting -- and it is needed by the SHELL this harness chose, not by the
2277
+ # command. The other 64 names `_scrubbed_env()` drops were each restored one
2278
+ # at a time against the same program and none of them changes the answer, so
2279
+ # this is the one addition the measurement supports. PowerShell BUILTINS
2280
+ # (`Start-Sleep`, `Write-Output`) run in-process and are unaffected, which is
2281
+ # why a probe written with those alone sees nothing wrong.
481
2282
 
482
2283
 
483
2284
  def _scrubbed_env() -> dict:
@@ -496,8 +2297,25 @@ def _scrubbed_env() -> dict:
496
2297
  # ---------------------------------------------------------------------------
497
2298
 
498
2299
 
499
- def _run_inert(
500
- command: str,
2300
+ def _inert_argv(command: str) -> list[str]:
2301
+ """The argv a host-side inert command executes -- one copy, for the
2302
+ one-shot light path and for a background session on the host
2303
+ (ROADMAP_v3 §49).
2304
+
2305
+ ONE copy because this tokenisation is load-bearing: `_is_inert` rejects
2306
+ every character shlex consumes, which is what makes `command.split()`
2307
+ and this list provably the same (Q1/Q5). Two copies of the rule would be
2308
+ two tokenisers free to drift, and the gap between two of them is where
2309
+ #157 arrived, twice.
2310
+ """
2311
+ try:
2312
+ return shlex.split(command, posix=(platform.system() != "Windows"))
2313
+ except ValueError:
2314
+ return command.split()
2315
+
2316
+
2317
+ def _run_inert(
2318
+ command: str,
501
2319
  workspace_dir: str,
502
2320
  _shell_binary: str = "",
503
2321
  ) -> dict:
@@ -507,10 +2325,7 @@ def _run_inert(
507
2325
  _shell_binary is accepted for signature compatibility with the
508
2326
  other backends but is not used (inert commands don't need a shell).
509
2327
  """
510
- try:
511
- args = shlex.split(command, posix=(platform.system() != "Windows"))
512
- except ValueError:
513
- args = command.split()
2328
+ args = _inert_argv(command)
514
2329
 
515
2330
  try:
516
2331
  result = subprocess.run(
@@ -518,9 +2333,15 @@ def _run_inert(
518
2333
  cwd=workspace_dir,
519
2334
  env=_scrubbed_env(),
520
2335
  capture_output=True,
2336
+ # DEVNULL rather than INHERITED (#203, batch 213), as the
2337
+ # fallback has had since batch 142: a bare `cat` is INERT and
2338
+ # auto-approved, and with the console as its stdin it read
2339
+ # the user's type-ahead -- a second reader beside the shell's
2340
+ # own (N1) -- or sat until the timeout waiting for an EOF.
2341
+ stdin=subprocess.DEVNULL,
521
2342
  text=True,
522
2343
  timeout=config.SANDBOX_TIMEOUT_SECONDS,
523
- shell=False,
2344
+ shell=False, # nosec B603 - EXECUTION ROUTE: carries the model's command by design. List form and no shell, so there is nothing to inject into; the bound is upstream -- mode gate G3, the INERT allowlist, the dangerous-flag check and the approval prompt -- not this call (ROUTE_INERT_HOST)
524
2345
  )
525
2346
  except subprocess.TimeoutExpired:
526
2347
  return {
@@ -554,8 +2375,8 @@ def _run_inert(
554
2375
 
555
2376
 
556
2377
  @functools.lru_cache(maxsize=8)
557
- def _resolved_image_id(image: str) -> str:
558
- """The image ID `docker run` will actually use for *image*, or "".
2378
+ def _resolved_image_id(image: str, runtime: str = DOCKER) -> str:
2379
+ """The image ID `<runtime> run` will actually use for *image*, or "".
559
2380
 
560
2381
  §46 (EP7). `SANDBOX_DOCKER_IMAGE` is a TAG, and a tag is not an
561
2382
  identity: anything on the machine may `docker build -t
@@ -565,18 +2386,22 @@ def _resolved_image_id(image: str) -> str:
565
2386
  command reported a filesystem nobody recognised -- it was not what
566
2387
  happened that time, and it is still worth being able to see.
567
2388
 
2389
+ Two runtimes make the point twice (ROADMAP_v3 §49): Docker and
2390
+ Podman keep separate image stores, and measured, the same tag pulled
2391
+ by each a week apart resolved to two different IDs.
2392
+
568
2393
  LOGGED, NOT ENFORCED. Pinning by digest is a separate decision with
569
2394
  a maintenance cost (somebody has to bump it), while a line in
570
2395
  app.log naming the ID costs one cached subprocess per process and
571
2396
  turns a silent substitution into a visible one.
572
2397
 
573
- Failure is not an error here: the image ID is diagnostic, and a
574
- `docker image inspect` that fails must not stop a run that Docker
2398
+ Failure is not an error here: the image ID is diagnostic, and an
2399
+ `image inspect` that fails must not stop a run that the runtime
575
2400
  itself is about to accept.
576
2401
  """
577
2402
  try:
578
- result = subprocess.run(
579
- ["docker", "image", "inspect", "--format", "{{.Id}}", image],
2403
+ result = subprocess.run( # nosec B603 - `image inspect`; runtime and image both come from config, list form
2404
+ [runtime, "image", "inspect", "--format", "{{.Id}}", image],
580
2405
  capture_output=True, text=True, timeout=10,
581
2406
  )
582
2407
  except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
@@ -584,21 +2409,23 @@ def _resolved_image_id(image: str) -> str:
584
2409
  return result.stdout.strip() if result.returncode == 0 else ""
585
2410
 
586
2411
 
587
- def _log_image_identity() -> None:
588
- """Say once per process which image the sandbox resolves to (EP7)."""
2412
+ def _log_image_identity(runtime: str = DOCKER) -> None:
2413
+ """Say once per process which image the sandbox resolves to, and under
2414
+ which runtime (EP7)."""
589
2415
  image = config.SANDBOX_DOCKER_IMAGE
590
- resolved = _resolved_image_id(image)
2416
+ resolved = _resolved_image_id(image, runtime)
591
2417
  if _log_image_identity._said:
592
2418
  return
593
2419
  _log_image_identity._said = True
594
- logger.info("Sandbox image %s resolves to %s", image,
595
- resolved or "an id docker would not report")
2420
+ logger.info("Sandbox image %s resolves to %s under %s", image,
2421
+ resolved or "an id the runtime would not report", runtime)
596
2422
 
597
2423
 
598
2424
  _log_image_identity._said = False
599
2425
 
600
2426
 
601
- def _annotate(result: dict, profile: CommandProfile, ran_on: str) -> dict:
2427
+ def _annotate(result: dict, profile: CommandProfile, ran_on: str,
2428
+ as_root: bool = False) -> dict:
602
2429
  """Record WHERE a command ran, in the result the model reads (§46, EP4).
603
2430
 
604
2431
  The gate has always told the HUMAN this -- `_shell_approval_notice`
@@ -632,6 +2459,11 @@ def _annotate(result: dict, profile: CommandProfile, ran_on: str) -> dict:
632
2459
  return result
633
2460
  result["ran_on"] = ran_on
634
2461
  result["tier"] = profile.tier
2462
+ # Slice 5b, and on the same argument as `ran_on` itself: a model that
2463
+ # cannot see it ran as root will describe what it did as though it did
2464
+ # not. Present only when true, so no unprivileged result changes shape.
2465
+ if as_root:
2466
+ result["as_root"] = True
635
2467
  return result
636
2468
 
637
2469
 
@@ -684,17 +2516,87 @@ def _venastine_readonly_mount(workspace_real: str) -> list[str]:
684
2516
  return ["-v", f"{venastine}:/workspace/.venastine:ro"]
685
2517
 
686
2518
 
687
- def _run_docker(
2519
+ # The command an interactive session's container runs (ROADMAP_v3 §49, slice
2520
+ # 2). Every part of it was measured through this builder before it was
2521
+ # written (batch 100), and each clause is here for a reason that was OBSERVED:
2522
+ #
2523
+ # script -qfec makes the pty INSIDE the container, so the client
2524
+ # never needs a real terminal and `docker run -t`'s
2525
+ # CR mangling never happens. `-e` returns the shell's
2526
+ # own exit code (measured: `exit 3` gives 3), `-f`
2527
+ # flushes so output arrives as it is written, `-q`
2528
+ # drops the transcript header.
2529
+ # stty -echo SS33. The pty is 0x0, so readline echoes a
2530
+ # 200-character command back as `\r<xxxx` -- its
2531
+ # horizontal-scroll marker -- which no honest rule
2532
+ # could strip. With the echo off there is nothing to
2533
+ # strip at any length.
2534
+ # rows 50 cols 1000 belt and braces for a program that turns echo back
2535
+ # on: then the mangling needs a 1000-column line
2536
+ # rather than an 80-character one.
2537
+ # the prompt SS34. Set to a token this process minted, so
2538
+ # "the shell is ready" is read rather than
2539
+ # inferred from silence. (Described rather than
2540
+ # named by its shell variable, whose spelling is
2541
+ # exactly the shape of a decision id -- the
2542
+ # citation guard is right to say so.)
2543
+ # +o emacs +o vi line editing off, so nothing re-enables the echo.
2544
+ # --norc --noprofile no user rc file reaches it, in a container whose
2545
+ # image the user may have replaced.
2546
+ _INTERACTIVE_INNER = (
2547
+ "stty -echo rows 50 cols 1000; export PS1='{prompt}'; "
2548
+ "exec bash --norc --noprofile -i +o emacs +o vi")
2549
+
2550
+ _PROMPT_TOKEN_CHARS = frozenset(
2551
+ "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789>")
2552
+
2553
+
2554
+ def new_prompt_token() -> str:
2555
+ """A fresh prompt token for one interactive session (SS34).
2556
+
2557
+ Minted here rather than by the caller because it is embedded in a shell
2558
+ string below: the character set is the reason that embedding is safe,
2559
+ and a token and the quoting that contains it are one decision.
2560
+ """
2561
+ return "VEN" + uuid.uuid4().hex[:8] + ">"
2562
+
2563
+
2564
+ def _interactive_command(prompt_token: str) -> str:
2565
+ """The container's command for an interactive session.
2566
+
2567
+ The token is asserted against its own alphabet rather than quoted
2568
+ defensively: it is never a model's value -- `new_prompt_token` is the
2569
+ only thing that makes one -- and a check that says so is worth more than
2570
+ an escape that would hide the day it stopped being true.
2571
+ """
2572
+ if not prompt_token or set(prompt_token) - _PROMPT_TOKEN_CHARS:
2573
+ raise ValueError("prompt token is not a minted one: %r" % prompt_token)
2574
+ return 'script -qfec "%s" /dev/null' % _INTERACTIVE_INNER.format(
2575
+ prompt=prompt_token)
2576
+
2577
+
2578
+ def _docker_argv(
688
2579
  command: str,
689
2580
  workspace_dir: str,
690
- _shell_binary: str = "",
691
- network: bool = False,
692
- argv: bool = False,
693
- ) -> dict:
694
- """Run a command inside a Docker container with the workspace
695
- mounted as a volume. On timeout, the container is explicitly
696
- killed via ``docker kill`` to prevent orphaned containers from
697
- continuing to write to the host via the volume mount.
2581
+ network: bool,
2582
+ argv: bool,
2583
+ runtime: str,
2584
+ name: str,
2585
+ *,
2586
+ session_timeout_s: Optional[int] = None,
2587
+ prompt_token: str = "",
2588
+ ) -> list[str]:
2589
+ """The container command line, for a one-shot run and for a session.
2590
+
2591
+ ONE builder (ROADMAP_v3 §49), so a background session cannot come to
2592
+ run in a laxer container than a one-shot command: a `--network none`
2593
+ or a `:ro` bind present on one path and missing from the other is the
2594
+ drift EP6 names for routing, one layer down.
2595
+
2596
+ *runtime* is the CLI -- "docker" or "podman" (SS22) -- and nothing else
2597
+ in the argv changes with it: every flag here was measured to mean the
2598
+ same thing under rootless Podman 5.7, the nested `:ro` bind and
2599
+ `--network none` included.
698
2600
 
699
2601
  *argv* runs the command as a pre-split argument vector instead of
700
2602
  through ``bash -c`` (§46, EP5). Only INERT commands set it, and
@@ -704,24 +2606,60 @@ def _run_docker(
704
2606
  Handing those to bash anyway would insert a third tokeniser between
705
2607
  the classifier and the executor, and the gap between two of them is
706
2608
  where #157 arrived, twice.
2609
+
2610
+ *session_timeout_s* makes it a SESSION's argv, which differs in two
2611
+ places and no others:
2612
+
2613
+ --sig-proxy=false a console Ctrl+C reaches every process attached to
2614
+ the terminal, and `docker run` forwards signals
2615
+ into the container by default -- so a session
2616
+ would die of the user's keystroke and report
2617
+ `exited` where it was `killed`.
2618
+ timeout -k 10 N coreutils `timeout` as the container's first
2619
+ process, so a container orphaned by a harness that
2620
+ crashed still ends at its own cap. Measured: exit
2621
+ 124 after 3.6 s over two children, and a child
2622
+ ignoring TERM KILLed at 5.5 s, the container
2623
+ removed both times.
2624
+
2625
+ *prompt_token* makes it an INTERACTIVE session's argv (slice 2), which
2626
+ differs in two more places and no others:
2627
+
2628
+ -i docker keeps the container's stdin open as a PIPE.
2629
+ NOT `-t`: the pty is made inside the container by
2630
+ `script`, so nothing here needs a real terminal.
2631
+ the wrapper `_interactive_command`, in place of the agent's
2632
+ text. An interactive session's *command* is TYPED
2633
+ into the shell once it is up, not handed to the
2634
+ container -- so it is classified and approved as
2635
+ `shell` would (SS32), and the shell it lands in is
2636
+ always the one measured here rather than whatever
2637
+ the text happened to start.
707
2638
  """
708
2639
  workspace_real = os.path.realpath(workspace_dir)
709
- container_name = f"sandbox-{uuid.uuid4().hex[:12]}"
710
2640
 
711
2641
  docker_args = [
712
- "docker", "run", "--rm",
713
- "--name", container_name,
2642
+ runtime, "run", "--rm",
2643
+ "--name", name,
714
2644
  # §46 (EP7). Ours, and findable as ours. The name is a uuid, so
715
2645
  # `docker ps` could not tell a container of ours from any other
716
2646
  # tool's -- which matters when you are trying to work out
717
2647
  # whether something on your machine is this harness.
718
2648
  "--label", "venastine.sandbox=1",
2649
+ # ROADMAP_v3 §49. Which harness PROCESS started it. Two instances
2650
+ # may run at once, so cleaning up "our" containers by the label
2651
+ # above would kill the other's sessions; this one scopes it.
2652
+ "--label", f"venastine.process={PROCESS_TOKEN}",
719
2653
  "-v", f"{workspace_real}:/workspace",
720
2654
  "-w", "/workspace",
721
2655
  "--memory", f"{config.SANDBOX_MEMORY_MB}m",
722
2656
  "--cpus", "1",
723
2657
  "--pids-limit", str(config.SANDBOX_MAX_PIDS),
724
2658
  ]
2659
+ if session_timeout_s is not None:
2660
+ docker_args.append("--sig-proxy=false")
2661
+ if prompt_token:
2662
+ docker_args.append("-i")
725
2663
 
726
2664
  if not network:
727
2665
  docker_args.append("--network")
@@ -737,17 +2675,69 @@ def _run_docker(
737
2675
 
738
2676
  docker_args.extend(["-e", "PATH=/usr/bin:/bin:/usr/local/bin"])
739
2677
  docker_args.append(config.SANDBOX_DOCKER_IMAGE)
740
- if argv:
741
- docker_args.extend(shlex.split(command))
2678
+ if session_timeout_s is not None:
2679
+ docker_args.extend(["timeout", "-k", "10", str(session_timeout_s)])
2680
+ if prompt_token:
2681
+ # The agent's text is not in this argv at all; see the docstring.
2682
+ docker_args.extend(
2683
+ ["bash", "-c", _interactive_command(prompt_token)])
2684
+ elif argv:
2685
+ # `_inert_argv`, NOT a second `shlex.split` (batch 108). That
2686
+ # function is the one copy of this tokenisation and its docstring
2687
+ # is explicit that two copies are two tokenisers free to drift --
2688
+ # which is the gap #157 arrived through, twice. This line was the
2689
+ # second copy, and it had already drifted in two ways: `posix=True`
2690
+ # unconditionally where `_inert_argv` reads
2691
+ # `posix=(platform.system() != "Windows")`, and no fallback for the
2692
+ # ValueError an unbalanced quote raises.
2693
+ #
2694
+ # Neither drift could be OBSERVED, and that is the point rather
2695
+ # than a reason to have left it. Measured over 398,184 generated
2696
+ # strings that `_SHELL_METACHARACTERS` admits, `command.split()`,
2697
+ # `shlex.split(posix=True)` and `shlex.split(posix=False)` returned
2698
+ # the same list every time -- because the only characters the two
2699
+ # modes disagree about are the three the regex rejects. So the
2700
+ # container path was correct by coincidence with a guard in another
2701
+ # function, which is exactly the "correct only when someone else
2702
+ # ran first" coupling `_ssh_known_hosts` was rewritten to stop
2703
+ # being.
2704
+ docker_args.extend(_inert_argv(command))
742
2705
  else:
743
2706
  docker_args.extend(["bash", "-c", command])
2707
+ return docker_args
2708
+
2709
+
2710
+ def _run_docker(
2711
+ command: str,
2712
+ workspace_dir: str,
2713
+ _shell_binary: str = "",
2714
+ network: bool = False,
2715
+ argv: bool = False,
2716
+ runtime: str = DOCKER,
2717
+ ) -> dict:
2718
+ """Run a command inside a container with the workspace mounted as a
2719
+ volume. On timeout, the container is explicitly killed via
2720
+ ``<runtime> kill`` to prevent orphaned containers from continuing to
2721
+ write to the host via the volume mount.
2722
+
2723
+ The argv is `_docker_argv`'s. The default runtime is Docker's so a
2724
+ caller that never probed builds the argv every test asserts; the
2725
+ production route passes `known_runtime()`.
2726
+ """
2727
+ container_name = f"sandbox-{uuid.uuid4().hex[:12]}"
2728
+ docker_args = _docker_argv(command, workspace_dir, network, argv,
2729
+ runtime, container_name)
744
2730
 
745
2731
  proc = None
746
2732
  try:
747
- proc = subprocess.Popen(
2733
+ proc = subprocess.Popen( # nosec B603 - EXECUTION ROUTE: carries the model's command by design. List form and no shell, so there is nothing to inject into; the bound is upstream -- mode gate G3, the INERT allowlist, the dangerous-flag check and the approval prompt -- not this call (the container one-shot)
748
2734
  docker_args,
749
2735
  stdout=subprocess.PIPE,
750
2736
  stderr=subprocess.PIPE,
2737
+ # #203, batch 213. The CLI ran without `-i`, so it held the
2738
+ # inherited console and never read it; DEVNULL anyway, so no
2739
+ # route but the sessions' own PIPE hands a child the console.
2740
+ stdin=subprocess.DEVNULL,
751
2741
  text=True,
752
2742
  )
753
2743
  stdout, stderr = proc.communicate(
@@ -762,12 +2752,12 @@ def _run_docker(
762
2752
  # Kill the container explicitly — killing the CLI client
763
2753
  # (proc.kill()) does NOT stop the container under the daemon.
764
2754
  try:
765
- subprocess.run(
766
- ["docker", "kill", container_name],
2755
+ subprocess.run( # nosec B603 - kills the container on timeout; runtime and container name are this module's
2756
+ [runtime, "kill", container_name],
767
2757
  capture_output=True, timeout=10,
768
2758
  )
769
2759
  except (FileNotFoundError, subprocess.TimeoutExpired):
770
- pass
2760
+ pass # the runtime is gone or hung; the process kill below still runs
771
2761
  if proc is not None:
772
2762
  proc.kill()
773
2763
  proc.wait()
@@ -781,9 +2771,253 @@ def _run_docker(
781
2771
  proc.kill()
782
2772
  proc.wait()
783
2773
  raise SandboxUnavailable(
784
- "Docker CLI not found. Install Docker Desktop or enable "
785
- "ALLOW_INSECURE_SANDBOX_FALLBACK in config.py."
2774
+ f"The {runtime} CLI was not found. Install Docker or Podman, "
2775
+ "or set allow_insecure_sandbox_fallback: true in config.yaml."
2776
+ )
2777
+
2778
+
2779
+ def _run_wsl(command: str, workspace_dir: str, argv: bool = False,
2780
+ as_root: bool = False) -> dict:
2781
+ """Run a command in the distro (ROADMAP_v3 §49, slice 3).
2782
+
2783
+ `_run_docker`'s opposite number, and shorter for one measured reason:
2784
+ killing the Windows process kills the Linux side. `sleep 987 &` plus a
2785
+ foreground `sleep 986`, then `Popen.kill()`, left neither behind -- so
2786
+ there is no `wsl kill <name>` step, no label, and no orphan to reap.
2787
+ The container needs one because the CLI client is not the container.
2788
+
2789
+ No resource limits (SS44). They belong to the whole WSL VM, and a
2790
+ `ulimit` inside the shell is removable by the command it is meant to
2791
+ bound -- a control that reads as safety without being one, which is the
2792
+ failure SECURITY.md already names for the insecure fallback.
2793
+ """
2794
+ workspace_posix = _wsl_workspace(workspace_dir)
2795
+ if not workspace_posix:
2796
+ raise SandboxUnavailable(_wsl_workspace_refusal(workspace_dir))
2797
+ secret = None
2798
+ if as_root:
2799
+ # The same refusal the gate read, re-read here: `run_sandboxed` is
2800
+ # a public entry point and the store can lock between the two.
2801
+ refusal = sudo_refusal(BACKEND_WSL)
2802
+ if refusal:
2803
+ raise SandboxUnavailable(refusal)
2804
+ secret = _sudo_secret(BACKEND_WSL)
2805
+ args = _wsl_argv(command, workspace_posix, argv_mode=argv,
2806
+ as_root=as_root)
2807
+ # SS60's "an exception escaping any secret consumer" trigger. The SSH
2808
+ # route gets this from `askpass.serving`; this route has no listener,
2809
+ # so it says so itself.
2810
+ with secrets.guarded("a root command on WSL") if as_root \
2811
+ else contextlib.nullcontext():
2812
+ return _run_wsl_process(args, secret)
2813
+
2814
+
2815
+ def _run_wsl_process(args: list, secret) -> dict:
2816
+ """The half of `_run_wsl` that owns the subprocess.
2817
+
2818
+ Split out for `_run_ssh_process`'s reason: the window in which a
2819
+ plaintext is in flight should be a BLOCK, not a try/finally wrapped
2820
+ round three returns and a raise.
2821
+ """
2822
+ as_root = secret is not None
2823
+ proc = None
2824
+ try:
2825
+ proc = subprocess.Popen( # nosec B603 - EXECUTION ROUTE: carries the model's command by design. List form and no shell, so there is nothing to inject into; the bound is upstream -- mode gate G3, the INERT allowlist, the dangerous-flag check and the approval prompt -- not this call (the WSL one-shot)
2826
+ args,
2827
+ stdout=subprocess.PIPE,
2828
+ stderr=subprocess.PIPE,
2829
+ # SS70, and a fix rather than a parameter this route needed.
2830
+ # Passing no `stdin` at all made a WSL command INHERIT this
2831
+ # process's console -- measured, a command here read a string
2832
+ # written to the harness's own stdin -- which is a second
2833
+ # reader beside the CLI's one (§29 N1) on a route written
2834
+ # before that rule existed. DEVNULL is what the container and
2835
+ # the SSH one-shot already give; the pipe carries one line and
2836
+ # is the harness's alone to write.
2837
+ stdin=subprocess.PIPE if as_root else subprocess.DEVNULL,
2838
+ text=True,
2839
+ # SS42, and the only thing between a `WSLENV` naming an API key
2840
+ # and the distro reading it. Measured: with `WSLENV` set to a
2841
+ # secret's name the unscrubbed run printed the secret inside
2842
+ # the distro; with this it printed ABSENT, and `id`/`pwd` still
2843
+ # worked, so wsl.exe does not need what is being taken away.
2844
+ env=_scrubbed_env(),
2845
+ )
2846
+ stdout, stderr = proc.communicate(
2847
+ input=(_sudo_password_line(secret)
2848
+ if secret is not None else None),
2849
+ timeout=config.SANDBOX_TIMEOUT_SECONDS,
2850
+ )
2851
+ _note_sudo_auth_failure(stderr, BACKEND_WSL, secret is not None)
2852
+ return {
2853
+ "stdout": stdout[:config.MAX_READ_CHARS],
2854
+ "stderr": stderr[:config.MAX_READ_CHARS],
2855
+ "return_code": proc.returncode,
2856
+ }
2857
+ except subprocess.TimeoutExpired:
2858
+ proc.kill()
2859
+ proc.wait()
2860
+ return {
2861
+ "stdout": "",
2862
+ "stderr": f"Command timed out after "
2863
+ f"{config.SANDBOX_TIMEOUT_SECONDS}s",
2864
+ "return_code": -1,
2865
+ }
2866
+ except FileNotFoundError:
2867
+ if proc is not None:
2868
+ proc.kill()
2869
+ proc.wait()
2870
+ raise SandboxUnavailable(
2871
+ "wsl.exe was not found, so the WSL backend cannot run "
2872
+ "anything.") from None
2873
+
2874
+
2875
+ def _wsl_workspace_refusal(workspace_dir: str) -> str:
2876
+ """Why a workspace the distro cannot see stops the route. One copy for
2877
+ the one-shot path and the session path."""
2878
+ return (f"WSL cannot see the workspace {workspace_dir!r}. `wslpath` "
2879
+ f"could not translate it, which happens for a UNC path or a "
2880
+ f"drive WSL does not mount. The command is refused rather than "
2881
+ f"run somewhere else: `wsl.exe --cd` answers an untranslatable "
2882
+ f"path by exiting 0 and running in your Linux home directory, "
2883
+ f"so it would have reported success from the wrong place.")
2884
+
2885
+
2886
+ def _ssh_workspace_refusal(stderr: str) -> str:
2887
+ """Why a remote working directory that is not there stops the command.
2888
+
2889
+ Recognised by BOTH the exit code and the marker the guard prints
2890
+ (SS52), because either alone is guessable: 125 is inside `timeout`'s
2891
+ own vocabulary, and a command is free to print any string it likes.
2892
+ """
2893
+ workspace = (config.SSH_REMOTE_WORKSPACE or "").strip()
2894
+ detail = " ".join(stderr.split())[:200]
2895
+ return (f"The remote working directory {workspace!r} could not be "
2896
+ f"entered on {ssh_target()}, so nothing was run. This is "
2897
+ f"refused rather than run somewhere else -- `ssh_remote_"
2898
+ f"workspace` names where approved work happens, and a command "
2899
+ f"that silently ran in the login home would report success "
2900
+ f"from a place nobody named. The remote said: {detail}")
2901
+
2902
+
2903
+ def _ssh_failed_to_start(stderr: str) -> str:
2904
+ """A connection that never carried the command, told apart from one
2905
+ that did. Same composition rule as the probe's (see
2906
+ `_ssh_connect_failure_reason`): ssh's own text is generic, so it is
2907
+ quoted after an interpretation rather than instead of one."""
2908
+ return _ssh_connect_failure_reason(ssh_target(),
2909
+ " ".join(stderr.split())[:300])
2910
+
2911
+
2912
+ def _run_ssh(command: str, workspace_dir: str,
2913
+ as_root: bool = False) -> dict:
2914
+ """Run a command on the configured remote host (ROADMAP_v3 §49, slice 4).
2915
+
2916
+ *workspace_dir* is the LOCAL workspace and is deliberately unused: the
2917
+ command runs in `ssh_remote_workspace`, on a filesystem this process
2918
+ cannot see. That gap is the trap this backend is most able to set --
2919
+ `write` saves a file locally and a shell here cannot read it -- and it
2920
+ is disclosed in the tool description and the approval notice rather
2921
+ than papered over (SS55).
2922
+
2923
+ No resource limits (SS44's rule on a third route), and here not even a
2924
+ `ulimit` to be theatre about: the remote's memory and CPU belong to the
2925
+ remote. What DOES bound this is the local wall clock below, and for a
2926
+ session the in-guest `timeout -k` that `_ssh_remote_script` wraps in.
2927
+ """
2928
+ sudo_secret = None
2929
+ if as_root:
2930
+ refusal = sudo_refusal(BACKEND_SSH)
2931
+ if refusal:
2932
+ raise SandboxUnavailable(refusal)
2933
+ sudo_secret = _sudo_secret(BACKEND_SSH)
2934
+ args = _ssh_argv(command, as_root=as_root)
2935
+ stored = _ssh_stored_secrets()
2936
+
2937
+ # SS64. The listener stands up only when something is stored, so the
2938
+ # no-secret path does not open a socket at all -- and `serving` locks
2939
+ # the store if anything escapes this block, which is SS60's
2940
+ # "an exception during a secret consumer" trigger.
2941
+ #
2942
+ # `guarded` is the same trigger for the ROOT half, which `serving`
2943
+ # does not cover: a host on key auth stores no login secret, so there
2944
+ # is no listener, and a sudo password is still in this process.
2945
+ with secrets.guarded("a root command over SSH") if as_root \
2946
+ else contextlib.nullcontext():
2947
+ with askpass.serving(stored) if stored \
2948
+ else contextlib.nullcontext() as live:
2949
+ env = _ssh_env()
2950
+ if live is not None:
2951
+ env.update(live.env)
2952
+ return _run_ssh_process(args, env, bool(stored), sudo_secret)
2953
+
2954
+
2955
+ def _run_ssh_process(args: list, env: dict, used_secrets: bool,
2956
+ sudo_secret=None) -> dict:
2957
+ """The half of `_run_ssh` that owns the subprocess, split out so the
2958
+ askpass window is a block rather than a try/finally wrapped round
2959
+ three returns and two raises."""
2960
+ proc = None
2961
+ try:
2962
+ proc = subprocess.Popen( # nosec B603 - EXECUTION ROUTE: carries the model's command by design. List form and no shell, so there is nothing to inject into; the bound is upstream -- mode gate G3, the INERT allowlist, the dangerous-flag check and the approval prompt -- not this call (the SSH one-shot)
2963
+ args,
2964
+ stdout=subprocess.PIPE,
2965
+ stderr=subprocess.PIPE,
2966
+ # DEVNULL unless there is a password to deliver, so the
2967
+ # no-root path is byte-for-byte the call slice 4 made.
2968
+ stdin=(subprocess.PIPE if sudo_secret is not None
2969
+ else subprocess.DEVNULL),
2970
+ text=True,
2971
+ # Measured, and NOT load-bearing the way SS42's is: nothing
2972
+ # local crosses into an SSH session by itself -- the remote
2973
+ # environment is twelve variables and every one is the
2974
+ # server's. The scrub stays because what a client SENDS is
2975
+ # `SendEnv`'s business and `SendEnv` lives in a config file
2976
+ # this harness cannot redirect, which `-F none` closes from
2977
+ # the other side. Two answers to one question is the point.
2978
+ env=env,
786
2979
  )
2980
+ stdout, stderr = proc.communicate(
2981
+ input=(_sudo_password_line(sudo_secret)
2982
+ if sudo_secret is not None else None),
2983
+ timeout=config.SANDBOX_TIMEOUT_SECONDS,
2984
+ )
2985
+ _note_ssh_auth_failure(stderr, used_secrets)
2986
+ _note_sudo_auth_failure(stderr, BACKEND_SSH, sudo_secret is not None)
2987
+ if (proc.returncode == _SSH_NO_WORKSPACE_CODE
2988
+ and _SSH_NO_WORKSPACE_MARKER in stderr):
2989
+ raise SandboxUnavailable(_ssh_workspace_refusal(stderr))
2990
+ # 255 is ssh's own "I never got there", distinct from any exit code
2991
+ # the remote command could return -- a remote exit status is 0-255
2992
+ # but ssh reports 255 only for its own failures, and the command
2993
+ # never ran in that case. Measured across every failure shape:
2994
+ # refused port, unroutable host, unknown user, no key, wrong host
2995
+ # key -- all 255.
2996
+ if proc.returncode == 255 and not stdout:
2997
+ raise SandboxUnavailable(_ssh_failed_to_start(stderr))
2998
+ return {
2999
+ "stdout": stdout[:config.MAX_READ_CHARS],
3000
+ "stderr": stderr[:config.MAX_READ_CHARS],
3001
+ "return_code": proc.returncode,
3002
+ }
3003
+ except subprocess.TimeoutExpired:
3004
+ proc.kill()
3005
+ proc.wait()
3006
+ return {
3007
+ "stdout": "",
3008
+ "stderr": f"Command timed out after "
3009
+ f"{config.SANDBOX_TIMEOUT_SECONDS}s. The remote "
3010
+ f"command may still be running: killing the local "
3011
+ f"ssh process does not end it (SS53).",
3012
+ "return_code": -1,
3013
+ }
3014
+ except FileNotFoundError:
3015
+ if proc is not None:
3016
+ proc.kill()
3017
+ proc.wait()
3018
+ raise SandboxUnavailable(
3019
+ f"{_ssh_binary()!r} was not found, so the SSH backend cannot "
3020
+ f"run anything.") from None
787
3021
 
788
3022
 
789
3023
  # ---------------------------------------------------------------------------
@@ -791,19 +3025,26 @@ def _run_docker(
791
3025
  # ---------------------------------------------------------------------------
792
3026
 
793
3027
 
794
- def _unix_resource_limits() -> Optional[Callable[[], None]]:
3028
+ def _unix_resource_limits(
3029
+ cpu_seconds: Optional[int] = None,
3030
+ ) -> Optional[Callable[[], None]]:
795
3031
  """Return a preexec_fn that sets CPU and memory limits via rlimit.
796
- Returns None on Windows (rlimit not available)."""
3032
+ Returns None on Windows (rlimit not available).
3033
+
3034
+ *cpu_seconds* defaults to `config.SANDBOX_CPU_SECONDS`, a one-shot
3035
+ command's budget. A background session passes its own effective
3036
+ timeout (ROADMAP_v3 §49, SS15): 30 CPU-seconds would end a CPU-bound
3037
+ session long before a cap of an hour, and report it as the program
3038
+ dying rather than as the harness stopping it."""
797
3039
  if platform.system() == "Windows":
798
3040
  return None
799
3041
 
800
3042
  import resource
801
3043
 
3044
+ cpu = config.SANDBOX_CPU_SECONDS if cpu_seconds is None else int(cpu_seconds)
3045
+
802
3046
  def _set_limits():
803
- resource.setrlimit(
804
- resource.RLIMIT_CPU,
805
- (config.SANDBOX_CPU_SECONDS, config.SANDBOX_CPU_SECONDS),
806
- )
3047
+ resource.setrlimit(resource.RLIMIT_CPU, (cpu, cpu))
807
3048
  mem_bytes = config.SANDBOX_MEMORY_MB * 1024 * 1024
808
3049
  resource.setrlimit(resource.RLIMIT_AS, (mem_bytes, mem_bytes))
809
3050
 
@@ -823,23 +3064,41 @@ def _run_subprocess_fallback(
823
3064
  """
824
3065
  preexec = _unix_resource_limits()
825
3066
 
3067
+ # ITS OWN PROCESS GROUP ON POSIX, so the timeout path below can
3068
+ # signal the GROUP. Without it the shell was killed and its
3069
+ # children ran on (batch 142, four survivors measured), and the flag
3070
+ # on its own is not the fix -- `_terminate_tree` is.
3071
+ #
3072
+ # NOT `_isolation_kwargs()`, which is the SESSION's answer and also
3073
+ # carries CREATE_NEW_PROCESS_GROUP on Windows. A session is stopped
3074
+ # through `kill()` from elsewhere; a one-shot is waited on right
3075
+ # here, so taking it out of the console's group on Windows would
3076
+ # only stop Ctrl+C reaching it, while `taskkill /T` already
3077
+ # reclaims the tree by pid. What Ctrl+C costs on POSIX is paid
3078
+ # below, where an interrupt reclaims before it unwinds.
3079
+ group_kwargs = ({} if platform.system() == "Windows"
3080
+ else {"start_new_session": True})
826
3081
  try:
827
- result = subprocess.run(
3082
+ proc = subprocess.Popen(
828
3083
  [shell_binary, "-c", command],
829
3084
  cwd=workspace_dir,
830
3085
  env=_scrubbed_env(),
831
- capture_output=True,
3086
+ stdout=subprocess.PIPE,
3087
+ stderr=subprocess.PIPE,
3088
+ # DEVNULL rather than INHERITED, which is what
3089
+ # `subprocess.run(capture_output=True)` left until batch
3090
+ # 142. SS70 measured the identical omission on the WSL
3091
+ # one-shot: a command there read a string written to the
3092
+ # HARNESS's own stdin, a second reader of the console
3093
+ # beside the CLI's one (N1). Every other route already
3094
+ # passes DEVNULL, and a command that waits on stdin now
3095
+ # ends instead of burning the whole wall clock.
3096
+ stdin=subprocess.DEVNULL,
832
3097
  text=True,
833
- timeout=config.SANDBOX_TIMEOUT_SECONDS,
834
3098
  preexec_fn=preexec,
835
- shell=False,
3099
+ shell=False, # nosec B603 - EXECUTION ROUTE: carries the model's command by design. List form and no shell, so there is nothing to inject into; the bound is upstream -- mode gate G3, the INERT allowlist, the dangerous-flag check and the approval prompt -- not this call (the insecure host fallback)
3100
+ **group_kwargs,
836
3101
  )
837
- except subprocess.TimeoutExpired:
838
- return {
839
- "stdout": "",
840
- "stderr": f"Command timed out after {config.SANDBOX_TIMEOUT_SECONDS}s",
841
- "return_code": -1,
842
- }
843
3102
  except FileNotFoundError as e:
844
3103
  return {
845
3104
  "stdout": "",
@@ -855,10 +3114,44 @@ def _run_subprocess_fallback(
855
3114
  "return_code": -1,
856
3115
  }
857
3116
 
3117
+ try:
3118
+ stdout, stderr = proc.communicate(
3119
+ timeout=config.SANDBOX_TIMEOUT_SECONDS)
3120
+ except subprocess.TimeoutExpired:
3121
+ # H7: the message below asserts the work stopped, so it has to
3122
+ # have stopped. `_reclaim_tree` is the session path's own
3123
+ # answer, shared rather than copied.
3124
+ reclaimed = _reclaim_tree(proc)
3125
+ stdout, stderr = _drain_after_kill(proc)
3126
+ note = (
3127
+ "Command timed out after "
3128
+ f"{config.SANDBOX_TIMEOUT_SECONDS}s. The shell and its "
3129
+ "process group were killed."
3130
+ if reclaimed else
3131
+ "Command timed out after "
3132
+ f"{config.SANDBOX_TIMEOUT_SECONDS}s, and it OUTLIVED a "
3133
+ "forced kill: some of its processes may still be running "
3134
+ "with your own authority, since this route has no "
3135
+ "isolation.")
3136
+ return {
3137
+ "stdout": (stdout or "")[:config.MAX_READ_CHARS],
3138
+ "stderr": ((stderr or "") + ("\n" if stderr else "")
3139
+ + note)[:config.MAX_READ_CHARS],
3140
+ "return_code": -1,
3141
+ }
3142
+ except BaseException:
3143
+ # Ctrl+C included, and it is the reason this is BaseException:
3144
+ # on POSIX the child now leads its own group, so the keystroke
3145
+ # the terminal delivered did NOT reach it. Reclaiming before
3146
+ # the unwind is what keeps the group change from trading a
3147
+ # timeout orphan for an interrupt orphan.
3148
+ _reclaim_tree(proc)
3149
+ raise
3150
+
858
3151
  return {
859
- "stdout": result.stdout[:config.MAX_READ_CHARS],
860
- "stderr": result.stderr[:config.MAX_READ_CHARS],
861
- "return_code": result.returncode,
3152
+ "stdout": (stdout or "")[:config.MAX_READ_CHARS],
3153
+ "stderr": (stderr or "")[:config.MAX_READ_CHARS],
3154
+ "return_code": proc.returncode,
862
3155
  }
863
3156
 
864
3157
 
@@ -873,10 +3166,13 @@ def run_sandboxed(
873
3166
  shell_binary: Optional[str] = None,
874
3167
  docker_available: Optional[bool] = None,
875
3168
  profile: Optional[CommandProfile] = None,
3169
+ backend: str = BACKEND_CONTAINER,
3170
+ needs_root: bool = False,
876
3171
  ) -> dict:
877
3172
  """Execute *command* through the appropriate sandbox backend.
878
3173
 
879
3174
  Routing:
3175
+ 0. The call asked for WSL or SSH → that backend, or a refusal (SS37)
880
3176
  1. Inert command → lightweight subprocess (no Docker/fallback needed)
881
3177
  2. Docker available → container with volume mount
882
3178
  3. Fallback enabled → subprocess with shell interpretation
@@ -905,7 +3201,21 @@ def run_sandboxed(
905
3201
  if refusal:
906
3202
  raise SandboxUnavailable(refusal)
907
3203
 
908
- if shell_binary is None:
3204
+ # Slice 5b, above makedirs for the workspace check's own reason: a call
3205
+ # that cannot run must not leave a directory behind. `_shell_approval_
3206
+ # check` already read this same refusal to answer "there is nothing to
3207
+ # approve", and `sudo_refusal` is the one copy both of them read.
3208
+ if needs_root:
3209
+ refusal = sudo_refusal(backend)
3210
+ if refusal:
3211
+ raise SandboxUnavailable(refusal)
3212
+
3213
+ # Not on the WSL route, which runs `bash` IN THE DISTRO and never reads
3214
+ # this. `detect_shell()` probes pwsh and then powershell with a 5s
3215
+ # timeout each, so a WSL call was paying for a Windows shell it does
3216
+ # not use -- and asking the host what shell it has, in order to run a
3217
+ # command somewhere else, is the wrong question as well as a slow one.
3218
+ if shell_binary is None and backend != BACKEND_WSL:
909
3219
  shell_binary = detect_shell()
910
3220
 
911
3221
  # Audit #50: nothing else in the codebase ever created WORKSPACE_DIR,
@@ -920,29 +3230,57 @@ def run_sandboxed(
920
3230
  if profile is None:
921
3231
  profile = classify_command(command, workspace_dir)
922
3232
 
3233
+ # Use pre-computed Docker status if provided (fixes TOCTOU), otherwise
3234
+ # probe now. HOST_READ never needs the answer, so it does not pay for
3235
+ # the probe, which is how this function always behaved.
3236
+ if docker_available is None and profile.tier != HOST_READ:
3237
+ docker_available = is_docker_available()
3238
+ # ROADMAP_v3 §49. The branch ladder below is `_route`'s, shared with
3239
+ # `start_sandboxed`, so a background session is routed by the same
3240
+ # decision a one-shot command is (EP6 keeps it agreeing with
3241
+ # containment_for).
3242
+ route = _route(profile, bool(docker_available), backend)
3243
+
3244
+ # ROADMAP_v3 §49 slice 3 (SS38). Above HOST_READ, because a call that
3245
+ # asked for WSL must not be handed to the Windows host by a tier.
3246
+ if route == ROUTE_WSL:
3247
+ logger.debug("WSL path (%s): %s", wsl_distro(), command[:80])
3248
+ return _annotate(
3249
+ _run_wsl(command, workspace_dir, argv=(profile.tier == INERT),
3250
+ as_root=needs_root),
3251
+ profile, "wsl", needs_root)
3252
+
3253
+ if route == ROUTE_SSH:
3254
+ logger.debug("SSH path (%s): %s", ssh_target(), command[:80])
3255
+ # `ran_on` is "ssh", not the host and not a container. `_annotate`
3256
+ # already takes it as a string, so the disclosure costs nothing
3257
+ # here -- what it buys is that a result can never imply the
3258
+ # command ran on this machine.
3259
+ return _annotate(_run_ssh(command, workspace_dir, needs_root),
3260
+ profile, "ssh", needs_root)
3261
+
923
3262
  # HOST_READ names a file the container cannot see, so it has exactly
924
3263
  # one backend and takes it before Docker is even considered.
925
- if profile.tier == HOST_READ:
3264
+ if route == ROUTE_HOST_READ:
926
3265
  logger.debug("Host read, using light path: %s", command[:80])
927
3266
  return _annotate(_run_inert(command, workspace_dir, shell_binary),
928
3267
  profile, "host")
929
3268
 
930
- # Use pre-computed Docker status if provided (fixes TOCTOU),
931
- # otherwise probe now.
932
- if docker_available is None:
933
- docker_available = is_docker_available()
934
-
935
- if docker_available:
3269
+ if route == ROUTE_CONTAINER:
936
3270
  network = profile.network
3271
+ # ROADMAP_v3 §49 (SS22). Docker's CLI or Podman's, as the probe that
3272
+ # produced `docker_available` found -- read, never re-probed.
3273
+ runtime = known_runtime()
937
3274
  logger.debug(
938
- "Docker path (network=%s): %s", network, command[:80],
3275
+ "Container path (%s, network=%s): %s", runtime, network,
3276
+ command[:80],
939
3277
  )
940
3278
  # HERE rather than inside _run_docker, which stays a function
941
3279
  # that builds an argv and opens one process. Putting a second
942
3280
  # subprocess in there would put it on the timeout and kill
943
3281
  # paths too, and it collides with every test that patches Popen
944
3282
  # to inspect the argv -- subprocess.run goes through Popen.
945
- _log_image_identity()
3283
+ _log_image_identity(runtime)
946
3284
  return _annotate(
947
3285
  _run_docker(command, workspace_dir, shell_binary, network,
948
3286
  # §46 (EP5). An inert command has no
@@ -952,7 +3290,8 @@ def run_sandboxed(
952
3290
  # executor, which is the gap #157 came through
953
3291
  # twice. argv keeps the `shell=False` semantics
954
3292
  # the light path always had.
955
- argv=(profile.tier == INERT)),
3293
+ argv=(profile.tier == INERT),
3294
+ runtime=runtime),
956
3295
  profile, "container")
957
3296
 
958
3297
  # §46 (EP5). Docker is down. An inert command still has somewhere to
@@ -960,7 +3299,7 @@ def run_sandboxed(
960
3299
  # approval answer is the same under either containment (see
961
3300
  # containment_for). What the model is told changes, and that is the
962
3301
  # point of saying it: `ran_on` reports "host" here.
963
- if profile.tier == INERT:
3302
+ if route == ROUTE_INERT_HOST:
964
3303
  logger.debug(
965
3304
  "Docker unavailable, inert command on the host: %s",
966
3305
  command[:80],
@@ -968,7 +3307,7 @@ def run_sandboxed(
968
3307
  return _annotate(_run_inert(command, workspace_dir, shell_binary),
969
3308
  profile, "host")
970
3309
 
971
- if posture.current().allow_insecure_fallback:
3310
+ if route == ROUTE_FALLBACK:
972
3311
  logger.warning(
973
3312
  "Using INSECURE subprocess fallback: %s", command[:80],
974
3313
  )
@@ -976,10 +3315,794 @@ def run_sandboxed(
976
3315
  _run_subprocess_fallback(command, workspace_dir, shell_binary),
977
3316
  profile, "host")
978
3317
 
979
- raise SandboxUnavailable(
980
- "Docker is not available and ALLOW_INSECURE_SANDBOX_FALLBACK is "
981
- "False. Install Docker Desktop for strong isolation, or set "
982
- "ALLOW_INSECURE_SANDBOX_FALLBACK = True in config.py to use the "
3318
+ raise SandboxUnavailable(_unavailable_message(backend))
3319
+
3320
+
3321
+ def _unavailable_message(backend: str = BACKEND_CONTAINER) -> str:
3322
+ """What a caller is told when no backend can run a command.
3323
+
3324
+ The probe's reason goes in because the case it exists for is otherwise
3325
+ baffling: Podman IS installed and answering, and was refused for limits
3326
+ it cannot enforce (SS24). A user told only "no runtime" would reinstall
3327
+ the one they have. One copy, for `run_sandboxed` and `start_sandboxed`.
3328
+
3329
+ A call that asked for WSL is told about WSL and nothing else (SS37).
3330
+ Offering it the container's install instructions would be answering a
3331
+ question it did not ask, and it is the shape that makes a model retry
3332
+ the same call with the same result.
3333
+ """
3334
+ if backend == BACKEND_WSL:
3335
+ return wsl_unavailable_reason() or (
3336
+ "The WSL backend cannot run this command.")
3337
+ if backend == BACKEND_SSH:
3338
+ return ssh_unavailable_reason() or (
3339
+ "The SSH backend cannot run this command.")
3340
+ reason = _known_unavailable_reason()
3341
+ return (
3342
+ "No container runtime can run the sandbox"
3343
+ + (f" ({reason})" if reason else "")
3344
+ + " and ALLOW_INSECURE_SANDBOX_FALLBACK is False. Install Docker or "
3345
+ "Podman for strong isolation, or set "
3346
+ "allow_insecure_sandbox_fallback: true in config.yaml to use the "
983
3347
  "weaker subprocess fallback (no filesystem isolation, no network "
984
3348
  "restriction)."
985
3349
  )
3350
+
3351
+
3352
+ # ---------------------------------------------------------------------------
3353
+ # ---- Routes and background sessions (ROADMAP_v3 §49, slice 1) --------------
3354
+ # ---------------------------------------------------------------------------
3355
+
3356
+ # Which harness process started a container: `<pid>-<uuid>`, because a pid
3357
+ # alone is reused by the OS and a later process could inherit an earlier
3358
+ # one's orphans. Minted once, at import.
3359
+ PROCESS_TOKEN = f"{os.getpid()}-{uuid.uuid4().hex[:12]}"
3360
+
3361
+ ROUTE_HOST_READ = "host_read"
3362
+ ROUTE_CONTAINER = "container"
3363
+ ROUTE_WSL = "wsl"
3364
+ ROUTE_SSH = "ssh"
3365
+ ROUTE_INERT_HOST = "inert_host"
3366
+ ROUTE_FALLBACK = "fallback"
3367
+ ROUTE_UNAVAILABLE = "unavailable"
3368
+
3369
+ # How long past a session's own timeout the in-container `timeout` waits
3370
+ # before ending it. The harness kills at the timeout and owns the
3371
+ # `timed_out` answer; this is the backstop for a harness that is no longer
3372
+ # there to kill anything.
3373
+ SESSION_TIMEOUT_MARGIN_S = 30
3374
+ _KILL_GRACE_S = 5
3375
+ _SIGKILL = getattr(signal, "SIGKILL", 9)
3376
+ _CREATE_NEW_PROCESS_GROUP = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP",
3377
+ 0x00000200)
3378
+ #: How long a reclaimed process gets to hand over what it had already
3379
+ #: written. Short, and bounded on purpose: an ORPHAN holding the write
3380
+ #: end of the pipe means EOF never comes, which is the 30.21s-for-a-5s
3381
+ #: bound half of the timeout defect batch 142 fixed.
3382
+ _DRAIN_AFTER_KILL_S = 2.0
3383
+
3384
+
3385
+ def _leads_its_own_group(pid: int) -> bool:
3386
+ """True when *pid* is its own process group leader.
3387
+
3388
+ ASKED BEFORE EVERY `killpg`, and the reason is the failure mode
3389
+ rather than tidiness. `os.killpg` takes a process GROUP id, and a
3390
+ child started WITHOUT `start_new_session` sits in THIS process's
3391
+ group -- so passing its pid as a group id means either no such
3392
+ group (ESRCH, which the caller handles) or, if an unrelated group
3393
+ happens to carry that id, somebody else's processes.
3394
+
3395
+ The property holds for both callers today: `_isolation_kwargs`
3396
+ sets the flag for a session and `_run_subprocess_fallback` sets it
3397
+ for a one-shot. So this is a guard that KEEPS it true rather than
3398
+ a fix for a live defect -- a change at either launch site can no
3399
+ longer turn a kill of the work into a kill of the harness.
3400
+ """
3401
+ try:
3402
+ return os.getpgid(pid) == pid
3403
+ except (OSError, AttributeError):
3404
+ # AttributeError is Windows, where there are no process groups
3405
+ # in this sense and `taskkill /T` is the tree walk instead.
3406
+ return False
3407
+
3408
+
3409
+ def _signal_tree(proc, sig) -> None:
3410
+ """Send *sig* to *proc*'s whole group, or to *proc* if it does not
3411
+ lead one."""
3412
+ if _leads_its_own_group(proc.pid):
3413
+ try:
3414
+ os.killpg(proc.pid, sig)
3415
+ return
3416
+ except OSError:
3417
+ pass
3418
+ proc.kill()
3419
+
3420
+
3421
+ def _terminate_tree(proc) -> None:
3422
+ """The polite stop, for the work and not only its shell.
3423
+
3424
+ A shell's children are what actually do the work (SS15), so a
3425
+ terminate that reaches only the shell reports a stop it did not
3426
+ make -- which H7 forbids: an IO bound that reports a timeout must
3427
+ have STOPPED the work. Measured (batch 142) on the one-shot route
3428
+ before this existed: `pgrep -a sleep` listed four survivors after
3429
+ a reported timeout, and the control in the same run showed
3430
+ `start_new_session=True` ALONE changes nothing, because nothing
3431
+ signalled the group.
3432
+ """
3433
+ if platform.system() == "Windows":
3434
+ try:
3435
+ subprocess.run( # nosec B603 - `taskkill` against this process's own child, by pid
3436
+ ["taskkill", "/T", "/F", "/PID", str(proc.pid)],
3437
+ capture_output=True, timeout=10)
3438
+ except (OSError, subprocess.TimeoutExpired):
3439
+ proc.kill()
3440
+ return
3441
+ _signal_tree(proc, signal.SIGTERM)
3442
+
3443
+
3444
+ def _force_tree(proc) -> None:
3445
+ """The forced stop. On Windows `taskkill /T /F` was already the
3446
+ forced one, so this is the single-process fallback for the case
3447
+ where it could not run."""
3448
+ if platform.system() == "Windows":
3449
+ proc.kill()
3450
+ return
3451
+ _signal_tree(proc, _SIGKILL)
3452
+
3453
+
3454
+ def _reclaim_tree(proc, *, grace_s: float = _KILL_GRACE_S) -> bool:
3455
+ """Stop *proc* and the work below it: polite, a grace period, then
3456
+ forced. True when it is gone.
3457
+
3458
+ ONE DECISION IN ONE PLACE, which is EP6's rule applied to a
3459
+ sibling pair rather than to a gate: `SessionProcess.kill` and
3460
+ `_run_subprocess_fallback`'s timeout are both "stop this host
3461
+ process and its children", and they were two different answers --
3462
+ the session's correct, the one-shot's a terminate of the shell
3463
+ alone under a message asserting the opposite.
3464
+ """
3465
+ _terminate_tree(proc)
3466
+ try:
3467
+ proc.wait(timeout=grace_s)
3468
+ return True
3469
+ except subprocess.TimeoutExpired:
3470
+ pass
3471
+ _force_tree(proc)
3472
+ try:
3473
+ proc.wait(timeout=grace_s)
3474
+ return True
3475
+ except subprocess.TimeoutExpired:
3476
+ logger.warning("Process %s outlived a forced kill", proc.pid)
3477
+ return False
3478
+
3479
+
3480
+ def _drain_after_kill(proc) -> tuple:
3481
+ """Whatever *proc* had already written, bounded.
3482
+
3483
+ `communicate()` after a kill is how CPython hands over the
3484
+ buffered output, and it waits for EOF on the pipes. An ORPHANED
3485
+ GRANDCHILD STILL HOLDS THE WRITE END, so on Windows that wait is
3486
+ what turned a 5s bound into a 30.21s return -- measured, and in
3487
+ principle unbounded. The second bound is what makes the first one
3488
+ true."""
3489
+ try:
3490
+ return proc.communicate(timeout=_DRAIN_AFTER_KILL_S)
3491
+ except subprocess.TimeoutExpired:
3492
+ return "", ""
3493
+ except (OSError, ValueError):
3494
+ # ValueError: the pipes are closed already, which is what a
3495
+ # second drain on a reaped process looks like.
3496
+ return "", ""
3497
+
3498
+
3499
+ def _route(profile: CommandProfile, docker_available: bool,
3500
+ backend: str = BACKEND_CONTAINER) -> str:
3501
+ """Which backend runs *profile*: the executor's half of EP6.
3502
+
3503
+ `run_sandboxed` and `start_sandboxed` both route through here, so a
3504
+ background session cannot be routed by a different decision from a
3505
+ one-shot command. `containment_for` is still the gate's half, written
3506
+ separately on purpose (§46, EP6), and tests/test_session_backends.py
3507
+ holds the two against each other for every tier, runtime answer,
3508
+ backend and fallback posture.
3509
+
3510
+ THE WSL BRANCH IS FIRST, ABOVE HOST_READ (SS38), and that order is the
3511
+ decision rather than a consequence of one. `cat /etc/passwd` asked for
3512
+ on WSL classifies HOST_READ -- the argument is outside the workspace,
3513
+ which is true on either machine -- and the old ladder would have run it
3514
+ through `_run_inert` on WINDOWS, against `C:\\etc\\passwd`, with
3515
+ whichever `cat` is first on the user's PATH. The tier keeps its whole
3516
+ meaning (`escapes_workspace` still forces a prompt in every mode but
3517
+ `never`); what it must not do is choose a machine the call did not ask
3518
+ for and the prompt did not name.
3519
+ """
3520
+ if backend == BACKEND_WSL:
3521
+ return ROUTE_WSL if wsl_available() else ROUTE_UNAVAILABLE
3522
+ if backend == BACKEND_SSH:
3523
+ return ROUTE_SSH if ssh_available() else ROUTE_UNAVAILABLE
3524
+ if profile.tier == HOST_READ:
3525
+ return ROUTE_HOST_READ
3526
+ if docker_available:
3527
+ return ROUTE_CONTAINER
3528
+ if profile.tier == INERT:
3529
+ return ROUTE_INERT_HOST
3530
+ if posture.current().allow_insecure_fallback:
3531
+ return ROUTE_FALLBACK
3532
+ return ROUTE_UNAVAILABLE
3533
+
3534
+
3535
+ def _isolation_kwargs() -> dict:
3536
+ """Popen arguments that take a session out of the console's signal group.
3537
+
3538
+ A console Ctrl+C is delivered to every process attached to the terminal.
3539
+ The CLI kills sessions on Ctrl+C on purpose, through `kill()`; without
3540
+ this the keystroke would reach them first and they would report
3541
+ `exited` instead of `killed`. It also makes a host session its own
3542
+ process group, which is what lets `kill()` end a shell's children and
3543
+ not only the shell.
3544
+ """
3545
+ if platform.system() == "Windows":
3546
+ return {"creationflags": _CREATE_NEW_PROCESS_GROUP}
3547
+ return {"start_new_session": True}
3548
+
3549
+
3550
+ def _popen_session(args: list[str], *, cwd: Optional[str] = None,
3551
+ env: Optional[dict] = None,
3552
+ preexec_fn: Optional[Callable[[], None]] = None,
3553
+ stdin=subprocess.DEVNULL):
3554
+ """Start a session's process: one merged output stream, and by
3555
+ default no stdin.
3556
+
3557
+ NO STDIN BY DEFAULT, because a long-lived child reading the TERMINAL is
3558
+ a second reader beside the CLI's one (§29 N1). An interactive session
3559
+ passes a PIPE (slice 2), and N1's reason survives the constant intact:
3560
+ what it forbids is a child INHERITING THE CONSOLE, and a pipe that only
3561
+ the harness writes to is not a second reader of anything. The default
3562
+ stays DEVNULL so a caller gets the old behaviour by saying nothing.
3563
+
3564
+ stderr MERGED into stdout, because a monitor has to see lines in the
3565
+ order the program wrote them, and two pipes read on two threads do not
3566
+ preserve that. For an interactive session there is only one stream to
3567
+ merge anyway: a pty carries both.
3568
+ """
3569
+ return subprocess.Popen( # nosec B603 - EXECUTION ROUTE: carries the model's command by design. List form and no shell, so there is nothing to inject into; the bound is upstream -- mode gate G3, the INERT allowlist, the dangerous-flag check and the approval prompt -- not this call (a shell session)
3570
+ args, cwd=cwd, env=env,
3571
+ stdin=stdin,
3572
+ stdout=subprocess.PIPE,
3573
+ stderr=subprocess.STDOUT,
3574
+ preexec_fn=preexec_fn,
3575
+ **_isolation_kwargs(),
3576
+ )
3577
+
3578
+
3579
+ def _popen_session_with_credentials(
3580
+ args: list[str], *, env: dict, sudo_secret=None,
3581
+ guard_reason: str = "", askpass_answers=None):
3582
+ """`_popen_session` plus the credential windows a SESSION needs.
3583
+
3584
+ Returns `(proc, window)`, where *window* is the live
3585
+ `askpass.serving` context the session now OWNS, or None.
3586
+
3587
+ THE SCOPE MISMATCH IS THE WHOLE PROBLEM, and it is why this
3588
+ exists instead of two more `with` statements in `start_sandboxed`.
3589
+ `askpass.serving` and `secrets.guarded` are BLOCKS; a session is
3590
+ not. `start_sandboxed` returns while the process it started keeps
3591
+ running, so a block around the start closes the window before the
3592
+ connection needs it and a block around the session cannot be
3593
+ written at all. Both one-shot routes got this right and both
3594
+ session routes got it wrong, which is EP6 one layer down: the
3595
+ environment a mode DEPENDS ON was composed at two call sites and
3596
+ only one of them knew.
3597
+
3598
+ THE ASKPASS HALF. `_ssh_auth_options` takes `BatchMode=yes`
3599
+ OFF as soon as anything is stored for the host, because BatchMode
3600
+ suppresses askpass too -- and its docstring records that the
3601
+ anti-hang property moves to `SSH_ASKPASS_REQUIRE=force`, measured
3602
+ as 20s hung versus 0.8s. `start_sandboxed` passed a bare
3603
+ `_ssh_env()`, so a background session on a password-authenticated
3604
+ host got the argv whose anti-hang property is a listener, with no
3605
+ listener. Measured: four askpass variables on the one-shot path
3606
+ and none on the session path, same store, same host.
3607
+
3608
+ THE GUARD HALF. SS60 locks the store on anything that is
3609
+ not "still working normally", and an exception escaping a secret
3610
+ consumer is one of its triggers. The one-shot routes say so
3611
+ themselves (`_run_wsl`) or get it from `serving` (`_run_ssh`); the
3612
+ session route did neither, on the route that holds the plaintext
3613
+ LONGEST. The span wrapped here is the one where the plaintext is
3614
+ in THIS process's hands -- from the start to the end of
3615
+ `_feed_sudo_password` -- which is as narrow as it can be while
3616
+ still being a block.
3617
+
3618
+ WHO CLOSES THE LISTENER. The session does, through
3619
+ `SessionProcess.release_credentials`, on its kill and on the first
3620
+ `poll`/`wait` that sees the process gone. Two backstops behind
3621
+ that: `_Listener` has its own `DEADLINE_S` (120s), so a session
3622
+ nobody ever reaps still stops serving, and `MAX_SERVES` caps the
3623
+ prompts one window may answer.
3624
+ """
3625
+ window = None
3626
+ if askpass_answers:
3627
+ window = askpass.serving(askpass_answers)
3628
+ live = window.__enter__()
3629
+ env = dict(env)
3630
+ env.update(live.env)
3631
+ try:
3632
+ with secrets.guarded(guard_reason) if sudo_secret is not None \
3633
+ else contextlib.nullcontext():
3634
+ proc = _popen_session(
3635
+ args, env=env,
3636
+ stdin=(subprocess.PIPE if sudo_secret is not None
3637
+ else subprocess.DEVNULL))
3638
+ if sudo_secret is not None:
3639
+ _feed_sudo_password(proc, sudo_secret)
3640
+ except BaseException as exc:
3641
+ # `__exit__` rather than `_cleanup`, because the exception is
3642
+ # what locks the store (SS60) and that trigger must survive
3643
+ # the window being hand-held rather than `with`-held.
3644
+ if window is not None:
3645
+ window.__exit__(type(exc), exc, exc.__traceback__)
3646
+ raise
3647
+ return proc, window
3648
+
3649
+
3650
+ class SessionProcess:
3651
+ """A sandboxed command running in the background.
3652
+
3653
+ What the session manager holds: a binary `stdout` to read lines from,
3654
+ `wait`, and `kill`. `kill` is idempotent and BOUNDED -- a polite stop,
3655
+ a grace period, then a forced one -- because H7 says an IO bound that
3656
+ reports a timeout must have stopped the work, and a kill that can hang
3657
+ stops nothing.
3658
+ """
3659
+
3660
+ ran_on = ""
3661
+
3662
+ def __init__(self, proc, *, tier: str, credentials=None,
3663
+ auth_check=None) -> None:
3664
+ self._proc = proc
3665
+ self.tier = tier
3666
+ self._kill_lock = threading.Lock()
3667
+ self._kill_started = False
3668
+ # The live `askpass.serving` window this session owns, or None.
3669
+ # A session outlives the call that started it, so the listener
3670
+ # it authenticated against cannot be scoped to that call
3671
+ # (batch 142). See `_popen_session_with_credentials`.
3672
+ self._credentials = credentials
3673
+ # `(code, first_output) -> None`, or None when this session offered
3674
+ # no stored credential. See `note_exit`.
3675
+ self._auth_check = auth_check
3676
+
3677
+ def note_exit(self, code: Optional[int], first_output: str) -> None:
3678
+ """Hand the quarantine a finished session's exit code and the start
3679
+ of its output (TECHNICAL_DEBT 51, batch 160). Once; idempotent.
3680
+
3681
+ A REFUSED CREDENTIAL WAS QUARANTINED ONLY WHEN A ONE-SHOT COMMAND
3682
+ OFFERED IT. Both matchers read the subprocess's stderr, and a
3683
+ session has none to read: `_popen_session` merges it into stdout so
3684
+ a monitor sees lines in the order they were written, and the stream
3685
+ belongs to the session manager. So a model starting background
3686
+ sessions against a host whose stored password is wrong was exactly
3687
+ "a harness that retried on every command" -- two authentication
3688
+ attempts a call, a lockout at four -- and the protection did not
3689
+ reach it.
3690
+
3691
+ The manager calls this, because the manager holds the stream; the
3692
+ MATCHING stays here, in the two functions the one-shot routes call,
3693
+ so there is one copy of what a refusal looks like. The manager hands
3694
+ over the session's first output and nothing else -- an
3695
+ authentication failure is the first thing a session prints, because
3696
+ nothing else has run yet.
3697
+ """
3698
+ with self._kill_lock:
3699
+ check, self._auth_check = self._auth_check, None
3700
+ if check is not None and code is not None:
3701
+ check(code, first_output)
3702
+
3703
+ @property
3704
+ def stdout(self):
3705
+ return self._proc.stdout
3706
+
3707
+ @property
3708
+ def stdin(self):
3709
+ """The write end, or None for a session started without one --
3710
+ which is every kind but interactive."""
3711
+ return self._proc.stdin
3712
+
3713
+ @property
3714
+ def pid(self) -> int:
3715
+ return self._proc.pid
3716
+
3717
+ @property
3718
+ def returncode(self) -> Optional[int]:
3719
+ return self._proc.returncode
3720
+
3721
+ def poll(self) -> Optional[int]:
3722
+ code = self._proc.poll()
3723
+ if code is not None:
3724
+ self.release_credentials()
3725
+ return code
3726
+
3727
+ def wait(self, timeout: Optional[float] = None) -> Optional[int]:
3728
+ """The exit code, or None if the process is still running when
3729
+ *timeout* runs out."""
3730
+ try:
3731
+ code = self._proc.wait(timeout=timeout)
3732
+ except subprocess.TimeoutExpired:
3733
+ return None
3734
+ self.release_credentials()
3735
+ return code
3736
+
3737
+ def kill(self) -> None:
3738
+ # ONE `finally` ROUND THE WHOLE METHOD, not round the last
3739
+ # wait. `kill` has four exits -- already killed, already
3740
+ # exited, stopped politely, forced -- and the credential
3741
+ # release belongs to all of them. Found by the tests in
3742
+ # batch 142: a session that had already ended kept its
3743
+ # listener, because that path returns before any of the
3744
+ # stopping happens.
3745
+ try:
3746
+ with self._kill_lock:
3747
+ if (self._kill_started
3748
+ or self._proc.poll() is not None):
3749
+ self._kill_started = True
3750
+ return
3751
+ self._kill_started = True
3752
+ self._terminate()
3753
+ try:
3754
+ self._proc.wait(timeout=_KILL_GRACE_S)
3755
+ return
3756
+ except subprocess.TimeoutExpired:
3757
+ pass # it outlived the grace period; forced below
3758
+ self._force()
3759
+ try:
3760
+ self._proc.wait(timeout=_KILL_GRACE_S)
3761
+ except subprocess.TimeoutExpired:
3762
+ logger.warning(
3763
+ "Session process %s outlived a forced kill",
3764
+ self._proc.pid)
3765
+ finally:
3766
+ self.release_credentials()
3767
+
3768
+ def release_credentials(self) -> None:
3769
+ """Close the credential machinery this session owns. Idempotent.
3770
+
3771
+ Called from `kill`, and from the first `poll` or `wait` that
3772
+ sees the process gone, so a session that ENDED BY ITSELF does
3773
+ not leave a listener up until its own deadline. Idempotent
3774
+ because all three can happen, in any order, from more than one
3775
+ thread."""
3776
+ with self._kill_lock:
3777
+ window, self._credentials = self._credentials, None
3778
+ if window is not None:
3779
+ window.__exit__(None, None, None)
3780
+
3781
+ def _terminate(self) -> None:
3782
+ self._proc.terminate()
3783
+
3784
+ def _force(self) -> None:
3785
+ self._proc.kill()
3786
+
3787
+
3788
+ class DockerSessionProcess(SessionProcess):
3789
+ """A session in a container, killed through its runtime by name."""
3790
+
3791
+ ran_on = "container"
3792
+
3793
+ def __init__(self, proc, *, runtime: str, name: str, tier: str) -> None:
3794
+ super().__init__(proc, tier=tier)
3795
+ self.runtime = runtime
3796
+ self.name = name
3797
+
3798
+ def _terminate(self) -> None:
3799
+ # The container, not the CLI client: killing the client does NOT
3800
+ # stop the container under the daemon, which is `_run_docker`'s own
3801
+ # lesson on its timeout path.
3802
+ try:
3803
+ subprocess.run([self.runtime, "kill", self.name], # nosec B603 - kills this session's own container; runtime and name are this module's
3804
+ capture_output=True, timeout=10)
3805
+ except (OSError, subprocess.TimeoutExpired):
3806
+ pass # the runtime is gone or hung; best effort on the way out
3807
+
3808
+
3809
+ class HostSessionProcess(SessionProcess):
3810
+ """A session on the host -- a host read, an inert command with no
3811
+ runtime, or the insecure fallback -- killed as a process GROUP, since a
3812
+ shell's children are what actually do the work (SS15)."""
3813
+
3814
+ ran_on = "host"
3815
+
3816
+ # Both halves live at module level since batch 142, because the
3817
+ # one-shot fallback needs the same reclamation and had its own
3818
+ # weaker answer (batch 142).
3819
+
3820
+ def _terminate(self) -> None:
3821
+ _terminate_tree(self._proc)
3822
+
3823
+ def _force(self) -> None:
3824
+ _force_tree(self._proc)
3825
+
3826
+
3827
+ class WslSessionProcess(SessionProcess):
3828
+ """A session in the distro (ROADMAP_v3 §49, slice 3).
3829
+
3830
+ It inherits `SessionProcess`'s plain terminate/kill and adds NOTHING,
3831
+ which is the measured fact rather than an omission: ending the Windows
3832
+ `wsl.exe` process ends its Linux children, a backgrounded grandchild
3833
+ included. `sleep 987 &` plus a foreground `sleep 986` were both gone two
3834
+ seconds after `Popen.kill()`, checked with `pgrep -a sleep` run as a
3835
+ bare argv -- an earlier attempt asked through `bash -c` and matched its
3836
+ own parent's command line, which reported a survivor that was the
3837
+ question.
3838
+
3839
+ So there is no process group to signal as `HostSessionProcess` must,
3840
+ and no `kill <name>` to send as `DockerSessionProcess` must. Anything
3841
+ added here would be machinery for a case that does not exist.
3842
+ """
3843
+
3844
+ ran_on = "wsl"
3845
+
3846
+
3847
+ class SshSessionProcess(SessionProcess):
3848
+ """A session on a remote host (ROADMAP_v3 §49, slice 4).
3849
+
3850
+ It inherits the plain terminate/kill and adds nothing -- and unlike
3851
+ `WslSessionProcess`, where that was the measured GOOD news, here it is
3852
+ the measured bad news, recorded rather than hidden.
3853
+
3854
+ MEASURED: killing the local `ssh` process does NOT end the remote
3855
+ command. A `sleep 400` on the far side outlived its client every time,
3856
+ because without a pty there is no hangup to deliver to it. `-tt` DOES
3857
+ end it -- and costs the stream: with a pty the remote's stderr is
3858
+ merged into stdout and every newline becomes CRLF, measured, which
3859
+ would silently change what every session and every one-shot command
3860
+ reports. A session whose output shape depends on an unrelated
3861
+ termination decision is the drift EP6 is about.
3862
+
3863
+ So the remote command is bounded by the in-guest `timeout -k` that
3864
+ `_ssh_remote_script` wraps in (measured working with no client alive,
3865
+ rc 124), and a KILL ends the local process and the output stream while
3866
+ the remote command runs on until that backstop fires. That is stated
3867
+ in the tool description and in the kill result rather than papered
3868
+ over -- and a process-group kill on the remote, which would need a
3869
+ second connection and the remote pid, stays an open item in §49's gap
3870
+ register, where it already was.
3871
+ """
3872
+
3873
+ ran_on = "ssh"
3874
+
3875
+
3876
+ def start_sandboxed(
3877
+ command: str,
3878
+ workspace_dir: str,
3879
+ *,
3880
+ profile: CommandProfile,
3881
+ docker_available: bool,
3882
+ timeout_s: int,
3883
+ shell_binary: Optional[str] = None,
3884
+ backend: str = BACKEND_CONTAINER,
3885
+ needs_root: bool = False,
3886
+ ) -> SessionProcess:
3887
+ """Start *command* as a background session and return at once.
3888
+
3889
+ `run_sandboxed`'s twin for a process that outlives the call: the same
3890
+ workspace refusal first, the same route, the same container argv. What
3891
+ differs is what a long-lived process needs -- no stdin, merged output,
3892
+ its own signal group, `--sig-proxy=false` and an in-container `timeout`
3893
+ on the container route, and a CPU limit equal to its own timeout on the
3894
+ host fallback, where a one-shot command's 30 CPU-seconds would kill a
3895
+ session long before its cap (SS15).
3896
+
3897
+ *timeout_s* is the EFFECTIVE timeout, already clamped by the caller.
3898
+ """
3899
+ refusal = protected_paths.check_workspace(workspace_dir)
3900
+ if refusal:
3901
+ raise SandboxUnavailable(refusal)
3902
+ if needs_root:
3903
+ refusal = sudo_refusal(backend)
3904
+ if refusal:
3905
+ raise SandboxUnavailable(refusal)
3906
+ os.makedirs(workspace_dir, exist_ok=True)
3907
+ route = _route(profile, bool(docker_available), backend)
3908
+ sudo_secret = _sudo_secret(backend) if needs_root else None
3909
+ try:
3910
+ if route == ROUTE_WSL:
3911
+ workspace_posix = _wsl_workspace(workspace_dir)
3912
+ if not workspace_posix:
3913
+ raise SandboxUnavailable(
3914
+ _wsl_workspace_refusal(workspace_dir))
3915
+ args = _wsl_argv(
3916
+ command, workspace_posix, argv_mode=(profile.tier == INERT),
3917
+ session_timeout_s=int(timeout_s) + SESSION_TIMEOUT_MARGIN_S,
3918
+ as_root=needs_root)
3919
+ try:
3920
+ proc, _ = _popen_session_with_credentials(
3921
+ args, env=_scrubbed_env(), sudo_secret=sudo_secret,
3922
+ guard_reason="a root command on WSL")
3923
+ except FileNotFoundError:
3924
+ raise SandboxUnavailable(
3925
+ "wsl.exe was not found, so the WSL backend cannot run "
3926
+ "anything.") from None
3927
+ return WslSessionProcess(
3928
+ proc, tier=profile.tier,
3929
+ auth_check=_session_auth_check(
3930
+ BACKEND_WSL, used_ssh_secrets=False,
3931
+ used_sudo_secret=sudo_secret is not None))
3932
+ if route == ROUTE_SSH:
3933
+ args = _ssh_argv(
3934
+ command,
3935
+ session_timeout_s=int(timeout_s) + SESSION_TIMEOUT_MARGIN_S,
3936
+ as_root=needs_root)
3937
+ stored = _ssh_stored_secrets()
3938
+ try:
3939
+ proc, window = _popen_session_with_credentials(
3940
+ args, env=_ssh_env(), sudo_secret=sudo_secret,
3941
+ guard_reason="a root command over SSH",
3942
+ askpass_answers=stored)
3943
+ except FileNotFoundError:
3944
+ raise SandboxUnavailable(
3945
+ f"{_ssh_binary()!r} was not found, so the SSH backend "
3946
+ f"cannot run anything.") from None
3947
+ return SshSessionProcess(
3948
+ proc, tier=profile.tier, credentials=window,
3949
+ auth_check=_session_auth_check(
3950
+ BACKEND_SSH, used_ssh_secrets=bool(stored),
3951
+ used_sudo_secret=sudo_secret is not None))
3952
+ if route == ROUTE_CONTAINER:
3953
+ runtime = known_runtime()
3954
+ _log_image_identity(runtime)
3955
+ name = f"session-{uuid.uuid4().hex[:12]}"
3956
+ args = _docker_argv(
3957
+ command, workspace_dir, profile.network,
3958
+ profile.tier == INERT, runtime, name,
3959
+ session_timeout_s=int(timeout_s) + SESSION_TIMEOUT_MARGIN_S)
3960
+ try:
3961
+ proc = _popen_session(args)
3962
+ except FileNotFoundError:
3963
+ raise SandboxUnavailable(
3964
+ f"The {runtime} CLI was not found. Install Docker or "
3965
+ "Podman, or set allow_insecure_sandbox_fallback: true in "
3966
+ "config.yaml.") from None
3967
+ return DockerSessionProcess(proc, runtime=runtime, name=name,
3968
+ tier=profile.tier)
3969
+ if route in (ROUTE_HOST_READ, ROUTE_INERT_HOST):
3970
+ proc = _popen_session(_inert_argv(command), cwd=workspace_dir,
3971
+ env=_scrubbed_env())
3972
+ return HostSessionProcess(proc, tier=profile.tier)
3973
+ if route == ROUTE_FALLBACK:
3974
+ logger.warning("Using INSECURE subprocess fallback for a "
3975
+ "session: %s", command[:80])
3976
+ proc = _popen_session(
3977
+ [shell_binary or detect_shell(), "-c", command],
3978
+ cwd=workspace_dir, env=_scrubbed_env(),
3979
+ preexec_fn=_unix_resource_limits(cpu_seconds=timeout_s))
3980
+ return HostSessionProcess(proc, tier=profile.tier)
3981
+ except SandboxUnavailable:
3982
+ raise
3983
+ except OSError as e:
3984
+ raise SandboxUnavailable(f"Could not start the command: {e}") from None
3985
+ raise SandboxUnavailable(_unavailable_message(backend))
3986
+
3987
+
3988
+
3989
+ def start_interactive(
3990
+ workspace_dir: str,
3991
+ *,
3992
+ profile: CommandProfile,
3993
+ docker_available: bool,
3994
+ timeout_s: int,
3995
+ prompt_token: str,
3996
+ backend: str = BACKEND_CONTAINER,
3997
+ ) -> SessionProcess:
3998
+ """Open a shell with a pty inside the container and return it at once.
3999
+
4000
+ `start_sandboxed`'s twin for a session the agent TYPES INTO: the same
4001
+ workspace refusal, the same route, the same container argv builder, plus
4002
+ a stdin pipe and the pty wrapper.
4003
+
4004
+ THE CONTAINER ROUTE OR NOTHING (SS28). Every other route is refused with
4005
+ the reason rather than served differently. A pipe-only shell with no pty
4006
+ is not a worse interactive session, it is a DIFFERENT one that the model
4007
+ cannot see is different: no prompt comes back, output is block-buffered
4008
+ until a program exits, and `isatty` sends half the programs worth opening
4009
+ down another path. That gap between what was approved and what runs is
4010
+ the drift class §46 (EP6) and #157 are about, so it is closed by refusing
4011
+ rather than by documenting.
4012
+
4013
+ SLICE 3 DOES NOT CHANGE THAT. WSL was measured holding a pty in §49 and
4014
+ carries `script`, `stty` and the rest, so the wrapper would very likely
4015
+ work -- and "very likely" is the word that made batch 100 expensive. Two
4016
+ of that batch's assumptions about a pty it had NOT measured through the
4017
+ real argv were false, and neither would have been caught by the tests,
4018
+ because both were in what the tests would have been written against. So
4019
+ an interactive session on WSL waits for the batch that measures its
4020
+ stream, and until then asking for one is refused by name.
4021
+
4022
+ There is no *command* argument on purpose: the agent's text is typed into
4023
+ the shell once it is up, so this function's answer does not depend on it.
4024
+ """
4025
+ refusal = protected_paths.check_workspace(workspace_dir)
4026
+ if refusal:
4027
+ raise SandboxUnavailable(refusal)
4028
+ if backend == BACKEND_SSH:
4029
+ raise SandboxUnavailable(
4030
+ "An interactive shell cannot run over SSH. Its stream shape "
4031
+ "there is not the container's: a remote pty is the only way to "
4032
+ "get a prompt back, and a remote pty merges stderr into stdout "
4033
+ "and turns every newline into CRLF -- measured. Use "
4034
+ "shell_background with backend 'ssh' for a command that does "
4035
+ "not need to be typed into, or open an interactive shell "
4036
+ "without asking for SSH.")
4037
+ if backend == BACKEND_WSL:
4038
+ raise SandboxUnavailable(
4039
+ "An interactive shell cannot run in WSL yet. Its stream shape "
4040
+ "there -- the prompt, the echo and the pty's size -- has not "
4041
+ "been measured, and a shell that answers differently in ways "
4042
+ "you cannot see is worse than one you cannot open. Use "
4043
+ "shell_background with backend 'wsl' for a command that does "
4044
+ "not need to be typed into, or open an interactive shell "
4045
+ "without asking for WSL.")
4046
+ os.makedirs(workspace_dir, exist_ok=True)
4047
+ route = _route(profile, bool(docker_available))
4048
+ if route != ROUTE_CONTAINER:
4049
+ raise SandboxUnavailable(
4050
+ "An interactive shell needs a container runtime, and none is "
4051
+ "available. Unlike a one-shot command there is no fallback: a "
4052
+ "shell without a pty would answer differently in ways you could "
4053
+ "not see -- no prompt, output held back until a program exits, "
4054
+ "and programs taking their non-interactive path. Install Docker "
4055
+ "or Podman, or use shell_background for a command that does not "
4056
+ "need to be typed into.")
4057
+ runtime = known_runtime()
4058
+ _log_image_identity(runtime)
4059
+ name = f"session-{uuid.uuid4().hex[:12]}"
4060
+ args = _docker_argv(
4061
+ "", workspace_dir, profile.network, False, runtime, name,
4062
+ session_timeout_s=int(timeout_s) + SESSION_TIMEOUT_MARGIN_S,
4063
+ prompt_token=prompt_token)
4064
+ try:
4065
+ proc = _popen_session(args, stdin=subprocess.PIPE)
4066
+ except FileNotFoundError:
4067
+ raise SandboxUnavailable(
4068
+ f"The {runtime} CLI was not found. Install Docker or Podman.") \
4069
+ from None
4070
+ except OSError as e:
4071
+ raise SandboxUnavailable(
4072
+ f"Could not open the shell: {e}") from None
4073
+ return DockerSessionProcess(proc, runtime=runtime, name=name,
4074
+ tier=profile.tier)
4075
+
4076
+
4077
+ def kill_labelled_containers() -> list[str]:
4078
+ """Kill every container THIS process started that is still running.
4079
+
4080
+ Scoped by `PROCESS_TOKEN`, never by `venastine.sandbox=1`: two harness
4081
+ instances may run at once, and one quitting must not end the other's
4082
+ sessions. A process that never found a runtime started no container,
4083
+ so it asks nothing. Bounded, and failure is logged rather than raised --
4084
+ this runs on the way out.
4085
+ """
4086
+ probe = _runtime_probe
4087
+ if probe is None or probe.name is None:
4088
+ return []
4089
+ runtime = probe.name
4090
+ try:
4091
+ listed = subprocess.run( # nosec B603 - `ps` filtered on this process's own label, to find containers it started
4092
+ [runtime, "ps", "-q", "--filter",
4093
+ f"label=venastine.process={PROCESS_TOKEN}"],
4094
+ capture_output=True, text=True, timeout=10)
4095
+ except (OSError, subprocess.TimeoutExpired):
4096
+ return []
4097
+ if listed.returncode != 0:
4098
+ return []
4099
+ ids = [line.strip() for line in (listed.stdout or "").splitlines()
4100
+ if line.strip()]
4101
+ if ids:
4102
+ try:
4103
+ subprocess.run([runtime, "kill", *ids], capture_output=True, # nosec B603 - kills exactly the ids the runtime printed on the line above
4104
+ timeout=30)
4105
+ except (OSError, subprocess.TimeoutExpired):
4106
+ logger.warning("Could not kill this process's containers %s",
4107
+ ", ".join(ids))
4108
+ return ids