[on8st]

Closes #5943. Follows up #5354, #5535, #5652.

Why

kAutoRfGainMaxBaselineDb = 19 refused to arm auto RF gain above +19 dB. It rested on #5354's "+48 dB measures like +18 dB", which was measured on one HL2 with a hardware fault: a bad joint at AD9866 pin 1, the FPGA→AD9866 Tx[5] line, which carries RX gain bit 5 while receiving. The bit was held high, so every commanded −12…+19 dB ran 32 dB hotter than displayed. The joint was reflowed on 2026-09-27; corrections are posted on #5354, #5535 and #5943.

The gateware agrees with the native range: with bit 6 set, ad9866.v (883a338, unchanged on master) takes all six gain bits as given (rx_gain <= cmd_data[6] ? cmd_data[5:0] : …), so codes 0–60 are −12…+48 dB with no five-bit fold.

On the repaired radio:

• Gain ladder: codes 0–60 rise monotonically (−97.4 → −42.2 dBFS on an 80 m EFHW, ~0.9 dB/code). Code 32 over code 0 went from 0.0 dB to +33.6 dB, and a repeat run matches to 0.10 dB.
• Clip point: on a dummy load there is no ADC-overload observation anywhere in −12…+48 dB. On live antennas the first clip moves with band conditions (+28…+38 dB across runs on an 80 m fan dipole and EFHW), so the +20 dB default sits inside the clean range.

What changes

