@hasna/recordings 0.2.14 → 0.3.2

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

@@ -1,5 +1,7 @@
 import AVFoundation
 @preconcurrency import ApplicationServices
+// CopySymbolicHotKeys lives in Carbon's HIToolbox.
+import Carbon.HIToolbox
 import Darwin
 import SwiftUI
 @preconcurrency import KeyboardShortcuts
@@ -303,16 +305,45 @@ struct PasteDeliveryTransaction: Equatable, Sendable {
 }
 
 enum PasteDeliveryOutcome: Equatable, Sendable {
+    /// Delivery *observed*: the focused field in the target app was read back after the
+    /// keystroke and had gained the pasted text. Reachable only from confirming evidence —
+    /// see `PasteDeliveryOutcome.forDeliveryEvidence`. A posted `CGEvent` never produces it,
+    /// because `CGEvent.post` returns no delivery receipt.
     case pasted
+    /// The keystroke was posted and the focused field, readable before and after, did not
+    /// change. The paste did not land where it was aimed.
+    case deliveryNotObserved
+    /// The keystroke was posted and the target app's focused field could not be read back, so
+    /// delivery is unknown. Carries the reason so the log says which surface refused to
+    /// answer instead of implying success.
+    case deliveredUnverified(PasteDeliveryUnverifiedReason)
+    /// Secure event input is on, so no synthetic keystroke can reach any app. Nothing was
+    /// posted; the payload is left on the clipboard for the user to paste.
+    case secureInputActive(SecureInputHolder)
     case targetUnavailable
     case clipboardOwnershipLost
     case clipboardWriteFailed
     case eventPostFailed
+
+    /// The single place delivery evidence is allowed to become `.pasted`. Kept next to the
+    /// outcome so a reader can check the whole mapping at once: two confirming reads, one
+    /// contradicting read, everything else unverified.
+    static func forDeliveryEvidence(_ evidence: PasteDeliveryEvidence) -> PasteDeliveryOutcome {
+        switch evidence {
+        case .confirmedByFocusedValue, .confirmedBySelectedText: .pasted
+        case .notObservedFocusedValueUnchanged: .deliveryNotObserved
+        case .unverified(let reason): .deliveredUnverified(reason)
+        }
+    }
 }
 
 struct PasteboardWriteResult: Equatable, Sendable {
     let verified: Bool
     let ownershipChangeCount: Int
+    /// Whether the pasteboard's `changeCount` actually advanced past its pre-write value.
+    /// Weaker than `verified` (which also re-reads the stored string) and reported separately
+    /// so a log reader can tell "the pasteboard moved" from "the pasteboard holds our text".
+    var changeCountAdvanced: Bool = false
 }
 
 /// Outcome of revalidating the frozen rewrite target immediately before a rewrite runs.
