@drakulavich/kesha-voice-kit 1.27.0-alpha.1 → 1.27.0

package/README.md

@@ -45,7 +45,7 @@ kesha install        # ~2.5 GB on Linux/Windows; ~0.6 GB on Apple Silicon, whose
 kesha audio.ogg      # transcript to stdout
 ```
 
-Prefer Homebrew, `.deb`/`.rpm`, Docker, or Nix? See [Other install methods](#other-install-methods).
+Prefer Homebrew, Docker, or Nix? See [Other install methods](#other-install-methods).
 Air-gapped or behind a corporate mirror? See [docs/model-mirror.md](docs/model-mirror.md).
 
 ## Speech-to-text
@@ -74,7 +74,7 @@ $ kesha freedom.ogg tahiti.ogg
 
 - **Record from the mic (macOS):** `kesha record --out hello.wav` writes microphone audio to a WAV file (`kesha hello.wav` transcribes it). macOS prompts for microphone access on first use — grant it under System Settings → Privacy & Security → Microphone if it was denied. On Linux/Windows or headless boxes, pass any existing audio file straight to `kesha` instead.
 - **Long / silence-heavy audio:** install VAD (`kesha install --vad`); Kesha auto-uses it past 120 s. Without VAD, long audio falls back to fixed ASR chunks. See [docs/vad.md](docs/vad.md).
-- **Speaker diarization** (darwin-arm64): `kesha install --diarize`, then `kesha --json --vad --speakers meeting.m4a` stamps each segment with a `speaker` id. Linux/Windows return a clear "darwin-arm64 only" error ([#199](https://github.com/drakulavich/kesha-voice-kit/issues/199)).
+- **Speaker diarization** (darwin-arm64): `kesha install --diarize` (which installs VAD too), then `kesha --json --speakers meeting.m4a` stamps each segment with a `speaker` id. `--speakers` engages VAD windowing itself at any duration, so it cannot be combined with `--no-vad`. Linux/Windows return a clear "darwin-arm64 only" error ([#199](https://github.com/drakulavich/kesha-voice-kit/issues/199)).
 
 ## Text-to-speech
 
@@ -117,7 +117,7 @@ Full per-file breakdown (Russian + English): [BENCHMARK.md](BENCHMARK.md).
 All of these install the Bun CLI wrapper; engine + models still download explicitly via `kesha install`.
 
 - **Homebrew** — `brew install drakulavich/tap/kesha-voice-kit` · [docs/homebrew.md](docs/homebrew.md)
-- **Linux packages** (`.deb`/`.rpm`, x64) — [docs/linux-packages.md](docs/linux-packages.md)
+- **Linux packages** (`.deb`/`.rpm`, x64) — not currently published, see [docs/linux-packages.md](docs/linux-packages.md)
 - **Docker** (GHCR image) — [docs/docker.md](docs/docker.md)
 - **Nix** (`aarch64-darwin` / `x86_64-linux`) — `nix run github:drakulavich/kesha-voice-kit -- install` · [docs/nix-install.md](docs/nix-install.md)
 - **Shell completions + manpage** — `kesha completions bash|zsh|fish` and `kesha manpage` print the packaged files to install wherever your shell expects them.

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kesha-voice-kit
-description: Local multilingual voice toolkit — speech-to-text (STT), text-to-speech (TTS), and language detection. Runs entirely offline on Apple Silicon, Linux, and Windows. No API keys, no cloud. NVIDIA Parakeet TDT for STT across 25 European languages, Kokoro-82M + Vosk-TTS for TTS, plus macOS AVSpeechSynthesizer for ~180 system voices with zero install.
+description: Local multilingual voice toolkit — speech-to-text (STT), text-to-speech (TTS), speaker diarization, and language detection, over a CLI or an MCP server. Runs entirely offline on Apple Silicon, Linux, and Windows. No API keys, no cloud. NVIDIA Parakeet TDT for STT across 25 European languages, Kokoro-82M + Vosk-TTS for TTS in 9 languages, plus macOS AVSpeechSynthesizer for ~180 system voices with zero install.
 emoji: 🎙️
 
 requires:
@@ -17,7 +17,7 @@ install:
 
 Local voice toolkit: transcribe voice messages to text, synthesize speech, detect language of audio or text. Fully offline after `kesha install`. No API keys, no per-minute billing.
 
-**Trigger keywords for when to use this skill:** voice message, voice memo, voice note, .ogg, .opus, .wav, .mp3, audio file, transcribe, transcription, speech-to-text, STT, text-to-speech, TTS, synthesize speech, say, telegram voice note, whatsapp voice note, ogg-opus, opus, multilingual voice, multilingual ASR, language detection, offline voice, privacy, Apple Silicon, CoreML.
+**Trigger keywords for when to use this skill:** voice message, voice memo, voice note, .ogg, .opus, .wav, .mp3, audio file, transcribe, transcription, speech-to-text, STT, text-to-speech, TTS, synthesize speech, say, telegram voice note, whatsapp voice note, ogg-opus, opus, multilingual voice, multilingual ASR, language detection, speaker diarization, who said what, meeting transcript, MCP server, offline voice, privacy, Apple Silicon, CoreML.
 
 ## When to use
 
@@ -107,6 +107,16 @@ When invoking Kesha manually from an OpenClaw flow, write OGG/Opus into an OpenC
 
 Do not configure OpenClaw Telegram TTS as `kesha say "<text>" > reply.wav`; that creates a WAV file and will not render as a native Telegram voice note.
 
+## MCP server
+
+`kesha mcp` serves the same capabilities over Model Context Protocol (stdio), exposing `transcribe_audio`, `synthesize_speech`, `list_voices`, and `list_languages` to any MCP client:
+
+```json
+{ "mcpServers": { "kesha": { "command": "kesha", "args": ["mcp"] } } }
+```
+
+Models are never auto-downloaded — tools fail with a `kesha install` / `kesha install --tts` hint when missing. Full client setup (Claude Code, Claude Desktop, Codex, Cursor): [docs/mcp.md](docs/mcp.md).
+
 ## STT: transcribe audio
 
 ```bash
@@ -138,12 +148,12 @@ Each segment has `start`, `end`, and `text` fields. `--timestamps` is available
 **Speaker diarization** (darwin-arm64, post-v1.12.0). Add `--speakers` to label each segment with a cluster ID — useful for transcribing multi-person calls / meetings:
 
 ```bash
-kesha install --diarize                                  # one-time, ~245MB
-kesha --json --vad --speakers meeting.m4a > out.json
+kesha install --diarize                                  # one-time, ~245MB (installs VAD too)
+kesha --json --speakers meeting.m4a > out.json           # --speakers engages VAD itself
 jq '.[0].segments[] | "\(.speaker)\t\(.text)"' out.json
 ```
 
