@namzu/sandbox 1.1.0 → 2.0.1

package/CHANGELOG.md

@@ -1,5 +1,282 @@
 # @namzu/sandbox
 
+## 2.0.1
+
+### Patch Changes
+
+- 4be54ca: Three sandbox and delegation gaps, all of the same kind: something declared,
+  threaded through types, and never driven.
+
+  **`SandboxExecOptions.signal` now works — on the backend where it can.** The
+  option was declared, documented and exported, with a docstring stating that
+  without it "a Stop could only ever abandon the _wait_ — the sandboxed process
+  kept running after the host believed the run had been cancelled". Every
+  backend dropped it, so that is exactly what happened. The local sandbox now
+  merges the caller's signal with the call's own deadline and hands the result to
+  `spawn`, so the child actually dies; a cancelled run is no longer reported as
+  `timedOut`, because a run someone stopped did not run too long, and telling the
+  model otherwise invites a retry with a bigger budget.
+
+  The remote backends still ignore it, now explicitly and with the reason in the
+  source. Their wire has no cancel op, so aborting the request would abandon the
+  wait while the command kept running — the original failure, wearing the
+  appearance of a fix. `SandboxExecOptions.signal` documents which backends
+  honour it.
+
+  **`ls` respects the sandbox.** It read the host through `node:fs` and named
+  `context.sandbox` nowhere, in the one builtin whose whole job is telling the
+  model what exists — so under a container or microVM backend the model's picture
+  of the filesystem was the host's. Its paths were host-relative too, while
+  `read`, `grep` and `glob` all resolve inside the sandbox, so an ls-to-read
+  handoff either failed or opened a different file than the one listed. `glob`
+  had the identical defect, was fixed, and its fix notes that "every sibling
+  builtin already remembers this branch"; this was the sibling that did not.
+
+  One behaviour difference worth knowing: inside a sandbox, directories are
+  derived from file paths, because `listFiles` reports files. An empty directory
+  is invisible there.
+
+  **The `Agent` tool's header described a design that no longer exists.** It told
+  readers to prefer `Agent` because `create_task` was a non-blocking trio driven
+  by notification callbacks. `create_task` blocks and returns the worker's output
+  as its own result, and `continue_task` / `cancel_task` are not registered at
+  all. The two tools are separated by how much of the coordinator surface they
+  bring, not by timing.
+
+## 2.0.0
+
+### Major Changes
+
+- 935b8f3: **Breaking:** `@namzu/sandbox` declares only the backends it has.
+
+  Four of the shapes this package offered could type-check and then throw: a `process` tier, a `passthrough` tier, and two adapters to third-party managed schedulers, none of which was ever written. Each demanded required configuration for a call that was never made — the `self-hosted` microvm arm went further and required three fields belonging to a local-daemon path that does not exist, while the two fields the working path needs were optional. So the only configuration that ran had to supply three values nothing reads, and omitting the two that matter compiled its way to a runtime throw.
+
+  `SandboxTier` is now `container | microvm`. `MicroVMBackendConfig` is one shape whose `orchestratorEndpoint` and `getToken` are required. `SandboxBackendNotImplementedError` stays exported and thrown: a JS host that invents a tier gets a named refusal rather than a provider that confines nothing.
+
+  The `sandbox.platform` health check now asks the provider what this host enforces instead of answering from a table keyed on the OS name. That table had drifted both ways — it called the Linux probe unimplemented long after the provider began probing real flags, and it told a Windows operator that sandboxing is "not supported", which is true of the in-process tier and silent about the container tier that runs there. Every non-passing result now names the missing controls and what to do about them.
+
+  `SANDBOX_ISOLATION_CONTROLS` is exported as a value from `@namzu/sdk`. It was reachable only through `export type *`, so importing it type-checked and then failed on the first line of a built binary.
+
+### Minor Changes
+
+- 935b8f3: The two gaps that were deferred as needing their own design session.
+
+  **A question raised inside a tool is now durable, and the answer reaches
+  the tool that asked.** `ask_user_question` parked through the raw handler
+  under a synthetic `cp_question_<toolUseId>` id that was never written
+  anywhere. The checkpoint did not exist: nothing on disk said a human owed
+  this run an answer, the pending-checkpoint lookup could never return it,
+  and a remote host could not even _observe_ the question except through the
+  in-process callback. Kill the process while somebody is looking at the card
+  and the answer could never be applied — the restore path stripped the whole
+  assistant turn, discarding work that sibling tools in the same batch had
+  already finished, and re-billed the turn.
+
+  The park is now a real checkpoint, with `user_question_asked` /
+  `user_question_answered` on the event stream, `question.asked` /
+  `question.answered` on the SSE wire, and an `input-required` A2A status —
+  the same surfaces a tool-review park has always had.
+
+  The re-entry contract was the deferred half, and it turned out to reuse
+  machinery that already exists. A question checkpoint is written
+  mid-execution, so it holds the assistant turn with its `tool_use` blocks
+  unanswered — the same shape a tool-review park leaves. Re-executing that
+  batch is _how_ the asking tool gets re-entered; a carried-answer registry
+  is what makes the re-entry return the recorded answer instead of parking a
+  second time; and every sibling that already completed is answered from the
+  transcript by the crash-resume recovery, so nothing runs twice. An answer
+  that does not name a call in this turn is refused rather than delivered to
+  whichever tool now holds that slot.
+
+  **The egress policy has a boundary to be enforced at.** Two of its four
+  shapes were honourable nowhere: the container backend refused a host
+  allowlist outright because it had nothing to filter through, so `deny-all`
+  and `allow-all` were the whole spectrum — all or nothing.
+
+  `EgressProxy` enforces the other two. Matching has exactly two forms —
+  exact host, and `.example.com` for a domain and its subdomains — and
+  substring is deliberately not one of them: `host.includes(entry)` would
+  admit `example.com.attacker.net`, and plain suffix matching would admit
+  `notexample.com`. A policy that cannot be read denies, because an allowlist
+  that fails open is not an allowlist. A request addressed to the proxy
+  itself is refused rather than forwarded — found by a test that hung instead
+  of failing, which is exactly the shape that failure takes in production.
+
+  `Sandbox.setNetworkPolicy` narrows or widens a **live** sandbox, so "clone
+  with a token, then drop to deny-all before running untrusted build scripts"
+  is expressible; it was not, because the policy was frozen at provider
+  construction. A backend that cannot enforce it throws.
+
+  And `brokeredCredentials` settles where the token lives. Any credential the
+  agent needed to reach an allowed host had to be inside the sandbox, in the
+  environment, readable by the untrusted code it is meant to be isolated from
+  — via `/proc/self/environ`, or via a prompt injection that exfiltrates it
+  over the very egress the policy permits. The real value is now held
+  host-side and applied at the boundary, scoped per host: a credential
+  attached to every request is a credential handed to whichever host the
+  agent was talked into contacting.
+
+  One limit, stated rather than hidden: a credential cannot be injected into
+  a CONNECT tunnel, because reading those bytes would mean terminating TLS
+  with a CA the sandbox trusts — a strictly larger risk than the one being
+  mitigated. A workload that needs brokering speaks plain HTTP to the proxy
+  and lets it upgrade upstream. The allowlist is enforced on CONNECT either
+  way, since the target names the host in clear text.
+
+- 935b8f3: Two blast-radius controls that were accepted and silently dropped.
+
+  **The standby-pool backend discarded every per-sandbox control.** Its create
+  function took its options parameter underscore-prefixed and never read it,
+  and the request body it assembled carried no resources, no environment
+  variables and no network policy — while the provider faithfully assembled
+  all of them first. A host that set `deny-all` and a 512 MB cap got full
+  outbound network, no memory cap and no process cap, with no error and no
+  warning, from the same call shape that **is** enforced on the sibling
+  container backend. Switching backends silently removed the controls.
+
+  The claim API rejects every property override except a config map, so these
+  genuinely cannot ride through per sandbox — which makes refusing the honest
+  fix rather than a missing feature. It now throws, naming every field it
+  cannot honour rather than the first, and saying where the limits do belong
+  (the container group profile the pool is built from). namzu already held
+  this norm next door, with the rationale in that backend's own comment: a
+  policy accepted and quietly ignored is worse than one that is refused.
+
+  **`allow-all` and `resolver` encoded identically on the microVM backend.**
+  Both resolved to an omitted allowlist, so one encoding carried two opposite
+  intentions — and the `resolve()` callback that produces a tenant-scoped list
+  was never invoked anywhere in the repo. Whichever way the orchestrator reads
+  an omitted field, one of the two was always mis-enforced, and the one that
+  failed **open** was the one whose entire purpose is restriction.
+
+  Each variant now has its own encoding: `allow-all` omits, `deny-all` sends
+  an explicitly empty list, `static` forwards its hosts, and `resolver` calls
+  `resolve()` and forwards the result — including an empty result, which is a
+  real deny-all and not an absence. The switch is exhaustive, so a new variant
+  fails to compile rather than falling through to unrestricted, and a resolver
+  that throws propagates instead of degrading to open.
+
+  The README's backend-by-policy table was wrong in both directions and is now
+  accurate. Neither backend had a test directory; both do now.
+
+### Patch Changes
+
+- 935b8f3: Four defects an adversarial audit confirmed
+
+  **A task could be created and then never found again.** `DiskTaskStore` writes under the run that created it and read only under the store's default run, so every lookup missed as soon as the two differed — the normal case, since the task tools are built with the live run id while a long-lived host constructs the store once with a fixed default. `create` succeeded, `list` succeeded, and `update`, `delete`, `claim` and every dependency link answered "not found" for a task the caller could see. The in-memory store keys by task id alone, which is why nothing caught it.
+
+  **A sub-agent's token reservation was never returned.** The debit at spawn reserves headroom so siblings cannot each be promised the same tokens, and nothing credited back the unused part — so a pool shrank by the full allocation on every spawn no matter what the child used. At a half-pool fraction, ten delegations left a parent with a thousandth of its budget and the next spawn was refused for a budget that had barely been spent. The debit also ran before provisioning, so a spawn rejected for capacity still burned its allocation — the one state change the comment there promised would not happen.
+
+  **A failed sandbox create leaked a proxy holding real credentials.** The egress proxy starts before the container and its only close was in `destroy()`, which a create that never returned can never reach. Every failure in between left a listening server on loopback stamping credential headers, plus a retained event-loop handle, one per retry.
+
+  **A remembered approval could overrule the operator.** The grant check ran before the verification gate and returned, so a remembered approval skipped the gate entirely — and because a tool-scoped grant matches any arguments, approving one harmless invocation authorised every other one, past a rule written to stop exactly that. The gate now runs first, and a grant can satisfy a review but never a denial.
+
+- 935b8f3: Stop dropping tool-failure status on Bedrock, and stop accepting a sandbox
+  egress policy this backend cannot enforce.
+
+  - **Bedrock** flattened every failed tool result into an ordinary success.
+    The executor computed `isError`, the SSE and A2A bridges carried it, and
+    the driver dropped it — even though Converse has a first-class
+    `toolResult.status`. The model's trained tool-failure recovery path keys
+    off that field, so namzu was relying on prose formatting to convey "that
+    call failed".
+
+    Scope note: the five OpenAI-shaped drivers are NOT affected, because
+    Chat Completions has no error field on a tool message at all. The error
+    reaches those models inside the result text, which is the only channel
+    the protocol has.
+
+  - **Docker sandbox** accepted `EgressPolicy` and silently ignored it. A
+    host that set `deny-all` believed the container had no network and it had
+    whatever `network` was configured. A security control that is accepted
+    and ignored is worse than one that does not exist. Now: `deny-all` maps
+    to `--network none` (which Docker enforces natively), `allow-all` keeps
+    the configured network, and `static` / `resolver` **throw** — this
+    backend has no proxy to filter hosts through, and downgrading a
+    restrictive policy to "allow everything" is exactly the failure worth
+    refusing.
+
+  - **Docker sandbox** containers now run with `--cap-drop=ALL` and
+    `--security-opt=no-new-privileges`, plus an opt-in `runAsUser`.
+    `CAP_DAC_OVERRIDE` alone walks past the read-only bind mounts the layout
+    sets up, and without `no-new-privileges` a setuid binary in the image
+    re-escalates.
+
+- 935b8f3: Five places where namzu gave up, or claimed to recover, too early.
+
+  **A transient failure now pauses instead of failing.** A 503 that survived
+  every in-turn recovery — retry with jitter, the one-shot compaction relief,
+  mid-stream salvage — settled the run as `failed`, identically to a bad API
+  key. The host could not tell them apart, and recovering meant knowing about
+  checkpoints and driving replay itself. The state was never the problem:
+  checkpoints are written every iteration by default and the failed run is
+  persisted with full messages. Only the settle and the signal were missing.
+
+  A retryable failure with a checkpoint to resume from now emits `run_paused`
+  naming that checkpoint, leaves the span OK rather than ERROR, and sets
+  `stopReason: 'paused'`. Both conditions are required — pausing on a
+  permanent error would invite a resume that cannot work, and pausing with
+  nowhere to resume from produces a run nobody can ever pick up.
+
+  **A forced compaction pass can no longer decline to do anything.** A forced
+  pass runs because the provider _rejected_ the prompt as too long, and two
+  things let it treat that as advisory. It re-applied the chars/4 estimate
+  after clearing stale tool results — the estimate the provider had just
+  refuted — and returned early if that said the context was fine. And relief
+  reported success on ANY positive shed, so clearing one short result counted
+  and the retry burned a whole model call to be told the same thing. The
+  early return is now force-gated, and a shed has to clear a floor (a
+  fraction of the prompt, at least a couple of thousand characters) to count.
+
+  Separately, the relief latch is per **stuck point**, not per run. It exists
+  to stop a second overflow immediately after a successful compaction from
+  looping; as a run-scoped flag it meant one relief at iteration 3 disarmed
+  the mechanism for the rest of the run, leaving iteration 40 to die with
+  obvious moves left. It is now cleared by a turn that actually succeeded.
+
+  **An eval case can no longer hang the suite.** `executeCase` was a bare
+  await, so a `run` closure that never settled blocked its worker and
+  `runExperiment` never returned — no report, no partial results, nothing to
+  read. `ExperimentConfig.timeoutMs` bounds a case and hands `run` an
+  `AbortSignal` as a third argument; a timed-out case is reported and the
+  suite continues, exactly like a case that threw, with its real elapsed time
+  rather than zero. Unset means no deadline, which is today's behaviour. The
+  documented path already inherits deadlines from the runtime it drives; this
+  covers what those cannot see — a closure that does not go through
+  `query()`, and a mid-iteration provider stall.
+
+  **A malformed content block is named, not smuggled.** One driver built an
+  image block by calling `String()` on whatever `data` and `mediaType`
+  happened to be, behind only a truthiness check — so a non-string `data`
+  became the literal `"[object Object]"` as the base64 payload, and the wire
+  rejected the whole request with nothing naming the block at fault. That is
+  reachable: a remote tool result is cast without validation on the way in.
+  It now type- and media-type-guards and degrades to a named placeholder,
+  matching the sibling driver that already did, and without inlining the
+  payload it refused to send.
+
+  **Failures have somewhere to grow remediation.** A stale API key surfaced
+  as whatever prose the vendor SDK happened to write: no id to grep in logs,
+  no instruction on what to change, and no growth point — a newly-observed
+  failure shape could only be given curated copy by editing the classifier.
+  `explainError` adds an ordered, id-keyed rule layer matching on
+  **structural** signals (code, status, an explicit hint) rather than
+  volatile vendor prose. `run_failed` carries the result as `explanation`;
+  `withHint(err, '…')` lets a throw site attach what only it knows, and
+  outranks every generic rule. It returns `null` when no rule claims the
+  failure — inventing advice for something uncharacterised is worse than
+  saying nothing, because it sends the reader somewhere specific and wrong.
+  The container backend's readiness, port-mapping and worker-fetch failures
+  now carry hints.
+
+- 935b8f3: Close every open code-scanning finding
+
+  **Breaking:** `LocalExecutionContext.executeCommand` no longer interprets its arguments as shell syntax. `shell` defaulted to `true`, and spawning with a shell re-joins the command and its argument array into a single `sh -c` string — so every metacharacter inside an argument became syntax. An `args` array reads argv-safe and was not. The default is now `false`; `shell: true` remains available where a caller genuinely wants a pipeline. A consumer passing `"ls -la"` as one command string, or relying on glob expansion without asking for a shell, must now pass `shell: true`.
+
+  **A sandbox timeout is bounded, and an out-of-range one is refused.** The bash tool's `timeout` argument is a number the model writes, with no ceiling of its own, and it reached both sandbox transports unmodified — so a single call could pin a container or a guest for as long as the platform's timer honours. Both transports now refuse a non-finite, non-positive or over-thirty-minute request rather than clamping it: running under a deadline the caller never chose, and never learns about, is the "accepted and silently not applied" failure this codebase treats as worse than not offering the control at all.
+
+  **Seven quadratic-backtracking regexes are now linear scans**, each on a path an attacker can reach: shell output the agent captured, a tenant-supplied connector URL, a host-supplied workspace root, a model completion, and three endpoint strings that cross the same trust boundary. The worst measured over thirty seconds on a single pathological input, on a shared event loop. Three of the seven were not flagged by the scanner — the same pattern, the same boundary — and were fixed with the rest rather than left to be rediscovered.
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -1,73 +1,98 @@
 # @namzu/sandbox
 
