@spec await_health(CrowdControl.Provider.Endpoint.t(), timeout()) ::
  :ok | {:error, term()}

Poll GET /v1/health until it answers, or timeout elapses.

This is what makes CrowdControl.Provider.acquire/1's contract satisfiable: provisioning that reports success before the agent answers is the single largest source of flaky remote backends.

@spec exec(CrowdControl.Provider.Endpoint.t(), String.t(), [String.t()], %{
  optional(String.t()) => String.t()
}) :: :ok | {:error, term()}

POST /v1/exec. Env travels in the JSON body, never in argv or a query string, and is never logged.

@spec health(
  CrowdControl.Provider.Endpoint.t(),
  keyword()
) :: :ok | {:error, term()}

GET /v1/health. The only unauthenticated route, and it returns no state.

@spec put_file(
  CrowdControl.Provider.Endpoint.t(),
  Path.t(),
  iodata(),
  non_neg_integer()
) ::
  :ok | {:error, term()}

PUT /v1/files/*path. Writes body inside the sandbox at mode.

Traversal is rejected here as well as by the agent. Two checks for one property is not redundancy: the client-side one is the only reason a caller gets a comprehensible error instead of a 400, and the server-side one is the only one that holds against a caller that is not this library.

@spec safe_path(Path.t()) :: {:ok, String.t()} | {:error, term()}

Reject a path with ./.. segments or a null byte, and require it absolute.

Public and pure so the check is testable without an agent.

@spec shutdown(CrowdControl.Provider.Endpoint.t()) :: :ok

POST /v1/shutdown. Kills the CLI and halts the agent.

Destroying the sandbox is the provider's job. A 404 or a transport error is success here: an agent that cannot be reached is already not running.

@spec status(CrowdControl.Provider.Endpoint.t(), non_neg_integer()) ::
  {:ok, status()} | {:error, term()}

GET /v1/status, optionally long-polled for up to wait_ms server-side.

A long poll is what stops a session from spinning on a live sandbox that has simply not produced output yet.

@spec stream(CrowdControl.Provider.Endpoint.t(), non_neg_integer()) ::
  {:ok, Req.Response.t()} | {:error, term()}

GET /v1/stream?offset=N as an into: :self response.

Returns the raw Req.Response because the caller must keep it to call Req.parse_message/2 and Req.cancel_async_response/1 — the same cancel-and-resume backpressure loop CrowdControl.Backend.Docker uses. Offsets are 0-indexed: the agent serves a byte offset directly, with none of tail -c +N's 1-indexed hazard.

:receive_timeout is the silent-sandbox watchdog

It is the only thing that turns "container is up, agent answers nothing, ever" into an :eof — nothing else in the stack notices, because the connection stays open and no bytes are owed. When it fires, Req delivers a normal {:error, %Finch.TransportError{reason: :timeout}} message rather than raising, so the reader's existing error path handles it.

It is set to 40s, deliberately longer than the agent's own idle stream window: the agent should end an idle response first, so an ordinary interactive pause produces a clean :done and a re-request rather than looking like a dead sandbox.

@spec stream_error(term()) :: {:sandboxd, term()}

Fold a mid-stream failure into this module's error vocabulary.

Req.parse_message/2 hands back a raw %Finch.TransportError{} for a connection that died under an open stream, and that is the one path where a failure reaches the reader without passing through normalize/1. Without this, the module's promise that callers only ever see {:sandboxd, _} would hold everywhere except the failure mode most likely to end up in a log.

@spec write(CrowdControl.Provider.Endpoint.t(), iodata()) :: :ok | {:error, term()}

POST /v1/stdin, base64-encoded so arbitrary bytes survive JSON.