clawmem 0.10.6 → 0.11.0

package/AGENTS.md

@@ -523,7 +523,7 @@ The `memory_relations` table is populated by multiple independent sources:
 
 **Graph traversal asymmetry:** `adaptiveTraversal()` traverses all edge types outbound (source→target) but only `semantic` and `entity` edges inbound (target→source). Temporal and causal edges are directional only.
 
-**MPFP graph retrieval (v0.2.0):** Multi-Path Fact Propagation runs predefined meta-path patterns in parallel (`[semantic, semantic]`, `[entity, temporal]`, `[semantic, causal]`, etc.), fuses via RRF. Hop-synchronized edge cache batches DB queries per hop instead of per pattern. Forward Push with α=0.15 teleport probability bounds active nodes sublinearly. Tier 3 only (`query`/`intent_search`), not hooks. Patterns selected per MAGMA intent: WHY → `[semantic, causal]`, ENTITY → `[entity, semantic]`, WHEN → `[temporal, semantic]`.
+**MPFP graph retrieval (v0.2.0):** Multi-Path Fact Propagation runs predefined meta-path patterns in parallel (`[semantic, semantic]`, `[entity, temporal]`, `[semantic, causal]`, etc.), fuses via **max-score** (best supporting path wins). Note: meta-path fusion is max-score, NOT RRF — Forward Push yields absolute propagation mass where magnitude carries signal, so rank-only fusion would discard the difference between a strong path hit and a barely-surviving tail hit (`src/graph-traversal.ts:413-425`). This is distinct from the `query`/`intent_search` *outer* retrieval, which does fuse BM25+vector via RRF. Hop-synchronized edge cache batches DB queries per hop instead of per pattern. Forward Push with α=0.15 teleport probability bounds active nodes sublinearly. Tier 3 only (`query`/`intent_search`), not hooks. Patterns selected per MAGMA intent: WHY → `[semantic, causal]`, ENTITY → `[entity, semantic]`, WHEN → `[temporal, semantic]`.
 
 ### When to Run `build_graphs`
 

package/CLAUDE.md

@@ -523,7 +523,7 @@ The `memory_relations` table is populated by multiple independent sources:
 
 **Graph traversal asymmetry:** `adaptiveTraversal()` traverses all edge types outbound (source→target) but only `semantic` and `entity` edges inbound (target→source). Temporal and causal edges are directional only.
 
-**MPFP graph retrieval (v0.2.0):** Multi-Path Fact Propagation runs predefined meta-path patterns in parallel (`[semantic, semantic]`, `[entity, temporal]`, `[semantic, causal]`, etc.), fuses via RRF. Hop-synchronized edge cache batches DB queries per hop instead of per pattern. Forward Push with α=0.15 teleport probability bounds active nodes sublinearly. Tier 3 only (`query`/`intent_search`), not hooks. Patterns selected per MAGMA intent: WHY → `[semantic, causal]`, ENTITY → `[entity, semantic]`, WHEN → `[temporal, semantic]`.
+**MPFP graph retrieval (v0.2.0):** Multi-Path Fact Propagation runs predefined meta-path patterns in parallel (`[semantic, semantic]`, `[entity, temporal]`, `[semantic, causal]`, etc.), fuses via **max-score** (best supporting path wins). Note: meta-path fusion is max-score, NOT RRF — Forward Push yields absolute propagation mass where magnitude carries signal, so rank-only fusion would discard the difference between a strong path hit and a barely-surviving tail hit (`src/graph-traversal.ts:413-425`). This is distinct from the `query`/`intent_search` *outer* retrieval, which does fuse BM25+vector via RRF. Hop-synchronized edge cache batches DB queries per hop instead of per pattern. Forward Push with α=0.15 teleport probability bounds active nodes sublinearly. Tier 3 only (`query`/`intent_search`), not hooks. Patterns selected per MAGMA intent: WHY → `[semantic, causal]`, ENTITY → `[entity, semantic]`, WHEN → `[temporal, semantic]`.
 
 ### When to Run `build_graphs`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmem",
