fix(hl2): a declined auto-gain arm explains itself where the operator is, not only in the log (#5825)

Closes #5817. The shape is the one proposed in that issue's triage,
widened in review to every route an arm request can take.

## What the operator sees today

Tick **Auto** with no stored gain for the current band and the
constructed baseline sits above `kAutoRfGainMaxBaselineDb`.
`setAutoRfGain` declines, and the checkbox **springs back to unticked
with no explanation**.

The wiring already reads `isArmed()` back, and that is correct — it is
what stops the UI reporting a state the radio is not in (#5395). But a
readback can only say *that* the request failed, and only after the
operator's own click. The account of *why* — a well-formed sentence
naming the baseline, the ceiling, and the remedy — went only to a
`qWarning`. And two routes to an arm never pass through that click at
all: the backend's own connect-time restore of a stored "on", and a
bridge `pan autorfgain on`. On both, the checkbox reported the wrong
state and a refusal was silent.

On a fresh install that is the **first** tick of Auto:
`kLnaDefaultGainDb` is 20 dB and the ceiling is 19 dB, so the shipped
default is always refused. A bench whose stored gains sit at −12 never
reproduces it, which is exactly why it went unnoticed here.

## The change

The sentence was already being composed. It is now kept, every outcome
of an arm request is announced on the seam, and one handler turns that
into the checkbox state, a card where the operator is looking, and a
channel a screen reader reads — **and takes it all back off again the
moment the control arms.**

| | |
|---|---|
| `src/core/backends/AutoRfGainControl.h` | `IAutoRfGainControl` gains
`lastArmRefusalReason()`, **defaulted to empty** so no other backend
changes; the contract now requires the backend to emit
`autoRfGainArmSettled` after every outcome |
| `src/core/backends/IRadioBackend.h` | new signal
`autoRfGainArmSettled(bool armed)`: fired after a refusal, an arm and a
disarm; not for a request that changed nothing |
| `src/core/backends/hl2/Hl2Backend.{h,cpp}` | stores the sentence it
already built — `tr()`'d, without the issue citation — **clears it on a
successful arm and on the radio-swap reset**, and emits the settled
signal on every outcome |
| `src/models/RadioModel.{h,cpp}` | relays `autoRfGainArmSettled` to the
GUI, caching nothing |
| `src/gui/MainWindow.{h,cpp}` | `onAutoRfGainArmSettled`: reflects the
outcome on every pan's copy of the checkbox; on a refusal, sets the
description on all of them and raises the card and the spoken
announcement once, on the active pan. The per-pan capability push also
reads a standing reason, for a pan built after the connect-time restore
settled |
| `src/gui/MainWindow_Wiring.cpp` | the click lambda now only commands
and reads back; the settled handler does the explaining |
| `src/gui/SpectrumWidget.{h,cpp}` | `showNoticeCard(detail, id, ms)`: a
transient card that takes the **caller's** id; the three card wrappers
share one private builder |
| `src/gui/SpectrumOverlayMenu.{h,cpp}` |
`setAutoRfGainRefusalDescription()` puts the reason on the Auto
checkbox's **accessible description**; arming, or hiding the control for
a family without the loop, clears it and restores the help tooltip.
`announceAutoRfGainRefusal()` speaks it once via
`QAccessibleAnnouncementEvent` |
| `src/core/AutomationServer.cpp` | `pan autorfgain on\|off` and its
status form now report `armed` and `refusal` alongside `requested` |
| `tests/spectrum_overlay_auto_rf_gain_refusal_test.cpp` | **new**,
registered; the widget half |
| `tests/hl2_gain_split_test.cpp` | the backend half: the reason, its
clears, and the settled signal |

### On the panadapter, not the status bar, and not a dialog

Not a dialog, because #4227 is stacked unclosable message boxes and a
refusal the operator asked for by clicking does not warrant one.

Not the status bar, because `MainWindow_Wiring`'s own `messageChanged`
handler hides `m_statusBarContainer` wholesale on any non-empty message
— so a timed notice there takes the TX indicator, PA temperature and
supply voltage with it for its whole duration, to explain a checkbox.
`MainWindow.cpp` and `MainWindow_Controllers.cpp` both route away from
it citing #4649.

### Its own card id

`showInterlockNotification` pins every card it raises to
`interlock.active` on a latest-wins rule — deliberately, so the radio's
authoritative denial supersedes a local preflight of the same refusal in
place (#3999). A gain refusal is not the same thing: routed through it,
the card would evict a live **Transmit disabled** card and be evicted by
the next one. `showNoticeCard` takes the caller's id, which is the
argument `showTxFilterNotification` already made for taking one of its
own. The refusal's id is `autorfgain.refused`.

### One handler for every route

`RadioModel::autoRfGainArmSettled` →
`MainWindow::onAutoRfGainArmSettled`. Three routes reach an arm outcome
and only one of them is a click:

- **the operator's click** — the signal lands synchronously inside
`setArmed()`; the lambda's readback afterwards is the #5395 guard for a
backend that settled silently;
- **the connect-time restore** in `Hl2Backend`, which settles inside its
link-up handler after it has already emitted `connected()` — so the pans
that would hear the signal may not exist yet, and the per-pan capability
push reads the standing reason onto a late pan's description (no card:
nothing just happened, that pan is catching up);
- **a bridge `pan autorfgain on`**, which arms without going near a
widget.

### And on a channel a screen reader actually reads

The checkbox carries the sentence as its accessible **description**
(what just happened to it) rather than its name (what it is), on every
pan's copy. And it is **spoken once, at the moment it happens**: a
description is read on arrival at a control, and on a refused tick the
operator is already on it, so without the `QAccessibleAnnouncementEvent`
the sentence would sit unread until they left and came back. The
clipping indicator beside the box raises the same event for the same
reason. One announcement, on the active pan, not one per copy.

### The clear lives in the widget, before the early return

`SpectrumOverlayMenu::setAutoRfGainEnabled(true)` clears the
description, and clears it **before** the function's "already there"
early return: on the operator's retry the box is *checked* before the
backend is asked, so when the arm succeeds `isChecked() == on` and the
early return fires. A clear written after that return never runs on the
one path it exists for.

The clear is a **restore, not a blanking**: the tooltip goes back to the
standing help text, hoisted into `autoRfGainHelpToolTip()` so the
constructor and the clear share one literal.

The backend clears its own copy too — on a successful arm, and on the
radio-swap reset in `applyRestoredState()`, so radio B's control never
reports a sentence composed about radio A's baseline.

### The sentence is no longer a log line

It is shown on the panadapter and read out by a screen reader, so it is
`tr()`'d, and the `#5354` citation moved to the `qWarning` — provenance
for us, noise to an operator.

## No constant moves

`kAutoRfGainMaxBaselineDb`, `kLnaDefaultGainDb` and the AD9866 fold
question stay exactly where #5752 left them. Each of the three candidate
"real" fixes settles the fold question by the back door, and #5752
merged explicitly **declining** to settle it. A visible refusal is the
one change that does not take a position.

## Tests

Two socket-free targets, both registered.

**`hl2_gain_split_test`** — the backend half. The sentence names both
numbers the operator needs and cites no issue number; a backend never
asked has no reason to give; a successful arm clears it (asserted, not
skipped); a radio swap clears it; and `autoRfGainArmSettled` fires on a
refusal, an arm and a disarm, and not on a no-op.

**`spectrum_overlay_auto_rf_gain_refusal_test`** — the widget half,
offscreen, a plain `QWidget` parent. Walks refuse → retry → arm and
asserts the description is *gone* afterwards and the help tooltip is
*back*, with the help text captured from the widget rather than retyped;
and that hiding the control for a family without the loop clears it.

Each guard has been broken on purpose and the assertion that catches it
named; the review threads carry the runs.

## What this does not cover

- **No hardware.** Socket-free throughout; nothing keyed. That the card
renders on a real refusal follows from the wiring and has not been
watched on screen — the demo `SimBackend` returns no
`IAutoRfGainControl`.
- **`showNoticeCard` and `onAutoRfGainArmSettled` have no test of their
own.** The overlay machinery underneath is covered by
`panadapter_message_overlay_test`; `MainWindow` is not cheaply
instantiable.
- **Whether the pans exist by the time the connect-time restore
settles** is not established; the capability-push catch-up is there for
the case where they do not.
- **The refusal itself is unchanged.** Whether 19 dB is the right
ceiling, or 20 the right default, is the fold question and stays open.
- **#5828** (an untick after a refusal is never recorded) is
pre-existing, filed with a repro, and deliberately not folded in here.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Jeremy [KK7GWY] <kk7gwy@aethersdr.com>

Author: 3 people

src/core/AutomationServer.cpp

@@ -11486,10 +11486,16 @@ QJsonObject AutomationServer::doPan(const QString& action, const QString& arg)
         }
         const QString v = raw.toLower();
         if (v.isEmpty()) {
-            return QJsonObject{{QStringLiteral("ok"), true},
+            auto* status = radio->autoRfGain();
+            QJsonObject report{{QStringLiteral("ok"), true},
                                {QStringLiteral("pan"), QStringLiteral("autorfgain")},
-                               {QStringLiteral("available"), radio->autoRfGain() != nullptr},
+                               {QStringLiteral("available"), status != nullptr},
                                {QStringLiteral("requested"), false}};
+            if (status) {
+                report.insert(QStringLiteral("armed"), status->isArmed());
+                report.insert(QStringLiteral("refusal"), status->lastArmRefusalReason());
+            }
+            return report;
         }
         const bool on = (v == QLatin1String("on") || v == QLatin1String("true")
                          || v == QLatin1String("1"));
@@ -11505,13 +11511,16 @@ QJsonObject AutomationServer::doPan(const QString& action, const QString& arg)
                 "pan autorfgain: this radio has no automatic RF gain control"));
         }
         ag->setArmed(on);
