thincoder 0.12.59 → 0.12.61

package/src/memory/docs.mjs

@@ -3,13 +3,15 @@
  */
 
 import { readFile, stat } from "node:fs/promises"
-import { join } from "node:path"
+import { isAbsolute, join } from "node:path"
 import { embed, cosine, toBlob, fromBlob } from "../embedding.mjs"
 import { commitAndPush } from "../git/gitmem.mjs"
-import { DOC_EXTS, SKIP_DIRS, MAX_DOC_FILE_BYTES } from "./schema.mjs"
-import { buildFtsQuery, put, search, putMarkdown, deleteByUid, matchMemoryRows, deleteWhere, clearPersonal, EMBED_TEXT_MAX_LEN } from "./core.mjs"
+import { MAX_DOC_FILE_BYTES } from "./schema.mjs"
+import { buildFtsQuery, put, search, putMarkdown, clearPersonal, EMBED_TEXT_MAX_LEN } from "./core.mjs"
+import { deleteByUid, matchMemoryRows, deleteWhere } from "./delete.mjs"
 import { _upsertDocFile, yieldTick } from "./code-index.mjs"
-import { markIndexedCommit, listProjectFiles } from "./code-sync.mjs"
+import { markIndexedCommit, listProjectFiles, indexExtensions } from "./code-sync.mjs"
+import { logEvent } from "../log.mjs"
 
 const DOC_EMBED_BATCH = 64
 
