@openparachute/vault 0.7.6 → 0.7.7

package/src/test-home-isolation.test.ts

@@ -0,0 +1,137 @@
+/**
+ * The suite must never write into a live Parachute install.
+ *
+ * On 2026-08-22 it did: two `bun test` runs created ~158 real vault
+ * directories under `~/.parachute/vault/data/` on a developer box —
+ * `tagscope-*`, `mint-*`, `retier-*`, `ledger-*`, and a `solo` vault from the
+ * mirror-routes tests. `core/src/test-preload.ts` existed and was loaded; it
+ * simply declined to act, because it only assigned PARACHUTE_HOME when the
+ * variable was *unset*, and the box's shell profile exported
+ * `PARACHUTE_HOME="$HOME/.parachute"`. The isolation was conditional on the
+ * one condition that mattered being false.
+ *
+ * These tests pin both layers of the fix:
+ *   1. the preload overrides an inherited PARACHUTE_HOME unconditionally
+ *   2. `configDirPath()` refuses the `~/.parachute` fallback under
+ *      NODE_ENV=test, so a run that never loaded the preload (wrong cwd →
+ *      bunfig.toml not found) fails loudly instead of writing real vaults
+ */
+
+import { describe, test, expect } from "bun:test";
+import { mkdtempSync, rmSync, existsSync } from "fs";
+import { homedir, tmpdir } from "os";
+import { join, resolve } from "path";
+
+import { runSubprocess } from "./test-support/spawn.ts";
+
+const REPO_ROOT = resolve(import.meta.dir, "..");
+
+describe("test-home isolation", () => {
+  test("this very process is not pointed at the real ~/.parachute", () => {
+    // The in-process invariant. If the preload stops loading, or stops
+    // overriding, this is the first thing that fails.
+    const real = join(homedir(), ".parachute");
+    expect(process.env.PARACHUTE_HOME).toBeTruthy();
+    expect(process.env.PARACHUTE_HOME).not.toBe(real);
+  });
+
+  test("the preload overrides an inherited PARACHUTE_HOME rather than deferring to it", async () => {
+    const sandbox = mkdtempSync(join(tmpdir(), "test-home-isolation-"));
+    try {
+      // Stand in for the live install: a HOME whose `.parachute` we watch, and
+      // the exported PARACHUTE_HOME a login shell would hand `bun test`. This
+      // is the exact shape of the 2026-08-22 environment.
+      const inherited = join(sandbox, ".parachute");
+      const probe = join(sandbox, "probe.test.ts");
+      await Bun.write(
+        probe,
+        [
+          `import { test } from "bun:test";`,
+          `import { writeVaultConfig } from ${JSON.stringify(join(REPO_ROOT, "src/config.ts"))};`,
+          `import { getVaultStore, closeAllStores } from ${JSON.stringify(join(REPO_ROOT, "src/vault-store.ts"))};`,
+          `test("writes a vault wherever config.ts points", async () => {`,
+          `  console.log("RESOLVED_HOME=" + process.env.PARACHUTE_HOME);`,
+          `  writeVaultConfig({ name: "isolation-probe", api_keys: [], created_at: new Date().toISOString() });`,
+          `  getVaultStore("isolation-probe");`,
+          `  closeAllStores();`,
+          `});`,
+        ].join("\n"),
+      );
+
+      // cwd = repo root so bunfig.toml's `[test] preload` applies, which is
+      // the normal way the suite runs.
+      const res = await runSubprocess({
+        cmd: ["bun", "test", probe],
+        cwd: REPO_ROOT,
+        env: { HOME: sandbox, PARACHUTE_HOME: inherited },
+      });
+
+      const out = res.stdout + res.stderr;
+      // Assert the child actually got as far as writing a vault — without
+      // this, a child that crashed on startup would satisfy every "nothing
+      // landed in the live install" assertion below for the wrong reason.
+      expect(res.exitCode).toBe(0);
+      expect(out).not.toContain(`RESOLVED_HOME=${inherited}`);
+      expect(out).toContain("RESOLVED_HOME=");
+      // The load-bearing assertion: nothing landed in the "live" install.
+      expect(existsSync(join(inherited, "vault", "data", "isolation-probe"))).toBe(false);
+      expect(existsSync(inherited)).toBe(false);
+    } finally {
+      rmSync(sandbox, { recursive: true, force: true });
+    }
+  });
+
+  test("runSubprocess propagates the live PARACHUTE_HOME to the child", async () => {
+    // Bun gives a child the environ the parent *started* with, not the live
+    // `process.env` — so the preload's runtime assignment is invisible to any
+    // child spawned without an explicit env, and that child resolves its home
+    // to the real ~/.parachute. `runSubprocess` spreads `process.env`, which
+    // is the only reason CLI tests are safe; pin it.
+    const res = await runSubprocess({
+      cmd: ["bun", "-e", `console.log("CHILD_PH=" + process.env.PARACHUTE_HOME)`],
+      cwd: REPO_ROOT,
+    });
+    expect(res.stdout.trim()).toBe(`CHILD_PH=${process.env.PARACHUTE_HOME}`);
+    expect(res.stdout).not.toContain(`CHILD_PH=${join(homedir(), ".parachute")}`);
+    expect(res.stdout).not.toContain("CHILD_PH=undefined");
+  });
+
+  test("configDirPath() refuses the ~/.parachute fallback under NODE_ENV=test", async () => {
+    // Simulates the other way the isolation can be lost: the preload never
+    // loads (bunfig.toml is resolved from the cwd, so running the suite by
+    // path from a parent directory skips it) and PARACHUTE_HOME is unset.
+    const res = await runSubprocess({
+      cmd: [
+        "bun",
+        "-e",
+        `const { vaultDir } = await import(${JSON.stringify(join(REPO_ROOT, "src/config.ts"))}); console.log(vaultDir("x"));`,
+      ],
+      cwd: REPO_ROOT,
+      env: { PARACHUTE_HOME: undefined, NODE_ENV: "test" },
+    });
+
+    const out = res.stdout + res.stderr;
+    expect(res.exitCode).not.toBe(0);
+    expect(out).toContain("refusing to default to the live install");
+    // The message has to be actionable for an npm consumer whose test runner
+    // set NODE_ENV=test, not just for a contributor in this repo.
+    expect(out).toContain("Set PARACHUTE_HOME explicitly");
+  });
+
+  test("configDirPath() still falls back to ~/.parachute outside tests", async () => {
+    // The guard is test-only: real installs resolve the home the way they
+    // always have.
+    const res = await runSubprocess({
+      cmd: [
+        "bun",
+        "-e",
+        `const { vaultDir } = await import(${JSON.stringify(join(REPO_ROOT, "src/config.ts"))}); console.log(vaultDir("x"));`,
+      ],
+      cwd: REPO_ROOT,
+      env: { PARACHUTE_HOME: undefined, NODE_ENV: undefined, HOME: "/tmp/not-a-real-home" },
+    });
+
+    expect(res.exitCode).toBe(0);
+    expect(res.stdout.trim()).toBe(join("/tmp/not-a-real-home", ".parachute", "vault", "data", "x"));
+  });
+});

