total-recall-brain 3.19.2 → 3.20.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.19.2",
+  "version": "3.20.1",
   "description": "Personal AI system — database-free, SSSS-powered intelligence engine deployable to any POSIX host.",
   "type": "module",
   "workspaces": [

package/scaffold/.agent/skills/total-recall/modules/agents/agents.yml

@@ -1,30 +1,66 @@
 agents:
-  - name: antigravity
-    binary: antigravity
-    flags: --sandbox=false --yolo -o json
+  # Google Antigravity CLI. The binary is `agy` (NOT `antigravity`) and it runs
+  # on the AI Ultra plan. Preferred agent for bulk work.
+  #   agy -p "prompt" --output-format json  ->  {status:"SUCCESS", response:"..."}
+  # Docs: https://antigravity.google/docs/cli/headless
+  - name: agy
+    binary: agy
+    flags: --output-format json -p
     priority: 1
     enabled: true
     exec: flag
 
-  - name: grok
-    binary: grok
-    # Grok Build TUI: -p single-turn, plain text for TR parser
-    flags: --output-format plain --always-approve --permission-mode bypassPermissions
-    priority: 2
-    enabled: true
-    exec: flag
-
+  # `-p` MUST be present (non-interactive requires --print) and MUST be LAST:
+  # `--tools` is variadic (`<tools...>`) in the shipped build, so anything after
+  # it — including the appended prompt — is swallowed as a tool name. Proven
+  # both ways on claude v2.1.201.
   - name: claude
     binary: claude
-    flags: --output-format json --permission-mode bypassPermissions --setting-sources local --tools ""
-    priority: 3
+    flags: --output-format json --permission-mode bypassPermissions --setting-sources local --tools "" -p
+    priority: 2
     enabled: true
     exec: flag
+
+  # `-m` is REQUIRED: ~/.codex/config.toml may pin a model the account cannot
+  # use (seen: gpt-5.6-sol -> HTTP 400 "not supported when using Codex with a
+  # ChatGPT account"). Account-supported slugs: ~/.codex/models_cache.json.
+  # `--full-auto` is hidden from --help but still works as a deprecated alias;
+  # the explicit `--sandbox` form is OpenAI's current recommendation.
   - name: codex
     binary: codex
-    flags: --full-auto --json --skip-git-repo-check
-    priority: 4
+    flags: -m gpt-5.5 --sandbox workspace-write --json --skip-git-repo-check
+    priority: 3
     enabled: true
     exec: subcommand
+
+  # DISABLED — `antigravity` on PATH is total-recall/bin/antigravity.mjs, a thin
+  # wrapper that POSTs to generativelanguage.googleapis.com with GOOGLE_API_KEY,
+  # i.e. the METERED Gemini API, not the Ultra plan. Verified 2026-08-01: every
+  # call returned 429 "You exceeded your current quota". Use `agy` above.
+  - name: antigravity
+    binary: antigravity
+    flags: --sandbox=false --yolo -o json
+    priority: 8
+    enabled: false
+    exec: flag
+
+  # DISABLED — this user has no Gemini CLI. Do not enable because a `gemini`
+  # binary resolves on PATH; their Google surface is `agy`.
+  - name: gemini
+    binary: gemini
+    flags: --sandbox=false --yolo -o json
+    priority: 9
+    enabled: false
+    exec: flag
+
+  # DISABLED — not installed. A stale binary may still resolve at
+  # ~/.grok/bin/grok; PATH presence is not proof an agent works.
+  - name: grok
+    binary: grok
+    flags: --output-format plain --always-approve --permission-mode bypassPermissions
+    priority: 10
+    enabled: false
+    exec: flag
+
 timeout: 300
 max_retries: 2

package/src/cli/recall.mjs

@@ -128,6 +128,8 @@ export default async function recall(args) {
     // Search all target brains and merge results
     let allResults = [];
     let isDegraded = false;
+    const searchErrors = [];
+    const degradedReasons = new Map();
 
     for (const target of searchTargets) {
       const vaultDir = path.join(target.brainDir, 'memory-vault');
@@ -162,14 +164,28 @@ export default async function recall(args) {
             priority
           });
         }
-        if (results.degradedTextSearch) isDegraded = true;
+        if (results.degradedTextSearch) {
+          isDegraded = true;
+          degradedReasons.set(results.degradedReason || 'unknown', {
+            label: target.label,
+            detail: results.degradedDetail || '',
+          });
+        }
         // Tag each result with its layer
         for (const r of results) {
           r._layer = target.label;
         }
         allResults = allResults.concat(results);
-      } catch {
-        // Skip brains that can't be searched (no embeddings, etc.)
+      } catch (err) {
+        // A brain that cannot be searched is skipped — but NEVER silently.
+        //
+        // This used to be a bare `catch {}`. A missing native binding for
+        // better-sqlite3 ("Could not locate the bindings file") made every
+        // semantic search throw, and the swallow turned a hard dependency
+        // crash into the message "No matching memory nodes found" — so a
+        // fully-populated vault looked empty and the real cause was invisible.
+        // Degrading to lexical-only results is fine; hiding why is not.
+        searchErrors.push({ label: target.label, message: String(err?.message || err) });
       }
     }
 
