@openparachute/vault 0.6.4 → 0.6.5-rc.10

package/src/transcription/build.test.ts

@@ -0,0 +1,224 @@
+import { describe, test, expect } from "bun:test";
+import { join } from "path";
+import {
+  buildTranscribeCli,
+  buildCompileCommand,
+  detectCompiler,
+  compilerInstallHint,
+  cliSourceUrl,
+  CLI_SOURCE_FILES,
+  CXX_CANDIDATES,
+  TRANSCRIBE_CPP_SOURCE_REF,
+  type BuildCliDeps,
+  type CompileResult,
+} from "./build.ts";
+
+/**
+ * transcribe-cli build tests (scribe-fold Phase 2b). Pure recipe shape +
+ * fully-mocked orchestration — NO network, NO real compiler (the real compile
+ * is exercised only by the install-time live verify). Covers the toolchain-
+ * absent, fetch-failure, compile-failure, and success branches, and the
+ * "never leave a half-built binary" invariant.
+ */
+
+describe("detectCompiler", () => {
+  test("returns the first candidate found (c++ preferred)", () => {
+    const which = (c: string) => (c === "c++" ? "/usr/bin/c++" : null);
+    expect(detectCompiler(which)).toBe("/usr/bin/c++");
+  });
+  test("falls through to a later candidate when earlier ones are absent", () => {
+    const which = (c: string) => (c === "g++" ? "/usr/bin/g++" : null);
+    expect(detectCompiler(which)).toBe("/usr/bin/g++");
+  });
+  test("returns null when NO compiler is on PATH", () => {
+    expect(detectCompiler(() => null)).toBeNull();
+    expect(detectCompiler(() => undefined)).toBeNull();
+  });
+  test("probes the documented candidate order", () => {
+    expect([...CXX_CANDIDATES]).toEqual(["c++", "clang++", "g++"]);
+  });
+});
+
+describe("compilerInstallHint", () => {
+  test("macOS → xcode-select", () => {
+    expect(compilerInstallHint("darwin")).toContain("xcode-select --install");
+  });
+  test("linux → build-essential / gcc-c++", () => {
+    const h = compilerInstallHint("linux");
+    expect(h).toContain("build-essential");
+    expect(h).toContain("gcc-c++");
+  });
+  test("other → generic compiler hint", () => {
+    expect(compilerInstallHint("win32")).toContain("c++/clang++/g++");
+  });
+});
+
+describe("cliSourceUrl + CLI_SOURCE_FILES", () => {
+  test("URL pins the exact v0.1.1 source ref", () => {
+    const url = cliSourceUrl("examples/cli/main.cpp");
+    expect(url).toContain("raw.githubusercontent.com/handy-computer/transcribe.cpp");
+    expect(url).toContain(TRANSCRIBE_CPP_SOURCE_REF);
+    expect(url.endsWith("/examples/cli/main.cpp")).toBe(true);
+  });
+  test("source set covers the CLI + WAV loader + public header", () => {
+    expect(CLI_SOURCE_FILES).toContain("examples/cli/main.cpp");
+    expect(CLI_SOURCE_FILES).toContain("examples/common/wav.cpp");
+    expect(CLI_SOURCE_FILES).toContain("examples/common/wav.h");
+    expect(CLI_SOURCE_FILES).toContain("examples/common/dr_wav.h");
+    expect(CLI_SOURCE_FILES).toContain("include/transcribe.h");
+    // headers main.cpp includes directly
+    expect(CLI_SOURCE_FILES).toContain("include/transcribe/parakeet.h");
+    expect(CLI_SOURCE_FILES).toContain("include/transcribe/whisper.h");
+    expect(CLI_SOURCE_FILES).toContain("include/transcribe/voxtral_realtime.h");
+  });
+});
+
+describe("buildCompileCommand — the proven recipe shape", () => {
+  const base = {
+    compiler: "/usr/bin/c++",
+    srcDir: "/root/.parachute/transcription/.src",
+    libsDir: "/root/.parachute/transcription/libs",
+    outPath: "/root/.parachute/transcription/bin/transcribe-cli",
+  };
+
+  test("macOS → @loader_path/../libs rpath", () => {
+    const cmd = buildCompileCommand({ ...base, platform: "darwin" });
+    expect(cmd[0]).toBe("/usr/bin/c++");
+    expect(cmd).toContain("-std=c++17");
+    expect(cmd).toContain(`-I${join(base.srcDir, "include")}`);
+    expect(cmd).toContain(`-I${join(base.srcDir, "examples", "common")}`);
+    expect(cmd).toContain(join(base.srcDir, "examples", "cli", "main.cpp"));
+    expect(cmd).toContain(join(base.srcDir, "examples", "common", "wav.cpp"));
+    expect(cmd).toContain(`-L${base.libsDir}`);
+    expect(cmd).toContain("-ltranscribe");
+    expect(cmd).toContain("-Wl,-rpath,@loader_path/../libs");
+    // output is the final -o <path>
+    expect(cmd[cmd.length - 2]).toBe("-o");
+    expect(cmd[cmd.length - 1]).toBe(base.outPath);
+  });
+
+  test("Linux → $ORIGIN/../libs rpath (literal — passed to argv, not a shell)", () => {
+    const cmd = buildCompileCommand({ ...base, platform: "linux" });
+    expect(cmd).toContain("-Wl,-rpath,$ORIGIN/../libs");
+    expect(cmd).not.toContain("-Wl,-rpath,@loader_path/../libs");
+  });
+});
+
+/** Build a deps object with call-recording mocks; overrides win. */
+function mkDeps(over: Partial<BuildCliDeps> = {}): BuildCliDeps & {
+  calls: { fetch: number; compile: number; removed: string[]; renamed: Array<[string, string]> };
+} {
+  const calls = { fetch: 0, compile: 0, removed: [] as string[], renamed: [] as Array<[string, string]> };
+  const deps: BuildCliDeps = {
+    platform: "darwin",
+    which: (c) => (c === "c++" ? "/usr/bin/c++" : null),
+    fetchSource: async () => {
+      calls.fetch++;
+    },
+    compile: async (): Promise<CompileResult> => {
+      calls.compile++;
+      return { exitCode: 0, stderr: "" };
+    },
+    exists: () => true,
+    removeBin: (p) => {
+      calls.removed.push(p);
+    },
+    rename: (from, to) => {
+      calls.renamed.push([from, to]);
+    },
+    ...over,
+  };
+  return Object.assign(deps, { calls });
+}
+
+const INPUT = { srcDir: "/t/.src", libsDir: "/t/libs", binPath: "/t/bin/transcribe-cli" };
+const TMP = `${INPUT.binPath}.building`; // the temp output the build compiles to
+
+describe("buildTranscribeCli — orchestration branches", () => {
+  test("SUCCESS: fetch → compile ok → temp exists ⇒ promote (rename) + { ok:true }", async () => {
+    const deps = mkDeps();
+    const r = await buildTranscribeCli(INPUT, deps);
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.binPath).toBe(INPUT.binPath);
+      expect(r.compiler).toBe("/usr/bin/c++");
+      // reported command targets the FINAL binPath (reproducible by hand), not the temp
+      expect(r.command).toContain("-ltranscribe");
+      expect(r.command).toContain(`-o ${INPUT.binPath}`);
+      expect(r.command).not.toContain(TMP);
+    }
+    expect(deps.calls.fetch).toBe(1);
+    expect(deps.calls.compile).toBe(1);
+    // only the TEMP is cleared pre-compile; the fresh temp is renamed into place
+    expect(deps.calls.removed).toEqual([TMP]);
+    expect(deps.calls.renamed).toEqual([[TMP, INPUT.binPath]]);
+  });
+
+  test("TOOLCHAIN ABSENT: no compiler ⇒ { ok:false, stage:'toolchain' }, no fetch/compile", async () => {
+    const deps = mkDeps({ which: () => null });
+    const r = await buildTranscribeCli(INPUT, deps);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.stage).toBe("toolchain");
+      expect(r.message).toContain("no C++ compiler");
+      expect(r.message).toContain("xcode-select"); // darwin hint embedded
+    }
+    expect(deps.calls.fetch).toBe(0);
+    expect(deps.calls.compile).toBe(0);
+  });
+
+  test("FETCH FAILURE: fetchSource throws ⇒ { ok:false, stage:'fetch' }, no compile", async () => {
+    const deps = mkDeps({
+      fetchSource: async () => {
+        throw new Error("network down");
+      },
+    });
+    const r = await buildTranscribeCli(INPUT, deps);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.stage).toBe("fetch");
+      expect(r.message).toContain("network down");
+      expect(r.message).toContain(TRANSCRIBE_CPP_SOURCE_REF);
+    }
+    expect(deps.calls.compile).toBe(0);
+  });
+
+  test("COMPILE FAILURE (nonzero exit): keeps provider + surfaces stderr + command; only the temp is cleaned", async () => {
+    const deps = mkDeps({
+      compile: async () => ({ exitCode: 1, stderr: "main.cpp:9: fatal error: transcribe.h not found" }),
+    });
+    const r = await buildTranscribeCli(INPUT, deps);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.stage).toBe("compile");
+      expect(r.message).toContain("transcribe.h not found");
+      expect(r.command).toContain("-ltranscribe");
+    }
+    // ONLY the temp is touched (pre-clear + post-cleanup) — the real binPath is never removed
+    expect(deps.calls.removed).toEqual([TMP, TMP]);
+    expect(deps.calls.removed).not.toContain(INPUT.binPath);
+    expect(deps.calls.renamed).toEqual([]);
+  });
+
+  test("COMPILE 'succeeds' but output missing ⇒ { ok:false, stage:'compile' } + only temp cleaned", async () => {
+    const deps = mkDeps({ exists: () => false });
+    const r = await buildTranscribeCli(INPUT, deps);
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.stage).toBe("compile");
+    expect(deps.calls.removed).toEqual([TMP, TMP]);
+    expect(deps.calls.renamed).toEqual([]);
+  });
+
+  test("ATOMIC: a failed rebuild NEVER removes/renames the existing binary (--force safety)", async () => {
+    // Simulate an existing working binary present at binPath; the rebuild fails.
+    const deps = mkDeps({
+      exists: (p) => p === INPUT.binPath, // real binary exists; the temp never appears
+      compile: async () => ({ exitCode: 1, stderr: "boom" }),
+    });
+    const r = await buildTranscribeCli(INPUT, deps);
+    expect(r.ok).toBe(false);
+    // The existing binary is untouched: no removeBin/rename ever names binPath.
+    expect(deps.calls.removed).not.toContain(INPUT.binPath);
+    expect(deps.calls.renamed).toEqual([]);
+  });
+});

