feat(network): implement Phase 6 LAN discovery and session signaling

Add mDNS/DNS-SD discovery and JSON session negotiation so two peers on
a LAN connect without hard-coded addresses.

- Discovery (Avahi threaded-poll client): the receiver announces
  _screencast._tcp with its signaling port; senders browse and resolve
  peers. Strict lock ordering (poll lock before state mutex) keeps the
  callbacks deadlock-free; name collisions rename via
  avahi_alternative_service_name.
- Signaling: one JSON object per newline-terminated TCP line. The
  receiver hosts a server (port 5005) and answers session offers with
  its RTP port; senders connect, offer, and stream to the negotiated
  endpoint. WebSocket was deferred: no WS library is installed, the
  skill permits plain TCP, and the wire format is transport-agnostic.
- Dual-stack transports: this machine resolves its own services over
  IPv6, so getaddrinfo now runs AF_UNSPEC and listeners bind IPv6 with
  IPV6_V6ONLY=0 (IPv4 fallback), covering UDP and TCP alike. The
  signaling client shutdown now uses shutdown() so a reader blocked in
  recv() cannot hang the join (a plain close() does not wake it).
- CLI: --discover lists receivers (deduped to one entry per host);
  --send auto-disovers when exactly one receiver is found; --peer
  targets a receiver directly; --signaling-port overrides the default.

Validation: meson test 5/5 (new signaling round-trip test), valgrind
clean. End-to-end over loopback: --discover finds the announced
receiver, a probe negotiated a session and streamed 60 frames over
both IPv4 and IPv6, and the receiver reported stream started. mDNS
resolution was verified against avahi-browse as an independent
reference.

include/screencast/app/cli.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#include <cstdint>
 #include <optional>
 #include <string_view>
 #include <variant>
@@ -7,17 +8,22 @@
 namespace sc {
 
 struct SendCommand {
-    std::string_view target = "monitor"; // monitor, window, region
-    std::string_view peer_address;       // optional
+    std::string_view target = "monitor"; // monitor, window
+    std::string_view peer_address;       // optional; empty means auto-discover
     int bitrate_kbps = 4000;
 };
 
 struct ReceiveCommand {
-    std::string_view peer_address; // optional
+    std::string_view peer_address; // optional, informational
     int local_rtp_port = 5004;
+    int signaling_port = 5005;
 };
 
-using Command = std::variant<SendCommand, ReceiveCommand>;
+struct DiscoverCommand {
+    int timeout_seconds = 3;
+};
+
+using Command = std::variant<SendCommand, ReceiveCommand, DiscoverCommand>;
 
 // Parse command line arguments. Prints usage and returns std::nullopt on error.
 // `argv` is `char const* const*` so both `main`'s `char**` and const arrays

include/screencast/app/pipeline.h

@@ -26,6 +26,8 @@ struct ReceiverPipelineConfig {
     Endpoint local_rtp_endpoint;
     std::optional<Endpoint> peer_signaling;
     RendererConfig renderer;
+    // TCP port the signaling server listens on (offers arrive here).
+    std::uint16_t signaling_port = 5005;
 };
 
 // Sender pipeline: capture → encode → packetize → RTP/UDP.

include/screencast/network/discovery.h

@@ -1,5 +1,7 @@
 #pragma once
 
+#include "screencast/network/error.h"
+
 #include <cstdint>
 #include <functional>
 #include <memory>
@@ -26,11 +28,14 @@ class DiscoveryService {
     virtual bool browse(PeerCallback on_peer) = 0;
 
     virtual void stop() = 0;
+
+    // Diagnostic message from the last failure (empty if none).
+    virtual std::string last_error() const = 0;
 };
 
 class DiscoveryFactory {
   public:
-    static std::unique_ptr<DiscoveryService> create_avahi();
+    static NetworkResult<std::unique_ptr<DiscoveryService>> create_avahi();
 };
 
 } // namespace sc

include/screencast/network/error.h

@@ -0,0 +1,36 @@
+#pragma once
+
+#include <string>
+#include <variant>
+
+namespace sc {
+
+struct NetworkError {
+    std::string message;
+};
+
+// C++20 does not provide std::expected. Use a variant-based result type so
+// fallible network operations do not rely on exceptions.
+template <typename T> using NetworkResult = std::variant<T, NetworkError>;
+
+template <typename T> constexpr bool is_network_error(const NetworkResult<T>& result) noexcept {
+    return std::holds_alternative<NetworkError>(result);
+}
+
+template <typename T> T& network_value(NetworkResult<T>& result) {
+    return std::get<T>(result);
+}
+
+template <typename T> const T& network_value(const NetworkResult<T>& result) {
+    return std::get<T>(result);
+}
+
+template <typename T> NetworkError& network_error(NetworkResult<T>& result) {
+    return std::get<NetworkError>(result);
+}
+
+template <typename T> const NetworkError& network_error(const NetworkResult<T>& result) {
+    return std::get<NetworkError>(result);
+}
+
+} // namespace sc

include/screencast/network/signaling.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#include "screencast/network/error.h"
 #include "screencast/network/transport.h"
 
 #include <cstdint>
@@ -10,19 +11,23 @@
 
 namespace sc {
 
-// JSON-based control messages exchanged before or during a session.
+// JSON-based control messages exchanged before or during a session. The wire
+// format is one JSON object per newline-terminated TCP line; a WebSocket
+// transport can replace TCP in a later phase without changing these types.
 struct SessionOffer {
     std::string session_id;
     std::string codec_name;
-    int width = 0;
+    int width = 0; // informational; the stream carries its own SPS/PPS
     int height = 0;
     int frame_rate_num = 30;
     int frame_rate_den = 1;
-    Endpoint rtp_endpoint;
+    Endpoint rtp_endpoint; // unused by the receiver; kept for symmetry
 };
 
 struct SessionAnswer {
     std::string session_id;
+    // The address may be empty: the sender then targets the address of its
+    // signaling connection and the port carried here.
     Endpoint rtp_endpoint;
 };
 
@@ -34,6 +39,7 @@ class SignalingChannel {
 
     virtual ~SignalingChannel() = default;
 
+    // Client channels connect to a receiver's signaling server.
     virtual bool connect(const Endpoint& server) = 0;
     virtual void send(const SignalingMessage& message) = 0;
     virtual void on_message(MessageCallback callback) = 0;
@@ -42,8 +48,11 @@ class SignalingChannel {
 
 class SignalingFactory {
   public:
-    static std::unique_ptr<SignalingChannel> create_websocket_client();
-    static std::unique_ptr<SignalingChannel> create_websocket_server(uint16_t port);
+    // A client channel that connects to a receiver's signaling server.
+    static NetworkResult<std::unique_ptr<SignalingChannel>> create_client();
+    // A server channel listening on the given port; it keeps the most
+    // recent connection as its active peer.
+    static NetworkResult<std::unique_ptr<SignalingChannel>> create_server(uint16_t port);
 };
 
 } // namespace sc