thincoder 0.12.61 → 0.12.62

package/src/prompts/persona-engineering.md

@@ -12,6 +12,7 @@ You are the **product manager and flow orchestrator** of this engineering-mode s
 **batch record** (`batches/*.md`).
 - **Yours**: requirement discussion + registration, batch close-out, batch record §1/§4/§6, content-level verification of the design
 (is the design right? does it cover the requirements?), reminding the user to fire the review, and delegating implementation.
+- **The ledger is yours**: the requirement-pool / tech-backlog ledger (record + status advance + physical writes; subagents never declare ledger files in `files`).
 - **NOT yours**: the requirements doc / design doc — that is **eng-designer**'s writing surface (revisions included; single writer).
 You do NOT write implementation code yourself — implementation is done by `eng-coder` subagents only.
 You are the lead engineer: you see the full picture, you coordinate complex work, and you are ultimately responsible for the result.

package/src/session-gc.mjs

@@ -19,7 +19,7 @@
  * import，启动钩子（session.mjs resumeSlot 包装）只一行调用。
  */
 
-import { readdirSync, readFileSync, statSync, unlinkSync, existsSync } from "node:fs"
+import { readdirSync, readFileSync, statSync, unlinkSync, existsSync, rmSync } from "node:fs"
 import { join, dirname, basename } from "node:path"
 import { configDir } from "./config.mjs"
 import { sessionPath, isProcessAlive } from "./session-slots.mjs"
