Add a ROS 2 sandbox that builds, lints, tests and launches packages

worker/ros/Dockerfile (humble/jazzy) carries colcon, the ament linters, launch_testing,
ros2_control, Nav2, MoveIt 2, xacro, robot_state_publisher, tf2 and rosbag2 MCAP.
worker/ros_runner.py builds the package, runs the linters and tests, launches it for
10 s while recording every topic, and reports what came up or crashed. CI checks four
sample packages (good Python, good C++, one that does not compile, one that crashes)
in both distros. On Modal it runs without network or secrets.

.github/workflows/ci.yml

@@ -68,3 +68,56 @@ jobs:
           name: worker-smoke-output
           path: ci-out/runs/ci1
           if-no-files-found: warn
+
+  ros-sandbox:
+    name: ROS 2 sandbox (${{ matrix.distro }})
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        distro: [humble, jazzy]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build
+        run: docker build -f worker/ros/Dockerfile --build-arg ROS_DISTRO=${{ matrix.distro }} -t rosdiff-ros:ci .
+      - name: Check the sample packages (build, lint, test, launch, bag)
+        run: |
+          mkdir -p ros-out && chmod 777 ros-out
+          docker run --rm -i -v "$PWD/ros-out:/out" rosdiff-ros:ci python3 - <<'EOF'
+          import json
+          from pathlib import Path
+          from worker.ros_runner import check
+
+          def run(name):
+              root = Path("/app/samples") / name
+              files = {p.relative_to(root).as_posix(): p.read_text() for p in root.rglob("*") if p.is_file()}
+              r = check(files, "${{ matrix.distro }}", Path("/out") / name)
+              print(f"===== {name}: {r['headline']}")
+              print(json.dumps(r, indent=2)[:4000])
+              return r
+
+          r = run("good_py")
+          assert r["passed"] and r["build"]["ok"] and r["launch"]["ok"], r
+          assert "/heartbeat" in r["launch"]["nodes"], r["launch"]
+          assert any(t.startswith("/heartbeat ") for t in r["launch"]["topics"]), r["launch"]
+          assert r.get("bag_bytes", 0) > 0 and Path("/out/good_py/bag.mcap").is_file(), r
+
+          r = run("good_cpp")
+          assert r["passed"] and "/twist_source" in r["launch"]["nodes"], r
+          assert r["test"]["ran"] and r["test"]["tests"] > 0, r["test"]
+
+          r = run("broken_cpp")
+          assert not r["passed"] and not r["build"]["ok"], r
+          assert any("speed" in e for e in r["build"]["errors"]), r["build"]
+
+          r = run("crash_py")
+          assert r["build"]["ok"] and not r["launch"]["ok"] and r["launch"]["crashed"], r["launch"]
+          print("all sample checks behaved as expected")
+          EOF
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: ros-sandbox-${{ matrix.distro }}
+          path: ros-out
+          if-no-files-found: warn
+

worker/modal_app.py

@@ -59,3 +59,49 @@ def run_simulation(job_input: dict) -> dict:
     from worker.handler import handler
 
     return handler({"input": job_input})
+
+
+# --------------------------------------------------------------------------- ROS 2 sandbox (/code/check)
+
+
+def _ros_image(distro: str) -> modal.Image:
+    # Same Dockerfile CI builds and tests; Modal's own Python is added alongside the image's (the checks call
+    # ROS through bash with a clean environment, so the two never mix).
+    return modal.Image.from_dockerfile(
+        str(Path(__file__).parent / "ros" / "Dockerfile"),
+        context_dir=str(Path(__file__).parent.parent),
+        build_args={"ROS_DISTRO": distro},
+        add_python="3.11",
+    ).add_local_python_source("worker")
+
+
+# Generated code is untrusted: no network, no secrets. Results come back inline and the API stores them.
+_ROS_SANDBOX = dict(
+    cpu=2.0,
+    memory=4096,
+    timeout=900,
+    max_containers=int(os.environ.get("MODAL_MAX_CONTAINERS", "2")),
+    scaledown_window=20,
+    block_network=True,
+)
+
+
+@app.function(image=_ros_image("humble"), **_ROS_SANDBOX)
+def ros_check_humble(job_input: dict) -> dict:
+    return _ros_check(job_input, "humble")
+
+
+@app.function(image=_ros_image("jazzy"), **_ROS_SANDBOX)
+def ros_check_jazzy(job_input: dict) -> dict:
+    return _ros_check(job_input, "jazzy")
+
+
+def _ros_check(job_input: dict, distro: str) -> dict:
+    import traceback
+
+    from worker.ros_runner import run_check_job
+
+    try:
+        return run_check_job(job_input, distro)
+    except Exception as e:
+        return {"error": f"{type(e).__name__}: {e}", "traceback": traceback.format_exc()[-2000:]}

