thincoder 0.12.59 → 0.12.60

package/src/context.mjs

@@ -287,7 +287,7 @@ export async function compressIfNeeded(agent, threshold, callbacks, extras = {},
   // Silent by design (D11): no onToken/onReasoning — the compaction process must not stream to the frontend.
   // signal propagates user cancellation (Ctrl+C) to the in-flight summary call.
   // Compression visibility (CONTEXT-COMPACTION.md §7 D-C1/D-C2): the frontend learns the compression
-  // STARTED right before the LLM call ("Compressing context… / summarizing N messages" panel) — only
+  // STARTED right before the summary LLM call ("Compressing context… / summarizing N messages" panel) — only
   // the lifecycle is surfaced, never the summary body. N = the number of history messages being summarized.
   callbacks?.onCompressStart?.({ messages: middle.length })
   const startedAt = performance.now()
@@ -374,150 +374,8 @@ function shrinkOversized(agent, limit = OVERSIZE_CONTENT_LIMIT) {
   return shrunk
 }
 
-// ─── End-of-run exploration distillation (AGENT-LOOP §13 + CONTEXT-COMPACTION §5, 2026-08-23) ───
-// The main agent's machine line is flooded by inline step-by-step exploration (read/grep/...).
-// At run end we distill THIS run's exploration tool-results into one semantic summary note that
-// replaces them in the machine line, while agent._fullHistory (the human line) stays untouched.
+// ─── 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））───────────────────────
 
-/** Read-only knowledge tools counted as "exploration" (execute writes files → never exploration). */
-export const EXPLORE_TOOLS = new Set([
-  "read", "grep", "glob", "ls", "code_search", "doc_search", "repo_outline",
-])
-
-/** Summary prompt for turning a burst of exploration results into a semantic summary. */
-export const EXPLORE_SUMMARY_PROMPT = `You are distilling exploration tool results. Summarize the following read-only codebase exploration into a compact semantic summary for the main agent's own context.
-
-Requirements:
-- Capture WHAT was discovered, WHERE (which files / directories / symbols), and the KEY CONCLUSIONS — do not list tool calls mechanically
-- Keep actionable facts the main agent needs to continue: code locations, function names, file paths, structure, and open questions the exploration raised
-- Drop raw tool-output noise, repeated lines, and verbatim file dumps — keep only what must be remembered
-- Be honest: mark anything not actually verified as "unverified"; do not present guesses as facts
-- Use bullet points; aim for information completeness, not a hard word limit
-
-Exploration log:
-`
-
-/** tool_calls name across both stored shapes ({function:{name}} and flat {name}). */
-function toolCallName(tc) {
-  return tc?.function?.name ?? tc?.name ?? ""
-}
-
-/** Tool that produced a tool-result message (falls back to its owner assistant's tool_call). */
-function toolResultName(msg, ownerToolCalls) {
-  if (typeof msg?.name === "string" && msg.name) return msg.name
-  const owner = (ownerToolCalls ?? []).find((tc) => tc.id === msg?.tool_call_id)
-  return owner ? toolCallName(owner) : ""
-}
-
-/**
- * Find the pure-exploration "assistant(tool_calls)→tool…" pair blocks added since `start`.
- * A block is explorable only when EVERY tool call AND every tool result in it is an exploration
- * tool — mixed blocks (read + edit in one turn) stay untouched, or we'd orphan the edit pairing.
- */
-function findExplorationBlocks(history, start) {
-  const blocks = []
-  let i = start
-  while (i < history.length) {
-    const m = history[i]
-    if (m?.role === "assistant" && Array.isArray(m.tool_calls) && m.tool_calls.length > 0) {
-      let j = i + 1
-      while (j < history.length && history[j]?.role === "tool") j++
-      const toolMsgs = history.slice(i + 1, j)
-      const allCallsExplore = m.tool_calls.every((tc) => EXPLORE_TOOLS.has(toolCallName(tc)))
-      const allResultsExplore = toolMsgs.length > 0 && toolMsgs.every((t) => EXPLORE_TOOLS.has(toolResultName(t, m.tool_calls)))
-      if (allCallsExplore && allResultsExplore) {
-        blocks.push({ start: i, end: j, messages: history.slice(i, j), toolCount: toolMsgs.length })
-      }
-      i = j
-    } else {
-      i++
-    }
-  }
-  return blocks
-}
-
-/** Serialize a batch of exploration messages for the summary LLM (same shape as compaction serialization). */
-function serializeExplorationMessages(messages) {
-  const cap = 8000 // exploration results ARE the signal to distill — generous cap (quality-first, N1)
-  return messages
-    .map((m) => {
-      const toolNote = m.tool_calls ? ` [called tools: ${m.tool_calls.map(toolCallName).join(", ")}]` : ""
-      let text = ""
-      if (typeof m.content === "string") text = m.content
-      else if (Array.isArray(m.content)) text = m.content.filter((p) => p?.type === "text").map((p) => p.text ?? "").join(" ")
-      return `[${m.role}]${toolNote} ${text.slice(0, cap)}`
-    })
-    .join("\n")
-}
-
-/**
- * Core (shared) distillation: replace this run's pure-exploration pair blocks with a single
- * "[Exploration summary]" note placed where the first block was. Returns a NEW history array,
- * or null when there is nothing to shrink (<3 exploration results / LLM failure). Pairing-safe:
- * whole assistant→tool blocks are removed, so no orphan tool_calls/tool can survive.
- */
-async function distillExplorations(history, start, provider, signal, agent, depth) {
-  if (!Array.isArray(history) || history.length - start < 2) return null
-  const blocks = findExplorationBlocks(history, start)
-  const resultCount = blocks.reduce((n, b) => n + b.toolCount, 0)
-  if (resultCount < 3) return null
-
-  const serialized = blocks.map((b) => serializeExplorationMessages(b.messages)).join("\n")
-
-  let summary
-  try {
-    // Silent by design (D11): thinking:null and no onToken/onReasoning — this internal
-    // distillation must not stream to the frontend. signal propagates user cancellation.
-    const resp = await chat({ ...provider, thinking: null, reasoningEffort: null }, {
-      messages: [{ role: "user", content: EXPLORE_SUMMARY_PROMPT + serialized }],
-      signal,
-      // §18.6 D-TR4：轨迹元数据增补——kind=distill（探索蒸馏面——agent 元数据透出；
-      // depth 经 summarizeRunExplorations 参数透传——agent.mjs 主作用域传入）
-      logCtx: {
-        stage: "distill", child: agent?._logId ?? null, kind: "distill",
-        role: agent?._role ?? null, depth: depth ?? null,
-        session: agent?._sessionStart ?? null, cwd: agent?.cwd ?? process.cwd(),
-        traces: agent?.config?.traces?.enabled !== false,
-      },
-    })
-    summary = resp?.content
-  } catch {
-    return null // N3: never block the run's return or lose history — original results stay
-  }
-  if (!summary) return null
-
-  const drop = new Set()
-  for (const b of blocks) for (let k = b.start; k < b.end; k++) drop.add(k)
-  const note = { role: "user", content: "[Exploration summary]\n" + summary }
-  const next = []
-  let inserted = false
-  for (let k = 0; k < history.length; k++) {
-    if (drop.has(k)) {
-      if (!inserted) { next.push(note); inserted = true }
-      continue
-    }
-    next.push(history[k])
-  }
-  return next
-}
-
-/**
- * End-of-run exploration distillation (runAgent's final return). Shrinks the MACHINE line
- * (agent.history) only; agent._fullHistory is never touched. Triggers when this run added ≥3
- * exploration tool results; on LLM failure it silently keeps the original history (N3).
- * The distillation itself is silent and never streams (D11); `callbacks.onDistilled` fires
- * ONLY after the replacement actually lands (never on no-op/failure) — callers persist the
- * compressed session (SEND-STALL-DISTILL §2.3).
- */
-export async function summarizeRunExplorations(agent, callbacks, signal, depth = 0) {
-  const next = await distillExplorations(agent.history, agent._runStartHistoryLen ?? 0, agent.provider, signal, agent, depth)
-  if (!next) return
-  agent.history = next
-  // The machine line changed shape — the measured token baseline was for the pre-shrink context.
-  // Invalidate so the next compaction check re-estimates instead of over-counting stale history.
-  agent._lastPromptTokens = null
-  agent._usageAtLen = null
-  // The compressed machine line must reach the disk: the run's own save already happened,
-  // so without this hook the async distill would leave the session un-compressed on exit.
-  callbacks.onDistilled?.()
-}
+export { summarizeRunExplorations, EXPLORE_TOOLS, EXPLORE_SUMMARY_PROMPT } from "./explore-distill.mjs"

package/src/crash-reports.mjs

@@ -0,0 +1,123 @@
+/**
+ * crash-reports.mjs — R25（docs/design/ARCHITECTURE.md §R25——F-R25a/b/c）CLI 异常终止
+ * 捕获与留痕机制。
+ *
+ * 三类能力（与设计逐项对应）：
+ * - prepareCrashReporting()（F-R25b）：入口最前调用——mkdir 预建 ~/.thincoder/crash-reports/
+ *   + process.report 代码内启用（reportOnFatalError + directory）——V8 OOM/原生 fatal
+ *   自动写 report.*.json。实现批实测（2026-09-07）：目录缺失时 Node 对 fatal 静默不写
+ *   报告——预建是必要动作而非"零成本保险"。
+ * - writeCrashRecord()（F-R25a）：JS 异常钩子同步落盘 crash-{ts}-{pid}.json（ts = epoch ms
+ *   UTC + pid——跨进程同 ms 防覆盖——复审 #3）——权限 0600（config.json 先例）。
+ * - recentCrashHint()（F-R25c）：启动扫描 24h 窗内记录（两类文件模式定死——评审 #8：
+ *   crash-*.json 自写 + report.*.json Node fatal——mtime 判定）→ 返回提示文本或 null
+ *   （无匹配不提示——负例）。
+ *
+ * 保留策略（评审 #6 + 复审 #4）：>30 天淘汰——写时自清理（tool-results 先例『落盘目录
+ * 写时自清理』段同动机——Windows 磁盘清理不覆盖 ~/.thincoder）——清理搭车点 = F-R25a 写 +
+ * F-R25b 入口 mkdir + F-R25c 启动扫描（纯 fatal 序列 JS 不运行——下个进程入口 mkdir 时
+ * 清理）。
+ *
+ * 纪律：全部同步 API（崩溃路径无异步）；调用方按执行序列各步独立 try/catch（复审 #2——
+ * 写失败/恢复失败不阻断后续步——exit 非 0 恒达）。
+ */
+import { chmodSync, existsSync, mkdirSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { configDir } from "./config.mjs"
+
+/** crash-reports 运行时目录（~/.thincoder/crash-reports——非仓内——写时自清理）。 */
+export function crashReportsDir() {
+  return join(configDir, "crash-reports")
+}
+
+/** 记录文件模式（评审 #8 定死）：crash-*.json = 自写（F-R25a）；report.*.json = Node
+ *  fatal（默认命名 report.YYYYMMDD.HHMMSS.<pid>.<seq>.json——2026-09-07 实现批实测）。 */
+function isCrashRecordName(name) {
+  return /^crash-.+\.json$/.test(name) || /^report\..+\.json$/.test(name)
+}
+
+/** >30 天淘汰（评审 #6）——写时自清理；搭车点 = 写 / 入口 mkdir / 启动扫描（复审 #4）。 */
+function purgeOldCrashReports(dir) {
+  const cutoff = Date.now() - 30 * 24 * 3_600_000
+  let names
+  try { names = readdirSync(dir) } catch { return } // 目录不存在/不可读 → 无事可做
+  for (const name of names) {
+    if (!isCrashRecordName(name)) continue
+    try {
+      if (statSync(join(dir, name)).mtimeMs < cutoff) unlinkSync(join(dir, name))
+    } catch { /* 单个文件失败不影响其余 */ }
+  }
+}
+
+/**
+ * F-R25b：入口最前调用（一切重活前——缩编程期窗口）——预建目录 + process.report 启用。
+ * 任何失败不阻断启动（尽力面——record 路径自带降级）。返回目录路径。
+ */
+export function prepareCrashReporting() {
+  const dir = crashReportsDir()
+  try {
+    mkdirSync(dir, { recursive: true })
+    // 代码内启用：shebang 入口无法携带启动参数（env 单参数限制 + execArgv 仅子进程——评审 #1）
+    process.report.directory = dir
+    process.report.reportOnFatalError = true
+  } catch { /* mkdir/启用失败不阻断启动——尽力面 */ }
+  purgeOldCrashReports(dir) // F-R25b 入口 mkdir 搭车清理（复审 #4——纯 fatal 序列也触发）
+  return dir
+}
+
+/**
+ * F-R25a：JS 异常钩子同步写诊断记录（内容：时间/类型/错误消息+堆栈/uptime/argv/cwd/
+ * 内存/node+版本——设计字段集）。
+ * @param {string} type uncaughtException | unhandledRejection
+ * @param {*} error 原始 error（unhandledRejection 可 reject 任意值——非 Error 兜底 String）
+ * @returns {string|null} 记录完整路径；写失败 → null（不抛——调用方步隔离——复审 #2）
+ */
+export function writeCrashRecord({ type, error }) {
+  const dir = crashReportsDir()
+  try {
+    const record = {
+      time: new Date().toISOString(),
+      type,
+      message: error?.message ?? String(error),
+      stack: typeof error?.stack === "string" ? error.stack : null,
+      uptime: process.uptime(),
+      argv: process.argv,
+      cwd: process.cwd(),
+      memoryUsage: process.memoryUsage(),
+      node: process.version,
+    }
+    // ts = epoch ms UTC + pid——跨进程同 ms 防覆盖（复审 #3）
+    const file = join(dir, `crash-${Date.now()}-${process.pid}.json`)
+    writeFileSync(file, JSON.stringify(record, null, 2) + "\n", { encoding: "utf8", mode: 0o600 })
+    try { chmodSync(file, 0o600) } catch { /* Windows chmod 尽力而为——config.json 先例 */ }
+    purgeOldCrashReports(dir) // F-R25a 写时搭车清理（评审 #6）
+    return file
+  } catch {
+    return null // 写失败不阻断后续步
+  }
+}
+
+/**
+ * F-R25c：启动扫描——crash-reports 24h 窗内是否有记录（两类模式——mtime 判定）。
+ * @param {object} [opts] 可选 { dir }——目录注入（测试用）；默认 crashReportsDir()
+ * @returns {string|null} 提示文本（含最新记录完整路径）；无匹配 → null（负例——不提示）
+ */
+export function recentCrashHint({ dir = crashReportsDir() } = {}) {
+  purgeOldCrashReports(dir) // F-R25c 启动扫描搭车清理（复审 #4）
+  if (!existsSync(dir)) return null
+  const cutoff = Date.now() - 24 * 3_600_000
+  let best = null // 窗内 mtime 最新记录
+  let names
+  try { names = readdirSync(dir) } catch { return null } // 目录不可读 → 静默无提示
+  for (const name of names) {
+    if (!isCrashRecordName(name)) continue
+    try {
+      const st = statSync(join(dir, name))
+      if (st.mtimeMs >= cutoff && (!best || st.mtimeMs > best.mtimeMs)) {
+        best = { path: join(dir, name), mtimeMs: st.mtimeMs }
+      }
+    } catch { /* 单文件 stat 失败跳过 */ }
+  }
+  if (!best) return null
+  return `上次运行异常终止（记录：${best.path}）`
+}

package/src/distill.mjs

@@ -18,7 +18,7 @@ Output a JSON array (nothing else):
     "title": "Short title",
     "content": "Full content, self-contained — understandable without session context",
     "tags": ["tag1", "tag2"],
-    "scope": "personal | project"
+    "layer": "personal | project"
   }
 ]
 
