fix(titlebar): keep the TX timer's slot so the audio row stops shifting. Principle VIII.

[w5jwp]

Summary

Fixes #6455

The title-bar audio controls no longer flick horizontally for a frame when the TX timer appears and disappears.

Cause. The transmit timer label (m_txTimerLabel) sits in the nested audio cluster just before PC Audio. The settled layout does not move when it hides: the drag gutter is the only stretch in m_hbox and absorbs the timer's 52 + 8 px, so the cluster's left edge moves, not PC Audio. What the operator saw is a one-pass transient: hiding the label made the cluster re-lay its children inside its still-old rect (PC Audio and everything right of it slide left), and the next pass shrank the cluster and snapped them back.

Change (src/gui/TitleBar.cpp, tests/unified_title_bar_test.cpp):

• QSizePolicy::setRetainSizeWhenHidden(true) on the timer label, so the cluster's size hint never changes and there is no second pass to catch. Visibility semantics are unchanged; txTimerState() (get txtimer) still reports visible from isVisible().
• Minimal mode turns the retention off (setMinimalMode()), so the idle slot does not hold 52 px of the narrow strip.
• The label text resets to 0:00 when the fade finishes, so the retained slot returns to normal width after an over longer than an hour.
• markDragHandle(audioCluster) so the reserved band keeps the open-hand cursor.
• audio->addSpacing(3), from the issue's proposed fix: the speaker icon is inset in its 22 px button, so the gap to its right read ~3 px wider than the 8 px on the timer side.

Trade-off. The reserved band is lost drag gutter, visually the same as the empty drag area that was there before. The real cost is that the bar's minimumSizeHint grows by about 55 px (52 + 3), which only bites when the bar is over-full and the gutter is already at 0.

Known limit. None for the hour case now: the text reset returns the slot to its normal width.

Constitution principle honored