@@ -18,7 +20,7 @@ const DOC_EMBED_BATCH = 64
  * Incremental by mtime.
  */
 export async function docSync(memory, dir, { onProgress } = {}) {
-  const entries = await listProjectFiles(dir, DOC_EXTS)
+  const { entries, unlisted } = await listProjectFiles(dir, indexExtensions(dir).doc)
   const files = [] // { abs, rel, mtimeMs }
   let overSizeSkipped = 0
   for (const { abs, rel } of entries) {
@@ -71,7 +73,10 @@ export async function docSync(memory, dir, { onProgress } = {}) {
 
   onProgress?.({ phase: "done", total: files.length, updated, removed, skipped, failed, overSizeSkipped })
   markIndexedCommit(memory, dir)
-  return { updated, removed, skipped, failed, errors, total: files.length, overSizeSkipped }
+  if (unlisted.count > 0) {
+    logEvent("index:unlisted", { dir, kind: "doc", count: unlisted.count, exts: unlisted.exts.map((e) => e.ext) })
+  }
+  return { updated, removed, skipped, failed, errors, total: files.length, overSizeSkipped, unlistedExts: unlisted }
 }
 
 /**
@@ -165,7 +170,8 @@ export function docSearchTool(memory) {
     name: "doc_search",
     description:
       "Search the project's documentation (README, design docs, guides, markdown files) for relevant information. Use this to find design decisions, coding conventions, architecture docs, or project rules. Prefer this over code_search when you need to understand the project's intended design rather than existing implementation. " +
-      "Returns matching doc chunks: path, heading, line range, relevance score, content excerpt.",
+      "Returns matching doc chunks: path, heading, line range, relevance score, content excerpt. " +
+      "For what was said in sessions (conversation/chat history — decisions, rulings), use read_history.",
     parameters: {
       type: "object",
       properties: {
@@ -188,19 +194,21 @@ export function docSearchTool(memory) {
 // ---------------------------------------------------------------- agent tools
 
 /** §6 shared tool surface — action enum / parameter shapes / descriptions byte-identical
- *  with thincoder-vscode/src/memory.mjs (MEMORY.md §6 D-M1/F-M6); scope VALUES per end
+ *  with thincoder-vscode/src/memory.mjs (MEMORY.md §6 D-M1/F-M6); layer VALUES per end
  *  (VS Code has no team layer and rejects it with CLI guidance). */
 const MEMORY_ACTIONS = ["search", "put", "list", "delete", "clear"]
-const MEMORY_SCOPES = ["personal", "project", "team"]
+const MEMORY_LAYERS = ["personal", "project", "team"]
 const MEMORY_TOOL_DESCRIPTION =
   "Manage long-term memory in ONE tool — the action parameter picks the operation:\n" +
-  "- search — find knowledge saved in previous sessions (query, optional scope/limit); results include every entry's id\n" +
-  "- put — save a piece of knowledge for future sessions (type: rule = coding standards, knowledge = project facts, decision = architecture decisions, pattern = debugging/workflow patterns; title/content/tags/scope)\n" +
-  "- list — inventory what memory holds: optional scope/type/keyword filters, limit default 50; one row per entry: id [type] title (date); a truncated list notes the full count\n" +
-  "- delete — SINGLE: {id, scope} deletes one entry by the id shown in put/search/list output. BATCH: {scope + type and/or keyword} deletes every matching entry in that scope — a call without confirm:true is refused and returns the count plus a preview (re-send with confirm:true to execute); scope-wide wipes without filters are refused on every layer\n" +
-  "- clear — {scope: \"personal\", confirm: true} wipes ALL personal memory entries. clear is personal-only: a missing scope or a project/team scope is refused (use delete batch filters on shared layers)\n" +
+  "- search — find knowledge saved in previous sessions (query, optional layer/limit); result rows start with a [layer] tag and carry the entry id (id prefix = the layer)\n" +
+  "- put — save a piece of knowledge for future sessions (type: rule = coding standards, knowledge = project facts, decision = architecture decisions, pattern = debugging/workflow patterns; title/content/tags; layer defaults to personal)\n" +
+  "- list — inventory what memory holds (optional layer/type/keyword filters, limit default 50); one row per entry: [layer] id [type] title (date); a truncated list notes the full count\n" +
+  "- delete — SINGLE: {id, layer} removes the entry shown in put/search/list output — layer is optional: when passed it is validated against the id prefix (a mismatch is refused — guards against deleting the wrong entry); when omitted the id prefix routes the delete, so any id search/list returned is directly deletable. BATCH (no id): {layer, type and/or keyword} removes every matching entry in that layer — layer and at least one of type/keyword are required, plus confirm:true (without confirm it returns the count plus a preview); layer-wide wipes without filters are refused on every layer\n" +
+  "- clear — {layer: \"personal\", confirm: true} wipes ALL personal memory entries. clear is personal-only: a missing layer or a project/team layer is refused (use delete batch filters on shared layers)\n" +
+  "Layer is the memory tier: personal (private), project (shared via this repo's .thincoder/memory/), team (CLI only, git-synced). The [layer] tag on search/list result rows, the row's id prefix, and the layer parameter are the same concept — pass a result row's [layer] as layer, or omit it on a single delete to auto-route by the id prefix.\n" +
   "Deleting project/team (CLI) entries removes the local markdown file and its index row — team deletion is local only and a later team sync may resurrect the file while the remote still has it.\n" +
-  "Save bugs, conventions, and preferences here — they persist across sessions."
+  "Save bugs, conventions, and preferences here — they persist across sessions.\n" +
+  "Session message history (what was said in this or past sessions) is NOT in memory — search session messages with read_history."
 
 function validateTypeFilter(type) {
   if (type === undefined || type === null || type === "") return null
@@ -218,18 +226,18 @@ function fmtDate(ts) {
   return ts ? new Date(ts).toISOString().slice(0, 10) : "?"
 }
 
-const listRowLine = (r) => `${r.id} [${r.type}] ${r.title}（${fmtDate(r.ts)}）`
+const listRowLine = (r) => `[${r.layer}] ${r.id} [${r.type}] ${r.title}（${fmtDate(r.ts)}）`
 
 /**
  * Generate the memory agent tool — ONE `memory` tool with five actions (MEMORY.md §6 D-M1).
  * search/list are read-only actions (planMode pass / no permission ask — dispatch classifies
  * them action-level, same as subagent check/status); put keeps its side-effect permission
- * gate; batch delete/clear gate on confirm:true + scope inside the tool (direct-delete
+ * gate; batch delete/clear gate on confirm:true + layer inside the tool (direct-delete
  * ruling — the confirm parameter IS the gate) and stay non-readonly like the retired tools.
  * opts: { cwd, projectDir, author, team: { dir, name } | null }
  */
 export function memoryTools(memory, opts = {}) {
-  const projectDir = opts.projectDir ? join(opts.cwd ?? process.cwd(), opts.projectDir) : null
+  const projectDir = opts.projectDir ? (isAbsolute(opts.projectDir) ? opts.projectDir : join(opts.cwd ?? process.cwd(), opts.projectDir)) : null
   const dirs = { project: projectDir, team: opts.team?.dir ?? null }
   return [
     {
@@ -239,7 +247,7 @@ export function memoryTools(memory, opts = {}) {
         type: "object",
         properties: {
           action: { type: "string", enum: MEMORY_ACTIONS, description: "Operation to run (required)" },
-          scope: { type: "string", enum: MEMORY_SCOPES, description: "Where the memory lives: personal (private), project (shared via this repo's .thincoder/memory/), team (CLI only). put defaults to personal; search/list search every layer when omitted; delete/clear require it" },
+          layer: { type: "string", enum: MEMORY_LAYERS, description: "The memory layer: personal (private), project (shared via this repo's .thincoder/memory/), team (CLI only). Same concept as the [layer] tag and the id prefix on search/list result rows. put/search/list: optional (put defaults to personal; search/list omit = all layers). single delete: optional (omit = route by id prefix). batch delete/clear: required" },
           type: { type: "string", enum: ["rule", "knowledge", "decision", "pattern"], description: "Entry type: put = what to save; list/delete batch = filter by type" },
           title: { type: "string", description: "put: short title" },
           content: { type: "string", description: "put: full content to remember" },
@@ -272,21 +280,21 @@ export function memoryTools(memory, opts = {}) {
 
 /** action search — the retired search tool surface (read-only, same output contract). */
 async function execSearch(memory, args) {
-  const scope = args.scope
-  if (scope !== undefined && scope !== null && !MEMORY_SCOPES.includes(String(scope))) {
-    throw new Error(`memory search: invalid scope "${scope}"`)
+  const layer = args.layer
+  if (layer !== undefined && layer !== null && !MEMORY_LAYERS.includes(String(layer))) {
+    throw new Error(`memory search: invalid layer "${layer}"`)
   }
   const query = String(args.query ?? "").trim()
   if (!query) return "(no matching memories)" // 空 query 短路——两端同语义（评审 code review #4）
   const limit = normalizeLimit(args.limit, 5)
   let results
-  if (!scope) {
+  if (!layer) {
     results = await search(memory, query, { limit })
   } else {
-    // scope filter: oversample then slice the requested layer (results keep global rank order).
+    // layer filter: oversample then slice the requested layer (results keep global rank order).
     // 窗口 = max(limit*4, 20) 是召回上限——大库 + 高 limit 时该层结果可能不足 limit（接受的取舍——评审 code review #3）
     const wide = await search(memory, query, { limit: Math.max(limit * 4, 20) })
-    results = wide.filter((r) => r.layer === String(scope)).slice(0, limit)
+    results = wide.filter((r) => r.layer === String(layer)).slice(0, limit)
   }
   if (results.length === 0) return "(no matching memories)"
   return results.map((r) => `[${r.layer}][${r.type}] ${r.title} (id=${r.id})\n${r.content}`).join("\n\n")
@@ -294,14 +302,14 @@ async function execSearch(memory, args) {
 
 /** action put — the retired put tool surface (side-effect gate, unchanged semantics). */
 async function execPut(memory, args, opts, dirs) {
-  const scope = String(args.scope ?? "personal")
-  if (!MEMORY_SCOPES.includes(scope)) throw new Error(`memory put: invalid scope "${scope}"`)
-  if (scope === "personal") {
+  const layer = String(args.layer ?? "personal")
+  if (!MEMORY_LAYERS.includes(layer)) throw new Error(`memory put: invalid layer "${layer}"`)
+  if (layer === "personal") {
     const id = await put(memory, { type: args.type, title: args.title, content: args.content, tags: args.tags ?? "" })
     return `Saved to personal memory (id=personal:${id}): [${args.type}] ${args.title}`
   }
-  if (scope === "project") {
-    if (!dirs.project) throw new Error("project scope unavailable: no project directory configured")
+  if (layer === "project") {
+    if (!dirs.project) throw new Error("project layer unavailable: no project directory configured")
     const filename = await putMarkdown(memory, {
       layer: "project",
       dir: dirs.project,
@@ -314,7 +322,7 @@ async function execPut(memory, args, opts, dirs) {
     return `Saved to project memory (id=project:${dirs.project}:${filename}): [${args.type}] ${args.title}`
   }
   if (!dirs.team) {
-    throw new Error("team scope not configured: set memory.team in ~/.thincoder/config.json")
+    throw new Error("team layer not configured: set memory.team in ~/.thincoder/config.json")
   }
   const filename = await putMarkdown(memory, {
     layer: "team",
@@ -329,12 +337,12 @@ async function execPut(memory, args, opts, dirs) {
   return `Saved to team memory and pushed (id=team:${dirs.team}:${filename}): [${args.type}] ${args.title}`
 }
 
-/** action list — new inventory action (read-only): scope/type/keyword filters + limit truncation note. */
+/** action list — new inventory action (read-only): layer/type/keyword filters + limit truncation note. */
 async function execList(memory, args, dirs) {
-  const scope = args.scope ?? null
-  if (scope && !MEMORY_SCOPES.includes(String(scope))) throw new Error(`memory list: invalid scope "${scope}"`)
+  const layer = args.layer ?? null
+  if (layer && !MEMORY_LAYERS.includes(String(layer))) throw new Error(`memory list: invalid layer "${layer}"`)
   const rows = await matchMemoryRows(memory, {
-    scope: scope ? String(scope) : null,
+    layer: layer ? String(layer) : null,
     type: validateTypeFilter(args.type),
     keyword: args.keyword ? String(args.keyword).trim() : null,
     projectDir: dirs.project,
@@ -348,22 +356,23 @@ async function execList(memory, args, dirs) {
   return lines.join("\n")
 }
 
-/** action delete — single ({ id, scope } — §0.1-era single-delete semantics) + batch (scope + type/keyword + confirm). */
+/** action delete — single ({ id, layer? } — MEMORY.md §6.2: layer OPTIONAL, validated when
+ *  passed, else the id prefix routes the delete) + batch (layer + type/keyword + confirm). */
 async function execDelete(memory, args, dirs) {
   const hasId = args.id !== undefined && args.id !== null && String(args.id) !== ""
   if (hasId) return execDeleteSingle(memory, args, dirs)
   // batch form
-  const scope = args.scope
-  if (!scope) throw new Error("batch delete requires scope plus type and/or keyword filter")
-  if (!MEMORY_SCOPES.includes(String(scope))) throw new Error(`memory delete: invalid scope "${scope}"`)
+  const layer = args.layer
+  if (!layer) throw new Error("batch delete requires layer plus type and/or keyword filter")
+  if (!MEMORY_LAYERS.includes(String(layer))) throw new Error(`memory delete: invalid layer "${layer}"`)
   const type = validateTypeFilter(args.type)
   const keyword = args.keyword ? String(args.keyword).trim() : null
   if (!type && !keyword) {
-    throw new Error("batch delete requires type and/or keyword filter — a scope-wide wipe without filters is refused (personal full wipe is the clear action)")
+    throw new Error("batch delete requires type and/or keyword filter — a layer-wide wipe without filters is refused (personal full wipe is the clear action)")
   }
-  if (scope === "project" && !dirs.project) throw new Error("project scope unavailable: no project directory configured")
-  if (scope === "team" && !dirs.team) throw new Error("team scope not configured: set memory.team in ~/.thincoder/config.json")
-  const filters = { scope: String(scope), type, keyword }
+  if (layer === "project" && !dirs.project) throw new Error("project layer unavailable: no project directory configured")
+  if (layer === "team" && !dirs.team) throw new Error("team layer not configured: set memory.team in ~/.thincoder/config.json")
+  const filters = { layer: String(layer), type, keyword }
   const rows = await matchMemoryRows(memory, { ...filters, projectDir: dirs.project, teamDir: dirs.team })
   if (rows.length === 0) return "0 条匹配"
   if (args.confirm !== true) {
@@ -374,27 +383,32 @@ async function execDelete(memory, args, dirs) {
     return lines.join("\n")
   }
   const n = await deleteWhere(memory, filters, { dirs })
-  return `Deleted ${n} entries in scope ${scope}`
+  return `Deleted ${n} entries in layer ${layer}`
 }
 
-/** Single-entry delete — §0.1-era delete semantics (id + scope, NF2/NF3, direct-delete ruling). */
+/** Single-entry delete — MEMORY.md §6.2: layer is OPTIONAL. When passed it is validated
+ *  against the id prefix (mismatch refused — guards against deleting the wrong entry); when
+ *  omitted the delete routes by the id prefix alone, so any id search/list returned is
+ *  directly deletable (deleteByUid already resolves the layer from the uid prefix). */
 async function execDeleteSingle(memory, args, dirs) {
-  if (!args.scope) throw new Error("delete requires id + scope")
   const uid = String(args.id)
   const prefix = uid.split(":")[0]
-  const uidScope = prefix === "personal" || prefix === "project" || prefix === "team" ? prefix : /^\d+$/.test(prefix) ? "personal" : null
-  if (!uidScope) throw new Error(`invalid memory id: ${uid}`)
-  if (uidScope !== args.scope) throw new Error(`id prefix ${prefix}: 与 scope ${args.scope} 不匹配`)
+  const uidLayer = prefix === "personal" || prefix === "project" || prefix === "team" ? prefix : /^\d+$/.test(prefix) ? "personal" : null
+  if (!uidLayer) throw new Error(`invalid memory id: ${uid}`)
+  const layer = args.layer
+  if (layer !== undefined && layer !== null && String(layer) !== uidLayer) {
+    throw new Error(`id prefix ${prefix}: 与 layer ${layer} 不匹配`)
+  }
   const entry = await deleteByUid(memory, uid, { dirs })
   return `Deleted ${entry.id}: ${entry.title}\n${(entry.content ?? "").slice(0, 500)}`
 }
 
-/** action clear — personal-only full wipe (scope + confirm:true gates; project/team refused). */
+/** action clear — personal-only full wipe (layer + confirm:true gates; project/team refused). */
 function execClear(memory, args) {
-  const scope = args.scope
-  if (!scope) throw new Error('clear requires scope "personal" — pass scope: "personal" plus confirm: true')
-  if (String(scope) !== "personal") {
-    if (!MEMORY_SCOPES.includes(String(scope))) throw new Error(`memory clear: invalid scope "${scope}"`)
+  const layer = args.layer
+  if (!layer) throw new Error('clear requires layer "personal" — pass layer: "personal" plus confirm: true')
+  if (String(layer) !== "personal") {
+    if (!MEMORY_LAYERS.includes(String(layer))) throw new Error(`memory clear: invalid layer "${layer}"`)
     throw new Error("shared layers don't support clear — use delete with type/keyword batch filters instead")
   }
   if (args.confirm !== true) throw new Error("clear requires confirm:true — this wipes ALL personal memory")

package/src/memory/file-walk.mjs

@@ -0,0 +1,109 @@
+/**
+ * memory/file-walk.mjs — filesystem walk fallback + the shared file-listing predicates.
+ *
+ * Why this module (PORTABILITY FR15 / P8): the index was built from `git ls-files`
+ * only — on a project that is not a git repository the code and doc indexes came
+ * back EMPTY, silently (the reviewer/agent then "searched" an empty index). The
+ * fallback traverses the filesystem instead, and the skip predicate lives here so
+ * the git path, the walk and the single-file reindex cannot drift apart against
+ * each other (they were three copies before).
+ */
+import { readdir } from "node:fs/promises"
+import { join } from "node:path"
+import { SKIP_DIRS } from "./schema.mjs"
+
+/** Upper guard for the walk: stop after this many matched files (runaway trees). */
+export const MAX_WALK_FILES = 20000
+
+/**
+ * Shared skip predicate for project-relative paths: any SKIP_DIRS basename, or any
+ * dot-prefixed segment (`.git`, `.cache`, `.thincoder`…). Accepts both separators.
+ */
+export function isSkippedRelPath(rel) {
+  return String(rel ?? "")
+    .replace(/\\/g, "/")
+    .split("/")
+    .some((seg) => seg !== "" && (seg.startsWith(".") || SKIP_DIRS.has(seg)))
+}
+
+/** Lower-cased ".ext" of a path, or "" when it has no extension. */
+export function extensionOf(p) {
+  const s = String(p ?? "")
+  const base = s.slice(Math.max(s.lastIndexOf("/"), s.lastIndexOf("\\")) + 1)
+  const i = base.lastIndexOf(".")
+  return i > 0 ? base.slice(i).toLowerCase() : ""
+}
+
+/**
+ * Unlisted-extension tally (PORTABILITY PO-9 — visibility): counts files the index
+ * will NOT pick up because their extension is in no list, so "my .xyz files are not
+ * searchable" stops being invisible. `exts` is a capped sample (the count is the
+ * signal; the list is the hint).
+ * @param {Set<string>} knownExts — every extension that IS indexed (code ∪ doc ∪ declared)
+ */
+export function createUnlistedTally(knownExts) {
+  const counts = new Map()
+  let count = 0
+  return {
+    note(rel) {
+      const ext = extensionOf(rel)
+      if (!ext || knownExts.has(ext)) return
+      count++
+      counts.set(ext, (counts.get(ext) ?? 0) + 1)
+    },
+    result(limit = 12) {
+      const exts = [...counts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, limit)
+        .map(([ext, n]) => ({ ext, count: n }))
+      return { count, exts }
+    },
+  }
+}
+
+/**
+ * Recursive project walk — the no-git listing source. Symlinks are never followed
+ * (loop/escape guard); skipped directories are pruned; only files whose extension
+ * is in `exts` are returned. Hitting maxFiles is reported as `truncated`, never
+ * silently dropped.
+ * @param {string} dir — project root
+ * @param {Set<string>} exts — extensions to keep (lower-case, leading dot)
+ * @param {{maxFiles?: number, knownExts?: Set<string>|null}} [opts]
+ *   knownExts → also tally files whose extension is in NO index list
+ * @returns {Promise<{files: {abs: string, rel: string}[], truncated: boolean,
+ *   unlisted: {count: number, exts: {ext: string, count: number}[]}}>}
+ */
+export async function walkProjectFiles(dir, exts, { maxFiles = MAX_WALK_FILES, knownExts = null } = {}) {
+  const files = []
+  const tally = knownExts ? createUnlistedTally(knownExts) : null
+  let truncated = false
+  const stack = [{ abs: dir, rel: "" }]
+  while (stack.length > 0) {
+    const cur = stack.pop()
+    let entries
+    try {
+      entries = await readdir(cur.abs, { withFileTypes: true })
+    } catch { continue /* unreadable dir — skip, the walk must not fail the sync */ }
+    for (const ent of entries) {
+      const rel = cur.rel ? `${cur.rel}/${ent.name}` : ent.name
+      if (ent.isSymbolicLink()) continue // never follow symlinks
+      if (ent.isDirectory()) {
+        if (!isSkippedRelPath(rel)) stack.push({ abs: join(cur.abs, ent.name), rel })
+        continue
+      }
+      if (!ent.isFile() || isSkippedRelPath(rel)) continue
+      const ext = extensionOf(ent.name)
+      if (!ext || !exts.has(ext)) {
+        tally?.note(rel)
+        continue
+      }
+      if (files.length >= maxFiles) {
+        truncated = true
+        break
+      }
+      files.push({ abs: join(cur.abs, ent.name), rel })
+    }
+    if (truncated) break
+  }
+  return { files, truncated, unlisted: tally ? tally.result() : { count: 0, exts: [] } }
+}

package/src/memory/schema.mjs

@@ -14,10 +14,22 @@ export const VALID_TYPES = new Set(["rule", "knowledge", "decision", "pattern"])
 export const SCHEMA_VERSION = 9
 export const SQLITE_BUSY_TIMEOUT = 3000
 
-// Code index: source file extensions
-export const CODE_EXTS = new Set([".mjs", ".js", ".ts", ".tsx", ".jsx", ".py", ".rs", ".go", ".java", ".c", ".h", ".cpp", ".hpp", ".rb", ".swift", ".kt", ".sh", ".bash", ".sql", ".yaml", ".yml", ".toml", ".json", ".css", ".html", ".vue", ".svelte"])
+// Code index: source file extensions. Curated DEFAULTS — a project can declare
+// more (union) through .thincoder/conventions.json → index.codeExtensions
+// (PORTABILITY PO-9: an unlisted extension used to be invisible AND undeclarable).
+export const CODE_EXTS = new Set([
+  ".mjs", ".js", ".cjs", ".mts", ".cts", ".ts", ".tsx", ".jsx",
+  ".py", ".rs", ".go", ".java", ".c", ".h", ".cpp", ".hpp",
+  ".rb", ".swift", ".kt", ".dart", ".lua", ".cs", ".fs", ".fsx",
+  ".clj", ".cljs", ".ex", ".exs", ".erl", ".hrl", ".scala", ".groovy",
+  ".pl", ".pm", ".r", ".jl", ".zig", ".ps1",
+  ".sh", ".bash", ".sql", ".yaml", ".yml", ".toml", ".json",
+  ".proto", ".graphql", ".tf", ".hcl",
+  ".css", ".html", ".vue", ".svelte",
+])
 // Doc index: markdown / plain text (separate index makes it easier for LLM to distinguish "design specs" from "existing code")
-export const DOC_EXTS = new Set([".md", ".mdc", ".txt", ".rst", ".adoc"])
+// Same declaration rule as CODE_EXTS (index.docExtensions).
+export const DOC_EXTS = new Set([".md", ".mdc", ".mdx", ".txt", ".rst", ".adoc", ".org", ".wiki", ".tex"])
 // Directory names always skipped during code/doc indexing
 // NOTE: these are case-sensitive basename matches; add common platform-specific dirs
 export const SKIP_DIRS = new Set([

package/src/memory.mjs

@@ -7,7 +7,9 @@
 export { createMemory, migrate, segmentCJK, VALID_TYPES, SCHEMA_VERSION, CODE_EXTS, DOC_EXTS, SKIP_DIRS, BIG_FILE_LINES } from "./memory/schema.mjs"
 
 // CRUD + search + ensureEmbeddings
-export { put, search, ftsSearch, fetchEntry, ensureEmbeddings, putMarkdown, syncDir, indexMarkdownFile, list, remove, deleteByUid, matchMemoryRows, deleteWhere, clearPersonal, buildFtsQuery } from "./memory/core.mjs"
+// (delete.mjs owns the disk-truth row match + deletion family — see its header)
+export { put, search, ftsSearch, fetchEntry, ensureEmbeddings, putMarkdown, syncDir, indexMarkdownFile, list, clearPersonal, buildFtsQuery } from "./memory/core.mjs"
+export { matchMemoryRows, deleteWhere, deleteByUid, remove } from "./memory/delete.mjs"
 
 // code chunking + markdown chunking
 export { detectLanguage, extractSymbols, extractPySymbols, chunkCode, extractLeadingDoc, yieldTick, _upsertCodeFile, chunkMarkdown, _upsertDocFile } from "./memory/code-index.mjs"

package/src/model-ref.mjs

@@ -0,0 +1,66 @@
+/**
+ * model-ref.mjs — composite model reference parser (MODEL-MERGE-SESSION; v2 2026-09-10).
+ * A model is an explicit "provider:model" composite — config.defaultModel (top level,
+ * new-session starting point) and session slots both speak this language. 有效域 = **provider 存在
+ * + 双段非空**：清单不再人工维护（模型清单由 provider 运行期 `GET /models` 拉取决定——
+ * PROVIDER.md §16），候选成员校验**已废除**——显式 `p:m` 一律放行（含多冒号首分割）。
+ * providers[].model 是渠道默认模型（单值）——候选清单字段 models[] 已整字段退场。
+ *
+ * Strict first-colon split — deliberately does NOT reuse resolveChildProvider's loose
+ * three-state resolution: ① legacy single-provider configs and ② model-name-only refs
+ * are gone with activeProvider/activeModel (F-1), so a bare provider or bare model is
+ * invalid everywhere (裁定③——裸 provider 拒——显式 p:m)。
+ *
+ * Runtime model resolution:
+ *   parseModelRef(ref, providers)      → { ok, provider, model } | { ok:false, reason }
+ *   resolveRuntimeProvider(providers, defaultModel)
+ *                                      → provider object with `.model` set, or {} when
+ *                                        defaultModel is null/invalid (D-S1: callers mark
+ *                                        _providerInvalid — never throws)
+ *   defaultModelReason(providers, defaultModel) → human reason for the D-S1 marker
+ *
+ * Consumers: config.mjs loadConfig (re-exported as the config hub), make-agent.mjs.
+ */
+export function parseModelRef(ref, providers) {
+  if (typeof ref !== "string" || !ref.trim()) {
+    return { ok: false, reason: 'model reference expected as "provider:model" (e.g. deepseek:deepseek-v4-pro)' }
+  }
+  // 首冒号分割——`a:b:c` → provider=a、model=`b:c`（`ollama:llama3:70b` 式模型名可用，M4）
+  const sep = ref.indexOf(":")
+  if (sep <= 0) {
+    return { ok: false, reason: `invalid model reference "${ref}" — expected provider:model (bare provider/model names are not accepted)` }
+  }
+  const providerName = ref.slice(0, sep)
+  const model = ref.slice(sep + 1)
+  if (!model) {
+    return { ok: false, reason: `invalid model reference "${ref}" — model part is empty (expected provider:model)` }
+  }
+  const list = Array.isArray(providers) ? providers : []
+  const provider = list.find((p) => p?.name === providerName)
+  if (!provider) {
+    const available = list.map((p) => p.name).join(", ") || "(none)"
+    return { ok: false, reason: `unknown provider "${providerName}" in model reference (available: ${available})` }
+  }
+  return { ok: true, provider, model }
+}
+
+/** Resolve the runtime provider object for config.defaultModel: provider clone carrying
+ *  `.model` = the parsed concrete model (API/spec consumers read provider.model unchanged).
+ *  Invalid/missing defaultModel → {} (D-S1 shape — name/model/baseURL absent so
+ *  validateProvider flags it; TUI/headless surface the reason from defaultModelReason). */
+export function resolveRuntimeProvider(providers, defaultModel) {
+  const r = parseModelRef(defaultModel, providers)
+  if (!r.ok) return {}
+  return { ...r.provider, model: r.model }
+}
+
+/** Human-readable reason behind an invalid/empty runtime resolution (D-S1 原因). */
+export function defaultModelReason(providers, defaultModel) {
+  const list = Array.isArray(providers) ? providers : []
+  if (!defaultModel) {
+    return list.length > 0
+      ? "defaultModel 未设置（config 顶层 defaultModel — 新会话起点；/config → 默认模型 设置）"
+      : "未配置任何 provider"
+  }
+  return parseModelRef(defaultModel, list).reason ?? `defaultModel "${defaultModel}" 无效`
+}

package/src/model-specs.mjs

@@ -25,10 +25,18 @@
  * tempRange:         valid temperature range [min, max] (if undeclared, no clamping)
  */
 const MODEL_SPECS = [
-  // DeepSeek V4 series
+  // DeepSeek V4.1 series (2026-09-11). `deepseek-flash` = DeepSeek-V4.1-Flash (in service):
+  // 1M ctx / 384K out, thinking on by default (effort low/high/max), Chat Prefix Completion
+  // beta, automatic disk cache, vision. The two legacy names below are RETIRED — the server
+  // still accepts them and serves them from V4.1-Flash today (no switch window), so their
+  // rows carry the V4.1-Flash parameters (v4-flash gains multimodal).
+  ["deepseek-flash",    { context: 1_000_000, maxOutput: 384_000, thinking: true,  prefixMode: true,  cacheMode: "auto", thinkApi: "type", reasoningEcho: "required", reasoningEffortEnum: ["low", "high", "max"], tempRange: [0, 2], multimodal: true }],
+  // deepseek-v4-pro (V4-Pro-0813): fields unchanged — vision capability NOT verified, so no
+  // multimodal (conservative). From 2026-09-14 12:00 Beijing all requests route to V4.1-Flash.
   ["deepseek-v4-pro",   { context: 1_000_000, maxOutput: 384_000, thinking: true,  prefixMode: true,  cacheMode: "auto", thinkApi: "type", reasoningEcho: "required", reasoningEffortEnum: ["low", "high", "max"], tempRange: [0, 2] }],
-  ["deepseek-v4-flash", { context: 1_000_000, maxOutput: 384_000, thinking: true,  prefixMode: true,  cacheMode: "auto", thinkApi: "type", reasoningEcho: "required", reasoningEffortEnum: ["low", "high", "max"], tempRange: [0, 2] }],
-  // DeepSeek V4 Flash Vision (experimental) — image input on top of the full V4-Flash stack
+  // deepseek-v4-flash: RETIRED name — still accepted, served by V4.1-Flash today → aligned row
+  ["deepseek-v4-flash", { context: 1_000_000, maxOutput: 384_000, thinking: true,  prefixMode: true,  cacheMode: "auto", thinkApi: "type", reasoningEcho: "required", reasoningEffortEnum: ["low", "high", "max"], tempRange: [0, 2], multimodal: true }],
+  // deepseek-v4-flash-vision-exp: retired experimental vision name — still accepted (V4.1-Flash)
   ["deepseek-v4-flash-vision-exp", { context: 1_000_000, maxOutput: 384_000, thinking: true,  prefixMode: true,  cacheMode: "auto", thinkApi: "type", reasoningEcho: "required", reasoningEffortEnum: ["low", "high", "max"], tempRange: [0, 2], multimodal: true }],
   // Kimi series
   ["kimi-k3",           { context: 1_000_000, maxOutput: 131_072, thinking: true,  partialMode: true, multimodal: true, cacheMode: "auto",  thinkApi: "effort", reasoningEcho: "required", reasoningEffortEnum: ["low", "high", "max"] }],
@@ -95,11 +103,15 @@ const DEFAULT_SPEC = { context: 128_000, maxOutput: 32_000, cacheMode: "none" }
  * 且含 "/" 时，剥掉第一个 "/" 前的 namespace 再按前缀匹配一次——ZHIPU/GLM-5.3 → glm-5.3 命中
  * 真实规格，不再降级 128K 默认。kimi/kimi-k3 的显式 alias 行保留为文档锚（发送路径
  * provider.core isRouter 依赖含 "/" 判定），通用机制已覆盖同类。 */
-const warnedModels = new Set() // warn once per model name — specForModel is a hot path (every request)
-// Pre-sorted once at module scope — specForModel runs on every request (agent, provider core,
+const warnedModels = new Set() // warn once per model name — spec lookup runs on every request (hot path)
+// Pre-sorted once at module scope — spec lookup runs on every request (agent, provider core,
 // context, auto-think, TUI rendering); re-sorting per call was wasteful.
 const SORTED_SPECS = [...MODEL_SPECS].sort((a, b) => b[0].length - a[0].length)
-export function specForModel(model) {
+
+/** Single table lookup shared by specForModel / specMatch — prefix match (case-insensitive)
+ *  with vendor-namespace stripping. Returns null on a miss (DEFAULT_SPEC is the caller-side
+ *  fallback and is deliberately NOT returned here — `matched` needs the miss itself). */
+function lookupSpec(model) {
   const m = (model ?? "").toLowerCase()
   for (const [prefix, spec] of SORTED_SPECS) {
     if (m.startsWith(prefix.toLowerCase())) return spec
@@ -112,15 +124,37 @@ export function specForModel(model) {
       if (bare.startsWith(prefix.toLowerCase())) return spec
     }
   }
-  // Unknown model: warn ONCE (not per request) so a typo'd ID or a missing alias surfaces
-  // instead of silently degrading to the 128K default (IK5VGJ).
+  return null
+}
+
+/** Unknown model: warn ONCE (not per request) so a typo'd ID or a missing alias surfaces
+ *  instead of silently degrading to the 128K default (IK5VGJ). The dedupe set is shared by
+ *  specForModel / specMatch (PROVIDER.md §16 M5). */
+function warnUnknownModel(model) {
+  const m = (model ?? "").toLowerCase()
   if (m && !warnedModels.has(m)) {
     warnedModels.add(m)
     console.warn(`[config] model "${model}" not found in MODEL_SPECS — using default spec (128K context, 32K output). Check the model ID or add an alias.`)
   }
+}
+
+export function specForModel(model) {
+  const hit = lookupSpec(model)
+  if (hit) return hit
+  warnUnknownModel(model)
   return DEFAULT_SPEC
 }
 
+/** specMatch(model) → { spec, matched }（PROVIDER.md §16 M5——切换回显的来源判定）。
+ *  `matched:false` = DEFAULT_SPEC 兜底（未知模型）；与 specForModel 共享同一查表实现（单次），
+ *  specForModel 的返回形状与共享对象契约零改（热路径零变）。 */
+export function specMatch(model) {
+  const hit = lookupSpec(model)
+  if (hit) return { spec: hit, matched: true }
+  warnUnknownModel(model)
+  return { spec: DEFAULT_SPEC, matched: false }
+}
+
 /**
  * providerSpec(provider) — spec with a provider-level context override (PROVIDER.md §15, 2026-09-02).
  *