@@ -27,7 +27,7 @@ Extraction criteria:
 - decision: technical decisions made in the session and their rationale
 - pattern: debugging experiences, solutions, reusable workflows
 - rule: coding standards (caution! rules are usually best written manually; only extract rules explicitly established in the session)
-- scope: use "project" for project-specific knowledge; use "personal" for general or personal preferences
+- layer: use "project" for project-specific knowledge; use "personal" for general or personal preferences
 
 Do NOT extract:
 - one-off task details ("changed line X in file Y today")
@@ -53,7 +53,7 @@ function tracesEnabledFromConfig() {
 
 /**
  * Extract candidates from a session transcript. transcript: plain-text session record.
- * Returns [{ type, title, content, tags, scope }], or [] on parse failure.
+ * Returns [{ type, title, content, tags, layer }], or [] on parse failure.
  * opts.traces（可选）：§18.6 D-TR6 开关显式透传（测试隔离/未来调用方）——缺省回退
  * 磁盘配置（tracesEnabledFromConfig）——关 = chat() 出口不落盘。
  */
@@ -117,23 +117,23 @@ export function historyToTranscript(history, { maxChars = 30_000 } = {}) {
 /**
  * Write confirmed candidates to the specified layer.
  * opts: { projectDir, team: { dir } | null, author }
- * scope=team requires opts.team; project requires opts.projectDir.
+ * layer=team requires opts.team; project requires opts.projectDir.
  * Returns write result description.
  */
 export async function saveCandidate(memory, candidate, opts = {}) {
-  const scope = candidate.scope ?? "personal"
+  const layer = candidate.layer ?? candidate.scope ?? "personal"
   // tags come from LLM output (untrusted): if not an array, stringify then split by comma/whitespace —
   // calling .split on a non-string would crash, and models often produce "a, b" comma strings
   const tags = Array.isArray(candidate.tags)
     ? candidate.tags.map((t) => String(t)).filter(Boolean)
     : String(candidate.tags ?? "").split(/[\s,]+/).filter(Boolean)
 
-  if (scope === "personal") {
+  if (layer === "personal") {
     const id = await put(memory, { type: candidate.type, title: candidate.title, content: candidate.content, tags: tags.join(" ") })
     return `personal#${id}`
   }
-  if (scope === "project") {
-    if (!opts.projectDir) throw new Error("project scope unavailable — no project directory configured (set memory.projectDir in ~/.thincoder/config.json)")
+  if (layer === "project") {
+    if (!opts.projectDir) throw new Error("project layer unavailable — no project directory configured (set memory.projectDir in ~/.thincoder/config.json)")
     const filename = await putMarkdown(memory, {
       layer: "project", dir: opts.projectDir,
       type: candidate.type, title: candidate.title, content: candidate.content,
@@ -141,8 +141,8 @@ export async function saveCandidate(memory, candidate, opts = {}) {
     })
     return `project:${filename}`
   }
-  if (scope === "team") {
-    if (!opts.team?.dir) throw new Error("team scope not configured — configure memory.team in ~/.thincoder/config.json")
+  if (layer === "team") {
+    if (!opts.team?.dir) throw new Error("team layer not configured — configure memory.team in ~/.thincoder/config.json")
     const filename = await putMarkdown(memory, {
       layer: "team", dir: opts.team.dir,
       type: candidate.type, title: candidate.title, content: candidate.content,
@@ -151,5 +151,5 @@ export async function saveCandidate(memory, candidate, opts = {}) {
     await commitAndPush(opts.team.dir, filename, `memory: [${candidate.type}] ${candidate.title} (distilled)`)
     return `team:${filename}`
   }
-  throw new Error(`unknown scope: ${scope}`)
+  throw new Error(`unknown layer: ${layer}`)
 }

package/src/explore-distill.mjs

@@ -0,0 +1,155 @@
+/**
+ * explore-distill.mjs — End-of-run exploration distillation (AGENT-LOOP §13 +
+ * CONTEXT-COMPACTION §5, 2026-08-23). 2026-09-05 module-split: moved verbatim out of
+ * context.mjs (524 > 500 hard limit). The main agent's machine line is flooded by inline
+ * step-by-step exploration (read/grep/...). At run end we distill THIS run's exploration
+ * tool-results into one semantic summary note that replaces them in the machine line,
+ * while agent._fullHistory (the human line) stays untouched. VS Code compact.mjs
+ * distillation mirrors this module (same-name file in thincoder-vscode/src, cross-repo
+ * parity anchors point here).
+ */
+
+import { chat } from "./provider/index.mjs"
+
+/** Read-only knowledge tools counted as "exploration" (execute writes files → never exploration). */
+export const EXPLORE_TOOLS = new Set([
+  "read", "grep", "glob", "ls", "code_search", "doc_search", "repo_outline",
+])
+
+/** Summary prompt for turning a burst of exploration results into a semantic summary. */
+export const EXPLORE_SUMMARY_PROMPT = `You are distilling exploration tool results. Summarize the following read-only codebase exploration into a compact semantic summary for the main agent's own context.
+
+Requirements:
+- Capture WHAT was discovered, WHERE (which files / directories / symbols), and the KEY CONCLUSIONS — do not list tool calls mechanically
+- Keep actionable facts the main agent needs to continue: code locations, function names, file paths, structure, and open questions the exploration raised
+- Drop raw tool-output noise, repeated lines, and verbatim file dumps — keep only what must be remembered
+- Be honest: mark anything not actually verified as "unverified"; do not present guesses as facts
+- Use bullet points; aim for information completeness, not a hard word limit
+
+Exploration log:
+`
+
+/** tool_calls name across both stored shapes ({function:{name}} and flat {name}). */
+function toolCallName(tc) {
+  return tc?.function?.name ?? tc?.name ?? ""
+}
+
+/** Tool that produced a tool-result message (falls back to its owner assistant's tool_call). */
+function toolResultName(msg, ownerToolCalls) {
+  if (typeof msg?.name === "string" && msg.name) return msg.name
+  const owner = (ownerToolCalls ?? []).find((tc) => tc.id === msg?.tool_call_id)
+  return owner ? toolCallName(owner) : ""
+}
+
+/**
+ * Find the pure-exploration "assistant(tool_calls)→tool…" pair blocks added since `start`.
+ * A block is explorable only when EVERY tool call AND every tool result in it is an exploration
+ * tool — mixed blocks (read + edit in one turn) stay untouched, or we'd orphan the edit pairing.
+ */
+function findExplorationBlocks(history, start) {
+  const blocks = []
+  let i = start
+  while (i < history.length) {
+    const m = history[i]
+    if (m?.role === "assistant" && Array.isArray(m.tool_calls) && m.tool_calls.length > 0) {
+      let j = i + 1
+      while (j < history.length && history[j]?.role === "tool") j++
+      const toolMsgs = history.slice(i + 1, j)
+      const allCallsExplore = m.tool_calls.every((tc) => EXPLORE_TOOLS.has(toolCallName(tc)))
+      const allResultsExplore = toolMsgs.length > 0 && toolMsgs.every((t) => EXPLORE_TOOLS.has(toolResultName(t, m.tool_calls)))
+      if (allCallsExplore && allResultsExplore) {
+        blocks.push({ start: i, end: j, messages: history.slice(i, j), toolCount: toolMsgs.length })
+      }
+      i = j
+    } else {
+      i++
+    }
+  }
+  return blocks
+}
+
+/** Serialize a batch of exploration messages for the summary LLM (same shape as compaction serialization). */
+function serializeExplorationMessages(messages) {
+  const cap = 8000 // exploration results ARE the signal to distill — generous cap (quality-first, N1)
+  return messages
+    .map((m) => {
+      const toolNote = m.tool_calls ? ` [called tools: ${m.tool_calls.map(toolCallName).join(", ")}]` : ""
+      let text = ""
+      if (typeof m.content === "string") text = m.content
+      else if (Array.isArray(m.content)) text = m.content.filter((p) => p?.type === "text").map((p) => p.text ?? "").join(" ")
+      return `[${m.role}]${toolNote} ${text.slice(0, cap)}`
+    })
+    .join("\n")
+}
+
+/**
+ * Core (shared) distillation: replace this run's pure-exploration pair blocks with a single
+ * "[Exploration summary]" note placed where the first block was. Returns a NEW history array,
+ * or null when there is nothing to shrink (<3 exploration results / LLM failure). Pairing-safe:
+ * whole assistant→tool blocks are removed, so no orphan tool_calls/tool can survive.
+ */
+async function distillExplorations(history, start, provider, signal, agent, depth) {
+  if (!Array.isArray(history) || history.length - start < 2) return null
+  const blocks = findExplorationBlocks(history, start)
+  const resultCount = blocks.reduce((n, b) => n + b.toolCount, 0)
+  if (resultCount < 3) return null
+
+  const serialized = blocks.map((b) => serializeExplorationMessages(b.messages)).join("\n")
+
+  let summary
+  try {
+    // Silent by design (D11): thinking:null and no onToken/onReasoning — this internal
+    // distillation must not stream to the frontend. signal propagates user cancellation.
+    const resp = await chat({ ...provider, thinking: null, reasoningEffort: null }, {
+      messages: [{ role: "user", content: EXPLORE_SUMMARY_PROMPT + serialized }],
+      signal,
+      // §18.6 D-TR4：轨迹元数据增补——kind=distill（探索蒸馏面——agent 元数据透出；
+      // depth 经 summarizeRunExplorations 参数透传——agent.mjs 主作用域传入）
+      logCtx: {
+        stage: "distill", child: agent?._logId ?? null, kind: "distill",
+        role: agent?._role ?? null, depth: depth ?? null,
+        session: agent?._sessionStart ?? null, cwd: agent?.cwd ?? process.cwd(),
+        traces: agent?.config?.traces?.enabled !== false,
+      },
+    })
+    summary = resp?.content
+  } catch {
+    return null // N3: never block the run's return or lose history — original results stay
+  }
+  if (!summary) return null
+
+  const drop = new Set()
+  for (const b of blocks) for (let k = b.start; k < b.end; k++) drop.add(k)
+  const note = { role: "user", content: "[Exploration summary]\n" + summary }
+  const next = []
+  let inserted = false
+  for (let k = 0; k < history.length; k++) {
+    if (drop.has(k)) {
+      if (!inserted) { next.push(note); inserted = true }
+      continue
+    }
+    next.push(history[k])
+  }
+  return next
+}
+
+/**
+ * End-of-run exploration distillation (runAgent's final return). Shrinks the MACHINE line
+ * (agent.history) only; agent._fullHistory is never touched. Triggers when this run added ≥3
+ * exploration tool results; on LLM failure it silently keeps the original history (N3).
+ * The distillation itself is silent and never streams (D11); `callbacks.onDistilled` fires
+ * ONLY after the replacement actually lands (never on no-op/failure) — callers persist the
+ * compressed session (SEND-STALL-DISTILL §2.3).
+ */
+export async function summarizeRunExplorations(agent, callbacks, signal, depth = 0) {
+  const next = await distillExplorations(agent.history, agent._runStartHistoryLen ?? 0, agent.provider, signal, agent, depth)
+  if (!next) return
+  agent.history = next
+  // The machine line changed shape — the measured token baseline was for the pre-shrink context.
+  // Invalidate so the next compaction check re-estimates instead of over-counting stale history.
+  agent._lastPromptTokens = null
+  agent._usageAtLen = null
+  // The compressed machine line must reach the disk: the run's own save already happened,
+  // so without this hook the async distill would leave the session un-compressed on exit.
+  callbacks.onDistilled?.()
+}

package/src/memory/code-sync.mjs

@@ -313,7 +313,8 @@ export function codeSearchTool(memory) {
   return {
     name: "code_search",
     description:
-      "Search the project's source code for relevant code. Use this to find functions, classes, or code patterns across the codebase. Supports natural language queries and code snippets. Returns matching code chunks with file paths and line numbers. Prefer doc_search for the intended design (design docs, conventions); code_search for the implementation as written.",
+      "Search the project's source code for relevant code. Use this to find functions, classes, or code patterns across the codebase. Supports natural language queries and code snippets. Returns matching code chunks with file paths and line numbers. Prefer doc_search for the intended design (design docs, conventions); code_search for the implementation as written. " +
+      "For what was said in a session (conversation/chat history), use read_history.",
     parameters: {
       type: "object",
       properties: {