@openparachute/vault 0.6.5-rc.9 → 0.6.5

package/src/transcription/select.test.ts

@@ -1,13 +1,25 @@
 import { describe, test, expect, afterEach } from "bun:test";
-import { mkdirSync, writeFileSync, rmSync } from "fs";
+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";
 
 /**
@@ -29,6 +41,14 @@ describe("resolveTranscriptionProviderName", () => {
       "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",
@@ -101,6 +121,45 @@ describe("transcribeCppInstalled", () => {
   });
 });
 
+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();
@@ -113,6 +172,112 @@ describe("readManifest", () => {
   });
 });
 
+// --- 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[] = [];

package/src/transcription/select.ts

@@ -30,9 +30,28 @@ import { join } from "path";
 import { homedir } from "os";
 import { existsSync, readFileSync } from "fs";
 
-export const TRANSCRIPTION_PROVIDERS = ["scribe-http", "transcribe-cpp"] as const;
+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
@@ -162,3 +181,217 @@ export function transcribeCppInstalled(
 ): 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);
+}

package/src/transcription/tiers.test.ts

@@ -0,0 +1,197 @@
+import { describe, test, expect } from "bun:test";
+import { selectDefaultProvider, NOMINAL_SLACK_GB, type TierPlan } from "./tiers.ts";
+import { DEFAULT_ONNX_ASR_MODEL, DEFAULT_PARAKEET_MLX_MODEL } from "./select.ts";
+
+/**
+ * The ratified RAM/arch/OS tier matrix (scribe-fold Phase 2b, 2026-07-03).
+ * Pure decision layer — no host probes, no network. The load-bearing
+ * invariants:
+ *
+ *   - macOS Apple Silicon 8GB+ → parakeet-mlx
+ *   - Linux 4GB+ → onnx-asr
+ *   - Linux ~2GB → transcribe-cpp with a SMALL WHISPER GGUF, never a Parakeet
+ *     variant (scribe#82: Parakeet peak RAM exceeds 2GB on meeting-length
+ *     audio → OOM)
+ *   - Linux ~1GB → remote default, tiny local model only as explicit opt-in
+ *   - below floor / unknown host → remote guidance, never a forced local pick
+ */
+
+const GB = 2 ** 30;
+
+function pick(platform: string, arch: string, gb: number): TierPlan {
+  return selectDefaultProvider({ platform, arch, totalRamBytes: gb * GB });
+}
+
+/** True when the plan's model is any Parakeet variant. */
+function isParakeet(plan: TierPlan): boolean {
+  return !!plan.model && /parakeet/i.test(plan.model);
+}
+
+describe("selectDefaultProvider — macOS Apple Silicon", () => {
+  test("darwin/arm64 8GB → parakeet-mlx (ratified default)", () => {
+    const plan = pick("darwin", "arm64", 8);
+    expect(plan.provider).toBe("parakeet-mlx");
+    expect(plan.model).toBe(DEFAULT_PARAKEET_MLX_MODEL);
+    expect(plan.approxDiskMb).toBe(2500);
+  });
+
+  test("darwin/arm64 16GB → parakeet-mlx", () => {
+    expect(pick("darwin", "arm64", 16).provider).toBe("parakeet-mlx");
+  });
+
+  test("darwin/arm64 just under 8GB nominal (7.7GB reported) → still parakeet-mlx (slack)", () => {
+    expect(pick("darwin", "arm64", 8 - NOMINAL_SLACK_GB).provider).toBe("parakeet-mlx");
+  });
+
+  test("darwin/arm64 well under 8GB → transcribe-cpp fallback, NOT parakeet-mlx", () => {
+    const plan = pick("darwin", "arm64", 6);
+    expect(plan.provider).toBe("transcribe-cpp");
+  });
+
+  test("darwin/x64 (Intel — no MLX) 16GB → transcribe-cpp fallback, never parakeet-mlx", () => {
+    const plan = pick("darwin", "x64", 16);
+    expect(plan.provider).toBe("transcribe-cpp");
+  });
+});
+
+describe("selectDefaultProvider — Linux", () => {
+  test("linux/x64 4GB → onnx-asr (ratified default)", () => {
+    const plan = pick("linux", "x64", 4);
+    expect(plan.provider).toBe("onnx-asr");
+    expect(plan.model).toBe(DEFAULT_ONNX_ASR_MODEL);
+    expect(plan.approxDiskMb).toBe(670);
+  });
+
+  test("linux/x64 8GB → onnx-asr, NOT parakeet-mlx (MLX is Apple-only)", () => {
+    expect(pick("linux", "x64", 8).provider).toBe("onnx-asr");
+  });
+
+  test("linux/arm64 4GB → onnx-asr", () => {
+    expect(pick("linux", "arm64", 4).provider).toBe("onnx-asr");
+  });
+
+  test("nominal-4GB box reporting 3.8GB (kernel reservation) → still onnx-asr (slack)", () => {
+    expect(pick("linux", "x64", 3.8).provider).toBe("onnx-asr");
+  });
+
+  test("linux 3.4GB (below the 4GB tier even with slack) → transcribe-cpp small whisper", () => {
+    const plan = pick("linux", "x64", 3.4);
+    expect(plan.provider).toBe("transcribe-cpp");
+    expect(plan.model).toBe("whisper-small.en");
+  });
+});
+
+describe("selectDefaultProvider — the 2GB-not-Parakeet floor (scribe#82)", () => {
+  test("linux 2GB → transcribe-cpp whisper-small.en — NEVER a Parakeet variant", () => {
+    const plan = pick("linux", "x64", 2);
+    expect(plan.provider).toBe("transcribe-cpp");
+    expect(plan.model).toBe("whisper-small.en");
+    expect(isParakeet(plan)).toBe(false);
+    expect(plan.reason).toContain("scribe#82");
+  });
+
+  test("nominal-2GB box reporting 1.9GB → still the whisper-small tier (slack), not tiny/remote", () => {
+    const plan = pick("linux", "x64", 1.9);
+    expect(plan.provider).toBe("transcribe-cpp");
+    expect(plan.model).toBe("whisper-small.en");
+  });
+
+  test("the whole 2–4GB Linux band never defaults to any Parakeet variant", () => {
+    for (const gb of [1.7, 2, 2.5, 3, 3.5]) {
+      const plan = pick("linux", "x64", gb);
+      expect(isParakeet(plan)).toBe(false);
+      expect(plan.provider).not.toBe("onnx-asr");
+      expect(plan.provider).not.toBe("parakeet-mlx");
+    }
+  });
+
+  // Regression for the double-applied-slack bug (reviewer, PR #537): the
+  // transcribe-cpp fallback used to add NOMINAL_SLACK_GB a SECOND time before
+  // install.ts's 4GB Parakeet-GGUF floor, so a real-3.6GB Darwin box picked a
+  // ~3.5GB-peak Parakeet model (~0.1GB headroom — the scribe#82 OOM class).
+  // Slack belongs to tier-entry boundaries only, never to model-floor checks.
+  test("darwin/x64 in the 3.6–3.9GB band → whisper-small.en, NEVER a Parakeet variant", () => {
+    for (const gb of [3.6, 3.8, 3.9]) {
+      const plan = pick("darwin", "x64", gb);
+      expect(plan.provider).toBe("transcribe-cpp");
+      expect(plan.model).toBe("whisper-small.en");
+      expect(isParakeet(plan)).toBe(false);
+    }
+  });
+
+  test("darwin/arm64 in the 3.6–3.9GB band → whisper-small.en, NEVER a Parakeet variant", () => {
+    for (const gb of [3.6, 3.9]) {
+      const plan = pick("darwin", "arm64", gb);
+      expect(plan.provider).toBe("transcribe-cpp");
+      expect(plan.model).toBe("whisper-small.en");
+      expect(isParakeet(plan)).toBe(false);
+    }
+  });
+
+  test("darwin just over a TRUE 4GB → the un-inflated Phase 2a pick (parakeet GGUF)", () => {
+    // At a genuine ≥4GB, install.ts's own matrix governs — same model an
+    // explicit `--provider transcribe-cpp` install would choose.
+    for (const [arch, gb] of [["x64", 4], ["x64", 4.1], ["arm64", 4]] as const) {
+      const plan = pick("darwin", arch, gb);
+      expect(plan.provider).toBe("transcribe-cpp");
+      expect(plan.model).toBe("parakeet-tdt-0.6b-v3");
+    }
+  });
+});
+
+describe("selectDefaultProvider — the ~1GB remote tier", () => {
+  test("linux 1GB → scribe-http by default (never a forced local install)", () => {
+    const plan = pick("linux", "x64", 1);
+    expect(plan.provider).toBe("scribe-http");
+  });
+
+  test("linux 1GB carries the explicit whisper-tiny local opt-in", () => {
+    const plan = pick("linux", "x64", 1);
+    expect(plan.localOptIn).toBeDefined();
+    expect(plan.localOptIn!.provider).toBe("transcribe-cpp");
+    expect(plan.localOptIn!.model).toBe("whisper-tiny.en");
+  });
+
+  test("nominal-1GB box reporting 0.95GB → still the opt-in tier", () => {
+    expect(pick("linux", "x64", 0.95).localOptIn).toBeDefined();
+  });
+
+  test("linux 1.4GB (below the 2GB tier) → remote default + tiny opt-in", () => {
+    const plan = pick("linux", "x64", 1.4);
+    expect(plan.provider).toBe("scribe-http");
+    expect(plan.localOptIn?.model).toBe("whisper-tiny.en");
+  });
+});
+
+describe("selectDefaultProvider — below floor / unknown hosts", () => {
+  test("linux 0.5GB → remote guidance with NO local opt-in", () => {
+    const plan = pick("linux", "x64", 0.5);
+    expect(plan.provider).toBe("scribe-http");
+    expect(plan.localOptIn).toBeUndefined();
+  });
+
+  test("unknown platform (win32) → remote guidance regardless of RAM", () => {
+    const plan = pick("win32", "x64", 32);
+    expect(plan.provider).toBe("scribe-http");
+    expect(plan.localOptIn).toBeUndefined();
+    expect(plan.reason).toContain("win32");
+  });
+
+  test("unknown arch (linux/riscv64) → remote guidance", () => {
+    expect(pick("linux", "riscv64", 8).provider).toBe("scribe-http");
+  });
+});
+
+describe("selectDefaultProvider — plan shape", () => {
+  test("carries the host facts for the human print", () => {
+    const plan = pick("linux", "x64", 4);
+    expect(plan.platform).toBe("linux");
+    expect(plan.arch).toBe("x64");
+    expect(plan.totalRamGb).toBe(4);
+    expect(plan.reason.length).toBeGreaterThan(0);
+  });
+
+  test("rounds detected RAM to 1dp", () => {
+    expect(selectDefaultProvider({ platform: "linux", arch: "x64", totalRamBytes: 3.84 * GB }).totalRamGb).toBe(3.8);
+  });
+});