lucen-cli 0.1.0__py3-none-any.whl

lucen_cli/rollout/engine.py

@@ -0,0 +1,1808 @@
+"""MuJoCo + onnxruntime: run a policy under its `io_contract`, and measure.
+
+What runs here is the deployment bridge's loop, in simulation: at the
+contract's control rate the observation is assembled in the contract's order
+and scales, the ONNX graph is asked for an action, the action is clipped and
+scaled onto the default pose to give joint targets, and a PD loop drives the
+joints at the physics rate, torque-clipped at the robot card's deployed
+limits ("simulation clips at the same value" — the card's own words). Laika's
+MJCF has no actuators, so the PD torque is applied through `qfrc_applied`;
+a model that does carry actuators is driven through `ctrl` instead.
+
+Measurement, not verdict: an episode reports whether the base stayed upright
+for the whole horizon (and when it stopped), and the mean body-frame
+velocity per commanded axis as a ratio of the command. The hub applies the
+harness rule to those numbers (`lucen_api.rollout.gate`).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+# onnxruntime's wheels embed Microsoft's 1DS telemetry client. It is created
+# with the runtime environment, starts an HTTP uploader thread, and on macOS
+# aborts the whole process at exit when a late response handler locks a mutex
+# libc++ has already destroyed (`recursive_mutex lock failed`, one pytest run
+# in three; the crash report's faulting thread is
+# `Microsoft::Applications::Events::HttpClientManager::onHttpResponse`). The
+# binary honours `ORT_DISABLE_TELEMETRY` at environment creation — which is
+# before `disable_telemetry_events()` can run, so only the variable prevents
+# the thread from existing. It has to be set before the import, which is why
+# the runtime comes from `lucen_cli.ort_quiet` (which also keeps the runtime's
+# device-discovery warnings off stderr). A policy gate on a user's machine has
+# no business reporting anywhere in any case.
+import mujoco
+import numpy as np
+
+from lucen_cli.onnx_manifest import OnnxReadError, read_lucen_manifest
+from lucen_cli.ort_quiet import ort
+
+if hasattr(ort, "disable_telemetry_events"):  # belt to the variable's braces
+    ort.disable_telemetry_events()
+from lucen_cli.embodiment import Embodiment, InterfaceError
+from lucen_cli.embodiment import card_limits as card_limits_of
+from lucen_cli.rollout import conditions as conditions_mod
+from lucen_cli.rollout import harness
+from lucen_cli.rollout import obs as obs_registry
+from lucen_cli.rollout import posture as posture_mod
+from lucen_cli.rollout.contract import ContractMismatch, IoContract, validate
+from lucen_cli.rollout.plant import Plant, PlantError, build_plant, default_qpos
+
+#: Upright: the base keeps at least this fraction of its initial height…
+UPRIGHT_HEIGHT_FRACTION = 0.4
+#: …and tilts less than 60 degrees (projected gravity's z component).
+UPRIGHT_GRAVITY_Z = -0.5
+#: Tracking is averaged after the policy has had this long to settle.
+SETTLE_S = 1.0
+#: Per-seed initial-state noise: joint offsets (rad) and base yaw (rad).
+JOINT_NOISE_RAD = 0.02
+YAW_NOISE_RAD = 0.3
+DEFAULT_GAINS = (40.0, 1.0)
+#: M17b. `joint_target` / `reach` cells: the error is averaged over the last
+#: this-fraction of the horizon ("settle"), and over everything after SETTLE_S
+#: ("tracking"). The PASS tolerances themselves are the hub's (gate.py).
+SETTLE_WINDOW_FRACTION = 0.2
+CELL_KINDS = ("velocity", "joint_target", "reach", "recovery")
+#: C2. How a battery measures: `m8` (M8's definitions, the default) or
+#: `sim2sim` (the founder's harness: its start pose, its survival reading, its
+#: yaw rate from the net heading change, and eval_c_matrix's median tracking).
+PROTOCOL_M8 = "m8"
+PROTOCOL_SIM2SIM = "sim2sim"
+PROTOCOLS = (PROTOCOL_M8, PROTOCOL_SIM2SIM)
+#: sim2sim's absolute survival numbers on Laika (0.384 m standing), as
+#: fractions of the robot's standing height: an episode ends below 0.25 m, and
+#: is alive when it ends above 0.30 m and tilted less than 25°.
+HARNESS_FALL_FRACTION = 0.25 / 0.384
+HARNESS_ALIVE_FRACTION = 0.30 / 0.384
+HARNESS_ALIVE_TILT_DEG = 25.0
+#: The recovery criterion (RECOVERY_V0_SPEC §5, sim2sim `--init-fallen`,
+#: `accept_recovery.py`): tilt, height, both feet, angular rate, held 0.5 s.
+RECOVERY_TILT_DEG = 15.0
+RECOVERY_HEIGHT_FRACTION = 0.85
+RECOVERY_FOOT_N = 5.0
+RECOVERY_OMEGA = 1.0
+RECOVERY_HOLD_S = 0.5
+RECOVERY_TORQUE_SETTLE_S = 0.5
+RECOVERY_ACTION_SAT = 0.99
+#: C3b. After a push on a posture cell, the base has RECOVERED at the first
+#: control step from which, to the end of the episode, it is tilted no more
+#: than the stand battery's tilt bar and moving no faster than 5 cm/s across
+#: the floor. Fixed with the calibration (docs/DECISIONS.md "C3b") and
+#: recorded beside the verdict; the hub gates on the tilt, not on this.
+PUSH_RECOVER_TILT_DEG = 3.0
+PUSH_RECOVER_SPEED_M_S = 0.05
+
+FrameSink = Callable[[mujoco.MjData, float], None]
+Log = Callable[[str], None]
+
+
+def versions() -> dict[str, str]:
+    return {"mujoco": str(mujoco.__version__), "onnxruntime": str(ort.__version__)}
+
+
+# ---------------------------------------------------------------------------
+# The policy
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Policy:
+    session: ort.InferenceSession
+    input_name: str
+    output_name: str
+    in_dim: int | None
+    out_dim: int | None
+    sha256: str
+    path: Path
+    manifest: dict[str, Any]
+
+    def __call__(self, obs: np.ndarray) -> np.ndarray:
+        out = self.session.run([self.output_name], {self.input_name: obs.reshape(1, -1)})[0]
+        return np.asarray(out, dtype=np.float64).reshape(-1)
+
+    def close(self) -> None:
+        """Drop the onnxruntime session now rather than at interpreter exit.
+
+        Native resources are released when the work is done, not whenever the
+        garbage collector gets to them; the worker closes its policy in a
+        `finally` and tests close their fixtures.
+        """
+        self.session = None
+
+
+def _session_options() -> ort.SessionOptions:
+    """One thread, no pool: a locomotion policy is a few thousand MACs a step.
+
+    With one thread onnxruntime creates no intra-op workers at all, so a
+    battery's per-step latency is lower and nothing of the session outlives
+    its last use. (The exit abort this was first suspected of turned out to
+    be the telemetry thread above.)
+    """
+    options = ort.SessionOptions()
+    options.intra_op_num_threads = 1
+    options.inter_op_num_threads = 1
+    options.log_severity_level = 3
+    return options
+
+
+def _last_dim(shape: list[Any]) -> int | None:
+    if not shape:
+        return None
+    last = shape[-1]
+    return int(last) if isinstance(last, int) else None
+
+
+def load_policy(path: Path, manifest: dict[str, Any] | None = None) -> Policy:
+    """An onnxruntime session plus the contract stamped in the file.
+
+    `manifest` overrides the stamp only when the file carries none (the
+    `io_contract.json` sidecar case); an unstamped ONNX with no sidecar is a
+    ContractMismatch, exactly as the two real consumers treat it.
+    """
+    data = path.read_bytes()
+    try:
+        stamped = read_lucen_manifest(path)
+    except (OnnxReadError, ValueError) as exc:
+        raise ContractMismatch(f"{path.name} is not a readable ONNX file: {exc}") from exc
+    chosen = stamped or manifest
+    if not chosen:
+        raise ContractMismatch(
+            f"{path.name} carries no `lucen_manifest` and no io_contract.json sidecar was "
+            "found; a policy with no contract is refused, as both real consumers refuse it"
+        )
+    try:
+        session = ort.InferenceSession(
+            str(path), sess_options=_session_options(), providers=["CPUExecutionProvider"]
+        )
+    except Exception as exc:
+        raise ContractMismatch(f"{path.name}: onnxruntime cannot load it ({exc})") from exc
+    inputs, outputs = session.get_inputs(), session.get_outputs()
+    if len(inputs) != 1 or len(outputs) < 1:
+        raise ContractMismatch(
+            f"{path.name}: expected one input and one output, found {len(inputs)} and "
+            f"{len(outputs)}"
+        )
+    return Policy(
+        session=session,
+        input_name=inputs[0].name,
+        output_name=outputs[0].name,
+        in_dim=_last_dim(list(inputs[0].shape)),
+        out_dim=_last_dim(list(outputs[0].shape)),
+        sha256=hashlib.sha256(data).hexdigest(),
+        path=path,
+        manifest=dict(chosen),
+    )
+
+
+# ---------------------------------------------------------------------------
+# The simulator
+# ---------------------------------------------------------------------------
+
+
+def model_joints(model: mujoco.MjModel) -> dict[str, int]:
+    """`{joint name: DoF count}` for every named joint in the model."""
+    out: dict[str, int] = {}
+    for j in range(model.njnt):
+        name = mujoco.mj_id2name(model, mujoco.mjtObj.mjOBJ_JOINT, j)
+        if not name:
+            continue
+        kind = model.jnt_type[j]
+        dofs = {mujoco.mjtJoint.mjJNT_FREE: 6, mujoco.mjtJoint.mjJNT_BALL: 3}.get(kind, 1)
+        out[name] = dofs
+    return out
+
+
+def load_model(mjcf_path: Path) -> mujoco.MjModel:
+    try:
+        return mujoco.MjModel.from_xml_path(str(mjcf_path))
+    except Exception as exc:
+        raise ContractMismatch(f"MuJoCo refused to compile {mjcf_path.name}: {exc}") from exc
+
+
+def _yaw_of(quat: np.ndarray) -> float:
+    """World yaw of a wxyz quaternion — sim2sim's `yaw_now`."""
+    w, x, y, z = (float(v) for v in quat)
+    return float(math.atan2(2 * (w * z + x * y), 1 - 2 * (y * y + z * z)))
+
+
+class Simulator:
+    """One robot, one contract: reset, observe, step, and say whether it is upright."""
+
+    def __init__(
+        self,
+        model: mujoco.MjModel,
+        contract: IoContract,
+        *,
+        plant: dict[str, Any] | None = None,
+        card: dict[str, Any] | None = None,
+        emb: Embodiment | None = None,
+        built: Plant | None = None,
+    ) -> None:
+        self.model = model
+        self.data = mujoco.MjData(model)
+        self.contract = contract
+        #: M17b. The robot's own declaration and the plant compiled from it.
+        #: Both None on the legacy path (a card with no `interface`).
+        self.emb = emb
+        self.built = built
+        plant = plant or {}
+        n = len(contract.joint_order)
+        joint_ids = [
+            mujoco.mj_name2id(model, mujoco.mjtObj.mjOBJ_JOINT, j) for j in contract.joint_order
+        ]
+        self.joint_ids = joint_ids
+        self.qpos_adr = np.asarray([model.jnt_qposadr[j] for j in joint_ids], dtype=np.intp)
+        self.dof_adr = np.asarray([model.jnt_dofadr[j] for j in joint_ids], dtype=np.intp)
+
+        # The floating base, if any.
+        self.base_qpos: int | None = None
+        self.base_dof: int | None = None
+        self.base_body = 1 if model.nbody > 1 else 0
+        for j in range(model.njnt):
+            if model.jnt_type[j] == mujoco.mjtJoint.mjJNT_FREE:
+                self.base_qpos = int(model.jnt_qposadr[j])
+                self.base_dof = int(model.jnt_dofadr[j])
+                self.base_body = int(model.jnt_bodyid[j])
+                break
+        self.fixed_base = self.base_qpos is None
+
+        # Torque limits: the card's deployed `effort` first, then the plant's
+        # scalar, then the MJCF's own actuatorfrcrange, then unlimited.
+        limits = np.full(n, np.inf)
+        card_limits = (card or {}).get("limits") if isinstance(card, dict) else None
+        tau_plant = plant.get("tau_limit")
+        for k, (name, j) in enumerate(zip(contract.joint_order, joint_ids, strict=True)):
+            effort = None
+            if isinstance(card_limits, dict) and isinstance(card_limits.get(name), dict):
+                effort = card_limits[name].get("effort")
+            if effort is None and isinstance(tau_plant, int | float):
+                effort = float(tau_plant)
+            if effort is None and model.jnt_actfrclimited[j]:
+                effort = float(model.jnt_actfrcrange[j][1])
+            if effort is not None:
+                limits[k] = abs(float(effort))
+        if emb is not None:
+            # The robot's declared effort limit is what its plant clips at.
+            for k in range(n):
+                if emb.effort_limit[k] is not None:
+                    limits[k] = abs(float(emb.effort_limit[k]))  # type: ignore[arg-type]
+        self.tau_limit = limits
+
+        gains = plant.get("gains_rl_default")
+        if isinstance(gains, list | tuple) and len(gains) == 2:
+            self.kp, self.kd = float(gains[0]), float(gains[1])
+        else:
+            self.kp, self.kd = DEFAULT_GAINS
+        self._base_kp, self._base_kd = self.kp, self.kd
+
+        # Actuators, when the model has them: one per contract joint at most.
+        self.actuator_of: dict[int, tuple[int, bool]] = {}
+        for a in range(model.nu):
+            if model.actuator_trntype[a] != mujoco.mjtTrn.mjTRN_JOINT:
+                continue
+            joint = int(model.actuator_trnid[a][0])
+            position_servo = (
+                model.actuator_biastype[a] == mujoco.mjtBias.mjBIAS_AFFINE
+                and model.actuator_biasprm[a][1] < 0
+            )
+            for k, j in enumerate(joint_ids):
+                if j == joint:
+                    self.actuator_of[k] = (a, bool(position_servo))
+
+        self.dt = float(model.opt.timestep)
+        # The robot declares its control rate; a contract that disagrees was
+        # already refused by `validate` via the fingerprint, so when there is
+        # an interface its rate is the one that holds.
+        rate = emb.control_rate_hz if emb is not None else contract.control_rate_hz
+        self.control_rate_hz = float(rate)
+        self.decimation = max(1, round(1.0 / (self.dt * self.control_rate_hz)))
+        self.control_dt = self.dt * self.decimation
+
+        # Soft joint limits for limit-violation counting: the card's
+        # `soft_lower`/`soft_upper` when it has them, else its `lower`/`upper`
+        # (else the MJCF range) shrunk by the interface's soft_limit_factor.
+        self.soft_lo, self.soft_hi = self._soft_limits(card, joint_ids)
+        # Hard ranges (the MJCF's, else the card's): where the founder's fallen
+        # starts draw their joints from.
+        hard = card_limits_of(card, contract.joint_order)
+        self.range_lo = np.full(n, -math.pi)
+        self.range_hi = np.full(n, math.pi)
+        for k, j in enumerate(joint_ids):
+            if model.jnt_limited[j]:
+                self.range_lo[k], self.range_hi[k] = model.jnt_range[j]
+            else:
+                if hard["lower"][k] is not None:
+                    self.range_lo[k] = float(hard["lower"][k])
+                if hard["upper"][k] is not None:
+                    self.range_hi[k] = float(hard["upper"][k])
+        self.ee_name: str | None = None
+        if built is not None and built.ee_sensor:
+            self.ee_name = next(iter(built.ee_sensor))
+
+        # C2: contract features past the base 45 dims (policy_io's own).
+        try:
+            self.lat_ff = harness.LateralFeedForward.from_contract(
+                contract.raw, contract.joint_order, contract.cycle_time_s
+            )
+            self.beta = harness.beta_vector(contract.raw, contract.joint_order)
+        except harness.HarnessContractError as exc:
+            raise ContractMismatch(str(exc)) from exc
+        self.history_dim = sum(b.dim for b in contract.obs_spec if b.name == harness.HISTORY_BLOCK)
+        self.history: harness.FrameHistory | None = (
+            harness.FrameHistory(self.history_dim, n) if self.history_dim else None
+        )
+        # C2: per-joint velocity limits for the bridge slew, from the interface.
+        self.velocity_limit = np.full(n, np.inf)
+        if emb is not None:
+            for k in range(n):
+                if emb.velocity_limit[k] is not None:
+                    self.velocity_limit[k] = float(emb.velocity_limit[k])  # type: ignore[arg-type]
+        # C2: what conditions scale is always scaled from these, never compounded.
+        self._base_friction = np.asarray(model.geom_friction, dtype=np.float64).copy()
+        self._base_gainprm = np.asarray(model.actuator_gainprm, dtype=np.float64).copy()
+        self._base_biasprm = np.asarray(model.actuator_biasprm, dtype=np.float64).copy()
+        self.cond = conditions_mod.Conditions()
+        self._total_mass = float(model.body_subtreemass[0])
+        self._foot_geoms: list[set[int]] = []
+        if emb is not None:
+            for foot in emb.feet:
+                body = mujoco.mj_name2id(model, mujoco.mjtObj.mjOBJ_BODY, foot)
+                if body >= 0:
+                    self._foot_geoms.append(
+                        {g for g in range(model.ngeom) if int(model.geom_bodyid[g]) == body}
+                    )
+
+        # Initial state: the `standing` keyframe, else keyframe 0, else qpos0.
+        self.keyframe = -1
+        self.standing_keyframe = -1
+        for k in range(model.nkey):
+            if mujoco.mj_id2name(model, mujoco.mjtObj.mjOBJ_KEY, k) == "standing":
+                self.keyframe = k
+                self.standing_keyframe = k
+        if self.keyframe < 0 and model.nkey > 0:
+            self.keyframe = 0
+        self._home_qpos: np.ndarray | None = None
+        if emb is not None and built is not None:
+            try:
+                self._home_qpos = default_qpos(built, emb)
+            except PlantError as exc:
+                raise ContractMismatch(str(exc)) from exc
+        # The policy's own nominal pose is what its actions are offsets from
+        # and what `joint_pos_rel` is measured against — the contract's, as
+        # both of the founder's consumers read it (policy_io's `default`). M17b
+        # took the robot's `default_pose` instead; for every policy trained
+        # against the interface they are the same numbers, and for a published
+        # Lucen policy whose profile has its own nominal (stand: all zeros;
+        # recovery: mid-range) the robot's pose was simply the wrong reference.
+        self._reset_state()
+        init = self.data.qpos[self.qpos_adr].copy()
+        self.default_pose = (
+            contract.default_pose.astype(np.float64)
+            if contract.default_pose is not None
+            else init.astype(np.float64)
+        )
+        self._reset_state()
+        self.init_height = float(self.base_position()[2]) if not self.fixed_base else 0.0
+        # C2: the founder's start (`sim2sim.py`): the `standing` keyframe (else
+        # the home pose), the policy joints at the policy's nominal. Its base
+        # height is the robot's standing height the harness's absolute numbers
+        # were written against (0.384 m on Laika).
+        self._harness_qpos = self._harness_home()
+        #: C2, parity only: read the base ROTATION the way `sim2sim.py` does —
+        #: from `xmat`, one physics substep old (see `_fresh_base`). Never set
+        #: by a battery; the parity harness sets it to show that, with this one
+        #: difference removed, the gate and the founder's harness agree step for step.
+        self.stale_rotation = False
+        self.stand_height = (
+            float(self._harness_qpos[self.base_qpos + 2]) if self.base_qpos is not None else 0.0
+        )
+        self.time_s = 0.0
+
+    # -- state -------------------------------------------------------------
+
+    def _soft_limits(
+        self, card: dict[str, Any] | None, joint_ids: list[int]
+    ) -> tuple[np.ndarray, np.ndarray]:
+        n = len(joint_ids)
+        lo, hi = np.full(n, -np.inf), np.full(n, np.inf)
+        for k, j in enumerate(joint_ids):
+            if self.model.jnt_limited[j]:
+                lo[k], hi[k] = self.model.jnt_range[j]
+        hard = card_limits_of(card, self.contract.joint_order)
+        for k in range(n):
+            if hard["lower"][k] is not None:
+                lo[k] = float(hard["lower"][k])
+            if hard["upper"][k] is not None:
+                hi[k] = float(hard["upper"][k])
+        factor = self.emb.soft_limit_factor if self.emb is not None else 1.0
+        centre, half = (lo + hi) / 2.0, (hi - lo) / 2.0
+        with np.errstate(invalid="ignore"):
+            soft_lo = np.where(np.isfinite(lo), centre - factor * half, -np.inf)
+            soft_hi = np.where(np.isfinite(hi), centre + factor * half, np.inf)
+        limits = (card or {}).get("limits") if isinstance(card, dict) else None
+        for k, name in enumerate(self.contract.joint_order):
+            entry = limits.get(name) if isinstance(limits, dict) else None
+            if isinstance(entry, dict):
+                if isinstance(entry.get("soft_lower"), int | float):
+                    soft_lo[k] = float(entry["soft_lower"])
+                if isinstance(entry.get("soft_upper"), int | float):
+                    soft_hi[k] = float(entry["soft_upper"])
+        return soft_lo, soft_hi
+
+    def limit_violation(self) -> bool:
+        """Is any policy joint outside its soft limit right now?"""
+        q = self.data.qpos[self.qpos_adr]
+        return bool(np.any(q < self.soft_lo - 1e-9) or np.any(q > self.soft_hi + 1e-9))
+
+    def ee_position(self) -> np.ndarray | None:
+        """The first declared end effector's position, or None when there is none."""
+        if self.built is None or self.ee_name is None:
+            return None
+        start, stop = self.built.ee_sensor[self.ee_name]
+        return np.asarray(self.data.sensordata[start:stop], dtype=np.float64).copy()
+
+    def _reset_state(self) -> None:
+        if self._home_qpos is not None:
+            mujoco.mj_resetData(self.model, self.data)
+            self.data.qpos[:] = self._home_qpos
+        elif self.keyframe >= 0:
+            mujoco.mj_resetDataKeyframe(self.model, self.data, self.keyframe)
+        else:
+            mujoco.mj_resetData(self.model, self.data)
+        pose = getattr(self, "default_pose", None)
+        if pose is not None:
+            self.data.qpos[self.qpos_adr] = pose
+        mujoco.mj_forward(self.model, self.data)
+
+    def _harness_home(self) -> np.ndarray:
+        data = mujoco.MjData(self.model)
+        if self.standing_keyframe >= 0:
+            mujoco.mj_resetDataKeyframe(self.model, data, self.standing_keyframe)
+        elif self._home_qpos is not None:
+            data.qpos[:] = self._home_qpos
+        elif self.keyframe >= 0:
+            mujoco.mj_resetDataKeyframe(self.model, data, self.keyframe)
+        data.qpos[self.qpos_adr] = self.default_pose
+        return np.asarray(data.qpos, dtype=np.float64).copy()
+
+    def configure(self, cond: conditions_mod.Conditions) -> list[str]:
+        """Apply a cell's plant conditions (friction, gains); returns what could not be applied.
+
+        Always from the pristine copies taken at construction, so one cell's
+        `kd_scale` never leaks into the next.
+        """
+        notes: list[str] = []
+        self.cond = cond
+        self.model.geom_friction[:] = self._base_friction
+        self.model.actuator_gainprm[:] = self._base_gainprm
+        self.model.actuator_biasprm[:] = self._base_biasprm
+        self.kp, self.kd = self._base_kp, self._base_kd
+        if cond.friction is not None:
+            # sim2sim `--friction`: the sliding coefficient of every geom.
+            self.model.geom_friction[:, 0] = cond.friction
+        if cond.kp_scale != 1.0 or cond.kd_scale != 1.0:
+            if self.built is not None:
+                for a in self.built.ctrl_adr:
+                    if self.model.actuator_biasprm[a, 1] < 0:  # position servo
+                        self.model.actuator_gainprm[a, 0] *= cond.kp_scale
+                        self.model.actuator_biasprm[a, 1] *= cond.kp_scale
+                        self.model.actuator_biasprm[a, 2] *= cond.kd_scale
+                    elif self.model.actuator_biasprm[a, 2] < 0:  # velocity servo
+                        self.model.actuator_gainprm[a, 0] *= cond.kd_scale
+                        self.model.actuator_biasprm[a, 2] *= cond.kd_scale
+            else:
+                self.kp = self._base_kp * cond.kp_scale
+                self.kd = self._base_kd * cond.kd_scale
+        if cond.slew and not np.all(np.isfinite(self.velocity_limit)):
+            unlimited = [
+                self.contract.joint_order[k]
+                for k in range(len(self.velocity_limit))
+                if not np.isfinite(self.velocity_limit[k])
+            ]
+            notes.append(
+                "bridge slew: no `velocity_limit` declared for "
+                + ", ".join(unlimited)
+                + " — those joints are held to 1 rad/s until homed and not limited after"
+            )
+        if cond.fallen is not None and not self._foot_geoms:
+            raise ContractMismatch(
+                "a fallen start is scored on both feet touching the ground, and the robot's "
+                "interface declares no `feet` in the MJCF"
+            )
+        return notes
+
+    def reset(
+        self,
+        seed: int,
+        *,
+        protocol: str = PROTOCOL_M8,
+        category: str | None = None,
+    ) -> conditions_mod.FallenState | None:
+        """Put the robot in seed `seed`'s start state.
+
+        `m8` — M8's start, unchanged apart from the policy's own nominal pose:
+        joint noise ±0.02 rad and base yaw ±0.3 rad (a condition's `jitter` /
+        `yaw_jitter` replaces either). `sim2sim` — the founder's: the
+        `standing` keyframe with the policy joints at their nominal, jittered by
+        `default_rng(seed).uniform(±jitter)` and clipped to the joint ranges,
+        yaw untouched. A fallen category (a recovery cell) replaces both with
+        `sample_fallen`, draw for draw the founder's `--init-fallen`.
+        """
+        cond = self.cond
+        fallen_state: conditions_mod.FallenState | None = None
+        if category is not None:
+            fallen = cond.fallen
+            jitter = fallen.jitter_rad if fallen is not None else 0.26
+            mujoco.mj_resetData(self.model, self.data)
+            self.data.qpos[:] = self._harness_qpos
+            (
+                fallen_state,
+                base_pos,
+                base_quat,
+                joints,
+                base_vel,
+                joint_vel,
+            ) = conditions_mod.sample_fallen(
+                category=category,
+                seed=seed,
+                jitter_rad=jitter,
+                lower=self.range_lo,
+                upper=self.range_hi,
+                stand_height=self.stand_height or conditions_mod.LAIKA_STAND_HEIGHT_M,
+            )
+            assert self.base_qpos is not None and self.base_dof is not None
+            self.data.qpos[self.base_qpos : self.base_qpos + 3] = base_pos
+            self.data.qpos[self.base_qpos + 3 : self.base_qpos + 7] = base_quat
+            self.data.qpos[self.qpos_adr] = joints
+            self.data.qvel[:] = 0.0
+            self.data.qvel[self.base_dof : self.base_dof + 6] = base_vel
+            self.data.qvel[self.dof_adr] = joint_vel
+        elif protocol == PROTOCOL_SIM2SIM:
+            mujoco.mj_resetData(self.model, self.data)
+            self.data.qpos[:] = self._harness_qpos
+            if cond.jitter:
+                rng = np.random.default_rng(seed)
+                q = self.data.qpos[self.qpos_adr] + rng.uniform(
+                    -cond.jitter, cond.jitter, len(self.qpos_adr)
+                )
+                self.data.qpos[self.qpos_adr] = np.clip(q, self.range_lo, self.range_hi)
+                if cond.yaw_jitter and self.base_qpos is not None:
+                    self._set_yaw(float(rng.uniform(-cond.yaw_jitter, cond.yaw_jitter)))
+            elif cond.yaw_jitter and self.base_qpos is not None:
+                rng = np.random.default_rng(seed)
+                self._set_yaw(float(rng.uniform(-cond.yaw_jitter, cond.yaw_jitter)))
+            self.data.qvel[:] = 0.0
+        else:
+            self._reset_state()
+            rng = np.random.default_rng(seed)
+            joint_noise = JOINT_NOISE_RAD if cond.jitter is None else cond.jitter
+            yaw_noise = YAW_NOISE_RAD if cond.yaw_jitter is None else cond.yaw_jitter
+            self.data.qpos[self.qpos_adr] += rng.uniform(
+                -joint_noise, joint_noise, len(self.qpos_adr)
+            )
+            if self.base_qpos is not None:
+                self._set_yaw(float(rng.uniform(-yaw_noise, yaw_noise)))
+            self.data.qvel[:] = 0.0
+        self.data.qfrc_applied[:] = 0.0
+        mujoco.mj_forward(self.model, self.data)
+        self.time_s = 0.0
+        if self.history is not None:
+            self.history.reset()
+        return fallen_state
+
+    def _set_yaw(self, yaw: float) -> None:
+        assert self.base_qpos is not None
+        quat = np.zeros(4)
+        mujoco.mju_axisAngle2Quat(quat, np.array([0.0, 0.0, 1.0]), yaw)
+        self.data.qpos[self.base_qpos + 3 : self.base_qpos + 7] = quat
+
+    def _fresh_base(self) -> bool:
+        """Read the base from `qpos` (current) rather than `xpos`/`xmat` (one substep old)?
+
+        `mj_step` runs its forward pass BEFORE it integrates, so after a step
+        `data.xpos` / `data.xmat` describe the state the step STARTED from
+        while `data.qpos` is already the new one. M8 read the derived arrays,
+        so its `projected_gravity` (and the rotation it applies to the base
+        velocity) lagged the joints by one physics substep. Nothing computed
+        the same quantity a second way, so nobody saw it — until M17b's
+        trainer, which derives the base from the rollout's output `qpos`, and
+        a parity test found the two disagreeing by 1.3% on a moving Laika.
+
+        On the interface path the gate now reads `qpos` too: the policy is
+        shown the current state, and trainer and gate are identical. The
+        legacy path (a card with no `interface`) is deliberately left exactly
+        as M8 shipped it — "every existing battery is unchanged" includes the
+        numbers the published policies were gated under; the staleness there
+        is reported in docs/DECISIONS.md rather than silently changed.
+        """
+        return self.built is not None and self.base_qpos is not None
+
+    def base_position(self) -> np.ndarray:
+        if self._fresh_base():
+            assert self.base_qpos is not None
+            return np.asarray(
+                self.data.qpos[self.base_qpos : self.base_qpos + 3], dtype=np.float64
+            ).copy()
+        return np.asarray(self.data.xpos[self.base_body], dtype=np.float64)
+
+    def base_rotation(self) -> np.ndarray:
+        if self._fresh_base() and not self.stale_rotation:
+            assert self.base_qpos is not None
+            quat = np.asarray(
+                self.data.qpos[self.base_qpos + 3 : self.base_qpos + 7], dtype=np.float64
+            )
+            matrix = np.zeros(9)
+            mujoco.mju_quat2Mat(matrix, quat / np.linalg.norm(quat))
+            return matrix.reshape(3, 3)
+        return np.asarray(self.data.xmat[self.base_body], dtype=np.float64).reshape(3, 3)
+
+    def base_velocity_body(self) -> tuple[np.ndarray, np.ndarray]:
+        """`(linear, angular)` in the base frame. Zero on a fixed base."""
+        if self.base_dof is None:
+            return np.zeros(3), np.zeros(3)
+        rot = self.base_rotation()
+        lin_world = np.asarray(self.data.qvel[self.base_dof : self.base_dof + 3])
+        ang_body = np.asarray(self.data.qvel[self.base_dof + 3 : self.base_dof + 6])
+        return np.asarray(rot.T @ lin_world, dtype=np.float64), ang_body.astype(np.float64)
+
+    def projected_gravity(self) -> np.ndarray:
+        return np.asarray(self.base_rotation().T @ np.array([0.0, 0.0, -1.0]), dtype=np.float64)
+
+    def mirror_pairs(self) -> list[tuple[int, int, int]]:
+        """`(left, right, sign)` per mirrored joint pair of the contract (C3, `posture`).
+
+        Indices into `contract.joint_order`; the sign is read from the joint
+        axes at the model's reference pose, in the base frame. Computed once.
+        """
+        cached = getattr(self, "_mirror_pairs", None)
+        if cached is not None:
+            return list(cached)
+        scratch = mujoco.MjData(self.model)
+        scratch.qpos[:] = self.model.qpos0
+        mujoco.mj_kinematics(self.model, scratch)
+        base_rot = np.asarray(scratch.xmat[self.base_body], dtype=np.float64).reshape(3, 3)
+        out: list[tuple[int, int, int]] = []
+        for left, right in posture_mod.mirror_name_pairs(list(self.contract.joint_order)):
+            axis_l = base_rot.T @ np.asarray(scratch.xaxis[self.joint_ids[left]], dtype=np.float64)
+            axis_r = base_rot.T @ np.asarray(scratch.xaxis[self.joint_ids[right]], dtype=np.float64)
+            sign = posture_mod.mirror_sign(axis_l, axis_r)
+            if sign is not None:
+                out.append((left, right, sign))
+        self._mirror_pairs = out
+        return list(out)
+
+    def tilt_deg(self) -> float:
+        """Angle between the base's z axis and the world's — sim2sim's `tilts`."""
+        return float(math.degrees(math.acos(max(-1.0, min(1.0, self.base_rotation()[2, 2])))))
+
+    def yaw(self) -> float:
+        if self.base_qpos is None:
+            return 0.0
+        return _yaw_of(self.data.qpos[self.base_qpos + 3 : self.base_qpos + 7])
+
+    def upright(self) -> bool:
+        if self.fixed_base:
+            return True
+        height = float(self.base_position()[2])
+        return (
+            height >= UPRIGHT_HEIGHT_FRACTION * self.init_height
+            and float(self.projected_gravity()[2]) <= UPRIGHT_GRAVITY_Z
+        )
+
+    def foot_forces(self) -> list[float]:
+        """Normal contact force on each declared foot (N), summed over its contacts."""
+        out = [0.0] * len(self._foot_geoms)
+        force = np.zeros(6)
+        for i in range(self.data.ncon):
+            contact = self.data.contact[i]
+            for k, geoms in enumerate(self._foot_geoms):
+                if contact.geom1 in geoms or contact.geom2 in geoms:
+                    mujoco.mj_contactForce(self.model, self.data, i, force)
+                    out[k] += abs(float(force[0]))
+        return out
+
+    # -- the contract's observation ---------------------------------------
+
+    def frame(
+        self,
+        command: np.ndarray,
+        last_action: np.ndarray,
+        *,
+        joint_target: np.ndarray | None = None,
+        ee_target: np.ndarray | None = None,
+    ) -> obs_registry.Frame:
+        """This instant as a one-env :class:`Frame` — what every block builder reads."""
+        lin, ang = self.base_velocity_body()
+        ee = self.ee_position()
+        return obs_registry.Frame(
+            joint_pos=np.asarray(self.data.qpos[self.qpos_adr], dtype=np.float64)[None],
+            joint_vel=np.asarray(self.data.qvel[self.dof_adr], dtype=np.float64)[None],
+            default_pose=self.default_pose,
+            last_action=np.asarray(last_action, dtype=np.float64)[None],
+            base_lin_vel=lin[None],
+            base_ang_vel=ang[None],
+            projected_gravity=self.projected_gravity()[None],
+            base_height=np.array([float(self.base_position()[2])]),
+            time_s=np.array([self.time_s]),
+            command=np.asarray(command, dtype=np.float64)[None],
+            cycle_time_s=self.contract.cycle_time_s,
+            joint_target=None if joint_target is None else joint_target[None],
+            ee_pos=None if ee is None else ee[None],
+            ee_target=None if ee_target is None else ee_target[None],
+        )
+
+    def observe(
+        self,
+        command: np.ndarray,
+        last_action: np.ndarray,
+        *,
+        joint_target: np.ndarray | None = None,
+        ee_target: np.ndarray | None = None,
+    ) -> np.ndarray:
+        """The contract's observation, in its order and scales.
+
+        `frame_hist` (C2) is built from the same scaled terms as the head of
+        the observation and advances exactly once per call — `observe` is
+        called once per control step, as `PolicyIO.build_obs` requires.
+        """
+        frame = self.frame(command, last_action, joint_target=joint_target, ee_target=ee_target)
+        try:
+            parts: list[np.ndarray] = []
+            scaled: dict[str, np.ndarray] = {}
+            for block in self.contract.obs_spec:
+                if block.name == harness.HISTORY_BLOCK:
+                    parts.append(np.zeros(0, dtype=np.float32))  # placeholder, filled below
+                    continue
+                value = obs_registry.build_observation(frame, [(block.name, block.scale)])[0]
+                scaled[obs_registry.resolve(block.name).name] = value
+                parts.append(value)
+            if self.history is not None:
+                current = np.concatenate(
+                    [scaled[obs_registry.resolve(t).name] for t in harness.HIST_FRAME_TERMS]
+                )
+                block_value = self.history.block(current)
+                for index, block in enumerate(self.contract.obs_spec):
+                    if block.name == harness.HISTORY_BLOCK:
+                        parts[index] = block_value
+            return np.asarray(np.concatenate(parts), dtype=np.float32)
+        except (obs_registry.UnknownObsTerm, ValueError, KeyError) as exc:
+            raise ContractMismatch(f"cannot build the observation: {exc}") from exc
+
+    # -- one control step --------------------------------------------------
+
+    def phase(self) -> float | None:
+        cycle = self.contract.cycle_time_s
+        return None if cycle is None else (self.time_s / cycle) % 1.0
+
+    def command_for(self, action: np.ndarray, *, command: np.ndarray | None = None) -> np.ndarray:
+        """The per-joint command an action means, under the contract's semantics.
+
+        `position_offset` (every contract before M17b): `default_pose + scale *
+        action`. `position_absolute`, `velocity` and `torque` drop the pose.
+        Position targets are clamped to the contract's `target_lo/hi` when it
+        carries them and to the joint range when the plant came from an
+        interface — a target past a hard stop is a fight with the limit, not a
+        command. C2 adds policy_io's two extras: the `omni_ff` lateral
+        feed-forward (on the commanded `vy` and the phase clock) and the
+        β-anchored recovery contract, `target = q + β · action`.
+        """
+        clip = self.contract.action_clip
+        action = np.clip(np.asarray(action, dtype=np.float64), -clip, clip)
+        semantics = self.contract.action_semantics
+        if self.beta is not None:
+            out = np.asarray(self.data.qpos[self.qpos_adr], dtype=np.float64) + self.beta * action
+        else:
+            scaled = self.contract.action_scale * action
+            out = self.default_pose + scaled if semantics == "position_offset" else scaled
+            if self.lat_ff is not None:
+                vy = float(command[1]) if command is not None else 0.0
+                out = out + self.lat_ff.offset(len(out), vy, self.phase() or 0.0)
+        if semantics.startswith("position") or self.beta is not None:
+            if self.contract.target_lo is not None and self.contract.target_hi is not None:
+                out = np.clip(out, self.contract.target_lo, self.contract.target_hi)
+            if self.built is not None:
+                out = np.clip(out, self.built.lower, self.built.upper)
+        return np.asarray(out, dtype=np.float64)
+
+    def gains(self) -> tuple[np.ndarray, np.ndarray]:
+        """Per-joint `(kp, kd)` the plant drives with right now (after `kp_scale`/`kd_scale`)."""
+        n = len(self.qpos_adr)
+        if self.built is not None:
+            kp = np.asarray([self.model.actuator_gainprm[a, 0] for a in self.built.ctrl_adr])
+            kd = np.asarray([-self.model.actuator_biasprm[a, 2] for a in self.built.ctrl_adr])
+            return kp, kd
+        return np.full(n, self.kp), np.full(n, self.kd)
+
+    def step(
+        self,
+        action: np.ndarray,
+        *,
+        target: np.ndarray | None = None,
+        torque_probe: Callable[[np.ndarray, bool], None] | None = None,
+    ) -> np.ndarray:
+        """Apply one policy action for `decimation` physics steps; returns the joint command.
+
+        `target` (C2) overrides the command the action would give — the bridge
+        slew and the delay line sit between the policy and the PD loop.
+        `torque_probe` is called before every physics substep with the PD
+        demand BEFORE the effort clip and whether it is the control step's
+        last substep (the recovery gate's torque bookkeeping: sim2sim's
+        `tau_demand_peak` per substep and `tau_demand_peak_ctrlrate` at the
+        control-step boundary).
+        """
+        if target is None:
+            target = self.command_for(action)
+        kp_v, kd_v = self.gains() if torque_probe is not None else (None, None)
+        if self.built is not None:
+            # Interface path: the servo (or motor) the plant builder compiled
+            # runs the loop inside mj_step, at the physics rate, with the
+            # robot's own per-group gains and effort limits.
+            self.data.ctrl[self.built.ctrl_adr] = target
+            for sub in range(self.decimation):
+                if torque_probe is not None:
+                    assert kp_v is not None and kd_v is not None
+                    torque_probe(
+                        kp_v * (target - self.data.qpos[self.qpos_adr])
+                        - kd_v * self.data.qvel[self.dof_adr],
+                        sub == self.decimation - 1,
+                    )
+                mujoco.mj_step(self.model, self.data)
+            self.time_s += self.control_dt
+            return target
+        if self.contract.action_semantics != "position_offset" and self.beta is None:
+            raise ContractMismatch(
+                f"action semantics `{self.contract.action_semantics}` needs a robot card with "
+                "an `interface` (it declares the actuators); this card has none"
+            )
+        for sub in range(self.decimation):
+            q = self.data.qpos[self.qpos_adr]
+            qd = self.data.qvel[self.dof_adr]
+            demand = self.kp * (target - q) - self.kd * qd
+            if torque_probe is not None:
+                torque_probe(np.asarray(demand, dtype=np.float64), sub == self.decimation - 1)
+            tau = np.clip(demand, -self.tau_limit, self.tau_limit)
+            self.data.qfrc_applied[:] = 0.0
+            for k, dof in enumerate(self.dof_adr):
+                actuator = self.actuator_of.get(k)
+                if actuator is None:
+                    self.data.qfrc_applied[dof] = tau[k]
+                else:
+                    index, position_servo = actuator
+                    self.data.ctrl[index] = target[k] if position_servo else tau[k]
+            mujoco.mj_step(self.model, self.data)
+        self.time_s += self.control_dt
+        return target
+
+    def push(self, impulse: float, axis: int) -> None:
+        """sim2sim `--push`: `impulse / total mass` added to the base's world velocity."""
+        if self.base_dof is None:
+            return
+        self.data.qvel[self.base_dof + axis] += impulse / self._total_mass
+
+
+# ---------------------------------------------------------------------------
+# Episodes and cells
+# ---------------------------------------------------------------------------
+
+
+def _wire_metrics(metrics: dict[str, float]) -> dict[str, float | None]:
+    """`inf` (a window with no sample) is not JSON; on the wire it is null.
+
+    Null means "could not be measured" and the hub scores it as such — it is
+    deliberately NOT zero, which would read as a perfect result.
+    """
+    return {k: (float(v) if math.isfinite(v) else None) for k, v in metrics.items()}
+
+
+@dataclass
+class EpisodeResult:
+    seed: int
+    alive: bool
+    fell_at_s: float | None
+    tracking: dict[str, float]
+    steps: int
+    trajectory: dict[str, Any] | None = None
+    #: M17b. `settle_error` / `tracking_error` / `limit_violations`; empty for
+    #: a velocity cell on a floating base, which is scored on `alive` + `tracking`.
+    metrics: dict[str, float] = field(default_factory=dict)
+    #: C2. The fallen category a recovery episode started in.
+    category: str | None = None
+
+    def as_measurement(self) -> dict[str, Any]:
+        out: dict[str, Any] = {
+            "seed": self.seed,
+            "alive": self.alive,
+            "fell_at_s": self.fell_at_s,
+            "tracking": dict(self.tracking),
+        }
+        if self.metrics:
+            out["metrics"] = _wire_metrics(self.metrics)
+        if self.category is not None:
+            out["category"] = self.category
+        return out
+
+
+@dataclass
+class CellResult:
+    name: str
+    command: dict[str, float]
+    episodes: list[EpisodeResult] = field(default_factory=list)
+    video_path: Path | None = None
+    traj_path: Path | None = None
+    kind: str = "velocity"
+    fixed_base: bool = False
+    #: C2. `sim2sim` aggregates tracking the harness's way.
+    protocol: str = PROTOCOL_M8
+    #: C2. `{view: mp4}` — side / front / feet — when the three-view recorder ran.
+    videos: dict[str, Path] = field(default_factory=dict)
+    #: C3. The cell's rule (`posture` logs its posture medians).
+    score: str | None = None
+    #: L1. The poster (`video: poster`) and when in seed 0's episode it was taken.
+    poster_path: Path | None = None
+    poster_t_s: float | None = None
+
+    @property
+    def metrics(self) -> dict[str, float]:
+        """Worst case over the seeds: a gate is about the seed that went wrong.
+
+        Errors take the max; `limit_violations` sums (it is a count of steps).
+        Only M17b's three target metrics aggregate this way; the recovery and
+        harness metrics live per episode and the hub aggregates those.
+        """
+        out: dict[str, float] = {}
+        for episode in self.episodes:
+            for key, value in episode.metrics.items():
+                if key not in TARGET_METRICS:
+                    continue
+                if key == "limit_violations":
+                    out[key] = out.get(key, 0.0) + value
+                else:
+                    out[key] = max(out.get(key, value), value)
+        return out
+
+    @property
+    def seeds(self) -> int:
+        return len(self.episodes)
+
+    @property
+    def alive(self) -> int:
+        return sum(1 for e in self.episodes if e.alive)
+
+    @property
+    def tracking(self) -> dict[str, float]:
+        """Per commanded axis over the seeds: M8's mean over every seed, or —
+        under the `sim2sim` protocol — `eval_c_matrix.cell`'s median over the
+        seeds that stayed alive (the aggregate the imported scorecards were
+        converted from)."""
+        axes = [a for a in ("vx", "vy", "yaw") if abs(self.command.get(a, 0.0)) > 1e-9]
+        out: dict[str, float] = {}
+        for axis in axes:
+            if self.protocol == PROTOCOL_SIM2SIM:
+                values = sorted(
+                    e.tracking[axis] for e in self.episodes if e.alive and axis in e.tracking
+                )
+                if values:
+                    out[axis] = float(values[len(values) // 2])
+                continue
+            values = [e.tracking[axis] for e in self.episodes if axis in e.tracking]
+            if values:
+                out[axis] = float(np.mean(values))
+        return out
+
+    def as_measurement(self) -> dict[str, Any]:
+        out: dict[str, Any] = {
+            "name": self.name,
+            "command": dict(self.command),
+            "seeds": self.seeds,
+            "alive": self.alive,
+            "tracking": self.tracking,
+            "episodes": [e.as_measurement() for e in self.episodes],
+            "kind": self.kind,
+            "fixed_base": self.fixed_base,
+        }
+        if self.metrics:
+            out["metrics"] = _wire_metrics(self.metrics)
+        return out
+
+
+#: M17b's three per-cell target metrics.
+TARGET_METRICS = frozenset({"settle_error", "tracking_error", "limit_violations"})
+
+
+def resolve_targets(sim: Simulator, cell: dict[str, Any]) -> tuple[str, Any, Any, list[str]]:
+    """`(kind, joint_target, ee_target, notes)` for one battery cell.
+
+    Targets are **offsets**, which is what makes a battery portable across
+    robots: `joint_offsets` is radians from the default pose, `ee_offset` is
+    metres from where the end effector sits AT the default pose. A joint
+    target outside the soft limits is clamped to them and the clamp is
+    reported — scoring a policy against a pose the robot may not take would
+    measure the battery, not the policy.
+    """
+    kind = str(cell.get("kind") or "velocity")
+    if kind not in CELL_KINDS:
+        raise ContractMismatch(
+            f"battery cell `{cell.get('name')}` has kind `{kind}`; this engine runs "
+            f"{', '.join(CELL_KINDS)}"
+        )
+    notes: list[str] = []
+    joint_target = ee_target = None
+    if kind == "joint_target":
+        offsets = cell.get("joint_offsets") or {}
+        strangers = sorted(set(offsets) - set(sim.contract.joint_order))
+        if strangers:
+            raise ContractMismatch(
+                f"cell `{cell.get('name')}`: joint_offsets names joints outside the contract: "
+                + ", ".join(strangers)
+            )
+        wanted = sim.default_pose + np.asarray(
+            [float(offsets.get(j, 0.0)) for j in sim.contract.joint_order]
+        )
+        joint_target = np.clip(wanted, sim.soft_lo, sim.soft_hi)
+        moved = [
+            sim.contract.joint_order[k]
+            for k in range(len(wanted))
+            if abs(wanted[k] - joint_target[k]) > 1e-9
+        ]
+        if moved:
+            notes.append(
+                f"{cell.get('name')}: target clamped to the soft limits on {', '.join(moved)}"
+            )
+    elif kind == "reach":
+        if sim.ee_name is None:
+            raise ContractMismatch(
+                f"cell `{cell.get('name')}` is a `reach` cell, but the robot's interface "
+                "declares no end effector with a site or body in the MJCF"
+            )
+        sim._reset_state()
+        home = sim.ee_position()
+        assert home is not None
+        offset = cell.get("ee_offset") or [0.0, 0.0, 0.0]
+        if len(offset) != 3:
+            raise ContractMismatch(f"cell `{cell.get('name')}`: ee_offset must be [dx, dy, dz]")
+        ee_target = home + np.asarray([float(v) for v in offset])
+    return kind, joint_target, ee_target, notes
+
+
+class _RecoveryTally:
+    """sim2sim's `--init-fallen` bookkeeping, step for step (C2).
+
+    Success: tilt < 15°, base height > 0.85 x standing height, both feet
+    pressing the ground (> 5 N) and |ω| < 1 rad/s, held for 0.5 s — the first
+    step of the first such window is the stand-up time. `end_good` is the last
+    step's verdict (sim2sim); `end_hold` is whether the whole last 0.5 s held
+    (`accept_recovery.py`'s re-fall reading, which does not trust one frame).
+    Torque demand is the PD's BEFORE the effort clip, skipping the first
+    0.5 s (the drop onto the floor is not the stand-up's demand), read twice
+    as sim2sim reads it: the peak over every physics substep (`tau_frac`)
+    and the peak of the one sample at each control-step boundary
+    (`tau_frac_ctrl`) — which is what `accept_recovery.py`'s ⑤ reads
+    (Isaac's `computed_torque` at 50 Hz), and so what the hub gates on.
+    """
+
+    def __init__(self, sim: Simulator) -> None:
+        self.sim = sim
+        self.hold = max(1, round(RECOVERY_HOLD_S * sim.control_rate_hz))
+        self.settle = max(0, round(RECOVERY_TORQUE_SETTLE_S * sim.control_rate_hz))
+        self.h_gate = RECOVERY_HEIGHT_FRACTION * (sim.stand_height or sim.init_height)
+        self.run = 0
+        self.first = -1
+        self.good: list[bool] = []
+        n = len(sim.qpos_adr)
+        self.tau_peak = np.zeros(n)
+        self.tau_peak_ctrl = np.zeros(n)
+        self.tau_sat = np.zeros(n)
+        self.tau_samples = 0
+        self.act_sat = np.zeros(n)
+        self.act_samples = 0
+        self.step_index = 0
+
+    def probe(self, demand: np.ndarray, last_substep: bool = False) -> None:
+        if self.step_index < self.settle:
+            return
+        magnitude = np.abs(demand)
+        np.maximum(self.tau_peak, magnitude, out=self.tau_peak)
+        if last_substep:
+            np.maximum(self.tau_peak_ctrl, magnitude, out=self.tau_peak_ctrl)
+        self.tau_sat += magnitude > self.sim.tau_limit
+        self.tau_samples += 1
+
+    def after_step(self, index: int, raw_action: np.ndarray) -> None:
+        sim = self.sim
+        feet = sim.foot_forces()
+        _lin, ang = sim.base_velocity_body()
+        ok = (
+            sim.tilt_deg() < RECOVERY_TILT_DEG
+            and float(sim.base_position()[2]) > self.h_gate
+            and len(feet) >= 2
+            and all(f > RECOVERY_FOOT_N for f in feet)
+            and float(np.linalg.norm(ang)) < RECOVERY_OMEGA
+        )
+        self.good.append(ok)
+        self.run = self.run + 1 if ok else 0
+        if self.run >= self.hold and self.first < 0:
+            self.first = index - self.run + 1
+        self.act_sat += np.abs(raw_action) >= RECOVERY_ACTION_SAT
+        self.act_samples += 1
+        self.step_index = index + 1
+
+    def metrics(self) -> dict[str, float]:
+        rate = self.sim.control_rate_hz
+        success = self.first >= 0
+        end_hold = len(self.good) >= self.hold and all(self.good[-self.hold :])
+        out: dict[str, float] = {
+            "recover_success": 1.0 if success else 0.0,
+            "recover_time_s": (self.first / rate) if success else float("inf"),
+            "end_good": 1.0 if (self.good and self.good[-1]) else 0.0,
+            "end_hold": 1.0 if end_hold else 0.0,
+            "refall": 1.0 if (success and not end_hold) else 0.0,
+        }
+        limit = np.where(np.isfinite(self.sim.tau_limit), self.sim.tau_limit, np.nan)
+        with np.errstate(invalid="ignore", divide="ignore"):
+            frac = self.tau_peak / limit
+            frac_ctrl = self.tau_peak_ctrl / limit
+        for name, value, sampled in zip(
+            self.sim.contract.joint_order, frac, frac_ctrl, strict=True
+        ):
+            out[f"tau_frac.{name}"] = float(value) if np.isfinite(value) else float("inf")
+            out[f"tau_frac_ctrl.{name}"] = float(sampled) if np.isfinite(sampled) else float("inf")
+        if self.act_samples:
+            for name, value in zip(
+                self.sim.contract.joint_order, self.act_sat / self.act_samples, strict=True
+            ):
+                out[f"sat.{name}"] = float(value)
+        return out
+
+
+def run_episode(
+    sim: Simulator,
+    policy: Policy,
+    *,
+    command: dict[str, float],
+    seed: int,
+    horizon_s: float,
+    record: bool = False,
+    frame_sink: FrameSink | None = None,
+    cell: dict[str, Any] | None = None,
+    protocol: str = PROTOCOL_M8,
+    category: str | None = None,
+) -> EpisodeResult:
+    """One episode: reset, run the contract's loop, measure.
+
+    A `velocity` cell on a floating base measures survival and per-axis
+    tracking, as M8 did. Everything else — `joint_target`, `reach`, and ANY
+    cell on a fixed base — also measures an error against a target (for a
+    velocity cell on a fixed base that target is the default pose: "hold")
+    plus soft-limit violations, because on a fixed base `upright()` is true by
+    construction and proves nothing.
+
+    C2: the cell's conditions (`sim.configure` was called by the battery)
+    shape the loop the way `sim2sim.py` shapes it — heading → observe → act →
+    power scale → target (feed-forward / β anchor) → bridge slew → delay →
+    push → PD substeps — and the `sim2sim` protocol measures survival and
+    tracking with the harness's own definitions. A `recovery` cell starts
+    fallen (`category`), never ends early, and measures the stand-up.
+    """
+    kind, joint_target, ee_target, _notes = resolve_targets(sim, cell or {})
+    cond = sim.cond
+    recovery = kind == "recovery"
+    fallen = sim.reset(seed, protocol=protocol, category=category if recovery else None)
+    cmd = np.array([command.get("vx", 0.0), command.get("vy", 0.0), command.get("yaw", 0.0)])
+    last_action = np.zeros(sim.contract.action_dim)
+    steps = max(1, math.ceil(horizon_s * sim.control_rate_hz))
+    settle = min(SETTLE_S, horizon_s / 4.0)
+    settle_from = horizon_s * (1.0 - SETTLE_WINDOW_FRACTION)
+    measure_error = kind in ("joint_target", "reach") or (kind == "velocity" and sim.fixed_base)
+    if kind == "velocity" and sim.fixed_base:
+        # "Stand" on a fixed base means "hold the default pose". It is scored
+        # that way, so a policy that observes `joint_target` must be shown
+        # that same target — not nothing.
+        joint_target = sim.default_pose.copy()
+    hold_target = joint_target
+    harness_mode = protocol == PROTOCOL_SIM2SIM
+    # C3: posture — tilt, mirrored-pair asymmetry, drift — on a `posture` cell,
+    # and on every sim2sim episode on a floating base (whose tilt it already read).
+    track_posture = (
+        not sim.fixed_base
+        and not recovery
+        and kind == "velocity"
+        and (harness_mode or (cell or {}).get("score") == "posture")
+    )
+    pairs = sim.mirror_pairs() if track_posture else []
+    pair_left = np.asarray([p[0] for p in pairs], dtype=np.intp)
+    pair_right = np.asarray([p[1] for p in pairs], dtype=np.intp)
+    pair_sign = np.asarray([p[2] for p in pairs], dtype=np.float64)
+    asym_sum = np.zeros(len(pairs))
+    asym_samples = 0
+    start_q = np.asarray(sim.data.qpos[sim.qpos_adr], dtype=np.float64).copy()
+    delay = conditions_mod.DelayLine(start_q, delay=cond.delay, jitter=cond.delay_jitter, seed=seed)
+    slew = conditions_mod.Slew(start_q, sim.velocity_limit, sim.control_dt) if cond.slew else None
+    yaw0 = sim.yaw()
+    tally = _RecoveryTally(sim) if recovery else None
+    fall_height = HARNESS_FALL_FRACTION * sim.stand_height
+    sums = np.zeros(3)
+    samples = 0
+    err_track: list[float] = []
+    err_settle: list[float] = []
+    violations = 0
+    fell_at: float | None = None
+    # sim2sim's arrays (only what the gate and the parity table read).
+    h_vels: list[tuple[float, float]] = []
+    h_yaws: list[float] = [yaw0]
+    h_heights: list[float] = []
+    h_tilts: list[float] = []
+    h_raw: list[np.ndarray] = []
+    # C3b: the base's horizontal speed per control step, and the step a push
+    # landed on — for the recovery time after it.
+    h_speed: list[float] = []
+    push_index: int | None = None
+    xy0 = sim.base_position()[:2].copy() if not sim.fixed_base else np.zeros(2)
+    traj: dict[str, list[Any]] | None = (
+        {"t": [], "joint_pos": [], "action": [], "target": [], "base_pos": [], "base_vel": []}
+        if record
+        else None
+    )
+    if traj is not None and measure_error:
+        traj["error"] = []
+    if traj is not None and recovery:
+        traj["tilt_deg"] = []
+    if frame_sink is not None:
+        frame_sink(sim.data, 0.0)
+    for index in range(steps):
+        if cond.heading and not sim.fixed_base:
+            error = conditions_mod.wrap(yaw0 - sim.yaw())
+            cmd[2] = float(
+                np.clip(
+                    cond.heading_k * error,
+                    -conditions_mod.HEADING_MAX_RATE,
+                    conditions_mod.HEADING_MAX_RATE,
+                )
+            )
+        obs = sim.observe(cmd, last_action, joint_target=joint_target, ee_target=ee_target)
+        raw = policy(obs)
+        clip = sim.contract.action_clip
+        acted = np.clip(raw, -clip, clip) * cond.power_scale
+        target = sim.command_for(acted, command=cmd)
+        if slew is not None:
+            target = slew(target)
+        target = delay(target)
+        if cond.push is not None and abs(index / sim.control_rate_hz - cond.push.at_s) < (
+            0.5 / sim.control_rate_hz
+        ):
+            sim.push(cond.push.impulse, cond.push.axis)
+            push_index = index
+        sim.step(acted, target=target, torque_probe=tally.probe if tally else None)
+        last_action = acted
+        t = sim.time_s
+        lin, ang = sim.base_velocity_body()
+        if t >= settle:
+            sums += np.array([lin[0], lin[1], ang[2]])
+            samples += 1
+        if harness_mode or tally is not None or track_posture:
+            h_vels.append((float(lin[0]), float(lin[1])))
+            h_yaws.append(sim.yaw())
+            h_heights.append(float(sim.base_position()[2]))
+            h_tilts.append(sim.tilt_deg())
+            h_raw.append(np.asarray(raw, dtype=np.float64))
+            if track_posture and sim.base_dof is not None:
+                v = sim.data.qvel[sim.base_dof : sim.base_dof + 2]
+                h_speed.append(float(math.hypot(float(v[0]), float(v[1]))))
+        if pairs and t >= settle:
+            q_now = np.asarray(sim.data.qpos[sim.qpos_adr], dtype=np.float64)
+            asym_sum += q_now[pair_left] - pair_sign * q_now[pair_right]
+            asym_samples += 1
+        if tally is not None:
+            tally.after_step(index, np.asarray(raw, dtype=np.float64))
+        error_value: float | None = None
+        if measure_error:
+            if kind == "reach":
+                ee = sim.ee_position()
+                assert ee is not None and ee_target is not None
+                error_value = float(np.linalg.norm(ee - ee_target))
+            else:
+                assert hold_target is not None
+                # The WORST joint, not an RMS: one joint far off must not hide
+                # behind five that are close.
+                error_value = float(np.max(np.abs(sim.data.qpos[sim.qpos_adr] - hold_target)))
+            if t >= settle:
+                err_track.append(error_value)
+            if t >= settle_from:
+                err_settle.append(error_value)
+            if sim.limit_violation():
+                violations += 1
+        if traj is not None:
+            traj["t"].append(round(t, 4))
+            traj["joint_pos"].append([round(float(v), 4) for v in sim.data.qpos[sim.qpos_adr]])
+            traj["action"].append([round(float(v), 4) for v in last_action])
+            traj["target"].append([round(float(v), 4) for v in target])
+            traj["base_pos"].append([round(float(v), 4) for v in sim.base_position()])
+            traj["base_vel"].append(
+                [round(float(lin[0]), 4), round(float(lin[1]), 4), round(float(ang[2]), 4)]
+            )
+            if error_value is not None:
+                traj["error"].append(round(error_value, 5))
+            if recovery:
+                traj["tilt_deg"].append(round(h_tilts[-1], 2))
+        if frame_sink is not None:
+            frame_sink(sim.data, t)
+        if recovery:
+            continue  # lying down is a legal state; getting back up is the task
+        if harness_mode and not sim.fixed_base:
+            if h_heights[-1] < fall_height:
+                fell_at = round(t, 3)
+                break
+        elif not sim.upright():
+            fell_at = round(t, 3)
+            break
+    tracking: dict[str, float] = {}
+    metrics: dict[str, float] = {}
+    alive = fell_at is None
+    if harness_mode and not sim.fixed_base and not recovery:
+        # sim2sim's own readings: alive = the last height and tilt, body-frame
+        # vx/vy averaged after the first second, and the yaw rate from the
+        # net world-yaw change (the body-frame rate is biased by the sway).
+        rate = sim.control_rate_hz
+        duration = len(h_heights) / rate if h_heights else 0.0
+        alive = bool(
+            h_heights
+            and h_heights[-1] > HARNESS_ALIVE_FRACTION * sim.stand_height
+            and h_tilts[-1] < HARNESS_ALIVE_TILT_DEG
+        )
+        if not alive and fell_at is None:
+            fell_at = round(duration, 3)
+        window = h_vels[int(rate) :] or h_vels
+        vx_mean = float(np.mean([v[0] for v in window])) if window else 0.0
+        vy_mean = float(np.mean([v[1] for v in window])) if window else 0.0
+        dyaw = float(np.unwrap(np.asarray(h_yaws))[-1] - h_yaws[0]) if len(h_yaws) > 1 else 0.0
+        yaw_rate = dyaw / duration if duration else 0.0
+        measured = {"vx": vx_mean, "vy": vy_mean, "yaw": yaw_rate}
+        for axis in ("vx", "vy", "yaw"):
+            if abs(cmd_of(command, axis)) > 1e-9:
+                tracking[axis] = measured[axis] / cmd_of(command, axis)
+        dxy = sim.base_position()[:2] - xy0
+        metrics = {
+            "vx_mean": vx_mean,
+            "vy_mean": vy_mean,
+            "dyaw_deg": math.degrees(dyaw),
+            "dx": float(dxy[0]),
+            "dy": float(dxy[1]),
+            "tilt_max_deg": float(max(h_tilts)) if h_tilts else float("inf"),
+            "t": duration,
+        }
+        if h_raw:
+            tail = np.abs(np.asarray(h_raw[len(h_raw) // 3 :]))
+            if len(tail):
+                metrics["sat_max_pct"] = float(
+                    ((tail >= sim.contract.action_clip - 1e-6).mean(axis=0) * 100).max()
+                )
+    elif not recovery:
+        # M8: the mean body-frame velocity after the settle, per commanded axis
+        # of the CELL's command (a heading loop may rewrite the yaw it sends).
+        measured_v = sums / samples if samples else np.zeros(3)
+        for index_axis, axis in enumerate(("vx", "vy", "yaw")):
+            commanded = cmd_of(command, axis)
+            if abs(commanded) > 1e-9:
+                tracking[axis] = float(measured_v[index_axis] / commanded) if samples else 0.0
+    if track_posture:
+        # C3 (lucen_cli.rollout.posture): the worst pair's settled asymmetry,
+        # the episode's maximum tilt, and how far the base wandered. A robot
+        # with no mirrored pair reports `asym_pairs: 0` and no asymmetry; an
+        # episode that ended before the settle reports inf, never a zero.
+        dxy_end = sim.base_position()[:2] - xy0
+        metrics["tilt_max_deg"] = float(max(h_tilts)) if h_tilts else float("inf")
+        metrics["drift_m"] = float(math.hypot(float(dxy_end[0]), float(dxy_end[1])))
+        metrics["asym_pairs"] = float(len(pairs))
+        if pairs:
+            metrics["asym_max_deg"] = (
+                float(posture_mod.pair_asymmetry_deg(asym_sum / asym_samples).max())
+                if asym_samples
+                else float("inf")
+            )
+        if cond.push is not None:
+            # C3b: how long the base took to settle after the push. A seed
+            # that fell, or never settled, reports the whole window that was
+            # left after the push — a number at least as bad as any bar, never
+            # a null that a median would quietly leave out.
+            window_s = max(0.0, horizon_s - cond.push.at_s)
+            metrics["recover_s"] = push_recovery_s(
+                h_tilts,
+                h_speed,
+                push_index=push_index,
+                rate_hz=sim.control_rate_hz,
+                fell=fell_at is not None,
+                window_s=window_s,
+            )
+            metrics["recovered"] = 1.0 if metrics["recover_s"] < window_s else 0.0
+    if measure_error:
+        # No sample in a window means the episode ended before it: report inf,
+        # never a flattering zero.
+        metrics.update(
+            {
+                "settle_error": float(np.mean(err_settle)) if err_settle else float("inf"),
+                "tracking_error": float(np.mean(err_track)) if err_track else float("inf"),
+                "limit_violations": float(violations),
+            }
+        )
+    if tally is not None:
+        metrics = tally.metrics()
+        alive = bool(metrics["recover_success"]) and not bool(metrics["refall"])
+        fell_at = None
+    trajectory: dict[str, Any] | None = None
+    if traj is not None:
+        trajectory = {
+            "command": {k: float(command.get(k, 0.0)) for k in ("vx", "vy", "yaw")},
+            "kind": kind,
+            "seed": seed,
+            "rate_hz": sim.control_rate_hz,
+            "joints": list(sim.contract.joint_order),
+            "alive": alive,
+            "fell_at_s": fell_at,
+            "tracking": tracking,
+            "metrics": {k: (v if math.isfinite(v) else None) for k, v in metrics.items()},
+            "joint_target": None if joint_target is None else [float(v) for v in joint_target],
+            "ee_target": None if ee_target is None else [float(v) for v in ee_target],
+            "conditions": cond.label() or None,
+            "category": fallen.category if fallen is not None else None,
+            "start": fallen.describe() if fallen is not None else None,
+            **traj,
+        }
+    return EpisodeResult(
+        seed=seed,
+        alive=alive,
+        fell_at_s=fell_at,
+        tracking=tracking,
+        steps=len(traj["t"]) if traj is not None else steps,
+        trajectory=trajectory,
+        metrics=metrics,
+        category=fallen.category if fallen is not None else None,
+    )
+
+
+def push_recovery_s(
+    tilts: list[float],
+    speeds: list[float],
+    *,
+    push_index: int | None,
+    rate_hz: float,
+    fell: bool,
+    window_s: float,
+    tilt_tol: float = PUSH_RECOVER_TILT_DEG,
+    speed_tol: float = PUSH_RECOVER_SPEED_M_S,
+) -> float:
+    """Seconds from a push until the base stays settled to the end of the episode (C3b).
+
+    Settled = tilted at most `tilt_tol` and moving at most `speed_tol` across
+    the floor, from that control step to the last one. `window_s` (the time
+    the episode had left after the push) when the robot fell, the push never
+    landed, or the base was still unsettled at the end.
+    """
+    if fell or push_index is None or push_index >= len(tilts) or len(speeds) != len(tilts):
+        return float(window_s)
+    after = range(push_index, len(tilts))
+    last_bad: int | None = None
+    for k in after:
+        if tilts[k] > tilt_tol or speeds[k] > speed_tol:
+            last_bad = k
+    if last_bad is None:
+        return 0.0
+    if last_bad == len(tilts) - 1:
+        return float(window_s)
+    return min(float(window_s), (last_bad + 1 - push_index) / rate_hz)
+
+
+def cmd_of(command: dict[str, float], axis: str) -> float:
+    return float(command.get(axis, 0.0) or 0.0)
+
+
+def build(
+    mjcf_path: Path,
+    policy: Policy,
+    *,
+    card: dict[str, Any] | None,
+) -> tuple[Simulator, IoContract]:
+    """Compile the robot, read the contract, and refuse a mismatch before stepping.
+
+    When the card carries an `interface` (M17b) the model is compiled by the
+    shared plant builder — the robot's own joint order, per-group gains,
+    default pose and rates — and `validate` checks the contract against that
+    declaration, fingerprint first. When it does not, this is M8's path,
+    unchanged: the MJCF as written, one scalar kp/kd, the joint set inferred
+    from the keys of `card.limits`.
+    """
+    contract = IoContract.from_manifest(policy.manifest)
+    try:
+        emb = Embodiment.from_card(card)
+    except InterfaceError as exc:
+        raise ContractMismatch(f"the robot card's interface is unreadable: {exc}") from exc
+    built: Plant | None = None
+    if emb is not None:
+        try:
+            built = build_plant(mjcf_path, emb)
+        except PlantError as exc:
+            raise ContractMismatch(str(exc)) from exc
+        model = built.model
+    else:
+        model = load_model(mjcf_path)
+    validate(
+        contract,
+        model_joints=model_joints(model),
+        policy_in_dim=policy.in_dim,
+        policy_out_dim=policy.out_dim,
+        card=card,
+    )
+    plant = policy.manifest.get("plant") if isinstance(policy.manifest.get("plant"), dict) else None
+    return Simulator(model, contract, plant=plant, card=card, emb=emb, built=built), contract
+
+
+#: The target a cell kind supplies, as the observation block that consumes it.
+_TARGET_BLOCK = {"joint_target": "joint_target", "reach": "ee_target"}
+
+
+def check_battery(sim: Simulator, spec: dict[str, Any]) -> None:
+    """Refuse a battery this policy cannot sit — before a single physics step.
+
+    A policy is trained to follow one kind of target. One whose contract has
+    no `ee_target` block has no input through which a `reach` cell's target
+    could reach it; running it anyway would score the robot's default
+    behaviour and call the number a reach error. Every cell is checked first,
+    so a bad cell five deep does not waste four. C2: every cell's conditions
+    are parsed here too, and a recovery cell needs a floating base and feet.
+    """
+    blocks = {
+        obs_registry.resolve(b.name).name
+        for b in sim.contract.obs_spec
+        if obs_registry.is_known(b.name)
+    }
+    problems: list[str] = []
+    protocol = str(spec.get("protocol") or PROTOCOL_M8)
+    if protocol not in PROTOCOLS:
+        problems.append(f"protocol `{protocol}` (this engine runs {', '.join(PROTOCOLS)})")
+    for cell in spec.get("cells") or []:
+        name = str(cell.get("name"))
+        kind = str(cell.get("kind") or "velocity")
+        if kind not in CELL_KINDS:
+            problems.append(
+                f"`{name}` has kind `{kind}` (this engine runs {', '.join(CELL_KINDS)})"
+            )
+            continue
+        try:
+            cond = conditions_mod.parse(
+                conditions_mod.merge(spec.get("conditions"), cell.get("conditions"))
+            )
+        except conditions_mod.ConditionError as exc:
+            problems.append(f"`{name}`: {exc}")
+            continue
+        if kind == "recovery":
+            if sim.fixed_base:
+                problems.append(f"`{name}` is a recovery cell, but the robot's base is fixed")
+            elif not sim._foot_geoms:
+                problems.append(
+                    f"`{name}` is a recovery cell, scored on both feet on the ground, and the "
+                    "robot's interface declares no `feet`"
+                )
+            if cond.fallen is None:
+                problems.append(f"`{name}` is a recovery cell with no `init_pose` condition")
+        elif cond.fallen is not None:
+            problems.append(f"`{name}` has an `init_pose` but is not a `recovery` cell")
+        needed = _TARGET_BLOCK.get(kind)
+        if needed is not None and needed not in blocks:
+            problems.append(
+                f"`{name}` is a `{kind}` cell, but the policy observes no `{needed}` block — "
+                "it has no input for that target"
+            )
+        if kind == "velocity" and not sim.fixed_base and "commands" not in blocks:
+            moving = any(abs(float(cell.get(a) or 0.0)) > 1e-9 for a in ("vx", "vy", "yaw"))
+            if moving:
+                problems.append(
+                    f"`{name}` commands a velocity, but the policy observes no `commands` block"
+                )
+        if kind == "reach" and sim.ee_name is None:
+            problems.append(
+                f"`{name}` is a `reach` cell, but the robot's interface declares no end "
+                "effector with a site or body in the MJCF"
+            )
+    if problems:
+        raise ContractMismatch(
+            "battery mismatch — refusing to run cells this policy cannot sit: "
+            + "; ".join(problems)
+            + "."
+        )
+
+
+def run_battery(
+    sim: Simulator,
+    policy: Policy,
+    spec: dict[str, Any],
+    *,
+    seed_base: int,
+    out_dir: Path,
+    recorder: Any | None = None,
+    log: Log = lambda _line: None,
+) -> tuple[list[CellResult], list[str]]:
+    """Every cell x seed of a battery. Seed 0 of each cell is recorded and rendered."""
+    import json
+
+    warnings: list[str] = []
+    check_battery(sim, spec)
+    horizon = float(spec.get("horizon_s") or 5.0)
+    seeds = int(spec.get("seeds") or 1)
+    protocol = str(spec.get("protocol") or PROTOCOL_M8)
+    results: list[CellResult] = []
+    for cell in spec["cells"]:
+        name = str(cell["name"])
+        command = {k: float(cell.get(k) or 0.0) for k in ("vx", "vy", "yaw")}
+        cond = conditions_mod.parse(
+            conditions_mod.merge(spec.get("conditions"), cell.get("conditions"))
+        )
+        for note in sim.configure(cond):
+            if note not in warnings:
+                warnings.append(note)
+        kind, _jt, _ee, notes = resolve_targets(sim, cell)
+        warnings.extend(notes)
+        result = CellResult(
+            name=name,
+            command=command,
+            kind=kind,
+            fixed_base=sim.fixed_base,
+            protocol=protocol,
+            score=cell.get("score"),
+        )
+        cell_dir = out_dir / "cells" / _slug(name)
+        cell_dir.mkdir(parents=True, exist_ok=True)
+        started = time.perf_counter()
+        for k in range(seeds):
+            seed = seed_base + k
+            category = (
+                cond.fallen.category_for(k, seeds)
+                if cond.fallen is not None and kind == "recovery"
+                else None
+            )
+            sink: FrameSink | None = None
+            recording: Any | None = None
+            if k == 0 and recorder is not None and recorder.available:
+                recording = recorder
+                recording.start(cell_dir / "video.mp4")
+                sink = recording.frame
+            episode = run_episode(
+                sim,
+                policy,
+                command=command,
+                seed=seed,
+                horizon_s=horizon,
+                record=(k == 0),
+                frame_sink=sink,
+                cell=cell,
+                protocol=protocol,
+                category=category,
+            )
+            if recording is not None:
+                finished = recording.finish()
+                if getattr(recording, "poster", False):
+                    # L1: one still, not a video.
+                    if finished is not None:
+                        result.poster_path, result.poster_t_s = finished
+                elif isinstance(finished, dict):
+                    result.videos = dict(finished)
+                    result.video_path = finished.get("side") or next(iter(finished.values()), None)
+                elif finished is not None:
+                    result.video_path = finished
+                if not finished and recording.reason:
+                    warnings.append(f"{name}: {recording.reason}")
+            if episode.trajectory is not None:
+                traj_path = cell_dir / "trajectory.json"
+                traj_path.write_text(
+                    json.dumps({"cell": name, **episode.trajectory}, separators=(",", ":")),
+                    encoding="utf-8",
+                )
+                result.traj_path = traj_path
+            result.episodes.append(episode)
+        log(_cell_line(result, sim, cond, time.perf_counter() - started))
+        results.append(result)
+    sim.configure(conditions_mod.Conditions())
+    if recorder is not None and not recorder.available and recorder.reason:
+        warnings.insert(0, f"video unavailable: {recorder.reason}")
+    return results, warnings
+
+
+def _cell_line(
+    result: CellResult, sim: Simulator, cond: conditions_mod.Conditions, seconds: float
+) -> str:
+    """The one log line per cell. A velocity cell on a floating base with no
+    conditions logs exactly the line M8 shipped — it is quoted in the
+    Quickstart, and "every existing battery is unchanged" includes what it
+    prints. Only the new shapes say more."""
+    kind = result.kind
+    tracking = ", ".join(f"{a} {v * 100:.0f}%" for a, v in sorted(result.tracking.items()))
+    label = cond.label()
+    if kind == "recovery":
+        eps = result.episodes
+        ok = [e for e in eps if e.metrics.get("recover_success")]
+        times = sorted(e.metrics["recover_time_s"] for e in ok)
+        refall = sum(1 for e in ok if e.metrics.get("refall"))
+        median = f"{times[len(times) // 2]:.2f} s" if times else "—"
+        return (
+            f"test {result.name} [recovery]: {len(ok)}/{len(eps)} stood up, median {median}, "
+            f"{refall} re-fell" + (f" · {label}" if label else "") + f" ({seconds:.1f}s)"
+        )
+    if result.score == "posture":
+        medians = _posture_medians(result.episodes)
+        shown = ", ".join(
+            f"{label} {medians[key]:.2f}{unit}"
+            for key, label, unit in (
+                ("tilt_max_deg", "tilt max", "°"),
+                ("asym_max_deg", "asym", "°"),
+                ("drift_m", "drift", " m"),
+                ("recover_s", "recovered in", " s"),
+            )
+            if key in medians
+        )
+        return (
+            f"test {result.name} [posture]: {result.alive}/{result.seeds} upright"
+            + (f", {shown} (median over seeds)" if shown else "")
+            + (f" · {label}" if label else "")
+            + f" ({seconds:.1f}s)"
+        )
+    measured = result.metrics
+    unit = "m" if kind == "reach" else "rad"
+    legacy = kind == "velocity" and not sim.fixed_base
+    head = f"test {result.name}: " if legacy else f"test {result.name} [{kind}]: "
+    return (
+        head
+        + ("fixed base" if sim.fixed_base else f"{result.alive}/{result.seeds} upright")
+        + (f", tracking {tracking}" if tracking else "")
+        + (
+            f", settle error {measured['settle_error']:.4f} {unit}, "
+            f"{int(measured['limit_violations'])} limit violation step(s)"
+            if "settle_error" in measured
+            else ""
+        )
+        + (f" · {label}" if label else "")
+        + f" ({seconds:.1f}s)"
+    )
+
+
+def _posture_medians(episodes: list[EpisodeResult]) -> dict[str, float]:
+    """The founder's median (`sorted(v)[n // 2]`) of each posture metric over the seeds."""
+    out: dict[str, float] = {}
+    for key in ("tilt_max_deg", "asym_max_deg", "drift_m", "recover_s"):
+        values = sorted(
+            e.metrics[key] for e in episodes if key in e.metrics and math.isfinite(e.metrics[key])
+        )
+        if values:
+            out[key] = float(values[len(values) // 2])
+    return out
+
+
+def _slug(name: str) -> str:
+    """A cell name as a path segment (`vy-0.10` → `vy-minus-0p10`), lower-case, no punctuation."""
+    swap = {"&": "-and-", "+": "-plus-", "-": "-minus-", ".": "p", "@": "-at-"}
+    text = "".join(swap.get(ch, ch) for ch in name.lower())
+    while "--" in text:
+        text = text.replace("--", "-")
+    return "".join(ch if ch.isalnum() or ch in "-_" else "-" for ch in text).strip("-") or "cell"