thincoder 0.12.60 → 0.12.62

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/context.mjs

@@ -163,7 +163,7 @@ function tightenTailByBudget(history, start, floorStart, budgetTokens) {
  * pushReal — the single entry point for REAL conversation messages.
  * A real message (user input, assistant reply, tool result, multimodal image) is appended to BOTH:
  *   agent.history      — the machine context (compaction shrinks this)
- *   agent._fullHistory — the NEVER-COMPACTED human-readable record (persistence source)
+ *   agent._fullHistory — the human-readable record (persistence source)
  * Machine-only messages ([System reminder:...], compaction notes, task/plan/checkpoint re-injections)
  * are pushed directly to agent.history WITHOUT going through here, so they never enter _fullHistory.
  * The two lines are written independently at the source — no after-the-fact delta sync.
@@ -171,11 +171,22 @@ function tightenTailByBudget(history, start, floorStart, budgetTokens) {
  * point covers every real message. Pre-existing ts (e.g. from another end writing the shared slot)
  * is preserved; restored old messages keep no ts rather than getting a misleading backdate (D-S3).
  * ts is a LOCAL-ONLY field — the send layer strips it before any provider request (T-S3).
+ *
+ * TUI-OOM-ROOTCAUSE 批（SESSION.md §14.3.5）——人读线内存有界 + 磁盘为准：
+ *   ① `agent._recordStore?.append(msg)`：记录同步追加（磁盘为准——append-only sidecar）；
+ *   ② 窗口驱逐：绑定态（agent._historyWindow = 200）下 _fullHistory 只保最近窗口条——
+ *      更早内容仅存磁盘（翻页/检索/保存从盘按需读）。未绑定（模式 F）不驱逐（零回归）。
+ * 追加失败不阻断回合（独立 try/catch——尽力面 N-S6；store 内部另置 degraded 并停写）。
  */
 export function pushReal(agent, msg) {
   if (!Array.isArray(agent._fullHistory)) agent._fullHistory = []
   if (msg && msg.ts === undefined) msg.ts = Date.now()
   agent._fullHistory.push(msg)
+  try { agent._recordStore?.append(msg) } catch { /* 尽力面：落盘失败不阻断回合（N-S6） */ }
+  const win = agent._historyWindow
+  if (win > 0 && agent._fullHistory.length > win) {
+    agent._fullHistory.splice(0, agent._fullHistory.length - win)
+  }
   agent.history.push(msg)
 }
 

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

@@ -1,12 +1,14 @@
 /**
- * crash-reports.mjs — R25（docs/design/ARCHITECTURE.md §R25——F-R25a/b/c）CLI 异常终止
- * 捕获与留痕机制。
+ * crash-reports.mjs — 崩溃捕获与取证（docs/design/CRASH-REPORTS.md——F1/F2 为 R25 与
+ * TUI-STDERR-CAPTURE 存量迁移；F3 近堆上限堆快照 = TUI-OOM-FORENSICS 批新增）。
  *
- * 三类能力（与设计逐项对应）：
- * - prepareCrashReporting()（F-R25b）：入口最前调用——mkdir 预建 ~/.thincoder/crash-reports/
+ * 能力（与设计逐项对应）：
+ * - prepareCrashReporting()（F-R25b + F3①）：入口最前调用——mkdir 预建 ~/.thincoder/crash-reports/
  *   + process.report 代码内启用（reportOnFatalError + directory）——V8 OOM/原生 fatal
  *   自动写 report.*.json。实现批实测（2026-09-07）：目录缺失时 Node 对 fatal 静默不写
  *   报告——预建是必要动作而非"零成本保险"。
+ *   F3①：同点武装近堆上限堆快照（v8.setHeapSnapshotNearHeapLimit——对象级证据，回答
+ *   "谁在持内存"；全路径单源，默认开、THINCODER_HEAP_SNAPSHOT 可关——F3②）。
  * - writeCrashRecord()（F-R25a）：JS 异常钩子同步落盘 crash-{ts}-{pid}.json（ts = epoch ms
  *   UTC + pid——跨进程同 ms 防覆盖——复审 #3）——权限 0600（config.json 先例）。
  * - recentCrashHint()（F-R25c）：启动扫描 24h 窗内记录（两类文件模式定死——评审 #8：
@@ -23,18 +25,30 @@
  */
 import { chmodSync, existsSync, mkdirSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
+// F3① 命名空间 import：API 缺失（旧 Node）降级为调用期异常并被武装 try 吞掉——不做 import 期硬失败
+import * as v8 from "node:v8"
 import { configDir } from "./config.mjs"
 
+/** F3② 关值集合（trim + 大小写不敏感）；其余取值（未设 / 空串 / 未知串）默认开——fail-open 向取证。 */
+const HEAP_SNAPSHOT_OFF_VALUES = new Set(["0", "false", "off", "no"])
+
 /** crash-reports 运行时目录（~/.thincoder/crash-reports——非仓内——写时自清理）。 */
 export function crashReportsDir() {
   return join(configDir, "crash-reports")
 }
 
 /** 记录文件模式（评审 #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 天同族淘汰）与
+ *  Heap.*.heapsnapshot（CRASH-REPORTS F3③——快照 GB 级、TUI 落点须自动兜底）——但
+ *  recentCrashHint 两类均不计（N3）：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) || /^Heap\..+\.heapsnapshot$/.test(name)
+}
 
 /** >30 天淘汰（评审 #6）——写时自清理；搭车点 = 写 / 入口 mkdir / 启动扫描（复审 #4）。 */
 function purgeOldCrashReports(dir) {
@@ -42,25 +56,38 @@ 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 { /* 单个文件失败不影响其余 */ }
   }
 }
 
+/** F3② 武装判定（单点——包装器不判 env，防两处判定漂移）：关值集合命中 → 不武装；其余 → 武装。 */
+function heapSnapshotEnabled(env) {
+  return !HEAP_SNAPSHOT_OFF_VALUES.has(String(env?.THINCODER_HEAP_SNAPSHOT ?? "").trim().toLowerCase())
+}
+
 /**
  * F-R25b：入口最前调用（一切重活前——缩编程期窗口）——预建目录 + process.report 启用。
  * 任何失败不阻断启动（尽力面——record 路径自带降级）。返回目录路径。
+ * F3①：同点武装近堆上限堆快照（默认开——全路径单源；环境开关见 heapSnapshotEnabled）。
+ * @param {object} [opts] 注入缝（默认参数保 bin 入口调用点零改）
+ * @param {string} [opts.dir] 目录注入（测试用——同时服务 mkdir / report / purge / 返回）
+ * @param {object} [opts.env] env 注入（测试用）——仅服务 F3② 判定
+ * @param {(n: number) => void} [opts.armHeapSnapshot] 武装实现注入（测试用）——默认真实 node:v8 API
  */
-export function prepareCrashReporting() {
-  const dir = crashReportsDir()
+export function prepareCrashReporting({ dir = crashReportsDir(), env = process.env, armHeapSnapshot = v8.setHeapSnapshotNearHeapLimit } = {}) {
   try {
     mkdirSync(dir, { recursive: true })
     // 代码内启用：shebang 入口无法携带启动参数（env 单参数限制 + execArgv 仅子进程——评审 #1）
     process.report.directory = dir
     process.report.reportOnFatalError = true
   } catch { /* mkdir/启用失败不阻断启动——尽力面 */ }
+  // F3① 武装（独立 try——失败不阻断启动、不影响上方 F1 既有步骤；尽力面静默）
+  if (heapSnapshotEnabled(env)) {
+    try { armHeapSnapshot(1) } catch { /* 武装失败不阻断——N1 */ }
+  }
   purgeOldCrashReports(dir) // F-R25b 入口 mkdir 搭车清理（复审 #4——纯 fatal 序列也触发）
   return dir
 }