@thincoder/core 0.10.13 → 0.11.1

package/agent/helpers.mjs

@@ -1,13 +1,12 @@
 /**
  * agent/helpers.mjs — Agent utility functions and constants
  */
-import { configDir } from "../config.mjs"
 import { readFileSync, readdirSync } from "node:fs"
 import { homedir } from "node:os"
-import { writeFile, mkdir, readdir, stat, unlink } from "node:fs/promises"
 import { join } from "node:path"
 import { execFile } from "node:child_process"
 import { promisify } from "node:util"
+export { offloadToolResult, cleanupOldToolResults, TMP_RETENTION_MS } from "./offload.mjs"
 
 /** Single source for the AUTO-mode reminder (was duplicated in agent.mjs +
  *  setup.mjs — consult P2, 2026-08-30). */
@@ -33,52 +32,6 @@ export const REPORT_CONTINUATION =
   "3. How you verified (tests run, commands executed, with results)\n" +
   "4. Anything left undone or worth follow-up"
 
-const TOOL_RESULT_OFFLOAD_LIMIT = 64 * 1024 // 65536 chars — offload only above 64K (2026-08-24)
-const TOOL_RESULT_PREVIEW = 64 * 1024 // total preview budget: head + middle note + tail ≤ 65536 (aligns with CLI/VS Code webview)
-const TOOL_RESULT_PREVIEW_HEAD = 16 * 1024 // head slice preserved (2026-09-04 §5 — dual-end preview)
-const TOOL_RESULT_PREVIEW_TAIL = 48 * 1024 // nominal tail slice (results/errors/stats live here — actual tail = budget remainder, see buildDualEndPreview)
-
-/** UTF-16 安全截断（2026-09-02 deepseek 400 根因）：slice(0, N) 按码元切会把 emoji 代理对切成孤立
- *  高代理（如 🔴=U+D83D+DD34 只剩 D83D）——deepseek 解析器严格 UTF-16 报 400
- *  "unexpected end of hex escape"。截断点落在高代理上时向前收一个码元。
- *  与 setup.mjs 的 safeSliceUTF16 同语义（两处独立实现——escape.mjs 的 sanitizeLoneSurrogates 是发送兜底，此处是源头）。 */
-function safeSliceUTF16(text, max) {
-  if (text.length <= max) return text
-  const cp = text.charCodeAt(max - 1)
-  if (cp >= 0xd800 && cp <= 0xdbff) return text.slice(0, max - 1)
-  return text.slice(0, max)
-}
-
-/** UTF-16 safe END slice (2026-09-04 §5 dual-end preview — review #5: both boundaries must not split
- *  a surrogate pair). Same rule as safeSliceUTF16, mirrored: if the slice START lands on a LOW
- *  surrogate (DC00-DFFF — the second half of a pair whose high half sits just before the boundary),
- *  advance one code unit so the slice never begins with an orphan low surrogate. */
-function safeSliceUTF16End(text, max) {
-  if (text.length <= max) return text
-  const start = text.length - max
-  const cp = text.charCodeAt(start)
-  if (cp >= 0xdc00 && cp <= 0xdfff) return text.slice(start + 1)
-  return text.slice(start)
-}
-
-/** Dual-end preview (design §5 D-4.1): head + middle-omitted note + tail — the tail carries
- *  results/errors/stats that a pure-head truncation would cut off.
- *  Budget (round1 review #2, fixed): head + note + tail ≤ TOOL_RESULT_PREVIEW (65536) — tail is
- *  computed from constants (tail = TOOL_RESULT_PREVIEW − head − noteLen), never hardcoded.
- *  The note length depends on the omitted digit count; text.length's digit count is an upper bound
- *  for omitted (< text.length), so budgeting with it keeps the total ≤ 65536 while the printed
- *  note reports the actual omitted count. Both boundaries run surrogate-safe slices (review #5). */
-function buildDualEndPreview(text) {
-  const head = safeSliceUTF16(text, TOOL_RESULT_PREVIEW_HEAD)
-  const noteFn = (omitted) => `\n\n… [middle omitted: ${omitted} chars] …\n\n`
-  const tailLen = Math.min(TOOL_RESULT_PREVIEW_TAIL, TOOL_RESULT_PREVIEW - TOOL_RESULT_PREVIEW_HEAD - noteFn(text.length).length)
-  const tail = safeSliceUTF16End(text, tailLen)
-  return head + noteFn(Math.max(0, text.length - head.length - tail.length)) + tail
-}
-
-/** Offload-dir write-time self-cleanup retention window (2026-08-21): files older than 3 days are deleted on the next offload. */
-export const TMP_RETENTION_MS = 3 * 24 * 3600 * 1000
-
 const GIT_TIMEOUT_MS = 5000
 const MAX_GIT_CHANGES_DISPLAY = 20
 
@@ -127,52 +80,6 @@ export function tryCanonicalize(name, args) {
   try { return name + ":" + JSON.stringify(JSON.parse(args)) } catch { return name + ":" + args }
 }
 
