@openparachute/vault 0.7.4 → 0.7.5-rc.5

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);
+}

package/src/transcription/resolve-binary.test.ts

@@ -0,0 +1,131 @@
+/**
+ * Binary resolution across the routes whisper.cpp actually arrives by.
+ *
+ * The case worth the most care is Homebrew: a launchd-supervised vault does
+ * NOT inherit a login shell's PATH, so on macOS `whisper-cli` is routinely
+ * installed and simultaneously invisible to the running daemon. Probing brew's
+ * prefixes explicitly is what stops "I installed it and it still says not
+ * configured" — the worst failure available here, because the operator did the
+ * work and got told no.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { join } from "path";
+import {
+  binaryNameFor,
+  candidateBinDirs,
+  managedBinDir,
+  managedModelDir,
+  resolveCliBinary,
+  resolveFfmpeg,
+} from "./resolve-binary.ts";
+
+/** An existsImpl that only knows about an explicit allow-list. */
+function only(...present: string[]) {
+  const set = new Set(present);
+  return (p: string) => set.has(p);
+}
+
+describe("binaryNameFor", () => {
+  test("maps engine → CLI name", () => {
+    expect(binaryNameFor("whisper")).toBe("whisper-cli");
+    expect(binaryNameFor("parakeet")).toBe("parakeet-cli");
+  });
+});
+
+describe("candidateBinDirs — the ladder", () => {
+  const env = { PARACHUTE_HOME: "/ph", PATH: "/usr/bin:/bin" } as NodeJS.ProcessEnv;
+
+  test("managed dir precedes brew, which precedes PATH", () => {
+    const dirs = candidateBinDirs({ env });
+    expect(dirs.indexOf("/ph/transcription/bin")).toBeLessThan(dirs.indexOf("/opt/homebrew/bin"));
+    expect(dirs.indexOf("/opt/homebrew/bin")).toBeLessThan(dirs.indexOf("/usr/bin"));
+  });
+
+  test("an explicit override leads everything", () => {
+    const dirs = candidateBinDirs({ env: { ...env, WHISPER_CPP_BIN_DIR: "/custom" } });
+    expect(dirs[0]).toBe("/custom");
+  });
+
+  test("brew prefixes are probed even when absent from PATH — the launchd case", () => {
+    // A launchd-supervised daemon gets a minimal PATH with no /opt/homebrew.
+    const dirs = candidateBinDirs({ env: { PATH: "/usr/bin:/bin" } as NodeJS.ProcessEnv });
+    expect(dirs).toContain("/opt/homebrew/bin");
+    expect(dirs).toContain("/usr/local/bin");
+  });
+
+  test("no duplicates, order preserved", () => {
+    const dirs = candidateBinDirs({
+      env: { PATH: "/usr/bin:/opt/homebrew/bin:/usr/bin" } as NodeJS.ProcessEnv,
+    });
+    expect(dirs.length).toBe(new Set(dirs).size);
+  });
+
+  test("an empty PATH doesn't produce empty-string dirs", () => {
+    const dirs = candidateBinDirs({ env: { PATH: "" } as NodeJS.ProcessEnv });
+    expect(dirs).not.toContain("");
+  });
+});
+
+describe("resolveCliBinary", () => {
+  const env = { PARACHUTE_HOME: "/ph", PATH: "/usr/bin" } as NodeJS.ProcessEnv;
+
+  test("finds a brew-installed binary a bare PATH lookup would miss", () => {
+    const got = resolveCliBinary("parakeet", {
+      env,
+      existsImpl: only("/opt/homebrew/bin/parakeet-cli"),
+    });
+    expect(got).toBe("/opt/homebrew/bin/parakeet-cli");
+  });
+
+  test("our managed install wins over a brew one", () => {
+    const got = resolveCliBinary("whisper", {
+      env,
+      existsImpl: only("/ph/transcription/bin/whisper-cli", "/opt/homebrew/bin/whisper-cli"),
+    });
+    expect(got).toBe("/ph/transcription/bin/whisper-cli");
+  });
+
+  test("the override beats everything", () => {
+    const got = resolveCliBinary("whisper", {
+      env: { ...env, WHISPER_CPP_BIN_DIR: "/custom" },
+      existsImpl: only("/custom/whisper-cli", "/ph/transcription/bin/whisper-cli"),
+    });
+    expect(got).toBe("/custom/whisper-cli");
+  });
+
+  test("returns an ABSOLUTE path, never a bare name", () => {
+    const got = resolveCliBinary("parakeet", { env, existsImpl: only("/usr/bin/parakeet-cli") });
+    // A bare name would be re-resolved against the spawn's PATH, which may
+    // differ from the one we probed.
+    expect(got?.startsWith("/")).toBe(true);
+  });
+
+  test("undefined when genuinely absent", () => {
+    expect(resolveCliBinary("whisper", { env, existsImpl: () => false })).toBeUndefined();
+  });
+
+  test("engine selects the binary — a whisper install doesn't satisfy parakeet", () => {
+    const deps = { env, existsImpl: only("/usr/bin/whisper-cli") };
+    expect(resolveCliBinary("whisper", deps)).toBe("/usr/bin/whisper-cli");
+    expect(resolveCliBinary("parakeet", deps)).toBeUndefined();
+  });
+});
+
+describe("resolveFfmpeg", () => {
+  test("uses the same ladder, so a brew ffmpeg is found under launchd too", () => {
+    const got = resolveFfmpeg({
+      env: { PATH: "/usr/bin" } as NodeJS.ProcessEnv,
+      existsImpl: only("/opt/homebrew/bin/ffmpeg"),
+    });
+    expect(got).toBe("/opt/homebrew/bin/ffmpeg");
+  });
+});
+
+describe("managed paths honour PARACHUTE_HOME", () => {
+  test("bin + model dirs sit under the ecosystem root", () => {
+    const env = { PARACHUTE_HOME: "/custom/root" } as NodeJS.ProcessEnv;
+    expect(managedBinDir(env)).toBe(join("/custom/root", "transcription", "bin"));
+    expect(managedModelDir(env)).toBe(join("/custom/root", "transcription", "models"));
+  });
+});