fix(desktop): cycle listening through all three audio recording modes (#11640)

## Problem

`AssistantSettings.AudioRecordingMode` has three cases — `off`,
`always`, `onlyMeetings` — but the listening control could only reach
two of them. `toggleListening` read:

```swift
let nextMode = currentMode == .off ? .onlyMeetings : .off
```

so `.always` was **unreachable from the top bar and from Home**. Turning
the microphone "on" always armed the meetings gate, which deliberately
holds the mic shut until a call is detected; there was no way to ask for
continuous recording from either shell. Reported from the top-bar
button: it "only toggles between off and only meetings".

Only Meetings was also indistinguishable from Always On at a glance —
same `mic`, same dot — even though the two behave completely
differently.

## Change

- **A cycle, not a flip.** `CaptureListeningLogic.cycleListening`
advances `Off → Always On → Only Meetings → Off`. Both shells already
share this one function, so both gain the third mode.
- **Only Meetings is marked.** It carries `person.2.fill` in the corner.
The mark is *additive corner ink* like the state dot — the base `mic`
silhouette stays byte-identical in every state, which is the rule the
cluster's header sets and `ShellStatusIconLegibilityTests` measures in
pixels.
- **Only Meetings explains itself once.** Selecting it shows a popover —
"the microphone stays closed until Omi detects a call, then records
until it ends" — which auto-dismisses. It fires on the transition only,
never on hover and never at rest, so the resting cluster stays wordless.
- **The tooltip names the destination.** "Click to stop" was true of a
two-state switch and is a false promise from Always On, where a click
selects Only Meetings and stops nothing.

## Product invariants

**INV-CHAT-1** (one shared transcript across surfaces) — cited because
the diff touches
`desktop/macos/Desktop/Sources/MainWindow/Pages/DashboardPage.swift`,
which is inside its path globs.
The change there is a single call-site rename (`toggleListening` →
`cycleListening`); it does not
touch conversation ownership, transcript routing, or any chat surface,
so the invariant's guard tests
are unchanged.

## Failure class

Failure-Class: FC-split-mutation-authority

The control is the authority for the listening mode's transitions, but
it only ever authored two of the three states the mode declares, leaving
the third reachable exclusively from Settings. The fix is the class's
canonical prevention: one transition function owns the whole state
machine, and `testTheCycleCoversEveryDeclaredMode` fails if a future
mode is added that the control cannot select.

## Review follow-ups (second commit)

Both findings from the automated review were valid and are fixed:

**P1 — the microphone stayed open when Only Meetings could not yet prove
a call.** `reconcileCapture`'s
`guard meetingStateReady else { return }` returned *before* either pause
branch. Selecting Only Meetings
from a live Always session builds a fresh detector, so that first pass
runs with
`hasObservedState == false` and the microphone the previous mode opened
kept running until the detector's
first asynchronous probe landed. A gate the user selects in order to
close the mic has to fail closed, so
"not known yet" now means "not in a call". `MeetingGateReadinessPolicy`
names the rule and
`pauseCaptureWhileMeetingGateUnknown` takes the same stop the normal
gating takes, earlier.

This path only became reachable from the button in this PR: before it,
Always On could not be selected
outside Settings, so `Always → Only Meetings` was not a transition the
control could make.

**P2 — the tooltip promised a mode the click could not reach.** Without
the microphone grant, a click
spends itself on the permission prompt and the mode does not move. The
tooltip now says what is actually
missing until the grant exists.

Line-Count-Exception:
desktop/macos/Desktop/Sources/AppState/AppState+Transcription.swift |
1736 -> 1738 | Fail-closed privacy fix for P1. The pause helper and its
policy live in new files (`AppState+MeetingGatePause.swift`,
`MeetingGateReadinessPolicy`); the two lines added here are the guard's
call and its comment, which have to sit at the point reconcileCapture
returns early.

## Verification

- `xcrun swift build -c debug --package-path Desktop --build-tests` —
clean.
- `ShellListeningCycleTests` 14/14, `ShellStatusIconLegibilityTests`
13/13, `DashboardCaptureStateTests` 10/10,
`MeetingGatedSystemAudioTests` — **43 tests, 0 failures**.
- **The regression test fails against the shipped behaviour.** Reverting
`nextAudioRecordingMode` to the two-state flip fails 4 tests and
reproduces the report verbatim:

> the listening cycle ran off → onlyMeetings → off → onlyMeetings. It
has to offer all three modes…

- `make preflight` — all checks pass.

### What is *not* verified, explicitly

The final code has **automated coverage only — it was not click-verified
in a running build.** The full three-state cycle, the `person.2.fill`
badge and the popover *were* exercised live (clicking the real control,
reading `defaults` and screenshotting each state) on a build of the
pre-rebase implementation, which carried the same badge, popover and
cycle order against the older two-setting model. That evidence does not
transfer to this diff.

The blocker was environmental, not the change: the summoned shell places
itself on this machine's secondary display, synthesized clicks are not
delivered there (a control-tab click failed too), and the panel
auto-dismisses on any focus change, so it could not be relocated to the
primary display. Worth a reviewer clicking the button once before merge.

## Notes for review

Three `ShellStatusTooltip.audio` call sites in
`ShellStatusIconLegibilityTests` gained a `next:` argument. Two are
mechanical — their assertions (`hasPrefix("Audio")`, `contains("Meetings
only")`) are byte-identical. The third,
`testTheAwaitingMeetingAudioTooltipDoesNotClaimOffOrStart`, changed one
expected literal from `"Click to turn off"` to `"Click for Off"`: from
Only Meetings a click still lands on Off, so the guard's intent is
unchanged and its real assertion — `XCTAssertFalse(contains("Click to
start"))` — is untouched. Only the copy it looks for moved.

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

Author: Git-on-my-level

desktop/macos/Desktop/Sources/AppState/AppState+MeetingGatePause.swift

@@ -0,0 +1,37 @@
+import Foundation
+
+extension AppState {
+  /// Pause both capture paths without ending the session, for the window in which the meeting gate
+  /// has not answered yet. Mirrors the pause branches `reconcileCapture` uses once it does answer;
+  /// this is the same stop, taken earlier, when the honest answer is "not in a call as far as we
+  /// know".
+  /// Apply `MeetingGateReadinessPolicy` and pause when it says the gate cannot yet justify capture.
+  @MainActor
+  func pauseCaptureIfMeetingGateUnknown(
+    mode: AssistantSettings.AudioRecordingMode, meetingStateReady: Bool
+  ) {
+    guard
+      MeetingGateReadinessPolicy.shouldPauseCapture(
+        mode: mode, meetingStateReady: meetingStateReady)
+    else { return }
+    pauseCaptureWhileMeetingGateUnknown()
+  }
+
+  @MainActor
+  func pauseCaptureWhileMeetingGateUnknown() {
+    if let mic = audioCaptureService, mic.capturing {
+      mic.stopCapture()
+      AudioLevelMonitor.shared.updateMicrophoneLevel(0)
+      log("Transcription: Microphone capture paused (meeting state not yet known)")
+    }
+    if #available(macOS 14.4, *) {
+      if let systemService = systemAudioCaptureService as? SystemAudioCaptureService,
+        systemService.capturing
+      {
+        systemService.stopCapture()
+        AudioLevelMonitor.shared.updateSystemLevel(0)
+        log("Transcription: System audio capture paused (meeting state not yet known)")
+      }
+    }
+  }
+}

