@thincoder/core 0.9.1 → 0.9.3

package/tools/git-run.mjs

@@ -0,0 +1,141 @@
+/**
+ * tools/git-run.mjs — git spawn 单点（TOOLS.md §6.14 · 批 GIT-NONINTERACTIVE · 台账 #207）。
+ *
+ * 为什么单点：git 的四交互族（编辑器 / 凭据 / GUI / pager）在**无 TTY** 下永久等待——
+ * `rebase --continue` 起编辑器即冻死整个会话（已发布 `0.12.64` 实报）。加固只许一处
+ * （逐调用点补 = 必漏）：三个形适配器（`shared.mjs` `runGit` · `git.mjs` `runGitRaw` ·
+ * `git-ext.mjs` `runGitStrict`）体转**异步薄壳**委托本档，签名与返回形零变。
+ *
+ * 三件套：① `GIT_ENV` 加固集（**env 形**——实测 `GIT_EDITOR` env 优先于 `core.editor`，
+ * `-c` 形单独不足）② 两档超时（本地 120s / 网络 300s · 全量适用）③ 超时动作序
+ * （SIGTERM → 1.5s 树杀 → 1.5s kick——孙进程持管道时 `close` 永不触发）。
+ */
+import { spawn } from "node:child_process"
+import { killProcessTree } from "./process-tree.mjs"
+
+/** 加固集（逐字 = §6.14「加固集」）：继承面在前，加固键一律置后覆盖——继承面不得反超。
+ *  编辑器族 4 键 · pager 族 2 键 · 凭据族 2 键（本批新增，bash 面亦无）· 终端族 1 键。 */
+export const GIT_ENV = {
+  ...process.env,               // 继承面（PATH / HOME / 用户 proxy 等）
+  GIT_EDITOR: "true",           // 编辑器族：提交信息编辑器（解析链最高优先键）
+  GIT_SEQUENCE_EDITOR: "true",  // 编辑器族：rebase todo 列表编辑器
+  EDITOR: "true",               // 编辑器族：兜底链 VISUAL / EDITOR
+  VISUAL: "true",
+  GIT_PAGER: "cat",             // pager 族（bash 工具先例同值）
+  PAGER: "cat",
+  GIT_TERMINAL_PROMPT: "0",     // 凭据族：禁终端提示
+  GIT_ASKPASS: "",              // 凭据族：空串 ⇒ 不调 askpass 程序（同时封 core.askpass 升级路）
+  TERM: "dumb",                 // 终端族（bash 工具先例同值）
+}
+
+export const GIT_TIMEOUT_MS = 120_000
+export const GIT_NET_TIMEOUT_MS = 300_000
+/** 网路面五动作（300s 档——合法耗时可远超本地；依据 = 需求档 §4.7 TTY-DRIVE N3 候选参照值）。 */
+const GIT_NET_ACTIONS = new Set(["push", "fetch", "pull", "clone", "ls-remote"])
+
+/** 测试态缝（模块级 · 缺省 null = 生产零行为变——先例 `manifest.mjs:40-41` · `session-gc.mjs:136`）。
+ *  用例 `finally` 复位；不经用户参数面（边界：不新增参数 / 用户选项）。 */
+let gitTimeoutOverride = null
+export function _setGitTimeoutForTest(ms) { gitTimeoutOverride = ms }
+export function _resetGitTimeoutForTest() { gitTimeoutOverride = null }
+
+/** 子命令取形：跳 `-c <k=v>` 对（适配器把 config 前置在 args 头）——首个其余 arg 即子命令。 */
+function gitSubcommand(args) {
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "-c") { i++; continue }
+    return args[i]
+  }
+  return ""
+}
+
+/** 超时文案单源（逐字 = §6.14「超时错误文案」）：两帧嵌同一条——`runGit` / `runGitRaw` 抛错经
+ *  `gitFailureMessage`；`runGitStrict` 的 `err` = 本条（调用方另加 `git <action> failed: ` 前缀）。 */
+export function gitTimeoutNote(ms) {
+  return `timed out after ${ms / 1000}s (killed) — no interactive input is possible here (editor / credential / network); `
+    + "process killed, tree best-effort — retry or use the bash tool; an interrupted write keeps git state (`git status`) "
+    + "— git abort / continue, or checkpoint action=checkpoint checkpointAction=list"
+}
+
+/** git spawn 单点。返回 Promise<string>（stdout 原文——trim / `\r` 归一 / 溢出分支等形由适配器保留）。
+ *  失败 / 超时 / 溢出 ⇒ reject；错误形 = `execFileSync` 同构（`.stdout` / `.stderr` / `.status` / `.message` /
+ *  `.code`），超时另带 `.timedOut = true` / `.timeoutMs`（可辨性不靠 stderr 文本猜）。
+ *  缺省：timeout 按面取常量（网络五动作 300s / 其余 120s）· maxBuffer = Node `execFileSync` 缺省 1MB
+ *  （`runGit` / `runGitRaw` 显式传 10MB——形保真清单 ②）。 */
+export function spawnGit(cwd, args, { timeout, maxBuffer } = {}) {
+  const timeoutMs = timeout ?? gitTimeoutOverride ?? (GIT_NET_ACTIONS.has(gitSubcommand(args)) ? GIT_NET_TIMEOUT_MS : GIT_TIMEOUT_MS)
+  const cap = maxBuffer ?? 1024 * 1024
+  return new Promise((resolve, reject) => {
+    const child = spawn("git", args, {
+      cwd,
+      env: GIT_ENV,
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+      detached: process.platform !== "win32", // POSIX：组首 ⇒ 树杀（-pid 组杀）可达孙进程（execute / bash 先例）
+    })
+    let stdout = "", stderr = "", mode = null, settled = false
+    let outBytes = 0, errBytes = 0   // maxBuffer 口径 = **byte**（`execFileSync` 同源）
+    let timer = null, killTimer = null, kickTimer = null
+    const finish = (fn) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer); clearTimeout(killTimer); clearTimeout(kickTimer)
+      fn()
+    }
+    const timeoutErr = () => Object.assign(new Error(gitTimeoutNote(timeoutMs)), {
+      code: "ETIMEDOUT", timedOut: true, timeoutMs, stdout, stderr, status: null,
+    })
+    const overflowErr = () => Object.assign(new Error(`git output exceeded maxBuffer (${cap} bytes)`), {
+      code: "ERR_CHILD_PROCESS_STDIO_MAXBUFFER", stdout, stderr, status: null,
+    })
+    const exitErr = (code, signal) => Object.assign(new Error(`Command failed: git ${args.join(" ")}${stderr ? `\n${stderr}` : ""}`), {
+      cmd: `git ${args.join(" ")}`, status: code, signal, killed: Boolean(signal), stdout, stderr,
+    })
+    const settleWith = (code, signal) => {
+      // 超时收尾：树杀必达（`close` 早退 ⇒ 1.5s 定时器已被 finish 清掉——**不持管道**的孙进程
+      // 会因此漏杀；树杀在头进程死后于 POSIX 仍可达全组）
+      if (mode === "timeout") { treeKill(); return reject(timeoutErr()) }
+      if (mode === "overflow") return reject(overflowErr())
+      if (code === 0 && !signal) return resolve(stdout)
+      return reject(exitErr(code, signal))
+    }
+    const treeKill = () => { try { killProcessTree(child) } catch { /* 尽力而为 */ } }
+    // 超时动作序（§6.14）：① 直接子 → ② 逾 1.5s 树杀（`killProcessTree`，尽力而为）→ ③ 逾 1.5s 未 `close`
+    // 亦 settle（kick——孙进程持管道时 `close` 永不触发，`bash.mjs:200-217` 同款）。上界 = timeout + 3s。
+    // 平台分岔（§6.14 平台注的后果）：win32 上 SIGTERM 实为硬终止且**不连带子进程**——父一死，
+    // `taskkill /PID <父> /T` 就够不到孙进程（实测：helper 孤儿存活、管道不放 ⇒ 只能等 kick）⇒
+    // win32 直接走树杀（须在树仍可寻址时执行）；POSIX 保留宽限序（组杀在头进程死后仍可达全组）。
+    const armKill = () => {
+      if (process.platform === "win32") treeKill()
+      else { try { child.kill("SIGTERM") } catch { /* 已退 */ } }
+      killTimer = setTimeout(treeKill, 1500)
+      kickTimer = setTimeout(() => finish(() => settleWith(null, "SIGTERM")), 3000)
+    }
+    timer = setTimeout(() => { if (!mode) { mode = "timeout"; armKill() } }, timeoutMs)
+    // 解码 = **流级 UTF-8**（`StringDecoder` 正确拼接跨 chunk 的多字节序列——逐 chunk `toString()`
+    // 会把半截序列解成 U+FFFD；批前三档经 `execFileSync({encoding:"utf8"})` 整体解码）
+    child.stdout.setEncoding("utf8")
+    child.stderr.setEncoding("utf8")
+    child.stdout.on("data", (d) => {
+      if (mode === "overflow") return
+      stdout += d
+      outBytes += Buffer.byteLength(d)
+      // 截断按**字符**（判据只认 code + 部分输出——多字节前缀可略超 cap 字节，语义不损）
+      if (outBytes > cap) { mode = "overflow"; stdout = stdout.slice(0, cap); armKill() }
+    })
+    child.stderr.on("data", (d) => {
+      if (errBytes > cap) return   // 两管各自独立计（`spawnSync` 的 maxBuffer 同口径：per-stream）
+      stderr += d
+      errBytes += Buffer.byteLength(d)
+    })
+    child.on("error", (e) => {
+      // 杀失败等信号面错误不得遮蔽已定模式（timeout / overflow 由 kick 收尾）
+      if (mode) return
+      finish(() => reject(Object.assign(e, { stdout, stderr, status: null })))
+    })
+    child.on("exit", (code, signal) => {
+      // 直接子已退但孙进程持管道 ⇒ `close` 不到：逾 1.5s 亦按已收集输出 settle（kick）
+      if (!settled && !kickTimer) kickTimer = setTimeout(() => finish(() => settleWith(code, signal)), 1500)
+    })
+    child.on("close", (code, signal) => finish(() => settleWith(code, signal)))
+  })
+}

