@openparachute/vault 0.6.5-rc.2 → 0.6.5-rc.9

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

package/src/transcription/select.test.ts

@@ -0,0 +1,134 @@
+import { describe, test, expect, afterEach } from "bun:test";
+import { mkdirSync, writeFileSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import {
+  resolveTranscriptionProviderName,
+  resolveTranscribeCppPaths,
+  transcribeCppInstalled,
+  readManifest,
+  transcriptionHomeDir,
+} from "./select.ts";
+
+/**
+ * Provider-selection + path-resolution tests (scribe-fold Phase 2a). All env is
+ * passed explicitly so the shared bun-test process isn't polluted.
+ */
+
+const silent = { warn: () => {} };
+
+describe("resolveTranscriptionProviderName", () => {
+  test("unset → scribe-http (behavior-preserving default)", () => {
+    expect(resolveTranscriptionProviderName({}, silent)).toBe("scribe-http");
+  });
+  test("blank → scribe-http", () => {
+    expect(resolveTranscriptionProviderName({ TRANSCRIPTION_PROVIDER: "  " }, silent)).toBe("scribe-http");
+  });
+  test("explicit transcribe-cpp", () => {
+    expect(resolveTranscriptionProviderName({ TRANSCRIPTION_PROVIDER: "transcribe-cpp" }, silent)).toBe(
+      "transcribe-cpp",
+    );
+  });
+  test("explicit scribe-http", () => {
+    expect(resolveTranscriptionProviderName({ TRANSCRIPTION_PROVIDER: "scribe-http" }, silent)).toBe(
+      "scribe-http",
+    );
+  });
+  test("unknown value → warns + falls back to scribe-http", () => {
+    let warned = false;
+    const name = resolveTranscriptionProviderName(
+      { TRANSCRIPTION_PROVIDER: "whisper-magic" },
+      { warn: () => (warned = true) },
+    );
+    expect(name).toBe("scribe-http");
+    expect(warned).toBe(true);
+  });
+});
+
+describe("transcriptionHomeDir + resolveTranscribeCppPaths — PARACHUTE_HOME + overrides", () => {
+  test("honors PARACHUTE_HOME", () => {
+    const dir = transcriptionHomeDir({ PARACHUTE_HOME: "/custom/home" });
+    expect(dir).toBe(join("/custom/home", "transcription"));
+  });
+
+  test("default binPath/modelsDir under the transcription dir", () => {
+    const paths = resolveTranscribeCppPaths({ PARACHUTE_HOME: "/h" });
+    expect(paths.binPath).toBe(join("/h", "transcription", "bin", "transcribe-cli"));
+    expect(paths.modelsDir).toBe(join("/h", "transcription", "models"));
+    expect(paths.manifestPath).toBe(join("/h", "transcription", "install.json"));
+  });
+
+  test("TRANSCRIBE_CPP_BIN + TRANSCRIBE_CPP_MODEL env overrides win", () => {
+    const paths = resolveTranscribeCppPaths({
+      PARACHUTE_HOME: "/h",
+      TRANSCRIBE_CPP_BIN: "/opt/tc",
+      TRANSCRIBE_CPP_MODEL: "/models/custom.gguf",
+    });
+    expect(paths.binPath).toBe("/opt/tc");
+    expect(paths.modelPath).toBe("/models/custom.gguf");
+  });
+
+  test("model path resolves from the install manifest when no env override", () => {
+    const home = mkTmpHome();
+    writeManifest(home, { modelFile: "whisper-small.en-Q5_K_M.gguf", model: "whisper-small.en" });
+    const paths = resolveTranscribeCppPaths({ PARACHUTE_HOME: home });
+    expect(paths.modelPath).toBe(join(home, "transcription", "models", "whisper-small.en-Q5_K_M.gguf"));
+  });
+
+  test("no manifest, no env → modelPath undefined", () => {
+    const home = mkTmpHome();
+    expect(resolveTranscribeCppPaths({ PARACHUTE_HOME: home }).modelPath).toBeUndefined();
+  });
+});
+
+describe("transcribeCppInstalled", () => {
+  test("true only when both binary AND model exist on disk", () => {
+    const home = mkTmpHome();
+    const tcDir = join(home, "transcription");
+    mkdirSync(join(tcDir, "bin"), { recursive: true });
+    mkdirSync(join(tcDir, "models"), { recursive: true });
+    // Neither present yet.
+    expect(transcribeCppInstalled(resolveTranscribeCppPaths({ PARACHUTE_HOME: home }))).toBe(false);
+
+    // Binary only → still false.
+    writeFileSync(join(tcDir, "bin", "transcribe-cli"), "#!/bin/sh\n");
+    writeManifest(home, { modelFile: "m.gguf", model: "whisper-tiny.en" });
+    expect(transcribeCppInstalled(resolveTranscribeCppPaths({ PARACHUTE_HOME: home }))).toBe(false);
+
+    // Model too → true.
+    writeFileSync(join(tcDir, "models", "m.gguf"), "gguf");
+    expect(transcribeCppInstalled(resolveTranscribeCppPaths({ PARACHUTE_HOME: home }))).toBe(true);
+  });
+});
+
+describe("readManifest", () => {
+  test("returns null for a missing/unreadable manifest", () => {
+    expect(readManifest(join(tmpdir(), "does-not-exist-xyz.json"))).toBeNull();
+  });
+  test("parses a written manifest", () => {
+    const home = mkTmpHome();
+    writeManifest(home, { model: "whisper-tiny.en", modelFile: "t.gguf" });
+    const m = readManifest(join(home, "transcription", "install.json"));
+    expect(m?.model).toBe("whisper-tiny.en");
+  });
+});
+
+// --- helpers ---------------------------------------------------------------
+
+const tmpHomes: string[] = [];
+afterEach(() => {
+  for (const h of tmpHomes.splice(0)) rmSync(h, { recursive: true, force: true });
+});
+
+function mkTmpHome(): string {
+  const home = join(tmpdir(), `tc-select-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(home, { recursive: true });
+  tmpHomes.push(home);
+  return home;
+}
+
+function writeManifest(home: string, fields: Record<string, unknown>): void {
+  const tcDir = join(home, "transcription");
+  mkdirSync(tcDir, { recursive: true });
+  writeFileSync(join(tcDir, "install.json"), JSON.stringify(fields));
+}

package/src/transcription/select.ts

@@ -0,0 +1,164 @@
+/**
+ * Transcription provider selection + `transcribe-cpp` path resolution
+ * (scribe-fold Phase 2a).
+ *
+ * Vault now ships TWO transcription providers behind the Phase 1
+ * `TranscriptionProvider` seam:
+ *
+ *   - `scribe-http` — the remote/compat provider (the DEFAULT; existing scribe
+ *     installs are unchanged);
+ *   - `transcribe-cpp` — a local, no-Python provider that subprocesses the
+ *     prebuilt `transcribe-cli` (opt-in via `transcription install` + config).
+ *
+ * The active provider is chosen by the `TRANSCRIPTION_PROVIDER` env var
+ * (persisted in `~/.parachute/vault/.env`), resolved here so the worker boot
+ * (`server.ts`) and the capability flag (`capability.ts`) agree on one source
+ * of truth. Unset ⇒ `scribe-http`, so no config change means no behavior
+ * change.
+ *
+ * The `transcribe-cli` binary, GGUF model, and runtime shared libraries live
+ * under `$PARACHUTE_HOME/transcription/` (parallel to the vault's other
+ * ecosystem state), written there by `transcription install`. NOTE:
+ * transcribe.cpp v0.1.1 ships a *library*, not a prebuilt CLI, so after an
+ * install the `libs/` + `models/` are present but `bin/transcribe-cli` may be
+ * absent until a CLI is built or `TRANSCRIBE_CPP_BIN` is set — the readiness
+ * checks below gate on the binary existing. Paths are resolved per-call so
+ * `PARACHUTE_HOME` overrides (tests, Docker) apply.
+ */
+
+import { join } from "path";
+import { homedir } from "os";
+import { existsSync, readFileSync } from "fs";
+
+export const TRANSCRIPTION_PROVIDERS = ["scribe-http", "transcribe-cpp"] as const;
+export type TranscriptionProviderName = (typeof TRANSCRIPTION_PROVIDERS)[number];
+
+/**
+ * Resolve the configured provider name. `TRANSCRIPTION_PROVIDER` selects it;
+ * unset (or blank) ⇒ `scribe-http` (the behavior-preserving default). An
+ * unrecognized value warns once and falls back to `scribe-http` rather than
+ * failing boot — a typo shouldn't take transcription offline hard.
+ */
+export function resolveTranscriptionProviderName(
+  env: NodeJS.ProcessEnv = process.env,
+  logger: { warn?: (...args: unknown[]) => void } = console,
+): TranscriptionProviderName {
+  const raw = env.TRANSCRIPTION_PROVIDER?.trim();
+  if (!raw) return "scribe-http";
+  if ((TRANSCRIPTION_PROVIDERS as readonly string[]).includes(raw)) {
+    return raw as TranscriptionProviderName;
+  }
+  logger.warn?.(
+    `[transcribe] unknown TRANSCRIPTION_PROVIDER="${raw}" — falling back to scribe-http. ` +
+      `Valid values: ${TRANSCRIPTION_PROVIDERS.join(", ")}.`,
+  );
+  return "scribe-http";
+}
+
+/** The ecosystem root (shared with `config.ts`'s `configDirPath`), per-call so
+ * `PARACHUTE_HOME` overrides apply in tests / Docker. */
+function ecosystemRoot(env: NodeJS.ProcessEnv): string {
+  return env.PARACHUTE_HOME ?? join(homedir(), ".parachute");
+}
+
+/** The cache dir for transcribe-cpp's binary + models: `<root>/transcription/`. */
+export function transcriptionHomeDir(env: NodeJS.ProcessEnv = process.env): string {
+  return join(ecosystemRoot(env), "transcription");
+}
+
+/** Resolved filesystem locations for the transcribe-cpp install. */
+export interface TranscribeCppPaths {
+  /** `<root>/transcription/`. */
+  dir: string;
+  /** `<dir>/bin/`. */
+  binDir: string;
+  /** The `transcribe-cli` binary path (env `TRANSCRIBE_CPP_BIN` overrides).
+   *  May not exist on disk — v0.1.1 ships a library, not a CLI. */
+  binPath: string;
+  /** `<dir>/libs/` — the extracted runtime shared libraries (libtranscribe +
+   *  libggml) the CLI links against. */
+  libsDir: string;
+  /** `<dir>/models/`. */
+  modelsDir: string;
+  /** `<dir>/install.json` — the install manifest. */
+  manifestPath: string;
+  /**
+   * The active GGUF model path, or `undefined` when nothing is installed.
+   * Env `TRANSCRIBE_CPP_MODEL` overrides; otherwise resolved from the
+   * manifest's `modelFile` under `modelsDir`.
+   */
+  modelPath: string | undefined;
+}
+
+/** Persisted `install.json` shape (written by `transcription install`). */
+export interface TranscribeCppManifest {
+  version: string;
+  asset: string;
+  /** Binary filename under `bin/` (usually "transcribe-cli"). */
+  binFile: string;
+  /** Model id (e.g. "whisper-small.en"). */
+  model: string;
+  /** GGUF filename under `models/`. */
+  modelFile: string;
+  /** Runtime shared-library filenames extracted under `libs/` (libtranscribe +
+   *  libggml). v0.1.1 ships these instead of a CLI. */
+  libFiles?: string[];
+  /** When the `transcribe-cli` was built from source at install, the pinned
+   *  upstream source ref it was compiled from. Absent when no CLI was built
+   *  (build skipped/failed, or an operator-supplied `TRANSCRIBE_CPP_BIN`). */
+  binBuiltFrom?: string;
+  os: string;
+  arch: string;
+  ram_gb: number;
+  installedAt: string;
+}
+
+/**
+ * Resolve the transcribe-cpp binary + model paths. Env overrides
+ * (`TRANSCRIBE_CPP_BIN`, `TRANSCRIBE_CPP_MODEL`) win; otherwise the binary is
+ * `<dir>/bin/transcribe-cli` and the model comes from the install manifest.
+ */
+export function resolveTranscribeCppPaths(
+  env: NodeJS.ProcessEnv = process.env,
+): TranscribeCppPaths {
+  const dir = transcriptionHomeDir(env);
+  const binDir = join(dir, "bin");
+  const libsDir = join(dir, "libs");
+  const modelsDir = join(dir, "models");
+  const manifestPath = join(dir, "install.json");
+
+  const binPath = env.TRANSCRIBE_CPP_BIN?.trim() || join(binDir, "transcribe-cli");
+
+  let modelPath = env.TRANSCRIBE_CPP_MODEL?.trim() || undefined;
+  if (!modelPath) {
+    const manifest = readManifest(manifestPath);
+    if (manifest?.modelFile) modelPath = join(modelsDir, manifest.modelFile);
+  }
+
+  return { dir, binDir, binPath, libsDir, modelsDir, manifestPath, modelPath };
+}
+
+/** Read + parse the install manifest, or `null` when absent/unreadable. */
+export function readManifest(manifestPath: string): TranscribeCppManifest | null {
+  try {
+    if (!existsSync(manifestPath)) return null;
+    const parsed = JSON.parse(readFileSync(manifestPath, "utf8")) as TranscribeCppManifest;
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Cheap, spawn-free readiness check: a runnable `transcribe-cli` binary AND a
+ * model both exist on disk. Used by the worker-boot gate (`server.ts`) and
+ * mirrors the provider's `available()`. Because v0.1.1 ships a library (no CLI),
+ * this stays `false` after an install until a CLI is built or
+ * `TRANSCRIBE_CPP_BIN` points at one — so the worker never starts only to
+ * terminal-fail every item.
+ */
+export function transcribeCppInstalled(
+  paths: TranscribeCppPaths = resolveTranscribeCppPaths(),
+): boolean {
+  return existsSync(paths.binPath) && !!paths.modelPath && existsSync(paths.modelPath);
+}

package/src/transcription-worker.test.ts

@@ -140,6 +140,50 @@ describe("transcription worker", () => {
     expect(att.metadata?.transcript).toBe("hello world transcript");
   });
 
+  test("injected provider (scribe-fold 2a): worker routes audio→text through it, not scribe-http", async () => {
+    const note = await store.createNote(
+      "# 🎙️ Voice memo\n\n_Transcript pending._\n",
+      { id: "n1cpp", metadata: { transcribe_stub: true } },
+    );
+    seedAudio("memos/cpp.webm");
+    await store.addAttachment(note.id, "memos/cpp.webm", "audio/webm", {
+      transcribe_status: "pending",
+    });
+
+    // A fake local provider (stands in for transcribe-cpp). If the worker used
+    // it, the note gets this text; a `fetchImpl` that throws proves scribe-http
+    // was NOT called.
+    let called = 0;
+    const provider = {
+      name: "transcribe-cpp",
+      available: async () => ({ ok: true }),
+      transcribe: async () => {
+        called++;
+        return { text: "local transcript" };
+      },
+    };
+    const worker = startTranscriptionWorker({
+      vaultList: () => ["default"],
+      getStore: () => store as unknown as Store,
+      resolveAssetsDir: () => assetsRoot,
+      provider,
+      fetchImpl: (() => {
+        throw new Error("scribe-http must not be called when a provider is injected");
+      }) as unknown as typeof fetch,
+      pollIntervalMs: 10_000_000,
+      logger: silentLogger,
+    });
+    try {
+      expect(await worker.tick()).toBe(1);
+    } finally {
+      await worker.stop();
+    }
+
+    expect(called).toBe(1);
+    const updated = await store.getNote("n1cpp");
+    expect(updated!.content).toBe("# 🎙️ Voice memo\n\nlocal transcript\n");
+  });
+
   test("no-clobber: stub flag absent → does not touch note content", async () => {
     await store.createNote("my own edit", { id: "n2" });
     seedAudio("memos/b.webm");