@remnic/core 9.3.612 → 9.3.614

package/src/config.test.ts

@@ -3,6 +3,63 @@ import test from "node:test";
 
 import { parseConfig } from "./config.js";
 
+test("parseConfig emitLegacyTools defaults to true and coerces config/env (issue #1427)", () => {
+  // Default: legacy aliases on, for backward compatibility.
+  assert.equal(parseConfig({}).emitLegacyTools, true);
+  // `null` means "unset → use default", consistent with the repo convention for
+  // optional fields (e.g. taskModelChain: null → undefined). Not a hard error.
+  assert.equal(parseConfig({ emitLegacyTools: null }).emitLegacyTools, true);
+  // Boolean + boolean-like string config values.
+  assert.equal(parseConfig({ emitLegacyTools: false }).emitLegacyTools, false);
+  assert.equal(parseConfig({ emitLegacyTools: "false" }).emitLegacyTools, false);
+  assert.equal(parseConfig({ emitLegacyTools: "0" }).emitLegacyTools, false);
+  assert.equal(parseConfig({ emitLegacyTools: "true" }).emitLegacyTools, true);
+
+  // Env var fallback (REMNIC_ preferred, ENGRAM_ legacy) when config field absent.
+  const prevRemnic = process.env.REMNIC_EMIT_LEGACY_TOOLS;
+  const prevEngram = process.env.ENGRAM_EMIT_LEGACY_TOOLS;
+  try {
+    process.env.REMNIC_EMIT_LEGACY_TOOLS = "false";
+    assert.equal(parseConfig({}).emitLegacyTools, false, "REMNIC_ env disables");
+    // Explicit config field wins over env.
+    assert.equal(parseConfig({ emitLegacyTools: true }).emitLegacyTools, true, "config field wins over env");
+    delete process.env.REMNIC_EMIT_LEGACY_TOOLS;
+    process.env.ENGRAM_EMIT_LEGACY_TOOLS = "false";
+    assert.equal(parseConfig({}).emitLegacyTools, false, "ENGRAM_ env fallback disables");
+  } finally {
+    if (prevRemnic === undefined) delete process.env.REMNIC_EMIT_LEGACY_TOOLS;
+    else process.env.REMNIC_EMIT_LEGACY_TOOLS = prevRemnic;
+    if (prevEngram === undefined) delete process.env.ENGRAM_EMIT_LEGACY_TOOLS;
+    else process.env.ENGRAM_EMIT_LEGACY_TOOLS = prevEngram;
+  }
+});
+
+test("parseConfig rejects a present-but-malformed emitLegacyTools (gotcha #51, #1427)", () => {
+  // A typo must fail fast, not silently fall through to the default (true) and
+  // re-enable legacy tool advertising.
+  for (const bad of ["fales", "maybe", 2, "2", "enabled"]) {
+    assert.throws(
+      () => parseConfig({ emitLegacyTools: bad }),
+      /emitLegacyTools must be a boolean-like value/,
+      `emitLegacyTools=${JSON.stringify(bad)} should throw`,
+    );
+  }
+  // Malformed env var also fails fast (only when the config field is absent).
+  const prev = process.env.REMNIC_EMIT_LEGACY_TOOLS;
+  try {
+    process.env.REMNIC_EMIT_LEGACY_TOOLS = "maybe";
+    assert.throws(
+      () => parseConfig({}),
+      /REMNIC_EMIT_LEGACY_TOOLS must be a boolean-like value/,
+    );
+    // An explicit valid config field overrides a malformed env (field wins first).
+    assert.equal(parseConfig({ emitLegacyTools: false }).emitLegacyTools, false);
+  } finally {
+    if (prev === undefined) delete process.env.REMNIC_EMIT_LEGACY_TOOLS;
+    else process.env.REMNIC_EMIT_LEGACY_TOOLS = prev;
+  }
+});
+
 test("parseConfig expands tilde paths for core storage directories", () => {
   const previousHome = process.env.HOME;
   process.env.HOME = "/Users/remnic-test";
@@ -72,6 +129,33 @@ test("parseConfig codex missing entirely → installExtension defaults to true",
   assert.equal(result.codex.installExtension, true);
 });
 
+test("parseConfig recallPlannerLlmEnabled defaults to false and coerces boolean-like strings (opt-in, issue #1367)", () => {
+  assert.equal(parseConfig({}).recallPlannerLlmEnabled, false);
+  assert.equal(parseConfig({ recallPlannerLlmEnabled: true }).recallPlannerLlmEnabled, true);
+  // CLI/env surfaces pass strings — these must enable the gate (gotcha #36).
+  assert.equal(parseConfig({ recallPlannerLlmEnabled: "true" }).recallPlannerLlmEnabled, true);
+  assert.equal(parseConfig({ recallPlannerLlmEnabled: "1" }).recallPlannerLlmEnabled, true);
+  assert.equal(parseConfig({ recallPlannerLlmEnabled: "on" }).recallPlannerLlmEnabled, true);
+  // Boolean-like falses and junk stay off.
+  assert.equal(parseConfig({ recallPlannerLlmEnabled: "false" }).recallPlannerLlmEnabled, false);
+  assert.equal(parseConfig({ recallPlannerLlmEnabled: "0" }).recallPlannerLlmEnabled, false);
+});
+
+test("parseConfig coerces boolean-like strings for all recallPlanner gates (issue #1367, gotcha #36)", () => {
+  // Rollout switches must honor string config from CLI/env surfaces.
+  assert.equal(parseConfig({ recallPlannerShadowMode: "true" }).recallPlannerShadowMode, true);
+  assert.equal(parseConfig({ recallPlannerShadowMode: "off" }).recallPlannerShadowMode, false);
+  assert.equal(parseConfig({}).recallPlannerShadowMode, false);
+
+  assert.equal(parseConfig({ recallPlannerTelemetryEnabled: "false" }).recallPlannerTelemetryEnabled, false);
+  assert.equal(parseConfig({}).recallPlannerTelemetryEnabled, true);
+
+  // The enable gate must be disableable via string "false" (the old `!== false`
+  // check treated "false" as truthy → could not disable).
+  assert.equal(parseConfig({ recallPlannerEnabled: "false" }).recallPlannerEnabled, false);
+  assert.equal(parseConfig({}).recallPlannerEnabled, true);
+});
+
 test("parseConfig dreaming.maxEntries=0 preserves the runtime disable switch", () => {
   const result = parseConfig({ dreaming: { maxEntries: 0 } });
   assert.equal(result.dreaming.maxEntries, 0);
@@ -116,6 +200,59 @@ test("parseConfig initGateTimeoutMs defaults to OpenClaw cold-start budget", ()
   assert.equal(result.initGateTimeoutMs, 30_000);
 });
 
+test("parseConfig qmdSearchStrategy defaults to hybrid and validates the enum", () => {
+  // Default must equal the historical lex+vec+hyde behavior. Issue #1335.
+  assert.equal(parseConfig({}).qmdSearchStrategy, "hybrid");
+  assert.equal(parseConfig({ qmdSearchStrategy: "hybrid" }).qmdSearchStrategy, "hybrid");
+  assert.equal(parseConfig({ qmdSearchStrategy: "lex-vec" }).qmdSearchStrategy, "lex-vec");
+  assert.equal(parseConfig({ qmdSearchStrategy: "lex" }).qmdSearchStrategy, "lex");
+  assert.equal(parseConfig({ qmdSearchStrategy: "LEX" }).qmdSearchStrategy, "lex");
+
+  for (const value of ["hyde", "vec", "bm25", "", 42]) {
+    assert.throws(
+      () => parseConfig({ qmdSearchStrategy: value }),
+      /qmdSearchStrategy must be one of/,
+      `invalid qmdSearchStrategy ${String(value)} should throw`,
+    );
+  }
+});
+
+test("parseConfig qmdSubprocessStrategy defaults to query (honors QMD query intent)", () => {
+  // Default must remain `qmd query` (LLM expansion + rerank) per CLAUDE.md gotcha #7.
+  assert.equal(parseConfig({}).qmdSubprocessStrategy, "query");
+  assert.equal(parseConfig({ qmdSubprocessStrategy: "query" }).qmdSubprocessStrategy, "query");
+  assert.equal(parseConfig({ qmdSubprocessStrategy: "search" }).qmdSubprocessStrategy, "search");
+  assert.equal(parseConfig({ qmdSubprocessStrategy: "SEARCH" }).qmdSubprocessStrategy, "search");
+
+  for (const value of ["bm25", "vsearch", "", 7]) {
+    assert.throws(
+      () => parseConfig({ qmdSubprocessStrategy: value }),
+      /qmdSubprocessStrategy must be one of/,
+      `invalid qmdSubprocessStrategy ${String(value)} should throw`,
+    );
+  }
+});
+
+test("parseConfig qmdDaemonTimeoutMs defaults to 8000 and clamps valid integers", () => {
+  assert.equal(parseConfig({}).qmdDaemonTimeoutMs, 8_000);
+  assert.equal(parseConfig({ qmdDaemonTimeoutMs: 20_000 }).qmdDaemonTimeoutMs, 20_000);
+  assert.equal(parseConfig({ qmdDaemonTimeoutMs: "20000" }).qmdDaemonTimeoutMs, 20_000);
+  // Below floor clamps up; above ceiling clamps down.
+  assert.equal(parseConfig({ qmdDaemonTimeoutMs: 100 }).qmdDaemonTimeoutMs, 1_000);
+  assert.equal(parseConfig({ qmdDaemonTimeoutMs: 999_999 }).qmdDaemonTimeoutMs, 120_000);
+});
+
+test("parseConfig qmdDaemonTimeoutMs rejects non-numeric and non-integer input", () => {
+  // gotcha #51 + codex review on #1422: silent coercion hides config mistakes.
+  for (const value of ["abc", "", 2500.9, "2500.9", Number.NaN, Infinity, true, {}]) {
+    assert.throws(
+      () => parseConfig({ qmdDaemonTimeoutMs: value }),
+      /qmdDaemonTimeoutMs must be an integer/,
+      `invalid qmdDaemonTimeoutMs ${String(value)} should throw`,
+    );
+  }
+});
+
 test("parseConfig initGateTimeoutMs accepts CLI-style numeric strings", () => {
   const result = parseConfig({ initGateTimeoutMs: "45000" });
   assert.equal(result.initGateTimeoutMs, 45_000);
@@ -140,6 +277,82 @@ test("parseConfig modelSource=gateway does not inherit OPENAI_API_KEY from the p
   }
 });
 
+test("parseConfig normalizes taskModelChain", () => {
+  const cfg = parseConfig({
+    taskModelChain: {
+      primary: " openai/cheap-primary ",
+      fallbacks: ["openai/cheap-primary", " fireworks/accounts/fireworks/models/glm-5p1 ", ""],
+    },
+  });
+
+  assert.deepEqual(cfg.taskModelChain, {
+    primary: "openai/cheap-primary",
+    fallbacks: ["fireworks/accounts/fireworks/models/glm-5p1"],
+  });
+});
+
+test("parseConfig treats an absent taskModelChain as not configured", () => {
+  assert.equal(parseConfig({}).taskModelChain, undefined);
+  assert.equal(parseConfig({ taskModelChain: null }).taskModelChain, undefined);
+  assert.equal(parseConfig({ taskModelChain: undefined }).taskModelChain, undefined);
+});
+
+test("parseConfig rejects a present-but-malformed taskModelChain (gotcha #51)", () => {
+  // A typo'd chain must surface loudly instead of silently reverting to defaults.
+  assert.throws(() => parseConfig({ taskModelChain: [] }), /taskModelChain must be an object/);
+  assert.throws(() => parseConfig({ taskModelChain: "openai/x" }), /taskModelChain must be an object/);
+  assert.throws(() => parseConfig({ taskModelChain: { primary: " " } }), /taskModelChain\.primary is required/);
+  assert.throws(() => parseConfig({ taskModelChain: { fallbacks: ["openai/fallback-only"] } }), /taskModelChain\.primary is required/);
+  assert.throws(
+    () => parseConfig({ taskModelChain: { primary: "openai/p", fallbacks: "not-an-array" } }),
+    /taskModelChain\.fallbacks must be an array/,
+  );
+  assert.throws(
+    () => parseConfig({ taskModelChain: { primary: "openai/p", fallbacks: [123] } }),
+    /taskModelChain\.fallbacks must contain only strings/,
+  );
+});
+
+test("parseConfig rejects unqualified taskModelChain model strings (codex review #1425)", () => {
+  // A slash-less id like "gpt-4.1" parses here but FallbackLlmClient.parseModelString
+  // drops it, leaving the chain silently using a different model — reject at parse.
+  assert.throws(
+    () => parseConfig({ taskModelChain: { primary: "gpt-4.1" } }),
+    /taskModelChain\.primary must be in "provider\/model" form/,
+  );
+  assert.throws(
+    () => parseConfig({ taskModelChain: { primary: "openai/" } }),
+    /taskModelChain\.primary must be in "provider\/model" form/,
+  );
+  assert.throws(
+    () => parseConfig({ taskModelChain: { primary: "/gpt-4.1" } }),
+    /taskModelChain\.primary must be in "provider\/model" form/,
+  );
+  assert.throws(
+    () => parseConfig({ taskModelChain: { primary: "openai/gpt", fallbacks: ["bare-model"] } }),
+    /taskModelChain\.fallbacks entries must be in "provider\/model" form/,
+  );
+  // Multi-slash provider/model paths remain valid.
+  assert.deepEqual(
+    parseConfig({
+      taskModelChain: { primary: "fireworks/accounts/fireworks/models/glm-5p1" },
+    }).taskModelChain,
+    { primary: "fireworks/accounts/fireworks/models/glm-5p1" },
+  );
+});
+
+test("parseConfig rejects unknown taskModelChain keys (codex review #1425)", () => {
+  // A misspelled "fallback" must not silently drop the fallback chain.
+  assert.throws(
+    () => parseConfig({ taskModelChain: { primary: "openai/p", fallback: ["openai/q"] } }),
+    /taskModelChain has unknown property: fallback/,
+  );
+  assert.throws(
+    () => parseConfig({ taskModelChain: { primary: "openai/p", fallbackModels: ["openai/q"], extra: 1 } }),
+    /taskModelChain has unknown properties:/,
+  );
+});
+
 test("parseConfig modelSource=gateway still honors an explicit openaiApiKey override", () => {
   const original = process.env.OPENAI_API_KEY;
   process.env.OPENAI_API_KEY = "sk-env-should-not-be-used";

package/src/config.ts

@@ -13,6 +13,7 @@ import type {
   HeartbeatConfig,
   IdentityInjectionMode,
   MemoryOsPresetName,
+  AgentPersonaModelConfig,
   PluginConfig,
   PrincipalRule,
   RecallPipelineConfig,
@@ -69,6 +70,81 @@ function parseBoundedIntegerMs(
   return Math.min(max, Math.max(min, Math.floor(coerced)));
 }
 
+// A gateway model string must be "provider/model" — at least one "/" with a
+// non-empty provider segment and a non-empty model segment. This mirrors
+// FallbackLlmClient.parseModelString (which requires >= 2 slash-parts), so a
+// model the runtime would silently drop is rejected at config time instead.
+function isQualifiedModelString(value: string): boolean {
+  const slash = value.indexOf("/");
+  return slash > 0 && slash < value.length - 1;
+}
+
+function parseModelChainConfig(
+  value: unknown,
+  keyName: string,
+): AgentPersonaModelConfig | undefined {
+  // Absent → not configured (no error).
+  if (value === undefined || value === null) return undefined;
+
+  // Present but malformed → reject loudly rather than silently dropping it,
+  // so a typo'd chain surfaces instead of quietly reverting to defaults
+  // (gotcha #51). Issue #1365 / PR #1370.
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(
+      `${keyName} must be an object like { "primary": "provider/model", "fallbacks": ["provider/model", ...] }; got ${JSON.stringify(value)}`,
+    );
+  }
+  const raw = value as Record<string, unknown>;
+  // Reject unknown keys (matches the manifest's additionalProperties:false) so a
+  // misspelled "fallback"/"fallbackModels" doesn't silently drop the fallback
+  // chain (gotcha #51, codex review #1425).
+  const unknownKeys = Object.keys(raw).filter((k) => k !== "primary" && k !== "fallbacks");
+  if (unknownKeys.length > 0) {
+    throw new Error(
+      `${keyName} has unknown propert${unknownKeys.length === 1 ? "y" : "ies"}: ${unknownKeys.join(", ")}. Allowed: "primary", "fallbacks".`,
+    );
+  }
+  if (typeof raw.primary !== "string" || raw.primary.trim().length === 0) {
+    throw new Error(
+      `${keyName}.primary is required and must be a non-empty "provider/model" string; got ${JSON.stringify(raw.primary)}`,
+    );
+  }
+  const primary = raw.primary.trim();
+  if (!isQualifiedModelString(primary)) {
+    throw new Error(
+      `${keyName}.primary must be in "provider/model" form (e.g. "zai/glm-4.7-flash"); got ${JSON.stringify(primary)}`,
+    );
+  }
+
+  let dedupedFallbacks: string[] | undefined;
+  if (raw.fallbacks !== undefined) {
+    if (!Array.isArray(raw.fallbacks)) {
+      throw new Error(
+        `${keyName}.fallbacks must be an array of "provider/model" strings; got ${JSON.stringify(raw.fallbacks)}`,
+      );
+    }
+    if (raw.fallbacks.some((item) => typeof item !== "string")) {
+      throw new Error(`${keyName}.fallbacks must contain only strings`);
+    }
+    const trimmed = raw.fallbacks
+      .map((item) => (item as string).trim())
+      .filter((item) => item.length > 0 && item !== primary);
+    for (const fb of trimmed) {
+      if (!isQualifiedModelString(fb)) {
+        throw new Error(
+          `${keyName}.fallbacks entries must be in "provider/model" form; got ${JSON.stringify(fb)}`,
+        );
+      }
+    }
+    dedupedFallbacks = [...new Set(trimmed)];
+  }
+
+  return {
+    primary,
+    ...(dedupedFallbacks && dedupedFallbacks.length > 0 ? { fallbacks: dedupedFallbacks } : {}),
+  };
+}
+
 function parsePositiveInteger(value: unknown, keyName: string): number | undefined {
   if (value === undefined || value === null) return undefined;
   const coerced = coerceNumber(value);
@@ -139,6 +215,51 @@ function parseQmdChunkStrategy(value: unknown): "auto" | "regex" {
   throw new Error(`qmdChunkStrategy must be "auto" or "regex"; got ${JSON.stringify(value)}`);
 }
 
+// Issue #1335. Default "hybrid" preserves the historical lex+vec+hyde daemon plan.
+function parseQmdSearchStrategy(value: unknown): "hybrid" | "lex-vec" | "lex" {
+  if (value === undefined || value === null) return "hybrid";
+  if (typeof value !== "string") {
+    throw new Error(
+      `qmdSearchStrategy must be one of "hybrid", "lex-vec", or "lex"; got ${JSON.stringify(value)}`,
+    );
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "hybrid" || normalized === "lex-vec" || normalized === "lex") {
+    return normalized;
+  }
+  throw new Error(
+    `qmdSearchStrategy must be one of "hybrid", "lex-vec", or "lex"; got ${JSON.stringify(value)}`,
+  );
+}
+
+// Issue #1335. Reject non-numeric / non-integer timeouts rather than silently
+// coercing them (gotcha #51), then clamp valid integers to the documented bounds.
+function parseQmdDaemonTimeoutMs(value: unknown): number {
+  if (value === undefined || value === null) return 8_000;
+  const coerced = coerceNumber(value);
+  if (coerced === undefined || !Number.isInteger(coerced)) {
+    throw new Error(
+      `qmdDaemonTimeoutMs must be an integer number of milliseconds between 1000 and 120000; got ${JSON.stringify(value)}`,
+    );
+  }
+  return Math.min(120_000, Math.max(1_000, coerced));
+}
+
+// Issue #1335. Default "query" keeps `qmd query` (LLM expansion + rerank) per gotcha #7.
+function parseQmdSubprocessStrategy(value: unknown): "query" | "search" {
+  if (value === undefined || value === null) return "query";
+  if (typeof value !== "string") {
+    throw new Error(
+      `qmdSubprocessStrategy must be one of "query" or "search"; got ${JSON.stringify(value)}`,
+    );
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "query" || normalized === "search") return normalized;
+  throw new Error(
+    `qmdSubprocessStrategy must be one of "query" or "search"; got ${JSON.stringify(value)}`,
+  );
+}
+
 function parseOptionalNonEmptyString(value: unknown): string | undefined {
   if (typeof value !== "string") return undefined;
   const normalized = value.trim();
@@ -230,6 +351,38 @@ function coerceBooleanLike(value: unknown): boolean | undefined {
   return undefined;
 }
 
+/**
+ * Resolve the `emitLegacyTools` opt-out (issue #1427): config field wins, then
+ * the REMNIC_/ENGRAM_ env var, then default true. A *present-but-malformed*
+ * value fails fast rather than silently re-enabling legacy aliases — this knob
+ * controls the advertised MCP `tools/list` surface, so a typo like
+ * `emitLegacyTools=fales` must not be misread as `true` (gotcha #51).
+ */
+function resolveEmitLegacyTools(configValue: unknown): boolean {
+  const ACCEPTED = "true/false/1/0/yes/no/on/off";
+  if (configValue !== undefined && configValue !== null) {
+    const coerced = coerceBooleanLike(configValue);
+    if (coerced === undefined) {
+      throw new Error(
+        `emitLegacyTools must be a boolean-like value (${ACCEPTED}); got ${JSON.stringify(configValue)}`,
+      );
+    }
+    return coerced;
+  }
+  const envRaw =
+    readEnvVar("REMNIC_EMIT_LEGACY_TOOLS") ?? readEnvVar("ENGRAM_EMIT_LEGACY_TOOLS");
+  if (envRaw !== undefined) {
+    const coerced = coerceBooleanLike(envRaw);
+    if (coerced === undefined) {
+      throw new Error(
+        `REMNIC_EMIT_LEGACY_TOOLS must be a boolean-like value (${ACCEPTED}); got "${envRaw}"`,
+      );
+    }
+    return coerced;
+  }
+  return true;
+}
+
 export function isOpenaiApiKeyDisabled(value: unknown): boolean {
   return value === false || (typeof value === "string" && value.trim().toLowerCase() === "false");
 }
@@ -1379,6 +1532,9 @@ export function parseConfig(raw: unknown): PluginConfig {
     qmdChunkStrategy: parseQmdChunkStrategy(cfg.qmdChunkStrategy),
     qmdCandidateLimit: parsePositiveInteger(cfg.qmdCandidateLimit, "qmdCandidateLimit"),
     qmdQueryRerankEnabled: coerceBooleanLike(cfg.qmdQueryRerankEnabled) ?? true,
+    qmdSearchStrategy: parseQmdSearchStrategy(cfg.qmdSearchStrategy),
+    qmdSubprocessStrategy: parseQmdSubprocessStrategy(cfg.qmdSubprocessStrategy),
+    qmdDaemonTimeoutMs: parseQmdDaemonTimeoutMs(cfg.qmdDaemonTimeoutMs),
     qmdIndexName: parseOptionalNonEmptyString(cfg.qmdIndexName),
     qmdForceCpu: coerceBooleanLike(cfg.qmdForceCpu) ?? false,
     qmdGpuBackend: parseQmdGpuBackend(cfg.qmdGpuBackend),
@@ -2377,6 +2533,7 @@ export function parseConfig(raw: unknown): PluginConfig {
       typeof cfg.fastGatewayAgentId === "string" && cfg.fastGatewayAgentId.length > 0
         ? cfg.fastGatewayAgentId
         : "",
+    taskModelChain: parseModelChainConfig(cfg.taskModelChain, "taskModelChain"),
 
     // v3.0 namespaces (default off)
     namespacesEnabled: cfg.namespacesEnabled === true,
@@ -2716,20 +2873,30 @@ export function parseConfig(raw: unknown): PluginConfig {
           .filter((param): param is string => typeof param === "string" && param.trim().length > 0)
       : [...DEFAULT_BEHAVIOR_LOOP_PROTECTED_PARAMS],
     // v8.0 phase 1
-    recallPlannerEnabled: cfg.recallPlannerEnabled !== false,
+    // All recallPlanner boolean gates coerce boolean-like strings so CLI/env
+    // surfaces (`--config recallPlanner*=true|false`) behave correctly — the
+    // shadow-mode/telemetry/enable flags are documented rollout switches and
+    // must not silently ignore string values (gotcha #36, #1428 review).
+    recallPlannerEnabled: coerceBooleanLike(cfg.recallPlannerEnabled) ?? true,
+    // Issue #1367 / Option C: LLM-based recall planning is opt-in so the
+    // default recall path stays heuristic (no added latency / LLM call unless
+    // the operator asks for it — gotcha #30). Coerce boolean-like strings so
+    // CLI/env surfaces (`--config recallPlannerLlmEnabled=true`) actually
+    // enable it (gotcha #36); defaults off.
+    recallPlannerLlmEnabled: coerceBooleanLike(cfg.recallPlannerLlmEnabled) ?? false,
     recallPlannerModel:
       typeof cfg.recallPlannerModel === "string" && cfg.recallPlannerModel.trim().length > 0
         ? cfg.recallPlannerModel.trim()
         : DEFAULT_REASONING_MODEL,
     recallPlannerTimeoutMs:
       typeof cfg.recallPlannerTimeoutMs === "number" ? cfg.recallPlannerTimeoutMs : 1500,
-    recallPlannerUseResponsesApi: cfg.recallPlannerUseResponsesApi !== false,
+    recallPlannerUseResponsesApi: coerceBooleanLike(cfg.recallPlannerUseResponsesApi) ?? true,
     recallPlannerMaxPromptChars:
       typeof cfg.recallPlannerMaxPromptChars === "number" ? cfg.recallPlannerMaxPromptChars : 4000,
     recallPlannerMaxMemoryHints:
       typeof cfg.recallPlannerMaxMemoryHints === "number" ? cfg.recallPlannerMaxMemoryHints : 24,
-    recallPlannerShadowMode: cfg.recallPlannerShadowMode === true,
-    recallPlannerTelemetryEnabled: cfg.recallPlannerTelemetryEnabled !== false,
+    recallPlannerShadowMode: coerceBooleanLike(cfg.recallPlannerShadowMode) ?? false,
+    recallPlannerTelemetryEnabled: coerceBooleanLike(cfg.recallPlannerTelemetryEnabled) ?? true,
     recallPlannerMaxQmdResultsMinimal:
       typeof cfg.recallPlannerMaxQmdResultsMinimal === "number"
         ? cfg.recallPlannerMaxQmdResultsMinimal
@@ -3422,6 +3589,10 @@ export function parseConfig(raw: unknown): PluginConfig {
         ? cfg.binaryLifecycleBackendPath.trim()
         : "",
 
+    // Legacy MCP tool aliases opt-out (issue #1427). Config field wins; then
+    // the REMNIC_/ENGRAM_ env var (gotcha #9); default true for back-compat.
+    // Malformed values fail fast rather than silently defaulting (gotcha #51).
+    emitLegacyTools: resolveEmitLegacyTools(cfg.emitLegacyTools),
     // Codex citation parity (issue #379)
     citationsEnabled: cfg.citationsEnabled === true,
     citationsAutoDetect: cfg.citationsAutoDetect !== false,

package/src/connectors/codex-materialize-runner.ts

@@ -70,8 +70,9 @@ export async function runCodexMaterialize(
   }
 
   // Per-trigger gate: session-end runs must honor codexMaterializeOnSessionEnd.
-  // session-end.sh passes reason="session_end"; when the user has turned off the
-  // session-end trigger we short-circuit here without touching disk.
+  // The Codex Stop hook (remnic-codex-hook.cjs, session-end event) passes
+  // reason="session_end"; when the user has turned off the session-end trigger
+  // we short-circuit here without touching disk.
   if (options.reason === "session_end" && cfg.codexMaterializeOnSessionEnd === false) {
     log.debug(
       `[codex-materialize] skipped — session-end disabled via codexMaterializeOnSessionEnd=false`,
@@ -199,8 +200,10 @@ function resolveNamespaceDir(
 ): string {
   if (!cfg.namespacesEnabled) return memoryDir;
 
-  const defaultNamespace = (cfg.defaultNamespace ?? "").trim();
-  const ns = (namespace || defaultNamespace || "default").trim();
+  const configuredDefaultNamespace = (cfg.defaultNamespace ?? "").trim();
+  const defaultNamespace =
+    configuredDefaultNamespace.length > 0 ? configuredDefaultNamespace : "default";
+  const ns = (namespace || defaultNamespace).trim();
   if (!isSafeRouteNamespace(ns)) {
     throw new Error(`invalid materialize namespace: ${ns}`);
   }

package/src/consolidation-provenance-check.ts

@@ -18,7 +18,7 @@
  */
 
 import path from "node:path";
-import { access, readdir, readFile, stat } from "node:fs/promises";
+import { lstat, readdir, readFile, realpath, stat } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
 import type { StorageManager } from "./storage.js";
 import {
@@ -499,7 +499,7 @@ export async function runConsolidationProvenanceCheck(options: {
     const scanRoots = ["facts", "corrections", "procedures", "reasoning-traces"];
     for (const rootName of scanRoots) {
       const rootPath = path.join(memoryDir, rootName);
-      for await (const file of walkMarkdownFiles(rootPath)) {
+      for await (const file of walkMarkdownFiles(rootPath, memoryDir)) {
         if (seenPaths.has(file)) continue;
         try {
           const raw = await readFile(file, "utf-8");
@@ -531,21 +531,40 @@ export async function runConsolidationProvenanceCheck(options: {
 /**
  * Recursively yield all `.md` file paths under `root`.  Silent on
  * missing directories — the facts/corrections dirs may not exist in
- * fresh installs.
+ * fresh installs.  Symlinked roots/directories are skipped so the
+ * best-effort parse-failure pass cannot escape `memoryDir`.
  */
-async function* walkMarkdownFiles(root: string): AsyncGenerator<string> {
+async function* walkMarkdownFiles(root: string, memoryDir: string): AsyncGenerator<string> {
   let entries;
+  let memoryDirReal: string;
   try {
+    const rootStat = await lstat(root);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) return;
+    memoryDirReal = await realpath(memoryDir);
+    const rootReal = await realpath(root);
+    if (!isPathWithin(rootReal, memoryDirReal)) return;
     entries = await readdir(root, { withFileTypes: true });
   } catch {
     return;
   }
   for (const entry of entries) {
     const full = path.join(root, entry.name);
+    if (entry.isSymbolicLink()) continue;
     if (entry.isDirectory()) {
-      yield* walkMarkdownFiles(full);
+      yield* walkMarkdownFiles(full, memoryDirReal);
     } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      try {
+        const fileReal = await realpath(full);
+        if (!isPathWithin(fileReal, memoryDirReal)) continue;
+      } catch {
+        continue;
+      }
       yield full;
     }
   }
 }
+
+function isPathWithin(candidate: string, root: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!!relative && !relative.startsWith("..") && !path.isAbsolute(relative));
+}

package/src/conversation-index/indexer.test.ts

@@ -98,6 +98,28 @@ test("writeConversationChunks keeps distinct raw session keys from overwriting a
   }
 });
 
+test("writeConversationChunks quotes metadata scalars in front matter", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-conversation-index-"));
+  try {
+    const sessionKey = "agent\nkind: other\n---\ncolon: value";
+    const written = await writeConversationChunks(root, [
+      sampleChunk({
+        sessionKey,
+        startTs: "2026-05-17T00:00:00.000Z",
+        endTs: "2026-05-17T00:01:00.000Z",
+      }),
+    ]);
+
+    const content = await readFile(written[0]!, "utf-8");
+    assert.match(content, /^sessionKey: "agent\\nkind: other\\n---\\ncolon: value"$/m);
+    assert.match(content, /^startTs: "2026-05-17T00:00:00.000Z"$/m);
+    assert.match(content, /^endTs: "2026-05-17T00:01:00.000Z"$/m);
+    assert.doesNotMatch(content, /^kind: other$/m);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 test("writeConversationChunks rejects invalid chunk timestamps before deriving paths", async () => {
   const root = await mkdtemp(path.join(os.tmpdir(), "remnic-conversation-index-"));
   try {

package/src/conversation-index/indexer.ts

@@ -40,6 +40,10 @@ function sanitizeChunkId(id: string): string {
   return sanitizePathComponent(id, "chunk");
 }
 
+function yamlQuotedScalar(value: string): string {
+  return JSON.stringify(value);
+}
+
 function datePathComponent(startTs: string): string {
   const match = typeof startTs === "string"
     ? /^(\d{4})-(\d{2})-(\d{2})T/.exec(startTs)
@@ -153,9 +157,9 @@ export async function writeConversationChunks(
     const content =
       `---\n` +
       `kind: conversation_chunk\n` +
-      `sessionKey: ${c.sessionKey}\n` +
-      `startTs: ${c.startTs}\n` +
-      `endTs: ${c.endTs}\n` +
+      `sessionKey: ${yamlQuotedScalar(c.sessionKey)}\n` +
+      `startTs: ${yamlQuotedScalar(c.startTs)}\n` +
+      `endTs: ${yamlQuotedScalar(c.endTs)}\n` +
       `---\n\n` +
       c.text +
       "\n";