thincoder 0.12.58 → 0.12.59

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 { 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
@@ -56,11 +60,10 @@ function applyFilter(output, filter) {
 
 /** 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,
     })
@@ -80,7 +83,7 @@ function runNode(childArgs, baseDir, root, timeoutMs, signal) {
     const kill = () => { try { child.kill("SIGKILL") } catch { /* already gone */ } }
     // 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)
@@ -100,7 +103,7 @@ function runNode(childArgs, baseDir, root, timeoutMs, signal) {
     child.on("error", (e) => 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 +135,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 +177,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 +189,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
   },
-}
+}

package/src/tools/file.mjs

@@ -10,10 +10,10 @@ import {
   detectFileEol,
   joinWithEol,
   majorityEol,
-  findCandidates,
   FFFD_WARNING,
 } from "./shared.mjs";
 import { applyEditBatch } from "./edit-batch.mjs";
+import { runSingleEdit } from "./edit-diff.mjs";
 import { specForModel } from "../config.mjs";
 import { createHash } from "node:crypto";
 import { mkdir, readFile, stat, writeFile, unlink } from "node:fs/promises";
@@ -73,6 +73,7 @@ export const readTool = {
     type: "object",
     properties: {
       path: { type: "string", description: "File path (relative to cwd or absolute)" },
+      filePath: { type: "string", description: "Alias for path (supported for API compatibility)" },
       offset: { type: "number", description: "1-based line number to start from" },
       limit: { type: "number", description: `Max lines to return (default ${MAX_READ_LINES})` },
       allowExternal: { type: "boolean", description: "No-op retained for API compatibility — path resolution no longer asserts a working-directory boundary (all paths resolve relative to cwd)." },
@@ -82,7 +83,8 @@ export const readTool = {
   },
   readonly: true,
   async execute(args, ctx) {
-    const abs = args.allowExternal ? resolveExternal(ctx, args.path) : resolveInCwd(ctx, args.path)
+    const p = args.path ?? args.filePath
+    const abs = args.allowExternal ? resolveExternal(ctx, p) : resolveInCwd(ctx, p)
     // Large file guard: check size first, reject reading entire file if >10MB (offset/limit only affect the returned slice, not buffering)
     const st = await stat(abs).catch(() => null)
     if (st && st.size > MAX_FILE_READ_BYTES) throw new Error(`File too large (${Math.round(st.size / 1_000_000)}MB > 10MB limit). Use bash with head/tail or grep for targeted extraction.`)
@@ -214,13 +216,13 @@ export const editTool = {
   parameters: {
     type: "object",
     properties: {
-      path: { type: "string", description: "File path" },
+      path: { type: "string", description: "File path — single form: required; with the edits array: optional top-level default for entries without their own path" },
       old_string: { type: "string", description: "Exact text to replace" },
       new_string: { type: "string", description: "Replacement text" },
       replace_all: { type: "boolean", description: "Replace all occurrences (default false)" },
       edits: {
         type: "array",
-        description: "Batch form — multiple edits in ONE call, atomic (any failure writes nothing; same-file entries apply serially, each based on the previous result). Use it for multiple changes to the same file AND for independent changes across multiple files — prefer one batched call over N single edits. Mutually exclusive with path/old_string/new_string.",
+        description: "Batch form — multiple edits in ONE call, atomic (any failure writes nothing; same-file entries apply serially, each based on the previous result). Use it for multiple changes to the same file AND for independent changes across multiple files — prefer one batched call over N single edits. A top-level path is allowed — it defaults entries without their own path (entry paths win). Mutually exclusive with top-level old_string/new_string — provide each change's old/new inside its edits entry.",
         items: {
           type: "object",
           properties: {
@@ -229,7 +231,7 @@ export const editTool = {
             new_string: { type: "string" },
             replace_all: { type: "boolean" },
           },
-          required: ["path", "old_string", "new_string"],
+          required: ["old_string", "new_string"],
         },
       },
     },
@@ -237,7 +239,13 @@ export const editTool = {
   },
   readonly: false,
   touchedPaths(args) {
-    if (args.edits) return args.edits.map((e) => e.path).filter(Boolean)
+    // 2026-09-05 用户裁定：顶层 path = 批默认——仅当有条目缺 path 时计入（条目全带 path
+    // 时顶层 path 不实际使用——不虚报进 _touchedFiles）
+    if (args.edits) {
+      const out = args.edits.map((e) => e.path).filter(Boolean)
+      if (args.path && args.edits.some((e) => !e.path)) out.push(args.path)
+      return out
+    }
     return args.path ? [args.path] : []
   },
   async execute(args, ctx) {
@@ -245,67 +253,9 @@ export const editTool = {
     // （应用逻辑在 edit-batch.mjs——2026-09-01 拆出，500 行硬限，先例 git-ext.mjs）
     if (args.edits) return applyEditBatch(args, ctx)
 
-    // 单文件（现状路径）
-    const abs = resolveInCwd(ctx, args.path)
-    if (!args.old_string) {
-      throw new Error("old_string must not be empty (empty string matches everywhere and would corrupt the file)")
-    }
-    // #5（2026-09-01 交付评审尾巴）：new_string 非字符串（含 undefined）在写盘前拒绝——
-    // 原缺陷：replace 回调返回 undefined 被字符串化成 "undefined" 写入盘，随后
-    // args.new_string.split 才 TypeError——文件已损坏 + 错误信息不知所云。
-    if (typeof args.new_string !== "string") {
-      throw new Error(
-        `new_string must be a string${args.new_string === undefined ? " (missing)" : ` (got ${typeof args.new_string})`} — nothing written`,
-      )
-    }
-    const raw = await readFile(abs, "utf8")
-    const content = normalizeEOL(raw)
-    const occurrences = content.split(args.old_string).length - 1
-    if (occurrences === 0) {
-      // Give clues to help the model locate: first-line preview + common causes
-      const preview = args.old_string.slice(0, 100).split("\n")[0]
-      // Similarity candidates (LCS, line-level, top 3, score ≥ 0.5) — turns the
-      // "not found" black box into a pointer at the most likely intended line.
-      // Multi-line old_string: only its first line is scored (marked accordingly).
-      const cands = findCandidates(content.split("\n"), args.old_string)
-      let candText = ""
-      if (cands.length > 0) {
-        const header = args.old_string.includes("\n")
-          ? `  similar lines (old_string line 1: "${args.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(
-        `old_string not found in ${args.path}\n` +
-        `  searched: "${preview}${args.old_string.length > 100 ? "…" : ""}"\n` +
-        (lastWriteOf(abs)?.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`
-          : isDirty(abs)
-            ? `  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 && !args.replace_all) {
-      throw new Error(`old_string matches ${occurrences} times in ${args.path}; provide more context or set replace_all`)
-    }
-    const updated = args.replace_all
-      ? content.split(args.old_string).join(args.new_string)
-      // Functional replacement: avoid $-substitution patterns in new_string (match string / backreference) being expanded
-      : content.replace(args.old_string, () => args.new_string)
-    // Write back in the file's ORIGINAL EOL style (first-newline rule) — a CRLF
-    // file must not come back as LF (that rewrites every line in the diff).
-    // normalizeEOL first: new_string may carry \r\n (e.g. pasted from a raw CRLF
-    // read); without normalizing, split leaves stray \r and CRLF join makes \r\r\n.
-    await writeFile(abs, joinWithEol(normalizeEOL(updated).split("\n"), raw), "utf8")
-    // 2026-08-31 工具顺手度：记录受影响区（替换首行 + 行数差）——insert_after 精确判定
-    const matchIdx = content.indexOf(args.old_string)
-    const editStartLine = matchIdx >= 0 ? content.slice(0, matchIdx).split("\n").length : 1
-    const lineShift = args.new_string.split("\n").length - args.old_string.split("\n").length
-    recordWrite(abs, { type: "edit", startLine: editStartLine, shift: lineShift })
-    const diff = gitDiffOne(ctx.cwd, abs)
-    const baseResult = `Edited ${args.path}: replaced ${args.replace_all ? occurrences : 1} occurrence(s)${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}`
-    return await appendWriteContext(abs, editStartLine, baseResult)
+    // 单文件（现状路径）——执行体整段迁出至 edit-diff.mjs（TOOLS.md §15 D15.1——
+    // 行级 LCS 判定：零重叠→插入 / 一般 diff→LCS / 空 new→显式报错）
+    return runSingleEdit(args, ctx)
   },
 }
 
@@ -453,7 +403,7 @@ export const hashlineEditTool = {
       const hashDump = fileHashes.slice(0, maxShow).map((h, i) => `${h}  L${i + 1}: ${lines[i].slice(0, 80)}`).join("\n")
       const preview = target.join(" ")
       throw new Error(
-        `Hash sequence not found in ${args.path}: ${preview}\n` +
+        `Hash sequence not found in ${args.path}: ${preview} — for fresh hashes, re-read the file with hashes=true\n` +
         `The file may have been modified since you last read it. Current hashes (first ${maxShow} lines):\n${hashDump}` +
         (corrupted ? `\n${FFFD_WARNING}` : "")
       )

package/src/tools/file_ops.md

@@ -13,4 +13,5 @@ Parameters:
 Notes:
 - Paths resolve relative to cwd — no directory restriction (same boundary as bash; the approval gate is the guard).
 - `dest` is overwritten if it already exists. `copy` is recursive for directories.
-- To create a directory, use `write` (creates parent dirs) or `bash mkdir`.
+- To create a directory, use `write` (creates parent dirs) or `bash mkdir`.
+- Returns `Moved|Copied|Renamed <source> -> <dest>` or `Error: ...` (same-path and missing-path errors).

package/src/tools/get_current_time.md

@@ -3,4 +3,6 @@ Get the current date, time, weekday, and timezone.
 **Route to get_current_time instead of bash:**
 - `date` / `time` → get_current_time
 
-Use it whenever a task depends on the current time or date (deadlines, freshness, timestamps) rather than shelling out.
+Use it whenever a task depends on the current time or date (deadlines, freshness, timestamps) rather than shelling out.
+
+Returns `Date` / `Timezone` / `Weekday` / `Local` lines (UTC + local timezone).

package/src/tools/hashline_edit.md

@@ -10,3 +10,5 @@ Notes:
 - Hashes are position-independent: they identify lines by content, not by line number (which changes after edits)
 - If the hash sequence isn't found, the error will include the current file's hashes so you can retry with corrected values
 - Prefer this over edit when: 1) the file may have mixed whitespace/encoding, 2) you want to edit a block of lines with a single call
+- Replacement text replaces the lines identified by the hashes — content not present in new_content is deleted. For a new line after a known line, use insert_after. For a single simple string swap, use edit.
+- 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/index.mjs

@@ -2,6 +2,7 @@
 export { toOpenAISchema } from "./shared.mjs";
 
 import { readTool, writeTool, editTool, insertAfterTool, readImageTool, hashlineEditTool } from "./file.mjs";
+import { readPdfTool } from "./pdf.mjs";
 import { applyPatchTool, deleteTool } from "./patch.mjs";
 import { bashTool, globTool, grepTool, lsTool } from "./system.mjs";
 import { websearchTool, fetchTool } from "./web.mjs";
@@ -15,7 +16,7 @@ import { treeTool } from "./tree.mjs";
 
 export const builtinTools = [
   readTool, writeTool, editTool, insertAfterTool, hashlineEditTool, applyPatchTool,
-  readImageTool, bashTool, globTool, grepTool,
+  readImageTool, readPdfTool, bashTool, globTool, grepTool,
   websearchTool, lsTool, fetchTool, deleteTool,
   gitTool, questionTool,
   checklistTool, lintTool, lspTool, executeTool,
@@ -25,7 +26,7 @@ export const builtinTools = [
 
 export {
   readTool, writeTool, editTool, insertAfterTool, hashlineEditTool, applyPatchTool,
-  readImageTool, bashTool, globTool, grepTool,
+  readImageTool, readPdfTool, bashTool, globTool, grepTool,
   websearchTool, lsTool, fetchTool, deleteTool,
   gitTool, questionTool,
   checklistTool, lintTool, lspTool, executeTool,

package/src/tools/insert_after.md

@@ -8,7 +8,8 @@ Parameters:
 
 Notes:
 - Either after_line or after_regex is required; if both are given, after_line wins.
-- Use this instead of `edit` when you're adding a new function, import, or block — no need to fabricate surrounding context for exact matching.
+- Use this instead of edit when you're adding a new line — a checklist item, a doc heading, a line of prose, a function, an import, or a block — no need to fabricate surrounding context for exact matching.
 - The inserted content becomes its own line; it's equivalent to `lines.splice(targetLine, 0, content)`.
 - Returns a diff of the change.
 - **Read-before-insert guard**: if the file was modified by any write tool (write/edit/insert_after/hashline_edit/apply_patch/delete) since your last `read`, this tool REFUSES with an error — line numbers may be stale. Read the file again, then retry. This prevents after_line from silently landing at a drifted position.
+- 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/lint.md

@@ -3,6 +3,8 @@ Without 'full', runs a fast node --check (JS/TS syntax only, catches parse error
 With 'full', runs the language-aware cascade: tsc –noEmit (TS); ruff (Python); cargo check (Rust); go vet (Go). JS/JSX files fall back to node --check; TS uses tsc --noEmit (requires tsconfig.json).
 Use the fast default after every write/edit; use 'full' before declaring a task complete.
 
+Returns the check result: `Syntax OK: <path>` / `Syntax error in <path>: <message>` (or the language checker's output — `✓ no issues` or the failure text).
+
 Parameters:
 - path: File to check (default: most recently modified file)
 - full: Run the full language-aware cascade instead of just node --check (default false)

package/src/tools/lsp.md

@@ -1,7 +1,10 @@
-LSP code intelligence: go to definition, find references, hover info, document symbols, diagnostics. Use this to understand code structure without grep-guessing function locations or type shapes.
+LSP code intelligence: go to definition, find references, hover info, document symbols, diagnostics. Use this to understand code structure without grep-guessing function locations or type shapes. Find files with glob / repo_outline — use lsp for definition / references / diagnostics
 
 Parameters:
 - subcommand (required): LSP operation — "definition" | "references" | "hover" | "symbols" | "diagnostics"
 - uri (required): Target file path (relative to project root)
 - line: 1-based line number (for definition/references/hover)
 - character: 1-based character offset (for definition/references/hover)
+
+Notes:
+- Returns the requested LSP result: definition location, references, hover info, document symbols, or diagnostics — or an error message.

package/src/tools/patch.mjs

@@ -15,8 +15,23 @@ import { relative, dirname } from "node:path";
 /**
  * Parse a unified diff: returns [{ path, isNew, hunks: [{ ops: [{type:" "|"-"|"+", text}] }] }]
  * Consume hunk lines by the line counts in the @@ header — LLMs often strip context blank lines to pure empty lines,
- * so we use counts rather than first characters to determine hunk boundaries
+ * so we use counts rather than first characters to determine hunk boundaries.
+ * D15.6: a bare "@@" header (no coordinates) is accepted — the hunk body runs until the next hunk/file header
+ * ("@@" / "--- " / "+++ " / "diff " / "index "), purely located by its ops.
  */
+/**
+ * P15.10（2026-09-05 用户裁定——「符合模型直觉」）：文件头判定——
+ * 完整头（`--- x` 后随 `+++ `）任意老路径形态均认（git 规范）；
+ * 容缺头（`+++ b/<path>` 配对行省略——模型单文件补丁自然形态）仅认 a//b/ 前缀——
+ * newPath 推导 = oldPath；`/dev/null` 容缺仍拒（新文件名从 --- 侧不可推导——parsePatch 内特报）；
+ * 其他 `--- x` = 普通删行内容（行首标记 - + 内容 `-- x`）——不是文件头——hunk 体不得误断。
+ */
+function isFileHeader(line, nextLine) {
+  if (!line.startsWith("--- ")) return false
+  if (nextLine?.startsWith("+++ ")) return true
+  return /^[ab]\//.test(line.slice(4).trim())
+}
+
 function parsePatch(patch) {
   // Patch text often comes from CRLF terminals/model output; trailing \r mixed into hunk content breaks context matching, strip uniformly
   const lines = patch.replace(/\r(?=\n|$)/g, "").split("\n")
@@ -29,18 +44,69 @@ function parsePatch(patch) {
     if (line.startsWith("--- ")) {
       const oldPath = line.slice(4).trim()
       const plus = lines[i + 1]
-      if (!plus?.startsWith("+++ ")) throw new Error(`Malformed patch: expected "+++" line after "${line}"`)
-      const newPath = plus.slice(4).trim()
-      if (newPath === "/dev/null") throw new Error("Deleting files via patch is not supported — use the delete tool")
-      cur = { path: stripPrefix(newPath), isNew: oldPath === "/dev/null", hunks: [] }
-      files.push(cur)
-      i += 2
-      continue
+      if (plus?.startsWith("+++ ")) {
+        const newPath = plus.slice(4).trim()
+        if (newPath === "/dev/null") throw new Error("Deleting files via patch is not supported — use the delete tool")
+        cur = { path: stripPrefix(newPath), isNew: oldPath === "/dev/null", hunks: [] }
+        files.push(cur)
+        i += 2
+        continue
+      }
+      // P15.10：容缺头——`--- a/<path>`（或 b/ 前缀）后直接跟 hunk = 对同路径的修改。
+      if (/^[ab]\//.test(oldPath)) {
+        cur = { path: stripPrefix(oldPath), isNew: false, hunks: [] }
+        files.push(cur)
+        i += 1
+        continue
+      }
+      if (oldPath === "/dev/null") {
+        throw new Error(`"--- /dev/null" needs a "+++ b/<path>" line naming the new file — the --- side does not carry the file name`)
+      }
+      throw new Error(`Malformed patch: expected "+++" line after "${line}"`)
     }
     if (line.startsWith("@@")) {
       if (!cur) throw new Error("Malformed patch: hunk header before any file header")
       const m = line.match(/^@@ -\d+(?:,(\d+))? \+\d+(?:,(\d+))? @@/)
-      if (!m) throw new Error(`Malformed patch: bad hunk header "${line}" (need @@ -old,count +new,count @@)`)
+      if (!m) {
+        // D15.6 (TOOLS.md §15)：坐标裸 "@@" 头——hunk 完全靠操作行定位。
+        // 无行数可用：操作行以 " " / "-" / "+" 开头（空行宽容为上下文行），
+        // 直到下一个 hunk 头 / 文件头 "@@"/"--- "/"+++ "/"diff "/"index " 为止。
+        if (!/^@@(?: @@)?\s*$/.test(line)) {
+          throw new Error(`Malformed patch: bad hunk header "${line}" (need @@ -old,count +new,count @@ or bare @@)`)
+        }
+        const hunk = { ops: [] }
+        i++
+        while (i < lines.length) {
+          const hl = lines[i]
+          if (hl.startsWith("@") || isFileHeader(hl, lines[i + 1]) || hl.startsWith("+++ ") || hl.startsWith("diff ") || hl.startsWith("index ")) break
+          if (hl.startsWith("\\")) { i++; continue } // ""
+          // 宽容空行=上下文行——但 patch 文本末尾（或 hunk 之间/文件头之前）的 "" 是
+          // 分隔产物而非内容：仅当后继仍是操作行时才当作上下文消费。
+          // 复评 #1（2026-09-04）：文件头 "--- "/"+++ " 以 -/+ 开头会被 op 前缀判定误收——
+          // 文件头前的分隔空行不得吞成幽灵上下文行（会把 - 锚序列尾部拼上 ""——跨文件
+          // 零上下文 hunk 因此误报 not-found）。
+          const next = lines[i + 1]
+          if (hl === "" && (next == null || !/^[ +\-\\]/.test(next) || isFileHeader(next, lines[i + 2]) || next.startsWith("+++ "))) break
+          const tag = hl === "" ? " " : hl[0]
+          if (tag !== " " && tag !== "-" && tag !== "+") break // metadata / file section end
+          hunk.ops.push({ type: tag, text: hl === "" ? "" : hl.slice(1) })
+          i++
+        }
+        if (hunk.ops.length === 0) throw new Error(`Malformed patch: empty coordinate-less hunk "${line.trim()}"`)
+        const ctxCount = hunk.ops.filter((o) => o.type === " ").length
+        // §15.3 (TOOLS.md D15.10.1——2026-09-04)：context<2 且含 ≥1 个 - 行 → 接受——定位锚 = hunk 内
+        // 匹配行序列（空格上下文行 + - 行——按出现序）连续——唯一匹配即应用（applyHunks 既有锚匹配域——
+        // 多匹配 / not-found 语义不变）。0 上下文与 1 上下文同待遇（评审 #4a）。
+        // 纯 +（无 - 锚）且 context<2 仍拒——插入位置不可判——报错引导加锚（NF15.8c）。
+        const removedCount = hunk.ops.filter((o) => o.type === "-").length
+        if (ctxCount < 2 && removedCount === 0) {
+          throw new Error(
+            `Coordinate-less hunk ${cur.hunks.length + 1} in ${cur.path} has ${ctxCount} context line(s) — add more context lines`,
+          )
+        }
+        cur.hunks.push(hunk)
+        continue
+      }
       let oldNeed = m[1] == null ? 1 : Number(m[1])
       let newNeed = m[2] == null ? 1 : Number(m[2])
       const hunk = { ops: [] }
@@ -62,8 +128,10 @@ function parsePatch(patch) {
     }
     i++ // skip diff --git / index / blank lines and other metadata
   }
-  if (files.length === 0) throw new Error("No file changes found in patch (need --- / +++ headers)")
-  return files
+  // P15.10：容缺/完整空段头（头后无任何 hunk）过滤——不虚报 touchedPaths、不触发无谓 read+write
+  const withHunks = files.filter((f) => f.hunks.length > 0)
+  if (withHunks.length === 0) throw new Error("No file changes found in patch (need --- / +++ headers)")
+  return withHunks
 }
 
 /** Apply hunks sequentially onto an in-memory line array; any failure throws (caller guarantees nothing is written to disk). Ignores trailing \r when comparing; context lines retain original bytes */
@@ -84,7 +152,10 @@ function applyHunks(fileLines, hunks, eol, path) {
       const preview = oldSeq.slice(0, 3).join(" ⏎ ")
       throw new Error(`Hunk ${h + 1} in ${path} does not apply — context not found: "${preview}${oldSeq.length > 3 ? "…" : ""}". Read the file first and regenerate the patch from actual content.`)
     }
-    if (matches.length > 1) throw new Error(`Hunk ${h + 1} in ${path} matches ${matches.length} locations — add more context lines to make it unique`)
+    if (matches.length > 1) {
+      const preview = oldSeq.slice(0, 3).join(" ⏎ ")
+      throw new Error(`Hunk ${h + 1} in ${path} matches ${matches.length} locations — add more context lines to make it unique. Anchor: "${preview}${oldSeq.length > 3 ? "…" : ""}"`)
+    }
     const pos = matches[0]
     const out = []
     let src = pos
@@ -103,7 +174,7 @@ export const applyPatchTool = {
   parameters: {
     type: "object",
     properties: {
-      patch: { type: "string", description: "Unified diff. May span multiple files (multiple --- / +++ header pairs — including creating MULTIPLE new files via --- /dev/null); --- / +++ headers per file, @@ -old,count +new,count @@ hunks." },
+      patch: { type: "string", description: "Unified diff. May span multiple files (multiple --- / +++ header pairs — including creating MULTIPLE new files via --- /dev/null); --- / +++ headers per file, @@ -old,count +new,count @@ hunks (a bare @@ header is also 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; a zero/one-context hunk is accepted only when it removes (-) at least one line and that anchor sequence is unique, while anchor-free pure-+ (insert) hunks need at least 2 context lines). 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>)." },
     },
     required: ["patch"],
   },