worker/ros/Dockerfile

@@ -0,0 +1,42 @@
+# ROS 2 sandbox for /code/check: build, lint, test and launch generated packages.
+#
+#   docker build -f worker/ros/Dockerfile --build-arg ROS_DISTRO=jazzy -t rosdiff-ros:jazzy .
+#
+# The tools most ROS 2 projects depend on are installed, so generated code that uses them builds:
+# colcon, ament linters, launch_testing, ros2_control (+ controllers), Nav2, MoveIt 2, xacro,
+# robot_state_publisher, tf2, rosbag2 with MCAP storage. Modal adds its own Python on top (add_python).
+ARG ROS_DISTRO=jazzy
+FROM ros:${ROS_DISTRO}-ros-base
+ARG ROS_DISTRO
+
+ENV DEBIAN_FRONTEND=noninteractive PYTHONUNBUFFERED=1
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential cmake git python3-colcon-common-extensions python3-pytest python3-numpy \
+        ros-${ROS_DISTRO}-ament-lint-common \
+        ros-${ROS_DISTRO}-ament-cmake-pytest \
+        ros-${ROS_DISTRO}-launch-testing-ament-cmake \
+        ros-${ROS_DISTRO}-launch-testing-ros \
+        ros-${ROS_DISTRO}-ros2-control \
+        ros-${ROS_DISTRO}-ros2-controllers \
+        ros-${ROS_DISTRO}-navigation2 \
+        ros-${ROS_DISTRO}-moveit-core \
+        ros-${ROS_DISTRO}-moveit-ros-planning-interface \
+        ros-${ROS_DISTRO}-moveit-msgs \
+        ros-${ROS_DISTRO}-xacro \
+        ros-${ROS_DISTRO}-robot-state-publisher \
+        ros-${ROS_DISTRO}-joint-state-publisher \
+        ros-${ROS_DISTRO}-tf2-ros \
+        ros-${ROS_DISTRO}-tf2-geometry-msgs \
+        ros-${ROS_DISTRO}-example-interfaces \
+        ros-${ROS_DISTRO}-rosbag2-storage-mcap \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY worker/__init__.py worker/ros_runner.py worker/
+COPY worker/ros/samples /app/samples
+
+# Fail the build if the tools cannot be found.
+RUN bash -c "source /opt/ros/${ROS_DISTRO}/setup.bash && ros2 pkg prefix nav2_msgs && ros2 pkg prefix moveit_core \
+    && ros2 pkg prefix controller_manager && ros2 pkg prefix xacro && ros2 pkg prefix rosbag2_storage_mcap \
+    && which ament_flake8 ament_cpplint ament_cppcheck ament_xmllint colcon"

worker/ros/samples/broken_cpp/rosdiff_broken_cpp/CMakeLists.txt

@@ -0,0 +1,9 @@
+cmake_minimum_required(VERSION 3.8)
+project(rosdiff_broken_cpp)
+find_package(ament_cmake REQUIRED)
+find_package(rclcpp REQUIRED)
+find_package(geometry_msgs REQUIRED)
+add_executable(broken src/broken.cpp)
+ament_target_dependencies(broken rclcpp geometry_msgs)
+install(TARGETS broken DESTINATION lib/${PROJECT_NAME})
+ament_package()

worker/ros/samples/broken_cpp/rosdiff_broken_cpp/package.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0"?>
+<package format="3">
+  <name>rosdiff_broken_cpp</name>
+  <version>0.1.0</version>
+  <maintainer email="dev@example.com">dev</maintainer>
+  <license>Apache-2.0</license>
+  <buildtool_depend>ament_cmake</buildtool_depend>
+  <depend>rclcpp</depend>
+  <depend>geometry_msgs</depend>
+  <exec_depend>launch_ros</exec_depend>
+  <export>
+    <build_type>ament_cmake</build_type>
+  </export>
+</package>

worker/ros/samples/broken_cpp/rosdiff_broken_cpp/src/broken.cpp

@@ -0,0 +1,11 @@
+// Deliberately does not compile: Twist has no field "speed".
+#include "geometry_msgs/msg/twist.hpp"
+#include "rclcpp/rclcpp.hpp"
+
+int main(int argc, char ** argv)
+{
+  rclcpp::init(argc, argv);
+  geometry_msgs::msg::Twist msg;
+  msg.speed = 1.0;
+  return 0;
+}

worker/ros/samples/crash_py/rosdiff_crash_py/launch/heartbeat.launch.py

