@drakulavich/kesha-voice-kit 1.31.0 → 2.0.0

package/README.md

@@ -19,7 +19,7 @@
 - **Small Rust engine** — single ~65MB binary, no ffmpeg, no Python, no native Node addons
 
 <p align="center">
-  <img src="https://github.com/drakulavich/kesha-voice-kit/raw/main/demo.gif" alt="kesha demo — English + Russian transcription with automatic language detection" width="800">
+  <img src="https://github.com/drakulavich/kesha-voice-kit/raw/main/docs/assets/demo.webp" alt="kesha demo: an English voice message transcribed, a Russian one as JSON with automatic language detection, then text-to-speech into a wav" width="800">
 </p>
 
 ## Quick Start
@@ -138,10 +138,10 @@ Full per-file breakdown (Russian + English): [BENCHMARK.md](BENCHMARK.md). The C
 
 All of these install the Bun CLI wrapper; engine + models still download explicitly via `kesha install`. (Nix is the exception — it currently builds only the engine from source; see below.)
 
-- **Homebrew** — `brew install drakulavich/tap/kesha-voice-kit` · [docs/homebrew.md](docs/homebrew.md)
-- **Linux packages** (`.deb`/`.rpm`, x64) — published on CLI releases, see [docs/linux-packages.md](docs/linux-packages.md)
+- **Homebrew** — `brew install drakulavich/tap/kesha-voice-kit` · [docs/distribution.md](docs/distribution.md#homebrew)
+- **Linux packages** (`.deb`/`.rpm`, x64) — published on stable releases, see [docs/distribution.md](docs/distribution.md#linux-packages)
 - **Docker** (GHCR image) — [docs/docker.md](docs/docker.md)
-- **Nix** (`aarch64-darwin` / `x86_64-linux`) — builds the engine from source (`nix build github:drakulavich/kesha-voice-kit#kesha-engine`). The full `kesha` CLI via `nix run` / `nix profile install` is **not yet available** — it needs a maintainer with Nix to populate a build hash ([#946](https://github.com/drakulavich/kesha-voice-kit/issues/946)). · [docs/nix-install.md](docs/nix-install.md)
+- **Nix** (`aarch64-darwin` / `x86_64-linux`) — builds the engine from source (`nix build github:drakulavich/kesha-voice-kit#kesha-engine`). The full `kesha` CLI via `nix run` / `nix profile install` is **not yet available** — it needs a maintainer with Nix to populate a build hash ([#946](https://github.com/drakulavich/kesha-voice-kit/issues/946)). · [docs/distribution.md](docs/distribution.md#nix)
 - **Shell completions + manpage** — `kesha completions bash|zsh|fish` and `kesha manpage` print the packaged files to install wherever your shell expects them.
 
 ## Integrations

package/SKILL.md

@@ -236,7 +236,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 (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-*`.
+**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). The `hi`/`ja` Kokoro voices read romanized Latin input only; on macOS, text that is mostly Devanagari or kana/kanji with no `--voice` routes to an installed AVSpeech voice (Lekha for `hi-IN`, Otoya for `ja-JP`), while an explicit `--voice hi-*`/`ja-*` refuses them with `E_SCRIPT_UNSUPPORTED`; non-macOS builds have no `hi`/`ja` voices, so the text is refused by the default English voice (`E_SCRIPT_UNSUPPORTED`) and `--voice hi-*`/`ja-*` is `E_VOICE_UNKNOWN` — see [#492](https://github.com/drakulavich/kesha-voice-kit/issues/492). Any macOS system voice is also available via `--voice macos-*`.
 
 ## Performance
 

package/docs/product-positioning.md

@@ -27,7 +27,7 @@ The product promise is not "one model for every audio problem." The promise is a
 | 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` |
+| Install through Nix instead of Bun/npm | Beta, selected systems | `docs/distribution.md#nix` |
 
 ## Non-goals
 
@@ -63,8 +63,8 @@ The product promise is not "one model for every audio problem." The promise is a
 | 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: Kokoro (`en` `es` `fr` `it` `pt`) | 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` |
+| TTS: Kokoro (`en` `es` `fr` `it` `pt`) | Supported, FluidAudio/CoreML in release builds | Not shipped | Supported, ONNX path | Supported, ONNX path | Supported except where noted in `docs/distribution.md#nix` |
+| TTS: Russian Vosk-TTS | Supported | Not shipped | Supported | Supported | Supported except where noted in `docs/distribution.md#nix` |
 | TTS: Kokoro (`hi` `ja` `zh`) | Supported, darwin-arm64 only | Not shipped | Not supported | Not supported | `aarch64-darwin` only |
 | 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 |

package/model-plan.json

@@ -62,14 +62,14 @@
     { "relPath": "KokoroNoise_v2.mlmodelc/weights/weight.bin", "sizeBytes": 4580160 },
     { "relPath": "KokoroVocoder.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
     { "relPath": "KokoroVocoder.mlmodelc/coremldata.bin", "sizeBytes": 626 },
-    { "relPath": "KokoroVocoder.mlmodelc/metadata.json", "sizeBytes": 4392 },
-    { "relPath": "KokoroVocoder.mlmodelc/model.mil", "sizeBytes": 309130 },
+    { "relPath": "KokoroVocoder.mlmodelc/metadata.json", "sizeBytes": 4331 },
+    { "relPath": "KokoroVocoder.mlmodelc/model.mil", "sizeBytes": 309000 },
     { "relPath": "KokoroVocoder.mlmodelc/weights/weight.bin", "sizeBytes": 48889920 },
-    { "relPath": "KokoroTail.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
-    { "relPath": "KokoroTail.mlmodelc/coremldata.bin", "sizeBytes": 392 },
-    { "relPath": "KokoroTail.mlmodelc/metadata.json", "sizeBytes": 1872 },
-    { "relPath": "KokoroTail.mlmodelc/model.mil", "sizeBytes": 7014 },
-    { "relPath": "KokoroTail.mlmodelc/weights/weight.bin", "sizeBytes": 81088 },
+    { "relPath": "KokoroTail_v2.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroTail_v2.mlmodelc/coremldata.bin", "sizeBytes": 392 },
+    { "relPath": "KokoroTail_v2.mlmodelc/metadata.json", "sizeBytes": 1872 },
+    { "relPath": "KokoroTail_v2.mlmodelc/model.mil", "sizeBytes": 7014 },
+    { "relPath": "KokoroTail_v2.mlmodelc/weights/weight.bin", "sizeBytes": 81088 },
     { "relPath": "vocab.json", "sizeBytes": 1416 },
     { "relPath": "af_heart.bin", "sizeBytes": 522240 }
   ],
@@ -143,14 +143,14 @@
     { "relPath": "KokoroNoise_v2.mlmodelc/weights/weight.bin", "sizeBytes": 4580160 },
     { "relPath": "KokoroVocoder.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
     { "relPath": "KokoroVocoder.mlmodelc/coremldata.bin", "sizeBytes": 627 },
-    { "relPath": "KokoroVocoder.mlmodelc/metadata.json", "sizeBytes": 4392 },
-    { "relPath": "KokoroVocoder.mlmodelc/model.mil", "sizeBytes": 309127 },
+    { "relPath": "KokoroVocoder.mlmodelc/metadata.json", "sizeBytes": 4331 },
+    { "relPath": "KokoroVocoder.mlmodelc/model.mil", "sizeBytes": 308997 },
     { "relPath": "KokoroVocoder.mlmodelc/weights/weight.bin", "sizeBytes": 48889920 },
-    { "relPath": "KokoroTail.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
-    { "relPath": "KokoroTail.mlmodelc/coremldata.bin", "sizeBytes": 392 },
-    { "relPath": "KokoroTail.mlmodelc/metadata.json", "sizeBytes": 1872 },
-    { "relPath": "KokoroTail.mlmodelc/model.mil", "sizeBytes": 7014 },
-    { "relPath": "KokoroTail.mlmodelc/weights/weight.bin", "sizeBytes": 81088 },
+    { "relPath": "KokoroTail_v2.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroTail_v2.mlmodelc/coremldata.bin", "sizeBytes": 392 },
+    { "relPath": "KokoroTail_v2.mlmodelc/metadata.json", "sizeBytes": 1872 },
+    { "relPath": "KokoroTail_v2.mlmodelc/model.mil", "sizeBytes": 7014 },
+    { "relPath": "KokoroTail_v2.mlmodelc/weights/weight.bin", "sizeBytes": 81088 },
     { "relPath": "vocab.json", "sizeBytes": 1796 },
     { "relPath": "voices/zf_001.bin", "sizeBytes": 522240 },
     { "relPath": "voices/zm_050.bin", "sizeBytes": 522240 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.31.0",
+  "version": "2.0.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": {
@@ -39,9 +39,6 @@
       "openclawVersion": "2026.5.27"
     }
   },
-  "keshaEngine": {
-    "version": "1.26.0"
-  },
   "scripts": {
     "test": "bun test --timeout 30000",
     "test:watch": "bun test --timeout 30000 --watch",
@@ -61,7 +58,7 @@
     "check:release-manifest": "bun .github/scripts/release-manifest.mjs --check",
     "check:versions": "bun .github/scripts/check-versions.ts",
     "check:engine-targets": "bun .github/scripts/check-engine-targets.ts",
-    "mutants:ts": "bun scripts/mutants-ts.ts"
+    "check:file-sizes": "bun .github/scripts/check-file-sizes.ts"
   },
   "keywords": [
     "asr",
@@ -89,8 +86,6 @@
     "bun": ">=1.3.0"
   },
   "devDependencies": {
-    "@hughescr/stryker-bun-runner": "^1.3.8",
-    "@stryker-mutator/core": "^9.6.1",
     "@types/bun": "latest",
     "fast-xml-parser": "^5.8.0",
     "typescript": "^7.0.2",
@@ -111,5 +106,24 @@
     "fast-uri": "^3.1.5",
     "ip-address": "^10.3.1",
     "smol-toml": "1.7.2"
+  },
+  "kesha": {
+    "engine": {
+      "version": "2.0.0",
+      "sha256": {
+        "kesha-engine-darwin-arm64": "2d75bc773fb81917a0dd996124c0e18eea3b15ecc8f04fe274d41c68bda9276c",
+        "kesha-engine-linux-x64": "09082a1f3eb07d8f8051806a057669f098856d84541f087a1e614ca80d8235b2",
+        "kesha-engine-windows-x64.exe": "de86f350bfd3d076cf339d99d892605b1a37a99085e8ff4c8ef87057618193f3",
+        "say-avspeech-darwin-arm64": "a3aa5b75ddff68a48f1158e838310b37cac72ef86841d9cfcdf1ee233cb7451a",
+        "kesha-textlang-darwin-arm64": "e45e2822248b14dd72aa79e2def8fa6b9c07c97423f11c841508769225d72da4"
+      },
+      "size": {
+        "kesha-engine-darwin-arm64": 73623152,
+        "kesha-engine-linux-x64": 67392296,
+        "kesha-engine-windows-x64.exe": 66550272,
+        "say-avspeech-darwin-arm64": 64208,
+        "kesha-textlang-darwin-arm64": 57648
+      }
+    }
   }
 }

package/src/cache-layout.ts

@@ -1,8 +1,21 @@
-import { join, resolve, sep } from "path";
+import { existsSync, realpathSync, statSync } from "fs";
+import { dirname, join, resolve, sep } from "path";
+import { dirSizeBytes } from "./diagnostic-paths";
 
-export interface CachePathEntry {
+/** The sidecar executables the engine spawns from its own directory. */
+const SIDECAR_FILES = ["say-avspeech", "kesha-textlang"] as const;
+
+export interface CacheComponentSize {
   label: string;
   path: string;
+  exists: boolean;
+  sizeBytes: number;
+}
+
+interface EngineFootprint {
+  path: string;
+  members: string[];
+  sizeOf: (path: string) => number;
 }
 
 /**
@@ -18,6 +31,56 @@ export function isInsideDir(child: string, parent: string): boolean {
   return resolvedChild === resolvedParent || resolvedChild.startsWith(`${resolvedParent}${sep}`);
 }
 
+/**
+ * What the Engine row owns (#1313). A managed install owns all of `<cache>/engine`. An
+ * overridden binary (`KESHA_ENGINE_BIN`, a Nix store path) shares its directory with software
+ * Kesha does not own, so only the binary and the sidecars beside it are counted — its
+ * grandparent may be `/usr/local`.
+ */
+function engineFootprint(binPath: string, cacheRoot: string): EngineFootprint {
+  const managedRoot = join(cacheRoot, "engine");
+  if (resolve(dirname(binPath)) === resolve(managedRoot, "bin")) {
+    return { path: managedRoot, members: [managedRoot], sizeOf: dirSizeBytes };
+  }
+  const binDir = dirname(binPath);
+  return {
+    path: binPath,
+    members: [binPath, ...SIDECAR_FILES.map((f) => join(binDir, f))],
+    sizeOf: regularFileBytes,
+  };
+}
+
+/** A sidecar name that is (or links to) a directory is not ours to walk. */
+function regularFileBytes(path: string): number {
+  try {
+    const st = statSync(path);
+    return st.isFile() ? st.size : 0;
+  } catch {
+    return 0;
+  }
+}
+
+function footprintBytes(engine: EngineFootprint, members: string[]): number {
+  return members.reduce((n, p) => n + engine.sizeOf(p), 0);
+}
+
+/** The cache plus whatever engine bytes live outside it, each counted once (#790). */
+export function cacheTotalBytes(cacheRoot: string, binPath: string): number {
+  const engine = engineFootprint(binPath, cacheRoot);
+  const realCache = existingPath(cacheRoot);
+  const outside = engine.members.filter((m) => !isInsideDir(existingPath(m), realCache));
+  return dirSizeBytes(cacheRoot) + footprintBytes(engine, outside);
+}
+
+/** Compared by target, so an outside symlink into the cache is not counted twice. */
+function existingPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
 /**
  * The Kesha-managed directories both `kesha status --disk` and `kesha doctor` report, in one
  * place so a new model dir cannot be added to only one of them. The two ASR rows are mutually
@@ -26,13 +89,19 @@ export function isInsideDir(child: string, parent: string): boolean {
  * Whatever stayed in FluidAudio's own trees is outside this cache and is reported separately
  * by `fluidExternalRoots`.
  */
-export function cacheComponentPaths(
+export function cacheComponents(
   cacheRoot: string,
-  engineDir: string,
+  binPath: string,
   coreml: boolean,
-): CachePathEntry[] {
-  return [
-    { label: "Engine", path: engineDir },
+): CacheComponentSize[] {
+  const engine = engineFootprint(binPath, cacheRoot);
+  const engineRow = {
+    label: "Engine",
+    path: engine.path,
+    exists: existsSync(engine.path),
+    sizeBytes: footprintBytes(engine, engine.members),
+  };
+  const modelRows = [
     ...(coreml
       ? [{ label: "FluidAudio (in cache)", path: join(cacheRoot, "fluidaudio") }]
       : [{ label: "ASR (Parakeet)", path: join(cacheRoot, "models/parakeet-tdt-v3") }]),
@@ -40,5 +109,6 @@ export function cacheComponentPaths(
     { label: "VAD (Silero)", path: join(cacheRoot, "models/silero-vad") },
     { label: "TTS (Kokoro)", path: join(cacheRoot, "models/kokoro-82m") },
     { label: "TTS (Vosk)", path: join(cacheRoot, "models/vosk-ru") },
-  ];
+  ].map((row) => ({ ...row, exists: existsSync(row.path), sizeBytes: dirSizeBytes(row.path) }));
+  return [engineRow, ...modelRows];
 }

package/src/cli/install.ts

@@ -86,10 +86,12 @@ export function resolveEngineVersionFlag(raw: unknown): string | undefined {
   const value = String(raw).trim();
   if (isSemver(value)) return value;
   const hint = /^v\d/.test(value)
-    ? ' Drop the leading "v" — that belongs to the release tag, not the version.'
-    : "";
-  throw new Error(
-    `--engine-version needs an exact SemVer 2.0 version like 1.24.8 or 1.24.8-alpha.1, got "${value}".${hint}`,
+    ? 'drop the leading "v" — that belongs to the release tag, not the version.'
+    : undefined;
+  throw new KeshaError(
+    "E_INVALID_ARG",
+    `--engine-version needs an exact SemVer 2.0 version like 1.24.8 or 1.24.8-alpha.1, got "${value}".`,
+    hint === undefined ? {} : { hint },
   );
 }
 

package/src/cli/main.ts

@@ -1,7 +1,6 @@
 import { defineCommand } from "citty";
 import { errorMessage } from "../error-utils";
 import { existsSync } from "fs";
-import { detectAll } from "tinyld";
 import { isDirectoryPath, transcribeWithSegments, validateTranscribeRequest } from "../transcribe";
 
 export { isDirectoryPath };
@@ -26,7 +25,7 @@ import { runCommandSession, type CommandSession } from "./command-session";
 import { USAGE_MESSAGE } from "./dispatch";
 import type { CliContext } from "./context";
 import { exitCodeFor, KeshaError } from "../engine/events";
-import { routeLanguage } from "../language-routing";
+import { detectTextLanguageFallback, routeLanguage } from "../language-routing";
 import { renderInvalidArg } from "./options";
 
 interface MainCommandArgs {
@@ -47,18 +46,7 @@ interface MainCommandArgs {
   "no-color": boolean;
 }
 
-/**
- * The CLI-side `tinyld` fallback, tagged `source: "tinyld"` so a consumer can
- * tell it apart from an Engine detection instead of reading the placeholder
- * `confidence: 0` it used to carry as a genuine zero (#941). The score is
- * tinyld's own and is not on the Engine's scale.
- */
-export function detectTextLanguageFallback(text: string): TextLangDetectResult | undefined {
-  if (!text) return undefined;
-  const [best] = detectAll(text);
-  if (!best) return undefined;
-  return { code: best.lang, confidence: best.accuracy, source: "tinyld" };
-}
+export { detectTextLanguageFallback };
 
 export function detectLanguage(text: string): string {
   return detectTextLanguageFallback(text)?.code ?? "";

package/src/doctor.ts

@@ -1,5 +1,5 @@
 import { existsSync } from "fs";
-import { cacheComponentPaths, isInsideDir } from "./cache-layout";
+import { cacheComponents, cacheTotalBytes } from "./cache-layout";
 import { errorMessage } from "./error-utils";
 import { humanBytes } from "./format";
 import { dirname, join } from "path";
@@ -270,14 +270,8 @@ function collectCache(
 ): DoctorReport["cache"] {
   const cache = keshaCacheDir();
   const binPath = getEngineBinPath();
-  const engineDir = dirname(dirname(binPath));
-  const components: CacheComponent[] = cacheComponentPaths(
-    cache,
-    engineDir,
-    isCoremlBackend(backend),
-  ).map((component) => ({ label: component.label, ...pathSummary(component.path) }));
-  const engineOutsideCache = isInsideDir(engineDir, cache) ? 0 : dirSizeBytes(engineDir);
-  const totalBytes = dirSizeBytes(cache) + engineOutsideCache;
+  const components: CacheComponent[] = cacheComponents(cache, binPath, isCoremlBackend(backend));
+  const totalBytes = cacheTotalBytes(cache, binPath);
   const externalRoots = fluidExternalRoots({ homeDir, cacheRoot: cache });
   const externalTotalBytes = fluidExternalTotalBytes(externalRoots);
 

package/src/engine/events.ts

@@ -233,6 +233,11 @@ function quoteInvalidLine(line: string): string {
   return chars.length <= MAX_QUOTED_LINE_CHARS ? line : `${chars.slice(0, MAX_QUOTED_LINE_CHARS).join("")}…`;
 }
 
+/** One wording for an off-protocol line, whether it fails the run or only warns. */
+export function offProtocolLine(command: string, line: string): string {
+  return `kesha-engine ${command} wrote a line that is not a protocol event: "${quoteInvalidLine(line)}"`;
+}
+
 /** The KeshaError for a run that wrote a non-event line, reported an error event, or exited non-zero in silence; `stderr` is the transcript unless the caller substitutes one. */
 export function engineFailure(command: string, outcome: StderrOutcome, exitCode: number | undefined, stderr = outcome.stderr.trim()): KeshaError {
   const extra = { exitCode, stderr, origin: "engine" as const };
@@ -240,7 +245,7 @@ export function engineFailure(command: string, outcome: StderrOutcome, exitCode:
     const rest = stderr.split("\n").filter((line) => !outcome.invalid.includes(line)).join("\n").trim();
     return new KeshaError(
       "E_INTERNAL",
-      `kesha-engine ${command} wrote a line that is not a protocol event: "${quoteInvalidLine(outcome.invalid[0]!)}"`,
+      offProtocolLine(command, outcome.invalid[0]!),
       { ...extra, stderr: rest },
     );
   }

package/src/engine/spawn.ts

@@ -0,0 +1,114 @@
+import { errorMessage } from "../error-utils";
+import { log } from "../log";
+import { abortOnSignal, engineAbortError, pendingInterruption, registerProcessTree } from "../process-tree";
+import { resolveStatePaths } from "../state-paths";
+import { PROTOCOL_VERSION } from "./describe";
+import { KeshaError, readEvents, type EventSinks, type StderrOutcome } from "./events";
+
+type SpawnStdioEntry = "inherit" | "pipe" | "ignore";
+type SpawnStdio = [SpawnStdioEntry, SpawnStdioEntry, SpawnStdioEntry];
+type EngineProcess = ReturnType<typeof Bun.spawn>;
+
+/** The env for a spawn whose stderr is parsed as protocol 4 events. */
+function protocolEnv(): Record<string, string | undefined> {
+  return { ...process.env, KESHA_PROTOCOL: String(PROTOCOL_VERSION) };
+}
+
+export function spawnHint(): string {
+  return process.env.KESHA_ENGINE_BIN
+    ? "KESHA_ENGINE_BIN points at it; fix the path or unset it and run `kesha install`"
+    : "run `kesha install`";
+}
+
+/** The engine reads only `KESHA_CACHE_DIR`; it gets the root the CLI resolved whenever that differs from the raw value. */
+function withResolvedCacheDir(env: Record<string, string | undefined>): Record<string, string | undefined> {
+  const cache = resolveStatePaths(env).cacheDir;
+  const raw = env.KESHA_CACHE_DIR;
+  if (cache.source === "default") {
+    if (raw === undefined) return env;
+    const { KESHA_CACHE_DIR: _empty, ...rest } = env;
+    return rest;
+  }
+  return raw === cache.path ? env : { ...env, KESHA_CACHE_DIR: cache.path };
+}
+
+/** `Bun.spawn` throws synchronously on ENOENT/EACCES; every launch failure becomes `E_ENGINE_SPAWN`. */
+function spawnEngineProcess(
+  binPath: string,
+  args: string[],
+  stdio: SpawnStdio,
+  env: Record<string, string | undefined> = process.env,
+): EngineProcess {
+  const interrupted = pendingInterruption();
+  if (interrupted) throw interrupted;
+  try {
+    // `env` is passed explicitly: Bun snapshots process.env at startup otherwise (#874).
+    return Bun.spawn([binPath, ...args], { detached: true, stdio, env: withResolvedCacheDir(env) });
+  } catch (err) {
+    throw new KeshaError("E_ENGINE_SPAWN", `failed to launch kesha-engine at ${binPath}: ${errorMessage(err)}`, {
+      hint: spawnHint(),
+    });
+  }
+}
+
+/** An engine that refuses the run before reading closes the pipe; that EPIPE is its answer, reported by the exit status and stderr. */
+async function writeEngineStdin(proc: EngineProcess, text: string): Promise<void> {
+  const sink = proc.stdin as Bun.FileSink;
+  try {
+    sink.write(text);
+    await sink.end();
+  } catch (err) {
+    log.debug(`stdin write failed: ${errorMessage(err)}`);
+  }
+}
+
+export interface EngineProcessOptions<T> {
+  /** `[stdin, stdout, stderr]`. A piped stderr is read as protocol 4 events and the engine is told so through its env. */
+  stdio: SpawnStdio;
+  /** Written to a piped stdin, which is then closed. */
+  stdin?: string;
+  /** Consumes a piped stdout; `proc` lets a relay stop the engine once nobody reads it. */
+  readStdout?: (stream: ReadableStream<Uint8Array>, proc: EngineProcess) => Promise<T>;
+  sinks?: EventSinks;
+  /** Aborting terminates the process tree, SIGKILL after a grace; an already-aborted signal is `E_INTERRUPTED` before any spawn. */
+  signal?: AbortSignal;
+}
+
+export interface EngineProcessRun<T> {
+  exitCode: number;
+  signalCode: string | null;
+  /** The signal fired while the engine ran: a caller's cancel, or a deadline it set with `AbortSignal.timeout`. */
+  aborted: boolean;
+  stdout: T;
+  events: StderrOutcome;
+}
+
+/** Spawns the engine (or a sidecar) as its own process tree and waits for it; the tree is unregistered however the run ends. */
+export async function runEngineProcess<T = undefined>(
+  binPath: string,
+  args: string[],
+  opts: EngineProcessOptions<T>,
+): Promise<EngineProcessRun<T>> {
+  if (opts.signal?.aborted) throw engineAbortError();
+  const startedAt = performance.now();
+  log.debug(`spawn ${binPath} ${args.join(" ")}`);
+  const eventsOnStderr = opts.stdio[2] === "pipe";
+  const proc = spawnEngineProcess(binPath, args, opts.stdio, eventsOnStderr ? protocolEnv() : process.env);
+  const tree = registerProcessTree(proc);
+  const cancel = abortOnSignal(tree, opts.signal);
+  try {
+    const [stdout, events, exitCode] = await Promise.all([
+      opts.readStdout?.(proc.stdout as ReadableStream<Uint8Array>, proc),
+      eventsOnStderr
+        ? readEvents(proc.stderr as ReadableStream<Uint8Array>, opts.sinks)
+        : { stderr: "", error: null, invalid: [] },
+      proc.exited,
+      opts.stdin === undefined ? undefined : writeEngineStdin(proc, opts.stdin),
+    ]);
+    log.debug(`exit=${exitCode} dt=${Math.round(performance.now() - startedAt)}ms args=${JSON.stringify(args)}`);
+    return { exitCode, signalCode: proc.signalCode, aborted: cancel.aborted, stdout: stdout as T, events };
+  } finally {
+    cancel.dispose();
+    tree.dispose();
+  }
+}

package/src/engine-health.ts

@@ -1,22 +1,14 @@
 import { existsSync } from "fs";
-import { errorMessage } from "./error-utils";
-import {
-  getDescribe,
-  getEngineBinPath,
-  spawnEngineProcess,
-  type EngineCapabilities,
-} from "./engine";
+import { ENGINE_PROBE_TIMEOUT_MS, getDescribe, getEngineBinPath, type EngineCapabilities } from "./engine";
 import { describeToCapabilities } from "./engine/describe";
 import { KeshaError } from "./engine/events";
-import { registerProcessTree } from "./process-tree";
+import { runEngineProcess } from "./engine/spawn";
 
 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).
  *
@@ -28,39 +20,32 @@ const PROBE_TIMEOUT_MS = 15_000;
  * 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.
  */
+/** Message plus hint, not the rendered error: a caller wrapping it would otherwise nest a second code line. */
+function spawnFailureDetail(err: unknown): string {
+  if (!(err instanceof Error)) return String(err);
+  return err instanceof KeshaError && err.hint ? `${err.message}; ${err.hint}` : err.message;
+}
+
 export async function probeExecutable(
   binPath: string,
   args: string[] = [],
 ): Promise<ExecutableHealth> {
   if (!existsSync(binPath)) return { status: "missing" };
 
-  let proc: ReturnType<typeof Bun.spawn>;
+  let run: Awaited<ReturnType<typeof runEngineProcess>>;
   try {
-    proc = spawnEngineProcess(binPath, args, ["ignore", "ignore", "ignore"]);
+    run = await runEngineProcess(binPath, args, {
+      stdio: ["ignore", "ignore", "ignore"],
+      signal: AbortSignal.timeout(ENGINE_PROBE_TIMEOUT_MS),
+    });
   } catch (err) {
-    return { status: "unusable", detail: errorMessage(err) };
-  }
-  const tree = registerProcessTree(proc);
-
-  let timedOut = false;
-  let forceKillTimer: Timer | undefined;
-  const timer = setTimeout(() => {
-    timedOut = true;
-    tree.terminate();
-    forceKillTimer = tree.forceKillAfterGrace();
-  }, PROBE_TIMEOUT_MS);
-  try {
-    await proc.exited;
-  } finally {
-    clearTimeout(timer);
-    tree.dispose();
-    if (!timedOut && forceKillTimer) clearTimeout(forceKillTimer);
+    return { status: "unusable", detail: spawnFailureDetail(err) };
   }
 
-  if (timedOut) {
-    return { status: "unusable", detail: `no exit within ${PROBE_TIMEOUT_MS / 1000}s` };
+  if (run.aborted) {
+    return { status: "unusable", detail: `no exit within ${ENGINE_PROBE_TIMEOUT_MS / 1000}s` };
   }
-  if (proc.signalCode) return { status: "unusable", detail: `killed by ${proc.signalCode}` };
+  if (run.signalCode) return { status: "unusable", detail: `killed by ${run.signalCode}` };
   return { status: "ok" };
 }
 
@@ -73,36 +58,20 @@ export async function probeExecutable(
  */
 export async function readExecutableVersion(
   binPath: string,
-  timeoutMs = PROBE_TIMEOUT_MS,
+  timeoutMs = ENGINE_PROBE_TIMEOUT_MS,
 ): Promise<string | null> {
   if (!existsSync(binPath)) return null;
 
-  let proc: ReturnType<typeof Bun.spawn>;
+  let stdout: string;
   try {
-    proc = spawnEngineProcess(binPath, ["--version"], ["ignore", "pipe", "ignore"]);
+    ({ stdout } = await runEngineProcess(binPath, ["--version"], {
+      stdio: ["ignore", "pipe", "ignore"],
+      readStdout: (stream) => new Response(stream).text(),
+      signal: AbortSignal.timeout(timeoutMs),
+    }));
   } catch {
     return null;
   }
-  const tree = registerProcessTree(proc);
-
-  let timedOut = false;
-  let forceKillTimer: Timer | undefined;
-  const timer = setTimeout(() => {
-    timedOut = true;
-    tree.terminate();
-    forceKillTimer = tree.forceKillAfterGrace();
-  }, timeoutMs);
-  let stdout: string;
-  try {
-    [stdout] = await Promise.all([
-      new Response(proc.stdout as ReadableStream<Uint8Array>).text(),
-      proc.exited,
-    ]);
-  } finally {
-    clearTimeout(timer);
-    tree.dispose();
-    if (!timedOut && forceKillTimer) clearTimeout(forceKillTimer);
-  }
   return /(\d+\.\d+\.\d+[0-9A-Za-z.+-]*)/.exec(stdout)?.[1] ?? null;
 }
 
@@ -132,7 +101,7 @@ const MUTE_DETAIL = "reports no capabilities";
  * that could not be made to answer (`unusable`), not one that answered nothing (`mute`).
  */
 export async function engineFunctionalHealth(
-  timeoutMs = PROBE_TIMEOUT_MS,
+  timeoutMs = ENGINE_PROBE_TIMEOUT_MS,
 ): Promise<EngineFunctionalHealth> {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);