Merge remote-tracking branch 'origin/main' into musa/cli

cli/planoai/trace_cmd.py

@@ -31,6 +31,17 @@ MAX_TRACES = 50
 MAX_SPANS_PER_TRACE = 500
 
 
+class TraceListenerBindError(RuntimeError):
+    """Raised when the OTLP/gRPC listener cannot bind to the requested address."""
+
+
+def _trace_listener_bind_error_message(address: str) -> str:
+    return (
+        f"Failed to start OTLP listener on {address}: address is already in use.\n"
+        "Stop the process using that port or run `planoai trace listen --port <PORT>`."
+    )
+
+
 @dataclass
 class TraceSummary:
     trace_id: str
@@ -496,7 +507,15 @@ def _start_trace_server(host: str, grpc_port: int) -> grpc.Server:
     trace_service_pb2_grpc.add_TraceServiceServicer_to_server(
         _OTLPTraceServicer(), grpc_server
     )
-    grpc_server.add_insecure_port(f"{host}:{grpc_port}")
+    address = f"{host}:{grpc_port}"
+    try:
+        bound_port = grpc_server.add_insecure_port(address)
+    except RuntimeError as exc:
+        raise TraceListenerBindError(
+            _trace_listener_bind_error_message(address)
+        ) from exc
+    if bound_port == 0:
+        raise TraceListenerBindError(_trace_listener_bind_error_message(address))
     grpc_server.start()
     return grpc_server