thincoder 0.12.66 → 0.12.68

package/src/command-table.mjs

@@ -0,0 +1,185 @@
+/**
+ * command-table.mjs — CLI 命令分发表（`bin/thincoder.mjs` 外提——2026-09-28 拆档批 R4 · 纯移动 ·
+ *   命令行为 ∕ USAGE 文本 ∕ 旗标语义零改）：分发骨架 + 八薄命令族（memory ∕ sync ∕ distill ∕
+ *   reindex ∕ completion ∕ upgrade ∕ session ∕ ledger）+ help ∕ version；交互长驻三命令
+ *   （chat ∕ tui ∕ acp）经 `command-interactive.mjs` 承接。依赖经 ctx 注入（`usage` ∕ `version` ∕
+ *   `exitSoon`——bin 装配面注入；先例 = `src/tui/turn-face.mjs` 出档）。
+ */
+import { readFileSync } from "node:fs"
+import { isAbsolute, join } from "node:path"
+import { loadConfig } from "@thincoder/core/config.mjs"
+import { createMemory, syncDir } from "@thincoder/core/memory.mjs"
+import { teamConfig } from "./cli/make-agent.mjs"
+import { memoryCommand } from "./cli/memory-command.mjs"
+import { distillCommand } from "./cli/distill-command.mjs"
+import { chatCommand, tuiCommand, acpCommand } from "./command-interactive.mjs"
+
+/** 命令分发（原 `bin/thincoder.mjs` 顶层 switch 骨架逐字搬移——命令行为零改）。 */
+export async function runCommandTable(command, args, ctx) {
+  const { usage, version, exitSoon } = ctx
+  switch (command) {
+    case "chat": {
+      await chatCommand(args, ctx)
+      break
+    }
+
+    case "memory": {
+      const config = loadConfig()
+      const memory = createMemory({ dbPath: config.memory.dbPath })
+      if (config.embedding?.apiKey) {
+        const { createEmbedder } = await import("@thincoder/core/embedding.mjs")
+        memory.embedder = createEmbedder(config.embedding)
+      }
+      if (config.memory.projectDir) {
+        memory.projectOrigin = isAbsolute(config.memory.projectDir) ? config.memory.projectDir : join(process.cwd(), config.memory.projectDir)
+      }
+      const code = await memoryCommand(memory, args)
+      if (code) exitSoon(code)
+      break
+    }
+
+    case "sync": {
+      const config = loadConfig()
+      const team = teamConfig(config)
+      if (!team) {
+        console.error("Team memory not configured. Set memory.team in ~/.thincoder/config.json:")
+        console.error('  "team": { "name": "myteam", "repo": "git@github.com:org/team-memory.git" }')
+        exitSoon(1)
+        break
+      }
+      const memory = createMemory({ dbPath: config.memory.dbPath })
+      const { ensureClone, pullTeam } = await import("@thincoder/core/git/gitmem.mjs")
+      try {
+        const cloned = await ensureClone(team)
+        if (cloned) console.log(`Cloned team repo to ${team.dir}`)
+        await pullTeam(team.dir)
+        const stats = await syncDir(memory, { layer: "team", dir: team.dir })
+        console.log(`Synced. Index: +${stats.added} ~${stats.updated} -${stats.removed}`)
+      } catch (error) {
+        console.error(`[error] ${error.message}`)
+        exitSoon(1)
+      }
+      break
+    }
+
+    case "distill": {
+      const code = await distillCommand(args, exitSoon)
+      if (code) exitSoon(code)
+      break
+    }
+
+    case "reindex": {
+      const config = loadConfig()
+      const memory = createMemory({ dbPath: config.memory.dbPath })
+      // files 层（project/team 的 markdown 索引）全量重建；索引是易失品，真相在 markdown
+      memory.db.prepare(`DELETE FROM files`).run()
+      const cwd = process.cwd()
+      let total = { added: 0, removed: 0 }
+      if (config.memory.projectDir) {
+        const s = await syncDir(memory, { layer: "project", dir: isAbsolute(config.memory.projectDir) ? config.memory.projectDir : join(cwd, config.memory.projectDir) })
+        total.added += s.added
+      }
+      const team = teamConfig(config)
+      if (team) {
+        const { ensureClone } = await import("@thincoder/core/git/gitmem.mjs")
+        await ensureClone(team)
+        const s = await syncDir(memory, { layer: "team", dir: team.dir })
+        total.added += s.added
+      }
+      console.log(`Reindexed ${total.added} markdown entries (project${team ? " + team" : ""}). Vectors will be lazily regenerated on next search.`)
+      break
+    }
+
+    case "tui":
+    case undefined: {
+      await tuiCommand(ctx)
+      break
+    }
+
+    case "completion": {
+      const shell = args[0]
+      if (!["bash", "zsh", "fish"].includes(shell)) {
+        console.error(`Usage: thincoder completion <bash|zsh|fish>`)
+        exitSoon(1)
+        break
+      }
+      // §11.2 交付行数债（2026-09-08——500 行硬限触碰执行）：直写段逐字迁出
+      // src/completions.mjs（脚本字节不变——printCompletion 发射）
+      const { printCompletion } = await import("./completions.mjs")
+      printCompletion(shell)
+      break
+    }
+
+    case "upgrade": {
+      const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"))
+      const local = pkg.version
+      const { checkForUpdate } = await import("./upgrade.mjs")
+      const result = await checkForUpdate(local)
+      if (!result) {
+        console.error("[upgrade] Unable to query npm registry — check your network connection and that npm is installed")
+        exitSoon(1)
+        break
+      }
+      if (!result.newer) {
+        console.log(`ThinCoder ${local} is already the latest.`)
+      } else {
+        console.log(`Upgrading: ${local} → ${result.latest}`)
+        const { execSync } = await import("node:child_process")
+        execSync("npm install -g thincoder@latest", { stdio: "inherit" })
+        console.log(`Upgraded to ${result.latest}`)
+      }
+      break
+    }
+
+    case "acp": {
+      await acpCommand(args, ctx)
+      break
+    }
+
+    case "session": {
+      // SESSION.md §6.12 / §6.17：会话目录 GC 显式面（冷 cwd 90 天面 + 三合取存量组全量面）——
+      // 双端同面（2026-09-21 端差注销：VS Code 端命令 `thincoder.sessionGc` 走同一核数据面）。
+      // SESSION.md §6.19 D-SE46（2026-09-22 会话索引批）：`session index` = 派生索引库显式面
+      // （--status 读数 / --rebuild 全量重扫）——同一 `session` 分发族（壳侧分发，实现在核）。
+      if (args[0] === "index") {
+        const { runSessionIndex } = await import("@thincoder/core/session-index-cmd.mjs")
+        process.exitCode = await runSessionIndex(args)
+        break
+      }
+      const { runSessionGc } = await import("@thincoder/core/session-gc.mjs")
+      process.exitCode = await runSessionGc(args)
+      break
+    }
+
+    case "ledger": {
+      // LEDGER.md §2.2（2026-09-25 批）：台账存量收正面——变体键合并迁移（migrate）/ 残档审计（audit）；
+      // 核内实现（ledger-migrate.mjs），壳侧只分发（先例 = `session gc` 双档：--dry-run 只读 / --confirm 执行）。
+      if (args[0] === "migrate" || args[0] === "audit") {
+        const m = await import("@thincoder/core/ledger-migrate.mjs")
+        process.exitCode = await (args[0] === "migrate" ? m.runLedgerMigrate(args) : m.runLedgerAudit(args))
+        break
+      }
+      console.error("Usage: thincoder ledger migrate --dry-run | --confirm [--from <key>] | thincoder ledger audit [--root <dir>]")
+      exitSoon(1)
+      break
+    }
+
+    case "--help":
+    case "-h": {
+      process.stdout.write(usage)
+      break
+    }
+
+    case "--version":
+    case "-v": {
+      console.log(version)
+      break
+    }
+
+    default: {
+      console.error(`Unknown command: ${command}\n`)
+      process.stdout.write(usage)
+      exitSoon(1)
+    }
+  }
+}

