@drakulavich/kesha-voice-kit 1.30.0 → 2.0.0

package/src/cli/init.ts

@@ -32,16 +32,16 @@ export type TtsLangPrompt = (preselect: string[]) => Promise<string[]>;
 /** Signature of the interactive yes/no prompt (injectable for tests). */
 export type ConfirmPrompt = (message: string, initialValue: boolean) => Promise<boolean>;
 
-/** Ctrl-C at any prompt ends init without downloading, rather than falling through with a default. */
+/** Ctrl-C at any prompt ends init without downloading, exiting 130 like an interrupted install so `kesha init && …` stops (S4-F1). */
 function exitIfCancelled<T>(answer: T | symbol): T {
   if (isCancel(answer)) {
     cancel("Init cancelled.");
-    process.exit(0);
+    process.exit(130);
   }
   return answer as T;
 }
 
-async function promptTtsLangs(preselect: string[]): Promise<string[]> {
+export async function promptTtsLangs(preselect: string[]): Promise<string[]> {
   // A corrupt engine must leave init offering the fallback list rather than aborting the
   // guided setup that would replace it (#770).
   const caps = await getEngineCapabilities().catch(() => null);
@@ -57,7 +57,7 @@ async function promptTtsLangs(preselect: string[]): Promise<string[]> {
 }
 
 /** #677: keep every prompt on clack — its close() unpipes stdin, deadlocking any readline sharing it. */
-async function promptConfirm(message: string, initialValue: boolean): Promise<boolean> {
+export async function promptConfirm(message: string, initialValue: boolean): Promise<boolean> {
   return exitIfCancelled(await confirm({ message, initialValue }));
 }
 

package/src/cli/install.ts

@@ -6,6 +6,7 @@ import { getEngineBinPath, getEngineCapabilities, type EngineCapabilities } from
 import { exitCodeFor, KeshaError } from "../engine/events";
 import { renderInstallPlan } from "../install-plan";
 import { maybeAskForStar } from "../star";
+import { renderInvalidArg } from "./options";
 import { log } from "../log";
 import { packageVersion } from "../package-info";
 import { isSemver } from "../semver.mjs";
@@ -85,10 +86,12 @@ export function resolveEngineVersionFlag(raw: unknown): string | undefined {
   const value = String(raw).trim();
   if (isSemver(value)) return value;
   const hint = /^v\d/.test(value)
-    ? ' Drop the leading "v" — that belongs to the release tag, not the version.'
-    : "";
-  throw new Error(
-    `--engine-version needs an exact SemVer 2.0 version like 1.24.8 or 1.24.8-alpha.1, got "${value}".${hint}`,
+    ? 'drop the leading "v" — that belongs to the release tag, not the version.'
+    : undefined;
+  throw new KeshaError(
+    "E_INVALID_ARG",
+    `--engine-version needs an exact SemVer 2.0 version like 1.24.8 or 1.24.8-alpha.1, got "${value}".`,
+    hint === undefined ? {} : { hint },
   );
 }
 
@@ -321,8 +324,8 @@ export const installCommand = defineCommand({
     try {
       ttsLangs = resolveTtsLangs({ tts: args.tts === true, positionals }, supported);
     } catch (err) {
-      log.error(errorMessage(err));
-      process.exit(1);
+      log.error(renderInvalidArg(errorMessage(err)));
+      process.exit(2);
     }
     await performInstall({
       noCache: resolveNoCacheFlag(args, rawArgs),

package/src/cli/main.ts

@@ -1,8 +1,9 @@
 import { defineCommand } from "citty";
 import { errorMessage } from "../error-utils";
-import { existsSync, statSync } from "fs";
-import { detectAll } from "tinyld";
-import { transcribeWithSegments, validateTranscribeRequest } from "../transcribe";
+import { existsSync } from "fs";
+import { isDirectoryPath, transcribeWithSegments, validateTranscribeRequest } from "../transcribe";
+
+export { isDirectoryPath };
 import { detectAudioLanguageEngine, detectTextLanguageEngine } from "../engine";
 import type { LangDetectResult } from "../engine";
 import { log } from "../log";
@@ -11,19 +12,21 @@ import {
   formatJsonOutput,
   formatTextOutput,
   formatTranscriptOutput,
-  formatVerboseOutput,
+  formatVerboseDiagnostics,
 } from "../format";
 import { packageVersion } from "../package-info";
 import { formatToonOutput } from "../toon";
 import { artifactFromFile, type StatsRecorder } from "../stats";
 import { createPercentProgress } from "../progress";
-import { getPendingSignalExitCode, waitForPendingSignalCleanup } from "../process-tree";
+import { getPendingSignalExitCode, pendingInterruption, waitForPendingSignalCleanup } from "../process-tree";
 import type { TranscriptionSegment } from "../types";
 import { diagnosticSizeBucket } from "../diagnostic-events";
 import { runCommandSession, type CommandSession } from "./command-session";
 import { USAGE_MESSAGE } from "./dispatch";
 import type { CliContext } from "./context";
-import { KeshaError } from "../engine/events";
+import { exitCodeFor, KeshaError } from "../engine/events";
+import { detectTextLanguageFallback, routeLanguage } from "../language-routing";
+import { renderInvalidArg } from "./options";
 
 interface MainCommandArgs {
   _: string[];
@@ -43,32 +46,12 @@ interface MainCommandArgs {
   "no-color": boolean;
 }
 
-/**
- * The CLI-side `tinyld` fallback, tagged `source: "tinyld"` so a consumer can
- * tell it apart from an Engine detection instead of reading the placeholder
- * `confidence: 0` it used to carry as a genuine zero (#941). The score is
- * tinyld's own and is not on the Engine's scale.
- */
-export function detectTextLanguageFallback(text: string): TextLangDetectResult | undefined {
-  if (!text) return undefined;
-  const [best] = detectAll(text);
-  if (!best) return undefined;
-  return { code: best.lang, confidence: best.accuracy, source: "tinyld" };
-}
+export { detectTextLanguageFallback };
 
 export function detectLanguage(text: string): string {
   return detectTextLanguageFallback(text)?.code ?? "";
 }
 
-/** True when `path` exists and is a directory. Used to reject directory positionals before any progress/engine spawn. */
-export function isDirectoryPath(path: string): boolean {
-  try {
-    return statSync(path).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Pulled out of the citty `run` handler so the contract is unit-testable.
  * Mutex check happens AFTER format validation so unknown `--format` surfaces
@@ -121,8 +104,14 @@ export function resolveOutputFormat(input: {
   return { ok: true, format: input.json ? "json" : input.toon ? "toon" : (input.format ?? "text") };
 }
 
+/** Case-folded primary subtag: `en-US`, `EN` and `en_us` all reduce to `en`; a three-letter `eng` stays `eng`. */
+export function primaryLanguageSubtag(code: string): string {
+  return code.trim().toLowerCase().split(/[-_]/, 1)[0] ?? "";
+}
+
 export function checkLanguageMismatch(expected: string | undefined, detected: string): string | null {
-  if (!expected || !detected || expected === detected) return null;
+  if (!expected || !detected) return null;
+  if (primaryLanguageSubtag(expected) === primaryLanguageSubtag(detected)) return null;
   return `warning: expected language "${expected}" but detected "${detected}"`;
 }
 
@@ -214,13 +203,21 @@ export function validateTranscribeArgs(
   return { ok: true, vadMode, outputFormat: fmt.format };
 }
 
+type FileProgress = ReturnType<typeof createPercentProgress> | null;
+
+/** A warning is not progress: it must reach stderr under --quiet, where no bar exists to interrupt. */
+function warnAboveProgress(progress: FileProgress, message: string): void {
+  if (progress) progress.interrupt(() => log.warn(message));
+  else log.warn(message);
+}
+
 async function detectLanguages(
   file: string,
   text: string,
   options: {
     wantsLangId: boolean;
     expectedLang?: string;
-    progress: ReturnType<typeof createPercentProgress> | null;
+    progress: FileProgress;
     stats: StatsRecorder;
     transcriptDurationSeconds: number | null;
   },
@@ -250,7 +247,7 @@ async function detectLanguages(
   if (audioLanguage && expectedLang && audioLanguage.confidence > 0.8) {
     const mismatch = checkLanguageMismatch(expectedLang, audioLanguage.code);
     if (mismatch) {
-      progress?.interrupt(() => log.warn(`${file}: ${mismatch} (from audio)`));
+      warnAboveProgress(progress, `${file}: ${mismatch} (from audio)`);
     }
   }
 
@@ -264,11 +261,13 @@ async function detectLanguages(
     }
   }
 
-  const lang = textLanguage?.code || tinyldResult?.code || "";
+  const route = routeLanguage({ audioLanguage, textLanguage: textLanguage ?? tinyldResult });
+  const { lang } = route;
 
-  const mismatchWarning = checkLanguageMismatch(expectedLang, lang);
+  // A lang taken from audio was already judged by the audio check above; warning again would double it.
+  const mismatchWarning = route.source === "audio" ? null : checkLanguageMismatch(expectedLang, lang);
   if (mismatchWarning) {
-    progress?.interrupt(() => log.warn(`${file}: ${mismatchWarning}`));
+    warnAboveProgress(progress, `${file}: ${mismatchWarning}`);
   }
 
   return {
@@ -290,7 +289,13 @@ type ProcessFileOptions = {
 };
 
 type ProcessFileSuccess = { ok: true; result: TranscribeResult };
-type ProcessFileFailure = { ok: false; error: TranscribeErrorRecord };
+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). */
+function failureExitCode(err: unknown): number {
+  const usage = err instanceof KeshaError && err.origin === "cli" && err.code === "E_INVALID_ARG";
+  return usage ? exitCodeFor(err) : 1;
+}
 
 async function processFile(
   file: string,
@@ -308,7 +313,7 @@ async function processFile(
       error_code: err.code,
     });
     log.error(`${file}: ${errorMessage(err)}`);
-    return { ok: false, error: { file, code: err.code, message: err.message } };
+    return { ok: false, error: { file, code: err.code, message: err.message }, exitCode: failureExitCode(err) };
   }
 
   if (isDirectoryPath(file)) {
@@ -319,7 +324,7 @@ async function processFile(
       error_code: err.code,
     });
     log.error(`${file}: ${errorMessage(err)}`);
-    return { ok: false, error: { file, code: err.code, message: err.message } };
+    return { ok: false, error: { file, code: err.code, message: err.message }, exitCode: failureExitCode(err) };
   }
 
   const inputArtifact = artifactFromFile(file, "input_audio");
@@ -337,6 +342,7 @@ async function processFile(
   // #1002: the bar sitting at 0% through a ~100 s diarization model load reads as a hang,
   // 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();
@@ -403,17 +409,18 @@ async function processFile(
       error_code: code,
     });
     log.error(`${file}: ${stderrText}`);
-    return { ok: false, error: { file, code, message: stderrText } };
+    return { ok: false, error: { file, code, message: stderrText }, exitCode: failureExitCode(err) };
   }
 }
 
-/** `verbose` is only consulted for the plain-text fallback path. */
+/** `--verbose` diagnostics are stderr's whatever the format; stdout carries results only. */
 function writeOutput(
   results: TranscribeResult[],
   errors: TranscribeErrorRecord[],
   format: ValidatedTranscribeArgs["outputFormat"],
   opts: { includeErrors: boolean; verbose: boolean },
 ): void {
+  if (opts.verbose) process.stderr.write(formatVerboseDiagnostics(results));
   const errorEnvelope = (format === "json" || format === "toon") && opts.includeErrors;
   // #773: `[]` reads as "ran fine, nothing found" to a consumer ignoring the exit code.
   if (results.length === 0 && errors.length > 0 && !errorEnvelope) return;
@@ -424,8 +431,6 @@ function writeOutput(
     process.stdout.write(formatToonOutput(results, opts.includeErrors ? errors : undefined));
   } else if (format === "transcript") {
     process.stdout.write(formatTranscriptOutput(results));
-  } else if (opts.verbose) {
-    process.stdout.write(formatVerboseOutput(results));
   } else {
     process.stdout.write(formatTextOutput(results));
   }
@@ -550,20 +555,21 @@ export function createMainCommand(context: CliContext = { quiet: false, disableC
         format: args.format,
       });
       if (!fmt.ok) {
-        log.error(fmt.error);
+        log.error(renderInvalidArg(fmt.error));
         process.exit(2);
       }
 
       const validated = validateTranscribeArgs(args, rawArgs, fmt);
       if (!validated.ok) {
-        log.error(validated.error);
+        log.error(renderInvalidArg(validated.error));
         process.exit(2);
       }
       const { vadMode, outputFormat } = validated;
 
       if (files.length === 0) {
-        log.info(USAGE_MESSAGE);
-        process.exit(1);
+        log.error(renderInvalidArg("no input file"));
+        process.stderr.write(`${USAGE_MESSAGE}\n`);
+        process.exit(2);
       }
 
       const wantsLangId = !!(args.lang || args.verbose || outputFormat !== "text");
@@ -574,7 +580,7 @@ export function createMainCommand(context: CliContext = { quiet: false, disableC
         quiet: context.quiet,
       });
 
-      const { status } = await runCommandSession(
+      const { status, exitCode } = await runCommandSession(
         "transcribe",
         {
           itemCount: files.length,
@@ -589,8 +595,15 @@ export function createMainCommand(context: CliContext = { quiet: false, disableC
         async (session) => {
           const results: TranscribeResult[] = [];
           const errors: TranscribeErrorRecord[] = [];
+          let exitCode = 0;
 
           for (const file of files) {
+            const interrupted = pendingInterruption();
+            if (interrupted) {
+              log.error(`${file}: ${errorMessage(interrupted)}`);
+              errors.push({ file, code: interrupted.code, message: interrupted.message });
+              continue;
+            }
             const outcome = await processFile(
               file,
               {
@@ -608,6 +621,7 @@ export function createMainCommand(context: CliContext = { quiet: false, disableC
               results.push(outcome.result);
             } else {
               errors.push(outcome.error);
+              exitCode = Math.max(exitCode, outcome.exitCode);
             }
           }
 
@@ -619,6 +633,7 @@ export function createMainCommand(context: CliContext = { quiet: false, disableC
           return {
             status: errors.length > 0 ? "failed" : "success",
             itemCount: files.length,
+            exitCode: errors.length > 0 ? exitCode : undefined,
             finishFields: {
               itemCount: files.length,
               resultCount: results.length,
@@ -634,7 +649,7 @@ export function createMainCommand(context: CliContext = { quiet: false, disableC
           await waitForPendingSignalCleanup();
           process.exit(signalExitCode);
         }
-        process.exit(1);
+        process.exit(exitCode ?? 1);
       }
     },
   });

package/src/cli/mcp.ts

@@ -13,5 +13,7 @@ export const mcpCommand = defineCommand({
     const server = createKeshaMcpServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    // The SDK transport never watches for EOF, so a client that died mid-call left the engine running (exploratory S7-2).
+    process.stdin.once("end", () => void server.close());
   },
 });

package/src/cli/options.ts

@@ -0,0 +1,79 @@
+import type { ArgsDef } from "citty";
+import { renderError } from "../engine/events";
+import { log } from "../log";
+import { suggestCommand } from "../suggest-command";
+
+export interface UnknownOption {
+  name: string;
+  suggestion: string | null;
+}
+
+const RUNNER_LONG = ["help", "version"];
+const RUNNER_SHORT = ["h", "v"];
+
+function camelCase(name: string): string {
+  return name.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+/** The first flag `argsDef` does not declare, or null; citty parses non-strict, so the flag would otherwise vanish and its value become a positional (S9-F3). */
+export function findUnknownOption(rawArgs: string[], argsDef: ArgsDef): UnknownOption | null {
+  const long = new Set(RUNNER_LONG);
+  const short = new Set(RUNNER_SHORT);
+  const valued = new Set<string>();
+  const suggestable: string[] = [];
+  for (const [name, def] of Object.entries(argsDef)) {
+    if (def.type === "positional") continue;
+    const alias = "alias" in def ? def.alias : undefined;
+    const aliases = alias === undefined ? [] : Array.isArray(alias) ? alias : [alias];
+    for (const spelling of [name, ...aliases]) {
+      if (spelling.length === 1) {
+        short.add(spelling);
+      } else {
+        long.add(spelling);
+        long.add(camelCase(spelling));
+        suggestable.push(spelling);
+      }
+      if (def.type === "boolean") long.add(`no-${spelling}`);
+      else valued.add(spelling);
+    }
+  }
+  const suggest = (name: string): string | null => {
+    const match = suggestCommand(name, suggestable);
+    return match === null ? null : `--${match}`;
+  };
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i]!;
+    if (arg === "--") break;
+    if (!arg.startsWith("-") || arg === "-" || /^-\d/.test(arg)) continue;
+    if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      const name = eq === -1 ? arg.slice(2) : arg.slice(2, eq);
+      if (!long.has(name)) return { name: `--${name}`, suggestion: suggest(name) };
+      if (eq === -1 && valued.has(name)) i++;
+      continue;
+    }
+    for (const letter of arg.slice(1)) {
+      if (!short.has(letter)) return { name: `-${letter}`, suggestion: null };
+    }
+    if (valued.has(arg[arg.length - 1]!)) i++;
+  }
+  return null;
+}
+
+/** The coded line for a usage error the CLI refuses before doing anything (S9-F2). */
+export function renderInvalidArg(message: string): string {
+  return renderError({ code: "E_INVALID_ARG", message });
+}
+
+export function renderUnknownOption(option: UnknownOption): string {
+  const tail = option.suggestion === null ? "" : ` (did you mean ${option.suggestion}?)`;
+  return renderInvalidArg(`unknown option ${option.name}${tail}`);
+}
+
+/** Exits 2 with one coded stderr line when `rawArgs` carries a flag the command does not declare. */
+export function rejectUnknownOptions(rawArgs: string[], argsDef: ArgsDef): void {
+  const unknown = findUnknownOption(rawArgs, argsDef);
+  if (unknown === null) return;
+  log.error(renderUnknownOption(unknown));
+  process.exit(2);
+}

package/src/cli/record.ts

@@ -1,6 +1,7 @@
 import { defineCommand } from "citty";
 import { errorMessage } from "../error-utils";
 import { exitCodeFor, KeshaError } from "../engine/events";
+import { renderInvalidArg } from "./options";
 import {
   isEngineInstalled,
   recordEngine,
@@ -197,7 +198,7 @@ export const recordCommand = defineCommand({
     if (args.debug) log.debugEnabled = true;
     const resolved = resolveRecordArgs(args as RecordArgs);
     if (!resolved.ok) {
-      log.error(resolved.error);
+      log.error(renderInvalidArg(resolved.error));
       process.exit(2);
     }
     if (!isEngineInstalled()) {

package/src/cli/say.ts

@@ -1,11 +1,15 @@
 import { defineCommand } from "citty";
+import { statSync } from "fs";
 import { errorMessage } from "../error-utils";
 import { exitCodeFor, KeshaError } from "../engine/events";
+import { renderInvalidArg } from "./options";
 import { log } from "../log";
 import {
+  MAX_TEXT_CHARS,
   listVoiceIds,
   say,
   SUPPORTED_SAMPLE_RATES,
+  validateSayText,
   type SayFormat,
   type SayOptions,
 } from "../synth";
@@ -14,13 +18,25 @@ import { resolveSayVoice } from "../voice-routing";
 import { diagnosticCharBucket, diagnosticSizeBucket } from "../diagnostic-events";
 import { runCommandSession, type CommandOutcome, type CommandSession } from "./command-session";
 
+/** Four bytes per allowed character: a pipe that streams past it is refused without waiting for EOF. */
+const MAX_STDIN_BYTES = MAX_TEXT_CHARS * 4 + 4;
+
+/** A positional the user gave is the text, empty or not; only an absent one falls through to stdin (#T1-2). */
 async function resolveText(inline: string | undefined): Promise<string> {
-  if (inline !== undefined && inline.length > 0) return inline;
+  if (inline !== undefined) return inline;
   const chunks: Uint8Array[] = [];
+  let total = 0;
   for await (const chunk of Bun.stdin.stream()) {
     chunks.push(chunk);
+    total += chunk.byteLength;
+    if (total > MAX_STDIN_BYTES) break;
+  }
+  if (total > MAX_STDIN_BYTES) {
+    throw new KeshaError(
+      "E_TEXT_TOO_LONG",
+      `text exceeds ${MAX_TEXT_CHARS} chars (stdin passed ${MAX_STDIN_BYTES} bytes)`,
+    );
   }
-  const total = chunks.reduce((n, c) => n + c.byteLength, 0);
   const merged = new Uint8Array(total);
   let offset = 0;
   for (const c of chunks) {
@@ -34,7 +50,7 @@ export function shouldRejectMissingSayText(
   inlineText: string | undefined,
   stdinIsTty: boolean | undefined,
 ): boolean {
-  return (inlineText === undefined || inlineText.length === 0) && stdinIsTty === true;
+  return inlineText === undefined && stdinIsTty === true;
 }
 
 type Parsed<T> = { ok: true; value: T | undefined } | { ok: false; error: string };
@@ -58,12 +74,19 @@ function parseRateFlag(value: unknown): Parsed<number> {
   return rate;
 }
 
+/** The Opus encoder's own range, mirrored here so a caller error never costs a synthesis (#T1-5). */
+const MIN_OPUS_BITRATE = 6000;
+const MAX_OPUS_BITRATE = 510000;
+
 function parseBitrateFlag(value: unknown): Parsed<number> {
   const bitrate = parseFiniteNumberFlag("--bitrate", value);
   if (!bitrate.ok || bitrate.value === undefined) return bitrate;
   if (!Number.isInteger(bitrate.value) || bitrate.value <= 0) {
     return { ok: false, error: "--bitrate must be a positive integer." };
   }
+  if (bitrate.value < MIN_OPUS_BITRATE || bitrate.value > MAX_OPUS_BITRATE) {
+    return { ok: false, error: `--bitrate must be between ${MIN_OPUS_BITRATE} and ${MAX_OPUS_BITRATE} bps.` };
+  }
   return bitrate;
 }
 
@@ -106,6 +129,8 @@ function checkOpusOnlyFlags(
 }
 
 export type SayFlagArgs = {
+  voice?: unknown;
+  lang?: unknown;
   format?: unknown;
   rate?: unknown;
   bitrate?: unknown;
@@ -116,6 +141,9 @@ export type SayFlagArgs = {
 export type ResolvedSayFlags =
   | {
       ok: true;
+      voice: string | undefined;
+      lang: string | undefined;
+      out: string | undefined;
       format: SayFormat | undefined;
       rate: number | undefined;
       bitrate: number | undefined;
@@ -123,8 +151,22 @@ export type ResolvedSayFlags =
     }
   | { ok: false; error: string };
 
+const STRING_FLAGS = ["voice", "lang", "out", "format", "rate", "bitrate", "sample-rate"] as const;
+
+/** citty returns a trailing valueless string flag as `true` and `--out=` as `""`; both used to be discarded silently (#T1-3). */
+function missingFlagValue(args: SayFlagArgs): string | null {
+  for (const name of STRING_FLAGS) {
+    const value = (args as Record<string, unknown>)[name];
+    if (value === true || value === "") return `--${name} needs a value`;
+  }
+  return null;
+}
+
 /** Validates the encoder flags before the engine is spawned: faster failure in scripts (the engine repeats them authoritatively). */
 export function resolveSayFlags(args: SayFlagArgs): ResolvedSayFlags {
+  const missing = missingFlagValue(args);
+  if (missing) return { ok: false, error: missing };
+
   const format = parseFormatFlag(args.format);
   if (!format.ok) return format;
   const rate = parseRateFlag(args.rate);
@@ -140,6 +182,9 @@ export function resolveSayFlags(args: SayFlagArgs): ResolvedSayFlags {
 
   return {
     ok: true,
+    voice: typeof args.voice === "string" ? args.voice : undefined,
+    lang: typeof args.lang === "string" ? args.lang : undefined,
+    out,
     format: format.value,
     rate: rate.value,
     bitrate: bitrate.value,
@@ -147,6 +192,24 @@ export function resolveSayFlags(args: SayFlagArgs): ResolvedSayFlags {
   };
 }
 
+const STDIO_ALIASES = ["/dev/stdout", "/dev/stderr", "/dev/stdin"];
+
+/** `/dev/fd/N` stats as whatever the descriptor points at, so the name decides where stat cannot. */
+function isDeviceDestination(out: string): boolean {
+  if (STDIO_ALIASES.includes(out) || /^\/dev\/fd\/\d+$/.test(out)) return true;
+  try {
+    return statSync(out).isCharacterDevice();
+  } catch {
+    return false;
+  }
+}
+
+/** The engine writes `--out` from its own process, whose stdout is the CLI's pipe, so a device destination swallows the audio and still reports success (#T1-15). */
+export function deviceOutRefusal(out: string | undefined): string | null {
+  if (out === undefined || !isDeviceDestination(out)) return null;
+  return `--out ${out} is a character device, where the audio would be discarded; omit --out to write it to stdout`;
+}
+
 type SayOpts = {
   text: string;
   voice: string | undefined;
@@ -177,6 +240,11 @@ function recordOutputArtifact(
   return { outputFormat: opts.format ?? "wav", outputSizeBytes: audio.byteLength };
 }
 
+/** citty's parser reads `--no-expand-abbrev` as the negation of a boolean `expand-abbrev`, so the declared key is never set (same trap `--no-vad` works around in main.ts). */
+export function noExpandAbbrevRequested(args: Record<string, unknown>, rawArgs: string[]): boolean {
+  return rawArgs.includes("--no-expand-abbrev") || args["no-expand-abbrev"] === true;
+}
+
 async function synthesizeAndEmit(
   opts: SayOpts,
   verbose: boolean,
@@ -280,7 +348,7 @@ export const sayCommand = defineCommand({
       default: false,
     },
   },
-  async run({ args }) {
+  async run({ args, rawArgs }) {
     if (args.debug) log.debugEnabled = true;
     if (args["list-voices"]) {
       let ids: string[];
@@ -296,32 +364,45 @@ export const sayCommand = defineCommand({
 
     const flags = resolveSayFlags(args);
     if (!flags.ok) {
-      log.error(flags.error);
+      log.error(renderInvalidArg(flags.error));
+      process.exit(2);
+    }
+
+    const deviceOut = deviceOutRefusal(flags.out);
+    if (deviceOut) {
+      log.error(renderInvalidArg(deviceOut));
       process.exit(2);
     }
 
     const inlineText = typeof args.text === "string" ? args.text : undefined;
     const stdinIsTty = (process.stdin as { isTTY?: boolean }).isTTY;
     if (shouldRejectMissingSayText(inlineText, stdinIsTty)) {
-      log.error("kesha say requires text or piped stdin. Usage: kesha say <text>");
+      log.error(renderInvalidArg("kesha say requires text or piped stdin. Usage: kesha say <text>"));
       process.exit(2);
     }
-    const text = await resolveText(inlineText);
-    const explicitVoice = typeof args.voice === "string" ? args.voice : undefined;
-    const langHint = typeof args.lang === "string" ? args.lang : undefined;
+    let text: string;
+    try {
+      text = await resolveText(inlineText);
+      validateSayText(text);
+    } catch (err) {
+      log.error(errorMessage(err));
+      process.exit(exitCodeFor(err));
+    }
+    const explicitVoice = flags.voice;
+    const langHint = flags.lang;
     const voice = await resolveSayVoice(explicitVoice, langHint, text);
 
     const opts: SayOpts = {
       text,
       voice,
       lang: langHint,
-      out: typeof args.out === "string" ? args.out : undefined,
+      out: flags.out,
       rate: flags.rate,
       ssml: Boolean(args.ssml),
       format: flags.format,
       bitrate: flags.bitrate,
       sampleRate: flags.sampleRate,
-      noExpandAbbrev: Boolean(args["no-expand-abbrev"]),
+      noExpandAbbrev: noExpandAbbrevRequested(args, rawArgs),
     };
 
     const outcome = await runCommandSession(