fix: harden runtime hang guards

README.md

@@ -115,6 +115,26 @@ whispers completions zsh
 - `whispers` installs the helper rewrite worker for you when that feature is enabled.
 - Shell completions are printed to `stdout`.
 
+## Troubleshooting
+
+If the main `whispers` process ever gets stuck after playback when using local
+`whisper_cpp`, enable the built-in hang diagnostics for the next repro:
+
+```sh
+WHISPERS_HANG_DEBUG=1 whispers
+```
+
+When that mode is enabled, `whispers` writes runtime status and hang bundles
+under `${XDG_RUNTIME_DIR:-/tmp}/whispers/`:
+
+- `main-status.json` shows the current dictation stage and recent stage metadata.
+- `hang-<pid>-<stage>-<timestamp>.log` is emitted if `whisper_cpp` spends too
+  long in model load or transcription.
+
+Those bundles include the current status snapshot plus best-effort stack and
+open-file diagnostics. If the hang reproduces, capture the newest `hang-*.log`
+file along with `main-status.json`.
+
 ## License
 
 [Mozilla Public License 2.0](LICENSE)

src/agentic_rewrite/mod.rs

@@ -46,6 +46,12 @@ struct PreparedGlossaryEntry {
     normalized_aliases: Vec<Vec<String>>,
 }
 
+#[derive(Debug, Clone, Default)]
+pub(crate) struct RuntimePolicyResources {
+    policy_rules: Vec<AppRule>,
+    glossary_entries: Vec<GlossaryEntry>,
+}
+
 pub use runtime::conservative_output_allowed;
 
 pub fn default_policy_path() -> &'static str {
@@ -56,17 +62,43 @@ pub fn default_glossary_path() -> &'static str {
     store::default_glossary_path()
 }
 
+pub(crate) fn load_runtime_resources(config: &Config) -> RuntimePolicyResources {
+    load_runtime_resources_with_status(config).0
+}
+
+pub(crate) fn load_runtime_resources_with_status(
+    config: &Config,
+) -> (RuntimePolicyResources, bool) {
+    let (policy_rules, policy_degraded) =
+        store::load_policy_file_for_runtime_with_status(&config.resolved_rewrite_policy_path());
+    let (glossary_entries, glossary_degraded) =
+        store::load_glossary_file_for_runtime_with_status(&config.resolved_rewrite_glossary_path());
+
+    (
+        RuntimePolicyResources {
+            policy_rules,
+            glossary_entries,
+        },
+        policy_degraded || glossary_degraded,
+    )
+}
+
 pub fn apply_runtime_policy(config: &Config, transcript: &mut RewriteTranscript) {
-    let policy_rules = store::load_policy_file_for_runtime(&config.resolved_rewrite_policy_path());
-    let glossary_entries =
-        store::load_glossary_file_for_runtime(&config.resolved_rewrite_glossary_path());
+    let resources = load_runtime_resources(config);
+    apply_runtime_policy_with_resources(config, transcript, &resources);
+}
 
