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

package/src/symbols.js

@@ -144,18 +144,57 @@ function extractTypeSignature(line) {
   return sig
 }
 
-function extractInterfaceOrType(line) {
-  // interface User { name: string; age: number }
-  const ifaceMatch = line.match(/^interface\s+(\w+)\s*(?:extends\s+[^{]+)?\s*\{([^}]*)\}/)
-  if (ifaceMatch) {
-    return `{ ${ifaceMatch[2].trim()} }`
+function braceDelta(s) {
+  let d = 0
+  for (const ch of s) {
+    if (ch === '{') d++
+    else if (ch === '}') d--
   }
-  // type UserMap = Map<string, User>
-  const typeMatch = line.match(/^type\s+(\w+)\s*=\s*([^;{]+)/)
-  if (typeMatch) {
-    return `= ${typeMatch[2].trim()}`
+  return d
+}
+
+/**
+ * 读取一条 interface / type 声明，支持 `export`（含 `declare`）与多行形态。
+ * 旧实现要求 `^interface`（不吃 export）且 `}` 必须在本行，于是
+ * `export interface X {…}`、任何多行 interface、`export type X = …` 在 L1 正则扫描器里
+ * 全都产出 0 个符号（TS 增强器可用时才被补回来；没有 typescript 的项目就彻底看不到）。
+ * @returns {{kind: 'interface'|'type', name: string, text: string, endIdx: number} | null}
+ */
+function readTypeDeclaration(rawLines, startIdx) {
+  const first = rawLines[startIdx].trim()
+  const m = first.match(/^(?:export\s+)?(?:declare\s+)?(interface|type)\s+([A-Za-z_$][\w$]*)/)
+  if (!m) return null
+  const kind = m[1]
+  const parts = [first]
+  let depth = braceDelta(first)
+  let endIdx = startIdx
+  const complete = () => (kind === 'interface'
+    ? depth <= 0 && parts[parts.length - 1].includes('}')
+    : depth <= 0 && /[;}]/.test(parts[parts.length - 1]))
+  for (let j = startIdx + 1; j < rawLines.length && j - startIdx <= 20 && !complete(); j++) {
+    const t = rawLines[j].trim()
+    if (!t) {
+      if (depth <= 0) break
+      parts.push(t)
+      endIdx = j
+      continue
+    }
+    // 归零后遇到下一条声明开头就收尾（TS 的 type 别名常不写分号）
+    if (depth <= 0 && j > startIdx && /^(?:export\s+)?(?:declare\s+)?(?:interface|type|function|class|const|let|var|import|enum)\b/.test(t)) break
+    parts.push(t)
+    depth += braceDelta(t)
+    endIdx = j
   }
-  return ''
+  return { kind, name: m[2], text: parts.join(' '), endIdx }
+}
+
+function formatTypeDeclaration({ kind, text }) {
+  if (kind === 'interface') {
+    const body = text.match(/\{([\s\S]*)\}/)
+    return body ? `{ ${body[1].replace(/\s+/g, ' ').trim()} }` : ''
+  }
+  const eq = text.match(/=\s*([\s\S]+?);?\s*$/)
+  return eq ? `= ${eq[1].replace(/\s+/g, ' ').trim()}` : ''
 }
 
 function extractOverloads(masked, startIdx) {
@@ -226,6 +265,7 @@ function scanJsLike(masked, relPath, rawLines) {
   const symbols = []
   let prevOpensBlock = false
   for (let i = 0; i < masked.length; i++) {
+    const declStart = i // 多行声明会推进 i，符号行号要记声明的**首行**
     const rawText = rawLines[i].trim()
     const maskedText = masked[i].trim()
     if (!rawText) continue
@@ -233,13 +273,12 @@ function scanJsLike(masked, relPath, rawLines) {
     let matched = null
     let joinedText = null
     
-    // Check for interface / type alias first (on raw line, not masked)
-    const ifaceSig = extractInterfaceOrType(rawText)
-    if (ifaceSig) {
-      const nameMatch = rawText.match(/^(?:export\s+)?(?:interface|type)\s+(\w+)/)
-      if (nameMatch) {
-        matched = { name: nameMatch[1], kind: 'interface', typeSig: ifaceSig }
-      }
+    // interface / type（支持 export 与多行；没有 TS 增强器时这是唯一来源）
+    const typeDecl = readTypeDeclaration(rawLines, i)
+    if (typeDecl) {
+      const sig = formatTypeDeclaration(typeDecl)
+      if (sig) matched = { name: typeDecl.name, kind: typeDecl.kind, typeSig: sig }
+      i = typeDecl.endIdx
     }
     
     if (!matched) {
@@ -294,7 +333,7 @@ function scanJsLike(masked, relPath, rawLines) {
         if (overloads.length > 1) matched.overloads = overloads
       }
       
-      symbols.push(buildSymbol(matched, relPath, rawLines[i], i + 1))
+      symbols.push(buildSymbol(matched, relPath, rawLines[declStart], declStart + 1))
     }
     
     prevOpensBlock = masked[i].trim().endsWith('{')
@@ -433,7 +472,7 @@ function buildSymbol(matched, relPath, rawLine, lineNo) {
 export function scanSymbols(a, b, c) {
   // Backward compatible: old signature (filePath, content) or new (relPath, filePath, content)
   const [relPath, filePath, content] = c === undefined ? [a, a, b] : [a, b, c]
-  const ext = relPath.slice(relPath.lastIndexOf('.'))
+  const ext = relPath.slice(relPath.lastIndexOf('.')).toLowerCase()
   const lines = content.split(/\r?\n/)
   if (JS_LIKE.has(ext)) return scanJsLike(maskTokens(lines, JS_MASKER), relPath, lines)
   if (PYTHON.has(ext)) return scanPython(maskTokens(lines, PY_MASKER), relPath, lines)

package/src/tools/forget.js

@@ -1,5 +1,5 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import { memoryRootFor, resolveIndexRoot } from '../util/fs.js'
+import { assertIndexRoot, memoryRootFor, resolveIndexRoot } from '../util/fs.js'
 import { ProjectMemoryStore } from '../store.js'
 
 export function forgetTool(config) {
@@ -24,6 +24,7 @@ export function forgetTool(config) {
     },
     async execute(args, exec) {
       const root = resolveIndexRoot(exec, args.root)
+      assertIndexRoot(root, args.root || root)
       const memoryDir = memoryRootFor(root, config.memoryDir)
       const store = new ProjectMemoryStore(memoryDir).load()
       return store.commit((s) => {

package/src/tools/index-doc.js

@@ -2,6 +2,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import path from 'node:path'
 import { assertReadableFile, memoryRootFor, sha256OfFile, storeKey } from '../util/fs.js'
 import { buildDocEntries } from '../doc-pipeline.js'
+import { docEntriesNeedBackfill } from '../doc-index.js'
 import { linkEntries } from '../link.js'
 import { ProjectMemoryStore } from '../store.js'
 import { findProjectRoot } from '../lazy.js'
@@ -38,7 +39,9 @@ export function indexDocTool(ctx, config) {
       const rel = storeKey(path.relative(root, filePath).split(path.sep).join('/'))
       const { hash, size } = await sha256OfFile(filePath)
       const existing = store.fileRecord(rel)
-      if (existing && existing.sha256 === hash) {
+      // 与 index_repo/watch/lazy 同一条判据：哈希未变但旧条目缺 terms 时仍要重抽一次（一次性回填）。
+      // 少了这一步，terms 回填就是"路径相关"的——只有走 index_repo 才生效。
+      if (existing && existing.sha256 === hash && !docEntriesNeedBackfill(store.entries[rel])) {
         return `Skipped (unchanged): ${rel}\nAlready indexed with ${(store.entries[rel] || []).length} entry/entries.`
       }
 

package/src/tools/index-repo.js

@@ -1,11 +1,8 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import path from 'node:path'
 import { statSync } from 'node:fs'
-import { assertIndexRoot, isSupportedCode, isSupportedDoc, looksLikeDump, memoryRootFor, readFileForIndex, relativePath, storeKey, walkDir } from '../util/fs.js'
-import { buildDocEntries } from '../doc-pipeline.js'
-import { docEntriesNeedBackfill } from '../doc-index.js'
-import { scanSymbols } from '../symbols.js'
-import { linkEntries } from '../link.js'
+import { assertIndexRoot, memoryRootFor, relativePath, storeKey, walkDir } from '../util/fs.js'
+import { DROP, OVERSIZE, UNCHANGED, commitFileUpdates, fileKind, planFileIndex, toFileUpdate } from '../index-pipeline.js'
 import { ProjectMemoryStore } from '../store.js'
 import { onFileIndexed, isTypeScriptFile } from '../enhancer.js'
 
@@ -16,109 +13,59 @@ export async function indexRepository(ctx, config, root, { reindex = false } = {
   const memoryDir = memoryRootFor(root, config.memoryDir)
   const store = new ProjectMemoryStore(memoryDir).load()
 
-  const files = walkDir(root)
   const seen = new Set()
+  const updates = []
+  const failures = []
   let indexed = 0
   let updated = 0
   let skipped = 0
-  let removed = 0
-  const failures = []
-
-  // First pass: collect all file info and compute hashes/entries (async work outside commit)
-  const fileUpdates = []
 
-  for (const filePath of files) {
+  for (const filePath of walkDir(root)) {
     const rel = storeKey(relativePath(root, filePath))
     seen.add(rel)
-    const ext = path.extname(filePath).toLowerCase()
-    if (!isSupportedDoc(ext) && !isSupportedCode(ext)) continue
+    const kind = fileKind(path.extname(filePath).toLowerCase())
+    if (!kind) continue
 
     try {
       const size = statSync(filePath).size
-        const existing = store.fileRecord(rel)
-      if (isSupportedCode(ext) && config.maxFileSizeMb && size > config.maxFileSizeMb * 1024 * 1024) {
-        fileUpdates.push({ rel, deleted: true })
+      const record = store.fileRecord(rel)
+      const plan = await planFileIndex({ rel, filePath, kind, config, record, existingEntries: store.entries[rel], size, force: reindex })
+      if (plan.key === UNCHANGED) {
         skipped++
         continue
       }
-
-      // 单次读盘：同一 buffer 供哈希与正文使用（不再 sha256OfFile + readFileSync 读两遍）
-      const { hash, buffer } = readFileForIndex(filePath)
-      // 旧 store 的 doc 条目缺 terms → 即使哈希未变也重抽一次（一次性回填）
-      const needsBackfill = isSupportedDoc(ext) && docEntriesNeedBackfill(store.entries[rel])
-      if (!reindex && existing && existing.sha256 === hash && !needsBackfill) {
+      if (plan.key === OVERSIZE) {
+        // 体积超限的代码文件：旧记录一律清掉，避免检索命中一个已经不索引的文件。
+        updates.push({ rel, drop: true })
         skipped++
         continue
       }
-
-      let entries
-      if (isSupportedCode(ext)) {
-        entries = scanSymbols(rel, filePath, buffer.toString('utf8'))
-        fileUpdates.push({ rel, expectedHash: existing?.sha256, hash, size, entries, type: 'code' })
-        updated++
-      } else {
-        const content = buffer.toString('utf8')
-        if (looksLikeDump(content)) {
-          fileUpdates.push({ rel, deleted: true })
-          skipped++
-          continue
-        }
-        entries = await buildDocEntries(rel, filePath, {
-          chunkChars: config.chunkChars,
-          maxChunks: config.maxChunksPerFile,
-          maxFileSizeMb: config.maxFileSizeMb,
-          maxPdfPages: config.maxPdfPages,
-        })
-        if (entries === null) {
-          fileUpdates.push({ rel, deleted: true })
-          skipped++
-          continue
-        }
-        fileUpdates.push({ rel, expectedHash: existing?.sha256, hash, size, entries, type: 'doc' })
-        indexed++
-      }
-    } catch (err) {
+      updates.push(toFileUpdate(rel, plan, record))
+      if (plan.key === DROP) skipped++
+      else if (plan.type === 'code') updated++
+      else indexed++
+    } catch {
       failures.push(rel)
     }
   }
 
-  // Second pass: single commit with all updates
-  const report = store.commit((s) => {
-    for (const update of fileUpdates) {
-      const result = s.applyFileUpdate(update.rel, update)
-      if (result.skipped) {
-        // CAS failed - file was modified concurrently, skip
-        continue
-      }
-    }
-
-    // Remove files not seen
-    for (const rel of Object.keys(s.files)) {
-      if (!seen.has(rel)) {
-        s.removeFile(rel)
-        removed++
-      }
-    }
-
-    linkEntries(s)
-    const stats = s.stats()
-    let report =
-      `Indexed project: ${root}\n` +
-      `docs indexed: ${indexed}, code symbols updated: ${updated}, unchanged skipped: ${skipped}, removed: ${removed}\n` +
-      `memory store: ${stats.files} files, ${stats.entries} entries, ${stats.experience} experience notes`
-    if (failures.length) {
-      report += `\nfailed to index ${failures.length} file(s): ${failures.join(', ')}`
-    }
-    return report
-  })
+  // 单事务提交：写入 + 清理本轮未见到的旧条目 + 重建链接。
+  const { removed } = commitFileUpdates(store, { updates, unseen: seen })
+  const stats = store.stats()
+  let report =
+    `Indexed project: ${root}\n` +
+    `docs indexed: ${indexed}, code symbols updated: ${updated}, unchanged skipped: ${skipped}, removed: ${removed}\n` +
+    `memory store: ${stats.files} files, ${stats.entries} entries, ${stats.experience} experience notes`
+  if (failures.length) {
+    report += `\nfailed to index ${failures.length} file(s): ${failures.join(', ')}`
+  }
 
   // Trigger TS enhancement for code files (TS/JS only)
-  for (const update of fileUpdates) {
-    if (update.type === 'code') {
-      const filePath = path.join(root, update.rel)
-      if (isTypeScriptFile(filePath)) {
-        onFileIndexed(store, update.rel, filePath, config, root)
-      }
+  for (const update of updates) {
+    if (update.type !== 'code') continue
+    const filePath = path.join(root, update.rel)
+    if (isTypeScriptFile(filePath)) {
+      onFileIndexed(store, update.rel, filePath, config, root)
     }
   }
 

package/src/tools/lesson-tools.js

@@ -1,5 +1,5 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import { memoryRootFor, resolveIndexRoot } from '../util/fs.js'
+import { assertIndexRoot, memoryRootFor, resolveIndexRoot } from '../util/fs.js'
 import { ProjectMemoryStore } from '../store.js'
 import { truncate } from '../util/text.js'
 import { cfgInsight, saveInsight, defaultGlobalFile, GlobalStore } from '../insight-store.js'
@@ -35,16 +35,38 @@ export function lessonTool(config) {
         type: 'object',
         additionalProperties: false,
         properties: {
-          keywords: { type: 'array', items: { type: 'string' } },
+          when: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              ops: { type: 'array', items: { type: 'string' }, description: '归一动作 id：file-write / file-delete / shell-run / git-commit / git-push / release / npm-publish / deploy / migrate / render-doc / index-doc / read-image / fetch-web / run-bench / query-memory。' },
+              writes: { type: 'array', items: { type: 'string' }, description: '本次要【写】的项目相对路径（禁扩展名/泛名 glob）。' },
+              intents: { type: 'array', items: { type: 'string' }, description: '人类消息里剥离引用后的意图词（CJK ≥2 字、拉丁 ≥5 字符且不含 _ . /）。' },
+            },
+            description: '唯一触发面：三者取或。',
+          },
+          guard: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              paths: { type: 'array', items: { type: 'string' }, description: '收窄：写目标必须命中其中之一（自己不能触发）。' },
+              not_paths: { type: 'array', items: { type: 'string' } },
+              hosts: { type: 'array', items: { type: 'string' }, description: '例如 wsl（命令里出现 /mnt/* 或 powershell.exe）。' },
+              tags: { type: 'array', items: { type: 'string' }, description: '项目画像 tag 交集（画像未知时不过滤）。' },
+            },
+            description: '收窄条件：全部满足才注入。',
+          },
+          prevents: { type: 'string', description: '准入条件：不知道这条，这一步会做错什么。写不出来 → 不该进自动注入。' },
+          keywords: { type: 'array', items: { type: 'string' }, description: '【旧字段】降级为 intents 与被动召回排序。' },
           symbols: { type: 'array', items: { type: 'string' } },
-          actions: { type: 'array', items: { type: 'string' } },
-          paths: { type: 'array', items: { type: 'string' } },
-          scope: { type: 'array', items: { type: 'string' } },
+          actions: { type: 'array', items: { type: 'string' }, description: '【旧字段】映射为 when.ops；死值丢弃并计入自检。' },
+          paths: { type: 'array', items: { type: 'string' }, description: '【旧字段】具体文件映射为 when.writes；扩展名/泛名 glob 丢弃。' },
+          scope: { type: 'array', items: { type: 'string' }, description: '【旧字段】默认忽略（值不在项目画像 tag 空间里）。' },
         },
         description:
-          'authored trigger（所有 kind 通用）：命中即在**动手前**确定性注入本条。' +
-          'keywords/symbols 匹配人类消息与工具参数；actions 用归一 id（git-commit / npm-publish / go-public / deploy / delete / migrate …）；' +
-          'paths 用 glob（README* / CHANGELOG* / .gitignore）；scope 按项目画像 tags 过滤。留空则只可能作为统计提示注入。',
+          'authored trigger：命中即在**动手前**确定性注入。' +
+          'when = 唯一触发面（ops / writes / intents 取或）；guard 只能收窄；prevents 是准入条件。' +
+          '没有 when 的条目不会自动推送，只出现在记忆目录里供按需拉取。',
       },
       task_id: { type: 'string', description: '目标任务 id（scope 缺省时优先于绑定任务）' },
       files: { type: 'array', items: { type: 'string' }, description: '关联文件（项目相对路径）' },
@@ -55,6 +77,7 @@ export function lessonTool(config) {
     output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
     async execute(args, exec) {
       const root = resolveIndexRoot(exec, args.root)
+      assertIndexRoot(root, args.root || root)
       const memoryDir = memoryRootFor(root, config.memoryDir)
       const store = new ProjectMemoryStore(memoryDir).load()
       const cfg = cfgInsight(config)

package/src/tools/query-memory.js

@@ -11,6 +11,15 @@ function toAbs(root, rel) {
   return path.isAbsolute(rel) ? rel : path.join(root, rel)
 }
 
+/** 步骤在历史数据里可能是字符串或 {content|text, status}：TaskBridge/注入/反思都按 content||text 读。 */
+function stepContent(s) {
+  if (typeof s === 'string') return s
+  return s?.content ?? s?.text ?? ''
+}
+function stepStatus(s) {
+  return typeof s === 'string' ? 'pending' : (s?.status || 'pending')
+}
+
 export function queryMemoryTool(ctx, config) {
   return defineTool({
     name: 'query_memory',
@@ -46,6 +55,11 @@ export function queryMemoryTool(ctx, config) {
     },
     async execute(args, exec) {
       const root = resolveIndexRoot(exec, args.root)
+      // 空查询不是"全部"：recallItems 会过滤空串，rankEntriesStreaming 随即返回
+      // entries.slice(0, limit)（任意条目、分数 0），task 分支的 includes('') 更是命中所有任务。
+      if (!String(args.query ?? '').trim()) {
+        return 'query must not be empty. Use memory_stats to see what the store contains.'
+      }
       const store = new ProjectMemoryStore(memoryRootFor(root, config.memoryDir)).load()
       const type = args.type || 'all'
       const limit = Math.max(1, Math.min(Number(args.limit) || 8, 20))
@@ -146,16 +160,16 @@ export function queryMemoryTool(ctx, config) {
       if (type === 'task') {
         const q = (queries[0] || '').toLowerCase()
         const matched = tasks
-          .filter((t) => !t.archived && (t.title.toLowerCase().includes(q) || (t.steps || []).some((s) => s.text?.toLowerCase().includes(q)) || (t.files || []).some((f) => f.toLowerCase().includes(q))))
+          .filter((t) => !t.archived && (t.title.toLowerCase().includes(q) || (t.steps || []).some((s) => stepContent(s).toLowerCase().includes(q)) || (t.files || []).some((f) => f.toLowerCase().includes(q))))
           .slice(0, limit)
         if (!matched.length) {
           return `任务记录: 0 套匹配 "${args.query}"（list_tasks 查看全部，select_task 续做）`
         }
         for (const t of matched) {
-          const done = (t.steps || []).filter((s) => s.status === 'completed').length
+          const done = (t.steps || []).filter((s) => stepStatus(s) === 'completed').length
           const total = (t.steps || []).length
           const stepsText = (t.steps || []).length
-            ? (t.steps || []).map((s) => `- [${s.status === 'completed' ? 'x' : s.status === 'in_progress' ? '*' : ' '}] ${s.text}`).join('\n')
+            ? (t.steps || []).map((s) => `- [${stepStatus(s) === 'completed' ? 'x' : stepStatus(s) === 'in_progress' ? '*' : ' '}] ${stepContent(s)}`).join('\n')
             : '（无步骤）'
           const files = (t.files || []).slice(0, 8).join(', ')
           lines.push(`### ${t.title} (${done}/${total} 完成)\n${stepsText}\n- 文件: ${files || '无'}`)

package/src/tools/remember.js

@@ -1,5 +1,5 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import { memoryRootFor, resolveIndexRoot } from '../util/fs.js'
+import { assertIndexRoot, memoryRootFor, resolveIndexRoot } from '../util/fs.js'
 import { ProjectMemoryStore } from '../store.js'
 
 export function rememberTool(config) {
@@ -35,6 +35,8 @@ export function rememberTool(config) {
     },
     async execute(args, exec) {
       const root = resolveIndexRoot(exec, args.root)
+      // 写盘前校验根：否则一个拼错的 root 会被 mkdir 成字面量目录（连同 .dsh-project-memory）。
+      assertIndexRoot(root, args.root || root)
       const memoryDir = memoryRootFor(root, config.memoryDir)
       const store = new ProjectMemoryStore(memoryDir).load()
       return store.commit((s) => {

package/src/tools/task-tools.js

@@ -1,5 +1,5 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import { memoryRootFor, resolveIndexRoot } from '../util/fs.js'
+import { assertIndexRoot, memoryRootFor, resolveIndexRoot } from '../util/fs.js'
 import { ProjectMemoryStore } from '../store.js'
 import { truncate } from '../util/text.js'
 import { genTaskId, hash8, adoptStepsToSession, shouldAdoptToHost } from '../setup/taskbridge.js'
@@ -40,6 +40,7 @@ export function listTasksTool(config) {
     output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
     async execute(args, exec) {
       const root = resolveIndexRoot(exec, args.root)
+      assertIndexRoot(root, args.root || root)
       const store = new ProjectMemoryStore(memoryRootFor(root, config.memoryDir)).load()
       const tasks = store.getTasks()
       if (!tasks.length) {
@@ -66,6 +67,7 @@ export function selectTaskTool(config, host) {
     output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
     async execute(args, exec) {
       const root = resolveIndexRoot(exec, args.root)
+      assertIndexRoot(root, args.root || root)
       const store = new ProjectMemoryStore(memoryRootFor(root, config.memoryDir)).load()
       const sid = sessionIdOf(exec)
       const now = new Date().toISOString()
@@ -184,6 +186,7 @@ export function archiveTaskTool(config, host) {
     output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
     async execute(args, exec) {
       const root = resolveIndexRoot(exec, args.root)
+      assertIndexRoot(root, args.root || root)
       const store = new ProjectMemoryStore(memoryRootFor(root, config.memoryDir)).load()
       const task = store.getTask(args.taskId)
       if (!task) return truncate(JSON.stringify({ success: false, error: 'Task not found' }), config.maxOutputChars)

package/src/tools/watch-repo.js

@@ -1,7 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import path from 'node:path'
-import { existsSync } from 'node:fs'
-import { isUnwatchableRoot, memoryRootFor, resolveIndexRoot } from '../util/fs.js'
+import { assertIndexRoot, isUnwatchableRoot, memoryRootFor, resolveIndexRoot } from '../util/fs.js'
 import { ProjectMemoryStore } from '../store.js'
 
 export function watchRepoTool(watchManager, config) {
@@ -28,9 +27,14 @@ export function watchRepoTool(watchManager, config) {
     },
     async execute(args, exec) {
       const root = path.resolve(args.root)
-      // 不存在的根不写进 watchlist：watch 每轮会 commit → save → mkdirSync，把它重新造出来
-      if (args.watch !== false && !existsSync(root)) {
-        return `Not watching: ${root} does not exist.`
+      // 不存在的根不写进 watchlist：watch 每轮会 commit → save → mkdirSync，把它重新造出来。
+      // 根是**文件**时同样要拦：否则 save() 的 mkdirSync 会抛裸 ENOTDIR。
+      if (args.watch !== false) {
+        try {
+          assertIndexRoot(root, args.root)
+        } catch (err) {
+          return `Not watching: ${err.message}`
+        }
       }
       // 文件系统根 / 共享临时目录不整体监听（子目录允许）：会把无关程序和测试夹具的临时文件全扫进来
       if (args.watch !== false && isUnwatchableRoot(root)) {

package/src/util/fs.js

@@ -73,8 +73,22 @@ export function readFileForIndex(filePath) {
 }
 
 export async function readTextFile(filePath, maxBytes = 2 * 1024 * 1024) {
+  // 先 stat 再读：大小上限的意义就是"别把整个文件读进内存"。旧写法先 readFile 再比较，
+  // 127 MB 的文件会先把 127 MB 拉进 RSS 再抛错（watch/lazy 每轮重试，反复发生）。
+  if (Number.isFinite(maxBytes)) {
+    let size = 0
+    try {
+      size = statSync(filePath).size
+    } catch {
+      size = 0 // 交给下面的 readFile 报真实错误（不存在 / 无权限）
+    }
+    if (size > maxBytes) {
+      throw new Error(`File too large to index as text (${(size / 1024 / 1024).toFixed(1)} MB)`)
+    }
+  }
   const buf = await readFile(filePath)
   if (buf.length > maxBytes) {
+    // stat 与 read 之间文件被改大：兜底再判一次
     throw new Error(`File too large to index as text (${(buf.length / 1024 / 1024).toFixed(1)} MB)`)
   }
   return buf.toString('utf8')

package/src/util/session-cache.js

@@ -0,0 +1,72 @@
+/**
+ * 会话级状态的容量管理。
+ *
+ * 注入引擎有六张「每会话一份」的表（注入指纹 / 丢弃签名 / 已注入条目 / 步号 / 额度 / 动作观察窗）。
+ * 它们各自都需要淘汰最旧会话，于是同一个 `while (map.size > CAP) delete(oldest)` 被抄了五遍——
+ * 容量上限写在五处，抄漏一处就是无界增长，dispose 时也漏清两张表。这里把容量收成唯一事实：
+ * 新增一种会话状态只需换一个 create 函数，不必再想淘汰。
+ */
+
+const DEFAULT_MAX_SESSIONS = 200
+
+/** 容量受限的 Map：写入超过 max 时按插入顺序淘汰最旧项（重写已有键会刷新它的位置）。 */
+export class BoundedMap extends Map {
+  constructor(max, entries) {
+    super(entries)
+    this.max = max
+  }
+
+  set(key, value) {
+    if (this.has(key)) super.delete(key)
+    super.set(key, value)
+    while (this.size > this.max) super.delete(this.keys().next().value)
+    return this
+  }
+}
+
+/**
+ * 会话 → 值，容量按会话数封顶（淘汰最久未触碰的会话）。
+ * - `ensure(id)`：读不到就用 create 建一份并记下，适合数组 / 计数 / 额度这类累加器；
+ * - `peek(id)` / `set(id, v)`：适合只需读写的值（指纹、签名），不假设默认值。
+ */
+export class SessionCache {
+  constructor({ create = () => undefined, maxSessions = DEFAULT_MAX_SESSIONS } = {}) {
+    this.create = create
+    this.store = new BoundedMap(maxSessions)
+  }
+
+  /** 只读查找；不存在返回 undefined（不创建）。读到即刷新其"最近使用"位置。 */
+  peek(sessionId) {
+    const value = this.store.get(sessionId)
+    if (value !== undefined) this.store.set(sessionId, value)
+    return value
+  }
+
+  /** 读取并（必要时）创建：create 只会在该会话第一次出现时调用。 */
+  ensure(sessionId) {
+    const value = this.store.get(sessionId)
+    if (value !== undefined) {
+      this.store.set(sessionId, value)
+      return value
+    }
+    const created = this.create(sessionId)
+    this.store.set(sessionId, created)
+    return created
+  }
+
+  set(sessionId, value) {
+    this.store.set(sessionId, value)
+  }
+
+  delete(sessionId) {
+    return this.store.delete(sessionId)
+  }
+
+  clear() {
+    this.store.clear()
+  }
+
+  get size() {
+    return this.store.size
+  }
+}