@rainbow-robotics/muscat-plugin-kit 1.10.1-dev.1 → 1.10.1

package/cli/src/devBack.mjs

@@ -1,727 +1,734 @@
-// muscat-pk dev:back — run the plugin back end during development.
-// Every backend runs in a warm Docker container that matches the robot
-// (Ubuntu 24.04), so dev behaves like production.
-//   python : Python 3.12 container, pip install, run main.py with watchfiles
-//            hot-reload. Shares the local Muscat container's netns (localhost:10000).
-//   cpp    : Ubuntu + cmake container, build cpp/, run the binary, rebuild +
-//            restart on source changes.
-//   ros2   : Jazzy + Python 3.12 container, colcon build, run the node, restart
-//            on source changes (rclcpp rebuilds on change).
-import { spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, watch, writeFileSync } from "node:fs";
-import { isIP } from "node:net";
-import { dirname, resolve } from "node:path";
-import { dockerUserFlags, ensureDocker, ensureIdeVenv, findPluginRoot, log, promptRobotConnection, realtimeFlags } from "./util.mjs";
-import { ensureRemoteZenohEnv, getFreePort, isRemoteRobot, usesHostNetwork } from "./zenohDev.mjs";
-import { GATEWAY_PORT, localMuscatContainer, robotHasMuscat } from "./muscatLocal.mjs";
-import { PLUGIN_ID_RE, assertManifestPorts, assertManifestVariables, manifestRuntime, readManifest, rosNamespace, validateManifest } from "./manifest.mjs";
-import {
-  portEnvFlags,
-  publishPortFlags,
-  startPortContractMonitor,
-} from "./ports.mjs";
-import {
-  PYTHON_DEV_IMAGE,
-  assertDockerReady as pyAssertDockerReady,
-  ensureImage as pyEnsureImage,
-} from "./python.mjs";
-import {
-  ROS2_DEV_IMAGE,
-  assertDockerReady,
-  ensureImage,
-  ros2PackageName,
-} from "./ros2.mjs";
-import {
-  CPP_DEV_IMAGE,
-  assertDockerReady as cppAssertDockerReady,
-  ensureImage as cppEnsureImage,
-} from "./cpp.mjs";
-
-const MANAGED_DEV_ENV = "MUSCAT_PK_MANAGED_DEV";
-
-function exitAfterCleanup(code = 0) {
-  if (process.env[MANAGED_DEV_ENV] !== "1") process.exit(code ?? 0);
-}
-
-export function stopDevBackContainers() {
-  for (const container of [
-    `${PYTHON_DEV_IMAGE}-run`,
-    `${ROS2_DEV_IMAGE}-run`,
-    `${CPP_DEV_IMAGE}-run`,
-  ]) {
-    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
-  }
-}
-
-// Where the backend's 127.0.0.1 points. A local Muscat container (muscat-pk-muscat, muscat-dev):
-// join its netns so the gateway and MediaMTX resolve like on the robot. Otherwise its own
-// netns, gateway via the host.
-// IS_DEV Muscat (muscat-dev): common is a zenoh-router client and opens no 7447 listener,
-// so the plugin must join the router too or `execute` queries never reach it.
-function muscatZenohEnv(container) {
-  const r = spawnSync("docker", ["inspect", "-f", "{{range .Config.Env}}{{println .}}{{end}}", container], { encoding: "utf8" });
-  return /^IS_DEV=(true|1)$/im.test(r.stdout || "")
-    ? ["-e", "ZENOH_PEER_CONNECT_ENDPOINTS=tcp/zenoh-router:7447"]
-    : [];
-}
-
-function backendNetwork(portRanges, robotGateway) {
-  const muscat = process.env.MUSCAT_PK_MUSCAT_CONTAINER;
-  if (muscat) return { run: ["--network", `container:${muscat}`], env: muscatZenohEnv(muscat), shared: true };
-  // The robot runs Muscat: its gateway, own netns (host network on Linux), declared ports published.
-  if (robotGateway) {
-    const run = usesHostNetwork() ? ["--network", "host"] : publishPortFlags(portRanges);
-    return { run, env: ["-e", `RB_PLUGIN_GATEWAY_URL=${robotGateway}`], shared: usesHostNetwork() };
-  }
-  if (usesHostNetwork()) return { run: ["--network", "host"], env: [], shared: true };
-  return {
-    // host.docker.internal is automatic on Docker Desktop; this makes it resolve on Linux too.
-    run: [...publishPortFlags(portRanges), "--add-host", "host.docker.internal:host-gateway"],
-    env: ["-e", "RB_PLUGIN_GATEWAY_URL=http://host.docker.internal:10000"],
-    shared: false,
-  };
-}
-
-// rb.rosPeers in dev: answer muscat/plugin/<id>/ros_peers/{get,set} on the gateway the way
-// Muscat (common) does on the robot — keep the list in .muscat-dev/ and restart the node
-// with ROS_STATIC_PEERS.
-const ROS_PEERS_FILE = ".muscat-dev/ros-peers.json";
-
-function readRosPeers(root) {
-  try {
-    return JSON.parse(readFileSync(resolve(root, ROS_PEERS_FILE), "utf8"));
-  } catch {
-    return [];
-  }
-}
-
-async function serveRosPeers(root, pluginId, restart) {
-  if (!pluginId) return;
-  const { RbWs } = await import("@rainbow-robotics/plugin-ui/ws");
-  const ws = await Promise.race([
-    RbWs.connect("http://127.0.0.1:10000", pluginId).catch(() => null),
-    new Promise((r) => setTimeout(() => r(null), 5000)),
-  ]);
-  if (!ws) return log.warn("rb.rosPeers unavailable in dev: plugin gateway not reachable on :10000");
-  const base = `/muscat/plugin/${pluginId}/ros_peers`;
-  await ws.serve(`${base}/get`, () => ({ peers: readRosPeers(root) }));
-  await ws.serve(`${base}/set`, (payload) => {
-    const peers = payload?.peers;
-    if (!Array.isArray(peers) || !peers.every((p) => typeof p === "string" && isIP(p))) {
-      return { ok: false, error: "peers must be a list of IP addresses" };
-    }
-    const file = resolve(root, ROS_PEERS_FILE);
-    mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, JSON.stringify(peers) + "\n");
-    log.step(`ROS_STATIC_PEERS → ${peers.join(";") || "(none)"} — restarting node`);
-    restart();
-    return { ok: true, peers };
-  });
-}
-
-// ── IDE tooling venv (best-effort, non-blocking) ────────────────────────────
-// `muscat-pk new` already creates this up front (see new.mjs); this just
-// refreshes it on every `dev`/`dev:back` in case requirements.txt changed.
-// Docker remains the actual execution environment — this never affects it.
-// Runs in the background so it never delays `dev:back` starting, and any
-// failure here (no local Python toolchain, offline, ...) is silent.
-function syncIdeVenv(root) {
-  setImmediate(() => {
-    try {
-      ensureIdeVenv(root);
-    } catch {
-      /* best-effort only */
-    }
-  });
-}
-
-// ── python ────────────────────────────────────────────────────────────────────
-// Runs in a warm Ubuntu 24.04 + Python 3.12 container (matches the robot).
-// Under `muscat-pk dev`, it shares the local Muscat container's netns, so the SDK
-// reaches the plugin gateway at the default localhost:10000.
-async function runPython(root, portRanges, robotGateway) {
-  // Independent of Docker readiness — must still happen if Docker isn't
-  // installed/running, since that's exactly when local IDE tooling matters most.
-  syncIdeVenv(root);
-  pyAssertDockerReady();
-  await pyEnsureImage();
-
-  const manifest = readManifest(root);
-  const pluginId = manifest.id ?? "";
-  const container = `${PYTHON_DEV_IMAGE}-run`;
-  const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
-  const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
-  const zenohAdvertiseHost = process.env.MUSCAT_ZENOH_ADVERTISE_HOST ?? "";
-  const zenohPort = process.env.MUSCAT_ZENOH_PORT ?? "";
-  // See host_agent.py: a Docker Desktop container can't join the robot's
-  // Zenoh mesh, so it speaks a byte protocol to the host-side proxy instead.
-  const proxyEndpoint = process.env.MUSCAT_PROXY_ENDPOINT ?? "";
-  // Native Linux (not WSL, not Docker Desktop) has real host networking: the
-  // container shares the host's network stack, so it reaches the gateway at
-  // localhost:10000 and the robot's Zenoh router / reverse-dial path directly
-  // — no netns sharing, port publishing, host.docker.internal, or byte-proxy.
-  const net = backendNetwork(portRanges, robotGateway);
-  // Only the container's OWN reverse-dial path needs to publish a listen port.
-  // With a shared netns the port is already reachable; with the byte-proxy
-  // the container just connects out — neither needs -p.
-  const standaloneZenohPortFlags =
-    !net.shared && !proxyEndpoint && zenohPort ? ["-p", `${zenohPort}:${zenohPort}`] : [];
-  // C++ SDK (rainbow-rb-sdk >= 0.10) can't use the byte shim: its Zenoh session is native. It listens
-  // on this published port instead and the entry script registers it with the robot (see there).
-  const sdkPeerPort = proxyEndpoint && !net.shared && zenohPort ? await getFreePort(Number(zenohPort) + 1) : "";
-  const envFlags = [
-    // docker exec below has no -t (no pseudo-TTY), so Python defaults to
-    // block-buffered stdout — print() output wouldn't show up until the
-    // buffer fills or the process exits. Force unbuffered.
-    "-e", "PYTHONUNBUFFERED=1",
-    ...net.env,
-    ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
-    ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
-    ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
-    // Byte-proxy mode: the container has no Zenoh session of its own — the
-    // entry script's shim speaks the raw query/put/subscribe protocol to the
-    // host_agent process at this address instead.
-    ...(proxyEndpoint ? ["-e", `MUSCAT_PROXY_ENDPOINT=${proxyEndpoint}`] : []),
-    ...(sdkPeerPort ? ["-e", `MUSCAT_SDK_PEER_PORT=${sdkPeerPort}`] : []),
-    // Fallback (no proxy): the container reverse-dials the robot itself.
-    ...(!proxyEndpoint && zenohAdvertiseHost ? ["-e", `MUSCAT_ZENOH_ADVERTISE_HOST=${zenohAdvertiseHost}`] : []),
-    ...(!proxyEndpoint && zenohPort ? ["-e", `MUSCAT_ZENOH_PORT=${zenohPort}`] : []),
-    ...portEnvFlags(portRanges),
-  ];
-  const docker = (args, opts = {}) =>
-    spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
-
-  // start a warm, long-lived container with the plugin mounted.
-  // 호스트 uid 로 돌린다(dockerUserFlags) — root 로 쓴 build/·install/ 은 사용자가 지우지 못한다.
-  docker(["rm", "-f", container], { stdio: "ignore" });
-  const up = docker(
-    ["run", "-d", "--name", container, ...net.run, ...standaloneZenohPortFlags, ...(sdkPeerPort ? ["-p", `${sdkPeerPort}:${sdkPeerPort}`] : []), ...realtimeFlags(), ...dockerUserFlags(),
-      "-e", "PIP_ROOT_USER_ACTION=ignore",
-      "-v", `${root}:/plugin`, "-w", "/plugin", PYTHON_DEV_IMAGE, "sleep", "infinity"],
-    { stdio: ["ignore", "ignore", "inherit"] }, // stdout is just the container id
-  );
-  if (up.status !== 0) throw new Error("failed to start dev container.");
-  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [zenohPort, sdkPeerPort] });
-
-  docker(["exec", container, "bash", "-lc",
-    "pip install --break-system-packages --ignore-installed -q watchfiles" +
-    " && { [ -f requirements.txt ] && pip install --break-system-packages --ignore-installed -q -r requirements.txt || true; }"]);
-
-  docker(["exec", container, "bash", "-lc", `cat > /tmp/muscat-pk-python-dev-entry.py <<'PY'
-import os
-
-try:
-    import glob
-    import importlib.util
-
-    proxy_endpoint = os.getenv("MUSCAT_PROXY_ENDPOINT")
-    # Located without importing: importing rainbow.rb_sdk opens the SDK's Zenoh session.
-    _rainbow = importlib.util.find_spec("rainbow")
-    cpp_sdk = bool(_rainbow and any(glob.glob(os.path.join(p, "rb_sdk", "rb_sdk_cpp*.so")) for p in _rainbow.submodule_search_locations))
-    if proxy_endpoint and cpp_sdk and os.getenv("MUSCAT_SDK_PEER_PORT"):
-        # C++ SDK (rainbow-rb-sdk >= 0.10): its Zenoh session is native, so the byte shim below
-        # can't reach it, and connect() would register the container's own unreachable IP.
-        # Listen on the published port and register the host's address for it instead, the
-        # same way host_agent registers itself; the robot then dials in through Docker.
-        import json
-        import threading
-        import time
-        import urllib.request
-
-        from rainbow.rb_sdk import rb_sdk_cpp
-
-        _port = int(os.environ["MUSCAT_SDK_PEER_PORT"])
-        os.environ["ZENOH_PEER_LISTEN_ENDPOINTS"] = f"tcp/0.0.0.0:{_port}"
-        for _cls in list(vars(rb_sdk_cpp).values()):
-            if isinstance(_cls, type) and issubclass(_cls, rb_sdk_cpp.RBBaseSDK) and "connect" in _cls.__dict__:
-                _cls.connect = lambda self, *args, **kwargs: None
-
-        def _peer_http(method, path, body=None):
-            headers = {"Content-Type": "application/json"}
-            if os.getenv("MUSCAT_ROBOT_TOKEN"):
-                headers["Authorization"] = "Bearer " + os.environ["MUSCAT_ROBOT_TOKEN"]
-            req = urllib.request.Request(f"http://{os.environ['MUSCAT_ROBOT_HOST']}:8000{path}",
-                                         data=json.dumps(body).encode() if body is not None else None,
-                                         headers=headers, method=method)
-            with urllib.request.urlopen(req, timeout=10) as resp:
-                raw = resp.read()
-                return json.loads(raw) if raw else {}
-
-        def _peer_keepalive():
-            advertise = proxy_endpoint.rsplit(":", 1)[0]
-            peer_id = None
-            while True:
-                try:
-                    if peer_id is None:
-                        peer_id = _peer_http("POST", "/zenoh/peer", {"ip": advertise, "port": _port, "ttl": 30})["peer_id"]
-                        print(f"[muscat-pk] C++ SDK zenoh peer {advertise}:{_port} registered with the robot", flush=True)
-                    elif not _peer_http("POST", f"/zenoh/peer/{peer_id}/heartbeat", {"ttl": 30}).get("ok"):
-                        peer_id = None
-                        continue
-                except Exception as exc:
-                    print(f"[muscat-pk] zenoh peer registration failed ({exc}); retrying", flush=True)
-                    peer_id = None
-                time.sleep(15 if peer_id else 3)
-
-        threading.Thread(target=_peer_keepalive, daemon=True).start()
-    elif proxy_endpoint:
-        # Byte-proxy mode: this container has no Zenoh session of its own.
-        # ZenohClient's C++ core is replaced with a shim that speaks a raw
-        # query/put/subscribe byte protocol to host_agent.py instead.
-        import json
-        import socket
-        import struct
-        import threading
-
-        _proxy_host, _proxy_port_s = proxy_endpoint.rsplit(":", 1)
-        _proxy_port = int(_proxy_port_s)
-
-        def _send_frame(conn, lock, obj):
-            body = json.dumps(obj).encode()
-            with lock:
-                conn.sendall(struct.pack(">I", len(body)) + body)
-
-        def _recv_frame(conn):
-            hdr = b""
-            while len(hdr) < 4:
-                chunk = conn.recv(4 - len(hdr))
-                if not chunk:
-                    return None
-                hdr += chunk
-            n = struct.unpack(">I", hdr)[0]
-            buf = b""
-            while len(buf) < n:
-                chunk = conn.recv(n - len(buf))
-                if not chunk:
-                    return None
-                buf += chunk
-            return json.loads(buf.decode())
-
-        class _ProxyRawClient:
-            """Drop-in replacement for ZenohClient's C++ core, backed by the
-            host_agent byte-proxy instead of a local Zenoh session."""
-
-            sender = "RRS"
-            sender_id = ""
-
-            def __init__(self, host, port):
-                self._conn = socket.create_connection((host, port), timeout=10)
-                # create_connection() leaves the connect timeout applied to
-                # the socket permanently; the background read loop below does
-                # a long-lived blocking recv() for async "sample" pushes, so
-                # it must not time out on an idle connection.
-                self._conn.settimeout(None)
-                self._send_lock = threading.Lock()
-                self._req_id = 0
-                self._req_lock = threading.Lock()
-                self._pending = {}
-                self._subs = {}  # sub_id -> callback
-                self._sub_by_keyexpr = {}
-                threading.Thread(target=self._read_loop, daemon=True).start()
-
-            def _next_id(self):
-                with self._req_lock:
-                    self._req_id += 1
-                    return self._req_id
-
-            def _read_loop(self):
-                while True:
-                    frame = _recv_frame(self._conn)
-                    if frame is None:
-                        return
-                    ftype = frame.get("type")
-                    if ftype == "sample":
-                        cb = self._sub_by_keyexpr.get(frame["keyexpr"])
-                        if cb is not None:
-                            try:
-                                cb(frame["key"], bytes.fromhex(frame["payload_hex"]), frame.get("att", ""))
-                            except Exception as exc:
-                                print(f"[muscat-pk] proxy subscriber callback error: {exc}", flush=True)
-                    elif "id" in frame:
-                        ev = self._pending.pop(frame["id"], None)
-                        if ev is not None:
-                            ev[1] = frame
-                            ev[0].set()
-
-            def _request(self, obj, timeout=30):
-                req_id = self._next_id()
-                obj["id"] = req_id
-                ev = threading.Event()
-                slot = [ev, None]
-                self._pending[req_id] = slot
-                _send_frame(self._conn, self._send_lock, obj)
-                if not ev.wait(timeout):
-                    self._pending.pop(req_id, None)
-                    raise TimeoutError(f"proxy request timed out: {obj.get('type')} {obj.get('keyexpr')}")
-                return slot[1]
-
-            def query(self, keyexpr, payload, timeout_ms, target):
-                resp = self._request({
-                    "type": "query", "keyexpr": keyexpr,
-                    "payload_hex": payload.hex() if payload else None,
-                    "timeout_ms": timeout_ms, "target": target,
-                }, timeout=(timeout_ms / 1000) + 5)
-                if not resp.get("ok"):
-                    raise RuntimeError(resp.get("error", "proxy query failed"))
-                return [
-                    (r["key"], bytes.fromhex(r["payload_hex"]), r["att"], r["encoding"], r["is_error"])
-                    for r in resp["replies"]
-                ]
-
-            def query_all(self, keyexpr, payload, timeout_ms, target):
-                return self.query(keyexpr, payload, timeout_ms, target)
-
-            def publish(self, topic, payload, att, congestion_control, priority, express):
-                resp = self._request({
-                    "type": "put", "keyexpr": topic,
-                    "payload_hex": bytes(payload).hex() if payload else None,
-                })
-                if not resp.get("ok"):
-                    raise RuntimeError(resp.get("error", "proxy put failed"))
-
-            def has_subscriber(self, topic):
-                return topic in self._sub_by_keyexpr
-
-            def declare_subscriber(self, topic, callback, opts=None):
-                resp = self._request({"type": "subscribe", "keyexpr": topic})
-                if not resp.get("ok"):
-                    raise RuntimeError(resp.get("error", "proxy subscribe failed"))
-                sub_id = self._next_id()
-                self._subs[sub_id] = topic
-                self._sub_by_keyexpr[topic] = callback
-                return sub_id
-
-            def undeclare_subscriber(self, sub_id):
-                topic = self._subs.pop(sub_id, None)
-                if topic is None:
-                    return
-                self._sub_by_keyexpr.pop(topic, None)
-                self._request({"type": "unsubscribe", "keyexpr": topic})
-
-            def unsubscribe_topic(self, topic):
-                for sub_id, t in list(self._subs.items()):
-                    if t == topic:
-                        self.undeclare_subscriber(sub_id)
-
-            def unsubscribe_all(self):
-                for sub_id in list(self._subs):
-                    self.undeclare_subscriber(sub_id)
-
-            def get_sub_stats(self, sub_id):
-                return {}
-
-            def declare_queryable(self, keyexpr, handler):
-                raise NotImplementedError("byte-proxy mode does not support declare_queryable")
-
-            def undeclare_queryable_by_topic(self, keyexpr):
-                pass
-
-        # ZenohClient is a process-wide singleton whose __init__ eagerly
-        # calls connect() on first construction. rainbow.rb_sdk.base
-        # transitively imports rainbow.rb_log.log, which constructs one at
-        # module level — so this patch must land before RBBaseSDK is
-        # imported, or that eager construction wins with a real session.
-        from rainbow.rb_zenoh.client import ZenohClient
-
-        def _proxy_connect(self, *, config_pairs=None, sender=None, max_attempts=8, initial_delay_s=0.5, max_delay_s=3.0):
-            if self._client is not None:
-                return
-            if sender is not None:
-                self._sender = sender
-            print(f"[muscat-pk] zenoh via host byte-proxy → {proxy_endpoint} (no local Zenoh session)", flush=True)
-            self._client = _ProxyRawClient(_proxy_host, _proxy_port)
-
-        ZenohClient.connect = _proxy_connect
-
-        from rainbow.rb_sdk.base import RBBaseSDK
-
-        async def _sdk_connect_via_proxy(self, *args, **kwargs):
-            # No HTTP registration with common — host_agent already handles
-            # that. Just make sure the (proxy-backed) shared ZenohClient exists.
-            self._ensure_zenoh_client_alive()
-            return None
-
-        async def _sdk_disconnect_via_proxy(self, *args, **kwargs):
-            return None
-
-        RBBaseSDK.connect = _sdk_connect_via_proxy
-        RBBaseSDK.disconnect = _sdk_disconnect_via_proxy
-    else:
-        # Fallback: no host byte-proxy — the container reverse-dials the robot itself.
-        advertise_host = os.getenv("MUSCAT_ZENOH_ADVERTISE_HOST")
-        zenoh_port = os.getenv("MUSCAT_ZENOH_PORT")
-        from rainbow.rb_sdk.base import RBBaseSDK
-        if advertise_host:
-            RBBaseSDK._detect_local_ip = staticmethod(lambda host: advertise_host)
-        if zenoh_port:
-            _orig_connect = RBBaseSDK.connect
-
-            async def _connect_with_dev_port(self, *args, **kwargs):
-                kwargs.setdefault("zenoh_port", int(zenoh_port))
-                return await _orig_connect(self, *args, **kwargs)
-
-            RBBaseSDK.connect = _connect_with_dev_port
-except Exception as exc:
-    print(f"[muscat-pk] SDK dev network patch skipped: {exc}", flush=True)
-
-import runpy
-runpy.run_path("/plugin/py/main.py", run_name="__main__")
-PY`]);
-
-  if (usesHostNetwork()) log.step("network: host (native Linux — direct robot/gateway access)");
-  if (proxyEndpoint) log.step(`Zenoh via host byte-proxy → ${proxyEndpoint}`);
-  else if (zenohAdvertiseHost && zenohPort) log.step(`Zenoh advertise → ${zenohAdvertiseHost}:${zenohPort}`);
-  const child = spawn(
-    "docker",
-    ["exec", ...envFlags, container, "bash", "-lc",
-      "python3 -m watchfiles --filter python --target-type command 'python3 /tmp/muscat-pk-python-dev-entry.py' py"],
-    { cwd: root, stdio: ["inherit", "inherit", "pipe"] },
-  );
-  // watchfiles prints a KeyboardInterrupt traceback on SIGTERM — suppress it
-  child.stderr.on("data", (buf) => {
-    const text = buf.toString();
-    if (!text.includes("KeyboardInterrupt") && !text.includes("raise_keyboard_interrupt")) {
-      process.stderr.write(buf);
-    }
-  });
-
-  let cleaned = false;
-  const cleanupResources = () => {
-    if (cleaned) return;
-    cleaned = true;
-    stopPortMonitor();
-    if (!child.killed && child.exitCode === null) child.kill();
-    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
-  };
-  const cleanup = () => {
-    cleanupResources();
-    exitAfterCleanup(0);
-  };
-  child.on("exit", (code) => {
-    cleanupResources();
-    exitAfterCleanup(code ?? 0);
-  });
-  process.once("SIGINT", cleanup);
-  process.once("SIGTERM", cleanup);
-  process.once("SIGHUP", cleanup);
-}
-
-// ── ros2 ───────────────────────────────────────────────────────────────────────
-async function runRos2(root, portRanges, robotGateway) {
-  const manifest = readManifest(root);
-  const isRclcpp = manifest.runtime?.rosClient === "rclcpp";
-  // Independent of Docker readiness — must still happen if Docker isn't
-  // installed/running, since that's exactly when local IDE tooling matters most.
-  if (!isRclcpp) syncIdeVenv(root); // rclpy is plain Python — rclcpp is C++, no venv needed
-
-  assertDockerReady();
-  const pkg = ros2PackageName(root);
-  if (!pkg) throw new Error("no ROS2 package found under ros2_ws/src.");
-
-  await ensureImage();
-
-  const pluginId = manifest.id ?? "";
-  const container = `${ROS2_DEV_IMAGE}-run`;
-  const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
-  const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
-  const net = backendNetwork(portRanges, robotGateway);
-  const envFlags = [
-    // Same rationale as runPython(): no -t on docker exec below means
-    // rclpy's Python process stdout is block-buffered, not line-buffered.
-    "-e", "PYTHONUNBUFFERED=1",
-    // Same as the robot: ROS discovery stays on this host (allow a PC with ROS_STATIC_PEERS).
-    "-e", "ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST",
-    ...net.env,
-    ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
-    ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
-    ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
-    ...portEnvFlags(portRanges),
-  ];
-  const docker = (args, opts = {}) =>
-    spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
-
-  // start a warm, long-lived container with the workspace mounted
-  docker(["rm", "-f", container], { stdio: "ignore" });
-  const up = docker(
-    ["run", "-d", "--name", container, ...net.run, ...realtimeFlags(), ...dockerUserFlags(), "-e", "PIP_ROOT_USER_ACTION=ignore", "-v", `${root}:/plugin`, "-w", "/plugin", ROS2_DEV_IMAGE, "sleep", "infinity"],
-    { stdio: ["ignore", "ignore", "inherit"] }, // stdout is just the container id
-  );
-  if (up.status !== 0) throw new Error("failed to start dev container.");
-  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [process.env.MUSCAT_ZENOH_PORT] });
-
-  // one-time deps + symlink build (edits to .py reflect without rebuilding)
-  docker(["exec", container, "bash", "-lc",
-    "pip install -r requirements.txt --break-system-packages --ignore-installed -q || true; cd ros2_ws && colcon build --symlink-install"]);
-
-  let child = null;
-  const startNode = () => {
-    if (child) child.kill();
-    // killing the `docker exec` client doesn't stop the node inside the container
-    spawnSync("docker", ["exec", container, "pkill", "-f", `${pkg}_node|${manifest.runtime?.launch || pkg}`], { stdio: "ignore" });
-    const peers = readRosPeers(root);
-    // Same command the robot runs: rclpy execs the console script, rclcpp uses `ros2 run`;
-    // relative topics land under the plugin's namespace (rosNamespace).
-    const launch = manifest.runtime?.launch || `${pkg}_node`;
-    const nsArgs = PLUGIN_ID_RE.test(pluginId) ? ` --ros-args -r __ns:=${rosNamespace(pluginId)}` : "";
-    const run = (isRclcpp ? `ros2 run ${pkg} ${launch}` : `exec ${launch}`) + nsArgs;
-    child = spawn(
-      "docker",
-      ["exec", ...envFlags, ...(peers.length ? ["-e", `ROS_STATIC_PEERS=${peers.join(";")}`] : []), container, "bash", "-lc",
-        `cd ros2_ws && source install/setup.bash && ${run}`],
-      { cwd: root, stdio: "inherit" },
-    );
-  };
-  startNode();
-  serveRosPeers(root, pluginId, startNode);
-
-  // restart node on source change. rclpy reflects .py edits live (symlink-install);
-  // rclcpp (C++) and package-metadata changes require a colcon rebuild.
-  let timer = null;
-  const onChange = (_event, filename) => {
-    clearTimeout(timer);
-    timer = setTimeout(() => {
-      const structural = filename && /(setup\.py|package\.xml|CMakeLists\.txt)$/.test(String(filename));
-      if (structural || isRclcpp) {
-        log.info(structural ? "package metadata changed — colcon rebuild…" : "source changed — colcon rebuild…");
-        docker(["exec", container, "bash", "-lc", "cd ros2_ws && colcon build --symlink-install"]);
-      } else {
-        log.info("source changed — restarting node…");
-      }
-      startNode();
-    }, 300);
-  };
-  for (const target of ["ros2_ws/src", "main.py"]) {
-    const full = resolve(root, target);
-    if (existsSync(full)) watch(full, { recursive: true }, onChange);
-  }
-
-  const cleanup = () => {
-    stopPortMonitor();
-    if (child) child.kill();
-    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
-    exitAfterCleanup(0);
-  };
-  process.on("SIGINT", cleanup);
-  process.on("SIGTERM", cleanup);
-  process.on("SIGHUP", cleanup);
-}
-
-// ── cpp ──────────────────────────────────────────────────────────────────────
-async function runCpp(root, portRanges, robotGateway) {
-  cppAssertDockerReady();
-  const manifest = readManifest(root);
-  const entry = manifest.runtime?.entry;
-  if (!entry) throw new Error("runtime.entry (the built executable name) is required for cpp.");
-
-  await cppEnsureImage();
-
-  const pluginId = manifest.id ?? "";
-  const container = `${CPP_DEV_IMAGE}-run`;
-  const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
-  const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
-  const net = backendNetwork(portRanges, robotGateway);
-  const envFlags = [
-    ...net.env,
-    ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
-    ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
-    ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
-    ...portEnvFlags(portRanges),
-  ];
-  const docker = (args, opts = {}) =>
-    spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
-
-  // start a warm, long-lived container with the plugin mounted
-  docker(["rm", "-f", container], { stdio: "ignore" });
-  const up = docker(
-    ["run", "-d", "--name", container, ...net.run, ...realtimeFlags(), ...dockerUserFlags(), "-v", `${root}:/plugin`, "-w", "/plugin", CPP_DEV_IMAGE, "sleep", "infinity"],
-    { stdio: ["ignore", "ignore", "inherit"] }, // stdout is just the container id
-  );
-  if (up.status !== 0) throw new Error("failed to start dev container.");
-  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [process.env.MUSCAT_ZENOH_PORT] });
-
-  const build = () => {
-    return docker(["exec", container, "bash", "-lc",
-      "cmake -S cpp -B cpp/build -DCMAKE_BUILD_TYPE=Debug && cmake --build cpp/build -j"]);
-  };
-  build();
-
-  let child = null;
-  const startBin = () => {
-    if (child) child.kill();
-    child = spawn(
-      "docker",
-      ["exec", ...envFlags, container, "bash", "-lc", `./cpp/build/${entry}`],
-      { cwd: root, stdio: "inherit" },
-    );
-  };
-  startBin();
-
-  // rebuild + restart on C++ source changes; ignore the build/ output dir.
-  let timer = null;
-  const onChange = (_event, filename) => {
-    if (filename && String(filename).startsWith("build")) return;
-    clearTimeout(timer);
-    timer = setTimeout(() => {
-      log.info("source changed — rebuilding…");
-      const r = build();
-      if (r.status === 0) startBin();
-      else log.warn("build failed — keeping previous binary");
-    }, 300);
-  };
-  const cppDir = resolve(root, "cpp");
-  if (existsSync(cppDir)) watch(cppDir, { recursive: true }, onChange);
-
-  const cleanup = () => {
-    stopPortMonitor();
-    if (child) child.kill();
-    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
-    exitAfterCleanup(0);
-  };
-  process.on("SIGINT", cleanup);
-  process.on("SIGTERM", cleanup);
-  process.on("SIGHUP", cleanup);
-}
-
-function warnManifest(root) {
-  const manifest = readManifest(root);
-  if (!manifest || Object.keys(manifest).length === 0) return;
-  const errors = validateManifest(manifest);
-  for (const e of errors) log.warn(`manifest.json: ${e}`);
-}
-
-export async function runDevBack(args = []) {
-  const root = findPluginRoot();
-  assertManifestVariables(root);
-  warnManifest(root);
-  const portRanges = assertManifestPorts(root);
-  ensureDocker();
-  const { robotIp, robotToken } = await promptRobotConnection(args);
-  if (robotIp)    process.env.MUSCAT_ROBOT_HOST  = robotIp;
-  if (robotToken) process.env.MUSCAT_ROBOT_TOKEN = robotToken;
-  // Standalone `dev:back` against a remote robot needs the Zenoh reverse-path
-  // advertise host/port too (idempotent — `muscat-pk dev` already set these).
-  // Byte-proxy mode (a host-side host_agent set MUSCAT_PROXY_ENDPOINT) makes
-  // the container speak the proxy protocol instead, so it needs no reverse-dial.
-  if (!process.env.MUSCAT_PROXY_ENDPOINT) await ensureRemoteZenohEnv(robotIp, { log });
-  // Standalone against a local Muscat (muscat-dev, …): join its netns like `dev` does,
-  // otherwise zenoh reaches nothing and `execute` never arrives.
-  if (!process.env.MUSCAT_PK_MUSCAT_CONTAINER && !isRemoteRobot(robotIp)) {
-    const muscat = localMuscatContainer();
-    if (muscat) {
-      process.env.MUSCAT_PK_MUSCAT_CONTAINER = muscat;
-    }
-  }
-  // Stopped while still setting up (image build, pip install, first cmake build): the runtime's own
-  // cleanup is not registered yet, so remove the container here. Once it is, it handles the signal.
-  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"])
-    process.once(signal, () => {
-      if (process.listenerCount(signal)) return;
-      stopDevBackContainers();
-      process.exit(130);
-    });
-  const robotGateway = (await robotHasMuscat(robotIp)) ? `http://${robotIp}:${GATEWAY_PORT}` : "";
-  const type = manifestRuntime(root);
-  if (type === "ros2") return await runRos2(root, portRanges, robotGateway);
-  if (type === "cpp") return await runCpp(root, portRanges, robotGateway);
-  return await runPython(root, portRanges, robotGateway);
-}
+// muscat-pk dev:back — run the plugin back end during development.
+// Every backend runs in a warm Docker container that matches the robot
+// (Ubuntu 24.04), so dev behaves like production.
+//   python : Python 3.12 container, pip install, run main.py with watchfiles
+//            hot-reload. Shares the local Muscat container's netns (localhost:10000).
+//   cpp    : Ubuntu + cmake container, build cpp/, run the binary, rebuild +
+//            restart on source changes.
+//   ros2   : Jazzy + Python 3.12 container, colcon build, run the node, restart
+//            on source changes (rclcpp rebuilds on change).
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, watch, writeFileSync } from "node:fs";
+import { isIP } from "node:net";
+import { dirname, resolve } from "node:path";
+import { dockerUserFlags, ensureDocker, ensureIdeVenv, findPluginRoot, log, promptRobotConnection, realtimeFlags } from "./util.mjs";
+import { ensureRemoteZenohEnv, getFreePort, isRemoteRobot, usesHostNetwork } from "./zenohDev.mjs";
+import { GATEWAY_PORT, localMuscatContainer, robotHasMuscat } from "./muscatLocal.mjs";
+import { PLUGIN_ID_RE, assertManifestPorts, assertManifestVariables, manifestRuntime, readManifest, rosNamespace, validateManifest } from "./manifest.mjs";
+import {
+  portEnvFlags,
+  publishPortFlags,
+  startPortContractMonitor,
+} from "./ports.mjs";
+import {
+  PYTHON_DEV_IMAGE,
+  assertDockerReady as pyAssertDockerReady,
+  ensureImage as pyEnsureImage,
+} from "./python.mjs";
+import {
+  ROS2_DEV_IMAGE,
+  assertDockerReady,
+  ensureImage,
+  ros2PackageName,
+} from "./ros2.mjs";
+import {
+  CPP_DEV_IMAGE,
+  assertDockerReady as cppAssertDockerReady,
+  ensureImage as cppEnsureImage,
+} from "./cpp.mjs";
+
+const MANAGED_DEV_ENV = "MUSCAT_PK_MANAGED_DEV";
+
+function exitAfterCleanup(code = 0) {
+  if (process.env[MANAGED_DEV_ENV] !== "1") process.exit(code ?? 0);
+}
+
+export function stopDevBackContainers() {
+  for (const container of [
+    `${PYTHON_DEV_IMAGE}-run`,
+    `${ROS2_DEV_IMAGE}-run`,
+    `${CPP_DEV_IMAGE}-run`,
+  ]) {
+    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
+  }
+}
+
+// Where the backend's 127.0.0.1 points. A local Muscat container (muscat-pk-muscat, muscat-dev):
+// join its netns so the gateway and MediaMTX resolve like on the robot. Otherwise its own
+// netns, gateway via the host.
+// IS_DEV Muscat (muscat-dev): common is a zenoh-router client and opens no 7447 listener,
+// so the plugin must join the router too or `execute` queries never reach it.
+function muscatZenohEnv(container) {
+  const r = spawnSync("docker", ["inspect", "-f", "{{range .Config.Env}}{{println .}}{{end}}", container], { encoding: "utf8" });
+  return /^IS_DEV=(true|1)$/im.test(r.stdout || "")
+    ? ["-e", "ZENOH_PEER_CONNECT_ENDPOINTS=tcp/zenoh-router:7447"]
+    : [];
+}
+
+function backendNetwork(portRanges, robotGateway) {
+  const muscat = process.env.MUSCAT_PK_MUSCAT_CONTAINER;
+  if (muscat) return { run: ["--network", `container:${muscat}`], env: muscatZenohEnv(muscat), shared: true };
+  // The robot runs Muscat: its gateway, own netns (host network on Linux), declared ports published.
+  if (robotGateway) {
+    const run = usesHostNetwork() ? ["--network", "host"] : publishPortFlags(portRanges);
+    return { run, env: ["-e", `RB_PLUGIN_GATEWAY_URL=${robotGateway}`], shared: usesHostNetwork() };
+  }
+  if (usesHostNetwork()) return { run: ["--network", "host"], env: [], shared: true };
+  return {
+    // host.docker.internal is automatic on Docker Desktop; this makes it resolve on Linux too.
+    run: [...publishPortFlags(portRanges), "--add-host", "host.docker.internal:host-gateway"],
+    env: ["-e", "RB_PLUGIN_GATEWAY_URL=http://host.docker.internal:10000"],
+    shared: false,
+  };
+}
+
+// rb.rosPeers in dev: answer muscat/plugin/<id>/ros_peers/{get,set} on the gateway the way
+// Muscat (common) does on the robot — keep the list in .muscat-dev/ and restart the node
+// with ROS_STATIC_PEERS.
+const ROS_PEERS_FILE = ".muscat-dev/ros-peers.json";
+
+function readRosPeers(root) {
+  try {
+    return JSON.parse(readFileSync(resolve(root, ROS_PEERS_FILE), "utf8"));
+  } catch {
+    return [];
+  }
+}
+
+async function serveRosPeers(root, pluginId, restart) {
+  if (!pluginId) return;
+  const { RbWs } = await import("@rainbow-robotics/plugin-ui/ws");
+  const ws = await Promise.race([
+    RbWs.connect("http://127.0.0.1:10000", pluginId).catch(() => null),
+    new Promise((r) => setTimeout(() => r(null), 5000)),
+  ]);
+  if (!ws) return log.warn("rb.rosPeers unavailable in dev: plugin gateway not reachable on :10000");
+  const base = `/muscat/plugin/${pluginId}/ros_peers`;
+  await ws.serve(`${base}/get`, () => ({ peers: readRosPeers(root) }));
+  await ws.serve(`${base}/set`, (payload) => {
+    const peers = payload?.peers;
+    if (!Array.isArray(peers) || !peers.every((p) => typeof p === "string" && isIP(p))) {
+      return { ok: false, error: "peers must be a list of IP addresses" };
+    }
+    const file = resolve(root, ROS_PEERS_FILE);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(peers) + "\n");
+    log.step(`ROS_STATIC_PEERS → ${peers.join(";") || "(none)"} — restarting node`);
+    restart();
+    return { ok: true, peers };
+  });
+}
+
+// ── IDE tooling venv (best-effort, non-blocking) ────────────────────────────
+// `muscat-pk new` already creates this up front (see new.mjs); this just
+// refreshes it on every `dev`/`dev:back` in case requirements.txt changed.
+// Docker remains the actual execution environment — this never affects it.
+// Runs in the background so it never delays `dev:back` starting, and any
+// failure here (no local Python toolchain, offline, ...) is silent.
+function syncIdeVenv(root) {
+  setImmediate(() => {
+    try {
+      ensureIdeVenv(root);
+    } catch {
+      /* best-effort only */
+    }
+  });
+}
+
+// ── python ────────────────────────────────────────────────────────────────────
+// Runs in a warm Ubuntu 24.04 + Python 3.12 container (matches the robot).
+// Under `muscat-pk dev`, it shares the local Muscat container's netns, so the SDK
+// reaches the plugin gateway at the default localhost:10000.
+async function runPython(root, portRanges, robotGateway) {
+  // Independent of Docker readiness — must still happen if Docker isn't
+  // installed/running, since that's exactly when local IDE tooling matters most.
+  syncIdeVenv(root);
+  pyAssertDockerReady();
+  await pyEnsureImage();
+
+  const manifest = readManifest(root);
+  const pluginId = manifest.id ?? "";
+  const container = `${PYTHON_DEV_IMAGE}-run`;
+  const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
+  const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
+  const zenohAdvertiseHost = process.env.MUSCAT_ZENOH_ADVERTISE_HOST ?? "";
+  const zenohPort = process.env.MUSCAT_ZENOH_PORT ?? "";
+  // See host_agent.py: a Docker Desktop container can't join the robot's
+  // Zenoh mesh, so it speaks a byte protocol to the host-side proxy instead.
+  const proxyEndpoint = process.env.MUSCAT_PROXY_ENDPOINT ?? "";
+  // Native Linux (not WSL, not Docker Desktop) has real host networking: the
+  // container shares the host's network stack, so it reaches the gateway at
+  // localhost:10000 and the robot's Zenoh router / reverse-dial path directly
+  // — no netns sharing, port publishing, host.docker.internal, or byte-proxy.
+  const net = backendNetwork(portRanges, robotGateway);
+  // Only the container's OWN reverse-dial path needs to publish a listen port.
+  // With a shared netns the port is already reachable; with the byte-proxy
+  // the container just connects out — neither needs -p.
+  const standaloneZenohPortFlags =
+    !net.shared && !proxyEndpoint && zenohPort ? ["-p", `${zenohPort}:${zenohPort}`] : [];
+  // C++ SDK (rainbow-rb-sdk >= 0.10) can't use the byte shim or the fallback patch: its Zenoh session
+  // is native. It joins the robot's mesh itself on this host port (see the entry script); inside,
+  // the port + 1 accepts. With or without host_agent (dev vs standalone dev:back).
+  const sdkAdvertiseHost = proxyEndpoint ? proxyEndpoint.split(":")[0] : zenohAdvertiseHost;
+  const sdkPeerPort = sdkAdvertiseHost && !net.shared && zenohPort ? await getFreePort(Number(zenohPort) + 1) : "";
+  const sdkPeerFlags = sdkPeerPort
+    ? ["--sysctl", "net.ipv4.ip_nonlocal_bind=1", "-p", `${sdkPeerPort}:${Number(sdkPeerPort) + 1}`]
+    : [];
+  const envFlags = [
+    // docker exec below has no -t (no pseudo-TTY), so Python defaults to
+    // block-buffered stdout — print() output wouldn't show up until the
+    // buffer fills or the process exits. Force unbuffered.
+    "-e", "PYTHONUNBUFFERED=1",
+    ...net.env,
+    ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
+    ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
+    ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
+    // Byte-proxy mode: the container has no Zenoh session of its own — the
+    // entry script's shim speaks the raw query/put/subscribe protocol to the
+    // host_agent process at this address instead.
+    ...(proxyEndpoint ? ["-e", `MUSCAT_PROXY_ENDPOINT=${proxyEndpoint}`] : []),
+    ...(sdkPeerPort ? ["-e", `MUSCAT_SDK_PEER_PORT=${sdkPeerPort}`, "-e", `MUSCAT_SDK_ADVERTISE_HOST=${sdkAdvertiseHost}`] : []),
+    // Fallback (no proxy): the container reverse-dials the robot itself.
+    ...(!proxyEndpoint && zenohAdvertiseHost ? ["-e", `MUSCAT_ZENOH_ADVERTISE_HOST=${zenohAdvertiseHost}`] : []),
+    ...(!proxyEndpoint && zenohPort ? ["-e", `MUSCAT_ZENOH_PORT=${zenohPort}`] : []),
+    ...portEnvFlags(portRanges),
+  ];
+  const docker = (args, opts = {}) =>
+    spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
+
+  // start a warm, long-lived container with the plugin mounted.
+  // 호스트 uid 로 돌린다(dockerUserFlags) — root 로 쓴 build/·install/ 은 사용자가 지우지 못한다.
+  docker(["rm", "-f", container], { stdio: "ignore" });
+  const up = docker(
+    ["run", "-d", "--name", container, ...net.run, ...standaloneZenohPortFlags, ...sdkPeerFlags, ...realtimeFlags(), ...dockerUserFlags(),
+      "-e", "PIP_ROOT_USER_ACTION=ignore",
+      "-v", `${root}:/plugin`, "-w", "/plugin", PYTHON_DEV_IMAGE, "sleep", "infinity"],
+    { stdio: ["ignore", "ignore", "inherit"] }, // stdout is just the container id
+  );
+  if (up.status !== 0) throw new Error("failed to start dev container.");
+  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [zenohPort, sdkPeerPort, sdkPeerPort && String(Number(sdkPeerPort) + 1)] });
+
+  docker(["exec", container, "bash", "-lc",
+    "pip install --break-system-packages --ignore-installed -q watchfiles" +
+    " && { [ -f requirements.txt ] && pip install --break-system-packages --ignore-installed -q -r requirements.txt || true; }"]);
+
+  docker(["exec", container, "bash", "-lc", `cat > /tmp/muscat-pk-python-dev-entry.py <<'PY'
+import os
+
+try:
+    import glob
+    import importlib.util
+
+    proxy_endpoint = os.getenv("MUSCAT_PROXY_ENDPOINT")
+    # Located without importing: importing rainbow.rb_sdk opens the SDK's Zenoh session.
+    _rainbow = importlib.util.find_spec("rainbow")
+    cpp_sdk = bool(_rainbow and any(glob.glob(os.path.join(p, "rb_sdk", "rb_sdk_cpp*.so")) for p in _rainbow.submodule_search_locations))
+    if cpp_sdk and os.getenv("MUSCAT_SDK_PEER_PORT"):
+        # C++ SDK (rainbow-rb-sdk >= 0.10): its Zenoh session is native, so the byte shim below
+        # can't reach it, and connect() would register the container's own unreachable IP.
+        # Robot peers dial each remote peer at the locators it gossips, so the session must
+        # advertise the host's ip:port: listen there (ip_nonlocal_bind; never accepts) plus on
+        # port + 1, where Docker forwards the host port. Then register like host_agent does.
+        import json
+        import threading
+        import time
+        import urllib.request
+
+        from rainbow.rb_sdk import rb_sdk_cpp
+
+        _port = int(os.environ["MUSCAT_SDK_PEER_PORT"])
+        _advertise = os.environ["MUSCAT_SDK_ADVERTISE_HOST"]
+        os.environ["ZENOH_PEER_LISTEN_ENDPOINTS"] = f"tcp/{_advertise}:{_port},tcp/0.0.0.0:{_port + 1}"
+        for _cls in list(vars(rb_sdk_cpp).values()):
+            if isinstance(_cls, type) and issubclass(_cls, rb_sdk_cpp.RBBaseSDK) and "connect" in _cls.__dict__:
+                _cls.connect = lambda self, *args, **kwargs: None
+
+        def _peer_http(method, path, body=None):
+            headers = {"Content-Type": "application/json"}
+            if os.getenv("MUSCAT_ROBOT_TOKEN"):
+                headers["Authorization"] = "Bearer " + os.environ["MUSCAT_ROBOT_TOKEN"]
+            req = urllib.request.Request(f"http://{os.environ['MUSCAT_ROBOT_HOST']}:8000{path}",
+                                         data=json.dumps(body).encode() if body is not None else None,
+                                         headers=headers, method=method)
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                raw = resp.read()
+                return json.loads(raw) if raw else {}
+
+        def _peer_keepalive():
+            advertise = _advertise
+            peer_id = None
+            while True:
+                try:
+                    if peer_id is None:
+                        peer_id = _peer_http("POST", "/zenoh/peer", {"ip": advertise, "port": _port, "ttl": 30})["peer_id"]
+                        print(f"[muscat-pk] C++ SDK zenoh peer {advertise}:{_port} registered with the robot", flush=True)
+                    elif not _peer_http("POST", f"/zenoh/peer/{peer_id}/heartbeat", {"ttl": 30}).get("ok"):
+                        peer_id = None
+                        continue
+                except Exception as exc:
+                    print(f"[muscat-pk] zenoh peer registration failed ({exc}); retrying", flush=True)
+                    peer_id = None
+                time.sleep(15 if peer_id else 3)
+
+        threading.Thread(target=_peer_keepalive, daemon=True).start()
+    elif proxy_endpoint:
+        # Byte-proxy mode: this container has no Zenoh session of its own.
+        # ZenohClient's C++ core is replaced with a shim that speaks a raw
+        # query/put/subscribe byte protocol to host_agent.py instead.
+        import json
+        import socket
+        import struct
+        import threading
+
+        _proxy_host, _proxy_port_s = proxy_endpoint.rsplit(":", 1)
+        _proxy_port = int(_proxy_port_s)
+
+        def _send_frame(conn, lock, obj):
+            body = json.dumps(obj).encode()
+            with lock:
+                conn.sendall(struct.pack(">I", len(body)) + body)
+
+        def _recv_frame(conn):
+            hdr = b""
+            while len(hdr) < 4:
+                chunk = conn.recv(4 - len(hdr))
+                if not chunk:
+                    return None
+                hdr += chunk
+            n = struct.unpack(">I", hdr)[0]
+            buf = b""
+            while len(buf) < n:
+                chunk = conn.recv(n - len(buf))
+                if not chunk:
+                    return None
+                buf += chunk
+            return json.loads(buf.decode())
+
+        class _ProxyRawClient:
+            """Drop-in replacement for ZenohClient's C++ core, backed by the
+            host_agent byte-proxy instead of a local Zenoh session."""
+
+            sender = "RRS"
+            sender_id = ""
+
+            def __init__(self, host, port):
+                self._conn = socket.create_connection((host, port), timeout=10)
+                # create_connection() leaves the connect timeout applied to
+                # the socket permanently; the background read loop below does
+                # a long-lived blocking recv() for async "sample" pushes, so
+                # it must not time out on an idle connection.
+                self._conn.settimeout(None)
+                self._send_lock = threading.Lock()
+                self._req_id = 0
+                self._req_lock = threading.Lock()
+                self._pending = {}
+                self._subs = {}  # sub_id -> callback
+                self._sub_by_keyexpr = {}
+                threading.Thread(target=self._read_loop, daemon=True).start()
+
+            def _next_id(self):
+                with self._req_lock:
+                    self._req_id += 1
+                    return self._req_id
+
+            def _read_loop(self):
+                while True:
+                    frame = _recv_frame(self._conn)
+                    if frame is None:
+                        return
+                    ftype = frame.get("type")
+                    if ftype == "sample":
+                        cb = self._sub_by_keyexpr.get(frame["keyexpr"])
+                        if cb is not None:
+                            try:
+                                cb(frame["key"], bytes.fromhex(frame["payload_hex"]), frame.get("att", ""))
+                            except Exception as exc:
+                                print(f"[muscat-pk] proxy subscriber callback error: {exc}", flush=True)
+                    elif "id" in frame:
+                        ev = self._pending.pop(frame["id"], None)
+                        if ev is not None:
+                            ev[1] = frame
+                            ev[0].set()
+
+            def _request(self, obj, timeout=30):
+                req_id = self._next_id()
+                obj["id"] = req_id
+                ev = threading.Event()
+                slot = [ev, None]
+                self._pending[req_id] = slot
+                _send_frame(self._conn, self._send_lock, obj)
+                if not ev.wait(timeout):
+                    self._pending.pop(req_id, None)
+                    raise TimeoutError(f"proxy request timed out: {obj.get('type')} {obj.get('keyexpr')}")
+                return slot[1]
+
+            def query(self, keyexpr, payload, timeout_ms, target):
+                resp = self._request({
+                    "type": "query", "keyexpr": keyexpr,
+                    "payload_hex": payload.hex() if payload else None,
+                    "timeout_ms": timeout_ms, "target": target,
+                }, timeout=(timeout_ms / 1000) + 5)
+                if not resp.get("ok"):
+                    raise RuntimeError(resp.get("error", "proxy query failed"))
+                return [
+                    (r["key"], bytes.fromhex(r["payload_hex"]), r["att"], r["encoding"], r["is_error"])
+                    for r in resp["replies"]
+                ]
+
+            def query_all(self, keyexpr, payload, timeout_ms, target):
+                return self.query(keyexpr, payload, timeout_ms, target)
+
+            def publish(self, topic, payload, att, congestion_control, priority, express):
+                resp = self._request({
+                    "type": "put", "keyexpr": topic,
+                    "payload_hex": bytes(payload).hex() if payload else None,
+                })
+                if not resp.get("ok"):
+                    raise RuntimeError(resp.get("error", "proxy put failed"))
+
+            def has_subscriber(self, topic):
+                return topic in self._sub_by_keyexpr
+
+            def declare_subscriber(self, topic, callback, opts=None):
+                resp = self._request({"type": "subscribe", "keyexpr": topic})
+                if not resp.get("ok"):
+                    raise RuntimeError(resp.get("error", "proxy subscribe failed"))
+                sub_id = self._next_id()
+                self._subs[sub_id] = topic
+                self._sub_by_keyexpr[topic] = callback
+                return sub_id
+
+            def undeclare_subscriber(self, sub_id):
+                topic = self._subs.pop(sub_id, None)
+                if topic is None:
+                    return
+                self._sub_by_keyexpr.pop(topic, None)
+                self._request({"type": "unsubscribe", "keyexpr": topic})
+
+            def unsubscribe_topic(self, topic):
+                for sub_id, t in list(self._subs.items()):
+                    if t == topic:
+                        self.undeclare_subscriber(sub_id)
+
+            def unsubscribe_all(self):
+                for sub_id in list(self._subs):
+                    self.undeclare_subscriber(sub_id)
+
+            def get_sub_stats(self, sub_id):
+                return {}
+
+            def declare_queryable(self, keyexpr, handler):
+                raise NotImplementedError("byte-proxy mode does not support declare_queryable")
+
+            def undeclare_queryable_by_topic(self, keyexpr):
+                pass
+
+        # ZenohClient is a process-wide singleton whose __init__ eagerly
+        # calls connect() on first construction. rainbow.rb_sdk.base
+        # transitively imports rainbow.rb_log.log, which constructs one at
+        # module level — so this patch must land before RBBaseSDK is
+        # imported, or that eager construction wins with a real session.
+        from rainbow.rb_zenoh.client import ZenohClient
+
+        def _proxy_connect(self, *, config_pairs=None, sender=None, max_attempts=8, initial_delay_s=0.5, max_delay_s=3.0):
+            if self._client is not None:
+                return
+            if sender is not None:
+                self._sender = sender
+            print(f"[muscat-pk] zenoh via host byte-proxy → {proxy_endpoint} (no local Zenoh session)", flush=True)
+            self._client = _ProxyRawClient(_proxy_host, _proxy_port)
+
+        ZenohClient.connect = _proxy_connect
+
+        from rainbow.rb_sdk.base import RBBaseSDK
+
+        async def _sdk_connect_via_proxy(self, *args, **kwargs):
+            # No HTTP registration with common — host_agent already handles
+            # that. Just make sure the (proxy-backed) shared ZenohClient exists.
+            self._ensure_zenoh_client_alive()
+            return None
+
+        async def _sdk_disconnect_via_proxy(self, *args, **kwargs):
+            return None
+
+        RBBaseSDK.connect = _sdk_connect_via_proxy
+        RBBaseSDK.disconnect = _sdk_disconnect_via_proxy
+    else:
+        # Fallback: no host byte-proxy — the container reverse-dials the robot itself.
+        advertise_host = os.getenv("MUSCAT_ZENOH_ADVERTISE_HOST")
+        zenoh_port = os.getenv("MUSCAT_ZENOH_PORT")
+        from rainbow.rb_sdk.base import RBBaseSDK
+        if advertise_host:
+            RBBaseSDK._detect_local_ip = staticmethod(lambda host: advertise_host)
+        if zenoh_port:
+            _orig_connect = RBBaseSDK.connect
+
+            async def _connect_with_dev_port(self, *args, **kwargs):
+                kwargs.setdefault("zenoh_port", int(zenoh_port))
+                return await _orig_connect(self, *args, **kwargs)
+
+            RBBaseSDK.connect = _connect_with_dev_port
+except Exception as exc:
+    print(f"[muscat-pk] SDK dev network patch skipped: {exc}", flush=True)
+
+import runpy
+runpy.run_path("/plugin/py/main.py", run_name="__main__")
+PY`]);
+
+  if (usesHostNetwork()) log.step("network: host (native Linux — direct robot/gateway access)");
+  if (proxyEndpoint) log.step(`Zenoh via host byte-proxy → ${proxyEndpoint}`);
+  else if (zenohAdvertiseHost && zenohPort) log.step(`Zenoh advertise → ${zenohAdvertiseHost}:${zenohPort}`);
+  const child = spawn(
+    "docker",
+    ["exec", ...envFlags, container, "bash", "-lc",
+      "python3 -m watchfiles --filter python --target-type command 'python3 /tmp/muscat-pk-python-dev-entry.py' py"],
+    { cwd: root, stdio: ["inherit", "inherit", "pipe"] },
+  );
+  // watchfiles prints a KeyboardInterrupt traceback on SIGTERM — suppress it
+  child.stderr.on("data", (buf) => {
+    const text = buf.toString();
+    if (!text.includes("KeyboardInterrupt") && !text.includes("raise_keyboard_interrupt")) {
+      process.stderr.write(buf);
+    }
+  });
+
+  let cleaned = false;
+  const cleanupResources = () => {
+    if (cleaned) return;
+    cleaned = true;
+    stopPortMonitor();
+    if (!child.killed && child.exitCode === null) child.kill();
+    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
+  };
+  const cleanup = () => {
+    cleanupResources();
+    exitAfterCleanup(0);
+  };
+  child.on("exit", (code) => {
+    cleanupResources();
+    exitAfterCleanup(code ?? 0);
+  });
+  process.once("SIGINT", cleanup);
+  process.once("SIGTERM", cleanup);
+  process.once("SIGHUP", cleanup);
+}
+
+// ── ros2 ───────────────────────────────────────────────────────────────────────
+async function runRos2(root, portRanges, robotGateway) {
+  const manifest = readManifest(root);
+  const isRclcpp = manifest.runtime?.rosClient === "rclcpp";
+  // Independent of Docker readiness — must still happen if Docker isn't
+  // installed/running, since that's exactly when local IDE tooling matters most.
+  if (!isRclcpp) syncIdeVenv(root); // rclpy is plain Python — rclcpp is C++, no venv needed
+
+  assertDockerReady();
+  const pkg = ros2PackageName(root);
+  if (!pkg) throw new Error("no ROS2 package found under ros2_ws/src.");
+
+  await ensureImage();
+
+  const pluginId = manifest.id ?? "";
+  const container = `${ROS2_DEV_IMAGE}-run`;
+  const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
+  const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
+  const net = backendNetwork(portRanges, robotGateway);
+  const envFlags = [
+    // Same rationale as runPython(): no -t on docker exec below means
+    // rclpy's Python process stdout is block-buffered, not line-buffered.
+    "-e", "PYTHONUNBUFFERED=1",
+    // Same as the robot: ROS discovery stays on this host (allow a PC with ROS_STATIC_PEERS).
+    "-e", "ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST",
+    ...net.env,
+    ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
+    ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
+    ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
+    ...portEnvFlags(portRanges),
+  ];
+  const docker = (args, opts = {}) =>
+    spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
+
+  // start a warm, long-lived container with the workspace mounted
+  docker(["rm", "-f", container], { stdio: "ignore" });
+  const up = docker(
+    ["run", "-d", "--name", container, ...net.run, ...realtimeFlags(), ...dockerUserFlags(), "-e", "PIP_ROOT_USER_ACTION=ignore", "-v", `${root}:/plugin`, "-w", "/plugin", ROS2_DEV_IMAGE, "sleep", "infinity"],
+    { stdio: ["ignore", "ignore", "inherit"] }, // stdout is just the container id
+  );
+  if (up.status !== 0) throw new Error("failed to start dev container.");
+  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [process.env.MUSCAT_ZENOH_PORT] });
+
+  // one-time deps + symlink build (edits to .py reflect without rebuilding)
+  docker(["exec", container, "bash", "-lc",
+    "pip install -r requirements.txt --break-system-packages --ignore-installed -q || true; cd ros2_ws && colcon build --symlink-install"]);
+
+  let child = null;
+  const startNode = () => {
+    if (child) child.kill();
+    // killing the `docker exec` client doesn't stop the node inside the container
+    spawnSync("docker", ["exec", container, "pkill", "-f", `${pkg}_node|${manifest.runtime?.launch || pkg}`], { stdio: "ignore" });
+    const peers = readRosPeers(root);
+    // Same command the robot runs: rclpy execs the console script, rclcpp uses `ros2 run`;
+    // relative topics land under the plugin's namespace (rosNamespace).
+    const launch = manifest.runtime?.launch || `${pkg}_node`;
+    const nsArgs = PLUGIN_ID_RE.test(pluginId) ? ` --ros-args -r __ns:=${rosNamespace(pluginId)}` : "";
+    const run = (isRclcpp ? `ros2 run ${pkg} ${launch}` : `exec ${launch}`) + nsArgs;
+    child = spawn(
+      "docker",
+      ["exec", ...envFlags, ...(peers.length ? ["-e", `ROS_STATIC_PEERS=${peers.join(";")}`] : []), container, "bash", "-lc",
+        `cd ros2_ws && source install/setup.bash && ${run}`],
+      { cwd: root, stdio: "inherit" },
+    );
+  };
+  startNode();
+  serveRosPeers(root, pluginId, startNode);
+
+  // restart node on source change. rclpy reflects .py edits live (symlink-install);
+  // rclcpp (C++) and package-metadata changes require a colcon rebuild.
+  let timer = null;
+  const onChange = (_event, filename) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      const structural = filename && /(setup\.py|package\.xml|CMakeLists\.txt)$/.test(String(filename));
+      if (structural || isRclcpp) {
+        log.info(structural ? "package metadata changed — colcon rebuild…" : "source changed — colcon rebuild…");
+        docker(["exec", container, "bash", "-lc", "cd ros2_ws && colcon build --symlink-install"]);
+      } else {
+        log.info("source changed — restarting node…");
+      }
+      startNode();
+    }, 300);
+  };
+  for (const target of ["ros2_ws/src", "main.py"]) {
+    const full = resolve(root, target);
+    if (existsSync(full)) watch(full, { recursive: true }, onChange);
+  }
+
+  const cleanup = () => {
+    stopPortMonitor();
+    if (child) child.kill();
+    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
+    exitAfterCleanup(0);
+  };
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+  process.on("SIGHUP", cleanup);
+}
+
+// ── cpp ──────────────────────────────────────────────────────────────────────
+async function runCpp(root, portRanges, robotGateway) {
+  cppAssertDockerReady();
+  const manifest = readManifest(root);
+  const entry = manifest.runtime?.entry;
+  if (!entry) throw new Error("runtime.entry (the built executable name) is required for cpp.");
+
+  await cppEnsureImage();
+
+  const pluginId = manifest.id ?? "";
+  const container = `${CPP_DEV_IMAGE}-run`;
+  const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
+  const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
+  const net = backendNetwork(portRanges, robotGateway);
+  const envFlags = [
+    ...net.env,
+    ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
+    ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
+    ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
+    ...portEnvFlags(portRanges),
+  ];
+  const docker = (args, opts = {}) =>
+    spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
+
+  // start a warm, long-lived container with the plugin mounted
+  docker(["rm", "-f", container], { stdio: "ignore" });
+  const up = docker(
+    ["run", "-d", "--name", container, ...net.run, ...realtimeFlags(), ...dockerUserFlags(), "-v", `${root}:/plugin`, "-w", "/plugin", CPP_DEV_IMAGE, "sleep", "infinity"],
+    { stdio: ["ignore", "ignore", "inherit"] }, // stdout is just the container id
+  );
+  if (up.status !== 0) throw new Error("failed to start dev container.");
+  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [process.env.MUSCAT_ZENOH_PORT] });
+
+  const build = () => {
+    return docker(["exec", container, "bash", "-lc",
+      "cmake -S cpp -B cpp/build -DCMAKE_BUILD_TYPE=Debug && cmake --build cpp/build -j"]);
+  };
+  build();
+
+  let child = null;
+  const startBin = () => {
+    if (child) child.kill();
+    child = spawn(
+      "docker",
+      ["exec", ...envFlags, container, "bash", "-lc", `./cpp/build/${entry}`],
+      { cwd: root, stdio: "inherit" },
+    );
+  };
+  startBin();
+
+  // rebuild + restart on C++ source changes; ignore the build/ output dir.
+  let timer = null;
+  const onChange = (_event, filename) => {
+    if (filename && String(filename).startsWith("build")) return;
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      log.info("source changed — rebuilding…");
+      const r = build();
+      if (r.status === 0) startBin();
+      else log.warn("build failed — keeping previous binary");
+    }, 300);
+  };
+  const cppDir = resolve(root, "cpp");
+  if (existsSync(cppDir)) watch(cppDir, { recursive: true }, onChange);
+
+  const cleanup = () => {
+    stopPortMonitor();
+    if (child) child.kill();
+    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
+    exitAfterCleanup(0);
+  };
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+  process.on("SIGHUP", cleanup);
+}
+
+function warnManifest(root) {
+  const manifest = readManifest(root);
+  if (!manifest || Object.keys(manifest).length === 0) return;
+  const errors = validateManifest(manifest);
+  for (const e of errors) log.warn(`manifest.json: ${e}`);
+}
+
+export async function runDevBack(args = []) {
+  const root = findPluginRoot();
+  assertManifestVariables(root);
+  warnManifest(root);
+  const portRanges = assertManifestPorts(root);
+  ensureDocker();
+  const { robotIp, robotToken } = await promptRobotConnection(args);
+  if (robotIp)    process.env.MUSCAT_ROBOT_HOST  = robotIp;
+  if (robotToken) process.env.MUSCAT_ROBOT_TOKEN = robotToken;
+  // Standalone `dev:back` against a remote robot needs the Zenoh reverse-path
+  // advertise host/port too (idempotent — `muscat-pk dev` already set these).
+  // Byte-proxy mode (a host-side host_agent set MUSCAT_PROXY_ENDPOINT) makes
+  // the container speak the proxy protocol instead, so it needs no reverse-dial.
+  if (!process.env.MUSCAT_PROXY_ENDPOINT) await ensureRemoteZenohEnv(robotIp, { log });
+  // Standalone against a local Muscat (muscat-dev, …): join its netns like `dev` does,
+  // otherwise zenoh reaches nothing and `execute` never arrives.
+  if (!process.env.MUSCAT_PK_MUSCAT_CONTAINER && !isRemoteRobot(robotIp)) {
+    const muscat = localMuscatContainer();
+    if (muscat) {
+      process.env.MUSCAT_PK_MUSCAT_CONTAINER = muscat;
+    }
+  }
+  // Stopped while still setting up (image build, pip install, first cmake build): the runtime's own
+  // cleanup is not registered yet, so remove the container here. Once it is, it handles the signal.
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"])
+    process.once(signal, () => {
+      if (process.listenerCount(signal)) return;
+      stopDevBackContainers();
+      process.exit(130);
+    });
+  const robotGateway = (await robotHasMuscat(robotIp)) ? `http://${robotIp}:${GATEWAY_PORT}` : "";
+  const type = manifestRuntime(root);
+  if (type === "ros2") return await runRos2(root, portRanges, robotGateway);
+  if (type === "cpp") return await runCpp(root, portRanges, robotGateway);
+  return await runPython(root, portRanges, robotGateway);
+}