feat: robot serve CLI command

[maxxgx]

Summary

Add CLI for serving and discovering SharedRobot over IPC or LAN.

Robot serve

❯ physicalai robot serve --config examples/so101/serve.yaml
22:48:31  INFO     Starting robot 'test' using physicalai.robot.SO101
22:48:31  INFO     SO-101 connected on /dev/ttyACM0 (role=follower, servos={'shoulder_pan': 1, 'shoulder_lift': 2, 'elbow_flex': 3, 'wrist_flex': 4, 'wrist_roll': 5, 'gripper': 6})
22:48:31  SUCCESS  Serving robot 'test' · 100 Hz
22:48:39  INFO     Subscriber(s) connected
22:49:01  INFO     Healthy · uptime 00:00:30 · subscriber(s) connected
22:49:08  INFO     No subscribers remain
22:49:09  INFO     Subscriber(s) connected
22:49:13  INFO     No subscribers remain
^C22:49:15  INFO     SO-101 disconnected from /dev/ttyACM0
22:49:15  INFO     Shutdown requested by SIGINT
22:49:15  SUCCESS  Robot 'test' disconnected safely

Robot discover

❯ physicalai robot discover --allow_remote
NAME  ROBOT CLASS             HOST   JOINTS
----  ----------------------  -----  ------
test  physicalai.robot.SO101  pcube       6

1 robot found in 2.0s

Why

Allows to connect an use a robot over LAN.

Validation

Breaking changes

• None

Related issues

• Closes #

[Copilot]

Pull request overview

Adds a new physicalai robot CLI group to serve a SharedRobot owner in the foreground and to discover reachable shared-robot owners, while refactoring the existing owner worker into a reusable in-process run_owner() runtime that supports structured exit reasons and operator-facing events.

Changes:

• Introduces physicalai robot serve (foreground owner) and physicalai robot discover (sorted human table or JSON array) CLI commands.
• Refactors the owner worker into run_owner() with structured OwnerResult/OwnerExitReason and OwnerEvent telemetry (subscriber transitions + heartbeat).
• Adds unit + process-level tests plus documentation and an SO101 serve example config.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/unit/robot/transport/test_owner_worker.py	Adds tests for owner loop termination reasons, events, and disconnect/ready failure handling.
tests/unit/robot/transport/test_owner_config.py	Extends config validation tests (name/rate/idle_timeout) and JSON roundtrip for idle_timeout=None.
tests/unit/robot/transport/fake.py	Enhances FakeRobot to simulate delayed observation failures and disconnect failure/markers for process tests.
tests/unit/cli/test_robot_cli.py	Adds CLI behavior tests for serve/discover output, logging, validation, signals, and a process-level SIGTERM/lock-release test.
tests/unit/cli/test_cli.py	Updates builtin command list expectation to include robot.
src/physicalai/robot/transport/_owner.py	Retains owner subprocess exit code and adds wait() API for supervising the worker.
src/physicalai/robot/transport/_owner_worker.py	Adds run_owner() runtime, structured results/events, idle-timeout disabling, and heartbeat/subscriber event emission.
src/physicalai/robot/transport/_owner_config.py	Tightens config validation (finite numeric types, name validation, dotted-path robot class) and allows idle_timeout=None.
src/physicalai/robot/transport/init.py	Re-exports owner config/runtime/result/event types from physicalai.robot.transport.
src/physicalai/cli/robot.py	Implements physicalai robot serve/discover parsers, foreground serve lifecycle, logging, and discovery formatting.
src/physicalai/cli/main.py	Registers robot as a builtin command and adjusts fast-help routing for direct-help-only invocations.
examples/so101/serve.yaml	Adds a portable example serve config with placeholders and local-only defaults.
docs/reference/cli.md	Documents the new robot serve and robot discover commands and their flags/behavior.
docs/how-to/runtime/share-a-robot.md	Adds an operator-focused walkthrough for serving and discovering shared robots.
docs/explanation/cli.md	Updates the runtime command list to include robot serve/robot discover.
docs/development/robot-serve-plan.md	Adds/updates the design/contract document describing lifecycle invariants and CLI behavior.