fix(windows): eliminate three kernel-wedge deadlock vectors

A prior clx-rust.exe instance (PID 7580) ran for 3 days and could not be
killed by taskkill or elevated Stop-Process, requiring a reboot. Analysis
of the Windows adapter found three places where a user-space lock or a
slow Win32/Tauri call could stall a thread inside an unabortable kernel
wait and leave the process unkillable.

1. core/audio_capture.rs: replace Arc<Mutex<Vec<f32>>> with a lock-free
   SPSC HeapRb ring. The cpal input callback thread no longer blocks on
   a user-space Mutex, so a consumer holding the lock across slow I/O
   can't stall the audio thread into an unjoinable state when the stream
   is later paused or dropped.

2. adapters/windows/src/hook.rs: spawn a dedicated clx-tray-worker thread
   owning all update_tray_icon / cursor_visibility::enable|disable calls,
   fed by an mpsc::Sender<bool>. The WH_KEYBOARD_LL callback now only
   does a non-blocking tx.send on mode edges - no Tauri calls, no
   SystemParametersInfoW, no GUI locks touched from the hook. Also moves
   cursor_visibility::nudge out of the hook callback into tick_timer_proc
   (16 ms SetTimer) so the hook stays well under the ~300 ms budget.

3. adapters/windows/src/main.rs: the quit-watch thread now polls
   WaitForSingleObject with a 500 ms timeout and checks a SHUTDOWN
   AtomicBool set at end of main, instead of blocking INFINITE. This
   lets the thread exit cleanly during normal shutdown rather than
   sitting in a kernel wait forever.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: snomiao

rs/Cargo.lock

@@ -1,6 +1,7 @@
 /// Windows WH_KEYBOARD_LL hook – bridges Win32 key events to ClxEngine.
 use std::sync::{Arc, OnceLock};
 use std::sync::atomic::{AtomicU32, AtomicUsize, Ordering};
+use std::sync::mpsc;
 
 use windows::Win32::Foundation::{HWND, LPARAM, LRESULT, WPARAM};
 use windows::Win32::System::LibraryLoader::GetModuleHandleW;
@@ -30,6 +31,39 @@ static SHM: OnceLock<SharedState> = OnceLock::new();
 /// Last tray-active state for edge detection (0 = off, 1 = on, u32::MAX = uninitialised).
 static LAST_TRAY_ACTIVE: AtomicU32 = AtomicU32::new(u32::MAX);
 
+/// Channel sender to the tray/cursor worker thread. `None` until `init_tray_worker`
+/// is called. The hook callback must NEVER call Tauri or SystemParametersInfoW
+/// directly — those can block on GUI locks held by threads waiting on the hook,
+/// creating a 3-way deadlock that leaves the process unkillable.
+static TRAY_TX: OnceLock<mpsc::Sender<bool>> = OnceLock::new();
+
+/// Spawn the tray/cursor-visibility worker thread. Must be called once before
+/// `install_hook()`. The worker coalesces bursts of edge events so a rapid
+/// on/off/on flicker only triggers the most recent state.
+pub fn init_tray_worker() {
+    let (tx, rx) = mpsc::channel::<bool>();
+    if TRAY_TX.set(tx).is_err() {
+        return;
+    }
+    let _ = std::thread::Builder::new()
+        .name("clx-tray-worker".into())
+        .spawn(move || {
+            while let Ok(first) = rx.recv() {
+                // Coalesce any backlog so we only apply the latest state.
+                let mut latest = first;
+                while let Ok(next) = rx.try_recv() {
+                    latest = next;
+                }
+                crate::update_tray_icon(latest);
+                if latest {
+                    crate::cursor_visibility::enable();
+                } else {
+                    crate::cursor_visibility::disable();
+                }
+            }
+        });
+}
+
 /// Store the shared memory handle so the hook callback can publish mode changes.
 pub fn init_shared_state(shm: SharedState) {
     let _ = SHM.set(shm);
@@ -86,11 +120,18 @@ pub fn install_hook() {
     }
 }
 
