@openparachute/vault 0.6.4 → 0.6.5-rc.10

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

@@ -0,0 +1,314 @@
+import { describe, test, expect } from "bun:test";
+import {
+  TranscribeCppProvider,
+  buildTranscribeArgs,
+  buildFfmpegArgs,
+  parseTranscribeCliOutput,
+  type SpawnRunner,
+  type SubprocessResult,
+} from "./transcribe-cpp.ts";
+import { TranscriptionError } from "../../../core/src/transcription/provider.ts";
+
+/**
+ * Conformance tests for the `transcribe-cpp` local provider (scribe-fold
+ * Phase 2a). The subprocess (`Bun.spawn`) is mocked so no real binary runs and
+ * no bytes are downloaded — we pin the argv shape, the WAV/transcode decision,
+ * the stdout parse, and the terminal-vs-retriable error mapping the worker
+ * depends on.
+ */
+
+const AUDIO = new Uint8Array([1, 2, 3, 4]);
+
+/** A spawn mock that records every argv and returns canned results per call. */
+function recordingSpawn(results: SubprocessResult[] | ((cmd: string[]) => SubprocessResult)): {
+  spawn: SpawnRunner;
+  calls: string[][];
+} {
+  const calls: string[][] = [];
+  let i = 0;
+  const spawn: SpawnRunner = async (cmd) => {
+    calls.push(cmd);
+    if (typeof results === "function") return results(cmd);
+    return results[Math.min(i++, results.length - 1)]!;
+  };
+  return { spawn, calls };
+}
+
+const ok = (stdout: string): SubprocessResult => ({ exitCode: 0, stdout, stderr: "" });
+
+/**
+ * A real `transcribe-cli` v0.1.1 stdout report (macOS arm64, whisper-tiny.en).
+ * The transcript is the single `text:` line; library `[info]`/`[debug]` logs go
+ * to STDERR (not shown here). Build one with a given `text:` value.
+ */
+function cliReport(text: string): string {
+  return [
+    "audio: test.wav",
+    "  samples:    48422",
+    "  duration:   3.026 s",
+    "  sample rate 16000 Hz mono float32",
+    "model: /models/whisper-tiny.en-Q5_K_M.gguf -> ok",
+    "  backend:    MTL0",
+    "  name:       Whisper Tiny (English)",
+    "  license:    apache-2.0",
+    "  max audio:  unbounded (long audio chunked internally)",
+    "run: ok",
+    `text: ${text}`,
+    "segments: 1",
+    `  [   0.00 ->    3.00] ${text}`,
+    "  realtime:   9x (332.1 ms for 3.0 s)",
+    "",
+  ].join("\n");
+}
+
+/** A provider whose binary + model both "exist", with an injected spawn. */
+function provider(spawn: SpawnRunner, opts: Partial<{ existsImpl: (p: string) => boolean }> = {}) {
+  return new TranscribeCppProvider({
+    binPath: "/tc/bin/transcribe-cli",
+    modelPath: "/tc/models/whisper-tiny.en-Q5_K_M.gguf",
+    ffmpegPath: "ffmpeg",
+    spawn,
+    existsImpl: opts.existsImpl ?? (() => true),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+
+describe("buildTranscribeArgs", () => {
+  test("matches upstream usage: transcribe-cli -m <model> <wav>", () => {
+    expect(buildTranscribeArgs("/bin/transcribe-cli", "/m.gguf", "/a.wav")).toEqual([
+      "/bin/transcribe-cli",
+      "-m",
+      "/m.gguf",
+      "/a.wav",
+    ]);
+  });
+});
+
+describe("buildFfmpegArgs", () => {
+  test("transcodes to 16kHz mono WAV", () => {
+    const args = buildFfmpegArgs("ffmpeg", "/in.webm", "/out.wav");
+    expect(args).toContain("-ar");
+    expect(args[args.indexOf("-ar") + 1]).toBe("16000");
+    expect(args).toContain("-ac");
+    expect(args[args.indexOf("-ac") + 1]).toBe("1");
+    expect(args[args.length - 1]).toBe("/out.wav");
+  });
+});
+
+describe("parseTranscribeCliOutput", () => {
+  test("extracts exactly the `text:` line from the real v0.1.1 report", () => {
+    const report = cliReport("Hello parachute. Testing transcribe CPP.");
+    expect(parseTranscribeCliOutput(report)).toBe("Hello parachute. Testing transcribe CPP.");
+  });
+  test("ignores the indented per-segment line (starts with a bracket, not `text:`)", () => {
+    // The segment line repeats the transcript but is indented + bracketed; only
+    // the column-0 `text:` line is the transcript, and we return it once.
+    const report = cliReport("just once");
+    expect(parseTranscribeCliOutput(report)).toBe("just once");
+  });
+  test("the `(empty)` no-result sentinel maps to \"\"", () => {
+    expect(parseTranscribeCliOutput(cliReport("(empty)"))).toBe("");
+  });
+  test("no `text:` line at all → empty string", () => {
+    expect(parseTranscribeCliOutput("audio: test.wav\nrun: ok\nsegments: 0\n")).toBe("");
+  });
+  test("empty / whitespace stdout → empty string", () => {
+    expect(parseTranscribeCliOutput("   \n  ")).toBe("");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// available() — cheap, no spawn
+// ---------------------------------------------------------------------------
+
+describe("TranscribeCppProvider.available", () => {
+  test("name is stable 'transcribe-cpp'", () => {
+    expect(provider(recordingSpawn([]).spawn).name).toBe("transcribe-cpp");
+  });
+
+  test("ok:true when binary + model exist — and NEVER spawns", async () => {
+    const { spawn, calls } = recordingSpawn([]);
+    const p = provider(spawn);
+    expect(await p.available()).toEqual({ ok: true });
+    expect(calls.length).toBe(0); // no subprocess on the hot path
+  });
+
+  test("ok:false with reason when the binary is missing", async () => {
+    const { spawn, calls } = recordingSpawn([]);
+    const p = provider(spawn, { existsImpl: (path) => !path.includes("transcribe-cli") });
+    const avail = await p.available();
+    expect(avail.ok).toBe(false);
+    expect(avail.reason).toContain("transcribe-cli");
+    expect(calls.length).toBe(0);
+  });
+
+  test("ok:false when the model is missing", async () => {
+    const { spawn } = recordingSpawn([]);
+    const p = provider(spawn, { existsImpl: (path) => !path.endsWith(".gguf") });
+    expect((await p.available()).ok).toBe(false);
+  });
+
+  test("dylib-only install (model exists, no runnable CLI) → ok:false (honesty)", async () => {
+    // v0.1.1 ships a library, not a CLI: libs + model land on disk but no
+    // transcribe-cli. available() must gate on the binary so the capability
+    // flag reports enabled:false rather than a capability we can't deliver.
+    const { spawn } = recordingSpawn([]);
+    const p = provider(spawn, { existsImpl: (path) => path.endsWith(".gguf") }); // only the model exists
+    const avail = await p.available();
+    expect(avail.ok).toBe(false);
+    expect(avail.reason).toContain("transcribe-cli");
+  });
+
+  test("unconfigured (no binPath) → ok:false, no throw", async () => {
+    const p = new TranscribeCppProvider({});
+    expect((await p.available()).ok).toBe(false);
+  });
+
+  test("caches the once-true result (no repeated existsSync after ok)", async () => {
+    let calls = 0;
+    const p = provider(recordingSpawn([]).spawn, {
+      existsImpl: () => {
+        calls++;
+        return true;
+      },
+    });
+    await p.available();
+    const afterFirst = calls;
+    await p.available();
+    expect(calls).toBe(afterFirst); // second call short-circuits the cache
+  });
+});
+
+// ---------------------------------------------------------------------------
+// transcribe() — happy paths
+// ---------------------------------------------------------------------------
+
+describe("TranscribeCppProvider.transcribe — happy path", () => {
+  test("non-WAV input transcodes via ffmpeg THEN runs transcribe-cli", async () => {
+    const { spawn, calls } = recordingSpawn([ok(""), ok(cliReport("the transcript"))]);
+    const p = provider(spawn);
+    const res = await p.transcribe({ audio: AUDIO, filename: "memo.webm", mimeType: "audio/webm" });
+
+    expect(res.text).toBe("the transcript");
+    expect(calls.length).toBe(2);
+    // First call: ffmpeg transcode to 16kHz mono WAV.
+    expect(calls[0]![0]).toBe("ffmpeg");
+    expect(calls[0]).toContain("16000");
+    // Second call: transcribe-cli -m <model> <wav>.
+    expect(calls[1]![0]).toBe("/tc/bin/transcribe-cli");
+    expect(calls[1]![1]).toBe("-m");
+    expect(calls[1]![2]).toBe("/tc/models/whisper-tiny.en-Q5_K_M.gguf");
+    expect(calls[1]![3]).toMatch(/\.16k\.wav$/);
+  });
+
+  test("WAV input ALSO transcodes (strict 16kHz — we can't trust its rate)", async () => {
+    // Regression for the live-verified bug: a 44.1kHz .wav made transcribe-cli
+    // exit 1. We now ALWAYS run ffmpeg first, even for a .wav → two spawns, and
+    // the CLI reads the 16k .wav ffmpeg produced (not the raw input).
+    const { spawn, calls } = recordingSpawn([ok(""), ok(cliReport("wav text"))]);
+    const p = provider(spawn);
+    const res = await p.transcribe({ audio: AUDIO, filename: "clip.wav", mimeType: "audio/wav" });
+
+    expect(res.text).toBe("wav text");
+    expect(calls.length).toBe(2);
+    expect(calls[0]![0]).toBe("ffmpeg");
+    expect(calls[0]).toContain("16000");
+    expect(calls[0]).toContain("1"); // -ac 1 mono
+    expect(calls[1]![0]).toBe("/tc/bin/transcribe-cli");
+    expect(calls[1]![3]).toMatch(/\.16k\.wav$/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// transcribe() — error mapping
+// ---------------------------------------------------------------------------
+
+describe("TranscribeCppProvider.transcribe — error mapping", () => {
+  async function catchErr(fn: () => Promise<unknown>): Promise<unknown> {
+    try {
+      await fn();
+    } catch (err) {
+      return err;
+    }
+    throw new Error("expected transcribe() to throw");
+  }
+
+  test("binary missing → non-retriable missing_provider, NEVER spawns", async () => {
+    const { spawn, calls } = recordingSpawn([ok("nope")]);
+    const p = provider(spawn, { existsImpl: (path) => !path.includes("transcribe-cli") });
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" }),
+    )) as TranscriptionError;
+    expect(err).toBeInstanceOf(TranscriptionError);
+    expect(err.code).toBe("missing_provider");
+    expect(err.retriable).toBe(false);
+    expect(calls.length).toBe(0);
+  });
+
+  test("model missing → non-retriable missing_provider", async () => {
+    const { spawn } = recordingSpawn([ok("nope")]);
+    const p = provider(spawn, { existsImpl: (path) => !path.endsWith(".gguf") });
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" }),
+    )) as TranscriptionError;
+    expect(err.code).toBe("missing_provider");
+    expect(err.retriable).toBe(false);
+  });
+
+  test("ffmpeg not found (exit 127) → non-retriable ffmpeg_missing", async () => {
+    const { spawn } = recordingSpawn([{ exitCode: 127, stdout: "", stderr: "not found" }]);
+    const p = provider(spawn);
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" }),
+    )) as TranscriptionError;
+    expect(err.code).toBe("ffmpeg_missing");
+    expect(err.retriable).toBe(false);
+  });
+
+  test("ffmpeg transcode failure (non-127) → non-retriable transcode_failed", async () => {
+    const { spawn } = recordingSpawn([{ exitCode: 1, stdout: "", stderr: "bad input" }]);
+    const p = provider(spawn);
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" }),
+    )) as TranscriptionError;
+    expect(err.code).toBe("transcode_failed");
+    expect(err.retriable).toBe(false);
+  });
+
+  test("transcribe-cli non-zero exit → RETRIABLE transcribe_cli_error", async () => {
+    // ffmpeg succeeds; transcribe-cli then fails with a generic exit code.
+    const { spawn } = recordingSpawn([ok(""), { exitCode: 2, stdout: "", stderr: "decode error" }]);
+    const p = provider(spawn);
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.wav", mimeType: "audio/wav" }),
+    )) as TranscriptionError;
+    expect(err).toBeInstanceOf(TranscriptionError);
+    expect(err.code).toBe("transcribe_cli_error");
+    expect(err.retriable).toBe(true);
+  });
+
+  test("transcribe-cli launch failure (127) → non-retriable missing_provider", async () => {
+    const { spawn } = recordingSpawn([ok(""), { exitCode: 127, stdout: "", stderr: "gone" }]);
+    const p = provider(spawn);
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.wav", mimeType: "audio/wav" }),
+    )) as TranscriptionError;
+    expect(err.code).toBe("missing_provider");
+    expect(err.retriable).toBe(false);
+  });
+
+  test("`text: (empty)` no-result → plain Error (retriable via worker), not TranscriptionError", async () => {
+    // ffmpeg ok; transcribe-cli returns its (empty) sentinel → parses to "".
+    const { spawn } = recordingSpawn([ok(""), ok(cliReport("(empty)"))]);
+    const p = provider(spawn);
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.wav", mimeType: "audio/wav" }),
+    )) as Error;
+    expect(err).toBeInstanceOf(Error);
+    expect(err).not.toBeInstanceOf(TranscriptionError);
+    expect(err.message).toContain("no transcript text");
+  });
+});

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

