mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/hosted_session_worker.py

@@ -0,0 +1,3554 @@
+"""The warm worker behind one research session (ADR 0021).
+
+A session worker is not a new kind of worker. Studio's ``RESEARCH-SESSIONS.md`` is explicit about
+it: *"A session worker IS a producer-role attempt on the session run"*, with ``worker_kind =
+"session"`` and two extra capability scopes, so everything it does after the lease --
+``attempt:start``, batch ``event:append``, ``attempt:heartbeat``, ``attempt:fail`` -- is an existing
+fenced producer callback with the existing workspace/run/attempt/generation/fence binding. Only
+four verbs are new -- ``probes:claim``, ``probes/{id}:result``, and the ``session-acquisitions``
+pair that gives a probe its bytes -- and this module is the whole of the harness half of that
+protocol.
+
+Read this module against :mod:`mostlyright.data_harness.hosted_bootstrap`, which establishes the
+same workload-identity and bounded-secret handling discipline.
+
+**What is kept.** Ambient workload identity is read once, from the metadata server, into a
+``bytearray`` that is zeroed in a ``finally``. The capability that comes back is never a ``str``
+this module holds: it goes straight into a :class:`~mostlyright.data_harness.hosted_worker.
+CredentialLease`, which is non-serializable, redacted in every repr, and zeroed on close. There is
+exactly one capability per attempt and exactly one attempt per session, so "one capability per
+attempt" survives verbatim. Nothing is written to disk: the lease response is parsed out of a
+bounded in-memory buffer that is zeroed as soon as the capability is inside its lease.
+
+**What is different, and why it has to be.** The generic bootstrap reads a dispatch descriptor from
+a file descriptor because producer and verifier jobs carry sealed job descriptions. A research
+session Job instead receives three non-secret arguments and uses the atomically claimed dispatch
+record in Studio as its bootstrap authority. A capability-free monitor starts an isolated child;
+only that child exchanges and retains the capability in ``CredentialLease`` for the session
+lifetime, never in argv, environment or a descriptor visible to another task.
+
+**Request lifetime, and how scale-to-zero actually happens.** This is a Cloud Run *Job*, not a
+service. Studio supplies only an opaque UUID4 dispatch id, an exact Studio exchange URL and the OIDC
+audience as task arguments. The task reads its ambient workload identity, atomically exchanges the
+dispatch id for the one fenced session lease, and runs :class:`SessionSupervisor` synchronously to
+its terminal state. The Job task is therefore the unit Cloud Run retains: an overlapping session
+gets a distinct task and cannot share a warm service instance or an in-memory capability with the
+first.
+
+The dispatch id is deliberately not a lease nonce. It is non-secret routing data, accepted exactly
+once by Studio's transaction that creates and fences the attempt. The capability appears only in the
+exchange response, immediately enters ``CredentialLease``, and is zeroed when the supervisor exits.
+Job retry policy and task timeout are deployment controls, not a second leasing protocol: a retry
+of an already-claimed dispatch receives Studio's typed duplicate/terminal refusal and must not run a
+second supervisor.
+
+**Exit is by stopping, never by completing.** There is no ``:complete`` here. Studio's contract
+says why: ``:complete`` requires an admitted candidate, which a session never has, and after a
+close the session run is already terminal so ``:fail`` cannot land either. ``:fail`` is reserved
+for the one case where it is still meaningful -- the worker dying while its session is still live.
+
+**Heartbeat is liveness, never activity.** It runs on its own timer thread and it deliberately does
+not touch ``last_activity_at`` server-side. That is Studio's rule and the reason is the bill: a
+worker heartbeats every thirty seconds, so counting a heartbeat as activity would mean no session
+ever goes idle and scale-to-session never happens. Nothing in this module tries to keep a session
+alive; keeping a session alive is the user's job, by using it.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import logging
+import math
+import os
+import re
+import select
+import signal
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field, replace
+from datetime import UTC, datetime
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any, ClassVar, Protocol
+from uuid import UUID
+
+from mostlyright.data_harness import progress_events, session_probes
+from mostlyright.data_harness.acquisition.parsing import ParseLimits
+from mostlyright.data_harness.acquisition.result_download import (
+    ResultDownloadError,
+    validate_result_download,
+    verify_result_bytes,
+)
+from mostlyright.data_harness.canonical import canonical_json_bytes, sha256_bytes
+from mostlyright.data_harness.hosted_bootstrap import (
+    BootstrapTransport,
+    UrlLibBootstrapTransport,
+    _https_url,
+    _metadata_identity,
+)
+from mostlyright.data_harness.hosted_crawler_protocol import (
+    HostedCrawlerProtocolError,
+    parse_crawler_result,
+)
+from mostlyright.data_harness.hosted_worker import (
+    MAX_CAPABILITY_BYTES,
+    CredentialLease,
+    HostedWorkerError,
+    _authenticated_client,
+    _idempotency,
+    _load_generated,
+    _new_transfer_client,
+    _ProducerAuthority,
+    _response,
+    _strict_json,
+    parse_capability,
+)
+from mostlyright.data_harness.linux_process_boundary import (
+    _child_subreaper_enabled,
+    _set_child_subreaper,
+)
+
+LOGGER = logging.getLogger(__name__)
+
+#: The role this worker presents. Studio mints the attempt with ``worker_kind = "session"``; the
+#: value is restated here only for the progress record that names the role.
+SESSION_WORKER_ROLE = "session"
+
+#: The one path Studio invokes, spelled by ``GoogleCloudRunSessionWorkerStarter``.
+START_PATH = "/sessions:start"
+#: An internal, descriptor-only command used by the retained Service rollback path.  The service
+#: process starts a fresh interpreter rather than forking Python from a request thread; the only
+#: value passed in argv is an inherited descriptor number, never a nonce or capability.
+LEGACY_BOOTSTRAP_FD_ARGUMENT = "--legacy-bootstrap-fd"
+#: Liveness only. Cloud Run's startup probe needs an endpoint that answers before a session exists,
+#: and answering it must never imply a session is warm -- ``warming`` is Studio's state to clear,
+#: on a fenced attempt callback, and a 200 from here is not one.
+HEALTH_PATHS = ("/livez", "/healthz")
+
+#: Studio's start invocation carries its own contract version.
+START_SCHEMA_VERSION = "3.0.0"
+#: Cloud Run Job dispatches use the same schema as the lease response they mint.  The dispatch
+#: itself is deliberately only an opaque routing token; it is never a capability or lease nonce.
+SESSION_DISPATCH_SCHEMA_VERSION = "3.0.0"
+#: The only Studio URL a Job task may exchange its dispatch id against.  The id is part of the
+#: path so a task cannot turn an opaque value into a request to a neighbouring session.
+SESSION_DISPATCH_EXCHANGE_PATH_TEMPLATE = (
+    "/internal/v3/session-worker/dispatches/{dispatch_id}:exchange"
+)
+#: Studio refuses an exchange after its one dispatch has already been consumed. These are normal
+#: no-op terminal outcomes for a Cloud Run Job task, not failed executions: the task must not
+#: invoke ``attempt:start`` after another task has claimed it or after Studio has closed it.
+CONSUMED_SESSION_DISPATCH_CODES = frozenset(
+    {
+        "RESEARCH_SESSION_DISPATCH_ALREADY_CLAIMED",
+        "RESEARCH_SESSION_DISPATCH_CLOSED",
+    }
+)
+#: The lease path Studio publishes. Derived here rather than taken from the invocation; see
+#: :func:`parse_start_invocation`.
+LEASE_PATH_TEMPLATE = "/internal/v3/session-worker/sessions/{session_id}:lease"
+
+#: A start invocation is five short fields. Anything larger is not one.
+MAX_START_REQUEST_BYTES = 8 * 1024
+#: A lease has no source bytes and must remain a small control-plane document.  This separate
+#: bound means a compromised exchange cannot make a long-lived Job hold an arbitrary response.
+MAX_SESSION_DISPATCH_RESPONSE_BYTES = 64 * 1024
+#: The service-to-fresh-interpreter start document is an already validated start request and must
+#: stay no larger than the public request surface.  The child accepts exactly one such document.
+MAX_LEGACY_BOOTSTRAP_BYTES = MAX_START_REQUEST_BYTES
+#: Service start must not acknowledge until its fresh monitor has installed the cancellation
+#: handler that owns an inner capability child. This remains far below Studio's start request
+#: timeout while rejecting a stuck/interrupted bootstrap rather than accepting a zombie session.
+LEGACY_BOOTSTRAP_READY_TIMEOUT_SECONDS = 5.0
+#: Studio bounds the nonce at 32..128 URL-safe characters.
+MIN_NONCE_CHARS = 32
+MAX_NONCE_CHARS = 128
+
+#: How long the process waits for another session before exiting so Cloud Run can drop the
+#: instance. Long enough that reopening a session is warm, short enough that a finished session is
+#: not billed for a coffee break.
+DEFAULT_SHUTDOWN_GRACE_SECONDS = 30.0
+#: Pre-spawned no-network sandbox children. This is the first production caller of the warm pool
+#: (#306), and the pool exists precisely for this: the follow-up-probe budget is 100-300 ms and a
+#: cold interpreter spawn does not fit in it. On Linux under a bounded cgroup root
+#: ``start_warm_pool`` returns 0 by design -- the count is read, not assumed, and a zero is not an
+#: error, only a slower first probe.
+DEFAULT_WARM_POOL_SIZE = 2
+#: A probe is interactive. A probe that is not finished in this long is failed, not waited on.
+DEFAULT_PROBE_TIMEOUT_SECONDS = 45.0
+#: How long one session acquisition may take from the create call to a settled status. This is the
+#: network half of a probe and it is bounded SEPARATELY from the Clean room ceiling above, because
+#: the two fail for unrelated reasons and a client that is told "the crawl did not come back" can
+#: act on that differently from "parsing did not finish".
+DEFAULT_ACQUISITION_TIMEOUT_SECONDS = 90.0
+#: How often the worker asks Studio whether its acquisition has settled. Fixed rather than backed
+#: off: the whole wait is bounded above by one interactive ceiling, so a backoff would only make
+#: the common fast case slower without making the slow case cheaper.
+ACQUISITION_POLL_SECONDS = 1.0
+#: The largest quarantine bundle a probe will pull into memory. The contract's own ceiling is 6 GiB
+#: -- correct for a Build, absurd for a preview -- and the bundle is base64 inside canonical JSON,
+#: so this is comfortably above `ProbeExecutor._max_source_bytes` (16 MiB) times the 4/3 encoding
+#: expansion plus the receipt. A bundle over it is refused on its DECLARED size, before a byte is
+#: transferred, which is the only place refusing is free.
+MAX_PROBE_ACQUISITION_BUNDLE_BYTES = 32 * 1024 * 1024
+#: Poll and heartbeat floors, used only when a lease omits them (it cannot -- both are required --
+#: but a default beats a KeyError if Studio ever relaxes that).
+FALLBACK_CLAIM_POLL_SECONDS = 1.0
+FALLBACK_HEARTBEAT_SECONDS = 30.0
+#: A refused claim poll is transient far more often than it is fatal. After this many in a row the
+#: worker gives up on the session rather than polling a Studio that is saying no forever.
+MAX_CONSECUTIVE_CLAIM_FAILURES = 10
+#: Studio only lets a session shorten the ordinary thirty-minute producer lease.  A later value
+#: would make a compromised or mismatched control plane turn one session capability into an
+#: unbounded worker lifetime, so it is a lease refusal rather than a value to clamp.
+MAX_SESSION_CAPABILITY_REMAINING_SECONDS = 30 * 60
+#: The isolated session child communicates only an expiry, identity and terminal summary to its
+#: capability-free parent. It has no reason to emit a large record, and this ceiling makes the
+#: parent-side parser a fixed-memory boundary if a child is compromised.
+MAX_SESSION_SUPERVISOR_MESSAGE_BYTES = 128 * 1024
+
+_UTC_TIMESTAMP = re.compile(
+    r"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]{1,6})?Z$"
+)
+
+#: The failure codes that mean the probe was REFUSED rather than attempted-and-broken. The
+#: distinction is the only part of a failure a client can act on: a refused probe refuses the same
+#: way every time, so the fix is a different probe -- or, for the source channel, somebody wiring
+#: one -- while a broken probe may well not break twice. The set is written out rather than
+#: inferred from the exception class, because the same class carries both halves.
+PROBE_REFUSAL_CODES = frozenset(
+    {
+        # The open gap: no session-scoped source channel exists, so nothing was read.
+        "PROBE_SOURCE_CHANNEL_UNAVAILABLE",
+        # The session's own authority check, made before any read.
+        "PROBE_SOURCE_OUT_OF_SCOPE",
+        # A reader that answered for a different source. Refused before the bytes are used.
+        "PROBE_SOURCE_MISMATCH",
+        # The request body is not in the probe vocabulary.
+        "PROBE_REQUEST_INVALID",
+        # The request names a column, or an aggregate over a column, this source cannot answer.
+        # Discovered after the read rather than before it, and still a refusal of the REQUEST:
+        # re-asking it changes nothing.
+        "PROBE_COLUMN_UNKNOWN",
+        "PROBE_AGGREGATE_NOT_NUMERIC",
+        # Studio's own refusals on the session-acquisition door. The first is the session's
+        # source allowlist, checked before any lookup so a refusal is not an existence oracle;
+        # the second is "this source has no single active public.https registration", which is a
+        # fact about the source's registration and not about this probe.
+        "RESEARCH_SOURCE_FORBIDDEN",
+        "RESEARCH_SOURCE_UNACQUIRABLE",
+        # The acquired source is larger than a probe may hold. A property of the source.
+        "PROBE_SOURCE_TOO_LARGE",
+    }
+)
+#: The Clean room's own code for "did not finish in time" (`acquisition.sandbox`). It is distinct
+#: from a source acquisition timing out: reducing a scan can help after bytes arrived, but cannot
+#: make a delayed remote acquisition arrive sooner.
+PROBE_TIMEOUT_CODES = frozenset({"SANDBOX_TIMEOUT", "PROBE_SOURCE_ACQUISITION_TIMEOUT"})
+#: Studio's code for an acquisition whose own expiry passed -- the earliest of the crawler-session
+#: TTL, the deployment's admission window and the worker's attempt lease. It is the one failure the
+#: reader retries, because Studio releases the admission slot as it expires the acquisition, so
+#: opening a fresh one is not a second spend. See :meth:`StudioSessionAcquisitionReader.read`.
+ACQUISITION_EXPIRED_CODE = "CRAWLER_SESSION_EXPIRED"
+#: A ceiling somebody else is holding, not a refusal of this request. Studio charges a session
+#: acquisition to the principal who opened the session, against the same active-and-rate admission
+#: limits a person acquiring by hand would spend (ADR 0015: two at once, four in sixty seconds), so
+#: this arrives when the session is busy rather than when the probe is wrong. It is its own outcome
+#: because the advice it carries is the opposite of a refusal's: ask again in a moment.
+SESSION_ACQUISITION_THROTTLED = "SESSION_ACQUISITION_THROTTLED"
+#: Studio's wire code is retained in the probe result. The progress/UI code is separate so an
+#: acquisition admission window is not presented as model-token, billing, sign-in, or source-key
+#: configuration trouble.
+PROBE_THROTTLE_WIRE_CODES = frozenset({"AGENT_BUDGET_EXCEEDED"})
+PROBE_THROTTLE_CODES = frozenset({SESSION_ACQUISITION_THROTTLED})
+MAX_RETRY_AFTER_SECONDS = 3600
+
+_ENV_PORT = "PORT"
+_ENV_STUDIO_ORIGIN = "STUDIO_API_ORIGIN"
+_ENV_LEASE_AUDIENCE = "MR_SESSION_WORKER_LEASE_AUDIENCE"
+_ENV_WORKER_BOOTSTRAP_AUDIENCE = "STUDIO_WORKER_BOOTSTRAP_AUDIENCE"
+_ENV_SHUTDOWN_GRACE = "MR_SESSION_WORKER_SHUTDOWN_GRACE_SECONDS"
+_ENV_WARM_POOL = "MR_SESSION_WORKER_WARM_POOL_SIZE"
+_ENV_PROBE_TIMEOUT = "MR_SESSION_WORKER_PROBE_TIMEOUT_SECONDS"
+_ENV_ACQUISITION_TIMEOUT = "MR_SESSION_WORKER_ACQUISITION_TIMEOUT_SECONDS"
+_ENV_EXTERNAL_NETWORK_POLICY = "MOSTLYRIGHT_EXTERNAL_NETWORK_POLICY_ATTESTATION"
+_ENV_CRAWLER_RESULTS_BUCKET = "MOSTLYRIGHT_CRAWLER_RESULTS_BUCKET"
+
+
+class SessionWorkerError(RuntimeError):
+    """A coded session-worker refusal. The code is what a probe or a session fails with."""
+
+    def __init__(self, code: str, detail: str, *, retry_after_seconds: int | None = None) -> None:
+        super().__init__(f"{code}: {detail}")
+        self.code = code
+        self.detail = detail
+        self.retry_after_seconds = retry_after_seconds
+
+
+@dataclass(frozen=True)
+class SessionDispatch:
+    """The complete, non-secret argument contract of one Cloud Run Job task.
+
+    Nothing from the resulting lease belongs here.  In particular, keeping this object safe to
+    log is a guard against a future Terraform change accidentally moving a capability or nonce
+    into command arguments, which Cloud Run exposes as execution configuration.
+    """
+
+    dispatch_id: str
+    exchange_url: str
+    audience: str
+
+
+# ==========================================================================================
+# Configuration
+# ==========================================================================================
+
+
+@dataclass(frozen=True)
+class SessionWorkerConfig:
+    """Everything the service reads from its environment, validated once at start."""
+
+    studio_origin: str
+    lease_audience: str
+    port: int = 8080
+    shutdown_grace_seconds: float = DEFAULT_SHUTDOWN_GRACE_SECONDS
+    warm_pool_size: int = DEFAULT_WARM_POOL_SIZE
+    probe_timeout_seconds: float = DEFAULT_PROBE_TIMEOUT_SECONDS
+    acquisition_timeout_seconds: float = DEFAULT_ACQUISITION_TIMEOUT_SECONDS
+    external_network_policy_attestation: str | None = None
+    crawler_results_bucket: str | None = None
+
+
+def _positive_number(raw: str | None, default: float, label: str, *, maximum: float) -> float:
+    if raw is None or raw == "":
+        return default
+    try:
+        value = float(raw)
+    except ValueError as error:
+        raise SessionWorkerError("SESSION_WORKER_CONFIG_INVALID", f"{label} is not a number") from (
+            error
+        )
+    if not 0 < value <= maximum:
+        raise SessionWorkerError(
+            "SESSION_WORKER_CONFIG_INVALID", f"{label} must be in (0, {maximum}]"
+        )
+    return value
+
+
+def config_from_environment(environment: Mapping[str, str] | None = None) -> SessionWorkerConfig:
+    """Build the config, refusing rather than defaulting anything that is a coordinate."""
+
+    env = os.environ if environment is None else environment
+    origin = env.get(_ENV_STUDIO_ORIGIN, "")
+    if not origin:
+        raise SessionWorkerError(
+            "SESSION_WORKER_CONFIG_INVALID", f"{_ENV_STUDIO_ORIGIN} is required"
+        )
+    origin = origin.rstrip("/")
+    _https_url(origin, _ENV_STUDIO_ORIGIN)
+    # Studio verifies the session worker against the same closed workload-identity audience as the
+    # producer bootstrap exchange. The shared Cloud Run template already supplies that coordinate;
+    # consuming it here keeps the identity token's ``aud`` exact while preserving the explicit
+    # Harness override for a deliberately split deployment. An older deployment without the shared
+    # coordinate remains compatible with its historical origin audience.
+    audience = (
+        env.get(_ENV_LEASE_AUDIENCE, "") or env.get(_ENV_WORKER_BOOTSTRAP_AUDIENCE, "") or origin
+    )
+    _https_url(
+        audience,
+        (
+            _ENV_LEASE_AUDIENCE
+            if env.get(_ENV_LEASE_AUDIENCE, "")
+            else _ENV_WORKER_BOOTSTRAP_AUDIENCE
+            if env.get(_ENV_WORKER_BOOTSTRAP_AUDIENCE, "")
+            else _ENV_STUDIO_ORIGIN
+        ),
+    )
+    raw_port = env.get(_ENV_PORT, "8080")
+    try:
+        port = int(raw_port)
+    except ValueError as error:
+        raise SessionWorkerError("SESSION_WORKER_CONFIG_INVALID", "PORT is not an integer") from (
+            error
+        )
+    if not 1 <= port <= 65535:
+        raise SessionWorkerError("SESSION_WORKER_CONFIG_INVALID", "PORT is out of range")
+    raw_pool = env.get(_ENV_WARM_POOL, "")
+    try:
+        warm_pool = DEFAULT_WARM_POOL_SIZE if raw_pool == "" else int(raw_pool)
+    except ValueError as error:
+        raise SessionWorkerError(
+            "SESSION_WORKER_CONFIG_INVALID", f"{_ENV_WARM_POOL} is not an integer"
+        ) from error
+    if not 0 <= warm_pool <= 8:
+        raise SessionWorkerError("SESSION_WORKER_CONFIG_INVALID", f"{_ENV_WARM_POOL} must be 0..8")
+    return SessionWorkerConfig(
+        studio_origin=origin,
+        lease_audience=audience,
+        port=port,
+        shutdown_grace_seconds=_positive_number(
+            env.get(_ENV_SHUTDOWN_GRACE),
+            DEFAULT_SHUTDOWN_GRACE_SECONDS,
+            _ENV_SHUTDOWN_GRACE,
+            maximum=600.0,
+        ),
+        warm_pool_size=warm_pool,
+        probe_timeout_seconds=_positive_number(
+            env.get(_ENV_PROBE_TIMEOUT),
+            DEFAULT_PROBE_TIMEOUT_SECONDS,
+            _ENV_PROBE_TIMEOUT,
+            maximum=300.0,
+        ),
+        acquisition_timeout_seconds=_positive_number(
+            env.get(_ENV_ACQUISITION_TIMEOUT),
+            DEFAULT_ACQUISITION_TIMEOUT_SECONDS,
+            _ENV_ACQUISITION_TIMEOUT,
+            maximum=600.0,
+        ),
+        external_network_policy_attestation=env.get(_ENV_EXTERNAL_NETWORK_POLICY) or None,
+        # The same name the hosted producer reads, because it is the same quarantine bucket and a
+        # second spelling would be a second thing to get wrong on one deployment. Absent means a
+        # Studio-local result authority, which `validate_result_download` then requires.
+        crawler_results_bucket=env.get(_ENV_CRAWLER_RESULTS_BUCKET) or None,
+    )
+
+
+# ==========================================================================================
+# Cloud Run Job dispatch bootstrap
+# ==========================================================================================
+
+
+def _dispatch_uuid(value: Any) -> str:
+    if not isinstance(value, str):
+        raise SessionWorkerError("SESSION_DISPATCH_INVALID", "dispatch id must be a string")
+    try:
+        parsed = UUID(value)
+    except ValueError as error:
+        raise SessionWorkerError("SESSION_DISPATCH_INVALID", "dispatch id is not a UUID") from error
+    if parsed.version != 4 or str(parsed) != value:
+        raise SessionWorkerError(
+            "SESSION_DISPATCH_INVALID", "dispatch id must be a canonical UUID4"
+        )
+    return value
+
+
+def _dispatch_https_url(value: Any, label: str) -> str:
+    try:
+        return _https_url(value, label)
+    except HostedWorkerError as error:
+        raise SessionWorkerError("SESSION_DISPATCH_INVALID", error.detail) from error
+
+
+def parse_session_dispatch(argv: Sequence[str]) -> SessionDispatch:
+    """Parse exactly the three non-secret Job arguments, in their deployment order.
+
+    A normal argument parser intentionally permits flags in any order and can silently admit
+    future options.  Job overrides are a security boundary, so this parser instead spells the
+    only six argv cells Studio may create.  It also keeps the invocation object incapable of
+    carrying a lease nonce or capability.
+    """
+
+    values = tuple(argv)
+    flags = (
+        "--session-dispatch-id",
+        "--session-dispatch-exchange-url",
+        "--session-dispatch-audience",
+    )
+    if len(values) != 6 or values[::2] != flags or any(not item for item in values[1::2]):
+        raise SessionWorkerError(
+            "SESSION_DISPATCH_ARGUMENTS_INVALID",
+            "expected --session-dispatch-id, --session-dispatch-exchange-url and "
+            "--session-dispatch-audience in that order",
+        )
+    dispatch_id, exchange_url, audience = values[1::2]
+    return SessionDispatch(
+        dispatch_id=_dispatch_uuid(dispatch_id),
+        exchange_url=_dispatch_https_url(exchange_url, "session dispatch exchange URL"),
+        audience=_dispatch_https_url(audience, "session dispatch audience"),
+    )
+
+
+def _validate_session_dispatch(config: SessionWorkerConfig, dispatch: SessionDispatch) -> None:
+    """Bind a Job's opaque id to this deployment's one exchange endpoint.
+
+    The OIDC audience is intentionally supplied by Studio's Job override, but the URL itself must
+    remain derived from the locally pinned Studio origin.  This closes request-target substitution
+    even if an operator can create an execution override.
+    """
+
+    expected = config.studio_origin + SESSION_DISPATCH_EXCHANGE_PATH_TEMPLATE.format(
+        dispatch_id=dispatch.dispatch_id
+    )
+    if dispatch.exchange_url != expected:
+        raise SessionWorkerError(
+            "SESSION_DISPATCH_URL_UNRECOGNIZED",
+            "session dispatch exchange URL is not this deployment's endpoint for this dispatch",
+        )
+    if dispatch.audience != config.studio_origin:
+        raise SessionWorkerError(
+            "SESSION_DISPATCH_AUDIENCE_UNRECOGNIZED",
+            "session dispatch audience is not this deployment's Studio audience",
+        )
+
+
+def _dispatch_exchange_error(status: int, raw: bytearray) -> SessionWorkerError:
+    """Keep Studio's typed refusal without echoing a response that could contain a secret."""
+
+    try:
+        value = _strict_json(raw, "session dispatch exchange refusal")
+    except HostedWorkerError:
+        value = None
+    if isinstance(value, dict):
+        code = value.get("code")
+        if isinstance(code, str) and re.fullmatch(r"[A-Z][A-Z0-9_]{2,127}", code):
+            return SessionWorkerError(code, f"session dispatch exchange returned HTTP {status}")
+    return SessionWorkerError(
+        "SESSION_DISPATCH_EXCHANGE_FAILED", f"session dispatch exchange returned HTTP {status}"
+    )
+
+
+def exchange_session_dispatch(
+    *,
+    config: SessionWorkerConfig,
+    dispatch: SessionDispatch,
+    transport: BootstrapTransport | None = None,
+) -> tuple[SessionLease, CredentialLease]:
+    """Redeem one dispatch through Studio and return the sole fenced session lease.
+
+    The metadata identity proves the Job's workload principal.  The body is deliberately exact and
+    contains no secret: Studio's atomically claimed dispatch record is what binds that principal to
+    the resulting attempt.  An already claimed or terminal dispatch is a typed non-200 response;
+    callers must treat it as terminal rather than retrying into a second supervisor.
+    """
+
+    _validate_session_dispatch(config, dispatch)
+    active_transport = transport or UrlLibBootstrapTransport()
+    identity = _metadata_identity(active_transport, dispatch.audience)
+    payload = canonical_json_bytes(
+        {
+            "schema_version": SESSION_DISPATCH_SCHEMA_VERSION,
+            "dispatch_id": dispatch.dispatch_id,
+        }
+    )
+    try:
+        token = identity.decode("ascii")
+        status, response = active_transport.request(
+            "POST",
+            dispatch.exchange_url,
+            {
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+            },
+            payload,
+            MAX_SESSION_DISPATCH_RESPONSE_BYTES,
+        )
+    finally:
+        identity[:] = b"\x00" * len(identity)
+    raw = bytearray(response)
+    try:
+        if status != HTTPStatus.OK:
+            raise _dispatch_exchange_error(status, raw)
+        try:
+            lease_wire = _strict_json(raw, "session dispatch exchange response")
+        except HostedWorkerError as error:
+            raise SessionWorkerError(
+                "SESSION_DISPATCH_RESPONSE_INVALID", "session dispatch exchange response is invalid"
+            ) from error
+        try:
+            return parse_session_lease(lease_wire)
+        finally:
+            if isinstance(lease_wire, dict):
+                lease_wire.clear()
+    finally:
+        raw[:] = b"\x00" * len(raw)
+
+
+# ==========================================================================================
+# The start invocation
+# ==========================================================================================
+
+
+@dataclass(frozen=True)
+class StartInvocation:
+    """The four non-secret coordinates of one start signal. The nonce is never in here."""
+
+    session_id: str
+    workspace_id: str
+    lease_url: str
+
+
+def _uuid_text(value: Any, label: str) -> str:
+    if not isinstance(value, str):
+        raise SessionWorkerError("SESSION_START_INVALID", f"{label} must be a string")
+    try:
+        parsed = UUID(value)
+    except ValueError as error:
+        raise SessionWorkerError("SESSION_START_INVALID", f"{label} is not a UUID") from error
+    if str(parsed) != value:
+        raise SessionWorkerError("SESSION_START_INVALID", f"{label} is not canonical")
+    return value
+
+
+def parse_start_invocation(raw: bytes, *, studio_origin: str) -> tuple[StartInvocation, bytearray]:
+    """Admit one start invocation and separate the nonce from everything else.
+
+    The nonce comes back as a ``bytearray`` rather than a ``str`` so the caller can zero it, and it
+    is never a field on :class:`StartInvocation` so that logging or repr'ing the invocation cannot
+    print it.
+
+    ``lease_url`` is **checked, never followed**. The URL arrives inside a request body, and a
+    request body is data: a worker that fetched whatever URL it was handed -- carrying a Google
+    identity token minted for the audience it was configured with -- would be an SSRF primitive
+    with a credential attached, reachable by anything that could reach this port. The value is
+    therefore compared against the URL derived from ``STUDIO_API_ORIGIN`` and the session id, and a
+    mismatch is a refusal. The call itself is then made through the generated client bound to
+    ``STUDIO_API_ORIGIN``, so even a check that somehow passed could not redirect the request.
+    """
+
+    if len(raw) > MAX_START_REQUEST_BYTES:
+        raise SessionWorkerError("SESSION_START_TOO_LARGE", "start invocation exceeds its budget")
+    try:
+        value = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, ValueError) as error:
+        raise SessionWorkerError("SESSION_START_INVALID", "start invocation is not JSON") from error
+    if not isinstance(value, dict):
+        raise SessionWorkerError("SESSION_START_INVALID", "start invocation must be an object")
+    expected = {"schema_version", "session_id", "workspace_id", "lease_nonce", "lease_url"}
+    if set(value) != expected:
+        raise SessionWorkerError("SESSION_START_INVALID", "start invocation fields are not exact")
+    if value["schema_version"] != START_SCHEMA_VERSION:
+        raise SessionWorkerError("SESSION_START_INVALID", "start invocation schema is unsupported")
+    session_id = _uuid_text(value["session_id"], "session_id")
+    workspace_id = _uuid_text(value["workspace_id"], "workspace_id")
+    nonce = value["lease_nonce"]
+    if (
+        not isinstance(nonce, str)
+        or not MIN_NONCE_CHARS <= len(nonce) <= MAX_NONCE_CHARS
+        or not all(character.isalnum() or character in "_-" for character in nonce)
+    ):
+        raise SessionWorkerError("SESSION_START_INVALID", "lease nonce shape is invalid")
+    lease_url = value["lease_url"]
+    if not isinstance(lease_url, str):
+        raise SessionWorkerError("SESSION_START_INVALID", "lease_url must be a string")
+    derived = studio_origin.rstrip("/") + LEASE_PATH_TEMPLATE.format(session_id=session_id)
+    if lease_url != derived:
+        raise SessionWorkerError(
+            "SESSION_LEASE_URL_UNRECOGNIZED",
+            "lease_url is not this deployment's lease endpoint for this session",
+        )
+    return (
+        StartInvocation(session_id=session_id, workspace_id=workspace_id, lease_url=derived),
+        bytearray(nonce.encode("ascii")),
+    )
+
+
+# ==========================================================================================
+# The lease
+# ==========================================================================================
+
+
+@dataclass(frozen=True)
+class SessionContext:
+    """The workspace coordinate the session probes against. Also the probe authority allowlist."""
+
+    dataset_id: str
+    question_id: str
+    table_id: str | None
+    source_ids: frozenset[str]
+
+
+@dataclass(frozen=True)
+class SessionLease:
+    """Everything the lease said except the capability, which lives in a ``CredentialLease``."""
+
+    session_id: str
+    workspace_id: UUID
+    run_id: UUID
+    attempt_id: UUID
+    generation: int
+    fence: int
+    capability_expires_at: datetime
+    callback_base_url: str
+    allowed_callback_paths: tuple[str, ...]
+    heartbeat_interval_seconds: float
+    claim_poll_interval_seconds: float
+    idle_timeout_seconds: float
+    context: SessionContext
+
+
+def _positive_int(value: Any, label: str) -> int:
+    if type(value) is not int or value <= 0 or value > 2**53 - 1:
+        raise SessionWorkerError("SESSION_LEASE_INVALID", f"{label} is not a positive integer")
+    return value
+
+
+def _parse_utc_timestamp(value: Any, label: str) -> datetime:
+    """Parse Studio's canonical UTC instant without accepting a local-time interpretation."""
+
+    if not isinstance(value, str) or _UTC_TIMESTAMP.fullmatch(value) is None:
+        raise SessionWorkerError(
+            "SESSION_LEASE_INVALID", f"{label} must be a canonical UTC timestamp"
+        )
+    try:
+        pattern = "%Y-%m-%dT%H:%M:%S.%fZ" if "." in value else "%Y-%m-%dT%H:%M:%SZ"
+        return datetime.strptime(value, pattern).replace(tzinfo=UTC)
+    except ValueError as error:
+        raise SessionWorkerError(
+            "SESSION_LEASE_INVALID", f"{label} is not a real UTC timestamp"
+        ) from error
+
+
+def _wall_clock_now() -> datetime:
+    return datetime.now(UTC)
+
+
+@dataclass(frozen=True)
+class SessionDeadline:
+    """One capability boundary measured against both wall and monotonic clocks.
+
+    The wire instant is the authority, but a wall clock can jump backwards after the lease is
+    accepted.  Capturing its remaining duration on a monotonic clock prevents that jump from
+    extending a session.  Conversely, a forward wall-clock jump stops early, which is the safe
+    direction for a fenced credential.
+    """
+
+    expires_at: datetime
+    monotonic_expires_at: float
+    _wall_clock: Callable[[], datetime] = field(repr=False, compare=False)
+    _monotonic_clock: Callable[[], float] = field(repr=False, compare=False)
+
+    @classmethod
+    def from_lease(
+        cls,
+        lease: SessionLease,
+        *,
+        wall_clock: Callable[[], datetime] = _wall_clock_now,
+        monotonic_clock: Callable[[], float] = time.monotonic,
+    ) -> SessionDeadline:
+        return cls.from_expiry(
+            lease.capability_expires_at,
+            wall_clock=wall_clock,
+            monotonic_clock=monotonic_clock,
+        )
+
+    @classmethod
+    def from_expiry(
+        cls,
+        expires_at: datetime,
+        *,
+        wall_clock: Callable[[], datetime] = _wall_clock_now,
+        monotonic_clock: Callable[[], float] = time.monotonic,
+    ) -> SessionDeadline:
+        """Create a paired deadline from an already authenticated expiry instant."""
+
+        if not isinstance(expires_at, datetime) or expires_at.tzinfo is None:
+            raise SessionWorkerError(
+                "SESSION_LEASE_INVALID", "capability_expires_at is not an absolute instant"
+            )
+        expires_at = expires_at.astimezone(UTC)
+        now = cls._wall_now(wall_clock)
+        remaining = (expires_at - now).total_seconds()
+        if remaining <= 0:
+            raise SessionWorkerError(
+                "SESSION_CAPABILITY_EXPIRED",
+                "the session capability expired before the worker could use it",
+            )
+        if remaining > MAX_SESSION_CAPABILITY_REMAINING_SECONDS:
+            raise SessionWorkerError(
+                "SESSION_LEASE_EXPIRY_UNREASONABLE",
+                "the session capability exceeds the maximum producer lease",
+            )
+        monotonic_now = cls._monotonic_now(monotonic_clock)
+        return cls(
+            expires_at=expires_at,
+            monotonic_expires_at=monotonic_now + remaining,
+            _wall_clock=wall_clock,
+            _monotonic_clock=monotonic_clock,
+        )
+
+    @staticmethod
+    def _wall_now(clock: Callable[[], datetime]) -> datetime:
+        now = clock()
+        if not isinstance(now, datetime) or now.tzinfo is None:
+            raise SessionWorkerError(
+                "SESSION_CLOCK_INVALID", "the session worker wall clock is not an absolute instant"
+            )
+        return now.astimezone(UTC)
+
+    @staticmethod
+    def _monotonic_now(clock: Callable[[], float]) -> float:
+        value = float(clock())
+        if not math.isfinite(value):
+            raise SessionWorkerError(
+                "SESSION_CLOCK_INVALID", "the session worker monotonic clock is not finite"
+            )
+        return value
+
+    def remaining_seconds(self) -> float:
+        """Return the earliest safe deadline; a broken clock fails closed at zero."""
+
+        try:
+            wall_remaining = (self.expires_at - self._wall_now(self._wall_clock)).total_seconds()
+            monotonic_remaining = self.monotonic_expires_at - self._monotonic_now(
+                self._monotonic_clock
+            )
+        except (SessionWorkerError, TypeError, ValueError, OverflowError):
+            return 0.0
+        return min(wall_remaining, monotonic_remaining)
+
+    def expired(self) -> bool:
+        return self.remaining_seconds() <= 0
+
+    def bounded_wait(self, requested_seconds: float) -> float:
+        """Limit one interruptible wait to the remaining credential lifetime."""
+
+        return max(0.0, min(float(requested_seconds), self.remaining_seconds()))
+
+
+def _linux_direct_child_pids() -> frozenset[int]:
+    """Return direct children across threads, or fail closed if Linux cannot enumerate them."""
+
+    if sys.platform != "linux":
+        return frozenset()
+    children: set[int] = set()
+    try:
+        for task in Path("/proc/self/task").iterdir():
+            raw = (task / "children").read_text(encoding="ascii").strip()
+            if raw:
+                children.update(int(value) for value in raw.split())
+    except (OSError, ValueError) as error:
+        raise SessionWorkerError(
+            "SESSION_PROCESS_ISOLATION_UNAVAILABLE",
+            "could not enumerate isolated-session descendants",
+        ) from error
+    return frozenset(children)
+
+
+def parse_session_lease(value: Any) -> tuple[SessionLease, CredentialLease]:
+    """Admit one ``ResearchSessionLease`` and put the capability straight into a lease object.
+
+    The capability never becomes a module-level or dataclass-held ``str``. It is validated by
+    ``hosted_worker.parse_capability`` -- the same shape check the producer path applies -- and then
+    handed to ``CredentialLease``, which refuses to be pickled, refuses ``to_dict``, and renders as
+    ``<CredentialLease redacted state=open>`` wherever anything tries to print it.
+    """
+
+    if not isinstance(value, dict):
+        raise SessionWorkerError("SESSION_LEASE_INVALID", "lease must be an object")
+    required = {
+        "schema_version",
+        "session_id",
+        "workspace_id",
+        "run_id",
+        "attempt_id",
+        "generation",
+        "fence",
+        "capability",
+        "capability_expires_at",
+        "callback_base_url",
+        "allowed_callback_paths",
+        "heartbeat_interval_seconds",
+        "claim_poll_interval_seconds",
+        "idle_timeout_seconds",
+        "context",
+    }
+    if set(value) != required:
+        missing = sorted(required - set(value))
+        unexpected = sorted(set(value) - required)
+        detail = []
+        if missing:
+            detail.append(f"omits {', '.join(missing)}")
+        if unexpected:
+            detail.append(f"has unexpected {', '.join(unexpected)}")
+        raise SessionWorkerError("SESSION_LEASE_INVALID", f"lease {'; '.join(detail)}")
+    expires_at = _parse_utc_timestamp(value["capability_expires_at"], "capability_expires_at")
+    raw_capability = value["capability"]
+    if not isinstance(raw_capability, str) or len(raw_capability) > MAX_CAPABILITY_BYTES:
+        raise SessionWorkerError("SESSION_LEASE_INVALID", "lease capability is not admissible")
+    # `parse_capability` refuses anything that is not the exact `mr_cap_...` shape, so a lease that
+    # somehow carried a URL, a path, or a JWT never reaches an Authorization header.
+    token = parse_capability(raw_capability.encode("ascii", errors="replace"))
+    credential = CredentialLease(token.encode("ascii"), {"kind": "session-attempt-capability"})
+    del token, raw_capability
+
+    paths = value["allowed_callback_paths"]
+    if not isinstance(paths, list) or not paths:
+        credential.close()
+        raise SessionWorkerError("SESSION_LEASE_INVALID", "lease declares no callback paths")
+    for entry in paths:
+        if not isinstance(entry, str) or not entry.startswith("/internal/v3/producer/"):
+            credential.close()
+            raise SessionWorkerError(
+                "SESSION_LEASE_INVALID", "lease callback path is outside the Builder surface"
+            )
+    context = value["context"]
+    if not isinstance(context, dict):
+        credential.close()
+        raise SessionWorkerError("SESSION_LEASE_INVALID", "lease context must be an object")
+    source_ids = context.get("source_ids", [])
+    if not isinstance(source_ids, list) or len(source_ids) > 32:
+        credential.close()
+        raise SessionWorkerError("SESSION_LEASE_INVALID", "lease context source_ids is invalid")
+    try:
+        base_url = value["callback_base_url"]
+        _https_url(str(base_url).rstrip("/"), "callback_base_url")
+        lease = SessionLease(
+            session_id=_uuid_text(value["session_id"], "session_id"),
+            workspace_id=UUID(_uuid_text(value["workspace_id"], "workspace_id")),
+            run_id=UUID(_uuid_text(value["run_id"], "run_id")),
+            attempt_id=UUID(_uuid_text(value["attempt_id"], "attempt_id")),
+            generation=_positive_int(value["generation"], "generation"),
+            fence=_positive_int(value["fence"], "fence"),
+            capability_expires_at=expires_at,
+            callback_base_url=str(base_url).rstrip("/"),
+            allowed_callback_paths=tuple(paths),
+            heartbeat_interval_seconds=float(
+                _positive_int(value["heartbeat_interval_seconds"], "heartbeat_interval_seconds")
+            ),
+            claim_poll_interval_seconds=float(
+                _positive_int(value["claim_poll_interval_seconds"], "claim_poll_interval_seconds")
+            ),
+            idle_timeout_seconds=float(
+                _positive_int(value["idle_timeout_seconds"], "idle_timeout_seconds")
+            ),
+            context=SessionContext(
+                dataset_id=_uuid_text(context["dataset_id"], "context.dataset_id"),
+                question_id=_uuid_text(context["question_id"], "context.question_id"),
+                table_id=(
+                    _uuid_text(context["table_id"], "context.table_id")
+                    if context.get("table_id") is not None
+                    else None
+                ),
+                source_ids=frozenset(
+                    _uuid_text(item, "context.source_ids entry") for item in source_ids
+                ),
+            ),
+        )
+    except (KeyError, SessionWorkerError, HostedWorkerError, ValueError):
+        credential.close()
+        raise
+    return lease, credential
+
+
+# ==========================================================================================
+# Probe source access
+# ==========================================================================================
+
+
+@dataclass(frozen=True)
+class ProbeSource:
+    """The bytes a probe looks at, and where they lawfully came from."""
+
+    source_id: str
+    content: bytes
+    media_type: str
+    data_format: str
+    filename: str
+    truncated: bool
+    origin: str
+
+
+class ProbeSourceReader(Protocol):
+    """Where a probe's bytes come from. Injected, because which door is open is a deployment fact.
+
+    A session worker holds a *producer capability on a session run*, which is deliberately less
+    authority than a build attempt has, and that closes both of the older acquisition paths:
+
+    * ``producer/attempts/{id}/public-crawls`` (ADR 0015, worker side) requires
+      ``table_recipe_id``, ``recipe_version``, ``recipe_digest``, ``activation_epoch`` and
+      ``execution_scope_digest`` on the command, plus a frozen ``source_authority_digest`` from the
+      job's ``source_bindings``. A session run has none of the recipe-bound six -- Studio's own
+      design note says so, because probing is what a recipe gets written *from* -- so the command
+      cannot be constructed, let alone accepted.
+    * ``/v3/workspaces/{id}/public-acquisitions`` (ADR 0015, requester side) is
+      ``userBearer``-authenticated. The worker holds no user bearer and must not be given one.
+
+    Studio built a third door for exactly this authority (Studio #99), and
+    :class:`StudioSessionAcquisitionReader` is the harness half of it. It is now the production
+    default. :class:`UnavailableProbeSourceReader` stays as the honest reader for a deployment
+    whose Studio predates that door: a probe that cannot read its source is a failed probe, not a
+    failed session, and the session stays live either way.
+    """
+
+    def read(self, *, source_id: str, max_bytes: int) -> ProbeSource: ...
+
+
+@dataclass(frozen=True)
+class UnavailableProbeSourceReader:
+    """Refuses every read, with the reason, and never guesses.
+
+    No longer the production default -- :class:`StudioSessionAcquisitionReader` is -- and kept
+    rather than deleted for the two cases where refusing is the correct answer: a Studio that
+    predates the session-acquisition door, and a test that wants the refusal path without a fake
+    for the whole acquisition protocol.
+    """
+
+    reason: str = (
+        "no session-scoped source channel is wired: the producer public-crawl command requires "
+        "the recipe-bound coordinates a session run does not have, and the workspace "
+        "public-acquisition endpoint requires a user bearer this worker must not hold"
+    )
+
+    def read(self, *, source_id: str, max_bytes: int) -> ProbeSource:
+        raise SessionWorkerError("PROBE_SOURCE_CHANNEL_UNAVAILABLE", self.reason)
+
+
+class StudioSessionAcquisitionReader:
+    """The production reader, against Studio's third acquisition door (Studio #99).
+
+    **Why this endpoint and not one of the two that already existed.** A session worker holds a
+    producer capability on a *session* run. `producer/attempts/{id}/public-crawls` validates its
+    command against a frozen recipe activation -- ``table_recipe_id``, ``recipe_version``,
+    ``recipe_digest``, ``activation_epoch``, ``execution_scope_digest`` and a
+    ``source_authority_digest`` from the run's source bindings -- and a session run carries none of
+    the six, because probing is what a recipe gets written *from*. `/v3/workspaces/{id}/public-
+    acquisitions` is ``userBearer``-authenticated and this worker must never hold a user bearer.
+    `session-acquisitions` is the door built for exactly this authority, with two scopes of its own.
+
+    **The worker names a source and nothing else, and that is load-bearing rather than tidy.** The
+    command admits no additional properties, so there is no field through which a URL, an adapter,
+    a reader pin, a limit or an egress attestation could arrive. Studio resolves the locator from
+    the source's one active ``public.https`` connector configuration -- a registration a *person*
+    made -- applies its own reviewed egress policy, and clamps the registered limits to the session
+    ceilings. A worker therefore cannot point the Clean room anywhere, and this class could not
+    make it do so if it tried, because it has nothing to send.
+
+    **What is verified before anything is parsed.** The bundle is the same generation-pinned
+    quarantine object the Builder collects, and the same obligation comes with it: the storage
+    observation is not the evidence. `validate_result_download` re-derives the transfer authority
+    and the pinned length and integrity, `verify_result_bytes` checks the bytes against them, and
+    `parse_crawler_result` then re-derives the nested ``normalized_content_digest``,
+    ``normalized_size_bytes`` and ``result_digest`` from the document itself. Only after all three
+    does a byte reach the sandbox.
+
+    **The wait is bounded and the loop is idempotent.** One create per source per attempt, under an
+    Idempotency-Key derived from the source id, so a retried probe replays the first acquisition
+    rather than spending a second admission slot -- the session's slots are charged to the person
+    who opened it. Polling stops at `acquisition_timeout_seconds`; a probe is interactive and a
+    crawl that has not settled by then is a timeout the client can be told about, not a thread the
+    session should keep parked.
+    """
+
+    def __init__(
+        self,
+        *,
+        authority: Any,
+        models: Any,
+        lease: SessionLease,
+        transfer: Any,
+        results_bucket: str | None = None,
+        timeout_seconds: float = DEFAULT_ACQUISITION_TIMEOUT_SECONDS,
+        poll_seconds: float = ACQUISITION_POLL_SECONDS,
+        sleep: Callable[[float], None] = time.sleep,
+        monotonic: Callable[[], float] = time.monotonic,
+        now: Callable[[], datetime] = lambda: datetime.now(UTC),
+    ) -> None:
+        self._authority = authority
+        self._models = models
+        self._lease = lease
+        self._transfer = transfer
+        self._results_bucket = results_bucket
+        self._timeout = timeout_seconds
+        self._poll = poll_seconds
+        self._sleep = sleep
+        self._monotonic = monotonic
+        self._now = now
+        # One entry per source, bumped only when that source's acquisition expired. It is what
+        # makes the idempotency key stable for the ordinary case and re-openable for the one case
+        # where replaying the old key would replay a corpse. See :meth:`read`.
+        self._epochs: dict[str, int] = {}
+
+    # -- the read ----------------------------------------------------------------------------
+
+    def read(self, *, source_id: str, max_bytes: int) -> ProbeSource:
+        try:
+            session = self._settled(self._create(source_id), source_id)
+        except SessionWorkerError as error:
+            if error.code != ACQUISITION_EXPIRED_CODE:
+                raise
+            # An acquisition expires no later than the worker's attempt lease, and a warm session
+            # outlives that comfortably -- the idle timeout alone is ten minutes. Without this, the
+            # first source a long session reads becomes permanently unreadable the moment its
+            # acquisition lapses, because the source-keyed idempotency key would keep replaying the
+            # lapsed one. Studio releases the admission slot as it expires the acquisition, so
+            # opening a fresh one under the next epoch is not a second spend. Exactly one retry:
+            # a second expiry inside one probe is a clock problem, not a race.
+            self._epochs[source_id] = self._epochs.get(source_id, 0) + 1
+            session = self._settled(self._create(source_id), source_id)
+        download = session.get("result_download")
+        if not isinstance(download, Mapping):
+            raise SessionWorkerError(
+                "PROBE_SOURCE_RESULT_INVALID",
+                "a ready session acquisition carried no result download",
+            )
+        raw = self._collect(download, session)
+        return self._probe_source(raw, session, source_id, max_bytes)
+
+    # -- Studio ------------------------------------------------------------------------------
+
+    def _create(self, source_id: str) -> dict[str, Any]:
+        command = self._models.CreateSessionScopedHostedAcquisitionCommand.from_dict(
+            {
+                "schema_version": START_SCHEMA_VERSION,
+                "workspace_id": str(self._lease.workspace_id),
+                "run_id": str(self._lease.run_id),
+                "attempt_id": str(self._lease.attempt_id),
+                "fence": self._lease.fence,
+                "session_id": self._lease.session_id,
+                "source_id": source_id,
+            }
+        )
+        response = self._authority.create_session_acquisition.sync_detailed(
+            attempt_id=self._lease.attempt_id,
+            body=command,
+            # KEYED ON THE SOURCE, deliberately, and not on a counter the way the claim poll
+            # is. Two probes against one source inside one session must share the acquisition
+            # they would otherwise both pay an admission slot for; a counter would turn a
+            # follow-up question into a second crawl of the same bytes.
+            idempotency_key=_idempotency(
+                "session",
+                self._lease.attempt_id,
+                "acquire",
+                f"{source_id}:{self._epochs.get(source_id, 0)}",
+            ),
+        )
+        try:
+            return _response("createSessionAcquisition", response, 201).to_dict()
+        except HostedWorkerError as error:
+            if (
+                error.code in PROBE_THROTTLE_WIRE_CODES
+                and int(response.status_code) == HTTPStatus.TOO_MANY_REQUESTS
+            ):
+                retry_after_seconds = _retry_after_seconds(getattr(response, "headers", {}))
+                raise SessionWorkerError(
+                    error.code,
+                    error.detail,
+                    retry_after_seconds=retry_after_seconds,
+                ) from error
+            raise
+
+    def _settled(self, session: Mapping[str, Any], source_id: str) -> dict[str, Any]:
+        deadline = self._monotonic() + self._timeout
+        try:
+            crawler_session_id = UUID(str(session.get("crawler_session_id")))
+        except ValueError as error:
+            raise SessionWorkerError(
+                "PROBE_SOURCE_ACQUISITION_MISBOUND",
+                "session acquisition has no canonical crawler session id",
+            ) from error
+        current = dict(session)
+        while True:
+            self._check(current, source_id)
+            status = str(current.get("status", ""))
+            if status == "result_ready":
+                return current
+            if status == "failed":
+                raise SessionWorkerError(
+                    _acquisition_failure_code(current.get("failure_code")),
+                    "Studio session acquisition failed",
+                )
+            if self._monotonic() >= deadline:
+                raise SessionWorkerError(
+                    "PROBE_SOURCE_ACQUISITION_TIMEOUT",
+                    f"session acquisition did not settle within {self._timeout:g}s",
+                )
+            self._sleep(self._poll)
+            current = _response(
+                "getSessionAcquisition",
+                self._authority.get_session_acquisition.sync_detailed(
+                    attempt_id=self._lease.attempt_id,
+                    crawler_session_id=crawler_session_id,
+                ),
+                200,
+            ).to_dict()
+
+    def _check(self, session: Mapping[str, Any], source_id: str) -> None:
+        """Refuse an acquisition that is not this attempt's, for this session, for this source.
+
+        Studio binds every one of these server-side, so this can only ever agree -- until the day
+        it does not. Re-deriving them is what makes a mixed-up answer a refusal instead of bytes
+        attributed to the wrong source, and it costs seven comparisons on a path that has just
+        spent a network round trip.
+        """
+
+        if (
+            str(session.get("workspace_id")) != str(self._lease.workspace_id)
+            or str(session.get("run_id")) != str(self._lease.run_id)
+            or str(session.get("attempt_id")) != str(self._lease.attempt_id)
+            or str(session.get("research_session_id")) != str(self._lease.session_id)
+            or session.get("source_id") != source_id
+            or session.get("producer_fence") != self._lease.fence
+            or session.get("adapter_id") != "public.https"
+        ):
+            raise SessionWorkerError(
+                "PROBE_SOURCE_ACQUISITION_MISBOUND",
+                "session acquisition is not bound to this attempt, session and source",
+            )
+
+    # -- the bundle --------------------------------------------------------------------------
+
+    def _collect(self, download: Mapping[str, Any], session: Mapping[str, Any]) -> bytes:
+        declared = download.get("bundle_size_bytes")
+        if type(declared) is not int or declared > MAX_PROBE_ACQUISITION_BUNDLE_BYTES:
+            raise SessionWorkerError(
+                "PROBE_SOURCE_TOO_LARGE",
+                "the acquired bundle is larger than a probe may hold",
+            )
+        try:
+            validated = validate_result_download(
+                download,
+                base_url=self._lease.callback_base_url,
+                crawler_session_id=str(session["crawler_session_id"]),
+                request_digest=str(session["request_digest"]),
+                source_id=str(session["source_id"]),
+                source_authority_digest=str(session["source_authority_digest"]),
+                now=self._now(),
+                expected_gcs_bucket=self._results_bucket,
+            )
+        except ResultDownloadError as error:
+            raise SessionWorkerError("PROBE_SOURCE_DOWNLOAD_INVALID", str(error)) from error
+        content = bytearray()
+        with self._transfer.stream("GET", validated.url, headers={}) as response:
+            if response.status_code != 200:
+                raise SessionWorkerError(
+                    "PROBE_SOURCE_DOWNLOAD_FAILED",
+                    f"quarantine download returned HTTP {response.status_code}",
+                )
+            for chunk in response.iter_bytes():
+                content.extend(chunk)
+                if len(content) > validated.size:
+                    raise SessionWorkerError(
+                        "PROBE_SOURCE_DOWNLOAD_FAILED",
+                        "quarantine bytes exceed the generation-pinned size",
+                    )
+        raw = bytes(content)
+        try:
+            verify_result_bytes(validated, raw)
+        except ResultDownloadError as error:
+            raise SessionWorkerError("PROBE_SOURCE_DOWNLOAD_FAILED", str(error)) from error
+        return raw
+
+    def _probe_source(
+        self, raw: bytes, session: Mapping[str, Any], source_id: str, max_bytes: int
+    ) -> ProbeSource:
+        document = _strict_json(raw, "session acquisition result")
+        if not isinstance(document, dict) or canonical_json_bytes(document) != raw:
+            raise SessionWorkerError(
+                "PROBE_SOURCE_RESULT_INVALID",
+                "the acquired result is not exact canonical JSON",
+            )
+        try:
+            result = parse_crawler_result(document)
+        except HostedCrawlerProtocolError as error:
+            raise SessionWorkerError("PROBE_SOURCE_RESULT_INVALID", error.detail) from error
+        receipt = result.acquisition_receipt
+        if (
+            result.source_id != source_id
+            or result.request_digest != session.get("request_digest")
+            or result.adapter_id != "public.https"
+            or receipt.get("source_id") != source_id
+            or receipt.get("normalized_content_sha256") != sha256_bytes(result.normalized_content)
+            or receipt.get("normalized_size_bytes") != len(result.normalized_content)
+            or receipt.get("egress_policy_attestation") != session.get("egress_policy_attestation")
+        ):
+            raise SessionWorkerError(
+                "PROBE_SOURCE_RESULT_INVALID",
+                "the acquired result is not bound to the acquisition that produced it",
+            )
+        if len(result.normalized_content) > max_bytes:
+            raise SessionWorkerError(
+                "PROBE_SOURCE_TOO_LARGE",
+                "the acquired source is larger than a probe may hold",
+            )
+        media_type = receipt.get("normalized_media_type")
+        data_format = receipt.get("normalized_data_format")
+        filename = receipt.get("normalized_filename")
+        if (
+            not isinstance(media_type, str)
+            or not isinstance(data_format, str)
+            or not isinstance(filename, str)
+        ):
+            raise SessionWorkerError(
+                "PROBE_SOURCE_RESULT_INVALID",
+                "the acquisition receipt does not name its normalized shape",
+            )
+        return ProbeSource(
+            source_id=source_id,
+            content=result.normalized_content,
+            media_type=media_type,
+            data_format=data_format,
+            filename=filename,
+            # The bytes are whole or they are refused. Studio clamps the source to the session
+            # ceiling before it crawls, and a truncated table would make every count a probe
+            # reports quietly wrong, so there is no partial answer to flag here.
+            truncated=False,
+            origin="studio.session-acquisition",
+        )
+
+
+def _acquisition_failure_code(value: Any) -> str:
+    """Render Studio's ``failure_code`` as a code this worker will settle a probe under.
+
+    Studio's is free-form on the wire; anything that is not a code-shaped token becomes one stable
+    value rather than reaching the probe record, and the timeline, as somebody's prose.
+    """
+
+    if isinstance(value, str) and re.fullmatch(r"[A-Z][A-Z0-9_]{2,127}", value):
+        return value
+    return "PROBE_SOURCE_ACQUISITION_FAILED"
+
+
+def install_hosted_catalogue() -> Mapping[str, Any] | None:
+    """Put this deployment's pinned sealed catalogue on the worker, when one is pinned.
+
+    The same hook the Builder calls, at start rather than at first query, so a worker that needs
+    the catalogue discovers it cannot have one while it can still fail cleanly. ``None`` when no
+    generation is pinned, which is an ordinary deployment and not a fault: probes then run against
+    whatever the source reader provides.
+
+    Imported inside the function rather than at module scope. The import reaches the channel
+    client and its digest verification, and a session that never touches the catalogue should not
+    pay for loading them.
+    """
+
+    from mostlyright.data_harness.sources.catalog.hosted_catalog import (
+        ensure_hosted_catalog,
+    )
+
+    receipt = ensure_hosted_catalog()
+    return None if receipt is None else dict(receipt)
+
+
+# ==========================================================================================
+# Probe execution
+# ==========================================================================================
+
+
+class ProbeExecutor:
+    """Run one probe inside the sandbox and answer with a vocabulary-valid result body.
+
+    Every probe is a *no-network* sandbox operation (``parse``), which is the only confinement the
+    warm pool serves and therefore the only one that can meet the follow-up-probe budget. Bytes
+    reach the executor already acquired, through the injected :class:`ProbeSourceReader`; nothing
+    here retrieves anything, so a probe cannot cause an outbound request at all.
+
+    **The read is before the dispatch because all four kinds need it, not by accident.** When the
+    read refuses -- against a Studio with no session-acquisition door, or for a source with no
+    registration -- every kind refuses with it, and the obvious question is whether some kind could
+    have been answered from metadata instead and let through. The answer is no, for each of them:
+
+    * ``sample_rows`` and ``profile_columns`` answer with cell values and per-column statistics
+      computed over them.
+    * ``evaluate_expression`` -- the one that looks like it might, since ``count`` with no
+      predicate is just a number -- filters *rows* and aggregates *values*. Even the degenerate
+      case would have to answer from ``declared_row_count``, which is what a publisher SAYS, and
+      answering an observation with a claim is the substitution this whole lane exists to avoid.
+    * ``source_inspect`` is the closest call. The sealed catalogue does carry ``declared_columns``,
+      but they are provider-declared names with no types; the answer this kind gives is a
+      ``schema_digest`` from the parse plus an ``inferred_type`` per column, both derived from the
+      scanned cells, and neither is reachable without them.
+
+    So a read refusal is per-read and not per-kind, and there is no subset to exempt. What a caller
+    gets instead is a *settled* probe carrying the refusal's own code -- reported to Studio so the
+    probe record terminates, and narrated on the run stream as an ``outcome="refused"`` completion
+    -- rather than a probe that starts and never ends.
+    """
+
+    def __init__(
+        self,
+        *,
+        sandbox: Any,
+        reader: ProbeSourceReader,
+        context: SessionContext,
+        parse_limits: ParseLimits | None = None,
+        max_source_bytes: int = 16 * 1024 * 1024,
+    ) -> None:
+        self._sandbox = sandbox
+        self._reader = reader
+        self._context = context
+        self._limits = parse_limits or ParseLimits()
+        self._max_source_bytes = max_source_bytes
+
+    def execute(self, *, probe_id: str, probe_kind: str, request: Any) -> dict[str, Any]:
+        """Answer one probe.
+
+        Raises :class:`SessionWorkerError`, or
+        :class:`~mostlyright.data_harness.session_probes.ProbeVocabularyError`, or whatever the
+        Clean room raises -- every one of which carries a ``code`` that
+        :func:`_probe_failure_code` settles the probe under.
+        """
+
+        normalized = session_probes.validate_probe_request(probe_kind, request)
+        source_id = normalized["source_id"]
+        # The session's own context is the probe authority. A probe naming a source the session was
+        # not opened against is refused here, before any read: the capability says which session
+        # this is, and the session says which sources it may look at. Studio does not re-check this
+        # -- the probe body is opaque to it -- so if this check is not here, it is nowhere.
+        if self._context.source_ids and source_id not in self._context.source_ids:
+            raise SessionWorkerError(
+                "PROBE_SOURCE_OUT_OF_SCOPE",
+                "probe names a source this session was not opened against",
+            )
+        source = self._reader.read(source_id=source_id, max_bytes=self._max_source_bytes)
+        if source.source_id != source_id:
+            raise SessionWorkerError(
+                "PROBE_SOURCE_MISMATCH", "source reader answered for a different source"
+            )
+        result = self._sandbox.parse(
+            request_id=_sandbox_request_id(probe_id),
+            content=source.content,
+            data_format=source.data_format,
+            media_type=source.media_type,
+            filename=source.filename,
+            limits=self._limits,
+        )
+        parsed = getattr(result, "parsed", None)
+        if parsed is None:
+            raise SessionWorkerError("PROBE_PARSE_EMPTY", "the Clean room returned no table")
+        envelope = {
+            "schema_version": session_probes.PROBE_SCHEMA_VERSION,
+            "probe_kind": probe_kind,
+            "source_id": source_id,
+            "content_sha256": hashlib.sha256(source.content).hexdigest(),
+            "content_bytes": len(source.content),
+            "data_format": parsed.data_format,
+            "sandbox_policy_digest": result.policy_digest,
+            "truncated": bool(source.truncated),
+        }
+        body = self._answer(probe_kind, normalized, parsed, envelope)
+        return session_probes.validate_probe_result(probe_kind, body)
+
+    # -- per-kind answers -------------------------------------------------------------------
+
+    def _answer(
+        self,
+        probe_kind: str,
+        request: Mapping[str, Any],
+        parsed: Any,
+        envelope: dict[str, Any],
+    ) -> dict[str, Any]:
+        columns: tuple[str, ...] = tuple(parsed.columns)
+        rows: tuple[tuple[Any, ...], ...] = tuple(parsed.rows)
+        if probe_kind == "sample_rows":
+            return self._sample_rows(request, columns, rows, envelope)
+        scanned = rows[: request["scan_rows"]]
+        envelope["rows_scanned"] = len(scanned)
+        if probe_kind == "source_inspect":
+            return self._source_inspect(columns, scanned, parsed, envelope)
+        if probe_kind == "profile_columns":
+            return self._profile_columns(request, columns, scanned, envelope)
+        return self._evaluate_expression(request, columns, scanned, envelope)
+
+    def _source_inspect(
+        self,
+        columns: Sequence[str],
+        scanned: Sequence[Sequence[Any]],
+        parsed: Any,
+        envelope: dict[str, Any],
+    ) -> dict[str, Any]:
+        # Deliberately no cell values. `source_inspect` answers "what shape is this", and a client
+        # that wants values asks `sample_rows` -- which is a separate probe, separately visible on
+        # the session's event stream, so "who looked at the data" stays answerable.
+        return {
+            **envelope,
+            "schema_digest": parsed.schema_digest,
+            "columns": [
+                {
+                    "name": name,
+                    "inferred_type": session_probes.inferred_type([row[index] for row in scanned]),
+                }
+                for index, name in enumerate(columns[: session_probes.MAX_PROFILE_COLUMNS])
+            ],
+        }
+
+    def _sample_rows(
+        self,
+        request: Mapping[str, Any],
+        columns: Sequence[str],
+        rows: Sequence[Sequence[Any]],
+        envelope: dict[str, Any],
+    ) -> dict[str, Any]:
+        selected = self._selected_columns(request, columns)
+        indices = [columns.index(name) for name in selected]
+        window = rows[request["offset"] : request["offset"] + request["limit"]]
+        envelope["rows_scanned"] = request["offset"] + len(window)
+        body = {
+            **envelope,
+            "columns": list(selected),
+            "rows": [
+                [session_probes.preview_cell(row[index]) for index in indices] for row in window
+            ],
+        }
+        # A preview that would not fit is trimmed from the end rather than refused: an interactive
+        # caller asking for 200 wide rows should get the first N it can have, and `truncated` says
+        # so. Refusing would make the useful answer unreachable without a second round trip.
+        while (
+            len(canonical_json_bytes(body)) > session_probes.PROBE_RESULT_MAX_BYTES and body["rows"]
+        ):
+            body["rows"].pop()
+            body["truncated"] = True
+        return body
+
+    def _profile_columns(
+        self,
+        request: Mapping[str, Any],
+        columns: Sequence[str],
+        scanned: Sequence[Sequence[Any]],
+        envelope: dict[str, Any],
+    ) -> dict[str, Any]:
+        selected = self._selected_columns(request, columns)
+        profiles: list[dict[str, Any]] = []
+        for name in selected:
+            index = columns.index(name)
+            values = [row[index] for row in scanned]
+            present = [value for value in values if value is not None]
+            profile: dict[str, Any] = {
+                "name": name,
+                "inferred_type": session_probes.inferred_type(values),
+                "non_null": len(present),
+                "nulls": len(values) - len(present),
+                # Exact over the scanned rows, and `rows_scanned` is in the envelope beside it, so
+                # the number always arrives with its denominator.
+                "distinct": len({session_probes.preview_cell(value) for value in present}),
+            }
+            ordered = self._orderable(present)
+            if ordered:
+                profile["minimum"] = session_probes.preview_cell(ordered[0])
+                profile["maximum"] = session_probes.preview_cell(ordered[-1])
+            profiles.append(profile)
+        return {**envelope, "columns": profiles}
+
+    def _evaluate_expression(
+        self,
+        request: Mapping[str, Any],
+        columns: Sequence[str],
+        scanned: Sequence[Sequence[Any]],
+        envelope: dict[str, Any],
+    ) -> dict[str, Any]:
+        expression = request["expression"]
+        predicate = expression.get("where")
+        aggregate = expression["aggregate"]
+        column = expression.get("column")
+        index = columns.index(column) if column in columns else None
+        matched = 0
+        values: list[Any] = []
+        for row in scanned:
+            record = dict(zip(columns, row, strict=False))
+            if predicate is not None and not session_probes.evaluate_predicate(predicate, record):
+                continue
+            matched += 1
+            if index is not None and row[index] is not None:
+                values.append(row[index])
+        body: dict[str, Any] = {
+            **envelope,
+            "aggregate": aggregate,
+            "value": self._aggregate(aggregate, matched, values),
+            "rows_matched": matched,
+        }
+        if column is not None:
+            body["column"] = column
+        return body
+
+    @staticmethod
+    def _aggregate(aggregate: str, matched: int, values: Sequence[Any]) -> Any:
+        if aggregate == "count":
+            return matched
+        if not values:
+            # No value is `null`, never zero. A sum over nothing that reported 0 would be
+            # indistinguishable from a sum over zeros, and an exploratory probe is exactly where
+            # that distinction matters.
+            return None
+        numeric = [value for value in values if type(value) in {int, float}]
+        if aggregate in {"min", "max"}:
+            ordered = ProbeExecutor._orderable(values)
+            if not ordered:
+                return None
+            return session_probes.preview_cell(ordered[0 if aggregate == "min" else -1])
+        if len(numeric) != len(values):
+            raise SessionWorkerError(
+                "PROBE_AGGREGATE_NOT_NUMERIC",
+                f"{aggregate} needs a numeric column; the scanned values are not all numbers",
+            )
+        total = sum(numeric)
+        return session_probes.preview_cell(total if aggregate == "sum" else total / len(numeric))
+
+    @staticmethod
+    def _orderable(values: Sequence[Any]) -> list[Any]:
+        """Sort a column's present values, or answer empty when the column is not orderable.
+
+        Python 3 raises on ``1 < "a"``; a mixed column therefore has no extremes and says so,
+        rather than the probe failing on data the caller cannot be expected to know the shape of.
+        """
+
+        try:
+            return sorted(values)
+        except TypeError:
+            return []
+
+    def _selected_columns(
+        self, request: Mapping[str, Any], columns: Sequence[str]
+    ) -> tuple[str, ...]:
+        requested = request.get("columns")
+        if requested is None:
+            return tuple(columns[: session_probes.MAX_PROFILE_COLUMNS])
+        unknown = [name for name in requested if name not in columns]
+        if unknown:
+            raise SessionWorkerError(
+                "PROBE_COLUMN_UNKNOWN", f"source has no column named {unknown[0]!r}"
+            )
+        return tuple(requested)
+
+
+def _probe_failure_code(error: BaseException) -> str:
+    """Render one probe failure as the stable code it should settle under.
+
+    A ``code`` attribute is the convention every coded failure in this package already follows --
+    :class:`SessionWorkerError`, :class:`~mostlyright.data_harness.session_probes.
+    ProbeVocabularyError`, :class:`~mostlyright.data_harness.hosted_worker.HostedWorkerError` and
+    the Clean room's ``AcquisitionSecurityError`` all carry one -- so this reads the convention
+    rather than a list of classes. Reading the class list instead is what lost ``SANDBOX_TIMEOUT``:
+    the sandbox's error is declared in ``acquisition.url_policy`` and was in nobody's tuple.
+
+    The value is checked against the progress value domain before it is believed. A code reaches a
+    timeline as a fact, and a fact that is prose is a record the vocabulary drops whole -- which
+    would put the pair invariant back exactly where this change found it.
+    """
+
+    code = getattr(error, "code", None)
+    if isinstance(code, str) and progress_events.is_progress_fact_value(code):
+        return code
+    return "PROBE_FAILED"
+
+
+def _retry_after_seconds(headers: Any) -> int | None:
+    """Accept Studio's bounded delta-seconds retry window, never prose or a guessed delay."""
+
+    if not isinstance(headers, Mapping):
+        return None
+    value = next(
+        (
+            candidate
+            for key, candidate in headers.items()
+            if isinstance(key, str) and key.lower() == "retry-after"
+        ),
+        None,
+    )
+    if not isinstance(value, str) or not re.fullmatch(r"[1-9][0-9]{0,3}", value):
+        return None
+    seconds = int(value)
+    return seconds if seconds <= MAX_RETRY_AFTER_SECONDS else None
+
+
+def _probe_display_failure(error: BaseException, wire_code: str) -> tuple[str, int]:
+    """Return a person-facing code and its server-stated wait while retaining wire identity."""
+
+    if wire_code not in PROBE_THROTTLE_WIRE_CODES:
+        return wire_code, 0
+    retry_after_seconds = getattr(error, "retry_after_seconds", None)
+    if type(retry_after_seconds) is int and 1 <= retry_after_seconds <= MAX_RETRY_AFTER_SECONDS:
+        return SESSION_ACQUISITION_THROTTLED, retry_after_seconds
+    return SESSION_ACQUISITION_THROTTLED, 0
+
+
+def _probe_progress_outcome(failure_code: str | None) -> str:
+    """Classify a settled probe for the unsealed timeline. Total over ``PROBE_OUTCOMES``.
+
+    Keyed on the code rather than on the exception, so the classification is a property of what the
+    probe settled AS -- the same thing the client reads off the probe resource -- and not of how
+    the worker happened to learn it.
+    """
+
+    if failure_code is None:
+        return "succeeded"
+    if failure_code in PROBE_TIMEOUT_CODES:
+        return "timed_out"
+    if failure_code in PROBE_THROTTLE_CODES:
+        return "throttled"
+    if failure_code in PROBE_REFUSAL_CODES:
+        return "refused"
+    return "failed"
+
+
+# ==========================================================================================
+# The Studio authority
+# ==========================================================================================
+
+
+def _sandbox_request_id(probe_id: str) -> str:
+    """Render a probe id as a sandbox request id.
+
+    ``CrawlerSandbox`` requires a lowercase bounded identifier that *starts with a letter*, and a
+    UUID beginning with a digit does not -- which is roughly half of them. Passing the probe id
+    straight through therefore refused every other probe with ``SANDBOX_IDENTIFIER``, and the
+    prefix is what fixes it rather than a relaxation on the sandbox side. Anything outside the
+    admitted alphabet is replaced rather than dropped, so two different probe ids cannot collapse
+    into one request id.
+    """
+
+    safe = "".join(
+        character if character.islower() or character.isdigit() or character in "._-" else "-"
+        for character in probe_id.lower()
+    )
+    return f"probe-{safe}"[:128]
+
+
+class _SessionAuthority(_ProducerAuthority):
+    """The producer surface plus the two verbs a session adds, and the lease that precedes both.
+
+    Subclassed here rather than widened in ``hosted_worker`` so that the producer and verifier
+    façades keep exactly the operation sets they had: a session worker gaining a verb must not
+    silently widen what a build worker's façade will dispatch.
+    """
+
+    _operations: ClassVar[dict[str, str]] = {
+        **_ProducerAuthority._operations,
+        "lease_session": "sessions.lease_research_session",
+        "claim_probe": "producer.claim_research_probe",
+        "report_probe_result": "producer.report_research_probe_result",
+        "create_session_acquisition": "producer.create_session_acquisition",
+        "get_session_acquisition": "producer.get_session_acquisition",
+    }
+
+
+def _lease_session(
+    *,
+    config: SessionWorkerConfig,
+    invocation: StartInvocation,
+    nonce: bytearray,
+    transport: BootstrapTransport,
+) -> tuple[SessionLease, CredentialLease]:
+    """Present ambient workload identity plus the nonce, and take the one lease on this session.
+
+    Two credentials are in play for exactly one call each and both are zeroed. The identity token
+    proves *which fleet* is calling and is destroyed the moment the exchange returns. The nonce
+    proves *which invocation*, and is zeroed by the caller as soon as this returns -- it is a
+    one-time secret whose whole purpose is to stop a reviewed worker leasing a session it was not
+    sent to, and a copy that outlives its one use is a copy that can be stolen.
+    """
+
+    models, _, _, _ = _load_generated()
+    identity = _metadata_identity(transport, config.lease_audience)
+    try:
+        client = _authenticated_client(config.studio_origin, identity.decode("ascii"))
+    finally:
+        identity[:] = b"\x00" * len(identity)
+    try:
+        authority = _SessionAuthority(client)
+        command = models.ContractSessionLeaseCommand.from_dict(
+            {
+                "schema_version": START_SCHEMA_VERSION,
+                "session_id": invocation.session_id,
+                "lease_nonce": nonce.decode("ascii"),
+            }
+        )
+        parsed = _response(
+            "leaseResearchSession",
+            authority.lease_session.sync_detailed(
+                session_id=UUID(invocation.session_id), body=command
+            ),
+            200,
+        )
+        wire = parsed.to_dict()
+    finally:
+        # The identity-bearing client is discarded whatever happens: everything after the lease
+        # authenticates with the fenced capability, and an idle client holding a workload-identity
+        # bearer for the rest of a session is authority nothing needs.
+        client.get_httpx_client().close()
+    lease, credential = parse_session_lease(wire)
+    if lease.session_id != invocation.session_id or str(lease.workspace_id) != (
+        invocation.workspace_id
+    ):
+        credential.close()
+        raise SessionWorkerError(
+            "SESSION_LEASE_MISMATCH", "the lease names a different session or workspace"
+        )
+    return lease, credential
+
+
+# ==========================================================================================
+# The supervisor
+# ==========================================================================================
+
+
+@dataclass
+class _SessionOutcome:
+    session_id: str
+    attempt_id: str | None = None
+    probes_answered: int = 0
+    probes_failed: int = 0
+    terminal_state: str | None = None
+    failure_code: str | None = None
+    warm_pool_ready: int = 0
+    catalogue: Mapping[str, Any] | None = None
+    events: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "status": "failed" if self.failure_code else "stopped",
+            "role": SESSION_WORKER_ROLE,
+            "session_id": self.session_id,
+            "attempt_id": self.attempt_id,
+            "probes_answered": self.probes_answered,
+            "probes_failed": self.probes_failed,
+            "terminal_state": self.terminal_state,
+            "failure_code": self.failure_code,
+            "warm_pool_ready": self.warm_pool_ready,
+        }
+
+
+class _Heartbeat(threading.Thread):
+    """Liveness on a timer, and nothing else.
+
+    A separate thread rather than a tick inside the claim loop, because the claim loop blocks for
+    the length of a probe and a probe may run for the better part of a minute. A heartbeat that
+    only fires between probes would go quiet during exactly the interval where a client most wants
+    to know the worker is alive.
+
+    Every failure is swallowed. A missed heartbeat costs liveness resolution; the authority on
+    whether this worker still holds its lease is the attempt lease expiry Studio enforces on every
+    fenced call, and the claim loop discovers a lost lease there. Failing the session from this
+    thread would be this thread deciding something it cannot see.
+    """
+
+    def __init__(
+        self,
+        *,
+        send: Callable[[], None],
+        interval_seconds: float,
+        stop: threading.Event,
+        deadline: SessionDeadline | None = None,
+        on_expired: Callable[[], None] | None = None,
+    ) -> None:
+        super().__init__(name="mr-session-heartbeat", daemon=True)
+        self._send = send
+        self._interval = max(1.0, float(interval_seconds))
+        self._stop = stop
+        self._deadline = deadline
+        self._on_expired = on_expired
+        self.sent = 0
+
+    def run(self) -> None:
+        while not self._stop.is_set():
+            wait_seconds = self._interval
+            if self._deadline is not None:
+                wait_seconds = self._deadline.bounded_wait(wait_seconds)
+                if wait_seconds <= 0:
+                    self._expire()
+                    return
+            if self._stop.wait(wait_seconds):
+                return
+            if self._deadline is not None and self._deadline.expired():
+                self._expire()
+                return
+            try:
+                self._send()
+            except Exception:
+                LOGGER.debug("session heartbeat failed", exc_info=True)
+                continue
+            self.sent += 1
+
+    def _expire(self) -> None:
+        self._stop.set()
+        if self._on_expired is not None:
+            self._on_expired()
+
+
+class SessionSupervisor:
+    """Lease, start, claim, answer, heartbeat, and stop on a terminal state.
+
+    In production Job mode, a capability-free parent supplies an opaque dispatch and this
+    supervisor exchanges it only in its isolated child.  The capability remains in that child
+    inside ``CredentialLease`` only for the life of the session; it is not serialised, logged,
+    written to disk or passed to the probe sandbox, and it is zeroed when the supervisor stops.
+    ``invocation``/``nonce`` remain only as a compatibility seam for the retained rollback
+    Service; Job mode never constructs or accepts a lease nonce.
+    """
+
+    def __init__(
+        self,
+        *,
+        config: SessionWorkerConfig,
+        invocation: StartInvocation | None = None,
+        nonce: bytearray | None = None,
+        bootstrap: tuple[SessionLease, CredentialLease] | None = None,
+        dispatch: SessionDispatch | None = None,
+        transport: BootstrapTransport | None = None,
+        sandbox_factory: Callable[[SessionWorkerConfig], Any] | None = None,
+        reader_factory: Callable[[SessionLease], ProbeSourceReader] | None = None,
+        lease_session: Callable[..., tuple[SessionLease, CredentialLease]] = _lease_session,
+        sleep: Callable[[float], None] = time.sleep,
+        wall_clock: Callable[[], datetime] = _wall_clock_now,
+        monotonic_clock: Callable[[], float] = time.monotonic,
+        process_isolation: bool = False,
+        on_isolation_ready: Callable[[], None] | None = None,
+    ) -> None:
+        legacy = invocation is not None or nonce is not None
+        modes = int(legacy) + int(bootstrap is not None) + int(dispatch is not None)
+        if modes != 1 or (legacy and (invocation is None or nonce is None)):
+            raise SessionWorkerError(
+                "SESSION_SUPERVISOR_CONFIGURATION_INVALID",
+                "provide exactly one legacy invocation, dispatch, or dispatch bootstrap",
+            )
+        self._config = config
+        self._invocation = invocation
+        self._nonce = nonce
+        self._bootstrap = bootstrap
+        self._dispatch = dispatch
+        self._transport = transport or UrlLibBootstrapTransport()
+        self._sandbox_factory = sandbox_factory or _default_sandbox
+        # `None` rather than a default lambda, because the production reader cannot be built from
+        # a lease alone: it needs the fenced authority and a transfer client, both of which exist
+        # only once `_serve` has one. A test injecting a factory still overrides everything.
+        self._reader_factory = reader_factory
+        self._lease_session = lease_session
+        self._sleep = sleep
+        self._wall_clock = wall_clock
+        self._monotonic_clock = monotonic_clock
+        self._process_isolation = process_isolation
+        self._on_isolation_ready = on_isolation_ready
+        self._stop = threading.Event()
+        self.outcome = _SessionOutcome(
+            session_id=(
+                bootstrap[0].session_id
+                if bootstrap is not None
+                else invocation.session_id
+                if invocation is not None
+                else ""
+            )
+        )
+
+    def stop(self) -> None:
+        """Ask the claim loop to finish the probe it is on and then stop."""
+
+        self._stop.set()
+
+    @property
+    def is_running(self) -> bool:
+        """Whether this supervisor still owns a live session."""
+
+        return not self._stop.is_set() and self.outcome.terminal_state is None
+
+    def _stop_at_deadline(self, deadline: SessionDeadline) -> bool:
+        """Settle the local process at the credential boundary, without a producer callback."""
+
+        if not deadline.expired():
+            return False
+        if self.outcome.terminal_state is None:
+            self.outcome.terminal_state = "capability_expired"
+        self._stop.set()
+        return True
+
+    # -- the run ----------------------------------------------------------------------------
+
+    def run(self) -> dict[str, Any]:
+        """Own one session end to end. Never raises; the outcome carries the failure code."""
+
+        if self._process_isolation:
+            return self._run_isolated()
+        return self._run_in_process()
+
+    def _run_isolated(self) -> dict[str, Any]:
+        """Run the capability-bearing half in a child and enforce its expiry from this parent.
+
+        The parent receives only a session ID and absolute expiry, never the capability.  It is
+        therefore able to wait, kill and return exit-0 semantics even if a reader or native parser
+        in the child never returns to Python or holds the child GIL.  The child arms its own
+        default-action ``SIGALRM`` before it acknowledges the lease, closing the small scheduling
+        gap before this parent has installed its paired-clock monitor.
+        """
+
+        if self._bootstrap is not None:
+            raise SessionWorkerError(
+                "SESSION_SUPERVISOR_CONFIGURATION_INVALID",
+                "a capability-bearing bootstrap cannot enter process isolation",
+            )
+        if not hasattr(os, "fork") or not hasattr(signal, "setitimer"):
+            raise SessionWorkerError(
+                "SESSION_PROCESS_ISOLATION_UNAVAILABLE",
+                "the session deadline requires POSIX process and interval-timer support",
+            )
+        previous_sigterm: Any | None = None
+        if threading.current_thread() is threading.main_thread():
+            previous_sigterm = signal.getsignal(signal.SIGTERM)
+
+            def request_stop(_signum: int, _frame: Any) -> None:
+                # The monitor owns no capability. Do only the async-safe state change here; the
+                # ordinary monitor path kills/reaps every tracked process group.
+                self._stop.set()
+
+            # Install before the fork. A rejected/timeout legacy bootstrap must be able to signal
+            # its outer monitor even if its inner child has already made a separate process group.
+            signal.signal(signal.SIGTERM, request_stop)
+        prior_subreaper = False
+        subreaper_enabled = False
+        baseline_children = frozenset()
+        if sys.platform == "linux":
+            try:
+                prior_subreaper = _child_subreaper_enabled()
+                _set_child_subreaper(True)
+                subreaper_enabled = True
+                # The monitor is dedicated to one session.  A baseline still makes its teardown
+                # exact if an embedding process happened to own a child before supervision began.
+                baseline_children = _linux_direct_child_pids()
+            except OSError as error:
+                if subreaper_enabled:
+                    with contextlib.suppress(OSError):
+                        _set_child_subreaper(prior_subreaper)
+                if previous_sigterm is not None:
+                    signal.signal(signal.SIGTERM, previous_sigterm)
+                raise SessionWorkerError(
+                    "SESSION_PROCESS_ISOLATION_UNAVAILABLE",
+                    "could not establish isolated-session descendant supervision",
+                ) from error
+        try:
+            child_to_parent_read, child_to_parent_write = os.pipe()
+            parent_to_child_read, parent_to_child_write = os.pipe()
+        except OSError as error:
+            if subreaper_enabled:
+                with contextlib.suppress(OSError):
+                    _set_child_subreaper(prior_subreaper)
+            if previous_sigterm is not None:
+                signal.signal(signal.SIGTERM, previous_sigterm)
+            raise SessionWorkerError(
+                "SESSION_PROCESS_ISOLATION_UNAVAILABLE",
+                "could not allocate isolated-session control pipes",
+            ) from error
+        if self._stop.is_set():
+            for descriptor in (
+                child_to_parent_read,
+                child_to_parent_write,
+                parent_to_child_read,
+                parent_to_child_write,
+            ):
+                with contextlib.suppress(OSError):
+                    os.close(descriptor)
+            if subreaper_enabled:
+                with contextlib.suppress(OSError):
+                    _set_child_subreaper(prior_subreaper)
+            if previous_sigterm is not None:
+                signal.signal(signal.SIGTERM, previous_sigterm)
+            self.outcome.terminal_state = "service_stopped"
+            return self.outcome.to_dict()
+        try:
+            child_pid = os.fork()
+        except OSError as error:
+            for descriptor in (
+                child_to_parent_read,
+                child_to_parent_write,
+                parent_to_child_read,
+                parent_to_child_write,
+            ):
+                os.close(descriptor)
+            if subreaper_enabled:
+                with contextlib.suppress(OSError):
+                    _set_child_subreaper(prior_subreaper)
+            if previous_sigterm is not None:
+                signal.signal(signal.SIGTERM, previous_sigterm)
+            raise SessionWorkerError(
+                "SESSION_PROCESS_ISOLATION_UNAVAILABLE", "could not start an isolated session child"
+            ) from error
+        if child_pid == 0:  # pragma: no cover - exercised through the parent process contract.
+            if previous_sigterm is not None:
+                signal.signal(signal.SIGTERM, previous_sigterm)
+            os.close(child_to_parent_read)
+            os.close(parent_to_child_write)
+            self._process_isolation = False
+            try:
+                # Give this one capability-bearing process its own group before it can create a
+                # sandbox.  The parent kills this group at expiry; separate sandbox groups are
+                # reparented to the Linux subreaper and killed/reaped there.
+                os.setsid()
+                summary = self._run_in_process(
+                    on_lease=lambda lease, deadline: self._announce_isolated_lease(
+                        child_to_parent_write, parent_to_child_read, lease, deadline
+                    )
+                )
+                self._write_isolated_message(
+                    child_to_parent_write, {"kind": "summary", "summary": summary}
+                )
+                os._exit(0)
+            except BaseException as error:
+                # The parent gets a bounded, non-secret diagnostic instead of a traceback that
+                # could retain the capability-bearing stack.  ``_run_in_process`` normally
+                # turns operational failures into a summary; this is only its own control plane.
+                with contextlib.suppress(Exception):
+                    self._write_isolated_message(
+                        child_to_parent_write,
+                        {
+                            "kind": "error",
+                            "code": getattr(error, "code", "SESSION_CHILD_FAILED"),
+                        },
+                    )
+                os._exit(1)
+            finally:
+                with contextlib.suppress(OSError):
+                    os.close(child_to_parent_write)
+                with contextlib.suppress(OSError):
+                    os.close(parent_to_child_read)
+
+        os.close(child_to_parent_write)
+        os.close(parent_to_child_read)
+        # A fork duplicates a legacy nonce but not a capability (the child performs exchange).
+        # Retire the parent's copy before it waits so the service process cannot retain it.
+        if self._nonce is not None:
+            self._nonce[:] = b"\x00" * len(self._nonce)
+        try:
+            if self._stop.is_set():
+                self.outcome.terminal_state = "service_stopped"
+                return self._terminate_isolated_child(child_pid)
+            if self._on_isolation_ready is not None:
+                try:
+                    self._on_isolation_ready()
+                except Exception as error:
+                    self.outcome.failure_code = "SESSION_ISOLATION_READY_FAILED"
+                    LOGGER.warning(
+                        "isolated-session readiness acknowledgement failed: %s",
+                        type(error).__name__,
+                    )
+                    return self._terminate_isolated_child(child_pid)
+            return self._monitor_isolated_child(
+                child_pid, child_to_parent_read, parent_to_child_write
+            )
+        finally:
+            if previous_sigterm is not None:
+                signal.signal(signal.SIGTERM, previous_sigterm)
+            with contextlib.suppress(OSError):
+                os.close(child_to_parent_read)
+            with contextlib.suppress(OSError):
+                os.close(parent_to_child_write)
+            if subreaper_enabled:
+                try:
+                    self._kill_adopted_session_descendants(baseline_children)
+                finally:
+                    _set_child_subreaper(prior_subreaper)
+
+    @staticmethod
+    def _write_isolated_message(descriptor: int, payload: dict[str, Any]) -> None:
+        raw = canonical_json_bytes(payload) + b"\n"
+        if len(raw) > MAX_SESSION_SUPERVISOR_MESSAGE_BYTES:
+            raise SessionWorkerError(
+                "SESSION_CHILD_PROTOCOL_INVALID", "isolated-session message exceeds its byte limit"
+            )
+        view = memoryview(raw)
+        try:
+            while view:
+                written = os.write(descriptor, view)
+                if written <= 0:
+                    raise OSError("short isolated-session pipe write")
+                view = view[written:]
+        finally:
+            view.release()
+
+    @staticmethod
+    def _read_isolated_message(
+        descriptor: int, buffer: bytearray, *, timeout: float | None
+    ) -> dict[str, Any] | None:
+        readable, _unused, _errors = select.select([descriptor], [], [], timeout)
+        if not readable:
+            return None
+        chunk = os.read(descriptor, 64 * 1024)
+        if not chunk:
+            raise EOFError("isolated session child closed its control pipe")
+        buffer.extend(chunk)
+        if len(buffer) > MAX_SESSION_SUPERVISOR_MESSAGE_BYTES:
+            raise SessionWorkerError(
+                "SESSION_CHILD_PROTOCOL_INVALID", "isolated-session message exceeds its byte limit"
+            )
+        newline = buffer.find(b"\n")
+        if newline < 0:
+            return None
+        raw = bytes(buffer[:newline])
+        del buffer[: newline + 1]
+        value = _strict_json(raw, "isolated-session message")
+        if not isinstance(value, dict):
+            raise SessionWorkerError(
+                "SESSION_CHILD_PROTOCOL_INVALID", "isolated-session message is not an object"
+            )
+        return value
+
+    def _announce_isolated_lease(
+        self,
+        write_descriptor: int,
+        read_descriptor: int,
+        lease: SessionLease,
+        deadline: SessionDeadline,
+    ) -> None:
+        remaining = deadline.remaining_seconds()
+        if remaining <= 0:
+            raise SessionWorkerError(
+                "SESSION_CAPABILITY_EXPIRED", "the session capability expired before supervision"
+            )
+        # SIG_DFL is a kernel-enforced deadline: a child blocked in native code cannot delay it.
+        signal.signal(signal.SIGALRM, signal.SIG_DFL)
+        signal.setitimer(signal.ITIMER_REAL, remaining)
+        expiry = lease.capability_expires_at.isoformat(timespec="microseconds").replace(
+            "+00:00", "Z"
+        )
+        self._write_isolated_message(
+            write_descriptor,
+            {"kind": "lease", "session_id": lease.session_id, "capability_expires_at": expiry},
+        )
+        response = bytearray()
+        while True:
+            command = self._read_isolated_message(read_descriptor, response, timeout=None)
+            if command is not None:
+                break
+        if command != {"kind": "start"}:
+            raise SessionWorkerError(
+                "SESSION_CHILD_PROTOCOL_INVALID", "isolated-session parent did not authorize start"
+            )
+
+    def _monitor_isolated_child(
+        self, child_pid: int, read_descriptor: int, write_descriptor: int
+    ) -> dict[str, Any]:
+        buffer = bytearray()
+        deadline: SessionDeadline | None = None
+        while True:
+            if self._stop.is_set():
+                if self.outcome.terminal_state is None:
+                    self.outcome.terminal_state = "service_stopped"
+                return self._terminate_isolated_child(child_pid)
+            timeout = 1.0 if deadline is None else deadline.bounded_wait(1.0)
+            if deadline is not None and timeout <= 0:
+                return self._expire_isolated_child(child_pid)
+            try:
+                message = self._read_isolated_message(read_descriptor, buffer, timeout=timeout)
+            except EOFError:
+                status = self._wait_for_isolated_child(child_pid)
+                if deadline is not None and (
+                    deadline.expired()
+                    or (os.WIFSIGNALED(status) and os.WTERMSIG(status) == signal.SIGALRM)
+                ):
+                    return self._deadline_summary()
+                self.outcome.failure_code = "SESSION_CHILD_EXITED"
+                return self.outcome.to_dict()
+            if message is None:
+                continue
+            kind = message.get("kind")
+            if kind == "lease":
+                if deadline is not None or set(message) != {
+                    "kind",
+                    "session_id",
+                    "capability_expires_at",
+                }:
+                    self.outcome.failure_code = "SESSION_CHILD_PROTOCOL_INVALID"
+                    return self._terminate_isolated_child(child_pid)
+                try:
+                    session_id = _uuid_text(message["session_id"], "isolated session id")
+                    expires_at = _parse_utc_timestamp(
+                        message["capability_expires_at"], "isolated capability_expires_at"
+                    )
+                    deadline = SessionDeadline.from_expiry(
+                        expires_at,
+                        wall_clock=self._wall_clock,
+                        monotonic_clock=self._monotonic_clock,
+                    )
+                except SessionWorkerError as error:
+                    if error.code == "SESSION_CAPABILITY_EXPIRED":
+                        return self._expire_isolated_child(child_pid)
+                    self.outcome.failure_code = error.code
+                    return self._terminate_isolated_child(child_pid)
+                self.outcome.session_id = session_id
+                self._write_isolated_message(write_descriptor, {"kind": "start"})
+                continue
+            if kind == "summary" and set(message) == {"kind", "summary"}:
+                status = self._wait_for_isolated_child(child_pid)
+                summary = message["summary"]
+                if not isinstance(summary, dict):
+                    self.outcome.failure_code = "SESSION_CHILD_PROTOCOL_INVALID"
+                    return self.outcome.to_dict()
+                if deadline is not None and (
+                    deadline.expired()
+                    or (os.WIFSIGNALED(status) and os.WTERMSIG(status) == signal.SIGALRM)
+                ):
+                    return self._deadline_summary()
+                return summary
+            if (
+                kind == "error"
+                and set(message) == {"kind", "code"}
+                and isinstance(message["code"], str)
+            ):
+                self.outcome.failure_code = message["code"]
+            else:
+                self.outcome.failure_code = "SESSION_CHILD_PROTOCOL_INVALID"
+            return self._terminate_isolated_child(child_pid)
+
+    def _expire_isolated_child(self, child_pid: int) -> dict[str, Any]:
+        self._kill_isolated_child_group(child_pid)
+        self._wait_for_isolated_child(child_pid)
+        return self._deadline_summary()
+
+    def _terminate_isolated_child(self, child_pid: int) -> dict[str, Any]:
+        self._kill_isolated_child_group(child_pid)
+        self._wait_for_isolated_child(child_pid)
+        return self.outcome.to_dict()
+
+    @staticmethod
+    def _kill_isolated_child_group(child_pid: int) -> None:
+        """Kill the child process group, with a PID fallback before ``setsid`` can complete."""
+
+        try:
+            os.killpg(child_pid, signal.SIGKILL)
+            return
+        except (PermissionError, ProcessLookupError):
+            # Before the child's first control message it may not yet have made itself a group
+            # leader. Some Darwin process-group races also report EPERM after the group leader has
+            # exited. Killing the exact direct PID still prevents a bootstrap/protocol error from
+            # leaving the capability exchange running.
+            pass
+        with contextlib.suppress(PermissionError, ProcessLookupError):
+            os.kill(child_pid, signal.SIGKILL)
+
+    @staticmethod
+    def _wait_for_isolated_child(child_pid: int) -> int:
+        while True:
+            try:
+                _pid, status = os.waitpid(child_pid, 0)
+                return status
+            except InterruptedError:
+                continue
+            except ChildProcessError:
+                return 0
+
+    @staticmethod
+    def _kill_adopted_session_descendants(baseline_children: frozenset[int]) -> None:
+        """Kill/reap Linux descendants adopted after the capability child dies.
+
+        Sandboxes intentionally create separate process groups so parser helpers cannot affect the
+        coordinator.  A force-killed capability child cannot run ``close_warm_pool``; as a Linux
+        subreaper, this parent adopts those groups and kills their live leader/group before each
+        reap.  The monitor creates no other children, and the pre-fork baseline prevents touching
+        a host process's pre-existing children if this code is embedded in a test or adapter.
+        """
+
+        if sys.platform != "linux":
+            return
+        deadline = time.monotonic() + 5.0
+        own_group = os.getpgrp()
+        while True:
+            children = _linux_direct_child_pids() - baseline_children
+            if not children:
+                return
+            for child_pid in children:
+                try:
+                    group = os.getpgid(child_pid)
+                except ProcessLookupError:
+                    continue
+                try:
+                    if group == own_group:
+                        # The dedicated capability child makes its own group before any sandbox
+                        # launch. A shared group is therefore never safe to signal wholesale.
+                        os.kill(child_pid, signal.SIGKILL)
+                    else:
+                        os.killpg(group, signal.SIGKILL)
+                except ProcessLookupError:
+                    continue
+            for child_pid in children:
+                with contextlib.suppress(ChildProcessError):
+                    os.waitpid(child_pid, os.WNOHANG)
+            if time.monotonic() >= deadline:
+                raise SessionWorkerError(
+                    "SESSION_DESCENDANT_CLEANUP_FAILED",
+                    "isolated-session descendants did not exit after the capability child",
+                )
+            time.sleep(0.005)
+
+    def _deadline_summary(self) -> dict[str, Any]:
+        self.outcome.terminal_state = "capability_expired"
+        self._stop.set()
+        return self.outcome.to_dict()
+
+    def _run_in_process(
+        self, *, on_lease: Callable[[SessionLease, SessionDeadline], None] | None = None
+    ) -> dict[str, Any]:
+        """Run the capability-bearing half, optionally after an isolated-parent handshake."""
+
+        if self._bootstrap is not None:
+            # Transfer ownership exactly once.  A duplicate Job execution must obtain a fresh
+            # bootstrap through Studio; it cannot re-run this supervisor with an old capability.
+            lease, credential = self._bootstrap
+            self._bootstrap = None
+        elif self._dispatch is not None:
+            try:
+                lease, credential = exchange_session_dispatch(
+                    config=self._config, dispatch=self._dispatch, transport=self._transport
+                )
+            except (SessionWorkerError, HostedWorkerError) as error:
+                code = getattr(error, "code", "SESSION_LEASE_FAILED")
+                if code in CONSUMED_SESSION_DISPATCH_CODES:
+                    self.outcome.terminal_state = "dispatch_consumed"
+                else:
+                    self.outcome.failure_code = code
+                return self.outcome.to_dict()
+        else:
+            assert self._invocation is not None
+            assert self._nonce is not None
+            try:
+                lease, credential = self._lease_session(
+                    config=self._config,
+                    invocation=self._invocation,
+                    nonce=self._nonce,
+                    transport=self._transport,
+                )
+            except (SessionWorkerError, HostedWorkerError) as error:
+                self.outcome.failure_code = getattr(error, "code", "SESSION_LEASE_FAILED")
+                return self.outcome.to_dict()
+            finally:
+                # Zeroed the instant the legacy lease exchange is over, success or failure. One
+                # use, one lifetime.  Job mode has no nonce at all.
+                self._nonce[:] = b"\x00" * len(self._nonce)
+        self.outcome.attempt_id = str(lease.attempt_id)
+        try:
+            with credential:
+                deadline = SessionDeadline.from_lease(
+                    lease,
+                    wall_clock=self._wall_clock,
+                    monotonic_clock=self._monotonic_clock,
+                )
+                if on_lease is not None:
+                    on_lease(lease, deadline)
+                try:
+                    self.outcome.catalogue = install_hosted_catalogue()
+                except Exception as error:
+                    LOGGER.warning("hosted catalogue install failed: %s", type(error).__name__)
+                self._serve(lease, credential, deadline)
+        except (SessionWorkerError, HostedWorkerError) as error:
+            if getattr(error, "code", None) == "SESSION_CAPABILITY_EXPIRED":
+                # A dispatch that reaches its absolute capability boundary during bootstrap is a
+                # normal no-op.  There is no candidate to complete or session failure to report;
+                # Studio owns the durable close/reap and the Job must not retry it as an error.
+                self.outcome.terminal_state = "capability_expired"
+                self._stop.set()
+            else:
+                self.outcome.failure_code = getattr(error, "code", "SESSION_WORKER_FAILED")
+        except Exception as error:
+            LOGGER.exception("session worker failed")
+            self.outcome.failure_code = type(error).__name__
+        return self.outcome.to_dict()
+
+    def _serve(
+        self, lease: SessionLease, credential: CredentialLease, deadline: SessionDeadline
+    ) -> None:
+        models, _, _, _ = _load_generated()
+        with credential.borrow() as view:
+            client = _authenticated_client(lease.callback_base_url, bytes(view).decode("ascii"))
+        authority = _SessionAuthority(client)
+        sandbox = self._sandbox_factory(self._config)
+        self.outcome.warm_pool_ready = _start_warm_pool(sandbox, self._config.warm_pool_size)
+        transfer: Any | None = None
+        if self._reader_factory is not None:
+            reader = self._reader_factory(lease)
+        else:
+            # A SEPARATE client from the one carrying the capability. The quarantine download is
+            # signed and must reach storage with no Authorization header on it; sharing the
+            # authenticated client would put the attempt capability on a request to a bucket.
+            transfer = _new_transfer_client()
+            reader = StudioSessionAcquisitionReader(
+                authority=authority,
+                models=models,
+                lease=lease,
+                transfer=transfer,
+                results_bucket=self._config.crawler_results_bucket,
+                timeout_seconds=self._config.acquisition_timeout_seconds,
+                sleep=self._sleep,
+            )
+        executor = ProbeExecutor(
+            sandbox=sandbox,
+            reader=reader,
+            context=lease.context,
+        )
+        progress = _SessionProgress(
+            authority=authority,
+            models=models,
+            lease=lease,
+            deadline=deadline,
+        )
+        heartbeat = _Heartbeat(
+            send=lambda: self._heartbeat(authority, models, lease, deadline),
+            interval_seconds=lease.heartbeat_interval_seconds,
+            stop=self._stop,
+            deadline=deadline,
+            on_expired=lambda: self._stop_at_deadline(deadline),
+        )
+        try:
+            if self._stop_at_deadline(deadline):
+                return
+            # `attempt:start` is what clears `warming`. It is the first fenced callback and it is
+            # sent before the warm pool is used for anything, so the session reports ready as soon
+            # as a worker demonstrably exists rather than after the first probe.
+            _response(
+                "startProducerAttempt",
+                authority.start_attempt.sync_detailed(
+                    attempt_id=lease.attempt_id,
+                    body=_session_callback(models, lease),
+                    idempotency_key=_idempotency("session", lease.attempt_id, "start"),
+                ),
+                200,
+            )
+            if self._stop_at_deadline(deadline):
+                return
+            progress.emit(
+                "attempt_started",
+                {"role": SESSION_WORKER_ROLE, "stage_total": 0},
+            )
+            # Flushed here rather than left pending for the first probe. A session that opens and
+            # then sits quiet is the ordinary case -- a person is reading before they ask anything
+            # -- and its stream should say "the worker is here" immediately rather than at the
+            # moment the first probe lands, which is the one moment nobody needs telling.
+            progress.flush()
+            if self._stop_at_deadline(deadline):
+                return
+            heartbeat.start()
+            self._claim_loop(authority, models, lease, executor, progress, deadline)
+        finally:
+            self._stop.set()
+            progress.emit(
+                "attempt_finished",
+                {"outcome": self.outcome.terminal_state or "stopped"},
+            )
+            progress.close()
+            try:
+                sandbox.close_warm_pool()
+            except Exception:
+                LOGGER.debug("warm pool close failed", exc_info=True)
+            if transfer is not None:
+                with contextlib.suppress(Exception):
+                    transfer.close()
+            client.get_httpx_client().close()
+
+    def _claim_loop(
+        self,
+        authority: Any,
+        models: Any,
+        lease: SessionLease,
+        executor: ProbeExecutor,
+        progress: _SessionProgress,
+        deadline: SessionDeadline,
+    ) -> None:
+        interval = lease.claim_poll_interval_seconds or FALLBACK_CLAIM_POLL_SECONDS
+        failures = 0
+        poll = 0
+        while not self._stop.is_set():
+            if self._stop_at_deadline(deadline):
+                return
+            poll += 1
+            try:
+                answer = _response(
+                    "claimResearchProbe",
+                    authority.claim_probe.sync_detailed(
+                        attempt_id=lease.attempt_id,
+                        body=_claim_command(models, lease),
+                        # Claim is NOT idempotent-keyed on a constant. Every poll must be able to
+                        # return a different probe; a fixed key would replay the first answer for
+                        # the life of the session and the worker would answer one probe forever.
+                        # A monotonic COUNTER, not a clock reading. Two polls inside one clock
+                        # tick would share a key, and a shared claim key means Studio replaying
+                        # the first answer -- the worker would re-answer one probe while the
+                        # queue grew behind it. A counter cannot collide.
+                        idempotency_key=_idempotency(
+                            "session", lease.attempt_id, "claim", str(poll)
+                        ),
+                    ),
+                    200,
+                ).to_dict()
+            except HostedWorkerError as error:
+                if self._stop_at_deadline(deadline):
+                    return
+                # A stale fence is Studio saying this worker is no longer the session's worker.
+                # There is no recovery from that and retrying would be a second worker arguing
+                # with the first.
+                if error.code in {"ATTEMPT_FENCE_STALE", "ATTEMPT_STALE", "AUTHORIZATION_DENIED"}:
+                    self.outcome.failure_code = error.code
+                    return
+                failures += 1
+                if failures >= MAX_CONSECUTIVE_CLAIM_FAILURES:
+                    self.outcome.failure_code = error.code
+                    return
+                wait_seconds = deadline.bounded_wait(interval)
+                if wait_seconds <= 0:
+                    self._stop_at_deadline(deadline)
+                    return
+                self._sleep(wait_seconds)
+                continue
+            if self._stop_at_deadline(deadline):
+                return
+            failures = 0
+            state = str(answer.get("session_state", ""))
+            interval = float(answer.get("claim_poll_interval_seconds") or interval)
+            if state in {"closed", "failed"}:
+                # The whole of the exit protocol. No `:complete`, no `:fail`: the session is
+                # already terminal server-side, so both would be refused, and Studio retires the
+                # leftover attempt row on its next sweep.
+                self.outcome.terminal_state = state
+                return
+            if not answer.get("claimed"):
+                wait_seconds = deadline.bounded_wait(interval)
+                if wait_seconds <= 0:
+                    self._stop_at_deadline(deadline)
+                    return
+                self._sleep(wait_seconds)
+                continue
+            self._answer_probe(
+                authority,
+                models,
+                lease,
+                executor,
+                progress,
+                deadline,
+                answer.get("probe"),
+            )
+
+    def _answer_probe(
+        self,
+        authority: Any,
+        models: Any,
+        lease: SessionLease,
+        executor: ProbeExecutor,
+        progress: _SessionProgress,
+        deadline: SessionDeadline,
+        probe: Any,
+    ) -> None:
+        if self._stop_at_deadline(deadline):
+            return
+        if not isinstance(probe, dict):
+            self.outcome.failure_code = "PROBE_CLAIM_INVALID"
+            self._stop.set()
+            return
+        probe_id = str(probe.get("probe_id", ""))
+        probe_kind = str(probe.get("probe_kind", ""))
+        ordinal = probe.get("ordinal")
+        ordinal = ordinal if type(ordinal) is int and ordinal > 0 else 1
+        request = probe.get("request") or {}
+        source_id = str(request.get("source_id", "")) if isinstance(request, dict) else ""
+        # ONE condition for both halves of the pair. A watcher's whole use for this stream is that
+        # a start it sees will be followed by an end, so the two records must be emittable or not
+        # emittable together -- never a start whose end could not be spelled. `source_id` and
+        # `probe_kind` are the two facts a settled record needs, and Studio's claim contract
+        # requires both, so this is false only for a claim this worker could not answer anyway: a
+        # body with no source, or a kind outside the four -- which `execute` refuses too, and which
+        # a drift test keeps equal to the generated enum.
+        narrated = bool(source_id) and probe_kind in session_probes.PROBE_KINDS
+        failure_code: str | None = "PROBE_FAILED"
+        wire_code = "PROBE_FAILED"
+        display_code = "PROBE_FAILED"
+        retry_after_seconds = 0
+        result: dict[str, Any] | None = None
+        try:
+            if narrated:
+                progress.emit(
+                    "source_probe_started",
+                    {"source_id": source_id, "probe_kind": probe_kind, "ordinal": ordinal},
+                )
+                # Flushed BEFORE the probe runs, not left to ride out with its own completion. A
+                # probe may hold this thread for the whole `probe_timeout_seconds` ceiling, and a
+                # start that arrives at the same instant as its end has told a watcher nothing it
+                # did not already know.
+                progress.flush()
+            result = executor.execute(probe_id=probe_id, probe_kind=probe_kind, request=request)
+            failure_code = None
+            wire_code = progress_events.PROBE_OUTCOME_OK_CODE
+            display_code = progress_events.PROBE_OUTCOME_OK_CODE
+        except Exception as error:
+            # Every exception, coded or not, and the code is KEPT when there is one. The two-clause
+            # form this replaces named three classes and let everything else collapse to
+            # `PROBE_FAILED` -- which silently swallowed the Clean room's own `SANDBOX_TIMEOUT`
+            # (`AcquisitionSecurityError`, named in neither clause), turning the one failure a
+            # client can act on into the one that says nothing.
+            failure_code = _probe_failure_code(error)
+            wire_code = failure_code
+            display_code, retry_after_seconds = _probe_display_failure(error, wire_code)
+            if failure_code == "PROBE_FAILED":
+                LOGGER.warning("probe %s failed: %s", probe_id, type(error).__name__)
+        if self._stop_at_deadline(deadline):
+            return
+        # Studio's `ContractProbeResultCommand.outcome` enum is two values. The four-value reading
+        # below is a REFINEMENT for the unsealed timeline and never a second answer: the probe
+        # record settles as `succeeded` or `failed`, exactly as before.
+        settled = "succeeded" if failure_code is None else "failed"
+        self._report(authority, models, lease, deadline, probe_id, settled, result, failure_code)
+        if failure_code is None:
+            self.outcome.probes_answered += 1
+        else:
+            self.outcome.probes_failed += 1
+        if narrated:
+            # EVERY terminal outcome, not only success. `source_probe_settled` travels as Studio's
+            # `source_probe_completed` event type -- the exact type the research-session design
+            # names for a settled probe -- so a client watching the existing per-run SSE stream
+            # sees every probe end live, with no new event type and no second stream. Emitting
+            # only on success (the shape this replaces) meant a watcher saw a start and never an
+            # end, which with no source channel wired was every probe there is.
+            #
+            # `ordinal` and no denominator: how many probes a session will raise is not knowable
+            # while one of them runs. The `source_acquire_*` pair this replaces demanded an
+            # `index` and a `total`, so the worker sent the ordinal for both and every probe read
+            # "N of N" -- a fraction a progress rail will happily draw and that never means
+            # anything.
+            progress.emit(
+                "source_probe_settled",
+                {
+                    "source_id": source_id,
+                    "probe_kind": probe_kind,
+                    "ordinal": ordinal,
+                    "outcome": _probe_progress_outcome(
+                        None if failure_code is None else display_code
+                    ),
+                    "code": wire_code,
+                    "display_code": display_code,
+                    "retry_after_seconds": retry_after_seconds,
+                    "bytes": len(canonical_json_bytes(result)) if result is not None else 0,
+                },
+            )
+        progress.flush()
+
+    def _report(
+        self,
+        authority: Any,
+        models: Any,
+        lease: SessionLease,
+        deadline: SessionDeadline,
+        probe_id: str,
+        outcome: str,
+        result: Mapping[str, Any] | None,
+        failure_code: str | None,
+    ) -> None:
+        if self._stop_at_deadline(deadline):
+            return
+        wire: dict[str, Any] = {
+            "schema_version": START_SCHEMA_VERSION,
+            "workspace_id": str(lease.workspace_id),
+            "run_id": str(lease.run_id),
+            "attempt_id": str(lease.attempt_id),
+            "fence": lease.fence,
+            "session_id": lease.session_id,
+            "probe_id": probe_id,
+            "outcome": outcome,
+        }
+        if result is not None:
+            wire["result"] = dict(result)
+        if failure_code is not None:
+            wire["failure_code"] = failure_code
+        try:
+            _response(
+                "reportResearchProbeResult",
+                authority.report_probe_result.sync_detailed(
+                    attempt_id=lease.attempt_id,
+                    probe_id=UUID(probe_id),
+                    body=models.ContractProbeResultCommand.from_dict(wire),
+                    # Keyed on the probe, so a retried report is the same report. One answer per
+                    # probe is enforced server-side as well -- a second is
+                    # RESEARCH_PROBE_ALREADY_SETTLED -- and the key means an ordinary network
+                    # retry never becomes that.
+                    idempotency_key=_idempotency("session", lease.attempt_id, "result", probe_id),
+                ),
+                200,
+            )
+        except HostedWorkerError as error:
+            if error.code == "RESEARCH_PROBE_ALREADY_SETTLED":
+                # Already answered, by us, before a retry. Nothing to do and nothing wrong: the
+                # client has an answer, which is the only thing that matters.
+                LOGGER.info("probe %s was already settled", probe_id)
+                return
+            raise
+
+    def _heartbeat(
+        self,
+        authority: Any,
+        models: Any,
+        lease: SessionLease,
+        deadline: SessionDeadline | None = None,
+    ) -> None:
+        if deadline is not None and self._stop_at_deadline(deadline):
+            return
+        _response(
+            "heartbeatProducerAttempt",
+            authority.heartbeat_attempt.sync_detailed(
+                attempt_id=lease.attempt_id,
+                body=_session_callback(models, lease),
+                idempotency_key=_idempotency("session", lease.attempt_id, "heartbeat"),
+            ),
+            200,
+        )
+
+
+def _session_callback(models: Any, lease: SessionLease) -> Any:
+    return models.ContractAttemptCallback(
+        schema_version=START_SCHEMA_VERSION,
+        workspace_id=lease.workspace_id,
+        run_id=lease.run_id,
+        attempt_id=lease.attempt_id,
+        fence=lease.fence,
+    )
+
+
+def _claim_command(models: Any, lease: SessionLease) -> Any:
+    return models.ContractProbeClaimCommand.from_dict(
+        {
+            "schema_version": START_SCHEMA_VERSION,
+            "workspace_id": str(lease.workspace_id),
+            "run_id": str(lease.run_id),
+            "attempt_id": str(lease.attempt_id),
+            "fence": lease.fence,
+            "session_id": lease.session_id,
+        }
+    )
+
+
+class _SessionProgress:
+    """Unsealed progress onto the session run's existing event log. Never fails a session.
+
+    The same promise ``hosted_worker._ProgressEmitter`` makes, kept for the same reason: a client
+    that loses timeline resolution has lost a nicety, and a session that died because a progress
+    append was refused has lost the thing it exists for. Records go out one at a time rather than
+    batched, because a session's whole product claim is that a probe is visible immediately, and a
+    250 ms coalescing window is a quarter of the follow-up budget.
+    """
+
+    def __init__(
+        self,
+        *,
+        authority: Any,
+        models: Any,
+        lease: SessionLease,
+        deadline: SessionDeadline | None = None,
+    ) -> None:
+        self._authority = authority
+        self._models = models
+        self._lease = lease
+        self._deadline = deadline
+        self._sequence = 0
+        self._batch = 0
+        self._pending: list[Any] = []
+        self._armed = True
+
+    @property
+    def armed(self) -> bool:
+        return self._armed
+
+    def emit(self, name: str, facts: Mapping[str, Any]) -> None:
+        if self._deadline is not None and self._deadline.expired():
+            self._armed = False
+            self._pending.clear()
+            return
+        if not self._armed:
+            return
+        if self._sequence >= progress_events.MAX_PROGRESS_EVENTS_PER_ATTEMPT:
+            self._armed = False
+            self._pending.clear()
+            return
+        try:
+            self._sequence += 1
+            payload, digest = progress_events.progress_payload_and_digest(name, facts)
+            identifier = bytearray(
+                hashlib.sha256(
+                    f"{self._lease.attempt_id}:{self._sequence}:{name}:{digest}".encode()
+                ).digest()[:16]
+            )
+            identifier[6] = (identifier[6] & 0x0F) | 0x40
+            identifier[8] = (identifier[8] & 0x3F) | 0x80
+            self._pending.append(
+                self._models.ContractProducerEventCommand(
+                    schema_version=START_SCHEMA_VERSION,
+                    workspace_id=self._lease.workspace_id,
+                    run_id=self._lease.run_id,
+                    attempt_id=self._lease.attempt_id,
+                    fence=self._lease.fence,
+                    client_event_id=UUID(bytes=bytes(identifier)),
+                    event_type=self._models.ContractProducerEventCommandEventType(
+                        progress_events.STUDIO_EVENT_TYPE[name]
+                    ),
+                    payload_digest=digest,
+                    payload=self._models.ContractProducerEventCommandPayload.from_dict(payload),
+                )
+            )
+        except Exception:
+            LOGGER.debug("session progress record dropped", exc_info=True)
+
+    def flush(self) -> None:
+        if self._deadline is not None and self._deadline.expired():
+            self._armed = False
+            self._pending.clear()
+            return
+        if not self._pending:
+            return
+        batch, self._pending = self._pending, []
+        self._batch += 1
+        if not self._armed:
+            return
+        try:
+            _response(
+                "appendProducerEvents",
+                self._authority.append_events.sync_detailed(
+                    attempt_id=self._lease.attempt_id,
+                    body=batch,
+                    idempotency_key=_idempotency(
+                        "session", self._lease.attempt_id, "event-progress", str(self._batch)
+                    ),
+                ),
+                200,
+            )
+        except Exception:
+            LOGGER.debug("session progress append failed", exc_info=True)
+
+    def close(self) -> None:
+        try:
+            self.flush()
+        finally:
+            self._armed = False
+
+
+def _start_warm_pool(sandbox: Any, size: int) -> int:
+    """Ask for a warm pool and believe the answer.
+
+    ``start_warm_pool`` returns the number now ready, which on Linux under a bounded cgroup root is
+    zero by design and is not an error -- the first probe simply spawns cold. The lazy-import gain
+    that came with the pool (#306) applies either way, so a zero costs latency and nothing else.
+    """
+
+    if size <= 0:
+        return 0
+    try:
+        return int(sandbox.start_warm_pool(size=size))
+    except Exception:
+        LOGGER.info("warm sandbox pool unavailable; probes will spawn cold")
+        return 0
+
+
+def _default_sandbox(config: SessionWorkerConfig) -> Any:
+    from mostlyright.data_harness.acquisition.sandbox import (
+        HOSTED_SESSION_CONTAINER_MEMORY_BYTES,
+        CrawlerSandbox,
+    )
+
+    staging_root = Path(tempfile.mkdtemp(prefix="mr-session-probe-")).resolve()
+    return CrawlerSandbox(
+        staging_root=staging_root,
+        timeout_seconds=config.probe_timeout_seconds,
+        external_network_policy_attestation=config.external_network_policy_attestation,
+        hosted_session_container_memory_bytes=HOSTED_SESSION_CONTAINER_MEMORY_BYTES,
+    )
+
+
+# ==========================================================================================
+# The HTTP surface
+# ==========================================================================================
+
+
+class _LegacySessionProcess:
+    """A capability-free Service-side handle for one fresh legacy-session interpreter.
+
+    ``ThreadingHTTPServer`` calls :meth:`SessionWorkerService.start` from a request thread.  It is
+    unsafe to ``fork()`` there and then execute Python, HTTP clients or parsers: another thread
+    may have held one of their runtime locks at the instant of the fork.  This handle uses the
+    platform's subprocess exec path only, then the fresh interpreter creates the monitored
+    capability child from its main thread.  The Service process therefore retains neither the
+    lease capability nor a post-fork Python child.
+    """
+
+    def __init__(self, *, process: Any, session_id: str) -> None:
+        self._process = process
+        self._session_id = session_id
+        self._stopped = False
+
+    @classmethod
+    def start(
+        cls,
+        *,
+        config: SessionWorkerConfig,
+        invocation: StartInvocation,
+        nonce: bytearray,
+    ) -> _LegacySessionProcess:
+        """Pass one validated nonce over a pipe to a fresh interpreter, then zero local copies."""
+
+        try:
+            read_descriptor, write_descriptor = os.pipe()
+        except OSError as error:
+            nonce[:] = b"\x00" * len(nonce)
+            raise SessionWorkerError(
+                "SESSION_LEGACY_PROCESS_START_FAILED",
+                "could not allocate the isolated legacy session pipe",
+            ) from error
+        process: Any | None = None
+        payload = bytearray()
+        try:
+            # No ``preexec_fn``: on POSIX that would run Python after a multithreaded fork.  The
+            # executable receives only a descriptor number; the nonce is written after exec over
+            # an inherited private pipe and never appears in argv or the environment.
+            process = subprocess.Popen(
+                (
+                    sys.executable,
+                    "-m",
+                    "mostlyright.data_harness.hosted_session_worker",
+                    LEGACY_BOOTSTRAP_FD_ARGUMENT,
+                    str(read_descriptor),
+                ),
+                close_fds=True,
+                pass_fds=(read_descriptor,),
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.PIPE,
+                start_new_session=True,
+            )
+            os.close(read_descriptor)
+            read_descriptor = -1
+            payload = bytearray(
+                canonical_json_bytes(
+                    {
+                        "schema_version": START_SCHEMA_VERSION,
+                        "session_id": invocation.session_id,
+                        "workspace_id": invocation.workspace_id,
+                        "lease_nonce": nonce.decode("ascii"),
+                        "lease_url": invocation.lease_url,
+                    }
+                )
+            )
+            if len(payload) > MAX_LEGACY_BOOTSTRAP_BYTES:
+                raise SessionWorkerError(
+                    "SESSION_LEGACY_BOOTSTRAP_INVALID",
+                    "legacy bootstrap exceeds its byte limit",
+                )
+            cls._write_all(write_descriptor, payload)
+            cls._await_ready(process)
+        except (OSError, UnicodeError, SessionWorkerError, subprocess.SubprocessError) as error:
+            if process is not None:
+                cls._terminate_process_group(process)
+            raise SessionWorkerError(
+                "SESSION_LEGACY_PROCESS_START_FAILED",
+                "could not start the isolated legacy session process",
+            ) from error
+        finally:
+            if read_descriptor >= 0:
+                with contextlib.suppress(OSError):
+                    os.close(read_descriptor)
+            with contextlib.suppress(OSError):
+                os.close(write_descriptor)
+            payload[:] = b"\x00" * len(payload)
+            nonce[:] = b"\x00" * len(nonce)
+        assert process is not None
+        return cls(process=process, session_id=invocation.session_id)
+
+    @staticmethod
+    def _write_all(descriptor: int, payload: bytearray) -> None:
+        view = memoryview(payload)
+        try:
+            while view:
+                written = os.write(descriptor, view)
+                if written <= 0:
+                    raise OSError("short legacy bootstrap pipe write")
+                view = view[written:]
+        finally:
+            view.release()
+
+    @staticmethod
+    def _await_ready(process: Any) -> None:
+        """Require the fresh bootstrap monitor to arm its cleanup handler before HTTP accepts."""
+
+        stdout = process.stdout
+        if stdout is None:
+            raise OSError("legacy bootstrap process has no control output")
+        readable, _unused, _errors = select.select(
+            [stdout.fileno()], [], [], LEGACY_BOOTSTRAP_READY_TIMEOUT_SECONDS
+        )
+        if not readable:
+            raise OSError("legacy bootstrap monitor did not become ready in time")
+        raw = stdout.readline(MAX_SESSION_SUPERVISOR_MESSAGE_BYTES + 1)
+        if len(raw) > MAX_SESSION_SUPERVISOR_MESSAGE_BYTES or not raw.endswith(b"\n"):
+            raise OSError("legacy bootstrap monitor readiness is invalid")
+        try:
+            message = _strict_json(raw[:-1], "legacy bootstrap readiness")
+        except HostedWorkerError as error:
+            raise OSError("legacy bootstrap monitor readiness is invalid") from error
+        if message != {"kind": "ready"}:
+            raise OSError("legacy bootstrap monitor did not acknowledge readiness")
+
+    @staticmethod
+    def _terminate_process_group(process: Any) -> None:
+        if process.poll() is not None:
+            return
+        # The fresh bootstrap installs its monitor handler *before* it forks the separate
+        # capability group. SIGTERM therefore lets it kill/reap that group and its adopted
+        # sandboxes during a readiness failure; SIGKILL is only the bounded fallback for a wedged
+        # outer monitor.
+        with contextlib.suppress(PermissionError, ProcessLookupError):
+            os.killpg(process.pid, signal.SIGTERM)
+        try:
+            process.wait(timeout=1.0)
+            return
+        except subprocess.TimeoutExpired:
+            pass
+        with contextlib.suppress(PermissionError, ProcessLookupError):
+            os.killpg(process.pid, signal.SIGKILL)
+        with contextlib.suppress(Exception):
+            process.wait(timeout=5)
+
+    @property
+    def is_running(self) -> bool:
+        return self._process.poll() is None
+
+    def stop(self) -> None:
+        self._stopped = True
+        if self._process.poll() is not None:
+            return
+        # The fresh bootstrap interpreter catches this signal in its capability-free monitor, then
+        # kills the separate capability group and reaps its adopted sandbox groups before exiting.
+        # The group here intentionally contains only that bootstrap interpreter, not its child.
+        with contextlib.suppress(ProcessLookupError):
+            os.killpg(self._process.pid, signal.SIGTERM)
+
+    def run(self) -> dict[str, Any]:
+        raw, _unused_stderr = self._process.communicate()
+        if (
+            self._stopped
+            and not raw
+            and self._process.returncode is not None
+            and self._process.returncode < 0
+        ):
+            return {
+                "status": "stopped",
+                "role": SESSION_WORKER_ROLE,
+                "session_id": self._session_id,
+                "attempt_id": None,
+                "probes_answered": 0,
+                "probes_failed": 0,
+                "terminal_state": "service_stopped",
+                "failure_code": None,
+                "warm_pool_ready": 0,
+            }
+        if (
+            self._process.returncode == 0
+            and len(raw) <= MAX_SESSION_SUPERVISOR_MESSAGE_BYTES
+            and raw.endswith(b"\n")
+            and raw.count(b"\n") == 1
+        ):
+            try:
+                summary = _strict_json(raw[:-1], "isolated legacy session summary")
+            except HostedWorkerError:
+                summary = None
+            if isinstance(summary, dict) and summary.get("session_id") == self._session_id:
+                return summary
+        return {
+            "status": "failed",
+            "role": SESSION_WORKER_ROLE,
+            "session_id": self._session_id,
+            "attempt_id": None,
+            "probes_answered": 0,
+            "probes_failed": 0,
+            "terminal_state": None,
+            "failure_code": "SESSION_LEGACY_PROCESS_FAILED",
+            "warm_pool_ready": 0,
+        }
+
+
+class SessionWorkerService:
+    """One process, at most one live session, and an exit that lets Cloud Run scale to zero.
+
+    ``max_instance_request_concurrency = 1`` means Cloud Run will not send this instance a second
+    request while the start invocation is being handled, but the invocation returns in
+    milliseconds, so a second start *can* arrive while the first session is still running. It is
+    refused with 409 rather than served: one session per instance is the tofu's own comment ("A
+    probe must not queue behind another session's CPU") and serving two here would silently break
+    the latency claim the whole feature is built on. Cloud Run answers a 409 by placing the session
+    on another instance, which is what should happen.
+
+    Sessions are served serially, though, and that matters: a client who closes one session and
+    opens another within the grace window gets this warm instance instead of a second cold start.
+    """
+
+    def __init__(
+        self,
+        config: SessionWorkerConfig,
+        *,
+        supervisor_factory: Callable[..., SessionSupervisor] | None = None,
+    ) -> None:
+        self._config = config
+        self._supervisor_factory = supervisor_factory
+        self._lock = threading.Lock()
+        self._active: Any | None = None
+        self._idle_since: float | None = time.monotonic()
+        self._shutdown = threading.Event()
+        self.completed: list[dict[str, Any]] = []
+
+    # -- the two verbs ----------------------------------------------------------------------
+
+    def start(self, raw: bytes) -> tuple[int, dict[str, Any]]:
+        """Accept one start signal and return in milliseconds. See the module docstring."""
+
+        try:
+            invocation, nonce = parse_start_invocation(
+                raw, studio_origin=self._config.studio_origin
+            )
+        except SessionWorkerError as error:
+            # The reason is returned because Studio's starter treats any non-2xx as a failed
+            # session and an operator reading the log needs to know which check refused. The nonce
+            # is not in the invocation object, so nothing here can echo it.
+            return int(HTTPStatus.BAD_REQUEST), {"code": error.code, "detail": error.detail}
+        with self._lock:
+            if self._active is not None and self._active.is_running:
+                nonce[:] = b"\x00" * len(nonce)
+                return int(HTTPStatus.CONFLICT), {
+                    "code": "SESSION_WORKER_BUSY",
+                    "detail": "this instance already holds a live session",
+                }
+            if self._supervisor_factory is None:
+                try:
+                    supervisor: Any = _LegacySessionProcess.start(
+                        config=self._config, invocation=invocation, nonce=nonce
+                    )
+                except SessionWorkerError as error:
+                    return int(HTTPStatus.SERVICE_UNAVAILABLE), {
+                        "code": error.code,
+                        "detail": error.detail,
+                    }
+            else:
+                supervisor = self._supervisor_factory(
+                    config=self._config, invocation=invocation, nonce=nonce
+                )
+            self._active = supervisor
+            self._idle_since = None
+        threading.Thread(
+            target=self._run_session,
+            args=(supervisor,),
+            name=f"mr-session-{invocation.session_id[:8]}",
+            daemon=False,
+        ).start()
+        return int(HTTPStatus.ACCEPTED), {
+            "accepted": True,
+            "session_id": invocation.session_id,
+        }
+
+    def live(self) -> tuple[int, dict[str, Any]]:
+        """Liveness. Deliberately says nothing about whether a session is warm."""
+
+        return int(HTTPStatus.OK), {"status": "live", "role": SESSION_WORKER_ROLE}
+
+    # -- lifecycle --------------------------------------------------------------------------
+
+    def _run_session(self, supervisor: SessionSupervisor) -> None:
+        try:
+            summary = supervisor.run()
+        finally:
+            with self._lock:
+                self._active = None
+                self._idle_since = time.monotonic()
+        self.completed.append(summary)
+        sys.stdout.write(json.dumps(summary, sort_keys=True, separators=(",", ":")) + "\n")
+        sys.stdout.flush()
+
+    def idle_seconds(self, *, now: float | None = None) -> float | None:
+        with self._lock:
+            if self._idle_since is None:
+                return None
+            return (time.monotonic() if now is None else now) - self._idle_since
+
+    def should_exit(self, *, now: float | None = None) -> bool:
+        """True once the instance has been idle long enough to be worth giving back.
+
+        This is the whole of scale-to-zero on the worker side. Cloud Run would eventually reap an
+        idle instance on its own, but 'eventually' is billed at ``cpu_idle = false`` rates, and the
+        difference between roughly $21 and roughly $55 per user-month is the difference between the
+        product's price working and not.
+        """
+
+        idle = self.idle_seconds(now=now)
+        return idle is not None and idle >= self._config.shutdown_grace_seconds
+
+    def stop(self) -> None:
+        with self._lock:
+            active = self._active
+        if active is not None:
+            active.stop()
+        self._shutdown.set()
+
+
+class _Handler(BaseHTTPRequestHandler):
+    """The smallest surface that satisfies the contract. Everything else is 404."""
+
+    protocol_version = "HTTP/1.1"
+    service: SessionWorkerService
+
+    def version_string(self) -> str:
+        return "mostlyright-session-worker"
+
+    def log_message(self, format: str, *args: Any) -> None:
+        # The default writes the full request line to stderr. A request line is never secret here
+        # (the nonce is in the body), but routing it through the logger keeps one place responsible
+        # for what this service says out loud.
+        LOGGER.info("%s %s", self.command, self.path)
+
+    def do_GET(self) -> None:
+        if self.path in HEALTH_PATHS:
+            self._respond(*self.service.live())
+            return
+        self._respond(int(HTTPStatus.NOT_FOUND), {"code": "NOT_FOUND"})
+
+    def do_POST(self) -> None:
+        if self.path != START_PATH:
+            self._respond(int(HTTPStatus.NOT_FOUND), {"code": "NOT_FOUND"})
+            return
+        try:
+            length = int(self.headers.get("Content-Length", "0"))
+        except ValueError:
+            self._respond(int(HTTPStatus.BAD_REQUEST), {"code": "SESSION_START_INVALID"})
+            return
+        if length < 0 or length > MAX_START_REQUEST_BYTES:
+            self._respond(
+                int(HTTPStatus.REQUEST_ENTITY_TOO_LARGE), {"code": "SESSION_START_TOO_LARGE"}
+            )
+            return
+        raw = self.rfile.read(length)
+        self._respond(*self.service.start(raw))
+
+    def _respond(self, status: int, body: Mapping[str, Any]) -> None:
+        encoded = json.dumps(body, sort_keys=True, separators=(",", ":")).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(encoded)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(encoded)
+
+
+class _Server(ThreadingHTTPServer):
+    daemon_threads = True
+    allow_reuse_address = True
+
+
+def serve(
+    config: SessionWorkerConfig,
+    *,
+    service: SessionWorkerService | None = None,
+    poll_seconds: float = 0.5,
+) -> int:
+    """Run the service until the instance has been idle long enough to give back.
+
+    The exit is the point. A container that stays up holds a Cloud Run instance, and an instance
+    that is held is billed; returning from here lets the platform drop it immediately rather than
+    waiting on its own idle reaper.
+    """
+
+    worker = service or SessionWorkerService(config)
+    handler = type("_BoundHandler", (_Handler,), {"service": worker})
+    shutdown_requested = threading.Event()
+    previous_sigterm: Any | None = None
+    if threading.current_thread() is threading.main_thread():
+        previous_sigterm = signal.getsignal(signal.SIGTERM)
+
+        def request_shutdown(_signum: int, _frame: Any) -> None:
+            # A signal handler must not take the Service lock. The main lifecycle loop calls
+            # ``worker.stop`` and lets its bootstrap monitor kill/reap the isolated child.
+            shutdown_requested.set()
+
+        signal.signal(signal.SIGTERM, request_shutdown)
+    with _Server(("0.0.0.0", config.port), handler) as server:
+        thread = threading.Thread(target=server.serve_forever, name="mr-session-http", daemon=True)
+        thread.start()
+        try:
+            while not shutdown_requested.is_set() and not worker.should_exit():
+                time.sleep(poll_seconds)
+        finally:
+            worker.stop()
+            server.shutdown()
+            if previous_sigterm is not None:
+                signal.signal(signal.SIGTERM, previous_sigterm)
+    return 0
+
+
+def run_session_job(
+    *,
+    config: SessionWorkerConfig,
+    dispatch: SessionDispatch,
+    transport: BootstrapTransport | None = None,
+    sandbox_factory: Callable[[SessionWorkerConfig], Any] | None = None,
+    reader_factory: Callable[[SessionLease], ProbeSourceReader] | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+    wall_clock: Callable[[], datetime] = _wall_clock_now,
+    monotonic_clock: Callable[[], float] = time.monotonic,
+    process_isolation: bool = True,
+) -> dict[str, Any]:
+    """Exchange and synchronously supervise exactly one session in one Cloud Run Job task."""
+
+    # The command-line audience is the task's lease audience.  Do not read a legacy audience
+    # environment variable after the dispatch has been accepted: that would make a task's OIDC
+    # proof differ from the deployment coordinate Studio minted for it.
+    job_config = replace(config, lease_audience=dispatch.audience)
+    if process_isolation:
+        # The opaque dispatch is safe in the parent; the capability exchange is intentionally in
+        # the child, so neither this monitor nor the Cloud Run task's launcher retain a bearer.
+        supervisor = SessionSupervisor(
+            config=job_config,
+            dispatch=dispatch,
+            transport=transport,
+            sandbox_factory=sandbox_factory,
+            reader_factory=reader_factory,
+            sleep=sleep,
+            wall_clock=wall_clock,
+            monotonic_clock=monotonic_clock,
+            process_isolation=True,
+        )
+    else:
+        # Deterministic unit adapters are intentionally in-process; production callers use the
+        # default above. This seam prevents forked copies of in-memory fakes from being mistaken
+        # for an end-to-end Studio result.
+        lease, credential = exchange_session_dispatch(
+            config=job_config, dispatch=dispatch, transport=transport
+        )
+        supervisor = SessionSupervisor(
+            config=job_config,
+            bootstrap=(lease, credential),
+            transport=transport,
+            sandbox_factory=sandbox_factory,
+            reader_factory=reader_factory,
+            sleep=sleep,
+            wall_clock=wall_clock,
+            monotonic_clock=monotonic_clock,
+        )
+    return supervisor.run()
+
+
+def _read_legacy_bootstrap_descriptor(descriptor: int) -> bytearray:
+    """Read exactly one bounded start request from the Service's private inherited pipe."""
+
+    if descriptor < 3:
+        raise SessionWorkerError(
+            "SESSION_LEGACY_BOOTSTRAP_INVALID", "legacy bootstrap descriptor is not inherited"
+        )
+    raw = bytearray()
+    try:
+        while True:
+            chunk = os.read(descriptor, min(4096, MAX_LEGACY_BOOTSTRAP_BYTES + 1 - len(raw)))
+            if not chunk:
+                break
+            raw.extend(chunk)
+            if len(raw) > MAX_LEGACY_BOOTSTRAP_BYTES:
+                raise SessionWorkerError(
+                    "SESSION_LEGACY_BOOTSTRAP_INVALID", "legacy bootstrap exceeds its byte limit"
+                )
+    finally:
+        with contextlib.suppress(OSError):
+            os.close(descriptor)
+    if not raw:
+        raise SessionWorkerError("SESSION_LEGACY_BOOTSTRAP_INVALID", "legacy bootstrap is empty")
+    return raw
+
+
+def _legacy_bootstrap_child_main(arguments: Sequence[str]) -> int:
+    """Start the rollback-session supervisor in a fresh main-thread interpreter.
+
+    This is intentionally an internal descriptor protocol rather than an alternate public Service
+    command.  It performs the old nonce lease exchange only inside a newly exec'd process, whose
+    own :class:`SessionSupervisor` then forks the capability-bearing child from a safe main
+    thread.  Neither parent can be held past capability expiry by a reader or native parser.
+    """
+
+    if (
+        len(arguments) != 2
+        or arguments[0] != LEGACY_BOOTSTRAP_FD_ARGUMENT
+        or not arguments[1].isdecimal()
+    ):
+        sys.stderr.write("SESSION_LEGACY_BOOTSTRAP_INVALID: expected one inherited descriptor\n")
+        return 2
+    try:
+        descriptor = int(arguments[1])
+        raw = _read_legacy_bootstrap_descriptor(descriptor)
+        config = config_from_environment()
+        invocation, nonce = parse_start_invocation(raw, studio_origin=config.studio_origin)
+    except (SessionWorkerError, HostedWorkerError, OSError) as error:
+        code = getattr(error, "code", "SESSION_LEGACY_BOOTSTRAP_INVALID")
+        sys.stderr.write(f"{code}: bootstrap refused\n")
+        return 1
+    finally:
+        if "raw" in locals():
+            raw[:] = b"\x00" * len(raw)
+
+    try:
+        summary = SessionSupervisor(
+            config=config,
+            invocation=invocation,
+            nonce=nonce,
+            process_isolation=True,
+            on_isolation_ready=lambda: SessionSupervisor._write_isolated_message(
+                sys.stdout.fileno(), {"kind": "ready"}
+            ),
+        ).run()
+    finally:
+        nonce[:] = b"\x00" * len(nonce)
+    try:
+        SessionSupervisor._write_isolated_message(sys.stdout.fileno(), summary)
+    except (OSError, SessionWorkerError):
+        return 1
+    return 0 if summary["status"] == "stopped" else 1
+
+
+def session_worker_job_main(argv: Sequence[str] | None = None) -> int:
+    """The Cloud Run Job ``mr-data-session-worker-job`` entrypoint.
+
+    Its sole task-specific inputs are the opaque dispatch id, exact exchange URL and OIDC audience;
+    the task never receives a nonce or a capability in argv or its environment.
+    """
+
+    logging.basicConfig(
+        level=logging.INFO, stream=sys.stderr, format="%(levelname)s %(name)s %(message)s"
+    )
+    arguments = tuple(sys.argv[1:] if argv is None else argv)
+    try:
+        dispatch = parse_session_dispatch(arguments)
+    except SessionWorkerError as error:
+        sys.stderr.write(f"{error.code}: {error.detail}\n")
+        return 2
+    try:
+        config = config_from_environment()
+        summary = run_session_job(config=config, dispatch=dispatch)
+    except SessionWorkerError as error:
+        if error.code in CONSUMED_SESSION_DISPATCH_CODES:
+            LOGGER.info(
+                "session dispatch %s was already consumed; exiting without work", error.code
+            )
+            return 0
+        sys.stderr.write(f"{error.code}: {error.detail}\n")
+        return 1
+    except HostedWorkerError as error:
+        sys.stderr.write(f"{error.code}: {error.detail}\n")
+        return 1
+    # A task that reaches Studio's terminal session state completed its work even when the state
+    # is ``failed``: the dispatch was consumed and a retry must not create a second attempt.
+    if summary["status"] == "stopped":
+        return 0
+    failure = summary.get("failure_code") or "SESSION_WORKER_FAILED"
+    sys.stderr.write(f"{failure}: session job did not reach a terminal session state\n")
+    return 1
+
+
+def session_worker_main(argv: Sequence[str] | None = None) -> int:
+    """The legacy Cloud Run service entrypoint, retained unchanged for rollback."""
+
+    logging.basicConfig(
+        level=logging.INFO, stream=sys.stderr, format="%(levelname)s %(name)s %(message)s"
+    )
+    # This executable is also the fresh interpreter launched by
+    # ``_LegacySessionProcess``.  In that path Python invokes this module with
+    # ``--legacy-bootstrap-fd <fd>`` in ``sys.argv``; treating a default ``None``
+    # as an empty sequence would incorrectly enter ``serve`` a second time and
+    # contend with the parent service for ``PORT``.  Keep an explicitly supplied
+    # empty sequence meaningful for unit callers, but mirror the Job entrypoint
+    # when invoked as a console script.
+    arguments = tuple(sys.argv[1:] if argv is None else argv)
+    if arguments and arguments[0] == LEGACY_BOOTSTRAP_FD_ARGUMENT:
+        return _legacy_bootstrap_child_main(arguments)
+    if arguments:
+        sys.stderr.write("mr-data-session-worker takes no arguments\n")
+        return 2
+    try:
+        config = config_from_environment()
+    except (SessionWorkerError, HostedWorkerError) as error:
+        sys.stderr.write(f"{error.code}: {error.detail}\n")
+        return 1
+    return serve(config)
+
+
+if __name__ == "__main__":  # pragma: no cover - exercised as a console script
+    raise SystemExit(session_worker_main())