@openparachute/vault 0.7.4 → 0.7.5-rc.4

package/src/transcription/models.ts

@@ -0,0 +1,187 @@
+/**
+ * The local-transcription model catalog (whisper.cpp era).
+ *
+ * ## Why this replaced the transcribe.cpp plan
+ *
+ * The 2026-07-03 ratification adopted transcribe.cpp as the local provider.
+ * That decision assumed a `transcribe-cli` binary would ship. It never did:
+ * v0.1.3 (2026-07-12, latest as of this writing) still publishes only
+ * `libtranscribe.{dylib,so}` + `libggml*` + `contract.json` in its release
+ * tarballs — the CLI is build-from-source — and its N-API binding crashes on
+ * Bun, so the in-process route is closed too. Four weeks and three releases
+ * after the ratification, `parachute-vault transcription install` still could
+ * not produce a runnable setup.
+ *
+ * whisper.cpp ships what transcribe.cpp doesn't: **prebuilt CLIs on both
+ * platforms**. `brew install whisper-cpp` (bottled for arm64 macOS) installs
+ * BOTH `whisper-cli` and `parakeet-cli`, and the Linux release tarballs carry
+ * the same two binaries. Models are prebuilt too — `ggml-org/parakeet-GGUF`
+ * and `ggerganov/whisper.cpp` — so nothing has to be converted, and no Python
+ * is involved anywhere.
+ *
+ * Note that handy-computer's own GGUFs (68 repos, 16 model families) are NOT
+ * format-compatible with whisper.cpp's `parakeet-cli` — verified: loading
+ * `parakeet-tdt-0.6b-v3-Q4_K_M.gguf` fails with "failed to load Parakeet
+ * model". They are two ecosystems, and this catalog lives in whisper.cpp's.
+ * If transcribe.cpp ships a CLI later, its 16-family catalog becomes a
+ * genuinely attractive swap — the provider seam is where that would land.
+ *
+ * ## Why Parakeet is the default
+ *
+ * On the Open ASR Leaderboard, Parakeet TDT 0.6b v3 beats Whisper large-v3 on
+ * average WER (6.32% vs 7.44%) at roughly a third of the parameters, and runs
+ * substantially faster. The property that matters most for voice memos:
+ * **Parakeet does not hallucinate during silence**, which is Whisper's
+ * best-known failure mode and precisely what a recording with pauses triggers.
+ *
+ * The trade-off is language coverage — Parakeet v3 handles 25 European
+ * languages, Whisper 99 — which is why the Whisper models stay in the catalog
+ * rather than being dropped. A vault whose audio isn't in Parakeet's range
+ * picks a Whisper model and everything else works the same.
+ */
+
+/**
+ * Which whisper.cpp CLI runs a given model. The two binaries take slightly
+ * different flags and read different model formats, so this is not cosmetic —
+ * it selects the argv builder and the readiness probe.
+ */
+export type TranscriptionEngine = "parakeet" | "whisper";
+
+/** A model an operator can pick, with everything needed to fetch and run it. */
+export interface TranscriptionModel {
+  /** Stable id — what `TRANSCRIPTION_MODEL` is set to. */
+  id: string;
+  /** Short label for the admin UI. */
+  label: string;
+  /** Which CLI runs it. */
+  engine: TranscriptionEngine;
+  /** Download URL for the ggml `.bin`. */
+  url: string;
+  /** On-disk filename under `<root>/transcription/models/`. */
+  filename: string;
+  /** Approximate download size, MB. Real measured values, not estimates. */
+  sizeMb: number;
+  /**
+   * Rough floor of usable system RAM, MB. Used to pick a sane default on a
+   * given box and to warn when an operator picks something their machine will
+   * struggle with — NOT a hard refusal; an operator may know better.
+   */
+  minRamMb: number;
+  /** One line for the picker — what this trades away. */
+  note: string;
+}
+
+/**
+ * The catalog, smallest first.
+ *
+ * Sizes are measured from the HuggingFace API, not estimated. The Parakeet
+ * entries come from `ggml-org/parakeet-GGUF` (whisper.cpp's own conversions,
+ * which is what makes them loadable by `parakeet-cli`); the Whisper entries
+ * from `ggerganov/whisper.cpp`, the canonical source `download-ggml-model.sh`
+ * uses.
+ */
+export const TRANSCRIPTION_MODELS: readonly TranscriptionModel[] = [
+  {
+    id: "whisper-tiny.en",
+    label: "Whisper Tiny (English)",
+    engine: "whisper",
+    url: "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.en.bin",
+    filename: "ggml-tiny.en.bin",
+    sizeMb: 74,
+    minRamMb: 1024,
+    note: "Smallest option. Noticeably less accurate — for very constrained boxes.",
+  },
+  {
+    id: "whisper-base.en",
+    label: "Whisper Base (English)",
+    engine: "whisper",
+    url: "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin",
+    filename: "ggml-base.en.bin",
+    sizeMb: 141,
+    minRamMb: 2048,
+    note: "Small and quick. English only.",
+  },
+  {
+    id: "parakeet-tdt-0.6b-v3-q4",
+    label: "Parakeet TDT 0.6b v3 (q4)",
+    engine: "parakeet",
+    url: "https://huggingface.co/ggml-org/parakeet-GGUF/resolve/main/ggml-parakeet-tdt-0.6b-v3-q4_0.bin",
+    filename: "ggml-parakeet-tdt-0.6b-v3-q4_0.bin",
+    sizeMb: 339,
+    minRamMb: 2048,
+    note: "Parakeet at the smallest quantization. 25 European languages.",
+  },
+  {
+    id: "parakeet-tdt-0.6b-v3",
+    label: "Parakeet TDT 0.6b v3 (recommended)",
+    engine: "parakeet",
+    url: "https://huggingface.co/ggml-org/parakeet-GGUF/resolve/main/ggml-parakeet-tdt-0.6b-v3-q4_k.bin",
+    filename: "ggml-parakeet-tdt-0.6b-v3-q4_k.bin",
+    sizeMb: 396,
+    minRamMb: 3072,
+    note: "Best accuracy-per-byte, and doesn't hallucinate on silence. 25 European languages.",
+  },
+  {
+    id: "whisper-small.en",
+    label: "Whisper Small (English)",
+    engine: "whisper",
+    url: "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.en.bin",
+    filename: "ggml-small.en.bin",
+    sizeMb: 465,
+    minRamMb: 4096,
+    note: "More accurate Whisper. English only.",
+  },
+  {
+    id: "parakeet-tdt-0.6b-v3-q8",
+    label: "Parakeet TDT 0.6b v3 (q8)",
+    engine: "parakeet",
+    url: "https://huggingface.co/ggml-org/parakeet-GGUF/resolve/main/ggml-parakeet-tdt-0.6b-v3-q8_0.bin",
+    filename: "ggml-parakeet-tdt-0.6b-v3-q8_0.bin",
+    sizeMb: 638,
+    minRamMb: 6144,
+    note: "Parakeet at higher precision. Marginal gain over q4_k for most audio.",
+  },
+  {
+    id: "whisper-large-v3-turbo",
+    label: "Whisper Large v3 Turbo (multilingual)",
+    engine: "whisper",
+    url: "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin",
+    filename: "ggml-large-v3-turbo.bin",
+    sizeMb: 1549,
+    minRamMb: 8192,
+    note: "All 99 Whisper languages. Pick this when Parakeet's 25 aren't enough.",
+  },
+] as const;
+
+/**
+ * The default model when nothing is configured.
+ *
+ * Parakeet q4_k rather than the smallest option: at 396 MB it is a reasonable
+ * download on any machine that can host a vault, and choosing accuracy by
+ * default is the right call for transcripts an operator will read months
+ * later. `pickDefaultModel` steps down on low-RAM boxes.
+ */
+export const DEFAULT_MODEL_ID = "parakeet-tdt-0.6b-v3";
+
+/** Look a model up by id. `undefined` for an unknown id. */
+export function findModel(id: string): TranscriptionModel | undefined {
+  return TRANSCRIPTION_MODELS.find((m) => m.id === id);
+}
+
+/**
+ * Pick a sensible default for a machine with `totalRamMb`.
+ *
+ * Walks DOWN from the default to the largest model the box comfortably fits,
+ * so a small VPS gets something that runs rather than something that swaps.
+ * Never returns undefined — the smallest entry is the floor, and a box too
+ * small even for that has bigger problems than model choice.
+ */
+export function pickDefaultModel(totalRamMb: number): TranscriptionModel {
+  const preferred = findModel(DEFAULT_MODEL_ID);
+  if (preferred && totalRamMb >= preferred.minRamMb) return preferred;
+  // Largest model that fits, else the smallest we have.
+  const fits = TRANSCRIPTION_MODELS.filter((m) => totalRamMb >= m.minRamMb);
+  return fits.length > 0
+    ? fits.reduce((a, b) => (b.sizeMb > a.sizeMb ? b : a))
+    : TRANSCRIPTION_MODELS[0]!;
+}

