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.

docs/PHASES.md

@@ -67,12 +67,15 @@ machine show the captured desktop in a window.
 **Goal**: two peers on the same LAN can find each other and negotiate a
 session.
 
-- Implement mDNS/DNS-SD discovery with Avahi.
-- Implement JSON WebSocket signaling.
-- Extend CLI with `--peer-address` or `--discover`.
+- [x] Implement mDNS/DNS-SD discovery with Avahi.
+- [x] Implement JSON signaling (newline-delimited JSON over TCP for now;
+      the WebSocket transport is deferred to Phase 7 with its dependency).
+- [x] Extend CLI with `--peer` and `--discover`.
 
-**Validation**: two machines on the same LAN connect without hard-coded IP
-addresses.
+**Validation**: two peers connect without hard-coded IP addresses.
+Validated end-to-end over loopback: discovery finds the announced receiver,
+the sender negotiates a session over the signaling channel, and streams to
+the negotiated endpoint over both IPv4 and IPv6.
 
 ## Phase 7 — Resilience and Polish
 
@@ -89,4 +92,4 @@ where available.
 
 ## Current phase
 
-Phase 6 — LAN Signaling and Discovery.
+Phase 7 — Resilience and Polish.

docs/RUNBOOK.md

@@ -49,6 +49,27 @@ PipeWire proxy operation ran without the thread-loop lock — all pw
 calls that send messages (connect, stream, core) must happen under
 `pw_thread_loop_lock`.
 
+## LAN discovery and signaling (Phase 6)
+
+Two machines on the same LAN (mDNS via avahi-daemon, which must be running
+on both):
+
+```sh
+screencast --receive                # machine A: announce + window
+screencast --send                   # machine B: discovers A, negotiates, streams
+screencast --discover               # list receivers on the LAN
+```
+
+`--send` without `--peer` requires exactly one discovered receiver. Use
+`--peer HOST[:PORT]` to target a receiver directly (signaling port defaults
+to 5005), e.g. `--peer 192.168.178.20`.
+
+Operational note: never `kill -9` a running receiver — a SIGKILLed process
+cannot withdraw its mDNS registration, and avahi-daemon then keeps broken
+records for that service name until they expire (~75 min), making resolution
+time out for every peer. If that happens, `systemctl restart avahi-daemon`
+clears it. Always stop screencast with Ctrl-C (SIGTERM).
+
 ## Sender / receiver loopback (Phase 5, manual)
 
 Two terminals on the same desktop session: