Review and simplify the commits since 2026-10-02

[alexkroman]

What & why

A /code-review and a /simplify pass over the 16 commits since 2026-10-02 (a3aab4c..9405b76). After those, five structural refactors, then fixes from CI.

fix: code-review findings

• Hold-to-ask while a dictation is still finishing. SelectionSpeechRouting now tracks whether the session is busy: the app passes every phase to sessionPhaseChanged, which replaces sessionReachedTerminalPhase. A hold over a selection while the earlier dictation is still transcribing now waits for that dictation to end, then opens the mic. Before, it read that dictation's .pasted as the request failing and reset the gate while the key was still held. Letting go before the mic opened reads the selection and cancels nothing.
• SelectionCopy clobbering the clipboard. If ⌘C was answered after the 100 ms timeout, the selection stayed on the user's clipboard. Now the first clipboard change within a further second is restored, in the background so the press doesn't wait.
• Hold-to-ask is now off by default, like skip-jargon: it sends the selection and the spoken request to the LLM Gateway, so it gets its own opt-in. ⚠️ This changes behaviour for anyone who never touched the toggle.
• Overlay fade race. A fade-out's completion handler now dismisses the panel only if no later setVisible call superseded it. It checks a generation counter instead of the alpha value, so the resize path setting alphaValue = 0 can't let a stale fade hide the silent-mic notice.
• iPhone: a refused press redirected the dictation in flight. A keyboard press now parks its keyboard and field text in a pending slot. The session's frontmost hook claims them, and that hook runs only for a press the session accepts.
• AssemblyAITranscriber reads the enhanced-transcripts setting once per request, so rewrite_mode and the pasted transcript always agree.
• The developer log records rewrite_mode (fast or smart; absent with the rewrite off).
• ListeningWindow's heartbeat no longer holds self strongly across its 5 s sleep.

refactor: cleanups (intended behaviour unchanged, except one item)

• iPhone phase mapping. It was written out in three places; now there is one:
  • VoiceState.Phase is a typealias of PhaseSnapshot.State.
  • The OverlayUIState to state/message mapping lives once in BlurtiOSCore.
  • isSettled is defined once, on the state.
• Key terms. KeyTerms.normalized(_:) is split out of parse and used by the iPhone's keyTerms(). TermPack.termCap is replaced by KeyTerms.termCap.
• Restated constants. The iPhone's staleness limits are derived from SyncSTTLimits.maxAudioSeconds and the notice dwell. Its level meter uses MicCapture.linearLevel, now public.
• Small reuse: trimmedNonEmpty(), Duration ratios instead of attosecond arithmetic, one endTermField(), and one raw-value accessor in SharedStore plus defaultThemeID.
• Wasted work on the iPhone:
  • The capture delegate skips resampling while no utterance is open.
  • The one behaviour change: release and cancel commands no longer copy the field's text across the App Group, since the app only reads it on a press.
• Scripts: ios_require_device and IOS_DEFAULT_DEVICE in ios-lib.sh replace the device-picking code copied into seven scripts.

Structural refactors

• Pasting where Accessibility can't tell. FocusCapture.FocusedEditability adds a third answer, .cannotTell. It covers a system-wide focus query that fails with cannotComplete, and a bare AXWindow with no text signal, which is what editors that draw their own text view report. hasEditableFocusedElement pastes on it, so the Sublime/Zed bundle-ID list goes away. ⚠️ Worth checking on hardware: a native app whose focused element is a bare window with no text field now beeps on ⌘V instead of copying.
• .inputSilent folds into .error(message:notice:), with an optional PillNotice. Its wording is built once in MicCaptureError.
• TextShortcut and TextShortcutExpander move from the AssemblyAI SDK to the engine. They do on-device text processing and put nothing on the wire.
• BlockingIPC.queue and BlockingIPC.run replace DictationSession.contextQueue and offPool, which read-aloud had been reaching into.
• The SDK's rewrite_mode is typed: DictationRewriteMode replaces String?.
• The APIKeyModel merge is now main's. Gate on copy/paste detection (jscpd) and remove every clone it found #248 merged the two copies into one engine type independently, so this branch takes main's version.

How it was tested

Authored in a Linux sandbox with no Swift toolchain, so CI on macOS is the only Swift build and test run.

• scripts/check.sh --portable passes, including the new jscpd gate (0 clones).
• On head 1a5e46a, every CI job passed (compile, the iOS build, both iOS sanitizers, the engine tests) except check. Its two lint failures, unused imports and a redundant public, are fixed in 49be1fb.

New tests:

• Hold-to-ask routing during an earlier dictation.
• A late ⌘C copy restoring the clipboard.
• The hold-to-ask default.
• The once-per-request setting read.
• rewrite_mode in the log and on the wire.
• KeyTerms.normalized.
• UtteranceFeed.isCapturing.
• FocusedEditability.

The overlay generation counter and the iPhone press claim have no unit tests.

• scripts/check.sh passes (or CI will, if I'm not on a Mac)
• I read AGENTS.md and this doesn't reintroduce anything deliberately removed
• Docs updated if behavior changed

🤖 Generated with Claude Code

https://claude.ai/code/session_01X84Vo9pry7SANcbu86Jjrh