@hasna/recordings 0.3.13 → 0.5.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,22 @@ 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)
+                // Providers need every admitted packet before a pause can settle.
+                // Only the legacy realtime client waits for network-sized chunks.
+                providerSession?.appendPCM(data)
                 pendingChunk.append(data)
 
                 while pendingChunk.count >= chunkSize {
-                    await client?.sendAudio(pendingChunk.prefixData(count: chunkSize))
+                    let chunk = pendingChunk.prefixData(count: chunkSize)
+                    await client?.sendAudio(chunk)
                     pendingChunk.removeFirst(chunkSize)
                 }
             }
 
-            if !pendingChunk.isEmpty {
+            if !Task.isCancelled && !pendingChunk.isEmpty {
                 await client?.sendAudio(pendingChunk)
             }
             return recordedPCM
@@ -737,7 +746,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 +863,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 +883,68 @@ 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>?
+    /// Injection keeps persistence ordering testable without changing the public file contract.
+    var providerAudioWriter: @Sendable (Data, URL) throws -> Void = { pcm, url in
+        try RecordingEngine.writeWAV(pcmData: pcm, sampleRate: 24_000, channelCount: 1, bitsPerSample: 16, to: url)
+    }
+
     private var nativeRecorder: PCMRecordingSource?
     private var recordingTimer: Timer?
     private var activeTrigger: RecordingTrigger?
@@ -889,10 +953,21 @@ public final class RecordingEngine: ObservableObject {
     private var fnKeyIsDown = false
     private var targetAppBundleIdentifier: String?
     private var targetAppPid: pid_t?
+    private var frozenPasteTargetsByGeneration: [UInt64: RecordingPasteTargetSelection] = [:]
     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.
@@ -911,6 +986,12 @@ public final class RecordingEngine: ObservableObject {
             launchDate: app.launchDate
         )
     }
+    var pasteTargetApplicationLookup: (pid_t) -> PasteApplicationObservation? = {
+        NSRunningApplication(processIdentifier: $0).map(PasteApplicationObservation.init)
+    }
+    var pasteFallbackWriter: (String) -> Bool = { text in
+        RecordingEngine.writeClipboardPreservingOnFailure(text, to: .general)
+    }
     var recorderFactory: (@escaping @Sendable (Data) -> Void) -> PCMRecordingSource = {
         NativePCMRecorder(onPCM: $0)
     }
@@ -921,12 +1002,15 @@ public final class RecordingEngine: ObservableObject {
         RecordingEngine.focusedWindowTitle(pid: $0)
     }
     var commandCLI: @Sendable (_ args: [String], _ home: String, _ timeout: TimeInterval) -> String = { args, home, ceiling in
-        // The caller's timeout is the public ceiling on *observable* wall time. CLIRunner's
+        // The caller supplies the remaining public budget after queue admission. CLIRunner's
         // total deadline (execution, termination grace, kill grace, pipe drain) sits a full
         // return margin below it: spawn setup, waitid poll granularity, capture shutdown,
         // and the hop back to the caller all run outside CLIRunner's clamped waits and must
         // fit inside the reserved margin.
         let cliDeadline = ceiling - RecordingEngine.commandRewriteReturnMargin
+        guard cliDeadline > CLIRunner.wallClockCleanupReserve else {
+            return "ERROR: \(CLIRunner.ExecutionError.deadlineExhausted.localizedDescription)"
+        }
         return CLIRunner.run(args, home: home, timeout: cliDeadline, totalWallClockBudget: cliDeadline)
     }
     /// Resolves and revalidates the frozen rewrite target immediately before a rewrite:
@@ -1158,6 +1242,23 @@ public final class RecordingEngine: ObservableObject {
     /// *observable* rewrite time under the public ceiling even when the execution window,
     /// termination grace, and pipe drain all run to exhaustion.
     nonisolated static let commandRewriteReturnMargin: TimeInterval = 1
+
+    /// Create this operation synchronously before awaiting the blocking queue: creating
+    /// its deadline inside the submitted closure would give delayed work a fresh budget.
+    nonisolated static func makeCommandRewriteOperation(
+        args: [String],
+        home: String,
+        runCLI: @escaping @Sendable ([String], String, TimeInterval) -> String,
+        deadline: CLIRunner.WallClockDeadline = .init(after: commandRewriteTimeout)
+    ) -> @Sendable () -> String {
+        return {
+            let remaining = min(commandRewriteTimeout, deadline.remaining())
+            guard remaining > commandRewriteReturnMargin + CLIRunner.wallClockCleanupReserve else {
+                return "ERROR: \(CLIRunner.ExecutionError.deadlineExhausted.localizedDescription)"
+            }
+            return runCLI(args, home, remaining)
+        }
+    }
     /// Wait before each read-back of the target app's focused field. The window server
     /// delivers the posted keystroke asynchronously and the app then does its own work, so a
     /// read taken on the posting turn would report "unchanged" for a paste that is simply
@@ -1188,15 +1289,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 +1391,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 +1463,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 +1539,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 +1646,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()
@@ -1635,7 +1770,8 @@ public final class RecordingEngine: ObservableObject {
 
     // MARK: - Start Recording (Streaming)
 
-    public func startRecording(trigger: RecordingTrigger = .manual) {
+    public func startRecording(trigger: RecordingTrigger = .manual,
+                               pasteTarget: RecordingPasteTargetSelection = .frontmostApplication) {
         guard Self.canBeginRecording(
             isRecording: isRecording,
             isTranscribing: isTranscribing,
@@ -1652,11 +1788,12 @@ public final class RecordingEngine: ObservableObject {
         }
         log("startRecording trigger=\(trigger) microphoneStatus=\(microphoneAuthorization().rawValue) accessibility=\(accessibilityTrustCheck())")
         recordingGeneration &+= 1
-        if pasteTargetProcessIdentityByGeneration.count >= 32 {
+        if pasteTargetProcessIdentityByGeneration.count >= 32 || frozenPasteTargetsByGeneration.count >= 32 {
             let oldestRetainedGeneration = recordingGeneration > 16 ? recordingGeneration - 16 : 0
             pasteTargetProcessIdentityByGeneration = pasteTargetProcessIdentityByGeneration.filter {
                 $0.key >= oldestRetainedGeneration
             }
+            frozenPasteTargetsByGeneration = frozenPasteTargetsByGeneration.filter { $0.key >= oldestRetainedGeneration }
         }
         activeTrigger = trigger
         keyboardShortcutIsDown = trigger == .keyboardShortcut
@@ -1675,7 +1812,19 @@ public final class RecordingEngine: ObservableObject {
         setBlockedReason(nil, for: .delivery)
 
         let myPID = ProcessInfo.processInfo.processIdentifier
-        let frontmostApp = frontmostAppSnapshot()
+        let frontmostApp: FrontmostAppSnapshot?
+        switch pasteTarget {
+        case .frontmostApplication:
+            frontmostApp = frontmostAppSnapshot()
+        case .frozen(let target):
+            // Keep explicit nil distinct from omission, including when a previously
+            // observed target terminated between the host's snapshot and this call.
+            frozenPasteTargetsByGeneration[recordingGeneration] = pasteTarget
+            if let target, target.processIdentifier != myPID,
+               let app = pasteTargetApplicationLookup(target.processIdentifier), target.matches(app) {
+                frontmostApp = FrontmostAppSnapshot(pid: target.processIdentifier, bundleIdentifier: target.bundleIdentifier, launchDate: target.launchDate)
+            } else { frontmostApp = nil }
+        }
         let isOwnApp = frontmostApp?.pid == myPID
         targetAppBundleIdentifier = isOwnApp ? nil : frontmostApp?.bundleIdentifier
         targetAppPid = isOwnApp ? nil : frontmostApp?.pid
@@ -1695,26 +1844,28 @@ public final class RecordingEngine: ObservableObject {
         // The selection is still frozen for every recording (not only an exposed "command
         // mode"), so a later command decision can only ever act on the exact text and
         // element that were selected when the user started speaking. The Accessibility IPC
-        // that reads it runs on a detached task, concurrently with recorder start: the
-        // microphone must never wait on a beachballing target app, and the MainActor stays
+        // that reads it runs on a blocking-work queue, concurrently with recorder start:
+        // neither the microphone nor a cooperative worker waits on a beachballing app. The MainActor stays
         // free to process the key-up that stops the recording. Skipped entirely when intent
         // detection is off — no command route exists to consume it.
         let shouldCaptureSelection = Self.shouldCaptureSelection(
             targetPid: targetAppPid,
             accessibilityTrusted: accessibilityTrustCheck(),
-            intentDetectionEnabled: intentDetectionEnabled
+            intentDetectionEnabled: !usesIsolatedProvider && intentDetectionEnabled
         )
         let capturePid = targetAppPid
         let captureSelection = selectionCapture
         let windowTitleLookup = focusedWindowTitleLookup
         let windowTitlePid = frontmostApp?.pid
         let axSnapshotTask = Task.detached(priority: .userInitiated) { () -> RecordingStartAXSnapshot in
-            let selectionToken = shouldCaptureSelection ? capturePid.flatMap { captureSelection($0) } : nil
-            let focusedWindowTitle = windowTitlePid.flatMap { windowTitleLookup($0) }
-            return RecordingStartAXSnapshot(
-                selectionToken: selectionToken,
-                focusedWindowTitle: focusedWindowTitle
-            )
+            await BlockingOperation.run {
+                let selectionToken = shouldCaptureSelection ? capturePid.flatMap { captureSelection($0) } : nil
+                let focusedWindowTitle = windowTitlePid.flatMap { windowTitleLookup($0) }
+                return RecordingStartAXSnapshot(
+                    selectionToken: selectionToken,
+                    focusedWindowTitle: focusedWindowTitle
+                )
+            }
         }
 
         // Project auto-selection and the processing configuration resolve with the
@@ -1722,9 +1873,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 +1901,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 +1911,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 +2100,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 +2138,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 +2146,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 +2183,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 +2232,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 +2338,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 +2358,7 @@ public final class RecordingEngine: ObservableObject {
         }
         guard isRecording else { return }
         log("cancelRecording")
+        cancelProviderSession()
 
         recordingTimer?.invalidate()
         recordingTimer = nil
@@ -2178,6 +2375,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 +2391,98 @@ 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 }
+            var timings = [pipelineTrace.message(stage: "pcm_drain_complete", detail: "pcm_bytes=\(pcm.count)")]
+            // Capture timestamps now, but batch their I/O after completion. Instrumentation
+            // must not add a log-file write before the early network commit or WAV write.
+            defer { self.log(timings.joined(separator: "\n")) }
+            do {
+                guard !pcm.isEmpty, let audioPath else { throw RecordingProviderError.noAudio }
+                let audioURL = URL(fileURLWithPath: audioPath)
+                session.inputEnded()
+                timings.append(pipelineTrace.message(stage: "provider_input_ended"))
+                let writeAudio = self.providerAudioWriter
+                try await Task.detached(priority: .userInitiated) {
+                    try writeAudio(pcm, audioURL)
+                }.value
+                try Task.checkCancellation()
+                guard self.recordingGeneration == pipelineGeneration else { return }
+                timings.append(pipelineTrace.message(stage: "wav_write_complete"))
+                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 }
+                timings.append(pipelineTrace.message(stage: "provider_finish_complete"))
+                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 +2500,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 +2522,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 +2534,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",
@@ -3815,10 +4124,12 @@ public final class RecordingEngine: ObservableObject {
                 activeProjectId: canonicalProjectId,
                 processingConfiguration: processingConfiguration
             )
-            let runCLI = self.commandCLI
-            let result = await Task.detached {
-                runCLI(rewriteArguments, homePath, Self.commandRewriteTimeout)
-            }.value
+            let rewriteOperation = Self.makeCommandRewriteOperation(
+                args: rewriteArguments,
+                home: homePath,
+                runCLI: self.commandCLI
+            )
+            let result = await BlockingOperation.run(rewriteOperation)
             if self.canOwnBusyState(pipelineGeneration: pipelineGeneration) {
                 self.isTranscribing = false
                 self.liveTranscriptionText = ""
@@ -3969,7 +4280,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 +4289,7 @@ public final class RecordingEngine: ObservableObject {
             targetAppPid: targetAppPid,
             restoreClipboard: restoreClipboard,
             deliveryKind: .manualPaste,
+            captureID: captureID,
             pipelineTrace: nil,
             pipelineGeneration: nil,
             deliveryCompleted: nil
@@ -3989,6 +4302,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,18 +4321,31 @@ 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?()
             return
         }
-        let pb = NSPasteboard.general
+        if let generation = pipelineGeneration, frozenPasteTargetsByGeneration[generation] != nil,
+           pasteTargetProcessIdentityByGeneration[generation] == nil {
+            completeUnavailablePaste(text, deliveryKind: deliveryKind, captureID: captureID,
+                                     pipelineGeneration: pipelineGeneration)
+            deliveryCompleted?()
+            return
+        }
         var previousClipboard: ClipboardSnapshot?
 
         let accessibility = protectedOperationTrust()
         guard accessibility.trusted else {
             let shouldCopy = Self.shouldCopyPasteFallback(deliveryKind: deliveryKind)
-            let copied = shouldCopy && Self.writeClipboardPreservingOnFailure(text, to: pb)
+            let copied = shouldCopy && pasteFallbackWriter(text)
+            appendUndeliveredPaste(text: text, copied: copied, captureID: captureID,
+                                   pipelineGeneration: pipelineGeneration, fallbackBundle: targetAppBundleIdentifier)
             log("paste blocked by accessibility permission")
             let message = if deliveryKind == .commandRewrite {
                 "Paste cancelled because Accessibility permission changed"
@@ -4046,18 +4373,8 @@ public final class RecordingEngine: ObservableObject {
         )
 
         guard let app = targetApp else {
-            let shouldCopy = Self.shouldCopyPasteFallback(deliveryKind: deliveryKind)
-            let copied = shouldCopy && Self.writeClipboardPreservingOnFailure(text, to: pb)
-            log("paste target app not found")
-            updateDeliveryStatus(
-                deliveryKind == .commandRewrite
-                    ? "Paste cancelled because the target app is unavailable"
-                    : copied
-                        ? "Copied — no target app found"
-                        : "Transcription ready, but the clipboard could not be updated",
-                kind: .failure,
-                pipelineGeneration: pipelineGeneration
-            )
+            completeUnavailablePaste(text, deliveryKind: deliveryKind, captureID: captureID,
+                                     pipelineGeneration: pipelineGeneration, fallbackBundle: targetAppBundleIdentifier)
             deliveryCompleted?()
             return
         }
@@ -4176,6 +4493,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 +4846,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"
@@ -4563,15 +4897,37 @@ public final class RecordingEngine: ObservableObject {
         setBlockedReason(nil, for: .pressConsumed)
     }
 
+    private func appendUndeliveredPaste(text: String, copied: Bool, captureID: String?,
+                                       pipelineGeneration: UInt64?, fallbackBundle: String? = nil) {
+        let selection = pipelineGeneration.flatMap { frozenPasteTargetsByGeneration[$0] }
+        let target: RecordingPasteTarget? = if case .frozen(let value) = selection { value } else { nil }
+        recentPastes.insert(RecentPaste(text: text, bundleIdentifier: target?.bundleIdentifier ?? fallbackBundle,
+            appName: target?.applicationName ?? fallbackBundle ?? "No target app",
+            location: copied ? "Clipboard only" : "", status: copied ? "Copied; paste not delivered" : "Paste not delivered",
+            verified: false, captureID: captureID, deliveryStatus: .notDelivered), at: 0)
+        if recentPastes.count > 50 { recentPastes.removeLast() }
+    }
+
+    private func completeUnavailablePaste(_ text: String, deliveryKind: PasteDeliveryKind, captureID: String?,
+                                          pipelineGeneration: UInt64?, fallbackBundle: String? = nil) {
+        let copied = Self.shouldCopyPasteFallback(deliveryKind: deliveryKind) && pasteFallbackWriter(text)
+        appendUndeliveredPaste(text: text, copied: copied, captureID: captureID,
+                               pipelineGeneration: pipelineGeneration, fallbackBundle: fallbackBundle)
+        log("paste target app not found")
+        updateDeliveryStatus(deliveryKind == .commandRewrite
+            ? "Paste cancelled because the target app is unavailable"
+            : copied ? "Copied — no target app found" : "Transcription ready, but the clipboard could not be updated",
+            kind: .failure, pipelineGeneration: pipelineGeneration)
+    }
+
     private func selectedRunningPasteTarget(
         targetAppBundleIdentifier: String?,
         targetAppPid: pid_t?,
         frontmostPid: pid_t?,
         pipelineGeneration: UInt64?
     ) -> NSRunningApplication? {
-        let myPID = ProcessInfo.processInfo.processIdentifier
         let runningApps = NSWorkspace.shared.runningApplications
-        let candidates = runningApps.map {
+        let candidates = runningApps.filter { !$0.isTerminated }.map {
             PasteTargetCandidate(
                 pid: $0.processIdentifier,
                 bundleIdentifier: $0.bundleIdentifier,
@@ -4579,23 +4935,30 @@ public final class RecordingEngine: ObservableObject {
                 launchDate: $0.launchDate
             )
         }
-        let requiredProcessIdentity = pipelineGeneration.flatMap {
-            pasteTargetProcessIdentityByGeneration[$0]
-        }
-        let selectedTarget = Self.selectPasteTarget(
-            candidates: candidates,
-            currentPid: myPID,
-            targetBundleIdentifier: targetAppBundleIdentifier,
-            targetPid: targetAppPid,
-            frontmostPid: frontmostPid,
-            requiredProcessIdentity: requiredProcessIdentity,
-            requiresProcessIdentity: pipelineGeneration != nil && targetAppPid != nil
+        let selectedTarget = resolvePasteTarget(
+            candidates: candidates, targetBundleIdentifier: targetAppBundleIdentifier,
+            targetPid: targetAppPid, frontmostPid: frontmostPid, pipelineGeneration: pipelineGeneration
         )
         return selectedTarget.flatMap { selected in
             runningApps.first { $0.processIdentifier == selected.pid }
         }
     }
 
+    func resolvePasteTarget(candidates: [PasteTargetCandidate], targetBundleIdentifier: String?,
+                            targetPid: pid_t?, frontmostPid: pid_t?, pipelineGeneration: UInt64?) -> PasteTargetCandidate? {
+        let frozen = pipelineGeneration.flatMap { frozenPasteTargetsByGeneration[$0] }
+        let identity = pipelineGeneration.flatMap { pasteTargetProcessIdentityByGeneration[$0] }
+        if frozen != nil {
+            // No bundle-only or foreground fallback for an explicitly frozen capture.
+            guard let identity, targetPid == identity.pid,
+                  targetBundleIdentifier == identity.bundleIdentifier else { return nil }
+        }
+        return Self.selectPasteTarget(candidates: frozen == nil ? candidates : candidates.filter(\.isRegularApp),
+            currentPid: ProcessInfo.processInfo.processIdentifier, targetBundleIdentifier: targetBundleIdentifier,
+            targetPid: targetPid, frontmostPid: frontmostPid, requiredProcessIdentity: identity,
+            requiresProcessIdentity: frozen != nil || (pipelineGeneration != nil && targetPid != nil))
+    }
+
     nonisolated static func selectPasteTarget(
         candidates: [PasteTargetCandidate],
         currentPid: pid_t,
@@ -4754,12 +5117,15 @@ enum CLIRunner: Sendable {
 
     enum ExecutionError: Error, LocalizedError, Equatable {
         case timedOut(executable: String, seconds: TimeInterval)
+        case deadlineExhausted
         case captureFailed(operation: CaptureOperation, code: Int32)
 
         var errorDescription: String? {
             switch self {
             case let .timedOut(executable, seconds):
                 return "Command timed out after \(seconds.formatted()) seconds: \(executable)"
+            case .deadlineExhausted:
+                return "Command timed out: insufficient time remains to start safely."
             case let .captureFailed(operation, code):
                 return "Failed to capture command output while \(operation.description): \(String(cString: strerror(code)))"
             }
@@ -4788,24 +5154,76 @@ enum CLIRunner: Sendable {
         _ lifecycleObserver: ((ProcessLifecycleEvent) -> Void)?
     ) throws -> Int32
 
+    /// An explicit monotonic deadline can cross queue and preparation boundaries without
+    /// resetting the budget. The clock is injectable for deterministic boundary tests.
+    struct WallClockDeadline: Sendable {
+        private let expiresAt: UInt64
+        private let now: @Sendable () -> UInt64
+
+        init(
+            after seconds: TimeInterval,
+            now: @escaping @Sendable () -> UInt64 = { DispatchTime.now().uptimeNanoseconds }
+        ) {
+            precondition(seconds.isFinite && seconds >= 0)
+            let startedAt = now()
+            let maximumDelay = min(UInt64(Int64.max), UInt64.max - startedAt)
+            let requested = seconds * 1_000_000_000
+            // Truncate fractional nanoseconds: rounding up could extend the configured
+            // budget and reject its own deadline at a subsequent handoff validation.
+            let delay = requested >= Double(maximumDelay)
+                ? maximumDelay : UInt64(requested)
+            expiresAt = startedAt + delay
+            self.now = now
+        }
+
+        func remaining(reserving reserve: TimeInterval = 0) -> TimeInterval {
+            let current = now()
+            guard expiresAt > current else { return 0 }
+            return max(0, Double(expiresAt - current) / 1_000_000_000 - reserve)
+        }
+    }
+
+    private static func requireStartBudget(_ deadline: WallClockDeadline?) throws {
+        if let deadline, deadline.remaining() <= wallClockCleanupReserve {
+            throw ExecutionError.deadlineExhausted
+        }
+    }
+
     static func run(
         _ args: [String],
         home: String,
         timeout: TimeInterval = 120,
-        totalWallClockBudget: TimeInterval? = nil
+        totalWallClockBudget: TimeInterval? = nil,
+        environment suppliedEnvironment: [String: String]? = nil,
+        wallClockDeadline suppliedDeadline: WallClockDeadline? = nil,
+        environmentProvider: (() throws -> [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 }
+        if let totalWallClockBudget {
+            precondition(totalWallClockBudget.isFinite && totalWallClockBudget > wallClockCleanupReserve)
+        }
+        precondition(suppliedDeadline == nil || totalWallClockBudget != nil)
+        let deadline = suppliedDeadline ?? totalWallClockBudget.map { WallClockDeadline(after: $0) }
+        if let suppliedDeadline, let totalWallClockBudget {
+            precondition(suppliedDeadline.remaining() <= totalWallClockBudget)
+        }
         do {
+            try requireStartBudget(deadline)
+            let command = resolveCommand(home: home)
+            let arguments = command.argumentsPrefix + args
+            try requireStartBudget(deadline)
+            let environment = try suppliedEnvironment ?? environmentProvider?() ?? 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)
+            )
+            try requireStartBudget(deadline)
             let output = try runExecutable(
                 command.executable,
                 arguments: arguments,
                 environment: environment,
                 executionTimeout: timeout,
-                totalWallClockBudget: totalWallClockBudget
+                totalWallClockBudget: totalWallClockBudget,
+                wallClockDeadline: deadline
             )
             if output.terminationStatus != 0 {
                 let details = output.stderr.isEmpty ? output.stdout : output.stderr
@@ -4853,6 +5271,7 @@ enum CLIRunner: Sendable {
         forceKillGracePeriod: TimeInterval = 1,
         pipeDrainTimeout: TimeInterval = 2,
         totalWallClockBudget: TimeInterval? = nil,
+        wallClockDeadline suppliedDeadline: WallClockDeadline? = nil,
         beforeExecutionDeadline: (() -> Void)? = nil,
         lifecycleObserver: ((ProcessLifecycleEvent) -> Void)? = nil,
         leaderReaper: LeaderReaper? = nil,
@@ -4866,23 +5285,24 @@ enum CLIRunner: Sendable {
             precondition(totalWallClockBudget.isFinite && totalWallClockBudget > wallClockCleanupReserve)
         }
 
-        // The budget clock starts before the spawn so setup latency cannot extend the
-        // observable wall time. Every wait below is clamped to what is left of it.
-        let wallClockDeadline = totalWallClockBudget.map { monotonicUptimeDeadline(after: $0) }
+        precondition(suppliedDeadline == nil || totalWallClockBudget != nil)
+        if let suppliedDeadline, let totalWallClockBudget {
+            precondition(suppliedDeadline.remaining() <= totalWallClockBudget)
+        }
+        // A caller that prepared the command supplies its original deadline. Direct
+        // executable callers begin here; neither path resets a previously spent budget.
+        let wallClockDeadline = suppliedDeadline ?? totalWallClockBudget.map { WallClockDeadline(after: $0) }
         func clampedToWallClockBudget(
             _ phaseTimeout: TimeInterval,
             reserving reserve: TimeInterval = 0
         ) -> TimeInterval {
             guard let wallClockDeadline else { return phaseTimeout }
-            let now = DispatchTime.now().uptimeNanoseconds
-            let remaining = wallClockDeadline > now
-                ? Double(wallClockDeadline - now) / 1_000_000_000 - reserve
-                : 0
-            return max(0, min(phaseTimeout, remaining))
+            return min(phaseTimeout, wallClockDeadline.remaining(reserving: reserve))
         }
         let contractualExecutionTimeout = totalWallClockBudget
             .map { min(executionTimeout, $0 - wallClockCleanupReserve) } ?? executionTimeout
 
+        try requireStartBudget(wallClockDeadline)
         let stdoutReader = try PipeCaptureReader(systemCalls: captureSystemCalls)
         let stderrReader: PipeCaptureReader
         do {
@@ -4896,6 +5316,7 @@ enum CLIRunner: Sendable {
 
         let processIdentifier: pid_t
         do {
+            try requireStartBudget(wallClockDeadline)
             processIdentifier = try spawnProcessGroup(
                 executable,
                 arguments: arguments,
@@ -5075,6 +5496,30 @@ enum CLIRunner: Sendable {
             )
         }
 
+        // CLOEXEC_DEFAULT also closes stdin unless it is explicitly inherited. Keep
+        // the existing stdin behavior, including an already closed/CLOEXEC stream;
+        // a capture pipe that reused fd 0 must still be closed by the actions above.
+        if !inheritedDescriptors.contains(STDIN_FILENO) {
+            var inputFlags: Int32
+            repeat {
+                inputFlags = Darwin.fcntl(STDIN_FILENO, F_GETFD)
+            } while inputFlags == -1 && errno == EINTR
+            let inputError = errno
+            if inputFlags == -1 && inputError != EBADF {
+                throw NSError(
+                    domain: NSPOSIXErrorDomain,
+                    code: Int(inputError),
+                    userInfo: [NSLocalizedDescriptionKey: "Failed to inspect command standard input"]
+                )
+            }
+            if inputFlags >= 0 && inputFlags & FD_CLOEXEC == 0 {
+                try checkPOSIX(
+                    posix_spawn_file_actions_addinherit_np(&fileActions, STDIN_FILENO),
+                    operation: "inherit command standard input"
+                )
+            }
+        }
+
         var attributes: posix_spawnattr_t?
         try checkPOSIX(posix_spawnattr_init(&attributes), operation: "initialize spawn attributes")
         defer { posix_spawnattr_destroy(&attributes) }
@@ -5091,7 +5536,10 @@ enum CLIRunner: Sendable {
             posix_spawnattr_setsigmask(&attributes, &unblockedSignals),
             operation: "unblock command signals"
         )
-        let spawnFlags = POSIX_SPAWN_SETPGROUP | POSIX_SPAWN_SETSIGDEF | POSIX_SPAWN_SETSIGMASK
+        // A different reader may still be between pipe() and FD_CLOEXEC setup.
+        // Inherit only our explicit standard streams, never that unrelated pipe.
+        let spawnFlags = POSIX_SPAWN_SETPGROUP | POSIX_SPAWN_SETSIGDEF
+            | POSIX_SPAWN_SETSIGMASK | POSIX_SPAWN_CLOEXEC_DEFAULT
         try checkPOSIX(
             posix_spawnattr_setflags(&attributes, Int16(spawnFlags)),
             operation: "configure command process group"
@@ -5611,7 +6059,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 +6068,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") {