thincoder 0.12.54 → 0.12.59

package/src/tools/read_pdf.md

@@ -0,0 +1,21 @@
+Read a PDF file and extract its text as plain text — page by page, in reading order (row/column layout, `--- Page N ---` separators). Use this instead of `read` for `.pdf` files: read decodes PDFs as UTF-8 garbage.
+
+**Route to read_pdf instead of bash:** `pdftotext`, python `pypdf`/`pdfminer`, node pdf libraries → read_pdf (zero-dependency built-in extractor).
+
+Parameters:
+- path (required): PDF file path (relative to cwd or absolute).
+- pages: which pages to extract, e.g. `"1-3,5"` (1-based PDF page numbers, ranges inclusive). Default: all pages; at most 50 pages per call (larger documents need a `pages` selection).
+
+What it handles:
+- Text PDFs from real producers: Chrome/Edge print, Word, LibreOffice, LaTeX, Quartz — xref tables and xref streams, object streams, Flate + PNG predictors, Type0/CID fonts with ToUnicode CMaps (bfchar/bfrange), simple fonts via WinAnsi/StandardEncoding/MacRoman (+ /Differences), TJ kerning, ligature ActualText spans, and double/triple-column layout (light x-cluster column detection; tables are NOT reconstructed — table cell text reads in row/column flow).
+- Scanned/image-only pages (no text operators): the page image is returned via the multimodal channel (`{ text, images }` JSON, like read_image) so a vision-capable model can read it. DCTDecode (JPEG) images pass through; 8-bit Flate gray/RGB images are converted to PNG. This needs a multimodal (vision) provider — under a text-only model such pages degrade to a hint telling you to switch providers.
+
+Limits & refusals (explicit, never silent):
+- Text-only results follow the read-family pipeline: extraction over 64KB is saved to the standard offload file (preview + path returned — page the file with read). When scanned-page images are attached, the JSON envelope rides the multimodal channel inline; text is capped at 60KB and images at 25MB cumulative per call (per-image 15MB) — narrow the pages range to read large scans in batches.
+- Encrypted PDFs (/Encrypt) are refused with a clear message — decrypt first.
+- Unsupported forms (Type3 glyph runs without ToUnicode, symbolic fonts without mappings, LZW-compressed streams, CMap-preset fonts without ToUnicode, JBIG2/JPX/CCITT images, palette/CMYK images) produce warnings or inline notes — output is best-effort and never silently wrong.
+- Files >100MB refused; results never inflate past 512MB per stream (hostile-PDF guards: xref chains, recursion, operand floods).
+
+Notes:
+- Extraction is text-layer only — it does not OCR. Scanned pages without a text layer rely on the multimodal image channel.
+- Layout is best-effort for irregular designs (rotated text, complex tables, text boxes).

package/src/tools/repomap.mjs

