@openparachute/vault 0.7.6 → 0.7.7

package/src/attachment-tickets.ts

@@ -20,7 +20,7 @@ import { mkdirSync, writeFileSync, existsSync, readFileSync, statSync } from "fs
 import { join, normalize } from "path";
 import type { Store } from "../core/src/types.ts";
 import type { AttachmentTicket, AttachmentTicketProvider } from "../core/src/attachment/tickets.ts";
-import { sanitizeAttachmentExtension } from "../core/src/attachment/policy.ts";
+import { sanitizeAttachmentExtension, contentTypeForAttachmentPath } from "../core/src/attachment/policy.ts";
 import { assetsDir, readVaultConfig } from "./config.ts";
 import {
   NO_PROVIDER_ERROR,
@@ -370,7 +370,7 @@ async function handleDownloadSpend(
   return new Response(fileBuffer, {
     status: 200,
     headers: {
-      "Content-Type": attachment.mimeType || "application/octet-stream",
+      "Content-Type": contentTypeForAttachmentPath(attachment.path),
       "Content-Length": String(stat.size),
       // Same defense-in-depth as the existing GET /storage/<path> byte-serve
       // (src/routes.ts) — never let a browser MIME-sniff a stored asset into

package/src/cli.ts

@@ -176,7 +176,7 @@ import {
   TRANSCRIBE_CPP_SOURCE_REF,
   type CliBuildResult,
 } from "./transcription/build.ts";
-import { downloadTo } from "./transcription/download.ts";
+import { downloadTo, ensureDownloaded } from "./transcription/download.ts";
 import {
   describeWhisperPlan,
   planWhisperInstall,
@@ -3983,11 +3983,31 @@ async function runTranscribeCppInstall(opts: {
 
     // 2) Model GGUF.
     const modelDest = join(paths.modelsDir, plan.model!.file);
-    if (existsSync(modelDest) && !force) {
-      console.log(`✓ model already present (${modelDest}) — skipping (use --force to re-download).`);
-    } else {
-      console.log(`Downloading model ${plan.model!.file} (~${plan.model!.approxSizeMb}MB) …`);
-      await downloadTo(plan.model!.url, modelDest);
+    // `ensureDownloaded` (vault#531) replaces a bare existsSync skip: when the
+    // host publishes a digest (HuggingFace does for every GGUF here) an
+    // already-present file is VERIFIED before it's trusted, so a model left
+    // corrupt by an interrupted run gets repaired instead of being skipped
+    // forever by every future non---force re-run.
+    const modelResult = await ensureDownloaded(plan.model!.url, modelDest, {
+      force,
+      onBeforeDownload: (reason) => {
+        if (reason === "corrupt") {
+          console.log(
+            `⚠  model at ${modelDest} failed its checksum — re-downloading ${plan.model!.file} …`,
+          );
+        } else {
+          console.log(`Downloading model ${plan.model!.file} (~${plan.model!.approxSizeMb}MB) …`);
+        }
+      },
+    });
+    if (modelResult.outcome === "reused") {
+      console.log(
+        modelResult.verified
+          ? `✓ model already present and checksum-verified (${modelDest}) — skipping.`
+          : `✓ model already present (${modelDest}) — skipping (use --force to re-download).`,
+      );
+    } else if (modelResult.verified) {
+      console.log(`✓ model checksum verified.`);
     }
 
     // 3) Build transcribe-cli from source against the extracted dylibs.
@@ -4283,10 +4303,18 @@ async function cmdTranscriptionStatus(): Promise<void> {
     legacy.push(`  transcribe-cpp   ${probe.ok ? "runnable" : `not runnable (${probe.reason})`}`);
   }
   if (active === "parakeet-mlx" || parakeetMlxInstalled()) {
-    legacy.push(`  parakeet-mlx     ${parakeetMlxInstalled() ? `runnable (${resolveParakeetMlxBin()})` : "not installed"}`);
+    const bin = resolveParakeetMlxBin();
+    const probe = bin ? await probeTranscribeCliRunnable(bin) : { ok: false, reason: "not installed" };
+    legacy.push(
+      `  parakeet-mlx     ${probe.ok ? `runnable (${bin})` : `not runnable (${probe.reason})`}`,
+    );
   }
   if (active === "onnx-asr" || onnxAsrInstalled()) {
-    legacy.push(`  onnx-asr         ${onnxAsrInstalled() ? `runnable (${resolveOnnxAsrBin()})` : "not installed"}`);
+    const bin = resolveOnnxAsrBin();
+    const probe = bin ? await probeTranscribeCliRunnable(bin) : { ok: false, reason: "not installed" };
+    legacy.push(
+      `  onnx-asr         ${probe.ok ? `runnable (${bin})` : `not runnable (${probe.reason})`}`,
+    );
   }
   if (legacy.length > 0) {
     console.log("\nLegacy providers (superseded by whisper-cpp):");

package/src/config.ts

@@ -61,7 +61,40 @@ import {
 // ---------------------------------------------------------------------------
 
 function configDirPath(): string {
-  return process.env.PARACHUTE_HOME ?? join(homedir(), ".parachute");
+  const fromEnv = process.env.PARACHUTE_HOME;
+  if (fromEnv) return fromEnv;
+  // Second layer of the test-isolation defense (`core/src/test-preload.ts` is
+  // the first). The preload is loaded by `bunfig.toml`, which Bun reads
+  // relative to the *cwd* — run `bun test path/to/parachute-vault/src/...`
+  // from a parent directory and the preload silently never loads, leaving
+  // every unset-PARACHUTE_HOME test writing real vaults into the developer's
+  // live install. `bun test` sets NODE_ENV=test, so the ambiguity is
+  // detectable here, at the one function that resolves the root. Deliberately
+  // narrow: only the *unset* case throws. Tests legitimately point
+  // PARACHUTE_HOME at a sandbox whose HOME is that same sandbox (init.test.ts
+  // does exactly this), so an equality check against `~/.parachute` would fire
+  // on correct code.
+  //
+  // This is reachable in SHIPPED code, not just in this repo's suite: the
+  // package ships source (`bin` points at `src/cli.ts`, no bundler) and
+  // `CONFIG_DIR` below is evaluated at module load, so an end user whose
+  // vitest/jest integration test shells out to the CLI hits it — those runners
+  // set NODE_ENV=test too. The message has to serve that reader as well as a
+  // contributor. The escape hatch needs no new env var: the guard only fires
+  // when PARACHUTE_HOME is UNSET, so setting it — to a sandbox, or to the real
+  // `~/.parachute` if that is genuinely what the test wants — is both the fix
+  // and the statement of intent.
+  if (process.env.NODE_ENV === "test") {
+    throw new Error(
+      "[parachute-vault] NODE_ENV=test and PARACHUTE_HOME is unset — refusing to default " +
+        "to the live install at ~/.parachute, because a test run that writes there creates " +
+        "real vaults in a real install. Set PARACHUTE_HOME explicitly for this process: a " +
+        "temp dir to keep the test hermetic, or ~/.parachute if you truly mean the live " +
+        "install. (Contributors to parachute-vault: running `bun test` from the repo root " +
+        "sets it for you via bunfig.toml's preload.)",
+    );
+  }
+  return join(homedir(), ".parachute");
 }
 
 function vaultHomePath(): string {

package/src/contract-honest-queries.test.ts

@@ -286,7 +286,39 @@ describe("contract: truncation-honesty warning (V1.3)", () => {
     const query = tools.find((t) => t.name === "query-notes")!;
     const result = (await query.execute({ limit: 2 })) as any;
     expect(result.warnings).toBeDefined();
-    expect(result.warnings.some((w: any) => w.code === "truncated" && w.limit === 2)).toBe(true);
+    const truncated = result.warnings.find((w: any) => w.code === "truncated" && w.limit === 2);
+    expect(truncated).toBeDefined();
+    expect(truncated.message).toContain('cursor: ""');
+    expect(truncated.message).not.toContain("?cursor=");
+  });
+
+  it("an explicit-offset page does not carry a truncated warning (vault#601)", async () => {
+    for (let i = 0; i < 3; i++) await store.createNote(`offset note ${i}`);
+    const res = await getNotes("limit=2&offset=1");
+    expect(res.status).toBe(200);
+    const body: any[] = await res.json();
+    expect(body.length).toBe(2);
+    const warnings = decodeWarningsHeader(res);
+    expect(warnings?.some((w) => w.code === "truncated") ?? false).toBe(false);
+  });
+
+  it("MCP query-notes with explicit offset does not warn (vault#601)", async () => {
+    for (let i = 0; i < 3; i++) await store.createNote(`mcp offset ${i}`);
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({ limit: 2, offset: 1 })) as any;
+    const notes = Array.isArray(result) ? result : result.notes;
+    expect(notes).toHaveLength(2);
+    expect(result.warnings?.some((w: any) => w.code === "truncated") ?? false).toBe(false);
+  });
+
+  it("REST truncated wording still names ?cursor= (vault#601)", async () => {
+    for (let i = 0; i < 3; i++) await store.createNote(`rest wording ${i}`);
+    const res = await getNotes("limit=2");
+    const warnings = decodeWarningsHeader(res);
+    const truncated = warnings!.find((w) => w.code === "truncated");
+    expect(truncated.message).toContain("?cursor=");
+    expect(truncated.message).not.toContain('cursor: ""');
   });
 });
 

package/src/contract-search.test.ts

@@ -133,6 +133,53 @@ describe("contract: search — passing (lock in current behavior)", () => {
   });
 });
 
+describe("contract: search composes with structured filters (vault#647)", () => {
+  it("REST ?search= + exclude_tag drops notes that carry the excluded tag", async () => {
+    await store.createNote("unique-647-term keep", { tags: ["keep-tag"] });
+    await store.createNote("unique-647-term drop", { tags: ["keep-tag", "drop-tag"] });
+    const res = await search("search=unique-647-term&tag=keep-tag&exclude_tag=drop-tag&include_content=true");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    const contents = body.map((n: any) => n.content);
+    expect(contents).toContain("unique-647-term keep");
+    expect(contents).not.toContain("unique-647-term drop");
+  });
+
+  it("REST ?search= + meta[created_at][gte] drops notes below the date floor", async () => {
+    // REST removed the flat date_from param at 0.6.4; the live date grammar
+    // is bracket-style. Same composition hole as MCP date_from.
+    await store.createNote("unique-647-date recent", {
+      tags: ["keep-tag"],
+      created_at: "2026-07-01T00:00:00.000Z",
+    });
+    await store.createNote("unique-647-date old", {
+      tags: ["keep-tag"],
+      created_at: "2023-06-01T00:00:00.000Z",
+    });
+    const res = await search(
+      "search=unique-647-date&tag=keep-tag&meta[created_at][gte]=2026-06-01&include_content=true",
+    );
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    const contents = body.map((n: any) => n.content);
+    expect(contents).toContain("unique-647-date recent");
+    expect(contents).not.toContain("unique-647-date old");
+  });
+
+  it("REST ?search= + exclude_path_prefix drops matching paths (vault#628)", async () => {
+    await store.createNote("unique-628-search-term keep", { path: "Projects/a" });
+    await store.createNote("unique-628-search-term drop", { path: ".parachute/notes/settings" });
+    const res = await search(
+      "search=unique-628-search-term&exclude_path_prefix=.parachute/&include_content=true",
+    );
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    const contents = body.map((n: any) => n.content);
+    expect(contents).toContain("unique-628-search-term keep");
+    expect(contents).not.toContain("unique-628-search-term drop");
+  });
+});
+
 describe('contract: search — literal-by-default (#551, flipped from todo)', () => {
   it(`unquoted search "didn't" finds the contraction content (literal-by-default — the bare apostrophe used to split into two AND'd tokens and return [])`, async () => {
     const res = await search(`search=${encodeURIComponent("didn't")}&include_content=true`);

package/src/embedding/select.ts

@@ -14,8 +14,11 @@
  *     bearer token, when the endpoint needs one.
  *   - **Bundled floor** (`onnx-transformers.ts`): no env at all → the
  *     zero-config default, `bge-small-en-v1.5` (q8 ONNX) running
- *     in-process. This is what makes semantic search work on a fresh
- *     install with no operator action.
+ *     in-process. This is what makes semantic search work with no
+ *     provider configuration — but note it is still gated by the opt-in
+ *     switch below, so "no env at all" now means NO provider, not the
+ *     bundled one. Pre-0.7.3 this tier made the feature work on a fresh
+ *     install with no operator action at all; that is no longer true.
  *
  * **Opt-in gate (0.7.3, Aaron-ratified):** semantic search is OFF by
  * default. `buildEmbeddingProvider` returns a provider ONLY when the
@@ -25,7 +28,17 @@
  *
  *   1. **`EMBEDDINGS_ENABLED` env var** — the low-level override. `true`/`1`
  *      forces ON, `false`/`0` forces OFF, anything else (incl. unset)
- *      defers to the persisted setting. Mirrors the cloud wrangler var.
+ *      defers to the persisted setting.
+ *
+ *      NOTE: this is **tri-state** (on / off / defer), not the plain
+ *      off-switch it used to be — before 0.7.3 the feature was on unless
+ *      this var turned it off, so an UNSET var meant ON; now an unset var
+ *      means "defer", and the persisted setting defaults OFF. Anything
+ *      that consumes this selector and relies on the old
+ *      unset-means-enabled reading will silently come up with semantic
+ *      search DISABLED. If the cloud worker shares this selector, set its
+ *      embeddings default EXPLICITLY rather than leaving it to this
+ *      default-off (vault#623).
  *   2. **Persisted `embeddings_enabled`** (config.yaml, wired in by the
  *      caller — see `getSharedEmbeddingProvider`) — the self-host settings
  *      toggle, so an operator can turn semantic search on without editing

package/src/live-match.test.ts

@@ -122,6 +122,14 @@ describe("live-match — predicate parity with the query engine", () => {
     expect(ids.size).toBe(2);
   });
 
+  it("excludePathPrefix (vault#628)", async () => {
+    await store.createNote("user", { path: "Projects/a" });
+    await store.createNote("sys", { path: ".parachute/notes/settings" });
+    await store.createNote("bare");
+    const ids = await assertParity({ excludePathPrefix: [".parachute/"] });
+    expect(ids.size).toBe(2);
+  });
+
   it("hasTags true/false (M1 — presence parity)", async () => {
     await store.createNote("tagged", { tags: ["x"] });
     await store.createNote("bare", {});

package/src/live-match.ts

@@ -21,6 +21,8 @@
  *   - `excludeTags` — raw exact-name match (engine does NOT expand excludes).
  *   - `path` — case-insensitive exact (engine: `n.path = ? COLLATE NOCASE`).
  *   - `pathPrefix` — prefix (engine: `n.path LIKE prefix || '%'`).
+ *   - `excludePathPrefix` — NOT those prefixes (engine: `n.path IS NULL OR
+ *     n.path NOT LIKE prefix || '%'`). Repeatable. vault#628.
  *   - `extension` — lower-cased, default "md" (engine: `LOWER(n.extension)`),
  *     a note with no extension is treated as "md".
  *   - `metadata` operator objects (eq/ne/gt/gte/lt/lte/in/not_in/exists) +
@@ -283,6 +285,19 @@ function matchAgainst(
     if (!note.path || !note.path.toLowerCase().startsWith(opts.pathPrefix.toLowerCase())) return false;
   }
 
+  // ---- excludePathPrefix (vault#628) — same CI prefix match as pathPrefix;
+  // a note with no path is not under the prefix, so it stays.
+  if (opts.excludePathPrefix && opts.excludePathPrefix.length > 0) {
+    const p = note.path;
+    if (p) {
+      const lower = p.toLowerCase();
+      for (const prefix of opts.excludePathPrefix) {
+        if (typeof prefix !== "string" || prefix.length === 0) continue;
+        if (lower.startsWith(prefix.toLowerCase())) return false;
+      }
+    }
+  }
+
   // ---- extension (lower-cased; default "md") ----
   if (opts.extension !== undefined) {
     const exts = Array.isArray(opts.extension) ? opts.extension : [opts.extension];

package/src/mcp-http.test.ts

@@ -128,6 +128,18 @@ describe("handleMcp JSON-RPC error mapping — end to end (vault#555 fix 6)", ()
     expect(body.error.data.field).toBe("limit");
   });
 
+  test("invalid_query forwards how_to (vault#617 bun/cloud symmetry)", async () => {
+    const body = await callBoom(() => {
+      throw Object.assign(new Error("size_bytes must be a positive number"), {
+        error_type: "invalid_query",
+        field: "size_bytes",
+        how_to: "pass the exact byte length of the file you're about to upload",
+      });
+    });
+    expect(body.error.data.error_type).toBe("invalid_query");
+    expect(body.error.data.how_to).toBe("pass the exact byte length of the file you're about to upload");
+  });
+
   test("a truly unknown error (no error_type anywhere) falls through to the unstructured isError text, not a thrown McpError", async () => {
     const body = await callBoom(() => {
       throw new Error("plain unstructured failure");

package/src/mcp-http.ts

@@ -258,6 +258,7 @@ export async function handleMcp(
           field: e.field,
           got: e.got,
           hint: e.hint,
+          ...(e.how_to !== undefined ? { how_to: e.how_to } : {}),
         });
       }
       // Advanced-mode full-text search syntax error (vault#551) — a

package/src/mcp-tools.ts

@@ -23,6 +23,7 @@ import {
   filterHydratedLinksByTagScope,
   noteWithinTagScope,
   scrubIndexedFieldConflictError,
+  scrubNoteTagsByScope,
   scrubParentCycleError,
   scrubReferencingTagsByScope,
   scrubTagFieldViolationsByScope,
@@ -398,33 +399,57 @@ function applyTagScopeWrappers(
   };
   const rawTags = auth.scoped_tags;
 
-  // Scrub a returned note's hydrated `links` array (present when the caller
-  // set `include_links`) so out-of-scope NEIGHBOR summaries (id/path/tags)
-  // don't leak — symmetric with the REST `include_links` fix. Mutates in
-  // place and returns the note for chaining. No-op when `links` is absent.
+  // Apply every scope scrub a returned note needs, in one place:
+  //
+  //  1. hydrated `links` (present when the caller set `include_links`) — drop
+  //     out-of-scope NEIGHBOR summaries (id/path/tags) and scrub the
+  //     surviving summaries' own `.tags`; symmetric with REST.
+  //  2. `validation_status` (vault#555 auth review) — a note the caller can
+  //     see may ALSO carry an out-of-scope co-tag whose schema would
+  //     otherwise leak (field name / type / enum values, the #560 class).
+  //  3. the note's OWN `.tags` array (vault#568) — being admitted via one
+  //     in-scope tag must not disclose the NAMES of its out-of-scope
+  //     co-tags. This is the same leak class as (2) through a plainer field.
+  //
+  // (1) and (2) mutate in place; (3) is non-mutating and may return a NEW
+  // object, so callers must use the RETURN VALUE, never rely on the mutation.
   //
   // Ordering invariant: reading `allowedHolder.value` here is safe ONLY
-  // because every wrapper that calls scrubNoteLinks first does
+  // because every wrapper that calls scrubNoteForScope first does
   // `await getAllowed()` (which populates the holder) before `orig(params)`
   // and before this scrub runs. So by the time we read `holder.value` it is
   // the resolved allowlist, never the initial `null`. The `?? null` fallback
   // is the unscoped/holder-absent path; `filterHydratedLinksByTagScope` then
   // keys off `rawTags` (non-null here) for the actual scope check.
-  const scrubNoteLinks = (n: any): any => {
+  const scrubNoteForScope = (n: any): any => {
     if (n && Array.isArray(n.links)) {
       n.links = filterHydratedLinksByTagScope(n.links, allowedHolder?.value ?? null, rawTags);
     }
-    // vault#555 auth review — a note the caller can see may ALSO carry an
-    // out-of-scope co-tag whose schema `validation_status` would otherwise
-    // leak (field name / type / enum values, the #560 class). Scrub it with
-    // the same allowlist the link scrub uses. Reads the resolved holder for
-    // the same reason (see the ordering-invariant note above scrubNoteLinks).
     if (n && n.validation_status) {
       const scrubbed = scrubValidationStatusByScope(n.validation_status, allowedHolder?.value ?? null, rawTags);
       if (scrubbed === undefined) delete n.validation_status;
       else n.validation_status = scrubbed;
     }
-    return n;
+    return scrubNoteTagsByScope(n, allowedHolder?.value ?? null, rawTags);
+  };
+
+  /**
+   * Shape dispatcher for the WRITE tools (vault#568). `create-note` and
+   * `update-note` echo the stored note, so they leak exactly what the read
+   * paths leak — and a no-op `update-note` would otherwise be a one-call
+   * bypass of the read-path scrub. Their result is a single note, a `notes`
+   * array (batch), or a `{created, ids, failed}` batch summary (no note
+   * bodies → nothing to scrub). Errors (`{error, error_type}`) pass through.
+   */
+  const scrubWriteResult = (result: any): any => {
+    if (!result || typeof result !== "object") return result;
+    if (Array.isArray(result)) return result.map(scrubNoteForScope);
+    if ("error" in result) return result;
+    if (Array.isArray((result as any).notes)) {
+      return { ...result, notes: (result as any).notes.map(scrubNoteForScope) };
+    }
+    if ("id" in result && "tags" in result) return scrubNoteForScope(result);
+    return result;
   };
 
   wrapReadTool(tools, "query-notes", async (orig, params) => {
@@ -463,7 +488,7 @@ function applyTagScopeWrappers(
     if (Array.isArray(result)) {
       return result
         .filter((n: any) => noteWithinTagScope(n, allowed, rawTags))
-        .map(scrubNoteLinks);
+        .map(scrubNoteForScope);
     }
     if (
       result &&
@@ -475,7 +500,7 @@ function applyTagScopeWrappers(
       return {
         notes: r.notes
           .filter((n: any) => noteWithinTagScope(n, allowed, rawTags))
-          .map(scrubNoteLinks),
+          .map(scrubNoteForScope),
         ...("next_cursor" in r ? { next_cursor: r.next_cursor } : {}),
         // `warnings` intentionally DROPPED for a tag-scoped session: core's
         // `collectUnknownTagWarnings` (core/src/query-warnings.ts) resolves
@@ -489,7 +514,7 @@ function applyTagScopeWrappers(
     }
     if (result && typeof result === "object" && "id" in result && "tags" in result) {
       return noteWithinTagScope(result as any, allowed, rawTags)
-        ? scrubNoteLinks(result)
+        ? scrubNoteForScope(result)
         : { error: "Note not found", error_type: "not_found", id: (result as any).id };
     }
     return result;
@@ -623,7 +648,10 @@ function applyTagScopeWrappers(
     // both the proactive site and the race-backstop site with one guard. The
     // `await getAllowed()` at the top of this wrapper populates the shared
     // `allowedHolder` the predicate reads, before core's execute runs.
-    return await orig(params);
+    // vault#568 — scrub the echoed note(s): under `if_exists: ignore|update|
+    // replace` the response is a PRE-EXISTING note whose co-tags this caller
+    // never supplied and must not learn.
+    return scrubWriteResult(await orig(params));
   });
 
   wrapReadTool(tools, "update-note", async (orig, params) => {
@@ -646,7 +674,13 @@ function applyTagScopeWrappers(
         return forbidden("update-note: post-update tag set must satisfy the token's allowlist");
       }
     }
-    return await orig(params);
+    // vault#568 — scrub the echoed note(s). Without this a no-op update-note
+    // is a one-call bypass of the read-path `.tags` scrub. Also closes two
+    // pre-existing parity gaps on this tool: the echoed hydrated `links`
+    // (REST's PATCH already scrubbed them at the `filterHydratedLinksByTagScope`
+    // call; MCP did not) and `validation_status` (#555 wired the scrub to the
+    // read paths only).
+    return scrubWriteResult(await orig(params));
   });
 
   wrapReadTool(tools, "delete-note", async (orig, params) => {

package/src/mirror-routes.test.ts

@@ -395,22 +395,20 @@ describe("handleMirrorPut", () => {
     await manager.stop();
   });
 
-  test("two PUTs fired in quick succession both apply; manager ends in the second config's state", async () => {
-    // Reviewer concern: a second PUT entering `reload()` while the
-    // first PUT's `stop()` is still inside its 250ms in-flight settle
-    // window could theoretically race the `stopping` flag. JS's
-    // microtask-serialized awaits make this safe in practice — each
-    // PUT's reload→start chain runs to completion on its own tick
-    // before the next runs — but pinning the expected outcome with a
-    // test documents the behavior + catches a regression if the
-    // serialization ever relaxes.
+  test("two PUTs in succession both apply; manager ends in the second config's state", async () => {
+    // vault#558: the previous Promise.all pairing raced. `reload()` is
+    // async (stop's 250ms in-flight settle + start), so the two PUTs
+    // could finish in either order and the last-writer-wins assertion
+    // on safety_net_seconds: 120 flaked. The issue is the assertion,
+    // not a product bug as observed — serialize the second PUT behind
+    // the first's completion so last-writer-wins is deterministic.
     //
     // What we assert:
     //   - Both PUTs return 200 (no crash, no stuck-in-flight).
     //   - After both resolve, the manager is in the SECOND config's
     //     shape (last-writer-wins; not a stale first-config state
     //     leaking through).
-    home = tmp("mirror-put-concurrent-");
+    home = tmp("mirror-put-succession-");
     const { manager } = makeManager(home);
     const put = (body: Record<string, unknown>) =>
       handleMirrorPut(
@@ -420,29 +418,22 @@ describe("handleMirrorPut", () => {
         }),
         manager,
       );
-    const [res1, res2] = await Promise.all([
-      put({
-        enabled: true,
-        location: "internal",
-        sync_mode: "events",
-        auto_commit: false,
-        safety_net_seconds: 60,
-      }),
-      put({
-        enabled: true,
-        location: "internal",
-        sync_mode: "events",
-        auto_commit: false,
-        safety_net_seconds: 120,
-      }),
-    ]);
+    const res1 = await put({
+      enabled: true,
+      location: "internal",
+      sync_mode: "events",
+      auto_commit: false,
+      safety_net_seconds: 60,
+    });
+    const res2 = await put({
+      enabled: true,
+      location: "internal",
+      sync_mode: "events",
+      auto_commit: false,
+      safety_net_seconds: 120,
+    });
     expect(res1.status).toBe(200);
     expect(res2.status).toBe(200);
-    // Both PUTs read the same config-storage seam (deps.writeMirrorConfig)
-    // and serialize through the manager's async start() under the
-    // microtask queue. Final config reflects whichever PUT entered
-    // `reload()` last — practically the second one — but the salient
-    // assertion is "the manager isn't stuck": enabled + watch_running.
     const status = manager.getStatus();
     expect(status.enabled).toBe(true);
     expect(status.watch_running).toBe(true);

package/src/onboarding-seed.test.ts

@@ -36,6 +36,7 @@ import {
   welcomePack,
   YOURS_TO_KEEP_PATH,
 } from "../core/src/seed-packs.ts";
+import { PathConflictError } from "../core/src/notes.ts";
 import {
   buildVaultProjection,
   projectionToMarkdown,
@@ -293,6 +294,73 @@ describe("applySeedPack — surface-starter via add-pack", () => {
   });
 });
 
+describe("applySeedPack — concurrent-apply skip grace (vault#527)", () => {
+  /**
+   * The applier's idempotency is check-then-create: `getNoteByPath` decides,
+   * then `createNote` writes. Two callers applying the same pack at once can
+   * BOTH see "absent" and both try to create; the loser hits the path UNIQUE
+   * constraint. That race can't be scheduled deterministically from a test,
+   * so we inject it — a store proxy whose `getNoteByPath` reports absent (as
+   * it genuinely would for the racer that checked first) while `createNote`
+   * rejects with the PathConflictError the real store raises when the winner
+   * has already committed. That is exactly the state the loser observes.
+   */
+  function racingStore(target: BunStore, racedPaths: Set<string>) {
+    return new Proxy(target, {
+      get(obj, prop, recv) {
+        if (prop === "createNote") {
+          return async (content: string, opts: { path?: string } = {}) => {
+            if (opts.path && racedPaths.has(opts.path)) {
+              throw new PathConflictError(opts.path);
+            }
+            return (obj as BunStore).createNote(content, opts as never);
+          };
+        }
+        return Reflect.get(obj, prop, recv);
+      },
+    }) as BunStore;
+  }
+
+  test("a path lost to a concurrent creator is reported skipped, not thrown", async () => {
+    const raced = new Set(SURFACE_STARTER_PACK.notes.map((n) => n.path));
+    const proxied = racingStore(store, raced);
+
+    const result = await applySeedPack(proxied, SURFACE_STARTER_PACK);
+
+    expect(result.seededNotes).toEqual([]);
+    expect(result.skippedNotes).toEqual(SURFACE_STARTER_PACK.notes.map((n) => n.path));
+  });
+
+  test("losing one path does not abort the rest of the pack", async () => {
+    // welcomePack is multi-note, so this proves the loop CONTINUES past a
+    // lost race rather than aborting the whole pack on the first conflict.
+    const pack = welcomePack();
+    const [first, ...rest] = pack.notes;
+    expect(rest.length).toBeGreaterThan(0);
+    const proxied = racingStore(store, new Set([first!.path]));
+
+    const result = await applySeedPack(proxied, pack);
+
+    expect(result.skippedNotes).toContain(first!.path);
+    for (const n of rest) expect(result.seededNotes).toContain(n.path);
+  });
+
+  test("a PathConflictError is the ONLY create failure swallowed — others still propagate", async () => {
+    const boom = new Proxy(store, {
+      get(obj, prop, recv) {
+        if (prop === "createNote") {
+          return async () => {
+            throw new Error("disk on fire");
+          };
+        }
+        return Reflect.get(obj, prop, recv);
+      },
+    }) as BunStore;
+
+    expect(applySeedPack(boom, SURFACE_STARTER_PACK)).rejects.toThrow(/disk on fire/);
+  });
+});
+
 describe("applySeedPack — tag description preservation on re-apply (Aaron-ratified 2026-07-17)", () => {
   test("fresh apply: a brand-new tag gets the pack's description, reported as touched not preserved", async () => {
     const result = await applySeedPack(store, STARTER_ONTOLOGY_PACK);