@hasna/recordings 0.1.22 → 0.1.24

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.21";
+export declare const VERSION = "0.1.24";
 //# sourceMappingURL=version.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/recordings",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "type": "module",
   "description": "Speech-to-text recording tool with MCP and CLI — records, transcribes, and optionally enhances text using AI",
   "repository": {
@@ -17,13 +17,18 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./storage": {
+      "import": "./dist/storage.js",
+      "types": "./dist/storage.d.ts"
     }
   },
   "scripts": {
-    "build": "bun run build:cli && bun run build:mcp && bun run build:lib && tsc --emitDeclarationOnly --outDir dist",
+    "clean": "rm -rf dist",
+    "build": "bun run clean && bun run build:cli && bun run build:mcp && bun run build:lib && tsc --emitDeclarationOnly --outDir dist",
     "build:cli": "bun build src/cli/index.ts --target=bun --outfile=dist/cli/index.js --external=commander --external=chalk --external=openai",
     "build:mcp": "bun build src/mcp/index.ts --target=bun --outfile=dist/mcp/index.js --external=@modelcontextprotocol/sdk --external=openai",
-    "build:lib": "bun build src/index.ts --target=bun --outfile=dist/index.js --external=openai",
+    "build:lib": "bun build src/index.ts src/storage.ts --target=bun --outdir=dist --external=openai",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "test:coverage": "bun test --coverage",
@@ -45,15 +50,16 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@hasna/cloud": "^0.1.24",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
     "openai": "^5.1.0",
+    "pg": "^8.13.3",
     "zod": "^3.24.2"
   },
   "devDependencies": {
     "@types/bun": "^1.2.5",
+    "@types/pg": "^8.11.11",
     "typescript": "^5.8.2"
   },
   "publishConfig": {

package/scripts/install_macos_app.sh

@@ -105,4 +105,21 @@ APP_CDHASH="$(current_cdhash "$APP_DEST" || true)"
 reset_stale_permission "Microphone" "kTCCServiceMicrophone" "${HOME}/Library/Application Support/com.apple.TCC/TCC.db" "$APP_CDHASH"
 reset_stale_permission "Accessibility" "kTCCServiceAccessibility" "/Library/Application Support/com.apple.TCC/TCC.db" "$APP_CDHASH"
 
+# A second copy in ~/Applications splits TCC permissions and leaves users running
+# stale builds. Keep that launch point but always point it at the fresh build.
+ALT_COPY="${HOME}/Applications/Recordings.app"
+if [ -d "$ALT_COPY" ]; then
+  rm -rf "$ALT_COPY"
+  cp -R "$APP_SOURCE" "$ALT_COPY" || true
+  echo "Updated stale copy at ${ALT_COPY} to the freshly built app."
+fi
+
+# If an old instance is running, restart it on the new build.
+if pgrep -x Recordings >/dev/null 2>&1; then
+  pkill -x Recordings || true
+  sleep 1
+  open "$APP_DEST" || true
+  echo "Restarted Recordings.app on the new build."
+fi
+
 echo "Installed Recordings.app from package: ${APP_DEST}"

package/src/native/Recordings/App/RecordingsApp.swift

@@ -25,10 +25,11 @@ struct RecordingsApp: App {
                 }
         } label: {
             if engine.isRecording {
-                Image(systemName: "record.circle.fill")
-                    .symbolRenderingMode(.multicolor)
+                Image(systemName: "waveform")
+                    .symbolEffect(.variableColor.iterative, isActive: true)
             } else if engine.isTranscribing {
                 Image(systemName: "ellipsis.circle")
+                    .symbolEffect(.pulse, isActive: true)
             } else {
                 Image(systemName: "mic.fill")
             }

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

@@ -28,11 +28,10 @@ public struct MenuBarPopover: View {
         VStack(spacing: 0) {
             header
                 .padding(.horizontal, 16).padding(.top, 12).padding(.bottom, 8)
-            Divider()
             modePicker
-                .padding(.horizontal, 16).padding(.top, 10)
+                .padding(.horizontal, 16).padding(.top, 2)
             recordingArea
-                .padding(.horizontal, 16).padding(.top, 8).padding(.bottom, 12)
+                .padding(.horizontal, 16).padding(.top, 10).padding(.bottom, 12)
             Divider()
             if !engine.recentTranscriptions.isEmpty {
                 filterBar
@@ -44,6 +43,8 @@ public struct MenuBarPopover: View {
             Divider()
             footerMenu
         }
+        .animation(.smooth(duration: 0.25), value: engine.isRecording)
+        .animation(.smooth(duration: 0.25), value: engine.isTranscribing)
     }
 
     // MARK: - Header
@@ -54,16 +55,21 @@ public struct MenuBarPopover: View {
                 Image(systemName: "mic.fill")
                     .foregroundStyle(.tint)
                 Text("Hasna Recordings")
+                    .font(.headline)
                 Spacer()
                 if let shortcut = KeyboardShortcuts.getShortcut(for: .toggleRecording) {
                     Text(shortcut.description)
+                        .font(.caption)
                         .foregroundStyle(.secondary)
+                        .padding(.horizontal, 7)
+                        .padding(.vertical, 3)
+                        .glassEffect(.regular, in: .capsule)
                 }
             }
             if !projectStore.settings.projects.isEmpty {
                 HStack(spacing: 4) {
                     Image(systemName: "folder.fill")
-                        .foregroundColor(projectStore.activeProject != nil ? .accentColor : .secondary)
+                        .foregroundStyle(projectStore.activeProject != nil ? AnyShapeStyle(.tint) : AnyShapeStyle(.secondary))
                     Menu {
                         Button("None") { projectStore.setActive(nil) }
                         Divider()
@@ -102,91 +108,103 @@ public struct MenuBarPopover: View {
             }
         }
         .pickerStyle(.segmented)
+        .help(engine.mode.hint)
     }
 
     @ViewBuilder
     private var recordingArea: some View {
         if engine.isRecording {
-                VStack(spacing: 6) {
-                    HStack {
-                        Circle().fill(.red).frame(width: 8, height: 8)
-                        Text(fmt(engine.recordingDuration))
-                            .monospacedDigit()
-                        Spacer()
-                        Button("Stop") { engine.stopAndTranscribe() }
-                            .controlSize(.small)
-                    }
-                    // Live streaming transcription text
-                    if !engine.liveTranscriptionText.isEmpty {
-                        Text(engine.liveTranscriptionText)
-                            .font(.callout)
-                            .foregroundStyle(.primary)
-                            .multilineTextAlignment(.leading)
-                            .lineLimit(3)
-                            .padding(.vertical, 4)
-                        Text("Listening...")
-                            .font(.caption)
-                            .foregroundStyle(.green)
-                    }
-                    if let project = projectStore.activeProject {
-                        HStack(spacing: 4) {
-                            Image(systemName: "folder.fill").foregroundStyle(.tint)
-                            Text(project.name).foregroundStyle(.secondary)
-                            Spacer()
-                        }
-                    }
+            VStack(spacing: 8) {
+                HStack {
+                    Image(systemName: "waveform")
+                        .symbolEffect(.variableColor.iterative, isActive: true)
+                        .foregroundStyle(.red)
+                    Text(fmt(engine.recordingDuration))
+                        .monospacedDigit()
+                        .contentTransition(.numericText())
+                        .font(.title3.weight(.medium))
+                    Spacer()
+                    Button("Stop", systemImage: "stop.fill") { engine.stopAndTranscribe() }
+                        .buttonStyle(.glassProminent)
+                        .tint(.red)
+                        .controlSize(.small)
                 }
-                .padding(10)
-                .glassEffect(.regular)
+                if !engine.liveTranscriptionText.isEmpty {
+                    Text(engine.liveTranscriptionText)
+                        .font(.callout)
+                        .foregroundStyle(.primary)
+                        .frame(maxWidth: .infinity, alignment: .leading)
+                        .lineLimit(3)
+                        .contentTransition(.opacity)
+                } else {
+                    Text("Listening…")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .frame(maxWidth: .infinity, alignment: .leading)
+                }
+                if let project = projectStore.activeProject {
+                    activeProjectTag(project)
+                }
+            }
+            .padding(12)
+            .glassEffect(.regular.tint(.red.opacity(0.1)), in: .rect(cornerRadius: 14))
         } else if engine.isTranscribing {
-                VStack(spacing: 6) {
-                    HStack(spacing: 8) {
-                        ProgressView().controlSize(.small)
-                        Text("Transcribing...")
-                            .foregroundStyle(.secondary)
-                        Spacer()
-                    }
-                    // Show accumulated text during transcribing
-                    if !engine.liveTranscriptionText.isEmpty {
-                        Text(engine.liveTranscriptionText)
-                            .font(.callout)
-                            .foregroundStyle(.primary)
-                            .multilineTextAlignment(.leading)
-                            .lineLimit(3)
-                            .padding(.vertical, 4)
-                    }
-                    if let project = projectStore.activeProject {
-                        HStack(spacing: 4) {
-                            Image(systemName: "folder.fill").foregroundStyle(.tint)
-                            Text(project.name).foregroundStyle(.secondary)
-                            Spacer()
-                        }
-                    }
+            VStack(spacing: 8) {
+                HStack(spacing: 8) {
+                    ProgressView().controlSize(.small)
+                    Text("Transcribing…")
+                        .foregroundStyle(.secondary)
+                    Spacer()
+                }
+                if !engine.liveTranscriptionText.isEmpty {
+                    Text(engine.liveTranscriptionText)
+                        .font(.callout)
+                        .foregroundStyle(.primary)
+                        .frame(maxWidth: .infinity, alignment: .leading)
+                        .lineLimit(3)
                 }
-                .frame(maxWidth: .infinity)
-                .padding(10)
-                .glassEffect(.regular)
+                if let project = projectStore.activeProject {
+                    activeProjectTag(project)
+                }
+            }
+            .frame(maxWidth: .infinity)
+            .padding(12)
+            .glassEffect(.regular, in: .rect(cornerRadius: 14))
         } else {
-                VStack(spacing: 6) {
-                    Button { engine.startRecording() } label: {
-                        Label("Record", systemImage: "mic.circle.fill")
-                    }
-                    .controlSize(.regular)
+            VStack(spacing: 8) {
+                Button {
+                    engine.startRecording()
+                } label: {
+                    Label("Record", systemImage: "mic.fill")
+                        .frame(maxWidth: .infinity)
+                }
+                .buttonStyle(.glassProminent)
+                .controlSize(.large)
 
-                    if let shortcut = KeyboardShortcuts.getShortcut(for: .toggleRecording) {
-                        Text("or hold \(shortcut.description)")
-                            .foregroundStyle(.tertiary)
-                    }
-                    Text(engine.statusMessage)
+                if let shortcut = KeyboardShortcuts.getShortcut(for: .toggleRecording) {
+                    Text("or hold \(shortcut.description)")
                         .font(.caption)
-                        .foregroundStyle(engine.statusMessage == "Ready" ? Color.secondary : Color.orange)
-                        .multilineTextAlignment(.center)
-                        .lineLimit(2)
+                        .foregroundStyle(.tertiary)
                 }
-                .frame(maxWidth: .infinity)
-                .padding(10)
-                .glassEffect(.regular)
+                Text(engine.statusMessage)
+                    .font(.caption)
+                    .foregroundStyle(engine.statusMessage == "Ready" ? Color.secondary : Color.orange)
+                    .multilineTextAlignment(.center)
+                    .lineLimit(2)
+            }
+            .frame(maxWidth: .infinity)
+            .padding(12)
+            .glassEffect(.regular, in: .rect(cornerRadius: 14))
+        }
+    }
+
+    private func activeProjectTag(_ project: RecProject) -> some View {
+        HStack(spacing: 4) {
+            Image(systemName: "folder.fill").foregroundStyle(.tint)
+            Text(project.name).foregroundStyle(.secondary)
+            Spacer()
         }
+        .font(.caption)
     }
 
     // MARK: - Filter Bar
@@ -300,13 +318,16 @@ struct FilterChip: View {
     var body: some View {
         Button(action: action) {
             Text(label)
-                .padding(.horizontal, 8)
-                .padding(.vertical, 3)
-                .background(isActive ? Color.accentColor.opacity(0.15) : Color.clear)
-                .clipShape(RoundedRectangle(cornerRadius: 6))
+                .font(.caption)
+                .padding(.horizontal, 9)
+                .padding(.vertical, 4)
         }
         .buttonStyle(.plain)
         .foregroundStyle(isActive ? .primary : .secondary)
+        .glassEffect(
+            isActive ? .regular.tint(.accentColor.opacity(0.25)).interactive() : .regular.interactive(),
+            in: .capsule
+        )
     }
 }
 

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

@@ -21,6 +21,32 @@ enum OpenAIAPIKeyStore {
         return ""
     }
 
+    /// Persist the key into ~/.hasna/recordings/config.json so the CLI (which the app
+    /// shells out to for final transcription) uses the same key as the app itself.
+    static func save(key: String, homePath: String) throws {
+        let trimmed = key.trimmingCharacters(in: .whitespacesAndNewlines)
+        let dir = URL(fileURLWithPath: homePath)
+            .appendingPathComponent(".hasna")
+            .appendingPathComponent("recordings")
+        let url = dir.appendingPathComponent("config.json")
+
+        var json: [String: Any] = [:]
+        if let data = try? Data(contentsOf: url),
+           let existing = try? JSONSerialization.jsonObject(with: data) as? [String: Any] {
+            json = existing
+        }
+
+        if trimmed.isEmpty {
+            json.removeValue(forKey: "openai_api_key")
+        } else {
+            json["openai_api_key"] = trimmed
+        }
+
+        try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        let data = try JSONSerialization.data(withJSONObject: json, options: [.prettyPrinted, .sortedKeys])
+        try data.write(to: url, options: .atomic)
+    }
+
     private static func loadConfigKey(homePath: String, environment: [String: String]) -> String? {
         let url = URL(fileURLWithPath: homePath)
             .appendingPathComponent(".hasna")

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

@@ -166,6 +166,12 @@ public final class RealtimeTranscriptionClient: ObservableObject, @unchecked Sen
     /// Returns the final accumulated transcription text.
     @discardableResult
     public func stop() -> String {
+        if isStreaming {
+            NativeAppLog.write(
+                "realtime session summary items=\(itemOrder.count) committed=\(committedItemIDs.count) completed=\(completedItemIDs.count) deltaChars=\(deltaTextByItem.values.map(\.count).reduce(0, +)) finalChars=\(accumulatedText.count) error=\(error ?? "none")",
+                homePath: homePath
+            )
+        }
         isStreaming = false
         isConfigured = false
         receiveTask?.cancel()
@@ -256,7 +262,13 @@ public final class RealtimeTranscriptionClient: ObservableObject, @unchecked Sen
             if let detail = json["error"] as? [String: Any],
                let msg = detail["message"] as? String {
                 fputs("[RealtimeClient] Error: \(msg)\n", stderr)
-                self.error = msg
+                // "buffer too small" on commit just means server VAD already consumed
+                // the audio — the transcript is intact, so don't surface it as a failure.
+                if msg.localizedCaseInsensitiveContains("buffer too small") {
+                    NativeAppLog.write("realtime benign commit error: \(msg)", homePath: homePath)
+                } else {
+                    self.error = msg
+                }
             }
 
         default:

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

@@ -411,7 +411,9 @@ public final class RecordingEngine: ObservableObject {
             if let message = client.error, !message.isEmpty {
                 await MainActor.run {
                     self.log("realtime unavailable message=\(message)")
-                    self.statusMessage = "Realtime unavailable — will transcribe after recording"
+                    if self.isRecording {
+                        self.statusMessage = "Live preview unavailable — will transcribe after recording"
+                    }
                 }
             }
         }
@@ -464,21 +466,33 @@ public final class RecordingEngine: ObservableObject {
             self.liveTranscriptionText = ""
 
             if let audioPath, self.writeCapturedWAV(to: audioPath) {
-                if let realtimeText {
-                    self.log("realtime preview ignored for final chars=\(realtimeText.count)")
-                }
-                self.log("transcribing captured full audio audioPath=\(audioPath)")
+                self.log("transcribing captured full audio audioPath=\(audioPath) realtimePreviewChars=\(realtimeText?.count ?? 0)")
                 self.fallbackTranscribe(
                     audioPath: audioPath,
                     curMode: curMode,
                     targetAppBundleIdentifier: targetAppBundleIdentifier,
                     targetAppPid: targetAppPid,
                     activeProjectId: activeProjectId,
-                    activeProjectName: activeProjectName
+                    activeProjectName: activeProjectName,
+                    realtimeText: realtimeText
                 )
             } else {
-                self.log("no audio captured")
-                self.finish("No audio captured")
+                let resolved = Self.resolveFinalTranscript(cliText: nil, cliError: "No audio captured", realtimeText: realtimeText)
+                if let text = resolved.text {
+                    self.log("no audio file written; using realtime transcript chars=\(text.count)")
+                    self.isTranscribing = false
+                    self.finishWithText(
+                        text,
+                        curMode: curMode,
+                        targetAppBundleIdentifier: targetAppBundleIdentifier,
+                        targetAppPid: targetAppPid,
+                        activeProjectId: activeProjectId,
+                        activeProjectName: activeProjectName
+                    )
+                } else {
+                    self.log("no audio captured")
+                    self.finish(resolved.failureStatus ?? "No audio captured")
+                }
             }
 
             self.activeAudioPath = nil
@@ -502,7 +516,7 @@ public final class RecordingEngine: ObservableObject {
 
         let shortcutText = voiceShortcuts?.match(text)
         let output = shortcutText ?? text
-        pasteIntoFrontApp(output, targetAppBundleIdentifier: targetAppBundleIdentifier, targetAppPid: targetAppPid)
+        pasteIntoFrontApp(output, targetAppBundleIdentifier: targetAppBundleIdentifier, targetAppPid: targetAppPid, restoreClipboard: true)
         recentTranscriptions.insert(
             TranscriptionResult(
                 rawText: text,
@@ -584,7 +598,7 @@ public final class RecordingEngine: ObservableObject {
 
     // MARK: - Fallback Transcription
 
-    private func fallbackTranscribe(audioPath: String, curMode: RecordingMode, targetAppBundleIdentifier: String?, targetAppPid: pid_t?, activeProjectId: String?, activeProjectName: String?) {
+    private func fallbackTranscribe(audioPath: String, curMode: RecordingMode, targetAppBundleIdentifier: String?, targetAppPid: pid_t?, activeProjectId: String?, activeProjectName: String?, realtimeText: String? = nil) {
         let homePath = home
 
         isTranscribing = true
@@ -592,25 +606,27 @@ public final class RecordingEngine: ObservableObject {
 
         Task.detached {
             let output = CLIRunner.run(["--json", "transcribe", audioPath, "--no-enhance"], home: homePath)
-            if let error = CLIRunner.parseError(output) {
-                await MainActor.run {
-                    self.log("fallback transcription failed error=\(error)")
-                    self.finish(error)
+            let cliError = CLIRunner.parseError(output)
+            let cliText = cliError == nil ? CLIRunner.parseJSON(output) : nil
+
+            await MainActor.run {
+                if let cliError {
+                    self.log("cli transcription failed error=\(cliError)")
+                } else if cliText == nil {
+                    self.log("cli transcription empty output=\(output.prefix(160))")
                 }
-                return
-            }
 
-            let text = CLIRunner.parseJSON(output)
-            guard let text, !text.isEmpty else {
-                await MainActor.run {
-                    self.log("fallback transcription empty output=\(output.prefix(160))")
-                    self.finish("Empty transcription")
+                let resolved = Self.resolveFinalTranscript(cliText: cliText, cliError: cliError, realtimeText: realtimeText)
+                guard let text = resolved.text else {
+                    self.finish(resolved.failureStatus ?? "Transcription failed")
+                    return
                 }
-                return
-            }
 
-            await MainActor.run {
-                self.log("fallback transcription succeeded chars=\(text.count)")
+                if cliText == nil {
+                    self.log("using realtime transcript fallback chars=\(text.count)")
+                } else {
+                    self.log("cli transcription succeeded chars=\(text.count)")
+                }
                 self.isTranscribing = false
                 self.finishWithText(
                     text,
@@ -707,9 +723,10 @@ public final class RecordingEngine: ObservableObject {
 
     // MARK: - Paste
 
-    func pasteIntoFrontApp(_ text: String, targetAppBundleIdentifier: String? = nil, targetAppPid: pid_t? = nil) {
+    func pasteIntoFrontApp(_ text: String, targetAppBundleIdentifier: String? = nil, targetAppPid: pid_t? = nil, restoreClipboard: Bool = false) {
         log("paste requested chars=\(text.count) target=\(targetAppBundleIdentifier ?? "nil") pid=\(targetAppPid.map(String.init) ?? "nil") accessibility=\(AXIsProcessTrusted())")
         let pb = NSPasteboard.general
+        let previousClipboard = restoreClipboard ? pb.string(forType: .string) : nil
         pb.clearContents()
         pb.setString(text, forType: .string)
 
@@ -724,6 +741,7 @@ public final class RecordingEngine: ObservableObject {
 
         let myPID = ProcessInfo.processInfo.processIdentifier
         let runningApps = NSWorkspace.shared.runningApplications
+        let frontmostPid = NSWorkspace.shared.frontmostApplication?.processIdentifier
         let candidates = runningApps.map {
             PasteTargetCandidate(
                 pid: $0.processIdentifier,
@@ -735,7 +753,8 @@ public final class RecordingEngine: ObservableObject {
             candidates: candidates,
             currentPid: myPID,
             targetBundleIdentifier: targetAppBundleIdentifier,
-            targetPid: targetAppPid
+            targetPid: targetAppPid,
+            frontmostPid: frontmostPid
         )
         let targetApp = selectedTarget.flatMap { selected in
             runningApps.first { $0.processIdentifier == selected.pid }
@@ -748,9 +767,13 @@ public final class RecordingEngine: ObservableObject {
         }
 
         // Activate the exact app that owned focus when recording started, then paste after focus settles.
-        app.activate(options: [.activateIgnoringOtherApps])
+        let alreadyFrontmost = app.processIdentifier == frontmostPid
+        if !alreadyFrontmost {
+            app.activate(options: [.activateIgnoringOtherApps])
+        }
 
-        DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {
+        let pasteDelay: TimeInterval = alreadyFrontmost ? 0.15 : 0.5
+        DispatchQueue.main.asyncAfter(deadline: .now() + pasteDelay) {
             let src = CGEventSource(stateID: .hidSystemState)
             if let down = CGEvent(keyboardEventSource: src, virtualKey: 0x09, keyDown: true),
                let up = CGEvent(keyboardEventSource: src, virtualKey: 0x09, keyDown: false) {
@@ -759,8 +782,19 @@ public final class RecordingEngine: ObservableObject {
                 down.post(tap: .cgSessionEventTap)
                 up.post(tap: .cgSessionEventTap)
             }
-            self.log("paste event posted")
+            self.log("paste event posted target=\(app.bundleIdentifier ?? "?") alreadyFrontmost=\(alreadyFrontmost)")
             self.statusMessage = "Pasted (\(text.count) chars)"
+
+            if let previousClipboard {
+                // Give the target app time to consume the paste, then hand the clipboard back.
+                DispatchQueue.main.asyncAfter(deadline: .now() + 0.6) {
+                    let pb = NSPasteboard.general
+                    if pb.string(forType: .string) == text {
+                        pb.clearContents()
+                        pb.setString(previousClipboard, forType: .string)
+                    }
+                }
+            }
         }
     }
 
@@ -768,7 +802,8 @@ public final class RecordingEngine: ObservableObject {
         candidates: [PasteTargetCandidate],
         currentPid: pid_t,
         targetBundleIdentifier: String?,
-        targetPid: pid_t?
+        targetPid: pid_t?,
+        frontmostPid: pid_t? = nil
     ) -> PasteTargetCandidate? {
         candidates.first {
             guard let targetPid else { return false }
@@ -777,11 +812,28 @@ public final class RecordingEngine: ObservableObject {
             guard $0.pid != currentPid, $0.isRegularApp else { return false }
             guard let targetBundleIdentifier else { return false }
             return $0.bundleIdentifier == targetBundleIdentifier
+        } ?? candidates.first {
+            guard let frontmostPid else { return false }
+            return $0.pid == frontmostPid && $0.pid != currentPid && $0.isRegularApp
         } ?? candidates.first {
             $0.isRegularApp && $0.pid != currentPid
         }
     }
 
+    nonisolated static func resolveFinalTranscript(
+        cliText: String?,
+        cliError: String?,
+        realtimeText: String?
+    ) -> (text: String?, failureStatus: String?) {
+        if let cliText, !cliText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            return (cliText, nil)
+        }
+        if let realtimeText, !realtimeText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            return (realtimeText, nil)
+        }
+        return (nil, cliError ?? "Empty transcription")
+    }
+
     private func ensureAccessibilityPermission(prompt: Bool) -> Bool {
         if AXIsProcessTrusted() {
             return true
@@ -861,6 +913,15 @@ enum CLIRunner: Sendable {
         let trimmed = output.trimmingCharacters(in: .whitespacesAndNewlines)
         guard trimmed.hasPrefix("ERROR:") else { return nil }
         let message = trimmed.dropFirst("ERROR:".count).trimmingCharacters(in: .whitespacesAndNewlines)
+        let lowercased = message.lowercased()
+        if lowercased.contains("401") || lowercased.contains("incorrect api key")
+            || lowercased.contains("invalid_api_key") || lowercased.contains("invalid or expired") {
+            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") {
+            return "OpenAI quota exceeded — check the OpenAI account billing"
+        }
         if message.contains("OpenAI API key not configured") {
             return "OpenAI API key not configured on this Mac"
         }

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

@@ -29,7 +29,11 @@ public struct SettingsView: View {
             Section("OpenAI") {
                 SecureField("API key", text: $openAIAPIKey)
                     .textFieldStyle(.roundedBorder)
-                Text("Used for realtime transcription in the menu bar app.")
+                    .onChange(of: openAIAPIKey) {
+                        // Keep the CLI config in sync — final transcription shells out to it.
+                        try? OpenAIAPIKeyStore.save(key: openAIAPIKey, homePath: engine.home)
+                    }
+                Text("Used for live transcription and the final paste. Stored in ~/.hasna/recordings/config.json.")
                     .foregroundStyle(.secondary)
             }