release: bump version to 0.50.0

docs/technical/en/ops-planet-sh-startup.md

@@ -177,7 +177,7 @@ Frontend startup now has an additional pre-start cleanup retry layer:
 - `PORT_PRESTART_RETRIES`: defaults to 3 attempts.
 - `PORT_PRESTART_RETRY_INTERVAL`: defaults to 2 seconds.
 
-`kill_port_if_requested()` only kills processes when the current environment can identify listening PIDs. If no PID is visible but the port still cannot bind, it logs diagnostics and lets the service startup flow make the final decision. `start_frontend_with_retry()` only enters the pre-cleanup retry path when a listener PID is visible, so the script no longer spends its retry budget repeatedly killing nothing while a host-side or external network namespace is still releasing the port. Seeing "no listener found but port still unavailable" on the first restart usually means the external environment is still releasing the port, not that a local process cleanup loop is useful.
+`kill_port_if_requested()` first cleans listener PIDs visible in the current environment. It only checks for Windows-side listeners when the script detects WSL, no local listener PID is visible, and the port still cannot bind. In that WSL-only path it tries to stop the owning Windows service or force-stop the owning process through PowerShell. If permissions are missing, or a system service such as `iphlpsvc` refuses to stop, the script prints the Windows listener details and stops startup immediately instead of launching the service into the same port error. Non-WSL environments do not run the Windows cleanup path. At that point, use Administrator PowerShell to clear the portproxy/service ownership, or choose another port.
 
 ## Issue 4: `restart` Behavior
 
@@ -188,6 +188,92 @@ Before the stamp path fix:
 
 After moving the stamp file, plain `restart` uses the same `stop + start` behavior and the same fingerprint check as `restart -b`.
 
+## Optional Motion Agent Startup
+
+`planet.sh` can now manage the local Motion Capture Agent. It is disabled by default so ordinary development machines do not fail startup when cameras, OpenCV, or MediaPipe are unavailable.
+
+Start it with:
+
+```bash
+./planet.sh start --motion-agent
+```
+
+Common options:
+
+- `--motion-agent` / `-m`: start or restart the Motion Agent for this command.
+- `--motion-agent-port <port>`: override the default WebSocket port `8765`.
+- `--motion-agent-camera-indexes <indexes>`: override auto-detected camera indexes, for example `0` or `0,1`. The same can be provided through `MOTION_AGENT_CAMERA_INDEXES=0,1`.
+- `--motion-agent-camera-urls <urls>`: use RTSP/HTTP camera streams, useful for WSL, phone cameras, or network cameras. The same can be provided through `MOTION_AGENT_CAMERA_URLS=...`.
+- `--motion-agent-dry-run`: start only the protocol service without opening cameras or loading CV dependencies; useful for Web client debugging.
+
+Non-dry-run live mode checks `mediapipe` and `opencv-python` before startup. If the current `.venv` is missing them, the script automatically runs:
+
+```bash
+uv add mediapipe opencv-python
+```
+
+To disable startup-time auto-install:
+
+```bash
+PLANET_MOTION_AGENT_AUTO_INSTALL=0 ./planet.sh start --motion-agent
+```
+
+Live mode auto-detects `/dev/video*` and passes the first two indexes to the Motion Agent. In WSL, Windows cameras usually do not appear as `/dev/video*` automatically. Check available devices first:
+
+```bash
+ls /dev/video*
+```
+
+To override auto-detection, pass indexes explicitly:
+
+```bash
+./planet.sh start --motion-agent --motion-agent-camera-indexes 1,2
+```
+
+In WSL, the more general path is to connect a phone or network camera through an RTSP/HTTP stream:
+
+```bash
+./planet.sh start --motion-agent --motion-agent-camera-urls http://192.168.1.20:8080/video
+```
+
+If WSL has no `/dev/video*` and no `--motion-agent-camera-urls` is provided, live startup stops and prints guidance instead of silently falling back to dry-run. Choose one of:
+
+```bash
+./planet.sh start --motion-agent --motion-agent-camera-urls http://<phone-ip>:8080/video
+./planet.sh start --motion-agent --motion-agent-dry-run
+```
+
+Automatic dry-run fallback only happens when `PLANET_MOTION_AGENT_WSL_ALLOW_DRY_RUN_FALLBACK=1` is explicitly set.
+
+Environment-variable startup is also supported:
+
+```bash
+PLANET_START_MOTION_AGENT=1 ./planet.sh start
+MOTION_AGENT_DRY_RUN=1 PLANET_START_MOTION_AGENT=1 ./planet.sh start
+```
+
+Logs:
+
+```bash
+./planet.sh log -m
+```
+
+To expose it together with the frontend on the LAN:
+
+```bash
+./planet.sh start --allow-lan --motion-agent
+```
+
+In this mode the Motion Agent binds `0.0.0.0`, and startup output prints both the local WebSocket URL and the recommended LAN WebSocket URL. When opening Earth from another LAN browser, point `motionAgent` at the display machine:
+
+```text
+http://<LAN_IP>:3000/earth?motion=1&motionAgent=ws://<LAN_IP>:8765/ws/gestures
+```
+
+`./planet.sh stop` also stops a script-managed Motion Agent. `./planet.sh health` reports its online/offline status. The Earth page still requires `?motion=1` or browser local storage to enable the Web client connection explicitly.
+
+For ordinary web, WSL, or no-install demo scenarios, you can skip Motion Agent entirely: choose the `Browser Camera` input source in Earth settings and enable Motion Debug Mode. This route uses browser `getUserMedia`, so the page must run on HTTPS or localhost and the user must grant camera permission.
+
 ## Other Cleanup
 
 Two redundant `sleep 3` waits were removed because health checks already cover the same readiness: