@drakulavich/kesha-voice-kit 1.24.6 → 1.25.0

package/README.md

@@ -16,7 +16,7 @@
 - **Transcribe locally** — [25 languages](docs/languages.md#speech-to-text-25), up to ~19x faster than Whisper on Apple Silicon, ~2.5x on CPU
 - **Speak back** — text-to-speech in [9 languages](docs/languages.md#text-to-speech)
 - **Plug into agents** — ship voice workflows as CLI commands, an MCP server, an <a href="docs/openclaw.md">OpenClaw</a> skill, or a <a href="docs/hermes.md">Hermes</a> agent
-- **Small Rust engine** — single ~20MB binary, no ffmpeg, no Python, no native Node addons
+- **Small Rust engine** — single ~60MB binary, no ffmpeg, no Python, no native Node addons
 
 <p align="center">
   <img src="https://github.com/drakulavich/kesha-voice-kit/raw/main/demo.gif" alt="kesha demo — English + Russian transcription with automatic language detection" width="800">
@@ -24,16 +24,21 @@
 
 ## Quick Start
 
-Runtime: **[Bun](https://bun.sh)** >= 1.3.0 · Platforms: macOS arm64, Linux x64, Windows x64.
+Runtime: **[Bun](https://bun.sh)** >= 1.3.0 · Platforms: macOS arm64, Linux x64. Windows x64 is currently blocked at install ([#216](https://github.com/drakulavich/kesha-voice-kit/issues/216)).
 
 ```bash
 # 1. Install Bun (skip if you have it) — Linux & macOS:
 curl -fsSL https://bun.sh/install | bash        # or: brew install oven-sh/bun/bun
 # Windows: powershell -c "irm bun.sh/install.ps1 | iex"
+# if `bun --version` fails, reload PATH: exec $SHELL -l
 
 # 2. Install Kesha:
 bun add -g @drakulavich/kesha-voice-kit
-kesha install        # downloads engine + models (explicit — never automatic)
+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.
+                      # No progress bar during the model step; can take several minutes.
+                      # Prefer a guided wizard? `kesha init` walks through the same choices interactively.
 
 # 3. Transcribe:
 kesha audio.ogg      # transcript to stdout
@@ -51,6 +56,8 @@ kesha --format json audio.ogg              # full JSON with lang fields
 kesha --json --timestamps audio.ogg        # JSON with timestamped segments
 kesha --toon audio.ogg                     # compact LLM-friendly TOON
 kesha status                               # show installed backend info
+kesha status --disk                        # + recursive cache disk usage
+kesha status --json                        # machine-readable, for scripts
 ```
 
 Multiple files get `head`-style headers; stdout is the transcript, stderr is errors — pipe-friendly:
@@ -64,6 +71,7 @@ $ kesha freedom.ogg tahiti.ogg
 Таити, Таити! Не были мы ни в какой Таити! Нас и тут неплохо кормят.
 ```
 
+- **Record from the mic (macOS):** `kesha record --out hello.wav` writes microphone audio to a WAV file (`kesha hello.wav` transcribes it). macOS prompts for microphone access on first use — grant it under System Settings → Privacy & Security → Microphone if it was denied. On Linux/Windows or headless boxes, pass any existing audio file straight to `kesha` instead.
 - **Long / silence-heavy audio:** install VAD (`kesha install --vad`); Kesha auto-uses it past 120 s. Without VAD, long audio falls back to fixed ASR chunks. See [docs/vad.md](docs/vad.md).
 - **Speaker diarization** (darwin-arm64): `kesha install --diarize`, then `kesha --json --vad --speakers meeting.m4a` stamps each segment with a `speaker` id. Linux/Windows return a clear "darwin-arm64 only" error ([#199](https://github.com/drakulavich/kesha-voice-kit/issues/199)).
 
@@ -72,7 +80,8 @@ $ kesha freedom.ogg tahiti.ogg
 Kesha speaks back in [9 languages](docs/languages.md#text-to-speech), auto-picking the voice from the text's language. Override with `--lang <code>` or `--voice <id>`.
 
 ```bash
-kesha install --tts                              # opt-in models (~990MB)
+kesha install --tts                              # English voices; sizes differ per platform — preview: kesha install --plan
+kesha install --tts en ru                        # + Russian (+~890 MB, Vosk)
 kesha say "Hello, world" > hello.wav
 kesha say "Привет, мир" > privet.wav             # auto-routes by language
 kesha say --voice ru-vosk-m02 "Голос в текст." > ru.wav
@@ -117,7 +126,7 @@ All of these install the Bun CLI wrapper; engine + models still download explici
 - **MCP server** — `kesha mcp` exposes transcribe/synthesize/list tools to any MCP client (Claude, Cursor, Codex, Gemini). Setup: [docs/mcp.md](docs/mcp.md).
 - **OpenClaw** — give your LLM agent ears. Install & config: [docs/openclaw.md](docs/openclaw.md).
 - **Hermes Agent** — local STT/TTS through Hermes command providers. Setup: [docs/hermes.md](docs/hermes.md).
-- **Raycast** (macOS) — transcribe selected audio & speak the clipboard from the launcher. Source + install: [`raycast/`](raycast/).
+- **Raycast** (macOS) — offline microphone dictation from the launcher: *Dictate to Clipboard* records with a live signal meter, auto-stops on silence, transcribes locally, and copies the text. [Install from the Raycast Store](https://www.raycast.com/drakulavich/kesha-voice-kit) · source: [`raycast/`](raycast/).
 - **Programmatic API** — `@drakulavich/kesha-voice-kit/core` for use inside a Bun program. See [docs/api.md](docs/api.md).
 
 ## More

package/completions/kesha.bash

@@ -28,7 +28,7 @@ _kesha_completion() {
     record) opts="--help -h --out --max-seconds --debug" ;;
     say) opts="--help -h --voice --lang --out --rate --list-voices --ssml --format --bitrate --sample-rate --no-expand-abbrev --verbose --debug" ;;
     stats) opts="--help -h --format" ;;
-    status) opts="--help -h --disk" ;;
+    status) opts="--help -h --disk --json" ;;
     support-bundle) opts="--help -h --output --include-logs" ;;
     *) opts="--help -h --version -v --json --toon --timestamps --speakers --include-errors --verbose --format --lang --debug --vad --no-vad --quiet --no-color" ;;
   esac

