@drakulavich/kesha-voice-kit 2.3.0-beta.1 → 2.3.0-beta.3

package/README.md

@@ -16,7 +16,7 @@
 - **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
+- **Small Rust engine** — single ~74 MB binary, no ffmpeg, no Python, no native Node addons
 
 <p align="center">
   <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">
@@ -104,6 +104,7 @@ $ kesha freedom.ogg tahiti.ogg
 - **Word-level timestamps** (every platform): `kesha --json --timestamps audio.ogg` adds a `words` array to each segment — `{ "word": "email", "start": 0.72, "end": 1.12 }` — on the same file-relative clock as the segment, so a word always lies inside the segment carrying it. Read them off the decoder's own frame grid, so: times are quantised to 0.08 s, consecutive spans may overlap (each `end` is a per-word duration prediction, not the next word's `start`), `end >= start` rather than strictly greater, and punctuation stays attached to its word. The key is simply absent where a segment has none — any segment `--itn` rewrote, for one — so check the `transcribe.words` capability rather than expecting an empty array ([#720](https://github.com/drakulavich/kesha-voice-kit/issues/720)).
 - **Text-language detection:** JSON and TOON results include `textLanguage` with a language code, confidence, and its `source`. On macOS Kesha uses Apple `NLLanguageRecognizer`; elsewhere it uses the bundled `tinyld` fallback, whose confidence scale is different. This is separate from `audioLanguage`, which identifies the spoken audio when available.
 - **Written-form numbers:** `--itn` rewrites what the model spells out — `"two hundred thirty two"` → `"232"`, `"five dollars and fifty cents"` → `"$5.50"`. Opt-in, every platform, timestamps untouched. English-only in practice; Russian and the rest pass through unchanged. Spoken punctuation names stay words (`"dot"`, `"comma"`, `"the period of growth"`) because Kesha transcribes speech rather than dictation — so `"example dot com"` keeps its words too ([#822](https://github.com/drakulavich/kesha-voice-kit/issues/822)). A sentence `"and"` survives the number that follows it (`"cats and three dogs"` → `"cats and 3 dogs"`), while an `"and"` the number owns still joins it (`"three hundred and five"` → `"305"`) ([#1000](https://github.com/drakulavich/kesha-voice-kit/issues/1000)) — and no longer splits the number around it (`"two hundred and thirty two"` → `"232"`, not `"230 2"`) ([#1006](https://github.com/drakulavich/kesha-voice-kit/issues/1006)). A hyphenated number reads the same as the spaced form (`"twenty-five apples"` → `"25 apples"`), while a hyphen between ordinary words is left alone (`"well-known"`, `"state-of-the-art"`, `"twenty-something"`) ([#1004](https://github.com/drakulavich/kesha-voice-kit/issues/1004)).
+- **A file name starting with `-`:** write it as `./-file.wav`, or put an option before `--` (`kesha --json -- -file.wav`). A bare `kesha -- -file.wav` fails with `unknown option`, because Bun drops a `--` that comes right after the command name ([#1464](https://github.com/drakulavich/kesha-voice-kit/issues/1464)).
 
 ## Text-to-speech
 
@@ -126,7 +127,7 @@ kesha say "Hello" --format ogg-opus --out hi.ogg  # OGG/Opus — messenger voice
 kesha say "Hello" --format flac --out hi.flac     # FLAC — lossless, plays in every browser incl. Safari/iOS
 ```
 
-`kesha say --list-voices` lists what's installed. Voices, the full catalogue, macOS system voices, SSML, speaking rate (`--rate`, `<prosody>`), Russian word stress, and Russian/English abbreviation handling are all in **[docs/tts.md](docs/tts.md)**.
+`kesha say --list-voices` lists the voices kesha knows; some need `kesha install --tts <lang>` before they speak. Voices, the full catalogue, macOS system voices, SSML, speaking rate (`--rate`, `<prosody>`), Russian word stress, and Russian/English abbreviation handling are all in **[docs/tts.md](docs/tts.md)**.
 
 ## Languages
 

package/completions/kesha.fish

@@ -78,7 +78,7 @@ complete -c kesha -n '__fish_seen_subcommand_from say' -l voice -r -d 'Voice id,
 complete -c kesha -n '__fish_seen_subcommand_from say' -l lang -r -d 'Language code, e.g. en-us (default en-us; see docs/languages.md). With no --voice, routes to that language\'s default voice and skips text-language detection.'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l out -r -d 'Write audio to file instead of stdout'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l rate -r -d 'Speaking rate 0.5–2.0'
-complete -c kesha -n '__fish_seen_subcommand_from say' -l list-voices -d 'List installed voices and exit'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l list-voices -d 'List the voices kesha knows and exit; some need kesha install --tts <lang> first'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l ssml -d 'Parse input as SSML (supports <speak>, <break>; strips unknown tags)'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l format -r -d 'Output format: wav (default), ogg-opus (Telegram-ready voice note), or flac (lossless, plays in all browsers incl. Safari). Inferred from --out extension when omitted.'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l bitrate -r -d 'Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.'

package/completions/kesha.zsh

@@ -112,7 +112,7 @@ _kesha() {
         '--lang=[Language code, e.g. en-us (default en-us; see docs/languages.md). With no --voice, routes to that language'\''s default voice and skips text-language detection.]:lang:' \
         '--out=[Write audio to file instead of stdout]:out:' \
         '--rate=[Speaking rate 0.5–2.0]:rate:' \
-        '--list-voices[List installed voices and exit]' \
+        '--list-voices[List the voices kesha knows and exit; some need kesha install --tts <lang> first]' \
         '--ssml[Parse input as SSML (supports <speak>, <break>; strips unknown tags)]' \
         '--format=[Output format: wav (default), ogg-opus (Telegram-ready voice note), or flac (lossless, plays in all browsers incl. Safari). Inferred from --out extension when omitted.]:format:' \
         '--bitrate=[Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.]:bitrate:' \

package/man/kesha.1

@@ -191,7 +191,7 @@ Write audio to file instead of stdout
 Speaking rate 0.5–2.0
 .TP
 .B \-\-list\-voices
-List installed voices and exit
+List the voices kesha knows and exit; some need kesha install \-\-tts <lang> first
 .TP
 .B \-\-ssml
 Parse input as SSML (supports <speak>, <break>; strips unknown tags)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "2.3.0-beta.1",
+  "version": "2.3.0-beta.3",
   "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": {
@@ -109,20 +109,20 @@
   },
   "kesha": {
     "engine": {
-      "version": "2.3.0-beta.1",
+      "version": "2.3.0-beta.3",
       "sha256": {
-        "kesha-engine-darwin-arm64": "dade5c6c2d8fc838a38c1381915ee9e3a1d2840f20c87b6cabcdd3f2dcec3c9e",
-        "kesha-engine-linux-x64": "2b6e604cb24fca040b60136df3e4e29e3005959aea0a6cd7d3fb80930e9f3380",
-        "kesha-engine-windows-x64.exe": "269e13d10852bc01fdce2bec880bb9831bdaf19c4cb8e7a2d0a09a84c2980dc7",
-        "say-avspeech-darwin-arm64": "3a7e8b8fac92ce4ce0c34f736098a685dcb745f741db8303e1721e320ac73a98",
-        "kesha-textlang-darwin-arm64": "e45e2822248b14dd72aa79e2def8fa6b9c07c97423f11c841508769225d72da4"
+        "kesha-engine-darwin-arm64": "db444c1c0ccc368e72068f050807ab54975fb516055480b33c32d5b1f29c4e58",
+        "kesha-engine-linux-x64": "0ac69c63cc8e922aaaea5b6df221dd97f6add02d4d6fb09def2317c331019a89",
+        "kesha-engine-windows-x64.exe": "0ae3063b7d5ff00da7cd0f675cd557374d81ff94087787dc90d7c195f7347194",
+        "say-avspeech-darwin-arm64": "6c7e0708f27c1baf3d8013bfbeb6249a6c3acbb718b3d39081707c7a8aa22e5b",
+        "kesha-textlang-darwin-arm64": "cbe74ee1aebdb902e21d4c69769c71b6d49e037794a8623db11faa8cf2814420"
       },
       "size": {
-        "kesha-engine-darwin-arm64": 73639696,
-        "kesha-engine-linux-x64": 67403816,
-        "kesha-engine-windows-x64.exe": 66584064,
-        "say-avspeech-darwin-arm64": 82992,
-        "kesha-textlang-darwin-arm64": 57648
+        "kesha-engine-darwin-arm64": 73672784,
+        "kesha-engine-linux-x64": 67422216,
+        "kesha-engine-windows-x64.exe": 66576384,
+        "say-avspeech-darwin-arm64": 82896,
+        "kesha-textlang-darwin-arm64": 57488
       }
     }
   }

package/src/cache-layout.ts

@@ -1,6 +1,9 @@
 import { existsSync, realpathSync, statSync } from "fs";
 import { dirname, join, resolve, sep } from "path";
 import { dirSizeBytes } from "./diagnostic-paths";
+import { isDarwinArm64 } from "./engine-targets";
+
+export const KOKORO_ONNX_UNUSED_NOTE = "not used on darwin-arm64, where Kokoro runs from the TTS (Kokoro ANE) bundle";
 
 /** The sidecar executables the engine spawns from its own directory. */
 const SIDECAR_FILES = ["say-avspeech", "kesha-textlang"] as const;
@@ -10,6 +13,7 @@ export interface CacheComponentSize {
   path: string;
   exists: boolean;
   sizeBytes: number;
+  note?: string;
 }
 
 interface EngineFootprint {
@@ -101,14 +105,33 @@ export function cacheComponents(
     exists: existsSync(engine.path),
     sizeBytes: footprintBytes(engine, engine.members),
   };
+  const coremlRows = [
+    { label: "FluidAudio (in cache)", path: join(cacheRoot, "fluidaudio") },
+    { label: "Diarization (Sortformer)", path: join(cacheRoot, "models/diarize") },
+  ];
+  const onnxRows = [
+    { label: "ASR (Parakeet)", path: join(cacheRoot, "models/parakeet-tdt-v3") },
+    { label: "G2P (CharsiuG2P)", path: join(cacheRoot, "models/g2p") },
+  ];
+  const [usedRows, unusedRows] = coreml ? [coremlRows, onnxRows] : [onnxRows, coremlRows];
+  const sized = (row: { label: string; path: string }) => ({
+    ...row,
+    exists: existsSync(row.path),
+    sizeBytes: dirSizeBytes(row.path),
+  });
   const modelRows = [
-    ...(coreml
-      ? [{ label: "FluidAudio (in cache)", path: join(cacheRoot, "fluidaudio") }]
-      : [{ label: "ASR (Parakeet)", path: join(cacheRoot, "models/parakeet-tdt-v3") }]),
+    ...usedRows,
     { label: "Language ID", path: join(cacheRoot, "models/lang-id-ecapa") },
     { label: "VAD (Silero)", path: join(cacheRoot, "models/silero-vad") },
-    { label: "TTS (Kokoro)", path: join(cacheRoot, "models/kokoro-82m") },
+    {
+      label: "TTS (Kokoro)",
+      path: join(cacheRoot, "models/kokoro-82m"),
+      ...(isDarwinArm64() ? { note: KOKORO_ONNX_UNUSED_NOTE } : {}),
+    },
     { label: "TTS (Vosk)", path: join(cacheRoot, "models/vosk-ru") },
-  ].map((row) => ({ ...row, exists: existsSync(row.path), sizeBytes: dirSizeBytes(row.path) }));
-  return [engineRow, ...modelRows];
+  ].map(sized);
+  const leftoverRows = unusedRows
+    .map((row) => sized({ ...row, label: `${row.label}, unused by this engine, safe to delete` }))
+    .filter((row) => row.exists);
+  return [engineRow, ...modelRows, ...leftoverRows];
 }

package/src/cli/context.ts

@@ -34,7 +34,8 @@ function stripBooleanFlag(
   const valuedPrefixes = names.filter((n) => n.startsWith("--")).map((n) => `${n}=`);
   let value = false;
   const cleaned: string[] = [];
-  for (const arg of rawArgs) {
+  const end = rawArgs.indexOf("--");
+  for (const arg of end === -1 ? rawArgs : rawArgs.slice(0, end)) {
     if (names.includes(arg)) {
       value = true;
     } else if (valuedPrefixes.some((prefix) => arg.startsWith(prefix))) {
@@ -43,7 +44,7 @@ function stripBooleanFlag(
       cleaned.push(arg);
     }
   }
-  return { value, rawArgs: cleaned };
+  return { value, rawArgs: end === -1 ? cleaned : [...cleaned, ...rawArgs.slice(end)] };
 }
 
 /**

package/src/cli/dispatch.ts

@@ -1,6 +1,8 @@
 import { renderUsage, runMain, type ArgsDef, type CommandDef } from "citty";
 import { existsSync } from "fs";
 import { stripVTControlCharacters } from "util";
+import { exitCodeFor, KeshaError, SUPPORT_BUNDLE_HINT } from "../engine/events";
+import { errorMessage } from "../error-utils";
 import { isColorEnabled, log } from "../log";
 import { packageVersion } from "../package-info";
 import { guardStdoutWrites } from "../stdout-pipe";
@@ -117,6 +119,24 @@ function misplacedSubcommand(rawArgs: string[], subcommandKeys: string[]): strin
   return rawArgs.slice(0, end === -1 ? undefined : end).find((arg) => subcommandKeys.includes(arg) && !existsSync(arg));
 }
 
+/** citty's runMain prints whatever `run` throws as a stack trace with exit 1; only `run` is wrapped, so a command with `subCommands` needs the same. */
+function reportThrows(command: CommandDef<any>): CommandDef<any> {
+  const run = command.run;
+  if (!run) return command;
+  return {
+    ...command,
+    async run(context) {
+      try {
+        return await run(context);
+      } catch (err) {
+        const coded = err instanceof KeshaError ? err : new KeshaError("E_INTERNAL", errorMessage(err), { hint: SUPPORT_BUNDLE_HINT });
+        log.error(coded.render());
+        process.exit(exitCodeFor(coded));
+      }
+    },
+  };
+}
+
 export async function runCli(argv = process.argv.slice(2)): Promise<void> {
   guardStdoutWrites();
   const context = resolveCliContext(argv);
@@ -136,7 +156,7 @@ export async function runCli(argv = process.argv.slice(2)): Promise<void> {
       const argsDef = await resolveArgsDef(command);
       rejectUnknownOptions(restArgs, argsDef);
       if (firstArg !== "install" && firstArg !== "say") rejectExtraPositionals(restArgs, argsDef);
-      await runMain(command, { rawArgs: restArgs, showUsage });
+      await runMain(reportThrows(command), { rawArgs: restArgs, showUsage });
       return;
     }
 
@@ -163,7 +183,12 @@ export async function runCli(argv = process.argv.slice(2)): Promise<void> {
         await showUsage(rawArgs.includes("--all") ? command : briefMainUsage(command));
         return;
       }
-      await runMain(command, { rawArgs, showUsage });
+      const options = rawArgs.slice(0, rawArgs.includes("--") ? rawArgs.indexOf("--") : undefined);
+      if (options.includes("--version") || options.includes("-v")) {
+        process.stdout.write(`${packageVersion}\n`);
+        return;
+      }
+      await runMain(reportThrows(command), { rawArgs, showUsage });
     }
   }
 }

package/src/cli/install.ts

@@ -140,8 +140,8 @@ export function selectBackend(coreml: boolean, onnx: boolean): BackendSelection
 export function resolveBackendFlag(coreml: boolean, onnx: boolean): string | undefined {
   const selection = selectBackend(coreml, onnx);
   if (!selection.ok) {
-    log.error(selection.error);
-    process.exit(1);
+    log.error(renderInvalidArg(selection.error));
+    process.exit(2);
   }
   return selection.backend;
 }

package/src/cli/main.ts

@@ -1,7 +1,15 @@
 import { defineCommand, type ArgsDef, type CommandDef } from "citty";
 import { errorMessage } from "../error-utils";
 import { existsSync } from "fs";
-import { isDirectoryPath, transcribeWithSegments, validateTranscribeRequest } from "../transcribe";
+import {
+  isDirectoryPath,
+  isSpecialFilePath,
+  missingFileHint,
+  SPECIAL_FILE_HINT,
+  transcribeWithSegments,
+  truncatedWavSeconds,
+  validateTranscribeRequest,
+} from "../transcribe";
 
 export { isDirectoryPath };
 import { detectAudioLanguageEngine, detectTextLanguageEngine, isEngineInstalled } from "../engine";
@@ -28,7 +36,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 { detectTextLanguageFallback, routeLanguage } from "../language-routing";
+import { detectTextLanguageFallback, routeLanguage, unsupportedAudioLanguageWarning } from "../language-routing";
 import { renderInvalidArg } from "./options";
 
 interface MainCommandArgs {
@@ -81,14 +89,12 @@ export function resolveOutputFormat(input: {
       error: `unknown --format '${input.format}'. supported: ${SUPPORTED_FORMATS.join(", ")}`,
     };
   }
-  if (
-    (input.json && input.toon) ||
-    (input.json && input.format === "toon") ||
-    (input.toon && input.format === "json")
-  ) {
+  const jsonFlag = input.json ? "--json" : input.format === "json" ? "--format json" : null;
+  const toonFlag = input.toon ? "--toon" : input.format === "toon" ? "--format toon" : null;
+  if (jsonFlag && toonFlag) {
     return {
       ok: false,
-      error: "--json and --toon are mutually exclusive (pick one output format).",
+      error: `${jsonFlag} and ${toonFlag} are mutually exclusive (pick one output format).`,
     };
   }
   // `--format transcript` + boolean `--json` / `--toon` was previously
@@ -264,6 +270,11 @@ async function detectLanguages(
     }
   }
 
+  const unsupportedWarning = unsupportedAudioLanguageWarning(audioLanguage, textLanguage ?? tinyldResult);
+  if (unsupportedWarning) {
+    warnAboveProgress(progress, `${file}: ${unsupportedWarning}`);
+  }
+
   const route = routeLanguage({ audioLanguage, textLanguage: textLanguage ?? tinyldResult });
   const { lang } = route;
 
@@ -316,8 +327,19 @@ async function processFile(
   const { vadMode, timestamps, speakers, itn, wantsLangId, expectedLang, reportProgress } = options;
   const { stats, diagnosticLog } = recorders;
 
+  if (file === "-") {
+    const err = new KeshaError("E_INVALID_ARG", "reading audio from stdin is not supported", { hint: SPECIAL_FILE_HINT });
+    stats.recordError("input", err, err.code);
+    diagnosticLog.event("input.invalid", {
+      command: "transcribe",
+      error_code: err.code,
+    });
+    log.error(`${file}: ${errorMessage(err)}`);
+    return { ok: false, error: { file, code: err.code, message: err.message }, exitCode: failureExitCode(err) };
+  }
+
   if (!existsSync(file)) {
-    const err = new KeshaError("E_INPUT_NOT_FOUND", "File not found");
+    const err = new KeshaError("E_INPUT_NOT_FOUND", "File not found", { hint: missingFileHint(file) });
     stats.recordError("input", err, err.code);
     diagnosticLog.event("input.missing", {
       command: "transcribe",
@@ -340,6 +362,26 @@ async function processFile(
     return { ok: false, error: { file, code: err.code, message: err.message }, exitCode: failureExitCode(err) };
   }
 
+  if (isSpecialFilePath(file)) {
+    const err = new KeshaError("E_INVALID_ARG", "is not a regular file (expected an audio file)", {
+      hint: SPECIAL_FILE_HINT,
+    });
+    stats.recordError("input", err, err.code);
+    diagnosticLog.event("input.invalid", {
+      command: "transcribe",
+      error_code: err.code,
+    });
+    log.error(`${file}: ${errorMessage(err)}`);
+    return { ok: false, error: { file, code: err.code, message: err.message }, exitCode: failureExitCode(err) };
+  }
+
+  const truncated = truncatedWavSeconds(file);
+  if (truncated) {
+    log.warn(
+      `warning: ${file} is truncated: its header declares ${truncated.declared.toFixed(1)} s of audio but the file holds ${truncated.present.toFixed(1)} s; transcribing the part present`,
+    );
+  }
+
   const inputArtifact = artifactFromFile(file, "input_audio");
   if (inputArtifact) {
     stats.recordArtifact(inputArtifact);
@@ -508,20 +550,25 @@ export function createMainCommand(context: CliContext = { quiet: false, disableC
         "  kesha init               Guided first-time setup.\n" +
         "\n" +
         "Commands:\n" +
-        "  completions  Print shell completion script.\n" +
-        "  doctor     Collect support diagnostics.\n" +
-        "  init       Interactive setup guide for Kesha features.\n" +
-        "  install    Download engine and models.\n" +
-        "  logs       Manage local privacy-safe diagnostic logs.\n" +
-        "  manpage    Print the kesha(1) manpage.\n" +
-        "  mcp        Run an MCP server over stdio.\n" +
-        "  record     Record microphone audio to a WAV file.\n" +
-        "  status     Inspect installed backend.\n" +
-        "  say        Synthesize speech from text.\n" +
-        "  stats      Manage local anonymous performance stats.\n" +
-        "  support-bundle  Create a redacted diagnostics archive.",
+        "  completions     Print shell completion script.\n" +
+        "  doctor          Collect support diagnostics.\n" +
+        "  init            Interactive setup guide for Kesha features.\n" +
+        "  install         Download engine and models.\n" +
+        "  logs            Manage local privacy-safe diagnostic logs.\n" +
+        "  manpage         Print the kesha(1) manpage.\n" +
+        "  mcp             Run an MCP server over stdio.\n" +
+        "  record          Record microphone audio to a WAV file.\n" +
+        "  status          Inspect installed backend.\n" +
+        "  say             Synthesize speech from text.\n" +
+        "  stats           Manage local anonymous performance stats.\n" +
+        "  support-bundle  Create a redacted diagnostics archive.\n",
     },
     args: {
+      audio_file: {
+        type: "positional",
+        required: false,
+        description: "Audio file(s) to transcribe",
+      },
       json: {
         type: "boolean",
         description: "Output results as JSON",

package/src/cli/options.ts

@@ -71,6 +71,11 @@ function scanArgs(rawArgs: string[], argsDef: ArgsDef): { unknown: UnknownOption
   return { unknown: null, positionals };
 }
 
+/** The positionals in `rawArgs` as the user typed them; citty reads `-5 degrees` as a bundle of short flags (#1473 S2-5). */
+export function positionalArgs(rawArgs: string[], argsDef: ArgsDef): string[] {
+  return scanArgs(rawArgs, argsDef).positionals;
+}
+
 /** The coded line for a usage error the CLI refuses before doing anything (S9-F2). */
 export function renderInvalidArg(message: string): string {
   return renderError({ code: "E_INVALID_ARG", message });

package/src/cli/record.ts

@@ -3,13 +3,13 @@ import { errorMessage } from "../error-utils";
 import { exitCodeFor, KeshaError } from "../engine/events";
 import { renderInvalidArg } from "./options";
 import {
+  engineMissingError,
   isEngineInstalled,
   recordEngine,
   validateRecordRequest,
   type LiveAutoStopOptions,
   type RecordTarget,
 } from "../engine";
-import { installHint } from "../install-hint";
 import { log } from "../log";
 import { getPendingSignalExitCode, waitForPendingSignalCleanup } from "../process-tree";
 
@@ -142,12 +142,7 @@ function resolveThreshold(
 
 /** Mirrors `src/transcribe.ts`'s "no transcription backend" guard message, worded for recording. */
 export function noRecordingBackendMessage(): string {
-  return (
-    "Error: No recording backend is installed.\n\n" +
-    "Run the following to get started:\n\n" +
-    "    bun add -g @drakulavich/kesha-voice-kit\n" +
-    `    ${installHint()}`
-  );
+  return errorMessage(engineMissingError("recording"));
 }
 
 export const recordCommand = defineCommand({

package/src/cli/say.ts

@@ -1,11 +1,14 @@
-import { defineCommand } from "citty";
+import { defineCommand, type ArgsDef } from "citty";
 import { statSync } from "fs";
+import { extname } from "path";
 import { errorMessage } from "../error-utils";
+import { engineMissingError, isEngineInstalled } from "../engine";
 import { exitCodeFor, KeshaError } from "../engine/events";
-import { renderInvalidArg } from "./options";
+import { positionalArgs, renderInvalidArg } from "./options";
 import { log } from "../log";
 import {
   MAX_TEXT_CHARS,
+  TEXT_TOO_LONG_HINT,
   listVoiceIds,
   say,
   SUPPORTED_SAMPLE_RATES,
@@ -35,6 +38,7 @@ async function resolveText(inline: string | undefined): Promise<string> {
     throw new KeshaError(
       "E_TEXT_TOO_LONG",
       `text exceeds ${MAX_TEXT_CHARS} chars (stdin passed ${MAX_STDIN_BYTES} bytes)`,
+      { hint: TEXT_TOO_LONG_HINT },
     );
   }
   const merged = new Uint8Array(total);
@@ -128,6 +132,16 @@ function checkOpusOnlyFlags(
   return "--bitrate and --sample-rate are only valid with --format ogg-opus";
 }
 
+const OUT_EXTENSIONS = [".wav", ".ogg", ".opus", ".oga", ".flac"];
+
+/** Mirrors the engine's `format_from_extension`, which writes WAV under any name it does not know (#1473 S2-4). */
+function checkOutExtension(outArg: string | undefined): string | null {
+  if (outArg === undefined) return null;
+  const ext = extname(outArg).toLowerCase();
+  if (ext === "" || OUT_EXTENSIONS.includes(ext)) return null;
+  return `--out ${outArg}: kesha cannot encode ${ext}; use one of ${OUT_EXTENSIONS.join(", ")}, or no extension for WAV`;
+}
+
 export type SayFlagArgs = {
   voice?: unknown;
   lang?: unknown;
@@ -179,6 +193,8 @@ export function resolveSayFlags(args: SayFlagArgs): ResolvedSayFlags {
   const out = typeof args.out === "string" ? args.out : undefined;
   const opusOnlyError = checkOpusOnlyFlags(bitrate.value, sampleRate.value, format.value, out);
   if (opusOnlyError) return { ok: false, error: opusOnlyError };
+  const outExtError = checkOutExtension(out);
+  if (outExtError) return { ok: false, error: outExtError };
 
   return {
     ok: true,
@@ -253,6 +269,7 @@ async function synthesizeAndEmit(
   const { stats } = session;
   try {
     const startedAt = performance.now();
+    if (!isEngineInstalled()) throw engineMissingError("speech synthesis", "--tts");
     if (opts.out) {
       const voiceLabel = opts.voice ?? "default voice";
       log.status(`Synthesizing ${voiceLabel} -> ${opts.out}...`);
@@ -310,7 +327,7 @@ export const sayCommand = defineCommand({
     },
     out: { type: "string", description: "Write audio to file instead of stdout" },
     rate: { type: "string", description: "Speaking rate 0.5–2.0", default: "1.0" },
-    "list-voices": { type: "boolean", description: "List installed voices and exit" },
+    "list-voices": { type: "boolean", description: "List the voices kesha knows and exit; some need kesha install --tts <lang> first" },
     ssml: {
       type: "boolean",
       description: "Parse input as SSML (supports <speak>, <break>; strips unknown tags)",
@@ -374,7 +391,7 @@ export const sayCommand = defineCommand({
       process.exit(2);
     }
 
-    const positionals = (args._ ?? []).map(String);
+    const positionals = positionalArgs(rawArgs, sayCommand.args as ArgsDef);
     const inlineText =
       positionals.length > 0 ? positionals.join(" ") : typeof args.text === "string" ? args.text : undefined;
     const stdinIsTty = (process.stdin as { isTTY?: boolean }).isTTY;

package/src/cli/stats.ts

@@ -6,6 +6,7 @@ import {
   getRecentErrors,
   getStatsStatus,
   getWeekSummary,
+  MAX_RETENTION_DAYS,
   renderErrors,
   renderWeekSummary,
   resetStats,
@@ -13,6 +14,9 @@ import {
   vacuumStats,
   type StatsExportFormat,
 } from "../stats";
+import { exitCodeFor, KeshaError } from "../engine/events";
+import { errorMessage } from "../error-utils";
+import { log } from "../log";
 import { emitActionResult, type ActionMessage, type ActionResult } from "./action-result";
 
 export interface StatsCommandArgs {
@@ -113,7 +117,13 @@ function runRetentionAction(value: string | undefined): ActionResult {
     return { ok: true, messages: info(`Kesha Stats retention: ${formatRetention(status.retentionDays)}`) };
   }
   const retention = parseRetention(value);
-  if (retention === undefined) return { ok: false, error: "usage: kesha stats retention <days|off>" };
+  if (retention === undefined) {
+    return {
+      ok: false,
+      error: "usage: kesha stats retention <days|off>",
+      hint: `days is a whole number from 1 to ${MAX_RETENTION_DAYS}.`,
+    };
+  }
   setStatsRetentionDays(retention);
   return { ok: true, messages: info(`Kesha Stats retention set to ${formatRetention(retention)}`) };
 }
@@ -144,7 +154,15 @@ export const statsCommand = defineCommand({
     },
   },
   run({ args, rawArgs }: { args: StatsCommandArgs; rawArgs: string[] }) {
-    emitActionResult(runStatsAction({ ...args, value: args.value ?? eatenNegativeNumber(rawArgs) }));
+    let result: ActionResult;
+    try {
+      result = runStatsAction({ ...args, value: args.value ?? eatenNegativeNumber(rawArgs) });
+    } catch (err) {
+      const coded = err instanceof KeshaError ? err : new KeshaError("E_INTERNAL", errorMessage(err));
+      log.error(coded.render());
+      process.exit(exitCodeFor(coded));
+    }
+    emitActionResult(result);
   },
 });
 
@@ -161,7 +179,7 @@ function parseRetention(value: string): number | null | undefined {
   const normalized = value.trim().toLowerCase();
   if (normalized === "off" || normalized === "none" || normalized === "never") return null;
   const days = Number(normalized);
-  if (Number.isInteger(days) && days >= 1) return days;
+  if (Number.isInteger(days) && days >= 1 && days <= MAX_RETENTION_DAYS) return days;
   return undefined;
 }
 

package/src/diagnostic-log.ts

@@ -1,4 +1,6 @@
+import { KeshaError } from "./engine/events";
 import { errorMessage } from "./error-utils";
+import { PATH_ERRNOS } from "./path-errnos";
 import { resolveStatePaths } from "./state-paths";
 import {
   closeSync,
@@ -19,7 +21,7 @@ import { packageVersion } from "./package-info";
 
 const ACTIVE_LOG_FILE = "kesha.ndjson";
 const STATE_FILE = "diagnostic-logs.json";
-const DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+const DEFAULT_MAX_BYTES = 10_000_000;
 const DEFAULT_RETAIN = 5;
 const DEFAULT_TAIL_BYTES = 64 * 1024;
 const SAFE_FIELD_NAME = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
@@ -115,8 +117,16 @@ function positiveInt(value: unknown, fallback: number): number {
 
 function writeConfig(config: DiagnosticLogConfig): void {
   const statePath = resolveStatePath();
-  mkdirSync(dirname(statePath), { recursive: true });
-  writeFileSync(statePath, `${JSON.stringify(config, null, 2)}\n`);
+  try {
+    mkdirSync(dirname(statePath), { recursive: true });
+    writeFileSync(statePath, `${JSON.stringify(config, null, 2)}\n`);
+  } catch (err) {
+    const errno = (err as NodeJS.ErrnoException).code ?? "";
+    const why = PATH_ERRNOS[errno];
+    throw new KeshaError(why ? "E_INVALID_ARG" : "E_INTERNAL", `cannot write the diagnostic log settings ${statePath}: ${why ? `${why} (${errno})` : errorMessage(err)}`, {
+      hint: `make ${dirname(statePath)} writable, or set KESHA_LOG_DIR to a folder you can write to.`,
+    });
+  }
 }
 
 export function setDiagnosticLogMode(mode: DiagnosticLogMode): DiagnosticLogStatus {
@@ -311,12 +321,12 @@ function rotateIfNeeded(activePath: string, nextBytes: number, maxBytes: number,
 }
 
 export function humanBytes(bytes: number): string {
-  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1000) return `${bytes} B`;
   const units = ["KB", "MB", "GB", "TB"];
-  let value = bytes / 1024;
+  let value = bytes / 1000;
   let unit = units[0];
-  for (let i = 1; i < units.length && value >= 1024; i++) {
-    value /= 1024;
+  for (let i = 1; i < units.length && value >= 1000; i++) {
+    value /= 1000;
     unit = units[i];
   }
   return `${value >= 10 ? value.toFixed(0) : value.toFixed(1)} ${unit}`;