diff --git a/.gitmodules b/.gitmodules
index cc5c648b8..a9b10433f 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,3 +1,6 @@
 [submodule "external/openpi"]
 	path = external/openpi
 	url = https://github.com/GaTech-RL2/openpi.git
+[submodule "external/RoboTwin"]
+	path = external/RoboTwin
+	url = https://github.com/GaTech-RL2/RoboTwin.git
diff --git a/CLAUDE.md b/CLAUDE.md
index 38807f1c5..a33c04c98 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -36,6 +36,17 @@ all `*.ipynb`. **Never read into context**: venvs (`emimic/`, `.venv/`), caches
   salloc -A gts-dxu345-rl2 -N1 -q inferno -t 1:00:00 --mem=75G --gres=gpu:h200:1
   ```
   Always use the `inferno` queue (`-q inferno`) rather than `ember` — it's faster. Adjust `-t`, `--mem`, and `--gres` to the job. `salloc` is best for interactive / iterative work (smoke tests, debugging) where you hold the node and run into it repeatedly. For large or long-running jobs (real training runs), submit through Hydra's submitit launcher instead (`hydra/launcher/submitit.yaml`) so the job queues and runs unattended. Lightweight read-only work (lint, type checks, small unit tests, file edits, single-file syntax checks) is fine on the login node.
+- **Pick the GPU variant by job — don't always queue for `h200`.** `gpu-h200` is the most contended partition, so jobs sit. Choose by what the job needs to fit in VRAM (pi0.5 is 3.6 B params ≈ **14.5 GB fp32 / ~7 GB bf16** for the weights alone). Each type is its own partition `gpu-<type>` with `--gres=gpu:<type>:N`, same `-A gts-dxu345-rl2 -q inferno`:
+  | partition | `--gres` type | GPU mem | use for |
+  |---|---|---|---|
+  | `gpu-h200` | `h200` | 141 GB | **pi0.5 full fp32 AdamW training** (model+optimizer ≈ 57 GB) |
+  | `gpu-rtxpro-blackwell` | `rtx_pro_6000_blackwell` | 96 GB | training (newer, fewer nodes) |
+  | `gpu-h100` | `h100` | 80 GB | training |
+  | `gpu-l40s` | `l40s` | 48 GB | **pi0.5 eval/inference** (the eval sbatch was originally sized for a 48 GB a40) |
+  | `gpu-a100` | `a100` | 40 GB | **pi0.5 eval/inference**; training only with `--adam8bit` + small batch |
+  | `gpu-rtx6000` | `rtx_6000` | 24 GB | small / bf16-only inference — tight for pi0.5, plentiful nodes |
+  | `gpu-v100` | `v100` | 16 GB | too small to load pi0.5 comfortably — avoid |
+  Rule of thumb: **training needs ≥80 GB** (h200/h100/blackwell); **eval/inference fits 40–48 GB** (l40s/a100, with room for DINOv2 retrieval + SAPIEN) and those queues schedule far faster than h200. **Each partition caps the CPU:GPU ratio differently** — `gpu-h200` is 8:1, `gpu-l40s` is **4:1** — so `--cpus-per-task` must be ≤ ratio × #GPUs or the job is rejected with "Invalid generic resource (gres) specification" (e.g. 8 CPUs / 1 l40s fails; use 4). Validate a header without queuing via `sbatch --test-only <script>`.
 - **Short GPU runs (eval-only, smoke, a few hundred forward passes): export `TORCH_COMPILE_DISABLE=1`.** pi0.5's `sample_actions` triggers a `torch.compile` max-autotune compile on the first call — minutes of warmup that only pays off across a long training run. Disabling it runs eager (slower per call, no warmup), a net win when you're not training for a while. Leave compile ON for real training.
 - Python 3.11. Activate the project venv before any Python tooling: `source emimic/bin/activate`.
 - Package is installed editable as `egomimic` (see `pyproject.toml`). Linting is `ruff` via pre-commit.
diff --git a/egomimic/hydra_configs/data/robotwin_local.yaml b/egomimic/hydra_configs/data/robotwin_local.yaml
new file mode 100644
index 000000000..a0232ec21
--- /dev/null
+++ b/egomimic/hydra_configs/data/robotwin_local.yaml
@@ -0,0 +1,36 @@
+# RoboTwin reusable-corpus data recipe: load converted local .zarr stores (no S3/SQL)
+# through the standard MultiDataset pipeline as eva_bimanual cartesian episodes, so
+# RoboTwin can cotrain alongside the eva/human corpus. Produce the stores first with
+# `egomimic/ricl/scripts/robotwin_to_zarr.py` and point `paths.dataset_dir` at the
+# output dir. Mirrors `data/eva.yaml` but uses LocalEpisodeResolver + the PI image
+# keymap (`cartesian_pi` -> base_0_rgb / *_wrist_0_rgb) and a no-op filter.
+_target_: egomimic.pl_utils.pl_data_utils.MultiDataModuleWrapper
+
+train_datasets:
+  eva_bimanual:
+    _target_: egomimic.rldb.zarr.zarr_dataset_multi.MultiDataset._from_resolver
+    resolver:
+      _target_: egomimic.rldb.zarr.zarr_dataset_multi.LocalEpisodeResolver
+      folder_path: ${paths.dataset_dir} # dir of converted RoboTwin <hash>.zarr stores
+      key_map:
+        _target_: egomimic.rldb.embodiment.eva.Eva.get_keymap
+        keymap_mode: cartesian_pi
+      transform_list:
+        _target_: egomimic.rldb.embodiment.eva.Eva.get_transform_list
+        mode: cartesian
+    filters:
+      _target_: egomimic.rldb.filters.DatasetFilter
+      filter_lambdas: [] # load every local .zarr (all are RoboTwin eva_bimanual)
+    mode: total
+
+valid_datasets:
+  eva_bimanual: ${train_datasets.eva_bimanual}
+
+train_dataloader_params:
+  eva_bimanual:
+    batch_size: 8
+    num_workers: 4
+valid_dataloader_params:
+  eva_bimanual:
+    batch_size: 8
+    num_workers: 4
diff --git a/egomimic/ricl/CLAUDE.md b/egomimic/ricl/CLAUDE.md
index 991860d2e..3cbbb7d12 100644
--- a/egomimic/ricl/CLAUDE.md
+++ b/egomimic/ricl/CLAUDE.md
@@ -23,6 +23,61 @@ resolve `episode_lists/`, `pg_tokenizer/`, `outputs/` relative to the parent dir
   builder over the pre-pooled `top_image_embeddings`; runnable `--build-cache`),
   `droid_eval.py` (`DroidRiclEval` retrieval vs a *true* zero-context floor,
   paired flow-loss; `DroidRiclModelWrapper`).
+- RoboTwin integration (joint-space shim mirroring DROID + a reusable Zarr
+  converter; goal/steps in `robotwin_setup.md`): `robotwin_data.py`
+  (`RoboTwinCorpus` reads RoboTwin HDF5 — `joint_action/vector` + `endpose` +
+  `observation/<cam>/rgb` — query dataset, bank provider, within-task LOO cache;
+  **detects the embodiment's qpos dim + gripper slots** — `aloha-agilex` is 6-DOF
+  -> 14-D, slots 6/13 — so don't hardcode 16/(7,15)), `robotwin_eval.py`
+  (`RoboTwinRiclEval`/`RoboTwinRiclModelWrapper`, thin `DroidRiclEval` subclass for
+  RoboTwin's dim/grippers). Scripts: `scripts/download_robotwin.py`
+  (HF zip slice from `dataset/<task>/<embodiment>_<setting>_<N>.zip` — the bimanual
+  embodiment is `aloha-agilex`, smallest is `clean_50` ~230 MB; plus a `--mode
+  synthetic` fixture for tests), `scripts/robotwin_to_zarr.py` (HDF5 ->
+  `eva_bimanual` cartesian Zarr via `ZarrWriter`; needs `endpose`; cmd==obs pose,
+  chunked at load like aria), `scripts/train_robotwin_ricl.py` (`--stage cpu` = fast
+  data-path/collate smoke with `--embed fake`; `--stage full` = GPU training on a
+  Lightning `Trainer` — NOT submitit; launch via `scripts/train_robotwin_ricl.sbatch`
+  [PACE: gpu-h200, qos inferno] and it saves `quantiles.json` beside the checkpoints
+  for eval), `scripts/build_robotwin_bank_index.py` (consolidated DINOv2 bank index over
+  a `RoboTwinCorpus`, built with the SAME `.embed` as eval's `OnlineRetriever`; output
+  format = `build_embedding_index.build_retrieval_index`). Tests:
+  `tests/{robotwin_data_test.py,robotwin_to_zarr_test.py,robotwin_bank_index_test.py}`
+  build a synthetic 6-DOF fixture. Reusable-corpus path: `hydra_configs/data/robotwin_local.yaml`
+  (`LocalEpisodeResolver` + `Eva` keymap/transform, no SQL/S3) +
+  `tests/robotwin_zarr_multidataset_test.py` (converts fixture -> Zarr -> loads via
+  `MultiDataset._from_resolver` + replicates trainHydra norm-stats wiring). Closed-loop
+  eval: `robotwin_adapter.py` (model-free glue — `obs_to_state`,
+  `quantile_norm`/`unnorm`, `state_to_model_input`, `unnormalize_action`,
+  `OnlineRetriever`; unit-tested in `tests/robotwin_adapter_test.py` with the model/sim
+  mocked) and `robotwin_policy.py` — the deploy contract (`encode_obs`/`get_model`/`eval`/
+  `reset_model` + `PIRiclPolicy` backed by EgoVerse `PIRicl`), the **source of truth**.
+  RoboTwin loads it via a **thin shim** at `policy/pi_ricl_egoverse/`
+  (`__init__.py` = `from .deploy_policy import *`; `deploy_policy.py` = `from
+  egomimic.ricl.robotwin_policy import *`; + `deploy_policy.yml`/`eval.sh`) that lives in
+  the **`GaTech-RL2/RoboTwin` fork** = the `external/RoboTwin` submodule (matches the
+  `GaTech-RL2/openpi` pattern; new-cluster setup = `git submodule update --init
+  external/RoboTwin`). Driven by RoboTwin's SAPIEN `script/eval_policy.py`. The shim's
+  `deploy_policy.yml` needs four artifacts: `egoverse_checkpoint` (trained `.ckpt`),
+  `bank_root` (a RoboTwin task dir), `bank_index_dir` (`build_robotwin_bank_index.py`
+  output), `quantiles_path` (the `quantiles.json` the trainer saves). Sim deps
+  (sapien/mplib/curobo/pytorch3d) install **selectively** — do NOT run RoboTwin's
+  `script/_install.sh` (it pins `torch==2.4.1`, breaking emimic's 2.7.1). Eval task
+  config = `demo_clean` (matches the `clean` data slice).
+  **Cross-embodiment RICL** (retrieve from embodiment A, predict embodiment B —
+  arx-x5 and aloha-agilex share the identical 14-D dual-arm layout): `robotwin_data.
+  build_cross_embodiment_retrieval_cache` (per emb-B query frame, kNN emb-A frames of
+  the SAME task; no leave-one-out — different corpora) + `train_robotwin_ricl.
+  build_data_xemb` (gated by `--bank-root`/`--eval-bank-root`; query/target = emb B
+  with its own quantiles, in-context bank = emb A with ITS own quantiles, so the
+  spliced demo is encoded in emb-A units). Pass `BANK_ROOT`/`EVAL_BANK_ROOT` to
+  `train_robotwin_ricl.sbatch` (also `NO_RANDOM=1` — the xemb path builds no
+  random-control caches). The run saves `bank_quantiles.json` (emb-A) beside
+  `quantiles.json` (emb-B). Closed-loop: `scripts/eval_xemb_compare.sbatch` (sim
+  controls emb B; cross-emb retrieves the emb-A bank, passing `bank_quantiles_path`
+  to `robotwin_policy` so retrieved demos normalize in emb-A units — the one deploy
+  change cross-embodiment needs). Result: arx-x5 demos cut held-out aloha action
+  loss ~40% (helps 100% of frames).
 - Embedding -> index: embed a corpus with
   `egomimic/scripts/embedding_process/zarr_embedding.py` — supports SQL-registry
   filters (`--filter-lambda` + `--sync-root`) and writes to a writable mirror
diff --git a/egomimic/ricl/robotwin_adapter.py b/egomimic/ricl/robotwin_adapter.py
new file mode 100644
index 000000000..ab6bca528
--- /dev/null
+++ b/egomimic/ricl/robotwin_adapter.py
@@ -0,0 +1,191 @@
+"""Pure-Python glue for the RoboTwin closed-loop RICL eval adapter.
+
+The closed-loop benchmark runs a trained EgoVerse PyTorch ``PIRicl`` checkpoint
+inside RoboTwin's SAPIEN sim. This module holds the embodiment/observation/action
+**glue** that is independent of both SAPIEN and the model, so it is directly
+unit-testable:
+
+- ``obs_to_state``        : RoboTwin obs dict -> ([head, right, left] rgb, qpos vector)
+  (mirrors ``policy/pi05/deploy_policy.encode_obs``).
+- ``quantile_norm`` / ``quantile_unnorm`` : the [-1,1] map used by the shim and its
+  inverse (for turning a model action back into RoboTwin qpos).
+- ``state_to_model_input`` : raw qpos -> normalized, slot-filled 32-D proprio.
+- ``unnormalize_action``  : model action (32-D, normalized) -> RoboTwin qpos chunk.
+- ``OnlineRetriever``     : embed the live head frame -> kNN against a prebuilt demo
+  bank -> assemble ``ricl_retrieved_*`` blocks (the same keys ``build_ricl_collate``
+  produces) for the model prefix.
+
+The RoboTwin-side ``policy/pi_ricl_egoverse/{deploy_policy,pi_model}.py`` is a thin
+wrapper that loads the checkpoint + a DINOv2 embedder and drives these primitives.
+Quantiles come from the training corpus
+(``robotwin_data.RoboTwinCorpus.save_quantiles`` / ``load_quantiles``); the action
+space is RoboTwin's native qpos so the adapter returns a ``(steps, state_dim)`` chunk
+executed with ``take_action(action)`` in the default ``qpos`` control mode.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+import numpy as np
+import torch
+
+from egomimic.ricl.robotwin_data import slot32
+
+# RoboTwin obs camera -> RICL image key (head exterior is the retrieval/base view).
+_RGB_ORDER = ("head_camera", "right_camera", "left_camera")  # matches pi05 encode_obs
+
+
+def obs_to_state(observation: dict) -> tuple[list[np.ndarray], np.ndarray]:
+    """RoboTwin ``get_obs()`` dict -> ``([head, right, left] rgb, qpos vector)``.
+
+    Mirrors ``external/RoboTwin/policy/pi05/deploy_policy.encode_obs`` exactly so the
+    same eval driver works."""
+    obs = observation["observation"]
+    rgb = [np.asarray(obs[cam]["rgb"]) for cam in _RGB_ORDER]
+    state = np.asarray(observation["joint_action"]["vector"], dtype=np.float32)
+    return rgb, state
+
+
+def quantile_norm(x: np.ndarray, q01: np.ndarray, q99: np.ndarray) -> np.ndarray:
+    """Map raw qpos to [-1, 1] (same formula as ``RoboTwinCorpus.quantile_norm``)."""
+    x = np.asarray(x, dtype=np.float32)
+    return 2.0 * ((x - q01) / (q99 - q01 + 1e-6)) - 1.0
+
+
+def quantile_unnorm(x: np.ndarray, q01: np.ndarray, q99: np.ndarray) -> np.ndarray:
+    """Inverse of :func:`quantile_norm`: [-1, 1] -> raw qpos units."""
+    x = np.asarray(x, dtype=np.float32)
+    return (x + 1.0) / 2.0 * (q99 - q01 + 1e-6) + q01
+
+
+def state_to_model_input(
+    state: np.ndarray, q_state: tuple[np.ndarray, np.ndarray]
+) -> np.ndarray:
+    """Raw qpos -> normalized, slot-filled 32-D proprio (the model's state input)."""
+    q01, q99 = q_state
+    return slot32(quantile_norm(state, q01, q99))
+
+
+def unnormalize_action(
+    pred: np.ndarray,
+    q_actions: tuple[np.ndarray, np.ndarray],
+    state_dim: int,
+) -> np.ndarray:
+    """Model action -> RoboTwin qpos chunk.
+
+    ``pred`` is ``(H, 32)`` or ``(32,)`` normalized (the 32-D shared space, slot-filled);
+    keep the first ``state_dim`` dims and invert the quantile normalization with the
+    training corpus's action quantiles. Returns ``(H, state_dim)`` (or ``(state_dim,)``)."""
+    pred = np.asarray(pred, dtype=np.float32)
+    q01, q99 = q_actions
+    sliced = pred[..., :state_dim]
+    return quantile_unnorm(sliced, q01, q99)
+
+
+def _to_chw01(img_hwc: np.ndarray, hw: tuple[int, int] = (224, 224)) -> torch.Tensor:
+    """HWC uint8 (or float) -> CHW float in [0, 1], resized to ``hw`` (mirrors the
+    collate's image handling so retrieved frames match the trained representation)."""
+    t = torch.as_tensor(np.asarray(img_hwc))
+    if t.ndim == 3 and t.shape[-1] in (1, 3):
+        t = t.permute(2, 0, 1)
+    t = t.float()
+    if t.max() > 1.5:  # uint8 -> [0, 1]
+        t = t / 255.0
+    if tuple(t.shape[-2:]) != tuple(hw):
+        t = torch.nn.functional.interpolate(
+            t[None], size=tuple(hw), mode="bilinear", align_corners=False
+        )[0]
+    return t.contiguous()
+
+
+class OnlineRetriever:
+    """Build ``ricl_retrieved_*`` blocks for a live query frame at eval time.
+
+    Embeds the query head frame, finds the k nearest demos in a prebuilt bank
+    (``egomimic.ricl.retrieval.RetrievalIndex`` over the same 64-patch DINOv2
+    descriptors used in training), and gathers each neighbor's (image, state, action)
+    via ``bank_provider`` into the batch keys the model prefix consumes — the online
+    analog of ``build_ricl_collate``. The embedder and index are injected so this is
+    unit-testable with stubs (no DINOv2 needed).
+
+    Args:
+        index: a ``RetrievalIndex`` (``.query(vecs, k) -> (hashes, frames, dists)``).
+        bank_provider: ``(episode_hash, frame_idx) -> {"image": HWC, "state": (D,),
+            "action": (H, D)}`` (e.g. ``robotwin_data.make_robotwin_bank_provider``).
+        embedder: object with ``.embed(images_thwc) -> (T, EMBED_DIM)`` (e.g.
+            ``retrieval.DinoV2Embedder``); only called on the single query frame.
+        k, action_horizon, state_dim: block dimensions; image_hw the resize target.
+    """
+
+    def __init__(
+        self,
+        index,
+        bank_provider: Callable[[str, int], dict],
+        embedder,
+        *,
+        k: int = 4,
+        action_horizon: int = 15,
+        state_dim: int = 14,
+        image_hw: tuple[int, int] = (224, 224),
+    ):
+        self.index = index
+        self.bank_provider = bank_provider
+        self.embedder = embedder
+        self.k = int(k)
+        self.action_horizon = int(action_horizon)
+        self.state_dim = int(state_dim)
+        self.image_hw = image_hw
+
+    def retrieve(self, query_image_hwc: np.ndarray) -> dict:
+        """Return ``ricl_retrieved_*`` tensors (batch dim 1) for one query frame."""
+        H, W = self.image_hw
+        k, Ha, D = self.k, self.action_horizon, self.state_dim
+        qvec = self.embedder.embed(np.asarray(query_image_hwc)[None])  # (1, EMBED_DIM)
+        hashes, frames, dists = self.index.query(qvec, k=k)  # each (1, k)
+        hashes, frames, dists = hashes[0], frames[0], dists[0]
+
+        imgs = [torch.zeros(3, H, W) for _ in range(k)]
+        states = [torch.zeros(D) for _ in range(k)]
+        acts = [torch.zeros(Ha, D) for _ in range(k)]
+        mask = torch.zeros(k, dtype=torch.bool)
+        dist = torch.full((k,), float("inf"))
+        for i in range(k):
+            h = str(hashes[i])
+            if not h:  # padded slot (bank smaller than k)
+                continue
+            blk = self.bank_provider(h, int(frames[i]))
+            imgs[i] = _to_chw01(blk["image"], self.image_hw)
+            st = torch.as_tensor(np.asarray(blk["state"]), dtype=torch.float32).reshape(
+                -1
+            )
+            states[i] = _fit(st, D)
+            ac = torch.as_tensor(np.asarray(blk["action"]), dtype=torch.float32)
+            acts[i] = _fit_action(ac, Ha, D)
+            mask[i] = True
+            dist[i] = float(dists[i])
+        return {
+            "ricl_retrieved_images": torch.stack(imgs)[None],  # (1, k, 3, H, W)
+            "ricl_retrieved_state": torch.stack(states)[None],  # (1, k, D)
+            "ricl_retrieved_action": torch.stack(acts)[None],  # (1, k, Ha, D)
+            "ricl_retrieved_mask": mask[None],  # (1, k)
+            "ricl_retrieved_dist": dist[None],  # (1, k)
+        }
+
+
+def _fit(v: torch.Tensor, dim: int) -> torch.Tensor:
+    if v.numel() == dim:
+        return v
+    out = torch.zeros(dim, dtype=torch.float32)
+    n = min(dim, v.numel())
+    out[:n] = v.reshape(-1)[:n]
+    return out
+
+
+def _fit_action(a: torch.Tensor, horizon: int, dim: int) -> torch.Tensor:
+    if a.ndim == 1:
+        a = a[None, :]
+    h = min(horizon, a.shape[0])
+    out = torch.zeros(horizon, dim, dtype=torch.float32)
+    out[:h, : min(dim, a.shape[1])] = a[:h, : min(dim, a.shape[1])]
+    return out
diff --git a/egomimic/ricl/robotwin_data.py b/egomimic/ricl/robotwin_data.py
new file mode 100644
index 000000000..b46b637db
--- /dev/null
+++ b/egomimic/ricl/robotwin_data.py
@@ -0,0 +1,693 @@
+"""RoboTwin shim data layer for RICL training (joint-space).
+
+Feeds RoboTwin 2.0 bimanual expert demos through EgoVerse's real RICL machinery
+(``build_ricl_collate`` -> ``PIRicl`` prefix conditioning -> pi0.5) via the same
+"thin shim, not a port" pattern proven on DROID (see ``droid_data.py`` /
+``DROID_VERIFICATION.md``). RoboTwin is natively **joint-space** — 16-D qpos
+``[left_arm(7), left_gripper(1), right_arm(7), right_gripper(1)]`` — so, exactly
+like DROID's 8-D, the raw state/action are quantile-normalized to [-1, 1] and
+slot-filled into pi0.5's shared 32-D space (dims 0..15; grippers land at slots
+7 and 15). No Zarr/SQL/embodiment port; the Zarr converter
+(``scripts/robotwin_to_zarr.py``) is the *separate* reusable-corpus path.
+
+What this module provides (mirrors ``droid_data.py``)
+-----------------------------------------------------
+- ``RoboTwinCorpus``        : discover task dirs (``<task>/data/episode*.hdf5`` +
+  ``<task>/instructions/episode*.json``) and lazily read per-array HDF5 (LRU).
+- ``RoboTwinQueryDataset``  : per-frame torch ``Dataset`` yielding the post-transform
+  keys the RICL query path consumes (``base_0_rgb`` etc., a 32-D slot-filled state,
+  a (horizon,32) action target, ``episode_hash``/``frame_idx``/``annotations``),
+  quantile-normalized to [-1, 1].
+- ``make_robotwin_bank_provider`` : a ``BankFrameProvider`` returning a neighbor's
+  (head image, normalized 16-D state, normalized (horizon,16) action chunk).
+- ``build_robotwin_retrieval_cache`` / ``build_random_neighbor_cache`` : within-task
+  leave-one-out retrieval cache (and random controls) over a per-frame embedding
+  provider, via the same ``RetrievalCache`` the Zarr path uses.
+- ``make_dinov2_embedding_provider`` / ``make_fake_embedding_provider`` : per-frame
+  ``(T, D)`` embedding providers for cache building (real DINOv2 vs a deterministic
+  stub for fast smoke checks / unit tests that don't need the encoder).
+- ``RoboTwinNormStats`` / ``Passthrough32`` : the minimal norm-stats surface PI's
+  constructor + ``process_batch_for_training`` touch, and a no-op 16->32 converter.
+
+Quantile stats are computed from the corpus (RoboTwin ships none) and may be shared
+across a train/eval split via ``quantiles=`` so both sides normalize identically.
+"""
+
+from __future__ import annotations
+
+import glob
+import json
+import logging
+import os
+from collections import OrderedDict
+from functools import lru_cache
+from typing import Callable
+
+import cv2
+import h5py
+import numpy as np
+import torch
+from torch.utils.data import Dataset
+
+from egomimic.ricl.retrieval import RetrievalCache
+from egomimic.utils.action_utils import BaseActionConverter, _pad32
+
+logger = logging.getLogger(__name__)
+
+# --------------------------------------------------------------------------- #
+# Constants
+# --------------------------------------------------------------------------- #
+# RoboTwin's qpos dim is embodiment-dependent: aloha-agilex has 6-DOF arms ->
+# 14-D state (6+1+6+1, grippers at 6 and 13); a 7-DOF arm gives 16-D (7/15). The
+# corpus DETECTS its own ``state_dim`` + ``gripper_slots`` from the data; these are
+# only fallback defaults (and the synthetic fixture's default 6-DOF layout).
+RAW_DIM = 14  # default qpos dim (aloha-agilex, the bimanual RoboTwin embodiment)
+SHARED_DIM = 32  # pi0.5 shared action/state space
+GRIPPER_SLOTS = (6, 13)  # default left/right gripper indices (6-DOF arms)
+
+EMB_ID = 8  # eva_bimanual masquerade (matches DROID's choice; no new embodiment)
+EMB_NAME = "eva_bimanual"
+AC_KEY = "actions_joint"
+STATE_KEY = "observations.state.ee_pose"  # 32-D slot-fill -> model continuous proprio
+PROMPT_STATE_KEY = "state_raw"  # normalized raw qpos -> compact text State block
+CAM_KEYS = ("base_0_rgb", "left_wrist_0_rgb", "right_wrist_0_rgb")
+# query cameras map to RoboTwin's three views (head exterior is the retrieval view)
+_CAM_TO_ROBOTWIN = {
+    "base_0_rgb": "head_camera",
+    "left_wrist_0_rgb": "left_camera",
+    "right_wrist_0_rgb": "right_camera",
+}
+IMAGE_HW = (224, 224)  # query/bank images resized to pi0.5's resolution
+
+
+def slot32(x: np.ndarray) -> np.ndarray:
+    """Place a D-dim vector into dims 0..D-1 of a 32-D zero vector (last axis),
+    where ``D = x.shape[-1]`` (RoboTwin's per-embodiment qpos dim — 14 for the
+    6-DOF aloha-agilex arms, 16 for 7-DOF). ``D`` must be <= 32."""
+    x = np.asarray(x, dtype=np.float32)
+    d = x.shape[-1]
+    if d > SHARED_DIM:
+        raise ValueError(f"state/action dim {d} exceeds shared dim {SHARED_DIM}")
+    out = np.zeros(x.shape[:-1] + (SHARED_DIM,), dtype=np.float32)
+    out[..., :d] = x
+    return out
+
+
+# --------------------------------------------------------------------------- #
+# Corpus
+# --------------------------------------------------------------------------- #
+def _discover_groups(root: str) -> "OrderedDict[str, list[str]]":
+    """Map group_id -> sorted episode hdf5 paths.
+
+    A *group* is any dir that contains ``data/episode*.hdf5`` (a RoboTwin
+    task/setting), keyed by its path relative to ``root`` (``/`` -> ``__``). This
+    handles both a single task dir and a parent dir of many tasks.
+    """
+    groups: "OrderedDict[str, list[str]]" = OrderedDict()
+    for data_dir in sorted(glob.glob(os.path.join(root, "**", "data"), recursive=True)):
+        if not os.path.isdir(data_dir):
+            continue
+        eps = sorted(glob.glob(os.path.join(data_dir, "episode*.hdf5")))
+        if not eps:
+            continue
+        rel = os.path.relpath(os.path.dirname(data_dir), root)
+        gid = "root" if rel == "." else rel.replace(os.sep, "__")
+        groups[gid] = eps
+    # also allow root itself being a task dir (root/data/episode*.hdf5)
+    return groups
+
+
+def _episode_name(path: str) -> str:
+    return os.path.splitext(os.path.basename(path))[0]  # "episode3"
+
+
+class RoboTwinCorpus:
+    """Discover + lazily load RoboTwin episode HDF5s, grouped by task.
+
+    Episode hash = ``"{group_id}__{episode_name}"`` (filesystem-safe, unique
+    across groups). Per-(hash, key) arrays are LRU-cached; images are decoded on
+    demand. Quantile stats (q01/q99 over the qpos dims, for state + action) are
+    computed once from the corpus unless an explicit ``quantiles`` dict is given
+    (pass the train corpus's to an eval corpus so both normalize identically).
+    """
+
+    def __init__(
+        self,
+        root: str,
+        groups: list[str] | None = None,
+        cache_size: int = 4096,
+        image_hw: tuple[int, int] = IMAGE_HW,
+        quantiles: dict | None = None,
+    ):
+        self.root = root
+        self.image_hw = image_hw
+        self.hash_to_path: "OrderedDict[str, str]" = OrderedDict()
+        self.group_to_hashes: "OrderedDict[str, list[str]]" = OrderedDict()
+        discovered = _discover_groups(root)
+        if groups is not None:
+            discovered = OrderedDict(
+                (g, hs) for g, hs in discovered.items() if g in set(groups)
+            )
+        for g, eps in discovered.items():
+            hs = []
+            for ep in eps:
+                h = f"{g}__{_episode_name(ep)}"
+                self.hash_to_path[h] = ep
+                hs.append(h)
+            if hs:
+                self.group_to_hashes[g] = hs
+        if not self.hash_to_path:
+            raise FileNotFoundError(
+                f"no <task>/data/episode*.hdf5 found under {root!r}"
+            )
+        self._arr = lru_cache(maxsize=cache_size)(self._load_arr)
+        self._actions_cache = lru_cache(maxsize=cache_size)(self._compute_actions)
+        # Detect the embodiment's qpos layout from the first episode: RoboTwin arm
+        # DOF varies (aloha-agilex 6-DOF -> 14-D state, grippers at 6/13; 7-DOF ->
+        # 16-D, 7/15). vector = [l_arm, l_grip, r_arm, r_grip].
+        h0 = next(iter(self.hash_to_path))
+        la = int(self._arr(h0, "joint_action/left_arm").shape[-1])
+        ra = int(self._arr(h0, "joint_action/right_arm").shape[-1])
+        self.state_dim = int(self._arr(h0, "joint_action/vector").shape[-1])
+        self.gripper_slots = (la, la + 1 + ra)
+        self.quantiles = quantiles or self._compute_quantiles()
+
+    # ---- raw HDF5 access ----
+    def _load_arr(self, h: str, key: str) -> np.ndarray:
+        """Read one HDF5 dataset (e.g. ``joint_action/vector``) for an episode."""
+        with h5py.File(self.hash_to_path[h], "r") as f:
+            return f[key][()]
+
+    @property
+    def hashes(self) -> list[str]:
+        return list(self.hash_to_path.keys())
+
+    def group_of(self, h: str) -> str:
+        return h.split("__", 1)[0]
+
+    def num_frames(self, h: str) -> int:
+        return int(self._arr(h, "joint_action/vector").shape[0])
+
+    def state(self, h: str, fi: int) -> np.ndarray:
+        """Raw 16-D qpos at frame ``fi`` (``joint_action/vector``)."""
+        return np.asarray(self._arr(h, "joint_action/vector")[fi], dtype=np.float32)
+
+    def _compute_actions(self, h: str) -> np.ndarray:
+        """Action array (T, 16): action[t] = next state (qpos), last repeated —
+        RoboTwin's ``action = next state`` convention (process_data.py)."""
+        v = np.asarray(self._arr(h, "joint_action/vector"), dtype=np.float32)
+        nxt = np.concatenate([v[1:], v[-1:]], axis=0)
+        return nxt
+
+    def action_chunk(self, h: str, fi: int, horizon: int) -> np.ndarray:
+        """Raw (horizon, 16) action chunk starting at ``fi`` (repeat-pad the tail)."""
+        acts = self._actions_cache(h)
+        T = acts.shape[0]
+        idx = np.clip(np.arange(fi, fi + horizon), 0, T - 1)
+        return acts[idx]
+
+    def image(self, h: str, fi: int, cam: str) -> np.ndarray:
+        """Decode the JPEG for ``cam`` at frame ``fi`` -> (H, W, 3) RGB uint8.
+
+        RoboTwin stores cv2-encoded JPEG bytes; cv2 encode/decode round-trips the
+        array byte-for-byte regardless of channel-order interpretation, so the
+        renderer's RGB frame decodes back as RGB — no BGR swap needed. Trailing
+        ``\\x00`` padding (fixed-length ``S{maxlen}`` storage) is ignored by the
+        JPEG decoder (stops at the EOI marker)."""
+        raw = self._arr(h, f"observation/{_CAM_TO_ROBOTWIN[cam]}/rgb")[fi]
+        buf = np.frombuffer(bytes(raw), np.uint8)
+        img = cv2.imdecode(buf, cv2.IMREAD_COLOR)  # (h, w, 3)
+        if img is None:
+            raise ValueError(f"failed to decode {cam} frame {fi} of {h}")
+        if tuple(img.shape[:2]) != tuple(self.image_hw):
+            img = cv2.resize(img, (self.image_hw[1], self.image_hw[0]))
+        return np.ascontiguousarray(img, dtype=np.uint8)
+
+    def prompt(self, h: str) -> str:
+        """First 'seen' instruction for the episode (from ``instructions/*.json``)."""
+        ep_path = self.hash_to_path[h]
+        task_dir = os.path.dirname(os.path.dirname(ep_path))
+        instr_path = os.path.join(
+            task_dir, "instructions", f"{_episode_name(ep_path)}.json"
+        )
+        try:
+            with open(instr_path) as f:
+                instr = json.load(f)
+            seen = instr.get("seen") or instr.get("unseen") or []
+            if seen:
+                return str(seen[0])
+        except FileNotFoundError:
+            pass
+        return self.group_of(h).replace("__", " ").replace("_", " ")
+
+    # ---- normalization ----
+    def _compute_quantiles(self) -> dict:
+        """q01/q99 per-dim over all frames, for ``state`` and ``actions``."""
+        states, actions = [], []
+        for h in self.hashes:
+            v = np.asarray(self._arr(h, "joint_action/vector"), dtype=np.float32)
+            states.append(v)
+            actions.append(self._actions_cache(h))
+        S = np.concatenate(states, axis=0)
+        A = np.concatenate(actions, axis=0)
+        out = {}
+        for name, arr in (("state", S), ("actions", A)):
+            out[name] = (
+                np.quantile(arr, 0.01, axis=0).astype(np.float32),
+                np.quantile(arr, 0.99, axis=0).astype(np.float32),
+            )
+        return out
+
+    def quantile_norm(self, x: np.ndarray, which: str) -> np.ndarray:
+        """Map raw 16-D state/actions to [-1, 1] using q01/q99 (mirrors the pi0.5
+        State-block range). ``which`` is ``"state"`` or ``"actions"``."""
+        q01, q99 = self.quantiles[which]
+        x = np.asarray(x, dtype=np.float32)
+        return 2.0 * ((x - q01) / (q99 - q01 + 1e-6)) - 1.0
+
+    def save_quantiles(self, path: str) -> None:
+        payload = {
+            k: {"q01": q01.tolist(), "q99": q99.tolist()}
+            for k, (q01, q99) in self.quantiles.items()
+        }
+        os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True)
+        with open(path, "w") as f:
+            json.dump(payload, f, indent=2)
+
+
+def save_quantiles(quantiles: dict, path: str) -> None:
+    """Persist a ``{which: (q01, q99)}`` quantile dict to JSON (standalone analog of
+    ``RoboTwinCorpus.save_quantiles`` — used to save the cross-embodiment BANK
+    corpus's quantiles next to the trained checkpoint)."""
+    payload = {
+        k: {"q01": np.asarray(q01).tolist(), "q99": np.asarray(q99).tolist()}
+        for k, (q01, q99) in quantiles.items()
+    }
+    os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True)
+    with open(path, "w") as f:
+        json.dump(payload, f, indent=2)
+
+
+def load_quantiles(path: str) -> dict:
+    with open(path) as f:
+        payload = json.load(f)
+    return {
+        k: (
+            np.asarray(v["q01"], dtype=np.float32),
+            np.asarray(v["q99"], dtype=np.float32),
+        )
+        for k, v in payload.items()
+    }
+
+
+# --------------------------------------------------------------------------- #
+# Query dataset
+# --------------------------------------------------------------------------- #
+class RoboTwinQueryDataset(Dataset):
+    """Flat per-frame query dataset over a set of RoboTwin episodes.
+
+    Each item is a flat dict (the RICL collate reads ``episode_hash`` /
+    ``frame_idx`` off the top level, then ``annotation_collate`` stacks the rest):
+        base_0_rgb / left_wrist_0_rgb / right_wrist_0_rgb : (224,224,3) uint8 HWC
+        observations.state.ee_pose : (32,) f32   slot32(quantile_norm(state))
+        actions_joint              : (H,32) f32  slot32(quantile_norm(chunk))
+        state16                    : (16,) f32   normalized state for the text block
+        annotations                : [prompt]
+        episode_hash, frame_idx
+    """
+
+    def __init__(self, corpus: RoboTwinCorpus, hashes: list[str], action_horizon: int):
+        self.corpus = corpus
+        self.action_horizon = int(action_horizon)
+        self.index: list[tuple[str, int]] = []
+        for h in hashes:
+            for fi in range(corpus.num_frames(h)):
+                self.index.append((h, fi))
+
+    def __len__(self) -> int:
+        return len(self.index)
+
+    def __getitem__(self, idx: int) -> dict:
+        h, fi = self.index[idx]
+        c = self.corpus
+        state = slot32(c.quantile_norm(c.state(h, fi), "state"))  # (32,)
+        chunk = c.action_chunk(h, fi, self.action_horizon)  # (H, 16)
+        action = slot32(c.quantile_norm(chunk, "actions"))  # (H, 32)
+        sample = {
+            STATE_KEY: state.astype(np.float32),
+            AC_KEY: action.astype(np.float32),
+            PROMPT_STATE_KEY: c.quantile_norm(c.state(h, fi), "state").astype(
+                np.float32
+            ),
+            "annotations": [c.prompt(h)],
+            "episode_hash": h,
+            "frame_idx": int(fi),
+        }
+        for cam in CAM_KEYS:
+            sample[cam] = c.image(h, fi, cam)  # HWC uint8
+        return sample
+
+
+# --------------------------------------------------------------------------- #
+# Bank frame provider
+# --------------------------------------------------------------------------- #
+def make_robotwin_bank_provider(corpus: RoboTwinCorpus, action_horizon: int = 1):
+    """Return a ``BankFrameProvider``: (episode_hash, frame_idx) -> retrieved block.
+
+    Returns the raw head image (HWC uint8; the collate scales to [0,1]) plus the
+    quantile-normalized 16-D state and the ``(action_horizon, 16)`` retrieved action
+    *chunk* (repeat-padded at the episode tail). Carrying the full chunk — not just
+    one step — is what lets a kNN demo's trajectory differ from a random one's (#1).
+    The collate keeps these 16-D (text-only prompt encoding); the model's own
+    continuous inputs are slot-filled to 32 separately.
+    """
+
+    def provider(episode_hash: str, frame_idx: int) -> dict:
+        fi = int(np.clip(frame_idx, 0, corpus.num_frames(episode_hash) - 1))
+        state = corpus.quantile_norm(corpus.state(episode_hash, fi), "state")  # (16,)
+        action = corpus.quantile_norm(
+            corpus.action_chunk(episode_hash, fi, action_horizon), "actions"
+        )  # (action_horizon, 16)
+        return {
+            "image": corpus.image(episode_hash, fi, "base_0_rgb"),  # HWC u8
+            "state": state.astype(np.float32),
+            "action": action.astype(np.float32),
+        }
+
+    return provider
+
+
+# --------------------------------------------------------------------------- #
+# Per-frame embedding providers (for the retrieval cache)
+# --------------------------------------------------------------------------- #
+def make_dinov2_embedding_provider(corpus: RoboTwinCorpus, **kwargs):
+    """Per-episode ``(T, EMBED_DIM)`` DINOv2 descriptors of the head view.
+
+    Lazily builds a single ``DinoV2Embedder`` (downloads weights on first use, runs
+    on the GPU). Cached per hash.
+    """
+    from egomimic.ricl.retrieval import DinoV2Embedder
+
+    embedder = DinoV2Embedder(**kwargs)
+    cache: dict[str, np.ndarray] = {}
+
+    def provider(episode_hash: str) -> np.ndarray:
+        if episode_hash not in cache:
+            T = corpus.num_frames(episode_hash)
+            frames = np.stack(
+                [corpus.image(episode_hash, fi, "base_0_rgb") for fi in range(T)]
+            )
+            cache[episode_hash] = embedder.embed(frames)
+        return cache[episode_hash]
+
+    return provider
+
+
+def make_fake_embedding_provider(corpus: RoboTwinCorpus, dim: int = 256, seed: int = 0):
+    """Deterministic per-frame embeddings for fast smoke checks / unit tests that
+    don't need the DINOv2 encoder.
+
+    Frames of one episode cluster around a per-episode centroid (so within-task
+    retrieval is sane to assert on); a small per-task component keeps same-task
+    episodes nearer each other than cross-task ones."""
+
+    def provider(episode_hash: str) -> np.ndarray:
+        T = corpus.num_frames(episode_hash)
+        rng = np.random.default_rng(abs(hash(episode_hash)) % (2**32) + seed)
+        grp_rng = np.random.default_rng(
+            abs(hash(corpus.group_of(episode_hash))) % (2**32)
+        )
+        task_centroid = grp_rng.standard_normal(dim).astype(np.float32)
+        ep_centroid = task_centroid + 0.3 * rng.standard_normal(dim).astype(np.float32)
+        return (
+            ep_centroid[None, :]
+            + 0.02 * rng.standard_normal((T, dim)).astype(np.float32)
+        ).astype(np.float32)
+
+    return provider
+
+
+# --------------------------------------------------------------------------- #
+# Retrieval cache (within-group leave-one-out) + random controls
+# --------------------------------------------------------------------------- #
+def build_robotwin_retrieval_cache(
+    corpus: RoboTwinCorpus,
+    k: int,
+    embeddings_provider: Callable[[str], np.ndarray],
+):
+    """Within-task leave-one-out ``RetrievalCache`` over all frames.
+
+    For each task group, stack every frame's per-frame embedding, then for each
+    query episode compute raw-L2 distances to all group frames, mask the query's
+    own frames (leave-one-out), and keep the top-k. Mirrors
+    ``build_droid_retrieval_cache`` but takes an explicit per-frame embedding
+    provider (RoboTwin ships no precomputed embeddings)."""
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    cache = RetrievalCache(
+        k=k, meta={"source": "robotwin", "k": k, "loeo": True, "device": device}
+    )
+    emb = {
+        h: np.asarray(embeddings_provider(h), dtype=np.float32) for h in corpus.hashes
+    }
+    for g, hs in corpus.group_to_hashes.items():
+        if len(hs) < 2:
+            logger.warning("group %s has <2 episodes; skipping (no leave-one-out)", g)
+            continue
+        vecs, ref_hash, ref_frame = [], [], []
+        for h in hs:
+            v = emb[h]
+            vecs.append(v)
+            ref_hash.append(np.full(v.shape[0], h))
+            ref_frame.append(np.arange(v.shape[0], dtype=np.int32))
+        ref_hash = np.concatenate(ref_hash)
+        ref_frame = np.concatenate(ref_frame)
+        bank = torch.from_numpy(np.concatenate(vecs, axis=0)).to(device)  # (N, D)
+
+        for qh in hs:
+            qv = torch.from_numpy(emb[qh]).to(device)  # (Tq, D)
+            d = torch.cdist(qv, bank)  # (Tq, N) raw L2
+            self_rows = torch.from_numpy(ref_hash == qh).to(device)
+            d[:, self_rows] = float("inf")  # leave-one-out
+            kk = min(k, int((ref_hash != qh).sum()))
+            dist, top = torch.topk(d, kk, dim=1, largest=False)  # ascending
+            top = top.cpu().numpy()
+            dist = dist.cpu().numpy().astype(np.float32)
+            bh = ref_hash[top]
+            bf = ref_frame[top]
+            if kk < k:  # pad to fixed width
+                pad = k - kk
+                bh = np.pad(bh, ((0, 0), (0, pad)), constant_values="")
+                bf = np.pad(bf, ((0, 0), (0, pad)), constant_values=-1)
+                dist = np.pad(dist, ((0, 0), (0, pad)), constant_values=np.inf)
+            cache.add(
+                qh,
+                bh.astype("U"),
+                bf.astype(np.int32),
+                dist.astype(np.float32),
+                group_id=f"{g}:loeo:{qh}",
+            )
+    return cache
+
+
+def build_cross_embodiment_retrieval_cache(
+    query_corpus: RoboTwinCorpus,
+    bank_corpus: RoboTwinCorpus,
+    k: int,
+    query_embeddings_provider: Callable[[str], np.ndarray],
+    bank_embeddings_provider: Callable[[str], np.ndarray],
+):
+    """Cross-EMBODIMENT retrieval cache: each QUERY frame (embodiment B) retrieves
+    its top-k BANK frames (embodiment A) of the SAME task, by head-image L2.
+
+    Unlike ``build_robotwin_retrieval_cache`` (within-corpus leave-one-out), query
+    and bank are DIFFERENT corpora (different embodiments doing the same tasks).
+    Groups are matched by ``group_id`` (task name), so the two corpora must use a
+    parallel ``<task>/data`` layout. No leave-one-out — the embodiments don't share
+    episodes, so a query frame can never retrieve "itself". The retrieved demos thus
+    show a *different robot* (emb A) performing the query's task; the model must
+    transfer that guidance to predict emb B's actions.
+
+    The cached bank refs (``episode_hash``/``frame_idx``) resolve against
+    ``bank_corpus`` — pair this with ``make_robotwin_bank_provider(bank_corpus, ...)``
+    so the spliced demo image/state/action come from embodiment A (its own quantiles).
+    """
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    cache = RetrievalCache(
+        k=k,
+        meta={"source": "robotwin_xemb", "k": k, "loeo": False, "device": device},
+    )
+    q_emb = {
+        h: np.asarray(query_embeddings_provider(h), dtype=np.float32)
+        for h in query_corpus.hashes
+    }
+    b_emb = {
+        h: np.asarray(bank_embeddings_provider(h), dtype=np.float32)
+        for h in bank_corpus.hashes
+    }
+    for g, qhs in query_corpus.group_to_hashes.items():
+        bhs = bank_corpus.group_to_hashes.get(g)
+        if not bhs:
+            logger.warning(
+                "cross-emb: query group %s has no matching bank group; skipping", g
+            )
+            continue
+        vecs, ref_hash, ref_frame = [], [], []
+        for h in bhs:
+            v = b_emb[h]
+            vecs.append(v)
+            ref_hash.append(np.full(v.shape[0], h))
+            ref_frame.append(np.arange(v.shape[0], dtype=np.int32))
+        ref_hash = np.concatenate(ref_hash)
+        ref_frame = np.concatenate(ref_frame)
+        bank = torch.from_numpy(np.concatenate(vecs, axis=0)).to(device)  # (N, D)
+        kk = min(k, int(ref_hash.shape[0]))
+        for qh in qhs:
+            qv = torch.from_numpy(q_emb[qh]).to(device)  # (Tq, D)
+            d = torch.cdist(qv, bank)  # (Tq, N) raw L2
+            dist, top = torch.topk(d, kk, dim=1, largest=False)  # ascending
+            top = top.cpu().numpy()
+            dist = dist.cpu().numpy().astype(np.float32)
+            bh = ref_hash[top]
+            bf = ref_frame[top]
+            if kk < k:  # pad to fixed width
+                pad = k - kk
+                bh = np.pad(bh, ((0, 0), (0, pad)), constant_values="")
+                bf = np.pad(bf, ((0, 0), (0, pad)), constant_values=-1)
+                dist = np.pad(dist, ((0, 0), (0, pad)), constant_values=np.inf)
+            cache.add(
+                qh,
+                bh.astype("U"),
+                bf.astype(np.int32),
+                dist.astype(np.float32),
+                group_id=f"{g}:xemb:{qh}",
+            )
+    return cache
+
+
+def build_random_neighbor_cache(
+    corpus: RoboTwinCorpus,
+    k: int,
+    scope: str = "within",
+    seed: int = 0,
+    embeddings_provider: Callable[[str], np.ndarray] | None = None,
+):
+    """Random-retrieval control cache (RANDOM neighbors instead of kNN).
+
+      scope="within": random demos from the query's OWN task group (leave-one-out)
+                      -> "given the right task bank, does kNN *ranking* matter?"
+      scope="bank"  : random demos from ALL groups pooled (leave-one-episode-out)
+                      -> "does retrieving the *right task* matter at all?"
+
+    ``dist`` carries the true embedding L2 (so distance-weighted interpolation #2
+    barely fires for far random demos) when ``embeddings_provider`` is given,
+    else 0 (with a warning). Mirrors ``droid_data.build_random_neighbor_cache``."""
+    rng = np.random.default_rng(seed)
+    cache = RetrievalCache(k=k, meta={"source": "robotwin", "random": scope, "k": k})
+    g2h = corpus.group_to_hashes
+    h2g = {h: g for g, hs in g2h.items() for h in hs}
+    all_h = [h for hs in g2h.values() for h in hs]
+    nf = {h: corpus.num_frames(h) for h in all_h}
+    emb = (
+        {h: np.asarray(embeddings_provider(h), dtype=np.float32) for h in all_h}
+        if embeddings_provider is not None
+        else None
+    )
+    if emb is None:
+        logger.warning(
+            "build_random_neighbor_cache: no embeddings_provider; dist=0 (random "
+            "demos will get full interpolation weight — pass a provider for #2)"
+        )
+    for h in all_h:
+        T, g = nf[h], h2g[h]
+        if scope == "within":
+            pool = [x for x in g2h[g] if x != h]
+        else:
+            pool = [x for x in all_h if x != h]
+        if not pool:  # singleton group under within-scope: fall back to whole bank
+            pool = [x for x in all_h if x != h]
+        ep = rng.integers(0, len(pool), size=(T, k))
+        bh = np.empty((T, k), dtype=object)
+        bf = np.zeros((T, k), dtype=np.int32)
+        dist = np.zeros((T, k), dtype=np.float32)
+        for t in range(T):
+            for j in range(k):
+                eh = pool[int(ep[t, j])]
+                fj = int(rng.integers(0, nf[eh]))
+                bh[t, j] = eh
+                bf[t, j] = fj
+                if emb is not None:
+                    diff = emb[h][t] - emb[eh][fj]
+                    dist[t, j] = float(np.sqrt(diff @ diff))
+        cache.add(
+            h,
+            bh.astype("U"),
+            bf.astype(np.int32),
+            dist,
+            group_id=f"{g}:rand-{scope}:{h}",
+        )
+    return cache
+
+
+def _verify_cache(cache, corpus: RoboTwinCorpus) -> None:
+    """Spot-check: neighbors are in the query's group, never self, dists sorted."""
+    n_checked = 0
+    for qh in cache.query_hashes:
+        g = corpus.group_of(qh)
+        group_hashes = set(corpus.group_to_hashes[g])
+        bh, bf, dd = cache.neighbors(qh, 0)
+        valid = [str(x) for x in bh if str(x)]
+        assert qh not in valid, f"{qh}: self in neighbors"
+        for h in valid:
+            assert h in group_hashes, f"{qh}: neighbor {h} not in group {g}"
+        finite = dd[np.isfinite(dd)]
+        assert np.all(np.diff(finite) >= -1e-3), f"{qh}: distances not ascending"
+        n_checked += 1
+    print(f"  verified {n_checked} query episodes (in-group, no self, sorted dists)")
+
+
+# --------------------------------------------------------------------------- #
+# Norm-stats stub + action converter
+# --------------------------------------------------------------------------- #
+class RoboTwinNormStats:
+    """Minimal norm-stats surface PI's constructor + process_batch touch.
+
+    The shim normalizes in the dataset, so only the structural methods are
+    exercised in the train + flow-loss-eval path; ``unnormalize`` is a pass-through.
+    """
+
+    KEY_TYPES = {
+        "base_0_rgb": "camera_keys",
+        "left_wrist_0_rgb": "camera_keys",
+        "right_wrist_0_rgb": "camera_keys",
+        STATE_KEY: "proprio_keys",
+        AC_KEY: "action_keys",
+    }
+
+    def __init__(self, emb_id: int = EMB_ID):
+        self.emb_id = int(emb_id)
+
+    def keys_of_type(self, key_type: str, embodiment_id: int) -> list[str]:
+        if embodiment_id != self.emb_id:
+            return []
+        return [k for k, t in self.KEY_TYPES.items() if t == key_type]
+
+    def is_key_with_embodiment(self, key: str, embodiment_id: int) -> bool:
+        return embodiment_id == self.emb_id and key in self.KEY_TYPES
+
+    def zarr_key_to_keyname(self, key: str, embodiment_id: int):
+        if embodiment_id == self.emb_id and key in self.KEY_TYPES:
+            return key
+        return None
+
+    def unnormalize(self, batch, embodiment_id):  # pragma: no cover (sampling-only)
+        return batch
+
+
+class Passthrough32(BaseActionConverter):
+    """No-op converter: RoboTwin actions are already slot-filled to 32-D."""
+
+    def to32(self, actions: torch.Tensor) -> torch.Tensor:
+        return _pad32(actions)
+
+    def from32(self, actions32: torch.Tensor) -> torch.Tensor:
+        return actions32
diff --git a/egomimic/ricl/robotwin_eval.py b/egomimic/ricl/robotwin_eval.py
new file mode 100644
index 000000000..a38099887
--- /dev/null
+++ b/egomimic/ricl/robotwin_eval.py
@@ -0,0 +1,72 @@
+"""Validation for the RoboTwin RICL run — the RoboTwin analog of ``DroidRiclEval``.
+
+Reuses the proven DROID evaluator wholesale (retrieval / random-within /
+random-bank / clean zero-context floor on the *raw* batch, paired-seed flow loss
+averaged over ``n_flow_samples``, optional sampled-action MSE/L1/gripper-accuracy,
+and distance-weighted interpolation #2). The ONLY embodiment-specific change is
+``_sampled_metrics``: RoboTwin is 16-D joint-space with **two** grippers (slots 7
+and 15), vs DROID's 8-D single gripper at slot 7 — so the metric is restricted to
+the real 16 dims and gripper accuracy is scored at both slots.
+
+Mirrors ``egomimic/ricl/droid_eval.py`` line-for-line except the dim/gripper
+constants — keep the two in sync if the DROID eval changes.
+"""
+
+from __future__ import annotations
+
+import torch
+
+from egomimic.ricl import metrics as M
+from egomimic.ricl import robotwin_data as R
+from egomimic.ricl.droid_eval import DroidRiclEval, DroidRiclModelWrapper
+from egomimic.rldb.embodiment.embodiment import get_embodiment
+
+
+class RoboTwinRiclEval(DroidRiclEval):
+    """DROID's retrieval-vs-floor flow-loss eval, parametrized for RoboTwin's
+    16-D joint-space action with two grippers."""
+
+    def __init__(
+        self, *args, gripper_indices=R.GRIPPER_SLOTS, raw_dim=R.RAW_DIM, **kwargs
+    ):
+        super().__init__(*args, gripper_indices=gripper_indices, **kwargs)
+        # RoboTwin's real qpos dim (detect per-corpus: 14 for aloha-agilex, 16 for
+        # 7-DOF). Slice the sampled-action error to these dims; the 32-D slot-fill
+        # pad dims are zero in the target and would only dilute the metric.
+        self._raw_dim = int(raw_dim)
+        self._gripper_indices = tuple(gripper_indices)
+
+    def _sampled_metrics(self, processed_batch, seed: int, *, dist_max: float = 1.0):
+        """Sampled-action MSE/L1/gripper-accuracy (mirrors DroidRiclEval but over
+        RoboTwin's real 16 dims and both gripper slots)."""
+        algo = self.model
+        base: dict[str, float] = {}
+        sweep: dict[str, float] = {}
+        d = self._raw_dim
+        torch.manual_seed(seed)
+        preds = algo.forward_eval(processed_batch)
+        for emb_id, _b in processed_batch.items():
+            name = get_embodiment(emb_id).lower()
+            ac_key = algo.ac_keys[emb_id]
+            pred_key = f"{name}_{ac_key}"
+            if pred_key not in preds:
+                continue
+            p = preds[pred_key].detach().cpu()[..., :d]
+            g = _b[ac_key].detach().cpu()[..., :d]
+            base[f"{name}_sampled_mse"] = M.cartesian_mse(p, g)
+            base[f"{name}_sampled_l1"] = M.cartesian_l1(p, g)
+            ga = M.gripper_accuracy(p, g, self._gripper_indices, 0.0)
+            if ga == ga:  # not NaN
+                base[f"{name}_sampled_gripper_acc"] = ga
+            for lam in self.interp_lamdas:
+                p_l, wmean = self._interpolate_toward_neighbor(p, _b, dist_max, lam)
+                if p_l is None:
+                    continue
+                sweep[f"{name}_sampled_mse_l{lam:g}"] = M.cartesian_mse(p_l, g)
+                sweep[f"{name}_interp_wmean_l{lam:g}"] = wmean
+        return base, sweep
+
+
+class RoboTwinRiclModelWrapper(DroidRiclModelWrapper):
+    """Identical to DroidRiclModelWrapper: pass the RAW val batch to the evaluator
+    (for a clean floor) and keep the fit/validation barriers single-device-safe."""
diff --git a/egomimic/ricl/robotwin_fork_eval.patch b/egomimic/ricl/robotwin_fork_eval.patch
new file mode 100644
index 000000000..a4e2777ac
--- /dev/null
+++ b/egomimic/ricl/robotwin_fork_eval.patch
@@ -0,0 +1,180 @@
+diff --git a/envs/robot/planner.py b/envs/robot/planner.py
+index 21ae432..6b9d6e4 100644
+--- a/envs/robot/planner.py
++++ b/envs/robot/planner.py
+@@ -271,9 +271,40 @@ try:
+             return result_p, result_q
+     
+ except Exception as e:
+-    print('[planner.py]: Something wrong happened when importing CuroboPlanner! Please check if Curobo is installed correctly. If the problem still exists, you can install Curobo from https://github.com/NVlabs/curobo manually.')
+-    print('Exception traceback:')
+-    traceback.print_exc()
++    # EgoVerse patch: curobo is intentionally NOT installed for policy eval (the
++    # policy drives the arms directly in joint space, so no arm motion planning is
++    # needed). Provide an in-process stub so envs/robot import cleanly and the robot
++    # can still build a "planner". Only gripper interpolation is exercised at eval.
++    print('[planner.py]: Curobo unavailable — using EgoVerse no-op CuroboPlanner stub '
++          '(policy eval needs no arm motion planning).')
++
++    class CuroboPlanner:
++        def __init__(self, robot_origion_pose, active_joints_name, all_joints, yml_path=None):
++            self.robot_origion_pose = robot_origion_pose
++            self.active_joints_name = active_joints_name
++            self.all_joints = all_joints
++            self.yml_path = yml_path
++
++        def plan_grippers(self, now_val, target_val):
++            # Identical to the real CuroboPlanner.plan_grippers (linear interpolation).
++            num_step = 200
++            dis_val = target_val - now_val
++            step = dis_val / num_step
++            res = {}
++            vals = np.linspace(now_val, target_val, num_step)
++            res["num_step"] = num_step
++            res["per_step"] = step
++            res["result"] = vals
++            return res
++
++        def update_point_cloud(self, *args, **kwargs):
++            return None
++
++        def __getattr__(self, name):
++            # Any unused arm-planning method (plan_path/plan_pose/plan_batch/...) is a no-op.
++            def _noop(*args, **kwargs):
++                return {"status": "Fail"}
++            return _noop
+ 
+ 
+ # ********************** MplibPlanner **********************
+diff --git a/envs/robot/robot.py b/envs/robot/robot.py
+index 9dfc08f..ad0b648 100644
+--- a/envs/robot/robot.py
++++ b/envs/robot/robot.py
+@@ -259,6 +259,9 @@ class Robot:
+         abs_right_curobo_yml_path = os.path.join(CONFIGS.ROOT_PATH, self.right_curobo_yml_path)
+ 
+         self.communication_flag = (abs_left_curobo_yml_path != abs_right_curobo_yml_path)
++        # EgoVerse patch: force the in-process (stub) CuroboPlanner instead of curobo
++        # worker subprocesses — policy eval needs no arm motion planning.
++        self.communication_flag = False
+ 
+         if self.is_dual_arm:
+             abs_left_curobo_yml_path = abs_left_curobo_yml_path.replace("curobo.yml", "curobo_left.yml")
+diff --git a/script/eval_policy.py b/script/eval_policy.py
+index eded198..4459103 100644
+--- a/script/eval_policy.py
++++ b/script/eval_policy.py
+@@ -160,6 +160,10 @@ def main(usr_args):
+     st_seed = 100000 * (1 + seed)
+     suc_nums = []
+     test_num = 100
++    # EgoVerse patch: bound the number of policy rollouts via env (fast eval).
++    _env_test_num = os.environ.get("EVAL_TEST_NUM")
++    if _env_test_num:
++        test_num = int(_env_test_num)
+     topk = 1
+ 
+     model = get_model(usr_args)
+@@ -197,7 +201,9 @@ def eval_policy(task_name,
+     print(f"\033[34mTask Name: {args['task_name']}\033[0m")
+     print(f"\033[34mPolicy Name: {args['policy_name']}\033[0m")
+ 
+-    expert_check = True
++    # EgoVerse patch: skip the curobo-based expert solvability run — we eval the
++    # policy directly (no motion planning / curobo installed).
++    expert_check = False
+     TASK_ENV.suc = 0
+     TASK_ENV.test_num = 0
+ 
+@@ -253,10 +259,41 @@ def eval_policy(task_name,
+ 
+         args["render_freq"] = render_freq
+ 
+-        TASK_ENV.setup_demo(now_ep_num=now_id, seed=now_seed, is_test=True, **args)
+-        episode_info_list = [episode_info["info"]]
+-        results = generate_episode_descriptions(args["task_name"], episode_info_list, test_num)
+-        instruction = np.random.choice(results[0][instruction_type])
++        # EgoVerse patch: with expert_check disabled the early try/except above is
++        # skipped, so this setup_demo is the only scene init. Guard it — RoboTwin's
++        # physics-settling check raises UnStableError for some random object
++        # placements (intended to be resampled, common under domain randomization),
++        # and other init errors shouldn't crash the whole eval. Resample a fresh
++        # seed instead. succ_seed was already incremented above for the no-expert
++        # path, so undo it before retrying.
++        try:
++            TASK_ENV.setup_demo(now_ep_num=now_id, seed=now_seed, is_test=True, **args)
++        except UnStableError as e:
++            try:
++                TASK_ENV.close_env()
++            except Exception:
++                pass
++            succ_seed -= 1
++            now_seed += 1
++            print(f"unstable scene, resampling seed: {e}")
++            continue
++        except Exception as e:
++            try:
++                TASK_ENV.close_env()
++            except Exception:
++                pass
++            succ_seed -= 1
++            now_seed += 1
++            print(f"scene init error, resampling seed: {e}")
++            continue
++        if expert_check:
++            episode_info_list = [episode_info["info"]]
++            results = generate_episode_descriptions(args["task_name"], episode_info_list, test_num)
++            instruction = np.random.choice(results[0][instruction_type])
++        else:
++            # EgoVerse patch: no expert run → no episode_info; use the task name
++            # (underscores -> spaces) as the language instruction.
++            instruction = args["task_name"].replace("_", " ")
+         TASK_ENV.set_instruction(instruction=instruction)  # set language instruction
+ 
+         if TASK_ENV.eval_video_path is not None:
+@@ -290,12 +327,19 @@ def eval_policy(task_name,
+ 
+         succ = False
+         reset_func(model)
+-        while TASK_ENV.take_action_cnt < TASK_ENV.step_lim:
+-            observation = TASK_ENV.get_obs()
+-            eval_func(TASK_ENV, model, observation)
+-            if TASK_ENV.eval_success:
+-                succ = True
+-                break
++        try:
++            while TASK_ENV.take_action_cnt < TASK_ENV.step_lim:
++                observation = TASK_ENV.get_obs()
++                eval_func(TASK_ENV, model, observation)
++                if TASK_ENV.eval_success:
++                    succ = True
++                    break
++        except Exception as e:
++            # EgoVerse patch: some tasks' check_success references expert-only state
++            # (e.g. self.arm_tag, set in play_once which no-expert eval never runs).
++            # Count the episode as a failure instead of crashing the multi-task eval.
++            print(f"eval step error, counting as failure: {e}")
++            succ = False
+         # task_total_reward += TASK_ENV.episode_score
+         if TASK_ENV.eval_video_path is not None:
+             TASK_ENV._del_eval_video_ffmpeg()
+diff --git a/task_config/demo_clean.yml b/task_config/demo_clean.yml
+index 7e0de0a..4b29be2 100644
+--- a/task_config/demo_clean.yml
++++ b/task_config/demo_clean.yml
+@@ -34,4 +34,4 @@ pcd_crop: true
+ save_path: ./data
+ clear_cache_freq: 5
+ collect_data: true
+-eval_video_log: true
++eval_video_log: false
+diff --git a/task_config/demo_randomized.yml b/task_config/demo_randomized.yml
+index d3fc5ed..d921d05 100644
+--- a/task_config/demo_randomized.yml
++++ b/task_config/demo_randomized.yml
+@@ -34,4 +34,4 @@ pcd_crop: true
+ save_path: ./data
+ clear_cache_freq: 5
+ collect_data: true
+-eval_video_log: true
++eval_video_log: false
diff --git a/egomimic/ricl/robotwin_new_cluster_setup.md b/egomimic/ricl/robotwin_new_cluster_setup.md
new file mode 100644
index 000000000..c6c992144
--- /dev/null
+++ b/egomimic/ricl/robotwin_new_cluster_setup.md
@@ -0,0 +1,202 @@
+# RoboTwin pi0.5 RICL — new-cluster setup
+
+End-to-end guide to stand up **training + closed-loop eval** of EgoVerse's pi0.5 RICL
+on RoboTwin 2.0 on a fresh SLURM/GPU cluster. Verified on the Georgia Tech PACE cluster
+(`/storage/project/r-dxu345-0/...`). For the per-run command cheatsheet see `robotwin_setup.md`; for code
+layout see `CLAUDE.md`.
+
+Throughout, let `REPO=/path/to/EgoVerse` and run from `$REPO`.
+
+---
+
+## 0. Assumptions
+
+- Linux + SLURM, NVIDIA GPUs, CUDA 12.x driver (see gotcha G1 — some nodes lag).
+- Python 3.11, the project venv managed by **`uv`** (no `pip` inside it — see G2).
+- AWS/R2 creds only if you also pull the SQL episode registry; **not needed** for the
+  RoboTwin path (it's local HDF5/zarr).
+- GPU memory: the h200s here (~141 GB) run full fp32 AdamW of the 3.6 B model (~57 GB)
+  comfortably (step 6).
+
+---
+
+## 1. Repo + submodules
+
+```bash
+git clone <egoverse remote> $REPO && cd $REPO
+git checkout ryanco/robotwin-sim
+git submodule update --init external/RoboTwin external/openpi
+```
+`external/RoboTwin` is the `GaTech-RL2/RoboTwin` fork and carries the
+`policy/pi_ricl_egoverse/` deploy shim. (Ignore any stray `external/robocasa`/
+`external/robosuite` gitlinks — not used.)
+
+---
+
+## 2. Project venv (egomimic)
+
+The venv is `uv`-managed and installs the package editable as `egomimic`.
+
+```bash
+cd $REPO
+uv venv emimic --python 3.11
+source emimic/bin/activate
+uv pip install -e .            # or `uv sync` if the repo ships a uv.lock workflow
+python -c "import torch; print(torch.__version__)"   # expect 2.7.x +cuXXX
+```
+**Always install with `uv pip install`, never `pip`** (G2).
+
+---
+
+## 3. PaliGemma tokenizer (offline-safe)
+
+pi0.5 needs the PaliGemma tokenizer. Vendor it locally so compute nodes don't hit the
+gated HF download:
+
+```bash
+source emimic/bin/activate
+python - <<'PY'
+from transformers import AutoTokenizer
+AutoTokenizer.from_pretrained("google/paligemma-3b-mix-224").save_pretrained("egomimic/ricl/pg_tokenizer")
+PY
+```
+`pg_tokenizer/` is gitignored. If the model isn't already in the HF cache you'll need an
+HF token (`huggingface-cli login`) once.
+
+---
+
+## 4. pi0.5 base checkpoint
+
+Training fine-tunes from the PyTorch pi0.5 base at:
+```
+egomimic/algo/pi_checkpoints/pi05_base_pytorch/{config.json, model.safetensors}   (~6.8 GB)
+```
+Provision it by copying from an existing cluster, or convert the JAX/openpi base to
+PyTorch (see the JAX→PyTorch conversion command in the repo history /
+`egomimic/algo/pi_checkpoints/`). The trainer's `--ckpt` defaults to this repo-relative
+path.
+
+---
+
+## 5. RoboTwin data → zarr (TODO 1)
+
+```bash
+source emimic/bin/activate
+# ~230 MB: beat_block_hammer / aloha-agilex / clean_50 from HF TianxingChen/RoboTwin2.0
+python -m egomimic.ricl.scripts.download_robotwin --mode hf --out egomimic/ricl/outputs/robotwin_raw
+# optional: validate the EgoVerse-zarr converter on a few episodes
+python -m egomimic.ricl.scripts.robotwin_to_zarr \
+  --root egomimic/ricl/outputs/robotwin_raw/extracted --out egomimic/ricl/outputs/robotwin_zarr --limit 5
+# CPU smoke (no GPU): validates collate + RICL prompt + token budget
+python egomimic/ricl/scripts/train_robotwin_ricl.py --stage cpu \
+  --root egomimic/ricl/outputs/robotwin_raw/extracted --embed fake
+```
+The data lands one level deep (`.../extracted/<task>__<emb>_<setting>/<...>/data/`); the
+trainer's recursive `**/data` glob finds it, so always pass `--root .../extracted`.
+
+---
+
+## 6. Train (TODO 1)
+
+The h200's ~141 GB fits full fp32 AdamW of the 3.6 B model (~57 GB), so no 8-bit
+optimizer is needed. (On a ≤ 48 GB GPU, add `--adam8bit` to the sbatch — it needs
+`uv pip install bitsandbytes`.)
+
+Edit `egomimic/ricl/scripts/train_robotwin_ricl.sbatch` for your cluster
+(`--partition`/`--account`/`--gres`, the `cd $REPO`, and `source emimic/bin/activate`);
+it ships preset for PACE (`gpu-h200` / `gts-dxu345-rl2` / `qos inferno`). Then:
+```bash
+sbatch egomimic/ricl/scripts/train_robotwin_ricl.sbatch
+# knobs via env: CKPT_EVERY, VAL_EVERY, MAX_STEPS, BATCH_SIZE, EMBED, ROOT
+```
+The sbatch sets `--batch-size 2` and
+`PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True`. `--embed dinov2` builds the
+retrieval cache via DINOv2 (`torch.hub`; pre-cache if compute nodes are offline).
+Outputs: `egomimic/ricl/outputs/robotwin_train/robotwin_ricl/version_*/`
+(`checkpoints/*.ckpt` + `quantiles.json`). Expect loss to fall from ~1.5 toward <0.1.
+
+---
+
+## 7. Closed-loop eval (TODO 2)
+
+### 7a. Demo-bank DINOv2 index
+```bash
+sbatch -p gpu-h200 -A gts-dxu345-rl2 -q inferno --gres=gpu:h200:1 -c8 --mem=64G --wrap=\
+ "emimic/bin/python egomimic/ricl/scripts/build_robotwin_bank_index.py \
+    --root egomimic/ricl/outputs/robotwin_raw/extracted \
+    --out egomimic/ricl/outputs/robotwin_bank_index --embed dinov2"
+```
+(Use the venv python directly — `--wrap` runs under `dash`, where `source` fails, G4.)
+
+### 7b. Sim stack — install SELECTIVELY (do NOT run RoboTwin's `_install.sh`, it pins `torch==2.4.1`, G3)
+```bash
+uv pip install sapien==3.0.0b1 mplib==0.2.1 open3d trimesh "pyglet<2"
+# verify torch is still 2.7.x AND `import sapien` works
+# curobo / pytorch3d are NOT installed — see patches below.
+```
+Assets (~16 GB):
+```bash
+emimic/bin/python external/RoboTwin/assets/_download.py        # background_texture/embodiments/objects .zip
+# unzip each into external/RoboTwin/assets/, then:
+emimic/bin/python external/RoboTwin/script/update_embodiment_config_path.py
+```
+
+### 7c. Patch the RoboTwin fork (lets policy eval run without curobo)
+Policy eval drives joints directly (qpos), so no motion planning is needed:
+1. `external/RoboTwin/envs/robot/planner.py` — in the curobo-import `except`, define a
+   stub `class CuroboPlanner` (constructible; a real `plan_grippers` that linearly
+   interpolates `{num_step, per_step, result}`; `__getattr__` returns a no-op
+   `{"status":"Fail"}` for the unused arm planner).
+2. `external/RoboTwin/envs/robot/robot.py` `set_planner` — force
+   `self.communication_flag = False` (in-process stub, not curobo worker subprocesses).
+3. `external/RoboTwin/script/eval_policy.py` — `expert_check = False`; guard the
+   `episode_info`/`generate_episode_descriptions` block and fall back to the task name
+   as the instruction; honor `EVAL_TEST_NUM` to bound episode count.
+4. `external/RoboTwin/task_config/demo_clean.yml` — `eval_video_log: false`.
+5. `external/RoboTwin/policy/pi_ricl_egoverse/deploy_policy.yml` — set absolute
+   `egoverse_checkpoint`, `bank_root`, `bank_index_dir`, `quantiles_path`.
+
+### 7d. Run
+Edit `egomimic/ricl/scripts/eval_robotwin_ricl.sbatch` partition/account, then:
+```bash
+CKPT=<abs path to .ckpt> EVAL_TEST_NUM=10 \
+  sbatch egomimic/ricl/scripts/eval_robotwin_ricl.sbatch
+```
+The sbatch activates the venv, sets `TORCH_COMPILE_DISABLE=1` (eval-only — pi0.5
+`sample_actions` otherwise triggers a multi-minute compile, G5) and runs `python -u`.
+Success: log shows `Render Well` then `Success rate: k/n` per episode and `eval exit: 0`.
+
+---
+
+## 8. Gotchas / troubleshooting
+
+- **G1 — bad GPU node.** `nvidia-smi` shows the GPU but torch errors `No CUDA GPUs are
+  available` → that node's driver is too old for torch cu126. Exclude it:
+  `sbatch --exclude=<node> ...`.
+- **G2 — venv has no `pip`.** Use `uv pip install`. Bare `pip` silently hits a stray
+  system Python; `python -m pip` says "No module named pip".
+- **G3 — RoboTwin deps pin old torch.** Never install RoboTwin's `requirements.txt` or
+  `_install.sh` wholesale (pins `torch==2.4.1`, breaks the shared env). Install sim deps
+  selectively and verify torch is unchanged after every install (`uv pip install
+  --dry-run ...` first).
+- **G4 — `sbatch --wrap` uses `dash`.** `source` fails; call `emimic/bin/python` (or
+  `. emimic/bin/activate`) directly.
+- **G5 — torch.compile.** Leave compile ON for training; set `TORCH_COMPILE_DISABLE=1`
+  for eval/smoke (avoids minutes of max-autotune warmup).
+- **G6 — inferno preemption.** The shared `inferno`/`gpu-h200` queue preempts
+  allocations mid-run, which can wedge a held `salloc`/`srun`. Submit unattended jobs
+  with `sbatch`, not interactive `salloc`.
+- **G7 — buffered logs.** Run `python -u`; otherwise stdout (episode prints) only flushes
+  on exit when redirected to a file.
+- **G8 — `--root` nesting.** Always point data `--root` at `.../extracted` (the recursive
+  `**/data` glob finds the nested task dir).
+
+---
+
+## 9. Quick verification ladder
+
+1. `pytest egomimic/ricl/tests/robotwin_*_test.py -q` → all pass (CPU, synthetic).
+2. `--stage cpu` smoke → `ALL CHECKS PASSED`.
+3. Short GPU train (`MAX_STEPS=10`) → produces a `.ckpt`, loss prints.
+4. Build bank index → `vectors.npy`/`refs.npz`/`manifest.json`.
+5. Eval `EVAL_TEST_NUM=2` → `Render Well` + `Success rate: k/2` + `eval exit: 0`.
diff --git a/egomimic/ricl/robotwin_policy.py b/egomimic/ricl/robotwin_policy.py
new file mode 100644
index 000000000..db7d914a5
--- /dev/null
+++ b/egomimic/ricl/robotwin_policy.py
@@ -0,0 +1,274 @@
+"""EgoVerse RICL policy for RoboTwin's closed-loop eval (the source of truth).
+
+RoboTwin's eval driver loads a policy by ``importlib.import_module(policy_name)`` and
+calls module-level ``get_model`` / ``eval`` / ``reset_model`` (and the policy object's
+``set_language`` / ``update_observation_window`` / ``get_action`` /
+``reset_obsrvationwindows``). That contract lives in the RoboTwin tree at
+``policy/pi_ricl_egoverse/`` — but only as a **thin shim** that re-exports this module
+(``from egomimic.ricl.robotwin_policy import *``), so the actual logic stays here in
+egomimic next to the adapter glue (``robotwin_adapter``) and stays unit-tested.
+
+This wraps the EgoVerse PyTorch ``PIRicl`` policy with online RICL retrieval (vs the
+stock pi05 openpi-JAX path). Per inference: embed the live head frame -> kNN against a
+prebuilt demo bank -> splice the retrieved (image, state, action) blocks into the pi0.5
+prefix -> sample an action chunk -> un-normalize the model's 32-D output back to
+RoboTwin's native qpos. torch + the EgoVerse algo + DINOv2 are imported lazily so this
+module imports without a GPU/checkpoint (the model-free glue is exercised by
+``egomimic/ricl/tests/robotwin_adapter_test.py``). The PIRicl construction mirrors
+``egomimic/ricl/scripts/train_robotwin_ricl.build_model``; verify the checkpoint-load +
+``forward_eval`` input contract on first deploy.
+
+``usr_args`` keys (set in the shim's ``deploy_policy.yml`` + eval.sh overrides):
+    egoverse_checkpoint : path to the trained Lightning ``.ckpt``
+    bank_root           : RoboTwin task dir whose demos form the retrieval bank
+    bank_index_dir      : consolidated DINOv2 index for ``bank_root`` (build_embedding_index)
+    quantiles_path      : norm-stats JSON saved at training (RoboTwinCorpus.save_quantiles)
+    k, action_horizon, pi0_step : retrieval/inference sizes
+"""
+
+from __future__ import annotations
+
+import os
+
+import numpy as np
+
+# Vendored (gitignored) PaliGemma tokenizer — same one training uses; avoids a
+# gated HF download on the eval node. Override via usr_args["tokenizer"].
+DEFAULT_TOKENIZER_DIR = os.path.join(
+    os.path.dirname(os.path.abspath(__file__)), "pg_tokenizer"
+)
+
+__all__ = [
+    "encode_obs",
+    "get_model",
+    "eval",
+    "reset_model",
+    "PIRiclPolicy",
+]
+
+
+# --------------------------------------------------------------------------- #
+# RoboTwin deploy contract (module-level functions the eval driver calls)
+# --------------------------------------------------------------------------- #
+def encode_obs(observation):
+    """RoboTwin obs -> ([head, right, left] rgb, qpos vector). Mirrors pi05."""
+    from egomimic.ricl.robotwin_adapter import obs_to_state
+
+    return obs_to_state(observation)
+
+
+def get_model(usr_args):
+    return PIRiclPolicy(usr_args)
+
+
+def eval(TASK_ENV, model, observation):  # noqa: A001 (name required by RoboTwin driver)
+    if model.observation_window is None:
+        instruction = TASK_ENV.get_instruction()
+        model.set_language(instruction)
+
+    input_rgb_arr, input_state = encode_obs(observation)
+    model.update_observation_window(input_rgb_arr, input_state)
+
+    actions = model.get_action()[: model.pi0_step]
+    for action in actions:
+        TASK_ENV.take_action(action)  # default qpos control mode (joint-space)
+        observation = TASK_ENV.get_obs()
+        input_rgb_arr, input_state = encode_obs(observation)
+        model.update_observation_window(input_rgb_arr, input_state)
+
+
+def reset_model(model):
+    model.reset_obsrvationwindows()
+
+
+# --------------------------------------------------------------------------- #
+# Policy object
+# --------------------------------------------------------------------------- #
+class PIRiclPolicy:
+    """RoboTwin ``PI0``-shaped wrapper around EgoVerse ``PIRicl`` + online retrieval."""
+
+    def __init__(self, usr_args: dict):
+        import torch  # noqa: F401  (asserts the torch env exists)
+
+        from egomimic.ricl import robotwin_adapter as A
+        from egomimic.ricl import robotwin_data as R
+        from egomimic.ricl.retrieval import DinoV2Embedder
+        from egomimic.ricl.scripts.build_embedding_index import build_retrieval_index
+
+        self._A = A
+        self.pi0_step = int(usr_args.get("pi0_step", 50))
+        self.action_horizon = int(usr_args.get("action_horizon", 15))
+        self.k = int(usr_args.get("k", 4))
+        self.tokenizer_dir = usr_args.get("tokenizer") or DEFAULT_TOKENIZER_DIR
+        # Plain-finetune baseline (ablation): no online retrieval, no spliced demos —
+        # PIRicl runs as base pi0.5 when no ricl_retrieved_* keys are present.
+        # Accept a yaml bool or a string override ("true"/"1"/...).
+        _ni = usr_args.get("no_incontext", False)
+        self.no_incontext = (
+            _ni
+            if isinstance(_ni, bool)
+            else str(_ni).strip().lower() in ("1", "true", "yes")
+        )
+
+        # Norm quantiles from training (so eval normalizes identically). These apply
+        # to the QUERY state input + the model's action output (the predicted
+        # embodiment). For CROSS-EMBODIMENT eval the in-context bank is a DIFFERENT
+        # embodiment, so its demos must be normalized with that embodiment's own
+        # quantiles — pass ``bank_quantiles_path`` (defaults to ``quantiles_path`` for
+        # the same-embodiment case, preserving existing behavior).
+        self.quantiles = R.load_quantiles(usr_args["quantiles_path"])
+        bank_quantiles = (
+            R.load_quantiles(usr_args["bank_quantiles_path"])
+            if usr_args.get("bank_quantiles_path")
+            else self.quantiles
+        )
+
+        # state_dim/gripper layout from the corpus (cheap; reads headers only). The
+        # bank corpus normalizes retrieved demos with the BANK embodiment's quantiles.
+        bank_corpus = R.RoboTwinCorpus(usr_args["bank_root"], quantiles=bank_quantiles)
+        self.state_dim = bank_corpus.state_dim
+        self.gripper_slots = bank_corpus.gripper_slots
+        if self.no_incontext:
+            self.retriever = None
+        else:
+            # Demo bank: RoboTwin corpus + consolidated DINOv2 index, queried online.
+            bank_provider = R.make_robotwin_bank_provider(
+                bank_corpus, action_horizon=self.action_horizon
+            )
+            index = build_retrieval_index(usr_args["bank_index_dir"])
+            self.retriever = A.OnlineRetriever(
+                index,
+                bank_provider,
+                DinoV2Embedder(),
+                k=self.k,
+                action_horizon=self.action_horizon,
+                state_dim=self.state_dim,
+            )
+
+        self.algo = self._load_algo(usr_args["egoverse_checkpoint"])
+        self.observation_window = None
+        self.instruction = None
+
+    def _load_algo(self, ckpt_path: str):
+        """Reconstruct PIRicl and load the trained Lightning checkpoint weights.
+
+        Mirrors ``train_robotwin_ricl.build_model`` for the architecture, then loads
+        the checkpoint's ``state_dict`` (the ckpt is a ModelWrapper, so weights are
+        under the ``model.`` prefix). Verify on first deploy."""
+        from types import SimpleNamespace
+
+        import torch
+
+        from egomimic.algo.pi_ricl import PIRicl
+        from egomimic.ricl import robotwin_data as R
+
+        config = SimpleNamespace(
+            pytorch_training_precision="bfloat16",
+            pytorch_weight_path=None,  # weights come from the trained ckpt below
+            model=SimpleNamespace(
+                pi05=True,
+                action_dim=32,
+                action_horizon=self.action_horizon,
+                max_token_len=4608,
+                paligemma_variant="gemma_2b",
+                action_expert_variant="gemma_300m",
+            ),
+        )
+        converters = SimpleNamespace(
+            rules={R.EMB_NAME: R.Passthrough32()},
+            fallback=R.Passthrough32(),
+            ac_key=R.AC_KEY,
+        )
+        algo = PIRicl(
+            norm_stats=R.RoboTwinNormStats(),
+            camera_transforms=None,
+            domains=[R.EMB_NAME],
+            train_image_augs=None,
+            eval_image_augs=None,
+            config=config,
+            ac_keys={R.EMB_NAME: R.AC_KEY},
+            action_converters=converters,
+            tokenizer_model_name=self.tokenizer_dir,
+            tokenizer_max_length=4608,
+            sampling_mode="random",
+            annotation_key="annotations",
+            default_prompt="",
+            proprio_in_prompt=True,
+            embodiment_label=True,
+            state_num_bins=256,
+            proprio_keys_for_prompt=[R.PROMPT_STATE_KEY],
+            num_retrieved_observations=(0 if self.no_incontext else self.k),
+            retrieved_action_steps=self.action_horizon,
+            ricl_base_key="base_0_rgb",
+            image_resolution=(224, 224),
+        )
+        ckpt = torch.load(ckpt_path, map_location="cpu", weights_only=False)
+        state_dict = ckpt.get("state_dict", ckpt)
+        # ModelWrapper stores the algo under ``model.``; strip that prefix.
+        weights = {
+            k[len("model.") :]: v
+            for k, v in state_dict.items()
+            if k.startswith("model.")
+        } or state_dict
+        algo.nets["policy"].load_state_dict(weights, strict=False)
+        # Standalone deploy (no Lightning ModelWrapper): place the model on GPU, set
+        # eval mode, and set algo.device so process_batch_for_training builds its
+        # tensors on the right device. (PIRicl is not an nn.Module; nets is.)
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+        algo.nets.to(device)
+        algo.nets.eval()
+        algo.device = device
+        return algo
+
+    def set_language(self, instruction: str) -> None:
+        self.instruction = instruction
+
+    def update_observation_window(self, img_arr, state) -> None:
+        # img_arr = [head, right, left] (from encode_obs); state = raw qpos vector.
+        self.observation_window = {
+            "base_0_rgb": np.asarray(img_arr[0]),
+            "right_wrist_0_rgb": np.asarray(img_arr[1]),
+            "left_wrist_0_rgb": np.asarray(img_arr[2]),
+            "state": np.asarray(state, dtype=np.float32),
+        }
+
+    def get_action(self):
+        """Sample an action chunk and map it to RoboTwin qpos (pi0_step, state_dim)."""
+        import torch
+
+        from egomimic.ricl import robotwin_data as R
+
+        assert self.observation_window is not None, "update observation_window first!"
+        w = self.observation_window
+        A = self._A
+
+        # Plain baseline: no retrieval -> no ricl_retrieved_* keys -> PIRicl == base pi0.5.
+        ricl = {} if self.no_incontext else self.retriever.retrieve(w["base_0_rgb"])
+        state32 = A.state_to_model_input(w["state"], self.quantiles["state"])
+        raw = {
+            R.EMB_NAME: {
+                "base_0_rgb": torch.as_tensor(w["base_0_rgb"])[None],
+                "left_wrist_0_rgb": torch.as_tensor(w["left_wrist_0_rgb"])[None],
+                "right_wrist_0_rgb": torch.as_tensor(w["right_wrist_0_rgb"])[None],
+                R.STATE_KEY: torch.as_tensor(state32, dtype=torch.float32)[None],
+                # Dummy action target (shape only): process_batch_for_training infers
+                # (B, horizon) from the action key; sample_actions ignores its values.
+                R.AC_KEY: torch.zeros(1, self.action_horizon, 32, dtype=torch.float32),
+                "annotations": [[self.instruction or ""]],
+                "episode_hash": ["__live__"],
+                "frame_idx": [0],
+                **ricl,
+            }
+        }
+        # The model is built in bfloat16; training ran under Lightning bf16-mixed
+        # autocast, so mirror that here (inputs are float32 -> autocast casts them).
+        dev_type = "cuda" if str(self.algo.device).startswith("cuda") else "cpu"
+        with torch.no_grad(), torch.autocast(dev_type, dtype=torch.bfloat16):
+            proc = self.algo.process_batch_for_training(raw)
+            preds = self.algo.forward_eval(proc)
+        pred = preds[f"{R.EMB_NAME}_{R.AC_KEY}"][0].detach().cpu().numpy()  # (H, 32)
+        return A.unnormalize_action(pred, self.quantiles["actions"], self.state_dim)
+
+    def reset_obsrvationwindows(self) -> None:
+        self.instruction = None
+        self.observation_window = None
diff --git a/egomimic/ricl/robotwin_setup.md b/egomimic/ricl/robotwin_setup.md
new file mode 100644
index 000000000..7dec5b025
--- /dev/null
+++ b/egomimic/ricl/robotwin_setup.md
@@ -0,0 +1,69 @@
+# RoboTwin PI-RICL — cluster runbook
+
+RoboTwin docs: https://robotwin-platform.github.io/doc/usage/robotwin-install.html
+
+**Fresh cluster from scratch?** See `robotwin_new_cluster_setup.md` (full install guide).
+This file is the per-run cheatsheet + current status.
+
+**Status: training + closed-loop eval both verified end-to-end.** Commands below target
+the Georgia Tech PACE cluster (repo at `/storage/project/r-dxu345-0/rco3/EgoVerse`).
+A 250-step checkpoint scored 1/10 on `beat_block_hammer`
+(undertrained — train longer for a real number; the pipeline is the deliverable).
+
+Setup once per cluster: `git submodule update --init external/RoboTwin`; vendor the
+PaliGemma tokenizer to `pg_tokenizer/` (gitignored) via
+`AutoTokenizer.from_pretrained("google/paligemma-3b-mix-224").save_pretrained(...)`
+(check the HF cache first). pi0.5 base ckpt: `egomimic/algo/pi_checkpoints/pi05_base_pytorch`.
+**Install packages with `uv pip install` — the venv has no `pip`.**
+
+## TODO 1 — data → zarr → train  (DONE)
+
+```bash
+source emimic/bin/activate
+python -m egomimic.ricl.scripts.download_robotwin --mode hf --out egomimic/ricl/outputs/robotwin_raw
+python -m egomimic.ricl.scripts.robotwin_to_zarr \
+  --root egomimic/ricl/outputs/robotwin_raw/extracted --out egomimic/ricl/outputs/robotwin_zarr --limit 5  # optional validation
+python egomimic/ricl/scripts/train_robotwin_ricl.py --stage cpu \
+  --root egomimic/ricl/outputs/robotwin_raw/extracted --embed fake          # CPU smoke
+sbatch egomimic/ricl/scripts/train_robotwin_ricl.sbatch                      # GPU training (gpu-h200, qos inferno)
+```
+The trainer reads the HDF5 corpus directly (`--root` = parent of the nested
+`<task>/data`). Writes checkpoints + `quantiles.json` under
+`outputs/robotwin_train/robotwin_ricl/version_*/`. The h200's ~141 GB fits full fp32
+AdamW of the 3.6 B model (~57 GB), so no 8-bit optimizer is needed.
+
+## TODO 2 — closed-loop eval on RoboTwin  (DONE)
+
+1. Build the demo-bank DINOv2 index (GPU):
+   ```bash
+   sbatch -p gpu-h200 -A gts-dxu345-rl2 -q inferno --gres=gpu:h200:1 -c8 --mem=64G --wrap=\
+     "emimic/bin/python egomimic/ricl/scripts/build_robotwin_bank_index.py \
+        --root egomimic/ricl/outputs/robotwin_raw/extracted \
+        --out egomimic/ricl/outputs/robotwin_bank_index --embed dinov2"
+   ```
+2. Sim deps — install **selectively** into `emimic` (NOT RoboTwin's `_install.sh`, which
+   pins `torch==2.4.1`): `uv pip install sapien==3.0.0b1 mplib==0.2.1 open3d trimesh
+   "pyglet<2"`. curobo/pytorch3d are NOT needed (see patches). Assets (~16GB):
+   `emimic/bin/python external/RoboTwin/assets/_download.py` then unzip
+   `{background_texture,embodiments,objects}.zip` into `assets/` and run
+   `external/RoboTwin/script/update_embodiment_config_path.py`.
+3. **Patches to the `external/RoboTwin` fork** (policy eval needs no motion planning, so
+   we skip curobo entirely):
+   - `envs/robot/planner.py`: in the `except` (curobo import failed), define a stub
+     `CuroboPlanner` (constructible; real `plan_grippers` interpolation; other methods
+     no-op) so the env imports + the robot builds a planner.
+   - `envs/robot/robot.py` `set_planner`: force `self.communication_flag = False` (use
+     the in-process stub, not curobo worker subprocesses).
+   - `script/eval_policy.py`: `expert_check = False` (skip the curobo expert solvability
+     run); guard the `episode_info`/`generate_episode_descriptions` block and fall back
+     to the task name as the instruction; honor `EVAL_TEST_NUM` to bound episodes.
+   - `task_config/demo_clean.yml`: `eval_video_log: false` (skip per-episode ffmpeg).
+   - `policy/pi_ricl_egoverse/deploy_policy.yml`: set absolute `egoverse_checkpoint`,
+     `bank_root`, `bank_index_dir`, `quantiles_path`.
+4. Run:
+   ```bash
+   CKPT=<abs .ckpt> EVAL_TEST_NUM=10 sbatch egomimic/ricl/scripts/eval_robotwin_ricl.sbatch
+   ```
+   SAPIEN renders headless ("Render Well"); eval runs eager (`TORCH_COMPILE_DISABLE=1`,
+   in the sbatch — pi0.5 `sample_actions` otherwise triggers a multi-minute compile).
+   Prints `Success rate: k/n` per episode.
diff --git a/egomimic/ricl/scripts/build_robotwin_bank_index.py b/egomimic/ricl/scripts/build_robotwin_bank_index.py
new file mode 100644
index 000000000..34d9b4242
--- /dev/null
+++ b/egomimic/ricl/scripts/build_robotwin_bank_index.py
@@ -0,0 +1,142 @@
+"""Build a consolidated DINOv2 kNN index over a RoboTwin HDF5 demo bank.
+
+The closed-loop eval (``egomimic.ricl.robotwin_policy.PIRiclPolicy``) retrieves
+online against a prebuilt index that it loads with
+``build_embedding_index.build_retrieval_index`` — i.e. a directory of
+``{vectors.npy, refs.npz, manifest.json}`` keyed by ``(episode_hash, frame_idx)``.
+The generic ``build_embedding_index.build_index`` consumes *zarr* DINOv2 mirror
+stores; RoboTwin's bank is HDF5 (``RoboTwinCorpus``), so this builds the same index
+format directly from the corpus.
+
+Critically it uses the SAME per-frame embedding the eval-time retriever uses:
+``make_dinov2_embedding_provider`` wraps ``retrieval.DinoV2Embedder().embed`` of the
+head view, and ``robotwin_adapter.OnlineRetriever`` embeds the live query with the
+same ``DinoV2Embedder().embed`` — so bank vectors and query vectors live in one
+space and kNN is meaningful. The refs carry ``RoboTwinCorpus`` episode hashes
+(``"{group}__{episode}"``) + frame indices, which ``OnlineRetriever`` feeds straight
+back into ``make_robotwin_bank_provider`` to fetch each neighbor's (image, state,
+action) block.
+
+Output dir (default ``<root>/_bank_index``):
+  - ``vectors.npy``   (N_frames, D) float32  — per-frame head-view descriptors
+  - ``refs.npz``      episode_hash (N,) <U, frame_idx (N,) int32
+  - ``manifest.json`` {source, embed, embed_dim, n_frames, n_episodes,
+                       episodes:[{hash, start, count}]}
+
+Example (GPU, real DINOv2 — matches eval):
+    python egomimic/ricl/scripts/build_robotwin_bank_index.py \\
+        --root egomimic/ricl/outputs/robotwin_raw/extracted \\
+        --out  egomimic/ricl/outputs/robotwin_bank_index --embed dinov2
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+from typing import Callable
+
+import numpy as np
+
+from egomimic.ricl import robotwin_data as R
+
+logger = logging.getLogger(__name__)
+
+
+def build_bank_index(
+    corpus: R.RoboTwinCorpus,
+    out_dir: str,
+    embeddings_provider: Callable[[str], np.ndarray],
+) -> str:
+    """Embed every bank frame and write a consolidated index under ``out_dir``.
+
+    ``embeddings_provider`` is a per-episode ``hash -> (T, D)`` callable (e.g.
+    ``make_dinov2_embedding_provider``); each row of the stacked matrix is one frame,
+    in ``corpus.hashes`` order, with parallel ``(episode_hash, frame_idx)`` refs.
+    """
+    os.makedirs(out_dir, exist_ok=True)
+    hashes = corpus.hashes
+    emb = {h: np.asarray(embeddings_provider(h), dtype=np.float32) for h in hashes}
+
+    lengths = [emb[h].shape[0] for h in hashes]
+    n_frames = int(sum(lengths))
+    embed_dim = int(emb[hashes[0]].shape[1])
+    logger.info(
+        "n_frames=%d embed_dim=%d over %d episodes", n_frames, embed_dim, len(hashes)
+    )
+
+    vectors = np.empty((n_frames, embed_dim), dtype=np.float32)
+    ref_hash = np.empty(n_frames, dtype=object)
+    ref_frame = np.empty(n_frames, dtype=np.int32)
+    episodes_meta: list[dict] = []
+
+    row = 0
+    for h in hashes:
+        v = emb[h]
+        t = v.shape[0]
+        if v.shape[1] != embed_dim:
+            raise RuntimeError(f"{h}: embed dim {v.shape[1]} != {embed_dim}")
+        vectors[row : row + t] = v
+        ref_hash[row : row + t] = h
+        ref_frame[row : row + t] = np.arange(t, dtype=np.int32)
+        episodes_meta.append({"hash": h, "start": row, "count": t})
+        row += t
+
+    np.save(os.path.join(out_dir, "vectors.npy"), vectors)
+    np.savez(
+        os.path.join(out_dir, "refs.npz"),
+        episode_hash=np.asarray(ref_hash).astype("U"),
+        frame_idx=ref_frame,
+    )
+    manifest = {
+        "source": "robotwin",
+        "embed_dim": embed_dim,
+        "n_frames": n_frames,
+        "n_episodes": len(hashes),
+        "episodes": episodes_meta,
+    }
+    with open(os.path.join(out_dir, "manifest.json"), "w") as f:
+        json.dump(manifest, f, indent=2)
+
+    logger.info(
+        "wrote bank index: %d frames x %d dims over %d episodes -> %s",
+        n_frames,
+        embed_dim,
+        len(hashes),
+        out_dir,
+    )
+    return out_dir
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument(
+        "--root", required=True, help="RoboTwin bank root (parent of <task>/data)"
+    )
+    p.add_argument(
+        "--out", default=None, help="output index dir (default <root>/_bank_index)"
+    )
+    p.add_argument(
+        "--embed",
+        choices=["dinov2", "fake"],
+        default="dinov2",
+        help="per-frame embedding source (dinov2 = real, matches eval; fake = stub)",
+    )
+    p.add_argument("--fake-embed-dim", type=int, default=256)
+    args = p.parse_args()
+
+    logging.basicConfig(
+        level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s"
+    )
+    corpus = R.RoboTwinCorpus(args.root)
+    if args.embed == "fake":
+        provider = R.make_fake_embedding_provider(corpus, dim=args.fake_embed_dim)
+    else:
+        provider = R.make_dinov2_embedding_provider(corpus)
+    out_dir = args.out or os.path.join(args.root, "_bank_index")
+    build_bank_index(corpus, out_dir, provider)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/egomimic/ricl/scripts/download_robotwin.py b/egomimic/ricl/scripts/download_robotwin.py
new file mode 100644
index 000000000..17499f540
--- /dev/null
+++ b/egomimic/ricl/scripts/download_robotwin.py
@@ -0,0 +1,284 @@
+"""Fetch a small RoboTwin 2.0 slice (or synthesize a fixture) for the RICL bring-up.
+
+RoboTwin 2.0 ships ~100k expert trajectories across 50 bimanual tasks on
+HuggingFace (``TianxingChen/RoboTwin2.0``). For the EgoVerse RICL integration we
+pull a slice — a few episodes (or a full task) — to (a) drive the HDF5->Zarr
+converter and (b) feed the in-memory shim + RICL collate. This module does two
+things:
+
+- ``download_robotwin_slice`` : download + unzip one per-(task, embodiment, setting)
+  archive from HF (``dataset/<task>/<embodiment>_<setting>_<N>.zip``). ``aloha-agilex``
+  is the bimanual embodiment; ``clean`` (50 demos, ~230 MB) is the smallest.
+- ``make_synthetic_robotwin_task`` : write a schema-faithful *synthetic* task dir
+  (no network) so the converter and unit tests always have valid input without
+  pulling a real archive.
+
+Raw RoboTwin episode layout this targets (verified against a real
+``aloha-agilex_clean_50`` archive + ``policy/pi05/scripts/process_data.py``)::
+
+    <task_dir>/data/episode{i}.hdf5
+        /joint_action/left_arm       (T, A)  float64   joint angles (A=6 for aloha-agilex)
+        /joint_action/left_gripper   (T,)    float64   aperture
+        /joint_action/right_arm      (T, A)  float64
+        /joint_action/right_gripper  (T,)    float64
+        /joint_action/vector         (T, 2A+2) float64 [l_arm, l_grip, r_arm, r_grip]
+        /observation/{head,left,right,front}_camera/rgb (T,) S{maxlen} JPEG bytes (240x320)
+        /endpose/left_endpose        (T, 7)  float64   [x,y,z,qw,qx,qy,qz] (SAPIEN p+q)
+        /endpose/left_gripper        (T,)    float64
+        /endpose/right_endpose       (T, 7)  float64
+        /endpose/right_gripper       (T,)    float64
+    <task_dir>/instructions/episode{i}.json  {"seen": [...], "unseen": [...]}
+
+``endpose`` is optional in real RoboTwin (only when ``data_type.endpose`` is set;
+the released aloha-agilex sets DO include it). The synthetic fixture defaults to
+6-DOF arms (14-D state, like aloha-agilex) and always includes ``endpose``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+
+import cv2
+import h5py
+import numpy as np
+
+HF_REPO_ID = "TianxingChen/RoboTwin2.0"
+HF_REPO_TYPE = "dataset"
+
+
+# --------------------------------------------------------------------------- #
+# Synthetic fixture (no network) — schema-faithful tiny RoboTwin task
+# --------------------------------------------------------------------------- #
+def _encode_jpeg_bytes(img_rgb: np.ndarray) -> bytes:
+    """JPEG-encode an HWC RGB uint8 frame to bytes (cv2, RoboTwin-style).
+
+    cv2.imencode/imdecode round-trips the array byte-for-byte regardless of
+    channel-order interpretation, so a frame stored here decodes back identically
+    (see module note in ``robotwin_data.image``)."""
+    ok, buf = cv2.imencode(".jpg", img_rgb)
+    if not ok:
+        raise RuntimeError("cv2.imencode failed")
+    return buf.tobytes()
+
+
+def _store_jpeg_dataset(group: h5py.Group, name: str, frames_rgb: np.ndarray) -> None:
+    """Store (T,H,W,3) RGB frames as a fixed-length ``S{maxlen}`` JPEG byte dataset
+    (matching RoboTwin's ``observation/<cam>/rgb`` layout)."""
+    encoded = [_encode_jpeg_bytes(f) for f in frames_rgb]
+    maxlen = max(len(b) for b in encoded)
+    padded = [b.ljust(maxlen, b"\0") for b in encoded]
+    group.create_dataset(name, data=np.array(padded), dtype=f"S{maxlen}")
+
+
+def _random_unit_quats(n: int, rng: np.random.Generator) -> np.ndarray:
+    """n random unit quaternions in (w, x, y, z) order (SAPIEN convention)."""
+    q = rng.standard_normal((n, 4)).astype(np.float32)
+    q /= np.linalg.norm(q, axis=1, keepdims=True)
+    q[q[:, 0] < 0] *= -1.0  # canonical hemisphere (w >= 0)
+    return q
+
+
+def make_synthetic_robotwin_episode(
+    hdf5_path: str,
+    *,
+    n_frames: int = 60,
+    img_hw: tuple[int, int] = (56, 56),
+    arm_dof: int = 6,
+    with_endpose: bool = True,
+    seed: int = 0,
+) -> None:
+    """Write one schema-faithful synthetic RoboTwin ``episode{i}.hdf5``.
+
+    ``arm_dof`` defaults to 6 (the real aloha-agilex bimanual embodiment -> 14-D
+    state, grippers at slots 6/13)."""
+    rng = np.random.default_rng(seed)
+    H, W = img_hw
+    T = n_frames
+
+    # Smooth-ish joint trajectories so action=next-state chunks are non-trivial.
+    t = np.linspace(0.0, 1.0, T, dtype=np.float32)[:, None]
+    left_arm = (0.3 * np.sin(2 * np.pi * (t + rng.random((1, arm_dof))))).astype(
+        np.float32
+    )
+    right_arm = (0.3 * np.cos(2 * np.pi * (t + rng.random((1, arm_dof))))).astype(
+        np.float32
+    )
+    left_grip = (0.5 + 0.5 * np.sin(2 * np.pi * t[:, 0])).astype(np.float32)
+    right_grip = (0.5 + 0.5 * np.cos(2 * np.pi * t[:, 0])).astype(np.float32)
+    vector = np.concatenate(
+        [left_arm, left_grip[:, None], right_arm, right_grip[:, None]], axis=1
+    ).astype(np.float32)  # (T, 2*arm_dof + 2)
+
+    # Distinct per-frame imagery so DINOv2 / fake embeddings differ across frames.
+    frames = rng.integers(0, 256, size=(T, H, W, 3), dtype=np.uint8)
+
+    os.makedirs(os.path.dirname(hdf5_path), exist_ok=True)
+    with h5py.File(hdf5_path, "w") as f:
+        ja = f.create_group("joint_action")
+        ja.create_dataset("left_arm", data=left_arm)
+        ja.create_dataset("left_gripper", data=left_grip)
+        ja.create_dataset("right_arm", data=right_arm)
+        ja.create_dataset("right_gripper", data=right_grip)
+        ja.create_dataset("vector", data=vector)
+
+        obs = f.create_group("observation")
+        for cam in ("head_camera", "left_camera", "right_camera"):
+            cam_grp = obs.create_group(cam)
+            _store_jpeg_dataset(cam_grp, "rgb", frames)
+
+        if with_endpose:
+            ep = f.create_group("endpose")
+            lpos = (0.1 * rng.standard_normal((T, 3))).astype(np.float32)
+            rpos = (0.1 * rng.standard_normal((T, 3))).astype(np.float32)
+            lq = _random_unit_quats(T, rng)
+            rq = _random_unit_quats(T, rng)
+            ep.create_dataset("left_endpose", data=np.concatenate([lpos, lq], axis=1))
+            ep.create_dataset("left_gripper", data=left_grip)
+            ep.create_dataset("right_endpose", data=np.concatenate([rpos, rq], axis=1))
+            ep.create_dataset("right_gripper", data=right_grip)
+
+
+def make_synthetic_robotwin_task(
+    root: str,
+    task: str = "pick_cube",
+    *,
+    n_episodes: int = 4,
+    n_frames: int = 60,
+    img_hw: tuple[int, int] = (56, 56),
+    arm_dof: int = 6,
+    with_endpose: bool = True,
+    seed: int = 0,
+) -> str:
+    """Create ``<root>/<task>/{data,instructions}`` with ``n_episodes`` synthetic
+    episodes. Returns the task dir (a single RICL "group")."""
+    task_dir = os.path.join(root, task)
+    data_dir = os.path.join(task_dir, "data")
+    instr_dir = os.path.join(task_dir, "instructions")
+    os.makedirs(data_dir, exist_ok=True)
+    os.makedirs(instr_dir, exist_ok=True)
+    instr = {
+        "seen": [f"perform the {task.replace('_', ' ')} task"],
+        "unseen": [f"complete the {task.replace('_', ' ')} demonstration"],
+    }
+    for i in range(n_episodes):
+        make_synthetic_robotwin_episode(
+            os.path.join(data_dir, f"episode{i}.hdf5"),
+            n_frames=n_frames,
+            img_hw=img_hw,
+            arm_dof=arm_dof,
+            with_endpose=with_endpose,
+            seed=seed + i,
+        )
+        with open(os.path.join(instr_dir, f"episode{i}.json"), "w") as fp:
+            json.dump(instr, fp, indent=2)
+    return task_dir
+
+
+# --------------------------------------------------------------------------- #
+# HuggingFace task-archive download (download + unzip)
+# --------------------------------------------------------------------------- #
+def download_robotwin_slice(
+    out_dir: str,
+    task: str = "beat_block_hammer",
+    embodiment: str = "aloha-agilex",
+    setting: str = "clean",
+    extract: bool = True,
+) -> str:
+    """Download + unzip one RoboTwin task archive from HuggingFace.
+
+    RoboTwin 2.0 ships raw demos as per-(task, embodiment, setting) zip archives at
+    ``dataset/<task>/<embodiment>_<setting>_<N>.zip`` (e.g.
+    ``dataset/beat_block_hammer/aloha-agilex_clean_50.zip``). ``aloha-agilex`` is the
+    **bimanual** embodiment; ``clean`` is the smallest set (50 demos). The archive
+    expands to the raw ``data/episode*.hdf5`` + ``instructions/`` layout the shim and
+    converter consume.
+
+    Returns the extraction dir (point ``--root`` at it; groups are discovered
+    within). Raises with a clear message if the archive can't be found/listed so
+    callers can fall back to ``make_synthetic_robotwin_task``. NOTE: even the
+    smallest archive is ~230 MB.
+    """
+    import zipfile
+
+    from huggingface_hub import HfApi, hf_hub_download
+
+    api = HfApi()
+    files = api.list_repo_files(HF_REPO_ID, repo_type=HF_REPO_TYPE)
+    prefix = f"dataset/{task}/{embodiment}_{setting}_"
+    cands = sorted(f for f in files if f.startswith(prefix) and f.endswith(".zip"))
+    if not cands:
+        tasks = sorted(
+            {
+                f.split("/")[1]
+                for f in files
+                if f.startswith("dataset/") and f.count("/") >= 2
+            }
+        )
+        raise ValueError(
+            f"no archive {prefix}*.zip in {HF_REPO_ID}; available tasks e.g. "
+            f"{tasks[:8]} (embodiment: aloha-agilex/arx-x5/franka/piper/ur5; "
+            f"setting: clean/randomized)"
+        )
+
+    def _n_demos(f: str) -> int:
+        try:
+            return int(f.rsplit("_", 1)[1].split(".")[0])
+        except Exception:
+            return 1 << 30
+
+    zip_repo_path = min(cands, key=_n_demos)  # smallest set (clean_50 before _500)
+    print(f"[download] {HF_REPO_ID}: {zip_repo_path}", flush=True)
+    local_zip = hf_hub_download(
+        HF_REPO_ID, zip_repo_path, repo_type=HF_REPO_TYPE, local_dir=out_dir
+    )
+    if not extract:
+        return local_zip
+    extract_dir = os.path.join(out_dir, "extracted", f"{task}__{embodiment}_{setting}")
+    os.makedirs(extract_dir, exist_ok=True)
+    with zipfile.ZipFile(local_zip) as z:
+        z.extractall(extract_dir)
+    print(f"[download] extracted -> {extract_dir}", flush=True)
+    return extract_dir
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument(
+        "--mode",
+        choices=["synthetic", "hf"],
+        default="synthetic",
+        help="synthetic: write a tiny local fixture (no network); "
+        "hf: download a real slice from HuggingFace",
+    )
+    p.add_argument("--out", required=True, help="output root dir")
+    p.add_argument("--task", default=None, help="RoboTwin task name")
+    p.add_argument(
+        "--embodiment", default="aloha-agilex", help="hf mode: bimanual=aloha-agilex"
+    )
+    p.add_argument("--setting", default="clean", help="hf mode: clean | randomized")
+    p.add_argument("--episodes", type=int, default=4, help="synthetic: episodes")
+    p.add_argument("--frames", type=int, default=60, help="frames/episode (synthetic)")
+    args = p.parse_args()
+
+    if args.mode == "synthetic":
+        task_dir = make_synthetic_robotwin_task(
+            args.out,
+            task=args.task or "pick_cube",
+            n_episodes=args.episodes,
+            n_frames=args.frames,
+        )
+        print(f"wrote synthetic task -> {task_dir}", flush=True)
+    else:
+        task_dir = download_robotwin_slice(
+            args.out,
+            task=args.task or "beat_block_hammer",
+            embodiment=args.embodiment,
+            setting=args.setting,
+        )
+        print(f"downloaded slice -> {task_dir}", flush=True)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/egomimic/ricl/scripts/eval_multitask_compare.sbatch b/egomimic/ricl/scripts/eval_multitask_compare.sbatch
new file mode 100644
index 000000000..f0ae2c076
--- /dev/null
+++ b/egomimic/ricl/scripts/eval_multitask_compare.sbatch
@@ -0,0 +1,69 @@
+#!/bin/bash
+#SBATCH --job-name=rtw_mt_eval
+#SBATCH --nodes=1
+#SBATCH --ntasks=1
+#SBATCH --cpus-per-task=4
+#SBATCH --mem=64G
+# Eval is inference-only: pi0.5 weights (~14.5GB fp32) fit a 48GB l40s with room for
+# DINOv2 + SAPIEN, and gpu-l40s schedules far faster than the contended gpu-h200.
+# (Override to gpu-h200/gpu-a100 via sbatch -p/--gres if l40s is drained.)
+#SBATCH --partition=gpu-l40s
+#SBATCH --account=gts-dxu345-rl2
+#SBATCH --qos=inferno
+#SBATCH --gres=gpu:l40s:1
+#SBATCH --time=08:00:00
+#SBATCH --output=egomimic/ricl/outputs/robotwin_eval/mt_compare_%j.out
+#SBATCH --error=egomimic/ricl/outputs/robotwin_eval/mt_compare_%j.err
+
+# Closed-loop RICL-vs-plain comparison on HELD-OUT RoboTwin tasks.
+# For each held-out task: build its DINOv2 bank index, then eval the RICL model
+# (within-task retrieval ON) and the plain model (retrieval OFF). The RICL model
+# never trained on these tasks — it only gets k=4 in-context demos at eval.
+# Queue after training: sbatch --dependency=afterany:<ricl_jid>:<plain_jid> ...
+set -uo pipefail
+REPO=/storage/project/r-dxu345-0/rco3/EgoVerse2
+cd "$REPO"
+mkdir -p egomimic/ricl/outputs/robotwin_eval
+source emimic/bin/activate
+export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
+export TORCH_COMPILE_DISABLE=1
+export PYTHONWARNINGS=ignore::UserWarning
+export DISPLAY=""
+export EVAL_TEST_NUM="${EVAL_TEST_NUM:-10}"
+# demo_clean (default) or demo_randomized (cluttered table, random bg/light/table-height).
+export TASK_CONFIG="${TASK_CONFIG:-demo_clean}"
+
+MT="$REPO/egomimic/ricl/outputs/robotwin_mt"
+TRAIN="$REPO/egomimic/ricl/outputs/robotwin_train"
+IDXBASE="$REPO/egomimic/ricl/outputs/robotwin_mt_eval_index"
+RICL_CKPT=$(ls -t "$TRAIN"/robotwin_mt_ricl/version_0/checkpoints/*.ckpt | head -1)
+RICL_Q="$TRAIN/robotwin_mt_ricl/version_0/quantiles.json"
+PLAIN_CKPT=$(ls -t "$TRAIN"/robotwin_mt_plain/version_0/checkpoints/*.ckpt | head -1)
+PLAIN_Q="$TRAIN/robotwin_mt_plain/version_0/quantiles.json"
+TASKS="${TASKS:-click_alarmclock open_microwave}"
+
+echo "host=$(hostname) gpu=${CUDA_VISIBLE_DEVICES:-?} N=$EVAL_TEST_NUM task_config=$TASK_CONFIG"
+echo "RICL_CKPT=$RICL_CKPT"
+echo "PLAIN_CKPT=$PLAIN_CKPT"
+nvidia-smi --query-gpu=name,memory.total --format=csv,noheader || true
+
+run_eval () {  # name task ckpt quant bank idx noic
+  echo "##### EVAL model=$1 task=$2 no_incontext=$7 #####"
+  ( cd "$REPO/external/RoboTwin" && python -u script/eval_policy.py \
+      --config policy/pi_ricl_egoverse/deploy_policy.yml --overrides \
+      --task_name "$2" --task_config "$TASK_CONFIG" --policy_name pi_ricl_egoverse \
+      --egoverse_checkpoint "$3" --quantiles_path "$4" \
+      --bank_root "$5" --bank_index_dir "$6" --no_incontext "$7" \
+      --model_name "$1" --ckpt_setting "$1" --seed 0 ) || echo "[$1/$2] EVAL FAILED"
+}
+
+for T in $TASKS; do
+  BANK="$MT/eval/$T"
+  IDX="$IDXBASE/$T"
+  echo "=== build bank index: $T ==="
+  python egomimic/ricl/scripts/build_robotwin_bank_index.py --root "$BANK" --out "$IDX" --embed dinov2 \
+    || { echo "index build FAILED for $T"; continue; }
+  run_eval ricl  "$T" "$RICL_CKPT"  "$RICL_Q"  "$BANK" "$IDX" false
+  run_eval plain "$T" "$PLAIN_CKPT" "$PLAIN_Q" "$BANK" "$IDX" true
+done
+echo "=== mt eval compare DONE ==="
diff --git a/egomimic/ricl/scripts/eval_robotwin_ricl.sbatch b/egomimic/ricl/scripts/eval_robotwin_ricl.sbatch
new file mode 100644
index 000000000..7317d4447
--- /dev/null
+++ b/egomimic/ricl/scripts/eval_robotwin_ricl.sbatch
@@ -0,0 +1,53 @@
+#!/bin/bash
+#SBATCH --job-name=robotwin_eval
+#SBATCH --nodes=1
+#SBATCH --ntasks=1
+#SBATCH --cpus-per-task=4
+#SBATCH --mem=64G
+# Eval is inference-only — a 48GB l40s loads pi0.5 fine and schedules faster than h200.
+#SBATCH --partition=gpu-l40s
+#SBATCH --account=gts-dxu345-rl2
+#SBATCH --gres=gpu:l40s:1
+#SBATCH --qos=inferno
+#SBATCH --time=01:00:00
+#SBATCH --output=egomimic/ricl/outputs/robotwin_eval/slurm_%j.out
+#SBATCH --error=egomimic/ricl/outputs/robotwin_eval/slurm_%j.err
+
+# Closed-loop eval of the EgoVerse pi0.5 RICL checkpoint on a RoboTwin task.
+# Replicates policy/pi_ricl_egoverse/eval.sh but uses the (uv-managed) emimic venv
+# and the correct cwd. Bank/quantiles/checkpoint paths come from deploy_policy.yml.
+#   TASK / TASK_CONFIG / CKPT / SEED overridable via env vars.
+set -uo pipefail
+mkdir -p egomimic/ricl/outputs/robotwin_eval
+cd /storage/project/r-dxu345-0/rco3/EgoVerse2
+source emimic/bin/activate
+
+TASK="${TASK:-beat_block_hammer}"
+TASK_CONFIG="${TASK_CONFIG:-demo_clean}"
+CKPT="${CKPT:-egomimic/ricl/outputs/robotwin_train/robotwin_ricl/version_2/checkpoints/last.ckpt}"
+CKPT_ABS="$(readlink -f "$CKPT")"
+SEED="${SEED:-0}"
+
+echo "host=$(hostname) gpu=${CUDA_VISIBLE_DEVICES:-?} ckpt=$CKPT_ABS"
+nvidia-smi --query-gpu=name,memory.total --format=csv,noheader || true
+
+# SAPIEN headless offscreen rendering on the compute node
+export DISPLAY=""
+export PYTHONWARNINGS=ignore::UserWarning
+# Eval-only: run eager (pi0.5 sample_actions triggers a multi-minute torch.compile
+# max-autotune otherwise). Bound the episode count for a fast eval (default 100).
+export TORCH_COMPILE_DISABLE=1
+export EVAL_TEST_NUM="${EVAL_TEST_NUM:-10}"
+
+cd external/RoboTwin
+python -u script/eval_policy.py --config policy/pi_ricl_egoverse/deploy_policy.yml \
+  --overrides \
+  --task_name "${TASK}" \
+  --task_config "${TASK_CONFIG}" \
+  --egoverse_checkpoint "${CKPT_ABS}" \
+  --model_name eva_bimanual \
+  --ckpt_setting eva_bimanual \
+  --seed "${SEED}" \
+  --policy_name pi_ricl_egoverse
+
+echo "=== eval exit: $? ==="
diff --git a/egomimic/ricl/scripts/eval_xemb_compare.sbatch b/egomimic/ricl/scripts/eval_xemb_compare.sbatch
new file mode 100644
index 000000000..80d18ebd9
--- /dev/null
+++ b/egomimic/ricl/scripts/eval_xemb_compare.sbatch
@@ -0,0 +1,92 @@
+#!/bin/bash
+#SBATCH --job-name=rtw_xemb_eval
+#SBATCH --nodes=1
+#SBATCH --ntasks=1
+#SBATCH --cpus-per-task=4
+#SBATCH --mem=64G
+# Inference-only: pi0.5 weights (~14.5GB fp32) + DINOv2 + SAPIEN fit a 48GB l40s,
+# which schedules far faster than the contended gpu-h200.
+#SBATCH --partition=gpu-l40s
+#SBATCH --account=gts-dxu345-rl2
+#SBATCH --qos=inferno
+#SBATCH --gres=gpu:l40s:1
+#SBATCH --time=06:00:00
+#SBATCH --output=egomimic/ricl/outputs/robotwin_eval/xemb_compare_%j.out
+#SBATCH --error=egomimic/ricl/outputs/robotwin_eval/xemb_compare_%j.err
+
+# CLOSED-LOOP CROSS-EMBODIMENT comparison on HELD-OUT RoboTwin tasks.
+# The SAPIEN sim controls embodiment B = aloha-agilex (the predicted embodiment,
+# demo_clean default). For each held-out task we run three policies and compare
+# closed-loop success:
+#   xemb  : cross-embodiment RICL — predict aloha, retrieve ARX-X5 demos (emb A).
+#   same  : same-embodiment RICL  — predict aloha, retrieve aloha demos (upper bound).
+#   plain : no in-context demos    — plain aloha pi0.5 finetune (floor).
+# Only the retrieval bank differs across xemb/same; the controlled robot is always
+# aloha. xemb normalizes retrieved demos with the ARX-X5 bank quantiles
+# (bank_quantiles_path) — exactly as in cross-embodiment training.
+set -uo pipefail
+REPO=/storage/project/r-dxu345-0/rco3/EgoVerse2
+cd "$REPO"
+mkdir -p egomimic/ricl/outputs/robotwin_eval
+source emimic/bin/activate
+export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
+export TORCH_COMPILE_DISABLE=1
+export PYTHONWARNINGS=ignore::UserWarning
+export DISPLAY=""
+export EVAL_TEST_NUM="${EVAL_TEST_NUM:-10}"
+# demo_clean (default) or demo_randomized (domain randomization: cluttered table,
+# random background/light/table-height — breaks the clean-task success ceiling).
+export TASK_CONFIG="${TASK_CONFIG:-demo_clean}"
+
+TRAIN="$REPO/egomimic/ricl/outputs/robotwin_train"
+# Cross-embodiment RICL run (predict aloha / retrieve arx-x5).
+XEMB_DIR="$TRAIN/robotwin_xemb_ricl/version_0"
+XEMB_CKPT=$(ls -t "$XEMB_DIR"/checkpoints/*.ckpt | head -1)
+XEMB_Q="$XEMB_DIR/quantiles.json"             # aloha (query/action) quantiles
+XEMB_BANK_Q="$XEMB_DIR/bank_quantiles.json"   # arx-x5 (retrieved demo) quantiles
+# Existing same-embodiment baselines (predict aloha).
+SAME_CKPT=$(ls -t "$TRAIN"/robotwin_mt_ricl/version_0/checkpoints/*.ckpt | head -1)
+SAME_Q="$TRAIN/robotwin_mt_ricl/version_0/quantiles.json"
+PLAIN_CKPT=$(ls -t "$TRAIN"/robotwin_mt_plain/version_0/checkpoints/*.ckpt | head -1)
+PLAIN_Q="$TRAIN/robotwin_mt_plain/version_0/quantiles.json"
+
+# Held-out eval tasks that have BOTH an aloha and an arx-x5 bank (and run in sim).
+TASKS="${TASKS:-click_alarmclock open_microwave turn_switch}"
+ALOHA_BANK="$REPO/egomimic/ricl/outputs/robotwin_mt/eval"          # emb B banks (same-emb)
+ARX_BANK="$REPO/egomimic/ricl/outputs/robotwin_xemb_bank/eval"     # emb A banks (cross-emb)
+IDXBASE="$REPO/egomimic/ricl/outputs/robotwin_xemb_eval_index"
+
+echo "host=$(hostname) gpu=${CUDA_VISIBLE_DEVICES:-?} N=$EVAL_TEST_NUM task_config=$TASK_CONFIG"
+echo "XEMB_CKPT=$XEMB_CKPT"
+echo "SAME_CKPT=$SAME_CKPT"
+echo "PLAIN_CKPT=$PLAIN_CKPT"
+nvidia-smi --query-gpu=name,memory.total --format=csv,noheader || true
+
+run_eval () {  # name task ckpt quant bank idx noic bankquant
+  echo "##### EVAL model=$1 task=$2 no_incontext=$7 bank=$5 #####"
+  local extra=""
+  [ -n "${8:-}" ] && extra="--bank_quantiles_path $8"
+  ( cd "$REPO/external/RoboTwin" && python -u script/eval_policy.py \
+      --config policy/pi_ricl_egoverse/deploy_policy.yml --overrides \
+      --task_name "$2" --task_config "$TASK_CONFIG" --policy_name pi_ricl_egoverse \
+      --egoverse_checkpoint "$3" --quantiles_path "$4" \
+      --bank_root "$5" --bank_index_dir "$6" --no_incontext "$7" $extra \
+      --model_name "$1" --ckpt_setting "$1" --seed 0 ) || echo "[$1/$2] EVAL FAILED"
+}
+
+for T in $TASKS; do
+  ARX_IDX="$IDXBASE/arx/$T"; ALOHA_IDX="$IDXBASE/aloha/$T"
+  echo "=== build ARX-X5 bank index: $T ==="
+  python egomimic/ricl/scripts/build_robotwin_bank_index.py --root "$ARX_BANK/$T" --out "$ARX_IDX" --embed dinov2 \
+    || { echo "arx index build FAILED for $T"; continue; }
+  echo "=== build aloha bank index: $T ==="
+  python egomimic/ricl/scripts/build_robotwin_bank_index.py --root "$ALOHA_BANK/$T" --out "$ALOHA_IDX" --embed dinov2 \
+    || { echo "aloha index build FAILED for $T"; continue; }
+  # cross-embodiment RICL: aloha query/action quantiles + arx-x5 bank quantiles.
+  run_eval xemb  "$T" "$XEMB_CKPT"  "$XEMB_Q"  "$ARX_BANK/$T"   "$ARX_IDX"   false "$XEMB_BANK_Q"
+  # same-embodiment RICL upper bound: aloha bank.
+  run_eval same  "$T" "$SAME_CKPT"  "$SAME_Q"  "$ALOHA_BANK/$T" "$ALOHA_IDX" false
+  # plain floor: no retrieval (bank passed only for state_dim detection).
+  run_eval plain "$T" "$PLAIN_CKPT" "$PLAIN_Q" "$ALOHA_BANK/$T" "$ALOHA_IDX" true
+done
+echo "=== xemb eval compare DONE ==="
diff --git a/egomimic/ricl/scripts/robotwin_to_zarr.py b/egomimic/ricl/scripts/robotwin_to_zarr.py
new file mode 100644
index 000000000..6b5c40cc1
--- /dev/null
+++ b/egomimic/ricl/scripts/robotwin_to_zarr.py
@@ -0,0 +1,213 @@
+"""Convert RoboTwin 2.0 episodes to EgoVerse Zarr (the reusable-corpus path).
+
+Companion to the in-memory shim (``egomimic/ricl/robotwin_data.py``): where the
+shim feeds RoboTwin straight into RICL training, this converter writes RoboTwin
+demos as first-class EgoVerse Zarr stores via the supported ``ZarrWriter`` so they
+can flow through the standard ``MultiDataset`` pipeline and cotrain alongside the
+eva/human corpus later.
+
+It labels episodes as ``eva_bimanual`` (no new embodiment registration) and emits
+exactly the zarr keys ``Eva._get_keymap("cartesian_pi")`` reads, in the
+**cartesian end-effector** representation:
+
+    images.front_1 / images.left_wrist / images.right_wrist  (JPEG)
+    left.obs_ee_pose  / right.obs_ee_pose   (T, 7)  XYZWXYZ  [x,y,z,qw,qx,qy,qz]
+    left.cmd_ee_pose  / right.cmd_ee_pose   (T, 7)  == obs pose (chunked at load)
+    left.obs_gripper  / right.obs_gripper   (T, 1)
+    left.cmd_gripper  / right.cmd_gripper   (T, 1)
+
+RoboTwin's ``endpose`` is the SAPIEN ``pose.p + pose.q`` = ``[x,y,z,qw,qx,qy,qz]``,
+which is already EgoVerse's XYZWXYZ order (no quaternion reordering). ``cmd_*`` is
+set equal to ``obs_*`` — the same "observed pose IS the action target, chunked at
+load time" convention the aria human keymap uses — so the action chunk is the
+future end-effector trajectory.
+
+Requires the ``endpose`` group: the cartesian path needs end-effector poses. If an
+episode only has ``joint_action`` (no ``endpose``), conversion raises with a clear
+message (FK joints->ee, or a joint-space Zarr embodiment, are follow-ups — the
+joint-space shim path is unaffected).
+
+NOTE: Eva's ``cartesian`` transform re-expresses poses relative to *EVA's* fixed
+camera extrinsics, which is not RoboTwin's true camera geometry; obs and cmd are
+transformed by the same rigid extrinsic so relative motion is preserved, which is
+sufficient for the shim-first plan. (A dedicated RoboTwin extrinsic/embodiment is a
+later refinement if these Zarrs are used for serious cotraining.)
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import os
+
+import cv2
+import h5py
+import numpy as np
+
+from egomimic.rldb.zarr.zarr_writer import ZarrWriter
+
+EMBODIMENT = "eva_bimanual"
+_CAM_TO_ZARR = {
+    "head_camera": "images.front_1",
+    "left_camera": "images.left_wrist",
+    "right_camera": "images.right_wrist",
+}
+
+
+def _decode_cam(group: h5py.Group, cam: str, image_hw: tuple[int, int]) -> np.ndarray:
+    """Decode a RoboTwin ``observation/<cam>/rgb`` JPEG dataset -> (T,H,W,3) RGB."""
+    raw = group[f"{cam}/rgb"][()]
+    H, W = image_hw
+    out = np.empty((len(raw), H, W, 3), dtype=np.uint8)
+    for i, b in enumerate(raw):
+        img = cv2.imdecode(np.frombuffer(bytes(b), np.uint8), cv2.IMREAD_COLOR)
+        if img is None:
+            raise ValueError(f"failed to decode {cam} frame {i}")
+        if tuple(img.shape[:2]) != (H, W):
+            img = cv2.resize(img, (W, H))
+        out[i] = img  # cv2 round-trips channel order -> renderer RGB preserved
+    return out
+
+
+def _read_instruction(task_dir: str, episode_name: str) -> str:
+    path = os.path.join(task_dir, "instructions", f"{episode_name}.json")
+    try:
+        with open(path) as f:
+            instr = json.load(f)
+        seen = instr.get("seen") or instr.get("unseen") or []
+        if seen:
+            return str(seen[0])
+    except FileNotFoundError:
+        pass
+    return ""
+
+
+def convert_episode(
+    hdf5_path: str,
+    out_zarr: str,
+    *,
+    task_name: str,
+    task_description: str = "",
+    image_hw: tuple[int, int] = (224, 224),
+    fps: int = 25,
+) -> str:
+    """Convert one RoboTwin ``episode*.hdf5`` to an EgoVerse Zarr store."""
+    with h5py.File(hdf5_path, "r") as f:
+        if "endpose" not in f:
+            raise ValueError(
+                f"{hdf5_path}: no 'endpose' group — the cartesian Zarr path needs "
+                "end-effector poses. Re-collect RoboTwin with data_type.endpose=True, "
+                "add FK (joints->ee), or use the joint-space shim (robotwin_data.py)."
+            )
+        ep = f["endpose"]
+        left_pose = np.asarray(ep["left_endpose"][()], dtype=np.float64)  # (T,7)
+        right_pose = np.asarray(ep["right_endpose"][()], dtype=np.float64)
+        left_grip = np.asarray(ep["left_gripper"][()], dtype=np.float32).reshape(-1, 1)
+        right_grip = np.asarray(ep["right_gripper"][()], dtype=np.float32).reshape(
+            -1, 1
+        )
+        obs = f["observation"]
+        images = {
+            zarr_key: _decode_cam(obs, cam, image_hw)
+            for cam, zarr_key in _CAM_TO_ZARR.items()
+            if cam in obs
+        }
+
+    T = left_pose.shape[0]
+    if not (right_pose.shape[0] == T == left_grip.shape[0] == right_grip.shape[0]):
+        raise ValueError(f"{hdf5_path}: inconsistent frame counts")
+    for k, v in images.items():
+        if len(v) != T:
+            raise ValueError(f"{hdf5_path}: {k} has {len(v)} frames, expected {T}")
+
+    numeric = {
+        # observed pose == commanded pose target; cmd is chunked into the future
+        # trajectory at load time via the keymap horizon (the aria "obs as action").
+        "left.obs_ee_pose": left_pose,
+        "right.obs_ee_pose": right_pose,
+        "left.cmd_ee_pose": left_pose.copy(),
+        "right.cmd_ee_pose": right_pose.copy(),
+        "left.obs_gripper": left_grip,
+        "right.obs_gripper": right_grip,
+        "left.cmd_gripper": left_grip.copy(),
+        "right.cmd_gripper": right_grip.copy(),
+    }
+    annotations = [(task_description, 0, T)] if task_description else None
+
+    writer = ZarrWriter(
+        episode_path=out_zarr,
+        embodiment=EMBODIMENT,
+        fps=fps,
+        task_name=task_name,
+        task_description=task_description,
+        annotations=annotations,
+    )
+    writer.write(numeric_data=numeric, image_data=images)
+    return out_zarr
+
+
+def convert_task(
+    root: str,
+    out_dir: str,
+    *,
+    image_hw: tuple[int, int] = (224, 224),
+    fps: int = 25,
+    limit: int | None = None,
+) -> list[str]:
+    """Convert every ``<task>/data/episode*.hdf5`` under ``root`` to Zarr stores in
+    ``out_dir``, named ``<group>__<episode>.zarr``. Returns the written paths."""
+    os.makedirs(out_dir, exist_ok=True)
+    written: list[str] = []
+    data_dirs = sorted(glob.glob(os.path.join(root, "**", "data"), recursive=True))
+    for data_dir in data_dirs:
+        eps = sorted(glob.glob(os.path.join(data_dir, "episode*.hdf5")))
+        if not eps:
+            continue
+        task_dir = os.path.dirname(data_dir)
+        rel = os.path.relpath(task_dir, root)
+        gid = "root" if rel == "." else rel.replace(os.sep, "__")
+        for ep in eps:
+            ep_name = os.path.splitext(os.path.basename(ep))[0]
+            desc = _read_instruction(task_dir, ep_name)
+            out_zarr = os.path.join(out_dir, f"{gid}__{ep_name}.zarr")
+            convert_episode(
+                ep,
+                out_zarr,
+                task_name=gid,
+                task_description=desc,
+                image_hw=image_hw,
+                fps=fps,
+            )
+            written.append(out_zarr)
+            print(f"[zarr] {ep} -> {out_zarr}", flush=True)
+            if limit is not None and len(written) >= limit:
+                return written
+    if not written:
+        raise FileNotFoundError(f"no <task>/data/episode*.hdf5 found under {root!r}")
+    return written
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument(
+        "--root", required=True, help="RoboTwin task root (parent of <task>/data)"
+    )
+    p.add_argument("--out", required=True, help="output dir for .zarr stores")
+    p.add_argument("--limit", type=int, default=None, help="max episodes to convert")
+    p.add_argument("--height", type=int, default=224)
+    p.add_argument("--width", type=int, default=224)
+    p.add_argument("--fps", type=int, default=25)
+    args = p.parse_args()
+    written = convert_task(
+        args.root,
+        args.out,
+        image_hw=(args.height, args.width),
+        fps=args.fps,
+        limit=args.limit,
+    )
+    print(f"wrote {len(written)} zarr stores -> {args.out}", flush=True)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/egomimic/ricl/scripts/setup_multitask_robotwin.py b/egomimic/ricl/scripts/setup_multitask_robotwin.py
new file mode 100644
index 000000000..4d6cd4e8d
--- /dev/null
+++ b/egomimic/ricl/scripts/setup_multitask_robotwin.py
@@ -0,0 +1,101 @@
+"""Download + arrange a DROID-style multi-task RoboTwin split for PI RICL.
+
+Downloads aloha-agilex slices for the given train/eval tasks and symlinks N demos
+per task into ``train_root/`` and ``eval_root/`` with the ``<task>/{data,instructions}``
+layout ``RoboTwinCorpus`` expects (one group per task). Train and eval task sets are
+DISJOINT, so eval-task demos are never seen during training — at eval they're used
+only as test-time in-context retrieval examples (within-group leave-one-out).
+
+Example:
+    python egomimic/ricl/scripts/setup_multitask_robotwin.py \\
+      --train-tasks beat_block_hammer,lift_pot,... --eval-tasks click_alarmclock,... \\
+      --n-demos 20 --setting clean \\
+      --raw-dir egomimic/ricl/outputs/robotwin_raw_mt \\
+      --train-root egomimic/ricl/outputs/robotwin_mt/train \\
+      --eval-root  egomimic/ricl/outputs/robotwin_mt/eval
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import os
+import re
+
+from egomimic.ricl.scripts.download_robotwin import download_robotwin_slice
+
+
+def _ep_num(path: str) -> int:
+    m = re.search(r"episode(\d+)", os.path.basename(path))
+    return int(m.group(1)) if m else 1 << 30
+
+
+def arrange_task(extract_dir: str, task: str, dst_root: str, n: int) -> int:
+    """Symlink the first ``n`` (numeric) episodes of ``task`` into dst_root/<task>."""
+    data_dirs = sorted(
+        glob.glob(os.path.join(extract_dir, "**", "data"), recursive=True)
+    )
+    data_dirs = [d for d in data_dirs if glob.glob(os.path.join(d, "episode*.hdf5"))]
+    if not data_dirs:
+        raise FileNotFoundError(f"no episode*.hdf5 under {extract_dir}")
+    data_dir = data_dirs[0]
+    instr_dir = os.path.join(os.path.dirname(data_dir), "instructions")
+    eps = sorted(glob.glob(os.path.join(data_dir, "episode*.hdf5")), key=_ep_num)[:n]
+
+    dst_data = os.path.join(dst_root, task, "data")
+    dst_instr = os.path.join(dst_root, task, "instructions")
+    os.makedirs(dst_data, exist_ok=True)
+    os.makedirs(dst_instr, exist_ok=True)
+    for ep in eps:
+        name = os.path.basename(ep)
+        link = os.path.join(dst_data, name)
+        if not os.path.lexists(link):
+            os.symlink(os.path.abspath(ep), link)
+        ij = os.path.join(instr_dir, name.replace(".hdf5", ".json"))
+        if os.path.exists(ij):
+            ilink = os.path.join(dst_instr, os.path.basename(ij))
+            if not os.path.lexists(ilink):
+                os.symlink(os.path.abspath(ij), ilink)
+    return len(eps)
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--train-tasks", required=True, help="comma-separated task names")
+    p.add_argument("--eval-tasks", required=True, help="comma-separated task names")
+    p.add_argument("--n-demos", type=int, default=20)
+    p.add_argument("--embodiment", default="aloha-agilex")
+    p.add_argument("--setting", default="clean", choices=["clean", "randomized"])
+    p.add_argument("--raw-dir", required=True, help="download/extract scratch dir")
+    p.add_argument("--train-root", required=True)
+    p.add_argument("--eval-root", required=True)
+    args = p.parse_args()
+
+    train = [t for t in args.train_tasks.split(",") if t]
+    evald = [t for t in args.eval_tasks.split(",") if t]
+    overlap = set(train) & set(evald)
+    if overlap:
+        raise SystemExit(
+            f"train/eval tasks must be DISJOINT; overlap: {sorted(overlap)}"
+        )
+
+    for split, tasks, root in (
+        ("train", train, args.train_root),
+        ("eval", evald, args.eval_root),
+    ):
+        for t in tasks:
+            extract_dir = download_robotwin_slice(
+                args.raw_dir, task=t, embodiment=args.embodiment, setting=args.setting
+            )
+            n = arrange_task(extract_dir, t, root, args.n_demos)
+            print(f"[{split}] {t}: linked {n} demos -> {root}/{t}", flush=True)
+
+    print(
+        f"DONE: train {len(train)} tasks -> {args.train_root} | "
+        f"eval {len(evald)} tasks -> {args.eval_root}",
+        flush=True,
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/egomimic/ricl/scripts/summarize_eval_jobs.py b/egomimic/ricl/scripts/summarize_eval_jobs.py
new file mode 100644
index 000000000..cfab89460
--- /dev/null
+++ b/egomimic/ricl/scripts/summarize_eval_jobs.py
@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Scan RoboTwin eval .out logs, print per-(job,model,task) success rates, and flag
+any task where the policies diverge (a difference between RICL/xemb and plain)."""
+
+import glob
+import os
+import re
+import sys
+
+
+def strip(s):
+    return re.sub(r"\x1b\[[0-9;]*m", "", s)
+
+
+def parse(path):
+    rows = []  # (model, task, suc, n, done)
+    cur = None
+    suc = n = 0
+    cfg = "?"
+    for ln in open(path, encoding="utf-8", errors="ignore"):
+        s = strip(ln)
+        mc = re.search(r"task_config=(\w+)", s)
+        if mc:
+            cfg = mc.group(1)
+        m = re.search(r"EVAL model=(\w+) task=(\w+)", s)
+        if m:
+            if cur:
+                rows.append((*cur, suc, n))
+            cur = (m.group(1), m.group(2))
+            suc = n = 0
+        r = re.search(r"Success rate: (\d+)/(\d+)", s)
+        if r:
+            suc, n = int(r.group(1)), int(r.group(2))
+    if cur:
+        rows.append((*cur, suc, n))
+    done = (
+        "mt eval compare DONE" in open(path, encoding="utf-8", errors="ignore").read()
+        or "xemb eval compare DONE"
+        in open(path, encoding="utf-8", errors="ignore").read()
+    )
+    return cfg, rows, done
+
+
+paths = sys.argv[1:] or sorted(
+    glob.glob("egomimic/ricl/outputs/robotwin_eval/*compare_*.out")
+)
+# task -> {model: (suc,n)} across all jobs (keyed by config to avoid mixing)
+agg = {}
+for p in paths:
+    cfg, rows, done = parse(p)
+    jid = re.search(r"_(\d+)\.out", p)
+    jid = jid.group(1) if jid else os.path.basename(p)
+    print(f"\n=== {jid}  config={cfg}  {'DONE' if done else 'running'} ===")
+    for model, task, suc, n in rows:
+        print(f"  {model:6s} {task:18s} {suc}/{n}")
+        agg.setdefault((cfg, task), {})[model] = (suc, n)
+
+print("\n=== DIVERGENCE (RICL/xemb vs plain, same task+config, both with >=5 eps) ===")
+found = False
+for (cfg, task), d in sorted(agg.items()):
+    if "plain" not in d:
+        continue
+    ps, pn = d["plain"]
+    if pn < 5:
+        continue
+    for model in ("xemb", "same", "ricl"):
+        if model not in d:
+            continue
+        ms, mn = d[model]
+        if mn < 5:
+            continue
+        diff = ms / mn - ps / pn
+        if abs(diff) >= 0.2:  # >=20 pp gap
+            found = True
+            print(
+                f"  [{cfg}] {task}: {model} {ms}/{mn} vs plain {ps}/{pn}  (Δ={diff:+.0%})"
+            )
+if not found:
+    print("  none yet (no >=20pp gap among completed cells)")
diff --git a/egomimic/ricl/scripts/train_robotwin_ricl.py b/egomimic/ricl/scripts/train_robotwin_ricl.py
new file mode 100644
index 000000000..45d4452b0
--- /dev/null
+++ b/egomimic/ricl/scripts/train_robotwin_ricl.py
@@ -0,0 +1,678 @@
+"""Train + verify EgoVerse's RICL pipeline on RoboTwin 2.0 (joint-space shim).
+
+The RoboTwin analog of ``train_droid_ricl.py``: runs the *real* RICL machinery
+(``build_ricl_collate`` -> ``PIRicl`` prefix conditioning -> pi0.5 flow matching ->
+loss -> backward -> AdamW) on RoboTwin bimanual demos via the in-memory shim in
+``egomimic.ricl.robotwin_data`` (no Zarr/SQL port). It reuses the production
+``ModelWrapper`` + Lightning ``Trainer``; only the data layer + Hydra entrypoint
+are bypassed. Eval mirrors the DROID conditions (retrieval / random-within /
+random-bank / clean floor) via the same evaluator wrapper.
+
+Stages:
+  --stage cpu  : build/load the retrieval cache, collate one batch, assert
+                 shapes/masks/prompt-splice + token budget. A fast data-path smoke
+                 with no model load; ``--embed fake`` skips the DINOv2 encoder.
+  --stage full : construct PIRicl + ModelWrapper + RoboTwin eval + Trainer and fit
+                 on GPU (submit via Hydra submitit).
+
+Data-path smoke:
+  python egomimic/ricl/scripts/train_robotwin_ricl.py --stage cpu \\
+    --root <robotwin_task_root> --embed fake --k 4 --action-horizon 15
+"""
+
+from __future__ import annotations
+
+import argparse
+import functools
+import os
+
+import torch
+
+from egomimic.ricl import robotwin_data as R
+
+RICL_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+# Local (gitignored) PaliGemma tokenizer — avoids the gated HF download (cluster).
+TOKENIZER_DIR = os.path.join(RICL_DIR, "pg_tokenizer")
+CKPT_DIR = os.path.join(
+    os.path.dirname(os.path.dirname(RICL_DIR)),
+    "egomimic/algo/pi_checkpoints/pi05_base_pytorch",
+)
+DEFAULT_OUT = os.path.join(RICL_DIR, "outputs", "robotwin_train")
+
+
+# --------------------------------------------------------------------------- #
+# Data
+# --------------------------------------------------------------------------- #
+def _retrieved_steps(args) -> int:
+    """Retrieved action steps to encode in the prompt (#1). 0 -> full chunk."""
+    return (
+        args.retrieved_action_steps
+        if args.retrieved_action_steps > 0
+        else args.action_horizon
+    )
+
+
+def _make_embed_provider(args, corpus):
+    if args.embed == "fake":
+        return R.make_fake_embedding_provider(corpus, dim=args.fake_embed_dim)
+    return R.make_dinov2_embedding_provider(corpus)
+
+
+def _make_collate(args, cache, provider, state_dim):
+    from egomimic.ricl.data import build_ricl_collate
+
+    # Retrieved state/action are TEXT-ONLY (discretized bins spliced into the
+    # prompt); encode RoboTwin's real qpos dims (``state_dim``, e.g. 14 for
+    # aloha-agilex), not the 32-D slot-fill, so retrieved bins match the query's
+    # State block. Carry the FULL retrieved action chunk (#1).
+    return build_ricl_collate(
+        cache,
+        provider,
+        k=args.k,
+        action_horizon=args.action_horizon,
+        image_hw=(224, 224),
+        state_dim=state_dim,
+        action_dim=state_dim,
+    )
+
+
+_RICL_COLLATE_FIELDS = ("images", "state", "action", "mask", "dist")
+
+
+def _combined_collate(primary, variants):
+    """Wrap the kNN collate so each val batch ALSO carries random-control blocks
+    under tagged keys (so all conditions score the same frames in one pass)."""
+
+    def collate(samples):
+        batch = primary(samples)
+        for tag, vcollate in variants.items():
+            vbatch = vcollate(samples)
+            for f in _RICL_COLLATE_FIELDS:
+                key = f"ricl_retrieved_{f}"
+                if key in vbatch:
+                    batch[f"ricl_{tag}_retrieved_{f}"] = vbatch[key]
+        return batch
+
+    return collate
+
+
+def build_data_xemb(args):
+    """Cross-EMBODIMENT data path.
+
+    Query/target = embodiment B (``--root`` / ``--eval-root``): the model predicts
+    THIS embodiment's actions. In-context bank = embodiment A (``--bank-root`` /
+    ``--eval-bank-root``): the retrieved demos show a *different* robot performing the
+    same task. Retrieval matches by task name across the two corpora (no leave-one-out;
+    the embodiments share no episodes). Each side keeps its OWN quantiles — the spliced
+    demo is encoded in emb-A units, the query/target proprio in emb-B units. Requires a
+    held-out eval split (``--eval-root`` + ``--eval-bank-root``)."""
+    if not (args.eval_root and args.eval_bank_root):
+        raise SystemExit(
+            "--bank-root (cross-embodiment) requires --eval-root and --eval-bank-root"
+        )
+    # Embodiment B (predicted): train + held-out eval queries; eval shares train norm.
+    query_corpus = R.RoboTwinCorpus(args.root)
+    eval_query_corpus = R.RoboTwinCorpus(
+        args.eval_root, quantiles=query_corpus.quantiles
+    )
+    # Embodiment A (in-context bank): own quantiles (demo encoded in emb-A units).
+    bank_corpus = R.RoboTwinCorpus(args.bank_root)
+    eval_bank_corpus = R.RoboTwinCorpus(
+        args.eval_bank_root, quantiles=bank_corpus.quantiles
+    )
+    q_embed = _make_embed_provider(args, query_corpus)
+    b_embed = _make_embed_provider(args, bank_corpus)
+    eq_embed = _make_embed_provider(args, eval_query_corpus)
+    eb_embed = _make_embed_provider(args, eval_bank_corpus)
+
+    train_cache = R.build_cross_embodiment_retrieval_cache(
+        query_corpus,
+        bank_corpus,
+        k=args.k,
+        query_embeddings_provider=q_embed,
+        bank_embeddings_provider=b_embed,
+    )
+    eval_cache = R.build_cross_embodiment_retrieval_cache(
+        eval_query_corpus,
+        eval_bank_corpus,
+        k=args.k,
+        query_embeddings_provider=eq_embed,
+        bank_embeddings_provider=eb_embed,
+    )
+    train_provider = R.make_robotwin_bank_provider(
+        bank_corpus, action_horizon=args.action_horizon
+    )
+    eval_provider = R.make_robotwin_bank_provider(
+        eval_bank_corpus, action_horizon=args.action_horizon
+    )
+    train_collate = _make_collate(
+        args, train_cache, train_provider, query_corpus.state_dim
+    )
+    val_collate = _make_collate(
+        args, eval_cache, eval_provider, eval_query_corpus.state_dim
+    )
+    if args.no_incontext:
+        from egomimic.pl_utils.pl_data_utils import annotation_collate
+
+        train_collate = annotation_collate
+        print("[data] NO-INCONTEXT baseline: plain pi0.5 finetune collate", flush=True)
+
+    train_hashes = [h for hs in query_corpus.group_to_hashes.values() for h in hs]
+    val_hashes = [h for hs in eval_query_corpus.group_to_hashes.values() for h in hs]
+    train_ds = R.RoboTwinQueryDataset(query_corpus, train_hashes, args.action_horizon)
+    val_ds = R.RoboTwinQueryDataset(eval_query_corpus, val_hashes, args.action_horizon)
+    # Expose the in-context bank's (emb A) quantiles so stage_full persists them
+    # beside the checkpoint — the closed-loop eval needs them to normalize retrieved
+    # demos identically to training (see robotwin_policy ``bank_quantiles_path``).
+    query_corpus.bank_quantiles = bank_corpus.quantiles
+    print(
+        f"[data] CROSS-EMBODIMENT: predict emb-B ({args.root}) | retrieve emb-A "
+        f"bank ({args.bank_root}); train {len(query_corpus.group_to_hashes)} tasks "
+        f"({len(train_hashes)} eps) | eval {len(eval_query_corpus.group_to_hashes)} "
+        f"held-out tasks ({len(val_hashes)} eps)",
+        flush=True,
+    )
+    return query_corpus, train_cache, train_collate, val_collate, train_ds, val_ds
+
+
+def build_data(args):
+    from egomimic.ricl.retrieval import RetrievalCache
+
+    if args.bank_root:
+        return build_data_xemb(args)
+    corpus = R.RoboTwinCorpus(args.root)
+    embed = _make_embed_provider(args, corpus)
+    if args.cache_dir and os.path.isdir(args.cache_dir):
+        cache = RetrievalCache.load(args.cache_dir)
+        print(
+            f"[data] loaded train retrieval cache ({len(cache.query_hashes)} queries) "
+            f"from {args.cache_dir}",
+            flush=True,
+        )
+    else:
+        cache = R.build_robotwin_retrieval_cache(
+            corpus, k=args.k, embeddings_provider=embed
+        )
+        print(
+            f"[data] built train retrieval cache ({len(cache.query_hashes)} queries)",
+            flush=True,
+        )
+    provider = R.make_robotwin_bank_provider(corpus, action_horizon=args.action_horizon)
+    train_collate = _make_collate(args, cache, provider, corpus.state_dim)
+    if args.no_incontext:
+        # PLAIN-FINETUNE BASELINE: no in-context demos in training (the honest
+        # comparison the k=0 floor can't give). Val collate left unchanged.
+        from egomimic.pl_utils.pl_data_utils import annotation_collate
+
+        train_collate = annotation_collate
+        print("[data] NO-INCONTEXT baseline: plain pi0.5 finetune collate", flush=True)
+
+    if args.eval_root:
+        # Separate new-task eval set; share the TRAIN corpus's quantiles so both
+        # sides normalize identically (the model was trained in train-norm units).
+        eval_corpus = R.RoboTwinCorpus(args.eval_root, quantiles=corpus.quantiles)
+        eval_embed = _make_embed_provider(args, eval_corpus)
+        train_hashes = [h for hs in corpus.group_to_hashes.values() for h in hs]
+        val_hashes = [h for hs in eval_corpus.group_to_hashes.values() for h in hs]
+        eval_cache = R.build_robotwin_retrieval_cache(
+            eval_corpus, k=args.k, embeddings_provider=eval_embed
+        )
+        eval_provider = R.make_robotwin_bank_provider(
+            eval_corpus, action_horizon=args.action_horizon
+        )
+        val_collate = _make_collate(
+            args, eval_cache, eval_provider, eval_corpus.state_dim
+        )
+        if not args.no_random:
+            within_cache = R.build_random_neighbor_cache(
+                eval_corpus,
+                k=args.k,
+                scope="within",
+                seed=args.seed,
+                embeddings_provider=eval_embed,
+            )
+            bank_cache = R.build_random_neighbor_cache(
+                eval_corpus,
+                k=args.k,
+                scope="bank",
+                seed=args.seed,
+                embeddings_provider=eval_embed,
+            )
+            val_collate = _combined_collate(
+                val_collate,
+                {
+                    "randwithin": _make_collate(
+                        args, within_cache, eval_provider, eval_corpus.state_dim
+                    ),
+                    "randbank": _make_collate(
+                        args, bank_cache, eval_provider, eval_corpus.state_dim
+                    ),
+                },
+            )
+            print("[data] random-control caches built (within + bank)", flush=True)
+        train_ds = R.RoboTwinQueryDataset(corpus, train_hashes, args.action_horizon)
+        val_ds = R.RoboTwinQueryDataset(eval_corpus, val_hashes, args.action_horizon)
+        print(
+            f"[data] NEW-TASK SPLIT: train {len(corpus.group_to_hashes)} tasks "
+            f"({len(train_hashes)} eps) | eval {len(eval_corpus.group_to_hashes)} "
+            f"NEW tasks ({len(val_hashes)} eps)",
+            flush=True,
+        )
+        return corpus, cache, train_collate, val_collate, train_ds, val_ds
+
+    # Diagnostic same-corpus episode split (smoke only): hold out the last episode
+    # of each task. The canonical RICL test is --eval-root (a separate new-task set).
+    train_hashes, val_hashes = [], []
+    for _, hs in corpus.group_to_hashes.items():
+        n_val = max(1, len(hs) // 5)
+        train_hashes += hs[:-n_val]
+        val_hashes += hs[-n_val:]
+    train_ds = R.RoboTwinQueryDataset(corpus, train_hashes, args.action_horizon)
+    val_ds = R.RoboTwinQueryDataset(corpus, val_hashes, args.action_horizon)
+    print(
+        f"[data] EPISODE-SPLIT (diagnostic): {len(train_hashes)} train eps | "
+        f"{len(val_hashes)} val eps",
+        flush=True,
+    )
+    return corpus, cache, train_collate, train_collate, train_ds, val_ds
+
+
+# --------------------------------------------------------------------------- #
+# Stage: cpu — verify the data path without the model
+# --------------------------------------------------------------------------- #
+def _load_tokenizer(args):
+    """Tokenizer for the budget check: the vendored pg_tokenizer or an explicit
+    --tokenizer. Returns None only if none is available (then the structural prompt
+    checks still run but the exact token-budget assertion is skipped)."""
+    from transformers import AutoTokenizer
+
+    for cand in (args.tokenizer, TOKENIZER_DIR):
+        if cand and (os.path.isdir(cand) or "/" not in cand):
+            try:
+                return AutoTokenizer.from_pretrained(cand)
+            except Exception as e:  # gated / missing
+                print(
+                    f"[cpu] tokenizer {cand!r} unavailable ({e}); trying next",
+                    flush=True,
+                )
+    return None
+
+
+def stage_cpu(args):
+    from egomimic.ricl import conditioning as C
+
+    corpus, cache, collate, val_collate, train_ds, val_ds = build_data(args)
+    D = corpus.state_dim
+    print(
+        f"[cpu] detected state_dim={D}, gripper_slots={corpus.gripper_slots}",
+        flush=True,
+    )
+    idxs = (0, len(train_ds) // 2, len(train_ds) - 1)
+    batch = collate([train_ds[i] for i in idxs])
+    B, k = len(idxs), args.k
+    assert batch["ricl_retrieved_images"].shape == (B, k, 3, 224, 224)
+    assert batch["ricl_retrieved_state"].shape == (B, k, D)
+    # (#1) full retrieved action chunk: (B, k, action_horizon, D)
+    assert batch["ricl_retrieved_action"].shape == (
+        B,
+        k,
+        args.action_horizon,
+        D,
+    )
+    assert batch["ricl_retrieved_mask"].shape == (B, k)
+    assert (
+        batch["ricl_retrieved_images"].min() >= 0
+        and batch["ricl_retrieved_images"].max() <= 1.0
+    )
+    assert batch[R.AC_KEY].shape == (B, args.action_horizon, 32)
+    assert batch[R.STATE_KEY].shape == (B, 32)
+    assert batch["ricl_retrieved_mask"].any(), "no neighbors found for train frames"
+    print(
+        f"[cpu] collate shapes OK; "
+        f"valid neighbors/sample={batch['ricl_retrieved_mask'].sum(1).tolist()}",
+        flush=True,
+    )
+
+    # prompt splice (structural — no tokenizer needed)
+    states = batch["ricl_retrieved_state"]
+    actions = batch["ricl_retrieved_action"]
+    valid = batch["ricl_retrieved_mask"]
+    steps = _retrieved_steps(args)
+    spliced_prompts = []
+    for i in range(B):
+        task = corpus.prompt(batch["episode_hash"][i])
+        block = C.build_retrieved_prompt_block(
+            states[i],
+            actions[i],
+            valid[i],
+            prompt=task,
+            num_bins=256,
+            action_steps=steps,
+        )
+        base = (
+            f"Task: {task}, Embodiment: eva bimanual, State: "
+            + " ".join(["128"] * D)
+            + C.PI05_ANCHOR
+        )
+        spliced = C.splice_retrieved_into_prompt(base, block)
+        assert spliced.endswith(
+            C.PI05_ANCHOR
+        ), "anchor must stay terminal (query block)"
+        if valid[i].any():
+            assert block and spliced.startswith(block)
+            assert spliced.count("|") == int(valid[i].sum())  # one '|' per valid demo
+        spliced_prompts.append(spliced)
+    print(
+        "[cpu] prompt splice OK (anchor terminal, one '|' per valid demo)", flush=True
+    )
+
+    # token budget (requires a tokenizer; skipped only if none is available)
+    tok = _load_tokenizer(args)
+    if tok is None:
+        wc = max(len(p.split()) for p in spliced_prompts)
+        print(
+            f"[cpu] no tokenizer found -> skipping exact token-budget check "
+            f"(worst-case ~{wc} whitespace tokens; provide --tokenizer or pg_tokenizer "
+            f"for the strict --max-token-len {args.max_token_len} check)",
+            flush=True,
+        )
+    else:
+        max_tokens = max(len(tok(p)["input_ids"]) for p in spliced_prompts)
+        print(
+            f"[cpu] worst-case prompt = {max_tokens} tokens "
+            f"(max_token_len={args.max_token_len})",
+            flush=True,
+        )
+        assert (
+            max_tokens < args.max_token_len
+        ), f"prompt {max_tokens} >= max_token_len {args.max_token_len}: bump it"
+    print("[cpu] ALL CHECKS PASSED", flush=True)
+
+
+# --------------------------------------------------------------------------- #
+# Model + Lightning wiring (cluster)
+# --------------------------------------------------------------------------- #
+def build_model(args):
+    from types import SimpleNamespace
+
+    from egomimic.algo.pi_ricl import PIRicl
+
+    config = SimpleNamespace(
+        pytorch_training_precision="bfloat16",
+        pytorch_weight_path=args.ckpt,
+        model=SimpleNamespace(
+            pi05=True,
+            action_dim=32,
+            action_horizon=args.action_horizon,
+            max_token_len=args.max_token_len,
+            paligemma_variant="gemma_2b",
+            action_expert_variant="gemma_300m",
+        ),
+    )
+    action_converters = SimpleNamespace(
+        rules={R.EMB_NAME: R.Passthrough32()},
+        fallback=R.Passthrough32(),
+        ac_key=R.AC_KEY,
+    )
+    algo = PIRicl(
+        norm_stats=R.RoboTwinNormStats(),
+        camera_transforms=None,
+        domains=[R.EMB_NAME],
+        train_image_augs=None,
+        eval_image_augs=None,
+        config=config,
+        ac_keys={R.EMB_NAME: R.AC_KEY},
+        action_converters=action_converters,
+        tokenizer_model_name=args.tokenizer or TOKENIZER_DIR,
+        tokenizer_max_length=args.max_token_len,
+        sampling_mode="random",
+        annotation_key="annotations",
+        default_prompt="",
+        proprio_in_prompt=True,
+        embodiment_label=True,
+        state_num_bins=256,
+        proprio_keys_for_prompt=[R.PROMPT_STATE_KEY],
+        num_retrieved_observations=args.k,
+        retrieved_action_steps=_retrieved_steps(args),
+        ricl_base_key="base_0_rgb",
+        image_resolution=(224, 224),
+    )
+    return algo
+
+
+def stage_full(args):
+    import lightning as L
+    from lightning.pytorch.callbacks import ModelCheckpoint
+    from lightning.pytorch.loggers import CSVLogger
+    from lightning.pytorch.utilities import CombinedLoader
+    from torch.utils.data import DataLoader
+    from transformers import get_cosine_schedule_with_warmup
+
+    from egomimic.ricl.robotwin_eval import (
+        RoboTwinRiclEval,
+        RoboTwinRiclModelWrapper,
+    )
+
+    torch.manual_seed(args.seed)
+    L.seed_everything(args.seed, workers=True)
+
+    corpus, cache, train_collate, val_collate, train_ds, val_ds = build_data(args)
+
+    train_loader = DataLoader(
+        train_ds,
+        batch_size=args.batch_size,
+        shuffle=True,
+        collate_fn=train_collate,
+        num_workers=args.num_workers,
+        drop_last=True,
+        persistent_workers=args.num_workers > 0,
+    )
+    val_loader = DataLoader(
+        val_ds,
+        batch_size=args.batch_size,
+        shuffle=False,
+        collate_fn=val_collate,
+        num_workers=args.num_workers,
+        persistent_workers=args.num_workers > 0,
+    )
+    train_cl = CombinedLoader({R.EMB_NAME: train_loader}, "max_size_cycle")
+    val_cl = CombinedLoader({R.EMB_NAME: val_loader}, "max_size_cycle")
+
+    algo = build_model(args)
+    if args.adam8bit:
+        # 8-bit AdamW (bitsandbytes): optimizer state ~7GB vs ~29GB for fp32 moments,
+        # so the 3.6B pi0.5 full fine-tune fits on a single <=48GB GPU (a40/l40s).
+        # Required on this cluster (no >48GB GPU); H200 runs can keep plain AdamW.
+        import bitsandbytes as bnb
+
+        optimizer = functools.partial(
+            bnb.optim.AdamW8bit,
+            lr=args.lr,
+            betas=(0.9, 0.95),
+            eps=1e-8,
+            weight_decay=1e-10,
+        )
+        print("[full] optimizer: 8-bit AdamW (bitsandbytes)", flush=True)
+    else:
+        optimizer = functools.partial(
+            torch.optim.AdamW,
+            lr=args.lr,
+            betas=(0.9, 0.95),
+            eps=1e-8,
+            weight_decay=1e-10,
+        )
+    scheduler = functools.partial(
+        get_cosine_schedule_with_warmup,
+        num_warmup_steps=args.warmup_steps,
+        num_training_steps=args.max_steps,
+        num_cycles=0.5,
+    )
+    model = RoboTwinRiclModelWrapper(
+        robomimic_model=algo,
+        optimizer=optimizer,
+        scheduler=scheduler,
+        scheduler_interval="step",
+        enable_grad_norm=True,
+    )
+    evaluator = RoboTwinRiclEval(
+        compute_floor=True,
+        compute_random=not args.no_random,
+        n_flow_samples=args.flow_samples,
+        compute_sampled=args.compute_sampled,
+        interp_lamdas=[float(x) for x in args.interp_lamdas.split(",") if x.strip()]
+        if args.interp_lamdas
+        else [],
+        gripper_indices=corpus.gripper_slots,  # detected (e.g. (6, 13) for aloha-agilex)
+        raw_dim=corpus.state_dim,  # detected (e.g. 14 for aloha-agilex)
+        limit_val_batches=args.limit_val_batches,
+    )
+
+    os.makedirs(args.out, exist_ok=True)
+    logger = CSVLogger(args.out, name=args.name, flush_logs_every_n_steps=10)
+    # Persist the TRAIN corpus's norm quantiles next to the checkpoints so the
+    # closed-loop eval (robotwin_policy.PIRiclPolicy) normalizes identically to
+    # training. Pair (quantiles.json, checkpoint) when wiring deploy_policy.yml.
+    corpus.save_quantiles(os.path.join(logger.log_dir, "quantiles.json"))
+    print(f"[full] saved quantiles -> {logger.log_dir}/quantiles.json", flush=True)
+    if getattr(corpus, "bank_quantiles", None) is not None:
+        # Cross-embodiment: persist the in-context bank (emb A) quantiles too.
+        R.save_quantiles(
+            corpus.bank_quantiles, os.path.join(logger.log_dir, "bank_quantiles.json")
+        )
+        print(
+            f"[full] saved BANK quantiles -> {logger.log_dir}/bank_quantiles.json",
+            flush=True,
+        )
+    ckpt_cb = ModelCheckpoint(
+        dirpath=os.path.join(logger.log_dir, "checkpoints"),
+        filename="step{step}-{Valid/action_loss:.4f}",
+        monitor="Valid/action_loss",
+        mode="min",
+        save_top_k=1,
+        save_last=True,
+        every_n_train_steps=args.ckpt_every,
+        auto_insert_metric_name=False,
+    )
+    trainer = L.Trainer(
+        accelerator="gpu",
+        devices=args.devices,
+        strategy="ddp_find_unused_parameters_true" if args.devices > 1 else "auto",
+        precision="bf16-mixed",
+        max_steps=args.max_steps,
+        val_check_interval=args.val_every,
+        check_val_every_n_epoch=None,
+        limit_val_batches=args.limit_val_batches,
+        num_sanity_val_steps=0,
+        log_every_n_steps=args.log_every,
+        logger=logger,
+        default_root_dir=args.out,
+        callbacks=[ckpt_cb],
+    )
+    evaluator.trainer = trainer
+    evaluator.model = model.model
+    model.evaluator = evaluator
+
+    print(f"[full] metrics CSV -> {logger.log_dir}/metrics.csv", flush=True)
+    if args.validate_only:
+        if not args.resume_from:
+            raise SystemExit("--validate-only requires --resume-from <ckpt>")
+        trainer.validate(
+            model, dataloaders=val_cl, ckpt_path=args.resume_from, weights_only=False
+        )
+        return
+    trainer.fit(
+        model,
+        train_dataloaders=train_cl,
+        val_dataloaders=val_cl,
+        ckpt_path=args.resume_from,
+    )
+
+
+# --------------------------------------------------------------------------- #
+def build_argparser():
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--stage", choices=["cpu", "full"], required=True)
+    p.add_argument(
+        "--root", required=True, help="RoboTwin task root (parent of <task>/data)"
+    )
+    p.add_argument("--eval-root", default="", help="separate new-task eval root")
+    p.add_argument(
+        "--bank-root",
+        default="",
+        help="CROSS-EMBODIMENT: in-context retrieval bank (embodiment A) for the TRAIN "
+        "tasks. When set, --root/--eval-root are the predicted embodiment B and demos "
+        "are retrieved cross-corpus by task. Requires --eval-bank-root.",
+    )
+    p.add_argument(
+        "--eval-bank-root",
+        default="",
+        help="CROSS-EMBODIMENT: in-context retrieval bank (embodiment A) for the "
+        "held-out EVAL tasks.",
+    )
+    p.add_argument(
+        "--cache-dir", default="", help="load a prebuilt retrieval cache from here"
+    )
+    p.add_argument("--out", default=DEFAULT_OUT)
+    p.add_argument("--name", default="robotwin_ricl")
+    p.add_argument(
+        "--ckpt", default=CKPT_DIR, help="pi0.5 base checkpoint (full stage)"
+    )
+    p.add_argument(
+        "--tokenizer", default="", help="tokenizer dir/name (default: pg_tokenizer)"
+    )
+    p.add_argument(
+        "--embed",
+        choices=["fake", "dinov2"],
+        default="fake",
+        help="per-frame embedding source for the retrieval cache (fake=stub for a fast smoke)",
+    )
+    p.add_argument("--fake-embed-dim", type=int, default=256)
+    p.add_argument("--k", type=int, default=4)
+    p.add_argument("--action-horizon", type=int, default=15)
+    p.add_argument(
+        "--retrieved-action-steps",
+        type=int,
+        default=0,
+        help="(#1) retrieved action steps encoded in the prompt; 0 = full chunk. "
+        "16-D RoboTwin chunks are token-heavy: k=4 full 15-step worst case is large, "
+        "so --max-token-len defaults high. Lower this to shrink the prompt.",
+    )
+    p.add_argument("--max-token-len", type=int, default=4608)
+    p.add_argument("--interp-lamdas", type=str, default="")
+    p.add_argument("--batch-size", type=int, default=4)
+    p.add_argument("--num-workers", type=int, default=4)
+    p.add_argument("--devices", type=int, default=1)
+    p.add_argument("--max-steps", type=int, default=4000)
+    p.add_argument("--warmup-steps", type=int, default=200)
+    p.add_argument("--lr", type=float, default=3e-5)
+    p.add_argument(
+        "--adam8bit",
+        action="store_true",
+        help="use 8-bit AdamW (bitsandbytes) to fit the optimizer state on <=48GB GPUs",
+    )
+    p.add_argument("--val-every", type=int, default=250)
+    p.add_argument("--limit-val-batches", type=int, default=10)
+    p.add_argument("--log-every", type=int, default=10)
+    p.add_argument("--seed", type=int, default=42)
+    p.add_argument("--no-random", action="store_true")
+    p.add_argument(
+        "--no-incontext", action="store_true", help="plain-finetune baseline"
+    )
+    p.add_argument("--flow-samples", type=int, default=8)
+    p.add_argument("--compute-sampled", action="store_true")
+    p.add_argument("--validate-only", action="store_true")
+    p.add_argument("--ckpt-every", type=int, default=1000)
+    p.add_argument("--resume-from", default=None)
+    return p
+
+
+def main():
+    args = build_argparser().parse_args()
+    if args.stage == "cpu":
+        stage_cpu(args)
+    else:
+        stage_full(args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/egomimic/ricl/scripts/train_robotwin_ricl.sbatch b/egomimic/ricl/scripts/train_robotwin_ricl.sbatch
new file mode 100644
index 000000000..351b54e5e
--- /dev/null
+++ b/egomimic/ricl/scripts/train_robotwin_ricl.sbatch
@@ -0,0 +1,50 @@
+#!/bin/bash
+#SBATCH --job-name=robotwin_ricl
+#SBATCH --nodes=1
+#SBATCH --ntasks=1
+#SBATCH --cpus-per-task=8
+#SBATCH --mem=100G
+#SBATCH --partition=gpu-h200
+#SBATCH --account=gts-dxu345-rl2
+#SBATCH --gres=gpu:h200:1
+#SBATCH --qos=inferno
+#SBATCH --time=04:00:00
+#SBATCH --output=egomimic/ricl/outputs/robotwin_train/slurm_%j.out
+#SBATCH --error=egomimic/ricl/outputs/robotwin_train/slurm_%j.err
+
+# Train EgoVerse pi0.5 RICL on RoboTwin (single task, in-memory HDF5 shim).
+# Submit from the repo root: sbatch egomimic/ricl/scripts/train_robotwin_ricl.sbatch
+set -uo pipefail
+cd /storage/project/r-dxu345-0/rco3/EgoVerse2
+mkdir -p egomimic/ricl/outputs/robotwin_train
+source emimic/bin/activate
+export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
+
+echo "host=$(hostname) gpu=${CUDA_VISIBLE_DEVICES:-?}"
+nvidia-smi --query-gpu=name,memory.total --format=csv,noheader || true
+
+ROOT="${ROOT:-egomimic/ricl/outputs/robotwin_raw/extracted}"
+
+python -u egomimic/ricl/scripts/train_robotwin_ricl.py --stage full \
+  --root "${ROOT}" \
+  ${EVAL_ROOT:+--eval-root "${EVAL_ROOT}"} \
+  ${BANK_ROOT:+--bank-root "${BANK_ROOT}"} \
+  ${EVAL_BANK_ROOT:+--eval-bank-root "${EVAL_BANK_ROOT}"} \
+  --embed "${EMBED:-dinov2}" \
+  --k "${K:-4}" \
+  --action-horizon "${ACTION_HORIZON:-15}" \
+  --batch-size "${BATCH_SIZE:-2}" \
+  --num-workers "${NUM_WORKERS:-6}" \
+  --devices 1 \
+  --max-steps "${MAX_STEPS:-4000}" \
+  --warmup-steps "${WARMUP_STEPS:-200}" \
+  --lr "${LR:-3e-5}" \
+  ${NO_INCONTEXT:+--no-incontext} \
+  ${NO_RANDOM:+--no-random} \
+  --val-every "${VAL_EVERY:-250}" \
+  --limit-val-batches "${LIMIT_VAL:-10}" \
+  --ckpt-every "${CKPT_EVERY:-1000}" \
+  --out egomimic/ricl/outputs/robotwin_train \
+  --name "${RUN_NAME:-robotwin_ricl}"
+
+echo "=== train exit: $? ==="
diff --git a/egomimic/ricl/tests/robotwin_adapter_test.py b/egomimic/ricl/tests/robotwin_adapter_test.py
new file mode 100644
index 000000000..033bd4e3a
--- /dev/null
+++ b/egomimic/ricl/tests/robotwin_adapter_test.py
@@ -0,0 +1,118 @@
+"""Unit tests for the RoboTwin closed-loop adapter glue (robotwin_adapter.py).
+
+Exercises the pure-Python pieces with the model + SAPIEN sim MOCKED: observation
+mapping, quantile (un)normalization round-trip, slot-filled model input, action
+un-normalization to qpos, and online retrieval against a tiny stub bank. No
+checkpoint, no DINOv2, no sim.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from egomimic.ricl import robotwin_adapter as A
+from egomimic.ricl.retrieval import BankRefs, RetrievalIndex
+
+D = 14  # aloha-agilex qpos dim
+H = 15
+K = 4
+
+
+def _fake_obs(d=D, hw=(48, 64)):
+    H_, W_ = hw
+    rng = np.random.default_rng(0)
+    return {
+        "observation": {
+            "head_camera": {"rgb": np.full((H_, W_, 3), 10, np.uint8)},
+            "left_camera": {"rgb": np.full((H_, W_, 3), 20, np.uint8)},
+            "right_camera": {"rgb": np.full((H_, W_, 3), 30, np.uint8)},
+        },
+        "joint_action": {"vector": rng.standard_normal(d).astype(np.float32)},
+    }
+
+
+def test_obs_to_state_order_and_shape():
+    obs = _fake_obs()
+    rgb, state = A.obs_to_state(obs)
+    assert len(rgb) == 3
+    # order is [head, right, left] (matches pi05 encode_obs)
+    assert rgb[0][0, 0, 0] == 10  # head
+    assert rgb[1][0, 0, 0] == 30  # right
+    assert rgb[2][0, 0, 0] == 20  # left
+    assert state.shape == (D,)
+
+
+def test_quantile_norm_roundtrip():
+    q01 = np.full(D, -2.0, np.float32)
+    q99 = np.full(D, 2.0, np.float32)
+    x = np.linspace(-1.5, 1.5, D).astype(np.float32)
+    x_norm = A.quantile_norm(x, q01, q99)
+    x_back = A.quantile_unnorm(x_norm, q01, q99)
+    assert np.allclose(x, x_back, atol=1e-4)
+
+
+def test_state_to_model_input_slotfill():
+    q = (np.full(D, -1.0, np.float32), np.full(D, 1.0, np.float32))
+    state = np.zeros(D, np.float32)
+    out = A.state_to_model_input(state, q)
+    assert out.shape == (32,)
+    assert np.allclose(out[D:], 0.0)  # pad dims zero
+
+
+def test_unnormalize_action_to_qpos():
+    q01 = np.full(D, -3.0, np.float32)
+    q99 = np.full(D, 3.0, np.float32)
+    qpos = np.linspace(-2.0, 2.0, D).astype(np.float32)
+    # forward: qpos -> normalized -> slot-fill to 32 (what the model predicts)
+    norm = A.quantile_norm(qpos, q01, q99)
+    pred32 = np.concatenate([norm, np.zeros(32 - D, np.float32)])
+    pred_chunk = np.tile(pred32, (H, 1))  # (H, 32)
+    out = A.unnormalize_action(pred_chunk, (q01, q99), state_dim=D)
+    assert out.shape == (H, D)
+    assert np.allclose(out[0], qpos, atol=1e-4)  # inverts back to qpos
+
+
+class _FakeEmbedder:
+    """Returns a fixed descriptor equal to bank row 0 (so kNN is deterministic)."""
+
+    def __init__(self, vec):
+        self._vec = np.asarray(vec, np.float32)
+
+    def embed(self, images_thwc):
+        return np.tile(self._vec, (len(images_thwc), 1)).astype(np.float32)
+
+
+def _fake_bank_provider(episode_hash, frame_idx):
+    return {
+        "image": np.full((32, 32, 3), 100, np.uint8),
+        "state": np.full(D, 0.5, np.float32),
+        "action": np.full((H, D), 0.25, np.float32),
+    }
+
+
+def test_online_retriever_blocks():
+    dim = 8
+    vectors = np.eye(5, dim, dtype=np.float32)  # 5 distinct bank rows
+    refs = BankRefs(
+        episode_hash=np.array([f"ep{i}" for i in range(5)]).astype("U"),
+        frame_idx=np.zeros(5, np.int32),
+    )
+    index = RetrievalIndex(vectors, refs)
+    retriever = A.OnlineRetriever(
+        index,
+        _fake_bank_provider,
+        _FakeEmbedder(vectors[0]),  # query matches ep0
+        k=K,
+        action_horizon=H,
+        state_dim=D,
+    )
+    out = retriever.retrieve(np.full((48, 64, 3), 7, np.uint8))
+    assert out["ricl_retrieved_images"].shape == (1, K, 3, 224, 224)
+    assert out["ricl_retrieved_state"].shape == (1, K, D)
+    assert out["ricl_retrieved_action"].shape == (1, K, H, D)
+    assert out["ricl_retrieved_mask"].shape == (1, K)
+    assert bool(out["ricl_retrieved_mask"].all())  # 5 bank rows >= k -> all valid
+    imgs = out["ricl_retrieved_images"]
+    assert imgs.min() >= 0.0 and imgs.max() <= 1.0  # scaled to [0,1]
+    # nearest neighbor is bank row 0 (query == vectors[0]) at ~zero distance
+    assert float(out["ricl_retrieved_dist"][0, 0]) < 1e-4
diff --git a/egomimic/ricl/tests/robotwin_bank_index_test.py b/egomimic/ricl/tests/robotwin_bank_index_test.py
new file mode 100644
index 000000000..ffc099a80
--- /dev/null
+++ b/egomimic/ricl/tests/robotwin_bank_index_test.py
@@ -0,0 +1,86 @@
+"""Bank-index builder + OnlineRetriever round-trip (CPU, synthetic, no DINOv2).
+
+Covers the eval-side glue: ``build_robotwin_bank_index.build_bank_index`` writes a
+consolidated ``{vectors.npy, refs.npz, manifest.json}`` index over a RoboTwin corpus,
+which ``build_embedding_index.build_retrieval_index`` loads and
+``robotwin_adapter.OnlineRetriever`` queries online. Uses fake embeddings + a stub
+query embedder so it runs on a login node.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+import numpy as np
+import pytest
+
+from egomimic.ricl import robotwin_data as R
+from egomimic.ricl.robotwin_adapter import OnlineRetriever
+from egomimic.ricl.scripts.build_embedding_index import build_retrieval_index
+from egomimic.ricl.scripts.build_robotwin_bank_index import build_bank_index
+from egomimic.ricl.scripts.download_robotwin import make_synthetic_robotwin_task
+
+DIM = 128
+
+
+@pytest.fixture(scope="module")
+def corpus(tmp_path_factory):
+    root = str(tmp_path_factory.mktemp("robotwin_bank"))
+    make_synthetic_robotwin_task(root, "pick_cube", n_episodes=4, n_frames=30)
+    return R.RoboTwinCorpus(root)
+
+
+class _StubEmbedder:
+    """Deterministic query embedder matching the fake bank-index dim."""
+
+    def __init__(self, dim: int):
+        self.dim = dim
+
+    def embed(self, imgs):
+        return np.zeros((np.asarray(imgs).shape[0], self.dim), dtype=np.float32)
+
+
+def test_build_bank_index_artifacts(corpus, tmp_path):
+    out = str(tmp_path / "bank_index")
+    build_bank_index(corpus, out, R.make_fake_embedding_provider(corpus, dim=DIM))
+
+    assert os.path.isfile(os.path.join(out, "vectors.npy"))
+    assert os.path.isfile(os.path.join(out, "refs.npz"))
+    with open(os.path.join(out, "manifest.json")) as f:
+        manifest = json.load(f)
+
+    vectors = np.load(os.path.join(out, "vectors.npy"))
+    refs = np.load(os.path.join(out, "refs.npz"))
+    n_total = sum(corpus.num_frames(h) for h in corpus.hashes)
+    assert vectors.shape == (n_total, DIM)
+    assert manifest["n_frames"] == n_total
+    assert manifest["embed_dim"] == DIM
+    # refs reference only real corpus episodes, frame_idx within range
+    hashes = set(corpus.hashes)
+    assert set(refs["episode_hash"].tolist()) <= hashes
+    for h, fi in zip(refs["episode_hash"], refs["frame_idx"]):
+        assert 0 <= int(fi) < corpus.num_frames(str(h))
+
+
+def test_online_retriever_roundtrip(corpus, tmp_path):
+    out = str(tmp_path / "bank_index2")
+    build_bank_index(corpus, out, R.make_fake_embedding_provider(corpus, dim=DIM))
+    index = build_retrieval_index(out)
+    bank_provider = R.make_robotwin_bank_provider(corpus, action_horizon=15)
+    ret = OnlineRetriever(
+        index,
+        bank_provider,
+        _StubEmbedder(DIM),
+        k=4,
+        action_horizon=15,
+        state_dim=corpus.state_dim,
+    )
+    q = corpus.image(corpus.hashes[0], 0, "base_0_rgb")
+    blocks = ret.retrieve(q)
+    d = corpus.state_dim
+    assert blocks["ricl_retrieved_images"].shape == (1, 4, 3, 224, 224)
+    assert blocks["ricl_retrieved_state"].shape == (1, 4, d)
+    assert blocks["ricl_retrieved_action"].shape == (1, 4, 15, d)
+    assert blocks["ricl_retrieved_mask"].shape == (1, 4)
+    assert bool(blocks["ricl_retrieved_mask"].any())
diff --git a/egomimic/ricl/tests/robotwin_data_test.py b/egomimic/ricl/tests/robotwin_data_test.py
new file mode 100644
index 000000000..f2b7b07bd
--- /dev/null
+++ b/egomimic/ricl/tests/robotwin_data_test.py
@@ -0,0 +1,167 @@
+"""Unit tests for the RoboTwin RICL shim (egomimic/ricl/robotwin_data.py).
+
+Builds a tiny *synthetic* RoboTwin corpus (no archive download, no simulator) and validates the
+corpus accessors, the query dataset keys/shapes/normalization, the bank provider,
+the within-task leave-one-out retrieval cache + random controls, and the RICL
+collate output shapes/masks. Uses a deterministic fake embedding provider so no
+DINOv2 weights are needed.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from egomimic.ricl import robotwin_data as R
+from egomimic.ricl.data import build_ricl_collate
+from egomimic.ricl.scripts.download_robotwin import make_synthetic_robotwin_task
+
+N_EPS = 4
+N_FRAMES = 40
+HORIZON = 15
+K = 4
+
+
+@pytest.fixture(scope="module")
+def root(tmp_path_factory):
+    d = tmp_path_factory.mktemp("robotwin_fixture")
+    # two tasks (groups) so within-task LOO and cross-task random-bank are testable
+    make_synthetic_robotwin_task(
+        str(d), task="pick_cube", n_episodes=N_EPS, n_frames=N_FRAMES, seed=0
+    )
+    make_synthetic_robotwin_task(
+        str(d), task="stack_blocks", n_episodes=N_EPS, n_frames=N_FRAMES, seed=100
+    )
+    return str(d)
+
+
+@pytest.fixture(scope="module")
+def corpus(root):
+    return R.RoboTwinCorpus(root)
+
+
+def test_corpus_discovery(corpus):
+    assert len(corpus.group_to_hashes) == 2
+    assert set(corpus.group_to_hashes) == {"pick_cube", "stack_blocks"}
+    assert len(corpus.hashes) == 2 * N_EPS
+    for h in corpus.hashes:
+        assert corpus.num_frames(h) == N_FRAMES
+        assert corpus.group_of(h) in corpus.group_to_hashes
+    # detected qpos layout: 6-DOF arms -> 14-D state, grippers at slots 6 and 13
+    assert corpus.state_dim == 14
+    assert corpus.gripper_slots == (6, 13)
+    # quantiles computed for state + actions, per-dim over the qpos dims
+    for which in ("state", "actions"):
+        q01, q99 = corpus.quantiles[which]
+        assert q01.shape == (corpus.state_dim,) and q99.shape == (corpus.state_dim,)
+
+
+def test_state_action_shapes_and_chunk_padding(corpus):
+    h = corpus.hashes[0]
+    D = corpus.state_dim
+    assert corpus.state(h, 0).shape == (D,)
+    chunk = corpus.action_chunk(h, 0, HORIZON)
+    assert chunk.shape == (HORIZON, D)
+    # near the episode tail the chunk repeat-pads the last action
+    tail = corpus.action_chunk(h, N_FRAMES - 2, HORIZON)
+    assert tail.shape == (HORIZON, D)
+    assert np.allclose(tail[-1], tail[-2])  # padded with the last frame
+
+
+def test_image_decode(corpus):
+    img = corpus.image(corpus.hashes[0], 0, "base_0_rgb")
+    assert img.shape == (224, 224, 3)
+    assert img.dtype == np.uint8
+
+
+def test_query_sample_keys_and_norm(corpus):
+    D = corpus.state_dim
+    ds = R.RoboTwinQueryDataset(corpus, corpus.hashes[:1], action_horizon=HORIZON)
+    s = ds[0]
+    assert s[R.STATE_KEY].shape == (32,)
+    assert s[R.AC_KEY].shape == (HORIZON, 32)
+    # slot-fill: pad dims D..31 are zero on both state and action
+    assert np.allclose(s[R.STATE_KEY][D:], 0.0)
+    assert np.allclose(s[R.AC_KEY][:, D:], 0.0)
+    # quantile-normalized payload roughly within [-1, 1] (q01/q99 clip the bulk)
+    assert s[R.STATE_KEY][:D].min() > -5 and s[R.STATE_KEY][:D].max() < 5
+    assert s[R.PROMPT_STATE_KEY].shape == (D,)
+    for cam in R.CAM_KEYS:
+        assert s[cam].shape == (224, 224, 3)
+        assert s[cam].dtype == np.uint8
+    assert isinstance(s["annotations"], list) and isinstance(s["annotations"][0], str)
+    assert s["episode_hash"] == corpus.hashes[0]
+    assert s["frame_idx"] == 0
+
+
+def test_bank_provider(corpus):
+    D = corpus.state_dim
+    prov = R.make_robotwin_bank_provider(corpus, action_horizon=HORIZON)
+    blk = prov(corpus.hashes[0], 3)
+    assert blk["image"].shape == (224, 224, 3)
+    assert blk["state"].shape == (D,)
+    assert blk["action"].shape == (HORIZON, D)
+
+
+def test_retrieval_cache_and_collate(corpus):
+    D = corpus.state_dim
+    embed = R.make_fake_embedding_provider(corpus, dim=128)
+    cache = R.build_robotwin_retrieval_cache(corpus, k=K, embeddings_provider=embed)
+    R._verify_cache(cache, corpus)
+
+    prov = R.make_robotwin_bank_provider(corpus, action_horizon=HORIZON)
+    collate = build_ricl_collate(
+        cache,
+        prov,
+        k=K,
+        action_horizon=HORIZON,
+        state_dim=D,
+        action_dim=D,
+    )
+    ds = R.RoboTwinQueryDataset(corpus, corpus.hashes[:2], action_horizon=HORIZON)
+    batch = collate([ds[0], ds[N_FRAMES // 2], ds[N_FRAMES + 1]])
+    B = 3
+    assert batch["ricl_retrieved_images"].shape == (B, K, 3, 224, 224)
+    assert batch["ricl_retrieved_state"].shape == (B, K, D)
+    assert batch["ricl_retrieved_action"].shape == (B, K, HORIZON, D)
+    assert batch["ricl_retrieved_mask"].shape == (B, K)
+    imgs = batch["ricl_retrieved_images"]
+    assert imgs.min() >= 0.0 and imgs.max() <= 1.0
+    assert batch["ricl_retrieved_mask"].any()  # in-task frames have neighbors
+    # base query keys survived the collate
+    assert batch[R.AC_KEY].shape == (B, HORIZON, 32)
+    assert batch[R.STATE_KEY].shape == (B, 32)
+    assert len(batch["annotations"]) == B
+
+
+def test_random_neighbor_caches(corpus):
+    embed = R.make_fake_embedding_provider(corpus, dim=64)
+    within = R.build_random_neighbor_cache(
+        corpus, k=K, scope="within", seed=1, embeddings_provider=embed
+    )
+    bank = R.build_random_neighbor_cache(
+        corpus, k=K, scope="bank", seed=1, embeddings_provider=embed
+    )
+    # within-scope neighbors stay in the query's own group; bank-scope may cross
+    for qh in within.query_hashes:
+        bh, _, dd = within.neighbors(qh, 0)
+        grp = set(corpus.group_to_hashes[corpus.group_of(qh)])
+        for h in (str(x) for x in bh if str(x)):
+            assert h in grp and h != qh
+        assert np.all(dd >= 0.0)  # true embedding L2 carried (not fake 0)
+    crossed = False
+    for qh in bank.query_hashes:
+        bh, _, _ = bank.neighbors(qh, 0)
+        grp = set(corpus.group_to_hashes[corpus.group_of(qh)])
+        if any(str(x) and str(x) not in grp for x in bh):
+            crossed = True
+    assert crossed, "bank scope should sometimes pull cross-task demos"
+
+
+def test_shared_quantiles_across_corpora(root):
+    """An eval corpus can reuse the train corpus's quantiles for matched norm."""
+    train = R.RoboTwinCorpus(root, groups=["pick_cube"])
+    evald = R.RoboTwinCorpus(root, groups=["stack_blocks"], quantiles=train.quantiles)
+    for which in ("state", "actions"):
+        assert np.array_equal(train.quantiles[which][0], evald.quantiles[which][0])
+        assert np.array_equal(train.quantiles[which][1], evald.quantiles[which][1])
diff --git a/egomimic/ricl/tests/robotwin_to_zarr_test.py b/egomimic/ricl/tests/robotwin_to_zarr_test.py
new file mode 100644
index 000000000..48cecd435
--- /dev/null
+++ b/egomimic/ricl/tests/robotwin_to_zarr_test.py
@@ -0,0 +1,98 @@
+"""Integration test for the RoboTwin -> EgoVerse Zarr converter.
+
+Converts a synthetic RoboTwin task to Zarr, then loads it back through the *real*
+EgoVerse pipeline — ``ZarrDataset`` + ``Eva.get_keymap("cartesian_pi")`` +
+``Eva.get_transform_list("cartesian")`` — proving the produced store is a valid
+``eva_bimanual`` cartesian episode (the standard MultiDataset path) without any
+S3/SQL. Also checks the converter errors clearly when ``endpose`` is absent.
+"""
+
+from __future__ import annotations
+
+import h5py
+import numpy as np
+import pytest
+
+from egomimic.ricl.scripts.download_robotwin import (
+    make_synthetic_robotwin_episode,
+    make_synthetic_robotwin_task,
+)
+from egomimic.ricl.scripts.robotwin_to_zarr import convert_episode, convert_task
+from egomimic.rldb.embodiment.eva import Eva
+from egomimic.rldb.zarr.zarr_dataset_multi import ZarrDataset
+
+CHUNK = 15
+N_EPS = 2
+N_FRAMES = 60
+
+
+@pytest.fixture(scope="module")
+def zarr_stores(tmp_path_factory):
+    src = tmp_path_factory.mktemp("rt_src")
+    out = tmp_path_factory.mktemp("rt_zarr")
+    make_synthetic_robotwin_task(
+        str(src), task="pick_cube", n_episodes=N_EPS, n_frames=N_FRAMES, seed=7
+    )
+    written = convert_task(str(src), str(out))
+    assert len(written) == N_EPS
+    return written
+
+
+def test_zarr_loads_through_eva_pipeline(zarr_stores):
+    keymap = Eva.get_keymap("cartesian_pi")
+    transform_list = Eva.get_transform_list("cartesian", chunk_length=CHUNK)
+    ds = ZarrDataset(zarr_stores[0], key_map=keymap, transform_list=transform_list)
+
+    assert ds.embodiment == "eva_bimanual"
+    assert len(ds) == N_FRAMES
+
+    for idx in (0, N_FRAMES // 2):
+        sample = ds[idx]
+        # cartesian action chunk: per-arm xyz+ypr (6) + gripper (1) = 7, x2 = 14
+        act = sample["actions_cartesian"]
+        assert tuple(act.shape) == (CHUNK, 14)
+        state = sample["observations.state.ee_pose"]
+        assert state.shape[-1] == 14
+        # PI/PaliGemma camera keys are present and look like images (H, W, 3)
+        for cam in ("base_0_rgb", "left_wrist_0_rgb", "right_wrist_0_rgb"):
+            img = np.asarray(sample[cam])
+            assert img.ndim == 3 and 3 in img.shape
+        assert np.isfinite(np.asarray(act)).all()
+        assert np.isfinite(np.asarray(state)).all()
+
+
+def test_zarr_metadata_and_keys(zarr_stores):
+    import zarr
+
+    store = zarr.open(zarr_stores[0], mode="r")
+    attrs = dict(store.attrs)
+    assert attrs["embodiment"] == "eva_bimanual"
+    assert attrs["total_frames"] == N_FRAMES
+    for key in (
+        "images.front_1",
+        "images.left_wrist",
+        "images.right_wrist",
+        "left.obs_ee_pose",
+        "right.obs_ee_pose",
+        "left.cmd_ee_pose",
+        "right.cmd_ee_pose",
+        "left.obs_gripper",
+        "right.obs_gripper",
+        "left.cmd_gripper",
+        "right.cmd_gripper",
+    ):
+        assert key in attrs["features"], f"missing feature {key}"
+    # ee poses are 7-D XYZWXYZ, grippers 1-D
+    assert attrs["features"]["left.obs_ee_pose"]["shape"] == [7]
+    assert attrs["features"]["left.obs_gripper"]["shape"] == [1]
+
+
+def test_missing_endpose_raises(tmp_path):
+    """An episode with only joint_action (no endpose) errors clearly."""
+    ep = str(tmp_path / "noendpose" / "data" / "episode0.hdf5")
+    make_synthetic_robotwin_episode(ep, n_frames=20, with_endpose=False)
+    # sanity: the fixture really has no endpose group
+    with h5py.File(ep, "r") as f:
+        assert "endpose" not in f
+    with pytest.raises(ValueError, match="endpose"):
+        convert_episode(ep, str(tmp_path / "out.zarr"), task_name="noendpose")
diff --git a/egomimic/ricl/tests/robotwin_zarr_multidataset_test.py b/egomimic/ricl/tests/robotwin_zarr_multidataset_test.py
new file mode 100644
index 000000000..2b5ee7337
--- /dev/null
+++ b/egomimic/ricl/tests/robotwin_zarr_multidataset_test.py
@@ -0,0 +1,133 @@
+"""End-to-end test of the RoboTwin Zarr reusable-corpus path.
+
+Converts a synthetic RoboTwin task to Zarr, then loads it through the *standard*
+EgoVerse data pipeline — `LocalEpisodeResolver` + `MultiDataset._from_resolver` +
+`Eva` keymap/transform (no SQL/S3) — and replicates `trainHydra.py`'s
+norm-stats wiring (populate -> infer -> cache -> set_norm_stats_from). This proves the
+converted stores are a loadable `eva_bimanual` cartesian corpus and that the
+`data/robotwin_local.yaml` recipe works, a stronger check than the single-episode
+`ZarrDataset` test in `robotwin_to_zarr_test.py`.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from egomimic.ricl.scripts.download_robotwin import make_synthetic_robotwin_task
+from egomimic.ricl.scripts.robotwin_to_zarr import convert_task
+from egomimic.rldb.embodiment.embodiment import get_embodiment_id
+from egomimic.rldb.embodiment.eva import Eva
+from egomimic.rldb.filters import DatasetFilter
+from egomimic.rldb.zarr.zarr_dataset_multi import LocalEpisodeResolver, MultiDataset
+
+CHUNK = 15
+N_EPS = 3
+N_FRAMES = 60
+
+
+@pytest.fixture(scope="module")
+def zarr_dir(tmp_path_factory):
+    src = tmp_path_factory.mktemp("rt_md_src")
+    out = tmp_path_factory.mktemp("rt_md_zarr")
+    make_synthetic_robotwin_task(
+        str(src), task="pick_cube", n_episodes=N_EPS, n_frames=N_FRAMES, seed=3
+    )
+    convert_task(str(src), str(out))
+    return str(out)
+
+
+def _make_dataset(zarr_dir: str, *, norm_mode_keymap: bool):
+    """Build a MultiDataset over the local zarr dir (mirrors data/robotwin_local.yaml).
+
+    ``norm_mode_keymap`` drops camera/annotation keys (what trainHydra feeds to
+    norm-stats inference)."""
+    resolver = LocalEpisodeResolver(
+        folder_path=Path(zarr_dir),
+        key_map=Eva.get_keymap("cartesian_pi", norm_mode=norm_mode_keymap),
+        transform_list=Eva.get_transform_list("cartesian", chunk_length=CHUNK),
+    )
+    return MultiDataset._from_resolver(
+        resolver,
+        filters=DatasetFilter(filter_lambdas=[]),
+        mode="total",
+        norm_mode="quantile",
+    )
+
+
+def test_multidataset_loads_offline(zarr_dir):
+    md = _make_dataset(zarr_dir, norm_mode_keymap=False)
+    assert len(md) == N_EPS * N_FRAMES  # one sample per frame, all episodes kept
+    s = md[0]  # no norm stats set yet -> post-transform sample passes through
+    act = np.asarray(s["actions_cartesian"])
+    state = np.asarray(s["observations.state.ee_pose"])
+    assert act.shape == (CHUNK, 14)
+    assert state.shape[-1] == 14
+    img = np.asarray(s["base_0_rgb"])
+    assert img.ndim == 3 and 3 in img.shape
+    assert s.get("embodiment") == get_embodiment_id("eva_bimanual")
+
+
+def test_norm_stats_inferred_and_cached_offline(zarr_dir, tmp_path):
+    md = _make_dataset(zarr_dir, norm_mode_keymap=False)
+    train_datasets = {"eva_bimanual": md}
+
+    # Replicate trainHydra.py's norm-stats wiring (stats-only MultiDataset).
+    norm_stats = MultiDataset(state={}, norm_mode="quantile")
+    norm_stats.populate_from_datasets(train_datasets)
+    norm_stats.infer_shapes_from_batch(md[0])
+    norm_dataset = _make_dataset(zarr_dir, norm_mode_keymap=True)
+    norm_stats.infer_norm_from_dataset(
+        norm_dataset,
+        "eva_bimanual",
+        sample_frac=1.0,
+        num_workers=0,  # single-process for a deterministic test
+    )
+    save_dir = str(tmp_path / "stats")
+    norm_stats.cache_stats(save_cache_dir=save_dir)
+
+    # norm_stats.json written with stats for the eva_bimanual embodiment id
+    out_path = os.path.join(save_dir, "norm_stats", "norm_stats.json")
+    assert os.path.isfile(out_path)
+    with open(out_path) as f:
+        payload = json.load(f)
+    emb_id = get_embodiment_id("eva_bimanual")
+    assert str(emb_id) in payload["stats"]
+    assert payload["stats"][str(emb_id)], "no per-key stats computed"
+
+    # After wiring stats by reference, samples are normalized but keep their shape.
+    md.set_norm_stats_from(norm_stats)
+    s = md[0]
+    assert np.asarray(s["actions_cartesian"]).shape == (CHUNK, 14)
+    assert np.isfinite(np.asarray(s["observations.state.ee_pose"])).all()
+
+
+def test_hydra_config_instantiates(zarr_dir):
+    """`data/robotwin_local.yaml`'s dataset node instantiates over the local zarr
+    (guards the config's _target_s / arg names against drift)."""
+    import hydra
+    from omegaconf import OmegaConf
+
+    import egomimic
+
+    cfg_path = os.path.join(
+        os.path.dirname(egomimic.__file__),
+        "hydra_configs",
+        "data",
+        "robotwin_local.yaml",
+    )
+    cfg = OmegaConf.load(cfg_path)
+    node = cfg.train_datasets.eva_bimanual
+    node.resolver.folder_path = zarr_dir  # override ${paths.dataset_dir}
+    md = hydra.utils.instantiate(node)
+    assert isinstance(md, MultiDataset)
+    assert len(md) == N_EPS * N_FRAMES
+    s = md[0]
+    assert all(
+        k in s
+        for k in ("actions_cartesian", "observations.state.ee_pose", "base_0_rgb")
+    )
diff --git a/external/RoboTwin b/external/RoboTwin
new file mode 160000
index 000000000..1bfa5312a
--- /dev/null
+++ b/external/RoboTwin
@@ -0,0 +1 @@
+Subproject commit 1bfa5312aab848f265f7231b611468412e61eb6a