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

package/README.md

@@ -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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "2.3.0-beta.1",
+  "version": "2.3.0-beta.2",
   "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.2",
       "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": "febd870e9f857be6452336c74daad161f2cef74dfedb64a21b49b6b1fc2ce94c",
+        "kesha-engine-linux-x64": "9c16e72e5290f774b1d93cbf44b2fc6eca3c4b30659038ccb80f5e98dc748d2a",
+        "kesha-engine-windows-x64.exe": "231bc45eb345ef359ca94685866de8cb4c7c76ae9bef1072c20a60640c458f63",
+        "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": 73672800,
+        "kesha-engine-linux-x64": 67418152,
+        "kesha-engine-windows-x64.exe": 66596864,
+        "say-avspeech-darwin-arm64": 82896,
+        "kesha-textlang-darwin-arm64": 57488
       }
     }
   }

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,7 @@ 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 });
+      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,7 @@
 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, SPECIAL_FILE_HINT, transcribeWithSegments, validateTranscribeRequest } from "../transcribe";
 
 export { isDirectoryPath };
 import { detectAudioLanguageEngine, detectTextLanguageEngine, isEngineInstalled } from "../engine";
@@ -28,7 +28,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 {
@@ -264,6 +264,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;
 
@@ -340,6 +345,19 @@ 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 inputArtifact = artifactFromFile(file, "input_audio");
   if (inputArtifact) {
     stats.recordArtifact(inputArtifact);

package/src/cli/record.ts

@@ -3,6 +3,7 @@ import { errorMessage } from "../error-utils";
 import { exitCodeFor, KeshaError } from "../engine/events";
 import { renderInvalidArg } from "./options";
 import {
+  getEngineBinPath,
   isEngineInstalled,
   recordEngine,
   validateRecordRequest,
@@ -142,11 +143,10 @@ 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(
+    new KeshaError("E_ENGINE_SPAWN", `No recording backend is installed: no kesha-engine at ${getEngineBinPath()}`, {
+      hint: `bun add -g @drakulavich/kesha-voice-kit, then ${installHint()}`,
+    }),
   );
 }
 

package/src/cli/say.ts

@@ -6,6 +6,7 @@ import { renderInvalidArg } from "./options";
 import { log } from "../log";
 import {
   MAX_TEXT_CHARS,
+  TEXT_TOO_LONG_HINT,
   listVoiceIds,
   say,
   SUPPORTED_SAMPLE_RATES,
@@ -35,6 +36,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);

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,
@@ -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 {

package/src/engine/describe.ts

@@ -197,7 +197,9 @@ export function validateArgv(argv: string[], doc: DescribeDocument): { argv: str
     if (name === null) continue;
     const flag = schema.flags[name];
     if (!flag) {
-      throw new KeshaError("E_INVALID_ARG", `kesha-engine ${command} does not accept --${name}`);
+      throw new KeshaError("E_INVALID_ARG", `kesha-engine ${command} does not accept --${name}`, {
+        hint: `the installed kesha-engine is older than this CLI and lacks --${name}; run \`kesha install\` to fetch the engine this CLI expects`,
+      });
     }
     if (!gateSatisfied(flag.gate, doc.features)) {
       const needs = `--${name} needs ${gateText(flag.gate)}, which this kesha-engine build (${build}) does not provide`;

package/src/engine/events.ts

@@ -228,8 +228,10 @@ export function exitCodeFor(err: unknown): number {
 
 const MAX_QUOTED_LINE_CHARS = 200;
 
+export const SUPPORT_BUNDLE_HINT = "re-run with KESHA_DEBUG=1, then file a bug with the `kesha support-bundle` archive";
+
 /** A library line can carry the user's whole input back, so the quote is bounded and the transcript no longer repeats it (#T1-14). */
-function quoteInvalidLine(line: string): string {
+export function quoteInvalidLine(line: string): string {
   const chars = Array.from(line);
   return chars.length <= MAX_QUOTED_LINE_CHARS ? line : `${chars.slice(0, MAX_QUOTED_LINE_CHARS).join("")}…`;
 }
@@ -247,9 +249,9 @@ export function engineFailure(command: string, outcome: StderrOutcome, exitCode:
     return new KeshaError(
       "E_INTERNAL",
       offProtocolLine(command, outcome.invalid[0]!),
-      { ...extra, stderr: rest },
+      { ...extra, stderr: rest, hint: `the engine and CLI may not match: run \`kesha install\`; if it persists, ${SUPPORT_BUNDLE_HINT}` },
     );
   }
   if (outcome.error) return new KeshaError(outcome.error.code, outcome.error.message, { ...extra, hint: outcome.error.hint });
-  return new KeshaError("E_INTERNAL", `kesha-engine ${command} exited with code ${exitCode}`, extra);
+  return new KeshaError("E_INTERNAL", `kesha-engine ${command} exited with code ${exitCode}`, { ...extra, hint: SUPPORT_BUNDLE_HINT });
 }

package/src/engine/spawn.ts

@@ -83,6 +83,28 @@ export interface EngineProcessRun<T> {
   events: StderrOutcome;
 }
 
+/** Fault signals, by number. SIGBUS is 10 on darwin but 7 on linux. */
+const FAULT_SIGNALS: Record<number, string> = { 4: "SIGILL", 6: "SIGABRT", 8: "SIGFPE", 11: "SIGSEGV" };
+
+/** The signal that killed the engine, or null; the wait status outranks Bun's signalCode (10 is SIGBUS on darwin, SIGUSR1 to Bun). */
+export function engineSignal(exitCode: number, signalCode: string | null, platform: string = process.platform): string | null {
+  const number = exitCode > 128 ? exitCode - 128 : undefined;
+  const sigbus = platform === "darwin" ? 10 : 7;
+  const signal =
+    number === undefined
+      ? (signalCode ?? undefined)
+      : number === sigbus
+        ? "SIGBUS"
+        : (FAULT_SIGNALS[number] ?? signalCode ?? undefined);
+  return signal ?? null;
+}
+
+/** What a run that reported nothing ended with: the signal that killed it, else its exit status. */
+export function engineExitCause(command: string, exitCode: number, signalCode: string | null): string {
+  const signal = engineSignal(exitCode, signalCode);
+  return signal ? `kesha-engine ${command} was killed by ${signal}` : `kesha-engine ${command} exited with code ${exitCode}`;
+}
+
 /** 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,

package/src/engine-install.ts

@@ -14,8 +14,8 @@ import {
   targetKey,
 } from "./engine-targets";
 import { validateArgv } from "./engine/describe";
-import { engineFailure, KeshaError, offProtocolLine } from "./engine/events";
-import { runEngineProcess } from "./engine/spawn";
+import { engineFailure, KeshaError, offProtocolLine, SUPPORT_BUNDLE_HINT } from "./engine/events";
+import { engineExitCause, runEngineProcess } from "./engine/spawn";
 import { acquireInstallLock } from "./install-lock";
 import { log } from "./log";
 import { engineVersion, injectedEnginePins } from "./package-info";
@@ -108,7 +108,12 @@ export function releaseChecksums(
   return async (assetName) => {
     if (version === pins?.version) {
       const pinned = pins.sha256[assetName];
-      if (!pinned) throw new Error(`No pinned SHA-256 for ${assetName} of engine v${version}; this CLI build is incomplete.\n  Fix: report it at https://github.com/${GITHUB_REPO}/issues.`);
+      if (!pinned) {
+        throw new KeshaError("E_INTERNAL", `No pinned SHA-256 for ${assetName} of engine v${version}; this CLI build is incomplete`, {
+          exitCode: 1,
+          hint: `report it at https://github.com/${GITHUB_REPO}/issues`,
+        });
+      }
       return { sha256: pinned, source: "its pinned SHA-256" };
     }
     sums ??= fetchSha256Sums(version, pins);
@@ -779,8 +784,11 @@ async function runEngineModelInstall(binPath: string, installArgs: string[]): Pr
   }
   if (events.error || events.invalid.length > 0) throw engineFailure("install", events, exitCode);
   if (exitCode !== 0) {
-    // Nothing coded and nothing off-protocol: the engine failed without saying why, so neither do we.
-    throw new Error(`Failed to install models: kesha-engine install exited with code ${exitCode}.`);
+    throw new KeshaError("E_INTERNAL", `Failed to install models: ${engineExitCause("install", exitCode, run.signalCode)}`, {
+      exitCode: 1,
+      stderr: events.stderr.trim(),
+      hint: SUPPORT_BUNDLE_HINT,
+    });
   }
 }
 

package/src/engine.ts

@@ -7,8 +7,8 @@ import { log } from "./log";
 import { createLiveStatus } from "./progress";
 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 { engineExitCause, engineSignal, runEngineProcess, spawnHint } from "./engine/spawn";
+import { engineFailure, KeshaError, quoteInvalidLine, renderError, SUPPORT_BUNDLE_HINT, type ErrorEvent } from "./engine/events";
 import { MIN_ENGINE_VERSION, predatesMinimumEngine, readInstalledEngineVersion } from "./engine-version-marker";
 import {
   describeToCapabilities,
@@ -90,6 +90,7 @@ interface EngineRun {
   stdout: string;
   stderr: string;
   exitCode: number;
+  signalCode: string | null;
   error: ErrorEvent | null;
   invalid: string[];
 }
@@ -113,7 +114,7 @@ async function runEngine(args: string[], opts: RunEngineOptions = {}): Promise<E
   // #275 D4: warnings reach the user on success; on failure they travel inside the KeshaError.
   if (run.exitCode === 0 && events.invalid.length === 0 && events.error === null && stderr.length > 0)
     process.stderr.write(`${stderr}\n`);
-  return { stdout: run.stdout.trim(), stderr, exitCode: run.exitCode, error: events.error, invalid: events.invalid };
+  return { stdout: run.stdout.trim(), stderr, exitCode: run.exitCode, signalCode: run.signalCode, error: events.error, invalid: events.invalid };
 }
 
 /** The run failed and said so: a non-zero status, or an error event whatever the status. */
@@ -302,9 +303,10 @@ export function buildTranscribeArgs(
   opts: TranscribeEngineOptions,
   json = false,
 ): string[] {
-  const args = ["transcribe", audioPath, ...(json ? ["--json"] : []), ...vadArg(opts.vad)];
+  const args = ["transcribe", ...(json ? ["--json"] : []), ...vadArg(opts.vad)];
   if (opts.itn) args.push("--itn");
   if (json && opts.speakers) args.push("--speakers");
+  args.push("--", audioPath);
   return args;
 }
 
@@ -318,7 +320,7 @@ export function withVirtualMacHint(
   platform: string = process.platform,
   isVirtualMac: () => boolean = hostIsVirtualMac,
 ): KeshaError {
-  if (platform !== "darwin" || err.hint || !err.message.includes("Swift bridge error") || !isVirtualMac()) return err;
+  if (platform !== "darwin" || !err.message.includes("Swift bridge error") || !isVirtualMac()) return err;
   return new KeshaError(err.code, err.message, {
     exitCode: err.exitCode,
     stderr: err.stderr,
@@ -327,10 +329,22 @@ export function withVirtualMacHint(
   });
 }
 
+function transcribeFailure(command: string, run: EngineRun): KeshaError {
+  const failure = engineFailure(command, run, run.exitCode);
+  const signal = run.error === null && run.invalid.length === 0 ? engineSignal(run.exitCode, run.signalCode) : null;
+  if (!signal) return failure;
+  return new KeshaError("E_INTERNAL", `kesha-engine ${command} was killed by ${signal}`, {
+    exitCode: failure.exitCode,
+    stderr: failure.stderr,
+    origin: failure.origin,
+    hint: SUPPORT_BUNDLE_HINT,
+  });
+}
+
 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 withVirtualMacHint(engineFailure(args[0] ?? "", run, run.exitCode));
+  if (failed(run)) throw withVirtualMacHint(transcribeFailure(args[0] ?? "", run));
   return run.stdout;
 }
 
@@ -388,12 +402,14 @@ 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 withVirtualMacHint(engineFailure(args[0] ?? "", run, run.exitCode));
+  if (failed(run)) throw withVirtualMacHint(transcribeFailure(args[0] ?? "", run));
   try {
     return parseTranscriptionOutput(run.stdout);
   } catch (err: unknown) {
     const message = err instanceof Error ? err.message : String(err);
-    throw new KeshaError(err instanceof KeshaError ? err.code : "E_INTERNAL", `${message}: ${run.stdout}`);
+    throw new KeshaError(err instanceof KeshaError ? err.code : "E_INTERNAL", `${message}: ${quoteInvalidLine(run.stdout)}`, {
+      hint: SUPPORT_BUNDLE_HINT,
+    });
   }
 }
 
@@ -417,7 +433,7 @@ export type RecordTarget =
 const SIGNALLED_LIVE_EXIT_CODES = new Set([130, 143]);
 
 export function buildRecordArgs(target: RecordTarget, maxSeconds: number): string[] {
-  if (!target.live) return ["record", "--out", target.out, "--max-seconds", String(maxSeconds)];
+  if (!target.live) return ["record", `--out=${target.out}`, "--max-seconds", String(maxSeconds)];
   const args = ["record", "--live", "--max-seconds", String(maxSeconds)];
   if (target.autoStop) {
     args.push(
@@ -511,7 +527,13 @@ export async function recordEngine(target: RecordTarget, maxSeconds: number): Pr
   // so an error event beside that status is a real failure the signal must not excuse.
   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}`);
+  if (!signalled && exitCode !== 0) {
+    throw new KeshaError("E_INTERNAL", engineExitCause("record", exitCode, run.signalCode), {
+      exitCode: 1,
+      stderr: events.stderr.trim(),
+      hint: SUPPORT_BUNDLE_HINT,
+    });
+  }
 }
 
 export function parseLangResult(stdout: string): LangDetectResult | null {
@@ -531,14 +553,13 @@ export async function detectAudioLanguageEngine(
   opts: RunEngineOptions = {},
 ): Promise<LangDetectResult | null> {
   if (!isEngineInstalled()) return null;
-  const run = await runEngine(["detect-lang", audioPath], opts);
+  const run = await runEngine(["detect-lang", "--", audioPath], opts);
   // The tolerant form: a noisy onnxruntime warning must not blind a best-effort guess.
   if (reportedFailure(run)) {
-    const cause = run.error ? renderError(run.error) : `kesha-engine detect-lang exited with code ${run.exitCode}`;
-    log.warn(
-      `Audio language detection failed: ${cause}\n` +
-        "  Fix: run `kesha install` to reinstall the engine and its language-ID model.",
-    );
+    const crashed = !run.error && engineSignal(run.exitCode, run.signalCode) !== null;
+    const cause = run.error ? renderError(run.error) : engineExitCause("detect-lang", run.exitCode, run.signalCode);
+    const fix = crashed ? SUPPORT_BUNDLE_HINT : "run `kesha install` to reinstall the engine and its language-ID model.";
+    log.warn(`Audio language detection failed: ${cause}\n  Fix: ${fix}`);
     return null;
   }
   return parseLangResult(run.stdout);

package/src/format.ts

@@ -1,4 +1,4 @@
-import { LANG_CONFIDENCE_FLOOR, routeLanguage } from "./language-routing";
+import { LANG_CONFIDENCE_FLOOR, routeLanguage, unsupportedAudioLanguageWarning } from "./language-routing";
 import type { TranscribeErrorRecord, TranscribeJsonOutput, TranscribeResult } from "./types";
 
 const BELOW_FLOOR_NOTE = `below the ${LANG_CONFIDENCE_FLOOR} floor, ignored for lang`;
@@ -51,8 +51,9 @@ export function formatTranscriptOutput(results: TranscribeResult[]): string {
         lines.push(`=== ${r.file} ===`);
       }
       lines.push(r.text);
-      const lang = r.textLanguage?.code || r.audioLanguage?.code || r.lang;
-      const confidence = r.textLanguage?.confidence ?? r.audioLanguage?.confidence;
+      const detected = unsupportedAudioLanguageWarning(r.audioLanguage, r.textLanguage) ? r.audioLanguage : (r.textLanguage ?? r.audioLanguage);
+      const lang = detected?.code || r.lang;
+      const confidence = detected?.confidence;
       if (lang) lines.push(`[lang: ${lang}${confidence != null ? `, confidence: ${confidence.toFixed(2)}` : ""}]`);
       return lines.join("\n");
     })

package/src/language-routing.ts

@@ -5,6 +5,25 @@ import type { TextLangDetectResult } from "./types";
 /** A guess scoring below this is kept in its raw field but never names the top-level `lang` (Exploratory S11-2, S11-4). */
 export const LANG_CONFIDENCE_FLOOR = 0.5;
 
+/** The speech-to-text languages in docs/languages.md; keep the two in step. */
+const ASR_LANGUAGES = new Set([
+  "bg", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hu", "it",
+  "lv", "lt", "mt", "pl", "pt", "ro", "ru", "sk", "sl", "es", "sv", "uk",
+]);
+
+/** Audio lang-id this sure of a non-ASR language outranks text detection on the transcript (#1463: zh audio 0.999 vs text 0.63). */
+export const UNSUPPORTED_AUDIO_LANGUAGE_CONFIDENCE = 0.95;
+
+export function unsupportedAudioLanguageWarning(
+  audioLanguage: LangDetectResult | undefined,
+  textLanguage: TextLangDetectResult | undefined,
+): string | null {
+  if (!audioLanguage?.code || audioLanguage.confidence < UNSUPPORTED_AUDIO_LANGUAGE_CONFIDENCE) return null;
+  if (ASR_LANGUAGES.has(audioLanguage.code)) return null;
+  if (textLanguage && ASR_LANGUAGES.has(textLanguage.code) && textLanguage.confidence >= LANG_CONFIDENCE_FLOOR) return null;
+  return `warning: audio language "${audioLanguage.code}" is not one kesha can transcribe; the text is unreliable (supported: docs/languages.md)`;
+}
+
 export type LangRouteSource = "engine" | "tinyld" | "audio";
 
 export interface LanguageRoute {
@@ -14,7 +33,8 @@ export interface LanguageRoute {
 }
 
 /**
- * Picks the top-level `lang` from what the detectors returned: the Engine's text result as-is,
+ * Picks the top-level `lang` from what the detectors returned: confident audio in a language outside the ASR set,
+ * else the Engine's text result as-is,
  * else a `tinyld` guess that clears `LANG_CONFIDENCE_FLOOR`, else audio that clears it, else "".
  */
 export function routeLanguage(input: {
@@ -28,6 +48,9 @@ export function routeLanguage(input: {
     textLanguage.confidence < LANG_CONFIDENCE_FLOOR;
   const audioBelowFloor = audioLanguage !== undefined && audioLanguage.confidence < LANG_CONFIDENCE_FLOOR;
   const belowFloor = { audio: audioBelowFloor, text: textBelowFloor };
+  if (audioLanguage && unsupportedAudioLanguageWarning(audioLanguage, textLanguage)) {
+    return { lang: audioLanguage.code, source: "audio", belowFloor };
+  }
   if (textLanguage?.code && !textBelowFloor) {
     return { lang: textLanguage.code, source: textLanguage.source, belowFloor };
   }

package/src/mcp/tools.ts

@@ -2,6 +2,7 @@ import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mc
 import { errorMessage } from "../error-utils";
 import { KeshaError } from "../engine/events";
 import { installHint } from "../install-hint";
+import { PATH_ERRNOS } from "../path-errnos";
 import { z } from "zod";
 import { chmodSync, existsSync, readFileSync, statSync } from "fs";
 import { basename, isAbsolute, join } from "path";
@@ -29,7 +30,11 @@ export function registerTools(server: McpServer): void {
       try {
         bytes = readFileSync(filePath);
       } catch {
-        throw new Error(`synthesized-audio: file not found or already swept: ${name}`);
+        // The SDK sends only `message`, so the code and hint go inside it.
+        const coded = new KeshaError("E_INPUT_NOT_FOUND", `synthesized-audio: file not found or already swept: ${name}`, {
+          hint: "synthesized files are deleted after 24 hours; call synthesize_speech again.",
+        });
+        throw new Error(errorMessage(coded));
       }
       return { contents: [{ uri: uri.href, mimeType: mimeForExt(name), blob: bytes.toString("base64") }] };
     },
@@ -66,7 +71,17 @@ export function registerTools(server: McpServer): void {
         return { isError: true, content: [{ type: "text" as const, text: errorMessage(err) }] };
       }
       const fmt: SayFormat = format ?? "wav";
-      const outPath = allocAudioPath(fmt);
+      let outPath: string;
+      try {
+        outPath = allocAudioPath(fmt);
+      } catch (err) {
+        const errno = (err as NodeJS.ErrnoException).code ?? "";
+        const why = PATH_ERRNOS[errno];
+        const coded = new KeshaError(why ? "E_INVALID_ARG" : "E_INTERNAL", `cannot create the audio folder ${audioDir()}: ${why ? `${why} (${errno})` : errorMessage(err)}`, {
+          hint: "set KESHA_HOME to a directory you can write to.",
+        });
+        return { isError: true, content: [{ type: "text" as const, text: errorMessage(coded) }] };
+      }
       try {
         // An MCP caller has no stderr to read: the voice it is told is its only record (#942).
         const resolvedVoice = (await resolveSayVoice(voice, undefined, text, { signal: extra.signal })) ?? DEFAULT_VOICE_ID;
@@ -173,7 +188,7 @@ export function registerTools(server: McpServer): void {
           structuredContent: { voices },
         };
       } catch (err) {
-        return { isError: true, content: [{ type: "text" as const, text: `list_voices failed: ${errorMessage(err)}` }] };
+        return { isError: true, content: [{ type: "text" as const, text: errorMessage(err) }] };
       }
     },
   );
@@ -203,7 +218,7 @@ export function registerTools(server: McpServer): void {
           structuredContent: { languages },
         };
       } catch (err) {
-        return { isError: true, content: [{ type: "text" as const, text: `list_languages failed: ${errorMessage(err)}` }] };
+        return { isError: true, content: [{ type: "text" as const, text: errorMessage(err) }] };
       }
     },
   );

package/src/stats.ts

@@ -1,4 +1,5 @@
 import { Database } from "bun:sqlite";
+import { KeshaError } from "./engine/events";
 import { errorMessage } from "./error-utils";
 import { humanBytes } from "./format";
 import { existsSync, mkdirSync, statSync } from "fs";
@@ -11,6 +12,8 @@ import { resolveStatePaths } from "./state-paths";
 const SCHEMA_VERSION = 1;
 const MAX_ERROR_MESSAGE_CHARS = 300;
 const DEFAULT_RETENTION_DAYS = 90;
+// A Date reaches back only 100,000,000 days before 1970: a longer retention makes the cutoff an Invalid Date.
+export const MAX_RETENTION_DAYS = 100_000_000;
 const APP_VERSION = readPackageVersion();
 
 export type StatsCommandName = "transcribe" | "say";
@@ -148,7 +151,9 @@ let warnedStatsWriteFailed = false;
 
 function warnStatsWriteFailed(err: unknown): void {
   if (!warnedStatsWriteFailed) {
-    log.warn("warning: failed to write Kesha Stats; continuing without stats for this event");
+    log.warn(
+      `warning: failed to write Kesha Stats at ${resolveStatsDbPath()} (${errorMessage(err)}); continuing without stats for this event; fix that, or run \`kesha stats disable\` to stop recording.`,
+    );
     warnedStatsWriteFailed = true;
   }
   const message = errorMessage(err);
@@ -175,9 +180,28 @@ export function createStatsRecorder(command: StatsCommandName): StatsRecorder {
 
 /** Open the stats DB (creating it if needed), run fn, always close. */
 function withStatsDb<T>(fn: (db: Database) => T): T {
-  const db = openStatsDatabase(resolveStatsDbPath());
+  const dbPath = resolveStatsDbPath();
+  let db: Database;
+  try {
+    db = openStatsDatabase(dbPath);
+  } catch (err) {
+    const code = (err as { code?: unknown }).code;
+    const corrupt = code === "SQLITE_NOTADB" || code === "SQLITE_CORRUPT";
+    throw new KeshaError("E_INTERNAL", `cannot open the Kesha Stats database ${dbPath}: ${errorMessage(err)}`, {
+      hint: corrupt
+        ? `delete ${dbPath} to start over; Stats stays off until \`kesha stats enable\` creates a new one.`
+        : `check that ${dbPath} and its folder can be read and written, or point KESHA_STATS_DB at another file.`,
+    });
+  }
   try {
     return fn(db);
+  } catch (err) {
+    const busy = String((err as { code?: unknown }).code ?? "").startsWith("SQLITE_BUSY");
+    throw new KeshaError("E_INTERNAL", `cannot read or write the Kesha Stats database ${dbPath}: ${errorMessage(err)}`, {
+      hint: busy
+        ? "another kesha command is writing to it; retry when that command finishes."
+        : `check that ${dbPath} and its folder can be written and that its disk has free space, or point KESHA_STATS_DB at another file.`,
+    });
   } finally {
     db.close();
   }
@@ -958,7 +982,7 @@ function parseRetentionSetting(raw: string): number | null {
   const normalized = raw.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 DEFAULT_RETENTION_DAYS;
 }
 

package/src/stdout-pipe.ts

@@ -1,3 +1,4 @@
+import { renderError } from "./engine/events";
 import { errorMessage } from "./error-utils";
 import { log } from "./log";
 
@@ -9,6 +10,7 @@ let guarded = false;
  * try/catch around the write, so it escaped as an uncaught stack trace and turned a
  * successful synthesis into exit 1 (#1001). EPIPE alone means the reader left; every other
  * write failure still reports and exits non-zero.
+ * A stdout closed before launch (`>&-`) never errors here: Bun reopens fd 1 as /dev/null (#1471).
  */
 export function guardStdoutWrites(): void {
   if (guarded) return;
@@ -19,7 +21,11 @@ export function guardStdoutWrites(): void {
       return;
     }
     log.error(
-      `failed writing to stdout: ${errorMessage(err)}. Check that the destination is writable and has free space.`,
+      renderError({
+        code: "E_INTERNAL",
+        message: `failed writing to stdout: ${errorMessage(err)}`,
+        hint: "free disk space or check what stdout is redirected to.",
+      }),
     );
     process.exitCode = 1;
   });

package/src/synth.ts

@@ -1,5 +1,5 @@
 import { getDescribe, getEngineBinPath, isEngineInstalled } from "./engine";
-import { runEngineProcess } from "./engine/spawn";
+import { engineSignal, runEngineProcess } from "./engine/spawn";
 import { validateArgv } from "./engine/describe";
 import { engineFailure, exitCodeFor, KeshaError, type EventSinks } from "./engine/events";
 import { installHint } from "./install-hint";
@@ -18,6 +18,7 @@ export type SayFormat = "wav" | "ogg-opus" | "flac";
 export const SUPPORTED_SAMPLE_RATES = [8000, 12000, 16000, 24000, 48000] as const;
 export type SupportedSampleRate = (typeof SUPPORTED_SAMPLE_RATES)[number];
 export const MAX_TEXT_CHARS = 5000;
+export const TEXT_TOO_LONG_HINT = `split the text into requests of at most ${MAX_TEXT_CHARS} characters`;
 
 type SayBase = {
   /**
@@ -57,7 +58,7 @@ export function buildSayArgs(o: SayOptions): string[] {
   const args: string[] = ["say"];
   if (o.voice) args.push("--voice", o.voice);
   if (o.lang) args.push("--lang", o.lang);
-  if (o.out) args.push("--out", o.out);
+  if (o.out) args.push(`--out=${o.out}`);
   if (o.rate !== undefined && o.rate !== 1.0) args.push("--rate", String(o.rate));
   if (o.ssml) args.push("--ssml");
   if (o.format) args.push("--format", o.format);
@@ -68,23 +69,13 @@ export function buildSayArgs(o: SayOptions): string[] {
   return args;
 }
 
-/** Fault signals, by number. SIGBUS is 10 on darwin but 7 on linux. */
-const FAULT_SIGNALS: Record<number, string> = { 4: "SIGILL", 6: "SIGABRT", 8: "SIGFPE", 11: "SIGSEGV" };
-
-/** Explains a signal death, which leaves no error event; the wait status outranks Bun's signalCode (10 is SIGBUS on darwin, SIGUSR1 to Bun). */
+/** Explains a signal death, which leaves no error event. */
 export function engineCrashMessage(
   exitCode: number,
   signalCode: string | null,
   platform: string = process.platform,
 ): string | null {
-  const number = exitCode > 128 ? exitCode - 128 : undefined;
-  const sigbus = platform === "darwin" ? 10 : 7;
-  const signal =
-    number === undefined
-      ? (signalCode ?? undefined)
-      : number === sigbus
-        ? "SIGBUS"
-        : (FAULT_SIGNALS[number] ?? signalCode ?? undefined);
+  const signal = engineSignal(exitCode, signalCode, platform);
   if (!signal) return null;
   const base = `kesha-engine was killed by ${signal} and produced no audio`;
   // Every physical Apple Silicon Mac has a Neural Engine; virtualised macOS has
@@ -148,7 +139,11 @@ export function validateSayText(text: string): void {
   }
   const chars = Array.from(text).length;
   if (chars > MAX_TEXT_CHARS) {
-    throw new KeshaError("E_TEXT_TOO_LONG", `text exceeds ${MAX_TEXT_CHARS} chars (${chars})`, { exitCode: 5, stderr: "" });
+    throw new KeshaError("E_TEXT_TOO_LONG", `text exceeds ${MAX_TEXT_CHARS} chars (${chars})`, {
+      exitCode: 5,
+      stderr: "",
+      hint: TEXT_TOO_LONG_HINT,
+    });
   }
   if (text.includes("\0")) {
     throw new KeshaError("E_INVALID_ARG", "text contains a NUL byte", { exitCode: 2, stderr: "" });

package/src/transcribe.ts

@@ -24,6 +24,19 @@ export function isDirectoryPath(path: string): boolean {
   }
 }
 
+export const SPECIAL_FILE_HINT =
+  "kesha reads its input more than once, so a named pipe, /dev/stdin or <(...) cannot work; save the audio to a file and pass that.";
+
+/** True when `path` exists and is neither a regular file nor a directory: the engine opens its input more than once, so a FIFO, `/dev/stdin` or `<(...)` hangs it (#1468). */
+export function isSpecialFilePath(path: string): boolean {
+  try {
+    const st = statSync(path);
+    return !st.isFile() && !st.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 export interface TranscribeOptions {
   /** Silero VAD preprocessing selector. Defaults to `"auto"`. */
   vad?: VadMode;
@@ -54,6 +67,9 @@ export function assertAudioFileArgument(audioPath: string): void {
   if (isDirectoryPath(audioPath)) {
     throw new KeshaError("E_INVALID_ARG", `${audioPath}: is a directory (expected an audio file)`);
   }
+  if (isSpecialFilePath(audioPath)) {
+    throw new KeshaError("E_INVALID_ARG", `${audioPath}: is not a regular file (expected an audio file)`, { hint: SPECIAL_FILE_HINT });
+  }
 }
 
 /** The CLI's gate before any progress UI: the engine, its describe document, the request's flags, and the model files a request needs; the argv actually sent is validated again at the spawn. */