@drakulavich/kesha-voice-kit 1.18.2 → 1.18.3

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/logo.png" alt="Kesha Voice Kit" width="200">
+  <img src="docs/assets/logo.png" alt="Kesha Voice Kit" width="200">
 </p>
 
 <h1 align="center">Kesha Voice Kit</h1>
@@ -11,12 +11,12 @@
   <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun" alt="Bun"></a>
 </p>
 
-<p align="center"><b>Open-source voice toolkit.</b> Optimized for Apple Silicon (CoreML), with ONNX fallback on supported Linux/Windows builds.<br>A collection of small, fast, open-source audio models — packaged as CLI tools and an <a href="https://github.com/openclaw/openclaw">OpenClaw</a> skill for LLM agents.</p>
+<p align="center"><b>Give your local tools and LLM agents a voice.</b><br>Fast speech-to-text, text-to-speech, voice-activity detection, and language detection in one local-first CLI: Apple Silicon CoreML first, ONNX fallback on supported Linux/Windows builds.</p>
 
-- **Speech-to-text** — 25 languages, ~15x faster than Whisper on Apple Silicon, ~2.5x on CPU
-- **Text-to-speech** — Kokoro (EN) + Vosk-TTS (RU) + macOS system voices, SSML preview
-- **Rust engine** — single 20MB binary, no ffmpeg, no Python, no native Node addons
-- **OpenClaw-ready** — plug into your LLM agent as a voice processing skill
+- **Transcribe locally** — 25 languages, up to ~19x faster than Whisper on Apple Silicon, ~2.5x on CPU
+- **Speak back** — Kokoro (EN), Vosk-TTS (RU), macOS system voices, and SSML preview
+- **Plug into agents** — ship voice workflows as CLI commands or an <a href="https://github.com/openclaw/openclaw">OpenClaw</a> skill
+- **Small Rust engine** — single ~20MB binary, no ffmpeg, no Python, no native Node addons
 
 See [Product positioning](docs/product-positioning.md) for supported workflows, non-goals, maturity labels, and the platform matrix.
 