package/src/test-support/spawn.ts

@@ -18,6 +18,18 @@
  * `runSubprocess` uses async `Bun.spawn` + `await proc.exited`, so the
  * parent's event loop keeps servicing requests while the child runs.
  *
+ * THE OTHER RULE — always give a spawned child an explicit `env`.
+ *
+ * Bun hands a child the environ the parent process *started* with, not the
+ * live `process.env`: assignments made at runtime are invisible to it. That
+ * includes the temp `PARACHUTE_HOME` that `core/src/test-preload.ts` sets for
+ * the whole suite, so a child spawned with no `env` resolves its parachute
+ * home to the developer's real `~/.parachute` (verified with Bun 1.3.14).
+ * `runSubprocess` handles this for you — it spreads the live `process.env`
+ * below and merges `opts.env` over it. Hand-rolled `Bun.spawnSync` calls must
+ * do the same; `src/version.test.ts` was silently pointing its CLI child at
+ * the real install until the config.ts NODE_ENV=test guard caught it.
+ *
  * NOTE on what's *fine*: `Bun.spawnSync` is safe in tests that don't run
  * an in-test server the child talks to over HTTP — e.g. shelling out to
  * `git` to build a fixture repo (`mirror-*.test.ts`), or a `Bun.serve`

package/src/transcription/download.test.ts