+pub(crate) fn apply_runtime_policy_with_resources(
+    config: &Config,
+    transcript: &mut RewriteTranscript,
+    resources: &RuntimePolicyResources,
+) {
     let policy_context = runtime::resolve_policy_context(
         config.rewrite.default_correction_policy,
         transcript.typing_context.as_ref(),
         &transcript.rewrite_candidates,
-        &policy_rules,
-        &glossary_entries,
+        &resources.policy_rules,
+        &resources.glossary_entries,
     );
 
     for candidate in &policy_context.glossary_candidates {

src/agentic_rewrite/runtime.rs

@@ -305,7 +305,7 @@ fn built_in_rules(default_policy: RewriteCorrectionPolicy) -> Vec<AppRule> {
                 surface_kind: Some(RewriteSurfaceKind::Browser),
                 ..ContextMatcher::default()
             },
-            "Favor clean prose and natural punctuation for browser text fields, but stay grounded in the listed candidates, glossary evidence, and the utterance's technical topic when it clearly refers to software or documentation.",
+            "Favor clean prose and natural punctuation for browser text fields, except when the utterance is structured text such as a hostname, URL, email address, or similar punctuation-sensitive literal. In those cases preserve punctuation literally and do not rewrite it into prose. Stay grounded in the listed candidates, glossary evidence, and the utterance's technical topic when it clearly refers to software or documentation.",
             Some(RewriteCorrectionPolicy::Balanced),
         ),
         AppRule::built_in(
@@ -314,7 +314,7 @@ fn built_in_rules(default_policy: RewriteCorrectionPolicy) -> Vec<AppRule> {
                 surface_kind: Some(RewriteSurfaceKind::GenericText),
                 ..ContextMatcher::default()
             },
-            "Favor clean prose and natural punctuation for general text entry while staying grounded in the listed candidates and glossary evidence. If the utterance clearly discusses technical tools or software, prefer the most plausible technical term over a phonetically similar common word.",
+            "Favor clean prose and natural punctuation for general text entry, except when the utterance is structured text such as a hostname, URL, email address, or similar punctuation-sensitive literal. In those cases preserve punctuation literally and do not rewrite it into prose. Stay grounded in the listed candidates and glossary evidence. If the utterance clearly discusses technical tools or software, prefer the most plausible technical term over a phonetically similar common word.",
             Some(RewriteCorrectionPolicy::Balanced),
         ),
         AppRule::built_in(

src/agentic_rewrite/store.rs

@@ -4,6 +4,7 @@ use serde::{Deserialize, Serialize};
 
 use crate::config::Config;
 use crate::error::{Result, WhsprError};
+use crate::safe_fs;
 
 use super::{AppRule, GlossaryEntry};
 
@@ -101,7 +102,7 @@ fn ensure_text_file(path: &Path, contents: &str) -> Result<bool> {
     }
 
     write_parent(path)?;
-    std::fs::write(path, contents).map_err(|e| {
+    safe_fs::write(path, contents).map_err(|e| {
         WhsprError::Config(format!(
             "failed to write starter file {}: {e}",
             path.display()
@@ -115,7 +116,7 @@ pub(super) fn read_policy_file(path: &Path) -> Result<Vec<AppRule>> {
         return Ok(Vec::new());
     }
 
-    let contents = std::fs::read_to_string(path).map_err(|e| {
+    let contents = safe_fs::read_to_string(path).map_err(|e| {
         WhsprError::Config(format!("failed to read app rules {}: {e}", path.display()))
     })?;
     if contents.trim().is_empty() {
@@ -133,7 +134,7 @@ pub(super) fn write_policy_file(path: &Path, rules: &[AppRule]) -> Result<()> {
         rules: rules.to_vec(),
     })
     .map_err(|e| WhsprError::Config(format!("failed to encode app rules: {e}")))?;
-    std::fs::write(path, contents).map_err(|e| {
+    safe_fs::write(path, contents).map_err(|e| {
         WhsprError::Config(format!("failed to write app rules {}: {e}", path.display()))
     })?;
     Ok(())
@@ -144,7 +145,7 @@ pub(super) fn read_glossary_file(path: &Path) -> Result<Vec<GlossaryEntry>> {
         return Ok(Vec::new());
     }
 
-    let contents = std::fs::read_to_string(path).map_err(|e| {
+    let contents = safe_fs::read_to_string(path).map_err(|e| {
         WhsprError::Config(format!("failed to read glossary {}: {e}", path.display()))
     })?;
     if contents.trim().is_empty() {
@@ -162,28 +163,30 @@ pub(super) fn write_glossary_file(path: &Path, entries: &[GlossaryEntry]) -> Res
         entries: entries.to_vec(),
     })
     .map_err(|e| WhsprError::Config(format!("failed to encode glossary: {e}")))?;
-    std::fs::write(path, contents).map_err(|e| {
+    safe_fs::write(path, contents).map_err(|e| {
         WhsprError::Config(format!("failed to write glossary {}: {e}", path.display()))
     })?;
     Ok(())
 }
 
-pub(super) fn load_policy_file_for_runtime(path: &Path) -> Vec<AppRule> {
+pub(super) fn load_policy_file_for_runtime_with_status(path: &Path) -> (Vec<AppRule>, bool) {
     match read_policy_file(path) {
-        Ok(rules) => rules,
+        Ok(rules) => (rules, false),
         Err(err) => {
             tracing::warn!("{err}; using built-in app rewrite defaults");
-            Vec::new()
+            (Vec::new(), true)
         }
     }
 }
 
-pub(super) fn load_glossary_file_for_runtime(path: &Path) -> Vec<GlossaryEntry> {
+pub(super) fn load_glossary_file_for_runtime_with_status(
+    path: &Path,
+) -> (Vec<GlossaryEntry>, bool) {
     match read_glossary_file(path) {
-        Ok(entries) => entries,
+        Ok(entries) => (entries, false),
         Err(err) => {
             tracing::warn!("{err}; ignoring runtime glossary");
-            Vec::new()
+            (Vec::new(), true)
         }
     }
 }

src/app/mod.rs

@@ -3,19 +3,22 @@ use std::time::Instant;
 use crate::config::Config;
 use crate::error::Result;
 use crate::postprocess::finalize;
+use crate::runtime_diagnostics::DictationRuntimeDiagnostics;
+use crate::runtime_support::PidLock;
 
 mod osd;
 mod runtime;
 
 use runtime::DictationRuntime;
 
-pub async fn run(config: Config) -> Result<()> {
+pub async fn run(config: Config, _pid_lock: PidLock) -> Result<()> {
     let activation_started = Instant::now();
+    let diagnostics = DictationRuntimeDiagnostics::new(&config);
     // Register signals before startup work to minimize early-signal races.
     let mut sigusr1 =
         tokio::signal::unix::signal(tokio::signal::unix::SignalKind::user_defined1())?;
     let mut sigterm = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())?;
-    let mut runtime = DictationRuntime::new(config);
+    let mut runtime = DictationRuntime::new(config, diagnostics.clone());
     let recording = runtime.start_recording()?;
     runtime.prepare_services()?;
 
@@ -41,6 +44,7 @@ pub async fn run(config: Config) -> Result<()> {
     if transcribed.is_empty() {
         tracing::warn!("transcription returned empty text");
         finalize::wait_for_feedback_drain().await;
+        diagnostics.clear_with_stage(crate::runtime_diagnostics::DictationStage::Done);
         return Ok(());
     }
 
@@ -53,10 +57,12 @@ pub async fn run(config: Config) -> Result<()> {
         // causes an audible click as the OS closes our audio file descriptors.
         // With speech, transcription takes seconds — providing natural drain time.
         finalize::wait_for_feedback_drain().await;
+        diagnostics.clear_with_stage(crate::runtime_diagnostics::DictationStage::Done);
         return Ok(());
     }
 
     runtime.inject_finalized(finalized).await?;
+    diagnostics.clear_with_stage(crate::runtime_diagnostics::DictationStage::Done);
 
     tracing::info!("done");
     tracing::info!(

src/app/osd.rs

@@ -1,8 +1,13 @@
 use std::process::Child;
+use std::time::Duration;
 
 #[cfg(feature = "osd")]
 use std::process::Command;
 
+use crate::runtime_guards::wait_child_with_timeout;
+
+const OSD_SHUTDOWN_TIMEOUT: Duration = Duration::from_millis(250);
+
 #[cfg(feature = "osd")]
 pub(super) fn spawn_osd() -> Option<Child> {
     // Look for whispers-osd next to our own binary first, then fall back to PATH
@@ -38,8 +43,21 @@ pub(super) fn kill_osd(child: &mut Option<Child>) {
         unsafe {
             libc::kill(pid, libc::SIGTERM);
         }
-        let _ = c.wait();
-        tracing::debug!("whispers-osd (pid {pid}) terminated");
+        match wait_child_with_timeout(&mut c, OSD_SHUTDOWN_TIMEOUT) {
+            Ok(Some(_)) => {
+                tracing::debug!("whispers-osd (pid {pid}) terminated");
+            }
+            Ok(None) => {
+                unsafe {
+                    libc::kill(pid, libc::SIGKILL);
+                }
+                let _ = wait_child_with_timeout(&mut c, OSD_SHUTDOWN_TIMEOUT);
+                tracing::warn!("whispers-osd (pid {pid}) did not exit after SIGTERM; killed");
+            }
+            Err(err) => {
+                tracing::warn!("failed to wait for whispers-osd (pid {pid}) to exit: {err}");
+            }
+        }
     }
 }