package/tools/git.mjs

@@ -4,7 +4,7 @@ import {
   runGit,
   gitFailureMessage
 } from "./shared.mjs";
-import { execFileSync } from "node:child_process";
+import { spawnGit } from "./git-run.mjs";
 import { resolve } from "node:path";
 import { filterLines, runGitStrict, validateRef, gitConfigArgs, snapshotBefore, executeExtAction } from "./git-ext.mjs";
 import { executeCheckpointAction } from "./git-checkpoint.mjs";
@@ -15,10 +15,11 @@ import { discoverRepos, MANIFEST_REL } from "../manifest.mjs";
  *  strips a porcelain line's leading " " (the unstaged marker) and misclassifies an
  *  unstaged-only first line as staged. status uses this so the staged/unstaged column survives.
  *  #55 fail-closed：失败不再吞成 ""（曾把非仓 / 任意失败渲染成 `(clean — no changes)`）——
- *  溢出保留部分输出；其余 ⇒ throw（消息契约 = `shared.mjs` `gitFailureMessage`）。 */
-function runGitRaw(cwd, cmdArgs, config = []) {
+ *  溢出保留部分输出；其余 ⇒ throw（消息契约 = `shared.mjs` `gitFailureMessage`）。§6.14：体改**异步薄壳**
+ *  （`spawnGit` 单点——加固 env + 两档超时 + 树杀；签名与产出形零变）。 */
+async function runGitRaw(cwd, cmdArgs, config = []) {
   try {
-    return execFileSync("git", [...config, ...cmdArgs], { cwd, encoding: "utf8", maxBuffer: 10 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }).replace(/\r/g, "").replace(/\n$/, "")
+    return (await spawnGit(cwd, [...config, ...cmdArgs], { maxBuffer: 10 * 1024 * 1024 })).replace(/\r/g, "").replace(/\n$/, "")
   } catch (e) {
     if (e.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" && e.stdout) return String(e.stdout).replace(/\r/g, "")
     throw new Error(gitFailureMessage(e, cmdArgs, cwd))
@@ -42,10 +43,14 @@ function resolveBaseDir(cwd, workdir) {
  *  二者仍可经显式 `workdir` 指落点。 */
 const NO_REPO_DISCOVERY = new Set(["init", "clone"])
 
-/** 歧义（多态）消息：候选全列（绝对路径、按名排序）+ 指引显式 `workdir`——不猜（§6.13 解析序行 5）。 */
-function ambiguousRepoMessage(candidates, cwd) {
-  return `Ambiguous git repo at ${cwd}: ${candidates.length} subdirectories carry .git and ${MANIFEST_REL} — ` +
-    `pass workdir to run git in the intended one (no silent pick):\n` + candidates.map((c) => `- ${c}`).join("\n")
+/** 歧义（多态）消息：候选全列（绝对路径、按名排序）+ 指引显式 `workdir`——不猜（§6.13 解析序行 5）；
+ *  **两档变体**（#188——按 `matched`）：带档级 ⇒ 「.git ∧ PROJECT-MANIFEST.json」；裸仓级 ⇒ 「.git」
+ *  且注明 none carries …（不书带档句——§6.13 A22）。 */
+function ambiguousRepoMessage(candidates, cwd, matched) {
+  const head = matched === "git"
+    ? `Ambiguous git repo at ${cwd}: ${candidates.length} subdirectories carry .git (none carries ${MANIFEST_REL})`
+    : `Ambiguous git repo at ${cwd}: ${candidates.length} subdirectories carry .git and ${MANIFEST_REL}`
+  return `${head} — pass workdir to run git in the intended one (no silent pick):\n` + candidates.map((c) => `- ${c}`).join("\n")
 }
 
 // ─── 审批门注入缝（#59——「只读判定 / 审批门按端注入」，形态参 §2.13.5 注入缝）────────
@@ -108,14 +113,15 @@ export const gitTool = {
     // workdir: run git in a subdirectory (monorepo / multi-repo). Shadow ctx.cwd so
     // every action + snapshotBefore + checkpoint resolves against the workdir.
     if (args.workdir) ctx = { ...ctx, cwd: resolveBaseDir(ctx.cwd, args.workdir) }
-    // 仓发现（§6.13 · #62）：缺省路径（无 workdir）⇒ 单源 = `discoverRepos`——工作区根（非仓）⇒
-    // 唯一带 manifest 子仓：重定向 `ctx.cwd` + 结果首行注记；零 ⇒ 原值落 §6.12 fail-closed（零
-    // 行为变）；多 ⇒ throw（列候选 + 指 workdir，不猜）。判据 = workdir 真值在场（与上行同源——
-    // 空串与缺省同判）；`init` / `clone` 例外不做发现。self / none 态 ctx 对象引用透传（不 clone）。
+    // 仓发现（§6.13 · #62）：缺省路径（无 workdir）⇒ 单源 = `discoverRepos`（仓梯——#188 含裸仓级）
+    // ——工作区根（非仓）⇒ 唯一带档子仓 / 零档时唯一裸仓：重定向 `ctx.cwd` + 结果首行注记；零 ⇒ 原值
+    // 落 §6.12 fail-closed（零行为变）；多 ⇒ throw（列该级候选 + 指 workdir，不猜——消息按 `matched`
+    // 两档变体）。判据 = workdir 真值在场（与上行同源——空串与缺省同判）；`init` / `clone` 例外
+    // 不做发现。self / none 态 ctx 对象引用透传（不 clone）。
     let repoNote = ""
     if (!args.workdir && !NO_REPO_DISCOVERY.has(args.action)) {
       const discovered = discoverRepos(ctx.cwd)
-      if (discovered.kind === "ambiguous") throw new Error(ambiguousRepoMessage(discovered.candidates, ctx.cwd))
+      if (discovered.kind === "ambiguous") throw new Error(ambiguousRepoMessage(discovered.candidates, ctx.cwd, discovered.matched))
       if (discovered.kind === "unique") {
         ctx = { ...ctx, cwd: discovered.root }
         repoNote = `(repo: ${discovered.root})`
@@ -145,13 +151,16 @@ const gitActionCore = {
         if (!/^[A-Za-z0-9._/~^@][A-Za-z0-9._/~^@{}-]*$/.test(ref)) throw new Error(`Invalid git ref: ${ref}`)
         const flags = args.staged ? ["--staged"] : []
         const paths = args.path ? [args.path] : []
-        const out = runGit(ctx.cwd, ["diff", ...flags, ref, "--", ...paths])
-        return truncate(filterLines(out || "(no changes)", args.filter))
+        const out = await runGit(ctx.cwd, ["diff", ...flags, ref, "--", ...paths])
+        // #71（hygiene-sweep 批）：传了 path 且输出空 ⇒ 注记（pathspec 未命中也是 exit 0——
+        // 原样「(no changes)」为假洁净；不传 path 逐字零变）
+        const empty = args.path ? `(no changes — pathspec '${args.path}' matched nothing in ${ref})` : "(no changes)"
+        return truncate(filterLines(out || empty, args.filter))
       }
       case "status": {
         // Preserve per-line leading whitespace — porcelain " M"/"M " staged/unstaged markers are
         // significant (runGit trims the whole output's leading space, corrupting an unstaged-first-line).
-        const porcelain = runGitRaw(ctx.cwd, ["status", "--porcelain"])
+        const porcelain = await runGitRaw(ctx.cwd, ["status", "--porcelain"])
         if (!porcelain) return "(clean — no changes)"
 
         const staged = []
@@ -191,19 +200,21 @@ const gitActionCore = {
           ? ["log", "-" + n, "--oneline"]
           : ["log", "-" + n, "--format=%h %ad %an %s", "--date=short"]
         if (args.path) cmdArgs.push("--", args.path)
-        const out = runGit(ctx.cwd, cmdArgs)
-        return truncate(filterLines(out || "(no commits)", args.filter))
+        const out = await runGit(ctx.cwd, cmdArgs)
+        // #71：同上（log 腿——传了 path 且输出空 ⇒ 注记；不传 path 逐字零变）
+        const empty = args.path ? `(no commits — pathspec '${args.path}' matched nothing)` : "(no commits)"
+        return truncate(filterLines(out || empty, args.filter))
       }
       case "show": {
         const ref = args.ref ?? "HEAD"
         if (!/^[A-Za-z0-9._/~^@][A-Za-z0-9._/~^@{}-]*$/.test(ref)) throw new Error(`Invalid git ref: ${ref}`)
-        const out = runGit(ctx.cwd, ["show", "--stat", ref])
+        const out = await runGit(ctx.cwd, ["show", "--stat", ref])
         return truncate(out || "(no such commit)")
       }
       case "rm": {
         if (!args.path) return "Error: rm requires path (the file/directory to untrack, relative to repo root)"
         const paths = args.path.split(/\s+/).filter(Boolean)
-        const r = runGitStrict(ctx.cwd, ["rm", "--cached", "-r", "--", ...paths])
+        const r = await runGitStrict(ctx.cwd, ["rm", "--cached", "-r", "--", ...paths])
         return r.ok ? truncate(r.out || `Untracked ${paths.join(" ")} (kept on disk)`) : truncate(`git rm failed: ${r.err || r.out}`)
       }
       case "commit": {
@@ -217,12 +228,12 @@ const gitActionCore = {
         if (args.path !== undefined && args.path !== null) {
           const trimmed = args.path.trim()
           if (!trimmed) return "Error: commit path is empty/whitespace — give at least one file path (space-separated)"
-          commit = runGitStrict(ctx.cwd, ["commit", "--only", "-m", args.message, "--", ...trimmed.split(/\s+/)])
+          commit = await runGitStrict(ctx.cwd, ["commit", "--only", "-m", args.message, "--", ...trimmed.split(/\s+/)])
         } else {
-          const add = runGitStrict(ctx.cwd, ["add", "-A"])
+          const add = await runGitStrict(ctx.cwd, ["add", "-A"])
           if (!add.ok) return truncate(`git add failed: ${add.err || add.out || "(no output)"}`)
           if (add.out) parts.push(add.out)
-          commit = runGitStrict(ctx.cwd, ["commit", "-m", args.message])
+          commit = await runGitStrict(ctx.cwd, ["commit", "-m", args.message])
         }
         if (commit.ok) {
           if (commit.out) parts.push(commit.out)
@@ -244,7 +255,7 @@ const gitActionCore = {
         if (args.remote) cmdArgs.push(validateRef(args.remote, "remote"))
         if (args.ref) for (const r of args.ref.split(/\s+/).filter(Boolean)) cmdArgs.push(validateRef(r, "ref"))
         if (args.tags) cmdArgs.push("--tags")
-        const r = runGitStrict(ctx.cwd, cmdArgs, cfgArgs)
+        const r = await runGitStrict(ctx.cwd, cmdArgs, cfgArgs)
         return r.ok ? truncate(r.out || "(push complete — no output)") : truncate(`git push failed: ${r.err || r.out || "(no output)"}`)
       }
       case "ls-remote": {
@@ -253,7 +264,7 @@ const gitActionCore = {
         const cmdArgs = ["ls-remote"]
         if (args.remote) cmdArgs.push(validateRef(args.remote, "remote"))
         if (args.ref) for (const r of args.ref.split(/\s+/).filter(Boolean)) cmdArgs.push(validateRef(r, "ref"))
-        const out = runGit(ctx.cwd, cmdArgs, cfgArgs)
+        const out = await runGit(ctx.cwd, cmdArgs, cfgArgs)
         if (!out) return "(no refs / remote unreachable)"
         return truncate(filterLines(out, args.filter))
       }
@@ -262,51 +273,51 @@ const gitActionCore = {
         // 多路径：空格分隔（ref 先例 L175——2026-09-05 发版痛点——git add 单路径被迫 N 次调用）
         const paths = args.path ? args.path.split(/\s+/).filter(Boolean) : null
         const cmdArgs = paths?.length ? ["add", "--", ...paths] : ["add", "-A"]
-        const r = runGitStrict(ctx.cwd, cmdArgs)
+        const r = await runGitStrict(ctx.cwd, cmdArgs)
         return r.ok ? truncate(r.out || `Staged ${paths?.join(" ") || "all changes"}`) : truncate(`git add failed: ${r.err || r.out}`)
       }
       case "tag": {
         const sub = args.tagAction
-        if (sub === "list") return truncate(filterLines(runGit(ctx.cwd, ["tag", "-l"]) || "(no tags)", args.filter))
+        if (sub === "list") return truncate(filterLines(await runGit(ctx.cwd, ["tag", "-l"]) || "(no tags)", args.filter))
         if (sub === "create") {
           if (!args.name) return "Error: tag create requires name"
           validateRef(args.name, "tag")
           const cmdArgs = ["tag", args.name]
           if (args.ref) cmdArgs.push(validateRef(args.ref))
-          const r = runGitStrict(ctx.cwd, cmdArgs)
+          const r = await runGitStrict(ctx.cwd, cmdArgs)
           return r.ok ? `Tag ${args.name} created` : truncate(`git tag failed: ${r.err || r.out}`)
         }
         if (sub === "delete") {
           if (!args.name) return "Error: tag delete requires name"
           validateRef(args.name, "tag")
           const snap = await snapshotBefore(ctx, `tag delete ${args.name}`)
-          const r = runGitStrict(ctx.cwd, ["tag", "-d", args.name])
+          const r = await runGitStrict(ctx.cwd, ["tag", "-d", args.name])
           return r.ok ? truncate(snap + `Tag ${args.name} deleted`) : truncate(`git tag -d failed: ${r.err || r.out}`)
         }
         return "Error: tag requires tagAction — use: list | create | delete"
       }
       case "branch": {
         const sub = args.branchAction
-        if (sub === "list") return truncate(filterLines(runGit(ctx.cwd, ["branch", "--all", "-vv"]) || "(no branches)", args.filter))
+        if (sub === "list") return truncate(filterLines(await runGit(ctx.cwd, ["branch", "--all", "-vv"]) || "(no branches)", args.filter))
         if (sub === "create") {
           if (!args.name) return "Error: branch create requires name"
           validateRef(args.name, "branch")
           const cmdArgs = ["branch", args.name]
           if (args.ref) cmdArgs.push(validateRef(args.ref))
-          const r = runGitStrict(ctx.cwd, cmdArgs)
+          const r = await runGitStrict(ctx.cwd, cmdArgs)
           return r.ok ? `Branch ${args.name} created` : truncate(`git branch failed: ${r.err || r.out}`)
         }
         if (sub === "switch") {
           if (!args.name) return "Error: branch switch requires name"
           validateRef(args.name, "branch")
-          const r = runGitStrict(ctx.cwd, ["checkout", args.name])
+          const r = await runGitStrict(ctx.cwd, ["checkout", args.name])
           return r.ok ? `Switched to branch ${args.name}` : truncate(`git checkout ${args.name} failed: ${r.err || r.out}`)
         }
         if (sub === "delete") {
           if (!args.name) return "Error: branch delete requires name"
           validateRef(args.name, "branch")
           const snap = await snapshotBefore(ctx, `branch delete ${args.name}`)
-          const r = runGitStrict(ctx.cwd, ["branch", "-d", args.name])
+          const r = await runGitStrict(ctx.cwd, ["branch", "-d", args.name])
           return r.ok ? truncate(snap + `Branch ${args.name} deleted`) : truncate(`git branch -d failed: ${r.err || r.out}`)
         }
         return "Error: branch requires branchAction — use: list | create | delete | switch"
@@ -315,12 +326,12 @@ const gitActionCore = {
         if (args.path) {
           // Restore file from index (discards working-tree changes to it) — destructive: snapshot first.
           const snap = await snapshotBefore(ctx, `checkout -- ${args.path}`)
-          const r = runGitStrict(ctx.cwd, ["checkout", "--", args.path])
+          const r = await runGitStrict(ctx.cwd, ["checkout", "--", args.path])
           return r.ok ? truncate(snap + `Restored ${args.path}`) : truncate(`git checkout -- ${args.path} failed: ${r.err || r.out}`)
         }
         if (args.ref) {
           validateRef(args.ref, "ref")
-          const r = runGitStrict(ctx.cwd, ["checkout", args.ref])
+          const r = await runGitStrict(ctx.cwd, ["checkout", args.ref])
           return r.ok ? truncate(r.out || `Checked out ${args.ref}`) : truncate(`git checkout ${args.ref} failed: ${r.err || r.out}`)
         }
         return "Error: checkout requires ref (branch/commit) or path (file to restore)"
@@ -331,21 +342,21 @@ const gitActionCore = {
         const cmdArgs = ["restore"]
         if (args.staged) cmdArgs.push("--staged")
         cmdArgs.push("--", args.path)
-        const r = runGitStrict(ctx.cwd, cmdArgs)
+        const r = await runGitStrict(ctx.cwd, cmdArgs)
         return r.ok ? truncate(snap + `Restored ${args.path}`) : truncate(`git restore failed: ${r.err || r.out}`)
       }
       case "stash": {
         const sub = args.stashAction
-        if (sub === "list") return truncate(filterLines(runGit(ctx.cwd, ["stash", "list"]) || "(no stashes)", args.filter))
+        if (sub === "list") return truncate(filterLines(await runGit(ctx.cwd, ["stash", "list"]) || "(no stashes)", args.filter))
         if (sub === "push") {
           const cmdArgs = ["stash", "push"]
           if (args.message) cmdArgs.push("-m", args.message)
-          const r = runGitStrict(ctx.cwd, cmdArgs)
+          const r = await runGitStrict(ctx.cwd, cmdArgs)
           return r.ok ? truncate(r.out || "Stashed") : truncate(`git stash push failed: ${r.err || r.out}`)
         }
         if (sub === "pop") {
           const snap = await snapshotBefore(ctx, "stash pop")
-          const r = runGitStrict(ctx.cwd, ["stash", "pop"])
+          const r = await runGitStrict(ctx.cwd, ["stash", "pop"])
           return r.ok ? truncate(snap + (r.out || "Popped")) : truncate(`git stash pop failed: ${r.err || r.out}`)
         }
         return "Error: stash requires stashAction — use: push | pop | list"
@@ -354,14 +365,14 @@ const gitActionCore = {
         const cmdArgs = ["fetch"]
         if (args.remote) cmdArgs.push(validateRef(args.remote, "remote"))
         if (args.ref) cmdArgs.push(validateRef(args.ref, "ref"))
-        const r = runGitStrict(ctx.cwd, cmdArgs, cfgArgs)
+        const r = await runGitStrict(ctx.cwd, cmdArgs, cfgArgs)
         return r.ok ? truncate(r.out || "(fetch complete — no output)") : truncate(`git fetch failed: ${r.err || r.out}`)
       }
       case "pull": {
         const cmdArgs = ["pull"]
         if (args.remote) cmdArgs.push(validateRef(args.remote, "remote"))
         if (args.ref) cmdArgs.push(validateRef(args.ref, "ref"))
-        const r = runGitStrict(ctx.cwd, cmdArgs, cfgArgs)
+        const r = await runGitStrict(ctx.cwd, cmdArgs, cfgArgs)
         return r.ok ? truncate(r.out || "(pull complete — no output)") : truncate(`git pull failed: ${r.err || r.out}`)
       }
       case "reset": {
@@ -371,24 +382,24 @@ const gitActionCore = {
         if (mode === "hard") snap = await snapshotBefore(ctx, "reset --hard") // destructive: drops working-tree changes
         const cmdArgs = ["reset", `--${mode}`]
         if (args.ref) cmdArgs.push(validateRef(args.ref))
-        const r = runGitStrict(ctx.cwd, cmdArgs)
+        const r = await runGitStrict(ctx.cwd, cmdArgs)
         return r.ok ? truncate(snap + (r.out || `Reset (${mode}) complete`)) : truncate(`git reset failed: ${r.err || r.out}`)
       }
       case "revert": {
         const ref = validateRef(args.ref ?? "HEAD")
-        const r = runGitStrict(ctx.cwd, ["revert", "--no-edit", ref])
+        const r = await runGitStrict(ctx.cwd, ["revert", "--no-edit", ref])
         return r.ok ? truncate(r.out || `Reverted ${ref}`) : truncate(`git revert failed: ${r.err || r.out}`)
       }
       case "merge": {
         if (!args.ref) return "Error: merge requires ref (branch/commit to merge)"
         validateRef(args.ref, "ref")
-        const r = runGitStrict(ctx.cwd, ["merge", "--no-edit", args.ref])
+        const r = await runGitStrict(ctx.cwd, ["merge", "--no-edit", args.ref])
         return r.ok ? truncate(r.out || `Merged ${args.ref}`) : truncate(`git merge failed: ${r.err || r.out} — resolve conflicts, then commit`)
       }
       case "cherry-pick": {
         if (!args.ref) return "Error: cherry-pick requires ref (commit)"
         validateRef(args.ref, "ref")
-        const r = runGitStrict(ctx.cwd, ["cherry-pick", args.ref])
+        const r = await runGitStrict(ctx.cwd, ["cherry-pick", args.ref])
         return r.ok ? truncate(r.out || `Cherry-picked ${args.ref}`) : truncate(`git cherry-pick failed: ${r.err || r.out}`)
       }
       // F7 扩展 action + checkpoint：实现拆在 git-ext.mjs / git-checkpoint.mjs（500 行硬限）

package/tools/index.mjs

@@ -45,8 +45,10 @@ export {
 // faces (memory / code+doc search / repo outline / settings / peer instances)
 // whose factories need the shell's memory handle at run time.
 //
-// Host-only tools (VS Code `context` / `focus` — TOOLS #179 ④, IDE capabilities)
+// Host-only tools (VS Code `ide` / `focus` — TOOLS #179 ④, IDE capabilities)
 // are NOT part of the core registry: the VS Code shell adds them itself.
+// D-CC26（context-tool 批 2026-09-21）：宿主 IDE 快照工具自 `context` **改名 `ide`**（`tools/ide.mjs`）
+// ——让出 `context` 名给核新工具（`agent-tools/context.mjs`；同名撞车 ⇒ provider 逐字 400）。
 //
 // `read_image` registration follows VS Code (#70): it is registered only when the
 // model accepts image input (`specForModel(model).multimodal`) — the conservative

package/tools/process-tree.mjs

@@ -0,0 +1,20 @@
+/**
+ * tools/process-tree.mjs — 平台感知树杀单源（自 `execute.mjs` 抽出——TOOLS.md §6.14 落位表行 2）。
+ * 抽出理由 = **断环**：`shared → git-run → execute → shared` 会 TDZ（`execute.mjs:29` 在模块求值期
+ * 调 `DESC`（`const`））⇒ 树杀须住两不依赖档。行为逐字同（win32 `taskkill /T /F` · POSIX 组杀 + 直杀兜底）。
+ * `execute.mjs` 保持再导出面（`test/tool-seams.test.mjs:26` 消费）。
+ */
+import { execFileSync } from "node:child_process"
+
+/** Platform-aware process tree kill — mirror of system.mjs/verify.mjs killProcessTree.
+ *  Timeout/abort must reach grandchildren: a script that spawned children keeps the
+ *  pipes open otherwise — "close" never fires and the tool stalls until the 3s kick
+ *  while the orphan keeps running (2026-09-05 advisor 🟡#4). */
+export function killProcessTree(child) {
+  if (process.platform === "win32") {
+    try { execFileSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore" }) } catch {}
+  } else {
+    try { process.kill(-child.pid, "SIGKILL") } catch {}
+    try { child.kill("SIGKILL") } catch {}
+  }
+}

package/tools/shared.mjs

@@ -8,6 +8,7 @@ import { readFileSync, existsSync, realpathSync, readdirSync, statSync, openSync
 import { dirname, join, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
 import { loadToolDoc, applyPromptInjections } from "../prompt-files.mjs"
+import { spawnGit, gitTimeoutNote, GIT_TIMEOUT_MS } from "./git-run.mjs"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 // 工具描述加载面——**核内单一解析面**（D-C13 / 契约 8）：解析根 = `prompt-files.mjs`
@@ -438,8 +439,10 @@ export function htmlToText(html) {
 
 /** git 失败消息构造单点（#55 fail-closed——`runGit` / `runGitRaw` 两读取面同款）：形态 =
  *  `git <args…> failed: <stderr 首行> (cwd: <绝对 cwd>)`；**非仓**失败（退出码 128 ∧ stderr 首行含
- *  `not a git repository`）尾附 workdir 指引；spawn 失败（无 stderr）取 `e.message` 首行——**禁空尾**。 */
+ *  `not a git repository`）尾附 workdir 指引；spawn 失败（无 stderr）取 `e.message` 首行——**禁空尾**。
+ *  **超时**（`e.timedOut`——§6.14）：帧 + 单源超时注（`gitTimeoutNote`，含树杀尽义与恢复指引）。 */
 export function gitFailureMessage(e, cmdArgs, cwd) {
+  if (e?.timedOut) return `git ${cmdArgs.join(" ")} failed: ${gitTimeoutNote(e.timeoutMs ?? GIT_TIMEOUT_MS)} (cwd: ${resolve(cwd ?? ".")})`
   const stderr = String(e?.stderr ?? "").trim()
   const first = stderr.split("\n")[0].trim() || String(e?.message || e?.code || "unknown error").split("\n")[0]
   const notRepo = e?.status === 128 && first.includes("not a git repository")
@@ -449,10 +452,11 @@ export function gitFailureMessage(e, cmdArgs, cwd) {
 
 /** Execute a git command. maxBuffer 10MB prevents large diff/log overflow; on overflow, returns truncated partial output rather than empty.
  *  config: optional array of `-c key=value` overrides (e.g. ["http.proxy=http://10.2.2.112:3128"]) —
- *  inserted verbatim after `git`, so network actions (push/fetch/pull/ls-remote) can route through a proxy. */
-export function runGit(cwd, cmdArgs, config = []) {
+ *  inserted verbatim after `git`, so network actions (push/fetch/pull/ls-remote) can route through a proxy.
+ *  §6.14：体改**异步薄壳**委托 `spawnGit` 单点（加固 env + 两档超时 + 树杀）；trim / `\r` / 溢出 / 抛出四形逐字保留。 */
+export async function runGit(cwd, cmdArgs, config = []) {
   try {
-    return execFileSync("git", [...config, ...cmdArgs], { cwd, encoding: "utf8", maxBuffer: 10 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }).trim().replace(/\r/g, "")
+    return (await spawnGit(cwd, [...config, ...cmdArgs], { maxBuffer: 10 * 1024 * 1024 })).trim().replace(/\r/g, "")
   } catch (e) {
     // maxBuffer overflow: e.stdout contains partial collected output — return it
     // (callers show "(truncated)"-style tails). Every OTHER failure (non-git repo,

package/traces/trace-cleanup.mjs

@@ -0,0 +1,109 @@
+/**
+ * trace-cleanup.mjs — 轨迹清理执行面（TRACES.md §6.4 · STARTUP-LATENCY 批，2026-09-21）。
+ *
+ * 判据 = **目录级三段梯**（D-TR11）：设 `D` = 日目录（`YYYY-MM-DD`——本地时区，与
+ * `localDateStr` 同口径）、`retention` = `traces.retentionHours`：
+ *   ① `dayEnd(D) + retention ≤ now` **且目录内全部条目为 `.jsonl`** ⇒ **整目录删**
+ *      （递归 rm，零逐文件 stat）；
+ *   ② `dayStart(D) + retention > now` ⇒ **整目录跳过**（正常写入下目录内无可过期文件）；
+ *   ③ 其余（含非 `.jsonl` 条目的目录；非日期名目录——日期解析 NaN ⇒ ①② 两条件恒假 ⇒ 自然落 ③）
+ *      ⇒ 逐文件 `stat` 判定 + unlink（现行语义；非 `.jsonl` 一律不碰）。
+ *   空日目录在任何分支后按现法移除。
+ *
+ * 计数口径（D-TR11）：整删支的 `removed` = 该批内 `.jsonl` 条目数（与 ③ 支逐文件计入同口径；
+ * 非 `.jsonl` 不计数）——既有断言面保持。
+ * 语义 delta（登记）：整删不逐文件核 mtime（人为回拨 mtime 的文件随目录清理——正常写入
+ * mtime ∈ 目录日 ⇒ 无差异）；② 支跳过时人为前拨（超期）文件暂留（宽容向）——保留期主粒度
+ * 改为**目录日**（与 §6.1 的 24h 保留期并读）。
+ *
+ * 本体**无状态**（手动面 / 每写节流面直调——启动面经 `scheduleTraceCleanup`）；每写节流住
+ * `trace-store.mjs`（`maybePruneTraces`——D-TR12：10 分钟窗 + 在飞合并）。启动面 = **启动窗外
+ * 延迟拍**（D-TR13）：`scheduleTraceCleanup` + `TRACE_CLEANUP_DELAY_MS`（3s）住本档、由 CLI
+ * 直引（白名单 / 闸位住调用面）；`_setTraceCleanupDelayForTest` = 延迟测试缝。
+ * `_cleanupHooks` = 测试注入缝（`_traceHooks` 同惯例——stat 计数 / 失败注入；生产永远走真实实现）。
+ */
+import { readdir, stat, unlink, rmdir, rm } from "node:fs/promises"
+import { join } from "node:path"
+
+export const _cleanupHooks = {
+  readdir: (dir) => readdir(dir),
+  stat: (p) => stat(p),
+  unlink: (p) => unlink(p),
+  rmdir: (d) => rmdir(d),
+  rm: (d) => rm(d, { recursive: true, force: true }),
+}
+
+const DAY_RE = /^(\d{4})-(\d{2})-(\d{2})$/
+
+/** 日目录边界（本地时区——`localDateStr` 同口径）；非日期名 / 非法日（如 2026-02-31）
+ *  ⇒ null（⇒ ①② 两条件恒假 ⇒ 落 ③ 逐文件支）。 */
+export function dayBounds(name) {
+  const m = DAY_RE.exec(name)
+  if (!m) return null
+  const y = Number(m[1])
+  const mo = Number(m[2])
+  const d = Number(m[3])
+  const start = new Date(y, mo - 1, d).getTime()
+  if (Number.isNaN(start) || new Date(start).getDate() !== d) return null // 2026-02-31 归一为 03-03 ⇒ 非日期名
+  return { start, end: new Date(y, mo - 1, d, 23, 59, 59, 999).getTime() }
+}
+
+/**
+ * D-TR10 保留期语义 + D-TR11 目录级判据：删除 traces 根下 mtime 超过保留期的轨迹文件
+ * （保留期 = config.traces.retentionHours，默认 24h）；删空的日期目录（YYYY-MM-DD）。
+ * 目录里非 .jsonl 文件不碰。返回删除文件数（整删支 = 批内 `.jsonl` 条目数）。
+ */
+export async function cleanupTraces({ dir, retentionHours = 24 } = {}) {
+  const now = Date.now()
+  const cutoff = now - retentionHours * 3_600_000
+  const window = retentionHours * 3_600_000
+  let days
+  try { days = await _cleanupHooks.readdir(dir) } catch { return 0 } // 目录不存在/不可读 → 无事可做
+  let removed = 0
+  for (const day of days) {
+    const dayDir = join(dir, day)
+    let names
+    try { names = await _cleanupHooks.readdir(dayDir) } catch { continue } // 非目录 / 不可读 → 跳过
+    const bounds = dayBounds(day)
+    if (bounds && bounds.end + window <= now && names.every((n) => n.endsWith(".jsonl"))) {
+      // ① 整目录删（纯 .jsonl 且全目录过期——零逐文件 stat；批内条目全计入）
+      try { await _cleanupHooks.rm(dayDir); removed += names.length } catch { /* 占用/竞态——跳过 */ }
+      continue
+    }
+    if (bounds && bounds.start + window > now) {
+      // ② 整目录跳过（未到期——空日目录仍按现法移除）
+      try { if (!names.length) await _cleanupHooks.rmdir(dayDir) } catch { /* 跳过 */ }
+      continue
+    }
+    // ③ 逐文件（现行语义——非 .jsonl 一律不碰）
+    for (const n of names) {
+      if (!n.endsWith(".jsonl")) continue
+      try {
+        if ((await _cleanupHooks.stat(join(dayDir, n))).mtimeMs < cutoff) { await _cleanupHooks.unlink(join(dayDir, n)); removed++ }
+      } catch { /* 单个文件失败不影响其余 */ }
+    }
+    try { if ((await _cleanupHooks.readdir(dayDir)).length === 0) await _cleanupHooks.rmdir(dayDir) } catch { /* 跳过 */ }
+  }
+  return removed
+}
+
+// ─── 启动窗外延迟拍（D-TR13 · 2026-09-21 收口前机制微修 2）────────────────────────────────
+
+/** 延迟（自**调度点**起）：与 D-SE39 的 `GC_PASS_DELAY_MS` 同值同形态——3s ⇒ 清理起点落于
+ *  启动窗（TTY 门 ≤2s）之外，启动链不因本清理的 fs 爆发与自身争同一事件循环。 */
+export const TRACE_CLEANUP_DELAY_MS = 3000
+let traceCleanupDelayMs = TRACE_CLEANUP_DELAY_MS
+
+/** 测试缝（`_setSessionGcDelayForTest` 同款）：用例置 0–短值即可点火（勿真等 3s）；
+ *  还原 = `_setTraceCleanupDelayForTest(TRACE_CLEANUP_DELAY_MS)`。 */
+export function _setTraceCleanupDelayForTest(ms) { traceCleanupDelayMs = ms }
+
+/** 启动面调度器（CLI 会话型命令白名单闸内直引——`thincoder-cli/bin/thincoder.mjs`）：
+ *  `dir` / `retentionHours` 由**调度点**捕获（调用面取 `tracesRoot()`）；延迟
+ *  `TRACE_CLEANUP_DELAY_MS` 后点火。失败静默（`.catch` 在此——fire-and-forget 语义不变）；
+ *  **不 unref**（保后台排空现状——同 D-SE39）。**无去重闸**：白名单 / 闸位 / 每进程一次语义
+ *  住调用面（启动面恰一处调用）；进程早退（显式 `process.exit`）未及拍 ⇒ 本次不执行
+ *  （幂等——下次会话型命令照常清理）。 */
+export function scheduleTraceCleanup({ dir, retentionHours = 24 } = {}) {
+  setTimeout(() => { cleanupTraces({ dir, retentionHours }).catch(() => { /* 失败静默——同上 */ }) }, traceCleanupDelayMs)
+}