feat(imitation): add CLI learning workflow

[TomCC7]

Contribution path

• PRD: Manipulation SDK preview, discussion #3923.
• Stacked on feat(imitation): add direct OpenYAM teach collection #3921.

Problem

• A learning-workflow catalog duplicates Blueprint discovery and module-config matching.
• Collection and rollout controls should work with externally packaged robots without owning their runtime.
• Dataset preparation must use saved recording metadata rather than a selected live robot profile.

Solution

• Add dimos imitation collect and rollout as attached Textual controls.

• Discover controllers through Dimos.connect().find_module_by_spec(...), using the Specs already defined in feat(imitation): add native OpenYAM collection #3854 and refactor(imitation): isolate LeRobot policy runtime #3315.

• Keep launch, module configuration, and lifecycle in dimos run; remove workflow catalogs and dedicated robot flags.

• Add directory-based prepare and inspect, reading the schema.json contract from feat(imitation): add native OpenYAM collection #3854.

• Delegate visualization to isolated lerobot-dataset-viz; use a stable path-derived dataset identity so Rerun does not reuse another recording's Blueprint. Do not hardcode camera views or joint labels.

• Pass training arguments directly to isolated lerobot-train.

• Document external Blueprint entry points and the unchanged Python recorder path for G1.

• Keep dual-arm composition in feat(imitation): add profile-driven dual-arm collection #3942 and the existing single-camera LeRobot backend unchanged.

• Assert viewer help/errors after stripping ANSI styles with Click; test plain and forced-color output.

API shape

dimos run BLUEPRINT [module config] → running robot stack
                                      ↑
dimos imitation collect             EpisodeControlSpec
dimos imitation rollout             RolloutControlSpec

dimos imitation prepare RECORDING_DIR --output DATASET_DIR
dimos imitation inspect ARTIFACT
dimos imitation visualize DATASET_DIR --episode 0
dimos imitation train [LEROBOT_ARGS...]

• Collection: get_status(), command(event). Space starts/saves, D discards, Q detaches.
• Rollout: preflight_rollout(), start_rollout(), stop_rollout(), rollout_status(). Space explicitly starts/stops; Q detaches.
• Exactly one Spec implementation must match, and module classes must be importable. Missing/ambiguous matches fail; there is no --module selector.
• Quitting or losing the UI connection does not stop recording or motion. Active collection asks for confirmation before detaching. Use dimos stop separately; neither panel is a deadman switch.
• An external distribution named vendor-robot can publish collect = "vendor_robot.collection:collect" under [project.entry-points."dimos.blueprints"], then run as dimos run vendor-robot.collect. No imitation registry entry is needed.

How to Test

With single-arm teaching hardware configured:

dimos --can-port follower_l run openyam-teach-collection --daemon --recorder.recording recordings/session-001 --episodes.task "pick up the cube"
dimos imitation collect

After saving episodes:

dimos imitation inspect recordings/session-001
dimos imitation prepare recordings/session-001 --output datasets/session-001
dimos imitation visualize datasets/session-001 --episode 0
dimos imitation train --help

• Launch openyam-lerobot-rollout with a compatible checkpoint, then attach dimos imitation rollout.

• In the previous cleanup: 19 CLI/TUI/conversion-process tests and 6 registry checks passed; scoped mypy and commit hooks passed.

• Current review cleanup: all 28 CLI tests pass in the final focused suite; the visualization identity fix now lives in this layer rather than dual-arm integration. No interactive viewer retest was performed.

• Coverage includes external Spec discovery, rejected ambiguity, detach behavior, headless collection controls, and direct training argument forwarding.

• Physical collection, rollout, and shutdown remain hardware release checks.

• CI repair: all 34 CLI tests and the documentation-branding check passed under forced color. No changes to the viewer launch contract.

AI assistance

• Review cleanup updated by OpenAI Codex (agent).
• OpenAI Codex (GPT-5) assisted extensively with implementation, tests, documentation, and stack cleanup.

Checklist

• I have read and approved the CLA.

[codecov]

Codecov Report

❌ Patch coverage is 91.30913% with 79 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
dimos/imitation/tui.py	74.32%	47 Missing and 10 partials ⚠️
dimos/cli/commands/imitation.py	89.21%	7 Missing and 4 partials ⚠️
dimos/cli/imitation_inspect.py	95.04%	1 Missing and 4 partials ⚠️
...ntrol/tasks/hand_guiding_task/hand_guiding_task.py	90.38%	2 Missing and 3 partials ⚠️
...ors/openyam/blueprints/test_learning_collection.py	96.55%	0 Missing and 1 partial ⚠️

@@                            Coverage Diff                            @@
##           cc/feat/openyam-teach-data-collection    #3931      +/-   ##
=========================================================================
+ Coverage                                  79.68%   79.74%   +0.06%     
=========================================================================
  Files                                       1521     1530       +9     
  Lines                                     143383   144292     +909     
  Branches                                   12246    12319      +73     
=========================================================================
+ Hits                                      114249   115060     +811     
- Misses                                     25788    25866      +78     
- Partials                                    3346     3366      +20     

Components	Coverage Δ
Tests	95.37% <99.76%> (-0.01%)	⬇️

Flag	Coverage Δ
OS-ubuntu-24.04-arm	75.58% <91.30%> (+0.09%)	⬆️
OS-ubuntu-latest	76.34% <91.30%> (+0.09%)	⬆️
Py-3.10	76.12% <91.30%> (+0.09%)	⬆️
Py-3.11	76.32% <91.30%> (+0.09%)	⬆️
Py-3.12	76.33% <91.30%> (+0.09%)	⬆️
SelfHosted-Large	30.67% <23.98%> (-0.05%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
dimos/cli/commands/test_imitation.py	100.00% <100.00%> (ø)
dimos/cli/dimos.py	97.89% <100.00%> (-1.03%)	⬇️
dimos/cli/test_imitation_inspect.py	100.00% <100.00%> (ø)
dimos/control/tasks/hand_guiding_task/_registry.py	100.00% <100.00%> (ø)
.../tasks/hand_guiding_task/test_hand_guiding_task.py	100.00% <100.00%> (ø)
dimos/imitation/test_tui.py	100.00% <100.00%> (ø)
...pulators/openyam/blueprints/learning_collection.py	86.36% <ø> (ø)
...t/unitree/g1/blueprints/basic/unitree_g1_teleop.py	96.87% <ø> (+6.25%)	⬆️
...ors/openyam/blueprints/test_learning_collection.py	96.77% <96.55%> (-0.20%)	⬇️
dimos/cli/imitation_inspect.py	95.04% <95.04%> (ø)
... and 3 more

... and 3 files with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[greptile-apps]

Confidence Score: 4/5

Not safe to merge: an active but unresponsive coordinator can be bypassed, allowing a competing robot-control stack to start.

Findings

1.  Coordinator Timeouts Start Stacks ▶

Summary

• The new imitation workflow can misclassify a slow but active DimOS coordinator as absent.
• Collection and policy rollout may then launch a second stack that competes for control of the same robot hardware.

This must be corrected before merging.