@thincoder/core 0.9.1

package/history-window.mjs

@@ -0,0 +1,179 @@
+/**
+ * history-window.mjs — lazy human-line window (restore / render-facing):
+ * historyWindow + tool-call/result pairing + the real-user-message predicate.
+ *
+ * Pure functions — no fs, no host imports (node --test drives it directly).
+ * Window semantics follow the restore contract (turnStart / reminder-skip /
+ * reasoning), plus one frame rule: an assistant frame becomes ONE message
+ * carrying its tool cards nested (rules below).
+ *
+ * 承接：会话数据面的「人读线」窗口切分（分段恢复 / 逐页回看）——与磁盘会话档
+ * 同源（`{hash}.json.N`），本档只读数组、不触盘。
+ */
+
+/** Real user message predicate (shared by the slot metadata digest and the window).
+ *  NOTE: returns true for an EMPTY string content — rule 1 layers a trim() check on top.
+ *  Null-safe（非对象 / 缺内容 ⇒ false——调用面含批量过滤）。 */
+export function isRealUserMsg(m) {
+  return m?.role === "user" && typeof m?.content === "string" && !m.content.startsWith("[System reminder:")
+}
+
+/** Page size for lazy history loading (initial paint + scroll-back pages).
+ *  200 = the first-window size parity with the main line's initial window; loadOlder
+ *  scroll-back pages step by the same constant. */
+export const HISTORY_PAGE_SIZE = 200
+
+/** Read-side timestamp compat: the real-message writer stamps `ts` (epoch-ms); older
+ *  files may carry `timestamp`; even older carry neither → null. Field name on the
+ *  wire stays `timestamp` (consumers zero-rename). */
+function tsOf(m) {
+  const ts = m?.ts ?? m?.timestamp
+  return typeof ts === "number" ? ts : null
+}
+
+function kindOf(m) {
+  return m?.type ?? m?.role
+}
+
+function toolCallsOf(m) {
+  if (!m || !Array.isArray(m.tool_calls)) return []
+  return m.tool_calls.filter((tc) => tc && typeof tc === "object")
+}
+
+function reasoningOf(m) {
+  const r = m.reasoning_content ?? m.reasoning
+  return typeof r === "string" && r.trim() !== "" ? r : null
+}
+
+/** Assistant frame text = string content only (multimodal arrays are not renderable). */
+function textOf(m) {
+  return typeof m.content === "string" ? m.content : null
+}
+
+/** Ghost frame (rules 2/6): no visible text ∧ no tool_calls ∧ no reasoning → skip
+ *  (everything else is kept — a content-null pure-tool frame renders through its cards). */
+function isGhostAssistant(m) {
+  const text = textOf(m)
+  const hasText = text !== null && text.trim() !== ""
+  return !hasText && toolCallsOf(m).length === 0 && reasoningOf(m) === null
+}
+
+/**
+ * Rules 3/4 — full-history rolling pairing: every tool entry is matched to the most
+ * recent assistant frame (before it) that declared its tool_call_id; each tool entry
+ * is consumed at most once (parallel batches complete out of order — id matching,
+ * declaration order preserved per frame). Orphan determination is against the FULL
+ * history: a window-local "orphan" whose frame lives outside the window is still
+ * consumed here, so it never renders standalone on a second page (防跨页双显).
+ * Returns { frameResults, ownerOf }:
+ *  - frameResults: frame idx → Map(callId → tool entry idx) — cards per frame
+ *  - ownerOf: tool entry idx → consuming frame idx (absent = true orphan)
+ */
+function pairToolEntries(history) {
+  const total = history.length
+  const frameResults = new Map()
+  const ownerOf = new Map()
+  const pending = [] // unpaired declarations (declaration order) — [{ frame, callId }]
+  for (let i = 0; i < total; i++) {
+    const m = history[i]
+    if (kindOf(m) === "assistant") {
+      for (const tc of toolCallsOf(m)) {
+        if (tc.id !== undefined && tc.id !== null) pending.push({ frame: i, callId: tc.id })
+      }
+    } else if (kindOf(m) === "tool" && m.tool_call_id !== undefined && m.tool_call_id !== null) {
+      // most-recent declarer first (a normal file has at most one unpaired declaration per id)
+      for (let p = pending.length - 1; p >= 0; p--) {
+        if (String(pending[p].callId) === String(m.tool_call_id)) {
+          const { frame } = pending[p]
+          pending.splice(p, 1)
+          let map = frameResults.get(frame)
+          if (!map) { map = new Map(); frameResults.set(frame, map) }
+          map.set(String(m.tool_call_id), i)
+          ownerOf.set(i, frame)
+          break
+        }
+      }
+    }
+  }
+  return { frameResults, ownerOf }
+}
+
+/**
+ * Window into the human line for lazy history loading (rules 1-6). `before` = null
+ * takes the LAST page (first paint); otherwise the page [s, e) ending just before
+ * `before`. Half-open [s, e) keeps loadOlder pages from re-rendering the boundary
+ * message. `idx` values are GLOBAL history indexes — pagination never renumbers.
+ */
+export function historyWindow(history, before, pageSize = HISTORY_PAGE_SIZE) {
+  const total = Array.isArray(history) ? history.length : 0
+  if (total === 0) return { messages: [], hasOlder: false }
+  const { frameResults, ownerOf } = pairToolEntries(history)
+  const end = before == null ? total : Math.max(0, Math.min(before, total))
+  const start = Math.max(0, end - pageSize)
+  const messages = []
+  const visible = (i) => {
+    const k = kindOf(history[i])
+    if (k === "user") {
+      const m = history[i]
+      return isRealUserMsg(m) && typeof m.content === "string" && m.content.trim() !== ""
+    }
+    if (k === "assistant") return !isGhostAssistant(history[i])
+    if (k === "tool") return !ownerOf.has(i) // true orphan (unowned across the whole history) → top-level fallback
+    return false
+  }
+  for (let i = start; i < end; i++) {
+    const m = history[i]
+    const kind = kindOf(m)
+    if (kind === "user") {
+      // Rule 1: skip = ¬(isRealUserMsg ∧ content.trim() ≠ "")
+      if (isRealUserMsg(m) && typeof m.content === "string" && m.content.trim() !== "") {
+        messages.push({ kind: "user", text: m.content, timestamp: tsOf(m), idx: i })
+      }
+    } else if (kind === "assistant") {
+      if (isGhostAssistant(m)) continue
+      // Rule 5: turnStart = the previous VISIBLE message is a user or there is none —
+      // scan back past skipped entries (reminder / consumed tool / ghost frame — a skip
+      // never resets the turn, matching the main line's in-turn semantics)
+      let prevVisibleKind = null
+      for (let j = i - 1; j >= 0; j--) {
+        if (visible(j)) { prevVisibleKind = kindOf(history[j]); break }
+      }
+      // Rules 3/4: frame tools[] = one card per declared call, declaration order (a result
+      // may sit past the window's end — pairing is against the full history)
+      const matched = frameResults.get(i)
+      const tools = []
+      for (const tc of toolCallsOf(m)) {
+        const toolIdx = matched?.get(String(tc.id))
+        const toolMsg = toolIdx !== undefined ? history[toolIdx] : null
+        tools.push({
+          id: tc.id ?? null,
+          name: tc.function?.name ?? null,
+          args: typeof tc.function?.arguments === "string" ? tc.function.arguments : null,
+          result: toolMsg && typeof toolMsg.content === "string" ? toolMsg.content : null,
+        })
+      }
+      messages.push({
+        kind: "assistant",
+        text: textOf(m),
+        reasoning: reasoningOf(m),
+        timestamp: tsOf(m),
+        idx: i,
+        turnStart: prevVisibleKind === null || prevVisibleKind === "user",
+        tools,
+      })
+    } else if (kind === "tool") {
+      // A consumed tool entry produces no message of its own (rendered with its frame) —
+      // only a true orphan falls back to the top level (rules 3/4)
+      if (!ownerOf.has(i)) {
+        messages.push({
+          kind: "tool",
+          name: typeof m.name === "string" ? m.name : null,
+          text: typeof m.content === "string" ? m.content : null,
+          timestamp: tsOf(m),
+          idx: i,
+        })
+      }
+    }
+  }
+  return { messages, hasOlder: start > 0 }
+}

