From 47ae16b5b9dd65ab72e174e6c9ae21274cfc4671 Mon Sep 17 00:00:00 2001
From: Fabian Meyer <44942030+dinooo13@users.noreply.github.com>
Date: Fri, 16 Oct 2026 15:29:11 +0200
Subject: [PATCH 01/16] Permission monitor: the two-second poll is a named
 constant

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Sources/Pladder/PermissionMonitor.swift | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Sources/Pladder/PermissionMonitor.swift b/Sources/Pladder/PermissionMonitor.swift
index 4368d2f..fa5be86 100644
--- a/Sources/Pladder/PermissionMonitor.swift
+++ b/Sources/Pladder/PermissionMonitor.swift
@@ -16,6 +16,8 @@ final class PermissionMonitor {
 
     @ObservationIgnored private var pollTask: Task<Void, Never>?
 
+    private static let pollInterval: Duration = .seconds(2)
+
     var needsAccessibility: Bool { !accessibilityTrusted }
     var needsMicrophone: Bool { microphoneStatus != .authorized }
     var needsAnyPermission: Bool { needsAccessibility || needsMicrophone }
@@ -64,7 +66,7 @@ final class PermissionMonitor {
         pollTask?.cancel()
         pollTask = Task { [weak self] in
             while !Task.isCancelled {
-                try? await Task.sleep(for: .seconds(2))
+                try? await Task.sleep(for: Self.pollInterval)
                 guard let self else { return }
                 self.refresh()
             }

From d1487b5eb683858169b9d92743f97b616b848a4e Mon Sep 17 00:00:00 2001
From: Fabian Meyer <44942030+dinooo13@users.noreply.github.com>
Date: Fri, 16 Oct 2026 15:29:12 +0200
Subject: [PATCH 02/16] CI: a comment naming a docs/ heading that does not
 exist fails; ARCHITECTURE.md says where each number lives

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/docs.yml    |  27 ++++++++
 docs/ARCHITECTURE.md          |  65 ++++++++++++++++++
 scripts/check-doc-pointers.sh | 120 ++++++++++++++++++++++++++++++++++
 3 files changed, 212 insertions(+)
 create mode 100644 .github/workflows/docs.yml
 create mode 100755 scripts/check-doc-pointers.sh

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..903227e
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,27 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'Sources/**'
+      - 'Tests/**'
+      - 'scripts/check-doc-pointers.sh'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'Sources/**'
+      - 'Tests/**'
+      - 'scripts/check-doc-pointers.sh'
+      - '.github/workflows/docs.yml'
+
+jobs:
+  doc-pointers:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - name: Comments point at headings that exist
+        run: ./scripts/check-doc-pointers.sh
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index d362749..586da5e 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -5,6 +5,10 @@ made is in the Decisions table of [CLAUDE.md](../CLAUDE.md#decisions); why the
 release-to-paste path is fast is in [PERFORMANCE.md](PERFORMANCE.md). This
 file is the map: what runs where, in what order, and what each part relies on.
 
+Comments in the code point at its sections by name, and
+`scripts/check-doc-pointers.sh` fails CI when a pointer names a heading
+that does not exist. Rename a section together with its pointers.
+
 ## Modules
 
 | Target | Holds | Frameworks that matter |
@@ -485,3 +489,64 @@ Errors and progress go to stderr, so stdout holds only results.
 Fixtures are audio files with a sibling `.txt` holding the script, made by
 `scripts/make-fixtures.sh`. The procedures are in
 [BENCHMARKS.md](BENCHMARKS.md).
+
+## Where the numbers live
+
+The timings and limits this file and CLAUDE.md quote, and the constant each
+comes from. A change to a constant updates its row here and the prose that
+quotes it. Where an initialiser's default is the constant, the app relies on
+that default.
+
+| Number | What | Constant | File |
+|---|---|---|---|
+| 0.3 s | Shortest recording that is transcribed | `DictationCoordinator.minimumDuration` | `PladderCore/DictationCoordinator.swift` |
+| 4 words | Shortest dictation that is polished | `DictationCoordinator.minimumPolishWords` | `PladderCore/DictationCoordinator.swift` |
+| 10 min | Recording cap | `DictationCoordinator.maximumDuration` | `PladderCore/DictationCoordinator.swift` |
+| 1 s | Feed loop cadence | `DictationCoordinator.feedInterval` | `PladderCore/DictationCoordinator.swift` |
+| 500 ms | Live pass cadence (Live Transcript) | `DictationCoordinator.livePassInterval` | `PladderCore/DictationCoordinator.swift` |
+| 2 s | Warm loop cadence | `DictationCoordinator.warmupInterval` | `PladderCore/DictationCoordinator.swift` |
+| 0.5 s | Length of a warm pass, 8,000 samples at 16 kHz | `DictationCoordinator.warmupSamples` (batch engine), `FluidAudioIncrementalEngine.warmupSamples` (streaming) | `PladderCore/DictationCoordinator.swift`, `PladderEngines/FluidAudioIncrementalEngine.swift` |
+| 2 s | How long an error shows before the state goes idle | `DictationCoordinator.errorDisplayDuration` | `PladderCore/DictationCoordinator.swift` |
+| 3 s | Quit waits this long for `shutdown()` | `AppDelegate.shutdownDeadline` | `Pladder/PladderApp.swift` |
+| 5 s | SIGTERM ends the process after this | `AppDelegate.signalExitDeadline` | `Pladder/PladderApp.swift` |
+| 5 s | Grid a live pass's window is cut on, 80,000 samples | `FluidAudioIncrementalEngine.windowHopSamples` | `PladderEngines/FluidAudioIncrementalEngine.swift` |
+| 250 ms | Engine status poll while loading | `EngineLoader.init(pollInterval:)` | `PladderCore/EngineLoader.swift` |
+| 400 ms | A shorter press of a hybrid key latches | `DictationCoordinator.holdThreshold`, handed to `HotkeyGestureTracker` | `PladderCore/DictationCoordinator.swift` |
+| 50 ms | Bounce window, and the settle after it | `DictationCoordinator.bounceWindow`, handed to `HotkeyGestureTracker` | `PladderCore/DictationCoordinator.swift` |
+| 1 s | Interrupted press window | `HotkeyChordSet.init(interruptionWindow:)`, handed to each `HotkeyChordTracker` | `PladderCore/HotkeyChordSet.swift` |
+| 3 s | Secure Event Input sustained before Carbon takes over | `SustainedCondition.init(threshold:)` | `PladderCore/Support/SustainedCondition.swift` |
+| 2 s | Retry of a tap that could not be installed | `GlobalHotkeyMonitor.retryInterval` | `PladderSystem/GlobalHotkeyMonitor.swift` |
+| 2 s | Permission and Secure Event Input poll | `PermissionMonitor.pollInterval` | `Pladder/PermissionMonitor.swift` |
+| 64 MB | Largest clipboard item the snapshot keeps | `ClipboardSnapshot.maximumItemBytes` | `PladderSystem/ClipboardSnapshot.swift` |
+| 400 ms | Earliest restore after Cmd+V; also when an owed Return goes out if nothing reads | `ClipboardKeeper.restoreFloor` | `PladderSystem/ClipboardKeeper.swift` |
+| 200 ms | Restore after the target app's last read | `ClipboardKeeper.readSettle` | `PladderSystem/ClipboardKeeper.swift` |
+| 8 s | Restore when nothing reads | `ClipboardKeeper.restoreCap` | `PladderSystem/ClipboardKeeper.swift` |
+| 50 ms | Return after the target app reads the paste | `PasteboardOutput.init(submitDelay:)` | `PladderSystem/PasteboardOutput.swift` |
+| 200 ms | Mute lands this long after key-down | `OutputMuteController.init(delay:)` | `PladderCore/Support/OutputMuteController.swift` |
+| 150 ms | The pill appears this long into a recording | `OverlayController.presentDelay` | `Pladder/Overlay/OverlayController.swift` |
+| 0.18 | Custom-word match: edit distance over the longer length must be under this | `CustomWordCorrector.threshold` | `PladderCore/Processors/CustomWordCorrector.swift` |
+| 0.3 | Factor on the score when the Soundex codes agree | `CustomWordCorrector.soundexBonus` | `PladderCore/Processors/CustomWordCorrector.swift` |
+| 4 tokens | Longest run tried as one custom word | `CustomWordCorrector.maxNGram` | `PladderCore/Processors/CustomWordCorrector.swift` |
+| 3 characters | Key or candidate this short must match exactly | `CustomWordCorrector.exactOnlyLength` | `PladderCore/Processors/CustomWordCorrector.swift` |
+| 1 edit, 5 characters | Soundex buys at most one edit on keys this short | `CustomWordCorrector.shortKeySoundexEdits`, `shortKeyLength` | `PladderCore/Processors/CustomWordCorrector.swift` |
+| 8 s | Polish budget | `TranscriptPolisher.init(timeout:)`, `S1MiniPolisher.init(timeout:)` | `PladderRefine/TranscriptPolisher.swift`, `PladderRefine/S1MiniPolisher.swift` |
+| 300 / 250 words | Polish chunk size, Apple's model / S1-mini | `TranscriptPolisher.chunkSize`, `S1MiniPolisher.chunkSize` | `PladderRefine/TranscriptPolisher.swift`, `PladderRefine/S1MiniPolisher.swift` |
+| 600 / 400 words | A dictation longer than this is chunked | `TranscriptPolisher.chunkThreshold`, `S1MiniPolisher.chunkThreshold` | `PladderRefine/TranscriptPolisher.swift`, `PladderRefine/S1MiniPolisher.swift` |
+| 1.5 × chunk size | Forced cut between words | `PolishChunking.hardLimit` | `PladderRefine/PolishChunking.swift` |
+| 16 MB | Checksum read size, and how often a cancel is checked | `ModelFiles.sha256(chunkSize:)` | `PladderRefine/ModelFiles.swift` |
+| 60 s | How long a pasted field is watched | `AXPasteObserver.init(observationWindow:)` | `PladderSystem/AXPasteObserver.swift` |
+| 8 × 125 ms | Retries to find the paste in the field | `AXPasteObserver.init(anchorRetries:anchorRetryInterval:)` | `PladderSystem/AXPasteObserver.swift` |
+| 2 words | Most words on either side of a correction | `CorrectionDiff.maximumWordsPerSide` | `PladderCore/Learning/CorrectionDiff.swift` |
+| 3 spans | More changed spans is a rewrite | `CorrectionDiff.maximumHunks` | `PladderCore/Learning/CorrectionDiff.swift` |
+| half, at least 2 words | More changed words of the paste is a rewrite | `CorrectionDiff.rewriteFraction`, `rewriteAllowance` | `PladderCore/Learning/CorrectionDiff.swift` |
+| 60 % | Share of the window a reading must still hold to be diffed | `CorrectionDiff.anchorCoverage` | `PladderCore/Learning/CorrectionDiff.swift` |
+| 2 edits, 1 up to 3 letters | Phonetic gate: largest edit distance, and for words this short | `PhoneticGate.maximumDistance`, `shortKeyDistance`, `shortKeyLength` | `PladderCore/Learning/PhoneticGate.swift` |
+| 3 | Proposals per paste | `CorrectionLearner.maximumProposalsPerPaste` | `PladderCore/Learning/CorrectionLearner.swift` |
+| 400 characters | Sentence around the correction the reviewer sees | `CorrectionLearner.sentenceLimit` | `PladderCore/Learning/CorrectionLearner.swift` |
+| 10 s | Correction review budget | `FoundationModelsCorrectionReviewer.init(timeout:)` | `PladderRefine/FoundationModelsCorrectionReviewer.swift` |
+
+Some numbers are measurements, not constants, and change only with a new
+measurement: the cold encoder pass costing about 110 ms more than a warm one
+([PERFORMANCE.md](PERFORMANCE.md#what-is-still-slow), 0.114 s on an M1),
+apps reading the pasteboard 0 to 25 ms after Cmd+V, and Universal Clipboard
+reading an unmarked write within about 15 ms.
diff --git a/scripts/check-doc-pointers.sh b/scripts/check-doc-pointers.sh
new file mode 100755
index 0000000..60e9763
--- /dev/null
+++ b/scripts/check-doc-pointers.sh
@@ -0,0 +1,120 @@
+#!/bin/bash
+# Fails when a Swift comment points at a docs/*.md heading that does not exist.
+# A pointer is `docs/X.md, "Section"` or `"Section" in docs/X.md`; a comment
+# split over several `//` lines is read as one. Headings are levels 1 to 3,
+# outside code fences, with backticks removed. A bare `docs/X.md` is fine as
+# long as the file exists.
+#
+# Plain bash 3.2 and POSIX awk, so it runs the same on macOS and ubuntu.
+
+set -eo pipefail
+cd "$(dirname "$0")/.."
+
+headings=$(mktemp)
+trap 'rm -f "$headings"' EXIT
+
+for doc in docs/*.md; do
+    awk -v doc="$doc" '
+        { sub(/\r$/, "") }
+        /^[ \t]*(```|~~~)/ { fenced = !fenced; next }
+        fenced { next }
+        match($0, /^#+ /) && RLENGTH <= 4 {
+            text = substr($0, RLENGTH + 1)
+            gsub(/`/, "", text)
+            sub(/[ \t#]+$/, "", text)
+            print doc "\t" text
+        }
+        END { print doc "\t" }
+    ' "$doc" >> "$headings"
+done
+
+files=()
+while IFS= read -r file; do files+=("$file"); done < <(find Sources Tests -name '*.swift' 2>/dev/null | LC_ALL=C sort)
+if [ ${#files[@]} -eq 0 ]; then
+    echo "no Swift files under Sources or Tests" >&2
+    exit 1
+fi
+
+awk -v headings="$headings" '
+    BEGIN {
+        while ((getline line < headings) > 0) {
+            tab = index(line, "\t")
+            doc = substr(line, 1, tab - 1)
+            exists[doc] = 1
+            section = substr(line, tab + 1)
+            if (section != "") known[doc SUBSEP section] = 1
+        }
+        close(headings)
+    }
+
+    function report(offset, message,    i) {
+        for (i = runLines; i > 1 && starts[i] > offset; i--) {}
+        printf "%s:%d: %s\n", runFile, runFirst + i - 1, message
+        failures++
+    }
+
+    # A missing file is reported once, by the bare-name pass.
+    function check(doc, section, offset) {
+        pointers++
+        if ((doc in exists) && !((doc SUBSEP section) in known))
+            report(offset, "no heading \"" section "\" in " doc)
+    }
+
+    # Every pointer in the joined comment run, in both orders, then every bare file name.
+    function scan(    rest, base, hit, doc, section, q) {
+        rest = run; base = 0
+        while (match(rest, /docs\/[A-Z]+\.md, "[^"]+"/)) {
+            hit = substr(rest, RSTART, RLENGTH)
+            doc = substr(hit, 1, index(hit, ",") - 1)
+            q = index(hit, "\"")
+            section = substr(hit, q + 1, length(hit) - q - 1)
+            check(doc, section, base + RSTART)
+            base += RSTART + RLENGTH - 1
+            rest = substr(rest, RSTART + RLENGTH)
+        }
+        rest = run; base = 0
+        while (match(rest, /"[^"]+" in docs\/[A-Z]+\.md/)) {
+            hit = substr(rest, RSTART, RLENGTH)
+            q = index(substr(hit, 2), "\"") + 1
+            section = substr(hit, 2, q - 2)
+            doc = substr(hit, q + 5)
+            check(doc, section, base + RSTART)
+            base += RSTART + RLENGTH - 1
+            rest = substr(rest, RSTART + RLENGTH)
+        }
+        rest = run; base = 0
+        while (match(rest, /docs\/[A-Z]+\.md/)) {
+            doc = substr(rest, RSTART, RLENGTH)
+            if (!(doc in exists)) report(base + RSTART, "no file " doc)
+            base += RSTART + RLENGTH - 1
+            rest = substr(rest, RSTART + RLENGTH)
+        }
+    }
+
+    function flush() {
+        if (runLines > 0) scan()
+        run = ""; runLines = 0
+    }
+
+    FNR == 1 { flush(); files++ }
+
+    {
+        line = $0
+        sub(/\r$/, "", line)
+        if (match(line, /^[ \t]*\/\/+[ \t]?/)) {
+            text = substr(line, RLENGTH + 1)
+            if (runLines == 0) { runFile = FILENAME; runFirst = FNR }
+            else run = run " "
+            starts[++runLines] = length(run) + 1
+            run = run text
+        } else {
+            flush()
+        }
+    }
+
+    END {
+        flush()
+        if (failures > 0) exit 1
+        printf "%d pointers to docs/ headings checked in %d Swift files.\n", pointers, files
+    }
+' "${files[@]}"

From e403b158a3bfad6a38eb381cc105a88316a7dddf Mon Sep 17 00:00:00 2001
From: Fabian Meyer <44942030+dinooo13@users.noreply.github.com>
Date: Fri, 16 Oct 2026 15:41:28 +0200
Subject: [PATCH 03/16] Tests: ManualClock wakes a waiter when its sleeper
 arrives, and waitUntil joins eventually in PladderTestSupport

`waitForSleeper(at:)` polled `deadlines` a millisecond at a time; a sleep now resumes the waiters it satisfies, and `waitForSleepers(_:)` does the same for a count, replacing four `waitUntil { clock.sleeperCount >= 2 }`. Both still end by themselves after two seconds, as a Gate does.

`waitUntil` moves from DictationCoordinatorTests to PladderTestSupport, and the coordinator tests' own `eventually` goes in favour of the shared one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../CoordinatorRegressionTests.swift          |  4 +-
 .../DictationCoordinatorTests.swift           | 24 +-----
 .../PladderCoreTests/EngineLoaderTests.swift  |  1 +
 Tests/PladderTestSupport/ManualClock.swift    | 77 ++++++++++++++-----
 Tests/PladderTestSupport/TestSupport.swift    | 21 +++++
 5 files changed, 85 insertions(+), 42 deletions(-)

diff --git a/Tests/PladderCoreTests/CoordinatorRegressionTests.swift b/Tests/PladderCoreTests/CoordinatorRegressionTests.swift
index c9d3681..67702f2 100644
--- a/Tests/PladderCoreTests/CoordinatorRegressionTests.swift
+++ b/Tests/PladderCoreTests/CoordinatorRegressionTests.swift
@@ -290,7 +290,7 @@ import Testing
         let (c, output, _) = makeCoordinator(clock: clock)
         await c.startIdle()
         await c.hotkeyPressed()
-        #expect(await waitUntil { clock.sleeperCount >= 2 })
+        #expect(await clock.waitForSleepers(2))
         clock.advance(by: c.maximumDuration - .seconds(1))
         #expect(c.state.isRecording)
         clock.advance(by: .seconds(1))
@@ -354,7 +354,7 @@ import Testing
         await c.hotkeyPressed()
         #expect(await waitUntil { warmPasses() == 1 })
         for expected in 2...4 {
-            #expect(await waitUntil { clock.sleeperCount >= 2 })
+            #expect(await clock.waitForSleepers(2))
             clock.advance(by: c.warmupInterval)
             #expect(await waitUntil { warmPasses() == expected })
         }
diff --git a/Tests/PladderCoreTests/DictationCoordinatorTests.swift b/Tests/PladderCoreTests/DictationCoordinatorTests.swift
index 59d0091..1e24e3d 100644
--- a/Tests/PladderCoreTests/DictationCoordinatorTests.swift
+++ b/Tests/PladderCoreTests/DictationCoordinatorTests.swift
@@ -389,26 +389,6 @@ func makeStreamingCoordinator(
     return (coordinator, output, capture, engine)
 }
 
-@MainActor
-func waitUntil(_ timeout: Duration = .seconds(2), _ condition: @MainActor () -> Bool) async -> Bool {
-    let deadline = ContinuousClock.now + timeout
-    while ContinuousClock.now < deadline {
-        if condition() { return true }
-        try? await Task.sleep(for: .milliseconds(10))
-    }
-    return condition()
-}
-
-// A dropped recording is idle at once; its microphone stops on a task after.
-func eventually(_ timeout: Duration = .seconds(2), _ condition: () async -> Bool) async -> Bool {
-    let deadline = ContinuousClock.now + timeout
-    while ContinuousClock.now < deadline {
-        if await condition() { return true }
-        try? await Task.sleep(for: .milliseconds(10))
-    }
-    return await condition()
-}
-
 extension DictationCoordinator {
     func startIdle(sourceLocation: SourceLocation = #_sourceLocation) async {
         start()
@@ -1342,7 +1322,7 @@ final class EventLog: @unchecked Sendable {
         await c.press(hotkey)
         hotkey.release()
         #expect(await waitUntil { c.isLatched })
-        #expect(await waitUntil { clock.sleeperCount >= 2 })
+        #expect(await clock.waitForSleepers(2))
         clock.advance(by: c.maximumDuration)
         await c.cycleFinished()
         #expect(output.inserted.count == 1)
@@ -1479,7 +1459,7 @@ final class EventLog: @unchecked Sendable {
         #expect(await waitUntil { c.state == .idle })
         #expect(hotkey.cancelKeyEnabled == [true, false, true, false])
         await c.hotkeyPressed()
-        #expect(await waitUntil { clock.sleeperCount >= 2 })
+        #expect(await clock.waitForSleepers(2))
         clock.advance(by: c.maximumDuration)
         #expect(await waitUntil { !c.state.isRecording })
         await c.inFlight?.value
diff --git a/Tests/PladderCoreTests/EngineLoaderTests.swift b/Tests/PladderCoreTests/EngineLoaderTests.swift
index ab2242e..49d0cee 100644
--- a/Tests/PladderCoreTests/EngineLoaderTests.swift
+++ b/Tests/PladderCoreTests/EngineLoaderTests.swift
@@ -1,4 +1,5 @@
 import Foundation
+import PladderTestSupport
 import Testing
 @testable import PladderCore
 
diff --git a/Tests/PladderTestSupport/ManualClock.swift b/Tests/PladderTestSupport/ManualClock.swift
index 2ab6f7b..e7d199d 100644
--- a/Tests/PladderTestSupport/ManualClock.swift
+++ b/Tests/PladderTestSupport/ManualClock.swift
@@ -10,11 +10,31 @@ public final class ManualClock: Clock, Sendable {
         let continuation: CheckedContinuation<Void, any Error>
     }
 
+    private struct Watcher {
+        let id: Int
+        let isMet: @Sendable ([Instant]) -> Bool
+        let continuation: CheckedContinuation<Bool, Never>
+    }
+
     private struct State {
         var now: Instant
         var nextID = 0
         var sleepers: [Sleeper] = []
         var cancelled: Set<Int> = []
+        var watchers: [Watcher] = []
+        var expired: Set<Int> = []
+
+        mutating func takeID() -> Int {
+            defer { nextID += 1 }
+            return nextID
+        }
+
+        mutating func takeMetWatchers() -> [Watcher] {
+            let deadlines = sleepers.map(\.deadline)
+            let met = watchers.filter { $0.isMet(deadlines) }
+            watchers.removeAll { watcher in met.contains { $0.id == watcher.id } }
+            return met
+        }
     }
 
     private let state: Mutex<State>
@@ -47,18 +67,16 @@ public final class ManualClock: Clock, Sendable {
     }
 
     public func sleep(until deadline: Instant, tolerance: Duration? = nil) async throws {
-        let id = state.withLock { state -> Int in
-            defer { state.nextID += 1 }
-            return state.nextID
-        }
+        let id = state.withLock { $0.takeID() }
         try await withTaskCancellationHandler {
             try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, any Error>) in
-                let early = state.withLock { state -> Result<Void, any Error>? in
-                    if state.cancelled.remove(id) != nil || Task.isCancelled { return .failure(CancellationError()) }
-                    if deadline <= state.now { return .success(()) }
+                let (early, met) = state.withLock { state -> (Result<Void, any Error>?, [Watcher]) in
+                    if state.cancelled.remove(id) != nil || Task.isCancelled { return (.failure(CancellationError()), []) }
+                    if deadline <= state.now { return (.success(()), []) }
                     state.sleepers.append(Sleeper(id: id, deadline: deadline, continuation: continuation))
-                    return nil
+                    return (nil, state.takeMetWatchers())
                 }
+                for watcher in met { watcher.continuation.resume(returning: true) }
                 if let early { continuation.resume(with: early) }
             }
         } onCancel: {
@@ -73,19 +91,42 @@ public final class ManualClock: Clock, Sendable {
         }
     }
 
-    // Waits in real time, but briefly, until a detached task has reached its sleep.
     public func waitForSleeper(at offset: Duration) async -> Bool {
         let deadline = start + offset
-        return await eventually { self.deadlines.contains(deadline) }
+        return await waitFor { $0.contains(deadline) }
     }
-}
 
-// Polls in real time, a millisecond at a time for up to about two seconds, for what a
-// detached task does on its own schedule.
-public func eventually(_ condition: @Sendable () async -> Bool) async -> Bool {
-    for _ in 0..<2_000 {
-        if await condition() { return true }
-        try? await Task.sleep(for: .milliseconds(1))
+    public func waitForSleepers(_ count: Int) async -> Bool {
+        await waitFor { $0.count >= count }
+    }
+
+    private func waitFor(_ isMet: @escaping @Sendable ([Instant]) -> Bool) async -> Bool {
+        let id = state.withLock { $0.takeID() }
+        // Ends the wait after two seconds, as a `Gate` does, so a regression fails rather than hangs.
+        let timeout = Task {
+            guard (try? await Task.sleep(for: .seconds(2))) != nil else { return }
+            self.expire(id)
+        }
+        defer { timeout.cancel() }
+        return await withCheckedContinuation { (continuation: CheckedContinuation<Bool, Never>) in
+            let early = state.withLock { state -> Bool? in
+                if state.expired.remove(id) != nil { return false }
+                if isMet(state.sleepers.map(\.deadline)) { return true }
+                state.watchers.append(Watcher(id: id, isMet: isMet, continuation: continuation))
+                return nil
+            }
+            if let early { continuation.resume(returning: early) }
+        }
+    }
+
+    private func expire(_ id: Int) {
+        let watcher = state.withLock { state -> Watcher? in
+            if let index = state.watchers.firstIndex(where: { $0.id == id }) {
+                return state.watchers.remove(at: index)
+            }
+            state.expired.insert(id)
+            return nil
+        }
+        watcher?.continuation.resume(returning: false)
     }
-    return await condition()
 }
diff --git a/Tests/PladderTestSupport/TestSupport.swift b/Tests/PladderTestSupport/TestSupport.swift
index 8d350f3..b662b60 100644
--- a/Tests/PladderTestSupport/TestSupport.swift
+++ b/Tests/PladderTestSupport/TestSupport.swift
@@ -61,3 +61,24 @@ public func scratchDirectory(_ name: String) throws -> URL {
     try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
     return dir
 }
+
+// Polls in real time: the fakes' counters are not observable.
+@MainActor
+public func waitUntil(_ timeout: Duration = .seconds(2), _ condition: @MainActor () -> Bool) async -> Bool {
+    let deadline = ContinuousClock.now + timeout
+    while ContinuousClock.now < deadline {
+        if condition() { return true }
+        try? await Task.sleep(for: .milliseconds(10))
+    }
+    return condition()
+}
+
+// Polls in real time, a millisecond at a time for up to about two seconds, for what a
+// detached task does on its own schedule.
+public func eventually(_ condition: @Sendable () async -> Bool) async -> Bool {
+    for _ in 0..<2_000 {
+        if await condition() { return true }
+        try? await Task.sleep(for: .milliseconds(1))
+    }
+    return await condition()
+}

From 6c45e6b479d05670e91993cd8a780b00327dd1a4 Mon Sep 17 00:00:00 2001
From: Fabian Meyer <44942030+dinooo13@users.noreply.github.com>
Date: Fri, 16 Oct 2026 15:41:35 +0200
Subject: [PATCH 04/16] Tests: the coordinator fakes hold on a Gate instead of
 sleeping

`FakeCapture.stop`, `FakeRefiner.refine` and the counting engine's warm pass slept 50 to 200 ms so a cancel, a press or a release would land while they ran. Each now waits on a Gate the test opens once it has seen that state. The warm pass's wait cannot be cancelled, like a CoreML pass in flight.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../CoordinatorRegressionTests.swift          | 12 ++++--
 .../DictationCoordinatorTests.swift           | 42 ++++++++++++-------
 2 files changed, 35 insertions(+), 19 deletions(-)

diff --git a/Tests/PladderCoreTests/CoordinatorRegressionTests.swift b/Tests/PladderCoreTests/CoordinatorRegressionTests.swift
index 67702f2..a7f6996 100644
--- a/Tests/PladderCoreTests/CoordinatorRegressionTests.swift
+++ b/Tests/PladderCoreTests/CoordinatorRegressionTests.swift
@@ -53,12 +53,16 @@ import Testing
     @Test func aPressRightAfterACancelKeepsItsUtterance() async {
         let engine = FakeStreamingEngine()
         let (c, output, capture, _) = await makeStreamingCoordinator(style: .compact, engine: engine)
-        await capture.setStopDelay(.milliseconds(150))
+        let stopGate = Gate()
+        await capture.setStopGate(stopGate)
         await c.startIdle()
         await c.hotkeyPressed()
         let cancel = Task { await c.cancelRecording() }
         #expect(await waitUntil { c.state == .idle })
-        await c.hotkeyPressed()
+        let press = Task { await c.hotkeyPressed() }
+        #expect(await waitUntil { c.state.isRecording })
+        await stopGate.open()
+        await press.value
         #expect(c.state.isRecording)
         await cancel.value
         c.hotkeyReleased()
@@ -92,7 +96,8 @@ import Testing
 
     @Test func aPressCancelledWhileItWaitsLeavesTheMicrophoneAlone() async {
         let (c, _, capture) = makeCoordinator()
-        await capture.setStopDelay(.milliseconds(150))
+        let stopGate = Gate()
+        await capture.setStopGate(stopGate)
         await c.startIdle()
         await c.hotkeyPressed()
         let cancel = Task { await c.cancelRecording() }
@@ -103,6 +108,7 @@ import Testing
         #expect(await waitUntil { c.state == .idle })
         let press = Task { await c.hotkeyPressed() }
         #expect(await waitUntil { c.state.isRecording })
+        await stopGate.open()
         _ = await (cancel.value, cancelledPress.value, cancelPress.value, press.value)
         #expect(c.state.isRecording)
         #expect(await capture.startCount == 2)
diff --git a/Tests/PladderCoreTests/DictationCoordinatorTests.swift b/Tests/PladderCoreTests/DictationCoordinatorTests.swift
index 1e24e3d..9495f59 100644
--- a/Tests/PladderCoreTests/DictationCoordinatorTests.swift
+++ b/Tests/PladderCoreTests/DictationCoordinatorTests.swift
@@ -17,7 +17,7 @@ actor FakeCapture: AudioCapture {
     var startCount = 0
     var stopCount = 0
     var levelContinuation: AsyncStream<Float>.Continuation?
-    var stopDelay: Duration = .zero
+    var stopGate: Gate?
 
     func start() async throws -> AsyncStream<Float> {
         startCount += 1
@@ -33,7 +33,7 @@ actor FakeCapture: AudioCapture {
     func stop() async -> CapturedAudio {
         stopCount += 1
         levelContinuation?.finish()
-        if stopDelay > .zero { try? await Task.sleep(for: stopDelay) }
+        await stopGate?.wait()
         return CapturedAudio(samples: samplesToReturn)
     }
 
@@ -41,7 +41,7 @@ actor FakeCapture: AudioCapture {
 
     func setSamples(_ s: [Float]) { samplesToReturn = s }
     func setDrainSamples(_ s: [Float]) { drainSamples = s }
-    func setStopDelay(_ d: Duration) { stopDelay = d }
+    func setStopGate(_ gate: Gate) { stopGate = gate }
     func emitLevel(_ l: Float) { levelContinuation?.yield(l) }
 }
 
@@ -126,20 +126,20 @@ final class FakeRefiner: TranscriptRefiner, @unchecked Sendable {
     private var _calls: [String] = []
     private var _prepareCount = 0
     private let result: String?
-    private let delay: Duration
+    private let gate: Gate?
     var calls: [String] { lock.withLock { _calls } }
     var prepareCount: Int { lock.withLock { _prepareCount } }
 
-    init(result: String? = "polished", delay: Duration = .zero) {
+    init(result: String? = "polished", gate: Gate? = nil) {
         self.result = result
-        self.delay = delay
+        self.gate = gate
     }
 
     func prepare() async { lock.withLock { _prepareCount += 1 } }
 
     func refine(_ text: String) async -> String? {
         lock.withLock { _calls.append(text) }
-        if delay > .zero { try? await Task.sleep(for: delay) }
+        await gate?.wait()
         return result
     }
 }
@@ -184,15 +184,15 @@ actor CountingEngine: TranscriptionEngine {
     nonisolated let displayName = "Counting"
     private(set) var status: EngineStatus = .unloaded
     private let recorder = Recorder<Int>()
-    private let delay: Duration
+    private let warmGate: Gate?
 
-    init(delay: Duration = .zero) { self.delay = delay }
+    init(warmGate: Gate? = nil) { self.warmGate = warmGate }
     nonisolated var calls: [Int] { recorder.all }
 
     func load() async throws { status = .ready }
     func transcribe(_ samples: [Float]) async throws -> Transcript {
         recorder.append(samples.count)
-        if delay > .zero { try? await Task.sleep(for: delay) }
+        if samples.count == 8_000 { await warmGate?.wait() }
         return Transcript(text: "counted", audioDuration: Double(samples.count) / CapturedAudio.sampleRate, processingTime: 0, engineID: id)
     }
     func unload() { status = .unloaded }
@@ -357,10 +357,10 @@ extension EngineRegistry.Entry {
 
 @MainActor
 func makeCountingCoordinator(
-    engineDelay: Duration = .zero,
+    warmGate: Gate? = nil,
     clock: any Clock<Duration> = ContinuousClock()
 ) -> (DictationCoordinator, FakeOutput, FakeCapture, CountingEngine) {
-    let engine = CountingEngine(delay: engineDelay)
+    let engine = CountingEngine(warmGate: warmGate)
     var settings = DictationSettings(engineID: CountingEngine.engineID)
     settings.appendTrailingSpace = false
     let (coordinator, output, capture) = makeCoordinator(engines: [.serving(engine)], settings: settings, clock: clock)
@@ -647,12 +647,15 @@ final class EventLog: @unchecked Sendable {
         let a = FakeHotkey()
         let b = FakeHotkey()
         let (c, _, capture) = makeCoordinator(hotkeyMonitor: a)
-        await capture.setStopDelay(.milliseconds(50))
+        let stopGate = Gate()
+        await capture.setStopGate(stopGate)
         await c.startIdle()
         await c.press(a)
         c.update(c.settings, standInHotkey: c.standInHotkey, monitor: b)
         #expect(c.state == .idle)
         b.press()
+        #expect(await waitUntil { c.state.isRecording })
+        await stopGate.open()
         #expect(await waitUntil { c.handledHotkeyEvents == 2 })
         #expect(c.state.isRecording)
         #expect(await capture.startCount == 2)
@@ -846,9 +849,14 @@ final class EventLog: @unchecked Sendable {
     }
 
     @Test func releaseDuringWarmupStillInserts() async {
-        let (c, output, _, _) = makeCountingCoordinator(engineDelay: .milliseconds(200))
+        let warmGate = Gate()
+        let (c, output, _, engine) = makeCountingCoordinator(warmGate: warmGate)
         await c.startIdle()
-        await c.dictate()
+        await c.hotkeyPressed()
+        #expect(await waitUntil { engine.calls == [8_000] })
+        c.hotkeyReleased()
+        await warmGate.open()
+        await c.inFlight?.value
         #expect(output.inserted.count == 1)
         #expect(c.state == .idle)
     }
@@ -1085,7 +1093,8 @@ final class EventLog: @unchecked Sendable {
     }
 
     @Test func polishingStateIsPublishedWhileTheModelRuns() async {
-        let refiner = FakeRefiner(delay: .milliseconds(200))
+        let gate = Gate()
+        let refiner = FakeRefiner(gate: gate)
         let (c, output, _) = makeCoordinator(engineText: Self.sentence, settings: Self.settings(), refiner: refiner)
         await c.startIdle()
         await c.hotkeyPressed()
@@ -1094,6 +1103,7 @@ final class EventLog: @unchecked Sendable {
         #expect(await waitUntil { c.state == .polishing })
         #expect(c.willPolish)
         #expect(output.inserted.isEmpty)
+        await gate.open()
         await c.inFlight?.value
         #expect(c.state == .idle)
         #expect(!c.willPolish)

From 1ab225944f34d8f18843f511c12545903aa38c3b Mon Sep 17 00:00:00 2001
From: Fabian Meyer <44942030+dinooo13@users.noreply.github.com>
Date: Fri, 16 Oct 2026 15:41:39 +0200
Subject: [PATCH 05/16] Tests: the engine loader test waits for the superseded
 load on a Gate, not a 10 ms poll

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Tests/PladderCoreTests/EngineLoaderTests.swift | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/Tests/PladderCoreTests/EngineLoaderTests.swift b/Tests/PladderCoreTests/EngineLoaderTests.swift
index 49d0cee..62bdf56 100644
--- a/Tests/PladderCoreTests/EngineLoaderTests.swift
+++ b/Tests/PladderCoreTests/EngineLoaderTests.swift
@@ -83,6 +83,7 @@ private actor GatedEngine: TranscriptionEngine {
     private var progress: Double
     private var isOpen = false
     private var waiters: [CheckedContinuation<Void, Never>] = []
+    private let loaded = Gate()
 
     init(id: EngineID, progress: Double) {
         self.id = id
@@ -95,13 +96,11 @@ private actor GatedEngine: TranscriptionEngine {
             await withCheckedContinuation { waiters.append($0) }
         }
         status = .ready
+        await loaded.open()
     }
 
     func waitUntilLoaded() async -> Bool {
-        for _ in 0..<100 {
-            if status == .ready { return true }
-            try? await Task.sleep(for: .milliseconds(10))
-        }
+        await loaded.wait()
         return status == .ready
     }
 

From de4b068f8c4a740232859c8a653b8135e5944178 Mon Sep 17 00:00:00 2001
From: Fabian Meyer <44942030+dinooo13@users.noreply.github.com>
Date: Fri, 16 Oct 2026 15:41:42 +0200
Subject: [PATCH 06/16] Tests: OrderedTasks' cancel winds down on a Gate, in
 one run instead of fifty

The stand-in cancel slept 5 ms and the test ran fifty times so the ensure would sometimes reach the actor first. It now waits on a Gate and marks the download stopped only after it, so an ensure that does not wait for the cancel loses its download whether it reaches the actor before the cancel or during its wind-down.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../PladderCoreTests/OrderedTasksTests.swift  | 27 +++++++++++--------
 1 file changed, 16 insertions(+), 11 deletions(-)

diff --git a/Tests/PladderCoreTests/OrderedTasksTests.swift b/Tests/PladderCoreTests/OrderedTasksTests.swift
index 4f59dd6..47aa34d 100644
--- a/Tests/PladderCoreTests/OrderedTasksTests.swift
+++ b/Tests/PladderCoreTests/OrderedTasksTests.swift
@@ -5,26 +5,31 @@ import Testing
 
 private actor Downloads {
     private(set) var running = false
+    private let windDown: Gate
+
+    init(windDown: Gate) { self.windDown = windDown }
+
     func ensure() { running = true }
+    // Winding down, as a cancelled URLSession task does, and only then marked stopped.
     func cancel() async {
+        await windDown.wait()
         running = false
-        // Winding down, as a cancelled URLSession task does.
-        try? await Task.sleep(for: .milliseconds(5))
     }
 }
 
 @MainActor
 @Suite(.timeLimit(.minutes(1))) struct OrderedTasksTests {
     @Test func aCancelThenEnsureLeavesTheDownloadRunning() async {
-        for _ in 0..<50 {
-            let downloads = Downloads()
-            await downloads.ensure()
-            let tasks = OrderedTasks()
-            tasks.enqueue { await downloads.cancel() }
-            tasks.enqueue { await downloads.ensure() }
-            await tasks.drained()
-            #expect(await downloads.running)
-        }
+        let windDown = Gate()
+        let downloads = Downloads(windDown: windDown)
+        await downloads.ensure()
+        let tasks = OrderedTasks()
+        tasks.enqueue { await downloads.cancel() }
+        tasks.enqueue { await downloads.ensure() }
+        await windDown.untilSomeoneWaits()
+        await windDown.open()
+        await tasks.drained()
+        #expect(await downloads.running)
     }
 
     @Test func eachPieceStartsAfterThePreviousOneFinished() async {

From 8894ccc75a3a50389811eef080ed7396910447fe Mon Sep 17 00:00:00 2001
From: Fabian Meyer <44942030+dinooo13@users.noreply.github.com>
Date: Fri, 16 Oct 2026 15:41:52 +0200
Subject: [PATCH 07/16] Output mute: the arm delay sleeps on an injected clock

Defaulted to ContinuousClock, so the app's call site is unchanged. The two tests that slept four times the delay to be sure an arm had given up now drive it with ManualClock. Off the release path: only `recordingStarted`, called at key-down, reads the clock.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../Support/OutputMuteController.swift        |  5 +++-
 .../OutputMuteControllerTests.swift           | 26 +++++++++----------
 2 files changed, 16 insertions(+), 15 deletions(-)

diff --git a/Sources/PladderCore/Support/OutputMuteController.swift b/Sources/PladderCore/Support/OutputMuteController.swift
index 369ac66..1e15d0e 100644
--- a/Sources/PladderCore/Support/OutputMuteController.swift
+++ b/Sources/PladderCore/Support/OutputMuteController.swift
@@ -5,6 +5,7 @@ import Foundation
 public actor OutputMuteController: OutputMuter {
     private let control: any OutputMuteControl
     private let delay: Duration
+    private let clock: any Clock<Duration>
     private let log: @Sendable (String) -> Void
 
     // A pending arm that wakes to find this changed belongs to a session already over.
@@ -15,10 +16,12 @@ public actor OutputMuteController: OutputMuter {
     public init(
         control: any OutputMuteControl,
         delay: Duration = .milliseconds(200),
+        clock: any Clock<Duration> = ContinuousClock(),
         log: @escaping @Sendable (String) -> Void = { _ in }
     ) {
         self.control = control
         self.delay = delay
+        self.clock = clock
         self.log = log
     }
 
@@ -29,7 +32,7 @@ public actor OutputMuteController: OutputMuter {
         latestSession = session
         generation += 1
         let mine = generation
-        try? await Task.sleep(for: delay)
+        try? await clock.sleep(for: delay)
         guard generation == mine else { return }
         guard restore == nil else {
             // An earlier session muted it and its end has not come; this session's end restores it.
diff --git a/Tests/PladderCoreTests/OutputMuteControllerTests.swift b/Tests/PladderCoreTests/OutputMuteControllerTests.swift
index 12ccace..dfd5dc4 100644
--- a/Tests/PladderCoreTests/OutputMuteControllerTests.swift
+++ b/Tests/PladderCoreTests/OutputMuteControllerTests.swift
@@ -61,36 +61,33 @@ private final class FakeMuteControl: OutputMuteControl, @unchecked Sendable {
     }
 }
 
-// Short enough to keep the tests fast, long enough that a "before the delay" call
-// really lands before it.
+// Short, so the tests that let it pass in real time stay fast.
 private let testDelay = Duration.milliseconds(10)
 
 private func makeController(
     _ control: FakeMuteControl,
     delay: Duration = testDelay,
+    clock: any Clock<Duration> = ContinuousClock(),
     log: @escaping @Sendable (String) -> Void = { _ in }
 ) -> OutputMuteController {
-    OutputMuteController(control: control, delay: delay, log: log)
+    OutputMuteController(control: control, delay: delay, clock: clock, log: log)
 }
 
 private func waitForGeneration(_ muter: OutputMuteController, _ target: Int) async {
     while await muter.armedGeneration < target { await Task.yield() }
 }
 
-private func pastTheDelay() async {
-    try? await Task.sleep(for: testDelay * 4)
-}
-
 @Suite(.timeLimit(.minutes(1))) struct OutputMuteControllerTests {
     @Test func tapAndReleaseBeforeTheDelayNeverMutes() async {
         let control = FakeMuteControl()
-        let muter = makeController(control)
+        let clock = ManualClock()
+        let muter = makeController(control, clock: clock)
 
         let started = Task { await muter.recordingStarted(session: 1) }
-        await waitForGeneration(muter, 1)
+        #expect(await clock.waitForSleeper(at: testDelay))
         await muter.recordingEnded(session: 1)
+        clock.advance(by: testDelay)
         await started.value
-        await pastTheDelay()
 
         #expect(control.setCalls.isEmpty)
         #expect(control.state(of: 1) == false)
@@ -186,16 +183,17 @@ private func pastTheDelay() async {
 
     @Test func aRestartInsideTheDelayStillEndsUpMuted() async {
         let control = FakeMuteControl()
-        let muter = makeController(control)
+        let clock = ManualClock()
+        let muter = makeController(control, clock: clock)
 
         let first = Task { await muter.recordingStarted(session: 1) }
-        await waitForGeneration(muter, 1)
+        #expect(await clock.waitForSleepers(1))
         await muter.recordingEnded(session: 1)
         let second = Task { await muter.recordingStarted(session: 2) }
-        await waitForGeneration(muter, 3)
+        #expect(await clock.waitForSleepers(2))
+        clock.advance(by: testDelay)
         await first.value
         await second.value
-        await pastTheDelay()
 
         #expect(control.state(of: 1) == true)
         #expect(control.setCalls == [.mute(1)])

From a1eaec9540279cbd18f8763201e7eeedd7944954 Mon Sep 17 00:00:00 2001
From: Fabian Meyer <44942030+dinooo13@users.noreply.github.com>
Date: Fri, 16 Oct 2026 15:41:55 +0200
Subject: [PATCH 08/16] S1-mini: the test of a load interrupted by unload
 awaits the abandoned load instead of sleeping 20 ms

`abandoned` becomes `private(set)` so the test, through `@testable import`, can wait for the first load to finish and try to store its model.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Sources/PladderRefine/S1MiniPolisher.swift | 2 +-
 Tests/PladderRefineTests/S1MiniTests.swift | 4 +---
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/Sources/PladderRefine/S1MiniPolisher.swift b/Sources/PladderRefine/S1MiniPolisher.swift
index 40b7c16..c46d394 100644
--- a/Sources/PladderRefine/S1MiniPolisher.swift
+++ b/Sources/PladderRefine/S1MiniPolisher.swift
@@ -39,7 +39,7 @@ public actor S1MiniPolisher: ReportingRefiner {
     private var loading: Task<(any PromptCompleter)?, Never>?
     // llama.cpp ignores cancellation, so a load `unload()` gave up on still reads weights;
     // the next load waits for it rather than holding two models at once.
-    private var abandoned: Task<(any PromptCompleter)?, Never>?
+    private(set) var abandoned: Task<(any PromptCompleter)?, Never>?
     // Bumped by `unload()`, so a load it interrupted cannot store its model.
     private var generation = 0
     private static let log = Logger(subsystem: "de.dinooo13.pladder", category: "polish")
diff --git a/Tests/PladderRefineTests/S1MiniTests.swift b/Tests/PladderRefineTests/S1MiniTests.swift
index 9c437b1..ce53931 100644
--- a/Tests/PladderRefineTests/S1MiniTests.swift
+++ b/Tests/PladderRefineTests/S1MiniTests.swift
@@ -136,9 +136,7 @@ private struct StandInModel: PromptCompleter {
         _ = await polisher.polish("send it")
         await polisher.unload()
         await gate.open()
-        // Time for the first load to finish and try to store its model; the right answer
-        // does not depend on it.
-        try await Task.sleep(for: .milliseconds(20))
+        _ = await polisher.abandoned?.value
         #expect(await polisher.refine("send it") == "Second.")
     }
 

From 8d2cc708cc2d6d8ee38fe313c91de8d114d25a51 Mon Sep 17 00:00:00 2001
From: Fabian Meyer <44942030+dinooo13@users.noreply.github.com>
Date: Fri, 16 Oct 2026 15:42:01 +0200
Subject: [PATCH 09/16] Tests: the sleeps that must stay real time say why

Each is a negative path, where nothing happens that a test could wait for, or a cancellable sleep standing in for a download that the cancel must interrupt.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Tests/PladderCoreTests/EngineLoaderTests.swift | 3 ++-
 Tests/PladderCoreTests/OrderedTasksTests.swift | 1 +
 Tests/PladderRefineTests/ModelFilesTests.swift | 1 +
 Tests/PladderRefineTests/S1MiniTests.swift     | 1 +
 4 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/Tests/PladderCoreTests/EngineLoaderTests.swift b/Tests/PladderCoreTests/EngineLoaderTests.swift
index 62bdf56..f5ac5d7 100644
--- a/Tests/PladderCoreTests/EngineLoaderTests.swift
+++ b/Tests/PladderCoreTests/EngineLoaderTests.swift
@@ -64,7 +64,8 @@ import Testing
 
         await first.open()
         #expect(await first.waitUntilLoaded())
-        // Time for the superseded load task to resume on the main actor.
+        // Negative path: a superseded load leaves nothing to wait for, so this gives its task
+        // time to resume on the main actor.
         try? await Task.sleep(for: .milliseconds(50))
         #expect(loader.engine.id == second.id)
         #expect(loader.status == .downloading(progress: 0.5))
diff --git a/Tests/PladderCoreTests/OrderedTasksTests.swift b/Tests/PladderCoreTests/OrderedTasksTests.swift
index 47aa34d..b7e9870 100644
--- a/Tests/PladderCoreTests/OrderedTasksTests.swift
+++ b/Tests/PladderCoreTests/OrderedTasksTests.swift
@@ -42,6 +42,7 @@ private actor Downloads {
         }
         tasks.enqueue { order.append("second") }
         await gate.untilSomeoneWaits()
+        // Gives a wrongly started second piece time to show.
         try? await Task.sleep(for: .milliseconds(10))
         #expect(order.all.isEmpty)
         await gate.open()
diff --git a/Tests/PladderRefineTests/ModelFilesTests.swift b/Tests/PladderRefineTests/ModelFilesTests.swift
index 498d190..59edee4 100644
--- a/Tests/PladderRefineTests/ModelFilesTests.swift
+++ b/Tests/PladderRefineTests/ModelFilesTests.swift
@@ -121,6 +121,7 @@ private actor StandInTransport: ModelFileTransport {
             if call == 1 {
                 try Data("wei".utf8).write(to: staging)
                 await started.open()
+                // A cancellable sleep stands in for the download; the test is that cancel interrupts it.
                 try await Task.sleep(for: .seconds(3))
             }
             try Data("weights".utf8).write(to: staging)
diff --git a/Tests/PladderRefineTests/S1MiniTests.swift b/Tests/PladderRefineTests/S1MiniTests.swift
index ce53931..a64f986 100644
--- a/Tests/PladderRefineTests/S1MiniTests.swift
+++ b/Tests/PladderRefineTests/S1MiniTests.swift
@@ -154,6 +154,7 @@ private struct StandInModel: PromptCompleter {
         _ = await polisher.polish("send it")
         await polisher.unload()
         let second = Task { await polisher.prepare() }
+        // Negative path: gives a second load that wrongly skipped the wait time to start.
         try await Task.sleep(for: .milliseconds(30))
         #expect(loadsStarted.all == [0])
         await gate.open()

From cff3dcb654ce6cd8e427cc66e29f00fb2029a600 Mon Sep 17 00:00:00 2001
From: Fabian Meyer <44942030+dinooo13@users.noreply.github.com>
Date: Fri, 16 Oct 2026 15:37:56 +0200
Subject: [PATCH 10/16] CLI: bench-coordinator times the coordinator's own
 share of release-to-paste

The real coordinator and processors, with stand-ins of fixed latency for the
engine, microphone, paste and polish; what is left of the total is the
coordinator's hand-over and its hops between stages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md                                 |   1 +
 Sources/PladderCLI/BenchCoordinator.swift | 326 ++++++++++++++++++++++
 Sources/PladderCLI/main.swift             |   4 +
 docs/ARCHITECTURE.md                      |   1 +
 docs/BENCHMARKS.md                        |  52 ++++
 5 files changed, 384 insertions(+)
 create mode 100644 Sources/PladderCLI/BenchCoordinator.swift

diff --git a/CLAUDE.md b/CLAUDE.md
index 3b70e85..dba4322 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -28,6 +28,7 @@ swift run -c release pladder-cli <audio file> [--process] [--verbose] # transcri
 ./scripts/make-fixtures.sh                    # synthesise benchmark fixtures into bench/fixtures (gitignored)
 swift run -c release pladder-cli bench bench/fixtures            # whole-buffer benchmark
 swift run -c release pladder-cli bench bench/fixtures --paced     # feed at real time, time endUtterance, check identity
+swift run -c release pladder-cli bench-coordinator [--polish] [--live]   # the coordinator's own share of release-to-paste, stand-ins of fixed latency
 swift run -c release pladder-cli polish <text file> [--model apple|s1-mini|s1-mini-8bit]   # one transcript, cold and warm
 swift run -c release pladder-cli polish-set docs/polish-set.json --model s1-mini-8bit    # a polish model over the test set: error rate, exact matches, timings
 ./scripts/overlay-demo.sh [dir] [--style …] [--speed …]  # play every overlay path with stand-ins, record the screen, cut contact sheets
diff --git a/Sources/PladderCLI/BenchCoordinator.swift b/Sources/PladderCLI/BenchCoordinator.swift
new file mode 100644
index 0000000..1c7cebb
--- /dev/null
+++ b/Sources/PladderCLI/BenchCoordinator.swift
@@ -0,0 +1,326 @@
+import Foundation
+import PladderCore
+import PladderSystem
+
+// The coordinator's own share of release-to-paste: "The coordinator's share" in
+// docs/BENCHMARKS.md. Stand-ins of fixed latency for everything the coordinator
+// drives, so what is left of the total is the coordinator.
+enum CoordinatorBench {
+    struct Options {
+        var runs = 21
+        var hold: Duration = .milliseconds(1_500)
+        var engineLatency: Duration = .milliseconds(150)
+        var pasteLatency: Duration = .zero
+        var polish = false
+        var live = false
+    }
+
+    static let polishLatency: Duration = .milliseconds(300)
+
+    static func run(arguments: [String]) async {
+        var options = Options()
+        var rest = arguments[...]
+        func number(_ value: String?) -> Double {
+            guard let value, let number = Double(value), number >= 0 else { usage() }
+            return number
+        }
+        while let argument = rest.popFirst() {
+            switch argument {
+            case "--runs":
+                guard let value = rest.popFirst(), let count = Int(value) else { usage() }
+                options.runs = count
+            case "--hold": options.hold = .milliseconds(Int(number(rest.popFirst()) * 1_000))
+            case "--engine-latency": options.engineLatency = .milliseconds(Int(number(rest.popFirst())))
+            case "--paste-latency": options.pasteLatency = .milliseconds(Int(number(rest.popFirst())))
+            case "--polish": options.polish = true
+            case "--live": options.live = true
+            default: usage()
+            }
+        }
+        guard options.runs >= 2 else {
+            eprint("--runs must be at least 2 (the first run is discarded)")
+            exit(2)
+        }
+        guard options.hold >= .milliseconds(300) else {
+            eprint("--hold must be at least 0.3 s, the coordinator's minimum recording")
+            exit(2)
+        }
+        await run(options)
+    }
+
+    struct Run {
+        var total: Duration
+        var share: Duration
+        var engineExcess: Duration
+    }
+
+    @MainActor
+    static func run(_ options: Options) async {
+        let engine = FixedLatencyEngine(latency: options.engineLatency)
+        let stamps = EventStamps()
+        var settings = DictationSettings(engineID: FixedLatencyEngine.engineID)
+        settings.polishDictations = options.polish
+        settings.liveTranscript = options.live
+        let coordinator = DictationCoordinator(
+            settings: settings,
+            registry: EngineRegistry([
+                .init(id: engine.id, displayName: engine.displayName, detail: "") { engine },
+            ]),
+            capture: SilentCapture(),
+            output: TimedOutput(latency: options.pasteLatency),
+            refiner: options.polish ? FixedLatencyRefiner(latency: polishLatency) : nil,
+            hotkeyMonitor: SilentHotkeyMonitor(),
+            makePipeline: { StandardProcessors.pipeline(for: $0) },
+            onEvent: { stamps.stamp($0) }
+        )
+        coordinator.start()
+        while !coordinator.engineStatus.isReady || coordinator.state != .idle {
+            try? await Task.sleep(for: .milliseconds(10))
+        }
+
+        var overshoots: [Duration] = []
+        for _ in 0..<11 {
+            let started = ContinuousClock.now
+            await uncancellableSleep(options.engineLatency)
+            overshoots.append(ContinuousClock.now - started - options.engineLatency)
+        }
+
+        printBenchHeader("Pladder coordinator benchmark", engine: engine)
+        print(String(format: "load:    %.2f (1-minute average) at start", loadAverage()))
+        print("runs:    \(options.runs), first discarded, median reported")
+        print("hold:    \(format(options.hold)), engine \(format(options.engineLatency)), "
+            + "paste \(format(options.pasteLatency))"
+            + (options.polish ? ", polish \(format(polishLatency))" : "")
+            + (options.live ? ", Live Transcript" : ""))
+        print("timer:   a \(format(options.engineLatency)) stand-in sleep overshoots by \(format(median(overshoots))) "
+            + "(median), which engine excess includes")
+        print("")
+
+        var kept: [Run] = []
+        for attempt in 1...options.runs {
+            await coordinator.hotkeyPressed()
+            guard coordinator.state.isRecording else {
+                eprint("run \(attempt): the press was refused in state \(coordinator.state)")
+                exit(1)
+            }
+            try? await Task.sleep(for: options.hold)
+            coordinator.hotkeyReleased()
+            await coordinator.inFlight?.value
+            guard let insertion = stamps.insertion, let stopped = stamps.stopped, let inserted = stamps.inserted else {
+                eprint("run \(attempt): nothing was inserted (state \(coordinator.state))")
+                exit(1)
+            }
+            stamps.reset()
+            let timing = insertion.timing
+            let total = inserted - stopped
+            let stages = timing.captureStop + timing.engine + timing.processing + timing.insert + (timing.polish ?? .zero)
+            let run = Run(total: total, share: total - stages, engineExcess: timing.engine - options.engineLatency)
+            let tag = attempt == 1 ? " (discarded)" : ""
+            print("run \(attempt): total \(format(run.total)) (stop \(format(timing.captureStop)), "
+                + "process \(format(timing.processing))), share \(format(run.share)), "
+                + "engine excess \(format(run.engineExcess))\(tag)")
+            if attempt > 1 { kept.append(run) }
+            // Lets the release's detached work (the clipboard prepare, the mute restore) end.
+            try? await Task.sleep(for: .milliseconds(100))
+        }
+        coordinator.stop()
+
+        let shares = kept.map(\.share)
+        print("")
+        print("| Hold | Engine | Total (median) | Share (median / p90 / max) | Engine excess (median) |")
+        print("|---:|---:|---:|---:|---:|")
+        print("| \(format(options.hold)) | \(format(options.engineLatency)) "
+            + "| \(format(median(kept.map(\.total)))) "
+            + "| \(format(median(shares))) / \(format(percentile(shares, 0.9))) / \(format(shares.max() ?? .zero)) "
+            + "| \(format(median(kept.map(\.engineExcess)))) |")
+        print(String(format: "load:    %.2f (1-minute average) at end", loadAverage()))
+    }
+
+    private static func median(_ values: [Duration]) -> Duration {
+        percentile(values, 0.5)
+    }
+
+    private static func percentile(_ values: [Duration], _ fraction: Double) -> Duration {
+        let sorted = values.sorted()
+        guard !sorted.isEmpty else { return .zero }
+        let index = Int((Double(sorted.count - 1) * fraction).rounded())
+        return sorted[index]
+    }
+
+    private static func format(_ duration: Duration) -> String {
+        let ms = duration / .milliseconds(1)
+        return ms.magnitude >= 100 ? String(format: "%.0f ms", ms) : String(format: "%.2f ms", ms)
+    }
+}
+
+// MARK: - Stand-ins
+
+private final class EventStamps: @unchecked Sendable {
+    private let lock = NSLock()
+    private var _stopped: ContinuousClock.Instant?
+    private var _inserted: ContinuousClock.Instant?
+    private var _insertion: DictationCoordinator.Insertion?
+    var stopped: ContinuousClock.Instant? { lock.withLock { _stopped } }
+    var inserted: ContinuousClock.Instant? { lock.withLock { _inserted } }
+    var insertion: DictationCoordinator.Insertion? { lock.withLock { _insertion } }
+
+    func stamp(_ event: DictationCoordinator.Event) {
+        let now = ContinuousClock.now
+        lock.withLock {
+            switch event {
+            case .recordingStopped: _stopped = now
+            case .inserted(let insertion):
+                _inserted = now
+                _insertion = insertion
+            default: break
+            }
+        }
+    }
+
+    func reset() {
+        lock.withLock {
+            _stopped = nil
+            _inserted = nil
+            _insertion = nil
+        }
+    }
+}
+
+// Ignores cancellation, as a CoreML pass in flight does. A strict timer: `Task.sleep`
+// overshoots 150 ms by about 8 ms on an M1 even with zero tolerance, this by 0.2 ms.
+private func uncancellableSleep(_ duration: Duration) async {
+    guard duration > .zero else { return }
+    await withCheckedContinuation { (done: CheckedContinuation<Void, Never>) in
+        let timer = DispatchSource.makeTimerSource(flags: .strict, queue: .global(qos: .userInteractive))
+        timer.schedule(deadline: .now() + duration.timeInterval, leeway: .nanoseconds(0))
+        timer.setEventHandler {
+            timer.cancel()
+            done.resume()
+        }
+        timer.resume()
+    }
+}
+
+private actor FixedLatencyEngine: StreamingTranscriptionEngine {
+    static let engineID = EngineID("fixed-latency")
+    nonisolated let id = FixedLatencyEngine.engineID
+    nonisolated let displayName = "Fixed latency (benchmark)"
+    private(set) var status: EngineStatus = .unloaded
+    private let latency: Duration
+    private var slot = UtteranceSlot<Void>()
+
+    // About what a dictation of this length looks like, with a filler for the processors.
+    private static let text = "So um I think we should move the review to Thursday afternoon and send the notes to the whole team before then."
+
+    init(latency: Duration) {
+        self.latency = latency
+    }
+
+    func load() async throws { status = .ready }
+    func unload() async { status = .unloaded }
+
+    func transcribe(_ samples: [Float]) async throws -> Transcript {
+        await uncancellableSleep(latency)
+        return transcript(samples: samples.count)
+    }
+
+    func beginUtterance() async throws -> Utterance {
+        let (utterance, _) = slot.begin()
+        _ = slot.install((), for: utterance)
+        return utterance
+    }
+
+    func feed(_ samples: [Float], to utterance: Utterance) async {}
+
+    func endUtterance(_ utterance: Utterance, tail: [Float]) async throws -> Transcript {
+        guard slot.release(utterance).wasCurrent else { throw TranscriptionError.notLoaded }
+        await uncancellableSleep(latency)
+        return transcript(samples: 0)
+    }
+
+    func abandonUtterance(_ utterance: Utterance) async {
+        slot.release(utterance)
+    }
+
+    func warmPass() async {
+        await uncancellableSleep(latency)
+    }
+
+    func livePass(_ utterance: Utterance) async -> String? {
+        guard slot.session(for: utterance) != nil else { return nil }
+        await uncancellableSleep(latency)
+        return Self.text
+    }
+
+    // An audio duration of zero lets the coordinator fill in what it fed.
+    private func transcript(samples: Int) -> Transcript {
+        Transcript(
+            text: Self.text,
+            audioDuration: Double(samples) / CapturedAudio.sampleRate,
+            processingTime: latency.timeInterval,
+            engineID: id
+        )
+    }
+}
+
+// Silence at the real rate: a drain or a stop returns what a microphone would have
+// captured since the last one.
+private actor SilentCapture: AudioCapture {
+    private var since: ContinuousClock.Instant?
+
+    func start() async throws -> AsyncStream<Float> {
+        since = .now
+        return AsyncStream { _ in }
+    }
+
+    func drain() async -> [Float] {
+        collect()
+    }
+
+    func stop() async -> CapturedAudio {
+        let samples = collect()
+        since = nil
+        return CapturedAudio(samples: samples)
+    }
+
+    func warmUp() async throws {}
+
+    private func collect() -> [Float] {
+        guard let since else { return [] }
+        let now = ContinuousClock.now
+        self.since = now
+        let count = Int((now - since).timeInterval * CapturedAudio.sampleRate)
+        return [Float](repeating: 0, count: count)
+    }
+}
+
+private struct TimedOutput: TextOutput {
+    let latency: Duration
+
+    func insert(_ text: String, submit: Bool) async throws -> InsertResult {
+        await uncancellableSleep(latency)
+        return .pasted
+    }
+
+    func copy(_ text: String) async {}
+}
+
+private struct FixedLatencyRefiner: TranscriptRefiner {
+    let latency: Duration
+
+    func prepare() async {}
+
+    func refine(_ text: String) async -> String? {
+        await uncancellableSleep(latency)
+        return text
+    }
+}
+
+private struct SilentHotkeyMonitor: HotkeyMonitor {
+    func start(chords: [HotkeyRole: Hotkey], submitKey: Hotkey) -> AsyncStream<HotkeyMonitorEvent> {
+        AsyncStream { _ in }
+    }
+
+    func stop() {}
+    func setCancelKeyEnabled(_ enabled: Bool) {}
+}
diff --git a/Sources/PladderCLI/main.swift b/Sources/PladderCLI/main.swift
index a1b9591..367af7f 100644
--- a/Sources/PladderCLI/main.swift
+++ b/Sources/PladderCLI/main.swift
@@ -10,6 +10,7 @@ func usage() -> Never {
            pladder-cli bench <fixtures dir> [--runs N] [--pause S]
            pladder-cli bench <fixtures dir> --paced [--runs N] [--pause S] [--all] [--live]
            pladder-cli bench-process <fixtures dir> [--runs N]
+           pladder-cli bench-coordinator [--runs N] [--hold S] [--engine-latency MS] [--paste-latency MS] [--polish] [--live]
            pladder-cli polish <text file | -> [--model \(PolishModel.cliNames) | --gguf <file>] [--control <line>] [--instructions <file>]
            pladder-cli polish-set <set.json> [--model \(PolishModel.cliNames) | --gguf <file>] [--control <line>]
     """)
@@ -63,6 +64,9 @@ case "bench":
 case "bench-process":
     arguments.removeFirst()
     ProcessorBench.run(arguments: arguments)
+case "bench-coordinator":
+    arguments.removeFirst()
+    await CoordinatorBench.run(arguments: arguments)
 case "polish", "polish-set":
     let command = arguments.removeFirst()
     var options = PolishOptions()
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 586da5e..f2094b9 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -483,6 +483,7 @@ Errors and progress go to stderr, so stdout holds only results.
 | `bench <fixtures dir>` | The whole-buffer benchmark. `--runs N` (default 6, first discarded; 11 to settle a result near the noise line), `--pause S` (idle seconds before every run, default 10). |
 | `bench <dir> --paced` | Feeds each fixture in one-second chunks at real time and times `endUtterance`; also transcribes it whole and reports whether the texts are identical. Skips fixtures under 13 s unless `--all`. `--live` adds the Live Transcript pass every 0.5 s and reports its cost. |
 | `bench-process <dir>` | Times the processor pipeline on the fixtures' scripts, with a filler in every sentence and with a spoken question mark too. `--runs N`, default 31. |
+| `bench-coordinator` | Drives the real coordinator and processors with stand-ins of fixed latency for the engine, microphone, paste and polish, and reports what release-to-paste costs beyond them. `--runs N` (default 21, first discarded), `--hold S` (1.5), `--engine-latency MS` (150), `--paste-latency MS` (0), `--polish` (a 300 ms stand-in), `--live`. |
 | `polish <text file \| ->` | Runs a polish model over one transcript, cold and then warm. `--model apple\|s1-mini\|s1-mini-8bit`, `--instructions <file>` (Apple), `--gguf <file>` (any S1-mini-family model), `--control <line>` (S1-mini). |
 | `polish-set <set.json>` | Runs a polish model over a test set after the app's processors: every answer, word error rate per language, exact matches, timings. `--model`, `--gguf` and `--control` as for `polish`; no `--instructions`. |
 
diff --git a/docs/BENCHMARKS.md b/docs/BENCHMARKS.md
index 80f07bd..6984249 100644
--- a/docs/BENCHMARKS.md
+++ b/docs/BENCHMARKS.md
@@ -123,6 +123,53 @@ without them. Run it beside a plain `--paced` run and compare the
 `endUtterance` medians: the difference is what a release that lands next to a
 live pass costs.
 
+### The coordinator's share
+
+The engine benchmarks time the engine; the app's log line times a whole
+dictation. What sits between them, the coordinator's own work on the
+release-to-paste path (the feed hand-over, `endRecording`, the hops between
+stages on the main actor), has a number of its own here:
+
+```sh
+swift run -c release pladder-cli bench-coordinator [--runs N] [--hold S] [--engine-latency MS] [--paste-latency MS] [--polish] [--live]
+```
+
+It builds the real `DictationCoordinator` with the app's processors on a
+fresh install's settings, and stand-ins for the rest: a streaming engine whose
+`endUtterance`, warm pass and live pass each take `--engine-latency` (150 ms by
+default) and ignore cancellation, as a CoreML pass does; a microphone that
+hands out silence at the real rate; a paste of `--paste-latency` (0); and with
+`--polish` a 300 ms polish model. Each run presses, holds for `--hold` seconds
+(1.5), releases and waits for the paste. It touches no microphone, pasteboard
+or hotkey, so it can run beside a copy of Pladder in use.
+
+Per run, `total` is `inserted` minus `recordingStopped`, as in the app's log
+line. `share` is the total minus the stages the `inserted` event reports
+(stop, engine, process, polish, paste): the time spent between them.
+`engine excess` is the engine stage minus the stand-in's latency: the feed
+hand-over and the actor hops around `endUtterance`, plus the stand-in timer's
+own overshoot, which the header prints. 21 runs by default, the first
+discarded.
+
+Use it before and after a change to the coordinator, beside the paced bench:
+the paced bench says what the engine costs, this what the coordinator adds.
+
+First numbers, Apple M1, 16 GB, macOS 27.0, October 2026, 21 runs each,
+load average about 2:
+
+| Variant | Total (median) | Share (median / p90 / max) | Engine excess (median) |
+|---|---:|---:|---:|
+| default | 153 ms | 0.02 / 0.02 / 0.03 ms | 0.15 ms |
+| `--polish` | 453 ms | 0.04 / 0.04 / 0.04 ms | 0.15 ms |
+| `--live` | 153 ms | 0.02 / 0.07 / 0.09 ms | 0.14 ms |
+
+The stand-in timer overshot by 0.1 ms, so the coordinator's hand-over and
+hops come to a few hundredths of a millisecond, and the rest of the total
+above the stand-ins' latencies is the processors' 2 to 3 ms. Two 51-run
+passes gave medians of 156 and 153 ms total and 0.05 and 0.02 ms share. A
+release that lands in a warm or live pass waits for it, as in the app; at
+the default 1.5 s hold none does.
+
 ## Baseline
 
 Reference machine: Apple M1, 16 GB, macOS 26.6.2 (25G83), FluidAudio 0.15.6,
@@ -141,6 +188,11 @@ the models and takes far longer; that is a one-time cost and not what this
 number tracks. The weights run on the Neural Engine and are held outside the
 process, so the footprint understates total memory use.
 
+During the benchmarking for #70 the M1 logged `ANECCompile() FAILED (11)` on
+the first run of each new build, and both builds measured about 0.45 s slower
+than the table below. A pass that logs it is not comparable; the table wants
+re-running on a quiet day (numbers to follow).
+
 | Fixture | Audio | Engine (median) | Spread | Realtime | WER |
 |---|---:|---:|---:|---:|---:|
 | 10s | 9.7 s | 0.237 s | 20 % | 41x | 0.0 % |

From 8f8b591e809880053498f4800fa3e92ff6528234 Mon Sep 17 00:00:00 2001
From: Fabian Meyer <44942030+dinooo13@users.noreply.github.com>
Date: Fri, 16 Oct 2026 15:40:18 +0200
Subject: [PATCH 11/16] Coordinator: the finish pipeline is DictationFinish,
 which returns an outcome

Engine, processors, polish, insert and their timing move into a value built at
release; the coordinator keeps every state flip and turns the outcome into the
event and the state after.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../PladderCore/DictationCoordinator.swift    | 100 +++------
 Sources/PladderCore/DictationFinish.swift     |  93 ++++++++
 .../DictationFinishTests.swift                | 200 ++++++++++++++++++
 docs/ARCHITECTURE.md                          |  23 +-
 4 files changed, 342 insertions(+), 74 deletions(-)
 create mode 100644 Sources/PladderCore/DictationFinish.swift
 create mode 100644 Tests/PladderCoreTests/DictationFinishTests.swift

diff --git a/Sources/PladderCore/DictationCoordinator.swift b/Sources/PladderCore/DictationCoordinator.swift
index 94f9176..195cb29 100644
--- a/Sources/PladderCore/DictationCoordinator.swift
+++ b/Sources/PladderCore/DictationCoordinator.swift
@@ -525,6 +525,10 @@ public final class DictationCoordinator {
         onEvent(.recordingStopped)
         let engine = cycleEngine ?? loader.engine
         cycleEngine = nil
+        let finish = DictationFinish(
+            pipeline: pipeline, disabledProcessors: settings.disabledProcessors,
+            appendTrailingSpace: settings.appendTrailingSpace, willPolish: willPolish, refiner: refiner,
+            minimumDuration: minimumDuration, minimumPolishWords: minimumPolishWords, output: output)
         inFlight = Task { [weak self] in
             guard let self else { return }
             // The feed loop finishes handing over a chunk drained before the release. What
@@ -535,80 +539,44 @@ public final class DictationCoordinator {
             let feedWait = stopped - handover
             let audio = await self.capture.stop()
             let captureStop = ContinuousClock.now - stopped
-            await self.finish(
-                audio, stream: stream, fedSamples: fed ?? 0, with: engine, submit: submit,
-                captureStop: captureStop, feedWait: feedWait)
+            let source: DictationFinish.Source = if let stream {
+                .utterance(stream.engine, stream.utterance)
+            } else {
+                .whole(engine)
+            }
+            let outcome = await finish.run(
+                DictationFinish.Input(
+                    audio: audio, fedSamples: fed ?? 0, source: source, submit: submit,
+                    captureStop: captureStop, feedWait: feedWait),
+                onStage: { self.enter($0) })
+            self.finished(outcome)
         }
     }
 
-    private func finish(
-        _ audio: CapturedAudio,
-        stream: Stream?,
-        fedSamples: Int,
-        with engine: any TranscriptionEngine,
-        submit: Bool,
-        captureStop: Duration,
-        feedWait: Duration
-    ) async {
-        defer {
-            drainPendingUnloads()
-            willPolish = false
-        }
-        // A streaming engine was fed `fedSamples` while recording; only the tail came
-        // from `stop()`.
-        let totalDuration = Double(fedSamples + audio.samples.count) / CapturedAudio.sampleRate
-        guard totalDuration >= minimumDuration else {
-            if let stream { await stream.engine.abandonUtterance(stream.utterance) }
-            becomeIdle()
-            return
-        }
-        do {
-            var timing = CycleTiming(captureStop: captureStop, engine: .zero, processing: .zero, insert: .zero)
-            var started = ContinuousClock.now
-            var transcript = if let stream {
-                try await stream.engine.endUtterance(stream.utterance, tail: audio.samples)
-            } else {
-                try await engine.transcribe(audio.samples)
-            }
-            timing.engine = feedWait + (ContinuousClock.now - started)
-            if transcript.audioDuration == 0 {
-                transcript.audioDuration = totalDuration
-            }
-            started = ContinuousClock.now
-            let processed = pipeline.run(transcript.text, disabled: settings.disabledProcessors)
-            timing.processing = ContinuousClock.now - started
-            guard !processed.isEmpty else {
-                becomeIdle()
-                return
-            }
-            var final = processed
-            if willPolish, let refiner, processed.wordCount >= minimumPolishWords {
-                state = .polishing
-                started = ContinuousClock.now
-                if let polished = await refiner.refine(processed) { final = polished }
-                timing.polish = ContinuousClock.now - started
-            } else if willPolish {
-                timing.polish = .zero
-            }
+    private func enter(_ stage: DictationFinish.Stage) {
+        switch stage {
+        case .polishing:
+            state = .polishing
+        case .inserting(let transcript):
             state = .inserting
-            let needsSpace = settings.appendTrailingSpace && final.last?.isWhitespace != true
-            let toInsert = needsSpace ? final + " " : final
-            // Before the insert, so a paste that fails leaves the menu's
-            // copy of it processed, which is when the user needs it.
-            transcript.text = final
             lastTranscript = transcript
-            started = ContinuousClock.now
-            let result = try await output.insert(toInsert, submit: submit)
-            timing.insert = ContinuousClock.now - started
-            onEvent(.inserted(Insertion(
-                transcript: transcript, timing: timing, result: result,
-                submitted: submit && result == .pasted)))
-            if result == .copied { showCopied() } else { becomeIdle() }
-        } catch {
-            fail(DictationFailure(error))
         }
     }
 
+    private func finished(_ outcome: DictationFinish.Outcome) {
+        switch outcome {
+        case .tooShort, .empty:
+            becomeIdle()
+        case .inserted(let insertion):
+            onEvent(.inserted(insertion))
+            if insertion.result == .copied { showCopied() } else { becomeIdle() }
+        case .failed(let failure):
+            fail(failure)
+        }
+        drainPendingUnloads()
+        willPolish = false
+    }
+
     private func becomeIdle() {
         switch engineStatus {
         case .ready: state = .idle
diff --git a/Sources/PladderCore/DictationFinish.swift b/Sources/PladderCore/DictationFinish.swift
new file mode 100644
index 0000000..15357d9
--- /dev/null
+++ b/Sources/PladderCore/DictationFinish.swift
@@ -0,0 +1,93 @@
+import Foundation
+
+// See docs/ARCHITECTURE.md, "Dictation flow".
+@MainActor
+struct DictationFinish {
+    enum Source {
+        case utterance(any StreamingTranscriptionEngine, Utterance)
+        case whole(any TranscriptionEngine)
+    }
+
+    struct Input {
+        var audio: CapturedAudio
+        // A streaming engine was fed these while recording; `audio` is only the tail.
+        var fedSamples: Int
+        var source: Source
+        var submit: Bool
+        var captureStop: Duration
+        var feedWait: Duration
+    }
+
+    enum Stage: Equatable {
+        case polishing
+        // Before the insert, so a paste that fails leaves the processed text as the
+        // last transcript, which is when the user needs it.
+        case inserting(Transcript)
+    }
+
+    enum Outcome: Equatable {
+        case tooShort
+        case empty
+        case inserted(DictationCoordinator.Insertion)
+        case failed(DictationFailure)
+    }
+
+    let pipeline: ProcessorPipeline
+    let disabledProcessors: Set<String>
+    let appendTrailingSpace: Bool
+    let willPolish: Bool
+    let refiner: (any TranscriptRefiner)?
+    let minimumDuration: TimeInterval
+    let minimumPolishWords: Int
+    let output: any TextOutput
+
+    func run(_ input: Input, onStage: (Stage) -> Void) async -> Outcome {
+        let totalDuration = Double(input.fedSamples + input.audio.samples.count) / CapturedAudio.sampleRate
+        guard totalDuration >= minimumDuration else {
+            if case .utterance(let engine, let utterance) = input.source {
+                await engine.abandonUtterance(utterance)
+            }
+            return .tooShort
+        }
+        do {
+            var timing = DictationCoordinator.CycleTiming(
+                captureStop: input.captureStop, engine: .zero, processing: .zero, insert: .zero)
+            var started = ContinuousClock.now
+            var transcript = switch input.source {
+            case .utterance(let engine, let utterance):
+                try await engine.endUtterance(utterance, tail: input.audio.samples)
+            case .whole(let engine):
+                try await engine.transcribe(input.audio.samples)
+            }
+            timing.engine = input.feedWait + (ContinuousClock.now - started)
+            if transcript.audioDuration == 0 {
+                transcript.audioDuration = totalDuration
+            }
+            started = ContinuousClock.now
+            let processed = pipeline.run(transcript.text, disabled: disabledProcessors)
+            timing.processing = ContinuousClock.now - started
+            guard !processed.isEmpty else { return .empty }
+            var final = processed
+            if willPolish, let refiner, processed.wordCount >= minimumPolishWords {
+                onStage(.polishing)
+                started = ContinuousClock.now
+                if let polished = await refiner.refine(processed) { final = polished }
+                timing.polish = ContinuousClock.now - started
+            } else if willPolish {
+                timing.polish = .zero
+            }
+            let needsSpace = appendTrailingSpace && final.last?.isWhitespace != true
+            let toInsert = needsSpace ? final + " " : final
+            transcript.text = final
+            onStage(.inserting(transcript))
+            started = ContinuousClock.now
+            let result = try await output.insert(toInsert, submit: input.submit)
+            timing.insert = ContinuousClock.now - started
+            return .inserted(DictationCoordinator.Insertion(
+                transcript: transcript, timing: timing, result: result,
+                submitted: input.submit && result == .pasted))
+        } catch {
+            return .failed(DictationFailure(error))
+        }
+    }
+}
diff --git a/Tests/PladderCoreTests/DictationFinishTests.swift b/Tests/PladderCoreTests/DictationFinishTests.swift
new file mode 100644
index 0000000..b586499
--- /dev/null
+++ b/Tests/PladderCoreTests/DictationFinishTests.swift
@@ -0,0 +1,200 @@
+import Foundation
+import Testing
+@testable import PladderCore
+
+private struct Emptying: TextProcessor {
+    let id = "emptying"
+    func process(_ text: String) -> String { "" }
+}
+
+private final class FixedRefiner: TranscriptRefiner, @unchecked Sendable {
+    private let lock = NSLock()
+    private var _calls: [String] = []
+    private let result: String
+    var calls: [String] { lock.withLock { _calls } }
+
+    init(result: String) { self.result = result }
+
+    func prepare() async {}
+
+    func refine(_ text: String) async -> String? {
+        lock.withLock { _calls.append(text) }
+        return result
+    }
+}
+
+@MainActor
+@Suite(.timeLimit(.minutes(1))) struct DictationFinishTests {
+    private static let second = CapturedAudio(samples: Array(repeating: 0.1, count: 16_000))
+
+    private func finish(
+        pipeline: ProcessorPipeline = ProcessorPipeline([WhitespaceNormalizer()]),
+        appendTrailingSpace: Bool = true,
+        refiner: FixedRefiner? = nil,
+        output: FakeOutput = FakeOutput()
+    ) -> DictationFinish {
+        DictationFinish(
+            pipeline: pipeline, disabledProcessors: [], appendTrailingSpace: appendTrailingSpace,
+            willPolish: refiner != nil, refiner: refiner, minimumDuration: 0.3, minimumPolishWords: 4,
+            output: output)
+    }
+
+    private func loaded(_ text: String, delay: Duration = .zero) async throws -> EchoEngine {
+        let engine = EchoEngine(text: text, delay: delay)
+        try await engine.load()
+        return engine
+    }
+
+    private func input(
+        _ source: DictationFinish.Source, audio: CapturedAudio = second, fed: Int = 0,
+        captureStop: Duration = .zero, feedWait: Duration = .zero
+    ) -> DictationFinish.Input {
+        DictationFinish.Input(
+            audio: audio, fedSamples: fed, source: source, submit: false,
+            captureStop: captureStop, feedWait: feedWait)
+    }
+
+    private func run(_ finish: DictationFinish, _ input: DictationFinish.Input) async -> (
+        DictationFinish.Outcome, [DictationFinish.Stage]
+    ) {
+        var stages: [DictationFinish.Stage] = []
+        let outcome = await finish.run(input) { stages.append($0) }
+        return (outcome, stages)
+    }
+
+    @Test func aRecordingUnderTheMinimumAbandonsTheUtteranceAndInsertsNothing() async throws {
+        let engine = FakeStreamingEngine()
+        try await engine.load()
+        let utterance = try await engine.beginUtterance()
+        let output = FakeOutput()
+        let short = CapturedAudio(samples: Array(repeating: 0.1, count: 3_000))
+        let (outcome, stages) = await run(
+            finish(output: output), input(.utterance(engine, utterance), audio: short, fed: 1_000))
+        #expect(outcome == .tooShort)
+        #expect(stages.isEmpty)
+        #expect(engine.log.last == "abandon")
+        #expect(engine.endCount == 0)
+        #expect(output.inserted.isEmpty)
+    }
+
+    @Test func fedSamplesCountTowardsTheMinimum() async throws {
+        let engine = FakeStreamingEngine()
+        try await engine.load()
+        let utterance = try await engine.beginUtterance()
+        let tail = CapturedAudio(samples: Array(repeating: 0.1, count: 1_000))
+        let (outcome, _) = await run(finish(), input(.utterance(engine, utterance), audio: tail, fed: 16_000))
+        guard case .inserted(let insertion) = outcome else {
+            Issue.record("expected an insertion, got \(outcome)")
+            return
+        }
+        #expect(insertion.transcript.text == "final")
+        #expect(insertion.transcript.audioDuration == 17_000 / CapturedAudio.sampleRate)
+    }
+
+    @Test func processedTextEmptyInsertsNothingAndReportsEmpty() async throws {
+        let output = FakeOutput()
+        let (outcome, stages) = await run(
+            finish(pipeline: ProcessorPipeline([Emptying()]), output: output),
+            input(.whole(try await loaded("um"))))
+        #expect(outcome == .empty)
+        #expect(stages.isEmpty)
+        #expect(output.inserted.isEmpty)
+    }
+
+    @Test func polishRunsFromTheMinimumWordCountAndReportsItsStage() async throws {
+        let refiner = FixedRefiner(result: "Polished.")
+        let output = FakeOutput()
+        let (outcome, stages) = await run(
+            finish(refiner: refiner, output: output), input(.whole(try await loaded("one two three four"))))
+        #expect(refiner.calls == ["one two three four"])
+        #expect(stages.count == 2)
+        #expect(stages.first == .polishing)
+        #expect(output.inserted == ["Polished. "])
+        guard case .inserted(let insertion) = outcome else {
+            Issue.record("expected an insertion, got \(outcome)")
+            return
+        }
+        #expect(insertion.transcript.text == "Polished.")
+        #expect(insertion.timing.polish != nil)
+    }
+
+    @Test func underTheMinimumPolishIsZeroNotNil() async throws {
+        let refiner = FixedRefiner(result: "Polished.")
+        let (outcome, stages) = await run(finish(refiner: refiner), input(.whole(try await loaded("one two three"))))
+        #expect(refiner.calls.isEmpty)
+        #expect(!stages.contains(.polishing))
+        guard case .inserted(let insertion) = outcome else {
+            Issue.record("expected an insertion, got \(outcome)")
+            return
+        }
+        #expect(insertion.timing.polish == .zero)
+    }
+
+    @Test func withoutPolishTheTimingHasNoPolishStage() async throws {
+        let (outcome, _) = await run(finish(), input(.whole(try await loaded("one two three four"))))
+        guard case .inserted(let insertion) = outcome else {
+            Issue.record("expected an insertion, got \(outcome)")
+            return
+        }
+        #expect(insertion.timing.polish == nil)
+    }
+
+    @Test func theInsertingStageCarriesTheProcessedTranscriptBeforeTheInsert() async throws {
+        let output = FakeOutput()
+        output.shouldFail = true
+        let pipeline = ProcessorPipeline([
+            DictionaryReplacer(entries: [DictionaryEntry(from: "hello world", to: "Hello, World!")]),
+        ])
+        let (outcome, stages) = await run(
+            finish(pipeline: pipeline, output: output), input(.whole(try await loaded("hello world"))))
+        guard case .failed = outcome else {
+            Issue.record("expected a failure, got \(outcome)")
+            return
+        }
+        guard case .inserting(let transcript) = stages.last else {
+            Issue.record("expected the inserting stage, got \(stages)")
+            return
+        }
+        #expect(transcript.text == "Hello, World!")
+    }
+
+    @Test func timingSumsTheStagesAndFeedWaitCountsAsEngineTime() async throws {
+        let engine = try await loaded("hello world", delay: .milliseconds(20))
+        let (outcome, _) = await run(
+            finish(), input(.whole(engine), captureStop: .milliseconds(7), feedWait: .milliseconds(40)))
+        guard case .inserted(let insertion) = outcome else {
+            Issue.record("expected an insertion, got \(outcome)")
+            return
+        }
+        #expect(insertion.timing.captureStop == .milliseconds(7))
+        #expect(insertion.timing.engine >= .milliseconds(60))
+        #expect(insertion.timing.processing > .zero)
+        #expect(insertion.timing.insert > .zero)
+    }
+
+    @Test func aTrailingSpaceIsAppendedOnlyWhenMissing() async throws {
+        let output = FakeOutput()
+        let noProcessors = ProcessorPipeline([])
+        _ = await run(finish(pipeline: noProcessors, output: output), input(.whole(try await loaded("spaced "))))
+        _ = await run(finish(pipeline: noProcessors, output: output), input(.whole(try await loaded("bare"))))
+        _ = await run(
+            finish(pipeline: noProcessors, appendTrailingSpace: false, output: output),
+            input(.whole(try await loaded("off"))))
+        #expect(output.inserted == ["spaced ", "bare ", "off"])
+    }
+
+    @Test func aThrowingInsertBecomesAFailure() async throws {
+        let output = FakeOutput()
+        output.shouldFail = true
+        output.failure = OutputError.eventCreationFailed
+        let (outcome, _) = await run(finish(output: output), input(.whole(try await loaded("hello world"))))
+        #expect(outcome == .failed(.pasteKeystroke))
+    }
+
+    @Test func aThrowingEngineBecomesAFailureBeforeAnyStage() async throws {
+        let engine = EchoEngine(text: "never loaded")
+        let (outcome, stages) = await run(finish(), input(.whole(engine)))
+        #expect(outcome == .failed(.engineNotLoaded))
+        #expect(stages.isEmpty)
+    }
+}
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index f2094b9..28b156d 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -71,14 +71,21 @@ the rest runs in `inFlight`:
    release is still handed over, so every sample reaches the engine once and
    in order. This wait counts as engine time;
 2. stop the capture, which returns only the samples after the last drain;
-3. `finish`: drop a recording under 0.3 s, then `endUtterance` with the tail
-   (or `transcribe` the whole buffer), run the processor pipeline, polish if
-   the cycle asked for it and the text has four words or more, append the
-   trailing space, and `insert`. Words are counted by `String.wordCount` in
-   Core, the count the polishers cut their chunks by. `lastTranscript`, the
-   menu's "Last" line and its copy, is set to the processed text just before
-   `insert`, so a paste that fails leaves that text there, not the engine's;
-   a dictation the processors empty pastes nothing and leaves it as it was.
+3. `DictationFinish.run`: drop a recording under 0.3 s, then `endUtterance`
+   with the tail (or `transcribe` the whole buffer), run the processor
+   pipeline, polish if the cycle asked for it and the text has four words or
+   more, append the trailing space, and `insert`. Words are counted by
+   `String.wordCount` in Core, the count the polishers cut their chunks by.
+   The finish is built at release, so the pipeline, the processors switched
+   off and the trailing space are the ones set then. It owns no state: it
+   reports the polishing and inserting stages as it reaches them, and the
+   coordinator flips its state on each, and it returns an outcome (too short,
+   empty, inserted with its timing, or failed) that the coordinator turns
+   into the event and the state after. `lastTranscript`, the menu's "Last"
+   line and its copy, is set to the processed text at the inserting stage,
+   before `insert`, so a paste that fails leaves that text there, not the
+   engine's; a dictation the processors empty pastes nothing and leaves it as
+   it was.
 
 `inserted` carries the timing of every stage; the app turns it into the
 release-to-paste log line (`TimingLine.swift`).

From 5aea3837040c5a9bd1da7fd0b9b57a4f18476efc Mon Sep 17 00:00:00 2001
From: Fabian Meyer <44942030+dinooo13@users.noreply.github.com>
Date: Fri, 16 Oct 2026 15:45:03 +0200
Subject: [PATCH 12/16] Coordinator: the feed and warm loops are a
 RecordingEngineSession

The utterance, the feed loop with its live passes, and the warm loop move into
a session on the coordinator's clock. It hands back what it ended with: the
source to transcribe and the feed to wait for. The coordinator keeps the
recording number and the checks after every wait.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../PladderCore/DictationCoordinator.swift    | 115 +++-----------
 .../PladderCore/RecordingEngineSession.swift  | 134 ++++++++++++++++
 .../RecordingEngineSessionTests.swift         | 143 ++++++++++++++++++
 docs/ARCHITECTURE.md                          |  12 +-
 4 files changed, 306 insertions(+), 98 deletions(-)
 create mode 100644 Sources/PladderCore/RecordingEngineSession.swift
 create mode 100644 Tests/PladderCoreTests/RecordingEngineSessionTests.swift

diff --git a/Sources/PladderCore/DictationCoordinator.swift b/Sources/PladderCore/DictationCoordinator.swift
index 195cb29..9c6a10b 100644
--- a/Sources/PladderCore/DictationCoordinator.swift
+++ b/Sources/PladderCore/DictationCoordinator.swift
@@ -99,25 +99,12 @@ public final class DictationCoordinator {
     private var pendingUnloads: [any TranscriptionEngine] = []
     private var cycleEngine: (any TranscriptionEngine)?
 
-    // Cancelling cannot abort a CoreML call already started, so a release landing in
-    // a warm pass waits for it; the log shows that as `engine` above `engine-time`.
-    private var warmupTask: Task<Void, Never>?
-    private var stream: Stream?
-
-    private struct Stream {
-        let engine: any StreamingTranscriptionEngine
-        let utterance: Utterance
-        let feed: Task<Int, Never>
-    }
+    private var engineSession: RecordingEngineSession?
 
     private var recordingID = 0
     private var cancelCleanup: Task<Void, Never>?
     private var muteRestoreTask: Task<Void, Never>?
 
-    // Every utterance is padded to the model's full window, so half a second of
-    // silence costs the same encoder pass as a real call.
-    private static let warmupSamples = [Float](repeating: 0, count: 8_000)
-
     @ObservationIgnored private(set) var handledHotkeyEvents = 0
 
     public struct CycleTiming: Sendable, Equatable {
@@ -387,8 +374,16 @@ public final class DictationCoordinator {
         onEvent(.recordingStarted)
         armOutputMute()
         startKeyDownWork()
-        await startEngineWork(live: live, recordingID: mine)
-        guard isCurrent(mine) else { return }
+        if let engine = cycleEngine {
+            let session = RecordingEngineSession(
+                engine: engine, capture: capture, clock: clock,
+                intervals: .init(feed: feedInterval, livePass: livePassInterval, warmup: warmupInterval),
+                live: live, onPartial: { [weak self] in self?.partialTranscript = $0 })
+            engineSession = session
+            await session.begin()
+            guard isCurrent(mine) else { return }
+            session.startLoops()
+        }
         levelTask = Task { [weak self] in
             for await level in levels {
                 guard let self, self.state.isRecording else { return }
@@ -416,62 +411,6 @@ public final class DictationCoordinator {
         state.isRecording && recordingID == id
     }
 
-    // A streaming engine that cannot begin an utterance is used like a batch engine:
-    // transcribed whole at release, slower but not lost.
-    private func startEngineWork(live: Bool, recordingID id: Int) async {
-        if let streaming = cycleEngine as? (any StreamingTranscriptionEngine),
-           let utterance = try? await streaming.beginUtterance() {
-            guard isCurrent(id) else {
-                await streaming.abandonUtterance(utterance)
-                return
-            }
-            startStreamingFeed(streaming, utterance: utterance, live: live)
-            // The live loop's pass is the warm pass; a second loop would only compete with it.
-            if !live { startWarmupLoop { await streaming.warmPass() } }
-        } else if let engine = cycleEngine {
-            startWarmupLoop { [warmupSamples = Self.warmupSamples] in
-                _ = try? await engine.transcribe(warmupSamples)
-            }
-        }
-    }
-
-    // One loop for feed and live passes, so they never drain against each other. At
-    // release the loop is cancelled and awaited: a chunk drained just before is still
-    // fed, so every sample reaches the engine once and in order.
-    private func startStreamingFeed(_ engine: any StreamingTranscriptionEngine, utterance: Utterance, live: Bool) {
-        let feed = Task { [weak self, clock, feedInterval, livePassInterval] in
-            var fed = 0
-            while !Task.isCancelled {
-                if !live { try? await clock.sleep(for: feedInterval) }
-                guard let self, !Task.isCancelled, self.state.isRecording else { return fed }
-                let chunk = await self.capture.drain()
-                if !chunk.isEmpty {
-                    fed += chunk.count
-                    await engine.feed(chunk, to: utterance)
-                }
-                guard live, !Task.isCancelled else { continue }
-                let text = await engine.livePass(utterance)
-                // A pass finishing after the release would put stale text back on screen.
-                guard !Task.isCancelled, self.state.isRecording else { return fed }
-                self.partialTranscript = text
-                try? await clock.sleep(for: livePassInterval)
-            }
-            return fed
-        }
-        stream = Stream(engine: engine, utterance: utterance, feed: feed)
-    }
-
-    private func startWarmupLoop(_ warm: @escaping @Sendable () async -> Void) {
-        warmupTask?.cancel()
-        warmupTask = Task.detached(priority: .utility) { [clock, interval = warmupInterval] in
-            while !Task.isCancelled {
-                await warm()
-                if Task.isCancelled { return }
-                try? await clock.sleep(for: interval)
-            }
-        }
-    }
-
     private func armOutputMute() {
         guard settings.muteOutputWhileDictating, let outputMuter else { return }
         let session = recordingID
@@ -493,7 +432,7 @@ public final class DictationCoordinator {
     // Synchronous, and every call only flips a flag, cancels a task or spawns one,
     // so on the release path this costs nothing before `recordingStopped`.
     @discardableResult
-    private func endRecording() -> Stream? {
+    private func endRecording() -> RecordingEngineSession.Ending? {
         settleTask?.cancel()
         settleTask = nil
         gesture.reset()
@@ -504,20 +443,17 @@ public final class DictationCoordinator {
         inputLevel = 0
         maxDurationTask?.cancel()
         maxDurationTask = nil
-        let ended = stream
-        ended?.feed.cancel()
-        stream = nil
         // Before the state flip, so no further pass is queued ahead of the real call.
-        warmupTask?.cancel()
-        warmupTask = nil
+        let ending = engineSession?.end()
+        engineSession = nil
         partialTranscript = nil
         restoreOutputDevice()
-        return ended
+        return ending
     }
 
     public func hotkeyReleased(submit: Bool = false) {
         guard state.isRecording else { return }
-        let stream = endRecording()
+        let ending = endRecording()
         state = .transcribing
         // Snapshots anything copied while speaking now, beside the engine pass, not in
         // the paste.
@@ -534,19 +470,14 @@ public final class DictationCoordinator {
             // The feed loop finishes handing over a chunk drained before the release. What
             // it waits for is engine work `endUtterance` would wait for anyway: engine time.
             let handover = ContinuousClock.now
-            let fed = await stream?.feed.value
+            let fed = await ending?.feed?.value
             let stopped = ContinuousClock.now
             let feedWait = stopped - handover
             let audio = await self.capture.stop()
             let captureStop = ContinuousClock.now - stopped
-            let source: DictationFinish.Source = if let stream {
-                .utterance(stream.engine, stream.utterance)
-            } else {
-                .whole(engine)
-            }
             let outcome = await finish.run(
                 DictationFinish.Input(
-                    audio: audio, fedSamples: fed ?? 0, source: source, submit: submit,
+                    audio: audio, fedSamples: fed ?? 0, source: ending?.source ?? .whole(engine), submit: submit,
                     captureStop: captureStop, feedWait: feedWait),
                 onStage: { self.enter($0) })
             self.finished(outcome)
@@ -594,19 +525,15 @@ public final class DictationCoordinator {
     // Synchronous, so the state is idle on return; the task stops the microphone.
     private func beginCancel() -> Task<Void, Never>? {
         guard state.isRecording else { return nil }
-        let stream = endRecording()
+        let ending = endRecording()
         willPolish = false
         becomeIdle()
         cycleEngine = nil
-        // The mic goes off first; the engine drops the utterance only once the feed has
-        // exited, so no chunk lands after it. Then it waits for the cancel before it.
+        // The mic goes off first, then the utterance; then it waits for the cancel before it.
         let previous = cancelCleanup
         let cleanup = Task { [capture] in
             _ = await capture.stop()
-            if let stream {
-                _ = await stream.feed.value
-                await stream.engine.abandonUtterance(stream.utterance)
-            }
+            await ending?.abandon()
             await previous?.value
         }
         cancelCleanup = cleanup
diff --git a/Sources/PladderCore/RecordingEngineSession.swift b/Sources/PladderCore/RecordingEngineSession.swift
new file mode 100644
index 0000000..5f6422d
--- /dev/null
+++ b/Sources/PladderCore/RecordingEngineSession.swift
@@ -0,0 +1,134 @@
+import Foundation
+
+// See docs/ARCHITECTURE.md, "Dictation flow".
+@MainActor
+final class RecordingEngineSession {
+    struct Intervals: Sendable {
+        var feed: Duration
+        var livePass: Duration
+        var warmup: Duration
+    }
+
+    struct Ending: Sendable {
+        let source: DictationFinish.Source
+        // Awaited at release: a chunk drained just before is still fed, so every sample
+        // reaches the engine once and in order.
+        let feed: Task<Int, Never>?
+
+        // The engine drops the utterance only once the feed has exited, so no chunk lands
+        // after it.
+        func abandon() async {
+            guard case .utterance(let engine, let utterance) = source else { return }
+            _ = await feed?.value
+            await engine.abandonUtterance(utterance)
+        }
+    }
+
+    // Every utterance is padded to the model's full window, so half a second of
+    // silence costs the same encoder pass as a real call.
+    static let warmupSamples = [Float](repeating: 0, count: 8_000)
+
+    private let engine: any TranscriptionEngine
+    private let capture: any AudioCapture
+    private let clock: any Clock<Duration>
+    private let intervals: Intervals
+    private let live: Bool
+    private let onPartial: @MainActor (String?) -> Void
+    private var streaming: (engine: any StreamingTranscriptionEngine, utterance: Utterance)?
+    private var feed: Task<Int, Never>?
+    // Cancelling cannot abort a CoreML call already started, so a release landing in
+    // a warm pass waits for it; the log shows that as `engine` above `engine-time`.
+    private var warmup: Task<Void, Never>?
+    private(set) var isEnded = false
+
+    init(
+        engine: any TranscriptionEngine,
+        capture: any AudioCapture,
+        clock: any Clock<Duration>,
+        intervals: Intervals,
+        live: Bool,
+        onPartial: @escaping @MainActor (String?) -> Void
+    ) {
+        self.engine = engine
+        self.capture = capture
+        self.clock = clock
+        self.intervals = intervals
+        self.live = live
+        self.onPartial = onPartial
+    }
+
+    // A streaming engine that cannot begin an utterance is used like a batch engine:
+    // transcribed whole at release, slower but not lost.
+    func begin() async {
+        guard let engine = engine as? (any StreamingTranscriptionEngine),
+              let utterance = try? await engine.beginUtterance()
+        else { return }
+        guard !isEnded else {
+            await engine.abandonUtterance(utterance)
+            return
+        }
+        streaming = (engine, utterance)
+    }
+
+    func startLoops() {
+        guard !isEnded else { return }
+        if let streaming {
+            startFeed(streaming.engine, utterance: streaming.utterance)
+            // The live loop's pass is the warm pass; a second loop would only compete with it.
+            if !live { startWarmupLoop { [engine = streaming.engine] in await engine.warmPass() } }
+        } else {
+            startWarmupLoop { [engine, warmupSamples = Self.warmupSamples] in
+                _ = try? await engine.transcribe(warmupSamples)
+            }
+        }
+    }
+
+    // Synchronous: it only cancels, so the release path waits on nothing here.
+    @discardableResult
+    func end() -> Ending {
+        isEnded = true
+        feed?.cancel()
+        warmup?.cancel()
+        warmup = nil
+        let source: DictationFinish.Source = if let streaming {
+            .utterance(streaming.engine, streaming.utterance)
+        } else {
+            .whole(engine)
+        }
+        return Ending(source: source, feed: feed)
+    }
+
+    // One loop for feed and live passes, so they never drain against each other.
+    private func startFeed(_ engine: any StreamingTranscriptionEngine, utterance: Utterance) {
+        feed = Task { [weak self, capture, clock, intervals, live] in
+            var fed = 0
+            while !Task.isCancelled {
+                if !live { try? await clock.sleep(for: intervals.feed) }
+                guard let self, !Task.isCancelled, !self.isEnded else { return fed }
+                let chunk = await capture.drain()
+                if !chunk.isEmpty {
+                    fed += chunk.count
+                    await engine.feed(chunk, to: utterance)
+                }
+                guard live, !Task.isCancelled else { continue }
+                let text = await engine.livePass(utterance)
+                // A pass finishing after the release would put stale text back on screen.
+                guard !Task.isCancelled, !self.isEnded else { return fed }
+                self.onPartial(text)
+                try? await clock.sleep(for: intervals.livePass)
+            }
+            return fed
+        }
+    }
+
+    private func startWarmupLoop(_ warm: @escaping @Sendable () async -> Void) {
+        warmup?.cancel()
+        warmup = Task.detached(priority: .utility) { [clock, interval = intervals.warmup] in
+            while !Task.isCancelled {
+                await warm()
+                if Task.isCancelled { return }
+                try? await clock.sleep(for: interval)
+            }
+        }
+    }
+}
diff --git a/Tests/PladderCoreTests/RecordingEngineSessionTests.swift b/Tests/PladderCoreTests/RecordingEngineSessionTests.swift
new file mode 100644
index 0000000..2ef2cac
--- /dev/null
+++ b/Tests/PladderCoreTests/RecordingEngineSessionTests.swift
@@ -0,0 +1,143 @@
+import Foundation
+import PladderTestSupport
+import Testing
+@testable import PladderCore
+
+@MainActor
+@Suite(.timeLimit(.minutes(1))) struct RecordingEngineSessionTests {
+    private func session(
+        _ engine: any TranscriptionEngine, clock: ManualClock, live: Bool = false,
+        partials: Recorder<String?> = Recorder()
+    ) async -> RecordingEngineSession {
+        let capture = FakeCapture()
+        await capture.setDrainSamples(Array(repeating: 0.1, count: 8_000))
+        return RecordingEngineSession(
+            engine: engine, capture: capture, clock: clock,
+            intervals: .init(feed: .seconds(1), livePass: .milliseconds(500), warmup: .seconds(2)),
+            live: live, onPartial: { partials.append($0) })
+    }
+
+    private func loadedStreaming(
+        livePassDelay: Duration = .zero, feedDelay: Duration = .zero, beginDelay: Duration = .zero,
+        beginFails: Bool = false
+    ) async throws -> FakeStreamingEngine {
+        let engine = FakeStreamingEngine(
+            livePassDelay: livePassDelay, feedDelay: feedDelay, beginDelay: beginDelay, beginFails: beginFails)
+        try await engine.load()
+        return engine
+    }
+
+    @Test func theFeedLoopHandsOverEveryDrainedChunkOnce() async throws {
+        let clock = ManualClock()
+        let engine = try await loadedStreaming()
+        let s = await session(engine, clock: clock)
+        await s.begin()
+        s.startLoops()
+        for second in 1...3 {
+            #expect(await clock.waitForSleeper(at: .seconds(second)))
+            clock.advance(to: .seconds(second))
+            #expect(await waitUntil { engine.feedCounts.count == second })
+        }
+        let ending = s.end()
+        guard case .utterance = ending.source else {
+            Issue.record("expected the utterance, got \(ending.source)")
+            return
+        }
+        #expect(await ending.feed?.value == 24_000)
+        #expect(engine.feedCounts == [8_000, 8_000, 8_000])
+    }
+
+    @Test func endCancelsTheWarmLoopBeforeReturning() async throws {
+        let clock = ManualClock()
+        let engine = try await loadedStreaming()
+        let s = await session(engine, clock: clock)
+        await s.begin()
+        s.startLoops()
+        #expect(await waitUntil { engine.warmPassCount == 1 })
+        #expect(await clock.waitForSleeper(at: .seconds(2)))
+        s.end()
+        #expect(clock.sleeperCount == 0)
+        clock.advance(by: .seconds(10))
+        #expect(engine.warmPassCount == 1)
+    }
+
+    @Test func aLivePassFinishingAfterEndPublishesNothing() async throws {
+        let clock = ManualClock()
+        let engine = try await loadedStreaming(livePassDelay: .milliseconds(50))
+        let partials = Recorder<String?>()
+        let s = await session(engine, clock: clock, live: true, partials: partials)
+        await s.begin()
+        s.startLoops()
+        #expect(await waitUntil { partials.all == ["partial 1"] })
+        #expect(await clock.waitForSleeper(at: .milliseconds(500)))
+        clock.advance(to: .milliseconds(500))
+        #expect(await waitUntil { engine.livePassCount == 2 })
+        let ending = s.end()
+        _ = await ending.feed?.value
+        #expect(partials.all == ["partial 1"])
+        #expect(engine.warmPassCount == 0)
+    }
+
+    @Test func aBatchEngineGetsOnlyTheWarmLoop() async throws {
+        let clock = ManualClock()
+        let engine = CountingEngine()
+        try await engine.load()
+        let s = await session(engine, clock: clock)
+        await s.begin()
+        s.startLoops()
+        #expect(await waitUntil { engine.calls == [8_000] })
+        let ending = s.end()
+        guard case .whole = ending.source else {
+            Issue.record("expected the whole buffer, got \(ending.source)")
+            return
+        }
+        #expect(ending.feed == nil)
+        #expect(clock.sleeperCount == 0)
+    }
+
+    @Test func aStreamingEngineThatCannotBeginIsWarmedAndTranscribedWhole() async throws {
+        let clock = ManualClock()
+        let engine = try await loadedStreaming(beginFails: true)
+        let s = await session(engine, clock: clock)
+        await s.begin()
+        s.startLoops()
+        #expect(await waitUntil { engine.log.contains("transcribe") })
+        let ending = s.end()
+        guard case .whole = ending.source else {
+            Issue.record("expected the whole buffer, got \(ending.source)")
+            return
+        }
+        #expect(ending.feed == nil)
+    }
+
+    @Test func abandonWaitsForTheFeedBeforeDroppingTheUtterance() async throws {
+        let clock = ManualClock()
+        let engine = try await loadedStreaming(feedDelay: .milliseconds(50))
+        let s = await session(engine, clock: clock)
+        await s.begin()
+        s.startLoops()
+        #expect(await clock.waitForSleeper(at: .seconds(1)))
+        clock.advance(to: .seconds(1))
+        #expect(await waitUntil { engine.isFeeding })
+        await s.end().abandon()
+        #expect(Array(engine.log.suffix(2)) == ["fed", "abandon"])
+    }
+
+    @Test func aBeginOvertakenByEndDropsItsUtteranceAndStartsNoLoop() async throws {
+        let clock = ManualClock()
+        let engine = try await loadedStreaming(beginDelay: .milliseconds(50))
+        let s = await session(engine, clock: clock)
+        let beginning = Task { await s.begin() }
+        #expect(await waitUntil { engine.log.contains("begin") })
+        let ending = s.end()
+        await beginning.value
+        s.startLoops()
+        guard case .whole = ending.source else {
+            Issue.record("expected the whole buffer, got \(ending.source)")
+            return
+        }
+        #expect(engine.log.last == "abandon")
+        #expect(clock.sleeperCount == 0)
+        #expect(engine.warmPassCount == 0)
+    }
+}
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 28b156d..675d4ff 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -46,9 +46,10 @@ its timers with `ManualClock`.
    running, and starts the capture;
 4. arms the output mute and starts the key-down work: the clipboard snapshot
    and the polish model's load;
-5. starts the engine work. A streaming engine begins an utterance and gets a
-   feed loop. In the other styles the loop wakes every second and hands the
-   engine the audio captured since. With the Live Transcript style it skips
+5. starts the engine work, a `RecordingEngineSession` on the coordinator's
+   clock. A streaming engine begins an utterance and gets a feed loop. In
+   the other styles the loop wakes every second and hands the engine the
+   audio captured since. With the Live Transcript style it skips
    that second: each turn hands over what has been captured, asks for the
    text so far, publishes it as `partialTranscript` and then waits half a
    second, so audio goes in on the live-pass cadence. Outside Live
@@ -57,7 +58,10 @@ its timers with `ManualClock`.
    Neural Engine from going cold; in Live Transcript the live passes keep it
    warm instead. A batch engine, or a streaming one that could not begin,
    gets the warm loop in every style, and nothing else, and is transcribed
-   whole at release;
+   whole at release. A session ended while its utterance was still beginning
+   drops that utterance itself and starts no loop. At release or cancel the
+   session hands the coordinator what it ended with: the utterance or the
+   whole buffer to transcribe, and the feed loop to wait for;
 6. starts the level meter and the 10 minute cap.
 
 **Release** (`hotkeyReleased`). `endRecording()` stops everything the press

From b279fdb780827f45b626599aeaa7534c334a59ad Mon Sep 17 00:00:00 2001
From: Fabian Meyer <44942030+dinooo13@users.noreply.github.com>
Date: Fri, 16 Oct 2026 15:59:54 +0200
Subject: [PATCH 13/16] Core: one Generation for the recording number and the
 mute's arm

The coordinator's recording number and OutputMuteController's arm counter
read the same way: next() when new work starts, isCurrent(_:) when the old
work wakes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../PladderCore/DictationCoordinator.swift    | 11 +++++-----
 Sources/PladderCore/Support/Generation.swift  | 18 +++++++++++++++++
 .../Support/OutputMuteController.swift        | 11 +++++-----
 Tests/PladderCoreTests/GenerationTests.swift  | 20 +++++++++++++++++++
 4 files changed, 48 insertions(+), 12 deletions(-)
 create mode 100644 Sources/PladderCore/Support/Generation.swift
 create mode 100644 Tests/PladderCoreTests/GenerationTests.swift

diff --git a/Sources/PladderCore/DictationCoordinator.swift b/Sources/PladderCore/DictationCoordinator.swift
index 9c6a10b..aa77bbd 100644
--- a/Sources/PladderCore/DictationCoordinator.swift
+++ b/Sources/PladderCore/DictationCoordinator.swift
@@ -101,7 +101,7 @@ public final class DictationCoordinator {
 
     private var engineSession: RecordingEngineSession?
 
-    private var recordingID = 0
+    private var recording = Generation()
     private var cancelCleanup: Task<Void, Never>?
     private var muteRestoreTask: Task<Void, Never>?
 
@@ -347,8 +347,7 @@ public final class DictationCoordinator {
         // concurrent press cannot start capture twice.
         state = .recording
         inputLevel = 0
-        recordingID += 1
-        let mine = recordingID
+        let mine = recording.next()
         hotkeyMonitor.setCancelKeyEnabled(true)
         // Waits for every earlier cancel to stop its microphone and drop its utterance.
         await cancelCleanup?.value
@@ -408,12 +407,12 @@ public final class DictationCoordinator {
     }
 
     private func isCurrent(_ id: Int) -> Bool {
-        state.isRecording && recordingID == id
+        state.isRecording && recording.isCurrent(id)
     }
 
     private func armOutputMute() {
         guard settings.muteOutputWhileDictating, let outputMuter else { return }
-        let session = recordingID
+        let session = recording.current
         Task { await outputMuter.recordingStarted(session: session) }
     }
 
@@ -421,7 +420,7 @@ public final class DictationCoordinator {
     // device. Detached so the paste never waits on CoreAudio.
     private func restoreOutputDevice() {
         guard let outputMuter else { return }
-        let session = recordingID
+        let session = recording.current
         let previous = muteRestoreTask
         muteRestoreTask = Task.detached(priority: .utility) {
             await previous?.value
diff --git a/Sources/PladderCore/Support/Generation.swift b/Sources/PladderCore/Support/Generation.swift
new file mode 100644
index 0000000..4673f67
--- /dev/null
+++ b/Sources/PladderCore/Support/Generation.swift
@@ -0,0 +1,18 @@
+import Foundation
+
+// See docs/ARCHITECTURE.md, "Superseded work".
+public struct Generation: Sendable, Equatable {
+    public private(set) var current = 0
+
+    public init() {}
+
+    @discardableResult
+    public mutating func next() -> Int {
+        current += 1
+        return current
+    }
+
+    public func isCurrent(_ id: Int) -> Bool {
+        id == current
+    }
+}
diff --git a/Sources/PladderCore/Support/OutputMuteController.swift b/Sources/PladderCore/Support/OutputMuteController.swift
index 1e15d0e..ee892df 100644
--- a/Sources/PladderCore/Support/OutputMuteController.swift
+++ b/Sources/PladderCore/Support/OutputMuteController.swift
@@ -9,7 +9,7 @@ public actor OutputMuteController: OutputMuter {
     private let log: @Sendable (String) -> Void
 
     // A pending arm that wakes to find this changed belongs to a session already over.
-    private var generation = 0
+    private var generation = Generation()
     private var latestSession: Int?
     private var restore: (device: UInt32, state: MuteState)?
 
@@ -25,15 +25,14 @@ public actor OutputMuteController: OutputMuter {
         self.log = log
     }
 
-    var armedGeneration: Int { generation }
+    var armedGeneration: Int { generation.current }
 
     public func recordingStarted(session: Int) async {
         if let latestSession, session <= latestSession { return }
         latestSession = session
-        generation += 1
-        let mine = generation
+        let mine = generation.next()
         try? await clock.sleep(for: delay)
-        guard generation == mine else { return }
+        guard generation.isCurrent(mine) else { return }
         guard restore == nil else {
             // An earlier session muted it and its end has not come; this session's end restores it.
             log("output still muted from the previous recording")
@@ -71,7 +70,7 @@ public actor OutputMuteController: OutputMuter {
         if let latestSession, session < latestSession { return }
         latestSession = session
         // Also disarms a mute that has not landed yet.
-        generation += 1
+        generation.next()
         guard let restore else { return }
         self.restore = nil
         do {
diff --git a/Tests/PladderCoreTests/GenerationTests.swift b/Tests/PladderCoreTests/GenerationTests.swift
new file mode 100644
index 0000000..cb7d67f
--- /dev/null
+++ b/Tests/PladderCoreTests/GenerationTests.swift
@@ -0,0 +1,20 @@
+import Testing
+@testable import PladderCore
+
+@Suite struct GenerationTests {
+    @Test func eachNextIsCurrentUntilTheOneAfter() {
+        var generation = Generation()
+        let first = generation.next()
+        #expect(generation.isCurrent(first))
+        let second = generation.next()
+        #expect(!generation.isCurrent(first))
+        #expect(generation.isCurrent(second))
+        #expect(generation.current == second)
+    }
+
+    @Test func nothingIsCurrentBeforeTheFirstNext() {
+        let generation = Generation()
+        #expect(!generation.isCurrent(1))
+        #expect(generation.current == 0)
+    }
+}

From 55a69c93866ed027cdee4d516913ee22f6db1a41 Mon Sep 17 00:00:00 2001
From: Fabian Meyer <44942030+dinooo13@users.noreply.github.com>
Date: Fri, 16 Oct 2026 15:59:54 +0200
Subject: [PATCH 14/16] Docs: superseded work is one rule with its sites
 listed, and the speakers' restore chain has a test

ARCHITECTURE gains "Superseded work": the rule, every place that keeps it,
and the test convention for detached tasks. The one detached task without a
supersede test, the speakers' restore waiting for the one before it, gets
aSecondRecordingsRestoreWaitsForTheFirst.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../CoordinatorRegressionTests.swift          | 36 ++++++++++++
 docs/ARCHITECTURE.md                          | 58 ++++++++++++++++++-
 2 files changed, 91 insertions(+), 3 deletions(-)

diff --git a/Tests/PladderCoreTests/CoordinatorRegressionTests.swift b/Tests/PladderCoreTests/CoordinatorRegressionTests.swift
index a7f6996..371b3ec 100644
--- a/Tests/PladderCoreTests/CoordinatorRegressionTests.swift
+++ b/Tests/PladderCoreTests/CoordinatorRegressionTests.swift
@@ -287,6 +287,42 @@ import Testing
         #expect(output.inserted == ["hello world "])
         #expect(output.flushCount == 1)
     }
+
+    @Test func aSecondRecordingsRestoreWaitsForTheFirst() async {
+        let gate = Gate()
+        let muter = GatedOutputMuter(holdingTheEndOf: 1, on: gate)
+        var settings = DictationSettings(engineID: EchoEngine.engineID)
+        settings.muteOutputWhileDictating = true
+        let (c, _, _) = makeCoordinator(settings: settings, outputMuter: muter)
+        await c.startIdle()
+        await c.dictate()
+        await gate.untilSomeoneWaits()
+        await c.dictate()
+        #expect(muter.ended.isEmpty)
+        await gate.open()
+        #expect(await waitUntil { muter.ended.count == 2 })
+        #expect(muter.ended == [1, 2])
+    }
+}
+
+private final class GatedOutputMuter: OutputMuter, @unchecked Sendable {
+    private let lock = NSLock()
+    private let held: Int
+    private let gate: Gate
+    private var _ended: [Int] = []
+    var ended: [Int] { lock.withLock { _ended } }
+
+    init(holdingTheEndOf held: Int, on gate: Gate) {
+        self.held = held
+        self.gate = gate
+    }
+
+    func recordingStarted(session: Int) async {}
+
+    func recordingEnded(session: Int) async {
+        if session == held { await gate.wait() }
+        lock.withLock { _ended.append(session) }
+    }
 }
 
 @MainActor
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 675d4ff..eb8e325 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -39,9 +39,9 @@ its timers with `ManualClock`.
    mid-recording cannot change this cycle;
 2. flips the state to `.recording`, before the first `await`, so the overlay
    reacts at once and a second press cannot start the microphone twice, and
-   numbers the recording (`recordingID`). After every wait below the press
-   checks it is still the current recording, and stops if a cancel ended it
-   meanwhile;
+   numbers the recording (`recording`, a `Generation`). After every wait
+   below the press checks it is still the current recording, and stops if a
+   cancel ended it meanwhile;
 3. turns Escape into the cancel key, waits for every earlier cancel still
    running, and starts the capture;
 4. arms the output mute and starts the key-down work: the clipboard snapshot
@@ -445,6 +445,58 @@ The coordinator sees only `DictationSettings`, and the app assigns a new
 value only when that part changed. `PLADDER_SETTINGS_PATH` points a test copy
 at a file of its own.
 
+## Superseded work
+
+Most of the races the reviews found had one shape: work that outlives what it
+was started for (a timer, a detached task, a callback on another thread, an
+engine call that cannot be aborted) finishes after something newer has taken
+its place, and acts on the newer one. The rule everywhere: such work takes a
+number or an identity when it starts and compares it against the current one
+before it acts; a mismatch means it was superseded and does nothing.
+Cancelling alone is not enough: a task past its last cancellation check, or a
+call into an actor waiting its turn, runs on regardless. `Generation` in Core
+is the counter for the plain case: `next()` when the new work starts,
+`isCurrent(_:)` when the old work wakes.
+
+| Where | What is compared | What it keeps out |
+|---|---|---|
+| `DictationCoordinator`, `recording` | The recording's `Generation`, after every wait in `hotkeyPressed` (`isCurrent`) | A press cancelled while it waited starting the microphone or the engine for a recording that is over |
+| `UtteranceSlot` | The `Utterance` handle | A cancelled recording's late feed, live pass or abandon reaching the next utterance |
+| `RecordingEngineSession` | Whether it has ended, when its utterance has begun | An utterance begun after its recording ended being fed or left open |
+| `OutputMuteController`, `generation` and `latestSession` | The arm's `Generation` when its delay ends; the session number of every start and end | A mute landing after its recording ended; an older recording's end unmuting a newer one |
+| `ClipboardKeeper`, `restoreID` | The number of the latest restore scheduling | A restore that woke at its old instant putting the old clipboard back after a later read moved it |
+| `ClipboardKeeper`, read waiters | The waiter's number | A read timer resolving a waiter that a read already resolved |
+| `ClipboardKeeper`, `TranscriptPromise` | The promise's identity (`===`) | A read or restore of an earlier paste acting on the current one |
+| `ClipboardKeeper`, the pasteboard's `changeCount` | The count after the transcript went on | A restore overwriting a copy the user made in between |
+| `PasteboardOutput`, `owedReturn` | The owed Return's identity | A send's Return posted twice, by its timer and by the next paste |
+| `HotkeyMonitorLifecycle`, `generation` | The session's number, also packed into `CarbonHotkeySession`'s hot key IDs | A tap or Carbon handler made after its session ended being adopted; an old session's hot key events being found |
+| `HotkeyRecordingSlot` | The recorder's token | A freed recorder ending the session of the field that took over |
+| `ObservationLoop`, `generation` | The loop's number in each re-armed callback | A callback pending at `stop()` re-arming the loop |
+| `EngineLoader` | `engine === self.engine` | A superseded load's status reaching the engine that replaced it |
+| `ModelFiles`, `isCurrent(file, id)` | The download's ID | A cancelled download or checksum writing its status over the next one |
+| `S1MiniPolisher`, `generation` | The load's number | A load finishing after an unload or a switch keeping its model resident |
+| `OnDeviceLanguageModel`, `leftover` | The abandoned call's task identity | A drain clearing the slot of a call abandoned after it |
+| `OverlayPanel`, `generation` | The animation's number | A hide's or show's completion handler acting on the next one |
+
+**Tests.** Every detached task has a test that supersedes or cancels it while
+it runs, on `ManualClock` where it sleeps on a clock and on a `Gate` where it
+waits on other work:
+
+| Detached task | Test |
+|---|---|
+| The warm loop (`RecordingEngineSession`) | `theWarmLoopRunsOnTheClockAndStopsAtRelease`, `endCancelsTheWarmLoopBeforeReturning` |
+| The speakers' restore (`DictationCoordinator.restoreOutputDevice`) | `aSecondRecordingsRestoreWaitsForTheFirst` |
+| The owed Return (`PasteboardOutput`) | `aSendStillWaitingPostsItsReturnBeforeTheNextPaste` |
+| The clipboard restore (`ClipboardKeeper`) | `aRestoreThatWokeBeforeALaterReadDoesNothing`, `aNewerPasteTakesOverThePendingRestore` |
+| The read waiter's timer (`ClipboardKeeper.firstRead`) | `returnWaitsForTheReadPlusTheSubmitDelay`, `returnWithoutAReadComesAtTheFloor` |
+| `firstOf`'s work and timer | `theDeadlineWinsOverWorkThatIgnoresCancellation` |
+| The checksum (`ModelFiles`) | `cancelReachesTheChecksum`, `theChecksumStopsBetweenChunksWhenCancelled` |
+
+Exempt are the fire-and-forget calls that are idempotent and leave nothing
+to supersede: `refiner.prepare()` at key-down, `S1MiniPolisher.warmUpRuntime`,
+`session.prewarm()` in `OnDeviceLanguageModel`, and `CorrectionLearner.pasted`,
+whose watch a new paste ends through the observer.
+
 ## The app
 
 `AppModel` is the composition root. It builds the engine registry, the

From 4634ed825188804a1864be5ca365f2ce2c32357b Mon Sep 17 00:00:00 2001
From: Fabian Meyer <44942030+dinooo13@users.noreply.github.com>
Date: Fri, 16 Oct 2026 15:28:41 +0200
Subject: [PATCH 15/16] Hotkeys: which monitor and which stand-in is
 HotkeyRouting, a value in Core

The router's decision (the grant, the sustained secure-input reading, the first observation's stand-in, a chord change with the last reading) moves out of the app into `HotkeyRouting`, which returns one `Change` carrying the source and the stand-in together. `HotkeyRouter` keeps the monitors and hands each change to the coordinator in one update.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md                                     |   2 +-
 Sources/Pladder/HotkeyRouter.swift            |  63 ++++-----
 Sources/PladderCore/HotkeyRouting.swift       |  65 ++++++++++
 .../PladderCoreTests/HotkeyRoutingTests.swift | 121 ++++++++++++++++++
 docs/ARCHITECTURE.md                          |  19 ++-
 5 files changed, 223 insertions(+), 47 deletions(-)
 create mode 100644 Sources/PladderCore/HotkeyRouting.swift
 create mode 100644 Tests/PladderCoreTests/HotkeyRoutingTests.swift

diff --git a/CLAUDE.md b/CLAUDE.md
index dba4322..931a907 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -74,7 +74,7 @@ swift run -c release pladder-cli polish-set docs/polish-set.json --model s1-mini
 - Adding a hotkey role: a case in `HotkeyRole`, a `Hotkey` field in `Settings` with `[]` meaning off, an entry in the chords `startHotkey` hands the monitor and a mode in `startGesture`, a `HotkeyRecorderField` row. The monitors and trackers need nothing.
 - Adding a language: add a `<code>` localization to both catalogs; nothing else. Adding a *string*: the key is the exact English text, and `PladderCore` never holds one — it emits an enum case and `Sources/Pladder/StatusText.swift` words it.
 - Engine and capture are actors. The coordinator is `@MainActor` because it drives UI. It owns the state machine and nothing else; every dependency is injected, its clock included, so tests run it with in-memory fakes and fire its timers with `ManualClock`. It sees `DictationSettings`, the part of `Settings` it acts on, and the app hands it a new value only when that part changed.
-- The app target is split by job: `AppModel` is the composition root and owns the settings; `HotkeyRouter` picks the tap or Carbon (the rule itself is `HotkeySource.choose` in Core); `PermissionMonitor` polls the grants; `PolishModelController` owns the polish model and its file; `CorrectionInbox` the learned corrections; `SettingsLocation` the files. Decisions worth testing go to Core as values (`HotkeyWarning`, `HotkeySource`, the timing line) and the app words them in `StatusText.swift`. Views talk to `AppModel` and its parts, not to the coordinator.
+- The app target is split by job: `AppModel` is the composition root and owns the settings; `HotkeyRouter` holds the tap and Carbon monitors (which one, and the stand-in, is `HotkeyRouting` in Core); `PermissionMonitor` polls the grants; `PolishModelController` owns the polish model and its file; `CorrectionInbox` the learned corrections; `SettingsLocation` the files. Decisions worth testing go to Core as values (`HotkeyWarning`, `HotkeySource`, `HotkeyRouting`, the timing line) and the app words them in `StatusText.swift`. Views talk to `AppModel` and its parts, not to the coordinator.
 
 ## Code style
 
diff --git a/Sources/Pladder/HotkeyRouter.swift b/Sources/Pladder/HotkeyRouter.swift
index 9030b7e..8130791 100644
--- a/Sources/Pladder/HotkeyRouter.swift
+++ b/Sources/Pladder/HotkeyRouter.swift
@@ -3,77 +3,62 @@ import Observation
 import PladderCore
 import PladderSystem
 
-// Both monitors live for the app's life, so switching costs nothing. The rule is
-// `HotkeySource.choose`; see docs/ARCHITECTURE.md, "Hotkeys".
+// Both monitors live for the app's life, so switching costs nothing. The decision is
+// `HotkeyRouting`; see docs/ARCHITECTURE.md, "Hotkeys".
 @MainActor
 @Observable
 final class HotkeyRouter {
-    private(set) var usesTap: Bool
-    private(set) var accessibilityTrusted: Bool
+    // Written only when it changed, so a poll with nothing new invalidates no view.
+    private var routing: HotkeyRouting
     // `CopySymbolicHotKeys` is main-thread work linear in the shortcut count: read at launch,
     // a permission flip and settings opening, never on a key press.
     private(set) var systemShortcuts: Set<Hotkey> = []
-    private(set) var hotkey: Hotkey
 
     @ObservationIgnored private let tap = GlobalHotkeyMonitor()
     @ObservationIgnored private let carbon = CarbonHotkeyMonitor()
-    @ObservationIgnored private var secureInput = SustainedCondition()
-    @ObservationIgnored private var secureInputSustained = false
     @ObservationIgnored private weak var coordinator: DictationCoordinator?
-    // So the first `update` applies the stand-in even though nothing flipped.
-    @ObservationIgnored private var didApplyStandIn = false
 
     init(accessibilityTrusted: Bool, hotkey: Hotkey) {
-        self.accessibilityTrusted = accessibilityTrusted
-        self.hotkey = hotkey
-        usesTap = accessibilityTrusted
+        routing = HotkeyRouting(accessibilityTrusted: accessibilityTrusted, hotkey: hotkey)
     }
 
-    var initialMonitor: any HotkeyMonitor { usesTap ? tap : carbon }
+    var initialMonitor: any HotkeyMonitor { monitor(for: routing.source) }
 
     func attach(_ coordinator: DictationCoordinator) {
         self.coordinator = coordinator
     }
 
-    func update(accessibilityTrusted trusted: Bool, secureInputEnabled: Bool) {
-        if trusted != accessibilityTrusted { accessibilityTrusted = trusted }
-        secureInputSustained = secureInput.observe(secureInputEnabled)
-        let flipped = chooseMonitor()
-        guard flipped != nil || !didApplyStandIn else { return }
-        didApplyStandIn = true
-        // One update: the new monitor started first with the old stand-in
-        // would have Carbon refuse a modifier-only chord.
+    func update(accessibilityTrusted: Bool, secureInputEnabled: Bool) {
+        var next = routing
+        let change = next.observe(accessibilityTrusted: accessibilityTrusted, secureInputEnabled: secureInputEnabled)
+        if next != routing { routing = next }
+        guard let change else { return }
         if let coordinator {
-            coordinator.update(coordinator.settings, standInHotkey: standInHotkey, monitor: flipped)
+            coordinator.update(
+                coordinator.settings, standInHotkey: change.standInHotkey, monitor: change.source.map(monitor(for:)))
         }
         refreshSystemShortcuts()
     }
 
     func hotkeyChanged(to hotkey: Hotkey) -> (any HotkeyMonitor)? {
-        guard hotkey != self.hotkey else { return nil }
-        self.hotkey = hotkey
-        return chooseMonitor()
+        guard hotkey != routing.hotkey else { return nil }
+        return routing.hotkeyChanged(to: hotkey).map(monitor(for:))
     }
 
-    private func chooseMonitor() -> (any HotkeyMonitor)? {
-        let wantsTap = HotkeySource.choose(
-            accessibilityTrusted: accessibilityTrusted, secureInputSustained: secureInputSustained,
-            hotkey: hotkey) == .tap
-        guard wantsTap != usesTap else { return nil }
-        usesTap = wantsTap
-        return wantsTap ? tap : carbon
-    }
-
-    var standInHotkey: Hotkey? {
-        accessibilityTrusted ? nil : hotkey.standInWithoutAccessibility
+    private func monitor(for source: HotkeySource) -> any HotkeyMonitor {
+        switch source {
+        case .tap: tap
+        case .carbon: carbon
+        }
     }
 
-    var usesCarbonForSecureInput: Bool { accessibilityTrusted && !usesTap }
-    var hotkeyNeedsRegularKey: Bool { !accessibilityTrusted }
+    var standInHotkey: Hotkey? { routing.standInHotkey }
+    var usesCarbonForSecureInput: Bool { routing.accessibilityTrusted && routing.source == .carbon }
+    var hotkeyNeedsRegularKey: Bool { !routing.accessibilityTrusted }
 
     // Named as the matching monitor sees it: the tap tells Left from Right, Carbon cannot.
     func displayName(of chord: Hotkey) -> String {
-        usesTap ? chord.displayName : chord.sideAgnosticDisplayName
+        routing.source == .tap ? chord.displayName : chord.sideAgnosticDisplayName
     }
 
     func refreshSystemShortcuts() {
diff --git a/Sources/PladderCore/HotkeyRouting.swift b/Sources/PladderCore/HotkeyRouting.swift
new file mode 100644
index 0000000..870834d
--- /dev/null
+++ b/Sources/PladderCore/HotkeyRouting.swift
@@ -0,0 +1,65 @@
+import Foundation
+
+// See docs/ARCHITECTURE.md, "Hotkeys".
+public struct HotkeyRouting: Sendable, Equatable {
+    // Applied in one coordinator update, so the new monitor never starts with the old stand-in.
+    public struct Change: Sendable, Equatable {
+        // nil: the monitor stays.
+        public var source: HotkeySource?
+        public var standInHotkey: Hotkey?
+
+        public init(source: HotkeySource?, standInHotkey: Hotkey?) {
+            self.source = source
+            self.standInHotkey = standInHotkey
+        }
+    }
+
+    public private(set) var accessibilityTrusted: Bool
+    public private(set) var hotkey: Hotkey
+    public private(set) var source: HotkeySource
+    private var secureInput: SustainedCondition
+    // A chord changed between polls decides with the last poll's reading.
+    private var secureInputSustained = false
+    // The first observation applies the stand-in even though nothing flipped.
+    private var hasObserved = false
+
+    public init(accessibilityTrusted: Bool, hotkey: Hotkey, secureInput: SustainedCondition = SustainedCondition()) {
+        self.accessibilityTrusted = accessibilityTrusted
+        self.hotkey = hotkey
+        self.secureInput = secureInput
+        source = HotkeySource.choose(
+            accessibilityTrusted: accessibilityTrusted, secureInputSustained: false, hotkey: hotkey)
+    }
+
+    public var standInHotkey: Hotkey? {
+        accessibilityTrusted ? nil : hotkey.standInWithoutAccessibility
+    }
+
+    public mutating func observe(
+        accessibilityTrusted trusted: Bool, secureInputEnabled: Bool,
+        at instant: ContinuousClock.Instant = .now
+    ) -> Change? {
+        let standIn = standInHotkey
+        accessibilityTrusted = trusted
+        secureInputSustained = secureInput.observe(secureInputEnabled, at: instant)
+        let flipped = choose()
+        guard flipped != nil || standInHotkey != standIn || !hasObserved else { return nil }
+        hasObserved = true
+        return Change(source: flipped, standInHotkey: standInHotkey)
+    }
+
+    // The caller hands the coordinator the new chord, `standInHotkey` and this source together.
+    public mutating func hotkeyChanged(to hotkey: Hotkey) -> HotkeySource? {
+        guard hotkey != self.hotkey else { return nil }
+        self.hotkey = hotkey
+        return choose()
+    }
+
+    private mutating func choose() -> HotkeySource? {
+        let wanted = HotkeySource.choose(
+            accessibilityTrusted: accessibilityTrusted, secureInputSustained: secureInputSustained, hotkey: hotkey)
+        guard wanted != source else { return nil }
+        source = wanted
+        return wanted
+    }
+}
diff --git a/Tests/PladderCoreTests/HotkeyRoutingTests.swift b/Tests/PladderCoreTests/HotkeyRoutingTests.swift
new file mode 100644
index 0000000..26b4ea8
--- /dev/null
+++ b/Tests/PladderCoreTests/HotkeyRoutingTests.swift
@@ -0,0 +1,121 @@
+import Foundation
+import Testing
+@testable import PladderCore
+
+@Suite struct HotkeyRoutingTests {
+    private let t0 = ContinuousClock.now
+
+    private func observed(trusted: Bool, hotkey: Hotkey) -> HotkeyRouting {
+        var routing = HotkeyRouting(accessibilityTrusted: trusted, hotkey: hotkey)
+        _ = routing.observe(accessibilityTrusted: trusted, secureInputEnabled: false, at: t0)
+        return routing
+    }
+
+    @Test func itStartsOnTheMonitorTheGrantCallsFor() {
+        #expect(HotkeyRouting(accessibilityTrusted: true, hotkey: .rightCommand).source == .tap)
+        #expect(HotkeyRouting(accessibilityTrusted: false, hotkey: .rightCommand).source == .carbon)
+    }
+
+    @Test func theFirstObservationAppliesTheStandInWithoutAFlip() {
+        var routing = HotkeyRouting(accessibilityTrusted: false, hotkey: .rightCommand)
+        let change = routing.observe(accessibilityTrusted: false, secureInputEnabled: false, at: t0)
+        #expect(change == HotkeyRouting.Change(source: nil, standInHotkey: .optionSpace))
+    }
+
+    @Test func theFirstObservationWithAccessibilityAppliesNoStandIn() {
+        var routing = HotkeyRouting(accessibilityTrusted: true, hotkey: .rightCommand)
+        let change = routing.observe(accessibilityTrusted: true, secureInputEnabled: false, at: t0)
+        #expect(change == HotkeyRouting.Change(source: nil, standInHotkey: nil))
+    }
+
+    @Test func aPollWithNothingChangedYieldsNothing() {
+        var routing = observed(trusted: false, hotkey: .rightCommand)
+        #expect(routing.observe(accessibilityTrusted: false, secureInputEnabled: false, at: t0 + .seconds(2)) == nil)
+        #expect(routing.observe(accessibilityTrusted: false, secureInputEnabled: false, at: t0 + .seconds(4)) == nil)
+    }
+
+    @Test func aGrantFlipYieldsOneChangeWithTheNewSourceAndTheNewStandIn() {
+        var routing = observed(trusted: true, hotkey: .rightCommand)
+        let lost = routing.observe(accessibilityTrusted: false, secureInputEnabled: false, at: t0 + .seconds(2))
+        #expect(lost == HotkeyRouting.Change(source: .carbon, standInHotkey: .optionSpace))
+        #expect(routing.observe(accessibilityTrusted: false, secureInputEnabled: false, at: t0 + .seconds(4)) == nil)
+        let granted = routing.observe(accessibilityTrusted: true, secureInputEnabled: false, at: t0 + .seconds(6))
+        #expect(granted == HotkeyRouting.Change(source: .tap, standInHotkey: nil))
+        #expect(routing.observe(accessibilityTrusted: true, secureInputEnabled: false, at: t0 + .seconds(8)) == nil)
+    }
+
+    @Test func sustainedSecureInputMovesARegistrableChordToCarbonAfterThreeSeconds() {
+        var routing = observed(trusted: true, hotkey: .optionSpace)
+        #expect(routing.observe(accessibilityTrusted: true, secureInputEnabled: true, at: t0) == nil)
+        #expect(routing.observe(accessibilityTrusted: true, secureInputEnabled: true, at: t0 + .seconds(2)) == nil)
+        let sustained = routing.observe(accessibilityTrusted: true, secureInputEnabled: true, at: t0 + .seconds(4))
+        #expect(sustained == HotkeyRouting.Change(source: .carbon, standInHotkey: nil))
+        #expect(routing.source == .carbon)
+    }
+
+    @Test func theTapComesBackOnTheFirstPollWithoutSecureInput() {
+        var routing = observed(trusted: true, hotkey: .optionSpace)
+        for seconds in [0, 2, 4] {
+            _ = routing.observe(accessibilityTrusted: true, secureInputEnabled: true, at: t0 + .seconds(seconds))
+        }
+        let cleared = routing.observe(accessibilityTrusted: true, secureInputEnabled: false, at: t0 + .seconds(6))
+        #expect(cleared == HotkeyRouting.Change(source: .tap, standInHotkey: nil))
+    }
+
+    @Test func aModifierOnlyChordStaysOnTheTapUnderSecureInput() {
+        var routing = observed(trusted: true, hotkey: .rightCommand)
+        for seconds in [0, 2, 4, 6] {
+            #expect(routing.observe(accessibilityTrusted: true, secureInputEnabled: true, at: t0 + .seconds(seconds)) == nil)
+        }
+        #expect(routing.source == .tap)
+    }
+
+    @Test func aChordChangeUsesTheLastSecureInputReading() {
+        var routing = observed(trusted: true, hotkey: .optionSpace)
+        for seconds in [0, 2, 4] {
+            _ = routing.observe(accessibilityTrusted: true, secureInputEnabled: true, at: t0 + .seconds(seconds))
+        }
+        #expect(routing.hotkeyChanged(to: .rightCommand) == .tap)
+        #expect(routing.hotkeyChanged(to: .optionSpace) == .carbon)
+    }
+
+    @Test func aChordChangeBeforeSecureInputIsSustainedStaysOnTheTap() {
+        var routing = observed(trusted: true, hotkey: .rightCommand)
+        _ = routing.observe(accessibilityTrusted: true, secureInputEnabled: true, at: t0)
+        #expect(routing.hotkeyChanged(to: .optionSpace) == nil)
+        #expect(routing.source == .tap)
+    }
+
+    @Test func theSameChordAgainIsNoChange() {
+        var routing = observed(trusted: true, hotkey: .optionSpace)
+        #expect(routing.hotkeyChanged(to: .optionSpace) == nil)
+    }
+
+    @Test func aChordChangeWithoutAccessibilityChangesTheStandInButNotTheSource() {
+        var routing = observed(trusted: false, hotkey: .optionSpace)
+        #expect(routing.standInHotkey == nil)
+        #expect(routing.hotkeyChanged(to: .rightCommand) == nil)
+        #expect(routing.standInHotkey == .optionSpace)
+        #expect(routing.source == .carbon)
+    }
+}
+
+@MainActor
+@Suite(.timeLimit(.minutes(1))) struct HotkeyRoutingCoordinatorTests {
+    @Test func aGrantFlipAppliedInOneUpdateStartsTheNewMonitorOnceWithTheStandIn() async {
+        let tap = FakeHotkey()
+        let carbon = FakeHotkey()
+        var settings = DictationSettings(engineID: EchoEngine.engineID)
+        settings.hotkey = .rightCommand
+        let (c, _, _) = makeCoordinator(settings: settings, hotkeyMonitor: tap)
+        var routing = HotkeyRouting(accessibilityTrusted: true, hotkey: .rightCommand)
+        let first = routing.observe(accessibilityTrusted: true, secureInputEnabled: false)
+        c.update(c.settings, standInHotkey: first?.standInHotkey, monitor: nil)
+        await c.startIdle()
+        let change = routing.observe(accessibilityTrusted: false, secureInputEnabled: false)
+        let monitor = change?.source.map { $0 == .tap ? tap : carbon }
+        c.update(c.settings, standInHotkey: change?.standInHotkey, monitor: monitor)
+        #expect(tap.startedHotkeys == [.rightCommand])
+        #expect(carbon.startedHotkeys == [.optionSpace])
+    }
+}
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index eb8e325..62a384d 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -198,9 +198,11 @@ turns on `deferReleases`; from then on a stopping release comes back as a
 inside the window makes the chord held again, so the timer's token then
 matches nothing and its firing is ignored.
 
-**Tap and Carbon.** `HotkeySource.choose` picks the monitor; `HotkeyRouter`
-keeps both alive and swaps them as the Accessibility grant and Secure Event
-Input change.
+**Tap and Carbon.** `HotkeySource.choose` is the rule for one reading;
+`HotkeyRouting`, a value in Core, applies it as the Accessibility grant,
+Secure Event Input and the chord change, and says what the coordinator must
+be handed. `HotkeyRouter` in the app keeps both monitors alive and passes
+each change on.
 
 - `GlobalHotkeyMonitor` is an active `CGEvent` tap on its own run-loop
   thread. It matches any chord, swallows keys, and supports the send key and
@@ -221,7 +223,7 @@ Input change.
 
 Without Accessibility a stored chord Carbon cannot register is stood in for
 by Option+Space (`DictationCoordinator.standInHotkey`); the stored chord is
-never rewritten. A chord change runs `HotkeySource.choose` again at once,
+never rewritten. A chord change (`HotkeyRouting.hotkeyChanged`) chooses again at once,
 with the last Secure Event Input reading, and hands the coordinator the new
 chord, its stand-in and, when it changed, the other monitor together
 (`update(_:standInHotkey:monitor:)`), in one restart. Left to the next
@@ -230,8 +232,10 @@ under Secure Event Input would sit on Carbon, which cannot register it, for
 up to two seconds. `settings` and `standInHotkey` both go through `update`,
 which works out once whether the monitor restarts. A permission flip, or a
 sustained Secure Event Input, swaps the monitor the same way:
-`HotkeyRouter.update` hands the coordinator the new monitor and the stand-in
-it needs in one `update`. Set one after the other, the new monitor would
+`HotkeyRouting.observe` returns one `Change` with the new source and the
+stand-in it needs, and `HotkeyRouter.update` hands both to the coordinator
+in one `update`. The first observation returns a `Change` without a flip, so
+the stand-in is applied at launch; a poll with nothing new returns none. Set one after the other, the new monitor would
 first be started with the old stand-in, and Carbon would be handed a stored
 modifier-only chord it refuses, with the recording dropped twice.
 
@@ -504,7 +508,8 @@ settings store, the coordinator and the parts around it, owns the settings,
 and turns the coordinator's events into sounds, log lines and learning. The
 parts split off it:
 
-- `HotkeyRouter` picks the tap or Carbon and applies the stand-in chord.
+- `HotkeyRouter` holds both monitors and applies what `HotkeyRouting`
+  decides: the tap or Carbon, and the stand-in chord.
 - `PermissionMonitor` polls Accessibility, the microphone and Secure Event
   Input every two seconds for the app's life.
 - `PolishModelController` owns the polish model, its download and its memory.

From 30eeb8234abcf7b5e8ddd475c34e91f7bd99c1a6 Mon Sep 17 00:00:00 2001
From: Fabian Meyer <44942030+dinooo13@users.noreply.github.com>
Date: Fri, 16 Oct 2026 15:29:28 +0200
Subject: [PATCH 16/16] App: copying the last transcript goes through the
 coordinator and the output seam

`TextOutput` gains `copy` as a requirement, which `PasteboardOutput` already served. `DictationCoordinator.copyLastTranscript` copies the last transcript through it, so the menu's copy is tested in Core against the fake output, and `AppModel` no longer keeps the output itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Sources/Pladder/AppModel.swift                |  8 ++-----
 Sources/Pladder/OverlayDemo.swift             |  1 +
 .../PladderCore/DictationCoordinator.swift    |  5 ++++
 .../PladderCore/Protocols/TextOutput.swift    |  3 +++
 .../DictationCoordinatorTests.swift           | 24 +++++++++++++++++++
 docs/ARCHITECTURE.md                          |  3 ++-
 6 files changed, 37 insertions(+), 7 deletions(-)

diff --git a/Sources/Pladder/AppModel.swift b/Sources/Pladder/AppModel.swift
index 4ebb62d..c0468dc 100644
--- a/Sources/Pladder/AppModel.swift
+++ b/Sources/Pladder/AppModel.swift
@@ -25,7 +25,6 @@ final class AppModel {
 
     @ObservationIgnored private let store: SettingsStore
     @ObservationIgnored private let overlay: OverlayController
-    @ObservationIgnored private let output: PasteboardOutput
     @ObservationIgnored private let events = MainActorRelay<(DictationCoordinator.Event, ContinuousClock.Instant)>()
     @ObservationIgnored private var releaseInstant: ContinuousClock.Instant?
     private static let timingLog = Logger(subsystem: "de.dinooo13.pladder", category: "timing")
@@ -85,14 +84,12 @@ final class AppModel {
         let polish = PolishModelController()
         self.polish = polish
 
-        let output = PasteboardOutput()
-        self.output = output
         let events = self.events
         let coordinator = DictationCoordinator(
             settings: DictationSettings(initial),
             registry: registry,
             capture: AVAudioEngineCapture(),
-            output: output,
+            output: PasteboardOutput(),
             outputMuter: OutputMuteController(
                 control: CoreAudioOutputMute(),
                 log: { Self.muteLog.info("\($0, privacy: .public)") }),
@@ -259,8 +256,7 @@ final class AppModel {
     }
 
     func copyLastTranscript() {
-        guard let text = coordinator.lastTranscript?.text else { return }
-        Task { await output.copy(text) }
+        Task { await coordinator.copyLastTranscript() }
     }
 
     var canRetryEngine: Bool {
diff --git a/Sources/Pladder/OverlayDemo.swift b/Sources/Pladder/OverlayDemo.swift
index 5544b57..4ef7dde 100644
--- a/Sources/Pladder/OverlayDemo.swift
+++ b/Sources/Pladder/OverlayDemo.swift
@@ -153,6 +153,7 @@ private final class DemoOutput: TextOutput, @unchecked Sendable {
     init(result: InsertResult) { self.result = result }
     func insert(_ text: String, submit: Bool) async throws -> InsertResult { result }
     func prepare() async {}
+    func copy(_ text: String) async {}
 }
 
 // About as long as the on-device model takes for a short dictation.
diff --git a/Sources/PladderCore/DictationCoordinator.swift b/Sources/PladderCore/DictationCoordinator.swift
index aa77bbd..af27c4a 100644
--- a/Sources/PladderCore/DictationCoordinator.swift
+++ b/Sources/PladderCore/DictationCoordinator.swift
@@ -190,6 +190,11 @@ public final class DictationCoordinator {
         loader.load()
     }
 
+    public func copyLastTranscript() async {
+        guard let text = lastTranscript?.text else { return }
+        await output.copy(text)
+    }
+
     private func setEngineStatus(_ status: EngineStatus) {
         engineStatus = status
         if status.isReady {
diff --git a/Sources/PladderCore/Protocols/TextOutput.swift b/Sources/PladderCore/Protocols/TextOutput.swift
index 1ad9d5f..3b4c58e 100644
--- a/Sources/PladderCore/Protocols/TextOutput.swift
+++ b/Sources/PladderCore/Protocols/TextOutput.swift
@@ -23,6 +23,9 @@ public protocol TextOutput: Sendable {
     // Does now what would otherwise wait on a timer, the clipboard restore: called
     // when the app quits and a detached timer would die with it.
     func flush() async
+
+    // Leaves the text on the clipboard, nothing pasted and nothing restored over it.
+    func copy(_ text: String) async
 }
 
 extension TextOutput {
diff --git a/Tests/PladderCoreTests/DictationCoordinatorTests.swift b/Tests/PladderCoreTests/DictationCoordinatorTests.swift
index 9495f59..9de7d41 100644
--- a/Tests/PladderCoreTests/DictationCoordinatorTests.swift
+++ b/Tests/PladderCoreTests/DictationCoordinatorTests.swift
@@ -51,8 +51,10 @@ final class FakeOutput: TextOutput, @unchecked Sendable {
     private var _submitted: [Bool] = []
     private var _prepareCount = 0
     private var _flushCount = 0
+    private var _copied: [String] = []
     var inserted: [String] { lock.withLock { _inserted } }
     var flushCount: Int { lock.withLock { _flushCount } }
+    var copied: [String] { lock.withLock { _copied } }
     var submitted: [Bool] { lock.withLock { _submitted } }
     var prepareCount: Int { lock.withLock { _prepareCount } }
     var shouldFail = false
@@ -76,6 +78,10 @@ final class FakeOutput: TextOutput, @unchecked Sendable {
     func flush() async {
         lock.withLock { _flushCount += 1 }
     }
+
+    func copy(_ text: String) async {
+        lock.withLock { _copied.append(text) }
+    }
 }
 
 final class FakeHotkey: HotkeyMonitor, @unchecked Sendable {
@@ -506,6 +512,24 @@ final class EventLog: @unchecked Sendable {
         #expect(c.lastTranscript?.text == "first")
     }
 
+    @Test func copyingTheLastTranscriptGoesThroughTheOutput() async {
+        var settings = DictationSettings(engineID: EchoEngine.engineID)
+        settings.dictionary = [DictionaryEntry(from: "hello world", to: "Hello, World!")]
+        let (c, output, _) = makeCoordinator(settings: settings)
+        await c.startIdle()
+        await c.dictate()
+        await c.copyLastTranscript()
+        #expect(output.copied == ["Hello, World!"])
+        #expect(output.inserted == ["Hello, World! "])
+    }
+
+    @Test func copyingWithNoLastTranscriptDoesNothing() async {
+        let (c, output, _) = makeCoordinator()
+        await c.startIdle()
+        await c.copyLastTranscript()
+        #expect(output.copied.isEmpty)
+    }
+
     @Test func noTrailingSpaceWhenDisabled() async {
         var settings = DictationSettings(engineID: EchoEngine.engineID)
         settings.appendTrailingSpace = false
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 62a384d..9b8610c 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -271,7 +271,8 @@ user's clipboard, `KeyPoster` types the keys.
   next paste.
 - **Without Accessibility** the text is copied and stays; no restore, no
   Return. The menu's copy of the last transcript takes the same path,
-  `PasteboardOutput.copy`: the marker types, and the end of any restore
+  `DictationCoordinator.copyLastTranscript` through `TextOutput.copy`, which
+  `PasteboardOutput` serves: the marker types, and the end of any restore
   still pending, which would otherwise put the old clipboard back over it.
 - **A failed Cmd+V** puts the clipboard back at once, through the same
   restore: when every item of the user's clipboard was too large to keep,