@@ -0,0 +1,293 @@
+/**
+ * `transcribe-cpp` — the local, no-Python transcription provider
+ * (scribe-fold Phase 2a).
+ *
+ * Turns audio into text by subprocessing the prebuilt `transcribe-cli` from
+ * transcribe.cpp (github.com/handy-computer/transcribe.cpp — CJ Pais /
+ * Mozilla.ai, MIT). transcribe.cpp's in-process N-API binding crashes on Bun,
+ * so we drive the CLI as a subprocess — structurally like the `scribe-http`
+ * provider, but local. It's the recommended low-RAM / no-Python provider,
+ * opt-in via `parachute-vault transcription install` + `TRANSCRIPTION_PROVIDER`.
+ *
+ * ## The audio path
+ *
+ * `transcribe-cli` STRICTLY requires **16kHz mono WAV** input — it rejects other
+ * sample rates (a 44.1kHz .wav exits non-zero; verified against v0.1.1). So we
+ * ALWAYS transcode the incoming audio through `ffmpeg -ar 16000 -ac 1` first,
+ * even when it's already a `.wav` — we can't trust an incoming WAV's sample
+ * rate. The install verb prints an ffmpeg hint when it's missing; here a missing
+ * ffmpeg surfaces as a terminal `ffmpeg_missing` error the operator must fix.
+ *
+ * ## Reading the output
+ *
+ * `transcribe-cli` prints a human-readable report to STDOUT (audio/model/run
+ * lines, a `text: <transcript>` line, then per-segment lines) and sends its
+ * library `[info]`/`[debug]` logs to STDERR. The transcript is the single
+ * `text:` line; `text: (empty)` is its no-result sentinel. See
+ * `parseTranscribeCliOutput`.
+ *
+ * ## Error mapping (mirrors scribe-http's terminal-vs-retriable contract)
+ *
+ *   - binary / model not installed → non-retriable `missing_provider` (operator
+ *     runs `transcription install`); never spawns.
+ *   - ffmpeg not found → non-retriable `ffmpeg_missing`.
+ *   - ffmpeg transcode non-zero exit → non-retriable `transcode_failed`
+ *     (a re-run on the same undecodable blob won't help).
+ *   - `transcribe-cli` non-zero exit → RETRIABLE `transcribe_cli_error` (could
+ *     be a transient resource blip; the worker backs off, and a deterministic
+ *     failure still terminates after maxAttempts).
+ *   - empty/unparseable stdout → plain `Error` (retriable via the worker),
+ *     matching scribe-http's "missing text field".
+ */
+
+import { randomUUID } from "crypto";
+import { existsSync } from "fs";
+import { writeFile, unlink } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import {
+  TranscriptionError,
+  type TranscriptionProvider,
+  type TranscribeInput,
+  type TranscribeResult,
+  type ProviderAvailability,
+} from "../../../core/src/transcription/provider.ts";
+
+/** transcribe-cli can be slow on CPU for long audio; generous default. */
+const DEFAULT_TIMEOUT_MS = 600_000;
+
+/** Result of running a subprocess: exit code + captured streams (as text). */
+export interface SubprocessResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Injection seam for the subprocess call. Production uses `defaultSpawnRunner`
+ * (Bun.spawn); tests pass a mock so no real binary runs. A launch failure
+ * (binary not found) resolves to `exitCode: 127` rather than throwing, so the
+ * provider maps it to a friendly terminal error.
+ */
+export type SpawnRunner = (
+  cmd: string[],
+  opts?: { timeoutMs?: number },
+) => Promise<SubprocessResult>;
+
+/** Production spawn runner over `Bun.spawn`. */
+export const defaultSpawnRunner: SpawnRunner = async (cmd, opts) => {
+  let proc: ReturnType<typeof Bun.spawn>;
+  try {
+    proc = Bun.spawn(cmd, { stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+  } catch (err) {
+    // ENOENT etc. — the binary couldn't be launched at all.
+    return { exitCode: 127, stdout: "", stderr: err instanceof Error ? err.message : String(err) };
+  }
+  let timedOut = false;
+  const timer = opts?.timeoutMs
+    ? setTimeout(() => {
+        timedOut = true;
+        proc.kill();
+      }, opts.timeoutMs)
+    : null;
+  try {
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout as ReadableStream).text(),
+      new Response(proc.stderr as ReadableStream).text(),
+      proc.exited,
+    ]);
+    if (timedOut) {
+      return { exitCode: 124, stdout, stderr: `${stderr}\n[transcribe-cli timed out]` };
+    }
+    return { exitCode, stdout, stderr };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+};
+
+export interface TranscribeCppProviderOpts {
+  /** Path to the `transcribe-cli` binary. Undefined ⇒ unavailable + terminal. */
+  binPath?: string;
+  /** Path to the GGUF model. Undefined ⇒ unavailable + terminal. */
+  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). Default `defaultSpawnRunner`. */
+  spawn?: SpawnRunner;
+  /** Existence probe (tests inject). Default `fs.existsSync`. */
+  existsImpl?: (p: string) => boolean;
+  /** Scratch dir for the temp audio/wav files. Default `os.tmpdir()`. */
+  tmpDir?: string;
+}
+
+/**
+ * Build the `transcribe-cli` argv. Upstream usage:
+ *   `transcribe-cli -m <model.gguf> <audio.wav>`
+ * (model via `-m`, audio as a positional). Exported so a test pins the shape.
+ */
+export function buildTranscribeArgs(binPath: string, modelPath: string, wavPath: string): string[] {
+  return [binPath, "-m", modelPath, wavPath];
+}
+
+/** Build the ffmpeg transcode argv → 16kHz 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 `transcribe-cli`'s stdout report. The CLI prints a
+ * human report whose transcript is the single `text: <transcript>` line at
+ * column 0 (library `[info]`/`[debug]` logs go to STDERR, and the indented
+ * per-segment lines start with a bracket, not `text:`). We return the first
+ * `text:` line trimmed; the `text: (empty)` no-result sentinel maps to "" so the
+ * caller treats it as a retriable empty-output failure. Returns "" when no
+ * `text:` line is present. Validated against transcribe.cpp v0.1.1. Exported for
+ * tests.
+ */
+export function parseTranscribeCliOutput(stdout: string): string {
+  for (const line of stdout.split("\n")) {
+    const m = line.match(/^text:\s?(.*)$/);
+    if (m) {
+      const t = m[1]!.trim();
+      return t === "(empty)" ? "" : t;
+    }
+  }
+  return "";
+}
+
+export class TranscribeCppProvider implements TranscriptionProvider {
+  readonly name = "transcribe-cpp";
+
+  private readonly binPath: string | undefined;
+  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: TranscribeCppProviderOpts = {}) {
+    this.binPath = opts.binPath;
+    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();
+  }
+
+  /**
+   * Cheap readiness probe — a runnable `transcribe-cli` binary AND the model
+   * both present on disk. NEVER spawns (it gates the capability flag on every
+   * `/api/vault` GET). Memoizes the once-true result so repeated landing reads
+   * don't re-stat.
+   *
+   * The binary check is load-bearing for honesty: transcribe.cpp v0.1.1 ships a
+   * *library*, not a prebuilt CLI, so `transcription install` can leave the libs
+   * + model in place with no runnable CLI. `binPath` resolves to
+   * `TRANSCRIBE_CPP_BIN` or a located binary; when neither exists we report
+   * `ok:false` (capability `enabled:false`) rather than claiming a capability we
+   * can't deliver.
+   */
+  async available(): Promise<ProviderAvailability> {
+    if (this.cachedAvailable) return { ok: true };
+    if (!this.binPath || !this.existsImpl(this.binPath)) {
+      return {
+        ok: false,
+        reason:
+          "no runnable transcribe-cli (run `parachute-vault transcription install` to build one against the prebuilt libs — needs a C++ compiler — or set TRANSCRIBE_CPP_BIN; see `parachute-vault transcription status`)",
+      };
+    }
+    if (!this.modelPath || !this.existsImpl(this.modelPath)) {
+      return {
+        ok: false,
+        reason: "no GGUF model installed (run `parachute-vault transcription install`)",
+      };
+    }
+    this.cachedAvailable = true;
+    return { ok: true };
+  }
+
+  async transcribe(input: TranscribeInput): Promise<TranscribeResult> {
+    if (!this.binPath || !this.existsImpl(this.binPath)) {
+      throw new TranscriptionError("transcribe-cli not installed", {
+        code: "missing_provider",
+        retriable: false,
+      });
+    }
+    if (!this.modelPath || !this.existsImpl(this.modelPath)) {
+      throw new TranscriptionError("no GGUF model installed for transcribe-cpp", {
+        code: "missing_provider",
+        retriable: false,
+      });
+    }
+
+    const id = randomUUID();
+    const inExt = extFor(input.filename, input.mimeType);
+    const inputPath = join(this.tmpDir, `parachute-tc-${id}.${inExt}`);
+    const wavPath = join(this.tmpDir, `parachute-tc-${id}.16k.wav`);
+    const cleanup: string[] = [inputPath, wavPath];
+
+    try {
+      await writeFile(inputPath, input.audio);
+
+      // transcribe-cli STRICTLY requires 16kHz mono WAV and rejects other sample
+      // rates (a 44.1kHz .wav exits non-zero). ALWAYS transcode — even an
+      // incoming .wav, whose sample rate we can't trust — via ffmpeg.
+      const ff = await this.spawn(buildFfmpegArgs(this.ffmpegPath, inputPath, wavPath), {
+        timeoutMs: this.timeoutMs,
+      });
+      if (ff.exitCode !== 0) {
+        const missing = ff.exitCode === 127;
+        throw new TranscriptionError(
+          missing
+            ? "ffmpeg not found — install it to transcode audio to 16kHz mono WAV for transcribe-cpp (apt install ffmpeg / brew install ffmpeg)"
+            : `ffmpeg transcode failed (exit ${ff.exitCode}): ${ff.stderr.trim().slice(0, 500)}`,
+          { code: missing ? "ffmpeg_missing" : "transcode_failed", retriable: false },
+        );
+      }
+
+      const res = await this.spawn(buildTranscribeArgs(this.binPath, this.modelPath, wavPath), {
+        timeoutMs: this.timeoutMs,
+      });
+      if (res.exitCode !== 0) {
+        // Launch failure (127) means the binary vanished under us despite the
+        // existsSync above — terminal. Any other non-zero is retriable so a
+        // transient resource blip backs off; a deterministic failure still
+        // terminates after the worker's maxAttempts.
+        if (res.exitCode === 127) {
+          throw new TranscriptionError(`transcribe-cli could not be launched: ${res.stderr.trim()}`, {
+            code: "missing_provider",
+            retriable: false,
+          });
+        }
+        throw new TranscriptionError(
+          `transcribe-cli exited ${res.exitCode}: ${res.stderr.trim().slice(0, 500)}`,
+          { code: "transcribe_cli_error", retriable: true },
+        );
+      }
+
+      const text = parseTranscribeCliOutput(res.stdout);
+      if (!text) {
+        // Empty/unparseable — plain Error is treated as retriable by the worker.
+        throw new Error("transcribe-cli produced no transcript text");
+      }
+      return { text };
+    } finally {
+      await Promise.all(cleanup.map((p) => unlink(p).catch(() => {})));
+    }
+  }
+}
+
+/** Choose a temp-file extension from the filename or mime type. */
+function extFor(filename: string, mimeType: string): string {
+  const fromName = filename.split(".").pop();
+  if (fromName && fromName.length <= 5 && /^[a-z0-9]+$/i.test(fromName)) return fromName.toLowerCase();
+  const sub = mimeType.split("/")[1]?.split(";")[0]?.trim();
+  if (sub && /^[a-z0-9]+$/i.test(sub)) return sub.toLowerCase();
+  return "bin";
+}