@drakulavich/kesha-voice-kit 1.26.0 → 1.27.0-alpha.1

package/README.md

@@ -36,7 +36,8 @@ curl -fsSL https://bun.sh/install | bash        # or: brew install oven-sh/bun/b
 bun add -g @drakulavich/kesha-voice-kit
 kesha --version                                 # confirms `kesha` resolved on PATH
 kesha install --plan                            # preview exact download/disk sizes first — downloads nothing
-kesha install        # ~2.5 GB (engine + speech-to-text models), explicit — never automatic.
+kesha install        # ~2.5 GB on Linux/Windows; ~0.6 GB on Apple Silicon, whose CoreML
+                      # engine uses a different, smaller model set. Explicit — never automatic.
                       # No progress bar during the model step; can take several minutes.
                       # Prefer a guided wizard? `kesha init` walks through the same choices interactively.
 

package/completions/kesha.bash

@@ -21,7 +21,7 @@ _kesha_completion() {
     completions) opts="--help -h" ;;
     doctor) opts="--help -h --json --redact" ;;
     init) opts="--help -h --coreml --onnx --no-cache --plan --yes --tts --vad --diarize" ;;
-    install) opts="--help -h --coreml --onnx --no-cache --plan --tts --vad --diarize" ;;
+    install) opts="--help -h --coreml --onnx --no-cache --plan --tts --vad --diarize --engine-version" ;;
     logs) opts="--help -h --json" ;;
     manpage) opts="--help -h" ;;
     mcp) opts="--help -h" ;;

package/completions/kesha.fish

@@ -54,6 +54,7 @@ complete -c kesha -n '__fish_seen_subcommand_from install' -l plan -d 'Show down
 complete -c kesha -n '__fish_seen_subcommand_from install' -l tts -d 'Also install TTS models (English only; add codes for more, e.g. --tts en ru (preview sizes: kesha install --plan))'
 complete -c kesha -n '__fish_seen_subcommand_from install' -l vad -d 'Also install Silero VAD (~2.3MB) for long-audio preprocessing'
 complete -c kesha -n '__fish_seen_subcommand_from install' -l diarize -d 'Also install the Sortformer streaming-diarization model (~245MB, darwin-arm64 only — #199)'
+complete -c kesha -n '__fish_seen_subcommand_from install' -l engine-version -r -d 'Install this exact engine release instead of the pinned one (expert; the next install returns to the pin)'
 complete -c kesha -n '__fish_seen_subcommand_from logs' -l help -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from logs' -s h -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from logs' -l json -d 'Output status as JSON'

package/completions/kesha.zsh

@@ -75,7 +75,8 @@ _kesha() {
         '--plan[Show download, disk, and warm-up plan without changing local state]' \
         '--tts[Also install TTS models (English only; add codes for more, e.g. --tts en ru (preview sizes: kesha install --plan))]' \
         '--vad[Also install Silero VAD (~2.3MB) for long-audio preprocessing]' \
-        '--diarize[Also install the Sortformer streaming-diarization model (~245MB, darwin-arm64 only — #199)]'
+        '--diarize[Also install the Sortformer streaming-diarization model (~245MB, darwin-arm64 only — #199)]' \
+        '--engine-version=[Install this exact engine release instead of the pinned one (expert; the next install returns to the pin)]:engine version:'
       ;;
     logs)
       _arguments '--help[Show help]' \

package/man/kesha.1

