thincoder 0.12.60 → 0.12.62

package/src/expand-home.mjs

@@ -0,0 +1,16 @@
+/**
+ * expand-home.mjs — 配置路径字段家目录展开器（第 29 批 HOME-EXPANSION，2026-09-11）。
+ * `loadConfig()` 单一规范化点（设计 MEMORY.md §9.3a）：纯函数、零依赖、home 可注入。
+ */
+
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+/** 展开配置路径字段的前缀 `~`（`~` / `~/` / `~\`）为主目录绝对路径；不识别形态原样返回。
+ *  home 第二参 = 测试注入缝（生产缺省 homedir()）。 */
+export function expandHome(p, home = homedir()) {
+  if (typeof p !== "string" || !p.startsWith("~")) return p   // 非字符串 / 非 ~ 前缀 → 原样
+  if (p === "~") return home                                  // 裸 ~ = 主目录
+  if (p[1] !== "/" && p[1] !== "\\") return p                 // ~user 等非分隔符 → 原样（不猜用户）
+  return join(home, p.slice(2).replaceAll("\\", "/"))         // 余段分隔符归一（跨端统一）
+}

package/src/generate-title.mjs

@@ -46,7 +46,7 @@ export async function generateTitle(userContent, provider) {
     const url = `${provider.baseURL.replace(/\/+$/, "")}${chatPath}`
     const opts = {
       method: "POST",
-      headers: { "Content-Type": "application/json", Authorization: `Bearer ${provider.apiKey}` },
+      headers: { ...(provider.headers ?? {}), "Content-Type": "application/json", Authorization: `Bearer ${provider.apiKey}` }, // 定制头展开（PROVIDER.md §21）——定制头在前、内置头在后：内置头胜出
       body,
       signal: AbortSignal.timeout(10000),
     }
@@ -69,9 +69,14 @@ export async function generateTitle(userContent, provider) {
 export async function ensureSessionTitle(agent) {
   if (agent.title) return agent.title
   try {
-    const firstUser = (agent._fullHistory ?? agent.history).find(
-      (m) => m.role === "user" && typeof m.content === "string" && !m.content.startsWith("[System reminder:"),
-    )
+    // TUI-OOM-ROOTCAUSE 批（SESSION.md §14.3.3）：绑定态首条 user 消息在记录存储（段 1）——
+    // 内存窗口可能已滑过它（store.firstUserMessage 首扫一次并缓存）；未绑定回退内存查找。
+    let firstUser = agent._recordStore?.firstUserMessage?.() ?? null
+    if (!firstUser) {
+      firstUser = (agent._fullHistory ?? agent.history).find(
+        (m) => m.role === "user" && typeof m.content === "string" && !m.content.startsWith("[System reminder:"),
+      )
+    }
     if (firstUser) {
       const title = await generateTitle(firstUser.content, agent.provider)
       if (title) agent.title = title

package/src/heap-watch.mjs

@@ -0,0 +1,88 @@
+/**
+ * heap-watch.mjs — 堆遥测/看门狗（TUI-OOM-ROOTCAUSE 批——CRASH-REPORTS.md §8）。
+ *
+ * 事故会话堆爬升 ~19 分钟无任何事前信号（「炸了才知道」）；本模块补「事前预警」：
+ * 60s 采样 + 堆上限比例双档（70% / 85%）边缘触发 → stderr 行 + TUI 行（订阅制）+
+ * 事件日志。**只看不治**（不强制 GC、不阻断、不触发快照——D-HW2）。
+ *
+ * 关口（§8.3）：阈值 = `heapUsed / v8.getHeapStatistics().heap_size_limit`（比例——可移植，
+ * 无绝对 MB 常量）；双档边缘触发（每档一次/进程——不重复刷屏）；零常态开销
+ * （60s 一次 memoryUsage()，无输出——D-HW5）。
+ *
+ * 开关单点：`THINCODER_HEAP_WATCH`——关值集合 {`0`,`false`,`off`,`no`}（trim + 大小写
+ * 不敏感）→ 不启动；未设/空串/其他值 → 启动（默认开——与 F3② 同约定）。
+ *
+ * 注入缝（N5 可测）：`sample` / `heapLimit` / `timer`——测试以假实现 + `checkNow()`
+ * 直驱（零等待）；失败面全吞（采样抛错不阻断——样本失败静默跳过本次）。
+ */
+import { getHeapStatistics } from "node:v8"
+import { logEvent } from "./log.mjs"
+
+/** 关值集合（单点判定——§3.2 同约定复用）。 */
+export const HEAP_WATCH_OFF = new Set(["0", "false", "off", "no"])
+
+/** 开关判定（单点——grep 面：仅本模块读 env.THINCODER_HEAP_WATCH）。 */
+export function heapWatchEnabled(env = process.env) {
+  const v = String(env.THINCODER_HEAP_WATCH ?? "").trim().toLowerCase()
+  return !HEAP_WATCH_OFF.has(v)
+}
+
+// 订阅表（TUI 行接线——§8.3 订阅制；模块级：武装在 bin、订阅在 startTUI）
+const _subscribers = new Set()
+
+/** 订阅预警行（返回退订函数）。 */
+export function onHeapWarn(cb) {
+  if (typeof cb !== "function") return () => {}
+  _subscribers.add(cb)
+  return () => _subscribers.delete(cb)
+}
+
+/** 预警行格式化（逐字——§8.3；U/L 一位小数、P 取整）。 */
+export function heapWarnLine(used, limit, ratio) {
+  const gb = (n) => (n / 1024 / 1024 / 1024).toFixed(1)
+  return `[heap] warning: heapUsed ${gb(used)} GB / ${gb(limit)} GB heap limit (${Math.round(ratio * 100)}%) — long session; consider /new to reset context`
+}
+
+/**
+ * 启动看门狗（返回 `{ stop(), checkNow() }`——checkNow 直驱一次采样并返回本轮新发预警行）。
+ * 关值（§8.3）→ 不注册定时器（返回惰性句柄）。
+ */
+export function startHeapWatch({
+  intervalMs = 60_000,
+  ratios = [0.7, 0.85],
+  sample = process.memoryUsage,
+  heapLimit = () => getHeapStatistics().heap_size_limit,
+  env = process.env,
+  timer = setInterval,
+} = {}) {
+  const warned = new Set()
+  const checkNow = () => {
+    const out = []
+    try {
+      const used = sample()?.heapUsed ?? 0
+      const limit = heapLimit()
+      if (!(limit > 0)) return out
+      const ratio = used / limit
+      for (const r of ratios) {
+        if (ratio >= r && !warned.has(r)) {
+          warned.add(r) // 每档一次/进程
+          const line = heapWarnLine(used, limit, ratio)
+          out.push(line)
+          try { console.error(line) } catch { /* 输出失败不阻断 */ } // stderr（headless 主面——§8.3）
+          for (const cb of _subscribers) { try { cb(line) } catch { /* 订阅者失败不阻断 */ } }
+          try { logEvent("heap-warn", { kind: "heap-warn", used, limit, ratio: Number(ratio.toFixed(3)) }) } catch { /* 日志失败不阻断（D-HW4） */ }
+        }
+      }
+    } catch { /* 失败面全吞（N5——采样/上限抛错不阻断、状态保持） */ }
+    return out
+  }
+  if (!heapWatchEnabled(env)) return { stop() {}, checkNow }
+  const handle = timer(checkNow, intervalMs)
+  try { handle?.unref?.() } catch { /* unref 失败不阻断（一次性命令自然退出） */ }
+  return {
+    stop() {
+      try { clearInterval(handle) } catch { /* 已停/不可清——静默（尽力面） */ }
+    },
+    checkNow,
+  }
+}

package/src/hooks.mjs

@@ -8,7 +8,7 @@
  *   PreToolUse          — before each tool call (can block execution)
  *   PostToolUse         — after successful tool execution
  *   PostToolUseFailure  — after failed tool execution
- *   Notification        — generic notification (triggered by agent)
+ *   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)
@@ -29,9 +29,11 @@ export async function runHooks(event, ctx) {
   if (!hooks?.length) return true
 
   for (const hook of hooks) {
-    if (hook.matcher) {
+    // 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
+        if (!new RegExp(hook.matcher).test(ctx.toolName)) continue
       } catch { /* invalid regex → skip */ }
     }
 
@@ -48,6 +50,8 @@ async function runOneHook(event, hook, ctx) {
     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(),
   })
 

package/src/ledger.mjs

@@ -0,0 +1,227 @@
+/**
+ * ledger.mjs — 台账（需求池 / 技术待办）单源读取面（LEDGER-SURFACE 批——设计档 §2.30.3）。
+ *
+ * 数字单源（F7）：解析（`scanGroups`）/ 计数 / 老化 / 阈值一处实现——机检器
+ * （`scripts/check-ledger.mjs`）与显示面（CLI TUI `src/tui/ledger-surface.mjs`）共用本口径；
+ * VSC 端为独立实现、语义同源（不跨仓 import）。
+ * 口径（需求档 §1.18）：计数 = `##` 组内 `- [ ]` 未决条目；老化 = 技术组无 `触发=` 且行龄
+ * > 30 天（行龄未知不计）；阈值 = 池 ≥ 3 或任一板块 ≥ 2；可动作 = 老化 > 0 或阈值达成。
+ * 行文本逐字契约 = 设计档 §2.30.3.3（本模块只产出文本，色 / 态归各端显示面）。
+ */
+import { mkdirSync, opendirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs"
+import { basename, dirname, join, resolve } from "node:path"
+import { execFileSync } from "node:child_process"
+import { configDir } from "./config.mjs"
+
+/** 老化阈值（天——口径 = 需求档 §1.18；`days` 参数可覆盖）。 */
+export const AGING_DAYS = 30
+/** 「可开批」阈值：同一板块（池条目指针所指需求档文档名）未决 ≥ 2。 */
+export const THRESHOLD_BOARD = 2
+/** 「可开批」阈值：需求池未决 ≥ 3。 */
+export const THRESHOLD_POOL = 3
+/** 刷新周期（N2 实现常量；VSC 端另有换项目事件触发）。 */
+export const REFRESH_MS = 120000
+/** 变化行去重档（跨会话、跨端共享——需求档 §1.18 F5；configDir 先例 = crash-reports 同区）。 */
+export const NOTIFY_FILE = join(configDir, "ledger-notify.json")
+/** 空族提示（仅命令面——运行时面静默，N1 / 设计档 §2.30.3.3）。 */
+export const EMPTY_FAMILY_LINE = "台账：未发现台账（docs/TODO.md）。"
+
+const LEDGER_REL = join("docs", "TODO.md")
+const H2_RE = /^##\s+(.*)$/
+const DECL_RE = /（(\d+)\s*条）/
+const OPEN_ENTRY_RE = /^- \[ \]\s+/
+const TRIGGER_RE = /触发\s*=\s*([^·\n]*)/
+const BOARD_REF_RE = /requirements\/([A-Za-z0-9_.-]+\.md)/
+
+/** `##` 组扫描（与机检器 L2/L3 同源——解析唯一实现）：[{name,line,declared,entries:[{line,text}]}]。 */
+export function scanGroups(lines) {
+  const groups = []
+  lines.forEach((l, i) => {
+    const h = H2_RE.exec(l)
+    if (h) groups.push({ name: h[1].trim(), line: i + 1, declared: Number((DECL_RE.exec(h[1]) ?? [])[1] ?? NaN), entries: [] })
+    else if (groups.length && OPEN_ENTRY_RE.test(l)) groups[groups.length - 1].entries.push({ line: i + 1, text: l })
+  })
+  return groups
+}
+
+/** 条目归一化文本 = 条目键（去 `- [ ] ` 前缀 + 去首尾空白 + 连续空白折叠单空格）。
+ *  位置无关（位移 / 他条编辑稳定）；自身文本变更 = 键变（最坏一次重报）。§2.30.3.2。 */
+export function normalizeEntry(text) {
+  return text.replace(/^- \[[ x]\]\s+/, "").trim().replace(/\s+/g, " ")
+}
+
+/** 条目标题：首个 `**…**` 段；无粗体段 → 归一化文本前 20 字（超出加 `…`）。§2.30.3.3 L3。 */
+export function entryTitle(text) {
+  const m = /\*\*(.+?)\*\*/.exec(text)
+  if (m) return m[1]
+  const norm = normalizeEntry(text)
+  return norm.length > 20 ? norm.slice(0, 20) + "…" : norm
+}
+
+const isFile = (p) => { try { return statSync(p).isFile() } catch { return false } }
+
+/** 向上（含自身）最近的含台账目录 → {root, ledger} / null（F4——CLI 锚 = cwd）。 */
+export function findProject(anchor) {
+  let dir = resolve(anchor)
+  for (;;) {
+    const ledger = join(dir, LEDGER_REL)
+    if (isFile(ledger)) return { root: dir, ledger }
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/** 同级枚举上限（N2 成本有界：父目录超此规模 = 缓存 / 临时等非仓族形态 → 退化空集，只显当前项目）。 */
+export const MAX_SIBLING_SCAN = 100
+
+/** 目录下含台账的直接子目录（目录名升序；不可读 → []；**惰性枚举 + 上限**——大目录零全量扫描）。 */
+function ledgerChildren(dir) {
+  const out = []
+  let handle
+  try { handle = opendirSync(dir) } catch { return out }
+  try {
+    let n = 0
+    for (;;) {
+      const ent = handle.readSync()
+      if (!ent) break
+      if (++n > MAX_SIBLING_SCAN) return []
+      if (!ent.isDirectory()) continue
+      const root = join(dir, ent.name)
+      const ledger = join(root, LEDGER_REL)
+      if (isFile(ledger)) out.push({ root, ledger })
+    }
+  } catch { /* 读中断 → 已得子集（尽力而为） */ }
+  finally { try { handle.closeSync() } catch { /* 已关 */ } }
+  return out.sort((a, b) => (a.root < b.root ? -1 : a.root > b.root ? 1 : 0))
+}
+
+/** 项目族发现：{current, projects}——projects = current + 其同级含台账目录（**发现序：current 在前**，
+ *  其余按目录名升序）；current 缺（容器目录，K6）→ 上下文目录向上最近「含台账子目录」者取其子目录。 */
+export function discoverFamily(anchor) {
+  const current = findProject(anchor)
+  if (current) {
+    const siblings = ledgerChildren(dirname(current.root)).filter((p) => p.root !== current.root)
+    return { current, projects: [current, ...siblings] }
+  }
+  let dir = resolve(anchor)
+  for (;;) {
+    const kids = ledgerChildren(dir)
+    if (kids.length) return { current: null, projects: kids }
+    const parent = dirname(dir)
+    if (parent === dir) return { current: null, projects: [] }
+    dir = parent
+  }
+}
+
+/** 行龄 Map：全档一次 `git blame --porcelain` → Map<行号, 天>；非 git / 不可判定 → null（零假阳降级）。 */
+export function blameAges(abs) {
+  let out
+  try {
+    out = execFileSync("git", ["blame", "--porcelain", "--", abs], {
+      cwd: dirname(abs), encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 32 * 1024 * 1024,
+    })
+  } catch { return null }
+  const times = new Map(), ages = new Map()
+  const now = Date.now() / 1000
+  let sha = null, line = 0
+  for (const l of out.split("\n")) {
+    const h = /^([0-9a-f^]{7,40})\s+\d+\s+(\d+)(?:\s+\d+)?$/.exec(l)
+    if (h) { sha = h[1]; line = Number(h[2]); continue }
+    if (l.startsWith("author-time ")) { times.set(sha, Number(l.slice(12))); continue }
+    if (l.startsWith("\t")) {
+      const t = times.get(sha)
+      ages.set(line, t != null ? (now - t) / 86400 : null)
+    }
+  }
+  return ages
+}
+
+/** 单项目汇总 → {name,root,ledger,pool,tech,aged,agedKeys,agedTitles,thresholdReached,boards,actionable}。
+ *  `ageOf(abs)` → Map<行号,天>|null（注入面——确定性用例）；**无候选条目不调 ageOf**（N2）。 */
+export function summarizeLedger(project, { days = AGING_DAYS, ageOf = blameAges } = {}) {
+  const groups = scanGroups(readFileSync(project.ledger, "utf8").split("\n"))
+  const poolEntries = groups.filter((g) => g.name.includes("需求池")).flatMap((g) => g.entries)
+  const techEntries = groups.filter((g) => g.name.includes("技术")).flatMap((g) => g.entries)
+  const candidates = techEntries.filter((e) => !TRIGGER_RE.test(e.text))
+  const ages = candidates.length ? ageOf(project.ledger) : null
+  const aged = candidates.filter((e) => { const a = ages?.get(e.line); return a != null && a > days })
+  const boards = new Map()
+  for (const e of poolEntries) {
+    const m = BOARD_REF_RE.exec(e.text)
+    if (m) boards.set(m[1], (boards.get(m[1]) ?? 0) + 1)
+  }
+  const thresholdReached = poolEntries.length >= THRESHOLD_POOL || [...boards.values()].some((n) => n >= THRESHOLD_BOARD)
+  return {
+    name: basename(project.root), root: project.root, ledger: project.ledger,
+    pool: poolEntries.length, tech: techEntries.length, aged: aged.length,
+    agedKeys: aged.map((e) => normalizeEntry(e.text)), agedTitles: aged.map((e) => entryTitle(e.text)),
+    thresholdReached, boards, actionable: aged.length > 0 || thresholdReached,
+  }
+}
+
+/** L1 状态标记（逐字——§2.30.3.3）。 */
+export function formatMarker(scan) {
+  return scan ? `台账 ${scan.pool}·${scan.tech}` : null
+}
+
+/** L2 明细行（逐字——`（老化 <n>）` 恒显；阈值达成加 ` — 可开批`）。 */
+export function formatDetailLine(scan) {
+  return `台账 ${scan.name}：需求池 ${scan.pool} · 技术待办 ${scan.tech}（老化 ${scan.aged}）${scan.thresholdReached ? " — 可开批" : ""}`
+}
+
+/** L3 变化行·老化（titles = 新增老化条目标题；> 3 条时第三项后接 `；…`）。 */
+export function formatAgingLine(scan, titles) {
+  return `台账变化：${scan.name} 老化首次越线 ${titles.length} 条（超 30 天未处置）：${titles.slice(0, 3).join("；")}${titles.length > 3 ? "；…" : ""}`
+}
+
+/** L4 变化行·阈值。 */
+export function formatThresholdLine(scan) {
+  return `台账变化：${scan.name} 需求池达阈值（${scan.pool} 条）— 可开批`
+}
+
+/** 明细行集 = {current} ∪ {可动作项目}（发现序——current 在前，其余按目录名升序；同项去重）。 */
+export function detailScans(scans, current) {
+  const out = []
+  if (current) out.push(current)
+  for (const s of scans) if (s !== current && s.actionable) out.push(s)
+  return out
+}
+
+/** 变化行规划（纯函数）：{lines:[{text,warn}], next:{aged,threshold}}（去重口径 §2.30.3.2）。 */
+export function planChangeLines(prev, scan) {
+  const p = prev && typeof prev === "object" ? prev : {}
+  const before = new Set(Array.isArray(p.aged) ? p.aged : [])
+  const freshTitles = scan.agedKeys.map((k, i) => (before.has(k) ? null : scan.agedTitles[i])).filter((t) => t != null)
+  const lines = []
+  if (freshTitles.length) lines.push({ text: formatAgingLine(scan, freshTitles), warn: true })
+  if (scan.thresholdReached && !p.threshold) lines.push({ text: formatThresholdLine(scan), warn: true })
+  return { lines, next: { aged: scan.agedKeys, threshold: scan.thresholdReached } }
+}
+
+/** 去重档键 = 台账绝对路径·正斜杠 + **盘符大写**（跨端同规则——CLI 的 `process.cwd()` 盘符大写、
+ *  VSC 的 `uri.fsPath` 小写（`session-slots.mjs` `normalizeCwd` 同一契约——session / checkpoint /
+ *  trace 跨端共享即赖此）；CLI 写的键 VSC 须逐字认得）。 */
+export function notifyKey(ledger) {
+  return resolve(ledger).replace(/\\/g, "/").replace(/^([a-z]):/, (_, d) => `${d.toUpperCase()}:`)
+}
+
+/** 去重档读（缺失 / 坏 JSON → 空态——N1 降级不崩）。 */
+export function loadNotifyState(file = NOTIFY_FILE) {
+  try {
+    const j = JSON.parse(readFileSync(file, "utf8"))
+    if (j && typeof j === "object" && j.ledgers && typeof j.ledgers === "object") return { version: 1, ledgers: j.ledgers }
+  } catch { /* 缺失 / 坏档 → 空态 */ }
+  return { version: 1, ledgers: {} }
+}
+
+/** 去重档写（temp + rename 防撕裂；写失败静默返回 false——唯一写面，仅送达后调）。 */
+export function saveNotifyState(file, state) {
+  try {
+    mkdirSync(dirname(file), { recursive: true })
+    const tmp = `${file}.tmp-${process.pid}`
+    writeFileSync(tmp, JSON.stringify(state), "utf8")
+    renameSync(tmp, file)
+    return true
+  } catch { return false }
+}

package/src/memory/code-index.mjs

@@ -8,14 +8,20 @@ import { segmentCJK, CODE_EXTS, DOC_EXTS, SKIP_DIRS, BIG_FILE_LINES } from "./sc
 export function detectLanguage(filename) {
   const ext = filename.slice(filename.lastIndexOf(".")).toLowerCase()
   const map = {
-    ".mjs": "javascript", ".js": "javascript", ".jsx": "jsx", ".ts": "typescript", ".tsx": "tsx",
+    ".mjs": "javascript", ".js": "javascript", ".cjs": "javascript", ".jsx": "jsx",
+    ".ts": "typescript", ".tsx": "tsx", ".mts": "typescript", ".cts": "typescript",
     ".py": "python", ".rs": "rust", ".go": "go", ".java": "java",
     ".c": "c", ".h": "c", ".cpp": "cpp", ".hpp": "cpp",
-    ".rb": "ruby", ".swift": "swift", ".kt": "kotlin",
+    ".rb": "ruby", ".swift": "swift", ".kt": "kotlin", ".dart": "dart", ".lua": "lua",
+    ".cs": "csharp", ".fs": "fsharp", ".fsx": "fsharp",
+    ".clj": "clojure", ".cljs": "clojure", ".ex": "elixir", ".exs": "elixir",
+    ".erl": "erlang", ".hrl": "erlang", ".scala": "scala", ".groovy": "groovy",
+    ".pl": "perl", ".pm": "perl", ".r": "r", ".jl": "julia", ".zig": "zig",
+    ".ps1": "powershell", ".proto": "protobuf", ".graphql": "graphql", ".tf": "terraform", ".hcl": "hcl",
     ".sh": "bash", ".bash": "bash", ".sql": "sql",
     ".yaml": "yaml", ".yml": "yaml", ".toml": "toml", ".json": "json",
     ".css": "css", ".html": "html", ".vue": "vue", ".svelte": "svelte",
-    ".md": "markdown", ".mdc": "markdown",
+    ".md": "markdown", ".mdc": "markdown", ".mdx": "markdown", ".org": "org", ".wiki": "wiki", ".tex": "tex",
   }
   return map[ext] ?? ext.slice(1)
 }

package/src/memory/code-sync.mjs

@@ -4,13 +4,31 @@
 import { readFile, stat } from "node:fs/promises"
 import { join, relative } from "node:path"
 import { embed, cosine, toBlob, fromBlob } from "../embedding.mjs"
-import { CODE_EXTS, DOC_EXTS, SKIP_DIRS, MAX_CODE_FILE_BYTES, MAX_DOC_FILE_BYTES } from "./schema.mjs"
+import { scanVectors, createTopK } from "./scan.mjs"
+import { CODE_EXTS, DOC_EXTS, MAX_CODE_FILE_BYTES, MAX_DOC_FILE_BYTES } from "./schema.mjs"
 import { buildFtsQuery, ensureEmbeddings, EMBED_TEXT_MAX_LEN } from "./core.mjs"
 import { detectLanguage, _upsertCodeFile, _upsertDocFile, yieldTick } from "./code-index.mjs"
+import { walkProjectFiles, isSkippedRelPath, extensionOf, createUnlistedTally, MAX_WALK_FILES } from "./file-walk.mjs"
+import { loadConventions } from "../conventions.mjs"
+import { logEvent } from "../log.mjs"
 
 const DIFF_FULL_SYNC_THRESHOLD = 200
 const CODE_EMBED_BATCH = 64
 
+/**
+ * Index extension sets = built-in tables ∪ project declaration
+ * (`.thincoder/conventions.json` → index.codeExtensions / index.docExtensions;
+ * PORTABILITY PO-9/§3.7 — a project may declare extensions this product does not
+ * ship a default for). Declaration only ADDS (union), never removes.
+ */
+export function indexExtensions(dir) {
+  const conv = loadConventions(dir)
+  return {
+    code: new Set([...CODE_EXTS, ...conv.index.codeExtensions]),
+    doc: new Set([...DOC_EXTS, ...conv.index.docExtensions]),
+  }
+}
+
 /**
  * git-driven incremental indexing: use git diff to find files changed since
  * the last index, and only rebuild FTS5 chunks for those files (vectors are untouched).
@@ -19,6 +37,7 @@ const CODE_EMBED_BATCH = 64
  */
 export async function gitSync(memory, dir, { onProgress } = {}) {
   const { execFile: _execFile } = await import("node:child_process")
+  const { code: codeExts, doc: docExts } = indexExtensions(dir)
   const gitRun = (args) => new Promise((resolve, reject) => {
     _execFile("git", args, { cwd: dir, encoding: "utf8", timeout: 10000, windowsHide: true }, (err, stdout) => {
       if (err) reject(err); else resolve(stdout)
@@ -55,17 +74,16 @@ export async function gitSync(memory, dir, { onProgress } = {}) {
   for (let i = 0; i < diffOut.length; i++) {
     const rel = diffOut[i].replaceAll("\\", "/")
     const abs = join(dir, rel)
-    const ext = rel.slice(rel.lastIndexOf(".")).toLowerCase()
+    const ext = extensionOf(rel)
 
-    const pathDirs = rel.split("/")
-    if (pathDirs.some((d) => SKIP_DIRS.has(d) || d.startsWith("."))) continue
+    if (isSkippedRelPath(rel)) continue
 
-    if (!CODE_EXTS.has(ext) && !DOC_EXTS.has(ext)) { skipped++; continue }
+    if (!codeExts.has(ext) && !docExts.has(ext)) { skipped++; continue }
 
     try {
       const text = await readFile(abs, "utf8")
       const lines = text.split("\n")
-      if (CODE_EXTS.has(ext)) {
+      if (codeExts.has(ext)) {
         const lang = detectLanguage(abs)
         let mtimeMs = 0
         try { mtimeMs = Math.floor((await stat(abs)).mtimeMs) } catch { /* new file */ }
@@ -79,7 +97,7 @@ export async function gitSync(memory, dir, { onProgress } = {}) {
     } catch (e) {
       const isDeleted = e.code === "ENOENT"
       if (isDeleted) {
-        if (CODE_EXTS.has(ext)) memory.db.prepare(`DELETE FROM code_chunks WHERE origin = ? AND path = ?`).run(dir, rel)
+        if (codeExts.has(ext)) memory.db.prepare(`DELETE FROM code_chunks WHERE origin = ? AND path = ?`).run(dir, rel)
         else memory.db.prepare(`DELETE FROM doc_chunks WHERE origin = ? AND path = ?`).run(dir, rel)
         removed++
       } else {
@@ -104,16 +122,27 @@ export async function gitSync(memory, dir, { onProgress } = {}) {
 
 /**
  * List project files matching the given extensions.
- * Only indexes git repos — if dir isn't inside a git worktree, returns [].
- * Uses `git ls-files --cached --others --exclude-standard` to get the file list
- * (tracked + untracked-not-ignored, respecting .gitignore).
- * Returns an array of { abs, rel } pairs (abs = full path, rel = path relative to dir).
+ * Preferred source = git (`git ls-files --cached --others --exclude-standard`:
+ * tracked + untracked-not-ignored, .gitignore respected). Projects WITHOUT git
+ * fall back to a filesystem walk (PORTABILITY FR15/P8) — before, the index was
+ * silently empty there. The walk cannot honour .gitignore (no git → no such
+ * concept) and skips the shared SKIP_DIRS/dot-directory set instead.
+ * Returns { entries, unlisted }: `entries` = { abs, rel } pairs (rel relative to
+ * dir); `unlisted` = files whose extension is in NO index list (count + sample),
+ * the visible signal behind "my .xyz files are not searchable" (PORTABILITY PO-9).
+ * `truncated` = the non-git walk hit its file cap (capped trees are logged, never
+ * silently indexed-partial). opts.maxFiles = the walk cap (test seam).
  */
-export async function listProjectFiles(dir, exts) {
+export async function listProjectFiles(dir, exts, { maxFiles } = {}) {
   const { execFile: _execFile } = await import("node:child_process")
   const { join: joinPath } = await import("node:path")
+  const { code, doc } = indexExtensions(dir)
+  const tally = createUnlistedTally(new Set([...code, ...doc]))
 
-  // Only index git repos — if this isn't one, return empty
+  const files = []
+  const finish = (truncated = false) => ({ entries: files, unlisted: tally.result(), truncated })
+
+  // Git listing when available; a non-git project falls through to the walk.
   let gitTop
   try {
     gitTop = (await new Promise((resolve, reject) => {
@@ -121,10 +150,17 @@ export async function listProjectFiles(dir, exts) {
         (err, stdout) => { if (err) reject(err); else resolve(stdout.trim()) })
     })).replace(/\\/g, "/")
   } catch {
-    return [] // not a git repo → nothing to index
+    // Not a git repo → filesystem walk (FR15: the index must still be usable).
+    const walked = await walkProjectFiles(dir, exts, { knownExts: new Set([...code, ...doc]), ...(maxFiles !== undefined ? { maxFiles } : {}) })
+    files.push(...walked.files)
+    // The walk's cap must stay visible end-to-end (file-walk.mjs: "never silently
+    // dropped") — a capped listing says so in the log, not only in a discarded flag.
+    if (walked.truncated) {
+      logEvent("index:truncated", { dir, files: walked.files.length, maxFiles: maxFiles ?? MAX_WALK_FILES })
+    }
+    return { entries: files, unlisted: walked.unlisted, truncated: walked.truncated }
   }
 
-  const files = []
   try {
     const raw = await new Promise((resolve, reject) => {
       _execFile("git", ["ls-files", "--cached", "--others", "--exclude-standard"],
@@ -134,16 +170,15 @@ export async function listProjectFiles(dir, exts) {
     for (const line of raw.trim().split("\n")) {
       const p = line.trim()
       if (!p) continue
-      const ext = p.slice(p.lastIndexOf(".")).toLowerCase()
-      if (!exts.has(ext)) continue
-      const abs = joinPath(dir, p)
       const rel = p.replace(/\\/g, "/")
-      if (rel.split("/").some((seg) => SKIP_DIRS.has(seg) || seg.startsWith("."))) continue
-      files.push({ abs, rel })
+      if (isSkippedRelPath(rel)) continue
+      const ext = extensionOf(rel)
+      if (!ext || !exts.has(ext)) { tally.note(rel); continue }
+      files.push({ abs: joinPath(dir, rel), rel })
     }
   } catch { /* ls-files failed */ }
 
-  return files
+  return finish()
 }
 
 
@@ -152,7 +187,8 @@ export async function listProjectFiles(dir, exts) {
  * Incremental by mtime — only rebuilds chunks for files that have changed.
  */
 export async function codeSync(memory, dir, { onProgress } = {}) {
-  const entries = await listProjectFiles(dir, CODE_EXTS)
+  const { code: exts } = indexExtensions(dir)
+  const { entries, unlisted } = await listProjectFiles(dir, exts)
   const files = [] // { abs, rel, mtimeMs }
   let overSizeSkipped = 0
   for (const { abs, rel } of entries) {
@@ -206,7 +242,10 @@ export async function codeSync(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: "code", count: unlisted.count, exts: unlisted.exts.map((e) => e.ext) })
+  }
+  return { updated, removed, skipped, failed, errors, total: files.length, overSizeSkipped, unlistedExts: unlisted }
 }
 
 /** Record current HEAD as the index anchor (gitSync incremental diff baseline); silently skip non-git repos */
@@ -253,11 +292,12 @@ export async function codeSearch(memory, query, { limit = 5 } = {}) {
     console.error(`[code] query embedding failed, falling back to FTS-only: ${e.message}`)
     return ftsList.slice(0, limit)
   }
-  const rows = memory.db.prepare(`SELECT rowid, embedding FROM code_chunks WHERE embedding IS NOT NULL ${vecOriginFilter}`).all(...originParams)
-  const vecList = rows
-    .map((r) => ({ rowid: r.rowid, score: cosine(qvec, fromBlob(r.embedding)) }))
-    .sort((a, b) => b.score - a.score)
-    .slice(0, Math.max(limit * 4, 20))
+  // TUI-OOM-ROOTCAUSE（MEMORY.md §10.3）：分块扫描 + 有界 top-K（原全表 .all()——峰值 = 块 + K）
+  const top = createTopK(Math.max(limit * 4, 20))
+  scanVectors(memory.db, `SELECT rowid, embedding FROM code_chunks WHERE embedding IS NOT NULL ${vecOriginFilter}`, originParams, {
+    onRow: (r) => top.push({ id: r.rowid, rowid: r.rowid, score: cosine(qvec, fromBlob(r.embedding)) }),
+  })
+  const vecList = top.list().map((c) => ({ rowid: c.id, score: c.score }))
 
   const K = 60
   const scores = new Map()
@@ -338,32 +378,33 @@ export function codeSearchTool(memory) {
  * Single-file incremental reindex: called after write/edit/delete, only rebuilds this one path.
  */
 export async function reindexFile(memory, cwd, absPath) {
-  const ext = absPath.slice(absPath.lastIndexOf(".")).toLowerCase()
+  const ext = extensionOf(absPath)
   const rel = relative(cwd, absPath).replaceAll("\\", "/")
   if (rel === ".." || rel.startsWith("../")) return
-  const dirs = rel.split("/").slice(0, -1)
-  if (dirs.some((d) => SKIP_DIRS.has(d) || d.startsWith("."))) return
+  if (isSkippedRelPath(rel)) return
+  // Declared extensions count for the single-file path too (union with built-ins).
+  const { code: codeExts, doc: docExts } = indexExtensions(cwd)
 
   // skip oversized files (minified bundles, test fixtures, generated code)
-  const maxBytes = CODE_EXTS.has(ext) ? MAX_CODE_FILE_BYTES : DOC_EXTS.has(ext) ? MAX_DOC_FILE_BYTES : 0
+  const maxBytes = codeExts.has(ext) ? MAX_CODE_FILE_BYTES : docExts.has(ext) ? MAX_DOC_FILE_BYTES : 0
   if (maxBytes > 0) {
     try { const st = await stat(absPath); if (st.size > maxBytes) return } catch { /* can't stat, proceed */ }
   }
 
   let text
   try { text = await readFile(absPath, "utf8") } catch {
-    if (CODE_EXTS.has(ext)) memory.db.prepare(`DELETE FROM code_chunks WHERE origin = ? AND path = ?`).run(cwd, rel)
-    else if (DOC_EXTS.has(ext)) memory.db.prepare(`DELETE FROM doc_chunks WHERE origin = ? AND path = ?`).run(cwd, rel)
+    if (codeExts.has(ext)) memory.db.prepare(`DELETE FROM code_chunks WHERE origin = ? AND path = ?`).run(cwd, rel)
+    else if (docExts.has(ext)) memory.db.prepare(`DELETE FROM doc_chunks WHERE origin = ? AND path = ?`).run(cwd, rel)
     return
   }
   const lines = text.split("\n")
 
-  if (CODE_EXTS.has(ext)) {
+  if (codeExts.has(ext)) {
     const lang = detectLanguage(absPath)
     let mtimeMs = 0
     try { mtimeMs = Math.floor((await stat(absPath)).mtimeMs) } catch { /* new file */ }
     _upsertCodeFile(memory, cwd, rel, lines, lang, mtimeMs)
-  } else if (DOC_EXTS.has(ext)) {
+  } else if (docExts.has(ext)) {
     let mtimeMs = 0
     try { mtimeMs = Math.floor((await stat(absPath)).mtimeMs) } catch { /* new file */ }
     _upsertDocFile(memory, cwd, rel, lines, mtimeMs)