# ADR 0005 — Worker runs inside a macOS Seatbelt sandbox (Q1-A, v2)

Date: 2026-06-11 · Status: accepted

## Launch update

The original decision was macOS-first. The current launch build also supports
Linux through the bubblewrap backend described in `docs/sandboxing.md`: deny-all
network is enforced with a network namespace, writable paths are explicit binds,
and concrete per-domain allowlists fail closed on Linux until an enforceable
proxy namespace path exists.

## Context

v1 gated the worker by *policy*: the worker enforced its own workspace boundary
and the supervisor handed it a strict env allowlist (G2), but nothing
*physically* stopped a worker from writing outside its worktree or opening a
network socket.
The decision record (Q1) committed to making this a real boundary at v2 with
macOS Seatbelt, and to a hard honesty rule: **the docs may only say "physically
can't" once the mechanism actually enforces it.**

## Decision

The supervisor launches the worker under `sandbox-exec` with a per-task SBPL
profile generated by `skep/supervisor/sandbox.py`. The profile is built around a
network **allowlist** (decision D1) even though v1/v2 only ever pass deny-all:
`NetworkPolicy` carries a domain list, `()` ≡ deny-all, and the policy derives
from the task's `permissions.network`.

The profile (last-matching-rule-wins SBPL):

```
(version 1)
(allow default)            ; reads/exec/IPC stay working — the toolchain runs
(deny network*)            ; deny-all outbound (permissions.network = False)
(deny file-write*)         ; then confine writes…
(allow file-write* (subpath "<workspace>") (subpath "<results>") (subpath "<temp>"…))
(allow file-write* (literal "/dev/null") …)
```

The generated profile is written next to the worker log under
`audit/<task_id>/sandbox.profile.sb` — the exact boundary that was enforced is
part of the evidence chain.

## What is physically enforced — and what is not (stated honestly)

- **Enforced:** no outbound network; no file writes outside the workspace, the
  supervisor's result-file dir, and the OS temp roots. Proven by escape tests
  that run `sandbox-exec` for real (write-outside and an outbound socket both
  return EPERM) and by the full smoke + 10/10 reliability suite running the real
  worker under the sandbox with zero toolchain breakage.
- **Not enforced (deliberately, v2):** *read* confinement. The profile uses
  `allow default` for reads so Python/git/pytest keep working; tightening reads
  is out of scope. Env-secret exposure — the high-value read target — is already
  closed by the G2 env allowlist, so the residual risk is a worker reading
  on-disk files it was not handed. Recorded as a gap, not hidden.
- **Not possible in pure Seatbelt:** *per-domain* network allowlists. Seatbelt
  filters by IP/port, not DNS name. A concrete-domain `NetworkPolicy` raises
  `SandboxAllowlistUnsupported` rather than silently failing to enforce; the two
  shapes v2 uses (deny-all, allow-all) are both exact. Per-domain enforcement
  lands with the v3 proxy/container layer (Q1-B), which is also where the D1
  network field stops being effectively deny-all.

## Consequences

- The claim follows the mechanism: docs now say the write/network boundary is
  physically enforced, scoped exactly as above — never broader.
- macOS-first (G3): off macOS, `sandbox.available()` is False and the launch is
  unsandboxed. CI runs on `macos-latest`, so the gate exercises the real
  profile; a non-macOS run is the only place the physical claim does not hold,
  and it is explicit, not silent.
- Re-verification (ADR 0006) reuses the same profile, so the supervisor's own
  patch-re-run is sandboxed too.
