@yahyahammad/venastine 0.1.0

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 (143) hide show
  1. package/.env.example +14 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +14 -0
  4. package/PRIVACY.md +66 -0
  5. package/README.md +878 -0
  6. package/SECURITY.md +88 -0
  7. package/THIRD_PARTY_NOTICES.md +100 -0
  8. package/agents/builtin/compactor.md +75 -0
  9. package/agents/builtin/explore.md +77 -0
  10. package/agents/builtin/grill-me.md +27 -0
  11. package/agents/builtin/initializer.md +94 -0
  12. package/agents/builtin/pipeline-reviewer.md +100 -0
  13. package/agents/builtin/plan.md +88 -0
  14. package/agents/builtin/review.md +74 -0
  15. package/agents/manager.py +195 -0
  16. package/agents/subagent_tool.py +215 -0
  17. package/agents/tui_commands.py +136 -0
  18. package/bin/venastine.mjs +382 -0
  19. package/config.py +1198 -0
  20. package/core/__init__.py +0 -0
  21. package/core/approval.py +115 -0
  22. package/core/client.py +1548 -0
  23. package/core/compaction.py +959 -0
  24. package/core/config_loader.py +1563 -0
  25. package/core/events.py +61 -0
  26. package/core/interaction.py +328 -0
  27. package/core/loop.py +1353 -0
  28. package/core/memory.py +370 -0
  29. package/core/model_windows.py +175 -0
  30. package/core/pipeline_models.py +176 -0
  31. package/core/reasoning/__init__.py +0 -0
  32. package/core/reasoning/authorization.py +130 -0
  33. package/core/reasoning/base.py +219 -0
  34. package/core/reasoning/confidence_scoring.py +468 -0
  35. package/core/reasoning/events.py +149 -0
  36. package/core/reasoning/json_retry.py +219 -0
  37. package/core/reasoning/orchestrator.py +1382 -0
  38. package/core/reasoning/output_writer.py +286 -0
  39. package/core/reasoning/payload_validation.py +398 -0
  40. package/core/reasoning/pipeline_storage.py +361 -0
  41. package/core/reasoning/review.py +615 -0
  42. package/core/reasoning/scholar.py +434 -0
  43. package/core/reasoning/source_corpus.py +327 -0
  44. package/core/reasoning/source_scoring.py +855 -0
  45. package/core/replay.py +167 -0
  46. package/core/session.py +153 -0
  47. package/core/workspace_trust.py +207 -0
  48. package/credentials.py +180 -0
  49. package/database.py +252 -0
  50. package/env_secrets.py +77 -0
  51. package/json_store.py +123 -0
  52. package/logging_setup.py +185 -0
  53. package/main.py +1959 -0
  54. package/mcp_client/__init__.py +15 -0
  55. package/mcp_client/client.py +499 -0
  56. package/mcp_client/config.py +379 -0
  57. package/mcp_client/registration.py +182 -0
  58. package/memories/manager.py +132 -0
  59. package/memories/tui_commands.py +232 -0
  60. package/package.json +73 -0
  61. package/project_init/config_files.py +278 -0
  62. package/project_init/doc_sets.py +330 -0
  63. package/project_init/generator.py +564 -0
  64. package/project_init/manifest.py +406 -0
  65. package/project_init/tui_commands.py +144 -0
  66. package/prompts/__init__.py +0 -0
  67. package/prompts/annotate.md +14 -0
  68. package/prompts/assumption_audit.md +27 -0
  69. package/prompts/claim_extraction.md +34 -0
  70. package/prompts/completeness.md +18 -0
  71. package/prompts/confidence_tiers.md +23 -0
  72. package/prompts/critic_pass.md +24 -0
  73. package/prompts/final_synthesis.md +13 -0
  74. package/prompts/initial_generation.md +14 -0
  75. package/prompts/preliminary_plan.md +23 -0
  76. package/prompts/revalidate.md +25 -0
  77. package/prompts/revise.md +15 -0
  78. package/prompts/source_grounding.md +66 -0
  79. package/prompts/system_prompts.py +262 -0
  80. package/prompts/universal_system_prompt +7 -0
  81. package/prompts/untrusted_content +1 -0
  82. package/providers.json.example +92 -0
  83. package/pyproject.toml +100 -0
  84. package/requirements.txt +72 -0
  85. package/safety/__init__.py +0 -0
  86. package/safety/policy_enforcement.py +682 -0
  87. package/security/__init__.py +0 -0
  88. package/security/capability.py +177 -0
  89. package/security/permissions.py +190 -0
  90. package/security/posture.py +302 -0
  91. package/security/protected_paths.py +309 -0
  92. package/security/sandbox.py +985 -0
  93. package/skills/builtin/crypto/cryptography-verification.md +66 -0
  94. package/skills/builtin/math/formal-specification.md +67 -0
  95. package/skills/builtin/math/numerical-methods.md +66 -0
  96. package/skills/builtin/math/proof-writing.md +61 -0
  97. package/skills/builtin/research/experiment-design.md +62 -0
  98. package/skills/builtin/research/literature-review.md +65 -0
  99. package/skills/builtin/research/reproducibility.md +55 -0
  100. package/skills/builtin/research/source-evaluation.md +70 -0
  101. package/skills/builtin/research/statistical-inference.md +63 -0
  102. package/skills/builtin/research/technical-writing.md +59 -0
  103. package/skills/builtin/security/cybersecurity-research.md +63 -0
  104. package/skills/builtin/software/code-review.md +61 -0
  105. package/skills/builtin/software/debugging.md +61 -0
  106. package/skills/builtin/software/test-design.md +67 -0
  107. package/skills/manager.py +138 -0
  108. package/skills/tui_commands.py +111 -0
  109. package/storage.py +1005 -0
  110. package/tools/base.py +305 -0
  111. package/tools/builtin/__init__.py +0 -0
  112. package/tools/builtin/_math_common.py +377 -0
  113. package/tools/builtin/_net_common.py +61 -0
  114. package/tools/builtin/arxiv.py +223 -0
  115. package/tools/builtin/ask_user.py +213 -0
  116. package/tools/builtin/discrete_math.py +134 -0
  117. package/tools/builtin/fetch_url.py +153 -0
  118. package/tools/builtin/file_ops.py +412 -0
  119. package/tools/builtin/geometry.py +148 -0
  120. package/tools/builtin/get_time.py +20 -0
  121. package/tools/builtin/linear_algebra.py +155 -0
  122. package/tools/builtin/load_skill.py +66 -0
  123. package/tools/builtin/logic.py +96 -0
  124. package/tools/builtin/pin.py +193 -0
  125. package/tools/builtin/probability_stats.py +228 -0
  126. package/tools/builtin/project_docs.py +405 -0
  127. package/tools/builtin/remember.py +158 -0
  128. package/tools/builtin/shell.py +461 -0
  129. package/tools/builtin/symbolic_math.py +119 -0
  130. package/tools/builtin/todo.py +147 -0
  131. package/tools/builtin/web_search.py +151 -0
  132. package/tools/context.py +136 -0
  133. package/tools/isolation.py +314 -0
  134. package/tools/registry.py +897 -0
  135. package/tui/app.py +3423 -0
  136. package/tui/app.tcss +458 -0
  137. package/tui/commands.py +61 -0
  138. package/tui/diffs.py +265 -0
  139. package/tui/preferences.py +182 -0
  140. package/tui/ravens.py +146 -0
  141. package/tui/screens.py +943 -0
  142. package/tui/themes.py +366 -0
  143. package/tui/widgets.py +1239 -0
