fix(macos): retain capture cleanup and diagnose system audio conflicts

Author: Leonardlsa

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- Restore the macOS cancelled-recorder cleanup protections alongside the delayed startup-status UI, so an update built from the current mainline includes both fixes.
+- Distinguish microphone startup failure from a genuinely short recording. On startup timeout, report a possible system-audio capture conflict only when the specifically observed helper is present; this advisory never terminates other applications.
+
 ## [5.0.8] - 2026-09-13
 
 ### Fixed

docs/diagnostics/macos-audio-startup.md

@@ -0,0 +1,29 @@
+# macOS microphone startup: verified failure and recovery boundary
+
+On 2026-09-13 a macOS 26.5 machine running the Apple-signed local 5.0.8 build failed to start recording repeatedly. The input method, Settings app, and recorder all passed code-signature verification and had the audio-input entitlement. The actual input-method microphone request was approved by TCC (authValue=2, authReason=2). A Settings microphone smoke test reported authorization=authorized, success=false, waveform_blocks=0 after the eight-second startup deadline.
+
+The recorder thread was waiting in AudioOutputUnitStart / AudioDeviceStart / HALB_IOThread::StartAndWaitForState. An independent AVAudioRecorder probe reported authorized access and then failed to return from recordForDuration before its ten-second external deadline. No other process was reported as actively recording by the public CoreAudio process-list API at the time checked.
+
+A later HAL StartIO/Running message emitted while the cancelled client was being torn down is not evidence that microphone samples were captured. In this incident the same teardown reported zero frames. Earlier explanations that treated this as proof of ordinary multi-second DSP wake latency were too strong. The current evidence places the stall below the app's permission check, but does not establish which component originally caused it.
+
+The app previously displayed “listening” before receiving audio and called the no-audio case “recording too short”. Cancellation sent SIGTERM and followed it with SIGKILL after 250 ms. The new behavior only shows listening after real PCM, gives an explicit startup-failure message otherwise, and allows cancelled startup to unwind without an early forced kill. The existing recorder startup watchdog is eight seconds; a nine-second parent cleanup deadline remains as a final bound. A new recording cannot overlap a cancelled helper's cleanup.
+
+Tests cover UI timing classification and an artificial recorder that needs 600 ms to finish cancellation cleanup. These are regression tests, not evidence that the system-level recurrence is permanently solved. A main-run-loop pumping experiment did not restore capture in the failing state and was not included in the fix.
+
+Restarting coreaudiod is a recovery operation, not a proven permanent fix. It requires normal user administrator authorization and interrupts audio across applications. Do not reset microphone permissions, replace Apple signatures with ad-hoc signatures, disable platform security, or repeatedly kill unrelated applications as a substitute for diagnosis. Verify recovery through real PCM and the signed Settings microphone smoke test, not only a green permission toggle or device enumeration.
+
+## Recovery verification for this incident
+
+The user-authorized coreaudiod restart succeeded. Before deploying the lifecycle patch, the same installed 5.0.8 recorder completed three one-second tests in 1.375, 1.398 and 1.411 seconds, producing 51,840, 51,840 and 53,760 frames at 48 kHz. The independent AVAudioRecorder probe captured 48,000 frames; the signed Settings smoke captured 73,920 frames across 77 waveform blocks. The successful recovery therefore predates this patch and cannot be credited to the patch. Test WAVs were removed.
+
+The application patch passed all 11 macOS CTest cases and repository native contracts, including the new cancellation-cleanup test. A long-idle recurrence test is still needed before drawing any conclusion about prevention.
+
+## Later recurrence: system-audio capture component comparison
+
+On 2026-09-13 the installed input method was replaced by a mainline build from `fa430e3` (delayed startup-status UI), which did not include the separate `895c86e` cancellation-cleanup patch. This change integrates both code paths, rather than attributing the later failure to a test of the combined version.
+
+During the later failure, an independently signed AVAudioRecorder probe reported authorized access but never returned from recordForDuration before its 10-second process deadline. The system audio daemon PID was 89799. At 02:53, terminating only the running `/Applications/ChatGPT.app/Contents/Resources/native/system-audio-spectrum` helper restored the same native probe: it captured 48,000 frames. The main ChatGPT application, the audio daemon, microphone permissions, and VocoType binaries were not restarted or changed for this comparison. The daemon PID remained 89799.
+
+The existing VocoType recorder then captured 52,800 frames at 48 kHz in each of two one-second tests (1.471 and 1.497 seconds wall time). The existing VocoType recorder then captured 52,800 frames at 48 kHz in each of two one-second tests (1.471 and 1.497 seconds wall time). The existing VocoType recorder then captured 52,800 frames at 48 kHz in each of two one-second tests (1.471 and 1.497 seconds wall time). The existing VocoType recordehis occurrence.
+
+This is evidence for a system-audio capture interaction, not proof that every startup failure has this cause or that the daemon can never fail independently. The helper was not re-enabled for a reverse reproduction. Its presence on timeout is reported only as a possible conflict. The recorder must never terminate another application's processes automatically. The component may reappear when its owning application starts system-audio capture again.