package/hooks.mjs

@@ -0,0 +1,108 @@
+/**
+ * hooks.mjs — Lifecycle hook engine
+ *
+ * Hooks are user-defined shell commands executed at key agent lifecycle points.
+ * Configured in ~/.thincoder/config.json under "hooks".
+ *
+ * Event types:
+ *   PreToolUse          — before each tool call (can block execution)
+ *   PostToolUse         — after successful tool execution
+ *   PostToolUseFailure  — after failed tool execution
+ *   Stop                — main-session run end (no tool name; block is meaningless)
+ *
+ * Each hook: { matcher?, command, args?, timeout?, action? }
+ *   matcher: regex against tool name (default: match all)
+ *   command: executable path/name
+ *   args: optional CLI args; without args, stdin receives JSON payload
+ *   timeout: ms (default 10000)
+ *   action: "allow" | "block" | "notify" (default "notify")
+ *
+ * "block" hooks: exit code 0 = allow, non-zero = block.
+ * "allow"/"notify": exit code ignored.
+ */
+
+import { spawn } from "node:child_process"
+
+/** @param {string} event @param {object} ctx @returns {Promise<boolean>} false if blocked */
+export async function runHooks(event, ctx) {
+  const hooks = ctx.agent?.config?.hooks?.[event]
+  if (!hooks?.length) return true
+
+  for (const hook of hooks) {
+    // Matcher = tool-name regex: tool events always carry a toolName; no-tool-name
+    // events (Stop) ignore it — a configured matcher must not silently never fire.
+    if (hook.matcher && ctx.toolName != null) {
+      try {
+        if (!new RegExp(hook.matcher).test(ctx.toolName)) continue
+      } catch { /* invalid regex → skip */ }
+    }
+
+    const allowed = await runOneHook(event, hook, ctx)
+    if (hook.action === "block" && !allowed) return false
+  }
+  return true
+}
+
+async function runOneHook(event, hook, ctx) {
+  const payload = JSON.stringify({
+    event,
+    toolName: ctx.toolName ?? null,
+    toolArgs: ctx.toolArgs ?? null,
+    result: ctx.result ?? null,
+    error: ctx.error?.message ?? null,
+    // Event-specific fields (Stop: turn / reason) — existing callers pass no extra ⇒ payload unchanged.
+    ...(ctx.extra ?? {}),
+    timestamp: new Date().toISOString(),
+  })
+
+  return new Promise((resolve) => {
+    const timeout = hook.timeout ?? 10_000
+    let settled = false
+    let guard = null
+    const done = (code) => {
+      if (settled) return
+      settled = true
+      if (guard) clearTimeout(guard) // #135-④：守卫句柄收尾清理（unref 后的显式释放）
+      resolve(code === 0)
+    }
+
+    let proc
+    try {
+      // 不传 spawn 的 `timeout` 选项（#135-④）：其内部定时器在 spawn 失败（ENOENT）路径
+      // 不被清理、也不 unref ⇒ 单独维持事件循环整整 `timeout` ms（实测：命令不存在时
+      // 10023ms 退出，去掉该选项后 6ms）——超时杀子进程改由下方自有 guard 承担（同时点、
+      // 同默认信号 SIGTERM，语义等价）。
+      if (hook.args?.length) {
+        proc = spawn(hook.command, hook.args, {
+          stdio: ["pipe", "ignore", "ignore"],
+          windowsHide: true,
+        })
+      } else {
+        proc = spawn(hook.command, [], {
+          stdio: ["pipe", "ignore", "ignore"],
+          windowsHide: true,
+        })
+      }
+    } catch {
+      // command not found or spawn failure — don't block, don't crash
+      return resolve(true)
+    }
+
+    proc.on("error", () => done(0))     // spawn failure → allow
+    proc.on("close", (code) => done(code ?? 0))
+    proc.on("exit", (code) => done(code ?? 0))
+
+    // Send payload via stdin
+    try { proc.stdin?.end(payload) } catch { /* */ }
+
+    // Timeout guard（#135-④：`timeout` ms 到点杀掉子进程 + 放行——原由 spawn 的 `timeout`
+    // 选项承担，见上）。句柄捕获 + `unref()`：进程存活期间守卫照常触发（真 CLI 运行事件循环
+    // 另有 handle），但不再单独维持事件循环存活 ⇒ 子进程钩子用例的测试进程零尾挂；
+    // 任一出口经 `done` 收尾 clearTimeout（house 先例 = mcp/transport-stdio.mjs:20）。
+    guard = setTimeout(() => {
+      try { proc.kill() } catch { /* already gone */ }
+      done(0)
+    }, timeout)
+    guard.unref?.()
+  })
+}