@@ -141,6 +141,9 @@ Also install Silero VAD (~2.3MB) for long\-audio preprocessing
 .TP
 .B \-\-diarize
 Also install the Sortformer streaming\-diarization model (~245MB, darwin\-arm64 only — #199)
+.TP
+.B \-\-engine\-version
+Install this exact engine release instead of the pinned one (expert; the next install returns to the pin)
 .SS logs
 .TP
 .B \-\-json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.26.0",
+  "version": "1.27.0-alpha.1",
   "description": "Give your tools a voice — speech to text and back, 25 languages, up to ~19× faster than Whisper. On your machine.",
   "type": "module",
   "bin": {
@@ -25,7 +25,8 @@
     "SKILL.md",
     "LICENSE",
     "NOTICES.md",
-    "README.md"
+    "README.md",
+    "!src/__tests__"
   ],
   "openclaw": {
     "extensions": [

package/src/cli/init.ts

@@ -3,7 +3,13 @@ import { confirm, multiselect, isCancel, cancel } from "@clack/prompts";
 import { renderInstallPlan } from "../install-plan";
 import { log } from "../log";
 import { getEngineCapabilities } from "../engine";
-import { performInstall, resolveBackendFlag, resolveNoCacheFlag, TTS_LANG_FALLBACK } from "./install";
+import {
+  performInstall,
+  resolveBackendFlag,
+  resolveNoCacheFlag,
+  TTS_LANG_FALLBACK,
+  unavailableBackendError,
+} from "./install";
 import type { SharedInstallArgs } from "./types";
 
 const TTS_LANG_LABELS: Record<string, string> = {
@@ -171,7 +177,14 @@ export async function promptInitSelection(
   };
 }
 
-async function printPlan(selection: InitSelection): Promise<void> {
+/** Mirrors the guard in `performInstall`: a preview must not describe an install this platform rejects (#684). */
+async function printPlan(selection: InitSelection): Promise<boolean> {
+  const backendError = unavailableBackendError(selection.backend);
+  if (backendError) {
+    log.error(backendError);
+    process.exitCode = 2;
+    return false;
+  }
   log.info(
     await renderInstallPlan({
       noCache: selection.noCache,
@@ -181,6 +194,7 @@ async function printPlan(selection: InitSelection): Promise<void> {
       diarize: selection.diarize,
     }),
   );
+  return true;
 }
 
 async function runNonInteractive(selection: InitSelection): Promise<void> {
@@ -190,7 +204,7 @@ async function runNonInteractive(selection: InitSelection): Promise<void> {
     log.warn("--diarize is currently darwin-arm64 only; omitting it from non-interactive examples.");
   }
   log.info(renderInitOverview(canDiarize));
-  await printPlan(printableSelection);
+  if (!(await printPlan(printableSelection))) return;
   log.info("Run one of these commands from an interactive terminal:");
   for (const command of initSuggestionCommands(printableSelection, canDiarize)) {
     log.info(`  ${command.join(" ")}`);
@@ -260,13 +274,7 @@ export const initCommand = defineCommand({
       if (selection.diarize && !installSelection.diarize) {
         log.warn("--diarize is currently darwin-arm64 only; omitting it from the --yes install.");
       }
-      await performInstall(
-        installSelection.noCache,
-        installSelection.backend,
-        installSelection.ttsLangs,
-        installSelection.vad,
-        installSelection.diarize,
-      );
+      await performInstall(installSelection);
       return;
     }
 
@@ -286,7 +294,7 @@ export const initCommand = defineCommand({
       noCache,
     );
     log.info("");
-    await printPlan(prompted);
+    if (!(await printPlan(prompted))) return;
     const confirmed = await promptConfirm(
       `Run \`${initInstallArgs(prompted).join(" ")}\` now?`,
       true,
@@ -295,13 +303,7 @@ export const initCommand = defineCommand({
       log.info(`Skipped install. Run later: ${initInstallArgs(prompted).join(" ")}`);
       return;
     }
-    await performInstall(
-      prompted.noCache,
-      prompted.backend,
-      prompted.ttsLangs,
-      prompted.vad,
-      prompted.diarize,
-    );
+    await performInstall(prompted);
     // #523: end on something runnable, not on the install log.
     log.info("");
     log.success("Kesha is ready. Try:");

package/src/cli/install.ts

@@ -1,18 +1,22 @@
 import { defineCommand } from "citty";
 import { errorMessage } from "../error-utils";
-import { downloadEngine } from "../engine-install";
+import { installEngine } from "../engine-install";
 import { engineTarget } from "../engine-targets";
 import { getEngineBinPath, getEngineCapabilities } from "../engine";
 import { renderInstallPlan } from "../install-plan";
 import { maybeAskForStar } from "../star";
 import { log } from "../log";
 import { packageVersion } from "../package-info";
+import { isSemver } from "../semver.mjs";
 import { createDiagnosticLogSession, type DiagnosticLogSession } from "../diagnostic-log";
 import type { SharedInstallArgs } from "./types";
 
 export interface InstallCommandArgs extends SharedInstallArgs {
   /** Positional args after `install` — candidate TTS language codes. */
   _?: string[];
+  /** `init` deliberately has no such flag: an override is an expert action, not a guided one. */
+  "engine-version"?: string;
+  engineVersion?: string;
 }
 
 /**
@@ -57,6 +61,23 @@ export function resolveTtsLangs(input: TtsArgInput, supported: string[] | undefi
   return langs;
 }
 
+/**
+ * Validates `--engine-version` before any network call. Returns undefined when the flag is
+ * absent, so the Pinned Engine version stays the default; throws on anything the version
+ * drift gate would not accept either — one SemVer 2.0 definition across the repo.
+ */
+export function resolveEngineVersionFlag(raw: unknown): string | undefined {
+  if (raw === undefined || raw === null || raw === false) return 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}`,
+  );
+}
+
 export function resolveNoCacheFlag(
   args: Pick<InstallCommandArgs, "no-cache" | "noCache" | "no_cache">,
   rawArgs: string[] = [],
@@ -120,16 +141,42 @@ function finishInstallDiagnostic(
   }
 }
 
-export async function performInstall(
-  noCache: boolean,
-  backend: string | undefined,
-  ttsLangs: string[],
-  vad = false,
-  diarize = false,
-  plan = false,
-) {
+/** Null when the requested backend is installable here. `KESHA_ENGINE_BIN` opts out — the user supplied their own engine. */
+export function unavailableBackendError(backend: string | undefined): string | null {
+  const platformBackend = defaultBackendForPlatform();
+  if (!backend || process.env.KESHA_ENGINE_BIN || !platformBackend) return null;
+  if (backend === platformBackend) return null;
+  return (
+    `Requested backend "${backend}" is not available on this platform; ` +
+    `the release engine uses "${platformBackend}".`
+  );
+}
+
+export interface PerformInstallOptions {
+  noCache: boolean;
+  backend?: string;
+  ttsLangs: string[];
+  vad?: boolean;
+  diarize?: boolean;
+  plan?: boolean;
+  /** Engine release to install instead of the pin, for this invocation only. */
+  engineVersion?: string;
+}
+
+export async function performInstall(options: PerformInstallOptions) {
+  const { noCache, backend, ttsLangs, vad = false, diarize = false, plan = false, engineVersion } =
+    options;
+  // A plan for an unavailable backend previews what its own printed command rejects (#684).
+  const backendError = unavailableBackendError(backend);
   if (plan) {
-    log.info(await renderInstallPlan({ noCache, backend, ttsLangs, vad, diarize }));
+    if (backendError) {
+      log.error(backendError);
+      process.exitCode = 2;
+      return;
+    }
+    log.info(
+      await renderInstallPlan({ noCache, backend, ttsLangs, vad, diarize, engineVersion }),
+    );
     return;
   }
 
@@ -145,6 +192,7 @@ export async function performInstall(
       tts: ttsLangs.length > 0,
       vad,
       diarize,
+      engineVersionOverride: engineVersion !== undefined,
     });
 
     if (diarize && !(process.platform === "darwin" && process.arch === "arm64")) {
@@ -154,15 +202,11 @@ export async function performInstall(
         "(see https://github.com/drakulavich/kesha-voice-kit/issues/199).",
       );
     }
-    const platformBackend = defaultBackendForPlatform();
-    if (backend && !process.env.KESHA_ENGINE_BIN && platformBackend && backend !== platformBackend) {
+    if (backendError) {
       errorKind = "validation_failed";
-      throw new Error(
-        `Requested backend "${backend}" is not available on this platform; ` +
-          `the release engine uses "${platformBackend}".`,
-      );
+      throw new Error(backendError);
     }
-    await downloadEngine(noCache, backend, { ttsLangs, vad, diarize });
+    await installEngine({ noCache, backend, ttsLangs, vad, diarize, version: engineVersion });
     await maybeAskForStar(getEngineBinPath(), packageVersion, log);
     finishInstallDiagnostic(diagnosticLog, startedAt, "success");
   } catch (err: unknown) {
@@ -214,8 +258,20 @@ export const installCommand = defineCommand({
       description: "Also install the Sortformer streaming-diarization model (~245MB, darwin-arm64 only — #199)",
       default: false,
     },
+    "engine-version": {
+      type: "string",
+      description:
+        "Install this exact engine release instead of the pinned one (expert; the next install returns to the pin)",
+    },
   },
   async run({ args, rawArgs }: { args: InstallCommandArgs; rawArgs: string[] }) {
+    let engineVersion: string | undefined;
+    try {
+      engineVersion = resolveEngineVersionFlag(args["engine-version"] ?? args.engineVersion);
+    } catch (err) {
+      log.error(errorMessage(err));
+      process.exit(2);
+    }
     const backend = resolveBackendFlag(args.coreml, args.onnx);
     const positionals = (args._ ?? []).map(String);
     const caps = await getEngineCapabilities();
@@ -227,13 +283,14 @@ export const installCommand = defineCommand({
       log.error(errorMessage(err));
       process.exit(1);
     }
-    await performInstall(
-      resolveNoCacheFlag(args, rawArgs),
+    await performInstall({
+      noCache: resolveNoCacheFlag(args, rawArgs),
       backend,
       ttsLangs,
-      args.vad,
-      args.diarize,
-      args.plan,
-    );
+      vad: args.vad,
+      diarize: args.diarize,
+      plan: args.plan,
+      engineVersion,
+    });
   },
 });

package/src/doctor.ts

@@ -10,12 +10,13 @@ import {
 } from "./engine";
 import { readInstalledEngineVersion } from "./engine-version-marker";
 import { keshaCacheDir } from "./paths";
-import { packageName, packageVersion } from "./package-info";
+import { engineVersion, packageName, packageVersion } from "./package-info";
 import { getStatsStatus, type StatsStatus } from "./stats";
 import {
   fluidKokoroCacheInfo,
   type FluidKokoroCacheInfo,
 } from "./fluid-kokoro-cache";
+import { fluidAsrCacheInfo, isCoremlBackend } from "./fluid-asr-cache";
 import { diagnosticHomeDir, dirSizeBytes } from "./diagnostic-paths";
 import {
   getDiagnosticLogStatus,
@@ -30,6 +31,7 @@ const KNOWN_ENV_KEYS = [
   "KESHA_STATS_DB",
   "KESHA_DEBUG",
   "KESHA_DEBUG_FD",
+  "KESHA_KOKORO_COMPUTE_UNITS",
 ] as const;
 
 interface DoctorOptions {
@@ -53,6 +55,21 @@ interface OptionalComponent extends PathSummary {
 
 type DoctorDiagnosticLogStatus = DiagnosticLogStatus & { error?: string };
 
+/**
+ * How the Recorded Engine version relates to the Pinned Engine version. `differs-from-pin`
+ * is a supported state (`kesha install --engine-version`), not a fault — `unrecorded` is
+ * separate so a missing marker is never reported as a difference.
+ */
+export type EngineVersionState = "matches-pin" | "differs-from-pin" | "unrecorded";
+
+export function engineVersionState(
+  versionMarker: string | null,
+  pinnedVersion: string,
+): EngineVersionState {
+  if (versionMarker === null) return "unrecorded";
+  return versionMarker === pinnedVersion ? "matches-pin" : "differs-from-pin";
+}
+
 export interface DoctorReport {
   generatedAt: string;
   redacted: boolean;
@@ -69,6 +86,8 @@ export interface DoctorReport {
     path: string;
     installed: boolean;
     versionMarker: string | null;
+    pinnedVersion: string;
+    versionState: EngineVersionState;
     capabilities: EngineCapabilities | null;
     probeError: string | null;
   };
@@ -188,10 +207,14 @@ async function collectEngine(redact: boolean): Promise<DoctorReport["engine"]> {
     }
   }
 
+  const versionMarker = readInstalledEngineVersion(binPath);
+
   return {
     path: redactPath(binPath, redact),
     installed,
-    versionMarker: readInstalledEngineVersion(binPath),
+    versionMarker,
+    pinnedVersion: engineVersion,
+    versionState: engineVersionState(versionMarker, engineVersion),
     capabilities,
     probeError: redactString("probeError", probeError, redact),
   };
@@ -200,18 +223,33 @@ async function collectEngine(redact: boolean): Promise<DoctorReport["engine"]> {
 function collectCache(
   redact: boolean,
   fluidKokoro: FluidKokoroCacheInfo,
+  backend?: string,
 ): DoctorReport["cache"] {
   const cache = keshaCacheDir();
   const binPath = getEngineBinPath();
   const engineDir = dirname(dirname(binPath));
+  const coreml = isCoremlBackend(backend);
   const components: CacheComponent[] = [
     { label: "Engine", ...pathSummary(engineDir) },
-    { label: "ASR (Parakeet)", ...pathSummary(join(cache, "models/parakeet-tdt-v3")) },
+    // A CoreML engine never populates the ONNX dir; pointing at it would render a
+    // healthy darwin install as "ASR missing" (#684).
+    ...(coreml
+      ? []
+      : [{ label: "ASR (Parakeet)", ...pathSummary(join(cache, "models/parakeet-tdt-v3")) }]),
     { label: "Language ID", ...pathSummary(join(cache, "models/lang-id-ecapa")) },
     { label: "VAD (Silero)", ...pathSummary(join(cache, "models/silero-vad")) },
     { label: "TTS (Kokoro)", ...pathSummary(join(cache, "models/kokoro-82m")) },
     { label: "TTS (Vosk)", ...pathSummary(join(cache, "models/vosk-ru")) },
   ];
+  if (coreml) {
+    const fluidAsr = fluidAsrCacheInfo();
+    components.push({
+      label: "ASR (Parakeet, FluidAudio) (external)",
+      path: fluidAsr.path,
+      exists: fluidAsr.exists,
+      sizeBytes: fluidAsr.sizeBytes,
+    });
+  }
   if (fluidKokoro.supported) {
     components.push({
       label: "FluidAudio Kokoro cache (external)",
@@ -346,6 +384,7 @@ export async function collectDoctorReport(
 ): Promise<DoctorReport> {
   const redact = options.redact === true;
   const fluidKokoro = fluidKokoroCacheInfo();
+  const engine = await collectEngine(redact);
   return {
     generatedAt: new Date().toISOString(),
     redacted: redact,
@@ -355,8 +394,8 @@ export async function collectDoctorReport(
       platform: process.platform,
       arch: process.arch,
     },
-    engine: await collectEngine(redact),
-    cache: collectCache(redact, fluidKokoro),
+    engine,
+    cache: collectCache(redact, fluidKokoro, engine.capabilities?.backend),
     optionalComponents: collectOptionalComponents(redact, fluidKokoro),
     stats: collectStats(redact),
     diagnosticLogs: collectDiagnosticLogs(redact),
@@ -368,6 +407,22 @@ function formatInstalled(installed: boolean): string {
   return installed ? "installed" : "missing";
 }
 
+function formatVersionState(engine: DoctorReport["engine"]): string {
+  switch (engine.versionState) {
+    case "differs-from-pin":
+      return (
+        `installed v${engine.versionMarker} differs from the pinned v${engine.pinnedVersion} — ` +
+        "supported; `kesha install` without --engine-version restores the pin"
+      );
+    case "unrecorded":
+      return engine.installed
+        ? "no recorded version beside the binary; `kesha install` records one"
+        : "no engine installed";
+    default:
+      return "matches the pin";
+  }
+}
+
 function formatCapabilities(engine: DoctorReport["engine"]): string {
   if (!engine.capabilities) return engine.probeError ?? "not available";
   const { backend, protocolVersion, features } = engine.capabilities;
@@ -437,6 +492,8 @@ export function formatDoctorReport(report: DoctorReport): string {
     "Engine:",
     `  Binary: ${report.engine.path} (${formatInstalled(report.engine.installed)})`,
     `  Version marker: ${report.engine.versionMarker ?? "missing"}`,
+    `  Pinned version: ${report.engine.pinnedVersion}`,
+    `  Version state: ${formatVersionState(report.engine)}`,
     `  Capabilities: ${formatCapabilities(report.engine)}`,
     "",
     ...formatCacheSection(report.cache),

package/src/engine-install.ts

@@ -192,12 +192,12 @@ function darwinTrustBinary(path: string, displayName: string): void {
 async function downloadSidecar(
   spec: SidecarSpec,
   binPath: string,
-  engineVersion: string,
+  version: string,
 ): Promise<void> {
   if (!isDarwinArm64()) return;
 
   const sidecarPath = join(dirname(binPath), spec.fileBasename);
-  const url = `https://github.com/${GITHUB_REPO}/releases/download/v${engineVersion}/${spec.assetName}`;
+  const url = `https://github.com/${GITHUB_REPO}/releases/download/v${version}/${spec.assetName}`;
 
   let res: Response;
   try {
@@ -211,7 +211,7 @@ async function downloadSidecar(
 
   if (!res.ok) {
     log.warn(
-      `${spec.displayName} not in release v${engineVersion} (HTTP ${res.status}); ${spec.unavailableHint}.`,
+      `${spec.displayName} not in release v${version} (HTTP ${res.status}); ${spec.unavailableHint}.`,
     );
     return;
   }
@@ -328,21 +328,22 @@ export interface InstallOptions {
 }
 
 /**
- * Cache-valid path: the binary at binPath already matches engineVersion.
+ * Cache-valid path: the binary at binPath already matches the requested version.
  * Re-trusts it and tops up any sidecars the cached install is missing.
  */
 async function refreshCachedEngine(
   binPath: string,
   canWriteEngineDir: boolean,
   noCache: boolean,
+  version: string,
 ): Promise<void> {
   const engineDir = dirname(binPath);
   if (noCache && !canWriteEngineDir) {
     log.info(
-      `Engine binary at v${engineVersion} is on a read-only filesystem; --no-cache skipped for engine (still forwarded to model installs).`,
+      `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${engineVersion}).`);
+    log.success(`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).
@@ -355,7 +356,7 @@ async function refreshCachedEngine(
     const missing = SIDECARS.filter(
       (s) => !existsSync(join(engineDir, s.fileBasename)),
     );
-    await Promise.all(missing.map((s) => downloadSidecar(s, binPath, engineVersion)));
+    await Promise.all(missing.map((s) => downloadSidecar(s, binPath, version)));
     // Also re-trust already-present sidecars for the Sequoia upgrade scenario.
     for (const s of SIDECARS) {
       const p = join(engineDir, s.fileBasename);
@@ -428,21 +429,22 @@ export async function waitUntilSpawnable(
 async function fetchEngineBinary(
   binPath: string,
   installedVersion: string | null,
+  version: string,
 ): Promise<void> {
   // Log why we're downloading — helps diagnose surprising re-downloads.
-  if (existsSync(binPath) && installedVersion && installedVersion !== engineVersion) {
+  if (existsSync(binPath) && installedVersion && installedVersion !== version) {
     log.progress(
-      `Upgrading engine v${installedVersion} → v${engineVersion}...`,
+      `Replacing engine v${installedVersion} → v${version}...`,
     );
   }
   const binaryName = getEngineBinaryName();
-  const url = `https://github.com/${GITHUB_REPO}/releases/download/v${engineVersion}/${binaryName}`;
+  const url = `https://github.com/${GITHUB_REPO}/releases/download/v${version}/${binaryName}`;
 
   mkdirSync(dirname(binPath), { recursive: true });
 
   // Overlap sidecar fetches with the engine fetch (~15-30s saved on cold install).
   const sidecarPromises = SIDECARS.map((s) =>
-    downloadSidecar(s, binPath, engineVersion),
+    downloadSidecar(s, binPath, version),
   );
   // If the engine fetch throws, silence in-flight sidecar rejections so unhandledRejection doesn't obscure the engine error.
   const muteSidecarRejections = () =>
@@ -460,8 +462,9 @@ async function fetchEngineBinary(
 
   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 (HTTP ${res.status})\n  Fix: Check https://github.com/${GITHUB_REPO}/releases for available versions`,
+      `Failed to download engine binary from release v${version} (HTTP ${res.status})\n  Fix: Check https://github.com/${GITHUB_REPO}/releases for available versions`,
     );
   }
 
@@ -470,8 +473,8 @@ async function fetchEngineBinary(
   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, engineVersion);
-  log.success(`Engine binary downloaded (v${engineVersion}).`);
+  writeInstalledEngineVersion(binPath, version);
+  log.success(`Engine binary downloaded (v${version}).`);
   await Promise.all(sidecarPromises);
 }
 
@@ -556,27 +559,51 @@ function runEngineModelInstall(
   }
 }
 
-export async function downloadEngine(
-  noCache = false,
-  backend?: string,
-  options: InstallOptions = {},
-): Promise<string> {
+export interface EngineInstallRequest extends InstallOptions {
+  noCache?: boolean;
+  backend?: string;
+  /** Engine release to install; defaults to the Pinned Engine version and applies to this call only. */
+  version?: string;
+}
+
+/**
+ * Installs one Engine release plus its models.
+ *
+ * `version` is the single input for the release URL, the cache-validity comparison, the
+ * sidecar downloads and the recorded `.version` marker — reading the pin at any one of
+ * them would install the requested Engine and then replace it on the next cache check.
+ */
+export async function installEngine(request: EngineInstallRequest = {}): Promise<string> {
+  const { noCache = false, backend, version = engineVersion, ...options } = request;
   const binPath = getEngineBinPath();
   const installedVersion = readInstalledEngineVersion(binPath);
   const engineDir = dirname(binPath);
 
+  if (version !== engineVersion) {
+    log.info(
+      `Installing engine v${version} instead of the pinned v${engineVersion}; ` +
+        "a later `kesha install` without --engine-version restores the pin.",
+    );
+  }
+
   // Read-only engine dir = Nix-store install; skip download/sidecar writes to avoid EROFS errors.
   const canWriteEngineDir = checkEngineWritable(engineDir);
 
-  const versionMatches =
-    existsSync(binPath) && installedVersion === engineVersion;
+  const versionMatches = existsSync(binPath) && installedVersion === version;
   // 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);
 
   if (cacheValid) {
-    await refreshCachedEngine(binPath, canWriteEngineDir, noCache);
+    await refreshCachedEngine(binPath, canWriteEngineDir, noCache, version);
   } else {
-    await fetchEngineBinary(binPath, installedVersion);
+    if (!canWriteEngineDir) {
+      throw new Error(
+        `Cannot install engine v${version}: ${engineDir} is not writable ` +
+          `(installed: ${installedVersion ? `v${installedVersion}` : "no recorded version"}).\n` +
+          "  Fix: point KESHA_ENGINE_BIN at a writable path, or install into a writable prefix.",
+      );
+    }
+    await fetchEngineBinary(binPath, installedVersion, version);
   }
 
   if (backend || options.diarize) {
@@ -599,6 +626,22 @@ export async function downloadEngine(
     cleanupRetiredSidecars(engineDir);
   }
 
-  log.success("Backend installed successfully.");
+  log.success(`Backend installed successfully (engine v${version}).`);
   return binPath;
 }
+
+/** Installs the Pinned Engine version. Public API (`downloadModel`); the override is CLI-only. */
+export async function downloadEngine(
+  noCache = false,
+  backend?: string,
+  options: InstallOptions = {},
+): Promise<string> {
+  // Field-by-field, not a spread: a caller's stray `version` must not reach installEngine.
+  return installEngine({
+    noCache,
+    backend,
+    ttsLangs: options.ttsLangs,
+    vad: options.vad,
+    diarize: options.diarize,
+  });
+}

package/src/fluid-asr-cache.ts

@@ -0,0 +1,91 @@
+import { existsSync } from "fs";
+import { join } from "path";
+import { diagnosticHomeDir, dirSizeBytes } from "./diagnostic-paths";
+import { isDarwinArm64 } from "./fluid-kokoro-cache";
+import { engineTarget } from "./engine-targets";
+
+export const FLUID_ASR_CACHE_NOTE =
+  "required for speech-to-text; fetched by the backend during warm-up, outside Kesha's model cache";
+
+/**
+ * Which ASR layout applies. The reported backend is authoritative; when the capabilities
+ * probe yields nothing, fall back to the platform's shipped backend rather than to "not
+ * CoreML", which would point darwin at an ONNX directory it never populates (#684).
+ */
+export function isCoremlBackend(
+  backend?: string,
+  platform?: string,
+  arch?: string,
+): boolean {
+  return (backend ?? engineTarget(platform, arch)?.backend) === "coreml";
+}
+
+export interface FluidAsrCacheInfo {
+  supported: boolean;
+  path: string;
+  exists: boolean;
+  sizeBytes: number;
+}
+
+/**
+ * FluidAudio loads ASR from `<ApplicationSupport>/FluidAudio/Models/<repo folder>`,
+ * and that folder name has the `-coreml` suffix stripped — the `…-v3-coreml` sibling
+ * that also appears on disk is not what it reads (#684).
+ */
+export function fluidAsrCachePath(homeDir = diagnosticHomeDir()): string {
+  return join(
+    homeDir,
+    "Library",
+    "Application Support",
+    "FluidAudio",
+    "Models",
+    "parakeet-tdt-0.6b-v3",
+  );
+}
+
+/**
+ * What FluidAudio's own `modelsExist` requires. The encoder is pinned to int8 because
+ * the bridge calls `downloadAndLoad(to:)` with its default `useInt8Encoder: true` —
+ * accepting `EncoderInt4.mlmodelc` would pass preflight and then let FluidAudio fetch
+ * the int8 encoder on first transcribe. Keep in step with `models.rs::FLUID_ASR_REQUIRED`.
+ */
+export const FLUID_ASR_REQUIRED = [
+  "Preprocessor.mlmodelc",
+  "Encoder.mlmodelc",
+  "Decoder.mlmodelc",
+  "JointDecisionv3.mlmodelc",
+  "parakeet_vocab.json",
+];
+
+/**
+ * Complete enough to transcribe. Mirrors `models.rs::fluidaudio_asr_ready` — a bare
+ * directory check would call an interrupted fetch healthy, and the engine would then
+ * download the remainder on first transcribe (#684).
+ *
+ * Existence-only on purpose: FluidAudio's own `modelsExist` is `fileExists` over the same
+ * names, and its download skips whatever that predicate accepts. Requiring more here (that
+ * each `.mlmodelc` is a directory, that `coremldata.bin` is inside) would report not-ready
+ * for a bundle FluidAudio considers present, so `kesha install` would fetch nothing and the
+ * user could never clear the error. Match the loader; do not out-strict it.
+ */
+export function fluidAsrCacheReady(path: string): boolean {
+  return FLUID_ASR_REQUIRED.every((f) => existsSync(join(path, f)));
+}
+
+export function fluidAsrCacheInfo(
+  options: {
+    platform?: typeof process.platform;
+    arch?: typeof process.arch;
+    homeDir?: string;
+  } = {},
+): FluidAsrCacheInfo {
+  const supported = isDarwinArm64(options.platform, options.arch);
+  const path = fluidAsrCachePath(options.homeDir);
+
+  return {
+    supported,
+    path,
+    exists: supported && fluidAsrCacheReady(path),
+    sizeBytes: supported ? dirSizeBytes(path) : 0,
+  };
+}

package/src/install-plan.ts

@@ -1,7 +1,7 @@
 import { existsSync, statSync } from "fs";
 import { humanBytes } from "./format";
 import { dirname, join } from "path";
-import { getEngineBinPath } from "./engine";
+import { getEngineBinPath, getEngineCapabilities } from "./engine";
 import { SIDECARS } from "./engine-install";
 import { engineTarget } from "./engine-targets";
 import { readInstalledEngineVersion } from "./engine-version-marker";
@@ -13,6 +13,12 @@ import {
   isDarwinArm64,
 } from "./fluid-kokoro-cache";
 import modelPlan from "../model-plan.json" with { type: "json" };
+import {
+  FLUID_ASR_CACHE_NOTE,
+  fluidAsrCachePath,
+  fluidAsrCacheReady,
+  isCoremlBackend,
+} from "./fluid-asr-cache";
 
 export interface InstallPlanOptions {
   noCache?: boolean;
@@ -21,6 +27,8 @@ export interface InstallPlanOptions {
   ttsLangs?: string[];
   vad?: boolean;
   diarize?: boolean;
+  /** `--engine-version`; the plan must preview the release the real install would fetch. */
+  engineVersion?: string;
 }
 
 interface PlanFile {
@@ -46,6 +54,8 @@ interface PlanComponent {
   cached: boolean;
   refresh: boolean;
   note?: string;
+  /** Fetched by a backend into its own cache — excluded from the Kesha-managed totals. */
+  external?: boolean;
 }
 
 interface PlanWarmup {
@@ -135,14 +145,59 @@ function bundleComponent(input: {
   };
 }
 
-function buildEngineComponent(binPath: string, noCache: boolean): PlanComponent {
+/**
+ * A CoreML engine cannot read the ONNX weights, so quoting their 2.43 GB would
+ * promise a download that never happens. FluidAudio fetches its own bundle during
+ * the install warm-up instead — still a cost, so it is named rather than dropped (#684).
+ *
+ * Measured from `parakeet-tdt-0.6b-v3`, the directory the current FluidAudio actually
+ * loads. A `…-v3-coreml` sibling may also exist from earlier versions; counting it here
+ * would overstate the plan against what `status --disk` then reports. An estimate, not a
+ * manifest sum — rendered as approximate.
+ */
+const FLUID_ASR_BUNDLE_BYTES = 473 * 1024 * 1024;
+
+/**
+ * An explicit `--coreml` / `--onnx` wins. Otherwise ask the installed engine, so a custom
+ * `KESHA_ENGINE_BIN` is planned for what it actually is rather than what the host usually
+ * ships (#684). The probe is optional: `--plan` must still work before any engine exists,
+ * and `isCoremlBackend` falls back to the platform when it yields nothing.
+ */
+async function planBackendIsCoreml(options: InstallPlanOptions): Promise<boolean> {
+  if (options.backend === "coreml") return true;
+  if (options.backend === "onnx") return false;
+  const probed = await getEngineCapabilities().catch(() => null);
+  return isCoremlBackend(probed?.backend);
+}
+
+function fluidAsrComponent(): PlanComponent {
+  return {
+    name: "ASR Parakeet TDT v3 (CoreML)",
+    source: "FluidAudio cache",
+    sizeBytes: FLUID_ASR_BUNDLE_BYTES,
+    cached: fluidAsrCacheReady(fluidAsrCachePath()),
+    // `--no-cache` is a Kesha-cache flag; FluidAudio's bundle is not re-fetched by it.
+    refresh: false,
+    external: true,
+    note: FLUID_ASR_CACHE_NOTE,
+  };
+}
+
+function engineIsCached(binPath: string, version: string): boolean {
+  return existsSync(binPath) && readInstalledEngineVersion(binPath) === version;
+}
+
+function buildEngineComponent(
+  binPath: string,
+  noCache: boolean,
+  version: string,
+): PlanComponent {
   const engineAsset = engineAssetForPlatform();
   if (engineAsset) {
-    const engineCached =
-      existsSync(binPath) && readInstalledEngineVersion(binPath) === engineVersion;
+    const engineCached = engineIsCached(binPath, version);
     return {
       name: `Engine ${engineAsset.assetName}`,
-      source: `GitHub release v${engineVersion}`,
+      source: `GitHub release v${version}`,
       sizeBytes: engineAsset.sizeBytes,
       cached: engineCached,
       refresh: noCache,
@@ -158,13 +213,19 @@ function buildEngineComponent(binPath: string, noCache: boolean): PlanComponent
   };
 }
 
-function buildSidecarComponents(engineDir: string, noCache: boolean): PlanComponent[] {
+function buildSidecarComponents(
+  engineDir: string,
+  noCache: boolean,
+  version: string,
+  engineCached: boolean,
+): PlanComponent[] {
   if (!isDarwinArm64()) return [];
   return DARWIN_SIDECARS.map((sidecar) => ({
     name: `Sidecar ${sidecar.assetName}`,
-    source: `GitHub release v${engineVersion}`,
+    source: `GitHub release v${version}`,
     sizeBytes: sidecar.sizeBytes,
-    cached: existsSync(join(engineDir, sidecar.fileBasename)),
+    // A cold engine fetch re-downloads every sidecar; only a cache hit tops up the missing ones.
+    cached: engineCached && existsSync(join(engineDir, sidecar.fileBasename)),
     refresh: noCache,
   }));
 }
@@ -245,6 +306,8 @@ function assembleComponents(input: {
   engineDir: string;
   noCache: boolean;
   options: InstallPlanOptions;
+  coreml: boolean;
+  version: string;
   tts: ReturnType<typeof buildTtsComponents>;
 }): PlanComponent[] {
   const { cacheRoot, noCache, options } = input;
@@ -252,9 +315,16 @@ function assembleComponents(input: {
     bundleComponent({ cacheRoot, name, source: "model cache", files, refresh: noCache, note });
 
   const components: PlanComponent[] = [
-    buildEngineComponent(input.binPath, noCache),
-    ...buildSidecarComponents(input.engineDir, noCache),
-    modelBundle("ASR Parakeet TDT v3", ASR_FILES, "required for speech-to-text"),
+    buildEngineComponent(input.binPath, noCache, input.version),
+    ...buildSidecarComponents(
+      input.engineDir,
+      noCache,
+      input.version,
+      engineIsCached(input.binPath, input.version),
+    ),
+    input.coreml
+      ? fluidAsrComponent()
+      : modelBundle("ASR Parakeet TDT v3", ASR_FILES, "required for speech-to-text"),
     modelBundle(
       "Audio language ID ECAPA",
       LANG_ID_FILES,
@@ -279,12 +349,18 @@ function assembleComponents(input: {
   return components;
 }
 
-function renderHeader(cacheRoot: string, binPath: string, backend: string | undefined): string[] {
+function renderHeader(
+  cacheRoot: string,
+  binPath: string,
+  backend: string | undefined,
+  version: string,
+): string[] {
+  const pinNote = version === engineVersion ? "" : ` (overrides the pinned v${engineVersion})`;
   return [
     "Kesha install plan",
     "",
     `Package: @drakulavich/kesha-voice-kit ${packageVersion}`,
-    `Engine release: v${engineVersion}`,
+    `Engine release: v${version}${pinNote}`,
     `Platform: ${process.platform} ${process.arch}`,
     `Cache: ${cacheRoot}`,
     `Engine binary: ${binPath}`,
@@ -298,7 +374,9 @@ function renderComponentLines(components: PlanComponent[]): string[] {
   const status = (c: PlanComponent) => (c.refresh ? "refresh" : c.cached ? "cached" : "needed");
   const lines: string[] = [];
   for (const c of components) {
-    lines.push(`  - ${c.name}: ${humanBytes(c.sizeBytes)} (${c.sizeBytes} bytes, ${status(c)}, ${c.source})`);
+    const size = c.external ? `~${humanBytes(c.sizeBytes)}` : humanBytes(c.sizeBytes);
+    const detail = c.external ? "approximate" : `${c.sizeBytes} bytes`;
+    lines.push(`  - ${c.name}: ${size} (${detail}, ${status(c)}, ${c.source})`);
     if (c.note) lines.push(`    ${c.note}`);
   }
   return lines;
@@ -310,14 +388,25 @@ function renderWarmupLines(warmups: PlanWarmup[]): string[] {
 }
 
 function renderTotalLines(components: PlanComponent[]): string[] {
-  const coldBytes = components.reduce((sum, c) => sum + c.sizeBytes, 0);
-  const expectedNetworkBytes = components.reduce((sum, c) => (c.cached && !c.refresh ? sum : sum + c.sizeBytes), 0);
-  return [
+  // External components are fetched by a backend into its own cache, so they cannot
+  // sit under a total labelled "Kesha-managed" — they get their own line (#684).
+  const managed = components.filter((c) => !c.external);
+  const external = components.filter((c) => c.external);
+  const coldBytes = managed.reduce((sum, c) => sum + c.sizeBytes, 0);
+  const expectedNetworkBytes = managed.reduce((sum, c) => (c.cached && !c.refresh ? sum : sum + c.sizeBytes), 0);
+  const lines = [
     "",
     "Totals:",
     `  Cold-cache Kesha-managed download: ${humanBytes(coldBytes)}`,
     `  Expected Kesha-managed network for this run: ${humanBytes(expectedNetworkBytes)}`,
   ];
+  const externalPending = external.reduce((sum, c) => (c.cached ? sum : sum + c.sizeBytes), 0);
+  if (externalPending > 0) {
+    lines.push(
+      `  Additionally fetched by the backend into its own cache: ~${humanBytes(externalPending)}`,
+    );
+  }
+  return lines;
 }
 
 function renderBehaviorLines(ttsLangs: string[], wantsAnyKokoro: boolean): string[] {
@@ -344,6 +433,7 @@ export function buildInstallCommand(options: InstallPlanOptions, ttsLangs: strin
   return [
     "kesha",
     "install",
+    ...(options.engineVersion ? ["--engine-version", options.engineVersion] : []),
     options.noCache ? "--no-cache" : "",
     options.backend === "coreml" ? "--coreml" : "",
     options.backend === "onnx" ? "--onnx" : "",
@@ -379,11 +469,23 @@ export async function renderInstallPlan(options: InstallPlanOptions = {}): Promi
   const noCache = options.noCache === true;
   const ttsLangs = options.ttsLangs ?? [];
 
+  const version = options.engineVersion ?? engineVersion;
+
   const tts = buildTtsComponents(cacheRoot, ttsLangs, noCache);
-  const components = assembleComponents({ cacheRoot, binPath, engineDir, noCache, options, tts });
+  const coreml = await planBackendIsCoreml(options);
+  const components = assembleComponents({
+    cacheRoot,
+    binPath,
+    engineDir,
+    noCache,
+    options,
+    coreml,
+    version,
+    tts,
+  });
 
   const lines = [
-    ...renderHeader(cacheRoot, binPath, options.backend),
+    ...renderHeader(cacheRoot, binPath, options.backend, version),
     ...renderComponentLines(components),
     ...renderFooter({
       components,

package/src/semver.d.mts

@@ -0,0 +1,16 @@
+// The module stays .mjs because the npm-publish and homebrew workflows run their scripts
+// under node, which cannot import a .ts module.
+export type SemVer = {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease: string[];
+  build: string[];
+};
+
+export function tryParseSemver(raw: unknown): SemVer | null;
+export function parseSemver(raw: unknown, label: string): SemVer;
+export function isSemver(raw: unknown): boolean;
+export function isStableVersion(raw: unknown): boolean;
+export function cmp(a: SemVer, b: SemVer): number;
+export function fmt(v: SemVer): string;

package/src/semver.mjs

@@ -0,0 +1,87 @@
+/**
+ * SemVer 2.0 — the one place in this repo that knows the grammar.
+ *
+ * `kesha install --engine-version`, the version drift gate, the alpha derivation, the npm
+ * dist-tag resolver, the package.json writer and the Linux package names all decide "is this
+ * a version" or "which is newer". Separate copies disagree at the edges: `derive-alpha-version`
+ * asserts its output sorts above the pin that `check-versions` later validates, so one parser
+ * accepting what another refuses is a release that passes derivation and fails the gate
+ * (#685, #738).
+ *
+ * Stays `.mjs`: npm-publish.yml, release-npm-publish.yml and homebrew-tap.yml run their
+ * scripts under node, which cannot import a `.ts` module. Types live in `semver.d.mts`.
+ *
+ * The release *tag* grammar is deliberately not here — `.github/scripts/release-tags.mjs`
+ * keeps it as a POSIX ERE string so bash `=~` and JavaScript consume identical text.
+ */
+
+/** The pattern published with the SemVer 2.0 spec; a looser one accepts `1.0.0-01` and `01.2.3`. */
+const SEMVER_2_0 =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+
+/** The only place the pattern is applied; everything else here builds on this. */
+export function tryParseSemver(raw) {
+  const m = typeof raw === "string" ? raw.match(SEMVER_2_0) : null;
+  if (!m) return null;
+  return {
+    major: Number(m[1]),
+    minor: Number(m[2]),
+    patch: Number(m[3]),
+    prerelease: m[4]?.split(".") ?? [],
+    build: m[5]?.split(".") ?? [],
+  };
+}
+
+export function parseSemver(raw, label) {
+  const parsed = tryParseSemver(raw);
+  if (!parsed) {
+    throw new Error(`${label}: not a valid SemVer 2.0 version (got '${raw}')`);
+  }
+  return parsed;
+}
+
+export function isSemver(raw) {
+  return tryParseSemver(raw) !== null;
+}
+
+/** A version fit for a release tag or a package filename: no prerelease, no build metadata. */
+export function isStableVersion(raw) {
+  const parsed = tryParseSemver(raw);
+  return parsed !== null && parsed.prerelease.length === 0 && parsed.build.length === 0;
+}
+
+/** SemVer §10: build metadata is ignored when determining precedence. */
+export function cmp(a, b) {
+  if (a.major !== b.major) return a.major - b.major;
+  if (a.minor !== b.minor) return a.minor - b.minor;
+  if (a.patch !== b.patch) return a.patch - b.patch;
+
+  // SemVer precedence: a stable version outranks its prereleases.
+  if (a.prerelease.length === 0 && b.prerelease.length === 0) return 0;
+  if (a.prerelease.length === 0) return 1;
+  if (b.prerelease.length === 0) return -1;
+
+  const len = Math.max(a.prerelease.length, b.prerelease.length);
+  for (let i = 0; i < len; i++) {
+    const ai = a.prerelease[i];
+    const bi = b.prerelease[i];
+    if (ai === undefined) return -1;
+    if (bi === undefined) return 1;
+    if (ai === bi) continue;
+
+    const an = ai.match(/^(0|[1-9]\d*)$/);
+    const bn = bi.match(/^(0|[1-9]\d*)$/);
+    if (an && bn) return Number(ai) - Number(bi);
+    if (an) return -1;
+    if (bn) return 1;
+    return ai < bi ? -1 : 1;
+  }
+
+  return 0;
+}
+
+export function fmt(v) {
+  const base = `${v.major}.${v.minor}.${v.patch}`;
+  const withPre = v.prerelease.length ? `${base}-${v.prerelease.join(".")}` : base;
+  return v.build.length ? `${withPre}+${v.build.join(".")}` : withPre;
+}

package/src/star.ts

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync, writeFileSync } from "fs";
+import { tryParseSemver } from "./semver.mjs";
 
 /**
  * Version-bump gate for the "star the repo" prompt in `kesha install`.
@@ -26,12 +27,8 @@ export function writeStarSeen(binPath: string, version: string): void {
 }
 
 function parseMajorMinor(v: string): [number, number] | null {
-  const parts = v.split(".");
-  if (parts.length < 2) return null;
-  const major = Number(parts[0]);
-  const minor = Number(parts[1]);
-  if (!Number.isFinite(major) || !Number.isFinite(minor)) return null;
-  return [major, minor];
+  const parsed = tryParseSemver(v);
+  return parsed && [parsed.major, parsed.minor];
 }
 
 /**

package/src/status.ts

@@ -11,6 +11,7 @@ import { log } from "./log";
 import { packageVersion } from "./package-info";
 import { keshaCacheDir } from "./paths";
 import { fluidKokoroCacheInfo } from "./fluid-kokoro-cache";
+import { fluidAsrCacheInfo, isCoremlBackend } from "./fluid-asr-cache";
 import { dirSizeBytes } from "./diagnostic-paths";
 import pc from "picocolors";
 
@@ -52,6 +53,7 @@ export interface StatusDiskUsage {
   componentTotalBytes: number;
   totalBytes: number;
   fluidKokoro: { path: string; sizeBytes: number } | null;
+  fluidAsr: { path: string; sizeBytes: number } | null;
 }
 
 /**
@@ -90,7 +92,7 @@ export async function collectStatus(options: ShowStatusOptions = {}): Promise<St
       ? null
       : `Run \`${installHint()}\` to download the engine and models.`,
     // Absent engine means no disk walk, matching the human path (#647).
-    disk: installed && options.disk ? collectDiskUsage(path) : null,
+    disk: installed && options.disk ? collectDiskUsage(path, capabilities?.backend) : null,
   };
 }
 
@@ -144,10 +146,19 @@ export function renderStatus(report: StatusReport): void {
 }
 
 
-function buildDiskComponents(cache: string, engineDir: string): Array<{ label: string; path: string }> {
+function buildDiskComponents(
+  cache: string,
+  engineDir: string,
+  coreml: boolean,
+): Array<{ label: string; path: string }> {
   return [
     { label: "Engine", path: engineDir },
-    { label: "ASR (Parakeet)", path: join(cache, "models/parakeet-tdt-v3") },
+    // A CoreML engine never populates the ONNX dir, and its own bundle lives outside
+    // the Kesha cache — so it is reported under external caches, not here, or the rows
+    // would sum past a Total that cannot include it (#684).
+    ...(coreml
+      ? []
+      : [{ label: "ASR (Parakeet)", path: join(cache, "models/parakeet-tdt-v3") }]),
     { label: "Language ID", path: join(cache, "models/lang-id-ecapa") },
     { label: "VAD (Silero)", path: join(cache, "models/silero-vad") },
     { label: "TTS (Kokoro)", path: join(cache, "models/kokoro-82m") },
@@ -169,20 +180,28 @@ function logDiskRows(rows: StatusDiskComponent[], total: number, componentTotal:
   }
 }
 
-function logFluidKokoroCache(fluidKokoro: StatusDiskUsage["fluidKokoro"]): void {
-  if (!fluidKokoro) return;
+function logExternalCaches(disk: StatusDiskUsage): void {
+  if (!disk.fluidKokoro && !disk.fluidAsr) return;
   log.info("");
   log.info(`External caches (not included in Kesha total):`);
-  log.info(`  FluidAudio Kokoro: ${humanBytes(fluidKokoro.sizeBytes)} (${fluidKokoro.path})`);
+  if (disk.fluidAsr) {
+    log.info(`  FluidAudio ASR:    ${humanBytes(disk.fluidAsr.sizeBytes)} (${disk.fluidAsr.path})`);
+  }
+  if (disk.fluidKokoro) {
+    log.info(
+      `  FluidAudio Kokoro: ${humanBytes(disk.fluidKokoro.sizeBytes)} (${disk.fluidKokoro.path})`,
+    );
+  }
 }
 
-function collectDiskUsage(binPath: string): StatusDiskUsage {
+function collectDiskUsage(binPath: string, backend?: string): StatusDiskUsage {
   const cache = keshaCacheDir();
   // Two levels up from the binary (`<cache>/engine/bin/`) so future engine-root siblings are counted.
   const engineDir = join(binPath, "..", "..");
+  const coreml = isCoremlBackend(backend);
 
   const components: StatusDiskComponent[] = [];
-  for (const c of buildDiskComponents(cache, engineDir)) {
+  for (const c of buildDiskComponents(cache, engineDir, coreml)) {
     const sizeBytes = dirSizeBytes(c.path);
     if (sizeBytes > 0) components.push({ label: c.label, sizeBytes });
   }
@@ -191,6 +210,8 @@ function collectDiskUsage(binPath: string): StatusDiskUsage {
   const cacheTotal = dirSizeBytes(cache);
   const engineOutsideCache = engineDir.startsWith(cache) ? 0 : dirSizeBytes(engineDir);
   const fluidKokoro = fluidKokoroCacheInfo();
+  // Only walked when it is the backend in play; otherwise the size is computed and dropped.
+  const fluidAsr = coreml ? fluidAsrCacheInfo() : null;
 
   return {
     cachePath: cache,
@@ -201,6 +222,12 @@ function collectDiskUsage(binPath: string): StatusDiskUsage {
       fluidKokoro.exists && fluidKokoro.sizeBytes > 0
         ? { path: fluidKokoro.path, sizeBytes: fluidKokoro.sizeBytes }
         : null,
+    // Gate on readiness, not size, so a partial bundle is not shown as a present
+    // cache while doctor reports it missing.
+    fluidAsr:
+      fluidAsr?.exists && fluidAsr.sizeBytes > 0
+        ? { path: fluidAsr.path, sizeBytes: fluidAsr.sizeBytes }
+        : null,
   };
 }
 
@@ -209,7 +236,7 @@ function showDiskUsage(disk: StatusDiskUsage): void {
 
   log.info(`Disk usage (${disk.cachePath}):`);
   logDiskRows(disk.components, disk.totalBytes, disk.componentTotalBytes);
-  logFluidKokoroCache(disk.fluidKokoro);
+  logExternalCaches(disk);
   log.info("");
   log.info(
     pc.dim(`  To reset cache: rm -rf ${disk.cachePath} — next \`kesha install\` re-downloads.`),

package/src/__tests__/error-codes-drift.test.ts

@@ -1,29 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { existsSync, readFileSync } from "node:fs";
-import { spawnSync } from "node:child_process";
-import { join } from "node:path";
-import { KNOWN_TS_CODES } from "../error-codes";
-
-const ENGINE_BIN =
-  process.env.KESHA_ENGINE_BIN ?? join(import.meta.dir, "../../rust/target/release/kesha-engine");
-
-const describeOrSkip = existsSync(ENGINE_BIN) ? describe : describe.skip;
-
-describeOrSkip("error-code drift", () => {
-  test("engine codes ∪ TS-native codes == codes documented in docs/errors.md", () => {
-    const res = spawnSync(ENGINE_BIN, ["--error-codes-json"], { encoding: "utf8" });
-    expect(res.status).toBe(0);
-    const engineCodes: string[] = JSON.parse(res.stdout).map((e: { code: string }) => e.code);
-
-    const known = new Set<string>([...engineCodes, ...KNOWN_TS_CODES]);
-
-    const doc = readFileSync(join(import.meta.dir, "../../docs/errors.md"), "utf8");
-    const documented = new Set<string>();
-    for (const m of doc.matchAll(/`(E_[A-Z0-9_]+)`/g)) documented.add(m[1]);
-
-    // every known code is documented
-    for (const c of known) expect(documented.has(c)).toBe(true);
-    // every documented code is known (no stale doc rows)
-    for (const c of documented) expect(known.has(c)).toBe(true);
-  });
-});

package/src/__tests__/error-codes.test.ts

@@ -1,25 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { extractEngineErrorCode, TS_NATIVE_CODES, KNOWN_TS_CODES } from "../error-codes";
-
-describe("extractEngineErrorCode", () => {
-  test("extracts the code from a coded engine stderr line", () => {
-    const stderr = "error [E_MODEL_MISSING]: voice 'ru-vosk-m02' not installed. run: kesha install --tts";
-    expect(extractEngineErrorCode(stderr)).toBe("E_MODEL_MISSING");
-  });
-
-  test("extracts even when the message embeds a path or token", () => {
-    const stderr = "warning: foo\nerror [E_BAD_AUDIO]: decode error in: /Users/alice/secret-token-abc.wav";
-    expect(extractEngineErrorCode(stderr)).toBe("E_BAD_AUDIO");
-  });
-
-  test("returns undefined for an uncoded stderr so caller can fall back", () => {
-    expect(extractEngineErrorCode("Error: something went wrong")).toBeUndefined();
-  });
-
-  test("TS-native codes are exposed and included in KNOWN_TS_CODES", () => {
-    expect(TS_NATIVE_CODES.INPUT_NOT_FOUND).toBe("E_INPUT_NOT_FOUND");
-    expect(TS_NATIVE_CODES.ENGINE_SPAWN).toBe("E_ENGINE_SPAWN");
-    expect(TS_NATIVE_CODES.INVALID_ARG).toBe("E_INVALID_ARG");
-    expect(KNOWN_TS_CODES.has("E_INTERNAL")).toBe(true);
-  });
-});

package/src/__tests__/stats-error-codes.test.ts

@@ -1,14 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { SayError } from "../synth";
-
-describe("SayError carries a taxonomy code", () => {
-  test("pre-check throws carry text codes", () => {
-    const e = new SayError("text is empty", 2, "", "E_TEXT_EMPTY");
-    expect(e.code).toBe("E_TEXT_EMPTY");
-    expect(e.exitCode).toBe(2);
-  });
-  test("defaults to E_INTERNAL when unspecified", () => {
-    const e = new SayError("boom", 4, "");
-    expect(e.code).toBe("E_INTERNAL");
-  });
-});