@yolk_vat-y/dsh-project-memory 0.5.5 → 0.5.7

package/src/auto-inject.js

@@ -9,13 +9,15 @@ import { createHash } from 'node:crypto'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { ProjectMemoryStore } from './store.js'
 import { memoryRootFor } from './util/fs.js'
-import { insightMatchText } from './similarity.js'
-import { normalizedTokenOverlap } from './similarity.js'
+import { insightMatchText, normalizedTokenOverlap } from './similarity.js'
+import { BoundedMap, SessionCache } from './util/session-cache.js'
 import { cfgInsight, GlobalStore, defaultGlobalFile } from './insight-store.js'
 import { projectTags } from './project-profile.js'
 import { rankEntriesMergedScored } from './util/search.js'
-import { insightToEntry } from './recall.js'
-import { buildReadinessContext, hintQueryText, matchTrigger, relativeHits } from './readiness.js'
+import { insightToEntry, insightScoringText } from './recall.js'
+import { buildReadinessContext, hintQueryText, idfCoverage, matchTrigger, normalizeTrigger, relativeHits } from './readiness.js'
+import { activityFromCalls } from './ops.js'
+import { appendInjectionAudit, auditRecordFrom, cfgAudit } from './audit.js'
 
 export const INJECT_MARK = '[Memory Inject]'
 
@@ -40,6 +42,8 @@ export function cfgEngine(config) {
     relevanceMin: typeof c.relevanceMin === 'number' ? c.relevanceMin : null,
     // resident 任务卡最多显示几个"编辑中"文件（纯写权重，最近写优先）
     editedMax: typeof c.editedMax === 'number' ? c.editedMax : 3,
+    // 常驻任务卡总开关（entryOn:false = 只做条目注入，不回声任务卡）
+    entryOn: c.entryOn !== false,
     // 模型自己写/维护任务清单后、尚无新人类消息时，不把任务卡再回声给模型（省 token）
     skipEchoSelfTodo: c.skipEchoSelfTodo !== false,
     // 预算审计日志级别（stderr）。默认 off：预算挤掉低优先级条目是正常降级，不是故障，
@@ -52,6 +56,25 @@ export function cfgEngine(config) {
     // 0（默认）= 内容没变就不再注入：注入消息会留在会话历史里（宿主不压缩历史），
     // 整块重发同一条 1200 字 procedure 只是重复占位。>0 用于历史可能被外部裁剪的场景。
     reinjectItemsAfter: typeof c.reinjectItemsAfter === 'number' && c.reinjectItemsAfter >= 0 ? c.reinjectItemsAfter : 0,
+    // ---- S2/S3/S4 新增（准入化改造） ----
+    // 旧 `scope` 的处理：'filter'（默认，保留旧语义——不静默改用户数据）或 'ignore'。
+    // 注意：实测里唯一带 scope 的条目，其值不在项目画像 tag 空间内，等于被判死刑；
+    // 自检会把它报出来，由作者决定改值还是改语义。
+    legacyScope: c.legacyScope === 'ignore' ? 'ignore' : 'filter',
+    // 条目通道的步间隔：两次"条目注入"之间至少隔这么多步（常驻任务卡不受限——它是状态快照，
+    // 内容变了就该更新）。这是"不频繁"的主要旋钮。
+    gateCooldownSteps: typeof c.gateCooldownSteps === 'number' && c.gateCooldownSteps >= 0 ? c.gateCooldownSteps : 2,
+    // 每会话条目注入的上限（条数 / 字符）：预算只能是上限，不是目标。
+    maxItemsPerSession: typeof c.maxItemsPerSession === 'number' && c.maxItemsPerSession >= 0 ? c.maxItemsPerSession : 12,
+    maxItemCharsPerSession: typeof c.maxItemCharsPerSession === 'number' && c.maxItemCharsPerSession >= 0 ? c.maxItemCharsPerSession : 4000,
+    // 提示通道的**绝对**下限（IDF 加权覆盖率）：相对阈值分不出"有信号"和"矮子里拔将军"。
+    // null = 关闭（回到只有相对阈值的老行为）。
+    hintMinCoverage: typeof c.hintMinCoverage === 'number' && c.hintMinCoverage >= 0 ? c.hintMinCoverage : 0.3,
+    // 提示通道还要求至少这么多个共同词：单个通用词（"插件"）也能拿到 coverage=1.00。
+    hintMinMatched: typeof c.hintMinMatched === 'number' && c.hintMinMatched >= 0 ? c.hintMinMatched : 2,
+    // 通道级沉默：查询里能在语料中找到对应的词占比低于这个值时，整条提示通道本轮不出声。
+    // 长句子里只有一两个词碰巧命中，coverage 会虚高到 1.00——这条门就是为它设的。
+    hintMinSupport: typeof c.hintMinSupport === 'number' && c.hintMinSupport >= 0 ? c.hintMinSupport : 0.15,
   }
 }
 
@@ -74,6 +97,9 @@ export function lastUserText(messages) {
     // 真人消息优先：本插件注入的块也是 role=user，若按"最后一条 user"取，
     // 上一步的注入块会变成这一步的就绪查询（自激：拿自己注入的内容再检索一遍）。
     if (m.source && m.source.kind === 'user') return t.trim()
+    // 本插件注入的块同样是 role=user。无 source 的老宿主下若把它当兜底查询，
+    // 就成了"拿自己上一步注入的内容再检索一遍"的自激——正是 kind==='user' 这道闸要防的。
+    if (m.source && m.source.plugin === 'dsh-project-memory') continue
     if (!fallback) fallback = t.trim() // 无 source 的消息（老宿主 / 测试）兜底
   }
   return fallback
