@thincoder/core 0.9.2 → 0.9.4

package/tools/git-ext.mjs

@@ -4,7 +4,7 @@
  * 供 git.mjs 核心 action 复用——500 行硬限拆分）。CLI 与 VS Code 两端同构（镜像，修改须两端同批）。
  */
 import { runGit, truncate } from "./shared.mjs"
-import { execFileSync } from "node:child_process"
+import { spawnGit, gitTimeoutNote } from "./git-run.mjs"
 
 /** Keep only output lines matching a regex (git filter, case-insensitive). */
 export function filterLines(output, filter) {
@@ -19,12 +19,15 @@ export function filterLines(output, filter) {
 }
 
 /** Run git and report failure (stderr + exit code) instead of swallowing it.
- *  Used by write ops (commit/push/rm) where a silent "" would masquerade as success. */
-export function runGitStrict(cwd, cmdArgs, config = []) {
+ *  Used by write ops (commit/push/rm) where a silent "" would masquerade as success.
+ *  §6.14：体改**异步薄壳**（`spawnGit` 单点——加固 env + 两档超时 + 树杀）；`{ok, out, err}` 形逐字保留
+ *  + 超时分支（`err` = 单源超时注——可辨性不靠 stderr 文本猜）。 */
+export async function runGitStrict(cwd, cmdArgs, config = []) {
   try {
-    const out = execFileSync("git", [...config, ...cmdArgs], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim().replace(/\r/g, "")
+    const out = (await spawnGit(cwd, [...config, ...cmdArgs])).trim().replace(/\r/g, "")
     return { ok: true, out }
   } catch (e) {
+    if (e.timedOut) return { ok: false, out: String(e.stdout || "").trim(), err: gitTimeoutNote(e.timeoutMs) }
     return { ok: false, out: String(e.stdout || "").trim(), err: String(e.stderr || e.message || "").trim() }
   }
 }
@@ -36,7 +39,7 @@ export function validateRef(ref, what = "git ref") {
 }
 
 /** Normalize args.config into `-c key=value` pairs (git -c overrides, e.g. a proxy).
- *  Values are execFileSync array args (no shell injection) — still reject newlines/empty. */
+ *  Values are spawn array args (no shell injection) — still reject newlines/empty. */
 export function gitConfigArgs(config) {
   if (config == null) return []
   if (!Array.isArray(config)) throw new Error("config must be an array of \"key=value\" strings")
@@ -70,11 +73,11 @@ export async function executeExtAction(args, ctx) {
       if (!args.remote) return "Error: clone requires remote (URL or local path)"
       const cmdArgs = ["clone", args.remote]
       if (args.path) cmdArgs.push(args.path)
-      const r = runGitStrict(ctx.cwd, cmdArgs, gitConfigArgs(args.config))
+      const r = await runGitStrict(ctx.cwd, cmdArgs, gitConfigArgs(args.config))
       return r.ok ? truncate(r.out || `Cloned ${args.remote}`) : truncate(`git clone failed: ${r.err || r.out}`)
     }
     case "init": {
-      const r = runGitStrict(ctx.cwd, ["init"])
+      const r = await runGitStrict(ctx.cwd, ["init"])
       return r.ok ? truncate(r.out || "Initialized empty git repository") : truncate(`git init failed: ${r.err || r.out}`)
     }
     case "rebase": {
@@ -89,21 +92,21 @@ export async function executeExtAction(args, ctx) {
       if (sub === "abort") cmdArgs.push("--abort")
       else if (sub === "continue") cmdArgs.push("--continue")
       else { if (!args.ref) return "Error: rebase requires ref (branch/commit to rebase onto)"; 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 || `Rebase ${sub} complete`)) : truncate(snap + `git rebase failed: ${r.err || r.out} — use rebaseAction=abort to abort`)
     }
     case "remote": {
       const sub = args.remoteAction ?? "list"
-      if (sub === "list") return truncate(filterLines(runGit(ctx.cwd, ["remote", "-v"]) || "(no remotes)", args.filter))
+      if (sub === "list") return truncate(filterLines(await runGit(ctx.cwd, ["remote", "-v"]) || "(no remotes)", args.filter))
       if (!args.remote) return `Error: remote ${sub} requires remote (name)`
       validateRef(args.remote, "remote name")
       if (sub === "add" || sub === "set-url") {
         if (!args.remoteUrl) return `Error: remote ${sub} requires remoteUrl`
-        const r = runGitStrict(ctx.cwd, ["remote", sub === "add" ? "add" : "set-url", args.remote, args.remoteUrl])
+        const r = await runGitStrict(ctx.cwd, ["remote", sub === "add" ? "add" : "set-url", args.remote, args.remoteUrl])
         return r.ok ? `Remote ${args.remote} ${sub === "add" ? "added" : "URL set"}` : truncate(`git remote ${sub} failed: ${r.err || r.out}`)
       }
       if (sub === "remove") {
-        const r = runGitStrict(ctx.cwd, ["remote", "remove", args.remote])
+        const r = await runGitStrict(ctx.cwd, ["remote", "remove", args.remote])
         return r.ok ? `Remote ${args.remote} removed` : truncate(`git remote remove failed: ${r.err || r.out}`)
       }
       return "Error: remote requires remoteAction — use: list | add | remove | set-url"
@@ -113,7 +116,7 @@ export async function executeExtAction(args, ctx) {
       // dryRun (-n) is a preview: no deletion, no snapshot.
       const snap = args.dryRun ? "" : await snapshotBefore(ctx, "clean")
       const cmdArgs = ["clean", args.dryRun ? "-n" : "-f", "-d"]
-      const r = runGitStrict(ctx.cwd, cmdArgs)
+      const r = await runGitStrict(ctx.cwd, cmdArgs)
       return r.ok ? truncate(snap + (r.out || (args.dryRun ? "Nothing to clean (dry run)" : "Clean complete"))) : truncate(snap + `git clean failed: ${r.err || r.out}`)
     }
     case "switch": {
@@ -122,28 +125,28 @@ export async function executeExtAction(args, ctx) {
       const cmdArgs = ["switch"]
       if (args.create) cmdArgs.push("-c")
       cmdArgs.push(args.name)
-      const r = runGitStrict(ctx.cwd, cmdArgs)
+      const r = await runGitStrict(ctx.cwd, cmdArgs)
       return r.ok ? truncate(r.out || `Switched to branch ${args.name}`) : truncate(`git switch failed: ${r.err || r.out}`)
     }
     case "apply": {
       // Apply a patch — non-destructive (fails cleanly on conflict, applies nothing).
       if (!args.path) return "Error: apply requires path (patch file)"
-      const r = runGitStrict(ctx.cwd, ["apply", "--", args.path])
+      const r = await runGitStrict(ctx.cwd, ["apply", "--", args.path])
       return r.ok ? truncate(r.out || `Applied ${args.path}`) : truncate(`git apply failed: ${r.err || r.out}`)
     }
     case "worktree": {
       const sub = args.worktreeAction ?? "list"
-      if (sub === "list") return truncate(filterLines(runGit(ctx.cwd, ["worktree", "list"]) || "(no worktrees)", args.filter))
+      if (sub === "list") return truncate(filterLines(await runGit(ctx.cwd, ["worktree", "list"]) || "(no worktrees)", args.filter))
       if (sub === "add") {
         if (!args.path) return "Error: worktree add requires path (new worktree directory)"
         const cmdArgs = ["worktree", "add", args.path]
         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(r.out || `Worktree added at ${args.path}`) : truncate(`git worktree add failed: ${r.err || r.out}`)
       }
       if (sub === "remove") {
         if (!args.path) return "Error: worktree remove requires path"
-        const r = runGitStrict(ctx.cwd, ["worktree", "remove", args.path])
+        const r = await runGitStrict(ctx.cwd, ["worktree", "remove", args.path])
         return r.ok ? truncate(r.out || `Worktree removed: ${args.path}`) : truncate(`git worktree remove failed: ${r.err || r.out}`)
       }
       return "Error: worktree requires worktreeAction — use: list | add | remove"
@@ -154,17 +157,17 @@ export async function executeExtAction(args, ctx) {
       const cmdArgs = ["archive", "--format=tar", "-o", args.path]
       if (args.ref) cmdArgs.push(validateRef(args.ref))
       else cmdArgs.push("HEAD")
-      const r = runGitStrict(ctx.cwd, cmdArgs)
+      const r = await runGitStrict(ctx.cwd, cmdArgs)
       return r.ok ? truncate(r.out || `Archived ${args.ref ?? "HEAD"} to ${args.path}`) : truncate(`git archive failed: ${r.err || r.out}`)
     }
     case "blame": {
       if (!args.path) return "Error: blame requires path (file)"
-      const out = runGit(ctx.cwd, ["blame", "--", args.path])
+      const out = await runGit(ctx.cwd, ["blame", "--", args.path])
       return truncate(out || `(no blame output for ${args.path})`)
     }
     case "mv": {
       if (!args.path || !args.dest) return "Error: mv requires path (source) and dest (destination)"
-      const r = runGitStrict(ctx.cwd, ["mv", "--", args.path, args.dest])
+      const r = await runGitStrict(ctx.cwd, ["mv", "--", args.path, args.dest])
       return r.ok ? truncate(r.out || `Moved ${args.path} → ${args.dest}`) : truncate(`git mv failed: ${r.err || r.out}`)
     }
     default:

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))
@@ -150,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 = []
@@ -196,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": {
@@ -222,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)
@@ -249,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": {
@@ -258,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))
       }
@@ -267,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"
@@ -320,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)"
@@ -336,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"
@@ -359,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": {
@@ -376,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,