@thincoder/core 0.9.5 → 0.10.2

package/config-watch.mjs

@@ -0,0 +1,83 @@
+/**
+ * config-watch.mjs — config.json 外部写盘感知·**纯逻辑面**（R8 · 桌面功能对位批「上提」KD-T2——
+ * 自 `thincoder-vscode/src/extension/config-watch.mjs:35-77` 逐字随迁：去抖 300ms ∕ stat 元组
+ * （`mtimeMs:size`）比对 ∕ 自写抑制；原批 = 第 21 批 B5 · `docs/design/SETTINGS.md` §2.6）。
+ *
+ * `~/.thincoder/config.json` 为多端共享单文件：CLI（`/advisor`、`settings set`）或手工编辑写盘后，
+ * 常开面板原本零感知（只在打开面板/保存时拉快照）。机制（零语义改）：
+ *   宿主 fs 事件 →（端落子）`onEvent` → 去抖 → 元组比对 → 变化才 `onChange`（事件驱动零空转）。
+ * 自写抑制：本端自身写盘同样改元组 ⇒ 裸推送会在用户编辑中被快照重建；写盘成功后核 `config-io`
+ * `saveRaw` 同步回调 `onConfigSelfWrite`（`config-io.mjs:107`）⇒ `noteSelfWrite()` 把基线刷到当前
+ * 元组 ⇒ 事件到达时元组已等于基线 ⇒ 零推送；外部写无回调 ⇒ 元组异于基线 ⇒ 推送。
+ *
+ * 平台面两注入（核内零宿主绑定）：① `attach`（fs 事件源工厂——端落子：VSC = `createFileSystemWatcher`、
+ * 桌面 = `node:fs.watch`）② `setTimer` ∕ `clearTimer`（定时器；缺省 = 全局）。`tupleOf`（stat 探针）缺省 =
+ * 本核 `statSync` 实现（两端宿主皆 Node）；`subscribeSelfWrite` 缺省 = 核自写订阅。
+ * 降级（无 path ∕ `attach` 缺失 ∕ 构造抛错 ∕ 返回空）⇒ no-op 面（不阻断端激活——面板打开拉新的既有路径兜底）。
+ * 装配序微差（对源件）：事件订阅随 `attach` 一次落（源件 = 构造 → 基线 → 订阅三事件）——订阅更早，
+ * 不丢事件；基线仍于 `attach` 后取（同步段内零窗口）。零语义差。
+ */
+import { statSync } from "node:fs"
+import { _configPath, onConfigSelfWrite } from "./config-io.mjs"
+
+/** stat 元组（mtimeMs + size——同 tick 快写 mtime 可同，size 兜底）；缺失 ∕ 不可读 ⇒ null。 */
+export function configTupleOf(path) {
+  try {
+    const s = statSync(path)
+    return `${s.mtimeMs}:${s.size}`
+  } catch { return null }
+}
+
+/**
+ * 建配置监视面（纯逻辑）。
+ * @param {{ configPath?: string, onChange?: () => void, debounceMs?: number,
+ *   attach?: (arg: { path: string, onEvent: () => void }) => { dispose?: () => void } | null,
+ *   tupleOf?: (path: string) => string | null,
+ *   setTimer?: (fn: () => void, ms: number) => unknown, clearTimer?: (handle: unknown) => void,
+ *   subscribeSelfWrite?: (fn: () => void) => (() => void) | void }} [opts]
+ *   `configPath` 缺省 = 核 `_configPath()` 当前值（测试缝同源）；`attach` = 平台落子（fs 事件源）。
+ * @returns {{ dispose: () => void, noteSelfWrite: () => void }} 降级时返回 no-op（不阻断激活）。
+ */
+export function createConfigWatch({
+  configPath, onChange, debounceMs = 300, attach, tupleOf = configTupleOf,
+  setTimer = setTimeout, clearTimer = clearTimeout, subscribeSelfWrite = onConfigSelfWrite,
+} = {}) {
+  const noop = { dispose() {}, noteSelfWrite() {} }
+  const path = configPath || _configPath()
+  if (!path) return noop
+  if (typeof attach !== "function") return noop
+
+  let baseline = null
+  let timer = null
+  /** 元组比对（去抖落点）：未变 → 零推送（隐藏 N5 判据保持）；变 ⇒ 基线刷新 + `onChange`（抛不炸宿主）。 */
+  const check = () => {
+    timer = null
+    const now = tupleOf(path)
+    if (now === baseline) return
+    baseline = now // 比对后基线更新为当前元组
+    try { onChange?.() } catch (e) { console.warn(`[config-watch] onChange failed: ${e.message}`) }
+  }
+  /** 去抖（同拍多事件合并——窗口内重排）。 */
+  const schedule = () => {
+    if (timer) clearTimer(timer)
+    timer = setTimer(check, debounceMs)
+  }
+
+  let listener
+  try { listener = attach({ path, onEvent: schedule }) } catch { return noop }
+  if (!listener) return noop
+  baseline = tupleOf(path)
+  const noteSelfWrite = () => { baseline = tupleOf(path) }
+
+  let unsubSelfWrite = null
+  try { unsubSelfWrite = subscribeSelfWrite(noteSelfWrite) } catch { /* 订阅失败仅弱化自写抑制 */ }
+
+  return {
+    noteSelfWrite,
+    dispose() {
+      try { listener.dispose?.() } catch { /* already disposed */ }
+      if (timer) { clearTimer(timer); timer = null }
+      try { unsubSelfWrite?.() } catch { /* ignore */ }
+    },
+  }
+}

