@openparachute/vault 0.7.5 → 0.7.6-rc.2

package/src/transcription/select.ts

@@ -13,8 +13,8 @@
  * 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.
+ * of truth. Unset ⇒ `whisper-cpp` UNLESS a scribe is actually reachable, in
+ * which case `scribe-http` (see `resolveTranscriptionProviderName`).
  *
  * The `transcribe-cli` binary, GGUF model, and runtime shared libraries live
  * under `$PARACHUTE_HOME/transcription/` (parallel to the vault's other
@@ -30,6 +30,7 @@ import { join } from "path";
 import { homedir } from "os";
 import { existsSync, readFileSync } from "fs";
 import { DEFAULT_MODEL_ID } from "./models.ts";
+import { resolveScribeUrl } from "../scribe-discovery.ts";
 
 export const TRANSCRIPTION_PROVIDERS = [
   "whisper-cpp",
@@ -54,34 +55,65 @@ export type TranscriptionProviderName = (typeof TRANSCRIPTION_PROVIDERS)[number]
 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";
 
+/** Injection seam: "is a scribe actually reachable from here?" */
+export interface ProviderResolveDeps {
+  scribeConfiguredImpl?: () => boolean;
+}
+
 /**
- * Resolve the configured provider name. `TRANSCRIPTION_PROVIDER` selects it;
- * unset (or blank) ⇒ `scribe-http`. An unrecognized value warns once and falls
- * back rather than failing boot — a typo shouldn't take transcription offline
- * hard.
+ * The default provider when nothing is configured.
+ *
+ * This used to be an unconditional `scribe-http`, which was the wrong default
+ * the moment scribe stopped shipping: a fresh box resolved to a provider with
+ * no backend, so it accepted audio and transcribed nothing (vault#643 made that
+ * visible; it did not make it correct). `whisper-cpp` is the right default —
+ * it's local, and `transcription install` now installs a binary + model and
+ * verifies a real transcription before claiming success (vault#636), which is
+ * the precondition this flip was waiting on.
  *
- * NOTE on the default: `scribe-http` remains the fallback for now because
- * flipping it is a separate, riskier change — see the `whisper-cpp` entry in
- * `models.ts`. On a box with nothing configured, `scribe-http` with no
- * SCRIBE_URL means transcription doesn't run at all, which vault#643 now
- * reports honestly instead of silently skipping. Making `whisper-cpp` the
- * default is the follow-up, once `transcription install` can guarantee a
- * runnable binary + model.
+ * But flipping unconditionally would break the boxes that DO have a working
+ * scribe: their config is the absence of config, so "unset" can't be read as
+ * "wants local". So the default asks whether a scribe is actually reachable —
+ * the same `SCRIBE_URL`-then-`services.json` resolution the provider itself
+ * uses — and defers to it when one is. A working box keeps working; a box with
+ * nothing gets the provider it can actually install.
+ *
+ * Deliberately NOT a migration that writes `TRANSCRIPTION_PROVIDER` to `.env`:
+ * pinning a value at upgrade time would freeze whichever answer was true that
+ * day, and an operator who later removes scribe would stay pinned to a dead
+ * provider — the exact failure being fixed here.
+ */
+function defaultProviderName(
+  env: NodeJS.ProcessEnv,
+  deps: ProviderResolveDeps,
+): TranscriptionProviderName {
+  const scribeConfigured =
+    deps.scribeConfiguredImpl ?? (() => resolveScribeUrl(env, undefined, { warn: undefined }) !== undefined);
+  return scribeConfigured() ? "scribe-http" : "whisper-cpp";
+}
+
+/**
+ * Resolve the configured provider name. `TRANSCRIPTION_PROVIDER` selects it;
+ * unset (or blank) ⇒ {@link defaultProviderName}. An unrecognized value warns
+ * once and falls back 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,
+  deps: ProviderResolveDeps = {},
 ): TranscriptionProviderName {
   const raw = env.TRANSCRIPTION_PROVIDER?.trim();
-  if (!raw) return "scribe-http";
+  if (!raw) return defaultProviderName(env, deps);
   if ((TRANSCRIPTION_PROVIDERS as readonly string[]).includes(raw)) {
     return raw as TranscriptionProviderName;
   }
+  const fallback = defaultProviderName(env, deps);
   logger.warn?.(
-    `[transcribe] unknown TRANSCRIPTION_PROVIDER="${raw}" — falling back to scribe-http. ` +
+    `[transcribe] unknown TRANSCRIPTION_PROVIDER="${raw}" — falling back to ${fallback}. ` +
       `Valid values: ${TRANSCRIPTION_PROVIDERS.join(", ")}.`,
   );
-  return "scribe-http";
+  return fallback;
 }
 
 /** The ecosystem root (shared with `config.ts`'s `configDirPath`), per-call so

package/src/transcription-routes.test.ts

@@ -44,12 +44,13 @@ beforeEach(() => {
   process.env.PATH = "";
   delete process.env.WHISPER_CPP_BIN_DIR;
   delete process.env.TRANSCRIPTION_PROVIDER;
+  delete process.env.SCRIBE_URL;
   delete process.env.TRANSCRIPTION_MODEL;
 });
 
 afterEach(() => {
   rmSync(home, { recursive: true, force: true });
-  for (const k of ["PARACHUTE_HOME", "PATH", "WHISPER_CPP_BIN_DIR", "TRANSCRIPTION_PROVIDER", "TRANSCRIPTION_MODEL"]) {
+  for (const k of ["PARACHUTE_HOME", "PATH", "WHISPER_CPP_BIN_DIR", "TRANSCRIPTION_PROVIDER", "TRANSCRIPTION_MODEL", "SCRIBE_URL"]) {
     if (ORIG[k] === undefined) delete process.env[k];
     else process.env[k] = ORIG[k];
   }
@@ -68,11 +69,33 @@ function installFfmpeg() {
   present.add(join(home, "ff", "ffmpeg"));
 }
 
-describe("snapshot — the default (stale) provider", () => {
-  test("scribe-http with no backend reports NOT ready and says why", () => {
-    // The fresh-install state: nothing configured, so the provider resolves to
-    // scribe-http and there is no scribe. This is the case that used to be
-    // invisible.
+describe("snapshot — the default provider on a fresh box", () => {
+  test("nothing configured → whisper-cpp, and it reports what's missing", () => {
+    // The fresh-install state. This used to resolve to `scribe-http` with no
+    // scribe anywhere — a provider that could never run, which is how audio was
+    // accepted and silently never transcribed. The default is now the local
+    // provider, so "not ready" is a list of things `transcription install`
+    // fixes rather than a dead end.
+    const s = buildTranscriptionSnapshot(deps(false));
+    expect(s.provider).toBe("whisper-cpp");
+    expect(s.ready).toBe(false);
+    expect(s.reason).toMatch(/parakeet-cli|model file|ffmpeg/);
+    expect(s.fix_command).toBe("parachute-vault transcription install");
+  });
+
+  test("a box with a reachable scribe still resolves to scribe-http", () => {
+    // The flip's safety property, asserted at the snapshot level: an operator
+    // running scribe today configured it by NOT setting TRANSCRIPTION_PROVIDER,
+    // so the flip must not move them off it.
+    process.env.SCRIBE_URL = "http://127.0.0.1:1943";
+    const s = buildTranscriptionSnapshot(deps(true));
+    expect(s.provider).toBe("scribe-http");
+    // ...and with a worker live, it reports as working rather than as broken.
+    expect(s.ready).toBe(true);
+  });
+
+  test("an explicitly-pinned scribe-http with nothing behind it still says why", () => {
+    process.env.TRANSCRIPTION_PROVIDER = "scribe-http";
     const s = buildTranscriptionSnapshot(deps(false));
     expect(s.provider).toBe("scribe-http");
     expect(s.ready).toBe(false);

package/src/transcription-status-cli.test.ts

@@ -0,0 +1,221 @@
+/**
+ * `transcription status` — that it reports the ACTIVE provider honestly.
+ *
+ * Found live: a box with a working whisper-cpp install (binary, model, and
+ * ffmpeg all present, transcribing fine) was told
+ *
+ *   ⚠ provider is whisper-cpp but no runnable whisper-cpp install was found —
+ *     transcription is offline until one is available
+ *
+ * The command predates whisper-cpp (vault#635) and never grew a branch for it,
+ * so the `activeRunnable` disjunction simply omitted it and could only ever
+ * evaluate false. A status command that reports working software as broken is
+ * worse than no status command — it sends someone to re-install a 400 MB model
+ * to fix nothing.
+ *
+ * The fix shares `buildTranscriptionSnapshot` with the admin SPA's page, so
+ * these tests pin the property that actually prevents recurrence: the CLI and
+ * the UI answer "is transcription working" from ONE implementation.
+ */
+
+import { describe, expect, test, afterEach } from "bun:test";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, chmodSync } from "fs";
+import { tmpdir } from "os";
+import { join, resolve } from "path";
+import { buildTranscriptionSnapshot } from "./transcription-routes.ts";
+import { TRANSCRIPTION_PROVIDERS } from "./transcription/select.ts";
+
+describe("every provider the CLI can resolve is one status knows about", () => {
+  test("the provider list has no member without a readiness story", () => {
+    // The regression in one assertion: whisper-cpp was resolvable as the active
+    // provider while nothing computed its readiness. Any future provider added
+    // to TRANSCRIPTION_PROVIDERS has to be handled too.
+    const handled = new Set([
+      "scribe-http",
+      "whisper-cpp",
+      "transcribe-cpp",
+      "parakeet-mlx",
+      "onnx-asr",
+    ]);
+    for (const p of TRANSCRIPTION_PROVIDERS) {
+      expect(handled.has(p)).toBe(true);
+    }
+  });
+});
+
+describe("the snapshot is the single source of truth", () => {
+  test("readiness comes back as a decidable boolean with a reason when false", () => {
+    const snap = buildTranscriptionSnapshot({
+      active: false,
+      resolveBinaryImpl: () => undefined,
+      resolveFfmpegImpl: () => undefined,
+      existsImpl: () => false,
+    });
+    expect(typeof snap.ready).toBe("boolean");
+    expect(snap.ready).toBe(false);
+    // A false readiness must always carry something actionable, or the CLI has
+    // nothing honest to print.
+    expect(snap.reason).toBeTruthy();
+    expect(snap.fix_command).toBeTruthy();
+  });
+
+  test("a fully-present whisper-cpp install reports ready, with paths to print", () => {
+    const prev = process.env.TRANSCRIPTION_PROVIDER;
+    process.env.TRANSCRIPTION_PROVIDER = "whisper-cpp";
+    try {
+      const snap = buildTranscriptionSnapshot({
+        active: true,
+        resolveBinaryImpl: () => "/opt/homebrew/bin/parakeet-cli",
+        resolveFfmpegImpl: () => "/opt/homebrew/bin/ffmpeg",
+        existsImpl: () => true,
+      });
+      expect(snap.provider).toBe("whisper-cpp");
+      expect(snap.ready).toBe(true);
+      expect(snap.reason).toBeNull();
+      // These are exactly what the CLI prints — a ready snapshot must carry
+      // them or the output degrades to "yes" with no evidence.
+      expect(snap.binary.path).toBe("/opt/homebrew/bin/parakeet-cli");
+      expect(snap.ffmpeg.path).toBe("/opt/homebrew/bin/ffmpeg");
+      expect(snap.model?.installed).toBe(true);
+    } finally {
+      if (prev === undefined) delete process.env.TRANSCRIPTION_PROVIDER;
+      else process.env.TRANSCRIPTION_PROVIDER = prev;
+    }
+  });
+
+  test("a missing binary still reports WHERE it looked — the launchd trap", () => {
+    // What makes "NOT FOUND" actionable on macOS, where the binary is often
+    // installed but invisible to a launchd-supervised vault.
+    const snap = buildTranscriptionSnapshot({
+      active: false,
+      resolveBinaryImpl: () => undefined,
+      resolveFfmpegImpl: () => "/usr/bin/ffmpeg",
+      existsImpl: () => true,
+    });
+    expect(snap.binary.path).toBeNull();
+    expect(snap.binary.searched.length).toBeGreaterThan(0);
+  });
+});
+
+describe("what `transcription status` must not claim", () => {
+  test("readiness never depends on the in-process worker registry", () => {
+    // A one-shot CLI process has no transcription worker — `active` is
+    // structurally false there. Keying the headline off it would print
+    // "ready, but the worker isn't running yet" on every healthy box, which is
+    // the same class of lie the command was just fixed for.
+    const installed = {
+      resolveBinaryImpl: () => "/opt/homebrew/bin/parakeet-cli",
+      resolveFfmpegImpl: () => "/opt/homebrew/bin/ffmpeg",
+      existsImpl: () => true,
+    };
+    const prev = process.env.TRANSCRIPTION_PROVIDER;
+    process.env.TRANSCRIPTION_PROVIDER = "whisper-cpp";
+    try {
+      // `ready` is identical whether or not a worker happens to be live; only
+      // `active` differs. The CLI reports the former.
+      const withWorker = buildTranscriptionSnapshot({ ...installed, active: true });
+      const without = buildTranscriptionSnapshot({ ...installed, active: false });
+      expect(withWorker.ready).toBe(true);
+      expect(without.ready).toBe(true);
+      expect(without.active).toBe(false);
+    } finally {
+      if (prev === undefined) delete process.env.TRANSCRIPTION_PROVIDER;
+      else process.env.TRANSCRIPTION_PROVIDER = prev;
+    }
+  });
+});
+
+/**
+ * The command must report the CONFIG FILE, not its own process environment.
+ *
+ * Found live (UniOps, 2026-08-02): a box whose `.env` said `whisper-cpp` was
+ * told `scribe-http` — the retired service — while `status` was the very tool
+ * being used to diagnose why transcription was dead. Same class as the bug at
+ * the top of this file: the daemon loads `~/.parachute/vault/.env` at boot
+ * (`server.ts` → `loadEnvFile()`), a one-shot CLI process never did, and every
+ * resolver underneath reads `process.env`.
+ *
+ * These spawn the real CLI because that is where the defect lived — the
+ * resolvers were always correct when handed the right env; nothing but a
+ * process boundary reproduces it. No in-test `Bun.serve` is involved, so
+ * `Bun.spawnSync` is fine here (CLAUDE.md, "Subprocess tests + Bun.serve").
+ *
+ * Each case sets a value that DIFFERS from the fallback. A test using a value
+ * the fallback happens to produce would pass without the fix — which is
+ * precisely how this shipped: on an unconfigured box the default agrees with
+ * the file, so the command looked right until someone changed something.
+ */
+describe("`transcription status` reads ~/.parachute/vault/.env", () => {
+  const CLI = resolve(import.meta.dir, "cli.ts");
+  const homes: string[] = [];
+
+  afterEach(() => {
+    for (const h of homes.splice(0)) rmSync(h, { recursive: true, force: true });
+  });
+
+  /** A temp PARACHUTE_HOME whose `vault/.env` holds exactly these lines. */
+  function homeWithEnv(lines: string[]): string {
+    const home = mkdtempSync(join(tmpdir(), "pv-transcription-env-"));
+    homes.push(home);
+    mkdirSync(join(home, "vault"), { recursive: true });
+    writeFileSync(join(home, "vault", ".env"), `${lines.join("\n")}\n`);
+    return home;
+  }
+
+  /** Run `transcription status` with the file's values ONLY on disk. */
+  function status(home: string): string {
+    // Strip the inherited values so the child cannot pass by reading the
+    // parent's environment — the file is the only source in play.
+    const env: Record<string, string | undefined> = { ...process.env, PARACHUTE_HOME: home };
+    for (const k of [
+      "TRANSCRIPTION_PROVIDER",
+      "TRANSCRIPTION_MODEL",
+      "WHISPER_CPP_BIN_DIR",
+      "SCRIBE_URL",
+      "PARACHUTE_HUB_ORIGIN",
+    ]) {
+      delete env[k];
+    }
+    const proc = Bun.spawnSync({
+      cmd: ["bun", CLI, "transcription", "status"],
+      stdout: "pipe",
+      stderr: "pipe",
+      env,
+    });
+    return new TextDecoder().decode(proc.stdout);
+  }
+
+  test("the provider comes from the file, not the fallback default", () => {
+    // `scribe-http` is never the fallback on a box with no scribe in
+    // services.json — the default there is whisper-cpp. So this asserts the
+    // file was read rather than that two paths coincided.
+    const out = status(homeWithEnv(["TRANSCRIPTION_PROVIDER=scribe-http", "SCRIBE_URL=http://127.0.0.1:1943"]));
+    expect(out).toContain("scribe-http");
+    expect(out).not.toContain("(whisper-cpp)");
+  });
+
+  test("the model comes from the file", () => {
+    const out = status(homeWithEnv(["TRANSCRIPTION_PROVIDER=whisper-cpp", "TRANSCRIPTION_MODEL=whisper-tiny.en"]));
+    expect(out).toContain("Whisper Tiny (English)");
+    expect(out).not.toContain("Parakeet TDT 0.6b v3");
+  });
+
+  test("a binary-dir override in the file is honored — the false 'not found'", () => {
+    // The sharpest symptom: an installed, working binary reported missing
+    // because the `.env` override naming its directory never reached the
+    // resolver. This is the `runnable: no` line UniOps flagged as suspect.
+    const home = homeWithEnv([]);
+    const bin = join(home, "fakebin");
+    mkdirSync(bin, { recursive: true });
+    const exe = join(bin, "parakeet-cli");
+    writeFileSync(exe, "#!/bin/sh\nexit 0\n");
+    chmodSync(exe, 0o755);
+    writeFileSync(
+      join(home, "vault", ".env"),
+      `TRANSCRIPTION_PROVIDER=whisper-cpp\nWHISPER_CPP_BIN_DIR=${bin}\n`,
+    );
+    const out = status(home);
+    expect(out).toContain(exe);
+    expect(out).not.toContain("parakeet-cli   not found");
+  });
+});

package/src/vault.test.ts

@@ -2901,6 +2901,63 @@ describe("HTTP /notes", async () => {
       expect((note!.metadata as any)?.transcribe_stub).toBeUndefined();
     });
 
+    // The explicit opt-out. `transcribe: false` is a caller saying no, and it
+    // used to be indistinguishable from saying nothing — `body.transcribe` was
+    // read once, as `=== true`. So a user who turned the capture's transcribe
+    // toggle OFF had their decision answered by the auto-transcribe guess,
+    // which exists for callers who expressed no preference.
+    //
+    // Contrast with the test directly above: same request, same suite, same
+    // absent provider — absent gets `failed`, `false` gets nothing at all.
+    test("transcribe: false is honoured — no transcription, and NO failure marker", async () => {
+      await store.createNote("note body", { id: "v2c" });
+      const res = await handleNotes(
+        mkReq("POST", "/notes/v2c/attachments", {
+          path: "memos/memo-optout.webm",
+          mimeType: "audio/webm",
+          transcribe: false,
+        }),
+        store,
+        "/v2c/attachments",
+      );
+      expect(res.status).toBe(201);
+      const att = await res.json() as any;
+      // Not enqueued...
+      expect(att.metadata?.transcribe_status).toBeUndefined();
+      // ...and NOT recorded as a misconfiguration either. Nothing failed; the
+      // caller asked for nothing to happen and nothing happened.
+      expect(att.metadata?.transcribe_error).toBeUndefined();
+      expect(att.metadata?.transcribe_origin).toBeUndefined();
+      // The note is untouched — no stub to fill, because no transcript is coming.
+      const note = await store.getNote("v2c");
+      expect((note!.metadata as any)?.transcribe_stub).toBeUndefined();
+    });
+
+    test("false and absent are no longer the same request", async () => {
+      // The regression this pair exists to prevent, stated as one assertion:
+      // if these two ever produce equal metadata again, the opt-out has been
+      // collapsed back into "no opinion".
+      await store.createNote("body", { id: "v2d" });
+      await store.createNote("body", { id: "v2e" });
+      const mk = async (id: string, extra: Record<string, unknown>) => {
+        const r = await handleNotes(
+          mkReq("POST", `/notes/${id}/attachments`, {
+            path: `memos/${id}.webm`,
+            mimeType: "audio/webm",
+            ...extra,
+          }),
+          store,
+          `/${id}/attachments`,
+        );
+        return ((await r.json()) as any).metadata ?? {};
+      };
+      const absent = await mk("v2d", {});
+      const optedOut = await mk("v2e", { transcribe: false });
+      expect(absent.transcribe_status).toBe("failed");
+      expect(optedOut.transcribe_status).toBeUndefined();
+      expect(absent).not.toEqual(optedOut);
+    });
+
     test("NON-audio with no flag still leaves metadata completely empty", async () => {
       await store.createNote("note body", { id: "v2b" });
       const res = await handleNotes(
@@ -7541,6 +7598,23 @@ describe("manage-token MCP tool (vault#403, MGT — hub-JWT attenuation proxy)",
     closeAllStores();
   });
 
+  test("long_lived=true permits a 30-day TTL", async () => {
+    installHubStub();
+    const { vaultName, auth } = await setupAdminSession("mint-long-lived");
+    const { closeAllStores } = await import("./vault-store.ts");
+    const { parsed } = await callTool(vaultName, auth, "manage-token", {
+      action: "mint",
+      scope: "vault:read",
+      ttl_seconds: 2592000,
+      long_lived: true,
+    });
+    expect(parsed.action).toBe("mint");
+    expect(parsed.error).toBeUndefined();
+    const mint = hubCalls.find((c) => c.url.endsWith("/api/auth/mint-token"));
+    expect(mint!.body.expires_in).toBe(2592000);
+    closeAllStores();
+  });
+
   test("tag-scoped caller's mint includes permissions.scoped_tags", async () => {
     installHubStub();
     const { vaultName, auth } = await setupAdminSession("mint-scoped", ["task", "project"]);
@@ -7568,6 +7642,52 @@ describe("manage-token MCP tool (vault#403, MGT — hub-JWT attenuation proxy)",
     const { closeAllStores } = await import("./vault-store.ts");
     const { parsed } = await callTool(vaultName, auth, "manage-token", { action: "mint", scope: "vault:read", ttl_seconds: 3601 });
     expect(parsed.error).toBe("invalid_request");
+    expect(parsed.message).toBe("manage-token mint: ttl_seconds must be in (0, 3600]; got 3601.");
+    expect(hubCalls.length).toBe(0);
+    closeAllStores();
+  });
+
+  test("long_lived=true rejects TTL above the 90-day cap locally", async () => {
+    installHubStub();
+    const { vaultName, auth } = await setupAdminSession("mint-long-over");
+    const { closeAllStores } = await import("./vault-store.ts");
+    const { parsed } = await callTool(vaultName, auth, "manage-token", {
+      action: "mint",
+      scope: "vault:read",
+      ttl_seconds: 7776001,
+      long_lived: true,
+    });
+    expect(parsed.error).toBe("invalid_request");
+    expect(parsed.message).toContain("7776000");
+    expect(hubCalls.length).toBe(0);
+    closeAllStores();
+  });
+
+  test("long_lived=false keeps the 1-hour cap", async () => {
+    installHubStub();
+    const { vaultName, auth } = await setupAdminSession("mint-long-false");
+    const { closeAllStores } = await import("./vault-store.ts");
+    const { parsed } = await callTool(vaultName, auth, "manage-token", {
+      action: "mint",
+      scope: "vault:read",
+      ttl_seconds: 7200,
+      long_lived: false,
+    });
+    expect(parsed.error).toBe("invalid_request");
+    expect(hubCalls.length).toBe(0);
+    closeAllStores();
+  });
+
+  test("omitted long_lived keeps the 1-hour cap", async () => {
+    installHubStub();
+    const { vaultName, auth } = await setupAdminSession("mint-long-omitted");
+    const { closeAllStores } = await import("./vault-store.ts");
+    const { parsed } = await callTool(vaultName, auth, "manage-token", {
+      action: "mint",
+      scope: "vault:read",
+      ttl_seconds: 7200,
+    });
+    expect(parsed.error).toBe("invalid_request");
     expect(hubCalls.length).toBe(0);
     closeAllStores();
   });