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

snowflake/sandbox/_transport.py

@@ -0,0 +1,1366 @@
+"""HTTP transport for ``snowflake.sandbox``.
+
+Wraps a single process-wide ``httpx.AsyncClient`` (HTTP/2, bearer auth,
+JSON content-type), handles the retry policy, maps
+HTTP status codes to the ``SandboxError`` hierarchy, and exposes a
+streaming SSE primitive used by ``exec_stream``.
+
+Imports ``httpx`` lazily-at-module-load (i.e. when the module is imported
+from ``__init__``'s ``__getattr__``); ``import snowflake.sandbox`` does
+not pay this cost.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import inspect
+import random
+import threading
+import weakref
+from collections.abc import AsyncIterator, Callable, Mapping
+from dataclasses import dataclass
+from typing import Any, BinaryIO, Final
+
+import httpx
+
+from snowflake.sandbox._retry import (
+    DEFAULT_500_DELAYS_S,
+    DEFAULT_COLD_START_DELAYS_S,
+    DEFAULT_NOT_FOUND_DELAYS_S,
+    compute_backoff,
+)
+from snowflake.sandbox._sse import (
+    SSEEvent,
+    _iter_sse_frames,
+    _sse_open_retry_delay,
+    parse_sse_event,  # noqa: F401 - re-exported so _transport.parse_sse_event resolves
+)
+from snowflake.sandbox._transport_errors import (
+    _RATE_LIMIT_MAX_ATTEMPTS,  # noqa: F401 - re-exported for callers/tests
+    _RETRY_AFTER_MAX_S,  # noqa: F401 - re-exported for callers/tests
+    SandboxSSEDecodeError,  # noqa: F401 - re-exported for callers/tests
+    _error_detail,
+    _is_clean_goaway,
+    _is_cold_start_409,
+    _is_reauth_response,
+    _rate_limit_delay,
+    _retry_after_seconds,
+    _says_not_ready,
+    _status_to_error,
+)
+from snowflake.sandbox._version import __version__ as _SDK_VERSION
+from snowflake.sandbox.config import (
+    Config,
+    current_config,
+    refresh_config,
+    refresh_credential,
+)
+from snowflake.sandbox.exceptions import (
+    SandboxAuthError,
+    SandboxNotReadyError,
+    SandboxRateLimitError,
+    SandboxTransportError,
+)
+
+# ``shutdown()`` is public API and now has a public home in ``lifecycle``; it is
+# re-exported here so the internal callers (and tests) that reach for
+# ``_transport.shutdown`` keep working. ``lifecycle`` imports this module only inside
+# its function bodies, so this edge does not close a module-scope cycle.
+from snowflake.sandbox.lifecycle import shutdown
+
+__all__ = [
+    "Transport",
+    "get_transport",
+    "reset_transport",
+    "shutdown",
+    "SSEEvent",
+    "AsyncStreamAbort",
+    "parse_sse_event",
+]
+
+_USER_AGENT: Final = f"snowflake-sandbox-python/{_SDK_VERSION}"
+_MCP_PATH: Final = "/api/v2/cortex/v1/mcp"
+# Status codes that indicate the container is still cold-starting.
+_COLD_START_STATUSES: Final = {503}
+# Headers a caller-supplied `extra_headers` (SNOWFLAKE_CWS_EXTRA_HEADERS) may never
+# override -- doing so would swap the bearer token or redirect the request host.
+_RESERVED_HEADER_NAMES: Final = frozenset({"authorization", "host"})
+
+# Methods for which re-sending a request that may already have run is harmless.
+# POST is deliberately absent: a re-sent `POST /containers` leaves an orphaned,
+# billed sandbox whose id the caller never learns, and a re-sent
+# `POST /containers/{id}/exec` re-runs the caller's command with its full side
+# effects (`git push`, `dbt run`, a Slack post) while looking identical to a
+# command that never ran.
+_IDEMPOTENT_METHODS: Final = frozenset({"GET", "HEAD", "OPTIONS", "PUT", "DELETE"})
+
+# Failures raised before any byte of the request reached the server. Retrying
+# these cannot duplicate a side effect, whatever the method.
+_UNSENT_ERRORS: Final = (
+    httpx.ConnectError,
+    httpx.ConnectTimeout,
+    httpx.PoolTimeout,
+)
+# Failures raised after the request was written. Whether the server ran it is
+# unknowable from the client, so these are retried only for idempotent methods.
+_SENT_ERRORS: Final = (
+    httpx.ReadTimeout,
+    httpx.ReadError,
+    httpx.WriteTimeout,
+    httpx.WriteError,
+    httpx.RemoteProtocolError,
+)
+
+
+@dataclass
+class _RetryState:
+    """Per-request retry counters, threaded from request()'s send/retry loop into
+    the per-status policy in `_status_retry_delay`. One instance per request()."""
+
+    cold: int = 0
+    five_hundred: int = 0
+    rate_limit: int = 0
+    not_found: int = 0
+
+
+@dataclass
+class _RequestAuth:
+    """The token a request()'s headers carry, tracked so a reauth response can
+    re-mint it and retry exactly once. One instance per request(), mutated in
+    place by `Transport._reauth` / `SyncTransport._reauth`.
+
+    ``refreshed`` is the one-shot guard: a freshly-minted token that still draws a
+    reauth response is a real auth failure, not expiry, so it must not loop."""
+
+    headers: dict[str, str]
+    sent_pat: str | None
+    refreshed: bool = False
+
+
+def _status_retry_delay(
+    rng: random.Random,
+    resp: httpx.Response,
+    *,
+    method: str,
+    path: str,
+    idempotent: bool,
+    retry_not_found: bool,
+    retry_500_delays: tuple[float, ...],
+    state: _RetryState,
+) -> float | None:
+    """The per-status retry POLICY, split out of request()'s send/retry LOOP.
+
+    For a ``>=400`` response that is NOT a reauth case (the caller handles those),
+    returns the seconds to back off before retrying, or ``None`` when the status is
+    not one this policy retries (the caller then does reauth-or-terminal-raise).
+    Raises the terminal ``SandboxError`` when the method makes a retry unsafe or a
+    retry budget is exhausted. Pure and synchronous, so the async and sync
+    transports share one implementation. ``state`` carries the attempt counters.
+    """
+    sc = resp.status_code
+
+    # Retryable: 503 or 409 cold-start. For a non-idempotent request the body must
+    # say the work was refused, not merely that something went wrong upstream of an
+    # unknown outcome.
+    if sc in _COLD_START_STATUSES or _is_cold_start_409(resp):
+        if not idempotent and not _says_not_ready(resp):
+            raise SandboxTransportError(
+                f"HTTP {sc} on {method.upper()} {path}: "
+                f"{_error_detail(resp.text)} — not retried because the server may "
+                "already have executed it"
+            )
+        state.cold += 1
+        delay = compute_backoff(state.cold, delays=DEFAULT_COLD_START_DELAYS_S, rng=rng)
+        if delay is None:
+            if sc == 409:
+                raise SandboxNotReadyError(
+                    f"sandbox not ready after {len(DEFAULT_COLD_START_DELAYS_S)} retries"
+                )
+            raise SandboxTransportError(
+                f"503 after {len(DEFAULT_COLD_START_DELAYS_S)} retries: {_error_detail(resp.text)}"
+            )
+        return delay
+
+    # 429: honor a sanitized Retry-After, retry up to the shared budget. A
+    # rate-limited request was rejected without being executed, so this is safe for
+    # any method. Jitter is upward only (see _rate_limit_delay) so we never retry
+    # before the server said it was safe to.
+    if sc == 429:
+        state.rate_limit += 1
+        delay = _rate_limit_delay(resp, state.rate_limit, rng)
+        if delay is None:
+            raise SandboxRateLimitError(
+                f"rate-limited after {state.rate_limit - 1} retries",
+                retry_after=_retry_after_seconds(resp),
+            )
+        return delay
+
+    # 500 surfaces as transport-error after one retry — but only for an idempotent
+    # method: a 500 means the server accepted the request and failed somewhere
+    # inside, which says nothing about whether the side effect landed.
+    if sc == 500:
+        if not idempotent:
+            raise SandboxTransportError(
+                f"HTTP 500 on {method.upper()} {path}: {_error_detail(resp.text)} — "
+                "not retried because the server may already have executed it"
+            )
+        state.five_hundred += 1
+        delay = compute_backoff(state.five_hundred, delays=retry_500_delays, rng=rng)
+        if delay is None:
+            raise SandboxTransportError(
+                f"500 from server after {len(retry_500_delays)} retries: {_error_detail(resp.text)}"
+            )
+        return delay
+
+    # 404 keeps its create-race retry logic; every other terminal status goes
+    # through the shared _status_to_error table in the caller.
+    if sc == 404:
+        # A freshly-created container is briefly unroutable — its id is returned by
+        # create before the route is registered, so the first exec/logs can 404.
+        # Retry on a tight bounded schedule; a genuinely-missing container still
+        # surfaces quickly. Safe for a POST too: a 404 means no handler ran, so
+        # there is no side effect a retry could duplicate.
+        #
+        # retry_not_found=False skips this schedule: a caller probing an optional
+        # route (e.g. a cheap /status older servers lack) or looking up a
+        # user-supplied id wants the 404 immediately, not after the create-race wait.
+        if not retry_not_found:
+            raise _status_to_error(404, resp.text)
+        state.not_found += 1
+        delay = compute_backoff(state.not_found, delays=DEFAULT_NOT_FOUND_DELAYS_S, rng=rng)
+        if delay is None:
+            raise _status_to_error(404, resp.text)
+        return delay
+
+    return None
+
+
+def _transport_error_delay(
+    exc: Exception,
+    *,
+    sent: bool,
+    idempotent: bool,
+    method: str,
+    path: str,
+    state: _RetryState,
+    rng: random.Random,
+) -> float:
+    """Backoff (seconds) for a transport-layer error, or raise if the retry is
+    unsafe or the budget is exhausted.
+
+    A pre-send error is always retryable (nothing reached the server). A post-send
+    error (``sent=True``) is retryable only for an idempotent method or a clean
+    GOAWAY (error_code=0, no streams processed) — the server told us it closed the
+    connection before touching the request. Split from request()'s loop; shared by
+    both transports.
+    """
+    if sent and not idempotent and not _is_clean_goaway(exc):
+        raise SandboxTransportError(
+            f"{method.upper()} {path} failed after the request was sent "
+            f"({type(exc).__name__}: {exc}); not retried because the "
+            "server may already have executed it"
+        ) from exc
+    state.cold += 1
+    delay = compute_backoff(state.cold, delays=DEFAULT_COLD_START_DELAYS_S, rng=rng)
+    if delay is None:
+        raise SandboxTransportError(f"transport error after retries: {exc}") from exc
+    return delay
+
+
+class AsyncStreamAbort:
+    """`StreamAbort` for the async client: interrupt a pending SSE read.
+
+    Different mechanism, same contract. The sync reader blocks in ``recv()`` on
+    another thread, so a socket shutdown is what reaches it; here the read is an
+    ``await`` in the same event loop, and reaching into the transport's socket would
+    bypass the loop's bookkeeping. Closing the httpcore stream is the supported
+    equivalent -- measured: the pending read resolves immediately.
+
+    It resolves by RAISING ``httpx.ReadError``, though, where the sync shutdown ends
+    at EOF. So an abort arrives at the caller's ``except SandboxTransportError``
+    branch rather than its clean-EOF branch, and that branch resumes -- which is why
+    `aborted` has to be checked there or terminate() is followed by a reconnect to a
+    dead sandbox.
+    """
+
+    __slots__ = ("_aborted", "_stream")
+
+    def __init__(self) -> None:
+        self._aborted = False
+        self._stream: Any = None
+
+    async def bind(self, resp: httpx.Response) -> None:
+        """Remember the network stream under *resp* for the duration of the read.
+
+        Best-effort, as in the sync twin: ``network_stream`` is not public httpx API
+        and is absent on some transports. Without it the read ends at its timeout, as
+        before -- degraded, not broken.
+        """
+        stream = None
+        try:
+            stream = resp.extensions.get("network_stream")
+        except Exception:  # pragma: no cover - transport-shape dependent
+            stream = None
+        self._stream = stream
+        if self._aborted:
+            # abort() ran between the open and this bind, so it saw no stream.
+            await self._close()
+
+    def unbind(self) -> None:
+        self._stream = None
+
+    async def abort(self) -> None:
+        self._aborted = True
+        await self._close()
+
+    async def _close(self) -> None:
+        stream, self._stream = self._stream, None
+        if stream is None:
+            return
+        try:
+            await stream.aclose()
+        except Exception:  # pragma: no cover - already closed, or never connected
+            pass
+
+    @property
+    def aborted(self) -> bool:
+        return self._aborted
+
+
+_FILE_CHUNK_BYTES: Final = 64 * 1024
+
+
+def _seekable_size(f: BinaryIO) -> int:
+    """Byte length of an open file, leaving it rewound."""
+    f.seek(0, 2)
+    size = f.tell()
+    f.seek(0)
+    return size
+
+
+async def _aiter_file(f: BinaryIO) -> AsyncIterator[bytes]:
+    """Yield a file's bytes in chunks for an async request body.
+
+    An ``AsyncClient`` cannot take a plain file object as ``content`` -- httpx wraps
+    it in a *sync* byte stream and refuses to send it -- so the file is adapted to an
+    async iterator. Reads go through a thread because a large read on the event loop
+    would stall every other request sharing it.
+    """
+    while True:
+        chunk = await asyncio.to_thread(f.read, _FILE_CHUNK_BYTES)
+        if not chunk:
+            return
+        yield chunk
+
+
+def _cws_transform(
+    method: str,
+    endpoint: str,
+    json_body: Any,
+    timeout: float | None,
+) -> tuple[str, Any]:
+    """CWS dev mode: redirect MCP exec → REST and convert env dict → sandbox_env."""
+    if method.upper() == "POST" and endpoint == _MCP_PATH and isinstance(json_body, dict):
+        args = json_body.get("params", {}).get("arguments", {})
+        cid = args.get("container_id")
+        if cid:
+            body: dict[str, Any] = {
+                "code": args.get("code", ""),
+                "language": "python",
+                "timeout_seconds": int(timeout or 60),
+            }
+            exec_env = args.get("env")
+            if isinstance(exec_env, dict) and exec_env:
+                body["env"] = exec_env
+            return f"containers/{cid}/exec", body
+    if (
+        method.upper() == "POST"
+        and "exec" not in str(endpoint)
+        and isinstance(json_body, dict)
+        and isinstance(json_body.get("env"), dict)
+    ):
+        body = {k: v for k, v in json_body.items() if k != "env"}
+        body["sandbox_env"] = [f"{k}={v}" for k, v in json_body["env"].items()]
+        json_body = body
+    return endpoint, json_body
+
+
+async def _aclose_quietly(client: httpx.AsyncClient) -> None:
+    """Close a pooled client, swallowing whatever the close itself raises.
+
+    Best-effort on purpose, and shared by every deferred/refcounted close path: they all
+    run during teardown -- an ``__aexit__``, a request's ``finally``, an async generator
+    being closed -- where a socket-level failure (or a loop that has already gone away)
+    must not become the exception a caller's block raises.
+    """
+    try:
+        await client.aclose()
+    except Exception:  # noqa: BLE001 - teardown; see docstring
+        pass
+
+
+class Transport:
+    """Owns the process-wide ``httpx.AsyncClient`` and the retry loop.
+
+    All public methods are async. The client is created lazily on first
+    use so importing the module is cheap.
+    """
+
+    def __init__(self, config: Config | None = None, role_key: str | None = None) -> None:
+        self._config_override = config
+        # With no explicit config this transport is the AMBIENT one: it re-resolves
+        # through current_config() on every request. ``role_key`` is the role to resolve
+        # AT, so its requests carry that role's token rather than the default's.
+        self._role_key = role_key if config is None else None
+        # One (client, semaphore) per running event loop. An ``httpx.AsyncClient``
+        # -- and an ``asyncio.Semaphore`` -- binds to the loop it is first used on;
+        # a single process-global client shared across loops is broken: the
+        # documented ``asyncio.run()`` idiom closes its loop on return, so the next
+        # ``asyncio.run()`` (a re-run notebook cell, a second CLI invocation, a
+        # pytest case, a per-request handler) inherited a client wired to a closed
+        # loop and failed intermittently with ``RuntimeError: Event loop is
+        # closed``. Keying on the running loop hands each loop its own client, so
+        # sequential ``asyncio.run()`` calls -- and concurrent loops on different
+        # threads -- each get a working one. A ``WeakKeyDictionary`` lets a
+        # finished loop's entry (and its client) be collected once the loop is gone.
+        self._clients: weakref.WeakKeyDictionary[
+            asyncio.AbstractEventLoop, tuple[httpx.AsyncClient, asyncio.Semaphore]
+        ] = weakref.WeakKeyDictionary()
+        # A plain threading lock (not an ``asyncio.Lock``, which would itself bind
+        # to one loop) guards the map. The client is constructed synchronously
+        # inside it -- ``httpx.AsyncClient(...)`` needs no running loop.
+        self._clients_lock = threading.Lock()
+        # How many `async with AsyncSandbox(...)` blocks on each loop are currently
+        # using that loop's client (see _retain_loop_user). Keyed by loop for the same
+        # reason ``_clients`` is: the thing being refcounted is per-loop, so a
+        # process-global count would have one loop's exit decide another's close.
+        # Guarded by ``_clients_lock`` -- the count and the client it protects are
+        # read and mutated for the same key, so one lock keeps them consistent.
+        self._loop_users: weakref.WeakKeyDictionary[asyncio.AbstractEventLoop, int] = (
+            weakref.WeakKeyDictionary()
+        )
+        # How many requests are currently in flight on each loop's client (see
+        # _in_flight_request). Separate from ``_loop_users`` because it counts a
+        # different thing: a request on a sandbox driven with explicit
+        # ``create()``/``terminate()``, or a module helper like ``list_sandboxes()``,
+        # is in flight while retaining nothing. Guarded by ``_clients_lock`` with the
+        # other two maps, so the close decision reads a consistent snapshot.
+        self._in_flight: weakref.WeakKeyDictionary[asyncio.AbstractEventLoop, int] = (
+            weakref.WeakKeyDictionary()
+        )
+        # Loops whose last ``async with`` exited while a request was still in flight,
+        # so the close was deferred to whichever request finishes last (#370).
+        self._closes_deferred: weakref.WeakSet[asyncio.AbstractEventLoop] = weakref.WeakSet()
+        self._rng = random.Random()
+        # Serializes reactive re-mints for a Transport built with an explicit
+        # config override (the module path has its own lock in config). Keyed off
+        # nothing — the re-check of resolve_pat() inside dedups by token.
+        self._refresh_lock = threading.Lock()
+
+    @property
+    def config(self) -> Config:
+        return self._config_override or current_config(role=self._role_key)
+
+    async def _get_client(
+        self,
+    ) -> tuple[httpx.AsyncClient, asyncio.Semaphore]:
+        """The (client, semaphore) pair for the currently-running event loop."""
+        loop = asyncio.get_running_loop()
+        with self._clients_lock:
+            entry = self._clients.get(loop)
+            if entry is None:
+                cfg = self.config
+                limits = httpx.Limits(
+                    max_connections=cfg.max_connections,
+                    max_keepalive_connections=cfg.max_connections,
+                )
+                client = httpx.AsyncClient(
+                    base_url=cfg.base_url,
+                    http2=not cfg.cws_dev,
+                    trust_env=not cfg.cws_dev,
+                    timeout=cfg.timeout_s,
+                    verify=cfg.verify,
+                    limits=limits,
+                    headers={"User-Agent": _USER_AGENT},
+                )
+                entry = (client, asyncio.Semaphore(cfg.max_connections))
+                self._clients[loop] = entry
+            return entry
+
+    def _retain_loop_user(self) -> None:
+        """Register one user of the running loop's client (an ``async with`` entry).
+
+        Refcounted rather than closed per sandbox: the pool is process-wide on purpose
+        so repeated calls skip the TLS handshake, and nested or concurrent sandboxes on
+        one loop must keep it open. Refcounted PER LOOP because the client is per loop
+        -- with one process-global count, two ``asyncio.run()`` loops on two threads
+        each retained, so the first to exit saw ``count > 0``, closed nothing, and its
+        loop closed still holding sockets: ``ResourceWarning: unclosed transport``
+        (#202) with the refcount in place.
+        """
+        loop = asyncio.get_running_loop()
+        with self._clients_lock:
+            self._loop_users[loop] = self._loop_users.get(loop, 0) + 1
+            # This loop's client has a user again, so a close an earlier exit deferred
+            # (#370) is off: the block entering here is entitled to keep it open for as
+            # long as it runs, and its own exit will close it if it is the last one.
+            self._closes_deferred.discard(loop)
+
+    async def _release_loop_user(self) -> None:
+        """Drop one user of the running loop's client, closing it when it was the last.
+
+        Scoped to the running loop: closing every loop's client here (what the
+        package-level ``shutdown()`` does) would tear down clients belonging to loops
+        still running on other threads. Clients on other loops are left alone, and each
+        one closes when its own last block exits.
+
+        A release with nothing retained on this loop is a no-op -- a sandbox driven with
+        explicit ``create()``/``terminate()`` never retained, and closing a client it
+        never opened would break whoever did.
+
+        The close also waits for the loop's client to be IDLE (see
+        `_in_flight_request`): with requests still in flight the close is deferred to
+        whichever of them finishes last, because closing the client under a sibling task
+        aborted its request (#370).
+        """
+        loop = asyncio.get_running_loop()
+        with self._clients_lock:
+            users = self._loop_users.get(loop, 0)
+            if users == 0:
+                return
+            if users > 1:
+                self._loop_users[loop] = users - 1
+                return
+            self._loop_users.pop(loop, None)
+            if self._in_flight.get(loop, 0) > 0:
+                # Another task on this loop is mid-request. Closing now aborts it: an
+                # idempotent GET would retry onto a fresh client, but a POST (``exec``)
+                # cannot be re-sent, so it surfaced as ``SandboxTransportError`` for a
+                # command the server may well have run. Hand the close to whichever
+                # request finishes last -- a deferral, not a leak: `_finish_request`
+                # releases the sockets as soon as the client goes idle.
+                self._closes_deferred.add(loop)
+                return
+            self._closes_deferred.discard(loop)
+            entry = self._clients.pop(loop, None)
+        if entry is None:
+            return
+        await _aclose_quietly(entry[0])
+
+    @contextlib.asynccontextmanager
+    async def _in_flight_request(self) -> AsyncIterator[None]:
+        """Count one in-flight request against the running loop's client.
+
+        Every send path holds this for as long as it needs the client, so that
+        `_release_loop_user` can tell an idle client from a busy one. The last
+        ``async with`` block on a loop can exit while a SIBLING task on the same loop is
+        mid-request -- a sandbox driven with explicit ``create()``/``terminate()``, or a
+        module helper like ``list_sandboxes()``, neither of which retains -- and the
+        close that exit performs then landed on a live request (#370).
+
+        Entered BEFORE ``_get_client()`` on purpose: both take ``_clients_lock``, so
+        registering first is what makes the pair atomic against a concurrent release,
+        which can otherwise pop the client between the two.
+
+        Held across retries and their backoff sleeps as well, not just the individual
+        ``client.request`` await: a client closed mid-backoff fails the next attempt with
+        a bare ``RuntimeError`` from httpx, which no branch of the retry loop maps.
+        """
+        loop = asyncio.get_running_loop()
+        with self._clients_lock:
+            self._in_flight[loop] = self._in_flight.get(loop, 0) + 1
+        try:
+            yield
+        finally:
+            await self._finish_request(loop)
+
+    async def _finish_request(self, loop: asyncio.AbstractEventLoop) -> None:
+        """Drop one in-flight request, performing a close `_release_loop_user` deferred.
+
+        Takes *loop* as an argument instead of reading ``get_running_loop()``: this runs
+        from a ``finally``, including the one inside `stream_sse`'s async generator,
+        which is not guaranteed to be closed on the loop the stream began on.
+        """
+        entry = None
+        with self._clients_lock:
+            remaining = self._in_flight.get(loop, 0) - 1
+            if remaining > 0:
+                self._in_flight[loop] = remaining
+                return
+            self._in_flight.pop(loop, None)
+            if loop not in self._closes_deferred:
+                return
+            # The loop's last block exited while this request was in flight, leaving the
+            # close to whoever finished last -- this call. A block that retained the
+            # client SINCE clears the flag under this same lock (`_retain_loop_user`), so
+            # a flag still set here means nothing has taken the client over and the close
+            # is still ours to do.
+            self._closes_deferred.discard(loop)
+            entry = self._clients.pop(loop, None)
+        if entry is not None:
+            await _aclose_quietly(entry[0])
+
+    async def aclose(self) -> None:
+        """Close every cached HTTP client and drop them.
+
+        Awaiting this from a loop closes that loop's client cleanly; clients bound
+        to other (possibly already-closed) loops are closed best-effort. Prefer the
+        package-level ``shutdown()`` at program/kernel/handler end.
+
+        Unlike the refcounted release, this does NOT wait for in-flight requests: it is
+        the explicit end-of-program teardown, and a caller who asked for it wants the
+        sockets gone. A request still running over one of these clients fails, as it
+        always has.
+        """
+        with self._clients_lock:
+            entries = list(self._clients.values())
+            self._clients.clear()
+            # A deferred close names the client that was mapped when it was deferred, and
+            # every one of those is being closed here. Dropping the flags keeps a stale
+            # one from closing a LATER client out from under a request using it.
+            self._closes_deferred.clear()
+        for client, _sem in entries:
+            await _aclose_quietly(client)
+
+    def _close_sync_best_effort(self) -> None:
+        """Close cached clients from a synchronous context (``reset_transport``).
+
+        If a loop is running we cannot block on ``aclose`` here, so we drop the
+        references (above) and let the clients close on garbage collection. With no
+        running loop we spin a throwaway loop to close them, swallowing anything a
+        client bound to an already-closed loop raises.
+        """
+        with self._clients_lock:
+            entries = list(self._clients.values())
+            self._clients.clear()
+            self._closes_deferred.clear()  # see aclose()
+        if not entries:
+            return
+        try:
+            asyncio.get_running_loop()
+            return  # a loop is running; GC will close them
+        except RuntimeError:
+            pass
+
+        async def _close_all() -> None:
+            for client, _sem in entries:
+                try:
+                    await client.aclose()
+                except Exception:  # noqa: BLE001 - best-effort
+                    pass
+
+        import warnings as _warnings
+
+        with _warnings.catch_warnings():
+            _warnings.simplefilter("ignore")
+            try:
+                asyncio.run(_close_all())
+            except Exception:  # noqa: BLE001 - best-effort teardown
+                pass
+
+    def _auth_headers(
+        self, extra: Mapping[str, str] | None = None, *, cfg: Config | None = None
+    ) -> dict[str, str]:
+        # Accept the caller's config SNAPSHOT so the token in these headers and the
+        # ``sent_pat`` the caller tracks come from the same read — otherwise a
+        # concurrent re-mint between the two reads could make them disagree and
+        # trigger a redundant refresh.
+        cfg = cfg if cfg is not None else self.config
+        # Read the token LIVE from the connection when there is one (resolve_pat),
+        # so a connector-renewed token is used on the next request with no stale
+        # snapshot; falls back to the env/PAT snapshot otherwise.
+        token = cfg.resolve_pat()
+        if not token:
+            raise SandboxAuthError(
+                "no Snowflake credential resolved: set SNOWFLAKE_PAT or "
+                "SNOWFLAKE_TOKEN, name a connection in ~/.snowflake/connections.toml, "
+                "or pass connection= on the call"
+            )
+        if cfg.cws_dev:
+            h: dict[str, str] = {
+                "Authorization": f'Snowflake Token="{token}"',
+                "Accept": "application/json",
+            }
+            if cfg.cws_gs_host:
+                h["Host"] = cfg.cws_gs_host
+        else:
+            # Session tokens from snowflake.connector start with "ver:"; they
+            # require the Snowflake-proprietary header form. OAuth PATs use Bearer.
+            if token.startswith("ver:"):
+                auth_val = f'Snowflake Token="{token}"'
+            else:
+                auth_val = f"Bearer {token}"
+            h = {
+                "Authorization": auth_val,
+                "Accept": "application/json",
+            }
+        # cfg.extra_headers is untrusted -- it comes from the SNOWFLAKE_CWS_EXTRA_HEADERS
+        # env var. A stray/hostile value must never be able to replace the bearer
+        # token or redirect the request to another host: SNOWFLAKE_CWS_EXTRA_HEADERS=
+        # '{"Authorization":"Bearer ATTACKER"}' previously overrode auth in every mode.
+        # `extra` is internal (our own Accept/Content-Type) and stays trusted.
+        for k, v in cfg.extra_headers.items():
+            if k.lower() in _RESERVED_HEADER_NAMES:
+                import warnings
+
+                warnings.warn(
+                    f"ignoring header {k!r} from SNOWFLAKE_CWS_EXTRA_HEADERS: it may "
+                    "not override the request's Authorization or Host.",
+                    RuntimeWarning,
+                    stacklevel=2,
+                )
+                continue
+            h[k] = v
+        if extra:
+            for k, v in extra.items():
+                h[k] = v
+        return h
+
+    async def _refresh_auth(self, stale_pat: str | None) -> str | None:
+        """Re-mint the token after a reauth response; the new token, or ``None``.
+
+        The blocking connector round-trip (a token-request renewal, or a full
+        reconnect) runs off the event loop. Returns ``None`` — meaning "surface the
+        auth error, do not retry" — when the token is unset, there is nothing to
+        refresh, or the mint did not change it.
+
+        A Transport built with an explicit Config refreshes THAT config (serialized
+        + deduped on its own ``_refresh_lock``); the default transport refreshes the
+        process-wide active config, where a concurrent burst collapses to a single
+        re-mint in the config layer.
+        """
+        if stale_pat is None:
+            return None
+        if self._config_override is None:
+            return await asyncio.to_thread(refresh_credential, stale_pat)
+        return await asyncio.to_thread(self._refresh_override, stale_pat)
+
+    def _refresh_override(self, stale_pat: str) -> str | None:
+        """Deduped re-mint of this transport's explicit config override (worker
+        thread). Re-reads under ``_refresh_lock`` so two racers don't double-mint
+        or clobber a newer token with an older one."""
+        with self._refresh_lock:
+            ov = self._config_override
+            if ov is None:
+                return None
+            current = ov.resolve_pat()
+            if current != stale_pat:
+                return current  # already refreshed by a racer
+            new = refresh_config(ov, stale_pat)
+            new_token = new.resolve_pat()
+            if new_token is None or new_token == stale_pat:
+                return None
+            if new is not ov:
+                self._config_override = new
+            return new_token
+
+    async def _ensure_pat(self) -> None:
+        """Lazy-mint a CWS dev session token if no PAT is configured.
+
+        In CWS dev mode (SNOWFLAKE_CWS_DEV=1), if neither SNOWFLAKE_PAT nor
+        SNOWFLAKE_TOKEN is set, mint one via /session/v1/login-request using
+        the regtest test account credentials and cache it process-wide. Safe
+        to call before every request — the cache fast-paths after the first
+        mint. Outside CWS dev mode this is a no-op; _auth_headers raises if
+        the PAT is still missing.
+        """
+        cfg = self.config
+        if cfg.pat or not cfg.cws_dev:
+            return
+        from snowflake.sandbox._cws_dev import mint_testaccount_token
+
+        await mint_testaccount_token(cfg)
+
+    def _full_path(self, endpoint: str) -> str:
+        if endpoint.startswith("http://") or endpoint.startswith("https://"):
+            return endpoint
+        if endpoint.startswith("/"):
+            return endpoint
+        return f"{self.config.base_path}/{endpoint}"
+
+    async def request(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        json_body: Any = None,
+        content: bytes | BinaryIO | None = None,
+        params: Mapping[str, str] | None = None,
+        timeout: float | None = None,
+        extra_headers: Mapping[str, str] | None = None,
+        retry_not_found: bool = True,
+        retry_500_delays: tuple[float, ...] = DEFAULT_500_DELAYS_S,
+    ) -> httpx.Response:
+        """Issue a request with retry + error mapping.
+
+        ``retry_500_delays`` overrides the (idempotent-only) 500 retry budget for a
+        single call — e.g. the read-only logs route passes a longer schedule to ride
+        out a transient upstream 500. Default is the one-shot ``DEFAULT_500_DELAYS_S``.
+
+        Retries are **idempotency-aware**. For a non-idempotent method (anything
+        outside `_IDEMPOTENT_METHODS`, i.e. POST) a retry is issued only when the
+        failure proves the server did not run the request: a connect-phase
+        transport error, a 429, a 404, or a 409/503 whose body says "not ready".
+        A read timeout, a 500, or an opaque 503 after the request was written
+        surfaces to the caller instead — re-sending would duplicate the side
+        effect and, worse, look exactly like a first attempt.
+
+        ``content`` sends a raw body (used by file upload) instead of JSON. Either
+        bytes, or an open binary file: httpx reads a file's size and frames the
+        request with ``Content-Length`` rather than chunked, which is required here
+        because the sandbox container's server cannot decode a chunked body — while
+        still streaming it rather than holding the whole file in memory. A file is
+        rewound before every retry, since a partly-consumed stream would otherwise
+        re-send a truncated body.
+        """
+        if self.config.cws_dev:
+            endpoint, json_body = _cws_transform(method, endpoint, json_body, timeout)
+        await self._ensure_pat()
+        # The whole send/retry cycle is ONE in-flight request against this loop's
+        # client, registered before the client is fetched (see _in_flight_request) so a
+        # concurrent `async with` exit defers its close instead of aborting this.
+        async with self._in_flight_request():
+            client, semaphore = await self._get_client()
+            path = self._full_path(endpoint)
+            # One config snapshot for both the headers and the tracked sent token, so
+            # they cannot disagree under a concurrent re-mint.
+            cfg = self.config
+            headers = self._auth_headers(extra_headers, cfg=cfg)
+            if json_body is not None:
+                headers.setdefault("Content-Type", "application/json")
+
+            # A file body is framed with an explicit Content-Length and re-wrapped per
+            # attempt. Both are required: httpx would otherwise send an async iterator
+            # chunked, which the sandbox container cannot decode, and an iterator is
+            # single-use so a retry needs a fresh one over a rewound file.
+            file_body: BinaryIO | None = None if isinstance(content, bytes) else content
+            if file_body is not None:
+                headers["Content-Length"] = str(_seekable_size(file_body))
+
+            idempotent = method.upper() in _IDEMPOTENT_METHODS
+            state = _RetryState()
+            # The token these headers carry, tracked so a reauth response can re-mint it
+            # and retry exactly once (see `_reauth`).
+            auth = _RequestAuth(headers=headers, sent_pat=cfg.resolve_pat())
+
+            while True:
+                async with semaphore:
+                    # Rewind before every attempt: after a failure the file sits wherever
+                    # it stopped, and re-sending from there is a silently truncated upload
+                    # -- the declared length still matches, so nothing downstream notices.
+                    send_content: bytes | AsyncIterator[bytes] | None = None
+                    if file_body is not None:
+                        file_body.seek(0)
+                        send_content = _aiter_file(file_body)
+                    elif isinstance(content, bytes):
+                        send_content = content
+                    try:
+                        resp = await client.request(
+                            method,
+                            path,
+                            json=json_body,
+                            content=send_content,
+                            params=params,
+                            headers=auth.headers,
+                            timeout=timeout if timeout is not None else self.config.timeout_s,
+                        )
+                    except _UNSENT_ERRORS as exc:
+                        delay = _transport_error_delay(
+                            exc,
+                            sent=False,
+                            idempotent=idempotent,
+                            method=method,
+                            path=path,
+                            state=state,
+                            rng=self._rng,
+                        )
+                        await asyncio.sleep(delay)
+                        continue
+                    except _SENT_ERRORS as exc:
+                        delay = _transport_error_delay(
+                            exc,
+                            sent=True,
+                            idempotent=idempotent,
+                            method=method,
+                            path=path,
+                            state=state,
+                            rng=self._rng,
+                        )
+                        await asyncio.sleep(delay)
+                        continue
+
+                if resp.status_code < 400:
+                    # A 2xx can still be a legacy reauth envelope (success:false +
+                    # 390111) for a session token; re-mint once and retry if so.
+                    if _is_reauth_response(resp) and await self._reauth(
+                        auth, extra_headers=extra_headers, json_body=json_body, file_body=file_body
+                    ):
+                        continue
+                    return resp
+
+                # The per-status retry POLICY (cold-start 503/409, 429, 500, 404) lives
+                # in _status_retry_delay: it returns the seconds to back off, or None
+                # when the status is not one it retries (fall through to reauth /
+                # terminal below), or raises the terminal error itself.
+                retry_delay = _status_retry_delay(
+                    self._rng,
+                    resp,
+                    method=method,
+                    path=path,
+                    idempotent=idempotent,
+                    retry_not_found=retry_not_found,
+                    retry_500_delays=retry_500_delays,
+                    state=state,
+                )
+                if retry_delay is not None:
+                    await asyncio.sleep(retry_delay)
+                    continue
+
+                # A reauth response (401/403, or a 4xx reauth envelope): the session
+                # likely lapsed faster than the connector's keep-alive. Re-mint off the
+                # live connection and retry once; a concurrent burst is de-duplicated to
+                # a single re-mint in the config layer, so all the sharing requests
+                # recover together. If there is nothing to refresh, or the fresh token
+                # also fails, fall through to the terminal auth error.
+                if _is_reauth_response(resp) and await self._reauth(
+                    auth, extra_headers=extra_headers, json_body=json_body, file_body=file_body
+                ):
+                    continue
+                raise _status_to_error(resp.status_code, resp.text)
+
+    async def _reauth(
+        self,
+        auth: _RequestAuth,
+        *,
+        extra_headers: Mapping[str, str] | None,
+        json_body: Any,
+        file_body: BinaryIO | None,
+    ) -> bool:
+        """Re-mint the token once on a reauth response and rebuild *auth*'s headers.
+
+        Mutates ``auth`` in place (fresh token + rebuilt headers) and returns True
+        when the caller should retry, False when there is nothing to refresh or the
+        fresh token is unchanged. ``auth.refreshed`` bounds this to a single re-mint
+        per request, so a fresh token that still fails surfaces as a real auth error.
+        """
+        if auth.refreshed:
+            return False
+        auth.refreshed = True
+        new_pat = await self._refresh_auth(auth.sent_pat)
+        if new_pat is None or new_pat == auth.sent_pat:
+            return False
+        auth.sent_pat = new_pat
+        auth.headers = self._auth_headers(extra_headers)  # fresh read: new token
+        if json_body is not None:
+            auth.headers.setdefault("Content-Type", "application/json")
+        if file_body is not None:
+            auth.headers["Content-Length"] = str(_seekable_size(file_body))
+        return True
+
+    async def download(
+        self,
+        endpoint: str,
+        sink: Callable[[bytes], object],
+        *,
+        params: Mapping[str, str] | None = None,
+        timeout: float | None = None,
+        retry_not_found: bool = True,
+    ) -> httpx.Response:
+        """GET ``endpoint`` and hand each chunk to ``sink`` as it arrives.
+
+        Separate from `request()` because that reads the whole body into memory
+        before returning, which for a file means holding it twice -- once in the
+        response and once on the way to disk. The returned response has been fully
+        consumed; only its status and headers are still meaningful.
+
+        Error mapping is `request()`'s, applied to the response *before* any chunk
+        is handed over, so a 4xx never reaches the sink. Retry is the initial open
+        only, exactly as `stream_sse` does it: a create-race 404 or a "not ready"
+        409/503 is absorbed on the bounded schedule, and a failure after bytes have
+        been delivered surfaces rather than restarting a partial file.
+        """
+        await self._ensure_pat()
+        # One in-flight request for the whole download, re-opens included, so a
+        # concurrent `async with` exit cannot close the client mid-file (see
+        # _in_flight_request).
+        async with self._in_flight_request():
+            client, semaphore = await self._get_client()
+            path = self._full_path(endpoint)
+            cfg = self.config
+            headers = self._auth_headers(cfg=cfg)
+            sent_pat = cfg.resolve_pat()
+            auth_refreshed = False
+            open_attempt = 0
+            while True:
+                async with semaphore:
+                    try:
+                        async with client.stream(
+                            "GET",
+                            path,
+                            params=params,
+                            headers=headers,
+                            timeout=timeout if timeout is not None else self.config.timeout_s,
+                        ) as resp:
+                            if resp.status_code >= 400:
+                                body = await resp.aread()
+                                # Full body: _status_to_error unwraps the error envelope
+                                # and truncates any non-envelope fallback itself.
+                                text = body.decode("utf-8", errors="replace")
+                                open_attempt += 1
+                                delay = _sse_open_retry_delay(
+                                    resp.status_code,
+                                    resp,
+                                    open_attempt,
+                                    self._rng,
+                                    retry_not_found=retry_not_found,
+                                )
+                                if delay is not None:
+                                    await asyncio.sleep(delay)
+                                    continue  # re-open: nothing was delivered
+                                # Reauth response: re-mint once and re-open (nothing was
+                                # delivered). See request().
+                                if _is_reauth_response(resp) and not auth_refreshed:
+                                    auth_refreshed = True
+                                    new_pat = await self._refresh_auth(sent_pat)
+                                    if new_pat is not None and new_pat != sent_pat:
+                                        sent_pat = new_pat
+                                        headers = self._auth_headers()
+                                        continue
+                                raise _status_to_error(resp.status_code, text)
+                            async for chunk in resp.aiter_bytes():
+                                # The type hint accepts an async sink, so mypy approved
+                                # one -- but a bare ``sink(chunk)`` merely built a
+                                # coroutine and dropped it, delivering ZERO bytes under
+                                # a 200 (an empty file, silently). Await it if awaitable.
+                                result = sink(chunk)
+                                if inspect.isawaitable(result):
+                                    await result
+                            return resp
+                    except _UNSENT_ERRORS as exc:
+                        open_attempt += 1
+                        delay = compute_backoff(
+                            open_attempt, delays=DEFAULT_COLD_START_DELAYS_S, rng=self._rng
+                        )
+                        if delay is None:
+                            raise SandboxTransportError(
+                                f"transport error after retries: {exc}"
+                            ) from exc
+                        await asyncio.sleep(delay)
+                    except _SENT_ERRORS as exc:
+                        # A read/protocol failure mid-stream, after chunks may already
+                        # have reached the sink. Converted to the transport taxonomy so a
+                        # caller catching SandboxError sees it, but never retried: re-opening
+                        # would restart a file the sink has partly written, and the caller
+                        # cannot tell the resend from a fresh body. Same rule stream_sse
+                        # applies to _SENT_ERRORS.
+                        raise SandboxTransportError(f"transport error mid-download: {exc}") from exc
+
+    def stream_sse(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        json_body: Any = None,
+        timeout: float | None = None,
+        retry_not_found: bool = True,
+        abort: AsyncStreamAbort | None = None,
+    ) -> AsyncIterator[SSEEvent]:
+        """Open an SSE stream and yield parsed events.
+
+        *abort* lets terminate() interrupt the read -- see `AsyncStreamAbort`.
+        Without it a reader stays blocked until the HTTP read timeout, which on the
+        default exec budget is 630s.
+
+        The **initial open** follows the same retry policy as `request()`: a
+        create-race 404, a 429 (now capped at the shared budget, not retried
+        forever), or a 409/503 that says "not ready" is absorbed on the bounded
+        schedule, because none of them ran the request. Once any frame has been
+        delivered the stream is never re-opened -- a mid-stream disconnect surfaces
+        as ``SandboxTransportError`` so the caller can decide, and re-POSTing an
+        exec that is already running is exactly the duplicate this SDK must not
+        create.
+
+        ``retry_not_found=False`` returns a 404 immediately instead of paying the
+        ~8s create-race backoff -- for a caller resuming against a user-supplied or
+        possibly-vanished session id.
+
+        Returns an async iterator (not a coroutine) so callers can
+        ``async for evt in t.stream_sse(...):`` without an extra await.
+        """
+        path = self._full_path(endpoint)
+
+        return _stream_sse_impl(
+            self,
+            method,
+            path,
+            json_body=json_body,
+            timeout=timeout if timeout is not None else self.config.timeout_s,
+            retry_not_found=retry_not_found,
+            abort=abort,
+        )
+
+
+async def _stream_sse_impl(
+    transport: Transport,
+    method: str,
+    path: str,
+    *,
+    json_body: Any,
+    timeout: float | None,
+    retry_not_found: bool = True,
+    abort: AsyncStreamAbort | None = None,
+) -> AsyncIterator[SSEEvent]:
+    await transport._ensure_pat()
+    headers = transport._auth_headers({"Accept": "text/event-stream"})
+    if json_body is not None:
+        headers.setdefault("Content-Type", "application/json")
+    # The token these headers carry, for the reauth self-heal (see request()).
+    # getattr keeps this module function usable by a minimal fake transport that
+    # implements only what it touches; a fake with no config just never refreshes.
+    _cfg = getattr(transport, "config", None)
+    sent_pat = _cfg.resolve_pat() if _cfg is not None else None
+    auth_refreshed = False
+    # A live SSE stream is an in-flight request for its whole life: closing the client
+    # under a reader is exactly the tear-down this guard prevents, so a concurrent
+    # `async with` exit waits for the stream to end (see _in_flight_request).
+    async with transport._in_flight_request():
+        client, _semaphore = await transport._get_client()
+        open_attempt = 0
+        while True:
+            if abort is not None and abort.aborted:
+                return
+            try:
+                async with client.stream(
+                    method,
+                    path,
+                    json=json_body,
+                    headers=headers,
+                    timeout=timeout,
+                ) as resp:
+                    if resp.status_code >= 400:
+                        body = await resp.aread()
+                        # Full body: _status_to_error unwraps the error envelope
+                        # and truncates any non-envelope fallback itself.
+                        text = body.decode("utf-8", errors="replace")
+                        open_attempt += 1
+                        delay = _sse_open_retry_delay(
+                            resp.status_code,
+                            resp,
+                            open_attempt,
+                            transport._rng,
+                            retry_not_found=retry_not_found,
+                        )
+                        if delay is not None:
+                            await asyncio.sleep(delay)
+                            continue  # re-open the stream
+                        # Reauth response: re-mint once and re-open the stream (no frame
+                        # delivered yet, so no duplicate exec). See request().
+                        if (
+                            _is_reauth_response(resp)
+                            and not auth_refreshed
+                            and sent_pat is not None
+                        ):
+                            auth_refreshed = True
+                            new_pat = await transport._refresh_auth(sent_pat)
+                            if new_pat is not None and new_pat != sent_pat:
+                                sent_pat = new_pat
+                                headers = transport._auth_headers({"Accept": "text/event-stream"})
+                                if json_body is not None:
+                                    headers.setdefault("Content-Type", "application/json")
+                                continue
+                        # One shared terminal table (see _status_to_error): a persistent
+                        # 429 now raises SandboxRateLimitError instead of the old
+                        # SandboxTransportError, and 409/413/unknown match request() and
+                        # download() exactly.
+                        raise _status_to_error(resp.status_code, text)
+                    if abort is not None:
+                        await abort.bind(resp)
+                    try:
+                        async for evt in _iter_sse_frames(resp):
+                            yield evt
+                    finally:
+                        if abort is not None:
+                            abort.unbind()
+                    return
+            except _UNSENT_ERRORS as exc:
+                # Nothing was written, so re-opening cannot duplicate the exec.
+                open_attempt += 1
+                delay = compute_backoff(
+                    open_attempt, delays=DEFAULT_COLD_START_DELAYS_S, rng=transport._rng
+                )
+                if delay is None:
+                    raise SandboxTransportError(f"SSE transport error: {exc}") from exc
+                await asyncio.sleep(delay)
+            except _SENT_ERRORS as exc:
+                # The stream was cut after the request was written -- the ordinary end
+                # of a long-lived SSE, and `RemoteProtocolError` wrapping an h2
+                # `ConnectionTerminated` (a graceful GOAWAY) is the common shape.
+                #
+                # Converted, not retried. Re-opening here would re-run a streaming
+                # `exec` with its full side effects, for the reason `_IDEMPOTENT_METHODS`
+                # gives above; the transport cannot know the caller can resume. Callers
+                # that can, do: `shell.py` re-opens from its last frame id, which the
+                # sandbox answers exactly. Callers that cannot get a typed error instead
+                # of an httpx internal.
+                #
+                # All five members on purpose. This clause used to hand-list ReadError
+                # and ReadTimeout, so WriteError, WriteTimeout and RemoteProtocolError
+                # escaped the generator, sailed past shell.py's
+                # `except SandboxTransportError` reconnect loop, and reached the CLI as
+                # `<ConnectionTerminated error_code:0, last_stream_id:2147483647>` --
+                # killing a live terminal that the resume path was built to save.
+                raise SandboxTransportError(f"SSE transport error: {exc}") from exc
+
+
+_transport_lock = threading.Lock()
+# Transport pool, keyed ``(role, scope)``: ``role`` is the uppercased Snowflake role
+# (``None`` for no role override) and ``scope`` is the identity of an enclosing
+# ``using()`` connection (``None`` outside one). Created lazily on first
+# get_transport() call.
+#
+# ``scope`` is part of the key because an ``httpx.AsyncClient`` bakes ``base_url``
+# and ``verify`` in at construction (see ``_get_client``): a transport that merely
+# re-read the config per request would keep talking to whichever host it was first
+# used against, and would send a scoped account's token to the previous account's
+# host.
+_transport_pool: dict[tuple[str | None, str | None], Transport] = {}
+
+
+def get_transport_for_config(config: Config, role: str | None = None) -> Transport:
+    """Return the pooled transport for an explicitly-resolved `Config`.
+
+    The single place an explicit connection becomes a transport: both ``connection=`` on
+    an entry point and a ``using()`` block arrive here, so the two cannot drift apart.
+    Keyed on ``(role, credential identity)`` -- see ``config._scope_key`` for why the
+    credential is part of that, and why a scoped transport carries its Config instead of
+    late-binding.
+    """
+    from snowflake.sandbox.config import _scope_key
+
+    key: str | None = role.upper() if role else None
+    with _transport_lock:
+        entry = (key, _scope_key(config))
+        if entry not in _transport_pool:
+            _transport_pool[entry] = Transport(config=config, role_key=None)
+        return _transport_pool[entry]
+
+
+def get_transport(role: str | None = None) -> Transport:
+    """Return the process-wide async transport for the given role, creating it lazily.
+
+    ``role=None`` (the default) returns the no-role transport. Passing a role returns
+    a transport that resolves the ambient connection AT that role, so concurrent agents
+    using different roles never share a transport or HTTP client.
+
+    Inside a ``using()`` block, returns that block's transport instead -- the ambient
+    transport is only for callers who named no connection at all.
+    """
+    from snowflake.sandbox.config import _scoped_config
+
+    cfg = _scoped_config(role)
+    if cfg is not None:
+        return get_transport_for_config(cfg, role)
+    key: str | None = role.upper() if role else None
+    with _transport_lock:
+        entry = (key, None)
+        if entry not in _transport_pool:
+            # The ambient transport re-resolves through ``current_config(role=...)``.
+            _transport_pool[entry] = Transport(role_key=key)
+        return _transport_pool[entry]
+
+
+def is_pooled_transport(transport: Transport) -> bool:
+    """True when ``transport`` is one of this module's process-wide pool slots.
+
+    Identity against the pool, not "was the ``transport=`` argument ``None``". The
+    SDK SELF-injects the shared transport on several paths -- ``_hydrate_sandbox()``
+    (so every handle from ``list_sandboxes`` / ``get_sandbox`` / ``get_sandbox_by_name``)
+    and ``create(role=...)``, which passes ``get_transport(role)`` -- so an
+    argument-based test called those caller-owned and excluded them from the refcount.
+    A transport a caller built themselves (``Transport(config=...)``) is not in the
+    pool, so its lifetime stays entirely theirs; a caller who passes
+    ``get_transport()`` explicitly is handing us the shared pool and is treated as such.
+
+    Any role slot counts, not just the default one, so a role-scoped sandbox releases
+    the client it actually used.
+    """
+    with _transport_lock:
+        return any(t is transport for t in _transport_pool.values())
+
+
+def reset_scoped_transports() -> None:
+    """Drop every transport bound to an explicit connection, closing their clients.
+
+    Called by ``close_connections()``. An explicitly-bound transport carries its `Config`
+    (that is what keeps it pointed at the right host), and that Config may reference a
+    live connector session. ``close_connections()`` CLOSES those sessions, which would leave
+    such a transport authenticating from a dead session -- its next request fails to
+    auth, and nothing would ever re-resolve it.
+
+    The ambient transport never had this problem: it re-resolves through
+    ``current_config()``, so after a reset it simply resolves a fresh config. Explicit
+    binding is what makes this cleanup necessary, so it is done here rather than left
+    to the caller.
+    """
+    with _transport_lock:
+        doomed = [k for k in _transport_pool if k[1] is not None]
+        entries = [_transport_pool.pop(k) for k in doomed]
+    for t in entries:
+        t._close_sync_best_effort()
+
+
+def close_scoped_transports_for(scope_key: str) -> None:
+    """Close only the scoped async transports built for ONE credential scope.
+
+    The narrow counterpart of `reset_scoped_transports`; see
+    `_sync_transport.close_scoped_sync_transports_for` for why
+    ``using(..., close=True)`` needs the narrow form rather than the global one.
+    """
+    with _transport_lock:
+        doomed = [k for k in _transport_pool if k[1] == scope_key]
+        entries = [_transport_pool.pop(k) for k in doomed]
+    for t in entries:
+        t._close_sync_best_effort()
+
+
+def _take_all_transports() -> list[Transport]:
+    """Detach and return every pooled transport (all roles, all ``using()`` scopes).
+
+    ``shutdown()`` used to close only the default slot, so a role-scoped or scoped
+    connection's client stayed open until interpreter exit -- the one thing
+    ``shutdown()`` exists to prevent. Take-once under the lock, as above: a
+    concurrent second caller gets an empty list rather than double-closing.
+    """
+    with _transport_lock:
+        entries = list(_transport_pool.values())
+        _transport_pool.clear()
+    return entries
+
+
+def reset_transport(role: str | None = None) -> None:
+    """Drop one (or all) async transports from the pool, closing their HTTP clients.
+
+    Called with no arguments (or ``role=None``) to close **all** pool entries.
+
+    Called with a specific role, it closes **every** entry for that role — the ambient
+    one and each connection a ``using()`` block or a ``connection=`` argument bound,
+    since the pool is keyed ``(role, credential)``. Other roles are untouched. The
+    broader-than-it-looks blast radius is deliberate: a caller asking for a role's
+    clients to be released means all of them, not whichever one happened to be ambient.
+
+    Best-effort synchronous close: prefer the async ``shutdown()`` where you can
+    await it -- e.g. at the end of a notebook kernel or a request handler.
+    """
+    key: str | None = role.upper() if role else None
+    with _transport_lock:
+        if role is None:
+            entries = list(_transport_pool.values())
+            _transport_pool.clear()
+        else:
+            # Every scope's slot for this role, not just the ambient one: the caller
+            # asked for this role's clients to be released.
+            doomed = [k for k in _transport_pool if k[0] == key]
+            entries = [_transport_pool.pop(k) for k in doomed]
+    for t in entries:
+        t._close_sync_best_effort()