aimpg 0.4.0__tar.gz → 0.4.2__tar.gz

aimpg-0.4.2/.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: test
+on:
+  push:
+    branches: [main, "linux-*"]
+  pull_request:
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.10", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: git config --global user.email ci@example.com && git config --global user.name CI
+      - run: uv run --python ${{ matrix.python }} --group dev pytest -q
+  linux-sandbox:
+    # Replays on Linux: bubblewrap + the AppArmor rule Ubuntu 24.04 needs for bwrap only
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: sudo apt-get update -q && sudo apt-get install -y -q bubblewrap
+      - name: allow user namespaces for bwrap only
+        run: |
+          printf 'abi <abi/4.0>,\ninclude <tunables/global>\n\nprofile bwrap /usr/bin/bwrap flags=(unconfined) {\n  userns,\n  include if exists <local/bwrap>\n}\n' | sudo tee /etc/apparmor.d/bwrap
+          sudo apparmor_parser -r /etc/apparmor.d/bwrap
+      - run: git config --global user.email ci@example.com && git config --global user.name CI
+      - name: an SSH agent for the sandbox to fail to reach
+        run: ssh-agent -a /tmp/aimpg-ci-agent.sock && echo "SSH_AUTH_SOCK=/tmp/aimpg-ci-agent.sock" >> "$GITHUB_ENV"
+      - run: uv run --group dev pytest -q -rs tests/test_sandbox_required.py tests/test_replay_sandbox.py tests/test_replay_e2e.py
+        env:
+          AIMPG_REQUIRE_SANDBOX: "1"

