thincoder 0.12.58 → 0.12.59

package/src/provider/core.mjs

@@ -6,7 +6,9 @@
 
 import { providerSpec, resolveEnableThinking } from "../config.mjs"
 import { proxyFetch } from "../proxy.mjs"
-import { escapeMessages } from "../escape.mjs"
+import { escapeMessages, stripLocalMessageFields } from "../escape.mjs"
+import { logEvent, errText, classifyErr, headText } from "../log.mjs"
+import { recordChatTrace } from "../traces/trace-store.mjs"
 import { readSSE } from "./sse.mjs"
 export { readSSE } from "./sse.mjs"
 import {
@@ -71,13 +73,60 @@ export function effectiveFetchTimeoutMs(provider) {
   return Number.isFinite(provider?.fetchTimeoutMs) && provider.fetchTimeoutMs > 0 ? provider.fetchTimeoutMs : 600_000
 }
 
-export async function chat(provider, { messages, tools, onToken, onReasoning, onWait, signal, streamRules, firedPatterns, toolChoice, parallelToolCalls }) {
+export async function chat(provider, opts = {}) {
+  // LOGGING（docs/design/LOGGING.md）：llm:* 事件统一在此落点——所有 chat 调用
+  // （主回合/消化轮/compress/distill/advisor/子代理/auto-think/consult）都经本函数，
+  // 格式分派（anthropic/google/responses）在内部——单点覆盖即 llm:* 全覆盖。
+  // 续写/重试各自为独立 HTTP 请求——续写递归（下方 chatImpl 内）会再包一层（嵌套
+  // llm:start/done 对——每请求一事件）；重试在 requestWithRetry 内部不可见。
+  // §18.6 完整轨迹存档（AGENT-LOOP.md §18.6 N-TR2——权威句 D-TR1）：采集点唯一=
+  // 本函数出口——所有 chat 调用（主回合/消化轮/compress/distill/advisor/子代理/
+  // auto-think/consult）都经本函数；续写/重试在出口已合并——reasoning 全量才完整。
+  const logCtx = opts.logCtx ?? {}
+  const t0 = Date.now()
+  const pname = provider?.name ?? provider?.model ?? "unknown"
+  logEvent("llm:start", { provider: pname, model: provider?.model ?? "", stage: logCtx.stage, turn: logCtx.turn, auto: logCtx.auto === true, child: logCtx.child })
+  try {
+    const result = await chatImpl(provider, opts)
+    logEvent("llm:done", {
+      provider: pname, model: provider?.model ?? "",
+      ms: Date.now() - t0,
+      stage: logCtx.stage, turn: logCtx.turn, auto: logCtx.auto === true, child: logCtx.child,
+      head: headText(result?.content ?? "", 300, { paragraph: true }),
+      len: String(result?.content ?? "").length,
+      finish: result?.finishReason ?? null,
+      tools: Array.isArray(result?.toolCalls) ? result.toolCalls.length : 0,
+    })
+    // §18.6 D-TR1/D-TR5：出口收集——成功路径轨迹（含 content/reasoning 全文/toolCalls）
+    recordChatTrace(provider, opts, result, null)
+    return result
+  } catch (e) {
+    logEvent("llm:error", {
+      provider: pname, model: provider?.model ?? "",
+      ms: Date.now() - t0,
+      stage: logCtx.stage, turn: logCtx.turn, auto: logCtx.auto === true, child: logCtx.child,
+      err: errText(e, 200),
+      kind: classifyErr(e, opts.signal),
+    })
+    // §18.6 D-TR5：失败路径也落盘——error（errText 截断 + 类别）+ finishReason:null
+    recordChatTrace(provider, opts, null, e)
+    throw e
+  }
+}
+
+/** chat 本体（LOG(LLM) 事件包装之外——见上方 chat 包装器）。 */
+async function chatImpl(provider, { messages, tools, onToken, onReasoning, onWait, signal, streamRules, firedPatterns, toolChoice, parallelToolCalls, logCtx }) {
   // Sanitize BEFORE format dispatch — image poisoning bricks anthropic/google sessions
   // the same way it bricks OpenAI-format ones (all raster-only).
   // providerSpec: spec with the provider-level context override (PROVIDER.md §15) — the
   // window/clamping logic below reads the overridden value where it matters.
   const spec = providerSpec(provider)
   messages = stripImagesForTextModel(messages, spec)
+  // SESSION.md §9 T-S3: local-only message fields (ts/transient) never reach the wire.
+  // Stripped BEFORE format dispatch — anthropic/responses transports pass whole message
+  // objects through verbatim (only the OpenAI path ran escapeMessages). Copy-on-write:
+  // history keeps the fields, the request never sees them.
+  messages = stripLocalMessageFields(messages)
   const _debugBeforeLen = process.env.THIN_DEBUG_BODY ? JSON.stringify(messages).length : 0
 
   // Format dispatch: delegate to non-OpenAI transports
@@ -211,6 +260,11 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, on
         onReasoning,
         onWait,
         signal,
+        // §18.6：续写是同一逻辑调用的子请求——logCtx 原样透传（元数据与门控
+        // traces.enabled 对续写调用同样生效，不在出口静默越过开关）
+        // fix round1（D-TR1）：续写子请求标记 isContinuation:true（T-TR14——true =
+        // 该调用是续写链的一环；外层新调用 false）——分析"纠结"时区分续写/重试链。
+        logCtx: { ...logCtx, isContinuation: true },
       })
     } catch (error) {
       // §14.3 失败可见性：续写失败注入 _warnings（agent 机读线可见）不整轮飞出；AbortError 用户中断透传

package/src/tools/apply_patch.md

@@ -3,9 +3,11 @@ Apply a unified diff to one or more files, atomically: if any hunk fails to appl
 **Use it for whole-file and multi-file changes:** creating MULTIPLE new files at once (`--- /dev/null` header per file), whole-file replacement, and cross-file refactors — one unified-diff call covers the whole change. A batched call is one permission ask and one turn instead of N separate calls.
 
 Parameters:
-- patch (required): Unified diff text. One `--- a/path` / `+++ b/path` header pair per file, then `@@ -old,count +new,count @@` hunks. Use `--- /dev/null` to create a new file.
+- patch (required): Unified diff text. One `--- a/path` / `+++ b/path` header pair per file, then `@@ -old,count +new,count @@` hunks. Use `--- /dev/null` to create a new file. The `+++ b/path` pair may be omitted for existing files — a lone `--- a/path` (or `--- b/path`) header followed directly by hunks applies to that path (new files still need `--- /dev/null` + `+++ b/path`).
 
 Notes:
+- Hunk header "@@" without coordinates is accepted. Coordinate-less hunks are located by their anchor lines: context lines plus the removed (-) lines, matched as a contiguous sequence — a unique match applies. The anchor-free forms require context: a hunk with no removed (-) lines (pure additions) needs at least 2 context lines for a unique match; a zero/one-context hunk with at least one removed (-) line is located by its anchor sequence (context + removed lines, in order) and applies on a unique match.
+- Returns the applied-file summary (`Applied patch to N file(s)` plus per-file change lines and syntax-check notes for changed .mjs files)
 - Use this for multi-file changes (e.g. rename an interface + update all callers) — one call, all-or-nothing
 - Hunks are located by their context/removed lines, not line numbers — but the context must match the file EXACTLY. Read the files first and generate the patch from actual content
 - If a hunk's context matches multiple locations it is rejected — add more surrounding context lines

package/src/tools/bash.md

@@ -5,7 +5,7 @@ Execute a shell command and return stdout+stderr. Use for running commands, buil
 - `ls` / `dir` → `ls`
 - `find` / glob search → `glob`
 - `grep` / `rg` → `grep`
-- `echo >` / `sed` / `printf >` / `cat << EOF` → `write` / `edit` / `hashline_edit` / `apply_patch` (enforced: redirection is blocked)
+- `echo >` / `sed` / `printf >` / `cat << EOF` → `write` / `edit` / `hashline_edit` / `apply_patch` (preferred: write tools handle encoding/EOL correctly)
 - `git diff` / `git status` / `git log` → `git` tool
 
 Parameters:

package/src/tools/delete.md

@@ -10,3 +10,4 @@ Notes:
 - Untracked or non-git files are deleted immediately
 - Tracked files require force=true (user must confirm separately)
 - Directories must be removed with bash (rm -rf)
+- Returns `Deleted <path>` (or `Error: ...` on failure/tracked refusal).

package/src/tools/edit-batch.mjs

@@ -1,17 +1,22 @@
 /**
  * edit-batch.mjs — edit 工具的数组形态（edits: [...]）：一次多文件原子替换。
- * （2026-08-31 工具顺手度 §9 ②；2026-09-01 缺陷修复"同文件多条串行累积"。）
- * 从 file.mjs 拆出（500 行硬限，先例 git-ext.mjs）——纯移动，零行为变化。
+ * （2026-08-31 工具顺手度 §9 ②；2026-09-01 缺陷修复"同文件多条串行累积"；
+ * 2026-09-04 TOOLS.md §15 D15.1——条目级判定+应用迁至 edit-diff.mjs——批量调共用。）
  *
  * 语义：同一 path 的多条编辑按序**串行累积应用**——第 n 条基于前 n-1 条已应用后的
  * 累积内容做匹配与替换；跨 path 条目互不影响（并行原子语义）；任一条失败 →
- * 全不写（原子性保留）。
+ * 全不写（原子性保留）。每条目独立按判定序（§15.2 分支 0 单行替换 / 零重叠→插入 / LCS /
+ * 空 new 显式报错）。顶层 path（args.path）为无自带 path 条目的默认（2026-09-05 用户裁定
+ * ——条目自带 path 优先——见 TOOLS.md D15.3#9 修订注）。
  */
 import { readFile, writeFile } from "node:fs/promises"
 import { resolveInCwd, normalizeEOL, joinWithEol, gitDiffOne, autoSyntaxCheck } from "./shared.mjs"
 // file.mjs ↔ edit-batch.mjs 循环引用：两侧导入的都是函数声明（提升初始化），
 // 仅在调用期使用——ESM 循环下安全（无模块求值期取值）。
 import { recordWrite, appendWriteContext } from "./file.mjs"
+// TOOLS.md §15 D15.1：批量条目判定+应用共用 edit-diff（§15.2 分支 0 单行替换 + 行级 LCS——零重叠→插入）；
+// D15.3#9：edits 互斥错误文本随前置校验分支迁出至 edit-diff.mjs。
+import { assertEditArgsExclusive, validateEditEntry, computeEditEntry } from "./edit-diff.mjs"
 
 /**
  * Apply the `edits` array form: multi-file atomic replacement. Throws on any
@@ -21,9 +26,7 @@ export async function applyEditBatch(args, ctx) {
   if (!Array.isArray(args.edits) || args.edits.length === 0) {
     throw new Error("edits must be a non-empty array of {path, old_string, new_string}")
   }
-  if (args.path || args.old_string !== undefined || args.new_string !== undefined) {
-    throw new Error("edits array is mutually exclusive with path/old_string/new_string")
-  }
+  assertEditArgsExclusive(args)
   // 原子：先全量检查（所有文件的替换都可执行）——任一失败全不写。
   // 2026-09-01 缺陷修复（TOOLS.md §9 ②"同文件多条规则"）：同一 path 的多条编辑
   // 按序**串行累积应用**——第 n 条基于前 n-1 条已应用后的累积内容做匹配与替换
@@ -31,55 +34,40 @@ export async function applyEditBatch(args, ctx) {
   // 除最后一条外全部静默丢失）；跨 path 条目互不影响（并行原子语义不变）。
   const groups = new Map() // abs → 每文件一条流水线
   for (const e of args.edits) {
-    if (!e.path) throw new Error("each edit must have a path")
-    if (!e.old_string) throw new Error(`edit for ${e.path}: old_string must not be empty`)
-    if (typeof e.new_string !== "string") {
-      throw new Error(
-        `edit for ${e.path}: new_string must be a string` +
-        `${e.new_string === undefined ? " (missing)" : ` (got ${typeof e.new_string})`}`,
-      )
-    }
-    const abs = resolveInCwd(ctx, e.path)
+    // 2026-09-05 用户裁定：顶层 path + edits 并存合法化——`e.path || args.path`（条目优先；
+    // 缺省入口仅在此兜底）；两者皆无 → 原错误文本（措辞补顶层选项）。
+    const p = e.path || args.path
+    if (!p) throw new Error("each edit must have a path — give each entry its own path or pass a top-level path")
+    // 前置校验（空 old / 非字符串 new——文本同 edit-diff 批量形态；读盘前校验）
+    validateEditEntry(e, { label: `edit for ${p}: `, rich: false })
+    const abs = resolveInCwd(ctx, p)
     let g = groups.get(abs)
     if (!g) {
       const raw = await readFile(abs, "utf8")
-      g = { abs, path: e.path, raw, content: normalizeEOL(raw), edits: [] }
+      g = { abs, path: p, raw, content: normalizeEOL(raw), edits: [] }
       groups.set(abs, g)
     }
     g.edits.push(e)
   }
-  const prepared = [] // 顺序 = args.edits 顺序（回显按条）；recordWrite 每组一条合并快照
+  const prepared = [] // 每条目一条回显；同文件内按 args 序，跨文件按首次出现分组序（应用/回显语义均正确）
   for (const g of groups.values()) {
     g.netShift = 0 // 组内行数差累积（合并快照的 shift = 全组净漂移）
     for (const e of g.edits) {
-      const content = g.content
-      const occurrences = content.split(e.old_string).length - 1
-      if (occurrences === 0) {
-        throw new Error(
-          `edit aborted (atomic — no files written): old_string not found in ${g.path}\n` +
-          `  searched: "${e.old_string.slice(0, 100).split("\n")[0]}${e.old_string.length > 100 ? "…" : ""}"`
-        )
-      }
-      if (occurrences > 1 && !e.replace_all) {
-        throw new Error(
-          `edit aborted (atomic — no files written): old_string matches ${occurrences} times in ${g.path}; ` +
-          `provide more context or set replace_all`
-        )
-      }
-      const matchIdx = content.indexOf(e.old_string)
-      const editStartLine = matchIdx >= 0 ? content.slice(0, matchIdx).split("\n").length : 1
-      const lineShift = e.new_string.split("\n").length - e.old_string.split("\n").length
-      const updated = e.replace_all
-        ? content.split(e.old_string).join(e.new_string)
-        : content.replace(e.old_string, () => e.new_string)
+      // 条目级判定+应用（edit-diff——§15.2 分支 0 单行替换 + 判定序 1/2/3 + 空 new 显式报错 + >1000 行报错）
+      const out = computeEditEntry(g.content, e, {
+        path: g.path,
+        absPath: g.abs,
+        abortPrefix: "edit aborted (atomic — no files written): ",
+      })
       prepared.push({
         g,
-        editStartLine, // 基于累积内容计算——已天然计入前面条目的行偏移，不再累加
-        lineShift,
-        occurrences: e.replace_all ? occurrences : 1,
+        editStartLine: out.editStartLine, // 基于累积内容计算——已天然计入前面条目的行偏移，不再累加
+        lineShift: out.lineShift,
+        occurrences: out.occurrences,
+        note: out.note ?? null, // P15.11——空白差异自动落点标记（成功消息追加）
       })
-      g.content = updated // 串行累积：下一条基于本条应用后的内容
-      g.netShift += lineShift
+      g.content = out.updated // 串行累积：下一条基于本条应用后的内容
+      g.netShift += out.lineShift
     }
   }
   // 全部检查通过——每文件一次写盘（同文件多条：写入串行累积后的最终内容）；
@@ -97,7 +85,7 @@ export async function applyEditBatch(args, ctx) {
     // #4（2026-09-01 交付评审尾巴）：与单文件路径对齐——每条结果附 git diff +
     // autoSyntaxCheck（同文件多条会重复 diff/检查，换取格式一致、实现零分支）
     const diff = gitDiffOne(ctx.cwd, p.g.abs)
-    const base = `Edited ${p.g.path}: replaced ${p.occurrences} occurrence(s)${diff ? "\n" + diff : ""}${await autoSyntaxCheck(p.g.abs)}`
+    const base = `Edited ${p.g.path}: replaced ${p.occurrences} occurrence(s)${p.note ? ` — ${p.note}` : ""}${diff ? "\n" + diff : ""}${await autoSyntaxCheck(p.g.abs)}`
     results.push(await appendWriteContext(p.g.abs, p.editStartLine, base))
   }
   return results.join("\n")

package/src/tools/edit-diff.mjs

@@ -0,0 +1,265 @@
+/**
+ * edit-diff.mjs — edit 工具的行级 diff 内核（TOOLS.md §15 D15.1，2026-09-04）。
+ *
+ * edit 新语义（用户裁定——breaking——不承诺旧行为兼容）：old_string = 变化区**当前内容**
+ * （必须精确存在、单次匹配——不变）；new_string = 该区的**期望结果**。判定序：
+ *   0. 分支 0（TOOLS.md §15.2——单行精确替换）：old 单行 && new 单行 && old 全文唯一 &&
+ *      new 非空 → **就地替换该行**（行数不变——EOL 由调用方 joinWithEol 恢复）；
+ *   1. 零重叠（old 每一行都不出现在 new 行集中）→ 按**插入**——new 整体插入在 old
+ *      最后一行之后（旧内容保留——数据零丢失）；
+ *   2. 有公共行（≥1）→ 行级 LCS——公共行保留、差异行增删；
+ *   3. new 与 old 行级完全一致 → 原样替换（no-op 语义——仍报成功）。
+ * 空 new_string（纯删除意图）→ 显式报错（不静默——先于分支 0——单行替换永不成删除）；
+ * 分支 0 只在 computeEditEntry 条目判定层（壳/桥/批量自动继承）——applyPatchLines
+ * （纯 diff 层）语义不动。old/new 行数各上限 1000（超限报错）。
+ *
+ * 行尾权威 = EDIT-TOOL-EOL-DESIGN.md：判定/应用在 normalizeEOL 后的 LF 域计算，
+ * 写回由调用方 joinWithEol(原文) 恢复原行尾。
+ * 模块拆分（file.mjs ≤500 硬限）：file.mjs 只留工具壳与转发——单形态执行体与前置校验
+ * 分支整段迁出至本模块（模块拆分写优先纪律：先迁后删、逻辑体不变、wiring 导入）。
+ */
+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"
+
+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 EDIT_ARGS_MUTEX = "edits array is mutually exclusive with top-level old_string/new_string — a top-level path is allowed (default for entries without their own path); provide each change's old_string/new_string inside its edits entry"
+
+/** 行切分（尾随换行终止最后一行——非额外空行）："a\nb\n" → ["a","b"]。 */
+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 中相对公共行的位置插入。结果在 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（F15.2）：零重叠 → 插入——new 整体插在 old 最后一行之后（旧内容保留）
+  const newSet = new Set(newLines)
+  const merged = oldLines.some((l) => newSet.has(l))
+    ? lcsMerge(oldLines, newLines) // 判定 2/3——公共行保留、差异行增删
+    : [...oldLines, ...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()
+}
+
+/**
+ * D15.3#9 修订（2026-09-05 用户裁定——顶层 path + edits 并存合法化：顶层 path = 无自带
+ * path 条目的默认——模型直觉形态「顶层 path + 数组条目」不再拒绝；条目自带 path 优先）。
+ * 互斥收窄为只对顶层 old_string/new_string——edits 下它们无批语义可解释——顶层 path 不再触发。
+ */
+export function assertEditArgsExclusive(args) {
+  if (args.old_string !== undefined || args.new_string !== undefined) {
+    throw new Error(EDIT_ARGS_MUTEX)
+  }
+}
+
+/**
+ * 前置校验（空 old / 非字符串 new）——error 文本按调用形态（单形态 rich / 批量 label）。
+ * opts: { label = ""（批量前缀 "edit for <path>: "）, rich = true（单形态完整文本） }
+ */
+export function validateEditEntry(entry, opts = {}) {
+  const label = opts.label ?? ""
+  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 (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 形态判定（TOOLS.md §15.2 D15.9.1）：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
+  )
+}
+
+/**
+ * 条目级判定+应用（单形态与批量共用——D15.1"批量条目判定+应用调用 edit-diff"）：
+ * 匹配校验（精确存在——非 replace_all 单次）→ 按判定序应用（分支 0 单行替换 / 零重叠插入 /
+ * LCS 替换 / replace_all 字面）→
+ * 元数据（受影响区首行/行数差/次数——recordWrite 与结果回显用）。
+ * 返回 { updated, editStartLine, lineShift, occurrences }；失败抛错（含路径/引导）。
+ * 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 })
+  // 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 }
+  }
+  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（§15.2 D15.9.2）
+    updated = content.split(old).join(entry.new_string)
+    resultForShift = entry.new_string
+  } else if (isSingleLineReplace(entry)) {
+    // 分支 0（§15.2 D15.9.1——单行精确替换）：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 行数；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 = `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,25 @@
-Edit a file by exact string replacement. old_string must match exactly once unless replace_all is set.
+Edit a file as a patch. old_string is the current content of the region to change (must match exactly once); new_string is the desired result of that region. Lines shared by both are kept; lines only in new_string take their position relative to the shared lines (LCS order) — when no line overlaps, new_string is inserted after old_string (old content stays) — except a unique single-line old_string paired with a single-line new_string: that exact line is replaced in place (line count unchanged); for a multi-line replacement, include a shared context line — for adding a new line use insert_after: a unique single-line old/new pair replaces the line in place; multi-line zero-overlap pairs still insert per the diff rules above. replace_all keeps literal replacement of every occurrence — the insert rule does 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`
+- Add a line/entry after a known line → insert_after — includes checklist items and doc lines.
 - Same change across multiple files or many spots → `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
+- path: File path (single form: required; with the edits array: optional — the default for entries without their own path)
+- old_string (required): Current content of the region to change (must match exactly once)
+- new_string (required): Desired result of the region — diffed against old_string (shared lines kept; zero overlap → new_string inserted after old_string — a unique single-line old/new pair replaces the line in place)
 - 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
+- edits: Array of {path?, old_string, new_string, replace_all?} entries — batch form; mutually exclusive with top-level old_string/new_string — 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
+- new_string empty (deletion) is an explicit error — keep the context lines you want to preserve in both old_string and new_string
+- Returns `Edited <path>: replaced N occurrence(s)` + 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.