package/src/completions.mjs

@@ -2,6 +2,10 @@
  * completions.mjs — `thincoder completion <shell>` shell 补全脚本发射（bash/zsh/fish）。
  * bin/thincoder.mjs case "completion" 直写段拆分（2026-09-08——500 行硬限触碰执行：
  * 段逐字迁出，脚本字节与既有输出一致）。
+ * 发射契约（CLI-ENTRY.md §3 —— #704 收正 2026-09-30）：**源档形 ≡ 发射字节形**——bash 直写形零反斜杠
+ * `\$(...)` 非命令替换 ⇒ `bash -n` 语法错；zsh 分派行同排直写（双引号内 `\$` = 字面 `$` ⇒ 分派永不匹配）；
+ * 余反斜杠仅续行 `\\`（行尾接续，发射 `\`）——保留。
+ * 例外（JS 插值险位）：须发射字面 `${…}` 的段在源档保留 `\${` 转义。
  */
 export function printCompletion(shell) {
     if (shell === "bash") {
@@ -11,17 +15,23 @@ export function printCompletion(shell) {
   cur="\${COMP_WORDS[COMP_CWORD]}"
   prev="\${COMP_WORDS[COMP_CWORD-1]}"
   case "\${COMP_WORDS[1]}" in
-    chat)    COMPREPLY=( \\$(compgen -W "--auto" -- "\\$cur") ) ;;
+    chat)    COMPREPLY=( $(compgen -W "--auto" -- "$cur") ) ;;
     memory)
-      case "\\$prev" in
-        memory) COMPREPLY=( \\$(compgen -W "list search put remove" -- "\\$cur") ) ;;
-        list)   COMPREPLY=( \\$(compgen -W "--type=rule --type=knowledge --type=decision --type=pattern" -- "\\$cur") ) ;;
-        put)    COMPREPLY=( \\$(compgen -W "--type= --title= --content= --tags=" -- "\\$cur") ) ;;
+      case "$prev" in
+        memory) COMPREPLY=( $(compgen -W "list search put remove sweep" -- "$cur") ) ;;
+        list)   COMPREPLY=( $(compgen -W "--type=rule --type=knowledge --type=decision --type=pattern" -- "$cur") ) ;;
+        put)    COMPREPLY=( $(compgen -W "--type= --title= --content= --tags=" -- "$cur") ) ;;
+        sweep)  COMPREPLY=( $(compgen -W "--origin= --dry-run --confirm" -- "$cur") ) ;;
       esac ;;
-    distill) COMPREPLY=( \\$(compgen -W "--yes --layer=" -- "\\$cur") ) ;;
-    completion) COMPREPLY=( \\$(compgen -W "bash zsh fish" -- "\\$cur") ) ;;
+    ledger) case "$prev" in
+        ledger)  COMPREPLY=( $(compgen -W "migrate audit" -- "$cur") ) ;;
+        migrate) COMPREPLY=( $(compgen -W "--dry-run --confirm --from" -- "$cur") ) ;;
+        audit)   COMPREPLY=( $(compgen -W "--root" -- "$cur") ) ;;
+      esac ;;
+    distill) COMPREPLY=( $(compgen -W "--yes --layer=" -- "$cur") ) ;;
+    completion) COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") ) ;;
     *)
-      COMPREPLY=( \\$(compgen -W "tui chat acp memory sync reindex distill upgrade completion session -v --version -h --help" -- "\\$cur") ) ;;
+      COMPREPLY=( $(compgen -W "tui chat acp memory sync reindex distill upgrade completion session ledger -v --version -h --help" -- "$cur") ) ;;
   esac
 }
 complete -F _thincoder thincoder
@@ -36,7 +46,7 @@ _thincoder() {
     '1: :->cmd' \\
     '*:: :->args'
 
-  case "\\$state" in
+  case "$state" in
     cmd)
       _values 'command' \\
         'tui[Launch the interactive TUI]' \\
@@ -48,16 +58,21 @@ _thincoder() {
         'distill[Extract knowledge from session transcript]' \\
         'upgrade[Update to latest version from npm]' \\
         'completion[Generate shell completion script]' \\
-        'session[Session dir GC: session gc --dry-run|--confirm]'
+        'session[Session dir GC: session gc --dry-run|--confirm]' \\
+        'ledger[Ledger variants: migrate / audit]'
       ;;
     args)
-      case "\\$words[1]" in
+      case "$words[1]" in
         chat)    _arguments '--auto[Auto-approve all tool calls]' ;;
         memory)
-          case "\\$words[2]" in
+          case "$words[2]" in
             list) _arguments '--type=[Filter by type]' ;;
             put)  _arguments '--type=[Entry type]' '--title=[Title]' '--content=[Content]' '--tags=[Space-separated tags]' ;;
+            sweep) _arguments '--origin=[Origin path]' '--dry-run[Report only]' '--confirm[Apply writes]' ;;
           esac ;;
+        ledger) case "$words[2]" in
+            migrate) _arguments '--dry-run[Report only]' '--confirm[Apply migration]' '--from:Source key:' ;;
+            audit)   _arguments '--root:Scan root dir:' ;; esac ;;
         distill) _arguments '--yes[Skip confirmation]' '--layer=[Layer filter]' ;;
         completion) _values 'shell' 'bash' 'zsh' 'fish' ;;
       esac ;;
@@ -79,6 +94,7 @@ complete -c thincoder -a distill  -d 'Extract knowledge from session'
 complete -c thincoder -a upgrade  -d 'Update to latest version'
 complete -c thincoder -a completion -d 'Shell completion'
 complete -c thincoder -a session -d 'Session dir GC (session gc --dry-run|--confirm)'
+complete -c thincoder -a ledger -d 'Ledger variants: migrate / audit'
 complete -c thincoder -a acp -d 'Agent Client Protocol server for IDEs'
 
 # Flags
@@ -93,6 +109,7 @@ complete -c thincoder -n '__fish_seen_subcommand_from memory' -a list   -d 'List
 complete -c thincoder -n '__fish_seen_subcommand_from memory' -a search -d 'Search memory'
 complete -c thincoder -n '__fish_seen_subcommand_from memory' -a put    -d 'Add entry'
 complete -c thincoder -n '__fish_seen_subcommand_from memory' -a remove -d 'Remove entry'
+complete -c thincoder -n '__fish_seen_subcommand_from memory' -a sweep  -d 'Sweep dead origins'
 
 # memory list flags
 complete -c thincoder -n '__fish_seen_subcommand_from memory; and __fish_seen_subcommand_from list' -l type -d 'Filter by type' -xa 'rule knowledge decision pattern'
@@ -103,6 +120,11 @@ complete -c thincoder -n '__fish_seen_subcommand_from memory; and __fish_seen_su
 complete -c thincoder -n '__fish_seen_subcommand_from memory; and __fish_seen_subcommand_from put' -l content -d 'Content'
 complete -c thincoder -n '__fish_seen_subcommand_from memory; and __fish_seen_subcommand_from put' -l tags    -d 'Space-separated tags'
 
+# memory sweep flags
+complete -c thincoder -n '__fish_seen_subcommand_from memory; and __fish_seen_subcommand_from sweep' -l origin -d 'Origin path'
+complete -c thincoder -n '__fish_seen_subcommand_from memory; and __fish_seen_subcommand_from sweep' -l dry-run -d 'Report only'
+complete -c thincoder -n '__fish_seen_subcommand_from memory; and __fish_seen_subcommand_from sweep' -l confirm -d 'Apply writes'
+
 # distill flags
 complete -c thincoder -n '__fish_seen_subcommand_from distill' -l yes   -d 'Skip confirmation'
 complete -c thincoder -n '__fish_seen_subcommand_from distill' -l layer -d 'Layer filter'
@@ -111,6 +133,8 @@ complete -c thincoder -n '__fish_seen_subcommand_from distill' -l layer -d 'Laye
 complete -c thincoder -n '__fish_seen_subcommand_from completion' -a bash -d 'Bash completions'
 complete -c thincoder -n '__fish_seen_subcommand_from completion' -a zsh  -d 'Zsh completions'
 complete -c thincoder -n '__fish_seen_subcommand_from completion' -a fish -d 'Fish completions'
+complete -c thincoder -n '__fish_seen_subcommand_from ledger' -a 'migrate audit' -d 'Ledger variants: migrate / audit'
+complete -c thincoder -n '__fish_seen_subcommand_from ledger' -l dry-run -l confirm -l from -l root -d 'Ledger flags'
 `)
     }
 }

