recallnest 2.3.0 → 2.6.0

package/src/cli.ts

@@ -11,16 +11,19 @@
 
 import { Command } from "commander";
 import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";
 
 import { metaDir } from "./compat.js";
+import { PACKAGE_VERSION } from "./version.js";
 import type { RetrievalResult } from "./retriever.js";
 import { applyRetrievalProfile, listRetrievalProfiles } from "./retrieval-profiles.js";
 import { distillResults, formatExplainResults, formatSearchResults, selectBriefSeedResults, summarizeResults } from "./memory-output.js";
 import { archiveDirtyBriefAsset, assetSummaryLine, buildBriefAsset, buildPinAsset, getExportsDir, listDirtyBriefAssets, listMemoryAssets, listPinAssets, pinSummaryLine, saveBriefAsset, savePinAsset, writeExportArtifact } from "./memory-assets.js";
 import { indexAsset, indexPinnedAsset } from "./asset-sync.js";
-import { createComponents, createStoreOnly, expandHome, loadConfig, loadDotEnv, type LocalMemoryConfig } from "./runtime-config.js";
+import { createComponents, createStoreOnly, expandHome, loadConfig, loadDotEnv, resolveDbPath, type LocalMemoryConfig } from "./runtime-config.js";
+import { KGStore } from "./kg-store.js";
+import { isKGModeEnabled } from "./kg-extractor.js";
 import {
   formatDedupReasonSummary,
   getDedupSkipRate,
@@ -28,12 +31,16 @@ import {
   ingestCCTranscripts,
   ingestCodexSessions,
   ingestGeminiSessions,
+  ingestKimiSessions,
   ingestMarkdownFiles,
   ingestObsidianVault,
   ingestConnectorFile,
 } from "./ingest.js";
 import { runDoctor, formatDoctorResults } from "./doctor.js";
 import { persistCaseMemory, persistMemory, persistWorkflowPattern } from "./capture-engine.js";
+import { scanMemoryPromotions, buildPromoteScanDeps, formatPromoteScanResult } from "./memory-promotion.js";
+import { runDream, formatDreamResult, formatDreamMetrics, DEFAULT_DREAM_CONFIG, classifyDreamFailure, shouldBlockDreamRun, partitionAutoDreamScopes } from "./dream-pipeline.js";
+import { listScopesAboveThreshold } from "./activity-counter.js";
 import {
   CaseMemoryInputSchema,
   type CaseMemoryInput,
@@ -47,6 +54,7 @@ import { ConflictStatusSchema } from "./conflict-schema.js";
 import { resolveConflictCandidate } from "./conflict-engine.js";
 import { escalateConflicts } from "./conflict-escalation.js";
 import { ConflictCandidateStore } from "./conflict-store.js";
+import { createAuditLogger } from "./audit-log.js";
 import { formatConflictAudit, formatConflictAuditMarkdown, formatConflictClusters, formatConflictEscalation, formatConflictList, formatConflictRecord, formatConflictResolution } from "./conflict-output.js";
 import { CONFLICT_ATTENTION_LEVELS, parseConflictAttention, summarizeConflictLifecycle } from "./conflict-lifecycle.js";
 import { buildConflictAuditSummary, clusterConflicts, summarizeConflictAdvice } from "./conflict-advisor.js";
@@ -63,49 +71,66 @@ import {
 } from "./workflow-observation-scope-review.js";
 import { collectScopeInventory, formatScopeInventoryReport } from "./scope-inventory.js";
 import { buildRetrievalContext, resolveScopeSelection } from "./scope-policy.js";
+import { createScopeSuggester } from "./scope-suggester.js";
 
 /**
- * Auto-detect Claude Code transcript directory.
- * Scans ~/.claude/projects/ for subdirectories containing .jsonl files.
+ * Auto-detect Claude Code transcript directories.
+ * Scans ~/.claude/projects/ for ALL subdirectories containing .jsonl files.
+ *
+ * CC 按 cwd 编码 project 子目录，凡是不在 ~ 下跑的会话（Codex spawn 的子进程 / cd 到 repo 跑 /
+ * bridge 临时工作目录）会落到 ~/.claude/projects/-XXX/ 别的子目录。旧版只挑 jsonl 最多的根
+ * 目录返回，导致 28+ 个子目录全失声。修复：返回所有有 jsonl 的子目录，调用方循环 ingest。
  */
-function detectCCPath(): string | null {
+function detectCCPath(): string[] {
   const projectsDir = join(homedir(), ".claude", "projects");
-  if (!existsSync(projectsDir)) return null;
+  if (!existsSync(projectsDir)) return [];
   try {
-    const dirs = readdirSync(projectsDir, { withFileTypes: true })
+    return readdirSync(projectsDir, { withFileTypes: true })
       .filter(d => d.isDirectory())
-      .map(d => join(projectsDir, d.name));
-    // Pick the directory with most .jsonl files
-    let best = "";
-    let bestCount = 0;
-    for (const dir of dirs) {
-      const jsonlCount = readdirSync(dir).filter(f => f.endsWith(".jsonl")).length;
-      if (jsonlCount > bestCount) {
-        bestCount = jsonlCount;
-        best = dir;
-      }
-    }
-    return best || null;
+      .map(d => join(projectsDir, d.name))
+      .filter(dir => {
+        try { return readdirSync(dir).some(f => f.endsWith(".jsonl")); }
+        catch { return false; }
+      });
   } catch {
-    return null;
+    return [];
   }
 }
 
+/**
+ * Pick the CC project subdirectory with the most jsonl files (heuristic: user's primary cwd).
+ * Used by memory source which still expects a single directory.
+ */
+function pickPrimaryCCPath(detected: string[]): string {
+  let best = detected[0];
+  let bestCount = 0;
+  for (const dir of detected) {
+    try {
+      const c = readdirSync(dir).filter(f => f.endsWith(".jsonl")).length;
+      if (c > bestCount) { bestCount = c; best = dir; }
+    } catch { /* skip */ }
+  }
+  return best;
+}
+
 /**
  * Resolve "auto" paths in config to actual directories.
+ *
+ * Note: cc 分支只返回第一个 detect 到的目录（fallback），ingest 入口已改为直接调
+ * detectCCPath() 拿全量子目录循环处理。这里保留是为兼容潜在的其它调用方。
  */
 function resolveSourcePath(source: string, key: string): string {
   if (source !== "auto") return expandHome(source);
 
   if (key === "cc") {
     const detected = detectCCPath();
-    if (!detected) throw new Error("Could not auto-detect Claude Code transcript path. Set sources.cc.path in config.json.");
-    return detected;
+    if (detected.length === 0) throw new Error("Could not auto-detect Claude Code transcript path. Set sources.cc.path in config.json.");
+    return pickPrimaryCCPath(detected);
   }
   if (key === "memory") {
-    const ccPath = detectCCPath();
-    if (!ccPath) throw new Error("Could not auto-detect memory path. Set sources.memory.path in config.json.");
-    return join(ccPath, "memory");
+    const detected = detectCCPath();
+    if (detected.length === 0) throw new Error("Could not auto-detect memory path. Set sources.memory.path in config.json.");
+    return join(pickPrimaryCCPath(detected), "memory");
   }
   throw new Error(`Cannot auto-detect path for source "${key}". Set it manually in config.json.`);
 }
@@ -130,7 +155,7 @@ const program = new Command();
 program
   .name("recallnest")
   .description("本地优先 AI 对话记忆搜索与蒸馏层")
-  .version("1.4.0");
+  .version(PACKAGE_VERSION);
 
 async function runRetrievalView(
   view: "search" | "explain" | "distill",
@@ -147,7 +172,7 @@ async function runRetrievalView(
   },
 ) {
   const config = loadConfig();
-  const { retriever, profile } = createComponents(config, options.profile);
+  const { retriever, profile, store } = createComponents(config, options.profile);
 
   const limit = parseLimitOption(options.limit, 5, 1, 20);
 
@@ -206,6 +231,17 @@ async function runRetrievalView(
       : formatSearchResults(results, context);
 
   console.log(rendered);
+
+  // P1-A: 显式 scope 0 命中 → 相近 scope 提示打到 stderr(不污染 stdout)
+  if (results.length === 0 && options.scope) {
+    try {
+      const suggest = createScopeSuggester(async () => (await store.stats()).scopeCounts);
+      const suggestions = (await suggest(options.scope)).filter(s => s !== options.scope);
+      if (suggestions.length > 0) {
+        console.error(`⚠️ scope '${options.scope}' 命中 0 条,相近 scope: [${suggestions.join(", ")}]`);
+      }
+    } catch { /* best-effort */ }
+  }
 }
 
 function parseLimitOption(value: string | undefined, fallback: number, min = 1, max = 50): number {
@@ -644,6 +680,28 @@ program
     ].join("\n"));
   });
 
+program
+  .command("promote-scan")
+  .description("扫描 transcript 降级的 profile/preferences evidence，聚类高频高 importance 项晋升回 durable")
+  .requiredOption("--scope <scope>", "要扫描的 scope，如 cc:project:recallnest")
+  .option("--apply", "执行晋升；默认 dry-run 只预览")
+  .option("--min-occurrences <n>", "聚类最小成员数（默认 3）", "3")
+  .option("--min-importance <n>", "聚类最小平均 importance（默认 0.6）", "0.6")
+  .action(async (options) => {
+    const config = loadConfig();
+    const { store, embedder } = createComponents(config);
+    const conflictStore = new ConflictCandidateStore();
+    const deps = buildPromoteScanDeps({ store, embedder, conflictStore });
+    const minOccurrences = Number(options.minOccurrences);
+    const minImportance = Number(options.minImportance);
+    const result = await scanMemoryPromotions(deps, options.scope, {
+      dryRun: !options.apply,
+      ...(Number.isFinite(minOccurrences) ? { minOccurrences } : {}),
+      ...(Number.isFinite(minImportance) ? { minImportance } : {}),
+    });
+    console.log(formatPromoteScanResult(result));
+  });
+
 program
   .command("export <query>")
   .description("导出检索与蒸馏结果到 markdown/json")
@@ -1054,7 +1112,7 @@ program
         continue;
       }
 