@@ -0,0 +1,6 @@
+from launch import LaunchDescription
+from launch_ros.actions import Node
+
+
+def generate_launch_description():
+    return LaunchDescription([Node(package="rosdiff_crash_py", executable="heartbeat", output="screen")])

worker/ros/samples/crash_py/rosdiff_crash_py/package.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0"?>
+<package format="3">
+  <name>rosdiff_crash_py</name>
+  <version>0.1.0</version>
+  <description>Sample: publishes a heartbeat and checks that Nav2 and ros2_control messages are importable.</description>
+  <maintainer email="dev@example.com">dev</maintainer>
+  <license>Apache-2.0</license>
+  <depend>rclpy</depend>
+  <depend>std_msgs</depend>
+  <exec_depend>launch_ros</exec_depend>
+  <export>
+    <build_type>ament_python</build_type>
+  </export>
+</package>

worker/ros/samples/crash_py/rosdiff_crash_py/rosdiff_crash_py/heartbeat.py

@@ -0,0 +1,11 @@
+"""Sample that crashes on start (a parameter it needs is missing), to check crash detection."""
+
+import rclpy
+from rclpy.node import Node
+
+
+def main():
+    rclpy.init()
+    node = Node("crashes")
+    rate = node.get_parameter("rate").value  # never declared: raises ParameterNotDeclaredException
+    print(rate)

worker/ros/samples/crash_py/rosdiff_crash_py/setup.cfg

@@ -0,0 +1,4 @@
+[develop]
+script_dir=$base/lib/rosdiff_crash_py
+[install]
+install_scripts=$base/lib/rosdiff_crash_py

worker/ros/samples/crash_py/rosdiff_crash_py/setup.py

@@ -0,0 +1,23 @@
+from glob import glob
+
+from setuptools import setup
+
+package_name = "rosdiff_crash_py"
+
+setup(
+    name=package_name,
+    version="0.1.0",
+    packages=[package_name],
+    data_files=[
+        ("share/ament_index/resource_index/packages", ["resource/" + package_name]),
+        ("share/" + package_name, ["package.xml"]),
+        ("share/" + package_name + "/launch", glob("launch/*.launch.py")),
+    ],
+    install_requires=["setuptools"],
+    zip_safe=True,
+    maintainer="dev",
+    maintainer_email="dev@example.com",
+    description="Sample package",
+    license="Apache-2.0",
+    entry_points={"console_scripts": ["heartbeat = rosdiff_crash_py.heartbeat:main"]},
+)

worker/ros/samples/good_cpp/rosdiff_sample_cpp/CMakeLists.txt

@@ -0,0 +1,21 @@
+cmake_minimum_required(VERSION 3.8)
+project(rosdiff_sample_cpp)
+
+find_package(ament_cmake REQUIRED)
+find_package(rclcpp REQUIRED)
+find_package(geometry_msgs REQUIRED)
+find_package(moveit_msgs REQUIRED)
+
+add_executable(twist_source src/twist_source.cpp)
+ament_target_dependencies(twist_source rclcpp geometry_msgs moveit_msgs)
+install(TARGETS twist_source DESTINATION lib/${PROJECT_NAME})
+install(DIRECTORY launch DESTINATION share/${PROJECT_NAME})
+
+if(BUILD_TESTING)
+  find_package(ament_lint_auto REQUIRED)
+  set(ament_cmake_copyright_FOUND TRUE)
+  set(ament_cmake_uncrustify_FOUND TRUE)
+  ament_lint_auto_find_test_dependencies()
+endif()
+
+ament_package()

worker/ros/samples/good_cpp/rosdiff_sample_cpp/launch/twist.launch.xml

@@ -0,0 +1,3 @@
+<launch>
+  <node pkg="rosdiff_sample_cpp" exec="twist_source" output="screen"/>
+</launch>

worker/ros/samples/good_cpp/rosdiff_sample_cpp/package.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0"?>
+<package format="3">
+  <name>rosdiff_sample_cpp</name>
+  <version>0.1.0</version>
+  <description>Sample: C++ node using MoveIt 2 messages, with ament_lint_auto tests.</description>
+  <maintainer email="dev@example.com">dev</maintainer>
+  <license>Apache-2.0</license>
+  <buildtool_depend>ament_cmake</buildtool_depend>
+  <depend>rclcpp</depend>
+  <depend>geometry_msgs</depend>
+  <depend>moveit_msgs</depend>
+  <exec_depend>launch_ros</exec_depend>
+  <test_depend>ament_lint_auto</test_depend>
+  <test_depend>ament_lint_common</test_depend>
+  <export>
+    <build_type>ament_cmake</build_type>
+  </export>
+</package>

