thincoder 0.12.61 → 0.12.62

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+## [0.12.62] — 2026-09-13
+
+> 0.12.61 → 0.12.62（§4.3 连续号——发布时定号）
+
+### Added
+
+- **文档锚一致性机检 V5（DOC-CODE-RECONCILE 批）**：`scripts/doc-anchors.mjs`（三类锚——用例号 / 本仓符号 / 路径——存在性判定 + 假阳类逐条排除 + 注记闭枚举 + 两态 `V5_GATE` / `--v5-gate` / `--v5-report`）· `scripts/doc-impact.mjs`（改动面反查：`--base` 必给、只读不阻断）· 常驻零值锁（`test:full` 内——再出现即红）· **清账 347 处 → 0**。
+- **台账自持机检**：`check-ledger` L4 本仓可解析闸 + 指针 / D3 组计数 / 六态 / 触发 / 老化报告。
+- **工程模式纪律进提示词**：跨仓派单与写域纪律 · 改动面反查（提示词两副本逐字一致）。
+
+### Changed
+
+- **文档体系各仓自持**：需求档 / 设计档 / 批次档 / 台账各仓记各仓（禁跨仓写需求与跨仓指针）；跨仓引用统一「名称（仓别）§N」规范形态。
+- **台账归档制**：活文件只留未决四态，已决逐条移入 `TODO-archive.md`。
+- **在途批一并签入（8 批）**：TUI 内存取证与上界（session store / segments / 堆遥测）· 台账可见面 · 测试纪律提示词 · 子代理审批面与活动区对位。
+
+### Removed
+
+- **散文锚退役（PROSE-ANCHOR-RETIRE 批）**：退役断言「某句在场 / 缺席」类测试 71 例（保留结构机检面：引用可解析 / 组计数 / 六态取值 / 行宽 / slow 归册）。
+
+### Fixed
+
+- 文档↔实装漂移清账（逐档处置留痕，禁「只删不记」）· `check-ledger` 扫描域收窄（只扫本仓活档 + 归档档）· 台账 L4 误报修正 · 批次档 / 设计档宽度与计数纪律收正。
+
 ## [0.12.61] — 2026-09-11
 
 > 0.12.60 → 0.12.61（§4.3 连续号——发布时定号）
@@ -291,7 +315,7 @@
 
 ### Changed
 
-- **系统提示词加两条约束**：①「先定正确再谈实现」——动手前先回答"正确应该是什么"（每个入口/视图/边界），再谈怎么实现，实现规模是"正确"的结果、不是决策标准；②「确认时暴露方案权衡」——确认理解时列出选的做法、为什么它对（绝不是"改动最小"）、考虑过但没选的替代方案。治"最小改动"偷懒病根
+- **系统提示词加两条约束**：①「先定正确再谈实现」——动手前先回答"正确应该是什么"（每个入口/视图/边界），再谈怎么实现，实现规模是"正确"的结果、不是决策标准；②「确认时暴露方案权衡」——确认理解时列出选的做法、为什么它对（判据 = 正确性优先——不是省事程度）、考虑过但没选的替代方案。治"图省事"的偷懒病根
 
 ## [0.12.47] — 2026-08-28
 

package/bin/thincoder.mjs

@@ -41,6 +41,13 @@ const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.u
 // 期窗口）——V8 OOM/原生 fatal 自动写 report.*.json（实现批实测：目录缺失时 Node 静默不写
 // ——预建为必要动作）。失败不阻断启动（尽力面）。
 prepareCrashReporting()
+// TUI-OOM-ROOTCAUSE（CRASH-REPORTS.md §8.3 武装点——全命令同源单点）：堆遥测/看门狗——
+// 60s 采样 + 双档（70/85%）比例边缘预警（stderr + TUI 行 + 事件日志）；定时器 unref
+// （一次性命令自然退出零阻塞）；默认开 / THINCODER_HEAP_WATCH 关值集可不启。失败面全吞。
+try {
+  const { startHeapWatch } = await import("../src/heap-watch.mjs")
+  startHeapWatch()
+} catch { /* 看门狗启动失败不阻断启动（尽力面） */ }
 
 // R25（F-R25a）异常钩子升级：原"只 console.error 一行（TUI 全屏下不可见）"→ ① 落盘
 // crash-{ts}-{pid}.json ② TUI 活动态终端恢复 ③ console.error（恢复后打印才可见）
