feat(arq): keepalive ACK DEFAULT-ON — universal channel_busy_query_ makes it collision-safe on GUI + TNC (fixes the default-on blocker)

Connection gains channel_busy_query_ (mirrors setTxActiveProvider), wired from
the modem by both app.cpp (GUI) and ultra_tnc.cpp (headless). Keepalive
self-gates on channel-busy → no listen-before-ACK dependency. UltraTncSimAudio
(broke at 264s timeout with default-on before) now PASSES 58.8s; ctest 86/86.
8s stall-cap unchanged on the rig. Caps the 44s marginal-SNR stall at 8s
everywhere.

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,25 @@ Verified: ctest 85/85; good@20 PASS 1600 bps.
 
 ---
 
+## 2026-07-14 — feat(arq): keepalive ACK now DEFAULT-ON — universal channel-busy gate makes it collision-safe on GUI AND TNC
+
+The TNC-path blocker is fixed. The keepalive's collision-safety no longer
+depends on the GUI-only listen-before-ACK: the Connection gained a
+channel_busy_query_ (mirrors setTxActiveProvider) that BOTH the GUI (app.cpp)
+and the headless TNC (ultra_tnc.cpp) wire from the modem
+(channelBusyForTx || burstAirSamplesRemaining>0). The keepalive checks it and
+skips while a burst is arriving — self-gating, universal. So the 8 s keepalive
+is now DEFAULT-ON (opt-out ULTRA_KEEPALIVE_ACK=0).
+
+Verified: UltraTncSimAudio — which default-on BROKE before the gate (264 s
+timeout) — now PASSES (58.8 s) with default-on. Full ctest 86/86. The 8 s
+stall-cap (rig-proven F290/F291) is unchanged on the GUI: after a rejected
+burst the channel is idle → busy=false → keepalive fires at 8 s exactly as
+before. Answers the operator's "no ACK at SNR 25": the 44 s marginal-SNR stall
+is now capped at 8 s everywhere.
+
+---
+
 ## 2026-07-14 — feat(arq): keepalive ACK v2 (8 s) — rig-PROVEN (stall 44→8 s, no collision), default-off blocked by TNC listen-before-ACK gap
 
 Direct silence-gap measurement (epoch-independent, unlike the goodput A/B)

src/gui/app.cpp