@@ -0,0 +1,985 @@
1
+ """
2
+ security/sandbox.py
3
+
4
+ Cross-platform command sandboxing with two backends:
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.
10
+
11
+ 2. **Subprocess + hardening** (fallback) — weak isolation. Requires
12
+ explicit opt-in via config.ALLOW_INSECURE_SANDBOX_FALLBACK.
13
+ Filesystem isolation is NOT enforced (absolute paths can escape the
14
+ workspace). Network cannot be restricted. CPU/memory limits are
15
+ Unix-only (rlimit); Windows relies on wall-clock timeout only.
16
+
17
+ 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.
21
+
22
+ This module is intentionally separate from tools/builtin/shell.py so
23
+ that other tools needing safe command execution can reuse it.
24
+ """
25
+
26
+ from __future__ import annotations
27
+
28
+ import functools
29
+ import logging
30
+ import os
31
+ import platform
32
+ import re
33
+ import shlex
34
+ import subprocess
35
+ import uuid
36
+ from typing import Callable, Optional
37
+
38
+ import config
39
+ from security import posture, protected_paths
40
+ from security.capability import (
41
+ CONTAINED,
42
+ UNAVAILABLE,
43
+ UNCONTAINED,
44
+ CommandProfile,
45
+ )
46
+
47
+ logger = logging.getLogger(__name__)
48
+
49
+ # ---------------------------------------------------------------------------
50
+ # ---- Exceptions -----------------------------------------------------------
51
+ # ---------------------------------------------------------------------------
52
+
53
+
54
+ class SandboxUnavailable(Exception):
55
+ """Raised when no sandbox backend is available (Docker not found and
56
+ fallback not enabled)."""
57
+
58
+
59
+ # ---------------------------------------------------------------------------
60
+ # ---- Shell detection ------------------------------------------------------
61
+ # ---------------------------------------------------------------------------
62
+
63
+
64
+ def detect_shell() -> str:
65
+ """Return the shell binary to use inside the sandbox.
66
+
67
+ Respects config.SHELL_BINARY if set. Otherwise auto-detects:
68
+ bash on Linux/macOS, pwsh (or powershell) on Windows.
69
+ """
70
+ if config.SHELL_BINARY:
71
+ return config.SHELL_BINARY
72
+ if platform.system() == "Windows":
73
+ for candidate in ("pwsh", "powershell"):
74
+ try:
75
+ subprocess.run(
76
+ [candidate, "-NoProfile", "-Command", "exit 0"],
77
+ capture_output=True, timeout=5,
78
+ )
79
+ return candidate
80
+ except (FileNotFoundError, subprocess.TimeoutExpired):
81
+ continue
82
+ return "powershell"
83
+ return "bash"
84
+
85
+
86
+ # ---------------------------------------------------------------------------
87
+ # ---- Docker availability --------------------------------------------------
88
+ # ---------------------------------------------------------------------------
89
+
90
+
91
+ @functools.lru_cache(maxsize=1)
92
+ 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.
114
+ """
115
+ 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):
122
+ return False
123
+
124
+
125
+ # ---------------------------------------------------------------------------
126
+ # ---- Command classification -----------------------------------------------
127
+ # ---------------------------------------------------------------------------
128
+
129
+ # The two quotes and the backslash are here for a reason that is NOT
130
+ # "they are shell syntax": this module tokenises a command twice, in two
131
+ # different ways, and they have to agree. This classifier reads raw
132
+ # `.split()` tokens; `_run_inert` execs `shlex.split()` tokens, and shlex
133
+ # CONSUMES all three. So `cat "/etc/passwd"` was ONE token that joined
134
+ # onto the workspace root and read as inside it -- classified INERT,
135
+ # silently auto-approved -- and was then executed as
136
+ # `['cat', '/etc/passwd']` on the host. Audit #157, arriving through the
137
+ # gap between two tokenisers rather than through the gate.
138
+ #
139
+ # Rejecting the character keeps this module's actual soundness argument
140
+ # (reject syntax, never interpret it). Teaching the classifier to unquote
141
+ # would close the same hole by making it the shell parser
142
+ # `_escapes_workspace` explains it must never become.
143
+ #
144
+ # Q1. The backslash arrived a batch later than the quotes, through the
145
+ # same hole and for want of one character in this class. `cat \/etc\/passwd`
146
+ # passed every check here, joined onto the workspace root as one token
147
+ # that read as inside it, and shlex handed `['cat', '/etc/passwd']` to a
148
+ # HOST subprocess -- measured on a POSIX host returning real content, at
149
+ # the shipped "tiered" default. `.\.\/etc/passwd` did it by traversal
150
+ # rather than by absolute path, which is why the leading-backslash
151
+ # spelling is not the whole family.
152
+ #
153
+ # What makes this the LAST character rather than the next in a series:
154
+ # shlex in POSIX mode consumes exactly whitespace, `'`, `"` and `\`, and
155
+ # nothing else. Whitespace splits both tokenisers identically. The other
156
+ # three are now all rejected. So for any command that reaches the inert
157
+ # path, `command.split()` and `shlex.split(command)` are provably the
158
+ # same list -- a closure, not a patch, and pinned as one by
159
+ # `test_the_two_tokenisers_cannot_disagree`.
160
+ _SHELL_METACHARACTERS = re.compile(r"""[;|&$`><(){}!#~'"\\]""")
161
+
162
+ # Dangerous flags for commands that remain in INERT_COMMANDS.
163
+ # Even though find/sort were removed, this denylist provides
164
+ # defense-in-depth for any future additions.
165
+ _DANGEROUS_FLAGS: dict[str, frozenset[str]] = {
166
+ "find": frozenset({"-delete", "-exec", "-execdir", "-ok", "-okdir", "-fprint", "-fprint0", "-fprintf"}),
167
+ "sort": frozenset({"-o", "--output"}),
168
+ "diff": frozenset(), # diff is read-only, no dangerous flags
169
+ }
170
+
171
+
172
+ def _is_inert(command: str) -> bool:
173
+ """True if the command is a read-only inspection command with no
174
+ shell metacharacters, no quoting, no escaping, no path-qualified
175
+ binary, and no dangerous flags — safe to run without full sandbox
176
+ isolation.
177
+
178
+ "No quoting and no escaping" is load-bearing rather than tidy, and
179
+ _SHELL_METACHARACTERS carries the whole reason. A quoted OR escaped
180
+ argument means this function and `_run_inert` disagree about where one
181
+ token ends, and a disagreement between the classifier and the executor
182
+ is a command approved as one thing and run as another.
183
+
184
+ The escape half is the one that took two batches (Q1, Q4). A backslash
185
+ survives every check here as an ordinary character, so
186
+ `cat .\\.\\/etc/passwd` reads as a relative path inside the workspace
187
+ -- and then shlex removes the backslashes and hands the executor
188
+ `../etc/passwd`. Escaping does not need to produce an ABSOLUTE path to
189
+ escape the workspace; it only needs to produce a different one."""
190
+ stripped = command.strip()
191
+ if not stripped:
192
+ return False
193
+ first_word = stripped.split()[0]
194
+ # Reject path-qualified binaries (./ls, /workspace/ls, /tmp/ls).
195
+ # An attacker who can write to the workspace could plant a malicious
196
+ # binary whose basename matches an inert command name.
197
+ if "/" in first_word or "\\" in first_word or first_word.startswith("."):
198
+ return False
199
+ if first_word not in config.INERT_COMMANDS:
200
+ return False
201
+ if _SHELL_METACHARACTERS.search(stripped):
202
+ return False
203
+ # Check for dangerous flags on specific commands
204
+ dangerous = _DANGEROUS_FLAGS.get(first_word)
205
+ if dangerous:
206
+ tokens = stripped.split()
207
+ if any(t in dangerous for t in tokens):
208
+ return False
209
+ return True
210
+
211
+
212
+ def _needs_network(command: str, first_word_only: bool) -> bool:
213
+ """True if *command* names a binary in NETWORK_ALLOWED_COMMANDS.
214
+
215
+ Q2 REVERSES this function's original rule, which read the first word
216
+ only "to prevent a command from granting itself network access via a
217
+ keyword in its arguments". A compound command has more than one
218
+ command position, and the first word was never the whole answer:
219
+ `echo hi && curl http://evil` profiled as network=False on the
220
+ strength of `echo`.
221
+
222
+ That was not an escalation and the reversal is not a fix for one.
223
+ `network` is ONE fact with two consumers (see CommandProfile), so the
224
+ flag the classifier withheld is the flag `_run_docker` read, and the
225
+ whole compound line ran under `--network none` -- the egress was never
226
+ there to take. What was wrong is the CLASSIFICATION: the profile
227
+ asserted "no network" about a call that plainly wanted it, and
228
+ `auto_approved` skipped the human on that basis. It failed the user in
229
+ the other direction too, and that half is the more common one --
230
+ `cd proj && pip install -e .` and `python -m pip install x` have no
231
+ egress today, are never asked about, and so cannot be allowed.
232
+
233
+ *first_word_only* is not a caller preference; it is `_is_inert`, and
234
+ `classify_command` is the only caller. An inert command carries no
235
+ metacharacters, so it CANNOT chain -- its first word is its only
236
+ command position, and scanning its arguments would buy nothing while
237
+ making `grep pip notes.txt` and `grep git notes.txt` prompt. The
238
+ carve-out is the reversal's price, paid where it buys something and
239
+ not where it does not.
240
+
241
+ Known limit, stated because a half-understood control is worse than
242
+ none: a quoted spelling (`bash -c "curl x"`) tokenises as `"curl` and
243
+ does not match. That is the safe direction for the executor -- under-
244
+ granting means `--network none` -- and it is simply a tightening this
245
+ classifier does not get, because it still refuses to parse (G2).
246
+ """
247
+ stripped = command.strip()
248
+ if not stripped:
249
+ return False
250
+ tokens = stripped.split()
251
+ if first_word_only:
252
+ tokens = tokens[:1]
253
+ 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)
256
+
257
+
258
+ # ---------------------------------------------------------------------------
259
+ # ---- Capability classification (ROADMAP_v2 §28) ---------------------------
260
+ # ---------------------------------------------------------------------------
261
+
262
+ # Tier LABELS. Nothing branches on these -- see CommandProfile.tier. They
263
+ # exist so the approval prompt and the record can name what was decided.
264
+ INERT = "INERT" # read-only, every argument inside the workspace
265
+ HOST_READ = "HOST_READ" # read-only, but an argument leaves the workspace
266
+ SANDBOXED = "SANDBOXED" # needs a real backend, no network
267
+ SANDBOXED_NET = "SANDBOXED_NET" # needs a real backend, and gets network
268
+ UNKNOWN = "UNKNOWN" # empty or unparseable
269
+
270
+
271
+ def _within(root: str, token: str) -> bool:
272
+ """Whether *token*, read as a path relative to *root*, stays inside it.
273
+
274
+ Deliberately NOT tools.builtin.file_ops._is_within_workspace, for two
275
+ measured reasons. security/ imports nothing but config and the stdlib
276
+ at runtime -- reaching into tools/ from here would be the first edge
277
+ in that direction and inverts the layering. And file_ops captures
278
+ WORKSPACE_ROOT at IMPORT time, so it cannot follow a workspace that
279
+ the caller passed in, which is the only thing this needs to do.
280
+
281
+ Q3. A token this cannot RESOLVE counts as outside, and the try/except
282
+ is load-bearing rather than defensive. `os.path.realpath` raises on
283
+ Windows for a malformed UNC path -- `OSError: [WinError 668]` on the
284
+ token `\\;` -- and this runs inside `classify_command`, which runs
285
+ inside `registry.approval_needed()`, which is handed the model's
286
+ tool-call input verbatim. There is no handler anywhere above it, so
287
+ `ls \\;` was an unhandled OSError out of the approval gate. That is
288
+ `classify_command`'s own totality requirement ("`command.strip()` on a
289
+ list is an AttributeError escaping the approval check and then the
290
+ loop") failing one layer further down, on a value that IS a string and
291
+ so walks straight past the isinstance guard written for it.
292
+
293
+ False is the only defensible answer: a path the harness cannot resolve
294
+ is not one it can vouch is inside the workspace, and this predicate's
295
+ False means "ask a human", never "deny silently". Found by the
296
+ generative corpus in TestTheTwoTokenisersCannotDisagree, which is what
297
+ a generative corpus is for -- no enumerated list of spellings anyone
298
+ would write was going to contain `\\;`.
299
+ """
300
+ try:
301
+ root = os.path.realpath(root)
302
+ resolved = os.path.realpath(os.path.join(root, token))
303
+ except (OSError, ValueError):
304
+ return False
305
+ return resolved == root or resolved.startswith(root + os.sep)
306
+
307
+
308
+ def _escapes_workspace(command: str, workspace_dir: str) -> bool:
309
+ """Whether any argument of *command* reaches outside the workspace.
310
+
311
+ THIS FUNCTION DOES NOT PARSE, and that is the whole reason it is
312
+ trustworthy (G2). It does not know a flag from an operand, and it must
313
+ not learn: `_is_inert` is sound because it rejects every metacharacter
314
+ rather than understanding one, and a classifier that starts
315
+ interpreting shell syntax is a shell parser whose bugs auto-approve
316
+ things. So every token after the first is read as a path, and a flag
317
+ like `-la` passes only because it is RELATIVE and therefore lands
318
+ inside the workspace on its own -- not because anything recognised it
319
+ as a flag.
320
+
321
+ The corollary, learned the hard way: because this reads RAW tokens,
322
+ every caller has to guarantee the raw tokens are the real ones.
323
+ `_is_inert` does that by rejecting quotes outright. Without it,
324
+ `cat "/etc/passwd"` is one token that lands inside the workspace here
325
+ and two tokens naming the host's file by the time shlex has finished
326
+ with it. Refusing to parse is only sound while nothing downstream
327
+ parses either.
328
+
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.
335
+
336
+ False positives are the designed error direction: `grep /etc/passwd
337
+ notes.txt` searches for a STRING that looks like a path, and it will
338
+ cost one approval prompt. That is the trade that keeps the rule from
339
+ needing to know what grep does.
340
+ """
341
+ for token in command.split()[1:]:
342
+ if not _within(workspace_dir, token):
343
+ return True
344
+ if "=" in token and not _within(workspace_dir, token.split("=", 1)[1]):
345
+ return True
346
+ return False
347
+
348
+
349
+ def classify_command(command: str, workspace_dir: str) -> CommandProfile:
350
+ """Measure *command* into a capability set (ROADMAP_v2 §28, G1).
351
+
352
+ One classification, two consumers: `_shell_approval_check` reads it to
353
+ decide whether to ask, and `run_sandboxed` reads the same object to
354
+ decide how to run it. Before §28 those two asked `_is_inert`
355
+ separately and never compared answers, which is how a command could be
356
+ auto-approved as harmless and then executed on the host (#157).
357
+ """
358
+ # Totality is a REQUIREMENT here, not defensiveness. This runs inside
359
+ # registry.approval_needed(), which is handed the model's tool-call
360
+ # input verbatim -- ShellParams does not validate it until run(),
361
+ # which is after approval. So `command` can be a list, a dict, None,
362
+ # anything the model emitted. Before §28 this was unreachable only
363
+ # because ToolApprovals.shell defaulted True and returned before any
364
+ # of it; flipping that field (G3) made the raw value reach here, and
365
+ # `command.strip()` on a list is an AttributeError escaping the
366
+ # approval check and then the loop.
367
+ #
368
+ # UNKNOWN rather than a raise: the gate's job is to answer, and
369
+ # `measured=False` already means nobody may skip the human.
370
+ if not isinstance(command, str):
371
+ return CommandProfile(
372
+ tier=UNKNOWN, measured=False, escapes_workspace=True,
373
+ writes=True, network=False,
374
+ reason=f"command is {type(command).__name__}, not a string")
375
+
376
+ stripped = command.strip()
377
+ if not stripped:
378
+ return CommandProfile(
379
+ tier=UNKNOWN, measured=False, escapes_workspace=True,
380
+ writes=True, network=False, reason="empty command")
381
+
382
+ # Order matters, and only for Q2: `_needs_network` reads every command
383
+ # position of a compound command and the FIRST WORD ONLY of an inert
384
+ # one, and `_is_inert` is what tells those apart. One call, read twice
385
+ # -- not two calls, which is the shape #157 came from.
386
+ inert = _is_inert(stripped)
387
+ network = _needs_network(stripped, first_word_only=inert)
388
+
389
+ if inert:
390
+ # INERT_COMMANDS is a read-only list and _DANGEROUS_FLAGS guards
391
+ # the entries that have a writing mode, so writes=False here is a
392
+ # claim about the COMMAND. It says nothing about the arguments,
393
+ # which is what the next line is for.
394
+ if _escapes_workspace(stripped, workspace_dir):
395
+ return CommandProfile(
396
+ tier=HOST_READ, measured=True, escapes_workspace=True,
397
+ writes=False,
398
+ network=network,
399
+ reason=(f"reads {stripped.split()[0]!r} with an argument "
400
+ f"outside the workspace, which no container "
401
+ f"can see"))
402
+ return CommandProfile(
403
+ tier=INERT, measured=True, escapes_workspace=False,
404
+ writes=False,
405
+ network=network,
406
+ reason=(f"read-only {stripped.split()[0]!r}, every argument "
407
+ f"inside the workspace"))
408
+
409
+ tier = SANDBOXED_NET if network else SANDBOXED
410
+ return CommandProfile(
411
+ tier=tier,
412
+ measured=True,
413
+ # Not consulted under CONTAINED, and under UNCONTAINED a non-inert
414
+ # command is asked about anyway because writes is True. Measured
415
+ # rather than assumed True so the record says something real.
416
+ escapes_workspace=_escapes_workspace(stripped, workspace_dir),
417
+ writes=True,
418
+ network=network,
419
+ reason=("needs network and a sandbox" if network
420
+ else "not a read-only command, so it needs a sandbox"))
421
+
422
+
423
+ def containment_for(
424
+ profile: CommandProfile, docker_available: bool,
425
+ ) -> str:
426
+ """Which containment the backend that will actually run *profile*
427
+ provides -- the second half of what the gate needs.
428
+
429
+ This mirrors run_sandboxed()'s routing exactly and must keep doing so
430
+ (§46, EP6). The two functions are one decision written twice, and
431
+ #157 is what it costs when they drift: a command auto-approved as
432
+ harmless by one and executed on the host by the other.
433
+
434
+ HOST_READ IS UNCONTAINED AND ALWAYS WILL BE. Its whole definition is
435
+ an argument that resolves outside the workspace, which is exactly
436
+ what a container cannot see -- so there is nothing to route it to.
437
+ `auto_approved` never covers it either (`escapes_workspace` is True),
438
+ so it is the tier that always asks.
439
+
440
+ INERT IS DIFFERENT SINCE §46 (EP5), and the difference is a fact
441
+ about its definition rather than a preference: every argument is
442
+ inside the workspace, and the workspace is the thing the container
443
+ mounts. So the tier the gate AUTO-APPROVES can be the tier that runs
444
+ in a pinned image, instead of running on the host against whatever
445
+ `ls` or `cat` happens to be first on PATH -- which on Windows, where
446
+ none of those binaries exists natively, is a third party's.
447
+
448
+ It falls back to the host when Docker is down, and that is not a
449
+ hole: the approval answer is identical either way. Under CONTAINED
450
+ `auto_approved` returns `not network`, under UNCONTAINED it returns
451
+ `not (escapes_workspace or writes or network)`, and an INERT profile
452
+ has the first two False by construction while
453
+ `INERT_COMMANDS` and `NETWORK_ALLOWED_COMMANDS` do not intersect.
454
+ Pinned by test_shell.py so a word added to either list cannot make
455
+ that quietly untrue.
456
+
457
+ *docker_available* is required rather than probed here. Probing would
458
+ put subprocess IO inside a predicate, and it would move the probe out
459
+ from under the callers that pre-compute it for the TOCTOU thread --
460
+ the same reason run_sandboxed takes it instead of asking.
461
+ """
462
+ if profile.tier == HOST_READ:
463
+ return UNCONTAINED
464
+ if docker_available:
465
+ return CONTAINED
466
+ if profile.tier == INERT:
467
+ return UNCONTAINED
468
+ if posture.current().allow_insecure_fallback:
469
+ return UNCONTAINED
470
+ return UNAVAILABLE
471
+
472
+
473
+ # ---------------------------------------------------------------------------
474
+ # ---- Environment scrubbing ------------------------------------------------
475
+ # ---------------------------------------------------------------------------
476
+
477
+ _SAFE_ENV_KEYS = frozenset({
478
+ "PATH", "HOME", "USERPROFILE", "SYSTEMROOT", "TEMP", "TMP",
479
+ "LANG", "LC_ALL", "TERM", "SHELL", "COMSPEC", "WINDIR",
480
+ })
481
+
482
+
483
+ def _scrubbed_env() -> dict:
484
+ """Return a minimal environment with no API keys or secrets."""
485
+ env = {}
486
+ for key in _SAFE_ENV_KEYS:
487
+ if key in os.environ:
488
+ env[key] = os.environ[key]
489
+ if platform.system() != "Windows":
490
+ env["PATH"] = "/usr/bin:/bin"
491
+ return env
492
+
493
+
494
+ # ---------------------------------------------------------------------------
495
+ # ---- Inert path -----------------------------------------------------------
496
+ # ---------------------------------------------------------------------------
497
+
498
+
499
+ def _run_inert(
500
+ command: str,
501
+ workspace_dir: str,
502
+ _shell_binary: str = "",
503
+ ) -> dict:
504
+ """Run an inert command via subprocess with shell=False (pre-split
505
+ args), scrubbed env, and timeout. No Docker, no fallback needed.
506
+
507
+ _shell_binary is accepted for signature compatibility with the
508
+ other backends but is not used (inert commands don't need a shell).
509
+ """
510
+ try:
511
+ args = shlex.split(command, posix=(platform.system() != "Windows"))
512
+ except ValueError:
513
+ args = command.split()
514
+
515
+ try:
516
+ result = subprocess.run(
517
+ args,
518
+ cwd=workspace_dir,
519
+ env=_scrubbed_env(),
520
+ capture_output=True,
521
+ text=True,
522
+ timeout=config.SANDBOX_TIMEOUT_SECONDS,
523
+ shell=False,
524
+ )
525
+ except subprocess.TimeoutExpired:
526
+ return {
527
+ "stdout": "",
528
+ "stderr": f"Command timed out after {config.SANDBOX_TIMEOUT_SECONDS}s",
529
+ "return_code": -1,
530
+ }
531
+ except FileNotFoundError as e:
532
+ return {"stdout": "", "stderr": f"Command not found: {e}", "return_code": -1}
533
+ except OSError as e:
534
+ # Audit #50's other half. A bad CWD is FileNotFoundError on POSIX
535
+ # but NotADirectoryError (WinError 267) on Windows, which is an
536
+ # OSError and NOT a FileNotFoundError -- so on Windows it escaped
537
+ # this handler entirely and left the module as an unhandled
538
+ # exception. makedirs above removes the usual cause; this stops
539
+ # the next one (a permission error, a path that is a file) being
540
+ # reported as a crash instead of a result.
541
+ return {"stdout": "", "stderr": f"Could not run command: {e}",
542
+ "return_code": -1}
543
+
544
+ return {
545
+ "stdout": result.stdout[:config.MAX_READ_CHARS],
546
+ "stderr": result.stderr[:config.MAX_READ_CHARS],
547
+ "return_code": result.returncode,
548
+ }
549
+
550
+
551
+ # ---------------------------------------------------------------------------
552
+ # ---- Docker path ----------------------------------------------------------
553
+ # ---------------------------------------------------------------------------
554
+
555
+
556
+ @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 "".
559
+
560
+ §46 (EP7). `SANDBOX_DOCKER_IMAGE` is a TAG, and a tag is not an
561
+ identity: anything on the machine may `docker build -t
562
+ python:3.13-slim .` or pull a different digest under the same name,
563
+ and this harness would run inside it without a word. That was the
564
+ shape of the contamination a user suspected when a sandboxed
565
+ command reported a filesystem nobody recognised -- it was not what
566
+ happened that time, and it is still worth being able to see.
567
+
568
+ LOGGED, NOT ENFORCED. Pinning by digest is a separate decision with
569
+ a maintenance cost (somebody has to bump it), while a line in
570
+ app.log naming the ID costs one cached subprocess per process and
571
+ turns a silent substitution into a visible one.
572
+
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
575
+ itself is about to accept.
576
+ """
577
+ try:
578
+ result = subprocess.run(
579
+ ["docker", "image", "inspect", "--format", "{{.Id}}", image],
580
+ capture_output=True, text=True, timeout=10,
581
+ )
582
+ except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
583
+ return ""
584
+ return result.stdout.strip() if result.returncode == 0 else ""
585
+
586
+
587
+ def _log_image_identity() -> None:
588
+ """Say once per process which image the sandbox resolves to (EP7)."""
589
+ image = config.SANDBOX_DOCKER_IMAGE
590
+ resolved = _resolved_image_id(image)
591
+ if _log_image_identity._said:
592
+ return
593
+ _log_image_identity._said = True
594
+ logger.info("Sandbox image %s resolves to %s", image,
595
+ resolved or "an id docker would not report")
596
+
597
+
598
+ _log_image_identity._said = False
599
+
600
+
601
+ def _annotate(result: dict, profile: CommandProfile, ran_on: str) -> dict:
602
+ """Record WHERE a command ran, in the result the model reads (§46, EP4).
603
+
604
+ The gate has always told the HUMAN this -- `_shell_approval_notice`
605
+ says "Runs on the HOST, with your own file access" in as many words
606
+ -- and never told the model anything at all. `run_sandboxed`
607
+ returned stdout, stderr and a return code, so a HOST_READ and a
608
+ contained run were indistinguishable to the only party that then
609
+ writes the user an answer about them.
610
+
611
+ That is not hypothetical. An agent asked what filesystem it was on
612
+ ran `pwd && ls -la` (metacharacters, so: container) and then `cat
613
+ /proc/self/mountinfo` (inert, argument outside the workspace, so:
614
+ host). On Windows `cat` resolves off the host PATH, which on the
615
+ machine in question meant a third party's MSYS2 build, and MSYS2
616
+ SYNTHESISES /proc from its own mount table. The model read a Git
617
+ installation's fstab, believed it was reading the container's, and
618
+ reported to its user that the sandbox was rooted in another
619
+ product's directory and had the whole C: drive bind-mounted in.
620
+ Every alarming sentence in that report was false, and nothing it
621
+ had been given could have told it so.
622
+
623
+ `tier` travels beside `ran_on` because "host" alone under-explains:
624
+ HOST_READ on the host is the design working, while INERT on the
625
+ host means Docker was down. Two facts, so two fields.
626
+
627
+ An `{"error": ...}` from `shell.run()` is deliberately NOT annotated
628
+ -- those paths never executed anything, and a `ran_on` on one would
629
+ claim a run that never happened.
630
+ """
631
+ if not isinstance(result, dict):
632
+ return result
633
+ result["ran_on"] = ran_on
634
+ result["tier"] = profile.tier
635
+ return result
636
+
637
+
638
+ def _venastine_readonly_mount(workspace_real: str) -> list[str]:
639
+ """A nested read-only bind for `.venastine/`, or nothing (§28 G6).
640
+
641
+ `.venastine/` holds mcp.json and the project's agents and skills --
642
+ content that is injected into system prompts and that names commands
643
+ the harness will spawn. D17 gates loading it behind a trust hash; this
644
+ stops a sandboxed command REWRITING it in between.
645
+ /workspace stays writable so builds still work; only the subtree is
646
+ read-only, which Docker resolves by mount depth.
647
+
648
+ Both halves of the condition do work, and neither is padding:
649
+
650
+ nested `.venastine/` resolves from the PROJECT path while the
651
+ sandbox mounts AGENT_WORKSPACE, which defaults to
652
+ `./workspace` -- so in the default layout they are
653
+ SIBLINGS and Docker cannot reach `.venastine` at all. The
654
+ mount only means anything when someone has pointed the
655
+ workspace at a directory that contains one.
656
+
657
+ isdir Docker CREATES a missing bind source, as a root-owned
658
+ directory on the HOST. And is_trusted() returns True when
659
+ `.venastine/` is absent but False once it exists with no
660
+ store entry -- so an unconditional mount would have
661
+ `docker run` conjure a `.venastine/` into the user's
662
+ project and then make the harness prompt them to trust it.
663
+
664
+ Known limits, since a half-understood control is worse than none:
665
+ this covers WRITES on the Docker path only. It does not cover reads,
666
+ the subprocess fallback (which mounts nothing), or the harness's own
667
+ `agents/builtin` when the workspace is the harness repo.
668
+
669
+ AND SINCE §44 IT DOES NOT COVER THE HUB. WS8 moved the project's
670
+ context document out of `.venastine/` to a root `AGENTS.md`, and WS9
671
+ put that file inside D17's content hash -- so the one document this
672
+ docstring named first is now trust-gated content sitting OUTSIDE the
673
+ subtree this mount protects. Dormant rather than live, because
674
+ `config.ToolPermissions.shell` ships False and `is_tool_allowed` reads
675
+ it directly, so nothing reaches the Docker path at all. Recorded here
676
+ rather than fixed: widening the mount to a second bind is a §28 G6
677
+ decision, not a comment repair.
678
+ """
679
+ venastine = os.path.realpath(os.path.join(workspace_real, ".venastine"))
680
+ if not venastine.startswith(os.path.realpath(workspace_real) + os.sep):
681
+ return []
682
+ if not os.path.isdir(venastine):
683
+ return []
684
+ return ["-v", f"{venastine}:/workspace/.venastine:ro"]
685
+
686
+
687
+ def _run_docker(
688
+ command: str,
689
+ 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.
698
+
699
+ *argv* runs the command as a pre-split argument vector instead of
700
+ through ``bash -c`` (§46, EP5). Only INERT commands set it, and
701
+ only they may: `_is_inert` rejects every shell metacharacter, so
702
+ `command.split()` and `shlex.split(command)` are provably the same
703
+ list (Q1/Q5) and there is no shell syntax left to interpret.
704
+ Handing those to bash anyway would insert a third tokeniser between
705
+ the classifier and the executor, and the gap between two of them is
706
+ where #157 arrived, twice.
707
+ """
708
+ workspace_real = os.path.realpath(workspace_dir)
709
+ container_name = f"sandbox-{uuid.uuid4().hex[:12]}"
710
+
711
+ docker_args = [
712
+ "docker", "run", "--rm",
713
+ "--name", container_name,
714
+ # §46 (EP7). Ours, and findable as ours. The name is a uuid, so
715
+ # `docker ps` could not tell a container of ours from any other
716
+ # tool's -- which matters when you are trying to work out
717
+ # whether something on your machine is this harness.
718
+ "--label", "venastine.sandbox=1",
719
+ "-v", f"{workspace_real}:/workspace",
720
+ "-w", "/workspace",
721
+ "--memory", f"{config.SANDBOX_MEMORY_MB}m",
722
+ "--cpus", "1",
723
+ "--pids-limit", str(config.SANDBOX_MAX_PIDS),
724
+ ]
725
+
726
+ if not network:
727
+ docker_args.append("--network")
728
+ docker_args.append("none")
729
+
730
+ docker_args.extend(_venastine_readonly_mount(workspace_real))
731
+ # Kept separate from the line above because the two answer different
732
+ # questions: that one protects a PROJECT's `.venastine/`, this one
733
+ # protects the HARNESS -- its source, and the user-tier state that
734
+ # decides what it trusts and what it spawns. See
735
+ # security/protected_paths.py for the geometry and its limits.
736
+ docker_args.extend(protected_paths.readonly_mounts(workspace_real))
737
+
738
+ docker_args.extend(["-e", "PATH=/usr/bin:/bin:/usr/local/bin"])
739
+ docker_args.append(config.SANDBOX_DOCKER_IMAGE)
740
+ if argv:
741
+ docker_args.extend(shlex.split(command))
742
+ else:
743
+ docker_args.extend(["bash", "-c", command])
744
+
745
+ proc = None
746
+ try:
747
+ proc = subprocess.Popen(
748
+ docker_args,
749
+ stdout=subprocess.PIPE,
750
+ stderr=subprocess.PIPE,
751
+ text=True,
752
+ )
753
+ stdout, stderr = proc.communicate(
754
+ timeout=config.SANDBOX_TIMEOUT_SECONDS,
755
+ )
756
+ return {
757
+ "stdout": stdout[:config.MAX_READ_CHARS],
758
+ "stderr": stderr[:config.MAX_READ_CHARS],
759
+ "return_code": proc.returncode,
760
+ }
761
+ except subprocess.TimeoutExpired:
762
+ # Kill the container explicitly — killing the CLI client
763
+ # (proc.kill()) does NOT stop the container under the daemon.
764
+ try:
765
+ subprocess.run(
766
+ ["docker", "kill", container_name],
767
+ capture_output=True, timeout=10,
768
+ )
769
+ except (FileNotFoundError, subprocess.TimeoutExpired):
770
+ pass
771
+ if proc is not None:
772
+ proc.kill()
773
+ proc.wait()
774
+ return {
775
+ "stdout": "",
776
+ "stderr": f"Command timed out after {config.SANDBOX_TIMEOUT_SECONDS}s",
777
+ "return_code": -1,
778
+ }
779
+ except FileNotFoundError:
780
+ if proc is not None:
781
+ proc.kill()
782
+ proc.wait()
783
+ raise SandboxUnavailable(
784
+ "Docker CLI not found. Install Docker Desktop or enable "
785
+ "ALLOW_INSECURE_SANDBOX_FALLBACK in config.py."
786
+ )
787
+
788
+
789
+ # ---------------------------------------------------------------------------
790
+ # ---- Subprocess fallback path ---------------------------------------------
791
+ # ---------------------------------------------------------------------------
792
+
793
+
794
+ def _unix_resource_limits() -> Optional[Callable[[], None]]:
795
+ """Return a preexec_fn that sets CPU and memory limits via rlimit.
796
+ Returns None on Windows (rlimit not available)."""
797
+ if platform.system() == "Windows":
798
+ return None
799
+
800
+ import resource
801
+
802
+ def _set_limits():
803
+ resource.setrlimit(
804
+ resource.RLIMIT_CPU,
805
+ (config.SANDBOX_CPU_SECONDS, config.SANDBOX_CPU_SECONDS),
806
+ )
807
+ mem_bytes = config.SANDBOX_MEMORY_MB * 1024 * 1024
808
+ resource.setrlimit(resource.RLIMIT_AS, (mem_bytes, mem_bytes))
809
+
810
+ return _set_limits
811
+
812
+
813
+ def _run_subprocess_fallback(
814
+ command: str,
815
+ workspace_dir: str,
816
+ shell_binary: str,
817
+ ) -> dict:
818
+ """Run a command via subprocess with shell interpretation, scrubbed
819
+ env, timeout, and platform-specific resource limits.
820
+
821
+ WARNING: no filesystem isolation — absolute paths can escape the
822
+ workspace. No network restriction. This is the insecure fallback.
823
+ """
824
+ preexec = _unix_resource_limits()
825
+
826
+ try:
827
+ result = subprocess.run(
828
+ [shell_binary, "-c", command],
829
+ cwd=workspace_dir,
830
+ env=_scrubbed_env(),
831
+ capture_output=True,
832
+ text=True,
833
+ timeout=config.SANDBOX_TIMEOUT_SECONDS,
834
+ preexec_fn=preexec,
835
+ shell=False,
836
+ )
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
+ except FileNotFoundError as e:
844
+ return {
845
+ "stdout": "",
846
+ "stderr": f"Shell binary not found: {e}",
847
+ "return_code": -1,
848
+ }
849
+ except OSError as e:
850
+ # See _run_inert: on Windows a bad CWD is NotADirectoryError, not
851
+ # FileNotFoundError, and escaped as an unhandled exception.
852
+ return {
853
+ "stdout": "",
854
+ "stderr": f"Could not run command: {e}",
855
+ "return_code": -1,
856
+ }
857
+
858
+ return {
859
+ "stdout": result.stdout[:config.MAX_READ_CHARS],
860
+ "stderr": result.stderr[:config.MAX_READ_CHARS],
861
+ "return_code": result.returncode,
862
+ }
863
+
864
+
865
+ # ---------------------------------------------------------------------------
866
+ # ---- Public API -----------------------------------------------------------
867
+ # ---------------------------------------------------------------------------
868
+
869
+
870
+ def run_sandboxed(
871
+ command: str,
872
+ workspace_dir: str,
873
+ shell_binary: Optional[str] = None,
874
+ docker_available: Optional[bool] = None,
875
+ profile: Optional[CommandProfile] = None,
876
+ ) -> dict:
877
+ """Execute *command* through the appropriate sandbox backend.
878
+
879
+ Routing:
880
+ 1. Inert command → lightweight subprocess (no Docker/fallback needed)
881
+ 2. Docker available → container with volume mount
882
+ 3. Fallback enabled → subprocess with shell interpretation
883
+ 4. Otherwise → SandboxUnavailable
884
+
885
+ *docker_available* can be pre-computed by the caller (e.g. the
886
+ approval check) to avoid a TOCTOU gap where Docker status changes
887
+ between the approval decision and execution.
888
+
889
+ *profile* is the same thing for the COMMAND: §28 has the approval
890
+ check classify once and hand the result here, so the call that runs
891
+ is the call that was approved. The two parameters stay separate on
892
+ purpose -- a profile says what the command wants, docker_available
893
+ says what the host can give, and merging them would make one of those
894
+ two questions unaskable.
895
+
896
+ Returns ``{"stdout": str, "stderr": str, "return_code": int}``.
897
+ """
898
+ # BEFORE makedirs, and before any backend is chosen. A workspace
899
+ # overlapping the harness's own tree is a configuration error, and
900
+ # CREATING such a directory is already the wrong move. One check here
901
+ # rather than one inside _run_docker, so the inert path and the
902
+ # subprocess fallback -- which mount nothing and would otherwise be
903
+ # exempt by accident -- refuse it too.
904
+ refusal = protected_paths.check_workspace(workspace_dir)
905
+ if refusal:
906
+ raise SandboxUnavailable(refusal)
907
+
908
+ if shell_binary is None:
909
+ shell_binary = detect_shell()
910
+
911
+ # Audit #50: nothing else in the codebase ever created WORKSPACE_DIR,
912
+ # so on a fresh clone it does not exist -- and subprocess raises
913
+ # FileNotFoundError for a missing CWD exactly as it does for a missing
914
+ # executable, so both backends reported "Command not found" / "Shell
915
+ # binary not found" while naming the directory in the same breath.
916
+ # Every other state path in the project is created by whoever needs
917
+ # it; this is the one that had three consumers and no creator.
918
+ os.makedirs(workspace_dir, exist_ok=True)
919
+
920
+ if profile is None:
921
+ profile = classify_command(command, workspace_dir)
922
+
923
+ # HOST_READ names a file the container cannot see, so it has exactly
924
+ # one backend and takes it before Docker is even considered.
925
+ if profile.tier == HOST_READ:
926
+ logger.debug("Host read, using light path: %s", command[:80])
927
+ return _annotate(_run_inert(command, workspace_dir, shell_binary),
928
+ profile, "host")
929
+
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:
936
+ network = profile.network
937
+ logger.debug(
938
+ "Docker path (network=%s): %s", network, command[:80],
939
+ )
940
+ # HERE rather than inside _run_docker, which stays a function
941
+ # that builds an argv and opens one process. Putting a second
942
+ # subprocess in there would put it on the timeout and kill
943
+ # paths too, and it collides with every test that patches Popen
944
+ # to inspect the argv -- subprocess.run goes through Popen.
945
+ _log_image_identity()
946
+ return _annotate(
947
+ _run_docker(command, workspace_dir, shell_binary, network,
948
+ # §46 (EP5). An inert command has no
949
+ # metacharacters by construction, so it needs no
950
+ # shell -- and giving it one would put a THIRD
951
+ # tokeniser between the classifier and the
952
+ # executor, which is the gap #157 came through
953
+ # twice. argv keeps the `shell=False` semantics
954
+ # the light path always had.
955
+ argv=(profile.tier == INERT)),
956
+ profile, "container")
957
+
958
+ # §46 (EP5). Docker is down. An inert command still has somewhere to
959
+ # go -- the light path it used to take unconditionally -- and the
960
+ # approval answer is the same under either containment (see
961
+ # containment_for). What the model is told changes, and that is the
962
+ # point of saying it: `ran_on` reports "host" here.
963
+ if profile.tier == INERT:
964
+ logger.debug(
965
+ "Docker unavailable, inert command on the host: %s",
966
+ command[:80],
967
+ )
968
+ return _annotate(_run_inert(command, workspace_dir, shell_binary),
969
+ profile, "host")
970
+
971
+ if posture.current().allow_insecure_fallback:
972
+ logger.warning(
973
+ "Using INSECURE subprocess fallback: %s", command[:80],
974
+ )
975
+ return _annotate(
976
+ _run_subprocess_fallback(command, workspace_dir, shell_binary),
977
+ profile, "host")
978
+
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 "
983
+ "weaker subprocess fallback (no filesystem isolation, no network "
984
+ "restriction)."
985
+ )