Field report: five first-run failures on a real rig that a setup wizard should preflight

[aris-zhu]

Context

Real first-run session on the YAM rig host (omen), 2026-07-13. The operator recreated .venv (uv venv && uv pip install "inspect-robots[rerun]", got 0.7.0), then followed the README quickstart to uv run inspect-robots "place the fork on the plate". Every failure below was hit in sequence, one run at a time — each fix revealed the next failure. A setup wizard (or an extended doctor) should catch all of them in one preflight pass, before anything energizes.

The failure chain

#	Symptom	Root cause	When it surfaced
1	no policy named 'molmoact2'; available: ['noop', 'random', 'scripted']	config.ini names plugin components, but inspect-robots-yam was not installed; the README quickstart never shows the plugin install command	at resolution (early, cheap)
2	ValueError: rest_pose must have 14 entries	PyPI inspect-robots-yam 0.6.0 predates the comma-string→float-tuple parsing for pose fields (plugin PR #24, merged but unreleased); len() of the raw string = ~90 chars. Fixed locally with an editable install of the plugin checkout	at embodiment construction
3	EmbodimentFault: No module named 'i2rt'	plugin runtime extras missing: i2rt driver (GitHub-only, cannot be a plain PyPI dep), [client] (requests+json-numpy for the /act transport), [cameras] (OpenCV for the V4L2 devices the quickstart config itself asks you to fill in)	at reset, with the arms already in the loop — worst possible place
4	winit EventLoopError: neither WAYLAND_DISPLAY nor WAYLAND_SOCKET nor DISPLAY is set + 6s of gRPC flush errors	rerun = true in config, but the session is SSH (headless). Run still executed; viewer spawn failed noisily	every run over SSH
5	Could not access SocketCAN device can0 ([Errno 19] No such device)	two causes: (a) generic yam_arms defaults to can0/can1, but this host udev-pins interfaces by adapter serial to can_left/can_right (/etc/udev/rules.d/70-can-names.rules); the machine-specific wrapper package (omen-rig, registers yam_arms_omen with the right channels baked in) was also missing from the fresh venv. (b) only ONE USB-CAN adapter was enumerated (lsusb: one gs_usb device; ip -br link: can_left UP, no can_right) — the right arm's adapter is physically unplugged or unpowered	at CAN open

What a wizard should check, derived from the above

1. Resolution dry-run: resolve every config-named component (policy, embodiment, sim_embodiment, scorer) against the registry and report all misses at once, with the plugin package that provides each name and its install command.
2. Lazy-import preflight: embodiments/policies declare their runtime imports (or the wizard just constructs + introspects); verify i2rt, cv2, requests/json_numpy import BEFORE any reset. A missing module must never first surface as an EmbodimentFault mid-trial.
3. Version-skew check: compare installed plugin versions against the framework (the conformance kit already catches part of this: PyPI yam 0.6.0 also predates dim_labels and fails doctor). Recommend upgrade/release when a plugin lags known-required features.
4. Display probe: no DISPLAY/WAYLAND_DISPLAY + rerun = true → warn up front and offer config set rerun false (frames side-car still works). Do not let the viewer fail after the run already happened.
5. Interface existence probe: for CAN-backed embodiments, check the configured channels exist and are UP (ip -br link) before energizing; on miss, list present CAN interfaces (this catches both wrong-name config and an unplugged adapter, with different guidance for each). Same idea generalizes to the camera device paths in config (test -e /dev/v4l/by-id/...).
6. Policy-server probe: molmoact2 is a thin client (default http://127.0.0.1:8202); a TCP/HTTP reachability check is one line and turns "first /act call fails mid-episode" into a preflight message. (On this host the server was up, so this one didn't fire — but it's the same class.)
7. Check everything, then report everything: the defining pain of this session was serial discovery — five runs to find five problems. The wizard's contract should be one pass, full list, each item with its fix command.

Docs follow-ups (separate, but same root): the README quickstart should install the plugin + extras it configures, and mention --no-rerun for SSH. And inspect-robots-yam needs a release cut (the PyPI 0.6.0 path is broken for any config with pose fields).

Raised for ingestion by the setup-wizard effort; happy to split items out.

[jeqcho]

#52 (merged) ships the setup wizard and covers item 4 from this list (headless display probe: the wizard flips the suggested rerun default to false and explains why) plus the docs follow-up (quickstart now shows the plugin install command and leads with inspect-robots setup). Items 1-3 and 5-7 (resolution dry-run reporting all misses at once, lazy-import preflight, version skew, CAN/policy-server probes, check-everything-report-everything) remain open here and are doctor-shaped rather than wizard-shaped.

🤖 Generated with Claude Code