thincoder 0.12.60 → 0.12.61

package/src/config.mjs

@@ -1,6 +1,12 @@
 /**
  * config.mjs — configuration loading and saving
- * Multi-provider structure: providers[] + activeProvider
+ * Model-merge schema v2 (2026-09-10 MODEL-SELECTION): providers[] carry ONE default model
+ * per channel (`providers[].model` — the new-install seed / empty-slot fallback); the
+ * candidates list field models[] is gone — the available-model list is fetched from the
+ * provider at runtime (`GET /models`, PROVIDER.md §16). config.defaultModel (top level,
+ * "provider:model" composite) is the new-session starting point; activeProvider/activeModel
+ * are gone from config (session slots keep their own double fields). Legacy fields migrate
+ * on load (write-back failure never blocks startup).
  * Config file: ~/.thincoder/config.json
  * API key can fall back to environment variables (when not configured in providers).
  */
@@ -8,13 +14,27 @@
 import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
 import { homedir } from "node:os"
 import { dirname, join } from "node:path"
+import { parseModelRef, resolveRuntimeProvider, defaultModelReason } from "./model-ref.mjs"
+// 老形态迁移核（M7 v2——纯函数零依赖——本文件超 500 行硬限拆分，VSC 同构文件）
+import { migrateLegacyModelFields } from "./config-migrate.mjs"
+import { expandHome } from "./expand-home.mjs"
+
+export { parseModelRef, resolveRuntimeProvider, defaultModelReason, migrateLegacyModelFields }
 
 export const configDir = join(homedir(), ".thincoder")
 export const configPath = join(configDir, "config.json")
 