-      const record = await persistWorkflowPattern({ store, embedder, conflictStore }, input);
+      const record = await persistWorkflowPattern({ store, embedder, conflictStore, auditLogger: createAuditLogger() }, input);
       existingKeys.add(key);
       stored.push({ title: record.title, id: record.id, scope: record.resolvedScope });
     }
@@ -1130,7 +1188,7 @@ program
         continue;
       }
 
-      const record = await persistCaseMemory({ store, embedder, conflictStore }, input);
+      const record = await persistCaseMemory({ store, embedder, conflictStore, auditLogger: createAuditLogger() }, input);
       existingKeys.add(key);
       stored.push({ title: record.title, id: record.id, scope: record.resolvedScope });
     }
@@ -1208,7 +1266,7 @@ program
         continue;
       }
 
-      const record = await persistMemory({ store, embedder, conflictStore }, input);
+      const record = await persistMemory({ store, embedder, conflictStore, auditLogger: createAuditLogger() }, input);
       existingKeys.add(storeMemoryIdentity({
         category: input.category,
         scope: record.resolvedScope,
@@ -1302,7 +1360,7 @@ program
 program
   .command("ingest")
   .description("导入对话记录到索引")
-  .option("-s, --source <source>", "数据源: cc / codex / memory / desktop / all", "all")
+  .option("-s, --source <source>", "数据源: cc / codex / gemini / kimi / memory / desktop / all", "all")
   .option("-l, --limit <n>", "限制处理文件数（调试用）")
   .option("-v, --verbose", "详细输出")
   .option("--no-dedup", "跳过向量去重")
@@ -1345,8 +1403,10 @@ program
     console.log(`  ✅ ${config.embedding.model} (${testResult.dimensions}d)`);
 
     // LLM status — respect --no-llm flag
-    const effectiveLlm = options.noLlm ? null : llm;
-    if (options.noLlm) {
+    // commander 把 --no-llm 解析成 options.llm=false（不产生 options.noLlm），对齐 --no-dedup 的取反键写法
+    const noLlm = options.llm === false;
+    const effectiveLlm = noLlm ? null : llm;
+    if (noLlm) {
       console.log("  ⚠️  LLM: 已通过 --no-llm 禁用，原始对话将跳过不存入");
     } else if (llm) {
       const llmTest = await llm.test();
@@ -1376,15 +1436,23 @@ program
     const ingestOpts = { limit, verbose, noDedup, llm: effectiveLlm, recentHours };
 
     // CC Transcripts
+    // CC 按 cwd 编码 project 子目录，所有有 jsonl 的子目录都要 ingest（不只是 jsonl 最多的那个）
     if (source === "all" || source === "cc") {
       console.log("📝 导入 Claude Code 对话...");
       const ccSource = config.sources.cc;
       if (ccSource) {
-        const ccPath = resolveSourcePath(ccSource.path, "cc");
-        const r = await ingestCCTranscripts(store, embedder, ccPath, ingestOpts);
-        results.push(r);
-        console.log(`  ✅ CC: ${formatIngestSummary(r)}`);
-        maybeWarnHighCCDedupRate(r);
+        const ccPaths = ccSource.path === "auto"
+          ? detectCCPath()
+          : [expandHome(ccSource.path)];
+        if (ccPaths.length === 0) {
+          throw new Error("Could not auto-detect Claude Code transcript path. Set sources.cc.path in config.json.");
+        }
+        for (const ccPath of ccPaths) {
+          const r = await ingestCCTranscripts(store, embedder, ccPath, ingestOpts);
+          results.push(r);
+          console.log(`  ✅ CC [${basename(ccPath)}]: ${formatIngestSummary(r)}`);
+          maybeWarnHighCCDedupRate(r);
+        }
       }
     }
 
@@ -1396,6 +1464,14 @@ program
       console.log(`  ✅ Codex: ${formatIngestSummary(r)}`);
     }
 
+    // Kimi Code Sessions (wire.jsonl 事件流，~/.kimi-code/sessions/)
+    if (source === "all" || source === "kimi") {
+      console.log("🌙 导入 Kimi Code 对话...");
+      const r = await ingestKimiSessions(store, embedder, ingestOpts);
+      results.push(r);
+      console.log(`  ✅ Kimi: ${formatIngestSummary(r)}`);
+    }
+
     // Gemini Sessions (JSON format under ~/.gemini/tmp/*/chats/)
     if (source === "all" || source === "gemini") {
       console.log("💎 导入 Gemini 对话...");
@@ -1403,7 +1479,7 @@ program
         limit,
         verbose,
         noDedup,
-        llm,
+        llm: effectiveLlm,
         recentHours,
       });
       results.push(r);
@@ -1436,7 +1512,7 @@ program
         const r = await ingestMarkdownFiles(store, embedder, memPath, "memory", {
           verbose,
           noDedup,
-          llm,
+          llm: effectiveLlm,
           recentHours,
         });
         results.push(r);
@@ -1502,6 +1578,155 @@ program
     console.log();
   });
 
+// ─── dream ───────────────────────────────────────────────────────────────────
+// P3 调度化入口:launchd 经 scripts/dream-consolidation.sh 调用本命令,
+// 输出 [[DREAM_STATUS]] ok|skip|blocked 标记供脚本判定(同 weekly-distill 的
+// [[DISTILL_STATUS]] 模式)。dream 是 auto-gc / usageStatus 快照 / consolidation
+// 的唯一生产触发点——没有它们整条维护链就是死代码(2026-06-11 临床重审实锤)。
+
+program
+  .command("dream")
+  .description("运行 dream 离线整固管线 (Orient/Gather/Consolidate/Prune)")
+  .option("--scope <scope>", "目标 scope(前缀或精确)", "cc")
+  .option("--auto", "扫描 activity-counter 中写计数达标的所有 scope，逐个跑 dream（单 scope 失败不阻断其他）")
+  .option("--force", "跳过 min-writes 门槛强制运行")
+  .action(async (options: { scope: string; auto?: boolean; force?: boolean }) => {
+    const config = loadConfig();
+    const { store, embedder, llm } = createComponents(config);
+    // Same activity-stats file the store writes per-scope counts to (beside the LanceDB dir).
+    const activityStatsPath = join(dirname(store.dbPath), "activity-stats.json");
+    // KG evidence for triple-overlap merging — same gate as the MCP server
+    const kgStore = isKGModeEnabled() ? new KGStore({ dbPath: store.dbPath }) : null;
+
+    if (options.auto) {
+      const eligible = listScopesAboveThreshold(DEFAULT_DREAM_CONFIG.minWritesForDream, { statsPath: activityStatsPath });
+      // 巨型 scope 交给专用 schedule,不占日常轮次的 wall-clock 预算(理由见
+      // DreamConfig.autoExcludeScopes:07-30 那轮 6h 只跑了 15/507,而 memory 独占 79% 的条数)。
+      const { run: scopes, deferred } = partitionAutoDreamScopes(eligible, DEFAULT_DREAM_CONFIG.autoExcludeScopes);
+      if (deferred.length > 0) {
+        // 不静默:被挪走的 scope 必须在日志里看得见,否则"今天怎么没跑 memory"只能靠翻代码回答。
+        // 前缀刻意用 `[dream]` 而不是 `dream --auto:`——后者是 dream-checkup.sh 抓「达标 scope 数」
+        // 的锚点,多一行同前缀的会混进它的取数。
+        console.log(`[dream] ${deferred.length} 个 scope 交给专用 schedule，本轮不跑 → ${deferred.join(", ")}`);
+      }
+      if (scopes.length === 0) {
+        // 两种空:一种是真没人达标,一种是达标的全被挪走了——混成一句会让排障从这里开始跑偏。
+        console.log(
+          eligible.length === 0
+            ? "dream --auto: 无达标 scope（写计数均低于门槛）"
+            : "dream --auto: 达标 scope 全部交给专用 schedule，本轮无事可做",
+        );
+        console.log("[[DREAM_STATUS]] skip");
+        process.exit(0);
+      }
+      console.log(`dream --auto: ${scopes.length} 个达标 scope → ${scopes.join(", ")}`);
+
+      // Wall-clock 预算(2026-07-29 补)：防单轮跑成跨天。07-24 那轮跑了 4 天 15 小时，
+      // 把 07-25~27 三天的调度全堵死（上一次没结束，launchd 起不了新的）。
+      // 天花板见 DreamConfig.autoRunBudgetMs 的注释——截断会让靠后 scope 系统性饿死，
+      // 真解是 session scope TTL，不是把预算调大。
+      const budgetMs = Number(process.env.RECALLNEST_DREAM_BUDGET_MS ?? DEFAULT_DREAM_CONFIG.autoRunBudgetMs);
+      const deadline = Date.now() + budgetMs;
+
+      let fatalFailures = 0;
+      let transientFailures = 0;
+      let processed = 0;
+      // 2026-08-12 产出计量：`[[DREAM_STATUS]] ok` 只证明「没崩」，不证明「产出了东西」。
+      // 2026-07-23 查出的语义阈值卡在真实 p99 之上，就是这样静默跑了 2716 次零 insight
+      // 而无人察觉 —— 当时日志里每一轮都是 ok。
+      const tally = { produced: 0, noop: 0, partial: 0, skipped: 0 };
+      let effectsTotal = 0;
+      const degradedScopes: string[] = [];
+      for (const scope of scopes) {
+        if (Date.now() > deadline) {
+          console.warn(
+            `[dream] wall-clock 预算 ${Math.round(budgetMs / 60_000)} 分钟耗尽：已处理 ` +
+              `${processed}/${scopes.length}，剩余 ${scopes.length - processed} 个 scope 本轮跳过`,
+          );
+          break;
+        }
+        processed++;
+        try {
+          const result = await runDream({ store, llm, embedder, scope, force: Boolean(options.force), activityStatsPath, kgStore });
+          tally[result.output.kind]++;
+          effectsTotal += result.output.effectsWritten;
+          if (result.output.degraded) degradedScopes.push(`${scope}=${result.output.degraded}`);
+          console.log(`[scope=${scope}] ${formatDreamResult(result)}`);
+        } catch (err) {
+          // 单 scope 失败不阻断其他 scope。
+          // 打完整 stack 而不只是 message：像「Array.from requires an array-like object」
+          // 这种原生错误，只有 message 时根本定位不到是哪一行抛的——2026-07-18/19 连着两天
+          // 因此 blocked，回头查日志除了这一句什么线索都没有，只能靠猜。
+          // 分类基于 message（不是 stack）：stack 里的文件路径不该参与判定。
+          const message = err instanceof Error ? err.message : String(err);
+          if (classifyDreamFailure(message) === "transient") transientFailures++;
+          else fatalFailures++;
+          console.error(`[scope=${scope}] dream failed: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+        }
+      }
+
+      // 旧语义是「任一 scope 抛异常即 blocked」，在 475 个 scope 的规模下等于「有一个撞上
+      // store-write 锁就整轮红」，而整轮红会让 shell 脚本重试 → 重跑全量。改为：代码/数据
+      // 缺陷一票否决，环境性失败要成规模才算整轮失败。比例按已处理数算，不按总数。
+      // 结构性降级一票否决：它不是「今天数据不成簇」（那是合法的 noop），而是某条路径
+      // 整段断了 —— 向量管线空、或压根没配 LLM。判据只认确定性零值，不含任何阈值，
+      // 所以不会因为数据分布变化而误伤（详见 assertDreamSweepHealth 的注释）。
+      const structurallyBroken = degradedScopes.length > 0;
+      if (structurallyBroken) {
+        console.error(`[dream] ⚠ 结构性降级 ${degradedScopes.length} 个 scope：${degradedScopes.join(", ")}`);
+      }
+      const blocked = shouldBlockDreamRun({ totalScopes: processed, fatalFailures, transientFailures })
+        || structurallyBroken;
+      if (fatalFailures > 0 || transientFailures > 0) {
+        console.log(`[dream] 失败统计：fatal=${fatalFailures} transient=${transientFailures}（已处理 ${processed}）`);
+      }
+      // 这一行是 dream-consolidation.sh 存在性闸的锚点：STATUS=ok 却没有它 = 判失败。
+      // 它防的是「断言本身被某次重构悄悄删掉」—— 一个不需要调参的自检。
+      console.log(formatDreamMetrics({
+        tally,
+        degraded: degradedScopes.length,
+        effects: effectsTotal,
+        processed,
+        total: scopes.length,
+      }));
+      console.log(blocked ? "[[DREAM_STATUS]] blocked" : "[[DREAM_STATUS]] ok");
+      process.exit(blocked ? 1 : 0);
+    }
+
+    try {
+      const result = await runDream({
+        store,
+        llm,
+        embedder,
+        scope: options.scope,
+        force: Boolean(options.force),
+        activityStatsPath,
+        kgStore,
+      });
+
+      console.log(formatDreamResult(result));
+      // 单 scope 也必须打产出计量：dream-consolidation.sh 的存在性闸对 STATUS=ok
+      // 一视同仁地要求这行，而本分支此前从不打 —— 08-12 那道闸上线后，周日的
+      // memory 轮次即使跑成功也会被判"产出断言缺失"。tally 在这里只有一格是 1。
+      const tally = { produced: 0, noop: 0, partial: 0, skipped: 0 };
+      tally[result.output.kind] = 1;
+      console.log(formatDreamMetrics({
+        tally,
+        degraded: result.output.degraded ? 1 : 0,
+        effects: result.output.effectsWritten,
+        processed: 1,
+        total: 1,
+      }));
+      console.log(result.ran ? "[[DREAM_STATUS]] ok" : "[[DREAM_STATUS]] skip");
+      process.exit(0);
+    } catch (err) {
+      // 同 --auto 分支：带 stack，否则原生错误无从定位。
+      console.error(`dream failed: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+      console.log("[[DREAM_STATUS]] blocked");
+      process.exit(1);
+    }
+  });
+
 // ─── stats ───────────────────────────────────────────────────────────────────
 
 program
@@ -1611,7 +1836,7 @@ program
     }
 
     const config = loadConfig();
-    const dbPath = resolve(metaDir(import.meta), "..", expandHome(config.dbPath));
+    const dbPath = resolveDbPath(config);
 
     if (existsSync(dbPath)) {
       const { rmSync } = await import("node:fs");
@@ -1723,6 +1948,7 @@ program
   .option("--task <task>", "相关任务")
   .option("--tags <tags>", "逗号分隔 tags")
   .option("--tools <tools>", "逗号分隔 tools")
+  .option("--idempotency-key <key>", "同一请求重试时用于替换旧 observation 的稳定键")
   .option("--json", "输出 JSON")
   .action(async (workflowId, summary, options) => {
     const store = new WorkflowObservationStore();
@@ -1736,6 +1962,7 @@ program
       task: options.task,
       tags: splitCsvOption(options.tags),
       tools: splitCsvOption(options.tools),
+      idempotencyKey: options.idempotencyKey,
     });
     const stored = await store.save(record);
     if (options.json) {

package/src/confidence-tracker.ts

@@ -261,50 +261,68 @@ export function buildContradictPatch(
 // Convenience wrappers (for callers who DO have a store)
 // ---------------------------------------------------------------------------
 
+/** 单写通道端口：读改写经 store.patchMetadata per-id 队列，防并发覆盖。 */
+type ConfidenceStorePort = {
+  patchMetadata(
+    id: string,
+    patchFn: (meta: Record<string, unknown>, entry: MemoryEntry) => Record<string, unknown>,
+    scopeFilter?: string[],
+  ): Promise<MemoryEntry | null>;
+};
+
+function applyConfidencePatch(
+  store: ConfidenceStorePort,
+  entryId: string,
+  scope: string,
+  build: (entry: MemoryEntry) => ConfidencePatch | null,
+): Promise<ConfidenceUpdate | null> {
+  let update: ConfidenceUpdate | null = null;
+  return store
+    .patchMetadata(
+      entryId,
+      (meta, entry) => {
+        const patch = build(entry);
+        if (!patch) return meta;
+        update = patch.update;
+        return patch.metadata;
+      },
+      [scope],
+    )
+    .then(result => (result === null ? null : update));
+}
+
 /**
  * Confirm a memory and write back to store. Convenience wrapper.
  */
 export async function confirmMemory(
-  store: { getById(id: string): Promise<MemoryEntry | null>; update(id: string, data: { metadata: string }, scopes: string[]): Promise<void> },
+  store: ConfidenceStorePort,
   entryId: string,
   scope: string,
 ): Promise<ConfidenceUpdate | null> {
-  const entry = await store.getById(entryId);
-  const patch = buildConfirmPatch(entry);
-  if (!patch) return null;
-  await store.update(entryId, { metadata: JSON.stringify(patch.metadata) }, [scope]);
-  return patch.update;
+  return applyConfidencePatch(store, entryId, scope, entry => buildConfirmPatch(entry));
 }
 
 /**
  * Correct a memory and write back to store. Convenience wrapper.
  */
 export async function correctMemory(
-  store: { getById(id: string): Promise<MemoryEntry | null>; update(id: string, data: { metadata: string }, scopes: string[]): Promise<void> },
+  store: ConfidenceStorePort,
   entryId: string,
   scope: string,
   correctedById?: string,
 ): Promise<ConfidenceUpdate | null> {
-  const entry = await store.getById(entryId);
-  const patch = buildCorrectPatch(entry, correctedById);
-  if (!patch) return null;
-  await store.update(entryId, { metadata: JSON.stringify(patch.metadata) }, [scope]);
-  return patch.update;
+  return applyConfidencePatch(store, entryId, scope, entry => buildCorrectPatch(entry, correctedById));
 }
 
 /**
  * Contradict a memory and write back to store. Convenience wrapper.
  */
 export async function contradictMemory(
-  store: { getById(id: string): Promise<MemoryEntry | null>; update(id: string, data: { metadata: string }, scopes: string[]): Promise<void> },
+  store: ConfidenceStorePort,
   entryId: string,
   scope: string,
 ): Promise<ConfidenceUpdate | null> {
-  const entry = await store.getById(entryId);
-  const patch = buildContradictPatch(entry);
-  if (!patch) return null;
-  await store.update(entryId, { metadata: JSON.stringify(patch.metadata) }, [scope]);
-  return patch.update;
+  return applyConfidencePatch(store, entryId, scope, entry => buildContradictPatch(entry));
 }
 
 // ---------------------------------------------------------------------------

package/src/conflict-engine.ts

@@ -9,6 +9,8 @@ import {
   parseMetadataObject,
 } from "./memory-boundaries.js";
 import type { MemoryStore } from "./store.js";
+import { archiveBeliefVersion, buildSupersedingBeliefMetadata } from "./belief-history.js";
+import { parseEvolution } from "./memory-evolution.js";
 import {
   type ConflictCandidateInput,
   ConflictCandidateInputSchema,
@@ -95,7 +97,8 @@ function buildMergedConflictMetadata(
 }
 
 export interface ResolveConflictDeps {
-  store: Pick<MemoryStore, "getById" | "update">;
+  // `store`/`upsert` are needed to archive the belief being replaced before overwriting it.
+  store: Pick<MemoryStore, "getById" | "update" | "store"> & Partial<Pick<MemoryStore, "upsert">>;
   embedder: Pick<Embedder, "embedPassage">;
   conflictStore: Pick<ConflictCandidateStore, "getById" | "replace">;
 }
@@ -144,13 +147,31 @@ export async function resolveConflictCandidate(
     }
 
     const vector = await deps.embedder.embedPassage(nextText);
+
+    // Conflict resolution is the most deliberate belief change there is — accepting the
+    // incoming version or merging both used to overwrite the existing row in place, losing
+    // precisely the "before" side of the decision. Archive it first.
+    const resolvedAtMs = Date.now();
+    const previousEvo = parseEvolution(existing.metadata, existing.timestamp);
+    const { historyId } = await archiveBeliefVersion(
+      { store: deps.store, embedder: deps.embedder },
+      existing,
+      { now: resolvedAtMs },
+    );
+
     const updated = await deps.store.update(existing.id, {
       text: nextText,
       vector,
       importance: nextImportance,
       category: nextCategory,
-      metadata: nextMetadata,
-      timestamp: Date.now(),
+      metadata: buildSupersedingBeliefMetadata(
+        nextMetadata,
+        previousEvo,
+        historyId,
+        resolvedAtMs,
+        `conflict:${input.resolution}`,
+      ),
+      timestamp: resolvedAtMs,
     });
     if (!updated) {
       throw new Error(`Failed to update durable memory ${existing.id}`);