@drakulavich/kesha-voice-kit 2.2.0 → 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/completions/kesha.fish

@@ -26,7 +26,7 @@ complete -c kesha -n '__fish_use_subcommand' -l format -r -d 'Output format: tra
 complete -c kesha -n '__fish_use_subcommand' -l lang -r -d 'Expected language code, e.g. en or en-us (see docs/languages.md); warn if mismatch'
 complete -c kesha -n '__fish_use_subcommand' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
 complete -c kesha -n '__fish_use_subcommand' -l vad -d 'Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.'
-complete -c kesha -n '__fish_use_subcommand' -l no-vad -d 'Force full-file ASR for short/medium files; long audio fails early. Incompatible with --speakers'
+complete -c kesha -n '__fish_use_subcommand' -l no-vad -d 'Skip VAD and transcribe the whole file in one pass; audio measured at 24 minutes or more is refused. Incompatible with --speakers'
 complete -c kesha -n '__fish_use_subcommand' -l quiet -d 'Suppress progress output; print only results and errors'
 complete -c kesha -n '__fish_use_subcommand' -l no-color -d 'Disable ANSI colors (also via NO_COLOR=1; auto-off when CI=true)'
 complete -c kesha -n '__fish_seen_subcommand_from completions' -l help -d 'Show help'

package/completions/kesha.zsh

