@remnic/core 9.3.664 → 9.3.666

package/src/orchestrator.ts

@@ -245,6 +245,7 @@ import {
   type TrustZoneSearchResult,
 } from "./trust-zones.js";
 import { tryDirectAnswer, type DirectAnswerSources } from "./direct-answer-wiring.js";
+import { resolveCapabilities, type CapabilitySet } from "./capabilities.js";
 import { DEFAULT_TAXONOMY } from "./taxonomy/index.js";
 import {
   searchHarmonicRetrieval,
@@ -1376,6 +1377,13 @@ export function resolveRecallModeDecision(options: RecallModeGraphOptions): Reca
 export async function resolveRecallModeDecisionAsync(
   options: RecallModeGraphOptions & {
     config: PluginConfig;
+    /**
+     * Recall-operation capability gates (issue #1523). OPTIONAL and additive:
+     * the recall orchestrator passes a resolved set, but existing callers that
+     * only pass `config` + planner flags stay backward-compatible — the LLM
+     * planner gate falls back to `config.recallPlannerLlmEnabled` when omitted.
+     */
+    caps?: CapabilitySet;
     hints?: string[];
     llm?: FallbackLlmClient;
     signal?: AbortSignal;
@@ -1384,7 +1392,11 @@ export async function resolveRecallModeDecisionAsync(
   const heuristicDecision = resolveRecallModeDecision(options);
 
   // Planner globally off, or LLM planning not opted into → heuristic only.
-  if (!options.plannerEnabled || !options.config.recallPlannerLlmEnabled) {
+  // Prefer the resolved capability when supplied; otherwise fall back to the
+  // config flag so callers on the old option shape get identical gating.
+  const plannerLlmEnabled =
+    options.caps?.recallPlannerLlm ?? options.config.recallPlannerLlmEnabled;
+  if (!options.plannerEnabled || !plannerLlmEnabled) {
     return heuristicDecision;
   }
 
@@ -1395,6 +1407,7 @@ export async function resolveRecallModeDecisionAsync(
     options.config,
     options.llm,
     options.signal,
+    options.caps,
   );
 
   // Shadow mode: record what the LLM would have chosen but keep the heuristic
@@ -5738,6 +5751,10 @@ export class Orchestrator {
     sessionKey?: string,
     options: RecallInvocationOptions = {},
   ): Promise<string> {
+    // Resolve the recall-operation capability gates ONCE, at the operation
+    // entry, and thread the frozen set down (issue #1523). Never re-read the
+    // migrated flags off `this.config` mid-operation.
+    const caps = resolveCapabilities(this.config);
     const abortController = new AbortController();
     const onAbort = () => {
       abortController.abort();
@@ -5813,7 +5830,7 @@ export class Orchestrator {
       const recallPromise = this.recallInternal(prompt, sessionKey, {
         ...options,
         abortSignal: abortController.signal,
-      });
+      }, caps);
       const RECALL_TIMEOUT_MS = this.config.recallOuterTimeoutMs ?? 75_000;
       if (RECALL_TIMEOUT_MS <= 0) {
         return await recallPromise;
@@ -5837,13 +5854,14 @@ export class Orchestrator {
       // Observation-mode direct-answer tier (issue #518 slice 3c).
       // Runs after the user's recall already succeeded, fire-and-forget,
       // so annotation latency can never delay the caller's response.
-      if (this.config.recallDirectAnswerEnabled && sessionKey) {
+      if (caps.recallDirectAnswer && sessionKey) {
         try {
           this.enqueueDirectAnswerObservation(
             prompt,
             sessionKey,
             options.namespace?.trim() || undefined,
             options.principalOverride,
+            caps,
           );
         } catch (err) {
           log.debug(`direct-answer observation setup failed: ${err}`);
@@ -5912,6 +5930,7 @@ export class Orchestrator {
     sessionKey: string,
     namespaceOverride: string | undefined,
     principalOverride: string | undefined,
+    caps: CapabilitySet,
   ): void {
     const expectedSnapshot = this.lastRecall.get(sessionKey);
     if (expectedSnapshot === null) return;
@@ -5992,6 +6011,7 @@ export class Orchestrator {
             sessionKey,
             observationNamespaces,
             expectedIdentity,
+            caps,
             undefined,
           );
         } catch (err) {
@@ -6007,6 +6027,7 @@ export class Orchestrator {
     expectedIdentity:
       | { writeNonce?: string; traceId?: string; recordedAt?: string }
       | undefined,
+    caps: CapabilitySet,
     _parentAbortSignal?: AbortSignal,
   ): Promise<void> {
     const tierStart = Date.now();
@@ -6091,6 +6112,7 @@ export class Orchestrator {
           query: prompt,
           namespace: ns,
           config: this.config,
+          enabled: caps.recallDirectAnswer,
           sources,
         });
         if (r.eligible && r.winner) {
@@ -7277,6 +7299,7 @@ export class Orchestrator {
     prompt: string,
     sessionKey?: string,
     options: RecallInvocationOptions = {},
+    caps: CapabilitySet = resolveCapabilities(this.config),
   ): Promise<string> {
     const recallStart = Date.now();
     // Backend degradations observed by this recall's QMD searches (#1536):
@@ -7436,11 +7459,10 @@ export class Orchestrator {
     let identityInjectionTruncated = false;
     timings.queryPolicy = `${queryPolicy.promptShape}/${queryPolicy.retrievalBudgetMode}${queryPolicy.skipConversationRecall ? "/skip-conv" : ""}`;
     const recallModeDecisionOptions = {
-      plannerEnabled: this.config.recallPlannerEnabled,
-      graphRecallEnabled: this.config.graphRecallEnabled,
+      plannerEnabled: caps.recallPlanner,
+      graphRecallEnabled: caps.graphRecall,
       multiGraphMemoryEnabled: this.config.multiGraphMemoryEnabled,
-      graphExpandedIntentEnabled:
-        this.config.graphExpandedIntentEnabled === true,
+      graphExpandedIntentEnabled: caps.graphExpandedIntent,
       prompt,
     };
     const requestedMode = options.mode;
@@ -7454,6 +7476,7 @@ export class Orchestrator {
         : await resolveRecallModeDecisionAsync({
             ...recallModeDecisionOptions,
             config: this.config,
+            caps,
             signal: options.abortSignal,
           });
     if (
@@ -7779,7 +7802,7 @@ export class Orchestrator {
       promptLength: prompt.length,
       retrievalQueryHash,
       retrievalQueryLength: retrievalQuery.length,
-      plannerEnabled: this.config.recallPlannerEnabled,
+      plannerEnabled: caps.recallPlanner,
       plannedMode: requestedMode ?? recallDecision.plannedMode,
       effectiveMode: recallMode,
       recallResultLimit,
@@ -7790,7 +7813,7 @@ export class Orchestrator {
         reason: graphDecisionReason,
         shadowMode: graphDecisionShadowMode,
         qmdAvailable,
-        graphRecallEnabled: this.config.graphRecallEnabled,
+        graphRecallEnabled: caps.graphRecall,
         multiGraphMemoryEnabled: this.config.multiGraphMemoryEnabled,
       },
     });
@@ -11012,7 +11035,7 @@ export class Orchestrator {
 
       const isFullModeGraphAssist =
         this.config.multiGraphMemoryEnabled &&
-        this.config.graphAssistInFullModeEnabled !== false &&
+        caps.graphAssistInFullMode &&
         recallMode === "full" &&
         memoryResults.length >=
           Math.max(1, this.config.graphAssistMinSeedResults ?? 3);
@@ -11192,7 +11215,7 @@ export class Orchestrator {
           timeoutMs: this.config.rerankTimeoutMs,
           maxCandidates: this.config.rerankMaxCandidates,
           cache: this.rerankCache,
-          cacheEnabled: this.config.rerankCacheEnabled,
+          cacheEnabled: caps.rerankCache,
           cacheTtlMs: this.config.rerankCacheTtlMs,
         });
         if (ranked && ranked.length > 0) {
@@ -11222,7 +11245,7 @@ export class Orchestrator {
       // flips the default once bench shows tie-or-win. Fail-open: any
       // lookup error leaves the original scores untouched rather than
       // breaking recall for the whole namespace.
-      if (this.config.recallMemoryWorthFilterEnabled && memoryResults.length > 0) {
+      if (caps.recallMemoryWorthFilter && memoryResults.length > 0) {
         try {
           memoryResults = await this.applyMemoryWorthRerank(memoryResults, recallNamespaces);
         } catch (err) {
@@ -11260,7 +11283,7 @@ export class Orchestrator {
         memoryResults.length,
       );
       let confidenceGateRejected = false;
-      if (this.config.recallConfidenceGateEnabled && effectiveGateScore > 0) {
+      if (caps.recallConfidenceGate && effectiveGateScore > 0) {
         if (effectiveGateScore < this.config.recallConfidenceGateThreshold) {
           log.debug(
             `recall: confidence gate rejected ${memoryResults.length} results (effective score ${effectiveGateScore.toFixed(3)} below ${this.config.recallConfidenceGateThreshold})`,
@@ -11278,6 +11301,7 @@ export class Orchestrator {
         memoryResults,
         recallResultLimit,
         retrievalQuery,
+        caps,
       );
 
       // E-Mem-inspired memory reconstruction: fill gaps for referenced entities
@@ -11394,6 +11418,7 @@ export class Orchestrator {
               boostedScoped,
               recallResultLimit,
               retrievalQuery,
+              caps,
             );
           },
           [] as QmdSearchResult[],
@@ -11431,6 +11456,7 @@ export class Orchestrator {
             recallNamespaces,
             recallResultLimit,
             recallMode,
+            caps,
             queryAwarePrefilter,
             abortSignal: options.abortSignal,
             onDegradation: (degradation) => {
@@ -11551,6 +11577,7 @@ export class Orchestrator {
               boostedScoped,
               recallResultLimit,
               retrievalQuery,
+              caps,
             );
           },
           [] as QmdSearchResult[],
@@ -11656,6 +11683,7 @@ export class Orchestrator {
               recallNamespaces,
               recallResultLimit,
               recallMode,
+              caps,
               queryAwarePrefilter,
               abortSignal: options.abortSignal,
               onDegradation: (degradation) => {
@@ -11730,6 +11758,7 @@ export class Orchestrator {
                   boostedRecent,
                   recallResultLimit,
                   retrievalQuery,
+                  caps,
                 );
               },
               [] as QmdSearchResult[],
@@ -11768,6 +11797,7 @@ export class Orchestrator {
                 recallNamespaces,
                 recallResultLimit,
                 recallMode,
+                caps,
                 queryAwarePrefilter,
                 abortSignal: options.abortSignal,
                 onDegradation: (degradation) => {
@@ -11815,6 +11845,7 @@ export class Orchestrator {
             recallNamespaces,
             recallResultLimit,
             recallMode,
+            caps,
             queryAwarePrefilter,
             abortSignal: options.abortSignal,
             onDegradation: (degradation) => {
@@ -18361,6 +18392,11 @@ export class Orchestrator {
     results: QmdSearchResult[],
     limit: number,
     retrievalQuery?: string,
+    // `caps` is additive AND last (issue #1523) so the positional call shape
+    // stays backward-compatible: the recall pipeline threads a resolved set,
+    // but callers that omit it (e.g. direct unit-test invocations) get an
+    // equivalent set derived from the same config — behavior-preserving.
+    caps: CapabilitySet = resolveCapabilities(this.config),
   ): QmdSearchResult[] {
     const safeLimit =
       typeof limit === "number" && Number.isFinite(limit)
@@ -18377,13 +18413,13 @@ export class Orchestrator {
     // facts/decisions before MMR picks the final section. No-op when the
     // flag is off or the query is not a problem-solving ask.
     const boosted =
-      this.config.recallReasoningTraceBoostEnabled && typeof retrievalQuery === "string"
+      caps.recallReasoningTraceBoost && typeof retrievalQuery === "string"
         ? applyReasoningTraceBoost(results, {
             enabled: true,
             query: retrievalQuery,
           })
         : results;
-    const diversified = this.applyMmrToQmdResults(sectionId, boosted);
+    const diversified = this.applyMmrToQmdResults(sectionId, boosted, caps);
     return diversified.slice(0, safeLimit);
   }
 
@@ -18398,8 +18434,11 @@ export class Orchestrator {
   private applyMmrToQmdResults(
     sectionId: string,
     results: QmdSearchResult[],
+    // Additive `caps` (issue #1523); defaults to a config-derived set so direct
+    // callers that omit it behave identically to the threaded recall path.
+    caps: CapabilitySet = resolveCapabilities(this.config),
   ): QmdSearchResult[] {
-    if (this.config.recallMmrEnabled === false) return results;
+    if (!caps.recallMmr) return results;
     if (!Array.isArray(results) || results.length < 2) return results;
 
     // Config is runtime API (see AGENTS.md §4): preserve `0` as a true zero
@@ -18698,6 +18737,13 @@ export class Orchestrator {
     recallNamespaces: string[];
     recallResultLimit: number;
     recallMode: RecallPlanMode;
+    /**
+     * Recall-operation capability gates resolved once at recall entry (#1523).
+     * OPTIONAL and additive: the recall pipeline threads a resolved set, but
+     * callers that omit it (e.g. direct unit-test invocations) get an
+     * equivalent config-derived set — behavior-preserving.
+     */
+    caps?: CapabilitySet;
     queryAwarePrefilter?: QueryAwarePrefilter;
     abortSignal?: AbortSignal;
     /** Backend degradation observer — cold-tier QMD must report like hot (#1536). */
@@ -18717,6 +18763,9 @@ export class Orchestrator {
     /** Issue #681 — when true, bypass graphTraversalConfidenceFloor. */
     includeLowConfidence?: boolean;
   }): Promise<QmdSearchResult[]> {
+    // Prefer the threaded set; fall back to a config-derived set so direct
+    // callers (unit tests) behave identically to the recall pipeline (#1523).
+    const caps = options.caps ?? resolveCapabilities(this.config);
     if (options.queryAwarePrefilter?.candidatePaths?.size === 0) {
       if (options.xrayPoolSizeSink) options.xrayPoolSizeSink.size = 0;
       return [];
@@ -18932,7 +18981,7 @@ export class Orchestrator {
     const isFullModeGraphAssist =
       this.config.qmdTierParityGraphEnabled &&
       this.config.multiGraphMemoryEnabled &&
-      this.config.graphAssistInFullModeEnabled !== false &&
+      caps.graphAssistInFullMode &&
       options.recallMode === "full" &&
       results.length >= Math.max(1, this.config.graphAssistMinSeedResults ?? 3);
     const shouldRunGraphExpansion =
@@ -19028,7 +19077,7 @@ export class Orchestrator {
         timeoutMs: this.config.rerankTimeoutMs,
         maxCandidates: this.config.rerankMaxCandidates,
         cache: this.rerankCache,
-        cacheEnabled: this.config.rerankCacheEnabled,
+        cacheEnabled: caps.rerankCache,
         cacheTtlMs: this.config.rerankCacheTtlMs,
       });
       if (ranked && ranked.length > 0) {
@@ -19054,7 +19103,7 @@ export class Orchestrator {
     // Memory Worth filter — must fire on the cold fallback path too, or the
     // feature flag produces divergent behavior by retrieval path (CLAUDE.md
     // rule 39). Fail-open on lookup errors.
-    if (this.config.recallMemoryWorthFilterEnabled && results.length > 0) {
+    if (caps.recallMemoryWorthFilter && results.length > 0) {
       try {
         results = await this.applyMemoryWorthRerank(results, options.recallNamespaces);
       } catch (err) {
@@ -19079,6 +19128,7 @@ export class Orchestrator {
       results,
       options.recallResultLimit,
       options.prompt,
+      caps,
     );
   }
 

package/src/recall-planner-llm.test.ts

@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import { parseConfig } from "./config.js";
+import { resolveCapabilities } from "./capabilities.js";
 import {
   planRecallModeLLM,
   resolveRecallPlannerLlmOptions,
@@ -40,7 +41,7 @@ test("returns heuristic without calling the LLM when recallPlannerLlmEnabled is
   const captured: Array<Record<string, unknown>> = [];
   const llm = stubLlm({ capturedOptions: captured, result: { mode: "no_recall" } });
 
-  const result = await planRecallModeLLM("what did we decide about auth?", undefined, config, llm);
+  const result = await planRecallModeLLM("what did we decide about auth?", undefined, config, llm, undefined, resolveCapabilities(config));
 
   assert.equal(captured.length, 0, "LLM must not be contacted when disabled");
   assert.equal(result.source, "heuristic");
@@ -54,7 +55,7 @@ test("uses the LLM classification when enabled", async () => {
   const config = parseConfig({ recallPlannerLlmEnabled: true });
   const llm = stubLlm({ result: { mode: "graph_mode", reason: "asks for root cause" }, modelUsed: "anthropic/claude" });
 
-  const result = await planRecallModeLLM("restart the gateway", undefined, config, llm);
+  const result = await planRecallModeLLM("restart the gateway", undefined, config, llm, undefined, resolveCapabilities(config));
 
   assert.equal(result.source, "llm");
   assert.equal(result.mode, "graph_mode");
@@ -74,7 +75,7 @@ test("forwards taskModelChain AND recallPlannerModel in gateway mode (provider-a
   const captured: Array<Record<string, unknown>> = [];
   const llm = stubLlm({ capturedOptions: captured, result: { mode: "minimal" } });
 
-  await planRecallModeLLM("check status", undefined, config, llm);
+  await planRecallModeLLM("check status", undefined, config, llm, undefined, resolveCapabilities(config));
 
   assert.equal(captured.length, 1);
   // recallPlannerModel is tried first (prepended), taskModelChain is the fallback chain.
@@ -97,7 +98,7 @@ test("plugin mode passes only the explicit model, no gateway chain", async () =>
   const captured: Array<Record<string, unknown>> = [];
   const llm = stubLlm({ capturedOptions: captured, result: { mode: "full" } });
 
-  await planRecallModeLLM("summarize the project", undefined, config, llm);
+  await planRecallModeLLM("summarize the project", undefined, config, llm, undefined, resolveCapabilities(config));
 
   assert.equal(captured.length, 1);
   assert.equal(captured[0]?.model, "openai/gpt-5.5");
@@ -109,7 +110,7 @@ test("falls back to heuristic when the LLM throws", async () => {
   const config = parseConfig({ recallPlannerLlmEnabled: true });
   const llm = stubLlm({ throwError: "boom" });
 
-  const result = await planRecallModeLLM("what happened during the outage?", undefined, config, llm);
+  const result = await planRecallModeLLM("what happened during the outage?", undefined, config, llm, undefined, resolveCapabilities(config));
 
   assert.equal(result.source, "heuristic-fallback");
   assert.equal(result.fallbackUsed, true);
@@ -123,7 +124,7 @@ test("falls back to heuristic when the LLM returns no parseable result", async (
   const config = parseConfig({ recallPlannerLlmEnabled: true });
   const llm = stubLlm({ result: null });
 
-  const result = await planRecallModeLLM("how did we get here?", undefined, config, llm);
+  const result = await planRecallModeLLM("how did we get here?", undefined, config, llm, undefined, resolveCapabilities(config));
 
   assert.equal(result.source, "heuristic-fallback");
   assert.equal(result.fallbackUsed, true);
@@ -139,7 +140,7 @@ test("falls back without a network attempt when the chain is empty and the model
   const captured: Array<Record<string, unknown>> = [];
   const llm = stubLlm({ available: false, capturedOptions: captured, result: { mode: "full" } });
 
-  const result = await planRecallModeLLM("anything", undefined, config, llm);
+  const result = await planRecallModeLLM("anything", undefined, config, llm, undefined, resolveCapabilities(config));
 
   assert.equal(captured.length, 0, "no network attempt when nothing is routable");
   assert.equal(result.source, "heuristic-fallback");
@@ -155,7 +156,7 @@ test("attempts the call (and falls back) when a provider-qualified model overrid
   const captured: Array<Record<string, unknown>> = [];
   const llm = stubLlm({ available: false, capturedOptions: captured, result: null });
 
-  const result = await planRecallModeLLM("anything", undefined, config, llm);
+  const result = await planRecallModeLLM("anything", undefined, config, llm, undefined, resolveCapabilities(config));
 
   assert.equal(captured.length, 1, "qualified model override → still attempt the call");
   assert.equal(captured[0]?.model, "openai/gpt-5.5");
@@ -170,7 +171,7 @@ test("an already-aborted recall short-circuits to the heuristic without an LLM c
   const ac = new AbortController();
   ac.abort();
 
-  const result = await planRecallModeLLM("what did we decide?", undefined, config, llm, ac.signal);
+  const result = await planRecallModeLLM("what did we decide?", undefined, config, llm, ac.signal, resolveCapabilities(config));
 
   assert.equal(captured.length, 0, "no LLM call when the recall is already aborted");
   assert.equal(result.source, "heuristic-fallback");
@@ -184,7 +185,7 @@ test("forwards the abort signal into the LLM call (cancellation contract)", asyn
   const llm = stubLlm({ capturedOptions: captured, result: { mode: "minimal" } });
   const ac = new AbortController();
 
-  await planRecallModeLLM("check status", undefined, config, llm, ac.signal);
+  await planRecallModeLLM("check status", undefined, config, llm, ac.signal, resolveCapabilities(config));
 
   assert.equal(captured.length, 1);
   assert.equal(captured[0]?.signal, ac.signal, "recall abort signal must reach FallbackLlmClient");
@@ -195,7 +196,7 @@ test("empty prompts skip the LLM entirely", async () => {
   const captured: Array<Record<string, unknown>> = [];
   const llm = stubLlm({ capturedOptions: captured, result: { mode: "full" } });
 
-  const result = await planRecallModeLLM("   ", undefined, config, llm);
+  const result = await planRecallModeLLM("   ", undefined, config, llm, undefined, resolveCapabilities(config));
 
   assert.equal(captured.length, 0);
   assert.equal(result.mode, "no_recall"); // heuristic returns no_recall for empty

package/src/recall-planner-llm.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 
 import type { PluginConfig, RecallPlanMode } from "./types.js";
+import type { CapabilitySet } from "./capabilities.js";
 import { planRecallMode } from "./intent.js";
 import {
   FallbackLlmClient,
@@ -189,10 +190,15 @@ export async function planRecallModeLLM(
   config: PluginConfig,
   llm?: FallbackLlmClient,
   signal?: AbortSignal,
+  caps?: CapabilitySet,
 ): Promise<RecallPlannerLlmResult> {
   const heuristicMode = planRecallMode(prompt);
 
-  if (!config.recallPlannerLlmEnabled) {
+  // `caps` is OPTIONAL and additive (issue #1523). Prefer the resolved
+  // capability when supplied; fall back to the config flag so existing callers
+  // that pass only `config` keep identical gating.
+  const plannerLlmEnabled = caps?.recallPlannerLlm ?? config.recallPlannerLlmEnabled;
+  if (!plannerLlmEnabled) {
     return heuristicResult(heuristicMode, "heuristic", "llm-disabled", 0, false);
   }
 

package/src/storage-fallback-category-dirs.test.ts

@@ -27,7 +27,7 @@
  */
 
 import assert from "node:assert/strict";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -356,6 +356,155 @@ test("question-queue items written by writeQuestion() do NOT leak into fallback
  * directly with a config object that explicitly disables QMD, proving the disk
  * scan a QMD-disabled deployment relies on returns every category.
  */
+/**
+ * Symlink containment (same walker-hardening class as PR #1563 / issue #1546).
+ *
+ * `collectActiveMemoryPaths()` walks the RECALL_FALLBACK_DIRS category dirs for
+ * the QMD-unavailable filesystem recall fallback. A category dir symlinked
+ * outside `memoryDir` (e.g. `decisions/` -> an external directory) must NOT be
+ * followed — otherwise out-of-store files leak into recall results. The walker
+ * now `lstat`s each dir (skipping symlinks/non-dirs), realpaths it, and asserts
+ * it stays inside the memory root; per entry it skips symlinks and asserts the
+ * file resolves inside the root before including it.
+ */
+test("category dir symlinked outside memoryDir does NOT leak files into fallback recall", async (t) => {
+  if (process.platform === "win32") {
+    t.skip("directory symlink setup is platform-specific");
+    return;
+  }
+  const baseDir = await mkdtemp(path.join(os.tmpdir(), "engram-1497-symlink-dir-"));
+  const outsideDir = await mkdtemp(path.join(os.tmpdir(), "engram-1497-symlink-out-"));
+  const storage = new StorageManager(baseDir);
+  StorageManager.clearAllStaticCaches();
+  storage.invalidateAllMemoriesCacheForDir();
+  try {
+    // A genuine in-store memory that MUST still be recalled.
+    await seedMemory(baseDir, "facts", "real-fact", "fact", "A genuine in-store fact.");
+
+    // An out-of-store memory reachable only via a symlinked category dir.
+    await writeFile(
+      path.join(outsideDir, "leaked.md"),
+      memoryFile("leaked-secret", "decision", "Out-of-store file must never be recalled."),
+      "utf-8",
+    );
+    // `decisions/` is a RECALL_FALLBACK_DIRS category dir; point it outside the store.
+    await symlink(outsideDir, path.join(baseDir, "decisions"), "dir");
+
+    storage.invalidateAllMemoriesCacheForDir();
+    const memories = await storage.readAllMemories();
+    const foundIds = new Set(memories.map((m) => m.frontmatter.id));
+
+    assert.ok(foundIds.has("real-fact"), "the genuine in-store fact must still be recalled");
+    assert.ok(
+      !foundIds.has("leaked-secret"),
+      "a symlinked-out category dir must not leak files into recall",
+    );
+    assert.equal(memories.length, 1, "only the in-store memory should be returned");
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(baseDir, { recursive: true, force: true });
+    await rm(outsideDir, { recursive: true, force: true });
+  }
+});
+
+test("symlinked entry nested inside a category dir does NOT leak into fallback recall", async (t) => {
+  if (process.platform === "win32") {
+    t.skip("directory symlink setup is platform-specific");
+    return;
+  }
+  const baseDir = await mkdtemp(path.join(os.tmpdir(), "engram-1497-symlink-entry-"));
+  const outsideDir = await mkdtemp(path.join(os.tmpdir(), "engram-1497-symlink-entry-out-"));
+  const storage = new StorageManager(baseDir);
+  StorageManager.clearAllStaticCaches();
+  storage.invalidateAllMemoriesCacheForDir();
+  try {
+    // A genuine in-store memory in the same category dir that holds the symlink.
+    await seedMemory(baseDir, "facts", "real-fact", "fact", "A genuine in-store fact.");
+
+    await writeFile(
+      path.join(outsideDir, "leaked.md"),
+      memoryFile("nested-leak", "fact", "Out-of-store nested file must never be recalled."),
+      "utf-8",
+    );
+    // A symlinked *entry* inside facts/ that escapes the store.
+    await symlink(outsideDir, path.join(baseDir, "facts", "escape"), "dir");
+
+    storage.invalidateAllMemoriesCacheForDir();
+    const memories = await storage.readAllMemories();
+    const foundIds = new Set(memories.map((m) => m.frontmatter.id));
+
+    assert.ok(foundIds.has("real-fact"), "the genuine in-store fact must still be recalled");
+    assert.ok(
+      !foundIds.has("nested-leak"),
+      "a symlinked entry escaping the store must not leak files into recall",
+    );
+    assert.equal(memories.length, 1, "only the in-store memory should be returned");
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(baseDir, { recursive: true, force: true });
+    await rm(outsideDir, { recursive: true, force: true });
+  }
+});
+
+/**
+ * Regression for Cursor Bugbot "Poisoned md skips sibling subdirs".
+ *
+ * Per-entry containment/realpath failures must be isolated so they cannot drop
+ * sibling `.md` files or, crucially, the nested-subdir recursion. This asserts
+ * that a category dir which also contains a symlinked-out entry still recurses
+ * into its real nested subdirectory and returns every in-store memory, while
+ * the out-of-store target stays excluded.
+ */
+test("a guarded/skipped sibling entry does NOT drop nested in-store memories", async (t) => {
+  if (process.platform === "win32") {
+    t.skip("directory symlink setup is platform-specific");
+    return;
+  }
+  const baseDir = await mkdtemp(path.join(os.tmpdir(), "engram-1497-sibling-"));
+  const outsideDir = await mkdtemp(path.join(os.tmpdir(), "engram-1497-sibling-out-"));
+  const storage = new StorageManager(baseDir);
+  StorageManager.clearAllStaticCaches();
+  storage.invalidateAllMemoriesCacheForDir();
+  try {
+    const factsDir = path.join(baseDir, "facts");
+    await mkdir(factsDir, { recursive: true });
+    // A top-level in-store memory and a nested in-store memory in the SAME
+    // category dir that also holds the symlinked-out sibling.
+    await writeFile(
+      path.join(factsDir, "top.md"),
+      memoryFile("top-fact", "fact", "Top-level in-store fact."),
+      "utf-8",
+    );
+    await seedMemory(baseDir, "facts", "deep-fact", "fact", "Deeply nested in-store fact.", {
+      nested: true,
+    });
+
+    await writeFile(
+      path.join(outsideDir, "leaked.md"),
+      memoryFile("leaked-secret", "fact", "Out-of-store file must never be recalled."),
+      "utf-8",
+    );
+    // A symlinked-out sibling entry alongside the real files/subdir.
+    await symlink(outsideDir, path.join(factsDir, "escape"), "dir");
+
+    storage.invalidateAllMemoriesCacheForDir();
+    const memories = await storage.readAllMemories();
+    const foundIds = new Set(memories.map((m) => m.frontmatter.id));
+
+    assert.ok(foundIds.has("top-fact"), "the top-level in-store fact must be recalled");
+    assert.ok(
+      foundIds.has("deep-fact"),
+      "the nested in-store fact must still be recalled past a skipped sibling",
+    );
+    assert.ok(!foundIds.has("leaked-secret"), "the symlinked-out file must not leak");
+    assert.equal(memories.length, 2, "exactly the two in-store memories should be returned");
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(baseDir, { recursive: true, force: true });
+    await rm(outsideDir, { recursive: true, force: true });
+  }
+});
+
 test("QMD-disabled deployment: disk-scan collector returns all categories", async () => {
   const baseDir = await mkdtemp(path.join(os.tmpdir(), "engram-1497-qmd-off-"));
   // entitySchemas is the only other constructor arg; QMD is never constructed by