Fix external STT server lifecycle to ensure single instance and proper cleanup

[devin-ai-integration]

Fix external STT server lifecycle to prevent multiple instances

Summary

Fixes a race condition in the external STT server lifecycle management that caused multiple server processes to accumulate when switching between models (e.g., ParakeetV2 ↔ ParakeetV3).

Root Cause: When switching models, stop_all_stt_servers() would wait for the actor to be removed from the registry, but the actual process cleanup happened asynchronously in the post_stop() hook. This meant new servers could start spawning before old processes were fully terminated.

Solution:

• Added wait_for_process_cleanup() function that verifies external STT processes are actually terminated before returning from stop_stt_server()
• Waits up to 5 seconds for graceful termination (checking every 100ms)
• Falls back to force kill if process doesn't terminate in time
• Added helper functions to hypr_host crate for process verification
• NEW: Refactored cleanup logic with dependency injection to enable unit testing

Changes:

• crates/host/src/lib.rs: Added has_processes_matching() and wait_for_processes_to_terminate() functions
• plugins/local-stt/src/server/supervisor.rs:
  • Added wait_for_process_cleanup() call after stopping external STT servers
  • Added ProcessCleanupDeps struct for dependency injection
  • Added wait_for_process_cleanup_with() that accepts test dependencies
  • Added 3 unit tests covering graceful termination, force kill, and edge cases
• crates/host/Cargo.toml: Added tokio dependency with time feature for async sleep

Updates Since Last Revision

Added unit tests for the cleanup logic using dependency injection:

• test_cleanup_process_terminates_gracefully: Verifies no force kill when process exits cleanly
• test_cleanup_process_never_terminates: Verifies force kill is called and sleep happens after
• test_cleanup_process_kill_returns_zero: Verifies no sleep when kill finds no processes

The cleanup logic is now testable without spawning real processes or waiting real time.

Review & Testing Checklist for Human

⚠️ CRITICAL - This PR has NOT been tested with actual STT server processes running

The unit tests verify the cleanup logic in isolation but do NOT test the full lifecycle with real processes. Manual testing is essential.

• Test model switching: Switch between ParakeetV2 and ParakeetV3 multiple times and verify only ONE "stt" process is running at any time (use ps aux | grep stt or Activity Monitor)
• Test timing: Verify the 5-second timeout is appropriate - model switching shouldn't feel sluggish, but should wait long enough for processes to terminate
• Test app shutdown: Quit the app and verify all STT processes are cleaned up properly
• Verify schema.json changes: The owhisper/schema.json file has property reordering - confirm these changes are intentional and don't break anything
• Check process matching safety: Verify the "stt" substring matching doesn't accidentally match/kill unrelated processes on your system

Recommended Test Plan

1. Start the app and select an external STT model (ParakeetV2 or ParakeetV3)
2. Open Activity Monitor / Task Manager and filter for "stt" processes
3. Switch to a different external STT model
4. Verify only one "stt" process exists after the switch completes
5. Repeat steps 3-4 several times to ensure consistency
6. Quit the app and verify all "stt" processes are terminated

Notes

• The fix only applies to ServerType::External (Am models), not ServerType::Internal (Whisper models) since internal servers don't spawn external processes
• The process matching uses substring matching on process names containing "stt" - this should be safe but worth double-checking
• Unit tests use mocked dependencies and don't verify actual process cleanup behavior
• The ProcessCleanupDeps struct uses function pointers with Pin<Box<Future>> for testability - the type signature is verbose but necessary for async testing

Session: https://app.devin.ai/sessions/0d06a16e24d441a087fec63fc1e92a45
Requested by: yujonglee (@yujonglee)

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch devin/1763954023-fix-stt-server-lifecycle

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[netlify]

✅ Deploy Preview for hyprnote ready!

Name	Link
🔨 Latest commit	c16af19
🔍 Latest deploy log	https://app.netlify.com/projects/hyprnote/deploys/6923d9b3c69834000898c0b9
😎 Deploy Preview	https://deploy-preview-1829--hyprnote.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.