-/**
- * Best-effort write-time self-cleanup: delete files in dir whose mtime exceeds TMP_RETENTION_MS.
- * Subdirectories are never touched; every failure is silent — cleanup must not affect offload.
- */
-export async function cleanupOldToolResults(dir) {
-  const now = Date.now()
-  let entries
-  try {
-    entries = await readdir(dir, { withFileTypes: true })
-  } catch {
-    return // dir missing or unreadable → nothing to clean
-  }
-  for (const entry of entries) {
-    if (!entry.isFile()) continue // subdirectories untouched
-    try {
-      const st = await stat(join(dir, entry.name))
-      if (now - st.mtimeMs > TMP_RETENTION_MS) await unlink(join(dir, entry.name))
-    } catch {
-      /* entry vanished concurrently or I/O error — best effort, keep going */
-    }
-  }
-}
-
-/** Offload a tool result / report to disk (§2.2): `force` = write regardless of size (async
- *  subagent reports must survive the parent turn). Rendering splits on the SAME constant as the old
- *  gate: ≤ TOOL_RESULT_OFFLOAD_LIMIT ⇒ body once + path (never dual-end — a short body would come
- *  out twice with `middle omitted: 0 chars`); > ⇒ dual-end preview + path. Writes self-clean first. */
-export async function offloadToolResult(text, callId, dir = join(configDir, "tool-results"), { force = false } = {}) {
-  const overLimit = text.length > TOOL_RESULT_OFFLOAD_LIMIT
-  if (!force && !overLimit) return text
-  try {
-    await cleanupOldToolResults(dir)
-    await mkdir(dir, { recursive: true })
-    const file = join(dir, `${Date.now()}-${String(callId).replace(/[^a-zA-Z0-9_-]/g, "_")}.log`)
-    await writeFile(file, text, "utf8")
-    if (!overLimit) return `${text}\n\n[... full content saved to: ${file}\nPage through it with the read tool (offset/limit) if you need the full text later.]`
-    return buildDualEndPreview(text) + `\n\n[... output too large (${text.length} chars total), full content saved to: ${file}\n` +
-      `Page through it with the read tool (offset/limit) or sed -n 'START,ENDp' — do NOT re-run the tool blindly.]`
-  } catch {
-    // 写盘失败不吞报告：>LIMIT 走双端预览 + 原文案；≤LIMIT 正文整段在前（不谎称 truncated）
-    const body = overLimit ? buildDualEndPreview(text) : text
-    return body + (overLimit ? `\n\n[... truncated: ${text.length} chars total, offload to disk failed]`
-      : `\n\n[... full text kept inline above (${text.length} chars), offload to disk failed]`)
-  }
-}
-
 // 失败冷却 v1（用户裁——GIT-ASYNC L21）：真失败/超时后 30s 内跳过该 cwd 的收集——
 // 病态 repo 周期拖慢变一次性。VSC setup-reminders.mjs 同构镜像。
 const GIT_FAILURE_COOLDOWN_MS = 30_000

package/agent/offload.mjs

@@ -0,0 +1,88 @@
+/**
+ * agent/offload.mjs — 一次「把超长正文落到盘上、把注入体压成预览 + 路径」：门限常量 → 两端安全切片 → 预览拼装 → 落盘 → 写时自清理。
+ */
+import { configDir } from "../config.mjs"
+import { writeFile, mkdir, readdir, stat, unlink } from "node:fs/promises"
+import { join } from "node:path"
+import { safeSliceUTF16 } from "../text-budget.mjs"
+
+const TOOL_RESULT_OFFLOAD_LIMIT = 64 * 1024 // 65536 chars — offload only above 64K (2026-08-24)
+const TOOL_RESULT_PREVIEW = 64 * 1024 // total preview budget: head + middle note + tail ≤ 65536 (aligns with CLI/VS Code webview)
+const TOOL_RESULT_PREVIEW_HEAD = 16 * 1024 // head slice preserved (2026-09-04 §5 — dual-end preview)
+const TOOL_RESULT_PREVIEW_TAIL = 48 * 1024 // nominal tail slice (results/errors/stats live here — actual tail = budget remainder, see buildDualEndPreview)
+
+/** UTF-16 safe END slice (2026-09-04 §5 dual-end preview — review #5: both boundaries must not split
+ *  a surrogate pair). Same rule as safeSliceUTF16, mirrored: if the slice START lands on a LOW
+ *  surrogate (DC00-DFFF — the second half of a pair whose high half sits just before the boundary),
+ *  advance one code unit so the slice never begins with an orphan low surrogate. */
+function safeSliceUTF16End(text, max) {
+  if (text.length <= max) return text
+  const start = text.length - max
+  const cp = text.charCodeAt(start)
+  if (cp >= 0xdc00 && cp <= 0xdfff) return text.slice(start + 1)
+  return text.slice(start)
+}
+
+/** Dual-end preview (design §5 D-4.1): head + middle-omitted note + tail — the tail carries
+ *  results/errors/stats that a pure-head truncation would cut off.
+ *  Budget (round1 review #2, fixed): head + note + tail ≤ TOOL_RESULT_PREVIEW (65536) — tail is
+ *  computed from constants (tail = TOOL_RESULT_PREVIEW − head − noteLen), never hardcoded.
+ *  The note length depends on the omitted digit count; text.length's digit count is an upper bound
+ *  for omitted (< text.length), so budgeting with it keeps the total ≤ 65536 while the printed
+ *  note reports the actual omitted count. Both boundaries run surrogate-safe slices (review #5). */
+function buildDualEndPreview(text) {
+  const head = safeSliceUTF16(text, TOOL_RESULT_PREVIEW_HEAD)
+  const noteFn = (omitted) => `\n\n… [middle omitted: ${omitted} chars] …\n\n`
+  const tailLen = Math.min(TOOL_RESULT_PREVIEW_TAIL, TOOL_RESULT_PREVIEW - TOOL_RESULT_PREVIEW_HEAD - noteFn(text.length).length)
+  const tail = safeSliceUTF16End(text, tailLen)
+  return head + noteFn(Math.max(0, text.length - head.length - tail.length)) + tail
+}
+
+/** Offload-dir write-time self-cleanup retention window (2026-08-21): files older than 3 days are deleted on the next offload. */
+export const TMP_RETENTION_MS = 3 * 24 * 3600 * 1000
+
+/**
+ * Best-effort write-time self-cleanup: delete files in dir whose mtime exceeds TMP_RETENTION_MS.
+ * Subdirectories are never touched; every failure is silent — cleanup must not affect offload.
+ */
+export async function cleanupOldToolResults(dir) {
+  const now = Date.now()
+  let entries
+  try {
+    entries = await readdir(dir, { withFileTypes: true })
+  } catch {
+    return // dir missing or unreadable → nothing to clean
+  }
+  for (const entry of entries) {
+    if (!entry.isFile()) continue // subdirectories untouched
+    try {
+      const st = await stat(join(dir, entry.name))
+      if (now - st.mtimeMs > TMP_RETENTION_MS) await unlink(join(dir, entry.name))
+    } catch {
+      /* entry vanished concurrently or I/O error — best effort, keep going */
+    }
+  }
+}
+
+/** Offload a tool result / report to disk (§2.2): `force` = write regardless of size (async
+ *  subagent reports must survive the parent turn). Rendering splits on the SAME constant as the old
+ *  gate: ≤ TOOL_RESULT_OFFLOAD_LIMIT ⇒ body once + path (never dual-end — a short body would come
+ *  out twice with `middle omitted: 0 chars`); > ⇒ dual-end preview + path. Writes self-clean first. */
+export async function offloadToolResult(text, callId, dir = join(configDir, "tool-results"), { force = false } = {}) {
+  const overLimit = text.length > TOOL_RESULT_OFFLOAD_LIMIT
+  if (!force && !overLimit) return text
+  try {
+    await cleanupOldToolResults(dir)
+    await mkdir(dir, { recursive: true })
+    const file = join(dir, `${Date.now()}-${String(callId).replace(/[^a-zA-Z0-9_-]/g, "_")}.log`)
+    await writeFile(file, text, "utf8")
+    if (!overLimit) return `${text}\n\n[... full content saved to: ${file}\nPage through it with the read tool (offset/limit) if you need the full text later.]`
+    return buildDualEndPreview(text) + `\n\n[... output too large (${text.length} chars total), full content saved to: ${file}\n` +
+      `Page through it with the read tool (offset/limit) or sed -n 'START,ENDp' — do NOT re-run the tool blindly.]`
+  } catch {
+    // 写盘失败不吞报告：>LIMIT 走双端预览 + 原文案；≤LIMIT 正文整段在前（不谎称 truncated）
+    const body = overLimit ? buildDualEndPreview(text) : text
+    return body + (overLimit ? `\n\n[... truncated: ${text.length} chars total, offload to disk failed]`
+      : `\n\n[... full text kept inline above (${text.length} chars), offload to disk failed]`)
+  }
+}