@@ -2,7 +2,12 @@ import { describe, test, expect, afterAll } from "bun:test";
 import { existsSync, mkdtempSync, readFileSync, rmSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
-import { downloadTo } from "./download.ts";
+import {
+  downloadTo,
+  ensureDownloaded,
+  fetchUpstreamDigest,
+  sha256OfFile,
+} from "./download.ts";
 
 /**
  * `downloadTo` tests (vault#534 blocker 1). The manual body→FileSink pump
@@ -99,3 +104,184 @@ describe("downloadTo", () => {
     }
   });
 });
+
+/**
+ * Checksum + idempotency (vault#531). The digest shape under test is the real
+ * one: HuggingFace serves LFS-backed `resolve/` URLs as a 302 carrying
+ * `x-linked-etag` = the plain sha256 of the bytes. Verified against a live
+ * download of ggml-tiny.en.bin (77,704,715 bytes) — header and
+ * `shasum -a 256` agreed exactly — and fixtured here so the suite stays
+ * offline.
+ */
+const PAYLOAD_SHA = new Bun.CryptoHasher("sha256").update(PAYLOAD).digest("hex");
+
+describe("downloadTo — sha256 verification", () => {
+  test("accepts a body whose hash matches", async () => {
+    const { server, url } = serve(() => new Response(PAYLOAD));
+    const dest = join(dir, "sha-ok.bin");
+    try {
+      await downloadTo(`${url}/file`, dest, { sha256: PAYLOAD_SHA });
+      expect(readFileSync(dest).byteLength).toBe(PAYLOAD.byteLength);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("a complete-but-corrupt body throws AND removes the file", async () => {
+    // Length is right, bytes are wrong — invisible to the content-length
+    // check, which is exactly the gap a checksum closes.
+    const corrupt = new Uint8Array(PAYLOAD);
+    corrupt[corrupt.length - 1] ^= 0xff;
+    const { server, url } = serve(() => new Response(corrupt));
+    const dest = join(dir, "sha-bad.bin");
+    try {
+      expect(downloadTo(`${url}/file`, dest, { sha256: PAYLOAD_SHA })).rejects.toThrow(
+        /failed checksum: sha256 [0-9a-f]{64}, expected/,
+      );
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("no sha256 given → unchanged behaviour, body accepted", async () => {
+    const { server, url } = serve(() => new Response(PAYLOAD));
+    const dest = join(dir, "sha-none.bin");
+    try {
+      await downloadTo(`${url}/file`, dest);
+      expect(existsSync(dest)).toBe(true);
+    } finally {
+      server.stop(true);
+    }
+  });
+});
+
+describe("fetchUpstreamDigest", () => {
+  function redirectingServer(headers: Record<string, string>) {
+    return serve((req) => {
+      if (new URL(req.url).pathname === "/target") return new Response(PAYLOAD);
+      return new Response("", { status: 302, headers: { location: "/target", ...headers } });
+    });
+  }
+
+  test("reads the sha256 off a HuggingFace-style x-linked-etag 302", async () => {
+    const { server, url } = redirectingServer({ "x-linked-etag": `"${PAYLOAD_SHA}"` });
+    try {
+      const digest = await fetchUpstreamDigest(`${url}/model.bin`);
+      expect(digest?.sha256).toBe(PAYLOAD_SHA);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("tolerates a weak-etag prefix", async () => {
+    const { server, url } = redirectingServer({ "x-linked-etag": `W/"${PAYLOAD_SHA}"` });
+    try {
+      expect((await fetchUpstreamDigest(`${url}/model.bin`))?.sha256).toBe(PAYLOAD_SHA);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("returns null for an opaque etag that is not a sha256", async () => {
+    // A GitHub-release-style cache token must never be mistaken for a digest.
+    const { server, url } = redirectingServer({ "x-linked-etag": '"0x8DA1B2C3D4E5F60"' });
+    try {
+      expect(await fetchUpstreamDigest(`${url}/model.bin`)).toBeNull();
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("returns null when the host publishes no digest at all", async () => {
+    const { server, url } = serve(() => new Response(PAYLOAD));
+    try {
+      expect(await fetchUpstreamDigest(`${url}/asset.tar.gz`)).toBeNull();
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("returns null (does not throw) when the probe cannot connect", async () => {
+    expect(await fetchUpstreamDigest("http://127.0.0.1:1/nope")).toBeNull();
+  });
+});
+
+describe("ensureDownloaded — partial-download idempotency (vault#531)", () => {
+  function digestServer() {
+    return serve((req) => {
+      if (new URL(req.url).pathname === "/target") return new Response(PAYLOAD);
+      return new Response("", {
+        status: 302,
+        headers: { location: "/target", "x-linked-etag": `"${PAYLOAD_SHA}"` },
+      });
+    });
+  }
+
+  test("fetches when absent and reports it verified", async () => {
+    const { server, url } = digestServer();
+    const dest = join(dir, "ens-new.bin");
+    try {
+      const r = await ensureDownloaded(`${url}/model.bin`, dest);
+      expect(r.outcome).toBe("downloaded");
+      expect(r.verified).toBe(true);
+      expect(await sha256OfFile(dest)).toBe(PAYLOAD_SHA);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("reuses an intact existing file without re-downloading", async () => {
+    const { server, url } = digestServer();
+    const dest = join(dir, "ens-good.bin");
+    try {
+      await Bun.write(dest, PAYLOAD);
+      const r = await ensureDownloaded(`${url}/model.bin`, dest);
+      expect(r.outcome).toBe("reused");
+      expect(r.verified).toBe(true);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("REPAIRS a corrupt file that a plain existsSync check would have skipped", async () => {
+    // The bug: install skipped anything that existed. A truncated model
+    // survived every non---force re-run.
+    const { server, url } = digestServer();
+    const dest = join(dir, "ens-corrupt.bin");
+    try {
+      await Bun.write(dest, PAYLOAD.slice(0, 1024)); // truncated leftover
+      const r = await ensureDownloaded(`${url}/model.bin`, dest);
+      expect(r.outcome).toBe("repaired");
+      expect(await sha256OfFile(dest)).toBe(PAYLOAD_SHA);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("force re-downloads even an intact file", async () => {
+    const { server, url } = digestServer();
+    const dest = join(dir, "ens-force.bin");
+    try {
+      await Bun.write(dest, PAYLOAD);
+      const r = await ensureDownloaded(`${url}/model.bin`, dest, { force: true });
+      expect(r.outcome).toBe("downloaded");
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("no published digest → an existing file is reused unverified, as before", async () => {
+    const { server, url } = serve(() => new Response(PAYLOAD));
+    const dest = join(dir, "ens-nodigest.bin");
+    try {
+      await Bun.write(dest, PAYLOAD.slice(0, 512));
+      const r = await ensureDownloaded(`${url}/asset.tar.gz`, dest);
+      expect(r.outcome).toBe("reused");
+      expect(r.verified).toBe(false);
+      // Unchanged: with nothing to check against we must not guess.
+      expect(readFileSync(dest).byteLength).toBe(512);
+    } finally {
+      server.stop(true);
+    }
+  });
+});

package/src/transcription/download.ts

@@ -16,7 +16,83 @@
  * platform gate). See vault#534 for the full container verification.
  */
 
-import { rmSync } from "fs";
+import { existsSync, rmSync } from "fs";
+
+/**
+ * A content hash the UPSTREAM host publishes for an artifact, discovered at
+ * download time rather than pinned in this repo.
+ */
+export interface UpstreamDigest {
+  /** Lowercase hex sha256 of the file's bytes. */
+  sha256: string;
+  /** Where we learned it, for error messages. */
+  source: string;
+}
+
+/**
+ * Ask the host whether it publishes a content digest for `url`, WITHOUT
+ * downloading the body.
+ *
+ * HuggingFace — where every GGUF model in `models.ts` / `install.ts` comes
+ * from — serves LFS-backed `resolve/` URLs as a 302 whose `x-linked-etag`
+ * header is the git-LFS oid: the plain sha256 of the file's bytes. Verified
+ * against a real download (`ggml-tiny.en.bin`, 77,704,715 bytes): the header
+ * and `shasum -a 256` of the fetched file agree exactly. `x-linked-size`
+ * likewise matches the byte count.
+ *
+ * The redirect TARGET's own `etag` is a different thing — HF's Xet CAS hash,
+ * not a sha256 of the content — so the digest has to be read off the 302
+ * itself. That's why this uses `redirect: "manual"` instead of reading
+ * headers off the followed response.
+ *
+ * Returns `null` for any host that publishes nothing (GitHub release assets,
+ * today). A missing digest is NOT an error: it degrades to the size check
+ * `downloadTo` already performs. Network failures here are swallowed for the
+ * same reason — a checksum probe must never be the thing that breaks an
+ * install.
+ */
+export async function fetchUpstreamDigest(url: string): Promise<UpstreamDigest | null> {
+  try {
+    const resp = await fetch(url, { method: "GET", redirect: "manual", headers: { range: "bytes=0-0" } });
+    // Consume/discard: with `redirect: manual` the 302 body is a short stub,
+    // and the range header keeps a non-redirecting 200 to a single byte.
+    try { await resp.arrayBuffer(); } catch { /* nothing worth reporting */ }
+    const linked = resp.headers.get("x-linked-etag") ?? resp.headers.get("x-linked-etag".toUpperCase());
+    const hex = normalizeSha256Etag(linked);
+    if (hex) return { sha256: hex, source: "HuggingFace x-linked-etag (git-LFS oid)" };
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * An ETag is quoted and may carry a `W/` weak prefix. Accept it only when what
+ * remains is exactly 64 hex characters — anything else is some other host's
+ * opaque cache token, not a sha256, and must not be treated as one.
+ */
+function normalizeSha256Etag(raw: string | null): string | null {
+  if (!raw) return null;
+  const stripped = raw.trim().replace(/^W\//i, "").replace(/^"|"$/g, "").toLowerCase();
+  return /^[0-9a-f]{64}$/.test(stripped) ? stripped : null;
+}
+
+/** Streaming sha256 of a file already on disk — never buffers it whole. */
+export async function sha256OfFile(path: string): Promise<string> {
+  const hasher = new Bun.CryptoHasher("sha256");
+  const stream = Bun.file(path).stream();
+  for await (const chunk of stream) hasher.update(chunk);
+  return hasher.digest("hex");
+}
+
+export interface DownloadOptions {
+  /**
+   * Expected lowercase-hex sha256. When set, the hash is computed AS THE BYTES
+   * STREAM (no second pass, no buffering) and a mismatch removes the file and
+   * throws.
+   */
+  sha256?: string | null;
+}
 
 /**
  * Download `url` to `dest` (follows redirects). Streams chunk-by-chunk — never
@@ -24,8 +100,13 @@ import { rmSync } from "fs";
  * the partial file is removed so a retry never trusts a truncated artifact.
  * When the server sent an honest `content-length` (no content-encoding
  * transform), a byte-count mismatch is treated as a failed download too.
+ *
+ * With `opts.sha256`, content integrity is checked as well as length — a
+ * corrupted-but-complete transfer (a proxy that mangles bytes, a truncation
+ * the length check can't see because no `content-length` was sent) is caught
+ * and the file removed.
  */
-export async function downloadTo(url: string, dest: string): Promise<void> {
+export async function downloadTo(url: string, dest: string, opts: DownloadOptions = {}): Promise<void> {
   const resp = await fetch(url, { redirect: "follow" });
   if (!resp.ok) throw new Error(`download failed (${resp.status}) for ${url}`);
   if (!resp.body) throw new Error(`download failed (empty response body) for ${url}`);
@@ -41,11 +122,15 @@ export async function downloadTo(url: string, dest: string): Promise<void> {
       ? Number(lengthHeader)
       : null;
 
+  const wantSha = opts.sha256 ? opts.sha256.trim().toLowerCase() : null;
+  const hasher = wantSha ? new Bun.CryptoHasher("sha256") : null;
+
   const sink = Bun.file(dest).writer();
   let written = 0;
   try {
     for await (const chunk of resp.body) {
       sink.write(chunk);
+      hasher?.update(chunk);
       written += chunk.byteLength;
     }
     await sink.end();
@@ -68,4 +153,66 @@ export async function downloadTo(url: string, dest: string): Promise<void> {
       `download of ${url} was truncated: got ${written} bytes, expected ${expectedBytes} (content-length)`,
     );
   }
+
+  if (wantSha && hasher) {
+    const got = hasher.digest("hex");
+    if (got !== wantSha) {
+      rmSync(dest, { force: true });
+      throw new Error(
+        `download of ${url} failed checksum: sha256 ${got}, expected ${wantSha}`,
+      );
+    }
+  }
+}
+
+/**
+ * Fetch `url` to `dest` **idempotently** — the policy `transcription install`
+ * needs for a re-run (vault#531).
+ *
+ * The hole this closes: the install path skipped any file that merely EXISTED
+ * (`existsSync(dest) && !force`). `downloadTo` removes partials it notices, but
+ * it can't notice everything — a `kill -9` mid-write, a full disk, or a server
+ * that sent no `content-length` all leave a complete-looking file behind. From
+ * then on every non-`--force` re-run reported "already present — skipping" and
+ * the operator got a corrupt model forever, with no signal and no path out
+ * short of knowing to pass `--force`.
+ *
+ * So: when the artifact is already on disk and the host publishes a digest, we
+ * VERIFY it before trusting it, and re-download on mismatch. When the host
+ * publishes nothing, behaviour is unchanged (skip) — this can only ever turn a
+ * silent corruption into a repair, never a good file into a re-download.
+ *
+ * Returns what happened so the caller can print something honest.
+ */
+export type EnsureOutcome = "downloaded" | "reused" | "repaired";
+
+export async function ensureDownloaded(
+  url: string,
+  dest: string,
+  opts: {
+    force?: boolean;
+    /**
+     * Called just before bytes are actually pulled, so the caller can print a
+     * progress line only when there IS a transfer. `reason` distinguishes a
+     * first fetch from replacing a bad file.
+     */
+    onBeforeDownload?: (reason: "missing" | "forced" | "corrupt") => void;
+  } = {},
+): Promise<{ outcome: EnsureOutcome; verified: boolean }> {
+  const digest = await fetchUpstreamDigest(url);
+
+  if (existsSync(dest) && !opts.force) {
+    if (!digest) return { outcome: "reused", verified: false };
+    const actual = await sha256OfFile(dest);
+    if (actual === digest.sha256) return { outcome: "reused", verified: true };
+    // Present but wrong — the corrupt-and-skipped case. Replace it.
+    rmSync(dest, { force: true });
+    opts.onBeforeDownload?.("corrupt");
+    await downloadTo(url, dest, { sha256: digest.sha256 });
+    return { outcome: "repaired", verified: true };
+  }
+
+  opts.onBeforeDownload?.(existsSync(dest) ? "forced" : "missing");
+  await downloadTo(url, dest, { sha256: digest?.sha256 ?? null });
+  return { outcome: "downloaded", verified: digest !== null };
 }

package/src/transcription/install-python.test.ts

@@ -328,7 +328,8 @@ describe("installPythonBackend — warm-pull + verify", () => {
       files,
       run: async (cmd) => {
         if (cmd.some((c) => c.endsWith("/pip"))) files.add(venvBin("onnx-asr"));
-        if (cmd.includes("--help")) return { exitCode: 1, stdout: "", stderr: "offline" };
+        // Warm-pull is `<bin> <model> --help`; verify is `<bin> --help`.
+        if (cmd.includes("--help") && cmd.length > 2) return { exitCode: 1, stdout: "", stderr: "offline" };
         return { exitCode: 0, stdout: "", stderr: "" };
       },
     });
@@ -349,7 +350,8 @@ describe("installPythonBackend — warm-pull + verify", () => {
     const out = await installPythonBackend(deps, { provider: "parakeet-mlx" });
     expect(out.ok).toBe(true);
     expect(out.steps.find((s) => s.name === "model-warm-pull")!.status).toBe("skipped");
-    expect(runs.some((r) => r.includes("--help"))).toBe(false);
+    expect(runs.some((r) => r.length > 2 && r.includes("--help"))).toBe(false);
+    expect(runs.some((r) => r.length === 2 && r[1] === "--help")).toBe(true);
   });
 
   test("HONEST verify: pip 'succeeds' but no binary appears → ok:false, no activation signal", async () => {
@@ -363,4 +365,23 @@ describe("installPythonBackend — warm-pull + verify", () => {
     expect(out.binPath).toBeUndefined();
     expect(out.steps.find((s) => s.name === "verify")!.status).toBe("failed");
   });
+
+  test("HONEST verify: binary exists but --help fails → ok:false (vault#539)", async () => {
+    const files = new Set<string>([venvBin("onnx-asr")]);
+    const { deps } = makeDeps({
+      path: { python3: "/usr/bin/python3", ffmpeg: "/usr/bin/ffmpeg" },
+      files,
+      run: async (cmd) => {
+        if (cmd.length === 2 && cmd[1] === "--help") {
+          return { exitCode: 127, stdout: "", stderr: "No such file or directory: python3" };
+        }
+        return { exitCode: 0, stdout: "", stderr: "" };
+      },
+    });
+    const out = await installPythonBackend(deps, { provider: "onnx-asr", skipModel: true });
+    expect(out.ok).toBe(false);
+    expect(out.binPath).toBeUndefined();
+    expect(out.steps.find((s) => s.name === "verify")!.status).toBe("failed");
+    expect(out.steps.find((s) => s.name === "verify")!.detail).toMatch(/--help/);
+  });
 });

package/src/transcription/install-python.ts

@@ -301,16 +301,25 @@ export async function installPythonBackend(
     record(await warmPullModel(deps, spec, opts.model ?? spec.defaultModel));
   }
 
-  // --- Verify: a runnable binary via the same ladder the daemon uses --------
+  // --- Verify: EXECUTE the binary (--help), not just existsSync (vault#539) --
+  // Same honesty as probeTranscribeCliRunnable: a venv entrypoint can exist
+  // and still fail (moved PARACHUTE_HOME, deleted interpreter, half-finished
+  // pip). Per-request capability gates stay spawn-free; this is install-time.
   const binPath = resolveBin(spec, deps);
-  const runnable = !!binPath && deps.existsImpl(binPath);
   const venv = pythonVenvDir(deps.env);
-  if (!runnable) {
+  if (!binPath || !deps.existsImpl(binPath)) {
     const detail = `install ran but no runnable \`${spec.bin}\` was found (looked at ${join(venv, "bin", spec.bin)} and PATH).`;
     record({ name: "verify", status: "failed", detail });
     return fail(`${spec.provider} install did not produce a runnable binary. ${detail}`);
   }
-  record({ name: "verify", status: "ok", detail: `runnable binary at ${binPath}.` });
+  const help = await deps.run([binPath, "--help"]);
+  if (help.exitCode !== 0) {
+    const reason = help.stderr.trim().split("\n")[0]?.slice(0, 200) || `exit ${help.exitCode}`;
+    const detail = `\`${spec.bin} --help\` failed (${reason}). A present file is not a runnable provider.`;
+    record({ name: "verify", status: "failed", detail });
+    return fail(`${spec.provider} binary exists but is not runnable. ${detail}`);
+  }
+  record({ name: "verify", status: "ok", detail: `runnable binary at ${binPath} (verified --help).` });
 
   const summary = `${spec.provider} installed and verified runnable (${binPath}).`;
   deps.log(summary);