thincoder 0.12.59 → 0.12.61

package/src/context.mjs

@@ -287,7 +287,7 @@ export async function compressIfNeeded(agent, threshold, callbacks, extras = {},
   // Silent by design (D11): no onToken/onReasoning — the compaction process must not stream to the frontend.
   // signal propagates user cancellation (Ctrl+C) to the in-flight summary call.
   // Compression visibility (CONTEXT-COMPACTION.md §7 D-C1/D-C2): the frontend learns the compression
-  // STARTED right before the LLM call ("Compressing context… / summarizing N messages" panel) — only
+  // STARTED right before the summary LLM call ("Compressing context… / summarizing N messages" panel) — only
   // the lifecycle is surfaced, never the summary body. N = the number of history messages being summarized.
   callbacks?.onCompressStart?.({ messages: middle.length })
   const startedAt = performance.now()
@@ -374,150 +374,8 @@ function shrinkOversized(agent, limit = OVERSIZE_CONTENT_LIMIT) {
   return shrunk
 }
 
-// ─── End-of-run exploration distillation (AGENT-LOOP §13 + CONTEXT-COMPACTION §5, 2026-08-23) ───
-// The main agent's machine line is flooded by inline step-by-step exploration (read/grep/...).
-// At run end we distill THIS run's exploration tool-results into one semantic summary note that
-// replaces them in the machine line, while agent._fullHistory (the human line) stays untouched.
+// ─── End-of-run exploration distillation（2026-09-05 module-split：524 > 500 硬限——verbatim
+// 迁至 explore-distill.mjs，语义零变——VS Code compact.mjs 同款联动；cross-repo parity 锚改指
+// explore-distill.mjs——消费方 import 面不变（re-export））───────────────────────
 
-/** Read-only knowledge tools counted as "exploration" (execute writes files → never exploration). */
-export const EXPLORE_TOOLS = new Set([
-  "read", "grep", "glob", "ls", "code_search", "doc_search", "repo_outline",
-])
-
-/** Summary prompt for turning a burst of exploration results into a semantic summary. */
-export const EXPLORE_SUMMARY_PROMPT = `You are distilling exploration tool results. Summarize the following read-only codebase exploration into a compact semantic summary for the main agent's own context.
-
-Requirements:
-- Capture WHAT was discovered, WHERE (which files / directories / symbols), and the KEY CONCLUSIONS — do not list tool calls mechanically
-- Keep actionable facts the main agent needs to continue: code locations, function names, file paths, structure, and open questions the exploration raised
-- Drop raw tool-output noise, repeated lines, and verbatim file dumps — keep only what must be remembered
-- Be honest: mark anything not actually verified as "unverified"; do not present guesses as facts
-- Use bullet points; aim for information completeness, not a hard word limit
-
-Exploration log:
-`
-
-/** tool_calls name across both stored shapes ({function:{name}} and flat {name}). */
-function toolCallName(tc) {
-  return tc?.function?.name ?? tc?.name ?? ""
-}
-
-/** Tool that produced a tool-result message (falls back to its owner assistant's tool_call). */
-function toolResultName(msg, ownerToolCalls) {
-  if (typeof msg?.name === "string" && msg.name) return msg.name
-  const owner = (ownerToolCalls ?? []).find((tc) => tc.id === msg?.tool_call_id)
-  return owner ? toolCallName(owner) : ""
-}
-
-/**
- * Find the pure-exploration "assistant(tool_calls)→tool…" pair blocks added since `start`.
- * A block is explorable only when EVERY tool call AND every tool result in it is an exploration
- * tool — mixed blocks (read + edit in one turn) stay untouched, or we'd orphan the edit pairing.
- */
-function findExplorationBlocks(history, start) {
-  const blocks = []
-  let i = start
-  while (i < history.length) {
-    const m = history[i]
-    if (m?.role === "assistant" && Array.isArray(m.tool_calls) && m.tool_calls.length > 0) {
-      let j = i + 1
-      while (j < history.length && history[j]?.role === "tool") j++
-      const toolMsgs = history.slice(i + 1, j)
-      const allCallsExplore = m.tool_calls.every((tc) => EXPLORE_TOOLS.has(toolCallName(tc)))
-      const allResultsExplore = toolMsgs.length > 0 && toolMsgs.every((t) => EXPLORE_TOOLS.has(toolResultName(t, m.tool_calls)))
-      if (allCallsExplore && allResultsExplore) {
-        blocks.push({ start: i, end: j, messages: history.slice(i, j), toolCount: toolMsgs.length })
-      }
-      i = j
-    } else {
-      i++
-    }
-  }
-  return blocks
-}
-
-/** Serialize a batch of exploration messages for the summary LLM (same shape as compaction serialization). */
-function serializeExplorationMessages(messages) {
-  const cap = 8000 // exploration results ARE the signal to distill — generous cap (quality-first, N1)
-  return messages
-    .map((m) => {
-      const toolNote = m.tool_calls ? ` [called tools: ${m.tool_calls.map(toolCallName).join(", ")}]` : ""
-      let text = ""
-      if (typeof m.content === "string") text = m.content
-      else if (Array.isArray(m.content)) text = m.content.filter((p) => p?.type === "text").map((p) => p.text ?? "").join(" ")
-      return `[${m.role}]${toolNote} ${text.slice(0, cap)}`
-    })
-    .join("\n")
-}
-
-/**
- * Core (shared) distillation: replace this run's pure-exploration pair blocks with a single
- * "[Exploration summary]" note placed where the first block was. Returns a NEW history array,
- * or null when there is nothing to shrink (<3 exploration results / LLM failure). Pairing-safe:
- * whole assistant→tool blocks are removed, so no orphan tool_calls/tool can survive.
- */
-async function distillExplorations(history, start, provider, signal, agent, depth) {
-  if (!Array.isArray(history) || history.length - start < 2) return null
-  const blocks = findExplorationBlocks(history, start)
-  const resultCount = blocks.reduce((n, b) => n + b.toolCount, 0)
-  if (resultCount < 3) return null
-
-  const serialized = blocks.map((b) => serializeExplorationMessages(b.messages)).join("\n")
-
-  let summary
-  try {
-    // Silent by design (D11): thinking:null and no onToken/onReasoning — this internal
-    // distillation must not stream to the frontend. signal propagates user cancellation.
-    const resp = await chat({ ...provider, thinking: null, reasoningEffort: null }, {
-      messages: [{ role: "user", content: EXPLORE_SUMMARY_PROMPT + serialized }],
-      signal,
-      // §18.6 D-TR4：轨迹元数据增补——kind=distill（探索蒸馏面——agent 元数据透出；
-      // depth 经 summarizeRunExplorations 参数透传——agent.mjs 主作用域传入）
-      logCtx: {
-        stage: "distill", child: agent?._logId ?? null, kind: "distill",
-        role: agent?._role ?? null, depth: depth ?? null,
-        session: agent?._sessionStart ?? null, cwd: agent?.cwd ?? process.cwd(),
-        traces: agent?.config?.traces?.enabled !== false,
-      },
-    })
-    summary = resp?.content
-  } catch {
-    return null // N3: never block the run's return or lose history — original results stay
-  }
-  if (!summary) return null
-
-  const drop = new Set()
-  for (const b of blocks) for (let k = b.start; k < b.end; k++) drop.add(k)
-  const note = { role: "user", content: "[Exploration summary]\n" + summary }
-  const next = []
-  let inserted = false
-  for (let k = 0; k < history.length; k++) {
-    if (drop.has(k)) {
-      if (!inserted) { next.push(note); inserted = true }
-      continue
-    }
-    next.push(history[k])
-  }
-  return next
-}
-
-/**
- * End-of-run exploration distillation (runAgent's final return). Shrinks the MACHINE line
- * (agent.history) only; agent._fullHistory is never touched. Triggers when this run added ≥3
- * exploration tool results; on LLM failure it silently keeps the original history (N3).
- * The distillation itself is silent and never streams (D11); `callbacks.onDistilled` fires
- * ONLY after the replacement actually lands (never on no-op/failure) — callers persist the
- * compressed session (SEND-STALL-DISTILL §2.3).
- */
-export async function summarizeRunExplorations(agent, callbacks, signal, depth = 0) {
-  const next = await distillExplorations(agent.history, agent._runStartHistoryLen ?? 0, agent.provider, signal, agent, depth)
-  if (!next) return
-  agent.history = next
-  // The machine line changed shape — the measured token baseline was for the pre-shrink context.
-  // Invalidate so the next compaction check re-estimates instead of over-counting stale history.
-  agent._lastPromptTokens = null
-  agent._usageAtLen = null
-  // The compressed machine line must reach the disk: the run's own save already happened,
-  // so without this hook the async distill would leave the session un-compressed on exit.
-  callbacks.onDistilled?.()
-}
+export { summarizeRunExplorations, EXPLORE_TOOLS, EXPLORE_SUMMARY_PROMPT } from "./explore-distill.mjs"

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

@@ -0,0 +1,128 @@
+/**
+ * crash-reports.mjs — R25（docs/design/ARCHITECTURE.md §R25——F-R25a/b/c）CLI 异常终止
+ * 捕获与留痕机制。
+ *
+ * 三类能力（与设计逐项对应）：
+ * - prepareCrashReporting()（F-R25b）：入口最前调用——mkdir 预建 ~/.thincoder/crash-reports/
+ *   + process.report 代码内启用（reportOnFatalError + directory）——V8 OOM/原生 fatal
+ *   自动写 report.*.json。实现批实测（2026-09-07）：目录缺失时 Node 对 fatal 静默不写
+ *   报告——预建是必要动作而非"零成本保险"。
+ * - writeCrashRecord()（F-R25a）：JS 异常钩子同步落盘 crash-{ts}-{pid}.json（ts = epoch ms
+ *   UTC + pid——跨进程同 ms 防覆盖——复审 #3）——权限 0600（config.json 先例）。
+ * - recentCrashHint()（F-R25c）：启动扫描 24h 窗内记录（两类文件模式定死——评审 #8：
+ *   crash-*.json 自写 + report.*.json Node fatal——mtime 判定）→ 返回提示文本或 null
+ *   （无匹配不提示——负例）。
+ *
+ * 保留策略（评审 #6 + 复审 #4）：>30 天淘汰——写时自清理（tool-results 先例『落盘目录
+ * 写时自清理』段同动机——Windows 磁盘清理不覆盖 ~/.thincoder）——清理搭车点 = F-R25a 写 +
+ * F-R25b 入口 mkdir + F-R25c 启动扫描（纯 fatal 序列 JS 不运行——下个进程入口 mkdir 时
+ * 清理）。
+ *
+ * 纪律：全部同步 API（崩溃路径无异步）；调用方按执行序列各步独立 try/catch（复审 #2——
+ * 写失败/恢复失败不阻断后续步——exit 非 0 恒达）。
+ */
+import { chmodSync, existsSync, mkdirSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { configDir } from "./config.mjs"
+
+/** 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 实现批实测）。
+ *  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) {
+  const cutoff = Date.now() - 30 * 24 * 3_600_000
+  let names
+  try { names = readdirSync(dir) } catch { return } // 目录不存在/不可读 → 无事可做
+  for (const name of names) {
+    if (!isPurgeRecordName(name)) continue
+    try {
+      if (statSync(join(dir, name)).mtimeMs < cutoff) unlinkSync(join(dir, name))
+    } catch { /* 单个文件失败不影响其余 */ }
+  }
+}
+
+/**
+ * F-R25b：入口最前调用（一切重活前——缩编程期窗口）——预建目录 + process.report 启用。
+ * 任何失败不阻断启动（尽力面——record 路径自带降级）。返回目录路径。
+ */
+export function prepareCrashReporting() {
+  const dir = crashReportsDir()
+  try {
+    mkdirSync(dir, { recursive: true })
+    // 代码内启用：shebang 入口无法携带启动参数（env 单参数限制 + execArgv 仅子进程——评审 #1）
+    process.report.directory = dir
+    process.report.reportOnFatalError = true
+  } catch { /* mkdir/启用失败不阻断启动——尽力面 */ }
+  purgeOldCrashReports(dir) // F-R25b 入口 mkdir 搭车清理（复审 #4——纯 fatal 序列也触发）
+  return dir
+}
+
+/**
+ * F-R25a：JS 异常钩子同步写诊断记录（内容：时间/类型/错误消息+堆栈/uptime/argv/cwd/
+ * 内存/node+版本——设计字段集）。
+ * @param {string} type uncaughtException | unhandledRejection
+ * @param {*} error 原始 error（unhandledRejection 可 reject 任意值——非 Error 兜底 String）
+ * @returns {string|null} 记录完整路径；写失败 → null（不抛——调用方步隔离——复审 #2）
+ */
+export function writeCrashRecord({ type, error }) {
+  const dir = crashReportsDir()
+  try {
+    const record = {
+      time: new Date().toISOString(),
+      type,
+      message: error?.message ?? String(error),
+      stack: typeof error?.stack === "string" ? error.stack : null,
+      uptime: process.uptime(),
+      argv: process.argv,
+      cwd: process.cwd(),
+      memoryUsage: process.memoryUsage(),
+      node: process.version,
+    }
+    // ts = epoch ms UTC + pid——跨进程同 ms 防覆盖（复审 #3）
+    const file = join(dir, `crash-${Date.now()}-${process.pid}.json`)
+    writeFileSync(file, JSON.stringify(record, null, 2) + "\n", { encoding: "utf8", mode: 0o600 })
+    try { chmodSync(file, 0o600) } catch { /* Windows chmod 尽力而为——config.json 先例 */ }
+    purgeOldCrashReports(dir) // F-R25a 写时搭车清理（评审 #6）
+    return file
+  } catch {
+    return null // 写失败不阻断后续步
+  }
+}
+
+/**
+ * F-R25c：启动扫描——crash-reports 24h 窗内是否有记录（两类模式——mtime 判定）。
+ * @param {object} [opts] 可选 { dir }——目录注入（测试用）；默认 crashReportsDir()
+ * @returns {string|null} 提示文本（含最新记录完整路径）；无匹配 → null（负例——不提示）
+ */
+export function recentCrashHint({ dir = crashReportsDir() } = {}) {
+  purgeOldCrashReports(dir) // F-R25c 启动扫描搭车清理（复审 #4）
+  if (!existsSync(dir)) return null
+  const cutoff = Date.now() - 24 * 3_600_000
+  let best = null // 窗内 mtime 最新记录
+  let names
+  try { names = readdirSync(dir) } catch { return null } // 目录不可读 → 静默无提示
+  for (const name of names) {
+    if (!isCrashRecordName(name)) continue
+    try {
+      const st = statSync(join(dir, name))
+      if (st.mtimeMs >= cutoff && (!best || st.mtimeMs > best.mtimeMs)) {
+        best = { path: join(dir, name), mtimeMs: st.mtimeMs }
+      }
+    } catch { /* 单文件 stat 失败跳过 */ }
+  }
+  if (!best) return null
+  return `上次运行异常终止（记录：${best.path}）`
+}

