@openparachute/vault 0.6.5-rc.10 → 0.6.5-rc.12

package/core/src/core.test.ts

@@ -4046,7 +4046,7 @@ describe("query-notes link expansion", async () => {
 });
 
 // ---------------------------------------------------------------------------
-// Tag hierarchy via tags.parent_names (post-v14, patterns/tag-data-model.md)
+// Tag hierarchy via tags.parent_names (post-v14, docs/contracts/tag-data-model.md)
 // ---------------------------------------------------------------------------
 
 describe("tag hierarchy (tags.parent_names)", async () => {
@@ -5107,7 +5107,7 @@ describe("schema inheritance via parent_names (vault#270)", async () => {
   });
 });
 
-describe("expandTagsWithDescendants (tag-scoped tokens — patterns/tag-scoped-tokens.md)", async () => {
+describe("expandTagsWithDescendants (tag-scoped tokens — docs/contracts/tag-scoped-tokens.md)", async () => {
   it("returns the union of root + every descendant per tags.parent_names", async () => {
     await store.upsertTagRecord("health/food", { parent_names: ["health"] });
     await store.upsertTagRecord("health/food/breakfast", { parent_names: ["health/food"] });
@@ -5143,10 +5143,10 @@ describe("expandTagsWithDescendants (tag-scoped tokens — patterns/tag-scoped-t
 });
 
 // ---------------------------------------------------------------------------
-// Tag record API — patterns/tag-data-model.md
+// Tag record API — docs/contracts/tag-data-model.md
 // ---------------------------------------------------------------------------
 
-describe("tag record API (patterns/tag-data-model.md)", async () => {
+describe("tag record API (docs/contracts/tag-data-model.md)", async () => {
   it("upsertTagRecord persists description + fields + relationships + parent_names", async () => {
     await store.upsertTagRecord("project", {
       description: "long-running deliverable",
@@ -5430,7 +5430,7 @@ describe("tag record API (patterns/tag-data-model.md)", async () => {
 });
 
 // ---------------------------------------------------------------------------
-// Schema migration v13 → v14 — patterns/tag-data-model.md
+// Schema migration v13 → v14 — docs/contracts/tag-data-model.md
 // ---------------------------------------------------------------------------
 
 describe("schema migration v13 → v14", async () => {
@@ -5809,7 +5809,7 @@ describe("schema migration v15 → v16", async () => {
 });
 
 // ---------------------------------------------------------------------------
-// Tag-scope auth post-v14 — patterns/tag-scoped-tokens.md
+// Tag-scope auth post-v14 — docs/contracts/tag-scoped-tokens.md
 // ---------------------------------------------------------------------------
 
 describe("tag-scope auth (post-v14 hierarchy)", async () => {
@@ -5824,7 +5824,7 @@ describe("tag-scope auth (post-v14 hierarchy)", async () => {
   });
 
   it("orphan sub-tag fallback: token for `health` still sees `#health/food` even with no declared hierarchy", async () => {
-    // Per patterns/tag-scoped-tokens.md §Storage details, the auth check
+    // Per docs/contracts/tag-scoped-tokens.md §Storage details, the auth check
     // also splits on '/' and matches the root verbatim against the raw
     // allowlist. This survives the v14 source-of-truth swap because the
     // fallback lives in src/tag-scope.ts, not in the resolver.

package/core/src/mcp.ts

@@ -1408,7 +1408,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     {
       name: "update-tag",
       requiredVerb: "write",
-      description: "Create or update a tag's identity row: description, indexed-field schemas, relationship-vocabulary map, and hierarchy parents. If the tag doesn't exist, it's created. Fields are merged (new keys added, existing keys replaced); relationships and parent_names are replaced wholesale when provided. Pass null for fields/relationships/parent_names to clear that column. See parachute-patterns/patterns/tag-data-model.md.",
+      description: "Create or update a tag's identity row: description, indexed-field schemas, relationship-vocabulary map, and hierarchy parents. If the tag doesn't exist, it's created. Fields are merged (new keys added, existing keys replaced); relationships and parent_names are replaced wholesale when provided. Pass null for fields/relationships/parent_names to clear that column. See parachute-vault/docs/contracts/tag-data-model.md.",
       inputSchema: {
         type: "object",
         properties: {

package/core/src/schema.ts

@@ -41,7 +41,7 @@ CREATE TABLE IF NOT EXISTS notes (
 
 -- Tags: first-class identity carrying schema, hierarchy, and typed-link
 -- declarations. One row per tag; no notes-as-config sidecars for these
--- concerns. See parachute-patterns/patterns/tag-data-model.md.
+-- concerns. See docs/contracts/tag-data-model.md.
 --
 -- description    — human-readable blurb (markdown).
 -- fields         — JSON: indexed metadata field declarations per
@@ -136,7 +136,7 @@ CREATE TABLE IF NOT EXISTS indexed_fields (
 -- scoped_tags is a JSON-encoded array of root tag names that constrain the
 -- token's effective access (intersection with the scopes column). NULL
 -- means unscoped — full vault access per scopes. Introduced in v13 per
--- patterns/tag-scoped-tokens.md. Hierarchy expansion is applied at auth
+-- docs/contracts/tag-scoped-tokens.md. Hierarchy expansion is applied at auth
 -- time via getTagDescendants; the column stores root names only.
 --
 -- vault_name (v16) binds the token to a single vault. NULL means the
@@ -443,7 +443,7 @@ export function initSchema(db: Database): void {
   // Migrate v13 → v14: tag-data-model reshape. Augment `tags` row with
   // description/fields/relationships/parent_names/timestamps; copy data
   // from the v6-era tag_schemas sidecar and from `_tags/<name>` config
-  // notes; drop tag_schemas after copy. See patterns/tag-data-model.md.
+  // notes; drop tag_schemas after copy. See docs/contracts/tag-data-model.md.
   migrateToV14(db);
 
   // Migrate v14 → v15: retire the `_schemas/<name>` and `_schema_defaults`
@@ -650,7 +650,7 @@ function migrateToV12(db: Database): void {
  * (current full-vault behavior); a JSON array of root tag names narrows the
  * token's access to notes carrying one of those tags or a sub-tag thereof
  * (hierarchy expansion via getTagDescendants at auth time). See
- * parachute-patterns/patterns/tag-scoped-tokens.md.
+ * docs/contracts/tag-scoped-tokens.md.
  */
 function migrateToV13(db: Database): void {
   if (hasTable(db, "tokens") && !hasColumn(db, "tokens", "scoped_tags")) {
@@ -659,7 +659,7 @@ function migrateToV13(db: Database): void {
 }
 
 /**
- * Migrate v13 → v14: tag-data-model reshape (patterns/tag-data-model.md).
+ * Migrate v13 → v14: tag-data-model reshape (docs/contracts/tag-data-model.md).
  *
  * Augments the `tags` table with five new columns and one timestamp pair,
  * then copies pre-existing data from two notes-as-config sidecars:

package/core/src/tag-hierarchy.ts

@@ -9,7 +9,7 @@
  * History: pre-v14 vaults stored hierarchy in notes-as-config at
  * `_tags/<name>`. The v14 migration (see core/src/schema.ts:migrateToV14)
  * lifts those parent declarations onto the tags row and the resolver here
- * was swapped accordingly. See parachute-patterns/patterns/tag-data-model.md.
+ * was swapped accordingly. See docs/contracts/tag-data-model.md.
  *
  * Resolution model:
  * - Lazy: built on first access, cached on the store.

package/core/src/tag-schemas.ts

@@ -4,7 +4,7 @@
  * Each tag row carries: human-readable description, indexed metadata field
  * declarations (`fields`), typed-link relationship declarations
  * (`relationships`), and the hierarchy parent list (`parent_names`).
- * See parachute-patterns/patterns/tag-data-model.md.
+ * See docs/contracts/tag-data-model.md.
  *
  * This module retains the historical `tag-schemas` filename and exports
  * (`TagSchema`, `listTagSchemas`, `getTagSchema`, `upsertTagSchema`,
@@ -51,7 +51,7 @@ export interface TagFieldSchema {
  * `{ target_tag, cardinality }` declaration — but `relationships` is now an
  * opaque vocabulary map (see `TagRelationshipMap` / `validateRelationships`),
  * so this is one valid value shape among many, not a required one.
- * See patterns/tag-data-model.md §Relationships.
+ * See docs/contracts/tag-data-model.md §Relationships.
  */
 export type TagRelCardinality = "one" | "optional" | "many" | "many-required";
 

package/core/src/types.ts

@@ -406,7 +406,7 @@ export interface Store {
 
   // Tag records — full v14 identity row (description + fields + typed
   // relationships + parent_names + timestamps). See
-  // parachute-patterns/patterns/tag-data-model.md.
+  // docs/contracts/tag-data-model.md.
   listTagRecords(): Promise<TagRecord[]>;
   getTagRecord(tag: string): Promise<TagRecord | null>;
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.6.5-rc.10",
+  "version": "0.6.5-rc.12",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/admin-spa.ts

@@ -8,7 +8,8 @@
  *
  * Per-vault mount (vault#252): the SPA lives under `/vault/<name>/admin/*`
  * rather than the origin-rooted `/admin/*` it shipped with. The hub only
- * proxies `/vault/<name>/*` paths (per parachute-patterns/module-protocol),
+ * proxies `/vault/<name>/*` paths (per the module protocol —
+ * https://github.com/ParachuteComputer/parachute-hub/blob/main/docs/contracts/module-protocol.md),
  * so an origin-rooted SPA is unreachable through the hub. Asset URLs are
  * relative (Vite `base: "./"`), so the same bundle works at any mount
  * point — no rebuild per vault.

package/src/auth.ts

@@ -123,7 +123,7 @@ export interface AuthResult {
    * Tag-allowlist (root tag names) for tag-scoped tokens. NULL = unscoped
    * (current full-vault behavior). Hub-issued JWTs and legacy YAML keys
    * always have null — tag scoping is a per-token vault-DB attribute, not
-   * an OAuth-claim concern. See patterns/tag-scoped-tokens.md.
+   * an OAuth-claim concern. See docs/contracts/tag-scoped-tokens.md.
    */
   scoped_tags: string[] | null;
   /**

package/src/cli.ts

@@ -152,6 +152,7 @@ import {
   resolveTranscribeCppPaths,
   resolveTranscriptionProviderName,
   transcribeCppInstalled,
+  probeTranscribeCliRunnable,
   readManifest,
   transcriptionHomeDir,
   pythonVenvDir,
@@ -173,6 +174,7 @@ import {
   TRANSCRIBE_CPP_SOURCE_REF,
   type CliBuildResult,
 } from "./transcription/build.ts";
+import { downloadTo } from "./transcription/download.ts";
 import { selectDefaultProvider, NOMINAL_SLACK_GB, type TierPlan } from "./transcription/tiers.ts";
 import {
   PYTHON_PROVIDERS,
@@ -3572,7 +3574,7 @@ async function cmdTranscription(args: string[]) {
     return;
   }
   if (sub === "status" || sub === undefined) {
-    cmdTranscriptionStatus();
+    await cmdTranscriptionStatus();
     return;
   }
   console.error(`Unknown transcription subcommand: ${sub}`);
@@ -3867,14 +3869,25 @@ async function runTranscribeCppInstall(opts: {
 
     // 5) CLI resolution + provider switch — honest, no silent success. `binPath`
     //    resolves to TRANSCRIBE_CPP_BIN or the built binary; we activate
-    //    transcribe-cpp only when one actually exists, else we keep the current
-    //    provider and report the acquisition gap rather than taking
-    //    transcription offline behind a provider that can't run.
+    //    transcribe-cpp only when one actually EXECUTES (`--help` exits 0 —
+    //    vault#534: an existsSync-only check activated Linux installs whose CLI
+    //    exited 1 on every run). Otherwise we keep the current provider and
+    //    report the gap rather than taking transcription offline behind a
+    //    provider that can't run.
     if (existsSync(paths.binPath)) {
-      setEnvVar("TRANSCRIPTION_PROVIDER", "transcribe-cpp");
-      console.log(`\n✓ Installed and activated → TRANSCRIPTION_PROVIDER=transcribe-cpp set in the vault .env.`);
-      console.log(`  CLI:   ${paths.binPath}`);
-      console.log(`  Restart vault to activate:  parachute restart vault`);
+      const probe = await probeTranscribeCliRunnable(paths.binPath);
+      if (probe.ok) {
+        setEnvVar("TRANSCRIPTION_PROVIDER", "transcribe-cpp");
+        console.log(`\n✓ Installed and activated → TRANSCRIPTION_PROVIDER=transcribe-cpp set in the vault .env.`);
+        console.log(`  CLI:   ${paths.binPath} (verified runnable)`);
+        console.log(`  Restart vault to activate:  parachute restart vault`);
+      } else {
+        console.log(
+          `\n⚠  transcribe-cli exists at ${paths.binPath} but is NOT runnable (${probe.reason}).`,
+        );
+        console.log("   NOT activating transcribe-cpp — your current provider is unchanged.");
+        console.log(noRunnableCliGuidance(paths, buildResult));
+      }
     } else {
       console.log(`\n✓ Libraries + model installed to ${paths.dir} — transcription is NOT yet activated.`);
       console.log(noRunnableCliGuidance(paths, buildResult));
@@ -3886,13 +3899,6 @@ async function runTranscribeCppInstall(opts: {
   }
 }
 
-/** Download a URL to a destination file (streamed via fetch → Bun.write). */
-async function downloadTo(url: string, dest: string): Promise<void> {
-  const resp = await fetch(url, { redirect: "follow" });
-  if (!resp.ok) throw new Error(`download failed (${resp.status}) for ${url}`);
-  await Bun.write(dest, resp);
-}
-
 /**
  * Download the release tarball, extract it, and place its runtime shared
  * libraries (libtranscribe + libggml `.dylib`/`.so`) into `paths.libsDir`,
@@ -3984,6 +3990,8 @@ async function maybeBuildTranscribeCli(
           await downloadTo(cliSourceUrl(rel), dest);
         }
       },
+      readFile: (p) => readFileSync(p, "utf8"),
+      writeFile: (p, content) => writeFileSync(p, content),
       compile: (cmd) => {
         const p = Bun.spawnSync(cmd);
         return { exitCode: p.exitCode ?? 1, stderr: new TextDecoder().decode(p.stderr) };
@@ -4032,6 +4040,14 @@ function noRunnableCliGuidance(
       "     • build transcribe-cli yourself, point TRANSCRIBE_CPP_BIN at it, and re-run; OR",
       "     • use the remote provider:  parachute-vault transcription install --provider scribe-http",
     );
+  } else if (build && !build.ok && build.stage === "patch") {
+    lines.push(
+      `\n⚠  Could not apply the vault#534 backend-init source patch — ${build.message}`,
+      "   The pinned upstream source no longer matches the patch anchor. This needs a code fix",
+      "   (re-anchor or drop the patch), not a toolchain fix. Until then, either:",
+      "     • build a transcribe-cli yourself, point TRANSCRIBE_CPP_BIN at it, and re-run; OR",
+      "     • use the remote provider:  parachute-vault transcription install --provider scribe-http",
+    );
   } else if (build && !build.ok) {
     lines.push(
       `\n⚠  transcribe-cli build failed (${build.stage}). The libraries + model are installed;`,
@@ -4055,7 +4071,7 @@ function noRunnableCliGuidance(
 }
 
 /** `parachute-vault transcription status` — provider + per-provider install state. */
-function cmdTranscriptionStatus(): void {
+async function cmdTranscriptionStatus(): Promise<void> {
   const active = resolveTranscriptionProviderName();
   console.log(`Configured provider: ${active}`);
 
@@ -4069,12 +4085,24 @@ function cmdTranscriptionStatus(): void {
     `Tier default for this host (${tier.platform}/${tier.arch}, ${tier.totalRamGb}GB): ${tier.provider}${tier.model ? ` (${tier.model})` : ""}`,
   );
 
-  // transcribe-cpp — prebuilt libs + GGUF model + built CLI.
+  // transcribe-cpp — prebuilt libs + GGUF model + built CLI. "runnable" is an
+  // EXECUTED verdict, not a stat: `--help` must actually exit 0 (vault#534 —
+  // an existsSync-only check said "yes" on Linux while the CLI exited 1 on
+  // every real transcription because its dlopen'd CPU backends never loaded).
   const paths = resolveTranscribeCppPaths();
   const manifest = readManifest(paths.manifestPath);
   const cliPresent = existsSync(paths.binPath);
-  const installed = transcribeCppInstalled(paths); // runnable CLI + model both present
-  console.log(`\ntranscribe-cpp runnable: ${installed ? "yes" : "no"}`);
+  const filesPresent = transcribeCppInstalled(paths); // CLI + model both on disk
+  let installed = false;
+  let notRunnableReason: string | undefined;
+  if (!filesPresent) {
+    notRunnableReason = !cliPresent ? "no transcribe-cli binary" : "no GGUF model on disk";
+  } else {
+    const probe = await probeTranscribeCliRunnable(paths.binPath);
+    installed = probe.ok;
+    notRunnableReason = probe.reason;
+  }
+  console.log(`\ntranscribe-cpp runnable: ${installed ? "yes" : `no (${notRunnableReason})`}`);
   if (manifest) {
     console.log(`  model:   ${manifest.model} (${manifest.modelFile})`);
     console.log(

package/src/export-watch.ts

@@ -10,7 +10,7 @@
  * cursor captured at the *start* of the previous cycle. Vault writes are
  * HTTP-mediated and don't surface to filesystem watchers (the bun:sqlite DB
  * is opaque), so polling on `updated_at >= cursor` is the simplest robust
- * detection. See `parachute-patterns/cookbook/vault-portable-export.md`.
+ * detection. See `docs/contracts/vault-portable-export.md`.
  */
 
 import { ensureGitAvailable } from "./git-preflight.ts";

package/src/routes.ts

@@ -2089,7 +2089,7 @@ export async function handleTags(
 
   // PUT /tags/:name — upsert tag identity row. Body accepts any combination
   // of { description, fields, relationships, parent_names }; omitted keys
-  // are preserved, explicit null clears. See patterns/tag-data-model.md.
+  // are preserved, explicit null clears. See docs/contracts/tag-data-model.md.
   if (req.method === "PUT") {
     // Canonical-bare-tag guard (vault#XXX): normalize the upserted tag NAME so
     // the existing-field merge read (store.getTagSchema below) and the upsert
@@ -2114,7 +2114,7 @@ export async function handleTags(
        * the MCP `update-tag` tool relies on (omitted keys preserved). The
        * Schema editor (vault#283) sends the full map + `replace_fields: true`
        * so removing a field row actually deletes the field. See
-       * patterns/tag-data-model.md.
+       * docs/contracts/tag-data-model.md.
        */
       replace_fields?: unknown;
     };
@@ -2211,7 +2211,7 @@ export async function handleTags(
     // Tag-scoped tokens reference root tags by name; deleting a referenced
     // tag would silently orphan the token's allowlist. Fail closed (409)
     // and name the offending tokens so the operator can revoke or re-mint
-    // before retrying. patterns/tag-scoped-tokens.md §Dependencies.
+    // before retrying. docs/contracts/tag-scoped-tokens.md §Dependencies.
     const referenced_by = findTokensReferencingTag(store.db, tagName);
     if (referenced_by.length > 0) {
       return json(

package/src/routing.test.ts

@@ -1631,7 +1631,7 @@ describe("scope enforcement on /api/*", () => {
     expect(res.status).toBe(401);
   });
 
-  // ----- tag-scoped tokens (patterns/tag-scoped-tokens.md) -----------------
+  // ----- tag-scoped tokens (docs/contracts/tag-scoped-tokens.md) -----------------
 
   /**
    * Mint a tag-scoped token. Mirrors `mintToken` above but threads
@@ -1745,7 +1745,7 @@ describe("scope enforcement on /api/*", () => {
   });
 
   // ----- Q6: orphan-sub-tag fail-open ------------------------------------
-  // patterns/tag-scoped-tokens.md §Storage: when a sub-tag has no declared
+  // docs/contracts/tag-scoped-tokens.md §Storage: when a sub-tag has no declared
   // schema, the string-form root authorizes. Token allowlisted for `health`
   // must see `#health/food` even when no `_tags/health/food` schema exists.
 

package/src/routing.ts

@@ -856,7 +856,7 @@ export async function route(
 
   const apiPath = apiMatch[1] ?? "";
 
-  // Tag-scoped tokens (patterns/tag-scoped-tokens.md): expand the token's
+  // Tag-scoped tokens (docs/contracts/tag-scoped-tokens.md): expand the token's
   // root-tag allowlist into `{root} ∪ descendants(root)` once per request,
   // so handlers can intersect against the note's tag set without re-walking
   // the `_tags/<name>` hierarchy on every check. `tagScope.allowed` is null

package/src/tag-scope.ts

@@ -1,12 +1,12 @@
 /**
- * Tag-scope enforcement for tag-scoped tokens (patterns/tag-scoped-tokens.md).
+ * Tag-scope enforcement for tag-scoped tokens (docs/contracts/tag-scoped-tokens.md).
  *
  * A token's `scoped_tags` allowlist narrows its effective access to notes
  * carrying one of the allowlisted tags or a sub-tag thereof. The expansion
  * to descendants happens via the per-vault `_tags/<name>` config-note
  * hierarchy (see core/src/tag-hierarchy.ts).
  *
- * Auth check pseudocode (from patterns/tag-scoped-tokens.md):
+ * Auth check pseudocode (from docs/contracts/tag-scoped-tokens.md):
  *
  *   if (!hasScope(token, ...)) return forbidden();
  *   if (token.scoped_tags === null) return ok();   // unscoped
@@ -38,7 +38,7 @@ export async function expandTokenTagScope(
 
 /**
  * Return true iff the note's tag set intersects the expanded allowlist OR
- * — fail-open per patterns/tag-scoped-tokens.md §Storage — any of the
+ * — fail-open per docs/contracts/tag-scoped-tokens.md §Storage — any of the
  * note's tags has a string-form root inside `rawRoots`. The string-form
  * fallback covers the orphan-sub-tag case: a token allowlisted for
  * `health` should still see `#health/food` even when no `_tags/health/food`

package/src/token-store.ts

@@ -54,7 +54,7 @@ export interface Token {
    * access is the intersection of `scopes` and notes carrying one of these
    * tags or a sub-tag thereof (hierarchy expansion via getTagDescendants).
    * NULL = unscoped, full vault access per `scopes`. See
-   * patterns/tag-scoped-tokens.md.
+   * docs/contracts/tag-scoped-tokens.md.
    */
   scoped_tags: string[] | null;
   /**
@@ -301,7 +301,7 @@ export function markMcpMintLedgerRevoked(
  * Returns display ID + label pairs (no token-hash exposure) so error
  * envelopes can name the offending tokens for the operator. The match is
  * exact on the root name — `scoped_tags` only ever stores roots per
- * patterns/tag-scoped-tokens.md.
+ * docs/contracts/tag-scoped-tokens.md.
  */
 export function findTokensReferencingTag(
   db: Database,

package/src/transcription/build.test.ts

@@ -6,6 +6,9 @@ import {
   detectCompiler,
   compilerInstallHint,
   cliSourceUrl,
+  patchMainCppBackendInit,
+  BACKEND_INIT_PATCH_ANCHOR,
+  BACKEND_INIT_PATCH_MARKER,
   CLI_SOURCE_FILES,
   CXX_CANDIDATES,
   TRANSCRIBE_CPP_SOURCE_REF,
@@ -17,10 +20,26 @@ import {
  * transcribe-cli build tests (scribe-fold Phase 2b). Pure recipe shape +
  * fully-mocked orchestration — NO network, NO real compiler (the real compile
  * is exercised only by the install-time live verify). Covers the toolchain-
- * absent, fetch-failure, compile-failure, and success branches, and the
- * "never leave a half-built binary" invariant.
+ * absent, fetch-failure, patch-failure, compile-failure, and success branches,
+ * and the "never leave a half-built binary" invariant.
  */
 
+/** A minimal stand-in for the pinned main.cpp: log-sink install + the batch-
+ *  mode comment the vault#534 patch anchors on. */
+const MAIN_CPP_FIXTURE = [
+  "int main(int argc, char ** argv) {",
+  "    if (!args.quiet) {",
+  "        transcribe_log_set(log_cb, nullptr);",
+  "    }",
+  "",
+  BACKEND_INIT_PATCH_ANCHOR,
+  "    // the model ONCE and reuses the context across all files.",
+  "    if (!args.batch_file.empty()) {",
+  "    }",
+  "}",
+  "",
+].join("\n");
+
 describe("detectCompiler", () => {
   test("returns the first candidate found (c++ preferred)", () => {
     const which = (c: string) => (c === "c++" ? "/usr/bin/c++" : null);
@@ -106,15 +125,31 @@ describe("buildCompileCommand — the proven recipe shape", () => {
 
 /** Build a deps object with call-recording mocks; overrides win. */
 function mkDeps(over: Partial<BuildCliDeps> = {}): BuildCliDeps & {
-  calls: { fetch: number; compile: number; removed: string[]; renamed: Array<[string, string]> };
+  calls: {
+    fetch: number;
+    compile: number;
+    removed: string[];
+    renamed: Array<[string, string]>;
+    written: Array<[string, string]>;
+  };
 } {
-  const calls = { fetch: 0, compile: 0, removed: [] as string[], renamed: [] as Array<[string, string]> };
+  const calls = {
+    fetch: 0,
+    compile: 0,
+    removed: [] as string[],
+    renamed: [] as Array<[string, string]>,
+    written: [] as Array<[string, string]>,
+  };
   const deps: BuildCliDeps = {
     platform: "darwin",
     which: (c) => (c === "c++" ? "/usr/bin/c++" : null),
     fetchSource: async () => {
       calls.fetch++;
     },
+    readFile: () => MAIN_CPP_FIXTURE,
+    writeFile: (p, content) => {
+      calls.written.push([p, content]);
+    },
     compile: async (): Promise<CompileResult> => {
       calls.compile++;
       return { exitCode: 0, stderr: "" };
@@ -134,8 +169,36 @@ function mkDeps(over: Partial<BuildCliDeps> = {}): BuildCliDeps & {
 const INPUT = { srcDir: "/t/.src", libsDir: "/t/libs", binPath: "/t/bin/transcribe-cli" };
 const TMP = `${INPUT.binPath}.building`; // the temp output the build compiles to
 
+describe("patchMainCppBackendInit — the vault#534 backend-init source patch", () => {
+  test("injects transcribe_init_backends_default() before the batch-mode anchor", () => {
+    const patched = patchMainCppBackendInit(MAIN_CPP_FIXTURE);
+    expect(patched).toContain("transcribe_init_backends_default();");
+    expect(patched).toContain(BACKEND_INIT_PATCH_MARKER);
+    // The init call lands BEFORE the inference paths (the anchor) and AFTER
+    // the log-sink install, so backend plugin-load logs route through the sink.
+    const initAt = patched.indexOf("transcribe_init_backends_default();");
+    expect(initAt).toBeGreaterThan(patched.indexOf("transcribe_log_set(log_cb, nullptr);"));
+    expect(initAt).toBeLessThan(patched.indexOf(BACKEND_INIT_PATCH_ANCHOR));
+    // Everything else is preserved verbatim: removing the injected block
+    // restores the original source exactly.
+    const [before, after] = patched.split(/    \/\/ \[parachute-vault[\s\S]*?transcribe_init_backends_default\(\);\n\n/);
+    expect(`${before}${after}`).toBe(MAIN_CPP_FIXTURE);
+  });
+
+  test("idempotent: an already-patched source is returned unchanged", () => {
+    const once = patchMainCppBackendInit(MAIN_CPP_FIXTURE);
+    expect(patchMainCppBackendInit(once)).toBe(once);
+  });
+
+  test("anchor missing ⇒ throws a loud, actionable error naming the pin + vault#534", () => {
+    expect(() => patchMainCppBackendInit("int main() { return 0; }\n")).toThrow(
+      /anchor not found[\s\S]*vault#534/,
+    );
+  });
+});
+
 describe("buildTranscribeCli — orchestration branches", () => {
-  test("SUCCESS: fetch → compile ok → temp exists ⇒ promote (rename) + { ok:true }", async () => {
+  test("SUCCESS: fetch → patch → compile ok → temp exists ⇒ promote (rename) + { ok:true }", async () => {
     const deps = mkDeps();
     const r = await buildTranscribeCli(INPUT, deps);
     expect(r.ok).toBe(true);
@@ -149,11 +212,29 @@ describe("buildTranscribeCli — orchestration branches", () => {
     }
     expect(deps.calls.fetch).toBe(1);
     expect(deps.calls.compile).toBe(1);
+    // the vault#534 backend-init patch was written into the fetched main.cpp
+    expect(deps.calls.written).toHaveLength(1);
+    const [patchedPath, patchedContent] = deps.calls.written[0]!;
+    expect(patchedPath).toBe(join(INPUT.srcDir, "examples", "cli", "main.cpp"));
+    expect(patchedContent).toContain("transcribe_init_backends_default();");
     // only the TEMP is cleared pre-compile; the fresh temp is renamed into place
     expect(deps.calls.removed).toEqual([TMP]);
     expect(deps.calls.renamed).toEqual([[TMP, INPUT.binPath]]);
   });
 
+  test("PATCH FAILURE: anchor missing in fetched source ⇒ { ok:false, stage:'patch' }, no write, no compile", async () => {
+    const deps = mkDeps({ readFile: () => "int main() { return 0; }\n" });
+    const r = await buildTranscribeCli(INPUT, deps);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.stage).toBe("patch");
+      expect(r.message).toContain("anchor not found");
+      expect(r.message).toContain("vault#534");
+    }
+    expect(deps.calls.written).toEqual([]);
+    expect(deps.calls.compile).toBe(0);
+  });
+
   test("TOOLCHAIN ABSENT: no compiler ⇒ { ok:false, stage:'toolchain' }, no fetch/compile", async () => {
     const deps = mkDeps({ which: () => null });
     const r = await buildTranscribeCli(INPUT, deps);

package/src/transcription/build.ts

@@ -6,8 +6,10 @@
  * `install.ts` + the provider-seam design doc. This module closes that gap: it
  * fetches the CLI's source (`examples/cli/main.cpp` + `examples/common/wav.cpp`
  * + the public headers) from the transcribe.cpp repo pinned at the v0.1.1 tag
- * commit, then compiles it with the host C++ compiler against the extracted
- * prebuilt dylibs. The result is a ~127KB driver that links the prebuilt
+ * commit, applies the **vault#534 backend-init patch** (see
+ * `patchMainCppBackendInit` below — temporary until upstream ships the fix),
+ * then compiles it with the host C++ compiler against the extracted prebuilt
+ * dylibs. The result is a ~127KB driver that links the prebuilt
  * `libtranscribe` at runtime — **no ggml / Metal rebuild**.
  *
  * ## The proven recipe (live-verified 2026-07-03, macOS arm64 M4)
@@ -34,10 +36,11 @@
  * ## Testability
  *
  * `buildTranscribeCli` is a pure orchestrator over injected side effects
- * (`which` / `fetchSource` / `compile` / `exists` / `removeBin`), mirroring the
- * provider's `SpawnRunner` seam. Tests exercise every branch — toolchain
- * absent, fetch failure, compile failure, success — with no network and no real
- * compiler. The real compile is exercised only by the install-time live verify.
+ * (`which` / `fetchSource` / `readFile` / `writeFile` / `compile` / `exists` /
+ * `removeBin`), mirroring the provider's `SpawnRunner` seam. Tests exercise
+ * every branch — toolchain absent, fetch failure, patch failure, compile
+ * failure, success — with no network and no real compiler. The real compile is
+ * exercised only by the install-time live verify.
  */
 
 import { join } from "path";
@@ -78,6 +81,63 @@ export function cliSourceUrl(repoPath: string): string {
   return `${RAW_BASE}/${repoPath}`;
 }
 
+// ---------------------------------------------------------------------------
+// Build-time source patch: unconditional backend init (vault#534 blocker 2)
+// ---------------------------------------------------------------------------
+
+/** Marker comment baked into the injected code — makes the patch idempotent
+ *  and greppable in a fetched source tree. */
+export const BACKEND_INIT_PATCH_MARKER = "[parachute-vault vault#534 backend-init patch]";
+
+/**
+ * The anchor line in the pinned `examples/cli/main.cpp` the patch injects
+ * before: the batch-mode comment that opens the inference half of `main()`,
+ * directly AFTER the log-sink install (so backend plugin-load logs route
+ * through the CLI's log callback) and after the `--list-devices` early return.
+ * Unique at the pinned ref (verified); if the pin ever advances and this
+ * anchor drifts, the build fails LOUDLY (stage "patch") so the patch gets
+ * re-evaluated against the new source instead of silently shipping a CLI that
+ * can't transcribe on Linux.
+ */
+export const BACKEND_INIT_PATCH_ANCHOR =
+  "    // Batch mode: --batch reads a file list, one wav path per line. Loads";
+
+const BACKEND_INIT_PATCH_BLOCK = `    // ${BACKEND_INIT_PATCH_MARKER}
+    // Upstream (at the pinned ${TRANSCRIBE_CPP_SOURCE_REF.slice(0, 12)}) only calls
+    // transcribe_init_backends_default() in the --list-devices path. On Linux
+    // the CPU backends are dlopen plugins (libggml-cpu-*.so), so with no init
+    // the ggml device registry is empty and EVERY transcription fails
+    // ("whisper: failed to initialize CPU backend", exit 1). macOS is masked:
+    // its libtranscribe.dylib direct-links libggml-cpu, which self-registers
+    // at library load. Init the default backends unconditionally before any
+    // inference (batch or single-file). Verified fix on real Linux containers,
+    // both arches — see vault#534. DROP THIS PATCH when upstream ships the fix
+    // and the source pin advances past it.
+    transcribe_init_backends_default();
+
+`;
+
+/**
+ * Apply the vault#534 backend-init patch to the fetched `main.cpp` source.
+ * Pure (string → string) so tests pin the behavior without a filesystem.
+ * Idempotent: an already-patched source is returned unchanged. Throws with a
+ * clear operator-facing message when the anchor is missing — the caller
+ * surfaces it as a `stage: "patch"` build failure (fail loudly; never compile
+ * an unpatched CLI on the assumption it'll work).
+ */
+export function patchMainCppBackendInit(source: string): string {
+  if (source.includes(BACKEND_INIT_PATCH_MARKER)) return source;
+  const idx = source.indexOf(BACKEND_INIT_PATCH_ANCHOR);
+  if (idx === -1) {
+    throw new Error(
+      `backend-init patch anchor not found in examples/cli/main.cpp at ${TRANSCRIBE_CPP_SOURCE_REF.slice(0, 12)} — ` +
+        `the pinned source no longer matches the vault#534 patch. If the pin advanced, check whether upstream ` +
+        `now calls transcribe_init_backends_default() unconditionally (then drop the patch); otherwise re-anchor it.`,
+    );
+  }
+  return source.slice(0, idx) + BACKEND_INIT_PATCH_BLOCK + source.slice(idx);
+}
+
 /** C++ compiler binaries we probe for, in preference order. */
 export const CXX_CANDIDATES = ["c++", "clang++", "g++"] as const;
 
@@ -158,6 +218,10 @@ export interface BuildCliDeps {
   which: (cmd: string) => string | null | undefined;
   /** Fetch `files` (repo-relative) into `srcDir`. Throws on network failure. */
   fetchSource: (files: readonly string[], srcDir: string) => Promise<void>;
+  /** Read a fetched source file as UTF-8 (production: `fs.readFileSync`). */
+  readFile: (p: string) => string;
+  /** Write a patched source file (production: `fs.writeFileSync`). */
+  writeFile: (p: string, content: string) => void;
   /** Run the compiler argv. */
   compile: (cmd: string[]) => CompileResult | Promise<CompileResult>;
   /** Existence probe (production: `fs.existsSync`). */
@@ -185,7 +249,7 @@ export type CliBuildResult =
   | {
       ok: false;
       /** Which stage failed — drives the operator guidance. */
-      stage: "toolchain" | "fetch" | "compile";
+      stage: "toolchain" | "fetch" | "patch" | "compile";
       message: string;
       compiler?: string;
       /** The compile argv (as a string) when we got far enough to build one. */
@@ -223,6 +287,22 @@ export async function buildTranscribeCli(
     };
   }
 
+  // Apply the vault#534 backend-init source patch BEFORE compiling — without
+  // it the built CLI exits 1 on every transcription on Linux (dlopen'd CPU
+  // backends are never registered). A missing anchor is a loud, typed failure,
+  // never a silent skip.
+  const mainCppPath = join(input.srcDir, "examples", "cli", "main.cpp");
+  try {
+    deps.writeFile(mainCppPath, patchMainCppBackendInit(deps.readFile(mainCppPath)));
+  } catch (err) {
+    return {
+      ok: false,
+      stage: "patch",
+      compiler,
+      message: err instanceof Error ? err.message : String(err),
+    };
+  }
+
   const common = { platform: deps.platform, compiler, srcDir: input.srcDir, libsDir: input.libsDir };
   // The reported command targets the FINAL binPath (what an operator would run
   // by hand to reproduce). The actual compile writes to a temp sibling and is

package/src/transcription/download.test.ts

@@ -0,0 +1,101 @@
+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";
+
+/**
+ * `downloadTo` tests (vault#534 blocker 1). The manual body→FileSink pump
+ * replaced `Bun.write(dest, resp)`, which hangs forever on Linux for large
+ * responses. These run the pump against an in-process `Bun.serve` (no
+ * subprocess involved — see CLAUDE.md's spawnSync note; plain in-process
+ * fetches are fine) and pin: bytes land intact, HTTP errors throw, and a
+ * mid-stream failure never leaves a partial file behind.
+ */
+
+const dir = mkdtempSync(join(tmpdir(), "vault-download-test-"));
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+// 4MB of deterministic non-trivial bytes — large enough to stream in many
+// chunks (the hang was specific to the large-response path).
+const PAYLOAD = new Uint8Array(4 * 1024 * 1024);
+for (let i = 0; i < PAYLOAD.length; i++) PAYLOAD[i] = (i * 31 + (i >> 8)) & 0xff;
+
+function serve(handler: (req: Request) => Response | Promise<Response>) {
+  const server = Bun.serve({ port: 0, fetch: handler });
+  return { server, url: `http://127.0.0.1:${server.port}` };
+}
+
+describe("downloadTo", () => {
+  test("streams a multi-MB body to disk byte-for-byte", async () => {
+    const { server, url } = serve(() => new Response(PAYLOAD));
+    const dest = join(dir, "ok.bin");
+    try {
+      await downloadTo(`${url}/file`, dest);
+      const got = readFileSync(dest);
+      expect(got.byteLength).toBe(PAYLOAD.byteLength);
+      expect(Buffer.from(got).equals(Buffer.from(PAYLOAD))).toBe(true);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("non-OK status throws with the status + URL, writes nothing", async () => {
+    const { server, url } = serve(() => new Response("nope", { status: 404 }));
+    const dest = join(dir, "missing.bin");
+    try {
+      expect(downloadTo(`${url}/gone`, dest)).rejects.toThrow(/download failed \(404\)/);
+      expect(existsSync(dest)).toBe(false);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("truncated download throws AND removes the partial file", async () => {
+    // Raw TCP fixture: a real content-length response (how GitHub releases +
+    // HuggingFace serve these binaries) whose connection dies mid-body.
+    // Bun.serve can't fixture this — it re-frames streamed responses as
+    // chunked (dropping content-length), and Bun's fetch ends a truncated
+    // chunked stream CLEANLY, so truncation is only detectable on the
+    // content-length path `downloadTo` verifies.
+    const partial = PAYLOAD.slice(0, 64 * 1024);
+    const listener = Bun.listen({
+      hostname: "127.0.0.1",
+      port: 0,
+      socket: {
+        data(socket) {
+          socket.write(
+            `HTTP/1.1 200 OK\r\ncontent-type: application/octet-stream\r\ncontent-length: ${PAYLOAD.byteLength}\r\n\r\n`,
+          );
+          socket.write(partial);
+          socket.end(); // die after 64KB of a declared 4MB
+        },
+        open() {},
+        close() {},
+        error() {},
+      },
+    });
+    const dest = join(dir, "partial.bin");
+    try {
+      let threw = false;
+      try {
+        await downloadTo(`http://127.0.0.1:${listener.port}/flaky`, dest);
+      } catch (err) {
+        threw = true;
+        // The truncation surfaces differently per platform: on macOS the body
+        // stream errors mid-pump (wrapped "failed after N bytes") or the
+        // short read trips the content-length check ("truncated"); on Linux
+        // Bun's fetch() itself rejects on the early socket close. All are
+        // loud failures — the invariants are THROWS + NO PARTIAL FILE.
+        expect(String(err)).toMatch(
+          /failed after \d+ bytes|truncated|socket connection was closed|connection closed/i,
+        );
+      }
+      expect(threw).toBe(true);
+      // The half-written file must not survive to be mistaken for a good artifact.
+      expect(existsSync(dest)).toBe(false);
+    } finally {
+      listener.stop(true);
+    }
+  });
+});

package/src/transcription/download.ts

@@ -0,0 +1,71 @@
+/**
+ * Streaming file download for `transcription install` (tarball, GGUF models,
+ * CLI sources).
+ *
+ * ## Why a manual pump instead of `Bun.write(dest, resp)` (vault#534 blocker 1)
+ *
+ * `Bun.write(dest, response)` HANGS FOREVER on Linux when streaming a large
+ * Response body to disk — zero bytes land, no error, no timeout. Reproduced
+ * deterministically in real Linux containers on BOTH arches (aarch64 native +
+ * x86_64 emulated) across bun 1.2.23 / 1.3.13 / 1.3.14, while the identical
+ * code works on macOS. In the same environment `curl` pulls the same URL at
+ * full speed and `await resp.arrayBuffer()` gets all 26MB in ~2s — the bug is
+ * specifically Bun's Response→file streaming fast path. Manually pumping
+ * `resp.body` chunks into a `Bun.file(dest).writer()` moves the same 26MB in
+ * <1s and works on both platforms, so that's what we do everywhere (no
+ * platform gate). See vault#534 for the full container verification.
+ */
+
+import { rmSync } from "fs";
+
+/**
+ * Download `url` to `dest` (follows redirects). Streams chunk-by-chunk — never
+ * buffers the whole body (models run up to ~660MB). On any mid-stream failure
+ * 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.
+ */
+export async function downloadTo(url: string, dest: string): 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}`);
+
+  // content-length is only the on-the-wire byte count when no transfer
+  // decompression happened; fetch auto-decodes content-encoding'd bodies, so
+  // only enforce the size check for identity responses (the normal case for
+  // release tarballs + GGUFs — both already-compressed binary).
+  const encoding = resp.headers.get("content-encoding");
+  const lengthHeader = resp.headers.get("content-length");
+  const expectedBytes =
+    (!encoding || encoding === "identity") && lengthHeader && /^\d+$/.test(lengthHeader)
+      ? Number(lengthHeader)
+      : null;
+
+  const sink = Bun.file(dest).writer();
+  let written = 0;
+  try {
+    for await (const chunk of resp.body) {
+      sink.write(chunk);
+      written += chunk.byteLength;
+    }
+    await sink.end();
+  } catch (err) {
+    // Flush/close what we can, then remove the partial file — a half-written
+    // tarball/model must never survive to be mistaken for a good artifact.
+    try {
+      await sink.end();
+    } catch {
+      // best-effort close; the rm below is what matters
+    }
+    rmSync(dest, { force: true });
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`download of ${url} failed after ${written} bytes: ${msg}`);
+  }
+
+  if (expectedBytes !== null && written !== expectedBytes) {
+    rmSync(dest, { force: true });
+    throw new Error(
+      `download of ${url} was truncated: got ${written} bytes, expected ${expectedBytes} (content-length)`,
+    );
+  }
+}

package/src/transcription/select.test.ts

@@ -1,11 +1,12 @@
 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,
@@ -120,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();

package/src/transcription/select.ts

@@ -182,6 +182,69 @@ export function transcribeCppInstalled(
   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
 // ---------------------------------------------------------------------------

package/src/vault.test.ts

@@ -1093,7 +1093,7 @@ describe("scoped MCP wrapper", async () => {
     close();
   });
 
-  // -- tag-scoped MCP wrappers (patterns/tag-scoped-tokens.md) ------------
+  // -- tag-scoped MCP wrappers (docs/contracts/tag-scoped-tokens.md) ------------
   //
   // These pin the behavior of `applyTagScopeWrappers` in mcp-tools.ts: each
   // wrapped tool's execute() honors the auth's scoped_tags allowlist. The