package/i18n.mjs

@@ -0,0 +1,106 @@
+/**
+ * i18n.mjs — 核内文案常量容器（§2.5 #185 / 丁组 D1 裁定「容器归一、投影端差」）。
+ *
+ * 形态（用户 2026-09-13 裁定 · 按建议）：
+ *  - `CORE_MESSAGES` = 键 → `{ en, zh }`：核内文案**单一权威容器**（本批收编两端同语义文案）。
+ *  - `t(key, vars, locale)` = 核侧解析（CLI 直接用常量；缺键回退返回 key——不抛）。
+ *  - `projectDictionary(locale)` = **VSC 字典投影**：核常量 → VSC `locales/*.json` 的扁平
+ *    字典形态（VSC 的 `i18n.mjs` `t()` 壳在 S2 接线时并入本投影，壳内零文案）。
+ *
+ * 契约（CORE-UNIFICATION §2.12.2 第 12 行 · 输出文案类）：**机器消费面冻结**——本表键值
+ * 与现 VSC `locales/{en,zh}.json` 逐字一致（已锁定串不得改）；人读文案后续变更须登记 +
+ * CHANGELOG（S2 落地物）。`${name}` = 插值占位（两端同约定）。
+ *
+ * 边界：本模块只收「核域」文案（压缩 / 消化 / 限流状态 / 异步池状态 / 会诊 / 任务 / goal /
+ * 思考状态）；webview 面板专属文案（welcome / toolbar / settings / perm 卡等）留在 VSC 侧
+ * 字典（④ 端特有面——宿主 UI）。
+ */
+
+/** 支持的语言（与 VSC locales 文件名一致）。 */
+export const SUPPORTED_LOCALES = ["en", "zh"]
+
+/**
+ * 核内文案常量容器：键 → { en, zh }。
+ * 值 = 现 VSC `locales/{en,zh}.json` 逐字（机器消费面冻结——改值须走 A11 登记 + CHANGELOG）。
+ */
+export const CORE_MESSAGES = Object.freeze({
+  // ── 压缩（context compaction）──
+  "compress.start": { en: "Compressing context… (summarizing ${n} messages)", zh: "正在压缩上下文…（摘要 ${n} 条消息）" },
+  "compress.starting": { en: "Compressing context…", zh: "正在压缩上下文…" },
+  "compress.done": { en: "Compressed: ${tokens} tokens freed (${seconds}s)", zh: "已压缩：释放 ${tokens} tokens（${seconds} 秒）" },
+  "compress.failed": { en: "Compression failed: ${error}", zh: "压缩失败：${error}" },
+  "compress.fallback": { en: "Compression failed — fallback: truncated to ${n} messages", zh: "压缩失败 — 降级：截断为 ${n} 条消息" },
+  // ── 消化（auto-turn digest）──
+  "digest.start": { en: "Digesting ${n} background report(s)…", zh: "正在消化 ${n} 份后台报告…" },
+  "digest.done": { en: "Digested ${n} background report(s) (${seconds}s)", zh: "已消化 ${n} 份后台报告（${seconds}s）" },
+  "digest.aborted": { en: "Digestion interrupted (${seconds}s)", zh: "消化中断（${seconds}s）" },
+  "digest.turnLabel": { en: "[auto-turn: digesting finished subagent reports…]", zh: "自动回合：消化已完成的子代理报告…" },
+  // M4（2026-09-20 端差·显示面消差批）：起跑标签三档（en = CLI `suspension-drive.mjs:175-176`
+  // 逐字；zh = 与上方既有档同式译法）——VSC 本地档不重复定义（单一权威容器）。
+  "digest.turnLabelAsk": { en: "[auto-turn: answering a subagent's in-flight message…]", zh: "自动回合：答复子代理的在飞提问…" },
+  "digest.turnLabelAuto": { en: "[auto-turn: continuing background work…]", zh: "自动回合：继续后台推进…" },
+  "digest.capAuto": { en: "[auto-turn: continuing past turn cap…]", zh: "自动回合：越过轮次上限，继续推进…" },
+  "digest.capStop": { en: "[auto-turn stopped at ${turns} turns — partial digest; finished reports stay in history]", zh: "自动回合在 ${turns} 轮处停止——部分消化；已完成的报告保留在历史中" },
+  // ── 限流 / 供应商状态行 ──
+  "status.rateWait": { en: "TPM throttle wait ~${s}s", zh: "TPM 限流等待 ~${s}s" },
+  "status.rateLimited": { en: "Rate-limited 429, retry in ${s}s", zh: "限流 429，${s}s 后重试" },
+  "status.overloaded": { en: "Server overloaded, retrying in ${s}s", zh: "服务过载，${s}s 后重试" },
+  "status.quota": { en: "quota exhausted: ${msg}", zh: "配额耗尽：${msg}" },
+  // ── 异步池状态词 ──
+  "sub.running": { en: "running", zh: "运行中" },
+  "sub.queued": { en: "queued", zh: "排队中" },
+  "sub.stopped": { en: "stopped", zh: "已停止" },
+  "sub.done": { en: "done", zh: "完成" },
+  "sub.error": { en: "error", zh: "错误" },
+  "sub.cancelled": { en: "cancelled", zh: "已取消" },
+  "sub.awaitingDigest": { en: "done · awaiting digestion", zh: "已完成 · 等待消化" },
+  "sub.queueSlot": { en: "queued · position ${n} (slot full)", zh: "排队中 · 位置 ${n}（槽满等位）" },
+  // ── 会诊状态词 ──
+  "consult.answered": { en: "answered", zh: "已回复" },
+  "consult.terminated": { en: "terminated", zh: "已终止" },
+  // ── 任务 / goal ──
+  "task.in_progress": { en: "in progress", zh: "进行中" },
+  "goal.criteria": { en: "Criteria", zh: "验收标准" },
+  // ── 思考 / 工具状态词 ──
+  "status.stopped": { en: "[stopped]", zh: "[已停止]" },
+  "status.thinking": { en: "Thinking", zh: "思考中" },
+  "status.turn": { en: "turn ${n}/${m}", zh: "轮次 ${n}/${m}" },
+  "tool.running": { en: "running…", zh: "执行中…" },
+  "tool.done": { en: "done", zh: "完成" },
+})
+// 深度冻结（机器消费面冻结——嵌套 { en, zh } 也冻结；浅冻结下值可被静默改写）。
+for (const entry of Object.values(CORE_MESSAGES)) Object.freeze(entry)
+
+/** 语言归一（BCP-47：`zh-CN` → `zh`；未知 → `en`——镜像 VSC `_load` 的候选回退）。 */
+export function normalizeLocale(locale) {
+  const raw = String(locale ?? "").trim()
+  if (!raw) return "en"
+  if (SUPPORTED_LOCALES.includes(raw)) return raw
+  const base = raw.split("-")[0]
+  return SUPPORTED_LOCALES.includes(base) ? base : "en"
+}
+
+/**
+ * 核侧解析：`t("compress.starting")` / `t("digest.done", { n: 2, seconds: "1.2" })`。
+ * 缺键回退返回 key 本身（两端同口径——不抛）。
+ */
+export function t(key, vars = {}, locale = "en") {
+  const entry = CORE_MESSAGES[key]
+  if (entry === undefined) return key
+  let val = entry[normalizeLocale(locale)] ?? entry.en
+  for (const [k, v] of Object.entries(vars)) {
+    val = val.replace("${" + k + "}", String(v))
+  }
+  return val
+}
+
+/**
+ * VSC 字典投影：核常量 → 扁平 `{ key: value }`（VSC `locales/*.json` 形态）。
+ * S2 接线：VSC `i18n.mjs` 的 `_load` 以本投影为核域底座 + 端特有键（webview 面）叠加。
+ */
+export function projectDictionary(locale = "en") {
+  const lang = normalizeLocale(locale)
+  const out = {}
+  for (const [key, entry] of Object.entries(CORE_MESSAGES)) out[key] = entry[lang] ?? entry.en
+  return out
+}