-/// Timer callback — drives AccModel physics on the main/hook thread.
+/// Timer callback — drives AccModel physics on the main/hook thread, and
+/// periodically nudges cursor visibility while CLX mode is held. Nudging used
+/// to happen inside the hook callback; moving it here keeps the hook callback
+/// fast and keeps us well under the WH_KEYBOARD_LL ~300 ms budget.
 unsafe extern "system" fn tick_timer_proc(_hwnd: HWND, _msg: u32, _id: usize, _time: u32) {
     if let Some(engine) = ENGINE.get() {
         engine.tick();
     }
+    let active = LAST_TRAY_ACTIVE.load(Ordering::Relaxed);
+    if active != 0 && active != u32::MAX {
+        crate::cursor_visibility::nudge();
+    }
 }
 
 pub fn uninstall_hook() {
@@ -144,19 +185,16 @@ unsafe extern "system" fn keyboard_proc(
         shm.write_mode(mode);
     }
 
-    // Update tray icon on mode edge transitions.
+    // Dispatch mode-edge transitions to the tray worker. The hook callback
+    // must never call Tauri or SystemParametersInfoW directly — sending on an
+    // mpsc channel is wait-free (one atomic CAS + a malloc) and safe here.
+    // Cursor-visibility nudges are handled by the SetTimer tick instead.
     let active = u32::from(mode != 0);
     let prev = LAST_TRAY_ACTIVE.swap(active, Ordering::Relaxed);
     if prev != active {
-        crate::update_tray_icon(active != 0);
-        if active != 0 {
-            crate::cursor_visibility::enable();
-        } else {
-            crate::cursor_visibility::disable();
+        if let Some(tx) = TRAY_TX.get() {
+            let _ = tx.send(active != 0);
         }
-    } else if active != 0 {
-        // Periodic nudge while CLX mode held — defeats touch cursor suppression.
-        crate::cursor_visibility::nudge();
     }
 
     match resp {

rs/adapters/windows/src/hook.rs

@@ -16,6 +16,7 @@ mod vk;
 
 use std::path::Path;
 use std::process::{Child, Command};
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::OnceLock;
 
 use windows::Win32::Foundation::HANDLE;
@@ -35,6 +36,11 @@ static ICON_ON:  &[u8] = include_bytes!("../../../../Data/XIconBlue.ico");
 
 static APP_HANDLE: OnceLock<AppHandle> = OnceLock::new();
 
+/// Set when main() is about to return so background helper threads
+/// (e.g. the quit-watch thread) can exit their poll loops cleanly instead
+/// of blocking forever on kernel waits.
+static SHUTDOWN: AtomicBool = AtomicBool::new(false);
+
 const TRAY_ID: &str = "main";
 
 /// Switch tray icon between on (blue) and off (white).
@@ -142,6 +148,13 @@ fn main() {
     if let Some(ev) = ahk_ready_event {
         unsafe { let _ = windows::Win32::Foundation::CloseHandle(ev); }
     }
+    // Spawn the tray/cursor worker BEFORE install_hook so the first hook
+    // callback already has a channel to send edge events into. The worker
+    // absorbs all Tauri and SystemParametersInfoW work that used to run
+    // inside the WH_KEYBOARD_LL callback — keeping the hook callback fast
+    // and avoiding deadlocks that could leave the process unkillable.
+    hook::init_tray_worker();
+
     // Install hook on the main thread BEFORE Tauri init.
     // Tauri's setup takes ~15s, during which the hook would be starved of
     // message pumping.  We install here and run a brief PeekMessage pump
@@ -160,19 +173,34 @@ fn main() {
             let _ = APP_HANDLE.set(app.handle().clone());
 
             // Watch the quit event so a new instance can ask us to exit cleanly.
+            // Uses a 500 ms polling wait instead of INFINITE so the thread
+            // observes the SHUTDOWN flag during normal shutdown and exits
+            // cleanly, rather than sitting in a kernel wait forever.
             if let Some(evt) = shm::SharedState::create_quit_event() {
                 let app_handle = app.handle().clone();
                 let raw = evt.0 as usize; // extract raw ptr for Send
-                std::thread::spawn(move || {
-                    use windows::Win32::Foundation::{CloseHandle, HANDLE};
-                    use windows::Win32::System::Threading::WaitForSingleObject;
-                    unsafe {
-                        let h = HANDLE(raw as *mut _);
-                        WaitForSingleObject(h, u32::MAX); // INFINITE
-                        let _ = CloseHandle(h);
-                    }
-                    app_handle.exit(0);
-                });
+                let _ = std::thread::Builder::new()
+                    .name("clx-quit-watch".into())
+                    .spawn(move || {
+                        use windows::Win32::Foundation::{CloseHandle, HANDLE, WAIT_OBJECT_0};
+                        use windows::Win32::System::Threading::WaitForSingleObject;
+                        unsafe {
+                            let h = HANDLE(raw as *mut _);
+                            loop {
+                                let r = WaitForSingleObject(h, 500);
+                                if r == WAIT_OBJECT_0 {
+                                    let _ = CloseHandle(h);
+                                    app_handle.exit(0);
+                                    return;
+                                }
+                                if SHUTDOWN.load(Ordering::Relaxed) {
+                                    let _ = CloseHandle(h);
+                                    return;
+                                }
+                                // WAIT_TIMEOUT or WAIT_FAILED — retry.
+                            }
+                        }
+                    });
             }
 
             let prefs_item  = MenuItemBuilder::with_id("prefs",      "Preferences…").build(app)?;
@@ -239,6 +267,9 @@ fn main() {
             }
         });
 
+    // Signal helper threads to wind down before we tear down Win32 state.
+    SHUTDOWN.store(true, Ordering::Relaxed);
+
     hook::uninstall_hook();
     cursor_visibility::disable();
 

rs/adapters/windows/src/main.rs

@@ -13,6 +13,7 @@ path = "src/lib.rs"
 once_cell    = "1.19"
 parking_lot  = "0.12"
 cpal         = "0.15"
+ringbuf      = "0.4"
 dirs         = "5"
 whisper-rs   = { version = "0.13", optional = true }
 sherpa-rs    = { version = "0.6", optional = true }

rs/core/Cargo.toml

@@ -2,6 +2,13 @@
 //!
 //! Captures microphone audio as mono f32 samples, targeting 16 kHz for Whisper.
 //! Falls back to the device's default config if 16 kHz is unavailable.
+//!
+//! Uses a lock-free SPSC ring buffer between the cpal callback thread and
+//! consumers. The audio callback must never block on a user-space lock — if a
+//! consumer holds one across slow I/O while the callback is also trying to take
+//! it, the callback thread stalls and a subsequent `stream.pause()/drop()` can
+//! wedge waiting to join the callback thread. A lock-free ring avoids that
+//! entire failure mode.
 
 use std::sync::{
     atomic::{AtomicBool, Ordering},
@@ -10,10 +17,11 @@ use std::sync::{
 
 use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
 use cpal::{SampleFormat, Stream, StreamConfig};
+use ringbuf::{traits::*, HeapCons, HeapRb};
 
 pub struct AudioCapture {
     recording: Arc<AtomicBool>,
-    buffer: Arc<Mutex<Vec<f32>>>,
+    cons: Arc<Mutex<HeapCons<f32>>>,
     sample_rate: u32,
     stream: Option<Stream>,
 }
@@ -64,11 +72,17 @@ impl AudioCapture {
         };
 
         let recording = Arc::new(AtomicBool::new(false));
-        let buffer: Arc<Mutex<Vec<f32>>> = Arc::new(Mutex::new(Vec::new()));
+
+        // Ring buffer sized for ~10 s of mono audio at the target rate. Consumers
+        // typically drain every 50–200 ms, so this is generous head-room.
+        let rb_capacity = (sample_rate as usize).saturating_mul(10).max(16000);
+        let rb: HeapRb<f32> = HeapRb::new(rb_capacity);
+        let (mut prod, cons) = rb.split();
+        let cons = Arc::new(Mutex::new(cons));
 
         let rec_flag = Arc::clone(&recording);
-        let buf_handle = Arc::clone(&buffer);
         let channels = config.channels as usize;
+        let mut downmix: Vec<f32> = Vec::with_capacity(4096);
 
         let stream = device
             .build_input_stream(
@@ -77,15 +91,18 @@ impl AudioCapture {
                     if !rec_flag.load(Ordering::Relaxed) {
                         return;
                     }
-                    let mut buf = buf_handle.lock().unwrap();
                     if channels == 1 {
-                        buf.extend_from_slice(data);
+                        let _ = prod.push_slice(data);
                     } else {
-                        // Down-mix to mono by averaging channels.
+                        // Down-mix to mono by averaging channels. Reuse the
+                        // scratch buffer to avoid per-callback allocation.
+                        downmix.clear();
+                        downmix.reserve(data.len() / channels);
                         for chunk in data.chunks(channels) {
                             let sum: f32 = chunk.iter().sum();
-                            buf.push(sum / channels as f32);
+                            downmix.push(sum / channels as f32);
                         }
+                        let _ = prod.push_slice(&downmix);
                     }
                 },
                 move |err| {
@@ -95,12 +112,9 @@ impl AudioCapture {
             )
             .map_err(|e| format!("Failed to build input stream: {e}"))?;
 
-        // eprintln!("[CLX] audio capture: device ready, {}Hz {}ch",
-        //     sample_rate, config.channels);
-
         Ok(Self {
             recording,
-            buffer,
+            cons,
             sample_rate,
             stream: Some(stream),
         })
@@ -113,7 +127,6 @@ impl AudioCapture {
                 .play()
                 .map_err(|e| format!("Failed to start audio stream: {e}"))?;
             self.recording.store(true, Ordering::Relaxed);
-            // eprintln!("[CLX] audio capture: started");
             Ok(())
         } else {
             Err("No audio stream available".to_string())
@@ -126,13 +139,19 @@ impl AudioCapture {
         if let Some(ref stream) = self.stream {
             let _ = stream.pause();
         }
-        // eprintln!("[CLX] audio capture: stopped");
     }
 
     /// Drain and return all buffered samples collected so far.
     pub fn take_samples(&self) -> Vec<f32> {
-        let mut buf = self.buffer.lock().unwrap();
-        std::mem::take(&mut *buf)
+        let mut cons = self.cons.lock().unwrap();
+        let n = cons.occupied_len();
+        if n == 0 {
+            return Vec::new();
+        }
+        let mut out = vec![0.0f32; n];
+        let got = cons.pop_slice(&mut out);
+        out.truncate(got);
+        out
     }
 
     /// Whether the capture is currently recording.