-/** Built-in provider presets: shared by /provider add <preset> and first-run wizard */
+/** Test seam: override the config file location (mirrors thincoder-vscode config-io.mjs). */
+let _pathOverride = null
+export function _setConfigPathForTest(p) { _pathOverride = p }
+export function _resetConfigPathForTest() { _pathOverride = null }
+function cfgPath() { return _pathOverride ?? configPath }
+
+/** Built-in provider presets: shared by /provider add <preset> and first-run wizard.
+ *  MODEL-SELECTION v2 (2026-09-10): each preset carries exactly ONE default model
+ *  (`model` — 新装启动种子/槽位空兜底; 候选清单不再预置——运行期从 provider 拉取). */
 export const PROVIDER_PRESETS = {
-  deepseek: { baseURL: "https://api.deepseek.com", model: "deepseek-v4-pro", thinking: { type: "enabled" }, reasoningEffort: "max", maxTokens: 393216, desc: "DeepSeek" },
+  deepseek: { baseURL: "https://api.deepseek.com", model: "deepseek-flash", thinking: { type: "enabled" }, reasoningEffort: "max", maxTokens: 393216, desc: "DeepSeek" },
   kimi:     { baseURL: "https://api.moonshot.cn/v1", model: "kimi-k3", thinking: null, reasoningEffort: "max", maxTokens: 131072, desc: "Kimi / Moonshot" },
   "kimi-code": { baseURL: "https://api.kimi.com/coding/v1", model: "k3", thinking: null, reasoningEffort: "max", maxTokens: 131072, desc: "Kimi For Coding (platform.kimi.com — sk-kimi- keys; NOT interchangeable with Moonshot)" },
   glm:      { baseURL: "https://open.bigmodel.cn/api/paas/v4", model: "glm-5.2", thinking: { type: "enabled" }, reasoningEffort: "max", maxTokens: 128000, desc: "Zhipu GLM" },
@@ -37,7 +57,7 @@ export const PROVIDER_PRESETS = {
 }
 
 export const DEFAULTS = {
-  activeModel: null,  // optional: override provider.model (set via /model picker or /model provider:model)
+  defaultModel: null, // top-level "provider:model" composite — new-session starting point (F-1)
   agent: {
     maxTurns: 200,
     subagentTurns: 100,
@@ -54,15 +74,19 @@ export const DEFAULTS = {
     streamRules: [],      // time-traveling stream rules: [{ pattern: "regex", message: "reminder", action: "abort"|"warn", repeat: "always"|"once" }]
     advisor: { guard: false },  // code review is always available; guard: true pushes completion back until reviewed (opt-in). Also accepts provider/model/thinking/reasoningEffort/timeoutMs overrides. Deprecated: enabled (2026-08-21)
     autoThink: false,     // auto-classify task difficulty and set reasoning effort per-turn
-    engineering: false,   // strict methodology enforcement — read METHODOLOGY.md, design-before-code
-    // Async subagent pool limits per role domain (AGENT-LOOP.md §24 D-24a/R14):
-    // { engCoder, other } — eng-coder pool / other-role pool, defaults 4/4 (user
-    // ruling "eng-coder 四路，其他 4 路"). Runtime-validated at every pool admission
-    // (positive integer ≥1, invalid/absent keys fall back to 4 — settings tool and
-    // the /config 并发池 menu write this key; change applies to the next spawn).
-    // ⚠ 与 subagent-async.mjs ASYNC_POOL_LIMITS 逐键同值（运行时回退常量）——耦合锚
-    // T-24a4 断言锁住——勿单侧改默认。
-    poolLimits: { engCoder: 4, other: 4 },
+    engineering: false,   // strict methodology enforcement — design-before-code (design review + user approval before code)
+    // Async pool limits (AGENT-LOOP.md §11.1 D-24a/R14 + §11.2 R13 — POOL-CONFIG-
+    // UNIFIED 2026-09-09): { engCoder, other, advisor } — eng-coder pool / other-role
+    // pool / advisor-review pool, defaults 4/4/4 (user ruling "eng-coder 四路，其他
+    // 4 路" + advisor 评审池并入同一可配体系——三池统一默认 4)。engCoder/other
+    // runtime-validated at every subagent pool admission (subagent-async
+    // resolvePoolLimits); advisor runtime-validated at every advisor launch
+    // (advisor-async advisorPoolLimitFor——F-2——两域读取器独立不共享)——非法/缺省
+    // 回退 4——settings tool 与 /config 并发池菜单写此键——变更下个 spawn/launch 生效。
+    // ⚠ 与 subagent-async.mjs ASYNC_POOL_LIMITS（两键）/advisor-async.mjs
+    // ADVISOR_POOL_LIMIT 逐键同值（运行时回退常量）——耦合锚 T-24a4 断言锁住——
+    // 勿单侧改默认。
+    poolLimits: { engCoder: 4, other: 4, advisor: 4 },
   },
   memory: {
     dbPath: join(configDir, "memory.db"),
@@ -78,7 +102,7 @@ export const DEFAULTS = {
     servers: [],
   },
   websearch: {
-    provider: "tavily",  // structured search API; empty apiKey → fall back to Bing HTML scraping
+    // Structured search via Tavily when a key is set — empty apiKey → Bing RSS/HTML fallback (zero-config).
     apiKey: "",          // Tavily key (tvly-...) — optional
   },
   traces: {
@@ -90,8 +114,8 @@ export const DEFAULTS = {
 // Model capability table + spec lookup live in model-specs.mjs (2026-08-31
 // extract — config.mjs had grown past the 300-line advisory). Re-exported here
 // so the 23 existing importers keep their import paths.
-import { specForModel, providerSpec } from "./model-specs.mjs"
-export { specForModel, providerSpec }
+import { specForModel, providerSpec, specMatch } from "./model-specs.mjs"
+export { specForModel, providerSpec, specMatch }
 
 
 // Window utilization threshold: compacts at 60% context, reserving 40% headroom
@@ -144,6 +168,44 @@ export function resolveEnableThinking(provider, spec) {
 /** Module-level one-time warn dedupe for invalid providers[].context (PROVIDER.md §15 D-C1). */
 const warnedContextProviders = new Set()
 
+/** F-4 (IKCDMR) 软失败清洗（D-S1 范式——loadConfig 是 CLI 启动砖点）：consultModels 非法
+ *  条目过滤不 throw——非数组 → []、形状非法/未知渠道丢弃、超 5 截断（keep 前 5）。
+ *  返回 { keep, dropped }——dropped 供一次性警告；merged.agent.consultModelsFiltered 挂载
+ *  供后续首帧引导消费（数据层——本批文件面无消费方——同 providerInvalidReason 载体先例）。 */
+function sanitizeConsultModels(cm, providerNames) {
+  if (cm === undefined || cm === null) return { keep: [], dropped: [] }
+  if (!Array.isArray(cm)) {
+    return { keep: [], dropped: [`agent.consultModels must be an array of { provider, model } entries (got ${typeof cm})`] }
+  }
+  const names = new Set(providerNames)
+  const keep = []
+  const dropped = []
+  for (const entry of cm) {
+    if (keep.length >= 5) { dropped.push(`over the 5-entry cap — dropped ${JSON.stringify(entry)}`); continue }
+    if (!entry || typeof entry !== "object" || typeof entry.provider !== "string" || !entry.provider.trim()
+        || typeof entry.model !== "string" || !entry.model.trim()) {
+      dropped.push(`invalid entry (expected { provider: string, model: string }) — got ${JSON.stringify(entry)}`)
+      continue
+    }
+    if (!names.has(entry.provider)) {
+      dropped.push(`entry "${entry.provider}:${entry.model}" references unknown provider "${entry.provider}" (available: ${[...names].join(", ") || "none"})`)
+      continue
+    }
+    keep.push(entry)
+  }
+  return { keep, dropped }
+}
+
+/** F-4：过滤警告——进程级一次性（loadConfig 同进程可多次调用：TUI 启动 + reloadConfig）。 */
+let warnedConsultModels = false
+function warnConsultModelsFiltered(dropped, path) {
+  if (warnedConsultModels || dropped.length === 0) return
+  warnedConsultModels = true
+  console.warn(`[config] agent.consultModels: ${dropped.length} invalid entr${dropped.length === 1 ? "y ignored" : "ies ignored"} (filtered — startup continues; no crash):\n` +
+    dropped.map((d) => `  - ${d}`).join("\n") +
+    `\n  Fix: clean agent.consultModels in ${path} or use /config → consult/escalate pool menu.`)
+}
+
 /**
  * Find provider by name in providers[].
  * Throws if name is non-empty but not found — a typo in activeProvider silently falling to the first provider would use the wrong key on the wrong endpoint.
@@ -187,29 +249,58 @@ function sanitizeProviderHeaders(p) {
   return p
 }
 
+/** loadConfig 内联迁移核已迁 config-migrate.mjs（500 行硬限拆分——VSC 同构）——
+ *  migrateLegacyModelFields 纯函数 + 本文件 import/写回编排（折中 C 见其头注释）。 */
 export function loadConfig() {
   let config = {}
-  if (existsSync(configPath)) {
+  const path = cfgPath()
+  if (existsSync(path)) {
     try {
-      config = JSON.parse(readFileSync(configPath, "utf8"))
+      config = JSON.parse(readFileSync(path, "utf8"))
     } catch (error) {
-      throw new Error(`Config file is not valid JSON, check or delete it: ${configPath}\n  ${error.message}`, { cause: error })
+      throw new Error(`Config file is not valid JSON, check or delete it: ${path}\n  ${error.message}`, { cause: error })
+    }
+  }
+
+  // ── 迁移（M7 v2）：检测老字段（models[] / active* / 垃圾值）→ 内存迁移态先行；写回失败绝不阻断（下次 load 重试——幂等）──
+  if (migrateLegacyModelFields(config)) {
+    try {
+      const r = writeConfigAtomic(path, migrateLegacyModelFields) // 磁盘 fresh raw 同变换
+      if (r.ok === false) console.warn(`[config] migration write-back skipped (${r.reason}) — memory state continues, retried on next load`)
+    } catch (e) {
+      console.warn(`[config] migration write-back failed — memory state continues, retried on next load: ${e.message}`)
     }
   }
 
   const merged = {
     ...DEFAULTS,
     ...config,
+    defaultModel: typeof config.defaultModel === "string" && config.defaultModel.trim() ? config.defaultModel : null,
     providers: Array.isArray(config.providers)
       ? config.providers.map((p) => sanitizeProviderHeaders({ ...p }))
       : [],
-    activeProvider: config.activeProvider ?? "",
     agent: { ...DEFAULTS.agent, ...config.agent },
     memory: { ...DEFAULTS.memory, ...config.memory },
     embedding: { ...DEFAULTS.embedding, ...config.embedding },
     traces: { ...DEFAULTS.traces, ...config.traces },
   }
 
+  // 家目录展开（第 29 批）：config 路径字段单一规范化点——只读归一（磁盘原文保留）
+  merged.memory.dbPath = expandHome(merged.memory.dbPath)
+  merged.memory.projectDir = expandHome(merged.memory.projectDir)
+  const team = merged.memory.team
+  if (team && typeof team === "object" && !Array.isArray(team) && team.dir !== undefined) {
+    merged.memory.team = { ...team, dir: expandHome(team.dir) }   // 无 dir 键不注入（零键面变化）
+  }
+  merged.shell = expandHome(merged.shell)
+
+  // providers[].model 内存归一（v2 M3：非空字符串保留；非字符串/空串归一删除）——渠道默认模型
+  // 单值；无默认模型合法（模型选择经 /models 拉取候选——准入判据见 M8/M9）。
+  for (const p of merged.providers) {
+    if (typeof p.model === "string" && p.model.trim()) continue
+    if (p.model !== undefined) delete p.model
+  }
+
   // providers[].context (K units, PROVIDER.md §15 D-C1): positive integer only — invalid
   // values (0/negative/non-numeric) are IGNORED (spec value applies) with a ONE-TIME warn
   // per provider name (module-level dedupe, same precedent as warnedModels in model-specs.mjs).
@@ -223,27 +314,15 @@ export function loadConfig() {
     delete p.context
   }
 
-  // Consult/escalate pool validation (CLI parity with the plugin): up to 5 candidates.
-  const cm = merged.agent.consultModels
-  if (cm !== undefined && !Array.isArray(cm)) {
-    throw new Error(`agent.consultModels must be an array of { provider, model } entries (got ${typeof cm})`)
-  }
-  if (Array.isArray(cm) && cm.length > 5) {
-    throw new Error(`agent.consultModels supports at most 5 models (got ${cm.length})`)
-  }
-  if (Array.isArray(cm)) {
-    // Fail fast at load: a pool entry whose provider doesn't exist in providers[] fails
-    // every consult/escalate call at runtime with a quiet error string (eats a turn).
-    const providerNames = merged.providers.map((p) => p.name)
-    for (const entry of cm) {
-      if (!entry || typeof entry !== "object" || typeof entry.provider !== "string" || typeof entry.model !== "string") {
-        throw new Error(`agent.consultModels entries must be { provider: string, model: string } objects (got ${JSON.stringify(entry)})`)
-      }
-      if (!providerNames.includes(entry.provider)) {
-        throw new Error(`agent.consultModels entry "${entry.provider}:${entry.model}" references unknown provider "${entry.provider}" (available: ${providerNames.join(", ") || "none"})`)
-      }
-    }
-  }
+  // F-4 (IKCDMR) consultModels 软失败化——D-S1 范式（defaultModel 无效同族）：非法条目
+  // 过滤不 throw（去 startup brick——无修复入口的硬崩消）；一次性启动警告内嵌修复指引
+  // （引导清条目载体——保留 discoverability）；过滤记录挂 merged.agent.consultModelsFiltered
+  // （数据层——consumer-ready——首帧 UI 消费点同 D-S1 promptProviderIfInvalid 属后续批）。
+  // VSC loadAgentSettings 同规则（共享 config——双端锁步）。
+  const cmClean = sanitizeConsultModels(merged.agent.consultModels, merged.providers.map((p) => p.name))
+  warnConsultModelsFiltered(cmClean.dropped, path)
+  merged.agent.consultModels = cmClean.keep
+  if (cmClean.dropped.length) merged.agent.consultModelsFiltered = cmClean.dropped
 
   // Backward compatibility: promote root-level config fields to agent sub-object
   if (config.verifyGuard !== undefined) {
@@ -259,35 +338,24 @@ export function loadConfig() {
   // 保证 agent.config.proxy 永远是规范形态或 undefined
   merged.proxy = normalizeProxy(merged.proxy)
 
-  // Get the currently active provider
-  // 2026-09-02 Q1（SESSION.md §8）：activeProvider 指向不存在的 provider 不再抛错——runtimeProvider
-  // 置空对象，由 make-agent.mjs assembleAgent 后的校验打 `_providerInvalid` 标记 → TUI 引导重选 /
-  // headless 报可读错误（原 findProvider throw 直接击穿 loadConfig → uncaughtException 退出）。
-  // findProvider 的 throw 契约保留（advisor/run.mjs 等直接调用方仍依赖）。
-  let active
-  try {
-    active = findProvider(merged.providers, merged.activeProvider)
-  } catch {
-    active = {}
-  }
-
-  // Build runtime provider object (for agent.provider usage)
-  const runtimeProvider = { ...active }
-
-  // activeModel overrides provider's default model (config only)
-  if (merged.activeModel) runtimeProvider.model = merged.activeModel
-  merged.activeModel = merged.activeModel || null  // normalize for agent.activeModel
+  // Runtime provider = config.defaultModel 复合解析（F-2——resolveRuntimeProvider）。
+  // 无效/未设 → {} + providerInvalidReason（D-S1 处置不 throw——make-agent 打 _providerInvalid
+  // 标记 → TUI 首帧弹选择 / headless 报可读错误；同 2026-09-02 Q1 语义——不复用 findProvider
+  // throw 契约——findProvider 保留给 advisor/run.mjs 等直接调用方）。
+  merged.provider = resolveRuntimeProvider(merged.providers, merged.defaultModel)
+  merged.providerInvalidReason = merged.provider.name
+    ? null
+    : defaultModelReason(merged.providers, merged.defaultModel)
 
   // Compaction threshold follows the model (provider-level context override honored — providerSpec)
   const explicitThreshold = config.agent?.compactThreshold
-  const { value, auto } = resolveCompactThreshold(explicitThreshold, runtimeProvider)
+  const { value, auto } = resolveCompactThreshold(explicitThreshold, merged.provider)
   merged.agent.compactThreshold = value
   merged.agent.compactThresholdAuto = auto
 
   // Write back to merged for convenient access by upper layers
-  merged.provider = runtimeProvider
   // fetch 超时可配置（2026-09-01：agent.fetchTimeoutMs——provider/core.mjs effectiveFetchTimeoutMs 消费）
-  runtimeProvider.fetchTimeoutMs = Number.isFinite(merged.agent?.fetchTimeoutMs) && merged.agent.fetchTimeoutMs > 0
+  merged.provider.fetchTimeoutMs = Number.isFinite(merged.agent?.fetchTimeoutMs) && merged.agent.fetchTimeoutMs > 0
     ? merged.agent.fetchTimeoutMs : undefined
   merged.providersList = merged.providers
   merged.advisor = { ...merged.agent.advisor }  // promote for consistent access (decoupled copy)
@@ -344,7 +412,8 @@ function readMcpSection(path = configPath) {
     if (!existsSync(path)) return { ok: true, servers: [] }
     const raw = JSON.parse(readFileSync(path, "utf8"))
     const servers = raw?.mcp?.servers
-    if (servers !== undefined && !Array.isArray(servers)) return { ok: true, servers: [] }
+    // 非数组 = 畸形磁盘配置（2.3 代码正确性批）——ok:false 走调用方既有畸形回退（reloadMcpFromDisk 早退）
+    if (servers !== undefined && !Array.isArray(servers)) return { ok: false, error: "mcp.servers must be an array" }
     return { ok: true, servers: Array.isArray(servers) ? servers : [] }
   } catch (error) {
     return { ok: false, error: error?.message ?? String(error) }

package/src/conventions.mjs

@@ -0,0 +1,223 @@
+/**
+ * conventions.mjs — the single authority for code / doc / temp path classification,
+ * plus the project convention declaration surface (`.thincoder/conventions.json`).
+ *
+ * Why one module: engineering-mode gates and guards (design gate, review-doc gate,
+ * mutation accounting, verify fast path) each carried their own copy of the
+ * "what counts as product code" predicate — anchored `^src/` regexes, `docs/`
+ * prefix checks, component regexes. Each copy drifted, and each hardcoded THIS
+ * repository's layout: a project whose code lives outside `src/` slipped through
+ * the design gate silently (PORTABILITY FR12 / PO-10). One classifier + one
+ * declaration file = one truth.
+ *
+ * Defaults are DATA (`DEFAULT_CODE_PATHS`) — overridable per project through the
+ * declaration file (§4.1 schema). Missing file → pure defaults (no noise);
+ * corrupt/unreadable file → defaults + console.warn + a log event (never crash,
+ * never swallow — PORTABILITY FR10).
+ *
+ * Classification vocabulary (PORTABILITY design §3.1):
+ *   code — inside a declared code segment (default: the path segment `src`), or
+ *          not a documentation extension;  doc — documentation extension outside
+ *          any code segment;  temp — tmp-* name or .tmp/.temp extension.
+ */
+import { readFileSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { logEvent } from "./log.mjs"
+
+/** Default code-path segments (data, not logic — a project may replace them). */
+export const DEFAULT_CODE_PATHS = ["src"]
+
+/** Project declaration file, relative to the project root. */
+export const CONVENTIONS_REL_PATH = ".thincoder/conventions.json"
+
+/** Documentation predicate (moved here verbatim from advisor/repos.mjs — one copy). */
+const DOC_FILE = /(?:^|[/\\])(?:LICENSE|NOTICE|CHANGELOG|AUTHORS)(?:\.\w+)?$|\.(?:md|markdown|mdx|txt|rst|adoc)$/i
+
+/** Temp/scratch predicate (moved here verbatim from advisor/repos.mjs). */
+const TEMP_FILE = /(?:^|[/\\])tmp-[^/\\]+$|\.(?:tmp|temp)$/i
+
+/** True when a path is a throwaway temp file (tmp-* name or .tmp/.temp extension). */
+export function isTempPath(p) {
+  return TEMP_FILE.test(p ?? "")
+}
+
+/** Path → segments (both separators accepted; absolute and relative alike). */
+function segmentsOf(p) {
+  return String(p ?? "").replace(/\\/g, "/").split("/").filter(Boolean)
+}
+
+/**
+ * True when the path contains a declared code segment sequence at any depth.
+ * Segment matching (not a prefix anchor) is what closes the nested-layout hole:
+ * `packages/foo/src/x.md` is product code, not a document. Comparison is
+ * case-insensitive — on case-insensitive filesystems `Src/x.mjs` is the same
+ * directory, and the gate must not be bypassable by casing.
+ */
+function hasCodeSegment(p, conv) {
+  const parts = segmentsOf(p).map((s) => s.toLowerCase())
+  const wanted = conv?.codePaths ?? DEFAULT_CODE_PATHS
+  for (const entry of wanted) {
+    const want = segmentsOf(entry).map((s) => s.toLowerCase())
+    if (want.length === 0) continue
+    for (let i = 0; i + want.length <= parts.length; i++) {
+      if (want.every((seg, j) => parts[i + j] === seg)) return true
+    }
+  }
+  return false
+}
+
+/** "code" | "doc" | "temp" — the single classification decision.
+ *  Precedence: code segment first (src/** stays product code even when the name
+ *  looks scratch — the pre-existing unconditional-src rule), then temp, then a
+ *  documentation extension, else code (anything not doc/temp is product code). */
+export function classifyPath(p, conv) {
+  const s = String(p ?? "")
+  if (hasCodeSegment(s, conv)) return "code"
+  if (TEMP_FILE.test(s)) return "temp"
+  if (DOC_FILE.test(s)) return "doc"
+  return "code"
+}
+
+/** True when the path is product code (see classifyPath for the precedence). */
+export function isCodePath(p, conv) {
+  return classifyPath(p, conv) === "code"
+}
+
+/** True when the path is a documentation file — a doc extension that does NOT
+ *  live inside a declared code segment (src/prompts/*.md is product code). */
+export function isDocPath(p, conv) {
+  const s = String(p ?? "")
+  return DOC_FILE.test(s) && !hasCodeSegment(s, conv)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Declaration loading (cached per project root — `clearConventionsCache()` is
+// the test seam; declaration files change rarely and only at session scope).
+// ─────────────────────────────────────────────────────────────────────────────
+
+function normalizeExtensions(v) {
+  if (!Array.isArray(v)) return []
+  const out = []
+  for (const e of v) {
+    if (typeof e !== "string") continue
+    const t = e.trim().toLowerCase()
+    if (!t) continue
+    const ext = t.startsWith(".") ? t : `.${t}`
+    if (!out.includes(ext)) out.push(ext)
+  }
+  return out
+}
+
+/** Declared code paths replace the default (replacement, not union — §4.1). */
+function normalizeCodePaths(v) {
+  if (!Array.isArray(v)) return null
+  const out = []
+  for (const e of v) {
+    if (typeof e !== "string") continue
+    const s = e.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "")
+    if (!s || out.includes(s)) continue
+    out.push(s)
+  }
+  return out.length > 0 ? out : null
+}
+
+function normalizeString(v) {
+  return typeof v === "string" && v.trim() ? v.trim() : ""
+}
+
+/** Per-key type check for recognized keys (present but wrong type). §3.2/§4.1: a
+ *  type error degrades WITH a warning — never silently (the fallback semantics stay
+ *  per-key; only the visibility is added here). */
+function typeErrorsOf(raw) {
+  const isObj = (v) => v !== undefined && v !== null && typeof v === "object" && !Array.isArray(v)
+  const strArray = (v) => Array.isArray(v) && v.every((x) => typeof x === "string")
+  const errs = []
+  if (raw.codePaths !== undefined && !strArray(raw.codePaths)) errs.push("codePaths must be an array of strings")
+  const idx = raw.index
+  if (idx !== undefined && !isObj(idx)) errs.push("index must be an object")
+  else if (isObj(idx)) {
+    for (const k of ["codeExtensions", "docExtensions"]) {
+      if (idx[k] !== undefined && !strArray(idx[k])) errs.push(`index.${k} must be an array of strings`)
+    }
+  }
+  const adv = raw.advisor
+  if (adv !== undefined && !isObj(adv)) errs.push("advisor must be an object")
+  else if (isObj(adv)) {
+    for (const k of ["docMap", "standardsDoc"]) {
+      if (adv[k] !== undefined && typeof adv[k] !== "string") errs.push(`advisor.${k} must be a string`)
+    }
+  }
+  return errs
+}
+
+function buildConventions(raw) {
+  const codePaths = normalizeCodePaths(raw?.codePaths)
+  const codeExtensions = normalizeExtensions(raw?.index?.codeExtensions)
+  const docExtensions = normalizeExtensions(raw?.index?.docExtensions)
+  const docMap = normalizeString(raw?.advisor?.docMap)
+  const standardsDoc = normalizeString(raw?.advisor?.standardsDoc)
+  // `declared` = the declaration actually took effect (at least one recognized key
+  // honored) — the design-gate hint reads it to decide whether to point at the
+  // declaration file ("declare project conventions … to adjust").
+  const declared = Boolean(codePaths || codeExtensions.length || docExtensions.length || docMap || standardsDoc)
+  return Object.freeze({
+    declared,
+    codePaths: Object.freeze(codePaths ?? [...DEFAULT_CODE_PATHS]),
+    index: Object.freeze({
+      codeExtensions: Object.freeze(codeExtensions),
+      docExtensions: Object.freeze(docExtensions),
+    }),
+    advisor: Object.freeze({ docMap, standardsDoc }),
+  })
+}
+
+/** Full-default conventions (no declaration) — the fallback every consumer gets. */
+export const DEFAULT_CONVENTIONS = buildConventions(null)
+
+const _cache = new Map()
+
+/** Drop the per-root cache (test seam — declaration files are read once per root). */
+export function clearConventionsCache() {
+  _cache.clear()
+}
+
+/**
+ * Load (and cache) the normalized conventions for a project root.
+ * @param {string} cwd — project root (declaration lives at .thincoder/conventions.json)
+ * @returns {Readonly<{declared: boolean, codePaths: readonly string[],
+ *   index: {codeExtensions: string[], docExtensions: string[]},
+ *   advisor: {docMap: string, standardsDoc: string}}>}
+ */
+export function loadConventions(cwd) {
+  const root = resolve(cwd ?? process.cwd())
+  const hit = _cache.get(root)
+  if (hit) return hit
+  let conv = DEFAULT_CONVENTIONS
+  try {
+    const text = readFileSync(join(root, CONVENTIONS_REL_PATH), "utf8")
+    try {
+      const raw = JSON.parse(text)
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("top level must be a JSON object")
+      conv = buildConventions(raw)
+      const typeErrs = typeErrorsOf(raw)
+      if (typeErrs.length > 0) {
+        // Wrong-typed keys fall back per-key — but the user must SEE that their
+        // declaration did not take effect (never silently swallowed).
+        console.warn(`[conventions] ${CONVENTIONS_REL_PATH} has invalid value types (${typeErrs.join("; ")}) — those keys fall back to defaults`)
+        logEvent("conventions:error", { cwd: root, err: `type errors: ${typeErrs.join("; ").slice(0, 160)}` })
+      }
+    } catch (e) {
+      // Corrupt file / wrong shape → defaults, visible: warn + event (never silent).
+      console.warn(`[conventions] ${CONVENTIONS_REL_PATH} unreadable (${e?.message ?? e}) — falling back to defaults`)
+      logEvent("conventions:error", { cwd: root, err: String(e?.message ?? e).slice(0, 200) })
+    }
+  } catch (e) {
+    if (e?.code !== "ENOENT") {
+      // File exists but cannot be read (EACCES etc.) — same visible degradation.
+      console.warn(`[conventions] ${CONVENTIONS_REL_PATH} not readable (${e?.message ?? e}) — falling back to defaults`)
+      logEvent("conventions:error", { cwd: root, err: String(e?.message ?? e).slice(0, 200) })
+    }
+  }
+  _cache.set(root, conv)
+  return conv
+}

package/src/crash-reports.mjs

@@ -31,10 +31,15 @@ export function crashReportsDir() {
 }
 
 /** 记录文件模式（评审 #8 定死）：crash-*.json = 自写（F-R25a）；report.*.json = Node
- *  fatal（默认命名 report.YYYYMMDD.HHMMSS.<pid>.<seq>.json——2026-09-07 实现批实测）。 */
+ *  fatal（默认命名 report.YYYYMMDD.HHMMSS.<pid>.<seq>.json——2026-09-07 实现批实测）。
+ *  purge 另含 tui-stderr-*.log（TUI-STDERR-CAPTURE F-2——30 天同族淘汰）——但 recentCrashHint
+ *  不计该类：tui-stderr 每次 TUI 启动都生成（正常退出也留档）——计入即正常会话误报"异常终止"。 */
 function isCrashRecordName(name) {
   return /^crash-.+\.json$/.test(name) || /^report\..+\.json$/.test(name)
 }
+function isPurgeRecordName(name) {
+  return isCrashRecordName(name) || /^tui-stderr-.+\.log$/.test(name)
+}
 
 /** >30 天淘汰（评审 #6）——写时自清理；搭车点 = 写 / 入口 mkdir / 启动扫描（复审 #4）。 */
 function purgeOldCrashReports(dir) {
@@ -42,7 +47,7 @@ function purgeOldCrashReports(dir) {
   let names
   try { names = readdirSync(dir) } catch { return } // 目录不存在/不可读 → 无事可做
   for (const name of names) {
-    if (!isCrashRecordName(name)) continue
+    if (!isPurgeRecordName(name)) continue
     try {
       if (statSync(join(dir, name)).mtimeMs < cutoff) unlinkSync(join(dir, name))
     } catch { /* 单个文件失败不影响其余 */ }

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),
     }

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/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)
 }