package/completions/kesha.fish

@@ -42,7 +42,7 @@ complete -c kesha -n '__fish_seen_subcommand_from init' -l onnx -d 'Preselect ON
 complete -c kesha -n '__fish_seen_subcommand_from init' -l no-cache -d 'Re-download even if cached'
 complete -c kesha -n '__fish_seen_subcommand_from init' -l plan -d 'Show the selected install plan without downloading'
 complete -c kesha -n '__fish_seen_subcommand_from init' -l yes -d 'Accept defaults and run without prompts'
-complete -c kesha -n '__fish_seen_subcommand_from init' -l tts -d 'Preselect TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)'
+complete -c kesha -n '__fish_seen_subcommand_from init' -l tts -d 'Preselect TTS models (English; more languages via kesha install --tts <langs>)'
 complete -c kesha -n '__fish_seen_subcommand_from init' -l vad -d 'Preselect Silero VAD (~2.3MB) for long-audio preprocessing'
 complete -c kesha -n '__fish_seen_subcommand_from init' -l diarize -d 'Preselect Sortformer speaker diarization (~245MB, darwin-arm64 only)'
 complete -c kesha -n '__fish_seen_subcommand_from install' -l help -d 'Show help'
@@ -51,7 +51,7 @@ complete -c kesha -n '__fish_seen_subcommand_from install' -l coreml -d 'Force C
 complete -c kesha -n '__fish_seen_subcommand_from install' -l onnx -d 'Force ONNX backend'
 complete -c kesha -n '__fish_seen_subcommand_from install' -l no-cache -d 'Re-download even if cached'
 complete -c kesha -n '__fish_seen_subcommand_from install' -l plan -d 'Show download, disk, and warm-up plan without changing local state'
-complete -c kesha -n '__fish_seen_subcommand_from install' -l tts -d 'Also install TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)'
+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 logs' -l help -d 'Show help'
@@ -86,6 +86,7 @@ complete -c kesha -n '__fish_seen_subcommand_from stats' -l format -r -d 'Export
 complete -c kesha -n '__fish_seen_subcommand_from status' -l help -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from status' -s h -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from status' -l disk -d 'Include recursive cache disk usage'