• kAutoRfGainMaxBaselineDb becomes hl2::kLnaGainMaxDb (+48), so every baseline the slider offers can arm.
• kAutoRfGainFloorMaxDb becomes the full native span, kLnaGainMaxDb − kLnaGainMinDb (60), so the operator's floor can reach the register floor from any armable baseline. The default floor (26) is unchanged.
• The refusal branch stays as defensive code. It cannot be reached through the public API, because every writer of the baseline clamps to −12…+48. Its operator text says "above this radio's maximum", and the log line no longer cites HL2: drive RF/LNA gain from the ADC clip counter (roadmap item 14) — front end clips at any usable gain on a live antenna #5354.
• Auto-gain stays off by default; default-on for profiles that never expressed a wish is RFC [RFC] Automatic RF-gain protection for the Hermes-Lite 2 #5535's separate decision.
• The RF Gain slider describes the range the radio published (HL2 publishes a -12..+48 dB RF gain slider while its own auto-gain declines to arm above +19, and asking for more gain can deliver less #5943's second half; maintainer decision to fold it in here). The unarmed slider hardcoded Flex's "−8 to +32 dB in 8 dB steps" on both the accessible description and the tooltip, so an HL2 (−12…+48, 1 dB) was described as a Flex to screen readers and sighted operators alike. SpectrumOverlayMenu::applyRfGainRangeText() now writes both channels from the slider's published range, step and unit, and setRfGainRange uses it. It also fixes a pre-existing overwrite: a range push while Auto was armed replaced the slider's read-only tooltip with the range text.
• Comments in Hl2Backend.{h,cpp}, Hl2DbReference.h, MainWindow_Wiring.cpp, SpectrumOverlayMenu.cpp and docs/HERMES.md (§17 and roadmap row 12) state that the fold was one unit's hardware defect.

Behaviour change for existing installs

#5828 made the operator's ask survive a refusal. Anyone who ticked Auto RF gain on the stock +20 dB baseline (always refused until now) has autoEnabled: true saved with the loop never having run. From the first connect after this change, that profile arms. That is the safe direction (attenuate only, on clip evidence, with the AtFloor warning) and it is what those operators asked for. Profiles that never expressed a wish stay off.

Tests

• hl2_gain_split_test: kAutoRfGainMaxBaselineDb == kLnaGainMaxDb; arming succeeds from +19, +20 (the default) and +48; +49 clamps to +48 without moving the baseline or the wire; the deepest operator floor reaches the register floor from +48; armed/settled notifications are counted.
• hl2_gain_restore_test: arming from the shipped +20 succeeds and the "off" persists; a restored autoEnabled: true switched off before the connect-time arm clears the profile (HL2: switching auto RF gain off after a refused arm is never recorded, and the next connect arms it again #5828).
• spectrum_overlay_auto_rf_gain_refusal_test: updated to the new refusal sentence; the slider's description and tooltip name the published −12…+48 range when unarmed, keep the read-only reason across a range push while armed, and return to the range on disarm.
• The refusal path itself is no longer exercised: no public input reaches it.

🤖 Generated with Claude Code

[aethersdr-agent]

Issue fit

Yes, for the half it claims. #5943 asks that the published −12…+48 dB slider range and the range the backend is willing to operate in either agree or be explained; its author's correction comment (2026-09-27T11:40:37Z) narrows the ask to "the fix is to raise that baseline, not to narrow the slider", and that is exactly what kAutoRfGainMaxBaselineDb = hl2::kLnaGainMaxDb does. The evidence chain checks out as far as it can from here: the correction comments on both #5354 and #5943 attribute the fold to a bad joint on AD9866 pin 1 (Tx[5], RX gain bit 5) and report code 32 over code 0 measuring +33.6 dB after the reflow, against ~+32 expected. That agrees with ad9866.v at 883a338 passing all six gain bits in native format, which is the HL2's Principle I authority — so this change moves the client toward the protocol reference rather than away from it, and the asymmetry with #5752 (which refused to narrow the range on one board's evidence) resolves in the right direction.

Two things the PR does not address, both noted below: #5943's second half (the hardcoded −8 to +32 dB (8 dB steps) tooltip/accessible description the triage identified) is untouched, and the re-sweep the author said would precede this PR has not happened, so the two floor constants remain derived from labels the PR itself now marks 32 dB low.

Scope

File(s)	What changes	Claimed by title/body?	Verdict
src/core/backends/hl2/Hl2Backend.h	kAutoRfGainMaxBaselineDb 19 → hl2::kLnaGainMaxDb; rationale comments	Yes	In scope — the only behavioural change in the PR
src/core/backends/hl2/Hl2Backend.cpp	Comments; refusal tr() text reworded; #5354 provenance dropped from the qWarning	Yes	In scope
Hl2AutoGainPolicy.h, Hl2DbReference.h, Hl2GainSplit.h	Comment-only (verified: no +/- outside comment blocks)	Yes	In scope
src/gui/MainWindow_Wiring.cpp, src/gui/SpectrumOverlayMenu.cpp	Comment-only	Yes	In scope
docs/HERMES.md	§17 fold note + roadmap row 12 corrected	Yes	In scope
tests/hl2_gain_split_test.cpp, hl2_gain_restore_test.cpp, hl2_dbref_test.cpp, spectrum_overlay_auto_rf_gain_refusal_test.cpp	Refusal legs replaced with arm legs	Yes	In scope, but see nits 1–2

Everything in the diff is explained by the issue. No new public/protocol surface, no settings key, no CHANGELOG.md entry (correct), no socket-owning test added or modified (checked all four test sources for QTcpServer/QUdpSocket/bind/listen/connectToHost — none). One user-visible behaviour change is disclosed in the comments (the first tick of Auto on a fresh install now arms), and one is not — finding 2.

Blockers

None. The change itself is small, correctly wired, and the "this is now a dead guard" claim holds (see What I tried to break).

Findings

1. kAutoRfGainFloorMaxDb = 31 no longer spans the armable range — src/core/backends/hl2/Hl2Backend.h:220, unchanged by this PR. 31 is exactly 19 − (−12): with the old +19 arming ceiling, an operator's floor knob at maximum reached the register floor from any armable baseline. With the ceiling at +48, ceiling = min(cfg.maxOffsetDb, obs.availableOffsetDb) (Hl2AutoGainPolicy.h:763-765, availableOffsetDb = m_lnaGainDb − kLnaGainMinDb) caps the dig at 31 dB from a +48 baseline — down to +17 dB, with 29 dB of native range the loop cannot be configured to use. Reasoned from code, not run. Inline comment has the detail. Non-blocking, but it is the one arithmetic relationship the change silently breaks, and the constant is the only one in this cluster with no comment recording its derivation.

2. A persisted autoEnabled: true from a previously refused arm now activates the loop on the next connect, undisclosed. The invariant #5828 established — "the asking survives the refusal" — means every operator who ticked Auto on a stock +20 dB baseline (which, per the v26.9.4 notes quoted in #5943, was always refused) has autoEnabled: true on disk with the loop having never run. After this PR the constructor path at Hl2Backend.cpp:590 arms them on first connect after upgrade. The direction is the safe one (attenuate-only, on clip evidence, with the AtFloor warning), and the PR is careful to say default-on is not decided here — but this is default-on for an existing population, and the body/comments don't mention it. Worth one sentence in the PR body and, arguably, docs/HERMES.md.

Nits (non-blocking)

• The refusal machinery is now retained-but-unreachable, and its tests were deleted. Hl2Backend.cpp:8225-8270 (the guard, the tr() sentence, the settled-as-not-armed emit) plus applyRestoredState's clear-on-radio-swap now have zero coverage: the deleted legs included the "names both numbers", "cites no issue number at the operator" and "a radio swap clears a reason composed about the previous radio" assertions. hl2_gain_split_test.cpp discloses this honestly, which is why it's a nit and not a finding — but if #5943's option 2 (mark the untrusted region) is ever taken, that machinery comes back live and untested.
• hl2_gain_split_test.cpp:317 restates the definition. check(kAutoRfGainMaxBaselineDb == kLnaGainMaxDb) cannot fail against an implementation that defines the first as the second; hl2_gain_restore_test.cpp already static_asserts the same identity. Useful as a tripwire against re-hardcoding 19, not as behavioural coverage.
• #5943's other half is untouched. SpectrumOverlayMenu.cpp:2953 and :2960 still hardcode "RF gain, minus 8 to plus 32 dB in 8 dB steps." / "RF Gain: −8 to +32 dB (8 dB steps)" in the unarmed branches, overwriting the range-derived text setRfGainRange wrote. That is the non-UX defect the #5943 triage said "lands either way", and the accessible description is the worse half. If this PR is used to close #5943, please split that into its own issue rather than closing over it.
• The floor constants are still the faulty radio's numbers. The 26 dB default (AutoGainConfig::maxOffsetDb) and the 24 in probingReleaseConfig() are both now annotated "to be re-derived from a sweep on a healthy radio"; the author's own correction on #5354 said the follow-up PR would come after the re-sweep. Shipping the ceiling first is defensible (the ceiling now equals the datasheet range, the floor is an operator-owned number), but the sweep stays outstanding and should probably be a tracking issue rather than a comment.
• docs/HERMES.md:1533 (roadmap row 12) now reads both ways in one sentence — it keeps #5752's "remains unresolved against the native bit-6-selected RTL path" and then says the observation was a hardware defect. Worth one clause reconciling them.

What I tried to break

• "Every writer of m_lnaGainDb clamps to the native range", the premise that makes the guard dead. It holds. setPanRfGain qBounds (Hl2Backend.cpp:4195), the band change qBounds (:8616), the restore parses lnaDbByBand through qBound (:7821), the reset writes kLnaDefaultGainDb (:7598), and connectLna clamps both the param and the stored branch (Hl2BandMemoryPolicy.h:55-78). The one unclamped write I found — m_lnaGainDb = params["lnaGainDb"].toInt() at :2662 — is overwritten by the clamped seed at :2692 under exactly the condition that made it fire (paramPresent), so a connect param of 500 cannot leak a >48 baseline into setAutoRfGain. The "DEFENSIVE" comment is accurate.
• A stale copy of +19 somewhere the diff didn't reach. Grepped src/, tests/, docs/ for 5354, issues/177, +19, kAutoRfGainMaxBaselineDb, "fold", "wrap", "not trusted": every remaining hit is either updated by this PR or historical narration. No GUI or automation surface reads the constant, so no operator-facing copy went stale (unlike the pre-existing hardcoded tooltip above).
• Build reachability of the new constant. hl2::kLnaGainMaxDb comes from Hl2BandMemoryPolicy.h, included at Hl2Backend.h:16 — no forward-declaration or include-order trap. CI agrees: 5/5 green on be44640 (build, check-macos, check-windows, Static checks, Sanitizer configures). Note that per ci.yml those ctest calls are -R-filtered, so green is not "the suite passes"; I could not run the four modified tests.
• Whether the loop can now reach somewhere it couldn't. The axis is still attenuation-only (Hl2GainSplit.h), so raising the arming ceiling cannot make the radio louder than the operator asked — arming at +48 still only digs downward. What it can now do is stop short of the register floor, which is finding 1.
• Whether the "No amount of LNA will fix this" warning became a lie. It can fire with native range remaining — but I checked, and that was already true before this PR (default floor 26 from a +20 baseline leaves 6 dB unused), so the overclaim is pre-existing and not something this PR introduced. Only the size of the gap grows.
• The evidence itself. I read #5354 and #5943 end to end, including the author's two correction comments. The repair evidence is one unit, one operator, self-reported, with no second board — the same evidentiary shape #5752 declined to act on. I could not verify it independently and am not treating it as reproduced; what makes it acceptable here is that the conclusion lands on the documented native range rather than away from it.

All findings above are reasoned from the code in /tmp/aetherclaude/pr-5976; nothing was built, run, or exercised against hardware.

Recommendation

Approve with nits — one maintainer call attached. The constant change is correct, the dead-guard argument survives an attempt to break it, and the comment and doc corrections are thorough and honest about what is still unmeasured. Before merge I'd ask for two sentences in the PR body on finding 2 (existing profiles with a refused-arm wish will now arm on upgrade), and a decision on finding 1 — either raise kAutoRfGainFloorMaxDb to kLnaGainMaxDb − kLnaGainMinDb (60) so the operator's floor can still reach the register floor, or add a comment recording that 31 is now a deliberate cap rather than the range span. Whether to close #5943 against this PR while its hardcoded-tooltip half is still live is the maintainer's call.

Thanks for filing the correction against your own two issues rather than quietly editing the constant — the provenance trail in these comments is what made this reviewable at all.

---

_{🤖 aethersdr-agent · cost: $12.8445 · model: claude-opus-5}

[on8st]

A correction to this PR's body, and the floor re-measurement that the body said was still owed.

Correction first. The body says: "With a terminated input the flag appears from +31…+35 dB." I could not reproduce that. On 2026-10-01 (02:39–03:27 local), on the same repaired HL2, a dummy load gave zero ADC-overload observations at every point of a −12…+48 dB sweep (step 4 dB, 6 s per point), on three dials. It also gave zero in 90 s with the loop armed at +48. I do not know why the 27 September run saw the flag. I have marked that sentence in the body as not reproduced. The code in this PR does not depend on it.

The antenna figures also moved. The body gives the first clip at +34 / +37 / +38 dB on a fan dipole. That night it came 2 to 6 dB earlier:

band, antenna	last clean gain	first clip
40 m, fan dipole	+28 dB	+32 dB
30 m, fan dipole	+24 dB	+28 dB
80 m, EFHW	+28 dB	+32 dB

Earlier the same evening (22:20) I needed about +8 dB on 40 m for a clean ADC. So the clip point moves by 20 dB or more over an evening on this station. One sweep does not define it.

The floor, re-measured (receive only, this PR's head ad95680c, fresh profile). A fresh connect installs the ramp law with a floor of 26.

• From a +48 baseline, the loop settled at an offset of 24–26 dB on all three bands. That is at the floor or within 2 dB of it. It reached clean that night. With the 22:20 conditions it would not have: +48 − 26 = +22, and clean needed about +8.
• From the +20 default, the loop never went deeper than 3 dB. A floor of 26 from +20 would allow gains below the point where the antenna noise is still 6 dB above the terminated floor. That point was +8 dB on 40 m and +12 dB on 30 m. On those two bands the floor allows more attenuation than is harmless. This was not exercised in the run.
• Arming at +20, attenuating within 0.24–0.49 s of clip evidence, not hunting, and "off stays off" across a restart all passed on the three bands (23 checks). Of the 22 attacks, none came without clip evidence.

So the 26/24 figures are not wrong for a +48 baseline on a quiet night, and they are too deep for the +20 default on two of the three bands. Because the floor is an offset from the baseline, a stale high baseline stops short of clean on a busy evening. I am not changing the floor in this PR: #5535's ruling keeps maxOffsetDb as it is. These are the measurements to decide it on.

73, ON8ST

[on8st]

A correction to my comment above: I undercounted.

I wrote that a floor of 26 dB from the +20 default is too deep "on two of the three bands". It is all three. From +20, the attenuation that still leaves the antenna noise 6 dB above the terminated floor was 12 dB on 40 m, 8 dB on 30 m and 24 dB on 80 m. The ramp floor of 26 exceeds all three, 80 m by 2 dB. A floor of 24 would exceed it on 40 m and 30 m only, and that is where my "two" came from. A fresh connect runs ramp, so 26 is the figure that applies.

Nothing else in that comment changes. The loop was not driven to the floor from +20 in the run, so this is still arithmetic on the measured table, not an observed failure.

73, ON8ST

[on8st]

One more correction, and this one is a defect in our own merged code.

In my comment above I wrote that "a fresh connect installs the ramp law with a floor of 26". That is true, and I did not say what it means: it is not the law #5535 approved, and the cause is a line in our own #5652.

• Hl2Backend's constructor installs the bandscope law (m_autoGainConfig = bandscopeReleaseConfig(…), Hl2Backend.cpp:357 at main 25da98de).
• applyRestoredState() runs on every engaged connect and resets m_autoGainConfig = AutoGainConfig{} and m_autoGainMode = "ramp" (Hl2Backend.cpp:7618-7619). The comment above that block says the live members "reset to the same virgin defaults a fresh backend construction would have". They do not.
• The reset line predates the commit that made the bandscope law the constructed default, and that commit did not touch applyRestoredState(). No test reads the law after a restore.

So since #5652 merged, an HL2 that arms auto RF gain after a connect has been running ramp. That law attacks and releases on the ADC clip counter alone, with a 26 dB floor. The #5535 ruling approved moving to the wideband bandscope as the input (point 3) and a maxOffsetDb of 24 (point 2). Neither applies after a connect.

What this changes here:

• Every figure in my two comments above is a ramp figure. I have not measured the bandscope law after a connect.
• This PR is not affected in what it changes (the arming ceiling). But "arm by default after fix(hl2): let auto RF gain arm across the native range — the +19 ceiling came from one faulty unit. Principle II. #5976" would arm the wrong law, so the connect law has to be fixed first.

I have a local fix in progress: applyRestoredState() installs the same law and config as construction, and a test reads the law after a restore. I will bring it as its own PR, and then re-measure on the law that was approved.

73, ON8ST

[on8st]

The fix for the connect law is now open as #6062.

Two things in this PR are affected by it:

• This PR's body says "The default floor of 26 is unchanged." With fix(hl2): install the bandscope law on every connect. Principle VIII. #6062 the law after a connect is the bandscope law, and its floor is 24. That sentence is then true only of the ramp law.
• The two PRs conflict in one place, tests/hl2_gain_split_test.cpp. That test asserted a floor of 26 in a restored session, which was the defect. Merged together locally with that assertion at 24, the full suite passes (558/558). Whichever of the two lands second gets that one-line resolution, and I will do it.

73, ON8ST

[on8st]

I can now explain the terminated-input figure I could not reproduce, and I withdraw it.

The body said that with a terminated input the clip flag appears from +31…+35 dB. This morning I wrote that I did not know why the 27 September run saw that. The reason is in that run's own record: the leg was not on a terminated input. The sweep's "dummy" leg is taken on whatever antenna the switch is on when the run starts, and the switch's own read-back for that leg shows the 80 m EFHW, at 14.074 MHz. The leg's name said dummy. The antenna was live.

So:

• The +31…+35 dB figure is a live-antenna clip point on 20 m. It is not a property of the converter with its input terminated. The sentence is struck in the body.
• On a real dummy load (1 October, the switch's port read back by its label before every leg) there is no ADC-overload observation anywhere from −12 to +48 dB.
• The fan-dipole figures in the same paragraph (+34 / +37 / +38 dB) were taken on the antenna they name. They stand as one afternoon's figures. My comment above gives the night's (+28 / +32).

This PR's code does not depend on the withdrawn figure. The check that let a leg be named for a load it was not on is in our own bench runner, and it is being fixed there.

73, ON8ST

[on8st]

An update to what I wrote above about #6062. After its review round the two PRs conflict in two places, not one. The second is the floor comment in Hl2Backend.h: #6062 now rewrites its opening lines (it starts at 24 dB), and this PR rewrites the paragraph about the sweep behind the ramp's 26. It is a comment-only conflict. The resolution keeps #6062's opening and this PR's paragraph for the 26, and I will do it on whichever lands second.

73, ON8ST

[ten9876]

Approving at b53498423. The change is accepted, and every finding is addressed and proved.

Fixed in this pass

• a473bde63:
  • docs/HERMES.md roadmap row 12 no longer calls the fold caveat open; it states it closed against ad9866.v@883a338 and the repaired unit.
  • Comments that retold the #5354 history are condensed to AGENTS.md § Comments.
  • New check "the deepest floor reaches the register floor from the top armable baseline". With kAutoRfGainFloorMaxDb = 31 it goes [FAIL]; restored, it passes.
• 9e482a786: the #5828 off from a restored wish, with the loop not yet running, is pinned. A guard regressed to if (on == m_autoRfGainEnabled) return; goes [FAIL]; restored, it passes. This came from the automated code-review pass.
• 5b4ac55e8 (maintainer decision: fold #5943's second half in here and keep Closes #5943):
  • The RF Gain slider's accessible description and tooltip now come from the range the radio published, no longer from a hardcoded Flex −8..+32.
  • A range push while Auto is armed no longer overwrites the read-only tooltip.
  • Reverting the fix turns 4 checks [FAIL]. Removing the isEnabled guard turns the armed check [FAIL]. check_a11y reports no new warning.
• ec678cdbd, b53498423: signed merges of main (#6045, #6007, #6021, #6005), both clean.

Verified empirically

• Gateware authority (Principle I): ad9866.v:134 reads rx_gain <= cmd_data[6] ? cmd_data[5:0] : …. With bit 6 set all six bits are native, so codes 0–60 = −12…+48 dB and there is no five-bit fold. The file at 883a338 is identical to master.
• Ceiling mutation (back to 19): hl2_gain_restore_test fails to compile on its static_assert, and hl2_gain_split_test gives 8 [FAIL]s.
• Full ctest at b53498423: 550/551 pass. The one failure is connection_panel_size_test, a known local failure (#5811). Socket-owning tests were excluded per the test-layer boundary.
• Static gates: engine boundary, capability records, command plane and the touchpoint manifest all match between merge base and head.

Reasoned, not run

• The connect-time arm of a stored autoEnabled: true is a MetisClient::linkUp lambda and cannot be driven socket-free. It is disclosed in the body and in applyRestoredState.
• The retained refusal branch is unreachable, because every writer of the baseline clamps to the native range. Its absent coverage is disclosed.

Hardware: on8st's receive-only runs on the repaired unit. Nothing was keyed, and no radio was touched in this pass.