@@ -209,9 +209,9 @@ $ kesha freedom.ogg tahiti.ogg
 Таити, Таити! Не были мы ни в какой Таити! Нас и тут неплохо кормят.
 ```
 
-Stdout: transcript. Stderr: errors. Pipe-friendly. Also available as `parakeet` command (backward-compatible alias).
+Stdout: transcript. Stderr: errors. Pipe-friendly.
 
-For long / silence-heavy audio, use `--vad` (auto-on past 120 s). Details: [docs/vad.md](docs/vad.md).
+For long / silence-heavy audio, install VAD (`kesha install --vad`) and run without `--no-vad`. Kesha auto-uses VAD past 120 s when installed; without VAD, very long audio falls back to fixed ASR chunks. Details: [docs/vad.md](docs/vad.md).
 
 **Speaker diarization** (darwin-arm64, post-v1.12.0):
 
@@ -267,11 +267,11 @@ macOS system voices, SSML, voice listing, and the full voice catalogue: [docs/tt
 
 ## Performance
 
-> **~15x faster than Whisper** on Apple Silicon (M3 Pro), **~2.5x faster** on CPU
+> **Up to ~19x faster than Whisper** on Apple Silicon (M2), **~2.5x faster** on CPU
 
 Compared against Whisper `large-v3-turbo` — all engines auto-detect language.
 
-![Benchmark: openai-whisper vs faster-whisper vs Kesha Voice Kit](assets/benchmark.svg)
+![Benchmark: openai-whisper vs faster-whisper vs Kesha Voice Kit](docs/assets/benchmark.svg)
 
 See [BENCHMARK.md](BENCHMARK.md) for the full per-file breakdown (Russian + English).
 
@@ -297,6 +297,7 @@ Audio decoding via [symphonia](https://github.com/pdeljanov/Symphonia) — WAV,
 ## Integrations
 
 - **OpenClaw** — give your LLM agent ears. Install & config: [docs/openclaw.md](docs/openclaw.md).
+- **Hermes Agent** — local STT/TTS through Hermes command providers. Setup: [docs/hermes.md](docs/hermes.md).
 - **Raycast** (macOS) — transcribe selected audio & speak clipboard from the launcher. Source + install: [`raycast/`](raycast/).
 
 ## Programmatic API

package/completions/kesha.bash

@@ -6,7 +6,7 @@ _kesha_completion() {
   COMPREPLY=()
   cur="${COMP_WORDS[COMP_CWORD]}"
   command="${COMP_WORDS[1]}"
-  commands="completions doctor install manpage say stats status support-bundle"
+  commands="completions doctor install manpage record say stats status support-bundle"
 
   if [[ "$COMP_CWORD" -eq 1 ]]; then
     if [[ "$cur" == -* ]]; then
@@ -22,6 +22,7 @@ _kesha_completion() {
     doctor) opts="--help -h --json --redact" ;;
     install) opts="--help -h --coreml --onnx --no-cache --plan --tts --vad --diarize" ;;
     manpage) opts="--help -h" ;;
+    record) opts="--help -h --out --max-seconds --debug" ;;
     say) opts="--help -h --voice --lang --out --rate --list-voices --ssml --format --bitrate --sample-rate --no-expand-abbrev --verbose --debug" ;;
     stats) opts="--help -h --format" ;;
     status) opts="--help -h --disk" ;;
@@ -35,4 +36,3 @@ _kesha_completion() {
 }
 
 complete -F _kesha_completion kesha
-complete -F _kesha_completion parakeet

package/completions/kesha.fish

@@ -4,6 +4,7 @@ complete -c kesha -n '__fish_use_subcommand' -a 'completions' -d 'Print shell co
 complete -c kesha -n '__fish_use_subcommand' -a 'doctor' -d 'Collect support diagnostics without changing local state'
 complete -c kesha -n '__fish_use_subcommand' -a 'install' -d 'Download inference engine and models'
 complete -c kesha -n '__fish_use_subcommand' -a 'manpage' -d 'Print the kesha(1) manpage'
+complete -c kesha -n '__fish_use_subcommand' -a 'record' -d 'Record microphone audio to a WAV file'
 complete -c kesha -n '__fish_use_subcommand' -a 'say' -d 'Synthesize speech from text (TTS). Writes audio to stdout (or --out file). Defaults to WAV; use --format ogg-opus for messenger-ready voice notes.'
 complete -c kesha -n '__fish_use_subcommand' -a 'stats' -d 'Manage local anonymous Kesha Stats'
 complete -c kesha -n '__fish_use_subcommand' -a 'status' -d 'Show backend installation status'
@@ -22,7 +23,7 @@ complete -c kesha -n '__fish_use_subcommand' -l format -r -d 'Output format: tra
 complete -c kesha -n '__fish_use_subcommand' -l lang -r -d 'Expected language code (ISO 639-1), warn if mismatch'
 complete -c kesha -n '__fish_use_subcommand' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
 complete -c kesha -n '__fish_use_subcommand' -l vad -d 'Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.'
-complete -c kesha -n '__fish_use_subcommand' -l no-vad -d 'Disable VAD preprocessing regardless of duration or install state'
+complete -c kesha -n '__fish_use_subcommand' -l no-vad -d 'Force full-file ASR for short/medium files; long audio fails early'
 complete -c kesha -n '__fish_seen_subcommand_from completions' -l help -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from completions' -s h -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from doctor' -l help -d 'Show help'
@@ -40,6 +41,11 @@ complete -c kesha -n '__fish_seen_subcommand_from install' -l vad -d 'Also insta
 complete -c kesha -n '__fish_seen_subcommand_from install' -l diarize -d 'Also install the Sortformer streaming-diarization model (~245MB, darwin-arm64 only — #199)'
 complete -c kesha -n '__fish_seen_subcommand_from manpage' -l help -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from manpage' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from record' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from record' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from record' -l out -r -d 'Write recorded WAV audio to this path'
+complete -c kesha -n '__fish_seen_subcommand_from record' -l max-seconds -r -d 'Maximum recording duration in seconds'
+complete -c kesha -n '__fish_seen_subcommand_from record' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l help -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from say' -s h -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l voice -r -d 'Voice id, e.g. en-am_michael'
@@ -63,67 +69,3 @@ complete -c kesha -n '__fish_seen_subcommand_from status' -l disk -d 'Include re
 complete -c kesha -n '__fish_seen_subcommand_from support-bundle' -l help -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from support-bundle' -s h -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from support-bundle' -l output -r -d 'Write archive to this .tar.gz path'
-complete -c parakeet -f
-complete -c parakeet -n '__fish_use_subcommand' -a 'completions' -d 'Print shell completion script for bash, zsh, or fish'
-complete -c parakeet -n '__fish_use_subcommand' -a 'doctor' -d 'Collect support diagnostics without changing local state'
-complete -c parakeet -n '__fish_use_subcommand' -a 'install' -d 'Download inference engine and models'
-complete -c parakeet -n '__fish_use_subcommand' -a 'manpage' -d 'Print the kesha(1) manpage'
-complete -c parakeet -n '__fish_use_subcommand' -a 'say' -d 'Synthesize speech from text (TTS). Writes audio to stdout (or --out file). Defaults to WAV; use --format ogg-opus for messenger-ready voice notes.'
-complete -c parakeet -n '__fish_use_subcommand' -a 'stats' -d 'Manage local anonymous Kesha Stats'
-complete -c parakeet -n '__fish_use_subcommand' -a 'status' -d 'Show backend installation status'
-complete -c parakeet -n '__fish_use_subcommand' -a 'support-bundle' -d 'Create a redacted diagnostics archive for support'
-complete -c parakeet -n '__fish_use_subcommand' -l help -d 'Show help'
-complete -c parakeet -n '__fish_use_subcommand' -s h -d 'Show help'
-complete -c parakeet -n '__fish_use_subcommand' -l version -d 'Show version'
-complete -c parakeet -n '__fish_use_subcommand' -s v -d 'Show version'
-complete -c parakeet -n '__fish_use_subcommand' -l json -d 'Output results as JSON'
-complete -c parakeet -n '__fish_use_subcommand' -l toon -d 'Output results as TOON (compact, LLM-friendly encoding of the same data as --json)'
-complete -c parakeet -n '__fish_use_subcommand' -l timestamps -d 'Include timestamped transcript segments in JSON/TOON output'
-complete -c parakeet -n '__fish_use_subcommand' -l speakers -d 'Include speaker labels in transcript segments. Requires --json / --toon / --format json. Implies --timestamps. Currently darwin-arm64 only (#199).'
-complete -c parakeet -n '__fish_use_subcommand' -l include-errors -d 'With --json, output { results, errors } so scripts can read per-file failures without parsing stderr'
-complete -c parakeet -n '__fish_use_subcommand' -l verbose -d 'Show language detection details'
-complete -c parakeet -n '__fish_use_subcommand' -l format -r -d 'Output format: transcript | json | toon (long-form alias for --json / --toon)'
-complete -c parakeet -n '__fish_use_subcommand' -l lang -r -d 'Expected language code (ISO 639-1), warn if mismatch'
-complete -c parakeet -n '__fish_use_subcommand' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
-complete -c parakeet -n '__fish_use_subcommand' -l vad -d 'Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.'
-complete -c parakeet -n '__fish_use_subcommand' -l no-vad -d 'Disable VAD preprocessing regardless of duration or install state'
-complete -c parakeet -n '__fish_seen_subcommand_from completions' -l help -d 'Show help'
-complete -c parakeet -n '__fish_seen_subcommand_from completions' -s h -d 'Show help'
-complete -c parakeet -n '__fish_seen_subcommand_from doctor' -l help -d 'Show help'
-complete -c parakeet -n '__fish_seen_subcommand_from doctor' -s h -d 'Show help'
-complete -c parakeet -n '__fish_seen_subcommand_from doctor' -l json -d 'Output diagnostics as JSON'
-complete -c parakeet -n '__fish_seen_subcommand_from doctor' -l redact -d 'Redact secrets and user-home paths from diagnostic output'
-complete -c parakeet -n '__fish_seen_subcommand_from install' -l help -d 'Show help'
-complete -c parakeet -n '__fish_seen_subcommand_from install' -s h -d 'Show help'
-complete -c parakeet -n '__fish_seen_subcommand_from install' -l coreml -d 'Force CoreML backend (macOS arm64)'
-complete -c parakeet -n '__fish_seen_subcommand_from install' -l onnx -d 'Force ONNX backend'
-complete -c parakeet -n '__fish_seen_subcommand_from install' -l no-cache -d 'Re-download even if cached'
-complete -c parakeet -n '__fish_seen_subcommand_from install' -l plan -d 'Show download, disk, and warm-up plan without changing local state'
-complete -c parakeet -n '__fish_seen_subcommand_from install' -l tts -d 'Also install TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)'
-complete -c parakeet -n '__fish_seen_subcommand_from install' -l vad -d 'Also install Silero VAD (~2.3MB) for long-audio preprocessing'
-complete -c parakeet -n '__fish_seen_subcommand_from install' -l diarize -d 'Also install the Sortformer streaming-diarization model (~245MB, darwin-arm64 only — #199)'
-complete -c parakeet -n '__fish_seen_subcommand_from manpage' -l help -d 'Show help'
-complete -c parakeet -n '__fish_seen_subcommand_from manpage' -s h -d 'Show help'
-complete -c parakeet -n '__fish_seen_subcommand_from say' -l help -d 'Show help'
-complete -c parakeet -n '__fish_seen_subcommand_from say' -s h -d 'Show help'
-complete -c parakeet -n '__fish_seen_subcommand_from say' -l voice -r -d 'Voice id, e.g. en-am_michael'
-complete -c parakeet -n '__fish_seen_subcommand_from say' -l lang -r -d 'BCP 47 language code (default en-us)'
-complete -c parakeet -n '__fish_seen_subcommand_from say' -l out -r -d 'Write audio to file instead of stdout'
-complete -c parakeet -n '__fish_seen_subcommand_from say' -l rate -r -d 'Speaking rate 0.5–2.0'
-complete -c parakeet -n '__fish_seen_subcommand_from say' -l list-voices -d 'List installed voices and exit'
-complete -c parakeet -n '__fish_seen_subcommand_from say' -l ssml -d 'Parse input as SSML (supports <speak>, <break>; strips unknown tags)'
-complete -c parakeet -n '__fish_seen_subcommand_from say' -l format -r -d 'Output format: wav (default) or ogg-opus (Telegram-ready voice note). Inferred from --out extension when omitted.'
-complete -c parakeet -n '__fish_seen_subcommand_from say' -l bitrate -r -d 'Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.'
-complete -c parakeet -n '__fish_seen_subcommand_from say' -l sample-rate -r -d 'Opus encoder sample rate (8000/12000/16000/24000/48000). Only with --format ogg-opus.'
-complete -c parakeet -n '__fish_seen_subcommand_from say' -l no-expand-abbrev -d 'Disable Russian acronym auto-expansion (ВОЗ → \'вэ о зэ\') for ru-vosk-* voices. <say-as interpret-as=\'characters\'> still works. Applies to Russian (ru-vosk-*) and English (en-*) voices.'
-complete -c parakeet -n '__fish_seen_subcommand_from say' -l verbose -d 'Log TTS synthesis time to stderr'
-complete -c parakeet -n '__fish_seen_subcommand_from say' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
-complete -c parakeet -n '__fish_seen_subcommand_from stats' -l help -d 'Show help'
-complete -c parakeet -n '__fish_seen_subcommand_from stats' -s h -d 'Show help'
-complete -c parakeet -n '__fish_seen_subcommand_from stats' -l format -r -d 'Export format: json | csv'
-complete -c parakeet -n '__fish_seen_subcommand_from status' -l help -d 'Show help'
-complete -c parakeet -n '__fish_seen_subcommand_from status' -s h -d 'Show help'
-complete -c parakeet -n '__fish_seen_subcommand_from status' -l disk -d 'Include recursive cache disk usage'
-complete -c parakeet -n '__fish_seen_subcommand_from support-bundle' -l help -d 'Show help'
-complete -c parakeet -n '__fish_seen_subcommand_from support-bundle' -s h -d 'Show help'
-complete -c parakeet -n '__fish_seen_subcommand_from support-bundle' -l output -r -d 'Write archive to this .tar.gz path'

package/completions/kesha.zsh

@@ -1,4 +1,4 @@
-#compdef kesha parakeet
+#compdef kesha
 # zsh completion for kesha.
 
 _kesha() {
@@ -8,6 +8,7 @@ _kesha() {
     'doctor:Collect support diagnostics without changing local state'
     'install:Download inference engine and models'
     'manpage:Print the kesha(1) manpage'
+    'record:Record microphone audio to a WAV file'
     'say:Synthesize speech from text (TTS). Writes audio to stdout (or --out file). Defaults to WAV; use --format ogg-opus for messenger-ready voice notes.'
     'stats:Manage local anonymous Kesha Stats'
     'status:Show backend installation status'
@@ -30,7 +31,7 @@ _kesha() {
       '--lang=[Expected language code (ISO 639-1), warn if mismatch]:lang:' \
       '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]' \
       '--vad[Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.]' \
-      '--no-vad[Disable VAD preprocessing regardless of duration or install state]'
+      '--no-vad[Force full-file ASR for short/medium files; long audio fails early]'
     else
       _describe -t commands 'kesha command' commands
     fi
@@ -63,6 +64,13 @@ _kesha() {
       _arguments '--help[Show help]' \
         '-h[Show help]'
       ;;
+    record)
+      _arguments '--help[Show help]' \
+        '-h[Show help]' \
+        '--out=[Write recorded WAV audio to this path]:out:' \
+        '--max-seconds=[Maximum recording duration in seconds]:max seconds:' \
+        '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]'
+      ;;
     say)
       _arguments '--help[Show help]' \
         '-h[Show help]' \
@@ -109,7 +117,7 @@ _kesha() {
       '--lang=[Expected language code (ISO 639-1), warn if mismatch]:lang:' \
       '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]' \
       '--vad[Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.]' \
-      '--no-vad[Disable VAD preprocessing regardless of duration or install state]'
+      '--no-vad[Force full-file ASR for short/medium files; long audio fails early]'
       ;;
   esac
 }

package/docs/product-positioning.md

@@ -8,6 +8,7 @@ The product promise is not "one model for every audio problem." The promise is a
 
 - Developers and agent builders who need local speech-to-text for voice messages, meetings, support clips, or batch audio files.
 - OpenClaw users who want private, low-latency voice-message transcription through a CLI model route.
+- Hermes Agent users who want command-provider STT/TTS without cloud audio uploads.
 - macOS users who want the fastest path on Apple Silicon through CoreML, with a CPU/ONNX fallback on Linux and Windows.
 - Automation-heavy users who prefer stdout/stderr contracts, JSON/TOON output, and shell-friendly commands over a hosted dashboard.
 - Projects that can accept explicit model downloads and local cache management in exchange for no API keys and no cloud audio upload.
@@ -24,6 +25,7 @@ The product promise is not "one model for every audio problem." The promise is a
 | Use macOS system voices without model downloads | Stable on macOS | `kesha say --voice macos-*` |
 | Label speakers in meeting transcripts | Preview, darwin-arm64 only | `kesha --json --vad --speakers meeting.m4a` |
 | Integrate with OpenClaw as a local voice model | Stable integration surface, user-configured route | `docs/openclaw.md` |
+| Integrate with Hermes Agent as local STT/TTS commands | Stable CLI surface, user-configured route | `docs/hermes.md` |
 | Use Raycast actions for selected-file transcription or clipboard speech | Beta, macOS only | `raycast/` extension |
 | Install through Nix instead of Bun/npm | Beta, selected systems | `docs/nix-install.md` |
 
@@ -51,6 +53,7 @@ The product promise is not "one model for every audio problem." The promise is a
 | Speaker diarization | Preview | darwin-arm64 only; cluster IDs are stable within one file only. |
 | Raycast extension | Beta | Convenience UI over the CLI; macOS-only. |
 | OpenClaw plugin | Stable integration surface | Discovery is packaged; actual audio route remains explicit user config. |
+| Hermes Agent command provider | Stable CLI surface | Hermes owns the command-provider lifecycle; Kesha supplies the local STT/TTS commands. |
 | Nix flake | Beta | Reproducible alternate install path for selected systems; Bun/npm remains canonical. |
 
 ## Platform matrix
@@ -66,6 +69,7 @@ The product promise is not "one model for every audio problem." The promise is a
 | Speaker diarization | Preview, darwin-arm64 only | Not supported | Not supported | Not supported | Not wired into the Nix build yet |
 | Raycast extension | Supported | Not shipped | Not applicable | Not applicable | Not applicable |
 | OpenClaw integration | Supported through CLI route | Not shipped | Supported through CLI route | Supported through CLI route | Use the installed `kesha` command from the chosen path |
+| Hermes Agent integration | Supported through command providers | Not shipped | Supported through command providers | Supported through command providers | Use the installed `kesha` command from the chosen path |
 
 `macOS x64` means Intel Macs. Kesha does not currently publish a `darwin-x64` engine binary, so Intel Macs are intentionally marked as not shipped rather than implied to use the ONNX fallback.
 

package/man/kesha.1

@@ -1,4 +1,4 @@
-.TH KESHA 1 "May 2026" "kesha 1.18.2" "User Commands"
+.TH KESHA 1 "May 2026" "kesha 1.18.3" "User Commands"
 .SH NAME
 kesha \- open-source local voice toolkit
 .SH SYNOPSIS
@@ -23,6 +23,9 @@ Download inference engine and models
 .B manpage
 Print the kesha(1) manpage
 .TP
+.B record
+Record microphone audio to a WAV file
+.TP
 .B say
 Synthesize speech from text (TTS). Writes audio to stdout (or \-\-out file). Defaults to WAV; use \-\-format ogg\-opus for messenger\-ready voice notes.
 .TP
@@ -67,7 +70,7 @@ Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)
 Force Silero VAD preprocessing (kesha install \-\-vad first). Without this, VAD auto\-engages on audio ≥ 120s.
 .TP
 .B \-\-no\-vad
-Disable VAD preprocessing regardless of duration or install state
+Force full\-file ASR for short/medium files; long audio fails early
 .SH SUBCOMMAND OPTIONS
 .SS doctor
 .TP
@@ -98,6 +101,16 @@ Also install Silero VAD (~2.3MB) for long\-audio preprocessing
 .TP
 .B \-\-diarize
 Also install the Sortformer streaming\-diarization model (~245MB, darwin\-arm64 only — #199)
+.SS record
+.TP
+.B \-\-out
+Write recorded WAV audio to this path
+.TP
+.B \-\-max\-seconds
+Maximum recording duration in seconds
+.TP
+.B \-\-debug
+Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)
 .SS say
 .TP
 .B \-\-voice

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.18.2",
+  "version": "1.18.3",
   "description": "Give your local tools a voice: fast STT in 25 languages (~19x faster than Whisper on Apple Silicon, ONNX CPU fallback), TTS via Kokoro/Vosk/macOS voices, VAD + 107-language detection. Rust engine, Bun CLI, OpenClaw skill.",
   "type": "module",
   "bin": {
-    "kesha": "bin/kesha.js",
-    "parakeet": "bin/kesha.js"
+    "kesha": "bin/kesha.js"
   },
   "exports": {
     ".": "./src/cli.ts",

package/src/cli/dispatch.ts

@@ -6,13 +6,24 @@ import { completionsCommand } from "./completions";
 import { doctorCommand } from "./doctor";
 import { installCommand } from "./install";
 import { manpageCommand } from "./manpage";
+import { recordCommand } from "./record";
 import { sayCommand } from "./say";
 import { statsCommand } from "./stats";
 import { statusCommand } from "./status";
 import { supportBundleCommand } from "./support-bundle";
 import { mainCommand } from "./main";
 
-const SUBCOMMANDS = ["doctor", "install", "status", "say", "stats", "support-bundle", "completions", "manpage"];
+const SUBCOMMANDS = [
+  "doctor",
+  "install",
+  "status",
+  "record",
+  "say",
+  "stats",
+  "support-bundle",
+  "completions",
+  "manpage",
+];
 
 function isPathLike(arg: string): boolean {
   return arg.includes(".") || arg.includes("/") || existsSync(arg);
@@ -46,6 +57,11 @@ export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
     return;
   }
 
+  if (firstArg === "record") {
+    await runMain(recordCommand, { rawArgs: restArgs });
+    return;
+  }
+
   if (firstArg === "say") {
     await runMain(sayCommand, { rawArgs: restArgs });
     return;

package/src/cli/main.ts

@@ -16,6 +16,7 @@ import { packageVersion } from "../package-info";
 import { formatToonOutput } from "../toon";
 import { artifactFromFile, createStatsRecorder } from "../stats";
 import { createPercentProgress } from "../progress";
+import { getPendingSignalExitCode, waitForPendingSignalCleanup } from "../process-tree";
 
 interface MainCommandArgs {
   _: string[];
@@ -107,6 +108,15 @@ export function checkLanguageMismatch(expected: string | undefined, detected: st
   return `warning: expected language "${expected}" but detected "${detected}"`;
 }
 
+export function shouldReportTranscribeProgress(input: {
+  stderrIsTty: boolean;
+  stdoutIsTty: boolean;
+  debugEnabled: boolean;
+}): boolean {
+  if (input.debugEnabled) return false;
+  return input.stderrIsTty || !input.stdoutIsTty;
+}
+
 export const mainCommand = defineCommand({
   meta: {
     name: "kesha",
@@ -119,6 +129,7 @@ export const mainCommand = defineCommand({
       "  doctor     Collect support diagnostics.\n" +
       "  install    Download engine and models.\n" +
       "  manpage    Print the kesha(1) manpage.\n" +
+      "  record     Record microphone audio to a WAV file.\n" +
       "  status     Inspect installed backend.\n" +
       "  say        Synthesize speech from text.\n" +
       "  stats      Manage local anonymous performance stats.\n" +
@@ -175,7 +186,7 @@ export const mainCommand = defineCommand({
     },
     "no-vad": {
       type: "boolean",
-      description: "Disable VAD preprocessing regardless of duration or install state",
+      description: "Force full-file ASR for short/medium files; long audio fails early",
       default: false,
     },
   },
@@ -229,6 +240,7 @@ export const mainCommand = defineCommand({
           "       kesha doctor [--json] [--redact]\n" +
           "       kesha install [--no-cache]\n" +
           "       kesha manpage\n" +
+          "       kesha record --out path.wav [--max-seconds 120]\n" +
           "       kesha status\n" +
           "       kesha say <text>\n" +
           "       kesha stats [enable|disable|status|week|errors|export|reset|vacuum|retention]\n" +
@@ -243,7 +255,11 @@ export const mainCommand = defineCommand({
     const stats = createStatsRecorder("transcribe");
 
     const wantsLangId = !!(args.lang || args.verbose || wantsJson || wantsToon || wantsTranscript);
-    const reportProgress = process.stderr.isTTY === true || process.stdout.isTTY !== true;
+    const reportProgress = shouldReportTranscribeProgress({
+      stderrIsTty: process.stderr.isTTY === true,
+      stdoutIsTty: process.stdout.isTTY === true,
+      debugEnabled: log.isDebugEnabled(),
+    });
 
     for (const file of files) {
       if (!existsSync(file)) {
@@ -269,15 +285,31 @@ export const mainCommand = defineCommand({
               estimatedTotalMs: args.speakers ? 60 * 60 * 1000 : 30 * 60 * 1000,
             })
           : null;
-        // Run audio lang-id and transcription concurrently.
-        const [audioResult, transcript] = await Promise.all([
-          wantsLangId
-            ? stats.timeStage("lang_id_audio", () => detectAudioLanguageEngine(file))
-            : Promise.resolve(null),
-          stats.timeStage("transcribe", () =>
-            transcribeWithSegments(file, { vad: vadMode, timestamps: args.timestamps, speakers: args.speakers })
-          ),
-        ]);
+        // Run audio lang-id and transcription concurrently, but do not leave
+        // the sibling engine process alive if one side fails first.
+        const engineAbort = new AbortController();
+        const audioPromise = wantsLangId
+          ? stats.timeStage("lang_id_audio", () =>
+              detectAudioLanguageEngine(file, { signal: engineAbort.signal })
+            )
+          : Promise.resolve(null);
+        const transcriptPromise = stats.timeStage("transcribe", () =>
+          transcribeWithSegments(file, {
+            vad: vadMode,
+            signal: engineAbort.signal,
+            timestamps: args.timestamps,
+            speakers: args.speakers,
+          })
+        );
+        let audioResult: LangDetectResult | null;
+        let transcript: Awaited<ReturnType<typeof transcribeWithSegments>>;
+        try {
+          [audioResult, transcript] = await Promise.all([audioPromise, transcriptPromise]);
+        } catch (err) {
+          engineAbort.abort();
+          await Promise.allSettled([audioPromise, transcriptPromise]);
+          throw err;
+        }
         const { text, segments } = transcript;
 
         let audioLanguage: LangDetectResult | undefined;
@@ -347,6 +379,13 @@ export const mainCommand = defineCommand({
 
     stats.finish(hasError ? "failed" : "success", files.length);
 
-    if (hasError) process.exit(1);
+    if (hasError) {
+      const signalExitCode = getPendingSignalExitCode();
+      if (signalExitCode !== null) {
+        await waitForPendingSignalCleanup();
+        process.exit(signalExitCode);
+      }
+      process.exit(1);
+    }
   },
 });

package/src/cli/record.ts

@@ -0,0 +1,71 @@
+import { defineCommand } from "citty";
+import { recordEngine } from "../engine";
+import { log } from "../log";
+
+export interface RecordArgs {
+  out?: string;
+  "max-seconds"?: string | number;
+  debug?: boolean;
+}
+
+export type ResolvedRecordArgs =
+  | { ok: true; out: string; maxSeconds: number }
+  | { ok: false; error: string };
+
+const DEFAULT_MAX_SECONDS = 120;
+const MAX_RECORD_SECONDS = 3600;
+
+export function resolveRecordArgs(args: RecordArgs): ResolvedRecordArgs {
+  const out = typeof args.out === "string" ? args.out.trim() : "";
+  if (!out) {
+    return { ok: false, error: "kesha record requires --out <path>." };
+  }
+
+  const rawMax = args["max-seconds"] ?? String(DEFAULT_MAX_SECONDS);
+  const raw = String(rawMax).trim();
+  const maxSeconds = Number(raw);
+  if (raw === "" || !Number.isFinite(maxSeconds)) {
+    return { ok: false, error: "--max-seconds must be a finite number." };
+  }
+  if (!Number.isInteger(maxSeconds) || maxSeconds <= 0 || maxSeconds > MAX_RECORD_SECONDS) {
+    return {
+      ok: false,
+      error: `--max-seconds must be an integer between 1 and ${MAX_RECORD_SECONDS}.`,
+    };
+  }
+
+  return { ok: true, out, maxSeconds };
+}
+
+export const recordCommand = defineCommand({
+  meta: {
+    name: "record",
+    description: "Record microphone audio to a WAV file",
+  },
+  args: {
+    out: {
+      type: "string",
+      description: "Write recorded WAV audio to this path",
+      required: true,
+    },
+    "max-seconds": {
+      type: "string",
+      description: "Maximum recording duration in seconds",
+      default: String(DEFAULT_MAX_SECONDS),
+    },
+    debug: {
+      type: "boolean",
+      description: "Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)",
+      default: false,
+    },
+  },
+  async run({ args }) {
+    if (args.debug) log.debugEnabled = true;
+    const resolved = resolveRecordArgs(args as RecordArgs);
+    if (!resolved.ok) {
+      log.error(resolved.error);
+      process.exit(2);
+    }
+    await recordEngine(resolved.out, resolved.maxSeconds);
+  },
+});

package/src/cli.ts

@@ -7,6 +7,8 @@ export { doctorCommand } from "./cli/doctor";
 export { completionsCommand } from "./cli/completions";
 export { installCommand } from "./cli/install";
 export { manpageCommand } from "./cli/manpage";
+export { recordCommand, resolveRecordArgs } from "./cli/record";
+export type { ResolvedRecordArgs } from "./cli/record";
 export { sayCommand } from "./cli/say";
 export { pickVoiceForLang } from "./voice-routing";
 export { statusCommand } from "./cli/status";
@@ -17,6 +19,7 @@ export {
   detectLanguage,
   checkLanguageMismatch,
   resolveOutputFormat,
+  shouldReportTranscribeProgress,
 } from "./cli/main";
 export type { ResolvedOutputFormat } from "./cli/main";
 export { runCli } from "./cli/dispatch";

package/src/engine.ts

@@ -2,6 +2,7 @@ import { existsSync, statSync } from "fs";
 import { join } from "path";
 import { log } from "./log";
 import { defaultEngineBinPath, keshaCacheDir } from "./paths";
+import { engineAbortError, registerProcessTree } from "./process-tree";
 
 /**
  * Capability-flag string surfaced via `kesha-engine --capabilities-json`. Single
@@ -96,26 +97,57 @@ export function spawnStdioWithDebugFd(
   return out as [SpawnStdioEntry, SpawnStdioEntry, SpawnStdioEntry, ...SpawnStdioEntry[]];
 }
 
-async function runEngine(args: string[]): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+export interface RunEngineOptions {
+  signal?: AbortSignal;
+}
+
+async function runEngine(
+  args: string[],
+  opts: RunEngineOptions = {},
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  if (opts.signal?.aborted) throw engineAbortError();
   const binPath = getEngineBinPath();
   const startedAt = performance.now();
   log.debug(`spawn ${binPath} ${args.join(" ")}`);
   const proc = Bun.spawn([binPath, ...args], {
+    detached: true,
     stdio: spawnStdioWithDebugFd(["ignore", "pipe", "pipe"]),
   });
+  const tree = registerProcessTree(proc);
+  let aborted = false;
+  let forceKillTimer: Timer | undefined;
+  const abort = () => {
+    aborted = true;
+    tree.terminate("SIGTERM");
+    forceKillTimer ??= tree.forceKillAfterGrace();
+  };
+  opts.signal?.addEventListener("abort", abort, { once: true });
   // `stdio: [...]` widens stdout/stderr into a union; indices 1/2 are
   // pinned to "pipe" by the helper, so the narrow ReadableStream type
   // is correct. Cast to drop the spurious `number` arm.
   const stdoutStream = proc.stdout as ReadableStream<Uint8Array>;
   const stderrStream = proc.stderr as ReadableStream<Uint8Array>;
 
-  const [stdout, stderr, exitCode] = await Promise.all([
-    new Response(stdoutStream).text(),
-    new Response(stderrStream).text(),
-    proc.exited,
-  ]);
+  let stdout: string;
+  let stderr: string;
+  let exitCode: number;
+  try {
+    [stdout, stderr, exitCode] = await Promise.all([
+      new Response(stdoutStream).text(),
+      new Response(stderrStream).text(),
+      proc.exited,
+    ]);
+  } finally {
+    opts.signal?.removeEventListener("abort", abort);
+    tree.dispose();
+    if (!aborted && forceKillTimer) clearTimeout(forceKillTimer);
+  }
 
   log.debug(`exit=${exitCode} dt=${Math.round(performance.now() - startedAt)}ms args=${JSON.stringify(args)}`);
+  if (aborted) {
+    log.debug(`aborted args=${JSON.stringify(args)}`);
+    throw engineAbortError();
+  }
 
   // #275 D4: surface engine stderr on the success path so warnings like
   // `hint: audio is 180s`, `Model mirror active:`, and the dtrace lines
@@ -131,12 +163,13 @@ async function runEngine(args: string[]): Promise<{ stdout: string; stderr: stri
 /** VAD preprocessing selector.
  *  - `"auto"` (default): engine decides — VAD when audio ≥ 120 s and model installed
  *  - `"on"`: force VAD (requires `kesha install --vad`)
- *  - `"off"`: force full-file pass regardless of duration or install state
+ *  - `"off"`: force full-file ASR for short/medium files; long audio fails early
  */
 export type VadMode = "auto" | "on" | "off";
 
 export interface TranscribeEngineOptions {
   vad?: VadMode;
+  signal?: AbortSignal;
   /** Request speaker labels in transcript segments. Requires the engine to
    * advertise `transcribe.diarize` (darwin-arm64 only — see #199). */
   speakers?: boolean;
@@ -197,7 +230,7 @@ export async function transcribeEngine(
   const args = ["transcribe", audioPath];
   if (opts.vad === "on") args.push("--vad");
   else if (opts.vad === "off") args.push("--no-vad");
-  const { stdout, stderr, exitCode } = await runEngine(args);
+  const { stdout, stderr, exitCode } = await runEngine(args, { signal: opts.signal });
   if (exitCode !== 0) {
     throw new Error(stderr || `kesha-engine exited with code ${exitCode}`);
   }
@@ -239,7 +272,7 @@ export async function transcribeEngineWithSegments(
   if (opts.speakers) {
     args.push("--speakers");
   }
-  const { stdout, stderr, exitCode } = await runEngine(args);
+  const { stdout, stderr, exitCode } = await runEngine(args, { signal: opts.signal });
   if (exitCode !== 0) {
     throw new Error(stderr || `kesha-engine exited with code ${exitCode}`);
   }
@@ -251,6 +284,28 @@ export async function transcribeEngineWithSegments(
   }
 }
 
+export async function recordEngine(outPath: string, maxSeconds: number): Promise<void> {
+  const binPath = getEngineBinPath();
+  const args = ["record", "--out", outPath, "--max-seconds", String(maxSeconds)];
+  const startedAt = performance.now();
+  log.debug(`spawn ${binPath} ${args.join(" ")}`);
+  const proc = Bun.spawn([binPath, ...args], {
+    detached: true,
+    stdio: spawnStdioWithDebugFd(["inherit", "inherit", "inherit"]),
+  });
+  const tree = registerProcessTree(proc);
+  let exitCode: number;
+  try {
+    exitCode = await proc.exited;
+  } finally {
+    tree.dispose();
+  }
+  log.debug(`exit=${exitCode} dt=${Math.round(performance.now() - startedAt)}ms args=${JSON.stringify(args)}`);
+  if (exitCode !== 0) {
+    throw new Error(`kesha-engine record exited with code ${exitCode}`);
+  }
+}
+
 export function parseLangResult(stdout: string): LangDetectResult | null {
   try {
     const parsed = JSON.parse(stdout);
@@ -263,17 +318,23 @@ export function parseLangResult(stdout: string): LangDetectResult | null {
   }
 }
 
-export async function detectAudioLanguageEngine(audioPath: string): Promise<LangDetectResult | null> {
+export async function detectAudioLanguageEngine(
+  audioPath: string,
+  opts: RunEngineOptions = {},
+): Promise<LangDetectResult | null> {
   if (!isEngineInstalled()) return null;
-  const { stdout, exitCode } = await runEngine(["detect-lang", audioPath]);
+  const { stdout, exitCode } = await runEngine(["detect-lang", audioPath], opts);
   if (exitCode !== 0) return null;
   return parseLangResult(stdout);
 }
 
-export async function detectTextLanguageEngine(text: string): Promise<LangDetectResult | null> {
+export async function detectTextLanguageEngine(
+  text: string,
+  opts: RunEngineOptions = {},
+): Promise<LangDetectResult | null> {
   if (text.trim().length === 0) return null;
   if (!isEngineInstalled()) return null;
-  const { stdout, exitCode } = await runEngine(["detect-text-lang", text]);
+  const { stdout, exitCode } = await runEngine(["detect-text-lang", text], opts);
   if (exitCode !== 0) return null;
   return parseLangResult(stdout);
 }

package/src/log.ts

@@ -34,8 +34,11 @@ export const log = {
   error: (msg: string) => console.error(pc.red(msg)),
 
   debugEnabled: false,
+  isDebugEnabled(): boolean {
+    return this.debugEnabled || envDebug();
+  },
   debug(msg: string): void {
-    if (this.debugEnabled || envDebug()) {
+    if (this.isDebugEnabled()) {
       // `[debug +Nms]` prefix sits on the CLI process's own timeline so
       // the reader can see when each line fired. The Rust engine emits
       // the same `+Nms` shape from `rust/src/debug.rs::trace_fmt`, but

package/src/process-tree.ts

@@ -0,0 +1,133 @@
+type ManagedSignal = "SIGINT" | "SIGTERM" | "SIGKILL";
+
+interface KillableProcess {
+  pid: number;
+  kill(signal?: ManagedSignal): void;
+}
+
+interface ActiveProcess {
+  pid: number;
+  kill(signal?: ManagedSignal): void;
+}
+
+const FORCE_KILL_GRACE_MS = 1_000;
+const SIGNAL_EXIT_BUFFER_MS = 50;
+const activeProcesses = new Set<ActiveProcess>();
+let signalHandlersInstalled = false;
+let pendingSignalCleanup:
+  | {
+      exitCode: number;
+      done: Promise<void>;
+    }
+  | null = null;
+
+export function engineAbortError(): Error {
+  const err = new Error("kesha-engine process aborted");
+  err.name = "AbortError";
+  return err;
+}
+
+export function registerProcessTree(proc: KillableProcess): {
+  dispose: () => void;
+  terminate: (signal?: ManagedSignal) => void;
+  forceKillAfterGrace: () => Timer;
+} {
+  const active: ActiveProcess = {
+    pid: proc.pid,
+    kill: (signal?: ManagedSignal) => terminateProcessTree(proc, signal),
+  };
+  activeProcesses.add(active);
+  ensureSignalHandlers();
+  return {
+    dispose: () => {
+      activeProcesses.delete(active);
+    },
+    terminate: (signal: ManagedSignal = "SIGTERM") => active.kill(signal),
+    forceKillAfterGrace: () => scheduleForceKill(active),
+  };
+}
+
+export function getPendingSignalExitCode(): number | null {
+  return pendingSignalCleanup?.exitCode ?? null;
+}
+
+export async function waitForPendingSignalCleanup(): Promise<number | null> {
+  if (!pendingSignalCleanup) return null;
+  await pendingSignalCleanup.done;
+  return pendingSignalCleanup.exitCode;
+}
+
+export function terminateProcessTree(proc: KillableProcess, signal: ManagedSignal = "SIGTERM"): void {
+  if (!Number.isFinite(proc.pid) || proc.pid <= 0) {
+    safeKillDirect(proc, signal);
+    return;
+  }
+
+  if (process.platform === "win32") {
+    const args = ["/PID", String(proc.pid), "/T"];
+    if (signal === "SIGKILL") args.push("/F");
+    try {
+      Bun.spawn(["taskkill", ...args], {
+        stdout: "ignore",
+        stderr: "ignore",
+      });
+      return;
+    } catch {
+      safeKillDirect(proc, signal);
+      return;
+    }
+  }
+
+  try {
+    process.kill(-proc.pid, signal);
+  } catch {
+    safeKillDirect(proc, signal);
+  }
+}
+
+function safeKillDirect(proc: KillableProcess, signal: ManagedSignal): void {
+  try {
+    proc.kill(signal);
+  } catch {
+    // The process may already have exited between the caller deciding to clean
+    // it up and the signal reaching the kernel.
+  }
+}
+
+function scheduleForceKill(proc: ActiveProcess, opts: { ref?: boolean } = {}): Timer {
+  const timer = setTimeout(() => proc.kill("SIGKILL"), FORCE_KILL_GRACE_MS);
+  if (opts.ref !== true) timer.unref?.();
+  return timer;
+}
+
+function ensureSignalHandlers(): void {
+  if (signalHandlersInstalled) return;
+  signalHandlersInstalled = true;
+  process.on("SIGINT", () => terminateActiveProcessTrees("SIGINT", 130));
+  process.on("SIGTERM", () => terminateActiveProcessTrees("SIGTERM", 143));
+}
+
+function terminateActiveProcessTrees(signal: ManagedSignal, exitCode: number): void {
+  const processes = [...activeProcesses];
+  process.exitCode = exitCode;
+
+  for (const proc of processes) {
+    proc.kill(signal);
+    scheduleForceKill(proc, { ref: true });
+  }
+
+  if (pendingSignalCleanup) {
+    return;
+  }
+
+  const delayMs = processes.length > 0
+    ? FORCE_KILL_GRACE_MS + SIGNAL_EXIT_BUFFER_MS
+    : SIGNAL_EXIT_BUFFER_MS;
+  let resolveDone!: () => void;
+  const done = new Promise<void>((resolve) => {
+    resolveDone = resolve;
+  });
+  pendingSignalCleanup = { exitCode, done };
+  setTimeout(resolveDone, delayMs);
+  done.then(() => process.exit(exitCode));
+}

package/src/shell-artifacts.ts

@@ -4,6 +4,7 @@ import { doctorCommand } from "./cli/doctor";
 import { installCommand } from "./cli/install";
 import { mainCommand } from "./cli/main";
 import { manpageCommand } from "./cli/manpage";
+import { recordCommand } from "./cli/record";
 import { sayCommand } from "./cli/say";
 import { statsCommand } from "./cli/stats";
 import { statusCommand } from "./cli/status";
@@ -45,6 +46,7 @@ const CLI_COMMANDS: CliCommand[] = [
   { name: "doctor", command: doctorCommand },
   { name: "install", command: installCommand },
   { name: "manpage", command: manpageCommand },
+  { name: "record", command: recordCommand },
   { name: "say", command: sayCommand },
   { name: "stats", command: statsCommand },
   { name: "status", command: statusCommand },
@@ -154,7 +156,6 @@ ${cases}
 }
 
 complete -F _kesha_completion kesha
-complete -F _kesha_completion parakeet
 `;
 }
 