package/agent/record-results.mjs

@@ -26,8 +26,6 @@
 import { pushReal } from "../context.mjs"
 import { specForModel } from "../config.mjs"
 import { FILE_MUTATORS, toolTouchPaths } from "./helpers.mjs"
-// F-LC6（LIGHT-CHANNEL §2.9 · 台账 #1753）：无账之笔提醒叶（谓词 + 文案 + 闩单源）。
-import { unbookedPenNotice } from "./unbooked-pen.mjs"
 import { capHistoryImages } from "../provider/normalize.mjs"
 import { resolve } from "node:path"
 import { advisorRuns, stripApprovedSuffix } from "../agent-tools/advisor-async.mjs"
@@ -84,10 +82,7 @@ export async function recordToolResults(agent, toolByName, results) {
         }
       } catch { /* Parse failure doesn't affect normal tool messages */ }
     }
-    // F-LC6（LIGHT-CHANNEL §2.9）：主 agent 会话首笔产品源文件笔 ⇒ 回执末尾追加一行通道提醒
-    // （零拦截——只拼回执文本、入史时机不变；命中后本会话不再提示）。
-    const penNotice = unbookedPenNotice(agent, toolCall, ok, tool)
-    pushReal(agent, { role: "tool", tool_call_id: toolCall.id, name: toolCall.name, content: penNotice ? result + penNotice : result })
+    pushReal(agent, { role: "tool", tool_call_id: toolCall.id, name: toolCall.name, content: result })
     if (tool && ok) {
       if (FILE_MUTATORS.has(toolCall.name)) {
         // Direct file edit — code was changed. The prior advisor review and

package/agent/run-stages.mjs

@@ -1,7 +1,8 @@
 /**
  * run-stages.mjs — runAgent 主循环的阶段函数族（CLI，2026-09-05 实践轮：agent.mjs
  * runAgent 383 ≥300 按骨干—细节两层提取——VS Code 端同构文件（双端 parity——拆分
- * 两端同步））。本文件承载：回合压缩检查（runCompactionCheck）、回合注入组
+ * 两端同步））。本文件承载：回合压缩检查（runCompactionCheck）、越窗守卫 / 自适应共用原子
+ * （enforceContextFit——§6.17 守卫与 §6.17.1 链三共用一个压缩原子）、回合注入组
  * （injectTurnReminders——plan cadence + eng 状态）、回合收尾（finalizeAgentTurn——
  * consult 清理/async 池分流/guard 继承）与其收集器（collectSettledAsync——自
  * agent.mjs 迁入，agent.mjs 内无其他引用）。verbatim 迁移 + 签名化，语义零变。
@@ -73,6 +74,35 @@ export function injectResponseReminders(agent, response) {
   }
 }
 
+// ─── 压缩记账三件（§6.17 阈值面 ∥ 守卫面 ∥ §6.17.1 链三自适应面共用同一段，零复制）───
+
+/** 压缩成功记账：失败计数清零 / 计划提醒 cadence 复位 / 停滞检测计数复位 / 完成事件 / AUTO 提醒重注入。 */
+function bookkeepCompaction(agent, ctx) {
+  agent._compressFailures = 0
+  agent._planReminderAtLen = 0 // After compression history shrinks, reset cadence so reminders resume
+  ctx.recentCallSigs.length = 0 // After compression history is rebuilt, reset stall detection counter
+  // Completion info (CONTEXT-COMPACTION §7 D-C2): { mode, tokensFreed, elapsedMs } —
+  // the TUI panel renders it; callers that ignore the arg keep prior onCompress semantics.
+  ctx.callbacks?.onCompress?.(agent._lastCompressInfo ?? {})
+  ensureAutoReminder(agent)
+}
+
+/** 压缩失败记账——AbortError 必须透传（用户中止不得被当成压缩失败吞掉）。 */
+function noteCompressFailure(agent, ctx, compressError) {
+  if (compressError?.name === "AbortError" || ctx.signal?.aborted) throw compressError
+  agent._compressFailures = (agent._compressFailures ?? 0) + 1
+  // Q3 (CONTEXT-COMPACTION §7 D-C1): a failed compression is surfaced to the panel;
+  // COMPRESS_FAILURE_LIMIT consecutive failures still degrade to compressFallback.
+  ctx.callbacks?.onCompressFail?.(compressError)
+}
+
+/** 三连败降级（确定性截断——零网络，§6.5 D6）。 */
+function degradeIfCompressExhausted(agent, ctx) {
+  if (agent._compressFailures < COMPRESS_FAILURE_LIMIT) return
+  agent._compressFailures = 0
+  if (compressFallback(agent)) ctx.callbacks?.onCompress?.(agent._lastCompressInfo ?? {})
+}
+
 /**
  * 回合压缩检查（2026-09-05 实践轮——自 runAgent 主循环提取）：仅安全点（history 以
  * 完整交换结尾——user/tool 位）。成功：失败计数清零/计划提醒 cadence 复位/停滞检测
@@ -82,35 +112,12 @@ export function injectResponseReminders(agent, response) {
  * 模型主动压缩（`context` 工具）由本点消费（§6.16.2——取用即清槽；no-op 与失败各落一行注记）。
  */
 export async function runCompactionCheck(agent, ctx) {
-  const { threshold, callbacks, compactionOverhead, signal, recentCallSigs } = ctx
+  const { threshold, callbacks, compactionOverhead, signal } = ctx
   // F-CC2（CONTEXT-COMPACTION.md §6.16.2）：模型主动压缩（`context` 工具）在**本安全点**消费——
   // 取用即清槽（失败不重放；重发由模型再调）；`force` 只跳过阈值早退（模型判定优先于阈值），
   // 其余全同（同 splitHistory / 同尾部预算 / 同摘要链 / 同回注 / 同基线失效）。
   const pending = agent._pendingCompact
   agent._pendingCompact = null
-  // 成功记账（§6.17：成功记账段抽局部——阈值面与守卫面共用同一段，零复制）
-  const bookkeepCompaction = () => {
-    agent._compressFailures = 0
-    agent._planReminderAtLen = 0 // After compression history shrinks, reset cadence so reminders resume
-    recentCallSigs.length = 0 // After compression history is rebuilt, reset stall detection counter
-    // Completion info (CONTEXT-COMPACTION §7 D-C2): { mode, tokensFreed, elapsedMs } —
-    // the TUI panel renders it; callers that ignore the arg keep prior onCompress semantics.
-    callbacks.onCompress?.(agent._lastCompressInfo ?? {})
-    ensureAutoReminder(agent)
-  }
-  // 压缩失败记账（两处共用：下面的阈值面 catch ∥ 下面的守卫面强制压缩）——AbortError 必须透传。
-  const noteCompressFailure = (compressError) => {
-    if (compressError?.name === "AbortError" || signal?.aborted) throw compressError
-    agent._compressFailures = (agent._compressFailures ?? 0) + 1
-    // Q3 (CONTEXT-COMPACTION §7 D-C1): a failed compression is surfaced to the panel;
-    // COMPRESS_FAILURE_LIMIT consecutive failures still degrade to compressFallback.
-    callbacks?.onCompressFail?.(compressError)
-  }
-  const degradeIfCompressExhausted = () => {
-    if (agent._compressFailures < COMPRESS_FAILURE_LIMIT) return
-    agent._compressFailures = 0
-    if (compressFallback(agent)) callbacks.onCompress?.(agent._lastCompressInfo ?? {})
-  }
   try {
     let compacted = await compressIfNeeded(
       agent, threshold, callbacks,
@@ -123,43 +130,57 @@ export async function runCompactionCheck(agent, ctx) {
       agent.history.push({ role: "user", content: compactNoopNote(), transient: true })
       compacted = await compressIfNeeded(agent, threshold, callbacks, compactionOverhead, signal)
     }
-    if (compacted) bookkeepCompaction()
+    if (compacted) bookkeepCompaction(agent, ctx)
   } catch (compressError) {
-    noteCompressFailure(compressError)
+    noteCompressFailure(agent, ctx, compressError)
     if (pending) {
       // 失败注记（§6.16.2 回执面②）：模型面告知缺口——既有失败链 / 面板面零改，仅补一行机器注记
       const { compactFailureNote } = await import("../agent-tools/context.mjs")
       agent.history.push({ role: "user", content: compactFailureNote(errText(compressError), agent._compressFailures), transient: true })
     }
-    degradeIfCompressExhausted()
+    degradeIfCompressExhausted(agent, ctx)
   }
 
   // 溢出守卫（CONTEXT-COMPACTION.md §6.17 / D-CC32——兜底，非主修；本缝 = catch 闭合后、返回前）。
+  // 判据 / 强压 / 再判 / 抛三实数 全住 `enforceContextFit`——与 §6.17.1 链三的自适应面**同一个原子**（零复制）。
+  await enforceContextFit(agent, ctx)
+}
+
+/**
+ * 越窗守卫 / 自适应共用原子（CONTEXT-COMPACTION.md §6.17 守卫 ∥ §6.17.1 链三自适应）：
+ * `requestBudget` 判 → 强压一次（`force`）→ 再判 → 抛三实数（不截断、不静默削输出）。
+ *
+ * `opts.forceCompact`（链三面）：**跳过前置估算判据**、直接强压——服务端已判越窗时估算准不准不再作门
+ * （本批要治的就是估算低估：死锁现场估 491K < limit 606,784，按估算开门会压 0 次、重试同一请求再吃 400）。
+ * 压后仍超的再判两面同判（压后仍越线说明压缩解不了，再压只是重复付费）。
+ * 返回是否走到了再判通过（守卫面估算未越线 ⇒ false、零动作；压后仍超⇒抛，不到达返回值）。
+ */
+export async function enforceContextFit(agent, ctx, { forceCompact = false } = {}) {
+  const { threshold, callbacks, compactionOverhead, signal } = ctx
   // 判据 = prompt 估算 > `budget.limit`（**无档次门**——absent 档 limit 取地板 max(window − reserve, threshold)，
   // 恒为正数、恒可判）。**判据不用 maxTokens**：未发时为 undefined ⇒ NaN ⇒ 守卫静默失效（§6.17）。
-  // 真 ⇒ 以 force 强制压缩一次（先压再判）；再估仍超 ⇒ 抛三实数、回合请求零发。不截断、不静默削输出。
   const budget = requestBudget(agent.provider)
   let usage = contextUsage(agent, compactionOverhead)
+  if (!forceCompact && !(usage.total > budget.limit)) return false
+  // 强压一次：失败走与阈值面同一条记账 / 降级链（不把摘要错误当回合错误直抛——
+  // 记账后仍按「压后仍超」判：降级截断可能已把上下文压到线下）。
+  try {
+    const compacted = await compressIfNeeded(
+      agent, threshold, callbacks, { ...compactionOverhead, force: true }, signal,
+    )
+    if (compacted) bookkeepCompaction(agent, ctx)
+  } catch (compressError) {
+    noteCompressFailure(agent, ctx, compressError)
+    degradeIfCompressExhausted(agent, ctx)
+  }
+  usage = contextUsage(agent, compactionOverhead)
   if (usage.total > budget.limit) {
-    // 强压一次：失败走与阈值面同一条记账 / 降级链（不把摘要错误当回合错误直抛——
-    // 记账后仍按「压后仍超」判：降级截断可能已把上下文压到线下）。
-    try {
-      const compacted = await compressIfNeeded(
-        agent, threshold, callbacks, { ...compactionOverhead, force: true }, signal,
-      )
-      if (compacted) bookkeepCompaction()
-    } catch (compressError) {
-      noteCompressFailure(compressError)
-      degradeIfCompressExhausted()
-    }
-    usage = contextUsage(agent, compactionOverhead)
-    if (usage.total > budget.limit) {
-      const remedy = budget.limit < 0
-        ? `max_tokens ${budget.maxTokens} alone exceeds the window — lower provider.maxTokens or switch to a larger-window model`
-        : "forced compaction ran but the prompt still exceeds the window; reduce the conversation (/compact or prune) before retrying"
-      throw contextOverflowError(agent.provider, usage.total, budget, remedy)
-    }
+    const remedy = budget.limit < 0
+      ? `max_tokens ${budget.maxTokens} alone exceeds the window — lower provider.maxTokens or switch to a larger-window model`
+      : "forced compaction ran but the prompt still exceeds the window; reduce the conversation (/compact or prune) before retrying"
+    throw contextOverflowError(agent.provider, usage.total, budget, remedy)
   }
+  return true
 }
 
 /**
@@ -282,7 +303,7 @@ export async function finalizeAgentTurn(agent, ctx) {
   // 恒达窗 = 正常 ∥ Abort-continue ∥ 异常抛三径同达；会话停止径不判（清场语义归 finishSuspension）。
   if (isDigestRound({ autoTurn, upstreamTurn, timerTurn }) && carrierField(agent, "_daSession") === true
       && !(signal?.aborted && !signal?.reason?.interrupt)) {
-    accountDigestRound(agent)
+    await accountDigestRound(agent) // async（§6.31.5 升级支 ④ 终局披露复用注入器）
   }
   agent._inAutoTurn = false
   // AGENT-LOOP-ASYNC-POOL.md §6.8 D-S6: auto-turn guard marks survive into the next USER run (restored at its

package/agent/run-start.mjs

@@ -31,31 +31,31 @@ export async function beginRun(agent, input, callbacks, {
   // （consult → injectConsultResult；其余 → injectAsyncResult——族分支同 CONSULTATION.md §6.2 D-R17a/b）
   // ——单容器一处清，不再逐族三段。
   // §6.31 消化账务（批 digest-accounting · 2026-10-05 · 台账 #930）：**投递 ≠ 销账**——
-  // 会话态（`_daSession`）投递留容器（覆盖才离容器 / 未见账经消化轮回路重投）；fallback
+  // 会话态（`_daSession`）投递留容器（覆盖才离容器 / 未见账计一个未签收轮、达 `DA_MISS_LIMIT` 升级——
+  // 投递恒一次，无重投回路：批 digest-retry-amplify · 台账 #1850）；fallback
   // （headless / 直连 runAgent）缺省条逐字沿用取尽语义（先离容后注入 ∥ `releaseSettledEntry` 面；
   // 零账目动作——不销账 / 不重投），已投递未销账条同判据跳过且留容器（§6.31 出口缝② · 父侧裁定 2026-10-05）。
   const pendingAsync = agent._pendingAsyncResults
   const { carrierField, releaseChildHold, releaseSettledEntry } = await import("../agent-tools/async-settle.mjs")
   if (carrierField(agent, "_daSession") === true) {
     const { armAccountRound, isDigestRound, shouldDeliverEntry, digestAccountRequirement } = await import("./digest-account.mjs")
-    armAccountRound(agent) // §6.31.5 落痕清位：会话态起跑即清（缺痕 ⇒ 全条未覆盖——安全方向）
+    armAccountRound(agent) // §6.31.5 落痕清位：会话态起跑即清（缺痕 ⇒ 该轮按未签收判一个轮次）
     if (pendingAsync?.length) {
       const { injectAsyncResult } = await import("../agent-tools/subagent.mjs")
       const { injectConsultResult } = await import("../agent-tools/consult.mjs")
       const digestRound = isDigestRound({ autoTurn, upstreamTurn, timerTurn })
-      // 投递门控两态（§6.31.4 · §6.34 收窄）：首投**仅系统轮**（`autoTurn`——用户回合零注入）∥ 重投仅消化轮；
-      // 注入后**留容器**（不 splice）。
+      // 投递门控单门（§6.31.4 · 投递恒一次）：首投**仅系统轮**（`autoTurn`——用户回合零注入），
+      // 已投递条恒跳过；注入后**留容器**（不 splice）。
       // 注入抛错 ⇒ 未投条目（`_daDelivered` 未置）留容器待下轮——收窄既有「splice 先取尽」的丢失窗。
       for (const e of [...pendingAsync]) {
-        if (!shouldDeliverEntry(e, digestRound, autoTurn)) continue
+        if (!shouldDeliverEntry(e, autoTurn)) continue
         if (e.role === "consult") await injectConsultResult(agent, e)
         else await injectAsyncResult(agent, e)
         e._daDelivered = true
-        e._daRetry = false
-        releaseChildHold(e) // 仅释放 `childAgent`——`report` 保留至销账 / 升级（重投需原文）
+        releaseChildHold(e) // 仅释放 `childAgent`——`report` 保留至销账 / 升级（升级终局披露需原文）
       }
       // 账目要求行（§6.31.3）：仅会话态消化轮且未销账清单非空时注入（先投递后拼清单——
-      // 含本回合首投 / 重投）；两档同发（手动 / AUTO）；transient（机器线独有）。
+      // 含本回合首投）；两档同发（手动 / AUTO）；transient（机器线独有）。
       if (digestRound) {
         const ids = pendingAsync.filter((e) => e._daDelivered === true).map((e) => e.id)
         if (ids.length > 0) {

package/agent/setup.mjs

@@ -23,20 +23,10 @@ import { normalizeOrigin } from "../memory/origin.mjs"
 import { searchOrigins } from "../memory/code-search.mjs"
 import { INDEX_ORIGIN_ROW_WARN } from "../memory/schema.mjs"
 import { resolveCompactThreshold } from "../config.mjs"
+import { safeSliceUTF16 } from "../text-budget.mjs"
 
 const DOC_SEARCH_LIMIT = 5
 const DOC_CHUNK_PREVIEW_LEN = 300
-/** UTF-16 安全截断（2026-09-02 deepseek 400 根因）：slice(0, N) 按码元切会把 emoji 代理对切成孤立
- *  高代理（如 🔴=U+D83D+DD34 只剩 D83D）——deepseek 解析器严格 UTF-16 报 400
- *  "unexpected end of hex escape"。截断点落在高代理上时向前收一个码元。 */
-function safeSliceUTF16(text, max) {
-  if (text.length <= max) return text
-  const end = max
-  // 截断点恰在高代理（D800-DBFF）上 → 收到高代理之前（不带它）
-  const cp = text.charCodeAt(end - 1)
-  if (cp >= 0xd800 && cp <= 0xdbff) return text.slice(0, end - 1)
-  return text.slice(0, end)
-}
 const MEMORY_SEARCH_LIMIT = 3
 
 /**
@@ -67,6 +57,8 @@ export async function prepareRun(agent, input, callbacks, {
   // §6.17 估算自校准比（`_tok` / `_tokRatio`）**不在本处清**：本函数是每 run 的 pre-flight，
   // 而在每轮用户消息上归零会让池化比退化成单样本（R2 失效）。初值在 `agent.mjs` 构造字面量，
   // 清空点 = `/new`（`session-lifecycle.mjs`）∥ `key` 变自清（`token-window.mjs` `recordTokenSample`）。
+  // §6.17.1 链三自适应额度：run 级一次——本处复位（一次 = 全部额度；同一 run 内第二次独立越窗直接抛）。
+  agent._overflowRetried = false
   // Cumulative provider cache accounting (batch 2026-10-18-context-cache-visibility):
   // the service reports prompt_cache_hit/miss per response; the terminal faces each kept
   // their own tally, so the CORE had none and `context` could not report cache efficiency.

package/agent/suspension.mjs

@@ -240,7 +240,7 @@ export function startSuspension(ctx) {
   const done = (async () => {
     carrier._suspended = true
     // §6.31.2 会话标记（消化账务批 · 2026-10-05 · 台账 #930）：挂起会话期 true——投递留容器 /
-    // 见账 / 重投回路的唯一判据；退出（finally）置 false ⇒ 会话外回 fallback 语义。
+    // 见账的唯一判据；退出（finally）置 false ⇒ 会话外回 fallback 语义。
     carrier._daSession = true
     hooks.onCounts?.(backgroundCounts(carrier))
     let aborted = false

package/agent/turn-loop.mjs

@@ -11,8 +11,8 @@ import { specForModel, assistantToolCallMessage } from "../config.mjs"
 import { executeToolCalls } from "./dispatch.mjs"
 import { recordToolResults } from "./record-results.mjs"
 import { injectPostTurn } from "./post-turn.mjs"
-import { handleCompletion } from "./completion.mjs"
-import { runCompactionCheck, injectTurnReminders, injectResponseReminders } from "./run-stages.mjs"
+import { handleCompletion, isSubstantiveResponse } from "./completion.mjs"
+import { runCompactionCheck, enforceContextFit, injectTurnReminders, injectResponseReminders } from "./run-stages.mjs"
 import { recordTokenSample } from "../token-window.mjs"
 import { callModelTurn } from "./chat-call.mjs"
 import {
@@ -49,6 +49,28 @@ export async function runTurnLoop(agent, {
   // `context` 工具的 stats 报**同一口径**（不自行重算第二口径；VSC checkAndCompact 同款暂存）。
   agent._ctxBasis = { threshold, overhead: compactionOverhead }
 
+  // §6.17.1 链三（越窗 400 自适应）：单回合调用外包一层 catch——服务端说越窗 ⇒ 强制压一次 + 重试同一回合一次。
+  // 排除面：`stage ∈ {compress, distill}` 的请求**不经本函数**（压缩机与蒸馏各自直调 `chat`，续写子请求的
+  // 失败已在 `provider/core.mjs` 折进 `_warnings`）⇒ 本 catch 只接回合请求的 typed 越窗，不存在「已流出再重放」。
+  const callTurn = async (turnCtx) => {
+    try {
+      return await callModelTurn(agent, turnCtx)
+    } catch (e) {
+      if (e?.kind !== "context_overflow") throw e
+      // 死循环守卫（批档 D6）：额度 = run 级一次（`agent/setup.mjs` 每 run 复位）——已用过 ⇒ 原 typed 错误透传
+      // （三实数 + `/compact` 提示已在报文体里）；同一 run 内第二次独立越窗不再自愈，用户 `/compact` 后可继续。
+      if (agent._overflowRetried) throw e
+      agent._overflowRetried = true
+      // 越窗 typed 错误有两个出口（同 kind，§6.17）：HTTP 400 分类 ∥ 本地发送面净判——两面都归本链处理，
+      // 故估算不再作门（估算恰恰低估才有本链），整压一次；压后仍超 ⇒ 抛三实数、不再压。
+      await enforceContextFit(
+        agent, { threshold, callbacks, compactionOverhead, recentCallSigs, signal }, { forceCompact: true },
+      )
+      // 重试恰一次：此行不在 try 内——二次越窗的 typed 错误原样上抛（不截断、不静默）
+      return await callModelTurn(agent, turnCtx)
+    }
+  }
+
   // SUBAGENT-UPSTREAM-CHANNEL（AGENT-LOOP-UPSTREAM.md §6.27.4 消费点）：子 → 父在飞消息的
   // 回合边界注入单点取用一次（模块缓存 ⇒ 每 run 一次代价）；动态 import = 零新增静态边
   // （同款先例 = `run-start.mjs` 的 `injectAsyncResult` 动态 import）。
@@ -128,10 +150,17 @@ export async function runTurnLoop(agent, {
     // 2026-09-05 实践轮：plan cadence + eng 状态注入提为 injectTurnReminders（run-stages）
     await injectTurnReminders(agent, { depth })
 
-    const response = await callModelTurn(agent, {
+    const response = await callTurn({
       systemPrompt, toolSchemas, streamOutput, callbacks, signal, streamRuleFired, autoTurn, depth, turn,
     })
 
+    // 空响应预算复位（AGENT-LOOP.md §6.5① · D-AL28）：本轮响应**有实质** ⇒ 计数清 0（实质 = 有正文
+    // 或带工具调用；判据单源 = completion.mjs `isSubstantiveResponse`）。落位 = 本轮响应存在的第一处、
+    // 也是四支路（下方流规则 abort ∥ 用户中断 ∥ 工具批 ∥ 零工具）发散前的最后一处——落进任一分支都会漏其余三支。
+    // 与下方 `guardPushbacks = 0`（工具批执行处）分工：那处复位的是 verify ∥ advisor 推回预算、只看「有工具批」；
+    // 本处复位空响应预算、看「有实质」——正文本身已是实质，不必等工具批。
+    if (isSubstantiveResponse(response)) agent._emptyRetries = 0
+
     // §6.31.5 落痕（消化账务批 · 2026-10-05 · 台账 #930 ∥ #939 收正）：本 run 内**逐轮追加**——
     // 每模型轮返回即写（会话态）；首轮签收不为收口轮覆盖（见账取件读累积痕）。
     // 落父字段（抗 `history` 整体替换——`context.mjs` `applyCompression`）；非会话零动作。

package/agent/write-face.mjs

@@ -0,0 +1,99 @@
+/**
+ * agent/write-face.mjs — 面判定单源（写锁与设计门共用的判据底座）。
+ *
+ * 权威规格 = `docs/core/design/BATCH-LEDGER-REVIEW-UNIFY.md` §2.1 / §2.10；面分类的原文正源 =
+ * `docs/core/requirements/ENGINEERING-MODE-V2.md` §13.5。本档只做一件事：给一个绝对路径判「产品代码面
+ * / 文档面」，判据逐步骤对应 §2.10 的两值表。
+ *
+ * 面**只有两值**：文档面（放行）∥ 产品面（拦）——设计门按它拦；写锁 2026-11-03 起不分面（设计档 §2.3），
+ * 面在那里只选拒文变体。四格先命中先定：
+ *   1 出辖（祖先链无 manifest）⇒ 放行（`out-of-jurisdiction`）——辖界，不是面
+ *   2 manifest `docRoot` 前缀命中 ⇒ 放行（`doc-root`，D1 写权矩阵在写面上的机判投影）
+ *   3 文件 = `PROJECT-MANIFEST.json`（项目状态档）⇒ 放行（`manifest-state`）
+ *   4 其余一切 ⇒ 产品面（`product`，fail-closed——判不出面就按产品面走全链）
+ *
+ * 为什么不再复用 `classifyPath`：旧形把「构建产物 / 仓根 `scripts` ∥ `test` ∥ `.thincoder` ∥ `.github`
+ * / 锁文件 / `classifyPath` 的 temp·aux·state」当放行桶——每多一个放行桶，就多一条「这一步要不要走流程」
+ * 的自判口子（用户 2026-11-02 裁定退役）。两值之后没有第三桶、没有豁免、没有待裁格；`classifyPath` /
+ * `isCodePath` **本体零改**，它们仍是索引 / 检索 / verify 那一族的判据（七个生产消费面）。
+ *
+ * `test` 标记与面值**分离**：路径含 `test` / `tests` 段 ⇒ `test: true`，只决定写锁用测试变体拒文，
+ * 不改 `face`。
+ */
+import { isAbsolute, relative, resolve } from "node:path"
+
+import { declarationForTarget } from "../conventions.mjs"
+import { docRootPaths, manifestFilePath, readManifest } from "../manifest.mjs"
+// 文档面键集**不另持字面**（单源 = `agent-tools/review-facts.mjs` 的 `REVIEW_ROOT_KEYS`——同一组 docRoot 子键，
+// 两份清单漂移就是「评审面放的 / 写面拦的」各说各话）。
+import { REVIEW_ROOT_KEYS } from "../agent-tools/review-facts.mjs"
+
+/** 比较键（绝对化 + 分隔符归一 `/` + win32 大小写归一——同 `write-gate.mjs` 的 `gateKey` 口径）。 */
+const faceKey = (p) => {
+  const s = resolve(String(p)).replace(/\\/g, "/")
+  return process.platform === "win32" ? s.toLowerCase() : s
+}
+
+/** 该路径所属项目根的文档面根集（绝对比较键）。manifest 读不到 ⇒ 空集（兜底 = 产品代码面）。 */
+function docRootKeys(root, manifest) {
+  let man = manifest
+  if (!man || typeof man !== "object" || !man.docRoot) {
+    try { man = readManifest(root).manifest } catch { man = null }
+  }
+  if (!man || typeof man !== "object") return []
+  const out = []
+  for (const key of REVIEW_ROOT_KEYS) {
+    for (const abs of docRootPaths(man.docRoot?.[key], root)) out.push(faceKey(abs))
+  }
+  return out
+}
+
+/** 路径段里有没有 `test` / `tests`（拒文变体句的判据，与面值无关）。 */
+function hasTestSegment(relOrAbs) {
+  return String(relOrAbs).split(/[\\/]+/).filter(Boolean).some((s) => {
+    const low = s.toLowerCase()
+    return low === "test" || low === "tests"
+  })
+}
+
+/**
+ * 面判定（判据本体）。返回 `{face, reason, test}`：
+ *  - `face` = `"product"`（产品面 ⇒ 设计门拦；写锁里只选拒文变体）∥ `"pass"`（放行面）；
+ *  - `reason` = 命中的那一格——**只有四值**：`out-of-jurisdiction` / `doc-root` / `manifest-state` /
+ *    `product`（回执与用例的定位面）；
+ *  - `test` = 路径含 `test` / `tests` 段（产品测试面 ⇒ 写锁换测试变体那句拒文；不改 `face`）。
+ * @param {string} absPath — 目标绝对路径（相对形由调用方先 resolve；本档不猜会话锚）
+ * @param {object|null} [manifest] — 所属项目的 manifest（缺省 ⇒ 按项目根读；读不到 ⇒ 文档面空集）
+ * @returns {{face: "product"|"pass", reason: "out-of-jurisdiction"|"doc-root"|"manifest-state"|"product", test: boolean}}
+ */
+export function faceDetail(absPath, manifest = null) {
+  const abs = resolve(String(absPath ?? ""))
+  const conv = declarationForTarget(abs) // 出辖 ⇒ null（祖先链无 manifest）
+  if (!conv) return { face: "pass", reason: "out-of-jurisdiction", test: hasTestSegment(abs) }
+  const root = conv.root
+  const rel = relative(root, abs)
+  const inRoot = rel === "" || (!rel.startsWith("..") && !isAbsolute(rel))
+  const test = hasTestSegment(inRoot ? rel : abs)
+  if (inRoot) {
+    const key = faceKey(abs)
+    // 2 文档面（manifest docRoot）
+    if (docRootKeys(root, manifest).some((d) => key === d || key.startsWith(`${d}/`))) {
+      return { face: "pass", reason: "doc-root", test }
+    }
+    // 3 项目状态档（主 agent 的声明面——D1 写权矩阵同源）
+    if (key === faceKey(manifestFilePath(root))) return { face: "pass", reason: "manifest-state", test }
+  }
+  // 4 其余一切 = 产品面（fail-closed）
+  return { face: "product", reason: "product", test }
+}
+
+/**
+ * 面判定（§2.1 契约形）：`"product"` = 产品面（设计门按它拦；写锁里只选拒文变体——台账在途行才是判据），
+ * `"pass"` = 放行面（文档面 / 出辖）。
+ * @param {string} absPath — 目标绝对路径
+ * @param {object|null} [manifest] — 所属项目 manifest（缺省 ⇒ 按项目根读）
+ * @returns {"product"|"pass"}
+ */
+export function faceOf(absPath, manifest = null) {
+  return faceDetail(absPath, manifest).face
+}