package/src/crash-reports.mjs

@@ -1,5 +1,5 @@
 /**
- * crash-reports.mjs — 崩溃捕获与取证（docs/design/CRASH-REPORTS.md——F1/F2 为 R25 与
+ * crash-reports.mjs — 崩溃捕获与取证（docs/cli/design/CRASH-REPORTS.md——F1/F2 为 R25 与
  * TUI-STDERR-CAPTURE 存量迁移；F3 近堆上限堆快照 = TUI-OOM-FORENSICS 批新增）。
  *
  * 能力（与设计逐项对应）：
@@ -8,7 +8,8 @@
  *   自动写 report.*.json。实现批实测（2026-09-07）：目录缺失时 Node 对 fatal 静默不写
  *   报告——预建是必要动作而非"零成本保险"。
  *   F3①：同点武装近堆上限堆快照（v8.setHeapSnapshotNearHeapLimit——对象级证据，回答
- *   "谁在持内存"；全路径单源，默认开、THINCODER_HEAP_SNAPSHOT 可关——F3②）。
+ *   "谁在持内存"；全路径单源，默认关、配置键 `diagnostics.heapSnapshot` 取 `true` 才武装
+ *   （fail-closed；bin 入口读键后经 `heapSnapshot` 参数显式传入——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,15 +24,12 @@
  * 纪律：全部同步 API（崩溃路径无异步）；调用方按执行序列各步独立 try/catch（复审 #2——
  * 写失败/恢复失败不阻断后续步——exit 非 0 恒达）。
  */