@@ -297,7 +297,7 @@ export function repoOutlineTool(db, cwd) {
   return {
     name: "repo_outline",
     description:
-      "Show the project's file dependency outline: which files import/export from which, and what symbols they export. Use when you need to understand the project structure, find where a function is defined, or see what files depend on a module. Pass a path to focus on a single file's relationships.",
+      "Show the project's file dependency outline: which files import/export from which, and what symbols they export. Use when you need to understand the project structure, find where a function is defined, or see what files depend on a module. Pass a path to focus on a single file's relationships. Find code by keyword or snippet with code_search.",
     parameters: {
       type: "object",
       properties: {

package/src/tools/shared.mjs

@@ -5,7 +5,7 @@
 
 import { spawn, execFileSync, execFile } from "node:child_process"
 import { readFileSync, existsSync, realpathSync, readdirSync, statSync, openSync, readSync, closeSync } from "node:fs"
-import { dirname, join, resolve, relative, isAbsolute, sep } from "node:path"
+import { dirname, join, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -170,7 +170,7 @@ export function toOpenAISchema(tool) {
 /** Strip ANSI escape sequences */
 export function sanitizeOutput(s) {
   return s
-  // eslint-disable-next-line no-control-regex -- 有意为之：控制字符协议/转义序列剥离正则（ANSI/⟦ev⟧/SGR/history 双线分隔）
+    // 有意为之：控制字符协议/转义序列剥离正则（ANSI/⟦ev⟧/SGR/history 双线分隔）
     .replace(/\x1b\[[0-9;?]*[\x40-\x7E]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[()][0-9A-B]|\x1b[=>#][0-9]?/g, "")
     .replace(/\r\n/g, "\n")
     .replace(/\r/g, "\n")
@@ -276,27 +276,14 @@ function realCwd(cwd) {
   return realCwdCache.get(cwd)
 }
 
-/** Assert that a resolved path is inside cwd; throws on escape */
-function assertInside(cwd, resolved, p) {
-  // relative() returns platform-native separators; ".." + sep therefore
-  // matches both / and \ traversal on the respective platform.
-  const rel = relative(cwd, resolved)
-  if (isAbsolute(rel) || rel === ".." || rel.startsWith(".." + sep)) {
-    throw new Error(`Access denied outside working directory: ${p}`)
-  }
-}
-
-/** Resolve a user-supplied path relative to cwd, asserting it stays within cwd */
+/** Resolve a user-supplied path relative to cwd — no directory boundary assertion
+ *  (§10.1 2026-09-02: workspace confinement removed; resolveInCwd ≡ resolveExternal,
+ *  trust model + approval gate is the only guard — same boundary as bash). */
 export function resolveInCwd(ctx, p) {
-  const cwd = realCwd(ctx.cwd)
-  const resolved = resolve(cwd, p)
-  assertInside(cwd, resolved, p)
-  const real = realpathNearest(resolved)
-  assertInside(cwd, real, p)
-  return resolved
+  return resolveExternal(ctx, p)
 }
 
-/** Resolve a path relative to cwd without boundary check — use only when the user explicitly provides an external path */
+/** Resolve a path relative to cwd without boundary check — kept for compatibility (≡ resolveInCwd) */
 export function resolveExternal(ctx, p) {
   const cwd = realCwd(ctx.cwd)
   return resolve(cwd, p)
@@ -309,8 +296,8 @@ export function shellSegments(command) {
 
 /**
  * Blank out quoted regions (single/double/backtick) with spaces, preserving length.
- * Lets safety checks ignore shell metacharacters inside quoted script bodies —
- * e.g. `node -e "if (a > b) …"` comparisons are not redirections.
+ * Lets detectDanger ignore shell metacharacters inside quoted script bodies —
+ * e.g. `node -e "if (a > b) …"` comparisons are not danger signals.
  */
 function blankQuoted(command) {
   let out = ""
@@ -321,8 +308,8 @@ function blankQuoted(command) {
       if (ch === "\\" && quote !== "'") { out += " "; i++; out += " "; continue }
       if (ch === quote) { quote = null; out += " "; continue }
       // Backticks are COMMAND SUBSTITUTION — the content executes, so it must
-      // stay visible to the redirection check (echo `cat > /tmp/x` writes a
-      // file). Only ' and " are literal regions.
+      // stay visible to detectDanger (echo `cat > /tmp/x` still runs). Only '
+      // and " are literal regions.
       out += quote === "`" ? ch : " "
     } else if (ch === "'" || ch === '"' || ch === "`") {
       quote = ch
@@ -334,14 +321,6 @@ function blankQuoted(command) {
   return out
 }
 
-/** Detect shell output/input redirection (> >> < followed by filename) outside quoted regions.
- *  Backtick contents count (command substitution executes); fd-prefixed forms
- *  (2> file, 1>> file) count too. */
-export function hasFileRedirection(command) {
-  const bare = blankQuoted(command)
-  return /(^|[\s;&|0-9])>{1,2}\s*\S/.test(bare) || /(^|[\s;&|0-9])<\s*\S/.test(bare)
-}
-
 /**
  * Whether a single command segment is destructive — ALWAYS FALSE (deliberate).
  *

package/src/tools/system.mjs

@@ -6,7 +6,6 @@ import {
   BASH_TIMEOUT_MS,
   IGNORED_DIRS,
   resolveInCwd,
-  hasFileRedirection,
   globToRegex,
   normalizeEOL,
 } from "./shared.mjs";
@@ -51,20 +50,6 @@ function posixSyntaxHint(command) {
 // bash — command execution with safety gates
 // ====================================================================
 
-/**
- * Pre-execution safety checks for bash commands.
- * Layers: file redirection (guides toward structured tools, not a security gate).
- * Destructive commands (rm -rf, DROP TABLE, ...) are deliberately NOT rejected:
- * a determined model bypasses text matching anyway — real security is at the
- * tool approval layer plus snapshot backups (gitGuardSnapshot / checkpoint).
- * Git destructive ops: snapshot-then-proceed, never block.
- */
-function checkBashSafety(command, cwd) {
-  if (hasFileRedirection(command)) {
-    throw new Error("File redirection via bash is not allowed — use the write/edit/insert_after tools instead")
-  }
-}
-
 /**
  * Build environment for child process.
  * Passes through all parent env vars, with non-interactive overrides (EDITOR/PAGER/TERM).
@@ -113,11 +98,12 @@ function killProcessTree(child) {
  * cannot help (it was taken before the code was written); only a snapshot taken
  * immediately before the destructive command can.
  *
- * This is layer 1 (defense in depth): a WIDE match that snapshots before the command
- * runs. Layer 2 (checkBashSafety) then rejects the command when uncommitted changes
- * exist — but a rejection alone is not enough: the model may retry a variant that
- * slips through the exact matcher (e.g. `git checkout HEAD -- .`), or run git outside
- * the bash tool. The snapshot taken here survives all of those paths.
+ * This is the defense-in-depth guard: a WIDE match that snapshots before the command
+ * runs — the command itself is NEVER blocked (a determined model bypasses text
+ * matching anyway; the real gate is the approval layer). A snapshot alone is not
+ * enough: the model may retry a variant that slips through the exact matcher
+ * (e.g. `git checkout HEAD -- .`), or run git outside the bash tool. The snapshot
+ * taken here survives all of those paths.
  *
  * Matching is intentionally WIDE (false positives are harmless — one extra snapshot;
  * a missed match is a data-loss disaster).
@@ -266,7 +252,6 @@ export const bashTool = {
     // guard anyway. Instead: snapshot every uncommitted file first, then ALLOW
     // the command. The snapshot makes the rollback reversible (defense in depth:
     // the wide matcher also covers variants like `git checkout HEAD -- .`).
-    checkBashSafety(args.command, ctx.cwd)
     const guard = await gitGuardSnapshot(args.command, ctx.cwd)
     const result = await runBash(args.command, ctx.cwd, {
       timeout: args.timeout ?? BASH_TIMEOUT_MS,

package/src/tools/tree.md

@@ -10,4 +10,5 @@ Parameters:
 Notes:
 - Capped at 200 entries.
 - Directories end with `/`; tree-drawing uses `├──`/`└──`/`│`.
-- Use depth for a shallow overview; use `ls` for one directory, `glob` for a specific file pattern.
+- Use depth for a shallow overview; use `ls` for one directory, `glob` for a specific file pattern.
+- Returns the directory text tree — directories first (`dir/`), files after, both sorted, capped at 200 entries.

package/src/tools/web.mjs

@@ -4,6 +4,8 @@ import { proxyFetch } from "../proxy.mjs";
 
 export const UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
 const FETCH_TIMEOUT = 15_000
+// §14 D-TF3：网络失败错误文本追加 proxy 提示——纯文本提示，不自动路由（2026-08-31 裁定：proxy 显式传不自动应用）
+const PROXY_HINT = "network failure — retry with proxy: 'http://host:port' if the target is blocked"
 
 // ── Web search (Bing; direct by default, through proxy when configured and web toggle on) ──
 
@@ -204,19 +206,19 @@ export const fetchTool = {
             const r = resolveRedirectTarget(loc, args.url)
             if (r.error) throw new Error(`fetch failed: ${r.error}`)
             const r2 = await proxyFetch(r.target, { headers: { "User-Agent": UA } }, proxyUri)
-            if (!r2.ok) throw new Error(`fetch failed: HTTP ${r2.status}`)
+            if (!r2.ok) throw new Error(`fetch failed: HTTP ${r2.status}\n${PROXY_HINT}`)
             const ct2 = headerOf(r2, "content-type") ?? ""
             const b2 = await r2.text()
             if (ct2.includes("text/html")) { const t = htmlToText(b2); return truncate(t + detectSparseHtml(b2, t)) }
             return truncate(b2)
           }
         }
-        throw new Error(`fetch failed: HTTP ${response.status}`)
+        throw new Error(`fetch failed: HTTP ${response.status}\n${PROXY_HINT}`)
       }
       const ct = headerOf(response, "content-type") ?? ""
       const body = await response.text()
       if (ct.includes("text/html")) { const t = htmlToText(body); return truncate(t + detectSparseHtml(body, t)) }
       return truncate(body)
-    } catch (e) { throw new Error(`fetch failed: ${e.cause?.code ?? e.message}`, { cause: e }) }
+    } catch (e) { throw new Error(`fetch failed: ${e.cause?.code ?? e.message}\n${PROXY_HINT}`, { cause: e }) }
   },
 }

package/src/tools/websearch.md

@@ -8,7 +8,8 @@ Parameters:
 - proxy: http://host:port explicit proxy (optional) — use ONLY when passed; no proxy = direct. config.json proxy is NOT auto-applied (2026-08-31 ruling); Bing/foreign sites usually need a proxy, domestic targets don't
 
 Notes:
-- Before searching the web, call `memory_search` first — you may already know the answer from a previous session. Only reach for websearch if memory comes up empty.
+- Before searching the web, call the memory tool (action: search) first — you may already know the answer from a previous session. Only reach for websearch if memory comes up empty.
+- Runs synchronously — returns when the search completes (all selected engines run in parallel).
 - Use this for information that is NOT in the local codebase — current docs, error messages, API references
 - Follow up with `fetch` to read full pages from the results
 - **Weak engine warning**: Bing's index is noisy for technical queries — if a first websearch returns irrelevant/townhall-grade results, DO NOT retry the same query. Configure a search MCP tool (e.g. `glm-websearch` via the MCP config) for technical lookups; websearch is the fallback.

package/src/tools/write.md

@@ -5,5 +5,7 @@ Parameters:
 - content (required): Full content to write
 
 Notes:
+- write replaces the WHOLE file — read it first and confirm you intend to rewrite it entirely; for a small change use edit / insert_after.
+- Returns `Wrote N chars to <path>` + git diff + syntax-check note.
 - This overwrites the entire file — use `edit` for targeted changes
 - The file is atomic: it either writes completely or fails

package/src/traces/trace-store.mjs

@@ -0,0 +1,224 @@
+/**
+ * trace-store.mjs — §18.6 完整轨迹存档（AGENT-LOOP.md §18.6 D-TR1..TR8 权威规格）。
+ *
+ * 完整请求-响应轨迹落盘：每次 chat() 调用一个 JSONL 文件到
+ * ~/.thincoder/traces/YYYY-MM-DD/<sessionKey>-<seq>.jsonl。采集点唯一 = core.mjs
+ * chat() 导出出口（所有模型调用——主回合/消化轮/compress/distill/advisor/子代理/
+ * auto-think/consult——都经该函数）——续写/重试在出口已合并（reasoning 全量）。
+ *
+ * 纪律（与 log.mjs 同源惯例）：
+ * - 真 fire-and-forget（F-TR3——模型调用路径零额外阻塞）：seq 同步预留（原子号位），
+ *   写盘异步（node:fs/promises——不 await）；落盘失败静默降级（不抛错、不阻塞
+ *   chat() 返回）。recordChatTrace 返回落盘 promise——仅供测试/显式消费方 await。
+ * - 测试隔离：node --test 进程（NODE_TEST_CONTEXT）默认不写盘——防测试事件污染真实
+ *   轨迹目录（既有测试跑真实 agent 管线会产生数百次 chat 调用）；显式设置
+ *   THINCODER_TRACES_DIR 强制写入该目录（traces.test.mjs 用它隔离临时目录——
+ *   与 log.mjs 的 THINCODER_LOG_DIR 同惯例）。
+ * - 脱敏（D-TR2）：复用 log.mjs 字段名黑名单（apikey/designtoken/password/secret/
+ *   token/authorization/proxyuri/proxy）+ SECRET_FORM 形态扫描（redactSecret）——对
+ *   messages/content/reasoning/toolCalls/error 全字段递归应用；不发明新遮蔽模式。
+ * - 容量有界（N-TR1）：单条轨迹一个文件，大小不限（"成本不是问题"——不截断、不
+ *   脱漏行）；目录按日组织（YYYY-MM-DD），可按日/会话过滤；不自动清理（D-TR8——
+ *   清理机制记 docs/TODO.md 技术组）。
+ * - seq = 当日目录内最大已有 seq + 1（D-TR3——跨会话/进程重启不覆写既有旧轨迹——
+ *   18.6.1 评审 #3）。
+ * - 日期分日按本地时区（D-TR3——2026-09-04 fix round1：初版 toISOString()=UTC——
+ *   本地 00:00-08:00 的调用会落进前一日目录——改本地日期字符串 YYYY-MM-DD——T-TR12）。
+ * - isContinuation（D-TR1——2026-09-04 fix round1）：续写/重试链标记——true = 该调用
+ *   是续写链的一环（core.mjs 续写递归传出 logCtx.isContinuation）；新调用 false。
+ *   记录不输出 round 字段（全设计无 round 定义——删——不发明无来源字段）。
+ */
+import { readdirSync, existsSync } from "node:fs"
+import { appendFile, mkdir, readdir, stat, unlink, rmdir } from "node:fs/promises"
+import { join } from "node:path"
+import { createHash } from "node:crypto"
+import { configDir } from "../config.mjs"
+import { redactSecret, errText, classifyErr } from "../log.mjs"
+import { normalizeCwd } from "../session-slots.mjs"
+
+/** 轨迹根目录：THINCODER_TRACES_DIR（测试隔离/override——同 THINCODER_LOG_DIR
+ *  惯例）> ~/.thincoder/traces（configDir——D-TR3——与 sessions/ 同域）。 */
+export function tracesRoot() {
+  return process.env.THINCODER_TRACES_DIR ?? join(configDir, "traces")
+}
+
+/** 写门（测试隔离）：test runner 进程（NODE_TEST_CONTEXT）默认跳过——除显式
+ *  THINCODER_TRACES_DIR override（traces.test.mjs 隔离临时目录）。 */
+function writeEnabled() {
+  if (process.env.NODE_TEST_CONTEXT && !process.env.THINCODER_TRACES_DIR) return false
+  return true
+}
+
+/** sessionKey = sha1(normalizeCwd(cwd))[:12]（D-TR3——与 session-slots sessionPath
+ *  同算法同 cwd 归一——两端 hash 一致）。 */
+export function traceSessionKey(cwd) {
+  return createHash("sha1").update(normalizeCwd(cwd)).digest("hex").slice(0, 12)
+}
+
+/** 本地时区日期字符串 YYYY-MM-DD（D-TR3——2026-09-04 fix round1：初版
+ *  toISOString()=UTC 日期——本地 00:00-08:00 落前一日目录；本地日期才是用户视角的
+ *  "今天"——T-TR12）。recordChatTrace 与测试读取 helpers 共用同一实现——不双写。 */
+export function localDateStr(date = new Date()) {
+  const y = date.getFullYear()
+  const m = String(date.getMonth() + 1).padStart(2, "0")
+  const d = String(date.getDate()).padStart(2, "0")
+  return `${y}-${m}-${d}`
+}
+
+/** Test hooks（_rateHooks 同惯例——rate.mjs：测试可替换 now——T-TR12 注入本地日 ≠
+ *  UTC 日的时刻验证分日；生产永远走真实时钟）。 */
+export const _traceHooks = {
+  now: () => new Date(),
+}
+
+/** 当日轨迹目录（D-TR3：traces/YYYY-MM-DD——分日组织——N-TR1）。 */
+export function tracesDirFor(dateStr) {
+  return join(tracesRoot(), dateStr)
+}
+
+// 进程内 seq 预留表：同步预留（原子——异步写盘在途时并发调用不撞号）；键 = 目录。
+// 跨进程/重启由磁盘 max 兜底（同键无预留时磁盘值即事实——T-TR10）。
+const _reservedSeq = new Map()
+
+/** seq = max(当日目录最大已有 seq, 进程内已预留) + 1（D-TR3——跨会话/进程重启
+ *  不覆写——T-TR8/T-TR10；同步预留 = 异步写盘启动前的原子号位分配）。 */
+export function nextTraceSeq(dateStr) {
+  const dir = tracesDirFor(dateStr)
+  let max = 0
+  if (existsSync(dir)) {
+    let names
+    try {
+      names = readdirSync(dir)
+    } catch {
+      // 目录不可读——按预留表续号（不静默撞号）
+      max = _reservedSeq.get(dir) ?? 0
+      _reservedSeq.set(dir, max + 1)
+      return max + 1
+    }
+    for (const name of names) {
+      const m = name.match(/-(\d+)\.jsonl$/)
+      if (m) max = Math.max(max, Number(m[1]))
+    }
+  }
+  const seq = Math.max(max, _reservedSeq.get(dir) ?? 0) + 1
+  _reservedSeq.set(dir, seq)
+  return seq
+}
+
+/** 开关（D-TR6）：traces.enabled 缺省 on（默认全采集）；logCtx.traces === false
+ *  显式关闭（调用点读取 agent.config.traces.enabled——D-TR6）。 */
+export function tracesEnabled(logCtx) {
+  return logCtx?.traces !== false
+}
+
+/** 递归脱敏（D-TR2）：对 messages/content/reasoning/toolCalls/error 全字段应用——
+ *  字段名命中黑名单 → 遮蔽；字符串内容命中密钥形态（sk-/Bearer/-key=）→ 截断到
+ *  形态前 + 标记。数组/对象递归（消息 content 可为 parts 数组、toolCalls 嵌套）。 */
+function redactValue(fieldKey, value) {
+  if (typeof value === "string") return redactSecret(fieldKey, value)
+  if (Array.isArray(value)) return value.map((v) => redactValue(fieldKey, v))
+  if (value && typeof value === "object") {
+    const out = {}
+    for (const [k, v] of Object.entries(value)) out[k] = redactValue(k, v)
+    return out
+  }
+  return value
+}
+
+/**
+ * 收集一次 chat 调用轨迹（D-TR1 字段集）——fire-and-forget（F-TR3）。
+ * 由 core.mjs chat() 导出出口调用（唯一采集点——N-TR2）；签名零参数膨胀——
+ * 数据全部来自调用方已传入的 opts（logCtx 元数据——D-TR4）+ provider + result/error。
+ *
+ * @param {Object} provider chat() 的 provider 参数（provider/model 字段来源）
+ * @param {Object} opts chat() 原始 opts —— messages（输入）与 logCtx（元数据：
+ *   role/depth/kind/session/cwd/stage/turn/traces——调用点增补，D-TR4）
+ * @param {Object|null} result chatImpl 返回值（成功路径——content/reasoning/
+ *   toolCalls/usage/finishReason；N-TR3：出口汇总——续写/重试后全量）
+ * @param {Error|null} error chat() 抛出的错误（失败路径——D-TR5：error（errText
+ *   截断 + 类别）+ finishReason:null——失败轨迹恰是分析纠结点最有效的材料）
+ */
+export function recordChatTrace(provider, opts = {}, result = null, error = null) {
+  if (!writeEnabled()) return
+  const logCtx = opts.logCtx ?? {}
+  if (!tracesEnabled(logCtx)) return
+  // cwd/session 经 logCtx 增补（调用点传 agent.cwd / agent._sessionStart——
+  // D-TR3 的 cwdHash/命名与 D-TR1 的 session 字段所需）；无 agent 作用域的调用点
+  // 回退 process.cwd()——CLI 会话即工作区。该类点开关状态：distill 已含
+  // traces 开关（D-TR6 fix round1）；auto-think 已闭环（D-TS12——chat 调用点
+  // logCtx 全字段补传：traces/session/cwd/role/depth/kind——无残留点）。
+  const cwd = logCtx.cwd ?? process.cwd()
+  // D-TR3（fix round1）：分日按本地时区（_traceHooks.now——T-TR12 注入点）；
+  // ts 与 dateStr 同源（同一时刻）——记录时间戳与目录日不撕裂。
+  const now = _traceHooks.now()
+  const dateStr = localDateStr(now)
+  const seq = nextTraceSeq(dateStr)
+  const sessionKey = traceSessionKey(cwd)
+  const record = {
+    ts: now.toISOString(),
+    session: logCtx.session ?? null,
+    cwdHash: createHash("sha1").update(normalizeCwd(cwd)).digest("hex"),
+    role: logCtx.role ?? null,
+    depth: logCtx.depth ?? null,
+    turn: logCtx.turn ?? null,
+    provider: provider?.name ?? provider?.model ?? "unknown",
+    model: provider?.model ?? "",
+    stage: logCtx.stage ?? null,
+    kind: logCtx.kind ?? null,
+    // D-TR1（fix round1）：续写/重试链标记——true = 该调用是续写链的一环
+    // （core.mjs 续写递归传出）；新调用缺省 false——round 字段已删（无来源）。
+    isContinuation: logCtx.isContinuation === true,
+    messages: redactValue("messages", opts.messages ?? []),
+    content: redactValue("content", result?.content ?? null),
+    reasoning: redactValue("reasoning", result?.reasoning ?? null),
+    toolCalls: redactValue("toolCalls", result?.toolCalls ?? null),
+    usage: result?.usage ?? null,
+    finishReason: result?.finishReason ?? null,
+  }
+  if (error != null) {
+    // D-TR5：错误路径轨迹——error（errText 截断 + 类别）+ finishReason:null
+    record.error = {
+      err: redactValue("err", errText(error, 500)),
+      kind: classifyErr(error, opts.signal),
+    }
+  }
+  // 真 fire-and-forget（F-TR3——模型调用路径零额外阻塞）：seq 已在上面同步预留
+  // （原子号位——写盘在途并发不撞号）；写盘异步（不 await——chat() 出口立即返回）。
+  // 返回值 = 落盘 promise（测试 await 用；chat() 不消费——fire-and-forget 语义）。
+  return (async () => {
+    try {
+      const dir = tracesDirFor(dateStr)
+      await mkdir(dir, { recursive: true }) // D-TR3：写前建目录（与 sessions/tool-results 同惯例）
+      await appendFile(join(dir, `${sessionKey}-${seq}.jsonl`), JSON.stringify(record) + "\n", "utf8")
+    } catch {
+      // F-TR3：落盘失败静默降级——不抛错、不阻塞 chat() 返回
+    }
+  })()
+}
+
+/**
+ * D-TR10（2026-09-05 用户裁定——发布隐私 + 磁盘卫生）：启动清理——删除 traces 根下
+ * mtime 超过保留期的轨迹文件（保留期 = config.traces.retentionHours，默认 24h）；
+ * 删空的日期目录（YYYY-MM-DD）。目录里非 .jsonl 文件不碰。CLI 启动点 fire-and-forget
+ * 调用（不 await——不阻塞启动——失败静默——与轨迹写盘同纪律）。返回删除文件数。
+ */
+export async function cleanupTraces({ dir = tracesRoot(), retentionHours = 24 } = {}) {
+  const cutoff = Date.now() - retentionHours * 3_600_000
+  let days
+  try { days = await readdir(dir) } catch { return 0 } // 目录不存在/不可读 → 无事可做
+  let removed = 0
+  for (const day of days) {
+    const dayDir = join(dir, day)
+    try { if (!(await stat(dayDir)).isDirectory()) continue } catch { continue }
+    let names
+    try { names = await readdir(dayDir) } catch { continue }
+    for (const n of names) {
+      if (!n.endsWith(".jsonl")) continue
+      try {
+        if ((await stat(join(dayDir, n))).mtimeMs < cutoff) { await unlink(join(dayDir, n)); removed++ }
+      } catch { /* 单个文件失败不影响其余 */ }
+    }
+    try { if ((await readdir(dayDir)).length === 0) await rmdir(dayDir) } catch {}
+  }
+  return removed
+}