desktop/macos/Desktop/Sources/AppState/AppState+Transcription.swift

@@ -616,6 +616,8 @@ extension AppState {
     isAwaitingMeeting = mode == .onlyMeetings && !meetingActive
 
     guard meetingStateReady else {
+      // Fail closed while the gate has not answered — see `pauseCaptureWhileMeetingGateUnknown`.
+      pauseCaptureIfMeetingGateUnknown(mode: mode, meetingStateReady: meetingStateReady)
       log("Transcription: waiting for meeting detector before changing capture state")
       return
     }

desktop/macos/Desktop/Sources/AppState/MeetingConversationBoundaryPolicy.swift

@@ -1,5 +1,20 @@
 import Foundation
 
+/// Whether capture may continue while the meeting gate has not yet answered.
+///
+/// Only Meetings is a *closed* gate that a detected call opens, so "we do not know yet" has to be
+/// treated as "not in a call". Selecting Only Meetings from a live Always session builds a fresh
+/// detector, so its first reconcile pass runs with `hasObservedState == false`; leaving capture
+/// alone until the first probe lands would keep the microphone the previous mode opened running
+/// after the user asked for it to be closed.
+enum MeetingGateReadinessPolicy {
+  static func shouldPauseCapture(
+    mode: AssistantSettings.AudioRecordingMode, meetingStateReady: Bool
+  ) -> Bool {
+    mode == .onlyMeetings && !meetingStateReady
+  }
+}
+
 enum MeetingConversationBoundaryPolicy {
   typealias Role = TranscriptionConversationRole
 

desktop/macos/Desktop/Sources/MainWindow/CaptureListeningLogic.swift

@@ -62,17 +62,50 @@ enum CaptureListeningLogic {
     }
   }
 
+  /// Off → Always On → Only Meetings → Off.
+  ///
+  /// `AudioRecordingMode` has three cases, but the control only ever reached two of them: it
+  /// flipped between `.off` and `.onlyMeetings`, so `.always` — the mode that actually records
+  /// continuously — could not be selected from the top bar or Home at all, and turning the
+  /// microphone "on" silently armed a gate that keeps it shut until a call starts.
+  static func nextAudioRecordingMode(after mode: AssistantSettings.AudioRecordingMode)
+    -> AssistantSettings.AudioRecordingMode
+  {
+    switch mode {
+    case .off: return .always
+    case .always: return .onlyMeetings
+    case .onlyMeetings: return .off
+    }
+  }
+
+  /// The name of a *mode*, for naming a state the session is not in yet.
+  ///
+  /// Distinct from `listeningModeTitle`, which describes the **running** session and may answer
+  /// with the live microphone's own name ("Ray-Ban Meta") or with "In Meeting". That is the right
+  /// answer for "what is happening now" and the wrong one for "what does this click select".
+  static func audioRecordingModeTitle(_ mode: AssistantSettings.AudioRecordingMode) -> String {
+    switch mode {
+    case .off: return "Off"
+    case .always: return "Always On"
+    case .onlyMeetings: return "Only Meetings"
+    }
+  }
+
   // MARK: Actions
 
-  static func toggleListening(
+  /// Advance the control one step. Returns the mode it landed on so a caller can react to the
+  /// transition itself, or `nil` when the click was spent on the permission prompt and the state
+  /// did not move.
+  @discardableResult
+  static func cycleListening(
     appState: AppState, audioRecordingModeRaw: Binding<String>, isTogglingListening: Binding<Bool>
-  ) {
+  ) -> AssistantSettings.AudioRecordingMode? {
     let currentMode = audioRecordingMode(raw: audioRecordingModeRaw.wrappedValue)
-    let nextMode: AssistantSettings.AudioRecordingMode = currentMode == .off ? .onlyMeetings : .off
+    let nextMode = nextAudioRecordingMode(after: currentMode)
     let enabled = nextMode != .off
     if enabled && !appState.hasMicrophonePermission {
       appState.requestMicrophonePermission()
-      return
+      return nil
     }
 
     isTogglingListening.wrappedValue = true
@@ -82,6 +115,7 @@ enum CaptureListeningLogic {
     DispatchQueue.main.asyncAfter(deadline: .now() + 0.3) {
       isTogglingListening.wrappedValue = false
     }
+    return nextMode
   }
 
   static func toggleCapture(

desktop/macos/Desktop/Sources/MainWindow/Pages/DashboardPage.swift

@@ -1799,7 +1799,7 @@ struct DashboardPage: View {
   }
 
   private func toggleListening() {
-    CaptureListeningLogic.toggleListening(
+    CaptureListeningLogic.cycleListening(
       appState: appState, audioRecordingModeRaw: $audioRecordingModeRaw,
       isTogglingListening: $isTogglingListening)
   }

desktop/macos/Desktop/Sources/MainWindow/QueryShell/ShellStatusIcons.swift

@@ -204,6 +204,28 @@ enum ShellStatusGlyph {
   /// pair measured **while listening**, when the mic became `waveform`; that is the state the reported
   /// screenshot was in, and it is fixed by `listening` above rather than by this line.
   static let screen = "display"
+
+  /// The corner mark the listening control wears while its mode is Only Meetings.
+  ///
+  /// **This is not the swap the header rejects.** `listening` above is still the only listening
+  /// silhouette and is still byte-identical in every state; this rides *outside* it, in the corner,
+  /// exactly as `ShellStatusDot` does. The header's distinction is between ink that *replaces* the
+  /// glyph and ink that is *added* to it, and both marks this control wears are the second kind.
+  ///
+  /// **It is also not a new vocabulary.** `person.2.fill` is already the mark Home's listening
+  /// control uses for this mode, so one mode reads the same on both shells rather than growing a
+  /// second symbol for one idea.
+  static let meetingsOnly = "person.2.fill"
+
+  /// Which modes wear a mark, as a function rather than a ternary inside a `body`, so the rule —
+  /// *exactly one* of the three modes is badged — is something a test can state directly instead of
+  /// scraping it back out of the view.
+  ///
+  /// `.always` and `.off` are deliberately unbadged: the dot and the slash already say everything
+  /// true about them, and a mark on every state is a mark that distinguishes nothing.
+  static func modeBadge(for mode: AssistantSettings.AudioRecordingMode) -> String? {
+    mode == .onlyMeetings ? meetingsOnly : nil
+  }
 }
 
 // MARK: - The sentence
@@ -226,17 +248,30 @@ enum ShellStatusTooltip {
   /// `isAwaitingMeeting` is the Only Meetings wait: the session is armed, the mic is paused, and a
   /// click turns listening *off* rather than starting it. That must not reuse the "off / click to
   /// start" sentence.
-  static func audio(state: HomeStatusState, mode: String, isAwaitingMeeting: Bool = false) -> String {
+  /// `next` names the mode a click moves to. It is a parameter rather than the fixed "Click to
+  /// stop" / "Click to start" this shipped with, because the control is a three-mode cycle: from
+  /// Always On a click does not stop anything, it selects Only Meetings, and a tooltip on a
+  /// wordless control is the only place that promise is written down. Naming the destination also
+  /// makes the third mode discoverable without clicking twice to find it.
+  static func audio(
+    state: HomeStatusState, mode: String, isAwaitingMeeting: Bool = false, next: String,
+    hasMicrophonePermission: Bool = true
+  ) -> String {
     switch state {
     case .blocked:
       return "Audio — transcription unavailable. Open Settings to reconnect."
     case .active:
-      return "Audio — listening (\(mode)). Click to stop."
+      return "Audio — listening (\(mode)). Click for \(next)."
     case .inactive:
+      // Without the microphone grant a click spends itself on the permission prompt and the mode
+      // does not move, so promising the next mode here would be a promise the click cannot keep.
+      guard hasMicrophonePermission else {
+        return "Audio — off. Omi needs microphone access. Click to grant it."
+      }
       if isAwaitingMeeting {
-        return "Audio — waiting for a call (\(mode)). Nothing is being transcribed. Click to turn off."
+        return "Audio — waiting for a call (\(mode)). Nothing is being transcribed. Click for \(next)."
       }
-      return "Audio — off. Nothing is being transcribed. Click to start."
+      return "Audio — off. Nothing is being transcribed. Click for \(next)."
     }
   }
 
@@ -273,6 +308,16 @@ struct ShellStatusIconButton: View {
   /// is exact only while this flag moves nothing else. Product code leaves it alone and passes
   /// `state: nil` for a control that has no badge to draw.
   var showsDot: Bool = true
+  /// A corner mark naming the *mode* a capability is running in, for a control that has more than
+  /// one. `nil` on every control that does not — screen capture has no modes, and a mark it never
+  /// wears is not a mark it should be able to draw.
+  ///
+  /// It follows `showsDot`'s contract, not the glyph's: additive ink outside the silhouette, so
+  /// `ShellStatusGlyph.listening` stays byte-identical across every state and the swap guard in
+  /// `ShellStatusIconLegibilityTests` still measures what it was written to measure. It sits on the
+  /// leading edge because the dot owns the trailing corner, and the two answer different questions —
+  /// the dot whether it is capturing, this one which mode it is set to.
+  var badge: String? = nil
   var isSelected: Bool = false
   let action: () -> Void
 
@@ -305,6 +350,13 @@ struct ShellStatusIconButton: View {
           ShellStatusDot(state: state).offset(x: 6, y: -5)
         }
       }
+      .overlay(alignment: .bottomLeading) {
+        if let badge {
+          Image(systemName: badge)
+            .scaledFont(size: OmiType.micro, weight: .bold)
+            .offset(x: -5, y: 4)
+        }
+      }
     }
     .buttonStyle(GlassIconButtonStyle(isActive: isSelected || isActive))
     .help(tooltip)
@@ -326,6 +378,12 @@ struct ShellStatusIcons: View {
   @State private var isCaptureMonitoring = false
   @State private var isTogglingCapture = false
   @State private var isTogglingListening = false
+  /// Shown for a beat when a click *selects* Only Meetings, never on hover and never at rest.
+  /// Only Meetings is the one mode whose behaviour no glyph can state — the control is switched
+  /// on while the microphone is deliberately held shut until a call starts — so selecting it is
+  /// the one moment that earns a sentence. Tying it to the transition keeps the cluster wordless.
+  @State private var showsMeetingsHint = false
+  @State private var meetingsHintDismissal: DispatchWorkItem?
 
   @AppStorage("screenAnalysisEnabled") private var screenAnalysisEnabled = true
   @AppStorage(AssistantSettings.audioRecordingModeDefaultsKey) private var audioRecordingModeRaw =
@@ -338,9 +396,18 @@ struct ShellStatusIcons: View {
         tooltip: listeningTooltip,
         state: listeningState,
         isBusy: isTogglingListening,
-        action: toggleListening
+        badge: ShellStatusGlyph.modeBadge(for: listeningMode),
+        action: cycleListening
       )
       .accessibilityIdentifier("shell-status-listening")
+      .popover(isPresented: $showsMeetingsHint, attachmentAnchor: .rect(.bounds), arrowEdge: .bottom) {
+        Text(Self.meetingsHint)
+          .scaledFont(size: OmiType.caption)
+          .foregroundStyle(Ink.primary)
+          .multilineTextAlignment(.leading)
+          .frame(width: 232, alignment: .leading)
+          .padding(OmiSpacing.sm)
+      }
 
       ShellStatusIconButton(
         systemImage: ShellStatusGlyph.screen,
@@ -366,12 +433,27 @@ struct ShellStatusIcons: View {
     CaptureListeningLogic.listeningStatus(appState: appState)
   }
 
+  /// What the control is *set to* — distinct from `listeningState`, which is whether it is
+  /// currently capturing. Only Meetings is exactly the case where those two disagree, so the
+  /// button needs both.
+  private var listeningMode: AssistantSettings.AudioRecordingMode {
+    CaptureListeningLogic.audioRecordingMode(raw: audioRecordingModeRaw)
+  }
+
+  /// The sentence Only Meetings earns, kept beside the mode it explains. Static so a test can
+  /// read the wording without standing up an `AppState`.
+  static let meetingsHint =
+    "Only Meetings — the microphone stays closed until Omi detects a call, then records until it ends."
+
   private var listeningTooltip: String {
     ShellStatusTooltip.audio(
       state: listeningState,
       mode: CaptureListeningLogic.listeningModeTitle(
         appState: appState, raw: audioRecordingModeRaw),
-      isAwaitingMeeting: appState.isAwaitingMeeting)
+      isAwaitingMeeting: appState.isAwaitingMeeting,
+      next: CaptureListeningLogic.audioRecordingModeTitle(
+        CaptureListeningLogic.nextAudioRecordingMode(after: listeningMode)),
+      hasMicrophonePermission: appState.hasMicrophonePermission)
   }
 
   private var captureState: HomeStatusState {
@@ -382,11 +464,22 @@ struct ShellStatusIcons: View {
 
   // MARK: Actions — the shared logic, never a second copy
 
-  private func toggleListening() {
-    CaptureListeningLogic.toggleListening(
+  private func cycleListening() {
+    let landed = CaptureListeningLogic.cycleListening(
       appState: appState,
       audioRecordingModeRaw: $audioRecordingModeRaw,
       isTogglingListening: $isTogglingListening)
+
+    // A click spent on the permission prompt moved nothing, so it explains nothing.
+    meetingsHintDismissal?.cancel()
+    guard landed == .onlyMeetings else {
+      showsMeetingsHint = false
+      return
+    }
+    showsMeetingsHint = true
+    let dismissal = DispatchWorkItem { showsMeetingsHint = false }
+    meetingsHintDismissal = dismissal
+    DispatchQueue.main.asyncAfter(deadline: .now() + 4, execute: dismissal)
   }
 
   private func toggleCapture() {