worker/ros/samples/good_cpp/rosdiff_sample_cpp/src/twist_source.cpp

@@ -0,0 +1,37 @@
+// Publishes a slow forward twist; including a MoveIt 2 message proves MoveIt is installed.
+#include <chrono>
+#include <memory>
+
+#include "geometry_msgs/msg/twist.hpp"
+#include "moveit_msgs/msg/robot_state.hpp"
+#include "rclcpp/rclcpp.hpp"
+
+using namespace std::chrono_literals;
+
+class TwistSource : public rclcpp::Node
+{
+public:
+  TwistSource()
+  : Node("twist_source")
+  {
+    pub_ = create_publisher<geometry_msgs::msg::Twist>("cmd_vel", 10);
+    timer_ = create_wall_timer(100ms, [this]() {
+        geometry_msgs::msg::Twist msg;
+        msg.linear.x = 0.1;
+        pub_->publish(msg);
+      });
+  }
+
+private:
+  rclcpp::Publisher<geometry_msgs::msg::Twist>::SharedPtr pub_;
+  rclcpp::TimerBase::SharedPtr timer_;
+  moveit_msgs::msg::RobotState unused_state_;
+};
+
+int main(int argc, char ** argv)
+{
+  rclcpp::init(argc, argv);
+  rclcpp::spin(std::make_shared<TwistSource>());
+  rclcpp::shutdown();
+  return 0;
+}

worker/ros/samples/good_py/rosdiff_sample_py/launch/heartbeat.launch.py

@@ -0,0 +1,6 @@
+from launch import LaunchDescription
+from launch_ros.actions import Node
+
+
+def generate_launch_description():
+    return LaunchDescription([Node(package="rosdiff_sample_py", executable="heartbeat", output="screen")])

worker/ros/samples/good_py/rosdiff_sample_py/package.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0"?>
+<package format="3">
+  <name>rosdiff_sample_py</name>
+  <version>0.1.0</version>
+  <description>Sample: publishes a heartbeat and checks that Nav2 and ros2_control messages are importable.</description>
+  <maintainer email="dev@example.com">dev</maintainer>
+  <license>Apache-2.0</license>
+  <depend>rclpy</depend>
+  <depend>std_msgs</depend>
+  <depend>nav2_msgs</depend>
+  <depend>control_msgs</depend>
+  <exec_depend>launch_ros</exec_depend>
+  <export>
+    <build_type>ament_python</build_type>
+  </export>
+</package>

worker/ros/samples/good_py/rosdiff_sample_py/rosdiff_sample_py/heartbeat.py

@@ -0,0 +1,28 @@
+"""Publishes a heartbeat; importing Nav2 and ros2_control messages proves they are installed."""
+
+import rclpy
+from control_msgs.msg import JointTrajectoryControllerState  # noqa: F401
+from nav2_msgs.action import NavigateToPose  # noqa: F401
+from rclpy.node import Node
+from std_msgs.msg import String
+
+
+class Heartbeat(Node):
+    def __init__(self):
+        super().__init__("heartbeat")
+        self.pub = self.create_publisher(String, "heartbeat", 10)
+        self.count = 0
+        self.create_timer(0.2, self.tick)
+
+    def tick(self):
+        self.count += 1
+        self.pub.publish(String(data=f"beat {self.count}"))
+
+
+def main():
+    rclpy.init()
+    node = Heartbeat()
+    try:
+        rclpy.spin(node)
+    except KeyboardInterrupt:
+        pass

worker/ros/samples/good_py/rosdiff_sample_py/setup.cfg

@@ -0,0 +1,4 @@
+[develop]
+script_dir=$base/lib/rosdiff_sample_py
+[install]
+install_scripts=$base/lib/rosdiff_sample_py

worker/ros/samples/good_py/rosdiff_sample_py/setup.py

@@ -0,0 +1,23 @@
+from glob import glob
+
+from setuptools import setup
+
+package_name = "rosdiff_sample_py"
+
+setup(
+    name=package_name,
+    version="0.1.0",
+    packages=[package_name],
+    data_files=[
+        ("share/ament_index/resource_index/packages", ["resource/" + package_name]),
+        ("share/" + package_name, ["package.xml"]),
+        ("share/" + package_name + "/launch", glob("launch/*.launch.py")),
+    ],
+    install_requires=["setuptools"],
+    zip_safe=True,
+    maintainer="dev",
+    maintainer_email="dev@example.com",
+    description="Sample package",
+    license="Apache-2.0",
+    entry_points={"console_scripts": ["heartbeat = rosdiff_sample_py.heartbeat:main"]},
+)

