@hasna/recordings 0.3.13 → 0.4.0

package/src/native/Recordings/RecordingsLib/RecordingEngine.swift

@@ -16,19 +16,23 @@ extension KeyboardShortcuts.Name {
 
 public struct TranscriptionResult: Identifiable, Sendable {
     public let id = UUID()
-    let rawText: String
-    let processedText: String?
-    let timestamp: Date
-    let projectId: String?
-    let projectName: String?
+    public let rawText: String
+    public let processedText: String?
+    public let timestamp: Date
+    public let projectId: String?
+    public let projectName: String?
+    public let captureID: String?
+    public let audioURL: URL?
     public var displayText: String { processedText ?? rawText }
 
-    init(rawText: String, processedText: String?, timestamp: Date, projectId: String?, projectName: String?) {
+    public init(rawText: String, processedText: String?, timestamp: Date, projectId: String?, projectName: String?, captureID: String? = nil, audioURL: URL? = nil) {
         self.rawText = rawText
         self.processedText = processedText
         self.timestamp = timestamp
         self.projectId = projectId
         self.projectName = projectName
+        self.captureID = captureID
+        self.audioURL = audioURL
     }
 }
 
@@ -95,7 +99,7 @@ struct FrontmostAppSnapshot: Equatable, Sendable {
 
 /// The one capability `RecordingEngine` needs from an audio recorder; lets tests run the
 /// production start path without microphone hardware or TCC grants.
-protocol PCMRecordingSource: AnyObject {
+protocol PCMRecordingSource: AnyObject, Sendable {
     func start() throws
     func stop()
 }
@@ -671,7 +675,7 @@ private final class PCMStreamPipe: @unchecked Sendable {
     private let continuation: AsyncStream<Data>.Continuation
     private let processor: Task<Data, Never>
 
-    init(chunkSize: Int, client: RealtimeTranscriptionClient?) {
+    init(chunkSize: Int, client: RealtimeTranscriptionClient?, providerSession: (any RecordingTranscriptionSession)? = nil) {
         var streamContinuation: AsyncStream<Data>.Continuation!
         let stream = AsyncStream<Data>(bufferingPolicy: .unbounded) { continuation in
             streamContinuation = continuation
@@ -682,17 +686,21 @@ private final class PCMStreamPipe: @unchecked Sendable {
             var pendingChunk = Data()
 
             for await data in stream {
+                guard !Task.isCancelled else { break }
                 guard !data.isEmpty else { continue }
                 recordedPCM.append(data)
                 pendingChunk.append(data)
 
                 while pendingChunk.count >= chunkSize {
-                    await client?.sendAudio(pendingChunk.prefixData(count: chunkSize))
+                    let chunk = pendingChunk.prefixData(count: chunkSize)
+                    providerSession?.appendPCM(chunk)
+                    await client?.sendAudio(chunk)
                     pendingChunk.removeFirst(chunkSize)
                 }
             }
 
-            if !pendingChunk.isEmpty {
+            if !Task.isCancelled && !pendingChunk.isEmpty {
+                providerSession?.appendPCM(pendingChunk)
                 await client?.sendAudio(pendingChunk)
             }
             return recordedPCM
@@ -737,7 +745,7 @@ public final class RecordingEngine: ObservableObject {
     @Published public private(set) var isWarmingUpCapture = false
     @Published public var useFnKey: Bool = false {
         didSet {
-            UserDefaults.standard.set(useFnKey, forKey: "useFnKey")
+            preferences.set(useFnKey, forKey: "useFnKey")
             updateFnMonitor()
             refreshTriggerDiagnostics()
         }
@@ -854,9 +862,9 @@ public final class RecordingEngine: ObservableObject {
     private var deliveryBlockedReasonGeneration: UInt64?
     /// Advanced fallback policy (Settings only): when off, every recording is dictated
     /// literally and the classifier is never consulted.
-    @Published public var intentDetectionEnabled: Bool = true {
+    @Published public var intentDetectionEnabled: Bool = false {
         didSet {
-            UserDefaults.standard.set(intentDetectionEnabled, forKey: "intentDetectionEnabled")
+            preferences.set(intentDetectionEnabled, forKey: "intentDetectionEnabled")
         }
     }
     /// Typed Record-page state; views render idle/listening/finalizing/processing/ready/error
@@ -874,13 +882,64 @@ public final class RecordingEngine: ObservableObject {
     @Published public var isTranscribing = false
     @Published public var recordingDuration: TimeInterval = 0
     @Published public var liveTranscriptionText = ""
+    @Published public private(set) var isPaused = false
+    @Published public private(set) var audioLevel: Double = 0
+    @Published public private(set) var recentPastes: [RecentPaste] = []
+    @Published public private(set) var latestAudioPath: String?
+    @Published public var autoPasteEnabled = true {
+        didSet {
+            if usesIsolatedProvider || home == FileManager.default.homeDirectoryForCurrentUser.path {
+                preferences.set(autoPasteEnabled, forKey: "recordingsAutoPaste")
+            }
+        }
+    }
+    private var captureMonitor = CaptureMonitor()
+
+    public func togglePause() {
+        guard isRecording else { return }
+        isPaused.toggle()
+        captureMonitor.setPaused(isPaused)
+        statusMessage = isPaused ? "Paused" : "Recording…"
+    }
+
+    public func clearRecentPastes() { recentPastes.removeAll() }
+
+    #if DEBUG
+    /// Explicitly isolated design review only; does not open a microphone or connection.
+    public func configureVisualPreview() {
+        isRecording = true
+        recordingDuration = 12
+        audioLevel = 0.65
+        liveTranscriptionText = "Here are the key takeaways from today’s meeting…"
+        let samples = [
+            ("com.apple.MobileSMS", "To: James", "Schedule a review for tomorrow at 2 PM…"),
+            ("com.apple.Notes", "New Note", "Here are the key takeaways from today’s…"),
+            ("com.tinyspeck.slackmacgap", "#product", "Can you confirm we’re still on for Friday?"),
+            ("com.apple.mail", "New message", "Sharing the updated timeline and next steps."),
+            ("notion.id", "Page", "Write a short summary of the discussion…")
+        ]
+        recentPastes = zip(samples, ["Messages", "Notes", "Slack", "Mail", "Notion"]).map { sample, name in RecentPaste(text: sample.2, bundleIdentifier: sample.0, appName: name, location: sample.1, status: "Pasted", verified: true) }
+    }
+    #endif
+
     @Published public var transcriptionLanguage = OpenAIAPIKeyStore.defaultLanguage {
         didSet {
-            UserDefaults.standard.set(transcriptionLanguage, forKey: "recordingsLanguage")
-            try? OpenAIAPIKeyStore.saveLanguage(language: transcriptionLanguage, homePath: home)
+            preferences.set(transcriptionLanguage, forKey: "recordingsLanguage")
+            if !usesIsolatedProvider {
+                try? OpenAIAPIKeyStore.saveLanguage(language: transcriptionLanguage, homePath: home)
+            }
         }
     }
 
+    private let preferences: UserDefaults
+    private let preferencesSuiteName: String?
+    private let installsGlobalHandlers: Bool
+    private let transcriptionProvider: (any RecordingTranscriptionProvider)?
+    private var usesIsolatedProvider: Bool { transcriptionProvider != nil }
+    private var providerSession: (any RecordingTranscriptionSession)?
+    private var providerConfiguration: RecordingProviderSessionConfiguration?
+    private var providerCompletionTask: Task<Void, Never>?
+
     private var nativeRecorder: PCMRecordingSource?
     private var recordingTimer: Timer?
     private var activeTrigger: RecordingTrigger?
@@ -891,8 +950,18 @@ public final class RecordingEngine: ObservableObject {
     private var targetAppPid: pid_t?
     private var pasteTargetProcessIdentityByGeneration: [UInt64: PasteTargetProcessIdentity] = [:]
     public var projectStore: ProjectStore?
+    /// The minimal app uses only global cleanup preferences from the legacy settings
+    /// file. Keeping this separate prevents old active projects from tagging new captures.
+    public var globalRecordingPreferences: ProjectStore?
     public var voiceShortcuts: VoiceShortcuts?
 
+    var recordingCleanupPreferences: (prompt: String, mode: String) {
+        if let settings = globalRecordingPreferences?.settings {
+            return (settings.globalSystemPrompt, (PostProcessingMode(rawValue: settings.postProcessingMode) ?? .auto).rawValue)
+        }
+        return (projectStore?.effectiveSystemPrompt ?? "", projectStore?.effectivePostProcessingMode ?? PostProcessingMode.auto.rawValue)
+    }
+
     // MARK: - Injectable boundaries
     // Production defaults perform the real I/O; tests replace them to drive the production
     // start/delivery paths without microphone, Accessibility, network, or CLI access.
@@ -1188,15 +1257,37 @@ public final class RecordingEngine: ObservableObject {
     let home: String
     private var audioDir: String { "\(home)/.hasna/recordings/audio" }
 
-    public init(homePath: String = FileManager.default.homeDirectoryForCurrentUser.path) {
+    public convenience init(homePath: String = FileManager.default.homeDirectoryForCurrentUser.path, installsGlobalHandlers: Bool = true) {
+        self.init(homePath: homePath, preferences: .standard, preferencesSuiteName: nil, installsGlobalHandlers: installsGlobalHandlers, transcriptionProvider: nil)
+    }
+
+    /// Reuses native capture and paste with isolated preferences and an explicit provider.
+    /// No global handlers, legacy keys, environment routing or helper CLI are consulted.
+    public convenience init(configuration: RecordingEngineConfiguration, transcriptionProvider: any RecordingTranscriptionProvider) {
+        // A validated non-empty suite name is supported by Foundation on macOS.
+        let preferences = UserDefaults(suiteName: configuration.preferencesSuiteName)!
+        self.init(homePath: configuration.isolatedHomePath, preferences: preferences, preferencesSuiteName: configuration.preferencesSuiteName, installsGlobalHandlers: false, transcriptionProvider: transcriptionProvider)
+    }
+
+    private init(homePath: String, preferences: UserDefaults, preferencesSuiteName: String?, installsGlobalHandlers: Bool, transcriptionProvider: (any RecordingTranscriptionProvider)?) {
         home = homePath
+        self.preferences = preferences
+        self.preferencesSuiteName = preferencesSuiteName
+        self.installsGlobalHandlers = installsGlobalHandlers
+        self.transcriptionProvider = transcriptionProvider
         try? FileManager.default.createDirectory(atPath: audioDir, withIntermediateDirectories: true)
         log("RecordingEngine init; microphone=\(microphonePermissionLabel); accessibility=\(accessibilityPermissionLabel)")
 
         // Load preferences
-        intentDetectionEnabled = UserDefaults.standard.object(forKey: "intentDetectionEnabled") as? Bool ?? true
-        transcriptionLanguage = OpenAIAPIKeyStore.loadLanguage(homePath: home)
-        useFnKey = UserDefaults.standard.object(forKey: "useFnKey") as? Bool ?? false
+        if usesIsolatedProvider || home == FileManager.default.homeDirectoryForCurrentUser.path {
+            autoPasteEnabled = storedPreference("recordingsAutoPaste") as? Bool ?? true
+        }
+        intentDetectionEnabled = storedPreference("intentDetectionEnabled") as? Bool ?? false
+        transcriptionLanguage = usesIsolatedProvider
+            ? (storedPreference("recordingsLanguage") as? String ?? "en")
+            : OpenAIAPIKeyStore.loadLanguage(homePath: home)
+        useFnKey = storedPreference("useFnKey") as? Bool ?? false
+        guard installsGlobalHandlers else { statusMessage = "Ready"; return }
         if KeyboardShortcuts.getShortcut(for: .toggleRecording) == nil {
             KeyboardShortcuts.setShortcut(.init(.f5), for: .toggleRecording)
         }
@@ -1268,6 +1359,15 @@ public final class RecordingEngine: ObservableObject {
         updateStatus()
     }
 
+    private func storedPreference(_ key: String) -> Any? {
+        if let preferencesSuiteName {
+            // UserDefaults.object also consults process/global domains. A separate app's
+            // engine reads only its explicitly named persistent domain.
+            return preferences.persistentDomain(forName: preferencesSuiteName)?[key]
+        }
+        return preferences.object(forKey: key)
+    }
+
     public var microphonePermissionLabel: String {
         switch AVCaptureDevice.authorizationStatus(for: .audio) {
         case .authorized:
@@ -1331,6 +1431,7 @@ public final class RecordingEngine: ObservableObject {
     /// was indistinguishable from a working one. Log the resolved binding so "is the
     /// trigger armed, and to what" is answerable from the log alone.
     public func logResolvedTrigger() {
+        guard installsGlobalHandlers else { return }
         let stored = KeyboardShortcuts.getShortcut(for: .toggleRecording)
         let bound = stored
             .map { "carbonKeyCode=\($0.carbonKeyCode) carbonModifiers=\($0.carbonModifiers)" }
@@ -1406,6 +1507,7 @@ public final class RecordingEngine: ObservableObject {
     }
 
     private func updateFnMonitor(allowAutomaticPrompt: Bool = true) {
+        guard installsGlobalHandlers else { return }
         // Decided as a local first, then handed to the single writer once. Assigning the
         // published property from each branch is how the per-source erasure bug got in.
         var reason: String?
@@ -1512,6 +1614,7 @@ public final class RecordingEngine: ObservableObject {
     /// Re-evaluate every trigger's health, push it to the UI, and record it. The one entry
     /// point callers should use after anything changes a binding.
     public func refreshTriggerDiagnostics() {
+        guard installsGlobalHandlers else { updateStatus(); return }
         refreshHotkeyDiagnostics()
         updateStatus()
         logResolvedTrigger()
@@ -1702,7 +1805,7 @@ public final class RecordingEngine: ObservableObject {
         let shouldCaptureSelection = Self.shouldCaptureSelection(
             targetPid: targetAppPid,
             accessibilityTrusted: accessibilityTrustCheck(),
-            intentDetectionEnabled: intentDetectionEnabled
+            intentDetectionEnabled: !usesIsolatedProvider && intentDetectionEnabled
         )
         let capturePid = targetAppPid
         let captureSelection = selectionCapture
@@ -1722,9 +1825,11 @@ public final class RecordingEngine: ObservableObject {
         // recording pipeline awaits this context only after the recorder has stopped.
         let generation = recordingGeneration
         let projectStore = projectStore
+        let cleanupPreferences = recordingCleanupPreferences
         let targetBundleIdentifierForProjects = targetAppBundleIdentifier
         let transcriptionLanguageAtStart = transcriptionLanguage
-        let intentDetectionEnabledAtStart = intentDetectionEnabled
+        let intentDetectionEnabledAtStart = !usesIsolatedProvider && intentDetectionEnabled
+        let usesIsolatedProvider = usesIsolatedProvider
         let homePath = home
         let startContext = Task { @MainActor [weak self] () -> RecordingStartResolvedContext in
             let axSnapshot = await axSnapshotTask.value
@@ -1748,7 +1853,9 @@ public final class RecordingEngine: ObservableObject {
                     self.log("project synchronization degraded; continuing capture: \(warning)")
                 }
             }
-            let modelSelection = OpenAIAPIKeyStore.loadProcessingModelSelection(homePath: homePath)
+            let modelSelection = usesIsolatedProvider
+                ? ProcessingModelSelection(transcriptionPrompt: "", transcriptionModel: "", transcriberModel: "", enhancementModel: "", intentModel: "", enhanceTriggersJSON: "[]", keywordTransformsJSON: "{}")
+                : OpenAIAPIKeyStore.loadProcessingModelSelection(homePath: homePath)
             return RecordingStartResolvedContext(
                 selectionToken: axSnapshot.selectionToken,
                 canonicalProjectId: projectStore?.activeCanonicalProjectIdForRecording,
@@ -1756,8 +1863,8 @@ public final class RecordingEngine: ObservableObject {
                 activeProjectName: projectStore?.activeProject?.name,
                 processing: RecordingProcessingConfiguration(
                     transcriptionPrompt: modelSelection.transcriptionPrompt,
-                    transcriberPrompt: projectStore?.effectiveSystemPrompt ?? "",
-                    postProcessingMode: projectStore?.effectivePostProcessingMode ?? PostProcessingMode.auto.rawValue,
+                    transcriberPrompt: cleanupPreferences.prompt,
+                    postProcessingMode: cleanupPreferences.mode,
                     transcriptionLanguage: transcriptionLanguageAtStart,
                     transcriptionModel: modelSelection.transcriptionModel,
                     transcriberModel: modelSelection.transcriberModel,
@@ -1945,7 +2052,26 @@ public final class RecordingEngine: ObservableObject {
     }
 
     private func startNativeRecording(startContext: Task<RecordingStartResolvedContext, Never>) {
-        let apiKey = openAIAPIKeyProvider()
+        let apiKey = usesIsolatedProvider ? "" : openAIAPIKeyProvider()
+        if let transcriptionProvider {
+            let generation = recordingGeneration
+            let configuration = RecordingProviderSessionConfiguration(captureID: UUID().uuidString, language: transcriptionLanguage)
+            do {
+                providerSession = try transcriptionProvider.makeSession(configuration: configuration) { [weak self] text in
+                    Task { @MainActor [weak self] in
+                        guard let self, self.recordingGeneration == generation,
+                              self.captureIsActive || self.isTranscribing else { return }
+                        self.liveTranscriptionText = text
+                    }
+                }
+                providerConfiguration = configuration
+            } catch {
+                resetRecordingIntent()
+                statusMessage = error.localizedDescription
+                flowPhase = .failed(statusMessage)
+                return
+            }
+        }
         let captureConfiguration = RecordingCaptureConfiguration(
             targetAppBundleIdentifier: targetAppBundleIdentifier,
             targetAppPid: targetAppPid,
@@ -1964,7 +2090,7 @@ public final class RecordingEngine: ObservableObject {
             : RealtimeTranscriptionClient(apiKey: apiKey, homePath: home)
         realtimeClient = client
 
-        let streamPipe = PCMStreamPipe(chunkSize: 4_800, client: client)
+        let streamPipe = PCMStreamPipe(chunkSize: 4_800, client: client, providerSession: providerSession)
         pcmStreamPipe = streamPipe
         let homePath = home
         let captureGeneration = recordingGeneration
@@ -1972,7 +2098,12 @@ public final class RecordingEngine: ObservableObject {
             self?.confirmCaptureIsLive(generation: generation)
         }
         let firstChunkLogged = LockedFlag()
+        let monitor = CaptureMonitor()
+        captureMonitor = monitor
+        isPaused = false
+        audioLevel = 0
         let recorder = recorderFactory { data in
+            guard monitor.admit(data) else { return }
             if firstChunkLogged.take() {
                 NativeAppLog.write("native recorder received first PCM chunk bytes=\(data.count)", homePath: homePath)
                 // The first sample is the only honest signal that this recording exists.
@@ -2004,10 +2135,14 @@ public final class RecordingEngine: ObservableObject {
 
             recordingTimer = Timer.scheduledTimer(withTimeInterval: 0.1, repeats: true) { [weak self] _ in
                 Task { @MainActor [weak self] in
-                    self?.recordingDuration += 0.1
+                    guard let self else { return }
+                    let sample = monitor.snapshot()
+                    self.recordingDuration = sample.duration
+                    self.audioLevel = sample.level
                 }
             }
         } catch {
+            cancelProviderSession()
             log("native recorder failed error=\(error.localizedDescription)")
             // Unreachable today — nothing between `recorder.start()` and `isWarmingUpCapture`
             // can throw — but a warming flag left set here wedges the engine permanently: the
@@ -2049,6 +2184,7 @@ public final class RecordingEngine: ObservableObject {
     private func abandonWarmingCapture(reason: String, alert: RecordingAttemptAlert?) {
         guard isWarmingUpCapture else { return }
         log("capture abandoned before first audio reason=\(reason)")
+        cancelProviderSession()
         // Supersede the attempt so every completion still bound to it — a queued first-chunk
         // confirmation, the resolved start context — is stale and cannot apply.
         recordingGeneration &+= 1
@@ -2154,6 +2290,18 @@ public final class RecordingEngine: ObservableObject {
     // MARK: - Cancel (discard without transcribing)
 
     public func cancelRecording() {
+        if usesIsolatedProvider && isTranscribing {
+            pipelineDeliveryGate.abandonPipeline(recordingGeneration)
+            recordingGeneration &+= 1
+            cancelProviderSession()
+            isTranscribing = false
+            liveTranscriptionText = ""
+            recordedPCM.removeAll(keepingCapacity: true)
+            activeAudioPath = nil
+            resetRecordingIntent()
+            updateStatus()
+            return
+        }
         // Discard during warm-up: identical teardown, but the user asked for it, so the glyph
         // stays quiet.
         if isWarmingUpCapture {
@@ -2162,6 +2310,7 @@ public final class RecordingEngine: ObservableObject {
         }
         guard isRecording else { return }
         log("cancelRecording")
+        cancelProviderSession()
 
         recordingTimer?.invalidate()
         recordingTimer = nil
@@ -2178,6 +2327,9 @@ public final class RecordingEngine: ObservableObject {
         pcmStreamPipe = nil
 
         isRecording = false
+        isPaused = false
+        audioLevel = 0
+        recordingDuration = 0
         isTranscribing = false
         liveTranscriptionText = ""
         recordedPCM.removeAll(keepingCapacity: true)
@@ -2191,6 +2343,89 @@ public final class RecordingEngine: ObservableObject {
 
     // MARK: - Stop & Transcribe
 
+    private func cancelProviderSession() {
+        providerCompletionTask?.cancel()
+        providerCompletionTask = nil
+        providerSession?.cancel()
+        providerSession = nil
+        providerConfiguration = nil
+    }
+
+    /// The provider path shares capture, WAV writing and verified paste delivery with the
+    /// legacy recorder. It never enters the legacy CLI, credential or intent-model paths.
+    private func stopWithProvider(
+        recorder: PCMRecordingSource?, pipe: PCMStreamPipe?,
+        session: any RecordingTranscriptionSession,
+        configuration: RecordingProviderSessionConfiguration, audioPath: String?,
+        targetAppBundleIdentifier: String?, targetAppPid: pid_t?,
+        pipelineGeneration: UInt64, pipelineTrace: RecordingPipelineTrace
+    ) {
+        providerCompletionTask = Task { [weak self] in
+            // Shutdown and drain belong to this capture even if the user cancels and starts
+            // another one before the native input tap has stopped.
+            await Task.detached(priority: .userInitiated) { recorder?.stop() }.value
+            let pcm = await pipe?.finish() ?? Data()
+            guard !Task.isCancelled, let self,
+                  self.recordingGeneration == pipelineGeneration else { return }
+            do {
+                guard !pcm.isEmpty, let audioPath else { throw RecordingProviderError.noAudio }
+                let audioURL = URL(fileURLWithPath: audioPath)
+                try await Task.detached(priority: .userInitiated) {
+                    try Self.writeWAV(pcmData: pcm, sampleRate: 24_000, channelCount: 1, bitsPerSample: 16, to: audioURL)
+                }.value
+                try Task.checkCancellation()
+                guard self.recordingGeneration == pipelineGeneration else { return }
+                let duration = Double(pcm.count) / 48_000
+                self.recordingDuration = duration
+                let result = try await session.finish(RecordingTranscriptionRequest(
+                    captureID: configuration.captureID, audioURL: audioURL,
+                    duration: duration, language: configuration.language
+                ))
+                try Task.checkCancellation()
+                guard self.recordingGeneration == pipelineGeneration else { return }
+                let rawText = result.rawText.trimmingCharacters(in: .whitespacesAndNewlines)
+                let processed = result.processedText?.trimmingCharacters(in: .whitespacesAndNewlines)
+                let text = (processed?.isEmpty == false ? processed : nil) ?? rawText
+                guard !text.isEmpty else { throw RecordingProviderError.emptyTranscript }
+                self.isTranscribing = false
+                self.liveTranscriptionText = ""
+                self.activeAudioPath = nil
+                self.providerSession = nil
+                self.providerConfiguration = nil
+                self.providerCompletionTask = nil
+                // Publication precedes delivery. Consumers may persist asynchronously without
+                // delaying paste; this is an in-memory result, not a persistence receipt.
+                self.recentTranscriptions.insert(TranscriptionResult(
+                    rawText: rawText, processedText: processed?.isEmpty == false ? processed : nil,
+                    timestamp: Date(), projectId: nil, projectName: nil,
+                    captureID: configuration.captureID, audioURL: audioURL
+                ), at: 0)
+                if self.recentTranscriptions.count > 20 { self.recentTranscriptions.removeLast() }
+                guard self.pipelineDeliveryGate.claimDelivery(for: pipelineGeneration) else { return }
+                self.pasteIntoFrontApp(
+                    text, targetAppBundleIdentifier: targetAppBundleIdentifier,
+                    targetAppPid: targetAppPid, restoreClipboard: true,
+                    deliveryKind: .ordinaryDictation, captureID: configuration.captureID, pipelineTrace: pipelineTrace,
+                    pipelineGeneration: pipelineGeneration, deliveryCompleted: nil
+                )
+            } catch {
+                guard self.recordingGeneration == pipelineGeneration, !Task.isCancelled else { return }
+                session.cancel()
+                self.providerSession = nil
+                self.providerConfiguration = nil
+                self.providerCompletionTask = nil
+                self.activeAudioPath = nil
+                self.pipelineDeliveryGate.abandonPipeline(pipelineGeneration)
+                // Do not log provider errors: third-party error text can contain a token or
+                // request URL. The host UI receives the localized description for diagnosis.
+                self.isTranscribing = false
+                self.liveTranscriptionText = ""
+                self.statusMessage = error.localizedDescription
+                self.flowPhase = .failed(self.statusMessage)
+            }
+        }
+    }
+
     public func stopAndTranscribe() {
         // Stop during the warm-up window has nothing to transcribe — the microphone was opened
         // but has not delivered a sample. Abandon visibly instead of spending a transcription
@@ -2208,12 +2443,12 @@ public final class RecordingEngine: ObservableObject {
 
         let recorder = nativeRecorder
         nativeRecorder = nil
-        recorder?.stop()
 
         isRecording = false
         isTranscribing = true
 
         guard let captureConfiguration = activeCaptureConfiguration else {
+            recorder?.stop()
             realtimeClient?.stop()
             realtimeClient = nil
             streamingTask?.cancel()
@@ -2230,6 +2465,9 @@ public final class RecordingEngine: ObservableObject {
         let targetAppBundleIdentifier = captureConfiguration.targetAppBundleIdentifier
         let targetAppPid = captureConfiguration.targetAppPid
         let audioPath = activeAudioPath
+        latestAudioPath = audioPath
+        isPaused = false
+        audioLevel = 0
         let pcmStreamPipe = pcmStreamPipe
         let client = realtimeClient
         let pipelineGeneration = recordingGeneration
@@ -2239,9 +2477,23 @@ public final class RecordingEngine: ObservableObject {
         resetRecordingIntent()
         self.pcmStreamPipe = nil
 
+        if let providerSession, let providerConfiguration {
+            stopWithProvider(
+                recorder: recorder, pipe: pcmStreamPipe, session: providerSession,
+                configuration: providerConfiguration, audioPath: audioPath,
+                targetAppBundleIdentifier: targetAppBundleIdentifier, targetAppPid: targetAppPid,
+                pipelineGeneration: pipelineGeneration, pipelineTrace: pipelineTrace
+            )
+            return
+        }
+
         Task {
+            // AVAudioEngine shutdown can block for hundreds of milliseconds. Keep
+            // receiving realtime text and repainting while capture drains completely.
+            await Task.detached(priority: .userInitiated) { recorder?.stop() }.value
             if let pcmStreamPipe {
                 self.recordedPCM = await pcmStreamPipe.finish()
+                self.recordingDuration = Double(self.recordedPCM.count) / 48_000
             }
             self.log(pipelineTrace.message(
                 stage: "pcm_drain_complete",
@@ -3969,7 +4221,8 @@ public final class RecordingEngine: ObservableObject {
         _ text: String,
         targetAppBundleIdentifier: String? = nil,
         targetAppPid: pid_t? = nil,
-        restoreClipboard: Bool = false
+        restoreClipboard: Bool = false,
+        captureID: String? = nil
     ) {
         pasteIntoFrontApp(
             text,
@@ -3977,6 +4230,7 @@ public final class RecordingEngine: ObservableObject {
             targetAppPid: targetAppPid,
             restoreClipboard: restoreClipboard,
             deliveryKind: .manualPaste,
+            captureID: captureID,
             pipelineTrace: nil,
             pipelineGeneration: nil,
             deliveryCompleted: nil
@@ -3989,6 +4243,7 @@ public final class RecordingEngine: ObservableObject {
         targetAppPid: pid_t? = nil,
         restoreClipboard: Bool = false,
         deliveryKind: PasteDeliveryKind,
+        captureID: String? = nil,
         selectionToken: AccessibilitySelectionToken? = nil,
         pipelineTrace: RecordingPipelineTrace?,
         pipelineGeneration: UInt64?,
@@ -4007,6 +4262,11 @@ public final class RecordingEngine: ObservableObject {
             deliveryCompleted?()
             return
         }
+        if !autoPasteEnabled && deliveryKind != .manualPaste {
+            updateDeliveryStatus("Transcript ready — auto-paste is off", kind: .success, pipelineGeneration: pipelineGeneration)
+            deliveryCompleted?()
+            return
+        }
         if let pasteInterceptorForTesting {
             pasteInterceptorForTesting(text, deliveryKind, pipelineGeneration)
             deliveryCompleted?()
@@ -4176,6 +4436,14 @@ public final class RecordingEngine: ObservableObject {
                     detail: "chars=\(transaction.text.count)"
                 ))
             }
+            let verified = Self.pasteTraceStage(for: outcome) == "paste_delivery_confirmed"
+            let deliveryStatus = Self.recentPasteDeliveryStatus(for: outcome)
+            self.recentPastes.insert(RecentPaste(
+                text: transaction.text, bundleIdentifier: app.bundleIdentifier, appName: app.localizedName ?? "Application",
+                location: "Focused field", status: verified ? "Pasted" : "Unconfirmed", verified: verified,
+                captureID: captureID, deliveryStatus: deliveryStatus
+            ), at: 0)
+            if self.recentPastes.count > 50 { self.recentPastes.removeLast() }
             deliveryCompleted?()
             let message = switch outcome {
             case .pasted: "Pasted (\(transaction.text.count) chars)"
@@ -4521,6 +4789,15 @@ public final class RecordingEngine: ObservableObject {
     /// Pipeline-timing stage name. `paste_posted` used to be emitted for every posted
     /// keystroke, which made the timing trace read like a delivery record; the three delivery
     /// verdicts are now distinct stages.
+    nonisolated static func recentPasteDeliveryStatus(for outcome: PasteDeliveryOutcome) -> RecentPasteDeliveryStatus {
+        switch outcome {
+        case .pasted: .confirmed
+        case .deliveredUnverified: .unconfirmed
+        case .deliveryNotObserved, .secureInputActive, .targetUnavailable,
+             .clipboardOwnershipLost, .clipboardWriteFailed, .eventPostFailed: .notDelivered
+        }
+    }
+
     nonisolated static func pasteTraceStage(for outcome: PasteDeliveryOutcome) -> String {
         switch outcome {
         case .pasted: "paste_delivery_confirmed"
@@ -4792,14 +5069,17 @@ enum CLIRunner: Sendable {
         _ args: [String],
         home: String,
         timeout: TimeInterval = 120,
-        totalWallClockBudget: TimeInterval? = nil
+        totalWallClockBudget: TimeInterval? = nil,
+        environment suppliedEnvironment: [String: String]? = nil
     ) -> String {
         let command = resolveCommand(home: home)
         let arguments = command.argumentsPrefix + args
-        let environment = ProcessInfo.processInfo.environment.merging([
-            "PATH": "\(home)/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
-        ]) { _, new in new }
         do {
+            let environment = try suppliedEnvironment ?? ServiceAPIConfiguration.childEnvironment(
+                base: OpenAIAPIKeyStore.childEnvironment(base: ProcessInfo.processInfo.environment.merging([
+                    "PATH": "\(home)/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
+                ]) { _, new in new }, homePath: home)
+            )
             let output = try runExecutable(
                 command.executable,
                 arguments: arguments,
@@ -5611,7 +5891,7 @@ enum CLIRunner: Sendable {
         }
     }
 
-    static func parseError(_ output: String) -> String? {
+    static func parseError(_ output: String, serviceAPI: Bool = false) -> String? {
         let trimmed = output.trimmingCharacters(in: .whitespacesAndNewlines)
         guard trimmed.hasPrefix("ERROR:") else { return nil }
         let message = NativeErrorSanitizer.sanitize(
@@ -5620,10 +5900,12 @@ enum CLIRunner: Sendable {
         let lowercased = message.lowercased()
         if lowercased.contains("401") || lowercased.contains("incorrect api key")
             || lowercased.contains("invalid_api_key") || lowercased.contains("invalid or expired") {
+            if serviceAPI { return "Recordings API authentication failed — check the API connection in Settings" }
             return "OpenAI API key invalid or expired — update it in Recordings Settings"
         }
         if lowercased.contains("429") || lowercased.contains("exceeded your current quota")
             || lowercased.contains("insufficient_quota") || lowercased.contains("quota exceeded") {
+            if serviceAPI { return "Recordings API request limit reached — try again later" }
             return "OpenAI quota exceeded — check the OpenAI account billing"
         }
         if message.contains("OpenAI API key not configured") {