-Each `segment.speaker` is a number (cluster id, stable within one file). On Linux / Windows the engine returns a clear "currently darwin-arm64 only" error — see [#199](https://github.com/drakulavich/kesha-voice-kit/issues/199).
+Each `segment.speaker` is a number (cluster id, stable within one file). `--speakers` forces VAD windowing at any duration, so it cannot be combined with `--no-vad`. On Linux / Windows the engine returns a clear "currently darwin-arm64 only" error — see [#199](https://github.com/drakulavich/kesha-voice-kit/issues/199).
 
 **Formats:** .ogg, .opus, .mp3, .m4a, .wav, .flac, .webm — decoded via symphonia, no ffmpeg required.
 
@@ -207,10 +217,11 @@ bun add -g @drakulavich/kesha-voice-kit          # global CLI install (always fi
 kesha init
 
 # For agents and CI: explicit, scriptable install commands
-kesha install                                    # engine only (~350 MB)
-kesha install --tts                              # + Kokoro + Vosk-TTS RU (~990 MB more)
+kesha install                                    # engine only — ~0.6 GB on Apple Silicon, ~2.5 GB on Linux/Windows
+kesha install --plan                             # preview exact download/disk sizes first — downloads nothing
+kesha install --tts                              # + English Kokoro; add langs additively: --tts en ru es
 kesha install --tts --vad                        # + Silero VAD (long-audio chunking)
-kesha install --tts --vad --diarize              # + speaker diarization (darwin-arm64 only)
+kesha install --tts --diarize                    # + speaker diarization, VAD included (darwin-arm64 only)
 ```
 
 Kesha's runtime error/warning messages adapt to the same split: when `kesha` is invoked from a TTY, hints suggest `kesha init`; when stderr is piped (CI logs, OpenClaw, agent subprocess), hints suggest the equivalent `kesha install [...flags]`. Both run the same install code under the hood — pick the one your caller is.
@@ -223,7 +234,7 @@ No system deps — English G2P is embedded (`misaki-rs`); Russian G2P is bundled
 
 **Speech-to-text (25):** Bulgarian, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Latvian, Lithuanian, Maltese, Polish, Portuguese, Romanian, Russian, Slovak, Slovenian, Spanish, Swedish, Ukrainian.
 
-**Text-to-speech:** English (Kokoro-82M; FluidAudio CoreML on darwin-arm64, ONNX elsewhere), Russian (Vosk-TTS, 5 baked-in speakers — default `ru-vosk-m02`), plus any macOS system voice via `--voice macos-*`.
+**Text-to-speech (9):** English (Kokoro-82M; FluidAudio CoreML on darwin-arm64, ONNX elsewhere), Russian (Vosk-TTS, 5 baked-in speakers — default `ru-vosk-m02`), Spanish, French, Italian, Portuguese (Kokoro — CharsiuG2P on ONNX builds, FluidAudio G2P on darwin-arm64), plus Hindi, Japanese, Chinese (Kokoro, darwin-arm64 only). `hi`/`ja` accept romanized Latin input only; native Devanagari and kana/kanji are rejected with `E_SCRIPT_UNSUPPORTED` — see [#492](https://github.com/drakulavich/kesha-voice-kit/issues/492). Any macOS system voice is also available via `--voice macos-*`.
 
 ## Performance
 

package/completions/kesha.fish

@@ -19,14 +19,14 @@ complete -c kesha -n '__fish_use_subcommand' -s v -d 'Show version'
 complete -c kesha -n '__fish_use_subcommand' -l json -d 'Output results as JSON'
 complete -c kesha -n '__fish_use_subcommand' -l toon -d 'Output results as TOON (compact, LLM-friendly encoding of the same data as --json)'
 complete -c kesha -n '__fish_use_subcommand' -l timestamps -d 'Include timestamped transcript segments in JSON/TOON output'
-complete -c kesha -n '__fish_use_subcommand' -l speakers -d 'Include speaker labels in segments. Needs --json/--toon and darwin-arm64; run `kesha install --diarize` first. Implies --timestamps.'
+complete -c kesha -n '__fish_use_subcommand' -l speakers -d 'Include speaker labels in segments. Needs --json/--toon and darwin-arm64; run `kesha install --diarize` first (it installs VAD too). Implies --timestamps, and engages VAD windowing at any duration (so it cannot be combined with --no-vad).'
 complete -c kesha -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 kesha -n '__fish_use_subcommand' -l verbose -d 'Show language detection details'
 complete -c kesha -n '__fish_use_subcommand' -l format -r -d 'Output format: transcript | json | toon (long-form alias for --json / --toon)'
 complete -c kesha -n '__fish_use_subcommand' -l lang -r -d 'Expected language code, e.g. en or en-us (see docs/languages.md); 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 'Force full-file ASR for short/medium files; long audio fails early'
+complete -c kesha -n '__fish_use_subcommand' -l no-vad -d 'Force full-file ASR for short/medium files; long audio fails early. Incompatible with --speakers'
 complete -c kesha -n '__fish_use_subcommand' -l quiet -d 'Suppress progress output; print only results and errors'
 complete -c kesha -n '__fish_use_subcommand' -l no-color -d 'Disable ANSI colors (also via NO_COLOR=1; auto-off when CI=true)'
 complete -c kesha -n '__fish_seen_subcommand_from completions' -l help -d 'Show help'

package/completions/kesha.zsh

@@ -27,14 +27,14 @@ _kesha() {
       '--json[Output results as JSON]' \
       '--toon[Output results as TOON (compact, LLM-friendly encoding of the same data as --json)]' \
       '--timestamps[Include timestamped transcript segments in JSON/TOON output]' \
-      '--speakers[Include speaker labels in segments. Needs --json/--toon and darwin-arm64; run `kesha install --diarize` first. Implies --timestamps.]' \
+      '--speakers[Include speaker labels in segments. Needs --json/--toon and darwin-arm64; run `kesha install --diarize` first (it installs VAD too). Implies --timestamps, and engages VAD windowing at any duration (so it cannot be combined with --no-vad).]' \
       '--include-errors[With --json, output { results, errors } so scripts can read per-file failures without parsing stderr]' \
       '--verbose[Show language detection details]' \
       '--format=[Output format: transcript | json | toon (long-form alias for --json / --toon)]:format:' \
       '--lang=[Expected language code, e.g. en or en-us (see docs/languages.md); 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[Force full-file ASR for short/medium files; long audio fails early]' \
+      '--no-vad[Force full-file ASR for short/medium files; long audio fails early. Incompatible with --speakers]' \
       '--quiet[Suppress progress output; print only results and errors]' \
       '--no-color[Disable ANSI colors (also via NO_COLOR=1; auto-off when CI=true)]'
     else
@@ -139,14 +139,14 @@ _kesha() {
       '--json[Output results as JSON]' \
       '--toon[Output results as TOON (compact, LLM-friendly encoding of the same data as --json)]' \
       '--timestamps[Include timestamped transcript segments in JSON/TOON output]' \
-      '--speakers[Include speaker labels in segments. Needs --json/--toon and darwin-arm64; run `kesha install --diarize` first. Implies --timestamps.]' \
+      '--speakers[Include speaker labels in segments. Needs --json/--toon and darwin-arm64; run `kesha install --diarize` first (it installs VAD too). Implies --timestamps, and engages VAD windowing at any duration (so it cannot be combined with --no-vad).]' \
       '--include-errors[With --json, output { results, errors } so scripts can read per-file failures without parsing stderr]' \
       '--verbose[Show language detection details]' \
       '--format=[Output format: transcript | json | toon (long-form alias for --json / --toon)]:format:' \
       '--lang=[Expected language code, e.g. en or en-us (see docs/languages.md); 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[Force full-file ASR for short/medium files; long audio fails early]' \
+      '--no-vad[Force full-file ASR for short/medium files; long audio fails early. Incompatible with --speakers]' \
       '--quiet[Suppress progress output; print only results and errors]' \
       '--no-color[Disable ANSI colors (also via NO_COLOR=1; auto-off when CI=true)]'
       ;;

package/man/kesha.1

@@ -58,7 +58,7 @@ Output results as TOON (compact, LLM\-friendly encoding of the same data as \-\-
 Include timestamped transcript segments in JSON/TOON output
 .TP
 .B \-\-speakers
-Include speaker labels in segments. Needs \-\-json/\-\-toon and darwin\-arm64; run `kesha install \-\-diarize` first. Implies \-\-timestamps.
+Include speaker labels in segments. Needs \-\-json/\-\-toon and darwin\-arm64; run `kesha install \-\-diarize` first (it installs VAD too). Implies \-\-timestamps, and engages VAD windowing at any duration (so it cannot be combined with \-\-no\-vad).
 .TP
 .B \-\-include\-errors
 With \-\-json, output { results, errors } so scripts can read per\-file failures without parsing stderr
@@ -79,7 +79,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
-Force full\-file ASR for short/medium files; long audio fails early
+Force full\-file ASR for short/medium files; long audio fails early. Incompatible with \-\-speakers
 .TP
 .B \-\-quiet
 Suppress progress output; print only results and errors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.27.0-alpha.1",
+  "version": "1.27.0",
   "description": "Give your tools a voice — speech to text and back, 25 languages, up to ~19× faster than Whisper. On your machine.",
   "type": "module",
   "bin": {
@@ -40,7 +40,7 @@
     }
   },
   "keshaEngine": {
-    "version": "1.24.7"
+    "version": "1.24.9"
   },
   "scripts": {
     "test": "bun test --timeout 30000",

package/src/cli/init.ts

@@ -4,10 +4,10 @@ import { renderInstallPlan } from "../install-plan";
 import { log } from "../log";
 import { getEngineCapabilities } from "../engine";
 import {
+  installableTtsLangs,
   performInstall,
   resolveBackendFlag,
   resolveNoCacheFlag,
-  TTS_LANG_FALLBACK,
   unavailableBackendError,
 } from "./install";
 import type { SharedInstallArgs } from "./types";
@@ -40,8 +40,10 @@ function exitIfCancelled<T>(answer: T | symbol): T {
 }
 
 async function promptTtsLangs(preselect: string[]): Promise<string[]> {
-  const caps = await getEngineCapabilities();
-  const supported = caps?.tts?.languages.map((l) => l.code) ?? TTS_LANG_FALLBACK;
+  // A corrupt engine must leave init offering the fallback list rather than aborting the
+  // guided setup that would replace it (#770).
+  const caps = await getEngineCapabilities().catch(() => null);
+  const supported = caps?.tts?.languages.map((l) => l.code) ?? installableTtsLangs();
   const selected = await multiselect({
     message:
       "Select TTS languages to install (space to toggle, enter to confirm; none = skip TTS):",
@@ -113,8 +115,9 @@ export function initSuggestionCommands(
     { ...selection, ttsLangs: ["en"], vad: true, diarize: false },
   ];
 
+  // #768: --diarize installs VAD on its own, so no explicit --vad here.
   if (canDiarize) {
-    variants.push({ ...selection, ttsLangs: [], vad: true, diarize: true });
+    variants.push({ ...selection, ttsLangs: [], vad: false, diarize: true });
   }
 
   const seen = new Set<string>();
@@ -143,7 +146,7 @@ export function renderInitOverview(canDiarize = canInstallDiarizeOnPlatform()):
     "  - Text-to-speech: enables `kesha say` with Kokoro English voices (more languages via `kesha install --tts <langs>`).",
     "  - VAD: skips silence in long audio and improves meeting, lecture, and podcast transcripts (~2.3MB).",
     canDiarize
-      ? "  - Speaker diarization: labels speakers in JSON/TOON transcript segments (~245MB, darwin-arm64)."
+      ? "  - Speaker diarization: labels speakers in JSON/TOON transcript segments (~245MB, darwin-arm64; installs VAD too, since labels attach to VAD segments)."
       : "  - Speaker diarization: labels speakers, but the install is currently darwin-arm64 only.",
     "",
     "Nothing downloads until you confirm the final install plan.",
@@ -163,7 +166,10 @@ export async function promptInitSelection(
   const vad = await prompt("Install VAD for long or silence-heavy audio?", args.vad);
   let diarize = false;
   if (canDiarize) {
-    diarize = await prompt("Install speaker diarization for `--speakers`?", args.diarize);
+    diarize = await prompt(
+      "Install speaker diarization for `--speakers`? (installs VAD as well)",
+      args.diarize,
+    );
   } else if (args.diarize) {
     log.warn("--diarize is currently darwin-arm64 only; omitting it from the interactive install.");
   }

package/src/cli/install.ts

@@ -2,7 +2,8 @@ import { defineCommand } from "citty";
 import { errorMessage } from "../error-utils";
 import { installEngine } from "../engine-install";
 import { engineTarget } from "../engine-targets";
-import { getEngineBinPath, getEngineCapabilities } from "../engine";
+import { isDarwinArm64 } from "../fluid-kokoro-cache";
+import { getEngineBinPath, getEngineCapabilities, type EngineCapabilities } from "../engine";
 import { renderInstallPlan } from "../install-plan";
 import { maybeAskForStar } from "../star";
 import { log } from "../log";
@@ -19,12 +20,24 @@ export interface InstallCommandArgs extends SharedInstallArgs {
   engineVersion?: string;
 }
 
+/** TTS languages every build installs. */
+const TTS_LANGS_EVERYWHERE = ["en", "es", "fr", "it", "pt", "ru"];
+
+/** hi/ja/zh need FluidAudio's ANE Kokoro, which only the darwin-arm64 engine is built with. */
+const DARWIN_ARM64_ONLY_TTS_LANGS = ["hi", "ja", "zh"];
+
 /**
- * TTS languages installable on EVERY build, used when the engine binary isn't
- * installed yet (capabilities unavailable). hi/ja/zh are darwin-arm64-only and
- * can't be assumed without capabilities, so they're excluded here.
+ * What `--tts` may name when the Engine cannot be asked. Without it, a bogus code is only
+ * caught by the engine that a full download had to install first (#770).
  */
-export const TTS_LANG_FALLBACK = ["en", "es", "fr", "it", "pt", "ru"];
+export function installableTtsLangs(
+  platform = process.platform,
+  arch = process.arch,
+): string[] {
+  return isDarwinArm64(platform, arch)
+    ? [...TTS_LANGS_EVERYWHERE, ...DARWIN_ARM64_ONLY_TTS_LANGS]
+    : TTS_LANGS_EVERYWHERE;
+}
 
 export interface TtsArgInput {
   tts: boolean;
@@ -34,9 +47,9 @@ export interface TtsArgInput {
 /**
  * Resolve the requested TTS language list. Bare `--tts` defaults to English.
  * Positionals without `--tts` are an error. When `supported` is provided,
- * unsupported codes are a hard error (nothing downloads); when it's undefined
- * (engine not yet installed, capabilities unavailable) the check is skipped and
- * the engine validates authoritatively at download time.
+ * unsupported codes are a hard error (nothing downloads); the CLI passes the
+ * Engine's own list when it has one and `installableTtsLangs()` otherwise, and
+ * the installed Engine re-validates authoritatively at download time.
  */
 export function resolveTtsLangs(input: TtsArgInput, supported: string[] | undefined): string[] {
   if (!input.tts) {
@@ -90,6 +103,23 @@ export function resolveNoCacheFlag(
   );
 }
 
+/**
+ * Capabilities for `--tts` validation, tolerating an engine that cannot be spawned (#770).
+ *
+ * A corrupt or wrong-arch binary used to throw here and kill the command before the
+ * re-download that repairs it. Without capabilities the language codes simply go
+ * unvalidated locally — the freshly installed engine rejects unsupported ones at
+ * download time, which is authoritative anyway.
+ */
+export async function probeCapabilitiesForInstall(): Promise<EngineCapabilities | null> {
+  try {
+    return await getEngineCapabilities();
+  } catch (err) {
+    log.debug(`capabilities probe failed before install: ${errorMessage(err)}`);
+    return null;
+  }
+}
+
 export type BackendSelection =
   | { ok: true; backend: string | undefined }
   | { ok: false; error: string };
@@ -274,8 +304,8 @@ export const installCommand = defineCommand({
     }
     const backend = resolveBackendFlag(args.coreml, args.onnx);
     const positionals = (args._ ?? []).map(String);
-    const caps = await getEngineCapabilities();
-    const supported = caps?.tts?.languages.map((l) => l.code);
+    const caps = await probeCapabilitiesForInstall();
+    const supported = caps?.tts?.languages.map((l) => l.code) ?? installableTtsLangs();
     let ttsLangs: string[];
     try {
       ttsLangs = resolveTtsLangs({ tts: args.tts === true, positionals }, supported);

package/src/cli/main.ts

@@ -175,6 +175,16 @@ export function validateTranscribeArgs(
   if (args.speakers && !(wantsJson || wantsToon)) {
     return { ok: false, error: "--speakers requires --json, --toon, or --format {json,toon}." };
   }
+  // #768: diarization labels VAD-windowed segments, so --no-vad leaves nothing to label.
+  if (args.speakers && noVad) {
+    return {
+      ok: false,
+      error:
+        "--speakers cannot be combined with --no-vad: speaker labels attach to VAD-windowed " +
+        "speech segments, and --no-vad leaves the whole file as one segment. Drop --no-vad " +
+        "(VAD engages automatically for --speakers), or drop --speakers.",
+    };
+  }
   if (args["include-errors"] && !wantsJson) {
     return { ok: false, error: "--include-errors requires --json or --format json." };
   }
@@ -437,7 +447,7 @@ export function createMainCommand(context: CliContext = { quiet: false, disableC
       },
       speakers: {
         type: "boolean",
-        description: "Include speaker labels in segments. Needs --json/--toon and darwin-arm64; run `kesha install --diarize` first. Implies --timestamps.",
+        description: "Include speaker labels in segments. Needs --json/--toon and darwin-arm64; run `kesha install --diarize` first (it installs VAD too). Implies --timestamps, and engages VAD windowing at any duration (so it cannot be combined with --no-vad).",
         default: false,
       },
       "include-errors": {
@@ -470,7 +480,7 @@ export function createMainCommand(context: CliContext = { quiet: false, disableC
       },
       "no-vad": {
         type: "boolean",
-        description: "Force full-file ASR for short/medium files; long audio fails early",
+        description: "Force full-file ASR for short/medium files; long audio fails early. Incompatible with --speakers",
         default: false,
       },
       // quiet and no-color are resolved before citty in dispatch.ts (so they

package/src/cli/say.ts

@@ -25,10 +25,9 @@ async function autoRouteVoice(text: string): Promise<string | undefined> {
  * Resolve the voice for `kesha say`. Precedence: explicit `--voice` > explicit
  * `--lang` (route by the stated language, skipping detection — also the path on
  * Linux/Windows where text-language detection is unavailable) > macOS
- * text-language auto-detection > engine default (`undefined`). A `--lang` with
- * no mapped voice (an unsupported language, or French which has no male Kokoro
- * voice) resolves to `undefined` (engine default) rather than re-running
- * detection — the user stated the language explicitly.
+ * text-language auto-detection > engine default (`undefined`). A `--lang` the
+ * build has no voice for resolves to `undefined` (engine default) rather than
+ * re-running detection — the user stated the language explicitly.
  */
 export async function resolveSayVoice(
   explicitVoice: string | undefined,

package/src/doctor.ts

@@ -8,6 +8,7 @@ import {
   isEngineInstalled,
   type EngineCapabilities,
 } from "./engine";
+import { probeExecutable } from "./engine-health";
 import { readInstalledEngineVersion } from "./engine-version-marker";
 import { keshaCacheDir } from "./paths";
 import { engineVersion, packageName, packageVersion } from "./package-info";
@@ -51,6 +52,8 @@ interface CacheComponent extends PathSummary {
 interface OptionalComponent extends PathSummary {
   name: string;
   note?: string;
+  /** Binaries only: whether the file actually executes. Absent for model directories. */
+  runnable?: boolean;
 }
 
 type DoctorDiagnosticLogStatus = DiagnosticLogStatus & { error?: string };
@@ -88,6 +91,8 @@ export interface DoctorReport {
     versionMarker: string | null;
     pinnedVersion: string;
     versionState: EngineVersionState;
+    /** False when the binary is present but the OS refuses to run it (#770). */
+    runnable: boolean;
     capabilities: EngineCapabilities | null;
     probeError: string | null;
   };
@@ -197,8 +202,15 @@ async function collectEngine(redact: boolean): Promise<DoctorReport["engine"]> {
   const installed = isEngineInstalled();
   let capabilities: EngineCapabilities | null = null;
   let probeError: string | null = null;
-
-  if (installed) {
+  // A truncated download exists, so `installed` alone would report a bricked engine as
+  // healthy; probing the loader separates that from an old engine with no capabilities JSON.
+  const health = installed
+    ? await probeExecutable(binPath, ["--version"])
+    : ({ status: "missing" } as const);
+
+  if (health.status === "unusable") {
+    probeError = `binary is present but does not run (${health.detail}); re-run \`kesha install\``;
+  } else if (installed) {
     try {
       capabilities = await getEngineCapabilities();
       if (!capabilities) probeError = "capabilities probe returned no data";
@@ -215,6 +227,7 @@ async function collectEngine(redact: boolean): Promise<DoctorReport["engine"]> {
     versionMarker,
     pinnedVersion: engineVersion,
     versionState: engineVersionState(versionMarker, engineVersion),
+    runnable: health.status === "ok",
     capabilities,
     probeError: redactString("probeError", probeError, redact),
   };
@@ -269,10 +282,27 @@ function collectCache(
   };
 }
 
-function collectOptionalComponents(
+const SIDECAR_COMPONENTS = [
+  { name: "AVSpeech sidecar", note: "macOS voices", file: "say-avspeech" },
+  { name: "Text language sidecar", note: "darwin text language fast path", file: "kesha-textlang" },
+];
+
+/** Reporting a truncated sidecar as "installed" is a false clean — spawn it instead (#770). */
+async function sidecarComponent(
+  spec: (typeof SIDECAR_COMPONENTS)[number],
+  sidecarDir: string,
+): Promise<OptionalComponent> {
+  const summary = pathSummary(join(sidecarDir, spec.file));
+  const base = { name: spec.name, note: spec.note, ...summary };
+  if (!summary.exists) return base;
+  const health = await probeExecutable(summary.path);
+  return { ...base, runnable: health.status === "ok" };
+}
+
+async function collectOptionalComponents(
   redact: boolean,
   fluidKokoro: FluidKokoroCacheInfo,
-): OptionalComponent[] {
+): Promise<OptionalComponent[]> {
   const cache = keshaCacheDir();
   const sidecarDir = dirname(getEngineBinPath());
   const components: OptionalComponent[] = [
@@ -311,16 +341,7 @@ function collectOptionalComponents(
       note: "enabled with `kesha install --diarize` (darwin-arm64); runs in-engine",
       ...pathSummary(join(cache, "models/diarize")),
     },
-    {
-      name: "AVSpeech sidecar",
-      note: "macOS voices",
-      ...pathSummary(join(sidecarDir, "say-avspeech")),
-    },
-    {
-      name: "Text language sidecar",
-      note: "darwin text language fast path",
-      ...pathSummary(join(sidecarDir, "kesha-textlang")),
-    },
+    ...(await Promise.all(SIDECAR_COMPONENTS.map((spec) => sidecarComponent(spec, sidecarDir)))),
   ];
   return components.map((component) => redactComponent(component, redact));
 }
@@ -396,15 +417,23 @@ export async function collectDoctorReport(
     },
     engine,
     cache: collectCache(redact, fluidKokoro, engine.capabilities?.backend),
-    optionalComponents: collectOptionalComponents(redact, fluidKokoro),
+    optionalComponents: await collectOptionalComponents(redact, fluidKokoro),
     stats: collectStats(redact),
     diagnosticLogs: collectDiagnosticLogs(redact),
     env: collectEnv(redact),
   };
 }
 
-function formatInstalled(installed: boolean): string {
-  return installed ? "installed" : "missing";
+const CORRUPT_STATE = "installed but not executable (corrupt) - re-run `kesha install`";
+
+function formatComponentState(component: OptionalComponent): string {
+  if (!component.exists) return "missing";
+  return component.runnable === false ? CORRUPT_STATE : "installed";
+}
+
+function formatEngineBinaryState(engine: DoctorReport["engine"]): string {
+  if (!engine.installed) return "missing";
+  return engine.runnable ? "installed" : CORRUPT_STATE;
 }
 
 function formatVersionState(engine: DoctorReport["engine"]): string {
@@ -441,7 +470,7 @@ function formatOptionalSection(components: DoctorReport["optionalComponents"]):
   const lines = ["", "Optional components:"];
   for (const c of components) {
     const note = c.note ? ` - ${c.note}` : "";
-    lines.push(`  ${c.name}: ${formatInstalled(c.exists)}${note}`);
+    lines.push(`  ${c.name}: ${formatComponentState(c)}${note}`);
   }
   return lines;
 }
@@ -490,7 +519,7 @@ export function formatDoctorReport(report: DoctorReport): string {
     `  Platform: ${report.runtime.platform} ${report.runtime.arch}`,
     "",
     "Engine:",
-    `  Binary: ${report.engine.path} (${formatInstalled(report.engine.installed)})`,
+    `  Binary: ${report.engine.path} (${formatEngineBinaryState(report.engine)})`,
     `  Version marker: ${report.engine.versionMarker ?? "missing"}`,
     `  Pinned version: ${report.engine.pinnedVersion}`,
     `  Version state: ${formatVersionState(report.engine)}`,

package/src/engine-health.ts

@@ -0,0 +1,55 @@
+import { existsSync } from "fs";
+import { errorMessage } from "./error-utils";
+
+export type ExecutableHealth =
+  | { status: "ok" }
+  | { status: "missing" }
+  | { status: "unusable"; detail: string };
+
+const PROBE_TIMEOUT_MS = 15_000;
+
+/**
+ * Proves a downloaded binary actually executes — existence is not health (#770).
+ *
+ * Any exit code counts as healthy: the probe only has to show that the loader accepted the
+ * image, and the sidecars legitimately exit non-zero when invoked with no work to do. A
+ * truncated download is refused before `main` runs — the spawn throws, or the kernel kills
+ * the process outright (SIGKILL on an invalid Mach-O) — and those are what this reports.
+ *
+ * The timeout guards against a binary that starts but never exits; macOS Gatekeeper can take
+ * several seconds to scan a freshly written binary on its first run, so it is generous.
+ */
+export async function probeExecutable(
+  binPath: string,
+  args: string[] = [],
+): Promise<ExecutableHealth> {
+  if (!existsSync(binPath)) return { status: "missing" };
+
+  let proc: ReturnType<typeof Bun.spawn>;
+  try {
+    proc = Bun.spawn([binPath, ...args], {
+      stdin: "ignore",
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+  } catch (err) {
+    return { status: "unusable", detail: errorMessage(err) };
+  }
+
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    proc.kill();
+  }, PROBE_TIMEOUT_MS);
+  try {
+    await proc.exited;
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (timedOut) {
+    return { status: "unusable", detail: `no exit within ${PROBE_TIMEOUT_MS / 1000}s` };
+  }
+  if (proc.signalCode) return { status: "unusable", detail: `killed by ${proc.signalCode}` };
+  return { status: "ok" };
+}

package/src/engine-install.ts

@@ -8,6 +8,7 @@ import {
   TRANSCRIBE_DIARIZE_FEATURE,
   type EngineCapabilities,
 } from "./engine";
+import { probeExecutable } from "./engine-health";
 import { engineTarget } from "./engine-targets";
 import { isDarwinArm64 } from "./fluid-kokoro-cache";
 import { log } from "./log";
@@ -312,7 +313,8 @@ export function buildEngineInstallArgs(opts: {
     "install",
     ...(opts.noCache ? ["--no-cache"] : []),
     ...(opts.ttsLangs && opts.ttsLangs.length > 0 ? ["--tts", ...opts.ttsLangs] : []),
-    ...(opts.vad ? ["--vad"] : []),
+    // #768: speaker labels attach to VAD-windowed segments, so --diarize pulls VAD in.
+    ...(opts.vad || opts.diarize ? ["--vad"] : []),
     ...(opts.diarize ? ["--diarize"] : []),
   ];
 }
@@ -327,9 +329,21 @@ export interface InstallOptions {
   diarize?: boolean;
 }
 
+/** A sidecar that is present but unrunnable is as useless as an absent one, and `kesha install` is the repair (#770). */
+async function sidecarNeedsDownload(spec: SidecarSpec, engineDir: string): Promise<boolean> {
+  const health = await probeExecutable(join(engineDir, spec.fileBasename));
+  if (health.status === "ok") return false;
+  if (health.status === "unusable") {
+    log.warn(
+      `${spec.displayName} is installed but does not run (${health.detail}); re-downloading it.`,
+    );
+  }
+  return true;
+}
+
 /**
  * Cache-valid path: the binary at binPath already matches the requested version.
- * Re-trusts it and tops up any sidecars the cached install is missing.
+ * Re-trusts it and re-fetches any sidecar the cached install is missing or cannot run.
  */
 async function refreshCachedEngine(
   binPath: string,
@@ -350,18 +364,19 @@ async function refreshCachedEngine(
   if (canWriteEngineDir && existsSync(binPath)) {
     darwinTrustBinary(binPath, "kesha-engine binary");
   }
-  // Top up missing sidecars (pre-#141/#199 cached binaries never had them);
+  // Top up missing or broken sidecars (pre-#141/#199 cached binaries never had them);
   // skip on read-only fs (Nix-store) to avoid confusing "install failed" warnings.
   if (canWriteEngineDir) {
-    const missing = SIDECARS.filter(
-      (s) => !existsSync(join(engineDir, s.fileBasename)),
-    );
-    await Promise.all(missing.map((s) => downloadSidecar(s, binPath, version)));
-    // Also re-trust already-present sidecars for the Sequoia upgrade scenario.
+    // Re-trust before probing, for the Sequoia upgrade scenario: a provenance-blocked
+    // sidecar is SIGKILLed on spawn, and re-downloading it would not lift the block.
     for (const s of SIDECARS) {
       const p = join(engineDir, s.fileBasename);
       if (existsSync(p)) darwinTrustBinary(p, s.displayName);
     }
+    const needed = await Promise.all(SIDECARS.map((s) => sidecarNeedsDownload(s, engineDir)));
+    await Promise.all(
+      SIDECARS.filter((_, i) => needed[i]).map((s) => downloadSidecar(s, binPath, version)),
+    );
   }
 }
 
@@ -376,45 +391,34 @@ export function isTransientSpawnLock(message: string): boolean {
  * A security scanner (Windows Defender is the one this was found on) holds a lock on a newly
  * written 60 MB PE while it scans, so the first spawn fails with EBUSY 15 ms after the download
  * reported success (#216). The lock is transient, so probe until it clears.
+ *
+ * The probe is a full health check: a Gatekeeper-SIGKILLed binary spawns without throwing, and
+ * accepting that would let the `.version` marker vouch for an engine that never ran (#770).
  */
-export async function waitUntilSpawnable(
-  binPath: string,
-  deadlineMs = 60_000,
-  probeTimeoutMs = 5_000,
-): Promise<void> {
+export async function waitUntilSpawnable(binPath: string, deadlineMs = 60_000): Promise<void> {
   const deadline = Date.now() + deadlineMs;
   let lastError = "";
   let warned = false;
   let delay = 100;
 
   for (;;) {
-    try {
-      // Only a throw means locked; the timeout is for a scanner that detains rather than refuses.
-      const proc = Bun.spawn([binPath, "--version"], { stdout: "ignore", stderr: "ignore" });
-      const timer = setTimeout(() => proc.kill(), probeTimeoutMs);
-      try {
-        await proc.exited;
-      } finally {
-        clearTimeout(timer);
-      }
-      return;
-    } catch (e) {
-      lastError = errorMessage(e);
-      // Only a lock is worth waiting out — a missing or corrupt binary never becomes spawnable.
-      if (!isTransientSpawnLock(lastError)) {
-        throw new Error(
-          `Downloaded the engine to ${binPath} but it could not be started: ${lastError}\n` +
-            `  Fix: delete ${dirname(binPath)} and re-run \`kesha install\`.`,
-        );
-      }
-      if (Date.now() + delay > deadline) break;
-      if (!warned) {
-        warned = true;
-        log.progress("Waiting for the engine binary to be released by the system...");
-      }
-      await Bun.sleep(delay);
-      delay = Math.min(delay * 2, 2_000);
+    const health = await probeExecutable(binPath, ["--version"]);
+    if (health.status === "ok") return;
+    lastError = health.status === "unusable" ? health.detail : "the binary is gone";
+    // Only a lock is worth waiting out — a missing or corrupt binary never becomes spawnable.
+    if (!isTransientSpawnLock(lastError)) {
+      throw new Error(
+        `Downloaded the engine to ${binPath} but it could not be started: ${lastError}\n` +
+          `  Fix: delete ${dirname(binPath)} and re-run \`kesha install\`.`,
+      );
+    }
+    if (Date.now() + delay > deadline) break;
+    if (!warned) {
+      warned = true;
+      log.progress("Waiting for the engine binary to be released by the system...");
     }
+    await Bun.sleep(delay);
+    delay = Math.min(delay * 2, 2_000);
   }
 
   throw new Error(
@@ -425,6 +429,21 @@ export async function waitUntilSpawnable(
   );
 }
 
+/**
+ * Cache-validity health check: an install interrupted before `chmod`/marker-write, or a
+ * binary from another architecture, exists at the right version yet cannot start (#770).
+ */
+async function engineRuns(binPath: string): Promise<boolean> {
+  const health = await probeExecutable(binPath, ["--version"]);
+  if (health.status === "ok") return true;
+  const detail = health.status === "unusable" ? health.detail : "binary disappeared";
+  log.warn(
+    `Installed engine at ${binPath} does not run (${detail}); it is corrupt or built for ` +
+      "another architecture — re-downloading it.",
+  );
+  return false;
+}
+
 /** Cold path: download the engine binary (and sidecars, concurrently). */
 async function fetchEngineBinary(
   binPath: string,
@@ -589,7 +608,12 @@ export async function installEngine(request: EngineInstallRequest = {}): Promise
   // Read-only engine dir = Nix-store install; skip download/sidecar writes to avoid EROFS errors.
   const canWriteEngineDir = checkEngineWritable(engineDir);
 
-  const versionMatches = existsSync(binPath) && installedVersion === version;
+  const markerMatches = existsSync(binPath) && installedVersion === version;
+  // The marker vouches for a file, not for a working binary. Skipped on a read-only engine
+  // dir: nothing there can be repaired, so a failed probe would only turn a usable Nix
+  // install into a hard error.
+  const versionMatches =
+    markerMatches && (!canWriteEngineDir || (await engineRuns(binPath)));
   // On read-only fs, --no-cache can't re-download; treat as cache-valid and forward flag to model install.
   const cacheValid = versionMatches && (!noCache || !canWriteEngineDir);
 

package/src/engine.ts

@@ -168,6 +168,19 @@ export interface TranscribeEngineOptions {
   speakers?: boolean;
 }
 
+/** #768: speakers force VAD windowing, so `vad: "off"` is an invalid pair. Callers
+ * must run this before any capability or model resolution — an invalid request
+ * has to read as invalid whatever happens to be installed. */
+export function assertSpeakersVadCompatible(opts: TranscribeEngineOptions): void {
+  if (!opts.speakers || opts.vad !== "off") return;
+  throw new Error(
+    `error [${TS_NATIVE_CODES.INVALID_ARG}]: speakers cannot be combined with vad: "off": ` +
+      "speaker labels attach to VAD-windowed speech segments, and disabling VAD leaves the " +
+      'whole file as one segment with nothing to label. Drop vad: "off" (VAD engages ' +
+      "automatically for speakers), or drop speakers.",
+  );
+}
+
 function defaultDiarizeModelPath(): string {
   return join(keshaCacheDir(), "models", "diarize", "SortformerNvidiaLow_v2.mlpackage");
 }
@@ -181,9 +194,39 @@ function hasDiarizeModelLayout(modelPath: string): boolean {
   );
 }
 
+function assertDiarizeModelInstalled(): void {
+  const envPath = process.env.KESHA_DIARIZE_MODEL_PATH;
+  if (envPath !== undefined) {
+    if (existsSync(envPath)) return;
+    throw new Error(
+      `speaker diarization requires a model path\n\nCaused by:\n    KESHA_DIARIZE_MODEL_PATH set but path does not exist: ${envPath}`,
+    );
+  }
+
+  const modelPath = defaultDiarizeModelPath();
+  if (hasDiarizeModelLayout(modelPath)) return;
+  throw new Error(
+    `speaker diarization requires a model path\n\nCaused by:\n    diarization model not found at ${modelPath}. ` +
+      `Run \`${installHint("--diarize")}\` (or set KESHA_DIARIZE_MODEL_PATH).`,
+  );
+}
+
+/** #768: `--speakers` forces VAD windowing, so the VAD model is a hard dependency. */
+function assertVadModelInstalled(): void {
+  const modelPath = join(keshaCacheDir(), "models", "silero-vad", "silero_vad.onnx");
+  if (existsSync(modelPath)) return;
+  throw new Error(
+    "speaker diarization requires the VAD model: --speakers windows the audio with Silero VAD " +
+      `so each speech span can be labeled.\n\nCaused by:\n    VAD model not found at ${modelPath}. ` +
+      `Run \`${installHint("--vad")}\`.`,
+  );
+}
+
 export async function preflightTranscribeEngineWithSegments(
   opts: TranscribeEngineOptions = {},
 ): Promise<void> {
+  assertSpeakersVadCompatible(opts);
+
   const caps = await getEngineCapabilities();
   if (!caps?.features.includes(TRANSCRIBE_SEGMENTS_FEATURE)) {
     throw new Error(
@@ -200,20 +243,8 @@ export async function preflightTranscribeEngineWithSegments(
     );
   }
 
-  const envPath = process.env.KESHA_DIARIZE_MODEL_PATH;
-  if (envPath !== undefined) {
-    if (existsSync(envPath)) return;
-    throw new Error(
-      `speaker diarization requires a model path\n\nCaused by:\n    KESHA_DIARIZE_MODEL_PATH set but path does not exist: ${envPath}`,
-    );
-  }
-
-  const modelPath = defaultDiarizeModelPath();
-  if (hasDiarizeModelLayout(modelPath)) return;
-  throw new Error(
-    `speaker diarization requires a model path\n\nCaused by:\n    diarization model not found at ${modelPath}. ` +
-      `Run \`${installHint("--diarize")}\` (or set KESHA_DIARIZE_MODEL_PATH).`,
-  );
+  assertDiarizeModelInstalled();
+  assertVadModelInstalled();
 }
 
 function vadArg(vad: VadMode | undefined): string[] {
@@ -324,11 +355,32 @@ export async function detectTextLanguageEngine(
 ): Promise<LangDetectResult | null> {
   if (text.trim().length === 0) return null;
   if (!isEngineInstalled()) return null;
-  const { stdout, exitCode } = await runEngine(["detect-text-lang", text], opts);
-  if (exitCode !== 0) return null;
+  const { stdout, stderr, exitCode } = await runEngine(["detect-text-lang", text], opts);
+  if (exitCode !== 0) {
+    const warning = textLangFailureWarning(stderr);
+    if (warning) log.warn(warning);
+    return null;
+  }
   return parseLangResult(stdout);
 }
 
+/**
+ * Null off darwin, where text detection is unsupported by design and failing is expected.
+ *
+ * On darwin a failure means a broken `kesha-textlang` sidecar, and swallowing it routed
+ * `kesha say` to the default voice with no hint that detection had stopped working (#770).
+ */
+export function textLangFailureWarning(
+  stderr: string,
+  platform: string = process.platform,
+): string | null {
+  if (platform !== "darwin") return null;
+  return (
+    `Text language detection failed${stderr ? `: ${stderr}` : ""}\n` +
+    "  Falling back to the default voice. Fix: run `kesha install` to reinstall the kesha-textlang sidecar."
+  );
+}
+
 export interface TtsLanguageCapability {
   code: string;
   engines: string[];

package/src/install-plan.ts

@@ -332,8 +332,17 @@ function assembleComponents(input: {
     ),
     ...input.tts.components,
   ];
-  if (options.vad) {
-    components.push(modelBundle("VAD Silero v5", VAD_FILES, "long-audio preprocessing"));
+  // #768: --diarize implies VAD — speaker labels attach to VAD-windowed segments.
+  if (options.vad || options.diarize) {
+    components.push(
+      modelBundle(
+        "VAD Silero v5",
+        VAD_FILES,
+        options.vad
+          ? "long-audio preprocessing"
+          : "long-audio preprocessing; --diarize installs it to window audio into labelable segments",
+      ),
+    );
   }
   if (options.diarize) {
     components.push(

package/src/progress.ts

@@ -1,3 +1,6 @@
+import { copyFileSync, readdirSync, renameSync, rmSync, statSync } from "fs";
+import { basename, dirname, join } from "path";
+import { errorMessage } from "./error-utils";
 import { log } from "./log";
 
 const BAR_WIDTH = 20;
@@ -126,6 +129,62 @@ export async function applyBackpressure(
   if (written < 0) await writer.flush();
 }
 
+/**
+ * Age threshold and platform gate mirror `rust/src/models.rs::cleanup_orphan_staging`: a
+ * concurrent installer's staging file keeps a fresh mtime while bytes stream into it, and
+ * Windows leaves last-write time stale while a handle is open, so an in-flight download
+ * there could not be told apart from an orphan.
+ */
+const STALE_STAGING_MS = 24 * 60 * 60 * 1000;
+
+/** A Ctrl-C kills the process before any cleanup runs, so last run's staging file is swept by the next one (#770). */
+function sweepStagingFiles(destPath: string): void {
+  if (process.platform === "win32") return;
+  const dir = dirname(destPath);
+  const prefix = `${basename(destPath)}.part.`;
+  const cutoffMs = Date.now() - STALE_STAGING_MS;
+
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch (err) {
+    log.debug(`Could not scan ${dir} for orphaned download staging: ${errorMessage(err)}`);
+    return;
+  }
+
+  for (const name of names) {
+    if (!name.startsWith(prefix)) continue;
+    const path = join(dir, name);
+    try {
+      if (statSync(path).mtimeMs > cutoffMs) continue;
+      rmSync(path, { force: true });
+      log.debug(`Cleaned up orphaned download staging: ${name}`);
+    } catch (err) {
+      log.debug(`Could not sweep orphaned download staging ${name}: ${errorMessage(err)}`);
+    }
+  }
+}
+
+/** Windows refuses `rename` onto a destination another handle still holds; POSIX overwrites. */
+function publishStaging(stagingPath: string, destPath: string): void {
+  try {
+    renameSync(stagingPath, destPath);
+  } catch (err) {
+    if (process.platform !== "win32") throw err;
+    copyFileSync(stagingPath, destPath);
+    rmSync(stagingPath, { force: true });
+  }
+}
+
+/** The pid alone would collide between two concurrent calls in one process, which then share a staging file. */
+let stagingSeq = 0;
+
+/**
+ * Downloads into a sibling `.part.<pid>.<n>` file and renames it into place, so an
+ * interrupted download can never leave a truncated binary at `destPath` (#770). Mirrors the
+ * staging `rust/src/models.rs::write_verified` already does for model files. Staging beside
+ * the destination keeps the rename within one filesystem, where it is atomic.
+ */
 export async function streamResponseToFile(
   res: Response,
   destPath: string,
@@ -140,17 +199,25 @@ export async function streamResponseToFile(
   const totalBytes = Number(res.headers.get("content-length") || 0);
   const progress = createProgressBar(label, totalBytes);
 
-  const writer = Bun.file(destPath).writer();
+  sweepStagingFiles(destPath);
+  const stagingPath = `${destPath}.part.${process.pid}.${stagingSeq++}`;
+  const writer = Bun.file(stagingPath).writer();
   let bytes = 0;
   try {
-    for await (const chunk of res.body) {
-      await applyBackpressure(writer, writer.write(chunk));
-      bytes += chunk.length;
-      progress.update(chunk.length);
+    try {
+      for await (const chunk of res.body) {
+        await applyBackpressure(writer, writer.write(chunk));
+        bytes += chunk.length;
+        progress.update(chunk.length);
+      }
+    } finally {
+      // Must await: an open write handle makes the freshly-downloaded engine unspawnable — EBUSY on Windows, ETXTBSY on Linux.
+      await writer.end();
     }
-  } finally {
-    // Must await: an open write handle makes the freshly-downloaded engine unspawnable — EBUSY on Windows, ETXTBSY on Linux.
-    await writer.end();
+    publishStaging(stagingPath, destPath);
+  } catch (err) {
+    rmSync(stagingPath, { force: true });
+    throw err;
   }
 
   progress.finish();

package/src/transcribe.ts

@@ -1,4 +1,5 @@
 import {
+  assertSpeakersVadCompatible,
   isEngineInstalled,
   preflightTranscribeEngineWithSegments,
   transcribeEngine,
@@ -30,6 +31,9 @@ export async function transcribe(audioPath: string, opts: TranscribeOptions = {}
 }
 
 export async function preflightTranscribeWithSegments(opts: TranscribeOptions = {}): Promise<void> {
+  // #768: ahead of isEngineInstalled(), so an invalid pair never reads as a missing install.
+  assertSpeakersVadCompatible(opts);
+
   if (!isEngineInstalled()) {
     throw new Error(
       "Error: No transcription backend is installed.\n\n" +

package/src/voice-routing.ts

@@ -5,8 +5,16 @@
  */
 const RU_DARWIN_FALLBACK_VOICE = "macos-com.apple.voice.compact.ru-RU.Milena";
 
+/**
+ * darwin-arm64 (FluidAudio ANE voice pack) defaults. This table plus the
+ * `en`/`ru` switch arms must together cover every code `tts_languages()`
+ * advertises on a system_kokoro build — a missing entry silently drops
+ * `--voice` and the engine falls back to English (#769).
+ * fr is the documented brand-rule exception (no male French voice in Kokoro v1.0).
+ */
 const DARWIN_KOKORO_DEFAULTS: Record<string, string> = {
   es: "es-em_alex",
+  fr: "fr-ff_siwis",
   hi: "hi-hm_omega",
   it: "it-im_nicola",
   ja: "ja-jm_kumo",
@@ -40,7 +48,6 @@ export function pickVoiceForLang(
     case "ru":
       return platform === "darwin" ? RU_DARWIN_FALLBACK_VOICE : "ru-vosk-m02";
     default:
-      // darwin-arm64: FluidAudio ANE voice pack (full multilingual set).
       if (platform === "darwin" && arch === "arm64") return DARWIN_KOKORO_DEFAULTS[baseCode];
       // ONNX: es/fr/it/pt via CharsiuG2P; hi/ja/zh have no ONNX pack → undefined.
       return ONNX_KOKORO_DEFAULTS[baseCode];