@thincoder/core 0.9.4 → 0.10.1

package/tools/ops.mjs

@@ -1,8 +1,10 @@
 /**
- * ops.mjs — operational tools: file_ops (move/copy/rename), process (list),
+ * ops.mjs — operational tools: file_ops (move/copy/rename), process (list/kill),
  * get_current_time, wait_for (condition wait). Each exists so the model reaches
  * for a dedicated tool instead of shelling out to `bash` for the same operation
  * (parity with thinworker).
+ * #9：process 收编 `kill`（靶 = pid ∥ 后台 bash 任务 id——欠面收正：原须绕 bash taskkill）；
+ * wait_for 条件族 +`bash id:N done`。list ∥ 既有条件面零变。
  */
 import { DESC, resolveInCwd, truncate } from "./shared.mjs"
 // 单一写路径点（编辑器编辑径注入缝——CORE-UNIFICATION §2.13.5）：路径操作也经它落盘
@@ -51,11 +53,21 @@ export const processTool = {
   parameters: {
     type: "object",
     properties: {
-      name: { type: "string", description: "Optional name substring filter (case-insensitive)" },
+      action: { type: "string", enum: ["list", "kill"], description: "list (default) — show running processes; kill — terminate a process tree (target: pid) or a background bash task (target: id)" },
+      name: { type: "string", description: "Optional name substring filter for list (case-insensitive)" },
+      pid: { type: "number", description: "kill target: process id — the whole tree is terminated (taskkill /T /F on win32; POSIX group kill)" },
+      id: { type: "number", description: "kill target: background bash task id (bash#N from the bash async ack)" },
     },
   },
-  readonly: true,
-  async execute({ name }, ctx) {
+  // #9：动作分级——list 保持只读分类（dispatch-gates `isSubagentReadonlyAction`：planMode 放行/
+  // 免审批）；kill 是破坏性动作（审批门）。`parallel` 保既有调度形（list 恒可批并行）。
+  readonly: false,
+  parallel: true,
+  async execute(args = {}, ctx = {}) {
+    const action = args?.action ?? "list"
+    if (action === "kill") return await executeKill(args, ctx)
+    if (action !== "list") return `Error: action must be list | kill (got "${action}")`
+    const { name } = args
     const filter = typeof name === "string" && name.trim() ? name.trim().toLowerCase() : null
     let rows
     try {
@@ -69,6 +81,24 @@ export const processTool = {
   },
 }
 
+/** #9 kill 执行体（靶 = pid ∥ 后台任务 id 二选一；两靶皆树杀）。动态 import（W8 契约②：
+ *  agent-tools 链静态达 node:sqlite——端壳静态闭包须保持零命中）。 */
+async function executeKill({ pid, id }, ctx) {
+  const hasPid = pid !== undefined && pid !== null && String(pid).trim() !== ""
+  const hasId = id !== undefined && id !== null && String(id).trim() !== ""
+  if (hasPid === hasId) {
+    return "Error: kill requires exactly one target — pid (process id) or id (background bash task id)"
+  }
+  const { killBgTask, killBgPid } = await import("../agent-tools/bash-async.mjs")
+  if (hasPid) {
+    if (!killBgPid(pid)) return `Error: kill pid: "${String(pid)}" is not a valid process id`
+    return `killed process tree ${Number(pid)} (taskkill /T /F on win32; POSIX group kill)`
+  }
+  const res = killBgTask(ctx?.agent, id)
+  if (res.status === "error") return `Error: ${res.error}`
+  return `killed background bash#${res.id} — its process tree was terminated; no digest will arrive${res.logPath ? ` — log so far: ${res.logPath}` : ""}`
+}
+
 function listWindows() {
   // tasklist /FO CSV /NH → lines: "name.exe","1234","Console","1","12,345 K"
   const out = execFileSync("tasklist", ["/FO", "CSV", "/NH"], { encoding: "utf8", timeout: 10000 })
@@ -112,7 +142,7 @@ export const getCurrentTimeTool = {
 
 // ─── wait_for ───────────────────────────────────────────────────
 
-/** wait_for bounds (TOOLS.md §16): a BUILT-IN ceiling replaces the unbounded
+/** wait_for bounds: a BUILT-IN ceiling replaces the unbounded
  *  sleep-then-wait — timeout_ms defaults to 30s (config.json agent.waitForTimeoutMs
  *  overrides), capped at WAIT_FOR_MAX_TIMEOUT_MS (600s — the execute-tool timeout
  *  convention, Math.min(t, 600_000)); interval_ms defaults to 1s with a 100ms
@@ -122,7 +152,7 @@ export const WAIT_FOR_MAX_TIMEOUT_MS = 600_000
 export const WAIT_FOR_DEFAULT_INTERVAL_MS = 1_000
 export const WAIT_FOR_MIN_INTERVAL_MS = 100
 
-// Condition-source seam (§16 评审 #4): production uses the real evaluator
+// Condition-source seam (评审 #4): production uses the real evaluator
 // (evaluateWaitForCondition); tests inject a deterministic fake source via
 // setWaitForConditionSource (default null — production path unchanged).
 let injectedConditionSource = null
@@ -139,10 +169,11 @@ export function parseWaitForCondition(condition) {
   if (c === "advisor settled") return { kind: "advisor", arg: null }
   if (c === "consult done") return { kind: "consult", arg: null }
   if ((m = c.match(/^subagent id:\s*(\d+) done$/))) return { kind: "subagent", arg: String(Number(m[1])) }
+  if ((m = c.match(/^bash id:\s*(\d+) done$/))) return { kind: "bash", arg: String(Number(m[1])) }
   if ((m = c.match(/^file exists:\s*(.+)$/))) return { kind: "file", arg: m[1].trim() }
   if ((m = c.match(/^port open:\s*(\d+)$/))) return { kind: "port", arg: Number(m[1]) }
   throw new Error(
-    `wait_for: unsupported condition "${c}" — supported: "advisor settled", "subagent id:N done", "consult done", "file exists:path", "port open:N"`,
+    `wait_for: unsupported condition "${c}" — supported: "advisor settled", "subagent id:N done", "consult done", "bash id:N done", "file exists:path", "port open:N"`,
   )
 }
 
@@ -170,7 +201,7 @@ function asyncEntryDone(agent, id) {
   return entry.done === true || entry.status === "done"
 }
 
-/** 评审池双载体（第 10 批 §18.3 #2）：agent ∪ history——未初始化的载体不进集合。 */
+/** 评审池双载体（第 10 批 AGENT-LOOP-ASYNC-POOL.md §6.11 #2）：agent ∪ history——未初始化的载体不进集合。 */
 function advisorPools(agent) {
   return [agent?._asyncAdvisors, agent?.history?._asyncAdvisors].filter((m) => m instanceof Map)
 }
@@ -183,8 +214,8 @@ function hasRunningIn(pool, pred) {
   return false
 }
 
-/** "advisor settled" 真判据（第 10 批 §18.3 #2 修正）：**评审池真实态**——双载体
- *  （agent._asyncAdvisors ∪ history._asyncAdvisors）无 running/queued 条目（与 §11.2 的
+/** "advisor settled" 真判据（第 10 批 AGENT-LOOP-ASYNC-POOL.md §6.11 #2 修正）：**评审池真实态**——双载体
+ *  （agent._asyncAdvisors ∪ history._asyncAdvisors）无 running/queued 条目（与 AGENT-LOOP-ASYNC-POOL.md §6.10 的
  *  未决评审判定 advisorReviewPending 同源语义）。修前读**子代理池**的 role==="advisor"
  *  条目——评审条目只在 _asyncAdvisors → 恒无命中 → 恒真 0ms 秒过（用户实证）。 */
 function advisorSettled(agent) {
@@ -228,12 +259,18 @@ export async function evaluateWaitForCondition(condition, ctx) {
   const agent = ctx?.agent
   switch (parsed.kind) {
     case "advisor":
-      // 第 10 批修正（§18.3 #2——修前恒真 0ms 秒过）：判据 = 评审池真实态（双载体）——
-      // 不再读子代理池的 role==="advisor" 条目（该池永无此类条目）；语义与 §11.2 未决
+      // 第 10 批修正（AGENT-LOOP-ASYNC-POOL.md §6.11 #2——修前恒真 0ms 秒过）：判据 = 评审池真实态（双载体）——
+      // 不再读子代理池的 role==="advisor" 条目（该池永无此类条目）；语义与 §6.10 未决
       // 评审判定同源（advisorReviewPending）。
       return advisorSettled(agent)
     case "subagent":
       return asyncEntryDone(agent, parsed.arg)
+    case "bash": {
+      // #9：后台 bash 任务判据（池内 done ∥ 出池即 done——`bash-async.mjs` 单点）。
+      // 动态 import（W8 契约②：agent-tools 链静态达 node:sqlite——端壳静态闭包零命中）。
+      const { bgTaskDone } = await import("../agent-tools/bash-async.mjs")
+      return bgTaskDone(agent, parsed.arg)
+    }
     case "consult":
       return consultAllDone(agent)
     case "file":
@@ -256,7 +293,7 @@ export const waitForTool = {
   parameters: {
     type: "object",
     properties: {
-      condition: { type: "string", description: 'Condition expression — "advisor settled", "subagent id:N done", "consult done", "file exists:path", "port open:N"' },
+      condition: { type: "string", description: 'Condition expression — "advisor settled", "subagent id:N done", "consult done", "bash id:N done", "file exists:path", "port open:N"' },
       interval_ms: { type: "integer", description: "Poll interval in ms (default 1000, floor 100)" },
       timeout_ms: { type: "integer", description: "Overall timeout in ms (default 30000, cap 600000; config.json agent.waitForTimeoutMs overrides the default)" },
     },

package/tools/patch.mjs

@@ -7,7 +7,7 @@ import {
   majorityEol
 } from "./shared.mjs";
 import { writeThroughPath, TMP_SUFFIX, markDirty } from "./write-path.mjs";
-import { execFileSync } from "node:child_process";
+import { spawnGit } from "./git-run.mjs";
 import { mkdir, readFile, lstat, unlink } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { relative, dirname } from "node:path";
@@ -275,7 +275,9 @@ export const deleteTool = {
     const rel = relative(ctx.cwd, abs).replace(/\\/g, "/")
     let tracked = false
     try {
-      execFileSync("git", ["ls-files", "--error-unmatch", "--", rel], { cwd: ctx.cwd, stdio: "ignore" })
+      // #208①（2026-09-25）：表外同步 spawn 收口——探针转 `spawnGit` 单点（GIT_ENV 加固 + 超时 + 树杀）；
+      // 失败语义零变（未跟踪 / 非仓 ⇒ tracked 保持 false）。
+      await spawnGit(ctx.cwd, ["ls-files", "--error-unmatch", "--", rel])
       tracked = true
     } catch {
       // untracked / non-git repo

package/tools/repomap.mjs

@@ -6,7 +6,8 @@
 import { existsSync } from "node:fs"
 import { readFile, stat } from "node:fs/promises"
 import { join } from "node:path"
-import { normalizeEOL } from "./shared.mjs"
+import { DESC, normalizeEOL } from "./shared.mjs" // #15 描述外置：文本单点 = tool-docs/repo_outline.md（DESC 单解析面）
+import { INDEX_ORIGIN_ROW_WARN } from "../memory/schema.mjs" // §6.14 B4 文件数上界（WARN 值复用）
 
 /** Extract JS/TS file import paths (normalize by stripping .ts/.js/.mjs suffixes) */
 function parseImports(lines, ext) {
@@ -111,13 +112,22 @@ function normalizeExt(p) {
   return p.replace(/\.(m?js|jsx|tsx?)$/i, "")
 }
 
+/** B4 越界提示行（跳过大纲构建；指路 = 声明 ∕ 剪枝）——两入口（buildSummary ∕ buildOutline）同文；
+ *  `origin` 给出时才缀「for this origin」（repo_outline 工具缝不传 origin——跨 origin 行不假称本 origin）。 */
+function outlineOverLimit(origin = null) {
+  return `(code index too large for an outline: > ${INDEX_ORIGIN_ROW_WARN} files${origin ? " for this origin" : ""} — declare index.excludePaths in PROJECT-MANIFEST.json, or prune: thincoder memory sweep --origin <o> --path <sub>)`
+}
+
 /**
  * Internal: scan all files, build forward dependency graph + reverse reference graph.
  * Returns { deps, importers, fileCount } shared by buildOutline / buildSummary.
  */
-async function _buildDepGraph(db, cwd) {
-  const allFiles = db.prepare(`SELECT DISTINCT path FROM code_chunks ORDER BY path`).all().map((r) => r.path)
+async function _buildDepGraph(db, cwd, { origin = null } = {}) {
+  // §6.14 B4：origin 限定 + 文件数上界（文件行 `LIMIT = WARN+1` 形——越界不构建大纲，返回信号）
+  const limit = INDEX_ORIGIN_ROW_WARN + 1
+  const allFiles = db.prepare(`SELECT DISTINCT path FROM code_chunks ${origin ? "WHERE origin = ? " : ""}ORDER BY path LIMIT ${limit}`).all(...(origin ? [origin] : [])).map((r) => r.path)
   if (allFiles.length === 0) return null
+  if (allFiles.length >= limit) return { overLimit: true, fileCount: allFiles.length }
 
   const deps = new Map()      // path → { imports: Set, exports: Set, size: number, dir: string }
   const importers = new Map() // importee → Set<importer>
@@ -182,8 +192,9 @@ async function _buildDepGraph(db, cwd) {
  *  3. Entry points (files with no importers — startup/top-level entry points)
  * Output is naturally bounded (~1000-2000 chars), no more OUTLINE_INJECT_MAX hard truncation.
  */
-export async function buildSummary(db, cwd) {
-  const graph = await _buildDepGraph(db, cwd)
+export async function buildSummary(db, cwd, { origin = null } = {}) {
+  const graph = await _buildDepGraph(db, cwd, { origin })
+  if (graph?.overLimit) return outlineOverLimit(origin)
   if (!graph) return "(no indexed source files; run codeSync or /reindex first)"
   const { deps, importers, fileCount } = graph
 
@@ -257,8 +268,9 @@ export async function buildSummary(db, cwd) {
 }
 
 /** Get known file list from code_chunks (reuse index), parse by path to generate outline text */
-export async function buildOutline(db, cwd, focusPath) {
-  const graph = await _buildDepGraph(db, cwd)
+export async function buildOutline(db, cwd, focusPath, { origin = null } = {}) {
+  const graph = await _buildDepGraph(db, cwd, { origin })
+  if (graph?.overLimit) return outlineOverLimit(origin)
   if (!graph) return "(no indexed source files; run codeSync or /reindex first)"
   const { deps, importers } = graph
 
@@ -296,8 +308,7 @@ export async function buildOutline(db, cwd, focusPath) {
 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. Find code by keyword or snippet with code_search.",
+    description: DESC("repo_outline"), // #15 外置：文本单点 = tool-docs/repo_outline.md（工具名逐字对核）
     parameters: {
       type: "object",
       properties: {

package/tools/search.mjs

@@ -32,7 +32,7 @@ export const globTool = {
   readonly: true,
   async execute(args, ctx) {
     const base = resolveInCwd(ctx, args.path ?? ".")
-    // §17 调用侧拆分（评审 #5 职责分层）：空格分隔 include !exclude 多模式在这里拆；
+    // TOOLS.md §6.7 调用侧拆分（评审 #5 职责分层）：空格分隔 include !exclude 多模式在这里拆；
     // globToRegex 只收单个模式（数组由 compileGlobMatchers 收）。
     let match
     try {
@@ -115,7 +115,7 @@ export const grepTool = {
     } catch {
       return `grep error: path not found: ${base}`
     }
-    // §17 调用侧拆分：glob 参数支持空格分隔 include !exclude 多模式（include/exclude 求交）。
+    // TOOLS.md §6.7 调用侧拆分：glob 参数支持空格分隔 include !exclude 多模式（include/exclude 求交）。
     let fileTest = null
     if (args.glob) {
       try {

package/tools/shared.mjs

@@ -3,7 +3,7 @@
  * Imported by tools/file.mjs / system.mjs / web.mjs / git.mjs
  */
 
-import { spawn, execFileSync, execFile } from "node:child_process"
+import { execFile } from "node:child_process"
 import { readFileSync, existsSync, realpathSync, readdirSync, statSync, openSync, readSync, closeSync } from "node:fs"
 import { dirname, join, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
@@ -217,12 +217,14 @@ export function makeDecoder() {
   }
 }
 
-/** Single-file git diff. Silently returns empty on failure. Large diffs that exceed maxBuffer are truncated rather than swallowed. */
-export function gitDiffOne(cwd, abs) {
+/** Single-file git diff. Silently returns empty on failure. Large diffs that exceed maxBuffer are truncated rather than swallowed.
+ *  #208①（2026-09-25）：体转 async 薄壳委托 `spawnGit` 单点（GIT_ENV 加固 + 两档超时 + 树杀 + 非阻塞）；
+ *  形保真 = trim / 200 行截断 / 10MB 溢出取部分输出 / 失败静默回 `""`（调用面 5 处 `await` 化）。 */
+export async function gitDiffOne(cwd, abs) {
   try {
-    const diff = execFileSync("git", ["--no-pager", "diff", "--no-color", "--", abs], {
-      cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 10 * 1024 * 1024,
-    }).trim()
+    const diff = (await spawnGit(cwd, ["--no-pager", "diff", "--no-color", "--", abs], {
+      maxBuffer: 10 * 1024 * 1024,
+    })).trim()
     if (!diff) return ""
     const lines = diff.split("\n")
     if (lines.length <= 200) return diff
@@ -373,7 +375,7 @@ export function detectDanger(command) {
 }
 
 
-/** Glob dialect (TOOLS.md §17) lives in glob-dialect.mjs — single authority for
+/** Glob dialect (TOOLS.md §6.7) lives in glob-dialect.mjs — single authority for
  *  brace expansion / exclusion / explicit syntax errors (extracted 2026-09-06 —
  *  advisor #5: shared.mjs exceeded 500 lines). Re-exported so existing importers
  *  (system.mjs tools, ls filter, tests) keep their import paths unchanged. */

package/tools/web.mjs

@@ -1,10 +1,11 @@
 import { DESC, truncate, stripTags, htmlToText, isPrivateHost } from "./shared.mjs";
 import { URL } from "node:url";
 import { proxyFetch } from "../proxy.mjs";
+import { resolveEnvRefs } from "../env-ref.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 显式传不自动应用）
+// 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) ──
@@ -46,7 +47,9 @@ const ENGINE_NAMES = ENGINES.map(e => e.name)
  *  { engine, results } or null to fall back to Bing HTML scraping.
  *  proxyUri: explicit per-call proxy (args.proxy) — never the config.json one. */
 async function fetchTavily(query, limit, ctx, proxyUri) {
-  const apiKey = ctx?.agent?.config?.websearch?.apiKey
+  // #57（provider-config-family 批）：值位 `${env:VAR}` 消费侧解析（CONFIG.md §6.3）——未设 ∕ 空串 ∕
+  // 畸形 ⇒ 抛错（不静默字面透传）；未配置 key 仍走 Bing 回落。
+  const apiKey = resolveEnvRefs(ctx?.agent?.config?.websearch?.apiKey)
   if (!apiKey) return null
   const ctrl = new AbortController()
   const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT)

package/tools/write-path.mjs

@@ -6,7 +6,7 @@
  * 写入又与用户随后的保存互相竞写（split-brain 数据丢失）。核内原先写盘直调
  * `node:fs/promises`、散在 5 个档的 8 个写点上 ⇒ **没有可注入的一跳** ⇒ 端侧接核后会
  * 丢掉编辑器径。本模块就是那一跳：核内**工具面的 8 个编辑写点**全改调 `writeThroughPath`
- * （模型面直写 `agent-tools/batch-segment.mjs` = 设计登记的 S2 前置门——不在本缝覆盖面；
+ * （模型面直写 `agent-tools/batch.mjs` = 设计登记的 S2 前置门——不在本缝覆盖面；
  * 口径与 `CORE-UNIFICATION.md` §2.13.5 落地收正同源）。
  *
  * 默认径 = CLI 语义（**零行为变**）：`writeFile` + 记账。端侧

package/traces/trace-store.mjs

@@ -1,5 +1,5 @@
 /**
- * trace-store.mjs — §18.6 完整轨迹存档（AGENT-LOOP.md §18.6 D-TR1..TR8 权威规格）。
+ * trace-store.mjs — 完整轨迹存档（TRACES.md §6 机制 + §7 决策表 D-TR1–4 / D-TR6 / D-TR10–13 权威规格）。
  *
  * 完整请求-响应轨迹落盘：每次 chat() 调用一个 JSONL 文件到
  * ~/.thincoder/traces/YYYY-MM-DD/<sessionKey>-<seq>.jsonl。采集点唯一 = core.mjs
@@ -11,9 +11,8 @@
  *   写盘异步（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 同惯例）。
+ *   轨迹目录（既有测试跑真实 agent 管线会产生数百次 chat 调用）；显式测试缝
+ *   （`_setTracesRootForTest`）强制写入该目录（与 log.mjs 同惯例——CONFIG.md §6.2）。
  * - 脱敏（D-TR2）：复用 log.mjs 字段名黑名单（apikey/designtoken/password/secret/
  *   token/authorization/proxyuri/proxy）+ SECRET_FORM 形态扫描（redactSecret）——对
  *   messages/content/reasoning/toolCalls/error 全字段应用；不发明新遮蔽模式。
@@ -24,7 +23,7 @@
  *   与写盘同在 fire-and-forget 异步体内）。2026-09-21（TRACES.md §6.4）：判据改**目录级三段梯**
  *   + 每写 prune **节流**；清理实现外提 `trace-cleanup.mjs`（本档包装保既有 import 面）。
  * - seq = 当日目录内最大已有 seq + 1（D-TR3——跨会话/进程重启不覆写既有旧轨迹——
- *   18.6.1 评审 #3）；**进程内 seqCache（§23.3.2——消除逐调用同步扫目录）**：首次
+ *   18.6.1 评审 #3）；**进程内 seqCache（TRACES.md §6.2——消除逐调用同步扫目录）**：首次
  *   readdirSync 后进程内递增预留，目录被清理（retention）后取下界重扫一次（防御）。
  *   多进程语义（修正轮 #10——登记）：同 cwd 多实例各自进程内缓存——seq 可撞、同
  *   sessionKey 记录并入同名文件（append 不覆写）；**可容忍**（本机 traces = 诊断面、
@@ -44,16 +43,20 @@ import { configDir, loadConfig } 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/ 同域）。 */
+/** Test seam: override the traces root (process-internal seam — CONFIG.md §6.2 ③ 通道). */
+let _tracesRoot = null
+export function _setTracesRootForTest(p) { _tracesRoot = p }
+export function _resetTracesRootForTest() { _tracesRoot = null }
+
+/** 轨迹根目录：显式测试缝 > ~/.thincoder/traces（configDir——D-TR3——与 sessions/ 同域）。 */
 export function tracesRoot() {
-  return process.env.THINCODER_TRACES_DIR ?? join(configDir, "traces")
+  return _tracesRoot ?? join(configDir, "traces")
 }
 
 /** 写门（测试隔离）：test runner 进程（NODE_TEST_CONTEXT）默认跳过——除显式
- *  THINCODER_TRACES_DIR override（traces.test.mjs 隔离临时目录）。 */
+ *  测试缝 override（轨迹测试隔离临时目录）。 */
 function writeEnabled() {
-  if (process.env.NODE_TEST_CONTEXT && !process.env.THINCODER_TRACES_DIR) return false
+  if (process.env.NODE_TEST_CONTEXT && _tracesRoot === null) return false
   return true
 }
 
@@ -93,7 +96,7 @@ export function tracesDirFor(dateStr) {
 // 完整落盘：不截断、不丢行（无单消息/单记录额度，无在途丢弃）；清理 = 每写一次 prune
 // （写盘成功后顺带清理——与写盘同在 fire-and-forget 异步体内，永不阻塞 chat）。
 
-// 进程内 seq 缓存（§23.3.2：dir → 已预留 max；首次读盘后递增预留，目录被清理后取下界重扫一次）。
+// 进程内 seq 缓存（TRACES.md §6.2：dir → 已预留 max；首次读盘后递增预留，目录被清理后取下界重扫一次）。
 const _seqCache = new Map()
 // 每写 prune 节流（D-TR12 · §6.4）：窗 = 10 分钟 + 在飞合并（同窗 3 连写 ⇒ 扫描 ≤1 次）。
 export const PRUNE_THROTTLE_MS = 10 * 60_000
@@ -132,7 +135,7 @@ function scanMaxSeq(dir) {
 
 /** seq = max(当日目录最大已有 seq, 进程内已预留) + 1（D-TR3——跨会话/进程重启
  *  不覆写——T-TR8/T-TR10；同步预留 = 异步写盘启动前的原子号位分配）。
- *  §23.3.2：seqCache 进程内递增——不逐调用 readdirSync（目录被清理/缺失 → 重扫一次）。 */
+ *   TRACES.md §6.2：seqCache 进程内递增——不逐调用 readdirSync（目录被清理/缺失 → 重扫一次）。 */
 export function nextTraceSeq(dateStr) {
   const dir = tracesDirFor(dateStr)
   let max = _seqCache.get(dir)
@@ -152,7 +155,7 @@ export function tracesEnabled(logCtx) {
   return logCtx?.traces !== false
 }
 
-// ─── 单遍序列化（§23.3.2 D-TR1——脱敏内联、零复制图、字段名/次序同构）────────
+// ─── 单遍序列化（TRACES.md §6.2 D-TR1——脱敏内联、零复制图、字段名/次序同构）────────
 
 const OMIT = Symbol("omit") // JSON.stringify 语义：对象属性省略（数组元素 → null）
 
@@ -292,7 +295,7 @@ export function recordChatTrace(provider, opts = {}, result = null, error = null
 }
 
 /** D-TR10 清理面（D-TR11 目录级三段梯）——实现外提 `traces/trace-cleanup.mjs`；此处包装保
- *  既有 import 面与缺省 `dir`（`tracesRoot()` 单源——测试经 `THINCODER_TRACES_DIR` 隔离）。
+ *  既有 import 面与缺省 `dir`（`tracesRoot()` 单源——测试经 `_setTracesRootForTest` 隔离）。
  *  调用点 = 每写 prune（经 `maybePruneTraces`）+ 启动清理（壳侧）；返回删除文件数。 */
 export function cleanupTraces({ dir = tracesRoot(), retentionHours = 24 } = {}) {
   return cleanupTracesImpl({ dir, retentionHours })

package/vision-reader.mjs

@@ -0,0 +1,76 @@
+/**
+ * vision-reader.mjs — 非多模态降级读图跑者（上提核件 —— parity-b4 W0 · 2026-09-29）。
+ *
+ * 上提源 = VSC `thincoder-vscode/src/extension/vision-channel.mjs:14`（`findVisionChannel` 逐字）
+ * + `image-handler.mjs:70-95`（`runVisionReader` 逐字）；VSC 自持跑者 ∕ 渠道副本已随迁移轮（parity-b4）删。
+ * 消费面 = VSC `image-handler.mjs`（已改指本档）· 桌面 `src/main/attachments.mjs`
+ * （降级适配器缺省 = 本档 —— `visionReader` 缝的核默认实现）。
+ *
+ * `findVisionChannel`（纯函数）：渠道表 ⇒ 视觉读图渠道 —— 「优先同名（当前主）渠道的视觉默认模型，
+ * else 全渠道首个视觉默认模型者」；判据 = `specForModel(p.model).multimodal`
+ * （与 `read_image` 注册门 ∕ `isNonVisionModel` 同源）。
+ *
+ * `runVisionReader`：一次性 depth-1 只读 explore 子代理读图返回文本描述。
+ *  渠道 = 视觉渠道（`resolveProviders()` 现读）；provider = 核 `resolveChildProvider`（`<渠道>:<模型>`）；
+ *  工具 = 按**该渠道模型**装配的只读族（`read_image` 随 multimodal 注册 —— 主模型非视觉时其工具表
+ *  本无该件，故按子代理模型重装，不沿用主代理工具表）；`config ∕ memory` = 主代理同源。
+ *  失败径全 `null`（原样兜底，不静默丢）：无渠道 ∕ 渠道未知 ∕ 渠道无 key（spawn 期失败回落）∕
+ *  spawn 失败 ∕ 超时 ∕ 空返；外部 `signal` 已停 ⇒ 快速失败，否则桥接内部控制器。
+ *
+ *  W8 契约②（2026-09-29 断链）：`agent.mjs` ∕ `agent-tools/subagent-async.mjs` 静态链达 `node:sqlite`
+ *  （`agent.mjs` → `agent/setup.mjs` → `memory.mjs` → `memory/schema.mjs`）⇒ 两端一律**函数体内动态 import**
+ *  （约定源 = `ledger.mjs:16`；实例 = `tools/index.mjs:63`）；本档静态边只留闭包净件（`config-io.mjs` ∕
+ *  `model-specs.mjs` ∕ `tools/index.mjs`）。
+ */
+import { resolveProviders } from "./config-io.mjs"
+import { specForModel } from "./model-specs.mjs"
+import { assembleBuiltinTools } from "./tools/index.mjs"
+
+/** 读图墙钟上限（VSC `image-handler.mjs:70` 同值——一次性子代理的成功径上限）。 */
+export const VISION_READ_TIMEOUT_MS = 60_000
+
+/** 找可跑视觉读图的渠道：`{ provider, model }` ∥ `null`——优先同名（当前主）渠道的视觉默认模型，
+ *  else 全渠道首个视觉默认模型者（"优先同名渠道视觉模型 → 首视觉渠道"）。 */
+export function findVisionChannel(providers, currentName = "") {
+  const first = []
+  for (const p of providers ?? []) {
+    const model = typeof p?.model === "string" && p.model && specForModel(p.model).multimodal ? p.model : ""
+    if (!model) continue
+    if (p.name === currentName) return { provider: p.name, model }
+    first.push({ provider: p.name, model })
+  }
+  return first[0] ?? null
+}
+
+/** 降级读图跑者（缝契约 = `visionReader({ paths, signal }) ⇒ { ok: true, description }` ∥ `null`
+ *  ——见 `attachments.mjs` `downgradeNonVisionImages`）。 */
+export async function runVisionReader({ paths, providerName, cwd, parentAgent, signal }) {
+  // 取消缝（VSC A12 同款）：已停 ⇒ 快速失败（不复用 60s 超时路径）；否则桥接内部 controller。
+  if (signal?.aborted) return null
+  let providers = []
+  try { providers = resolveProviders().providers } catch { return null }
+  const vc = findVisionChannel(providers, providerName)
+  if (!vc) return null
+  let provider = null
+  try {
+    const { resolveChildProvider } = await import("./agent-tools/subagent-async.mjs") // 动态 import（该链静态达 node:sqlite——W8 契约②）
+    provider = resolveChildProvider(parentAgent, `${vc.provider}:${vc.model}`)
+  } catch { return null }
+  const ac = new AbortController()
+  const timer = setTimeout(() => ac.abort(), VISION_READ_TIMEOUT_MS)
+  const onAbort = () => ac.abort()
+  if (signal) signal.addEventListener("abort", onAbort, { once: true })
+  try {
+    const { createAgent, runAgent, readonlyToolNames, excludeSubagentTools } = await import("./agent.mjs") // 动态 import（agent 链静态达 node:sqlite——W8 契约②）
+    const builtins = await assembleBuiltinTools({ memory: parentAgent?.memory, cwd, model: vc.model })
+    const allowed = readonlyToolNames(builtins)
+    const tools = excludeSubagentTools(builtins.filter((t) => allowed.has(t.name)))
+    const child = createAgent({ provider, tools, config: parentAgent?.config, cwd, memory: parentAgent?.memory, role: "explore" })
+    const task = paths.map((f) => `用 read_image 读 ${f} 返回图像内容描述`).join("\n")
+    const desc = await runAgent(child, task, {}, { depth: 1, maxTurns: 10, signal: ac.signal })
+    return typeof desc === "string" && desc.trim() ? { ok: true, description: desc.trim() } : null
+  } catch { return null } finally {
+    clearTimeout(timer)
+    if (signal) signal.removeEventListener("abort", onAbort)
+  }
+}

package/agent-tools/batch-segment.mjs

@@ -1,18 +0,0 @@
-/**
- * agent-tools/batch-segment.mjs — **过渡 shim**（batch 工具单名化收口，BATCH-RECORD §4.14）：
- * 本档仅 re-export `batch.mjs` 主档导出面（旧 import 面 = VSC `setup-tooltable.mjs` 经此 import
- * `configureBatchSegment` / 旧测试消费——导出全超集，行为零变）。权威实现 = batch.mjs
- * （batchTool 四 action + append 迁移面 + 过渡别名 batchSegmentTool）；撤除判据 = §4.14
- * （消费面清零后删本档——先例债：删档需同步 tooltable 装配 import，随批登记）。
- */
-export {
-  MAX_TEXT_CHARS,
-  SEGMENT_BY_ROLE,
-  batchDocBases,
-  batchDocForReview,
-  batchSegmentTool,
-  batchTool,
-  configureBatchSegment,
-  resetBatchSegment,
-  resolveBatchDocPath,
-} from "./batch.mjs"