@@ -182,16 +198,59 @@ export default async function recall(args) {
       return;
     }
 
+    if (searchErrors.length > 0) {
+      // Surface the real cause. "No matches" and "search crashed" are very
+      // different problems and must never look the same.
+      console.log('');
+      for (const e of searchErrors) {
+        console.log(`  ⚠️  ${e.label} brain search failed: ${e.message.split('\n')[0]}`);
+      }
+      if (/bindings file|\.node|NODE_MODULE_VERSION|better-sqlite3/i.test(searchErrors.map(e => e.message).join(' '))) {
+        console.log('      A native module is missing or was built for a different Node version.');
+        console.log('      Fix: pnpm rebuild better-sqlite3   (or npm rebuild better-sqlite3)');
+        console.log('      With pnpm, the package must also be allowed to run build scripts.');
+      }
+      console.log('      Results below (if any) are lexical-only and may be incomplete.');
+    }
+
     if (allResults.length === 0) {
-      console.log('\n  🔍 No matching memory nodes found.');
+      console.log(
+        searchErrors.length > 0
+          ? '\n  🔍 No results — search failed above, so this is NOT proof the vault is empty.'
+          : '\n  🔍 No matching memory nodes found.',
+      );
       return;
     }
     if (isDegraded) {
-      console.log('\n  ⚠️  WARNING: Embedding API unreachable or unconfigured. Cos-similarity vector search is disabled.');
-      console.log('              Running basic text keyword search instead. Configure GOOGLE_API_KEY or OPENAI_API_KEY.');
+      // This block used to print ONE message for two unrelated failures:
+      // "Embedding API unreachable or unconfigured … Configure GOOGLE_API_KEY
+      // or OPENAI_API_KEY". When the real cause was an unbuilt index, that
+      // sent the reader to check credentials that were already working, while
+      // a brain with thousands of nodes quietly answered from keyword matching
+      // and returned results from the wrong project. Name the actual cause.
+      const empty = degradedReasons.get('empty_index');
+      const failed = degradedReasons.get('embedding_failed');
+
+      console.log('\n  ⚠️  Vector search is OFF — these results are keyword-only and may miss obvious matches.');
+      if (empty) {
+        console.log(`      Cause: the ${empty.label} brain has NO embeddings indexed. The API is fine; the index was never built.`);
+        console.log('      Fix:   npx total-recall compile        (embeds any unembedded nodes for this brain)');
+      }
+      if (failed) {
+        console.log(`      Cause: embedding generation failed for the ${failed.label} brain — ${failed.detail}`);
+        console.log('      Fix:   set OPENROUTER_API_KEY (preferred), or GOOGLE_API_KEY / OPENAI_API_KEY.');
+      }
+      if (!empty && !failed) {
+        console.log('      Cause: unknown — embeddings unavailable and no reason was reported.');
+      }
     }
     const layerSuffix = searchTargets.length > 1 ? ' (merged)' : ` (${searchTargets[0].label})`;
