@drakulavich/kesha-voice-kit 1.25.0 → 1.26.0

package/README.md

@@ -24,7 +24,7 @@
 
 ## Quick Start
 
-Runtime: **[Bun](https://bun.sh)** >= 1.3.0 · Platforms: macOS arm64, Linux x64. Windows x64 is currently blocked at install ([#216](https://github.com/drakulavich/kesha-voice-kit/issues/216)).
+Runtime: **[Bun](https://bun.sh)** >= 1.3.0 · Platforms: macOS arm64, Linux x64, Windows x64. Linux and Windows run the ONNX engine — everything except microphone capture (`kesha record`), macOS system voices, speaker diarization, and text language detection, which need Apple frameworks.
 
 ```bash
 # 1. Install Bun (skip if you have it) — Linux & macOS:

package/docs/product-positioning.md

@@ -60,27 +60,29 @@ The product promise is not "one model for every audio problem." The promise is a
 
 | Capability | macOS arm64 | macOS x64 | Linux x64 | Windows x64 | Nix path |
 |---|---|---|---|---|---|
-| STT | Supported, CoreML path | Not shipped | Supported, ONNX CPU path | Blocked at install (#216) | `aarch64-darwin`, `x86_64-linux` |
-| Audio language detection | Supported | Not shipped | Supported | Blocked at install (#216) | Supported where the flake builds |
-| VAD | Supported with `kesha install --vad` | Not shipped | Supported with `kesha install --vad` | Blocked at install (#216) | Supported where the engine path includes VAD assets |
-| TTS: English Kokoro | Supported, FluidAudio/CoreML in release builds | Not shipped | Supported, ONNX path | Blocked at install (#216) | Supported except where noted in `docs/nix-install.md` |
-| TTS: Russian Vosk-TTS | Supported | Not shipped | Supported | Blocked at install (#216) | Supported except where noted in `docs/nix-install.md` |
+| STT | Supported, CoreML path | Not shipped | Supported, ONNX CPU path | Supported, ONNX CPU path | `aarch64-darwin`, `x86_64-linux` |
+| Audio language detection | Supported | Not shipped | Supported | Supported | Supported where the flake builds |
+| VAD | Supported with `kesha install --vad` | Not shipped | Supported with `kesha install --vad` | Supported with `kesha install --vad` | Supported where the engine path includes VAD assets |
+| TTS: English Kokoro | Supported, FluidAudio/CoreML in release builds | Not shipped | Supported, ONNX path | Supported, ONNX path | Supported except where noted in `docs/nix-install.md` |
+| TTS: Russian Vosk-TTS | Supported | Not shipped | Supported | Supported | Supported except where noted in `docs/nix-install.md` |
 | macOS system voices | Supported | Not shipped | Not applicable | Not applicable | Supported on `aarch64-darwin` |
 | 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 | Blocked at install (#216) | Use the installed `kesha` command from the chosen path |
-| Hermes Agent integration | Supported through command providers | Not shipped | Supported through command providers | Blocked at install (#216) | Use the installed `kesha` command from the chosen path |
+| 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.
 
-`Windows x64` shows "Blocked at install" because the CLI's install step
-refuses to run on Windows, not because no binary exists — `build-engine.yml`
-builds and publishes `kesha-engine-windows-x64.exe` with every release. The
-Vosk-TTS native dependency trips MSVC at link time, so the CLI blocks the
-install client-side rather than shipping a broken engine. See
-[issue #216](https://github.com/drakulavich/kesha-voice-kit/issues/216) for
-the underlying failure and the v1.4.x workaround; the toolkit is unusable on
-Windows until that lands.
+`Windows x64` runs the same ONNX engine as Linux. The MSVC link failure behind
+[issue #216](https://github.com/drakulavich/kesha-voice-kit/issues/216) was fixed by
+vendoring the Vosk-TTS runtime under `rust/vendor/vosk-tts/`, and the CLI's install
+refusal — which outlived that fix by about twenty minor versions — is gone. CI now runs
+a cold `kesha install` on `windows-latest`, synthesises with both the Kokoro and Vosk
+engines, and transcribes the result back, so the platform's row reflects a tested path
+rather than a published binary nobody had run.
+
+Microphone capture is the one Linux/Windows gap that is not about Apple frameworks:
+`kesha record` is macOS-only, so pass an existing audio file instead.
 
 ## When to choose something else
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.25.0",
+  "version": "1.26.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": {
@@ -57,7 +57,8 @@
     "check:workflows": "bun .github/scripts/check-workflows.ts",
     "check:specs": "bunx @fission-ai/openspec@1.4.1 validate --specs --strict",
     "check:release-manifest": "bun .github/scripts/release-manifest.mjs --check",
-    "check:versions": "bun .github/scripts/check-versions.ts"
+    "check:versions": "bun .github/scripts/check-versions.ts",
+    "check:engine-targets": "bun .github/scripts/check-engine-targets.ts"
   },
   "keywords": [
     "asr",
@@ -102,6 +103,7 @@
   },
   "overrides": {
     "hono": "^4.12.25",
-    "fast-uri": "^3.1.3"
+    "fast-uri": "^3.1.5",
+    "ip-address": "^10.3.1"
   }
 }

package/src/cli/init.ts

@@ -1,7 +1,5 @@
 import { defineCommand } from "citty";
-import { createInterface } from "node:readline/promises";
-import { stdin as input, stdout as output } from "node:process";
-import { multiselect, isCancel, cancel } from "@clack/prompts";
+import { confirm, multiselect, isCancel, cancel } from "@clack/prompts";
 import { renderInstallPlan } from "../install-plan";
 import { log } from "../log";
 import { getEngineCapabilities } from "../engine";
@@ -23,6 +21,18 @@ const TTS_LANG_LABELS: Record<string, string> = {
 /** Signature of the interactive TTS-language picker (injectable for tests). */
 export type TtsLangPrompt = (preselect: string[]) => Promise<string[]>;
 
+/** Signature of the interactive yes/no prompt (injectable for tests). */
+export type ConfirmPrompt = (message: string, initialValue: boolean) => Promise<boolean>;
+
+/** Ctrl-C at any prompt ends init without downloading, rather than falling through with a default. */
+function exitIfCancelled<T>(answer: T | symbol): T {
+  if (isCancel(answer)) {
+    cancel("Init cancelled.");
+    process.exit(0);
+  }
+  return answer as T;
+}
+
 async function promptTtsLangs(preselect: string[]): Promise<string[]> {
   const caps = await getEngineCapabilities();
   const supported = caps?.tts?.languages.map((l) => l.code) ?? TTS_LANG_FALLBACK;
@@ -33,11 +43,12 @@ async function promptTtsLangs(preselect: string[]): Promise<string[]> {
     initialValues: preselect.filter((l) => supported.includes(l)),
     required: false,
   });
-  if (isCancel(selected)) {
-    cancel("Init cancelled.");
-    process.exit(0);
-  }
-  return selected as string[];
+  return exitIfCancelled(selected);
+}
+
+/** #677: keep every prompt on clack — its close() unpipes stdin, deadlocking any readline sharing it. */
+async function promptConfirm(message: string, initialValue: boolean): Promise<boolean> {
+  return exitIfCancelled(await confirm({ message, initialValue }));
 }
 
 export interface InitCommandArgs extends SharedInstallArgs {
@@ -52,10 +63,6 @@ export interface InitSelection {
   diarize: boolean;
 }
 
-interface PromptApi {
-  question(prompt: string): Promise<string>;
-}
-
 export function canInstallDiarizeOnPlatform(
   platform = process.platform,
   arch = process.arch,
@@ -140,17 +147,17 @@ export function renderInitOverview(canDiarize = canInstallDiarizeOnPlatform()):
 
 export async function promptInitSelection(
   args: InitCommandArgs,
-  prompt: PromptApi,
+  prompt: ConfirmPrompt,
   backend = resolveBackendFlag(args.coreml, args.onnx),
   canDiarize = canInstallDiarizeOnPlatform(),
   noCache = resolveNoCacheFlag(args),
   promptTts: TtsLangPrompt = promptTtsLangs,
 ): Promise<InitSelection> {
   const ttsLangs = await promptTts(args.tts ? ["en"] : []);
-  const vad = await askYesNo(prompt, "Install VAD for long or silence-heavy audio?", args.vad);
+  const vad = await prompt("Install VAD for long or silence-heavy audio?", args.vad);
   let diarize = false;
   if (canDiarize) {
-    diarize = await askYesNo(prompt, "Install speaker diarization for `--speakers`?", args.diarize);
+    diarize = await prompt("Install speaker diarization for `--speakers`?", args.diarize);
   } else if (args.diarize) {
     log.warn("--diarize is currently darwin-arm64 only; omitting it from the interactive install.");
   }
@@ -164,17 +171,6 @@ export async function promptInitSelection(
   };
 }
 
-async function askYesNo(prompt: PromptApi, message: string, defaultValue: boolean): Promise<boolean> {
-  const suffix = defaultValue ? "Y/n" : "y/N";
-  for (;;) {
-    const answer = (await prompt.question(`${message} [${suffix}] `)).trim().toLowerCase();
-    if (answer === "") return defaultValue;
-    if (answer === "y" || answer === "yes") return true;
-    if (answer === "n" || answer === "no") return false;
-    log.warn("Please answer yes or no.");
-  }
-}
-
 async function printPlan(selection: InitSelection): Promise<void> {
   log.info(
     await renderInstallPlan({
@@ -282,33 +278,36 @@ export const initCommand = defineCommand({
     }
 
     log.info(renderInitOverview());
-    const rl = createInterface({ input, output });
-    try {
-      const prompted = await promptInitSelection(args, rl, backend, canInstallDiarizeOnPlatform(), noCache);
-      log.info("");
-      await printPlan(prompted);
-      const confirmed = await askYesNo(rl, `Run \`${initInstallArgs(prompted).join(" ")}\` now?`, true);
-      if (!confirmed) {
-        log.info(`Skipped install. Run later: ${initInstallArgs(prompted).join(" ")}`);
-        return;
-      }
-      await performInstall(
-        prompted.noCache,
-        prompted.backend,
-        prompted.ttsLangs,
-        prompted.vad,
-        prompted.diarize,
-      );
-      // Next-steps hint (#523): leave the user with something runnable rather
-      // than ending on the install log.
-      log.info("");
-      log.success("Kesha is ready. Try:");
-      log.info("  kesha path/to/audio.ogg     Transcribe a file.");
-      if (prompted.ttsLangs.length > 0) {
-        log.info('  kesha say "hello"           Speak text (TTS).');
-      }
-    } finally {
-      rl.close();
+    const prompted = await promptInitSelection(
+      args,
+      promptConfirm,
+      backend,
+      canInstallDiarizeOnPlatform(),
+      noCache,
+    );
+    log.info("");
+    await printPlan(prompted);
+    const confirmed = await promptConfirm(
+      `Run \`${initInstallArgs(prompted).join(" ")}\` now?`,
+      true,
+    );
+    if (!confirmed) {
+      log.info(`Skipped install. Run later: ${initInstallArgs(prompted).join(" ")}`);
+      return;
+    }
+    await performInstall(
+      prompted.noCache,
+      prompted.backend,
+      prompted.ttsLangs,
+      prompted.vad,
+      prompted.diarize,
+    );
+    // #523: end on something runnable, not on the install log.
+    log.info("");
+    log.success("Kesha is ready. Try:");
+    log.info("  kesha path/to/audio.ogg     Transcribe a file.");
+    if (prompted.ttsLangs.length > 0) {
+      log.info('  kesha say "hello"           Speak text (TTS).');
     }
   },
 });

