@openparachute/vault 0.7.3-rc.9 → 0.7.3

package/src/transcription-worker.ts

@@ -64,41 +64,57 @@ import {
 } from "../core/src/transcription/provider.ts";
 import { ScribeHttpProvider } from "./transcription/providers/scribe-http.ts";
 
-/** Placeholder pattern written by the voice-memo capture stub. */
-const TRANSCRIPT_PLACEHOLDER = /_Transcript pending\._/;
-
 /**
- * Body written when transcription reaches a terminal failure (maxAttempts
- * exhausted, or the audio file is missing). This used to be written by
- * Lens's now-removed scribe client; owning it here means a failed upload
- * stops reading "Transcript pending" forever regardless of which client
- * uploaded the audio.
+ * The in-body transcription markers.
+ *
+ * The BARE markers are the un-segmented default; voice W2 (segmented
+ * recordings) targets per-part variants built by `markersFor`. Both are a
+ * BYTE-EXACT cross-door + cross-repo contract — the cloud Workers-AI
+ * transcription path ships the identical strings, and the notes-ui status
+ * chip (parachute-surface TranscriptionStatus.tsx) keys off the failure
+ * marker's exact copy. Don't change any of this text without a coordinated
+ * change in both places. A friendlier "retry available" copy + chip
+ * affordance is a tracked parachute-surface follow-up.
  *
- * NOTE: the notes-ui status chip (parachute-surface TranscriptionStatus.tsx)
- * keys off this exact string, so don't change the copy without a coordinated
- * change there. A friendlier "retry available" copy + chip affordance is a
- * tracked parachute-surface follow-up.
+ * Owning the failure marker here (it used to be written by Lens's now-removed
+ * scribe client) means a failed upload stops reading "Transcript pending"
+ * forever regardless of which client uploaded the audio.
  */
-const TRANSCRIPT_UNAVAILABLE = "_Transcription unavailable._";
+const BARE_PENDING = "_Transcript pending._";
+const BARE_UNAVAILABLE = "_Transcription unavailable._";
+
+/** Escape a literal string for safe embedding in a `RegExp`. */
+function escapeRegExp(literal: string): string {
+  return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 
 /**
- * On a successful (re)transcription of a legacy in-body memo, the transcript
- * replaces whichever marker is currently in the body — the original
- * `_Transcript pending._` on a first-try success, OR `_Transcription
- * unavailable._` if a prior attempt failed and we're now retrying. Matching
- * both means a retried success lands in the same spot a first-try success
- * would, preserving the surrounding capture body (the `![[memo]]` embed,
- * the `_Recorded …_` line, the header).
- *
- * Deliberately NO `/g` flag — `.replace` swaps only the FIRST match. A
- * canonical capture body holds exactly one marker, so first-match is the
- * correct target. `applyFailureMarker`'s includes-guard (no-op when the
- * marker is already present) prevents markers accumulating across repeated
- * terminal failures, so the body never carries two of the same marker. A
- * hand-edited body that somehow contains both markers patches only the
- * first — accepted (degenerate, operator-induced).
+ * The pending + terminal-failure markers for an attachment, honoring
+ * `segment_index` (voice W2 — segmented recordings). `undefined` yields the
+ * bare markers (fully backward compatible — un-segmented flows are byte-
+ * unchanged). An integer ≥ 0 yields this part's markers, with the human-
+ * facing part number N = segment_index + 1 (1-based, decimal):
+ *   `_Transcript pending (part N)._` / `_Transcription unavailable (part N)._`
  */
-const TRANSCRIPT_SUCCESS_TARGET = /_Transcript pending\._|_Transcription unavailable\._/;
+function markersFor(segmentIndex: number | undefined): { pending: string; unavailable: string } {
+  if (segmentIndex === undefined) return { pending: BARE_PENDING, unavailable: BARE_UNAVAILABLE };
+  const n = segmentIndex + 1;
+  return {
+    pending: `_Transcript pending (part ${n})._`,
+    unavailable: `_Transcription unavailable (part ${n})._`,
+  };
+}
+
+/**
+ * A valid segment index (integer ≥ 0) off attachment metadata, else
+ * `undefined` — the un-segmented path. Client-set at link time; anything that
+ * isn't a non-negative integer falls back to the bare markers rather than
+ * fabricating a `(part N)`.
+ */
+function segmentIndexOf(meta: { segment_index?: unknown }): number | undefined {
+  const raw = meta.segment_index;
+  return typeof raw === "number" && Number.isInteger(raw) && raw >= 0 ? raw : undefined;
+}
 
 /**
  * Default sweep cadence (ms). The sweep is the safety net for backoff-
@@ -195,6 +211,14 @@ interface PendingMeta {
    * worker preserves the original stub-patching behavior (Lens flow).
    */
   transcribe_origin?: "auto" | "legacy";
+  /**
+   * Voice W2 (segmented recordings): a client-set 0-based index marking this
+   * attachment as one segment of a longer recording sliced into ~10-min parts,
+   * all linked on ONE note. When present, the legacy in-body path targets this
+   * part's markers (`… (part N)._`, N = segment_index + 1) rather than the bare
+   * ones — making per-part ordering structurally guaranteed. See `markersFor`.
+   */
+  segment_index?: number;
   [k: string]: unknown;
 }
 