package/index-bin.mjs

@@ -0,0 +1,48 @@
+/**
+ * index-bin.mjs — binary I/O for the semantic vector index（CORE-UNIFICATION §2.5 #137
+ * 「融合：随核内索引面一并归位（向量编解码）」）。
+ *
+ * 来源 = `thincoder-vscode/src/index-bin.mjs`（VSC 拆档——CLI 侧无切分档）——**逐字随迁**；
+ * 零依赖（只 `node:buffer` 的 `Buffer`）⇒ 直接归位。
+ *
+ * vectors.bin layout: [4B dim][4B count][count × 4B offsets][all raw Float32 vectors]
+ */
+
+export function encodeVectors(dim, vectors) {
+  const count = vectors.length
+  const headerSize = 8 + count * 4
+  const dataSize = count * dim * 4
+  const buf = Buffer.alloc(headerSize + dataSize)
+
+  buf.writeUInt32LE(dim, 0)
+  buf.writeUInt32LE(count, 4)
+
+  let offset = headerSize
+  for (let i = 0; i < count; i++) {
+    buf.writeUInt32LE(offset, 8 + i * 4)
+    const vec = vectors[i]
+    for (let j = 0; j < dim; j++) {
+      buf.writeFloatLE(vec[j], offset + j * 4)
+    }
+    offset += dim * 4
+  }
+
+  return buf
+}
+
+export function decodeVectors(buf) {
+  const dim = buf.readUInt32LE(0)
+  const count = buf.readUInt32LE(4)
+
+  const vectors = []
+  for (let i = 0; i < count; i++) {
+    const offset = buf.readUInt32LE(8 + i * 4)
+    const vec = new Float32Array(dim)
+    for (let j = 0; j < dim; j++) {
+      vec[j] = buf.readFloatLE(offset + j * 4)
+    }
+    vectors.push(vec)
+  }
+
+  return { dim, vectors }
+}

