Route stop-timeout meetings to failed queue

When stopAndAwaitFiles times out waiting for Audio.onRecordingComplete,
the WAV header is not yet fully patched. Previously the controller fed
those URLs straight into transcription, risking a corrupted transcript.
Now the bridge returns CaptureStopResult with didTimeOut, the controller
routes to the failed queue on timeout, and the user can retry from
Settings - Meetings once the file finalizes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: r3dbars

Sources/Meeting/MeetingCaptureBridge.swift

@@ -19,6 +19,16 @@ import Combine
 import Foundation
 import TranscriptedCore
 
+/// Result of a stop request. `didTimeOut == true` means we did not receive
+/// `Audio.onRecordingComplete` within `meetingStopTimeout`, so the WAV files
+/// at the returned URLs may not be fully finalized — the controller should
+/// route the audio to the failed queue rather than enqueuing for transcription.
+struct CaptureStopResult {
+    let micURL: URL?
+    let systemURL: URL?
+    let didTimeOut: Bool
+}
+
 @available(macOS 14.0, *)
 @MainActor
 final class MeetingCaptureBridge: ObservableObject {
@@ -42,7 +52,7 @@ final class MeetingCaptureBridge: ObservableObject {
 
     /// Fulfilled when Core's Audio reports recording completed. Cleared each
     /// time `startRecording` runs so back-to-back sessions do not leak state.
-    private var completionContinuation: CheckedContinuation<(micURL: URL?, systemURL: URL?), Never>?
+    private var completionContinuation: CheckedContinuation<CaptureStopResult, Never>?
     private var completionAttemptID: UUID?
     private var completionTimeoutTask: Task<Void, Never>?
     private var startContinuation: CheckedContinuation<Bool, Never>?
@@ -59,7 +69,11 @@ final class MeetingCaptureBridge: ObservableObject {
         startTimeoutTask?.cancel()
         startContinuation?.resume(returning: false)
         completionTimeoutTask?.cancel()
-        completionContinuation?.resume(returning: (audio.micAudioFileURL, audio.systemAudioFileURL))
+        completionContinuation?.resume(returning: CaptureStopResult(
+            micURL: audio.micAudioFileURL,
+            systemURL: audio.systemAudioFileURL,
+            didTimeOut: false
+        ))
         // Combine cancellables auto-release. Audio's own deinit tears down CoreAudio.
     }
 
@@ -73,7 +87,11 @@ final class MeetingCaptureBridge: ObservableObject {
             completionAttemptID = nil
             completionTimeoutTask?.cancel()
             completionTimeoutTask = nil
-            continuation.resume(returning: (audio.micAudioFileURL, audio.systemAudioFileURL))
+            continuation.resume(returning: CaptureStopResult(
+                micURL: audio.micAudioFileURL,
+                systemURL: audio.systemAudioFileURL,
+                didTimeOut: false
+            ))
         }
         if audio.isRecording { return true }
 
@@ -109,11 +127,18 @@ final class MeetingCaptureBridge: ObservableObject {
     }
 
     /// Stop the current recording and wait for Core's Audio to finish writing
-    /// the mic + system WAV files to disk. Returns the URLs of both files (system
-    /// may be nil if capture failed or was disabled).
-    func stopAndAwaitFiles() async -> (micURL: URL?, systemURL: URL?) {
+    /// the mic + system WAV files to disk. Returns a result that distinguishes
+    /// natural completion (`didTimeOut == false`) from `meetingStopTimeout`
+    /// expiry (`didTimeOut == true`). On timeout the WAV header may not be
+    /// fully patched, so the caller should treat the audio as failed-but-
+    /// recoverable rather than enqueuing it for transcription directly.
+    func stopAndAwaitFiles() async -> CaptureStopResult {
         guard audio.isRecording else {
-            return (audio.micAudioFileURL, audio.systemAudioFileURL)
+            return CaptureStopResult(
+                micURL: audio.micAudioFileURL,
+                systemURL: audio.systemAudioFileURL,
+                didTimeOut: false
+            )
         }
 
         return await withCheckedContinuation { continuation in
@@ -142,19 +167,23 @@ final class MeetingCaptureBridge: ObservableObject {
                         "system_file_available": "\(self.audio.systemAudioFileURL != nil)",
                     ]
                 )
-                continuation.resume(returning: (self.audio.micAudioFileURL, self.audio.systemAudioFileURL))
+                continuation.resume(returning: CaptureStopResult(
+                    micURL: self.audio.micAudioFileURL,
+                    systemURL: self.audio.systemAudioFileURL,
+                    didTimeOut: true
+                ))
             }
         }
     }
 
     /// Stop the current recording, wait for file handles to close, then remove
     /// the just-captured scratch audio instead of handing it to transcription.
     func stopAndDiscardFiles() async -> (micURL: URL?, systemURL: URL?) {
-        let files = await stopAndAwaitFiles()
-        MeetingRecordingCleanup.discardFiles(micURL: files.micURL, systemURL: files.systemURL)
+        let result = await stopAndAwaitFiles()
+        MeetingRecordingCleanup.discardFiles(micURL: result.micURL, systemURL: result.systemURL)
         audio.micAudioFileURL = nil
         audio.systemAudioFileURL = nil
-        return files
+        return (result.micURL, result.systemURL)
     }
 
     /// Snapshot of Core's recording health metadata for transcript frontmatter.
@@ -227,7 +256,11 @@ final class MeetingCaptureBridge: ObservableObject {
                 self.completionAttemptID = nil
                 self.completionTimeoutTask?.cancel()
                 self.completionTimeoutTask = nil
-                continuation?.resume(returning: (micURL, systemURL))
+                continuation?.resume(returning: CaptureStopResult(
+                    micURL: micURL,
+                    systemURL: systemURL,
+                    didTimeOut: false
+                ))
             }
         }
     }