+complete -c kesha -n '__fish_seen_subcommand_from status' -l json -d 'Output status as JSON'
 complete -c kesha -n '__fish_seen_subcommand_from support-bundle' -l help -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from support-bundle' -s h -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from support-bundle' -l output -r -d 'Write archive to this .tar.gz path'

package/completions/kesha.zsh

@@ -62,7 +62,7 @@ _kesha() {
         '--no-cache[Re-download even if cached]' \
         '--plan[Show the selected install plan without downloading]' \
         '--yes[Accept defaults and run without prompts]' \
-        '--tts[Preselect TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)]' \
+        '--tts[Preselect TTS models (English; more languages via kesha install --tts <langs>)]' \
         '--vad[Preselect Silero VAD (~2.3MB) for long-audio preprocessing]' \
         '--diarize[Preselect Sortformer speaker diarization (~245MB, darwin-arm64 only)]'
       ;;
@@ -73,7 +73,7 @@ _kesha() {
         '--onnx[Force ONNX backend]' \
         '--no-cache[Re-download even if cached]' \
         '--plan[Show download, disk, and warm-up plan without changing local state]' \
-        '--tts[Also install TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)]' \
+        '--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)]'
       ;;
@@ -121,7 +121,8 @@ _kesha() {
     status)
       _arguments '--help[Show help]' \
         '-h[Show help]' \
-        '--disk[Include recursive cache disk usage]'
+        '--disk[Include recursive cache disk usage]' \
+        '--json[Output status as JSON]'
       ;;
     support-bundle)
       _arguments '--help[Show help]' \

package/docs/product-positioning.md

@@ -60,19 +60,28 @@ The product promise is not "one model for every audio problem." The promise is a
 
 | Capability | macOS arm64 | macOS x64 | Linux x64 | Windows x64 | Nix path |
 |---|---|---|---|---|---|
-| STT | Supported, CoreML path | Not shipped | Supported, ONNX CPU path | Supported, ONNX CPU path | `aarch64-darwin`, `x86_64-linux` |
-| Audio language detection | Supported | Not shipped | Supported | Supported | Supported where the flake builds |
-| VAD | Supported with `kesha install --vad` | Not shipped | Supported with `kesha install --vad` | Supported with `kesha install --vad` | Supported where the engine path includes VAD assets |
-| TTS: English Kokoro | Supported, FluidAudio/CoreML in release builds | Not shipped | Supported, ONNX path | Supported, ONNX path | Supported except where noted in `docs/nix-install.md` |
-| TTS: Russian Vosk-TTS | Supported | Not shipped | Supported | Supported | Supported except where noted in `docs/nix-install.md` |
+| STT | Supported, CoreML path | Not shipped | Supported, ONNX CPU path | Blocked at install (#216) | `aarch64-darwin`, `x86_64-linux` |
+| Audio language detection | Supported | Not shipped | Supported | Blocked at install (#216) | Supported where the flake builds |
+| VAD | Supported with `kesha install --vad` | Not shipped | Supported with `kesha install --vad` | Blocked at install (#216) | Supported where the engine path includes VAD assets |
+| TTS: English Kokoro | Supported, FluidAudio/CoreML in release builds | Not shipped | Supported, ONNX path | Blocked at install (#216) | Supported except where noted in `docs/nix-install.md` |
+| TTS: Russian Vosk-TTS | Supported | Not shipped | Supported | Blocked at install (#216) | Supported except where noted in `docs/nix-install.md` |
 | macOS system voices | Supported | Not shipped | Not applicable | Not applicable | Supported on `aarch64-darwin` |
 | Speaker diarization | Preview, darwin-arm64 only | Not supported | Not supported | Not supported | Not wired into the Nix build yet |
 | Raycast extension | Supported | Not shipped | Not applicable | Not applicable | Not applicable |
-| OpenClaw integration | Supported through CLI route | Not shipped | Supported through CLI route | Supported through CLI route | Use the installed `kesha` command from the chosen path |
-| Hermes Agent integration | Supported through command providers | Not shipped | Supported through command providers | Supported through command providers | Use the installed `kesha` command from the chosen path |
+| OpenClaw integration | Supported through CLI route | Not shipped | Supported through CLI route | Blocked at install (#216) | Use the installed `kesha` command from the chosen path |
+| Hermes Agent integration | Supported through command providers | Not shipped | Supported through command providers | Blocked at install (#216) | Use the installed `kesha` command from the chosen path |
 
 `macOS x64` means Intel Macs. Kesha does not currently publish a `darwin-x64` engine binary, so Intel Macs are intentionally marked as not shipped rather than implied to use the ONNX fallback.
 
+`Windows x64` shows "Blocked at install" because the CLI's install step
+refuses to run on Windows, not because no binary exists — `build-engine.yml`
+builds and publishes `kesha-engine-windows-x64.exe` with every release. The
+Vosk-TTS native dependency trips MSVC at link time, so the CLI blocks the
+install client-side rather than shipping a broken engine. See
+[issue #216](https://github.com/drakulavich/kesha-voice-kit/issues/216) for
+the underlying failure and the v1.4.x workaround; the toolkit is unusable on
+Windows until that lands.
+
 ## When to choose something else
 
 Use a hosted transcription provider when you need managed uptime, centralized audit logs, team permissions, or no local model cache. Use a streaming ASR stack when partial transcripts during a live call matter more than local-first batch reliability. Use a domain-specific ASR model when medical, legal, or noisy industrial audio quality is the primary requirement.

package/man/kesha.1

@@ -112,7 +112,7 @@ Show the selected install plan without downloading
 Accept defaults and run without prompts
 .TP
 .B \-\-tts
-Preselect TTS models (Kokoro EN + Vosk\-TTS RU, ~990MB)
+Preselect TTS models (English; more languages via kesha install \-\-tts <langs>)
 .TP
 .B \-\-vad
 Preselect Silero VAD (~2.3MB) for long\-audio preprocessing
@@ -134,7 +134,7 @@ Re\-download even if cached
 Show download, disk, and warm\-up plan without changing local state
 .TP
 .B \-\-tts
-Also install TTS models (Kokoro EN + Vosk\-TTS RU, ~990MB)
+Also install TTS models (English only; add codes for more, e.g. \-\-tts en ru (preview sizes: kesha install \-\-plan))
 .TP
 .B \-\-vad
 Also install Silero VAD (~2.3MB) for long\-audio preprocessing
@@ -200,6 +200,9 @@ Export format: json | csv
 .TP
 .B \-\-disk
 Include recursive cache disk usage
+.TP
+.B \-\-json
+Output status as JSON
 .SS support-bundle
 .TP
 .B \-\-output

package/model-plan.json

@@ -0,0 +1,43 @@
+{
+  "asr": [
+    { "relPath": "models/parakeet-tdt-v3/encoder-model.onnx", "sizeBytes": 41770866 },
+    { "relPath": "models/parakeet-tdt-v3/encoder-model.onnx.data", "sizeBytes": 2435420160 },
+    { "relPath": "models/parakeet-tdt-v3/decoder_joint-model.onnx", "sizeBytes": 72520893 },
+    { "relPath": "models/parakeet-tdt-v3/nemo128.onnx", "sizeBytes": 139764 },
+    { "relPath": "models/parakeet-tdt-v3/vocab.txt", "sizeBytes": 93939 }
+  ],
+  "langId": [
+    { "relPath": "models/lang-id-ecapa/lang-id-ecapa.onnx", "sizeBytes": 759814 },
+    { "relPath": "models/lang-id-ecapa/lang-id-ecapa.onnx.data", "sizeBytes": 85327872 },
+    { "relPath": "models/lang-id-ecapa/labels.json", "sizeBytes": 646 }
+  ],
+  "vad": [
+    { "relPath": "models/silero-vad/silero_vad.onnx", "sizeBytes": 2327524 }
+  ],
+  "g2pCharsiu": [
+    { "relPath": "models/g2p/byt5-tiny/encoder_model.onnx", "sizeBytes": 12478704 },
+    { "relPath": "models/g2p/byt5-tiny/decoder_model.onnx", "sizeBytes": 11983268 },
+    { "relPath": "models/g2p/byt5-tiny/decoder_with_past_model.onnx", "sizeBytes": 5427260 }
+  ],
+  "kokoroGraph": { "relPath": "models/kokoro-82m/model.onnx", "sizeBytes": 325532387 },
+  "kokoroVoices": {
+    "en": { "relPath": "models/kokoro-82m/voices/am_michael.bin", "sizeBytes": 522240 },
+    "es": { "relPath": "models/kokoro-82m/voices/em_alex.bin", "sizeBytes": 522240 },
+    "fr": { "relPath": "models/kokoro-82m/voices/ff_siwis.bin", "sizeBytes": 522240 },
+    "it": { "relPath": "models/kokoro-82m/voices/im_nicola.bin", "sizeBytes": 522240 },
+    "pt": { "relPath": "models/kokoro-82m/voices/pm_alex.bin", "sizeBytes": 522240 }
+  },
+  "voskRu": [
+    { "relPath": "models/vosk-ru/model.onnx", "sizeBytes": 179314533 },
+    { "relPath": "models/vosk-ru/dictionary", "sizeBytes": 101431118 },
+    { "relPath": "models/vosk-ru/config.json", "sizeBytes": 1518 },
+    { "relPath": "models/vosk-ru/bert/model.onnx", "sizeBytes": 654361598 },
+    { "relPath": "models/vosk-ru/bert/vocab.txt", "sizeBytes": 1780720 }
+  ],
+  "diarize": [
+    { "relPath": "models/diarize/SortformerNvidiaLow_v2.mlpackage/Manifest.json", "sizeBytes": 617 },
+    { "relPath": "models/diarize/SortformerNvidiaLow_v2.mlpackage/Data/com.apple.CoreML/model.mlmodel", "sizeBytes": 7080357 },
+    { "relPath": "models/diarize/SortformerNvidiaLow_v2.mlpackage/Data/com.apple.CoreML/weights/0-weight.bin", "sizeBytes": 5930400 },
+    { "relPath": "models/diarize/SortformerNvidiaLow_v2.mlpackage/Data/com.apple.CoreML/weights/1-weight.bin", "sizeBytes": 232161600 }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.24.6",
+  "version": "1.25.0",
   "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": {
@@ -15,6 +15,7 @@
     "completions/",
     "man/",
     "src/",
+    "model-plan.json",
     "package.json",
     "tsconfig.json",
     "openclaw.plugin.json",
@@ -38,14 +39,14 @@
     }
   },
   "keshaEngine": {
-    "version": "1.24.6"
+    "version": "1.24.7"
   },
   "scripts": {
-    "test": "bun test",
-    "test:watch": "bun test --watch",
-    "test:unit": "bun test tests/unit/",
-    "test:cli-fast": "bun test tests/unit/ tests/integration/cli-contracts.test.ts tests/integration/e2e-cli.test.ts tests/integration/say.test.ts",
-    "test:integration": "bun test tests/integration/",
+    "test": "bun test --timeout 30000",
+    "test:watch": "bun test --timeout 30000 --watch",
+    "test:unit": "bun test --timeout 30000 tests/unit/",
+    "test:cli-fast": "bun test --timeout 30000 tests/unit/ tests/integration/cli-contracts.test.ts tests/integration/e2e-cli.test.ts tests/integration/say.test.ts",
+    "test:integration": "bun test --timeout 30000 tests/integration/",
     "coverage:ts": "bun run test:cli-fast --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir=coverage/ts",
     "coverage:check:ts": "bun .github/scripts/check-coverage.ts --preset=ts --lcov=coverage/ts/lcov.info --summary=coverage/ts/summary.md",
     "coverage:rust": "mkdir -p coverage/rust && cd rust && cargo llvm-cov nextest --features tts --lcov --output-path ../coverage/rust/lcov.info",
@@ -54,6 +55,7 @@
     "lint": "bunx tsc --noEmit",
     "check": "bun run lint && bun run check:versions && bun run test:cli-fast",
     "check:workflows": "bun .github/scripts/check-workflows.ts",
+    "check:specs": "bunx @fission-ai/openspec@1.4.1 validate --specs --strict",
     "check:release-manifest": "bun .github/scripts/release-manifest.mjs --check",
     "check:versions": "bun .github/scripts/check-versions.ts"
   },
@@ -91,7 +93,7 @@
   "dependencies": {
     "@clack/prompts": "^1.5.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@toon-format/toon": "^2.1.0",
+    "@toon-format/toon": "^4.1.0",
     "citty": "^0.2.2",
     "fastest-levenshtein": "^1.0.16",
     "picocolors": "^1.1.1",

package/src/cli/action-result.ts

@@ -0,0 +1,18 @@
+import { log } from "../log";
+
+export type ActionMessage = { level: "success" | "info" | "warn"; text: string };
+
+export type ActionResult =
+  | { ok: true; messages: ActionMessage[]; stdout?: string }
+  | { ok: false; error: string; hint?: string };
+
+/** Renders an action's messages, writing `stdout` verbatim; a rejected action exits 2. */
+export function emitActionResult(result: ActionResult): void {
+  if (!result.ok) {
+    log.error(result.error);
+    if (result.hint) log.warn(result.hint);
+    process.exit(2);
+  }
+  for (const message of result.messages) log[message.level](message.text);
+  if (result.stdout !== undefined) process.stdout.write(result.stdout);
+}

package/src/cli/command-session.ts

@@ -0,0 +1,86 @@
+import { createDiagnosticLogSession } from "../diagnostic-log";
+import type {
+  DiagnosticLogFields,
+  DiagnosticLogSession,
+  DiagnosticSessionStatus,
+} from "../diagnostic-log";
+import { errorMessage } from "../error-utils";
+import { log } from "../log";
+import { createStatsRecorder } from "../stats";
+import type { StatsCommandName, StatsRecorder } from "../stats";
+
+export interface CommandSession {
+  readonly stats: StatsRecorder;
+  readonly diagnosticLog: DiagnosticLogSession;
+}
+
+export interface CommandOutcome {
+  status: DiagnosticSessionStatus;
+  itemCount: number;
+  /** Merged into the `command.finish` event alongside `command` and `status`. */
+  finishFields?: DiagnosticLogFields;
+  /** Exit code the caller should terminate with; omitted means "don't exit". */
+  exitCode?: number;
+}
+
+export interface CommandSessionFactories {
+  createStats: (command: StatsCommandName) => StatsRecorder;
+  createDiagnosticLog: () => DiagnosticLogSession;
+}
+
+const defaultFactories: CommandSessionFactories = {
+  createStats: createStatsRecorder,
+  createDiagnosticLog: createDiagnosticLogSession,
+};
+
+/** Runs one CLI command's body between `command.start` / `command.finish`, closing both recorders exactly once; `body` reports failure by returning a {@link CommandOutcome}, never by exiting. */
+export async function runCommandSession(
+  command: StatsCommandName,
+  startFields: DiagnosticLogFields,
+  body: (session: CommandSession) => Promise<CommandOutcome>,
+  factories: CommandSessionFactories = defaultFactories,
+): Promise<CommandOutcome> {
+  const session: CommandSession = {
+    stats: factories.createStats(command),
+    diagnosticLog: factories.createDiagnosticLog(),
+  };
+  session.diagnosticLog.event("command.start", { command, ...startFields });
+
+  let outcome: CommandOutcome;
+  try {
+    outcome = await body(session);
+  } catch (err) {
+    closeSessionQuietly(session, command, { status: "failed", itemCount: 0 });
+    throw err;
+  }
+
+  // A flush error must not displace a failure the command already has to report (Greptile P1/P2 on #607).
+  if (outcome.status === "failed") {
+    closeSessionQuietly(session, command, outcome);
+  } else {
+    closeSession(session, command, outcome);
+  }
+  return outcome;
+}
+
+function closeSessionQuietly(
+  session: CommandSession,
+  command: StatsCommandName,
+  outcome: CommandOutcome,
+): void {
+  try {
+    closeSession(session, command, outcome);
+  } catch (err) {
+    log.debug(`command session cleanup failed: ${errorMessage(err)}`);
+  }
+}
+
+function closeSession(session: CommandSession, command: StatsCommandName, outcome: CommandOutcome): void {
+  session.diagnosticLog.event("command.finish", {
+    command,
+    status: outcome.status,
+    ...outcome.finishFields,
+  });
+  session.stats.finish(outcome.status, outcome.itemCount);
+  session.diagnosticLog.finish(outcome.status);
+}

package/src/cli/context.ts

@@ -0,0 +1,108 @@
+import { log, setColorEnabled } from "../log";
+
+/** The global flags resolved before citty, so every command sees the same decision. */
+export interface CliContext {
+  quiet: boolean;
+  disableColor: boolean;
+}
+
+export interface ResolvedCliContext extends CliContext {
+  /** `rawArgs` with the global flag tokens removed, ready to hand to citty. */
+  rawArgs: string[];
+}
+
+// Falsey grammar shared by --no-color, --quiet, and CI. Mirrors KESHA_DEBUG so
+// `CI=false`/`CI=0` and `--no-color=false` opt back in.
+const FALSEY_VALUES = new Set(["", "0", "false", "no", "off"]);
+function isFalsey(v: string): boolean {
+  return FALSEY_VALUES.has(v.trim().toLowerCase());
+}
+
+/** True when NO_COLOR came from the user's environment, so re-enabling colors must not clear it. */
+export const USER_FORCED_NO_COLOR =
+  process.env.NO_COLOR !== undefined && !isFalsey(process.env.NO_COLOR);
+
+/**
+ * Strip a boolean global flag out of rawArgs so citty never sees it. Matches
+ * any of `names` bare (sets the flag) and the `--name=<value>` form for the
+ * long names (`<falsey>` explicitly turns the flag back off).
+ */
+function stripBooleanFlag(
+  rawArgs: string[],
+  names: string[],
+): { value: boolean; rawArgs: string[] } {
+  const valuedPrefixes = names.filter((n) => n.startsWith("--")).map((n) => `${n}=`);
+  let value = false;
+  const cleaned: string[] = [];
+  for (const arg of rawArgs) {
+    if (names.includes(arg)) {
+      value = true;
+    } else if (valuedPrefixes.some((prefix) => arg.startsWith(prefix))) {
+      value = !isFalsey(arg.slice(arg.indexOf("=") + 1));
+    } else {
+      cleaned.push(arg);
+    }
+  }
+  return { value, rawArgs: cleaned };
+}
+
+/**
+ * Decide whether ANSI colors should be disabled (#531) and return rawArgs with
+ * any `--no-color[=value]` token stripped so citty never sees it.
+ *
+ * Colors are disabled when `--no-color` (bare) or `--no-color=<truthy>` is
+ * passed, or when the environment looks like CI (`CI` set to a non-falsey value
+ * — GitHub Actions, GitLab, CircleCI, … export `CI=true`). `--no-color=false`
+ * and `CI=false`/`CI=0` explicitly opt back in.
+ */
+export function resolveColorMode(
+  rawArgs: string[],
+  env: { CI?: string } = process.env as { CI?: string },
+): { disableColor: boolean; rawArgs: string[] } {
+  const { value, rawArgs: cleaned } = stripBooleanFlag(rawArgs, ["--no-color"]);
+  const ci = env.CI !== undefined && !isFalsey(env.CI);
+  return { disableColor: value || ci, rawArgs: cleaned };
+}
+
+/**
+ * Detect `--quiet`/`-q` (and `--quiet=<value>`) and return rawArgs with the
+ * token stripped (#526). Resolved before citty — like `--no-color` — so quiet
+ * is global: it works for every command, not just the transcribe path, and a
+ * subcommand that doesn't declare it never sees the flag.
+ */
+export function resolveQuietMode(rawArgs: string[]): { quiet: boolean; rawArgs: string[] } {
+  const { value, rawArgs: cleaned } = stripBooleanFlag(rawArgs, ["--quiet", "-q"]);
+  return { quiet: value, rawArgs: cleaned };
+}
+
+/** Resolves every pre-citty global flag into one value, with the tokens stripped from rawArgs. */
+export function resolveCliContext(
+  rawArgs: string[],
+  env: { CI?: string } = process.env as { CI?: string },
+): ResolvedCliContext {
+  const color = resolveColorMode(rawArgs, env);
+  const quiet = resolveQuietMode(color.rawArgs);
+  return { quiet: quiet.quiet, disableColor: color.disableColor, rawArgs: quiet.rawArgs };
+}
+
+/**
+ * Sync NO_COLOR with the resolved color decision so engine subprocesses inherit
+ * the right value. Separated from setColorEnabled so it can be tested without
+ * picocolors side-effects.
+ *
+ * Never clears a NO_COLOR the user exported before this process started.
+ */
+export function applyColorEnv(disableColor: boolean): void {
+  if (disableColor) {
+    process.env.NO_COLOR = "1";
+  } else if (!USER_FORCED_NO_COLOR) {
+    delete process.env.NO_COLOR;
+  }
+}
+
+/** Applies the context to the process-wide output sinks, writing every value so an earlier in-process run (unit tests, `kesha mcp`) can't leak its settings into a later one. */
+export function applyCliContext(context: CliContext): void {
+  setColorEnabled(!context.disableColor);
+  applyColorEnv(context.disableColor);
+  log.quietEnabled = context.quiet;
+}