-  "version": "0.10.6",
+  "version": "0.11.0",
   "description": "On-device memory layer for AI agents. Claude Code, OpenClaw, and Hermes. Hooks + MCP server + hybrid RAG search.",
   "type": "module",
   "bin": {

package/src/clawmem.ts

@@ -18,6 +18,10 @@ import {
   DEFAULT_RERANK_MODEL,
   DEFAULT_GLOB,
   extractSnippet,
+  FatalVectorError,
+  VecDimensionMismatchError,
+  VecModelMismatchError,
+  EmbedLeaseLostError,
 } from "./store.ts";
 import {
   getDefaultLlamaCpp,
@@ -28,6 +32,11 @@ import {
   LlamaCpp,
   type Queryable,
 } from "./llm.ts";
+import {
+  acquireWorkerLease,
+  releaseWorkerLease,
+  renewWorkerLease,
+} from "./worker-lease.ts";
 import {
   loadConfig,
   addCollection as collectionsAdd,
@@ -385,200 +394,331 @@ async function cmdEmbed(args: string[]) {
 
   const s = getStore();
 
-  if (values.force) {
-    console.log(`${c.yellow}Force mode: clearing all embeddings${c.reset}`);
-    s.clearAllEmbeddings();
+  // Embedding lease: serialize embed commands (manual / embed timer / update --embed)
+  // so two embeds cannot run at once. It is RENEWABLE (token-fenced heartbeat), not a
+  // fixed-TTL lease — a full-vault rebuild outlasts any fixed TTL and would be reclaimed
+  // mid-run. Without serialization, two embeds using different same-dimension models can
+  // silently build a heterogeneous vector space (dimension checks can't catch that).
+  // See EMBED-LEASE-RENEWAL-DESIGN.md / INCIDENT-2026-06-22.
+  const LEASE_NAME = "embedding";
+  const LEASE_TTL_MS = 60_000;
+  const lease = acquireWorkerLease(s, LEASE_NAME, LEASE_TTL_MS);
+  if (!lease.acquired || !lease.token) {
+    console.log(`${c.yellow}Another embed is already in progress (lease held); skipping.${c.reset}`);
+    return;
   }
+  const leaseToken = lease.token;
+  // Passed into every vector mutation (clear, stale-clean, table-create, insert) so
+  // each verifies ownership before mutating — a process that lost the lease mid-await
+  // cannot wipe/recreate/write the vector store under the new holder.
+  const leaseGuard = { workerName: LEASE_NAME, token: leaseToken };
+  let leaseLost = false;
+  const heartbeat = setInterval(() => {
+    if (!renewWorkerLease(s, LEASE_NAME, leaseToken, LEASE_TTL_MS)) leaseLost = true;
+  }, Math.floor(LEASE_TTL_MS / 2));
 
-  // Clean stale embeddings (orphaned hashes from updated/deleted documents)
-  const cleaned = s.cleanStaleEmbeddings();
-  if (cleaned > 0) {
-    console.log(`${c.yellow}Cleaned ${cleaned} stale embedding(s) from orphaned documents${c.reset}`);
-  }
+  try {
+    const embedUrl = process.env.CLAWMEM_EMBED_URL;
+    if (embedUrl) {
+      console.log(`Using remote GPU embedding: ${embedUrl}`);
+    } else {
+      // Local CPU mode: disable inactivity timeout to prevent context disposal mid-batch
+      setDefaultLlamaCpp(new LlamaCpp({ inactivityTimeoutMs: 0 }));
+    }
+    const llm = getDefaultLlamaCpp();
 
-  // Use fragment-based pipeline: split documents into semantic fragments and embed each
-  const hashes = s.getHashesNeedingFragments();
-  if (hashes.length === 0) {
-    console.log(`${c.green}All documents already embedded${c.reset}`);
-    return;
-  }
+    // Probe the live model's output dimension (+ model name). Returns null on ANY
+    // failure so a down/flaky endpoint can NEVER trigger a destructive clear.
+    const probeEmbed = async (): Promise<{ dim: number; model: string } | null> => {
+      try {
+        const r = await llm.embed("clawmem dimension probe");
+        return r && r.embedding && r.embedding.length > 0
+          ? { dim: r.embedding.length, model: r.model ?? "" }
+          : null;
+      } catch { return null; }
+    };
 
-  // Count total fragments first for ETA
-  let totalFragEstimate = 0;
-  const docFragCounts: number[] = [];
-  for (const { body, path } of hashes) {
-    let frontmatter: Record<string, any> | undefined;
-    try {
-      const parsed = parseDocument(body, path);
-      frontmatter = parsed.meta as any;
-    } catch { /* skip */ }
-    const frags = splitDocument(body, frontmatter);
-    docFragCounts.push(frags.length);
-    totalFragEstimate += frags.length;
-  }
-  console.log(`Embedding ${hashes.length} documents (${totalFragEstimate} fragments total)...`);
-
-  const embedUrl = process.env.CLAWMEM_EMBED_URL;
-  if (embedUrl) {
-    console.log(`Using remote GPU embedding: ${embedUrl}`);
-  } else {
-    // Local CPU mode: disable inactivity timeout to prevent context disposal mid-batch
-    setDefaultLlamaCpp(new LlamaCpp({ inactivityTimeoutMs: 0 }));
-  }
-  const llm = getDefaultLlamaCpp();
-  let embedded = 0;
-  let totalFragments = 0;
-  let failedFragments = 0;
-  const batchStart = Date.now();
-
-  // Cloud API: global batch pacing state (persists across documents)
-  // TPM is the binding constraint, not RPM. 50 frags × ~800 tokens ≈ 40K tokens/batch → max ~2.5 batches/min at 100K TPM.
-  const isCloudEmbed = !!process.env.CLAWMEM_EMBED_API_KEY;
-  const CLOUD_BATCH_SIZE = 50;
-  const CLOUD_TPM_LIMIT = parseInt(process.env.CLAWMEM_EMBED_TPM_LIMIT || "100000", 10);
-  const CLOUD_TPM_SAFETY = 0.85; // use 85% of limit to leave headroom for retries
-  const CHARS_PER_TOKEN = 4;
-  let lastBatchSentAt = 0; // global timestamp of last batch send
-
-  for (let docIdx = 0; docIdx < hashes.length; docIdx++) {
-    const { hash, body, path, title: docTitle, collection } = hashes[docIdx]!;
-    const title = docTitle || basename(path).replace(/\.(md|txt)$/i, "");
-    const canId = canonicalDocId(collection, path);
-
-    // Parse frontmatter for fragment splitting
-    let frontmatter: Record<string, any> | undefined;
-    try {
-      const parsed = parseDocument(body, path);
-      frontmatter = parsed.meta as any;
-    } catch {
-      // No frontmatter or parsing error — fine, skip it
-    }
-
-    const fragments = splitDocument(body, frontmatter);
-    const docStart = Date.now();
-    const prevTotalFragments = totalFragments;
-    const prevFailedFragments = failedFragments;
-    let seq0Succeeded = false;
-    console.error(`  [${docIdx + 1}/${hashes.length}] ${basename(path)} (${fragments.length} frags, ${body.length} chars)`);
-
-    if (isCloudEmbed) {
-      // Batch mode: collect all texts, send in chunks of CLOUD_BATCH_SIZE
-      const allTexts: string[] = [];
-      for (const frag of fragments) {
-        const label = frag.label || title;
-        allTexts.push(formatDocForEmbedding(frag.content, label));
+    // Bind the whole run to one (dim, model); every fragment is validated before it is
+    // stored. On a fresh vault these are set from the first successful fragment.
+    let expectedDim: number | null = null;
+    let expectedModel: string | null = null;
+
+    if (values.force) {
+      // Probe FIRST — validate the endpoint before destroying anything (so a force
+      // re-embed against a dead endpoint cannot clear the vault and then fail).
+      const probe = await probeEmbed();
+      if (!probe) {
+        console.error(`${c.red}Force re-embed aborted: could not reach the embedding endpoint. Nothing was cleared.${c.reset}`);
+        return;
       }
-
-      for (let batchStart = 0; batchStart < allTexts.length; batchStart += CLOUD_BATCH_SIZE) {
-        // Global TPM-aware delay: compute required wait based on last batch's token count,
-        // then wait only the remaining time since lastBatchSentAt. Applies to ALL batches
-        // including first batch of each document (inter-document pacing).
-        if (lastBatchSentAt > 0) {
-          // Adaptive TPM-aware delay. Set CLAWMEM_EMBED_TPM_LIMIT to match your tier:
-          //   Free: 100000 (default), Paid: 2000000, Premium: 50000000
-          const batchEnd0 = Math.min(batchStart + CLOUD_BATCH_SIZE, allTexts.length);
-          const estimatedTokens = allTexts.slice(batchStart, batchEnd0)
-            .reduce((sum, t) => sum + Math.ceil(t.length / CHARS_PER_TOKEN), 0);
-          // Use current batch estimate (not previous batch actuals — previous batch may differ in size)
-          const batchTokens = estimatedTokens;
-          const safeTPM = CLOUD_TPM_LIMIT * CLOUD_TPM_SAFETY;
-          const requiredGapMs = Math.max(500, (batchTokens / safeTPM) * 60_000);
-          const elapsed = Date.now() - lastBatchSentAt;
-          const remainingMs = requiredGapMs - elapsed;
-          if (remainingMs > 0) {
-            const jittered = Math.floor(remainingMs * (0.85 + Math.random() * 0.3));
-            await new Promise(r => setTimeout(r, jittered));
-          }
+      console.log(`${c.yellow}Force mode: clearing all embeddings (rebuilding at dim ${probe.dim})${c.reset}`);
+      expectedDim = probe.dim;
+      expectedModel = probe.model || null;
+      s.clearAllEmbeddings(leaseGuard);
+    } else {
+      // Implicit run: NON-DESTRUCTIVE drift check (dimension AND model). Catches
+      // drift even when the worklist is empty (query embeddings would already be
+      // incompatible with the stored table). Never clears — aborts with instructions.
+      const existingDim = s.getVecTableDim(); // throws VecSchemaError on malformed DDL → caught below
+      if (existingDim !== null) {
+        const probe = await probeEmbed();
+        if (probe && probe.dim !== existingDim) {
+          console.error(`${c.red}Embedding dimension changed (${existingDim} → ${probe.dim}). Run 'clawmem embed --force' to clear and rebuild the full vault.${c.reset}`);
+          return;
         }
+        // Same dimension but a DIFFERENT model still mixes the vector space (cosine
+        // across two models is meaningless) and the dim check cannot see it. Compare
+        // the probe's model against what the vault was built with; abort on mismatch.
+        const existingModels = s.getVecModels();
+        if (existingModels.length > 1) {
+          console.error(`${c.red}Vault already contains mixed embedding models: ${existingModels.join(", ")}. Run 'clawmem embed --force' to rebuild with a single model.${c.reset}`);
+          return;
+        }
+        if (probe && probe.model && existingModels.length === 1 && existingModels[0] !== probe.model) {
+          console.error(`${c.red}Embedding model changed (${existingModels[0]} → ${probe.model}) at the same dimension. Mixing models in one vector space breaks similarity. Run 'clawmem embed --force' to rebuild with the current model.${c.reset}`);
+          return;
+        }
+        expectedDim = existingDim;
+        if (probe && probe.model) expectedModel = probe.model;
+      }
+    }
+
+    // Clean stale embeddings (orphaned hashes from updated/deleted documents)
+    const cleaned = s.cleanStaleEmbeddings(leaseGuard);
+    if (cleaned > 0) {
+      console.log(`${c.yellow}Cleaned ${cleaned} stale embedding(s) from orphaned documents${c.reset}`);
+    }
 
-        const batchEnd = Math.min(batchStart + CLOUD_BATCH_SIZE, allTexts.length);
-        const batchTexts = allTexts.slice(batchStart, batchEnd);
-        lastBatchSentAt = Date.now();
-        const reqStart = Date.now();
+    // Use fragment-based pipeline: split documents into semantic fragments and embed each
+    const hashes = s.getHashesNeedingFragments();
+    if (hashes.length === 0) {
+      console.log(`${c.green}All documents already embedded${c.reset}`);
+      return;
+    }
 
-        try {
-          const results = await llm.embedBatch(batchTexts);
-          const reqMs = Date.now() - reqStart;
-          const tokensUsed = llm.lastBatchTokens;
+    // Count total fragments first for ETA
+    let totalFragEstimate = 0;
+    const docFragCounts: number[] = [];
+    for (const { body, path } of hashes) {
+      let frontmatter: Record<string, any> | undefined;
+      try {
+        const parsed = parseDocument(body, path);
+        frontmatter = parsed.meta as any;
+      } catch { /* skip */ }
+      const frags = splitDocument(body, frontmatter);
+      docFragCounts.push(frags.length);
+      totalFragEstimate += frags.length;
+    }
+    console.log(`Embedding ${hashes.length} documents (${totalFragEstimate} fragments total)...`);
+
+    let embedded = 0;
+    let totalFragments = 0;
+    let failedFragments = 0;
+    const batchStart = Date.now();
+
+    // Cloud API: global batch pacing state (persists across documents)
+    // TPM is the binding constraint, not RPM. 50 frags × ~800 tokens ≈ 40K tokens/batch → max ~2.5 batches/min at 100K TPM.
+    const isCloudEmbed = !!process.env.CLAWMEM_EMBED_API_KEY;
+    const CLOUD_BATCH_SIZE = 50;
+    const CLOUD_TPM_LIMIT = parseInt(process.env.CLAWMEM_EMBED_TPM_LIMIT || "100000", 10);
+    const CLOUD_TPM_SAFETY = 0.85; // use 85% of limit to leave headroom for retries
+    const CHARS_PER_TOKEN = 4;
+    let lastBatchSentAt = 0; // global timestamp of last batch send
+
+    // Bind the run to one (dim, model) and validate every embedding before it is stored.
+    // The first successful fragment sets the binding on a fresh vault; any later drift —
+    // a dimension change OR a same-dimension model swap from a flapping endpoint — throws
+    // a fatal error that aborts the whole run (caught below). This is what dimension
+    // checks alone cannot do: catch a different 2560-d model.
+    const bindAndValidate = (result: { embedding: number[] | Float32Array; model?: string }) => {
+      const dim = result.embedding.length;
+      if (expectedDim === null) {
+        expectedDim = dim;
+        if (!expectedModel && result.model) expectedModel = result.model;
+      } else if (dim !== expectedDim) {
+        throw new VecDimensionMismatchError(expectedDim, dim);
+      }
+      if (expectedModel && result.model && result.model !== expectedModel) {
+        throw new VecModelMismatchError(expectedModel, result.model);
+      }
+    };
+
+    for (let docIdx = 0; docIdx < hashes.length; docIdx++) {
+      // Abort cleanly if the heartbeat reported the lease was reclaimed.
+      if (leaseLost) throw new EmbedLeaseLostError();
+
+      const { hash, body, path, title: docTitle, collection } = hashes[docIdx]!;
+      const title = docTitle || basename(path).replace(/\.(md|txt)$/i, "");
+      const canId = canonicalDocId(collection, path);
+
+      // Parse frontmatter for fragment splitting
+      let frontmatter: Record<string, any> | undefined;
+      try {
+        const parsed = parseDocument(body, path);
+        frontmatter = parsed.meta as any;
+      } catch {
+        // No frontmatter or parsing error — fine, skip it
+      }
 
-          for (let i = 0; i < results.length; i++) {
-            const seq = batchStart + i;
-            const frag = fragments[seq]!;
-            const result = results[i];
+      const fragments = splitDocument(body, frontmatter);
+      const docStart = Date.now();
+      const prevFailedFragments = failedFragments;
+      let seq0Succeeded = false;
+
+      // Mark the doc 'pending' and increment embed_attempts ONCE before its first
+      // fragment, so a crash mid-document leaves it retryable (re-selected by
+      // getHashesNeedingFragments). Completion setters below are state-only.
+      s.markEmbedStart(hash);
+      console.error(`  [${docIdx + 1}/${hashes.length}] ${basename(path)} (${fragments.length} frags, ${body.length} chars)`);
+
+      if (isCloudEmbed) {
+        // Batch mode: collect all texts, send in chunks of CLOUD_BATCH_SIZE
+        const allTexts: string[] = [];
+        for (const frag of fragments) {
+          const label = frag.label || title;
+          allTexts.push(formatDocForEmbedding(frag.content, label));
+        }
+
+        for (let batchStartIdx = 0; batchStartIdx < allTexts.length; batchStartIdx += CLOUD_BATCH_SIZE) {
+          // Abort before each batch if the lease was reclaimed — a large document
+          // must not keep writing after another process took the lease (HIGH-3).
+          if (leaseLost) throw new EmbedLeaseLostError();
+          // Global TPM-aware delay: compute required wait based on last batch's token count,
+          // then wait only the remaining time since lastBatchSentAt. Applies to ALL batches
+          // including first batch of each document (inter-document pacing).
+          if (lastBatchSentAt > 0) {
+            // Adaptive TPM-aware delay. Set CLAWMEM_EMBED_TPM_LIMIT to match your tier:
+            //   Free: 100000 (default), Paid: 2000000, Premium: 50000000
+            const batchEnd0 = Math.min(batchStartIdx + CLOUD_BATCH_SIZE, allTexts.length);
+            const estimatedTokens = allTexts.slice(batchStartIdx, batchEnd0)
+              .reduce((sum, t) => sum + Math.ceil(t.length / CHARS_PER_TOKEN), 0);
+            // Use current batch estimate (not previous batch actuals — previous batch may differ in size)
+            const batchTokens = estimatedTokens;
+            const safeTPM = CLOUD_TPM_LIMIT * CLOUD_TPM_SAFETY;
+            const requiredGapMs = Math.max(500, (batchTokens / safeTPM) * 60_000);
+            const elapsed = Date.now() - lastBatchSentAt;
+            const remainingMs = requiredGapMs - elapsed;
+            if (remainingMs > 0) {
+              const jittered = Math.floor(remainingMs * (0.85 + Math.random() * 0.3));
+              await new Promise(r => setTimeout(r, jittered));
+            }
+          }
+
+          const batchEnd = Math.min(batchStartIdx + CLOUD_BATCH_SIZE, allTexts.length);
+          const batchTexts = allTexts.slice(batchStartIdx, batchEnd);
+          lastBatchSentAt = Date.now();
+          const reqStart = Date.now();
+
+          try {
+            const results = await llm.embedBatch(batchTexts);
+            const reqMs = Date.now() - reqStart;
+            const tokensUsed = llm.lastBatchTokens;
+
+            for (let i = 0; i < results.length; i++) {
+              const seq = batchStartIdx + i;
+              const frag = fragments[seq]!;
+              const result = results[i];
+              if (result) {
+                bindAndValidate(result);
+                s.ensureVecTable(result.embedding.length, leaseGuard);
+                s.insertEmbedding(
+                  hash, seq, frag.startLine, new Float32Array(result.embedding),
+                  result.model, new Date().toISOString(), frag.type, frag.label ?? undefined, canId,
+                  leaseGuard
+                );
+                totalFragments++;
+                if (seq === 0) seq0Succeeded = true;
+              } else {
+                failedFragments++;
+              }
+            }
+            console.error(`    batch ${batchStartIdx + 1}-${batchEnd}/${allTexts.length} (${results.filter(r => r).length} ok) ${reqMs}ms${tokensUsed ? ` ${tokensUsed} tok` : ""}`);
+          } catch (err) {
+            if (err instanceof FatalVectorError) throw err; // dim/model/schema mismatch → abort the whole run
+            failedFragments += batchTexts.length;
+            console.error(`${c.yellow}Warning: batch embed failed for ${path} frags ${batchStartIdx + 1}-${batchEnd}: ${err}${c.reset}`);
+          }
+        }
+      } else {
+        // Local mode: embed one at a time (no rate limit concern)
+        for (let seq = 0; seq < fragments.length; seq++) {
+          // Abort before each fragment if the lease was reclaimed — bounds any
+          // post-loss writing to at most one fragment of a large doc (HIGH-3).
+          if (leaseLost) throw new EmbedLeaseLostError();
+          const frag = fragments[seq]!;
+          const label = frag.label || title;
+          const text = formatDocForEmbedding(frag.content, label);
+
+          try {
+            const fragStart = Date.now();
+            const result = await llm.embed(text);
+            const fragMs = Date.now() - fragStart;
             if (result) {
-              s.ensureVecTable(result.embedding.length);
+              bindAndValidate(result);
+              s.ensureVecTable(result.embedding.length, leaseGuard);
               s.insertEmbedding(
                 hash, seq, frag.startLine, new Float32Array(result.embedding),
-                result.model, new Date().toISOString(), frag.type, frag.label ?? undefined, canId
+                result.model, new Date().toISOString(), frag.type, frag.label ?? undefined, canId,
+                leaseGuard
               );
               totalFragments++;
               if (seq === 0) seq0Succeeded = true;
+              if (seq === 0 || (seq + 1) % 5 === 0 || seq === fragments.length - 1) {
+                console.error(`    frag ${seq + 1}/${fragments.length} (${frag.type}) ${fragMs}ms [${text.length} chars]`);
+              }
             } else {
               failedFragments++;
+              console.error(`    frag ${seq + 1}/${fragments.length} (${frag.type}) → null result [${text.length} chars]`);
             }
-          }
-          console.error(`    batch ${batchStart + 1}-${batchEnd}/${allTexts.length} (${results.filter(r => r).length} ok) ${reqMs}ms${tokensUsed ? ` ${tokensUsed} tok` : ""}`);
-        } catch (err) {
-          failedFragments += batchTexts.length;
-          console.error(`${c.yellow}Warning: batch embed failed for ${path} frags ${batchStart + 1}-${batchEnd}: ${err}${c.reset}`);
-        }
-      }
-    } else {
-      // Local mode: embed one at a time (no rate limit concern)
-      for (let seq = 0; seq < fragments.length; seq++) {
-        const frag = fragments[seq]!;
-        const label = frag.label || title;
-        const text = formatDocForEmbedding(frag.content, label);
-
-        try {
-          const fragStart = Date.now();
-          const result = await llm.embed(text);
-          const fragMs = Date.now() - fragStart;
-          if (result) {
-            s.ensureVecTable(result.embedding.length);
-            s.insertEmbedding(
-              hash, seq, frag.startLine, new Float32Array(result.embedding),
-              result.model, new Date().toISOString(), frag.type, frag.label ?? undefined, canId
-            );
-            totalFragments++;
-            if (seq === 0) seq0Succeeded = true;
-            if (seq === 0 || (seq + 1) % 5 === 0 || seq === fragments.length - 1) {
-              console.error(`    frag ${seq + 1}/${fragments.length} (${frag.type}) ${fragMs}ms [${text.length} chars]`);
-            }
-          } else {
+          } catch (err) {
+            if (err instanceof FatalVectorError) throw err; // dim/model/schema mismatch → abort the whole run
             failedFragments++;
-            console.error(`    frag ${seq + 1}/${fragments.length} (${frag.type}) → null result [${text.length} chars]`);
+            console.error(`${c.yellow}Warning: failed to embed fragment ${seq} (${frag.type}) of ${path}: ${err}${c.reset}`);
           }
-        } catch (err) {
-          failedFragments++;
-          console.error(`${c.yellow}Warning: failed to embed fragment ${seq} (${frag.type}) of ${path}: ${err}${c.reset}`);
         }
       }
+
+      // Embed-state completion: mark synced ONLY when the WHOLE document succeeded (no
+      // failed fragments) — a partial embed must not be silently permanent. Any failure
+      // → 'failed' (state-only; attempts already incremented at markEmbedStart) so the
+      // worklist retries it, bounded by embed_attempts < 3.
+      const docFragsFail = failedFragments - prevFailedFragments;
+      if (seq0Succeeded && docFragsFail === 0) {
+        s.markEmbedSynced(hash);
+      } else if (!seq0Succeeded) {
+        s.markEmbedFailed(hash, "primary fragment (seq=0) failed");
+      } else {
+        s.markEmbedFailed(hash, `${docFragsFail} fragment(s) failed`);
+      }
+
+      embedded++;
+      const docMs = Date.now() - docStart;
+      const elapsed = ((Date.now() - batchStart) / 1000).toFixed(0);
+      console.error(`  → doc done in ${(docMs / 1000).toFixed(1)}s | ${embedded}/${hashes.length} docs, ${totalFragments} frags, ${failedFragments} fails [${elapsed}s elapsed]`);
     }
 
-    // Track embed state per document — seq=0 (primary) must succeed for synced status
-    const docFragsOk = totalFragments - prevTotalFragments;
-    const docFragsFail = failedFragments - prevFailedFragments;
-    if (seq0Succeeded) {
-      s.markEmbedSynced(hash);
-    } else if (docFragsOk === 0 && docFragsFail > 0) {
-      s.markEmbedFailed(hash, "all fragments failed");
+    const totalSec = ((Date.now() - batchStart) / 1000).toFixed(1);
+    console.log();
+    console.log(`${c.green}Embedded ${embedded} documents (${totalFragments} fragments, ${failedFragments} failed) in ${totalSec}s${c.reset}`);
+  } catch (err) {
+    // Fatal aborts must NOT exit 0 — otherwise the embed timer / `update --embed`
+    // cannot tell the run was incomplete. Set a nonzero exit code (cleanup still
+    // runs in finally). Non-fatal errors propagate unchanged.
+    if (err instanceof EmbedLeaseLostError) {
+      // Checked before FatalVectorError because EmbedLeaseLostError extends it.
+      console.error(`${c.red}Embed aborted: lost the embedding lease (another embed process took over). Re-run 'clawmem embed'.${c.reset}`);
+      process.exitCode = 1;
+    } else if (err instanceof FatalVectorError) {
+      console.error(`${c.red}Embed aborted: ${(err as Error).message}${c.reset}`);
+      process.exitCode = 1;
     } else {
-      // seq=0 failed but some later fragments succeeded — mark failed so seq=0 gets retried
-      s.markEmbedFailed(hash, "primary fragment (seq=0) failed");
+      throw err;
     }
-
-    embedded++;
-    const docMs = Date.now() - docStart;
-    const elapsed = ((Date.now() - batchStart) / 1000).toFixed(0);
-    console.error(`  → doc done in ${(docMs / 1000).toFixed(1)}s | ${embedded}/${hashes.length} docs, ${totalFragments} frags, ${failedFragments} fails [${elapsed}s elapsed]`);
+  } finally {
+    clearInterval(heartbeat);
+    releaseWorkerLease(s, LEASE_NAME, leaseToken);
+    await disposeDefaultLlamaCpp();
   }
-
-  const totalSec = ((Date.now() - batchStart) / 1000).toFixed(1);
-  console.log();
-  console.log(`${c.green}Embedded ${embedded} documents (${totalFragments} fragments, ${failedFragments} failed) in ${totalSec}s${c.reset}`);
-
-  await disposeDefaultLlamaCpp();
 }
 
 async function cmdStatus() {
@@ -1891,13 +2031,34 @@ async function cmdDoctor() {
     const s = getStore();
     const needsEmbed = s.getHashesNeedingEmbedding();
     const hasVectors = !!s.db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='vectors_vec'").get();
-    if (hasVectors) {
-      console.log(`${c.green}✓${c.reset} Vector index: exists (${needsEmbed} need embedding)`);
-    } else {
+    // ALWAYS run the consistency check — the WORST desync (content_vectors rows but
+    // vectors_vec entirely absent) lives in the no-table case, so it must not be
+    // skipped. set-diff, NOT counts (one missing + one orphan cancel in a count check).
+    // Pending docs are reported separately — they are in neither table, not a desync.
+    const vc = s.getVectorConsistency();
+    if (!hasVectors && vc.cvCount === 0) {
       console.log(`${c.yellow}!${c.reset} Vector index: not created yet (run 'clawmem embed')`);
+    } else if (!hasVectors) {
+      console.log(`${c.red}✗${c.reset} Vector index: vectors_vec is MISSING but ${vc.cvCount} content_vectors row(s) exist — full desync. Run 'clawmem embed --force' to rebuild.`);
+      issues++;
+    } else {
+      console.log(`${c.green}✓${c.reset} Vector index: exists (${needsEmbed} need embedding)`);
+      if (vc.cvMissingVv > 0 || vc.vvOrphan > 0) {
+        console.log(`${c.red}✗${c.reset} Vector consistency: ${vc.cvMissingVv} metadata row(s) missing a vector, ${vc.vvOrphan} orphan vector(s) (content_vectors=${vc.cvCount}, vectors_vec=${vc.vvCount}). Run 'clawmem embed --force' to rebuild.`);
+        issues++;
+      } else {
+        console.log(`${c.green}✓${c.reset} Vector consistency: ${vc.vvCount} vectors match ${vc.cvCount} metadata rows (${vc.pending} pending)`);
+      }
     }
-  } catch {
-    console.log(`${c.yellow}!${c.reset} Vector index: could not check`);
+    // Mixed embedding models = a heterogeneous vector space (cosine across different
+    // models is meaningless) even when keys/dimensions are consistent. Flag it.
+    const vecModels = s.getVecModels();
+    if (vecModels.length > 1) {
+      console.log(`${c.red}✗${c.reset} Embedding models: vault has MIXED models (${vecModels.join(", ")}) — heterogeneous vector space. Run 'clawmem embed --force' to rebuild with one model.`);
+      issues++;
+    }
+  } catch (err) {
+    console.log(`${c.yellow}!${c.reset} Vector index: could not check (${(err as Error).message})`);
   }
 
   // 4. Content types

package/src/hermes/__init__.py

@@ -422,15 +422,20 @@ class ClawMemProvider(MemoryProvider):
         if not self._bin or not query or len(query) < 5:
             return
 
-        # Increment generation so older threads can't overwrite newer results
+        # Increment generation so older threads can't overwrite newer results,
+        # and snapshot the session id + transcript path under the same lock so a
+        # concurrent on_session_switch() can't make the worker read a torn
+        # (new id / old path) pair — the worker uses the snapshot, never live state.
         with self._prefetch_lock:
             self._prefetch_generation += 1
             my_gen = self._prefetch_generation
+            run_session_id = self._session_id
+            run_transcript_path = self._transcript_path
 
         def _run():
             hook_input = {
-                "session_id": self._session_id,
-                "transcript_path": self._transcript_path,
+                "session_id": run_session_id,
+                "transcript_path": run_transcript_path,
                 "prompt": query,
                 "hook_event_name": "UserPromptSubmit",
             }
@@ -531,6 +536,50 @@ class ClawMemProvider(MemoryProvider):
 
         logger.info("clawmem: session %s extraction complete", self._session_id[:8])
 
+    def on_session_switch(
+        self,
+        new_session_id: str,
+        *,
+        parent_session_id: str = "",
+        reset: bool = False,
+        **kwargs,
+    ) -> None:
+        """Refresh session-derived state when Hermes rotates session_id mid-process.
+
+        Fires on /new (reset=True), /resume, /branch, and compression (reset=False).
+        ClawMem reads _session_id and the session-keyed _transcript_path live in
+        queue_prefetch / sync_turn / on_session_end / on_pre_compress, so a switch
+        must repoint them and drop the prior session's prefetch + bootstrap context
+        (unconditional — NOT gated on reset, or stale recall leaks into the new
+        session). Cache coherence, not a vault write, so it runs for all contexts.
+        """
+        new_id = str(new_session_id or "").strip()
+        if not new_id or not self._bin:
+            return
+        # Idempotent re-fire (duplicate dispatch) with no reset is a no-op.
+        if new_id == self._session_id and not reset:
+            return
+
+        new_path = self._transcript_path
+        if self._hermes_home:
+            transcript_dir = Path(self._hermes_home) / "clawmem-transcripts"
+            transcript_dir.mkdir(parents=True, exist_ok=True)
+            new_path = str(transcript_dir / f"{new_id}.jsonl")
+
+        with self._prefetch_lock:
+            self._session_id = new_id
+            self._transcript_path = new_path
+            # Bump generation MONOTONICALLY (never reset to 0): an in-flight
+            # prefetch worker then fails its `my_gen == _prefetch_generation`
+            # check and discards its result instead of leaking it into the new
+            # session. Advancing consumed_gen drops any already-cached result.
+            self._prefetch_generation += 1
+            self._prefetch_result = ""
+            self._prefetch_result_gen = 0
+            self._prefetch_consumed_gen = self._prefetch_generation
+            # Startup context is session-derived; must not cross session ids.
+            self._bootstrap_context = ""
+
     def on_pre_compress(self, messages: List[Dict[str, Any]]) -> str:
         """Run precompact-extract (side effect only — Hermes ignores return).
 

package/src/llm.ts

@@ -290,6 +290,7 @@ function normalizeRemoteLlmReasoningEffort(value?: string): string | null {
 
 function buildRemoteChatCompletionsUrl(remoteLlmUrl: string): string {
   const baseUrl = remoteLlmUrl.replace(/\/+$/, "");
+  if (baseUrl.endsWith("/chat/completions")) return baseUrl;
   const endpoint = baseUrl.endsWith("/v1") ? "/chat/completions" : "/v1/chat/completions";
   return `${baseUrl}${endpoint}`;
 }

package/src/store.ts

@@ -592,6 +592,25 @@ function initializeDatabase(db: Database): void {
     }
   }
 
+  // Centralize the embed-lifecycle reset on content change: ANY path that updates
+  // documents.hash (updateDocument, reactivateDocument, indexer reactivation,
+  // decision/antipattern merges, saveMemory, beads sync, …) gets the doc's embed
+  // state reset, so the new content is re-embedded with a fresh retry budget and is
+  // never excluded by the OLD content's exhausted embed_attempts. One trigger covers
+  // every caller (codex HIGH, INCIDENT-2026-06-22). It fires only on an actual change
+  // (`IS NOT` is null-safe) and does not touch hash, so it cannot recurse. Created
+  // right after the embed_* column migrations above, so the columns it references
+  // exist. NOT wrapped in try/catch: a creation failure means this load-bearing
+  // reset is silently absent, so let it surface loudly rather than hide a footgun.
+  db.exec(`
+    CREATE TRIGGER IF NOT EXISTS reset_embed_on_hash_change
+    AFTER UPDATE OF hash ON documents
+    FOR EACH ROW WHEN OLD.hash IS NOT NEW.hash
+    BEGIN
+      UPDATE documents SET embed_state = 'pending', embed_attempts = 0, embed_error = NULL WHERE id = NEW.id;
+    END;
+  `);
+
   // Migration: add A-MEM columns to documents
   const amemMigrations: [string, string][] = [
     ["amem_keywords", "ALTER TABLE documents ADD COLUMN amem_keywords TEXT"],
@@ -923,32 +942,153 @@ function initializeDatabase(db: Database): void {
 }
 
 
-// Per-database dimension cache (WeakMap keyed by db object — no collisions for in-memory DBs)
-const vecTableDimsCache = new WeakMap<Database, number>();
-
 // v0.8.1 Ext 6b: per-database cache for the query_text column presence on
 // context_usage. Set once at migration time so insertUsageFn can pick the
 // correct INSERT shape without running PRAGMA on every write. Falls back
 // to `false` (safe — equivalent to pre-migration behavior) when absent.
 const contextUsageHasQueryTextCache = new WeakMap<Database, boolean>();
 
-function ensureVecTableInternal(db: Database, dimensions: number): void {
-  if (vecTableDimsCache.get(db) === dimensions) return;
-
-  const tableInfo = db.prepare(`SELECT sql FROM sqlite_master WHERE type='table' AND name='vectors_vec'`).get() as { sql: string } | null;
-  if (tableInfo) {
-    const match = tableInfo.sql.match(/float\[(\d+)\]/);
-    const hasHashSeq = tableInfo.sql.includes('hash_seq');
-    const hasCosine = tableInfo.sql.includes('distance_metric=cosine');
-    const existingDims = match?.[1] ? parseInt(match[1], 10) : null;
-    if (existingDims === dimensions && hasHashSeq && hasCosine) {
-      vecTableDimsCache.set(db, dimensions);
+/**
+ * Fatal, non-recoverable vector-store errors. These abort the embed run rather
+ * than being swallowed as per-fragment failures. A dimension/schema mismatch must
+ * NEVER silently drop an existing table — the only path that clears vectors is the
+ * explicit clearAllEmbeddings (gated behind `embed --force`). See
+ * INCIDENT-2026-06-22 §12 + EMBED-LEASE-RENEWAL-DESIGN.md.
+ */
+export class FatalVectorError extends Error {}
+
+export class VecDimensionMismatchError extends FatalVectorError {
+  constructor(public readonly existingDim: number, public readonly requestedDim: number) {
+    super(`Embedding dimension changed: vectors_vec is float[${existingDim}] but the model now returns float[${requestedDim}]. Run 'clawmem embed --force' to clear and rebuild the full vault.`);
+    this.name = "VecDimensionMismatchError";
+  }
+}
+
+export class VecSchemaError extends FatalVectorError {
+  constructor(message: string) {
+    super(message);
+    this.name = "VecSchemaError";
+  }
+}
+
+export class VecModelMismatchError extends FatalVectorError {
+  constructor(public readonly expectedModel: string, public readonly actualModel: string) {
+    super(`Embedding model changed mid-run: the vault is being built with "${expectedModel}" but the endpoint now returns "${actualModel}". Mixing different models in one vector space (even at the same dimension) makes cosine similarity meaningless. Run 'clawmem embed --force' to rebuild with the current model.`);
+    this.name = "VecModelMismatchError";
+  }
+}
+
+// A FatalVectorError so it propagates out of the per-fragment catch and aborts the
+// embed run. Thrown both by cmdEmbed (between fragments) and INSIDE insertEmbedding's
+// write transaction (atomic lease-token fence) when the lease was reclaimed.
+export class EmbedLeaseLostError extends FatalVectorError {
+  constructor() {
+    super("Embedding lease lost (another embed process took over). Re-run 'clawmem embed'.");
+    this.name = "EmbedLeaseLostError";
+  }
+}
+
+/** A held embedding-lease identity, passed into vector mutations so each can verify
+ *  ownership before mutating — a process that lost the lease cannot wipe/recreate/write
+ *  the vector store under the new holder. */
+export type LeaseGuard = { workerName: string; token: string };
+
+/**
+ * Throw EmbedLeaseLostError if the caller no longer holds the named lease. Call as the
+ * FIRST statement inside a write transaction (before any mutation), so the check and
+ * the writes are atomic under SQLite's single-writer serialization — no other holder
+ * can interleave a reclaim between the check and the mutation. No-op when leaseGuard
+ * is omitted (non-embed callers).
+ */
+function assertLeaseHeld(db: Database, leaseGuard?: LeaseGuard): void {
+  if (!leaseGuard) return;
+  const row = db.prepare(`SELECT lease_token FROM worker_leases WHERE worker_name = ?`).get(leaseGuard.workerName) as { lease_token: string } | null;
+  if (!row || row.lease_token !== leaseGuard.token) {
+    throw new EmbedLeaseLostError();
+  }
+}
+
+/**
+ * Single source of truth for vectors_vec schema validation. Reads the table DDL
+ * and returns:
+ *   - null      → table ABSENT
+ *   - <integer> → table VALID (vec0 schema: hash_seq + float[N] + cosine); the N
+ *   - throws VecSchemaError → table PRESENT but its schema is unexpected
+ *     (missing float[N], hash_seq, or distance_metric=cosine; malformed/legacy DDL).
+ * No caching: a stale per-process dim cache could bypass this validation when
+ * another process changed the table. The embed lease serializes embeds, and the
+ * old cache fast-path is removed so validation is unconditional on every call.
+ * Case-insensitive, whitespace-tolerant.
+ */
+function readVecTableDim(db: Database): number | null {
+  const info = db.prepare(`SELECT sql FROM sqlite_master WHERE type='table' AND name='vectors_vec'`).get() as { sql: string } | null;
+  if (!info) return null;
+  const m = info.sql.match(/float\s*\[\s*(\d+)\s*\]/i);
+  const hasHashSeq = /\bhash_seq\b/i.test(info.sql);
+  const hasCosine = /distance_metric\s*=\s*cosine/i.test(info.sql);
+  if (!m || !hasHashSeq || !hasCosine) {
+    throw new VecSchemaError(`vectors_vec exists but its schema is unexpected (need hash_seq + float[N] + distance_metric=cosine): ${info.sql}`);
+  }
+  return parseInt(m[1]!, 10);
+}
+
+function ensureVecTableInternal(db: Database, dimensions: number, leaseGuard?: LeaseGuard): void {
+  const existing = readVecTableDim(db); // null=absent, N=valid, throws VecSchemaError if malformed
+  if (existing !== null) {
+    // NEVER drop an existing table on a dimension mismatch — that silently destroys
+    // the vault's vectors while the metadata-based worklist skips the now-vectorless
+    // docs (INCIDENT-2026-06-22). Throw; the run aborts. Clear+rebuild happens only
+    // via clearAllEmbeddings (`embed --force`).
+    if (existing !== dimensions) throw new VecDimensionMismatchError(existing, dimensions);
+    return; // exists at the right dim + valid schema → nothing to do
+  }
+  // Table absent → create it ATOMICALLY. The lease assertion, a RE-CHECK of absence,
+  // and the CREATE run in ONE immediate-write-lock transaction, so no other process
+  // can clear/recreate between the check and the CREATE (closes the TOCTOU): a process
+  // that lost its lease cannot create an empty table at the wrong dimension under the
+  // new holder, and two creators cannot race. (vec0 CREATE works inside a transaction.)
+  db.transaction(() => {
+    assertLeaseHeld(db, leaseGuard);
+    const recheck = readVecTableDim(db);
+    if (recheck !== null) {
+      // Another holder created it while we waited for the write lock.
+      if (recheck !== dimensions) throw new VecDimensionMismatchError(recheck, dimensions);
       return;
     }
-    db.exec("DROP TABLE IF EXISTS vectors_vec");
-  }
-  db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS vectors_vec USING vec0(hash_seq TEXT PRIMARY KEY, embedding float[${dimensions}] distance_metric=cosine)`);
-  vecTableDimsCache.set(db, dimensions);
+    db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS vectors_vec USING vec0(hash_seq TEXT PRIMARY KEY, embedding float[${dimensions}] distance_metric=cosine)`);
+  }).immediate();
+}
+
+/**
+ * Public accessor for the vectors_vec dimension. Returns null if absent, the
+ * integer dimension if valid, or throws VecSchemaError if the table exists with
+ * a malformed/unexpected schema (see readVecTableDim).
+ */
+export function getVecTableDim(db: Database): number | null {
+  return readVecTableDim(db);
+}
+
+/**
+ * The DISTINCT non-empty embedding models stored in the vault (empty array if no
+ * embeddings exist). Used to detect model drift BETWEEN runs — a different model at
+ * the SAME dimension produces a heterogeneous vector space that dimension checks
+ * cannot catch. Returning ALL distinct models (not just the majority) lets callers
+ * also detect an ALREADY-heterogeneous vault (length > 1) instead of hiding the
+ * minority behind a majority match. The implicit embed path aborts and requires
+ * `embed --force` on any drift.
+ */
+export function getVecModels(db: Database): string[] {
+  // Join to ACTIVE documents so stale/orphaned content_vectors rows (an obsolete
+  // model on an inactive hash, not yet cleaned) cannot trigger a permanent
+  // "mixed models" abort that would block the very cleanup that removes them.
+  const rows = db.prepare(
+    `SELECT DISTINCT cv.model
+     FROM content_vectors cv
+     JOIN documents d ON d.hash = cv.hash AND d.active = 1
+     WHERE cv.model IS NOT NULL AND cv.model != ''
+     ORDER BY cv.model`
+  ).all() as { model: string }[];
+  return rows.map(r => r.model);
 }
 
 // =============================================================================
@@ -959,7 +1099,9 @@ export type Store = {
   db: Database;
   dbPath: string;
   close: () => void;
-  ensureVecTable: (dimensions: number) => void;
+  ensureVecTable: (dimensions: number, leaseGuard?: LeaseGuard) => void;
+  getVecTableDim: () => number | null;
+  getVecModels: () => string[];
 
   // Index health
   getHashesNeedingEmbedding: () => number;
@@ -976,7 +1118,6 @@ export type Store = {
   deleteLLMCache: () => number;
   deleteInactiveDocuments: () => number;
   cleanupOrphanedContent: () => number;
-  cleanupOrphanedVectors: () => number;
   vacuumDatabase: () => void;
 
   // Context
@@ -1025,9 +1166,10 @@ export type Store = {
   // Vector/embedding operations
   getHashesForEmbedding: () => { hash: string; body: string; path: string }[];
   getHashesNeedingFragments: () => { hash: string; body: string; path: string; title: string; collection: string }[];
-  clearAllEmbeddings: () => void;
-  insertEmbedding: (hash: string, seq: number, pos: number, embedding: Float32Array, model: string, embeddedAt: string, fragmentType?: string, fragmentLabel?: string, canonicalId?: string) => void;
-  cleanStaleEmbeddings: () => number;
+  clearAllEmbeddings: (leaseGuard?: LeaseGuard) => void;
+  getVectorConsistency: () => { cvCount: number; vvCount: number; cvMissingVv: number; vvOrphan: number; pending: number };
+  insertEmbedding: (hash: string, seq: number, pos: number, embedding: Float32Array, model: string, embeddedAt: string, fragmentType?: string, fragmentLabel?: string, canonicalId?: string, leaseGuard?: LeaseGuard) => void;
+  cleanStaleEmbeddings: (leaseGuard?: LeaseGuard) => number;
 
   // SAME: Observation metadata
   updateObservationFields: (docPath: string, collectionName: string, fields: { observation_type?: string; facts?: string; narrative?: string; concepts?: string; files_read?: string; files_modified?: string }) => void;
@@ -1052,6 +1194,7 @@ export type Store = {
   snoozeDocument: (collection: string, path: string, until: string | null) => void;
 
   // Embed state tracking
+  markEmbedStart: (hash: string) => void;
   markEmbedSynced: (hash: string) => void;
   markEmbedFailed: (hash: string, error: string) => void;
   getEmbedStats: () => { pending: number; synced: number; failed: number };
@@ -1150,7 +1293,9 @@ export function createStore(dbPath?: string, opts?: { readonly?: boolean; busyTi
     db,
     dbPath: resolvedPath,
     close: () => db.close(),
-    ensureVecTable: (dimensions: number) => ensureVecTableInternal(db, dimensions),
+    ensureVecTable: (dimensions: number, leaseGuard?: LeaseGuard) => ensureVecTableInternal(db, dimensions, leaseGuard),
+    getVecTableDim: () => getVecTableDim(db),
+    getVecModels: () => getVecModels(db),
 
     // Index health
     getHashesNeedingEmbedding: () => getHashesNeedingEmbedding(db),
@@ -1167,7 +1312,6 @@ export function createStore(dbPath?: string, opts?: { readonly?: boolean; busyTi
     deleteLLMCache: () => deleteLLMCache(db),
     deleteInactiveDocuments: () => deleteInactiveDocuments(db),
     cleanupOrphanedContent: () => cleanupOrphanedContent(db),
-    cleanupOrphanedVectors: () => cleanupOrphanedVectors(db),
     vacuumDatabase: () => vacuumDatabase(db),
 
     // Context
@@ -1216,9 +1360,10 @@ export function createStore(dbPath?: string, opts?: { readonly?: boolean; busyTi
     // Vector/embedding operations
     getHashesForEmbedding: () => getHashesForEmbedding(db),
     getHashesNeedingFragments: () => getHashesNeedingFragments(db),
-    clearAllEmbeddings: () => clearAllEmbeddings(db),
-    insertEmbedding: (hash: string, seq: number, pos: number, embedding: Float32Array, model: string, embeddedAt: string, fragmentType?: string, fragmentLabel?: string, canonicalId?: string) => insertEmbedding(db, hash, seq, pos, embedding, model, embeddedAt, fragmentType, fragmentLabel, canonicalId),
-    cleanStaleEmbeddings: () => cleanStaleEmbeddings(db),
+    clearAllEmbeddings: (leaseGuard?: LeaseGuard) => clearAllEmbeddings(db, leaseGuard),
+    getVectorConsistency: () => getVectorConsistency(db),
+    insertEmbedding: (hash: string, seq: number, pos: number, embedding: Float32Array, model: string, embeddedAt: string, fragmentType?: string, fragmentLabel?: string, canonicalId?: string, leaseGuard?: LeaseGuard) => insertEmbedding(db, hash, seq, pos, embedding, model, embeddedAt, fragmentType, fragmentLabel, canonicalId, leaseGuard),
+    cleanStaleEmbeddings: (leaseGuard?: LeaseGuard) => cleanStaleEmbeddings(db, leaseGuard),
 
     // SAME: Observation metadata
     updateObservationFields: (docPath: string, collectionName: string, fields) => updateObservationFieldsFn(db, docPath, collectionName, fields),
@@ -1243,11 +1388,23 @@ export function createStore(dbPath?: string, opts?: { readonly?: boolean; busyTi
     snoozeDocument: (collection: string, path: string, until: string | null) => snoozeDocumentFn(db, collection, path, until),
 
     // Embed state tracking
+    markEmbedStart: (hash: string) => {
+      // Increment embed_attempts exactly ONCE per attempt, at the start, and set
+      // 'pending' so a crash mid-document leaves the doc retryable (and selected by
+      // getHashesNeedingFragments). The completion setters below are state-only — no
+      // further increment — so a start + a failure for the same attempt cannot
+      // double-count the retry budget.
+      db.prepare(`UPDATE documents SET embed_state = 'pending', embed_error = NULL, embed_attempts = COALESCE(embed_attempts, 0) + 1 WHERE hash = ? AND active = 1`).run(hash);
+    },
     markEmbedSynced: (hash: string) => {
-      db.prepare(`UPDATE documents SET embed_state = 'synced' WHERE hash = ? AND active = 1`).run(hash);
+      // Success resets the retry budget: embed_attempts counts CONSECUTIVE failures
+      // of the current content, so a successful (re-)embed must clear it — otherwise
+      // a doc re-embedded many times (repeated content edits) accumulates attempts
+      // and is wrongly excluded by the worklist's `embed_attempts < 3` guard.
+      db.prepare(`UPDATE documents SET embed_state = 'synced', embed_attempts = 0, embed_error = NULL WHERE hash = ? AND active = 1`).run(hash);
     },
     markEmbedFailed: (hash: string, error: string) => {
-      db.prepare(`UPDATE documents SET embed_state = 'failed', embed_error = ?, embed_attempts = COALESCE(embed_attempts, 0) + 1 WHERE hash = ? AND active = 1`).run(error, hash);
+      db.prepare(`UPDATE documents SET embed_state = 'failed', embed_error = ? WHERE hash = ? AND active = 1`).run(error, hash);
     },
     getEmbedStats: () => {
       const stats = db.prepare(`
@@ -1923,51 +2080,9 @@ export function cleanupOrphanedContent(db: Database): number {
   return result.changes;
 }
 
-/**
- * Remove orphaned vector embeddings that are not referenced by any active document.
- * Returns the number of orphaned embedding chunks deleted.
- */
-export function cleanupOrphanedVectors(db: Database): number {
-  // Check if vectors_vec table exists
-  const tableExists = db.prepare(`
-    SELECT name FROM sqlite_master WHERE type='table' AND name='vectors_vec'
-  `).get();
-
-  if (!tableExists) {
-    return 0;
-  }
-
-  // Count orphaned vectors first
-  const countResult = db.prepare(`
-    SELECT COUNT(*) as c FROM content_vectors cv
-    WHERE NOT EXISTS (
-      SELECT 1 FROM documents d WHERE d.hash = cv.hash AND d.active = 1
-    )
-  `).get() as { c: number };
-
-  if (countResult.c === 0) {
-    return 0;
-  }
-
-  // Delete from vectors_vec first
-  db.exec(`
-    DELETE FROM vectors_vec WHERE hash_seq IN (
-      SELECT cv.hash || '_' || cv.seq FROM content_vectors cv
-      WHERE NOT EXISTS (
-        SELECT 1 FROM documents d WHERE d.hash = cv.hash AND d.active = 1
-      )
-    )
-  `);
-
-  // Delete from content_vectors
-  db.exec(`
-    DELETE FROM content_vectors WHERE hash NOT IN (
-      SELECT hash FROM documents WHERE active = 1
-    )
-  `);
-
-  return countResult.c;
-}
+// (Removed cleanupOrphanedVectors — an exposed, unfenced, non-transactional vector
+// mutation with no production caller. Use cleanStaleEmbeddings, which is lease-fenced
+// and atomic. See INCIDENT-2026-06-22 / codex review.)
 
 /**
  * Run VACUUM to reclaim unused space in the database.
@@ -1996,35 +2111,40 @@ export function canonicalDocId(collection: string, path: string): string {
  * to any active document. Also cleans the corresponding vectors_vec rows.
  * Returns the number of stale embeddings removed.
  */
-export function cleanStaleEmbeddings(db: Database): number {
-  // Find orphaned hashes in content_vectors that have no active document
-  const staleRows = db.prepare(`
-    SELECT DISTINCT cv.hash
-    FROM content_vectors cv
-    LEFT JOIN documents d ON d.hash = cv.hash AND d.active = 1
-    WHERE d.id IS NULL
-  `).all() as { hash: string }[];
-
-  if (staleRows.length === 0) return 0;
-
-  const staleHashes = staleRows.map(r => r.hash);
-
-  // Get all hash_seq keys for stale rows to clean vectors_vec
-  const placeholders = staleHashes.map(() => '?').join(',');
-  const staleVecKeys = db.prepare(`
-    SELECT hash || '_' || seq as hash_seq FROM content_vectors WHERE hash IN (${placeholders})
-  `).all(...staleHashes) as { hash_seq: string }[];
-
-  // Delete from vectors_vec
-  if (staleVecKeys.length > 0) {
-    const vecPlaceholders = staleVecKeys.map(() => '?').join(',');
-    db.prepare(`DELETE FROM vectors_vec WHERE hash_seq IN (${vecPlaceholders})`).run(...staleVecKeys.map(r => r.hash_seq));
-  }
+export function cleanStaleEmbeddings(db: Database, leaseGuard?: LeaseGuard): number {
+  // Atomic + lease-fenced: the ownership check and the deletes share one transaction
+  // so a process that lost its lease cannot delete vectors out from under the new holder.
+  return db.transaction(() => {
+    assertLeaseHeld(db, leaseGuard);
+    // Find orphaned hashes in content_vectors that have no active document
+    const staleRows = db.prepare(`
+      SELECT DISTINCT cv.hash
+      FROM content_vectors cv
+      LEFT JOIN documents d ON d.hash = cv.hash AND d.active = 1
+      WHERE d.id IS NULL
+    `).all() as { hash: string }[];
+
+    if (staleRows.length === 0) return 0;
+
+    const staleHashes = staleRows.map(r => r.hash);
+
+    // Get all hash_seq keys for stale rows to clean vectors_vec
+    const placeholders = staleHashes.map(() => '?').join(',');
+    const staleVecKeys = db.prepare(`
+      SELECT hash || '_' || seq as hash_seq FROM content_vectors WHERE hash IN (${placeholders})
+    `).all(...staleHashes) as { hash_seq: string }[];
+
+    // Delete from vectors_vec
+    if (staleVecKeys.length > 0) {
+      const vecPlaceholders = staleVecKeys.map(() => '?').join(',');
+      db.prepare(`DELETE FROM vectors_vec WHERE hash_seq IN (${vecPlaceholders})`).run(...staleVecKeys.map(r => r.hash_seq));
+    }
 
-  // Delete from content_vectors
-  db.prepare(`DELETE FROM content_vectors WHERE hash IN (${placeholders})`).run(...staleHashes);
+    // Delete from content_vectors
+    db.prepare(`DELETE FROM content_vectors WHERE hash IN (${placeholders})`).run(...staleHashes);
 
-  return staleVecKeys.length;
+    return staleVecKeys.length;
+  }).immediate(); // immediate write lock: assert ownership under the lock before the deletes
 }
 
 // =============================================================================
@@ -2410,6 +2530,8 @@ export function reactivateDocument(
   modifiedAt: string
 ): void {
   const safeTitle = (typeof title === "string") ? title : String(title ?? "Untitled");
+  // The reset_embed_on_hash_change trigger resets embed_state/attempts/error iff the
+  // hash actually changes, so re-adding unchanged content preserves its valid vectors.
   db.prepare(`UPDATE documents SET active = 1, title = ?, hash = ?, modified_at = ? WHERE id = ?`)
     .run(safeTitle, hash, modifiedAt, documentId);
 }
@@ -2439,6 +2561,8 @@ export function updateDocument(
   modifiedAt: string
 ): void {
   const safeTitle = (typeof title === "string") ? title : String(title ?? "Untitled");
+  // The reset_embed_on_hash_change trigger resets embed_state/attempts/error when the
+  // hash actually changes, so this only needs to set the content fields.
   db.prepare(`UPDATE documents SET title = ?, hash = ?, modified_at = ? WHERE id = ?`)
     .run(safeTitle, hash, modifiedAt, documentId);
 }
@@ -3305,6 +3429,9 @@ export function getHashesForEmbedding(db: Database): { hash: string; body: strin
 export function getHashesNeedingFragments(db: Database): { hash: string; body: string; path: string; title: string; collection: string }[] {
   // Select docs that either have no fragments at all OR are missing the primary (seq=0) fragment.
   // The seq=0 embedding is critical — surprisal scoring, semantic graph, and health checks depend on it.
+  // Also retry docs left 'pending' (crash mid-doc) or 'failed' (partial fragment failure) so partial
+  // embeds are not permanently silent — bounded by embed_attempts < 3. The OR-branch is parenthesized
+  // so embed_attempts < 3 and d.active = 1 always apply to every selected row (SQL precedence).
   return db.prepare(`
     SELECT d.hash, c.doc as body, MIN(d.path) as path, MIN(d.title) as title, MIN(d.collection) as collection
     FROM documents d
@@ -3312,8 +3439,8 @@ export function getHashesNeedingFragments(db: Database): { hash: string; body: s
     LEFT JOIN content_vectors v ON d.hash = v.hash AND v.fragment_type IS NOT NULL
     LEFT JOIN content_vectors v0 ON d.hash = v0.hash AND v0.seq = 0
     WHERE d.active = 1
-      AND (v.hash IS NULL OR v0.hash IS NULL)
       AND COALESCE(d.embed_attempts, 0) < 3
+      AND ((v.hash IS NULL OR v0.hash IS NULL) OR d.embed_state IN ('pending', 'failed'))
     GROUP BY d.hash
   `).all() as { hash: string; body: string; path: string; title: string; collection: string }[];
 }
@@ -3322,12 +3449,53 @@ export function getHashesNeedingFragments(db: Database): { hash: string; body: s
  * Clear all embeddings from the database (force re-index).
  * Deletes all rows from content_vectors and drops the vectors_vec table.
  */
-export function clearAllEmbeddings(db: Database): void {
-  db.exec(`DELETE FROM content_vectors`);
-  db.exec(`DROP TABLE IF EXISTS vectors_vec`);
-  // Reset embed state so failed docs get retried after force re-embed
-  try { db.exec(`UPDATE documents SET embed_state = 'pending', embed_error = NULL, embed_attempts = 0 WHERE active = 1`); } catch { /* column may not exist yet */ }
-  vecTableDimsCache.delete(db);
+export function clearAllEmbeddings(db: Database, leaseGuard?: LeaseGuard): void {
+  // Atomic: the lease check + DELETE content_vectors + DROP vectors_vec + reset
+  // embed_state all commit together. The in-transaction assertLeaseHeld means a
+  // `--force` process that lost its lease during the endpoint probe cannot wipe the
+  // vault out from under the new holder (the destructive op is the highest-risk
+  // mutation, so it MUST be fenced). A crash/concurrent reader never observes a
+  // half-cleared state.
+  db.transaction(() => {
+    assertLeaseHeld(db, leaseGuard);
+    db.exec(`DELETE FROM content_vectors`);
+    db.exec(`DROP TABLE IF EXISTS vectors_vec`);
+    // Reset embed state so failed docs get retried after force re-embed
+    try { db.exec(`UPDATE documents SET embed_state = 'pending', embed_error = NULL, embed_attempts = 0 WHERE active = 1`); } catch { /* column may not exist yet */ }
+  }).immediate(); // immediate write lock: assert ownership under the lock before this destructive op
+}
+
+/**
+ * Vault-wide content_vectors ↔ vectors_vec consistency snapshot for `doctor`.
+ * Computes BOTH key-set differences (not just counts — one missing + one orphan
+ * cancel in a count check) under a single read transaction so both scans see the
+ * same committed snapshot. Any nonzero cvMissingVv / vvOrphan is an invariant
+ * violation (every content_vectors row must have a vectors_vec entry and vice-versa).
+ * `pending` is reported separately (pending docs are in neither table, so they are
+ * not a desync). See INCIDENT-2026-06-22 §12.
+ */
+export function getVectorConsistency(db: Database): {
+  cvCount: number; vvCount: number; cvMissingVv: number; vvOrphan: number; pending: number;
+} {
+  return db.transaction(() => {
+    const cvKeys = new Set<string>(
+      (db.prepare(`SELECT hash || '_' || seq AS k FROM content_vectors`).all() as { k: string }[]).map(r => r.k)
+    );
+    let vvKeys = new Set<string>();
+    try {
+      vvKeys = new Set<string>(
+        (db.prepare(`SELECT hash_seq FROM vectors_vec`).all() as { hash_seq: string }[]).map(r => r.hash_seq)
+      );
+    } catch { /* vectors_vec absent → empty set (cvMissingVv will surface it) */ }
+    let cvMissingVv = 0;
+    for (const k of cvKeys) if (!vvKeys.has(k)) cvMissingVv++;
+    let vvOrphan = 0;
+    for (const k of vvKeys) if (!cvKeys.has(k)) vvOrphan++;
+    const pending = (db.prepare(
+      `SELECT COUNT(*) AS n FROM documents WHERE active = 1 AND (embed_state = 'pending' OR embed_state IS NULL)`
+    ).get() as { n: number }).n;
+    return { cvCount: cvKeys.size, vvCount: vvKeys.size, cvMissingVv, vvOrphan, pending };
+  })();
 }
 
 /**
@@ -3344,16 +3512,31 @@ export function insertEmbedding(
   embeddedAt: string,
   fragmentType?: string,
   fragmentLabel?: string,
-  canonicalId?: string
+  canonicalId?: string,
+  leaseGuard?: LeaseGuard
 ): void {
   const hashSeq = `${hash}_${seq}`;
-  // vec0 virtual tables don't support INSERT OR REPLACE — delete first if exists.
-  // Try-catch: table may not exist yet during dimension migration (ensureVecTable drops+recreates).
-  try { db.prepare(`DELETE FROM vectors_vec WHERE hash_seq = ?`).run(hashSeq); } catch {}
-  db.prepare(`INSERT INTO vectors_vec (hash_seq, embedding) VALUES (?, ?)`).run(hashSeq, embedding);
-  db.prepare(
-    `INSERT OR REPLACE INTO content_vectors (hash, seq, pos, model, embedded_at, fragment_type, fragment_label, canonical_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
-  ).run(hash, seq, pos, model, embeddedAt, fragmentType ?? null, fragmentLabel ?? null, canonicalId ?? null);
+  // Atomic vec0 + metadata write: the DELETE (vec0's "upsert" — no INSERT OR
+  // REPLACE on vec0), the vector INSERT, and the content_vectors UPSERT commit
+  // together, so an interruption can never leave a vector without its metadata
+  // row or vice-versa (the cv↔vv invariant the doctor check enforces).
+  // ensureVecTable is always called before this and now throws (never drops)
+  // on a dimension mismatch, so vectors_vec reliably exists here — the old
+  // DELETE error-suppression for the "table missing mid-migration" case is gone.
+  //
+  // leaseGuard (optional): an in-transaction embedding-lease fence. The token
+  // check and the writes share ONE transaction, so a process that lost the lease
+  // while awaiting the model (between its loop-level leaseLost check and this
+  // write) cannot commit a stale vector — SQLite serializes the transaction, so
+  // no other holder can interleave a reclaim between the check and the INSERTs.
+  db.transaction(() => {
+    assertLeaseHeld(db, leaseGuard);
+    db.prepare(`DELETE FROM vectors_vec WHERE hash_seq = ?`).run(hashSeq);
+    db.prepare(`INSERT INTO vectors_vec (hash_seq, embedding) VALUES (?, ?)`).run(hashSeq, embedding);
+    db.prepare(
+      `INSERT OR REPLACE INTO content_vectors (hash, seq, pos, model, embedded_at, fragment_type, fragment_label, canonical_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(hash, seq, pos, model, embeddedAt, fragmentType ?? null, fragmentLabel ?? null, canonicalId ?? null);
+  }).immediate(); // immediate write lock: the lease assert reads under the lock, so a lost-lease write can't slip through
 }
 
 // =============================================================================

package/src/worker-lease.ts

@@ -114,6 +114,40 @@ export function releaseWorkerLease(
   return result.changes > 0;
 }
 
+/**
+ * Extend a lease's expiry if the caller's token still owns it. Returns `true`
+ * if THIS holder still owns the lease and the TTL was extended; `false` if the
+ * row is gone or was reclaimed by another token (we lost the lease). A long
+ * embed run renews on a heartbeat well inside its TTL; on a `false` result the
+ * caller MUST abort, because another process now holds the lease and could run
+ * concurrently. Token-fenced like releaseWorkerLease (the UPDATE matches only
+ * our own (worker_name, lease_token) row); any DB error → `false` (fail-safe:
+ * a renewal failure is treated as lease-lost → abort).
+ */
+export function renewWorkerLease(
+  store: Store,
+  workerName: string,
+  token: string,
+  ttlMs: number,
+  now: Date = new Date(),
+): boolean {
+  if (ttlMs <= 0) {
+    throw new Error(`renewWorkerLease: ttlMs must be positive, got ${ttlMs}`);
+  }
+  try {
+    const result = store.db.prepare(
+      `UPDATE worker_leases SET acquired_at = ?, expires_at = ?
+         WHERE worker_name = ? AND lease_token = ?`,
+    ).run(nowIso(now), futureIso(now, ttlMs), workerName, token);
+    return result.changes > 0;
+  } catch (err) {
+    console.error(
+      `[worker-lease] renew error for ${workerName}: ${(err as Error).message}`,
+    );
+    return false;
+  }
+}
+
 /**
  * Run `fn` under an exclusive lease on `workerName`. If the lease cannot
  * be acquired, returns `{acquired: false}` without invoking `fn`. The