@@ -121,17 +147,26 @@ export function buildEntryContent(task, cfg, { withEdited = true } = {}) {
   if (!task) return ''
   const c = cfg || {}
   const steps = (task.steps || []).map((s) => (typeof s === 'string' ? s : s.content || s.text || '').slice(0, 80))
-  const card = [`任务: ${task.title || '(untitled)'}`, `进度: ${steps.filter((s) => true).length ? `${steps.length} 步` : ''}`, ...steps.slice(0, 12).map((s, i) => `  ${i + 1}. ${s}`)]
+  const progress = steps.length ? `${steps.length} 步` : ''
+  const card = [
+    `任务: ${task.title || '(untitled)'}`,
+    `进度: ${progress}`,
+    ...steps.slice(0, 12).map((s, i) => `  ${i + 1}. ${s}`),
+  ]
   const insights = linesOf(task.insights)
-  const edited = editedFiles(task, c.editedMax || 3)
+  // 0 是合法值（= 不显示）：cfgEngine 已归一成数字，这里不能再用 `||` 把 0 顶回默认。
+  const maxEdited = Number.isFinite(c.editedMax) ? c.editedMax : 3
+  const maxInsights = Number.isFinite(c.entryMaxInsights) ? c.entryMaxInsights : 6
+  const edited = editedFiles(task, maxEdited)
   const parts = [...card]
   if (withEdited && edited.length) parts.push(`  编辑中: ${edited.join(', ')}`)
-  if (insights.length) parts.push(`任务记忆:`, ...insights.slice(0, c.entryMaxInsights || 6))
+  if (insights.length) parts.push(`任务记忆:`, ...insights.slice(0, maxInsights))
   return parts.join('\n')
 }
 
