Converge macOS Voice trigger entry points

Author: MarcusJRLee

Sources/HardwareControllerApp/app_model.swift

@@ -224,6 +224,13 @@ final class AppModel {
         || selectedLocalAIReadiness.state.canRun)
   }
 
+  var voiceCaptureButtonState: VoiceCaptureButtonState {
+    VoiceCaptureButtonState(
+      phase: localAIDictationSnapshot.phase,
+      canBegin: canExecuteLocalAIDictation
+    )
+  }
+
   /// Reports whether one configured Action can currently execute.
   func canExecute(_ kind: ActionKind) -> Bool {
     switch kind {
@@ -586,6 +593,17 @@ final class AppModel {
     }
   }
 
+  /// Starts or finishes the shared Voice session from the menu bar.
+  func toggleVoiceCapture() {
+    let state = voiceCaptureButtonState
+    guard state.isEnabled, let command = state.command else {
+      return
+    }
+    enqueueIntent { [runtime] in
+      await runtime.submitVoiceCapture(command)
+    }
+  }
+
   /// Sends one demo Control transition.
   func simulate(
     _ controlID: ControlID,

Sources/HardwareControllerApp/application_runtime.swift

@@ -210,6 +210,9 @@ protocol ApplicationProcessControlling: Sendable {
   /// Runs a sanitized generation test without microphone or target access.
   func testLocalAIProvider() async -> LocalAIRefinementFailure?
 
+  /// Submits one app-initiated command to the shared Voice dispatcher.
+  func submitVoiceCapture(_ command: DictationCommand) -> Bool
+
   /// Runs one configured Binding without physical input.
   func testBinding(_ controlID: ControlID)
 
@@ -620,6 +623,14 @@ private final class LiveApplicationProcess:
     return await localAIDictationController.testProvider()
   }
 
+  /// Uses the same Local AI dispatcher as Controls and the Voice chord.
+  func submitVoiceCapture(_ command: DictationCommand) -> Bool {
+    guard isRunning else {
+      return false
+    }
+    return voiceDictationDispatcher.submit(command)
+  }
+
   private static let demoLocalAIReadiness = LocalAIReadinessSnapshot(
     apple: LocalAIProviderReadiness(
       provider: .appleOnDevice,
@@ -1449,6 +1460,24 @@ actor ApplicationRuntime {
     process.testBinding(controlID)
   }
 
+  /// Routes one in-app command through the process-owned Voice session.
+  @discardableResult
+  func submitVoiceCapture(_ command: DictationCommand) -> Bool {
+    guard isStarted, !isStopped, !isSuspended else {
+      return false
+    }
+    if command == .begin, !canExecuteLocalAIDictation {
+      return false
+    }
+    let accepted = process.submitVoiceCapture(command)
+    if !accepted {
+      snapshot.lastError =
+        "Voice capture is busy. Wait for the current session to finish."
+      publish()
+    }
+    return accepted
+  }
+
   /// Sends one demo transition through the process implementation.
   func simulate(
     _ controlID: ControlID,

Sources/HardwareControllerApp/hardware_controller_app.swift

@@ -362,6 +362,15 @@ private struct MenuBarContent: View {
         )
       }
 
+      Button(
+        model.voiceCaptureButtonState.title,
+        systemImage: model.voiceCaptureButtonState.systemImage
+      ) {
+        model.toggleVoiceCapture()
+      }
+      .disabled(!model.voiceCaptureButtonState.isEnabled)
+      .accessibilityIdentifier("voice_capture_button")
+
       Divider()
 
       Picker(

Sources/HardwareControllerApp/voice_capture_button_state.swift

@@ -0,0 +1,52 @@
+import HardwareControllerCore
+import HardwareControllerMac
+
+/// Derives one menu action from the authoritative Voice-session phase.
+struct VoiceCaptureButtonState: Equatable, Sendable {
+  let title: String
+  let systemImage: String
+  let isEnabled: Bool
+  let command: DictationCommand?
+
+  init(
+    title: String,
+    systemImage: String,
+    isEnabled: Bool,
+    command: DictationCommand?
+  ) {
+    self.title = title
+    self.systemImage = systemImage
+    self.isEnabled = isEnabled
+    self.command = command
+  }
+
+  init(
+    phase: LocalAIDictationPhase,
+    canBegin: Bool
+  ) {
+    switch phase {
+    case .idle, .completed, .failed:
+      self.init(
+        title: "Record Voice",
+        systemImage: "mic.fill",
+        isEnabled: canBegin,
+        command: .begin
+      )
+    case .preparing, .listening:
+      self.init(
+        title: "Stop Recording",
+        systemImage: "stop.fill",
+        isEnabled: true,
+        command: .finish
+      )
+    case .finalizing, .refining, .validating, .delivering,
+      .canceling:
+      self.init(
+        title: "Finishing Voice…",
+        systemImage: "waveform",
+        isEnabled: false,
+        command: nil
+      )
+    }
+  }
+}

Tests/HardwareControllerAppTests/application_runtime_test.swift

@@ -23,6 +23,40 @@ struct ApplicationRuntimeTest {
     #expect(!fixture.snapshots.values.isEmpty)
   }
 
+  /// Routes app UI capture through the process Voice dispatcher while active.
+  @Test
+  func voiceCaptureSubmissionFollowsRuntimeLifecycle() async {
+    let fixture = RuntimeFixture(
+      localAIReadiness: LocalAIReadinessSnapshot(
+        apple: LocalAIProviderReadiness(
+          provider: .appleOnDevice,
+          state: .ready
+        ),
+        ollama: LocalAIProviderReadiness(
+          provider: .ollama,
+          state: .unavailable("Not selected.")
+        )
+      )
+    )
+    await fixture.runtime.start(
+      snapshotHandler: fixture.snapshots.append
+    )
+
+    #expect(await fixture.runtime.submitVoiceCapture(.begin))
+    #expect(await fixture.runtime.submitVoiceCapture(.finish))
+    await fixture.runtime.prepareForSleep()
+    #expect(!(await fixture.runtime.submitVoiceCapture(.begin)))
+    await fixture.runtime.resumeAfterWake()
+    #expect(await fixture.runtime.submitVoiceCapture(.begin))
+    await fixture.runtime.stop()
+    #expect(!(await fixture.runtime.submitVoiceCapture(.finish)))
+
+    #expect(
+      fixture.process.voiceCaptureCommands
+        == [.begin, .finish, .begin]
+    )
+  }
+
   /// Starts hardware before a slow optional provider readiness check returns.
   @Test(.timeLimit(.minutes(1)))
   func localAIReadinessNeverDelaysHardwareStartup() async {
@@ -898,6 +932,7 @@ private final class FakeApplicationProcess:
   private var retryStorage = HardwareInputStartResult.started
   private var preferredMicrophoneUIDStorage: [String?] = []
   private var voiceTriggerSettingsStorage: [VoiceTriggerSettings] = []
+  private var voiceCaptureCommandStorage: [DictationCommand] = []
   private var localAIReadinessStorage = LocalAIReadinessSnapshot.checking
   private var localAIReadinessContinuation: CheckedContinuation<Void, Never>?
   private var localAIReadinessObservers: [CheckedContinuation<Void, Never>] = []
@@ -949,6 +984,10 @@ private final class FakeApplicationProcess:
     lock.withLock { voiceTriggerSettingsStorage }
   }
 
+  var voiceCaptureCommands: [DictationCommand] {
+    lock.withLock { voiceCaptureCommandStorage }
+  }
+
   var retryResult: HardwareInputStartResult {
     get {
       lock.withLock { retryStorage }
@@ -1126,6 +1165,14 @@ private final class FakeApplicationProcess:
     return nil
   }
 
+  /// Records commands sent through the process Voice dispatcher.
+  func submitVoiceCapture(_ command: DictationCommand) -> Bool {
+    lock.withLock {
+      voiceCaptureCommandStorage.append(command)
+    }
+    return true
+  }
+
   /// Accepts a deterministic test request.
   func testBinding(_ controlID: ControlID) {}
 

Tests/HardwareControllerAppTests/voice_capture_button_state_test.swift

@@ -0,0 +1,80 @@
+import HardwareControllerCore
+import HardwareControllerMac
+import Testing
+
+@testable import HardwareControllerApp
+
+struct VoiceCaptureButtonStateTest {
+  @Test
+  func idleCompletedAndFailedStartOnlyWhenLocalAIIsAvailable() {
+    for phase in [
+      LocalAIDictationPhase.idle,
+      .completed,
+      .failed,
+    ] {
+      #expect(
+        VoiceCaptureButtonState(
+          phase: phase,
+          canBegin: true
+        )
+          == VoiceCaptureButtonState(
+            title: "Record Voice",
+            systemImage: "mic.fill",
+            isEnabled: true,
+            command: .begin
+          )
+      )
+      #expect(
+        VoiceCaptureButtonState(
+          phase: phase,
+          canBegin: false
+        ).isEnabled == false
+      )
+    }
+  }
+
+  @Test
+  func preparingAndListeningAlwaysOfferToStopTheOwnedCapture() {
+    for phase in [
+      LocalAIDictationPhase.preparing,
+      .listening,
+    ] {
+      #expect(
+        VoiceCaptureButtonState(
+          phase: phase,
+          canBegin: false
+        )
+          == VoiceCaptureButtonState(
+            title: "Stop Recording",
+            systemImage: "stop.fill",
+            isEnabled: true,
+            command: .finish
+          )
+      )
+    }
+  }
+
+  @Test
+  func postCaptureWorkCannotStartOrFinishAnotherSession() {
+    for phase in [
+      LocalAIDictationPhase.finalizing,
+      .refining,
+      .validating,
+      .delivering,
+      .canceling,
+    ] {
+      #expect(
+        VoiceCaptureButtonState(
+          phase: phase,
+          canBegin: true
+        )
+          == VoiceCaptureButtonState(
+            title: "Finishing Voice…",
+            systemImage: "waveform",
+            isEnabled: false,
+            command: nil
+          )
+      )
+    }
+  }
+}

Tests/HardwareControllerMacTests/voice_keyboard_trigger_controller_test.swift

@@ -26,6 +26,28 @@ struct VoiceKeyboardTriggerControllerTest {
     #expect(dispatcher.commands == [.begin, .finish])
   }
 
+  @Test
+  func doublePressLatchesThenTheNextDoublePressFinishesOnce() async throws {
+    let dispatcher = DictationCommandRecorder()
+    let controller = try VoiceKeyboardTriggerController(
+      settings: .default,
+      dispatcher: dispatcher
+    )
+
+    await controller.handle(phase: .pressed, timestampNanoseconds: ms(0))
+    await controller.handle(phase: .released, timestampNanoseconds: ms(50))
+    await controller.handle(phase: .pressed, timestampNanoseconds: ms(100))
+    await controller.handle(phase: .released, timestampNanoseconds: ms(150))
+    #expect(dispatcher.commands == [.begin])
+
+    await controller.handle(phase: .pressed, timestampNanoseconds: ms(1_000))
+    await controller.handle(phase: .released, timestampNanoseconds: ms(1_050))
+    await controller.handle(phase: .pressed, timestampNanoseconds: ms(1_100))
+    await controller.handle(phase: .released, timestampNanoseconds: ms(1_150))
+
+    #expect(dispatcher.commands == [.begin, .finish])
+  }
+
   @Test
   func pendingShortPressFinishesOnlyWhenItsDecisionExpires() async throws {
     let dispatcher = DictationCommandRecorder()

docs/architecture.md

@@ -246,6 +246,20 @@ separate orchestration, presentation state, settings, and failure paths. Shared
 audio, recognition, target, writer, permission, and lifecycle services are
 composed rather than copied.
 
+Every macOS Local AI trigger converges before that orchestration boundary:
+
+| Trigger | Adapter semantics | Shared command destination |
+| --- | --- | --- |
+| Physical Control or exact Binding fallback | Binding-owned Hold or Toggle | Local AI `DictationCommand` dispatcher through the Action executor. |
+| Independent Voice chord | Hold or double-press latch | The same Local AI dispatcher through `VoiceKeyboardTriggerController`. |
+| Menu-bar record action | Phase-derived Record or Stop | The same Local AI dispatcher through the lifecycle-gated application runtime. |
+
+The menu-bar action does not open or activate the main window, preserving the
+external application's target opportunity. Presentation derives availability
+from the Local AI snapshot; the serialized dispatcher and session controller
+own idempotence and reject overlap. No trigger owns recognition, formatting,
+History, retention, target validation, or delivery.
+
 Local AI providers implement `TranscriptRefining`:
 
 - Every adapter declares one immutable `LocalAIProviderCapability` containing

docs/decisions/0029_local_voice_platform_expansion.md

@@ -1,6 +1,6 @@
 # 0029: Local Voice platform expansion
 
-- **Status:** Accepted; macOS M1–M9 implemented
+- **Status:** Accepted; macOS M1–M10 implemented
 - **Date:** 2026-08-25
 - **Amends:**
   [`0001_native_macos_stack.md`](0001_native_macos_stack.md),
@@ -199,3 +199,9 @@ remote-capable adapter before invoking it, validates provider identity, and
 preserves deterministic Edited fallback. Recognition failure after capture
 finalizes playable audio with delivery not attempted and never mutates the
 target.
+
+M10 converges physical Controls, Hold/latch Voice chords, and the menu-bar
+record action on one process-owned Local AI command dispatcher under
+[decision 0034](0034_voice_trigger_convergence.md). Trigger adapters retain only
+their interaction semantics; session lifecycle, ASR, formatting, History,
+retention, target validation, and delivery stay shared.