@@ -357,17 +381,28 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
    * attachment failure we're trying to record.
    *
    * Body policy (finding F — never destroy content):
-   *   - Placeholder PRESENT → surgical replace of `_Transcript pending._`
-   *     with the marker. The `![[memo]]` embed + any surrounding text survive.
-   *   - Marker ALREADY PRESENT → no-op (idempotent; a double-terminal-failure
-   *     must not stack markers).
-   *   - Otherwise (placeholder absent — the user edited the note while it was
-   *     pending) → APPEND `\n\n` + marker to the existing content. The old
-   *     code full-replaced the body here, destroying the embed AND the user's
-   *     edits. We append instead so nothing is lost. If the content is empty,
-   *     the marker alone becomes the body (avoids a leading blank line).
+   *   - Pending marker PRESENT → surgical replace of the pending marker with
+   *     the failure marker. The `![[memo]]` embed + any surrounding text
+   *     survive. For a segmented attachment (`segment_index` set) this is the
+   *     per-part `_Transcript pending (part N)._`; otherwise the bare marker.
+   *   - Failure marker ALREADY PRESENT → no-op (idempotent; a double-terminal-
+   *     failure must not stack markers).
+   *   - Otherwise (pending marker absent — the user edited the note while it
+   *     was pending) → APPEND `\n\n` + failure marker to the existing content.
+   *     The old code full-replaced the body here, destroying the embed AND the
+   *     user's edits. We append instead so nothing is lost. If the content is
+   *     empty, the marker alone becomes the body (avoids a leading blank line).
    */
