Condense the model card and link code, project page and paper

README.md

@@ -1,137 +1,87 @@
 ---
 license: apache-2.0
-tags: [robotics, manipulation, maniskill, trajectory-prediction, imitation-learning]
 library_name: pytorch
+pipeline_tag: robotics
+base_model: JayLee131/TraceGen
+base_model_relation: finetune
+tags:
+  - robotics
+  - manipulation
+  - maniskill
+  - trajectory-prediction
+  - imitation-learning
 ---
 
-# Checkpoints of "Predicted Futures Are Not Enough: Learning Executable Goals for Robot Manipulation" 
+# Predicted Futures Are Not Enough: Learning Executable Goals for Robot Manipulation
 
-This repository holds the weights that produced the reported numbers of the paper *Predicted Futures Are Not Enough: Learning Executable Goals for Robot Manipulation*. The accompanying code, scripts, frozen goal banks and evaluation records are in the code repository `Claire0730/executable-goals`; its `docs/GLOSSARY.md` maps every term of the paper to the identifiers used here. The three Pose-Native Executors and the five privileged teachers are the exact artefacts evaluated for the paper. The three 3D Trace Planner files hold the trained parameters of the evaluated checkpoints: the frozen encoder tensors, which were bitwise identical to the Hugging Face Hub weights, and the optimizer and gradient-scaler state were removed for redistribution (see Summary); nothing has been re-trained, and the reduced files reproduce the production predictions bitwise (checked on 16 scenes). SHA-256 digests of all weight files are in `SHA256SUMS`. This repository also carries `banks/`: the 49 frozen goal banks (58 MB) that let the code reproduce the paper's main table without running a planner -- they are data rather than code, so they live here beside the weights, with their own `banks/SHA256SUMS`.
+[Code](https://github.com/Claire0730/executable-goals) · [Project page](https://claire0730.github.io/executable-goals/) · Paper (arXiv, soon)
 
-## Summary
+Weights and frozen goal banks behind the paper. A 3D trace world model predicts one future per episode; the
+**Entity-Level Goal Readout** turns that prediction into a single executable goal in SE(3), and a shared
+**Pose-Native Executor** runs it closed loop at 20 Hz across five ManiSkill3 tasks.
 
-The release contains three groups of weights.
+## What is here
 
-**3D Trace Planner (three fine-tunes of TraceGen).** Each file holds the trained parameters of one fine-tuned planner (about 0.30 GB for `mix4_realcam_n2400`, 0.31 GB for each of the two `mix5` files): the flow decoder, the vision fusion layer, the Entity-Level Goal Readout (entity branch, and the map branch where present) and the depth mask token. The frozen encoders (DINOv3 ViT-L/16 `timm/vit_large_patch16_dinov3.lvd1689m`, SigLIP-B/16-384 `google/siglip-base-patch16-384` and its copy used as the depth encoder, T5-base; about 2.5 GB per file) are not included: every one of their tensors was bitwise identical to the Hub weights, so the upstream trainer built by `msgen.predict` re-creates them from the Hub at model construction and loads the checkpoint with `strict=False`. Optimizer and gradient-scaler state were removed as well. Loading a planner therefore requires the Hub weights; DINOv3 is gated, so its licence must be accepted on Hugging Face and `hf auth login` run once, for inference as well as for training. All three are fine-tuned from the upstream TraceGen "Generalist" checkpoint (Apache-2.0) on replays of the official ManiSkill3 demonstrations rendered under a fixed front camera with a wall backdrop.
+| Folder | Contents | Size |
+|---|---|---|
+| `planner/` | Three 3D Trace Planners fine-tuned from TraceGen: `mix4_realcam_n2400` (Rigid Readout source), `mix5_t2k_n3000` (entity branch), `mix5_t2k_gmap` (entity + map branch) | 0.30–0.31 GB each |
+| `student/` | The three Pose-Native Executors, 804,002 parameters each: `mt5_rciid_gmpc_s0`, `mt5_rcfz_gmpc_s0`, `mt5_rcfz_t2k_s0` | 3.2 MB each |
+| `teacher/` | Five privileged PPO teachers, one per task | ~4 MB each |
+| `banks/` | 49 frozen goal banks — one SE(3) goal per scene, for every reported row, task and evaluation seed | 58 MB |
 
-- `planner/mix4_realcam_n2400.pth` — the Rigid Readout source. K = 4 stochastic trace predictions are drawn per scene, averaged, and passed through a Kabsch fit inside RANSAC (K = 1 uses one prediction); this supplies the Rigid Readout K = 1 / K = 4 goal banks of Table II and the rotation of every composed goal except PushCube's. It is also the warm start of the other two planners and the source of the psi banks.
-- `planner/mix5_t2k_n3000.pth` — the entity branch of the Entity-Level Goal Readout (`MSGEN_T2K=1`). It supplies the full terminal pose for PegInsertionSide and the terminal position for LiftPegUpright and PushCube, and serves as the Rigid Readout source for PushCube.
-- `planner/mix5_t2k_gmap.pth` — entity branch plus map branch / Spatial Goal Map (`MSGEN_T2K=1 MSGEN_T2K_GMAP=1`). It supplies the terminal position of PickCube (map peak plus ray, bank suffix `gmappeakNC`; with the SAM 2 marker localiser prompted at the map peak, `sam2mk6`) and StackCube (weighted depth-centroid readout, `gmapdcc`).
+Digests: `SHA256SUMS` (weights) and `banks/SHA256SUMS`.
 
-The parameter counts of the full models are 674,546,334 for backbone plus decoder (75,486,238 trainable) and 677,596,675 with the Entity-Level Goal Readout (78,536,579 trainable; the paper's 677.6M); roughly 89 % of each model consists of the frozen encoders, which are not part of the released files. At batch size 1 with 20 fixed-step Euler steps on an RTX 5090 the forward pass takes 0.253-0.278 s per scene; the production `mix4` predictions use the native 100-step sampler, whose latency is not recorded, and the 1.27 s / 5.60 GB of the paper's Table III are not backed by a record in the release (code repository, `docs/KNOWN_ISSUES.md` item 19).
+## Use
 
-**Pose-Native Executors (three).** `student/<tag>/student.pt` are the multi-task executors of the paper: one 804,002-parameter policy each for PickCube, LiftPegUpright, PegInsertionSide, StackCube and PushCube, distilled with DAgger from the five teachers below with goal perturbations drawn from the measured planner error distribution (relbanks). The 60-dimensional observation is pose-based (joint positions and velocities, tool-centre-point pose, previous action, the object pose fitted from 64 perceived points, the executable goal, their relative pose and a 4-dimensional psi token); there is no scene channel and no language input; the goal is fixed for the episode. The three differ only in the distillation-time injection of the goal perturbation and, for the earliest one, in the relbanks (`docs/KNOWN_ISSUES.md` item 15 of the code repository):
+Reproducing the main table needs the executors and the banks only — no planner, no gated licence, one GPU:
 
-- `student/mt5_rciid_gmpc_s0/student.pt` — the executor of the **Entity-Level Goal Readout row of Table II**; per-step i.i.d. redraw of the goal perturbation (`msppo/patch_iid_inject.py`, `MSPPO_IID_INJECT=1`).
-- `student/mt5_rcfz_gmpc_s0/student.pt` — the executor of the **Rigid Readout K = 1 and K = 4 rows, the Oracle Goal references (Fig. 5a) and the Fig. 7 perturbation curves**; one goal-perturbation draw per episode, frozen (`msppo/patch_frozen_inject.py`, `MSPPO_FROZEN_INJECT=1`). Same relbanks as `mt5_rciid_gmpc_s0`.
-- `student/mt5_rcfz_t2k_s0/student.pt` — an earlier executor (episode-fixed injection, `t2kdcc` relbanks for all five tasks) that produced the **PickCube cell of the Rigid Readout K = 4 row only** (46.48, seed 999, goal bank `pickcube_goals_mix5_t2k_n3000_999_k4ransac.npz`).
-
-**Privileged teachers (five single-task PPO policies).** `teacher/<tag>/agent.pt` are the final PPO agents (`msppo.kp_teacher`, about 1.0 M parameters each) that receive the privileged guidance variable psi and from which the executors were distilled: `pc_v9_nz_s0` (PickCube-v1), `lp_v9_nz_s0` (LiftPegUpright-v1), `pi_v9_frame4_s0` (PegInsertionSide-v1), `sc_v9_nz03b_s0` (StackCube-v1, `panda_wristcam` robot variant) and `push_v9_nz_s0` (PushCube-v1).
-
-**Not included.** The upstream TraceGen code and its Generalist checkpoint (obtain them from the upstream repository at the commit pinned in `Claire0730/executable-goals/third_party/TRACEGEN_COMMIT`), the frozen encoder weights (not redistributed; fetched by `timm` / `transformers` from the Hub whenever a planner is built, for inference as well as training; DINOv3 requires accepting its licence on the Hugging Face Hub and an authenticated `hf` session), the ManiSkill demonstration packages, and the third-party perception weights SAM 2 (needed only by the optional `scripts/31_goals_sam2marker.sh`, which regenerates the `sam2mk6` PickCube bank; the frozen banks are shipped with the code) and CoTracker3 (the online-tracking loop of the paper is not part of the release).
-
-## Files
-
-| Path | Role | Training data and recipe | Warm start | SHA-256 (first 16 hex) |
-|---|---|---|---|---|
-| `planner/mix4_realcam_n2400.pth` (302,007,919 B) | Rigid Readout source and rotation source: K = 4 trace mean + RANSAC Kabsch for PickCube, LiftPegUpright, PegInsertionSide, StackCube; K = 1 / K = 4 goal banks; psi banks; warm start of the two readout planners | `data/ds/realcam_n2400`: four tasks (PickCube, StackCube, PegInsertionSide, LiftPegUpright), 200 official demos x 3 camera views each, wall backdrop, dense 3D traces with 16 object-aware queries; `msgen.run_train`, 15 epochs, batch 8, `lr_decoder` 1.5e-4; no `MSGEN_*` variable recorded | TraceGen Generalist `tracegen_model.pth` (SHA-256 `f595ad249cbd59ce`) | `81f25468df5de89f` |
-| `planner/mix5_t2k_n3000.pth` (314,213,705 B) | Entity branch: PegInsertionSide full pose; LiftPegUpright and PushCube position; PushCube Rigid Readout source | `data/ds/realcam_t2k_n3000`: five tasks (the four above plus PushCube), same replays, plus entity-level labels (`msgen.labels_t2k`); 8 epochs, batch 8, `lr_decoder` 1.5e-4, `MSGEN_T2K=1 MSGEN_T2K_W=0.3`; code git `ba7de4d2` | `mix4_realcam_n2400` final | `6b5b6544a0b7b502` |
-| `planner/mix5_t2k_gmap.pth` (314,217,163 B) | Entity branch + map branch (Spatial Goal Map): PickCube (`gmappeakNC`, `sam2mk6`) and StackCube (`gmapdcc`) goal positions | `data/ds/realcam_t2k_n3000` with goal-map labels **v1** (6 cm hard ball); 8 epochs, batch 8, `lr_decoder` 1.5e-4, `MSGEN_T2K=1 MSGEN_T2K_GMAP=1 MSGEN_T2K_W=0.3 MSGEN_KEEP_ALL_CKPT=1`; code git `ba7de4d2` | `mix4_realcam_n2400` final (not `mix5_t2k_n3000`) | `46643abdd9744d3c` |
-| `student/mt5_rciid_gmpc_s0/{student.pt, run.json}` (student 3,239,060 B) | Pose-Native Executor of the Entity-Level Goal Readout row of Table II; five tasks, 804,002 parameters (`--ckpt final`) | `msppo.multi_distill` (DAgger) from the five teachers below; 40,000 iterations, 320 envs (64 per task), lr 3e-4, seed 0, no scene channel, psi token, goal = K = 4 mean, goal perturbation redrawn i.i.d. at every control step (`MSPPO_IID_INJECT=1`, uniform scale) from the relbanks StackCube `gmapdcc`, PickCube `gmappeak`, others `t2kdcc`; trained 2026-09-13 | not recorded (no warm-start field in `run.json`) | `5ed8f4361eb6a676` |
-| `student/mt5_rcfz_gmpc_s0/{student.pt, run.json}` (student 3,239,060 B) | Pose-Native Executor of the Rigid Readout rows, the Oracle Goal references and Fig. 7 | same as above with one goal-perturbation draw per episode, frozen (`MSPPO_FROZEN_INJECT=1`, uniform scale); trained 2026-09-07 | not recorded | `50467d34909e0d82` |
-| `student/mt5_rcfz_t2k_s0/{student.pt, run.json}` (student 3,239,060 B) | Earlier Pose-Native Executor; the PickCube cell of the Rigid Readout K = 4 row (seed 999) | same recipe with episode-fixed injection and `t2kdcc` relbanks for all five tasks (its PickCube and StackCube relbanks are not shipped); trained 2026-09-01 | not recorded | `99aaa1f6eb50ac93` |
-| `teacher/pc_v9_nz_s0/{agent.pt, run.json, patches.json}` (agent 4,052,398 B) | PickCube-v1 privileged PPO teacher, 1,011,473 parameters | `msppo.kp_teacher`; 12,000,000 steps, 1024 envs, lr 5e-5, `target_kl` 0.01, noise-v2 injector (`noise_v2` 0.4, `obj_v2` 1.0); patch `msppo/patch_frame.py` with `MSPPO_FRAME_WPUSH=0.25` | `runs_rl/pc_v9_frame4_s0_padsig` (not released) | `702259e46a7ce08b` |
-| `teacher/lp_v9_nz_s0/{agent.pt, run.json, patches.json}` (agent 4,011,438 B) | LiftPegUpright-v1 privileged PPO teacher, 1,001,233 parameters | 12,000,000 steps, 256 envs, lr 5e-5, `target_kl` 0.01, `noise_v2` 1.0, `obj_v2` 1.0; patch `msppo/patch_frame.py` | `runs_rl/lp_v9_frame_s0_padsig` (not released) | `b3449a618fdf5e21` |
-| `teacher/pi_v9_frame4_s0/{agent.pt, run.json, patches.json}` (agent 4,056,494 B) | PegInsertionSide-v1 privileged PPO teacher (psi-conditioned), 1,012,497 parameters | 8,000,000 steps, 1024 envs, lr 2e-5, `target_kl` 0.005, `max_episode_steps` 100, `noise_v2` 1.0, `obj_v2` 1.0; patch `msppo/patch_frame.py` with `MSPPO_FRAME_WH=0 MSPPO_FRAME_WPUSH=0 MSPPO_FRAME_K1_BASE=-0.28,-0.56,-0.78` | `runs_rl/pi_v5_hi_s0` (not released) | `ef0559ebcfdc9c42` |
-| `teacher/sc_v9_nz03b_s0/{agent.pt, run.json, patches.json}` (agent 3,995,054 B) | StackCube-v1 privileged PPO teacher, `panda_wristcam` robot, 997,137 parameters | 12,000,000 steps, 1024 envs, lr 1e-4, `target_kl` 0.02, `noise_v2` 0.3, `obj_v2` 0.15, bump penalty `w_bump` 0.3, `w_kp` 0.125; patch `msppo/patch_stack_frame.py` | `runs_rl/sc_v9_frame_s0_padsig` (not released) | `fd8ef9911d8e153d` |
-| `teacher/push_v9_nz_s0/{agent.pt, run.json}` (agent 4,023,726 B) | PushCube-v1 privileged PPO teacher, 1,004,305 parameters (this run carries no `patches.json`) | 12,000,000 steps, 1024 envs, lr 5e-5, `target_kl` 0.01, `noise_v2` 1.0, `obj_v2` 1.0 | `runs_rl/push_kp_s0_psipad_padsig` (not released) | `34c0175e65cbe84b` |
-| `SHA256SUMS` | SHA-256 of every weight file above (`sha256sum -c SHA256SUMS`) | — | — | — |
-| `README.md` | This model card | — | — | — |
-
-Every teacher run and every distillation were launched with seed 0; the planner `run.json` files record no seed, and no executor `run.json` records a git revision. The teacher `patches.json` files record the code patch, the environment variables and the code git revision (`ba7de4d2af700d4d4f02a8d2c2f8f8d350751108`, a commit of the private research repository, not resolvable from this release) that were active when the teacher was trained; the same revision is recorded in the provenance block of the two readout planners. `mix4_realcam_n2400/run.json` carries no provenance or git field.
-
-## Intended use and how to load
-
-These weights reproduce the closed-loop tables of the paper inside ManiSkill3 under the production visual protocol (front camera `eye=(0.574,-0.051,0.378)`, `target=(-0.4751,0.0562,0.0200)`, `fov=0.754`, wall backdrop). They are research artefacts for that setting; no other use has been evaluated.
-
-1. Clone the code repository `Claire0730/executable-goals` and set up the two conda environments described in its `requirements/README.md` (`trace_gen`, Python 3.10, for the planner; `maniskill`, Python 3.11, for the simulator, teachers, distillation and evaluation; both frozen at `torch 2.11.0+cu128`). Clone the upstream TraceGen repository at the pinned commit and apply `third_party/tracegen_local.patch` as described in `third_party/README.md`.
-2. Download this repository and expose the weights under the layout the code expects:
-
-   ```bash
-   hf download Claire0730/executable-goals --local-dir checkpoints
-   bash scripts/00_link_checkpoints.sh
-   ```
-
-   `00_link_checkpoints.sh` symlinks `checkpoints/student/*` (the three executors) and `checkpoints/teacher/*` to `runs_rl/<tag>`, checks that the three planner files named by `CK_MIX4`, `CK_HEAD` and `CK_GMAP` in `scripts/config.sh` exist, and runs `sha256sum -c SHA256SUMS`.
-3. **Planners** are loaded through `msgen.predict` by path (`--ckpt checkpoints/planner/<tag>.pth`). The readout that is active is selected by environment variables, not by the file: `mix5_t2k_n3000.pth` must be run with `MSGEN_T2K=1`, `mix5_t2k_gmap.pth` with `MSGEN_T2K=1 MSGEN_T2K_GMAP=1`, and `mix4_realcam_n2400.pth` without either flag. The sampler differs per prediction family, as in production: the four-task `mix4` K = 4 Rigid Readout source uses the native TraceGen sampler (no `MSGEN_STEPS`), whereas the entity-branch, map-branch and PushCube K = 4 predictions use `MSGEN_STEPS=20 MSGEN_DT=fix`. The wall and camera variables are not passed to the planner process; they affect rendering only. The K = 4 Rigid Readout uses the flow-sampler seeds 1234-1237; the readouts use seed 1234 (for PushCube the seed-1234 K-sample file is also the entity-branch file). Because the encoders are re-created from the Hub, the planner process needs the authenticated Hugging Face session described above. `scripts/20_predict.sh` encodes this procedure.
-4. **Executors and teachers** are not self-describing: the network is rebuilt from the `run.json` next to each weight file (executor: `d_model`, `layers`, `heads`, observation layout `student_recon`, `num_kp` 64, `qdim` 9, `tcp_obs`, `pose_obs`, `psi`/`psi_token`, `no_scene`; teacher: `token_dim` 128, `hidden` 1024,1024,512,512, `pn_hidden` 128,128, `obs_dim`, `qdim` 9, `num_kp` 64). `msppo.multi_eval --run runs_rl/<executor tag> --ckpt final` loads an executor; `msppo.multi_distill --teachers <tag,...>` loads `runs_rl/<tag>/{agent.pt, run.json}` for the teachers. The teacher `patches.json` names the code patch (`msppo/patch_frame.py` or `msppo/patch_stack_frame.py`) and the environment variables that must be active before the environment is built.
-5. To reproduce a row of Table II from the frozen goal banks shipped in `Claire0730/executable-goals/banks/` without running a planner, use `ROW=final|k1|k4|k4pick|oracle bash scripts/verify_main_table.sh [seed]` (it selects the executor of that row); to regenerate the banks from the planners, run `scripts/10_render_banks.sh`, `20_predict.sh`, `30_goals.sh`, optionally `31_goals_sam2marker.sh` (SAM 2), and `40_eval_row4.sh`.
-
-## Evaluation results
-
-Protocol: `msppo.multi_eval`, N = 256 episodes per task and evaluation seed, training seed 0, `--ckpt final`, metric `success_once`, production camera and wall, psi banks derived from `mix4_realcam_n2400` predictions, the simulator's per-step object correspondence for the executor's pose feedback. The paper pools the evaluation seeds 999, 997 and 998 (768 episodes per task). Values are success rates in percent in the task order PickCube / LiftPegUpright / PegInsertionSide / StackCube / PushCube; "printed" is the value in the paper, "recorded" the mean over the three seeds of the `per_task` field of the records in `Claire0730/executable-goals/paper_results/table2/`. Where printed and recorded values differ by at most 0.08 percentage points, the difference is rounding of the printed values.
-
-| Table II row | Executor | Goal banks | Printed | Recorded (pooled) | Records |
-|---|---|---|---|---|---|
-| Rigid Readout K = 1 | `mt5_rcfz_gmpc_s0` | `k1ransac` (PushCube from `mix5_t2k_n3000`) | 29.80 / 70.18 / 20.05 / 52.47 / 99.74 (mean 54.45) | 29.82 / 70.18 / 20.05 / 52.47 / 99.74 (mean 54.45) | `rigid_k1_gmpc_<seed>.json` |
-| Rigid Readout K = 4 | `mt5_rcfz_gmpc_s0`; PickCube cell `mt5_rcfz_t2k_s0` (seed 999) | `kmean_ransac`; PickCube cell `pickcube_goals_mix5_t2k_n3000_999_k4ransac.npz` | 46.48 / 76.95 / 21.88 / 54.82 / 99.22 (mean 59.87) | 33.07 / 76.95 / 21.88 / 54.82 / 99.22 with `mt5_rcfz_gmpc_s0`; the printed PickCube cell 46.48 (119 of 256) is the single-seed record of `mt5_rcfz_t2k_s0` | `rigid_k4_gmpc_<seed>.json`, `rigid_k4_pickcube_t2k_s0_999.json` |
-| Entity-Level Goal Readout | `mt5_rciid_gmpc_s0` | PickCube `sam2mk6`, StackCube `gmapdcc`, others `t2kpos` | 81.50 / 98.35 / 32.84 / 86.54 / 99.20 (mean 79.69) | 81.51 / 98.31 / 32.81 / 86.46 / 99.22 (mean 79.66) | `final_pickcube_sam2_rciid_<seed>.json`, `final_rciid_<seed>.json` |
-| Oracle Goal (Fig. 5a) | `mt5_rcfz_gmpc_s0` | simulator goal | 94.66 / 97.27 / 36.72 / 87.11 / 99.74 | 94.66 / 97.27 / 36.72 / 87.11 / 99.74 | `oracle_gmpc_<seed>.json` |
-
-Per seed (999 / 997 / 998): Rigid K = 1 30.86 / 68.36 / 17.58 / 52.34 / 100.00, 32.42 / 71.88 / 18.75 / 51.56 / 99.22, 26.17 / 70.31 / 23.83 / 53.52 / 100.00; Rigid K = 4 (`mt5_rcfz_gmpc_s0`) 30.47 / 78.52 / 18.36 / 53.91 / 100.00, 39.06 / 76.95 / 23.83 / 53.91 / 99.22, 29.69 / 75.39 / 23.44 / 56.64 / 98.44; Entity-Level Goal Readout 84.38 / 98.05 / 36.72 / 88.28 / 99.61, 80.86 / 98.44 / 29.30 / 86.33 / 99.22, 79.30 / 98.44 / 32.42 / 84.77 / 98.83; Oracle Goal 93.75 / 96.88 / 37.11 / 88.28 / 100.00, 94.53 / 98.44 / 32.81 / 86.72 / 99.61, 95.70 / 96.48 / 40.23 / 86.33 / 99.61. The Fig. 7 curves (Oracle Goal translated by 0 to 120 mm, `mt5_rcfz_gmpc_s0`, seeds 999 and 997) are in `paper_results/fig7_perturbation/`. Not in the paper: the final routing with PickCube `gmappeakNC` evaluated with `mt5_rcfz_gmpc_s0` gives 70.31 / 96.35 / 30.34 / 82.94 / 100.00 pooled (`paper_results/supplementary/final_routing_gmpc_<seed>.json`).
-
-Table I (terminal goal position error, mm, mean +- sd, seed 999, 256 scenes; PickCube / PegInsertionSide / StackCube) and Fig. 6 are goal-bank statistics of the planners, recorded in `Claire0730/executable-goals/evidence/04_goal_summary.json` (`mean_all_finite`, `sd_all_finite`) and `evidence/goal_table.json` (median / 90th percentile): Rigid Readout K = 1 41.1 +- 21.7 / 42.6 +- 31.6 / 28.9 +- 38.7 (`rigid_K1_ransac|<task>|999`); Rigid Readout K = 4 37.2 +- 19.3 / 40.8 +- 33.0 / 25.4 +- 38.8 (`rigid_K4_ransac|<task>|999`); Entity-Level Goal Readout 31.5 +- 20.1 / 29.4 +- 16.4 / 12.8 +- 34.0 (`final_pick_gmappeakNC|pickcube|999`, `t2k_head_full|peginsert|999`, `final_stack_gmapdcc|stack|999`). The PickCube error of Table I is measured on the `gmappeakNC` bank, whereas the PickCube success of Table II is measured on the `sam2mk6` bank.
-
-Planner cost, measured on the planner models built from these checkpoints (batch 1, 20 ODE steps, `MSGEN_STEPS=20 MSGEN_DT=fix`, RTX 5090). The `mix4` row is a like-for-like measurement at 20 steps; the production `mix4` predictions run the native 100-step sampler, whose cost is not recorded:
-
-| Checkpoint | Parameters (total / trainable) | s per scene | TFLOPs per scene | Peak VRAM |
-|---|---|---|---|---|
-| `mix4_realcam_n2400.pth` | 674,546,334 / 75,486,238 | 0.253 | 4.51 | 2.62 GiB |
-| `mix5_t2k_gmap.pth` | 677,596,675 / 78,536,579 | 0.277 | 5.06 | 2.63 GiB |
-| `mix5_t2k_n3000.pth` | 677,595,906 / 78,535,810 | 0.278 | 5.06 | 2.63 GiB |
-
-A timing of the full K = 4 planning call (four forward passes plus the readout pass and the Rigid Readout) was not recorded; the 1.27 s and 5.60 GB of the paper's Table III do not correspond to these measurements and are not backed by a record in the release.
-
-## Training summary
-
-**Planner data.** The 200 official ManiSkill demonstrations of each task are replayed under the production camera in three views (nominal, and two jittered views with eye offsets +-(0.02, 0.02, 0.01) m and target offsets +-(0.04, 0.03, 0) m, about +-2-3 degrees of re-aim) with the wall backdrop, and labelled with dense 3D traces on 16 object-aware queries (`msgen.labels --n-obj 16 --stride 2 --min-future 8 --time-mode arclen`). `realcam_n2400` indexes the four tasks without PushCube (4 x 200 x 3 = 2,400 clips); `realcam_t2k_n3000` indexes all five tasks (3,000 clips) and additionally carries the entity-level labels written by `msgen.labels_t2k` (keyframes, per-segment twists, contact descriptor, structure-relative terminal pose, entity membership of the 400 queries, goal-map target).
+```bash
+git clone https://github.com/Claire0730/executable-goals && cd executable-goals
+hf download Claire0730/executable-goals --local-dir checkpoints --include "student/*" --include "teacher/*" --include "SHA256SUMS"
+hf download Claire0730/executable-goals --local-dir . --include "banks/*"
+bash scripts/00_link_checkpoints.sh
+ROW=final bash scripts/verify_main_table.sh 999
+```
 
-**Planner fine-tuning.** All three runs use batch size 8, `lr_decoder` 1.5e-4 in a single parameter group with weight decay 0.05, no learning-rate schedule, gradient clipping at norm 1.0 and mixed precision. The encoders (DINOv3 ViT-L/16, SigLIP, T5, depth encoder) are frozen apart from a few thousand adapter parameters each; the vision fusion, the flow decoder and, where present, the Entity-Level Goal Readout (`T2KHead(D=768, hidden=256, pos_in=4)`, 3,050,341 parameters in the map-branch checkpoint, initialised from scratch) are trained with the loss `L = L_flow + lambda_ent L_ent + lambda_map L_map` (`MSGEN_T2K_W=0.3`). `mix4_realcam_n2400`: 15 epochs from the Generalist checkpoint. `mix5_t2k_n3000`: 8 epochs from `mix4_realcam_n2400` with `MSGEN_T2K=1 MSGEN_T2K_W=0.3`. `mix5_t2k_gmap`: 8 epochs from `mix4_realcam_n2400` with `MSGEN_T2K=1 MSGEN_T2K_GMAP=1 MSGEN_T2K_W=0.3`. No `MSGEN_WALL` or camera variable was set in the training processes (the `mix5` `patches.json` files record `wall: false`; the `mix4` run recorded no `MSGEN_*` variable): the wall is a property of the rendered clips. Approximate wall-clock on one RTX 5090 as noted in the training script: 10 h, 6 h and 6 h.
+Everything else — the full install, the inference and training chains, which record backs which number — is in the
+code repository's README and `docs/REPRODUCTION.md`.
 
-**Teachers.** Single-task PPO (`msppo.kp_teacher`) on keypoint observations (64 keypoints, `qdim` 9) with the privileged guidance variable psi, control `pd_joint_delta_pos`, rollout length 50, 8 PPO epochs, 32 minibatches, gamma = 0.8, GAE lambda = 0.9, network `token_dim` 128 / `hidden` 1024,1024,512,512 / `pn_hidden` 128,128, observation-noise injector "noise-v2" with the true noise-scale block as an observation (`sig_obs`), `ignore_terminations` on except for StackCube. Per-task budgets:
+## Results
 
-| Teacher | Environment | Robot | Total steps | `num_envs` | lr | `target_kl` | `max_episode_steps` | Warm start (`init_from`) |
-|---|---|---|---|---|---|---|---|---|
-| `pc_v9_nz_s0` | PickCube-v1 | panda | 12,000,000 | 1024 | 5e-5 | 0.01 | 50 | `pc_v9_frame4_s0_padsig` |
-| `lp_v9_nz_s0` | LiftPegUpright-v1 | panda | 12,000,000 | 256 | 5e-5 | 0.01 | 50 | `lp_v9_frame_s0_padsig` |
-| `pi_v9_frame4_s0` | PegInsertionSide-v1 | panda | 8,000,000 | 1024 | 2e-5 | 0.005 | 100 | `pi_v5_hi_s0` |
-| `sc_v9_nz03b_s0` | StackCube-v1 | panda_wristcam | 12,000,000 | 1024 | 1e-4 | 0.02 | 50 | `sc_v9_frame_s0_padsig` |
-| `push_v9_nz_s0` | PushCube-v1 | panda | 12,000,000 | 1024 | 5e-5 | 0.01 | 50 | `push_kp_s0_psipad_padsig` |
+Closed-loop success, %, PickCube / LiftPegUpright / PegInsertionSide / StackCube / PushCube. The readout rows share
+one set of executor weights; only the goal pipeline differs. "Recorded" pools evaluation seeds 999 / 997 / 998
+(768 episodes per task).
 
-The `patches.json` of each teacher records the environment of its psi-reward patch: `MSPPO_FRAME_WPUSH=0.25` for `pc_v9_nz_s0`; `MSPPO_FRAME_WH=0 MSPPO_FRAME_WPUSH=0 MSPPO_FRAME_K1_BASE=-0.28,-0.56,-0.78` for `pi_v9_frame4_s0`; no reward-weight override for `lp_v9_nz_s0` and `sc_v9_nz03b_s0`; `push_v9_nz_s0` has no `patches.json`. `scripts/60_train_teachers.sh` exports this environment together with the flags generated from `run.json`.
+| Row | Executor | Printed | Recorded |
+|---|---|---|---|
+| Rigid Readout K = 1 | `mt5_rcfz_gmpc_s0` | 29.80 / 70.18 / 20.05 / 52.47 / 99.74 (mean 54.45) | 29.82 / 70.18 / 20.05 / 52.47 / 99.74 |
+| Rigid Readout K = 4 | `mt5_rcfz_gmpc_s0`, PickCube cell `mt5_rcfz_t2k_s0` | 46.48 / 76.95 / 21.88 / 54.82 / 99.22 (mean 59.87) | 33.07 / 76.95 / 21.88 / 54.82 / 99.22 with one executor; the printed PickCube cell is the second, at seed 999 |
+| **Entity-Level Goal Readout** | `mt5_rciid_gmpc_s0` | **81.50 / 98.35 / 32.84 / 86.54 / 99.20 (mean 79.69)** | 81.51 / 98.31 / 32.81 / 86.46 / 99.22 |
+| Oracle Goal | `mt5_rcfz_gmpc_s0` | 94.66 / 97.27 / 36.72 / 87.11 / 99.74 | identical |
 
-**Executor distillation.** `msppo.multi_distill` (DAgger) over the five tasks with the five teachers above: 40,000 iterations, 320 parallel environments (64 per task), lr 3e-4, seed 0, transformer `d_model` 128 / 4 layers / 4 heads, 804,002 parameters, observation `student_recon` (object pose fitted from 64 perceived points, `qdim` 9, proprioception and TCP, psi token; no scene channel, no language), goal form K = 4 mean, keypoint mask ratio 2 and keypoint noise 0.005 m. Goal perturbations are injected from the measured planner error distribution: for each task a relbank of goal errors measured for the goal source it is deployed with (StackCube `gmapdcc`, PickCube `gmappeak`, LiftPegUpright / PegInsertionSide / PushCube `t2kdcc` for `mt5_rciid_gmpc_s0` and `mt5_rcfz_gmpc_s0`; `t2kdcc` for all five tasks for `mt5_rcfz_t2k_s0`), with a per-draw scale uniform in (0, 1); no warm-up or curriculum. `mt5_rciid_gmpc_s0` redraws the perturbation i.i.d. at every control step (`MSPPO_IID_INJECT=1`, pool of 64 draws expanded once per episode); `mt5_rcfz_gmpc_s0` and `mt5_rcfz_t2k_s0` draw once per episode and hold it (`MSPPO_FROZEN_INJECT=1`). The environment patches (wall and production camera) are identical to those used in evaluation. Approximate wall-clock as noted in the distillation script: 6 h on one RTX 5090. `scripts/70_distill.sh` reproduces the first two recipes (`INJECT=iid|frozen`); the relbanks of `mt5_rcfz_t2k_s0` for PickCube and StackCube are not shipped.
+Terminal goal position error (mm, seed 999, PickCube / PegInsertionSide / StackCube): Rigid K = 1 41.1 / 42.6 / 28.9,
+Rigid K = 4 37.2 / 40.8 / 25.4, Entity-Level Goal Readout 31.5 / 29.4 / 12.8.
 
-## Limitations
+## Before you rely on these
 
-- **Three executors behind Table II.** The Entity-Level Goal Readout row was evaluated with `mt5_rciid_gmpc_s0`, the Rigid Readout rows and the Oracle Goal references with `mt5_rcfz_gmpc_s0`, and the printed PickCube cell of the Rigid Readout K = 4 row (46.48) with `mt5_rcfz_t2k_s0` at seed 999 on the `mix5_t2k_n3000` K = 4 bank; with `mt5_rcfz_gmpc_s0` and the `mix4_realcam_n2400` K = 4 banks that cell is 33.07 pooled.
-- **Two PickCube banks.** The Table I PickCube error (31.5 mm) is measured on the `gmappeakNC` bank; the Table II PickCube success (81.50) on the `sam2mk6` bank (SAM 2 marker localiser at the map peak; 227 / 216 / 218 of 256 scenes applied at seeds 999 / 997 / 998, the rest keeping the `gmappeakNC` goal).
-- **psi token.** Every released executor consumes a 4-dimensional psi token (task-constant approach axis and the carry height read from the predicted trace, `tools/psi_bank.py`, `tools/psinat.py`) as part of its 60-dimensional observation (`psi: true`, `psi_token: true` in `run.json`).
-- **Simulator correspondence.** The Table II records use the simulator's per-step object correspondence for the executor's pose feedback; the CoTracker3 online-tracking loop of the paper is not part of the release and no record of it is shipped.
-- **Table III timing.** The release's timing records are batch-1, 20-step measurements (0.253-0.278 s per scene, RTX 5090); the production `mix4` predictions use the native sampler, whose latency is not recorded; the 1.27 s and 5.60 GB of Table III are not backed by a shipped record.
-- **Printed versus recorded values.** Apart from the PickCube K = 4 cell, the printed Table II values differ from the pooled records by at most 0.08 percentage points (rounding of the printed values); the per-seed values are listed above.
-- **Goal-map labels v1 vs v2.** `mix5_t2k_gmap.pth` was trained on goal-map labels v1 (uniform weight inside a 6 cm ball). The label writer `msgen.labels_t2k` in the code repository now produces v2 (Gaussian weighting, sigma = 2 cm, cut at 6 cm), so a re-run of `scripts/52_train_planner.sh gmap` is not bitwise comparable to the released file; the v1 labels no longer exist on disk and are not part of any release.
-- **Teacher lineage.** Each released teacher was warm-started from an earlier PPO run (`init_from` in its `run.json`) that is not part of this release. `scripts/60_train_teachers.sh` trains from scratch with the same recipe and step budget; it is expected to reach a similar success level but not the same weights, and a distilled executor would in turn differ.
-- **Simulation only.** Every number above is a ManiSkill3 closed-loop result under one fixed camera, one wall backdrop and one training seed (0) for each executor and teacher; the real-robot results of the paper (Table IV) are not established for these checkpoints by this release.
-- **PegInsertionSide is not bitwise reproducible.** Two evaluations of the same PegInsertionSide checkpoint under identical conditions returned 94/256 and 96/256 successes; the other four tasks reproduce episode by episode. `scripts/verify_main_table.sh` therefore compares against the records with a +-0.04 band.
-- **Relbank seeds.** The goal-perturbation relbanks used during distillation were fit on planner outputs for seeds 990-996 (StackCube, PickCube), 990-997 (LiftPegUpright, PegInsertionSide) and 990-993 (PushCube); seed 997 is also one of the repeat evaluation seeds. The overlap concerns an error distribution, not the scene content of any evaluated episode.
-- **Planner files are parameter-only.** The frozen encoders are not redistributed; a planner cannot be built offline without the Hub weights (DINOv3 gated). `scripts/verify_main_table.sh` does not need the planner files.
-- **Training paths in the planner `config` are placeholders.** The three planner files carry the training run's configuration, whose `data.dataset_dirs`, `data.cache_dir` and `checkpoint_dir` pointed at the authors' machine. Those three strings were replaced with `[path-to-the-repository-root-here]` before release, keeping the relative part (`/data/ds/<dataset>`, `/data/cache`, `/runs/<tag>`). The fields are metadata only: nothing in inference or evaluation reads them, and only the tensor payload was left untouched (every other entry of each `.pth` is byte-identical to the file that was verified). **If you resume training from one of these checkpoints, set them to your own paths first** — the placeholder is not a valid directory. `SHA256SUMS` and the digests above are the post-replacement values.
-- **Records.** `mix4_realcam_n2400/run.json` has no provenance block (no argv or git field); no executor `run.json` has a git field; `teacher/push_v9_nz_s0/` has no `patches.json`.
+- **The planner files hold trained parameters only.** Every frozen-encoder tensor was bitwise identical to the
+  published Hub weights and was removed, along with the optimizer state. The encoders are re-created from the Hub
+  when the planner is built, so **DINOv3 is required and gated**: accept its licence and run `hf auth login` once.
+  `verify_main_table.sh` builds no planner and needs none of this.
+- **Training paths inside the planner `config` are placeholders.** `dataset_dirs`, `cache_dir` and `checkpoint_dir`
+  read `[path-to-the-repository-root-here]/...`. They are metadata — inference and evaluation never read them — but
+  set them to real directories before resuming training.
+- **PegInsertionSide is not bitwise reproducible.** Repeated evaluation of the same checkpoint moves by a couple of
+  episodes in 256, which is why the verification script compares within ±0.04.
+- **Simulation only, one training seed.** The paper's real-robot results are not established for these checkpoints
+  by this release, and the three evaluation seeds vary scenes, not training.
+- Nothing here is a third-party weight. CoTracker3 and SAM 2 are not redistributed; the code repository's README
+  lists every external model, its licence and which stage needs it.
 
-## Citation
+## License and citation
 
-If you use these weights, please cite the paper:
+Apache-2.0. The released weights contain only parameters trained by the authors; the upstream TraceGen Generalist
+checkpoint they are fine-tuned from is subject to its own terms.
 
 ```bibtex
 @article{chuang2026executablegoals,
@@ -140,5 +90,3 @@ If you use these weights, please cite the paper:
   year   = {2026}
 }
 ```
-
-Please also cite the upstream TraceGen work whose Generalist checkpoint is the warm start of every planner released here (see the upstream repository for its reference).