@openparachute/vault 0.7.4 → 0.7.5-rc.5

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

@@ -0,0 +1,228 @@
+/**
+ * The whisper.cpp install planner.
+ *
+ * Pure, so the whole host matrix is exercised without downloading anything.
+ * The cases that matter are the ones where a wrong answer is expensive: a
+ * platform with no prebuilt binaries must REFUSE with instructions rather than
+ * half-install, and an already-installed binary must short-circuit rather than
+ * triggering another package-manager round trip.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { DEFAULT_MODEL_ID } from "./models.ts";
+import {
+  describeWhisperPlan,
+  planBinaryStrategy,
+  planWhisperInstall,
+  WHISPER_CPP_VERSION,
+} from "./install-whisper-cpp.ts";
+
+const GB = 1024 * 1024 * 1024;
+const env = { PARACHUTE_HOME: "/ph" } as NodeJS.ProcessEnv;
+
+describe("planBinaryStrategy", () => {
+  test("macOS → Homebrew (upstream ships no macOS CLI tarball)", () => {
+    const s = planWhisperInstall(undefined, {
+      platform: "darwin",
+      arch: "arm64",
+      totalRamBytes: 16 * GB,
+      env,
+    }).binary;
+    expect(s.kind).toBe("homebrew");
+    expect(s.kind === "homebrew" && s.formula).toBe("whisper-cpp");
+  });
+
+  test("macOS Intel also gets Homebrew — the formula covers both arches", () => {
+    const s = planWhisperInstall(undefined, {
+      platform: "darwin",
+      arch: "x64",
+      totalRamBytes: 16 * GB,
+      env,
+    }).binary;
+    expect(s.kind).toBe("homebrew");
+  });
+
+  test("Linux x64 → the x64 release tarball, pinned to a version", () => {
+    const s = planWhisperInstall(undefined, {
+      platform: "linux",
+      arch: "x64",
+      totalRamBytes: 8 * GB,
+      env,
+    }).binary;
+    expect(s.kind).toBe("tarball");
+    if (s.kind === "tarball") {
+      expect(s.assetName).toBe("whisper-bin-ubuntu-x64.tar.gz");
+      expect(s.url).toContain(`v${WHISPER_CPP_VERSION}`);
+    }
+  });
+
+  test("Linux arm64 → the arm64 tarball", () => {
+    const s = planWhisperInstall(undefined, {
+      platform: "linux",
+      arch: "arm64",
+      totalRamBytes: 8 * GB,
+      env,
+    }).binary;
+    expect(s.kind === "tarball" && s.assetName).toBe("whisper-bin-ubuntu-arm64.tar.gz");
+  });
+
+  test("an exotic Linux arch REFUSES with a pointer at the override", () => {
+    const s = planWhisperInstall(undefined, {
+      platform: "linux",
+      arch: "riscv64",
+      totalRamBytes: 8 * GB,
+      env,
+    }).binary;
+    expect(s.kind).toBe("unsupported");
+    expect(s.kind === "unsupported" && s.reason).toMatch(/WHISPER_CPP_BIN_DIR/);
+  });
+
+  test("an unknown platform refuses rather than half-installing", () => {
+    const plan = planWhisperInstall(undefined, {
+      platform: "freebsd",
+      arch: "x64",
+      totalRamBytes: 8 * GB,
+      env,
+    });
+    expect(plan.supported).toBe(false);
+    expect(plan.binary.kind).toBe("unsupported");
+  });
+
+  test("an already-installed binary short-circuits every package manager", () => {
+    const plan = planWhisperInstall(undefined, {
+      platform: "darwin",
+      arch: "arm64",
+      totalRamBytes: 16 * GB,
+      env,
+      resolveExisting: () => "/opt/homebrew/bin/parakeet-cli",
+    });
+    expect(plan.binary.kind).toBe("already-present");
+    expect(plan.supported).toBe(true);
+  });
+});
+
+describe("model selection", () => {
+  test("a capable box gets the recommended Parakeet", () => {
+    const p = planWhisperInstall(undefined, {
+      platform: "linux",
+      arch: "x64",
+      totalRamBytes: 8 * GB,
+      env,
+    });
+    expect(p.model.id).toBe(DEFAULT_MODEL_ID);
+    expect(p.modelExplicit).toBe(false);
+  });
+
+  test("a 2 GB VPS still gets Parakeet, not a step down to Whisper Tiny", () => {
+    // The common cheap-VPS tier. Parakeet q4 is 339 MB and comfortably fits;
+    // dropping to Whisper Tiny here would be a large accuracy loss for
+    // headroom the box didn't need.
+    const p = planWhisperInstall(undefined, {
+      platform: "linux",
+      arch: "x64",
+      totalRamBytes: 2 * GB,
+      env,
+    });
+    expect(p.model.engine).toBe("parakeet");
+  });
+
+  test("a 1 GB box steps down rather than swapping itself to death", () => {
+    const p = planWhisperInstall(undefined, {
+      platform: "linux",
+      arch: "x64",
+      totalRamBytes: 1 * GB,
+      env,
+    });
+    expect(p.model.sizeMb).toBeLessThan(150);
+  });
+
+  test("an explicit model is honoured over the RAM pick, with a warning", () => {
+    const p = planWhisperInstall("whisper-large-v3-turbo", {
+      platform: "linux",
+      arch: "x64",
+      totalRamBytes: 2 * GB,
+      env,
+    });
+    expect(p.model.id).toBe("whisper-large-v3-turbo");
+    expect(p.modelExplicit).toBe(true);
+    // Honoured, but the operator is told what they're in for.
+    expect(p.ramWarning).toBeTruthy();
+    expect(p.ramWarning).toMatch(/may swap or run slowly/);
+  });
+
+  test("no warning when the box comfortably fits the model", () => {
+    const p = planWhisperInstall(undefined, {
+      platform: "linux",
+      arch: "x64",
+      totalRamBytes: 32 * GB,
+      env,
+    });
+    expect(p.ramWarning).toBeUndefined();
+  });
+
+  test("an unknown model id is refused, NOT silently defaulted", () => {
+    // Silently installing something else would leave the operator convinced
+    // they're running a model they aren't.
+    const p = planWhisperInstall("whisper-enormous", {
+      platform: "linux",
+      arch: "x64",
+      totalRamBytes: 8 * GB,
+      env,
+    });
+    expect(p.supported).toBe(false);
+    expect(p.binary.kind === "unsupported" && p.binary.reason).toMatch(/unknown model id/);
+  });
+
+  test("paths honour PARACHUTE_HOME", () => {
+    const p = planWhisperInstall(undefined, {
+      platform: "linux",
+      arch: "x64",
+      totalRamBytes: 8 * GB,
+      env,
+    });
+    expect(p.modelPath.startsWith("/ph/transcription/models/")).toBe(true);
+    expect(p.binDir).toBe("/ph/transcription/bin");
+  });
+});
+
+describe("describeWhisperPlan", () => {
+  test("names the model, its size, and where it goes", () => {
+    const out = describeWhisperPlan(
+      planWhisperInstall(undefined, {
+        platform: "linux",
+        arch: "x64",
+        totalRamBytes: 8 * GB,
+        env,
+      }),
+    ).join("\n");
+    expect(out).toMatch(/Parakeet/);
+    expect(out).toMatch(/396 MB/);
+    expect(out).toMatch(/\/ph\/transcription\/models/);
+  });
+
+  test("an unsupported host explains itself rather than printing a plan", () => {
+    const out = describeWhisperPlan(
+      planWhisperInstall(undefined, {
+        platform: "freebsd",
+        arch: "x64",
+        totalRamBytes: 8 * GB,
+        env,
+      }),
+    ).join("\n");
+    expect(out).toMatch(/UNSUPPORTED/);
+    expect(out).toMatch(/WHISPER_CPP_BIN_DIR/);
+  });
+
+  test("the macOS line tells you what brew actually gives you", () => {
+    const out = describeWhisperPlan(
+      planWhisperInstall(undefined, {
+        platform: "darwin",
+        arch: "arm64",
+        totalRamBytes: 16 * GB,
+        env,
+      }),
+    ).join("\n");
+    expect(out).toMatch(/brew install whisper-cpp/);
+    expect(out).toMatch(/whisper-cli \+ parakeet-cli/);
+  });
+});

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

@@ -0,0 +1,219 @@
+/**
+ * `parachute-vault transcription install` for the whisper.cpp provider.
+ *
+ * Split into a PURE planner and a thin executor. The planner takes the host's
+ * platform/arch/RAM and the operator's flags and answers "what would happen" —
+ * no network, no writes — so `--dry-run` and the tests exercise the whole
+ * decision matrix without downloading a byte.
+ *
+ * ## How the binaries arrive, per platform
+ *
+ * **macOS** — Homebrew, and only Homebrew. whisper.cpp publishes release
+ * tarballs for Linux and Windows but NOT macOS (the macOS artifact is an
+ * `.xcframework`, which is for embedding in an app, not a CLI to spawn). The
+ * formula is bottled for arm64 Tahoe/Sequoia/Sonoma, so `brew install
+ * whisper-cpp` is a fast binary download rather than a source build. With no
+ * brew on the box we refuse and say so plainly — pretending to have another
+ * route would just fail later and more confusingly.
+ *
+ * **Linux** — the release tarball, extracted into our own managed directory
+ * (`<root>/transcription/bin`) rather than anywhere system-wide. The tarball
+ * carries `whisper-cli`, `parakeet-cli`, and the `libggml*`/`libwhisper` shared
+ * objects they link against, so the whole set moves together and we never
+ * fight a distro's package manager.
+ *
+ * ## Why it verifies before declaring success
+ *
+ * The provider this replaces was configured by an install verb that never
+ * checked whether the thing it configured could run — which is exactly how
+ * `TRANSCRIPTION_PROVIDER=transcribe-cpp` came to point at a CLI that has
+ * never existed. So the last step here actually SPAWNS the CLI against a
+ * generated test clip and reads the transcript back. `TRANSCRIPTION_PROVIDER`
+ * flips only after that passes. An install that can't transcribe is an install
+ * that failed, and it should say so at install time rather than silently at
+ * the first voice memo.
+ */
+
+import { totalmem } from "os";
+import { join } from "path";
+import {
+  DEFAULT_MODEL_ID,
+  findModel,
+  pickDefaultModel,
+  type TranscriptionModel,
+} from "./models.ts";
+import { binaryNameFor, managedBinDir, managedModelDir } from "./resolve-binary.ts";
+
+/** whisper.cpp release the Linux tarballs are pulled from. */
+export const WHISPER_CPP_VERSION = "1.9.1";
+
+/** How the CLI binaries get onto this box. */
+export type BinaryStrategy =
+  | { kind: "homebrew"; formula: string }
+  | { kind: "tarball"; url: string; assetName: string }
+  | { kind: "already-present"; path: string }
+  | { kind: "unsupported"; reason: string };
+
+export interface WhisperInstallPlan {
+  platform: string;
+  arch: string;
+  totalRamGb: number;
+  /** The model to fetch + activate. */
+  model: TranscriptionModel;
+  /** Whether the operator named the model explicitly (skips the RAM warning). */
+  modelExplicit: boolean;
+  /** How to obtain `whisper-cli` / `parakeet-cli`. */
+  binary: BinaryStrategy;
+  /** Absolute destination for the model file. */
+  modelPath: string;
+  /** Directory binaries land in (tarball strategy) or are found in. */
+  binDir: string;
+  /** True when the plan can proceed. */
+  supported: boolean;
+  /** Set when the box has less RAM than the chosen model wants. */
+  ramWarning?: string;
+}
+
+export interface PlanDeps {
+  platform?: string;
+  arch?: string;
+  totalRamBytes?: number;
+  env?: NodeJS.ProcessEnv;
+  /** Existing binary probe — lets the plan report "already present". */
+  resolveExisting?: (engine: "whisper" | "parakeet") => string | undefined;
+}
+
+/**
+ * Decide how to get the binaries for this host.
+ *
+ * `already-present` short-circuits everything: an operator who ran `brew
+ * install whisper-cpp` themselves, or who is re-running install, shouldn't
+ * trigger another package-manager round trip.
+ */
+export function planBinaryStrategy(
+  model: TranscriptionModel,
+  deps: PlanDeps = {},
+): BinaryStrategy {
+  const platform = deps.platform ?? process.platform;
+  const arch = deps.arch ?? process.arch;
+
+  const existing = deps.resolveExisting?.(model.engine);
+  if (existing) return { kind: "already-present", path: existing };
+
+  if (platform === "darwin") {
+    // No macOS CLI tarball exists upstream — the macOS artifact is an
+    // xcframework for embedding, not a spawnable binary. Homebrew is the path.
+    return { kind: "homebrew", formula: "whisper-cpp" };
+  }
+
+  if (platform === "linux") {
+    const assetArch = arch === "arm64" || arch === "aarch64" ? "arm64" : arch === "x64" ? "x64" : null;
+    if (!assetArch) {
+      return {
+        kind: "unsupported",
+        reason: `no prebuilt whisper.cpp binaries for linux/${arch} — build whisper.cpp yourself and point WHISPER_CPP_BIN_DIR at the result`,
+      };
+    }
+    const assetName = `whisper-bin-ubuntu-${assetArch}.tar.gz`;
+    return {
+      kind: "tarball",
+      assetName,
+      url: `https://github.com/ggml-org/whisper.cpp/releases/download/v${WHISPER_CPP_VERSION}/${assetName}`,
+    };
+  }
+
+  return {
+    kind: "unsupported",
+    reason: `${platform} isn't supported for automatic install — install whisper.cpp yourself and point WHISPER_CPP_BIN_DIR at the directory holding ${binaryNameFor(model.engine)}`,
+  };
+}
+
+/**
+ * Build the full plan. Pure — safe to call for `--dry-run`.
+ *
+ * `modelId` undefined means "pick for this box": `pickDefaultModel` steps down
+ * from the recommended Parakeet on a machine that can't comfortably hold it.
+ * An explicitly-named model is honoured even when it's a stretch for the RAM,
+ * with a warning — the operator may know something we don't.
+ */
+export function planWhisperInstall(
+  modelId: string | undefined,
+  deps: PlanDeps = {},
+): WhisperInstallPlan {
+  const platform = deps.platform ?? process.platform;
+  const arch = deps.arch ?? process.arch;
+  const totalRamBytes = deps.totalRamBytes ?? totalmem();
+  const totalRamMb = Math.round(totalRamBytes / 1024 / 1024);
+  const env = deps.env ?? process.env;
+
+  const explicit = modelId !== undefined;
+  const model = explicit
+    ? findModel(modelId)
+    : pickDefaultModel(totalRamMb);
+
+  if (!model) {
+    // Unknown id — surface it as unsupported rather than silently defaulting,
+    // so a typo doesn't quietly install something else.
+    const fallback = findModel(DEFAULT_MODEL_ID)!;
+    return {
+      platform,
+      arch,
+      totalRamGb: Math.round((totalRamMb / 1024) * 10) / 10,
+      model: fallback,
+      modelExplicit: true,
+      binary: { kind: "unsupported", reason: `unknown model id "${modelId}"` },
+      modelPath: join(managedModelDir(env), fallback.filename),
+      binDir: managedBinDir(env),
+      supported: false,
+    };
+  }
+
+  const binary = planBinaryStrategy(model, deps);
+  const ramWarning =
+    totalRamMb < model.minRamMb
+      ? `${model.label} wants about ${Math.round(model.minRamMb / 1024)} GB of RAM and this box reports ${Math.round((totalRamMb / 1024) * 10) / 10} GB — it may swap or run slowly.`
+      : undefined;
+
+  return {
+    platform,
+    arch,
+    totalRamGb: Math.round((totalRamMb / 1024) * 10) / 10,
+    model,
+    modelExplicit: explicit,
+    binary,
+    modelPath: join(managedModelDir(env), model.filename),
+    binDir:
+      binary.kind === "already-present"
+        ? binary.path.slice(0, binary.path.lastIndexOf("/"))
+        : managedBinDir(env),
+    supported: binary.kind !== "unsupported",
+    ramWarning,
+  };
+}
+
+/** Human-readable plan, shared by `--dry-run` and the real run. */
+export function describeWhisperPlan(plan: WhisperInstallPlan): string[] {
+  const lines: string[] = [];
+  lines.push(`Host:   ${plan.platform}/${plan.arch}, ${plan.totalRamGb} GB RAM`);
+  lines.push(`Model:  ${plan.model.label} (${plan.model.sizeMb} MB)`);
+  lines.push(`        ${plan.model.note}`);
+  lines.push(`        → ${plan.modelPath}`);
+
+  switch (plan.binary.kind) {
+    case "already-present":
+      lines.push(`Engine: ${binaryNameFor(plan.model.engine)} already installed at ${plan.binary.path}`);
+      break;
+    case "homebrew":
+      lines.push(`Engine: brew install ${plan.binary.formula}  (installs whisper-cli + parakeet-cli)`);
+      break;
+    case "tarball":
+      lines.push(`Engine: download ${plan.binary.assetName}`);
+      lines.push(`        → ${plan.binDir}`);
+      break;
+    case "unsupported":
+      lines.push(`Engine: UNSUPPORTED — ${plan.binary.reason}`);
+      break;
+  }
+  if (plan.ramWarning) lines.push(`Note:   ${plan.ramWarning}`);
+  return lines;
+}

