@remnic/plugin-openclaw 1.0.6 → 1.0.7

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   SharedContextManager,
   defaultTierMigrationCycleBudget,
   external_exports
-} from "./chunk-GUKYM4XZ.js";
+} from "./chunk-SVGN3ACY.js";
 import {
   filterTrajectoriesByLookbackDays,
   getCausalTrajectoryStoreStatus,
@@ -85,12 +85,14 @@ import {
 import {
   FallbackLlmClient,
   buildChatCompletionTokenLimit,
-  extractJsonCandidates,
   mergeEnv,
   readEnvVar,
   resolveHomeDir,
   shouldAssumeOpenAiChatCompletions
-} from "./chunk-3SA5F4WT.js";
+} from "./chunk-NXLHSCLU.js";
+import {
+  extractJsonCandidates
+} from "./chunk-3A5ELHTT.js";
 import {
   listJsonFiles,
   listNamedFiles,
@@ -306,6 +308,31 @@ function normalizeMemoryRelativeDir(raw, fallback) {
   const normalized = trimmed.replace(/\\/g, "/").split("/").filter((segment) => segment.length > 0 && segment !== "." && segment !== "..").join("/");
   return normalized.length > 0 ? normalized : fallback;
 }
+function parseContradictionScanConfig(raw) {
+  if (!raw || typeof raw !== "object") {
+    return {
+      enabled: false,
+      similarityFloor: 0.82,
+      topicOverlapFloor: 0.4,
+      maxPairsPerRun: 500,
+      cooldownDays: 14,
+      autoMergeDuplicates: false
+    };
+  }
+  const src = raw;
+  const simFloor = coerceNumber(src.similarityFloor) ?? 0.82;
+  const topicFloor = coerceNumber(src.topicOverlapFloor) ?? 0.4;
+  const maxPairs = coerceNumber(src.maxPairsPerRun) ?? 500;
+  const cooldown = coerceNumber(src.cooldownDays) ?? 14;
+  return {
+    enabled: coerceBool(src.enabled) === true,
+    similarityFloor: Math.min(1, Math.max(0, simFloor)),
+    topicOverlapFloor: Math.min(1, Math.max(0, topicFloor)),
+    maxPairsPerRun: Math.max(1, maxPairs),
+    cooldownDays: Math.max(0, cooldown),
+    autoMergeDuplicates: coerceBool(src.autoMergeDuplicates) === true
+  };
+}
 function parseSemanticChunkingConfig(raw) {
   if (!raw || typeof raw !== "object") return {};
   const src = raw;
@@ -510,17 +537,26 @@ function parseConfig(raw) {
     fingerprintDedup: rawCodexCompat.fingerprintDedup !== false
   };
   const rawProcedural = cfg.procedural && typeof cfg.procedural === "object" && !Array.isArray(cfg.procedural) ? cfg.procedural : {};
-  const proceduralMinRaw = typeof rawProcedural.minOccurrences === "number" && Number.isFinite(rawProcedural.minOccurrences) ? Math.floor(rawProcedural.minOccurrences) : 3;
+  const proceduralMinCoerced = coerceNumber(rawProcedural.minOccurrences);
+  const proceduralMinRaw = proceduralMinCoerced !== void 0 ? Math.floor(proceduralMinCoerced) : 3;
+  const successFloorRaw = coerceNumber(rawProcedural.successFloor);
+  const successFloor = successFloorRaw !== void 0 && successFloorRaw >= 0 && successFloorRaw <= 1 ? successFloorRaw : 0.7;
+  const autoPromoteOccRaw = coerceNumber(rawProcedural.autoPromoteOccurrences);
+  const autoPromoteOccurrences = autoPromoteOccRaw !== void 0 && Number.isFinite(autoPromoteOccRaw) ? autoPromoteOccRaw <= 0 ? 0 : Math.min(1e4, Math.max(1, Math.floor(autoPromoteOccRaw))) : 8;
+  const lookbackCoerced = coerceNumber(rawProcedural.lookbackDays);
+  const lookbackDays = lookbackCoerced !== void 0 && Number.isFinite(lookbackCoerced) ? Math.min(3650, Math.max(1, Math.floor(lookbackCoerced))) : 30;
+  const recallMaxCoerced = coerceNumber(rawProcedural.recallMaxProcedures);
+  const recallMaxProcedures = recallMaxCoerced !== void 0 && Number.isFinite(recallMaxCoerced) ? Math.min(10, Math.max(1, Math.floor(recallMaxCoerced))) : 3;
   const procedural = {
     enabled: coerceBool(rawProcedural.enabled) === true,
-    /** 0 disables miner emission threshold (no clusters qualify). */
+    /** `0` skips all mining (`minOccurrences_zero`); otherwise clusters need at least this many members. */
     minOccurrences: Math.min(1e3, Math.max(0, proceduralMinRaw)),
-    successFloor: typeof rawProcedural.successFloor === "number" && Number.isFinite(rawProcedural.successFloor) && rawProcedural.successFloor >= 0 && rawProcedural.successFloor <= 1 ? rawProcedural.successFloor : 0.7,
-    autoPromoteOccurrences: typeof rawProcedural.autoPromoteOccurrences === "number" && Number.isFinite(rawProcedural.autoPromoteOccurrences) ? rawProcedural.autoPromoteOccurrences <= 0 ? 0 : Math.min(1e4, Math.max(1, Math.floor(rawProcedural.autoPromoteOccurrences))) : 8,
+    successFloor,
+    autoPromoteOccurrences,
     autoPromoteEnabled: coerceBool(rawProcedural.autoPromoteEnabled) === true,
-    lookbackDays: typeof rawProcedural.lookbackDays === "number" && Number.isFinite(rawProcedural.lookbackDays) ? Math.min(3650, Math.max(1, Math.floor(rawProcedural.lookbackDays))) : 30,
+    lookbackDays,
     proceduralMiningCronAutoRegister: coerceBool(rawProcedural.proceduralMiningCronAutoRegister) === true,
-    recallMaxProcedures: typeof rawProcedural.recallMaxProcedures === "number" && Number.isFinite(rawProcedural.recallMaxProcedures) ? Math.min(10, Math.max(1, Math.floor(rawProcedural.recallMaxProcedures))) : 3
+    recallMaxProcedures
   };
   const memoryDir = typeof cfg.memoryDir === "string" && cfg.memoryDir.length > 0 ? cfg.memoryDir : DEFAULT_MEMORY_DIR;
   const rawIdentityInjectionMode = cfg.identityInjectionMode;
@@ -704,13 +740,19 @@ function parseConfig(raw) {
     contradictionSimilarityThreshold: typeof cfg.contradictionSimilarityThreshold === "number" ? cfg.contradictionSimilarityThreshold : 0.7,
     contradictionMinConfidence: typeof cfg.contradictionMinConfidence === "number" ? cfg.contradictionMinConfidence : 0.9,
     contradictionAutoResolve: cfg.contradictionAutoResolve !== false,
+    // Contradiction Scan cron (issue #520)
+    contradictionScan: parseContradictionScanConfig(cfg.contradictionScan),
     // Temporal Supersession (issue #375)
     temporalSupersessionEnabled: cfg.temporalSupersessionEnabled !== false,
     // On by default
     temporalSupersessionIncludeInRecall: cfg.temporalSupersessionIncludeInRecall === true,
     // Off by default
-    // Direct-answer retrieval tier (issue #518)
-    recallDirectAnswerEnabled: coerceBool(cfg.recallDirectAnswerEnabled) ?? false,
+    // Direct-answer retrieval tier (issue #518).  Default on — the
+    // tier runs in observation mode: it annotates
+    // LastRecallSnapshot.tierExplain but never short-circuits the
+    // QMD path.  Operators can opt out with
+    // recallDirectAnswerEnabled=false.
+    recallDirectAnswerEnabled: coerceBool(cfg.recallDirectAnswerEnabled) ?? true,
     recallDirectAnswerTokenOverlapFloor: (() => {
       const n = coerceNumber(cfg.recallDirectAnswerTokenOverlapFloor);
       return n !== void 0 && n >= 0 && n <= 1 ? n : 0.55;
@@ -972,6 +1014,22 @@ function parseConfig(raw) {
     localLlmFastModel: typeof cfg.localLlmFastModel === "string" && cfg.localLlmFastModel.length > 0 ? cfg.localLlmFastModel : "",
     localLlmFastUrl: typeof cfg.localLlmFastUrl === "string" && cfg.localLlmFastUrl.length > 0 ? cfg.localLlmFastUrl : typeof cfg.localLlmUrl === "string" && cfg.localLlmUrl.length > 0 ? cfg.localLlmUrl : "http://localhost:1234/v1",
     localLlmFastTimeoutMs: typeof cfg.localLlmFastTimeoutMs === "number" ? cfg.localLlmFastTimeoutMs : 15e3,
+    // Thinking-mode suppression on the main local LLM (issue #548).
+    // Default true — extraction / consolidation produce structured
+    // JSON and gain nothing from chain-of-thought; thinking-capable
+    // models burn their token budget on reasoning and blow the
+    // default 60s timeout.  Operators who need thinking on the main
+    // client (e.g. for narrative tasks) can set this to false via
+    // config or --config CLI flag.  The fast-tier `fastLlm` always
+    // disables thinking and is unaffected by this flag.
+    //
+    // Injection is backend-gated inside LocalLlmClient: the
+    // `chat_template_kwargs` field is only sent when the detected
+    // backend is in `THINKING_COMPATIBLE_BACKENDS` (LM Studio, vLLM).
+    // Strict OpenAI-compatible backends reject unknown request
+    // fields with 400, so the client fails open on unknown backends
+    // rather than tripping the 400 cooldown (Codex P1 on PR #550).
+    localLlmDisableThinking: coerceBool(cfg.localLlmDisableThinking) ?? true,
     // Gateway config (passed from index.ts for fallback AI)
     gatewayConfig: cfg.gatewayConfig,
     // Gateway model source (v9.2) — route LLM calls through gateway agent model chain
@@ -2844,6 +2902,10 @@ function trimTrailingSlashes(s) {
   while (end > 0 && s[end - 1] === "/") end--;
   return s.substring(0, end);
 }
+var THINKING_COMPATIBLE_BACKENDS = /* @__PURE__ */ new Set([
+  "lmstudio",
+  "vllm"
+]);
 var LOCAL_SERVERS = [
   {
     type: "ollama",
@@ -2902,9 +2964,16 @@ var LocalLlmClient = class _LocalLlmClient {
     this.modelRegistry = modelRegistry;
   }
   /**
-   * Disable thinking/reasoning mode for models that support it (e.g. Qwen 3.5).
-   * When enabled, adds chat_template_kwargs to suppress chain-of-thought,
-   * reducing latency for fast-tier operations.
+   * Request thinking/reasoning suppression on the next chat completion.
+   *
+   * When `true`, the client will inject
+   * `chat_template_kwargs: { enable_thinking: false }` into the request
+   * body — **but only when the detected backend is known to support it**
+   * (LM Studio, vLLM; see `THINKING_COMPATIBLE_BACKENDS`).  Strict
+   * OpenAI-compat backends reject unknown fields with 400; on those the
+   * client fails open (thinking runs normally).  This is the safe
+   * default for Remnic extraction / consolidation: measurable latency
+   * win on thinking-capable backends, zero risk on others.  Issue #548.
    */
   set disableThinking(value) {
     this._disableThinking = value;
@@ -3402,7 +3471,7 @@ var LocalLlmClient = class _LocalLlmClient {
       if (options.responseFormat?.type === "json_schema") {
         requestBody.response_format = options.responseFormat;
       }
-      if (this._disableThinking) {
+      if (this._disableThinking && this.detectedType !== null && THINKING_COMPATIBLE_BACKENDS.has(this.detectedType)) {
         requestBody.chat_template_kwargs = { enable_thinking: false };
       }
       const baseUrl = trimTrailingSlashes(
@@ -5395,6 +5464,8 @@ Memory categories \u2014 use the MOST SPECIFIC category that fits:
 - commitment: Promises, obligations, deadlines
 - moment: Emotionally significant events
 - skill: Demonstrated capabilities
+- rule: Explicit operational rules or constraints
+- procedure: Repeatable workflows \u2014 use when the user describes a multi-step play (\u22652 ordered steps). Put the human-readable trigger/context in "content" (e.g. "When you deploy\u2026") and list steps in "procedureSteps" as [{"order":1,"intent":"\u2026"}, \u2026] mirroring the gateway extraction schema.
 
 IMPORTANT: Do NOT label everything as "fact". Use "decision" for architectural choices, "commitment" for deadlines/promises, "principle" for reusable rules, "correction" for when the user rejects a suggestion, etc.
 
@@ -5456,7 +5527,7 @@ Also generate:
 
 Output JSON:
 {
-  "facts": [{"category": "decision", "content": "Chose PostgreSQL over MongoDB for the user service", "importance": 8, "confidence": 0.9, "structuredAttributes": {"chosen": "PostgreSQL", "rejected": "MongoDB"}}, {"category": "commitment", "content": "Must ship v2.0 API by end of March", "importance": 10, "confidence": 1.0, "structuredAttributes": {"deadline": "end of March", "deliverable": "v2.0 API"}}, {"category": "fact", "content": "The store backend uses Redis for session caching", "importance": 6, "confidence": 0.95, "entityRef": "project-acme-store"}, {"category": "principle", "content": "Always run migrations in a transaction to avoid partial schema updates", "importance": 8, "confidence": 0.9}],
+  "facts": [{"category": "decision", "content": "Chose PostgreSQL over MongoDB for the user service", "importance": 8, "confidence": 0.9, "structuredAttributes": {"chosen": "PostgreSQL", "rejected": "MongoDB"}}, {"category": "procedure", "content": "When you cut a hotfix release, follow the checklist", "importance": 8, "confidence": 0.9, "procedureSteps": [{"order": 1, "intent": "Branch from main and cherry-pick the fix"}, {"order": 2, "intent": "Run CI and tag the release"}]}, {"category": "commitment", "content": "Must ship v2.0 API by end of March", "importance": 10, "confidence": 1.0, "structuredAttributes": {"deadline": "end of March", "deliverable": "v2.0 API"}}, {"category": "fact", "content": "The store backend uses Redis for session caching", "importance": 6, "confidence": 0.95, "entityRef": "project-acme-store"}, {"category": "principle", "content": "Always run migrations in a transaction to avoid partial schema updates", "importance": 8, "confidence": 0.9}],
   "entities": [{"name": "person-jane-doe", "type": "person", "facts": ["Works at Acme Corp", "Prefers Python over JavaScript"], "structuredSections": [{"key": "beliefs", "title": "Beliefs", "facts": ["Python is a better fit than JavaScript for backend work."]}]}, {"name": "project-acme-store", "type": "project", "facts": ["Built with Next.js", "Deployed on Vercel"]}],
   "profileUpdates": ["User prefers dark mode in all editors"],
   "questions": [{"question": "Which cloud provider hosts the staging environment?", "context": "Came up during deployment discussion", "priority": 0.5}],
@@ -7367,7 +7438,7 @@ var ENTITY_PATTERNS = [
   { re: /\b(model|llm|qmd|embedding|retrieval|memory)\b/i, entityType: "ai" },
   { re: /\b(doc|readme|docs|changelog)\b/i, entityType: "docs" }
 ];
-var TASK_INITIATION_RE = /\b(ship(?:ping|ped)?|deploy(?:ing|ed)?|release|publish|open(?:ing)?\s+(?:a\s+)?(?:pr|pull\s+request)|merge(?:ing)?\s+(?:the\s+)?(?:pr|pull\s+request)|run\s+(?:the\s+)?tests?|start(?:ing)?\s+(?:work|on|the)|kick\s+off|implement(?:ing|ed)?|let's\s+|going\s+to\s+(?:ship|deploy|release|open|run|merge)|need\s+to\s+(?:ship|deploy|run|open|merge|test)|fix(?:ing|ed)?\s+(?:the\s+)?(?:bug|build)|patch(?:ing|ed)?|build(?:ing)?\s+(?:and\s+)?(?:ship|deploy))\b/i;
+var TASK_INITIATION_RE = /\b(ship(?:ping|ped)?|deploy(?:ing|ed)?|release|publish|open(?:ing)?\s+(?:a\s+)?(?:pr|pull\s+request)|merge(?:ing)?\s+(?:the\s+)?(?:pr|pull\s+request)|run\s+(?:the\s+)?tests?|start(?:ing)?\s+(?:work|on|the)|kick\s+off|implement(?:ing|ed)?|let's\s+(?:ship|deploy|release|publish|open|run|merge|implement|fix|patch|build|start|do|get|put|wire|hook|land|roll)\b|going\s+to\s+(?:ship|deploy|release|open|run|merge)|need\s+to\s+(?:ship|deploy|run|open|merge|test)|fix(?:ing|ed)?\s+(?:(?:the|a)\s+)?(?:\w+\s+){0,4}(?:bug|build)\b|patch(?:ing|ed)?|build(?:ing)?\s+(?:and\s+)?(?:ship|deploy))\b/i;
 function normalizeTextInput(input) {
   return typeof input === "string" ? input : "";
 }
@@ -7698,8 +7769,13 @@ async function scanDir(dir) {
 async function scanMemoryDir(memoryDir) {
   const factsDir = path4.join(memoryDir, "facts");
   const correctionsDir = path4.join(memoryDir, "corrections");
-  const [facts, corrections] = await Promise.all([scanDir(factsDir), scanDir(correctionsDir)]);
-  return [...facts, ...corrections];
+  const proceduresDir = path4.join(memoryDir, "procedures");
+  const [facts, corrections, procedures] = await Promise.all([
+    scanDir(factsDir),
+    scanDir(correctionsDir),
+    scanDir(proceduresDir)
+  ]);
+  return [...facts, ...corrections, ...procedures];
 }
 
 // ../remnic-core/src/search/lancedb-backend.ts
@@ -8534,6 +8610,23 @@ var EmbedHelper = class {
 import { createHash as createHash3 } from "crypto";
 import os2 from "os";
 import path6 from "path";
+
+// ../remnic-core/src/abort-error.ts
+function abortError(message) {
+  const err = new Error(message);
+  Object.defineProperty(err, "name", { value: "AbortError" });
+  return err;
+}
+function isAbortError(err) {
+  return err instanceof Error && err.name === "AbortError";
+}
+function throwIfAborted(signal, message = "operation aborted") {
+  if (signal?.aborted) {
+    throw abortError(message);
+  }
+}
+
+// ../remnic-core/src/qmd.ts
 var QMD_TIMEOUT_MS = 3e4;
 var QMD_DAEMON_TIMEOUT_MS = 8e3;
 var QMD_PROBE_TIMEOUT_MS = 8e3;
@@ -8564,14 +8657,6 @@ function getGlobalQmdState() {
   }
   return g[QMD_GLOBAL_STATE_KEY];
 }
-function abortError(message) {
-  const err = new Error(message);
-  Object.defineProperty(err, "name", { value: "AbortError" });
-  return err;
-}
-function isAbortError(err) {
-  return err instanceof Error && err.name === "AbortError";
-}
 function errorMessage(err) {
   if (typeof err === "string") return err;
   if (err instanceof Error) return err.message;
@@ -8592,11 +8677,6 @@ function isCallerCancellation(err, signal) {
 function isDaemonTimeoutError(err) {
   return /timed out/i.test(errorMessage(err));
 }
-function throwIfAborted(signal, message = "operation aborted") {
-  if (signal?.aborted) {
-    throw abortError(message);
-  }
-}
 function sleepWithSignal(ms, signal) {
   return new Promise((resolve, reject) => {
     throwIfAborted(signal);
@@ -12983,6 +13063,7 @@ import path15 from "path";
 var DAY_SUMMARY_CRON_ID = "engram-day-summary";
 var GOVERNANCE_CRON_ID = "engram-nightly-governance";
 var PROCEDURAL_MINING_CRON_ID = "engram-procedural-mining";
+var CONTRADICTION_SCAN_CRON_ID = "engram-contradiction-scan";
 async function acquireCronJobsLock(jobsPath) {
   const lockPath2 = `${jobsPath}.lock`;
   const start = Date.now();
@@ -13119,6 +13200,30 @@ async function ensureProceduralMiningCron(jobsPath, options) {
     delivery: { mode: "none" }
   }));
 }
+async function ensureContradictionScanCron(jobsPath, options) {
+  const scheduleExpr = typeof options.scheduleExpr === "string" && options.scheduleExpr.trim().length > 0 ? options.scheduleExpr.trim() : "37 3 * * *";
+  const agentId = typeof options.agentId === "string" && options.agentId.trim().length > 0 ? options.agentId.trim() : "main";
+  return ensureCronJob(jobsPath, CONTRADICTION_SCAN_CRON_ID, () => ({
+    id: CONTRADICTION_SCAN_CRON_ID,
+    agentId,
+    name: "Remnic Contradiction Scan (nightly)",
+    enabled: true,
+    schedule: {
+      kind: "cron",
+      expr: scheduleExpr,
+      tz: options.timezone
+    },
+    sessionTarget: "isolated",
+    wakeMode: "now",
+    payload: {
+      kind: "agentTurn",
+      timeoutSeconds: 900,
+      thinking: "off",
+      message: "You are OpenClaw automation. Call tool `engram.contradiction_scan_run` with empty params. If successful output exactly NO_REPLY. On error output one concise line. Do NOT use message tool."
+    },
+    delivery: { mode: "none" }
+  }));
+}
 
 // ../remnic-core/src/lifecycle.ts
 var DEFAULT_POLICY = {
@@ -14882,6 +14987,14 @@ function clampGraphRecallExpandedEntries(entries, maxEntries = 64) {
     };
   }).filter((item) => item.path.length > 0 && item.namespace.length > 0).slice(0, limit);
 }
+function cloneTierExplain(tierExplain) {
+  if (!tierExplain) return void 0;
+  return structuredClone(tierExplain);
+}
+function cloneLastRecallSnapshot(snapshot) {
+  if (!snapshot) return null;
+  return structuredClone(snapshot);
+}
 var DEFAULT_TIER_MIGRATION_STATUS = {
   updatedAt: (/* @__PURE__ */ new Date(0)).toISOString(),
   lastCycle: null,
@@ -14912,13 +15025,17 @@ var LastRecallStore = class {
     }
   }
   get(sessionKey) {
-    return this.state[sessionKey] ?? null;
+    return cloneLastRecallSnapshot(this.state[sessionKey] ?? null);
   }
   getMostRecent() {
     const snapshots = Object.values(this.state);
     if (snapshots.length === 0) return null;
-    snapshots.sort((a, b) => b.recordedAt.localeCompare(a.recordedAt));
-    return snapshots[0] ?? null;
+    snapshots.sort((a, b) => {
+      const byTime = b.recordedAt.localeCompare(a.recordedAt);
+      if (byTime !== 0) return byTime;
+      return a.sessionKey.localeCompare(b.sessionKey);
+    });
+    return cloneLastRecallSnapshot(snapshots[0] ?? null);
   }
   /**
    * Persist last-recall snapshot and append an impression log entry.
@@ -14927,7 +15044,7 @@ var LastRecallStore = class {
   async record(opts) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const queryHash = createHash4("sha256").update(opts.query).digest("hex");
-    const snapshot = {
+    const liveSnapshot = {
       sessionKey: opts.sessionKey,
       recordedAt: now,
       queryHash,
@@ -14939,15 +15056,17 @@ var LastRecallStore = class {
       requestedMode: opts.requestedMode,
       source: opts.source,
       fallbackUsed: opts.fallbackUsed,
-      sourcesUsed: opts.sourcesUsed ? [...opts.sourcesUsed] : void 0,
-      budgetsApplied: opts.budgetsApplied ? { ...opts.budgetsApplied } : void 0,
+      sourcesUsed: opts.sourcesUsed,
+      budgetsApplied: opts.budgetsApplied,
       latencyMs: opts.latencyMs,
-      resultPaths: opts.resultPaths ? [...opts.resultPaths] : void 0,
+      resultPaths: opts.resultPaths,
       policyVersion: opts.policyVersion,
       identityInjectionMode: opts.identityInjection?.mode,
       identityInjectedChars: opts.identityInjection?.injectedChars,
-      identityInjectionTruncated: opts.identityInjection?.truncated
+      identityInjectionTruncated: opts.identityInjection?.truncated,
+      tierExplain: opts.tierExplain
     };
+    const snapshot = cloneLastRecallSnapshot(liveSnapshot);
     this.state[opts.sessionKey] = snapshot;
     const keys = Object.keys(this.state);
     if (keys.length > 50) {
@@ -14971,6 +15090,31 @@ var LastRecallStore = class {
       }
     }
   }
+  /**
+   * Attach a RecallTierExplain block to the existing snapshot for a
+   * session without rewriting the entire snapshot.  Used by the
+   * post-recall direct-answer annotation path (issue #518 slice 3c):
+   * recallInternal records the snapshot first, then the orchestrator
+   * fires the direct-answer tier in observation mode and annotates
+   * the stored snapshot with whichever tier served the query.
+   *
+   * No-op when no snapshot exists for the given session; callers do
+   * not need to guard on existence.
+   */
+  async annotateTierExplain(sessionKey, tierExplain) {
+    const current = this.state[sessionKey];
+    if (!current) return;
+    this.state[sessionKey] = {
+      ...current,
+      tierExplain: cloneTierExplain(tierExplain)
+    };
+    try {
+      await mkdir11(path20.dirname(this.statePath), { recursive: true });
+      await writeFile12(this.statePath, JSON.stringify(this.state, null, 2), "utf-8");
+    } catch (err) {
+      log.debug(`last recall tier-explain annotate failed: ${err}`);
+    }
+  }
 };
 var TierMigrationStatusStore = class {
   statePath;
@@ -20555,13 +20699,13 @@ async function readCueAnchors(options) {
   return anchors;
 }
 async function searchHarmonicRetrieval(options) {
-  throwIfAborted2(options.abortSignal);
+  throwIfAborted(options.abortSignal, "harmonic retrieval aborted");
   const queryTokens = new Set(normalizeRecallTokens(options.query, ["what", "which"]));
   if (queryTokens.size === 0 || options.maxResults <= 0) return [];
   const nodes = await readAbstractionNodes(options);
   const candidates = /* @__PURE__ */ new Map();
   for (const node of nodes) {
-    throwIfAborted2(options.abortSignal);
+    throwIfAborted(options.abortSignal, "harmonic retrieval aborted");
     const { score, matchedFields } = scoreNode(node, queryTokens);
     if (score <= 0) continue;
     candidates.set(node.nodeId, {
@@ -20573,11 +20717,11 @@ async function searchHarmonicRetrieval(options) {
     });
   }
   if (options.anchorsEnabled) {
-    throwIfAborted2(options.abortSignal);
+    throwIfAborted(options.abortSignal, "harmonic retrieval aborted");
     const anchors = await readCueAnchors(options);
     const nodeIndex = new Map(nodes.map((node) => [node.nodeId, node]));
     for (const anchor of anchors) {
-      throwIfAborted2(options.abortSignal);
+      throwIfAborted(options.abortSignal, "harmonic retrieval aborted");
       const { score, matchedFields } = scoreAnchor(anchor, queryTokens);
       if (score <= 0) continue;
       for (const nodeRef of anchor.nodeRefs) {
@@ -20619,12 +20763,6 @@ async function searchHarmonicRetrieval(options) {
     (left, right) => right.score - left.score || right.anchorScore - left.anchorScore || right.node.recordedAt.localeCompare(left.node.recordedAt)
   ).slice(0, options.maxResults);
 }
-function throwIfAborted2(signal) {
-  if (!signal?.aborted) return;
-  const err = new Error("harmonic retrieval aborted");
-  Object.defineProperty(err, "name", { value: "AbortError" });
-  throw err;
-}
 
 // ../remnic-core/src/verified-recall.ts
 function createReadOnlyBoxBuilder(memoryDir) {
@@ -27211,15 +27349,9 @@ function fingerprintEntitySynthesisEvidence(entity) {
   fingerprint.update(fingerprintEntityStructuredFacts(entity) ?? "");
   return fingerprint.digest("hex");
 }
-function abortRecallError(message) {
-  const err = new Error(message);
-  Object.defineProperty(err, "name", { value: "AbortError" });
-  return err;
-}
+var abortRecallError = abortError;
 function throwIfRecallAborted(signal, message = "recall aborted") {
-  if (signal?.aborted) {
-    throw abortRecallError(message);
-  }
+  throwIfAborted(signal, message);
 }
 async function raceRecallAbort(promise, signal, message = "recall aborted") {
   throwIfRecallAborted(signal, message);
@@ -27853,6 +27985,7 @@ var Orchestrator = class _Orchestrator {
     );
     this.judgeVerdictCache = createVerdictCache();
     this.localLlm = new LocalLlmClient(config, this.modelRegistry);
+    this.localLlm.disableThinking = config.localLlmDisableThinking;
     this.fastLlm = config.localLlmFastEnabled ? (() => {
       const client = new LocalLlmClient(
         {
@@ -28353,6 +28486,13 @@ var Orchestrator = class _Orchestrator {
         log.debug(`procedural mining cron auto-register failed (non-fatal): ${err}`);
       }
     }
+    if (this.config.contradictionScan?.enabled) {
+      try {
+        await this.autoRegisterContradictionScanCron();
+      } catch (err) {
+        log.debug(`contradiction scan cron auto-register failed (non-fatal): ${err}`);
+      }
+    }
     log.info("orchestrator initialized (full \u2014 deferred steps complete)");
   }
   /**
@@ -28520,6 +28660,26 @@ var Orchestrator = class _Orchestrator {
       log.debug(`procedural mining cron auto-register error: ${err}`);
     }
   }
+  async autoRegisterContradictionScanCron() {
+    const home = resolveHomeDir();
+    const jobsPath = path43.join(home, ".openclaw", "cron", "jobs.json");
+    try {
+      if (!existsSync8(jobsPath)) {
+        log.debug("contradiction scan cron: jobs.json not found, skipping auto-register");
+        return;
+      }
+      const created = await ensureContradictionScanCron(jobsPath, {
+        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone
+      });
+      if (created.created) {
+        log.info(`contradiction scan cron auto-registered (${created.jobId})`);
+      } else {
+        log.debug("contradiction scan cron already exists, skipping auto-register");
+      }
+    } catch (err) {
+      log.debug(`contradiction scan cron auto-register error: ${err}`);
+    }
+  }
   async applyBehaviorRuntimePolicy(state) {
     const result = await this.policyRuntime.applyFromBehaviorState(state);
     this.runtimePolicyValues = await this.policyRuntime.loadRuntimeValues();
@@ -28647,7 +28807,7 @@ var Orchestrator = class _Orchestrator {
       );
       return result;
     }
-    const { FallbackLlmClient: FallbackLlmClient2 } = await import("./fallback-llm-HJRCHKSA.js");
+    const { FallbackLlmClient: FallbackLlmClient2 } = await import("./fallback-llm-QEAPMDW7.js");
     const useGateway = this.config.modelSource === "gateway";
     const modelSetting = this.config.semanticConsolidationModel;
     if (modelSetting === "fast" && this.fastLlm && !useGateway) {
@@ -31036,7 +31196,7 @@ ${trimmedBody}`;
           return null;
         }
         try {
-          const { getCalibrationRulesForRecall, buildCalibrationRecallSection } = await import("./calibration-3JHF25QT.js");
+          const { getCalibrationRulesForRecall, buildCalibrationRecallSection } = await import("./calibration-BAC7KNKR.js");
           const rules = await getCalibrationRulesForRecall(this.config.memoryDir);
           if (rules.length === 0) {
             recordRecallSectionMetric({
@@ -31924,7 +32084,7 @@ ${formatted}`;
         if (!this.isRecallSectionEnabled("procedure-recall", true)) return null;
         try {
           return await buildProcedureRecallSection(
-            this.storage,
+            profileStorage,
             retrievalQuery,
             this.config
           );
@@ -33337,7 +33497,7 @@ _Context: ${topQuestion.context}_`
     if (!this.queueProcessing) {
       this.queueProcessing = true;
       this.processQueue().catch((err) => {
-        log.error("background extraction queue processor failed", err);
+        this.logExtractionQueueFailure(err, "processor");
         this.queueProcessing = false;
       });
     }
@@ -33395,12 +33555,38 @@ ${normalized}`).digest("hex");
         try {
           await task();
         } catch (err) {
-          log.error("background extraction task failed", err);
+          this.logExtractionQueueFailure(err, "task");
         }
       }
     }
     this.queueProcessing = false;
   }
+  /**
+   * Classify + log a failure from either the per-task catch inside
+   * `processQueue()` or the outer `processQueue().catch(...)` in
+   * `queueBufferedExtraction()`.  Issue #549: `throwIfRecallAborted`
+   * (used throughout `runExtraction`) raises an Error whose `name` is
+   * `"AbortError"`.  That path fires when `before_reset` aborts a
+   * queued task to avoid duplicate extraction — it is intentional
+   * cancellation, not a failure.  Downgrading the log to debug
+   * prevents spurious `error`-level lines that routinely appear
+   * right next to a successful `persisted: N facts, M entities` log
+   * and that confuse operators into thinking extraction is broken.
+   * Genuine extraction failures (network, parse, I/O) still log at
+   * `error`.
+   *
+   * Source differentiates the two call sites so the log message
+   * names the right layer (`task` vs `processor`).
+   */
+  logExtractionQueueFailure(err, source) {
+    const aborted = source === "task" ? "background extraction task aborted (session transition)" : "background extraction queue processor aborted (session transition)";
+    const failed = source === "task" ? "background extraction task failed" : "background extraction queue processor failed";
+    if (isAbortError(err)) {
+      log.debug(aborted);
+    } else {
+      log.error(failed, err);
+    }
+  }
   async runExtraction(turns, options = {}) {
     log.debug(`running extraction on ${turns.length} turns`);
     const clearBufferAfterExtraction = options.clearBufferAfterExtraction ?? true;
@@ -33412,12 +33598,12 @@ ${normalized}`).digest("hex");
         throw new Error(`replay extraction deadline exceeded (${stage})`);
       }
     };
-    const throwIfAborted3 = (stage) => {
+    const throwIfAborted2 = (stage) => {
       throwIfRecallAborted(options.abortSignal, `extraction aborted (${stage})`);
     };
     const clearBuffer = async (options2) => {
       if (options2?.ignoreAbort !== true) {
-        throwIfAborted3("before_clear_buffer");
+        throwIfAborted2("before_clear_buffer");
       }
       if (clearBufferAfterExtraction) {
         await this.buffer.clearAfterExtraction(bufferKey);
@@ -33436,7 +33622,7 @@ ${normalized}`).digest("hex");
       content: t.content.trim().slice(0, this.config.extractionMaxTurnChars)
     })).filter((t) => t.content.length > 0);
     throwIfDeadlineExceeded("before_extract");
-    throwIfAborted3("before_extract");
+    throwIfAborted2("before_extract");
     const userTurns = normalizedTurns.filter((t) => t.role === "user");
     const totalChars = normalizedTurns.reduce(
       (sum, t) => sum + t.content.length,
@@ -33481,7 +33667,7 @@ ${normalized}`).digest("hex");
       "extraction aborted (during_extract)"
     );
     throwIfDeadlineExceeded("before_persist");
-    throwIfAborted3("before_persist");
+    throwIfAborted2("before_persist");
     if (!result) {
       log.warn("runExtraction: extraction returned null/undefined");
       await clearBuffer();
@@ -34194,16 +34380,6 @@ ${normalized}`).digest("hex");
       }
       fact.tags = Array.isArray(fact.tags) ? fact.tags.filter((t) => typeof t === "string") : [];
       fact.confidence = typeof fact.confidence === "number" ? fact.confidence : 0.7;
-      if (this.contentHashIndex) {
-        const canonicalContent = citationEnabled && hasCitationForTemplate(fact.content, citationTemplate) ? stripCitationForTemplate(fact.content, citationTemplate) : fact.content;
-        if (this.contentHashIndex.has(canonicalContent)) {
-          log.debug(
-            `dedup: skipping duplicate fact "${fact.content.slice(0, 60)}\u2026"`
-          );
-          dedupedCount++;
-          continue;
-        }
-      }
       let writeCategory = fact.category;
       let targetStorage = storage;
       let routedRuleId;
@@ -34228,6 +34404,15 @@ ${normalized}`).digest("hex");
           );
         }
       }
+      const canonicalContentForHash = citationEnabled && hasCitationForTemplate(fact.content, citationTemplate) ? stripCitationForTemplate(fact.content, citationTemplate) : fact.content;
+      const contentHashDedupKey = writeCategory === "procedure" ? buildProcedurePersistBody(fact.content, fact.procedureSteps) : canonicalContentForHash;
+      if (this.contentHashIndex && this.contentHashIndex.has(contentHashDedupKey)) {
+        log.debug(
+          `dedup: skipping duplicate fact "${fact.content.slice(0, 60)}\u2026"`
+        );
+        dedupedCount++;
+        continue;
+      }
       const importance = scoreImportance(
         fact.content,
         writeCategory,
@@ -34271,16 +34456,10 @@ ${normalized}`).digest("hex");
           procedureSteps: fact.procedureSteps
         });
         if (!procGate.durable) {
-          if (this.config.extractionJudgeShadow) {
-            log.info(
-              `extraction-procedure-gate[shadow]: would reject "${fact.content.slice(0, 60)}\u2026" reason="${procGate.reason}"`
-            );
-          } else {
-            log.debug(
-              `extraction-procedure-gate: rejected "${fact.content.slice(0, 60)}\u2026" reason="${procGate.reason}"`
-            );
-            continue;
-          }
+          log.debug(
+            `extraction-procedure-gate: rejected "${fact.content.slice(0, 60)}\u2026" reason="${procGate.reason}"`
+          );
+          continue;
         }
       }
       let pendingSemanticSkip = null;
@@ -34677,7 +34856,8 @@ ${normalized}`).digest("hex");
       }
       if (this.contentHashIndex) {
         const canonicalFactContent = citationEnabled && hasCitationForTemplate(fact.content, citationTemplate) ? stripCitationForTemplate(fact.content, citationTemplate) : fact.content;
-        this.contentHashIndex.add(canonicalFactContent);
+        const hashRegisterKey = writeCategory === "procedure" ? buildProcedurePersistBody(fact.content, fact.procedureSteps) : canonicalFactContent;
+        this.contentHashIndex.add(hashRegisterKey);
       }
     }
     for (const entity of entities) {
@@ -45363,6 +45543,7 @@ function sleep2(ms) {
 }
 
 // ../remnic-core/src/procedural/procedure-miner.ts
+var PROCEDURE_CLUSTER_ATTR_MAX = 500;
 function clusterKey(record) {
   const goal = record.goal.trim().toLowerCase().replace(/\s+/g, " ").slice(0, 120);
   const refs = [...record.entityRefs ?? []].map((r) => r.trim().toLowerCase()).sort();
@@ -45395,11 +45576,12 @@ function pseudoStepsFromCluster(group) {
   }));
 }
 async function hasExistingClusterWrite(storage, cluster) {
+  const clusterKey2 = cluster.slice(0, PROCEDURE_CLUSTER_ATTR_MAX);
   const memories = await storage.readAllMemories();
   for (const m of memories) {
     if (m.frontmatter.category !== "procedure") continue;
     const c = m.frontmatter.structuredAttributes?.procedure_cluster;
-    if (c === cluster) return true;
+    if (c === clusterKey2) return true;
   }
   return false;
 }
@@ -45411,8 +45593,10 @@ async function runProcedureMining(options) {
   if (cfg.minOccurrences <= 0) {
     return { clustersProcessed: 0, proceduresWritten: 0, skippedReason: "minOccurrences_zero" };
   }
+  const trajectoryDir = typeof options.config.causalTrajectoryStoreDir === "string" && options.config.causalTrajectoryStoreDir.trim().length > 0 ? options.config.causalTrajectoryStoreDir.trim() : void 0;
   const { trajectories } = await readCausalTrajectoryRecords({
-    memoryDir: options.memoryDir
+    memoryDir: options.memoryDir,
+    causalTrajectoryStoreDir: trajectoryDir
   });
   const recent = filterTrajectoriesByLookbackDays(trajectories, cfg.lookbackDays);
   const clusters = /* @__PURE__ */ new Map();
@@ -45443,7 +45627,7 @@ async function runProcedureMining(options) {
       status: promote ? "active" : "pending_review",
       tags: ["procedure-miner", "causal-trajectory"],
       structuredAttributes: {
-        procedure_cluster: key.slice(0, 500),
+        procedure_cluster: key.slice(0, PROCEDURE_CLUSTER_ATTR_MAX),
         trajectory_ids: group.map((g) => g.trajectoryId).join(",").slice(0, 1900),
         trajectory_count: String(group.length),
         success_rate: rate.toFixed(4)
@@ -48064,6 +48248,25 @@ ${next}`);
     }
     return { submitted: memoryIds.length, matched: matchedIds.length };
   }
+  // ── Contradiction Review (issue #520) ──────────────────────────────────────
+  get memoryDir() {
+    return this.orchestrator.config.memoryDir;
+  }
+  get storageRef() {
+    return this.orchestrator.storage;
+  }
+  get configRef() {
+    return this.orchestrator.config;
+  }
+  get localLlmRef() {
+    return this.orchestrator.localLlm ?? null;
+  }
+  get fallbackLlmRef() {
+    return null;
+  }
+  get embeddingLookupRef() {
+    return void 0;
+  }
 };
 
 // ../remnic-core/src/access-http.ts
@@ -48812,7 +49015,45 @@ var EngramMcpServer = class {
           },
           additionalProperties: false
         }
-      }] : []
+      }] : [],
+      // ── Contradiction Review (issue #520) ────────────────────────────────
+      {
+        name: "engram.review_list",
+        description: "List contradiction review items pending user resolution.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            filter: { type: "string", enum: ["all", "unresolved", "contradicts", "independent", "duplicates", "needs-user"], description: "Filter by verdict type. Default: unresolved." },
+            namespace: { type: "string" },
+            limit: { type: "number", description: "Max items to return (default 50)." }
+          },
+          additionalProperties: false
+        }
+      },
+      {
+        name: "engram.review_resolve",
+        description: "Resolve a contradiction pair with a chosen verb.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            pairId: { type: "string", description: "The contradiction pair ID to resolve." },
+            verb: { type: "string", enum: ["keep-a", "keep-b", "merge", "both-valid", "needs-more-context"], description: "Resolution action." }
+          },
+          required: ["pairId", "verb"],
+          additionalProperties: false
+        }
+      },
+      {
+        name: "engram.contradiction_scan_run",
+        description: "Run an on-demand contradiction scan over the memory corpus.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            namespace: { type: "string" }
+          },
+          additionalProperties: false
+        }
+      }
     ].flatMap((tool) => withToolAliases(tool));
   }
   service;
@@ -49419,6 +49660,39 @@ ${body}`;
           principal: effectivePrincipal
         });
       }
+      // ── Contradiction Review (issue #520) ──────────────────────────────────
+      case "engram.review_list":
+      case "remnic.review_list": {
+        const { listPairs } = await import("./contradiction-review-SVGBS3V5.js");
+        const filter = typeof args.filter === "string" ? args.filter : "unresolved";
+        const ns = typeof args.namespace === "string" ? args.namespace : void 0;
+        const limit = typeof args.limit === "number" ? args.limit : 50;
+        return listPairs(this.service.memoryDir, { filter, namespace: ns, limit });
+      }
+      case "engram.review_resolve":
+      case "remnic.review_resolve": {
+        const pairId = typeof args.pairId === "string" ? args.pairId : "";
+        const verb = typeof args.verb === "string" ? args.verb : "";
+        if (!pairId) throw new Error("pairId is required");
+        if (!verb) throw new Error("verb is required");
+        const { isValidResolutionVerb } = await import("./resolution-YITUVUTH.js");
+        if (!isValidResolutionVerb(verb)) throw new Error(`Invalid verb: ${verb}. Must be one of: keep-a, keep-b, merge, both-valid, needs-more-context`);
+        const { executeResolution } = await import("./resolution-YITUVUTH.js");
+        return executeResolution(this.service.memoryDir, this.service.storageRef, pairId, verb);
+      }
+      case "engram.contradiction_scan_run":
+      case "remnic.contradiction_scan_run": {
+        const { runContradictionScan } = await import("./contradiction-scan-LRRLWUOS.js");
+        return runContradictionScan({
+          storage: this.service.storageRef,
+          config: this.service.configRef,
+          memoryDir: this.service.memoryDir,
+          embeddingLookup: this.service.embeddingLookupRef,
+          localLlm: this.service.localLlmRef,
+          fallbackLlm: this.service.fallbackLlmRef,
+          namespace: typeof args.namespace === "string" ? args.namespace : void 0
+        });
+      }
       default:
         throw new Error(`unknown tool: ${name}`);
     }
@@ -50266,6 +50540,67 @@ var EngramAccessHttpServer = class {
       });
       return;
     }
+    if (req.method === "GET" && pathname === "/engram/v1/review/contradictions") {
+      const VALID_FILTERS = /* @__PURE__ */ new Set(["all", "unresolved", "contradicts", "independent", "duplicates", "needs-user"]);
+      const rawFilter = parsed.searchParams.get("filter") ?? "unresolved";
+      if (!VALID_FILTERS.has(rawFilter)) {
+        this.respondJson(res, 400, { error: `Invalid filter '${rawFilter}'. Valid: ${[...VALID_FILTERS].join(", ")}` });
+        return;
+      }
+      const namespace = parsed.searchParams.get("namespace") ?? void 0;
+      const limitRaw = parseInt(parsed.searchParams.get("limit") ?? "50", 10);
+      const { listPairs } = await import("./contradiction-review-SVGBS3V5.js");
+      const result = listPairs(this.service.memoryDir, {
+        filter: rawFilter,
+        namespace,
+        limit: Number.isFinite(limitRaw) ? limitRaw : 50
+      });
+      this.respondJson(res, 200, result);
+      return;
+    }
+    if (req.method === "GET" && pathname.startsWith("/engram/v1/review/contradictions/")) {
+      const pairId = pathname.split("/").pop() ?? "";
+      const { readPair } = await import("./contradiction-review-SVGBS3V5.js");
+      const pair = readPair(this.service.memoryDir, pairId);
+      if (!pair) {
+        this.respondJson(res, 404, { error: "pair_not_found" });
+        return;
+      }
+      this.respondJson(res, 200, pair);
+      return;
+    }
+    if (req.method === "POST" && pathname === "/engram/v1/review/resolve") {
+      const body = await this.readJsonBody(req);
+      const pairId = typeof body.pairId === "string" ? body.pairId : "";
+      const verb = typeof body.verb === "string" ? body.verb : "";
+      if (!pairId || !verb) {
+        this.respondJson(res, 400, { error: "pairId and verb are required" });
+        return;
+      }
+      const { isValidResolutionVerb, executeResolution } = await import("./resolution-YITUVUTH.js");
+      if (!isValidResolutionVerb(verb)) {
+        this.respondJson(res, 400, { error: `Invalid verb: ${verb}. Must be one of: keep-a, keep-b, merge, both-valid, needs-more-context` });
+        return;
+      }
+      const result = await executeResolution(this.service.memoryDir, this.service.storageRef, pairId, verb);
+      this.respondJson(res, 200, result);
+      return;
+    }
+    if (req.method === "POST" && pathname === "/engram/v1/contradiction-scan") {
+      const body = await this.readJsonBody(req);
+      const { runContradictionScan } = await import("./contradiction-scan-LRRLWUOS.js");
+      const result = await runContradictionScan({
+        storage: this.service.storageRef,
+        config: this.service.configRef,
+        memoryDir: this.service.memoryDir,
+        embeddingLookup: this.service.embeddingLookupRef,
+        localLlm: this.service.localLlmRef,
+        fallbackLlm: this.service.fallbackLlmRef,
+        namespace: typeof body.namespace === "string" ? body.namespace : void 0
+      });
+      this.respondJson(res, 200, result);
+      return;
+    }
     this.respondJson(res, 404, { error: "not_found", code: "not_found" });
   }
   async handleMcpRequest(req, res) {
@@ -51536,7 +51871,7 @@ async function runSemanticRulePromoteCliCommand(options) {
   });
 }
 async function runCompoundingPromoteCliCommand(options) {
-  const { CompoundingEngine: CompoundingEngine2 } = await import("./engine-BU6GNUJ5.js");
+  const { CompoundingEngine: CompoundingEngine2 } = await import("./engine-WGNTTFYE.js");
   const config = parseConfig({
     memoryDir: options.memoryDir,
     qmdEnabled: false,
@@ -55146,6 +55481,94 @@ Semantic consolidation complete. clusters=${result.clustersFound}, consolidated=
         }
         console.log(orchestrator.summarizer.formatForRecall(summaries, summaries.length));
       });
+      const reviewCmd = cmd.command("review").description("Manage contradiction review queue");
+      reviewCmd.command("list").description("List contradiction review items").option("--filter <type>", "Filter: all, unresolved, contradicts, independent, duplicates, needs-user", "unresolved").option("--namespace <ns>", "Filter by namespace").option("--limit <n>", "Max items (default 50)", "50").action(async (...args) => {
+        const options = args[0] ?? {};
+        const filter = options.filter ?? "unresolved";
+        const validFilters = ["all", "unresolved", "contradicts", "independent", "duplicates", "needs-user"];
+        if (!validFilters.includes(filter)) {
+          console.error(`Invalid filter: ${filter}. Must be one of: ${validFilters.join(", ")}`);
+          process.exit(1);
+        }
+        const limit = parseInt(options.limit ?? "50", 10);
+        const { listPairs } = await import("./contradiction-review-SVGBS3V5.js");
+        const result = listPairs(orchestrator.config.memoryDir, {
+          filter,
+          namespace: options.namespace,
+          limit: Number.isFinite(limit) ? limit : 50
+        });
+        if (result.pairs.length === 0) {
+          console.log("No review items found.");
+          return;
+        }
+        console.log(`Found ${result.total} item(s) (${result.durationMs}ms):
+`);
+        for (const pair of result.pairs) {
+          console.log(`  [${pair.verdict}] ${pair.pairId}`);
+          console.log(`    Memories: ${pair.memoryIds.join(", ")}`);
+          console.log(`    Rationale: ${pair.rationale}`);
+          console.log(`    Confidence: ${pair.confidence.toFixed(2)}`);
+          if (pair.resolution) console.log(`    Resolution: ${pair.resolution}`);
+          console.log();
+        }
+      });
+      reviewCmd.command("show <pairId>").description("Show details of a contradiction pair").action(async (...args) => {
+        const pairId = typeof args[0] === "string" ? args[0] : "";
+        if (!pairId) {
+          console.error("pairId is required");
+          process.exit(1);
+        }
+        const { readPair } = await import("./contradiction-review-SVGBS3V5.js");
+        const pair = readPair(orchestrator.config.memoryDir, pairId);
+        if (!pair) {
+          console.error(`Pair ${pairId} not found.`);
+          process.exit(1);
+        }
+        console.log(JSON.stringify(pair, null, 2));
+      });
+      reviewCmd.command("resolve <pairId>").description("Resolve a contradiction pair").requiredOption("--verb <verb>", "Resolution verb: keep-a, keep-b, merge, both-valid, needs-more-context").action(async (...args) => {
+        const pairId = typeof args[0] === "string" ? args[0] : "";
+        const cmdOpts = args[1] ?? {};
+        if (!pairId) {
+          console.error("pairId is required");
+          process.exit(1);
+        }
+        const verb = cmdOpts.verb;
+        if (!verb) {
+          console.error("--verb is required. Must be one of: keep-a, keep-b, merge, both-valid, needs-more-context");
+          process.exit(1);
+        }
+        const { isValidResolutionVerb, executeResolution } = await import("./resolution-YITUVUTH.js");
+        if (!isValidResolutionVerb(verb)) {
+          console.error(`Invalid verb: ${verb}. Must be one of: keep-a, keep-b, merge, both-valid, needs-more-context`);
+          process.exit(1);
+        }
+        const result = await executeResolution(orchestrator.config.memoryDir, orchestrator.storage, pairId, verb);
+        console.log(result.message);
+        if (result.affectedIds.length > 0) {
+          console.log(`Affected: ${result.affectedIds.join(", ")}`);
+        }
+      });
+      reviewCmd.command("scan").description("Run an on-demand contradiction scan").option("--namespace <ns>", "Namespace to scan").action(async (...args) => {
+        const options = args[0] ?? {};
+        const { runContradictionScan } = await import("./contradiction-scan-LRRLWUOS.js");
+        console.log("Running contradiction scan...");
+        const result = await runContradictionScan({
+          storage: orchestrator.storage,
+          config: orchestrator.config,
+          memoryDir: orchestrator.config.memoryDir,
+          embeddingLookup: void 0,
+          localLlm: orchestrator.localLlm ?? null,
+          fallbackLlm: null,
+          namespace: options.namespace
+        });
+        console.log(`Scan complete in ${result.elapsedMs}ms:`);
+        console.log(`  Scanned: ${result.scanned} memories`);
+        console.log(`  Candidates: ${result.candidates} pairs`);
+        console.log(`  Judged: ${result.judged}`);
+        console.log(`  Queued: ${result.queued}`);
+        console.log(`  Cooled down: ${result.cooledDown}`);
+      });
     },
     { commands: ["engram"] }
   );