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

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/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kesha-voice-kit
-description: Local multilingual voice toolkit — speech-to-text (STT), text-to-speech (TTS), and language detection. Runs entirely offline on Apple Silicon, Linux, and Windows. No API keys, no cloud. NVIDIA Parakeet TDT for STT across 25 European languages, Kokoro-82M + Vosk-TTS for TTS, plus macOS AVSpeechSynthesizer for ~180 system voices with zero install.
+description: Local multilingual voice toolkit — speech-to-text (STT), text-to-speech (TTS), speaker diarization, and language detection, over a CLI or an MCP server. Runs entirely offline on Apple Silicon, Linux, and Windows. No API keys, no cloud. NVIDIA Parakeet TDT for STT across 25 European languages, Kokoro-82M + Vosk-TTS for TTS in 9 languages, plus macOS AVSpeechSynthesizer for ~180 system voices with zero install.
 emoji: 🎙️
 
 requires:
@@ -17,7 +17,7 @@ install:
 
 Local voice toolkit: transcribe voice messages to text, synthesize speech, detect language of audio or text. Fully offline after `kesha install`. No API keys, no per-minute billing.
 
-**Trigger keywords for when to use this skill:** voice message, voice memo, voice note, .ogg, .opus, .wav, .mp3, audio file, transcribe, transcription, speech-to-text, STT, text-to-speech, TTS, synthesize speech, say, telegram voice note, whatsapp voice note, ogg-opus, opus, multilingual voice, multilingual ASR, language detection, offline voice, privacy, Apple Silicon, CoreML.
+**Trigger keywords for when to use this skill:** voice message, voice memo, voice note, .ogg, .opus, .wav, .mp3, audio file, transcribe, transcription, speech-to-text, STT, text-to-speech, TTS, synthesize speech, say, telegram voice note, whatsapp voice note, ogg-opus, opus, multilingual voice, multilingual ASR, language detection, speaker diarization, who said what, meeting transcript, MCP server, offline voice, privacy, Apple Silicon, CoreML.
 
 ## When to use
 
@@ -107,6 +107,16 @@ When invoking Kesha manually from an OpenClaw flow, write OGG/Opus into an OpenC
 
 Do not configure OpenClaw Telegram TTS as `kesha say "<text>" > reply.wav`; that creates a WAV file and will not render as a native Telegram voice note.
 
+## MCP server
+
+`kesha mcp` serves the same capabilities over Model Context Protocol (stdio), exposing `transcribe_audio`, `synthesize_speech`, `list_voices`, and `list_languages` to any MCP client:
+
+```json
+{ "mcpServers": { "kesha": { "command": "kesha", "args": ["mcp"] } } }
+```
+
+Models are never auto-downloaded — tools fail with a `kesha install` / `kesha install --tts` hint when missing. Full client setup (Claude Code, Claude Desktop, Codex, Cursor): [docs/mcp.md](docs/mcp.md).
+
 ## STT: transcribe audio
 
 ```bash
@@ -207,8 +217,9 @@ bun add -g @drakulavich/kesha-voice-kit          # global CLI install (always fi
 kesha init
 
 # For agents and CI: explicit, scriptable install commands
-kesha install                                    # engine only (~350 MB)
-kesha install --tts                              # + Kokoro + Vosk-TTS RU (~990 MB more)
+kesha install                                    # engine only — ~0.6 GB on Apple Silicon, ~2.5 GB on Linux/Windows
+kesha install --plan                             # preview exact download/disk sizes first — downloads nothing
+kesha install --tts                              # + English Kokoro; add langs additively: --tts en ru es
 kesha install --tts --vad                        # + Silero VAD (long-audio chunking)
 kesha install --tts --vad --diarize              # + speaker diarization (darwin-arm64 only)
 ```
@@ -223,7 +234,7 @@ No system deps — English G2P is embedded (`misaki-rs`); Russian G2P is bundled
 
 **Speech-to-text (25):** Bulgarian, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Latvian, Lithuanian, Maltese, Polish, Portuguese, Romanian, Russian, Slovak, Slovenian, Spanish, Swedish, Ukrainian.
 
-**Text-to-speech:** English (Kokoro-82M; FluidAudio CoreML on darwin-arm64, ONNX elsewhere), Russian (Vosk-TTS, 5 baked-in speakers — default `ru-vosk-m02`), plus any macOS system voice via `--voice macos-*`.
+**Text-to-speech (9):** English (Kokoro-82M; FluidAudio CoreML on darwin-arm64, ONNX elsewhere), Russian (Vosk-TTS, 5 baked-in speakers — default `ru-vosk-m02`), Spanish, French, Italian, Portuguese (Kokoro — CharsiuG2P on ONNX builds, FluidAudio G2P on darwin-arm64), plus Hindi, Japanese, Chinese (Kokoro, darwin-arm64 only). `hi`/`ja` accept romanized Latin input only; native Devanagari and kana/kanji are rejected with `E_SCRIPT_UNSUPPORTED` — see [#492](https://github.com/drakulavich/kesha-voice-kit/issues/492). Any macOS system voice is also available via `--voice macos-*`.
 
 ## Performance
 

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.2",
   "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),