@@ -293,11 +300,13 @@ switch (command) {
     // 恢复上次的会话（同一项目目录）；provider 按保存的名字切回（用户上次可能换过模型）
     // 2026-09-05 §10（R4）：恢复决策按本端记录 resumeSlot（D-2 ①②③）——manifest active
     // 只作"无记录端"的一次性继承源，不再作本端恢复第一依据（D-6）。
-    const { resumeSlot, applySession } = await import("../src/session.mjs")
+    const { resumeSlot, applySession, sessionDescriptor } = await import("../src/session.mjs")
     const { slot, data } = resumeSlot(process.cwd())
     if (data) {
       // applySession 内部已按槽复合重算 compactThreshold（auto 时）——不再需要 switched 分支
-      applySession(agent, data)
+      // TUI-OOM-ROOTCAUSE（SESSION.md §14.3.4）：传 slot → 绑定记录存储（身份核验 + 对账）
+      // ——人读线 = 尾窗（磁盘为准）；未传 = 模式 F（全量数组）
+      applySession(agent, data, { slot })
       // SESSION.md §11.2（2026-09-08——N6 评审 🔴 修复）：process restarted 句 = 进程级
       // 信号——仅本启动 resume 路径设一次（真进程重启恢复盘上会话）；/session 切换与 ACP
       // 加载走同一 applySession 收敛但不设（不误报进程重启）。prepareRun 发句即清——进程
@@ -326,7 +335,7 @@ switch (command) {
         projectDir: config.memory.projectDir ? (isAbsolute(config.memory.projectDir) ? config.memory.projectDir : join(process.cwd(), config.memory.projectDir)) : null,
         team: teamConfig(config),
         author: gitAuthor(),
-        restored: data,
+        restored: data ? sessionDescriptor(agent, data) : data,
         // R25（F-R25c）：TUI 启动显示一行"上次运行异常终止"提示（showStartup 渲染——无匹配不传）
         crashNotice: recentCrashHint() ?? undefined,
       })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thincoder",
-  "version": "0.12.61",
+  "version": "0.12.62",
   "description": "Thin coding agent - zero dependencies, no build step, Node.js native. Sharp code, zero bloat.",
   "keywords": [
     "ai",

package/src/acp.mjs

@@ -19,7 +19,7 @@ import { assembleAgent } from "./cli/make-agent.mjs"
 import { createAcpServer, ACP_ERRORS } from "./acp/transport.mjs"
 import { createAcpSession } from "./acp/session.mjs"
 import { replayHistory } from "./acp/bridge.mjs"
-import { listSlots, applySession, deleteSlot, normalizeCwd, loadSlotFile, slotOccupancy, loadManifest, saveManifest, getSessionId, newSession } from "./session.mjs"
+import { listSlots, applySession, deleteSlot, normalizeCwd, loadSlotFile, slotOccupancy, loadManifest, saveManifest, getSessionId, newSession, slotPath, bindRecordStore } from "./session.mjs"
 import { createCheckpoint, listCheckpoints, rewind, isGitRepo } from "./git/checkpoint.mjs"
 import { createMemory, list as memList, remove as memRemove } from "./memory.mjs"
 
@@ -157,6 +157,9 @@ export function buildAcpHandlers({
           // mySessionId 同进程恒真）→ 第二个会话拿到与第一个相同的槽号 → 双写同槽
           // F2 互旋。getSessionId() 是进程级，_slot 是 agent 级——粒度错配必须在此切断。
           session.agent._slot = newSession(getCwd())
+          // TUI-OOM-ROOTCAUSE（SESSION.md §14.3.4）：新建槽绑定记录存储（baseHistory 空——
+          // identity 待固化）——与 /new 同语义
+          bindRecordStore(session.agent, { slotFile: slotPath(getCwd(), session.agent._slot), identity: session.agent._sessionStart ?? null, baseHistory: [] })
           sessions.set(id, session)
           return { id, configOptions: [{ configId: "model" }, { configId: "thinking" }, { configId: "mode" }] }
         } catch (e) {
@@ -231,7 +234,6 @@ export function buildAcpHandlers({
         try {
           const id = String(nextId++)
           const session = await createSession({ id, notify: notifyRef.current, request: requestRef.current, log })
-          applySession(session.agent, data)
           // 2026-08-31 advisor round2 🟡：钉 _slot 前查活主——目标槽被另一活进程（CLI/另一
           // IDE）占用时不得钉回（双方 sessionStart 一致 → F2 永不轮转 → 同槽 last-write-wins
           // 静默互覆盖）。空闲则认领后钉回；占用则不钉 → 下次保存经 activeSlot 自然 fork
@@ -241,7 +243,11 @@ export function buildAcpHandlers({
           // 同进程防护完全由 sameProcessPinned 承担：本进程另一 session 已钉该槽即视为占用
           // （进程级属主无法区分 agent，双方 sessionStart 相同 → F2 永不触发 → 静默互覆盖）。
           const sameProcessPinned = [...sessions.values()].some((s) => s.agent?._slot === slot)
-          if (!occ.occupied && !sameProcessPinned) {
+          const pinned = !occ.occupied && !sameProcessPinned
+          // TUI-OOM-ROOTCAUSE（SESSION.md §14.3.4）：钉槽（非占用）才绑定记录存储——
+          // 占用/fork 分支模式 F（首保存 fork 新槽后补绑）
+          applySession(session.agent, data, pinned ? { slot } : {})
+          if (pinned) {
             const m = loadManifest(getCwd())
             m.slotSessions ??= {}
             m.slotSessions[slot] = getSessionId()
@@ -278,13 +284,15 @@ export function buildAcpHandlers({
         try {
           const id = String(nextId++)
           const session = await createSession({ id, notify: notifyRef.current, request: requestRef.current, log })
-          applySession(session.agent, data)
           // 2026-08-31 advisor round2 🟡：同 session/load——活主占用的槽不钉回（防同槽双写，
           // 下次保存 fork 新槽）；空闲则认领后钉回。
           const occ = slotOccupancy(getCwd(), slot)
           // 2026-09-01 会诊 kimi/glm 🔴：同 session/load——同进程其他 session 已钉同槽视为占用 → fork
           const sameProcessPinned = [...sessions.values()].some((s) => s.agent?._slot === slot)
-          if (!occ.occupied && !sameProcessPinned) {
+          const pinned = !occ.occupied && !sameProcessPinned
+          // TUI-OOM-ROOTCAUSE（SESSION.md §14.3.4）：同 load——钉槽才绑定（占用/fork 模式 F）
+          applySession(session.agent, data, pinned ? { slot } : {})
+          if (pinned) {
             const m = loadManifest(getCwd())
             m.slotSessions ??= {}
             m.slotSessions[slot] = getSessionId()

package/src/agent/run-stages.mjs

@@ -12,7 +12,7 @@ import { ensureAutoReminder, injectEngineeringReminder, ContinueError } from "./
 import { cleanupConsultSessions } from "../agent-tools/consult.mjs"
 import { logEvent } from "../log.mjs"
 // ASYNC-RESULT-CONTAINER.md D1：池 accessor（absorb 双池——advisor 独立池无队列）
-import { getAsyncPool } from "../agent-tools/async-settle.mjs"
+import { getAsyncPool, releaseSettledEntry } from "../agent-tools/async-settle.mjs"
 // R10 L3 (MULTI-INSTANCE-COLLAB §2a.5 D-L3a)：回合末域登记 flush（写工具钩子累积 →
 // 整写一次本实例 peers 文件——无写入跳过；失败容忍不抛）
 import { flushPeerDomains } from "../peer-domains.mjs"
@@ -235,6 +235,8 @@ async function collectSettledAsync(agent, { suspDriven = false } = {}) {
       if (!e.done) continue // still running — stays in the pool (D-S1)
       await injectAsyncResult(agent, e)
       if (e.role === "advisor") injectedAdvisor = true
+      // TUI-OOM-ROOTCAUSE（§23.3.1 消费点①——回合尾收集）：注入完成 → 释放条目持有
+      releaseSettledEntry(e)
       map.delete(String(e.id))
     }
   }

package/src/agent/spawn-child.mjs

@@ -17,6 +17,7 @@
 import { specForModel } from "../config.mjs"
 import { ContinueError } from "../agent.mjs"
 import { relayPrefixOf } from "./relay-prefix.mjs"
+import { appendCappedText } from "../text-budget.mjs"
 // 第 27 批 §12.3①：relay 前缀文法单一权威模块（`src/agent/relay-prefix.mjs`）——
 // 生成侧枢纽再导出（TUI/ACP 消费方可经此导入；消费方按 §12.3① 直连模块亦可）。
 export { RELAY_PREFIX_RE, parseRelayPath, relayPrefixOf } from "./relay-prefix.mjs"
@@ -162,6 +163,18 @@ export function emitNestedChildEvent(ctx, relayPrefix, kind) {
   return true
 }
 
+/** 捕获额度（TUI-OOM-ROOTCAUSE——AGENT-LOOP.md §23.3.1 表 1 候选 1：滞后水位截断）：
+ *  `_capturedOutput` 是子代理流式文本的第二份全量拷贝（原无上限——勘察 C2）；超 hard 即
+ *  裁至头 16K + 标记 + 尾 48K（摊还 O(1)）——消费面读时已各自 slice(0, 2000/4000)，头尾
+ *  保真覆盖；停止报告内联场景出现截断标记（可断言——D-SM1）。纯函数本体住
+ *  src/text-budget.mjs（与 TUI 面共用——D2 单源）。 */
+export const CAPTURE_CAP_OPTS = {
+  hard: 131_072,
+  head: 16_384,
+  tail: 49_152,
+  marker: "… [captured output truncated: N chars omitted] …",
+}
+
 /**
  * 子 agent provider API key 检查：trim 后非空才保留；缺失返回 null（调用方
  * 按各自业务语汇报错——subagent 抛出 / escalate·consult 返回 Error 文本）。
@@ -207,9 +220,11 @@ export async function runWithContinue(runner, child, input, callbacks, runOpts,
   // Review #4 fix: strip sentinel/control chars from the capture — `output` feeds
   // onDeclined's partial-output return, which lands in the PARENT LLM history where
   // the display-layer sanitizeDisplay backstop does not apply.
+  // TUI-OOM-ROOTCAUSE（§23.3.1）：捕获滞后水位截断——超 CAPTURE_CAP_OPTS.hard 裁至
+  // 头 + 标记 + 尾（_capturedOutput 有界；续跑同闭包累积，语义一致）。
   const capture = callbacks?.onToken
-    ? (t) => { output += stripEventTokensForCapture(String(t)); child._capturedOutput = output; callbacks.onToken(t) }
-    : (t) => { output += stripEventTokensForCapture(String(t)); child._capturedOutput = output }
+    ? (t) => { output = appendCappedText(output, stripEventTokensForCapture(String(t)), CAPTURE_CAP_OPTS); child._capturedOutput = output; callbacks.onToken(t) }
+    : (t) => { output = appendCappedText(output, stripEventTokensForCapture(String(t)), CAPTURE_CAP_OPTS); child._capturedOutput = output }
   // §27 R23 D-R23c1（评审 🔴 修复——2026-09-07）：capture 是子代理 runAgent/dispatch ctx
   // 实际收到的 onToken——嵌套 wrapper 标记（wrapChildCallbacks `_relayPrefix`）必须随
   // capture 透传，否则 eng-coder 内 explore 同步收尾的 emitNestedChildEvent 判定恒 false

package/src/agent-tools/async-settle.mjs

@@ -69,6 +69,19 @@ export function buildChildSignal(parent, ctx) {
 
 // ─── D3 settle 共享 helper ───────────────────────────────────────────────────
 
+/**
+ * §23.3.1 消化窗口持有释放（TUI-OOM-ROOTCAUSE——D-SM2 表 2 候选 1）：注入完成后置空条目
+ * 对子代理对象的引用（`childAgent`/`report`——条目前此从不显式释放，挂起期 = 分钟级驻留）。
+ * 幂等（重入不抛）；池内/挂起未消化窗口语义零变（settle 时刻不释放——表 2 候选 2 否决：
+ * status/observe 在窗口内仍读 child 摘要）。三消费点（回合尾收集 / run 起始 pending 注入 /
+ * 挂起残差注入）在注入完成后调本 helper。
+ */
+export function releaseSettledEntry(entry) {
+  if (!entry || typeof entry !== "object") return
+  entry.childAgent = null
+  entry.report = null
+}
+
 /**
  * D3 settle 共享 helper——四族 settle 回调公共收尾单点（ASYNC-RESULT-CONTAINER.md
  * AC1：settle 记账单点，无逐字重复）。流程：

package/src/agent-tools/consult.mjs

@@ -29,6 +29,8 @@ import { offloadToolResult, escapeXml } from "../agent/helpers.mjs"
 import { logEvent, errText } from "../log.mjs"
 import { deathLine } from "../abort-provenance.mjs"
 import { makeRelay, wrapChildCallbacks, runWithContinue, ensureChildApiKey, clampEffort } from "../agent/spawn-child.mjs"
+// TUI-OOM-ROOTCAUSE §23.3.1：子代理人读线窗口常量（单源——store 零依赖）。
+import { RECORD_WINDOW_MESSAGES } from "../session-store.mjs"
 // ASYNC-RESULT-CONTAINER.md D2/D3/D6：pending 单容器停靠 + settle 公共收尾 + child signal 单点
 import { buildChildSignal, settleAsyncEntry } from "./async-settle.mjs"
 import { digestBudgetOver, persistOverflowReport } from "./digest-budget.mjs" // B5（群 B 批 §22 D-DG2）：digest 注入预算单源
@@ -280,6 +282,9 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
       // role "consult" (overlay + base would concatenate it twice).
       role: "consult",
     })
+    // TUI-OOM-ROOTCAUSE §23.3.1：子代理人读线窗口（四处创建点同置）——consult 会话跨回合驻留，
+    // 不置窗则 _fullHistory 仍无界（F-O1 覆盖 depth>0 全部创建点）
+    child._historyWindow = RECORD_WINDOW_MESSAGES
 
     // Activity relay via the unified spawn-child pipeline (§7.2 D3): `consult#<subId>/`
     // prefix (same channel subagent uses — parallel consultants stay independent) +

package/src/agent-tools/escalate-async.mjs

@@ -27,6 +27,8 @@
 import { relative, isAbsolute } from "node:path"
 import { runAgent, createAgent, DEFAULT_SUBAGENT_TURNS } from "../agent.mjs"
 import { runWithContinue, TURN_CAP_MARK, wrapChildCallbacks } from "../agent/spawn-child.mjs"
+// TUI-OOM-ROOTCAUSE §23.3.1：子代理人读线窗口常量（单源——store 零依赖）。
+import { RECORD_WINDOW_MESSAGES } from "../session-store.mjs"
 import { logEvent } from "../log.mjs"
 import { deathLine } from "../abort-provenance.mjs"
 import {
@@ -102,6 +104,9 @@ function touchedFilesNote(child, cwd) {
  */
 export function classifyEscalateSettle(parent, entry) {
   if (entry.cancelled) return { cancelled: true }
+  // §23.3.1（TUI-OOM-ROOTCAUSE）——childAgent 语义面：settle 分类（touched 摘要/partial
+  // merge）与 status/observe 摘要的读取源；**消化注入完成后由 `releaseSettledEntry`
+  // （async-settle.mjs）置 null**（池内未消化窗口不释放——表 2 候选 2 否决）。
   const child = entry.childAgent
   const touched = child?._touchedFiles ?? []
   const overlap = overlapPaths(parent, entry.launchSeq, touched)
@@ -196,6 +201,7 @@ export function launchEscalateAsync(parent, ctx, launch) {
       role: "coder",
     })
     entry.childAgent = child // settle 分类/status touched 摘要绑定（start 时刻）
+    child._historyWindow = RECORD_WINDOW_MESSAGES // TUI-OOM-ROOTCAUSE §23.3.1：子代理人读线窗口（四处创建点同置）
     child._logId = relayPrefix.slice(0, -1)
     logEvent("child:spawn", { role: "escalate", id: child._logId, kind: "async", status: "running", ms: 0 })
     const childCallbacks = wrapChildCallbacks(relayPrefix, ctx.callbacks ?? {})

package/src/agent-tools/read-history.mjs

@@ -5,8 +5,9 @@
  * (SESSION.md §13 R19): an explicit session file path deep-queries that file's
  * history line; "cwd:<dir>" discovers the sessions stored for that directory.
  *
- * Default (no path) — THIS session's full human-readable record (agent._fullHistory
- * — NEVER compacted, audit-complete). Use to recall what was said or done earlier:
+ * Default (no path) — THIS session's full human-readable record (record store when bound
+ * — disk-backed, SESSION.md §14.3.7; agent._fullHistory memory fallback otherwise:
+ * NEVER compacted, audit-complete). Use to recall what was said or done earlier:
  * design decisions, tool-call timing, past rulings.
  *
  * Filters AND together: role / keyword (message text) / tool (tool messages by
@@ -273,7 +274,8 @@ export const readHistoryTool = {
     }
     const keyword = typeof a.keyword === "string" && a.keyword.length > 0 ? a.keyword : null
     // Case-insensitive substring WITHOUT copying the full message text: the human line is
-    // never compacted — single tool results can be hundreds of KB to MBs. Lowercase the
+    // never compacted (绑定态存储行 = slimForDisplay 产物——匹配基准 delta 见 SESSION.md
+    // §14.3.7 / T-RS8b) — single tool results can be hundreds of KB to MBs. Lowercase the
     // needle once and run a regex-i test over the haystack (escaping regex metachars so the
     // keyword stays a literal substring).
     const kwRe = keyword ? new RegExp(keyword.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i") : null
@@ -287,6 +289,19 @@ export const readHistoryTool = {
         : querySessionFile(pathArg, { role, kwRe, tool, since, until, direction, limit }, baseCwd)
     }
 
+    // 本会话（无 path）：绑定记录存储 → 方向流式迭代（磁盘为准——全量可见、内存窗口外
+    // 可命中；§14.3.7）；未绑定（测试 / 模式 F）→ 内存 _fullHistory 既有过滤路径（回退保留）。
+    // 方向语义不变：newest 自尾向前取满 limit → 反转回时间序（输出恒时间序）。
+    const store = ctx.agent?._recordStore
+    if (store?.iterate) {
+      const taken = []
+      for (const m of store.iterate(direction)) {
+        if (!matches(m, { role, kwRe, tool, since, until })) continue
+        taken.push(m)
+        if (taken.length >= limit) break
+      }
+      return formatMatches(direction === "newest" ? taken.reverse() : taken, "oldest", limit)
+    }
     const history = Array.isArray(ctx.agent?._fullHistory) ? ctx.agent._fullHistory : []
     const matched = history.filter((m) => matches(m, { role, kwRe, tool, since, until }))
     return formatMatches(matched, direction, limit)

package/src/agent-tools/subagent-actions.mjs

@@ -21,6 +21,8 @@ import { logEvent, errText } from "../log.mjs"
 import { describeBlockers, detectStall, STALL_NOTE } from "./subagent-scheduler.mjs"
 import { resolveChildProvider, mergeChildMutations } from "./subagent-async.mjs"
 import { launchEscalateAsync } from "./escalate-async.mjs"
+// TUI-OOM-ROOTCAUSE §23.3.1：子代理人读线窗口常量（单源——store 零依赖）。
+import { RECORD_WINDOW_MESSAGES } from "../session-store.mjs"
 // ASYNC-RESULT-CONTAINER.md D1：池 accessor（absorb 双池——advisor 独立池无队列）
 import { getAsyncPool } from "./async-settle.mjs"
 
@@ -406,6 +408,7 @@ export async function executeEscalateAction(args, ctx) {
       memory: parent.memory,
       role: "coder",
     })
+    child._historyWindow = RECORD_WINDOW_MESSAGES // TUI-OOM-ROOTCAUSE §23.3.1：子代理人读线窗口（四处创建点同置）
     child._logId = escId // LOGGING：子内事件归属（escalate#N）
     escT0 = Date.now()
     logEvent("child:spawn", { role: "escalate", id: escId, kind: "escalate" })

package/src/agent-tools/subagent-run.mjs

@@ -104,7 +104,7 @@ export function executeAsyncSpawn(parent, ctx, role, args, child, input, childOp
     if (baseSignal.aborted) ctrl.abort(baseSignal.reason)
     else baseSignal.addEventListener("abort", () => ctrl.abort(baseSignal.reason), { once: true })
   }
-  // §19.5 D-M5：turn 镜像拦截层（callbacks 包装层——选改动最小方案：在既有
+  // §19.5 D-M5：turn 镜像拦截层（callbacks 包装层——在既有
   // wrapChildCallbacks 之外再包一层，只解析 ⟦ev⟧turn 更新条目，其余原样转发）。
   const trackOpts = { ...childOpts }
   const parentOnToken = trackOpts.onToken

package/src/agent-tools/subagent-spawn.mjs

@@ -15,6 +15,8 @@ import {
   readonlyToolNames, escapeXml,
 } from "../agent.mjs"
 import { makeRelay, wrapChildCallbacks, relayPrefixOf } from "../agent/spawn-child.mjs"
+// TUI-OOM-ROOTCAUSE（AGENT-LOOP.md §23.3.1）：子代理人读线窗口常量单源（store 零依赖）。
+import { RECORD_WINDOW_MESSAGES } from "../session-store.mjs"
 import { validateDesignToken } from "./advisor.mjs"
 import { tokenExpired, removeDesignTokenSlot, reconcileEngTokensFromSlot, persistEngTokens } from "../token-ttl.mjs"
 import { resolveChildProvider, buildChildRunOpts, enqueueAsk } from "./subagent-async.mjs"
@@ -338,6 +340,10 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
     overlay,
     role,
   })
+  // TUI-OOM-ROOTCAUSE（AGENT-LOOP.md §23.3.1）：子代理人读线窗口置位（常量单源
+  // session-store.mjs）——机制复用主 agent 同路径（context.mjs pushReal 驱逐）；
+  // 每个 child 原先各自一份永不压缩的 _fullHistory（勘察 C2 乘数面）。
+  child._historyWindow = RECORD_WINDOW_MESSAGES
 
   // §2.20.2 批次档段写入通道绑定（第 4 批）：工程角色（eng-coder/eng-designer）把批次档
   // 绝对路径记在 child 上——setup 挂载 batch_segment 时读它。无路径参数的工具靠这条

package/src/agent.mjs

@@ -106,9 +106,13 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
   if (pendingAsync?.length) {
     const { injectAsyncResult } = await import("./agent-tools/subagent.mjs")
     const { injectConsultResult } = await import("./agent-tools/consult.mjs")
+    // TUI-OOM-ROOTCAUSE（AGENT-LOOP.md §23.3.1 消费点②——run 起始 pending 注入）：
+    // 注入完成后释放条目对子代理对象的持有（childAgent/report 置空——幂等 helper）。
+    const { releaseSettledEntry } = await import("./agent-tools/async-settle.mjs")
     for (const e of pendingAsync.splice(0)) {
       if (e.role === "consult") await injectConsultResult(agent, e)
       else await injectAsyncResult(agent, e)
+      releaseSettledEntry(e)
     }
   }
   agent._inAutoTurn = autoTurn // spawn gate for manual-tier digests (§17 D-S6/N3)

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/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,8 +25,13 @@
  */
 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")
@@ -32,13 +39,15 @@ export function crashReportsDir() {
 
 /** 记录文件模式（评审 #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 启动都生成（正常退出也留档）——计入即正常会话误报"异常终止"。 */
+ *  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)
+  return isCrashRecordName(name) || /^tui-stderr-.+\.log$/.test(name) || /^Heap\..+\.heapsnapshot$/.test(name)
 }
 
 /** >30 天淘汰（评审 #6）——写时自清理；搭车点 = 写 / 入口 mkdir / 启动扫描（复审 #4）。 */
@@ -54,18 +63,31 @@ 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 入口调用点零改）
+ * @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
 }

package/src/generate-title.mjs

@@ -69,9 +69,14 @@ export async function generateTitle(userContent, provider) {
 export async function ensureSessionTitle(agent) {
   if (agent.title) return agent.title
   try {
-    const firstUser = (agent._fullHistory ?? agent.history).find(
-      (m) => m.role === "user" && typeof m.content === "string" && !m.content.startsWith("[System reminder:"),
-    )
+    // TUI-OOM-ROOTCAUSE 批（SESSION.md §14.3.3）：绑定态首条 user 消息在记录存储（段 1）——
+    // 内存窗口可能已滑过它（store.firstUserMessage 首扫一次并缓存）；未绑定回退内存查找。
+    let firstUser = agent._recordStore?.firstUserMessage?.() ?? null
+    if (!firstUser) {
+      firstUser = (agent._fullHistory ?? agent.history).find(
+        (m) => m.role === "user" && typeof m.content === "string" && !m.content.startsWith("[System reminder:"),
+      )
+    }
     if (firstUser) {
       const title = await generateTitle(firstUser.content, agent.provider)
       if (title) agent.title = title

package/src/heap-watch.mjs

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