thincoder 0.12.58 → 0.12.59

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
@@ -250,6 +294,14 @@ export async function compressIfNeeded(agent, threshold, callbacks, extras = {},
   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)
@@ -404,7 +456,7 @@ function serializeExplorationMessages(messages) {
  * 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) {
+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)
@@ -419,6 +471,14 @@ async function distillExplorations(history, start, provider, signal) {
     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 {
@@ -449,8 +509,8 @@ async function distillExplorations(history, start, provider, signal) {
  * 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)
+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.

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"
 
@@ -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.
+ * 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 ']'.

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/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,7 @@ 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.",
     parameters: {
       type: "object",
       properties: {

package/src/memory/core.mjs

@@ -272,6 +272,132 @@ export async function list(memory, { type, limit = DEFAULT_LIST_LIMIT } = {}) {
     .all(limit)
 }
 
+/** LIKE pattern from a keyword (wildcards escaped — literal substring match, MEMORY.md §6 keyword filter). */
+function likePattern(keyword) {
+  return `%${keyword.replace(/[\\%_]/g, (c) => `\\${c}`)}%`
+}
+
+/**
+ * Shared row query for the §6 list action and the §6 batch delete (one match surface —
+ * rows carry { layer, id, type, title, ts }). Filters:
+ *   scope: "personal" | "project" | "team" | null (null = all layers)
+ *   type / keyword: optional (keyword matches title OR content, substring)
+ * Personal rows come from the entries table; project/team rows come from a DISK scan of
+ * the managed dir (2026-09-05 fix — disk is the truth): files present on disk but
+ * missing from the files index (orphans: external copies / gitmem pull / an earlier
+ * index failure) were invisible to list AND immune to batch delete — the old table-only
+ * match surface made a scope wipe need repeated delete rounds (deleteWhere→syncDir
+ * re-indexed the orphans one round later). Scanning disk keeps list and batch delete
+ * consistent with what the user can see and delete. Rows from other projects'/team
+ * repos' dirs stay out (the scan only covers the dirs this memory context manages).
+ * Malformed files are skipped (parseEntry failure — same semantics as syncDir). Sorted
+ * by ts (created/updated, ms) DESC.
+ */
+export async function matchMemoryRows(memory, { scope = null, type = null, keyword = null, projectDir = null, teamDir = null } = {}) {
+  const rows = []
+  const wantLayer = (l) => !scope || scope === l
+  if (wantLayer("personal")) {
+    let sql = `SELECT id, type, title, created_at AS ts FROM entries`
+    const cond = []
+    const params = []
+    if (type) { cond.push("type = ?"); params.push(type) }
+    if (keyword) { cond.push("(title LIKE ? ESCAPE '\\' OR content LIKE ? ESCAPE '\\')"); const p = likePattern(keyword); params.push(p, p) }
+    if (cond.length) sql += " WHERE " + cond.join(" AND ")
+    sql += " ORDER BY created_at DESC"
+    for (const r of memory.db.prepare(sql).all(...params)) {
+      rows.push({ layer: "personal", id: `personal:${r.id}`, uid: `personal:${r.id}`, type: r.type, title: r.title, ts: r.ts })
+    }
+  }
+  if (wantLayer("project") && projectDir) {
+    for (const r of await diskFileRows(projectDir, type, keyword)) rows.push({ ...r, layer: "project", id: `project:${projectDir}:${r.path}` })
+  }
+  if (wantLayer("team") && teamDir) {
+    for (const r of await diskFileRows(teamDir, type, keyword)) rows.push({ ...r, layer: "team", id: `team:${teamDir}:${r.path}` })
+  }
+  rows.sort((a, b) => (b.ts ?? 0) - (a.ts ?? 0))
+  return rows
+}
+
+/**
+ * Disk-truth file scan for the project/team layer (2026-09-05 fix — see matchMemoryRows):
+ * readdir + parse every .md entry in dir, filter by type equality and keyword substring
+ * on title OR content (case-insensitive — SQLite LIKE parity). ts = file mtime (ms).
+ * Rows come back WITHOUT the layer field — the caller stamps layer and builds the uid.
+ */
+async function diskFileRows(dir, type, keyword) {
+  let names
+  try {
+    names = (await readdir(dir)).filter((n) => n.endsWith(".md"))
+  } catch {
+    return []
+  }
+  const kw = keyword ? keyword.toLowerCase() : null
+  const out = []
+  for (const name of names) {
+    try {
+      const abs = join(dir, name)
+      const { meta, content } = parseEntry(await readFile(abs, "utf8"))
+      if (type && meta.type !== type) continue
+      if (kw && !(meta.title.toLowerCase().includes(kw) || content.toLowerCase().includes(kw))) continue
+      const mtime = Math.floor((await stat(abs)).mtimeMs)
+      out.push({ path: name, type: meta.type, title: meta.title, ts: mtime })
+    } catch (e) {
+      console.error(`[memory] skip ${name}: ${e.message}`)
+    }
+  }
+  out.sort((a, b) => b.ts - a.ts)
+  return out
+}
+
+/**
+ * §6 batch delete (action delete + type/keyword filter, confirm handled by the tool layer):
+ * deletes every row matchMemoryRows returns for the scope. Personal rows go straight to the
+ * DB (FTS + embedding cleanup via row triggers); project/team rows delete the markdown file
+ * (path containment enforced, ENOENT tolerated) then re-sync the layer dir once (index
+ * cleanup single source). Match surface = disk scan (2026-09-05 fix — orphans on disk
+ * with no index row are matched and deleted in the same pass; the trailing syncDir
+ * re-indexes the survivors). Team deletion never touches git — a later gitmem pull may
+ * resurrect the file while the remote still has it (same semantics as deleteByUid).
+ * Returns the number of deleted rows.
+ */
+export async function deleteWhere(memory, { scope, type = null, keyword = null } = {}, { dirs = {} } = {}) {
+  const rows = await matchMemoryRows(memory, { scope, type, keyword, projectDir: dirs.project ?? null, teamDir: dirs.team ?? null })
+  if (rows.length === 0) return 0
+  const personalIds = []
+  const byDir = new Map() // "layer\x00dir" → { layer, dir, paths: [] }
+  for (const r of rows) {
+    if (r.layer === "personal") {
+      const id = Number(String(r.uid).split(":")[1])
+      if (Number.isInteger(id)) personalIds.push(id)
+      continue
+    }
+    const dir = r.layer === "project" ? dirs.project : dirs.team
+    if (!dir) continue
+    const key = `${r.layer}\x00${dir}`
+    let group = byDir.get(key)
+    if (!group) { group = { layer: r.layer, dir, paths: [] }; byDir.set(key, group) }
+    group.paths.push(r.path)
+  }
+  const del = memory.db.prepare(`DELETE FROM entries WHERE id = ?`)
+  for (const id of personalIds) del.run(id)
+  for (const group of byDir.values()) {
+    for (const path of group.paths) {
+      assertPathInside(group.dir, path)
+      const abs = join(group.dir, path)
+      await unlink(abs).catch((e) => { if (e.code !== "ENOENT") throw e })
+    }
+    await syncDir(memory, { layer: group.layer, dir: group.dir })
+  }
+  return rows.length
+}
+
+/** §6 clear action: wipe ALL personal entries (pure DB rows — files are project/team only).
+ *  FTS + embedding go with the row triggers. Returns the number of deleted rows. */
+export function clearPersonal(memory) {
+  const { changes } = memory.db.prepare(`DELETE FROM entries`).run()
+  return changes
+}
+
 /** Delete a memory entry by unified id. Returns the deleted entry (F3: { id, layer, type, title, content, tags }).
  *  - personal:<n> (or bare <n>) → DELETE the entries row; FTS syncs via the entries_ad trigger and the
  *    embedding BLOB column goes with the row.