package/index-discover.mjs

@@ -0,0 +1,176 @@
+/**
+ * index-discover.mjs — file discovery + kind classification for the semantic index
+ * （CORE-UNIFICATION §2.5 #137「融合：随核内索引面一并归位（走查规则）」）。
+ *
+ * 来源 = `thincoder-vscode/src/index-discover.mjs`（VSC 拆档——CLI 无切分档；VSC 头注自述
+ * 「CLI-aligned」⇒ 走查规则两端同源）——**逐字随迁**；依赖 `./conventions.mjs`（核内在位）。
+ *
+ * PORTABILITY VSC mirror · VP-9 (P9): the extension tables were 14 code + 5 doc
+ * entries with no declaration surface — a project in any other mainstream language
+ * was invisible AND undeclarable, silently. Now: the tables carry the CLI-aligned
+ * additions, `.thincoder/conventions.json` (index.codeExtensions / index.docExtensions)
+ * unions in project-specific extensions, and files whose extension is in NO list are
+ * TALLIED (`collectUnlisted`) so "my .xyz files are not searchable" stops being
+ * invisible (buildIndex → panel hint + a log event).
+ */
+import { readdirSync } from "node:fs"
+import { join, relative } from "node:path"
+import { DEFAULT_CONVENTIONS, loadConventions } from "./conventions.mjs"
+
+const CODE_EXTS = new Set([
+  ".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx", ".py", ".rs", ".go", ".java", ".c", ".cpp", ".h", ".hpp",
+  // VP-9 additions (CLI-table alignment): languages whose absence made a whole
+  // project invisible. Anything still missing is declarable (index.codeExtensions).
+  ".mts", ".cts", ".dart", ".lua", ".cs", ".fs", ".fsx", ".clj", ".cljs", ".ex", ".exs", ".erl", ".hrl",
+  ".scala", ".pl", ".pm", ".r", ".jl", ".zig", ".groovy", ".ps1", ".proto", ".graphql", ".tf", ".hcl",
+])
+const DOC_EXTS = new Set([".md", ".markdown", ".txt", ".rst", ".adoc", ".mdx", ".org", ".wiki", ".tex"])
+export const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".turbo", "coverage", "__pycache__", ".next"])
+
+/** Lower-cased ".ext" of a path/name ("" when it has no extension). */
+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() : ""
+}
+
+/** Effective extension sets for one conventions object: defaults ∪ declared
+ *  (declaration is a UNION — §4.1: index.*Extensions APPEND). Cached per frozen
+ *  conventions object (the loader hands out stable per-root instances). */
+const _knownCache = new WeakMap()
+function knownExtensions(conv) {
+  const key = conv ?? DEFAULT_CONVENTIONS
+  let hit = _knownCache.get(key)
+  if (!hit) {
+    const code = new Set(CODE_EXTS)
+    const doc = new Set(DOC_EXTS)
+    for (const e of key.index?.codeExtensions ?? []) code.add(e)
+    for (const e of key.index?.docExtensions ?? []) doc.add(e)
+    hit = { code, doc, all: new Set([...code, ...doc]) }
+    _knownCache.set(key, hit)
+  }
+  return hit
+}
+
+/** Unlisted-extension tally (VP-9 visibility): counts files the index will NOT
+ *  pick up because their extension is in no list. `exts` is a capped sample (the
+ *  count is the signal; the list is the hint). */
+export const UNLISTED_SAMPLE_CAP = 20
+function createUnlistedTally() {
+  const counts = new Map()
+  let count = 0
+  return {
+    note(ext) {
+      if (!ext) return
+      count++
+      counts.set(ext, (counts.get(ext) ?? 0) + 1)
+    },
+    result() {
+      const exts = [...counts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, UNLISTED_SAMPLE_CAP)
+        .map(([ext, n]) => ({ ext, count: n }))
+      return { count, exts }
+    },
+  }
+}
+
+/** Shared walker — ONE rule set for whole-tree discovery, the ignored-subtree walk
+ *  (needsRebuild B2) and the memory self-check (listMemoryFiles): SKIP_DIRS / dot-dirs are
+ *  not entered, .thincoder is entered only for memory/, files are filtered by extension.
+ *  Keeping a single implementation is what makes "discovery" and "rebuild decision" unable
+ *  to disagree (§4.2 契约六/七). With `collectUnlisted`, files whose extension is in no
+ *  list are tallied instead of silently dropped. */
+function collectFiles(rootDir, cwd, inThincoder, signal, conv, collectUnlisted) {
+  const { all } = knownExtensions(conv)
+  const tally = collectUnlisted ? createUnlistedTally() : null
+  const files = []
+  function walk(dir, insideThincoder) {
+    let entries
+    try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
+    for (const e of entries) {
+      signal?.throwIfAborted()
+      // Inside .thincoder keep ONLY memory/ (skip index/, sessions/, checklist.md, …)
+      if (insideThincoder && e.name !== "memory") continue
+      if (e.isDirectory()) {
+        // Enter .thincoder at the project root (and its memory/ subdir); skip other dot-dirs.
+        if (SKIP_DIRS.has(e.name)) continue
+        if (e.name.startsWith(".") && e.name !== ".thincoder") continue
+        walk(join(dir, e.name), e.name === ".thincoder")
+      } else if (e.isFile()) {
+        if (isIndexableName(e.name, all)) {
+          files.push(relative(cwd, join(dir, e.name)).replaceAll("\\", "/"))
+        } else {
+          tally?.note(extensionOf(e.name))
+        }
+      }
+    }
+  }
+  walk(rootDir, inThincoder)
+  return { files, unlisted: tally ? tally.result() : { count: 0, exts: [] } }
+}
+
+function isIndexableName(name, allExts) {
+  const ext = extensionOf(name)
+  return ext !== "" && allExts.has(ext)
+}
+
+/**
+ * Discover indexable files under the project root.
+ * @param {string} cwd — project root
+ * @param {AbortSignal} [signal]
+ * @param {{collectUnlisted?: boolean}} [opts] — collectUnlisted: ALSO tally files whose
+ *   extension is in no list; the return becomes `{ files, unlisted }` where
+ *   `unlisted = { count, exts: [{ext, count}] }` (sample capped). Default: the plain
+ *   files array (backward-compatible with needsRebuild / the memory self-check).
+ */
+export function discoverFiles(cwd, signal, { collectUnlisted = false } = {}) {
+  const res = collectFiles(cwd, cwd, false, signal, loadConventions(cwd), collectUnlisted)
+  return collectUnlisted ? res : res.files
+}
+
+/** Indexable files under one subtree, relative to `cwd` — same walk rules as discoverFiles
+ *  (used by needsRebuild to walk an ignored directory entry: §4.2 契约六). */
+export function discoverFilesUnder(cwd, subdir, { collectUnlisted = false } = {}) {
+  const base = String(subdir ?? "").replaceAll("\\", "/").replace(/\/+$/, "")
+  if (!base) return collectUnlisted ? { files: [], unlisted: { count: 0, exts: [] } } : []
+  const res = collectFiles(join(cwd, base), cwd, false, undefined, loadConventions(cwd), collectUnlisted)
+  return collectUnlisted ? res : res.files
+}
+
+/** Extension-level predicate (defaults ∪ declared). */
+export function isIndexableFile(filePath, conv) {
+  return isIndexableName(String(filePath ?? ""), knownExtensions(conv).all)
+}
+
+/** Full predicate: is this relative path a file the index tracks? (extension + the same
+ *  directory exclusions discoverFiles applies — SKIP_DIRS and hidden dirs, except the
+ *  .thincoder/memory/ special case). Used by needsRebuild so "discovery" and "rebuild
+ *  decision" can never disagree. */
+export function shouldIndexFile(relPath, conv) {
+  const p = relPath.replaceAll("\\", "/")
+  if (p.startsWith(".thincoder/memory/")) return isIndexableFile(p, conv)
+  for (const d of p.split("/").slice(0, -1)) {
+    if (SKIP_DIRS.has(d) || d.startsWith(".")) return false
+  }
+  return isIndexableFile(p, conv)
+}
+
+export function kindFor(filePath, conv) {
+  // memory files live in .thincoder/memory/ — check FIRST: they're .md, DOC_EXTS would
+  // otherwise classify them as docs.
+  if (filePath.startsWith(".thincoder/memory/")) return "memory"
+  const { code, doc } = knownExtensions(conv)
+  const ext = extensionOf(filePath)
+  if (code.has(ext)) return "code"
+  if (doc.has(ext)) return "doc"
+  return "doc"
+}
+
+/** Memory files the index tracks — recursive, through the SAME walk as discovery
+ *  (§4.2 契约七: the old flat readdirSync missed nested files, so they were indexed and
+ *  then judged file-removed on every needsRebuild — an endless rebuild loop). */
+export function listMemoryFiles(cwd) {
+  return discoverFilesUnder(cwd, ".thincoder/memory")
+}