-        // DELIBERATELY NOT AN ECHO OF THE ARMED STATE. The backend may decline
-        // to arm and log why; reporting "requested" rather than "on" keeps this
-        // verb honest about the difference. Read `health` for what actually
-        // happened -- that is the row that comes from the backend.
+        // `requested` is what was asked and `armed` is what the backend did;
+        // they differ when it declined, and `refusal` then carries the same
+        // sentence the GUI shows (#5817). The verb used to report only the
+        // request, so a headless caller had to scrape the log to learn the
+        // arm never took.
         return QJsonObject{{QStringLiteral("ok"), true},
                            {QStringLiteral("pan"), QStringLiteral("autorfgain")},
-                           {QStringLiteral("requested"), on}};
+                           {QStringLiteral("requested"), on},
+                           {QStringLiteral("armed"), ag->isArmed()},
+                           {QStringLiteral("refusal"), ag->lastArmRefusalReason()}};
     }
 
     if (action == QLatin1String("float") || action == QLatin1String("dock")) {

src/core/backends/AutoRfGainControl.h

@@ -56,9 +56,29 @@ class IAutoRfGainControl {
     // A backend may DECLINE to arm — the HL2 refuses above a baseline where its
     // gain axis is not trustworthy — so a caller must read `isArmed()` back
     // rather than assuming the request took.
+    //
+    // AND THE BACKEND MUST EMIT IRadioBackend::autoRfGainArmSettled after every
+    // outcome, refusal included. A reader that polls isArmed() only after its
+    // own click never learns about an arm settled elsewhere -- the backend's
+    // own connect-time restore, a bridge verb -- and reports a control as off
+    // while it holds the operator's gain down (#5817).
     virtual void setArmed(bool on) = 0;
     [[nodiscard]] virtual bool isArmed() const = 0;
 
+    // WHY IT DECLINED, in a sentence meant for the operator rather than a log.
+    //
+    // Reading `isArmed()` back tells a caller THAT the request did not take.
+    // It cannot tell them why, and without the why the operator sees a checkbox
+    // spring back to unticked with no explanation -- which on the HL2 is what
+    // every fresh install does on its first tick of Auto, because a stored gain
+    // is absent and the constructed baseline sits above the ceiling that gates
+    // arming (#5817).
+    //
+    // Empty when the last attempt succeeded, or when a backend has no reason to
+    // give. A caller shows it only after a readback has already shown the
+    // request failed; it is not a status line.
+    [[nodiscard]] virtual QString lastArmRefusalReason() const { return {}; }
+
     // How far below the operator's own gain the control may go, in dB. The
     // second of exactly two numbers the operator owns; the first is the switch.
     // Everything else about such a loop is a decision they have no evidence to

src/core/backends/IRadioBackend.h

@@ -1130,6 +1130,16 @@ class IRadioBackend : public QObject {
     // behaves strangely. See FrontEndOverload.h.
     void frontEndOverloadChanged(const AetherSDR::FrontEndOverload& state);
 
+    // AN ARM REQUEST ON autoRfGainControl() HAS SETTLED: `armed` is what the
+    // control is now doing. Emitted after EVERY outcome of setArmed() --
+    // refused (armed stays false; lastArmRefusalReason() says why), armed, and
+    // disarmed -- and not for a request that changed nothing. This is how a
+    // view learns about an arm it did not ask for: the connect-time restore
+    // inside the backend and a bridge `pan autorfgain on` both settle without
+    // passing through any GUI click, and a checkbox that only read isArmed()
+    // back after its own click reported the wrong state on both (#5817).
+    void autoRfGainArmSettled(bool armed);
+
     // Normalized transmit-status delta (aetherd RFC 2.3 — TransmitModel
     // touchpoint). Typed + compiler-checked; the backend populates only the
     // fields the wire reported (across the transmit / interlock / ATU / APD /

src/core/backends/hl2/Hl2Backend.cpp

@@ -6458,6 +6458,11 @@ void Hl2Backend::applyRestoredState(const RestoredRadioState& state)
     // A radio swap ends the session, and an automatic control armed about radio
     // A's antenna has nothing to say about radio B's.
     m_autoRfGainEnabled = false;
+    // Nor does a refusal composed about radio A's baseline: the interface
+    // promises an empty reason from a backend that has not been asked, and
+    // radio B has not been. Left standing, any reader other than the toggle
+    // lambda would surface radio A's number as radio B's.
+    m_autoRfGainRefusal.clear();
     m_autoGainState = AetherSDR::hl2::AutoGainState{};
     m_autoGainConfig = AetherSDR::hl2::AutoGainConfig{};
     m_autoGainMode = QStringLiteral("ramp");
@@ -7006,16 +7011,38 @@ void Hl2Backend::setAutoRfGain(bool on)
             // so a radio that declined to arm keeps the operator's on
             // recorded"; without this line nothing had recorded it.
             m_autoRfGainWanted = true;
-            qWarning().noquote()
-                << QStringLiteral(
-                       "Hl2Backend: auto RF gain declined — the RF Gain baseline is "
-                       "%1 dB and this radio's gain axis is not trusted above %2 dB "
-                       "(#5354: +48 dB measures like +18 dB). Lower RF Gain to %2 dB "
-                       "or below and try again. Your setting has not been changed.")
+            // COMPOSED ONCE AND KEPT, because the operator needs it more than
+            // the log does. Reading isArmed() back tells the GUI THAT this
+            // declined; only this sentence says why, and it already names the
+            // baseline, the ceiling and the remedy. Storing it is what lets the
+            // checkbox explain itself instead of springing back in silence
+            // (#5817).
+            //
+            // tr(), AND WITHOUT THE ISSUE NUMBER, because this sentence stopped
+            // being a log line the moment it was kept: it is shown on the
+            // panadapter and read out by a screen reader. "#5354" is provenance
+            // for us and noise to an operator, so it stays on the qWarning --
+            // which is where the next person debugging this actually looks --
+            // and the operator gets the baseline, the ceiling and the remedy.
+            m_autoRfGainRefusal = tr(
+                       "Auto RF gain declined — the RF Gain baseline is "
+                       "%1 dB and this radio's gain axis is not trusted above "
+                       "%2 dB. Lower RF Gain to %2 dB or below and try again. "
+                       "Your setting has not been changed.")
                        .arg(m_lnaGainDb)
                        .arg(kAutoRfGainMaxBaselineDb);
+            qWarning().noquote()
+                << QStringLiteral("Hl2Backend: ") + m_autoRfGainRefusal
+                     + QStringLiteral(" (#5354: +48 dB measures like +18 dB)");
+            // SETTLED AS NOT ARMED, and said so. A refusal that only the
+            // caller's own readback could discover was invisible on the two
+            // routes that have no readback: the restore below and the bridge.
+            emit autoRfGainArmSettled(false);
             return;
         }
+        // CLEARED ON SUCCESS. A reason that outlived the refusal it describes
+        // would be shown against a later, unrelated failure.
+        m_autoRfGainRefusal.clear();
         m_autoGainState = AetherSDR::hl2::AutoGainState{};
         m_autoGainBandKey = m_currentBandKey;
         m_autoGainBaselineDb = m_lnaGainDb;
@@ -7031,6 +7058,7 @@ void Hl2Backend::setAutoRfGain(bool on)
         applyBandscopeForAutoGain();
         qCInfo(lcHl2) << "HL2 auto RF gain: ARMED at baseline" << m_lnaGainDb
                       << "dB, floor" << m_autoGainConfig.maxOffsetDb << "dB below";
+        emit autoRfGainArmSettled(true);
     } else {
         m_autoRfGainEnabled = false;
         // The operator turning it OFF is a preference, and is persisted as one.
@@ -7046,6 +7074,7 @@ void Hl2Backend::setAutoRfGain(bool on)
         setLnaAutoOffsetDb(0);
         qCInfo(lcHl2) << "HL2 auto RF gain: disarmed, baseline" << m_lnaGainDb
                       << "dB restored";
+        emit autoRfGainArmSettled(false);
     }
 }
 