-  async function applyFailureMarker(store: Store, noteId: string): Promise<void> {
+  async function applyFailureMarker(
+    store: Store,
+    noteId: string,
+    segmentIndex: number | undefined,
+  ): Promise<void> {
+    // Bare markers by default; this segment's `(part N)` markers when the
+    // attachment carries a `segment_index` (voice W2). String-search replace
+    // targets the FIRST occurrence (a canonical body holds exactly one), and
+    // the includes-guard below keeps a repeated terminal failure from stacking.
+    const { pending, unavailable } = markersFor(segmentIndex);
     // OC-guarded (vault#435): the read-transform-write below is re-run against
     // fresh content on a conflict so a concurrent user edit isn't clobbered.
     // The transform is pure w.r.t. the note it's handed; the stub-set and
@@ -381,17 +416,24 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
         if (noteMeta.transcribe_stub !== true) return null;
 
         let body: string;
-        if (TRANSCRIPT_PLACEHOLDER.test(note.content)) {
-          body = note.content.replace(TRANSCRIPT_PLACEHOLDER, TRANSCRIPT_UNAVAILABLE);
-        } else if (note.content.includes(TRANSCRIPT_UNAVAILABLE)) {
+        if (note.content.includes(pending)) {
+          // Function replacer so the search string is treated literally and the
+          // (fixed) failure marker is inserted verbatim.
+          body = note.content.replace(pending, () => unavailable);
+        } else if (note.content.includes(unavailable)) {
           // Marker already present — nothing to do. Clear the stub and
           // return without rewriting the body so we don't stack markers.
           body = note.content;
         } else {
           body = note.content.length > 0
-            ? `${note.content}\n\n${TRANSCRIPT_UNAVAILABLE}`
-            : TRANSCRIPT_UNAVAILABLE;
+            ? `${note.content}\n\n${unavailable}`
+            : unavailable;
         }
+        // Segmented: the stub is SHARED across this note's parts — keep it set
+        // so sibling parts still resolve their own slots. Return content only
+        // (leave note metadata untouched). Un-segmented: clear the one-shot
+        // stub as before (byte-unchanged).
+        if (segmentIndex !== undefined) return { content: body };
         const { transcribe_stub: _drop, ...restMeta } = noteMeta;
         return { content: body, metadata: restMeta };
       },
@@ -449,6 +491,12 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
     // vs. the legacy stub-patching path (Lens flow). Auto-write notes also
     // surface failures so the user can retry from the transcript note.
     const isAutoOrigin = meta.transcribe_origin === "auto";
+    // Voice W2: when this attachment is one segment of a longer recording
+    // (client-set `segment_index`), the legacy in-body path targets this
+    // part's markers instead of the bare ones. Undefined for un-segmented
+    // attachments — byte-unchanged behavior. Only the legacy path consults it;
+    // the auto/transcript-note path is untouched (segments are a memo concern).
+    const segmentIndex = segmentIndexOf(meta);
 
     // Honor backoff — we re-check here in case another tick queued this
     // attachment between the listing and now.
@@ -469,7 +517,7 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
       if (isAutoOrigin) {
         await writeFailureTranscriptNote(store, attachment, "audio file not found", undefined, undefined);
       } else {
-        await applyFailureMarker(store, attachment.noteId);
+        await applyFailureMarker(store, attachment.noteId, segmentIndex);
       }
       return;
     }
@@ -527,7 +575,7 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
         if (isAutoOrigin) {
           await writeFailureTranscriptNote(store, attachment, errMsg, apiErr?.code, undefined);
         } else {
-          await applyFailureMarker(store, attachment.noteId);
+          await applyFailureMarker(store, attachment.noteId, segmentIndex);
         }
         // retention=never drops the audio on any terminal state, including
         // failure. The user opted in to "I don't want the audio kept around
@@ -578,6 +626,16 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
       // before the transcript arrives opts out of the overwrite. OC-guarded
       // (vault#435): re-applied against fresh content on a conflict so a
       // concurrent user edit isn't clobbered.
+      //
+      // Success replaces whichever of THIS part's markers is present (bare, or
+      // `(part N)` when segmented). Built with no `/g` flag so `.replace`
+      // swaps only the FIRST match — a canonical capture body holds exactly
+      // one marker per part; alternation preserves positional-first semantics
+      // (a retried success replaces the failure marker where a first-try
+      // success replaced the pending one) so byte-for-byte matching today's
+      // un-segmented behavior.
+      const { pending, unavailable } = markersFor(segmentIndex);
+      const successTarget = new RegExp(`${escapeRegExp(pending)}|${escapeRegExp(unavailable)}`);
       await applyNoteTransformWithOC(
         store,
         attachment.noteId,
@@ -586,28 +644,31 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
           const noteMeta = (note.metadata as Record<string, unknown> | undefined) ?? {};
           if (noteMeta.transcribe_stub !== true) return null;
           // Body policy (finding F — never destroy content):
-          //   - placeholder OR failure-marker present → surgical replace in
-          //     place (a retried success replaces the `_Transcription
-          //     unavailable._` marker, landing exactly where a first-try
-          //     success would). The embed + surrounding capture body survive.
+          //   - pending OR failure marker present → surgical replace in place.
+          //     The embed + surrounding capture body survive.
           //   - neither present (user edited the note while pending) → APPEND
           //     the transcript instead of full-replacing the body, so the
           //     user's edits + the `![[memo]]` embed are preserved. The old
           //     code full-replaced here, which destroyed both.
           let body: string;
-          if (TRANSCRIPT_SUCCESS_TARGET.test(note.content)) {
+          if (successTarget.test(note.content)) {
             // Function replacer, NOT a string — speech-to-text is arbitrary
             // user content, and String.replace treats `$&`, `$\``, `$'`,
             // `$1`-`$9` as special patterns in a string replacement. A
             // transcript containing `$&` would otherwise inject the matched
             // marker text into the body. `() => transcript` returns the text
             // verbatim.
-            body = note.content.replace(TRANSCRIPT_SUCCESS_TARGET, () => transcript);
+            body = note.content.replace(successTarget, () => transcript);
           } else {
             body = note.content.length > 0
               ? `${note.content}\n\n${transcript}`
               : transcript;
           }
+          // Segmented: the stub is SHARED across this note's parts — keep it
+          // set so sibling parts still resolve their own slots. Return content
+          // only (leave note metadata untouched). Un-segmented: clear the
+          // one-shot stub as before (byte-unchanged).
+          if (segmentIndex !== undefined) return { content: body };
           const { transcribe_stub: _drop, ...restMeta } = noteMeta;
           return { content: body, metadata: restMeta };
         },

package/src/vault-embeddings-capability.test.ts

@@ -6,20 +6,28 @@
  */
 import { describe, test, expect, beforeEach, afterEach } from "bun:test";
 import { Database } from "bun:sqlite";
-import { BunStore } from "./vault-store.ts";
+import { BunStore, resetSharedEmbeddingProviderForTests } from "./vault-store.ts";
 import { handleVault } from "./routes.ts";
 import type { EmbeddingCapability } from "./embedding/capability.ts";
 
 let db: Database;
 let store: BunStore;
+let prevEnabled: string | undefined;
 
 beforeEach(() => {
   db = new Database(":memory:");
   store = new BunStore(db);
+  // The production-default tests below exercise the memoized shared provider;
+  // reset it + control the opt-in env so the default resolves deterministically.
+  prevEnabled = process.env.EMBEDDINGS_ENABLED;
+  resetSharedEmbeddingProviderForTests();
 });
 
 afterEach(() => {
   db.close();
+  if (prevEnabled === undefined) delete process.env.EMBEDDINGS_ENABLED;
+  else process.env.EMBEDDINGS_ENABLED = prevEnabled;
+  resetSharedEmbeddingProviderForTests();
 });
 
 const BASE = "http://localhost/api";
@@ -66,13 +74,27 @@ describe("GET /api/vault embeddings capability", () => {
     expect(body.embeddings).toEqual({ enabled: false });
   });
 
-  test("the production default resolves the shared embedding provider (zero-config -> the bundled floor, enabled:true)", async () => {
+  test("the production DEFAULT is off (opt-in, 0.7.3) — no provider, enabled:false", async () => {
+    delete process.env.EMBEDDINGS_ENABLED;
+    resetSharedEmbeddingProviderForTests();
     const cfg = { name: "default" };
     // No resolver override — exercises the real default wiring
-    // (getSharedEmbeddingProvider() -> resolveEmbeddingCapability()).
-    // Zero-config env -> the bundled onnx-transformers floor, which is
-    // optimistically available() before any real model load — see
-    // src/embedding/onnx-transformers.ts's "lazy-fail, not crash" doc.
+    // (getSharedEmbeddingProvider() -> resolveEmbeddingCapability()). Semantic
+    // search is opt-in as of 0.7.3, so with nothing enabling it the shared
+    // provider is undefined and the capability advertises disabled.
+    const res = await handleVault(new Request(`${BASE}/vault`, { method: "GET" }), store, cfg as any);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as any;
+    expect(body.embeddings).toEqual({ enabled: false });
+  });
+
+  test("once ENABLED (EMBEDDINGS_ENABLED=true) the default wiring resolves the bundled floor, enabled:true", async () => {
+    process.env.EMBEDDINGS_ENABLED = "true";
+    resetSharedEmbeddingProviderForTests();
+    const cfg = { name: "default" };
+    // The bundled onnx-transformers floor is optimistically available() before
+    // any real model load — see src/embedding/onnx-transformers.ts's
+    // "lazy-fail, not crash" doc.
     const res = await handleVault(new Request(`${BASE}/vault`, { method: "GET" }), store, cfg as any);
     expect(res.status).toBe(200);
     const body = (await res.json()) as any;

package/src/vault-store-embedding-wiring.test.ts

@@ -1,12 +1,12 @@
 /**
- * End-to-end wiring test for the `EMBEDDINGS_ENABLED=false` off switch's
- * error hint (review nano flag on #602): `getVaultStore` should thread
- * "explicitly disabled" through to `Store.semanticSearch`'s
- * `semantic_unavailable` hint, not the generic provider-setup message —
- * see `core/src/store.ts`'s `embeddingDisabledReason` doc comment for why
- * core can't determine this on its own. Unit coverage for the underlying
- * `Store` behavior lives in `core/src/store.semantic-search.test.ts`; this
- * file exercises the REAL `src/vault-store.ts` call site.
+ * End-to-end wiring test for the semantic-search opt-in gate (0.7.3) at the
+ * REAL `src/vault-store.ts` call site. Semantic search is OFF by default;
+ * when off, `getVaultStore` builds NO provider and threads the opt-in hint
+ * through to `Store.semanticSearch`'s `semantic_unavailable` error — not the
+ * generic provider-setup message — see `core/src/store.ts`'s
+ * `embeddingDisabledReason` doc comment for why core can't determine this on
+ * its own. Unit coverage for the underlying `Store` behavior lives in
+ * `core/src/store.semantic-search.test.ts`.
  */
 import { describe, test, expect, beforeEach, afterEach } from "bun:test";
 import { mkdirSync, rmSync } from "fs";
@@ -17,6 +17,7 @@ import {
   getVaultStore,
   clearVaultStoreCache,
   resetSharedEmbeddingProviderForTests,
+  EMBEDDINGS_DISABLED_REASON,
 } from "./vault-store.ts";
 
 let tmpHome: string;
@@ -43,11 +44,12 @@ afterEach(() => {
   rmSync(tmpHome, { recursive: true, force: true });
 });
 
-describe("getVaultStore — EMBEDDINGS_ENABLED=false hint wiring", () => {
-  test("store.embeddingDisabledReason is set, and semanticSearch's hint names the off switch", async () => {
-    process.env.EMBEDDINGS_ENABLED = "false";
+describe("getVaultStore — semantic-search opt-in gate wiring", () => {
+  test("DEFAULT off (env unset, no persisted setting): no provider, and semanticSearch's hint names the opt-in toggle", async () => {
+    delete process.env.EMBEDDINGS_ENABLED;
     const store = getVaultStore("test");
-    expect(store.embeddingDisabledReason).toBe("semantic search is disabled by EMBEDDINGS_ENABLED=false");
+    expect(store.embeddingProvider).toBeUndefined();
+    expect(store.embeddingDisabledReason).toBe(EMBEDDINGS_DISABLED_REASON);
 
     let caught: unknown;
     try {
@@ -57,13 +59,20 @@ describe("getVaultStore — EMBEDDINGS_ENABLED=false hint wiring", () => {
     }
     expect(caught).toBeInstanceOf(QueryError);
     expect((caught as QueryError).error_type).toBe("semantic_unavailable");
-    expect((caught as QueryError).hint).toBe("semantic search is disabled by EMBEDDINGS_ENABLED=false");
+    expect((caught as QueryError).hint).toBe(EMBEDDINGS_DISABLED_REASON);
   });
 
-  test("no reason set when EMBEDDINGS_ENABLED is unset — the store still has a (bundled-floor) provider", async () => {
-    delete process.env.EMBEDDINGS_ENABLED;
+  test("EMBEDDINGS_ENABLED=false is the same off path — no provider, opt-in hint", () => {
+    process.env.EMBEDDINGS_ENABLED = "false";
+    const store = getVaultStore("test");
+    expect(store.embeddingProvider).toBeUndefined();
+    expect(store.embeddingDisabledReason).toBe(EMBEDDINGS_DISABLED_REASON);
+  });
+
+  test("EMBEDDINGS_ENABLED=true enables — the store gets a (bundled-floor) provider and no disabled reason", () => {
+    process.env.EMBEDDINGS_ENABLED = "true";
     const store = getVaultStore("test");
-    expect(store.embeddingDisabledReason).toBeUndefined();
     expect(store.embeddingProvider).toBeDefined();
+    expect(store.embeddingDisabledReason).toBeUndefined();
   });
 });

package/src/vault-store.ts

@@ -9,9 +9,18 @@ import { SqliteStore } from "../core/src/store.ts";
 import { defaultHookRegistry } from "../core/src/hooks.ts";
 import type { Store } from "../core/src/types.ts";
 import type { EmbeddingProvider } from "../core/src/embedding/provider.ts";
-import { buildEmbeddingProvider, embeddingsExplicitlyDisabled } from "./embedding/select.ts";
+import { buildEmbeddingProvider } from "./embedding/select.ts";
+import { readGlobalConfig } from "./config.ts";
 import { openVaultDb } from "./db.ts";
 
+/**
+ * The honest hint `semanticSearch` surfaces when semantic search is OFF
+ * (the 0.7.3 opt-in default). Points the operator at both the env override
+ * and the persisted settings toggle — see `src/embedding/select.ts`.
+ */
+export const EMBEDDINGS_DISABLED_REASON =
+  "semantic search is off — it is opt-in as of 0.7.3; enable it with EMBEDDINGS_ENABLED=true, or set embeddings_enabled: true in ~/.parachute/vault/config.yaml, then restart the vault";
+
 export { SqliteStore as BunStore };
 export { defaultHookRegistry };
 
@@ -34,19 +43,26 @@ const storeToVault = new WeakMap<SqliteStore, string>();
  * `loadEnvFile()` in `server.ts` is visible) and reused for every
  * subsequent vault opened this process.
  *
- * `undefined` is a legitimate, cacheable resolution — `EMBEDDINGS_ENABLED=
- * false` (the off switch, see `select.ts`) means "no provider," not
- * "not resolved yet." A separate `resolved` flag (rather than null-
- * checking the provider itself) distinguishes the two, so an explicitly-
- * disabled vault doesn't re-run `buildEmbeddingProvider()` on every call.
+ * `undefined` is a legitimate, cacheable resolution — semantic search is
+ * OFF by default (opt-in as of 0.7.3), so the common case is "no provider,"
+ * not "not resolved yet." A separate `resolved` flag (rather than null-
+ * checking the provider itself) distinguishes the two, so a disabled vault
+ * doesn't re-run `buildEmbeddingProvider()` on every call.
+ *
+ * Resolution threads the persisted `embeddings_enabled` config.yaml setting
+ * in as the default, with the `EMBEDDINGS_ENABLED` env var as the override
+ * (see `select.ts`'s `resolveEmbeddingsEnabled`). Because it's memoized at
+ * first access, flipping the setting takes effect on the next server start.
  */
 let sharedEmbeddingProvider: EmbeddingProvider | undefined;
 let sharedEmbeddingProviderResolved = false;
 
-/** The shared embedding provider (see `sharedEmbeddingProvider`'s doc comment). `undefined` when `EMBEDDINGS_ENABLED=false`. */
+/** The shared embedding provider (see `sharedEmbeddingProvider`'s doc comment). `undefined` when semantic search is off (the opt-in default). */
 export function getSharedEmbeddingProvider(): EmbeddingProvider | undefined {
   if (!sharedEmbeddingProviderResolved) {
-    sharedEmbeddingProvider = buildEmbeddingProvider();
+    sharedEmbeddingProvider = buildEmbeddingProvider(process.env, {
+      persistedEnabled: readGlobalConfig().embeddings_enabled,
+    });
     sharedEmbeddingProviderResolved = true;
   }
   return sharedEmbeddingProvider;
@@ -68,16 +84,16 @@ export function getVaultStore(name: string): SqliteStore {
     // for the embedding provider (see `getSharedEmbeddingProvider`'s doc
     // comment) — every vault's semantic search resolves the SAME provider
     // instance. `embeddingDisabledReason` is only ever set here (core can't
-    // read env vars itself — see `Store.embeddingDisabledReason`'s doc
-    // comment), so `semanticSearch`'s no-provider hint can say "explicitly
-    // disabled" instead of generic provider-setup instructions when that's
-    // actually why.
+    // read env/config itself — see `Store.embeddingDisabledReason`'s doc
+    // comment), so `semanticSearch`'s no-provider hint can name the opt-in
+    // toggle instead of generic provider-setup instructions. Derived from
+    // provider-absence directly, so the hint is present exactly when (and
+    // because) semantic search is off — no second read of the resolution.
+    const embeddingProvider = getSharedEmbeddingProvider();
     store = new SqliteStore(db, {
       hooks: defaultHookRegistry,
-      embeddingProvider: getSharedEmbeddingProvider(),
-      embeddingDisabledReason: embeddingsExplicitlyDisabled()
-        ? "semantic search is disabled by EMBEDDINGS_ENABLED=false"
-        : undefined,
+      embeddingProvider,
+      embeddingDisabledReason: embeddingProvider ? undefined : EMBEDDINGS_DISABLED_REASON,
     });
     stores.set(name, store);
     storeToVault.set(store, name);

package/src/vault.test.ts

@@ -6625,12 +6625,15 @@ describe("stateless MCP transport", async () => {
     expect(toolNames).not.toContain("merge-tags");
     // Admin tools (vault#376) are hidden too
     expect(toolNames).not.toContain("manage-token");
-    // request-attachment-download is read-tier (upload is write-tier).
+    // request-attachment-download and read-attachment are read-tier
+    // (upload is write-tier).
     expect(toolNames).toContain("request-attachment-download");
     expect(toolNames).not.toContain("request-attachment-upload");
-    // Read tier is exactly 6 tools (doctor added by the re-tier;
-    // request-attachment-download added by the attachment-tickets design).
-    expect(toolNames.length).toBe(6);
+    expect(toolNames).toContain("read-attachment");
+    // Read tier is exactly 7 tools (doctor added by the re-tier;
+    // request-attachment-download by the attachment-tickets design;
+    // read-attachment by Wave 2).
+    expect(toolNames.length).toBe(7);
 
     closeAllStores();
   });
@@ -6911,15 +6914,23 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
     return names;
   }
 
-  test("vault:read sees exactly the 6 read tools (doctor moved admin → read; request-attachment-download is read-tier)", async () => {
+  test("vault:read sees exactly the 7 read tools (doctor moved admin → read; read-attachment and request-attachment-download are read-tier)", async () => {
     const names = await listToolNames(["vault:read"]);
     expect(new Set(names)).toEqual(
-      new Set(["query-notes", "list-tags", "find-path", "vault-info", "doctor", "request-attachment-download"]),
+      new Set([
+        "query-notes",
+        "list-tags",
+        "find-path",
+        "vault-info",
+        "doctor",
+        "request-attachment-download",
+        "read-attachment",
+      ]),
     );
-    expect(names.length).toBe(6);
+    expect(names.length).toBe(7);
   });
 
-  test("vault:read + vault:write sees the 10 read+write tools (tag-schema tools moved write → admin; request-attachment-upload is write-tier)", async () => {
+  test("vault:read + vault:write sees the 11 read+write tools (tag-schema tools moved write → admin; request-attachment-upload is write-tier)", async () => {
     const names = await listToolNames(["vault:read", "vault:write"]);
     expect(new Set(names)).toEqual(
       new Set([
@@ -6933,9 +6944,10 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
         "delete-note",
         "request-attachment-upload",
         "request-attachment-download",
+        "read-attachment",
       ]),
     );
-    expect(names.length).toBe(10);
+    expect(names.length).toBe(11);
     expect(names).not.toContain("manage-token");
     // Re-tier (this PR): update-tag/delete-tag/rename-tag/merge-tags are now
     // admin-tier — structure/taxonomy curation, not content authorship.
@@ -6947,7 +6959,7 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
     expect(names).toContain("delete-note");
   });
 
-  test("vault:admin sees all 16 tools including manage-token + prune-schema + the tag-schema tools + both attachment-ticket tools", async () => {
+  test("vault:admin sees all 17 tools including manage-token + prune-schema + the tag-schema tools + all three attachment tools", async () => {
     const names = await listToolNames(["vault:read", "vault:write", "vault:admin"]);
     expect(names).toContain("manage-token");
     expect(names).toContain("prune-schema");
@@ -6958,10 +6970,11 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
     expect(names).toContain("merge-tags");
     expect(names).toContain("request-attachment-upload");
     expect(names).toContain("request-attachment-download");
-    expect(names.length).toBe(16);
+    expect(names).toContain("read-attachment");
+    expect(names.length).toBe(17);
   });
 
-  test("legacy-derived full token sees all 16 tools (back-compat)", async () => {
+  test("legacy-derived full token sees all 17 tools (back-compat)", async () => {
     const { handleScopedMcp } = await import("./mcp-http.ts");
     const { writeVaultConfig } = await import("./config.ts");
     const { closeAllStores } = await import("./vault-store.ts");
@@ -6994,7 +7007,7 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
     } as any);
     const body = await res.json() as any;
     const names: string[] = body.result.tools.map((t: any) => t.name);
-    expect(names.length).toBe(16);
+    expect(names.length).toBe(17);
     expect(names).toContain("manage-token");
     expect(names).toContain("prune-schema");
     expect(names).toContain("doctor");

package/src/ws-server.ts

@@ -31,6 +31,7 @@
 
 import type { Server, ServerWebSocket, WebSocketHandler } from "bun";
 import type { Store } from "../core/src/types.ts";
+import { toNoteIndex } from "../core/src/notes.ts";
 import type { VaultConfig } from "./config.ts";
 import { readVaultConfig } from "./config.ts";
 import { getVaultStore } from "./vault-store.ts";
@@ -229,6 +230,9 @@ export function createSubscribeWsBinding(deps: SubscribeWsDeps = {}): {
       closeWs(ws, WS_CLOSE.PROTOCOL, "invalid subscription query");
       return;
     }
+    // Lean list subscriptions (`include_content=false`) ship the `NoteIndex`
+    // projection — snapshot + live upserts — instead of full note bodies.
+    const lean = !validated.includeContent;
 
     let tagScopeAllowed: Set<string> | null;
     let matcher;
@@ -247,7 +251,10 @@ export function createSubscribeWsBinding(deps: SubscribeWsDeps = {}): {
       closeWs(ws, WS_CLOSE.PROTOCOL, "snapshot query failed");
       return;
     }
-    const frames = buildSnapshotFrames(snapshotNotes);
+    // Project AFTER the tag-scope filter (which reads note.tags). `toNoteIndex`
+    // is the SAME lean shape the REST list route returns, so a client that
+    // renders REST lists renders these snapshot frames unchanged.
+    const frames = buildSnapshotFrames(lean ? snapshotNotes.map(toNoteIndex) : snapshotNotes);
 
     // --- SYNCHRONOUS from here (no await) so no write interleaves between
     //     register and the snapshot flush.
@@ -261,6 +268,7 @@ export function createSubscribeWsBinding(deps: SubscribeWsDeps = {}): {
       tagScopeAllowed,
       tagScopeRaw: auth.scoped_tags,
       sink: new WsSink(ws),
+      lean,
       tracksFlush: false,
       countsTowardCap: false,
     });