@@ -35,7 +35,7 @@ _kesha() {
       '--lang=[Expected language code, e.g. en or en-us (see docs/languages.md); warn if mismatch]:lang:' \
       '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]' \
       '--vad[Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.]' \
-      '--no-vad[Force full-file ASR for short/medium files; long audio fails early. Incompatible with --speakers]' \
+      '--no-vad[Skip VAD and transcribe the whole file in one pass; audio measured at 24 minutes or more is refused. Incompatible with --speakers]' \
       '--quiet[Suppress progress output; print only results and errors]' \
       '--no-color[Disable ANSI colors (also via NO_COLOR=1; auto-off when CI=true)]'
     else
@@ -154,7 +154,7 @@ _kesha() {
       '--lang=[Expected language code, e.g. en or en-us (see docs/languages.md); warn if mismatch]:lang:' \
       '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]' \
       '--vad[Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.]' \
-      '--no-vad[Force full-file ASR for short/medium files; long audio fails early. Incompatible with --speakers]' \
+      '--no-vad[Skip VAD and transcribe the whole file in one pass; audio measured at 24 minutes or more is refused. Incompatible with --speakers]' \
       '--quiet[Suppress progress output; print only results and errors]' \
       '--no-color[Disable ANSI colors (also via NO_COLOR=1; auto-off when CI=true)]' \
       '*:audio file:_files'

package/man/kesha.1

@@ -82,7 +82,7 @@ Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)
 Force Silero VAD preprocessing (kesha install \-\-vad first). Without this, VAD auto\-engages on audio ≥ 120s.
 .TP
 .B \-\-no\-vad
-Force full\-file ASR for short/medium files; long audio fails early. Incompatible with \-\-speakers
+Skip VAD and transcribe the whole file in one pass; audio measured at 24 minutes or more is refused. Incompatible with \-\-speakers
 .TP
 .B \-\-quiet
 Suppress progress output; print only results and errors

package/model-plan.json

@@ -161,6 +161,9 @@
     { "relPath": "g2pw/g2pw.mlmodelc/weights/weight.bin", "sizeBytes": 159294962 }
   ],
   "aneZhG2p": [
+    { "relPath": "g2p/jieba_hmm_emit.bin", "sizeBytes": 292640 },
+    { "relPath": "g2p/jieba_hmm_start.bin", "sizeBytes": 16 },
+    { "relPath": "g2p/jieba_hmm_trans.bin", "sizeBytes": 64 },
     { "relPath": "g2p/pinyin_phrases.bin", "sizeBytes": 9552083 },
     { "relPath": "g2p/pinyin_single.bin", "sizeBytes": 480169 }
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "2.2.0",
+  "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": {
@@ -50,8 +50,8 @@
     "coverage:rust": "mkdir -p coverage/rust && cd rust && cargo llvm-cov nextest --features tts --lcov --output-path ../coverage/rust/lcov.info",
     "coverage:check:rust": "bun .github/scripts/check-coverage.ts --preset=rust --lcov=coverage/rust/lcov.info --summary=coverage/rust/summary.md",
     "generate:shell-artifacts": "bun scripts/generate-shell-artifacts.ts",
-    "lint": "bunx tsc --noEmit",
-    "check": "bun run lint && bun run check:versions && bun run check:recipes && bun run test:cli-fast",
+    "lint": "bun check",
+    "check:fast": "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": "openspec validate --specs --strict",
@@ -89,7 +89,6 @@
     "@fission-ai/openspec": "1.14.1",
     "@types/bun": "latest",
     "fast-xml-parser": "^5.8.0",
-    "typescript": "^7.0.2",
     "yaml": "^2.9.0"
   },
   "dependencies": {
@@ -110,20 +109,20 @@
   },
   "kesha": {
     "engine": {
-      "version": "2.2.0",
+      "version": "2.3.0-beta.2",
       "sha256": {
-        "kesha-engine-darwin-arm64": "916ec3dbcb84337487d953b08816f6939ee3995d0851acd8acc5e084449e87cc",
-        "kesha-engine-linux-x64": "b25b77d3b0a64ccc6b0d276fd0a3fd320c60f06700e1ccfcb792359150248012",
-        "kesha-engine-windows-x64.exe": "e87a497444180f1d40ae0c51c78028bc41abc73523ba1e9e5f2bb71f278bf443",
-        "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": 73639712,
-        "kesha-engine-linux-x64": 67404968,
-        "kesha-engine-windows-x64.exe": 66583040,
-        "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;
 
@@ -295,6 +300,14 @@ type ProcessFileSuccess = { ok: true; result: TranscribeResult };
 type ProcessFileFailure = { ok: false; error: TranscribeErrorRecord; exitCode: number };
 
 /** An argument the CLI itself rejected exits by its code (2); every runtime failure keeps the batch's operational 1 (S9-F1). */
+/** `kesha <dir>/*.ogg`, pasteable: a name starting with `-` would parse as a flag, and only Windows separates with `\`. */
+export function folderGlobHint(dir: string): string {
+  const trimmed = dir.replace(process.platform === "win32" ? /[\\/]+$/ : /\/+$/, "");
+  const path = trimmed.startsWith("-") ? `./${trimmed}` : trimmed;
+  const quoted = /^[\w./-]+$/.test(path) ? path : `'${path.replaceAll("'", `'\\''`)}'`;
+  return `kesha ${quoted}/*.ogg`;
+}
+
 function failureExitCode(err: unknown): number {
   const usage = err instanceof KeshaError && err.origin === "cli" && err.code === "E_INVALID_ARG";
   return usage ? exitCodeFor(err) : 1;
@@ -320,7 +333,22 @@ async function processFile(
   }
 
   if (isDirectoryPath(file)) {
-    const err = new KeshaError("E_INVALID_ARG", "is a directory (expected an audio file)");
+    const err = new KeshaError("E_INVALID_ARG", "is a directory (expected an audio file)", {
+      hint: `pass the audio files in it instead, e.g. ${folderGlobHint(file)}`,
+    });
+    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 (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",
@@ -346,9 +374,8 @@ async function processFile(
   // so the engine's progress has to land while it happens, not once the run is over.
   const showProgressLine = (line: string) => {
     if (log.quietEnabled) return;
-    const write = () => process.stderr.write(`${line}\n`);
-    if (progress) progress.interrupt(write);
-    else write();
+    if (progress) progress.status(line);
+    else process.stderr.write(`${line}\n`);
   };
   try {
     await validateTranscribeRequest({ vad: vadMode, timestamps, speakers, itn });
@@ -451,7 +478,7 @@ export const MAIN_VAD_ARGS = {
   "no-vad": {
     type: "boolean",
     description:
-      "Force full-file ASR for short/medium files; long audio fails early. Incompatible with --speakers",
+      "Skip VAD and transcribe the whole file in one pass; audio measured at 24 minutes or more is refused. Incompatible with --speakers",
     default: false,
   },
 } as const;

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/install-hint.ts

@@ -7,6 +7,8 @@
 // `--no-cache`) — they preselect modules in the interactive wizard rather than
 // being install-only flags. Source of truth: `src/cli/init.ts::initCommand.args`.
 export function installHint(...flags: string[]): string {
-  const verb = process.stderr.isTTY ? "kesha init" : "kesha install";
+  // `kesha init` refuses unless stdin and stdout are terminals (#1373), so a piped run gets `install` (#1380).
+  const interactive = process.stdin.isTTY && process.stdout.isTTY && process.stderr.isTTY;
+  const verb = interactive ? "kesha init" : "kesha install";
   return [verb, ...flags].join(" ");
 }

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") }] };
     },
@@ -59,13 +64,24 @@ export function registerTools(server: McpServer): void {
     },
     async ({ text, voice, rate, format }, extra) => {
       if (extra.signal?.aborted) {
-        return { isError: true, content: [{ type: "text" as const, text: "request cancelled" }] };
+        return { isError: true, content: [{ type: "text" as const, text: errorMessage(new KeshaError("E_INTERRUPTED", "request cancelled")) }] };
       }
       if (rate !== undefined && !(rate >= 0.5 && rate <= 2.0)) {
-        return { isError: true, content: [{ type: "text" as const, text: `rate ${rate} out of range (0.5-2.0)` }] };
+        const err = new KeshaError("E_INVALID_ARG", `rate ${rate} out of range (0.5-2.0)`);
+        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;
@@ -121,7 +137,7 @@ export function registerTools(server: McpServer): void {
     },
     async ({ path, timestamps }, extra) => {
       if (extra.signal?.aborted) {
-        return { isError: true, content: [{ type: "text" as const, text: "request cancelled" }] };
+        return { isError: true, content: [{ type: "text" as const, text: errorMessage(new KeshaError("E_INTERRUPTED", "request cancelled")) }] };
       }
       if (!existsSync(path)) {
         const hint = isAbsolute(path)
@@ -172,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) }] };
       }
     },
   );
@@ -202,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/progress.ts

@@ -36,12 +36,28 @@ export function estimatePercent(elapsedMs: number, estimatedTotalMs: number): nu
   return Math.max(1, Math.min(99, Math.floor((elapsedMs / targetMs) * 99)));
 }
 
+// Whatever was painted on the row before, by this bar or another, would show past a shorter frame (#1440).
+const ERASE_TO_EOL = "\x1b[K";
+
+/** Cuts `text` to `max` terminal columns, ending in `…` when cut; wide (CJK) characters count as two. */
+function fitWidth(text: string, max: number): string {
+  if (Bun.stringWidth(text) <= max) return text;
+  if (max <= 0) return "";
+  let out = "";
+  for (const { segment } of new Intl.Segmenter().segment(text)) {
+    if (Bun.stringWidth(`${out}${segment}…`) > max) break;
+    out += segment;
+  }
+  return `${out}…`;
+}
+
 export function createPercentProgress(
   label: string,
   options: { estimatedTotalMs?: number; intervalMs?: number } = {},
 ): {
   finish(finalLabel: string): void;
   interrupt(writeLine: () => void): void;
+  status(line: string): void;
   stop(): void;
 } {
   const isTTY = process.stderr.isTTY;
@@ -55,6 +71,9 @@ export function createPercentProgress(
       interrupt(writeLine: () => void) {
         writeLine();
       },
+      status(line: string) {
+        process.stderr.write(`${line}\n`);
+      },
       stop() {},
     };
   }
@@ -62,18 +81,23 @@ export function createPercentProgress(
   const intervalMs = options.intervalMs ?? 250;
   const estimatedTotalMs = options.estimatedTotalMs ?? DEFAULT_ESTIMATED_PROGRESS_MS;
   const startedAt = performance.now();
-  let lastLineLength = 0;
+  let painted = false;
   let timer: Timer | undefined;
   let stopped = false;
   let firstRender = true;
+  let statusText = "";
 
   const render = () => {
     if (stopped) return;
     const percent = firstRender ? 0 : estimatePercent(performance.now() - startedAt, estimatedTotalMs);
     firstRender = false;
-    const line = formatPercentProgress(label, percent);
-    lastLineLength = line.length;
-    process.stderr.write(`\r${line}`);
+    const rest = formatPercentProgress("", percent) + (statusText ? `  ${statusText}` : "");
+    // A row wider than the terminal wraps, and `\r` then repaints only its last part; the file name gives way first.
+    const columns = process.stderr.columns;
+    const name = columns ? fitWidth(label, columns - 1 - Bun.stringWidth(rest)) : label;
+    const line = columns ? fitWidth(name + rest, columns - 1) : name + rest;
+    painted = true;
+    process.stderr.write(`\r${line}${ERASE_TO_EOL}`);
   };
 
   const clearLine = (stopTimer: boolean) => {
@@ -82,9 +106,9 @@ export function createPercentProgress(
       clearInterval(timer);
       timer = undefined;
     }
-    if (lastLineLength > 0) {
-      process.stderr.write(`\r${" ".repeat(lastLineLength)}\r`);
-      lastLineLength = 0;
+    if (painted) {
+      process.stderr.write(`\r${ERASE_TO_EOL}`);
+      painted = false;
     }
   };
 
@@ -106,6 +130,14 @@ export function createPercentProgress(
       render();
       timer = setInterval(render, intervalMs);
     },
+    status(line: string) {
+      if (stopped) {
+        process.stderr.write(`${line}\n`);
+        return;
+      }
+      statusText = line;
+      render();
+    },
     stop() {
       clearLine(true);
     },
@@ -119,11 +151,11 @@ export function createPercentProgress(
  */
 export function createLiveStatus(): { update(line: string): void; clear(): void } {
   const isTTY = process.stderr.isTTY && !log.quietEnabled;
-  let painted = 0;
+  let painted = false;
   const erase = () => {
-    if (painted === 0) return;
-    process.stderr.write(`\r${" ".repeat(painted)}\r`);
-    painted = 0;
+    if (!painted) return;
+    process.stderr.write(`\r${ERASE_TO_EOL}`);
+    painted = false;
   };
   // Ctrl-C exits through `process.exit` without unwinding the spawn's `finally` (src/process-tree.ts),
   // so without this the painted row survives into the shell prompt.
@@ -131,13 +163,12 @@ export function createLiveStatus(): { update(line: string): void; clear(): void
   return {
     update(line: string) {
       if (!isTTY) return;
-      if (painted === 0) process.once("exit", onExit);
-      const pad = painted > line.length ? " ".repeat(painted - line.length) : "";
-      process.stderr.write(`\r${line}${pad}`);
-      painted = line.length;
+      if (!painted) process.once("exit", onExit);
+      process.stderr.write(`\r${line}${ERASE_TO_EOL}`);
+      painted = true;
     },
     clear() {
-      if (painted === 0) return;
+      if (!painted) return;
       erase();
       process.removeListener("exit", onExit);
     },
@@ -303,11 +334,11 @@ export function createProgressBar(label: string, totalBytes: number): {
       if (pct === lastPct) return;
       lastPct = pct;
       const line = formatProgressBar(label, current, totalBytes);
-      process.stderr.write(`\r${line}`);
+      process.stderr.write(`\r${line}${ERASE_TO_EOL}`);
     },
     finish() {
       const line = formatProgressBar(label, totalBytes, totalBytes);
-      process.stderr.write(`\r${line}\n`);
+      process.stderr.write(`\r${line}${ERASE_TO_EOL}\n`);
     },
   };
 }

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
@@ -102,6 +93,42 @@ export function engineCrashMessage(
   return `${base}.`;
 }
 
+// ©, ® and ™ stay, emoji presentation (U+FE0F) or not: read aloud they still mean something.
+const KEPT_SYMBOL = /([©®™])️/g;
+const EMOJI = /\p{RGI_Emoji}|[\p{Extended_Pictographic}--[©®™]]/gv;
+
+/**
+ * Emoji are decoration in a reply; a voice would read out their Unicode names (#1388).
+ * Emoji-only text, SSML tags aside, goes through unchanged, so the engine still refuses it as E_SCRIPT_UNSUPPORTED.
+ */
+export function dropEmoji(text: string, ssml = false): string {
+  const spoken = (ssml ? decodeCharRefs(text) : text).replace(KEPT_SYMBOL, "$1").replace(EMOJI, "");
+  const speech = ssml ? spoken.replace(CDATA, "$1").replace(/<[^>]*>/g, "") : spoken;
+  return speech.trim().length > 0 ? spoken : text;
+}
+
+const CDATA = /<!\[CDATA\[([\s\S]*?)\]\]>/g;
+const NUMERIC_REF = /&#(?:x([0-9a-f]+)|(\d+));/gi;
+
+/**
+ * The engine decodes SSML character references, so `&#x1F60A;` is an emoji too. Decoding them first lets the
+ * emoji filter see sequences spelled across references; CDATA keeps its text literal, and markup characters stay escaped.
+ */
+function decodeCharRefs(ssml: string): string {
+  return ssml
+    .split(/(<!\[CDATA\[[\s\S]*?\]\]>)/)
+    .map((part) =>
+      part.startsWith("<![CDATA[")
+        ? part
+        : part.replace(NUMERIC_REF, (ref, hex?: string, dec?: string) => {
+            const cp = hex !== undefined ? parseInt(hex, 16) : Number(dec);
+            const plain = cp >= 0x20 && cp <= 0x10ffff && !(cp >= 0xd800 && cp <= 0xdfff) && !`<>&'"`.includes(String.fromCodePoint(cp));
+            return plain ? String.fromCodePoint(cp) : ref;
+          }),
+    )
+    .join("");
+}
+
 /**
  * The text contract both doors enforce, before anything that costs a subprocess.
  * Throws `KeshaError`; the CLI runs it before voice routing, `say()` for programmatic callers.
@@ -112,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: "" });
@@ -133,7 +164,7 @@ export async function say(opts: SayOptions): Promise<Uint8Array> {
   for (const warning of warnings) log.warn(warning);
   const { exitCode, signalCode, aborted, stdout, events } = await runEngineProcess(getEngineBinPath(), args, {
     stdio: ["pipe", "pipe", "pipe"],
-    stdin: text,
+    stdin: dropEmoji(text, opts.ssml),
     readStdout: (stream) => new Response(stream).arrayBuffer(),
     signal: opts.signal,
   });

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. */