@remnic/core 1.1.31 → 9.3.515

package/src/resolve-provider-secret.ts

@@ -1,23 +1,19 @@
 import { log } from "./logger.js";
 import { readEnvVar } from "./runtime/env.js";
 import path from "node:path";
-import os from "node:os";
 
 /**
- * Resolve a provider API key using OpenClaw's own auth resolution system.
+ * Resolve provider API keys while keeping core host-agnostic.
  *
- * This module delegates to the gateway's `resolveApiKeyForProvider()` function,
- * which handles all secret reference formats (SecretRef objects, auth profiles,
- * "secretref-managed" markers, environment variables, etc.) using the same
- * codepath the gateway uses for its own agent sessions.
+ * Plain-text API keys and provider-derived environment variables are handled
+ * directly. Host-specific secret references are resolved only when the caller
+ * supplies the host's native resolver. Core must not discover OpenClaw, Hermes,
+ * or any other runtime on its own.
  *
- * For plain-text API keys, a fast path returns them directly without
- * involving the gateway auth system.
- *
- * Results are cached per provider for the gateway process lifetime.
+ * Results are cached per provider and resolver context for the process lifetime.
  */
 
-type ResolveApiKeyFn = (params: {
+export type ResolveApiKeyFn = (params: {
   provider: string;
   cfg?: unknown;
   agentDir?: string;
@@ -39,11 +35,16 @@ export type GetRuntimeAuthForModelFn = (params: {
   profileId?: string;
 } | null>;
 
-let _resolveApiKeyForProvider: ResolveApiKeyFn | null = null;
-let _getRuntimeAuthForModel: GetRuntimeAuthForModelFn | null = null;
-let _resolverLoaded = false;
-let _resolverNextRetryAt = 0;
-const RESOLVER_RETRY_BACKOFF_MS = 60_000; // 1 minute between retries after first failure
+export interface ProviderSecretResolutionOptions {
+  resolveApiKeyForProvider?: ResolveApiKeyFn | null;
+}
+
+export interface RuntimeAuthResolutionOptions {
+  getRuntimeAuthForModel?: GetRuntimeAuthForModelFn | null;
+}
+
+let _resolveApiKeyForProviderForTest: ResolveApiKeyFn | null = null;
+let _getRuntimeAuthForModelForTest: GetRuntimeAuthForModelFn | null = null;
 const resolvedCache = new Map<string, string | undefined>();
 const cacheObjectIds = new WeakMap<object, number>();
 let nextCacheObjectId = 1;
@@ -54,180 +55,6 @@ const NON_LITERAL_AUTH_MARKERS = new Set([
 const ENV_VAR_MARKER_RE =
   /^[A-Z][A-Z0-9_]*(?:_API_KEY|_ACCESS_TOKEN|_TOKEN|_SECRET|_CREDENTIALS|_CREDENTIALS_JSON)$/;
 
-/**
- * Lazily load the gateway's resolveApiKeyForProvider function.
- * Returns null if not available (e.g., running outside the gateway process).
- */
-async function getGatewayResolver(): Promise<ResolveApiKeyFn | null> {
-  if (_resolverLoaded) {
-    return _resolveApiKeyForProvider;
-  }
-  // Backoff: don't re-scan filesystem on every call when module wasn't found.
-  // After a failure, wait RESOLVER_RETRY_BACKOFF_MS before trying again.
-  if (_resolverNextRetryAt > 0 && Date.now() < _resolverNextRetryAt) {
-    return null;
-  }
-
-  try {
-    // The gateway bundles this in a runtime chunk — import it dynamically.
-    // This import path is stable across gateway versions since it's a named runtime export.
-    const candidates = [
-      // Try glob-matching the runtime module name (hash varies per build)
-      ...await findRuntimeModules(),
-    ];
-
-    const { pathToFileURL } = await import("node:url");
-    for (const candidate of candidates) {
-      try {
-        // Convert native path to file:// URL for cross-platform ESM import compatibility
-        const importUrl = pathToFileURL(candidate).href;
-        const mod = await import(importUrl);
-        if (typeof mod.resolveApiKeyForProvider === "function") {
-          _resolveApiKeyForProvider = mod.resolveApiKeyForProvider;
-          if (typeof mod.getRuntimeAuthForModel === "function") {
-            _getRuntimeAuthForModel = mod.getRuntimeAuthForModel;
-            log.debug("loaded gateway getRuntimeAuthForModel from runtime module");
-          }
-          _resolverLoaded = true;
-          log.debug("loaded gateway resolveApiKeyForProvider from runtime module");
-          return _resolveApiKeyForProvider;
-        }
-      } catch {
-        // Try next candidate
-      }
-    }
-  } catch {
-    // Silent
-  }
-
-  // Backoff before retrying — avoid repeated fs scanning.
-  // Retries after RESOLVER_RETRY_BACKOFF_MS so the resolver can
-  // recover if the gateway restarts or the module becomes available.
-  _resolverNextRetryAt = Date.now() + RESOLVER_RETRY_BACKOFF_MS;
-  log.debug(`gateway resolveApiKeyForProvider not available — will retry after ${RESOLVER_RETRY_BACKOFF_MS / 1000}s`);
-  return null;
-}
-
-/**
- * Find the gateway's model-auth runtime module by scanning the dist directory.
- * Uses require.resolve to find the openclaw package regardless of install method.
- */
-async function findRuntimeModules(): Promise<string[]> {
-  return findGatewayRuntimeModules("runtime-model-auth.runtime-");
-}
-
-/**
- * Discover gateway runtime module files matching the given filename prefix.
- *
- * Reused by adjacent SecretRef resolution code (`resolve-auth-token.ts`,
- * issue #757). Walks the same dist-dir candidates as the model-auth path
- * so callers don't reimplement install-method discovery.
- */
-export async function findGatewayRuntimeModules(filePrefix: string): Promise<string[]> {
-  const { accessSync, constants, readdirSync, realpathSync, statSync } = await import("node:fs");
-  const { createRequire } = await import("node:module");
-  const candidates: string[] = [];
-
-  const distDirs: string[] = [];
-  const pushDistDirs = (entryPath: string): void => {
-    const resolvedEntryDir = path.dirname(entryPath);
-    const packageRoot = path.basename(resolvedEntryDir) === "dist"
-      ? path.resolve(resolvedEntryDir, "..")
-      : resolvedEntryDir;
-    const candidateDistDirs = [
-      path.join(packageRoot, "dist"),
-      path.join(packageRoot, "..", "dist"),
-    ];
-    for (const candidate of candidateDistDirs) {
-      const resolved = path.resolve(candidate);
-      if (!distDirs.includes(resolved)) distDirs.push(resolved);
-    }
-  };
-
-  try {
-    const req = createRequire(import.meta.url);
-    const openclawMain = req.resolve("openclaw");
-    pushDistDirs(openclawMain);
-  } catch {
-    // openclaw not resolvable from plugin context — try alternate paths
-  }
-
-  try {
-    const mainScript = process.argv[1];
-    if (mainScript) {
-      const realScript = realpathSync(mainScript);
-      if (realScript.includes("openclaw")) {
-        pushDistDirs(realScript);
-      }
-    }
-  } catch {
-    // Silent
-  }
-
-  try {
-    const openclawBin = findExecutableOnPath("openclaw", accessSync, statSync, constants.X_OK);
-    if (openclawBin) {
-      pushDistDirs(realpathSync(openclawBin));
-    }
-  } catch {
-    // Silent
-  }
-
-  for (const dir of distDirs) {
-    try {
-      const files = readdirSync(dir);
-      for (const f of files) {
-        if (f.startsWith(filePrefix) && f.endsWith(".js")) {
-          candidates.push(path.join(dir, f));
-        }
-      }
-    } catch {
-      // Directory doesn't exist — skip
-    }
-  }
-
-  return candidates;
-}
-
-function findExecutableOnPath(
-  executableName: string,
-  access: (path: string, mode?: number) => void,
-  stat: (path: string) => { isFile(): boolean },
-  executableMode: number,
-): string | undefined {
-  const pathEnv = readEnvVar("PATH");
-  if (!pathEnv) return undefined;
-
-  const pathExts = process.platform === "win32"
-    ? (readEnvVar("PATHEXT") ?? ".EXE;.CMD;.BAT;.COM")
-        .split(";")
-        .filter((ext) => ext.length > 0)
-    : [""];
-  const hasExtension = path.extname(executableName).length > 0;
-
-  for (const dir of pathEnv.split(path.delimiter)) {
-    if (!dir) continue;
-    const candidateNames = process.platform === "win32" && !hasExtension
-      ? pathExts.map((ext) => `${executableName}${ext}`)
-      : [executableName];
-
-    for (const candidateName of candidateNames) {
-      const candidate = path.join(dir, candidateName);
-      try {
-        access(candidate, executableMode);
-        if (!stat(candidate).isFile()) continue;
-        return candidate;
-      } catch {
-        // Try the next PATH entry.
-      }
-    }
-  }
-
-  return undefined;
-}
-
-export const __findExecutableOnPathForTest = findExecutableOnPath;
-
 function isNonLiteralAuthMarker(value: string): boolean {
   return (
     NON_LITERAL_AUTH_MARKERS.has(value) ||
@@ -251,37 +78,45 @@ function cacheIdentity(value: unknown): string {
   if (typeof value === "number") return `number:${String(value)}`;
   if (typeof value === "boolean") return `boolean:${String(value)}`;
   if (typeof value === "bigint") return `bigint:${String(value)}`;
-  if (typeof value === "symbol" || typeof value === "function") return typeof value;
+  if (typeof value === "symbol") return typeof value;
+  if (typeof value === "function") return cacheObjectIdentity(value as object);
   if (typeof value === "object") {
-    const existingId = cacheObjectIds.get(value);
-    if (existingId !== undefined) return `object:${existingId}`;
-    const newId = nextCacheObjectId++;
-    cacheObjectIds.set(value, newId);
-    return `object:${newId}`;
+    return cacheObjectIdentity(value);
   }
   return String(value);
 }
 
+function cacheObjectIdentity(value: object): string {
+  const existingId = cacheObjectIds.get(value);
+  if (existingId !== undefined) return `object:${existingId}`;
+  const newId = nextCacheObjectId++;
+  cacheObjectIds.set(value, newId);
+  return `object:${newId}`;
+}
+
 function providerSecretCacheKey(
   providerId: string,
   resolvedAgentDir: string,
   apiKeyValue: unknown,
   gatewayConfig: unknown,
+  resolverContext: unknown,
 ): string {
   return [
     `provider:${providerId}`,
     `agentDir:${resolvedAgentDir}`,
     `apiKey:${cacheIdentity(apiKeyValue)}`,
     `cfg:${cacheIdentity(gatewayConfig)}`,
+    `resolver:${cacheIdentity(resolverContext)}`,
   ].join(":");
 }
 
 /**
- * Resolve a provider API key from various OpenClaw formats.
+ * Resolve a provider API key from literal values, environment markers, or an
+ * injected host resolver.
  *
  * Resolution order:
  * 1. Plain-text string → returned immediately
- * 2. Gateway's resolveApiKeyForProvider → handles all secret ref formats
+ * 2. Injected host resolveApiKeyForProvider → handles host secret ref formats
  * 3. Environment variable fallback (PROVIDER_NAME_API_KEY)
  * 4. undefined → provider is skipped in the fallback chain
  */
@@ -290,10 +125,9 @@ export async function resolveProviderApiKey(
   apiKeyValue: unknown,
   gatewayConfig?: unknown,
   agentDir?: string,
+  options: ProviderSecretResolutionOptions = {},
 ): Promise<string | undefined> {
-  const resolvedAgentDir = path.resolve(
-    agentDir ?? path.join(os.homedir(), ".openclaw", "agents", "main", "agent"),
-  );
+  const resolvedAgentDir = agentDir ? path.resolve(agentDir) : "";
 
   let resolved: string | undefined;
 
@@ -313,26 +147,32 @@ export async function resolveProviderApiKey(
     }
   }
 
-  const cacheKey = providerSecretCacheKey(providerId, resolvedAgentDir, apiKeyValue, gatewayConfig);
+  const resolver = options.resolveApiKeyForProvider ?? _resolveApiKeyForProviderForTest;
+  const cacheKey = providerSecretCacheKey(
+    providerId,
+    resolvedAgentDir,
+    apiKeyValue,
+    gatewayConfig,
+    resolver ?? null,
+  );
   if (resolvedCache.has(cacheKey)) {
     return resolvedCache.get(cacheKey);
   }
 
   // The API key is either a SecretRef object, "secretref-managed", or empty.
-  // Try the gateway's own auth resolution system first.
-  const resolver = await getGatewayResolver();
+  // Try the host-supplied auth resolution system first.
   if (resolver) {
     try {
       const auth = await resolver({ provider: providerId, cfg: gatewayConfig, agentDir: resolvedAgentDir });
       if (auth?.apiKey) {
         resolved = auth.apiKey;
-        log.debug(`resolved API key for provider "${providerId}" via gateway auth (source: ${auth.source ?? "unknown"}, mode: ${auth.mode ?? "unknown"})`);
+        log.debug(`resolved API key for provider "${providerId}" via host auth (source: ${auth.source ?? "unknown"}, mode: ${auth.mode ?? "unknown"})`);
         resolvedCache.set(cacheKey, resolved);
         return resolved;
       }
     } catch (err) {
       log.debug(
-        `gateway auth resolution failed for provider "${providerId}": ${err instanceof Error ? err.message : String(err)}`,
+        `host auth resolution failed for provider "${providerId}": ${err instanceof Error ? err.message : String(err)}`,
       );
     }
   }
@@ -372,16 +212,14 @@ function resolveFromEnv(providerId: string): string | undefined {
 }
 
 /**
- * Get the gateway's getRuntimeAuthForModel function, if available.
+ * Get a host-supplied getRuntimeAuthForModel function, if available.
  * This resolves request-ready auth including provider-owned transforms
  * (OAuth token exchange, base URL override for codex/copilot/etc.).
- * Must be called after at least one resolveProviderApiKey() call to
- * trigger the lazy module load.
  */
-export async function getGatewayRuntimeAuthForModel(): Promise<GetRuntimeAuthForModelFn | null> {
-  // Ensure the runtime module has been loaded
-  await getGatewayResolver();
-  return _getRuntimeAuthForModel;
+export async function getGatewayRuntimeAuthForModel(
+  options: RuntimeAuthResolutionOptions = {},
+): Promise<GetRuntimeAuthForModelFn | null> {
+  return options.getRuntimeAuthForModel ?? _getRuntimeAuthForModelForTest;
 }
 
 /**
@@ -389,22 +227,16 @@ export async function getGatewayRuntimeAuthForModel(): Promise<GetRuntimeAuthFor
  */
 export function clearSecretCache(): void {
   resolvedCache.clear();
-  _resolveApiKeyForProvider = null;
-  _getRuntimeAuthForModel = null;
-  _resolverLoaded = false;
-  _resolverNextRetryAt = 0;
+  _resolveApiKeyForProviderForTest = null;
+  _getRuntimeAuthForModelForTest = null;
 }
 
 export function __setGatewayResolverForTest(resolver: ResolveApiKeyFn | null): void {
-  _resolveApiKeyForProvider = resolver;
-  _resolverLoaded = resolver !== null;
-  _resolverNextRetryAt = 0;
+  _resolveApiKeyForProviderForTest = resolver;
 }
 
 export function __setGatewayRuntimeAuthForModelForTest(
   resolver: GetRuntimeAuthForModelFn | null,
 ): void {
-  _getRuntimeAuthForModel = resolver;
-  _resolverLoaded = resolver !== null || _resolveApiKeyForProvider !== null;
-  _resolverNextRetryAt = 0;
+  _getRuntimeAuthForModelForTest = resolver;
 }

package/src/retrieval-agents.ts

@@ -18,11 +18,12 @@
  */
 
 import path from "node:path";
-import { readdir, readFile, stat } from "node:fs/promises";
+import { lstat, readdir, readFile, realpath, stat } from "node:fs/promises";
 import { log } from "./logger.js";
 import type { QmdSearchResult } from "./types.js";
 import type { QmdClient } from "./qmd.js";
 import { isTemporalQuery, recencyWindowBoundsFromPrompt } from "./temporal-index.js";
+import { isAbortError } from "./abort-error.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -88,6 +89,28 @@ function overlapScore(queryTokens: string[], candidateTokens: string[]): number
   return hits / Math.max(queryTokens.length, candidateTokens.length);
 }
 
+async function resolveContainedRegularFile(
+  memoryDir: string,
+  candidatePath: string,
+  canonicalRoot?: string,
+): Promise<string | null> {
+  try {
+    const root = canonicalRoot ?? await realpath(memoryDir);
+    const absolute = path.isAbsolute(candidatePath)
+      ? path.resolve(candidatePath)
+      : path.resolve(memoryDir, candidatePath);
+    const entryStat = await lstat(absolute);
+    if (entryStat.isSymbolicLink()) return null;
+    const fileStat = await stat(absolute);
+    if (!fileStat.isFile()) return null;
+    const canonical = await realpath(absolute);
+    if (canonical !== root && !canonical.startsWith(root + path.sep)) return null;
+    return absolute;
+  } catch {
+    return null;
+  }
+}
+
 // ─── Agent 1: Direct Facts ───────────────────────────────────────────────────
 
 /**
@@ -106,6 +129,7 @@ export async function runDirectAgent(
   maxResults = 10,
 ): Promise<ParallelSearchResult[]> {
   try {
+    const canonicalRoot = await realpath(memoryDir);
     const entitiesDir = path.join(memoryDir, "entities");
     let entries: string[];
     try {
@@ -128,9 +152,13 @@ export async function runDirectAgent(
       const score = overlapScore(queryTokens, entityTokens);
       if (score <= 0) continue;
 
+      const fullPath = path.join(entitiesDir, entry);
+      const safePath = await resolveContainedRegularFile(memoryDir, fullPath, canonicalRoot);
+      if (!safePath) continue;
+
       results.push({
         docid: nameWithoutExt,
-        path: path.join(entitiesDir, entry),
+        path: safePath,
         snippet: "", // populated by augmentWithDirectAndTemporal after merge
         score,
         transport: "scoped_prefilter",
@@ -168,6 +196,7 @@ export async function runTemporalAgent(
   candidatePaths?: Set<string> | null,
 ): Promise<ParallelSearchResult[]> {
   try {
+    const canonicalRoot = await realpath(memoryDir);
     // Read index_time.json once — used for both date-range filtering and recency scoring.
     let dateIndex: Record<string, string[]> = {};
     try {
@@ -244,17 +273,17 @@ export async function runTemporalAgent(
       : Promise.resolve(new Map<string, string[]>());
 
     // Parallel: existence checks + tag index read.
-    const [existenceResults, pathToTags] = await Promise.all([
-      Promise.all(entries.map(([p]) => stat(p).then(() => true).catch(() => false))),
+    const [safePathResults, pathToTags] = await Promise.all([
+      Promise.all(entries.map(([p]) => resolveContainedRegularFile(memoryDir, p, canonicalRoot))),
       tagIndexPromise,
     ]);
 
     const results: ParallelSearchResult[] = [];
 
     for (let i = 0; i < entries.length; i++) {
-      if (!existenceResults[i]) continue; // skip stale index entry
-
       const [p, dateStr] = entries[i];
+      const safePath = safePathResults[i];
+      if (!safePath) continue; // skip stale or out-of-root index entry
       const ageMs = todayMs - new Date(dateStr).getTime();
       const ageDays = ageMs / 86_400_000;
       // Exponential recency decay with half-life of ~30 days.
@@ -266,7 +295,7 @@ export async function runTemporalAgent(
       // purely temporal (no topic tokens) or the tag index doesn't cover the file.
       let topicBoost = 0;
       if (topicTokens.length > 0) {
-        const tags = pathToTags.get(p);
+        const tags = pathToTags.get(p) ?? pathToTags.get(safePath);
         if (tags && tags.length > 0) {
           const tagSet = new Set(tags.flatMap((t) => tokenize(t)));
           const hits = topicTokens.filter((t) => tagSet.has(t)).length;
@@ -275,11 +304,11 @@ export async function runTemporalAgent(
       }
       const score = recencyScore * (1 + topicBoost * 0.3);
 
-      const baseName = path.basename(p, ".md");
+      const baseName = path.basename(safePath, ".md");
 
       results.push({
         docid: baseName,
-        path: p,
+        path: safePath,
         snippet: "", // populated by augmentWithDirectAndTemporal after merge
         score,
         transport: "scoped_prefilter",
@@ -320,6 +349,7 @@ export async function runContextualAgent(
     );
     return results.map((r: QmdSearchResult) => ({ ...r, agentSource: "contextual" as const }));
   } catch (err) {
+    if (isAbortError(err)) throw err;
     log.debug(`ContextualAgent error: ${err}`);
     return [];
   }
@@ -375,9 +405,10 @@ function stripFrontmatter(raw: string): string {
   return raw.slice(end + 4).replace(/^\n+/, "");
 }
 
-async function populateEmptySnippets(results: QmdSearchResult[]): Promise<QmdSearchResult[]> {
+async function populateEmptySnippets(results: QmdSearchResult[], memoryDir?: string): Promise<QmdSearchResult[]> {
   const needsSnippet = results.filter((r) => !r.snippet && r.path);
   if (needsSnippet.length === 0) return results;
+  const canonicalRoot = memoryDir ? await realpath(memoryDir).catch(() => null) : null;
 
   const toRead = needsSnippet.slice(0, MAX_SNIPPET_READS);
   const snippetMap = new Map<string, string>();
@@ -385,7 +416,11 @@ async function populateEmptySnippets(results: QmdSearchResult[]): Promise<QmdSea
   await Promise.all(
     toRead.map(async (r) => {
       try {
-        const raw = await readFile(r.path, "utf-8");
+        const safePath = canonicalRoot && r.path
+          ? await resolveContainedRegularFile(memoryDir!, r.path, canonicalRoot)
+          : null;
+        if (!safePath) return;
+        const raw = await readFile(safePath, "utf-8");
         // Memory files start with YAML frontmatter — skip it so the snippet
         // contains actual memory content, not metadata fields.
         const body = stripFrontmatter(raw);
@@ -419,6 +454,7 @@ export async function mergeWithAgentResults(
   temporalResults: ParallelSearchResult[],
   weights: Record<SearchAgentSource, number>,
   maxResults: number,
+  memoryDir?: string,
 ): Promise<QmdSearchResult[]> {
   if (directResults.length === 0 && temporalResults.length === 0) {
     return contextualResults.slice(0, maxResults);
@@ -434,7 +470,7 @@ export async function mergeWithAgentResults(
     weights,
     maxResults,
   );
-  return populateEmptySnippets(merged);
+  return populateEmptySnippets(merged, memoryDir);
 }
 
 // ─── Augmentation helper (used by tests; orchestrator uses inline logic) ─────
@@ -542,7 +578,7 @@ export async function augmentWithDirectAndTemporal(
   );
 
   // Populate snippets for results discovered only by direct/temporal (no contextual preview)
-  return populateEmptySnippets(merged);
+  return populateEmptySnippets(merged, memoryDir);
 }
 
 // ─── Orchestrator ─────────────────────────────────────────────────────────────
@@ -601,6 +637,7 @@ export async function parallelRetrieval(
       : Promise.resolve([] as ParallelSearchResult[]),
     runContextual
       ? runContextualAgent(query, qmd, options.collection, maxPerAgent, options.signal).catch((err) => {
+        if (isAbortError(err)) throw err;
         log.debug(`parallelRetrieval: ContextualAgent failed — ${err}`);
         return [] as ParallelSearchResult[];
       })
@@ -619,5 +656,5 @@ export async function parallelRetrieval(
     options.agentWeights ?? PARALLEL_AGENT_WEIGHTS,
     maxResults,
   );
-  return populateEmptySnippets(merged);
+  return populateEmptySnippets(merged, memoryDir);
 }

package/src/review/index.test.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
-import { mkdtemp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import fs from "node:fs";
+import { mkdtemp, mkdir, readFile, rm, stat, symlink, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -48,6 +49,37 @@ test("listReviewItems applies reason filtering before enforcing the limit", asyn
   assert.equal(result.total, 1);
 });
 
+test("listReviewItems stops reading review files after satisfying the limit", async (t) => {
+  const memoryDir = await makeMemoryDir(t);
+  const suggestionsDir = path.join(memoryDir, "suggestions");
+  await mkdir(suggestionsDir, { recursive: true });
+  await writeFile(path.join(suggestionsDir, "001.md"), reviewMarkdown("suggestion-1", "suggestion"), "utf8");
+  await writeFile(path.join(suggestionsDir, "002.md"), reviewMarkdown("suggestion-2", "suggestion"), "utf8");
+  await writeFile(path.join(suggestionsDir, "003.md"), reviewMarkdown("suggestion-3", "suggestion"), "utf8");
+
+  const originalReadFileSync = fs.readFileSync;
+  let reviewFileReads = 0;
+  fs.readFileSync = function readFileSyncWithCount(
+    filePath: fs.PathOrFileDescriptor,
+    options?: BufferEncoding | { encoding?: BufferEncoding | null; flag?: string } | null,
+  ) {
+    if (typeof filePath === "string" && filePath.startsWith(suggestionsDir) && filePath.endsWith(".md")) {
+      reviewFileReads += 1;
+    }
+    return originalReadFileSync.call(fs, filePath, options as never);
+  } as typeof fs.readFileSync;
+
+  try {
+    const result = listReviewItems({ memoryDir, limit: 1 });
+
+    assert.equal(result.items.length, 1);
+    assert.equal(result.total, 1);
+    assert.equal(reviewFileReads, 1);
+  } finally {
+    fs.readFileSync = originalReadFileSync;
+  }
+});
+
 test("flag updates low-confidence category items returned by listReviewItems", async (t) => {
   const memoryDir = await makeMemoryDir(t);
   const factsDir = path.join(memoryDir, "facts", "2026-05-17");
@@ -124,6 +156,48 @@ Reviewed memory.`;
   assert.equal(await readFile(memoryPath, "utf8"), original);
 });
 
+test("review listing and actions ignore symlinked review roots", async (t) => {
+  const memoryDir = await makeMemoryDir(t);
+  const outsideDir = await mkdtemp(path.join(os.tmpdir(), "remnic-review-outside-"));
+  t.after(() => rm(outsideDir, { recursive: true, force: true }));
+  const outsidePath = path.join(outsideDir, "victim.md");
+  await writeFile(outsidePath, reviewMarkdown("victim"), "utf8");
+
+  try {
+    await symlink(outsideDir, path.join(memoryDir, "review"), "dir");
+  } catch {
+    return;
+  }
+
+  assert.deepEqual(listReviewItems({ memoryDir }).items, []);
+  const result = performReview(memoryDir, "victim", "dismiss");
+
+  assert.equal(result.message, "Item not found");
+  assert.equal(await readFile(outsidePath, "utf8"), reviewMarkdown("victim"));
+});
+
+test("review listing and actions ignore symlinked category roots", async (t) => {
+  const memoryDir = await makeMemoryDir(t);
+  const outsideDir = await mkdtemp(path.join(os.tmpdir(), "remnic-review-category-outside-"));
+  t.after(() => rm(outsideDir, { recursive: true, force: true }));
+  const outsideDateDir = path.join(outsideDir, "2026-05-17");
+  await mkdir(outsideDateDir, { recursive: true });
+  const outsidePath = path.join(outsideDateDir, "victim.md");
+  await writeFile(outsidePath, reviewMarkdown("category-victim"), "utf8");
+
+  try {
+    await symlink(outsideDir, path.join(memoryDir, "facts"), "dir");
+  } catch {
+    return;
+  }
+
+  assert.deepEqual(listReviewItems({ memoryDir }).items, []);
+  const result = performReview(memoryDir, "category-victim", "flag");
+
+  assert.equal(result.message, "Item not found");
+  assert.equal(await readFile(outsidePath, "utf8"), reviewMarkdown("category-victim"));
+});
+
 test("review actions can use the same custom confidence threshold as listReviewItems", async (t) => {
   const memoryDir = await makeMemoryDir(t);
   const factsDir = path.join(memoryDir, "facts", "2026-05-17");