test(aggregation): prove a peer that comes back is taken back

Retention is well covered in one direction only. Every case that watches a peer
go quiet leaves it quiet, so nothing observed the return trip, and the design
doc's promise that a recovering peer is re-included rested on no test at all. A
regression that kept replaying the retained copy would have poisoned the tree
after a single outage with every suite still green.

A peer is killed and then replaced through the same gate the trigger suite uses,
so the return happens when the case asks for it rather than on a clock. The
declared member's flag is watched down and back up, the runtime-discovered one
disappears and is merged again, a read that answered not-responding answers with
the peer's own payload, and the retained declaration does not linger beside the
live copy.

The two availability signals do not clear together, and the case pins that
rather than papering over it: reachability clears on the first refresh after the
health check passes, while is_online is the peer's own account of its graph and
follows a refresh or two later.

Author: bburda

docs/config/aggregation.rst

@@ -465,6 +465,15 @@ What clients see then depends on the peer's health check:
   incomplete refresh is logged at ``WARN``. Availability is untouched - the
   peer can still be reached; this gateway merely failed to read all of it.
 
+A peer that starts answering again is read again on the next refresh, and a
+retained declaration is replayed only for a peer that could not be read - so
+the live answer replaces the retained one rather than being merged beside it.
+``x-medkit.available`` clears on that refresh, and the entities the peer only
+discovered at runtime, dropped while it was silent, are merged again with it.
+``x-medkit.is_online`` is the peer's own account of an App rather than a
+statement about the link, so after a gateway restart it stays ``false`` until
+that gateway has relinked its ROS graph.
+
 Two statuses are read rather than treated as failures:
 
 - ``404`` on a nested collection route means the peer runs a gateway version

src/ros2_medkit_gateway/design/aggregation.rst

@@ -694,7 +694,15 @@ GETs ``/api/v1/health`` on its peer. If the health check fails, the peer is
 marked unhealthy and excluded from fan-out queries and entity fetching.
 
 When a peer recovers (health check succeeds again), it is automatically
-re-included.
+re-included: the next refresh fetches it like any other healthy peer, and since
+a retained declaration is replayed only for a peer that could not be read that
+cycle, the live answer replaces the retained one wholesale rather than being
+merged beside it. ``x-medkit.available`` therefore clears on that same refresh,
+and the entities the peer only discovered at runtime - dropped while it was
+silent - are merged again with it. ``x-medkit.is_online`` is read off the wire
+as the peer's own account of an App, not as a statement about the link, so an
+App on a gateway that has just restarted stays ``false`` for however many
+refreshes that gateway needs to relink its ROS graph, and then turns true.
 
 ``PeerClient::fetch_entities()`` reads a peer over several requests and either
 describes it whole or reports failure: a dead connection, a status a route has

src/ros2_medkit_integration_tests/CMakeLists.txt

@@ -255,6 +255,7 @@ if(BUILD_TESTING)
   # four where two are used takes two away from whatever the runner could
   # otherwise have started alongside it.
   set(_TWO_GATEWAY_TESTS
+    test_peer_recovery
     test_triggers_restore_before_discovery)
   set(_TWO_GATEWAY_DOMAINS 2)
 
@@ -297,6 +298,7 @@ if(BUILD_TESTING)
     test_graph_provider_greenwave 300
     test_graph_provider_stale 300
     test_graph_provider_sse 300
+    test_peer_recovery 300
     test_triggers_restore_before_discovery 300)
   # Names actually matched against a discovered test_name in the two loops
   # below. Checked against _MEDKIT_TEST_TIMEOUT_OVERRIDES itself after both