src/core/backends/hl2/Hl2Backend.h

@@ -250,6 +250,10 @@ class Hl2Backend : public IRadioBackend, public IAutoRfGainControl {
     IAutoRfGainControl* autoRfGainControl() override { return this; }
     void setArmed(bool on) override { setAutoRfGain(on); }
     [[nodiscard]] bool isArmed() const override { return m_autoRfGainEnabled; }
+    [[nodiscard]] QString lastArmRefusalReason() const override
+    {
+        return m_autoRfGainRefusal;
+    }
     void setFloorDb(int floorDb) override { setAutoRfGainFloorDb(floorDb); }
     [[nodiscard]] int floorDb() const override { return autoRfGainFloorDb(); }
     [[nodiscard]] int maxFloorDb() const override { return kAutoRfGainFloorMaxDb; }
@@ -1037,6 +1041,10 @@ class Hl2Backend : public IRadioBackend, public IAutoRfGainControl {
     // the control stays off, and the next connect from a baseline it trusts
     // honours the operator without them having to ask twice.
     bool m_autoRfGainWanted = false;
+    // Why the last arm attempt was declined, empty when it was not. See
+    // setAutoRfGain: composed where the refusal happens, cleared on a
+    // successful arm so it can never describe a different failure.
+    QString m_autoRfGainRefusal;
     AetherSDR::hl2::AutoGainState m_autoGainState;
     AetherSDR::hl2::AutoGainConfig m_autoGainConfig;
 

src/gui/MainWindow.cpp

@@ -1429,6 +1429,12 @@ MainWindow::MainWindow(QWidget* parent)
     });
     connect(&m_radioModel, &RadioModel::interlockNotificationRequested,
             this, &MainWindow::showPanadapterInterlockNotification);
