thincoder 0.12.58 → 0.12.60

package/src/cli/make-agent.mjs

@@ -3,9 +3,12 @@ import { join } from "node:path"
 import { createAgent } from "../agent.mjs"
 import { loadConfig, configDir } from "../config.mjs"
 import { createMemory, memoryTools, syncDir, codeSearchTool, docSearchTool } from "../memory.mjs"
+import { settingsTool } from "../agent-tools/settings.mjs"
 import { repoOutlineTool } from "../tools/repomap.mjs"
 import { builtinTools } from "../tools/index.mjs"
 import { discoverRules } from "../rules.mjs"
+// R10 L2（MULTI-INSTANCE-COLLAB §2a.4 D-L2b）：peer_instances 只读工具——挂感知模块导出
+import { peerInstancesTool } from "../peer-instances.mjs"
 
 /** Assemble an agent with memory, MCP tools, and code/doc indices attached (sync all layers, then return) */
 export async function assembleAgent() {
@@ -48,7 +51,7 @@ export async function assembleAgent() {
     await ensureClone(team)
     await syncDir(memory, { layer: "team", dir: team.dir })
   }
-  const baseTools = [...builtinTools, ...memoryTools(memory, { cwd, projectDir: config.memory.projectDir, author: gitAuthor(), team }), codeSearchTool(memory), docSearchTool(memory), repoOutlineTool(memory.db, cwd)]
+  const baseTools = [...builtinTools, ...memoryTools(memory, { cwd, projectDir: config.memory.projectDir, author: gitAuthor(), team }), codeSearchTool(memory), docSearchTool(memory), repoOutlineTool(memory.db, cwd), settingsTool(), peerInstancesTool]
 
   // MCP servers: connect in parallel (a dead server won't block startup), collect failures as warnings (stderr invisible in TUI, passed via agent object)
   const mcpServers = config.mcp?.servers ?? []

package/src/cli/memory-command.mjs

@@ -1,7 +1,8 @@
 import { join } from "node:path"
 import { loadConfig } from "../config.mjs"
 import { teamConfig } from "./make-agent.mjs"
-import { put, search, list, deleteByUid } from "../memory/core.mjs"
+import { put, search, list } from "../memory/core.mjs"
+import { deleteByUid } from "../memory/delete.mjs"
 
 /** thincoder memory <list|search|put|remove> subcommands.
  *  opts.dirs: { project, team } layer directories for project/team file deletion (tests inject their own);

package/src/cli/permission.mjs

@@ -19,7 +19,14 @@ export function formatPermission(name, args) {
   }
   if (base === "delete") return `${args.path}${args.force ? "（force：跟踪文件也删）" : ""}`
   if (base === "subagent") return cap(args.task ?? "", 500)
-  if (base === "memory_put") return `[${args.type ?? ""}] ${args.title ?? ""}\n${cap(args.content ?? "", 500)}`
+  if (base === "memory") {
+    // §6 action-routed preview: put shows content, batch delete/clear show the gate args
+    const action = String(args.action ?? "")
+    if (action === "put") return `[${args.type ?? ""}] ${args.title ?? ""}\n${cap(args.content ?? "", 500)}`
+    if (action === "delete") return args.id ? `id=${args.id}${args.layer ? ` layer=${args.layer}` : ""}` : `batch delete layer=${args.layer ?? ""} type=${args.type ?? ""} keyword=${args.keyword ?? ""} confirm=${args.confirm}`
+    if (action === "clear") return `clear layer=${args.layer ?? ""} confirm=${args.confirm}`
+    return cap(summarize(args), 300)
+  }
   return cap(summarize(args), 300)
 }
 

package/src/cli/setup-wizard.mjs

@@ -1,6 +1,5 @@
-import { existsSync, readFileSync } from "node:fs"
 import { createInterface } from "node:readline"
-import { configPath, saveConfig, PROVIDER_PRESETS } from "../config.mjs"
+import { configPath, writeConfigAtomic, PROVIDER_PRESETS } from "../config.mjs"
 
 /** First-time setup (TTY chat / distill): ask a few questions to configure a provider, save to disk, return runtime provider. Cancel returns null. */
 export async function setupWizard() {
@@ -52,16 +51,22 @@ export async function setupWizard() {
       return null
     }
     const embedKey = (await ask("Optional: embedding API key (SiliconFlow, for vector search; press Enter to skip): ")).trim()
-    const raw = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf8")) : {}
-    const providers = raw.providers?.length ? raw.providers : []
-    const existing = providers.find((p) => p.name === name)
-    if (existing) Object.assign(existing, { baseURL, model, apiKey })
-    else providers.push({ name, baseURL, model, apiKey })
-    raw.providers = providers
-    raw.activeProvider = name
-    delete raw.activeModel  // reset to default model
-    if (embedKey) raw.embedding = { ...(raw.embedding ?? {}), apiKey: embedKey }
-    saveConfig(raw)
+    // D-F5b：磁盘新鲜读 → mutate → mtime 门控写（writeConfigAtomic 收口）；冲突 = 放弃
+    // + 提示重试（首配场景另有实例同时写盘——极低概率；不自动合并——决策点① A）
+    const r = writeConfigAtomic(configPath, (raw) => {
+      const providers = raw.providers?.length ? raw.providers : []
+      const existing = providers.find((p) => p.name === name)
+      if (existing) Object.assign(existing, { baseURL, model, apiKey })
+      else providers.push({ name, baseURL, model, apiKey })
+      raw.providers = providers
+      raw.activeProvider = name
+      delete raw.activeModel  // reset to default model
+      if (embedKey) raw.embedding = { ...(raw.embedding ?? {}), apiKey: embedKey }
+    })
+    if (!r.ok) {
+      console.error("config changed on disk concurrently — retry")
+      return null
+    }
     console.error(`Configured: ${name} / ${model} (saved to ${configPath})`)
     console.error(embedKey ? "Vector search enabled\n" : "(No embedding key configured: memory search will use text-only FTS. Add embedding.apiKey to config.json to enable vector search later.)\n")
     return { name, baseURL, model, apiKey }

package/src/config.mjs

@@ -5,9 +5,9 @@
  * API key can fall back to environment variables (when not configured in providers).
  */
 
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
 import { homedir } from "node:os"
-import { join } from "node:path"
+import { dirname, join } from "node:path"
 
 export const configDir = join(homedir(), ".thincoder")
 export const configPath = join(configDir, "config.json")
@@ -55,6 +55,14 @@ export const DEFAULTS = {
     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 — read METHODOLOGY.md, design-before-code
+    // Async subagent pool limits per role domain (AGENT-LOOP.md §24 D-24a/R14):
+    // { engCoder, other } — eng-coder pool / other-role pool, defaults 4/4 (user
+    // ruling "eng-coder 四路，其他 4 路"). Runtime-validated at every pool admission
+    // (positive integer ≥1, invalid/absent keys fall back to 4 — settings tool and
+    // the /config 并发池 menu write this key; change applies to the next spawn).
+    // ⚠ 与 subagent-async.mjs ASYNC_POOL_LIMITS 逐键同值（运行时回退常量）——耦合锚
+    // T-24a4 断言锁住——勿单侧改默认。
+    poolLimits: { engCoder: 4, other: 4 },
   },
   memory: {
     dbPath: join(configDir, "memory.db"),
@@ -73,6 +81,10 @@ export const DEFAULTS = {
     provider: "tavily",  // structured search API; empty apiKey → fall back to Bing HTML scraping
     apiKey: "",          // Tavily key (tvly-...) — optional
   },
+  traces: {
+    enabled: false,  // §18.6 D-TR6 修订（2026-09-05 用户裁定——发布隐私："不希望用户那边也采集"）：轨迹存档默认 OFF——新用户零采集；本地调试分析可显式开（~/.thincoder/config.json traces.enabled:true）
+    retentionHours: 24, // D-TR10：轨迹文件保留小时数——CLI 启动时删除超过该时长的文件（默认 24h）
+  },
 }
 
 // Model capability table + spec lookup live in model-specs.mjs (2026-08-31
@@ -195,6 +207,7 @@ export function loadConfig() {
     agent: { ...DEFAULTS.agent, ...config.agent },
     memory: { ...DEFAULTS.memory, ...config.memory },
     embedding: { ...DEFAULTS.embedding, ...config.embedding },
+    traces: { ...DEFAULTS.traces, ...config.traces },
   }
 
   // providers[].context (K units, PROVIDER.md §15 D-C1): positive integer only — invalid
@@ -363,12 +376,52 @@ function mcpFingerprint(s) {
 }
 
 /**
- * Save configuration. Preserves providers list structure and activeProvider pointer.
- * providers[i].apiKey is only written when explicitly passed in (does not overwrite env-var-fallback keys).
+ * R10 F5（D-F5b，2026-09-06）——config.json 写前 mtime 门控收口函数（session-rename
+ * mtime-conflict 先例同型——MULTI-INSTANCE-COLLAB.md §2a.2）。所有 config.json 写点
+ * （config-helpers persistRaw / cmd-config saveProxy / cli setup-wizard / settings
+ * writeDisk）都经它落盘。
+ *
+ * 本函数持有整条「新鲜读 → mutate 单操作 → 写前重 stat → 写」链：
+ * - t0 = 写前重 stat 的比对基线，取在**新鲜读之前**（stat→read 序）：若对端在本端
+ *   stat 与 read 之间的微窗口写入，只会造成假冲突（放弃重试），绝不会带着旧内容覆盖
+ *   对端新值——read→stat 序存在漏检窗口（stat 已反映对端新 mtime → 门控放行旧内容）。
+ * - 写前重 stat ≠ t0 → **放弃**本次写（D-F5a 后各流已是 fresh 单操作语义，磁盘上对端
+ *   的新值保持在线不抹）；先 copy `.bak-{ts}` 留现场（仅冲突时——config 低频写不膨胀；
+ *   copy 而非 rename：冲突即放弃、本体不动，"保现场"是额外副本，非轮转腾位）。
+ * - 返回 { ok:false, reason:"mtime-conflict" }，调用方提示 "config changed on disk
+ *   concurrently — retry"——不自动合并（config 是用户显式操作——重试比猜测合并安全，
+ *   决策点① A）。
+ * - 文件缺失（首写）→ t0 = null；对端在本端读后创建 → null ≠ 新 mtime → 冲突放弃。
+ * - 畸形文件拒写（throw，绝不静默覆盖）；写后 chmod 0600 尽力而为（saveConfig 旧语义）。
+ *
+ * @param path config.json 路径（生产默认 configPath；测试注入 tmp 路径）
+ * @param mutate 在磁盘新鲜 raw 上执行单操作的同步回调（如 push/splice/单字段补丁）
+ * @returns { ok: true } | { ok: false, reason: "mtime-conflict" }
  */
-export function saveConfig(config) {
-  mkdirSync(configDir, { recursive: true })
+export function writeConfigAtomic(path, mutate) {
+  const mtimeOf = (p) => {
+    try { return statSync(p).mtimeMs } catch { return null } // 缺失 → null（t0 比对基线）
+  }
+  const t0 = mtimeOf(path) // stat 先于 read（安全方向——见头注释）
+  const text = existsSync(path) ? readFileSync(path, "utf8") : null
+  let raw = {}
+  if (text !== null) {
+    try {
+      raw = JSON.parse(text)
+    } catch (error) {
+      throw new Error(`config file not parseable — refusing to overwrite: ${path} — ${error.message}`, { cause: error })
+    }
+  }
+  mutate(raw)
+  const t1 = mtimeOf(path)
+  if (t0 !== t1) {
+    // 对端在我们新鲜读后改过磁盘 → 放弃本次写（对端内容保持在线）；.bak 副本留现场
+    try { if (existsSync(path)) copyFileSync(path, `${path}.bak-${Date.now()}`) } catch { /* 现场保留失败不阻断冲突报告 */ }
+    return { ok: false, reason: "mtime-conflict" }
+  }
+  mkdirSync(dirname(path), { recursive: true })
   // 0600: config.json contains API keys, must not be world-readable (POSIX; chmod is best-effort on Windows)
-  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", { encoding: "utf8", mode: 0o600 })
-  try { chmodSync(configPath, 0o600) } catch { /* may fail on Windows, ignore */ }
+  writeFileSync(path, JSON.stringify(raw, null, 2) + "\n", { encoding: "utf8", mode: 0o600 })
+  try { chmodSync(path, 0o600) } catch { /* may fail on Windows, ignore */ }
+  return { ok: true }
 }

package/src/context.mjs

@@ -37,9 +37,13 @@ export function estimateTokens(messages) {
 const KEEP_HEAD = 0 // No dedicated head: earliest messages may be a COMPLETED earlier task in multi-task
 // sessions — keeping them verbatim anchored attention on stale work. Everything before the tail is
 // summarized (the summary itself distinguishes completed vs in-progress work; see SUMMARIZE_PROMPT).
-// Tail size scales with the model context window (~30 messages per 100K tokens),
-// capped at 40% of history so small histories don't over-reserve. Window-adaptive
-// replaces the old fixed 10: on a 1M window, 10 messages is too thin for recent work.
+// Tail count formula (D4): window-adaptive (~30 msgs per 100K — old fixed 10 too thin on 1M), capped
+// at 40% of history; §9 D-T1/D-T2 make the count only a CANDIDATE — a token budget (TAIL_BUDGET_FRACTION
+// × window − SUMMARY_TOKEN_ESTIMATE ≈1K, §8) tightens it over pair-safe boundaries when compaction runs,
+// never below TAIL_FLOOR_MESSAGES; ordinary sessions never reach it (D-T4: trigger 0.6 untouched).
+const TAIL_BUDGET_FRACTION = 0.15
+const SUMMARY_TOKEN_ESTIMATE = 1000 // §8: summary output target ~1K tokens — reserved from the 15%
+const TAIL_FLOOR_MESSAGES = 10 // §9 D-T2: the tail keeps ≥10 verbatim messages — floor beats budget
 function keepTailSize(provider, historyLen) {
   // provider is guaranteed at every call site (runAgent always builds one); providerSpec
   // degrades to DEFAULT_SPEC (128K) only if provider is somehow absent — acceptable
@@ -48,6 +52,10 @@ function keepTailSize(provider, historyLen) {
   const ctxWindow = providerSpec(provider).context
   return Math.min(Math.max(10, Math.floor((ctxWindow / 100_000) * 30)), Math.floor(historyLen * 0.4))
 }
+// §9 D-T1 tail token budget: window×15% − summary ~1K — the compressed history segment (summary + placeholder + tail) lands ≈ 15% (B 口径 §9.5).
+function tailBudgetTokens(provider) {
+  return Math.max(0, Math.floor(providerSpec(provider).context * TAIL_BUDGET_FRACTION) - SUMMARY_TOKEN_ESTIMATE)
+}
 
 export const SUMMARIZE_PROMPT = `You are a conversation compressor. Summarize the following agent work log into a compact summary for use as context in the ongoing conversation.
 Requirements:
@@ -59,7 +67,7 @@ Requirements:
 - Explicitly list UNRESOLVED ISSUES / TODOs: anything still open plus the next steps — so post-compaction recovery knows where to resume
 - Drop: pleasantries, repetition, fine-grained tool output details
 - Honestly mark uncertain items: anything not actually verified must say "unverified"; do not present guesses as facts
-- Use bullet-point output; aim for information completeness, not a hard word limit (old 500-char cap is deprecated; in a 1M-context era, err on the long side)
+- Use bullet-point output. Stay under ~1K tokens (≈1000 Chinese chars / 4000 ASCII chars) — a hard target. An oversized summary wastes window and dilutes the tail; the old unbounded-length guidance is deprecated. When over budget, trim in this order: completed recaps to one line; FILES CHANGED why-notes to bare paths; in-progress prose tightened. NEVER cut design anchors or UNRESOLVED ISSUES/TODOs — recovery depends on them.
 
 Work log:
 `
@@ -68,7 +76,7 @@ Work log:
 const COMPACTION_PREFIX =
   "[Context was automatically compacted. Below is a summary of earlier work. " +
   "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"
+  "but re-verify transient state with tools. Check memory search for any missing decisions.]\n\n"
 
 /** 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
@@ -84,12 +92,13 @@ const FALLBACK_NOTE =
 
 /**
  * Split history into head / middle (to be summarized) / tail; return null if no middle to compress.
- * head is normally empty (KEEP_HEAD = 0 — earliest messages go into the summary); the
- * tool_calls-extension logic below is defensive for future KEEP_HEAD > 0.
- * The tail boundary must include any assistant whose tool results are in the tail — if the assistant is in the middle,
- * the summary swallows it, leaving orphan tool results → protocol 400.
+ * head is normally empty (KEEP_HEAD = 0 — earliest messages go into the summary); the tool_calls-extension logic below is defensive for future KEEP_HEAD > 0.
+ * The tail boundary must include any assistant whose tool results are in the tail — if the assistant is in the middle, the summary swallows it, leaving orphan tool results → protocol 400.
+ * `budgetTokens` (optional, §9 D-T1): when the candidate's estimate exceeds it, the boundary moves
+ * forward until the tail fits — never below the D-T2 floor (10 msgs, or the candidate itself when
+ * the 40% cap made it < 10 — short history).
  */
-function splitHistory(history, keepTail) {
+function splitHistory(history, keepTail, budgetTokens = null) {
   if (history.length <= KEEP_HEAD + keepTail + 1) return null
   let headEnd = KEEP_HEAD
   // head must not end with dangling tool_calls: when assistant declares tool_calls, all its tool results must stay in head.
@@ -97,10 +106,24 @@ function splitHistory(history, keepTail) {
   if (history[headEnd - 1]?.role === "assistant" && history[headEnd - 1].tool_calls?.length) {
     while (headEnd < history.length && history[headEnd].role === "tool") headEnd++
   }
-  let tailStart = history.length - keepTail
+  const candidate = repairedTailStart(history, headEnd, history.length - keepTail)
+  if (candidate <= headEnd) return null
+  let tailStart = candidate
+  // §9 D-T1: tighten only above the floor — a candidate ≤ 10 IS the floor (short history under the 40% cap must not tighten further, review #5); the floor is D5-repaired too.
+  if (budgetTokens > 0 && keepTail > TAIL_FLOOR_MESSAGES) {
+    const floor = repairedTailStart(history, headEnd, history.length - TAIL_FLOOR_MESSAGES)
+    if (floor > candidate) tailStart = tightenTailByBudget(history, candidate, floor, budgetTokens)
+  }
+  return { headEnd, tailStart }
+}
 
-  // Tool messages in the tail region whose assistant tool_calls are in the middle: the summary would swallow the assistant,
-  // leaving orphan tool results → protocol 400. Collect tool_call_ids from the tail, find their owner assistants and pull them into tail
+/**
+ * D5 tail-side pairing repair for a raw cut at history.length − tailCount: pull into the tail any
+ * assistant whose tool results are in the tail (the summary swallowing the owner leaves orphan tool
+ * results → protocol 400), then skip orphan tool messages at the new boundary. Single-assistant
+ * assumption (nearest owner only — a tail spans at most one assistant→tools cycle); bounds-guarded.
+ */
+function repairedTailStart(history, headEnd, tailStart) {
   const tailToolIds = new Set()
   for (let i = tailStart; i < history.length; i++) {
     if (history[i].role === "tool") tailToolIds.add(history[i].tool_call_id)
@@ -112,16 +135,28 @@ function splitHistory(history, keepTail) {
       break
     }
   }
-
-  // skip orphan tool messages at the new tail boundary (tool whose assistant was pulled in above)
-  // NOTE: single-assistant assumption — the backwards scan pulls the nearest owner only; in
-  // practice a tail spans at most one assistant→tools cycle (parallel calls share one assistant).
-  // Bounds-guarded so an all-tool tail cannot push tailStart past history.length.
   while (tailStart < history.length && tailStart > headEnd && history[tailStart].role === "tool") {
     tailStart++
   }
-  if (tailStart <= headEnd) return null
-  return { headEnd, tailStart }
+  return tailStart
+}
+
+/**
+ * §9 D-T1 budget tightening (pair-safe, review #2): walk the boundary FORWARD (fewer tail messages —
+ * the rest joins the summary) while the tail's estimated tokens exceed the budget. Only pair-safe
+ * positions may stop the walk: a boundary ON a tool message would orphan its owner assistant into the
+ * middle (D5); pairing is contiguous in the machine line (§6 note) — every non-tool boundary is safe.
+ * No fit before the floor → keep the floor, accept the overrun.
+ */
+function tightenTailByBudget(history, start, floorStart, budgetTokens) {
+  const suffixTokens = new Array(history.length + 1)
+  suffixTokens[history.length] = 0
+  for (let i = history.length - 1; i >= 0; i--) suffixTokens[i] = suffixTokens[i + 1] + estimateTokens([history[i]])
+  if (suffixTokens[start] <= budgetTokens) return start // already fits — ordinary sessions stay untouched (D-T2)
+  for (let p = start + 1; p <= floorStart; p++) { // first fit keeps the most recent verbatim context
+    if (history[p].role !== "tool" && suffixTokens[p] <= budgetTokens) return p
+  }
+  return floorStart
 }
 
 /**
@@ -132,9 +167,14 @@ function splitHistory(history, keepTail) {
  * 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 §9 D-S1): 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).
  */
 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)
   agent.history.push(msg)
 }
@@ -148,10 +188,14 @@ function applyCompression(agent, headEnd, tailStart, note) {
   // possibly-completed earlier requests.
   const head = agent.history.slice(0, headEnd)
   const tail = agent.history.slice(tailStart)
+  // SESSION.md §9 D-S1: compaction-injected messages (note + "Understood") carry a ts —
+  // Date.now() at the compaction moment. They are machine-only (never in _fullHistory),
+  // but the machine-line timeline stays consistent for any audit use.
+  const now = Date.now()
   agent.history = [
     ...head,
-    { role: "user", content: note },
-    { role: "assistant", content: "Understood. I'll continue from these notes, re-verifying anything transient." },
+    { role: "user", content: note, ts: now },
+    { role: "assistant", content: "Understood. I'll continue from these notes, re-verifying anything transient.", ts: now },
     ...tail,
   ]
   // Compaction REBUILDS the machine line (head + note + "Understood" + tail), so the pre-compaction
@@ -217,7 +261,7 @@ export async function compressIfNeeded(agent, threshold, callbacks, extras = {},
   if (tokens <= threshold) return false
 
   const keepTail = keepTailSize(agent.provider, history.length)
-  const split = splitHistory(history, keepTail)
+  const split = splitHistory(history, keepTail, tailBudgetTokens(agent.provider))
   if (!split) {
     // History is too short (≤KEEP_HEAD+keepTail+1 messages) to find a middle section, but tokens exceed threshold — typically a single giant message
     // (large paste / huge injection). When summarization has no room, degrade to deterministic shrinking to ensure context always reduces
@@ -243,13 +287,21 @@ 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()
   const summary = await chat({ ...agent.provider, thinking: null, reasoningEffort: null }, {
     messages: [{ role: "user", content: SUMMARIZE_PROMPT + serialized }],
     signal,
+    // §18.6 D-TR4：轨迹元数据增补——kind=compress（上下文构建面——agent 元数据透出；
+    // depth 经 extras.traceDepth——agent.mjs 主作用域传入——compress 调用点补齐）
+    logCtx: {
+      stage: "compress", child: agent._logId, kind: "compress",
+      role: agent._role ?? null, depth: extras?.traceDepth ?? null,
+      session: agent._sessionStart ?? null, cwd: agent.cwd,
+      traces: agent.config?.traces?.enabled !== false,
+    },
   })
 
   applyCompression(agent, split.headEnd, split.tailStart, COMPACTION_PREFIX + summary.content)
@@ -272,7 +324,7 @@ export async function compressIfNeeded(agent, threshold, callbacks, extras = {},
  */
 export function compressFallback(agent) {
   const keepTail = keepTailSize(agent.provider, agent.history.length)
-  const split = splitHistory(agent.history, keepTail)
+  const split = splitHistory(agent.history, keepTail, tailBudgetTokens(agent.provider))
   if (!split) return false
   const tailMessages = agent.history.length - split.tailStart
   applyCompression(agent, split.headEnd, split.tailStart, FALLBACK_NOTE)
@@ -322,142 +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.
-
-/** 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) {
-  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,
-    })
-    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（2026-09-05 module-split：524 > 500 硬限——verbatim
+// 迁至 explore-distill.mjs，语义零变——VS Code compact.mjs 同款联动；cross-repo parity 锚改指
+// explore-distill.mjs——消费方 import 面不变（re-export））───────────────────────
 
-/**
- * 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) {
-  const next = await distillExplorations(agent.history, agent._runStartHistoryLen ?? 0, agent.provider, signal)
-  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"