thincoder 0.12.58 → 0.12.60

package/src/tools/edit-diff.mjs

@@ -0,0 +1,348 @@
+/**
+ * edit-diff.mjs — edit 工具的行级 diff 内核（权威语义 = EDIT.md——2026-09-04 拆出）。
+ *
+ * edit 语义（权威 = EDIT.md §2-§5——2026-09-08 语义升级 D1/D2/D3 已并入）：两种定位形态（互斥）——
+ * ① 按行号改（D1/F1）：line（单行）/ startLine+endLine（1-based 闭区间）→ 直接替换该
+ *    行/行范围为 new_string（无需 old_string——实现落点 edit-batch.mjs applyLineEdit）；
+ *    阶段 2 删行形态（EDIT.md §5——约束）：省略 new_string = 删除该行/范围（有界意图）；
+ * ② 内容定位：old_string = 变化区**当前内容**（单次匹配——匹配档位：逐字 → P15.11 唯一
+ *    空白差异窗口 → D2/F2 模糊匹配（行级 normalize 后 ≥90% 行相等——edit-batch.mjs
+ *    findFuzzyWindow））；new_string = 该区的**期望结果**。判定序：
+ *   0. 分支 0（EDIT.md §4——单行精确替换）：old 单行 && new 单行 && old 全文唯一 &&
+ *      new 非空 → **就地替换该行**（行数不变——EOL 由调用方 joinWithEol 恢复）；
+ *   1. 零重叠（old 每一行都不出现在 new 行集中）→ **替换即删**（D3/F3，2026-09-08——
+ *      breaking：old 行整体删除、new 取而代之——旧行不再保留；新增行用 insert_after）；
+ *   2. 有公共行（≥1）→ 行级 LCS——公共行保留、差异行增删；
+ *   3. new 与 old 行级完全一致 → 原样替换（no-op 语义——仍报成功）。
+ * 内容形态空 new_string（纯删除意图）→ 显式报错（不静默——先于分支 0——单行替换永不
+ * 成删除）；行号形态显式空串 → 同样显式错（防误删——模板落空 ≠ 删行意图；EDIT.md
+ * §5 空串 vs 省略矩阵）；**省略 new_string = 删行/范围**（阶段 2 命名删行形态）；
+ * 分支 0 只在 computeEditEntry 条目判定层（壳/桥/批量自动继承）——
+ * applyPatchLines（纯 diff 层）语义不动。old/new 行数各上限 1000（超限报错）。
+ *
+ * 行尾权威 = EDIT-TOOL-EOL-DESIGN.md：判定/应用在 normalizeEOL 后的 LF 域计算，
+ * 写回由调用方 joinWithEol(原文) 恢复原行尾。
+ * 模块拆分（file.mjs ≤500 硬限）：file.mjs 只留工具壳与转发——单形态执行体与前置校验
+ * 分支整段迁出至本模块（模块拆分写优先纪律：先迁后删、逻辑体不变、wiring 导入）。
+ * edit-diff.mjs ↔ edit-batch.mjs 循环引用（2026-09-08——D1/D2 实现落点 edit-batch）：
+ * 两侧仅函数声明（提升初始化）、仅调用期使用——ESM 循环下安全（同 file.mjs 先例）。
+ */
+import { readFile, writeFile } from "node:fs/promises"
+import {
+  resolveInCwd, normalizeEOL, joinWithEol, gitDiffOne, autoSyntaxCheck, findCandidates,
+} from "./shared.mjs"
+// file.mjs ↔ edit-diff.mjs 循环引用：两侧导入的都是函数声明（提升初始化），
+// 仅在调用期使用——ESM 循环下安全（无模块求值期取值）。
+import { recordWrite, appendWriteContext, lastWriteOf, isDirty } from "./file.mjs"
+// D1/D2 落点（EDIT.md §6——edit-batch.mjs）：按行号改 + 模糊匹配纯函数。
+import { applyLineEdit, findFuzzyWindow, FUZZY_MATCH_NOTE } from "./edit-batch.mjs"
+
+export const MAX_DIFF_LINES = 1000
+export const REGION_TOO_LARGE = "edit region too large — narrow the change"
+export const EMPTY_NEW_STRING = "empty new_string — for deletion, keep the context lines you want to preserve in both old_string and new_string"
+export const EMPTY_NEW_STRING_LINE = "empty new_string with line-based targeting is an explicit error — OMIT new_string to delete the line/range (deleting by number is explicit intent; an empty replacement is a mistake, not a delete)"
+export const EDIT_ARGS_MUTEX = "edits array is mutually exclusive with top-level old_string/new_string/line/startLine/endLine — a top-level path is allowed (default for entries without their own path); provide each change's targeting (old_string or line range) and new_string inside its edits entry"
+
+/** D1（2026-09-08）：条目带按行号改参数（line / startLine / endLine 任一）。 */
+export function hasLineParams(entry) {
+  return entry.line !== undefined || entry.startLine !== undefined || entry.endLine !== undefined
+}
+
+/** 删行结果文本（EDIT.md——删行返回文本；out.deleted 才调用）：单行 "line N" / 范围 "lines N-M"。
+ *  删行 lineShift = -(范围行数)——end = start - 1 - lineShift。 */
+export function deleteTarget(out) {
+  const start = out.editStartLine
+  const end = start - 1 - out.lineShift
+  return start === end ? `line ${start}` : `lines ${start}-${end}`
+}
+
+/** 行切分（尾随换行终止最后一行——非额外空行）："a\nb\n" → ["a","b"]。
+ *  2026-09-08 导出（D1 落点 edit-batch.mjs applyLineEdit 复用同语义）。 */
+export function splitLines(text) {
+  const lines = text.split("\n")
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop()
+  return lines
+}
+
+/**
+ * 行级 LCS（整行相等判定）合并：公共行保留（LCS 序）、old 独有行删除、new 独有行按其在
+ * new 中相对公共行的位置插入；**零重叠 → 替换即删**（D3，2026-09-08 语义升级——
+ * breaking：old 行整体删除、new 取而代之，旧行不再保留——原"零重叠→插入保留旧行"
+ * 语义废止；新增行用 insert_after）。结果在 LF 域；区域尾随换行随 oldText（区域边界保持）。
+ * 返回 { ok: true, resultText } 或 { ok: false, reason }。
+ */
+export function applyPatchLines(oldText, newText) {
+  if (newText === "") return { ok: false, reason: EMPTY_NEW_STRING }
+  const oldLines = splitLines(oldText)
+  const newLines = splitLines(newText)
+  if (oldLines.length > MAX_DIFF_LINES || newLines.length > MAX_DIFF_LINES) {
+    return { ok: false, reason: REGION_TOO_LARGE }
+  }
+  // 判定 1（D3——替换即删）：零重叠 → old 行删、new 整体取代（旧行不再保留）
+  const newSet = new Set(newLines)
+  const merged = oldLines.some((l) => newSet.has(l))
+    ? lcsMerge(oldLines, newLines) // 判定 2/3——公共行保留、差异行增删
+    : [...newLines]
+  return { ok: true, resultText: merged.join("\n") + (oldText.endsWith("\n") ? "\n" : "") }
+}
+
+/** LCS 推导（DP + 回溯）——整行相等判定；结果 = 公共行 + 差异行增删的合并序列。 */
+function lcsMerge(a, b) {
+  const n = a.length
+  const m = b.length
+  const width = m + 1
+  const dp = new Uint16Array((n + 1) * width)
+  for (let i = 1; i <= n; i++) {
+    for (let j = 1; j <= m; j++) {
+      dp[i * width + j] = a[i - 1] === b[j - 1]
+        ? dp[(i - 1) * width + (j - 1)] + 1
+        : Math.max(dp[(i - 1) * width + j], dp[i * width + (j - 1)])
+    }
+  }
+  const merged = []
+  let i = n
+  let j = m
+  while (i > 0 && j > 0) {
+    if (a[i - 1] === b[j - 1]) {
+      merged.push(a[i - 1])
+      i--
+      j--
+    } else if (dp[(i - 1) * width + j] >= dp[i * width + (j - 1)]) {
+      i-- // old 独有行——删除
+    } else {
+      merged.push(b[j - 1]) // new 独有行——按 LCS 相对位置插入
+      j--
+    }
+  }
+  while (j > 0) { merged.push(b[j - 1]); j-- }
+  return merged.reverse()
+}
+
+/**
+ * （2026-09-05 用户裁定——EDIT.md §5——顶层 path + edits 并存合法化：顶层 path = 无自带
+ * path 条目的默认——模型直觉形态「顶层 path + 数组条目」不再拒绝；条目自带 path 优先）。
+ * 互斥收窄为只对顶层 old_string/new_string（+ 2026-09-08 D1 的 line/startLine/endLine）——
+ * edits 下它们无批语义可解释——顶层 path 不再触发。
+ */
+export function assertEditArgsExclusive(args) {
+  if (args.old_string !== undefined || args.new_string !== undefined || hasLineParams(args)) {
+    throw new Error(EDIT_ARGS_MUTEX)
+  }
+}
+
+/**
+ * 前置校验——内容形态：空 old / 非字符串 new；按行号改形态（D1，2026-09-08；阶段 2
+ * 删行——EDIT.md §5）：与 old_string 互斥 / line 与 startLine|endLine 互斥 /
+ * startLine+endLine 须成对 / 正整数 / endLine ≥ startLine / replace_all 不适用 /
+ * new_string：省略（undefined）= 删行 / 显式空串 = 显式错（防误删）/ 其他类型报错。
+ * error 文本按调用形态（单形态 rich / 批量 label）。
+ * opts: { label = ""（批量前缀 "edit for <path>: "）, rich = true（单形态完整文本） }
+ */
+export function validateEditEntry(entry, opts = {}) {
+  const label = opts.label ?? ""
+  if (hasLineParams(entry)) {
+    if (entry.old_string !== undefined) {
+      throw new Error(label + "line/startLine/endLine are mutually exclusive with old_string — target by line number OR by content, not both")
+    }
+    if (entry.line !== undefined && (entry.startLine !== undefined || entry.endLine !== undefined)) {
+      throw new Error(label + "line is mutually exclusive with startLine/endLine — single line or a range, not both")
+    }
+    if ((entry.startLine === undefined) !== (entry.endLine === undefined)) {
+      throw new Error(label + "startLine and endLine must be given together (1-based, inclusive)")
+    }
+    for (const k of ["line", "startLine", "endLine"]) {
+      if (entry[k] !== undefined && (!Number.isInteger(entry[k]) || entry[k] < 1)) {
+        throw new Error(label + `${k} must be a positive integer (1-based), got ${JSON.stringify(entry[k])}`)
+      }
+    }
+    if (entry.startLine !== undefined && entry.endLine < entry.startLine) {
+      throw new Error(label + `endLine (${entry.endLine}) is before startLine (${entry.startLine})`)
+    }
+    if (entry.replace_all) {
+      throw new Error(label + "replace_all does not apply to line-based edits (a line range is already a single explicit target)")
+    }
+    if (entry.new_string === "") {
+      throw new Error(label + EMPTY_NEW_STRING_LINE + (opts.rich === false ? "" : " — nothing written"))
+    }
+    if (entry.new_string !== undefined && typeof entry.new_string !== "string") {
+      throw new Error(
+        label + `new_string must be a string (got ${typeof entry.new_string})` +
+        (opts.rich === false ? "" : " — nothing written")
+      )
+    }
+    return
+  }
+  if (!entry.old_string) {
+    throw new Error(
+      label + "old_string must not be empty" + (opts.rich === false ? "" : " (empty string matches everywhere and would corrupt the file)")
+    )
+  }
+  if (entry.new_string === "") {
+    // 空串 vs 省略矩阵（EDIT.md §5/§8.1）：内容形态空串 = 显式错（无界意图防静默）——
+    // 先于 replace_all 分支（否则 replace_all + 空串会静默删除全部 occurrences——绕过保护）
+    throw new Error(label + EMPTY_NEW_STRING + (opts.rich === false ? "" : " — nothing written"))
+  }
+  if (typeof entry.new_string !== "string") {
+    throw new Error(
+      label + `new_string must be a string${entry.new_string === undefined ? " (missing)" : ` (got ${typeof entry.new_string})`}` +
+      (opts.rich === false ? "" : " — nothing written")
+    )
+  }
+}
+
+/**
+ * 分支 0 形态判定（EDIT.md §4）：old/new 各为单行——无内部换行（splitLines
+ * 语义：尾随单个换行符是行终止而非新行——old/new 行内容均不含 \n）——且 new 非空
+ * （"" 经 splitLines 切分为 []——由下方 !== "" 守卫先拦截——空 new 不落本分支——落
+ * applyPatchLines 的空 new 显式错误——单行替换永不成删除）。多匹配与 replace_all 不落
+ * 本分支（occurrences 错误 / 字面全部先行）。
+ */
+function isSingleLineReplace(entry) {
+  return (
+    entry.new_string !== "" &&
+    splitLines(entry.old_string).length === 1 &&
+    splitLines(entry.new_string).length === 1
+  )
+}
+
+/**
+ * 条目级判定+应用（单形态与批量共用——EDIT.md §6"批量条目判定+应用调用 edit-diff"）：
+ * 匹配校验（精确存在——非 replace_all 单次）→ 按判定序应用（分支 0 单行替换 / 零重叠替换即删 /
+ * LCS 替换 / replace_all 字面）→
+ * 元数据（受影响区首行/行数差/次数——recordWrite 与结果回显用）。
+ * 返回 { updated, editStartLine, lineShift, occurrences, note?, deleted? }；失败抛错（含路径/引导）。
+ * opts: { path, abortPrefix（批量 "edit aborted (atomic — no files written): "） }
+ */
+/**
+ * P15.11（2026-09-05 用户裁定——edit 连续失败分析）：old_string 逐字 not-found 时——
+ * 若文件中存在**唯一**窗口：行数与 old 相同、逐行 trim() 相等（内容零差异——差异仅前导/
+ * 尾随空白——EOL 已在 normalize 域消除）→ 返回 { actual }（actual = 文件窗口原文）；
+ * 多窗口（两处 trim 同内容不同空白）→ null（歧义不猜——报错引导）；old 含尾换行 → null
+ * （终止符语义边界——不做窗口猜测）。模型从 read 记忆拷贝 old_string 时丢/加前导空格是
+ * 纯机械损耗（本轮 12 次 edit 失败中 8 次空白差异）——内容零差异时自动落点 + 结果明示。
+ */
+function findWhitespaceVariant(content, old) {
+  if (old.endsWith("\n")) return null
+  const oldLines = old.split("\n")
+  const fileLines = content.split("\n")
+  const m = oldLines.length
+  if (m === 0 || fileLines.length < m) return null
+  const trimmed = oldLines.map((l) => l.trim())
+  let hit = null
+  for (let i = 0; i + m <= fileLines.length; i++) {
+    let same = true
+    for (let j = 0; j < m; j++) {
+      if (fileLines[i + j].trim() !== trimmed[j]) { same = false; break }
+    }
+    if (!same) continue
+    const actual = fileLines.slice(i, i + m).join("\n")
+    if (actual === old) continue // 逐字已匹配——occurrences=0 前提下不会发生
+    if (hit) return null // 多窗口空白差异 → 歧义 → 不猜
+    hit = { actual }
+  }
+  return hit
+}
+
+/**
+ * P15.11 note 文案（各端成功消息追加——双端同句）
+ */
+export const WHITESPACE_VARIANT_NOTE = "applied to the unique whitespace-only match (content identical, leading/trailing whitespace differs from your old_string)"
+
+export function computeEditEntry(content, entry, opts = {}) {
+  validateEditEntry(entry, { ...opts, rich: !opts.abortPrefix })
+  // D1 按行号改（EDIT.md §2/§5）：行号定位条目直接按行替换（applyLineEdit——落点
+  // edit-batch.mjs），不走 old_string 匹配/判定序；省略 new_string = 删行（EDIT.md §5）；
+  // 互斥/越界/显式空串均在 validateEditEntry/applyLineEdit 显式报错。
+  if (hasLineParams(entry)) return applyLineEdit(content, entry, opts)
+  // P15.11：not-found 时先查唯一空白差异窗口——命中则以其原文为实际 old 继续（内容零差异
+  // ——自动落点 + note 明示）；实质差异/歧义仍走下方 not-found 报错（不猜内容）。
+  let old = entry.old_string
+  let occurrences = content.split(old).length - 1
+  let note = null
+  if (occurrences === 0) {
+    const variant = findWhitespaceVariant(content, old)
+    if (variant) { old = variant.actual; occurrences = 1; note = WHITESPACE_VARIANT_NOTE }
+  }
+  // D2 模糊匹配（2026-09-08——P15.11 的推广）：逐字/trim 等价都失败后，找唯一
+  // normalize 后 ≥90% 行相等的窗口——细微差异（缩进/引号/行尾空格/少量行差异）自动
+  // 落点 + note 明示；多窗口歧义/不足阈值仍走 not-found 报错（不猜内容）。
+  if (occurrences === 0) {
+    const fuzzy = findFuzzyWindow(content, old)
+    if (fuzzy) { old = fuzzy.actual; occurrences = 1; note = FUZZY_MATCH_NOTE }
+  }
+  if (occurrences === 0) {
+    const preview = entry.old_string.slice(0, 100).split("\n")[0]
+    const cands = findCandidates(content.split("\n"), entry.old_string)
+    let candText = ""
+    if (cands.length > 0) {
+      const header = entry.old_string.includes("\n")
+        ? `  similar lines (old_string line 1: "${entry.old_string.split("\n")[0].slice(0, 80)}"):`
+        : "  similar lines:"
+      candText = "\n" + header + "\n" + cands.map((c) => `    L${c.line}: ${c.preview} (${Math.round(c.score * 100)}%)`).join("\n")
+    }
+    throw new Error(
+      `${opts.abortPrefix ?? ""}old_string not found in ${opts.path ?? "file"}\n` +
+      `  searched: "${preview}${entry.old_string.length > 100 ? "…" : ""}" — use grep to locate the actual content\n` +
+      (opts.absPath && lastWriteOf(opts.absPath)?.type === "write"
+        ? `  hints: this file was modified since your last read (write 全文重写后内容全变) — re-read it to refresh your copy of the content, then retry\n`
+        : opts.absPath && isDirty(opts.absPath)
+          ? `  hints: this file was modified since your last read (a prior write marked it dirty) — re-read it to refresh your copy of the content, then retry\n`
+          : `  hints: whitespace mismatch? file already changed? try reading the file first\n`) +
+      candText
+    )
+  }
+  if (occurrences > 1 && !entry.replace_all) {
+    throw new Error(
+      `${opts.abortPrefix ?? ""}old_string matches ${occurrences} times in ${opts.path ?? "file"}; provide more context or set replace_all`
+    )
+  }
+  const matchIdx = content.indexOf(old)
+  const editStartLine = matchIdx >= 0 ? content.slice(0, matchIdx).split("\n").length : 1
+  let updated
+  let resultForShift
+  if (entry.replace_all) {
+    // 字面替换——不做插入规则（old 多处时"插到哪处"无定义）——不落分支 0（EDIT.md §4）
+    updated = content.split(old).join(entry.new_string)
+    resultForShift = entry.new_string
+  } else if (isSingleLineReplace(entry)) {
+    // 分支 0（EDIT.md §4——单行精确替换）：old 单行 && new 单行 && old 唯一匹配
+    // （occ==1 既有校验保证）&& new 非空（空 new 显式错误先于本分支——防删除）→ **就地
+    // 替换该行**——不再零重叠插入（P15.8——行尾段编辑反复踩的插入坑）。只替换行内容段：
+    // old/new 的尾随换行符属文件结构而非行内容——留在原位——行数不变——EOL 由调用方
+    // joinWithEol 恢复（normalizeEOL 后本域为 LF）。边界声明（评审 2026-09-04）：new 为
+    // 行内容空串（如 new="\n"——置空行意图）时，常规带终止换行的行变空行（行数不变）；
+    // 唯一例外是**无终止换行的末行**被置空——该行随文件结束自然消失（行数 −1——文件格式
+    // 固有边界——空行无法表达）——不落 EMPTY_NEW_STRING 错误路径（new 本身非空串）。
+    const oldLine = splitLines(old)[0]
+    const newLine = splitLines(entry.new_string)[0]
+    updated = content.slice(0, matchIdx) + newLine + content.slice(matchIdx + oldLine.length)
+    resultForShift = newLine
+  } else {
+    const r = applyPatchLines(old, entry.new_string)
+    if (!r.ok) throw new Error(r.reason)
+    updated = content.slice(0, matchIdx) + r.resultText + content.slice(matchIdx + old.length)
+    resultForShift = r.resultText
+  }
+  // 行数差 = 应用后区域行数 − 旧区域行数（分支 0 单行替换：0；零重叠替换即删：new−old；LCS：new−old）
+  const lineShift = splitLines(resultForShift).length - splitLines(old).length
+  return { updated, editStartLine, lineShift, occurrences: entry.replace_all ? occurrences : 1, note }
+}
+
+/**
+ * 单形态 edit 执行体（自 file.mjs 整段迁出——模块拆分写优先纪律：逻辑体不变）——
+ * file.mjs 只留工具壳与转发。
+ */
+export async function runSingleEdit(args, ctx) {
+  const abs = resolveInCwd(ctx, args.path)
+  const raw = await readFile(abs, "utf8")
+  const content = normalizeEOL(raw)
+  const out = computeEditEntry(content, args, { path: args.path, absPath: abs })
+  // 写回按原文行尾（joinWithEol）——normalizeEOL 先行避免 \r\n 污染 split/join
+  await writeFile(abs, joinWithEol(normalizeEOL(out.updated).split("\n"), raw), "utf8")
+  recordWrite(abs, { type: "edit", startLine: out.editStartLine, shift: out.lineShift })
+  const diff = gitDiffOne(ctx.cwd, abs)
+  const baseResult = out.deleted
+    ? `Deleted ${deleteTarget(out)} of ${args.path}${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}`
+    : `Edited ${args.path}: replaced ${out.occurrences} occurrence(s)${out.note ? ` — ${out.note}` : ""}${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}`
+  return await appendWriteContext(abs, out.editStartLine, baseResult)
+}