Principle VIII — Evidence Over Assertion. The transient was measured (PC Audio x 1026 settled vs 978 after one layout pass in the #6455 thread) and is now pinned by a test that fails without the fix.

Test plan

• Focused local unified_title_bar_test build and CTest pass on the rebased code (macOS arm64, Qt 6.12.0, offscreen). Mutation: disabling size retention fails with PC Audio x=362 versus 415; restored fix passes.
• unified_title_bar_test: new checks hide the timer directly (skipping the hold and fade), pump one LayoutRequest pass and assert PC Audio's x is unchanged; same for setOtherClientTx(true,"X") then (false); minimal mode does not retain the timer's slot. The timer check fails (362 vs 415) with retainSizeWhenHidden reverted.
• Required CI passes on the rebased head
• Live: unkey and wait ~16 s, PC Audio does not flick; toggle minimal mode while idle, no 52 px gap

m_otherTxLabel is covered by a test, but it did not reproduce the transient in one layout pass on the offscreen platform, so no code change was made for it.

Checklist

• Commits are signed (docs/COMMIT-SIGNING.md) — SSH-signed as w5jwp
• No new flat-key AppSettings calls — none added (Principle V)
• Code is clean-room — not decompiled, disassembled, or reverse-engineered from a proprietary binary (Principle IV)
• All meter UI uses MeterSmoother — not applicable, no meter UI touched
• Documentation updated: timer spacing and minimal-mode behavior in the transmit-controls and menu-reference pages. CHANGELOG.md not touched.
• Security-sensitive changes reference a GHSA if applicable — not applicable

🤖 Generated with Claude Code

Landing validation: signed rebase onto current main; the timer-label policy, minimal-mode reservation, other-client label and slider cursor checks pass. No live-radio/TX or native-window visual validation was performed.

Generated with OpenAI Codex (GPT-6 Astra)

[aethersdr-agent]

Issue fit — partially, and the body's mechanism is refuted by the issue thread

The fix cures the real defect, but not for the reason the PR gives, and the thread moved under it 25 minutes after it was opened.

The body's cause section says that on expiry "PC Audio, the line-out speaker button, the master volume slider and readout, and the headphone control slid left by the timer's width, and slid back right at the next key-up." The triage pass on #6455 measured that and it does not happen in the settled layout: the audio cluster sits immediately right of the drag gutter, which is the only non-zero stretch in m_hbox (src/gui/TitleBar.cpp:332), so when the timer's 52 + 8 px slot collapses the gutter takes the width and the cluster's left edge moves right by the same amount. m_pcBtn's screen x is identical shown vs hidden, at every window width including the two where the gutter is already squeezed to 0.

What @jwpauler actually photographed — "a fraction of a second, followed by a shift back to the right" — is the nested cluster's intermediate layout pass: pass 1 re-lays the cluster's children inside its still-272 px rect (PC Audio slides left), pass 2 shrinks the cluster and snaps everything back. retainSizeWhenHidden does cure that, because the cluster's size hint stops changing at all, so there is no second pass to be caught between. The fix works; the stated mechanism is not why.

Two further body claims that the same measurement contradicts:

• "Trade-off. While idle there is now a permanent gap of about 52 px … to the left of PC Audio." It is lost gutter, not a gap — visually indistinguishable from the empty drag area that was already there. The real undisclosed cost is that the bar's minimumSizeHint grows by 52 + 3 px, which only bites when the bar is over-full and the gutter is already at 0.
• The title claims Principle VIII. The screenshots did establish the symptom, so the evidence is real — but the root-cause paragraph is the pre-triage reading. Worth rewriting the body around what was measured, since the comment added at :388-390 enshrines the refuted version in the source.

To be clear on timing: this PR was opened at 02:39 and the reproduction comment landed at 03:04, so the author was not ignoring it.

Scope

One file, two changes, nothing unexplained by #6455.

Change	Claimed?	Verdict
src/gui/TitleBar.cpp:388-394 — setRetainSizeWhenHidden(true) on m_txTimerLabel	Yes — the issue's proposed fix, and Option B in the thread	In scope; see Blockers 1 and the maintainer item
src/gui/TitleBar.cpp:398-400 — audio->addSpacing(3) + comment	Yes — issue "Proposed fix" bullet 2	In scope by the issue body, but the triage called it "purely cosmetic … a padding/spacing taste call rather than a defect, and worth settling separately from the shift." Needs the maintainer item below.

No build/CI/docs/vendor churn, no new public surface, no settings keys, no deleted guards, no CHANGELOG.md edit. The body's self-certifications check out against the diff.

Blockers

1. src/gui/TitleBar.cpp:1726-1754 — minimal mode now reserves the timer's slot in the narrow strip.

setMinimalMode() hides every audio control to free horizontal space, and deliberately does not touch the timer:

    m_pcBtn->setVisible(!on);
    m_speakerBtn->setVisible(!on);
    m_headphoneBtn->setVisible(!on);
    m_masterSlider->setVisible(!on);
    m_hpSlider->setVisible(!on);
    m_masterLabel->setVisible(!on);
    m_hpLabel->setVisible(!on);

None of those carry retainSizeWhenHidden, so they collapse properly and today the cluster shrinks to nothing in minimal mode. After this change the idle timer holds 52 px (plus the new 3 px spacer) in exactly the mode that exists to reclaim width. The thread named this as the one addition Option B still needs; it is not in the diff. Drop-in, in setMinimalMode() alongside the other visibility lines:

    // Minimal mode hides the audio row to free the strip; don't let the idle
    // timer's retained slot hold 52 px of it.
    {
        QSizePolicy sp = m_txTimerLabel->sizePolicy();
        sp.setRetainSizeWhenHidden(!on);
        m_txTimerLabel->setSizePolicy(sp);
    }

The 3 px spacer stays reserved either way; at 3 px that is negligible and not worth plumbing.

2. No regression test, and the stated reason for omitting one is incorrect.

The body says "there is no existing widget-layout test harness for TitleBar, and the property under test (row position across a show/hide cycle) is purely visual." There is one: unified_title_bar_test (tests/tests.cmake:7971-7999) compiles src/gui/TitleBar.cpp, runs under QT_QPA_PLATFORM=offscreen, and already asserts bar geometry (offsetInWindow, bar height) for exactly this kind of regression.

The property is also deterministic rather than visual, and the thread already drove it: show the timer, record m_pcBtn's window x, hide the label directly to skip the 15 s hold plus 800 ms fade, pump exactly one layout pass, assert x is unchanged.

    bar.setOperatorTransmitting(true);
    const int shownX = pcBtn->mapTo(&bar, QPoint(0, 0)).x();
    bar.findChild<QLabel*>(QStringLiteral("txTimerLabel"))->setVisible(false);
    QCoreApplication::sendPostedEvents(nullptr, QEvent::LayoutRequest);
    QCOMPARE(pcBtn->mapTo(&bar, QPoint(0, 0)).x(), shownX);

That is an assertion about equality across a cycle, not absolute pixels, so it does not inherit the font-dependence that makes other geometry probes here brittle. It fails on main (978 vs 1026 in the thread's replica), passes with this change, and it is the only thing in the PR that would pin the fix to the mechanism that was actually measured rather than the one the body describes. Per AGENTS.md's test-layer boundary this is a socket-free CTest in an existing registered target.

Needs maintainer decision

3. src/gui/TitleBar.cpp:388-394 and :398-400 — Option A vs B is still open, and the spacer was explicitly deferred.

#6455 carries maintainer-review and ends "I'd lean A — it removes the two-pass mechanism rather than papering over one instance of it — but B is smaller and keeps the cluster's grouping intent. Maintainer's call." Option A promotes the label out of the nested cluster into m_hbox, which removes the two-pass mechanism, needs no setMinimalMode() change, reserves nothing while idle, and gives the gap to PC Audio the bar's own 16 px inter-group spacing — close to what the 3 px spacer is reaching for. This PR implements B. Both measured flat; the choice is a judgment about whether to remove the mechanism or one instance of it, and no human has ruled yet. Not something I should adjudicate.

The spacer rides along in the same decision: it is listed in the issue's own proposed fix, so it is disclosed rather than smuggled, but the triage asked for it to be settled separately from the shift, and it is a permanent 3 px change to every operator's title bar with no defect behind it. If the maintainer takes Option A the spacer is moot anyway.

Nits (non-blocking)

• src/gui/TitleBar.cpp:388-390 — the comment states the refuted mechanism and will mislead the next reader:

  // doesn't reflow the row (PC Audio / volume / headphone would otherwise
// jump left on expiry and right on the next key-up).

  Suggested replacement:

    // Keep the slot reserved while idle so the cluster's size hint never
    // changes.  The settled row does not move (the drag gutter absorbs the
    // 52+8 px), but hiding the label made the nested cluster re-lay its
    // children inside its old rect for one pass, flicking PC Audio and
    // everything right of it left for a frame before m_hbox caught up (#6455).

• src/gui/TitleBar.cpp:423-425 — the label's text is never reset when it is hidden, so the retained slot keeps the width of the last reading. After an over past an hour (H:MM:SS, formatTxElapsed, :1363-1376) the idle gap stays wider for the rest of the session. The body's "Known limit" says "the row will resize once at that point, as it already did before this change" — before this change the width came back on hide; now it does not. One line in the fade-finished lambda fixes it: m_txTimerLabel->setText(QStringLiteral("0:00")); next to the setVisible(false).

• src/gui/TitleBar.cpp:398 — the reserved band is now bare audioCluster, which is not passed through markDragHandle(), so the cursor over those 52 px is the default arrow rather than the OpenHandCursor the gutter shows there today. Window dragging itself is unaffected (see below). markDragHandle(audioCluster); after the cluster is created would restore the affordance; children keep their own cursors.

• src/gui/TitleBar.cpp:352-354 — m_otherTxLabel sits in the same cluster and hides/shows the same way, so the same one-frame transient is still reachable when another client's TX indicator clears. Completeness only, and retainSizeWhenHidden is an awkward fit there because the label is text-sized — which is part of why the thread leaned toward Option A.

Security

Audited by the security-audit subagent against the CodeGuard findings. All 5 are false positives — none is a finding:

• src/gui/TitleBar.cpp:739 (CS-VLN-CMDI-AMP) is void TitleBar::setActiveRadio(const QString& id) — the & is a C++ reference qualifier, not a shell operator.
• :217, :661, :874, :1267 (CS-VLN-CMDI-BACKTICK) are all // comments whose backticks quote a QSS selector, an env-var assignment and a Qt signal name — the known lexical-match pattern.

The decisive point is structural: the translation unit has no process-spawning sink at all (no QProcess, system(, popen, execve; the two exec( hits are comments explaining why QMenu::popup() is used instead), so no CMDI source can be reachable. All five lines are pre-existing and outside the diff, consistent with a whole-file scan. The diff itself touches no input boundary, string formatting or dangerous API. Credit: security-audit (CodeGuard).

One pre-existing item outside the diff, noted and not asked for here: :1335 puts a peer's station name into m_otherTxLabel without setTextFormat(Qt::PlainText), and Qt auto-detects rich text.

What I tried to break

• The drag-dead-band theory. With the label hidden, childAt() returns audioCluster, which is not a drag handle, so isSystemMoveAreaAt() (:836-861) returns false for the reserved band — that looked like ~55 px of newly undraggable title bar. It is not: that function has zero callers anywhere in src/, and the live path is audioCluster (a plain QWidget, so it ignores presses) propagating to TitleBar::mousePressEvent (:1061) → startWindowMove(), which does not consult it. Dragging over the band still works; only the cursor changes, demoted to the nit above.
• The bridge verb. txTimerState() (:1420-1432) still derives visible from m_txTimerLabel->isVisible(), which retainSizeWhenHidden does not affect, so get txtimer reads the same as before. The body's claim here holds.
• The timer state machine. setOperatorTransmitting() (:1384-1417) is untouched, including the duplicate-rising-edge guard that protects an in-progress over and the spurious-unkey early return. No change to show/hold/fade ordering, no new path that keys or restores into a keyed transmitter.
• Over-constrained widths. The thread's harness probed 1400 / 900 / 700 / 560 / 480 px, including two widths where the gutter is already at 0 and the bar is over its minimum hint — zero delta at every one. That is what rules out the body's steady-state claim rather than just doubting it, and it is also why the only genuine width cost here is the grown minimumSizeHint.
• CI. All five checks green on 338c72a (Static checks, build, check-windows, check-macos, Sanitizer option configures). Normal base, not a stacked temp branch — but ctest in these lanes is -R-filtered, and no existing test asserts title-bar cluster geometry across a show/hide cycle, so green here is build evidence, not behavior evidence for this change.

Honesty boundary: I ran nothing. There is no build, no test run and no way to drive the GUI here, so every statement above is reasoned from the source in the PR head checkout. The layout numbers I rely on (pcX 1026 settled, 978 after one layout pass) are the triage harness's measurements quoted from the #6455 thread, not mine — I verified the code structure they describe (gutter stretch, cluster nesting, setMinimalMode's omission of the timer, isSystemMoveAreaAt's lack of callers) but not the measurements themselves.

Recommendation

Needs maintainer decision. The defect is real and retainSizeWhenHidden genuinely cures it, so there is a good fix in here — but the A-vs-B choice on #6455 is still unruled and this PR commits to B, and B as submitted is missing the setMinimalMode() clearing the thread named as its prerequisite. Concrete next step: a maintainer picks A or B on the issue. If B, the two blockers are small — the setRetainSizeWhenHidden(!on) block above, plus the regression test in unified_title_bar_test, which is also what would stop this from being re-litigated. Either way the body deserves a rewrite around the measured transient, since the current root-cause text is what the triage disproved.

Thanks for the unusually careful write-up on both the issue and the PR — the source reading was accurate, the trade-off was disclosed up front rather than buried, and the screenshot follow-up with "a fraction of a second, then it shifts back" is the single detail that cracked this open. The first triage pass got it wrong without it.

---

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

[aethersdr-agent]

Cisco CodeGuard — static analysis of this PR (5 finding(s))

• [CRITICAL] CS-VLN-CMDI-AMP — Vulnerability: CS-VLN-CMDI-AMP in src/gui/TitleBar.cpp /tmp/aetherclaude/pr-6456/src/gui/TitleBar.cpp:739
• [CRITICAL] CS-VLN-CMDI-BACKTICK — Vulnerability: CS-VLN-CMDI-BACKTICK in src/gui/TitleBar.cpp /tmp/aetherclaude/pr-6456/src/gui/TitleBar.cpp:217
• [CRITICAL] CS-VLN-CMDI-BACKTICK — Vulnerability: CS-VLN-CMDI-BACKTICK in src/gui/TitleBar.cpp /tmp/aetherclaude/pr-6456/src/gui/TitleBar.cpp:661
• [CRITICAL] CS-VLN-CMDI-BACKTICK — Vulnerability: CS-VLN-CMDI-BACKTICK in src/gui/TitleBar.cpp /tmp/aetherclaude/pr-6456/src/gui/TitleBar.cpp:874
• [CRITICAL] CS-VLN-CMDI-BACKTICK — Vulnerability: CS-VLN-CMDI-BACKTICK in src/gui/TitleBar.cpp /tmp/aetherclaude/pr-6456/src/gui/TitleBar.cpp:1267

_{Automated static scan by Cisco DefenseClaw CodeGuard on the changed files. Advisory — some may be false positives; the review above verifies them.}

---

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

[aethersdr-agent]

Antares Detector — candidate vulnerable file(s)

• src/gui/TitleBar.cpp

The transmit timer is allocated in TitleBar.cpp (lines 408–409) and connected to a timeout. The cleanup logic in the timeout handler stops and restarts the 15s hold/fade timer (lines ~1394–1417), which properly manages the timer slot lifecycle. The allocation and connection are safe; the vulnerability is not in allocation but in the missing explicit deletion of the timer slot in the timeout handler (the code stops/restarts the timer rather than deleting the slot), which could lead to a retained timer slot and memory-safety issues.

_{Localized by Cisco Foundation AI Antares-1B running locally in the AetherClaude sandbox, seeded by the Cartographer security map. Advisory only — please verify before acting.}

---

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

[w5jwp]

Thanks for the thorough review. Addressed in bf2d8f7:

• Blocker 1, minimal mode: setMinimalMode() now sets retainSizeWhenHidden(!on) on the timer label, with your comment.
• Blocker 2, test: added to unified_title_bar_test using your pattern (hide directly, one LayoutRequest pass, assert PC Audio x unchanged), plus the other-client TX case and a minimal-mode check. The timer check fails (362 vs 415) with the retain reverted, so it pins the mechanism.
• Body and comment: rewritten around the measured one-frame transient; trade-off restated as lost gutter plus ~55 px of minimumSizeHint.
• Nit, text reset: label resets to 0:00 when the fade finishes.
• Nit, cursor: markDragHandle(audioCluster).
• Nit, m_otherTxLabel: covered by a test. It did not reproduce the transient in one pass offscreen (with or without a synchronous m_hbox->activate()), so I left the code unchanged rather than add an unproven workaround. Happy to revisit if someone can reproduce it live.

Left to the maintainer: Option A vs B on #6455 (this PR is B), and whether the 3 px spacer stays (it is in the issue's proposed fix; trivial to drop).

[w5jwp]

Follow-up (verifier finding): marking the cluster as a drag handle made the master and headphone sliders inherit the open-hand cursor; both now set an explicit arrow cursor, and the test checks neither slider reports OpenHandCursor. Also worth noting: the other-client test is a guard rather than a mechanism pin, since the visible timer label absorbs the freed width in the first pass.

[w5jwp]

@aethersdr-agent please re-review at head 27dafca7. Your blockers (minimal-mode reservation, regression test) and nits (comment, text reset, drag cursor) were addressed in bf2d8f72, and 27dafca7 keeps the volume sliders off the cluster's drag-hand cursor. Option A vs B and the 3 px spacer remain the maintainer's call.

[jensenpat]

Reviewed the rebased head a67ea013867300dc67fe17e70177f8b896a53d00 against current main. The requested landing retains this PR's small reserved-slot implementation and 3 px spacer.

The earlier review's minimal-mode reservation and missing-test findings are fixed. The revised description matches the transient nested-layout mechanism. The fade resets the elapsed text; the reserved band has a drag cursor while the sliders retain arrow cursors. User-guide pages now describe stable control positions and minimal-mode behavior.

Local macOS arm64 / Qt 6.12.0: unified_title_bar_test builds and passes 1/1 under QT_QPA_PLATFORM=offscreen. Disabling retention makes the first-pass geometry check fail (PC Audio x=362 versus 415); restoring it passes. The suite also checks minimal-mode retention, other-client label clearing and both slider cursors. Engine-boundary, command-plane, capability-record, manifest, generated-reference and log-rule checks pass without baseline growth. All four commits are GitHub-verified.

CodeGuard's command-injection reports are lexical false positives: C++ references and backtick-containing comments, with no process-spawning sink in TitleBar.cpp. Antares' deletion suggestion is also invalid: the timers/animation use Qt parent ownership; a hidden label's retained layout slot is intentional and does not allocate repeatedly or require timeout-time deletion.

The automated review tool was unavailable; the diff, surrounding lifecycle and failure paths were reviewed manually. No live-radio/TX, native-window screenshot or visual inspection was performed. The geometry regression is exercised directly by the offscreen production TitleBar test; the bridge cannot produce those keyed timer transitions with TX disabled.

Hosted Docs and Static checks pass. Required platform builds are still in progress; the guarded auto-merge must wait for them.