@openparachute/vault 0.7.5 → 0.7.6-rc.2

package/src/mirror-routes.ts

@@ -91,6 +91,8 @@ import { redactToken } from "./export-watch.ts";
 import {
   findConflictingVault,
   remoteConflictMessage,
+  findUnrelatedRemoteHistory,
+  unrelatedHistoryMessage,
 } from "./mirror-remote-guard.ts";
 import { GitNotInstalledError, ensureGitAvailable } from "./git-preflight.ts";
 import { getVaultStore } from "./vault-store.ts";
@@ -1000,7 +1002,7 @@ export async function handleAuthPat(
 async function probeGitLsRemote(
   url: string,
   timeoutMs: number,
-): Promise<{ ok: boolean; error?: string }> {
+): Promise<{ ok: boolean; error?: string; heads?: string[] }> {
   // GIT_TERMINAL_PROMPT=0 ensures bad credentials FAIL FAST instead of
   // sitting at "Username:" indefinitely (which the timeout would then
   // catch, but failing fast on the auth wall is the better UX).
@@ -1025,7 +1027,18 @@ async function probeGitLsRemote(
   }, timeoutMs);
   const exitCode = await proc.exited;
   clearTimeout(timer);
-  if (exitCode === 0) return { ok: true };
+  if (exitCode === 0) {
+    // vault#823: the ref list answers "is this remote empty?", which is what
+    // the unrelated-history guard needs. We were already piping stdout and
+    // dropping it on the floor — the reachability answer and the emptiness
+    // answer come out of the same spawn.
+    const stdout = new TextDecoder().decode(await new Response(proc.stdout).arrayBuffer());
+    const heads = stdout
+      .split("\n")
+      .map((line) => line.split("\t")[0]?.trim() ?? "")
+      .filter((sha) => /^[0-9a-f]{40}$/.test(sha));
+    return { ok: true, heads };
+  }
   const stderr = new TextDecoder()
     .decode(await new Response(proc.stderr).arrayBuffer())
     .trim();
@@ -1736,6 +1749,13 @@ export async function handleMirrorImport(
   spawnOverride?: GitSpawn,
   whichOverride?: (cmd: string) => string | null,
   managerOverride?: MirrorManager,
+  // vault#823 test seam — the unrelated-history probe reaches the network
+  // (`git ls-remote`) on the sync-arm path. Inject one to keep import tests
+  // hermetic; production passes nothing and the real probe runs.
+  probeOverride?: (
+    url: string,
+    timeoutMs: number,
+  ) => Promise<{ ok: boolean; error?: string; heads?: string[] }>,
 ): Promise<Response> {
   let body: {
     remote_url?: unknown;
@@ -1939,6 +1959,7 @@ export async function handleMirrorImport(
           auth,
           manager,
           override,
+          probeOverride,
         });
         result.sync_enabled = outcome.sync_enabled;
         if (outcome.warning) result.sync_warning = outcome.warning;
@@ -2127,6 +2148,41 @@ function importErrorTitle(errorType: ImportJobError["error_type"]): string {
  *     stored credential's remote host/path against the import remote.
  *   - **A mirror already targets the SAME remote** — no-op success.
  */
+/**
+ * Head shas on `remoteUrl`, for the unrelated-history guard (vault#823).
+ *
+ * Reuses `probeGitLsRemote` — same spawn, same 10s bound, same no-prompt
+ * posture — and resolves the same authed URL shape the import clone used, so
+ * a private repo answers here too.
+ *
+ * Fails OPEN: any unreachable/ambiguous result returns `[]`, which the guard
+ * reads as "empty remote" and lets the bind proceed. A network blip must not
+ * block a legitimate setup; the failure it exists to catch is deterministic
+ * and will be caught on the next attempt.
+ */
+async function headShasOfRemote(
+  remoteUrl: string,
+  auth: ImportAuth,
+  probeOverride?: (
+    url: string,
+    timeoutMs: number,
+  ) => Promise<{ ok: boolean; error?: string; heads?: string[] }>,
+): Promise<{ heads: string[]; probed: boolean }> {
+  let url = remoteUrl;
+  if (auth.kind === "pat") {
+    url = embedTokenInRemoteUrl(remoteUrl, auth.token) ?? remoteUrl;
+  }
+  try {
+    const probe = await (probeOverride ?? probeGitLsRemote)(url, 10_000);
+    // `ok` with no `heads` key means an older probe shape, not an empty remote —
+    // treat it as "didn't ask" so the caller can say so.
+    if (probe.ok && probe.heads !== undefined) return { heads: probe.heads, probed: true };
+    return { heads: [], probed: false };
+  } catch {
+    return { heads: [], probed: false };
+  }
+}
+
 export async function enableSyncToImportedRepo(opts: {
   vaultName: string;
   remoteUrl: string;
@@ -2143,8 +2199,40 @@ export async function enableSyncToImportedRepo(opts: {
    * backs up to this repo.
    */
   override?: boolean;
+  /**
+   * Test seam for the vault#823 unrelated-history probe (default
+   * `probeGitLsRemote`, which spawns real git at the supplied remote). Inject
+   * one returning `{ ok: true, heads: [] }` to exercise the arm path without
+   * touching the network — matching `handleAuthPat`'s `probeOverride`.
+   */
+  probeOverride?: (
+    url: string,
+    timeoutMs: number,
+  ) => Promise<{ ok: boolean; error?: string; heads?: string[] }>;
 }): Promise<{ sync_enabled: boolean; warning?: string }> {
-  const { vaultName, remoteUrl, auth, manager, override = false } = opts;
+  const { vaultName, remoteUrl, auth, manager, override = false, probeOverride } = opts;
+  // Set when the unrelated-history probe couldn't reach the remote. Rides along
+  // on a SUCCESSFUL arm — the operator gets Sync and the caveat, not neither.
+  let historyUnverified = false;
+  const withUnverifiedNote = (
+    result: { sync_enabled: boolean; warning?: string },
+  ): { sync_enabled: boolean; warning?: string } => {
+    if (!historyUnverified || !result.sync_enabled) return result;
+    // Points at the vault's OWN Git remote section, which renders
+    // `status.last_push_error` today (mirror-manager.ts:121-140, "Cut 5: push
+    // observability"). Deliberately NOT the hub account page: that tile only
+    // reports push outcome once hub#820 lands, and an advisory naming a
+    // diagnostic that doesn't work yet is the same defect this whole set has
+    // been clearing — a claim asserting something that isn't true. Uni caught
+    // that this sentence had made #820 a precondition for user-facing text.
+    const note =
+      "Sync is on, but we couldn't reach the repo to check its history lines up with this vault's backup. " +
+      "If pushes start failing, the Git remote section will show the error.";
+    return {
+      ...result,
+      warning: result.warning ? `${result.warning} ${note}` : note,
+    };
+  };
 
   if (!manager) {
     return {
@@ -2167,6 +2255,38 @@ export async function enableSyncToImportedRepo(opts: {
         warning: `Import succeeded, but Sync was not enabled — ${remoteConflictMessage(conflict)}`,
       };
     }
+
+    // vault#823: arming Sync against a remote whose history this vault's
+    // mirror can't reach produces a backup that is refused on EVERY push and
+    // never self-corrects. Import is the path that creates it — it brings the
+    // notes across but not the mirror's git history, so the mirror is a fresh
+    // `git init` and the remote we just cloned from is, to it, unrelated.
+    //
+    // Decline the optional sync-arm and say why. The import itself already
+    // succeeded and is not touched: the thing that would be wrong is quietly
+    // pointing a backup at a repo it can never write to.
+    const probe = await headShasOfRemote(remoteUrl, auth, probeOverride);
+    if (probe.probed) {
+      const unrelated = await findUnrelatedRemoteHistory({
+        mirrorPath: manager.getStatus().mirror_path,
+        remoteUrl,
+        remoteHeads: probe.heads,
+      });
+      if (unrelated) {
+        return {
+          sync_enabled: false,
+          warning: `Import succeeded, but Sync was not enabled — ${unrelatedHistoryMessage(unrelated)}`,
+        };
+      }
+    } else {
+      // Fail OPEN — a network blip must not block a legitimate setup. But say
+      // so: this guard runs at BIND time and there may be no next bind, so a
+      // silently-skipped check is the same five-day silence it exists to
+      // prevent, reached by a different route. Arming with an unverified
+      // remote is the right trade; arming without saying it was unverified is
+      // not.
+      historyUnverified = true;
+    }
   }
 
   // --- Resolve the push credential we'll persist for this remote. ----------
@@ -2237,7 +2357,7 @@ export async function enableSyncToImportedRepo(opts: {
           };
         }
       }
-      return await applyEnabledAutoPush(manager);
+      return withUnverifiedNote(await applyEnabledAutoPush(manager));
     }
     // Different remote — don't clobber the operator's existing backup target.
     return {
@@ -2325,7 +2445,7 @@ export async function enableSyncToImportedRepo(opts: {
     }
   }
 
-  return await applyEnabledAutoPush(manager);
+  return withUnverifiedNote(await applyEnabledAutoPush(manager));
 }
 
 /**

package/src/routes.ts

@@ -147,6 +147,7 @@ import { existsSync, mkdirSync, statSync, unlinkSync, writeFileSync } from "fs";
 import { assetsDir, readGlobalConfig, readVaultConfig } from "./config.ts";
 import {
   NO_PROVIDER_ERROR,
+  noProviderErrorFor,
   classifyAutoTranscribe,
   shouldAutoTranscribe,
   warnNoTranscriptionProvider,
@@ -2367,6 +2368,22 @@ async function handleNotesInner(
       // Explicit `transcribe: true` wins — if the caller asked, we honor that
       // regardless of the auto-transcribe toggle (back-compat).
       const explicitOptIn = body.transcribe === true;
+      // Explicit opt-OUT. `transcribe: false` is a caller saying no, and it is
+      // NOT the same as saying nothing — which is the only reading this route
+      // had until now (`body.transcribe` was read once, as `=== true`, so
+      // `false` and absent were indistinguishable).
+      //
+      // That collapse is what put the auto path in front of a decision the user
+      // had already made: the app's `voice-capture-plan.ts` sets this from the
+      // capture's transcribe toggle, its docstring states the invariant
+      // ("every link sends `transcribe: false`"), and the sync queue dropped
+      // the `false` in transit. With both halves in place a "no" arrives as a
+      // "no" and auto-transcribe is never consulted — it exists to guess when
+      // nobody expressed a preference, which is no longer this case.
+      //
+      // Absent still means absent, so old app builds and any caller with
+      // genuinely no opinion are byte-unchanged; this is additive.
+      const explicitOptOut = body.transcribe === false;
       // Per-vault auto-transcribe: read THIS vault's `auto_transcribe.enabled`
       // (vault.yaml) and pass it as the precedence-winning toggle. A vault that
       // set its own value uses it; one that left it unset falls through to the
@@ -2378,9 +2395,18 @@ async function handleNotesInner(
       // turned it off" and "nothing is configured to do it" both used to read
       // as `false`, so a misconfigured box silently accepted audio and
       // transcribed nothing — no marker, no status, no log.
+      // An explicit opt-out resolves to `disabled`, which already carries
+      // exactly the right meaning here — "silence is correct: they asked for
+      // nothing to happen" (see `AutoTranscribeDecision`). Reusing it rather
+      // than adding a kind means the downstream branches need no changes: not
+      // `transcribe`, so nothing is enqueued; not `unavailable`, so no `failed`
+      // marker and no missing-provider warning. The attachment links as a plain
+      // audio file, which is what the caller asked for.
       const autoDecision = explicitOptIn
         ? ({ kind: "transcribe" } as const)
-        : classifyAutoTranscribe(body.mimeType, { perVaultEnabled });
+        : explicitOptOut
+          ? ({ kind: "disabled" } as const)
+          : classifyAutoTranscribe(body.mimeType, { perVaultEnabled });
       const autoOptIn = !explicitOptIn && autoDecision.kind === "transcribe";
       // Enabled, audio, but no reachable provider. Record it on the attachment
       // so the state is visible in the API and the admin SPA instead of the
@@ -2404,7 +2430,12 @@ async function handleNotesInner(
         : transcribeUnavailable
           ? {
               transcribe_status: "failed" as const,
-              transcribe_error: NO_PROVIDER_ERROR,
+              // Name the real situation — see noProviderErrorFor. On a box
+              // with a local provider configured, the flat NO_PROVIDER_ERROR
+              // told the operator to do what they had already done.
+              transcribe_error: noProviderErrorFor(
+                autoDecision.kind === "unavailable" ? autoDecision.localProvider : null,
+              ),
               transcribe_requested_at: new Date().toISOString(),
               transcribe_origin: "auto" as const,
               ...(validSegment ? { segment_index: segIdx } : {}),

package/src/transcription/capability.test.ts

@@ -1,4 +1,7 @@
 import { describe, test, expect, afterEach } from "bun:test";
+import { randomUUID } from "crypto";
+import { tmpdir } from "os";
+import { join } from "path";
 import { resolveTranscriptionCapability, defaultTranscriptionProvider } from "./capability.ts";
 import { ScribeHttpProvider } from "./providers/scribe-http.ts";
 import { TranscribeCppProvider } from "./providers/transcribe-cpp.ts";
@@ -81,11 +84,55 @@ describe("defaultTranscriptionProvider — provider selection", () => {
     else process.env.TRANSCRIPTION_PROVIDER = saved;
   });
 
-  test("default (unset) → the scribe-http provider", () => {
+  const savedScribe = process.env.SCRIBE_URL;
+  const savedHome = process.env.PARACHUTE_HOME;
+  afterEach(() => {
+    if (savedScribe === undefined) delete process.env.SCRIBE_URL;
+    else process.env.SCRIBE_URL = savedScribe;
+    if (savedHome === undefined) delete process.env.PARACHUTE_HOME;
+    else process.env.PARACHUTE_HOME = savedHome;
+  });
+
+  test("default (unset) with a reachable scribe → the scribe-http provider", () => {
     delete process.env.TRANSCRIPTION_PROVIDER;
+    process.env.SCRIBE_URL = "http://scribe.test";
     expect(defaultTranscriptionProvider().name).toBe("scribe-http");
   });
 
+  // REGRESSION (Aaron's box, 2026-08-07): `select.ts` defaults an un-scribed
+  // box to `whisper-cpp`, but this factory had no `whisper-cpp` branch and fell
+  // through to ScribeHttpProvider — which reports unavailable, so the landing
+  // said `transcription: {enabled:false}` and the app hid the mic while the
+  // WORKER (server.ts) was happily running whisper-cpp. The capability flag and
+  // the thing that actually transcribes must name the same provider.
+  test("default (unset) with no scribe → the whisper-cpp provider, not scribe-http", () => {
+    delete process.env.TRANSCRIPTION_PROVIDER;
+    delete process.env.SCRIBE_URL;
+    // Unsetting SCRIBE_URL is not enough to mean "no scribe": resolution falls
+    // back to the real `~/.parachute/services.json`, so on a box that still has
+    // a `parachute-scribe` entry this would resolve scribe-http and fail on
+    // correct code. Point PARACHUTE_HOME at an empty dir so "no scribe" is
+    // actually true here.
+    process.env.PARACHUTE_HOME = join(tmpdir(), `pv-cap-${randomUUID()}`);
+    expect(defaultTranscriptionProvider().name).toBe("whisper-cpp");
+  });
+
+  test("TRANSCRIPTION_PROVIDER=whisper-cpp → the whisper-cpp provider", () => {
+    process.env.TRANSCRIPTION_PROVIDER = "whisper-cpp";
+    expect(defaultTranscriptionProvider().name).toBe("whisper-cpp");
+  });
+
+  test("whisper-cpp with no installed model resolves to disabled (no throw)", async () => {
+    // Point PARACHUTE_HOME at a dir with no managed model. `available()` gates
+    // on the model file existing, so this stays hermetic even on a dev box
+    // that has `brew install whisper-cpp` on PATH.
+    process.env.TRANSCRIPTION_PROVIDER = "whisper-cpp";
+    process.env.PARACHUTE_HOME = join(tmpdir(), `pv-cap-${randomUUID()}`);
+    const cap = await resolveTranscriptionCapability(defaultTranscriptionProvider());
+    expect(cap.enabled).toBe(false);
+    expect(cap.provider).toBeUndefined();
+  });
+
   test("TRANSCRIPTION_PROVIDER=transcribe-cpp → the transcribe-cpp provider", () => {
     process.env.TRANSCRIPTION_PROVIDER = "transcribe-cpp";
     expect(defaultTranscriptionProvider().name).toBe("transcribe-cpp");

package/src/transcription/capability.ts

@@ -19,10 +19,15 @@ import { ScribeHttpProvider } from "./providers/scribe-http.ts";
 import { TranscribeCppProvider } from "./providers/transcribe-cpp.ts";
 import { ParakeetMlxProvider } from "./providers/parakeet-mlx.ts";
 import { OnnxAsrProvider } from "./providers/onnx-asr.ts";
+import { WhisperCppProvider } from "./providers/whisper-cpp.ts";
 import { getCachedScribeUrl } from "../scribe-discovery.ts";
 import { resolveScribeAuthToken } from "../scribe-env.ts";
+import { findModel } from "./models.ts";
+import { managedModelDir, resolveCliBinary, resolveFfmpeg } from "./resolve-binary.ts";
+import { join } from "path";
 import {
   resolveTranscriptionProviderName,
+  resolveTranscriptionModelId,
   resolveTranscribeCppPaths,
   resolveParakeetMlxBin,
   resolveParakeetMlxModel,
@@ -42,6 +47,10 @@ export interface TranscriptionCapability {
  * `TRANSCRIPTION_PROVIDER` (scribe-fold Phase 2a) so the capability flag
  * reflects whichever provider is actually configured:
  *
+ *   - `whisper-cpp` → the local whisper.cpp CLIs and the DEFAULT provider on a
+ *     box with no reachable scribe. The model id decides which CLI
+ *     (`parakeet-cli` / `whisper-cli`); `available()` is `false` until
+ *     `transcription install` has put both a binary and the model in place.
  *   - `transcribe-cpp` → the local provider, resolving the installed binary +
  *     GGUF model paths; `available()` is `false` until `transcription install`
  *     has run.
@@ -55,6 +64,20 @@ export interface TranscriptionCapability {
  */
 export function defaultTranscriptionProvider(): TranscriptionProvider {
   const name = resolveTranscriptionProviderName();
+  if (name === "whisper-cpp") {
+    // Mirrors the worker's construction in `server.ts` so the capability flag
+    // and the thing that actually transcribes agree. An unknown model id, a
+    // missing binary or a missing model file all resolve to `undefined` here,
+    // and `WhisperCppProvider.available()` reports not-ok for each — the flag
+    // goes false without throwing, which is the landing's contract.
+    const model = findModel(resolveTranscriptionModelId());
+    return new WhisperCppProvider({
+      binPath: model ? resolveCliBinary(model.engine) : undefined,
+      engine: model?.engine ?? "whisper",
+      modelPath: model ? join(managedModelDir(), model.filename) : undefined,
+      ffmpegPath: resolveFfmpeg(),
+    });
+  }
   if (name === "transcribe-cpp") {
     const paths = resolveTranscribeCppPaths();
     return new TranscribeCppProvider({ binPath: paths.binPath, modelPath: paths.modelPath });

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

@@ -26,7 +26,14 @@ import type { SpawnRunner } from "./transcribe-cpp.ts";
 
 const AUDIO = new Uint8Array([1, 2, 3, 4]);
 
-/** A provider wired to a scripted spawn; both paths "exist" by default. */
+/**
+ * A provider wired to a scripted spawn; both paths "exist" by default.
+ *
+ * `whichImpl` is stubbed because `available()` now also requires ffmpeg, and
+ * the default `ffmpegPath` is the bare name `"ffmpeg"` resolved on PATH. Left
+ * un-stubbed these tests would pass on a dev box with ffmpeg installed and fail
+ * in a CI container without it — the exact green-locally/red-in-CI trap.
+ */
 function makeProvider(
   spawn: SpawnRunner,
   over: Partial<WhisperCppProviderOpts> = {},
@@ -37,6 +44,7 @@ function makeProvider(
     modelPath: "/models/m.bin",
     spawn,
     existsImpl: () => true,
+    whichImpl: () => "/usr/bin/ffmpeg",
     tmpDir: tmpdir(),
     ...over,
   });
@@ -107,6 +115,41 @@ describe("availability", () => {
   test("both present → ok", async () => {
     expect((await makeProvider(scripted({}, {})).available()).ok).toBe(true);
   });
+
+  // ffmpeg is a hard requirement — `transcribe()` always transcodes to 16 kHz
+  // mono WAV first, so a box without it can never transcribe anything. Leaving
+  // it out of `available()` made the vault landing advertise a working mic that
+  // failed on every recording.
+  test("missing ffmpeg is reported as its own problem, distinct from binary/model", async () => {
+    const p = makeProvider(scripted({}, {}), { whichImpl: () => null });
+    const a = await p.available();
+    expect(a.ok).toBe(false);
+    expect(a.reason).toMatch(/ffmpeg/);
+    expect(a.reason).not.toMatch(/parakeet-cli binary/);
+    expect(a.reason).not.toMatch(/model file/);
+  });
+
+  test("an ABSOLUTE ffmpegPath is stat'd, not resolved on PATH", async () => {
+    const p = makeProvider(scripted({}, {}), {
+      ffmpegPath: "/opt/custom/ffmpeg",
+      existsImpl: (x) => x !== "/opt/custom/ffmpeg",
+      whichImpl: () => "/usr/bin/ffmpeg", // PATH has one; the configured path does not exist
+    });
+    const a = await p.available();
+    expect(a.ok).toBe(false);
+    expect(a.reason).toMatch(/ffmpeg/);
+  });
+
+  // The regression this probe could easily have introduced: the constructor
+  // defaults ffmpegPath to the BARE name "ffmpeg". Stat'ing that would always
+  // miss and report every default-constructed provider unavailable.
+  test("the bare-name default resolves on PATH rather than being stat'd", async () => {
+    const p = makeProvider(scripted({}, {}), {
+      existsImpl: (x) => x === "/bin/parakeet-cli" || x === "/models/m.bin",
+      whichImpl: (cmd) => (cmd === "ffmpeg" ? "/usr/bin/ffmpeg" : null),
+    });
+    expect((await p.available()).ok).toBe(true);
+  });
 });
 
 describe("transcribe — error taxonomy", () => {

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

@@ -77,6 +77,8 @@ export interface WhisperCppProviderOpts {
   spawn?: SpawnRunner;
   /** Existence probe (tests inject). */
   existsImpl?: (p: string) => boolean;
+  /** PATH lookup for a bare command name, e.g. the default `"ffmpeg"` (tests inject). */
+  whichImpl?: (cmd: string) => string | null;
   /** Scratch dir for temp audio. Default `os.tmpdir()`. */
   tmpDir?: string;
 }
@@ -131,6 +133,7 @@ export class WhisperCppProvider implements TranscriptionProvider {
   private readonly timeoutMs: number;
   private readonly spawn: SpawnRunner;
   private readonly existsImpl: (p: string) => boolean;
+  private readonly whichImpl: (cmd: string) => string | null;
   private readonly tmpDir: string;
   /** Once available, stays available for this process — avoids re-statting. */
   private cachedAvailable = false;
@@ -143,13 +146,38 @@ export class WhisperCppProvider implements TranscriptionProvider {
     this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     this.spawn = opts.spawn ?? defaultSpawnRunner;
     this.existsImpl = opts.existsImpl ?? existsSync;
+    this.whichImpl = opts.whichImpl ?? ((cmd) => Bun.which(cmd));
     this.tmpDir = opts.tmpDir ?? tmpdir();
   }
 
   /**
-   * Ready iff both the CLI and the model are on disk. Reports WHICH is missing
-   * — "not installed" is not an actionable message when there are two things
-   * it could mean and different fixes for each.
+   * Is ffmpeg actually invokable?
+   *
+   * `ffmpegPath` arrives in two shapes and they need different probes. A
+   * resolved absolute path (what `resolveFfmpeg()` returns) can be stat'd. The
+   * constructor's `"ffmpeg"` default is a BARE COMMAND NAME to be resolved on
+   * PATH — stat'ing that would always miss, and reporting every default-
+   * constructed provider unavailable would be a far worse bug than the one this
+   * check exists to catch.
+   */
+  private ffmpegReady(): boolean {
+    const p = this.ffmpegPath;
+    if (p.includes("/")) return this.existsImpl(p);
+    return this.whichImpl(p) != null;
+  }
+
+  /**
+   * Ready iff the CLI, the model AND ffmpeg are all present. Reports WHICH is
+   * missing — "not installed" is not an actionable message when there are
+   * several things it could mean and different fixes for each.
+   *
+   * ffmpeg is a hard requirement, not a nicety: `transcribe()` ALWAYS transcodes
+   * to 16 kHz mono WAV before invoking the CLI (browser capture is webm/opus,
+   * which neither CLI reads), so without ffmpeg every transcription fails with
+   * `ffmpeg_missing`. Omitting it here made the vault landing advertise
+   * `transcription: {enabled:true}` on a box that could never transcribe a
+   * single file — a mic that appears and then fails is worse than one that
+   * honestly isn't offered.
    */
   async available(): Promise<ProviderAvailability> {
     if (this.cachedAvailable) return { ok: true };
@@ -163,6 +191,9 @@ export class WhisperCppProvider implements TranscriptionProvider {
     if (!this.modelPath || !this.existsImpl(this.modelPath)) {
       missing.push("the model file (`parachute-vault transcription install` downloads it)");
     }
+    if (!this.ffmpegReady()) {
+      missing.push("ffmpeg (`brew install ffmpeg` on macOS, `apt install ffmpeg` on Linux)");
+    }
     if (missing.length > 0) {
       return { ok: false, reason: `whisper-cpp is not ready — missing ${missing.join(" and ")}` };
     }

package/src/transcription/select.test.ts

@@ -30,38 +30,101 @@ import {
 const silent = { warn: () => {} };
 
 describe("resolveTranscriptionProviderName", () => {
-  test("unset → scribe-http (behavior-preserving default)", () => {
-    expect(resolveTranscriptionProviderName({}, silent)).toBe("scribe-http");
+  // Scribe presence is injected in every case. Left to production resolution it
+  // would read the developer's real ~/.parachute/services.json, so "unset" would
+  // resolve differently on a box that happens to have scribe installed — the
+  // test would pass for the wrong reason on one machine and fail on another.
+  const noScribe = { scribeConfiguredImpl: () => false };
+  const withScribe = { scribeConfiguredImpl: () => true };
+
+  test("unset + no scribe → whisper-cpp (the local default)", () => {
+    // The default a fresh box gets. `scribe-http` used to win here and was
+    // unreachable, so audio was accepted and never transcribed.
+    expect(resolveTranscriptionProviderName({}, silent, noScribe)).toBe("whisper-cpp");
   });
-  test("blank → scribe-http", () => {
-    expect(resolveTranscriptionProviderName({ TRANSCRIPTION_PROVIDER: "  " }, silent)).toBe("scribe-http");
+
+  test("unset + a reachable scribe → scribe-http (a working box keeps working)", () => {
+    // The safety property of the flip. These operators configured scribe by
+    // NOT configuring anything, so "unset" can't be read as "wants local" —
+    // flipping unconditionally would take transcription away from them.
+    expect(resolveTranscriptionProviderName({}, silent, withScribe)).toBe("scribe-http");
   });
-  test("explicit transcribe-cpp", () => {
-    expect(resolveTranscriptionProviderName({ TRANSCRIPTION_PROVIDER: "transcribe-cpp" }, silent)).toBe(
-      "transcribe-cpp",
+
+  test("blank → same default resolution as unset", () => {
+    expect(resolveTranscriptionProviderName({ TRANSCRIPTION_PROVIDER: "  " }, silent, noScribe)).toBe(
+      "whisper-cpp",
     );
+    expect(resolveTranscriptionProviderName({ TRANSCRIPTION_PROVIDER: "  " }, silent, withScribe)).toBe(
+      "scribe-http",
+    );
+  });
+
+  test("an EXPLICIT scribe-http is honored even with no scribe reachable", () => {
+    // Explicit config always wins over the probe: the operator may be about to
+    // start scribe, or point SCRIBE_URL somewhere that's briefly down. Silently
+    // overriding a stated choice is its own bug.
+    expect(
+      resolveTranscriptionProviderName({ TRANSCRIPTION_PROVIDER: "scribe-http" }, silent, noScribe),
+    ).toBe("scribe-http");
+  });
+
+  test("an EXPLICIT whisper-cpp is honored even when scribe IS reachable", () => {
+    expect(
+      resolveTranscriptionProviderName({ TRANSCRIPTION_PROVIDER: "whisper-cpp" }, silent, withScribe),
+    ).toBe("whisper-cpp");
   });
+
+  test("explicit transcribe-cpp", () => {
+    expect(
+      resolveTranscriptionProviderName({ TRANSCRIPTION_PROVIDER: "transcribe-cpp" }, silent, noScribe),
+    ).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",
-    );
+    expect(
+      resolveTranscriptionProviderName({ TRANSCRIPTION_PROVIDER: "parakeet-mlx" }, silent, noScribe),
+    ).toBe("parakeet-mlx");
+    expect(
+      resolveTranscriptionProviderName({ TRANSCRIPTION_PROVIDER: "onnx-asr" }, silent, noScribe),
+    ).toBe("onnx-asr");
   });
-  test("explicit scribe-http", () => {
-    expect(resolveTranscriptionProviderName({ TRANSCRIPTION_PROVIDER: "scribe-http" }, silent)).toBe(
-      "scribe-http",
+
+  test("unknown value → warns + falls back to the DEFAULT, not to scribe-http", () => {
+    // The fallback follows the same rule as unset, so a typo on a box with no
+    // scribe lands on the provider that can actually run rather than a dead one.
+    let warned = "";
+    const name = resolveTranscriptionProviderName(
+      { TRANSCRIPTION_PROVIDER: "whisper-magic" },
+      { warn: (...a: unknown[]) => (warned = a.join(" ")) },
+      noScribe,
     );
+    expect(name).toBe("whisper-cpp");
+    // The warning must name what it fell back TO, or the operator can't tell
+    // which provider is actually running.
+    expect(warned).toContain("whisper-magic");
+    expect(warned).toContain("whisper-cpp");
   });
-  test("unknown value → warns + falls back to scribe-http", () => {
-    let warned = false;
+
+  test("unknown value on a scribe box falls back to scribe-http", () => {
+    let warned = "";
     const name = resolveTranscriptionProviderName(
       { TRANSCRIPTION_PROVIDER: "whisper-magic" },
-      { warn: () => (warned = true) },
+      { warn: (...a: unknown[]) => (warned = a.join(" ")) },
+      withScribe,
     );
     expect(name).toBe("scribe-http");
-    expect(warned).toBe(true);
+    expect(warned).toContain("scribe-http");
+  });
+
+  test("the scribe probe is consulted ONLY when there's no explicit provider", () => {
+    // Cheap guard against a regression that makes every capability check stat
+    // services.json — this runs on the per-upload path.
+    let probes = 0;
+    const counting = { scribeConfiguredImpl: () => (probes++, false) };
+    resolveTranscriptionProviderName({ TRANSCRIPTION_PROVIDER: "whisper-cpp" }, silent, counting);
+    expect(probes).toBe(0);
+    resolveTranscriptionProviderName({}, silent, counting);
+    expect(probes).toBe(1);
   });
 });