package/config.mjs

@@ -13,7 +13,7 @@
 
 import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
 import { dirname, join } from "node:path"
-import { parseModelRef, resolveRuntimeProvider, defaultModelReason } from "./model-ref.mjs"
+import { parseModelRef, resolveChannelModel, resolveProviderPlan, resolveRuntimeProvider, defaultModelReason } from "./model-ref.mjs"
 // 老形态迁移核（M7 v2——纯函数零依赖——本文件超 500 行硬限拆分，VSC 同构文件）
 import { migrateLegacyModelFields } from "./config-migrate.mjs"
 import { expandHome } from "./expand-home.mjs"
@@ -23,7 +23,7 @@ import {
   _configPath, writeConfigAtomic,
 } from "./config-io.mjs"
 
-export { parseModelRef, resolveRuntimeProvider, defaultModelReason, migrateLegacyModelFields }
+export { parseModelRef, resolveChannelModel, resolveProviderPlan, resolveRuntimeProvider, defaultModelReason, migrateLegacyModelFields }
 export { PROVIDER_PRESETS, presetToEntry, configDir, configPath, _setConfigPathForTest, _resetConfigPathForTest }
 // 核内单一写盘执行体（已迁 `config-io.mjs`）——本档 re-export 保持既有导入面（§2.5 #131）。
 export { writeConfigAtomic }
