convergent-cli 0.1.0__py3-none-any.whl

convergent_cli/commands/calibration.py

@@ -0,0 +1,3857 @@
+"""Staff commands that run one calibration treatment across tenants.
+
+Each step can be run again. A run that already exists is left in place when
+it matches this request. Nothing is stored in a local file.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import time
+import urllib.parse
+from collections.abc import Callable, Mapping, Sequence
+from concurrent.futures import CancelledError
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, TypeGuard
+
+from convergent_cli import calibration_frontier, control_client, customer_client
+from convergent_cli.calibration_runner import (
+    BUSY_SCOPE,
+    BUSY_SCOPE_NOTE,
+    RETRY_RECEIPTS,
+    SESSION_MINIMUM,
+    TenantSpec,
+    attempt_run_id,
+    contribution_receipt,
+    default_input_setting_run_id,
+    default_preprocessing_digest,
+    default_preprocessing_document,
+    document_digest,
+    error_rate_exceeds_limit,
+    error_verdict_rate,
+    estimate,
+    exclusion_reason,
+    input_attempt_exhausted,
+    input_run_is_reusable,
+    is_input_setting_run,
+    labeled_input_run_id,
+    parse_tenant,
+    preprocessing_digest,
+    preprocessing_slot_lines,
+    require_digest,
+    require_input_label,
+    require_input_run_id,
+    require_json_object,
+    require_k,
+    require_label_release,
+    require_manifest_id,
+    require_treatment,
+    resolved_runtime_pin,
+    run_request_mismatch,
+    session_minimum_waived,
+    session_minimum_warning,
+    spend_report,
+    stable_run_id,
+    step_event,
+    suite_digest_from_run,
+)
+from convergent_cli.calibration_send import (
+    DEFAULT_SEND_TIMEOUT_SECONDS,
+    SendDeadline,
+    SendTimeout,
+    send_timeout_seconds,
+)
+from convergent_cli.command_tree import CommandCatalog, CommandInfo, Effect, Plane
+from convergent_cli.commands.runs import _criterion_versions
+from convergent_cli.confirm import confirm_write
+from convergent_cli.errors import (
+    ControlRefusedError,
+    ExitCode,
+    InvalidResponseError,
+    NetworkError,
+    UsageError,
+)
+from convergent_cli.output import emit_json
+from convergent_cli.transport import post_json
+
+_ELIGIBLE_PATH = "/v1/staff/calibration/eligible-organizations"
+_TREATMENTS_PATH = "/v1/staff/calibration/treatments"
+_MANIFESTS_PATH = "/v1/staff/calibration/manifests"
+_CONTRIBUTION_READ_TIMEOUT_SECONDS = 300.0
+# show and compare compute pooled results on the server. Wait past the
+# control-plane ALB's 60-second idle timeout so cv is never the first hop to give up.
+_POOLED_READ_TIMEOUT_SECONDS = 65.0
+
+
+def register(subparsers: Any, catalog: CommandCatalog) -> None:
+    calibration = subparsers.add_parser(
+        "calibration",
+        help="Plan and run calibration treatments across tenants.",
+    )
+    commands = calibration.add_subparsers(dest="calibration_command", required=True)
+    plan = commands.add_parser("plan", help="Show who would run, who is left out, and the cost.")
+    _add_session_minimum_waiver(plan)
+    _bind(
+        catalog,
+        plan,
+        _plan,
+        ("calibration", "plan"),
+        "Show who would run, who is left out, and the cost.",
+        Effect.READ,
+        tenants=True,
+        k_default=1,
+    )
+    input_parser = commands.add_parser(
+        "input",
+        help="Start one input-setting run per included tenant.",
+    )
+    input_parser.add_argument(
+        "--carry-forward",
+        metavar="INPUT_LABEL",
+        help=(
+            "Copy each unchanged extraction document from the earlier input run with this "
+            "input label, instead of building it again."
+        ),
+    )
+    input_parser.add_argument(
+        "--carry-forward-digest",
+        help=(
+            "64 hex preprocessing digest of the --carry-forward input. "
+            "Needed on a treatment-scoped manifest."
+        ),
+    )
+    _bind(
+        catalog,
+        input_parser,
+        _input,
+        ("calibration", "input"),
+        "Start one input-setting run per included tenant.",
+        Effect.WRITE,
+        manifest=True,
+        grading=True,
+        preprocessing_body=True,
+        input_label=True,
+    )
+    _bind(
+        catalog,
+        commands.add_parser("treat", help="Start one treatment run per included tenant."),
+        _treat,
+        ("calibration", "treat"),
+        "Start one treatment run per included tenant.",
+        Effect.WRITE,
+        manifest=True,
+        treatment=True,
+        grading=True,
+        criterion_versions=True,
+        k=True,
+        preprocessing_body=True,
+        input_label=True,
+    )
+    candidate = commands.add_parser(
+        "candidate",
+        help="Create one calibration grader version on every included tenant.",
+    )
+    _add_manifest(candidate)
+    candidate.add_argument("--grader-id", required=True, help="Grader that receives the version.")
+    candidate.add_argument(
+        "--definition",
+        required=True,
+        help=(
+            "JSON file for the grader version. The file is sent unchanged to every tenant. "
+            "An agentic criterion switched to a judge can name its inputs: "
+            '{"evaluator": {"type": "llm_judge", "field": "final_content", '
+            '"context_fields": ["task_input", "trace_digest"], "on_missing_field": "skip", '
+            '"pass_condition": "...", "examples": {"pass_examples": [], "fail_examples": []}}}.'
+        ),
+    )
+    candidate.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show the tenants that would get this version, and do not create it.",
+    )
+    _add_format(candidate)
+    _bind_parser(
+        catalog,
+        candidate,
+        _candidate,
+        ("calibration", "candidate"),
+        "Create one calibration grader version on every included tenant.",
+        Effect.WRITE,
+        Plane.CUSTOMER,
+    )
+    declare = commands.add_parser(
+        "declare",
+        help="Write the expected contribution rows for one treatment.",
+    )
+    _add_treatment(declare)
+    _add_manifest(declare)
+    declare.add_argument(
+        "--grader-suite-digest",
+        action="append",
+        help=(
+            "Optional check against the finished treatment runs. "
+            "Those runs supply the grader suite digest. "
+            "Each value here must match the digest they record."
+        ),
+    )
+    _add_criterion_version(declare)
+    _add_runtime(declare)
+    _add_preprocessing_digest(declare)
+    _add_k(declare, default=None)
+    declare.add_argument(
+        "--replicates",
+        type=int,
+        default=1000,
+        help="How many replicates the declaration records. Defaults to 1000.",
+    )
+    _add_input_label(declare)
+    _add_format(declare)
+    _bind_parser(
+        catalog,
+        declare,
+        _declare,
+        ("calibration", "declare"),
+        "Write the expected contribution rows for one treatment.",
+        Effect.WRITE,
+        Plane.CONTROL,
+    )
+    _bind(
+        catalog,
+        commands.add_parser("stats", help="Send each succeeded treatment run's contribution."),
+        _stats,
+        ("calibration", "stats"),
+        "Send each succeeded treatment run's contribution.",
+        Effect.WRITE,
+        manifest=True,
+        treatment=True,
+        criterion_versions=True,
+        k=True,
+        input_label=True,
+        preprocessing_digest=True,
+        gate=True,
+        send_timeout=True,
+    )
+    finish = commands.add_parser(
+        "finish", help="Declare recorded treatment identity and send contributions concurrently."
+    )
+    # finish also imports this module for declaration and send helpers.
+    from convergent_cli.calibration_finish import concurrency
+
+    finish.add_argument(
+        "--concurrency",
+        type=concurrency,
+        default=2,
+        help="Maximum tenants sending concurrently (default: 2).",
+    )
+    finish.add_argument(
+        "--wait", action="store_true", help="Poll runs every 30 seconds until terminal."
+    )
+    _bind(
+        catalog,
+        finish,
+        _finish,
+        ("calibration", "finish"),
+        "Declare recorded treatment identity and send contributions concurrently.",
+        Effect.WRITE,
+        manifest=True,
+        treatment=True,
+        criterion_versions=True,
+        k=True,
+        input_label=True,
+        preprocessing_digest=True,
+        gate=True,
+        send_timeout=True,
+    )
+    _bind(
+        catalog,
+        commands.add_parser("cancel", help="Cancel each tenant's run for one treatment."),
+        _cancel,
+        ("calibration", "cancel"),
+        "Cancel each tenant's run for one treatment.",
+        Effect.WRITE,
+        manifest=True,
+        treatment=True,
+        criterion_versions=True,
+        k=True,
+        input_label=True,
+        preprocessing_digest=True,
+    )
+    _bind(
+        catalog,
+        commands.add_parser(
+            "status",
+            help="Show treatment runs, error rates, and spend against the monthly budget.",
+        ),
+        _status,
+        ("calibration", "status"),
+        "Show treatment runs, error rates, and spend against the monthly budget.",
+        Effect.READ,
+        manifest=True,
+        treatment=True,
+        criterion_versions=True,
+        k=True,
+        input_label=True,
+        preprocessing_digest=True,
+    )
+    show = commands.add_parser("show", help="Read one treatment's pooled calibration result.")
+    show.add_argument("treatment", help="Treatment name, such as treatment_a.")
+    show.add_argument("--tenant", help="Read one tenant instead of the pooled result.")
+    show.add_argument(
+        "--decider",
+        metavar="BASELINE",
+        help=(
+            "On a decider arm, also print its gated rates minus BASELINE's own, "
+            "after checking each tenant's gate names BASELINE's run."
+        ),
+    )
+    _add_read_format(show)
+    _bind_parser(
+        catalog,
+        show,
+        _show,
+        ("calibration", "show"),
+        "Read one treatment's pooled calibration result.",
+        Effect.READ,
+        Plane.CONTROL,
+    )
+    compare = commands.add_parser(
+        "compare",
+        help="Compare a baseline treatment with a candidate.",
+    )
+    compare.add_argument("baseline", help="Baseline treatment name.")
+    compare.add_argument("candidate", help="Candidate treatment name.")
+    compare.add_argument(
+        "--basis",
+        choices=("post_audit", "pre_audit"),
+        default="post_audit",
+        help=(
+            "Count the comparison from the stored verdict (post_audit) "
+            "or from the verdict before the finding audit (pre_audit)."
+        ),
+    )
+    _add_read_format(compare)
+    _bind_parser(
+        catalog,
+        compare,
+        _compare,
+        ("calibration", "compare"),
+        "Compare a baseline treatment with a candidate.",
+        Effect.READ,
+        Plane.CONTROL,
+    )
+    calibration_frontier.register(commands, catalog, read=_staff_get, warn=_warn_session_floor)
+    preprocessing = commands.add_parser(
+        "preprocessing",
+        help="Check a grader preprocessing document offline.",
+    )
+    preprocessing_commands = preprocessing.add_subparsers(
+        dest="preprocessing_command", required=True
+    )
+    check = preprocessing_commands.add_parser(
+        "check",
+        help="Validate a preprocessing document and print its digest. Makes no API call.",
+    )
+    check.add_argument("file", help="Path to the grader preprocessing JSON document.")
+    _add_format(check)
+    catalog.bind(
+        parser=check,
+        handler=_preprocessing_check,
+        info=CommandInfo(
+            path=("calibration", "preprocessing", "check"),
+            description="Validate a preprocessing document and print its digest.",
+            plane=Plane.LOCAL,
+            requires_session=False,
+            effect=Effect.READ,
+        ),
+    )
+    manifest = commands.add_parser(
+        "manifest",
+        help="Register and read a calibration corpus manifest.",
+    )
+    manifest_commands = manifest.add_subparsers(dest="manifest_command", required=True)
+    create = manifest_commands.add_parser(
+        "create",
+        help="Build a corpus manifest from the server and register it.",
+    )
+    create.add_argument("--label-release", required=True, help="Label release this corpus pins.")
+    create.add_argument(
+        "--tenant",
+        action="append",
+        required=True,
+        help=(
+            "tag,organization_id,workspace_id,environment_id[,dataset_id]. Repeat for each tenant."
+        ),
+    )
+    create.add_argument(
+        "--grader-preprocessing",
+        help="JSON object for grader preprocessing. The digest is computed from this.",
+    )
+    _add_preprocessing_digest(create)
+    create.add_argument(
+        "--input-setting-run",
+        action="append",
+        default=None,
+        metavar="TAG=BASE_RUN_ID",
+        help=(
+            "Base run id for one tenant's input-setting attempts. "
+            "Repeat for each tenant that should not use the default."
+        ),
+    )
+    create.add_argument(
+        "--treatment-scoped",
+        action="store_true",
+        help=(
+            "Leave preprocessing and the input run out of the manifest. "
+            "Each treatment names its own preprocessing document."
+        ),
+    )
+    create.add_argument(
+        "--pin-package",
+        metavar="SHA256",
+        help=(
+            "Pin every arm on this manifest to this calibration-grade package digest. "
+            "Run create refuses a digest that is unknown, not a calibration package, or denied."
+        ),
+    )
+    create.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print the manifest and its id, and do not register it.",
+    )
+    _add_session_minimum_waiver(create)
+    _add_format(create)
+    _bind_parser(
+        catalog,
+        create,
+        _manifest_create,
+        ("calibration", "manifest", "create"),
+        "Build a corpus manifest from the server and register it.",
+        Effect.WRITE,
+        Plane.CONTROL,
+    )
+    repin = manifest_commands.add_parser(
+        "repin",
+        help="Register a manifest's document again with a new pinned package: a new experiment.",
+    )
+    repin.add_argument("manifest_id", help="64 hex corpus manifest id.")
+    repin.add_argument(
+        "--package", required=True, metavar="SHA256", help="Calibration-grade package digest."
+    )
+    _add_format(repin)
+    _bind_parser(
+        catalog,
+        repin,
+        _manifest_repin,
+        ("calibration", "manifest", "repin"),
+        "Register a manifest's document again with a new pinned package.",
+        Effect.WRITE,
+        Plane.CONTROL,
+    )
+    manifest_show = manifest_commands.add_parser(
+        "show",
+        help="Read one stored corpus manifest and its tenants.",
+    )
+    manifest_show.add_argument("manifest_id", help="64 hex corpus manifest id.")
+    _add_format(manifest_show)
+    _bind_parser(
+        catalog,
+        manifest_show,
+        _manifest_show,
+        ("calibration", "manifest", "show"),
+        "Read one stored corpus manifest and its tenants.",
+        Effect.READ,
+        Plane.CONTROL,
+    )
+
+
+_REPEAT_NOTE = "Registering this same document again returns this id."
+_WAIVER_REFUSED = "session_minimum_waiver_not_allowed"
+_PLAN_EXCLUSION = {"ineligible": "off_shared_plane"}
+
+
+def _manifest_create(args: argparse.Namespace) -> int:
+    label = require_label_release(args.label_release)
+    tenants = [parse_tenant(raw) for raw in args.tenant or []]
+    if not tenants:
+        raise UsageError("at least one --tenant is required")
+    tags = [tenant.tenant_tag for tenant in tenants]
+    if len(tags) != len(set(tags)):
+        raise UsageError("tenant tag is repeated")
+    preprocessing = _manifest_preprocessing(args)
+    overrides = _input_setting_overrides(args, tenants)
+    treatment_scoped = bool(args.treatment_scoped)
+    if treatment_scoped and (preprocessing is not None or overrides):
+        raise UsageError("--treatment-scoped leaves preprocessing and the input run unset")
+    context = _control()
+    eligible = {
+        row["organization_id"]
+        for row in _organizations(
+            control_client.get_control_json_at(
+                context.control_origin,
+                _ELIGIBLE_PATH,
+                access_token=context.control_token,
+                transport=context.transport,
+            )
+        )
+    }
+    included: list[dict[str, object]] = []
+    excluded: list[dict[str, object]] = []
+    for tenant in tenants:
+        row, kept = _manifest_row(
+            tenant,
+            label=label,
+            eligible=tenant.organization_id in eligible,
+            preprocessing=preprocessing,
+            override=overrides.get(tenant.tenant_tag),
+            allow_waiver=args.allow_below_session_minimum,
+            treatment_scoped=treatment_scoped,
+        )
+        if kept:
+            included.append(row)
+        else:
+            excluded.append(row)
+    for row in included:
+        if row.get("session_minimum_waived") is True:
+            _warn(f"tenant {row['tenant_tag']}", int(str(row["session_count"])))
+    included.sort(key=lambda row: str(row["tenant_tag"]))
+    excluded.sort(key=lambda row: str(row["tenant_tag"]))
+    identities = [
+        {
+            "tenant_tag": tenant.tenant_tag,
+            "organization_id": tenant.organization_id,
+            "workspace_id": tenant.workspace_id,
+            "environment_id": tenant.environment_id,
+        }
+        for tenant in sorted(tenants, key=lambda item: item.tenant_tag)
+    ]
+    document: dict[str, object] = {
+        "label_release": label,
+        "included": included,
+        "excluded": excluded,
+    }
+    if args.pin_package is not None:
+        document["calibration_package_digest"] = require_digest(args.pin_package, "--pin-package")
+    payload, manifest_id = _manifest_payload(document, identities)
+    result: dict[str, object] = {
+        "corpus_manifest_id": manifest_id,
+        "repeat_note": _REPEAT_NOTE,
+        "document": payload["document"],
+        "tenants": payload["tenants"],
+    }
+    if args.dry_run:
+        result["dry_run"] = True
+        _emit(args, result)
+        return 0
+    confirm_write("This will register a calibration corpus manifest.")
+    response = _register_manifest(context, payload)
+    if response.get("corpus_manifest_id") != manifest_id:
+        raise InvalidResponseError("the stored corpus manifest id does not match the document")
+    _emit(args, result)
+    return 0
+
+
+def _manifest_repin(args: argparse.Namespace) -> int:
+    """Register the same document with a new package digest. The new id is a new epoch."""
+
+    manifest_id = require_manifest_id(args.manifest_id)
+    package = require_digest(args.package, "--package")
+    context = _control()
+    quoted = urllib.parse.quote(manifest_id, safe="")
+    stored = control_client.get_control_json_at(
+        context.control_origin,
+        f"{_MANIFESTS_PATH}/{quoted}",
+        access_token=context.control_token,
+        transport=context.transport,
+    )
+    document = stored.get("manifest")
+    if not isinstance(document, Mapping) or document_digest(document) != manifest_id:
+        raise InvalidResponseError("the corpus manifest response does not hash to its id")
+    rows = control_client.get_control_json_list(
+        context.control_origin,
+        f"{_MANIFESTS_PATH}/{quoted}/tenants",
+        access_token=context.control_token,
+        transport=context.transport,
+    )
+    identities = [
+        {key: _required_text(row, key) for key in _IDENTITY_KEYS}
+        for row in rows
+        if isinstance(row, Mapping)
+    ]
+    if len(identities) != len(rows):
+        raise InvalidResponseError("a manifest tenant identity is malformed")
+    payload, repinned = _manifest_payload(
+        {**document, "calibration_package_digest": package}, identities
+    )
+    if repinned == manifest_id:
+        raise UsageError(f"{manifest_id} is already pinned to {package}")
+    confirm_write("This will register a calibration corpus manifest pinned to a new package.")
+    response = _register_manifest(context, payload)
+    if response.get("corpus_manifest_id") != repinned:
+        raise InvalidResponseError("the stored corpus manifest id does not match the document")
+    _emit(
+        args,
+        {"corpus_manifest_id": repinned, "repinned_from": manifest_id, "package": package},
+    )
+    return 0
+
+
+_IDENTITY_KEYS = ("tenant_tag", "organization_id", "workspace_id", "environment_id")
+
+
+def _preprocessing_check(args: argparse.Namespace) -> int:
+    try:
+        raw = Path(args.file).read_text(encoding="utf-8")
+    except OSError as exc:
+        raise UsageError("cannot read the grader preprocessing file") from exc
+    document = require_json_object(
+        _json_object(raw, "grader preprocessing"), "grader preprocessing"
+    )
+    digest = preprocessing_digest(document)
+    slots = preprocessing_slot_lines(document)
+    if args.format == "json":
+        emit_json({"grader_preprocessing_digest": digest, "slots": slots})
+    else:
+        print("\n".join([f"grader_preprocessing_digest={digest}", *slots]))
+    return 0
+
+
+def _manifest_show(args: argparse.Namespace) -> int:
+    manifest_id = require_manifest_id(args.manifest_id)
+    context = _control()
+    quoted = _quote(manifest_id)
+    payload = control_client.get_control_json_at(
+        context.control_origin,
+        f"{_MANIFESTS_PATH}/{quoted}",
+        access_token=context.control_token,
+        transport=context.transport,
+    )
+    tenants = control_client.get_control_json_list(
+        context.control_origin,
+        f"{_MANIFESTS_PATH}/{quoted}/tenants",
+        access_token=context.control_token,
+        transport=context.transport,
+    )
+    if payload.get("corpus_manifest_id") != manifest_id:
+        raise InvalidResponseError("the corpus manifest response id does not match")
+    document = payload.get("manifest")
+    if not isinstance(document, Mapping):
+        raise InvalidResponseError("the corpus manifest response has no manifest")
+    if document_digest(document) != manifest_id:
+        raise UsageError("the stored corpus document does not match its id")
+    _emit(
+        args,
+        {
+            "corpus_manifest_id": manifest_id,
+            "document": document,
+            "tenants": tenants,
+        },
+    )
+    return 0
+
+
+def _manifest_preprocessing(args: argparse.Namespace) -> str | None:
+    raw = getattr(args, "grader_preprocessing", None)
+    flag = _optional_digest(getattr(args, "preprocessing_digest", None))
+    if raw is None:
+        return flag
+    document = require_json_object(
+        _json_object(raw, "grader preprocessing"),
+        "grader preprocessing",
+    )
+    computed = preprocessing_digest(document)
+    if flag is not None and flag != computed:
+        raise UsageError("--preprocessing-digest does not match --grader-preprocessing")
+    return computed
+
+
+def _input_setting_overrides(
+    args: argparse.Namespace,
+    tenants: list[TenantSpec],
+) -> dict[str, str]:
+    known = {tenant.tenant_tag for tenant in tenants}
+    overrides: dict[str, str] = {}
+    for raw in args.input_setting_run or []:
+        tag, separator, run_id = raw.partition("=")
+        if separator == "" or tag == "" or run_id == "":
+            raise UsageError("--input-setting-run must be TAG=BASE_RUN_ID")
+        if tag not in known:
+            raise UsageError(f"--input-setting-run names unknown tenant {tag}")
+        if tag in overrides:
+            raise UsageError(f"--input-setting-run repeats {tag}")
+        overrides[tag] = require_input_run_id(run_id)
+    return overrides
+
+
+def _manifest_row(
+    tenant: TenantSpec,
+    *,
+    label: str,
+    eligible: bool,
+    preprocessing: str | None,
+    override: str | None,
+    allow_waiver: bool,
+    treatment_scoped: bool = False,
+) -> tuple[dict[str, object], bool]:
+    if not eligible:
+        reason = exclusion_reason(
+            eligible=False,
+            dataset_id=tenant.dataset_id,
+            dataset_missing=False,
+            session_count=None,
+        )
+        return (
+            {
+                "tenant_tag": tenant.tenant_tag,
+                "reason": None if reason is None else _PLAN_EXCLUSION.get(reason, reason),
+            },
+            False,
+        )
+    if tenant.dataset_id is None:
+        return {"tenant_tag": tenant.tenant_tag, "reason": "no_dataset"}, False
+    try:
+        version_id, digest = _dataset_pin(tenant)
+    except customer_client.CustomerPlaneRequestError as exc:
+        if exc.status_code != 404:
+            raise
+        return {"tenant_tag": tenant.tenant_tag, "reason": "no_dataset"}, False
+    except customer_client.ControlPlaneRefusedError as exc:
+        raise InvalidResponseError(
+            f"{tenant.tenant_tag} was refused without a calibration reason"
+        ) from exc
+    try:
+        session_count = _session_count(tenant, version_id)
+    except customer_client.ControlPlaneRefusedError as exc:
+        raise InvalidResponseError(
+            f"{tenant.tenant_tag} was refused without a calibration reason"
+        ) from exc
+    waived = session_minimum_waived(session_count, allowed=allow_waiver)
+    if session_count < SESSION_MINIMUM and not waived:
+        return {"tenant_tag": tenant.tenant_tag, "reason": "below_session_minimum"}, False
+    if treatment_scoped:
+        row = {
+            "tenant_tag": tenant.tenant_tag,
+            "eval_dataset_id": tenant.dataset_id,
+            "eval_dataset_version_id": version_id,
+            "content_digest": digest,
+            "session_count": session_count,
+        }
+        if waived:
+            row["session_minimum_waived"] = True
+        return row, True
+    run_id = override or default_input_setting_run_id(
+        label,
+        tenant.tenant_tag,
+        eval_dataset_version_id=version_id,
+        preprocessing_digest=preprocessing,
+    )
+    if override is not None:
+        try:
+            _require_input_setting_run(tenant, override)
+        except customer_client.ControlPlaneRefusedError as exc:
+            raise InvalidResponseError(
+                f"{tenant.tenant_tag} was refused without a calibration reason"
+            ) from exc
+    row: dict[str, object] = {
+        "tenant_tag": tenant.tenant_tag,
+        "eval_dataset_id": tenant.dataset_id,
+        "eval_dataset_version_id": version_id,
+        "content_digest": digest,
+        "session_count": session_count,
+        "preprocessing_digest": preprocessing,
+        "input_setting_run_id": run_id,
+    }
+    if waived:
+        row["session_minimum_waived"] = True
+    return row, True
+
+
+def _require_input_setting_run(tenant: TenantSpec, run_id: str) -> None:
+    existing = _get_run(tenant, run_id)
+    if existing is None:
+        return
+    if is_input_setting_run(existing):
+        return
+    raise UsageError(f"{tenant.tenant_tag} input-setting run {run_id} is not an input-setting run")
+
+
+def _dataset_pin(tenant: TenantSpec) -> tuple[str, str]:
+    payload = _customer_get(tenant, f"/v1/eval-datasets/{_quote(_dataset_id(tenant))}")
+    dataset = payload.get("dataset")
+    if not isinstance(dataset, Mapping):
+        raise InvalidResponseError("the dataset response has no dataset")
+    version_id = dataset.get("current_version_id")
+    if not isinstance(version_id, str) or not version_id:
+        raise InvalidResponseError("the dataset response has no current version")
+    digest = dataset.get("content_digest")
+    if not isinstance(digest, str):
+        raise InvalidResponseError("the dataset response has no content digest")
+    try:
+        return version_id, require_digest(digest, "content digest")
+    except UsageError as exc:
+        raise InvalidResponseError("the dataset response has no content digest") from exc
+
+
+def _register_manifest(context: Any, payload: Mapping[str, object]) -> Mapping[str, object]:
+    url = control_client.control_url(context.control_origin, _MANIFESTS_PATH)
+    response = post_json(
+        context.transport,
+        url,
+        payload,
+        headers={"Authorization": f"Bearer {context.control_token}"},
+    )
+    if response.status_code == 422:
+        refusal = _named_refusal(response)
+        if str(refusal) == _WAIVER_REFUSED:
+            raise ControlRefusedError(
+                f"{_WAIVER_REFUSED}: the control plane refused the session-minimum waiver. "
+                "It is accepted only on staging."
+            )
+        raise refusal
+    control_client._require_success(response, url)
+    value = response.json()
+    if not isinstance(value, Mapping):
+        raise InvalidResponseError(f"{url} did not answer with a JSON object")
+    return value
+
+
+def _manifest_payload(
+    document: dict[str, object],
+    tenants: list[dict[str, str]],
+) -> tuple[dict[str, object], str]:
+    return {"document": document, "tenants": tenants}, document_digest(document)
+
+
+def _plan(args: argparse.Namespace) -> int:
+    started = time.perf_counter()
+    k = require_k(args.k)
+    tenants = [parse_tenant(raw) for raw in args.tenant or []]
+    context = _control()
+    payload = control_client.get_control_json_at(
+        context.control_origin,
+        _ELIGIBLE_PATH,
+        access_token=context.control_token,
+        transport=context.transport,
+    )
+    organizations = _organizations(payload)
+    eligible_ids = {row["organization_id"] for row in organizations}
+    rows: list[dict[str, object]] = []
+    included_traces = 0
+    for tenant in tenants:
+        row, traces = _plan_tenant(
+            tenant,
+            eligible=tenant.organization_id in eligible_ids,
+            allow_waiver=args.allow_below_session_minimum,
+        )
+        rows.append(row)
+        included_traces += traces
+        reason = row.get("reason")
+        _log(
+            args,
+            "plan",
+            "ok",
+            started=started,
+            tenant_tag=tenant.tenant_tag,
+            reason=reason if isinstance(reason, str) else None,
+        )
+    if not tenants:
+        _log(args, "plan", "ok", started=started)
+    result = {
+        "organizations": organizations,
+        "tenants": rows,
+        "estimate": estimate(trace_count=included_traces, k=k),
+        "busy_scope": BUSY_SCOPE,
+        "busy_scope_note": BUSY_SCOPE_NOTE,
+    }
+    _emit(args, result)
+    return 0
+
+
+def _input(args: argparse.Namespace) -> int:
+    started = time.perf_counter()
+    manifest_id = require_manifest_id(args.corpus_manifest_id)
+    runtime, criterion_ids, document, computed = _grading_document(args)
+    manifest = _load_manifest(manifest_id)
+    document, computed = _use_default_preprocessing(manifest, runtime, document, computed)
+    _agree_preprocessing(manifest, computed)
+    label = _input_label(args)
+    carry_label, carry_digest = _carry_forward(args, manifest)
+    confirm_write("This will start missing input-setting runs. Existing runs are kept.")
+    rows: list[dict[str, object]] = []
+    for tenant in manifest.included:
+        carry_run_id = None
+        if carry_label is not None:
+            carry_run_id = _latest_reusable_input(
+                tenant,
+                input_base=_input_base(manifest, tenant, carry_label, carry_digest),
+                dataset_id=tenant.dataset_id,
+                version_id=tenant.version_id,
+                environment_id=tenant.environment_id,
+                workspace_id=tenant.workspace_id,
+                preprocessing_digest=_active_digest(tenant, carry_digest),
+            )
+        tried: set[str] = set()
+        while True:
+            run_id, existing = _next_input_attempt(
+                tenant,
+                input_base=_input_base(manifest, tenant, label, computed),
+                dataset_id=tenant.dataset_id,
+                version_id=tenant.version_id,
+                environment_id=tenant.environment_id,
+                workspace_id=tenant.workspace_id,
+                preprocessing_digest=computed,
+            )
+            if existing is not None:
+                created = False
+                outcome = "reused"
+                break
+            if run_id in tried:
+                raise UsageError(
+                    f"{tenant.tenant_tag} input run {run_id} conflicted and was not reusable"
+                )
+            tried.add(run_id)
+            try:
+                run_id, created = _create_or_reuse(
+                    tenant,
+                    _run_body(
+                        dataset_id=tenant.dataset_id,
+                        version_id=tenant.version_id,
+                        environment_id=tenant.environment_id,
+                        run_id=run_id,
+                        samples=1,
+                        runtime=runtime,
+                        criterion_ids=criterion_ids,
+                        preprocessing=document,
+                        carry_forward_run_id=carry_run_id,
+                        package=manifest.package_digest,
+                    ),
+                    dataset_id=tenant.dataset_id,
+                    version_id=tenant.version_id,
+                    samples=1,
+                    preprocessing_digest=computed,
+                )
+            except _FailedInputConflict:
+                continue
+            outcome = "created" if created else "reused"
+            break
+        rows.append(
+            {
+                "tenant_tag": tenant.tenant_tag,
+                "run_id": run_id,
+                "created": created,
+                "dataset_version_id": tenant.version_id,
+            }
+        )
+        _log(args, "input", outcome, started=started, tenant_tag=tenant.tenant_tag, run_id=run_id)
+    _emit(args, {"tenants": rows})
+    return 0
+
+
+def _carry_forward(args: argparse.Namespace, manifest: _Manifest) -> tuple[str | None, str | None]:
+    """The earlier input's label and digest. Its run id is derived the way treat derives one."""
+
+    raw = getattr(args, "carry_forward", None)
+    digest = _optional_digest(getattr(args, "carry_forward_digest", None))
+    if raw is None:
+        if digest is not None:
+            raise UsageError("--carry-forward-digest needs --carry-forward")
+        return None, None
+    carry_label = require_input_label(raw)
+    if carry_label == _input_label(args):
+        raise UsageError("--carry-forward names this input's own label")
+    _require_scoped_preprocessing(manifest, digest, "--carry-forward-digest")
+    return carry_label, digest
+
+
+def _treat(args: argparse.Namespace) -> int:
+    started = time.perf_counter()
+    treatment = require_treatment(args.treatment)
+    k = require_k(args.k)
+    runtime, criterion_ids, document, computed = _grading_document(args)
+    pins = _parsed_pins(args, criterion_ids)
+    manifest = _load_manifest(require_manifest_id(args.corpus_manifest_id))
+    document, computed = _use_default_preprocessing(manifest, runtime, document, computed)
+    _agree_preprocessing(manifest, computed)
+    label = _input_label(args)
+    _refuse_treatment_bound_elsewhere(treatment, manifest, k, pins, label, computed)
+    confirm_write("This will start missing treatment runs. Existing runs are kept.")
+    rows: list[dict[str, object]] = []
+    for tenant in manifest.included:
+        source_run_id = _latest_reusable_input(
+            tenant,
+            input_base=_input_base(manifest, tenant, label, computed),
+            dataset_id=tenant.dataset_id,
+            version_id=tenant.version_id,
+            environment_id=tenant.environment_id,
+            workspace_id=tenant.workspace_id,
+            preprocessing_digest=computed,
+        )
+        run_id = _treatment_id(
+            treatment,
+            manifest,
+            tenant,
+            k,
+            source_run_id,
+            pins,
+            labeled=label is not None,
+            input_base=_input_base(manifest, tenant, label, computed),
+            preprocessing_digest=computed,
+        )
+        existing = _get_run(tenant, run_id)
+        if existing is None:
+            run_id, created = _create_or_reuse(
+                tenant,
+                _run_body(
+                    dataset_id=tenant.dataset_id,
+                    version_id=tenant.version_id,
+                    environment_id=tenant.environment_id,
+                    run_id=run_id,
+                    samples=k,
+                    runtime=runtime,
+                    criterion_ids=criterion_ids,
+                    criterion_versions=pins,
+                    preprocessing=document,
+                    source_run_id=source_run_id,
+                    treatment=treatment,
+                    tenant_tag=tenant.tenant_tag,
+                    manifest_id=manifest.manifest_id,
+                    label_release=manifest.label_release,
+                    session_minimum_waived=tenant.session_minimum_waived,
+                    package=manifest.package_digest,
+                ),
+                dataset_id=tenant.dataset_id,
+                version_id=tenant.version_id,
+                samples=k,
+                runtime=runtime,
+                criterion_ids=criterion_ids,
+                criterion_versions=pins,
+                preprocessing_digest=computed,
+                preprocessing=document,
+                treatment=treatment,
+                tenant_tag=tenant.tenant_tag,
+                manifest_id=manifest.manifest_id,
+                label_release=manifest.label_release,
+                source_run_id=source_run_id,
+            )
+            outcome = "created" if created else "reused"
+        else:
+            _refuse_mismatch(
+                existing,
+                tenant,
+                dataset_id=tenant.dataset_id,
+                version_id=tenant.version_id,
+                samples=k,
+                runtime=runtime,
+                criterion_ids=criterion_ids,
+                criterion_versions=pins,
+                preprocessing_digest=computed,
+                preprocessing=document,
+                treatment=treatment,
+                tenant_tag=tenant.tenant_tag,
+                manifest_id=manifest.manifest_id,
+                label_release=manifest.label_release,
+                source_run_id=source_run_id,
+            )
+            created = False
+            outcome = "reused"
+        rows.append(
+            {
+                "tenant_tag": tenant.tenant_tag,
+                "run_id": run_id,
+                "created": created,
+                "input_run_id": source_run_id,
+            }
+        )
+        _log(args, "treat", outcome, started=started, tenant_tag=tenant.tenant_tag, run_id=run_id)
+    _emit(args, {"tenants": rows})
+    return 0
+
+
+def _declare(args: argparse.Namespace) -> int:
+    started = time.perf_counter()
+    treatment = require_treatment(args.treatment)
+    label = _input_label(args)
+    manifest_id = require_manifest_id(args.corpus_manifest_id)
+    pins = _parsed_pins(args, None)
+    supplied = [
+        require_digest(item, "grader suite digest") for item in (args.grader_suite_digest or [])
+    ]
+    runtime = require_json_object(
+        _json_object(args.platform_grader_runtime, "platform grader runtime"),
+        "platform grader runtime",
+    )
+    k = require_k(args.k)
+    if isinstance(args.replicates, bool) or not isinstance(args.replicates, int):
+        raise UsageError("replicates must be an integer from 1 to 1000")
+    if not 1 <= args.replicates <= 1000:
+        raise UsageError("replicates must be an integer from 1 to 1000")
+    digest = _optional_digest(args.preprocessing_digest)
+    declaration = _recorded_declaration(
+        treatment,
+        manifest_id,
+        k,
+        pins,
+        input_label=label,
+        preprocessing_digest=digest,
+        runtime=runtime,
+    )
+    recorded = declaration.suite_digest
+    if supplied and set(supplied) != {recorded}:
+        supplied_text = ", ".join(supplied)
+        if pins:
+            raise UsageError(
+                "grader suite digest does not match the pinned treatment runs: "
+                f"runs have {recorded}; --grader-suite-digest has {supplied_text}"
+            )
+        raise UsageError(
+            "grader suite digest does not match the treatment runs: "
+            f"the runs record {recorded}; --grader-suite-digest has {supplied_text}"
+        )
+    digests = [recorded]
+    confirm_write("This will write the expected contribution rows for this treatment.")
+    response = _write_declaration(
+        treatment,
+        manifest_id,
+        digests,
+        declaration.runtime,
+        k,
+        args.replicates,
+        declaration.preprocessing_digest,
+    )
+    _log(args, "declare", "ok", started=started)
+    _emit(args, dict(response))
+    return 0
+
+
+def _write_declaration(
+    treatment: str,
+    manifest_id: str,
+    digests: list[str],
+    runtime: Mapping[str, object],
+    k: int,
+    replicates: int,
+    digest: str | None,
+) -> Mapping[str, object]:
+    body: dict[str, object] = {
+        "treatment": treatment,
+        "corpus_manifest_id": manifest_id,
+        "grader_suite_digests": digests,
+        "runtime_pin": runtime,
+        "k": k,
+        "replicate_count": replicates,
+        "declared": digest is not None,
+    }
+    if digest is not None:
+        body["preprocessing_digest"] = digest
+    context = _control()
+    return control_client.post_control_json(
+        context.control_origin,
+        _TREATMENTS_PATH,
+        body,
+        access_token=context.control_token,
+        transport=context.transport,
+    )
+
+
+def _gate_choice(
+    args: argparse.Namespace, treatment: str
+) -> tuple[str | None, dict[str, str] | None]:
+    gate = getattr(args, "gate_baseline", None)
+    if gate is not None:
+        gate = require_treatment(gate, label="--gate-baseline")
+        if gate == treatment:
+            raise UsageError("--gate-baseline names this treatment; name the baseline it gates")
+    raw_gate_pins = getattr(args, "gate_baseline_criterion_version", None)
+    if raw_gate_pins and gate is None:
+        raise UsageError("--gate-baseline-criterion-version pins the --gate-baseline treatment")
+    gate_pins = _criterion_versions(raw_gate_pins if isinstance(raw_gate_pins, list) else None)
+    return gate, gate_pins
+
+
+def _finish(args: argparse.Namespace) -> int:
+    # Load after registration: finish reuses this module's stats/declare operations.
+    from convergent_cli.calibration_finish import finish
+
+    return finish(args)
+
+
+def _stats(args: argparse.Namespace) -> int:
+    started = time.perf_counter()
+    treatment = require_treatment(args.treatment)
+    gate, gate_pins = _gate_choice(args, treatment)
+    k = require_k(args.k)
+    pins = _parsed_pins(args, None)
+    label = _input_label(args)
+    named = _optional_digest(getattr(args, "preprocessing_digest", None))
+    manifest = _load_manifest(require_manifest_id(args.corpus_manifest_id))
+    _require_scoped_preprocessing(manifest, named, "--preprocessing-digest")
+    _refuse_treatment_bound_elsewhere(treatment, manifest, k, pins, label, named)
+    confirm_write("This will send a contribution for each succeeded treatment run.")
+    receipts: list[dict[str, object]] = []
+    pending: list[tuple[_ManifestTenant, dict[str, object]]] = []
+    deadline = SendDeadline(args.send_timeout)
+    try:
+        for tenant in manifest.included:
+            if tenant.session_minimum_waived and tenant.session_count is not None:
+                _warn(f"tenant {tenant.tenant_tag}", tenant.session_count)
+            active = _active_digest(tenant, named)
+            source_run_id, run_id, run = _resolve_treatment_run(
+                treatment, manifest, tenant, k, pins, label, named
+            )
+            if run is None or run.get("status") != "succeeded":
+                continue
+            _refuse_mismatch(
+                run,
+                tenant,
+                dataset_id=tenant.dataset_id,
+                version_id=tenant.version_id,
+                samples=k,
+                preprocessing_digest=active,
+                criterion_versions=pins,
+                treatment=treatment,
+                tenant_tag=tenant.tenant_tag,
+                manifest_id=manifest.manifest_id,
+                label_release=manifest.label_release,
+                source_run_id=source_run_id,
+            )
+            gate_run_id = None
+            baseline = None
+            if gate is not None:
+                gate_run_id = _treatment_id(
+                    gate,
+                    manifest,
+                    tenant,
+                    k,
+                    source_run_id,
+                    gate_pins,
+                    labeled=label is not None,
+                    input_base=_input_base(manifest, tenant, label, named),
+                    preprocessing_digest=named,
+                )
+                baseline = _get_run(tenant, gate_run_id)
+            if gate_run_id is not None and (
+                baseline is None or baseline.get("status") != "succeeded"
+            ):
+                receipt, reason = "refused", "gate_baseline_unavailable"
+            else:
+                deadline.remaining()
+                receipt, reason = _send_contribution(
+                    tenant,
+                    run_id,
+                    treatment,
+                    gate_run_id,
+                    ungated=bool(args.ungated),
+                    deadline=deadline,
+                )
+                if reason == "gate_choice_required":
+                    # The data plane refused before writing anything.
+                    raise UsageError(
+                        "this treatment is graded by a decider route: pass --gate-baseline "
+                        "TREATMENT or --ungated. The first send is final."
+                    )
+            receipts.append(
+                {
+                    "tenant_tag": tenant.tenant_tag,
+                    "run_id": run_id,
+                    "receipt": receipt,
+                    "reason": reason,
+                }
+            )
+            if receipt in {"sending", "counting"}:
+                pending.append((tenant, receipts[-1]))
+            _log(
+                args,
+                "stats",
+                receipt,
+                started=started,
+                tenant_tag=tenant.tenant_tag,
+                run_id=run_id,
+                reason=reason,
+            )
+        while pending:
+            deadline.pause()
+            remaining = []
+            for tenant, row in pending:
+                state, reason = _poll_contribution(tenant, str(row["run_id"]), deadline=deadline)
+                row.update(receipt=state, reason=reason)
+                if state in {"sending", "counting"}:
+                    remaining.append((tenant, row))
+            pending = remaining
+    except (Exception, KeyboardInterrupt) as exc:
+        if args.format == "json":
+            _emit(args, {"receipts": receipts, "skipped_tenants": _skipped_rows(manifest)})
+        if isinstance(exc, SendTimeout):
+            raise _send_timeout_error(receipts, "receipt", treatment) from exc
+        raise
+    _emit(args, {"receipts": receipts, "skipped_tenants": _skipped_rows(manifest)})
+    if any(row.get("receipt") in RETRY_RECEIPTS | {"refused"} for row in receipts):
+        return int(ExitCode.REMOTE)
+    return 0
+
+
+def _send_timeout_error(
+    rows: Sequence[Mapping[str, object]],
+    state_key: str,
+    treatment: str,
+    unsent: Sequence[str] = (),
+) -> NetworkError:
+    pending = ", ".join(
+        str(row["tenant_tag"]) for row in rows if row.get(state_key) in {"sending", "counting"}
+    )
+    not_sent = f" Tenants not sent: {', '.join(unsent)}." if unsent else ""
+    return NetworkError(
+        f"send_timeout: tenants still sending: {pending or 'none'}. "
+        f"No further sends were posted.{not_sent} Check cv calibration show {treatment}."
+    )
+
+
+def _cancel(args: argparse.Namespace) -> int:
+    """Stop a treatment: a pending run ends now, a running one stops after its current trace."""
+    started = time.perf_counter()
+    treatment = require_treatment(args.treatment)
+    k = require_k(args.k)
+    pins = _parsed_pins(args, None)
+    label = _input_label(args)
+    named = _optional_digest(getattr(args, "preprocessing_digest", None))
+    manifest = _load_manifest(require_manifest_id(args.corpus_manifest_id))
+    _require_scoped_preprocessing(manifest, named, "--preprocessing-digest")
+    confirm_write("This will cancel each tenant's run for this treatment.")
+    rows: list[dict[str, object]] = []
+    for tenant in manifest.included:
+        active = _active_digest(tenant, named)
+        source_run_id = _latest_reusable_input(
+            tenant,
+            input_base=_input_base(manifest, tenant, label, named),
+            dataset_id=tenant.dataset_id,
+            version_id=tenant.version_id,
+            environment_id=tenant.environment_id,
+            workspace_id=tenant.workspace_id,
+            preprocessing_digest=active,
+        )
+        run_id = _treatment_id(
+            treatment,
+            manifest,
+            tenant,
+            k,
+            source_run_id,
+            pins,
+            labeled=label is not None,
+            input_base=_input_base(manifest, tenant, label, named),
+            preprocessing_digest=named,
+        )
+        run = _get_run(tenant, run_id)
+        if run is None:
+            rows.append({"tenant_tag": tenant.tenant_tag, "run_id": run_id, "status": "missing"})
+            continue
+        _refuse_mismatch(
+            run,
+            tenant,
+            dataset_id=tenant.dataset_id,
+            version_id=tenant.version_id,
+            samples=k,
+            preprocessing_digest=active,
+            criterion_versions=pins,
+            treatment=treatment,
+            tenant_tag=tenant.tenant_tag,
+            manifest_id=manifest.manifest_id,
+            label_release=manifest.label_release,
+            source_run_id=source_run_id,
+        )
+        path = f"/v1/runs/{_quote(run_id)}/cancel"
+
+        def post(client: customer_client.HostedClient, path: str = path) -> Mapping[str, object]:
+            return client.customer_post(path, {})
+
+        cancelled = _with_token(tenant, post)
+        status = cancelled.get("status")
+        rows.append(
+            {
+                "tenant_tag": tenant.tenant_tag,
+                "run_id": run_id,
+                "status": status if isinstance(status, str) else "unknown",
+            }
+        )
+        _log(args, "cancel", "ok", started=started, tenant_tag=tenant.tenant_tag, run_id=run_id)
+    _emit(args, {"runs": rows})
+    return 0
+
+
+def _status(args: argparse.Namespace) -> int:
+    started = time.perf_counter()
+    treatment = require_treatment(args.treatment)
+    k = require_k(args.k)
+    pins = _parsed_pins(args, None)
+    label = _input_label(args)
+    named = _optional_digest(getattr(args, "preprocessing_digest", None))
+    manifest = _load_manifest(require_manifest_id(args.corpus_manifest_id))
+    _require_scoped_preprocessing(manifest, named, "--preprocessing-digest")
+    rows: list[dict[str, object]] = []
+    for tenant in manifest.included:
+        active = _active_digest(tenant, named)
+        source_run_id = _latest_reusable_input(
+            tenant,
+            input_base=_input_base(manifest, tenant, label, named),
+            dataset_id=tenant.dataset_id,
+            version_id=tenant.version_id,
+            environment_id=tenant.environment_id,
+            workspace_id=tenant.workspace_id,
+            preprocessing_digest=active,
+        )
+        run_id = _treatment_id(
+            treatment,
+            manifest,
+            tenant,
+            k,
+            source_run_id,
+            pins,
+            labeled=label is not None,
+            input_base=_input_base(manifest, tenant, label, named),
+            preprocessing_digest=named,
+        )
+        run = _get_run(tenant, run_id)
+        by_state: dict[str, int] = {}
+        trace_refusals: dict[str, int] = {}
+        failure_reason = None
+        over_limit: list[str] = []
+        costs: list[object] = []
+        metadata = None if run is None else run.get("metadata")
+        if run is not None:
+            _refuse_mismatch(
+                run,
+                tenant,
+                dataset_id=tenant.dataset_id,
+                version_id=tenant.version_id,
+                samples=k,
+                preprocessing_digest=active,
+                criterion_versions=pins,
+                treatment=treatment,
+                tenant_tag=tenant.tenant_tag,
+                manifest_id=manifest.manifest_id,
+                label_release=manifest.label_release,
+                source_run_id=source_run_id,
+            )
+            failure_reason = (
+                metadata.get("failure_reason") if isinstance(metadata, Mapping) else None
+            )
+            refused = (
+                metadata.get("calibration_trace_refusals")
+                if isinstance(metadata, Mapping)
+                else None
+            )
+            if isinstance(refused, Mapping):
+                for reason in refused.values():
+                    if reason == "grade_result_too_large":
+                        trace_refusals[reason] = trace_refusals.get(reason, 0) + 1
+            status = run.get("status")
+            if status in {"pending", "running"} and isinstance(metadata, Mapping):
+                pinned_source = metadata.get("production_input_source_run_id")
+                if isinstance(pinned_source, str):
+                    source = _get_run(tenant, pinned_source)
+                    if source is not None and source.get("status") in {"pending", "running"}:
+                        status = "waiting"
+            if isinstance(status, str) and status:
+                by_state[status] = 1
+            rate = error_verdict_rate(_run_cases(tenant, run_id))
+            if error_rate_exceeds_limit(rate):
+                over_limit.append(run_id)
+            try:
+                usage = _customer_get(tenant, f"/v1/runs/{_quote(run_id)}/usage")
+            except customer_client.CustomerPlaneRequestError as exc:
+                if exc.status_code != 404:
+                    raise
+                costs.append(None)
+            else:
+                total = usage.get("total")
+                costs.append(total.get("cost_usd") if isinstance(total, Mapping) else None)
+        spend = spend_report(costs)
+        known_spend = spend["known_spend_usd"]
+        if known_spend is None and spend["runs_missing_cost"]:
+            known_spend = "cost unknown"
+        rows.append(
+            {
+                "tenant_tag": tenant.tenant_tag,
+                "by_state": by_state,
+                **(
+                    {
+                        key: metadata[key]
+                        for key in ("evidence_complete", "failure_stage")
+                        if key in metadata
+                    }
+                    if isinstance(metadata, Mapping)
+                    else {}
+                ),
+                **({"failure_reason": failure_reason} if failure_reason is not None else {}),
+                **({"trace_refusals": trace_refusals} if trace_refusals else {}),
+                "runs_over_error_limit": over_limit,
+                "known_spend_usd": known_spend,
+                "budget_usd": spend["budget_usd"],
+                "runs_missing_cost": spend["runs_missing_cost"],
+                "contributions_sent": "unknown",
+            }
+        )
+        _log(args, "status", "ok", started=started, tenant_tag=tenant.tenant_tag)
+    _emit(args, {"tenants": rows, "skipped_tenants": _skipped_rows(manifest)})
+    return 0
+
+
+def _candidate(args: argparse.Namespace) -> int:
+    started = time.perf_counter()
+    manifest = _load_manifest(require_manifest_id(args.corpus_manifest_id))
+    grader_id = args.grader_id
+    if not isinstance(grader_id, str) or not grader_id:
+        raise UsageError("--grader-id must be a non-empty string")
+    definition = _read_definition(args.definition)
+    if args.dry_run:
+        _emit(
+            args,
+            {
+                "dry_run": True,
+                "grader_id": grader_id,
+                "tenants": [{"tenant_tag": tenant.tenant_tag} for tenant in manifest.included],
+                "skipped_tenants": _skipped_rows(manifest),
+            },
+        )
+        return 0
+    confirm_write("This will store one calibration grader version on each included tenant.")
+    path = f"/v1/graders/{_quote(grader_id)}/versions"
+    rows: list[dict[str, str]] = []
+    for tenant in manifest.included:
+
+        def post(client: customer_client.HostedClient) -> Mapping[str, object]:
+            return client.customer_post(path, definition)
+
+        response = _with_token(tenant, post)
+        version_id = response.get("grader_version_id")
+        if not isinstance(version_id, str) or not version_id:
+            raise InvalidResponseError("the grader version response has no version id")
+        rows.append({"tenant_tag": tenant.tenant_tag, "grader_version_id": version_id})
+        _log(args, "candidate", "ok", started=started, tenant_tag=tenant.tenant_tag)
+    agreed = {row["grader_version_id"] for row in rows}
+    if len(agreed) > 1:
+        detail = ", ".join(f"{row['tenant_tag']}={row['grader_version_id']}" for row in rows)
+        raise ControlRefusedError(
+            "grader version ids differ, and every included tenant was already written: " + detail
+        )
+    version_id = rows[0]["grader_version_id"] if rows else None
+    _emit(
+        args,
+        {
+            "grader_version_id": version_id,
+            "tenants": [{"tenant_tag": row["tenant_tag"], "outcome": "stored"} for row in rows],
+            "skipped_tenants": _skipped_rows(manifest),
+        },
+    )
+    return 0
+
+
+def _show(args: argparse.Namespace) -> int:
+    treatment = require_treatment(args.treatment)
+    if args.tenant and getattr(args, "decider", None) is not None:
+        raise UsageError("--decider reads the pooled treatment; drop --tenant")
+    path = f"{_TREATMENTS_PATH}/{_quote(treatment)}"
+    if args.tenant:
+        tenant = require_treatment(args.tenant, label="tenant tag")
+        path = f"{path}/tenants/{_quote(tenant)}"
+    payload = _staff_get(path)
+    decider = getattr(args, "decider", None)
+    if decider is not None:
+        baseline = require_treatment(decider, label="--decider")
+        compared = _staff_get(
+            f"{_TREATMENTS_PATH}/{_quote(baseline)}/comparisons/{_quote(treatment)}"
+        )
+        gate = compared.get("decider_gate")
+        if not gate:
+            # A gate that names none of the baseline's runs compares plainly.
+            raise ControlRefusedError(f"no tenant's gate on {treatment} names a run of {baseline}")
+        payload = {**payload, "decider_gate": gate}
+    _warn_session_floor(payload)
+    _emit_read(payload, args)
+    return 0
+
+
+def _compare(args: argparse.Namespace) -> int:
+    baseline = require_treatment(args.baseline)
+    candidate = require_treatment(args.candidate, label="candidate treatment")
+    path = f"{_TREATMENTS_PATH}/{_quote(baseline)}/comparisons/{_quote(candidate)}"
+    params = {"basis": args.basis} if args.basis == "pre_audit" else None
+    payload = _staff_get(path, params)
+    _warn_session_floor(payload)
+    _emit_read(payload, args)
+    return 0
+
+
+class _ManifestTenant:
+    def __init__(
+        self,
+        *,
+        tenant_tag: str,
+        organization_id: str,
+        workspace_id: str,
+        environment_id: str,
+        dataset_id: str,
+        version_id: str,
+        preprocessing_digest: str | None,
+        input_setting_run_id: str | None,
+        session_count: int | None = None,
+        session_minimum_waived: bool = False,
+    ) -> None:
+        self.tenant_tag = tenant_tag
+        self.organization_id = organization_id
+        self.workspace_id = workspace_id
+        self.environment_id = environment_id
+        self.dataset_id = dataset_id
+        self.version_id = version_id
+        self.preprocessing_digest = preprocessing_digest
+        self.input_setting_run_id = input_setting_run_id
+        self.session_count = session_count
+        self.session_minimum_waived = session_minimum_waived
+
+
+class _Manifest:
+    def __init__(
+        self,
+        *,
+        manifest_id: str,
+        label_release: str,
+        included: list[_ManifestTenant],
+        skipped: list[str],
+        package_digest: str | None = None,
+    ) -> None:
+        self.manifest_id = manifest_id
+        self.label_release = label_release
+        self.included = included
+        self.skipped = skipped
+        self.package_digest = package_digest
+
+
+def _load_manifest(manifest_id: str) -> _Manifest:
+    context = _control()
+    quoted = urllib.parse.quote(manifest_id, safe="")
+    payload = control_client.get_control_json_at(
+        context.control_origin,
+        f"{_MANIFESTS_PATH}/{quoted}",
+        access_token=context.control_token,
+        transport=context.transport,
+    )
+    identities = control_client.get_control_json_list(
+        context.control_origin,
+        f"{_MANIFESTS_PATH}/{quoted}/tenants",
+        access_token=context.control_token,
+        transport=context.transport,
+    )
+    loaded = _manifest(payload, identities, manifest_id)
+    for tag in loaded.skipped:
+        print(
+            f"cv: warning: {tag} has no organization, workspace, and environment; skipping",
+            file=sys.stderr,
+        )
+    return loaded
+
+
+def _manifest(
+    payload: Mapping[str, object],
+    identities: list[object],
+    manifest_id: str,
+) -> _Manifest:
+    document = payload.get("manifest")
+    if not isinstance(document, Mapping):
+        raise InvalidResponseError("the corpus manifest response has no manifest")
+    label = document.get("label_release")
+    if not isinstance(label, str):
+        raise InvalidResponseError("the corpus manifest has no label release")
+    included = document.get("included")
+    if not isinstance(included, list):
+        raise InvalidResponseError("the corpus manifest has no included tenants")
+    by_tag = _identities(identities)
+    tenants: list[_ManifestTenant] = []
+    skipped: list[str] = []
+    for item in included:
+        if not isinstance(item, Mapping):
+            raise InvalidResponseError("an included tenant is malformed")
+        tag = _required_text(item, "tenant_tag")
+        identity = by_tag.get(tag)
+        if identity is None:
+            skipped.append(tag)
+            continue
+        digest = item.get("preprocessing_digest")
+        if digest is not None and not isinstance(digest, str):
+            raise InvalidResponseError(f"{tag} preprocessing digest is malformed")
+        tenants.append(
+            _ManifestTenant(
+                tenant_tag=tag,
+                organization_id=identity[0],
+                workspace_id=identity[1],
+                environment_id=identity[2],
+                dataset_id=_required_text(item, "eval_dataset_id"),
+                version_id=_required_text(item, "eval_dataset_version_id"),
+                preprocessing_digest=digest,
+                input_setting_run_id=_optional_run_id(item.get("input_setting_run_id")),
+                session_count=_optional_count(item.get("session_count")),
+                session_minimum_waived=item.get("session_minimum_waived") is True,
+            )
+        )
+    package = document.get("calibration_package_digest")
+    return _Manifest(
+        manifest_id=manifest_id,
+        label_release=require_label_release(label),
+        included=tenants,
+        skipped=skipped,
+        package_digest=None
+        if package is None
+        else require_digest(str(package), "manifest package"),
+    )
+
+
+def _optional_run_id(value: object) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, str) and value:
+        return value
+    raise InvalidResponseError("an included tenant input run id is malformed")
+
+
+def _optional_count(value: object) -> int | None:
+    if isinstance(value, bool) or not isinstance(value, int):
+        return None
+    return value
+
+
+def _warn(subject: str, session_count: int) -> None:
+    print(f"cv: {session_minimum_warning(subject, session_count)}", file=sys.stderr)
+
+
+def _warn_session_floor(payload: Mapping[str, object]) -> None:
+    """Warn for each tenant, or the pooled run, that the read shows under the floor."""
+    found: dict[str, int] = {}
+    tag = payload.get("tenant_tag")
+    run = payload.get("run")
+    if isinstance(run, Mapping):
+        subject = f"tenant {tag}" if isinstance(tag, str) else "the pooled result"
+        _keep_smallest(found, subject, _support_count(run.get("sample_support")))
+    for row in _mappings(payload.get("tenants")):
+        subject = f"tenant {row.get('tenant_tag')}"
+        _keep_smallest(found, subject, _optional_count(row.get("session_count")))
+        for side in ("baseline_support", "candidate_support"):
+            _keep_smallest(found, subject, _support_count(row.get(side)))
+    for subject, count in found.items():
+        if count < SESSION_MINIMUM:
+            _warn(subject, count)
+
+
+def _support_count(support: object) -> int | None:
+    if not isinstance(support, Mapping):
+        return None
+    return _optional_count(support.get("session_count"))
+
+
+def _keep_smallest(found: dict[str, int], subject: str, count: int | None) -> None:
+    if count is not None:
+        found[subject] = min(count, found.get(subject, count))
+
+
+def _skipped_rows(loaded: _Manifest) -> list[dict[str, str]]:
+    return [{"tenant_tag": tag, "reason": "no_identity"} for tag in loaded.skipped]
+
+
+def _identities(rows: list[object]) -> dict[str, tuple[str, str, str]]:
+    found: dict[str, tuple[str, str, str]] = {}
+    for item in rows:
+        if not isinstance(item, Mapping):
+            raise InvalidResponseError("a manifest tenant identity is malformed")
+        tag = _required_text(item, "tenant_tag")
+        found[tag] = (
+            _required_text(item, "organization_id"),
+            _required_text(item, "workspace_id"),
+            _required_text(item, "environment_id"),
+        )
+    return found
+
+
+def _required_text(item: Mapping[str, object], key: str) -> str:
+    value = item.get(key)
+    if not isinstance(value, str) or not value:
+        raise InvalidResponseError(f"the corpus manifest is missing {key}")
+    return value
+
+
+def _use_default_preprocessing(
+    loaded: _Manifest,
+    runtime: Mapping[str, object],
+    document: dict[str, object] | None,
+    computed: str | None,
+) -> tuple[dict[str, object] | None, str | None]:
+    if document is not None:
+        return document, computed
+    pin = resolved_runtime_pin(runtime)
+    default_digest = default_preprocessing_digest(pin)
+    pinned = [tenant.preprocessing_digest for tenant in loaded.included]
+    if all(item is None for item in pinned):
+        return None, None
+    if default_digest is not None and all(item == default_digest for item in pinned):
+        default_document = default_preprocessing_document(pin)
+        if default_document is None:
+            raise UsageError("the runtime pin has no default grader preprocessing")
+        print(
+            f"cv: using the runtime pin's default grader preprocessing {default_digest}",
+            file=sys.stderr,
+        )
+        return default_document, default_digest
+    named = ", ".join(item for item in pinned if item is not None)
+    raise UsageError(
+        f"manifest preprocessing digest {named} does not match the runtime pin's "
+        f"default {default_digest}. Pass --grader-preprocessing with the document "
+        f"whose digest is {named}."
+    )
+
+
+def _treatment_scoped_manifest(loaded: _Manifest) -> bool:
+    return bool(loaded.included) and all(
+        tenant.input_setting_run_id is None and tenant.preprocessing_digest is None
+        for tenant in loaded.included
+    )
+
+
+def _require_scoped_preprocessing(loaded: _Manifest, digest: str | None, flag: str) -> None:
+    if _treatment_scoped_manifest(loaded) and digest is None:
+        raise UsageError(f"a treatment-scoped manifest needs {flag}")
+
+
+def _agree_preprocessing(loaded: _Manifest, computed: str | None) -> None:
+    if _treatment_scoped_manifest(loaded):
+        _require_scoped_preprocessing(loaded, computed, "--grader-preprocessing")
+        return
+    for tenant in loaded.included:
+        if tenant.preprocessing_digest != computed:
+            raise UsageError(
+                f"{tenant.tenant_tag} preprocessing digest does not match --grader-preprocessing"
+            )
+
+
+def _grading_document(
+    args: argparse.Namespace,
+) -> tuple[dict[str, object], list[str], dict[str, object] | None, str | None]:
+    runtime = require_json_object(
+        _json_object(args.platform_grader_runtime, "platform grader runtime"),
+        "platform grader runtime",
+    )
+    criterion_ids = list(args.criterion_id or [])
+    if not criterion_ids:
+        raise UsageError("production grading needs at least one --criterion-id")
+    document, computed = _document_digest(args)
+    return runtime, criterion_ids, document, computed
+
+
+def _document_digest(args: argparse.Namespace) -> tuple[dict[str, object] | None, str | None]:
+    raw = getattr(args, "grader_preprocessing", None)
+    flag = _optional_digest(getattr(args, "preprocessing_digest", None))
+    if raw is None:
+        if flag is not None:
+            raise UsageError("a preprocessing digest needs --grader-preprocessing")
+        return None, None
+    document = require_json_object(
+        _json_object(raw, "grader preprocessing"),
+        "grader preprocessing",
+    )
+    computed = preprocessing_digest(document)
+    if flag is not None and flag != computed:
+        raise UsageError("--preprocessing-digest does not match --grader-preprocessing")
+    return document, computed
+
+
+def _plan_tenant(
+    tenant: TenantSpec, *, eligible: bool, allow_waiver: bool
+) -> tuple[dict[str, object], int]:
+    if not eligible or tenant.dataset_id is None:
+        reason = exclusion_reason(
+            eligible=eligible,
+            dataset_id=tenant.dataset_id,
+            dataset_missing=False,
+            session_count=None,
+        )
+        return {"tenant_tag": tenant.tenant_tag, "reason": reason}, 0
+    try:
+        version_id, task_count = _dataset_version(tenant)
+    except customer_client.CustomerPlaneRequestError as exc:
+        if exc.status_code != 404:
+            raise
+        return {"tenant_tag": tenant.tenant_tag, "reason": "no_dataset"}, 0
+    session_count = _session_count(tenant, version_id)
+    waived = session_minimum_waived(session_count, allowed=allow_waiver)
+    reason = None
+    if not waived:
+        reason = exclusion_reason(
+            eligible=True,
+            dataset_id=tenant.dataset_id,
+            dataset_missing=False,
+            session_count=session_count,
+        )
+    row: dict[str, object] = {
+        "tenant_tag": tenant.tenant_tag,
+        "dataset_version_id": version_id,
+        "session_count": session_count,
+        "trace_count": task_count,
+    }
+    if waived:
+        row["session_minimum"] = "waived"
+        _warn(f"tenant {tenant.tenant_tag}", session_count)
+    if reason is None:
+        return row, task_count
+    row["reason"] = reason
+    return row, 0
+
+
+def _dataset_version(tenant: TenantSpec) -> tuple[str, int]:
+    payload = _customer_get(tenant, f"/v1/eval-datasets/{_quote(_dataset_id(tenant))}")
+    dataset = payload.get("dataset")
+    if not isinstance(dataset, Mapping):
+        raise InvalidResponseError("the dataset response has no dataset")
+    version_id = dataset.get("current_version_id")
+    if not isinstance(version_id, str) or not version_id:
+        raise InvalidResponseError("the dataset response has no current version")
+    task_count = dataset.get("task_count")
+    if isinstance(task_count, bool) or not isinstance(task_count, int) or task_count < 0:
+        raise InvalidResponseError("the dataset response has no task count")
+    return version_id, task_count
+
+
+def _session_count(tenant: TenantSpec, version_id: str) -> int:
+    payload = _customer_get(
+        tenant,
+        f"/v1/eval-datasets/{_quote(_dataset_id(tenant))}/calibration-session-count",
+        {"eval_dataset_version_id": version_id},
+    )
+    count = payload.get("session_count")
+    if isinstance(count, bool) or not isinstance(count, int) or count < 0:
+        raise InvalidResponseError("the session count response has no session count")
+    if set(payload) != {"session_count"}:
+        raise InvalidResponseError("the session count response has more than the count")
+    return count
+
+
+def _next_input_attempt(
+    tenant: _ManifestTenant,
+    *,
+    input_base: str,
+    **expected: Any,
+) -> tuple[str, Mapping[str, object] | None]:
+    attempt = 1
+    while not input_attempt_exhausted(attempt):
+        run_id = attempt_run_id(input_base, attempt)
+        run = _get_run(tenant, run_id)
+        if run is None:
+            return run_id, None
+        _refuse_mismatch(run, tenant, samples=1, **expected)
+        if input_run_is_reusable(run):
+            return run_id, run
+        attempt += 1
+    raise UsageError(f"{tenant.tenant_tag} has no free input-setting attempt")
+
+
+def _latest_reusable_input(
+    tenant: _ManifestTenant,
+    *,
+    input_base: str,
+    **expected: Any,
+) -> str:
+    attempt = 1
+    found: str | None = None
+    while not input_attempt_exhausted(attempt):
+        run_id = attempt_run_id(input_base, attempt)
+        run = _get_run(tenant, run_id)
+        if run is None:
+            break
+        _refuse_mismatch(run, tenant, samples=1, **expected)
+        if input_run_is_reusable(run):
+            found = run_id
+        attempt += 1
+    if found is None:
+        raise UsageError(f"{tenant.tenant_tag} has no input-setting run for this preprocessing")
+    return found
+
+
+class _FailedInputConflict(Exception):
+    """The id from a 409 is a failed or cancelled input-setting run."""
+
+
+def _create_or_reuse(
+    tenant: _ManifestTenant,
+    body: Mapping[str, object],
+    **expected: Any,
+) -> tuple[str, bool]:
+    run_id = body.get("run_id")
+    if not isinstance(run_id, str):
+        raise UsageError("the run id is missing")
+
+    def post(client: customer_client.HostedClient) -> Mapping[str, object]:
+        return client.customer_post("/v1/runs", body, idempotency_key=run_id)
+
+    try:
+        response = _with_token(tenant, post)
+    except customer_client.CustomerPlaneConflictError:
+        found = _get_run(tenant, run_id)
+        if found is None:
+            raise
+        _refuse_mismatch(found, tenant, **expected)
+        if expected.get("treatment") is None and not input_run_is_reusable(found):
+            raise _FailedInputConflict from None
+        return run_id, False
+    created = response.get("run_id")
+    if not isinstance(created, str) or not created:
+        raise InvalidResponseError("the created run has no run id")
+    return created, True
+
+
+def _refuse_mismatch(
+    run: Mapping[str, object],
+    tenant: _ManifestTenant,
+    **expected: Any,
+) -> None:
+    mismatch = run_request_mismatch(
+        run,
+        dataset_id=expected["dataset_id"],
+        version_id=expected["version_id"],
+        environment_id=tenant.environment_id,
+        workspace_id=tenant.workspace_id,
+        samples=expected["samples"],
+        preprocessing_digest=expected.get("preprocessing_digest"),
+        runtime=expected.get("runtime"),
+        preprocessing=expected.get("preprocessing"),
+        criterion_ids=expected.get("criterion_ids"),
+        treatment=expected.get("treatment"),
+        tenant_tag=expected.get("tenant_tag"),
+        manifest_id=expected.get("manifest_id"),
+        label_release=expected.get("label_release"),
+        source_run_id=expected.get("source_run_id"),
+        criterion_versions=expected.get("criterion_versions"),
+    )
+    if mismatch is None:
+        return
+    if mismatch == "treatment" and expected.get("treatment") is None:
+        raise UsageError(
+            f"{tenant.tenant_tag} input-setting run {_run_id(run)} is a treatment run. "
+            "Register a manifest with a fresh input-setting run id."
+        )
+    raise UsageError(
+        f"{tenant.tenant_tag} run {_run_id(run)} does not match this request ({mismatch})"
+    )
+
+
+def _resolve_treatment_run(
+    treatment: str,
+    manifest: _Manifest,
+    tenant: _ManifestTenant,
+    k: int,
+    pins: Mapping[str, str],
+    label: str | None,
+    named: str | None,
+) -> tuple[str, str, Mapping[str, object] | None]:
+    active = _active_digest(tenant, named)
+    source_run_id = _latest_reusable_input(
+        tenant,
+        input_base=_input_base(manifest, tenant, label, named),
+        dataset_id=tenant.dataset_id,
+        version_id=tenant.version_id,
+        environment_id=tenant.environment_id,
+        workspace_id=tenant.workspace_id,
+        preprocessing_digest=active,
+    )
+    run_id = _treatment_id(
+        treatment,
+        manifest,
+        tenant,
+        k,
+        source_run_id,
+        pins,
+        labeled=label is not None,
+        input_base=_input_base(manifest, tenant, label, named),
+        preprocessing_digest=named,
+    )
+    run = _get_run(tenant, run_id)
+    return source_run_id, run_id, run
+
+
+def _treatment_id(
+    treatment: str,
+    manifest: _Manifest,
+    tenant: _ManifestTenant,
+    k: int,
+    source_run_id: str,
+    pins: Mapping[str, str] | None = None,
+    *,
+    labeled: bool = False,
+    input_base: str | None = None,
+    preprocessing_digest: str | None = None,
+) -> str:
+    # Attempt 1 of a labeled input omits the source so any later label finds
+    # that run. A later input attempt is its own id, so it is not attempt 1.
+    if labeled:
+        source_key = _labeled_attempt_key(input_base or source_run_id, source_run_id)
+    else:
+        source_key = source_run_id
+    if tenant.input_setting_run_id is None:
+        digest_part = preprocessing_digest or ""
+    else:
+        digest_part = tenant.preprocessing_digest or ""
+    parts = [
+        treatment,
+        tenant.tenant_tag,
+        manifest.manifest_id,
+        manifest.label_release,
+        str(k),
+        source_key,
+        digest_part,
+    ]
+    if pins:
+        parts.append(",".join(f"{criterion}={pins[criterion]}" for criterion in sorted(pins)))
+    return stable_run_id("treatment", parts)
+
+
+def _labeled_attempt_key(input_base: str, source_run_id: str) -> str:
+    attempt = 1
+    while not input_attempt_exhausted(attempt):
+        if source_run_id == attempt_run_id(input_base, attempt):
+            if attempt == 1:
+                return "labeled"
+            return f"labeled_{attempt}"
+        attempt += 1
+    return "labeled"
+
+
+def _get_run(tenant: TenantSpec | _ManifestTenant, run_id: str) -> Mapping[str, object] | None:
+    def get(client: customer_client.HostedClient) -> Mapping[str, object]:
+        return client.customer_get(f"/v1/runs/{_quote(run_id)}")
+
+    try:
+        return _with_token(tenant, get)
+    except customer_client.CustomerPlaneRequestError as exc:
+        if exc.status_code == 404:
+            return None
+        raise
+
+
+def _bound_input_source(run: Mapping[str, object], fallback: str) -> str:
+    metadata = run.get("metadata")
+    if isinstance(metadata, Mapping):
+        source = metadata.get("production_input_source_run_id")
+        if isinstance(source, str) and source:
+            return source
+    return fallback
+
+
+def _refuse_treatment_bound_elsewhere(
+    treatment: str,
+    manifest: _Manifest,
+    k: int,
+    pins: Mapping[str, str] | None,
+    label: str | None,
+    named: str | None = None,
+) -> None:
+    """A treatment name already accepted on another input cannot be reused."""
+    for tenant in manifest.included:
+        requested = _input_base(manifest, tenant, label, named)
+        if tenant.input_setting_run_id is not None and requested != tenant.input_setting_run_id:
+            _refuse_bound_base_attempt(treatment, manifest, tenant, k, pins, named)
+        _refuse_bound_labeled_input(treatment, manifest, tenant, k, pins, requested, named)
+
+
+def _refuse_bound_base_attempt(
+    treatment: str,
+    manifest: _Manifest,
+    tenant: _ManifestTenant,
+    k: int,
+    pins: Mapping[str, str] | None,
+    named: str | None,
+) -> None:
+    """Name a treatment already stored on a base attempt, including ``_2`` and later."""
+    stored = tenant.input_setting_run_id
+    if stored is None:
+        return
+    attempt = 1
+    while not input_attempt_exhausted(attempt):
+        source = attempt_run_id(stored, attempt)
+        existing = _get_run(
+            tenant,
+            _treatment_id(
+                treatment,
+                manifest,
+                tenant,
+                k,
+                source,
+                pins,
+                preprocessing_digest=named,
+            ),
+        )
+        if existing is not None:
+            raise UsageError(
+                f"{treatment} is bound to input run {_bound_input_source(existing, source)}"
+            )
+        if _get_run(tenant, source) is None:
+            return
+        attempt += 1
+
+
+def _refuse_bound_labeled_input(
+    treatment: str,
+    manifest: _Manifest,
+    tenant: _ManifestTenant,
+    k: int,
+    pins: Mapping[str, str] | None,
+    requested: str,
+    named: str | None,
+) -> None:
+    """Name a treatment already stored on any label, including a later attempt."""
+    attempt = 1
+    while not input_attempt_exhausted(attempt):
+        source = attempt_run_id(requested, attempt)
+        existing = _get_run(
+            tenant,
+            _treatment_id(
+                treatment,
+                manifest,
+                tenant,
+                k,
+                source,
+                pins,
+                labeled=True,
+                input_base=requested,
+                preprocessing_digest=named,
+            ),
+        )
+        if existing is not None:
+            bound = _bound_input_source(existing, "")
+            if bound and not _is_requested_input(bound, requested):
+                raise UsageError(f"{treatment} is bound to input run {bound}")
+        attempt += 1
+
+
+def _is_requested_input(source: str, requested: str) -> bool:
+    attempt = 1
+    while not input_attempt_exhausted(attempt):
+        if source == attempt_run_id(requested, attempt):
+            return True
+        attempt += 1
+    return False
+
+
+def _customer_get(
+    tenant: TenantSpec | _ManifestTenant,
+    path: str,
+    params: Mapping[str, str] | None = None,
+) -> Mapping[str, object]:
+    def get(client: customer_client.HostedClient) -> Mapping[str, object]:
+        return client.customer_get(path, params=params)
+
+    return _with_token(tenant, get)
+
+
+def _run_cases(tenant: _ManifestTenant, run_id: str) -> dict[str, object]:
+    page = _customer_get(tenant, f"/v1/runs/{_quote(run_id)}/cases")
+    counts = page.get("verdict_counts")
+    if not isinstance(counts, Mapping):
+        raise InvalidResponseError("the case list has no verdict counts")
+    if page.get("cases") not in (None, []):
+        raise InvalidResponseError("the case list included case rows")
+    return {"verdict_counts": counts}
+
+
+def _is_read_timeout(exc: BaseException) -> bool:
+    current: BaseException | None = exc
+    seen: set[int] = set()
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        if isinstance(current, TimeoutError):
+            return True
+        reason = getattr(current, "reason", None)
+        if isinstance(reason, TimeoutError):
+            return True
+        current = current.__cause__
+    return False
+
+
+def _send_contribution(
+    tenant: _ManifestTenant,
+    run_id: str,
+    treatment: str,
+    gate_baseline_run_id: str | None = None,
+    *,
+    ungated: bool = False,
+    deadline: SendDeadline | None = None,
+    cancelled: Callable[[], bool] | None = None,
+) -> tuple[str, str | None]:
+    path = f"/v1/eval-runs/{_quote(run_id)}/calibration-contribution"
+    body: dict[str, object] = {}
+    if gate_baseline_run_id is not None:
+        body["gate_baseline_run_id"] = gate_baseline_run_id
+    if ungated:
+        body["ungated"] = True
+
+    def post(client: customer_client.HostedClient) -> Mapping[str, object]:
+        if cancelled is not None and cancelled():
+            raise CancelledError
+        timeout = _CONTRIBUTION_READ_TIMEOUT_SECONDS
+        if deadline is not None:
+            timeout = min(timeout, deadline.remaining())
+        return client.customer_post(path, body, timeout=timeout)
+
+    try:
+        response = _with_token(tenant, post)
+    except customer_client.CustomerPlaneRequestError as exc:
+        if _is_read_timeout(exc) or (exc.status_code is not None and exc.status_code >= 500):
+            return "sending", None
+        if exc.status_code != 422:
+            raise
+        return contribution_receipt(
+            status_code=exc.status_code, outcome=None, message=str(exc), code=exc.code
+        )
+    except TimeoutError:
+        return "sending", None
+    if "state" in response:
+        return _send_status(response)
+    outcome = response.get("outcome")
+    if not isinstance(outcome, str):
+        raise InvalidResponseError("the contribution response has no outcome")
+    if response.get("gate_baseline_run_id") != gate_baseline_run_id:
+        # A customer-api that ignores the body stored this run ungated, and the
+        # first send is final. Stop before another tenant is locked the same way.
+        raise InvalidResponseError(
+            f"the contribution for run {run_id} was not stored with the gate baseline it "
+            "named, so this customer-api cannot gate it. Upgrade it, then declare a new "
+            "treatment."
+        )
+    return contribution_receipt(status_code=200, outcome=outcome, message=None)
+
+
+def _send_status(response: Mapping[str, object]) -> tuple[str, str | None]:
+    state = response.get("state")
+    if state not in {"sending", "counting", "stored", "duplicate", "refused"}:
+        raise InvalidResponseError("the contribution response has no valid state")
+    reason = response.get("reason")
+    if state == "refused" and not isinstance(reason, str):
+        raise InvalidResponseError("the refused contribution has no reason")
+    exception_type = response.get("exception_type")
+    if (
+        state == "refused"
+        and reason == "error"
+        and isinstance(exception_type, str)
+        and re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]{0,127}", exception_type)
+    ):
+        reason = f"error ({exception_type})"
+    return str(state), reason if isinstance(reason, str) else None
+
+
+def _poll_contribution(
+    tenant: _ManifestTenant,
+    run_id: str,
+    *,
+    deadline: SendDeadline | None = None,
+) -> tuple[str, str | None]:
+    path = f"/v1/eval-runs/{_quote(run_id)}/calibration-contribution"
+    try:
+
+        def get(client: customer_client.HostedClient) -> Mapping[str, object]:
+            timeout = min(15.0, deadline.remaining()) if deadline is not None else None
+            return client.customer_get(path, timeout=timeout)
+
+        response = _with_token(tenant, get)
+    except customer_client.CustomerPlaneRequestError as exc:
+        if exc.status_code == 404:
+            return "refused", "send_not_requested"
+        if _is_read_timeout(exc) or (exc.status_code is not None and exc.status_code >= 500):
+            return "sending", None
+        raise
+    except TimeoutError:
+        return "sending", None
+    return _send_status(response)
+
+
+def _with_token[Result](
+    tenant: TenantSpec | _ManifestTenant,
+    call: Callable[[customer_client.HostedClient], Result],
+) -> Result:
+    """Call with this tenant's calibration token. A 401 mints once more, then repeats."""
+    try:
+        return call(_calibration_client(tenant))
+    except customer_client.CustomerPlaneRefusedError as exc:
+        if exc.status_code != 401:
+            raise
+    return call(_calibration_client(tenant, refresh=True))
+
+
+def _run_body(
+    *,
+    dataset_id: str,
+    version_id: str,
+    environment_id: str,
+    run_id: str,
+    samples: int,
+    runtime: Mapping[str, object],
+    criterion_ids: Sequence[str],
+    preprocessing: Mapping[str, object] | None,
+    criterion_versions: Mapping[str, str] | None = None,
+    source_run_id: str | None = None,
+    treatment: str | None = None,
+    tenant_tag: str | None = None,
+    manifest_id: str | None = None,
+    label_release: str | None = None,
+    session_minimum_waived: bool = False,
+    carry_forward_run_id: str | None = None,
+    package: str | None = None,
+) -> dict[str, object]:
+    grading: dict[str, object] = {
+        "runtime": dict(runtime),
+        "criterion_ids": list(criterion_ids),
+    }
+    if criterion_versions:
+        grading["criterion_versions"] = {
+            criterion: criterion_versions[criterion] for criterion in sorted(criterion_versions)
+        }
+    if source_run_id is not None:
+        grading["source_run_id"] = source_run_id
+    if preprocessing is not None:
+        grading["preprocessing"] = dict(preprocessing)
+    if carry_forward_run_id is not None:
+        grading["carry_forward_run_id"] = carry_forward_run_id
+    body: dict[str, object] = {
+        "eval_dataset_id": dataset_id,
+        "eval_dataset_version_id": version_id,
+        "environment_id": environment_id,
+        "run_id": run_id,
+        "purpose": "calibration",
+        "samples_per_task": samples,
+        "production_grading": grading,
+    }
+    if treatment is not None:
+        body["calibration_treatment"] = treatment
+        body["calibration_tenant_tag"] = tenant_tag
+        body["calibration_corpus_manifest_id"] = manifest_id
+        body["calibration_label_release"] = label_release
+        if session_minimum_waived:
+            body["calibration_session_minimum_waived"] = True
+    if package is not None:
+        body["calibration_package_digest"] = package
+    return body
+
+
+def _organizations(payload: Mapping[str, object]) -> list[dict[str, str]]:
+    raw = payload.get("organizations")
+    if not isinstance(raw, list):
+        raise InvalidResponseError("eligible organizations response has no organizations list")
+    rows: list[dict[str, str]] = []
+    for index, item in enumerate(raw):
+        if not isinstance(item, Mapping):
+            raise InvalidResponseError(f"eligible organizations row {index} is malformed")
+        organization_id = item.get("organization_id")
+        name = item.get("name")
+        if not isinstance(organization_id, str) or not isinstance(name, str):
+            raise InvalidResponseError(
+                f"eligible organizations row {index} is missing an id or name"
+            )
+        rows.append({"organization_id": organization_id, "name": name})
+    return rows
+
+
+def _calibration_client(
+    tenant: TenantSpec | _ManifestTenant,
+    *,
+    refresh: bool = False,
+) -> customer_client.HostedClient:
+    return customer_client.HostedClient.for_calibration(
+        organization_id=tenant.organization_id,
+        workspace_id=tenant.workspace_id,
+        refresh=refresh,
+    )
+
+
+def _control() -> Any:
+    return customer_client._active_control_context(transport=None, now=None)
+
+
+def _run_id(run: Mapping[str, object]) -> str:
+    run_id = run.get("run_id")
+    if not isinstance(run_id, str) or not run_id:
+        raise InvalidResponseError("a run is missing its run id")
+    return run_id
+
+
+def _dataset_id(tenant: TenantSpec) -> str:
+    if tenant.dataset_id is None:
+        raise UsageError(f"{tenant.tenant_tag} needs a dataset id")
+    return tenant.dataset_id
+
+
+def _optional_digest(value: str | None) -> str | None:
+    if value is None:
+        return None
+    return require_digest(value, "preprocessing digest")
+
+
+def _json_object(raw: str, label: str) -> object:
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise UsageError(f"{label} must be a JSON object") from exc
+
+
+def _quote(value: str) -> str:
+    return urllib.parse.quote(value, safe="")
+
+
+def _log(
+    args: argparse.Namespace,
+    step: str,
+    outcome: str,
+    *,
+    started: float,
+    tenant_tag: str | None = None,
+    run_id: str | None = None,
+    reason: str | None = None,
+) -> None:
+    if not args.log_steps:
+        return
+    event = step_event(
+        step=step,
+        outcome=outcome,
+        duration_seconds=round(time.perf_counter() - started, 6),
+        tenant_tag=tenant_tag,
+        run_id=run_id,
+        reason=reason,
+    )
+    print(json.dumps(event, sort_keys=True), file=sys.stderr)
+
+
+def _emit(args: argparse.Namespace, payload: Mapping[str, object]) -> None:
+    if args.format == "json":
+        emit_json(dict(payload))
+        return
+    print(_human(payload), end="")
+
+
+def _human(payload: Mapping[str, object]) -> str:
+    lines: list[str] = []
+    manifest_id = payload.get("corpus_manifest_id")
+    if isinstance(manifest_id, str):
+        lines.append(f"corpus_manifest_id={manifest_id}")
+    repeat = payload.get("repeat_note")
+    if isinstance(repeat, str):
+        lines.append(repeat)
+    document = payload.get("document")
+    if isinstance(document, Mapping):
+        lines.extend(_manifest_document_lines(document))
+    organizations = payload.get("organizations")
+    if isinstance(organizations, list):
+        lines.append(f"Eligible organizations: {len(organizations)}")
+        for row in organizations:
+            if isinstance(row, Mapping):
+                lines.append(f"  {row.get('organization_id')}  {row.get('name')}")
+    tenants = payload.get("tenants")
+    if isinstance(tenants, list):
+        for row in tenants:
+            if isinstance(row, Mapping):
+                lines.append("  ".join(f"{key}={row.get(key)}" for key in row))
+    skipped = payload.get("skipped_tenants")
+    if isinstance(skipped, list):
+        for row in skipped:
+            if isinstance(row, Mapping):
+                lines.append(
+                    f"skipped tenant_tag={row.get('tenant_tag')} reason={row.get('reason')}"
+                )
+    receipts = payload.get("receipts")
+    if isinstance(receipts, list):
+        for row in receipts:
+            if isinstance(row, Mapping):
+                lines.append("  ".join(f"{key}={row.get(key)}" for key in row))
+    estimate_row = payload.get("estimate")
+    if isinstance(estimate_row, Mapping):
+        lines.append(
+            "estimate " + " ".join(f"{key}={estimate_row.get(key)}" for key in estimate_row)
+        )
+    expected = payload.get("expected_count")
+    if isinstance(expected, int):
+        lines.append(f"expected_count={expected}")
+    note = payload.get("busy_scope_note")
+    if isinstance(note, str):
+        lines.append(note)
+    if not lines:
+        return json.dumps(dict(payload), indent=2, sort_keys=True) + "\n"
+    return "\n".join(lines) + "\n"
+
+
+def _manifest_document_lines(document: Mapping[str, object]) -> list[str]:
+    lines: list[str] = []
+    included = document.get("included")
+    if isinstance(included, list):
+        for row in included:
+            if isinstance(row, Mapping):
+                lines.append("included " + " ".join(f"{key}={row.get(key)}" for key in row))
+    excluded = document.get("excluded")
+    if isinstance(excluded, list):
+        for row in excluded:
+            if isinstance(row, Mapping):
+                lines.append(
+                    f"excluded tenant_tag={row.get('tenant_tag')} reason={row.get('reason')}"
+                )
+    return lines
+
+
+def _bind(
+    catalog: CommandCatalog,
+    parser: argparse.ArgumentParser,
+    handler: Any,
+    path: tuple[str, ...],
+    description: str,
+    effect: Effect,
+    *,
+    tenants: bool = False,
+    manifest: bool = False,
+    treatment: bool = False,
+    grading: bool = False,
+    k: bool = False,
+    k_default: int | None = None,
+    preprocessing_body: bool = False,
+    criterion_versions: bool = False,
+    input_label: bool = False,
+    preprocessing_digest: bool = False,
+    gate: bool = False,
+    send_timeout: bool = False,
+) -> None:
+    if tenants:
+        parser.add_argument(
+            "--tenant",
+            action="append",
+            help=(
+                "tag,organization_id,workspace_id,environment_id[,dataset_id]. "
+                "Repeat for each tenant. Only plan takes this, before a manifest exists."
+            ),
+        )
+    if treatment:
+        _add_treatment(parser)
+    if manifest:
+        _add_manifest(parser)
+    if grading:
+        _add_runtime(parser)
+        parser.add_argument(
+            "--criterion-id",
+            action="append",
+            required=True,
+            help="Production grading criterion. Repeat for each one.",
+        )
+    if preprocessing_body:
+        parser.add_argument(
+            "--grader-preprocessing",
+            help="JSON object for grader preprocessing. The digest is computed from this.",
+        )
+        _add_preprocessing_digest(parser)
+    if k or k_default is not None:
+        _add_k(parser, default=k_default)
+    if criterion_versions:
+        _add_criterion_version(parser)
+    if input_label:
+        _add_input_label(parser)
+    if preprocessing_digest:
+        _add_preprocessing_digest(parser)
+    if gate:
+        _add_gate(parser)
+    if send_timeout:
+        parser.add_argument(
+            "--send-timeout",
+            type=send_timeout_seconds,
+            default=DEFAULT_SEND_TIMEOUT_SECONDS,
+            metavar="SECONDS",
+            help="Send-phase deadline in seconds. Defaults to 600 (10 minutes).",
+        )
+    _add_format(parser)
+    plane = Plane.CONTROL if path == ("calibration", "plan") else Plane.CUSTOMER
+    _bind_parser(catalog, parser, handler, path, description, effect, plane)
+
+
+def _bind_parser(
+    catalog: CommandCatalog,
+    parser: argparse.ArgumentParser,
+    handler: Any,
+    path: tuple[str, ...],
+    description: str,
+    effect: Effect,
+    plane: Plane,
+) -> None:
+    catalog.bind(
+        parser=parser,
+        handler=handler,
+        info=CommandInfo(
+            path=path,
+            description=description,
+            plane=plane,
+            requires_session=True,
+            effect=effect,
+        ),
+    )
+
+
+def _add_session_minimum_waiver(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--allow-below-session-minimum",
+        action="store_true",
+        help=(
+            "Include a tenant with 1 to 14 independent root sessions and record the waiver "
+            "in the manifest. The control plane accepts the waiver only on staging."
+        ),
+    )
+
+
+def _add_treatment(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--treatment", required=True, help="Treatment name, such as treatment_a.")
+
+
+def _add_input_label(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--input-label",
+        help=(
+            "Name an additional input-setting run. Its id is the manifest input id "
+            "plus this label. Omit it to use the manifest's input run."
+        ),
+    )
+
+
+def _input_label(args: argparse.Namespace) -> str | None:
+    raw = getattr(args, "input_label", None)
+    if raw is None:
+        return None
+    return require_input_label(raw)
+
+
+def _active_digest(tenant: _ManifestTenant, named: str | None) -> str | None:
+    if tenant.input_setting_run_id is None:
+        return named
+    return tenant.preprocessing_digest
+
+
+def _input_base(
+    manifest: _Manifest,
+    tenant: _ManifestTenant,
+    label: str | None,
+    named: str | None,
+) -> str:
+    stored = tenant.input_setting_run_id
+    if stored is None:
+        stored = default_input_setting_run_id(
+            manifest.label_release,
+            tenant.tenant_tag,
+            eval_dataset_version_id=tenant.version_id,
+            preprocessing_digest=named,
+        )
+    return labeled_input_run_id(stored, label)
+
+
+def _add_manifest(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--corpus-manifest-id", required=True, help="64 hex corpus manifest id.")
+
+
+def _add_preprocessing_digest(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--preprocessing-digest",
+        help="64 hex preprocessing digest. It must match --grader-preprocessing when both are set.",
+    )
+
+
+def _add_runtime(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--platform-grader-runtime",
+        required=True,
+        help="JSON object for the production grader runtime.",
+    )
+
+
+def _add_k(parser: argparse.ArgumentParser, *, default: int | None) -> None:
+    parser.add_argument(
+        "--k",
+        type=int,
+        required=default is None,
+        default=default,
+        help="Samples per task, from 1 to 30.",
+    )
+
+
+def _parsed_pins(
+    args: argparse.Namespace,
+    criterion_ids: Sequence[str] | None,
+) -> dict[str, str]:
+    raw_pins = getattr(args, "criterion_version", None)
+    parsed_pins = _criterion_versions(raw_pins if isinstance(raw_pins, list) else None)
+    pins = {} if parsed_pins is None else parsed_pins
+    if criterion_ids is None:
+        return pins
+    outside = [criterion for criterion in pins if criterion not in criterion_ids]
+    if outside:
+        raise UsageError(
+            "--criterion-version pins " + ", ".join(outside) + ", which is not among --criterion-id"
+        )
+    return pins
+
+
+@dataclass(frozen=True)
+class _DeclarationIdentity:
+    suite_digest: str
+    runtime: dict[str, object]
+    preprocessing_digest: str | None
+
+
+def _declaration_preprocessing_digest(manifest: _Manifest, named: str | None) -> str | None:
+    if _treatment_scoped_manifest(manifest):
+        _require_scoped_preprocessing(manifest, named, "--preprocessing-digest")
+        return named
+    recorded = {tenant.preprocessing_digest for tenant in manifest.included}
+    if len(recorded) != 1:
+        tags = ", ".join(tenant.tenant_tag for tenant in manifest.included)
+        raise UsageError(f"preprocessing_digest_mismatch: tenants disagree ({tags})")
+    return recorded.pop()
+
+
+def _resolved_declaration_runtime(
+    run: Mapping[str, object],
+    supplied: Mapping[str, object],
+    tag: str,
+) -> dict[str, object]:
+    metadata = run.get("metadata")
+    stored = metadata.get("platform_grader_runtime") if isinstance(metadata, Mapping) else None
+    preprocessing = run.get("grader_preprocessing")
+    try:
+        expected = resolved_runtime_pin(
+            supplied, preprocessing if isinstance(preprocessing, Mapping) else None
+        )
+    except UsageError as exc:
+        raise UsageError(f"runtime_pin_mismatch: {tag}") from exc
+    if stored != expected:
+        raise UsageError(f"runtime_pin_mismatch: {tag}")
+    return expected
+
+
+def _recorded_declaration(
+    treatment: str,
+    manifest_id: str,
+    k: int,
+    pins: Mapping[str, str],
+    *,
+    input_label: str | None = None,
+    preprocessing_digest: str | None = None,
+    runtime: Mapping[str, object],
+) -> _DeclarationIdentity:
+    manifest = _load_manifest(manifest_id)
+    _require_scoped_preprocessing(manifest, preprocessing_digest, "--preprocessing-digest")
+    _refuse_treatment_bound_elsewhere(
+        treatment, manifest, k, pins, input_label, preprocessing_digest
+    )
+    found: list[tuple[str, str]] = []
+    runtimes: list[dict[str, object]] = []
+    for tenant in manifest.included:
+        active = _active_digest(tenant, preprocessing_digest)
+        source_run_id, run_id, run = _resolve_treatment_run(
+            treatment, manifest, tenant, k, pins, input_label, preprocessing_digest
+        )
+        if run is None:
+            raise UsageError(
+                f"{tenant.tenant_tag} has no treatment run; run treat and wait until it finishes"
+            )
+        _refuse_mismatch(
+            run,
+            tenant,
+            dataset_id=tenant.dataset_id,
+            version_id=tenant.version_id,
+            samples=k,
+            preprocessing_digest=active,
+            criterion_versions=dict(pins) if pins else None,
+            treatment=treatment,
+            tenant_tag=tenant.tenant_tag,
+            manifest_id=manifest.manifest_id,
+            label_release=manifest.label_release,
+            source_run_id=source_run_id,
+        )
+        runtimes.append(_resolved_declaration_runtime(run, runtime, tenant.tenant_tag))
+        status = run.get("status")
+        if status != "succeeded":
+            shown = status if isinstance(status, str) and status else "unknown"
+            raise UsageError(
+                f"{tenant.tenant_tag} treatment run is not finished ({shown}); "
+                "wait for the runs to finish"
+            )
+        digest = suite_digest_from_run(run)
+        if digest is None:
+            raise UsageError(
+                f"{tenant.tenant_tag} treatment run has no grader suite digest yet; "
+                "run treat and wait until it finishes"
+            )
+        found.append((tenant.tenant_tag, digest))
+    if len({digest for _, digest in found}) != 1:
+        detail = ", ".join(f"{tag}={digest}" for tag, digest in found)
+        raise UsageError(f"grader suite digests differ across tenants: {detail}")
+    if any(pin != runtimes[0] for pin in runtimes[1:]):
+        tags = ", ".join(tag for tag, _ in found)
+        raise UsageError(f"runtime_pin_mismatch: tenants disagree ({tags})")
+    return _DeclarationIdentity(
+        found[0][1], runtimes[0], _declaration_preprocessing_digest(manifest, preprocessing_digest)
+    )
+
+
+def _read_definition(path: str) -> dict[str, object]:
+    try:
+        raw = Path(path).read_text(encoding="utf-8")
+    except OSError as exc:
+        raise UsageError(f"could not read --definition: {exc}") from exc
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise UsageError("--definition must be a JSON object") from exc
+    return require_json_object(value, "--definition")
+
+
+def _staff_get(
+    path: str,
+    params: Mapping[str, str] | None = None,
+) -> Mapping[str, object]:
+    context = _control()
+    url = control_client.control_url(context.control_origin, path, params)
+    try:
+        response = context.transport.request(
+            "GET",
+            url,
+            headers={
+                "Accept": "application/json",
+                "Authorization": f"Bearer {context.control_token}",
+            },
+            timeout=_POOLED_READ_TIMEOUT_SECONDS,
+        )
+    except (NetworkError, TimeoutError) as exc:
+        if not _is_read_timeout(exc):
+            raise
+        raise NetworkError(
+            f"cv stopped waiting after {_POOLED_READ_TIMEOUT_SECONDS:.0f} seconds. "
+            "The server may still be computing the pooled result. "
+            "This command only reads, so it is safe to rerun."
+        ) from exc
+    if 200 <= response.status_code < 300:
+        value = response.json()
+        if not isinstance(value, Mapping):
+            raise InvalidResponseError(f"{url} did not answer with a JSON object")
+        return value
+    raise _named_refusal(response)
+
+
+def _named_refusal(response: Any) -> ControlRefusedError:
+    try:
+        payload = response.json()
+    except InvalidResponseError:
+        payload = None
+    reason: str | None = None
+    tenant_tag: str | None = None
+    if isinstance(payload, Mapping):
+        details = payload.get("details")
+        if isinstance(details, Mapping):
+            named = details.get("reason")
+            if isinstance(named, str) and named:
+                reason = named
+            tag = details.get("tenant_tag")
+            if isinstance(tag, str) and tag:
+                tenant_tag = tag
+        if reason is None:
+            message = payload.get("message")
+            if isinstance(message, str) and message:
+                reason = message
+    if reason is None:
+        reason = f"HTTP {response.status_code}"
+    if tenant_tag is not None:
+        reason = f"{reason} (tenant_tag={tenant_tag})"
+    return ControlRefusedError(reason)
+
+
+def _emit_read(payload: Mapping[str, object], args: argparse.Namespace) -> None:
+    if args.format == "json":
+        emit_json(dict(payload))
+        return
+    print(_calibration_text(payload), end="")
+
+
+def _calibration_text(payload: Mapping[str, object]) -> str:
+    lines: list[str] = []
+    heading = [
+        f"{key}={_plain(payload.get(key))}"
+        for key in (
+            "treatment",
+            "baseline_treatment",
+            "candidate_treatment",
+            "corpus_manifest_id",
+            "label_release",
+            "complete",
+        )
+        if key in payload
+    ]
+    if heading:
+        lines.append(" ".join(heading))
+    note = payload.get("extraction_note")
+    if isinstance(note, str) and "extraction noise floor" in note:
+        lines.append("reading=extraction noise floor")
+    if payload.get("basis") == "pre_audit":
+        lines.append("basis=pre_audit")
+        lines.append("batch_stability=post_audit")
+        lines.append("run_stability=post_audit")
+    tenant_tag = payload.get("tenant_tag")
+    if isinstance(tenant_tag, str):
+        lines.append(f"tenant_tag={tenant_tag}")
+    lines.extend(_warning_lines(payload))
+    lines.extend(_changed_dimension_lines(payload))
+    lines.extend(_show_cost_lines(payload))
+    lines.extend(_latency_lines(payload))
+    pooled = _pooled_decision_line(payload)
+    if pooled is not None:
+        lines.append(pooled)
+    lines.extend(_audit_side_lines(payload.get("audit"), ""))
+    lines.extend(_audit_side_lines(payload.get("baseline_audit"), "baseline "))
+    lines.extend(_audit_side_lines(payload.get("candidate_audit"), "candidate "))
+    for row in _mappings(payload.get("graders")):
+        lines.append("grader " + " ".join(_grader_bits(row)))
+    for row in _mappings(payload.get("units")):
+        lines.append("unit " + " ".join(_unit_bits(row)))
+    for row in _mappings(payload.get("batches")):
+        lines.append("batch " + " ".join(_batch_bits(row)))
+    lines.extend(_decider_lines(payload.get("decider")))
+    for column in _mappings(payload.get("decider_gate")):
+        cutoff = _cutoff_text(column.get("cutoff"))
+        for row in _mappings(column.get("graders")):
+            lines.append(
+                f"gate_delta cutoff={cutoff} criterion_id={row.get('criterion_id')} "
+                + _rate_phrase(row, ("tpr", "tnr"))
+            )
+    for row in _mappings(payload.get("batch_call_costs")):
+        lines.append("batch_call " + " ".join(_batch_call_bits(row)))
+    for row in _mappings(payload.get("untied_calls")):
+        lines.append("untied " + " ".join(_untied_bits(row)))
+    whole_run = payload.get("whole_run_call_cost")
+    if isinstance(whole_run, Mapping):
+        lines.append("whole_run_call " + " ".join(_whole_run_bits(whole_run)))
+        lines.extend(
+            "whole_run_" + line
+            for line in _production_split_lines(whole_run.get("production_cost"))
+        )
+    lines.extend(_compare_premium_lines(payload))
+    lines.extend(_arm_cost_lines(payload.get("baseline_arm_cost"), side="baseline"))
+    lines.extend(_arm_cost_lines(payload.get("candidate_arm_cost"), side="candidate"))
+    lines.extend(_distribution_compare_lines(payload))
+    for side in ("baseline", "candidate"):
+        lines.extend(
+            _extraction_lines(
+                payload.get(f"{side}_extraction"), side=side, note=payload.get("extraction_note")
+            )
+        )
+    lines.extend(_production_equivalent_lines(payload.get("production_equivalent")))
+    for name in ("extraction_per_trace", "grading_per_production_grade", "total_per_trace"):
+        lines.extend(
+            line.replace("production_equivalent", name, 1)
+            for line in _production_equivalent_lines(payload.get(name))
+        )
+    for row in _mappings(payload.get("tenants")):
+        if "difference" not in row:
+            continue
+        lines.append("tenant " + " ".join(_tenant_bits(row)))
+    equal = payload.get("equal_customer")
+    if isinstance(equal, Mapping):
+        rate = equal.get("tpr")
+        lines.append(
+            "equal_customer macro_members="
+            + _macro_members(rate)
+            + " "
+            + _named_point_phrase(equal, ("tpr", "tnr"), "macro")
+        )
+    return "\n".join(lines) + "\n"
+
+
+def _show_cost_lines(payload: Mapping[str, object]) -> list[str]:
+    lines: list[str] = []
+    for row in _mappings(payload.get("tokens_by_kind")):
+        lines.append(
+            "tokens "
+            + f"subject_kind={row.get('subject_kind')} model={row.get('model')} "
+            + _token_phrase("", row)
+        )
+    if payload.get("unpriced_share") is not None:
+        lines.append(f"unpriced_share={_plain(payload.get('unpriced_share'))}")
+    price_basis = payload.get("price_basis")
+    if isinstance(price_basis, str) and price_basis:
+        lines.append(f"price_basis={price_basis}")
+    grade_once = payload.get("grade_once_usd")
+    if grade_once is not None:
+        lines.append(
+            _labeled_dollar("grade_once_usd", grade_once, payload.get("price_basis_label"))
+        )
+    lines.extend(_call_cost_lines(payload.get("call_cost"), payload.get("price_basis_label")))
+    lines.extend(_arm_cost_lines(payload.get("arm_cost")))
+    lines.extend(_distribution_lines(payload.get("cost_distribution")))
+    lines.extend(_extraction_lines(payload.get("extraction")))
+    return lines
+
+
+def _extraction_lines(
+    extraction: object, *, side: str | None = None, note: object = None
+) -> list[str]:
+    if not isinstance(extraction, Mapping):
+        return []
+    bits = ["input_extraction"]
+    if side is not None:
+        bits.append(f"side={side}")
+    for name, key in (
+        ("uncached_input", "uncached_input_tokens"),
+        ("cached_read", "cached_read_tokens"),
+        ("cache_write", "cache_write_tokens"),
+        ("output", "output_tokens"),
+    ):
+        bits.append(f"{name}={_plain(extraction.get(key))}")
+    numeric = False
+    for name, key in (("per_trace_usd", "per_trace"), ("total_usd", "total")):
+        amount = extraction.get(key)
+        if isinstance(amount, Mapping):
+            bits.append(_basis_line(name, {**amount, "price_basis_label": None}))
+            numeric = numeric or _is_number(amount.get("amount"))
+    label = extraction.get("price_basis_label")
+    if numeric and isinstance(label, str) and label:
+        bits.append(label)
+    for text in (extraction.get("label"), note):
+        if isinstance(text, str) and text:
+            bits.append(text)
+    return [" ".join(bits)]
+
+
+def _decider_lines(decider: object) -> list[str]:
+    """The decider alone and how close it answered, then the gate, its calls and its cost."""
+
+    if not isinstance(decider, Mapping):
+        return []
+    rows = decider.get("pinned_cutoffs")
+    pinned = ",".join(
+        f"{row[0]}:{_plain(row[1])}"
+        for row in (rows if isinstance(rows, list) else [])
+        if isinstance(row, list) and len(row) == 2
+    )
+    lines = [f"decider grid={_plain(decider.get('grid'))} pinned_cutoffs={pinned}"]
+    for row in _mappings(decider.get("closeness")):
+        lines.append(
+            f"decider_closeness criterion_id={row.get('criterion_id')} "
+            + _rate_phrase(
+                row, ("within_0_05", "within_0_10", "within_0_20", "beyond_0_20", "missing")
+            )
+        )
+    cost = decider.get("decider_cost_per_trace")
+    if isinstance(cost, Mapping):
+        lines.append("decider_cost " + _basis_line("per_trace_usd", cost))
+    for part in ("alone", "gated"):
+        columns = decider.get(part)
+        if isinstance(columns, str):
+            lines.append(f"decider_{part} {columns}")
+            continue
+        for column in _mappings(columns):
+            cutoff = _cutoff_text(column.get("cutoff"))
+            for row in _mappings(column.get("graders")):
+                lines.append(f"decider_{part} cutoff={cutoff} " + " ".join(_grader_bits(row)))
+    calls = decider.get("calls")
+    if isinstance(calls, str):
+        lines.append(f"gate_calls {calls}")
+    for row in _mappings(calls):
+        bits = [
+            f"batch_member_id={row.get('batch_member_id')}",
+            f"cutoff={_cutoff_text(row.get('cutoff'))}",
+            _rate_phrase(row, ("escalation_rate", "escalated_missing_rate")),
+        ]
+        flip = row.get("flip_rate")
+        bits.append(
+            f"flip_rate={flip}" if isinstance(flip, str) else _rate_phrase(row, ("flip_rate",))
+        )
+        cost = row.get("escalated_cost_per_trace")
+        if isinstance(cost, Mapping):
+            bits.append(_basis_line("escalated_cost_per_trace_usd", cost))
+        lines.append("gate_calls " + " ".join(bits))
+    gated_cost = decider.get("gated_cost")
+    if isinstance(gated_cost, str):
+        lines.append(f"gate_cost {gated_cost}")
+    for row in _mappings(gated_cost):
+        cost = row.get("gated_cost_per_trace")
+        if isinstance(cost, Mapping):
+            lines.append(
+                f"gate_cost cutoff={_cutoff_text(row.get('cutoff'))} "
+                + _basis_line("gated_cost_per_trace_usd", cost)
+            )
+    return lines
+
+
+def _cutoff_text(value: object) -> str:
+    return "pinned" if value is None else _plain(value)
+
+
+def _arm_cost_lines(arm_cost: object, *, side: str | None = None) -> list[str]:
+    if not isinstance(arm_cost, Mapping):
+        return []
+    prefix = f"{side} " if side is not None else ""
+    lines: list[str] = []
+    fields = (
+        ("treatment_spend_usd", "treatment_spend"),
+        ("extraction_per_trace_usd", "extraction_per_trace"),
+        ("extraction_total_usd", "extraction_total"),
+        ("grading_per_production_grade_usd", "grading_per_production_grade"),
+        ("grading_total_usd", "grading_total"),
+        ("total_per_trace_usd", "total_per_trace"),
+        ("production_total_usd", "total"),
+        ("production_equivalent_per_trace_usd", "production_equivalent_per_trace"),
+        ("error_share", "error_share"),
+    )
+    for name, key in fields:
+        amount = arm_cost.get(key)
+        if isinstance(amount, Mapping):
+            lines.append(prefix + _basis_line(name, amount))
+    if arm_cost.get("grading_basis"):
+        lines.append(
+            prefix + f"grading_basis={arm_cost['grading_basis']}; treatment_spend=all k samples"
+        )
+    lines.extend(_distribution_lines(arm_cost.get("distribution"), side=side))
+    return lines
+
+
+def _distribution_lines(report: object, *, side: str | None = None) -> list[str]:
+    if not isinstance(report, Mapping) or not isinstance(report.get("status"), str):
+        return []
+    prefix = f"{side} " if side else ""
+    status = report["status"]
+    lines = [prefix + f"cost_distribution status={status}"]
+    if status == "below session floor":
+        return lines
+    for kind in ("extraction", "grading", "total"):
+        part = report.get(kind)
+        if not isinstance(part, Mapping):
+            continue
+        for q in ("p50", "p90", "p99", "max"):
+            point = part.get(q)
+            if isinstance(point, Mapping):
+                precision = point.get("precision", "unknown")
+                amount = _plain(point.get("amount"))
+                if isinstance(precision, str) and precision.startswith(">"):
+                    amount = precision
+                lines.append(
+                    prefix
+                    + f"{kind}_{q}_usd={amount} precision={precision} price basis unconfirmed"
+                )
+        lines.append(
+            prefix
+            + f"{kind}_coverage "
+            + " ".join(
+                f"{name}={_plain(part.get(name))}"
+                for name in (
+                    "exact_count",
+                    "unknown_count",
+                    "lower_bound_count",
+                    "upper_bound_count",
+                )
+            )
+        )
+    lines.append(
+        prefix
+        + f"size_basis={report.get('size_basis')} "
+        + f"unknown_size_count={_plain(report.get('unknown_size_count'))}"
+    )
+    for band in _mappings(report.get("size_bands")):
+        lines.append(
+            prefix
+            + "size_band "
+            + " ".join(
+                f"{key}={_plain(band.get(key))}"
+                for key in (
+                    "lower_exclusive",
+                    "upper_inclusive",
+                    "trace_count",
+                    "priced_trace_count",
+                    "mean_total_usd",
+                    "unknown_cost_count",
+                    "lower_bound_count",
+                    "upper_bound_count",
+                )
+            )
+            + " mean=exact-priced traces only; price basis unconfirmed"
+        )
+    return lines
+
+
+def _distribution_compare_lines(payload: Mapping[str, object]) -> list[str]:
+    report = payload.get("cost_distribution")
+    if not isinstance(report, Mapping) or "baseline" not in report:
+        return []
+    lines = []
+    for side in ("baseline", "candidate"):
+        arm = payload.get(f"{side}_arm_cost")
+        if not isinstance(arm, Mapping) or "distribution" not in arm:
+            lines.extend(_distribution_lines(report.get(side), side=side))
+    for kind in ("extraction", "grading", "total"):
+        row = report.get(kind)
+        if isinstance(row, Mapping):
+            lines.append(
+                f"{kind}_percentile_delta "
+                + " ".join(f"{q}_delta_usd={_plain(row.get(f'{q}_delta'))}" for q in ("p50", "p90"))
+                + f" precision={row.get('precision')} price basis unconfirmed"
+            )
+    return lines
+
+
+def _production_equivalent_lines(row: object) -> list[str]:
+    if not isinstance(row, Mapping):
+        return []
+    bits = ["production_equivalent"]
+    for name, key in (
+        ("baseline_usd", "baseline"),
+        ("candidate_usd", "candidate"),
+    ):
+        side = row.get(key)
+        if isinstance(side, Mapping):
+            bits.append(_basis_line(name, side))
+    bits.append(f"delta_usd={_plain(row.get('delta'))}")
+    basis = row.get("cost_basis")
+    if isinstance(basis, str) and basis:
+        bits.append(basis)
+    label = row.get("price_basis_label")
+    if isinstance(label, str) and label:
+        bits.append(label)
+    return [" ".join(bits)]
+
+
+def _basis_line(name: str, amount: Mapping[str, object]) -> str:
+    text = f"{name}={_plain(amount.get('amount'))}"
+    basis = amount.get("cost_basis")
+    if isinstance(basis, str) and basis:
+        text = f"{text} {basis}"
+    lower = amount.get("cost_lower_usd")
+    if lower is not None:
+        text = f"{text} lower_cost_usd={_plain(lower)} lower bound"
+    label = amount.get("price_basis_label")
+    if isinstance(label, str) and label:
+        text = f"{text} {label}"
+    return text
+
+
+def _call_cost_lines(call_cost: object, price_label: object) -> list[str]:
+    if not isinstance(call_cost, Mapping):
+        return []
+    lines: list[str] = []
+    for row in _mappings(call_cost.get("batches")):
+        cost = row.get("cost")
+        if isinstance(cost, Mapping):
+            lines.append("call_group " + " ".join(_one_cost_bits(row.get("batch_member_id"), cost)))
+    untied = call_cost.get("untied")
+    if isinstance(untied, Mapping):
+        lines.append("untied_call " + " ".join(_one_cost_bits(None, untied)))
+    premium = call_cost.get("long_context_premium_usd")
+    if premium is not None:
+        lines.append(
+            _premium_line(premium, call_cost.get("long_context_premium_label"), price_label)
+        )
+    return lines
+
+
+def _batch_call_bits(row: Mapping[str, object]) -> list[str]:
+    return [
+        f"batch_member_id={row.get('batch_member_id')}",
+        *_sided_cost_bits(row),
+        *_latency_delta_bits(row.get("latency")),
+    ]
+
+
+def _sided_cost_bits(row: Mapping[str, object]) -> list[str]:
+    bits: list[str] = []
+    dollars: list[str] = []
+    numeric = False
+    sides = (
+        ("baseline_", row.get("baseline"), row.get("baseline_note")),
+        ("candidate_", row.get("candidate"), row.get("candidate_note")),
+        ("delta_", row.get("delta"), None),
+    )
+    for prefix, side, note in sides:
+        if not isinstance(side, Mapping):
+            if isinstance(note, str) and note:
+                bits.append(note)
+            elif (
+                prefix == "delta_"
+                and row.get("delta") is None
+                and (row.get("baseline_note") or row.get("candidate_note"))
+            ):
+                bits.append("delta=unknown")
+            continue
+        bits.append(_token_phrase(prefix, side))
+        dollars.append(_dollar_phrase(prefix, side))
+        if _is_number(side.get("cost_usd")):
+            numeric = True
+    bits.extend(dollars)
+    label = row.get("price_basis_label")
+    if numeric and isinstance(label, str) and label:
+        bits.append(label)
+    return bits
+
+
+def _one_cost_bits(batch_member_id: object, cost: Mapping[str, object]) -> list[str]:
+    bits: list[str] = []
+    if batch_member_id is not None:
+        bits.append(f"batch_member_id={batch_member_id}")
+    bits.append(_token_phrase("", cost))
+    bits.append(_dollar_phrase("", cost))
+    bits.extend(_once_per_line(cost))
+    return bits
+
+
+def _dollar_phrase(prefix: str, cost: Mapping[str, object]) -> str:
+    text = f"{prefix}cost_usd={_plain(cost.get('cost_usd'))}"
+    basis = cost.get("cost_basis")
+    if isinstance(basis, str) and basis:
+        text = f"{text} {basis}"
+    count = cost.get("call_count")
+    if basis == "unpriced" or count is None:
+        text = f"{text} calls={_plain(count)}"
+    lower = cost.get("cost_lower_usd")
+    if lower is not None:
+        text = f"{text} lower_cost_usd={_plain(lower)} lower bound"
+    return text
+
+
+def _compare_premium_lines(payload: Mapping[str, object]) -> list[str]:
+    lines: list[str] = []
+    pairs = (
+        ("baseline", "baseline_long_context_premium_usd"),
+        ("candidate", "candidate_long_context_premium_usd"),
+    )
+    for side, key in pairs:
+        amount = payload.get(key)
+        if amount is None:
+            continue
+        lines.append(
+            f"long_context_premium side={side} "
+            + _premium_line(
+                amount,
+                "unattributed long-context premium",
+                payload.get("price_basis_label"),
+            )
+        )
+    return lines
+
+
+def _premium_line(amount: object, premium_label: object, price_label: object) -> str:
+    text = _labeled_dollar("long_context_premium_usd", amount, price_label)
+    if isinstance(premium_label, str) and premium_label:
+        return f"{text} {premium_label}"
+    return text
+
+
+def _untied_bits(row: Mapping[str, object]) -> list[str]:
+    bits = [f"side={row.get('side')}"]
+    for key in ("label", "exclusion"):
+        value = row.get(key)
+        if isinstance(value, str) and value:
+            bits.append(value)
+    cost = row.get("cost")
+    if isinstance(cost, Mapping):
+        bits.append(_token_phrase("", cost))
+        bits.append(_dollar_phrase("", cost))
+        bits.extend(_once_per_line(cost))
+    return bits
+
+
+def _whole_run_bits(row: Mapping[str, object]) -> list[str]:
+    return _sided_cost_bits(row)
+
+
+def _production_split_lines(row: object) -> list[str]:
+    if not isinstance(row, Mapping):
+        return []
+    return [
+        line.replace("production_equivalent", f"{name}_per_trace", 1)
+        for name in ("extraction", "grading", "total")
+        for line in _production_equivalent_lines(row.get(name))
+    ]
+
+
+def _token_phrase(prefix: str, row: Mapping[str, object]) -> str:
+    parts = (
+        ("uncached_input", "uncached_input_tokens"),
+        ("cached_read", "cached_read_tokens"),
+        ("cache_write", "cache_write_tokens"),
+        ("output", "output_tokens"),
+    )
+    return " ".join(f"{prefix}{name}={row.get(key)}" for name, key in parts)
+
+
+def _once_per_line(cost: Mapping[str, object]) -> list[str]:
+    label = cost.get("price_basis_label")
+    if _is_number(cost.get("cost_usd")) and isinstance(label, str) and label:
+        return [label]
+    return []
+
+
+def _labeled_dollar(name: str, amount: object, label: object) -> str:
+    text = f"{name}={_plain(amount)}"
+    if isinstance(label, str) and label and _is_number(amount):
+        return f"{text} {label}"
+    return text
+
+
+def _warning_lines(payload: Mapping[str, object]) -> list[str]:
+    lines: list[str] = []
+    retired = payload.get("retired_note")
+    if isinstance(retired, str) and retired:
+        lines.append(f"retired_note={retired}")
+    note = payload.get("note")
+    if isinstance(note, str) and note:
+        lines.append(f"note={note}")
+    return lines
+
+
+def _changed_dimension_lines(payload: Mapping[str, object]) -> list[str]:
+    lines: list[str] = []
+    for row in _mappings(payload.get("changed_dimensions")):
+        lines.append(f"changed_dimension dimension={row.get('dimension')} kind={row.get('kind')}")
+    return lines
+
+
+def _pooled_decision_line(payload: Mapping[str, object]) -> str | None:
+    decision = payload.get("pooled")
+    if isinstance(decision, Mapping) and _has_rate(decision):
+        bits = ["pooled"]
+        support = decision.get("support")
+        if isinstance(support, str) and support:
+            bits.append(f"support={support}")
+        phrase = _rate_phrase(decision, ("tpr", "tnr"))
+        if phrase:
+            bits.append(phrase)
+        return " ".join(bits)
+    label = "tenant" if isinstance(payload.get("tenant_tag"), str) else "pooled"
+    counts = payload.get("counts") if label == "tenant" else payload.get("pooled_counts")
+    run = payload.get("run")
+    if not isinstance(counts, Mapping) and not isinstance(run, Mapping):
+        return None
+    bits = [label]
+    if isinstance(counts, Mapping):
+        for key in ("tp", "fp", "tn", "fn", "no_verdict"):
+            if key in counts:
+                bits.append(f"{key}={_plain(counts.get(key))}")
+    if isinstance(run, Mapping):
+        sessions = _sessions(run)
+        if sessions:
+            bits.append(sessions)
+        phrase = _rate_phrase(run, ("tpr", "tnr"))
+        if phrase:
+            bits.append(phrase)
+    return " ".join(bits)
+
+
+def _has_rate(row: Mapping[str, object]) -> bool:
+    return any(key in row for key in ("tpr", "tnr", "support"))
+
+
+def _audit_side_lines(report: object, prefix: str) -> list[str]:
+    if not isinstance(report, Mapping):
+        return []
+    lines: list[str] = []
+    pre_audit = report.get("pre_audit")
+    if pre_audit == "not recorded":
+        lines.append(f"{prefix}pre_audit not recorded")
+    else:
+        for row in _mappings(pre_audit):
+            lines.append(f"{prefix}pre_audit " + " ".join(_audit_rate_bits(row)))
+    effect = report.get("effect")
+    if effect == "not recorded":
+        lines.append(f"{prefix}audit_effect not recorded")
+    else:
+        for row in _mappings(effect):
+            lines.append(f"{prefix}audit_effect " + " ".join(_audit_rate_bits(row)))
+    dispositions = report.get("dispositions")
+    if dispositions == "not recorded":
+        lines.append(f"{prefix}audit_disposition not recorded")
+    else:
+        for row in _mappings(dispositions):
+            lines.append(f"{prefix}audit_disposition " + " ".join(_disposition_bits(row)))
+    return lines
+
+
+def _audit_rate_bits(row: Mapping[str, object]) -> list[str]:
+    bits = [f"{key}={row.get(key)}" for key in ("criterion_id",) if key in row]
+    phrase = _rate_phrase(row, ("tpr", "tnr", "balanced_accuracy"))
+    if phrase:
+        bits.append(phrase)
+    return bits
+
+
+def _disposition_bits(row: Mapping[str, object]) -> list[str]:
+    keys = (
+        "criterion_id",
+        "failed_before_audit",
+        "invalidated",
+        "upheld",
+        "error",
+        "skipped",
+    )
+    return [f"{key}={row.get(key)}" for key in keys if key in row]
+
+
+def _grader_bits(row: Mapping[str, object]) -> list[str]:
+    bits = [f"{key}={row.get(key)}" for key in ("criterion_id", "batch_member_id") if key in row]
+    sessions = _sessions(row)
+    if sessions:
+        bits.append(sessions)
+    support = row.get("support")
+    if isinstance(support, str) and support:
+        bits.append(f"support={support}")
+    phrase = _rate_phrase(row, ("tpr", "tnr"))
+    if phrase:
+        bits.append(phrase)
+    return bits
+
+
+def _unit_bits(row: Mapping[str, object]) -> list[str]:
+    bits = [f"unit_id={row.get('unit_id')}"]
+    criteria = row.get("criteria")
+    if isinstance(criteria, list):
+        bits.append(f"criteria={len(criteria)}")
+    reason = row.get("reason")
+    if isinstance(reason, str) and reason:
+        bits.append(f"reason={reason}")
+    difference = row.get("difference")
+    source = difference if isinstance(difference, Mapping) else row
+    phrase = _rate_phrase(source, ("tpr", "tnr"))
+    if phrase:
+        bits.append(phrase)
+    cost = row.get("cost")
+    if isinstance(cost, Mapping):
+        bits.extend(_sided_cost_bits(cost))
+        bits.extend(_production_equivalent_lines(cost.get("production_equivalent")))
+        bits.extend(_production_split_lines(cost.get("production_cost")))
+    bits.extend(_latency_delta_bits(row.get("latency")))
+    return bits
+
+
+def _batch_bits(row: Mapping[str, object]) -> list[str]:
+    bits = [f"batch_member_id={row.get('batch_member_id')}"]
+    for key in ("comparable", "negative_control", "drift"):
+        if key in row:
+            bits.append(f"{key}={_plain(row.get(key))}")
+    reason = row.get("reason")
+    if isinstance(reason, str) and reason:
+        bits.append(f"reason={reason}")
+    sessions = _sessions(row)
+    if sessions:
+        bits.append(sessions)
+    difference = row.get("difference")
+    source = difference if isinstance(difference, Mapping) else row
+    if isinstance(difference, Mapping):
+        support = difference.get("support")
+        if isinstance(support, str) and support:
+            bits.append(f"support={support}")
+    phrase = _rate_phrase(source, ("tpr", "tnr"))
+    if phrase:
+        bits.append(phrase)
+    return bits
+
+
+def _tenant_bits(row: Mapping[str, object]) -> list[str]:
+    bits = [f"tenant_tag={row.get('tenant_tag')}"]
+    note = row.get("note")
+    if isinstance(note, str) and note:
+        bits.append(f"note={note}")
+    difference = row.get("difference")
+    if isinstance(difference, Mapping):
+        phrase = _rate_phrase(difference, ("tpr", "tnr"))
+        if phrase:
+            bits.append(phrase)
+    return bits
+
+
+def _sessions(row: Mapping[str, object]) -> str:
+    support = row.get("sample_support")
+    if not isinstance(support, Mapping):
+        return ""
+    count = support.get("session_count")
+    if isinstance(count, bool) or not isinstance(count, int):
+        return ""
+    return f"sessions={count}"
+
+
+def _rate_phrase(row: Mapping[str, object], names: Sequence[str]) -> str:
+    return " ".join(f"{name}={_rate_text(row.get(name))}" for name in names if name in row)
+
+
+def _named_point_phrase(row: Mapping[str, object], names: Sequence[str], point: str) -> str:
+    parts: list[str] = []
+    for name in names:
+        if name not in row:
+            continue
+        value = row.get(name)
+        shown = value.get(point) if isinstance(value, Mapping) and point in value else value
+        parts.append(f"{name}={_rate_text(shown)}")
+    return " ".join(parts)
+
+
+def _rate_text(value: object) -> str:
+    if isinstance(value, Mapping) and "micro" in value:
+        return _rate_text(value.get("micro"))
+    if not isinstance(value, Mapping):
+        return "unknown"
+    point = value.get("point")
+    if isinstance(point, bool) or not isinstance(point, (int, float)):
+        return "unknown"
+    text = _format_number(float(point))
+    lower = value.get("lower")
+    upper = value.get("upper")
+    if _is_number(lower) and _is_number(upper):
+        text += f" [{_format_number(float(lower))}, {_format_number(float(upper))}]"
+    return text
+
+
+def _is_number(value: object) -> TypeGuard[int | float]:
+    return not isinstance(value, bool) and isinstance(value, (int, float))
+
+
+def _format_number(value: float) -> str:
+    return f"{value:.3f}".rstrip("0").rstrip(".")
+
+
+def _macro_members(value: object) -> str:
+    if not isinstance(value, Mapping):
+        return ""
+    members = value.get("macro_members")
+    if not isinstance(members, list):
+        return ""
+    return ",".join(item for item in members if isinstance(item, str))
+
+
+def _plain(value: object) -> str:
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if value is None:
+        return "unknown"
+    return str(value)
+
+
+def _mappings(value: object) -> list[Mapping[str, object]]:
+    if not isinstance(value, list):
+        return []
+    return [item for item in value if isinstance(item, Mapping)]
+
+
+def _add_gate(parser: argparse.ArgumentParser) -> None:
+    chosen = parser.add_mutually_exclusive_group()
+    chosen.add_argument(
+        "--gate-baseline",
+        metavar="TREATMENT",
+        help=(
+            "On a decider arm, the baseline treatment its gate is measured against. "
+            "Each tenant's baseline run is that treatment's run on the same input and k. "
+            "The first send is final."
+        ),
+    )
+    chosen.add_argument(
+        "--ungated",
+        action="store_true",
+        help=(
+            "On a decider arm, send the decider's own counts without a gate. "
+            "The first send is final."
+        ),
+    )
+    parser.add_argument(
+        "--gate-baseline-criterion-version",
+        action="append",
+        default=None,
+        metavar="CRITERION=VERSION",
+        help="One pin of the baseline treatment. Repeat for each pin. Its run id includes them.",
+    )
+
+
+def _add_criterion_version(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--criterion-version",
+        action="append",
+        default=None,
+        metavar="CRITERION=VERSION",
+        help=(
+            "Pin one platform criterion to a grader version. "
+            "Repeat for each pin. The pin is part of the treatment run id."
+        ),
+    )
+
+
+def _add_read_format(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--format",
+        choices=("text", "json"),
+        default="text",
+        help="Print the result as text or JSON.",
+    )
+
+
+def _add_format(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--log-steps",
+        action="store_true",
+        help="Print one JSON object per step to stderr.",
+    )
+    parser.add_argument(
+        "--format",
+        choices=("json",),
+        default=None,
+        help="Print the result as JSON.",
+    )
+
+
+def _latency_value(value: object, *, overflow: bool = False) -> str:
+    if value is None:
+        return ">1800 s" if overflow else "unknown"
+    return _plain(value)
+
+
+def _latency_bits(summary: object) -> list[str]:
+    if not isinstance(summary, Mapping):
+        return ["latency_p50_seconds=unknown", "latency_p90_seconds=unknown"]
+    overflow = summary.get("overflow") is True
+    return [
+        f"latency_{name}_seconds="
+        + _latency_value(summary.get(f"{name}_seconds"), overflow=overflow)
+        for name in ("p50", "p90", "max")
+    ]
+
+
+def _latency_delta_bits(value: object) -> list[str]:
+    if not isinstance(value, Mapping):
+        return []
+    bits = []
+    for name in ("p50", "p90"):
+        overflow = any(
+            isinstance(side, Mapping)
+            and side.get("overflow") is True
+            and side.get(f"{name}_seconds") is None
+            for side in (value.get("baseline"), value.get("candidate"))
+        )
+        shown = (
+            "unknown (overflow)" if overflow else _latency_value(value.get(f"delta_{name}_seconds"))
+        )
+        bits.append(f"latency_delta_{name}_seconds={shown}")
+    return bits
+
+
+def _latency_lines(payload: Mapping[str, object]) -> list[str]:
+    summary = payload.get("latency")
+    rows = payload.get("batch_latency")
+    if summary is None and not any(
+        isinstance(row, (tuple, list)) and len(row) == 2 and row[1] is not None
+        for row in (rows if isinstance(rows, (tuple, list)) else ())
+    ):
+        return []
+    lines = ["latency_basis=bucket_upper_bound scope=batch_executions"]
+    if isinstance(summary, Mapping) and "baseline" in summary:
+        lines.append("whole_run " + " ".join(_latency_delta_bits(summary)))
+    else:
+        lines.append("whole_run " + " ".join(_latency_bits(summary)))
+    if isinstance(rows, (tuple, list)):
+        for row in rows:
+            if isinstance(row, (tuple, list)) and len(row) == 2:
+                lines.append(
+                    f"batch_latency batch_member_id={row[0]} " + " ".join(_latency_bits(row[1]))
+                )
+    return lines