package/src/transcription/build.ts

@@ -0,0 +1,252 @@
+/**
+ * Building `transcribe-cli` from source at install time (scribe-fold Phase 2b).
+ *
+ * transcribe.cpp v0.1.1 ships a **library** (`libtranscribe.{dylib,so}` +
+ * `libggml*`), NOT a prebuilt `transcribe-cli` executable — see
+ * `install.ts` + the provider-seam design doc. This module closes that gap: it
+ * fetches the CLI's source (`examples/cli/main.cpp` + `examples/common/wav.cpp`
+ * + the public headers) from the transcribe.cpp repo pinned at the v0.1.1 tag
+ * commit, then compiles it with the host C++ compiler against the extracted
+ * prebuilt dylibs. The result is a ~127KB driver that links the prebuilt
+ * `libtranscribe` at runtime — **no ggml / Metal rebuild**.
+ *
+ * ## The proven recipe (live-verified 2026-07-03, macOS arm64 M4)
+ *
+ *   c++ -std=c++17 -O2 \
+ *     -I<srcDir>/include \
+ *     -I<srcDir>/examples/common \
+ *     <srcDir>/examples/cli/main.cpp \
+ *     <srcDir>/examples/common/wav.cpp \
+ *     -L<libsDir> -ltranscribe \
+ *     -Wl,-rpath,@loader_path/../libs \        # Linux: $ORIGIN/../libs
+ *     -o <binDir>/transcribe-cli
+ *
+ * The rpath is load-bearing: `libtranscribe.dylib`'s install_name is
+ * `@rpath/libtranscribe.dylib` (with no rpath of its own), so the CLI carries
+ * `@loader_path/../libs` to resolve it from a sibling `libs/` dir. In turn
+ * `libtranscribe` references `libggml*` via `@loader_path/libggml*.dylib`, so
+ * having all dylibs in the same `libs/` dir is enough — the CLI never needs to
+ * know about libggml. On Linux the analogous `$ORIGIN/../libs` is passed as a
+ * single argv element (we spawn the compiler directly, NOT through a shell, so
+ * `$ORIGIN` is NOT expanded — it lands literally in the ELF RUNPATH for the
+ * runtime loader to expand).
+ *
+ * ## Testability
+ *
+ * `buildTranscribeCli` is a pure orchestrator over injected side effects
+ * (`which` / `fetchSource` / `compile` / `exists` / `removeBin`), mirroring the
+ * provider's `SpawnRunner` seam. Tests exercise every branch — toolchain
+ * absent, fetch failure, compile failure, success — with no network and no real
+ * compiler. The real compile is exercised only by the install-time live verify.
+ */
+
+import { join } from "path";
+
+/**
+ * Pinned source ref for the CLI build: the transcribe.cpp **v0.1.1 tag commit**.
+ * Kept in lockstep with `TRANSCRIBE_CPP_VERSION` in `install.ts` — bump both
+ * together (a newer CLI source may need different headers or flags, and the
+ * provider's output parsing is validated against a specific version).
+ */
+export const TRANSCRIBE_CPP_SOURCE_REF = "d89ecb75062e8457681c563994675dc60e31db80";
+
+const RAW_BASE = `https://raw.githubusercontent.com/handy-computer/transcribe.cpp/${TRANSCRIBE_CPP_SOURCE_REF}`;
+
+/**
+ * Repo-relative source files needed to build `transcribe-cli`, laid out under a
+ * local source dir so the include paths resolve exactly as upstream expects.
+ * `main.cpp` includes `transcribe.h` + `transcribe/{parakeet,voxtral_realtime,
+ * whisper}.h` + `wav.h`; `wav.cpp` includes `wav.h` + `dr_wav.h`. We fetch the
+ * complete `include/` header set (the two extra sub-headers are tiny and keep
+ * the tree self-consistent). Verified sufficient by a real compile at this ref.
+ */
+export const CLI_SOURCE_FILES: readonly string[] = [
+  "include/transcribe.h",
+  "include/transcribe/extensions.h",
+  "include/transcribe/moonshine_streaming.h",
+  "include/transcribe/parakeet.h",
+  "include/transcribe/voxtral_realtime.h",
+  "include/transcribe/whisper.h",
+  "examples/common/wav.h",
+  "examples/common/wav.cpp",
+  "examples/common/dr_wav.h",
+  "examples/cli/main.cpp",
+];
+
+/** Full raw.githubusercontent URL for a repo-relative path at the pinned ref. */
+export function cliSourceUrl(repoPath: string): string {
+  return `${RAW_BASE}/${repoPath}`;
+}
+
+/** C++ compiler binaries we probe for, in preference order. */
+export const CXX_CANDIDATES = ["c++", "clang++", "g++"] as const;
+
+/**
+ * Resolve a C++ compiler path via the injected `which` (production:
+ * `Bun.which`). Returns the first candidate found, or `null` when none is on
+ * PATH — the caller keeps the current provider and prints a platform hint.
+ */
+export function detectCompiler(which: (cmd: string) => string | null | undefined): string | null {
+  for (const c of CXX_CANDIDATES) {
+    const p = which(c);
+    if (p) return p;
+  }
+  return null;
+}
+
+/** A short "install a compiler" hint tailored to the host platform. */
+export function compilerInstallHint(platform: string): string {
+  if (platform === "darwin") return "install the Xcode command-line tools: xcode-select --install";
+  if (platform === "linux") {
+    return "install a C++ toolchain: apt install build-essential (Debian/Ubuntu) | dnf install gcc-c++ (Fedora/RHEL)";
+  }
+  return "install a C++ compiler (c++/clang++/g++) on PATH";
+}
+
+export interface CompileCommandInput {
+  /** Host platform (`process.platform`) — selects the rpath flavor. */
+  platform: string;
+  /** Resolved compiler path (`detectCompiler`). */
+  compiler: string;
+  /** The local source dir the CLI sources were fetched into. */
+  srcDir: string;
+  /** The extracted prebuilt dylibs dir to link `-ltranscribe` from. */
+  libsDir: string;
+  /** Where the compiled `transcribe-cli` lands. */
+  outPath: string;
+}
+
+/**
+ * Build the compiler argv (the proven recipe). Pure — a test pins the shape,
+ * mirroring `buildTranscribeArgs` for the provider. The rpath resolves the
+ * sibling `libs/` dir from `bin/`: `@loader_path/../libs` (macOS) /
+ * `$ORIGIN/../libs` (Linux, passed literally — no shell expansion).
+ */
+export function buildCompileCommand(input: CompileCommandInput): string[] {
+  const includeDir = join(input.srcDir, "include");
+  const commonDir = join(input.srcDir, "examples", "common");
+  const mainCpp = join(input.srcDir, "examples", "cli", "main.cpp");
+  const wavCpp = join(input.srcDir, "examples", "common", "wav.cpp");
+  const rpath = input.platform === "darwin" ? "@loader_path/../libs" : "$ORIGIN/../libs";
+  return [
+    input.compiler,
+    "-std=c++17",
+    "-O2",
+    `-I${includeDir}`,
+    `-I${commonDir}`,
+    mainCpp,
+    wavCpp,
+    `-L${input.libsDir}`,
+    "-ltranscribe",
+    `-Wl,-rpath,${rpath}`,
+    "-o",
+    input.outPath,
+  ];
+}
+
+/** Result of running the compiler: exit code + captured stderr. */
+export interface CompileResult {
+  exitCode: number;
+  stderr: string;
+}
+
+/** Injected side effects for `buildTranscribeCli` (tests pass mocks). */
+export interface BuildCliDeps {
+  /** Host platform (`process.platform`). */
+  platform: string;
+  /** Compiler probe (production: `Bun.which`). */
+  which: (cmd: string) => string | null | undefined;
+  /** Fetch `files` (repo-relative) into `srcDir`. Throws on network failure. */
+  fetchSource: (files: readonly string[], srcDir: string) => Promise<void>;
+  /** Run the compiler argv. */
+  compile: (cmd: string[]) => CompileResult | Promise<CompileResult>;
+  /** Existence probe (production: `fs.existsSync`). */
+  exists: (p: string) => boolean;
+  /** Remove a stale / half-built binary (production: `fs.rmSync{force}`). */
+  removeBin: (p: string) => void;
+  /** Move a file into place (production: `fs.renameSync`). Used to promote the
+   *  freshly-built binary atomically, so a failed rebuild never clobbers a
+   *  previously working binary. */
+  rename: (from: string, to: string) => void;
+}
+
+export interface BuildCliInput {
+  /** Local dir to fetch the CLI sources into. */
+  srcDir: string;
+  /** The extracted prebuilt dylibs dir. */
+  libsDir: string;
+  /** Output binary path. */
+  binPath: string;
+}
+
+/** The outcome of a build attempt — a discriminated union the CLI branches on. */
+export type CliBuildResult =
+  | { ok: true; binPath: string; compiler: string; command: string }
+  | {
+      ok: false;
+      /** Which stage failed — drives the operator guidance. */
+      stage: "toolchain" | "fetch" | "compile";
+      message: string;
+      compiler?: string;
+      /** The compile argv (as a string) when we got far enough to build one. */
+      command?: string;
+    };
+
+/**
+ * Fetch the CLI source at the pinned ref and compile it against the extracted
+ * dylibs. Non-throwing: every failure is a typed `{ ok: false }` so the caller
+ * keeps the current provider and reports honestly. Never leaves a half-built
+ * binary — a nonzero compile (or a missing output) removes `binPath` so
+ * `available()` can't mistake a partial artifact for a runnable CLI.
+ */
+export async function buildTranscribeCli(
+  input: BuildCliInput,
+  deps: BuildCliDeps,
+): Promise<CliBuildResult> {
+  const compiler = detectCompiler(deps.which);
+  if (!compiler) {
+    return {
+      ok: false,
+      stage: "toolchain",
+      message: `no C++ compiler on PATH (looked for ${CXX_CANDIDATES.join(", ")}) — ${compilerInstallHint(deps.platform)}`,
+    };
+  }
+
+  try {
+    await deps.fetchSource(CLI_SOURCE_FILES, input.srcDir);
+  } catch (err) {
+    return {
+      ok: false,
+      stage: "fetch",
+      compiler,
+      message: `failed to fetch transcribe-cli source at ${TRANSCRIBE_CPP_SOURCE_REF}: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  const common = { platform: deps.platform, compiler, srcDir: input.srcDir, libsDir: input.libsDir };
+  // The reported command targets the FINAL binPath (what an operator would run
+  // by hand to reproduce). The actual compile writes to a temp sibling and is
+  // promoted on success — so a failed rebuild (e.g. `--force` that then fails)
+  // never clobbers a previously working binary, and no half-built artifact is
+  // ever left where available() would treat it as runnable. The temp is a
+  // sibling in the same dir, so the @loader_path/../libs rpath is unaffected.
+  const command = buildCompileCommand({ ...common, outPath: input.binPath }).join(" ");
+  const tmpOut = `${input.binPath}.building`;
+  const argv = buildCompileCommand({ ...common, outPath: tmpOut });
+
+  deps.removeBin(tmpOut); // clear any stale temp from a prior interrupted build
+  const res = await deps.compile(argv);
+  if (res.exitCode !== 0 || !deps.exists(tmpOut)) {
+    deps.removeBin(tmpOut); // drop any partial output; the existing binary stands
+    return {
+      ok: false,
+      stage: "compile",
+      compiler,
+      command,
+      message: (res.stderr || "").trim() || `compiler exited ${res.exitCode}`,
+    };
+  }
+
+  deps.rename(tmpOut, input.binPath); // atomic promote over any prior binary
+  return { ok: true, binPath: input.binPath, compiler, command };
+}

package/src/transcription/capability.test.ts

@@ -0,0 +1,118 @@
+import { describe, test, expect, afterEach } from "bun:test";
+import { resolveTranscriptionCapability, defaultTranscriptionProvider } from "./capability.ts";
+import { ScribeHttpProvider } from "./providers/scribe-http.ts";
+import { TranscribeCppProvider } from "./providers/transcribe-cpp.ts";
+import type { TranscriptionProvider } from "../../core/src/transcription/provider.ts";
+
+/**
+ * Capability-flag tests (scribe-fold Phase 1). The vault landing surfaces
+ * `transcription: { enabled, provider? }`; `enabled` iff a provider is
+ * configured AND available. Notes gates its mic on this.
+ */
+
+/** A minimal fake provider so tests don't depend on live scribe discovery. */
+function fakeProvider(available: boolean, name = "fake"): TranscriptionProvider {
+  return {
+    name,
+    available: async () => (available ? { ok: true } : { ok: false, reason: "off" }),
+    transcribe: async () => ({ text: "" }),
+  };
+}
+
+describe("resolveTranscriptionCapability", () => {
+  test("enabled:true + provider name when the provider is available", async () => {
+    const cap = await resolveTranscriptionCapability(fakeProvider(true, "scribe-http"));
+    expect(cap).toEqual({ enabled: true, provider: "scribe-http" });
+  });
+
+  test("enabled:false + no provider name when the provider is unavailable", async () => {
+    const cap = await resolveTranscriptionCapability(fakeProvider(false));
+    expect(cap).toEqual({ enabled: false });
+    expect(cap.provider).toBeUndefined();
+  });
+
+  test("no provider configured (scribe-http with no URL) resolves to disabled, no throw", async () => {
+    // The "no provider configured" path: a scribe-http provider whose URL is
+    // undefined reports unavailable rather than throwing, so the landing never
+    // crashes when scribe is absent.
+    const cap = await resolveTranscriptionCapability(new ScribeHttpProvider({ url: undefined }));
+    expect(cap.enabled).toBe(false);
+    expect(cap.provider).toBeUndefined();
+  });
+
+  test("a configured scribe-http provider resolves to enabled: scribe-http", async () => {
+    const cap = await resolveTranscriptionCapability(new ScribeHttpProvider({ url: "http://scribe.test" }));
+    expect(cap).toEqual({ enabled: true, provider: "scribe-http" });
+  });
+
+  test("never omits minutes_remaining as an unmetered self-host concern", async () => {
+    const cap = await resolveTranscriptionCapability(fakeProvider(true));
+    expect("minutes_remaining" in cap).toBe(false);
+  });
+
+  test("a transcribe-cpp provider (installed) resolves to enabled: transcribe-cpp", async () => {
+    // existsImpl stubs the binary + model as present so available() is ok
+    // without touching disk.
+    const p = new TranscribeCppProvider({
+      binPath: "/tc/transcribe-cli",
+      modelPath: "/tc/model.gguf",
+      existsImpl: () => true,
+    });
+    const cap = await resolveTranscriptionCapability(p);
+    expect(cap).toEqual({ enabled: true, provider: "transcribe-cpp" });
+  });
+
+  test("a transcribe-cpp provider (not installed) resolves to disabled", async () => {
+    const p = new TranscribeCppProvider({ binPath: "/tc/transcribe-cli", modelPath: "/tc/model.gguf", existsImpl: () => false });
+    const cap = await resolveTranscriptionCapability(p);
+    expect(cap.enabled).toBe(false);
+    expect(cap.provider).toBeUndefined();
+  });
+});
+
+/**
+ * `defaultTranscriptionProvider` honors `TRANSCRIPTION_PROVIDER` so the
+ * capability flag reflects whichever provider is configured (scribe-fold 2a).
+ */
+describe("defaultTranscriptionProvider — provider selection", () => {
+  const saved = process.env.TRANSCRIPTION_PROVIDER;
+  afterEach(() => {
+    if (saved === undefined) delete process.env.TRANSCRIPTION_PROVIDER;
+    else process.env.TRANSCRIPTION_PROVIDER = saved;
+  });
+
+  test("default (unset) → the scribe-http provider", () => {
+    delete process.env.TRANSCRIPTION_PROVIDER;
+    expect(defaultTranscriptionProvider().name).toBe("scribe-http");
+  });
+
+  test("TRANSCRIPTION_PROVIDER=transcribe-cpp → the transcribe-cpp provider", () => {
+    process.env.TRANSCRIPTION_PROVIDER = "transcribe-cpp";
+    expect(defaultTranscriptionProvider().name).toBe("transcribe-cpp");
+  });
+
+  test("TRANSCRIPTION_PROVIDER=parakeet-mlx → the parakeet-mlx provider (2b)", () => {
+    process.env.TRANSCRIPTION_PROVIDER = "parakeet-mlx";
+    expect(defaultTranscriptionProvider().name).toBe("parakeet-mlx");
+  });
+
+  test("TRANSCRIPTION_PROVIDER=onnx-asr → the onnx-asr provider (2b)", () => {
+    process.env.TRANSCRIPTION_PROVIDER = "onnx-asr";
+    expect(defaultTranscriptionProvider().name).toBe("onnx-asr");
+  });
+
+  test("an unconfigured python provider resolves to disabled (no throw)", async () => {
+    // No venv/PATH binary in a fresh env → available() is ok:false and the
+    // landing capability is {enabled:false} rather than a crash.
+    process.env.TRANSCRIPTION_PROVIDER = "parakeet-mlx";
+    const prevBin = process.env.PARAKEET_MLX_BIN;
+    process.env.PARAKEET_MLX_BIN = "/definitely/not/a/real/parakeet-mlx";
+    try {
+      const cap = await resolveTranscriptionCapability(defaultTranscriptionProvider());
+      expect(cap.enabled).toBe(false);
+    } finally {
+      if (prevBin === undefined) delete process.env.PARAKEET_MLX_BIN;
+      else process.env.PARAKEET_MLX_BIN = prevBin;
+    }
+  });
+});