[fix] a lingering Parley answers the keyboard's mic tap again instead of sending every dictation through the app

[YJack0000]

Why

The owner reports that a few versions ago, once the microphone permission was granted and Parley had been opened once, the keyboard stopped jumping to Parley, and that now every dictation jumps to Parley once.

The jump is the keyboard's 700 ms fallback: startDictation publishes the request over the App Group and opens parley://dictate only when the app does not acknowledge. #348 (a220edc, shipped in iOS 1.10) added a second guard to DictationCoordinator.armRequestObserver that makes a backgrounded process with no running capture refuse the note outright, on the premise that iOS never lets a backgrounded process start recording. With the microphone window off, which is the default, that is the state every lingering Parley is in after a dictation, so every tap since 1.10 has taken the round trip. The premise came from one phone's log. On the owner's phone the same activation succeeds, which is why #222 and #281 shipped the linger as a working no-jump path and why the report reads as a regression.

The observer now asks the audio session instead of assuming either answer. A lingering process with nothing to borrow opens a microphone before it acknowledges the start and answers only if iOS let it. A refused activation stays silent, so the keyboard opens Parley exactly as it does today, and the error loop #348 fixed ("Couldn't open the microphone" on every tap for the length of the linger) cannot come back.

Scope

• DictationCoordinator.armRequestObserver tries openMicrophoneInBackground() instead of declining when canServeInPlace is false.
• DictationCoordinator.canServeInPlace is the one predicate behind both the guard and the servesInPlace heartbeat. The heartbeat still reports the pessimistic answer, so the record button promises a jump that may then not happen rather than the reverse.
• docs/design/ios-voice-keyboard.md, the AppPresence doc and the KeyboardBridge.opensApp doc stop stating the premise as a rule.
• Out of scope: the microphone window path, which reads intact; HostReturnPolicy, which is the jump back after a dictation, not the jump to start one.

Tradeoffs

Reverting #348's guard alone would bring back its error loop on phones where the background activation is refused. Publishing the starting ack only after the microphone opens would have cost every no-jump start the activation time inside the 700 ms window. Trying before acknowledging keeps the ack fast where the microphone was already open and pays the activation only on the path that used to be refused outright.

Blast Radius

Only the Darwin start path from a backgrounded app with no running capture changes. Foreground starts, starts that borrow an open window, and the URL path are untouched. Where iOS refuses the activation the user sees today's behaviour, a jump after 700 ms plus one refused setActive. Where it succeeds the dictation stays in the host app, which is what the linger was built for. One new race: the starting ack now lands after AudioCapture.start() instead of milliseconds after the note, and the keyboard waits 700 ms, so a background activation slower than that makes the keyboard open parley://dictate over a microphone already running and begin(session:) stops and relaunches the session in the foreground. That degrades to today's jump plus a restart, not to a lost dictation.

Verification

• xcodebuild -scheme ParleyKit -destination 'platform=macOS' test: 421 tests, 1 skipped, 0 failures. swift test itself cannot run on this Mac (the Command Line Tools' SwiftPM fails to link the manifest, and xcrun under DEVELOPER_DIR=/Applications/Xcode.app/... aborts on an arm64-only libxcrun.dylib), so xcodebuild drives the same package.
• xcodebuild -target Parley -sdk iphoneos build CODE_SIGNING_ALLOWED=NO with the asset catalog excluded: app, keyboard and activities compile. The simulator SDK build and the catalog step both stop at actool, which needs a simulator runtime, and none is installed.
• Not verified on a phone or simulator. Whether a given iOS build lets a backgrounded, recently foregrounded app with UIBackgroundModes: audio start recording is the fact this fix stops guessing at; the simulator does not enforce it, this Mac has no simulator runtime, and there is no signed-in account to dictate with. The background start() latency is unmeasured here; the app now logs it (subsystem com.pathors.parley, category Dictation, "background mic start took N ms" or "refused after N ms") so the owner's phone can report it through Console. No ParleyKit test was added: the ack decision lives in the app target's coordinator and in AVAudioSession, not in package logic.

🤖 Generated with Claude Code

[github-actions]

✅ SonarQube Quality Gate passed — pathorsAI_parley

0 open issues on this PR.