-import { chmodSync, existsSync, mkdirSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs"
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, 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 "@thincoder/core/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")
@@ -43,8 +41,14 @@ export function crashReportsDir() {
  *  Heap.*.heapsnapshot（CRASH-REPORTS F3③——快照 GB 级、TUI 落点须自动兜底）——但
  *  recentCrashHint 两类均不计（N3）：tui-stderr 每次 TUI 启动都生成（正常退出也留档）、
  *  快照非「异常终止」证据类——计入即正常会话误报。 */
+/** 记录类判定单源（`isCrashRecordName` 与 `recordFacts` 共用——防两处正则漂移）：自写 / Node fatal / 其余。 */
+function recordClassOf(name) {
+  if (/^crash-.+\.json$/.test(name)) return "self"
+  if (/^report\..+\.json$/.test(name)) return "native"
+  return null
+}
 function isCrashRecordName(name) {
-  return /^crash-.+\.json$/.test(name) || /^report\..+\.json$/.test(name)
+  return recordClassOf(name) !== null
 }
 function isPurgeRecordName(name) {
   return isCrashRecordName(name) || /^tui-stderr-.+\.log$/.test(name) || /^Heap\..+\.heapsnapshot$/.test(name)
@@ -63,21 +67,16 @@ function purgeOldCrashReports(dir) {
   }
 }
 
-/** 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 入口调用点零改）
+ * F3①：同点武装近堆上限堆快照（默认关——fail-closed，显式 `true` 才武装；全路径单源；开关 = bin 入口读配置键后经 `heapSnapshot` 传入）。
+ * @param {object} [opts] 注入缝（默认参数 = 生产常态）
  * @param {string} [opts.dir] 目录注入（测试用——同时服务 mkdir / report / purge / 返回）
- * @param {object} [opts.env] env 注入（测试用）——仅服务 F3② 判定
+ * @param {boolean} [opts.heapSnapshot] 快照武装开关（bin 入口经配置键判定后显式传入；配置默认关、显式 `true` 才武装——fail-closed；形参缺省 = 内部约定，生产调用点恒显式传值）
  * @param {(n: number) => void} [opts.armHeapSnapshot] 武装实现注入（测试用）——默认真实 node:v8 API
  */
-export function prepareCrashReporting({ dir = crashReportsDir(), env = process.env, armHeapSnapshot = v8.setHeapSnapshotNearHeapLimit } = {}) {
+export function prepareCrashReporting({ dir = crashReportsDir(), heapSnapshot = true, armHeapSnapshot = v8.setHeapSnapshotNearHeapLimit } = {}) {
   try {
     mkdirSync(dir, { recursive: true })
     // 代码内启用：shebang 入口无法携带启动参数（env 单参数限制 + execArgv 仅子进程——评审 #1）
@@ -85,7 +84,7 @@ export function prepareCrashReporting({ dir = crashReportsDir(), env = process.e
     process.report.reportOnFatalError = true
   } catch { /* mkdir/启用失败不阻断启动——尽力面 */ }
   // F3① 武装（独立 try——失败不阻断启动、不影响上方 F1 既有步骤；尽力面静默）
-  if (heapSnapshotEnabled(env)) {
+  if (heapSnapshot) {
     try { armHeapSnapshot(1) } catch { /* 武装失败不阻断——N1 */ }
   }
   purgeOldCrashReports(dir) // F-R25b 入口 mkdir 搭车清理（复审 #4——纯 fatal 序列也触发）
@@ -124,10 +123,33 @@ export function writeCrashRecord({ type, error }) {
   }
 }
 
+/**
+ * 提示行事实段（台账 #212 · 用户裁 B）：从选中记录读回 `uptime` / `cwd` 两段——段序固定 =
+ * uptime 段（` · 运行 <u>s`，一位小数）在前 / cwd 段（` · cwd <c>`）在后。
+ * 字段源按记录类分：自写记录（`crash-*.json`）取顶部 `uptime` / `cwd`；Node fatal 报告
+ * （`report.*.json`）取 `header.cwd`——Node 报告无 uptime 字段（2026-09-25 实测），该段略去。
+ * 退化（尽力面 · N1）：读档 / 解析失败、记录类不明、字段缺 / 型不符（`uptime` 非有限非负数 ·
+ * `cwd` 非非空字符串）⇒ 对应段略去；两段皆缺 ⇒ 空串（基础形）。不抛、不阻断启动。
+ */
+function recordFacts(file, name) {
+  const cls = recordClassOf(name)
+  if (cls === null) return "" // 记录类不明 ⇒ 零事实
+  let rec
+  try { rec = JSON.parse(readFileSync(file, "utf8")) } catch { return "" }
+  if (rec === null || typeof rec !== "object") return ""
+  let facts = ""
+  if (cls === "self" && typeof rec.uptime === "number" && Number.isFinite(rec.uptime) && rec.uptime >= 0) {
+    facts += ` · 运行 ${rec.uptime.toFixed(1)}s`
+  }
+  const cwd = cls === "native" ? rec.header?.cwd : rec.cwd
+  if (typeof cwd === "string" && cwd !== "") facts += ` · cwd ${cwd}`
+  return facts
+}
+
 /**
  * F-R25c：启动扫描——crash-reports 24h 窗内是否有记录（两类模式——mtime 判定）。
  * @param {object} [opts] 可选 { dir }——目录注入（测试用）；默认 crashReportsDir()
- * @returns {string|null} 提示文本（含最新记录完整路径）；无匹配 → null（负例——不提示）
+ * @returns {string|null} 提示文本（含最新记录完整路径 + 事实段——#212）；无匹配 → null（负例——不提示）
  */
 export function recentCrashHint({ dir = crashReportsDir() } = {}) {
   purgeOldCrashReports(dir) // F-R25c 启动扫描搭车清理（复审 #4）
@@ -141,10 +163,10 @@ export function recentCrashHint({ dir = crashReportsDir() } = {}) {
     try {
       const st = statSync(join(dir, name))
       if (st.mtimeMs >= cutoff && (!best || st.mtimeMs > best.mtimeMs)) {
-        best = { path: join(dir, name), mtimeMs: st.mtimeMs }
+        best = { path: join(dir, name), name, mtimeMs: st.mtimeMs }
       }
     } catch { /* 单文件 stat 失败跳过 */ }
   }
   if (!best) return null
-  return `上次运行异常终止（记录：${best.path}）`
+  return `上次运行异常终止（记录：${best.path}${recordFacts(best.path, best.name)}）`
 }

package/src/distill.mjs

@@ -40,7 +40,7 @@ If the session is long, prioritize conclusions that appeared last and are still
 Session log:
 `
 
-/** §18.6 D-TR6（2026-09-04 fix round1）：distill 调用点无 agent 作用域——traces 开关
+/** TRACES.md §6.1 D-TR6（2026-09-04 fix round1）：distill 调用点无 agent 作用域——traces 开关
  *  缺省回退磁盘配置（loadConfig——与 agent.config 同源：traces.enabled 缺省 on）；
  *  配置不可读时按缺省 on（注：CLI 启动早已 loadConfig——此处仅是兜底防御）。 */
 function tracesEnabledFromConfig() {
@@ -54,14 +54,14 @@ function tracesEnabledFromConfig() {
 /**
  * Extract candidates from a session transcript. transcript: plain-text session record.
  * Returns [{ type, title, content, tags, layer }], or [] on parse failure.
- * opts.traces（可选）：§18.6 D-TR6 开关显式透传（测试隔离/未来调用方）——缺省回退
+ * opts.traces（可选）：TRACES.md §6.1 D-TR6 开关显式透传（测试隔离/未来调用方）——缺省回退
  * 磁盘配置（tracesEnabledFromConfig）——关 = chat() 出口不落盘。
  */
 export async function extractCandidates(provider, transcript, opts = {}) {
   const traces = opts.traces ?? tracesEnabledFromConfig()
   const res = await chat(provider, {
     messages: [{ role: "user", content: DISTILL_PROMPT + transcript }],
-    // §18.6 D-TR4/D-TR6（fix round1）：distill 调用经 chat() 唯一采集点——补轨迹
+    // TRACES.md §6.1 D-TR4/D-TR6（fix round1）：distill 调用经 chat() 唯一采集点——补轨迹
     // 元数据 + traces 开关透传（关=不落盘必须全覆盖——不再静默越过开关）
     logCtx: { stage: "distill", kind: "distill", traces },
   })

package/src/heap-watch.mjs

@@ -9,8 +9,8 @@
  * 无绝对 MB 常量）；双档边缘触发（每档一次/进程——不重复刷屏）；零常态开销
  * （60s 一次 memoryUsage()，无输出——D-HW5）。
  *
- * 开关单点：`THINCODER_HEAP_WATCH`——关值集合 {`0`,`false`,`off`,`no`}（trim + 大小写
- * 不敏感）→ 不启动；未设/空串/其他值 → 启动（默认开——与 F3② 同约定）。
+ * 开关：配置键 `diagnostics.heapWatch`（默认开——判定形 `!== false`，与 F3 快照面默认相反〔快照默认关〕）——bin 入口读键后经
+ * `enabled` 参数显式传入；关 ⇒ 不注册定时器（返回惰性句柄）。
  *
  * 注入缝（N5 可测）：`sample` / `heapLimit` / `timer`——测试以假实现 + `checkNow()`
  * 直驱（零等待）；失败面全吞（采样抛错不阻断——样本失败静默跳过本次）。
@@ -18,15 +18,6 @@
 import { getHeapStatistics } from "node:v8"
 import { logEvent } from "@thincoder/core/log.mjs"
 
-/** 关值集合（单点判定——§3.2 同约定复用）。 */
-export const HEAP_WATCH_OFF = new Set(["0", "false", "off", "no"])
-
-/** 开关判定（单点——grep 面：仅本模块读 env.THINCODER_HEAP_WATCH）。 */
-export function heapWatchEnabled(env = process.env) {
-  const v = String(env.THINCODER_HEAP_WATCH ?? "").trim().toLowerCase()
-  return !HEAP_WATCH_OFF.has(v)
-}
-
 // 订阅表（TUI 行接线——§8.3 订阅制；模块级：武装在 bin、订阅在 startTUI）
 const _subscribers = new Set()
 
@@ -45,14 +36,14 @@ export function heapWarnLine(used, limit, ratio) {
 
 /**
  * 启动看门狗（返回 `{ stop(), checkNow() }`——checkNow 直驱一次采样并返回本轮新发预警行）。
- * 关值（§8.3）→ 不注册定时器（返回惰性句柄）。
+ * 开关关（`enabled: false`）→ 不注册定时器（返回惰性句柄）。
  */
 export function startHeapWatch({
   intervalMs = 60_000,
   ratios = [0.7, 0.85],
   sample = process.memoryUsage,
   heapLimit = () => getHeapStatistics().heap_size_limit,
-  env = process.env,
+  enabled = true,
   timer = setInterval,
 } = {}) {
   const warned = new Set()
@@ -76,7 +67,7 @@ export function startHeapWatch({
     } catch { /* 失败面全吞（N5——采样/上限抛错不阻断、状态保持） */ }
     return out
   }
-  if (!heapWatchEnabled(env)) return { stop() {}, checkNow }
+  if (!enabled) return { stop() {}, checkNow }
   const handle = timer(checkNow, intervalMs)
   try { handle?.unref?.() } catch { /* unref 失败不阻断（一次性命令自然退出） */ }
   return {

package/src/prompt-injections.mjs

@@ -16,5 +16,5 @@ export const CLI_PROMPT_INJECTIONS = {
   // bash 宿主终端面——CLI 无 terminal 参数（工具面 review 再统一）
   "bash-terminal-face": "",
   // question 工具可用性行（核内正文该行已移出正文、锚原位替换——本端填回 CLI 措辞）
-  "question-ui-face": "- Availability: this tool needs an interactive UI — in contexts without one (headless runs, subagent children) it returns an error instead of asking; put the question in your reply text instead.",
+  "question-ui-face": "- Availability: this tool needs an interactive UI — in contexts without one (headless runs) it returns an error instead of asking; subagent children (depth>0) never get it (excluded from their tool tables); put the question in your reply text instead.",
 }