rosotacom-dev 2.5.dev7__tar.gz → 2.5.dev10__tar.gz

{rosotacom_dev-2.5.dev7 → rosotacom_dev-2.5.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev7
+Version: 2.5.dev10
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause
@@ -494,6 +494,34 @@ in this mode — there is no staging to undo, and the workdir is your repository
 The run manifest records which mode and which version the peers ran, so a result
 can be attributed to an artefact rather than to a working copy.
 
+#### How the peers are reached: `--peer-exec`
+
+`--peer-ssh` gives the orchestrator a shell on the peer, which is more than a
+run needs and more than some machines should hand out. `--peer-exec` names the
+transport instead:
+
+```bash
+rosotacom ota-smoke 2_native_chatter --peer a=workstation --peer b=robot \
+  --install-mode checkout \
+  --peer-checkout a=/home/me/fleet_mgmt --peer-checkout b=/home/robot/fleet_mgmt \
+  --peer-exec b='remote-rosotacom robot'
+```
+
+The command is run with the script as its final argument — the contract
+`ssh host <script>` already has — so anything of that shape can carry a peer: a
+wrapper that logs what a run asks for, a container exec, or a forced command
+that accepts some scripts and refuses the rest. rosotacom does not know or care
+which; it only stops assuming that reaching a peer means having a shell on it.
+
+Two restrictions, both load-bearing. It applies to `--install-mode checkout`
+only, because the staging modes push a tar stream and a file write by taking
+the ssh client's own argv apart, and a transport that promises no more than
+"run this script" cannot carry them. And a peer takes either `--peer-ssh` or
+`--peer-exec`, never both: leaving it ambiguous hides which one carried the run.
+
+`-t` and `-o BatchMode=yes` are dropped rather than forwarded. They are options
+of one client, and a transport that is not ssh never agreed to understand them.
+
 ### Live status / debugging overview
 
 Enable a continuously-updated, per-topic pipeline overview by setting

{rosotacom_dev-2.5.dev7 → rosotacom_dev-2.5.dev10}/README.md

@@ -449,6 +449,34 @@ in this mode — there is no staging to undo, and the workdir is your repository
 The run manifest records which mode and which version the peers ran, so a result
 can be attributed to an artefact rather than to a working copy.
 
+#### How the peers are reached: `--peer-exec`
+
+`--peer-ssh` gives the orchestrator a shell on the peer, which is more than a
+run needs and more than some machines should hand out. `--peer-exec` names the
+transport instead:
+
+```bash
+rosotacom ota-smoke 2_native_chatter --peer a=workstation --peer b=robot \
+  --install-mode checkout \
+  --peer-checkout a=/home/me/fleet_mgmt --peer-checkout b=/home/robot/fleet_mgmt \
+  --peer-exec b='remote-rosotacom robot'
+```
+
+The command is run with the script as its final argument — the contract
+`ssh host <script>` already has — so anything of that shape can carry a peer: a
+wrapper that logs what a run asks for, a container exec, or a forced command
+that accepts some scripts and refuses the rest. rosotacom does not know or care
+which; it only stops assuming that reaching a peer means having a shell on it.
+
+Two restrictions, both load-bearing. It applies to `--install-mode checkout`
+only, because the staging modes push a tar stream and a file write by taking
+the ssh client's own argv apart, and a transport that promises no more than
+"run this script" cannot carry them. And a peer takes either `--peer-ssh` or
+`--peer-exec`, never both: leaving it ambiguous hides which one carried the run.
+
+`-t` and `-o BatchMode=yes` are dropped rather than forwarded. They are options
+of one client, and a transport that is not ssh never agreed to understand them.
+
 ### Live status / debugging overview
 
 Enable a continuously-updated, per-topic pipeline overview by setting

{rosotacom_dev-2.5.dev7 → rosotacom_dev-2.5.dev10}/src/rosotacom/cli.py

@@ -234,6 +234,19 @@ class OtaSmokePeer:
     #: control centre runs it under a different account than a laptop does — and
     #: a single workdir would silently be wrong on all but one of them.
     checkout: str | None = None
+    #: How to reach this peer, when `ssh <alias> <script>` is not allowed to be
+    #: the answer. The command is given the script as its final argument, the
+    #: same contract ssh has, so anything with that shape can carry a peer:
+    #: a wrapper that logs, a container exec, or a capability that accepts only
+    #: some scripts and refuses the rest.
+    #:
+    #: This exists because "give the orchestrator a shell on the peer" is a poor
+    #: trade for a machine that is only meant to run one repository's test. An
+    #: SSH alias grants everything that account can do, forever, to whoever
+    #: holds the key; the operations a run actually needs are a short, fixed
+    #: list. Naming the transport lets the narrow thing be substituted without
+    #: this file having to know what narrow means.
+    exec_command: str | None = None
 
 
 @dataclass(frozen=True)
@@ -1027,6 +1040,10 @@ def _parse_peer_checkout_overrides(overrides: list[str] | None) -> dict[str, str
     return parse_assignments(overrides, option="--peer-checkout")
 
 
+def _parse_peer_exec_overrides(overrides: list[str] | None) -> dict[str, str]:
+    return parse_assignments(overrides, option="--peer-exec")
+
+
 def _deployment_config(runtime: RuntimeConfig) -> DeploymentConfig | None:
     return load_deployment(runtime.deployment)
 
@@ -1563,8 +1580,31 @@ def _ota_plan_from_bindings(
     install_pin: str | None = None,
     checkouts: Mapping[str, str] | None = None,
     project: str | None = None,
+    exec_commands: Mapping[str, str] | None = None,
 ) -> OtaSmokePlan:
     _ota_validate_install_mode(install_mode)
+    if exec_commands:
+        unknown = sorted(set(exec_commands) - set(bindings))
+        if unknown:
+            raise RuntimeError(f"--peer-exec names a peer the session does not have: {', '.join(unknown)}")
+        # Staging modes send a tar stream and a file write, not a command, and
+        # both take the ssh client's own argv apart to do it. A transport that
+        # only promises "run this script" cannot carry them, and quietly
+        # writing the peer's files onto the orchestrator instead — which is
+        # what the local branch of the staging helpers would do — is the worst
+        # of the available outcomes.
+        if install_mode != "checkout":
+            raise RuntimeError(
+                f"--peer-exec requires --install-mode checkout (got {install_mode!r}): the other modes copy a "
+                "tree to the peer, which a command transport cannot carry."
+            )
+        both = sorted(name for name in exec_commands if bindings[name].ssh)
+        if both:
+            raise RuntimeError(
+                "--peer-exec and --peer-ssh both name "
+                + ", ".join(both)
+                + "; a peer is reached one way, and leaving it ambiguous hides which one carried the run."
+            )
     if install_mode == "checkout":
         if not checkouts or not project:
             raise RuntimeError("--install-mode checkout requires --peer-checkout for every peer.")
@@ -1602,6 +1642,7 @@ def _ota_plan_from_bindings(
             ssh=binding.ssh,
             address=binding.address,
             checkout=(checkouts or {}).get(name) if install_mode == "checkout" else None,
+            exec_command=(exec_commands or {}).get(name),
         )
         for name, binding in bindings.items()
     }
@@ -1619,14 +1660,19 @@ def _ota_plan_from_bindings(
 def _ota_write_state(instance: SessionInstance, plan: OtaSmokePlan) -> OtaSmokePlan:
     path = instance.host_dir / "ota-deployment.yaml"
     payload = {
-        "schema_version": 3,
+        "schema_version": 4,
         "workdir": plan.workdir,
         "rosotacom": plan.rosotacom,
         "project": plan.project,
         "install_mode": plan.install_mode,
         "install_pin": plan.install_pin,
         "peers": {
-            name: {"address": peer.address, "ssh": peer.ssh, "checkout": peer.checkout}
+            name: {
+                "address": peer.address,
+                "ssh": peer.ssh,
+                "checkout": peer.checkout,
+                "exec": peer.exec_command,
+            }
             for name, peer in sorted(plan.peers.items())
         },
     }
@@ -1637,7 +1683,7 @@ def _ota_write_state(instance: SessionInstance, plan: OtaSmokePlan) -> OtaSmokeP
 def _ota_load_state(path_arg: str) -> OtaSmokePlan:
     path = Path(path_arg).expanduser().resolve()
     raw = _load_yaml_file(path)
-    if raw.get("schema_version") != 3:
+    if raw.get("schema_version") != 4:
         raise RuntimeError(f"Unsupported OTA deployment state: {path}")
     peers_raw = raw.get("peers")
     if not isinstance(peers_raw, dict) or len(peers_raw) != 2:
@@ -1651,6 +1697,7 @@ def _ota_load_state(path_arg: str) -> OtaSmokePlan:
             address=str(peer_raw["address"]),
             ssh=str(peer_raw["ssh"]) if peer_raw.get("ssh") else None,
             checkout=str(peer_raw["checkout"]) if peer_raw.get("checkout") else None,
+            exec_command=str(peer_raw["exec"]) if peer_raw.get("exec") else None,
         )
     install_pin = raw.get("install_pin")
     return OtaSmokePlan(
@@ -1682,7 +1729,32 @@ def _ota_quote_cmd(parts: list[str]) -> str:
     return shlex.join(parts)
 
 
+def _ota_peer_is_remote(peer: OtaSmokePeer) -> bool:
+    """Does this peer run somewhere other than the orchestrator?
+
+    Asked as a question about the peer rather than about SSH. Every caller that
+    used to read ``peer.ssh`` for this meant "is it over there", and each one
+    that kept reading it after a second transport existed would have taken the
+    local branch for a machine on the other side of the room.
+    """
+    return bool(peer.ssh or peer.exec_command)
+
+
+def _ota_peer_target(peer: OtaSmokePeer) -> str:
+    """How to name this peer's location in output meant for a human."""
+    if peer.exec_command:
+        return peer.exec_command
+    return peer.ssh or "local shell"
+
+
 def _ota_remote_argv(peer: OtaSmokePeer, script: str, *, tty: bool = False, batch: bool = False) -> list[str]:
+    # A named transport wins over the SSH alias, and it takes the script as its
+    # last argument because that is the contract `ssh host <script>` already
+    # has. `tty` and `batch` are dropped on purpose rather than guessed at:
+    # they are options of one particular client, and a transport that is not
+    # ssh has no obligation to understand them.
+    if peer.exec_command:
+        return [*shlex.split(peer.exec_command), script]
     if peer.ssh:
         argv = ["ssh"]
         if batch:
@@ -2194,7 +2266,12 @@ def _ota_write_manifest(
             "install_mode": plan.install_mode,
             "install_pin": plan.install_pin,
             "peers": {
-                name: {"ssh_configured": bool(peer.ssh), "address": peer.address} for name, peer in plan.peers.items()
+                name: {
+                    "ssh_configured": bool(peer.ssh),
+                    "exec_configured": bool(peer.exec_command),
+                    "address": peer.address,
+                }
+                for name, peer in plan.peers.items()
             },
         },
     )
@@ -2319,6 +2396,30 @@ def _infer_active_ota_smoke_run(
     )
 
 
+def _ota_latest_state_for(
+    runtime: RuntimeConfig, target: InteractiveSmokeTarget, instance_id: str | None
+) -> str | None:
+    """The newest `ota-deployment.yaml` for this target, if one is on disk.
+
+    Instances are laid out `<instances>/<date>/<session>_<time>_<instance-id>/`,
+    so a named instance can be matched by suffix and an unnamed one by
+    modification time. Returns None rather than raising: not finding a state is
+    a normal outcome (nothing was ever started here), and the caller has a
+    command line to fall back to.
+    """
+    root = _session_instances_root(runtime)
+    if not root.is_dir():
+        return None
+    candidates = sorted(
+        (path for path in root.glob("*/*/ota-deployment.yaml")),
+        key=lambda path: path.stat().st_mtime,
+        reverse=True,
+    )
+    if instance_id:
+        candidates = [path for path in candidates if path.parent.name.endswith(f"_{instance_id}")]
+    return str(candidates[0]) if candidates else None
+
+
 def _resolve_ota_smoke_context(
     args: argparse.Namespace,
 ) -> tuple[RuntimeConfig, OtaSmokePlan, InteractiveSmokeTarget]:
@@ -2327,6 +2428,21 @@ def _resolve_ota_smoke_context(
         getattr(args, "target", None), runtime, getattr(args, "target_type", "auto")
     )
     state_file = getattr(args, "state_file", None)
+    if not state_file and getattr(args, "stop", False):
+        # Stopping has to reach the run that exists, and the only record of how
+        # that run was deployed is the state a start wrote. Reconstructing a
+        # plan from the command line instead means guessing the install mode,
+        # and the default guess is `source` — which points the stop at
+        # `/tmp/rosotacom_ota/source/.venv/bin/rosotacom` for peers that were
+        # started from their own checkouts. Observed on 2026-08-11: every peer
+        # stop failed silently (they are best-effort), the containers stayed up,
+        # and the only visible action was a cleanup removing a staging directory
+        # that had never been created. Usually the live tmux session carries the
+        # state path; when it does not — a killed session, a run started from
+        # another terminal — the instance directory still does.
+        state_file = _ota_latest_state_for(runtime, target, getattr(args, "instance_id", None))
+        if state_file:
+            print(f"OTA smoke: stopping the run recorded in {state_file}")
     if state_file:
         plan = _ota_load_state(state_file)
     else:
@@ -2339,6 +2455,7 @@ def _resolve_ota_smoke_context(
         )
         install_mode = str(getattr(args, "install_mode", None) or "source")
         checkouts = _parse_peer_checkout_overrides(getattr(args, "peer_checkout", None))
+        exec_commands = _parse_peer_exec_overrides(getattr(args, "peer_exec", None))
         project: str | None = None
         if install_mode == "checkout":
             if not runtime.rosotacom_config:
@@ -2346,10 +2463,12 @@ def _resolve_ota_smoke_context(
             local_checkout, project = _ota_checkout_project_path(runtime.rosotacom_config)
             for name, path in sorted(checkouts.items()):
                 binding = bindings.get(name)
-                if binding is not None and not binding.ssh and Path(path).resolve() != local_checkout:
+                remote = binding is not None and (binding.ssh or name in exec_commands)
+                if binding is not None and not remote and Path(path).resolve() != local_checkout:
                     raise RuntimeError(
                         f"--peer-checkout {name}={path} names the peer that runs on this machine, but the active "
-                        f"project lives in {local_checkout}. Point it there, or give that peer an SSH target."
+                        f"project lives in {local_checkout}. Point it there, or give that peer a transport "
+                        "(--peer-ssh or --peer-exec)."
                     )
         plan = _ota_plan_from_bindings(
             bindings,
@@ -2358,6 +2477,7 @@ def _resolve_ota_smoke_context(
             install_pin=getattr(args, "install_pin", None),
             checkouts=checkouts,
             project=project,
+            exec_commands=exec_commands,
         )
     plan_peers = set(plan.peers)
     target_peers = set(_peer_keys_from_cfg(target.cfg))
@@ -2389,7 +2509,7 @@ def _ota_network_sudo_passwords(
         return {peer.name: "" for peer in plan.peers.values()}
     passwords: dict[str, str] = {}
     for peer in plan.peers.values():
-        target = peer.ssh or "local shell"
+        target = _ota_peer_target(peer)
         passwords[peer.name] = getpass.getpass(f"sudo password for {peer.name} ({target}) [network shaping only]: ")
     return passwords
 
@@ -2489,8 +2609,8 @@ def _ota_preflight(
     sudo_mode = _validate_ota_sudo_mode(sudo_mode)
     sudo_passwords = sudo_passwords or {}
     for peer in plan.peers.values():
-        if peer.ssh:
-            _ota_run(peer, "true", label=f"{peer.name}: SSH reachable", dry_run=dry_run, batch=True)
+        if _ota_peer_is_remote(peer):
+            _ota_run(peer, "true", label=f"{peer.name}: reachable", dry_run=dry_run, batch=True)
         required = ["python3", "docker", "tar"]
         if require_tmux:
             required.append("tmux")
@@ -2595,6 +2715,12 @@ def _ota_stage_tree(peer: OtaSmokePeer, source: Path, destination: str, *, dry_r
         "-",
         ".",
     ]
+    # Reached only in the staging install modes, which `--peer-exec` refuses.
+    # Kept as a check rather than a comment because the failure it prevents is
+    # silent: the local branch below would copy the peer's tree onto the
+    # orchestrator and report success.
+    if peer.exec_command:
+        raise RuntimeError(f"Cannot stage files to {peer.name} over a command transport; use --install-mode checkout.")
     if not peer.ssh:
         print(f"+ {label}: copy {source} -> {destination}")
         if not dry_run:
@@ -2616,7 +2742,13 @@ def _ota_stage_tree(peer: OtaSmokePeer, source: Path, destination: str, *, dry_r
 
 
 def _ota_stage_text(peer: OtaSmokePeer, text: str, destination: str, *, dry_run: bool, label: str) -> None:
-    print(f"+ {label}: write {destination} on {peer.ssh or 'local host'}")
+    # Reached only in the staging install modes, which `--peer-exec` refuses.
+    # Kept as a check rather than a comment because the failure it prevents is
+    # silent: the local branch below would copy the peer's tree onto the
+    # orchestrator and report success.
+    if peer.exec_command:
+        raise RuntimeError(f"Cannot stage files to {peer.name} over a command transport; use --install-mode checkout.")
+    print(f"+ {label}: write {destination} on {_ota_peer_target(peer)}")
     if dry_run:
         return
     if peer.ssh:
@@ -3159,7 +3291,7 @@ def _ota_verify_isolation(
     published = _ota_run(source, publish, label=f"{source_name}: publish isolation probe", dry_run=dry_run, check=False)
     if published.returncode != 0:
         _ota_print_failure_output(f"{source_name}: publish isolation probe", published)
-        errors.append(f"{source_name}: isolation probe publisher failed")
+        errors.append(f"{source_name}: isolation probe did not advertise (probe-publish output above names the cause)")
         return errors
     _print_completed_output(published)
     check = _ota_rosotacom_command(plan, _ota_probe_check_parts(target, receiver_name, peer_args), receiver)
@@ -3594,6 +3726,17 @@ def _list_ota_smoke(args: argparse.Namespace) -> int:
 
 
 def _ota_cleanup_hosts(plan: OtaSmokePlan, *, dry_run: bool) -> None:
+    if plan.state_path is None:
+        # No recorded state means this plan came from the command line, so its
+        # install mode is a default rather than a fact about the run. Removing a
+        # workdir on that basis is a destructive act taken on a guess: it is how
+        # a stop that reached no peer still reported doing something. Say what
+        # is missing instead.
+        print(
+            "OTA smoke: skipping cleanup — no deployment state for this run, so its install mode is unknown. "
+            "Pass --state-file if a workdir really needs removing."
+        )
+        return
     if plan.install_mode == "checkout":
         # The workdir is the user's repository here. `rm -rf` on it would delete
         # a checkout with its untracked work — bags, instance artefacts, local
@@ -6282,8 +6425,17 @@ def _stop_smoke_topic_publishers(containers: dict[str, str], specs: list[SmokeTo
         )
 
 
+# How long the graph may take to report the probe publisher. A loaded graph
+# (e.g. a control centre with hundreds of topics) can take well over the old
+# fixed 10 s to discover a new publisher, and that delay is not a defect.
+_PROBE_ADVERTISE_TIMEOUT_S = 60.0
+# The probe must outlive the advertise wait plus the peer's absence check, or
+# the absence check passes trivially against an already-stopped publisher.
+_PROBE_DURATION_S = 120.0
+
+
 def _publish_isolation_probe(
-    container_name: str, ros_setup: str, topic: str, *, rate: float = 5.0, duration: float = 30.0
+    container_name: str, ros_setup: str, topic: str, *, rate: float = 5.0, duration: float = _PROBE_DURATION_S
 ) -> None:
     """Publish a local-only topic in the container's local application domain,
     detached, for `duration` seconds (self-stops via `timeout`)."""
@@ -6312,6 +6464,45 @@ def _topic_present(container_name: str, ros_setup: str, topic: str) -> bool:
     return topic in names
 
 
+def _isolation_probe_running(container_name: str, topic: str) -> bool:
+    """Whether the probe publisher for `topic` is still alive in the container."""
+    result = subprocess.run(
+        ["docker", "exec", container_name, "pgrep", "-f", f"ros2 topic pub {topic}"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return result.returncode == 0
+
+
+def _wait_for_probe_advertisement(
+    container_name: str,
+    ros_setup: str,
+    topic: str,
+    *,
+    timeout_s: float,
+    log_line: Callable[[str], None] | None = None,
+) -> str:
+    """Poll until `topic` is reported by the container's local graph.
+
+    Returns "advertised", "publisher-gone" (the probe process exited or never
+    started), or "timeout" (the publisher is alive but the graph did not report
+    the topic within `timeout_s`). Only "publisher-gone" points at a publisher
+    defect; a loaded graph reports late, which is what "timeout" captures.
+    """
+    deadline = time.monotonic() + timeout_s
+    while True:
+        if log_line is not None:
+            log_line(f"Waiting for isolation probe {topic} to advertise in {container_name}")
+        if _topic_present(container_name, ros_setup, topic):
+            return "advertised"
+        if not _isolation_probe_running(container_name, topic):
+            return "publisher-gone"
+        if time.monotonic() >= deadline:
+            return "timeout"
+        time.sleep(1)
+
+
 def _verify_isolation(
     pub_container: str,
     pub_setup: str,
@@ -6326,15 +6517,18 @@ def _verify_isolation(
     log_line(f"Starting isolation probe {topic} in {pub_container}")
     _publish_isolation_probe(pub_container, pub_setup, topic)
     try:
-        live = False
-        for _ in range(8):
-            log_line(f"Waiting for isolation probe {topic} to advertise in {pub_container}")
-            if _topic_present(pub_container, pub_setup, topic):
-                live = True
-                break
-            time.sleep(1)
-        if not live:
-            return [f"isolation check inconclusive: {topic} never advertised in {pub_container}"]
+        outcome = _wait_for_probe_advertisement(
+            pub_container, pub_setup, topic, timeout_s=_PROBE_ADVERTISE_TIMEOUT_S, log_line=log_line
+        )
+        if outcome == "publisher-gone":
+            return [
+                f"isolation check inconclusive: probe publisher for {topic} exited or never started in {pub_container}"
+            ]
+        if outcome == "timeout":
+            return [
+                f"isolation check inconclusive: probe publisher for {topic} is running in {pub_container} "
+                f"but the graph did not report it within {_PROBE_ADVERTISE_TIMEOUT_S:.0f}s"
+            ]
         log_line(f"Checking that isolation probe {topic} is absent in {check_container}")
         if _topic_present(check_container, check_setup, topic):
             return [f"isolation breach: {topic} from {pub_container} leaked to {check_container}"]
@@ -6466,12 +6660,32 @@ def probe_publish_command(args: argparse.Namespace) -> int:
     # Block until the topic is actually advertised so a caller's subsequent
     # absence check on the other peer is meaningful (not a false pass on a
     # publisher that never came up).
-    for _ in range(10):
-        if _topic_present(container, ros_setup, args.topic):
-            print(f"Publishing {args.topic} in {container} (identity {args.identity}); advertised.")
-            return 0
-        time.sleep(1)
-    print(f"ERROR: {args.topic} did not advertise in {container} (identity {args.identity})", file=sys.stderr)
+    started = time.monotonic()
+    outcome = _wait_for_probe_advertisement(container, ros_setup, args.topic, timeout_s=args.advertise_timeout)
+    if outcome == "advertised":
+        print(f"Publishing {args.topic} in {container} (identity {args.identity}); advertised.")
+        return 0
+    if outcome == "publisher-gone":
+        if time.monotonic() - started >= args.duration:
+            print(
+                f"ERROR: probe publisher for {args.topic} in {container} (identity {args.identity}) ran its "
+                f"{args.duration:.0f}s --duration without the graph reporting the topic; keep --duration "
+                f"above --advertise-timeout",
+                file=sys.stderr,
+            )
+        else:
+            print(
+                f"ERROR: probe publisher for {args.topic} exited or never started in {container} "
+                f"(identity {args.identity})",
+                file=sys.stderr,
+            )
+    else:
+        print(
+            f"ERROR: probe publisher for {args.topic} is running in {container} (identity {args.identity}) "
+            f"but the graph did not report it within {args.advertise_timeout:.0f}s; a loaded graph reports "
+            f"late, retry with a larger --advertise-timeout",
+            file=sys.stderr,
+        )
     return 1
 
 
@@ -8445,6 +8659,18 @@ def main(argv: list[str] | None = None) -> int:
             "Required for every peer in that mode; the same repository is at a different path on each machine."
         ),
     )
+    ota_smoke_parser.add_argument(
+        "--peer-exec",
+        action="append",
+        default=[],
+        metavar="PEER=COMMAND",
+        help=(
+            "Run this peer's commands through COMMAND instead of ssh; the script is appended as the final "
+            "argument, the same contract ssh has. For --install-mode checkout only, and mutually exclusive "
+            "with --peer-ssh for the same peer. Use it to put a peer behind a transport narrower than a "
+            "shell, such as a forced command that accepts only this project's own commands."
+        ),
+    )
     ota_smoke_parser.add_argument("--target-type", choices=["auto", "session", "scenario"], default="auto")
     ota_smoke_parser.add_argument("--interactive", action="store_true", help="Open a local control tmux UI.")
     ota_smoke_parser.add_argument("--stop", action="store_true", help="Stop an OTA smoke run.")
@@ -8907,7 +9133,13 @@ def main(argv: list[str] | None = None) -> int:
     probe_publish_parser.add_argument("--instance-id")
     probe_publish_parser.add_argument("--topic", default=ISOLATION_PROBE_TOPIC)
     probe_publish_parser.add_argument("--rate", type=float, default=5.0)
-    probe_publish_parser.add_argument("--duration", type=float, default=30.0)
+    probe_publish_parser.add_argument("--duration", type=float, default=_PROBE_DURATION_S)
+    probe_publish_parser.add_argument(
+        "--advertise-timeout",
+        type=float,
+        default=_PROBE_ADVERTISE_TIMEOUT_S,
+        help="Seconds to wait for the local graph to report the probe topic before failing.",
+    )
     probe_publish_parser.add_argument(
         "--stop", action="store_true", help="Stop a running probe publisher instead of starting one."
     )

{rosotacom_dev-2.5.dev7 → rosotacom_dev-2.5.dev10}/src/rosotacom_dev.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev7
+Version: 2.5.dev10
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause
@@ -494,6 +494,34 @@ in this mode — there is no staging to undo, and the workdir is your repository
 The run manifest records which mode and which version the peers ran, so a result
 can be attributed to an artefact rather than to a working copy.
 
+#### How the peers are reached: `--peer-exec`
+
+`--peer-ssh` gives the orchestrator a shell on the peer, which is more than a
+run needs and more than some machines should hand out. `--peer-exec` names the
+transport instead:
+
+```bash
+rosotacom ota-smoke 2_native_chatter --peer a=workstation --peer b=robot \
+  --install-mode checkout \
+  --peer-checkout a=/home/me/fleet_mgmt --peer-checkout b=/home/robot/fleet_mgmt \
+  --peer-exec b='remote-rosotacom robot'
+```
+
+The command is run with the script as its final argument — the contract
+`ssh host <script>` already has — so anything of that shape can carry a peer: a
+wrapper that logs what a run asks for, a container exec, or a forced command
+that accepts some scripts and refuses the rest. rosotacom does not know or care
+which; it only stops assuming that reaching a peer means having a shell on it.
+
+Two restrictions, both load-bearing. It applies to `--install-mode checkout`
+only, because the staging modes push a tar stream and a file write by taking
+the ssh client's own argv apart, and a transport that promises no more than
+"run this script" cannot carry them. And a peer takes either `--peer-ssh` or
+`--peer-exec`, never both: leaving it ambiguous hides which one carried the run.
+
+`-t` and `-o BatchMode=yes` are dropped rather than forwarded. They are options
+of one client, and a transport that is not ssh never agreed to understand them.
+
 ### Live status / debugging overview
 
 Enable a continuously-updated, per-topic pipeline overview by setting

{rosotacom_dev-2.5.dev7 → rosotacom_dev-2.5.dev10}/src/rosotacom_dev.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
   "tag": "2.4",
-  "distance": 7,
-  "node": "g69ca2b26fe2a31c86e07be8e3aa626ef9a839266",
+  "distance": 10,
+  "node": "gc0c857f77e0a3a0b17134fdc9e0edb7a70f80a1b",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-11"