@@ -334,7 +365,11 @@ final class PasteTransactionCoordinator {
     typealias ScheduledOperation = @MainActor @Sendable () -> Void
     typealias Scheduler = @MainActor @Sendable (TimeInterval, @escaping ScheduledOperation) -> Void
     typealias PayloadWriter = @MainActor @Sendable (String) -> PasteboardWriteResult
-    typealias PastePoster = @MainActor @Sendable () -> Bool
+    typealias PastePoster = @MainActor @Sendable () -> PasteKeystrokeAttempt
+    /// Reads the target app back and reports what that read proves. Defaulted to
+    /// `.unverified(.readBackNotAttempted)` at every entry point so a caller that supplies no
+    /// verification gets an explicitly unverified outcome, never an assumed success.
+    typealias DeliveryVerifier = @MainActor @Sendable () -> PasteDeliveryEvidence
     typealias WriteObserver = @MainActor @Sendable (PasteboardWriteResult) -> Void
     typealias Completion = @MainActor @Sendable (PasteDeliveryTransaction, PasteDeliveryOutcome) -> Void
     typealias Settlement = @MainActor @Sendable (PasteDeliveryTransaction, PasteDeliveryOutcome) -> Void
@@ -379,6 +414,14 @@ final class PasteTransactionCoordinator {
         payloadIsReady: @escaping @MainActor @Sendable () -> Bool = { true },
         prepare: @escaping ScheduledOperation = {},
         writeAttempted: @escaping WriteObserver = { _ in },
+        verify: @escaping DeliveryVerifier = { .unverified(.readBackNotAttempted) },
+        // `verificationDelay` is the wait between posting the keystroke and reading the target
+        // app back; zero verifies on the posting turn, which only makes sense for tests since a
+        // real app cannot have processed the event yet. `verificationAttempts` bounds how many
+        // read-backs may run before "the field did not change" is accepted as the verdict —
+        // only that verdict is retried, and each retry costs one `verificationDelay`.
+        verificationDelay: TimeInterval = 0,
+        verificationAttempts: Int = 1,
         completion: @escaping Completion,
         settlement: @escaping Settlement = { _, _ in }
     ) -> Bool {
@@ -421,26 +464,92 @@ final class PasteTransactionCoordinator {
                 completion(transaction, .clipboardOwnershipLost)
                 return
             }
-            guard self.postPaste() else {
-                settlement(transaction, .eventPostFailed)
+            // `@MainActor` is required, not decorative: a local function does not inherit the
+            // enclosing closure's actor isolation, so without it `state` cannot be mutated and
+            // `completion`/`settlement` cannot be called from here at all.
+            @MainActor func failNow(with outcome: PasteDeliveryOutcome) {
+                settlement(transaction, outcome)
                 self.state = .idle
-                completion(transaction, .eventPostFailed)
+                completion(transaction, outcome)
+            }
+
+            switch self.postPaste() {
+            case .constructionFailed:
+                failNow(with: .eventPostFailed)
+                return
+            case .refusedSecureInput(let holder):
+                // Nothing was posted: with secure input on, the window server drops synthetic
+                // key events for every consumer, so posting would only manufacture a success
+                // log for a paste that cannot happen.
+                failNow(with: .secureInputActive(holder))
                 return
+            case .posted:
+                break
             }
-            completion(transaction, .pasted)
-            guard settlementDelay > 0 else {
-                settlement(transaction, .pasted)
-                self.state = .idle
+
+            // The keystroke is out. `CGEvent.post` returned no receipt, so the transaction
+            // stays open: the outcome comes from reading the target app back.
+            let pending = PendingDelivery(
+                transaction: transaction,
+                verify: verify,
+                verificationDelay: verificationDelay,
+                verificationAttempts: verificationAttempts,
+                settlementDelay: settlementDelay,
+                completion: completion,
+                settlement: settlement
+            )
+            guard verificationDelay > 0 else {
+                self.settleFromDeliveryEvidence(pending, readBackAttempt: verificationAttempts)
                 return
             }
-            self.schedule(settlementDelay) { [weak self] in
+            self.schedule(verificationDelay) { [weak self] in
                 guard let self, self.state == .settling(transaction.id) else { return }
-                settlement(transaction, .pasted)
-                self.state = .idle
+                self.settleFromDeliveryEvidence(pending, readBackAttempt: 1)
             }
         }
         return true
     }
+
+    /// Everything the read-back loop needs after the keystroke has been posted.
+    private struct PendingDelivery: Sendable {
+        let transaction: PasteDeliveryTransaction
+        let verify: DeliveryVerifier
+        let verificationDelay: TimeInterval
+        let verificationAttempts: Int
+        let settlementDelay: TimeInterval
+        let completion: Completion
+        let settlement: Settlement
+    }
+
+    /// Asks the verifier what the target app shows, retrying only the "field did not change"
+    /// verdict: that is the one a slow app can turn into a confirmation, while a confirmed or
+    /// unreadable result is already final.
+    private func settleFromDeliveryEvidence(_ pending: PendingDelivery, readBackAttempt: Int) {
+        let evidence = pending.verify()
+        guard evidence == .notObservedFocusedValueUnchanged,
+              readBackAttempt < pending.verificationAttempts else {
+            complete(pending, outcome: .forDeliveryEvidence(evidence))
+            return
+        }
+        schedule(pending.verificationDelay) { [weak self] in
+            guard let self, self.state == .settling(pending.transaction.id) else { return }
+            self.settleFromDeliveryEvidence(pending, readBackAttempt: readBackAttempt + 1)
+        }
+    }
+
+    private func complete(_ pending: PendingDelivery, outcome: PasteDeliveryOutcome) {
+        pending.completion(pending.transaction, outcome)
+        guard pending.settlementDelay > 0 else {
+            pending.settlement(pending.transaction, outcome)
+            state = .idle
+            return
+        }
+        schedule(pending.settlementDelay) { [weak self] in
+            guard let self, self.state == .settling(pending.transaction.id) else { return }
+            pending.settlement(pending.transaction, outcome)
+            self.state = .idle
+        }
+    }
 }
 
 struct PipelineDeliveryGate: Sendable {
@@ -615,14 +724,134 @@ private extension Data {
 
 @MainActor
 public final class RecordingEngine: ObservableObject {
-    @Published public var isRecording = false
+    /// Audio is arriving. Not "a start was requested": `AVAudioEngine.start()` returns before
+    /// the input tap delivers its first sample (measured cold on Apple silicon:
+    /// `native recorder started` at +541 ms, `native recorder received first PCM chunk` at
+    /// +644 ms), and a hold released inside that window captured nothing at all. Flipping this
+    /// on `start()` returning is what let a short tap fall through to the transcription
+    /// pipeline with an empty buffer and finish silently.
+    @Published public private(set) var isRecording = false
+    /// The microphone is open but has not produced a sample yet — the ~100 ms window above.
+    /// Surfaces render this as recording (the user is holding the key), and every teardown
+    /// path can abandon it, but nothing may treat it as audio that exists.
+    @Published public private(set) var isWarmingUpCapture = false
     @Published public var useFnKey: Bool = false {
         didSet {
             UserDefaults.standard.set(useFnKey, forKey: "useFnKey")
             updateFnMonitor()
-            updateStatus()
+            refreshTriggerDiagnostics()
+        }
+    }
+    /// Where a blocked reason came from. The published reason is composed across these rather
+    /// than written per-source, because more than one can hold at once — fn and the hotkey can
+    /// both be blocked, and a delivery can be blocked while a trigger is too. A per-source
+    /// writer lets whichever ran last erase the others, which is the erasure bug this whole
+    /// mechanism exists to prevent.
+    ///
+    /// `Comparable` by declaration order, so the composed string is stable no matter which
+    /// source was written last: a reason that reorders itself between renders reads as two
+    /// different problems.
+    enum BlockedReasonSource: Int, CaseIterable, Comparable, Sendable {
+        /// The last delivery could not reach the target app and the transcript is sitting on
+        /// the clipboard waiting for the user. Cleared by the next recording, not by the next
+        /// status write.
+        ///
+        /// FIRST deliberately. This is the only reason that tells the owner their transcript is
+        /// still recoverable ("press Cmd-V"), and it used to sort LAST — so with a blocked
+        /// trigger as well it landed at the tail of a `.font(.caption)` `Text` in a 260-pt
+        /// popover, behind two reasons about key bindings. Data-recovery advice leads; the
+        /// trigger reasons are about a next press, which can wait.
+        case delivery
+        /// The keyboard shortcut collides with an enabled system shortcut.
+        case hotkey
+        /// The fn monitor cannot run (Accessibility).
+        case fnKey
+        /// A trigger fired but the press was consumed before recording could start — the
+        /// permission-prompt case. Transient, and cleared by the next start.
+        case pressConsumed
+
+        static func < (lhs: Self, rhs: Self) -> Bool { lhs.rawValue < rhs.rawValue }
+
+        /// Whether this source describes trigger *health* — the subject of the Settings
+        /// "Recording Shortcut" section. Exhaustive so a new source has to make the decision
+        /// rather than defaulting into a section whose remedy does not fit it.
+        var isTriggerHealth: Bool {
+            switch self {
+            // `.pressConsumed` IS trigger health: it is written from the fn and hotkey release
+            // handlers and says "press and hold again to record". Classifying it as non-trigger
+            // dropped it from the one section documented as "a trigger that is switched on but
+            // cannot arm must say so next to its own switch". `remedy` alone suppresses the wrong
+            // button, so the row belongs here.
+            case .hotkey, .fnKey, .pressConsumed: true
+            // Delivery is about the last paste, not about a binding. It gets its own row.
+            case .delivery: false
+            }
+        }
+
+        /// The action that actually fixes this cause, so a surface offering a *button* keys it to
+        /// the cause instead of to whatever text happened to be composed.
+        var remedy: BlockedReasonEntry.Remedy {
+            switch self {
+            case .fnKey: .openAccessibilitySettings
+            // A chord collision is not a permissions problem; the Accessibility pane does
+            // nothing for it and the shortcut recorder is already on screen.
+            case .hotkey: .chooseAnotherShortcut
+            // Both say what to do in the message itself — "press Cmd-V", "press and hold
+            // again" — so a button would be a second, competing instruction.
+            case .delivery, .pressConsumed: .messageOnly
+            }
         }
     }
+
+    /// One source's reason together with the remedy that fixes it.
+    ///
+    /// The composed `blockedReason` string is what the menu bar renders, and it is enough there
+    /// because that surface only reports. A Settings section that offers a *button* needs to know
+    /// WHICH problem it is offering to fix: rendering the composed string under "Recording
+    /// Shortcut" next to "Open Accessibility Settings" meant a secure-input paste failure showed
+    /// "transcript copied, press Cmd-V" beside a button that opens the Accessibility pane — the
+    /// wrong remedy, in the wrong section, for the wrong cause.
+    public struct BlockedReasonEntry: Identifiable, Equatable, Sendable {
+        public enum Remedy: Equatable, Sendable {
+            /// Grant Accessibility — what the fn monitor needs before its tap can be created.
+            case openAccessibilitySettings
+            /// Pick a different chord; the recorder that does it is in the same section.
+            case chooseAnotherShortcut
+            /// The message is the whole remedy. No button.
+            case messageOnly
+        }
+
+        let source: BlockedReasonSource
+        public let message: String
+        public var remedy: Remedy { source.remedy }
+        /// Whether this belongs in the Settings trigger section.
+        public var isTriggerHealth: Bool { source.isTriggerHealth }
+        public var id: Int { source.rawValue }
+    }
+
+    /// Why the app currently cannot record or deliver, when the reason outlives one status
+    /// write. Held separately from `statusMessage` because `updateStatus()` rewrites that on
+    /// every return to idle; see `updateStatus()`.
+    ///
+    /// This is the collapse of what were two fields — `triggerBlockedReason` (trigger health)
+    /// and `blockedReason` (secure-input delivery). Two published fields describing "the app
+    /// cannot do the thing you asked" is two places for a view to forget to read, and the
+    /// menu bar forgot to read either of them. One field, one writer.
+    @Published public private(set) var blockedReason: String?
+    /// The same reasons, per source and in precedence order. `blockedReason` is composed from
+    /// exactly this array, in the same call, so the two cannot disagree — this is the structured
+    /// form of one field, not a second field describing the same thing.
+    @Published public private(set) var blockedReasonEntries: [BlockedReasonEntry] = []
+    /// The ONLY writer of `blockedReason` is `setBlockedReason(_:for:)`. Do not assign the
+    /// published property anywhere else; `macos-shortcut-contract.test.ts` asserts that.
+    private var blockedReasons: [BlockedReasonSource: String] = [:]
+    /// The recording generation the `.delivery` reason was written for, or nil when none is held.
+    ///
+    /// The `.delivery` reason is the only one that is a claim about a *specific* recording:
+    /// "press Cmd-V" is true of the clipboard that recording wrote, and stops being true once the
+    /// generation moves on. Tracked so `updateStatus()` can expire it structurally instead of
+    /// relying on someone having enumerated every path that ought to clear it.
+    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 {
@@ -753,19 +982,90 @@ public final class RecordingEngine: ObservableObject {
             let pasteboard = NSPasteboard.general
             return RecordingEngine.writeClipboardAttempt(text, to: pasteboard)
         },
-        postPaste: {
+        postPaste: { [weak self] in
+            // Secure input is checked here, on the posting turn, rather than earlier: a
+            // password field can take it between the readiness checks and the keystroke, and
+            // while it is held the window server drops every synthetic event.
+            let secureInput = SecureInputProbe.current()
+            self?.lastPasteSecureInputProbe = secureInput
+            if case .active(let holder) = secureInput {
+                return .refusedSecureInput(holder)
+            }
             let source = CGEventSource(stateID: .hidSystemState)
             guard let down = CGEvent(keyboardEventSource: source, virtualKey: 0x09, keyDown: true),
                   let up = CGEvent(keyboardEventSource: source, virtualKey: 0x09, keyDown: false) else {
-                return false
+                return .constructionFailed
             }
             down.flags = .maskCommand
             up.flags = .maskCommand
             down.post(tap: .cgSessionEventTap)
             up.post(tap: .cgSessionEventTap)
-            return true
+            // Probed AGAIN, after posting, because the pre-post reading cannot cover the case
+            // that matters: a password field takes secure input between that probe and the
+            // keystroke. The window server then drops both events, and the read-back — which
+            // compares two AX reads of the focused field — can say "the text did not land" but
+            // never "secure input ate it". Its vocabulary tops out at
+            // `.notObservedFocusedValueUnchanged` / `.unverified(.readBackUnreadable)`, so the
+            // outcome falls to `.deliveryNotObserved` or `.deliveredUnverified`, neither of which
+            // is an `isSecureInputOutcome` — deliberately — so NOTHING is persisted: no warning
+            // icon, no VoiceOver "blocked" label, and no "press Cmd-V", which is the only thing
+            // telling the owner the transcript is still recoverable.
+            //
+            // And the log was not merely silent about the cause, it stated the opposite:
+            // `lastPasteSecureInputProbe` still held the pre-post reading, so
+            // `PasteDeliveryReport.logLine` recorded `secureInput=inactive` for a paste secure
+            // input had actually eaten.
+            //
+            // Only an `.active` reading overwrites the stored probe. A post-post `.unknown` after
+            // a definite pre-post `.inactive` is less informative about the posting turn, not
+            // more, so it must not replace it. The residual race — secure input taken and
+            // released entirely inside the posting window — is unobservable from here and stays
+            // unobservable; this closes the case where it is still held.
+            //
+            // This reading does NOT change the return value, and that is the whole design of it.
+            // Returning `.refusedSecureInput` here would be wrong twice over. The coordinator
+            // answers that case with `failNow`, which settles immediately and never builds the
+            // `PendingDelivery` — so the read-back, the ONLY evidence that can say whether the
+            // keystroke actually landed, would be discarded at precisely the moment it is needed.
+            // And a post-post `.active` reading cannot distinguish the two cases it spans: secure
+            // input taken between `up.post()` and this probe leaves the events already dispatched
+            // and probably delivered, while secure input taken during the posts drops them.
+            // Calling that a refusal would tell the owner "transcript copied, press Cmd-V" for a
+            // paste that already succeeded, and Cmd-V would paste it a second time — a worse
+            // failure than the missing disclosure it was meant to fix. It would also make the log
+            // say `not_posted_secure_input` for events that WERE posted, trading one false
+            // statement for another. `.refusedSecureInput` means "nothing was posted"; it must
+            // keep meaning that.
+            //
+            // So the read-back stays the arbiter (#28's ruling) and this probe makes the LOG
+            // honest: `PasteDeliveryReport` now carries the post-post reading, where it previously
+            // carried the pre-post one and recorded `secure_input=inactive` for a paste secure
+            // input may have eaten — asserting the opposite of what happened rather than merely
+            // omitting it.
+            //
+            // NOT restored, and deliberately: attribution strong enough to reach the persistence
+            // and visibility path. Making a non-confirming read-back settle as
+            // `.secureInputActive` needs a new keystroke-attempt case threaded through
+            // `PasteAttempt`, or the log token lies about whether events were posted. That
+            // widening is a design change, left for review rather than smuggled in here.
+            let secureInputAfterPost = SecureInputProbe.current()
+            switch secureInputAfterPost {
+            // Held after the posts: the reading the log must carry.
+            case .active: self?.lastPasteSecureInputProbe = secureInputAfterPost
+            // Definite after an indefinite pre-post reading is strictly more informative, so it
+            // replaces it; the reverse would discard a definite reading for an indefinite one.
+            case .inactive: if case .unknown = secureInput { self?.lastPasteSecureInputProbe = secureInputAfterPost }
+            case .unknown: break
+            }
+            // Constructed and posted. Nothing here observes delivery, which is why this
+            // returns `.posted` and not a success.
+            return .posted
         }
     )
+    /// Secure-input reading taken on the last posting turn, or nil when no paste has reached
+    /// the posting step. Kept so the delivery log can say whether synthetic input was even
+    /// possible instead of leaving the reader to guess.
+    private var lastPasteSecureInputProbe: SecureInputState?
 
     /// Every coordinator the engine owns must publish its idle transitions:
     /// `canStartRecording` derives from coordinator state, and settlement back to idle is
@@ -807,7 +1107,40 @@ public final class RecordingEngine: ObservableObject {
     #endif
 
     private nonisolated static let realtimePeriodicCommitIntervalMilliseconds: UInt64 = 900
-    private nonisolated static let realtimeFinishTimeoutMilliseconds: UInt64 = 700
+    /// Floor of the post-release settlement budget. The settlement wait polls every 10 ms
+    /// and returns the moment the final transcription lands, so the budget is only ever
+    /// paid in full when the realtime session is still unsettled — the common settled case
+    /// costs its actual settle time (measured 0.6-1.6 s on station-class hardware).
+    private nonisolated static let realtimeSettleBudgetFloorMilliseconds: UInt64 = 1_500
+    /// Additional settlement budget granted per second of captured audio. A settlement
+    /// miss falls back to re-transcribing the whole recording through the batch API, which
+    /// costs roughly a quarter of the recording's duration (measured: 4 s floor + ~25%
+    /// of audio length) — so the longer the recording, the more waiting is worth it.
+    private nonisolated static let realtimeSettleBudgetPerAudioSecondMilliseconds: UInt64 = 25
+    /// Ceiling of the settlement budget: past this point the user has watched
+    /// "Transcribing..." for so long that starting the recoverable batch path is the
+    /// better trade even for very long recordings.
+    private nonisolated static let realtimeSettleBudgetCeilingMilliseconds: UInt64 = 5_000
+    /// PCM byte rate of the capture pipeline (24 kHz, 16-bit, mono) — used to convert
+    /// captured byte counts back into audio seconds for the settlement budget.
+    private nonisolated static let capturedPCMBytesPerSecond = 48_000
+
+    /// Settlement budget for `RealtimeTranscriptionClient.finish` scaled to the captured
+    /// audio length. The previous fixed 700 ms budget was routinely missed by real
+    /// sessions (final transcription completions arrive ~0.6-1.6 s after release), which
+    /// silently demoted nearly every recording to the duration-proportional batch path —
+    /// the "one minute to transcribe" failure mode this budget exists to prevent.
+    public nonisolated static func realtimeSettleBudgetMilliseconds(pcmByteCount: Int) -> UInt64 {
+        let audioSeconds = UInt64(max(pcmByteCount, 0)) / UInt64(capturedPCMBytesPerSecond)
+        let (scaled, overflowed) = audioSeconds.multipliedReportingOverflow(
+            by: realtimeSettleBudgetPerAudioSecondMilliseconds
+        )
+        guard !overflowed else { return realtimeSettleBudgetCeilingMilliseconds }
+        let (budget, budgetOverflowed) = realtimeSettleBudgetFloorMilliseconds
+            .addingReportingOverflow(scaled)
+        guard !budgetOverflowed else { return realtimeSettleBudgetCeilingMilliseconds }
+        return min(budget, realtimeSettleBudgetCeilingMilliseconds)
+    }
     /// Hard wall-clock budget for the rewrite helper (CLI spawn + one model call), covering
     /// execution *and* CLIRunner's termination grace, kill grace, and pipe drain — not just
     /// the child execution deadline. The user is waiting with recording blocked, so this
@@ -825,15 +1158,38 @@ 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
+    /// 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
+    /// still in flight.
+    nonisolated static let pasteReadBackInterval: TimeInterval = 0.15
+    /// How many read-backs before "the field did not change" is accepted as the verdict.
+    /// Four reads spaced by `pasteReadBackInterval` give a slow target app ~0.6 s to show the
+    /// paste; a confirmation on any read ends the wait immediately. The transaction stays
+    /// pending for that window, which is why the budget is bounded rather than generous.
+    nonisolated static let pasteReadBackAttempts = 4
 
     // fn key monitor (CGEventTap-based, swallows fn to prevent emoji picker)
     private let fnMonitor = FnKeyMonitor()
     private var permissionRetryTimer: Timer?
 
-    let home = FileManager.default.homeDirectoryForCurrentUser.path
+    /// Filesystem root for every artifact the engine owns: the audio spool, the
+    /// API-key/language store (`config.json`), `Recordings.log`, and the `recordings` CLI it
+    /// shells out to. This is the same `homePath:` seam `NativeAppLog.write` and
+    /// `OpenAIAPIKeyStore` already expose, defaulted the same way — production keeps the real
+    /// home and is unchanged.
+    ///
+    /// Unlike the closure seams above it must be supplied before `init` returns, because
+    /// `init` already creates `audioDir` and logs; hence an `init(homePath:)` parameter
+    /// rather than a settable property. Tests must pass a temp directory: with the default,
+    /// every engine a test builds appends the suite's synthetic fixtures
+    /// (`target=com.example.editor pid=99999`) to the operator's live `Recordings.log` and
+    /// rewrites their real `config.json`.
+    let home: String
     private var audioDir: String { "\(home)/.hasna/recordings/audio" }
 
-    public init() {
+    public init(homePath: String = FileManager.default.homeDirectoryForCurrentUser.path) {
+        home = homePath
         try? FileManager.default.createDirectory(atPath: audioDir, withIntermediateDirectories: true)
         log("RecordingEngine init; microphone=\(microphonePermissionLabel); accessibility=\(accessibilityPermissionLabel)")
 
@@ -844,18 +1200,25 @@ public final class RecordingEngine: ObservableObject {
         if KeyboardShortcuts.getShortcut(for: .toggleRecording) == nil {
             KeyboardShortcuts.setShortcut(.init(.f5), for: .toggleRecording)
         }
+        refreshHotkeyDiagnostics()
+        logResolvedTrigger()
 
         // Set up fn key monitor — hold fn to record, release to stop (like WisprFlow)
         fnMonitor.onFnKeyDown = { [weak self] in
             Task { @MainActor [weak self] in
                 guard let self else { return }
                 self.fnKeyIsDown = true
-                guard self.useFnKey, Self.canBeginRecording(
+                guard self.useFnKey else { return }
+                guard Self.canBeginRecording(
                     isRecording: self.isRecording,
                     isTranscribing: self.isTranscribing,
+                    isWarmingUpCapture: self.isWarmingUpCapture,
                     isAwaitingMicrophonePermission: self.microphonePermissionStartGate.isAwaitingResponse,
                     isDeliveryPending: self.deliveryIsPending
-                ) else { return }
+                ) else {
+                    self.logIgnoredTrigger(.fnKey)
+                    return
+                }
                 self.startRecording(trigger: .fnKey)
             }
         }
@@ -863,14 +1226,8 @@ public final class RecordingEngine: ObservableObject {
             Task { @MainActor [weak self] in
                 guard let self else { return }
                 self.fnKeyIsDown = false
-                guard self.useFnKey, self.activeTrigger == .fnKey else { return }
-                guard self.isRecording else {
-                    self.log("fn released before recording started; cancelling pending start")
-                    self.resetRecordingIntent()
-                    self.updateStatus()
-                    return
-                }
-                self.stopAndTranscribe()
+                guard self.useFnKey else { return }
+                self.handleTriggerRelease(.fnKey)
             }
         }
         updateFnMonitor(allowAutomaticPrompt: false)
@@ -882,9 +1239,13 @@ public final class RecordingEngine: ObservableObject {
                 guard Self.canBeginRecording(
                     isRecording: self.isRecording,
                     isTranscribing: self.isTranscribing,
+                    isWarmingUpCapture: self.isWarmingUpCapture,
                     isAwaitingMicrophonePermission: self.microphonePermissionStartGate.isAwaitingResponse,
                     isDeliveryPending: self.deliveryIsPending
-                ) else { return }
+                ) else {
+                    self.logIgnoredTrigger(.keyboardShortcut)
+                    return
+                }
                 self.startRecording(trigger: .keyboardShortcut)
             }
         }
@@ -892,14 +1253,7 @@ public final class RecordingEngine: ObservableObject {
             Task { @MainActor [weak self] in
                 guard let self, self.keyboardShortcutIsDown else { return }
                 self.keyboardShortcutIsDown = false
-                guard self.activeTrigger == .keyboardShortcut else { return }
-                guard self.isRecording else {
-                    self.log("shortcut released before recording started; cancelling pending start")
-                    self.resetRecordingIntent()
-                    self.updateStatus()
-                    return
-                }
-                self.stopAndTranscribe()
+                self.handleTriggerRelease(.keyboardShortcut)
             }
         }
 
@@ -907,9 +1261,7 @@ public final class RecordingEngine: ObservableObject {
         // so retry until permissions arrive instead of requiring a relaunch.
         permissionRetryTimer = Timer.scheduledTimer(withTimeInterval: 5.0, repeats: true) { [weak self] _ in
             Task { @MainActor [weak self] in
-                guard let self, self.useFnKey, !self.fnMonitor.isRunning, AXIsProcessTrusted() else { return }
-                self.log("accessibility granted — retrying fn monitor")
-                self.updateFnMonitor()
+                self?.refreshFnMonitorHealth()
             }
         }
 
@@ -972,7 +1324,91 @@ public final class RecordingEngine: ObservableObject {
         }
     }
 
+    /// Record which trigger is actually bound, at launch and whenever it changes.
+    ///
+    /// The log already showed `startRecording trigger=keyboardShortcut`, but never which
+    /// key was registered — so a hotkey silently rebound to a key the keyboard cannot send
+    /// 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() {
+        let stored = KeyboardShortcuts.getShortcut(for: .toggleRecording)
+        let bound = stored
+            .map { "carbonKeyCode=\($0.carbonKeyCode) carbonModifiers=\($0.carbonModifiers)" }
+            ?? "none"
+        // `getShortcut` is a UserDefaults read, so it says what is *configured*, never what
+        // is *armed*: KeyboardShortcuts 1.12.0 discards RegisterEventHotKey's OSStatus, so a
+        // chord already owned by another app is indistinguishable from a working one here.
+        // Say "unknown" rather than let a stored value read as a live binding.
+        let systemReserved = stored.map {
+            Self.systemReservedShortcuts().contains([$0.carbonKeyCode, $0.carbonModifiers])
+        }
+        // The permission labels belong on the same line: a press that fires but delivers
+        // nothing is a permission problem, and correlating two log lines by timestamp was
+        // the only way to tell that apart from a trigger that never fired.
+        log(
+            "trigger bindings: shortcutStored=\(bound) "
+                + "shortcutArmed=unknown(carbon-registration-status-not-exposed) "
+                + "shortcutSystemReserved=\(systemReserved.map(String.init(describing:)) ?? "n/a") "
+                + "useFnKey=\(useFnKey) fnMonitorRunning=\(fnMonitor.isRunning) "
+                + "microphone=\(microphonePermissionLabel) accessibility=\(accessibilityPermissionLabel) "
+                + "blocked=\(blockedReason ?? "none")"
+        )
+    }
+
+    /// Both global triggers used to `return` silently when the engine was busy, so a press
+    /// that produced nothing left no trace at all — indistinguishable from a trigger that
+    /// never fired. Name the refusal instead.
+    ///
+    /// Every field the start gate consults must appear here, `isWarmingUpCapture` included:
+    /// a press arriving during the ~100 ms warm-up is refused by that field alone, and
+    /// omitting it would print every reason as false and reproduce the exact silence this
+    /// function was added to end.
+    private func logIgnoredTrigger(_ trigger: RecordingTrigger) {
+        log(
+            "trigger ignored trigger=\(trigger) isRecording=\(isRecording) "
+                + "isWarmingUpCapture=\(isWarmingUpCapture) "
+                + "isTranscribing=\(isTranscribing) deliveryPending=\(deliveryIsPending) "
+                + "awaitingMicrophonePermission=\(microphonePermissionStartGate.isAwaitingResponse)"
+        )
+    }
+
+    /// Accessibility is the gate in practice: `FnKeyMonitor` creates an *active* tap
+    /// (`options: .defaultTap`, and it returns nil to swallow fn), and an event-modifying
+    /// tap requires Accessibility. Only a listen-only tap would fall under Input
+    /// Monitoring, so naming both grants sent people to the wrong pane.
+    static let fnAccessibilityBlockedMessage =
+        "fn needs Accessibility: System Settings > Privacy & Security > Accessibility"
+
+    /// Periodic reconciliation of the fn tap against reality.
+    ///
+    /// Two failures this closes. Granting Accessibility does not revive a tap that failed to
+    /// create, so it has to be retried — and the retry used to run `updateFnMonitor()`
+    /// without `updateStatus()`, so the stale "fn needs Accessibility" line survived the
+    /// grant. And a tap can die *after* creation (Accessibility revoked at runtime), which
+    /// no creation-time check can see; `FnKeyMonitor.isRunning` now reflects whether the tap
+    /// is actually enabled, so that case is detected here instead of reading as "Ready".
+    private func refreshFnMonitorHealth() {
+        guard useFnKey else { return }
+        if fnMonitor.isRunning {
+            if blockedReasons[.fnKey] != nil {
+                setBlockedReason(nil, for: .fnKey)
+                updateStatus()
+            }
+            return
+        }
+        if AXIsProcessTrusted() {
+            log("fn monitor not running while trusted — retrying")
+            updateFnMonitor()
+        } else {
+            setBlockedReason(Self.fnAccessibilityBlockedMessage, for: .fnKey)
+        }
+        updateStatus()
+    }
+
     private func updateFnMonitor(allowAutomaticPrompt: Bool = true) {
+        // 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?
         if useFnKey {
             let ok = fnMonitor.start()
             log("fn monitor start ok=\(ok)")
@@ -981,23 +1417,220 @@ public final class RecordingEngine: ObservableObject {
                     let result = accessibilityPromptGate.trustForProtectedOperation()
                     log("fn monitor accessibility trusted=\(result.trusted) prompted=\(result.didPrompt)")
                 }
-                statusMessage = "fn needs Input Monitoring / Accessibility permission, and Globe must be set to Do Nothing"
+                reason = Self.fnAccessibilityBlockedMessage
+                log("trigger blocked: \(Self.fnAccessibilityBlockedMessage)")
             }
         } else {
             fnMonitor.stop()
         }
+        setBlockedReason(reason, for: .fnKey)
     }
 
+    /// Record or clear one source's reason and recompute the published value. Each source owns
+    /// its own slot; this is the **only** writer of `blockedReason`.
+    ///
+    /// - Parameter generation: the recording generation a `.delivery` reason belongs to. Passed
+    ///   explicitly by the paste completion because that closure can run *after*
+    ///   `recordingGeneration` has already moved on — binding to the current value there would
+    ///   stamp a superseded reason as fresh, which is the whole failure this parameter closes.
+    ///   Ignored for every other source, none of which is recording-scoped.
+    private func setBlockedReason(
+        _ reason: String?,
+        for source: BlockedReasonSource,
+        generation: UInt64? = nil
+    ) {
+        if let reason, !reason.isEmpty {
+            // Refuse the write outright when the reason belongs to a superseded recording. The
+            // expiry in `updateStatus()` is lazy — no production caller runs it on the delivery
+            // completion or the return to idle — so a superseded reason written here would render
+            // and stay rendered until the owner next touched a trigger. Declining the store is the
+            // pre-render gate; the expiry remains as defence against a generation bump that
+            // happens AFTER a legitimate write.
+            if source == .delivery, let generation, generation != recordingGeneration {
+                log("delivery blocked reason refused for superseded generation=\(generation) current=\(recordingGeneration)")
+                return
+            }
+            blockedReasons[source] = reason
+            if source == .delivery {
+                // `nil` means unscoped, NOT "current". The public `pasteIntoFrontApp` route has no
+                // pipeline generation, so there is nothing that can supersede its reason and it
+                // must not be stamped with a generation it never belonged to.
+                deliveryBlockedReasonGeneration = generation
+            }
+        } else {
+            blockedReasons.removeValue(forKey: source)
+            if source == .delivery {
+                deliveryBlockedReasonGeneration = nil
+            }
+        }
+        let entries = blockedReasons
+            .sorted { $0.key < $1.key }
+            .map { BlockedReasonEntry(source: $0.key, message: $0.value) }
+        blockedReasonEntries = entries
+        let composed = entries
+            .map(\.message)
+            .joined(separator: " · ")
+        blockedReason = composed.isEmpty ? nil : composed
+    }
+
+    /// Enabled system-reserved shortcuts, read straight from Carbon.
+    ///
+    /// KeyboardShortcuts has an equivalent `Shortcut.isTakenBySystem`, but it sits in a
+    /// plain (internal) extension in the pinned 1.12.0 source, so it cannot be reached from
+    /// here. Only shortcuts flagged enabled count: a disabled system binding does not
+    /// contend for the key.
+    static func systemReservedShortcuts() -> Set<[Int]> {
+        var unmanaged: Unmanaged<CFArray>?
+        guard
+            CopySymbolicHotKeys(&unmanaged) == noErr,
+            let entries = unmanaged?.takeRetainedValue() as? [[String: Any]]
+        else {
+            return []
+        }
+        var reserved: Set<[Int]> = []
+        for entry in entries {
+            guard
+                (entry[kHISymbolicHotKeyEnabled] as? Bool) == true,
+                let code = entry[kHISymbolicHotKeyCode] as? Int,
+                let modifiers = entry[kHISymbolicHotKeyModifiers] as? Int
+            else {
+                continue
+            }
+            reserved.insert([code, modifiers])
+        }
+        return reserved
+    }
+
+    /// Re-evaluate whether the stored hotkey can plausibly arm.
+    ///
+    /// This is the honest half of a hard limit. `RegisterEventHotKey`'s `OSStatus` is
+    /// swallowed inside KeyboardShortcuts 1.12.0 (`CarbonKeyboardShortcuts.register` guards
+    /// on `registerError == noErr` and returns Void), so a hotkey stolen by *another
+    /// application* is not observable from here at all. A collision with an enabled
+    /// *system* shortcut is observable, and it is the case that silently wins, so it gets a
+    /// real blocked reason instead of a "Ready" that is not true.
+    /// 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() {
+        refreshHotkeyDiagnostics()
+        updateStatus()
+        logResolvedTrigger()
+    }
+
+    private func refreshHotkeyDiagnostics() {
+        guard let shortcut = KeyboardShortcuts.getShortcut(for: .toggleRecording) else {
+            setBlockedReason(nil, for: .hotkey)
+            return
+        }
+        let key = [shortcut.carbonKeyCode, shortcut.carbonModifiers]
+        var reason: String?
+        if Self.systemReservedShortcuts().contains(key) {
+            reason = "macOS already reserves this shortcut — pick another in Settings > Recording Shortcut"
+            log("trigger blocked: hotkey collides with an enabled system shortcut \(key)")
+        }
+        setBlockedReason(reason, for: .hotkey)
+    }
+
+    /// Message shown after a trigger fired but the press was consumed before recording could
+    /// start — in practice, the first fn press after a microphone permission prompt. Cancelling
+    /// is correct for push-to-talk (releasing the key before the recorder starts must not leave
+    /// a recording running with no key held); saying nothing about it is not.
+    static let pressConsumedByPermissionPromptMessage =
+        "Permission was requested — press and hold again to record"
+
+    /// The only writer of the idle status pair. Nothing else may set `statusMessage` to
+    /// "Ready" — three separate callers had grown their own copy of that assignment, and each
+    /// one silently bypassed the `blockedReason` branch below, overwriting a live "the app
+    /// cannot do the thing you asked" disclosure with a cheerful "Ready". Route every
+    /// return-to-idle through here so a fourth copy cannot appear.
     public func updateStatus() {
-        if isRecording || isTranscribing || deliveryIsPending { return }
+        if captureIsActive || isTranscribing || deliveryIsPending { return }
+        expireStaleDeliveryBlockedReason()
+        // A blocked trigger outlives one status write. `init` and every `useFnKey` change
+        // called `updateFnMonitor()` and then `updateStatus()`, so the fn permission
+        // warning was overwritten with "Ready" before it could ever be read — an enabled
+        // trigger that could not arm looked exactly like a working one. Idle now carries
+        // the reason until the blocker clears.
+        if let blockedReason {
+            statusMessage = blockedReason
+            flowPhase = .idle
+            return
+        }
         statusMessage = "Ready"
         flowPhase = .idle
     }
 
+    /// Drop a `.delivery` reason whose recording has been superseded since it was written.
+    ///
+    /// Lazily, and deliberately named as such: this runs only from `updateStatus()`, and no
+    /// production caller invokes that on the delivery completion or on the return to idle. It is
+    /// therefore NOT the pre-render gate — `setBlockedReason` declining the write is. This covers
+    /// the other half: a generation bump that happens after a legitimate write, which
+    /// `cancelIntentProcessing()` does.
+    ///
+    /// This is the structural half of the delivery reason's lifetime, and it exists because the
+    /// two halves are asymmetric: `updateDeliveryStatus` refuses to write a *status* for a
+    /// superseded generation and clears nothing on that path, while the paste completion's
+    /// `setBlockedReason(…, for: .delivery)` is ungated. A suppressed completion therefore
+    /// withholds the status line and persists "press Cmd-V" anyway — pointing at a clipboard that
+    /// has moved on, on the app's own instruction.
+    ///
+    /// A generation check here rather than a fifth enumerated clear site: the four existing clear
+    /// sites cover the paths someone thought of, and the paths that matter are the ones nobody
+    /// did. `cancelIntentProcessing()` is already one of them — it bumps `recordingGeneration`
+    /// without clearing — and `PasteTransactionCoordinator.failNow` releases the pending fence
+    /// *before* running the completion closure, so the interleaving is one inserted `await` away
+    /// from being reachable rather than latent.
+    private func expireStaleDeliveryBlockedReason() {
+        guard let generation = deliveryBlockedReasonGeneration,
+              generation != recordingGeneration else { return }
+        log("delivery blocked reason expired generation=\(generation) current=\(recordingGeneration)")
+        setBlockedReason(nil, for: .delivery)
+    }
+
+    // MARK: - Trigger release
+
+    /// Single key-up path for both hold-to-record triggers, so fn and the configurable
+    /// shortcut can never diverge on the only question that matters here: whether any audio
+    /// exists yet. A release that lands before the first PCM chunk is a tap that captured
+    /// nothing, and it is abandoned rather than transcribed.
+    func handleTriggerRelease(_ trigger: RecordingTrigger) {
+        guard activeTrigger == trigger else { return }
+        guard isRecording else {
+            log("\(trigger) released before audio started; cancelling pending start")
+            cancelPendingStart()
+            return
+        }
+        stopAndTranscribe()
+    }
+
+    /// Key-up with no audio yet. Two windows reach this: the microphone permission prompt
+    /// (nothing was ever started, so there is nothing to tear down) and the warm-up window
+    /// (the microphone is open and a realtime session may be negotiating, both of which must
+    /// be closed).
+    private func cancelPendingStart() {
+        if isWarmingUpCapture {
+            abandonWarmingCapture(
+                reason: "trigger released before first audio",
+                alert: .releasedBeforeAudio
+            )
+            return
+        }
+        // Nothing was started: the press landed while the microphone permission prompt was up
+        // and was consumed by it. Both key-up handlers used to carry a copy of this disclosure;
+        // it belongs here, once, with the rest of the no-audio branch.
+        let consumedByPermissionPrompt = microphonePermissionStartGate.isAwaitingResponse
+        resetRecordingIntent()
+        if consumedByPermissionPrompt {
+            setBlockedReason(Self.pressConsumedByPermissionPromptMessage, for: .pressConsumed)
+        }
+        updateStatus()
+    }
+
     // MARK: - Toggle
 
     public func toggleRecording() {
-        if isRecording { stopAndTranscribe() } else { startRecording(trigger: .manual) }
+        if captureIsActive { stopAndTranscribe() } else { startRecording(trigger: .manual) }
     }
 
     // MARK: - Start Recording (Streaming)
@@ -1006,6 +1639,7 @@ public final class RecordingEngine: ObservableObject {
         guard Self.canBeginRecording(
             isRecording: isRecording,
             isTranscribing: isTranscribing,
+            isWarmingUpCapture: isWarmingUpCapture,
             isAwaitingMicrophonePermission: microphonePermissionStartGate.isAwaitingResponse,
             isDeliveryPending: deliveryIsPending
         ) else {
@@ -1027,6 +1661,18 @@ public final class RecordingEngine: ObservableObject {
         activeTrigger = trigger
         keyboardShortcutIsDown = trigger == .keyboardShortcut
         conversationReply = nil
+        // Both transient reasons are superseded by a new press, and the delivery one is the
+        // reason this clearing exists: "transcript copied, press Cmd-V" was only ever cleared
+        // by the NEXT delivery's completion, so a recording that produced no delivery left it
+        // asserted indefinitely — and by then the clipboard may hold something else, so Cmd-V
+        // pastes the wrong thing on the app's own instruction. This recording is about to
+        // rewrite the clipboard, so the old instruction stops being true here.
+        //
+        // Accepted cost, stated rather than hidden: if this recording is itself cancelled, a
+        // still-accurate "press Cmd-V" has been cleared early. Losing a true message is a
+        // smaller failure than asserting a false one forever.
+        setBlockedReason(nil, for: .pressConsumed)
+        setBlockedReason(nil, for: .delivery)
 
         let myPID = ProcessInfo.processInfo.processIdentifier
         let frontmostApp = frontmostAppSnapshot()
@@ -1166,13 +1812,18 @@ public final class RecordingEngine: ObservableObject {
         }
     }
 
+    /// `isWarmingUpCapture` deliberately has no default. It is a safety input, and a default of
+    /// `false` is the permissive value: a call site that forgot it would compile, read as
+    /// startable during the warm-up window, and open a second recorder on top of a live one.
     nonisolated static func canBeginRecording(
         isRecording: Bool,
         isTranscribing: Bool,
+        isWarmingUpCapture: Bool,
         isAwaitingMicrophonePermission: Bool = false,
         isDeliveryPending: Bool = false
     ) -> Bool {
         !isRecording && !isTranscribing && !isAwaitingMicrophonePermission && !isDeliveryPending
+            && !isWarmingUpCapture
     }
 
     nonisolated static func shouldCaptureSelection(
@@ -1213,11 +1864,17 @@ public final class RecordingEngine: ObservableObject {
         Self.canBeginRecording(
             isRecording: isRecording,
             isTranscribing: isTranscribing,
+            isWarmingUpCapture: isWarmingUpCapture,
             isAwaitingMicrophonePermission: microphonePermissionStartGate.isAwaitingResponse,
             isDeliveryPending: deliveryIsPending
         )
     }
 
+    /// A capture attempt is in flight — warming up or live. Anything that used to read
+    /// `isRecording` because it meant "a recording is happening" reads this instead, so the
+    /// warm-up window can neither look idle nor accept a second start.
+    public var captureIsActive: Bool { isWarmingUpCapture || isRecording }
+
     /// Whether an in-flight Deciding/Answering/Rewriting delivery can be cancelled. Once a
     /// paste transaction is submitted the remaining window is sub-second and has its own
     /// target/clipboard safety rails, so cancellation stops being offered.
@@ -1296,21 +1953,32 @@ public final class RecordingEngine: ObservableObject {
         )
         activeCaptureConfiguration = captureConfiguration
         log("startNativeRecording apiKeyConfigured=\(!apiKey.isEmpty)")
-        if !apiKey.isEmpty {
-            startRealtimeStreaming(
-                apiKey: apiKey,
-                transcriptionLanguage: transcriptionLanguage
-            )
-        }
+        // Constructing the client is a plain allocation; the WebSocket handshake happens in
+        // `beginRealtimeStreaming` below, only once the recorder has actually started. The
+        // stream pipe needs the client at construction time, which is why the two steps are
+        // split rather than simply reordered. The handshake cannot be deferred further — to
+        // the first PCM chunk — without reworking `PCMStreamPipe`: `RealtimeTranscriptionClient`
+        // silently drops audio queued while `isStreaming` is false.
+        let client: RealtimeTranscriptionClient? = apiKey.isEmpty
+            ? nil
+            : RealtimeTranscriptionClient(apiKey: apiKey, homePath: home)
+        realtimeClient = client
 
-        let client = realtimeClient
         let streamPipe = PCMStreamPipe(chunkSize: 4_800, client: client)
         pcmStreamPipe = streamPipe
         let homePath = home
+        let captureGeneration = recordingGeneration
+        let confirmCapture: @MainActor @Sendable (UInt64) -> Void = { [weak self] generation in
+            self?.confirmCaptureIsLive(generation: generation)
+        }
         let firstChunkLogged = LockedFlag()
         let recorder = recorderFactory { data in
             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.
+                // Promoting the capture here — not when `start()` returned — is what makes a
+                // release during warm-up take the cancel path.
+                Task { @MainActor in confirmCapture(captureGeneration) }
             }
             streamPipe.append(data)
         }
@@ -1319,7 +1987,7 @@ public final class RecordingEngine: ObservableObject {
             try recorder.start()
             log("native recorder started")
             nativeRecorder = recorder
-            isRecording = true
+            isWarmingUpCapture = true
             recordingDuration = 0
             streamingText = ""
             liveTranscriptionText = ""
@@ -1327,7 +1995,12 @@ public final class RecordingEngine: ObservableObject {
             activeAudioPath = "\(audioDir)/recording-\(Self.timestampForFilename()).wav"
             let trigger = activeTrigger ?? .manual
             statusMessage = Self.recordingStatus(trigger: trigger)
+            // The pane must not look dead for the ~100 ms of warm-up, so it enters the
+            // listening layout immediately; Stop and Discard there both abandon the attempt.
             flowPhase = .listening
+            if let client {
+                beginRealtimeStreaming(client: client, transcriptionLanguage: transcriptionLanguage)
+            }
 
             recordingTimer = Timer.scheduledTimer(withTimeInterval: 0.1, repeats: true) { [weak self] _ in
                 Task { @MainActor [weak self] in
@@ -1336,6 +2009,12 @@ public final class RecordingEngine: ObservableObject {
             }
         } catch {
             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
+            // start gate refuses every press and no teardown path runs, with the input device
+            // possibly open. One added throwing call above is all it would take, so clear it
+            // here rather than rely on the current statement order.
+            isWarmingUpCapture = false
             realtimeClient?.stop()
             realtimeClient = nil
             streamingTask?.cancel()
@@ -1349,11 +2028,87 @@ public final class RecordingEngine: ObservableObject {
         }
     }
 
+    // MARK: - Capture confirmation
+
+    /// Promotes a warming capture to live on the first PCM chunk. Bound to the generation that
+    /// requested it, because a chunk already in the recorder's delivery queue can be handed to
+    /// the MainActor *after* a key-up has abandoned the attempt — that late chunk must never
+    /// resurrect a dead recording.
+    private func confirmCaptureIsLive(generation: UInt64) {
+        guard generation == recordingGeneration, isWarmingUpCapture else { return }
+        isWarmingUpCapture = false
+        isRecording = true
+        log("native capture confirmed live")
+    }
+
+    /// Tears down a capture attempt that never produced a sample. `recorder.start()` had
+    /// succeeded, so the microphone is open and a realtime session may be mid-handshake, but
+    /// there is no audio: running the transcription pipeline over that empty buffer is exactly
+    /// what made a short tap finish silently. `alert` is nil when the user asked for the
+    /// discard and therefore already knows the outcome.
+    private func abandonWarmingCapture(reason: String, alert: RecordingAttemptAlert?) {
+        guard isWarmingUpCapture else { return }
+        log("capture abandoned before first audio reason=\(reason)")
+        // 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
+
+        recordingTimer?.invalidate()
+        recordingTimer = nil
+
+        let recorder = nativeRecorder
+        nativeRecorder = nil
+        recorder?.stop()
+
+        realtimeClient?.stop()
+        realtimeClient = nil
+        streamingTask?.cancel()
+        streamingTask = nil
+        pcmStreamPipe?.cancel()
+        pcmStreamPipe = nil
+
+        isWarmingUpCapture = false
+        isRecording = false
+        isTranscribing = false
+        streamingText = ""
+        liveTranscriptionText = ""
+        recordedPCM.removeAll(keepingCapacity: true)
+        activeAudioPath = nil
+        activeCaptureConfiguration = nil
+        resetRecordingIntent()
+
+        if let alert {
+            discloseEmptyAttempt(alert)
+        } else {
+            // `updateStatus()`, never a direct "Ready": the state above is already cleared, so
+            // its early return does not fire, and going through it is what preserves a live
+            // `blockedReason` instead of overwriting the disclosure with "Ready".
+            updateStatus()
+        }
+    }
+
+    // MARK: - Visible outcome
+
+    /// Discloses an attempt that produced nothing, on the one surface that is always on screen.
+    ///
+    /// Routed through `setBlockedReason(_:for: .pressConsumed)` rather than a published field of
+    /// its own. That slot already means "a press was consumed and nothing was recorded", it is
+    /// already cleared by the next `startRecording`, and `MenuBarPresentation` already renders
+    /// `blockedReason` with a distinct icon and a distinct VoiceOver label. It also outlives a
+    /// timer: the disclosure is still on the glyph a minute later, which a three-second badge on
+    /// a surface the user had no reason to watch would not be.
+    private func discloseEmptyAttempt(_ alert: RecordingAttemptAlert) {
+        log("attempt produced no audio disclosure=\(alert)")
+        setBlockedReason(alert.message, for: .pressConsumed)
+        updateStatus()
+    }
+
     // MARK: - Real-time Streaming
 
-    private func startRealtimeStreaming(apiKey: String, transcriptionLanguage: String) {
-        let client = RealtimeTranscriptionClient(apiKey: apiKey, homePath: home)
-        realtimeClient = client
+    private func beginRealtimeStreaming(
+        client: RealtimeTranscriptionClient,
+        transcriptionLanguage: String
+    ) {
         let language = OpenAIAPIKeyStore.apiLanguageHint(for: transcriptionLanguage)
         log("realtime streaming task starting language=\(language.isEmpty ? "auto" : language)")
 
@@ -1399,6 +2154,12 @@ public final class RecordingEngine: ObservableObject {
     // MARK: - Cancel (discard without transcribing)
 
     public func cancelRecording() {
+        // Discard during warm-up: identical teardown, but the user asked for it, so the glyph
+        // stays quiet.
+        if isWarmingUpCapture {
+            abandonWarmingCapture(reason: "discarded during warm-up", alert: nil)
+            return
+        }
         guard isRecording else { return }
         log("cancelRecording")
 
@@ -1423,13 +2184,21 @@ public final class RecordingEngine: ObservableObject {
         activeAudioPath = nil
         activeCaptureConfiguration = nil
         resetRecordingIntent()
-        statusMessage = "Ready"
-        flowPhase = .idle
+        // Same reason as the warm-up abandon path: this used to assign "Ready" directly and
+        // silently discard a live trigger-blocked warning.
+        updateStatus()
     }
 
     // MARK: - Stop & Transcribe
 
     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
+        // pipeline (and a CLI round trip) on an empty buffer.
+        if isWarmingUpCapture {
+            abandonWarmingCapture(reason: "stopped during warm-up", alert: .releasedBeforeAudio)
+            return
+        }
         guard isRecording else { return }
         let pipelineTrace = RecordingPipelineTrace()
         log(pipelineTrace.message(stage: "release"))
@@ -1480,7 +2249,9 @@ public final class RecordingEngine: ObservableObject {
             ))
 
             let streamingResult = await client?.finish(
-                timeoutMilliseconds: Self.realtimeFinishTimeoutMilliseconds,
+                timeoutMilliseconds: Self.realtimeSettleBudgetMilliseconds(
+                    pcmByteCount: self.recordedPCM.count
+                ),
                 pipelineID: pipelineTrace.id,
                 pipelineStartedUptimeMilliseconds: pipelineTrace.startedUptimeMilliseconds
             )
@@ -1558,7 +2329,8 @@ public final class RecordingEngine: ObservableObject {
                     postProcessingMode: postProcessingMode,
                     transcript: realtimeFastPathText,
                     hasSelection: selectionToken != nil,
-                    intentDetectionEnabled: processingConfiguration.intentDetectionEnabled
+                    intentDetectionEnabled: processingConfiguration.intentDetectionEnabled,
+                    enhanceTriggersJSON: processingConfiguration.enhanceTriggersJSON
                 ) {
                     self.isTranscribing = false
                     _ = Self.deliverRealtimeBeforePersistence(
@@ -1693,7 +2465,18 @@ public final class RecordingEngine: ObservableObject {
                 } else {
                     self.log("no audio captured")
                     self.pipelineDeliveryGate.abandonPipeline(pipelineGeneration)
-                    self.finish(resolved.failureStatus ?? "No audio captured")
+                    // The one failure the user has no other way to notice: nothing was typed,
+                    // nothing appeared, and the status line lives behind a click on a menu-bar
+                    // glyph that never changed. So disclose it on the glyph too.
+                    //
+                    // One message, used for both. `MenuBarPresentation` renders the blocked
+                    // state as `statusText = blockedReason`, so passing the generic constant here
+                    // while `finish` held a specific `failureStatus` would replace the specific
+                    // diagnosis with "No audio captured" in every surface that reads the
+                    // presentation — losing the more useful of the two.
+                    let failure = resolved.failureStatus ?? RecordingAttemptAlert.noAudioCaptured.message
+                    self.finish(failure)
+                    self.setBlockedReason(failure, for: .pressConsumed)
                 }
             }
 
@@ -1733,7 +2516,8 @@ public final class RecordingEngine: ObservableObject {
         pcmByteCount: Int,
         language: String
     ) -> String? {
-        guard finishResult.settled, finishResult.error == nil else { return nil }
+        // Transport failures cannot settle, so a settled transcript outranks incidental server errors.
+        guard finishResult.settled else { return nil }
         guard let text = safeRealtimeFallbackTranscript(
             realtimeText: finishResult.text,
             language: language
@@ -1741,18 +2525,39 @@ public final class RecordingEngine: ObservableObject {
         return shouldFallbackFromPartialRealtime(text: text, pcmByteCount: pcmByteCount) ? nil : text
     }
 
-    /// Delivery may only run ahead of persistence for transcripts the local screen already
+    /// Delivery may only run ahead of persistence for transcripts the local screens already
     /// decided are plain dictation: the paste is near-instant, so persistence is deferred by
     /// milliseconds. Command/conversation-shaped transcripts persist first — their delivery
     /// can block on the classifier, the assistant, or the rewrite CLI, and the recording
     /// must already be durable by then.
+    ///
+    /// `off` mode never rewrites, so plain dictation always qualifies. `auto` mode
+    /// qualifies only when `EnhancementScreen` proves the helper cannot rewrite the
+    /// transcript — enhancement-eligible speech must keep pasting the helper's output,
+    /// which only exists after persistence. `always` mode rewrites unconditionally and
+    /// therefore always persists first.
     nonisolated static func shouldPasteBeforePersistence(
         postProcessingMode: String,
         transcript: String,
         hasSelection: Bool,
-        intentDetectionEnabled: Bool
+        intentDetectionEnabled: Bool,
+        // No default: "[]" decodes successfully to "no configured triggers", which
+        // silently fails OPEN for a caller that forgets the argument — the opposite
+        // of the fail-closed contract documented on EnhancementScreen. Every caller
+        // must state the configured triggers explicitly (review F2 on #30).
+        enhanceTriggersJSON: String
     ) -> Bool {
-        guard PostProcessingMode(rawValue: postProcessingMode) == .off else { return false }
+        switch PostProcessingMode(rawValue: postProcessingMode) {
+        case .off:
+            break
+        case .auto:
+            guard !EnhancementScreen.mayRequireEnhancement(
+                text: transcript,
+                enhanceTriggersJSON: enhanceTriggersJSON
+            ) else { return false }
+        default:
+            return false
+        }
         guard intentDetectionEnabled else { return true }
         return IntentScreen.screen(text: transcript, hasSelection: hasSelection)?.intent == .dictate
     }
@@ -3265,7 +4070,17 @@ public final class RecordingEngine: ObservableObject {
 
         let pasteDelay: TimeInterval = alreadyFrontmost ? 0.15 : 0.5
         var ownedPasteboardChangeCount: Int?
+        var clipboardWrite: PasteboardWriteResult?
         var clipboardOwnershipWasLost = false
+        // Focused field of the target app as it read immediately before the keystroke. The
+        // read-back after the keystroke is compared against this and against nothing else.
+        var deliveryProbe: FocusedTextProbe?
+        // What the read-back proved, and how many reads it took. Both stay at their initial
+        // values when the paste failed before the keystroke, so the log reports "no read-back"
+        // rather than borrowing a verdict from a previous paste.
+        var deliveryEvidence: PasteDeliveryEvidence = .unverified(.readBackNotAttempted)
+        var readBackAttempts = 0
+        lastPasteSecureInputProbe = nil
         updateDeliveryStatus("Pasting...", kind: .progress, pipelineGeneration: pipelineGeneration)
         let accepted = pasteTransactionCoordinator.submit(
             text: text,
@@ -3299,14 +4114,36 @@ public final class RecordingEngine: ObservableObject {
                 if restoreClipboard {
                     previousClipboard = ClipboardSnapshot(pasteboard: .general)
                 }
+                // Captured before the clipboard write rather than immediately before the
+                // keystroke: the readiness checks that follow re-validate focus anyway, and
+                // two Accessibility round trips must not sit between the payload check and
+                // the keystroke. A focus move in the gap is caught by the read-back, which
+                // refuses to compare across a changed element.
+                deliveryProbe = FocusedTextProbe.capture(pid: app.processIdentifier)
             },
             writeAttempted: { result in
                 ownedPasteboardChangeCount = result.ownershipChangeCount
-            }
+                clipboardWrite = result
+            },
+            verify: {
+                guard let deliveryProbe else { return .unverified(.readBackNotAttempted) }
+                readBackAttempts += 1
+                let evidence = PasteDeliveryVerifier.classify(
+                    pastedText: text,
+                    baseline: deliveryProbe.baseline,
+                    readBack: deliveryProbe.readBack()
+                )
+                deliveryEvidence = evidence
+                return evidence
+            },
+            verificationDelay: Self.pasteReadBackInterval,
+            verificationAttempts: Self.pasteReadBackAttempts
         ) { transaction, outcome in
-            let posted = outcome == .pasted
             let accessibilityTrusted = AXIsProcessTrusted()
-            let completedTranscriptAlreadyOnClipboard = outcome == .targetUnavailable
+            // Same reason the two static predicates below switch instead of comparing: a `==`
+            // test answers `false` for any outcome added later, and this feeds
+            // `shouldCopyAfterPasteFailure`, which decides whether the transcript is re-copied.
+            let completedTranscriptAlreadyOnClipboard = Self.outcomeLeavesTranscriptOnClipboard(outcome)
                 && !restoreClipboard
                 && (ownedPasteboardChangeCount.map {
                     Self.clipboardStillOwned(.general, text: transaction.text, changeCount: $0)
@@ -3321,15 +4158,42 @@ public final class RecordingEngine: ObservableObject {
             let copiedAfterFailure = shouldCopyAfterFailure
                 && Self.writeClipboardPreservingOnFailure(transaction.text, to: .general)
             self.log("paste outcome=\(outcome) target=\(app.bundleIdentifier ?? "?") alreadyFrontmost=\(alreadyFrontmost) transaction=\(transaction.id)")
+            // The line to read when asking "did the text land?". Every step reports itself, so
+            // a posted keystroke can no longer stand in for delivery.
+            self.log(PasteDeliveryReport(
+                targetBundleIdentifier: app.bundleIdentifier,
+                characterCount: transaction.text.count,
+                clipboardWriteVerified: clipboardWrite?.verified ?? false,
+                clipboardChangeCountAdvanced: clipboardWrite?.changeCountAdvanced ?? false,
+                attempt: .forOutcome(outcome),
+                secureInput: self.lastPasteSecureInputProbe,
+                evidence: deliveryEvidence,
+                readBackAttempts: readBackAttempts
+            ).logLine)
             if let pipelineTrace {
                 self.log(pipelineTrace.message(
-                    stage: posted ? "paste_posted" : "paste_failed",
+                    stage: Self.pasteTraceStage(for: outcome),
                     detail: "chars=\(transaction.text.count)"
                 ))
             }
             deliveryCompleted?()
             let message = switch outcome {
             case .pasted: "Pasted (\(transaction.text.count) chars)"
+            case .deliveryNotObserved: restoreClipboard
+                ? "Paste did not reach the target app"
+                : "Paste did not reach the target app — text kept on the clipboard"
+            case .deliveredUnverified: restoreClipboard
+                ? "Paste sent, delivery unconfirmed"
+                : "Paste sent, delivery unconfirmed — text kept on the clipboard"
+            // One message either way, because the clipboard is kept either way — see the
+            // `shouldRestore` switch in `settlement`. Telling the owner to press Cmd-V is only
+            // honest if the transcript is still there, so this branch may not depend on
+            // `restoreClipboard`. When restore WAS requested, say that it was overridden
+            // rather than letting the owner discover it.
+            case .secureInputActive: restoreClipboard
+                ? "This field blocks typing (secure input) — transcript kept on the clipboard "
+                    + "instead of restoring it, press Cmd-V"
+                : "This field blocks typing (secure input) — transcript copied, press Cmd-V"
             case .targetUnavailable: Self.targetUnavailableDeliveryStatus(
                 deliveryKind: deliveryKind,
                 accessibilityTrusted: accessibilityTrusted,
@@ -3344,11 +4208,35 @@ public final class RecordingEngine: ObservableObject {
                 ? "Paste failed because the paste event could not be posted"
                 : "Copied, but paste event could not be posted"
             }
+            // `updateDeliveryStatus` writes `statusMessage`, and `updateStatus()` rewrites it to
+            // "Ready" on the next return to idle. A transient success line can afford that;
+            // "press Cmd-V" cannot, because it is the only thing telling the owner their
+            // transcript is recoverable. So the secure-input reason is persisted through the
+            // one field every surface reads.
+            //
+            // ONLY this outcome persists, deliberately. `.deliveryNotObserved` also leaves the
+            // transcript on the clipboard, but it has a documented false negative — pasting text
+            // identical to the selection it replaces reads as "unchanged" — so persisting it
+            // would raise a standing warning over a paste that worked. `.deliveredUnverified`
+            // means "could not tell", and a standing blocked banner would over-claim it. Secure
+            // input has no such path: it is measured from the window-session dictionary, and an
+            // uninterrogable session yields `.unknown`, which never reaches here.
+            // AFTER `updateDeliveryStatus`, not before: that call clears the delivery reason so
+            // statuses which produce no outcome cannot leave a stale one behind, and this is the
+            // one caller whose reason has to outlive its own status line.
             self.updateDeliveryStatus(
                 message,
-                kind: posted ? .success : .failure,
+                kind: Self.deliveryStatusKind(for: outcome),
                 pipelineGeneration: transaction.generation
             )
+            // Stamped with the delivery's OWN generation, not the engine's current one: this
+            // closure can run after `recordingGeneration` has advanced, and binding to the
+            // current value would mark a superseded reason fresh. `updateStatus()` expires it.
+            self.setBlockedReason(
+                Self.isSecureInputOutcome(outcome) ? message : nil,
+                for: .delivery,
+                generation: transaction.generation
+            )
         } settlement: { transaction, outcome in
             let pasteboard = NSPasteboard.general
             let stillOwnsChangeCount = ownedPasteboardChangeCount.map {
@@ -3368,7 +4256,16 @@ public final class RecordingEngine: ObservableObject {
             let shouldRestore = switch outcome {
             case .clipboardWriteFailed:
                 stillOwnsChangeCount
-            case .targetUnavailable, .clipboardOwnershipLost, .eventPostFailed, .pasted:
+            // Never restore over secure input, even when `restoreClipboard` was requested.
+            // By the time this outcome is reachable the payload writer has already run, so the
+            // transcript IS the clipboard — and the status line has just told the owner to press
+            // Cmd-V. Restoring would delete the exact text the app told them to paste. This
+            // deliberately overrides an explicit opt-in, which is why the status message for
+            // this outcome says the clipboard was kept instead of restored.
+            case .secureInputActive:
+                false
+            case .targetUnavailable, .clipboardOwnershipLost, .eventPostFailed, .pasted,
+                 .deliveryNotObserved, .deliveredUnverified:
                 stillOwnsPayload
             }
             if shouldRestore {
@@ -3387,12 +4284,42 @@ public final class RecordingEngine: ObservableObject {
         }
     }
 
+    /// Whether an outcome ends with the transcript still sitting on the clipboard because the
+    /// paste never consumed it — so re-copying it would be redundant.
+    ///
+    /// Exhaustive on purpose. `.secureInputActive` answers `false` here even though it *does*
+    /// leave the transcript on the clipboard: it gets there because `shouldRestore` refuses to
+    /// restore, not because the paste was abandoned before the clipboard was written, and
+    /// `shouldCopyAfterPasteFailure` is additionally gated on `!accessibilityTrusted`, which is
+    /// never the path secure input takes.
+    nonisolated static func outcomeLeavesTranscriptOnClipboard(_ outcome: PasteDeliveryOutcome) -> Bool {
+        switch outcome {
+        case .targetUnavailable: true
+        case .pasted, .deliveryNotObserved, .deliveredUnverified, .clipboardOwnershipLost,
+             .clipboardWriteFailed, .eventPostFailed, .secureInputActive: false
+        }
+    }
+
     nonisolated static func clipboardOwnershipWasLostAfterPasteFailure(
         outcome: PasteDeliveryOutcome,
         hasOwnershipToken: Bool,
         stillOwnsPayload: Bool
     ) -> Bool {
-        outcome == .targetUnavailable && hasOwnershipToken && !stillOwnsPayload
+        // Switched rather than compared against `.targetUnavailable` so the compiler forces a
+        // decision here when an outcome is added. A `==` comparison answers `false` for every
+        // new case without anyone having considered it, and this predicate decides whether the
+        // engine still believes it owns the transcript — guessing wrong loses the text.
+        let outcomeCanStrandThePayload: Bool
+        switch outcome {
+        case .targetUnavailable:
+            outcomeCanStrandThePayload = true
+        // Secure input cannot strand the payload: nothing else wrote to the clipboard, and the
+        // transcript is deliberately kept there.
+        case .pasted, .deliveryNotObserved, .deliveredUnverified, .clipboardOwnershipLost,
+             .clipboardWriteFailed, .eventPostFailed, .secureInputActive:
+            outcomeCanStrandThePayload = false
+        }
+        return outcomeCanStrandThePayload && hasOwnershipToken && !stillOwnsPayload
     }
 
     @discardableResult
@@ -3418,18 +4345,21 @@ public final class RecordingEngine: ObservableObject {
         _ text: String,
         to pasteboard: NSPasteboard
     ) -> PasteboardWriteResult {
+        let changeCountBeforeWrite = pasteboard.changeCount
         let clearedChangeCount = pasteboard.clearContents()
         guard pasteboard.setString(text, forType: .string) else {
             return PasteboardWriteResult(
                 verified: false,
-                ownershipChangeCount: clearedChangeCount
+                ownershipChangeCount: clearedChangeCount,
+                changeCountAdvanced: clearedChangeCount > changeCountBeforeWrite
             )
         }
         let writtenChangeCount = pasteboard.changeCount
         let storedText = pasteboard.string(forType: .string)
         return PasteboardWriteResult(
             verified: pasteboard.changeCount == writtenChangeCount && storedText == text,
-            ownershipChangeCount: writtenChangeCount
+            ownershipChangeCount: writtenChangeCount,
+            changeCountAdvanced: writtenChangeCount > changeCountBeforeWrite
         )
     }
 
@@ -3473,7 +4403,19 @@ public final class RecordingEngine: ObservableObject {
         clipboardOwnershipWasLost: Bool = false,
         completedTranscriptAlreadyOnClipboard: Bool = false
     ) -> Bool {
-        outcome == .targetUnavailable
+        // Switched for the same reason as `clipboardOwnershipWasLostAfterPasteFailure`: a `==`
+        // test silently answers `false` for any outcome added later. Secure input already leaves
+        // the transcript on the clipboard, so re-copying it would be redundant at best — but that
+        // is a decision the compiler should make someone state, not one to inherit by accident.
+        let outcomeNeedsClipboardFallback: Bool
+        switch outcome {
+        case .targetUnavailable:
+            outcomeNeedsClipboardFallback = true
+        case .pasted, .deliveryNotObserved, .deliveredUnverified, .clipboardOwnershipLost,
+             .clipboardWriteFailed, .eventPostFailed, .secureInputActive:
+            outcomeNeedsClipboardFallback = false
+        }
+        return outcomeNeedsClipboardFallback
             && !accessibilityTrusted
             && !clipboardOwnershipWasLost
             && !completedTranscriptAlreadyOnClipboard
@@ -3533,6 +4475,11 @@ public final class RecordingEngine: ObservableObject {
     enum DeliveryStatusKind: Equatable, Sendable {
         case progress
         case success
+        /// The pipeline finished but delivery could not be observed. Presented like a finished
+        /// run — the recording is safe and the text is on the clipboard — while the message
+        /// itself says the paste is unconfirmed. Never folded into `.success`: that is the
+        /// false positive this state exists to avoid.
+        case unverified
         case failure
     }
 
@@ -3542,11 +4489,48 @@ public final class RecordingEngine: ObservableObject {
     ) -> RecordingFlowPhase {
         switch kind {
         case .progress: .processing(message)
-        case .success: .ready(message)
+        case .success, .unverified: .ready(message)
         case .failure: .failed(message)
         }
     }
 
+    /// Whether an outcome leaves a blocker the owner has to act on, so its explanation must
+    /// outlive the delivery status rather than being overwritten with "Ready".
+    ///
+    /// Written as an exhaustive switch rather than `if case`, so adding a `PasteDeliveryOutcome`
+    /// forces a decision here instead of silently defaulting to invisible.
+    nonisolated static func isSecureInputOutcome(_ outcome: PasteDeliveryOutcome) -> Bool {
+        switch outcome {
+        case .secureInputActive: true
+        case .pasted, .deliveryNotObserved, .deliveredUnverified, .targetUnavailable,
+             .clipboardOwnershipLost, .clipboardWriteFailed, .eventPostFailed: false
+        }
+    }
+
+    /// Only observed delivery is a success. An unreadable target is its own state, and both a
+    /// contradicted read-back and a refused post are failures.
+    nonisolated static func deliveryStatusKind(for outcome: PasteDeliveryOutcome) -> DeliveryStatusKind {
+        switch outcome {
+        case .pasted: .success
+        case .deliveredUnverified: .unverified
+        case .deliveryNotObserved, .secureInputActive, .targetUnavailable,
+             .clipboardOwnershipLost, .clipboardWriteFailed, .eventPostFailed: .failure
+        }
+    }
+
+    /// 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 pasteTraceStage(for outcome: PasteDeliveryOutcome) -> String {
+        switch outcome {
+        case .pasted: "paste_delivery_confirmed"
+        case .deliveredUnverified: "paste_delivery_unverified"
+        case .deliveryNotObserved: "paste_delivery_not_observed"
+        case .secureInputActive, .targetUnavailable, .clipboardOwnershipLost,
+             .clipboardWriteFailed, .eventPostFailed: "paste_failed"
+        }
+    }
+
     private func updateDeliveryStatus(
         _ message: String,
         kind: DeliveryStatusKind,
@@ -3565,6 +4549,18 @@ public final class RecordingEngine: ObservableObject {
         }
         statusMessage = message
         flowPhase = Self.flowPhase(forDeliveryStatus: message, kind: kind)
+        // A delivery status that actually reaches the screen replaces whatever explanation was
+        // there, so a persisted reason must not survive it — otherwise `updateStatus()`
+        // resurfaces it on the next return to idle. This closes the two leaks that produce no
+        // `PasteDeliveryOutcome` at all, and which clearing on `startRecording()` therefore
+        // cannot reach: the "Finish the previous paste before trying again" rejection, and the
+        // conversation route's "Answered".
+        //
+        // ORDERING: the secure-input caller must call this FIRST and re-set its reason after,
+        // which it does. `macos-shortcut-contract.test.ts` asserts that order, because getting it
+        // backwards silently reinstates the invisible-blocked bug with every test still green.
+        setBlockedReason(nil, for: .delivery)
+        setBlockedReason(nil, for: .pressConsumed)
     }
 
     private func selectedRunningPasteTarget(