Sources/Meeting/MeetingFailureCopy.swift

@@ -50,6 +50,13 @@ struct MeetingFailureCopy: Equatable {
             )
         }
 
+        if message.contains("stop timed out") {
+            return MeetingFailureCopy(
+                title: "Recording didn't close cleanly",
+                detail: "The audio files may be incomplete. Retry to transcribe what was captured, or delete to discard."
+            )
+        }
+
         return MeetingFailureCopy(
             title: isRetryable ? "Transcript needs another pass" : "Recording needs attention",
             detail: shortErrorMessage

Sources/Meeting/MeetingFailureKind.swift

@@ -14,6 +14,7 @@ enum MeetingFailureKind: String {
     case transcriptionInferenceFailed = "transcription_inference_failed"
     case diarizationFailed = "diarization_failed"
     case pipelineBusy = "pipeline_busy"
+    case stopTimeout = "stop_timeout"
     case unexpectedError = "unexpected_error"
 
     static func isRecordingTooShortMessage(_ message: String) -> Bool {
@@ -32,6 +33,11 @@ enum MeetingFailureKind: String {
     static func classify(message: String) -> MeetingFailureKind {
         let normalized = message.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
 
+        if normalized.contains("stop timed out")
+            || normalized.contains("recording stop timed out") {
+            return .stopTimeout
+        }
+
         if normalized.contains("system audio is required")
             || normalized.contains("system audio recording")
             || normalized.contains("screen recording") {

Sources/Meeting/MeetingSessionController.swift

@@ -497,7 +497,8 @@ final class MeetingSessionController: ObservableObject {
         // Snapshot capture health before stop resets system-audio status/stats during cleanup.
         let healthInfo = capture.healthInfo()
         let finalSystemAudioStatus = capture.systemAudioStatus
-        let files = await capture.stopAndAwaitFiles()
+        let stopResult = await capture.stopAndAwaitFiles()
+        let files = (micURL: stopResult.micURL, systemURL: stopResult.systemURL)
         let durationMs = Int(recordingDuration * 1000)
         activeRecordingTrigger = .unknown
         state = .transcribing
@@ -514,6 +515,7 @@ final class MeetingSessionController: ObservableObject {
                     "duration_ms": "\(durationMs)",
                     "mic_file_present": boolString(files.micURL != nil),
                     "system_file_present": boolString(files.systemURL != nil),
+                    "stop_timed_out": boolString(stopResult.didTimeOut),
                     "capture_quality": healthInfo.captureQuality.rawValue,
                     "audio_gaps": "\(healthInfo.audioGaps)",
                     "device_switches": "\(healthInfo.deviceSwitches)"
@@ -534,6 +536,28 @@ final class MeetingSessionController: ObservableObject {
             return
         }
 
+        // Stop timeout means Audio.onRecordingComplete never fired. The WAV
+        // header may not be fully patched, so route the audio to the failed
+        // queue rather than enqueuing for transcription. The user can retry
+        // from Settings → Meetings, where the pipeline will either succeed
+        // on a now-finalized file or fail cleanly.
+        if stopResult.didTimeOut {
+            failedManager.addFailedTranscription(
+                micAudioURL: micURL,
+                systemAudioURL: files.systemURL,
+                errorMessage: "Recording stop timed out before audio files were finalized."
+            )
+            DiagnosticsTrail.record(
+                level: .warning,
+                engine: "meeting",
+                event: "meeting_recording_stop_timeout_failed",
+                message: "Meeting routed to failed queue due to stop timeout",
+                context: baseDiagnosticsContext(extra: ["reason": reason.rawValue])
+            )
+            state = .error("Recording didn't close cleanly. Open Settings → Meetings to retry.")
+            return
+        }
+
         let outcome = enqueueTranscriptionJob(
             micURL: micURL,
             systemURL: files.systemURL,

Tests/MeetingFailureKindTests.swift

@@ -49,6 +49,24 @@ func testMeetingFailureKind() {
         assertEqual(kind, .pipelineBusy, "pipeline-busy rejections from TranscriptionTaskManager should not fall to unexpected_error")
     }
 
+    runSuite("MeetingFailureKind classifies stop-timeout errors") {
+        let kind = MeetingFailureKind.classify(
+            message: "Recording stop timed out before audio files were finalized."
+        )
+
+        assertEqual(kind, .stopTimeout, "stop-timeout failures should keep their own bucket so retry copy can target them")
+    }
+
+    runSuite("MeetingFailureCopy surfaces stop-timeout retry guidance") {
+        let copy = MeetingFailureCopy.make(
+            forMessage: "Recording stop timed out before audio files were finalized.",
+            shortErrorMessage: "Recording stop timed out.",
+            isRetryable: true
+        )
+
+        assertEqual(copy.title, "Recording didn't close cleanly", "stop-timeout users should see specific copy, not generic retry phrasing")
+    }
+
     runSuite("MeetingFailureKind falls back to an explicit unexpected bucket") {
         let kind = MeetingFailureKind.classify(
             message: "Something odd happened while processing the meeting"