worker/ros_runner.py

@@ -0,0 +1,414 @@
+"""Build, lint, test and launch a generated ROS 2 package, the way a developer would on their machine.
+
+Runs inside the ROS 2 image (worker/ros/Dockerfile) as a sandbox: the Modal function has no network and no
+secrets, and every ROS command gets a scrubbed environment. Standard library only, so it runs with the image's
+own Python as well as Modal's.
+
+    python3 -m worker.ros_runner PACKAGE_DIR_OR_JSON --distro jazzy [--out OUT_DIR]
+
+Steps (each one's output is kept as a log file):
+    1. colcon build                      build.log
+    2. ament linters on the sources      lint.log   (flake8/pep257 for Python, cpplint/cppcheck for C++, xmllint)
+    3. colcon test, if it has tests      test.log   (launch_testing, pytest, gtest, ament_lint_auto)
+    4. launch it for a few seconds       launch.log (ros2 launch, or ros2 run for each executable without one)
+       while ros2 bag records every topic to MCAP  bag.mcap
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import random
+import re
+import shutil
+import signal
+import subprocess
+import tempfile
+import time
+import xml.etree.ElementTree as ET
+from pathlib import Path, PurePosixPath
+
+DISTROS = ("humble", "jazzy")
+BUILD_TIMEOUT = 600
+TEST_TIMEOUT = 300
+LINT_TIMEOUT = 120
+LAUNCH_SECONDS = 10
+MAX_BAG_BYTES = 20_000_000
+MAX_LOG_BYTES = 400_000
+LAUNCH_SUFFIXES = (".launch.py", "_launch.py", ".launch.xml", "_launch.xml", ".launch.yaml", "_launch.yaml")
+
+
+def _env(distro: str, home: Path) -> dict[str, str]:
+    """A clean environment: nothing from the host (no credentials), ROS traffic kept on localhost."""
+    env = {
+        "PATH": "/usr/local/sbin:/usr/sbin:/usr/bin:/sbin:/bin",
+        "HOME": str(home),
+        "LANG": "C.UTF-8",
+        "LC_ALL": "C.UTF-8",
+        "ROS_DISTRO": distro,
+        "ROS_DOMAIN_ID": str(random.randint(1, 100)),
+        "ROS_LOCALHOST_ONLY": "1",  # humble
+        "ROS_AUTOMATIC_DISCOVERY_RANGE": "LOCALHOST",  # jazzy
+        "PYTHONUNBUFFERED": "1",
+        "RCUTILS_COLORIZED_OUTPUT": "0",
+        "QT_QPA_PLATFORM": "offscreen",
+        "MAKEFLAGS": f"-j{os.cpu_count() or 2}",
+    }
+    return env
+
+
+def _bash(script: str, ws: Path, env: dict, timeout: float) -> tuple[int | None, str]:
+    """Run `script` in bash with ROS (and the workspace, once built) sourced. Returns (exit code or None, output)."""
+    distro = env["ROS_DISTRO"]
+    prelude = f"source /opt/ros/{distro}/setup.bash; [ -f install/setup.bash ] && source install/setup.bash; "
+    try:
+        p = subprocess.run(
+            ["bash", "-c", prelude + script],
+            cwd=ws,
+            env=env,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            errors="replace",
+        )
+        return p.returncode, p.stdout + p.stderr
+    except subprocess.TimeoutExpired as e:
+        out = (e.stdout or b"").decode(errors="replace") if isinstance(e.stdout, bytes) else (e.stdout or "")
+        return None, out + f"\n[rosdiff] timed out after {timeout:.0f}s\n"
+
+
+def write_workspace(files: dict[str, str], ws: Path) -> list[str]:
+    """Write the generated files under ws/src. Returns the package names found."""
+    src = ws / "src"
+    src.mkdir(parents=True, exist_ok=True)
+    for rel, content in files.items():
+        p = PurePosixPath(rel)
+        if p.is_absolute() or ".." in p.parts:
+            raise ValueError(f"unsafe path in package: {rel}")
+        dest = src / p
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(content)
+    names = []
+    for xml in sorted(src.rglob("package.xml")):
+        try:
+            name = ET.parse(xml).getroot().findtext("name")
+        except ET.ParseError:
+            name = None
+        if name:
+            names.append(name.strip())
+    return names
+
+
+# --------------------------------------------------------------------------- steps
+
+
+_MISSING = [
+    re.compile(r'provided by "([\w-]+)"'),  # CMake find_package
+    re.compile(r"No module named '([\w.]+)'"),  # Python import
+    re.compile(r"Package '([\w-]+)' not found"),  # ros2 launch / ament index
+]
+
+
+def missing_dependencies(text: str) -> list[str]:
+    found: list[str] = []
+    for pattern in _MISSING:
+        for name in pattern.findall(text):
+            if name not in found:
+                found.append(name)
+    return found
+
+
+def first_errors(text: str, limit: int = 8) -> list[str]:
+    """The first compiler/Python/CMake error lines, for the summary."""
+    keys = ("error:", "Error:", "CMake Error", "Traceback", "SyntaxError", "ModuleNotFoundError", "ImportError")
+    lines = [ln.strip() for ln in text.splitlines() if any(k in ln for k in keys)]
+    out: list[str] = []
+    for ln in lines:
+        if ln not in out:
+            out.append(ln[:300])
+        if len(out) >= limit:
+            break
+    return out
+
+
+def build(ws: Path, env: dict) -> dict:
+    code, log = _bash(
+        "colcon build --event-handlers console_direct+ --cmake-args -DBUILD_TESTING=ON -DCMAKE_BUILD_TYPE=Release",
+        ws,
+        env,
+        BUILD_TIMEOUT,
+    )
+    (ws / "build.log").write_text(log)
+    return {
+        "ok": code == 0,
+        "exit_code": code,
+        "errors": first_errors(log) if code != 0 else [],
+        "missing_dependencies": missing_dependencies(log) if code != 0 else [],
+    }
+
+
+def lint(ws: Path, env: dict, packages: dict[str, Path]) -> dict:
+    """ament linters, as `ament_lint_auto` would run them. Reported, never a failure on their own."""
+    results: dict[str, int] = {}
+    logs = []
+    for name, pkg in packages.items():
+        py = any(pkg.rglob("*.py"))
+        cpp = any(p.suffix in (".cpp", ".hpp", ".cc", ".h") for p in pkg.rglob("*"))
+        tools = ["ament_xmllint"]
+        if py:
+            tools += ["ament_flake8", "ament_pep257"]
+        if cpp:
+            tools += ["ament_cpplint", "ament_cppcheck"]
+        for tool in tools:
+            code, out = _bash(f"{tool} {pkg}", ws, env, LINT_TIMEOUT)
+            issues = _count_issues(tool, out) if code else 0
+            results[tool] = results.get(tool, 0) + issues
+            logs.append(f"===== {name}: {tool} (exit {code})\n{out}")
+    (ws / "lint.log").write_text("\n".join(logs))
+    return {"issues": results, "total": sum(results.values())}
+
+
+def _count_issues(tool: str, out: str) -> int:
+    m = re.search(r"(?:errors found: |^)(\d+)(?: (?:errors?|problems?))?\s*$", out, re.MULTILINE)
+    if m:
+        return int(m.group(1))
+    return max(1, sum(1 for ln in out.splitlines() if re.match(r"^\S+:\d+", ln)))
+
+
+def test(ws: Path, env: dict) -> dict:
+    code, log = _bash(
+        "colcon test --event-handlers console_direct+ --return-code-on-test-failure; "
+        "echo '===== colcon test-result'; colcon test-result --all --verbose",
+        ws,
+        env,
+        TEST_TIMEOUT,
+    )
+    (ws / "test.log").write_text(log)
+    m = re.search(r"Summary: (\d+) tests?, (\d+) errors?, (\d+) failures?, (\d+) skipped", log)
+    if not m:
+        return {"ran": False, "ok": code == 0}
+    total, errors, failures, skipped = map(int, m.groups())
+    return {
+        "ran": total > 0,
+        "ok": errors == 0 and failures == 0,
+        "tests": total,
+        "errors": errors,
+        "failures": failures,
+        "skipped": skipped,
+    }
+
+
+def _launch_targets(ws: Path, env: dict, packages: dict[str, Path]) -> list[tuple[str, list[str]]]:
+    """What to start: each package's launch file, else each of its executables (at most 3 per package)."""
+    targets = []
+    for name, pkg in packages.items():
+        launches = sorted(
+            p for p in pkg.rglob("*") if p.is_file() and p.name.endswith(LAUNCH_SUFFIXES) and "test" not in p.parts
+        )
+        if launches:
+            targets.append((f"ros2 launch {name} {launches[0].name}", [name, launches[0].name]))
+            continue
+        _, out = _bash(f"ros2 pkg executables {name}", ws, env, 60)
+        for line in out.splitlines()[:3]:
+            parts = line.split()
+            if len(parts) == 2 and parts[0] == name:
+                targets.append((f"ros2 run {name} {parts[1]}", parts))
+    return targets
+
+
+def _start(cmd: str, ws: Path, env: dict, log: Path) -> subprocess.Popen:
+    distro = env["ROS_DISTRO"]
+    script = f"source /opt/ros/{distro}/setup.bash; source install/setup.bash; exec {cmd}"
+    return subprocess.Popen(
+        ["bash", "-c", script],
+        cwd=ws,
+        env=env,
+        stdout=log.open("w"),
+        stderr=subprocess.STDOUT,
+        start_new_session=True,  # its own process group, so every node it spawns can be stopped
+    )
+
+
+def _stop(proc: subprocess.Popen, grace: float = 8.0) -> int | None:
+    if proc.poll() is not None:
+        return proc.returncode
+    for sig, wait in ((signal.SIGINT, grace), (signal.SIGTERM, 3.0), (signal.SIGKILL, 2.0)):
+        try:
+            os.killpg(proc.pid, sig)
+        except ProcessLookupError:
+            break
+        try:
+            proc.wait(wait)
+            break
+        except subprocess.TimeoutExpired:
+            continue
+    return None  # still running when we stopped it: that is what we want
+
+
+def launch(ws: Path, env: dict, packages: dict[str, Path], seconds: float = LAUNCH_SECONDS) -> dict:
+    targets = _launch_targets(ws, env, packages)
+    if not targets:
+        (ws / "launch.log").write_text("nothing to launch: no launch file and no executables\n")
+        return {"ok": False, "started": [], "error": "no launch file and no executables to start"}
+
+    logs_dir = ws / "launch_logs"
+    logs_dir.mkdir()
+    bag = subprocess.Popen(
+        [
+            "bash",
+            "-c",
+            f"source /opt/ros/{env['ROS_DISTRO']}/setup.bash; exec ros2 bag record -a -s mcap -o {ws / 'bag'}",
+        ],
+        cwd=ws,
+        env=env,
+        stdout=(logs_dir / "bag.log").open("w"),
+        stderr=subprocess.STDOUT,
+        start_new_session=True,
+    )
+    time.sleep(2.0)  # let the recorder subscribe before the nodes start publishing
+    procs = [(cmd, _start(cmd, ws, env, logs_dir / f"{i}.log")) for i, (cmd, _) in enumerate(targets)]
+    exited_early: list[tuple[str, int]] = []
+    deadline = time.monotonic() + seconds
+    graph: dict = {}
+    while time.monotonic() < deadline:
+        time.sleep(0.5)
+        for cmd, p in procs:
+            if p.poll() is not None and (cmd, p.returncode) not in exited_early:
+                exited_early.append((cmd, p.returncode))
+        if not graph and time.monotonic() > deadline - seconds / 2:
+            graph = _graph(ws, env)
+    if not graph:
+        graph = _graph(ws, env)
+    for _, p in procs:
+        _stop(p)
+    _stop(bag, grace=10.0)
+
+    texts = []
+    for i, (cmd, _) in enumerate(procs):
+        texts.append(f"===== {cmd}\n" + (logs_dir / f"{i}.log").read_text(errors="replace"))
+    texts.append("===== ros2 bag record\n" + (logs_dir / "bag.log").read_text(errors="replace"))
+    log = "\n".join(texts)
+    (ws / "launch.log").write_text(log)
+
+    died = re.findall(r"\[ERROR\] \[([^\]]+)\]: process has died \[pid \d+, exit code (-?\d+)", log)
+    crashed = [f"{name} (exit {code})" for name, code in died]
+    crashed += [f"{cmd} (exit {code})" for cmd, code in exited_early if code != 0]
+    tracebacks = first_errors(log)
+    ok = not crashed and bool(graph.get("nodes"))
+    return {
+        "ok": ok,
+        "started": [cmd for cmd, _ in procs],
+        "seconds": seconds,
+        "nodes": graph.get("nodes", []),
+        "topics": graph.get("topics", []),
+        "crashed": crashed,
+        "errors": tracebacks,
+        "missing_dependencies": missing_dependencies(log),
+        "error": None if ok else ("a node crashed" if crashed else "no ROS node came up"),
+    }
+
+
+def _graph(ws: Path, env: dict) -> dict:
+    _, nodes = _bash("ros2 node list --no-daemon --spin-time 2", ws, env, 30)
+    _, topics = _bash("ros2 topic list -t --no-daemon --spin-time 2", ws, env, 30)
+    hidden = ("/rosbag2", "/_ros2cli", "/launch_ros")
+    node_list = [n.strip() for n in nodes.splitlines() if n.startswith("/") and not n.strip().startswith(hidden)]
+    topic_list = [t.strip() for t in topics.splitlines() if t.startswith("/")]
+    return {"nodes": node_list, "topics": topic_list}
+
+
+# --------------------------------------------------------------------------- job
+
+
+def check(files: dict[str, str], distro: str, out: Path, launch_seconds: float = LAUNCH_SECONDS) -> dict:
+    if distro not in DISTROS:
+        raise ValueError(f"distro must be one of {DISTROS}")
+    started = time.monotonic()
+    root = Path(tempfile.mkdtemp(prefix="ros_check_"))
+    ws, home = root / "ws", root / "home"
+    home.mkdir(parents=True)
+    ws.mkdir()
+    env = _env(distro, home)
+    try:
+        names = write_workspace(files, ws)
+        if not names:
+            raise ValueError("no package.xml with a <name> in the generated files")
+        packages = {}
+        for xml in (ws / "src").rglob("package.xml"):
+            n = ET.parse(xml).getroot().findtext("name")
+            if n:
+                packages[n.strip()] = xml.parent
+        result: dict = {"distro": distro, "packages": names}
+        result["build"] = build(ws, env)
+        result["lint"] = lint(ws, env, packages)
+        if result["build"]["ok"]:
+            result["test"] = test(ws, env)
+            result["launch"] = launch(ws, env, packages, launch_seconds)
+        result["headline"] = headline(result)
+        result["passed"] = bool(result["build"]["ok"] and result.get("launch", {}).get("ok"))
+
+        out.mkdir(parents=True, exist_ok=True)
+        for name in ("build.log", "lint.log", "test.log", "launch.log"):
+            if (ws / name).is_file():
+                data = (ws / name).read_bytes()
+                (out / name).write_bytes(data[-MAX_LOG_BYTES:])
+        bags = sorted((ws / "bag").glob("*.mcap")) if (ws / "bag").is_dir() else []
+        if bags and bags[0].stat().st_size <= MAX_BAG_BYTES:
+            shutil.copy(bags[0], out / "bag.mcap")
+            result["bag_bytes"] = bags[0].stat().st_size
+        result["worker_seconds"] = round(time.monotonic() - started, 1)
+        (out / "summary.json").write_text(json.dumps(result, indent=2))
+        return result
+    finally:
+        shutil.rmtree(root, ignore_errors=True)
+
+
+def headline(r: dict) -> str:
+    if not r["build"]["ok"]:
+        missing = r["build"].get("missing_dependencies")
+        return "does not build" + (f" (missing: {', '.join(missing[:4])})" if missing else "")
+    parts = ["builds"]
+    la = r.get("launch") or {}
+    if la.get("ok"):
+        parts.append(f"{len(la['nodes'])} node(s) up, {len(la['topics'])} topic(s)")
+    else:
+        parts.append(f"launch failed: {la.get('error')}")
+    t = r.get("test") or {}
+    if t.get("ran"):
+        parts.append(f"tests {t['tests'] - t['failures'] - t['errors']}/{t['tests']} passed")
+    lint_total = (r.get("lint") or {}).get("total", 0)
+    parts.append(f"lint: {lint_total} issue(s)" if lint_total else "lint clean")
+    return " · ".join(parts)
+
+
+def run_check_job(job_input: dict, distro: str) -> dict:
+    """Worker entry point: returns the summary plus the logs/bag as inline artifacts (the API stores them)."""
+    files = job_input["files"]
+    if not isinstance(files, dict) or not files:
+        raise ValueError("files must be a non-empty {path: content} mapping")
+    with tempfile.TemporaryDirectory() as tmp:
+        out = Path(tmp)
+        summary = check(files, distro, out)
+        artifacts = {p.name: p.read_bytes() for p in sorted(out.iterdir()) if p.is_file()}
+    return {"summary": summary, "artifacts": artifacts, "worker_seconds": summary["worker_seconds"]}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("source", type=Path, help="a directory containing package(s), or a JSON {path: content} file")
+    parser.add_argument("--distro", default=os.environ.get("ROS_DISTRO", "jazzy"), choices=DISTROS)
+    parser.add_argument("--out", type=Path, default=Path("ros_check_out"))
+    parser.add_argument("--launch-seconds", type=float, default=LAUNCH_SECONDS)
+    args = parser.parse_args(argv)
+    if args.source.is_dir():
+        files = {p.relative_to(args.source).as_posix(): p.read_text() for p in args.source.rglob("*") if p.is_file()}
+    else:
+        files = json.loads(args.source.read_text())
+    result = check(files, args.distro, args.out, args.launch_seconds)
+    print(json.dumps(result, indent=2))
+    return 0 if result["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())