microduck-cli 0.9.5__tar.gz → 0.9.6__tar.gz

{microduck_cli-0.9.5 → microduck_cli-0.9.6}/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.6] - 2026-09-08
+
+### Added
+
+- `docs/verification/2026-09-08-thor-orin-tutorial-run.md` — the tutorial's operator run on Jetson AGX Thor (PyPI 0.9.4 wheel): the first smoke failed on a torch the clone had re-synced to `+cu129` after slipping back to the pin, the second passed in 26 s beside the production stack; the simulation's memory footprint on Thor (`duck-body` 933 MB, `robotd` 34 MB) and Orin (590 MB / 41 MB, +0.9 GB box-wide, headless); Orin's clone at `a30a9e4` resolves torch from the SBSA index with a plain `uv sync`.
+
+### Changed
+
+- `README.md`: the Spark re-test row's `[FAIL]`-under-healthy caveat now points at this fix.
+
+### Fixed
+
+- `env doctor` on a wheel install (`uv tool install microduck-cli`) reported both pin checks as "pinned commit unknown" because it read `docs/upstream-pins.md` from a path the wheel does not ship (defect d5 from the 2026-09-07 Spark re-test). The pinned commits are now carried inside the package as `env/doctor.py`'s `PACKAGED_PINS`; a checkout still reads the docs table first, a wheel falls back to the packaged copy, and `tests/test_env_doctor.py` asserts the two never drift.
+- `env doctor` and `doctor` text output print `[WARN]` for a failing warning-severity check and reserve `[FAIL]` for errors, so a `healthy` verdict is never followed by a `[FAIL]` line (a Thor clone on the `microduck_rl#39` branch reads `[WARN] rl_pinned_commit`, as the tutorial says).
+
 ## [0.9.5] - 2026-09-07
 
 ### Added