@@ -542,6 +542,13 @@ App::App(const Options& opts) : options_(opts), simulation_enabled_(opts.enable_
     protocol_.setTxActiveProvider(
         [this] { return tx_in_progress_.load(std::memory_order_relaxed); });
 
+    // Keepalive ACK universal busy gate: don't re-emit an ACK while a burst is
+    // arriving (would collide). Mirrors the GUI's own listen-before-ACK signal.
+    protocol_.setChannelBusyQuery([this] {
+        return modem_.channelBusyForTx() ||
+               modem_.burstAirSamplesRemaining() > 0;
+    });
+
     // Set up status callback to show codeword progress in RX log
     modem_.setStatusCallback([this](const std::string& status) {
         enqueueOperatorLogLine(status);

src/protocol/connection.cpp

@@ -4424,20 +4424,18 @@ void Connection::tick(uint32_t elapsed_ms) {
             // routes through listen-before-ACK; the sender resends holes on any
             // tone-burst ACK (turn boundary). v2 (filed): channel-gated shorter
             // threshold for a bigger saving.
-            // ULTRA_KEEPALIVE_ACK, DEFAULT-OFF. On the rig/GUI the 8 s keepalive
-            // is mechanism-proven (F290/F291: max ACK-silence gap capped at
-            // exactly 8.0 s vs OFF's 36.7 s) and collision-free — because it
-            // routes through the GUI's listen-before-ACK (app.cpp), so a
-            // mid-burst fire DEFERS. BLOCKER for default-on: the HEADLESS TNC
-            // path (ultra_tnc) has NO listen-before-ACK gating, so default-on
-            // broke UltraTncSimAudio (keepalive TX'd over inbound bursts →
-            // collision → timeout). Fix before flipping: move the channel-clear
-            // gating into the connection/ARQ (universal) rather than the GUI
-            // app layer, so the keepalive is safe on TNC too. Until then:
-            // opt-in on the GUI/rig where the gating exists.
+            // KEEPALIVE ACK, DEFAULT-ON 2026-07-14 (opt-out ULTRA_KEEPALIVE_ACK=0).
+            // 8 s keepalive: rig-proven (F290/F291 max ACK-silence gap capped at
+            // exactly 8.0 s vs OFF's 36.7 s, reproducible, cwfails normal).
+            // UNIVERSAL collision-safety via channel_busy_query_ (below) — the
+            // keepalive checks "is a burst arriving?" itself and skips if busy,
+            // so it no longer depends on the GUI-only listen-before-ACK (which
+            // had blocked default-on: the headless TNC lacked it). Both the GUI
+            // (app.cpp) and the TNC (ultra_tnc.cpp) wire the query from the modem.
             static const bool keepalive_ack_enabled = [] {
                 const char* e = std::getenv("ULTRA_KEEPALIVE_ACK");
-                return e != nullptr && e[0] != '\0' && e[0] != '0';
+                if (!e || e[0] == '\0') return true;         // default-ON
+                return !(e[0] == '0' && e[1] == '\0');       // "0" opts out
             }();
             // Threshold env-tunable (ULTRA_KEEPALIVE_ACK_MS, default 25000).
             // The keepalive routes through listen-before-ACK (defers on channel
@@ -4453,7 +4451,11 @@ void Connection::tick(uint32_t elapsed_ms) {
                 }
                 return 8000u;  // v2 (rig-proven): caps stall at 8 s, no collision
             }();
-            if (keepalive_ack_enabled) {
+            // Emit only when the channel is NOT busy (no inbound burst) — the
+            // universal collision guard. If unwired (tests), fall back to
+            // threshold-only (safe when threshold > max burst airtime).
+            if (keepalive_ack_enabled &&
+                (!channel_busy_query_ || !channel_busy_query_())) {
                 arq_.keepaliveAckIfStalled(keepalive_ack_ms);
             }
 

src/protocol/connection.hpp

@@ -233,6 +233,17 @@ class Connection {
         tx_active_provider_ = std::move(provider);
     }
 
+    // Channel-busy query (keepalive ACK universal gating, 2026-07-14): returns
+    // true when a burst is currently arriving / the channel is busy. The
+    // keepalive checks this BEFORE emitting so it never TX's over an inbound
+    // burst — replacing the GUI-only listen-before-ACK dependency that blocked
+    // default-on (the headless TNC lacked it). Both the GUI and the TNC set it
+    // from the modem (channelBusyForTx || burstAirSamplesRemaining>0). Unwired
+    // (tests) => nullptr => keepalive falls back to threshold-only safety.
+    void setChannelBusyQuery(std::function<bool()> query) {
+        channel_busy_query_ = std::move(query);
+    }
+
     void setTransmitToneBurstAckCallback(TransmitToneBurstAckCallback cb) {
         on_transmit_tone_burst_ack_ = std::move(cb);
     }
@@ -1292,6 +1303,7 @@ class Connection {
     TransmitInfoCallback on_transmit_info_;
     TransmitToneBurstAckCallback on_transmit_tone_burst_ack_;
     std::function<bool()> tx_active_provider_;  // BUG-MC-RETRY-SPURIOUS: see setter
+    std::function<bool()> channel_busy_query_;  // keepalive universal busy gate
     DriveAdvisoryCallback on_drive_advisory_;  // software-ALC sender-side hook
     ArmToneBurstAckMonitorCallback on_arm_tone_burst_ack_monitor_;
     ConnectedCallback on_connected_;

src/protocol/protocol_engine.hpp

@@ -286,6 +286,10 @@ class ProtocolEngine {
         connection_.setTxActiveProvider(std::move(provider));
     }
 
+    void setChannelBusyQuery(std::function<bool()> query) {
+        connection_.setChannelBusyQuery(std::move(query));
+    }
+
     // Half-duplex INTERACTIVE (bidirectional) data path — the TNC / Winlink-B2F
     // case where both stations alternately transmit. Keeps the ISS/IRS turn gate
     // on burst sends so the directions serialize instead of colliding.

tools/ultra_tnc.cpp

@@ -466,6 +466,12 @@ class UltraTNCStation {
         // to a full chirp+LTS anchor so the peer can re-acquire our timing — the
         // fix for the half-duplex B2F stall (BUG-TNC-B2F-001). The yielding peer
         // already arms expectFullOFDMAnchorOnce() via the TURNOVER it sent.
+        // Keepalive ACK universal busy gate (the headless TNC has no
+        // listen-before-ACK, so the keepalive must self-gate on channel-busy).
+        engine_.setChannelBusyQuery([this] {
+            return modem_.channelBusyForTx() ||
+                   modem_.burstAirSamplesRemaining() > 0;
+        });
         engine_.setDataTurnAcquiredCallback([this]() {
             modem_.forceNextFrameFullPreamble();
         });