package/src/transcription/install-whisper-exec.test.ts

@@ -0,0 +1,244 @@
+/**
+ * The install executor.
+ *
+ * Driven through the spawn/download seams so no package manager runs and
+ * nothing is fetched. The behaviours worth pinning are the ones that decide
+ * whether an operator ends up with a working install or a convincing-looking
+ * broken one: refusing when brew is absent instead of emitting exit 127,
+ * never trusting a partial download, and failing the whole install when
+ * verification can't transcribe.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { planWhisperInstall } from "./install-whisper-cpp.ts";
+import {
+  ensureBinaries,
+  ensureModel,
+  silentWav16kMono,
+  verifyTranscription,
+} from "./install-whisper-exec.ts";
+import type { SpawnRunner } from "./providers/transcribe-cpp.ts";
+
+const GB = 1024 * 1024 * 1024;
+const env = { PARACHUTE_HOME: "/ph" } as NodeJS.ProcessEnv;
+
+const macPlan = () =>
+  planWhisperInstall(undefined, { platform: "darwin", arch: "arm64", totalRamBytes: 16 * GB, env });
+const tmpHomes: string[] = [];
+/** A Linux plan rooted in a real temp dir — the executor genuinely mkdirs. */
+const linuxPlan = () => {
+  const home = mkdtempSync(join(tmpdir(), "wcpp-install-"));
+  tmpHomes.push(home);
+  return planWhisperInstall(undefined, {
+    platform: "linux",
+    arch: "x64",
+    totalRamBytes: 8 * GB,
+    env: { PARACHUTE_HOME: home } as NodeJS.ProcessEnv,
+  });
+};
+
+afterEach(() => {
+  for (const h of tmpHomes.splice(0)) rmSync(h, { recursive: true, force: true });
+});
+
+/** A spawn that answers per-command from a lookup. */
+function spawnFor(map: Record<string, { exitCode?: number; stdout?: string; stderr?: string }>): SpawnRunner {
+  return async (cmd) => {
+    const key = Object.keys(map).find((k) => cmd.join(" ").includes(k));
+    const r = key ? map[key]! : {};
+    return { exitCode: r.exitCode ?? 0, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+  };
+}
+
+describe("ensureBinaries — macOS", () => {
+  test("no Homebrew → honest refusal, and brew install is never attempted", async () => {
+    // The alternative is an opaque exit 127 the operator has to decode.
+    let attempted = false;
+    const spawn: SpawnRunner = async (cmd) => {
+      if (cmd[1] === "install") attempted = true;
+      return { exitCode: cmd[1] === "--version" ? 1 : 0, stdout: "", stderr: "" };
+    };
+    const r = await ensureBinaries(macPlan(), { spawn });
+    expect(r.ok).toBe(false);
+    expect(r.message).toMatch(/Homebrew isn't installed/);
+    expect(r.message).toMatch(/brew\.sh/);
+    // And it explains WHY there's no alternative, so this doesn't read as laziness.
+    expect(r.message).toMatch(/no macOS CLI tarball|xcframework/);
+    expect(attempted).toBe(false);
+  });
+
+  test("brew present → installs the formula", async () => {
+    const r = await ensureBinaries(macPlan(), { spawn: spawnFor({}) });
+    expect(r.ok).toBe(true);
+    expect(r.message).toMatch(/whisper-cli \+ parakeet-cli/);
+  });
+
+  test("a failing brew install surfaces brew's own stderr", async () => {
+    const r = await ensureBinaries(macPlan(), {
+      spawn: spawnFor({ "brew install": { exitCode: 1, stderr: "No available formula" } }),
+    });
+    expect(r.ok).toBe(false);
+    expect(r.message).toMatch(/No available formula/);
+  });
+});
+
+describe("ensureBinaries — Linux", () => {
+  test("downloads + extracts, then confirms the binary really landed", async () => {
+    const seen: string[] = [];
+    // Model the real sequence: the binary is ABSENT before extraction and
+    // present after. A flat `true` would short-circuit at the already-present
+    // check and never download at all.
+    let extracted = false;
+    const r = await ensureBinaries(linuxPlan(), {
+      spawn: async (cmd) => {
+        if (cmd[0] === "tar") extracted = true;
+        return { exitCode: 0, stdout: "", stderr: "" };
+      },
+      download: async (url) => {
+        seen.push(url);
+      },
+      existsImpl: (p) => extracted && p.endsWith("parakeet-cli"),
+    });
+    expect(r.ok).toBe(true);
+    expect(seen[0]).toContain("whisper-bin-ubuntu-x64.tar.gz");
+  });
+
+  test("extraction that doesn't produce the binary is a FAILURE, not a shrug", async () => {
+    // Otherwise the install reports success and the first transcription is
+    // the thing that discovers the truth.
+    const r = await ensureBinaries(linuxPlan(), {
+      spawn: spawnFor({}),
+      download: async () => {},
+      existsImpl: () => false,
+    });
+    expect(r.ok).toBe(false);
+    expect(r.message).toMatch(/isn't in/);
+  });
+
+  test("a tar failure surfaces tar's stderr", async () => {
+    const r = await ensureBinaries(linuxPlan(), {
+      spawn: spawnFor({ tar: { exitCode: 2, stderr: "unexpected EOF" } }),
+      download: async () => {},
+      existsImpl: () => false,
+    });
+    expect(r.ok).toBe(false);
+    expect(r.message).toMatch(/unexpected EOF/);
+  });
+});
+
+describe("ensureBinaries — short circuits", () => {
+  test("already-present skips every package manager", async () => {
+    let spawned = false;
+    const plan = planWhisperInstall(undefined, {
+      platform: "darwin",
+      arch: "arm64",
+      totalRamBytes: 16 * GB,
+      env,
+      resolveExisting: () => "/opt/homebrew/bin/parakeet-cli",
+    });
+    const r = await ensureBinaries(plan, {
+      spawn: async () => {
+        spawned = true;
+        return { exitCode: 0, stdout: "", stderr: "" };
+      },
+    });
+    expect(r.ok).toBe(true);
+    expect(spawned).toBe(false);
+  });
+
+  test("an unsupported host fails with the planner's reason", async () => {
+    const plan = planWhisperInstall(undefined, {
+      platform: "freebsd",
+      arch: "x64",
+      totalRamBytes: 8 * GB,
+      env,
+    });
+    const r = await ensureBinaries(plan, { spawn: spawnFor({}) });
+    expect(r.ok).toBe(false);
+    expect(r.message).toMatch(/WHISPER_CPP_BIN_DIR/);
+  });
+});
+
+describe("ensureModel", () => {
+  test("an existing model isn't re-downloaded", async () => {
+    let downloads = 0;
+    const r = await ensureModel(linuxPlan(), {
+      existsImpl: () => true,
+      download: async () => {
+        downloads += 1;
+      },
+    });
+    expect(r.ok).toBe(true);
+    expect(downloads).toBe(0);
+  });
+
+  test("downloads to a .part first — a truncated file must never look complete", async () => {
+    // A half-file at the real path would pass the readiness probe and then
+    // fail mysteriously at the first transcription.
+    const targets: string[] = [];
+    await ensureModel(linuxPlan(), {
+      existsImpl: () => false,
+      download: async (_url, dest) => {
+        targets.push(dest);
+        // Materialise it so the rename can succeed.
+        await Bun.write(dest, "x");
+      },
+    }).catch(() => {});
+    expect(targets[0]).toMatch(/\.part$/);
+  });
+});
+
+describe("verifyTranscription", () => {
+  test("a clean exit means verified", async () => {
+    const r = await verifyTranscription(linuxPlan(), "/bin/parakeet-cli", { spawn: spawnFor({}) });
+    expect(r.ok).toBe(true);
+  });
+
+  test("a non-zero exit FAILS the install and names the likely cause", async () => {
+    const r = await verifyTranscription(linuxPlan(), "/bin/parakeet-cli", {
+      spawn: spawnFor({ "parakeet-cli": { exitCode: 1, stderr: "failed to load model" } }),
+    });
+    expect(r.ok).toBe(false);
+    expect(r.message).toMatch(/truncated download or a model\/binary mismatch/);
+    expect(r.message).toMatch(/failed to load model/);
+  });
+
+  test("engine picks the flags — whisper needs -nt, parakeet has no such flag", async () => {
+    let seen: string[] = [];
+    const capture: SpawnRunner = async (cmd) => {
+      seen = cmd;
+      return { exitCode: 0, stdout: "", stderr: "" };
+    };
+    await verifyTranscription(
+      planWhisperInstall("whisper-base.en", { platform: "linux", arch: "x64", totalRamBytes: 8 * GB, env }),
+      "/bin/whisper-cli",
+      { spawn: capture },
+    );
+    expect(seen).toContain("-nt");
+
+    await verifyTranscription(linuxPlan(), "/bin/parakeet-cli", { spawn: capture });
+    expect(seen).not.toContain("-nt");
+  });
+});
+
+describe("silentWav16kMono", () => {
+  test("is a valid RIFF/WAVE header at 16 kHz mono 16-bit", () => {
+    // Hand-built so verification doesn't depend on ffmpeg — the very tool
+    // whose absence we're trying to report clearly elsewhere.
+    const wav = silentWav16kMono(1);
+    const dv = new DataView(wav.buffer);
+    expect(String.fromCharCode(...wav.slice(0, 4))).toBe("RIFF");
+    expect(String.fromCharCode(...wav.slice(8, 12))).toBe("WAVE");
+    expect(dv.getUint16(22, true)).toBe(1); // mono
+    expect(dv.getUint32(24, true)).toBe(16000); // sample rate
+    expect(dv.getUint16(34, true)).toBe(16); // bits
+    expect(wav.length).toBe(44 + 16000 * 2);
+  });
+
+  test("a zero/negative duration still yields a structurally valid file", () => {
+    expect(silentWav16kMono(0).length).toBeGreaterThan(44);
+  });
+});