thincoder 0.12.58 → 0.12.60

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

@@ -5,6 +5,7 @@
  */
 
 import { chat } from "./provider/index.mjs"
+import { loadConfig } from "./config.mjs"
 import { put, putMarkdown } from "./memory.mjs"
 import { commitAndPush } from "./git/gitmem.mjs"
 
@@ -17,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"
   }
 ]
 
@@ -26,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")
@@ -39,13 +40,30 @@ If the session is long, prioritize conclusions that appeared last and are still
 Session log:
 `
 
+/** §18.6 D-TR6（2026-09-04 fix round1）：distill 调用点无 agent 作用域——traces 开关
+ *  缺省回退磁盘配置（loadConfig——与 agent.config 同源：traces.enabled 缺省 on）；
+ *  配置不可读时按缺省 on（注：CLI 启动早已 loadConfig——此处仅是兜底防御）。 */
+function tracesEnabledFromConfig() {
+  try {
+    return loadConfig().traces?.enabled !== false
+  } catch {
+    return true
+  }
+}
+
 /**
  * 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() 出口不落盘。
  */
-export async function extractCandidates(provider, transcript) {
+export async function extractCandidates(provider, transcript, opts = {}) {
+  const traces = opts.traces ?? tracesEnabledFromConfig()
   const res = await chat(provider, {
     messages: [{ role: "user", content: DISTILL_PROMPT + transcript }],
+    // §18.6 D-TR4/D-TR6（fix round1）：distill 调用经 chat() 唯一采集点——补轨迹
+    // 元数据 + traces 开关透传（关=不落盘必须全覆盖——不再静默越过开关）
+    logCtx: { stage: "distill", kind: "distill", traces },
   })
   // Balanced-bracket extraction: find the first '[' and track depth through nested
   // brackets (tags arrays, nested objects, etc.) until the matching ']'.
@@ -99,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,
@@ -123,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,
@@ -133,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/escape.mjs

@@ -131,13 +131,15 @@ export function escapeMessageContent(message) {
   return changed ? next : message
 }
 
-/** IKBGX4 (2026-08-28)：剥离仅本地使用的整消息标记字段（transient 等）——发送给 provider 前移除。
+/** IKBGX4 + SESSION.md §9 D-S1：剥离仅本地使用的整消息标记字段（transient/ts）——发送给 provider 前移除。
  * 严格 OpenAI 兼容服务端（opencode/LiteLLM 等）会拒绝消息级未知 key
- * （"Extra inputs are not permitted, field: 'messages[i].transient'"）。 */
+ * （"Extra inputs are not permitted, field: 'messages[i].transient'"）；ts 同理
+ * （消息时间戳是本地取证字段，不进任何 provider 请求——T-S3）。copy-on-write：
+ * 历史里的原对象不动（read_history 仍能读到 ts）。 */
 export function stripLocalMessageFields(messages) {
   return messages.map((m) => {
-    if (m && typeof m === "object" && "transient" in m) {
-      const { transient, ...rest } = m
+    if (m && typeof m === "object" && ("transient" in m || "ts" in m)) {
+      const { transient, ts, ...rest } = m
       return rest
     }
     return m

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/log.mjs

@@ -0,0 +1,195 @@
+/**
+ * log.mjs — 诊断事件日志（docs/design/LOGGING.md 权威规格）。
+ * 双端同构：thincoder/src/log.mjs 与 thincoder-vscode/src/log.mjs 同一实现语义
+ * （共享 ~/.thincoder/logs/、同格式、同事件面——F-L6）。
+ *
+ * 常驻骨架日志：回合/LLM/工具/子代理/挂起的关键事件——每行一个 JSON 事件，按天轮转
+ * （agent-YYYY-MM-DD.log），保留 1 天——用户零手动维护（F-L3/NF-L4）。问题发生时
+ * 直接 tail/grep 定位断点（根治"临时插桩再删"循环）。
+ *
+ * 纪律（实现侧逐条落实）：
+ * - fire-and-forget：logEvent 失败静默降级（NF-L1）——主流程零影响。进程内首次写失败
+ *   即置死（_dead），当日不再尝试（磁盘满/权限错不逐事件空转）。
+ * - 单事件行 <512 字符（NF-L2）：head（LLM ≤300 / 工具 ≤200）、err ≤200 由调用方截断，
+ *   本模块对任意字符串字段做上限兜底（head 300 / err 200 / 其余 120）+ 超长时丢可选字段。
+ * - 敏感字段零落盘（NF-L3/§2.4，2026-09-03 评审 refinement #7 匹配语义定稿）：
+ *   ① 字段名精确匹配黑名单（apiKey/designToken/password/secret/token，大小写不敏感；
+ *      另加防御性名称 authorization/proxy/proxyUri——防凭据型 URL/头字段泄漏——§2.5）
+ *      → 整个字段丢弃；
+ *   ② 内容只扫密钥形态（sk-xxx / Bearer xxx / key=… 等）→ 截断到形态之前
+ *      ——宁可丢信息不漏密钥。
+ *   工具事件不记 args；URL 不入事件（llm/tool 事件从不携带 URL；err 文本经形态扫描）。
+ * - 摘要截断（B 方案，2026-09-03 用户裁定）：截断处带 "…" 标记（截后仍 ≤上限）。
+ * - 测试隔离：node --test 进程（NODE_TEST_CONTEXT）默认不写盘——防测试事件污染真实
+ *   诊断日志（两端测试套件都会跑真实 agent 管线）；显式设置 THINCODER_LOG_DIR 强制
+ *   写入该目录（log.test.mjs 用它隔离临时目录——refinement #6）。
+ * - 轮转清理（refinement #3——长驻进程覆盖）：非仅启动时——每进程每日**首次写事件**
+ *   时顺带清理 >1 天的 agent-*.log（extension host 可长驻数月，启动清理覆盖不到）。
+ * - seq：每进程单调计数器。双端同写一个文件时 seq 会各自重复——定位同文件时序以
+ *   ts 为准，seq 仅进程内参照（refinement #8）。
+ */
+
+import { appendFileSync, mkdirSync, readdirSync, rmSync, existsSync, statSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+/** 单行长度硬上限（NF-L2） */
+export const MAX_LINE = 512
+/** 字段名精确黑名单（NF-L3/§2.4——2026-09-03 评审 refinement #7：与 §2.4 词表一致含 token） */
+const BLACKLIST_FIELDS = new Set(["apikey", "designtoken", "password", "secret", "token", "authorization", "proxyuri", "proxy"])
+/** 内容密钥形态扫描（大小写不敏感）——命中即截断到形态前 */
+const SECRET_FORM = /(\bsk-[A-Za-z0-9_-]{6,}|\bBearer\s+[A-Za-z0-9._~+/=-]{6,}|\b(?:api[_-]?key|key|token|secret|password|pwd|passwd)\s*[=:]\s*['"]?[A-Za-z0-9._~+/=-]{6,})/i
+/** 字符串字段长度兜底：head ≤300 / err ≤200 / 其余 ≤120 */
+const FIELD_CAPS = { head: 300, err: 200 }
+
+let _seq = 0
+let _dead = false // 进程内写失败即死（NF-L1 静默降级——不逐事件重复空转）
+let _cleanupDate = null // 本进程已执行过清理的日期（每日首次写时清一次）
+
+/** 日志目录：THINCODER_LOG_DIR（测试隔离/override）> ~/.thincoder/logs（与 sessions/ 同域） */
+export function logsDir() {
+  return process.env.THINCODER_LOG_DIR ?? join(homedir(), ".thincoder", "logs")
+}
+
+/** 今日日志文件路径（agent-YYYY-MM-DD.log） */
+export function todayLogPath(now = new Date()) {
+  const ymd = now.toISOString().slice(0, 10)
+  return join(logsDir(), `agent-${ymd}.log`)
+}
+
+/** 写门（测试隔离）：test runner 进程（NODE_TEST_CONTEXT）默认跳过——除显式
+ *  THINCODER_LOG_DIR override（log.test.mjs 隔离临时目录——refinement #6）。 */
+function writeEnabled() {
+  if (_dead) return false
+  if (process.env.NODE_TEST_CONTEXT && !process.env.THINCODER_LOG_DIR) return false
+  return true
+}
+
+/** 清理 >1 天的 agent-*.log（NF-L4——refinement #3：机会式，非仅启动时）。
+ *  保留窗口（2026-09-03 code review #1 修正）：以文件名日期的**当日结束**为龄基准——
+ *  今天+昨天的文件保留（任何事件至少留存 24h、最多 48h），早于昨天的删除。
+ *  无法按名解析日期的 agent-*.log 按 mtime 兜底（>1 天未写的删除）。
+ *  导出供测试直呼（T-L7/T-L7b）。静默：任何失败都不影响主流程。 */
+export const LOG_RETENTION_MS = 24 * 60 * 60 * 1000
+export function cleanupOldLogs(now = new Date()) {
+  const dir = logsDir()
+  if (!existsSync(dir)) return
+  let names
+  try {
+    names = readdirSync(dir)
+  } catch {
+    return
+  }
+  for (const name of names) {
+    if (!name.startsWith("agent-") || !name.endsWith(".log")) continue
+    const m = name.match(/^agent-(\d{4}-\d{2}-\d{2})\.log$/)
+    const ts = m ? Date.parse(m[1] + "T00:00:00Z") : NaN
+    // 文件名日期 → 龄以该日结束（ts+24h）计：事件在删除时至少已留存 24h
+    const ageMs = Number.isFinite(ts) ? now - (ts + LOG_RETENTION_MS) : (tryStatAge(dir, name, now) ?? Infinity)
+    if (ageMs > LOG_RETENTION_MS) {
+      try { rmSync(join(dir, name), { force: true }) } catch { /* 静默 */ }
+    }
+  }
+}
+
+function tryStatAge(dir, name, now) {
+  try {
+    return now - statSync(join(dir, name)).mtimeMs
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 写入一条事件（fire-and-forget）。fields 内所有字符串都经黑名单/截断处理。
+ * 事件行结构：{"ts":ISO,"ev":kind,"seq":N,...fields}——单行 JSON <512 字符。
+ */
+export function logEvent(kind, fields = {}) {
+  if (!writeEnabled()) return
+  const now = new Date()
+  // 机会式轮转清理：每进程每日首次写事件时执行一次（refinement #3——长驻进程覆盖）
+  const ymd = now.toISOString().slice(0, 10)
+  if (_cleanupDate !== ymd) {
+    _cleanupDate = ymd
+    cleanupOldLogs(now)
+  }
+  const entry = { ts: now.toISOString(), ev: kind, seq: ++_seq }
+  for (const [k, v] of Object.entries(fields ?? {})) {
+    if (v === undefined || v === null) continue
+    // ① 字段名精确黑名单 → 丢弃（token 族永不落盘）
+    if (BLACKLIST_FIELDS.has(String(k).toLowerCase())) continue
+    if (typeof v === "string") entry[k] = sanitizeString(k, v)
+    else if (typeof v === "number" || typeof v === "boolean") entry[k] = v
+  }
+  let line = JSON.stringify(entry)
+  // ② 防御性收尾（NF-L2）：字段上限后仍超长 → 丢可选字段（保留 ts/ev/seq）直至 <512
+  while (line.length > MAX_LINE && Object.keys(entry).length > 3) {
+    for (const k of Object.keys(entry)) {
+      if (k !== "ts" && k !== "ev" && k !== "seq") { delete entry[k]; break }
+    }
+    line = JSON.stringify(entry)
+  }
+  try {
+    const dir = logsDir()
+    mkdirSync(dir, { recursive: true })
+    appendFileSync(join(dir, `agent-${ymd}.log`), line + "\n", "utf8")
+  } catch {
+    _dead = true // NF-L1：写失败静默降级——主流程零影响
+  }
+}
+
+/** 共享脱敏（§18.6 D-TR2——trace-store 复用；logEvent 自身保持"丢弃字段"语义，
+ *  本函数提供"遮蔽标记"语义——同一字段名黑名单 + 同一 SECRET_FORM 形态扫描，
+ *  不发明新遮蔽模式）。字段名命中黑名单 → "[REDACTED]（整个字段遮蔽）；内容命中
+ *  密钥形态 → 截断到形态前 + "[redacted]" 标记（宁可丢信息不漏密钥——§2.4）。 */
+export function redactSecret(fieldKey, value) {
+  const s = String(value)
+  if (BLACKLIST_FIELDS.has(String(fieldKey).toLowerCase())) return "[REDACTED]"
+  const hit = s.match(SECRET_FORM)
+  return hit ? s.slice(0, hit.index) + "[redacted]" : s
+}
+
+/** 内容级净化：密钥形态截断到形态前（②）；超长截断 + "…" 标记。 */
+export function sanitizeString(key, value) {
+  let s = String(value)
+  // 密钥形态 → 截断到形态前（宁可丢信息不漏密钥——§2.4）
+  const hit = s.match(SECRET_FORM)
+  if (hit) s = s.slice(0, hit.index)
+  const cap = FIELD_CAPS[key] ?? 120
+  if (s.length > cap) s = s.slice(0, cap - 1) + "…"
+  return s
+}
+
+/** 错误文本提取：message + cause 链首条、压成单行、≤max（默认 200——NF-L2/§2.2） */
+export function errText(err, max = 200) {
+  let msg = err?.message ?? String(err ?? "")
+  if (!msg && err?.cause) msg = String(err.cause)
+  if (err?.cause?.message && !/^LLM API error/.test(msg)) msg += ` (${err.cause.message})`
+  msg = msg.replace(/\s*\n\s*/g, " ").trim()
+  if (msg.length > max) msg = msg.slice(0, max - 1) + "…"
+  return msg
+}
+
+/** 错误 kind 分类（llm:error 字段）：timeout（网关超时/超时信号）/ abort（用户中止）/
+ *  error（其余——API/网络/未分类）。signal 为请求中止信号（chat 调用点直传）。 */
+export function classifyErr(err, signal) {
+  const msg = String(err?.message ?? "").toLowerCase() + " " + String(err?.cause?.message ?? "").toLowerCase()
+  if (/timeout|timed ?out|etimedout|time limit exceeded/i.test(msg)) return "timeout"
+  if (err?.name === "AbortError" || signal?.aborted) {
+    return signal?.reason?.name === "TimeoutError" ? "timeout" : "abort"
+  }
+  return "error"
+}
+
+/** 文本头截取：前 max 字符、单行化（JSON 单行约束）、截断带 "…" 标记。
+ *  paragraph=true（llm:done 响应头）：取首段（首个空行前）——B 方案"首段文本"语义。 */
+export function headText(text, max, { paragraph = false } = {}) {
+  let s = String(text ?? "")
+  if (paragraph) {
+    const p = s.split(/\n\s*\n/, 1)[0]
+    if (p.length < s.length) s = p
+  }
+  s = s.replace(/\s*\n+\s*/g, " ").trim()
+  if (s.length > max) s = s.slice(0, max - 1) + "…"
+  return s
+}

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.",
+      "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: {