@@ -183,7 +184,7 @@ function renderZsh(model: ArtifactModel): string {
     })
     .join("\n");
 
-  return `#compdef kesha parakeet
+  return `#compdef kesha
 # zsh completion for kesha.
 
 _kesha() {
@@ -225,24 +226,21 @@ function renderFishOption(bin: string, condition: string, option: CliOption): st
 }
 
 function renderFish(model: ArtifactModel): string {
-  const bins = ["kesha", "parakeet"];
   const lines = ["# fish completion for kesha."];
 
-  for (const bin of bins) {
-    lines.push(`complete -c ${bin} -f`);
-    for (const command of model.commands) {
-      lines.push(
-        `complete -c ${bin} -n '__fish_use_subcommand' -a '${command.name}' -d '${fishEscape(command.description)}'`,
-      );
-    }
-    for (const option of [...ROOT_BUILT_INS, ...model.root.options]) {
-      lines.push(renderFishOption(bin, " -n '__fish_use_subcommand'", option));
-    }
-    for (const command of model.commands) {
-      const condition = ` -n '__fish_seen_subcommand_from ${command.name}'`;
-      for (const option of [...HELP_OPTIONS, ...command.options]) {
-        lines.push(renderFishOption(bin, condition, option));
-      }
+  lines.push("complete -c kesha -f");
+  for (const command of model.commands) {
+    lines.push(
+      `complete -c kesha -n '__fish_use_subcommand' -a '${command.name}' -d '${fishEscape(command.description)}'`,
+    );
+  }
+  for (const option of [...ROOT_BUILT_INS, ...model.root.options]) {
+    lines.push(renderFishOption("kesha", " -n '__fish_use_subcommand'", option));
+  }
+  for (const command of model.commands) {
+    const condition = ` -n '__fish_seen_subcommand_from ${command.name}'`;
+    for (const option of [...HELP_OPTIONS, ...command.options]) {
+      lines.push(renderFishOption("kesha", condition, option));
     }
   }
 

package/src/synth.ts

@@ -6,6 +6,7 @@ import {
   type EngineCapabilities,
 } from "./engine";
 import { log } from "./log";
+import { registerProcessTree } from "./process-tree";
 
 /**
  * Wire format for the synthesized audio. Matches the engine's `--format` flag.
@@ -125,8 +126,10 @@ export async function say(opts: SayOptions): Promise<Uint8Array> {
   const startedAt = performance.now();
   log.debug(`spawn ${getEngineBinPath()} ${args.join(" ")} (text: ${opts.text?.length ?? 0} chars)`);
   const proc = Bun.spawn([getEngineBinPath(), ...args], {
+    detached: true,
     stdio: spawnStdioWithDebugFd(["pipe", "pipe", "pipe"]),
   });
+  const tree = registerProcessTree(proc);
   // The `stdio: [...]` form widens stdin/stdout/stderr into a union
   // (Bun.spawn can't infer that indices 0/1/2 are always "pipe" given
   // the helper's return type). All three are guaranteed `FileSink` /
@@ -143,11 +146,18 @@ export async function say(opts: SayOptions): Promise<Uint8Array> {
     await stdin.end();
   }
 
-  const [stdoutBuf, stderrText, exitCode] = await Promise.all([
-    new Response(stdout).arrayBuffer(),
-    new Response(stderr).text(),
-    proc.exited,
-  ]);
+  let stdoutBuf: ArrayBuffer;
+  let stderrText: string;
+  let exitCode: number;
+  try {
+    [stdoutBuf, stderrText, exitCode] = await Promise.all([
+      new Response(stdout).arrayBuffer(),
+      new Response(stderr).text(),
+      proc.exited,
+    ]);
+  } finally {
+    tree.dispose();
+  }
 
   log.debug(`exit=${exitCode} dt=${Math.round(performance.now() - startedAt)}ms bytes=${stdoutBuf.byteLength}`);
 

package/src/transcribe.ts

@@ -14,6 +14,8 @@ export interface TranscribeOptions {
   silent?: boolean;
   /** Silero VAD preprocessing selector. Defaults to `"auto"`. */
   vad?: VadMode;
+  /** Cancel any in-flight engine subprocess for this transcription. */
+  signal?: AbortSignal;
   /** Request timestamped transcript segments from the engine. */
   timestamps?: boolean;
   /** Request speaker labels in transcript segments (#199). Implies `timestamps`.
@@ -56,10 +58,11 @@ export async function transcribeWithSegments(
   if (opts.timestamps || opts.speakers) {
     return transcribeEngineWithSegments(audioPath, {
       vad: opts.vad,
+      signal: opts.signal,
       speakers: opts.speakers,
     });
   }
 
-  const text = await transcribeEngine(audioPath, { vad: opts.vad });
+  const text = await transcribeEngine(audioPath, { vad: opts.vad, signal: opts.signal });
   return { text, segments: [] };
 }