Merge branch 'develop' into antoiner/deprecate-io-descriptors

Author: ooctipus

.gitattributes

@@ -7,11 +7,15 @@
 *.obj filter=lfs diff=lfs merge=lfs -text
 *.gif filter=lfs diff=lfs merge=lfs -text
 *.mp4 filter=lfs diff=lfs merge=lfs -text
+*.webp filter=lfs diff=lfs merge=lfs -text
 *.pt filter=lfs diff=lfs merge=lfs -text
 *.jit filter=lfs diff=lfs merge=lfs -text
 *.hdf5 filter=lfs diff=lfs merge=lfs -text
 
 source/isaaclab_tasks/test/golden_images/**/*.png filter=lfs diff=lfs merge=lfs -text
 
+# Generated actuator plots are reviewed as rendered images rather than XML.
+docs/source/_static/actuators/*.png binary linguist-generated
+
 *.bat text eol=crlf
 *.sh text eol=lf

.github/actions/_lib/compute-deps-hash/action.yml

@@ -54,6 +54,10 @@ runs:
           isaaclab.sh
           environment.yml
           source/isaaclab/isaaclab/cli
+          tools/wheel_builder/uv-overrides.txt
+          # Pins the CI pytest deps layered onto the image after build, so a
+          # change to that list must invalidate the deps cache.
+          .github/actions/docker-build/action.yml
         )
         deps_manifest_pattern='(setup\.py|pyproject\.toml|setup\.cfg|extension\.toml|requirements[^/]*\.txt|uv\.lock)$'
 

.github/actions/_lib/with-python-package-retries.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md).
+# All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+set -u
+
+if [ "$#" -eq 0 ]; then
+  echo "Usage: $0 <pip-or-uv-command> [args...]" >&2
+  exit 2
+fi
+
+readonly command_attempts=3
+readonly package_index_retries=3
+readonly retry_delay_seconds=3
+
+# Bound the combined command- and request-level retry budget to avoid excessively long CI stalls.
+export PIP_RETRIES="${PIP_RETRIES:-$package_index_retries}"
+export UV_HTTP_RETRIES="${UV_HTTP_RETRIES:-$package_index_retries}"
+
+for ((attempt = 1; attempt <= command_attempts; attempt++)); do
+  if "$@"; then
+    exit 0
+  else
+    exit_code=$?
+  fi
+
+  if ((attempt == command_attempts)); then
+    exit "$exit_code"
+  fi
+
+  echo "Package install attempt $attempt/$command_attempts failed; retrying in $retry_delay_seconds seconds..." >&2
+  sleep "$retry_delay_seconds"
+done

.github/actions/docker-build/action.yml

@@ -175,7 +175,33 @@ runs:
         docker buildx build --load "${BUILD_ARGS[@]}" "${{ inputs.context-path }}"
         echo "was-built=true" >> "$GITHUB_OUTPUT"
 
-    ##### 6: Tag built image with local deps-tag #####
+    ##### 6: Layer the CI pytest harness onto the built image #####
+
+    # Kept out of the tracked Dockerfiles, which build local dev containers and
+    # ship via publish-images.yaml. Only on a real build; cache hits have it.
+
+    - name: Layer CI test dependencies
+      if: steps.build.outputs.was-built == 'true'
+      shell: bash
+      run: |
+        set -euo pipefail
+        # pip needs root; restore the image's own default user afterwards.
+        image_user="$(docker image inspect --format '{{.Config.User}}' "${{ inputs.image-tag }}")"
+        # Dockerfile on stdin (no context to stage). Quoted heredoc so the
+        # shell leaves ISAACLAB_PATH and IMAGE_USER for Docker to expand; the
+        # image tag is an action input, substituted before bash ever runs.
+        docker build --platform "${{ inputs.platform }}" \
+          --build-arg "IMAGE_USER=${image_user:-root}" \
+          -t "${{ inputs.image-tag }}" - <<'DOCKERFILE'
+        FROM ${{ inputs.image-tag }}
+        ARG IMAGE_USER
+        USER root
+        RUN ${ISAACLAB_PATH}/isaaclab.sh -p -m pip install \
+              pytest pytest-mock junitparser flaky "coverage>=7.6.1"
+        USER ${IMAGE_USER}
+        DOCKERFILE
+
+    ##### 7: Tag built image with local deps-tag #####
 
     # Runs only when a real build happened (not on cache hits). Populates the
     # deps-tag so the next build with identical deps short-circuits at step 4.
@@ -191,7 +217,7 @@ runs:
           echo "🟠 LOCAL_DEPS_TAG not set, skipping local deps-cache tag"
         fi
 
-    ##### 7: Evict stale local deps-cache tags (>14d) — opt-in #####
+    ##### 8: Evict stale local deps-cache tags (>14d) — opt-in #####
 
     - name: Evict stale local deps-cache tags (>14d)
       if: always() && inputs.evict-stale-cache == 'true'
@@ -214,7 +240,7 @@ runs:
           --format '{{.CreatedAt}}|{{.Repository}}:{{.Tag}}' 2>/dev/null)
         echo "🔵 Evicted ${evicted} deps tag(s) older than ${TTL_DAYS}d"
 
-    ##### 8: Host disk snapshot (post) #####
+    ##### 9: Host disk snapshot (post) #####
 
     - name: Host disk snapshot (post)
       if: always()

.github/actions/install-ci-collect/action.yml

@@ -30,7 +30,8 @@ runs:
         venv="$RUNNER_TEMP/collect-venv"
         collected="$RUNNER_TEMP/install-ci-collected.txt"
         python3 -m venv "$venv"
-        "$venv/bin/pip" install --quiet pytest pytest-timeout
+        bash "$GITHUB_WORKSPACE/.github/actions/_lib/with-python-package-retries.sh" \
+          "$venv/bin/pip" install --quiet pytest pytest-timeout
         # -m "not skip" hides tests with @pytest.mark.skip; they would just
         # report SKIPPED at run time and clutter the collected inventory.
         args=( --collect-only -q -m "not skip" source/isaaclab/test/install_ci )

.github/actions/multi-gpu/multi_gpu_shard_runner.sh

@@ -20,37 +20,33 @@
 #
 # Behavior:
 #   1. Materializes HOME + PYTHONUSERBASE dirs (tmpfs, world-writable)
-#   2. Installs pytest deps (junitparser et al.) into the shared PYTHONUSERBASE
-#   3. Derives shard count from nvidia-smi -L (authoritative; torch.cuda.device_count
+#   2. Derives shard count from nvidia-smi -L (authoritative; torch.cuda.device_count
 #      under-counts MIG-on-same-parent unless CUDA_VISIBLE_DEVICES enumerates each)
-#   4. Cross-checks torch against the nvidia-smi count and caps shards to what torch
+#   3. Cross-checks torch against the nvidia-smi count and caps shards to what torch
 #      can address (guards against CUDA_VISIBLE_DEVICES misconfig on a MIG host)
-#   5. Fans out 1 pytest subshell per non-default cuda:N with per-shard HOME +
+#   4. Fans out 1 pytest subshell per non-default cuda:N with per-shard HOME +
 #      ISAACLAB_TEST_DEVICES; each shard tees its stdout to
 #      /shard-logs/cuda-N.log for the host's grouped re-print after the run
-#   6. Waits on every shard before aggregating exit codes — a fast failure doesn't
+#   5. Waits on every shard before aggregating exit codes — a fast failure doesn't
 #      tear down still-running siblings
+#
+# The pytest deps (pytest, junitparser et al.) are baked into the image by
+# .github/actions/docker-build, so this script no longer installs them.
 
 set +e  # keep going on errors; per-shard exit codes are aggregated at the end
 cd /workspace/isaaclab
 unset DISPLAY  # clear the var that would force Kit into headed (X11) mode
 
-# Container-level HOME + PYTHONUSERBASE for pip --user installs. The image
-# runs as --user $host_uid:$host_gid with no matching /etc/passwd entry, so
-# HOME defaults to /root which the user cannot write. /tmp/* is on tmpfs
+# Container-level HOME + PYTHONUSERBASE. The image runs as
+# --user $host_uid:$host_gid with no matching /etc/passwd entry, so HOME
+# defaults to /root which the user cannot write. /tmp/* is on tmpfs
 # (1777, world-writable).
 #
-# PYTHONUSERBASE is the key for the 1-docker shape: pip --user writes to
-# ${PYTHONUSERBASE}/lib/python3.12/site-packages, and every Python invocation
-# that sees the same env var imports from there. Per-shard subshells below
-# override HOME (so .cache / .nvidia-omniverse are isolated) but inherit
-# PYTHONUSERBASE so junitparser et al. resolve everywhere.
+# Both must exist before any shard starts: per-shard subshells below override
+# HOME (so .cache / .nvidia-omniverse are isolated) but inherit
+# PYTHONUSERBASE, so anything writing to the user site shares one directory.
 mkdir -p /tmp/mgpu-base-home /tmp/mgpu-pyuserbase
 
-# Pytest deps (same as run-tests action). junitparser is imported at
-# tools/conftest.py load time, so it must be present first.
-./isaaclab.sh -p -m pip install pytest pytest-mock junitparser flaky "coverage>=7.6.1"
-
 # Shard count from nvidia-smi -L (truth; torch under-counts MIG).
 MIG_COUNT=$(nvidia-smi -L | grep -c "^  MIG ")  # grep -c = count of matching lines (MIG slices)
 GPU_COUNT=$(nvidia-smi -L | grep -c "^GPU ")    # count of whole GPUs

.github/actions/run-package-tests/action.yml

@@ -211,6 +211,7 @@ runs:
         HOST_DIR: ${{ steps.warp-cache-key.outputs.host-dir }}
         MATCHED_KEY: ${{ steps.warp-cache-restore.outputs.cache-matched-key }}
         COLLECTION: ${{ steps.warp-cache-key.outputs.collection }}
+        CACHE_MODE: ${{ inputs.warp-cache }}
       run: |
         set -euo pipefail
         mkdir -p "$HOST_DIR"
@@ -228,9 +229,13 @@ runs:
           echo "Warp cache hit: ${MATCHED_KEY}"
           echo "WARP_CACHE_HIT=${MATCHED_KEY}" >> "$GITHUB_ENV"
         fi
-        echo "WARP_CACHE_MB_BEFORE=$(du -sm "$HOST_DIR" | cut -f1)" >> "$GITHUB_ENV"
+        echo "WARP_CACHE_BYTES_BEFORE=$(du -sb "$HOST_DIR" | cut -f1)" >> "$GITHUB_ENV"
 
         python3 .github/actions/run-package-tests/warp_cache_inventory.py "$HOST_DIR" "Warp cache restored"
+        if [ "$CACHE_MODE" = "save" ]; then
+          fingerprint="$(python3 .github/actions/run-package-tests/warp_cache_inventory.py "$HOST_DIR" --fingerprint)"
+          echo "WARP_CACHE_FINGERPRINT_BEFORE=$fingerprint" >> "$GITHUB_ENV"
+        fi
 
     - name: Setup wheelhouse registry authentication
       if: inputs.wheelhouse-image != ''
@@ -333,15 +338,16 @@ runs:
           exit 1
         fi
 
-    # Growth is the coverage signal: it is exactly the kernels this job needed
-    # that the collection did not already hold. Reporting only - no thresholds,
-    # since we have no measured basis for one yet.
+    # Net growth is a useful coverage signal for missing kernels. The writer
+    # also fingerprints the tree because recompilation can replace an existing
+    # artifact without changing the total size.
     - name: Report Warp cache growth
       if: always() && inputs.warp-cache != ''
       id: warp-cache-growth
       shell: bash
       env:
         HOST_DIR: ${{ steps.warp-cache-key.outputs.host-dir }}
+        CACHE_MODE: ${{ inputs.warp-cache }}
       run: |
         set -euo pipefail
 
@@ -351,31 +357,51 @@ runs:
           exit 0
         fi
 
-        before="${WARP_CACHE_MB_BEFORE:-0}"
-        after="$(du -sm "$HOST_DIR" | cut -f1)"
+        before="${WARP_CACHE_BYTES_BEFORE:-0}"
+        after="$(du -sb "$HOST_DIR" | cut -f1)"
         grew=$(( after - before ))
+        before_mb=$(( before / 1000000 ))
+        after_mb=$(( after / 1000000 ))
+        grew_mb=$(( grew / 1000000 ))
 
         if [ "${WARP_CACHE_HIT:-miss}" = "miss" ]; then
           verdict="cold run, nothing restored"
         elif [ "$grew" -le 0 ]; then
-          verdict="fully covered"
+          verdict="no net growth"
         else
           verdict="compiled $(( grew * 100 / (before > 0 ? before : 1) ))% beyond the restored cache"
         fi
 
-        echo "Warp cache: restored ${before} MB, ended at ${after} MB (+${grew} MB) - ${verdict}"
-        echo "🔵 Warp cache: ${before} -> ${after} MB (+${grew}) - ${verdict}" >> "$GITHUB_STEP_SUMMARY"
+        echo "Warp cache: restored ${before_mb} MB, ended at ${after_mb} MB (+${grew_mb} MB) - ${verdict}"
+        echo "🔵 Warp cache: ${before_mb} -> ${after_mb} MB (+${grew_mb}) - ${verdict}" >> "$GITHUB_STEP_SUMMARY"
         python3 .github/actions/run-package-tests/warp_cache_inventory.py "$HOST_DIR" "Warp cache final"
 
         # Publishing an empty tree would replace a good snapshot with nothing.
-        [ "$after" -lt 1 ] && echo "empty=true" >> "$GITHUB_OUTPUT" || echo "empty=false" >> "$GITHUB_OUTPUT"
+        if [ -z "$(find "$HOST_DIR" -type f -print -quit)" ]; then
+          echo "::warning::Warp cache contains no files; skipping publish"
+          echo "empty=true" >> "$GITHUB_OUTPUT"
+          echo "changed=false" >> "$GITHUB_OUTPUT"
+        else
+          echo "empty=false" >> "$GITHUB_OUTPUT"
+          if [ "$CACHE_MODE" = "save" ] && [ "${WARP_CACHE_HIT:-miss}" != "miss" ]; then
+            fingerprint="$(python3 .github/actions/run-package-tests/warp_cache_inventory.py "$HOST_DIR" --fingerprint)"
+            if [ "$fingerprint" = "${WARP_CACHE_FINGERPRINT_BEFORE:-}" ]; then
+              echo "Warp cache contents are unchanged; skipping duplicate snapshot"
+              echo "changed=false" >> "$GITHUB_OUTPUT"
+            else
+              echo "changed=true" >> "$GITHUB_OUTPUT"
+            fi
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+        fi
 
     # Not success(): the product is compiled kernels, and those stay valid when a
     # test assertion fails. Gating on success() let one failing env silently
     # discard the whole cache. Cancellation still skips, so a tree Warp was
     # mid-write on is never published.
     - name: Save Warp kernel cache
-      if: '!cancelled() && inputs.warp-cache == ''save'' && steps.warp-cache-growth.outputs.empty != ''true'''
+      if: '!cancelled() && inputs.warp-cache == ''save'' && steps.warp-cache-growth.outputs.empty != ''true'' && steps.warp-cache-growth.outputs.changed == ''true'''
       uses: actions/cache/save@v4
       with:
         path: ${{ steps.warp-cache-key.outputs.host-dir }}

.github/actions/run-package-tests/warp_cache_inventory.py

@@ -10,10 +10,13 @@
 cache size and retention with measurements - module counts, artifact mix, and
 the spread of GPU targets a shared collection has accumulated.
 
-Usage: warp_cache_inventory.py <cache-dir> [label]
+Usage:
+    warp_cache_inventory.py <cache-dir> [label]
+    warp_cache_inventory.py <cache-dir> --fingerprint
 """
 
 import collections
+import hashlib
 import os
 import pathlib
 import re
@@ -22,8 +25,33 @@
 SM_PATTERN = re.compile(r"\.(sm\d+[a-z]?)\.")
 
 
+def fingerprint(root: pathlib.Path) -> str:
+    """Return a stable digest of every cache file's relative path and contents.
+
+    This lets the writer avoid publishing another immutable GitHub cache entry
+    when a warm run only read the previously restored files.
+    """
+    digest = hashlib.sha256()
+    for path in sorted(path for path in root.rglob("*") if path.is_file()):
+        digest.update(path.relative_to(root).as_posix().encode())
+        digest.update(b"\0")
+        file_digest = hashlib.sha256()
+        try:
+            with path.open("rb") as stream:
+                for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+                    file_digest.update(chunk)
+        except OSError:
+            continue
+        digest.update(file_digest.digest())
+    return digest.hexdigest()
+
+
 def main() -> int:
     root = pathlib.Path(sys.argv[1])
+    if len(sys.argv) > 2 and sys.argv[2] == "--fingerprint":
+        print(fingerprint(root))
+        return 0
+
     label = sys.argv[2] if len(sys.argv) > 2 else "Warp cache"
 
     if not root.is_dir():

.github/actions/run-tests/run_tests.sh

@@ -305,6 +305,7 @@ run_tests() {
   docker run -d --name $container_name \
     --init --stop-timeout 5 \
     --entrypoint bash --gpus all --network=host \
+    -v "$PWD/.github/actions/_lib/with-python-package-retries.sh:/with-python-package-retries.sh:ro" \
     --security-opt=no-new-privileges:true \
     --memory=$(echo "$(free -m | awk '/^Mem:/{print $2}') * 0.9 / 1" | bc)m \
     --cpus=$(echo "$(nproc) * 0.9" | bc) \
@@ -321,7 +322,6 @@ run_tests() {
       mkdir -p tests
       rm _isaac_sim || true
       ln -s /isaac-sim _isaac_sim
-      ./isaaclab.sh -p -m pip install pytest pytest-mock junitparser flaky \"coverage>=7.6.1\"
       if [ -n \"\${WARP_CACHE_PATH:-}\" ]; then
         ./isaaclab.sh -p tools/verify_warp_cache.py
       fi
@@ -347,7 +347,7 @@ run_tests() {
       fi
       if [ -n \"\${TEST_EXTRA_PIP_PACKAGES:-}\" ]; then
         echo \"Installing extra pip packages: \${TEST_EXTRA_PIP_PACKAGES}\"
-        ./isaaclab.sh -p -m pip install \${TEST_EXTRA_PIP_PACKAGES}
+        bash /with-python-package-retries.sh ./isaaclab.sh -p -m pip install \${TEST_EXTRA_PIP_PACKAGES}
         case \" \${TEST_EXTRA_PIP_PACKAGES} \" in
           *\" leapp\"*)
             echo \"Resolved LEAPP package:\"
@@ -363,14 +363,14 @@ run_tests() {
         isaac_user_site=\"\$(./isaaclab.sh -p -c 'import site; print(site.getusersitepackages())' | tail -n 1)\"
         uv_executable=\"\$(./isaaclab.sh -p -c 'import pathlib, site; print(pathlib.Path(site.getuserbase()) / \"bin\" / \"uv\")' | tail -n 1)\"
         if [ ! -x \"\${uv_executable}\" ]; then
-          ./isaaclab.sh -p -m pip install uv
+          bash /with-python-package-retries.sh ./isaaclab.sh -p -m pip install uv
         fi
-        \"\${uv_executable}\" pip install --python \"\${isaac_python}\" --target \"\${isaac_user_site}\" \${TEST_EXTRA_UV_PACKAGES}
+        bash /with-python-package-retries.sh \"\${uv_executable}\" pip install --python \"\${isaac_python}\" --target \"\${isaac_user_site}\" \${TEST_EXTRA_UV_PACKAGES}
         # Isaac Sim puts bundled packages ahead of the user site. Overlay only
         # the explicitly requested packages so compatible direct pins win
         # without shadowing bundled transitive dependencies such as NumPy.
         isaac_uv_overlay=\"\$(mktemp -d)\"
-        \"\${uv_executable}\" pip install --python \"\${isaac_python}\" --target \"\${isaac_uv_overlay}\" --no-deps \${TEST_EXTRA_UV_PACKAGES}
+        bash /with-python-package-retries.sh \"\${uv_executable}\" pip install --python \"\${isaac_python}\" --target \"\${isaac_uv_overlay}\" --no-deps \${TEST_EXTRA_UV_PACKAGES}
         export PYTHONPATH=\"\${isaac_uv_overlay}\${PYTHONPATH:+:\${PYTHONPATH}}\"
       fi
       echo 'Starting pytest with path: $test_path'

.github/actions/upload-omni-github-test-results/action.yml

@@ -96,7 +96,8 @@ runs:
         # Validating with a local pinned copy of the schemas is recommended by the omni-github team.
         schema_venv="${RUNNER_TEMP}/omni-github-jsonschema-venv"
         python3 -m venv "$schema_venv"
-        "$schema_venv/bin/python" -m pip install -q jsonschema
+        bash "$GITHUB_WORKSPACE/.github/actions/_lib/with-python-package-retries.sh" \
+          "$schema_venv/bin/python" -m pip install -q jsonschema
         if ! "$schema_venv/bin/python" -m jsonschema \
           "$GITHUB_ACTION_PATH/result-json.schema.json" \
           --instance "$result_json"; then