package/src/cli/install.ts

@@ -1,6 +1,7 @@
 import { defineCommand } from "citty";
 import { errorMessage } from "../error-utils";
 import { downloadEngine } from "../engine-install";
+import { engineTarget } from "../engine-targets";
 import { getEngineBinPath, getEngineCapabilities } from "../engine";
 import { renderInstallPlan } from "../install-plan";
 import { maybeAskForStar } from "../star";
@@ -90,10 +91,11 @@ export function resolveBackendFlag(coreml: boolean, onnx: boolean): string | und
   return selection.backend;
 }
 
-function defaultBackendForPlatform(): string | undefined {
-  if (process.platform === "darwin" && process.arch === "arm64") return "coreml";
-  if (process.platform === "linux" && process.arch === "x64") return "onnx";
-  return undefined;
+export function defaultBackendForPlatform(
+  platform: string = process.platform,
+  arch: string = process.arch,
+): string | undefined {
+  return engineTarget(platform, arch)?.backend;
 }
 
 type InstallDiagnosticErrorKind = "validation_failed" | "install_failed";

package/src/cli/status.ts

@@ -26,8 +26,7 @@ export const statusCommand = defineCommand({
   async run({ args }: { args: StatusCommandArgs }) {
     const report = await collectStatus({ disk: args.disk });
     if (args.json) {
-      // `log.*` writes to stdout, so the payload must be the only thing printed —
-      // the setup hint ships inside it instead of on stderr (#647).
+      // `log.*` writes to stdout, so the payload must be the only thing printed (#647).
       console.log(JSON.stringify(report, null, 2));
       return;
     }

package/src/engine-install.ts

@@ -8,6 +8,7 @@ import {
   TRANSCRIBE_DIARIZE_FEATURE,
   type EngineCapabilities,
 } from "./engine";
+import { engineTarget } from "./engine-targets";
 import { isDarwinArm64 } from "./fluid-kokoro-cache";
 import { log } from "./log";
 import { engineVersion } from "./package-info";
@@ -25,22 +26,13 @@ export {
 
 const GITHUB_REPO = "drakulavich/kesha-voice-kit";
 
-function getEngineBinaryName(): string {
-  const platform = process.platform;
-  const arch = process.arch;
-
-  if (platform === "darwin" && arch === "arm64") return "kesha-engine-darwin-arm64";
-  if (platform === "linux" && arch === "x64") return "kesha-engine-linux-x64";
-  if (platform === "win32" && arch === "x64") {
-    throw new Error(
-      "Windows x64 is temporarily unsupported in v1.5.0 — the Vosk-TTS engine has " +
-        "native deps that trip MSVC at link time. Tracked at " +
-        "https://github.com/drakulavich/kesha-voice-kit/issues/216. " +
-        "Use v1.4.x as a workaround until the fix lands.",
-    );
-  }
-
-  throw new Error(`Unsupported platform: ${platform} ${arch}`);
+export function getEngineBinaryName(
+  platform: string = process.platform,
+  arch: string = process.arch,
+): string {
+  const target = engineTarget(platform, arch);
+  if (!target) throw new Error(`Unsupported platform: ${platform} ${arch}`);
+  return target.assetName;
 }
 
 /** Sidecar spec — centralises AVSpeech (#141) and future sidecars so each is one entry. */
@@ -372,6 +364,66 @@ async function refreshCachedEngine(
   }
 }
 
+/** EACCES/EPERM are deliberately absent: those are policy (noexec, ACL, AppLocker) and never clear. */
+export function isTransientSpawnLock(message: string): boolean {
+  return /\b(EBUSY|ETXTBSY)\b/.test(message) || /sharing violation/i.test(message);
+}
+
+/**
+ * Blocks until the freshly-downloaded engine can actually be spawned.
+ *
+ * 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.
+ */
+export async function waitUntilSpawnable(
+  binPath: string,
+  deadlineMs = 60_000,
+  probeTimeoutMs = 5_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);
+    }
+  }
+
+  throw new Error(
+    `Downloaded the engine to ${binPath} but it is still locked after ` +
+      `${Math.round(deadlineMs / 1000)}s: ${lastError}\n` +
+      `  Fix: a security scanner is likely holding the file. Re-run \`kesha install\`, ` +
+      `or exclude ${dirname(binPath)} from real-time scanning.`,
+  );
+}
+
 /** Cold path: download the engine binary (and sidecars, concurrently). */
 async function fetchEngineBinary(
   binPath: string,
@@ -416,6 +468,8 @@ async function fetchEngineBinary(
   await streamResponseToFile(res, binPath, "kesha-engine binary");
   chmodSync(binPath, 0o755);
   darwinTrustBinary(binPath, "kesha-engine binary");
+  // Marker last: writing it first sends the retry down the cacheValid branch, which never waits.
+  await waitUntilSpawnable(binPath);
   writeInstalledEngineVersion(binPath, engineVersion);
   log.success(`Engine binary downloaded (v${engineVersion}).`);
   await Promise.all(sidecarPromises);
@@ -474,7 +528,7 @@ function validateDiarize(caps: EngineCapabilities | null): void {
 
 /**
  * Runs `kesha-engine install` to download/verify models.
- * Streams stderr to the process and throws on non-zero exit.
+ * Inherits stdio so per-file progress reaches the user live, and throws on non-zero exit.
  */
 function runEngineModelInstall(
   binPath: string,
@@ -488,19 +542,17 @@ function runEngineModelInstall(
     vad: options.vad,
     diarize: options.diarize,
   });
+  // #680: piping buffers the child until exit, so multi-GB downloads looked hung.
   const proc = Bun.spawnSync([binPath, ...installArgs], {
-    stdout: "pipe",
-    stderr: "pipe",
+    stdout: "inherit",
+    stderr: "inherit",
   });
 
-  const stderr = proc.stderr.toString();
-  if (stderr) {
-    process.stderr.write(stderr);
-  }
-
   if (proc.exitCode !== 0) {
-    const detail = stderr.trim();
-    throw new Error(detail ? `Failed to install models: ${detail}` : "Failed to install models");
+    throw new Error(
+      `Failed to install models: kesha-engine install exited with code ${proc.exitCode}. ` +
+        "See the engine output above for the failing file.",
+    );
   }
 }
 

package/src/engine-targets.ts

@@ -0,0 +1,48 @@
+/**
+ * The one table of what each shipped platform gets.
+ *
+ * Kept import-free so any module can read it — `paths.ts` in particular must stay
+ * dependency-light. Adding a platform is one row here; #216 had to touch four
+ * separate switch chains, and nothing would have caught a missed one.
+ */
+export interface EngineTarget {
+  /** GitHub release asset name — suffixed for uniqueness across platforms. */
+  assetName: string;
+  backend: "coreml" | "onnx";
+  /** Published asset size, for `kesha install --plan`. Verified by `check:engine-targets`. */
+  sizeBytes: number;
+}
+
+const ENGINE_TARGETS: Record<string, EngineTarget> = {
+  "darwin-arm64": {
+    assetName: "kesha-engine-darwin-arm64",
+    backend: "coreml",
+    sizeBytes: 62_172_768,
+  },
+  "linux-x64": {
+    assetName: "kesha-engine-linux-x64",
+    backend: "onnx",
+    sizeBytes: 63_188_728,
+  },
+  "win32-x64": {
+    assetName: "kesha-engine-windows-x64.exe",
+    backend: "onnx",
+    sizeBytes: 63_447_040,
+  },
+};
+
+/** Returns null for a platform with no published engine — callers choose how loudly to fail. */
+export function engineTarget(
+  platform: string = process.platform,
+  arch: string = process.arch,
+): EngineTarget | null {
+  return ENGINE_TARGETS[`${platform}-${arch}`] ?? null;
+}
+
+export function engineTargetEntries(): Array<{ platform: string; arch: string; target: EngineTarget }> {
+  return Object.entries(ENGINE_TARGETS).map(([key, target]) => {
+    // Split once from the left: an arch token may itself contain a hyphen, a platform never does.
+    const sep = key.indexOf("-");
+    return { platform: key.slice(0, sep), arch: key.slice(sep + 1), target };
+  });
+}

package/src/engine.ts

@@ -373,9 +373,7 @@ export async function getEngineCapabilities(): Promise<EngineCapabilities | null
   }
 }
 
-// A non-null return has to mean "the engine described itself" — callers reach
-// straight for `.features.join()` and `.backend` (#647). Only the fields those
-// callers consume are checked, so a newer engine adding fields still validates.
+// A non-null return must mean "it described itself" — callers reach straight for `.features.join()` (#647).
 function parseCapabilities(parsed: unknown): EngineCapabilities | null {
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
   const { protocolVersion, backend, features } = parsed as Record<string, unknown>;

package/src/install-plan.ts

@@ -3,6 +3,7 @@ import { humanBytes } from "./format";
 import { dirname, join } from "path";
 import { getEngineBinPath } from "./engine";
 import { SIDECARS } from "./engine-install";
+import { engineTarget } from "./engine-targets";
 import { readInstalledEngineVersion } from "./engine-version-marker";
 import { keshaCacheDir } from "./paths";
 import { engineVersion, packageVersion } from "./package-info";
@@ -105,16 +106,8 @@ function sumFiles(files: PlanFile[]): number {
 }
 
 function engineAssetForPlatform(): ReleaseAssetSpec | null {
-  if (process.platform === "darwin" && process.arch === "arm64") {
-    return { assetName: "kesha-engine-darwin-arm64", sizeBytes: 59_621_264 };
-  }
-  if (process.platform === "linux" && process.arch === "x64") {
-    return { assetName: "kesha-engine-linux-x64", sizeBytes: 62_897_808 };
-  }
-  if (process.platform === "win32" && process.arch === "x64") {
-    return { assetName: "kesha-engine-windows-x64.exe", sizeBytes: 63_126_528 };
-  }
-  return null;
+  const target = engineTarget();
+  return target && { assetName: target.assetName, sizeBytes: target.sizeBytes };
 }
 
 function filesCached(cacheRoot: string, files: PlanFile[]): boolean {
@@ -153,10 +146,6 @@ function buildEngineComponent(binPath: string, noCache: boolean): PlanComponent
       sizeBytes: engineAsset.sizeBytes,
       cached: engineCached,
       refresh: noCache,
-      note:
-        process.platform === "win32"
-          ? "Windows x64 is currently blocked by the install path; see issue #216."
-          : undefined,
     };
   }
   return {

package/src/paths.ts

@@ -5,6 +5,8 @@ export function keshaCacheDir(): string {
   return process.env.KESHA_CACHE_DIR ?? join(homedir(), ".cache", "kesha");
 }
 
-export function defaultEngineBinPath(): string {
-  return join(keshaCacheDir(), "engine", "bin", "kesha-engine");
+/** The `.exe` suffix is a platform fact, not a per-target one: an extensionless PE is not reliably spawnable. */
+export function defaultEngineBinPath(platform = process.platform): string {
+  const basename = platform === "win32" ? "kesha-engine.exe" : "kesha-engine";
+  return join(keshaCacheDir(), "engine", "bin", basename);
 }

package/src/progress.ts

@@ -105,6 +105,27 @@ export function createPercentProgress(
   };
 }
 
+type SinkWrite = ReturnType<Bun.FileSink["write"]>;
+
+/**
+ * Waits for the sink whenever a write did not complete inline.
+ *
+ * Bun's FileSink reports a pending write as a Promise and backpressure as the negative
+ * sentinel `-(bytes + 1)`; discarding either buffers the whole download in memory instead
+ * of throttling to disk speed, which for the engine is ~63 MB and for the Vosk voice ~937 MB
+ * (#669). Exported for the test — the sentinel is not reproducible on demand.
+ */
+export async function applyBackpressure(
+  writer: Pick<Bun.FileSink, "flush">,
+  written: SinkWrite,
+): Promise<void> {
+  if (typeof written !== "number") {
+    await written;
+    return;
+  }
+  if (written < 0) await writer.flush();
+}
+
 export async function streamResponseToFile(
   res: Response,
   destPath: string,
@@ -123,12 +144,13 @@ export async function streamResponseToFile(
   let bytes = 0;
   try {
     for await (const chunk of res.body) {
-      writer.write(chunk);
+      await applyBackpressure(writer, writer.write(chunk));
       bytes += chunk.length;
       progress.update(chunk.length);
     }
   } finally {
-    writer.end();
+    // Must await: an open write handle makes the freshly-downloaded engine unspawnable — EBUSY on Windows, ETXTBSY on Linux.
+    await writer.end();
   }
 
   progress.finish();