package/src/tools/edit.md

@@ -1,23 +1,30 @@
-Edit a file by exact string replacement. old_string must match exactly once unless replace_all is set.
+Edit a file as a patch — targeted by content or by line number. Two targeting forms (mutually exclusive — use one): ① line-based: `line: N` replaces that single line, `startLine: N, endLine: M` replaces the inclusive 1-based line range — no old_string needed when you know the line number; give new_string to replace, or OMIT new_string to delete the line/range; ② content-based: old_string is the current content of the region to change (must match exactly once); new_string is the desired result of that region. old_string matching is tolerant: exact match first, then a unique whitespace-only variant, then fuzzy match (unique window with ≥90% of lines identical after trimming, tab→space indent and quote normalization — ASCII single, curly single/double and backtick quotes all unify to straight double quotes). Lines shared by old/new are kept; lines only in new_string take their position relative to the shared lines (LCS order); lines only in old_string are deleted — a replacement never leaves old lines behind (zero overlap → old lines are replaced by new_string, not kept). A unique single-line old_string paired with a single-line new_string replaces that exact line in place (line count unchanged). To add a new line without removing anything use insert_after. replace_all keeps literal replacement of every occurrence — the diff rules do not apply.
 
 **Routing — pick the right edit tool:**
-- Precise line-targeted change → `hashline_edit` (hash-based, immune to whitespace/encoding drift — preferred)
-- One exact-string swap → this tool
-- Add a function/block after a known line → `insert_after`
-- Same change across multiple files or many spots → `apply_patch`
-- Rewrite an entire file → `write`
+- Delete a line/range by number → omit new_string: edit with `line: N` / `startLine: N, endLine: M`
+- Line numbers fresh (just read) → `line`/`startLine`/`endLine` targeting — precise, no content copy needed
+- Line numbers may have drifted / content has whitespace-encoding noise → `hashline_edit` (content-hash addressing — position-independent)
+- Add a line/entry after a known line → insert_after
+- Same change across multiple files → apply_patch
+- Rewrite an entire file → write
 - Rename a symbol project-wide → `lsp` or `grep` first to map every caller
 