{aimpg-0.4.0 → aimpg-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: aimpg
-Version: 0.4.0
+Version: 0.4.2
 Summary: Real-world energy per solved task for AI coding agents
 Project-URL: Homepage, https://github.com/kumarganduri/aimpg
 Project-URL: Issues, https://github.com/kumarganduri/aimpg/issues
@@ -113,7 +113,7 @@ VERDICT: NOT PROVEN
 ```
 That's the real result on the author's Legwork repo: no saving shown, far from the advertised 60–90%. Your repo may differ, and now you can check.
 
-Every run writes a **record** (`~/.aimpg/verify/*.record.json`) holding versions, both setups, each run's tokens, $ and outcome, and the verdict, but never code, diffs or commit messages. Repo and commits are hashed unless you add `--public`. Anyone can recheck the math for free with `aimpg verify --check record.json`, and rerun a public record on their own machine with `aimpg verify --rerun record.json --repo <clone>`.
+Every run writes a **record** (`~/.aimpg/verify/*.record.json`) holding versions, both setups, each run's tokens, $ and outcome, and the verdict, but never code, diffs or commit messages. Repo and commits are hashed unless you add `--public`. Anyone can recheck the math and the record's consistency for free with `aimpg verify --check record.json` (it can't prove the runs happened), and rerun a public record on their own machine with `aimpg verify --rerun record.json --repo <clone>`, which first shows every command, hook and prompt the record would run and asks before running them. Private records keep only fingerprints (SHA-256) of your prompts, CLAUDE.md, settings and commands, never the text. Records also list every redone attempt and excluded commit.
 
 Same model: the energy test decides (it must hold at every corner of the energy ranges). Different models or agents: cost per solved task decides, because model sizes are secret. A challenger that solves more than 10 points fewer tasks is never "supported". Codex runs are measured from its own logs and priced from OpenAI's published prices. Codex logs in with an OpenAI **API key** (a ChatGPT subscription login can't be used inside the sandbox); the key is written to the run's throwaway folder and deleted when the run ends. Other commands are judged on solve rate and time only.
 
@@ -143,11 +143,11 @@ One row per AI-assisted commit: date, repo, energy range, CO₂ range and cost.
 
 **Energy:** a physical formula, not a price proxy. Prefill compute for new input, one KV-cache re-read per output token (so long contexts cost more), plus datacenter overhead. Model sizes aren't public, so every number is a range. Overheads follow Google's full-stack measurement of a median Gemini prompt (chips, host CPU and memory, idle capacity, cooling ≈ 1.7× the chips alone), and a chat-sized prompt on a mid-size model comes out at 0.017–0.34 Wh, bracketing Google's disclosed 0.24 Wh ([arXiv 2508.15734](https://arxiv.org/pdf/2508.15734)). Sources for every factor are in [`aimpg/factors.json`](aimpg/factors.json), [`aimpg/prices.json`](aimpg/prices.json) and [`aimpg/equivalences.json`](aimpg/equivalences.json).
 
-**Replays:** each run starts from the code just before your commit, in a fresh, history-free copy, inside a macOS sandbox. The only network allowed is the model API, through an allowlisting proxy. Your own tests judge the result, and edited tests are always restored before judging. Every token count is cross-checked against Claude Code's own totals. Details are in [docs/designs/aimpg-design.md](docs/designs/aimpg-design.md).
+**Replays:** each run starts from the code just before your commit, in a fresh, history-free copy, inside a sandbox (Seatbelt on macOS, bubblewrap on Linux). The only network allowed is the model API, through an allowlisting proxy. Your own tests judge the result, and edited tests are always restored before judging. Every token count is cross-checked against Claude Code's own totals. Details are in [docs/designs/aimpg-design.md](docs/designs/aimpg-design.md).
 
 ## Limits (honest list)
 
-- Claude Code and Codex CLI logs are read automatically. Cursor keeps token usage on its servers, so it needs its usage export (below), and that export doesn't say which folder the work was in: give `--cursor-repo` and requests are matched to your next own commit there by time alone (shown as "by time only"). Codex's model prices aren't in the table yet; its requests count toward energy but are listed as unpriced. Replays need macOS and an Anthropic API key (about $0.10–0.30 per run).
+- Claude Code and Codex CLI logs are read automatically. Cursor keeps token usage on its servers, so it needs its usage export (below), and that export doesn't say which folder the work was in: give `--cursor-repo` and requests are matched to your next own commit there by time alone (shown as "by time only"). Replays and `verify` need macOS or Linux and an API key (about $0.10–0.30 per run). On Linux install bubblewrap (`sudo apt install bubblewrap`); Ubuntu 24.04+ also needs a one-time AppArmor rule for bwrap, which aimpg prints if it's missing.
 - Energy is an estimate with a wide range; dollars are close (within about 7% of Claude Code's own session totals on the author's logs).
 - Tips are upper bounds and overlap; they can't be added together.
 - Replays from commit messages alone are hard (12% solved on the author's repo); `--task-mode tests` shows the agent the tests, which makes tasks easier than real work but keeps comparisons fair.

{aimpg-0.4.0 → aimpg-0.4.2}/README.md

@@ -93,7 +93,7 @@ VERDICT: NOT PROVEN
 ```
 That's the real result on the author's Legwork repo: no saving shown, far from the advertised 60–90%. Your repo may differ, and now you can check.
 
-Every run writes a **record** (`~/.aimpg/verify/*.record.json`) holding versions, both setups, each run's tokens, $ and outcome, and the verdict, but never code, diffs or commit messages. Repo and commits are hashed unless you add `--public`. Anyone can recheck the math for free with `aimpg verify --check record.json`, and rerun a public record on their own machine with `aimpg verify --rerun record.json --repo <clone>`.
+Every run writes a **record** (`~/.aimpg/verify/*.record.json`) holding versions, both setups, each run's tokens, $ and outcome, and the verdict, but never code, diffs or commit messages. Repo and commits are hashed unless you add `--public`. Anyone can recheck the math and the record's consistency for free with `aimpg verify --check record.json` (it can't prove the runs happened), and rerun a public record on their own machine with `aimpg verify --rerun record.json --repo <clone>`, which first shows every command, hook and prompt the record would run and asks before running them. Private records keep only fingerprints (SHA-256) of your prompts, CLAUDE.md, settings and commands, never the text. Records also list every redone attempt and excluded commit.
 
 Same model: the energy test decides (it must hold at every corner of the energy ranges). Different models or agents: cost per solved task decides, because model sizes are secret. A challenger that solves more than 10 points fewer tasks is never "supported". Codex runs are measured from its own logs and priced from OpenAI's published prices. Codex logs in with an OpenAI **API key** (a ChatGPT subscription login can't be used inside the sandbox); the key is written to the run's throwaway folder and deleted when the run ends. Other commands are judged on solve rate and time only.
 
@@ -123,11 +123,11 @@ One row per AI-assisted commit: date, repo, energy range, CO₂ range and cost.
 
 **Energy:** a physical formula, not a price proxy. Prefill compute for new input, one KV-cache re-read per output token (so long contexts cost more), plus datacenter overhead. Model sizes aren't public, so every number is a range. Overheads follow Google's full-stack measurement of a median Gemini prompt (chips, host CPU and memory, idle capacity, cooling ≈ 1.7× the chips alone), and a chat-sized prompt on a mid-size model comes out at 0.017–0.34 Wh, bracketing Google's disclosed 0.24 Wh ([arXiv 2508.15734](https://arxiv.org/pdf/2508.15734)). Sources for every factor are in [`aimpg/factors.json`](aimpg/factors.json), [`aimpg/prices.json`](aimpg/prices.json) and [`aimpg/equivalences.json`](aimpg/equivalences.json).
 
-**Replays:** each run starts from the code just before your commit, in a fresh, history-free copy, inside a macOS sandbox. The only network allowed is the model API, through an allowlisting proxy. Your own tests judge the result, and edited tests are always restored before judging. Every token count is cross-checked against Claude Code's own totals. Details are in [docs/designs/aimpg-design.md](docs/designs/aimpg-design.md).
+**Replays:** each run starts from the code just before your commit, in a fresh, history-free copy, inside a sandbox (Seatbelt on macOS, bubblewrap on Linux). The only network allowed is the model API, through an allowlisting proxy. Your own tests judge the result, and edited tests are always restored before judging. Every token count is cross-checked against Claude Code's own totals. Details are in [docs/designs/aimpg-design.md](docs/designs/aimpg-design.md).
 
 ## Limits (honest list)
 
-- Claude Code and Codex CLI logs are read automatically. Cursor keeps token usage on its servers, so it needs its usage export (below), and that export doesn't say which folder the work was in: give `--cursor-repo` and requests are matched to your next own commit there by time alone (shown as "by time only"). Codex's model prices aren't in the table yet; its requests count toward energy but are listed as unpriced. Replays need macOS and an Anthropic API key (about $0.10–0.30 per run).
+- Claude Code and Codex CLI logs are read automatically. Cursor keeps token usage on its servers, so it needs its usage export (below), and that export doesn't say which folder the work was in: give `--cursor-repo` and requests are matched to your next own commit there by time alone (shown as "by time only"). Replays and `verify` need macOS or Linux and an API key (about $0.10–0.30 per run). On Linux install bubblewrap (`sudo apt install bubblewrap`); Ubuntu 24.04+ also needs a one-time AppArmor rule for bwrap, which aimpg prints if it's missing.
 - Energy is an estimate with a wide range; dollars are close (within about 7% of Claude Code's own session totals on the author's logs).
 - Tips are upper bounds and overlap; they can't be added together.
 - Replays from commit messages alone are hard (12% solved on the author's repo); `--task-mode tests` shows the agent the tests, which makes tasks easier than real work but keeps comparisons fair.

aimpg-0.4.2/TODOS.md

@@ -0,0 +1,9 @@
+# TODOS
+
+## Phase 2
+
+The earlier TODOs (test leakage + memorization, statistics gate, network-limit spike) were resolved by the Phase 2 eng review (R3/R4, R7/R15/R16, spikes/egress + spikes/agent).
+
+### ~~Linux replay sandbox~~ (done 2026-10-05)
+bubblewrap backend in aimpg/replay/sandbox.py; the proxy is relayed into the sandbox through a Unix socket. CI's `linux-sandbox` job runs the escape and end-to-end tests on Ubuntu 24.04.
+- **Still untested on Linux:** a real paid Claude Code or Codex run (CI has no API keys); only the stand-in agent has run there.

{aimpg-0.4.0 → aimpg-0.4.2}/aimpg/replay/cli.py

@@ -21,10 +21,11 @@ from aimpg.replay import run as runner
 from aimpg.replay import select, stats
 from aimpg.replay.proxy import AllowlistProxy
 from aimpg.replay import picker
+from aimpg.replay import sandbox
 from aimpg.replay.setups import SETUPS, with_model
 from aimpg.replay.workspace import Layout
 
-ROOT = Path("/private/tmp/aimpg-replay")  # outside $HOME; every agent profile denies it
+ROOT = sandbox.TMP / "aimpg-replay"  # outside $HOME; every agent profile denies it
 STATE = Path.home() / ".aimpg" / "replay"  # selections + results, unreadable to agents
 DEFAULT_MODEL = "claude-sonnet-5-5"
 DEFAULT_SETUPS = "claude-code,claude-code+terse,claude-code+rtk"

{aimpg-0.4.0 → aimpg-0.4.2}/aimpg/replay/fake_agent.py

@@ -53,18 +53,23 @@ def transcript(cfg: Path, cwd: Path, model: str, n: int) -> tuple[dict, dict]:
 
 
 def escape_attempts(cwd: Path, cfg: Path) -> list[str]:
-    """Every attempt that SUCCEEDS is a sandbox bug."""
+    """Every attempt that SUCCEEDS is a sandbox bug.
+
+    Seeing a folder counts only if real content shows: on Linux, home and the
+    runs folder are empty private stand-ins, which is the sandbox working.
+    """
     succeeded = []
     real_home = Path(pwd.getpwuid(os.getuid()).pw_dir)
-    for target in (real_home, real_home / ".ssh", cwd.parent.parent):  # home, keys, sibling runs
+    own_run = cwd.parent.name
+    for target, allowed in ((real_home, set()), (real_home / ".ssh", set()), (cwd.parent.parent, {own_run})):
         try:
-            os.listdir(target)
-            succeeded.append(f"read {target}")
+            if set(os.listdir(target)) - allowed:
+                succeeded.append(f"read {target}")
         except OSError:
             pass
     try:
-        Path("/private/tmp/aimpg-escape-probe").write_text("x")
-        succeeded.append("write /private/tmp")
+        (real_home / "aimpg-escape-probe").write_text("x")
+        succeeded.append("write to home")
     except OSError:
         pass
     probe = subprocess.run(["/usr/bin/curl", "-s", "-m", "5", "-o", "/dev/null", "-w", "%{http_code}", "--noproxy", "*", "https://github.com"], capture_output=True, text=True)

{aimpg-0.4.0 → aimpg-0.4.2}/aimpg/replay/proxy.py

@@ -15,7 +15,11 @@ The allowlist changes per phase:
 from __future__ import annotations
 
 import asyncio
+import shutil
+import sys
+import tempfile
 import threading
+from pathlib import Path
 from dataclasses import dataclass, field
 
 PYPI = frozenset({"pypi.org", "files.pythonhosted.org"})
@@ -33,6 +37,9 @@ class AllowlistProxy:
     port: int = 0
     upstream_port: int = 443  # tests point this at a local echo server
     log: list[tuple[str, str]] = field(default_factory=list)  # ("ALLOW" | "BLOCK", "host:port")
+    # Linux: also a Unix socket, bound into the sandbox (its private network can't reach host ports)
+    socket_path: Path | None = None
+    unix: bool = field(default_factory=lambda: sys.platform.startswith("linux"))
     _loop: asyncio.AbstractEventLoop | None = None
     _thread: threading.Thread | None = None
     _ready: threading.Event = field(default_factory=threading.Event)
@@ -49,6 +56,8 @@ class AllowlistProxy:
             self._loop.call_soon_threadsafe(self._loop.stop)
         if self._thread is not None:
             self._thread.join(5)
+        if self.socket_path is not None:
+            shutil.rmtree(self.socket_path.parent, ignore_errors=True)
 
     def set_allow(self, hosts: frozenset[str]) -> None:
         self.allow = frozenset(hosts)
@@ -65,16 +74,23 @@ class AllowlistProxy:
         asyncio.set_event_loop(self._loop)
         server = self._loop.run_until_complete(asyncio.start_server(self._handle, "127.0.0.1", self.port))
         self.port = server.sockets[0].getsockname()[1]
+        servers = [server]
+        if self.unix:
+            # its own folder: the sandbox gets only this folder, nothing else from /tmp
+            self.socket_path = Path(tempfile.mkdtemp(prefix="aimpg-proxy-", dir="/tmp")) / "proxy.sock"
+            servers.append(self._loop.run_until_complete(asyncio.start_unix_server(self._handle, str(self.socket_path))))
         self._ready.set()
         try:
             self._loop.run_forever()
         finally:
-            server.close()
+            for srv in servers:
+                srv.close()
             pending = [t for t in asyncio.all_tasks(self._loop) if not t.done()]
             for task in pending:
                 task.cancel()
             self._loop.run_until_complete(asyncio.gather(*pending, return_exceptions=True))
-            self._loop.run_until_complete(server.wait_closed())
+            for srv in servers:
+                self._loop.run_until_complete(srv.wait_closed())
             self._loop.close()
 
     async def _handle(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:

{aimpg-0.4.0 → aimpg-0.4.2}/aimpg/replay/run.py

@@ -215,6 +215,7 @@ def _run_agent(commit: Commit, setup: Setup, layout: Layout, cfg: Config, work:
             # the source repo too: it holds the answer, and may live outside $HOME
             deny_roots=[layout.root, Path(commit.repo)],
             proxy_port=proxy.port,
+            proxy_socket=proxy.socket_path,
         )
         res = sandbox.run(
             setup.argv(task_text(commit, cfg.task_mode), cfg.model, cfg.per_run_budget_usd, cfgdir),
@@ -443,6 +444,17 @@ def load_results(path: Path) -> tuple[list[Record], set[str]]:
     return final, excluded
 
 
+def all_attempts(path: Path) -> list[Record]:
+    """Every run line in a results file, including retries and redone runs (for records)."""
+    out = []
+    for line in path.read_text().splitlines():
+        if line.strip():
+            data = json.loads(line)
+            if "excluded_commit" not in data:
+                out.append(Record(**data))
+    return out
+
+
 def make_solution(commit: Commit, dest: Path) -> Path:
     """Tar of the commit's non-test files (fake 'solve' agent only)."""
     tmp = dest.with_suffix(".tree")

aimpg-0.4.2/aimpg/replay/sandbox.py

@@ -0,0 +1,324 @@
+"""macOS Seatbelt sandbox for replay runs.
+
+Read rules adapted from Legwork's hardened profile
+(github.com/kumarganduri/legwork, legwork/sandbox_runner.py `_generate_profile`,
+MIT, same author): reads are allowed outside $HOME (system libraries) but not
+under it; the workdir is re-allowed. Added for replays:
+
+* network only to the local allowlisting proxy port (or none at all);
+* a deny-all replay root, re-allowing only this run's own folders, so parallel
+  runs can't read each other's hidden tests (verified: later, more specific
+  rules win);
+* read-only access to the agent's and toolchain's own install folders under
+  $HOME (Claude Code, uv, node), found by resolving the binaries.
+
+Linux: the same policy through bubblewrap (adapted from Legwork's
+`_bwrap_args`): the system read-only; home folders, /tmp, /var/tmp and /run
+replaced by empty private tmpfs (so other runs, the answer repo and local
+sockets such as the SSH agent are gone); only this run's folders bound back
+writable, the agent's install folders read-only. Every namespace is
+unshared, network included. The allowlisting proxy can't be reached as a
+host port from a private network namespace, so it also listens on a Unix
+socket that is bound in, and a tiny relay inside the sandbox listens on
+127.0.0.1:<the same port> and forwards to it. Ubuntu 24.04+ needs an
+AppArmor profile that lets bwrap (only) create user namespaces; the error
+message prints it.
+
+Other platforms raise SandboxUnavailable.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import os
+import shutil
+import signal
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_MACH_SERVICES = (
+    "com.apple.system.opendirectoryd.libinfo",
+    "com.apple.system.opendirectoryd.membership",
+    "com.apple.system.notification_center",
+    "com.apple.system.logger",
+    "com.apple.logd",
+    "com.apple.diagnosticd",
+    "com.apple.SystemConfiguration.configd",
+    "com.apple.SystemConfiguration.DNSConfiguration",
+    "com.apple.dnssd.service",
+    "com.apple.trustd",
+    "com.apple.trustd.agent",
+    "com.apple.cfprefsd.daemon",
+    "com.apple.cfprefsd.agent",
+)
+# Where replay data lives: outside $HOME on both systems.
+TMP = Path("/private/tmp") if sys.platform == "darwin" else Path("/tmp")
+TOOLS = ("claude", "codex", "uv", "node", "npm", "npx", "git", "rtk")
+
+
+class SandboxUnavailable(RuntimeError):
+    pass
+
+
+def available() -> bool:
+    return unavailable_reason() is None
+
+
+BWRAP_APPARMOR_PROFILE = """abi <abi/4.0>,
+include <tunables/global>
+
+profile bwrap /usr/bin/bwrap flags=(unconfined) {
+  userns,
+  include if exists <local/bwrap>
+}
+"""
+
+
+def unavailable_reason() -> str | None:
+    """Why replays can't be sandboxed here, with the fix; None if they can."""
+    if sys.platform == "darwin":
+        return None if _launcher("sandbox-exec") else "sandbox-exec is missing (it ships with macOS)"
+    if sys.platform.startswith("linux"):
+        if not _launcher("bwrap"):
+            return "replays on Linux need bubblewrap: sudo apt install bubblewrap (or dnf/pacman)"
+        error = _bwrap_probe()
+        if error is None:
+            return None
+        hint = ""
+        try:
+            if Path("/proc/sys/kernel/apparmor_restrict_unprivileged_userns").read_text().strip() == "1":
+                hint = ("\nUbuntu 24.04+ restricts user namespaces with AppArmor; allow them for bwrap only:\n"
+                        "  sudo tee /etc/apparmor.d/bwrap <<'EOF'\n" + BWRAP_APPARMOR_PROFILE + "EOF\n"
+                        "  sudo apparmor_parser -r /etc/apparmor.d/bwrap")
+        except OSError:
+            pass
+        return f"bubblewrap can't create a sandbox here ({error}){hint}"
+    return f"replays need macOS or Linux (not {sys.platform})"
+
+
+@functools.lru_cache(maxsize=None)
+def _launcher(name: str) -> str | None:
+    """Absolute path of the sandbox launcher, looked up in system folders only,
+    never in the child's PATH (which a sandboxed step could plant a fake in)."""
+    found = shutil.which(name, path="/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin")
+    return os.path.realpath(found) if found else None
+
+
+@functools.lru_cache(maxsize=1)
+def _bwrap_probe() -> str | None:
+    try:
+        r = subprocess.run([_launcher("bwrap"), "--unshare-all", "--ro-bind", "/", "/", "--dev", "/dev", "--proc", "/proc", "true"],
+                           stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=15)
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return str(exc)
+    return None if r.returncode == 0 else (r.stderr.strip() or f"exit {r.returncode}")
+
+
+def tool_dirs(tools: tuple[str, ...] = TOOLS) -> list[Path]:
+    """Install folders of the agent/toolchain that live under $HOME (read-only grants).
+
+    For a binary in some `bin/`, its package root (one level up) is granted so
+    node/npm can read their libraries, but never $HOME or ~/.local themselves:
+    uv sits directly in ~/.local/bin, and ~/.local holds other apps' data.
+    """
+    home = Path.home().resolve()
+    too_broad = {home, home / ".local", home / ".local" / "share"}
+    found: set[Path] = set()
+    for name in tools:
+        which = shutil.which(name)
+        if not which:
+            continue
+        for p in (Path(which).absolute(), Path(which).resolve()):
+            d = p.parent
+            if d.name in ("bin", "versions") and d.parent not in too_broad:
+                d = d.parent
+            if str(d).startswith(str(home) + os.sep) and d not in too_broad:
+                found.add(d)
+    uv_python = home / ".local/share/uv/python"
+    if uv_python.is_dir():
+        found.add(uv_python.resolve())
+    return sorted(found)
+
+
+def tool_path(tools: tuple[str, ...] = TOOLS) -> str:
+    """PATH made of the folders the tools are actually invoked from."""
+    dirs: list[str] = []
+    for name in tools:
+        which = shutil.which(name)
+        if which and str(Path(which).parent) not in dirs and str(Path(which).parent) not in ("/usr/bin", "/bin"):
+            dirs.append(str(Path(which).parent))
+    return ":".join(dirs + ["/usr/bin", "/bin", "/usr/sbin", "/sbin"])
+
+
+@dataclass
+class Profile:
+    writable: list[Path]
+    readable: list[Path] = field(default_factory=list)
+    deny_roots: list[Path] = field(default_factory=list)
+    proxy_port: int | None = None  # None: no network at all
+    proxy_socket: Path | None = None  # Linux: the proxy's Unix socket, relayed to 127.0.0.1:proxy_port inside
+
+    def render(self) -> str:
+        home = str(Path.home().resolve())
+        writable = [str(Path(p).resolve()) for p in self.writable]
+        readable = [str(Path(p).resolve()) for p in self.readable]
+        lines = [
+            "(version 1)",
+            "(deny default)",
+            "(allow process-fork)",
+            "(allow process-exec)",
+            "(allow sysctl-read)",
+            "(allow mach-lookup " + " ".join(f'(global-name "{m}")' for m in _MACH_SERVICES) + ")",
+            "(allow iokit-open)",
+            # Codex syncs macOS managed preferences at startup and refuses to run
+            # without them; cfprefsd shares them read-only through this memory.
+            '(allow ipc-posix-shm-read* (ipc-posix-name-prefix "apple.cfprefs"))',
+            "(allow signal (target same-sandbox))",
+            f'(allow file-read* (require-not (subpath "{home}")))',
+        ]
+        for root in self.deny_roots:
+            lines.append(f'(deny file-read* file-write* (subpath "{Path(root).resolve()}"))')
+        for d in readable:
+            lines.append(f'(allow file-read* (subpath "{d}"))')
+        for d in writable:
+            lines.append(f'(allow file-read* file-write* (subpath "{d}"))')
+        for ancestor in sorted(_ancestors([*writable, *readable], [home, *map(str, self.deny_roots)])):
+            lines.append(f'(allow file-read-metadata (literal "{ancestor}"))')
+        lines.append('(allow file-write-data (literal "/dev/null") (literal "/dev/zero"))')
+        if self.proxy_port is not None:
+            lines += ["(allow system-socket)", f'(allow network-outbound (remote ip "localhost:{self.proxy_port}"))']
+        return "\n".join(lines) + "\n"
+
+
+def bwrap_args(profile: Profile, cwd: Path) -> list[str]:
+    """Linux equivalent of Profile.render (see the module docstring)."""
+    home = Path.home().resolve()
+    hidden = sorted({p for p in (Path("/home"), Path("/root"), home) if p.is_dir()}, key=lambda p: len(p.parts))
+    args = [_launcher("bwrap") or "/usr/bin/bwrap", "--unshare-all", "--die-with-parent", "--new-session",
+            "--ro-bind", "/", "/", "--dev", "/dev", "--proc", "/proc",
+            "--tmpfs", "/tmp", "--tmpfs", "/var/tmp", "--tmpfs", "/run"]
+    if os.path.isdir("/var/run") and not os.path.islink("/var/run"):
+        args += ["--tmpfs", "/var/run"]
+    for d in hidden:
+        args += ["--tmpfs", str(d)]
+    for root in profile.deny_roots:  # e.g. the answer repo, wherever it lives
+        r = Path(root).resolve()
+        if r.is_dir() and not any(r == h or h in r.parents for h in (*hidden, Path("/tmp"), Path("/var/tmp"))):
+            args += ["--tmpfs", str(r)]
+    for d in profile.readable:
+        d = Path(d).resolve()
+        if d.exists():
+            args += ["--ro-bind", str(d), str(d)]
+    if profile.proxy_socket is not None:
+        python = Path(sys.base_prefix).resolve()  # the relay runs on this Python's stdlib
+        args += ["--ro-bind", str(python), str(python)]
+        sock_dir = Path(profile.proxy_socket).parent.resolve()
+        args += ["--bind", str(sock_dir), str(sock_dir)]
+    for d in profile.writable:
+        d = Path(d).resolve()
+        args += ["--bind", str(d), str(d)]
+    for d in reversed(hidden):  # stand-in homes read-only: writes fail as on macOS
+        args += ["--remount-ro", str(d)]
+    args += ["--chdir", str(Path(cwd).resolve())]
+    return args
+
+
+# Runs inside the Linux sandbox as `python -c`: 127.0.0.1:PORT -> the proxy's Unix socket.
+_RELAY = """
+import socket, subprocess, sys, threading
+sock_path, port, argv = sys.argv[1], int(sys.argv[2]), sys.argv[4:]
+def pipe(a, b):
+    try:
+        while True:
+            data = a.recv(65536)
+            if not data:
+                break
+            b.sendall(data)
+    except OSError:
+        pass
+    finally:
+        for s in (a, b):
+            try:
+                s.shutdown(socket.SHUT_RDWR)
+            except OSError:
+                pass
+def serve(srv):
+    while True:
+        client, _ = srv.accept()
+        try:
+            up = socket.socket(socket.AF_UNIX)
+            up.connect(sock_path)
+        except OSError:
+            client.close()
+            continue
+        threading.Thread(target=pipe, args=(client, up), daemon=True).start()
+        threading.Thread(target=pipe, args=(up, client), daemon=True).start()
+srv = socket.socket()
+srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+srv.bind(("127.0.0.1", port))
+srv.listen(64)
+threading.Thread(target=serve, args=(srv,), daemon=True).start()
+code = subprocess.call(argv)
+sys.exit(code if code >= 0 else 128 - code)
+"""
+
+
+def _ancestors(paths: list[str], roots: list[str]) -> set[str]:
+    """Parent dirs between a denied root and an allowed path: metadata only, so realpath() works."""
+    out = set()
+    for p in paths:
+        for root in roots:
+            root = str(Path(root).resolve())
+            if p.startswith(root + os.sep):
+                cur = Path(p).parent
+                while str(cur).startswith(root):
+                    out.add(str(cur))
+                    if str(cur) == root:
+                        break
+                    cur = cur.parent
+    return out
+
+
+@dataclass
+class Result:
+    returncode: int | None  # None when timed out
+    stdout: str
+    stderr: str
+    timed_out: bool = False
+
+
+def run(argv: list[str], *, profile: Profile, profile_path: Path, env: dict[str, str], cwd: Path, timeout: float) -> Result:
+    """Run argv inside the sandbox. The whole process group is killed on timeout."""
+    reason = unavailable_reason()
+    if reason:
+        raise SandboxUnavailable(reason)
+    if sys.platform == "darwin":
+        profile_path.write_text(profile.render())
+        full = [_launcher("sandbox-exec"), "-f", str(profile_path), *argv]
+    else:
+        inner = argv
+        if profile.proxy_socket is not None:
+            inner = [str(Path(sys.executable).resolve()), "-I", "-c", _RELAY, str(profile.proxy_socket), str(profile.proxy_port), "--", *argv]
+        full = [*bwrap_args(profile, cwd), "--", *inner]
+        profile_path.write_text(json.dumps(full[:-len(argv)] if argv else full, indent=1))  # audit copy
+    proc = subprocess.Popen(
+        full,
+        cwd=cwd,
+        env=env,
+        stdin=subprocess.DEVNULL,  # Codex waits for "additional input" on an open stdin
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        errors="replace",
+        start_new_session=True,
+    )
+    try:
+        out, err = proc.communicate(timeout=timeout)
+        return Result(proc.returncode, out, err)
+    except subprocess.TimeoutExpired:
+        os.killpg(proc.pid, signal.SIGKILL)
+        out, err = proc.communicate()
+        return Result(None, out, err, timed_out=True)