src/desktop/include/vocotype/desktop/audio_startup_diagnostics.hpp

@@ -0,0 +1,16 @@
+#pragma once
+#include <string>
+#include <string_view>
+
+namespace vocotype::desktop {
+// Presence is only a troubleshooting hint, never proof of a causal conflict.
+// Do not terminate another application's processes from the recorder.
+inline bool is_known_system_audio_capture_helper(std::string_view path) {
+  return path.ends_with("/ChatGPT.app/Contents/Resources/native/system-audio-spectrum");
+}
+inline std::string microphone_startup_error(bool helper_detected) {
+  if (helper_detected)
+    return "麦克风启动超过 8 秒；检测到 ChatGPT 音频采集组件可能冲突，请关闭该应用的系统音频采集或退出该应用后重试";
+  return "麦克风启动超过 8 秒，未收到音频；请检查输入设备及其他音频应用后重试";
+}
+} // namespace vocotype::desktop

src/desktop/src/audio.cpp

@@ -657,6 +657,13 @@ void AudioCapture::run(std::atomic_bool &stop, const BlockCallback &callback) {
         "cannot open microphone");
   stream_ = stream;
   try {
+    // A key release may have arrived while device setup was in progress.
+    // Do not start new microphone I/O after cancellation.
+    if (stop.load(std::memory_order_acquire)) {
+      check(Pa_CloseStream(stream), "cannot close cancelled microphone");
+      stream_ = nullptr;
+      return;
+    }
     check(Pa_StartStream(stream), "cannot start microphone");
     std::vector<std::int16_t> interleaved(
         static_cast<std::size_t>(frames) *

src/desktop/src/audio_recorder_main.cpp

@@ -1,3 +1,7 @@
+#include "vocotype/desktop/audio_startup_diagnostics.hpp"
+#ifdef __APPLE__
+#include <libproc.h>
+#endif
 #include "vocotype/desktop/audio.hpp"
 #include "vocotype/desktop/config.hpp"
 #include "vocotype/desktop/ipc.hpp"
@@ -69,6 +73,32 @@ Options parse(int argc, char **argv) {
   return options;
 }
 } // namespace
+#ifdef __APPLE__
+namespace {
+bool known_system_audio_capture_helper_present() noexcept {
+  try {
+    constexpr int kMaxProcessBytes = 1024 * 1024;
+    const int bytes = proc_listpids(PROC_ALL_PIDS, 0, nullptr, 0);
+    if (bytes <= 0 || bytes > kMaxProcessBytes) return false;
+    std::vector<pid_t> pids(static_cast<std::size_t>(bytes) / sizeof(pid_t) + 64);
+    const int received = proc_listpids(PROC_ALL_PIDS, 0, pids.data(),
+                                     static_cast<int>(pids.size() * sizeof(pid_t)));
+    if (received <= 0) return false;
+    const auto count = std::min(pids.size(), static_cast<std::size_t>(received) / sizeof(pid_t));
+    for (std::size_t index = 0; index < count; ++index) {
+      if (pids[index] <= 0) continue;
+      char path[PROC_PIDPATHINFO_MAXSIZE]{};
+      if (proc_pidpath(pids[index], path, sizeof(path)) > 0 &&
+          vocotype::desktop::is_known_system_audio_capture_helper(path)) return true;
+    }
+  } catch (...) {
+    // Diagnostics must never prevent the bounded recorder exit.
+  }
+  return false;
+}
+} // namespace
+#endif
+
 int main(int argc, char **argv) {
   try {
     const Options options = parse(argc, argv);
@@ -292,16 +322,18 @@ int main(int argc, char **argv) {
     // not sufficient here: a timed recording may request stop while the
     // capture thread is still blocked inside AudioDeviceStart.
     std::thread([&first_audio_block, &capture_finished] {
-      // A built-in microphone that has been idle for a long time can take just
-      // over five seconds to leave its deep CoreAudio power state on macOS 26.
-      // Keep enough margin to avoid killing the recorder exactly as the HAL
-      // reports the device Running, while still bounding genuine startup hangs.
+      // Bound a missing first PCM block. A later HAL "Running" log during
+      // process cancellation is not evidence that audio capture succeeded,
+      // nor proof of normal device wake-up latency.
       constexpr auto kMicrophoneStartupTimeout = std::chrono::seconds(8);
       std::this_thread::sleep_for(kMicrophoneStartupTimeout);
       if (!first_audio_block.load(std::memory_order_acquire) &&
           !capture_finished.load(std::memory_order_acquire)) {
+        const bool helper_detected = known_system_audio_capture_helper_present();
         emit({{"type", "error"},
-              {"error", "麦克风启动超过 8 秒（CoreAudio 未返回音频）；请重试，必要时重启系统音频服务"}});
+              {"error_code", "microphone_start_timeout"},
+              {"system_audio_capture_hint", helper_detected},
+              {"error", vocotype::desktop::microphone_startup_error(helper_detected)}});
         std::_Exit(2);
       }
     }).detach();

src/desktop/src/recorder_process.cpp

@@ -54,6 +54,18 @@ void RecorderProcess::start(const std::string &executable,
                             EventCallback callback) {
   if (running())
     throw std::runtime_error("recorder is already running");
+#ifdef __APPLE__
+  // Do not overlap another HAL start with a cancelled operation still unwinding.
+  // This gate never records while idle and clears when the old child is reaped.
+  static std::mutex launch_mutex;
+  static std::weak_ptr<State> previous_capture;
+  std::lock_guard launch_lock(launch_mutex);
+  if (const auto previous = previous_capture.lock()) {
+    std::lock_guard previous_lock(previous->mutex);
+    if (previous->cancel_requested && !previous->finished)
+      throw std::runtime_error("麦克风仍在清理上一段录音，请稍后重试");
+  }
+#endif
 
   int input_pipe[2]{};
   int output_pipe[2]{};
@@ -91,6 +103,9 @@ void RecorderProcess::start(const std::string &executable,
   state->stdin_fd = input_pipe[1];
   state->stdout_fd = output_pipe[0];
   state_ = state;
+#ifdef __APPLE__
+  previous_capture = state;
+#endif
 
   std::thread([state, callback = std::move(callback)] {
     int output_fd = -1;
@@ -201,9 +216,19 @@ void RecorderProcess::cancel_async() {
     std::remove(audio_path.c_str());
   if (child_pid > 0) {
     std::thread([state, child_pid] {
-      std::this_thread::sleep_for(std::chrono::milliseconds(250));
-      std::lock_guard lock(state->mutex);
-      if (!state->finished && state->pid == child_pid)
+      // Return to the UI immediately, but let a cancelled CoreAudio start
+      // finish its own shutdown. Killing it after 250 ms cuts through HAL
+      // initialization. The recorder's 8-second startup watchdog remains the
+      // primary bound; this is a final fallback, not extra recording time.
+#ifdef __APPLE__
+      constexpr auto grace = std::chrono::seconds(9);
+#else
+      constexpr auto grace = std::chrono::milliseconds(250);
+#endif
+      std::unique_lock lock(state->mutex);
+      if (!state->changed.wait_for(lock, grace, [&] {
+            return state->finished || state->pid != child_pid;
+          }))
         kill(child_pid, SIGKILL);
     }).detach();
   }

src/desktop/tests/audio_startup_diagnostics_tests.cpp

@@ -0,0 +1,18 @@
+#include "vocotype/desktop/audio_startup_diagnostics.hpp"
+#include <iostream>
+#include <stdexcept>
+using namespace vocotype::desktop;
+int main() {
+  try {
+    if (!is_known_system_audio_capture_helper("/Applications/ChatGPT.app/Contents/Resources/native/system-audio-spectrum"))
+      throw std::runtime_error("known helper not recognized");
+    for (const auto path : {"", "/tmp/system-audio-spectrum", "/Applications/Other.app/Contents/Resources/native/system-audio-spectrum", "/Applications/ChatGPT.app/Contents/Resources/native/system-audio-spectrum-other"})
+      if (is_known_system_audio_capture_helper(path)) throw std::runtime_error("unrelated process matched");
+    if (microphone_startup_error(true).find("可能冲突") == std::string::npos)
+      throw std::runtime_error("presence incorrectly described as proof");
+    if (microphone_startup_error(false).find("ChatGPT") != std::string::npos)
+      throw std::runtime_error("specific component blamed without detection");
+    std::cout << "PASS specific, advisory-only audio startup diagnostics\n";
+    return 0;
+  } catch (const std::exception& e) { std::cerr << e.what() << '\n'; return 1; }
+}

src/desktop/tests/fake_startup_cleanup_recorder.cpp

@@ -0,0 +1,19 @@
+#include <csignal>
+#include <cstdlib>
+#include <chrono>
+#include <fstream>
+#include <iostream>
+#include <thread>
+namespace { volatile std::sig_atomic_t cancelled = 0; void stop(int) { cancelled = 1; } }
+int main() {
+  std::signal(SIGTERM, stop);
+  std::cout << "{\"type\":\"test_ready\"}\n" << std::flush;
+  while (!cancelled) std::this_thread::sleep_for(std::chrono::milliseconds(5));
+  // Model a driver unwinding an already in-flight startup. No microphone is
+  // opened by this test helper. 250-ms SIGKILL must not interrupt cleanup.
+  std::this_thread::sleep_for(std::chrono::milliseconds(600));
+  const char *path = std::getenv("VOCOTYPE_TEST_CLEANUP_MARKER");
+  if (!path) return 2;
+  std::ofstream marker(path); marker << "cleaned\n";
+  return marker ? 0 : 3;
+}

src/desktop/tests/recorder_cancel_cleanup_tests.cpp

@@ -0,0 +1,48 @@
+#include "vocotype/desktop/recorder_process.hpp"
+#include <atomic>
+#include <chrono>
+#include <cstdlib>
+#include <filesystem>
+#include <fstream>
+#include <iostream>
+#include <stdexcept>
+#include <thread>
+#include <unistd.h>
+int main(int argc, char **argv) {
+  using namespace std::chrono_literals;
+  if (argc != 2) return 2;
+  char pattern[] = "/tmp/vocotype-cancel-cleanup-XXXXXX";
+  const int fd = mkstemp(pattern);
+  if (fd < 0) return 3;
+  close(fd);
+  struct Cleanup { const char *path; ~Cleanup() { std::remove(path); unsetenv("VOCOTYPE_TEST_CLEANUP_MARKER"); } } cleanup{pattern};
+  setenv("VOCOTYPE_TEST_CLEANUP_MARKER", pattern, 1);
+  try {
+    std::atomic_bool ready{false};
+    vocotype::desktop::RecorderProcess recorder;
+    recorder.start(argv[1], [&](const std::string &type, const std::string &) {
+      if (type == "test_ready") ready.store(true);
+    });
+    const auto deadline = std::chrono::steady_clock::now() + 2s;
+    while (!ready.load() && std::chrono::steady_clock::now() < deadline)
+      std::this_thread::sleep_for(5ms);
+    if (!ready.load()) throw std::runtime_error("fake recorder never became ready");
+    const auto started = std::chrono::steady_clock::now();
+    recorder.cancel_async();
+    if (std::chrono::steady_clock::now() - started > 200ms)
+      throw std::runtime_error("cancel blocked the UI");
+    vocotype::desktop::RecorderProcess overlapping;
+    bool overlap_blocked = false;
+    try { overlapping.start(argv[1], {}); }
+    catch (const std::exception &) { overlap_blocked = true; }
+    if (!overlap_blocked) throw std::runtime_error("new HAL start overlapped cancelled cleanup");
+    while (recorder.running() && std::chrono::steady_clock::now() - started < 2s)
+      std::this_thread::sleep_for(10ms);
+    if (recorder.running()) throw std::runtime_error("cancelled recorder was not reaped");
+    std::ifstream marker(pattern); std::string text; std::getline(marker, text);
+    if (text != "cleaned") throw std::runtime_error("startup cleanup was interrupted by early SIGKILL");
+    std::cout << "PASS cancellation returns immediately and allows startup cleanup\n";
+  } catch (const std::exception &e) {
+    std::cerr << "FAIL " << e.what() << '\n'; return 1;
+  }
+}

src/integrations/macos/CMakeLists.txt

@@ -272,3 +272,24 @@ set_target_properties(VocoTypeSettings PROPERTIES
   MACOSX_BUNDLE_INFO_PLIST ${CMAKE_CURRENT_BINARY_DIR}/SettingsInfo.plist
   XCODE_ATTRIBUTE_CODE_SIGNING_ALLOWED NO
 )
+
+if(BUILD_TESTING)
+  add_executable(vocotype-fake-startup-cleanup-recorder
+    ../../desktop/tests/fake_startup_cleanup_recorder.cpp)
+  target_compile_features(vocotype-fake-startup-cleanup-recorder PRIVATE cxx_std_20)
+  add_executable(vocotype-recorder-cancel-cleanup-tests
+    ../../desktop/tests/recorder_cancel_cleanup_tests.cpp)
+  target_link_libraries(vocotype-recorder-cancel-cleanup-tests PRIVATE vocotype_macos_base)
+  add_test(NAME vocotype-macos-recorder-cancel-cleanup
+    COMMAND vocotype-recorder-cancel-cleanup-tests
+      $<TARGET_FILE:vocotype-fake-startup-cleanup-recorder>)
+  set_tests_properties(vocotype-macos-recorder-cancel-cleanup PROPERTIES TIMEOUT 15)
+endif()
+
+if(BUILD_TESTING)
+  add_executable(vocotype-audio-startup-diagnostics-tests
+    ../../desktop/tests/audio_startup_diagnostics_tests.cpp)
+  target_include_directories(vocotype-audio-startup-diagnostics-tests PRIVATE ../../desktop/include)
+  target_compile_features(vocotype-audio-startup-diagnostics-tests PRIVATE cxx_std_20)
+  add_test(NAME vocotype-macos-audio-startup-diagnostics COMMAND vocotype-audio-startup-diagnostics-tests)
+endif()