@a9i5k4/dsh-auto-memory 2.2.6 → 2.3.0

package/lib/index.js

@@ -18,7 +18,7 @@
  */
 
 import { readFile, writeFile, mkdir, readdir, stat, rm, copyFile, appendFile, rename } from 'node:fs/promises'
-import { createReadStream, existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs'
+import { createReadStream, existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs'
 import { exec as cpExec } from 'node:child_process'
 import { promisify } from 'node:util'
 const execP = promisify(cpExec)
@@ -361,8 +361,8 @@ const DEFAULT_CONFIG = {
   procedurePromotionEnabled: false,
   /** ── M8 记忆中枢(Memory Hub)── 三层记忆(episodic/semantic/procedural)编排参数。
    *  所有参数都在设置页「记忆中枢」分组可调;默认值对应 M-02/M-03/M-04 元代码门槛。 */
-  /** 记忆中枢总开关(默认关;开启后消费 judgement-shadow + 三层 store 运行)。 */
-  memoryHubEnabled: false,
+  /** 记忆中枢总开关(2026-09-09 M8-3 经用户书面确认默认启用;开启后消费 judgement-shadow + 三层 store 运行;设置页「记忆中枢」开关可回滚)。 */
+  memoryHubEnabled: true,
   /** episodic: 一个 episode 至少多少段才巩固(少于=噪声丢弃)。默认 2。 */
   episodicMinSegments: 2,
   /** episodic: 保留的最多 episode 数(超出按时间淘汰)。默认 256。 */
@@ -1555,7 +1555,9 @@ class MemoryEngine {
     } catch (e) { return '' }
   }
 
-  /** 白板重写:旧 PLAN.md 有实质内容且与新内容不同时,先归档到 handoff/archive/PLAN-<ts>.md 再写新快照(保留更改历史)。 */
+  /** 白板重写:旧 PLAN.md 有实质内容且与新内容不同时,先归档到 handoff/archive/PLAN-<ts>.md 再写新快照(保留更改历史)。
+   *  P7(2026-09-09)白板老化:新内容中标题命中 /历史|踩坑|流水线要点/ 的顶层「## 」节移入 handoff/archive/PLAN-history-<ts>.md
+   *  (同秒多写 -b/-c 后缀防撞),PLAN.md 只留当前状态;内容只移动不删除;无匹配节 → 行为与旧版完全一致。 */
   async writePlanSnapshot(projectDir, content) {
     const dir = path.join(projectDir, 'handoff')
     const planPath = path.join(dir, 'PLAN.md')
@@ -1569,22 +1571,49 @@ class MemoryEngine {
         await writeFile(archPath, existing, 'utf8')
         archived = archPath
       }
-      await this.writeFullRaw(planPath, String(content || ''))
-      return { ok: true, path: planPath, archived }
+      // P7 白板老化(确定性节分类;移动不删除;全部节都命中时 fail-soft 放弃老化原样写入)
+      let finalContent = String(content || '')
+      let movedHistory = 0, historyPath = ''
+      const sections = finalContent.split(/(?=^## )/m)
+      if (sections.length > 1) {
+        const keep = [], hist = []
+        for (const sec of sections) {
+          const head = sec.split('\n', 1)[0] || ''
+          if (/^## .*(历史|踩坑|流水线要点)/.test(head)) hist.push(sec.replace(/\n+$/, ''))
+          else keep.push(sec)
+        }
+        // 兜底:老化后必须至少保留一个顶层节,否则(如全部节都命中)放弃老化原样写入,不留空白板
+        if (hist.length && keep.some((s) => /^## /.test((s.split('\n', 1)[0] || '')))) {
+          const archDir = path.join(dir, 'archive')
+          await mkdir(archDir, { recursive: true })
+          const base = 'PLAN-history-' + handoffStamp()
+          let hp = path.join(archDir, base + '.md')
+          for (let c = 98; c <= 122 && existsSync(hp); c++) { hp = path.join(archDir, base + '-' + String.fromCharCode(c) + '.md') }
+          await writeFile(hp, '# 白板历史归档 · ' + this.memToday() + ' ' + nowHm() + '\n\n' + hist.join('\n\n') + '\n', 'utf8')
+          finalContent = keep.join('').replace(/^\n+/, '')
+          movedHistory = hist.length
+          historyPath = hp
+        }
+      }
+      await this.writeFullRaw(planPath, finalContent)
+      return { ok: true, path: planPath, archived, movedHistory: movedHistory || undefined, historyPath: historyPath || undefined, final: finalContent }
     } catch (e) {
       return { ok: false, error: String((e && e.message) || e) }
     }
   }
 
-  /** 交接账本:每次一篇新文件(append-only 语料,不并入日志/笔记)。同秒多写用 -b/-c 后缀防撞且保持字典序=时间序。 */
+  /** 交接账本:每次一篇新文件(append-only 语料,不并入日志/笔记)。同秒多写用 -b/-c 后缀防撞且保持字典序=时间序。
+   *  P7(2026-09-09):标题行归属写入函数 —— 模型 content 自带的「交接账本」标题行一律剔除(实测最近 8 篇中
+   *  3 篇双标题且时间戳互相矛盾),正文零丢失仅去冗余标题元数据;剔除后正文经返回值 clean 带回供状态字段同步。 */
   async writeHandoffLedger(projectDir, content) {
     const dir = path.join(projectDir, 'handoff')
     const base = 'handoff-' + handoffStamp()
     let p = path.join(dir, base + '.md')
     try {
       for (let c = 98; c <= 122 && existsSync(p); c++) { p = path.join(dir, base + '-' + String.fromCharCode(c) + '.md') }
-      await this.writeFullRaw(p, '# 交接账本 · ' + this.memToday() + ' ' + nowHm() + '\n\n' + String(content || ''))
-      return { ok: true, path: p }
+      const clean = String(content || '').split(/\r?\n/).filter((l) => !/^#\s*交接账本/.test(l)).join('\n').replace(/^\n+/, '')
+      await this.writeFullRaw(p, '# 交接账本 · ' + this.memToday() + ' ' + nowHm() + '\n\n' + clean)
+      return { ok: true, path: p, clean }
     } catch (e) {
       return { ok: false, error: String((e && e.message) || e) }
     }
@@ -1876,7 +1905,15 @@ class MemoryEngine {
       const now = Date.now()
       if (rt && rt.waterStepAt && now - rt.waterStepAt < minGapMs) return
       if (rt) rt.waterStepAt = now
-      void this.checkWaterLevel(agent)
+      // 2.2.7 修复:pre-step 测到水位后同样 arm 自动接续 —— 旧实现只在 turn-stopping arm,
+      // 而官方压缩挂在 pre-step(80%)且长回合中轮末可能永远等不到 → 压缩抢先、接续从不触发。
+      // 这里 arm 的倒计时标记 awaitIdle,由 tickAutoContinue 在回合仍活跃时推迟执行,避免打断正在进行的回合。
+      void this.checkWaterLevel(agent).then(() => {
+        try {
+          const rt2 = this.runtimeFor(agent)
+          this.armAutoContinue(agent, { ratio: rt2.waterLevel, tokens: rt2.waterLevelTokens, window: rt2.waterLevelWindow, source: rt2.waterLevelSource }, { awaitIdle: true })
+        } catch (eArm) {}
+      }).catch(() => {})
     } catch (e) { diag('checkWaterLevelAtStep error: ' + (e && e.message)) }
   }
 
@@ -1885,7 +1922,7 @@ class MemoryEngine {
    *  默认 35s,写入 _autoContState)→ 浏览器轮询 GET auto-continue-state 显示确认卡(同意=POST decide
    *  agree,宿主立即执行;拒绝=POST decide reject,同一边界不再触发)→ 到期无人响应 → 宿主自动执行,
    *  与官方 SessionController service(ctx.get('sessionController'))同进程直调,不依赖浏览器。 */
-  armAutoContinue(agent, wl) {
+  armAutoContinue(agent, wl, opts = null) {
     try {
       if (!agent || !this.hasReliableSessionIdentity(agent)) return
       if (this.config.handoffEnabled === false) return
@@ -1910,8 +1947,11 @@ class MemoryEngine {
         tokens: Number(wl.tokens) || 0,
         window: Number(wl.window) || 0,
         source: String(wl.source || ''),
+        // 2.2.7:pre-step 侧 arm 的倒计时到期时,若回合仍活跃则推迟(避免打断进行中的对话)
+        awaitIdle: !!(opts && opts.awaitIdle),
+        deferCount: 0,
       }
-      diag('auto-continue armed: sid=' + sid + ' ratio=' + st.armed.ratio.toFixed(2) + ' expiresAt=' + st.armed.expiresAt)
+      diag('auto-continue armed: sid=' + sid + ' ratio=' + st.armed.ratio.toFixed(2) + ' awaitIdle=' + st.armed.awaitIdle + ' expiresAt=' + st.armed.expiresAt)
     } catch (e) { diag('armAutoContinue error: ' + (e && e.message)) }
   }
 
@@ -1921,6 +1961,18 @@ class MemoryEngine {
       const st = this._autoContState || (this._autoContState = {})
       if (!st.armed || st.executing) return
       if (Date.now() < st.armed.expiresAt) return
+      // 2.2.7:pre-step 侧 arm 的接续若恰逢回合仍活跃(30s 内有活动),推迟 20s 再评估,最多 5 次;
+      // 超过后仍执行(避免长任务里永不接续)。turn-stopping 侧 arm 不带 awaitIdle,行为不变。
+      if (st.armed.awaitIdle) {
+        const lastActive = Number(this._globalLastActiveAt) || 0
+        const busy = lastActive > 0 && Date.now() - lastActive < 30000
+        if (busy && (st.armed.deferCount || 0) < 5) {
+          st.armed.deferCount = (st.armed.deferCount || 0) + 1
+          st.armed.expiresAt = Date.now() + 20000
+          diag('auto-continue deferred (turn still active): count=' + st.armed.deferCount)
+          return
+        }
+      }
       diag('auto-continue deadline reached, executing host-side')
       await this.hostAutoContinue()
     } catch (e) { diag('tickAutoContinue error: ' + (e && e.message)) }
@@ -2155,17 +2207,28 @@ class MemoryEngine {
       const wsForSession = (pack && pack.cwd) || p.ws
       const workspaceId = this.resolveWorkspaceIdForSession(prevSid, wsForSession)
       const parts = [
-        '接续上一会话的任务。请先读完下面的交接材料恢复上下文,然后直接继续推进未完成事项,不要重新开始。',
+        '接续上一会话的任务。材料已分层,请按需取用而非通读:先看第0层白板建立全局图景,再视需要看第1层账本(含已试方案与失败原因)与第2层近期线程;第3层完整转写仅在前三层不足以推进时才 read。恢复上下文后直接继续推进未完成事项,不要重新开始。',
         '材料分层:第0层=指令+白板(全局图景);第1层=交接账本(四段式,最新);第2层=近期线程(最近 20 条,单条上限 700 字,保留角色与工具标记);第3层=完整转写(按需 read)。',
       ]
       if (plan) parts.push('【第0层 · 白板 PLAN.md(节选)】更新于 ' + fmtMt(planMt) + staleNote + NL + plan.slice(0, 3000))
-      if (ledger) parts.push('【第1层 · 交接账本 ' + (ledgerName || ledgerFrom) + '】写于 ' + fmtMt(ledgerMt) + ' (' + ledgerFrom + ')' + NL + ledger.slice(0, 8000))
+      if (ledger) {
+        // P6(2026-09-09):账本权重化截断 —— 按账本自身四段标题赋权(失败原因.35>下一步.30>目标.20>任务状态.15),
+        // 预算不足从最低权重段开始截(段标题保留)。解析失败/动态 import 失败 fail-soft 回落位置截断,绝不阻塞接续(I4)。
+        // 预算沿用现状 8000:handoffLedgerChars(默认 800)语义为动态快照注入预算(:3082),与 carry 层不同源,不复用。
+        let ledgerBody = ledger.slice(0, 8000)
+        try {
+          const { weightedTrimHandoffLedgerPre } = await import('./handoff-anchor.js')
+          const weighted = weightedTrimHandoffLedgerPre(ledger, 8000)
+          if (weighted != null) ledgerBody = weighted
+        } catch (eLedW) {}
+        parts.push('【第1层 · 交接账本 ' + (ledgerName || ledgerFrom) + '】写于 ' + fmtMt(ledgerMt) + ' (' + ledgerFrom + ')' + NL + ledgerBody)
+      }
       if (pack) {
         if (pack.tailText) parts.push('【第2层 · 近期线程(最近 ' + Math.min(20, Number(pack.msgCount) || 20) + ' 条 / 共 ' + (pack.msgCount || 0) + ' 条)】' + NL + pack.tailText)
         const guide = ['【第3层 · 完整转写与检索(按需)】']
         if (pack.transcriptPath) {
           guide.push('- 旧会话(' + pack.sessionId + ')的完整对话转写已写入: ' + pack.transcriptPath)
-          guide.push('- **接续前先用 read 工具读取该转写文件**,以完全理解旧会话的讨论、结论与未竟事项;任务推进中也可随时回读。')
+          guide.push('- 完整转写已归档,**不必在接续前通读**:仅在第0-2层不足以推进时再 read;优先用 memory_recall(scope=\'sessions\', query=\'关键词\') 定位片段,避免整篇读入。')
         } else {
           guide.push('- 旧会话 ID: ' + pack.sessionId + '(转写文件生成失败,可用 memory_recall 检索)')
         }
@@ -2174,6 +2237,28 @@ class MemoryEngine {
         if (pack.agentPreset) guide.push('- 旧会话 agentPreset: ' + pack.agentPreset + '(已随创建传递;注意 code→ptc 改名的历史会话需用户级兼容预设)。')
         parts.push(guide.join(NL))
       }
+      // P5(2026-09-09):接续锚点表 —— 用 T1 的 L0 抽取生成「记忆条目地图」,供新会话按需下钻
+      // (notesPath/logPath 正是 `<!-- memory:mem_<32hex> -->` 锚点的载体;纯解析零 LLM;字节稳定:
+      //  同输入 → 同抽取+同排序+同格式)。fail-soft:任何失败(读文件/动态 import/解析)→ 跳过整表,
+      //  材料回落现有平铺,绝不阻塞接续;表置于 parts 末尾 —— 预算超限时 slice(0,18000) 先截掉表,
+      //  等价于自动回退现有行为。
+      try {
+        const { buildL0IndexPre } = await import('./l0-extract.js')
+        const anchorSectionFor = async (label, file, cap) => {
+          const body = await this.readTextSafe(file)
+          if (!body) return ''
+          const rows = buildL0IndexPre(body, { maxChars: 48 }).slice(0, cap)
+          if (!rows.length) return ''
+          return '- ' + label + ':' + NL + rows.map((r) => '  - ' + String(r.id).slice(4, 12) + ' ' + r.l0).join(NL)
+        }
+        const anchorSections = (await Promise.all([
+          anchorSectionFor('工作区笔记', p.notesPath, 10),
+          anchorSectionFor('今日日志', p.logPath, 10),
+        ])).filter(Boolean)
+        if (anchorSections.length) {
+          parts.push('【锚点表 · 记忆条目地图(按需下钻,不必通读)】' + NL + anchorSections.join(NL))
+        }
+      } catch (eAnchor) {}
       // 接续序号:统计 handoff 目录里已有的 prev-session 包数量 +1(每次一键/自动接续产出一个)
       let contSeq = 1
       try { const prevs = (await readdir(p.handoffDir).catch(() => [])).filter((f) => /^prev-session-.*\.md$/.test(f)); contSeq = prevs.length + 1 } catch (eS) {}
@@ -3236,9 +3321,13 @@ class MemoryEngine {
   }
 
   // ---------- 检索 ----------
-  async recall(query, limit = 8, agent, scope = 'all') {
+  async recall(query, limit = 8, agent, scope = 'all', opts = null) {
+    // P4(2026-09-09):按需展开入口 —— opts.expand 指定 mem_<32hex> 时跳过检索,按锚点字节区间直接返回该条原文。
+    if (opts && opts.expand) return this.expandMemoryRecordPre(opts.expand, agent)
     const q = String(query || '').toLowerCase().trim()
     if (!q) return 'memory_recall: query 为空。'
+    // P4(2026-09-09):L0 模式开关 —— 工具层缺省 'l0';engine 直调不传 opts 保持旧行为。
+    const l0Mode = !!(opts && opts.format === 'l0')
     // 多词查询:按空白/中文标点分词,任一词命中即算命中(OR),按命中词数排序取相关度最高的
     const terms = q.split(/[\s,，、;；。:：]+/).filter((t) => t.length > 0)
     const p = await this.resolvePaths(agent)
@@ -3288,20 +3377,117 @@ class MemoryEngine {
       }
     }
     const logs = await this.listDailyLogs(p.projectDir, 40)
-    for (const log of logs) {
-      if (hits.length >= limit) break
-      await scanFile(log.name, path.join(p.projectDir, log.name), 2)
-    }
     const reflections = await this.listReflections(p.reflectDir, 30)
-    for (const r of reflections) {
-      if (hits.length >= limit) break
-      await scanFile('reflections/' + r.name, path.join(p.reflectDir, r.name), 2)
-    }
-    await scanFile('~' + p.userFile.slice(homedir().length), p.userFile)
-    await scanFile(p.projectDir + '/MEMORY.md', p.notesPath)
-    if (hits.length) {
-      out.push('== 本地记忆文件命中 ==')
-      for (const h of hits) out.push('· ' + h.where + ':\n' + h.matches.map((m) => '  - ' + m).join('\n'))
+    // P4(2026-09-09):L0 模式 —— 本地记忆段默认只列 L0 摘要(每条含 id/得分/匹配原因),原文经 expand="mem_xxx" 按需展开。
+    // 词法口径与词法臂一致(小写包含);语义分 fail-soft 叠加(_jsSemanticRank,与 P2 语义臂同源)。语料上限 256 对齐 P2。
+    if (l0Mode) {
+      const { buildL0IndexPre } = await import('./l0-extract.js')
+      const l0Corpus = []
+      const pushL0 = (label, text) => { if (text) for (const it of buildL0IndexPre(text)) l0Corpus.push({ id: it.id, l0: it.l0, label }) }
+      for (const log of logs) pushL0(log.name, await this.readTextSafe(path.join(p.projectDir, log.name)))
+      for (const rf of reflections) pushL0('reflections/' + rf.name, await this.readTextSafe(path.join(p.reflectDir, rf.name)))
+      pushL0(p.projectDir + '/MEMORY.md', await this.readTextSafe(p.notesPath))
+      pushL0('~' + p.userFile.slice(homedir().length), await this.readTextSafe(p.userFile))
+      if (l0Corpus.length > 256) l0Corpus.length = 256
+      for (const c of l0Corpus) {
+        const low = c.l0.toLowerCase()
+        const hitTerms = terms.filter((t) => low.includes(t))
+        c.lex = hitTerms.length
+        if (hitTerms.length) c.reason = '词法×' + hitTerms.length + '(' + hitTerms.slice(0, 3).join(',') + ')'
+      }
+      // P13:语义臂择优 —— python(c3 dense_search)优先,失败回 C2(_jsSemanticRank),lexical → 无语义臂。
+      // pyCorpus:与 context-host index-sync 同源的 corpus 快照(workspaceKey/scope/miv 须与已同步索引一致,
+      // 否则 worker 三重过滤拒绝 → 空 scores → 自动回退,不报错)。任何异常 → semScores=null → 纯词法。
+      let semScores = null
+      try {
+        const { createHash } = await import('node:crypto')
+        const canon = l0Corpus.map((c) => [c.id, c.l0]).sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+        const miv = 'idx_' + createHash('sha256').update(JSON.stringify(canon)).digest('hex').slice(0, 32)
+        const rankSnap = { memoryIndexVersion: miv, records: l0Corpus.map((c) => ({ memoryId: c.id, text: c.l0 })), pyPaths: { ws: p.ws || '', userFile: p.userFile, notesPath: p.notesPath, logPath: p.logPath } }
+        let rank = null
+        if (typeof this._semanticRankBest === 'function') rank = await this._semanticRankBest(rankSnap, query)
+        else if (typeof this._jsSemanticRank === 'function') rank = await this._jsSemanticRank(rankSnap, query)
+        if (rank && rank.scores && rank.scores.size) semScores = rank.scores
+      } catch (eBest) { try { diag('recall 语义臂择优降级: ' + String((eBest && eBest.message) || eBest).slice(0, 120)) } catch (_) {} }
+      if (semScores && semScores.size) {
+        for (const c of l0Corpus) {
+          const sc = semScores.get(c.id)
+          if (typeof sc === 'number' && sc >= 0.5) { c.sem = sc; c.reason = (c.reason ? c.reason + '+' : '') + '语义×' + sc.toFixed(2) }
+        }
+      }
+      // M8-2b(2026-09-09):evidence → importance → dense 臂加权因子。只读有界聚合(近 7 天/每文件末 400 行,
+      // 复用 :6876 证据读取范式);中性 0.5 → 因子 0.75 全体一致缩放=排序不变;correction 重则因子降至 0.5。
+      // 任何失败 → impMap 空 → 全体中性,绝不阻塞检索。importance 仅为加权因子之一,lex 臂不受影响。
+      const impMap = new Map()
+      try {
+        const { scanEvidenceEventsPre, aggregateEvidenceEventsPre } = await import('./evidence-agg.js')
+        const { computeImportancePre } = await import('./memory-importance.js')
+        const evDir = path.join(dshHome(), 'memory', 'evidence', 'events')
+        const agg = aggregateEvidenceEventsPre(scanEvidenceEventsPre({
+          listFiles: () => readdirSync(evDir).filter((x) => x.endsWith('.jsonl')),
+          readFile: (name) => readFileSync(path.join(evDir, name), 'utf8'),
+        }, {}))
+        for (const [mid, a] of agg) impMap.set(mid, computeImportancePre(a).importance)
+      } catch (eImp) { try { diag('evidence-agg 降级为中性(impMap 空): ' + String((eImp && eImp.message) || eImp).slice(0, 140)) } catch (_) {} }
+      const l0Hits = l0Corpus.filter((c) => c.lex > 0 || (typeof c.sem === 'number' && c.sem >= 0.5))
+      // 时间臂(2026-09-09):查询含中文时间表达 → 解析 [startMs,endMs),候选 label 中的日志日期
+      // (YYYY-MM-DD)命中 → temp=1 软提升;非日期来源(MEMORY.md/~userfile)不给 temp(中性)。
+      // 软性第三臂只提升不硬过滤;查询无时间表达 → tr=null → 不传 temp → 与现状逐字节一致。
+      let tr = null
+      let dateMsOf = null
+      try {
+        const tp = await import('./temporal-parse.js')
+        tr = tp.parseTemporalQueryPre(query, { now: Date.now() })
+        dateMsOf = tp.labelToDateMsPre
+      } catch (eTr) { try { diag('temporal-parse 降级(无时间臂): ' + String((eTr && eTr.message) || eTr).slice(0, 140)) } catch (_) {} }
+      const tempFieldOf = (c) => {
+        if (!tr || typeof dateMsOf !== 'function') return undefined
+        const d = dateMsOf(c.label)
+        if (d === null || d === undefined) return undefined
+        return d >= tr.startMs && d < tr.endMs ? 1 : 0
+      }
+      // P8(2026-09-09):RRF 融合排序取代 lex 绝对主导的字典序(旧排序下 sem 仅在 lex 全等时平局生效=语义臂实效为零)。
+      // rank-space 1/(k+rank/divisor),k=60 复用 FUSION_RRF_K_V1(Hindsight #3956:禁止 score-space 加权)。
+      // 开关 opts.fusion:'rrf'(默认)|'legacy';dense 臂=sem(缺席→null 臂贡献 0,等价纯词法),lex 臂=词命中数。
+      // fail-soft:动态 import 失败/任何异常 → 回落 legacy 字典序;_jsSemanticRank 抛错时 sem 全空,RRF 自动退化为纯词法序。
+      let l0Top = null
+      if ((opts && opts.fusion) !== 'legacy') {
+        try {
+          const { rankFusionRRFPre } = await import('./recall-fusion.js')
+          const byId = new Map(l0Hits.map((c) => [c.id, c]))
+          l0Top = rankFusionRRFPre(l0Hits.map((c) => ({ memoryId: c.id, dense: typeof c.sem === 'number' ? c.sem * (0.5 + 0.5 * (impMap.get(c.id) != null ? impMap.get(c.id) : 0.5)) : null, lex: c.lex, temp: tempFieldOf(c) })))
+            .map((f) => byId.get(f.memoryId))
+            .filter(Boolean)
+            .slice(0, Math.max(1, Number(limit) || 8))
+        } catch (eRrf) {}
+      }
+      if (!l0Top) {
+        l0Top = l0Hits.slice()
+          .sort((a, b) => b.lex - a.lex || (b.sem || 0) - (a.sem || 0) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+          .slice(0, Math.max(1, Number(limit) || 8))
+      }
+      if (l0Top.length) {
+        out.push('== L0 命中(摘要,含 id/得分/匹配原因;展开单条原文传 expand="mem_xxx") ==')
+        for (const c of l0Top) {
+          const sc = typeof c.sem === 'number' ? c.sem.toFixed(2) : String(c.lex)
+          out.push('· [' + c.id + '] ×' + sc + ' ' + (c.reason || '语义') + ' ' + c.label + ' — ' + c.l0)
+        }
+      }
+    } else {
+      for (const log of logs) {
+        if (hits.length >= limit) break
+        await scanFile(log.name, path.join(p.projectDir, log.name), 2)
+      }
+      for (const r of reflections) {
+        if (hits.length >= limit) break
+        await scanFile('reflections/' + r.name, path.join(p.reflectDir, r.name), 2)
+      }
+      await scanFile('~' + p.userFile.slice(homedir().length), p.userFile)
+      await scanFile(p.projectDir + '/MEMORY.md', p.notesPath)
+      if (hits.length) {
+        out.push('== 本地记忆文件命中 ==')
+        for (const h of hits) out.push('· ' + h.where + ':\n' + h.matches.map((m) => '  - ' + m).join('\n'))
+      }
     }
     // 其他 DSH 工作区记忆(跨工作区检索:从 sessions 发现的所有工作区,任何模型/新会话都能查到)
     const otherHits = []
@@ -3341,10 +3527,85 @@ class MemoryEngine {
         for (const l of sessionLines) out.push(l)
       }
     } catch (e) {}
+    // P2(2026-09-09):语义臂 —— 输入用 T1 的 L0(≈160 字符/条)而非全文(e5 512 token 上限会截断),
+    // 与词法臂互补:主题性查询("发布踩坑")可召回词法不重合但语义相关的记忆。
+    // fail-soft:非 C2 环境(_jsSemanticRank=null)/动态 import 失败/任何异常 → 跳过语义节,
+    // 纯词法照常返回,不报错不阻塞。词法臂与全文展示零改动;recall 签名与工具 schema 零改动。
+    // P4:l0Mode 时语义分已并入 L0 列表(match_reason),独立语义节跳过防重复注入。
+    if (scope === 'all' && !l0Mode && typeof this._jsSemanticRank === 'function') {
+      try {
+        const { buildL0IndexPre } = await import('./l0-extract.js')
+        const { createHash } = await import('node:crypto')
+        const semanticArm = async (env) => {
+          const corpus = []
+          for (const src of env.sources) {
+            const text = await this.readTextSafe(src.path)
+            if (!text) continue
+            const items = env.buildL0IndexPre(text)
+            for (const it of items) corpus.push({ memoryId: it.id, text: it.l0, label: src.label })
+            if (corpus.length >= env.maxRecords) break
+          }
+          if (!corpus.length) return []
+          corpus.length = Math.min(corpus.length, env.maxRecords)
+          // 语料版本:canonical sorted [id,L0] 元组哈希(idx_ 前缀匹配 rank() 校验);同语料同 miv → 引擎嵌入缓存命中
+          const canon = corpus.map((c) => [c.memoryId, c.text]).sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+          const miv = 'idx_' + env.createHash('sha256').update(JSON.stringify(canon)).digest('hex').slice(0, 32)
+          const rank = await this._jsSemanticRank({ memoryIndexVersion: miv, records: corpus.map((c) => ({ memoryId: c.memoryId, text: c.text })) }, env.query)
+          if (!rank || !rank.scores || !rank.scores.size) return []
+          return [...rank.scores.entries()]
+            .filter(([, sc]) => sc >= env.minScore)
+            .sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+            .slice(0, Math.max(2, env.limit))
+            .map(([id, sc]) => {
+              const rec = corpus.find((c) => c.memoryId === id) || {}
+              return { label: rec.label || '', id8: String(id).slice(4, 12), score: sc, l0: rec.text || '' }
+            })
+        }
+        const semSources = []
+        for (const log of logs) semSources.push({ label: log.name, path: path.join(p.projectDir, log.name) })
+        for (const rf of reflections) semSources.push({ label: 'reflections/' + rf.name, path: path.join(p.reflectDir, rf.name) })
+        semSources.push({ label: p.projectDir + '/MEMORY.md', path: p.notesPath })
+        semSources.push({ label: '~' + p.userFile.slice(homedir().length), path: p.userFile })
+        const semHits = await semanticArm({ sources: semSources, buildL0IndexPre, createHash, query, limit, maxRecords: 256, minScore: 0.5 })
+        if (semHits.length) {
+          out.push('== 语义命中(L0 摘要,按相关度;可按锚点下钻) ==')
+          for (const s of semHits) out.push('· ' + s.label + ' [' + s.id8 + '] ×' + s.score.toFixed(2) + ' ' + s.l0)
+        }
+      } catch (eSem) {}
+    }
     if (!out.length) return '[记忆检索] 查询 "' + q + '" —— 未找到相关记忆。'
     return '[记忆检索] "' + q + '":\n' + out.join('\n')
   }
 
+  /** P4(2026-09-09):按 mem_<32hex> 展开记忆原文。复用 parseAnchors 的字节区间定位(UTF-8 半开 [byteStart,byteEnd)
+   *  + recordDigest,memory-anchor.js:82),每条原文=锚点标记之后到下一条标记之前的切片,天然不串条。
+   *  搜索面与 L0 语料同源(当前项目日志/反思/项目笔记/用户级记忆);找不到如实回报,不猜测不串条。 */
+  async expandMemoryRecordPre(id, agent) {
+    const mid = String(id || '').trim()
+    if (!/^mem_[0-9a-f]{32}$/.test(mid)) return 'memory_recall: expand 需要合法记忆 id(mem_ + 32 个十六进制字符),收到: ' + mid.slice(0, 64)
+    const p = await this.resolvePaths(agent)
+    const sources = []
+    for (const log of await this.listDailyLogs(p.projectDir, 40)) sources.push({ label: log.name, path: path.join(p.projectDir, log.name) })
+    for (const r of await this.listReflections(p.reflectDir, 30)) sources.push({ label: 'reflections/' + r.name, path: path.join(p.reflectDir, r.name) })
+    sources.push({ label: p.projectDir + '/MEMORY.md', path: p.notesPath })
+    sources.push({ label: '~' + p.userFile.slice(homedir().length), path: p.userFile })
+    const searched = []
+    for (const src of sources) {
+      searched.push(src.label)
+      let buf
+      try { buf = await readFile(src.path) } catch (e) { continue }
+      if (buf.length > INDEX_MAX_FILE_BYTES) continue
+      let parsed
+      try { parsed = parseAnchors(buf) } catch (e) { continue }
+      const rec = (parsed.records || []).find((r) => r.kind === 'anchored' && r.memoryId === mid)
+      if (!rec) continue
+      const body = buf.subarray(rec.byteStart, rec.byteEnd).toString('utf8').trim()
+      if (!body) continue
+      return '[记忆展开] ' + mid + ' ← ' + src.label + '(第 ' + rec.lineStart + '-' + rec.lineEnd + ' 行,' + rec.chars + ' 字符,digest ' + String(rec.recordDigest).slice(0, 16) + ')\n' + body
+    }
+    return '[记忆展开] 未找到 ' + mid + '(已搜索: ' + searched.join('、') + ')。该条可能在其他工作区/已归档文件中,可换关键词重检索。'
+  }
+
   /** 多关键词扫描三层记忆(供智能检索用),返回 {where, line} 列表。 */
   async collectHits(keywords, limit) {
     const p = await this.resolvePaths(undefined)
@@ -4075,6 +4336,8 @@ class MemoryEngine {
 
   /** 调用 DSH subagent 发散/提炼一段文本(90s 超时,结果取 text 块;parent 用最近 agent)。 */
   async runSubagent(text, label, agent, timeoutMs) {
+    // 2.2.7:插件 context 已卸载(重启/禁用中)→ 不再 spawn,避免向失效 context 注册 effect
+    if (this._disposed) return ''
     const subagents = this._subagents
     if (!subagents) return ''
     // 配置性错误熔断(问题③):UNKNOWN_MODEL 等错误不会自愈,熔断期内直接返回空,不再反复 spawn(卡顿根因)
@@ -4106,7 +4369,8 @@ class MemoryEngine {
     const cfgProvider = String(this.config.subagentProvider || '').trim()
     if (cfgProvider && Array.isArray(registered) && registered.includes(cfgProvider)) providerName = cfgProvider
     const controller = new AbortController()
-    const timer = setTimeout(() => controller.abort(label + ' timeout'), Math.max(Number(timeoutMs) || 90000, 1000))
+    const tMs = Math.max(Number(timeoutMs) || 90000, 1000)
+    const timer = setTimeout(() => controller.abort(label + ' timeout'), tMs)
     let run
     try {
       // prompt 必须是 block 数组(createUserMessage 校验 content.some)
@@ -4121,13 +4385,16 @@ class MemoryEngine {
         ...(subModel ? { agentOptions: { model: subModel } } : {}),
       })
       // 套娃防护(问题②):登记本插件 spawn 的子代理,其生命周期事件在 pre-step/turn-stopping 零处理
-      try { if (run && run.agent) this._ownSubagents.add(run.agent) } catch (eReg) {}
+      // 2026-09-09 修复:DSH 0.1.2 in-process run 对象字段为 localAgent(旧版为 agent),取两者兼容
+      try { const ra = run && (run.localAgent || run.agent); if (ra) this._ownSubagents.add(ra) } catch (eReg) {}
       // UNKNOWN_MODEL 自保:子代理路由为两源拼接(provider 继承父会话 + 模型落宿主全局默认),
       // 父 provider 目录可能不含该模型(如 opencode-go-free × deepseek-v4-flash);
       // 此时回退用父会话抽屉当前模型(settings.yaml agent-default-model)重试一次。
       let result
       try {
-        result = await run.result
+        // 2026-09-09 修复:run.result 依赖 child.whenIdle() 且 DSH 无内置超时,卡死会泄漏 inflight 并使 finally 不执行。
+        // 包 withTimeout 兜底(超时返回 null → 空结果),保证 finally 的递减/dispose/回收总能跑。
+        result = await this.withTimeout(run.result, tMs, null)
       } catch (eRoute) {
         const em0 = eRoute && eRoute.message ? String(eRoute.message) : ''
         if (!/UNKNOWN_MODEL|has no configured model/.test(em0)) throw eRoute
@@ -4151,12 +4418,17 @@ class MemoryEngine {
           ...(parent ? { parent } : {}),
           agentOptions: { model: fbModel },
         })
-        result = await run2.result
+        result = await this.withTimeout(run2.result, tMs, null)
       }
       const blocks = result && result.output ? result.output : []
       return blocks.filter((b) => b && b.type === 'text').map((b) => b.text).join('').trim()
     } catch (e) {
       const em = e && e.message ? e.message : String(e)
+      // 2.2.7:context 已卸载导致的 effect 创建失败是重启/卸载竞态,不是功能缺陷 —— 只记一次 diag,不刷屏
+      if (/inactive context/i.test(em)) {
+        if (!this._inactiveWarned) { this._inactiveWarned = true; diag('subagent ' + label + ' skipped: plugin context inactive (宿主已卸载,重启后自动恢复)') }
+        return ''
+      }
       console.error('[dsh-auto-memory] ' + label + ' failed', em)
       diag('subagent ' + label + ' failed: ' + em)
       // 配置性错误熔断(问题③):UNKNOWN_MODEL / 无配置模型 / 供应商不含该模型——重试无意义,30 分钟内不再 spawn
@@ -4174,7 +4446,9 @@ class MemoryEngine {
       }
       // 子代理痕迹回收(2026-09-08):本插件的一次性子代理(auto-memory-*)结束即把会话目录移入备份,
       // 避免 ~/.dsh/sessions 下插件痕迹堆积拖慢宿主会话列表。失败静默,由每日兜底巡检补收。
-      if (run && run.agent) { try { await this.recycleSubagentSession(run.agent) } catch (e3) {} }
+      // 2026-09-09 修复:DSH 0.1.2 run 对象字段为 localAgent(旧版为 agent),旧写法 run.agent 恒 undefined 导致回收永不触发(子代理爆炸)
+      const runAgent = run && (run.localAgent || run.agent)
+      if (runAgent) { try { await this.recycleSubagentSession(runAgent) } catch (e3) {} }
     }
   }
 
@@ -4188,13 +4462,30 @@ class MemoryEngine {
       const sid = session && (session.id || (header && header.id)) ? String(session.id || header.id) : ''
       if (!sid) return { ok: false, reason: 'no-id' }
       if (!header || header.origin !== 'subagent') return { ok: false, reason: 'not-subagent' }
+      // 2.3.0:Windows 下 DSH 常持有会话文件句柄(子代理刚结束时仍在写)→ rename 抛 EPERM。
+      // 同一 sid 失败后冷却 30 分钟不再尝试(避免刷屏),占用释放后由每日 sweep 兜底回收。
+      const cool = this._gcCooldown || (this._gcCooldown = new Map())
+      const coolUntil = cool.get(sid) || 0
+      if (Date.now() < coolUntil) return { ok: false, reason: 'cooldown' }
       const dir = await this.locateSessionDir(sid, header)
       if (!dir) return { ok: false, reason: 'not-located' }
       const wsDir = path.basename(path.dirname(dir))
       const backupRoot = path.join(dshHome(), 'subagent-gc-backup')
       const dest = path.join(backupRoot, wsDir, sid)
       await mkdir(path.dirname(dest), { recursive: true })
-      await rename(dir, dest)
+      let renamed = false
+      let lastErr = null
+      for (const delay of [0, 300, 1000]) {
+        if (delay) await new Promise((r) => setTimeout(r, delay))
+        try { await rename(dir, dest); renamed = true; break } catch (e) { lastErr = e }
+      }
+      if (!renamed) {
+        cool.set(sid, Date.now() + 30 * 60 * 1000)
+        // 首次失败记 diag,后续静默(同一 sid 冷却期内不再刷屏)
+        const warned = this._gcWarned || (this._gcWarned = new Set())
+        if (!warned.has(sid)) { warned.add(sid); diag('subagent gc deferred (file locked by host): ' + sid) }
+        return { ok: false, reason: 'locked', sid }
+      }
       // 投影缓存同步移走,避免孤儿条目长期占用索引
       try {
         const cacheFile = path.join(dshHome(), 'storages', 'session_projcache', 'sessions', sid)
@@ -4244,9 +4535,11 @@ class MemoryEngine {
       const keepDays = Math.max(0, Number(this.config.subagentGcKeepDays) || 0)
       const scan = await scanPluginSubagentSessions({ sessionsRoot, labelPrefix: PLUGIN_LABEL_PREFIX, keepMs: 0 })
       const now = Date.now()
-      // 无论保留期多长,最近 10 分钟的一律不动(可能与正在运行的子代理竞争)
-      const floorMs = Math.max(keepDays * 24 * 3600 * 1000, 10 * 60 * 1000)
-      const eligible = scan.candidates.filter((c) => now - c.mtimeMs >= floorMs)
+      // 无论保留期多长,最近 60 分钟的一律不动(2.3.0:Windows 下宿主可能长期持有会话文件句柄,
+      // 10 分钟窗口不足以判断"已不再写入";占用中的目录 rename 必失败)
+      const floorMs = Math.max(keepDays * 24 * 3600 * 1000, 60 * 60 * 1000)
+      const cool = this._gcCooldown || (this._gcCooldown = new Map())
+      const eligible = scan.candidates.filter((c) => now - c.mtimeMs >= floorMs && now >= (cool.get(c.sid) || 0))
       if (!eligible.length) return { ok: true, scanned: scan.scanned, recycled: 0 }
       const res = await recycleSessions({
         candidates: eligible,
@@ -4255,6 +4548,8 @@ class MemoryEngine {
         apply: true,
       })
       diag('subagent gc sweep: recycled=' + res.moved.length + ' failed=' + res.failed.length + ' bytes=' + res.bytes)
+      // 2.3.0:被占用的目录进入 30 分钟冷却,避免每日巡检重复无效重试
+      for (const f of res.failed || []) { if (f && f.sid) cool.set(String(f.sid), Date.now() + 30 * 60 * 1000) }
       return { ok: true, scanned: scan.scanned, recycled: res.moved.length, failed: res.failed.length, bytes: res.bytes }
     } catch (e) {
       diag('subagent gc sweep failed: ' + (e && e.message ? e.message : String(e)))
@@ -5840,6 +6135,63 @@ export function apply(ctx, config) {
         return await engine._jsSemantic.rank(corpusSnap, queryText)
       } catch (_) { return null }
     }
+    // P13(2026-09-09):C3(python)语义臂 —— 经 sidecar recall_rank 调 worker.dense_search
+    // (三重过滤:workspaceRef+scope+miv),返回 {scores:Map<memoryId,score>, source:'c3'}。
+    // 前提:tier=c3,或 auto 档且 python 模型就绪(auto 先探 python,失败回 C2,见 _semanticRankBest)。
+    // 任何失败(sidecar 抛错/超时/空/档位不符)→ null → 调用方 fail-soft 回退。
+    engine._pythonModelReady = async () => {
+      try {
+        const fsMod = await import('node:fs')
+        const pyCands = (engine._pythonSetup ? [engine._pythonSetup.modelPath()] : []).concat([
+          path.join(pluginRootDir(), 'python', 'bench', 'models-xenova-bge-m3-int8', 'onnx', 'model_int8.onnx'),
+        ])
+        return pyCands.some((c) => fsMod.existsSync(c))
+      } catch (_) { return false }
+    }
+    engine._pySemanticRank = async (corpusSnap, queryText) => {
+      try {
+        const tier = await engine.resolveSemanticTier()
+        const autoProbe = String(engine.config.semanticEngineMode || 'auto') === 'auto'
+        if (tier !== 'c3' && !(autoProbe && await engine._pythonModelReady())) return null
+        const sc = engine._pythonSidecar
+        if (!sc || typeof sc.request !== 'function') return null
+        // 语料快照:与 context-host index-sync 同源(buildSourceCatalog+CorpusRegistry)。
+        // workspaceKey/scope/miv 须与已同步索引一致,否则 worker 三重过滤拒绝 → 空 scores → 回退。
+        let py = null
+        const pp = corpusSnap && corpusSnap.pyPaths
+        if (pp && pp.ws) {
+          const cat = buildSourceCatalog({ workspaceKey: pp.ws, userMemoryPath: pp.userFile, workspaceMemoryPath: pp.notesPath, todayLogPath: pp.logPath })
+          if (!engine._pyRankCorpusRegistry) engine._pyRankCorpusRegistry = new CorpusRegistry({ sidecarDir: path.join(dshHome(), 'memory', 'index', 'files') })
+          const res = engine._pyRankCorpusRegistry.get(cat)
+          if (res && res.ok && res.snapshot.memoryIndexVersion) {
+            py = { workspaceKey: canonicalize(pp.ws), scope: 'Workspace', memoryIndexVersion: res.snapshot.memoryIndexVersion }
+          }
+        }
+        if (!py) return null
+        const r = await sc.request('recall_rank', {
+          workspaceKey: py.workspaceKey, scope: py.scope || 'Workspace',
+          miv: py.memoryIndexVersion, query: queryText, topK: 20,
+        }, { timeoutMs: 8000 })
+        if (!r || !r.ok || !r.frame || !r.frame.payload) return null
+        const arr = r.frame.payload.scores || []
+        const scores = new Map()
+        for (const it of arr) {
+          if (it && typeof it.memoryId === 'string' && typeof it.score === 'number' && Number.isFinite(it.score)) scores.set(it.memoryId, it.score)
+        }
+        return scores.size ? { scores, source: 'c3' } : null
+      } catch (_) { return null }
+    }
+    // P13 择优:lexical → null;python 档 → _pySemanticRank;auto → 先 py(模型就绪,失败回 C2);js/C2 → _jsSemanticRank。
+    // 逐级 fail-soft,任何一级失败自动落到下一级,绝不抛错阻塞检索。_jsSemanticRank 保留不动(激活路径仍在用)。
+    engine._semanticRankBest = async (corpusSnap, queryText) => {
+      try {
+        const mode = String(engine.config.semanticEngineMode || 'auto')
+        if (mode === 'lexical') return null
+        const r = await engine._pySemanticRank(corpusSnap, queryText)
+        if (r) return r
+      } catch (_) { /* fall through */ }
+      try { return await engine._jsSemanticRank(corpusSnap, queryText) } catch (_) { return null }
+    }
     // JS 端判定核(2026-08-27):读策略工件(懒加载+缓存),对 C2 检索结果做 fv2 决策。
     // 完全独立于 Python——JS 端默认闭环(C2 检索 + JS 判定 + M6 投递)的核心。
     engine._jsDecideCtx = null
@@ -5957,6 +6309,11 @@ export function apply(ctx, config) {
   const sessionQuery = ctx.get('sessionQuery')
   engine._sessionQuery = sessionQuery
   engine._subagents = ctx.get('subagents') || undefined
+  // 2.2.7 修复:宿主 context 卸载后,残留的定时器/面板请求仍会调 runSubagent,
+  // DSH 0.1.2 的 in-process 子代理会向已失效 context 注册 effect → "cannot create effect on inactive context" 刷屏。
+  // 记 dispose 标记,runSubagent 入口直接短路。
+  engine._disposed = false
+  try { ctx.on('dispose', () => { engine._disposed = true }) } catch (eDispose) {}
   // 时间检测用的服务(软获取,缺失时定时兜底自动降级)
   engine._sessionsSvc = ctx.get('sessions') || undefined
   engine._agentSvc = ctx.get('agent') || undefined
@@ -6219,8 +6576,8 @@ export function apply(ctx, config) {
           ? await engine.writePlanSnapshot(p.projectDir, writeH)
           : await engine.writeHandoffLedger(p.projectDir, writeH)
         if (!r || !r.ok) return 'memory_note: 白板写入失败(' + ((r && r.error) || '未知') + ')。'
-        if (args.kind === 'plan') { engine.state.planText = writeH; engine.state.loadedAt = Date.now() }
-        else { engine.state.latestHandoffText = '# 交接账本 · ' + engine.memToday() + ' ' + nowHm() + '\n\n' + writeH; engine.state.loadedAt = Date.now() }
+        if (args.kind === 'plan') { engine.state.planText = (r && r.final) || writeH; engine.state.loadedAt = Date.now() }
+        else { engine.state.latestHandoffText = '# 交接账本 · ' + engine.memToday() + ' ' + nowHm() + '\n\n' + ((r && r.clean) || writeH); engine.state.loadedAt = Date.now() }
         return (args.kind === 'plan'
           ? '白板 PLAN.md 已更新' + (r.archived ? '(旧版已归档: ' + r.archived + ')' : '(首建)') + ': ' + r.path
           : '交接账本已写入: ' + r.path) + '\n请在本轮回复正文向用户转述本次更新要点。'
@@ -6299,11 +6656,13 @@ export function apply(ctx, config) {
         : label + '(' + file + '):\n' + text
     }),
 
-    defineTool('memory_recall', '检索记忆:本地记忆文件(当前工作区 + 其他所有工作区的每日日志、项目笔记、用户级记忆、反思、交接白板)关键词匹配 + 历史 DSH 会话全文检索(如部署启用)。开发/排查中不懂的、用户提到过去的做法/讨论/决定而当前上下文没有时调用——跨工作区的记忆也能检索到(结果标注来源工作区)。查询必须自包含。scope=handoff 只搜交接白板语料(白板 PLAN+交接账本——接续长任务时先查这里);scope=sessions 只搜历史会话。**检索后必须在本轮回复正文中向用户转述:检索了什么、找到什么(或没找到)**。', {
-      query: { type: 'string', required: true, description: '检索关键词或自包含描述。' },
+    defineTool('memory_recall', '检索记忆:本地记忆文件(当前工作区 + 其他所有工作区的每日日志、项目笔记、用户级记忆、反思、交接白板)关键词匹配 + 历史 DSH 会话全文检索(如部署启用)。开发/排查中不懂的、用户提到过去的做法/讨论/决定而当前上下文没有时调用——跨工作区的记忆也能检索到(结果标注来源工作区)。查询必须自包含。默认返回 L0 摘要列表(每条含 id/得分/匹配原因,省 token);需要某条完整原文时传 expand="mem_xxx" 按需展开(渐进式加载)。scope=handoff 只搜交接白板语料(白板 PLAN+交接账本——接续长任务时先查这里);scope=sessions 只搜历史会话。**检索后必须在本轮回复正文中向用户转述:检索了什么、找到什么(或没找到)**。', {
+      query: { type: 'string', required: true, description: '检索关键词或自包含描述;expand 时填该记忆 id 即可。' },
       limit: { type: 'integer', description: '最多返回条数,缺省 8。' },
       scope: { type: 'string', enum: ['all', 'handoff', 'sessions'], description: '检索范围:all=全部(默认), handoff=交接白板语料(跨窗口续命材料), sessions=历史 DSH 会话。' },
-    }, async (args, exec) => engine.recall(args.query, args.limit, exec.agent, args.scope || 'all')),
+      format: { type: 'string', enum: ['l0', 'full'], description: '本地记忆命中格式:l0=L0 摘要列表(默认,每条含 id/得分/匹配原因),full=整条原文(旧行为)。' },
+      expand: { type: 'string', description: '按记忆 id(mem_ + 32 个十六进制字符)展开该条完整原文;提供时忽略检索语义。' },
+    }, async (args, exec) => engine.recall(args.query, args.limit, exec.agent, args.scope || 'all', { format: args.format || 'l0', expand: args.expand })),
 
     defineTool('memory_maintain', '维护记忆(30 天蒸馏):把 days(缺省30)天前的 .dsh-memory/ 每日日志交给 AI 蒸馏提炼出有长期价值的要点写入项目 MEMORY.md,原文保底归档到 .dsh-memory/archive/ 后从活跃日志移除。AI 不可用时降级为原样归档,不丢信息。', {
       days: { type: 'integer', description: '归档阈值天数,缺省 30。' },