+    // An automatic-gain arm request settled -- from the operator's click, the
+    // backend's own connect-time restore, or a bridge verb. One handler for all
+    // three, because the checkbox reading isArmed() back after its OWN click
+    // covered exactly one of them (#5817).
+    connect(&m_radioModel, &RadioModel::autoRfGainArmSettled,
+            this, &MainWindow::onAutoRfGainArmSettled);
     // Goes on the panadapter as a transient card, NOT the status bar (#4649).
     // A QStatusBar temporary message hides every permanent widget for its whole
     // duration -- the TX indicator, PA temperature and supply voltage among
@@ -8007,8 +8013,18 @@ void MainWindow::applyRadioSideDspToPanDisplay(SpectrumWidget* sw) const
         // did not reflect that would report a control as off while it was
         // holding the operator's gain down.
         auto* autoGain = m_radioModel.autoRfGain();
+        const bool armed = autoGain && autoGain->isArmed();
         menu->setAutoRfGainAvailable(autoGain != nullptr);
-        menu->setAutoRfGainEnabled(autoGain && autoGain->isArmed());
+        menu->setAutoRfGainEnabled(armed);
+        // AND IF THE LAST REQUEST WAS REFUSED BEFORE THIS PAN EXISTED. The
+        // backend's connect-time restore settles inside its link-up handler,
+        // after it has emitted connected() and before the pans that would have
+        // heard autoRfGainArmSettled are built. The reason is still on the
+        // control, and the description is the only channel a late pan has for
+        // it. No card: nothing just happened, this pan is only catching up.
+        if (autoGain && !armed) {
+            menu->setAutoRfGainRefusalDescription(autoGain->lastArmRefusalReason());
+        }
     }
     // A MASK, not a rewrite: the operator's stored HW preference survives a
     // session on a radio that has no hardware black level, and comes back by