-/** 候选池：project + global + 绑定任务（同一 id 只取一次；归档/草稿不进注入）。 */
-function insightCandidates(store, globalStore, task) {
+/** 候选池：project + global + 绑定任务（同一 id 只取一次；归档/草稿不进注入）。
+ * 候选在进入匹配前统一走旧 trigger → 新 schema 的归一（幂等，纯内存，不落盘）。 */
+function insightCandidates(store, globalStore, task, opts) {
   const out = []
   const seen = new Set()
   const push = (it) => {
@@ -139,7 +174,7 @@ function insightCandidates(store, globalStore, task) {
     const key = it.id || `${it.kind}:${it.title}`
     if (seen.has(key)) return
     seen.add(key)
-    out.push(it)
+    out.push(normalizeTrigger(it, { legacyScope: opts?.legacyScope }))
   }
   for (const it of (store ? store.insightItems() : []) || []) push(it)
   for (const it of (globalStore ? globalStore.items() : []) || []) push(it)
@@ -161,11 +196,85 @@ export function insightItemHash(it) {
 
 /** 把正文塞进剩余预算：放不下就截断；连"有用前缀"都留不下就返回 null（由调用方记 dropped）。 */
 export function fitBody(body, remaining, min = MIN_BODY_CHARS.hint) {
-  if (remaining <= min) return null
+  if (remaining < min) return null
   if (body.length <= remaining) return body
   return `${body.slice(0, remaining - 1)}…`
 }
 
+/**
+ * 通道 1：authored trigger 命中（确定性、全文、优先级 1）。procedure 先于其它 kind（步骤更完整）。
+ * 准入化（S2）：只有 `when`（op / 写目标 / 意图词）能触发，guard 只能收窄；
+ * **没有 `when` 的条目在这里永远不命中**（降级为可发现 + 按需拉取）。
+ */
+function collectTriggered(cands, ctx) {
+  const hits = []
+  for (const it of cands) {
+    const why = matchTrigger(it.trigger, ctx)
+    if (why) hits.push({ it, why })
+  }
+  hits.sort(
+    (a, b) => (a.it.kind === 'procedure' ? 0 : 1) - (b.it.kind === 'procedure' ? 0 : 1)
+      || String(a.it.id).localeCompare(String(b.it.id)),
+  )
+  return hits
+}
+
+/**
+ * 通道 2：统计信号（提示态、优先级 2）。**双门槛**：层内相对阈值 + IDF 加权覆盖率（绝对下限）。
+ * 查询只用「人类消息的意图文字 + 本次写目标」：原始工具参数不是查询文本，它们正是
+ * `dcterms→rm`、`*.pptx→论文笔记` 那类假阳性的来源。被门槛拦下的记进 dropped，不静默。
+ */
+function scoreHints({ cands, query, humanText, hintQuery, cfg, dropped }) {
+  const hints = []
+  if (!cands.length) return hints
+  if (typeof cfg.relevanceMin === 'number') {
+    // 兼容：显式 relevanceMin → 旧的绝对 overlap 判据（老 profile 行为不变）
+    for (const it of cands) {
+      const score = normalizedTokenOverlap(humanText || query || '', insightMatchText(it))
+      if (score >= cfg.relevanceMin) hints.push({ it, score, why: `overlap:${score.toFixed(3)}` })
+    }
+    hints.sort((a, b) => b.score - a.score)
+    return hints
+  }
+  const q = hintQueryText(hintQuery)
+  if (!q) return hints
+  const byId = new Map(cands.map((it) => [it.id, it]))
+  // 覆盖率语料必须与 BM25 排序同源（insightScoringText）：否则"只在 fix/solution 里有匹配"
+  // 的查询词 df=0 → supportRatio=0 → 整条提示通道沉默，而排序明明给了它高分。
+  const corpus = cands.map((it) => insightScoringText(it))
+  // 查询与被测覆盖率的文本用**同一个**过滤后的查询：否则缩写（wsl/npm）会在 BM25 里被剔除、
+  // 却仍在覆盖率里计分，"至少两个共同词"就被它们凑够了。
+  const scored = rankEntriesMergedScored(cands.map(insightToEntry), [q], cands.length)
+  const coverage = new Map(cands.map((it, i) => [it.id, idfCoverage(q, corpus[i], corpus)]))
+  const qStats = coverage.get(cands[0].id) || { supported: 0, terms: 0 }
+  const supportRatio = qStats.terms > 0 ? qStats.supported / qStats.terms : 0
+  // 通道级沉默：查询里绝大多数词在语料里根本没有对应 → "覆盖率 1.00"只是假象。
+  const channelThin = typeof cfg.hintMinSupport === 'number' && supportRatio < cfg.hintMinSupport
+  for (const r of relativeHits(scored, { ratioMin: cfg.signalMinRatio })) {
+    const it = byId.get(r.entry.insightId)
+    if (!it) continue
+    const ev = coverage.get(it.id) || { coverage: 0, matched: 0, supported: 0, terms: 0 }
+    if (channelThin) {
+      dropped.push({ id: it.id, channel: 'hint', reason: `support:${supportRatio.toFixed(2)}` })
+      continue
+    }
+    // 绝对门槛：覆盖率下限 + 共同词数下限（查询本身很短时下限按可用词数收敛）。
+    if (typeof cfg.hintMinCoverage === 'number' && ev.coverage < cfg.hintMinCoverage) {
+      dropped.push({ id: it.id, channel: 'hint', reason: `coverage:${ev.coverage.toFixed(2)}` })
+      continue
+    }
+    // 共同词数下限按**查询本身的词数**收敛（查询很短时不强求两个），而不是按"语料能表示的词数"：
+    // 后者在长而杂的查询上会退化成 1，一个碰巧命中的通用词就能过闸。
+    const needMatched = Math.min(typeof cfg.hintMinMatched === 'number' ? cfg.hintMinMatched : 2, ev.terms)
+    if (ev.matched < needMatched) {
+      dropped.push({ id: it.id, channel: 'hint', reason: `thin:${ev.matched}` })
+      continue
+    }
+    hints.push({ it, score: r.score, why: `relative:${(r.score / (scored[0].score || 1)).toFixed(2)} cov:${ev.coverage.toFixed(2)}/${ev.matched}` })
+  }
+  return hints
+}
+
 /**
  * 构建注入内容（不写盘、无副作用）。
  *
@@ -181,144 +290,160 @@ export function buildInjection(opts) {
   const { query, task, globalStore, cfg } = opts
   const store = opts.store || null
   const tags = opts.projectTagsList || []
-  const ctx = buildReadinessContext(opts.readiness || { humanText: query || '' })
+  const ctx = buildReadinessContext({ ...(opts.readiness || { humanText: query || '' }), tags })
   const labels = []
   const reasons = []
   const dropped = []
   const parts = []
-  const budgetChars = (cfg.maxTokens || 400) * 3
+  // 预算只能是上限，不是目标。两条额度分开：
+  //   stepBudget —— 单轮（常驻块 + 条目）共享的 maxTokens；
+  //   itemBudget —— 条目还受会话字符额度约束；**常驻块不占这条**（它是状态快照，文档明说不受限）。
+  // 旧实现把两者取小成同一个 budgetChars，会话额度用尽后连任务卡都被截成 `…(截断)`。
+  const quotaChars = typeof opts.maxChars === 'number' ? opts.maxChars : Infinity
+  const maxItems = typeof opts.maxItems === 'number' ? opts.maxItems : Infinity
+  const skipItems = opts.skipItems === true
+  const stepBudget = Math.max(0, (cfg.maxTokens || 400) * 3)
+  const itemBudget = Math.max(0, Math.min(stepBudget, quotaChars))
 
   const skipItem = typeof opts.skipItem === 'function' ? opts.skipItem : null
-  const cands = insightCandidates(store, globalStore, task).filter((it) => !(skipItem && skipItem(it)))
+  const cands = insightCandidates(store, globalStore, task, cfg).filter((it) => !(skipItem && skipItem(it)))
 
-  // 通道 1：authored trigger —— 确定性、全文、优先级 1。procedure 先于其它 kind（步骤更完整）。
-  const triggered = []
-  for (const it of cands) {
-    const why = matchTrigger(it.trigger, ctx)
-    if (!why) continue
-    const scope = it.trigger?.scope
-    if (Array.isArray(scope) && scope.length && tags.length && !scope.some((s) => tags.includes(s))) continue
-    triggered.push({ it, why })
+  // 两条通道：authored trigger（确定性、全文、优先级 1）→ 统计信号提示（优先级 2）。
+  const triggered = collectTriggered(cands, ctx)
+  if (skipItems) {
+    // 会话级限流命中：条目通道本轮整体沉默，但把"本该注入什么"记进 dropped——不做静默降级。
+    for (const { it } of triggered) dropped.push({ id: it.id, channel: 'trigger', reason: opts.silenceReason || 'cooldown' })
   }
-  triggered.sort(
-    (a, b) => (a.it.kind === 'procedure' ? 0 : 1) - (b.it.kind === 'procedure' ? 0 : 1)
-      || String(a.it.id).localeCompare(String(b.it.id)),
-  )
-
-  // 通道 2：统计信号 —— 提示态、优先级 2，判据是层内相对阈值（尺度无关）。
-  // procedure 只走 trigger 通道：否则会被统计通道绕过 trigger.scope 的画像过滤。
+  // procedure 不进提示通道：它要过 trigger.scope（见 scoreHints 注释）。
   const consumed = new Set(triggered.map((t) => t.it.id))
-  const hintCands = cands.filter((it) => !consumed.has(it.id) && it.kind !== 'procedure')
-  const hints = []
-  if (hintCands.length) {
-    if (typeof cfg.relevanceMin === 'number') {
-      // 兼容：显式 relevanceMin → 旧的绝对 overlap 判据（老 profile 行为不变）
-      for (const it of hintCands) {
-        const score = normalizedTokenOverlap(ctx.humanText || query || '', insightMatchText(it))
-        if (score >= cfg.relevanceMin) hints.push({ it, score, why: `overlap:${score.toFixed(3)}` })
-      }
-      hints.sort((a, b) => b.score - a.score)
-    } else {
-      const byId = new Map(hintCands.map((it) => [it.id, it]))
-      // 提示查询先剔除 1–2 字符的拉丁缩写（PR/CI/OS）：它们一个巧合命中就能当上该层最高分。
-      const scored = rankEntriesMergedScored(
-        hintCands.map(insightToEntry),
-        [hintQueryText(ctx.humanText), hintQueryText(ctx.actionText)].filter(Boolean),
-        hintCands.length,
-      )
-      for (const r of relativeHits(scored, { ratioMin: cfg.signalMinRatio })) {
-        const it = byId.get(r.entry.insightId)
-        if (it) hints.push({ it, score: r.score, why: `relative:${(r.score / (scored[0].score || 1)).toFixed(2)}` })
-      }
-    }
-  }
+  const hintCands = skipItems ? [] : cands.filter((it) => !consumed.has(it.id) && it.kind !== 'procedure')
+  const hints = scoreHints({
+    cands: hintCands,
+    query,
+    humanText: ctx.humanText,
+    hintQuery: [ctx.intent || ctx.humanText || '', ...(ctx.targets || [])].filter(Boolean).join(' '),
+    cfg,
+    dropped,
+  })
 
   // 常驻块文本。去重指纹只看稳定内容（任务标题/步骤/insights + 相关 insights）：
   // “编辑中”随每次写文件变化，若参与指纹会导致每写一个文件就重发整块（噪音 + token 浪费）。
-  const echo = shouldEchoTaskCard(task, cfg)
+  const echo = cfg.entryOn !== false && shouldEchoTaskCard(task, cfg)
   const entry = echo ? buildEntryContent(task, cfg) : ''
   const entryStable = echo ? buildEntryContent(task, cfg, { withEdited: false }) : ''
   let used = entry.length
+  let itemUsed = 0
+  let itemCount = 0
 
-  for (const { it, why } of triggered) {
-    const body = fitBody(insightBody(it), budgetChars - used, MIN_BODY_CHARS.trigger)
-    if (body === null) {
-      dropped.push({ id: it.id, channel: 'trigger', reason: 'budget' })
-      continue
+  /** 把一组候选按优先级放进剩余预算：放不下的进 dropped（quota / budget），不静默。 */
+  const place = (channel, list, minChars, labelOf) => {
+    for (const { it, why } of list) {
+      if (itemCount >= maxItems) {
+        dropped.push({ id: it.id, channel, reason: 'quota' })
+        continue
+      }
+      // 条目同时受"单轮剩余"与"会话字符剩余"约束；常驻块只占前者。
+      const remaining = Math.min(stepBudget - used, itemBudget - itemUsed)
+      const body = fitBody(insightBody(it), remaining, minChars)
+      if (body === null) {
+        dropped.push({ id: it.id, channel, reason: 'budget' })
+        continue
+      }
+      used += body.length + 1
+      itemUsed += body.length + 1
+      itemCount++
+      parts.push(body)
+      labels.push(labelOf(it))
+      reasons.push({ id: it.id, channel, why, hash: insightItemHash(it), chars: body.length })
     }
-    used += body.length + 1
-    parts.push(body)
-    labels.push(it.kind === 'procedure' ? 'procedure' : it.kind)
-    reasons.push({ id: it.id, channel: 'trigger', why, hash: insightItemHash(it) })
   }
-  for (const { it, why } of hints) {
-    const body = fitBody(insightBody(it), budgetChars - used, MIN_BODY_CHARS.hint)
-    if (body === null) {
-      dropped.push({ id: it.id, channel: 'hint', reason: 'budget' })
-      continue
-    }
-    used += body.length + 1
-    parts.push(body)
-    labels.push('hint')
-    reasons.push({ id: it.id, channel: 'hint', why, hash: insightItemHash(it) })
+  // 限流命中时条目通道整体沉默：triggered 已在上方记进 dropped，这里不再重复排程。
+  if (!skipItems) {
+    place('trigger', triggered, MIN_BODY_CHARS.trigger, (it) => it.kind)
+    place('hint', hints, MIN_BODY_CHARS.hint, () => 'hint')
   }
 
   const total = [entry, ...parts].filter(Boolean)
-  if (!total.length) return { text: '', labels, reasons, dropped }
-  const clamp = (t) => (t.length > budgetChars ? `${t.slice(0, budgetChars)}\n…(截断)` : t)
+  if (!total.length) return { text: '', entry, labels, reasons, dropped }
+  // 整块只受单轮预算（maxTokens）约束；会话条目额度已在 place() 里单独扣过。
+  const clamp = (t) => (t.length > stepBudget ? `${t.slice(0, stepBudget)}\n…(截断)` : t)
   const dedupeText = clamp([entryStable, ...parts].filter(Boolean).join('\n'))
-  return { text: clamp(total.join('\n')), labels, reasons, dropped, dedupeText }
+  return { text: clamp(total.join('\n')), entry, entryStable, labels, reasons, dropped, dedupeText, itemChars: itemUsed }
 }
 
-/** 注册 agent/pre-step 监听，向每步请求的 enter 决策追加记忆消息（默认开）。
- * 宿主瀑布事件签名为 (payload, next)：payload.agent.session 提供会话（header.cwd=项目根）。
- * 任何异常/无会话 cwd → 原样返回默认决策，零副作用，绝不让宿主请求受影响。
+// 每会话状态的会话数上限：六张表共用（旧实现把同一个 200 在五处各写一遍）。
+const SESSION_STATE_MAX = 200
+// 单会话已注入条目表的条数上限。
+const INJECTED_ITEMS_MAX = 600
+// 单会话保留的 tool/call 观察窗口（够覆盖"最近几步在做什么"）。
+const OBSERVED_CALLS_MAX = 8
+
+/**
+ * 注入引擎的「每会话一份」状态。
+ *
+ * 之前六张表散在 installAutoInject 里、各自 hand-roll 淘汰循环，同一个
+ * `while (map.size > CAP) map.delete(map.keys().next().value)` 抄了五遍：容量上限写在五处，
+ * 抄漏一处就是无界增长，dispose 时也漏清两张表。容量只在这里定义一次。
  */
-export function installAutoInject(ctx, config) {
-  const auto = (config && config.autoContext) || {}
-  if (auto.enabled === false) return
-  const cfg = cfgEngine(config)
-  // 每个会话一份“上次注入指纹”。用单个变量会让并发会话互相抑制注入。
-  const lastFpBySession = new Map()
-  const LAST_FP_MAX = 200
-  // 每个会话一份"上次预算丢弃指纹"：预算把条目挤出去时必须留痕一次，而不是静默（degraded 可见性）。
-  const lastDroppedBySession = new Map()
-  // 条目级去重记忆：sessionId → Map(insightId → { hash, step })。注入的消息留在会话历史里
-  // （宿主只追加、不压缩），所以"整块指纹变了"不等于"内容都是新的"——同一份 procedure 会因为
-  // 滑动工具窗口、任务卡更新、预算截断边界变化被整块重发（实测 66 步注入 20 次，其中同一份
-  // 1732 字 procedure 重发 3 次、另一份 1008 字的 6 次）。这里按条目记账，正文没变就不再排程。
-  const injectedBySession = new Map()
-  const INJECTED_ITEMS_MAX = 600
-  // 会话步数：为 reinjectItemsAfter 提供时间轴（>0 时才用得上）。
-  const stepBySession = new Map()
-  // 反应窗口：本会话最近观察到的 tool/call（参数里有 git commit / npm publish / 改动的路径）。
-  // 宿主没有"工具执行前拦截"钩子，所以这是 pre-step 之外唯一能拿到的动作事实。
-  const observedBySession = new Map()
-  const OBSERVED_MAX = 8
-  const OBSERVED_SESSIONS = 200
+class InjectionSessions {
+  constructor() {
+    const cache = (create) => new SessionCache({ maxSessions: SESSION_STATE_MAX, create })
+    // 上次注入指纹：用单个变量会让并发会话互相抑制注入。
+    this.lastText = cache()
+    // 上次预算丢弃签名：预算把条目挤出去时必须留痕一次，而不是静默（degraded 可见性）。
+    this.lastDropped = cache()
+    // 条目级去重记忆：insightId → { hash, step }。注入的消息留在 append-only 的会话历史里，
+    // 所以"整块指纹变了"不等于"内容都是新的"：滑动工具窗口 / 任务卡更新 / 预算截断边界都会
+    // 让同一份 procedure 被整块重发（实测 66 步注入 20 次，同一份 1732 字重发 3 次）。
+    this.items = cache(() => new BoundedMap(INJECTED_ITEMS_MAX))
+    // 会话步数：为 reinjectItemsAfter 提供时间轴。
+    this.step = cache(() => 0)
+    // 会话级条目额度（S3）：条数 / 字符 / 上次"条目注入"的步号。常驻任务卡不占额度——
+    // 它是状态快照，内容变了就该更新；被限流的是记忆条目的推送。
+    this.quota = cache(() => ({ items: 0, chars: 0, lastStep: -Infinity }))
+    // 反应窗口：本会话最近观察到的 tool/call（参数里有 git commit / npm publish / 改动的路径）。
+    // 宿主没有"工具执行前拦截"钩子，所以这是 pre-step 之外唯一能拿到的动作事实。
+    this.observed = cache(() => [])
+    this._all = Object.values(this)
+  }
+
+  clear() {
+    for (const cache of this._all) cache.clear()
+  }
+}
+
+/** 记录会话里的 tool/call：ops.js 从这些参数解析出 op / 写目标 / 主机。 */
+function installCallObserver(ctx, sessions) {
   ctx.on('session/event', (session, event) => {
     try {
       if (!event || event.type !== 'tool/call') return
-      const sid = session && session.id
-      if (!sid) return
+      const sessionId = session && session.id
+      if (!sessionId) return
       const data = event.data || {}
-      const rec = observedBySession.get(sid) || []
-      rec.push({ name: String(data.name || ''), arguments: String(data.arguments || '') })
-      while (rec.length > OBSERVED_MAX) rec.shift()
-      observedBySession.set(sid, rec)
-      while (observedBySession.size > OBSERVED_SESSIONS) {
-        observedBySession.delete(observedBySession.keys().next().value)
-      }
+      const calls = sessions.observed.ensure(sessionId)
+      calls.push({ name: String(data.name || ''), arguments: String(data.arguments || '') })
+      if (calls.length > OBSERVED_CALLS_MAX) calls.shift()
     } catch {
       // 观察失败绝不影响宿主请求
     }
   })
+}
+
+/** 注册 agent/pre-step 监听，向每步请求的 enter 决策追加记忆消息（默认开）。
+ * 宿主瀑布事件签名为 (payload, next)：payload.agent.session 提供会话（header.cwd=项目根）。
+ * 任何异常/无会话 cwd → 原样返回默认决策，零副作用，绝不让宿主请求受影响。
+ */
+export function installAutoInject(ctx, config) {
+  const auto = (config && config.autoContext) || {}
+  if (auto.enabled === false) return
+  const cfg = cfgEngine(config)
+  // 审计配置同 cfg：安装时解析一次（与 autoContext 其余开关一致）。
+  const audit = cfgAudit(config)
+  const sessions = new InjectionSessions()
+
+  installCallObserver(ctx, sessions)
   if (typeof ctx.effect === 'function') {
-    ctx.effect(() => () => {
-      observedBySession.clear()
-      injectedBySession.clear()
-      stepBySession.clear()
-    })
+    ctx.effect(() => () => sessions.clear())
   }
   ctx.on('agent/pre-step', async (payload, next) => {
     // 宿主契约是 waterfall(payload, next)，next 一定存在；但一旦宿主版本漂移、或事件被当
@@ -330,90 +455,151 @@ export function installAutoInject(ctx, config) {
     if (!decision) return fallback()
     if (decision.kind !== 'enter') return decision
     try {
-      const agent = payload && payload.agent
-      const session = agent && agent.session
-      const root = session && session.header && session.header.cwd
-      const sessionId = session && session.id
-      if (!root || !sessionId) return decision
-      const query = lastUserText(decision.messages)
-      const store = new ProjectMemoryStore(memoryRootFor(root, config.memoryDir)).load()
-      const globalStore = new GlobalStore(cfgInsight(config).globalFile || defaultGlobalFile()).load()
-      const boundTaskId = store.getBoundTaskId(sessionId) ? store.getBoundTaskId(sessionId) : null
-      const task = boundTaskId ? store.getTask(boundTaskId) : null
-      // 两个窗口合并进同一个就绪上下文：人类消息（先发）+ 已观察动作（反应）。
-      const observed = observedBySession.get(sessionId) || []
-      const readiness = buildReadinessContext({
-        humanText: query || '',
-        actionText: observed.map((c) => `${c.name} ${c.arguments}`).join('\n'),
-      })
-      // 条目级去重：本会话已注入过、且正文未变的条目不再参与排程（cfg.reinjectItemsAfter=0 时永久，
-      // >0 时走冷却步数，用于历史可能被外部裁剪的场景）。正文变了（编辑过 insight）立刻允许重发。
-      const stepNo = (stepBySession.get(sessionId) || 0) + 1
-      stepBySession.set(sessionId, stepNo)
-      while (stepBySession.size > LAST_FP_MAX) stepBySession.delete(stepBySession.keys().next().value)
-      const seen = injectedBySession.get(sessionId) || new Map()
-      injectedBySession.set(sessionId, seen)
-      while (injectedBySession.size > LAST_FP_MAX) injectedBySession.delete(injectedBySession.keys().next().value)
-      const cooldown = cfg.reinjectItemsAfter || 0
-      const skipItem = cooldown === 0
-        ? (it) => {
-            const rec = seen.get(it.id)
-            return Boolean(rec) && rec.hash === insightItemHash(it)
-          }
-        : (it) => {
-            const rec = seen.get(it.id)
-            return Boolean(rec) && rec.hash === insightItemHash(it) && stepNo - rec.step < cooldown
-          }
-      const built = buildInjection({ query: query || '', readiness, task, store, globalStore, projectTagsList: projectTags(root), cfg, skipItem })
-      const fp = fingerprint(built.dedupeText ?? built.text)
-      const shouldInject = Boolean(built.text) && fp !== lastFpBySession.get(sessionId)
-      let injectMessage = null
-      if (shouldInject) {
-        // 以宿主 createUserMessage 构造的完整 user 消息追加（带 id/source，plan-mode narration 同款）。
-        // 裸 {role,content} 消息缺 source 会让宿主逐条读 message.source.kind 时崩溃。
-        lastFpBySession.set(sessionId, fp)
-        if (lastFpBySession.size > LAST_FP_MAX) lastFpBySession.delete(lastFpBySession.keys().next().value)
-        // 只记真的进了上下文的那几条：dropped 的没被看到，不能记账（否则以后永远不再注入）。
-        for (const r of built.reasons) {
-          if (r && r.id && r.hash) seen.set(r.id, { hash: r.hash, step: stepNo })
-        }
-        while (seen.size > INJECTED_ITEMS_MAX) seen.delete(seen.keys().next().value)
-        injectMessage = createUserMessage({
-          content: [{ type: 'text', text: `\n\n${INJECT_MARK} auto-context\n${built.text}` }],
-          // 这一块是「同一生产者后续快照会取代的当前状态」，不是一次性通知。
-          // 宿主 ContextFormed 是判别联合：snapshot 必须带 sections（notice 才需要 summary）。
-          // 通道不变（仍走 agent/pre-step 追加 user 消息），只修语义。
-          source: {
-            kind: 'plugin',
-            plugin: 'dsh-project-memory',
-            form: 'snapshot',
-            sections: [{ name: 'project-memory', text: built.text }],
-          },
-        })
-      }
-      // 未注入 ≠ 无事发生：因预算被挤掉的条目按 cfg.budgetLog 留痕（默认 off，见 cfgEngine）。
-      // 留痕仍然记账（去重 + 上限），只是默认不外泄到用户的终端。
-      if (built.dropped && built.dropped.length && cfg.budgetLog !== 'off') {
-        const sig = built.dropped.map((d) => `${d.id}:${d.reason}`).join(',')
-        if (lastDroppedBySession.get(sessionId) !== sig) {
-          const seenBefore = lastDroppedBySession.has(sessionId)
-          lastDroppedBySession.set(sessionId, sig)
-          while (lastDroppedBySession.size > LAST_FP_MAX) {
-            lastDroppedBySession.delete(lastDroppedBySession.keys().next().value)
-          }
-          // once：只有本会话第一次丢弃出声，之后继续记账但保持安静。
-          if (cfg.budgetLog === 'all' || !seenBefore) {
-            console.error(
-              `[dsh-project-memory] auto-inject degraded: ${built.dropped.length} insight(s) kept out by budget — `
-              + built.dropped.map((d) => `${d.id}(${d.reason})`).join(', '),
-            )
-          }
-        }
-      }
-      if (injectMessage) return { ...decision, messages: [...decision.messages, injectMessage] }
+      return (await injectForStep({ payload, decision, config, cfg, audit, sessions })) || decision
     } catch (err) {
       console.error(`[dsh-project-memory] auto-inject skipped: ${err?.message || err}`)
+      return decision
     }
-    return decision
+  })
+}
+
+/**
+ * 一个 pre-step 的注入决策：解析会话 → 排程 → 必要时构造消息。
+ * 返回 null 表示本步无事可做（交回原决策）。
+ */
+async function injectForStep({ payload, decision, config, cfg, audit, sessions }) {
+  const session = payload && payload.agent && payload.agent.session
+  const root = session && session.header && session.header.cwd
+  const sessionId = session && session.id
+  if (!root || !sessionId) return null
+
+  const query = lastUserText(decision.messages)
+  const memoryRoot = memoryRootFor(root, config.memoryDir)
+  const store = new ProjectMemoryStore(memoryRoot).load()
+  const globalStore = new GlobalStore(cfg.globalFile || defaultGlobalFile()).load()
+  const boundTaskId = store.getBoundTaskId(sessionId)
+  const task = boundTaskId ? store.getTask(boundTaskId) : null
+
+  // 两个窗口合并进同一个就绪上下文：人类消息（先发）+ 已观察动作（反应）。
+  // 动作平面（S1）：把"最近做过什么"解析成 op / 写目标 / 主机——不再把原始参数当文本搜。
+  const observed = sessions.observed.ensure(sessionId)
+  const activity = activityFromCalls(observed)
+  const readiness = buildReadinessContext({
+    humanText: query || '',
+    actionText: observed.map((c) => `${c.name} ${c.arguments}`).join('\n'),
+    ops: activity.ops,
+    targets: activity.targets,
+    hosts: activity.hosts,
+  })
+
+  const stepNo = sessions.step.ensure(sessionId) + 1
+  sessions.step.set(sessionId, stepNo)
+  const quota = sessions.quota.ensure(sessionId)
+  const silence = sessionSilence({ cfg, quota, stepNo })
+  // 条目级去重：本会话已注入过、且正文未变的条目不再参与排程（正文被编辑过 → 立刻允许重发）。
+  const skipItem = makeSkipItem(sessions.items.ensure(sessionId), stepNo, cfg.reinjectItemsAfter || 0)
+
+  const built = buildInjection({
+    query: query || '',
+    readiness,
+    task,
+    store,
+    globalStore,
+    projectTagsList: projectTags(root),
+    cfg,
+    skipItem,
+    skipItems: silence.reason !== null,
+    silenceReason: silence.reason || 'cooldown',
+    maxItems: silence.itemsLeft,
+    maxChars: silence.charsLeft,
+  })
+
+  // 未注入 ≠ 无事发生：因预算被挤掉的条目按 cfg.budgetLog 留痕（默认 off，见 cfgEngine）。
+  // 留痕仍然记账（去重 + 上限），只是默认不外泄到用户的终端。
+  recordDropped({ sessions, sessionId, dropped: built.dropped, budgetLog: cfg.budgetLog })
+
+  const fp = fingerprint(built.dedupeText ?? built.text)
+  if (!built.text || fp === sessions.lastText.peek(sessionId)) return null
+  sessions.lastText.set(sessionId, fp)
+
+  // 只记真的进了上下文的那几条：dropped 的没被看到，不能记账（否则以后永远不再注入）。
+  const seen = sessions.items.ensure(sessionId)
+  for (const r of built.reasons) {
+    if (r && r.id && r.hash) seen.set(r.id, { hash: r.hash, step: stepNo })
+  }
+  // 会话额度只被"条目"消耗；任务卡不算（否则任务一多就把记忆挤没了）。
+  if (built.reasons.length) {
+    quota.items += built.reasons.length
+    quota.chars += typeof built.itemChars === 'number' ? built.itemChars : 0
+    quota.lastStep = stepNo
+  }
+
+  // S0 观测：只记真的进了上下文的那一次（dropped 单独出现不写，否则每步刷屏）。
+  appendInjectionAudit(memoryRoot, auditRecordFrom({
+    sessionId,
+    root,
+    step: stepNo,
+    text: built.text,
+    labels: built.labels,
+    reasons: built.reasons,
+    dropped: built.dropped,
+    budget: { items: quota.items, chars: quota.chars, lastStep: Number.isFinite(quota.lastStep) ? quota.lastStep : null },
+    silence: silence.reason,
+  }), audit)
+
+  return { ...decision, messages: [...decision.messages, injectionMessage(built.text)] }
+}
+
+/**
+ * 会话级限流（S3）：冷却步数 / 条目条数 / 条目字符。三个任一触顶 → 条目通道整体沉默，
+ * 但本轮"本该注入什么"仍会进 dropped（不做静默降级）。
+ */
+function sessionSilence({ cfg, quota, stepNo }) {
+  const cooling = Number.isFinite(quota.lastStep) && stepNo - quota.lastStep < cfg.gateCooldownSteps
+  const itemsLeft = Math.max(0, cfg.maxItemsPerSession - quota.items)
+  const charsLeft = Math.max(0, cfg.maxItemCharsPerSession - quota.chars)
+  const reason = cooling ? 'cooldown'
+    : itemsLeft === 0 ? 'session-items'
+      : charsLeft === 0 ? 'session-chars' : null
+  return { reason, itemsLeft, charsLeft }
+}
+
+/** 条目级去重判据：会话里注入过且正文未变 → 跳过。cooldown=0 永久有效，>0 走步数冷却。 */
+function makeSkipItem(seen, stepNo, cooldown) {
+  return (it) => {
+    const rec = seen.get(it.id)
+    if (!rec || rec.hash !== insightItemHash(it)) return false
+    return cooldown === 0 || stepNo - rec.step < cooldown
+  }
+}
+
+/** 预算丢弃的留痕（cfg.budgetLog）：once=每会话首次，all=丢弃组合每变一次。 */
+function recordDropped({ sessions, sessionId, dropped, budgetLog }) {
+  if (!dropped || !dropped.length || budgetLog === 'off') return
+  const signature = dropped.map((d) => `${d.id}:${d.reason}`).join(',')
+  const previous = sessions.lastDropped.peek(sessionId)
+  if (previous === signature) return
+  sessions.lastDropped.set(sessionId, signature)
+  if (budgetLog === 'all' || previous === undefined) {
+    console.error(
+      `[dsh-project-memory] auto-inject degraded: ${dropped.length} insight(s) kept out by budget — `
+      + dropped.map((d) => `${d.id}(${d.reason})`).join(', '),
+    )
+  }
+}
+
+/** 追加的注入消息：必须是带 source 的完整消息——裸 {role,content} 会让宿主读 message.source 时崩。 */
+function injectionMessage(text) {
+  return createUserMessage({
+    content: [{ type: 'text', text: `\n\n${INJECT_MARK} auto-context\n${text}` }],
+    // 这一块是「同一生产者后续快照会取代的当前状态」，不是一次性通知。
+    // 宿主 ContextFormed 是判别联合：snapshot 必须带 sections（notice 才需要 summary）。
+    // 通道不变（仍走 agent/pre-step 追加 user 消息），只修语义。
+    source: {
+      kind: 'plugin',
+      plugin: 'dsh-project-memory',
+      form: 'snapshot',
+      sections: [{ name: 'project-memory', text }],
+    },
   })
 }