@@ -153,7 +153,14 @@ export function deleteColdCwd(hash, { dir = sessionsDir(), now = Date.now(), ali
   if (!target) return { ok: false, reason: "not-cold", deleted: [] }
   const deleted = []
   for (const name of target.files) {
-    try { unlinkSync(join(dir, name)); deleted.push(name) } catch { /* 占用/竞态——跳过 */ }
+    const p = join(dir, name)
+    try {
+      // §14.3.8（TUI-OOM-ROOTCAUSE）：目录项（记录存储 sidecar `{prefix}.N.d`）递归删——
+      // 现 unlinkSync 对目录静默跳过（旧实现漏删 sidecar）；数据文件维持 unlink。
+      if (statSync(p).isDirectory()) rmSync(p, { recursive: true, force: true })
+      else unlinkSync(p)
+      deleted.push(name)
+    } catch { /* 占用/竞态——跳过 */ }
   }
   return { ok: true, deleted }
 }

package/src/session-guard.mjs

@@ -11,6 +11,17 @@
 
 import { existsSync, readFileSync, renameSync, statSync } from "node:fs"
 import { basename } from "node:path"
+// §14.3.8①（修正轮 #1）：.bak 轮转对**非本会话活动绑定面**联动改名 sidecar（`{p}.d → {bak}.d`）。
+import { RECORD_DIR_SUFFIX } from "./session-store.mjs"
+
+/** 轮转时随迁记录存储（.bak 路径联动）——本会话活动绑定面跳过（防拔掉活动存储）。 */
+function moveSidecar(src, dst, agent) {
+  const dir = src + RECORD_DIR_SUFFIX
+  if (agent?._recordStore?.dir === dir) return // 本会话活动绑定面——原地保留（§14.3.8①）
+  try {
+    if (existsSync(dir)) renameSync(dir, dst + RECORD_DIR_SUFFIX)
+  } catch { /* 随迁失败不阻断轮转（现场原地保留——读侧身份核验兜底） */ }
+}
 
 export function guardForeignSlotFile(agent, p, slot) {
   try {
@@ -29,6 +40,7 @@ export function guardForeignSlotFile(agent, p, slot) {
     if (diskIsNewer || diskForeign || (diskStart && diskStart !== myStart)) {
       const bak = `${p}.bak-${Date.now()}`
       renameSync(p, bak)
+      moveSidecar(p, bak, agent)
       console.error(`[session] slot ${slot} holds ${diskIsNewer ? `a newer-version file (v${disk.version})` : diskForeign ? `a foreign-cwd file (${disk.cwd})` : `another session (start ${diskStart}, ours ${myStart})`} — preserved as ${basename(bak)}`)
       agent._slotMtime = st.mtimeMs
       return bak

package/src/session-segments.mjs

@@ -0,0 +1,100 @@
+/**
+ * session-segments.mjs — 记录存储的段文件原语 + 人读线条目形态（TUI-OOM-ROOTCAUSE 批）。
+ *
+ * 机制契约全文 = docs/design/SESSION.md §14.3（D2 单一权威源）；本文件 = 「段 IO + 条目
+ * 形态」叶子层（`session-store.mjs` 拆分产物——503+ 行越 500 硬限，§14.5 表列模块按职责
+ * 拆分；store 继续 re-export 全部公开名，调用面零改）。零项目内依赖（仅 `node:`）。
+ */
+
+import { readdirSync, readFileSync } from "node:fs"
+
+/** 常量单源（§14.3.2）：每段消息数 / sidecar 目录后缀。 */
+export const RECORD_SEG_MESSAGES = 100
+export const RECORD_DIR_SUFFIX = ".d"
+
+/** 观测计数（测试缝——AC-RS9「恢复只读末段」以段读次数断言）。 */
+export const _storeStats = { segmentReads: 0, segmentWrites: 0, appendedEntries: 0, catchUpRetries: 0 }
+
+const LEGACY_TRANSIENT_PREFIXES = [
+  "[System reminder: working directory snapshot:",
+  "[Relevant memories from previous sessions",
+]
+
+/** legacy transient 判定（旧进程写进人读线的机器注入——落盘/展示均跳过）。 */
+export function isLegacyTransient(m) {
+  return (
+    m?.role === "user" &&
+    typeof m.content === "string" &&
+    LEGACY_TRANSIENT_PREFIXES.some((p) => m.content.startsWith(p))
+  )
+}
+
+/** Slim the HUMAN line for storage（自 session.mjs 迁出——§14.5）：机器线（contextHistory）
+ *  逐字节保持。Copy-on-write ONLY（两线经 pushReal 共享对象引用）：tool args → 300 字符头
+ *  截断 / tool content → 500 / 多模态 user → 保留 text、丢 image_url。 */
+export function slimForDisplay(m) {
+  if (m && Array.isArray(m.content)) {
+    const textParts = m.content.filter((p) => p?.type !== "image_url")
+    if (textParts.length === m.content.length) return m
+    return { ...m, content: textParts }
+  }
+  if (m && m.role === "assistant" && Array.isArray(m.tool_calls)) {
+    let changed = false
+    const tool_calls = m.tool_calls.map((tc) => {
+      const args = tc.function?.arguments
+      if (typeof args === "string" && args.length > 300) {
+        changed = true
+        return { ...tc, function: { ...tc.function, arguments: args.slice(0, 300) + "…" } }
+      }
+      return tc
+    })
+    return changed ? { ...m, tool_calls } : m
+  }
+  if (m && m.role === "tool" && typeof m.content === "string" && m.content.length > 500) {
+    return { ...m, content: m.content.slice(0, 500) + "\n… (truncated for storage)" }
+  }
+  return m
+}
+
+/** 记录条目过滤（与 saveSession 同源）：transient 机器注入与 legacy-transient 前缀不进记录。 */
+export function shouldAppend(m) {
+  return !!m && typeof m === "object" && !m.transient && !isLegacyTransient(m)
+}
+
+/** 真实 user 消息（turnCount/firstMessage 口径——同 session-slots.extractSlotMeta）。 */
+export function isRealUserMsg(m) {
+  return m?.role === "user" && typeof m.content === "string" && !m.content.startsWith("[System reminder:")
+}
+
+/** sidecar 目录路径（`{slot 文件路径}.d`——同目录同前缀）。 */
+export function recordDirOf(slotFile) { return slotFile + RECORD_DIR_SUFFIX }
+
+/** 段文件名（六位零填充）。 */
+export function segName(n) { return `seg-${String(n).padStart(6, "0")}.jsonl` }
+
+/** 段号升序表（readdir——不读内容）。 */
+export function listSegments(dir) {
+  let names
+  try { names = readdirSync(dir) } catch { return [] }
+  const out = []
+  for (const n of names) {
+    const m = /^seg-(\d+)\.jsonl$/.exec(n)
+    if (m) out.push(Number(m[1]))
+  }
+  return out.sort((a, b) => a - b)
+}
+
+/** 读段（原始行——去尾空行）；读失败按空段容忍（读路径尽力面）。 */
+export function readSegmentLines(path) {
+  _storeStats.segmentReads++
+  let text
+  try { text = readFileSync(path, "utf8") } catch { return [] }
+  const lines = text.split("\n")
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop()
+  return lines
+}
+
+/** 逐行容错解析：半行/损坏行 → undefined（调用方跳过——不抛、不自动修复）。 */
+export function tryParse(line) {
+  try { return JSON.parse(line) } catch { return undefined }
+}

package/src/session-slots.mjs

@@ -18,6 +18,8 @@ import { migrateHashLength } from "./session-migrate.mjs"
 // legacy 过滤）属 session.mjs（500 行内不迁移）——静态环仅此一处：函数声明实例化期已初始化、
 // 只函数体内运行时使用（环安全）；VS Code 端 session-slots ↔ session-io 同构镜像。
 import { loadSlotFile, isLegacyTransient } from "./session.mjs"
+// TUI-OOM-ROOTCAUSE 批（SESSION.md §14.3.8）：删槽联动记录存储（store 零项目内依赖——无环）。
+import { unlinkRecordStore } from "./session-store.mjs"
 
 let currentSessionId = null
 
@@ -405,6 +407,7 @@ export function deleteSlot(cwd, slot) {
   delete m.slots[n]
   delete m.slotSessions?.[n] // orphan session-id entries bloat the manifest forever
   try { unlinkSync(slotPath(cwd, n)) } catch { /* missing file is fine */ }
+  unlinkRecordStore(slotPath(cwd, n)) // §14.3.8：删槽连带删除记录存储（sidecar）
   if (m.active === n) delete m.active
   // setActive: true —— 显式表达"删到 active 时 active 置空"的意图（saveManifest 默认
   // 保留 fresh.active，2026-09-01 会诊三家 🟡）

package/src/session-store.mjs

@@ -0,0 +1,441 @@
+/**
+ * session-store.mjs — 人读线记录存储：磁盘为准 + 内存窗口（TUI-OOM-ROOTCAUSE 批）。
+ * 机制契约全文 = docs/design/SESSION.md §14.3（D2 单一权威源）；本文件 = 实现。
+ * 形态：`{slot 文件路径}.d/` + `meta.json` + `seg-000001.jsonl`（行 = slimForDisplay 后的
+ * 消息 JSON——与槽 JSON `history` 元素逐字节同形；投影零转换，§14.3.1）。
+ * 依赖：零项目内依赖（仅 `node:`）——路径由 `slotFile` 传入；session.mjs / session-slots.mjs /
+ * session-guard.mjs 单向引本模块。窗口驱逐在 pushReal（context.mjs）、追加单点同 pushReal。
+ * 段 IO 原语与条目形态（`slimForDisplay` 等）拆住 `session-segments.mjs`（越 500 硬限的
+ * 职责拆分——本档 re-export 全部公开名，调用面零改）。
+ */
+
+import {
+  appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync,
+  renameSync, rmSync, truncateSync, unlinkSync, writeFileSync, writeSync,
+} from "node:fs"
+import { basename, dirname, join } from "node:path"
+import {
+  RECORD_SEG_MESSAGES, recordDirOf, segName, listSegments, readSegmentLines, tryParse,
+  isLegacyTransient, slimForDisplay, shouldAppend, isRealUserMsg, _storeStats,
+} from "./session-segments.mjs"
+
+// 公开名 re-export（调用面零改——§14.3.3 接口面）
+export {
+  RECORD_SEG_MESSAGES, RECORD_DIR_SUFFIX, recordDirOf, isLegacyTransient, slimForDisplay, _storeStats,
+} from "./session-segments.mjs"
+
+/** 内存窗口（条数——与首屏 INITIAL_HISTORY_MESSAGES 同值——单一概念，§14.3.2）。 */
+export const RECORD_WINDOW_MESSAGES = 200
+
+const META_NAME = "meta.json"
+
+class RecordStore {
+  constructor(slotFile) {
+    this.slotFile = slotFile
+    this.dir = recordDirOf(slotFile)
+    this.agent = null
+    this.identity = null      // meta.identity（会话身份锚 = sessionStart）
+    this.degraded = false     // 追加失败即停（§14.4 D-R4①）
+    this.memTotal = 0         // pushReal 计数（含未落盘条——缺口 = memTotal − total，D-R4②）
+    this._segCount = this._lastSegN = this._lastSegLines = 0 // 末段段号（= 段文件数）+ 行数
+    this._metaReady = false
+    this._lastSegCache = null // { n, lines }——bind 期复用（恢复只读末段：不重复读同一段）
+    this._partialSeg = 0      // 带未写完半行的段号（崩溃现场——首写前先补行终止符，防粘连）
+    this._counts = { turnCount: 0, firstMessage: "" }
+    this._sawRealUser = false
+    this._firstUser = undefined // undefined = 未扫；null = 无（首扫一次并缓存）
+  }
+
+  /** 绑定对账（§14.3.4）：**先验身份、后比计数**。返回 this。 */
+  bind(agent, identity, baseHistory) {
+    this.agent = agent
+    const base = (Array.isArray(baseHistory) ? baseHistory : []).filter(shouldAppend)
+    const site = identity ?? null
+    let meta = this._readMeta()
+    this._scan()
+    const hasSidecar = meta !== null || this._segCount > 0
+    if (hasSidecar) {
+      this.identity = meta?.identity ?? null
+      const bothEmpty = !this.identity && !site
+      const same = !!(this.identity && site && this.identity === site)
+      if (!bothEmpty && !same) {
+        // 陈旧/孤儿 sidecar——不得采纳（槽号回收/轮转/改名/对端占用同槽的跨会话污染面）：
+        // 改名 `.stale-<epochms>` 保留现场，按现场重建（§14.3.8 ②③）——身份回到现场身份
+        // （否则空 base 路径不重物化时，新建 sidecar 会把旧会话身份写进 meta——内审 #1）。
+        this._quarantine()
+        this.identity = site
+        meta = null
+      }
+    } else {
+      this.identity = site // 无 sidecar：创建时写入现场身份（可 null——待固化）
+    }
+    const storeTotal = this.total()
+    if (meta?.degraded === true || storeTotal < base.length) {
+      // ② 计数对账——以 JSON 为准重建（降级标记 / JSON 更长：VSC 追加、sidecar 缺失、首次迁移）
+      this.identity = site
+      this._materialize(base)
+    } else {
+      // 以段为准（崩溃后未保存消息可见）——计数 = JSON 全量 + JSON 之后的已落盘尾部
+      this._countOver(base)
+      if (storeTotal > base.length) this._countOver(this._range(base.length, storeTotal))
+    }
+    this.memTotal = this.total()
+    return this
+  }
+
+  _readMeta() {
+    try {
+      const p = join(this.dir, META_NAME)
+      if (!existsSync(p)) return null
+      const m = JSON.parse(readFileSync(p, "utf8"))
+      return m && typeof m === "object" ? m : null
+    } catch { return null }
+  }
+
+  _writeMeta() {
+    const meta = { v: 1, segSize: RECORD_SEG_MESSAGES, identity: this.identity ?? null }
+    if (this.degraded) meta.degraded = true
+    try {
+      mkdirSync(this.dir, { recursive: true })
+      const tmp = join(this.dir, META_NAME) + ".tmp"
+      writeFileSync(tmp, JSON.stringify(meta), "utf8")
+      renameSync(tmp, join(this.dir, META_NAME))
+    } catch {
+      try { writeFileSync(join(this.dir, META_NAME), JSON.stringify(meta), "utf8") } catch { /* 尽力面 */ }
+    }
+  }
+
+  /** meta 同步（身份补写 / 降级置位时重写——小文件原子写）。 */
+  syncMeta() {
+    try { this._writeMeta(); this._metaReady = true } catch { /* 尽力面 */ }
+  }
+
+  /** 陈旧/孤儿现场保留：目录改名 `.stale-<epochms>`（与 .bak/.corrupted 同族）后按现场重建。 */
+  _quarantine() {
+    const dst = `${this.dir}.stale-${Date.now()}`
+    try {
+      renameSync(this.dir, dst)
+      console.error(`[session] stale record store preserved as ${basename(dst)} (identity ${this.identity ?? "null"} ≠ session)`)
+    } catch { /* 改名失败（占用）——仍按现场重建（materialize 覆盖） */ }
+    this._resetState()
+    this.identity = null // 隔离后不再持有旧身份（新 sidecar 待写现场身份——bind 内随即置回 site）
+    this.degraded = false
+  }
+
+  /** 定位态 + 计数态归零（改名/重建/扫描共用；counts=false 保留计数——扫描路径）。 */
+  _resetState(counts = true) {
+    this._segCount = this._lastSegN = this._lastSegLines = 0
+    this._metaReady = false
+    this._lastSegCache = null
+    this._partialSeg = 0
+    if (!counts) return
+    this._counts = { turnCount: 0, firstMessage: "" }
+    this._sawRealUser = false
+    this._firstUser = undefined
+  }
+
+  /** 目录扫描：段数 + 末段行数（半行 = 末段最后一行解析失败 → 视为未写完、忽略）。 */
+  _scan() {
+    const segs = listSegments(this.dir)
+    this._resetState(false)
+    if (segs.length === 0) return
+    this._segCount = this._lastSegN = segs[segs.length - 1]
+    const lines = readSegmentLines(join(this.dir, segName(this._lastSegN)))
+    const complete = lines.length > 0 && tryParse(lines[lines.length - 1]) === undefined ? lines.length - 1 : lines.length
+    this._lastSegLines = complete
+    // 末尾半行（崩溃现场）：记段号——下一次追加先补行终止符（不自动修复内容，仅不粘连新记录）
+    this._partialSeg = lines.length > complete ? this._lastSegN : 0
+    this._lastSegCache = { n: this._lastSegN, lines: lines.slice(0, complete) }
+  }
+
+  /** 末段缓存取段（bind 期不重复读同一段）。 */
+  _segmentLines(n) {
+    if (this._lastSegCache && this._lastSegCache.n === n) return this._lastSegCache.lines
+    return readSegmentLines(join(this.dir, segName(n)))
+  }
+
+  _countOver(msgs) {
+    for (const m of msgs) this._countLine(m)
+  }
+
+  /** 以 JSON 为准重建整个 sidecar（rm 目录 → 重新物化——§14.3.4 规则 2）。 */
+  _materialize(base) {
+    try { rmSync(this.dir, { recursive: true, force: true }) } catch { /* 尽力面 */ }
+    this._resetState()
+    this.degraded = false
+    this.memTotal = 0
+    if (base.length === 0) return // 两者皆空 → 新目录懒创建（首 append 建目录/写 meta）
+    mkdirSync(this.dir, { recursive: true })
+    this._writeMeta()
+    this._metaReady = true
+    const buf = []
+    for (const m of base) {
+      this._countLine(m)
+      buf.push(JSON.stringify(slimForDisplay(m)))
+      if (buf.length >= RECORD_SEG_MESSAGES) this._flushSeg(buf)
+    }
+    this._flushSeg(buf)
+    this.memTotal = this.total()
+  }
+
+  /** 段落盘（物化路径——整段一次写出）。 */
+  _flushSeg(lines) {
+    if (lines.length === 0) return
+    const n = this._lastSegN + 1
+    writeFileSync(join(this.dir, segName(n)), lines.join("\n") + "\n", "utf8")
+    this._lastSegN = n
+    this._lastSegLines = lines.length
+    this._segCount = n
+    this._lastSegCache = null
+    _storeStats.segmentWrites++
+    lines.length = 0
+  }
+
+  /** 已落盘条数：(段数−1) × segSize + 末段行数（末段空文件按 0 行计）。 */
+  total() {
+    if (this._segCount <= 0) return 0
+    return (this._segCount - 1) * RECORD_SEG_MESSAGES + this._lastSegLines
+  }
+
+  /** 绝对区间 [lo, hi) 的连续切片（逐段读——只触碰覆盖区间段）。 */
+  _range(lo, hi) {
+    const out = []
+    const total = this.total()
+    if (hi <= lo || total <= 0) return out
+    const firstSeg = Math.floor(lo / RECORD_SEG_MESSAGES) + 1
+    const lastSeg = Math.floor((hi - 1) / RECORD_SEG_MESSAGES) + 1
+    for (let s = firstSeg; s <= lastSeg; s++) {
+      const lines = this._segmentLines(s)
+      const segBase = (s - 1) * RECORD_SEG_MESSAGES
+      for (let k = 0; k < lines.length; k++) {
+        const idx = segBase + k
+        if (idx < lo || idx >= hi || idx >= total) continue
+        const msg = tryParse(lines[k])
+        if (msg !== undefined) out.push(msg)
+      }
+    }
+    return out
+  }
+
+  /** 尾部 n 条（恢复窗口：只读末段及其前置段）。 */
+  tail(n) {
+    const total = this.total()
+    return this._range(Math.max(0, total - n), total)
+  }
+
+  /** 区间取页 + ±1 页沿（§14.3.6——页沿上下文供渲染层跨页回合标签/工具结果配对）。 */
+  page(start, end, { margin = 1 } = {}) {
+    const total = this.total()
+    const lo = Math.max(0, start - margin)
+    const hi = Math.min(total, end + margin)
+    return { messages: this._range(lo, hi), base: lo }
+  }
+
+  /** 方向流式迭代（read_history 用——'newest' 自尾向前 / 'oldest' 自首向后）。 */
+  *iterate(direction = "newest") {
+    const total = this.total()
+    if (total <= 0) return
+    const segs = []
+    for (let s = 1; s <= this._segCount; s++) segs.push(s)
+    const order = direction === "oldest" ? segs : [...segs].reverse()
+    for (const s of order) {
+      const lines = this._segmentLines(s)
+      const segBase = (s - 1) * RECORD_SEG_MESSAGES
+      for (let k = 0; k < lines.length; k++) {
+        const idx = direction === "oldest" ? segBase + k : segBase + (lines.length - 1 - k)
+        if (idx >= total) continue // 半行（末段未写完）不计
+        const msg = tryParse(lines[idx - segBase])
+        if (msg !== undefined) yield msg
+      }
+    }
+  }
+
+  /** 首条真实 user 消息（标题回退——首扫一次并缓存；生成器惰性：命中即停，不扫后续段）。 */
+  firstUserMessage() {
+    if (this._firstUser !== undefined) return this._firstUser
+    this._firstUser = null
+    for (const m of this.iterate("oldest")) {
+      if (isRealUserMsg(m)) { this._firstUser = m; break }
+    }
+    return this._firstUser
+  }
+
+  /** 槽摘要计数（manifest digest——不物化 history）：{total, userReal, firstMessage}。 */
+  counters() {
+    return { total: this.total(), userReal: this._counts.turnCount, firstMessage: this._counts.firstMessage }
+  }
+
+  /** 追加一条真实消息（§14.3.5 单点 = pushReal；同步；独立 try/catch——失败置 degraded + 停写）。 */
+  append(msg) {
+    if (!shouldAppend(msg)) return false
+    this.memTotal++
+    if (this.degraded) return false
+    try {
+      this._writeLine(msg)
+      return true
+    } catch (e) {
+      this.degraded = true
+      console.error(`[session] record store append failed (${e.message}) — writing stopped (SESSION.md §14.4 D-R4)`)
+      return false
+    }
+  }
+
+  /** 半行现场修复（写路径，代码评审 #1）：截掉末尾未写完的半行——恢复「物理行序 = 逻辑
+   *  序」不变式（读侧按计数索引；半行占位会使后续记录的物理位置与计数错位）。半行对应
+   *  的消息从未被确认（崩溃中止的写入）——丢弃即读侧「视为未写完、忽略」的落盘面。 */
+  _dropPartialTail() {
+    if (!this._partialSeg || this._partialSeg !== this._lastSegN) return
+    this._partialSeg = 0
+    this._lastSegCache = null
+    try {
+      const p = join(this.dir, segName(this._lastSegN))
+      const buf = readFileSync(p)
+      truncateSync(p, buf.lastIndexOf(0x0a) + 1) // −1（无完整行）→ 截为 0
+    } catch { /* 尽力面：截断失败仍按读侧半行容错跳过 */ }
+  }
+
+  /** 单条落盘（成功路径——失败向上抛，由 append/catchUp 统一处置）。 */
+  _writeLine(msg) {
+    mkdirSync(this.dir, { recursive: true })
+    this._dropPartialTail() // 先清末尾半行（若在）——防新记录与半行错位/粘连
+    // 身份固化：创建时为空 → 现场身份补写（只在跃迁时重写 meta——逐条追加不重复写）
+    const hadIdentity = this.identity != null
+    if (!hadIdentity && this.agent?._sessionStart) this.identity = this.agent._sessionStart
+    if (!this._metaReady || (!hadIdentity && this.identity != null)) {
+      this._writeMeta()
+      this._metaReady = true
+    }
+    if (this._lastSegN === 0) {
+      this._lastSegN = 1
+      this._lastSegLines = 0
+      this._segCount = 1
+    } else if (this._lastSegLines >= RECORD_SEG_MESSAGES) {
+      this._lastSegN++ // 轮转：末段满 segSize → 下一次追加新建下一段
+      this._lastSegLines = 0
+      this._segCount = this._lastSegN
+    }
+    appendFileSync(join(this.dir, segName(this._lastSegN)), JSON.stringify(slimForDisplay(msg)) + "\n", "utf8")
+    _storeStats.appendedEntries++
+    this._lastSegLines++
+    this._lastSegCache = null
+    this._countLine(msg)
+  }
+
+  _countLine(m) {
+    if (!isRealUserMsg(m)) return
+    this._counts.turnCount++
+    if (!this._sawRealUser) {
+      this._sawRealUser = true
+      this._counts.firstMessage = String(m.content).slice(0, 80)
+    }
+  }
+
+  /** D-R4② 追赶重试（保存时点）：缺口 ⊆ 窗口 → 重试追加；窗口已滑过缺口 → 不补写（不写洞）。 */
+  catchUp() {
+    if (!this.degraded) return true
+    _storeStats.catchUpRetries++
+    const gap = this.memTotal - this.total()
+    if (gap <= 0) { this.degraded = false; return true }
+    const win = (this.agent?._fullHistory ?? []).filter(shouldAppend)
+    if (gap > win.length) return false // 缺口已滑出窗口——保持降级（不写洞）
+    const missing = win.slice(win.length - gap)
+    try {
+      for (const m of missing) this._writeLine(m)
+    } catch (e) {
+      console.error(`[session] record store catch-up failed: ${e.message}`)
+      return false
+    }
+    this.degraded = false
+    return true
+  }
+
+  /** 降级置位（追赶失败——投影照 store 前缀 + meta.degraded 标记 + stderr 一行诊断）。 */
+  markDegraded() {
+    this.degraded = true
+    console.error("[session] record store degraded — projection written from the stored prefix; unflushed messages beyond the window are unrecoverable (SESSION.md §14.4 D-R4)")
+    this.syncMeta()
+  }
+}
+
+/** 绑定记录存储到 agent（`agent._recordStore`）+ 身份核验/对账 + 窗口置位（§14.3.4）。 */
+export function bindRecordStore(agent, { slotFile, identity = null, baseHistory = [] } = {}) {
+  const store = new RecordStore(slotFile)
+  store.bind(agent, identity, baseHistory)
+  agent._recordStore = store
+  agent._historyWindow = RECORD_WINDOW_MESSAGES
+  return store
+}
+
+/** 解绑（模式 F / /new 重置——内存窗口随之关闭，人读线回到全量数组语义）。 */
+export function unbindRecordStore(agent) {
+  agent._recordStore = null
+  agent._historyWindow = null
+}
+
+/** 删槽联动（deleteSlot / 冷前缀清理调用）。 */
+export function unlinkRecordStore(slotFile) {
+  try { rmSync(recordDirOf(slotFile), { recursive: true, force: true }) } catch { /* 尽力面 */ }
+}
+
+/**
+ * 槽 JSON 投影（流式拼接——§14.3.3 表 3 候选 1）：`history` = 各段原文拼接（峰值 O(单段)）；
+ * 原子写（.tmp + rename——与 writeSessionFile 同族）。降级态先追赶（D-R4②）。
+ */
+export function saveProjectedSlot(agent, p, fields, contextHistory) {
+  const store = agent?._recordStore
+  if (!store) return false
+  store.catchUp()
+  if (store.degraded) {
+    store.markDegraded()
+  } else {
+    if (store.identity == null && agent._sessionStart) store.identity = agent._sessionStart // 身份固化（规则 3）
+    store.syncMeta()
+  }
+  mkdirSync(dirname(p), { recursive: true })
+  const tmp = `${p}.tmp`
+  const fd = openSync(tmp, "w")
+  const w = (s) => writeSync(fd, s)
+  try {
+    w("{")
+    let first = true
+    for (const [k, v] of Object.entries(fields)) {
+      const encoded = v === undefined ? undefined : JSON.stringify(v)
+      if (encoded === undefined) continue // JSON.stringify 语义：undefined 字段省略（不产非法 JSON）
+      if (!first) w(",")
+      first = false
+      w(JSON.stringify(k) + ":" + encoded)
+    }
+    if (!first) w(",")
+    w(`${JSON.stringify("history")}:[`)
+    let wrote = false
+    for (let s = 1; s <= store._segCount; s++) {
+      let lines
+      try { lines = readSegmentLines(join(store.dir, segName(s))) } catch { lines = [] }
+      for (const line of lines) {
+        // 半行容忍（§14.3.2——读路径逐行容错）：崩溃在 append 中途留下的末尾半行/损坏行
+        // 不得拼进投影——否则槽 JSON 变成非法 JSON（下次 loadSlotFile 整体读不出）。
+        if (line === "" || tryParse(line) === undefined) continue
+        if (wrote) w(",")
+        wrote = true
+        w(line)
+      }
+    }
+    w("]")
+    w("," + JSON.stringify("contextHistory") + ":" + JSON.stringify(contextHistory ?? []))
+    w("}")
+  } finally {
+    try { closeSync(fd) } catch { /* ignore */ }
+  }
+  try {
+    renameSync(tmp, p)
+  } catch {
+    try { unlinkSync(p) } catch { /* missing is fine */ }
+    try {
+      renameSync(tmp, p)
+      try { unlinkSync(tmp) } catch { /* ignore */ }
+    } catch {
+      writeFileSync(p, readFileSync(tmp, "utf8"), "utf8")
+    }
+  }
+  return true
+}