-Pluggable sandbox provider for [`@namzu/sdk`](../sdk). Four tiers,
-each backed by the industrial-standard primitive for that
-deployment shape. Same `SandboxProvider` surface the SDK consumes
-across all of them — swapping tiers is a config change, not an
-integration rewrite.
-
-## Tier matrix (2026 industrial standard)
-
-| Tier | Use case | Primitive | Cold-start | Local dev |
-|---|---|---|---|---|
-| `process` | Agent runs on the developer's own host (Claude Code-style "don't read `~/.ssh`") | bubblewrap (Linux/WSL2) or Seatbelt (macOS), via [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime) | Process spawn (~ms) | Native — no infra |
-| `container` (`docker`) | App in `docker compose` locally or single-tenant prod replica | OCI container, seccomp default profile, tmpfs workdir, no-network default | 0.5–2s | `docker compose up` |
-| `container` (`runsc`) | Trusted-tenant SaaS — what OpenAI Code Interpreter and [Modal](https://modal.com/blog/gvisor-savings-article) ship | Google [gVisor](https://gvisor.dev/docs) userspace kernel as Docker runtime | container start + ~100ms | Linux Docker only (no Docker Desktop on macOS) |
-| `microvm` (`e2b`) | Adversarial multi-tenant SaaS, Python-REPL workloads | Firecracker microVM via [E2B](https://e2b.dev/docs/sandbox) managed service | ~150ms (snapshot/restore) | E2B API key from any laptop |
-| `microvm` (`fly-machines`) | Adversarial multi-tenant SaaS, arbitrary tool-call workloads | Firecracker microVM via [Fly Machines](https://fly.io/docs/machines) | 250ms–1s | Fly API token from any laptop |
-| `microvm` (`self-hosted`) | Same threat model, host insists on owning the scheduler | [`firecracker-containerd`](https://github.com/firecracker-microvm/firecracker-containerd) on KVM-enabled Linux | <300ms with snapshot restore | Lima/Colima Linux VM on macOS |
-| `passthrough` | Tests and explicitly trusted environments | Direct host process — no isolation | n/a | n/a |
-
-## Why these tiers (and not others)
-
-The 2026 consensus across production agent platforms (AWS
-Lambda/Fargate, Fly Machines, Replit, E2B, Modal, OpenAI Code
-Interpreter, Anthropic Code Execution, Daytona) bifurcates cleanly
-along the **trust boundary**:
-
-- **Adversarial multi-tenant code execution → Firecracker microVMs.**
-  AWS, Fly, Replit, E2B, Daytona all converged here. The argument
-  is in [Fly's "Sandboxing and Workload Isolation"](https://fly.io/blog/sandboxing-and-workload-isolation)
-  and the [original Firecracker paper](https://www.usenix.org/conference/nsdi20/presentation/agache):
-  KVM-backed VMs are the only mainstream primitive with a
-  kernel-level trust boundary, and `jailer` plus snapshot/restore
-  makes them boot in 125ms.
-- **Trusted-tenant or first-party workloads → gVisor.** Google's
-  GKE Sandbox, Modal, OpenAI Code Interpreter run gVisor's `runsc`.
-  Near-zero cold-start, runs on commodity Linux without nested
-  virt. Tradeoff: a userspace-kernel CVE is a tenant escape; a
-  Firecracker CVE generally is not.
-- **Single-user dev workstation → bubblewrap / Seatbelt.** What
-  Anthropic itself ships with Claude Code via
-  `@anthropic-ai/sandbox-runtime`. The threat model is "don't let
-  the agent read `~/.ssh` or run `rm -rf ~`," not "tenant A vs
-  tenant B." Process-spawn cold-start.
-- **Single-tenant or co-trusted tenants → plain Docker + seccomp.**
-  Northflank, Railway, Render, Compass-platform, GitHub Actions
-  runners. Adequate when the model is your model and the user is
-  your customer; insufficient when the prompt is the attacker.
-
-`@namzu/sandbox` exposes all four as separate tiers so the host
-picks the trust boundary that matches its threat model.
-
-**What we deliberately do NOT build** is yet-another Firecracker
-scheduler. That is E2B's and Fly's entire product, and writing
-our own would be a years-long detour. We adapt to theirs and
-reserve the `self-hosted` option for hosts that need to own the
-scheduler for compliance or air-gap reasons.
+Pluggable containment for [`@namzu/sdk`](../sdk). Two tiers, one
+`SandboxProvider` surface: swapping the trust boundary is a config
+change, not an integration rewrite.
+
+## Tiers
+
+| Tier | Trust boundary | Use it when | Cold start |
+|---|---|---|---|
+| `container` (`docker`) | Kernel namespaces + seccomp, tmpfs workdir, no network unless asked | The model is yours and the user is your customer | 0.5–2s |
+| `container` (`runsc`) | A userspace kernel serves the guest's syscalls | Same tenancy, stronger boundary, commodity Linux without nested virtualization | container start + ~100ms |
+| `container` (`aci-standby-pool`) | The managed provider's isolation host | You cannot reach a container daemon, and a ~1.5s claim is acceptable | ~1.5s from a warm pool |
+| `microvm` (`self-hosted`) | Hardware virtualization | The prompt itself is the attacker | <300ms, resuming a snapshot |
+
+Every shape above is implemented. That is worth stating because it
+used not to be: this package once advertised four tiers and six
+backends, and four of those shapes type-checked and then threw. A
+configuration that compiles and cannot run teaches the reader the
+wrong thing about what is here, so the ones that were never built
+are gone rather than pending.
+
+## Choosing a tier
+
+The question is not which tier is strongest, it is **who you are
+defending against**.
+
+- **The prompt is the attacker** — untrusted input reaching code
+  execution, or tenants who must not reach each other. Take the
+  hardware boundary: a guest kernel per task is the only mainstream
+  primitive whose escape surface is the hypervisor rather than a
+  shared kernel, and snapshot-resume makes starting one cost
+  milliseconds rather than seconds.
+- **The tenant is trusted, the code is not** — your own model, your
+  own users, arbitrary tool calls. A userspace kernel is the good
+  trade: near-zero cold start on commodity Linux, at the cost that a
+  bug in that kernel is a tenant escape where a hypervisor bug
+  usually is not.
+- **Single tenant, or tenants who already trust each other** —
+  namespaces and a seccomp profile are adequate, and they run
+  everywhere with no special runtime.
+- **One operator on their own machine** — the threat is the agent
+  reading `~/.ssh`, not tenant A reading tenant B. That is the SDK's
+  local sandbox provider, not this package.
+
+namzu does not build a microVM scheduler. Starting guests fast and
+safely is an entire product on its own, and the boundary a guest
+gives is the same whoever started it — so the microvm tier is an
+interface to a scheduler, and the one it speaks to is namzu's own.
 
 ## Cloud portability
 
-The interface is cloud-agnostic. `docker` works on every cloud,
-`e2b` and `fly-machines` are managed services not tied to any
-cloud, `runsc` and `firecracker:self-hosted` need infrastructure
-the host chooses (GKE Sandbox, AWS Fargate, self-hosted KVM, etc.).
-Picking a stronger backend may imply picking a different cloud —
-that's the host's call, not the SDK's.
+The interface carries no cloud in it. The container tier over a
+local daemon runs anywhere; the managed-pool runtime and the microvm
+tier need infrastructure the host chooses. Picking a stronger
+boundary may imply picking different infrastructure — that is the
+host's call, not the SDK's.
 
 ## Egress allowlist policy
 
-Every backend supports the same `EgressPolicy` shape:
+Every backend accepts the same `EgressPolicy` shape, but they do **not**
+all enforce every variant, and a backend that cannot enforce one now
+throws instead of quietly ignoring it:
+
+| Backend | `deny-all` | `allow-all` | `static` | `resolver` |
+|---|---|---|---|---|
+| `container:docker` | enforced (`--network none`) | enforced | **throws** — no proxy to filter through | **throws** |
+| `container:standby-pool` | **throws** | **throws** | **throws** | **throws** |
+| `microvm:firecracker` | enforced (empty allowlist) | enforced (no allowlist) | enforced | enforced — `resolve()` is called and its result forwarded |
+
+Two rows carry the same lesson from opposite directions.
+
+The docker row used to accept a restrictive policy and silently grant the
+configured network, which is worse than not supporting the feature: the
+host believes it is protected and stops looking. Refusing loudly is the
+only honest option for a control the backend cannot implement.
+
+The standby-pool row is the same failure found later. Its claim API rejects
+every property override except a config map, so a memory cap, a process
+cap, environment variables and an egress policy have nowhere to ride
+through — and all four were accepted and dropped. Set them on the container
+group profile the pool is built from; the backend now refuses them per
+sandbox rather than pretending.
+
+The firecracker `resolver` column is a third variant of it. `allow-all` and
+`resolver` both used to encode as an omitted allowlist, so one encoding
+carried two opposite intentions and the callback that produces the
+tenant-scoped list was never called anywhere. Whichever way the
+orchestrator reads an omitted field, one of the two was always
+mis-enforced — and the one that failed **open** was the one whose entire
+purpose is restriction. Each variant now has its own encoding: `allow-all`
+omits, `deny-all` sends an explicitly empty list, `resolver` sends what
+`resolve()` returned.
+
+The shape itself:
 
 ```ts
 type EgressPolicy =
@@ -86,63 +111,138 @@ avoids the "where does the resolver get its context from"
 plumbing problem; the host owns the closure, the SDK runtime
 doesn't have to forward identity through `provider.create`.
 
+## Container confinement (`container:docker`)
+
+Every container is launched with:
+
+- `--cap-drop=ALL` — `CAP_DAC_OVERRIDE` alone walks past the read-only bind
+  mounts the layout sets up, so the default capability set makes the mount
+  layout advisory rather than enforced.
+- `--security-opt=no-new-privileges` — without it a setuid binary in the
+  image re-escalates after the drop.
+- `--network none` by default (see the egress table above).
+
+There is deliberately **no re-add list** for capabilities. A workload that
+genuinely needs one should say so somewhere a reviewer sees it, not inherit
+it from a default.
+
+`runAsUser` (`--user`) is opt-in rather than defaulted, because the correct
+uid depends on the image's own filesystem ownership and forcing one breaks
+every image that expects root at startup. Set it whenever the image
+supports a non-root user — a container running as root is one bind-mount
+misconfiguration away from writing the host.
+
 ## Status
 
-This package is being built out across the `ses_004-native-agentic-runtime-and-sandbox`
-design session in phases. Each phase ships one tier, fully
-implemented + tested + documented:
-
-- ✅ **P3.0** — Public surface (this commit). Backend interfaces,
-  tier discriminator, egress policy. Factory throws
-  `SandboxBackendNotImplementedError` until backends land.
-- ⏳ **P3.1** — `container:docker` backend. Universal local-dev
-  default; ships first.
-- ⏳ **P3.2** — `EgressPolicy` plumbing + reference egress proxy
-  (compass-platform pattern: HTTP CONNECT tunnel + JWT-claim
-  allowlist).
-- ⏳ **P3.3** — `microvm:e2b` and `microvm:fly-machines` adapters.
-  Phase 2 production tier.
-- ⏳ **P3.4** — `process` backend (Anthropic sandbox-runtime
-  adapter — bubblewrap/Seatbelt).
-- ⏳ **P3.5** — `container:runsc` (gVisor) and
-  `microvm:self-hosted` (firecracker-containerd). Phase 3
-  adversarial-multi-tenant.
-
-The interface here is what every backend implements; the staged
-rollout is purely about turning each tier on, not about reshaping
-the contract.
-
-## Usage (post-implementation)
+Every backend this package declares is implemented, and
+`createSandboxProvider` refuses anything else BY NAME at construction
+rather than handing back a provider that confines nothing — so a
+mistake surfaces while the host is wiring, not mid-run.
+
+## Usage
 
 ```ts
 import { createSandboxProvider } from '@namzu/sandbox'
 
-// Phase 1: ship now, works on every dev's laptop
-const sandbox = createSandboxProvider({
+// A container per task, on a local daemon. Runs anywhere.
+const contained = createSandboxProvider({
   backend: { tier: 'container', runtime: 'docker', image: 'namzu-worker:latest' },
-  defaultEgress: { kind: 'static', allowedHosts: ['api.openai.com', 'api.anthropic.com'] },
+  layout,
+  defaultEgress: { kind: 'static', allowedHosts: ['api.example.com'] },
 })
 
-// Phase 2: production, adversarial multi-tenant, managed Firecracker
-const sandbox = createSandboxProvider({
-  backend: { tier: 'microvm', service: 'e2b', apiKey: process.env.E2B_API_KEY! },
-  defaultEgress: {
-    kind: 'resolver',
-    resolve: async () => fetchAllowlistForTenant(tenantId),
-  },
-})
-
-// Phase 3: adversarial multi-tenant, self-hosted Firecracker on KVM
-const sandbox = createSandboxProvider({
+// A guest per task, when the prompt itself is the attacker. The
+// allowlist is resolved per tenant, so the boundary is not fixed at
+// construction.
+const virtualized = createSandboxProvider({
   backend: {
     tier: 'microvm',
     service: 'self-hosted',
-    firecrackerBinary: '/usr/local/bin/firecracker',
-    kernelImage: '/var/lib/namzu/vmlinux',
-    rootfsImage: '/var/lib/namzu/rootfs.ext4',
+    orchestratorEndpoint: 'https://sandbox-control.internal',
+    getToken: async () => mintOrchestratorBearer(),
+    template: 'golden-rev-7',
+  },
+  defaultEgress: {
+    kind: 'resolver',
+    resolve: async () => fetchAllowlistForTenant(tenantId),
   },
 })
 
 // Wire into drainQuery / agent run config:
-//   sandboxProvider: sandbox
+//   sandboxProvider: contained
 ```
+
+## The egress boundary
+
+An egress policy could be *declared* long before it could be *enforced*.
+Only two of its four shapes were honourable anywhere: this backend refused
+a host allowlist outright because it had nothing to filter through, and
+only the microVM backend forwarded one. `deny-all` and `allow-all` were
+the whole spectrum a container-tier sandbox could express — all or nothing.
+
+`EgressProxy` is the boundary the other two shapes are enforced at. When a
+policy is `static` or `resolver`, the backend starts one on host loopback
+and points the container at it through `HTTP_PROXY` / `HTTPS_PROXY` (both
+spellings, because tooling is split between them and a workload reading
+only the missing one would bypass the boundary while looking like the
+policy worked).
+
+Matching has exactly two forms, and substring is deliberately not one of
+them:
+
+| Entry | Matches |
+| --- | --- |
+| `api.example.com` | that host only |
+| `.example.com` | that domain and any subdomain |
+
+`host.includes(entry)` is the obvious implementation and it is a hole: an
+entry of `example.com` would admit `example.com.attacker.net`, a domain
+the attacker owns. Plain suffix matching has the same hole without the
+leading dot — `notexample.com` ends with `example.com` — which is why the
+wildcard form requires it. Comparison ignores case and a trailing dot,
+because DNS does and an allowlist that did not would be bypassable by
+typing the host differently.
+
+A policy that cannot be read **denies**. An allowlist that fails open is
+not an allowlist.
+
+### Changing the policy while the sandbox runs
+
+`sandbox.setNetworkPolicy({ allowedHosts })` narrows or widens a live
+sandbox. The shape this exists for — "clone with a token, then drop to
+deny-all before running anything the repository contains" — was not
+expressible at all: the policy was frozen at provider construction, so a
+host had to build a second provider and a second sandbox and copy the work
+across.
+
+A backend that cannot enforce it **throws**. A network policy accepted and
+not applied is worse than one never offered: the caller stops looking, and
+the run proceeds believing it is confined.
+
+### Credentials that never enter the sandbox
+
+Any token the agent needed to reach an allowed host had to be inside the
+container, in the environment — readable by the untrusted code it is meant
+to be isolated from, via `/proc/self/environ`, or via a prompt injection
+that exfiltrates it over the very egress the policy permits.
+
+`brokeredCredentials` holds the real value host-side and stamps it on at
+the boundary, scoped per host:
+
+```ts
+brokeredCredentials: [
+  { host: 'api.example.com', header: 'authorization', value: process.env.TOKEN! },
+]
+```
+
+Per host, not globally: a credential attached to every request is a
+credential handed to whichever host the agent was talked into contacting.
+
+One honest limit. A credential **cannot** be injected into a CONNECT
+tunnel — by the time those bytes reach the proxy they are encrypted, and
+reading them would mean terminating TLS with a CA the sandbox trusts, which
+would let the proxy read every byte the agent sends anywhere. That is a
+strictly larger risk than the one being mitigated, so it is not built. A
+workload that needs brokering speaks plain HTTP to the proxy and lets it
+upgrade to HTTPS upstream. The allowlist is still enforced on CONNECT,
+because the target names the host in clear text.

package/dist/backends/aci-standby-pool/__tests__/unenforceable-controls.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=unenforceable-controls.test.d.ts.map

package/dist/backends/aci-standby-pool/__tests__/unenforceable-controls.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unenforceable-controls.test.d.ts","sourceRoot":"","sources":["../../../../src/backends/aci-standby-pool/__tests__/unenforceable-controls.test.ts"],"names":[],"mappings":""}