{microduck_cli-0.9.5 → microduck_cli-0.9.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: microduck-cli
-Version: 0.9.5
+Version: 0.9.6
 Summary: Agent-agnostic CLI for controlling the MicroDuck robot. Any agent, any human, one CLI. Sim-first: every verb is exercised against the real robotd daemon and the MuJoCo simulation.
 Project-URL: Homepage, https://github.com/agentculture/microduck-cli
 Project-URL: Issues, https://github.com/agentculture/microduck-cli/issues
@@ -150,7 +150,7 @@ before trusting a number here.
 | Box | Reached | Result | Caveat |
 |---|---|---|---|
 | **DGX Spark** (GB10, aarch64) | all six checks + train smoke | pass; live suite **12 passed, 0 failed** | walking `xfail` |
-| **DGX Spark**, re-test 2026-09-07 following the [Jetson AI Lab tutorial](docs/verification/2026-09-07-spark-retest.md) on the **PyPI 0.9.4 wheel**, viewer **windowed** | tutorial steps 1 and 5–11 executed on the wheel (steps 2–4, clone/build/venv, checked against pre-existing state, not re-run) + both live suites + smoke | pass; **12 passed, 1 xfailed** windowed | the wheel's `env doctor` prints two `[FAIL]` pin lines under a `healthy` verdict (pins file not shipped, filed); the smoke needs the GPU free — it failed OOM beside a resident vLLM engine and passed with it paused |
+| **DGX Spark**, re-test 2026-09-07 following the [Jetson AI Lab tutorial](docs/verification/2026-09-07-spark-retest.md) on the **PyPI 0.9.4 wheel**, viewer **windowed** | tutorial steps 1 and 5–11 executed on the wheel (steps 2–4, clone/build/venv, checked against pre-existing state, not re-run) + both live suites + smoke | pass; **12 passed, 1 xfailed** windowed | the wheel's `env doctor` printed two `[FAIL]` pin lines under a `healthy` verdict (pins file not shipped — fixed in 0.9.6: the pins are packaged and warnings render `[WARN]`); the smoke needs the GPU free — it failed OOM beside a resident vLLM engine and passed with it paused |
 | **Jetson AGX Thor** (JetPack 7) | all six checks, three tiers, headless | pass; **12 passed, 1 xfailed** | ran on an *uncommitted* local torch override; the upstream fix is still open as [microduck_rl#39](https://github.com/pollen-robotics/microduck_rl/pull/39) (issue [#38](https://github.com/pollen-robotics/microduck_rl/issues/38)), so `env doctor`'s `rl_pinned_commit` fails there **by design** until it merges and this repo re-pins |
 | **Jetson AGX Orin** (L4T R39) | checks 1–4 | pass | the SBSA torch wheel carries no `sm_87` kernels — GPU training is **not available** on Orin at this pin |
 

{microduck_cli-0.9.5 → microduck_cli-0.9.6}/README.md

@@ -133,7 +133,7 @@ before trusting a number here.
 | Box | Reached | Result | Caveat |
 |---|---|---|---|
 | **DGX Spark** (GB10, aarch64) | all six checks + train smoke | pass; live suite **12 passed, 0 failed** | walking `xfail` |
-| **DGX Spark**, re-test 2026-09-07 following the [Jetson AI Lab tutorial](docs/verification/2026-09-07-spark-retest.md) on the **PyPI 0.9.4 wheel**, viewer **windowed** | tutorial steps 1 and 5–11 executed on the wheel (steps 2–4, clone/build/venv, checked against pre-existing state, not re-run) + both live suites + smoke | pass; **12 passed, 1 xfailed** windowed | the wheel's `env doctor` prints two `[FAIL]` pin lines under a `healthy` verdict (pins file not shipped, filed); the smoke needs the GPU free — it failed OOM beside a resident vLLM engine and passed with it paused |
+| **DGX Spark**, re-test 2026-09-07 following the [Jetson AI Lab tutorial](docs/verification/2026-09-07-spark-retest.md) on the **PyPI 0.9.4 wheel**, viewer **windowed** | tutorial steps 1 and 5–11 executed on the wheel (steps 2–4, clone/build/venv, checked against pre-existing state, not re-run) + both live suites + smoke | pass; **12 passed, 1 xfailed** windowed | the wheel's `env doctor` printed two `[FAIL]` pin lines under a `healthy` verdict (pins file not shipped — fixed in 0.9.6: the pins are packaged and warnings render `[WARN]`); the smoke needs the GPU free — it failed OOM beside a resident vLLM engine and passed with it paused |
 | **Jetson AGX Thor** (JetPack 7) | all six checks, three tiers, headless | pass; **12 passed, 1 xfailed** | ran on an *uncommitted* local torch override; the upstream fix is still open as [microduck_rl#39](https://github.com/pollen-robotics/microduck_rl/pull/39) (issue [#38](https://github.com/pollen-robotics/microduck_rl/issues/38)), so `env doctor`'s `rl_pinned_commit` fails there **by design** until it merges and this repo re-pins |
 | **Jetson AGX Orin** (L4T R39) | checks 1–4 | pass | the SBSA torch wheel carries no `sm_87` kernels — GPU training is **not available** on Orin at this pin |
 

microduck_cli-0.9.6/docs/verification/2026-09-08-thor-orin-tutorial-run.md

@@ -0,0 +1,106 @@
+# Jetson AGX Thor and AGX Orin, 2026-09-08: the tutorial's operator run
+
+The Jetson AI Lab tutorial draft
+([NVIDIA-AI-IOT/jetson-ai-lab#444](https://github.com/NVIDIA-AI-IOT/jetson-ai-lab/pull/444))
+was followed by the operator on Jetson AGX Thor on the **PyPI 0.9.4 wheel**
+(`~/.local/bin/microduck`, `uv tool install`), and its review comments asked
+for numbers this record supplies: the Thor smoke on the wheel, and the
+simulation's memory footprint on both Jetson boards. Everything below was
+run over SSH by the agent at the operator's request, except the first smoke
+attempt, which the operator ran and saved as `1.json`.
+
+| | Jetson AGX Thor | Jetson AGX Orin |
+|---|---|---|
+| host | "NVIDIA Thor", JetPack 7 / L4T R38.2.2, kernel `6.8.12-tegra`, CUDA 13.0, 122 GB unified | "Orin (nvgpu)" sm_87, L4T R39, kernel `6.8.12-1021-tegra`, 61 GB unified |
+| CLI | `microduck-cli 0.9.4` from PyPI | `microduck-cli 0.9.4` from PyPI |
+| `microduck` clone | `0cd676d` (the pin) | `0cd676d` (the pin) |
+| `microduck_rl` clone | `a30a9e4` (`fix/jetson-thor-torch-source`, [microduck_rl#39](https://github.com/pollen-robotics/microduck_rl/pull/39)) | `a30a9e4` (same branch) |
+| shared box | the production stack (`prod-*`, `model-gear-*` vLLM engines) up throughout | `model-gear-*` and `prod-*` containers up throughout; 8 GB available |
+
+## Thor: the smoke failed first, on a torch the clone had re-synced
+
+The operator's first `policy smoke` (`1.json`, 01:31) failed in
+`ManagerBasedRlEnv.__init__` with `torch.AcceleratorError: CUDA error: no
+kernel image is available for execution on the device`, after torch's own
+warning that the installed build supports `sm_80 sm_90 sm_100 sm_120` and
+Thor is `sm_110`. The clone's reflog showed it had been checked out at
+`a30a9e4` and then moved back to the pinned `29e887e`; the next `uv run
+train` re-synced torch to the `2.9.1+cu129` wheel from PyTorch's index
+(`Uninstalled 1 package … Installed 1 package` at the top of stderr), which
+carries no Thor kernels. The three extra wheels the fix branch adds
+(`nvpl-blas`, `nvpl-lapack`, `nvidia-cudss-cu13`) were still in the venv.
+
+Fix: back to the tutorial's Thor tab.
+
+```text
+$ git checkout a30a9e4 && UV_HTTP_TIMEOUT=600 uv sync      # in ~/git/microduck_rl
+$ .venv/bin/python -c "import torch"
+ImportError: libnvpl_lapack_lp64_gomp.so.0: cannot open shared object file
+$ .venv/bin/python -c "import mjlab_microduck.tasks, torch; print(torch.__version__, torch.cuda.get_arch_list(), torch.cuda.is_available())"
+2.9.1 ['sm_110', 'sm_121'] True
+```
+
+The bare `import torch` failure is expected on this branch: `a30a9e4` does
+not use `LD_LIBRARY_PATH`; `mjlab_microduck/_torch_libs.py` pre-loads the two
+undeclared libraries when `mjlab_microduck.tasks` is imported, which every
+train/play path does before torch. A hand probe must import the package
+first. The 2026-09-04 Thor record used `LD_LIBRARY_PATH` because that module
+did not exist yet.
+
+## Thor: the smoke on the wheel, second attempt
+
+`free -g` immediately before: `Mem: 122 total, 86 used, 36 available` (the
+tutorial's floor is 20 GB).
+
+```text
+$ WANDB_MODE=offline timeout 30m microduck policy smoke Mjlab-Velocity-Flat-MicroDuck --json
+Warp 1.12.0 initialized:  CUDA Toolkit 12.9, Driver 13.0
+     "cuda:0"   : "NVIDIA Thor" (123 GiB, sm_101, mempool enabled)
+...
+                         Iteration time: 2.05s
+                           Time elapsed: 00:00:09
+{"argv": ["uv", "run", "train", "Mjlab-Velocity-Flat-MicroDuck", "--env.scene.num-envs", "64", "--agent.max_iterations", "5"], "ok": true, "returncode": 0, ...}
+exit 0   elapsed 0:26.02   max RSS 2.8 GB
+```
+
+**Pass.** 26 s wall-clock on a warm Warp kernel cache (the 2026-09-04 cold
+run took 144 s). `docker ps` afterwards: every `prod-*` and `model-gear-*`
+container still `Up`, the three vLLM engines `(healthy)`. `free -g` after:
+`36 available`, unchanged.
+
+## Memory footprint of the simulation
+
+RSS of the two processes `env up --sim` starts, read from `/proc/<pid>/status`
+while the duck was standing (`duck init --apply`, `duck enable --apply`):
+
+| process | Thor (windowed, up since the operator's run) | Orin (`--headless`, 3 s to healthy) |
+|---|---|---|
+| `duck-body` (`python -m mjlab_microduck.sim.body_server`) | 933 MB | 590 MB |
+| `robotd --sim` | 34 MB | 41 MB |
+| box `used` delta while up | not measured (already running) | +0.9 GB (`free -m`: 54355 → 55268 MB) |
+
+So the simulation and the daemon together cost about one gigabyte, an order
+of magnitude below the training smoke's 2.8 GB peak RSS and far below
+Thor's 20 GB floor for the smoke. On Orin the stack ran and stood the duck
+up with 8 GB available beside the production containers; `env down` stopped
+both processes (`body: terminated`; the "something is still listening on
+port 7801" warning cleared on the next check, nothing left running).
+
+## Orin: the fix branch resolves torch without `UV_INDEX`
+
+The Orin clone is also at `a30a9e4`, and its `uv.lock` resolves `torch`
+2.9.1 from `pypi.jetson-ai-lab.io/sbsa/cu130` (the branch keys the SBSA
+index on `'tegra' in platform_release`, which Orin's `6.8.12-1021-tegra`
+kernel matches); `torch-2.9.1.dist-info` is what is installed. The tutorial's
+Orin `UV_INDEX=…` line is only needed on the pinned `develop` commit. Nothing
+changes for training: that torch has `sm_110`/`sm_121` kernels, not Orin's
+`sm_87`, exactly as the 2026-09-04 Orin record found.
+
+## What this changed
+
+- The 0.9.6 `env doctor` fix in this repo (`PACKAGED_PINS`, `[WARN]`): Thor
+  on the wheel hit the two `[FAIL] … unknown` lines the Spark re-test filed as
+  `d5`, and the tutorial reviewer asked for it to just work.
+- The tutorial: Step 2 tells Jetson readers to check out `a30a9e4` up front
+  (the flip back to the pin is what broke the first smoke); the Thor and Orin
+  tabs carry these numbers; Step 4's Spark tab warns about the sync's size.

{microduck_cli-0.9.5 → microduck_cli-0.9.6}/microduck_cli/cli/_commands/doctor.py

@@ -98,20 +98,30 @@ def _diagnose() -> dict[str, object]:
     return {"healthy": healthy, "checks": checks}
 
 
+def _mark(check: dict) -> str:
+    """`ok` for a pass, `WARN` for a failing warning, `FAIL` for a failing error."""
+    if check["passed"]:
+        return "ok"
+    return "WARN" if check["severity"] == "warning" else "FAIL"
+
+
+def _render_text(report: dict) -> str:
+    status = "healthy" if report["healthy"] else "unhealthy"
+    lines = [f"microduck-cli doctor: {status}", ""]
+    for check in report["checks"]:
+        lines.append(f"[{_mark(check)}] {check['id']}: {check['message']}")
+        if not check["passed"] and check["remediation"]:
+            lines.append(f"  hint: {check['remediation']}")
+    return "\n".join(lines)
+
+
 def cmd_doctor(args: argparse.Namespace) -> int:
     report = _diagnose()
     json_mode = bool(getattr(args, "json", False))
     if json_mode:
         emit_result(report, json_mode=True)
     else:
-        status = "healthy" if report["healthy"] else "unhealthy"
-        lines = [f"microduck-cli doctor: {status}", ""]
-        for check in report["checks"]:
-            mark = "ok" if check["passed"] else "FAIL"
-            lines.append(f"[{mark}] {check['id']}: {check['message']}")
-            if not check["passed"] and check["remediation"]:
-                lines.append(f"  hint: {check['remediation']}")
-        emit_result("\n".join(lines), json_mode=False)
+        emit_result(_render_text(report), json_mode=False)
     return 0 if report["healthy"] else 1
 
 

{microduck_cli-0.9.5 → microduck_cli-0.9.6}/microduck_cli/env/doctor.py

@@ -2,7 +2,8 @@
 
 Diagnoses whether this box is ready to run the simulation stack (t13) and
 the training lane (t14): the upstream clones checked out at the pinned
-commits recorded in ``docs/upstream-pins.md``, a cargo toolchain new enough
+commits recorded in ``docs/upstream-pins.md`` (carried inside the package as
+``PACKAGED_PINS`` too, so a wheel install can verify them), a cargo toolchain new enough
 to build ``robotd``/``robotctl``/``tof``/``sounds``, the built daemons
 themselves, the ``microduck_rl`` virtualenv with ``onnxruntime`` installed,
 a state directory short enough for unix sockets, a free port for
@@ -65,6 +66,18 @@ _MICRODUCK_RL_HF_README_URL = (
     "https://github.com/pollen-robotics/microduck_rl/blob/develop/scripts/hf/README.md"
 )
 
+# --- the pinned upstream commits, carried inside the wheel -------------
+# docs/upstream-pins.md is the authoritative ledger, but a wheel does not
+# ship docs/, so a `uv tool install` used to report both pin checks as
+# "unknown" (a [FAIL] line under a healthy verdict — the 2026-09-07 Spark
+# re-test, defect d5). These are the same commits, hardcoded on purpose;
+# tests/test_env_doctor.py asserts they equal the table so a re-pin that
+# forgets one of the two fails CI rather than drifting.
+PACKAGED_PINS: dict[str, str] = {
+    "pollen-robotics/microduck": "0cd676d6fbb6e90a762c84aa63abe7a02dbc9495",
+    "pollen-robotics/microduck_rl": "29e887ecfbf5d37144759e5a9f8a176dfb83d547",
+}
+
 _MIN_CARGO_VERSION = (1, 89)
 
 # duck-body's default port, matching upstream's DUCK_SIM_PORT (env/stack.py's
@@ -181,6 +194,17 @@ def _parse_pins(pins_path: Path) -> dict[str, str]:
     return pins
 
 
+def load_pins(pins_path: Path) -> dict[str, str]:
+    """The pinned commits: the docs table when it is readable, else the packaged copy.
+
+    A checkout reads ``docs/upstream-pins.md`` (so an in-flight re-pin is seen
+    before the constant is updated); a wheel, which does not ship ``docs/``,
+    falls back to :data:`PACKAGED_PINS` row by row. Either way the result
+    carries both repos whenever either source knows them.
+    """
+    return {**PACKAGED_PINS, **_parse_pins(pins_path)}
+
+
 def _find_onnxruntime(rl_clone: str) -> str | None:
     venv = Path(rl_clone) / ".venv"
     if not venv.is_dir():
@@ -296,7 +320,7 @@ def default_probe() -> EnvProbe:
     env = _probe_environ()
 
     pins_path = Path(__file__).resolve().parents[2] / "docs" / "upstream-pins.md"
-    pins = _parse_pins(pins_path)
+    pins = load_pins(pins_path)
 
     microduck_clone, rl_clone = resolve_clone_paths(env)
     microduck_clone_commit = _git_head(microduck_clone) if microduck_clone else None
@@ -377,9 +401,9 @@ def _pinned_commit_check(
             check_id,
             False,
             "warning",
-            f"pinned commit for {label} is unknown (docs/upstream-pins.md unreadable or the "
-            "row is missing)",
-            "check that docs/upstream-pins.md is present and its table is well-formed",
+            f"pinned commit for {label} is unknown (no row in docs/upstream-pins.md and none "
+            "packaged)",
+            "add the repo's row to docs/upstream-pins.md and PACKAGED_PINS in env/doctor.py",
         )
     if not clone_commit:
         return _check(
@@ -621,17 +645,25 @@ def diagnose(probe: EnvProbe) -> dict[str, object]:
     return {"healthy": healthy, "checks": checks}
 
 
+def _mark(check: Mapping[str, object]) -> str:
+    if check["passed"]:
+        return "ok"
+    return "WARN" if check["severity"] == "warning" else "FAIL"
+
+
 def render_text(report: Mapping[str, object]) -> str:
     """Render `report` the way `microduck-cli doctor`'s text output looks.
 
-    ``"[ok] id: message"`` / ``"[FAIL] id: message"``, with a ``"  hint:
-    remediation"`` line under any failing check that carries one.
+    ``"[ok] id: message"`` for a passing check, ``"[WARN] id: message"`` for a
+    failing ``warning``-severity one (surfaced, never blocking the verdict) and
+    ``"[FAIL] id: message"`` for a failing ``error``, with a ``"  hint:
+    remediation"`` line under any failing check that carries one. The prefix
+    agrees with the verdict line: a healthy report never shows ``[FAIL]``.
     """
     status = "healthy" if report["healthy"] else "unhealthy"
     lines = [f"microduck-cli env doctor: {status}", ""]
     for check in report["checks"]:  # type: ignore[union-attr]
-        mark = "ok" if check["passed"] else "FAIL"
-        lines.append(f"[{mark}] {check['id']}: {check['message']}")
+        lines.append(f"[{_mark(check)}] {check['id']}: {check['message']}")
         if not check["passed"] and check["remediation"]:
             lines.append(f"  hint: {check['remediation']}")
     return "\n".join(lines)

{microduck_cli-0.9.5 → microduck_cli-0.9.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "microduck-cli"
-version = "0.9.5"
+version = "0.9.6"
 description = "Agent-agnostic CLI for controlling the MicroDuck robot. Any agent, any human, one CLI. Sim-first: every verb is exercised against the real robotd daemon and the MuJoCo simulation."
 readme = "README.md"
 license = "Apache-2.0"

{microduck_cli-0.9.5 → microduck_cli-0.9.6}/tests/test_env_doctor.py

@@ -3,11 +3,15 @@
 from __future__ import annotations
 
 import json
+from pathlib import Path
 
 from microduck_cli.env.doctor import (
+    PACKAGED_PINS,
     EnvProbe,
+    _parse_pins,
     default_probe,
     diagnose,
+    load_pins,
     render_text,
 )
 from microduck_cli.env.hosts import HostInfo
@@ -335,3 +339,58 @@ def test_default_probe_never_raises_and_returns_env_probe():
     # Must be diagnosable without raising regardless of what's installed here.
     report = diagnose(probe)
     assert isinstance(report["healthy"], bool)
+
+
+# --- packaged pins (d5: a wheel ships no docs/) ---------------------------
+
+_PINS_DOC = Path(__file__).resolve().parents[1] / "docs" / "upstream-pins.md"
+
+
+def test_packaged_pins_match_the_docs_table():
+    # A re-pin that updates one source and not the other must fail here.
+    assert _parse_pins(_PINS_DOC) == PACKAGED_PINS
+
+
+def test_load_pins_falls_back_to_packaged_when_docs_absent(tmp_path):
+    assert load_pins(tmp_path / "missing" / "upstream-pins.md") == PACKAGED_PINS
+
+
+def test_load_pins_prefers_a_readable_docs_table(tmp_path):
+    doc = tmp_path / "upstream-pins.md"
+    doc.write_text(
+        "| repo | ref | commit |\n|---|---|---|\n"
+        "| `pollen-robotics/microduck` | branch `x` | `abcdef1234567` |\n",
+        encoding="utf-8",
+    )
+    pins = load_pins(doc)
+    assert pins["pollen-robotics/microduck"] == "abcdef1234567"
+    assert pins["pollen-robotics/microduck_rl"] == PACKAGED_PINS["pollen-robotics/microduck_rl"]
+
+
+def test_default_probe_knows_both_pins():
+    probe = default_probe()
+    assert probe.microduck_pinned_commit == PACKAGED_PINS["pollen-robotics/microduck"]
+    assert probe.rl_pinned_commit == PACKAGED_PINS["pollen-robotics/microduck_rl"]
+
+
+# --- [WARN] vs [FAIL] -----------------------------------------------------
+
+
+def test_render_text_marks_warnings_warn_not_fail():
+    probe = EnvProbe(
+        **{
+            **COMPLETE_PROBE.__dict__,
+            "rl_clone_commit": "a30a9e4ffc161c90d19181f2815d1b50064182bb",
+        }
+    )
+    report = diagnose(probe)
+    text = render_text(report)
+    assert text.startswith("microduck-cli env doctor: healthy")
+    assert "[WARN] rl_pinned_commit:" in text
+    assert "[FAIL]" not in text
+
+
+def test_render_text_marks_errors_fail():
+    text = render_text(diagnose(EMPTY_PROBE))
+    assert text.startswith("microduck-cli env doctor: unhealthy")
+    assert "[FAIL] microduck_clone_present:" in text

{microduck_cli-0.9.5 → microduck_cli-0.9.6}/uv.lock

@@ -227,7 +227,7 @@ wheels = [
 
 [[package]]
 name = "microduck-cli"
-version = "0.9.5"
+version = "0.9.6"
 source = { editable = "." }
 
 [package.dev-dependencies]