feat(arq): keepalive ACK threshold env-tunable (ULTRA_KEEPALIVE_ACK_MS) + honest v1 A/B result — mechanism works, epoch-noise-dominated, v2 (fire at ~8-10s) filed

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019btwFxDt7D19SZSqPYvZnk

Author: secup

docs/CHANGELOG.md

@@ -84,6 +84,32 @@ Verified: ctest 85/85; good@20 PASS 1600 bps.
 
 ---
 
+## 2026-07-14 — feat(arq): keepalive ACK v1 (default off) + honest rig A/B — mechanism works, benefit epoch-noise-dominated; v2 (fire sooner) filed
+
+Built the receiver keepalive ACK for BUG-ANCHOR-WAIT-NO-ACK-STALL: re-emit the
+current cumulative ACK when the ACK side has been silent > threshold (default
+25 s, env ULTRA_KEEPALIVE_ACK_MS) during an active receive (rx_base>0 &&
+last_rx_more_data). Sender resends holes on any tone-burst ACK → converts the
+44.68 s RTO stall into a faster turnaround. Env-gated ULTRA_KEEPALIVE_ACK,
+default off; ctest 86/86 byte-identical; routes through listen-before-ACK.
+
+Rig A/B (F284-F289, interleaved MPG@25, KA off vs on): the keepalive FIRES
+correctly (1-2×/transfer, exactly on the anchor-reject stalls) and is safe
+(cannot cause failures). But the A/B is INCONCLUSIVE — the KA-ON arm drew
+consistently rougher epochs (fails 2386/487/860 vs OFF 386/216/645; means ON
+1.51 vs OFF 2.45 is pure epoch luck). The one clean pair (F288/F289, comparable
+fails) is a faint POSITIVE: ON matched OFF's goodput despite 33% more fails.
+
+LESSON: the 25 s threshold catches the stall LATE (~19 s of 44 s saved). Since
+the keepalive routes through listen-before-ACK (mid-burst fire is DEFERRED not
+collided), a shorter threshold is SAFE. **v2 (do next): ULTRA_KEEPALIVE_ACK_MS
+≈ 8000-10000** — catches the stall ~15 s earlier (~36 s saved), no rebuild.
+Or sender-side "no-ACK-after-burst → immediate full-anchor resend". Keep v1
+default-off until v2 is rig-A/B-confirmed with a many-pair batch (the effect
+is intermittent + small vs the huge MPG@25 epoch noise).
+
+---
+
 ## 2026-07-14 — diag: MPG@25 natural batch + BUG-ANCHOR-WAIT-NO-ACK-STALL (the marginal-SNR throughput lever, ~+30%)
 
 MPG@25 natural (F279-F283, ACE off, no force): 1.80/2.48/1.38/2.32/2.81,

docs/KNOWN_BUGS.md

@@ -49,7 +49,15 @@ Fixed/obsolete historical deep dives belong in `docs/CHANGELOG.md`.
   tone-burst ACK with the cumulative base UNCHANGED** ("no progress, resend") —
   which breaks the 44 s silence and gets an immediate resend. So the receiver
   does NOT need to decode the weak burst; it only needs to NOT be silent.
-- **Fix approaches (next session — protocol/sync path, rig-validate; ACK
+- **Status (2026-07-14): v1 SHIPPED (keepalive ACK, ULTRA_KEEPALIVE_ACK default
+  off, fc75b5b+). Mechanism confirmed on rig (fires 1-2×/transfer on the
+  stall), safe (ctest clean, cannot cause fails), but the 25 s threshold
+  catches the stall late and the A/B was epoch-noise-dominated (inconclusive,
+  faint positive in the one clean pair). NEXT = v2: ULTRA_KEEPALIVE_ACK_MS
+  ≈ 8-10 s (safe — routes through listen-before-ACK, mid-burst fire is
+  deferred; catches the stall ~15 s earlier) + many-pair rig A/B; then flip
+  default-on. See CHANGELOG 2026-07-14.**
+- **Fix approaches (protocol/sync path, rig-validate; ACK
   contract has regressed before, build carefully):**
   1. ACK-LIVENESS ACCEPT: when a burst is rejected in full-anchor-wait but
      light_found with clear energy (corr above a low floor, e.g. 0.15 — a real

src/protocol/connection.cpp

@@ -4428,8 +4428,22 @@ void Connection::tick(uint32_t elapsed_ms) {
                 const char* e = std::getenv("ULTRA_KEEPALIVE_ACK");
                 return e != nullptr && e[0] != '\0' && e[0] != '0';
             }();
+            // Threshold env-tunable (ULTRA_KEEPALIVE_ACK_MS, default 25000).
+            // The keepalive routes through listen-before-ACK (defers on channel
+            // busy), so a mid-legit-burst fire is deferred, not collided —
+            // meaning a SHORTER threshold (v2, ~8-10 s) is safe and catches the
+            // stall ~15 s earlier. Left at 25 s by default pending the v2 rig
+            // A/B (F284-F289 at 25 s: fires 1-2×/transfer on the real stall,
+            // benefit epoch-noise-dominated).
+            static const uint32_t keepalive_ack_ms = [] {
+                if (const char* e = std::getenv("ULTRA_KEEPALIVE_ACK_MS")) {
+                    const long v = std::atol(e);
+                    if (v >= 3000 && v <= 60000) return static_cast<uint32_t>(v);
+                }
+                return 25000u;
+            }();
             if (keepalive_ack_enabled) {
-                arq_.keepaliveAckIfStalled(25000u);
+                arq_.keepaliveAckIfStalled(keepalive_ack_ms);
             }
 
             // RX-AUTHORITY: age the verdict-SNR ring (stale readings must not