@drakulavich/kesha-voice-kit 2.1.0 → 2.2.0-beta.1

package/README.md

@@ -11,9 +11,9 @@
   <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun" alt="Bun"></a>
 </p>
 
-<p align="center"><b>Give your local tools and LLM agents a voice.</b><br>Fast speech-to-text, text-to-speech, voice-activity detection, and language detection in one local-first CLI — CoreML on Apple Silicon, ONNX on Linux and Windows.</p>
+<p align="center"><b>Kesha listens and talks back.</b><br>Your agent gets a voice message, Kesha turns it into text on your machine, and speaks the reply once you add <code>kesha install --tts</code> (<a href="docs/use-cases.md#sending-voice-replies">voice replies</a>). Fastest on Apple Silicon with CoreML, and it runs on Linux and Windows through ONNX.</p>
 
-- **Transcribe locally** — [25 languages](docs/languages.md#speech-to-text-25), up to ~19x faster than Whisper on Apple Silicon, ~2.5x on CPU
+- **Transcribe locally** — [25 languages](docs/languages.md#speech-to-text-25), up to ~19x faster than Whisper on Apple Silicon, ~10x on an x86 CPU
 - **Speak back** — text-to-speech in [9 languages](docs/languages.md#text-to-speech)
 - **Plug into agents** — ship voice workflows as CLI commands, an MCP server, an <a href="docs/openclaw.md">OpenClaw</a> skill, or a <a href="docs/hermes.md">Hermes</a> agent
 - **Small Rust engine** — single ~65MB binary, no ffmpeg, no Python, no native Node addons
@@ -24,7 +24,7 @@
 
 ## Quick Start
 
-Runtime: **[Bun](https://bun.sh)** >= 1.3.0.
+Runtime: **[Bun](https://bun.sh)** >= 1.4.0.
 
 ```bash
 # 1. Install Bun (skip if you have it)
@@ -64,6 +64,14 @@ All three targets transcribe, detect the spoken language, run VAD, and speak. Th
 
 Intel Macs get no published engine binary. Full matrix with maturity labels: [docs/product-positioning.md](docs/product-positioning.md#platform-matrix).
 
+## Plug into your agent
+
+- **MCP server** — `kesha mcp` exposes transcribe/synthesize/list tools to any MCP client (Claude, Cursor, Codex, Gemini). Setup: [docs/mcp.md](docs/mcp.md).
+- **OpenClaw** — give your LLM agent ears. Install & config: [docs/openclaw.md](docs/openclaw.md).
+- **Hermes Agent** — local STT/TTS through Hermes command providers. Setup: [docs/hermes.md](docs/hermes.md).
+- **Raycast** (macOS) — offline microphone dictation from the launcher: *Dictate to Clipboard* records with a live signal meter, auto-stops on silence, transcribes locally, and copies the text. [Install from the Raycast Store](https://www.raycast.com/drakulavich/kesha-voice-kit) · source: [`raycast/`](raycast/).
+- **Programmatic API** — `@drakulavich/kesha-voice-kit/core` for use inside a Bun program. See [docs/api.md](docs/api.md).
+
 ## Speech-to-text
 
 ```bash
@@ -126,13 +134,13 @@ kesha say "Hello" --format flac --out hi.flac     # FLAC — lossless, plays in
 
 ## Performance
 
-> **Up to ~19x faster than Whisper** on Apple Silicon (M2), **~2.5x faster** on CPU
+> **Up to ~19x faster than Whisper** on Apple Silicon (M2), **~10x faster** on an x86 Linux CPU (~2.5x faster than faster-whisper)
 
 Compared against Whisper `large-v3-turbo`, all engines auto-detecting language:
 
 ![Benchmark: openai-whisper vs faster-whisper vs Kesha Voice Kit](https://github.com/drakulavich/kesha-voice-kit/raw/main/docs/assets/benchmark.svg)
 
-Full per-file breakdown (Russian + English): [BENCHMARK.md](BENCHMARK.md). The CPU figure is the ONNX engine on an M2's CPU cores; no x86 numbers are published yet.
+Full per-file breakdown (Russian + English): [BENCHMARK.md](BENCHMARK.md). The chart is from an M2. The x86 figure comes from a GitHub-hosted `ubuntu-latest` runner (AMD EPYC, ONNX on CPU), where openai-whisper runs in FP32.
 
 ## Other install methods
 
@@ -144,14 +152,6 @@ All of these install the Bun CLI wrapper; engine + models still download explici
 - **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
-
-- **MCP server** — `kesha mcp` exposes transcribe/synthesize/list tools to any MCP client (Claude, Cursor, Codex, Gemini). Setup: [docs/mcp.md](docs/mcp.md).
-- **OpenClaw** — give your LLM agent ears. Install & config: [docs/openclaw.md](docs/openclaw.md).
-- **Hermes Agent** — local STT/TTS through Hermes command providers. Setup: [docs/hermes.md](docs/hermes.md).
-- **Raycast** (macOS) — offline microphone dictation from the launcher: *Dictate to Clipboard* records with a live signal meter, auto-stops on silence, transcribes locally, and copies the text. [Install from the Raycast Store](https://www.raycast.com/drakulavich/kesha-voice-kit) · source: [`raycast/`](raycast/).
-- **Programmatic API** — `@drakulavich/kesha-voice-kit/core` for use inside a Bun program. See [docs/api.md](docs/api.md).
-
 ## More
 
 - [Architecture](docs/architecture.md) — runtime data flow, the models that ship, the CLI ↔ Rust engine boundary, model pinning, and where tests live.

package/docs/product-positioning.md

@@ -1,6 +1,6 @@
 # Product positioning
 
-Kesha Voice Kit is a local-first voice toolkit for developers and agent workflows. It is built for small, scriptable jobs where a CLI can turn audio into text, text into audio, or voice messages into structured data without sending content to a hosted API.
+Kesha listens and talks back: an agent gets a voice message, Kesha turns it into text locally, and speaks the reply. It is a local-first voice toolkit for developers and agent workflows, and Apple Silicon is where it is fastest and most complete. It is built for small, scriptable jobs where a CLI can turn audio into text, text into audio, or voice messages into structured data without sending content to a hosted API.
 
 The product promise is not "one model for every audio problem." The promise is a boring, automatable local voice stack with clear platform limits, predictable install paths, and machine-readable output.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "2.1.0",
-  "description": "Give your tools a voice — speech to text and back, 25 languages, up to ~19× faster than Whisper. On your machine.",
+  "version": "2.2.0-beta.1",
+  "description": "Kesha listens and talks back: local speech to text and text to speech for agents and scripts, fastest on Apple Silicon.",
   "type": "module",
   "bin": {
     "kesha": "bin/kesha.js"
@@ -54,7 +54,7 @@
     "check": "bun run lint && bun run check:versions && bun run check:recipes && bun run test:cli-fast",
     "check:workflows": "bun .github/scripts/check-workflows.ts",
     "check:recipes": "bun .github/scripts/check-recipes.ts",
-    "check:specs": "bunx @fission-ai/openspec@1.4.1 validate --specs --strict",
+    "check:specs": "openspec validate --specs --strict",
     "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",
@@ -83,9 +83,10 @@
     "url": "https://github.com/drakulavich/kesha-voice-kit/issues"
   },
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.4.0"
   },
   "devDependencies": {
+    "@fission-ai/openspec": "1.14.1",
     "@types/bun": "latest",
     "fast-xml-parser": "^5.8.0",
     "typescript": "^7.0.2",
@@ -93,7 +94,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.5.0",
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@toon-format/toon": "^4.1.0",
     "citty": "^0.2.2",
     "fastest-levenshtein": "^1.0.16",
@@ -109,19 +110,19 @@
   },
   "kesha": {
     "engine": {
-      "version": "2.1.0",
+      "version": "2.2.0-beta.1",
       "sha256": {
-        "kesha-engine-darwin-arm64": "51446285f272a3d5060aa2dd21d2d16a5c31682a8554f29c944fe1af27677008",
-        "kesha-engine-linux-x64": "8728b467ca31640739dcbe18e53eadd27e795033075f6442fc14b729e0014a62",
-        "kesha-engine-windows-x64.exe": "82515821a6b424ff9c75462721f7723891705a2f1edcba0a1eb5c1704cfadbec",
-        "say-avspeech-darwin-arm64": "a3aa5b75ddff68a48f1158e838310b37cac72ef86841d9cfcdf1ee233cb7451a",
+        "kesha-engine-darwin-arm64": "ccdd35b2433950175a6e3791ac3264969a732ea005fae4642b32842b2eb3443b",
+        "kesha-engine-linux-x64": "626fd32be46645e312ae3ad4cdf15838d0c4f54d56bdc67ec6d8f2a017813db8",
+        "kesha-engine-windows-x64.exe": "b38bc35bc2d0304f324da02b1d2857e86baf3c69e5351e5df2619c1c3a38889a",
+        "say-avspeech-darwin-arm64": "3a7e8b8fac92ce4ce0c34f736098a685dcb745f741db8303e1721e320ac73a98",
         "kesha-textlang-darwin-arm64": "e45e2822248b14dd72aa79e2def8fa6b9c07c97423f11c841508769225d72da4"
       },
       "size": {
-        "kesha-engine-darwin-arm64": 73639664,
-        "kesha-engine-linux-x64": 67394344,
-        "kesha-engine-windows-x64.exe": 66586112,
-        "say-avspeech-darwin-arm64": 64208,
+        "kesha-engine-darwin-arm64": 73639712,
+        "kesha-engine-linux-x64": 67404584,
+        "kesha-engine-windows-x64.exe": 66583040,
+        "say-avspeech-darwin-arm64": 82992,
         "kesha-textlang-darwin-arm64": 57648
       }
     }

package/src/cli/dispatch.ts

@@ -1,10 +1,12 @@
-import { runMain, type ArgsDef, type CommandDef } from "citty";
+import { renderUsage, runMain, type ArgsDef, type CommandDef } from "citty";
 import { existsSync } from "fs";
-import { log } from "../log";
+import { stripVTControlCharacters } from "util";
+import { isColorEnabled, log } from "../log";
+import { packageVersion } from "../package-info";
 import { guardStdoutWrites } from "../stdout-pipe";
 import { suggestCommand } from "../suggest-command";
 import { applyCliContext, resolveCliContext } from "./context";
-import { rejectUnknownOptions, renderInvalidArg } from "./options";
+import { rejectExtraPositionals, rejectUnknownOptions, renderInvalidArg } from "./options";
 
 // Lazy loaders so a cold CLI spawn transpiles only the invoked command, not the whole graph (#568).
 // `CommandDef<any>`: citty's generic is invariant in the arg shape and each command has its own schema.
@@ -87,7 +89,12 @@ export function unknownCommandMessages(token: string, subcommandKeys: string[]):
   if (suggestCommand(token, ["transcribe"]) === "transcribe") {
     warnLines.push("To transcribe, pass the audio path directly: kesha ./recording.ogg");
   }
-  return { errorLine: `unknown command '${token}'`, warnLines };
+  return { errorLine: renderInvalidArg(`unknown command '${token}'`), warnLines };
+}
+
+async function showUsage<T extends ArgsDef>(cmd: CommandDef<T>, parent?: CommandDef<T>): Promise<void> {
+  const usage = await renderUsage(cmd, parent);
+  console.log((isColorEnabled() ? usage : stripVTControlCharacters(usage)) + "\n");
 }
 
 async function resolveArgsDef(command: CommandDef<any>): Promise<ArgsDef> {
@@ -121,9 +128,15 @@ export async function runCli(argv = process.argv.slice(2)): Promise<void> {
 
   switch (classifyFirstArg(firstArg, subcommandKeys)) {
     case "subcommand": {
+      if (restArgs.length === 1 && (restArgs[0] === "--version" || restArgs[0] === "-v")) {
+        process.stdout.write(`${packageVersion}\n`);
+        return;
+      }
       const command = await SUBCOMMANDS[firstArg!]!();
-      rejectUnknownOptions(restArgs, await resolveArgsDef(command));
-      await runMain(command, { rawArgs: restArgs });
+      const argsDef = await resolveArgsDef(command);
+      rejectUnknownOptions(restArgs, argsDef);
+      if (firstArg !== "install" && firstArg !== "say") rejectExtraPositionals(restArgs, argsDef);
+      await runMain(command, { rawArgs: restArgs, showUsage });
       return;
     }
 
@@ -132,7 +145,7 @@ export async function runCli(argv = process.argv.slice(2)): Promise<void> {
       const { errorLine, warnLines } = unknownCommandMessages(firstArg!, subcommandKeys);
       log.error(errorLine);
       for (const line of warnLines) log.warn(line);
-      process.exit(1);
+      process.exit(2);
       break;
     }
 
@@ -142,10 +155,15 @@ export async function runCli(argv = process.argv.slice(2)): Promise<void> {
         log.error(renderInvalidArg(`put global flags after the subcommand: kesha ${misplaced} ...`));
         process.exit(2);
       }
-      const { createMainCommand } = await import("./main");
+      const { briefMainUsage, createMainCommand } = await import("./main");
       const command = createMainCommand(context);
-      rejectUnknownOptions(rawArgs, await resolveArgsDef(command));
-      await runMain(command, { rawArgs });
+      const help = rawArgs.includes("--help") || rawArgs.includes("-h");
+      rejectUnknownOptions(help ? rawArgs.filter((arg) => arg !== "--all") : rawArgs, await resolveArgsDef(command));
+      if (help) {
+        await showUsage(rawArgs.includes("--all") ? command : briefMainUsage(command));
+        return;
+      }
+      await runMain(command, { rawArgs, showUsage });
     }
   }
 }

package/src/cli/init.ts

@@ -3,7 +3,7 @@ import { confirm, multiselect, isCancel, cancel } from "@clack/prompts";
 import { installCommandTokens, renderInstallPlan } from "../install-plan";
 import { log } from "../log";
 import { errorMessage } from "../error-utils";
-import { exitCodeFor } from "../engine/events";
+import { exitCodeFor, KeshaError } from "../engine/events";
 import { getEngineCapabilities } from "../engine";
 import {
   installableTtsLangs,
@@ -98,30 +98,6 @@ export function initInstallArgs(selection: InitSelection): string[] {
   return installCommandTokens(selection, selection.ttsLangs);
 }
 
-export function initSuggestionCommands(
-  selection: InitSelection,
-  canDiarize = canInstallDiarizeOnPlatform(),
-): string[][] {
-  const variants: InitSelection[] = [
-    selection,
-    { ...selection, ttsLangs: [], vad: true, diarize: false },
-    { ...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: false, diarize: true });
-  }
-
-  const seen = new Set<string>();
-  return variants.map(initInstallArgs).filter((command) => {
-    const key = command.join("\0");
-    if (seen.has(key)) return false;
-    seen.add(key);
-    return true;
-  });
-}
-
 export function omitUnsupportedDiarize(
   selection: InitSelection,
   canDiarize = canInstallDiarizeOnPlatform(),
@@ -188,20 +164,6 @@ async function printPlan(selection: InitSelection): Promise<void> {
   );
 }
 
-async function runNonInteractive(selection: InitSelection): Promise<void> {
-  const canDiarize = canInstallDiarizeOnPlatform();
-  const printableSelection = omitUnsupportedDiarize(selection, canDiarize);
-  if (selection.diarize && !canDiarize) {
-    log.warn("--diarize is currently darwin-arm64 only; omitting it from non-interactive examples.");
-  }
-  log.info(renderInitOverview(canDiarize));
-  await printPlan(printableSelection);
-  log.info("Run one of these commands from an interactive terminal:");
-  for (const command of initSuggestionCommands(printableSelection, canDiarize)) {
-    log.info(`  ${command.join(" ")}`);
-  }
-}
-
 export const initCommand = defineCommand({
   meta: {
     name: "init",
@@ -279,7 +241,11 @@ export const initCommand = defineCommand({
     const stdinIsTty = process.stdin.isTTY === true;
     const stdoutIsTty = process.stdout.isTTY === true;
     if (!stdinIsTty || !stdoutIsTty) {
-      await runNonInteractive(selection);
+      const noTerminal = new KeshaError("E_INVALID_ARG", "kesha init is interactive and needs a terminal", {
+        hint: "run `kesha init --yes` to install the defaults, or `kesha init --plan` to show the plan",
+      });
+      log.error(errorMessage(noTerminal));
+      process.exitCode = exitCodeFor(noTerminal);
       return;
     }
 

package/src/cli/logs.ts

@@ -23,6 +23,9 @@ export function runLogsAction(args: LogsCommandArgs): ActionResult {
   if (args.json && action !== "status") {
     return { ok: false, error: "usage: kesha logs status --json" };
   }
+  if (args.value !== undefined && action !== "mode" && SUPPORTED_ACTIONS.split(", ").includes(action)) {
+    return { ok: false, error: `unexpected argument '${args.value}' (kesha logs ${action} takes no value)` };
+  }
   switch (action) {
     case "enable": {
       const status = setDiagnosticLogMode("on");

package/src/cli/main.ts

@@ -1,10 +1,13 @@
-import { defineCommand } from "citty";
+import { defineCommand, type ArgsDef, type CommandDef } from "citty";
 import { errorMessage } from "../error-utils";
 import { existsSync } from "fs";
 import { isDirectoryPath, transcribeWithSegments, validateTranscribeRequest } from "../transcribe";
 
 export { isDirectoryPath };
-import { detectAudioLanguageEngine, detectTextLanguageEngine } from "../engine";
+import { detectAudioLanguageEngine, detectTextLanguageEngine, isEngineInstalled } from "../engine";
+import { renderInstallPlan } from "../install-plan";
+import { canInstallDiarizeOnPlatform, promptConfirm } from "./init";
+import { performInstall } from "./install";
 import type { LangDetectResult } from "../engine";
 import { log } from "../log";
 import type { TextLangDetectResult, TranscribeErrorRecord, TranscribeResult } from "../types";
@@ -409,7 +412,8 @@ async function processFile(
       error_code: code,
     });
     log.error(`${file}: ${stderrText}`);
-    return { ok: false, error: { file, code, message: stderrText }, exitCode: failureExitCode(err) };
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: { file, code, message }, exitCode: failureExitCode(err) };
   }
 }
 
@@ -452,13 +456,41 @@ export const MAIN_VAD_ARGS = {
   },
 } as const;
 
+const BRIEF_HELP_DESCRIPTION =
+  "Kesha Voice Kit listens and talks back: local speech for agents and scripts.\n" +
+  "Try: kesha audio.ogg, or kesha say \"hello\"\n" +
+  "\n" +
+  "Commands:\n" +
+  "  init      Interactive setup guide.\n" +
+  "  install   Download engine and models.\n" +
+  "  say       Synthesize speech from text.\n" +
+  "  record    Record microphone audio.\n" +
+  "  status    Inspect installed backend.\n" +
+  "  doctor    Collect support diagnostics.\n" +
+  "  mcp       Run an MCP server over stdio.\n" +
+  "\n" +
+  "All commands and flags: kesha --help --all";
+
+const BRIEF_HELP_ARGS: ArgsDef = {
+  json: { type: "boolean", description: "Output results as JSON" },
+  format: { type: "string", description: "transcript | json | toon" },
+  lang: { type: "string", description: "Expected language code, e.g. en" },
+  timestamps: { type: "boolean", description: "Timestamped segments in JSON/TOON" },
+  quiet: { type: "boolean", alias: "q", description: "Print only results and errors" },
+};
+
+/** What plain `kesha --help` renders; parsing still uses every flag of createMainCommand. */
+export function briefMainUsage(command: CommandDef<any>): CommandDef<any> {
+  return { ...command, meta: { ...command.meta, description: BRIEF_HELP_DESCRIPTION }, args: BRIEF_HELP_ARGS };
+}
+
 export function createMainCommand(context: CliContext = { quiet: false, disableColor: false }) {
   return defineCommand({
     meta: {
       name: "kesha",
       version: packageVersion,
       description:
-        "Kesha Voice Kit — open-source voice toolkit for Apple Silicon.\n" +
+        "Kesha Voice Kit listens and talks back: local speech for agents and scripts.\n" +
         "\n" +
         "Examples:\n" +
         "  kesha audio.ogg          Transcribe an audio file.\n" +
@@ -572,6 +604,19 @@ export function createMainCommand(context: CliContext = { quiet: false, disableC
         process.exit(2);
       }
 
+      if (
+        !isEngineInstalled() &&
+        process.stdin.isTTY && process.stdout.isTTY && process.stderr.isTTY &&
+        files.every((f) => existsSync(f) && !isDirectoryPath(f)) &&
+        (!args.speakers || canInstallDiarizeOnPlatform())
+      ) {
+        const modules = { vad: vadMode === "on", diarize: Boolean(args.speakers) };
+        log.info(await renderInstallPlan(modules));
+        if (await promptConfirm("Kesha needs these downloads before it can transcribe. Download them now?", true)) {
+          await performInstall({ noCache: false, ttsLangs: [], ...modules });
+        }
+      }
+
       const wantsLangId = !!(args.lang || args.verbose || outputFormat !== "text");
       const reportProgress = shouldReportTranscribeProgress({
         stderrIsTty: process.stderr.isTTY === true,

package/src/cli/options.ts

@@ -17,6 +17,10 @@ function camelCase(name: string): string {
 
 /** The first flag `argsDef` does not declare, or null; citty parses non-strict, so the flag would otherwise vanish and its value become a positional (S9-F3). */
 export function findUnknownOption(rawArgs: string[], argsDef: ArgsDef): UnknownOption | null {
+  return scanArgs(rawArgs, argsDef).unknown;
+}
+
+function scanArgs(rawArgs: string[], argsDef: ArgsDef): { unknown: UnknownOption | null; positionals: string[] } {
   const long = new Set(RUNNER_LONG);
   const short = new Set(RUNNER_SHORT);
   const valued = new Set<string>();
@@ -41,23 +45,30 @@ export function findUnknownOption(rawArgs: string[], argsDef: ArgsDef): UnknownO
     const match = suggestCommand(name, suggestable);
     return match === null ? null : `--${match}`;
   };
+  const positionals: string[] = [];
   for (let i = 0; i < rawArgs.length; i++) {
     const arg = rawArgs[i]!;
-    if (arg === "--") break;
-    if (!arg.startsWith("-") || arg === "-" || /^-\d/.test(arg)) continue;
+    if (arg === "--") {
+      positionals.push(...rawArgs.slice(i + 1));
+      break;
+    }
+    if (!arg.startsWith("-") || arg === "-" || /^-\d/.test(arg)) {
+      positionals.push(arg);
+      continue;
+    }
     if (arg.startsWith("--")) {
       const eq = arg.indexOf("=");
       const name = eq === -1 ? arg.slice(2) : arg.slice(2, eq);
-      if (!long.has(name)) return { name: `--${name}`, suggestion: suggest(name) };
+      if (!long.has(name)) return { unknown: { name: `--${name}`, suggestion: suggest(name) }, positionals };
       if (eq === -1 && valued.has(name)) i++;
       continue;
     }
     for (const letter of arg.slice(1)) {
-      if (!short.has(letter)) return { name: `-${letter}`, suggestion: null };
+      if (!short.has(letter)) return { unknown: { name: `-${letter}`, suggestion: null }, positionals };
     }
     if (valued.has(arg[arg.length - 1]!)) i++;
   }
-  return null;
+  return { unknown: null, positionals };
 }
 
 /** The coded line for a usage error the CLI refuses before doing anything (S9-F2). */
@@ -77,3 +88,13 @@ export function rejectUnknownOptions(rawArgs: string[], argsDef: ArgsDef): void
   log.error(renderUnknownOption(unknown));
   process.exit(2);
 }
+
+/** Exits 2 with one coded stderr line when `rawArgs` carries more positionals than the command declares. */
+export function rejectExtraPositionals(rawArgs: string[], argsDef: ArgsDef): void {
+  const declared = Object.values(argsDef).filter((def) => def.type === "positional").length;
+  const extra = scanArgs(rawArgs, argsDef).positionals[declared];
+  if (extra === undefined) return;
+  const tail = "output" in argsDef ? ` (did you mean --output ${extra}?)` : "";
+  log.error(renderInvalidArg(`unexpected argument '${extra}'${tail}`));
+  process.exit(2);
+}

package/src/cli/say.ts

@@ -358,8 +358,8 @@ export const sayCommand = defineCommand({
         log.error(errorMessage(err));
         process.exit(exitCodeFor(err));
       }
-      await Bun.write(Bun.stdout, ids.map((id) => `${id}\n`).join(""));
-      process.exit(0);
+      process.stdout.write(ids.map((id) => `${id}\n`).join(""));
+      return;
     }
 
     const flags = resolveSayFlags(args);
@@ -374,23 +374,26 @@ export const sayCommand = defineCommand({
       process.exit(2);
     }
 
-    const inlineText = typeof args.text === "string" ? args.text : undefined;
+    const positionals = (args._ ?? []).map(String);
+    const inlineText =
+      positionals.length > 0 ? positionals.join(" ") : typeof args.text === "string" ? args.text : undefined;
     const stdinIsTty = (process.stdin as { isTTY?: boolean }).isTTY;
     if (shouldRejectMissingSayText(inlineText, stdinIsTty)) {
       log.error(renderInvalidArg("kesha say requires text or piped stdin. Usage: kesha say <text>"));
       process.exit(2);
     }
+    const explicitVoice = flags.voice;
+    const langHint = flags.lang;
     let text: string;
+    let voice: string | undefined;
     try {
       text = await resolveText(inlineText);
       validateSayText(text);
+      voice = await resolveSayVoice(explicitVoice, langHint, text);
     } catch (err) {
       log.error(errorMessage(err));
       process.exit(exitCodeFor(err));
     }
-    const explicitVoice = flags.voice;
-    const langHint = flags.lang;
-    const voice = await resolveSayVoice(explicitVoice, langHint, text);
 
     const opts: SayOpts = {
       text,

package/src/cli/stats.ts

@@ -26,6 +26,14 @@ const SUPPORTED_ACTIONS = "enable, disable, status, week, errors, export, reset,
 /** Runs one `kesha stats` action and reports what to print; all output happens in the caller. */
 export function runStatsAction(args: StatsCommandArgs): ActionResult {
   const action = args.action ?? "status";
+  if (
+    args.value !== undefined &&
+    action !== "export" &&
+    action !== "retention" &&
+    SUPPORTED_ACTIONS.split(", ").includes(action)
+  ) {
+    return { ok: false, error: `unexpected argument '${args.value}' (kesha stats ${action} takes no value)` };
+  }
   switch (action) {
     case "enable": {
       enableStats();

package/src/cli/support-bundle.ts

@@ -27,14 +27,23 @@ export const supportBundleCommand = defineCommand({
   },
   async run({ args }: { args: SupportBundleCommandArgs }) {
     try {
+      if (args.output === "") {
+        throw new KeshaError("E_INVALID_ARG", "--output needs a file path", { hint: "pass --output path.tar.gz." });
+      }
+      if (args.output === "-") {
+        throw new KeshaError("E_INVALID_ARG", "--output - is not a file path", {
+          hint: "to write the archive to stdout, pass --output /dev/stdout.",
+        });
+      }
       const bundle = await createSupportBundle({
         output: args.output,
         includeLogs: Boolean(args["include-logs"]),
       });
-      log.status(`Created support bundle: ${bundle.path}`);
+      log.notice(`Created support bundle: ${bundle.path}`);
       log.status(`Entries: ${bundle.entries.length}`);
       log.status(`Size: ${bundle.sizeBytes} bytes`);
     } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "EPIPE") return;
       log.error(errorMessage(err));
       process.exit(err instanceof KeshaError ? exitCodeFor(err) : 1);
     }

package/src/cli.ts

@@ -9,7 +9,6 @@ export {
   canInstallDiarizeOnPlatform,
   initCommand,
   initInstallArgs,
-  initSuggestionCommands,
   omitUnsupportedDiarize,
   promptInitSelection,
   renderInitOverview,

package/src/doctor.ts

@@ -10,7 +10,7 @@ import {
   NOT_FUNCTIONAL_STATE,
   probeExecutable,
 } from "./engine-health";
-import { readInstalledEngineVersion } from "./engine-version-marker";
+import { MIN_ENGINE_VERSION, predatesMinimumEngine, readInstalledEngineVersion } from "./engine-version-marker";
 import { keshaCacheDir } from "./paths";
 import { installedVoiceIds } from "./voice-inventory";
 import { engineVersion, packageName, packageVersion } from "./package-info";
@@ -85,13 +85,14 @@ type DoctorDiagnosticLogStatus = DiagnosticLogStatus & { error?: string };
  * is a supported state (`kesha install --engine-version`), not a fault — `unrecorded` is
  * separate so a missing marker is never reported as a difference.
  */
-export type EngineVersionState = "matches-pin" | "differs-from-pin" | "unrecorded";
+export type EngineVersionState = "matches-pin" | "differs-from-pin" | "unsupported" | "unrecorded";
 
 export function engineVersionState(
   versionMarker: string | null,
   pinnedVersion: string,
 ): EngineVersionState {
   if (versionMarker === null) return "unrecorded";
+  if (predatesMinimumEngine(versionMarker)) return "unsupported";
   return versionMarker === pinnedVersion ? "matches-pin" : "differs-from-pin";
 }
 
@@ -477,6 +478,11 @@ function formatVersionState(engine: DoctorReport["engine"]): string {
         `installed v${engine.versionMarker} differs from the pinned v${engine.pinnedVersion} — ` +
         "supported; `kesha install` without --engine-version restores the pin"
       );
+    case "unsupported":
+      return (
+        `installed v${engine.versionMarker} is older than v${MIN_ENGINE_VERSION}, ` +
+        "the oldest engine this CLI supports; run `kesha install`"
+      );
     case "unrecorded":
       return engine.installed
         ? "no recorded version beside the binary; `kesha install` records one"

package/src/engine/events.ts

@@ -128,7 +128,8 @@ export class KeshaError extends Error {
     const transcript = this.stderr?.trim();
     if (!transcript) return renderError(this);
     const line = renderError(this).split("\n")[0] ?? "";
-    return transcript.split("\n").some((l) => l === line) ? transcript : `${renderError(this)}\n${transcript}`;
+    if (!transcript.split("\n").some((l) => l === line)) return `${renderError(this)}\n${transcript}`;
+    return this.hint && !transcript.includes(`  hint: ${this.hint}`) ? `${transcript}\n  hint: ${this.hint}` : transcript;
   }
 }
 

package/src/engine-version-marker.ts

@@ -1,4 +1,12 @@
 import { readFileSync, writeFileSync } from "fs";
+import { cmp, parseSemver, tryParseSemver } from "./semver.mjs";
+
+export const MIN_ENGINE_VERSION = "1.26.0";
+
+export function predatesMinimumEngine(version: string): boolean {
+  const parsed = tryParseSemver(version);
+  return parsed !== null && cmp(parsed, parseSemver(MIN_ENGINE_VERSION, "MIN_ENGINE_VERSION")) < 0;
+}
 
 /**
  * Version-marker file written next to the engine binary on download (#151).

package/src/engine.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from "child_process";
 import { existsSync, statSync, type Stats } from "fs";
 import { errorMessage } from "./error-utils";
 import { join } from "path";
@@ -8,6 +9,7 @@ import { defaultEngineBinPath, keshaCacheDir } from "./paths";
 import { engineAbortError, interruptedRun } from "./process-tree";
 import { runEngineProcess, spawnHint } from "./engine/spawn";
 import { engineFailure, KeshaError, renderError, type ErrorEvent } from "./engine/events";
+import { MIN_ENGINE_VERSION, predatesMinimumEngine, readInstalledEngineVersion } from "./engine-version-marker";
 import {
   describeToCapabilities,
   parseDescribe,
@@ -124,6 +126,16 @@ function failed(run: EngineRun): boolean {
   return reportedFailure(run) || run.invalid.length > 0;
 }
 
+function assertEngineSupported(binPath: string): void {
+  const installed = readInstalledEngineVersion(binPath);
+  if (installed === null || !predatesMinimumEngine(installed)) return;
+  throw new KeshaError(
+    "E_ENGINE_PROTOCOL",
+    `kesha-engine at ${binPath} is v${installed}; this CLI needs v${MIN_ENGINE_VERSION} or newer`,
+    { hint: "run `kesha install` to fetch the engine this CLI expects", versionMismatch: true },
+  );
+}
+
 let cachedDescribe: { identity: string; doc: DescribeDocument } | null = null;
 
 /** ctime is part of it because utimes cannot set it back after a replacement that restores mtime (#1256, #1258). */
@@ -142,6 +154,7 @@ export async function getDescribe(opts: RunEngineOptions = {}): Promise<Describe
       hint: spawnHint(),
     });
   }
+  assertEngineSupported(binPath);
   if (cachedDescribe?.identity === identity) return cachedDescribe.doc;
   const run = await runEngine(["describe"], opts);
   let doc: DescribeDocument | null = null;
@@ -295,10 +308,29 @@ export function buildTranscribeArgs(
   return args;
 }
 
+function hostIsVirtualMac(): boolean {
+  return spawnSync("sysctl", ["-n", "kern.hv_vmm_present"], { encoding: "utf8" }).stdout?.trim() === "1";
+}
+
+/** CoreML transcription is unreliable without an Apple Neural Engine, which no virtualised Mac has (#1419); synthesis says the same (#742). */
+export function withVirtualMacHint(
+  err: KeshaError,
+  platform: string = process.platform,
+  isVirtualMac: () => boolean = hostIsVirtualMac,
+): KeshaError {
+  if (platform !== "darwin" || err.hint || !err.message.includes("Swift bridge error") || !isVirtualMac()) return err;
+  return new KeshaError(err.code, err.message, {
+    exitCode: err.exitCode,
+    stderr: err.stderr,
+    origin: err.origin,
+    hint: "this is a virtualised Mac with no Apple Neural Engine, where CoreML transcription is unreliable; transcribe on a physical Mac, or on Linux or Windows",
+  });
+}
+
 export async function transcribeEngine(audioPath: string, opts: TranscribeEngineOptions = {}): Promise<string> {
   const args = await validatedArgs(buildTranscribeArgs(audioPath, opts), { signal: opts.signal });
   const run = await runEngine(args, { signal: opts.signal, onProgressLine: opts.onProgressLine });
-  if (failed(run)) throw engineFailure(args[0] ?? "", run, run.exitCode);
+  if (failed(run)) throw withVirtualMacHint(engineFailure(args[0] ?? "", run, run.exitCode));
   return run.stdout;
 }
 
@@ -356,7 +388,7 @@ export async function transcribeEngineWithSegments(
   const args = await validatedArgs(buildTranscribeArgs(audioPath, opts, true), { signal: opts.signal });
   if (opts.speakers) assertSpeakerModelsInstalled();
   const run = await runEngine(args, { signal: opts.signal, onProgressLine: opts.onProgressLine });
-  if (failed(run)) throw engineFailure(args[0] ?? "", run, run.exitCode);
+  if (failed(run)) throw withVirtualMacHint(engineFailure(args[0] ?? "", run, run.exitCode));
   try {
     return parseTranscriptionOutput(run.stdout);
   } catch (err: unknown) {
@@ -477,7 +509,7 @@ export async function recordEngine(target: RecordTarget, maxSeconds: number): Pr
   const signalled = target.live && SIGNALLED_LIVE_EXIT_CODES.has(exitCode);
   // A clean interrupt delivers the transcript and exits 128+signal saying nothing (rust/src/cli/record.rs:82),
   // so an error event beside that status is a real failure the signal must not excuse.
-  if (events.error || events.invalid.length > 0) throw engineFailure("record", events, exitCode);
+  if (events.error || events.invalid.length > 0) throw withVirtualMacHint(engineFailure("record", events, exitCode));
   // A silent non-zero exit named nothing, so it stays the operational 1 it has been since #1167.
   if (!signalled && exitCode !== 0) throw new Error(`kesha-engine record exited with code ${exitCode}`);
 }
@@ -518,6 +550,7 @@ export async function detectTextLanguageEngine(
 ): Promise<LangDetectResult | null> {
   if (text.trim().length === 0) return null;
   if (!isEngineInstalled()) return null;
+  assertEngineSupported(getEngineBinPath());
   const run = await runEngine(["detect-text-lang"], { ...opts, stdin: text });
   if (reportedFailure(run)) {
     const warning = textLangFailureWarning(run.stderr);

package/src/log.ts

@@ -16,6 +16,10 @@ export function setColorEnabled(enabled: boolean): void {
   colors = enabled ? pc : pc.createColors(false);
 }
 
+export function isColorEnabled(): boolean {
+  return colors.isColorSupported;
+}
+
 /**
  * Debug mode (#148): when `KESHA_DEBUG` is truthy OR the caller has flipped
  * `log.debugEnabled = true` (via `--debug`), `log.debug()` writes structured

package/src/mcp/tools.ts

@@ -1,5 +1,6 @@
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { errorMessage } from "../error-utils";
+import { KeshaError } from "../engine/events";
 import { installHint } from "../install-hint";
 import { z } from "zod";
 import { chmodSync, existsSync, readFileSync, statSync } from "fs";
@@ -126,7 +127,8 @@ export function registerTools(server: McpServer): void {
         const hint = isAbsolute(path)
           ? ""
           : ` (relative paths resolve against the MCP server's working directory, ${process.cwd()} — pass an absolute path instead)`;
-        return { isError: true, content: [{ type: "text" as const, text: `File not found: ${path}${hint}` }] };
+        const err = new KeshaError("E_INPUT_NOT_FOUND", `File not found: ${path}${hint}`);
+        return { isError: true, content: [{ type: "text" as const, text: errorMessage(err) }] };
       }
       try {
         assertAudioFileArgument(path);

package/src/support-bundle.ts

@@ -132,6 +132,7 @@ function mkdirReason(dir: string, errno: string): string {
 }
 
 function bundleWriteFailure(outputPath: string, e: unknown): unknown {
+  if ((e as NodeJS.ErrnoException).code === "EPIPE") return e;
   const dir = dirname(outputPath);
   const errno = mkdirReason(dir, (e as NodeJS.ErrnoException).code ?? "");
   const blocker = fileInTheWay(dir);

package/src/toon.ts

@@ -15,5 +15,6 @@ export function formatToonOutput<T extends object, E extends object>(
   results: T[],
   errors?: E[],
 ): string {
-  return encodeToon(errors === undefined ? results : { results, errors }) + "\n";
+  const payload = errors === undefined ? results : { results, errors };
+  return encodeToon(JSON.parse(JSON.stringify(payload))) + "\n";
 }

package/src/voice-routing.ts

@@ -1,4 +1,4 @@
-import { detectTextLanguageEngine } from "./engine";
+import { detectTextLanguageEngine, type LangDetectResult } from "./engine";
 import { listVoiceIds } from "./synth";
 
 /** The voice the Engine speaks with when `say` is given no `--voice` — mirrors `tts::voices::DEFAULT_VOICE_ID`. */
@@ -63,6 +63,12 @@ const NATIVE_SCRIPT_ROUTES: Record<string, NativeScriptRoute> = {
 };
 
 const LATIN_LETTER = /[A-Za-z]/u;
+const CYRILLIC = /\p{Script=Cyrillic}/u;
+
+function mostlyCyrillicWords(text: string): boolean {
+  const words = text.split(/\s+/).filter((w) => /\p{L}/u.test(w));
+  return words.filter((w) => CYRILLIC.test(w)).length * 2 > words.length;
+}
 
 /** True when more of the text's letters are in `script` than in the Latin alphabet. */
 function dominantScript(text: string, script: RegExp): boolean {
@@ -110,6 +116,7 @@ export interface ResolveSayVoiceOptions {
   arch?: NodeJS.Architecture;
   /** The engine's `say --list-voices` union; injected so the routing decision is testable without an engine. */
   listVoices?: (signal?: AbortSignal) => Promise<string[]>;
+  detectLanguage?: (text: string, signal?: AbortSignal) => Promise<LangDetectResult | null>;
 }
 
 function baseLangOf(code: string | undefined): string {
@@ -145,7 +152,9 @@ async function detectLang(
   options: ResolveSayVoiceOptions,
 ): Promise<{ code?: string; confidence: number }> {
   if (!text) return { confidence: 0 };
-  const detected = await detectTextLanguageEngine(text, { signal: options.signal });
+  const detected = options.detectLanguage
+    ? await options.detectLanguage(text, options.signal)
+    : await detectTextLanguageEngine(text, { signal: options.signal });
   return { code: detected?.code, confidence: detected?.confidence ?? 0 };
 }
 
@@ -153,7 +162,8 @@ async function detectLang(
  * Resolve the voice for a synthesis request. Precedence: explicit voice >
  * explicit language hint (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 language
+ * macOS text-language auto-detection > Russian when detection is inconclusive and most
+ * words are Cyrillic (#1387) > engine default (`undefined`). A language
  * hint the build has no voice for resolves to `undefined` (engine default)
  * rather than re-running detection — the user stated the language explicitly.
  *
@@ -170,6 +180,9 @@ export async function resolveSayVoice(
   const { code, confidence } =
     langHint !== undefined ? { code: langHint, confidence: 1 } : await detectLang(text, options);
   const voice = pickVoiceForLang(code, confidence, options.platform, options.arch);
+  if (confidence < 0.5 && mostlyCyrillicWords(text)) {
+    return pickVoiceForLang("ru", 1, options.platform, options.arch);
+  }
   if (confidence < 0.5) return voice;
   return (await nativeScriptOverride(baseLangOf(code), text, options)) ?? voice;
 }