-    console.log(`\n  🔍 Semantic search results for "${query}"${layerSuffix}:\n`);
+    // Never call it "Semantic search results" when semantic search did not run.
+    // The old header said exactly that regardless, so degraded keyword output
+    // was indistinguishable from real vector results — same header, same
+    // percentage scores. If the label doesn't change, nobody can tell.
+    const modeLabel = isDegraded ? '🔤 KEYWORD-ONLY results' : '🔍 Semantic search results';
+    console.log(`\n  ${modeLabel} for "${query}"${layerSuffix}:\n`);
     for (let i = 0; i < allResults.length; i++) {
       const match = allResults[i];
       const rank = i + 1;

package/src/core/config.mjs

@@ -285,7 +285,13 @@ export function detectProjectBrain(startDir = process.cwd()) {
     if (fs.existsSync(path.join(candidate, 'SKILL.md'))) {
       return {
         agentDir: path.join(dir, '.agent'),
-        brainDir: globalBrainDir,
+        // The project brain lives at the detected candidate — NEVER alias it to
+        // globalBrainDir. This returned `globalBrainDir` while the sibling
+        // implementation in src/cli/agent-dir.mjs returned `candidate`, so the
+        // two disagreed about where the project brain is: anything routed
+        // through this function silently operated on the GLOBAL vault while
+        // reporting itself as the 'project' layer.
+        brainDir: candidate,
         projectRoot: dir,
       };
     }

package/src/core/runtime.mjs

@@ -47,11 +47,21 @@ export function findBinaryInPath(binaryName) {
 
 // ─── Default agent registry (used when agents.yml doesn't exist) ─────────────
 
+// NOTE ON FLAG ORDER AND MODEL PINS (verified by live probe 2026-08-01):
+//   agy    — the REAL Google Antigravity CLI (AI Ultra). The binary named
+//            `antigravity` is a metered Gemini API wrapper, NOT this. Disabled
+//            below; enabling it bills an exhausted API budget (429s).
+//   claude — `-p` is required for non-interactive AND must be LAST, because
+//            `--tools` is variadic and otherwise swallows the prompt.
+//   codex  — `-m` must be pinned; a config.toml model the account cannot use
+//            fails with HTTP 400 at exit code 0.
 const DEFAULT_AGENTS = [
-  { name: 'antigravity', binary: 'antigravity', flags: '--sandbox=false --yolo -o json', priority: 1, enabled: true, exec: 'flag' },
-  { name: 'grok',        binary: 'grok',        flags: '--output-format plain --always-approve --permission-mode bypassPermissions', priority: 2, enabled: true, exec: 'flag' },
-  { name: 'claude',      binary: 'claude',      flags: '--output-format json --permission-mode bypassPermissions --setting-sources local --tools ""', priority: 3, enabled: true, exec: 'flag' },
-  { name: 'codex',       binary: 'codex',       flags: '--sandbox workspace-write --json --skip-git-repo-check', priority: 4, enabled: true, exec: 'subcommand' },
+  { name: 'agy',         binary: 'agy',         flags: '--output-format json -p', priority: 1, enabled: true, exec: 'flag' },
+  { name: 'claude',      binary: 'claude',      flags: '--output-format json --permission-mode bypassPermissions --setting-sources local --tools "" -p', priority: 2, enabled: true, exec: 'flag' },
+  { name: 'codex',       binary: 'codex',       flags: '-m gpt-5.5 --sandbox workspace-write --json --skip-git-repo-check', priority: 3, enabled: true, exec: 'subcommand' },
+  { name: 'antigravity', binary: 'antigravity', flags: '--sandbox=false --yolo -o json', priority: 8, enabled: false, exec: 'flag' },
+  { name: 'gemini',      binary: 'gemini',      flags: '--sandbox=false --yolo -o json', priority: 9, enabled: false, exec: 'flag' },
+  { name: 'grok',        binary: 'grok',        flags: '--output-format plain --always-approve --permission-mode bypassPermissions', priority: 10, enabled: false, exec: 'flag' },
 ];
 
 /**
@@ -299,29 +309,65 @@ export async function callLocalRuntime(prompt, system, config) {
     }
   } catch {}
 
-  // Try agents in priority order with retry budget
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    const agent = attempt === 0 ? resolveAgent(config) : resolveAgent({
-      ...config,
-      agents: agents.filter(a => a.name !== lastError?.agentName),
-    });
+  // Try agents in priority order, never re-trying one that already failed.
+  //
+  // The old filter excluded only `lastError.agentName` — the MOST RECENT
+  // failure — so a chain of three could hand work back to an agent that had
+  // already failed while a healthy one further down was never reached. Track
+  // every failure instead.
+  //
+  // The iteration cap is `agents.length + maxRetries` so that each enabled
+  // agent gets a turn even when the retry budget is smaller than the chain;
+  // the loop exits as soon as the untried pool is empty.
+  const failedAgents = new Set();
+  const maxAttempts = agents.length + maxRetries;
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const remaining = agents.filter(a => !failedAgents.has(a.name));
+    const agent = remaining.length > 0
+      ? resolveAgent({ ...config, agents: remaining })
+      : null;
 
     if (!agent) {
-      throw new Error('No CLI agents available. Install antigravity, grok, claude, or codex.');
+      if (failedAgents.size > 0) {
+        throw new Error(
+          `All CLI agents failed (tried: ${[...failedAgents].join(', ')}). ` +
+          `Last error: ${lastError?.error || 'unknown'}`,
+        );
+      }
+      throw new Error(
+        'No CLI agents available. Install agy (Google Antigravity), claude, or codex.',
+      );
     }
 
+    // The prompt goes LAST, after every flag. Pushing it first (the old
+    // behaviour) broke the registry's own flag sets: it emitted a duplicate
+    // `-p` for agents whose flags already carry one, and it defeats the
+    // ordering that keeps a variadic flag (claude's `--tools <tools...>`) from
+    // swallowing the prompt as one of its values.
     const args = [];
     if (agent.exec === 'subcommand') {
-      args.push('exec', fullPrompt);
-    } else {
-      args.push('-p', fullPrompt);
+      args.push('exec');
     }
     if (agent.flags) {
-      args.push(...agent.flags.split(/\s+/).filter(Boolean));
+      // spawnSync does not go through a shell, so quotes in the registry are
+      // literal characters: `--tools ""` would pass a two-character string
+      // rather than an empty one. Strip matched surrounding quotes per token.
+      args.push(
+        ...agent.flags
+          .split(/\s+/)
+          .filter(Boolean)
+          .map(tok => tok.replace(/^(['"])(.*)\1$/, '$2')),
+      );
     }
     if (agent.model) {
       args.push('-m', agent.model);
     }
+    // `exec: flag` agents need an explicit `-p` only if their flags omit it.
+    if (agent.exec !== 'subcommand' && !args.includes('-p') && !args.includes('--print')) {
+      args.push('-p');
+    }
+    args.push(fullPrompt);
 
     const cmd = `${agent.binaryPath} ${args.map(a => a.includes(' ') || a.includes('\n') ? `"${a.replace(/"/g, '\\"')}"` : a).join(' ')}`;
 
@@ -373,11 +419,27 @@ export async function callLocalRuntime(prompt, system, config) {
       cwd: process.cwd(),
     });
 
-    if (result.status === 0) {
+    const softFailure = detectAgentFailure(result.stdout || '');
+
+    if (result.status === 0 && !softFailure) {
       const output = result.stdout?.trim() || '';
       return parseAgentOutput(output);
     }
 
+    if (softFailure) {
+      // Exit code 0 but the payload says the run failed. Auth and model-config
+      // failures are not transient, so record and move to the next agent
+      // instead of burning the remaining retries on the same broken agent.
+      logger.error({
+        subsystem: 'runtime',
+        message: `${agent.name} reported failure despite exit 0`,
+        error: softFailure.slice(0, 500),
+      });
+      lastError = { agentName: agent.name, error: softFailure.slice(0, 500) };
+      failedAgents.add(agent.name);
+      continue;
+    }
+
     const err = result.stderr || result.stdout || 'Unknown error';
     logger.error({
       subsystem: 'runtime',
@@ -385,9 +447,13 @@ export async function callLocalRuntime(prompt, system, config) {
       error: err.slice(0, 500),
     });
     lastError = { agentName: agent.name, error: err.slice(0, 500) };
+    failedAgents.add(agent.name);
   }
 
-  throw new Error(`All CLI agents failed. Last error: ${lastError?.error || 'unknown'}`);
+  throw new Error(
+    `All CLI agents failed (tried: ${[...failedAgents].join(', ') || 'none'}). ` +
+    `Last error: ${lastError?.error || 'unknown'}`,
+  );
 }
 
 /**
@@ -406,6 +472,57 @@ export async function callLocalRuntimeRaw(messages, config, _tools = undefined)
 /**
  * Parse JSON or text output from a CLI agent into plain text.
  */
+/**
+ * Control-frame `type` values in codex's `--json` event stream. None of them
+ * carry the model's answer.
+ */
+const STREAM_CONTROL_TYPES = new Set([
+  'thread.started', 'turn.started', 'turn.completed', 'turn.failed',
+  'item.started', 'item.updated', 'item.completed', 'error',
+]);
+
+/**
+ * Detects a failure the exit code did not report.
+ *
+ * CLI agents exit 0 on failed runs and describe the failure only in the
+ * payload (verified 2026-08-01):
+ *   claude → {"subtype":"success","is_error":true,"result":"Not logged in …"}
+ *   codex  → {"type":"turn.failed","error":{"message":"…"}}
+ *   agy    → {"status":"ERROR"|"CANCELED","error":"…"}
+ *
+ * Without this, `status === 0` accepts the error text as the model's answer —
+ * e.g. "Not logged in · Please run /login" gets stored as a memory node.
+ *
+ * @param {string} output raw stdout
+ * @returns {string|null} failure reason, or null if the run looks clean
+ */
+function detectAgentFailure(output) {
+  if (!output) return null;
+  for (const line of output.split('\n')) {
+    const t = line.trim();
+    if (!t.startsWith('{')) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(t);
+    } catch {
+      continue;
+    }
+    if (parsed.is_error === true) {
+      return typeof parsed.result === 'string' ? parsed.result : 'is_error: true';
+    }
+    if (parsed.type === 'turn.failed' || parsed.type === 'error') {
+      const msg = parsed.error?.message ?? parsed.message;
+      return typeof msg === 'string' ? msg : String(parsed.type);
+    }
+    if (typeof parsed.status === 'string' && parsed.status.toUpperCase() !== 'SUCCESS') {
+      return typeof parsed.error === 'string'
+        ? `${parsed.status}: ${parsed.error}`
+        : `status=${parsed.status}`;
+    }
+  }
+  return null;
+}
+
 function parseAgentOutput(output) {
   try {
     const parsed = JSON.parse(output);
@@ -418,7 +535,34 @@ function parseAgentOutput(output) {
       return last.content || last.text || last.response || JSON.stringify(last);
     }
   } catch {
-    // Not JSON — return raw text
+    // Not a single JSON document. It may still be a JSONL event stream —
+    // codex `--json` emits one frame per line, so a whole-output JSON.parse
+    // always throws and the raw stream used to be returned as the "answer".
+    const answers = [];
+    for (const line of output.split('\n')) {
+      const t = line.trim();
+      if (!t.startsWith('{')) continue;
+      let frame;
+      try {
+        frame = JSON.parse(t);
+      } catch {
+        continue;
+      }
+      // codex: the reply is item.text of the `agent_message` item.
+      if (frame.item?.type === 'agent_message' && typeof frame.item.text === 'string') {
+        answers.push(frame.item.text);
+        continue;
+      }
+      if (STREAM_CONTROL_TYPES.has(frame.type)) continue;
+      for (const key of ['response', 'result', 'content', 'text']) {
+        if (typeof frame[key] === 'string') {
+          answers.push(frame[key]);
+          break;
+        }
+      }
+    }
+    // Last message wins: earlier frames are partial or superseded.
+    if (answers.length > 0) return answers[answers.length - 1];
   }
   return output;
 }

package/src/core/search.mjs

@@ -132,12 +132,22 @@ export async function semanticSearch(query, {
   const filteredSlugs = new Set(filteredNodes.map(n => n.slug));
   const results = [];
 
-  // Get query embedding
+  // Get query embedding.
+  //
+  // Falling back to lexical-only search is fine. Losing the REASON is not:
+  // "the embedding API failed" and "the index for this brain was never built"
+  // are completely different problems with completely different fixes, and
+  // this used to report both as the former. That mislabelling cost real time —
+  // festech.live's project brain had 2602 vault nodes and 0 embeddings, and
+  // every recall against it printed "Embedding API unreachable or
+  // unconfigured. Configure GOOGLE_API_KEY or OPENAI_API_KEY", which sent the
+  // reader off to check credentials that were working perfectly.
   let queryEmbedding = null;
+  let embeddingError = null;
   try {
     queryEmbedding = await getEmbedding(String(query));
   } catch (err) {
-    // Gracefully ignore embedding generation errors
+    embeddingError = String(err?.message || err);
   }
 
   const vaultIndex = loadEmbeddingsIndex(derivedDir);
@@ -279,6 +289,13 @@ export async function semanticSearch(query, {
   const finalResults = results.slice(0, k);
   if (!queryEmbedding || vaultEntries.length === 0) {
     finalResults.degradedTextSearch = true;
+    // Say WHICH failure this is. The caller renders remediation from it, and
+    // the two causes need opposite fixes: one is credentials, the other is an
+    // unbuilt index for this specific brain.
+    finalResults.degradedReason = !queryEmbedding ? 'embedding_failed' : 'empty_index';
+    finalResults.degradedDetail = !queryEmbedding
+      ? (embeddingError || 'embedding provider returned nothing')
+      : `no embeddings indexed for this brain (${derivedDir})`;
   }
 
   return finalResults;

package/src/core/throttled-fetch.mjs

@@ -552,6 +552,23 @@ export function resetGateStats() {
  * Reset internal rate-limit/concurrency state (for testing only).
  */
 export function resetGateStateForTests() {
+  // Tear down policy watchers FIRST. They are module-level singletons that
+  // outlive an individual test, and their callbacks call applyPolicy() +
+  // drainQueue() — so a watcher registered by an earlier test can fire in the
+  // middle of a later one, silently rewriting blockedDomains/domainMinInterval
+  // and draining the queue. That made the firewall-reject and minInterval
+  // tests fail intermittently under full-suite load while passing in
+  // isolation. Closing them here makes each test start from a quiet state.
+  for (const w of [policyWatcher, parentWatcher]) {
+    try {
+      w?.close();
+    } catch {
+      // already closed / never opened
+    }
+  }
+  policyWatcher = null;
+  parentWatcher = null;
+
   gateGeneration += 1;
   globalInFlight = 0;
   domainInFlight.clear();

package/src/server/index.mjs

@@ -187,8 +187,55 @@ app.get('/health', requireAuthOrLocal, async (req, res) => {
   // Check daemon status
   const daemonStatus = getDaemonStatus();
 
+  // Embedding coverage per brain.
+  //
+  // This existed nowhere before, and its absence is exactly why a brain with
+  // 2602 vault nodes and 0 embeddings looked healthy for weeks: compile
+  // reported `compiled: true`, recall returned keyword hits that read like
+  // real results, and nothing anywhere printed "N of M nodes embedded".
+  // Vector search silently off is a CRITICAL failure, not a cosmetic one —
+  // recall answers from the wrong brain and the caller cannot tell.
+  const embeddingCoverage = [];
+  try {
+    const { loadEmbeddingsIndex } = await import('../core/embeddings.mjs');
+    const { getActiveBrains } = await import('../core/config.mjs');
+    const brains = getActiveBrains();
+    for (const b of Object.values(brains)) {
+      if (!b?.brainDir) continue;
+      const vaultPath = path.join(b.brainDir, 'memory-vault');
+      if (!fs.existsSync(vaultPath)) continue;
+      let nodeCount = 0;
+      const walk = (d) => {
+        for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+          if (e.name.startsWith('.')) continue;
+          const p = path.join(d, e.name);
+          if (e.isDirectory()) walk(p);
+          else if (e.name.endsWith('.md')) nodeCount++;
+        }
+      };
+      try { walk(vaultPath); } catch { /* unreadable vault */ }
+      let embedded = 0;
+      try {
+        embedded = Object.keys(loadEmbeddingsIndex(path.join(b.brainDir, 'memory-derived'))).length;
+      } catch { /* index unreadable — reported as 0, which is the honest value */ }
+      embeddingCoverage.push({
+        layer: b.layer || 'unknown',
+        nodes: nodeCount,
+        embedded,
+        vector_search: embedded > 0 ? 'on' : 'OFF — keyword-only',
+      });
+    }
+  } catch (err) {
+    embeddingCoverage.push({ error: String(err?.message || err) });
+  }
+
+  // A brain with nodes but no vectors answers every query from keyword
+  // matching. Surface it at the same severity as a dead daemon.
+  const unembeddedBrains = embeddingCoverage.filter(c => c.nodes > 0 && c.embedded === 0);
+
   // Determine overall status
-  const hasCriticalIssue = emergencyAlerts.length > 0 || daemonStatus === 'dead' || cliAgents.length === 0;
+  const hasCriticalIssue = emergencyAlerts.length > 0 || daemonStatus === 'dead' || cliAgents.length === 0
+    || unembeddedBrains.length > 0;
 
   // Check Caddy and Cloudflare status
   let caddyStatus = 'inactive';
@@ -223,6 +270,12 @@ app.get('/health', requireAuthOrLocal, async (req, res) => {
     disk,
     cli_agents: cliAgents,
     daemon: daemonStatus,
+    embedding_coverage: embeddingCoverage,
+    // Explicit, greppable signal. A brain with nodes and no vectors serves
+    // keyword-only results that look exactly like real ones.
+    vector_search_degraded: unembeddedBrains.length > 0
+      ? unembeddedBrains.map(b => `${b.layer}: ${b.embedded}/${b.nodes} embedded`)
+      : null,
     caddy: caddyStatus,
     cloudflare: cloudflareStatus,
     emergency_alerts: emergencyAlerts || null,

package/src/server/routes/vault.mjs

@@ -15,6 +15,7 @@ import {
 import { compileSurface } from '../../core/surface.mjs';
 import { getNodes, invalidate } from '../../core/vault-cache.mjs';
 import { loadEmbeddingsIndex, loadSessionEmbeddingsIndex } from '../../core/embeddings.mjs';
+import { logger } from '../../core/logger.mjs';
 
 const router = Router();
 
@@ -32,20 +33,30 @@ router.post('/api/vault/compile', requireAuth, requireScope('memory:recompile'),
       force: true,
     });
     // Incrementally embed any new vault nodes and sessions for THIS brain
-    let vaultEmbed = null, sessionEmbed = null;
+    let vaultEmbed = null, sessionEmbed = null, embedError = null;
     try {
       const { buildEmbeddingsIndex, buildSessionEmbeddingsIndex } = await import('../../core/embeddings.mjs');
       invalidate(vaultDir);
       const vaultNodes = getNodes(vaultDir);
       vaultEmbed = await buildEmbeddingsIndex(vaultNodes, paths.derivedDir);
       sessionEmbed = await buildSessionEmbeddingsIndex(paths.sessionsDir, paths.derivedDir);
-    } catch { /* embedding service may be unavailable — non-fatal */ }
+    } catch (err) {
+      // Still non-fatal — a compile that produced surfaces is worth keeping —
+      // but NEVER silent. This was a bare `catch {}`, and it meant every
+      // compile could fail to embed a single node while reporting
+      // `compiled: true`. A brain with thousands of nodes and zero vectors
+      // looked perfectly healthy, and recall silently answered from keyword
+      // matching for weeks.
+      embedError = String(err?.message || err);
+      logger.error('vault', `Embedding build FAILED during compile (surfaces still compiled): ${embedError}`, { vaultDir });
+    }
     res.json({
       compiled: true,
       elapsed_ms: Date.now() - start,
       vault_dir: vaultDir,
       vault_embeddings: vaultEmbed,
       session_embeddings: sessionEmbed,
+      embedding_error: embedError,
     });
   } catch (err) {
     serverError(res, err);