src/gui/MainWindow.h

@@ -763,6 +763,9 @@ private slots:
     void showPanadapterInterlockNotification(const QString& message,
                                              const QString& key = QString(),
                                              const QString& panId = QString());
+    // RadioModel::autoRfGainArmSettled: reflect the outcome on every pan's copy
+    // of the Auto checkbox, and explain a refusal once, on the active pan.
+    void onAutoRfGainArmSettled(bool armed);
     void setActivePanApplet(PanadapterApplet* applet);
     void routeCwDecoderOutput();
     // Show a decoder panel on exactly one applet — the current decoder target —

src/gui/MainWindow_Wiring.cpp

@@ -5481,14 +5481,21 @@ void MainWindow::wirePanadapter(PanadapterApplet* applet)
             this, [this, sw](bool on) {
         auto* autoGain = m_radioModel.autoRfGain();
         if (autoGain) {
+            // The backend settles the request -- armed, or refused with a
+            // reason -- and says so through RadioModel::autoRfGainArmSettled.
+            // onAutoRfGainArmSettled turns that into the checkbox state, the
+            // card and the accessible description, and it is the one place all
+            // three routes to an arm meet: this click, the backend's own
+            // connect-time restore, and a bridge verb (#5817).
             autoGain->setArmed(on);
         }
-        // READ BACK WHAT ACTUALLY HAPPENED. The backend may DECLINE to arm --
-        // the HL2 refuses from a gain baseline inside the register region where
-        // #5354 measured +48 dB reading identically to +18 dB -- and a checkbox
-        // that stayed ticked over a control that is not running would be the
-        // #5395 defect exactly: a UI reporting one state while the radio is in
-        // another. So ask the control rather than assuming the request took.
+        // READ BACK WHAT ACTUALLY HAPPENED, regardless. The backend may DECLINE
+        // to arm -- the HL2 refuses from a gain baseline inside the register
+        // region where #5354 measured +48 dB reading identically to +18 dB --
+        // and a checkbox that stayed ticked over a control that is not running
+        // would be the #5395 defect exactly: a UI reporting one state while the
+        // radio is in another. The settled signal normally lands first, inside
+        // setArmed(); this is the guard for a backend that settled silently.
         if (auto* m = sw->overlayMenu()) {
             m->setAutoRfGainEnabled(autoGain && autoGain->isArmed());
         }
@@ -5533,6 +5540,70 @@ void MainWindow::wirePanadapter(PanadapterApplet* applet)
     refreshKiwiSdrWaterfallAvailability();
 }
 
