@rainbow-robotics/muscat-plugin-kit 1.3.2 → 1.3.3-dev.0

package/cli/src/host_agent.py

@@ -1,10 +1,7 @@
-"""Host-side raw Zenoh byte-proxy.
+"""Host-side Zenoh byte-proxy for Docker Desktop containers (Mac/WSL remote dev).
 
-Runs on the host as a normal Zenoh peer (reverse-dials the robot, same as the
-SDK's own connect()) and serves a tiny domain-agnostic byte protocol over TCP
-— {query, put, subscribe} by keyexpr + bytes only — so a Docker Desktop
-container, which cannot join the robot's Zenoh mesh itself, can talk to a
-process that can.
+Joins the robot's Zenoh mesh with eclipse-zenoh (no rainbow SDK) and relays
+{query, put, subscribe} bytes over TCP to the dev container.
 
 Env: MUSCAT_ROBOT_HOST, MUSCAT_ROBOT_TOKEN, MUSCAT_ZENOH_ADVERTISE_HOST,
 MUSCAT_ZENOH_PORT (robot-facing), MUSCAT_PROXY_PORT (container-facing).
@@ -12,13 +9,21 @@ MUSCAT_ZENOH_PORT (robot-facing), MUSCAT_PROXY_PORT (container-facing).
 
 from __future__ import annotations
 
-import asyncio
 import contextlib
 import json
 import os
+import signal
 import socket
 import struct
+import sys
 import threading
+import urllib.error
+import urllib.request
+
+import zenoh
+
+PEER_TTL = 30
+QUERY_TARGETS = {0: zenoh.QueryTarget.BEST_MATCHING, 1: zenoh.QueryTarget.ALL, 2: zenoh.QueryTarget.ALL_COMPLETE}
 
 
 def _send_frame(conn: socket.socket, lock: threading.Lock, obj: dict) -> None:
@@ -44,102 +49,156 @@ def _recv_frame(conn: socket.socket) -> dict | None:
     return json.loads(buf.decode())
 
 
-def _handle_conn(conn: socket.socket, zenoh_client) -> None:
+def _att(sample) -> str:
+    return sample.attachment.to_string() if sample.attachment is not None else ""
+
+
+def _query(session: zenoh.Session, req: dict) -> list[dict]:
+    payload = bytes.fromhex(req["payload_hex"]) if req.get("payload_hex") else None
+    replies = session.get(
+        req["keyexpr"],
+        payload=payload,
+        timeout=req.get("timeout_ms", 2000) / 1000,
+        target=QUERY_TARGETS.get(req.get("target", 0), zenoh.QueryTarget.BEST_MATCHING),
+    )
+    out = []
+    for reply in replies:
+        if reply.ok is not None:
+            s = reply.ok
+            out.append({"key": str(s.key_expr), "payload_hex": s.payload.to_bytes().hex(),
+                        "att": _att(s), "encoding": str(s.encoding), "is_error": False})
+        else:
+            e = reply.err
+            out.append({"key": req["keyexpr"], "payload_hex": e.payload.to_bytes().hex(),
+                        "att": "", "encoding": str(e.encoding), "is_error": True})
+    return out
+
+
+def _handle_conn(conn: socket.socket, session: zenoh.Session) -> None:
     send_lock = threading.Lock()
-    sub_ids: dict[str, int] = {}
+    subs: dict[str, zenoh.Subscriber] = {}
     try:
         while True:
             req = _recv_frame(conn)
             if req is None:
                 return
             op = req.get("type")
+            rid = req.get("id")
 
-            if op == "query":
-                payload = bytes.fromhex(req["payload_hex"]) if req.get("payload_hex") else None
-                try:
-                    replies = zenoh_client._client.query(
-                        req["keyexpr"], payload, req.get("timeout_ms", 2000), req.get("target", 0)
-                    )
-                    out = {
-                        "type": "query_resp", "id": req["id"], "ok": True,
-                        "replies": [
-                            {"key": k, "payload_hex": bytes(p).hex(), "att": a, "encoding": e, "is_error": ie}
-                            for (k, p, a, e, ie) in replies
-                        ],
-                    }
-                except Exception as exc:
-                    out = {"type": "query_resp", "id": req["id"], "ok": False, "error": f"{type(exc).__name__}: {exc}"}
-                _send_frame(conn, send_lock, out)
-
-            elif op == "put":
-                payload = bytes.fromhex(req["payload_hex"]) if req.get("payload_hex") else b""
-                try:
-                    zenoh_client._client.publish(req["keyexpr"], payload, "", 0, 5, False)
-                    out = {"type": "put_resp", "id": req["id"], "ok": True}
-                except Exception as exc:
-                    out = {"type": "put_resp", "id": req["id"], "ok": False, "error": f"{type(exc).__name__}: {exc}"}
-                _send_frame(conn, send_lock, out)
-
-            elif op == "subscribe":
-                keyexpr = req["keyexpr"]
-
-                def on_sample(topic: str, payload_bytes: bytes, att: str, _ke: str = keyexpr) -> None:
-                    _send_frame(conn, send_lock, {
-                        "type": "sample", "keyexpr": _ke, "key": topic,
-                        "payload_hex": bytes(payload_bytes).hex(), "att": att,
-                    })
-
-                try:
-                    sub_id = zenoh_client._client.declare_subscriber(keyexpr, on_sample)
-                    sub_ids[keyexpr] = sub_id
-                    out = {"type": "subscribe_resp", "id": req["id"], "ok": True}
-                except Exception as exc:
-                    out = {"type": "subscribe_resp", "id": req["id"], "ok": False, "error": f"{type(exc).__name__}: {exc}"}
-                _send_frame(conn, send_lock, out)
-
-            elif op == "unsubscribe":
-                keyexpr = req["keyexpr"]
-                sub_id = sub_ids.pop(keyexpr, None)
-                if sub_id is not None:
-                    try:
-                        zenoh_client._client.undeclare_subscriber(sub_id)
-                    except Exception:
-                        pass
-                _send_frame(conn, send_lock, {"type": "unsubscribe_resp", "id": req["id"], "ok": True})
-
-            else:
-                _send_frame(conn, send_lock, {"type": "error", "error": f"unknown op {op!r}"})
+            try:
+                if op == "query":
+                    out = {"type": "query_resp", "id": rid, "ok": True, "replies": _query(session, req)}
+
+                elif op == "put":
+                    payload = bytes.fromhex(req["payload_hex"]) if req.get("payload_hex") else b""
+                    session.put(req["keyexpr"], payload)
+                    out = {"type": "put_resp", "id": rid, "ok": True}
+
+                elif op == "subscribe":
+                    keyexpr = req["keyexpr"]
+
+                    def on_sample(s, _ke: str = keyexpr) -> None:
+                        _send_frame(conn, send_lock, {
+                            "type": "sample", "keyexpr": _ke, "key": str(s.key_expr),
+                            "payload_hex": s.payload.to_bytes().hex(), "att": _att(s),
+                        })
+
+                    old = subs.pop(keyexpr, None)
+                    if old is not None:
+                        old.undeclare()
+                    subs[keyexpr] = session.declare_subscriber(keyexpr, on_sample)
+                    out = {"type": "subscribe_resp", "id": rid, "ok": True}
+
+                elif op == "unsubscribe":
+                    sub = subs.pop(req["keyexpr"], None)
+                    if sub is not None:
+                        with contextlib.suppress(Exception):
+                            sub.undeclare()
+                    out = {"type": "unsubscribe_resp", "id": rid, "ok": True}
+
+                else:
+                    out = {"type": "error", "error": f"unknown op {op!r}"}
+            except Exception as exc:
+                out = {"type": f"{op}_resp", "id": rid, "ok": False, "error": f"{type(exc).__name__}: {exc}"}
+            _send_frame(conn, send_lock, out)
     except (ConnectionResetError, BrokenPipeError, OSError):
         pass
     finally:
-        for sub_id in sub_ids.values():
-            try:
-                zenoh_client._client.undeclare_subscriber(sub_id)
-            except Exception:
-                pass
+        for sub in subs.values():
+            with contextlib.suppress(Exception):
+                sub.undeclare()
         conn.close()
 
 
-def main() -> None:
-    from rainbow.rb_sdk.base import RBBaseSDK
+class Peer:
+    """Registers this host with the robot's common: POST /zenoh/peer, heartbeat, DELETE."""
+
+    def __init__(self, host: str, token: str, ip: str, port: int) -> None:
+        self.base = f"http://{host}:8000"
+        self.headers = {"Content-Type": "application/json"}
+        if token:
+            self.headers["Authorization"] = f"Bearer {token}"
+        self.body = {"ip": ip, "port": port, "ttl": PEER_TTL}
+        self.peer_id: str | None = None
+        self.stop = threading.Event()
+
+    def _http(self, method: str, path: str, body: dict | None = None) -> dict:
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(self.base + path, data=data, headers=self.headers, method=method)
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            raw = resp.read()
+            return json.loads(raw) if raw else {}
+
+    def register(self) -> None:
+        self.peer_id = self._http("POST", "/zenoh/peer", self.body)["peer_id"]
+        print(f"[host-agent] registered with {self.base} as zenoh peer {self.peer_id}", flush=True)
 
+    def maintain(self) -> None:
+        while True:
+            wait = PEER_TTL / 2 if self.peer_id else 3
+            if self.stop.wait(wait):
+                return
+            try:
+                if self.peer_id is None:
+                    self.register()
+                elif not self._http("POST", f"/zenoh/peer/{self.peer_id}/heartbeat", {"ttl": PEER_TTL}).get("ok"):
+                    print(f"[host-agent] heartbeat rejected for {self.peer_id}, re-registering", flush=True)
+                    self.peer_id = None
+            except Exception as exc:
+                print(f"[host-agent] peer maintenance failed ({exc}); retrying", flush=True)
+                if self.peer_id is not None and isinstance(exc, urllib.error.HTTPError) and exc.code == 404:
+                    self.peer_id = None
+
+    def close(self) -> None:
+        self.stop.set()
+        if self.peer_id:
+            with contextlib.suppress(Exception):
+                self._http("DELETE", f"/zenoh/peer/{self.peer_id}")
+
+
+def main() -> None:
+    # dev stops us with SIGTERM; exit via `finally` to deregister.
+    signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
     host = os.environ["MUSCAT_ROBOT_HOST"]
     token = os.environ.get("MUSCAT_ROBOT_TOKEN", "")
     advertise = os.environ["MUSCAT_ZENOH_ADVERTISE_HOST"]
     zenoh_port = int(os.environ["MUSCAT_ZENOH_PORT"])
     proxy_port = int(os.environ["MUSCAT_PROXY_PORT"])
 
-    # The robot reverse-dials the advertised host:port; force it to the host's
-    # real LAN IP (matches what dev.mjs computed via ensureRemoteZenohEnv).
-    RBBaseSDK._detect_local_ip = staticmethod(lambda _host: advertise)
+    # Listen only; the robot dials in after registration.
+    conf = zenoh.Config()
+    conf.insert_json5("mode", '"peer"')
+    conf.insert_json5("listen/endpoints", json.dumps([f"tcp/0.0.0.0:{zenoh_port}"]))
+    conf.insert_json5("scouting/multicast/enabled", "false")
+    session = zenoh.open(conf)
 
-    peer = RBBaseSDK()
-    connect_kwargs = {"host": host, "zenoh_port": zenoh_port, "mesh_timeout": 15.0}
-    if token:
-        connect_kwargs["token"] = token
-
-    asyncio.run(peer.connect(**connect_kwargs))
-    print(f"[host-agent] zenoh peer joined robot mesh (listening :{zenoh_port})", flush=True)
+    peer = Peer(host, token, advertise, zenoh_port)
+    try:
+        peer.register()
+    except Exception as exc:
+        print(f"[host-agent] registration with {peer.base} failed, retrying in background: {exc}", flush=True)
+    threading.Thread(target=peer.maintain, daemon=True, name="zenoh-peer").start()
+    print(f"[host-agent] zenoh peer listening :{zenoh_port} (advertised as {advertise})", flush=True)
 
     srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
     srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
@@ -150,12 +209,13 @@ def main() -> None:
     try:
         while True:
             conn, _addr = srv.accept()
-            threading.Thread(target=_handle_conn, args=(conn, peer.zenoh_client), daemon=True).start()
+            threading.Thread(target=_handle_conn, args=(conn, session), daemon=True).start()
     except KeyboardInterrupt:
         pass
     finally:
+        peer.close()
         with contextlib.suppress(Exception):
-            asyncio.run(peer.disconnect())
+            session.close()
 
 
 if __name__ == "__main__":

package/cli/src/mcp.mjs

@@ -39,10 +39,11 @@ import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { kitRoot, kitVersion, findPluginRoot, venvPython } from "./util.mjs";
+import { PYTHON_DEV_IMAGE } from "./python.mjs";
 import { SHIPPED_STORIES_SRC, SHIPPED_DESIGN_TOKENS } from "./storybook.mjs";
 import { CPP_DEV_IMAGE } from "./cpp.mjs";
 
-const TEMPLATE_README = join(kitRoot, "cli/templates/common/README.md");
+const TEMPLATE_READMES = { python: "common/README.md", cpp: "readme-cpp/README.md" };
 // Design tokens: prefer the shipped copy, fall back to the monorepo source.
 const DESIGN_TOKENS_CSS = existsSync(SHIPPED_DESIGN_TOKENS)
   ? SHIPPED_DESIGN_TOKENS
@@ -260,10 +261,29 @@ function splitSections(text) {
   return sections;
 }
 
-function searchReadme(query) {
-  if (!existsSync(TEMPLATE_README)) return [];
-  const text = readFileSync(TEMPLATE_README, "utf8");
-  const sections = splitSections(text);
+// Standalone binaries have no templates/ on disk.
+async function readTemplateReadme(rel) {
+  const onDisk = join(kitRoot, "cli/templates", rel);
+  if (existsSync(onDisk)) return readFileSync(onDisk, "utf8");
+  try {
+    const { TEMPLATES } = await import("./templates-embedded.mjs");
+    return TEMPLATES[rel] ? Buffer.from(TEMPLATES[rel], "base64").toString("utf8") : "";
+  } catch {
+    return "";
+  }
+}
+
+async function searchReadme(query, lang) {
+  const langs = lang ? [lang] : ["python", "cpp"];
+  const seen = new Set();
+  const sections = [];
+  for (const l of langs) {
+    for (const section of splitSections(await readTemplateReadme(TEMPLATE_READMES[l]))) {
+      if (seen.has(section)) continue; // UI/manifest sections are shared by both READMEs
+      seen.add(section);
+      sections.push(langs.length > 1 && l === "cpp" ? `[C++ backend]\n${section}` : section);
+    }
+  }
   const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
 
   return sections
@@ -357,9 +377,6 @@ function pythonCmd() {
 // backend dependency). Returns a clear hint if it isn't importable.
 function introspectRbSdk(script) {
   const py = pythonCmd();
-  if (!py) {
-    return { error: "Python not found on PATH. Install Python 3 to use rb-sdk introspection." };
-  }
   const probe = `
 import json, importlib
 try:
@@ -368,10 +385,44 @@ except Exception as e:
     print(json.dumps({"__notinstalled__": str(e)})); raise SystemExit(0)
 ${script}
 `;
+  if (!py) {
+    return introspectInDocker(probe) ?? { error: "Python not found on PATH. Install Python 3 to use rb-sdk introspection." };
+  }
   const r = spawnSync(py, ["-c", probe], { encoding: "utf8", maxBuffer: 8 << 20 });
   if (r.status !== 0) {
     return { error: `python introspection failed: ${(r.stderr || "").trim().slice(0, 500)}` };
   }
+  const local = parseProbe(r);
+  return local.error && local.notInstalled ? introspectInDocker(probe) ?? local : local;
+}
+
+// No macOS wheels: import the plugin's pinned SDK inside the python dev image (cached).
+function introspectInDocker(probe) {
+  if (spawnSync("docker", ["image", "inspect", PYTHON_DEV_IMAGE], { encoding: "utf8" }).status !== 0) return null;
+  let ver = "";
+  try {
+    const req = readFileSync(join(findPluginRoot(), "requirements.txt"), "utf8");
+    ver = req.match(/^rainbow-rb-sdk==(\S+)/m)?.[1] ?? "";
+  } catch {
+    /* not a python plugin — latest */
+  }
+  // ponytail: "latest" cache is never refreshed; delete ~/.cache/... rb-sdk-py/latest to update.
+  const cache = join(UI_INDEX_CACHE_DIR, "rb-sdk-py", ver || "latest");
+  mkdirSync(cache, { recursive: true });
+  const pkg = ver ? `rainbow-rb-sdk==${ver}` : "rainbow-rb-sdk";
+  const script =
+    `[ -f /c/.ok ] || { pip3 install -q --break-system-packages --target /c '${pkg}' >&2 && touch /c/.ok; } && ` +
+    `PYTHONPATH=/c python3 -c "$PROBE"`;
+  const r = spawnSync("docker", ["run", "--rm", "-v", `${cache}:/c`, "-e", "PROBE", PYTHON_DEV_IMAGE, "bash", "-c", script], {
+    encoding: "utf8",
+    maxBuffer: 8 << 20,
+    env: { ...process.env, PROBE: probe },
+  });
+  if (r.status !== 0) return { error: `python introspection (docker) failed: ${(r.stderr || "").trim().slice(-500)}` };
+  return parseProbe(r);
+}
+
+function parseProbe(r) {
   // Importing rainbow.rb_sdk has side effects that print to stdout (e.g. the
   // Zenoh client logs its connection endpoints), ahead of our own final
   // print(json.dumps(...)) — so parse the last line, not the whole output.
@@ -384,6 +435,7 @@ ${script}
   }
   if (data && data.__notinstalled__) {
     return {
+      notInstalled: true,
       error:
         "rainbow-rb-sdk is not installed in this environment. Install it with `pip install rainbow-rb-sdk` " +
         "(it's already in a plugin's requirements.txt), then retry.",
@@ -445,7 +497,7 @@ function cppHeaders(root) {
 }
 
 // "class Foo {" / "class Foo : public Bar {" — not forward declarations.
-const CLASS_RE = /^\s*(?:class|struct)\s+(\w+)\b(?![^\n]*;\s*$)/;
+const CLASS_RE = /^\s*(?:class|struct)\s+(?:[A-Z][A-Z0-9_]*_API\s+)?(\w+)\b(?![^\n]*;\s*$)/; // skip export macros (RB_SDK_API)
 
 function cppClassesIn(text) {
   return [...new Set(text.split("\n").map((l) => l.match(CLASS_RE)?.[1]).filter(Boolean))];
@@ -630,17 +682,23 @@ export async function runMcp() {
         "rb.toast/alert/confirm/prompt, useRbFormData/useRbSave (save/restore form data through the " +
         "host), manifest.json (including the \"variables\" declaration for the pyfm variable picker — " +
         "names require the RBP_ prefix), program variables & executor state (ctx.get_variable/" +
-        "set_variable/executor_state/check_stop), contribution points, and backend runtimes " +
-        "(Python/C++/ROS2). IMPORTANT: " +
+        "set_variable/executor_state/check_stop), video streaming (MediaMTX: backend publishes RTSP to " +
+        "127.0.0.1:8554, UI plays WebRTC from :8889), contribution points, and backend runtimes " +
+        "(Python/C++/ROS2). Covers BOTH backends: the Python README (py/main.py, rainbow.rb_sdk) and the " +
+        "C++ README (cpp/main.cpp or an rclcpp node: rb_plugin::RBPluginCall serve/subscribe/publish/" +
+        "router(), rb_plugin::PluginProgramContext, RBManipulateSDK, CMake rb_sdk::rb_sdk). Pass lang " +
+        "\"python\" or \"cpp\" to match the plugin's manifest runtime (cpp or ros2+rclcpp → \"cpp\"); " +
+        "omit it to search both. IMPORTANT: " +
         "the backend pattern depends on the contribution point — search 'which backend pattern' before " +
-        "writing py/main.py. Only a program.panel command uses PluginProgramContext; a toolbar/move.panel " +
+        "writing the backend. Only a program.panel command uses PluginProgramContext; a toolbar/move.panel " +
         "plugin controls the robot with the SDK (RBManipulateSDK/RBAmrSDK) directly.",
       inputSchema: {
         query: z.string().describe('Keywords, e.g. "save form data" or "rb.action"'),
+        lang: z.enum(["python", "cpp"]).optional().describe("Backend language; omit to search both"),
       },
     },
-    async ({ query }) => {
-      const sections = searchReadme(query);
+    async ({ query, lang }) => {
+      const sections = await searchReadme(query, lang);
       if (sections.length === 0) {
         return { content: [{ type: "text", text: `No matching section found for "${query}".` }] };
       }
@@ -747,8 +805,9 @@ export async function runMcp() {
         "...) — call before writing py/main.py; requires rainbow-rb-sdk to be pip-installed. lang \"cpp\": " +
         "the C++ SDK headers (apt rainbow-rb-sdk-dev: RBManipulateSDK, rb_plugin::PluginProgramContext, " +
         "...) grouped by header path — call before writing cpp/main.cpp or an rclcpp node; requires the " +
-        "muscat-pk-cpp-dev Docker image (built by `muscat-pk dev:back`). Note: RBPluginCall (UI pub/sub/" +
-        "serve) exists in Python only.",
+        "muscat-pk-cpp-dev Docker image (built by `muscat-pk dev:back`). RBPluginCall (UI pub/sub/serve, " +
+        "router) exists in both: Python rainbow.rb_sdk.RBPluginCall, C++ rb_plugin::RBPluginCall " +
+        "(plugin/rb_plugin.hpp).",
       inputSchema: { lang: z.enum(["python", "cpp"]).optional().describe('Default "python"') },
     },
     async ({ lang }) => {

package/cli/src/new.mjs

@@ -17,7 +17,7 @@ import { color, ensureIdeVenv, hasBin, kitVersion, parseArgs, prompt, templatesD
 // Like cpSync(src, dst, {recursive:true}) but reads from the embedded snapshot
 // when the templates dir doesn't exist on disk (compiled binary mode).
 // ponytail: import() is module-cached by the runtime — no manual cache needed.
-async function copyTemplate(srcDir, dst) {
+export async function copyTemplate(srcDir, dst) {
   if (existsSync(templatesDir)) { cpSync(srcDir, dst, { recursive: true }); return; }
   const { TEMPLATES } = await import("./templates-embedded.mjs");
   const prefix = srcDir.slice(templatesDir.length + 1).replace(/\\/g, "/") + "/";
@@ -226,6 +226,9 @@ export async function runNew(args) {
     rmSync(resolve(target, "py"), { recursive: true, force: true });
     rmSync(resolve(target, "requirements.txt"), { force: true });
   }
+  if (runtimeChoice.type === "cpp" || runtimeChoice.rosClient === "rclcpp") {
+    await copyTemplate(resolve(templatesDir, "readme-cpp"), target);
+  }
 
   applyTokens(target, {
     __PLUGIN_ID__: pluginId,
@@ -250,7 +253,7 @@ export async function runNew(args) {
   // gitignore (templates can't ship a literal .gitignore via npm reliably)
   writeFileSync(
     resolve(target, ".gitignore"),
-    ["node_modules", "dist", ".muscat-dev", ".venv", "*.zip", "ros2_ws/install", "cpp/build", ""].join("\n"),
+    ["node_modules", "dist", ".muscat-dev", ".venv", "*.zip", "ros2_ws/install", "ros2_ws/build*", "ros2_ws/log", "cpp/build*", ""].join("\n"),
   );
 
   if (!opts["no-install"]) {

package/cli/src/ports.mjs

@@ -4,7 +4,15 @@ import { usesHostNetwork } from "./zenohDev.mjs";
 
 export const PLUGIN_PORT_MIN = 28600;
 export const PLUGIN_PORT_MAX = 28999;
-export const INTERNAL_DEV_PORTS = new Set([10000]);
+export const MEDIA_PORTS = [8554, 8889, 8189]; // MediaMTX: RTSP publish, WebRTC, WebRTC media
+export const INTERNAL_DEV_PORTS = new Set([10000, ...MEDIA_PORTS]);
+
+export function mediaPortFlags() {
+  return [
+    "-p", "127.0.0.1:8554:8554", "-p", "127.0.0.1:8889:8889",
+    "-p", "127.0.0.1:8189:8189/udp", "-p", "127.0.0.1:8189:8189/tcp",
+  ];
+}
 export const RESERVED_BACKEND_PORTS = new Map([
   [502, "Modbus TCP"],
   [4840, "OPC-UA"],
@@ -118,14 +126,21 @@ export function publishPortFlags(ranges = []) {
   return ranges.flatMap((port) => ["-p", `127.0.0.1:${port}:${port}`]);
 }
 
+// Skips OS-assigned loopback listeners (127.0.0.1:0, e.g. the SDK's Zenoh session).
 function listeningTcpPorts(container) {
   const script = `
+read -r eph_lo eph_hi < /proc/sys/net/ipv4/ip_local_port_range 2>/dev/null || { eph_lo=32768; eph_hi=60999; }
 for f in /proc/net/tcp /proc/net/tcp6; do
   [ -r "$f" ] || continue
   tail -n +2 "$f" | while read -r sl local_address rem_address st rest; do
     [ "$st" = "0A" ] || continue
-    hex_port="\${local_address##*:}"
-    printf "%d\\n" "0x$hex_port"
+    hex_ip="\${local_address%%:*}"
+    port=$((0x\${local_address##*:}))
+    case "$hex_ip" in
+      0100007F|00000000000000000000000001000000)
+        [ "$port" -ge "$eph_lo" ] && [ "$port" -le "$eph_hi" ] && continue ;;
+    esac
+    echo "$port"
   done
 done | sort -n -u
 `;
@@ -141,10 +156,9 @@ done | sort -n -u
 }
 
 export function startPortContractMonitor({ container, ranges, log, intervalMs = 1000, allow = [] }) {
-  // Under --network host the container shares the host's netns, so
-  // /proc/net/tcp shows every host/robot service port, not just the plugin's —
-  // the contract can't be enforced. Skip it (no isolated ports to police).
-  if (usesHostNetwork()) return () => false;
+  // Under --network host (or a local Muscat container's netns) /proc/net/tcp shows every
+  // host/robot service port, not just the plugin's — the contract can't be enforced.
+  if (usesHostNetwork() || process.env.MUSCAT_PK_MUSCAT_CONTAINER) return () => false;
   const declared = ranges ?? [];
   // muscat-pk's own dev plumbing shares this netns — not the plugin's doing.
   const ignored = new Set([...INTERNAL_DEV_PORTS, ...allow.map(Number).filter(Number.isInteger)]);

package/cli/src/python.mjs

@@ -3,7 +3,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { canSkipImageBuild, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+import { canSkipImageBuild, imageKey, imageKeyLabel, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
 
 export const PYTHON_DEV_IMAGE = "muscat-pk-python-dev";
 
@@ -15,16 +15,17 @@ export function assertDockerReady() {
 
 /** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
 export async function ensureImage(image = PYTHON_DEV_IMAGE, { platform = null } = {}) {
-  if (canSkipImageBuild(image)) {
+  const dockerfile = await resolveDockerfile("Dockerfile.python");
+  const key = imageKey(dockerfile);
+  if (canSkipImageBuild(image, key)) {
     log.step(`${image} already built — skipping docker build`);
     return;
   }
-  const dockerfile = await resolveDockerfile("Dockerfile.python");
   log.step(`docker build -t ${image}${platform ? ` (${platform})` : ""} (first run is slow, then cached)…`);
   const platformFlags = platform ? ["--platform", platform] : [];
   const r = spawnSync(
     "docker",
-    ["build", ...platformFlags, "-t", image, "-f", dockerfile, dirname(dockerfile)],
+    ["build", ...platformFlags, ...imageKeyLabel(key), "-t", image, "-f", dockerfile, dirname(dockerfile)],
     { stdio: "inherit" },
   );
   if (r.status !== 0) throw new Error("docker build failed.");
@@ -81,10 +82,9 @@ export async function lockAndVendor(pluginRoot, archs = ["amd64", "arm64"]) {
   if (lockResult.status !== 0) throw new Error("lock generation failed (uv pip compile)");
   log.ok("dist/requirements.lock ready");
 
-  const failed = [];
   for (const arch of archs) {
     const pipPlatforms = PIP_PLATFORM[arch];
-    if (!pipPlatforms) { log.warn(`unknown arch '${arch}' — skipped`); continue; }
+    if (!pipPlatforms) throw new Error(`unknown arch '${arch}'`);
     log.step(`vendoring wheels for ${arch}…`);
     const r = spawnSync(
       "docker",
@@ -102,16 +102,8 @@ export async function lockAndVendor(pluginRoot, archs = ["amd64", "arm64"]) {
       ],
       { stdio: "inherit" },
     );
-    if (r.status !== 0) {
-      log.warn(`wheel vendoring failed for ${arch}`);
-      failed.push(arch);
-    } else {
-      log.ok(`dist/wheels/ ready (${arch})`);
-    }
-  }
-
-  if (failed.length === archs.length) {
-    throw new Error(`wheel vendoring failed for all archs: ${failed.join(", ")}`);
+    // A ZIP missing wheels fails to import on the robot — stop instead.
+    if (r.status !== 0) throw new Error(`wheel download failed for ${arch} (see pip output above)`);
+    log.ok(`dist/wheels/ ready (${arch})`);
   }
-  return failed;
 }

package/cli/src/ros2.mjs

@@ -3,7 +3,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { canSkipImageBuild, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+import { canSkipImageBuild, imageKey, imageKeyLabel, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
 
 export const ROS2_DEV_IMAGE = "muscat-pk-ros2-dev";
 
@@ -30,15 +30,16 @@ export const ARCH_DOCKER_PLATFORM = {
 
 /** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
 export async function ensureImage(image = ROS2_DEV_IMAGE, { platform = null } = {}) {
-  if (canSkipImageBuild(image)) {
+  const dockerfile = await resolveDockerfile("Dockerfile.dev");
+  const sdkVer = process.env.MUSCAT_PK_RB_SDK_VERSION;
+  const key = imageKey(dockerfile, sdkVer ?? "");
+  if (canSkipImageBuild(image, key)) {
     log.step(`${image} already built — skipping docker build`);
     return;
   }
-  const dockerfile = await resolveDockerfile("Dockerfile.dev");
   log.step(`docker build -t ${image}${platform ? ` (${platform})` : ""} (first run is slow, then cached)…`);
   const platformFlags = platform ? ["--platform", platform] : [];
-  const sdkVer = process.env.MUSCAT_PK_RB_SDK_VERSION;
-  const buildArgs = sdkVer ? ["--build-arg", `RB_SDK_VERSION=${sdkVer}`] : [];
+  const buildArgs = [...(sdkVer ? ["--build-arg", `RB_SDK_VERSION=${sdkVer}`] : []), ...imageKeyLabel(key)];
   const r = spawnSync(
     "docker",
     ["build", ...platformFlags, ...buildArgs, "-t", image, "-f", dockerfile, dirname(dockerfile)],
@@ -73,12 +74,16 @@ export function colconBuild(root, { image = ROS2_DEV_IMAGE, symlink = false, arc
     installBase = "../dist/ros2_ws/install";
   }
   const flag = symlink ? "--symlink-install" : "";
+  const buildBase = symlink ? "build" : arch ? `build-${arch}` : "build-dist";
   const script = [
     "pip install -r requirements.txt --break-system-packages --ignore-installed -q || true",
     "cd ros2_ws",
-    // ponytail: rm only on cross-arch; same-arch dev rebuilds keep the cache
-    ...(arch ? ["rm -rf build"] : []),
-    `colcon build ${flag} --install-base ${installBase}`.trim(),
+    // Export builds use their own build cache: sharing build/ with dev's --symlink-install
+    // (or another arch) breaks the next colcon build.
+    // rclcpp export: ship librb_sdk.so in <pkg>/lib/ (robot has no SDK) when the node links it.
+    `colcon build ${flag} --build-base ${buildBase} --install-base ${installBase}`.replace("  ", " ") +
+      (arch ? ` --cmake-args '-DCMAKE_INSTALL_RPATH=$ORIGIN/..'` : ""),
+    ...(arch ? [`for d in ${installBase}/*/lib; do if readelf -d $(find "$d" -mindepth 2 -type f -executable) 2>/dev/null | grep -q librb_sdk; then cp -a $(dpkg -L rainbow-rb-sdk | grep -E '/librb_sdk[.]so[.][0-9]') "$d"/; fi; done`] : []),
   ].join(" && ");
   const label = arch
     ? `colcon build (${arch}) → dist/ros2_ws/install-${arch}/…`