mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/thin/research.py

@@ -0,0 +1,1663 @@
+"""``mr-data research-open``, ``research-probe``, ``research-status`` and ``research-close``.
+
+WHAT WAS MISSING. ADR 0021 puts interactive source probing on the backend, and the backend has it:
+Studio opens a research session, starts a warm session worker behind it, queues probes for that
+worker, and appends every probe's progress to the session's own Run. The harness has the worker
+(:mod:`mostlyright.data_harness.hosted_session_worker`) and the probe vocabulary
+(:mod:`mostlyright.data_harness.session_probes`). What nothing had was the client: no command
+opened a session, submitted a probe, or closed one, so the skill told the agent that this profile
+submits no probe -- true while it was true, and no longer.
+
+THE SESSION ROUTES, AND THE ONE STREAM.
+
+1. ``POST /v3/sessions`` opens a session against one Dataset and one question. The answer is fast
+   and the cold start is VISIBLE: a freshly opened session reports ``warming`` until its worker
+   takes the lease, and is never reported ready before one exists. ``research-open`` polls the
+   session and prints each state as it changes, because ``warming`` is a product state rather than
+   a stall, and a person watching a blank terminal for twenty seconds cannot tell the two apart.
+2. ``POST /v3/sessions/{id}/probes`` queues one probe. The body under ``probe_kind`` is opaque to
+   Studio and specified by this repository, so it is checked here, in the vocabulary's own words,
+   before an idempotency key is spent on it.
+3. The probe's progress rides the session run's ordinary event stream --
+   ``GET /v3/runs/{run_id}/events:stream``, the one ``mr-data watch`` already follows -- as a
+   ``source_probe_started`` / ``source_probe_settled`` pair whose facts carry Studio's own
+   ``ordinal``. That counter is how a frame on the stream is joined to the probe this command
+   submitted, and the settled frame is what ends the wait.
+4. ``GET /v3/sessions/{id}/probes/{probe_id}`` is the authoritative answer, read once the stream
+   says the probe settled. The stream is an unsealed progress adjunct and says a probe ENDED; the
+   resource says how, and carries the result.
+5. ``POST /v3/sessions/{id}:close`` ends the session, cancels every probe still queued, and takes
+   the session run terminal so the streams a client holds close cleanly.
+6. ``GET /v3/runs/{run_id}/session`` and ``POST /v3/runs/{run_id}/session:close`` let a caller
+   who only has the Run identifier printed by list, fleet, or status resolve (and, when requested,
+   close) its owning research session. Studio performs that ownership check directly; this client
+   never lists or scans sessions to infer it.
+
+⚠ WHAT A PROBE ANSWER IS, AND IS NOT. It is exploration. A probe result is opaque to Studio, is
+never attestation evidence, produces no observation a Build could cite, and is not re-checked by
+anything. This lane prints it so a person or an agent can decide what to build from; it cannot be
+quoted by a receipt, and ``not_evidence`` says so in every answer that carries one.
+
+⚠ A 429 IS REPORTED, NEVER SLEPT THROUGH. A workspace holds a bounded number of live sessions,
+and an open past the bound is ``AGENT_BUDGET_EXCEEDED`` with a ``Retry-After`` header -- a
+refusal, not a queue. It is surfaced here as a typed refusal naming the window Studio stated, so
+the caller decides what to do with the wait rather than finding this command holding a terminal
+for the length of somebody else's session.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import time
+from collections.abc import Callable, Mapping, Sequence
+from pathlib import Path
+from typing import Any
+from uuid import UUID
+
+from mostlyright.data_harness import session_probes
+from mostlyright.data_harness.canonical import CanonicalJSONError, parse_json
+from mostlyright.data_harness.session_probes import ProbeVocabularyError, validate_probe_request
+from mostlyright.data_harness.thin import THIN_SCHEMA_PREFIX
+from mostlyright.data_harness.thin.runs import StudioApiClient, new_idempotency_key
+from mostlyright.data_harness.thin.session import (
+    StudioSession,
+    dataset_dashboard_url,
+    dataset_research_dashboard_url,
+    open_studio_session,
+    run_dashboard_url,
+)
+from mostlyright.data_harness.thin.stream import (
+    RUN_PROGRESS_FRAME,
+    RunEventStream,
+    progress_facts,
+    render_frame,
+)
+from mostlyright.data_harness.thin.transport import ThinLaneError
+from mostlyright.data_harness.ux.credentials import resolve_cloud_credentials
+from mostlyright.data_harness.ux.plain_file import PlainFileRefusal, open_plain_file, read_bounded
+
+RESEARCH_OPEN_SCHEMA = f"{THIN_SCHEMA_PREFIX}-research-open.v1"
+RESEARCH_PROBE_SCHEMA = f"{THIN_SCHEMA_PREFIX}-research-probe.v1"
+RESEARCH_STATUS_SCHEMA = f"{THIN_SCHEMA_PREFIX}-research-status.v1"
+RESEARCH_CLOSE_SCHEMA = f"{THIN_SCHEMA_PREFIX}-research-close.v1"
+
+#: The routes. Three of the five write: they open a session, queue a probe, and close a session.
+#: None of them can cancel or retry the session's run, release anything, or record a decision --
+#: Studio refuses ``:cancel`` and ``:retry`` on a session run by design, and nothing here reaches
+#: either.
+OPEN_SESSION_PATH = "/v3/sessions"
+GET_SESSION_PATH = "/v3/sessions/{session_id}"
+SUBMIT_PROBE_PATH = "/v3/sessions/{session_id}/probes"
+GET_PROBE_PATH = "/v3/sessions/{session_id}/probes/{probe_id}"
+CLOSE_SESSION_PATH = "/v3/sessions/{session_id}:close"
+GET_SESSION_BY_RUN_PATH = "/v3/runs/{run_id}/session"
+CLOSE_SESSION_BY_RUN_PATH = "/v3/runs/{run_id}/session:close"
+
+#: ``research-session.schema.json#/$defs/session_state``, in the order a live session walks it.
+SESSION_STATES = ("opening", "warming", "ready", "busy", "idle", "closed", "failed")
+
+#: The states in which a worker holds the lease and a probe would be answered. ``idle`` is
+#: ``ready`` that has been quiet for ``idle_after_seconds`` and is counting down to its close; it
+#: is still a session a probe reaches, and submitting one is exactly what resets that countdown.
+LIVE_SESSION_STATES = frozenset({"ready", "busy", "idle"})
+
+#: The two terminal states. A session in either will never answer a probe again.
+TERMINAL_SESSION_STATES = frozenset({"closed", "failed"})
+
+#: ``research-session.schema.json#/$defs/probe_state``. The last four settle the probe; only the
+#: third of them is an answer.
+PROBE_STATES = ("queued", "claimed", "succeeded", "failed", "expired", "cancelled")
+SETTLED_PROBE_STATES = frozenset({"succeeded", "failed", "expired", "cancelled"})
+
+#: Studio's closed probe-kind enum, taken from the vocabulary module rather than restated, so the
+#: command line's ``--kind`` choices cannot drift from what the worker answers.
+PROBE_KINDS = session_probes.PROBE_KINDS
+
+#: The one sentence every answer carrying a probe result says about it, for the reason
+#: ``approvals`` says ``never_decides`` and ``narrative`` says ``not_evidence`` in every one of
+#: theirs: the property has to survive being read by somebody who only sees one payload.
+NOT_EVIDENCE = (
+    "A probe answer is exploration: opaque to Studio, re-checked by nothing, quoted by no receipt, "
+    "and never attestation evidence. It says what a warm worker saw; it does not prove anything "
+    "about a Build."
+)
+
+#: ``research-session.schema.json``: ``label`` is 1..200 characters and a close ``reason`` is
+#: 1..512. Both are free text a person types, and both land in somebody else's session record, so
+#: control characters are refused under the same rule ``approvals`` applies to ``--reason``.
+MAX_LABEL_CHARS = 200
+MAX_CLOSE_REASON_CHARS = 512
+#: ``session_context.source_ids`` admits at most this many.
+MAX_SOURCE_IDS = 32
+
+#: How often ``research-open`` asks again while a session warms, and how long it keeps asking.
+#: One second is the cadence the worker itself polls at, and nothing in a warming session changes
+#: faster than that. The ceiling covers Studio's own policy with room to spare: a session may sit
+#: in ``warming`` for ``warm_timeout_seconds`` (180 by default) before the five-minute sweep fails
+#: it, so a session still warming at ten minutes is one Studio has already given up on, and the
+#: honest thing is to stop asking and say which state it was really in.
+OPEN_POLL_SECONDS = 1.0
+MAX_OPEN_WAIT_SECONDS = 600.0
+
+#: How long ``research-probe`` waits for its answer when the session states no usable idle
+#: timeout, and the ceiling it will wait whatever the session states. The session's own
+#: ``idle_timeout_seconds`` is the ordinary bound: a probe that has not settled when the session
+#: would have closed for inactivity is not going to settle, and the close is what cancels it.
+DEFAULT_PROBE_WAIT_SECONDS = 600.0
+MAX_PROBE_WAIT_SECONDS = 3600.0
+
+#: How often, at most, ``research-probe`` reads the probe resource while it follows the stream.
+#: The stream is asked between frames and on every heartbeat, so on a quiet session the resource
+#: is read about once per heartbeat (Studio's are at most fifteen seconds apart) and never more
+#: often than this.
+PROBE_POLL_SECONDS = 5.0
+
+#: The one line of ``--request`` this lane reads whole. A probe request is bounded by the
+#: vocabulary at 64 KiB of canonical JSON; a file four times that is refused before it is parsed.
+MAX_REQUEST_FILE_BYTES = 4 * session_probes.PROBE_REQUEST_MAX_BYTES
+
+#: Studio's ``Retry-After`` is delta-seconds in this contract. Bounded the way the token exchange
+#: bounds its own: a window this lane does not understand is reported as no window rather than as
+#: a number nobody checked.
+MAX_RETRY_AFTER_SECONDS = 3600
+
+#: The code Studio answers a full workspace with, as this lane's translation of it names it.
+BUDGET_EXCEEDED_CODE = "THIN_STUDIO_AGENT_BUDGET_EXCEEDED"
+
+_CONTROL = re.compile(r"[\x00-\x1f\x7f]")
+_FAILURE_CODE = re.compile(r"^[A-Z][A-Z0-9_]{2,127}$")
+
+#: ``common.schema.json#/$defs/uuid``, which is narrower than what :class:`uuid.UUID` parses: a
+#: version nibble of 1..8 and an RFC 4122 variant. An identifier the contract would refuse with a
+#: 422 is refused here with a sentence, before a credential is resolved.
+_CONTRACT_UUID = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+)
+
+
+class RetryAfterRefusal(ThinLaneError):
+    """A refusal Studio stamped with a retry window. Reported to the caller, never slept through.
+
+    Distinct from a plain :class:`ThinLaneError` in one attribute, ``retry_after_seconds``, which
+    the router carries into the error object so a script reads the window as a number rather than
+    parsing it out of a sentence. The sentence names it too, for the person.
+    """
+
+    def __init__(self, code: str, detail: str, *, retry_after_seconds: int | None) -> None:
+        super().__init__(code, detail)
+        self.retry_after_seconds = retry_after_seconds
+
+
+def _failure_code(value: Any, fallback: str) -> str:
+    """Keep one exact terminal worker code without rendering untrusted diagnostics."""
+
+    return value if isinstance(value, str) and _FAILURE_CODE.fullmatch(value) else fallback
+
+
+class StudioResearchClient(StudioApiClient):
+    """The research-session route family, including direct Run-to-session resolution.
+
+    Three write. ``open_session`` causes a session and a worker, ``submit_probe`` causes one row
+    a worker will answer, and the close calls end both. The two Run-coordinate calls are only
+    Studio's direct ownership resolver and close operation, never a client-side session scan.
+    What none of them can do is steer the session's Run: Studio refuses ``:cancel`` and ``:retry``
+    on a run of kind ``research_session`` so that taking the run terminal behind its session's back
+    is impossible, and this class formats neither path.
+    """
+
+    def open_session(
+        self, body: Mapping[str, Any], *, idempotency_key: str | None = None
+    ) -> dict[str, Any]:
+        """Open one session and return it as Studio recorded it, ``warming`` or not yet."""
+
+        headers: dict[str, str] = {}
+        try:
+            return self._call(
+                "POST",
+                OPEN_SESSION_PATH,
+                body=body,
+                extra_headers={
+                    "Idempotency-Key": idempotency_key or new_idempotency_key("mr-data-research")
+                },
+                expected=(201,),
+                response_headers=headers,
+            )
+        except ThinLaneError as refusal:
+            if refusal.code != BUDGET_EXCEEDED_CODE:
+                raise
+            raise _budget_refusal(refusal, headers, undone="opened") from refusal
+
+    def get_session(self, session_id: str) -> dict[str, Any]:
+        return self._call("GET", GET_SESSION_PATH.format(session_id=session_id), expected=(200,))
+
+    def get_session_by_run(self, run_id: str) -> dict[str, Any]:
+        """Resolve exactly one research session through Studio's Run ownership check."""
+
+        return self._call("GET", GET_SESSION_BY_RUN_PATH.format(run_id=run_id), expected=(200,))
+
+    def submit_probe(
+        self,
+        session_id: str,
+        body: Mapping[str, Any],
+        *,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        """Queue one probe. Studio answers 202 with the ResearchProbe, durable from that moment."""
+
+        headers: dict[str, str] = {}
+        try:
+            return self._call(
+                "POST",
+                SUBMIT_PROBE_PATH.format(session_id=session_id),
+                body=body,
+                extra_headers={
+                    "Idempotency-Key": idempotency_key or new_idempotency_key("mr-data-probe")
+                },
+                expected=(202,),
+                response_headers=headers,
+            )
+        except ThinLaneError as refusal:
+            if refusal.code != BUDGET_EXCEEDED_CODE:
+                raise
+            raise _budget_refusal(refusal, headers, undone="submitted") from refusal
+
+    def get_probe(self, session_id: str, probe_id: str) -> dict[str, Any]:
+        return self._call(
+            "GET",
+            GET_PROBE_PATH.format(session_id=session_id, probe_id=probe_id),
+            expected=(200,),
+        )
+
+    def close_session(
+        self,
+        session_id: str,
+        body: Mapping[str, Any],
+        *,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        """End one session. Closing a closed session is the same answer, not a conflict."""
+
+        return self._call(
+            "POST",
+            CLOSE_SESSION_PATH.format(session_id=session_id),
+            body=body,
+            extra_headers={
+                "Idempotency-Key": idempotency_key or new_idempotency_key("mr-data-research-close")
+            },
+            expected=(200,),
+        )
+
+    def close_session_by_run(
+        self,
+        run_id: str,
+        body: Mapping[str, Any],
+        *,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        """Ask Studio to resolve and atomically close the session owned by this displayed Run."""
+
+        return self._call(
+            "POST",
+            CLOSE_SESSION_BY_RUN_PATH.format(run_id=run_id),
+            body=body,
+            extra_headers={
+                "Idempotency-Key": idempotency_key
+                or new_idempotency_key("mr-data-research-close-by-run")
+            },
+            expected=(200,),
+        )
+
+
+def _budget_refusal(
+    refusal: ThinLaneError, headers: Mapping[str, str], *, undone: str
+) -> RetryAfterRefusal:
+    """Studio's capacity refusal, with the window it stated carried rather than slept on.
+
+    ``undone`` names what this call would have caused and did not -- a session, a probe -- because
+    the one sentence a caller reads after a 429 is the one saying nothing happened.
+    """
+
+    raw = headers.get("retry-after", "")
+    window = int(raw) if raw.isdecimal() and 1 <= int(raw) <= MAX_RETRY_AFTER_SECONDS else None
+    said = (
+        f"; Studio asked for a retry after {window} seconds"
+        if window is not None
+        else "; Studio stated no usable retry window"
+    )
+    return RetryAfterRefusal(
+        refusal.code,
+        f"{refusal.detail}{said}. Nothing was {undone}, and this command did not wait",
+        retry_after_seconds=window,
+    )
+
+
+# --------------------------------------------------------------------------------------------
+# The bodies this lane sends, with the contract applied here
+# --------------------------------------------------------------------------------------------
+
+
+def _identifier(value: Any, *, what: str, flag: str) -> str:
+    """Refuse anything that is not an identifier the contract admits, before it reaches the wire.
+
+    Checked before a credential is resolved and a token minted, the ordering every other lane here
+    establishes: a typo costs a sentence, not a round trip. The check is the contract's own
+    pattern rather than :class:`uuid.UUID`, which also parses the nil UUID, braces, and URN
+    prefixes that Studio would answer with a 422.
+    """
+
+    try:
+        normalized = str(UUID(str(value)))
+    except (ValueError, AttributeError) as error:
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID", f"{value!r} is not {what}; {flag} names one by its identifier"
+        ) from error
+    if not isinstance(value, str) or _CONTRACT_UUID.fullmatch(value) is None:
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            f"{value!r} is not {what}; {flag} names one by its identifier, as lowercase "
+            "hyphenated hex with a version of 1 to 8",
+        )
+    return normalized
+
+
+def _free_text(value: Any, *, flag: str, maximum: int) -> str:
+    if not isinstance(value, str) or not 1 <= len(value) <= maximum or _CONTROL.search(value):
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            f"{flag} is one line of at most {maximum} characters, with no control characters",
+        )
+    return value
+
+
+def session_context(
+    *,
+    dataset_id: Any,
+    question_id: Any,
+    table_id: Any = None,
+    source_ids: Sequence[Any] | None = None,
+) -> dict[str, Any]:
+    """The ``session_context`` a session is opened against, checked before anything is minted.
+
+    A session binds the Dataset and the question being explored -- and, optionally, a Table
+    already under construction and the sources it may probe -- and never a recipe activation.
+    Probing is what a recipe gets written FROM, so there is nothing here that could name one.
+    """
+
+    context: dict[str, Any] = {
+        "dataset_id": _identifier(dataset_id, what="a Dataset identifier", flag="--dataset"),
+        "question_id": _identifier(question_id, what="a question identifier", flag="--question"),
+    }
+    if table_id is not None:
+        context["table_id"] = _identifier(table_id, what="a Table identifier", flag="--table")
+    if not source_ids:
+        # ⚠ REQUIRED HERE, THOUGH THE CONTRACT MAKES IT OPTIONAL. `context.source_ids` is the
+        # permission: a probe naming a source outside it is refused `RESEARCH_SOURCE_FORBIDDEN`,
+        # so a session opened with none is a warm worker that can answer nothing, billed for
+        # every second it waits. Refusing the open is cheaper than the session it would produce.
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            "--source names at least one source the session may probe; a session opened with "
+            "none refuses every probe, because the sources named at the open are the permission",
+        )
+    # Repeats are folded rather than refused: `--source X --source X` is one source twice, and
+    # the contract's `uniqueItems` would otherwise turn a duplicated shell variable into a 422
+    # about a list the person cannot see.
+    selected = list(
+        dict.fromkeys(
+            _identifier(item, what="a source identifier", flag="--source") for item in source_ids
+        )
+    )
+    if len(selected) > MAX_SOURCE_IDS:
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            f"a session may name at most {MAX_SOURCE_IDS} sources; {len(selected)} were given",
+        )
+    context["source_ids"] = selected
+    return context
+
+
+def bundle_session_context(value: Any) -> dict[str, Any]:
+    """The Dataset, question and sources a bundle's propose journal recorded, for ``--bundle``.
+
+    ``propose --through sources`` registers those three and records their ids, so opening a session
+    to probe them is naming the bundle rather than repeating what it already holds. The journal is
+    read through the authoring lane's own reader -- the path, the byte ceiling and the schema check
+    are its -- imported here rather than at module scope because that lane imports this one.
+    A bundle whose proposal has not reached the sources stage has nothing to probe yet, and the
+    refusal says so.
+    """
+
+    from mostlyright.data_harness.thin import propose
+
+    ids = propose.journal_ids(value)
+    if ids.get("dataset_id") is None or ids.get("question_id") is None:
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            "--bundle's propose journal records no Dataset and question yet; run "
+            "mr-data propose --through question against it first",
+        )
+    source_ids = ids.get("source_ids")
+    if not isinstance(source_ids, list) or not source_ids:
+        # A session with no sources can answer no probe, so a bundle whose sources are not yet
+        # registered has nothing to open a session against. Refuse it here, naming the stage that
+        # registers them, rather than opening a warm worker that would refuse every probe.
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            "--bundle's propose journal records no registered sources yet; run "
+            "mr-data propose --through sources against it first, then probe what it registered",
+        )
+    return {
+        "dataset_id": ids.get("dataset_id"),
+        "question_id": ids.get("question_id"),
+        "source_ids": list(source_ids),
+    }
+
+
+def session_label(value: Any) -> str | None:
+    """The display label, or ``None`` when none was given. Never an identity."""
+
+    if value is None:
+        return None
+    return _free_text(value, flag="--label", maximum=MAX_LABEL_CHARS)
+
+
+def open_session_body(
+    *,
+    workspace_id: UUID,
+    dataset_id: Any,
+    question_id: Any,
+    table_id: Any = None,
+    source_ids: Sequence[Any] | None = None,
+    label: Any = None,
+) -> dict[str, Any]:
+    """The ``OpenResearchSessionCommand`` this lane sends."""
+
+    body: dict[str, Any] = {
+        "workspace_id": str(workspace_id),
+        "context": session_context(
+            dataset_id=dataset_id,
+            question_id=question_id,
+            table_id=table_id,
+            source_ids=source_ids,
+        ),
+    }
+    labelled = session_label(label)
+    if labelled is not None:
+        body["label"] = labelled
+    return body
+
+
+def probe_request(probe_kind: Any, request: Any) -> tuple[str, dict[str, Any]]:
+    """The kind and the normalized body, checked against the vocabulary before anything is sent.
+
+    ⚠ THE REQUEST IS CHECKED BEFORE IT IS SENT, AND WHAT IS SENT IS THE NORMALIZED FORM. Studio
+    stores a probe body uninterpreted and digests it; the worker then refuses one outside the
+    vocabulary as a ``failed`` probe with a code. Checking here turns that into a sentence at the
+    terminal, before a credential is resolved, a session's idempotency key is spent and a worker's
+    time is taken. The body that goes over the wire is the one :func:`validate_probe_request`
+    returns -- defaults filled in -- so two callers asking the same question get the same
+    ``request_digest`` whether or not one of them spelled out ``scan_rows``.
+    """
+
+    try:
+        kind = session_probes.probe_kind(probe_kind)
+        normalized = validate_probe_request(kind, request)
+    except ProbeVocabularyError as refusal:
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID", f"the probe request is outside the vocabulary: {refusal.detail}"
+        ) from refusal
+    except CanonicalJSONError as refusal:
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            f"the probe request is not canonical JSON: {refusal.detail}; a probe carries integers, "
+            "strings, booleans and null, never a fractional number",
+        ) from refusal
+    return kind, normalized
+
+
+def submit_probe_body(
+    *,
+    workspace_id: UUID,
+    session_id: str,
+    probe_kind: Any,
+    request: Any,
+) -> dict[str, Any]:
+    """The ``SubmitResearchProbeCommand`` this lane sends, with the vocabulary applied."""
+
+    kind, normalized = probe_request(probe_kind, request)
+    return {
+        "workspace_id": str(workspace_id),
+        "session_id": session_id,
+        "probe_kind": kind,
+        "request": normalized,
+    }
+
+
+def close_reason(value: Any) -> str | None:
+    """The close reason, or ``None`` when none was given."""
+
+    if value is None:
+        return None
+    return _free_text(value, flag="--reason", maximum=MAX_CLOSE_REASON_CHARS)
+
+
+def close_session_body(
+    *, workspace_id: UUID, session_id: str, reason: Any = None
+) -> dict[str, Any]:
+    """The ``CloseResearchSessionCommand`` this lane sends."""
+
+    body: dict[str, Any] = {"workspace_id": str(workspace_id), "session_id": session_id}
+    stated = close_reason(reason)
+    if stated is not None:
+        body["reason"] = stated
+    return body
+
+
+# --------------------------------------------------------------------------------------------
+# What the answers carry
+# --------------------------------------------------------------------------------------------
+
+
+def session_receipt(record: Mapping[str, Any]) -> dict[str, Any]:
+    """The ResearchSession fields a person reads, exactly as Studio reported them.
+
+    The three lease coordinates -- ``attempt_id``, ``worker_generation``, ``lease_nonce_digest``
+    -- and the image digest are left to ``--json`` readers of the raw record: they are facts about
+    the worker's fence, and a person deciding whether to probe needs the state, the clock and the
+    context, not the fence.
+    """
+
+    receipt = {
+        key: record[key]
+        for key in (
+            "session_id",
+            "run_id",
+            "state",
+            "context",
+            "label",
+            "warming_since",
+            "ready_at",
+            "idle_after_seconds",
+            "idle_timeout_seconds",
+            "probes_submitted",
+            "created_at",
+            "last_activity_at",
+            "last_worker_contact_at",
+            "closed_at",
+            "close_reason",
+            "failure_code",
+        )
+        if key in record
+    }
+    if "failure_code" in receipt:
+        receipt["failure_code"] = _failure_code(receipt["failure_code"], "RESEARCH_SESSION_FAILED")
+    return receipt
+
+
+def probe_receipt(record: Mapping[str, Any]) -> dict[str, Any]:
+    """The ResearchProbe coordinates, without the answer, which the payload carries on its own."""
+
+    receipt = {
+        key: record[key]
+        for key in (
+            "probe_id",
+            "session_id",
+            "run_id",
+            "ordinal",
+            "probe_kind",
+            "request",
+            "request_digest",
+            "state",
+            "result_digest",
+            "failure_code",
+            "submitted_at",
+            "claimed_at",
+            "settled_at",
+        )
+        if key in record
+    }
+    if "failure_code" in receipt:
+        receipt["failure_code"] = _failure_code(receipt["failure_code"], "PROBE_FAILED")
+    return receipt
+
+
+def _session(args: argparse.Namespace) -> StudioSession:
+    return open_studio_session(resolve_cloud_credentials())
+
+
+def _client(args: argparse.Namespace) -> StudioResearchClient:
+    return StudioResearchClient(_session(args))
+
+
+def _session_identifier(record: Mapping[str, Any]) -> str:
+    value = record.get("session_id")
+    try:
+        return str(UUID(str(value)))
+    except (ValueError, AttributeError) as error:
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID", "Studio answered with a session that has no identifier"
+        ) from error
+
+
+def _run_identifier(record: Mapping[str, Any]) -> str:
+    value = record.get("run_id")
+    try:
+        return str(UUID(str(value)))
+    except (ValueError, AttributeError) as error:
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID", "Studio answered with a session that names no run"
+        ) from error
+
+
+def _dataset_identifier(record: Mapping[str, Any]) -> str:
+    context = record.get("context")
+    value = context.get("dataset_id") if isinstance(context, Mapping) else None
+    try:
+        return str(UUID(str(value)))
+    except (ValueError, AttributeError) as error:
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID", "Studio answered with a session that names no Dataset"
+        ) from error
+
+
+def _dashboard_urls(cloud_url: str, record: Mapping[str, Any], run_id: str) -> dict[str, str]:
+    """All visual coordinates for one research session, derived from Studio's own binding."""
+
+    dataset_id = _dataset_identifier(record)
+    return {
+        "dashboard_url": run_dashboard_url(cloud_url, run_id),
+        "dataset_dashboard_url": dataset_dashboard_url(cloud_url, dataset_id),
+        "research_dashboard_url": dataset_research_dashboard_url(cloud_url, dataset_id, run_id),
+    }
+
+
+def _bind_session(record: Mapping[str, Any], *, session_id: str) -> None:
+    """Refuse a session record that is not the session this command is about.
+
+    Compared on every poll, the way the acquisition lane compares its immutable coordinates: a
+    record whose identifier moved under a reading is a different session, and printing its state
+    as this one's would be reporting somebody else's worker.
+    """
+
+    if record.get("session_id") != session_id:
+        raise ThinLaneError(
+            "THIN_SESSION_BINDING", "Studio answered about a different research session"
+        )
+
+
+def _refusal_receipt(refusal: ThinLaneError) -> dict[str, Any]:
+    """One typed refusal, as a member of a payload that still carries what was done before it."""
+
+    receipt: dict[str, Any] = {"code": refusal.code, "detail": refusal.detail}
+    window = getattr(refusal, "retry_after_seconds", None)
+    if window is not None:
+        receipt["retry_after_seconds"] = window
+    return receipt
+
+
+def _state_line(session_id: str, record: Mapping[str, Any]) -> str:
+    """One line a person reads when the session's state changes, and what the state means."""
+
+    state = str(record.get("state"))
+    if state == "opening":
+        return f"session {session_id} opening: the record exists; the worker is not started yet"
+    if state == "warming":
+        return (
+            f"session {session_id} warming: the worker is starting. This is the visible cold "
+            "start, not a stall; it ends when the worker takes its lease"
+        )
+    if state == "ready":
+        return f"session {session_id} ready: a worker holds the lease and no probe is waiting"
+    if state == "busy":
+        return f"session {session_id} busy: a probe is queued or being answered"
+    if state == "idle":
+        timeout = record.get("idle_timeout_seconds")
+        return (
+            f"session {session_id} idle: ready, and quiet; it closes on its own after "
+            f"{timeout} seconds without a probe"
+        )
+    if state == "failed":
+        code = _failure_code(record.get("failure_code"), "RESEARCH_SESSION_FAILED")
+        return f"session {session_id} failed: {code}"
+    if state == "closed":
+        reason = record.get("close_reason") or "no reason recorded"
+        return f"session {session_id} closed: {reason}"
+    return f"session {session_id} {state}: a state this client has no sentence for"
+
+
+# --------------------------------------------------------------------------------------------
+# research-open
+# --------------------------------------------------------------------------------------------
+
+
+def research_open(
+    args: argparse.Namespace,
+    *,
+    client: StudioResearchClient | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+    clock: Callable[[], float] = time.monotonic,
+) -> dict[str, Any]:
+    """``mr-data research-open``: open one session and watch it warm.
+
+    Every transition is printed as it happens -- ``opening``, ``warming``, ``ready`` -- so the
+    cold start reads as what it is. ``--no-wait`` returns as soon as Studio has recorded the
+    session, which is the shape a script that polls ``research-status`` itself wants.
+    """
+
+    announce = getattr(args, "json", False) is False
+    # Everything a client can settle on its own is settled before a credential is resolved: a
+    # mistyped identifier costs a sentence, not a token and a 422.
+    bundle = getattr(args, "bundle", None)
+    dataset = getattr(args, "dataset", None)
+    question = getattr(args, "question", None)
+    if bundle is not None and (dataset is not None or question is not None):
+        # Refused rather than silently preferring one: a bundle's journal and a flag that names a
+        # different Dataset are two answers to one question, and a session opened against the
+        # wrong one would probe sources the recipe will never name.
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            "--bundle names the Dataset and question from the bundle's journal; give it alone, "
+            "or give --dataset and --question without it",
+        )
+    if bundle is not None:
+        from_bundle = bundle_session_context(bundle)
+        dataset = from_bundle["dataset_id"]
+        question = from_bundle["question_id"]
+    else:
+        from_bundle = {}
+    if dataset is None or question is None:
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            "research-open needs a Dataset and a question: give --dataset and --question, or "
+            "--bundle whose propose journal records them",
+        )
+    # A bundle's sources and any named explicitly are one allowlist; `session_context` folds
+    # duplicates, so naming a source the bundle already carries is harmless.
+    sources = [*from_bundle.get("source_ids", []), *(getattr(args, "source", None) or [])]
+    context = session_context(
+        dataset_id=dataset,
+        question_id=question,
+        table_id=getattr(args, "table", None),
+        source_ids=sources or None,
+    )
+    label = session_label(getattr(args, "label", None))
+    selected = client or _client(args)
+    body: dict[str, Any] = {"workspace_id": str(selected.session.workspace_id), "context": context}
+    if label is not None:
+        body["label"] = label
+    record = selected.open_session(body)
+    session_id = _session_identifier(record)
+    run_id = _run_identifier(record)
+    waited = not getattr(args, "no_wait", False)
+    if announce:
+        print(_state_line(session_id, record), flush=True)
+    refusal: ThinLaneError | None = None
+    if waited:
+        try:
+            record = _await_live(
+                selected,
+                session_id,
+                record,
+                sleep=sleep,
+                clock=clock,
+                on_state=(lambda line: print(line, flush=True)) if announce else None,
+            )
+        except ThinLaneError as interrupted:
+            # The session exists whatever stopped the polling, and its identifier must not go
+            # down with the refusal: the record last read stands, the refusal rides beside it.
+            refusal = interrupted
+    state = record.get("state")
+    ready = state in LIVE_SESSION_STATES
+    if state in TERMINAL_SESSION_STATES:
+        status = "research_session_ended"
+    elif ready:
+        status = "research_session_ready"
+    else:
+        status = "research_session_opened"
+    payload: dict[str, Any] = {
+        "schema_version": RESEARCH_OPEN_SCHEMA,
+        "status": status,
+        "lane": "hosted",
+        "session_id": session_id,
+        "run_id": run_id,
+        "ready": ready,
+        "waited": waited,
+        "watch_command": f"mr-data watch {run_id} --hosted",
+        **_dashboard_urls(selected.session.cloud_url, record, run_id),
+        "session": session_receipt(record),
+        "studio": selected.session.to_receipt(),
+    }
+    if refusal is not None:
+        payload["refusal"] = _refusal_receipt(refusal)
+        payload["note"] = (
+            f"The session was opened and then this command could not keep reading it: "
+            f"{refusal.detail}. The session is unaffected; read it with mr-data research-status "
+            f"{session_id}."
+        )
+    elif status == "research_session_opened":
+        payload["note"] = f"The session is {state} and no worker has taken it yet. " + (
+            "Read it again with mr-data research-status; a probe submitted now waits in its "
+            "queue until the worker arrives."
+            if not waited
+            else f"Nothing answered within {int(MAX_OPEN_WAIT_SECONDS)} seconds, which is "
+            "past the warm timeout Studio enforces; read it again with mr-data "
+            "research-status, and open a new session if it has been failed."
+        )
+    elif status == "research_session_ended":
+        payload["note"] = (
+            "The session ended before a worker answered. It will not answer a probe; open a new "
+            "session."
+        )
+    return payload
+
+
+def _await_live(
+    client: StudioResearchClient,
+    session_id: str,
+    record: Mapping[str, Any],
+    *,
+    sleep: Callable[[float], None],
+    clock: Callable[[], float],
+    on_state: Callable[[str], None] | None,
+) -> dict[str, Any]:
+    """Poll the session until a worker holds it, it ends, or the ceiling arrives.
+
+    The ceiling is reported rather than raised: a session still warming at the deadline is a fact
+    about the session, and the payload says which state it was really in. Reading the session is
+    not activity -- ``last_activity_at`` moves on open, submission and settlement only -- so
+    polling cannot keep a session alive, and nothing here needs to avoid doing so.
+    """
+
+    observed = dict(record)
+    deadline = clock() + MAX_OPEN_WAIT_SECONDS
+    last_state = observed.get("state")
+    while True:
+        state = observed.get("state")
+        if state in LIVE_SESSION_STATES or state in TERMINAL_SESSION_STATES:
+            return observed
+        if clock() >= deadline:
+            return observed
+        sleep(OPEN_POLL_SECONDS)
+        observed = client.get_session(session_id)
+        _bind_session(observed, session_id=session_id)
+        if observed.get("state") != last_state:
+            last_state = observed.get("state")
+            if on_state is not None:
+                on_state(_state_line(session_id, observed))
+
+
+def research_open_exit_code(payload: Mapping[str, Any]) -> int:
+    """``0`` when a worker holds the session, or when the caller asked not to wait for one.
+
+    A session that ended, and a wait that ran out while it was still warming, both exit 2: the
+    caller asked for a session it could probe and did not get one, and the payload says which of
+    the two it was.
+    """
+
+    if payload.get("ready") is True:
+        return 0
+    if payload.get("status") == "research_session_opened" and payload.get("waited") is False:
+        return 0
+    return 2
+
+
+# --------------------------------------------------------------------------------------------
+# research-probe
+# --------------------------------------------------------------------------------------------
+
+
+def _read_request(args: argparse.Namespace) -> Any:
+    """The probe request, from ``--request`` or from ``--request-file``, and exactly one of them.
+
+    Parsed with the strict reader rather than the foreign one: the body goes out as canonical
+    JSON, which refuses a fractional number, so a request that carries one is refused here with a
+    sentence rather than three calls later with a traceback out of the encoder.
+    """
+
+    inline = getattr(args, "request", None)
+    named = getattr(args, "request_file", None)
+    if (inline is None) == (named is None):
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            "a probe carries one request body: give it inline with --request, or name a file "
+            "with --request-file, and not both",
+        )
+    if inline is not None:
+        raw: bytes | str = inline
+    else:
+        target = Path(str(named)).expanduser()
+        try:
+            descriptor, size = open_plain_file(target)
+        except PlainFileRefusal as refusal:
+            raise ThinLaneError(
+                "THIN_REQUEST_INVALID",
+                f"--request-file did not name one readable file: {refusal.path}",
+            ) from refusal
+        except OSError as error:
+            raise ThinLaneError(
+                "THIN_REQUEST_INVALID", f"--request-file could not be opened: {target}"
+            ) from error
+        try:
+            if size > MAX_REQUEST_FILE_BYTES:
+                raise ThinLaneError(
+                    "THIN_REQUEST_INVALID",
+                    f"--request-file holds {size} bytes; a probe request is at most "
+                    f"{session_probes.PROBE_REQUEST_MAX_BYTES} bytes of canonical JSON",
+                )
+            raw = read_bounded(descriptor, max_bytes=MAX_REQUEST_FILE_BYTES + 1)
+        finally:
+            os.close(descriptor)
+        if len(raw) > MAX_REQUEST_FILE_BYTES:
+            raise ThinLaneError(
+                "THIN_REQUEST_INVALID",
+                f"--request-file grew past {MAX_REQUEST_FILE_BYTES} bytes while it was being read",
+            )
+    try:
+        parsed = parse_json(raw)
+    except CanonicalJSONError as refusal:
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            f"the probe request is not strict JSON: {refusal.detail}; a probe carries integers, "
+            "strings, booleans and null, never a fractional number",
+        ) from refusal
+    if not isinstance(parsed, dict):
+        raise ThinLaneError("THIN_REQUEST_INVALID", "the probe request must be a JSON object")
+    return parsed
+
+
+def _probe_coordinates(record: Mapping[str, Any]) -> tuple[str, int]:
+    """The probe's identifier and its ordinal, which is how the stream names it."""
+
+    try:
+        probe_id = str(UUID(str(record.get("probe_id"))))
+    except (ValueError, AttributeError) as error:
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID", "Studio queued a probe without an identifier"
+        ) from error
+    ordinal = record.get("ordinal")
+    if type(ordinal) is not int or ordinal < 1:
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID",
+            "Studio queued a probe without the ordinal the stream would name it by",
+        )
+    return probe_id, ordinal
+
+
+def _probe_wait_seconds(record: Mapping[str, Any]) -> float:
+    declared = record.get("idle_timeout_seconds")
+    if type(declared) is int and declared >= 1:
+        return float(min(declared, MAX_PROBE_WAIT_SECONDS))
+    return DEFAULT_PROBE_WAIT_SECONDS
+
+
+def _session_sources(record: Mapping[str, Any]) -> list[str]:
+    context = record.get("context")
+    sources = context.get("source_ids") if isinstance(context, Mapping) else None
+    return [item for item in sources if isinstance(item, str)] if isinstance(sources, list) else []
+
+
+def _require_session_source(record: Mapping[str, Any], source_id: Any) -> None:
+    """Refuse a probe naming a source the session was not opened against, before it is queued.
+
+    The session's ``context.source_ids`` IS the permission: Studio's worker door refuses any other
+    source as ``RESEARCH_SOURCE_FORBIDDEN``, after the probe has been queued, claimed and given a
+    worker's time. The session record is already in hand here, so the refusal costs a sentence.
+    """
+
+    allowed = _session_sources(record)
+    if source_id in allowed:
+        return
+    raise ThinLaneError(
+        "THIN_RESEARCH_SOURCE_FORBIDDEN",
+        f"source {source_id} is not one this session may probe; the session was opened against "
+        + (", ".join(allowed) if allowed else "no source at all")
+        + ". Open a session naming the source with --source, or probe one of those",
+    )
+
+
+#: What the worker's own ``outcome`` on the settled frame means for the caller, in the words a
+#: caller acts on. The probe resource settles as ``failed`` for four of the five; the unsealed
+#: frame is where the refinement lives, and it is the difference between "ask again in a moment"
+#: and "never ask this again".
+_OUTCOME_ADVICE = {
+    "refused": (
+        "the request was refused rather than answered, and re-asking the same probe refuses the "
+        "same way; change the probe, or the source it names"
+    ),
+    "timed_out": (
+        "the worker did not finish inside its ceiling; the same probe against a smaller scan may "
+        "succeed"
+    ),
+    "failed": "the worker attempted it and broke; the code above is the worker's own",
+}
+
+_SESSION_ACQUISITION_THROTTLED = "SESSION_ACQUISITION_THROTTLED"
+_SESSION_ACQUISITION_THROTTLE_WIRE_CODE = "AGENT_BUDGET_EXCEEDED"
+
+
+def _worker_outcome_receipt(facts: Mapping[str, Any]) -> dict[str, Any]:
+    """Keep a bounded user-facing display code beside, never instead of, Studio's wire code."""
+
+    outcome = facts.get("outcome")
+    succeeded = outcome == "succeeded" and facts.get("code") == "OK"
+    wire_code = "OK" if succeeded else _failure_code(facts.get("code"), "PROBE_FAILED")
+    display_code = (
+        "OK"
+        if succeeded and facts.get("display_code") == "OK"
+        else _failure_code(facts.get("display_code"), wire_code)
+    )
+    receipt: dict[str, Any] = {
+        "outcome": outcome,
+        "code": display_code,
+        "wire_code": wire_code,
+        "bytes": facts.get("bytes"),
+    }
+    retry_after_seconds = facts.get("retry_after_seconds")
+    if wire_code == _SESSION_ACQUISITION_THROTTLE_WIRE_CODE:
+        receipt["code"] = _SESSION_ACQUISITION_THROTTLED
+    if (
+        receipt["code"] == _SESSION_ACQUISITION_THROTTLED
+        and wire_code == _SESSION_ACQUISITION_THROTTLE_WIRE_CODE
+        and type(retry_after_seconds) is int
+        and 1 <= retry_after_seconds <= MAX_RETRY_AFTER_SECONDS
+    ):
+        receipt["retry_after_seconds"] = retry_after_seconds
+    return receipt
+
+
+def _settles(
+    ordinal: int, announce: Callable[[str], None] | None, seen: dict[str, Any]
+) -> Callable[[Mapping[str, Any], str], bool]:
+    """The observer that ends the wait: the ``source_probe_settled`` frame carrying this ordinal.
+
+    Every frame on the session run passes through here -- replayed ones included, because the
+    stream is read from its first record -- and only the two about this probe are shown. Matching
+    on the ordinal rather than on a probe identifier is the design: the progress facts carry
+    Studio's counter and no identifier, and the counter is unique within the session, so a replay
+    of an earlier probe's settlement cannot be mistaken for this one's. The settled frame's facts
+    are kept in ``seen``: they carry the worker's refined ``outcome``, which the probe resource
+    collapses to ``failed`` and which is the fact a caller acts on.
+    """
+
+    def observe(body: Mapping[str, Any], frame_name: str) -> bool:
+        named = progress_facts(body)
+        if named is None:
+            return False
+        name, facts = named
+        if name not in {"source_probe_started", "source_probe_settled"}:
+            return False
+        if facts.get("ordinal") != ordinal:
+            return False
+        if announce is not None:
+            announce(render_frame(body, frame_name or RUN_PROGRESS_FRAME))
+        if name == "source_probe_settled":
+            seen.update(facts)
+            return True
+        return False
+
+    return observe
+
+
+def _polls_the_resource(
+    client: StudioResearchClient,
+    session_id: str,
+    probe_id: str,
+    *,
+    clock: Callable[[], float],
+    latest: dict[str, Any],
+) -> Callable[[], bool]:
+    """The check the stream asks between frames: has the probe settled on the resource itself?
+
+    ⚠ THE FRAME IS THE FAST PATH, NOT THE ONLY PATH. The worker writes a probe's result to Studio
+    BEFORE it emits the settled frame, and its emitter is best effort: it disarms itself after a
+    bounded number of progress records per attempt, and an append the callback refused is dropped
+    rather than retried. A wait that ended only on the frame would, on a long session, wait out
+    its whole ceiling for an answer Studio had already recorded. So the resource is read on a
+    bounded cadence -- at most once every :data:`PROBE_POLL_SECONDS`, asked between frames, on
+    every heartbeat of a quiet stream, and before every reconnect -- and the wait ends as soon as
+    either the frame or the resource says the probe settled. The last record read is kept in
+    ``latest`` so the caller does not read it twice.
+    """
+
+    asked_at = clock()
+
+    def stop() -> bool:
+        nonlocal asked_at
+        now = clock()
+        if now - asked_at < PROBE_POLL_SECONDS:
+            return False
+        asked_at = now
+        try:
+            record = client.get_probe(session_id, probe_id)
+        except ThinLaneError as refusal:
+            if refusal.code == "THIN_STUDIO_UNREACHABLE":
+                # One poll that did not get through is not a reason to stop listening to a
+                # stream that is still delivering; the next cadence asks again, and a Studio that
+                # stays unreachable is met at the read that follows the wait, as a refusal the
+                # payload carries.
+                return False
+            raise
+        if record.get("probe_id") != probe_id:
+            raise ThinLaneError("THIN_SESSION_BINDING", "Studio answered about a different probe")
+        latest.clear()
+        latest.update(record)
+        return record.get("state") in SETTLED_PROBE_STATES
+
+    return stop
+
+
+def research_probe(
+    args: argparse.Namespace,
+    *,
+    client: StudioResearchClient | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+    clock: Callable[[], float] = time.monotonic,
+) -> dict[str, Any]:
+    """``mr-data research-probe``: ask the warm worker one question and print its answer.
+
+    The request is checked against the vocabulary before a credential is resolved, the session is
+    read so the run to follow, the wait ceiling and the sources the probe may name are Studio's
+    rather than guessed, the probe is queued, and then the session run's stream is followed from
+    its first record until either the frame that says this probe settled or the probe resource,
+    read between frames, says so. The answer is then read from the probe resource itself.
+
+    ⚠ WHAT ``succeeded`` MEANS. It means the worker answered, and ``result`` is what it answered.
+    Every other settled state -- ``failed``, ``expired``, ``cancelled`` -- exits 2 with the state
+    named, the way ``approve`` treats every decision that is not the one asked for: a script
+    gating on an answer must not read the absence of one as a yes.
+
+    ⚠ A REFUSAL AFTER THE 202 KEEPS THE PROBE'S COORDINATES. Once Studio has queued the probe, a
+    stream this credential may not read, a stream that could not be re-established, or a frame
+    the parser refused is not a reason to lose the identifier of a probe that is still running:
+    the payload is emitted with the refusal under ``refusal`` and exits 2, and the probe is read
+    back with ``research-status``.
+    """
+
+    session_id = _identifier(
+        getattr(args, "session_id", None), what="a research session identifier", flag="SESSION_ID"
+    )
+    kind, normalized = probe_request(getattr(args, "kind", None), _read_request(args))
+    announce = getattr(args, "json", False) is False
+    selected = client or _client(args)
+    body = {
+        "workspace_id": str(selected.session.workspace_id),
+        "session_id": session_id,
+        "probe_kind": kind,
+        "request": normalized,
+    }
+    session_record = selected.get_session(session_id)
+    _bind_session(session_record, session_id=session_id)
+    run_id = _run_identifier(session_record)
+    if session_record.get("state") in TERMINAL_SESSION_STATES:
+        raise ThinLaneError(
+            "THIN_RESEARCH_SESSION_ENDED",
+            f"session {session_id} is {session_record.get('state')} and will not answer a probe; "
+            "open a new session with mr-data research-open",
+        )
+    _require_session_source(session_record, normalized.get("source_id"))
+    probe = selected.submit_probe(session_id, body)
+    probe_id, ordinal = _probe_coordinates(probe)
+    waited = not getattr(args, "no_wait", False)
+    if announce:
+        print(
+            f"probe {ordinal} ({body['probe_kind']}) queued on session {session_id} as {probe_id}",
+            flush=True,
+        )
+    payload: dict[str, Any] = {
+        "schema_version": RESEARCH_PROBE_SCHEMA,
+        "status": "research_probe_submitted",
+        "lane": "hosted",
+        "session_id": session_id,
+        "run_id": run_id,
+        "probe_id": probe_id,
+        "waited": waited,
+        "settled": False,
+        "watch_command": f"mr-data watch {run_id} --hosted",
+        **_dashboard_urls(selected.session.cloud_url, session_record, run_id),
+        "probe": probe_receipt(probe),
+        "result": None,
+        "not_evidence": NOT_EVIDENCE,
+        "studio": selected.session.to_receipt(),
+    }
+    if not waited:
+        payload["note"] = (
+            "The probe is queued and this command did not wait for it. Read its state with "
+            f"mr-data research-status {session_id} --probe {probe_id}."
+        )
+        return payload
+    stream = RunEventStream(selected.session, run_id, transport=selected.transport, sleep=sleep)
+    settled_facts: dict[str, Any] = {}
+    polled: dict[str, Any] = {}
+    try:
+        progress = stream.follow(
+            from_seq=0,
+            observe=_settles(
+                ordinal, (lambda line: print(line, flush=True)) if announce else None, settled_facts
+            ),
+            stop=_polls_the_resource(selected, session_id, probe_id, clock=clock, latest=polled),
+            deadline=clock() + _probe_wait_seconds(session_record),
+            clock=clock,
+        )
+        if polled.get("state") in SETTLED_PROBE_STATES:
+            # The poll that ended the wait already holds the settled record; reading it again
+            # would be one more round trip for the same bytes.
+            settled_probe = polled
+        else:
+            settled_probe = selected.get_probe(session_id, probe_id)
+            if settled_probe.get("probe_id") != probe_id:
+                raise ThinLaneError(
+                    "THIN_SESSION_BINDING", "Studio answered about a different probe"
+                )
+    except ThinLaneError as refusal:
+        payload["refusal"] = _refusal_receipt(refusal)
+        payload["note"] = (
+            f"The probe was queued and then this command could not follow it: {refusal.detail}. "
+            f"Nothing about the probe changed; read it with mr-data research-status {session_id} "
+            f"--probe {probe_id}."
+        )
+        return payload
+    state = settled_probe.get("state")
+    payload["probe"] = probe_receipt(settled_probe)
+    payload["stream"] = progress.to_receipt()
+    # The worker's own reading of how the probe ended, from the unsealed frame that ended the
+    # wait. Reported beside the resource rather than instead of it: the resource is the authority
+    # on WHETHER the probe settled, and the frame is the only place that says HOW.
+    worker_outcome = _worker_outcome_receipt(settled_facts) if settled_facts else None
+    # The terminal resource is authoritative and already passes through the
+    # bounded-code gate above.  This is an unsealed SSE observation used only
+    # to explain *how* the wait ended, so it gets the same treatment before it
+    # enters a CLI receipt; otherwise a malicious worker event could render a
+    # token or multiline diagnostic beside a perfectly safe resource record.
+    payload["worker_outcome"] = worker_outcome
+    outcome = settled_facts.get("outcome")
+    if state in SETTLED_PROBE_STATES:
+        payload["settled"] = True
+        # Which of the two said so first. The frame is the fast path; the resource is the one
+        # that is always there.
+        payload["settled_by"] = "stream" if settled_facts else "resource"
+    if state == "succeeded":
+        payload["status"] = "research_probe_answered"
+        payload["result"] = settled_probe.get("result")
+    elif state in SETTLED_PROBE_STATES:
+        payload["status"] = "research_probe_settled"
+        wire_failure_code = _failure_code(settled_probe.get("failure_code"), "PROBE_FAILED")
+        display_failure_code = wire_failure_code
+        retry_after_seconds: int | None = None
+        if worker_outcome is not None and worker_outcome.get("wire_code") == wire_failure_code:
+            display_failure_code = worker_outcome["code"]
+            retry_after_seconds = worker_outcome.get("retry_after_seconds")
+        payload["failure_code"] = display_failure_code
+        if display_failure_code != wire_failure_code:
+            payload["wire_failure_code"] = wire_failure_code
+        if retry_after_seconds is not None:
+            payload["retry_after_seconds"] = retry_after_seconds
+        payload["note"] = f"The probe settled as {state} and has no answer. " + _settled_why(
+            state, outcome, display_failure_code, retry_after_seconds
+        )
+    else:
+        payload["note"] = (
+            f"The probe is still {state}. "
+            + _unsettled_why(progress, bool(settled_facts))
+            + f"; read it again with mr-data research-status {session_id} --probe {probe_id}."
+        )
+    return payload
+
+
+def _settled_why(
+    state: str,
+    outcome: Any,
+    display_code: str | None = None,
+    retry_after_seconds: int | None = None,
+) -> str:
+    """Why a settled probe has no answer, following the RESOURCE where the two disagree.
+
+    The resource is the authority on the state; the frame refines a ``failed`` into which kind of
+    failure. A frame that says ``succeeded`` beside a resource that says ``cancelled`` is a probe
+    whose session ended between the worker answering and Studio recording it, and the record wins.
+    """
+
+    if state in {"cancelled", "expired"}:
+        said = (
+            "The session ended, or its worker's lease lapsed, before an answer was recorded; "
+            "open a new session."
+        )
+        if outcome == "succeeded":
+            said += (
+                " The worker's own frame says it answered, but Studio recorded no result, and "
+                "the record is the authority."
+            )
+        return said
+    if display_code == _SESSION_ACQUISITION_THROTTLED:
+        window = (
+            f"Retry after {retry_after_seconds} seconds."
+            if retry_after_seconds is not None
+            else "Studio supplied no usable retry window."
+        )
+        return (
+            f"Studio held this session's acquisition admission slot. {window} This is unrelated to "
+            "model tokens, billing, authentication, or source credentials."
+        )
+    if display_code == "PROBE_SOURCE_ACQUISITION_TIMEOUT":
+        return (
+            "Studio did not obtain the source before the acquisition timeout. Retrying later may "
+            "help; "
+            "choosing a smaller scan will not make the remote acquisition settle."
+        )
+    if display_code == "SANDBOX_TIMEOUT":
+        return (
+            "The source arrived, but the Clean room did not finish scanning it in time; the same "
+            "probe against a smaller scan may succeed."
+        )
+    if isinstance(outcome, str) and outcome in _OUTCOME_ADVICE:
+        return f"The worker reported it {outcome}: {_OUTCOME_ADVICE[outcome]}."
+    if outcome == "succeeded":
+        return (
+            "The worker's own frame says it answered, but Studio recorded a failure, and the "
+            "record is the authority; the code above is what Studio holds."
+        )
+    return (
+        "The code above is the worker's own; the settled line on the session's stream says "
+        "whether it was refused, throttled, or timed out."
+    )
+
+
+def _unsettled_why(progress: Any, frame_seen: bool) -> str:
+    """Why the wait ended with the probe still queued or claimed, by what actually ended it."""
+
+    if progress.expired:
+        return "The wait ran out before it settled"
+    if progress.end_reason is not None or progress.status is not None:
+        return "The session's run ended before it settled"
+    if frame_seen:
+        return "The stream said it settled, but Studio's record had not caught up when it was read"
+    return "The stream stopped before it settled"
+
+
+def research_probe_exit_code(payload: Mapping[str, Any]) -> int:
+    """``0`` only for an answered probe, or for a submission the caller chose not to wait on."""
+
+    if payload.get("status") == "research_probe_answered":
+        return 0
+    if payload.get("status") == "research_probe_submitted" and payload.get("waited") is False:
+        return 0
+    return 2
+
+
+# --------------------------------------------------------------------------------------------
+# research-status and research-close
+# --------------------------------------------------------------------------------------------
+
+
+def research_status(
+    args: argparse.Namespace, *, client: StudioResearchClient | None = None
+) -> dict[str, Any]:
+    """``mr-data research-status``: Studio's own reading of one session, and of one probe."""
+
+    session_id, requested_run_id = _session_or_run(args)
+    named = getattr(args, "probe", None)
+    probe_id = (
+        _identifier(named, what="a probe identifier", flag="--probe") if named is not None else None
+    )
+    selected = client or _client(args)
+    record = (
+        selected.get_session_by_run(requested_run_id)
+        if requested_run_id is not None
+        else selected.get_session(session_id)
+    )
+    if requested_run_id is not None:
+        session_id = _session_identifier(record)
+    _bind_session(record, session_id=session_id)
+    run_id = _run_identifier(record)
+    if requested_run_id is not None and run_id != requested_run_id:
+        raise ThinLaneError("THIN_SESSION_BINDING", "Studio answered about a different session Run")
+    payload: dict[str, Any] = {
+        "schema_version": RESEARCH_STATUS_SCHEMA,
+        "status": "research_session_reported",
+        "lane": "hosted",
+        "session_id": session_id,
+        "run_id": run_id,
+        "watch_command": f"mr-data watch {run_id} --hosted",
+        **_dashboard_urls(selected.session.cloud_url, record, run_id),
+        "session": session_receipt(record),
+        "studio": selected.session.to_receipt(),
+    }
+    if probe_id is not None:
+        probe = selected.get_probe(session_id, probe_id)
+        if probe.get("probe_id") != probe_id:
+            raise ThinLaneError("THIN_SESSION_BINDING", "Studio answered about a different probe")
+        payload["probe"] = probe_receipt(probe)
+        payload["result"] = probe.get("result") if probe.get("state") == "succeeded" else None
+        payload["not_evidence"] = NOT_EVIDENCE
+    return payload
+
+
+def research_close(
+    args: argparse.Namespace, *, client: StudioResearchClient | None = None
+) -> dict[str, Any]:
+    """``mr-data research-close``: end the session, its queued probes, and its worker."""
+
+    session_id, requested_run_id = _session_or_run(args)
+    # Checked once, and before the credential: the body below is composed from the checked value
+    # rather than run through the check a second time.
+    reason = close_reason(getattr(args, "reason", None))
+    selected = client or _client(args)
+    body: dict[str, Any] = {"workspace_id": str(selected.session.workspace_id)}
+    if requested_run_id is None:
+        body["session_id"] = session_id
+    else:
+        body["run_id"] = requested_run_id
+    if reason is not None:
+        body["reason"] = reason
+    record = (
+        selected.close_session_by_run(requested_run_id, body)
+        if requested_run_id is not None
+        else selected.close_session(session_id, body)
+    )
+    if requested_run_id is not None:
+        session_id = _session_identifier(record)
+    _bind_session(record, session_id=session_id)
+    run_id = _run_identifier(record)
+    if requested_run_id is not None and run_id != requested_run_id:
+        raise ThinLaneError("THIN_SESSION_BINDING", "Studio answered about a different session Run")
+    return {
+        "schema_version": RESEARCH_CLOSE_SCHEMA,
+        "status": "research_session_closed",
+        "lane": "hosted",
+        "session_id": session_id,
+        "run_id": run_id,
+        **_dashboard_urls(selected.session.cloud_url, record, run_id),
+        "session": session_receipt(record),
+        "studio": selected.session.to_receipt(),
+    }
+
+
+# --------------------------------------------------------------------------------------------
+# The command line, declared once for both parsers
+# --------------------------------------------------------------------------------------------
+
+#: The four names, in the order a session is used.
+COMMANDS = ("research-open", "research-probe", "research-status", "research-close")
+
+#: One help line per command. Read by the thin help and by the local parser alike, so the two
+#: cannot describe one command two ways.
+COMMAND_HELP = dict(
+    (
+        ("research-open", "open one hosted research session and watch its worker warm up"),
+        ("research-probe", "ask a research session's worker one question and print its answer"),
+        ("research-status", "report Studio's own reading of one research session, or one probe"),
+        ("research-close", "close one research session; its worker exits"),
+    )
+)
+
+_SESSION_POSITIONAL = "the research session, by the identifier research-open printed"
+
+
+def _session_or_run(args: argparse.Namespace) -> tuple[str, str | None]:
+    """Choose one direct Studio coordinate; resolving a Run by listing sessions is forbidden."""
+
+    session_value = getattr(args, "session_id", None)
+    run_value = getattr(args, "run_id", None)
+    if (session_value is None) == (run_value is None):
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID", "supply exactly one of SESSION_ID or --run RUN_ID"
+        )
+    if run_value is not None:
+        return "", _identifier(run_value, what="a research session Run identifier", flag="--run")
+    return _identifier(session_value, what="a research session identifier", flag="SESSION_ID"), None
+
+
+def declare_arguments(name: str, parser: argparse.ArgumentParser) -> None:
+    """Add one research command's arguments to ``parser``.
+
+    ⚠ CALLED BY BOTH PARSERS. The thin router's parser and ``cli``'s parser each add the four
+    names, and each hands its subparser here, so the argument surface is declared once and the
+    two cannot disagree -- the property ``note`` has by a test and these have by construction.
+    """
+
+    if name == "research-open":
+        parser.add_argument(
+            "--dataset",
+            help="the Dataset the session probes for; taken from --bundle when one is given",
+        )
+        parser.add_argument(
+            "--question",
+            help="the question being explored, by its identifier; taken from --bundle when given",
+        )
+        parser.add_argument(
+            "--bundle",
+            metavar="BUNDLE_DIR",
+            help="an authoring bundle whose propose journal names the Dataset, question and "
+            "sources to probe, so they are read rather than repeated",
+        )
+        parser.add_argument("--table", help="a Table already under construction, when there is one")
+        parser.add_argument(
+            "--source",
+            action="append",
+            metavar="SOURCE_ID",
+            help="a source the session may probe; repeatable, at most 32; added to --bundle's",
+        )
+        parser.add_argument("--label", help="a display label for the session; never an identity")
+        parser.add_argument(
+            "--no-wait",
+            dest="no_wait",
+            action="store_true",
+            help="return once Studio has recorded the session, without waiting for its worker",
+        )
+        return
+    if name == "research-probe":
+        parser.add_argument("session_id", help=_SESSION_POSITIONAL)
+        parser.add_argument(
+            "--kind",
+            required=True,
+            choices=PROBE_KINDS,
+            help="what to ask the worker; the request body under it is checked before it is sent",
+        )
+        parser.add_argument(
+            "--request", help="the probe request body, as one JSON object on the command line"
+        )
+        parser.add_argument(
+            "--request-file",
+            dest="request_file",
+            metavar="FILE",
+            help="the probe request body, read from a JSON file instead of the command line",
+        )
+        parser.add_argument(
+            "--no-wait",
+            dest="no_wait",
+            action="store_true",
+            help="return once the probe is queued, without waiting for its answer",
+        )
+        return
+    if name == "research-status":
+        parser.add_argument("session_id", nargs="?", metavar="SESSION_ID", help=_SESSION_POSITIONAL)
+        parser.add_argument(
+            "--run",
+            dest="run_id",
+            metavar="RUN_ID",
+            help="the displayed research session Run; Studio resolves its session directly",
+        )
+        parser.add_argument(
+            "--probe",
+            metavar="PROBE_ID",
+            help="also report this probe, with its answer if it has one",
+        )
+        return
+    if name == "research-close":
+        parser.add_argument("session_id", nargs="?", metavar="SESSION_ID", help=_SESSION_POSITIONAL)
+        parser.add_argument(
+            "--run",
+            dest="run_id",
+            metavar="RUN_ID",
+            help="the displayed research session Run; Studio resolves and closes its session",
+        )
+        parser.add_argument("--reason", help="why the session is being closed; recorded by Studio")
+        return
+    raise ValueError(f"{name!r} is not a research command")  # pragma: no cover - closed tuple
+
+
+#: The handler and the exit-code rule behind each name, for both front doors.
+HANDLERS: dict[str, Callable[[argparse.Namespace], dict[str, Any]]] = {
+    "research-open": research_open,
+    "research-probe": research_probe,
+    "research-status": research_status,
+    "research-close": research_close,
+}
+
+EXIT_CODES: dict[str, Callable[[Mapping[str, Any]], int]] = {
+    "research-open": research_open_exit_code,
+    "research-probe": research_probe_exit_code,
+}
+
+
+__all__ = [
+    "BUDGET_EXCEEDED_CODE",
+    "CLOSE_SESSION_BY_RUN_PATH",
+    "CLOSE_SESSION_PATH",
+    "COMMANDS",
+    "COMMAND_HELP",
+    "DEFAULT_PROBE_WAIT_SECONDS",
+    "EXIT_CODES",
+    "GET_PROBE_PATH",
+    "GET_SESSION_BY_RUN_PATH",
+    "GET_SESSION_PATH",
+    "HANDLERS",
+    "LIVE_SESSION_STATES",
+    "MAX_CLOSE_REASON_CHARS",
+    "MAX_LABEL_CHARS",
+    "MAX_OPEN_WAIT_SECONDS",
+    "MAX_PROBE_WAIT_SECONDS",
+    "MAX_SOURCE_IDS",
+    "NOT_EVIDENCE",
+    "OPEN_POLL_SECONDS",
+    "OPEN_SESSION_PATH",
+    "PROBE_KINDS",
+    "PROBE_STATES",
+    "RESEARCH_CLOSE_SCHEMA",
+    "RESEARCH_OPEN_SCHEMA",
+    "RESEARCH_PROBE_SCHEMA",
+    "RESEARCH_STATUS_SCHEMA",
+    "SESSION_STATES",
+    "SETTLED_PROBE_STATES",
+    "SUBMIT_PROBE_PATH",
+    "TERMINAL_SESSION_STATES",
+    "RetryAfterRefusal",
+    "StudioResearchClient",
+    "bundle_session_context",
+    "close_session_body",
+    "declare_arguments",
+    "open_session_body",
+    "probe_receipt",
+    "probe_request",
+    "research_close",
+    "research_open",
+    "research_open_exit_code",
+    "research_probe",
+    "research_probe_exit_code",
+    "research_status",
+    "session_context",
+    "session_label",
+    "session_receipt",
+    "submit_probe_body",
+]