Add handshake retransmission on periodic announce

When an announce is received from a peer whose handshake is incomplete,
retransmit the appropriate CONNECT packet:
- IDLE/SYN_SENT: retransmit SYN
- SYN_RECEIVED: retransmit SYN+ACK
- CONFIRMED: retransmit ACK (helps peer stuck in SYN_RECEIVED)

This handles all dropped packet scenarios by piggybacking on the
~500ms announce interval. No separate retransmission timer needed.

Changes:
- Discovery::process_announce now returns AnnounceResult with is_new
  and response_flags fields
- NUClearNet uses the result to send CONNECT and force re-announce
- Added unit tests for retransmission in each handshake state
- Documented resilience behavior in nuclearnet.md

Author: TrentHouliston

docs/explanation/nuclearnet.md

@@ -336,6 +336,50 @@ sequenceDiagram
 Duplicate or out-of-order handshake packets do not cause state regressions —
 once a peer reaches CONFIRMED, it stays there.
 
+#### Handshake resilience
+
+UDP packets can be dropped at any point in the handshake.
+Rather than adding a separate retransmission timer,
+the handshake piggybacks on the periodic announce cycle (~500ms):
+
+Each time an announce is received from a peer whose handshake is incomplete,
+the appropriate CONNECT packet is retransmitted:
+
+| Current state | Retransmit | Purpose                                         |
+| ------------- | ---------- | ----------------------------------------------- |
+| IDLE          | SYN        | Initial SYN was never sent or was dropped       |
+| SYN_SENT      | SYN        | Our SYN was dropped, retry                      |
+| SYN_RECEIVED  | SYN+ACK    | Our SYN+ACK was dropped, retry                  |
+| CONFIRMED     | ACK        | Our ACK was dropped, help peer finish handshake |
+
+This provides automatic recovery for every drop scenario:
+
+```mermaid
+sequenceDiagram
+    participant A as Node A
+    participant B as Node B
+
+    A->>B: ConnectPacket (SYN) [data port]
+    Note over A: handshake = SYN_SENT
+    Note over B: SYN dropped ✗
+
+    B-->>A: AnnouncePacket [multicast, periodic]
+    Note over A: Peer not connected, retransmit
+    A->>B: ConnectPacket (SYN) [data port, retransmit]
+
+    Note over B: Received SYN this time
+    B->>A: ConnectPacket (SYN+ACK) [data port]
+    Note over A: handshake = CONFIRMED ✓
+    A->>B: ConnectPacket (ACK) [data port]
+    Note over B: handshake = CONFIRMED ✓
+```
+
+Since both peers announce periodically,
+a dropped packet is retried within at most one announce interval.
+If the data path is permanently broken in one direction,
+the handshake will never complete — which is correct,
+since bidirectional data connectivity is required for message exchange.
+
 #### Connect packet
 
 ```mermaid

src/nuclearnet/Discovery.cpp

@@ -98,13 +98,15 @@
             return packet;
         }
 
-        void Discovery::process_announce(const sock_t& source,
+        Discovery::AnnounceResult Discovery::process_announce(const sock_t& source,
                                           const uint8_t* data,
                                           std::size_t length,
                                           std::chrono::steady_clock::time_point now) {
+            AnnounceResult announce_result;
+
             // Minimum size: header(5) + name_length(2) + num_subscriptions(2) = 9
             if (length < sizeof(PacketHeader) + sizeof(uint16_t) + sizeof(uint16_t)) {
-                return;
+                return announce_result;
             }
 
             const uint8_t* ptr    = data + sizeof(PacketHeader);
@@ -118,7 +120,7 @@
 
             // Validate name fits
             if (remaining < name_len + sizeof(uint16_t)) {
-                return;
+                return announce_result;
             }
 
             // Read name
@@ -128,7 +130,7 @@
 
             // Ignore empty names
             if (name.empty()) {
-                return;
+                return announce_result;
             }
 
             // Read subscription count
@@ -139,7 +141,7 @@
 
             // Validate subscriptions fit
             if (remaining < num_subs * sizeof(uint64_t)) {
-                return;
+                return announce_result;
             }
 
             // Read subscriptions
@@ -161,6 +163,7 @@
                 auto it = peers.find(source);
                 if (it == peers.end()) {
                     // New peer — record with announce_heard = true
+                    announce_result.is_new = true;
                     PeerInfo info;
                     info.name            = name;
                     info.address         = source;
@@ -193,6 +196,21 @@
                         peer.subscriptions = std::move(subscriptions);
                         subs_changed       = true;
                     }
+
+                    // Determine retransmit flags based on handshake state
+                    switch (peer.handshake) {
+                        case HandshakeState::IDLE:
+                        case HandshakeState::SYN_SENT:
+                            announce_result.response_flags = SYN;
+                            break;
+                        case HandshakeState::SYN_RECEIVED:
+                            announce_result.response_flags = SYN | CON_ACK;
+                            break;
+                        case HandshakeState::CONFIRMED:
+                            // Send ACK to help the other side if they're stuck in SYN_RECEIVED
+                            announce_result.response_flags = CON_ACK;
+                            break;
+                    }
                 }
             }
 
@@ -216,6 +234,8 @@
                     subscription_change_callback(info);
                 }
             }
+
+            return announce_result;
         }
 
         void Discovery::process_leave(const sock_t& source) {

src/nuclearnet/Discovery.hpp

@@ -138,16 +138,23 @@ namespace network {
 
         /**
          * Process a received announce packet from a peer.
+         * Returns information about what action to take (send CONNECT, re-announce, etc.)
          *
          * @param source  The UDP source address (IP + port) of the packet
          * @param data    The raw packet data
          * @param length  The length of the packet data
          * @param now     The current time (defaults to steady_clock::now())
+         *
+         * @return Result indicating whether this is a new peer and what CONNECT flags to send
          */
-        void process_announce(const sock_t& source,
-                              const uint8_t* data,
-                              std::size_t length,
-                              std::chrono::steady_clock::time_point now = std::chrono::steady_clock::now());
+        struct AnnounceResult {
+            bool is_new = false;          ///< Whether this was a previously unknown peer
+            uint8_t response_flags = 0;   ///< CONNECT flags to send (0 = don't send)
+        };
+        AnnounceResult process_announce(const sock_t& source,
+                                        const uint8_t* data,
+                                        std::size_t length,
+                                        std::chrono::steady_clock::time_point now = std::chrono::steady_clock::now());
 
         /**
          * Process a received leave packet from a peer.

src/nuclearnet/NUClearNet.cpp

@@ -436,18 +436,24 @@ namespace network {
             case ANNOUNCE: {
                 // Check if this is a new peer before processing (which adds them)
                 const bool is_new_peer = !discovery->has_peer(source);
-                discovery->process_announce(source, data, length);
+                auto announce_result = discovery->process_announce(source, data, length);
 
-                if (is_new_peer) {
+                if (announce_result.is_new) {
                     // Force an immediate announce to the multicast/broadcast group
                     // so the new peer hears us on the announce channel (confirms our_d→their_a)
                     announce();
                     last_announce = std::chrono::steady_clock::now();
+                }
+
+                // Send CONNECT packet if the handshake needs it (initial SYN or retransmit)
+                if (announce_result.response_flags != 0) {
+                    auto pkt = Discovery::build_connect_packet(announce_result.response_flags);
+                    send_buf(data_fd, source, pkt.data(), pkt.size());
 
-                    // Send SYN to the peer's data port to initiate the data path handshake
-                    auto syn = Discovery::build_connect_packet(SYN);
-                    send_buf(data_fd, source, syn.data(), syn.size());
-                    discovery->mark_syn_sent(source);
+                    // Mark SYN_SENT if we're sending a SYN (only advances from IDLE)
+                    if ((announce_result.response_flags & SYN) != 0) {
+                        discovery->mark_syn_sent(source);
+                    }
                 }
             } break;
 

tests/tests/nuclearnet/Discovery.cpp

@@ -363,3 +363,80 @@ SCENARIO("Discovery connection deferred until announce heard", "[nuclearnet][dis
     REQUIRE(join_called);
     REQUIRE(disc.is_connected(peer_addr));
 }
+
+SCENARIO("Discovery retransmits SYN when announce received in SYN_SENT state", "[nuclearnet][discovery]") {
+    Discovery disc(std::chrono::seconds(5));
+
+    sock_t peer_addr = make_addr(0x0A000001, 5000);
+
+    // First announce — new peer
+    auto announce = Discovery::build_announce_packet("peer_a", {});
+    auto result = disc.process_announce(peer_addr, announce.data(), announce.size());
+    REQUIRE(result.is_new);
+
+    // We send SYN (externally) and mark state
+    disc.mark_syn_sent(peer_addr);
+    REQUIRE(disc.get_peer(peer_addr)->handshake == HandshakeState::SYN_SENT);
+
+    // SYN was dropped. Another announce arrives — should indicate SYN retransmit
+    result = disc.process_announce(peer_addr, announce.data(), announce.size());
+    REQUIRE_FALSE(result.is_new);
+    REQUIRE(result.response_flags == SYN);
+}
+
+SCENARIO("Discovery retransmits SYN+ACK when announce received in SYN_RECEIVED state", "[nuclearnet][discovery]") {
+    Discovery disc(std::chrono::seconds(5));
+
+    sock_t peer_addr = make_addr(0x0A000001, 5000);
+
+    // Add peer via announce
+    auto announce = Discovery::build_announce_packet("peer_a", {});
+    disc.process_announce(peer_addr, announce.data(), announce.size());
+
+    // Peer sends SYN — we go to SYN_RECEIVED
+    auto connect_result = disc.process_connect(peer_addr, SYN);
+    REQUIRE(connect_result.response_flags == (SYN | CON_ACK));
+    REQUIRE(disc.get_peer(peer_addr)->handshake == HandshakeState::SYN_RECEIVED);
+
+    // Our SYN+ACK was dropped. Another announce arrives — should indicate SYN+ACK retransmit
+    auto result = disc.process_announce(peer_addr, announce.data(), announce.size());
+    REQUIRE_FALSE(result.is_new);
+    REQUIRE(result.response_flags == (SYN | CON_ACK));
+}
+
+SCENARIO("Discovery retransmits ACK when announce received in CONFIRMED but peer not connected", "[nuclearnet][discovery]") {
+    Discovery disc(std::chrono::seconds(5));
+
+    sock_t peer_addr = make_addr(0x0A000001, 5000);
+
+    // Add peer via announce and complete handshake
+    auto announce = Discovery::build_announce_packet("peer_a", {});
+    disc.process_announce(peer_addr, announce.data(), announce.size());
+    disc.mark_syn_sent(peer_addr);
+    auto connect_result = disc.process_connect(peer_addr, SYN | CON_ACK);
+    REQUIRE(connect_result.just_connected);
+    REQUIRE(disc.is_connected(peer_addr));
+
+    // Peer is fully connected — no retransmit needed
+    auto result = disc.process_announce(peer_addr, announce.data(), announce.size());
+    REQUIRE_FALSE(result.is_new);
+    REQUIRE(result.response_flags == CON_ACK);
+}
+
+SCENARIO("Discovery no retransmit for IDLE peer (not yet sent SYN)", "[nuclearnet][discovery]") {
+    Discovery disc(std::chrono::seconds(5));
+
+    sock_t peer_addr = make_addr(0x0A000001, 5000);
+
+    // First announce — new peer, handshake IDLE
+    auto announce = Discovery::build_announce_packet("peer_a", {});
+    auto result = disc.process_announce(peer_addr, announce.data(), announce.size());
+    REQUIRE(result.is_new);
+    REQUIRE(disc.get_peer(peer_addr)->handshake == HandshakeState::IDLE);
+
+    // Second announce — peer still in IDLE (we haven't sent SYN yet)
+    // Should indicate SYN needed
+    result = disc.process_announce(peer_addr, announce.data(), announce.size());
+    REQUIRE_FALSE(result.is_new);
+    REQUIRE(result.response_flags == SYN);
+}