The sandbox backend contract: one behaviour, one facade, one error taxonomy.

A sandbox is a machine an agent runs in, owned by a provider (Sprites, E2B and Daytona ship here; a host can register more). This module is both the @behaviour an adapter implements and the facade a host application calls — call sites never name an adapter module, they dispatch through here on either a provider atom (creation-side operations) or the provider tag carried by a Managoat.Sandbox.Handle / Managoat.Sandbox.Command.

The semantics below are normative for every adapter; Managoat.Sandbox.ConformanceCase pins them, and Managoat.Sandbox.Fake is the reference implementation.

Lifecycle semantics

• create/2 is name-keyed and idempotent-adopting: creating a name that already exists returns {:ok, handle} for the existing sandbox.
• get/1 must return {:error, :not_found} for a definitively absent sandbox and a different error for anything transient. Callers use the distinction to decide whether a parked disk (holding agent memory) may be given up — misclassifying a network blip as not-found loses data.
• destroy/1 tolerates an already-gone sandbox (:ok).
• list_all_names/0 returns the full account view or refuses with {:error, :truncated} — never a partial set that looks whole.
• suspend/1 / resume/1 park and wake a sandbox. Adapters whose platform parks implicitly (scale-to-zero) implement them as no-ops but still advertise :suspend — the flag answers "does idle parking preserve the disk cheaply?", and the idle sweep destroys instead where it is absent. A failed suspend call degrades to destroy (an unparked sandbox keeps billing); a failed resume leaves the row suspended (the disk is the agent's memory).

Exec semantics

• exec/4 blocks until the command exits and never raises: a nonzero exit is {:ok, output, code} (the script failed — readable), an unreachable sandbox is {:error, reason} (retriable by the caller).

• spawn/4 starts a streaming command. The adapter must deliver these messages, and only these, to the :owner pid:

  {:stdout, %{ref: ref}, data :: binary()}
  {:stderr, %{ref: ref}, data :: binary()}   # absent in tty mode
  {:exit,   %{ref: ref}, exit_code :: integer()}
  {:error,  %{ref: ref}, reason :: term()}   # transport failure; no :exit follows

  where ref equals the returned command's ref and the second element is any map carrying :ref — consumers must match %{ref: ref}, never an adapter's struct. Exactly one terminal frame (:exit or :error) arrives, after all output frames. A stream that closes without an exit frame must be surfaced as {:exit, %{ref: ref}, 0} — an adapter that drops the connection silently makes failed commands look successful.

• write_stdin/2 is total: writing to a command whose process has already exited returns {:error, :command_exited}, it never exits or raises in the caller (the #603 contract).

• attach/3 re-joins a detached session and replays its buffered output from the beginning, then tails. There is no offset parameter; callers de-duplicate by counting bytes already persisted per stream, which only works if replay starts at byte zero.

Errors

Adapters normalize provider error shapes into the closed error/0 taxonomy so retry classification (Managoat.Sandbox.Retry.transient?/1) and not-found handling are provider-neutral.