fix(cli): route non-RL scene demos away from the RL play helper (P8/P9)

[KraHsu]

Problem

genelab play GeneLab-Rubiks-Play-v0 --agent zero --steps 5 and the Wuji equivalent crash during env construction. After PR #153 added device to the base cfg, the crash just moved one field along:

AttributeError: 'RubiksEnvCfg' object has no attribute 'decimation'   (was 'device' before #153)

Corrected root cause (architectural, not a missing field)

Rubiks/Wuji are force-driven scene-playback demos. Their cfgs subclass the non-RL base ManagerBasedEnvCfg and have a completely different shape (robot: RubiksRobotCfg, interaction, force_controller, reset_interval — not the RL surface). They run via a dedicated path: RegisteredTask.play() → RubiksPlayEnv.play() / WujiHandPlaybackEnv.play(), which builds a Genesis scene directly (no managers, no policy).

_dispatch_play (cli/_dispatch.py) already routes to task.play() when no RL flags are present — so genelab play GeneLab-Rubiks-Play-v0 with no args works. The bug: RL-only flags (--agent / --checkpoint / --num-envs / --prof) force the fall-through to play_task → build_env → ManagerBasedRlEnv, which requires the full RL cfg surface (decimation, episode_length_s, actions_cfg, …) these demos don't have. Continuing to bolt fields onto the base cfg (as #153 did for device) only moves the crash to the next field.

Note: the prompt's framing ("build_env is called unconditionally") was slightly off — the dispatcher does have a non-RL branch; the defect is the routing condition, which keys off incidental CLI flags instead of whether the task is RL-capable.

Fix (Option A — gate routing on RL-capability)

_dispatch_play now routes through the RL play helper only when the play env cfg is a ManagerBasedRlEnvCfg. Non-RL tasks always run their own .play(). RL-only options are meaningless for a fixed scene demo, so they are warned-and-ignored rather than crashing:

warning: GeneLab-Rubiks-Play-v0 is a non-RL scene-playback task; ignoring --agent and running its built-in playback.

--steps / --vis / --gpu and dotted config overrides still apply to both kinds of task (they're resolved into the cfg before dispatch), so --steps 5 correctly runs the demo for 5 steps.

Defense-in-depth: build_env now raises a clear TypeError naming the required surface if ever handed a non-RL cfg, instead of a cryptic AttributeError deep inside ManagerBasedRlEnv.__init__.

Considered and rejected: (B) converting Rubiks/Wuji into ManagerBasedRlEnvCfg subclasses — they aren't RL (the cube isn't an actuated articulation); (C) removing them from the registry — they're working, runnable demos.

Reference audit

find_referencing_symbols(build_env) — all callers are RL paths, so the type-guard is safe:

src/genelab/cli/_export.py:47   export_task → build_env   (RL export)
src/genelab/rl/eval_task.py:81  eval_task → build_env     (RL eval)
src/genelab/rl/runner.py:141    train_task → build_env
src/genelab/rl/runner.py:179    _train_chunk → build_env
src/genelab/rl/runner.py:249    play_task → build_env

ManagerBasedRlEnv.__init__ reads the full RL surface (device, decimation, episode_length_s, scale_rewards_by_dt, actions_cfg, observations_cfg, commands_cfg, rewards_cfg, terminations_cfg, events_cfg, curriculum_cfg, metrics_cfg) — none of which exist on the base ManagerBasedEnvCfg. Confirmed RubiksEnvCfg/WujiEnvCfg subclass the base, not the RL cfg.

Tests

• tests/test_examples_{rubiks,wuji}.py — exercise the real genelab play … --agent zero --steps 5 dispatch path with Genesis stubbed out (headless): assert the scene demo runs, honors --steps, and is not routed through play_task. These guard the actual P8/P9 bug, which the fix(envs): move device cfg field onto base ManagerBasedEnvCfg #153 cfg-only tests never touched (false confidence — they never invoked genelab play).
• tests/test_cli_routing.py — non-RL task + --agent runs the demo with a warning; build_env rejects a non-RL cfg with a clear TypeError.
• tests/fake_extension.py — added an RL-capable fake task (External-Fake-RL-Task-v0, env subclasses ManagerBasedRlEnvCfg). The existing agent-routing tests (test_cli_routes_agent_through_play_task, test_play_invalid_agent_falls_back_to_picker, test_play_task_argument_preserves_dashed_runner_flags) now point at it — they previously asserted the buggy contract on a non-RL cfg.

uv run pytest -q → 506 passed (headless). The new example tests also pass in isolation (hardened against a pre-existing ordering fragility: faking sys.modules["genelab.rl"] breaks entry-point loading of genelab_unitree, so the new tests monkeypatch the play_task attribute on the real module instead).

GPU verification still recommended:

QT_QPA_PLATFORM=offscreen genelab play GeneLab-Rubiks-Play-v0 --agent zero --steps 5   # (QD_GRAPH=0 on H100/H200)

Docs

docs/cli/play-train.{en,zh}.md: policy options (--agent/--checkpoint/…) apply only to RL tasks; non-RL scene demos run their built-in playback.

🤖 Generated with Claude Code