fix infinite error in eval mode

[lemon-star608]

Summary(概述)

修复在 headless(无显示器)机器上运行 eval --render-mode record(MuJoCo)时的无限刷错误日志 + 卡死问题 —— issue #605 。

• 为什么改: 两个根本原因。
  1. headless 机器上没有可用的 EGL 时,_resolve_gl_backend 会回退到 glfw,而 glfw 需要 X11 显示。没有 DISPLAY 时,每个渲染 worker 的 mujoco.Renderer() 都会抛 mujoco.FatalError: an OpenGL platform library has not been loaded。
  2. 渲染用的是 multiprocessing.Pool,当 worker 的 initializer 抛异常时它会静默地无限重启 worker —— 于是同一段 traceback 反复打印、pool.map 永不返回(无限日志 + 卡死)。
• 对用户 / 训练的影响: 对训练无影响。仅改动 play/record 路径 —— 在无法渲染的机器上,eval 现在会打印一条可操作的警告、跳过视频、干净退出(exit 0),而不是刷爆日志。

具体改动

• _resolve_gl_backend:headless(无 DISPLAY)且无 EGL 时,改为回退到 OSMesa(软件渲染),不再用 glfw。macOS 行为不变(仍是 glfw)。
• 渲染进程池:multiprocessing.Pool → concurrent.futures.ProcessPoolExecutor,worker 失败时快速失败抛 BrokenProcessPool,不再无限重启。
• 兜底:新增预检 render_backend_usable() + _warn_render_unavailable();若没有可用后端(或 worker 死亡),只打印一条警告并返回 []。run_mujoco_playback / render_states_to_video 随后跳过写视频,而不是在空帧上崩溃。

Linked Work(关联工作)

• Issue: Bug: Infinite error log when run eval with record about g1_wall_flip_tracking #605
• Milestone: —

Validation(验证)

• make check
• uv run pytest -m "not slow"(通过 make test-all)
• 下方列出的额外验证

实际执行的命令:

make test-all
# ruff check          -> All checks passed!
# ruff format --check -> 414 files left unchanged
# mypy src/unilab     -> Success: no issues found in 215 source files
# pyright             -> 0 errors, 1 warning(既有的 mlx.core import,无关)
# pytest -m "not slow" --cov -> 1261 passed, 12 skipped, 255 deselected, 0 failed;

额外验证:

• 在 headless 机器上通过强制 MUJOCO_GL=glfw(无 DISPLAY)忠实复现出报告中一字不差的错误:mujoco.FatalError: an OpenGL platform library has not been loaded。
• 证明旧的 multiprocessing.Pool 在几秒内重启数百个 worker 并卡死(rc=124);新的 ProcessPoolExecutor 约 0.05s 抛出 BrokenProcessPool。
• 验证了四条失败路径 —— GL 上下文失败、非 GL 的 init 失败(坏模型)、worker 任务中途暴毙(OOM/段错误)、完整 render_states_to_video 管线 —— 全部降级为「一条警告 + 跳过视频 + exit 0」,没有 traceback 刷屏。
• Reporter已确认该分支修复生效。

注:tests/utils/test_render_many.py 在 GITHUB_ACTIONS 下会被跳过(CI runner 没有稳定的 EGL/GLFW 后端),所以这些新测试只在本地运行、不在 CI 跑。CI 仍会校验 ruff / mypy / pyright 及其余全部用例。

Impact(影响面)

• Backend impact: mujoco
• Platform impact: Linux(headless)—— 惠及任何无 EGL/无显示器的机器;macOS 不受影响。
• Training effect expected: no(仅 play/eval 路径;collector/learner 不 import 这些模块)

Artifacts(产物)

• W&B: —
• benchmark result: —
• video / screenshot: —
• ONNX / checkpoint: —

Checklist(检查项)

• 按需新增/更新了测试
• 行为或流程变化时更新文档(不适用 —— 无流程变化)
• 关联了驱动该 PR 的 issue
• 明确记录了后续工作(无)