package/src/transcription/providers/whisper-cpp.test.ts

@@ -0,0 +1,218 @@
+/**
+ * The whisper-cpp provider.
+ *
+ * Mostly driven through the `spawn` seam so no binary runs — but the last
+ * block is a LIVE test that shells the real `parakeet-cli`/`whisper-cli` and
+ * transcribes real audio when they're installed. That block is what actually
+ * proves the argv shape and the stdout contract against whisper.cpp itself;
+ * every mocked test above it is only as true as the fixtures. It skips
+ * cleanly on a machine without the binaries so CI stays green.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { TranscriptionError } from "../../../core/src/transcription/provider.ts";
+import { resolveCliBinary, resolveFfmpeg } from "../resolve-binary.ts";
+import {
+  buildCliArgs,
+  buildFfmpegArgs,
+  parseCliOutput,
+  WhisperCppProvider,
+  type WhisperCppProviderOpts,
+} from "./whisper-cpp.ts";
+import type { SpawnRunner } from "./transcribe-cpp.ts";
+
+const AUDIO = new Uint8Array([1, 2, 3, 4]);
+
+/** A provider wired to a scripted spawn; both paths "exist" by default. */
+function makeProvider(
+  spawn: SpawnRunner,
+  over: Partial<WhisperCppProviderOpts> = {},
+): WhisperCppProvider {
+  return new WhisperCppProvider({
+    binPath: "/bin/parakeet-cli",
+    engine: "parakeet",
+    modelPath: "/models/m.bin",
+    spawn,
+    existsImpl: () => true,
+    tmpDir: tmpdir(),
+    ...over,
+  });
+}
+
+/** Scripted runner: ffmpeg call first, CLI call second. */
+function scripted(ffmpeg: Partial<{ exitCode: number; stderr: string }>, cli: Partial<{ exitCode: number; stdout: string; stderr: string }>): SpawnRunner {
+  let n = 0;
+  return async () => {
+    n += 1;
+    if (n === 1) return { exitCode: ffmpeg.exitCode ?? 0, stdout: "", stderr: ffmpeg.stderr ?? "" };
+    return { exitCode: cli.exitCode ?? 0, stdout: cli.stdout ?? "", stderr: cli.stderr ?? "" };
+  };
+}
+
+describe("buildCliArgs", () => {
+  test("parakeet: -np, no -nt (it has no such flag)", () => {
+    const a = buildCliArgs("parakeet", "/b/parakeet-cli", "/m.bin", "/a.wav");
+    expect(a).toEqual(["/b/parakeet-cli", "-m", "/m.bin", "-f", "/a.wav", "-np"]);
+    expect(a).not.toContain("-nt");
+  });
+
+  test("whisper: adds -nt, or every line arrives timestamp-wrapped", () => {
+    const a = buildCliArgs("whisper", "/b/whisper-cli", "/m.bin", "/a.wav");
+    expect(a).toEqual(["/b/whisper-cli", "-m", "/m.bin", "-f", "/a.wav", "-np", "-nt"]);
+  });
+});
+
+describe("buildFfmpegArgs", () => {
+  test("always forces 16 kHz mono — an incoming WAV's rate can't be trusted", () => {
+    const a = buildFfmpegArgs("ffmpeg", "/in.webm", "/out.wav");
+    expect(a).toContain("-ar");
+    expect(a[a.indexOf("-ar") + 1]).toBe("16000");
+    expect(a).toContain("-ac");
+    expect(a[a.indexOf("-ac") + 1]).toBe("1");
+    expect(a).toContain("-nostdin");
+  });
+});
+
+describe("parseCliOutput", () => {
+  test("trims the leading whitespace both CLIs emit", () => {
+    expect(parseCliOutput("\n And so my fellow Americans.\n")).toBe(
+      "And so my fellow Americans.",
+    );
+  });
+  test("empty stdout → empty string", () => {
+    expect(parseCliOutput("   \n  ")).toBe("");
+  });
+});
+
+describe("availability", () => {
+  test("missing binary names the binary AND how to get it", async () => {
+    const p = makeProvider(scripted({}, {}), { existsImpl: (x) => x !== "/bin/parakeet-cli" });
+    const a = await p.available();
+    expect(a.ok).toBe(false);
+    expect(a.reason).toMatch(/parakeet-cli/);
+    expect(a.reason).toMatch(/transcription install|brew install/);
+  });
+
+  test("missing model is reported as a DIFFERENT problem than a missing binary", async () => {
+    const p = makeProvider(scripted({}, {}), { existsImpl: (x) => x !== "/models/m.bin" });
+    const a = await p.available();
+    expect(a.ok).toBe(false);
+    expect(a.reason).toMatch(/model file/);
+    expect(a.reason).not.toMatch(/parakeet-cli binary/);
+  });
+
+  test("both present → ok", async () => {
+    expect((await makeProvider(scripted({}, {})).available()).ok).toBe(true);
+  });
+});
+
+describe("transcribe — error taxonomy", () => {
+  test("not ready → terminal missing_provider, and never spawns", async () => {
+    let spawned = false;
+    const p = makeProvider(
+      async () => {
+        spawned = true;
+        return { exitCode: 0, stdout: "", stderr: "" };
+      },
+      { existsImpl: () => false },
+    );
+    await expect(p.transcribe({ audio: AUDIO, mimeType: "audio/webm" } as never)).rejects.toThrow(
+      TranscriptionError,
+    );
+    expect(spawned).toBe(false);
+  });
+
+  test("ffmpeg missing (127) → TERMINAL, with an install hint", async () => {
+    const p = makeProvider(scripted({ exitCode: 127 }, {}));
+    let caught: TranscriptionError | undefined;
+    try {
+      await p.transcribe({ audio: AUDIO, mimeType: "audio/webm" } as never);
+    } catch (e) {
+      caught = e as TranscriptionError;
+    }
+    expect(caught?.code).toBe("ffmpeg_missing");
+    expect(caught?.retriable).toBe(false);
+    expect(caught?.message).toMatch(/brew install ffmpeg|apt install ffmpeg/);
+  });
+
+  test("undecodable audio → TERMINAL transcode_failed (a retry can't help)", async () => {
+    const p = makeProvider(scripted({ exitCode: 1, stderr: "moov atom not found" }, {}), {
+      // wav never materialises
+      existsImpl: (x) => !x.endsWith(".wav"),
+    });
+    let caught: TranscriptionError | undefined;
+    try {
+      await p.transcribe({ audio: AUDIO, mimeType: "audio/webm" } as never);
+    } catch (e) {
+      caught = e as TranscriptionError;
+    }
+    expect(caught?.code).toBe("transcode_failed");
+    expect(caught?.retriable).toBe(false);
+  });
+
+  test("CLI non-zero → RETRIABLE (could be a transient resource blip)", async () => {
+    const p = makeProvider(scripted({}, { exitCode: 3, stderr: "out of memory" }));
+    let caught: TranscriptionError | undefined;
+    try {
+      await p.transcribe({ audio: AUDIO, mimeType: "audio/webm" } as never);
+    } catch (e) {
+      caught = e as TranscriptionError;
+    }
+    expect(caught?.code).toBe("whisper_cli_error");
+    expect(caught?.retriable).toBe(true);
+  });
+
+  test("empty transcript → plain retriable Error", async () => {
+    const p = makeProvider(scripted({}, { stdout: "   " }));
+    await expect(
+      p.transcribe({ audio: AUDIO, mimeType: "audio/webm" } as never),
+    ).rejects.toThrow(/no text/i);
+  });
+
+  test("success returns the trimmed transcript", async () => {
+    const p = makeProvider(scripted({}, { stdout: "\n Hello there.\n" }));
+    const r = await p.transcribe({ audio: AUDIO, mimeType: "audio/webm" } as never);
+    expect(r.text).toBe("Hello there.");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// LIVE — shells the real binaries. Skipped when they aren't installed.
+//
+// Everything above is only as true as its fixtures. This is the block that
+// proves the argv shape and the stdout contract against whisper.cpp itself.
+// ---------------------------------------------------------------------------
+const liveBin = resolveCliBinary("parakeet") ?? resolveCliBinary("whisper");
+const liveFfmpeg = resolveFfmpeg();
+const liveEngine = resolveCliBinary("parakeet") ? "parakeet" : "whisper";
+/** A real ggml model, if the operator running tests happens to have one. */
+const liveModel = [
+  join(tmpdir(), "pk.bin"),
+  join(tmpdir(), "ggml-base.en.bin"),
+].find((p) => existsSync(p));
+
+const canRunLive = Boolean(liveBin && liveFfmpeg && liveModel);
+
+describe.skipIf(!canRunLive)("LIVE — real whisper.cpp binary", () => {
+  test("transcribes real audio end to end", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "wcpp-live-"));
+    try {
+      // A short silent WAV is enough to prove the pipeline runs and the
+      // contract holds; we assert on mechanics, not on transcript content.
+      const provider = new WhisperCppProvider({
+        binPath: liveBin,
+        engine: liveEngine as "parakeet" | "whisper",
+        modelPath: liveModel,
+        ffmpegPath: liveFfmpeg,
+        tmpDir: dir,
+        timeoutMs: 120_000,
+      });
+      expect((await provider.available()).ok).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/transcription/providers/whisper-cpp.ts

@@ -0,0 +1,241 @@
+/**
+ * `whisper-cpp` — the local, no-Python transcription provider.
+ *
+ * Drives whisper.cpp's prebuilt CLIs as a subprocess: `parakeet-cli` for
+ * Parakeet models, `whisper-cli` for Whisper ones. Which binary runs is derived
+ * from the chosen model's `engine` (see `../models.ts`), so an operator picks a
+ * MODEL and never has to think about binaries.
+ *
+ * Replaces the `transcribe-cpp` provider, whose CLI never shipped — see the
+ * `models.ts` header for that history. Structurally this is the same shape:
+ * transcode → subprocess → parse → map errors. What changed is that the binary
+ * on the other end actually exists.
+ *
+ * ## The audio path — ffmpeg is still required
+ *
+ * `parakeet-cli` advertises flac/mp3/ogg/wav, which looks like it removes the
+ * ffmpeg dependency. It doesn't, for the case that matters: browser voice
+ * capture produces **webm/opus**, which is on neither CLI's list. And
+ * `whisper-cli` strictly wants 16 kHz mono WAV — a 44.1 kHz WAV exits non-zero.
+ *
+ * So we ALWAYS transcode through `ffmpeg -ar 16000 -ac 1` first, even when the
+ * input is already `.wav`, because an incoming WAV's sample rate can't be
+ * trusted. One path, no format sniffing, no class of bug where a particular
+ * recorder's output silently fails.
+ *
+ * ## Reading the output
+ *
+ * Both CLIs, run with `-np` (no prints), write the bare transcript to STDOUT
+ * and their backend chatter to STDERR. `whisper-cli` additionally needs `-nt`
+ * to suppress the `[00:00:00.000 --> ...]` timestamp prefixes. Verified against
+ * whisper.cpp 1.9.1: stdout is the transcript with leading whitespace and
+ * nothing else, so parsing is a trim.
+ *
+ * ## Error mapping (same terminal-vs-retriable contract as scribe-http)
+ *
+ *   - binary / model missing → non-retriable `missing_provider`; never spawns.
+ *   - ffmpeg not found → non-retriable `ffmpeg_missing`.
+ *   - ffmpeg non-zero → non-retriable `transcode_failed` (a re-run on the same
+ *     undecodable blob won't help).
+ *   - CLI non-zero → RETRIABLE `whisper_cli_error` (could be a transient
+ *     resource blip; a deterministic failure still terminates after
+ *     maxAttempts).
+ *   - empty stdout → plain `Error` (retriable), matching scribe-http's
+ *     "missing text field".
+ */
+
+import { randomUUID } from "crypto";
+import { existsSync } from "fs";
+import { unlink, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import {
+  TranscriptionError,
+  type ProviderAvailability,
+  type TranscribeInput,
+  type TranscribeResult,
+  type TranscriptionProvider,
+} from "../../../core/src/transcription/provider.ts";
+import type { TranscriptionEngine } from "../models.ts";
+import { defaultSpawnRunner, type SpawnRunner } from "./transcribe-cpp.ts";
+
+/** Local CPU inference on long audio can be slow; generous default. */
+const DEFAULT_TIMEOUT_MS = 600_000;
+
+export interface WhisperCppProviderOpts {
+  /** Path to `parakeet-cli` or `whisper-cli`. Undefined ⇒ unavailable. */
+  binPath?: string;
+  /** Which CLI `binPath` is — decides the argv shape. */
+  engine: TranscriptionEngine;
+  /** Path to the ggml model `.bin`. Undefined ⇒ unavailable. */
+  modelPath?: string;
+  /** ffmpeg binary (default "ffmpeg", resolved on PATH). */
+  ffmpegPath?: string;
+  /** Per-transcription timeout (ms). Default 600s. */
+  timeoutMs?: number;
+  /** Subprocess runner (tests inject a mock). */
+  spawn?: SpawnRunner;
+  /** Existence probe (tests inject). */
+  existsImpl?: (p: string) => boolean;
+  /** Scratch dir for temp audio. Default `os.tmpdir()`. */
+  tmpDir?: string;
+}
+
+/**
+ * Build the CLI argv for a transcription.
+ *
+ * `-np` silences backend logs on both. `whisper-cli` also needs `-nt` or every
+ * line arrives wrapped in `[00:00:00.000 --> 00:00:11.000]` timestamps.
+ * `parakeet-cli` has no `-nt` flag and doesn't print timestamps by default.
+ * Exported so a test pins the shape per engine.
+ */
+export function buildCliArgs(
+  engine: TranscriptionEngine,
+  binPath: string,
+  modelPath: string,
+  wavPath: string,
+): string[] {
+  const base = [binPath, "-m", modelPath, "-f", wavPath, "-np"];
+  return engine === "whisper" ? [...base, "-nt"] : base;
+}
+
+/** Build the ffmpeg transcode argv → 16 kHz mono WAV. Exported for tests. */
+export function buildFfmpegArgs(
+  ffmpegPath: string,
+  inputPath: string,
+  wavPath: string,
+): string[] {
+  return [ffmpegPath, "-nostdin", "-y", "-i", inputPath, "-ar", "16000", "-ac", "1", wavPath];
+}
+
+/**
+ * Extract the transcript from CLI stdout.
+ *
+ * With `-np` both binaries emit the bare transcript and nothing else, so this
+ * is a trim. It stays a named function rather than an inline `.trim()` because
+ * it is the contract with an external binary: if a future whisper.cpp adds a
+ * banner to stdout, this is the one place that has to learn about it, and the
+ * test that pins it is the one that fails.
+ */
+export function parseCliOutput(stdout: string): string {
+  return stdout.trim();
+}
+
+export class WhisperCppProvider implements TranscriptionProvider {
+  readonly name = "whisper-cpp";
+
+  private readonly binPath: string | undefined;
+  private readonly engine: TranscriptionEngine;
+  private readonly modelPath: string | undefined;
+  private readonly ffmpegPath: string;
+  private readonly timeoutMs: number;
+  private readonly spawn: SpawnRunner;
+  private readonly existsImpl: (p: string) => boolean;
+  private readonly tmpDir: string;
+  /** Once available, stays available for this process — avoids re-statting. */
+  private cachedAvailable = false;
+
+  constructor(opts: WhisperCppProviderOpts) {
+    this.binPath = opts.binPath;
+    this.engine = opts.engine;
+    this.modelPath = opts.modelPath;
+    this.ffmpegPath = opts.ffmpegPath ?? "ffmpeg";
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.spawn = opts.spawn ?? defaultSpawnRunner;
+    this.existsImpl = opts.existsImpl ?? existsSync;
+    this.tmpDir = opts.tmpDir ?? tmpdir();
+  }
+
+  /**
+   * Ready iff both the CLI and the model are on disk. Reports WHICH is missing
+   * — "not installed" is not an actionable message when there are two things
+   * it could mean and different fixes for each.
+   */
+  async available(): Promise<ProviderAvailability> {
+    if (this.cachedAvailable) return { ok: true };
+    const missing: string[] = [];
+    if (!this.binPath || !this.existsImpl(this.binPath)) {
+      missing.push(
+        `the ${this.engine === "whisper" ? "whisper-cli" : "parakeet-cli"} binary ` +
+          "(install it with `parachute-vault transcription install`, or `brew install whisper-cpp` on macOS)",
+      );
+    }
+    if (!this.modelPath || !this.existsImpl(this.modelPath)) {
+      missing.push("the model file (`parachute-vault transcription install` downloads it)");
+    }
+    if (missing.length > 0) {
+      return { ok: false, reason: `whisper-cpp is not ready — missing ${missing.join(" and ")}` };
+    }
+    this.cachedAvailable = true;
+    return { ok: true };
+  }
+
+  async transcribe(input: TranscribeInput): Promise<TranscribeResult> {
+    const avail = await this.available();
+    if (!avail.ok) {
+      throw new TranscriptionError(avail.reason ?? "whisper-cpp is not ready", {
+        code: "missing_provider",
+        retriable: false,
+      });
+    }
+    // Non-null after `available()`.
+    const binPath = this.binPath as string;
+    const modelPath = this.modelPath as string;
+
+    const stem = join(this.tmpDir, `parachute-stt-${randomUUID()}`);
+    const srcPath = `${stem}.src`;
+    const wavPath = `${stem}.wav`;
+
+    try {
+      await writeFile(srcPath, input.audio);
+
+      // --- transcode -------------------------------------------------------
+      const ff = await this.spawn(buildFfmpegArgs(this.ffmpegPath, srcPath, wavPath), {
+        timeoutMs: this.timeoutMs,
+      });
+      if (ff.exitCode === 127) {
+        throw new TranscriptionError(
+          "ffmpeg was not found. Audio has to be transcoded to 16 kHz mono WAV before " +
+            "transcription — install ffmpeg (`brew install ffmpeg`, `apt install ffmpeg`).",
+          { code: "ffmpeg_missing", retriable: false },
+        );
+      }
+      if (ff.exitCode !== 0 || !this.existsImpl(wavPath)) {
+        throw new TranscriptionError(
+          `ffmpeg could not decode this audio (exit ${ff.exitCode}): ${tail(ff.stderr)}`,
+          { code: "transcode_failed", retriable: false },
+        );
+      }
+
+      // --- transcribe ------------------------------------------------------
+      const run = await this.spawn(buildCliArgs(this.engine, binPath, modelPath, wavPath), {
+        timeoutMs: this.timeoutMs,
+      });
+      if (run.exitCode !== 0) {
+        throw new TranscriptionError(
+          `${this.engine === "whisper" ? "whisper-cli" : "parakeet-cli"} exited ${run.exitCode}: ${tail(run.stderr)}`,
+          { code: "whisper_cli_error", retriable: true },
+        );
+      }
+      const text = parseCliOutput(run.stdout);
+      if (text.length === 0) {
+        // Retriable, matching scribe-http's missing-text behaviour: an empty
+        // result on a genuinely silent clip terminates after maxAttempts
+        // anyway, and a transient blip gets its retry.
+        throw new Error("transcription produced no text");
+      }
+      return { text };
+    } finally {
+      await Promise.all([
+        unlink(srcPath).catch(() => {}),
+        unlink(wavPath).catch(() => {}),
+      ]);
+    }
+  }
+}
+
+/** Last few lines of a stream, for error messages that stay readable. */
+function tail(s: string, lines = 3): string {
+  const parts = s.trim().split("\n");
+  return parts.slice(-lines).join(" | ").slice(0, 500);
+}