@openparachute/vault 0.6.5-rc.2 → 0.6.5

package/src/transcription/select.test.ts

@@ -0,0 +1,299 @@
+import { describe, test, expect, afterEach } from "bun:test";
+import { mkdirSync, writeFileSync, rmSync, chmodSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import {
+  resolveTranscriptionProviderName,
+  resolveTranscribeCppPaths,
+  transcribeCppInstalled,
+  probeTranscribeCliRunnable,
+  readManifest,
+  transcriptionHomeDir,
+  pythonVenvDir,
+  pythonManifestPath,
+  readPythonManifest,
+  resolveParakeetMlxBin,
+  resolveOnnxAsrBin,
+  resolveParakeetMlxModel,
+  resolveOnnxAsrModel,
+  parakeetMlxInstalled,
+  onnxAsrInstalled,
+  DEFAULT_PARAKEET_MLX_MODEL,
+  DEFAULT_ONNX_ASR_MODEL,
+} 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 parakeet-mlx / onnx-asr (scribe-fold Phase 2b)", () => {
+    expect(resolveTranscriptionProviderName({ TRANSCRIPTION_PROVIDER: "parakeet-mlx" }, silent)).toBe(
+      "parakeet-mlx",
+    );
+    expect(resolveTranscriptionProviderName({ TRANSCRIPTION_PROVIDER: "onnx-asr" }, silent)).toBe(
+      "onnx-asr",
+    );
+  });
+  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("probeTranscribeCliRunnable — EXECUTED, not stat'd (vault#534)", () => {
+  // Tiny real shell scripts stand in for transcribe-cli: the probe's whole
+  // point is that it actually runs the binary, so mocks would test nothing.
+  function script(home: string, body: string): string {
+    const p = join(home, "fake-cli");
+    writeFileSync(p, `#!/bin/sh\n${body}\n`);
+    chmodSync(p, 0o755);
+    return p;
+  }
+
+  test("exit 0 ⇒ ok", async () => {
+    const bin = script(mkTmpHome(), "exit 0");
+    expect(await probeTranscribeCliRunnable(bin)).toEqual({ ok: true });
+  });
+
+  test("nonzero exit ⇒ not ok, reason carries the exit code + first stderr line", async () => {
+    // Mirrors the vault#534 Linux failure shape: binary present + launches,
+    // but errors out (there: empty ggml backend registry, exit 1).
+    const bin = script(mkTmpHome(), 'echo "whisper: failed to initialize CPU backend" >&2\nexit 1');
+    const r = await probeTranscribeCliRunnable(bin);
+    expect(r.ok).toBe(false);
+    expect(r.reason).toContain("exited 1");
+    expect(r.reason).toContain("failed to initialize CPU backend");
+  });
+
+  test("unlaunchable binary (missing) ⇒ not ok with a reason", async () => {
+    const r = await probeTranscribeCliRunnable(join(mkTmpHome(), "no-such-cli"));
+    expect(r.ok).toBe(false);
+    expect(r.reason).toBeTruthy();
+  });
+
+  test("hang ⇒ not ok after the timeout", async () => {
+    const bin = script(mkTmpHome(), "sleep 30");
+    const r = await probeTranscribeCliRunnable(bin, { timeoutMs: 250 });
+    expect(r.ok).toBe(false);
+    expect(r.reason).toContain("250ms");
+  });
+});
+
+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");
+  });
+});
+
+// --- python providers (parakeet-mlx / onnx-asr) — scribe-fold Phase 2b ------
+
+describe("python provider bin resolution (env → venv → PATH)", () => {
+  const noHit = { existsImpl: () => false, whichImpl: () => null };
+
+  test("pythonVenvDir lives under the transcription home", () => {
+    expect(pythonVenvDir({ PARACHUTE_HOME: "/h" })).toBe(join("/h", "transcription", "venv"));
+  });
+
+  test("env override wins and is returned verbatim (existence is the caller's check)", () => {
+    expect(resolveParakeetMlxBin({ PARACHUTE_HOME: "/h", PARAKEET_MLX_BIN: "/opt/pk" }, noHit)).toBe("/opt/pk");
+    expect(resolveOnnxAsrBin({ PARACHUTE_HOME: "/h", ONNX_ASR_BIN: "/opt/ox" }, noHit)).toBe("/opt/ox");
+  });
+
+  test("managed venv binary beats PATH", () => {
+    const venvPk = join("/h", "transcription", "venv", "bin", "parakeet-mlx");
+    const bin = resolveParakeetMlxBin(
+      { PARACHUTE_HOME: "/h" },
+      { existsImpl: (p) => p === venvPk, whichImpl: () => "/usr/local/bin/parakeet-mlx" },
+    );
+    expect(bin).toBe(venvPk);
+  });
+
+  test("falls back to PATH when no venv binary exists", () => {
+    const bin = resolveOnnxAsrBin(
+      { PARACHUTE_HOME: "/h" },
+      { existsImpl: () => false, whichImpl: (b) => (b === "onnx-asr" ? "/usr/local/bin/onnx-asr" : null) },
+    );
+    expect(bin).toBe("/usr/local/bin/onnx-asr");
+  });
+
+  test("nothing anywhere → undefined (provider reports unavailable)", () => {
+    expect(resolveParakeetMlxBin({ PARACHUTE_HOME: "/h" }, noHit)).toBeUndefined();
+    expect(resolveOnnxAsrBin({ PARACHUTE_HOME: "/h" }, noHit)).toBeUndefined();
+  });
+});
+
+describe("parakeetMlxInstalled / onnxAsrInstalled", () => {
+  test("true only when the resolved binary exists on disk", () => {
+    const home = mkTmpHome();
+    const env = { PARACHUTE_HOME: home };
+    expect(parakeetMlxInstalled(env, { whichImpl: () => null })).toBe(false);
+    expect(onnxAsrInstalled(env, { whichImpl: () => null })).toBe(false);
+
+    const binDir = join(home, "transcription", "venv", "bin");
+    mkdirSync(binDir, { recursive: true });
+    writeFileSync(join(binDir, "onnx-asr"), "#!/bin/sh\n");
+    expect(onnxAsrInstalled(env, { whichImpl: () => null })).toBe(true);
+    expect(parakeetMlxInstalled(env, { whichImpl: () => null })).toBe(false);
+  });
+
+  test("an env override pointing at a missing file is NOT installed (honesty)", () => {
+    const home = mkTmpHome();
+    expect(
+      onnxAsrInstalled({ PARACHUTE_HOME: home, ONNX_ASR_BIN: "/nope/onnx-asr" }, { whichImpl: () => null }),
+    ).toBe(false);
+  });
+});
+
+describe("python model resolution (env → manifest → ratified default)", () => {
+  test("defaults are the ratified v3 models", () => {
+    const home = mkTmpHome();
+    expect(resolveParakeetMlxModel({ PARACHUTE_HOME: home })).toBe(DEFAULT_PARAKEET_MLX_MODEL);
+    expect(resolveOnnxAsrModel({ PARACHUTE_HOME: home })).toBe(DEFAULT_ONNX_ASR_MODEL);
+  });
+
+  test("env overrides win", () => {
+    const home = mkTmpHome();
+    expect(resolveParakeetMlxModel({ PARACHUTE_HOME: home, PARAKEET_MLX_MODEL: "mlx-community/custom" })).toBe(
+      "mlx-community/custom",
+    );
+    expect(resolveOnnxAsrModel({ PARACHUTE_HOME: home, ONNX_ASR_MODEL: "whisper-base" })).toBe("whisper-base");
+  });
+
+  test("the install manifest's model applies to ITS provider only", () => {
+    const home = mkTmpHome();
+    const tcDir = join(home, "transcription");
+    mkdirSync(tcDir, { recursive: true });
+    writeFileSync(
+      join(tcDir, "install-python.json"),
+      JSON.stringify({ provider: "onnx-asr", model: "manifest-model" }),
+    );
+    expect(resolveOnnxAsrModel({ PARACHUTE_HOME: home })).toBe("manifest-model");
+    // A parakeet lookup ignores an onnx manifest.
+    expect(resolveParakeetMlxModel({ PARACHUTE_HOME: home })).toBe(DEFAULT_PARAKEET_MLX_MODEL);
+  });
+});
+
+describe("readPythonManifest", () => {
+  test("returns null for a missing manifest", () => {
+    const home = mkTmpHome();
+    expect(readPythonManifest(pythonManifestPath({ PARACHUTE_HOME: home }))).toBeNull();
+  });
+  test("parses a written manifest", () => {
+    const home = mkTmpHome();
+    const tcDir = join(home, "transcription");
+    mkdirSync(tcDir, { recursive: true });
+    writeFileSync(
+      join(tcDir, "install-python.json"),
+      JSON.stringify({ provider: "parakeet-mlx", model: "m", pipTarget: "parakeet-mlx" }),
+    );
+    const m = readPythonManifest(pythonManifestPath({ PARACHUTE_HOME: home }));
+    expect(m?.provider).toBe("parakeet-mlx");
+  });
+});
+
+// --- 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,397 @@
+/**
+ * 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",
+  "parakeet-mlx",
+  "onnx-asr",
+] as const;
+export type TranscriptionProviderName = (typeof TRANSCRIPTION_PROVIDERS)[number];
+
+/**
+ * Default models for the Python-based local providers (scribe-fold Phase 2b —
+ * the ratified RAM-tier table, 2026-07-03).
+ *
+ *   - parakeet-mlx drives the `parakeet-mlx` CLI (MLX, Apple Silicon); the
+ *     model is an mlx-community HuggingFace repo fetched into the HF cache on
+ *     first use (~2.5GB).
+ *   - onnx-asr drives the `onnx-asr` CLI (ONNX Runtime, CPU); the model id is
+ *     onnx-asr's own registry name for NVIDIA Parakeet TDT 0.6b v3 (int8 ONNX,
+ *     ~670MB), fetched on first use / warm-pulled at install.
+ */
+export const DEFAULT_PARAKEET_MLX_MODEL = "mlx-community/parakeet-tdt-0.6b-v3";
+export const DEFAULT_ONNX_ASR_MODEL = "nemo-parakeet-tdt-0.6b-v3";
+
+/**
+ * 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);
+}
+
+/** Outcome of the EXECUTED runnable probe (`probeTranscribeCliRunnable`). */
+export interface RunnableProbeResult {
+  ok: boolean;
+  /** Why the probe failed, for the `runnable: no (<reason>)` print. */
+  reason?: string;
+}
+
+/**
+ * EXECUTED runnable probe: actually launch `transcribe-cli --help` and check
+ * the exit code. Cheap (no model load, no inference — upstream's `--help`
+ * prints usage and exits 0) but honest where a stat can't be: it catches a
+ * binary whose shared libraries don't resolve (broken/missing `libs/`, a bad
+ * rpath), a wrong-arch or corrupt binary, and a missing exec bit — all cases
+ * where `existsSync` says "yes" while every real run fails (the vault#534
+ * honesty bug: Linux installs reported `runnable: yes` while the CLI exited 1
+ * on every transcription).
+ *
+ * Deliberately NOT used by the per-request capability gate or the provider's
+ * `available()` (both are documented spawn-free); this is for the human-paced
+ * paths — `transcription status` and the install verb's activation check.
+ */
+export async function probeTranscribeCliRunnable(
+  binPath: string,
+  opts: { timeoutMs?: number } = {},
+): Promise<RunnableProbeResult> {
+  const timeoutMs = opts.timeoutMs ?? 10_000;
+  let proc: ReturnType<typeof Bun.spawn>;
+  try {
+    proc = Bun.spawn([binPath, "--help"], { stdin: "ignore", stdout: "ignore", stderr: "pipe" });
+  } catch (err) {
+    return {
+      ok: false,
+      reason: `could not launch ${binPath}: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    proc.kill("SIGKILL"); // diagnostic probe — no graceful shutdown to preserve
+  }, timeoutMs);
+  try {
+    const exitCode = await proc.exited;
+    if (timedOut) return { ok: false, reason: `--help did not exit within ${timeoutMs}ms` };
+    // stderr normally EOFs at exit; the race guards against a wrapper-script
+    // binary whose orphaned grandchild still holds the pipe open.
+    const stderr = await Promise.race([
+      new Response(proc.stderr as ReadableStream).text(),
+      new Promise<string>((resolve) => setTimeout(resolve, 2_000, "")),
+    ]);
+    const detail = stderr.trim().split("\n")[0]?.slice(0, 200);
+    if (proc.signalCode) {
+      // e.g. macOS dyld aborts with SIGABRT when a linked dylib is missing.
+      return { ok: false, reason: `--help died on ${proc.signalCode}${detail ? `: ${detail}` : ""}` };
+    }
+    if (exitCode !== 0) {
+      return { ok: false, reason: `--help exited ${exitCode}${detail ? `: ${detail}` : ""}` };
+    }
+    return { ok: true };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Python-based local providers (parakeet-mlx / onnx-asr) — scribe-fold 2b
+// ---------------------------------------------------------------------------
+
+/**
+ * The dedicated venv `transcription install` creates for the Python-based
+ * providers: `<root>/transcription/venv/`. A deliberate deviation from
+ * scribe's installer (which preferred `uv tool install` + a `~/.venvs`
+ * fallback and then had to caveat "add the venv to your PATH"): vault resolves
+ * the venv binary by ABSOLUTE path, so the daemon needs no PATH surgery and
+ * the whole install is sandboxed under `PARACHUTE_HOME` (tests, Docker).
+ */
+export function pythonVenvDir(env: NodeJS.ProcessEnv = process.env): string {
+  return join(transcriptionHomeDir(env), "venv");
+}
+
+/** `<root>/transcription/install-python.json` — the python-provider install manifest. */
+export function pythonManifestPath(env: NodeJS.ProcessEnv = process.env): string {
+  return join(transcriptionHomeDir(env), "install-python.json");
+}
+
+/** Persisted manifest for a python-provider install (written by `transcription install`). */
+export interface PythonInstallManifest {
+  /** Which provider this install set up ("parakeet-mlx" | "onnx-asr"). */
+  provider: string;
+  /** The pip install target (e.g. "onnx-asr[cpu,hub]"). */
+  pipTarget: string;
+  /** Resolved binary path at install time. */
+  bin: string;
+  /** The venv the package landed in ("" when the binary came from PATH). */
+  venv: string;
+  /** Model id the provider was configured with. */
+  model: string;
+  os: string;
+  arch: string;
+  ram_gb: number;
+  installedAt: string;
+}
+
+/** Read + parse the python install manifest, or `null` when absent/unreadable. */
+export function readPythonManifest(
+  manifestPath: string = pythonManifestPath(),
+): PythonInstallManifest | null {
+  try {
+    if (!existsSync(manifestPath)) return null;
+    const parsed = JSON.parse(readFileSync(manifestPath, "utf8")) as PythonInstallManifest;
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Injection seams for binary resolution (tests stub the fs + PATH probes). */
+export interface BinResolveDeps {
+  existsImpl?: (p: string) => boolean;
+  whichImpl?: (bin: string) => string | null;
+}
+
+/**
+ * Resolve a python-provider binary. Ladder (first hit wins):
+ *
+ *   1. an explicit env override (`PARAKEET_MLX_BIN` / `ONNX_ASR_BIN`) —
+ *      returned verbatim, existence-checked by the caller (mirrors
+ *      `TRANSCRIBE_CPP_BIN`'s contract);
+ *   2. the managed venv binary `<root>/transcription/venv/bin/<bin>` when it
+ *      exists (vault's own install — deterministic under the daemon);
+ *   3. a PATH-installed binary via `Bun.which` (an operator's own
+ *      `uv tool install` / pipx install keeps working).
+ *
+ * Returns `undefined` when nothing is found — the provider reports itself
+ * unavailable and the worker-boot gate stays closed.
+ */
+function resolvePythonBin(
+  envVar: string,
+  bin: string,
+  env: NodeJS.ProcessEnv,
+  deps: BinResolveDeps,
+): string | undefined {
+  const override = env[envVar]?.trim();
+  if (override) return override;
+  const exists = deps.existsImpl ?? existsSync;
+  const which = deps.whichImpl ?? ((b: string) => Bun.which(b));
+  const venvBin = join(pythonVenvDir(env), "bin", bin);
+  if (exists(venvBin)) return venvBin;
+  return which(bin) ?? undefined;
+}
+
+/** Resolve the `parakeet-mlx` binary (env `PARAKEET_MLX_BIN` → venv → PATH). */
+export function resolveParakeetMlxBin(
+  env: NodeJS.ProcessEnv = process.env,
+  deps: BinResolveDeps = {},
+): string | undefined {
+  return resolvePythonBin("PARAKEET_MLX_BIN", "parakeet-mlx", env, deps);
+}
+
+/** Resolve the `onnx-asr` binary (env `ONNX_ASR_BIN` → venv → PATH). */
+export function resolveOnnxAsrBin(
+  env: NodeJS.ProcessEnv = process.env,
+  deps: BinResolveDeps = {},
+): string | undefined {
+  return resolvePythonBin("ONNX_ASR_BIN", "onnx-asr", env, deps);
+}
+
+/** Model resolution: env override → install manifest → ratified default. */
+function resolvePythonModel(
+  envVar: string,
+  provider: string,
+  fallback: string,
+  env: NodeJS.ProcessEnv,
+): string {
+  const override = env[envVar]?.trim();
+  if (override) return override;
+  const manifest = readPythonManifest(pythonManifestPath(env));
+  if (manifest?.provider === provider && manifest.model) return manifest.model;
+  return fallback;
+}
+
+/** The parakeet-mlx model id (`PARAKEET_MLX_MODEL` → manifest → default v3). */
+export function resolveParakeetMlxModel(env: NodeJS.ProcessEnv = process.env): string {
+  return resolvePythonModel("PARAKEET_MLX_MODEL", "parakeet-mlx", DEFAULT_PARAKEET_MLX_MODEL, env);
+}
+
+/** The onnx-asr model id (`ONNX_ASR_MODEL` → manifest → default parakeet v3 int8). */
+export function resolveOnnxAsrModel(env: NodeJS.ProcessEnv = process.env): string {
+  return resolvePythonModel("ONNX_ASR_MODEL", "onnx-asr", DEFAULT_ONNX_ASR_MODEL, env);
+}
+
+/**
+ * Cheap, spawn-free readiness check for a python provider: a resolved binary
+ * that exists on disk. (The MODEL is fetched into the HF cache on first use —
+ * there is no cheap on-disk check for it, so readiness is binary-only,
+ * matching the providers' `available()`.) Used by the worker-boot gate and
+ * `transcription status`.
+ */
+export function parakeetMlxInstalled(
+  env: NodeJS.ProcessEnv = process.env,
+  deps: BinResolveDeps = {},
+): boolean {
+  const bin = resolveParakeetMlxBin(env, deps);
+  return !!bin && (deps.existsImpl ?? existsSync)(bin);
+}
+
+/** See `parakeetMlxInstalled`. */
+export function onnxAsrInstalled(
+  env: NodeJS.ProcessEnv = process.env,
+  deps: BinResolveDeps = {},
+): boolean {
+  const bin = resolveOnnxAsrBin(env, deps);
+  return !!bin && (deps.existsImpl ?? existsSync)(bin);
+}