-**Batch multiple edits into ONE call via the `edits` array** (preferred over N single edit calls): multiple changes to the SAME file go into one `edits` array (entries are applied serially, each based on the previous one's result); independent changes across MULTIPLE files also go into the same `edits` array — one call, atomic (any failure writes nothing). A batched call is one permission ask, one undo unit, and one turn instead of N.
+**Batch multiple edits into ONE call via the `edits` array** (preferred over N single edit calls): multiple changes to the SAME file go into one `edits` array (entries are applied serially, each based on the previous one's result); independent changes across MULTIPLE files also go into the same `edits` array — one call, atomic (any failure writes nothing). A batched call is one permission ask, one undo unit, and one turn instead of N. A top-level path may accompany the array — entries without their own path inherit it (entry paths override).
 
 Parameters:
-- path (required): File path
-- old_string (required): Exact text to find and replace
-- new_string (required): Replacement text
-- replace_all: Replace all occurrences instead of just one (default false)
-- edits: Array of {path, old_string, new_string, replace_all?} entries — batch form; mutually exclusive with path/old_string/new_string
+- path: File path (single form: required; with the edits array: optional — the default for entries without their own path)
+- old_string: Current content of the region to change (must match exactly once — tolerant matching: exact → whitespace-only variant → fuzzy ≥90% line-equal). Mutually exclusive with line/startLine/endLine — required unless line targeting is used
+- new_string: Desired result of the region — diffed against old_string (shared lines kept; old-only lines deleted — a replacement never leaves old lines behind). Content-based edits: required — an explicit empty string is an error (protects against forgetting it). Line-based edits (line/startLine/endLine): give it to replace the line/range, or OMIT it to delete — an explicit empty string is NOT deletion (error — omit instead)
+- line: 1-based line number — replace that single line with new_string, or OMIT new_string to DELETE it (mutually exclusive with old_string and startLine/endLine)
+- startLine / endLine: 1-based inclusive line range to replace with new_string (given together; mutually exclusive with old_string) — OMIT new_string to DELETE the range
+- replace_all: Replace all occurrences instead of just one (default false; content-based targeting only)
+- edits: Array of {path?, old_string?, new_string?, line?, startLine?, endLine?, replace_all?} entries — batch form; mutually exclusive with top-level old_string/new_string/line/startLine/endLine — a top-level path is allowed and applies to entries without their own path
 
 Notes:
 - Prefer this over write for targeted edits — it's safer and keeps changes targeted
-- If old_string matches zero times: error. If it matches multiple times without replace_all: error — add more surrounding context to make it unique
+- If old_string matches zero times (even fuzzy): error. If it matches multiple times without replace_all: error — add more surrounding context to make it unique
+- Content-based edits: new_string empty is an explicit error (protects against forgetting it).
+- Line-based edits: OMIT new_string to delete the line/range — deleting by number is an explicit, bounded intent.
+- Returns `Edited <path>: replaced N occurrence(s)` (delete-mode: `Deleted line N of <path>` / `Deleted lines N-M of <path>`) + git diff + syntax-check note + context block (L..-L..).
 - Never fabricate the old_string — copy it verbatim from the actual file using read first
+- use the most recent read of the file as the source of old_string / line numbers / hashes — re-read after the file changed

package/src/tools/execute.md

@@ -1,4 +1,4 @@
-Execute JavaScript — either inline `code` or a `scriptFile`. Runs in a real `node` process with top-level `await` and dynamic `import()`. Use inline `code` to compose multiple operations into one call — read, write, glob, grep, log, import, or require() — without shelling out to `bash node -e`.
+Execute JavaScript — either inline `code` or a `scriptFile`. Runs in a real child `node` process — a pure node ESM environment: top-level `await` and dynamic `import()` are available, no globals are injected. File reads/writes/searches belong to the dedicated read/ls/glob/grep/write/edit tools — not to execute. If a script genuinely needs fs/path, `import` the `node:` module inside the code (one explicit import line).
 
 **Route to execute instead of bash:**
 - `node -e "…"` → execute (inline code; top-level await + import() + console all work)
@@ -6,16 +6,16 @@ Execute JavaScript — either inline `code` or a `scriptFile`. Runs in a real `n
 - `node --test <file>` / `node --check <file>` → execute with scriptFile + nodeArgs
 
 Parameters:
-- code: JavaScript to run inline. Top-level `await` and `import('./x.mjs')` are supported. Globals: readFile(path), writeFile(path, content), glob(pattern), grep(pattern, file), log(...args) — plus native require/process/console/fetch/import. Use this OR scriptFile.
-- scriptFile: run a .mjs/.js file with node (self-contained — no prelude; the file imports what it needs). Path relative to workdir — no directory restriction. Use this OR code.
+- code: JavaScript to run inline. Top-level `await` and `import('./x.mjs')` are supported. Pure node ESM — no preloaded helpers; import `node:fs`/`node:path` etc. yourself when needed. File reads/writes go through the dedicated read/ls/glob/grep/write/edit tools. Use this OR scriptFile.
+- scriptFile: run a .mjs/.js file with node (self-contained — the file imports what it needs). Path relative to workdir — no directory restriction. Use this OR code.
 - nodeArgs: (scriptFile) extra node flags before the script, e.g. ["--test"], ["--check"]. Eval-like flags (--eval/--input-type/--inspect) are rejected.
 - workdir: run in this directory (relative to cwd — no directory restriction; default cwd)
 - filter: optional — only return output lines matching this regex (case-insensitive)
-- timeoutMs: Timeout in milliseconds (default 30000, max 600000 — covers slow `node --test` suites and long package scripts)
+- timeoutMs: Timeout in milliseconds (default 30000, max 600000 — covers `node --test` suites and package scripts)
 
 Notes:
-- `console.log(...)` and `log(...)` both print to the result; objects are JSON-stringified by `log`.
-- The prelude's readFile/writeFile/glob/grep helpers resolve paths against the working directory (helper-only guard — `require`/`process`/`import()` are full Node, same boundary as bash).
+- `console.log(...)` prints to the result; objects are JSON-stringified where needed.
 - A non-zero exit / thrown exception returns the stderr (error + stack) as the result.
-- Output capped at ~50KB; use `writeFile` to a file if you need more.
+- Output is capped at ~50KB; when a script overruns it, an explicit `[output truncated]` marker is appended — print large results in chunks, or have the script write them to a file (node:fs) and read that file back with the `read` tool.
 - Use `write`/`edit`/`apply_patch` for source edits. Still use `bash` for package-manager/CLI subprocesses (`npm test`/`npm publish`/`vsce`), servers, and interactive/TTY programs — execute covers in-process JS and `node <script>`/`node --test`/`node --check`, not arbitrary CLI or long-running programs.
+- Irreversibility: it runs with full filesystem access and no automatic undo — script side effects are permanent; checkpoint (git) before risky bulk operations.

package/src/tools/execute.mjs

@@ -10,30 +10,34 @@
  * killable timeout (an in-process infinite loop would freeze the CLI; a child
  * process is killed like bash).
  *
- * The child `import()`-s exec-prelude.mjs first for readFile/writeFile/glob/grep/
- * log/require (helper paths resolve against the working directory — orthopedic
- * guard, not a sandbox). Full Node via require()/process/import() is available —
- * same boundary as bash, no fake sandbox.
+ * The child runs PURE node ESM — no helpers are injected (exec-prelude.mjs
+ * retired 2026-09-03, TOOLS.md §12: preloaded readFile/writeFile/glob/grep/log
+ * helpers made execute look like a file tool, bypassing the dedicated
+ * read/ls/glob/grep/write/edit tools). Scripts that need fs/path import the
+ * node: modules themselves — same boundary as bash, no fake sandbox.
  *
  * Parameters:
  *   code       — JS to run inline (top-level await and import() supported). Use this OR scriptFile.
- *   scriptFile — run a .mjs/.js file with node (self-contained, no prelude). Use this OR code.
+ *   scriptFile — run a .mjs/.js file with node (self-contained, imports what it needs). Use this OR code.
  *   nodeArgs   — (scriptFile) extra node flags before the script (e.g. --test, --check); eval-like flags rejected
  *   workdir    — run in this sub-directory (no directory restriction)
  *   filter     — return only output lines matching this regex (case-insensitive)
- *   timeoutMs  — timeout (default 30s, max 60s)
+ *   timeoutMs  — timeout (default 30s, max 600000ms)
  */
-import { spawn } from "node:child_process"
-import { dirname, resolve } from "node:path"
-import { fileURLToPath, pathToFileURL } from "node:url"
+import { spawn, execFileSync } from "node:child_process"
+import { resolve } from "node:path"
 import { DESC } from "./shared.mjs"
 
 const MAX_SCRIPT = 50_000
 const MAX_OUTPUT = 50_000
 const DEFAULT_TIMEOUT = 30_000
 
-const __dirname = dirname(fileURLToPath(import.meta.url))
-const PRELUDE_URL = pathToFileURL(resolve(__dirname, "exec-prelude.mjs")).href
+/**
+ * 超时错误文本——带重试引导（TOOLS.md §14.1 D14.1.2——"下一跳"）：数字 = 实际生效的
+ * timeoutMs（Math.min(t, 600_000) 或默认 30s）——上限 600000 与 schema/头注/execute.md 一致。
+ */
+const timeoutErrorText = (timeoutMs) =>
+  `Error: script timed out after ${timeoutMs}ms — retry with a larger timeoutMs (up to 600000) for long scripts, or use bash (default 120s) for shell commands`
 
 /** Resolve workdir relative to cwd — no boundary assertion
  *  (§10.1 2026-09-02: workspace confinement removed; the child node process is
@@ -54,15 +58,34 @@ function applyFilter(output, filter) {
   }
 }
 
+/** 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). */
+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 {}
+  }
+}
+
 /** Spawn node with the given args, capture stdout/stderr, enforce timeout/abort.
  *  Resolves { text, ok } — ok=false on non-zero exit / timeout / abort. */
-function runNode(childArgs, baseDir, root, timeoutMs, signal) {
+function runNode(childArgs, baseDir, timeoutMs, signal) {
   return new Promise((resolvePromise) => {
     const child = spawn(process.execPath, childArgs, {
       cwd: baseDir,
-      env: { ...process.env, THINCODER_EXEC_ROOT: root },
       stdio: ["ignore", "pipe", "pipe"],
       windowsHide: true,
+      // POSIX detached → 子进程为组首——killProcessTree 的 -pid 组杀可达孙进程（win 用
+      // taskkill /T 不需 detached）——2026-09-05 advisor 🟡#4
+      detached: process.platform !== "win32",
+      // 双保险（2026-09-05——裸 spawn 无 signal 教训——system.mjs 同款）：abort 时
+      // Node 自动杀直接子进程（第一道）——onAbort 手动 kill 兜底（SIGKILL 防信号陷阱
+      // 脚本——见 kill 注释）——AbortError 在 error 分支让路（close 必随——走 mode 收尾）
+      ...(signal ? { signal } : {}),
     })
 
     let outBuf = "", errBuf = "", truncated = false, settled = false, mode = null
@@ -76,11 +99,12 @@ function runNode(childArgs, baseDir, root, timeoutMs, signal) {
       if (signal) signal.removeEventListener("abort", onAbort)
       resolvePromise({ text, ok })
     }
-    // SIGKILL (not SIGTERM) so a signal-trapping script can't dodge the watchdog.
-    const kill = () => { try { child.kill("SIGKILL") } catch { /* already gone */ } }
+    // Tree kill（SIGKILL/taskkill /T——signal-trapping 脚本躲不开 watchdog；孙进程持管道
+    // 时直接 kill 不达——close 不触发拖到 kick——2026-09-05 advisor 🟡#4 对齐 bash/verify）
+    const kill = () => { killProcessTree(child) }
     // After kill, wait for "close" (child fully reaped) before settling — settling
     // early races the caller deleting the cwd dir while the child still holds it.
-    const armKick = () => { kickTimer = setTimeout(() => settle(mode === "abort" ? "(stopped)" : `Error: script timed out after ${timeoutMs}ms`, false), 3000) }
+    const armKick = () => { kickTimer = setTimeout(() => settle(mode === "abort" ? "(stopped)" : timeoutErrorText(timeoutMs), false), 3000) }
     const onAbort = () => { if (mode) return; mode = "abort"; kill(); armKick() }
 
     timer = setTimeout(() => { if (!mode) { mode = "timeout"; kill(); armKick() } }, timeoutMs)
@@ -97,10 +121,16 @@ function runNode(childArgs, baseDir, root, timeoutMs, signal) {
     }
     child.stdout.on("data", (d) => { outBuf = cap(outBuf, d.toString()) })
     child.stderr.on("data", (d) => { errBuf = cap(errBuf, d.toString()) })
-    child.on("error", (e) => settle(`Error: failed to start node: ${e.message}`, false))
+    child.on("error", (e) => {
+      // signal 双保险（2026-09-05）：abort 时 Node signal option 杀子进程 → 本事件以
+      // AbortError 先触发——让路（close 必随——close 分支 mode==="abort" →
+      // settle("(stopped)")）——不把中止误报为启动失败
+      if (e.name === "AbortError") return
+      settle(`Error: failed to start node: ${e.message}`, false)
+    })
     child.on("close", (code) => {
       if (mode === "abort") return settle("(stopped)", false)
-      if (mode === "timeout") return settle(`Error: script timed out after ${timeoutMs}ms`, false)
+      if (mode === "timeout") return settle(timeoutErrorText(timeoutMs), false)
       const out = outBuf.trimEnd()
       const err = errBuf.trim()
       if (code === 0) {
@@ -132,11 +162,11 @@ export const executeTool = {
     properties: {
       code: {
         type: "string",
-        description: "JavaScript code to execute (top-level await and dynamic import() supported). Use provided globals: readFile/writeFile/glob/grep/log, plus native require/process/console/fetch/import. Use this OR scriptFile.",
+        description: "JavaScript code to execute (top-level await and dynamic import() supported). Pure node ESM — no preloaded globals; import node: modules (fs/path) yourself when needed. File reads/writes go through the dedicated read/ls/glob/grep/write/edit tools. Use this OR scriptFile.",
       },
       scriptFile: {
         type: "string",
-        description: "Run a .mjs/.js file with node (self-contained, no prelude). Path relative to workdir — no directory restriction. Use this OR code. For `node <script>` / `node --test <file>` / `node --check <file>`.",
+        description: "Run a .mjs/.js file with node (self-contained — the file imports what it needs). Path relative to workdir — no directory restriction. Use this OR code. For `node <script>` / `node --test <file>` / `node --check <file>`.",
       },
       nodeArgs: {
         type: "array",
@@ -174,7 +204,7 @@ export const executeTool = {
     if (args.scriptFile) {
       if (args.code?.trim()) return "Error: pass code OR scriptFile, not both"
       // scriptFile mode: run a .mjs/.js file with node [nodeArgs...]. Self-contained —
-      // no prelude (a real node process imports what it needs). No directory restriction.
+      // a real node process imports what it needs. No directory restriction.
       const scriptAbs = resolve(baseDir, args.scriptFile)
       let nodeArgs
       try { nodeArgs = validateNodeArgs(args.nodeArgs) }
@@ -186,12 +216,13 @@ export const executeTool = {
       if (code.length > MAX_SCRIPT) {
         return `Error: script too large (${code.length} > ${MAX_SCRIPT} bytes). Split into smaller scripts or use individual tools.`
       }
-      childArgs = ["--input-type=module", "--eval", `await import(${JSON.stringify(PRELUDE_URL)});\n${code}`]
+      // inline mode: pure node ESM — no prelude, nothing injected (TOOLS.md §12).
+      childArgs = ["--input-type=module", "--eval", code]
     }
 
-    const { text, ok } = await runNode(childArgs, baseDir, ctx.cwd, timeoutMs, ctx.signal)
+    const { text, ok } = await runNode(childArgs, baseDir, timeoutMs, ctx.signal)
     // Only filter successful output — never swallow an error report behind a filter.
     if (!ok) return text
     return args.filter ? applyFilter(text, args.filter) : text
   },
-}
+}