package/src/distill.mjs

@@ -18,7 +18,7 @@ Output a JSON array (nothing else):
     "title": "Short title",
     "content": "Full content, self-contained — understandable without session context",
     "tags": ["tag1", "tag2"],
-    "scope": "personal | project"
+    "layer": "personal | project"
   }
 ]
 
@@ -27,7 +27,7 @@ Extraction criteria:
 - decision: technical decisions made in the session and their rationale
 - pattern: debugging experiences, solutions, reusable workflows
 - rule: coding standards (caution! rules are usually best written manually; only extract rules explicitly established in the session)
-- scope: use "project" for project-specific knowledge; use "personal" for general or personal preferences
+- layer: use "project" for project-specific knowledge; use "personal" for general or personal preferences
 
 Do NOT extract:
 - one-off task details ("changed line X in file Y today")
@@ -53,7 +53,7 @@ function tracesEnabledFromConfig() {
 
 /**
  * Extract candidates from a session transcript. transcript: plain-text session record.
- * Returns [{ type, title, content, tags, scope }], or [] on parse failure.
+ * Returns [{ type, title, content, tags, layer }], or [] on parse failure.
  * opts.traces（可选）：§18.6 D-TR6 开关显式透传（测试隔离/未来调用方）——缺省回退
  * 磁盘配置（tracesEnabledFromConfig）——关 = chat() 出口不落盘。
  */
@@ -117,23 +117,23 @@ export function historyToTranscript(history, { maxChars = 30_000 } = {}) {
 /**
  * Write confirmed candidates to the specified layer.
  * opts: { projectDir, team: { dir } | null, author }
- * scope=team requires opts.team; project requires opts.projectDir.
+ * layer=team requires opts.team; project requires opts.projectDir.
  * Returns write result description.
  */
 export async function saveCandidate(memory, candidate, opts = {}) {
-  const scope = candidate.scope ?? "personal"
+  const layer = candidate.layer ?? candidate.scope ?? "personal"
   // tags come from LLM output (untrusted): if not an array, stringify then split by comma/whitespace —
   // calling .split on a non-string would crash, and models often produce "a, b" comma strings
   const tags = Array.isArray(candidate.tags)
     ? candidate.tags.map((t) => String(t)).filter(Boolean)
     : String(candidate.tags ?? "").split(/[\s,]+/).filter(Boolean)
 
-  if (scope === "personal") {
+  if (layer === "personal") {
     const id = await put(memory, { type: candidate.type, title: candidate.title, content: candidate.content, tags: tags.join(" ") })
     return `personal#${id}`
   }
-  if (scope === "project") {
-    if (!opts.projectDir) throw new Error("project scope unavailable — no project directory configured (set memory.projectDir in ~/.thincoder/config.json)")
+  if (layer === "project") {
+    if (!opts.projectDir) throw new Error("project layer unavailable — no project directory configured (set memory.projectDir in ~/.thincoder/config.json)")
     const filename = await putMarkdown(memory, {
       layer: "project", dir: opts.projectDir,
       type: candidate.type, title: candidate.title, content: candidate.content,
@@ -141,8 +141,8 @@ export async function saveCandidate(memory, candidate, opts = {}) {
     })
     return `project:${filename}`
   }
-  if (scope === "team") {
-    if (!opts.team?.dir) throw new Error("team scope not configured — configure memory.team in ~/.thincoder/config.json")
+  if (layer === "team") {
+    if (!opts.team?.dir) throw new Error("team layer not configured — configure memory.team in ~/.thincoder/config.json")
     const filename = await putMarkdown(memory, {
       layer: "team", dir: opts.team.dir,
       type: candidate.type, title: candidate.title, content: candidate.content,
@@ -151,5 +151,5 @@ export async function saveCandidate(memory, candidate, opts = {}) {
     await commitAndPush(opts.team.dir, filename, `memory: [${candidate.type}] ${candidate.title} (distilled)`)
     return `team:${filename}`
   }
-  throw new Error(`unknown scope: ${scope}`)
+  throw new Error(`unknown layer: ${layer}`)
 }

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("\\", "/"))         // 余段分隔符归一（跨端统一）
+}