+// AN ARM REQUEST SETTLED, from whichever route asked. Reflect it on every pan's
+// copy of the control, and if it was a refusal, say why.
+//
+// ONE HANDLER FOR ALL ROUTES. The Auto checkbox used to learn the outcome only
+// by reading isArmed() back after its own click. That covers the click and
+// nothing else: the HL2 arms (or refuses) from its stored preference inside its
+// own link-up handler, after it has already emitted connected(), and a bridge
+// `pan autorfgain on` arms without going near a widget. On both, the checkbox
+// reported the wrong state and a refusal was silent -- the #5817 springback,
+// just not on a click (#5395 is the same defect seen from the other side).
+//
+// WHAT GOES WHERE. The armed state and the refusal DESCRIPTION go on every
+// pan's checkbox, because the control is radio-wide and each pan carries a
+// copy: the description is state, and a copy left saying "declined" over a
+// running loop would be read out as such. setAutoRfGainEnabled(true) is what
+// clears a standing description. The card and the spoken announcement go
+// ONCE, on the active pan, where the operator is looking.
+//
+// ON THE PANADAPTER, NOT THE STATUS BAR, and not a dialog either. Not a dialog
+// because #4227 is stacked unclosable message boxes, and a refusal the
+// operator asked for by clicking does not warrant one. Not the status bar
+// because of #4649: any non-empty temporary message hides m_statusBarContainer
+// wholesale for its whole duration, taking the TX indicator, PA temperature
+// and supply voltage with it -- MainWindow.cpp and MainWindow_Controllers.cpp
+// both route away from it for the same reason. The card takes its OWN id
+// rather than riding on the interlock's "interlock.active" latest-wins: a
+// gain refusal must not evict a live "Transmit disabled" card, nor be evicted
+// by one.
+void MainWindow::onAutoRfGainArmSettled(bool armed)
+{
+    if (!m_panStack) {
+        return;
+    }
+    auto* autoGain = m_radioModel.autoRfGain();
+    const QString why = (!armed && autoGain) ? autoGain->lastArmRefusalReason()
+                                             : QString();
+    const QStringList panIds = m_panStack->panIds();
+    for (const QString& panId : panIds) {
+        SpectrumWidget* sw = m_panStack->spectrum(panId);
+        auto* m = sw ? sw->overlayMenu() : nullptr;
+        if (!m) {
+            continue;
+        }
+        m->setAutoRfGainEnabled(armed);
+        if (!why.isEmpty()) {
+            m->setAutoRfGainRefusalDescription(why);
+        }
+    }
+    if (why.isEmpty()) {
+        return;
+    }
+    SpectrumWidget* where = m_panStack->activeSpectrum();
+    if (!where && !panIds.isEmpty()) {
+        where = m_panStack->spectrum(panIds.first());
+    }
+    if (!where) {
+        return;
+    }
+    where->showNoticeCard(why, QStringLiteral("autorfgain.refused"), 10000);
+    if (auto* m = where->overlayMenu()) {
+        m->announceAutoRfGainRefusal(why);
+    }
+}
+
 MainWindow::TuneCenteringResult MainWindow::revealFrequencyIfNeeded(
     SliceModel* slice, double mhz, TuneIntent intent, const char* source,
     double leftFlagEdgeOffsetMhz, double rightFlagEdgeOffsetMhz)