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

package/src/engine/events.ts

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

package/src/engine-install.ts

@@ -19,6 +19,7 @@ import { runEngineProcess } from "./engine/spawn";
 import { acquireInstallLock } from "./install-lock";
 import { log } from "./log";
 import { engineVersion, injectedEnginePins } from "./package-info";
+import { PATH_ERRNOS } from "./path-errnos";
 import { keshaCacheDir } from "./paths";
 import { createLiveStatus, streamResponseToFile } from "./progress";
 import { interruptedRun } from "./process-tree";
@@ -37,6 +38,8 @@ export {
 } from "./engine-version-marker";
 
 const GITHUB_REPO = "drakulavich/kesha-voice-kit";
+const NETWORK_HINT = "check your network connection and try again.";
+const MISMATCH_HINT = `re-run \`kesha install\`; if the mismatch persists, report it at https://github.com/${GITHUB_REPO}/issues.`;
 
 interface ExpectedSha256 {
   sha256: string;
@@ -51,30 +54,46 @@ export interface AssetPins {
 }
 
 /** Without `--engine-version` nothing but the maintainer can make an unverifiable pinned release verifiable. */
-function unverifiableFix(version: string): string {
+function unverifiableFix(version: string, pins: AssetPins | undefined): string {
+  if (!pins) {
+    return version === engineVersion
+      ? `this source checkout installs its own version v${engineVersion}, which may not be released yet: run ` +
+          `\`kesha install --engine-version <version>\` with a published release that ships SHA256SUMS (https://github.com/${GITHUB_REPO}/releases).`
+      : `pass --engine-version a published release that ships SHA256SUMS (https://github.com/${GITHUB_REPO}/releases).`;
+  }
   return version === engineVersion
     ? `report it at https://github.com/${GITHUB_REPO}/issues: the pinned engine release v${version} must publish its checksums.`
     : `pick a release that ships SHA256SUMS (https://github.com/${GITHUB_REPO}/releases), or run ` +
         `\`kesha install\` without --engine-version to install the pinned v${engineVersion}.`;
 }
 
-async function fetchSha256Sums(version: string): Promise<Map<string, string>> {
+async function fetchSha256Sums(version: string, pins: AssetPins | undefined): Promise<Map<string, string>> {
   const url = `https://github.com/${GITHUB_REPO}/releases/download/v${version}/SHA256SUMS`;
   let res: Response;
   try {
     res = await fetch(url, { redirect: "follow" });
   } catch (e) {
-    throw new Error(
-      `Failed to fetch SHA256SUMS for release v${version}: ${errorMessage(e)}\n  Fix: Check your network connection and try again`,
-    );
+    throw new KeshaError("E_MODEL_DOWNLOAD", `Failed to fetch SHA256SUMS for release v${version}: ${errorMessage(e)}`, {
+      hint: NETWORK_HINT,
+    });
   }
   if (!res.ok) {
-    throw new Error(
+    throw new KeshaError(
+      "E_MODEL_DOWNLOAD",
       `Cannot verify engine v${version}: release v${version} publishes no SHA256SUMS (HTTP ${res.status}), ` +
-        `so its binaries cannot be checked before they are installed.\n  Fix: ${unverifiableFix(version)}`,
+        "so its binaries cannot be checked before they are installed.",
+      { hint: unverifiableFix(version, pins) },
     );
   }
-  return parseSha256Sums(await res.text());
+  let body: string;
+  try {
+    body = await res.text();
+  } catch (e) {
+    throw new KeshaError("E_MODEL_DOWNLOAD", `Failed to read SHA256SUMS for release v${version}: ${errorMessage(e)}`, {
+      hint: NETWORK_HINT,
+    });
+  }
+  return parseSha256Sums(body);
 }
 
 /**
@@ -92,12 +111,14 @@ export function releaseChecksums(
       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.`);
       return { sha256: pinned, source: "its pinned SHA-256" };
     }
-    sums ??= fetchSha256Sums(version);
+    sums ??= fetchSha256Sums(version, pins);
     const sha256 = (await sums).get(assetName);
     if (!sha256) {
-      throw new Error(
+      throw new KeshaError(
+        "E_MODEL_DOWNLOAD",
         `Cannot verify ${assetName}: the SHA256SUMS of release v${version} does not list it, ` +
-          `so it cannot be checked before it is installed.\n  Fix: ${unverifiableFix(version)}`,
+          "so it cannot be checked before it is installed.",
+        { hint: unverifiableFix(version, pins) },
       );
     }
     return { sha256, source: `the SHA-256 in the SHA256SUMS of release v${version}` };
@@ -129,25 +150,44 @@ async function rejectMismatchedDownload(
   return (
     `${what} from release v${version} does not match ${expected.source}: ` +
     `expected sha256 ${expected.sha256}, got ${actual}. The download was corrupted or altered, ` +
-    "so it was deleted instead of installed.\n" +
-    `  Fix: re-run \`kesha install\`; if the mismatch persists, report it at https://github.com/${GITHUB_REPO}/issues.`
+    "so it was deleted instead of installed."
   );
 }
 
 /**
  * Whether a cached asset of the pinned release still hashes to its pin; one that does not is
- * deleted so the verified download replaces it. `--engine-version` caches are not re-hashed.
+ * deleted so the verified download replaces it, or refused when its directory is read-only.
+ * `--engine-version` caches are not re-hashed.
  */
-async function cachedAssetMatchesPin(path: string, assetName: string, what: string, version: string): Promise<boolean> {
+async function cachedAssetMatchesPin(
+  path: string,
+  assetName: string,
+  what: string,
+  version: string,
+  canRepair: boolean,
+): Promise<boolean> {
   // KESHA_ENGINE_BIN names the user's own build, which no release pin describes.
   if (version !== engineChecksums.pins?.version || process.env.KESHA_ENGINE_BIN || !existsSync(path)) return true;
   const expected = await engineChecksums.forRelease(version)(assetName);
-  const actual = await sha256OfFile(path);
+  let actual: string;
+  try {
+    actual = await sha256OfFile(path);
+  } catch (e) {
+    throw canRepair ? e : unreadableInReadOnlyDir(path, e);
+  }
   if (actual === expected.sha256) return true;
-  log.warn(
-    `Installed ${what} ${assetName} does not match ${expected.source} (expected sha256 ${expected.sha256}, ` +
-      `got ${actual}); deleting it and downloading a verified copy.`,
-  );
+  const mismatch =
+    `Installed ${what} ${assetName} at ${path} does not match ${expected.source} ` +
+    `(expected sha256 ${expected.sha256}, got ${actual})`;
+  if (!canRepair) {
+    const dir = dirname(path);
+    throw new KeshaError("E_CACHE_CORRUPT", `${mismatch}; ${dir} is read-only, so it cannot be replaced.`, {
+      hint:
+        `make ${dir} writable and re-run \`kesha install\` to replace it with a verified copy, ` +
+        "or point KESHA_CACHE_DIR at a writable directory and re-run `kesha install`.",
+    });
+  }
+  log.warn(`${mismatch}; deleting it and downloading a verified copy.`);
   rmSync(path, { force: true });
   return false;
 }
@@ -209,7 +249,7 @@ export function cleanupRetiredSidecars(engineDir: string): string[] {
   }
 
   if (removed.length > 0) {
-    log.success(`Removed retired sidecars: ${removed.join(", ")}.`);
+    log.progress(`Removed retired sidecars: ${removed.join(", ")}.`);
   }
 
   return removed;
@@ -320,12 +360,12 @@ async function downloadSidecar(
     await streamResponseToFile(res, sidecarPath, spec.displayName);
     const refusal = await rejectMismatchedDownload(sidecarPath, `${spec.displayName} ${spec.assetName}`, version, expected);
     if (refusal) {
-      log.warn(`${refusal}\n  ${spec.displayName} not installed; ${spec.unavailableHint}.`);
+      log.warn(`${refusal}\n  Fix: ${MISMATCH_HINT}\n  ${spec.displayName} not installed; ${spec.unavailableHint}.`);
       return;
     }
     chmodSync(sidecarPath, 0o755);
     darwinTrustBinary(sidecarPath, spec.displayName);
-    log.success(`${spec.displayName} installed (${spec.availableHint}).`);
+    log.progress(`${spec.displayName} installed (${spec.availableHint}).`);
   } catch (e) {
     log.warn(
       `${spec.displayName} install failed (${errorMessage(e)}); ${spec.unavailableHint}.`,
@@ -376,7 +416,7 @@ export async function warmDarwinKokoro(binPath: string, timeoutMs = 180_000): Pr
       return;
     }
 
-    log.success(
+    log.progress(
       `FluidAudio Kokoro warmed (${Math.round(performance.now() - startedAt)}ms).`,
     );
   } catch (e) {
@@ -446,19 +486,18 @@ async function refreshCachedEngine(
 ): Promise<void> {
   const engineDir = dirname(binPath);
   if (noCache && !canWriteEngineDir) {
-    log.info(
+    log.warn(
       `Engine binary at v${version} is on a read-only filesystem; --no-cache skipped for engine (still forwarded to model installs).`,
     );
   } else {
-    log.success(`Engine binary already installed (v${version}).`);
+    log.progress(`Engine binary already installed (v${version}).`);
   }
   // Re-trust on cache hit: a user who upgraded to Sequoia after install would still have
   // com.apple.provenance attached; idempotent (~10ms no-op if already correct).
   if (canWriteEngineDir && existsSync(binPath)) {
     darwinTrustBinary(binPath, "kesha-engine binary");
   }
-  // Top up missing or broken sidecars (pre-#141/#199 cached binaries never had them);
-  // skip on read-only fs (Nix-store) to avoid confusing "install failed" warnings.
+  // Top up missing or broken sidecars (pre-#141/#199 cached binaries never had them).
   if (canWriteEngineDir) {
     const checksums = engineChecksums.forRelease(version);
     await Promise.all(
@@ -468,7 +507,7 @@ async function refreshCachedEngine(
         // sidecar is SIGKILLed on spawn, and re-downloading it would not lift the block.
         let pinned = false;
         try {
-          pinned = existsSync(path) && (await cachedAssetMatchesPin(path, spec.assetName, spec.displayName, version));
+          pinned = existsSync(path) && (await cachedAssetMatchesPin(path, spec.assetName, spec.displayName, version, true));
         } catch (e) {
           log.warn(`Could not read ${spec.displayName} at ${path} (${errorMessage(e)}); removing it and downloading it again.`);
           rmSync(path, { force: true });
@@ -479,6 +518,10 @@ async function refreshCachedEngine(
         }
       }),
     );
+  } else {
+    for (const spec of SIDECARS) {
+      await cachedAssetMatchesPin(join(engineDir, spec.fileBasename), spec.assetName, spec.displayName, version, false);
+    }
   }
 }
 
@@ -602,32 +645,35 @@ async function fetchEngineBinary(
     res = await fetch(url, { redirect: "follow" });
   } catch (e) {
     muteSidecarRejections();
-    throw new Error(
-      `Failed to fetch engine binary: ${errorMessage(e)}\n  Fix: Check your network connection and try again`,
-    );
+    throw new KeshaError("E_MODEL_DOWNLOAD", `Failed to fetch engine binary: ${errorMessage(e)}`, { hint: NETWORK_HINT });
   }
 
   if (!res.ok) {
     muteSidecarRejections();
     // Names the tag: nothing falls back to the pin, so the caller must see which release 404ed.
-    throw new Error(
-      `Failed to download engine binary from release v${version} (HTTP ${res.status})\n  Fix: Check https://github.com/${GITHUB_REPO}/releases for available versions`,
-    );
+    throw new KeshaError("E_MODEL_DOWNLOAD", `Failed to download engine binary from release v${version} (HTTP ${res.status})`, {
+      hint: `check https://github.com/${GITHUB_REPO}/releases for available versions.`,
+    });
   }
 
-  await streamResponseToFile(res, binPath, "kesha-engine binary");
+  try {
+    await streamResponseToFile(res, binPath, "kesha-engine binary");
+  } catch (e) {
+    muteSidecarRejections();
+    throw e instanceof KeshaError ? e : (engineWriteFailure(binPath, e) ?? e);
+  }
   const refusal = await rejectMismatchedDownload(binPath, `kesha-engine binary ${binaryName}`, version, expected);
   if (refusal) {
     muteSidecarRejections();
     rmSync(getVersionMarkerPath(binPath), { force: true });
-    throw new Error(refusal);
+    throw new KeshaError("E_CACHE_CORRUPT", refusal, { hint: MISMATCH_HINT });
   }
   chmodSync(binPath, 0o755);
   darwinTrustBinary(binPath, "kesha-engine binary");
   // Marker last: writing it first sends the retry down the cacheValid branch, which never waits.
   await waitUntilSpawnable(binPath);
   writeInstalledEngineVersion(binPath, version);
-  log.success(`Engine binary downloaded (v${version}).`);
+  log.progress(`Engine binary downloaded (v${version}).`);
   await Promise.all(sidecarPromises);
 }
 
@@ -807,17 +853,28 @@ async function assertRequestedVersionLanded(binPath: string, version: string): P
   );
 }
 
-/** mkdir errnos that mean the configured path is itself wrong; anything else is not a bad argument. */
-const ENGINE_DIR_PATH_ERRNOS: Record<string, string> = {
-  EACCES: "permission denied",
-  EPERM: "permission denied",
-  ENOTDIR: "a component of it is a file, not a directory",
-  // mkdir(recursive) raises this, not ENOTDIR, when the engine directory itself is an existing file.
-  EEXIST: "it already exists as a file, not a directory",
-  EROFS: "the filesystem is read-only",
-  ELOOP: "the path loops through symlinks",
-  ENAMETOOLONG: "the path is too long",
-};
+function engineDirSetting(): { name: string; value: string } | null {
+  if (process.env.KESHA_ENGINE_BIN) return { name: "KESHA_ENGINE_BIN", value: process.env.KESHA_ENGINE_BIN };
+  if (process.env.KESHA_CACHE_DIR) return { name: "KESHA_CACHE_DIR", value: process.env.KESHA_CACHE_DIR };
+  if (process.env.KESHA_HOME) return { name: "KESHA_HOME", value: process.env.KESHA_HOME };
+  return null;
+}
+
+function unreadableInReadOnlyDir(path: string, e: unknown): unknown {
+  const errno = (e as NodeJS.ErrnoException).code ?? "";
+  const why = PATH_ERRNOS[errno];
+  if (!why) return e;
+  const dir = dirname(path);
+  return new KeshaError(
+    "E_INVALID_ARG",
+    `Cannot verify ${path} against its pinned SHA-256: ${why} (${errno}), and ${dir} is read-only, so it cannot be replaced.`,
+    {
+      hint:
+        `make ${path} readable and ${dir} writable, then re-run \`kesha install\`. Or ` +
+        engineDirFix(engineDirSetting()?.name, false, dir),
+    },
+  );
+}
 
 /** `KESHA_ENGINE_BIN` names the binary file, so "point it at a writable directory" breaks the next install. */
 function engineDirFix(setting: string | undefined, notADir: boolean, engineDir: string): string {
@@ -847,15 +904,9 @@ function ensureEngineDirCreatable(binPath: string): void {
   try {
     mkdirSync(engineDir, { recursive: true });
   } catch (e) {
-    const setting = process.env.KESHA_ENGINE_BIN
-      ? { name: "KESHA_ENGINE_BIN", value: process.env.KESHA_ENGINE_BIN }
-      : process.env.KESHA_CACHE_DIR
-        ? { name: "KESHA_CACHE_DIR", value: process.env.KESHA_CACHE_DIR }
-        : process.env.KESHA_HOME
-          ? { name: "KESHA_HOME", value: process.env.KESHA_HOME }
-          : null;
+    const setting = engineDirSetting();
     const errno = (e as NodeJS.ErrnoException).code ?? "";
-    const why = ENGINE_DIR_PATH_ERRNOS[errno];
+    const why = PATH_ERRNOS[errno];
     const what = setting
       ? `${setting.name}="${setting.value}" cannot hold the engine directory ${engineDir}: ${why ?? errorMessage(e)}`
       : `cannot create the engine directory ${engineDir}: ${why ?? errorMessage(e)}`;
@@ -871,6 +922,28 @@ function ensureEngineDirCreatable(binPath: string): void {
   }
 }
 
+function engineWriteFailure(binPath: string, e: unknown): KeshaError | null {
+  const engineDir = dirname(binPath);
+  const errno = (e as NodeJS.ErrnoException).code ?? "";
+  const setting = engineDirSetting();
+  const into = setting ? `${engineDir} (from ${setting.name}="${setting.value}")` : engineDir;
+  const why = PATH_ERRNOS[errno];
+  if (why) {
+    return new KeshaError("E_INVALID_ARG", `Cannot write the engine binary into ${into}: ${why}`, {
+      hint: engineDirFix(setting?.name, errno === "ENOTDIR" || errno === "EEXIST", engineDir),
+    });
+  }
+  if (!errno) return null;
+  if (errno === "ENOSPC") {
+    return new KeshaError("E_INTERNAL", `Cannot write the engine binary into ${into}: no space left on its disk (ENOSPC)`, {
+      hint: `the disk is full: free space on the volume that holds ${engineDir}, then re-run \`kesha install\`.`,
+    });
+  }
+  return new KeshaError("E_INTERNAL", `Cannot write the engine binary into ${into}: ${errorMessage(e)}`, {
+    hint: `resolve that filesystem error on ${engineDir} and re-run \`kesha install\`; if it persists, file a bug with \`kesha support-bundle\`.`,
+  });
+}
+
 export interface EngineInstallRequest extends InstallOptions {
   noCache?: boolean;
   backend?: string;
@@ -913,7 +986,7 @@ async function installLockedEngine(
   const engineDir = dirname(binPath);
 
   if (version !== engineVersion) {
-    log.info(
+    log.warn(
       `Installing engine v${version} instead of the pinned v${engineVersion}; ` +
         "a later `kesha install` without --engine-version restores the pin.",
     );
@@ -923,15 +996,14 @@ async function installLockedEngine(
   const canWriteEngineDir = checkEngineWritable(engineDir);
 
   const markerMatches = existsSync(binPath) && installedVersion === version;
-  // The marker vouches for a file, not for a working binary. Skipped on a read-only engine
-  // dir: nothing there can be repaired, so a failed probe would only turn a usable Nix
+  // The marker vouches for a file, not for a working binary. The probe is skipped on a read-only
+  // engine dir: nothing there can be repaired, so a failed probe would only turn a usable Nix
   // install into a hard error.
   // Hashed before the health probe, so an altered binary is never run.
   const versionMatches =
     markerMatches &&
-    (!canWriteEngineDir ||
-      ((await cachedAssetMatchesPin(binPath, getEngineBinaryName(), "kesha-engine binary", version)) &&
-        (await engineWorks(binPath))));
+    (await cachedAssetMatchesPin(binPath, getEngineBinaryName(), "kesha-engine binary", version, canWriteEngineDir)) &&
+    (!canWriteEngineDir || (await engineWorks(binPath)));
   // On read-only fs, --no-cache can't re-download; treat as cache-valid and forward flag to model install.
   const cacheValid = versionMatches && (!noCache || !canWriteEngineDir);
 

package/src/engine-version-marker.ts

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

package/src/engine.ts

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

package/src/log.ts

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

package/src/mcp/tools.ts

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

package/src/path-errnos.ts

@@ -0,0 +1,11 @@
+/** Errnos that mean the path itself is wrong for writing, so the fix is a different path; anything else is not a bad argument. */
+export const PATH_ERRNOS: Record<string, string> = {
+  EACCES: "permission denied",
+  EPERM: "permission denied",
+  ENOTDIR: "a component of it is a file, not a directory",
+  // mkdir(recursive) raises this, not ENOTDIR, when the directory itself is an existing file.
+  EEXIST: "it already exists as a file, not a directory",
+  EROFS: "the filesystem is read-only",
+  ELOOP: "the path loops through symlinks",
+  ENAMETOOLONG: "the path is too long",
+};

package/src/progress.ts

@@ -1,6 +1,7 @@
 import { copyFileSync, readdirSync, renameSync, rmSync, statSync } from "fs";
 import { basename, dirname, join } from "path";
 import { errorMessage } from "./error-utils";
+import { KeshaError } from "./engine/events";
 import { log } from "./log";
 
 const BAR_WIDTH = 20;
@@ -172,11 +173,15 @@ export async function applyBackpressure(
  */
 const STALE_STAGING_MS = 24 * 60 * 60 * 1000;
 
+export function stagingPrefix(destPath: string): string {
+  return `${destPath}.part.`;
+}
+
 /** A Ctrl-C kills the process before any cleanup runs, so last run's staging file is swept by the next one (#770). */
 function sweepStagingFiles(destPath: string): void {
   if (process.platform === "win32") return;
   const dir = dirname(destPath);
-  const prefix = `${basename(destPath)}.part.`;
+  const prefix = basename(stagingPrefix(destPath));
   const cutoffMs = Date.now() - STALE_STAGING_MS;
 
   let names: string[];
@@ -225,32 +230,44 @@ export async function streamResponseToFile(
   destPath: string,
   label: string,
 ): Promise<number> {
-  if (!res.body) {
-    throw new Error(
-      `Download failed: empty response for ${label}\n  Fix: Try again — the server may be temporarily unavailable`,
-    );
-  }
+  const emptyResponse = () =>
+    new KeshaError("E_MODEL_DOWNLOAD", `Download failed: empty response for ${label}`, {
+      hint: "try again; the server may be temporarily unavailable.",
+    });
+  if (!res.body) throw emptyResponse();
 
   const totalBytes = Number(res.headers.get("content-length") || 0);
   const progress = createProgressBar(label, totalBytes);
 
   sweepStagingFiles(destPath);
-  const stagingPath = `${destPath}.part.${process.pid}.${stagingSeq++}`;
-  const writer = Bun.file(stagingPath).writer();
+  const stagingPath = `${stagingPrefix(destPath)}${process.pid}.${stagingSeq++}`;
+  const reader = res.body.getReader();
   let bytes = 0;
   try {
+    const writer = Bun.file(stagingPath).writer();
     try {
-      for await (const chunk of res.body) {
-        await applyBackpressure(writer, writer.write(chunk));
-        bytes += chunk.length;
-        progress.update(chunk.length);
+      for (;;) {
+        let next: Awaited<ReturnType<typeof reader.read>>;
+        try {
+          next = await reader.read();
+        } catch (err) {
+          throw new KeshaError("E_MODEL_DOWNLOAD", `Download of ${label} broke off after ${bytes} bytes: ${errorMessage(err)}`, {
+            hint: "check your network connection and try again.",
+          });
+        }
+        if (next.done) break;
+        await applyBackpressure(writer, writer.write(next.value));
+        bytes += next.value.length;
+        progress.update(next.value.length);
       }
     } finally {
       // Must await: an open write handle makes the freshly-downloaded engine unspawnable — EBUSY on Windows, ETXTBSY on Linux.
       await writer.end();
     }
+    if (bytes === 0) throw emptyResponse();
     publishStaging(stagingPath, destPath);
   } catch (err) {
+    reader.cancel().catch(() => {});
     rmSync(stagingPath, { force: true });
     throw err;
   }
@@ -272,7 +289,7 @@ export function createProgressBar(label: string, totalBytes: number): {
     return {
       update() {},
       finish() {
-        log.success(`Downloaded ${label} ✓`);
+        log.progress(`Downloaded ${label} ✓`);
       },
     };
   }