@@ -48,7 +48,7 @@ export const DEFAULTS = {
     streamRules: [],      // time-traveling stream rules: [{ pattern: "regex", message: "reminder", action: "abort"|"warn", repeat: "always"|"once" }]
     advisor: { guard: false },  // code review is always available; guard: true pushes completion back until reviewed (opt-in). Also accepts provider/model/thinking/reasoningEffort/timeoutMs overrides. Deprecated: enabled (2026-08-21)
     autoThink: false,     // auto-classify task difficulty and set reasoning effort per-turn
-    engineering: false,   // strict methodology enforcement — design-before-code (design review + user approval before code)
+    engineering: false,   // initial default only — the runtime value is the session authority (MANIFEST.md §2.2 / ENGINEERING-MODE-V2.md §2.3 E5.1). Strict methodology enforcement — design-before-code (design review + user approval before code)
     // Async pool limits (AGENT-LOOP-ASYNC-POOL.md §6.10 D-24a/R14 + R13 — POOL-CONFIG-
     // UNIFIED 2026-09-09): { engCoder, other, advisor } — eng-coder pool / other-role
     // pool / advisor-review pool, defaults 4/4/4 (user ruling "eng-coder 四路，其他
@@ -61,6 +61,9 @@ export const DEFAULTS = {
     // ADVISOR_POOL_LIMIT 逐键同值（运行时回退常量）——耦合锚 T-24a4 断言锁住——
     // 勿单侧改默认。
     poolLimits: { engCoder: 4, other: 4, advisor: 4 },
+    // §6.30.3 门三件③（D-TW5）：timer 空闲自唤醒开关——默认开（工具描述面已承诺到点提醒）；
+    // false ⇒ 端侧不武装闩（回既有回合边界投递——零调度器面）。键面随 DEFAULTS 派生进 settings 类型表。
+    timerWake: true,
   },
   memory: {
     dbPath: join(configDir, "memory.db"),
@@ -83,6 +86,10 @@ export const DEFAULTS = {
     enabled: false,  // §18.6 D-TR6 修订（2026-09-05 用户裁定——发布隐私："不希望用户那边也采集"）：轨迹存档默认 OFF——新用户零采集；本地调试分析可显式开（~/.thincoder/config.json traces.enabled:true）
     retentionHours: 24, // D-TR10：轨迹文件保留小时数——CLI 启动时删除超过该时长的文件（默认 24h）
   },
+  // 诊断开关（用户面 ① 配置键——CONFIG.md §6.2 名录）：`heapWatch` 默认开（设 false 关闭）——自愈臂
+  // 遥测；`heapSnapshot` 默认关——采集 opt-in（堆转储敏感度 ≥ traces ⇒ 对齐发布隐私先例 D-TR6；
+  // 2026-09-30 采集收网批；桌面端运行期热读 ∥ CLI 本进程下次启动）
+  diagnostics: { heapWatch: true, heapSnapshot: false },
 }
 
 // Model capability table + spec lookup live in model-specs.mjs (2026-08-31
@@ -127,11 +134,12 @@ export function isBailianHost(baseURL) {
  *   provider.reasoningEffort   → true      (effort tier implies thinking on; rides with reasoning_effort)
  *   otherwise                  → undefined (field omitted — server default stays, no behavior change)
  * NOTE: spec carries no model field today — the name comes from provider.model (spec?.model is
- * a forward-compatible fallback). Keep the body byte-aligned with thincoder-vscode config.mjs
- * (cross-repo parity test compares them).
+ * a forward-compatible fallback). 非串 model（脏载 / 手工档）归一等价空串（未登记 ⇒ undefined）——
+ * 本函数恒 total、不因类型脏载抛（#638 查表族同归一）。
  */
 export function resolveEnableThinking(provider, spec) {
-  const model = (provider?.model ?? spec?.model ?? "").toLowerCase()
+  const raw = provider?.model ?? spec?.model ?? ""
+  const model = (typeof raw === "string" ? raw : "").toLowerCase()
   if (!model.startsWith("qwen") || model.startsWith("qwen3-coder")) return undefined
   if (!isBailianHost(provider?.baseURL)) return undefined
   if (provider.thinking === null) return false
@@ -257,6 +265,7 @@ export function loadConfig() {
     memory: { ...DEFAULTS.memory, ...config.memory },
     embedding: { ...DEFAULTS.embedding, ...config.embedding },
     traces: { ...DEFAULTS.traces, ...config.traces },
+    diagnostics: { ...DEFAULTS.diagnostics },
   }
 
   // 家目录展开（第 29 批）：config 路径字段单一规范化点——只读归一（磁盘原文保留）
@@ -268,6 +277,10 @@ export function loadConfig() {
   }
   merged.shell = expandHome(merged.shell)
 
+  // diagnostics（① 配置键，CONFIG.md §6.2 名录）：两键只认布尔值——非法 / 缺失回退默认（不 throw）
+  const _diagRaw = config.diagnostics && typeof config.diagnostics === "object" && !Array.isArray(config.diagnostics) ? config.diagnostics : {}
+  for (const key of ["heapWatch", "heapSnapshot"]) if (typeof _diagRaw[key] === "boolean") merged.diagnostics[key] = _diagRaw[key]
+
   // providers[].model 内存归一（v2 M3：非空字符串保留；非字符串/空串归一删除）——渠道默认模型
   // 单值；无默认模型合法（模型选择经 /models 拉取候选——准入判据见 M8/M9）。
   for (const p of merged.providers) {
@@ -312,14 +325,18 @@ export function loadConfig() {
   // 保证 agent.config.proxy 永远是规范形态或 undefined
   merged.proxy = normalizeProxy(merged.proxy)
 
-  // Runtime provider = config.defaultModel 复合解析（F-2——resolveRuntimeProvider）。
-  // 无效/未设 → {} + providerInvalidReason（D-S1 处置不 throw——make-agent 打 _providerInvalid
-  // 标记 → TUI 首帧弹选择 / headless 报可读错误；同 2026-09-02 Q1 语义——不复用 findProvider
-  // throw 契约——findProvider 保留给 advisor/run.mjs 等直接调用方）。
-  merged.provider = resolveRuntimeProvider(merged.providers, merged.defaultModel)
+  // Runtime provider = 统一解析（#841——resolveProviderPlan 单源：回退序 + 三态；PROVIDER.md §6.22）。
+  // 不可运行（渠表空 ∥ 全表无 key）⇒ {} + providerInvalidReason（D-S1 处置不 throw——make-agent 打
+  // _providerInvalid 标记 → TUI 首帧弹选择 / headless 报可读错误；同 2026-09-02 Q1 语义——不复用
+  // findProvider throw 契约——findProvider 保留给 advisor/run.mjs 等直接调用方）。
+  const plan = resolveProviderPlan({ providers: merged.providers, defaultModel: merged.defaultModel })
+  merged.provider = plan.provider
+  merged.providerState = plan.state // ok ∥ fallback ∥ invalid（三值闭集——KD-841-3 config 级）
+  merged.providerStateReason = plan.reason // state≠ok 时非空（语义源；消费者按 state 出词——禁串嗅探）
+  // providerInvalidReason 语义不变（provider 不完整时非空——装配校验 validateProvider 消费面照旧）
   merged.providerInvalidReason = merged.provider.name
     ? null
-    : defaultModelReason(merged.providers, merged.defaultModel)
+    : plan.reason ?? defaultModelReason(merged.providers, merged.defaultModel)
 
   // Compaction threshold follows the model (provider-level context override honored — providerSpec)
   const explicitThreshold = config.agent?.compactThreshold

package/context-degrade.mjs

@@ -0,0 +1,81 @@
+/**
+ * context-degrade.mjs — 确定性降级面（无 LLM 的有损收缩 · 自 `context.mjs` 迁出 · 2026-10-01 core 拆分批 #755 ∥ #786）。
+ * 内容 = `pruneStub` ∥ `pruneStaleToolOutputs`（F-CC3 陈旧工具输出清理）∥ `OVERSIZE_CONTENT_LIMIT` ∥
+ * `shrinkOversized`（splitHistory 无中间段时的单条超限收缩）——迁出块逐字。
+ * 原档 `context.mjs` 经 `export { … } from` 转口保名（消费面 / 批内件 import 面零改）；
+ * 跨档被引的原私有面（`shrinkOversized`）补 `export` 关键字。
+ */
+import { collectStaleToolOutputs } from "./token-window.mjs"
+
+/** prune stub 逐字（§6.16.3）：只给「已清理 + 原长度 + 重跑路径」——prune 是**删**不是摘要，不声称可复原。 */
+const pruneStub = (chars) => `[pruned: stale tool output dropped (${chars} chars) — re-run the tool if you need it again.]`
+
+/**
+ * 陈旧工具输出清理（F-CC3 · §6.16.3）：合格集 = `token-window.mjs` 单源（保护尾外 ∧ `role:"tool"` ∧ ≥ 门槛）；
+ * 命中项**原位换「内容」**（`history[i] = { ...m, content: stub }`——数组引用 / 长度 / 索引 / `tool_call_id` 全不变
+ * ⇒ 配对**结构上不可能被拆**）。记录面零改（copy-on-write：消息对象与人读线共享）；基线失效同 `shrinkOversized` 先例。
+ * @returns {{pruned:number, freed:number, candidates:number, tailKept:number, belowMin:number}}
+ */
+export function pruneStaleToolOutputs(agent) {
+  const history = agent.history
+  const stale = collectStaleToolOutputs(history, agent.provider)
+  const counts = {
+    pruned: stale.indexes.length,
+    freed: stale.tokens,
+    candidates: stale.candidates,
+    tailKept: stale.tailKept,
+    belowMin: stale.belowMin,
+  }
+  if (counts.pruned === 0) return counts
+  for (const i of stale.indexes) {
+    const m = history[i]
+    // 多模态 tool 结果（content 数组）整体替换为 stub ⇒ 图像 part 丢弃（不可再取——prune 是删；回执只给重跑路径）
+    const chars = typeof m.content === "string" ? m.content.length : JSON.stringify(m.content ?? "").length
+    history[i] = { ...m, content: pruneStub(chars) }
+  }
+  agent._lastPromptTokens = null
+  agent._usageAtLen = null
+  return counts
+}
+
+/** Hard truncation limit for a single message body: when exceeded and the splitter can't find a middle section, truncate to a stub (prevents one giant message from blocking compaction) */
+const OVERSIZE_CONTENT_LIMIT = 8_000
+
+/**
+ * Deterministic shrinking: last resort when splitHistory can't find a middle section (history too short) but threshold is exceeded. No LLM call.
+ * Truncates user/tool message bodies exceeding OVERSIZE_CONTENT_LIMIT to a stub (keeps head + tail);
+ * does not touch reasoning_content (DeepSeek/Kimi echo protocol) or tool_calls pairing structure — no protocol 400
+ * risk from this path (this module's echo-safety face is `applyCompression`: the compaction placeholder is never
+ * committed as a separate reasoning-less assistant next to another assistant — D-CC18, 2026-09-16 batch).
+ * Only called after compressIfNeeded determines threshold is exceeded. Returns whether any message was truncated.
+ */
+export function shrinkOversized(agent, limit = OVERSIZE_CONTENT_LIMIT) {
+  let shrunk = false
+  // Copy-on-write: build a NEW array and replace only truncated entries. pushReal stores the SAME
+  // message object in both `agent.history` (machine line) and `agent._fullHistory` (human/persistence
+  // line), so in-place `m.content = ...` would ALSO truncate the never-compacted human line and lose
+  // the original pasted content on session persist (session.mjs persists _fullHistory). VS Code port
+  // already copies (`history.map(m => ({ ...m }))`); this brings CLI to parity.
+  const next = agent.history.map((m) => {
+    if ((m.role !== "user" && m.role !== "tool") || typeof m.content !== "string") return m
+    if (m.content.length <= limit) return m
+    // Truncate keeping head + tail, insert stub in between; keepHead/keepTail proportional but not exceeding 50%/25% of limit
+    const keepHead = Math.min(Math.floor(limit * 0.5), 4000)
+    const keepTail = Math.min(Math.floor(limit * 0.25), 2000)
+    shrunk = true
+    return {
+      ...m,
+      content:
+        m.content.slice(0, keepHead) +
+        `\n[... ${m.content.length - keepHead - keepTail} chars truncated — single message too large for context window ...]\n` +
+        m.content.slice(-keepTail),
+    }
+  })
+  if (shrunk) {
+    agent.history = next
+    // Same as compaction: measured token baseline is invalidated by the changed history, fall back to estimation until next response
+    agent._lastPromptTokens = null
+    agent._usageAtLen = null
+  }
+  return shrunk
+}

package/context-echo.mjs

@@ -0,0 +1,88 @@
+/**
+ * context-echo.mjs — 回声安全面（D-CC18 ∥ D-CC19 恢复面归并 · 自 `context.mjs` 迁出 · 2026-10-01 core 拆分批 #755 ∥ #786）。
+ * 内容 = `COMPACTION_PLACEHOLDER` ∥ 前缀器族（`prefixContent` / `withPlaceholderPrefix`）∥ 回声对归并
+ * （`isAssistantEchoPair` / `contentTextOf` / `absorbEchoContent` / `mergeAdjacentAssistantEchoes`）——迁出块逐字。
+ * 原档 `context.mjs` 经 `export { … } from` 转口保名（消费面 / 批内件 import 面零改）；
+ * 跨档被引的原私有面（`COMPACTION_PLACEHOLDER` ∥ `withPlaceholderPrefix`）补 `export` 关键字。
+ */
+
+/** Placeholder assistant reply committed right after compaction (D9); D-CC18 merges it into an adjacent tail assistant instead of emitting it as a separate message */
+export const COMPACTION_PLACEHOLDER = "Understood. I'll continue from these notes, re-verifying anything transient."
+
+/**
+ * Content-shape-safe prefixing (D-CC18, generalized for D-CC19 merge reuse):
+ * string → text + blank line + original; multimodal array → text part prepended;
+ * empty string / null / undefined / other → text alone.
+ */
+function prefixContent(content, text) {
+  if (typeof content === "string" && content.length > 0) return `${text}\n\n${content}`
+  if (Array.isArray(content)) return [{ type: "text", text }, ...content]
+  return text
+}
+
+/**
+ * D-CC18 echo safety: prefix the placeholder onto an existing assistant message's content.
+ * Thin wrapper over prefixContent (behavioral semantics unchanged).
+ */
+export function withPlaceholderPrefix(content) {
+  return prefixContent(content, COMPACTION_PLACEHOLDER)
+}
+
+/**
+ * D-CC19 restore-path echo merge (2026-09-16 ENGINE-DEBT 批 ED-1): persisted `contextHistory`
+ * is loaded back VERBATIM on session restore, so the D-CC18 pathological shape (an assistant
+ * WITHOUT reasoning_content directly followed by another assistant — DeepSeek-family thinking
+ * mode rejects the first request with 400) can revive from disk. Pure in-core function: scans
+ * only at restore time, never prompts the user, never rewrites the session file. Merge direction
+ * matches D-CC18 (the reasoning-less message is absorbed INTO its follower — the follower's
+ * tool_calls / reasoning_content / other fields are kept verbatim; texts joined with a blank
+ * line). Iterates to a fixed point (chains collapse in full). Copy-on-write: messages may be
+ * shared with other lines, so the merged message is always a NEW object; clean input returns
+ * the SAME array reference (zero copy).
+ */
+
+/** Pair predicate: prev = assistant with no/empty reasoning_content and no tool_calls,
+ * directly followed by another assistant. (Prev WITH tool_calls is never merged — pairing
+ * safety, F-3.) */
+export function isAssistantEchoPair(prev, next) {
+  return prev?.role === "assistant"
+    && next?.role === "assistant"
+    && !prev.reasoning_content
+    && !(Array.isArray(prev.tool_calls) && prev.tool_calls.length > 0)
+}
+
+/** Text of a message content in any supported shape (string / parts array / null-ish). */
+function contentTextOf(content) {
+  if (typeof content === "string") return content
+  if (Array.isArray(content)) {
+    return content.filter((p) => p?.type === "text").map((p) => p.text ?? "").join("\n\n")
+  }
+  return ""
+}
+
+/** Absorb prev's text into next's content (blank-line join; empty prev text → next unchanged). */
+function absorbEchoContent(prevContent, nextContent) {
+  const text = contentTextOf(prevContent)
+  if (text.length === 0) return nextContent
+  return prefixContent(nextContent, text)
+}
+
+export function mergeAdjacentAssistantEchoes(history) {
+  if (!Array.isArray(history)) return history
+  let src = history
+  for (;;) {
+    let changed = false
+    const next = []
+    for (let i = 0; i < src.length; i++) {
+      if (i + 1 < src.length && isAssistantEchoPair(src[i], src[i + 1])) {
+        next.push({ ...src[i + 1], content: absorbEchoContent(src[i].content, src[i + 1].content) })
+        i += 1
+        changed = true
+      } else {
+        next.push(src[i])
+      }
+    }
+    if (!changed) return src === history ? history : src
+    src = next
+  }
+}

package/context-push.mjs

@@ -0,0 +1,51 @@
+/**
+ * context-push.mjs — 消息双线写入单点（写缝面 · 自 `context.mjs` 迁出 · 2026-10-01 core 拆分批 #755 ∥ #786）。
+ * `pushReal` = 真实消息写缝（机器线 `agent.history` + 人读线 `agent._fullHistory` 同源双写）；
+ * `pushRecord` = 人读线留档记录单点（机器线零触）。迁出块逐字；原档 `context.mjs` 经
+ * `export { … } from` 转口保名（消费面 / 批内件 import 面零改）。
+ */
+
+/**
+ * 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 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.
+ * Message timestamps (SESSION.md §6.9): stamped HERE once at push time (epoch ms) — a single
+ * 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 §6.14）——人读线内存有界 + 磁盘为准：
+ *   ① `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)
+}
+
+/**
+ * pushRecord — 人读线留档记录单点（消化生命周期面 · #726；形 ∥ 写缝 ∥ 判据单源 = SESSION.md §6.26）。
+ * `pushReal` 双胞（直复用——零算法副本）：`ts` 打点 ∥ 记录存储追加（`_recordStore?.append`——§6.14）∥
+ * 尾窗驱逐三面同源；**机器线零触** = `history` 以一次性弃数组承接 ⇒ 记录不入 `agent.history` /
+ * `contextHistory`（不喂模型）。未绑定（`_recordStore` 缺）⇒ 人读线追加照常 ∥ 存储腿空转（零抛——模式 F
+ * 零回归）；载体缺位（无活跃会话）⇒ 零动作（零抛——日志归端侧）。
+ */
+export function pushRecord(agent, record) {
+  if (!agent || typeof agent !== "object") return // 载体缺位：零动作（零抛——§6.26 失败面）
+  if (!Array.isArray(agent._fullHistory)) agent._fullHistory = []
+  // 载体形人读线半提取（先例 = 桌面 `session-io.appendRecord`）：`history` 弃数组承接 ⇒ 机器线零触
+  pushReal({ _fullHistory: agent._fullHistory, _recordStore: agent._recordStore, _historyWindow: agent._historyWindow, history: [] }, record)
+}

package/context.mjs

@@ -13,7 +13,9 @@
 
 import { chat } from "./provider/index.mjs"
 import { buildCompressMessages } from "./compress-form.mjs"
-import { contextUsage, estimateTokens, collectStaleToolOutputs, keepTailSize, splitHistory, tailBudgetTokens } from "./token-window.mjs"
+import { contextUsage, estimateTokens, keepTailSize, splitHistory, tailBudgetTokens } from "./token-window.mjs"
+import { COMPACTION_PLACEHOLDER, withPlaceholderPrefix } from "./context-echo.mjs"
+import { shrinkOversized } from "./context-degrade.mjs"
 
 export const SUMMARIZE_PROMPT = `The conversation above is our work log so far — summarize it into a compact summary for use as context in the ongoing conversation.
 Requirements:
@@ -34,9 +36,6 @@ const COMPACTION_PREFIX =
   "Treat it as notes, not proof — trust its conclusions (don't redo what it reports as done) " +
   "but re-verify transient state with tools. Check memory search for any missing decisions.]\n\n"
 
-/** Placeholder assistant reply committed right after compaction (D9); D-CC18 merges it into an adjacent tail assistant instead of emitting it as a separate message */
-const COMPACTION_PLACEHOLDER = "Understood. I'll continue from these notes, re-verifying anything transient."
-
 /** After this many consecutive compaction summary failures, degrade to deterministic truncation (losing info is better than task-killing 400 errors) */
 export const COMPRESS_FAILURE_LIMIT = 3
 
@@ -71,115 +70,6 @@ function anchorText(agent) {
   return lines.length > 0 ? lines.join("\n") : null
 }
 
-/**
- * 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 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.
- * Message timestamps (SESSION.md §6.9): stamped HERE once at push time (epoch ms) — a single
- * 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 §6.14）——人读线内存有界 + 磁盘为准：
- *   ① `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)
-}
-
-/**
- * Content-shape-safe prefixing (D-CC18, generalized for D-CC19 merge reuse):
- * string → text + blank line + original; multimodal array → text part prepended;
- * empty string / null / undefined / other → text alone.
- */
-function prefixContent(content, text) {
-  if (typeof content === "string" && content.length > 0) return `${text}\n\n${content}`
-  if (Array.isArray(content)) return [{ type: "text", text }, ...content]
-  return text
-}
-
-/**
- * D-CC18 echo safety: prefix the placeholder onto an existing assistant message's content.
- * Thin wrapper over prefixContent (behavioral semantics unchanged).
- */
-function withPlaceholderPrefix(content) {
-  return prefixContent(content, COMPACTION_PLACEHOLDER)
-}
-
-/**
- * D-CC19 restore-path echo merge (2026-09-16 ENGINE-DEBT 批 ED-1): persisted `contextHistory`
- * is loaded back VERBATIM on session restore, so the D-CC18 pathological shape (an assistant
- * WITHOUT reasoning_content directly followed by another assistant — DeepSeek-family thinking
- * mode rejects the first request with 400) can revive from disk. Pure in-core function: scans
- * only at restore time, never prompts the user, never rewrites the session file. Merge direction
- * matches D-CC18 (the reasoning-less message is absorbed INTO its follower — the follower's
- * tool_calls / reasoning_content / other fields are kept verbatim; texts joined with a blank
- * line). Iterates to a fixed point (chains collapse in full). Copy-on-write: messages may be
- * shared with other lines, so the merged message is always a NEW object; clean input returns
- * the SAME array reference (zero copy).
- */
-
-/** Pair predicate: prev = assistant with no/empty reasoning_content and no tool_calls,
- * directly followed by another assistant. (Prev WITH tool_calls is never merged — pairing
- * safety, F-3.) */
-export function isAssistantEchoPair(prev, next) {
-  return prev?.role === "assistant"
-    && next?.role === "assistant"
-    && !prev.reasoning_content
-    && !(Array.isArray(prev.tool_calls) && prev.tool_calls.length > 0)
-}
-
-/** Text of a message content in any supported shape (string / parts array / null-ish). */
-function contentTextOf(content) {
-  if (typeof content === "string") return content
-  if (Array.isArray(content)) {
-    return content.filter((p) => p?.type === "text").map((p) => p.text ?? "").join("\n\n")
-  }
-  return ""
-}
-
-/** Absorb prev's text into next's content (blank-line join; empty prev text → next unchanged). */
-function absorbEchoContent(prevContent, nextContent) {
-  const text = contentTextOf(prevContent)
-  if (text.length === 0) return nextContent
-  return prefixContent(nextContent, text)
-}
-
-export function mergeAdjacentAssistantEchoes(history) {
-  if (!Array.isArray(history)) return history
-  let src = history
-  for (;;) {
-    let changed = false
-    const next = []
-    for (let i = 0; i < src.length; i++) {
-      if (i + 1 < src.length && isAssistantEchoPair(src[i], src[i + 1])) {
-        next.push({ ...src[i + 1], content: absorbEchoContent(src[i].content, src[i + 1].content) })
-        i += 1
-        changed = true
-      } else {
-        next.push(src[i])
-      }
-    }
-    if (!changed) return src === history ? history : src
-    src = next
-  }
-}
-
 /** Replace middle with a note, then re-inject task/plan state (shared by LLM summary and truncation fallback) */
 function applyCompression(agent, headEnd, tailStart, note) {
   // _fullHistory already holds every real message (written at the source via pushReal),
@@ -314,7 +204,7 @@ export async function compressIfNeeded(agent, threshold, callbacks, extras = {},
     messages,
     tools: extras?.tools,
     signal,
-    // §18.6 D-TR4：轨迹元数据增补——kind=compress（上下文构建面——agent 元数据透出；
+    // TRACES.md §6.1 D-TR4：轨迹元数据增补——kind=compress（上下文构建面——agent 元数据透出；
     // depth 经 extras.traceDepth——agent.mjs 主作用域传入——compress 调用点补齐）
     logCtx: {
       stage: "compress", child: agent._logId, kind: "compress",
@@ -342,37 +232,6 @@ export async function compressIfNeeded(agent, threshold, callbacks, extras = {},
   return true
 }
 
-/** prune stub 逐字（§6.16.3）：只给「已清理 + 原长度 + 重跑路径」——prune 是**删**不是摘要，不声称可复原。 */
-const pruneStub = (chars) => `[pruned: stale tool output dropped (${chars} chars) — re-run the tool if you need it again.]`
-
-/**
- * 陈旧工具输出清理（F-CC3 · §6.16.3）：合格集 = `token-window.mjs` 单源（保护尾外 ∧ `role:"tool"` ∧ ≥ 门槛）；
- * 命中项**原位换「内容」**（`history[i] = { ...m, content: stub }`——数组引用 / 长度 / 索引 / `tool_call_id` 全不变
- * ⇒ 配对**结构上不可能被拆**）。记录面零改（copy-on-write：消息对象与人读线共享）；基线失效同 `shrinkOversized` 先例。
- * @returns {{pruned:number, freed:number, candidates:number, tailKept:number, belowMin:number}}
- */
-export function pruneStaleToolOutputs(agent) {
-  const history = agent.history
-  const stale = collectStaleToolOutputs(history, agent.provider)
-  const counts = {
-    pruned: stale.indexes.length,
-    freed: stale.tokens,
-    candidates: stale.candidates,
-    tailKept: stale.tailKept,
-    belowMin: stale.belowMin,
-  }
-  if (counts.pruned === 0) return counts
-  for (const i of stale.indexes) {
-    const m = history[i]
-    // 多模态 tool 结果（content 数组）整体替换为 stub ⇒ 图像 part 丢弃（不可再取——prune 是删；回执只给重跑路径）
-    const chars = typeof m.content === "string" ? m.content.length : JSON.stringify(m.content ?? "").length
-    history[i] = { ...m, content: pruneStub(chars) }
-  }
-  agent._lastPromptTokens = null
-  agent._usageAtLen = null
-  return counts
-}
-
 /**
  * Deterministic truncation fallback: called when the summary LLM fails repeatedly, no network call.
  * Drops the middle so the task can continue. Returns whether truncation happened.
@@ -389,50 +248,12 @@ export function compressFallback(agent) {
   return true
 }
 
-/** Hard truncation limit for a single message body: when exceeded and the splitter can't find a middle section, truncate to a stub (prevents one giant message from blocking compaction) */
-const OVERSIZE_CONTENT_LIMIT = 8_000
-
-/**
- * Deterministic shrinking: last resort when splitHistory can't find a middle section (history too short) but threshold is exceeded. No LLM call.
- * Truncates user/tool message bodies exceeding OVERSIZE_CONTENT_LIMIT to a stub (keeps head + tail);
- * does not touch reasoning_content (DeepSeek/Kimi echo protocol) or tool_calls pairing structure — no protocol 400
- * risk from this path (this module's echo-safety face is `applyCompression`: the compaction placeholder is never
- * committed as a separate reasoning-less assistant next to another assistant — D-CC18, 2026-09-16 batch).
- * Only called after compressIfNeeded determines threshold is exceeded. Returns whether any message was truncated.
- */
-function shrinkOversized(agent, limit = OVERSIZE_CONTENT_LIMIT) {
-  let shrunk = false
-  // Copy-on-write: build a NEW array and replace only truncated entries. pushReal stores the SAME
-  // message object in both `agent.history` (machine line) and `agent._fullHistory` (human/persistence
-  // line), so in-place `m.content = ...` would ALSO truncate the never-compacted human line and lose
-  // the original pasted content on session persist (session.mjs persists _fullHistory). VS Code port
-  // already copies (`history.map(m => ({ ...m }))`); this brings CLI to parity.
-  const next = agent.history.map((m) => {
-    if ((m.role !== "user" && m.role !== "tool") || typeof m.content !== "string") return m
-    if (m.content.length <= limit) return m
-    // Truncate keeping head + tail, insert stub in between; keepHead/keepTail proportional but not exceeding 50%/25% of limit
-    const keepHead = Math.min(Math.floor(limit * 0.5), 4000)
-    const keepTail = Math.min(Math.floor(limit * 0.25), 2000)
-    shrunk = true
-    return {
-      ...m,
-      content:
-        m.content.slice(0, keepHead) +
-        `\n[... ${m.content.length - keepHead - keepTail} chars truncated — single message too large for context window ...]\n` +
-        m.content.slice(-keepTail),
-    }
-  })
-  if (shrunk) {
-    agent.history = next
-    // Same as compaction: measured token baseline is invalidated by the changed history, fall back to estimation until next response
-    agent._lastPromptTokens = null
-    agent._usageAtLen = null
-  }
-  return shrunk
-}
-
 // ─── 迁出面（import 面保持：TUI / verify-compress / VSC 对拍经本档取——先例 = 下方 explore-distill 再导出）──
 export { estimateTokens }
+// ─── 拆分转口（2026-10-01 拆分批 · #755 ∥ #786）：写缝 ∥ 回声 ∥ 降级三面外提——消费面 / 批内件 import 面零改 ───
+export { pushReal, pushRecord } from "./context-push.mjs"
+export { isAssistantEchoPair, mergeAdjacentAssistantEchoes } from "./context-echo.mjs"
+export { pruneStaleToolOutputs } from "./context-degrade.mjs"
 // ─── 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））───────────────────────