snowflake-sandbox-python 0.2.1a1__py3-none-any.whl

snowflake/sandbox/sync_client.py

@@ -0,0 +1,2245 @@
+"""The ``Sandbox`` high-level synchronous/blocking client.
+
+Wraps the ``/api/v2/sandbox/v1`` REST surface: ``POST/GET/DELETE
+/containers`` for lifecycle and ``POST /containers/{id}/exec`` to run code.
+
+For the async API, see ``snowflake.sandbox.client.AsyncSandbox``.
+
+This module provides ``Sandbox`` — the default, blocking API that matches
+industry convention (Modal, E2B, Daytona). All I/O methods block until
+complete rather than returning coroutines.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import threading
+import time
+from collections.abc import Iterator, Mapping, Sequence
+from typing import TYPE_CHECKING, Any, Self
+
+from snowflake.sandbox._args import (
+    _cmd_to_code,
+    _require_nonempty_cmd,
+    _require_str_cmd,
+    _tags_post_create_message,
+    _validate_tags,
+    _wrap_detached,
+)
+from snowflake.sandbox._bundle import (
+    _collect_tree,
+    _hash_files,
+    _warn_notable_bundle_skips,
+    _zip_files,
+)
+from snowflake.sandbox._env import validate_env_mapping
+from snowflake.sandbox._retry import (
+    DEFAULT_LOGS_500_DELAYS_S,
+    DEFAULT_START_FAILURE_DELAYS_S,
+    compute_backoff,
+    is_retryable_start_failure,
+)
+from snowflake.sandbox._sandbox_state import _SandboxState
+from snowflake.sandbox._stage import (
+    _connect_for_stage,
+    _safe_stage_filename,
+    _validate_stage_identifier,
+)
+from snowflake.sandbox._sync_files_mixin import _FilesMixin
+from snowflake.sandbox._sync_transport import (
+    SSEEvent,
+    StreamAbort,
+    SyncTransport,
+    get_sync_transport,
+)
+from snowflake.sandbox._wire import (
+    _EXEC_RECONNECT_DELAYS,
+    _EXEC_TIMEOUT_GRACE_S,
+    _POLL_UNKNOWN_EXIT_CODE,
+    _advance_exec_cursor,
+    _exec_reconnect_exhausted,
+    _exec_session_id,
+    _fresh_exec_body,
+    _idle_suspend_minutes,
+    _parse_status,
+    _resolve_exec_budget,
+    _warn_if_truncated,
+)
+from snowflake.sandbox.egress import Egress, compile_egress
+from snowflake.sandbox.exceptions import (
+    SandboxConflictError,
+    SandboxError,
+    SandboxExecError,
+    SandboxExecTimeoutError,
+    SandboxNotFoundError,
+    SandboxNotImplementedError,
+    SandboxNotReadyError,
+    SandboxTransportError,
+)
+from snowflake.sandbox.image import Image
+from snowflake.sandbox.log_stream import _explain_logs_conflict, _log_lines_from_payload
+from snowflake.sandbox.mcp import McpServer, validate_mcp_servers
+from snowflake.sandbox.mount import validate_stage_mounts
+from snowflake.sandbox.secret import Secret
+from snowflake.sandbox.sync_exec_stream import SyncExecStream
+from snowflake.sandbox.sync_log_stream import SyncLogStream
+from snowflake.sandbox.sync_shell import SyncShell, open_shell_sync
+from snowflake.sandbox.types import (
+    SANDBOX_STATUSES,
+    TERMINAL_STATUSES,
+    ExecResult,
+    MemoryTier,
+    SandboxStatus,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from snowflake.sandbox.config import ConnectionLike
+    from snowflake.sandbox.jobs import RunResult
+    from snowflake.sandbox.mount import StageMount
+    from snowflake.sandbox.types import RunStatus
+
+__all__ = [
+    "Sandbox",
+    "list_sandboxes",
+    "get_sandbox_by_name",
+    "destroy_sandbox",
+]
+
+
+def _coerce_image(image: str | Image, transport: SyncTransport | None) -> str:
+    """Resolve an ``image=`` argument to the string ``create()`` sends to the server.
+
+    An ``Image`` is a reference to a catalog base, so it resolves to its ``name``; a
+    plain string passes through unchanged. (``transport`` is accepted for a stable
+    signature — the removed layered-image builder used it to build on create.)
+    """
+    if isinstance(image, Image):
+        return image.name
+    return image
+
+
+def _raise_if_stream_terminated(abort: StreamAbort) -> None:
+    """Abort ``_exec_stream_frames`` when ``terminate()`` fired mid-stream.
+
+    Checked at the three points a resume could otherwise happen -- the top of the
+    reconnect loop, a clean close, and a transport cut. Reopening from any of them
+    would resume a sandbox that another thread has torn down, so the stream ends
+    in a ``SandboxError`` naming the likely causes. ``from None`` drops any
+    incidental transport error: the abort is the real cause. The async client
+    mirrors this in ``client._raise_if_stream_terminated``.
+    """
+    if not abort.aborted:
+        return
+    raise SandboxError(
+        "exec_stream() was interrupted: this sandbox was terminated "
+        "while the command was still running, so the output is "
+        "incomplete and the exit status is unknown. If that was "
+        "deliberate, catch SandboxError around the iteration; if not, "
+        "check what else holds this handle -- terminate() from another "
+        "thread, or a `with` block that exited."
+    ) from None
+
+
+class Sandbox(_FilesMixin, _SandboxState):
+    """A Snowflake sandbox container (sync API).
+
+    `create()` is the factory, and the only creation path -- ``Sandbox(...)`` raises.
+    Reconnect to an existing sandbox with ``Sandbox.connect(name)`` / `get_sandbox` /
+    `get_sandbox_by_name`, or deploy local code with `from_local`.
+
+    For an async API, use ``AsyncSandbox`` instead.
+
+    Example (requires a Snowflake connection -- a ``~/.snowflake`` default,
+    ``SNOWFLAKE_ACCOUNT`` + ``SNOWFLAKE_TOKEN`` env vars, or an explicit
+    ``connection=``; otherwise ``Sandbox.create()`` raises
+    ``"snowflake.sandbox has no endpoint to talk to"``):
+
+        with Sandbox.create() as sb:
+            result = sb.exec(["python", "-c", "print(40+2)"])
+            print(result.stdout)
+    """
+
+    def __init__(
+        self,
+        *,
+        image: str | Image = "",
+        memory: MemoryTier = "4g",
+        cpu: float | None = None,
+        env: Mapping[str, str] | None = None,
+        name: str | None = None,
+        command: Sequence[str] | None = None,
+        stage_path: str | None = None,
+        egress: Egress | Mapping[str, object] | None = None,
+        secrets: Sequence[Secret | Mapping[str, str]] | None = None,
+        gpu: Mapping[str, object] | None = None,
+        stage_mounts: Sequence[StageMount] | None = None,
+        mcp_servers: Sequence[str | McpServer | Mapping[str, object]] | None = None,
+        tags: Mapping[str, str] | None = None,
+        mount_snowflake_config: bool = True,
+        transport: SyncTransport | None = None,
+        _internal: bool = False,
+    ) -> None:
+        # NOT a public constructor. `create()` / `connect()` / `from_local()` /
+        # hydration construct through here with _internal=True; a caller cannot, because
+        # the object this builds is not a sandbox yet -- it holds a spec and acquires a
+        # container only in __enter__, so every attribute a caller would reach for first
+        # (id, status, exec) failed on an unentered instance. That shape was kept working
+        # for demos doing ``with Sandbox() as sb:`` (#382) and is now refused outright.
+        #
+        # ``transport=`` is exempt because it IS the internal seam: its type lives in a
+        # private module and is not exported, so a caller outside this SDK has no
+        # supported way to build one. Requiring _internal=True there as well would buy
+        # no safety and would force ~90 of this SDK's own unit tests to fake a create
+        # round-trip just to get a handle.
+        if not _internal and transport is None:
+            raise TypeError(
+                f"{type(self).__name__}(...) is not a public constructor. Use "
+                f"{type(self).__name__}.create(...) to create a sandbox, "
+                f"{type(self).__name__}.connect(name) to attach to one by name, or "
+                f"{type(self).__name__}.from_local(...) to deploy local code. The bare "
+                "constructor returned an object with no container behind it until the "
+                "with-block was entered."
+            )
+        # An Image is a reference to a catalog base — resolve it to its name.
+        if isinstance(image, Image):
+            image = image.name
+        self._image = image
+        self._memory: MemoryTier = memory
+        # cpu overrides only the CPU the memory tier would imply; memory stays
+        # tier-selected. Rejected locally when non-positive so an obvious
+        # mistake fails at the call site rather than as a server 400. No upper
+        # bound is enforced here deliberately — the server owns the ceiling (it
+        # currently has none), and duplicating one client-side would drift.
+        if cpu is not None and cpu <= 0:
+            raise SandboxError(f"cpu must be greater than 0, got {cpu!r}")
+        self._cpu: float | None = cpu
+        # Validate the environment map: a caller-supplied SNOWFLAKE_* would
+        # redirect the sandbox's Snowflake identity, a proxy/TLS var could defeat
+        # egress confinement, and PATH/LD_* could hijack execution — the same
+        # validate_env_mapping() guard. No key is exempt: SDK-minted
+        # platform keys (SNOWFLAKE_CODE_URL, the session/job nonces) never come
+        # through here — they ride the `sandbox_env` channel via _add_platform_env().
+        self._env: dict[str, str] = validate_env_mapping(env, context="Sandbox(env=)")
+        # Platform-channel env, sent as the create body's `sandbox_env` LIST (not the
+        # user `env` map). The server validates this list with a policy that ALLOWS
+        # the SNOWFLAKE_/SANDBOX_ platform prefixes, whereas the `env` map reserves
+        # the whole SANDBOX_/SNOWFLAKE_ prefix.
+        # Every SDK-minted platform key (the per-session SANDBOX_SESSION_NONCE, the
+        # code-delivery SNOWFLAKE_CODE_URL, the SANDBOX_JOB_* runner vars) rides here
+        # via _add_platform_env() so it is not rejected as reserved. Never carries
+        # user-supplied keys.
+        self._sandbox_env: list[str] = []
+        self._name = name
+        self._command: list[str] | None = list(command) if command else None
+        self._stage_path = stage_path
+        # Secrets are authored flat (Modal-shaped) but nest under egress on the
+        # wire, since egress.secrets is a field of Snowflake's EgressConfig. Validation
+        # mirrors Snowflake's own rules so a misconfig fails here, not at StartApp.
+        self._egress = compile_egress(egress, secrets or ())
+        # Forward-compat GPU on-ramp: passed through to the create body
+        # verbatim, e.g. {"type": "L4", "count": 1, "profile": "full",
+        # "warm_pool": False}. Absent -> today's CPU behavior, unchanged.
+        # The backend 501s until GPU actually lands server-side.
+        self._gpu: dict[str, object] | None = dict(gpu) if gpu else None
+        if stage_mounts:
+            # Cross-mount check (each mount validated its own path at construction):
+            # two stages at the same mount_path is a silent last-one-wins.
+            validate_stage_mounts(list(stage_mounts))
+        self._stage_mounts: list[dict[str, object]] = (
+            [m.to_api_dict() for m in stage_mounts] if stage_mounts else []
+        )
+        # EXTERNAL MCP SERVERs to expose to the container, as FQN strings or
+        # `McpServer`. Only kind/name/fqn/profile are sent: the url, api_integration,
+        # and per-user secret_entity_id are resolved server-side by Snowflake under the
+        # calling user's own OAuth authorization, and a caller asserting them would be
+        # asserting another user's secret -- validate_mcp_servers rejects them here and
+        # sandbox-api 400s them again.
+        self._mcp_servers: list[dict[str, str]] = validate_mcp_servers(list(mcp_servers or []))
+        # Caller tags -> the server's `labels` map (Modal vocabulary on the SDK
+        # surface, `labels` on the wire). Metadata only; not part of container
+        # identity. Sent in the create body and echoed back on reads. Buffered here
+        # so a pre-create set_tags() can add to it before the create fires; after
+        # create it is the last value the server reported (the server has no
+        # relabel endpoint, so it cannot change post-create — see set_tags()).
+        self._tags: dict[str, str] = _validate_tags(tags, context="Sandbox(tags=)")
+        # When False, the platform does not render this sandbox's Snowflake
+        # connection (connections.toml + SNOWFLAKE_HOME); the caller manages its
+        # own. Default True keeps the zero-setup connection.
+        self._mount_snowflake_config = mount_snowflake_config
+        self._role: str | None = None  # set by create() when role= is passed
+        self._idle_suspend_minutes: int | None = None  # set by create() from idle_suspend=
+        # The transport is the POOLED one for whatever connection applies (ambient,
+        # an enclosing using() block, or the connection= create() resolved), or a
+        # caller-supplied transport=. A handle never OWNS it, so __exit__ closes
+        # nothing — shutdown() does. Do not re-add ownership/close logic here.
+        self._transport = transport or get_sync_transport()
+        self._id: str | None = None
+        # Lets terminate() interrupt an exec_stream() blocked in another
+        # thread. Per-sandbox, so aborting one never disturbs another.
+        self._stream_abort = StreamAbort()
+        self._status: SandboxStatus = "pending"
+        self._error_message: str | None = None
+        self._async_pending: bool = False  # True when server returned 202
+        # Whether _ensure_created() should settle a 202 before returning the
+        # handle. create() drives its own (strict) wait, so it opts out.
+        self._settle_on_create: bool = True
+        # The server's own status string, verbatim ("starting" | "running" |
+        # "crashed" | "suspended" | ...), kept alongside the mapped `_status`.
+        # `_status` collapses the vocabulary (starting->pending, running->ready),
+        # which hides the difference between "still coming up" and "process up" that
+        # `snow sandbox list` needs to show. Set by _hydrate/refresh/create; "" until
+        # the server reports one.
+        self._server_status: str = ""
+        # Read-only fields the server echoes on a get / status read:
+        # the managed process's last exit code, and a restart/resume generation
+        # counter (bumped when Snowflake cold-restarts a suspended sandbox — /tmp and
+        # /snowflake/stages are wiped, so a jump is worth reacting to). Populated by
+        # refresh()/connect()/the cheap status route; None until the server reports.
+        self._exit_code: int | None = None
+        self._generation: int | None = None
+        self._created_at: int | None = None
+        self._stopped_at: int | None = None
+        self._created = False
+        # Serializes the implicit create. Without it, `asyncio.gather(sb.exec(a),
+        # sb.exec(b))` on a fresh handle POSTed /containers twice: `_id` kept the
+        # second, the first was orphaned and billed, and nothing failed visibly.
+        # (asyncio.Lock binds to the running loop on first await, not here, so
+        # constructing it outside a loop is safe.)
+        self._create_lock = threading.Lock()
+        # Per-run nonce embedded in the detached-run result sentinel, when this
+        # handle wrapped the command itself (`Sandbox.create(command=...)`).
+        # `wait()` requires it so a sentinel printed by the workload's own stdout
+        # is not read as the run's authoritative outcome. A handle rehydrated by
+        # `connect()` has no nonce and keeps the unauthenticated read.
+        self._result_nonce: str | None = None
+        # Per-session reply nonce embedded in the daemon's __SANDBOX_REPLY__
+        # sentinel. Set by whichever path deployed the daemon and handed it
+        # SANDBOX_SESSION_NONCE on the `sandbox_env` platform channel (session_loop
+        # reads it once at startup and drops it before any handler runs); `send()`
+        # then requires it, so a __SANDBOX_REPLY__ line printed by an untrusted
+        # handler is not read as the daemon's authentic reply. Same shape as
+        # `_result_nonce`: a handle that holds no nonce keeps the unauthenticated
+        # read.
+        self._reply_nonce: str | None = None
+
+    # ----- platform env channel ---------------------------------------
+
+    # ----- properties -------------------------------------------------
+
+    @property
+    def id(self) -> str:
+        """The server-assigned container ID.
+
+        Example:
+            sb = Sandbox.create()
+            print(sb.id)   # "cntr_9f2a1b..."
+        """
+        if self._id is None:
+            raise SandboxError("sandbox has no id yet -- call create() (or use with)")
+        return self._id
+
+    @property
+    def server_status(self) -> str:
+        """The server's raw status string, or ``""`` if none has been reported.
+
+        Unlike `status` (which maps to the closed {pending, ready, dead, failed,
+        unknown} set), this
+        preserves the server's own word -- ``"starting"`` vs ``"running"`` -- so a
+        caller can tell a process that is still coming up from one that is up. Same
+        caching contract as `status`: set on create/connect/list and by `refresh()`.
+        """
+        return self._server_status
+
+    def refresh(self) -> SandboxStatus:
+        """Re-read this container's state from the server and return its status.
+
+        Example:
+            status = sb.refresh()
+            print(status)  # "ready", "pending", "dead", "failed", or "unknown"
+        """
+        if self._id is None:
+            return self._status
+        try:
+            resp = self._transport.request("GET", f"containers/{self._id}")
+        except SandboxNotFoundError:
+            self._status = "dead"
+            return self._status
+        payload = resp.json() if resp.content else {}
+        if isinstance(payload, dict):
+            parsed = _parse_status(payload.get("status"))
+            if parsed is not None:
+                self._status = parsed
+            if payload.get("status"):
+                self._server_status = str(payload["status"])
+            self._absorb_resource_echo(payload)
+            self._absorb_read_fields(payload)
+        return self._status
+
+    def refresh_live_status(self) -> SandboxStatus:
+        """Read the LIVE status of the managed process, updating ``status`` /
+        ``server_status``.
+
+        The list endpoint returns a create-time snapshot (a command-container is
+        stamped ``starting`` at create and the stored record is never advanced),
+        so a running job reads ``starting`` there forever. This probes the live
+        state via ``GET /{id}/status`` — cheap and side-effect-free (no app start,
+        so no resume, no idle-timer reset, no egress strip).
+
+        Deliberately the ONLY probe used. ``GET /{id}?refresh=true`` would also
+        report a live status, but it drives an app start: a cold resume can take
+        seconds, and running it per row made ``list`` very slow. So there is no
+        fallback to it here. On a replica that predates the ``/status`` route the
+        request falls through to the ``GET /{id}`` catch-all and comes back
+        ``400 "missing container id"`` (the id parses as ``{id}/status``, which
+        has a slash); that row simply keeps its list status.
+
+        Best-effort: on any failure the cached status is kept and ``_probe_error``
+        records it. A short timeout bounds a single slow/unreachable row so it
+        cannot stall the whole list.
+
+        Example:
+            status = sb.refresh_live_status()
+            print(status)  # the LIVE process status, not the create-time snapshot
+        """
+        self._probe_error: str | None = None
+        if self._id is None:
+            return self._status
+        # Only the cheap, side-effect-free /status route, with a short timeout so a
+        # single slow/unreachable row cannot stall the whole list. The heavier
+        # ?refresh=true fallback (which drives StartApp — a cold resume can take
+        # seconds) is deliberately NOT used here: it made `list` very slow. On a
+        # replica that lacks /status (a fast 400), the row keeps its list status.
+        try:
+            resp = self._transport.request(
+                "GET",
+                f"containers/{self._id}/status",
+                retry_not_found=False,
+                timeout=5.0,
+            )
+        except SandboxError as exc:
+            self._probe_error = f"{type(exc).__name__}: {exc}"
+            return self._status
+        payload = resp.json() if resp.content else {}
+        if isinstance(payload, dict):
+            raw = payload.get("status")
+            parsed = _parse_status(raw)
+            if parsed is not None:
+                self._status = parsed
+            if raw:
+                self._server_status = str(raw)
+            self._absorb_read_fields(payload)
+        return self._status
+
+    @property
+    def image(self) -> str:
+        """The image name the sandbox was constructed with.
+
+        Example:
+            sb = Sandbox.create()
+            print(sb.image)  # the deployment's default image
+        """
+        return self._image
+
+    @property
+    def memory(self) -> MemoryTier:
+        """The effective memory tier (`'1g'`, `'4g'`, `'8g'`, `'16g'`, `'32g'`, or `'64g'`).
+
+        Example:
+            sb = Sandbox.create(memory="16g")
+            print(sb.memory)  # "16g"
+        """
+        return self._memory
+
+    # ----- lifecycle --------------------------------------------------
+
+    def _ensure_created(self) -> Self:
+        """Ensure the underlying container exists (idempotent POST /containers).
+
+        Internal — the public factory is `Sandbox.create()`. Other methods
+        (``exec``, ``logs`` …) call this so a sandbox is created on first use.
+        Concurrent first uses of one handle serialize on ``_create_lock`` so only
+        one container is ever created for it.
+        """
+        if self._created:
+            return self
+        with self._create_lock:
+            if self._created:
+                return self
+            self._create_now()
+        return self._settle_pending_create()
+
+    def _build_create_body(self) -> dict[str, Any]:
+        """Assemble the ``POST /containers`` request body from the configured fields.
+
+        Each optional field is sent only when set, so a request that does not use it
+        is byte-identical to one made before the field existed. ``role`` is
+        deliberately never in the body (see below).
+
+        `memory` is the canonical field; `memory_limit` is its deprecated alias,
+        sent alongside so this SDK works against BOTH a current server and one
+        deployed before the rename. Neither direction fails loudly on its own:
+        an unrecognized key is ignored, so sending only `memory` to an older
+        server silently yields the default tier — ask for 64g, get 4g, with a
+        200. Drop the alias once every deployment understands `memory`.
+        """
+        body: dict[str, Any] = {
+            "image": self._image,
+            "memory": self._memory,
+            "memory_limit": self._memory,
+        }
+        if self._cpu is not None:
+            body["cpu"] = self._cpu
+        if self._env:
+            body["env"] = dict(self._env)
+        if self._sandbox_env:
+            # Platform-channel env (KEY=VALUE list). Kept distinct from `env` on the
+            # wire: the server reserves the SANDBOX_ prefix on the `env` map but
+            # allows it on `sandbox_env`, which is where our SANDBOX_SESSION_NONCE
+            # rides.
+            body["sandbox_env"] = list(self._sandbox_env)
+        if self._name:
+            body["name"] = self._name
+        if self._command:
+            body["command"] = self._command
+        if self._stage_path:
+            body["stage_path"] = self._stage_path
+        if self._egress:
+            body["egress"] = self._egress
+        if self._gpu:
+            # Passed through verbatim; the server owns the schema.
+            body["gpu"] = dict(self._gpu)
+        if self._stage_mounts:
+            body["stage_mounts"] = list(self._stage_mounts)
+        if self._mcp_servers:
+            # The server resolves each fqn per user and serializes the resolved list
+            # to SANDBOX_MCP_SERVERS on `sandbox_env` (never the `env` map -- the
+            # SANDBOX_ prefix is reserved there). A server the caller is not
+            # authorized for is omitted rather than sent with an empty token.
+            body["mcp_servers"] = list(self._mcp_servers)
+        if self._tags:
+            # Caller tags ride the server's `labels` field. The server accepts
+            # `labels` at create and echoes it on reads (get_tags), but has no
+            # relabel endpoint — see set_tags().
+            body["labels"] = dict(self._tags)
+        if not self._mount_snowflake_config:
+            # Opt out of the platform-rendered Snowflake connection (the server
+            # treats absent as "configure").
+            body["mount_snowflake_config"] = False
+        # role is NOT sent in the body: the sandbox runs under the role its
+        # session token was minted with (get_sync_transport(role) routes the
+        # role-scoped token), and the server records/echoes the role from that
+        # session's identity.Role. The create endpoint rejects unknown body
+        # fields with a 400, so sending `role` here would break every call.
+        if self._idle_suspend_minutes:
+            # Per-app idle-suspend override (minutes). Only the set key is sent.
+            body["lifecycle"] = {"idle_suspend_minutes": self._idle_suspend_minutes}
+        return body
+
+    def _create_now(self) -> Self:
+        """POST /containers and record the result. Holds ``_create_lock``."""
+        body = self._build_create_body()
+        resp = self._transport.request(
+            "POST",
+            "containers",
+            json_body=body,
+        )
+        payload = resp.json() if resp.content else {}
+        # Both create shapes are accepted, so this SDK can deploy independently of
+        # the server instead of in lockstep with it:
+        #   202  async create (sandbox-api #144 and later) — StartApp runs in a
+        #        background goroutine, so the record is still pending and
+        #        `_wait_until_ready` polls GET /containers/{id}.
+        #   200  synchronous create (a server deployed before #144) — StartApp has
+        #        already returned, so this payload's status is final and no poll is
+        #        needed. Behaviour here is identical to the pre-#144 SDK.
+        # Asserting 202 alone would make every create fail against an un-upgraded
+        # deployment, which is what forces a two-repo simultaneous deploy.
+        if resp.status_code not in (200, 202):
+            raise SandboxError(
+                f"create expected 200 OK or 202 Accepted, got {resp.status_code}: {payload!r}"
+            )
+        sandbox_id = payload.get("container_id") or payload.get("id") or payload.get("sandbox_id")
+        if not sandbox_id:
+            raise SandboxError(f"create returned no container id: {payload!r}")
+        self._id = sandbox_id
+        parsed = _parse_status(payload.get("status"))
+        self._status = parsed if parsed is not None else "pending"
+        if payload.get("status"):
+            self._server_status = str(payload["status"])
+        self._absorb_read_fields(payload)
+        self._absorb_resource_echo(payload)
+        self._created = True
+        # Only a 202 leaves server-side work outstanding. A 200 means StartApp
+        # already finished, so the status above is final and create() must not
+        # spend a GET confirming it.
+        self._async_pending = resp.status_code == 202
+        return self
+
+    def _raise_if_create_failed(self) -> None:
+        """Raise iff the SERVER reports the create itself failed.
+
+        Deliberately keyed on status alone. ``_error_message`` is not a usable signal
+        on its own: ``_absorb_read_fields`` sets it from *any* payload carrying a
+        non-empty ``error_message`` and never clears it, so a stale message left by an
+        earlier blip (or hydrated by ``connect()``/``refresh()``/list) would otherwise
+        fail a perfectly healthy create.
+        """
+        if self._status == "failed":
+            raise SandboxTransportError(
+                f"container create failed: {self._error_message or 'unknown server error'}"
+            )
+
+    def _reset_for_recreate(self) -> None:
+        """Clear create-state so ``create()`` can POST a fresh container after a
+        *retryable* StartApp failure.
+
+        Only the per-attempt fields are reset; the spec (image/env/egress/secrets/
+        command/…) lives in ctor-set instance fields and is untouched, so the
+        re-created container is byte-identical to the first attempt.
+        """
+        self._created = False
+        self._id = None
+        self._status = "pending"
+        self._server_status = ""
+        self._error_message = None
+        self._async_pending = False
+
+    def _settle_pending_create(self) -> Self:
+        """Let an async (202) create finish before this handle gets used.
+
+        ``create()`` runs its own strict wait and opts out of this one. This covers
+        every *other* door that provisions lazily — ``__enter__``, a bare
+        ``exec``/``logs``/``shell``, ``deploy()``, the job runners. Each was
+        safe by construction before sandbox-api#144, when a ``200`` meant ``StartApp``
+        had already finished; a ``202`` makes them race it, and the server evicts and
+        404s a record whose app the controller does not have yet — so an un-waited
+        exec fails with "container not found".
+
+        Only the ``pending`` sentinel means "not finished". Any other status — ready,
+        ``starting`` (a command container), terminal, or one this SDK does not
+        recognise — is an answer, so this returns without issuing a single request.
+        A ``dead`` container does not raise: it really ran, and reading the logs of a
+        finished run is legitimate and must not become a create error. A ``failed``
+        one does raise, here rather than later — it never came up, so every operation
+        on the handle would fail for a reason that looks unrelated.
+        """
+        if not (self._async_pending and self._settle_on_create):
+            return self
+        # A create that already settled on `failed` is reported HERE, as a create
+        # failure. The early return below skipped it, so the handle went on to the
+        # caller's own operation, which then failed for its own reason -- "container
+        # not found" from an exec, attributed to the exec. Only `failed` raises:
+        # `dead` is a container that really ran, and reading its logs is legitimate
+        # (which is what the lenient wait exists for).
+        self._raise_if_create_failed()
+        raw = (self._server_status or "").strip().lower()
+        if raw and raw not in ("pending", "not_started"):
+            return self
+        self._wait_until_ready(strict=False)
+        return self
+
+    def _wait_until_ready(self, timeout: float = 300.0, *, strict: bool = True) -> None:
+        """Poll ``GET /containers/{id}`` until the container is live, or fail.
+
+        Used after a ``202 Accepted`` from ``POST /containers``: the server finishes
+        ``StartApp`` on a background goroutine, so the record starts on the
+        ``"pending"`` sentinel and this waits for that sentinel to clear.
+
+        Create is finished when the server stops reporting ``"pending"`` — **not**
+        when it reports ``"ready"``. A command container settles on ``"starting"``
+        (its managed process is tracked separately, by ``wait()``), and ``"starting"``
+        maps to ``pending``, so waiting for ``"ready"`` would spin to the deadline for
+        every command container even though create succeeded.
+
+        Three cases deliberately keep polling instead of ending the wait, because each
+        would otherwise report a not-yet-live container as a successful create:
+
+        * a response carrying **no** ``status`` — nothing was observed, so the previous
+          response's value must not be reused as the answer;
+        * the ``"pending"`` / ``"not_started"`` sentinels;
+        A terminal status (``dead``/``failed``) raises rather than returning.
+
+        ``timeout`` matches ``cngStartAppTimeout`` on the server (5 minutes).
+        """
+        if self._id is None:
+            raise SandboxError(
+                "wait_until_ready() called before the container was created; "
+                "use Sandbox.create() (optionally with wait=False) first"
+            )
+        if self._status == "ready":
+            return
+        if strict:
+            self._raise_if_create_failed()
+        deadline = time.monotonic() + timeout
+        delay = 0.2
+        while time.monotonic() < deadline:
+            payload: dict[str, Any] | None
+            try:
+                resp = self._transport.request("GET", f"containers/{self._id}")
+                payload = resp.json() if resp.content else {}
+            except SandboxTransportError:
+                # One 5xx / GOAWAY / reset during a multi-minute cold start must not
+                # kill the create — the deadline decides, not a single bad response.
+                payload = None
+            if payload is not None:
+                raw = str(payload.get("status") or "").strip().lower()
+                parsed = _parse_status(payload.get("status"))
+                if parsed is not None:
+                    self._status = parsed
+                if raw:
+                    self._server_status = str(payload["status"])
+                self._absorb_read_fields(payload)
+                self._absorb_resource_echo(payload)
+                self._raise_if_create_failed()
+                if self._status in TERMINAL_STATUSES and not strict:
+                    # Lenient: a terminal container is a legitimate thing to operate
+                    # on (logs() of a run that already finished), so stop waiting and
+                    # let the caller's own operation speak for itself.
+                    return
+                if self._status in TERMINAL_STATUSES:
+                    raise SandboxTransportError(
+                        f"container {self._id!r} became "
+                        f"{self._server_status or self._status!r} while starting"
+                    )
+                if self._status == "ready":
+                    return
+                # Decide from THIS response only. `raw` is empty when the server sent
+                # no status, and "unknown" means a status this SDK does not know —
+                # both must keep waiting rather than read as ready.
+                if raw and raw not in ("pending", "not_started"):
+                    return
+            time.sleep(min(delay, max(0.0, deadline - time.monotonic())))
+            delay = min(delay * 1.5, 2.0)
+        raise SandboxNotReadyError(
+            f"container {self._id!r} did not become ready within {timeout:g}s"
+        )
+
+    def wait_until_ready(self, timeout: float = 300.0) -> None:
+        """Block until the container is live (for sandboxes created with ``wait=False``).
+
+        No-op if the sandbox is already in ``ready`` status. Raises
+        ``SandboxNotReadyError`` if the timeout expires before the container
+        becomes live, or ``SandboxTransportError`` if the server reports a
+        create failure.
+
+        Example:
+            # Fire all creates immediately
+            sandboxes = [Sandbox.create(wait=False)
+                         for _ in range(10)]
+            # Wait for all in parallel
+            with ThreadPoolExecutor() as pool:
+                pool.map(lambda sb: sb.wait_until_ready(), sandboxes)
+        """
+        if self._status == "ready":
+            return
+        self._wait_until_ready(timeout=timeout)
+
+    def logs(self, *, tail: int = 0, since_ts_ms: int = 0) -> str:
+        """Return the container's captured stdout and stderr as a string.
+
+        `tail` limits to the last N lines. Only meaningful for command containers
+        (created with `command=`).
+
+        Example:
+            output = sb.logs(tail=100)
+            print(output)
+        """
+        if not self._created:
+            self._ensure_created()
+        if self._id is None:  # pragma: no cover - defensive
+            raise SandboxError(
+                "logs() failed: sandbox has no id (this is a bug — create() should have set it)"
+            )
+        q = []
+        if tail:
+            q.append(f"tail={tail}")
+        if since_ts_ms:
+            q.append(f"since={since_ts_ms}")
+        path = f"containers/{self._id}/logs" + ("?" + "&".join(q) if q else "")
+        try:
+            resp = self._transport.request("GET", path, retry_500_delays=DEFAULT_LOGS_500_DELAYS_S)
+        except SandboxConflictError as exc:
+            explained = _explain_logs_conflict(exc)
+            if explained is exc:
+                raise
+            raise explained from exc
+        payload = resp.json() if resp.content else {}
+        lines = _log_lines_from_payload(payload)
+        return "\n".join(ln.get("text", "") for ln in lines)
+
+    def _fetch_log_lines(self, *, tail: int = 0, since_ts_ms: int = 0) -> list[dict[str, Any]]:
+        """Raw log lines -- ``{ts, stream, text}`` each -- backing the log streams.
+
+        logs() flattens these to text; LogStream needs the per-line ``stream``
+        channel and ``ts`` the server already sends.
+        """
+        if not self._created:
+            self._ensure_created()
+        if self._id is None:  # pragma: no cover - defensive
+            raise SandboxError(
+                "logs() failed: sandbox has no id (this is a bug — create() should have set it)"
+            )
+        q = []
+        if tail:
+            q.append(f"tail={tail}")
+        if since_ts_ms:
+            q.append(f"since={since_ts_ms}")
+        path = f"containers/{self._id}/logs" + ("?" + "&".join(q) if q else "")
+        try:
+            resp = self._transport.request("GET", path, retry_500_delays=DEFAULT_LOGS_500_DELAYS_S)
+        except SandboxConflictError as exc:
+            explained = _explain_logs_conflict(exc)
+            if explained is exc:
+                raise
+            raise explained from exc
+        return _log_lines_from_payload(resp.json() if resp.content else {})
+
+    @property
+    def stdout(self) -> SyncLogStream:
+        """The managed command process's stdout, as an async-iterable of lines.
+
+        Mirrors the ``.stdout`` an exec'd process exposes, so both handles read
+        the same way:
+
+            for line in sb.stdout:
+                print(line)
+
+        Only meaningful for command containers (created with ``command=``).
+        `logs()` remains the snapshot accessor -- prefer it for
+        ``logs(tail=100)`` on a container that has already finished.
+        """
+        return SyncLogStream(self, "stdout")
+
+    @property
+    def stderr(self) -> SyncLogStream:
+        """The managed command process's stderr. See `stdout`."""
+        return SyncLogStream(self, "stderr")
+
+    def shell(
+        self,
+        *,
+        rows: int = 24,
+        cols: int = 80,
+        cwd: str | None = None,
+    ) -> SyncShell:
+        """Open an interactive shell session inside the sandbox.
+
+        Note:
+            `shell` is a terminal verb, not the SSH protocol. There is no port 22,
+            no key exchange, and no scp. The shell is a PTY driven over the
+            Snowflake REST path.
+
+        Example:
+            with sb.shell() as sh:
+                sh.send("ls -la\\n")
+                for chunk in sh.output():
+                    sys.stdout.buffer.write(chunk)
+        """
+        if not self._created:
+            self._ensure_created()
+        if self._id is None:  # pragma: no cover - defensive
+            raise SandboxError(
+                "shell() failed: sandbox has no id (this is a bug — create() should have set it)"
+            )
+        return open_shell_sync(self._transport, self._id, rows=rows, cols=cols, cwd=cwd)
+
+    def destroy(self) -> None:
+        """Deprecated: use `terminate()` instead.
+
+        Terminate the container. Idempotent: an already-gone container is fine.
+        Only a 404 is swallowed. Any other failure -- an expired token, a
+        transport error, a rate limit -- propagates, and the handle is NOT marked
+        dead: swallowing those reported a successful teardown while the container
+        kept running with its brokered-secret environment, which on token expiry
+        at ``__aexit__`` is exactly when it matters.
+        """
+        import warnings
+
+        warnings.warn(
+            "destroy() is deprecated, use terminate() instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self._terminate_impl()
+
+    def _terminate_impl(self) -> None:
+        """Internal terminate implementation (no deprecation warning)."""
+        if self._id is None:
+            return
+        # Interrupt any exec_stream() reading this sandbox BEFORE the DELETE. Once
+        # the container is gone the server sends nothing more, so a reader blocked
+        # in recv() would sit there until the HTTP read timeout -- up to 630s on the
+        # default exec budget -- holding its thread the whole time. Doing this first
+        # also means the reader observes the abort flag rather than racing a
+        # not-found on reconnect.
+        self._stream_abort.abort()
+        try:
+            self._transport.request("DELETE", f"containers/{self._id}")
+        except SandboxNotFoundError:
+            # Already gone (TTL, manual delete, a previous destroy) -- the
+            # requested end state, so this is a success.
+            pass
+        except Exception:
+            # The DELETE failed for a reason other than "already gone" -- an expired
+            # token, a transport error, a rate limit -- so the container may still be
+            # running (destroy() keeps the handle alive on exactly these). The abort
+            # is irreversible, so re-arm it before propagating; otherwise a retryable
+            # teardown failure would brick exec_stream() on this live handle with a
+            # false "this sandbox was terminated".
+            self._stream_abort = StreamAbort()
+            raise
+        self._status = "dead"
+
+    def __enter__(self) -> Self:
+        self._ensure_created()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        # The transport is pooled (per credential identity) or caller-supplied, never
+        # owned by this handle, so exiting terminates the sandbox and leaves the client
+        # to `shutdown_sync()` — the same lifetime rule as the ambient path.
+        self._terminate_impl()
+
+    # ----- factory ----------------------------------------------------
+
+    @classmethod
+    def from_local(
+        cls,
+        source_dir: str | Path,
+        *,
+        command: Sequence[str] | None = None,
+        image: str | Image = "",
+        memory: MemoryTier = "4g",
+        cpu: float | None = None,
+        code_stage: str | None = None,
+        exclude: list[str] | None = None,
+        include: list[str] | None = None,
+        env: Mapping[str, str] | None = None,
+        platform_env: Mapping[str, str] | None = None,
+        egress: Egress | Mapping[str, object] | None = None,
+        secrets: Sequence[Secret | Mapping[str, str]] | None = None,
+        gpu: Mapping[str, object] | None = None,
+        stage_mounts: Sequence[StageMount] | None = None,
+        mcp_servers: Sequence[str | McpServer | Mapping[str, object]] | None = None,
+        tags: Mapping[str, str] | None = None,
+        mount_snowflake_config: bool = True,
+        transport: SyncTransport | None = None,
+        connection: ConnectionLike | None = None,
+    ) -> Sandbox:
+        """Zip ``source_dir``, deliver it to the container via ``code_stage``, and
+        return a configured ``Sandbox`` ready for `create()`.
+
+        ``code_stage`` is **required**: the bundle is PUT to that (SSE) stage, a
+        presigned URL is minted, and the container downloads it from cloud storage
+        at start (``SNOWFLAKE_CODE_URL``). The zip is named
+        ``{dir_name}_{hash16}.zip`` so repeated calls with unchanged code reuse the
+        same object. The returned sandbox is NOT yet created; call ``create()`` or
+        use ``with``.
+
+        ``exclude`` / ``include`` are gitignore-style patterns over the tree, applied
+        by the same engine as `Sandbox.upload_dir` and ``snow sandbox run``: build
+        output, VCS state and credential-shaped files are left out by default, and
+        ``include`` re-admits a path the defaults dropped (``include=["dist/**"]`` to
+        ship a built artifact). Anything dropped that a caller probably did not intend
+        -- a symlinked directory, an unreadable entry -- is warned about, because the
+        bundle is otherwise indistinguishable from a complete one.
+
+        The stage PUT authenticates from the environment when it is set
+        (``SNOWFLAKE_ACCOUNT_URL`` + ``SNOWFLAKE_TOKEN``, both injected by Snowflake
+        into sandbox containers), and otherwise from the SDK's resolved
+        `config.Config` -- an explicit ``connection=`` or a ``~/.snowflake``
+        connection is enough, and no longer has to be repeated as a second set of
+        differently-named env vars.
+        ``connection`` picks the Snowflake connection for this call; the handle carries it
+        onward. See `config.using` for the resolution rules (names, live connections,
+        memoisation, and how an enclosing ``using()`` block interacts).
+
+        """
+        from pathlib import Path as _Path
+
+        src = _Path(source_dir).resolve()
+        # Resolve connection=/transport= ONCE, up front, and use it for everything this
+        # method does. The stage work below (CREATE STAGE / PUT / presigned-URL mint)
+        # and the Image lookup both authenticate through the transport, so leaving them
+        # on the raw ``transport`` (None when the caller passed only ``connection=``)
+        # would upload the code under the AMBIENT connection while the sandbox itself
+        # ran on the named one.
+        effective_transport = _transport_for(connection, None, transport)
+        # Resolve an Image reference to its catalog name before it rides the create
+        # body; create() already does this, so a str passes through unchanged.
+        image = _coerce_image(image, effective_transport)
+
+        files, bundle_plan = _collect_tree(src, exclude=exclude, include=include)
+        # A bundle that quietly lost a vendored tree used to look identical to a
+        # complete one. Warn about the drops a caller would want to know about --
+        # not the ordinary VCS/build filtering, which is the whole point of it.
+        _warn_notable_bundle_skips(src, bundle_plan)
+        hash16 = _hash_files(files)
+        # `src.name` is a local directory basename (attacker-influenceable); squash
+        # it to a safe charset so it cannot break out of the PUT `'file://...'`
+        # literal or the presigned path. The hash16 is the real content key.
+        filename = f"{_safe_stage_filename(src.name)}_{hash16}.zip"
+        zip_bytes = _zip_files(files)
+
+        if code_stage:
+            # Direct presigned-URL download (works in dev + prod): PUT the bundle to
+            # an SSE named stage, mint a presigned URL, and let the container GET it
+            # from cloud storage. Snowflake's system egress allowlist permits reaching the
+            # stage's S3 bucket; SNOWFLAKE_SSE makes the GET return plaintext. No
+            # FUSE mount, no in-container credential.
+            import os
+            import tempfile
+
+            # Validate the stage name as an identifier before it touches any SQL:
+            # `code_stage` comes from config / CLI / CI, so an unvalidated value
+            # (e.g. "S LOCATION='s3://attacker/'") would create an external stage at
+            # an attacker bucket and PUT the bundle there, as the caller's role.
+            _validate_stage_identifier(code_stage)
+            conn, owns = _connect_for_stage(effective_transport)
+            try:
+                cur = conn.cursor()
+                # IDENTIFIER(%s) binds the (validated) name as data; %s is pyformat,
+                # the connector's default paramstyle.
+                cur.execute(
+                    "CREATE STAGE IF NOT EXISTS IDENTIFIER(%s) "
+                    "ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE')",
+                    (code_stage,),
+                )
+                with tempfile.TemporaryDirectory() as _tmpdir:
+                    local_zip = os.path.join(_tmpdir, filename)
+                    with open(local_zip, "wb") as _f:
+                        _f.write(zip_bytes)
+                    # PUT has no IDENTIFIER form; code_stage is a validated identifier
+                    # and local_zip/filename are squashed to a safe charset.
+                    cur.execute(
+                        f"PUT 'file://{local_zip}' @{code_stage}/ "
+                        "AUTO_COMPRESS=FALSE OVERWRITE=TRUE"
+                    )
+                # Both args bound as data — the stage location and filename never
+                # enter the SQL text.
+                cur.execute(
+                    "SELECT GET_PRESIGNED_URL(%s, %s, 3600)",
+                    (f"@{code_stage}", filename),
+                )
+                _row = cur.fetchone()
+                code_url = _row[0] if _row else ""
+            finally:
+                if owns:
+                    conn.close()
+            stage_path = None
+        else:
+            # No code_stage: the only other delivery the SDK knew how to do was PUT
+            # to @~ and inject SNOWFLAKE_CODE_STAGE_PATH — which the container runtime
+            # never reads (it downloads only from the presigned SNOWFLAKE_CODE_URL),
+            # so the bundle silently never arrived and the entry was "not found".
+            # Reject that dead path instead of shipping a container that can't run.
+            raise SandboxError(
+                "code delivery requires code_stage=: the container downloads the "
+                "bundle from the presigned URL that code_stage mints, and ignores the "
+                "@~ stage path the no-code_stage path used to inject — so the code "
+                "never arrived and the entry was 'not found'. Pass "
+                "code_stage='DB.SCHEMA.STAGE' (an SSE stage the SDK auto-creates), or "
+                "deliver code by mounting a stage (stage_mounts=[StageMount.from_stage"
+                "(...)]) and pointing the command at the mount path."
+            )
+
+        sb = cls(
+            image=image,
+            memory=memory,
+            cpu=cpu,
+            command=command,
+            stage_path=stage_path,
+            env=env,
+            egress=egress,
+            secrets=secrets,
+            gpu=gpu,
+            stage_mounts=stage_mounts,
+            mcp_servers=mcp_servers,
+            tags=tags,
+            transport=effective_transport,
+            _internal=True,
+        )
+        # SNOWFLAKE_CODE_URL is the presigned URL the container GETs at start. It is a
+        # server-reserved platform key, so it rides the `sandbox_env` channel, NOT the
+        # user `env` map: the server rejects a SNOWFLAKE_ key on the env map with
+        # `400 env key "SNOWFLAKE_CODE_URL" is reserved`, which took down the whole
+        # deploy / from_local / Function.remote path.
+        sb._add_platform_env("SNOWFLAKE_CODE_URL", code_url)
+        # Platform env minted by a deploy caller — agent_session()'s session reply
+        # nonce, deploy_async()'s SANDBOX_JOB_* runner vars — rides the same channel
+        # rather than the user `env` map, through the same guarded chokepoint.
+        for _pk, _pv in (platform_env or {}).items():
+            sb._add_platform_env(_pk, _pv)
+        sb._mount_snowflake_config = mount_snowflake_config
+        return sb
+
+    # ----- public factory --------------------------------------------
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        image: str | Image = "",
+        code: str | Path | None = None,
+        command: Sequence[str] | None = None,
+        memory: MemoryTier = "4g",
+        cpu: float | None = None,
+        env: Mapping[str, str] | None = None,
+        secrets: Sequence[Secret | Mapping[str, str]] | None = None,
+        egress: Egress | Mapping[str, object] | None = None,
+        code_stage: str | None = None,
+        name: str | None = None,
+        gpu: Mapping[str, object] | None = None,
+        stage_mounts: Sequence[StageMount] | None = None,
+        mcp_servers: Sequence[str | McpServer | Mapping[str, object]] | None = None,
+        tags: Mapping[str, str] | None = None,
+        role: str | None = None,
+        mount_snowflake_config: bool = True,
+        idle_suspend: dt.timedelta | str | None = None,
+        transport: SyncTransport | None = None,
+        connection: ConnectionLike | None = None,
+        wait: bool = True,
+    ) -> Sandbox:
+        """Create a sandbox and return a live handle — the one-call factory.
+
+        Pass ``code=`` to bundle and upload a local project (a directory) instead of running inline ``exec`` commands. When
+        ``code`` is a directory whose ``command`` runs a *bundled file* (e.g.
+        ``["python", "main.py"]``), you MUST pass ``code_stage`` — a Snowflake
+        stage the bundle is uploaded to and delivered from (via a presigned URL)
+        into the container, so the entry file is present at run time.
+
+        ``role`` sets the Snowflake role for this sandbox's session. A single
+        named connection is sufficient — role-scoped sessions
+        are minted lazily on demand. When omitted, the default session's role
+        is used. The role is returned by the server and stored on ``sb.role``.
+
+        ``connection`` picks the Snowflake connection for this sandbox — a name in
+        ``~/.snowflake/connections.toml``, a
+        live ``snowflake.connector`` connection the caller already opened, a Snowpark
+        ``Session`` (what you hold inside Streamlit-in-Snowflake and stored procedures),
+        or a `Config` you assembled from raw credentials (mirroring the connector's
+        ``connect(connection_name=...)``). The handle carries it, so everything you do
+        with the returned sandbox goes over that connection. The accepted shapes are
+        typed as `ConnectionLike`.
+
+        The transport is POOLED per credential identity, not owned by the handle:
+        exiting terminates the sandbox and leaves the HTTP client open for the next call
+        on that connection (``shutdown()``/``shutdown_sync()`` release it), and two
+        sandboxes on one connection share a client rather than opening two. Resolution
+        is memoised, so naming it call after call costs one connector login. ``role=``
+        composes (the session is minted under that role). Mutually exclusive with
+        ``transport=``. Omit to use an enclosing ``using()`` block, else the default
+        connection.
+
+        ``transport=`` is NOT part of the public surface: its type
+        (``Transport`` / ``SyncTransport``) lives in a private module and is not exported
+        from ``snowflake.sandbox``, so there is no supported way for a caller outside this
+        SDK to construct one. It exists as a seam for this SDK's own tests and for
+        internal hydration. Use ``connection=`` — it covers a connection name, a live
+        ``snowflake.connector`` connection, a Snowpark ``Session``, and a `Config` you
+        assembled yourself.
+
+        ``mount_snowflake_config`` (default True) has the platform render the
+        sandbox's Snowflake config so `snow`/`cortex`/the connector authenticate
+        with no setup. Set it False to manage your own: the platform then writes no
+        ``connections.toml``, sets no ``SNOWFLAKE_HOME``, **and** omits the
+        ``SNOWFLAKE_*`` connection env. So an opting-out caller must supply a full
+        connection itself, not just a token — a bare ``snow sql`` /
+        ``connector.connect()`` otherwise fails with "Connection default is not configured".
+
+        A ``command`` is treated as a **detached run-to-completion entrypoint**:
+        it is wrapped so `wait()` can recover its exit code and result. Keep its
+        ``id``, let the driver exit, and later `connect()` + `wait()`. For a
+        **long-lived daemon** (a `sandbox.session_loop()` you drive with `send()`)
+        use ``@app.session`` / `agent_session()`, which deploys it detached and
+        hands back a `Session`.
+
+        ``cpu`` overrides the CPU allocation in fractional cores, decoupling it
+        from ``memory``. Omit it and the memory tier's default applies (1g->1,
+        4g->2, 8g->3, 16g->4, 32g->6, 64g->8). Range is 0.25 to 8.0; out-of-range values are
+        rejected by the server with a 400. Note a sandbox's identity includes its
+        CPU limit, so changing ``cpu`` yields a distinct sandbox rather than
+        reusing one sized differently.
+
+        ``gpu`` is a forward-compatible on-ramp: a mapping (``type``, ``count``,
+        ``profile``, ``warm_pool``) passed through to the REST create body
+        verbatim. Omitting it leaves the body unchanged (today's CPU behavior);
+        the Snowflake backend 501s on a ``gpu`` request until GPU support lands.
+
+        ``stage_mounts`` mounts Snowflake stages into the container's filesystem —
+        a sequence of `StageMount` (e.g. ``StageMount.from_stage("@DB.SCHEMA.DATA",
+        mount_path="/mnt/data")``). This is the supported path for bulk/stage-backed data:
+        read and write through the mount rather than via ``stage_put``/``stage_get``
+        (unimplemented — see below). Mount paths are validated against a
+        reserved-root denylist.
+
+        ``mcp_servers`` exposes EXTERNAL MCP SERVERs to the container, named the
+        way every other Snowflake surface names them -- by FQN:
+        ``mcp_servers=["MYDB.MYSCHEMA.GITHUB_MCP_SERVER"]``, or `McpServer` to
+        override the client-facing name or transport profile. Snowflake resolves the
+        endpoint, the API integration, and *your* OAuth secret server-side; the
+        container gets a dummy in ``SANDBOX_MCP_TOKEN_<NAME>`` and the egress proxy
+        swaps in the real token on the wire. A server you have not authorized is
+        omitted. `list_mcp_servers()` shows what this account has and whether you
+        have connected it.
+
+        ``tags`` attaches a ``dict[str, str]`` of caller metadata (the server's
+        ``labels``), readable back via `get_tags()`. Tags can be set **only at
+        create** — the backend has no relabel endpoint, so `set_tags()` on a
+        running sandbox raises. They are metadata only and do not affect
+        scheduling or container identity.
+
+        ``idle_suspend`` sets how long this sandbox may sit idle (no inbound
+        traffic) before CNG auto-suspends it, overriding CNG's global default —
+        a ``datetime.timedelta`` or a duration string like ``"30m"``/``"2h"``.
+        CNG's resolution is minutes, so a value that is not a whole number of
+        minutes raises, and a bare number is rejected (be explicit about units).
+        Omit for the default; a value at or above the sandbox's max lifetime is
+        effectively "never suspend".
+        """
+        # connection= means here exactly what it means on every other entry point:
+        # resolve it (memoised) and use the pooled transport for that credential
+        # identity. See `_transport_for`. Mutually exclusive with transport=.
+        if connection is not None:
+            effective_transport: SyncTransport | None = _transport_for(connection, role, transport)
+        else:
+            # Resolve the ambient connection AT this role before the transport reads
+            # it mid-request, and refuse if the role did not take effect -- on create
+            # the role becomes the sandbox's own identity, so silently falling back to
+            # the default one is never right.
+            if role is not None and transport is None:
+                from snowflake.sandbox.config import prime_role_config
+
+                prime_role_config(role)
+            # Route to the role-keyed transport when role= is given. An explicit
+            # transport= always wins; it is the SDK's internal seam, not caller API.
+            effective_transport = transport or (get_sync_transport(role) if role else None)
+        # User tags only. The role is carried by the role-scoped session token
+        # (routed via the transport above), not in tags or the create body; the
+        # server echoes it back as a first-class field from the session identity.
+        effective_tags = tags
+        # An Image reference / str resolves to a catalog name here, so both dispatch
+        # branches get a plain string.
+        image = _coerce_image(image, transport)
+        if code is not None:
+            from pathlib import Path as _Path
+
+            p = _Path(code)
+            if p.is_file():
+                raise SandboxError(
+                    f"code= takes a project directory, got a file: {p}. "
+                    "sandbox.toml is retired — declare the app in Python "
+                    "(App + @app.function) and use fn.remote()."
+                )
+            sb = cls.from_local(
+                p,
+                command=command,
+                image=image,
+                memory=memory,
+                cpu=cpu,
+                code_stage=code_stage,
+                env=env,
+                egress=egress,
+                secrets=secrets,
+                gpu=gpu,
+                stage_mounts=stage_mounts,
+                mcp_servers=mcp_servers,
+                tags=effective_tags,
+                transport=effective_transport,
+            )
+        else:
+            sb = cls(
+                image=image,
+                memory=memory,
+                cpu=cpu,
+                env=env,
+                command=command,
+                egress=egress,
+                secrets=secrets,
+                name=name,
+                gpu=gpu,
+                stage_mounts=stage_mounts,
+                mcp_servers=mcp_servers,
+                tags=effective_tags,
+                transport=effective_transport,
+                _internal=True,
+            )
+        sb._role = role
+        sb._idle_suspend_minutes = _idle_suspend_minutes(idle_suspend)
+        sb._mount_snowflake_config = mount_snowflake_config
+        # A run-to-completion command is wrapped so wait() can recover its exit
+        # code + result.
+        if sb._command:
+            sb._command, sb._result_nonce = _wrap_detached(sb._command)
+        # create() owns readiness below (strict, and honouring wait=).
+        sb._settle_on_create = False
+        start_attempt = 0
+        while True:
+            sb._ensure_created()
+            # Poll for readiness only when the server responded 202 (async create).
+            # wait=False lets callers batch-wait via sb.wait_until_ready() -- there is
+            # no readiness wait here, so no terminal failure to react to.
+            if not (wait and sb._async_pending):
+                return sb
+            try:
+                sb._wait_until_ready()
+                return sb
+            except BaseException as exc:
+                # Capture retryability BEFORE cleanup: _terminate_impl() flips _status
+                # to "dead", which would mask the "failed" + (retryable) signal.
+                retryable = isinstance(exc, Exception) and is_retryable_start_failure(
+                    sb._status, sb._error_message
+                )
+                # The container EXISTS server-side. Propagating (or re-creating)
+                # without cleanup would leave it running and billed with no handle
+                # ever reaching the caller.
+                try:
+                    sb._terminate_impl()
+                except Exception:
+                    pass
+                # A *retryable* StartApp failure means the app never started (the
+                # controller exhausted its own attempts and tagged it retryable), so a
+                # fresh container is safe to create and may land on a healthy host.
+                # Bounded; any other failure -- or a spent budget -- propagates.
+                if retryable:
+                    delay = compute_backoff(
+                        start_attempt + 1, delays=DEFAULT_START_FAILURE_DELAYS_S
+                    )
+                    if delay is not None:
+                        start_attempt += 1
+                        sb._reset_for_recreate()
+                        time.sleep(delay)
+                        continue
+                raise
+
+    @classmethod
+    def connect(
+        cls, name: str, *, role: str | None = None, connection: ConnectionLike | None = None
+    ) -> Sandbox:
+        """Reconnect to an existing sandbox by its NAME (the identity `list` shows),
+        for example after your driver restarts. The name is unique per owner.
+
+        ``role`` resolves this call's connection AT that role.
+
+        ``connection`` picks the Snowflake connection for this call; the handle carries it
+        onward. See `config.using` for the resolution rules (names, live connections,
+        memoisation, and how an enclosing ``using()`` block interacts).
+
+        Example:
+            sb = Sandbox.connect("my-agent")
+            result = sb.exec(["python", "-c", "print('still running')"])
+        """
+        return get_sandbox_by_name(name, role=role, connection=connection)
+
+    @classmethod
+    def list(
+        cls,
+        *,
+        status: SandboxStatus | None = None,
+        role: str | None = None,
+        include_old_apps: bool = False,
+        connection: ConnectionLike | None = None,
+    ) -> list[Sandbox]:
+        """Return the sandboxes the caller can see, optionally filtered by status.
+
+        Accepts the same filters as the module-level `list_sandboxes()`, which
+        this delegates to. ``role`` resolves this call's connection AT that role
+        (see ``Sandbox.create(role=...)``); without it a caller using the
+        multi-role pattern could not list the sandboxes they had just created
+        under a non-default role.
+
+        ``include_old_apps`` widens the default view: on a server version that
+        supports it, the server otherwise returns the live set plus sandboxes
+        stopped within the last 24h. On older servers the list route ignores the
+        param (it does no unknown-param rejection, so sending it early is a no-op,
+        not a 400).
+
+        ``connection`` picks the Snowflake connection for this call; the handle carries it
+        onward. See `config.using` for the resolution rules (names, live connections,
+        memoisation, and how an enclosing ``using()`` block interacts).
+
+        Example:
+            sandboxes = Sandbox.list()
+            for sb in sandboxes:
+                print(sb.id, sb.status)
+
+            # What MY_ROLE can see. Resolved from the ambient connection at that role;
+            # under a bare env token, which carries its own role, role= only applies the
+            # server-side ?role= filter.
+            mine = Sandbox.list(role="MY_ROLE")
+        """
+        return list(
+            list_sandboxes(
+                status=status, role=role, include_old_apps=include_old_apps, connection=connection
+            )
+        )
+
+    # ----- exec -------------------------------------------------------
+
+    def exec(
+        self,
+        cmd: Sequence[str],
+        *,
+        stdin: bytes | None = None,
+        env: Mapping[str, str] | None = None,
+        timeout: float | None = None,
+        working_dir: str | None = None,
+        text: bool = True,
+    ) -> ExecResult:
+        """Run a command to completion and return an ExecResult.
+
+        Raises `SandboxExecError` on non-zero exit. For line-by-line streaming
+        output use `exec_stream()` instead.
+
+        Note:
+            There is no `pty=` option: exec is pipe-based with separate
+            stdout/stderr. For pseudo-terminal semantics use `shell()`.
+
+            `stdin`, `env`, `working_dir`, and `text=False` are present in the
+            signature but not supported by this method — passing any of them
+            raises `SandboxError`. Use `exec_stream(cmd, env=..., working_dir=...)`
+            for per-call environment or working directory, or set `env` once at
+            create time with `Sandbox(env=...)`.
+
+        Example:
+            result = sb.exec(["python", "-c", "print(40 + 2)"])
+            print(result.stdout)   # "42\\n"
+        """
+        _require_nonempty_cmd(cmd, caller="exec")
+        _require_str_cmd(cmd, caller="exec")
+        unsupported = [
+            name
+            for name, given in (
+                ("stdin", stdin is not None),
+                ("env", env is not None),
+                ("working_dir", working_dir is not None),
+                ("text=False", text is False),
+            )
+            if given
+        ]
+        if unsupported:
+            raise SandboxError(
+                f"exec() cannot carry {', '.join(unsupported)}: the unary exec "
+                "contract is {code, language, timeout_seconds}. Use "
+                "exec_stream(cmd, env=..., working_dir=...) for per-call env or "
+                "working directory, or set env at create time with "
+                "Sandbox(env=...); stdin and text=False are not supported by "
+                "either path yet."
+            )
+        # Resolved before _ensure_created(): a timeout this method can reject
+        # locally must not cost the caller a provisioned sandbox first.
+        exec_budget_s = _resolve_exec_budget(timeout, caller="exec")
+        if not self._created:
+            self._ensure_created()
+        if self._id is None:  # pragma: no cover - defensive
+            raise SandboxError(
+                "operation failed: sandbox has no id (this is a bug — create() should have set it)"
+            )
+
+        code = _cmd_to_code(cmd)
+
+        # The REST exec route: POST {base_path}/containers/{id}/exec with the
+        # {code, language, timeout_seconds} contract (the HTTP /execute path the
+        # Snowflake hostagent proxies to the container). `code` above is always Python
+        # -- a `python -c` passthrough, or a subprocess wrapper for arbitrary
+        # argv -- so language is "python".
+        #
+        # The server owns the exec deadline; the client's read timeout is that
+        # budget plus a grace margin so the server's 408 always wins the race.
+        # `timeout_seconds` is an int on the wire, so a sub-second budget rounds
+        # UP to 1s rather than truncating to 0 (which the server reads as
+        # "unset" and replaces with its own default).
+        import math
+
+        exec_body: dict[str, Any] = {
+            "code": code,
+            "language": "python",
+            "timeout_seconds": max(1, math.ceil(exec_budget_s)),
+        }
+        t0 = time.monotonic()
+        resp = self._transport.request(
+            "POST",
+            f"containers/{self._id}/exec",
+            json_body=exec_body,
+            timeout=exec_budget_s + _EXEC_TIMEOUT_GRACE_S,
+        )
+        elapsed_ms = int((time.monotonic() - t0) * 1000)
+        # The keep-alive whitespace the server flushes before the real body is
+        # harmless -- json.loads skips leading whitespace -- but a body that is
+        # *only* padding (connection died after the status line, before any JSON)
+        # must not escape as a bare JSONDecodeError: callers guarding the exec
+        # with `except SandboxError` would miss it entirely. Reported as
+        # unparseable rather than as a missing field, which is what it is.
+        try:
+            payload = resp.json() if resp.content else {}
+        except ValueError as exc:
+            raise SandboxExecError(
+                f"exec response was not JSON ({len(resp.content)} bytes): {exc}",
+                exit_code=-1,
+            ) from exc
+        if not isinstance(payload, dict):
+            raise SandboxError(f"unexpected exec response: {payload!r}")
+        stdout = payload.get("stdout", "") or ""
+        stderr = payload.get("stderr", "") or ""
+
+        # A 200 does NOT mean the exec ran. The server writes its status line
+        # before starting the exec (it then flushes keep-alive whitespace to
+        # survive proxy idle timeouts), so a failure afterwards can only be
+        # reported in the body: `{"error": {"message": ..., "type": ...}}` under
+        # an already-sent 200, with no exit_code. Defaulting a missing exit_code
+        # to 0 turned that into a silent success with empty output — the worst
+        # possible reading of a server error. `exit_code` has no `omitempty` on
+        # the wire, so its absence always means "this is not an exec result".
+        #
+        # exec is the ONLY endpoint where a 200 can carry a failure, and this
+        # handling belongs nowhere else. It is needed here because exec must
+        # commit a status before its outcome is known; every other endpoint
+        # writes its status and body together in one call,
+        # so a failure there arrives as a real error status and `_transport`
+        # raises on anything >= 400 before a parse is ever reached. Copying this
+        # onto logs()/list_sandboxes()/wait() would be unreachable code implying
+        # a hazard those paths do not have -- there, an absent field genuinely
+        # means "empty", not "the server failed".
+        err = payload.get("error")
+        if isinstance(err, Mapping) and err.get("message"):
+            err_type = err.get("type")
+            raise SandboxExecError(
+                f"exec failed server-side: {err.get('message')}"
+                + (f" (type={err_type})" if err_type else ""),
+                exit_code=-1,
+                stdout=stdout,
+                stderr=stderr,
+            )
+        if payload.get("exit_code") is None:
+            raise SandboxExecError(
+                f"exec response carried no exit_code: {str(payload)[:200]}",
+                exit_code=-1,
+                stdout=stdout,
+                stderr=stderr,
+            )
+        exit_code = int(payload.get("exit_code") or 0)
+        result = ExecResult(
+            stdout=stdout, stderr=stderr, exit_code=exit_code, elapsed_ms=elapsed_ms
+        )
+        if bool(payload.get("timed_out")) or exit_code == 124:
+            # timed_out is authoritative; the exit code is not. /execute reports 124,
+            # while guest-init normalises a signal death to 128+signal so its deadline
+            # arrives as 137 with empty stderr -- previously a generic SandboxExecError,
+            # indistinguishable from an OOM kill. 124 stays as a fallback for a server
+            # predating the field. The partial output rides on the exception because it
+            # is how a caller tells "the work started" from "it never did". #266
+            raise SandboxExecTimeoutError(
+                f"exec exceeded its timeout (exit code {exit_code})",
+                exit_code=exit_code,
+                stdout=stdout,
+                stderr=stderr,
+            )
+        if exit_code != 0:
+            raise SandboxExecError(
+                f"exec exited with code {exit_code}",
+                exit_code=exit_code,
+                stdout=stdout,
+                stderr=stderr,
+            )
+        return result
+
+    def exec_stream(
+        self,
+        cmd: Sequence[str],
+        *,
+        stdin: bytes | None = None,
+        env: Mapping[str, str] | None = None,
+        timeout: float | None = None,
+        working_dir: str | None = None,
+    ) -> SyncExecStream:
+        """Stream a command's output line by line. Returns a `SyncExecStream` iterator.
+
+        Resumable: if the connection is cut (the ingress drops it at ~180s),
+        `exec_stream` reconnects and continues from where output left off.
+        The command keeps running inside the sandbox; no output is lost.
+
+        Note:
+            There is no `pty=` option: exec_stream uses pipes with separate
+            stdout/stderr. For TTY semantics use `shell()`.
+
+        Example:
+            for line in sb.exec_stream(["python", "generate_report.py"]):
+                print(line.stream, line.data)
+        """
+        _require_nonempty_cmd(cmd, caller="exec_stream")
+        _require_str_cmd(cmd, caller="exec_stream")
+        if stdin is not None:
+            raise SandboxError(
+                "exec_stream() cannot carry stdin: the streaming exec contract is "
+                "{cmd, env, timeout_s, working_dir} and does not include stdin "
+                "(neither exec() nor exec_stream() supports it yet)."
+            )
+        # Validated eagerly. _exec_stream_frames resolves it again, but that is
+        # a generator: a raise in its body would not fire until the caller began
+        # iterating, so exec_stream(timeout=inf) would hand back a stream object
+        # that only failed later.
+        _resolve_exec_budget(timeout, caller="exec_stream")
+        sse_iter = self._exec_stream_frames(cmd, env, timeout, working_dir)
+        return SyncExecStream(sse_iter)
+
+    def _exec_stream_frames(
+        self,
+        cmd: Sequence[str],
+        env: Mapping[str, str] | None,
+        timeout: float | None,
+        working_dir: str | None,
+    ) -> Iterator[SSEEvent]:
+        """Open the streaming exec and yield its frames, reconnecting on a cut.
+
+        The fresh request runs the command; the container answers with a
+        ``session`` frame naming an ``exec_session``, then output frames each
+        carrying a monotonic ``id:``. On a transport cut (the ~180s GOAWAY) or a
+        clean close with no terminal frame, this reopens the SAME ``/exec`` route
+        with ``{exec_session, last_event_id}`` in the body -- which REATTACHES to
+        the running command from that cursor instead of re-running it -- and keeps
+        yielding. The cursor rides the body because that is the channel the
+        gateway forwards verbatim.
+
+        The ``session`` frame is consumed here (it is transport bookkeeping, not
+        output); every other frame is yielded to ``ExecStream`` to interpret.
+        """
+        if not self._created:
+            self._ensure_created()
+        if self._id is None:  # pragma: no cover - defensive
+            raise SandboxError(
+                "exec_stream() failed: sandbox has no id (this is a bug — create() should have set it)"
+            )
+
+        # Same rule as exec(): the server owns the deadline, the client waits
+        # longer than it does so a live exec is never abandoned client-side.
+        exec_budget_s = _resolve_exec_budget(timeout, caller="exec_stream")
+        read_timeout = exec_budget_s + _EXEC_TIMEOUT_GRACE_S
+        endpoint = f"containers/{self._id}/exec"
+        fresh_body = _fresh_exec_body(cmd, env, working_dir, exec_budget_s)
+
+        exec_session: str | None = None
+        cursor = 0
+        attempt = 0
+        while True:
+            # Fresh run first; once the session is known, every reopen is a resume
+            # from the cursor and must NOT re-send cmd (which would re-run it).
+            # terminate() fired here would resume a dead sandbox.
+            _raise_if_stream_terminated(self._stream_abort)
+            body: dict[str, Any] = (
+                dict(fresh_body)
+                if exec_session is None
+                else {"exec_session": exec_session, "last_event_id": cursor}
+            )
+            delivered = False
+            try:
+                for evt in self._transport.stream_sse(
+                    "POST",
+                    endpoint,
+                    json_body=body,
+                    timeout=read_timeout,
+                    abort=self._stream_abort,
+                ):
+                    if evt.event == "session":
+                        exec_session = _exec_session_id(evt) or exec_session
+                        continue
+                    cursor = _advance_exec_cursor(cursor, evt)
+                    if evt.event in ("stdout", "stderr", "gap"):
+                        delivered = True
+                        attempt = 0
+                    yield evt
+                    if evt.event in ("exit", "error"):
+                        return  # terminal; reconnecting would re-attach pointlessly
+                # Clean close with no terminal frame: the ordinary ~180s cut on a
+                # still-running command. Resume if we can identify the session;
+                # otherwise fall through to ExecStream, which raises truncation.
+                #
+                # An aborted read arrives here too, and looks identical: shutting the
+                # socket down ends iteration at EOF rather than raising. Only the
+                # abort flag distinguishes "terminate() was called" from "the ingress
+                # cut us and the command is still running", so it has to be checked
+                # before resuming.
+                _raise_if_stream_terminated(self._stream_abort)
+                if exec_session is None:
+                    return
+            except SandboxTransportError:
+                # The GOAWAY / mid-stream cut. Resumable only once the session is
+                # known; before that a reopen would re-run the command, so re-raise.
+                # terminate() fired mid-read takes priority: do not resume.
+                _raise_if_stream_terminated(self._stream_abort)
+                if exec_session is None:
+                    raise
+                if _exec_reconnect_exhausted(attempt, delivered=delivered):
+                    raise
+            if _exec_reconnect_exhausted(attempt, delivered=delivered):
+                # Reopened repeatedly with nothing to show: treat as dead rather
+                # than reconnect forever. ExecStream reports the truncation.
+                return
+            time.sleep(_EXEC_RECONNECT_DELAYS[min(attempt, len(_EXEC_RECONNECT_DELAYS) - 1)])
+            attempt += 1
+
+    # ----- detached run (wait) ----------------------------------------
+
+    def _probe_managed_exit_code(self) -> None:
+        """Best-effort read of the managed process's exit code from the cheap
+        read-only ``GET /containers/{id}/status`` route.
+
+        Unlike the ``?refresh=true`` probe, this route does not re-drive
+        ``StartApp`` (no resume, no idle-timer reset, no egress strip). Populates
+        ``self._exit_code`` / ``_generation`` from the response. Silent on any
+        failure — the route is absent on older servers (a fast 404, not retried) —
+        so ``exit_code`` simply stays whatever `refresh()` already had.
+        """
+        if self._id is None:  # pragma: no cover - defensive
+            return
+        try:
+            resp = self._transport.request(
+                "GET", f"containers/{self._id}/status", retry_not_found=False
+            )
+        except SandboxError:
+            return
+        payload = resp.json() if resp.content else {}
+        if isinstance(payload, dict):
+            self._absorb_read_fields(payload)
+
+    def wait(self, *, timeout: float | None = None, poll_s: float = 3.0) -> RunResult:
+        """Wait for a detached run to finish and return its result.
+
+        For sandboxes created with `Sandbox.create(command=...)`. Returns a
+        `RunResult` with `status` (`'succeeded'`, `'failed'`, or `'timed_out'`),
+        `exit_code`, and the parsed `result` artifact.
+
+        Example:
+            sb = Sandbox.create(
+                command=["python", "main.py"],
+            )
+            result = sb.wait()
+            print(result.status, result.exit_code)
+        """
+        import time as _time
+
+        from snowflake.sandbox.jobs import RunResult, _parse_result_sentinel
+
+        if self._id is None:
+            raise SandboxError("wait() requires a created sandbox (with a command)")
+        deadline = (_time.monotonic() + timeout) if timeout is not None else None
+        while True:
+            # Only trust the stdout sentinel when we hold the run's nonce; without
+            # it (the connect() reconnect path) fall through to the server-reported
+            # exit code rather than accepting a forgeable, unauthenticated line.
+            if self._result_nonce is not None:
+                parsed = _parse_result_sentinel(self.logs(), nonce=self._result_nonce)
+                if parsed is not None:
+                    parsed.logs_ref = self._id
+                    return parsed
+            # A terminal container with no (trusted) sentinel means the run died
+            # without reporting, or we cannot authenticate its report.
+            # `refresh()` maps the server's own vocabulary
+            # ("crashed"/"stopped"), which a literal `status == "dead"` test never
+            # matched -- so this loop used to run to the deadline instead.
+            if self.refresh() in TERMINAL_STATUSES:
+                # Read the real exit code from the cheap status route so a run that
+                # left no sentinel still reports it. Best-effort:
+                # on a server without that route exit_code stays None and we keep the
+                # conservative "failed".
+                self._probe_managed_exit_code()
+                ec = self._exit_code
+                status: RunStatus = "succeeded" if ec == 0 else "failed"
+                return RunResult(status=status, exit_code=ec, result=None, logs_ref=self._id)
+            if deadline is not None and _time.monotonic() + poll_s >= deadline:
+                return RunResult(status="timed_out", exit_code=None, result=None, logs_ref=self._id)
+            _time.sleep(poll_s)
+
+    # ----- warm agent (send) ------------------------------------------
+
+    def send(self, message: str, *, timeout: float = 120.0, poll_s: float = 1.0) -> str:
+        """Send a message to a warm daemon in the sandbox and return its reply.
+
+        For sandboxes running `session_loop` as their managed process. The daemon
+        keeps state warm in process memory across turns.
+
+        Example:
+            sb = Sandbox.create(
+                command=["python", "daemon.py"],
+            )
+            reply = sb.send("what changed in prod yesterday?")
+            print(reply)
+        """
+        import time as _time
+        import uuid as _uuid
+
+        from snowflake.sandbox.exceptions import SandboxExecTimeoutError
+        from snowflake.sandbox.warm_session import (
+            _ended_before_reply,
+            _mailbox_append_cmd,
+            _parse_reply_sentinel,
+        )
+
+        if not self._created:
+            self._ensure_created()
+        msg_id = _uuid.uuid4().hex
+        self.exec(_mailbox_append_cmd(msg_id, message))
+        deadline = _time.monotonic() + timeout
+        while True:
+            reply = _parse_reply_sentinel(self.logs(), msg_id, nonce=self._reply_nonce)
+            if reply is not None:
+                return reply
+            # A terminal container will never reply; surface that rather than spending
+            # the whole timeout and then blaming the caller's message. refresh() (not
+            # the cached status) is the only live read of the container's lifecycle.
+            if self.refresh() in TERMINAL_STATUSES:
+                # One last read: the daemon may have replied just before exiting.
+                reply = _parse_reply_sentinel(self.logs(), msg_id, nonce=self._reply_nonce)
+                if reply is not None:
+                    return reply
+                raise SandboxError(_ended_before_reply(self.status, msg_id))
+            if _time.monotonic() + poll_s >= deadline:
+                raise SandboxExecTimeoutError(f"no reply for message {msg_id} within {timeout}s")
+            _time.sleep(poll_s)
+
+    def terminate(self) -> None:
+        """Terminate the sandbox (idempotent).
+
+        Stops the sandbox and releases its resources. Safe to call multiple times
+        — an already-terminated sandbox is fine. This is the preferred method;
+        `destroy()` is deprecated.
+        """
+        self._terminate_impl()
+
+    def poll(self) -> int | None:
+        """Return the exit code if the sandbox has terminated, or `None` if still running.
+
+        Example:
+            while (code := sb.poll()) is None:
+                time.sleep(1)
+            print("exit code:", code)
+        """
+        if self.refresh() not in TERMINAL_STATUSES:
+            return None
+        # Terminal: fill in the managed process's exit code from the cheap
+        # read-only status route if `refresh()` did not already carry it.
+        if self._exit_code is None:
+            self._probe_managed_exit_code()
+        return self._exit_code if self._exit_code is not None else _POLL_UNKNOWN_EXIT_CODE
+
+    # ----- Modal-parity stubs ------------------------------------------
+    #
+    # Every method below has a real counterpart in Modal's modal.Sandbox
+    # reference but no backend here yet. Each raises `SandboxNotImplementedError`
+    # immediately so the surface is contract-complete (every Modal method
+    # resolves to *something* on this SDK) rather than silently absent — and so an
+    # unsupported call is distinguishable from an operational `SandboxError` and
+    # is not retried in a loop. Each docstring's FIRST line says so, because
+    # mkdocstrings renders these into the API reference and IDEs surface the first
+    # line: a customer/LLM must not read them as working features.
+
+    def snapshot_filesystem(self, *, timeout: float | None = None, ttl: float | None = None) -> str:
+        """Not implemented — raises `SandboxNotImplementedError`.
+
+        Would capture the sandbox's entire filesystem as a reusable image (Modal
+        Sandbox.snapshot_filesystem)."""
+        raise SandboxNotImplementedError("snapshot_filesystem() is not supported by the backend")
+
+    def snapshot_directory(
+        self, path: str, *, timeout: float | None = None, ttl: float | None = None
+    ) -> str:
+        """Not implemented — raises `SandboxNotImplementedError`.
+
+        Would capture one directory as a reusable image (Modal
+        Sandbox.snapshot_directory)."""
+        raise SandboxNotImplementedError("snapshot_directory() is not supported by the backend")
+
+    def mount_image(self, path: str, image: str) -> None:
+        """Not implemented — raises `SandboxNotImplementedError`.
+
+        Would attach a pre-built image at ``path`` inside the sandbox (Modal
+        Sandbox.mount_image)."""
+        raise SandboxNotImplementedError("mount_image() is not supported by the backend")
+
+    def unmount_image(self, path: str) -> None:
+        """Not implemented — raises `SandboxNotImplementedError`.
+
+        Would detach a previously mounted image (Modal Sandbox.unmount_image)."""
+        raise SandboxNotImplementedError("unmount_image() is not supported by the backend")
+
+    def tunnels(self, *, timeout: float | None = None) -> Mapping[int, str]:
+        """Not implemented — raises `SandboxNotImplementedError`.
+
+        Would return network tunnel metadata for reaching a port inside the
+        sandbox from outside (Modal Sandbox.tunnels). No Snowflake port-forwarding
+        support today."""
+        raise SandboxNotImplementedError("tunnels() is not supported by the backend")
+
+    def create_connect_token(
+        self, port: int, *, user_metadata: Mapping[str, str] | None = None
+    ) -> str:
+        """Not implemented — raises `SandboxNotImplementedError`.
+
+        Would mint short-lived HTTP access credentials for ``port`` (Modal
+        Sandbox.create_connect_token)."""
+        raise SandboxNotImplementedError("create_connect_token() is not supported by the backend")
+
+    def get_tags(self) -> Mapping[str, str]:
+        """Return the key-value tags attached to this sandbox.
+
+        Example:
+            tags = sb.get_tags()
+            print(tags.get("team"))
+        """
+        if self._id is not None:
+            self.refresh()
+        return dict(self._tags)
+
+    def set_tags(self, tags: Mapping[str, str]) -> None:
+        """Set key-value tags for this sandbox (must be called before creation).
+
+        Note:
+            Tags can only be set before `create()` is called. Pass `tags=` to
+            `Sandbox.create()` to set tags on an already-created sandbox.
+
+        Example:
+            with Sandbox.create(tags={"team": "sandbox", "env": "dev"}) as sb:
+                sb.exec(["python", "main.py"])
+        """
+        validated = _validate_tags(tags, context="set_tags()")
+        if self._created or self._id is not None:
+            raise SandboxError(_tags_post_create_message("Sandbox.create"))
+        self._tags = validated
+
+
+# ---- Module-level helpers ------------------------------------------------
+
+
+def _validate_status_filter(status: str | None) -> None:
+    """Reject a ``status=`` the SDK cannot filter on.
+
+    Raises rather than returning ``[]``, which is the whole of #207: a typo silently
+    produced an empty list and reaper/monitoring code read that as "nothing to do".
+
+    Called from a non-generator wrapper so it fires at CALL time. Inside a generator
+    body it only fired on first iteration, so ``it = list_sandboxes(status="bogus")``
+    raised nothing and a caller who never iterated never found out. Same bug class as
+    the ``exec_stream`` guard.
+    """
+    if status is None or status in SANDBOX_STATUSES:
+        return
+    raise SandboxError(
+        f"invalid status {status!r}. Must be one of: "
+        f"{', '.join(sorted(SANDBOX_STATUSES))}. "
+        f"These are the SDK's own status words, not the server's raw vocabulary: "
+        f"'ready' covers raw running/ready/suspended, 'pending' covers raw "
+        f"starting/pending/not_started/resuming/suspending, 'dead' covers raw "
+        f"crashed/stopped/dead/stopping. A sandbox's raw server word is on "
+        f"`Sandbox.server_status`."
+    )
+
+
+def _transport_for(
+    connection: ConnectionLike | None,
+    role: str | None,
+    transport: SyncTransport | None = None,
+) -> SyncTransport | None:
+    """The transport an explicit ``connection=`` / ``transport=`` asks for, or ``None``.
+
+    ``connection=`` means the same thing on EVERY entry point: resolve it (memoised, so
+    a per-call ``connection=`` does not cost a connector login per call) and use the
+    pooled transport for that credential identity -- exactly what wrapping the one call
+    in ``using(connection)`` does. There is no second, private-transport meaning on
+    ``create()``: one kwarg, one rule, and the pool is bounded by the number of
+    connections used rather than the number of sandboxes created.
+
+    ``None`` means "no opinion" -- the caller falls back to the ambient/scoped transport.
+    ``connection`` picks the Snowflake connection for this call; the handle carries it
+    onward. See `config.using` for the resolution rules (names, live connections,
+    memoisation, and how an enclosing ``using()`` block interacts).
+
+    """
+    if connection is not None and transport is not None:
+        raise SandboxError(
+            "pass either connection= or transport=, not both — connection= selects the "
+            "pooled transport for that connection."
+        )
+    if transport is not None:
+        return transport
+    if connection is None:
+        return None
+    from snowflake.sandbox._sync_transport import get_sync_transport_for_config
+    from snowflake.sandbox.config import resolve_config
+
+    return get_sync_transport_for_config(resolve_config(connection=connection, role=role), role)
+
+
+def _entry_transport(connection: ConnectionLike | None, role: str | None) -> SyncTransport:
+    """The transport for an id/name-based entry point.
+
+    An explicit ``connection=`` wins; otherwise mint the role slot if needed (see
+    `_prime_role`) and take the ambient/scoped transport.
+    ``connection`` picks the Snowflake connection for this call; the handle carries it
+    onward. See `config.using` for the resolution rules (names, live connections,
+    memoisation, and how an enclosing ``using()`` block interacts).
+
+    """
+    explicit = _transport_for(connection, role)
+    if explicit is not None:
+        return explicit
+    _prime_role(role)
+    return get_sync_transport(role)
+
+
+def _prime_role(role: str | None) -> None:
+    """Resolve the role a read/attach path is about to use, before the request needs it.
+
+    ``create(role=...)`` has always done this. The read paths did not: they called
+    ``get_sync_transport(role)`` directly and the role-keyed transport resolved the role
+    itself, mid-request -- and (before the config slots were removed) a role that was
+    never configured silently fell through to the DEFAULT one, so the request ran under
+    the default token. Resolving here makes ``role=`` mean one thing on every entry
+    point. An unrequested role binding is the wrong direction to fail in.
+
+    Inside a ``using()`` block the scope resolves the role from its own connection,
+    so this is a no-op there.
+
+    Strict, exactly like ``create(role=...)``: a role that cannot be minted raises. It was
+    best-effort here until now, because a read path's ``role=`` also carried the server-side
+    ``?role=`` filter (sandbox-api#236) and that meaning is valid under any credential, so
+    bare env/PAT credentials were tolerated. ``role=`` now means CREDENTIAL on every entry
+    point — one word, one meaning — so raw credentials plus ``role=`` is an error rather
+    than a role silently ignored.
+
+    The ``?role=`` filter is still SENT; only its status changed, from a second public
+    meaning to an internal narrowing that agrees with the credential. Removing it would have
+    been wrong on both counts: a role-minted session still sees every role's sandboxes
+    (measured live — a PUBLIC session listed 7 ENGINEER sandboxes), and this SDK does not
+    follow pagination cursors, so filtering locally on ``sb.role`` would quietly return part
+    of one page instead of that role's sandboxes.
+    """
+    if role is None:
+        return
+    from snowflake.sandbox.config import _in_scope, prime_role_config
+
+    if _in_scope():
+        # `prime_role_config` guards this too, and that one is the authoritative check --
+        # ``create(role=...)`` calls it directly.
+        return
+    prime_role_config(role)
+
+
+def list_sandboxes(
+    *,
+    status: SandboxStatus | None = None,
+    role: str | None = None,
+    include_old_apps: bool = False,
+    connection: ConnectionLike | None = None,
+) -> Iterator[Sandbox]:
+    """List sandboxes the caller's PAT has access to.
+
+    Maps to ``GET /containers``. Returns an iterator so callers can consume large
+    result sets without materialising them.
+
+    ``status`` is the SDK's own status word and is filtered CLIENT-SIDE; see
+    ``_iter_sandboxes``. An unrecognized value raises immediately rather than
+    yielding nothing.
+    ``connection`` picks the Snowflake connection for this call; the handle carries it
+    onward. See `config.using` for the resolution rules (names, live connections,
+    memoisation, and how an enclosing ``using()`` block interacts).
+
+    """
+    _validate_status_filter(status)
+    return _iter_sandboxes(
+        status=status, role=role, include_old_apps=include_old_apps, connection=connection
+    )
+
+
+def _iter_sandboxes(
+    *,
+    status: SandboxStatus | None = None,
+    role: str | None = None,
+    include_old_apps: bool = False,
+    connection: ConnectionLike | None = None,
+) -> Iterator[Sandbox]:
+    """List sandboxes the caller's PAT has access to.
+
+    Maps to ``GET /containers``. Returns an iterator so callers can
+    consume large result sets without materialising them.
+
+    ``role`` resolves this call's connection AT that role (see
+    ``Sandbox.create(role=...)``).
+
+    ``include_old_apps`` widens the default view. By default the server returns
+    the live set (running/suspended) plus sandboxes stopped within the last 24h;
+    set this to also include older-stopped and other terminal states the backend
+    still retains (bounded by its retention window).
+
+    **One page.** The endpoint exposes no documented cursor today, so this yields
+    exactly what the server returned. If a response ever *does* carry a
+    truncation marker, that is surfaced as a `exceptions.SandboxContractWarning`
+    rather than passed off as the complete set -- silently presenting a truncated
+    page as "all of them" is how a reaper leaves containers running and reports
+    success.
+    ``connection`` picks the Snowflake connection for this call; the handle carries it
+    onward. See `config.using` for the resolution rules (names, live connections,
+    memoisation, and how an enclosing ``using()`` block interacts).
+
+    """
+    t = _entry_transport(connection, role)
+    params: dict[str, str] = {}
+    # status is deliberately NOT sent. On the /containers path the server compares
+    # ?status= against the RAW backend word, while this SDK's vocabulary is the mapped
+    # one, so anything we send either matches nothing or is then dropped by the
+    # client-side filter below. Measured against a live deployment: 219 sandboxes, all
+    # sdk_status=ready / raw=running, and ?status=ready returned 0. Filtering locally on
+    # the mapped status is the only combination that agrees with itself.
+    #
+    # The vocabulary mismatch itself is tracked as sandbox-api#190.
+    if include_old_apps:
+        params["include_old_apps"] = "true"
+    # Narrow to one role server-side. Without it (role=None) the server lists every
+    # sandbox the user owns across all their roles.
+    #
+    # This is an INTERNAL narrowing, not a second meaning of role=: role= selects the
+    # CREDENTIAL (the session is minted at that role, strictly), and this param makes the
+    # server return the set that credential is asking about. The two agree because a
+    # sandbox is owned by the role that created it.
+    #
+    # Deliberately NOT replaced by filtering on the returned `sb.role`, which was the
+    # plan until it was measured: the credential alone does not scope the list (a session
+    # minted at PUBLIC listed 7 ENGINEER sandboxes live), and this SDK does not follow
+    # pagination cursors (`_warn_if_truncated` warns and stops), so a local filter over one
+    # unfiltered page can return a fraction of the role's sandboxes and look complete.
+    if role:
+        params["role"] = role
+    resp = t.request("GET", "containers", params=params or None)
+    payload = resp.json() if resp.content else {}
+    items: list[dict[str, Any]] = []
+    if isinstance(payload, dict):
+        raw = payload.get("data") or payload.get("containers") or payload.get("items") or []
+        if isinstance(raw, list):
+            items = [r for r in raw if isinstance(r, dict)]
+        _warn_if_truncated(payload, len(items))
+    elif isinstance(payload, list):
+        items = [r for r in payload if isinstance(r, dict)]
+    for item in items:
+        sb = _hydrate_sandbox(item, transport=t)
+        if status is not None and sb.status != status:
+            continue
+        yield sb
+
+
+def get_sandbox(
+    sandbox_id: str, *, role: str | None = None, connection: ConnectionLike | None = None
+) -> Sandbox:
+    """Rehydrate a Sandbox by id (e.g. after a driver restart).
+
+    ``role`` resolves this call's connection AT that role.
+
+    Maps to ``GET /containers/{id}``.
+    ``connection`` picks the Snowflake connection for this call; the handle carries it
+    onward. See `config.using` for the resolution rules (names, live connections,
+    memoisation, and how an enclosing ``using()`` block interacts).
+
+    """
+    t = _entry_transport(connection, role)
+    resp = t.request("GET", f"containers/{sandbox_id}")
+    payload = resp.json() if resp.content else {}
+    if not isinstance(payload, dict):
+        raise SandboxError(f"unexpected response shape for get_sandbox: {payload!r}")
+    return _hydrate_sandbox(payload, transport=t)
+
+
+def get_sandbox_by_name(
+    name: str, *, role: str | None = None, connection: ConnectionLike | None = None
+) -> Sandbox:
+    """Look up a sandbox by its caller-assigned ``name=`` (Modal Sandbox.from_name).
+
+    ``role`` resolves this call's connection AT that role.
+
+    Queries ``GET /containers?name=<name>`` and returns the match, re-filtering on
+    the echoed ``name`` field client-side. That second filter is what makes this
+    safe on a server that does not yet honor the query param or store the name: it
+    returns no false match, raising `SandboxNotFoundError` rather than handing back
+    an arbitrary sandbox.
+
+    Names are unique per owner (server-enforced). If more than one sandbox still
+    reports the same name (pre-enforcement duplicates), this raises
+    `SandboxConflictError` rather than returning an arbitrary one.
+
+    Kept as a module function alongside `get_sandbox`/`list_sandboxes`/
+    `destroy_sandbox` rather than a `Sandbox.from_name` classmethod, matching this
+    SDK's existing convention.
+    ``connection`` picks the Snowflake connection for this call; the handle carries it
+    onward. See `config.using` for the resolution rules (names, live connections,
+    memoisation, and how an enclosing ``using()`` block interacts).
+
+    """
+    if not name:
+        raise SandboxError("get_sandbox_by_name requires a non-empty name")
+    t = _entry_transport(connection, role)
+    resp = t.request("GET", "containers", params={"name": name})
+    payload = resp.json() if resp.content else {}
+    items: list[dict[str, Any]] = []
+    if isinstance(payload, dict):
+        raw = payload.get("data") or payload.get("containers") or payload.get("items") or []
+        if isinstance(raw, list):
+            items = [r for r in raw if isinstance(r, dict)]
+    elif isinstance(payload, list):
+        items = [r for r in payload if isinstance(r, dict)]
+    matches = [item for item in items if item.get("name") == name]
+    if not matches:
+        raise SandboxNotFoundError(f"no sandbox named {name!r}")
+    if len(matches) > 1:
+        ids = ", ".join(
+            str(m.get("container_id") or m.get("id") or m.get("sandbox_id") or "?") for m in matches
+        )
+        raise SandboxConflictError(
+            f"{len(matches)} sandboxes report the name {name!r} ({ids}); names are "
+            "unique per owner, so this indicates duplicates predating name "
+            "enforcement -- these must be de-duplicated by name"
+        )
+    return _hydrate_sandbox(matches[0], transport=t)
+
+
+def destroy_sandbox(
+    sandbox_id: str, *, role: str | None = None, connection: ConnectionLike | None = None
+) -> None:
+    """Destroy a sandbox by id. Idempotent for an already-absent container.
+
+    ``role`` resolves this call's connection AT that role.
+
+    Only a 404 is treated as success; every other failure propagates rather than
+    reporting a teardown that did not happen.
+    ``connection`` picks the Snowflake connection for this call; the handle carries it
+    onward. See `config.using` for the resolution rules (names, live connections,
+    memoisation, and how an enclosing ``using()`` block interacts).
+
+    """
+    t = _entry_transport(connection, role)
+    try:
+        t.request("DELETE", f"containers/{sandbox_id}")
+    except SandboxNotFoundError:
+        # 404 -> already gone, which is the requested end state.
+        pass
+
+
+def _hydrate_sandbox(item: Mapping[str, Any], *, transport: SyncTransport) -> Sandbox:
+    sb = Sandbox(
+        image=str(item.get("image") or "unknown"),
+        transport=transport,
+        _internal=True,
+    )
+    raw_id = item.get("container_id") or item.get("id") or item.get("sandbox_id") or ""
+    sb._id = str(raw_id) if raw_id else None
+    parsed = _parse_status(item.get("status"))
+    if parsed is not None:
+        sb._status = parsed
+    sb._server_status = str(item.get("status") or "")
+    # Canonical `memory` first, then the deprecated `memory_limit` for servers
+    # deployed before the rename; an unrecognized tier warns instead of silently
+    # reading as the 4g default.
+    sb._absorb_resource_echo(item, compare_to_request=False)
+    # image / gpu / name / exit_code / generation off the list/get response, so a
+    # reconnected handle reports them instead of "unknown"/echo-only/None.
+    sb._absorb_read_fields(item)
+    # _absorb_read_fields already set _role from the server's role field.
+    sb._created = sb._id is not None
+    return sb