@thincoder/core 0.9.1

package/tools/file.mjs

@@ -0,0 +1,464 @@
+import {
+  DESC,
+  truncate,
+  MAX_READ_LINES,
+  gitDiffOne,
+  autoSyntaxCheck,
+  resolveInCwd,
+  resolveExternal,
+  normalizeEOL,
+  detectFileEol,
+  joinWithEol,
+  majorityEol,
+  FFFD_WARNING,
+} from "./shared.mjs";
+import { applyEditBatch } from "./edit-batch.mjs";
+import { runSingleEdit } from "./edit-diff.mjs";
+// 单一写路径点（编辑器编辑径注入缝——CORE-UNIFICATION §2.13.5）：本档三个写点全走它，
+// 记账面同源住该档（下面只做再导出——保既有 import 面稳定）。
+import { writeThroughPath, clearDirty, clearLastWrite, lastWriteOf, isDirty } from "./write-path.mjs";
+import { specForModel } from "../config.mjs";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, stat, unlink } from "node:fs/promises";
+import { join, relative, dirname } from "node:path";
+
+const MAX_FILE_READ_BYTES = 10_000_000
+const MAX_IMAGE_BYTES = 15_000_000
+// DUAL-END-TRUNCATION (F-1, C 方案——2026-09-09)：read 双端尾行数——窗口截断大文件时
+// 返回 头 N 行（N = 请求窗口，默认 MAX_READ_LINES）+ 省略注 + 尾 M 行（本常量）。M 与
+// 窗口合计（2500 行）为"整读上限"——K=0（尾区与窗口相接）时整印剩余、不产生假省略注。
+export const READ_TAIL_LINES = 500
+
+// ────────────────────────────────────────
+// Dirty-file tracking (read-before-insert guard)
+// ────────────────────────────────────────
+// insert_after anchors on LINE NUMBERS — the most drift-prone addressing.
+// Every write tool marks the file dirty; insert_after refuses to run on a
+// dirty file until the agent reads it again (fresh line numbers).
+// 2026-09-14（CORE-UNIFICATION §2.13.5）：记账面（`dirtyPaths` / `lastWrites` +
+// `markDirty` / `clearDirty` / `isDirty` / `recordWrite` / `lastWriteOf` /
+// `clearLastWrite`）已**同源迁至单一写路径点** `tools/write-path.mjs`——写盘只此一处 ⇒
+// 记账只此一处，调用方不再自行记账（**不重复记账**）。本档只做再导出（**兼容面**——
+// 核内消费方现直取 `write-path.mjs`，此处保留给未改档 / 端侧装配的既有 import 面）。
+export { markDirty, clearDirty, isDirty, recordWrite, lastWriteOf, clearLastWrite } from "./write-path.mjs"
+
+/** 2026-08-31 工具顺手度（用户批准"可以啊"）：写入工具返回带上下文窗口——
+ *  模型拿到的不只是"inserted at L395"，而是"L395 这行是什么内容"——下次再操作时
+ *  能自检"我的行号 vs 实际内容"是否匹配，匹配不上 = 行号漂了，先 read——
+ *  死循环就断了（根因：模型对行号锚点的"新鲜度"没有感知——数字本身不携带语义）。
+ *  write 全文重写跳过（无行号锚点——模型刚写的知道内容）。
+ *  edit-batch.mjs（数组形态）复用——导出仅供内部模块，非公共 API。 */
+export async function appendWriteContext(abs, writeLine, baseResult) {
+  const content = normalizeEOL(await readFile(abs, "utf8"))
+  const lines = content.split("\n")
+  const start = Math.max(1, writeLine - 3)
+  const end = Math.min(lines.length, writeLine + 3)
+  const ctxLines = []
+  for (let i = start; i <= end; i++) {
+    const marker = i === writeLine ? "→" : " "
+    ctxLines.push(`${marker} L${i}\t${lines[i - 1]}`)
+  }
+  return `${baseResult}\ncontext (L${start}-L${end}):\n${ctxLines.join("\n")}`
+}
+
+export const readTool = {
+  name: "read",
+  description: DESC("read"),
+  parameters: {
+    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)." },
+      hashes: { type: "boolean", description: "Include SHA256 line hashes for hash-based editing (default false). Use when you plan to edit the file with hashline_edit." },
+    },
+    required: ["path"],
+  },
+  readonly: true,
+  async execute(args, ctx) {
+    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.`)
+    const content = normalizeEOL(await readFile(abs, "utf8"))
+    // A read refreshes the agent's view — line numbers are fresh again.
+    clearDirty(abs)
+    clearLastWrite(abs) // 2026-08-31：read 同时清写入快照（新视图以 read 为准）
+    const lines = content.split("\n")
+    const offset = Math.max(1, args.offset ?? 1)
+    const limit = Math.min(args.limit ?? MAX_READ_LINES, MAX_READ_LINES)
+    const windowEnd = offset - 1 + limit // index just past the requested window
+    const render = (slice, startLn) => slice.map((l, i) => {
+      const ln = startLn + i
+      if (args.hashes) return `${ln}\t[${hashLine(l)}] ${l}`
+      return `${ln}\t${l}`
+    }).join("\n")
+    // DUAL-END-TRUNCATION (F-1, C 方案——DUAL-END-TRUNCATION.md 2026-09-09):
+    // 大文件（> MAX_READ_LINES 行）窗口截断时返回 头（请求窗口）+ 中段省略注 +
+    // 文件真实尾部（末 READ_TAIL_LINES 行——现尾注升级为真实尾行内容——offload 产物
+    // 的尾端结论可见）。≤ 阈值文件任何窗口走旧头向路径（字节零变化）；窗口覆盖全文件
+    // 也走旧路径。与 hashes 模式照常交互（头尾行 hash 照算）。
+    if (windowEnd >= lines.length || lines.length <= MAX_READ_LINES) {
+      const suffix = windowEnd < lines.length ? `\n... (${lines.length} lines total, use offset to continue)` : ""
+      return truncate(render(lines.slice(offset - 1, windowEnd), offset) + suffix)
+    }
+    const head = render(lines.slice(offset - 1, windowEnd), offset)
+    // 尾区 = 文件末 READ_TAIL_LINES 行；尾区起点落在窗口内（重叠）→ 尾区从窗口后开始
+    // —— 任何行不打印两次；剩余全被覆盖（K=0）→ 整印余段且无假省略注。
+    const tailStart = Math.max(windowEnd, lines.length - READ_TAIL_LINES)
+    const middle = tailStart - windowEnd
+    const tail = render(lines.slice(tailStart), tailStart + 1)
+    return middle > 0
+      ? `${head}\n…(truncated: ${middle} lines in middle, use offset to continue)\n${tail}`
+      : `${head}\n${tail}`
+  },
+}
+
+// ---------------------------------------------------------------- read_image
+
+// Raster formats only — every mainstream vision API (Kimi, Anthropic, OpenAI, Gemini)
+// rejects svg/bmp. svg is served as text source below; bmp is refused with a hint.
+const IMAGE_EXTENSIONS = { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp" }
+const MAX_SVG_CHARS = 100_000
+
+export const readImageTool = {
+  name: "read_image",
+  description: DESC("read_image"),
+  parameters: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "Path to image file (relative to cwd or absolute). Supports png, jpg, gif, webp. svg files are returned as text source (no vision API accepts svg)." },
+    },
+    required: ["path"],
+  },
+  readonly: true,
+  multimodal: true, // returns JSON { text, images } — agent loop converts to multimodal user message
+  /** Returns JSON: { text, images }, for the agent layer to convert into multimodal user messages */
+  async execute(args, ctx) {
+    const abs = resolveInCwd(ctx, args.path)
+    const ext = abs.slice(abs.lastIndexOf(".") + 1).toLowerCase()
+
+    // SVG is text markup — return the source directly. Works with text-only models too
+    // (no vision gate), and never poisons history with an image part the API will 400 on.
+    if (ext === "svg") {
+      const st = await stat(abs).catch(() => null)
+      if (st && st.size > MAX_IMAGE_BYTES) throw new Error(`Image too large: ${Math.round(st.size / 1_000_000)}MB (max 15MB)`)
+      const src = normalizeEOL(await readFile(abs, "utf8"))
+      return `[read_image: ${args.path} (svg source, ${src.length} chars — no vision API accepts image/svg+xml, showing markup instead)]\n` +
+        truncate(src, MAX_SVG_CHARS)
+    }
+
+    // Vision capability gate: injecting an image into a text-only model's history poisons the whole
+    // conversation (every subsequent request 400s on the image part). Refuse before reading the file.
+    // F-3（IMAGE-DOWNGRADE-VISION——2026-09-09）：软引导句逐字锚（设计档照抄——CLI 无 extension
+    // 式自动降级——模型收到错误后自选 spawn 视觉渠道子代理路径）。
+    const model = ctx.agent?.provider?.model
+    if (model && !specForModel(model).multimodal) {
+      throw new Error(
+        `Model "${model}" does not support image input — read_image is unavailable with this provider. ` +
+        `Verify visual output programmatically (file size, dimensions, pixel checks via code) or ask the user to switch to a vision-capable provider.\n` +
+        `模型不支持图像——可 spawn 一个视觉模型子代理（subagent model 参数指视觉渠道）用 read_image 读图`
+      )
+    }
+    const mime = IMAGE_EXTENSIONS[ext]
+    if (!mime) {
+      const hint = ext === "bmp" ? " Convert it to PNG first (no mainstream vision API accepts BMP)." : ""
+      throw new Error(`Unsupported image format: .${ext}. Supported: ${Object.keys(IMAGE_EXTENSIONS).join(", ")}, svg (as text source).${hint}`)
+    }
+    // Check size before reading — prevent huge images from blowing up memory (20MB base64 ≈ 15MB raw)
+    const imgStat = await stat(abs).catch(() => null)
+    if (imgStat && imgStat.size > MAX_IMAGE_BYTES) throw new Error(`Image too large: ${Math.round(imgStat.size / 1_000_000)}MB (max 15MB)`)
+    const buf = await readFile(abs) // raw buffer, no encoding
+    const b64 = buf.toString("base64")
+    const bytes = buf.length
+    const result = JSON.stringify({
+      text: `[read_image: ${args.path} (${mime}, ${bytes} bytes)]`,
+      images: [{ type: "image_url", image_url: { url: `data:${mime};base64,${b64}` } }],
+    })
+    // Paste-created temp files: delete after use, no litter
+    const basename = abs.includes("/") ? abs.slice(abs.lastIndexOf("/") + 1) : abs.slice(abs.lastIndexOf("\\") + 1)
+    if (basename.startsWith(".thincoder-paste-")) {
+      try { await unlink(abs) } catch { /* can't delete, so be it */ }
+    }
+    return result
+  },
+}
+
+// ---------------------------------------------------------------- write
+
+export const writeTool = {
+  name: "write",
+  description: DESC("write"),
+  parameters: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "File path (relative to cwd or absolute)" },
+      content: { type: "string", description: "Full content to write" },
+    },
+    required: ["path", "content"],
+  },
+  readonly: false,
+  touchedPaths(args) { return args.path ? [args.path] : [] },
+  async execute(args, ctx) {
+    const abs = resolveInCwd(ctx, args.path)
+    await mkdir(dirname(abs), { recursive: true })
+    const st = await stat(abs).catch(() => null)
+    if (st?.isDirectory()) throw new Error(`Path is a directory: ${args.path}`)
+    // EOL semantics: overwriting an existing file restores ITS original EOL style (F1);
+    // a new file follows the directory's majority style, defaulting to LF (F2).
+    const prev = st ? await readFile(abs, "utf8").catch(() => null) : null
+    const eol = prev != null ? detectFileEol(prev) : majorityEol(dirname(abs))
+    const content = eol === "\r\n" ? normalizeEOL(args.content).replace(/\n/g, "\r\n") : args.content
+    // 单一写路径点：默认 = writeFile + 记账；端侧注入 ⇒ 编辑器径（§2.13.5）。
+    await writeThroughPath(abs, content, { op: "write", record: { type: "write", startLine: 1, shift: 0 } }) // 全文重写——全文件受影响
+    const diff = gitDiffOne(ctx.cwd, abs)
+    return `Wrote ${args.content.length} chars to ${args.path}${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}`
+  },
+}
+
+// ---------------------------------------------------------------- edit
+
+export const editTool = {
+  name: "edit",
+  description: DESC("edit"),
+  parameters: {
+    type: "object",
+    properties: {
+      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 (tolerant matching: exact → whitespace-only variant → fuzzy match at ≥90% line equality after whitespace/indent/quote normalization). Mutually exclusive with line/startLine/endLine" },
+      new_string: { type: "string", description: "Replacement text — content-based edits require it (empty is an explicit error); with line-based targeting (line/startLine/endLine) give it to replace the line/range, or OMIT it to delete (an explicit empty string is an error — omission is the delete signal)" },
+      line: { type: "integer", description: "1-based line number — replace that single line with new_string, or OMIT new_string to DELETE the line; no old_string needed (mutually exclusive with old_string and startLine/endLine)" },
+      startLine: { type: "integer", description: "1-based first line of the range to replace with new_string (inclusive — requires endLine; mutually exclusive with old_string); OMIT new_string to DELETE the range" },
+      endLine: { type: "integer", description: "1-based last line of the range to replace with new_string (inclusive — requires startLine; mutually exclusive with old_string); OMIT new_string to DELETE the range" },
+      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. 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/line/startLine/endLine — provide each change's targeting (old_string, or line / startLine+endLine) inside its edits entry; new_string replaces when given, and line-targeted entries may omit it to DELETE the line/range.",
+        items: {
+          type: "object",
+          properties: {
+            path: { type: "string" },
+            old_string: { type: "string" },
+            new_string: { type: "string" },
+            line: { type: "integer" },
+            startLine: { type: "integer" },
+            endLine: { type: "integer" },
+            replace_all: { type: "boolean" },
+          },
+        },
+      },
+    },
+    required: [],
+  },
+  readonly: false,
+  touchedPaths(args) {
+    // 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) {
+    // 2026-08-31 工具顺手度（用户批准）：数组形态——一次多文件原子替换
+    // （应用逻辑在 edit-batch.mjs——2026-09-01 拆出，500 行硬限，先例 git-ext.mjs）
+    if (args.edits) return applyEditBatch(args, ctx)
+
+    // 单文件（现状路径）——执行体整段迁出至 edit-diff.mjs（EDIT.md §6——
+    // 行级 LCS 判定：零重叠→替换即删 / 一般 diff→LCS / 空 new→显式报错）
+    return runSingleEdit(args, ctx)
+  },
+}
+
+// ---------------------------------------------------------------- insert_after
+
+export const insertAfterTool = {
+  name: "insert_after",
+  description: DESC("insert_after"),
+  parameters: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "File path" },
+      after_line: { type: "number", description: "Line number to insert after (1-based). Takes priority over after_regex." },
+      after_regex: { type: "string", description: "JavaScript regex to find the line to insert after (must match exactly one line)" },
+      content: { type: "string", description: "Text to insert (with leading newline if you need a blank line)" },
+    },
+    required: ["path", "content"],
+  },
+  readonly: false,
+  touchedPaths(args) { return args.path ? [args.path] : [] },
+  async execute(args, ctx) {
+    const abs = resolveInCwd(ctx, args.path)
+    // Read-before-insert guard: after_line anchors are line numbers, and any
+    // write since the last read made them stale. Refuse instead of silently
+    // inserting at a drifted position (the failure mode that corrupted test
+    // structure repeatedly). after_regex callers get the same gate — a stale
+    // target line is just as wrong, and the rule is simpler to reason about.
+    // 2026-08-31 工具顺手度（用户批准）：判定精确化——本 session 写入工具记录受影响区
+    // （lastWrite），after_line 在未受影响区（<= startLine）→ 行号未漂移 → 允许
+    // （消掉"我写的文件被当外部修改"的摩擦）；受影响区内/write 全文重写 → 拒绝。
+    const lw = lastWriteOf(abs)
+    if (lw && args.after_line != null) {
+      if (lw.type === "write") {
+        throw new Error(
+          `${args.path} 刚被 write 全文重写（was modified since your last read）——任何行号都可能漂移，必须重 read。`
+        )
+      }
+      if (args.after_line > lw.startLine) {
+        throw new Error(
+          `${args.path} 的 after_line ${args.after_line} 在上次写入（L${lw.startLine}）之后——` +
+          `行号已漂移 ${lw.shift >= 0 ? "+" : ""}${lw.shift}，请用新行号或先 read。`
+        )
+      }
+      // after_line <= startLine → 行号未漂移 → 允许
+    } else if (isDirty(abs)) {
+      throw new Error(
+        `${args.path} was modified since your last read — line numbers may be stale.\n` +
+        `Read the file again (read tool) to refresh line numbers, then retry insert_after.`
+      )
+    }
+    const raw = await readFile(abs, "utf8") // original bytes — EOL detection needs the file's real line endings
+    const text = normalizeEOL(raw)
+    const lines = text.split("\n")
+
+    let targetLine
+    if (args.after_line != null) {
+      targetLine = args.after_line
+      if (!Number.isInteger(targetLine)) {
+        throw new Error(`after_line must be an integer, got: ${args.after_line}`)
+      }
+      if (targetLine < 1 || targetLine > lines.length) {
+        throw new Error(`after_line ${targetLine} out of range (file has ${lines.length} lines)`)
+      }
+    } else if (args.after_regex) {
+      let regex
+      try {
+        regex = new RegExp(args.after_regex)
+      } catch (e) {
+        throw new Error(`after_regex /${args.after_regex}/ is not a valid JavaScript regex: ${e.message}`, { cause: e })
+      }
+      const matches = []
+      for (let i = 0; i < lines.length; i++) {
+        if (regex.test(lines[i])) matches.push(i + 1)
+      }
+      if (matches.length === 0) throw new Error(`after_regex /${args.after_regex}/ matched no lines in ${args.path}`)
+      if (matches.length > 1) throw new Error(`after_regex /${args.after_regex}/ matched ${matches.length} lines (${matches.slice(0, 5).join(", ")}${matches.length > 5 ? "…" : ""}); use a more specific pattern or after_line instead`)
+      targetLine = matches[0]
+    } else {
+      throw new Error("Either after_line or after_regex is required")
+    }
+
+    lines.splice(targetLine, 0, normalizeEOL(args.content))
+    // Write back in the file's ORIGINAL EOL style (review R9#2: same bug class as
+    // edit — a CRLF file must not silently become LF here either).
+    const updated = joinWithEol(lines, raw)
+    await writeThroughPath(abs, updated, {
+      op: "write",
+      record: { type: "insert", startLine: targetLine, shift: normalizeEOL(args.content).split("\n").length },
+    })
+    const diff = gitDiffOne(ctx.cwd, abs)
+    const baseResult = `Inserted after line ${targetLine} in ${args.path}${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}`
+    return await appendWriteContext(abs, targetLine + 1, baseResult)
+  },
+}
+
+// ---------------------------------------------------------------- hashline_edit
+
+/**
+ * Compute a 12-char hex SHA256 hash for a line (exact content, no trimming).
+ * Used by both read (hashes=true) and hashline_edit for hash-based matching.
+ */
+export function hashLine(content) {
+  return createHash("sha256").update(content).digest("hex").slice(0, 12)
+}
+
+export const hashlineEditTool = {
+  name: "hashline_edit",
+  description: DESC("hashline_edit"),
+  parameters: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "File path" },
+      old_hashes: { type: "array", items: { type: "string" }, description: "SHA256 hashes (12 chars) of the lines to replace. Read the file with hashes=true first to obtain these hashes. Single line: pass 1 hash; multiple lines: pass the exact sequence of hashes." },
+      new_content: { type: "string", description: "Replacement text (can span multiple lines)" },
+    },
+    required: ["path", "old_hashes", "new_content"],
+  },
+  readonly: false,
+  touchedPaths(args) { return args.path ? [args.path] : [] },
+  async execute(args, ctx) {
+    const abs = resolveInCwd(ctx, args.path)
+    if (!args.old_hashes?.length) throw new Error("old_hashes must not be empty — read the file with hashes=true to get line hashes")
+    const raw = await readFile(abs, "utf8")
+    const content = normalizeEOL(raw)
+    // Encoding-corruption probe: U+FFFD means the file is not clean UTF-8 — hash
+    // addressing may be unreliable. Warn (never block).
+    const corrupted = content.includes("\uFFFD")
+    const lines = content.split("\n")
+    const fileHashes = lines.map((l) => hashLine(l))
+    const target = args.old_hashes
+
+    // Sliding-window match: find all occurrences of the hash sequence.
+    // When multiple matches are found (e.g. empty lines), report positions so the
+    // model can include more context lines (adjacent lines with unique hashes).
+    const matches = []
+    for (let i = 0; i <= fileHashes.length - target.length; i++) {
+      let match = true
+      for (let j = 0; j < target.length; j++) {
+        if (fileHashes[i + j] !== target[j]) { match = false; break }
+      }
+      if (match) matches.push(i)
+    }
+
+    if (matches.length === 0) {
+      // Help the model recover: show the current file hashes for context
+      const maxShow = Math.min(fileHashes.length, 50)
+      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} — 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}` : "")
+      )
+    }
+
+    if (matches.length > 1) {
+      const ctx = 2 // lines of surrounding context
+      const detail = matches.map((m) => {
+        const start = Math.max(0, m - ctx)
+        const end = Math.min(lines.length, m + target.length + ctx)
+        const preview = lines.slice(start, end).map((l, i) => {
+          const ln = start + i + 1
+          const marker = m <= ln - 1 && ln - 1 < m + target.length ? ">" : " "
+          return `${marker} L${ln}: ${l.slice(0, 80)}`
+        }).join("\n")
+        return `  Match at line ${m + 1} (${target.length} line(s)):\n${preview}`
+      }).join("\n\n")
+      throw new Error(
+        `Hash sequence matches ${matches.length} positions in ${args.path} — ambiguous.\n` +
+        `Include more surrounding lines (unique-hash lines before/after the target) to disambiguate.\n\n` +
+        `All matches with surrounding context:\n\n${detail}`
+      )
+    }
+
+    const pos = matches[0]
+    // Replace: remove old lines, insert new lines at the same position
+    const newLines = normalizeEOL(args.new_content).split("\n") // normalize: CRLF in new_content would join into \r\r\n
+    lines.splice(pos, target.length, ...newLines)
+    // Write back in the file's original EOL style (same rule as edit / apply_patch).
+    const updated = joinWithEol(lines, raw)
+    await writeThroughPath(abs, updated, {
+      op: "write",
+      record: { type: "edit", startLine: pos + 1, shift: newLines.length - target.length },
+    })
+    const diff = gitDiffOne(ctx.cwd, abs)
+    const baseResult = `Edited ${args.path}: replaced ${target.length} line(s) at L${pos + 1} with ${newLines.length} line(s)${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}${corrupted ? `\n${FFFD_WARNING}` : ""}`
+    return await appendWriteContext(abs, pos + 1, baseResult)
+  },
+}
+

package/tools/git-checkpoint.mjs

@@ -0,0 +1,143 @@
+/**
+ * git-checkpoint.mjs — git 工具 checkpoint action 子系统（CHECKPOINT.md F2/F6）。
+ * git.mjs 的 checkpoint case 委托到这里：list/create/rewind/cat/versions + F6 懒清理 +
+ * F2/D7 提示行 + 文件树格式化。CLI 与 VS Code 两端同构（镜像，修改须两端同批）。
+ */
+import { runGit } from "./shared.mjs"
+import { escapeXml } from "../agent/helpers.mjs"
+import {
+  createCheckpoint,
+  listCheckpoints,
+  rewind,
+  listFileVersions,
+  catFile,
+  isGitRepo,
+  deleteCheckpointsForCwd,
+} from "../git/checkpoint.mjs"
+
+/** F6 lazy fallback (CHECKPOINT.md D3): an EXTERNAL git commit (via bash / IDE — not the git
+ *  tool) leaves this cwd's checkpoints as pre-commit state. Compare HEAD commit time
+ *  (epoch SECONDS from %ct) against the newest snapshot's meta.time (ms): `%ct × 1000` aligns
+ *  both to ms. HEAD newer → every snapshot predates the commit → clear all. All-or-nothing:
+ *  any snapshot NEWER than HEAD (e.g. a manual create after the external commit) skips the
+ *  whole clear. Best-effort — never blocks the checkpoint op. */
+export async function lazyClearIfCommitted(cwd) {
+  try {
+    const cps = await listCheckpoints(cwd)
+    if (cps.length === 0) return
+    const headSec = runGit(cwd, ["log", "-1", "--format=%ct"])
+    const headMs = Number.parseInt(headSec, 10) * 1000
+    if (!Number.isFinite(headMs) || headMs <= 0) return
+    const newest = cps[0] // listCheckpoints returns newest → oldest
+    if (headMs > newest.time) await deleteCheckpointsForCwd(cwd)
+  } catch {
+    // best-effort (NF7 philosophy) — a lazy-clear failure must not break list/create
+  }
+}
+
+/** checkpoint case 主入口（git 工具 checkpoint action 的全部子动作）。 */
+export async function executeCheckpointAction(args, ctx) {
+  const { checkpointAction: sub, checkpointId: id, path } = args
+  if (!isGitRepo(ctx.cwd)) throw new Error("Not a git repository — checkpoints unavailable")
+
+  if (!sub) return "checkpoint: missing checkpointAction — use: list | create | rewind | cat | versions"
+
+  // F6 lazy fallback (list/create entry): an EXTERNAL git commit (HEAD time newer
+  // than the newest snapshot) means every snapshot predates a safety baseline —
+  // clear them. All-or-nothing: if any snapshot is newer than HEAD, skip entirely.
+  if (sub === "list" || sub === "create") await lazyClearIfCommitted(ctx.cwd)
+
+  if (sub === "create") {
+    const cp = await createCheckpoint(ctx.cwd)
+    return `Checkpoint ${cp.id} created (${cp.files} file(s): ${cp.tracked.length} tracked, ${cp.untracked.length} untracked)`
+  }
+  if (sub === "versions") {
+    if (!path) throw new Error("path is required for versions — the file whose history you want")
+    const versions = await listFileVersions(ctx.cwd, path)
+    if (versions.length === 0) return `No snapshot copies of "${path}" found (it was never part of an auto/protection snapshot).`
+    return (
+      `Historical versions of "${path}" (${versions.length}, newest first):\n` +
+      versions.map((v) =>
+        `  ${v.snapshotId}  ${new Date(v.time).toISOString()}  ${v.size}B  sha:${v.sha}  (${v.source})` +
+        (v.sha === versions[versions.indexOf(v) - 1]?.sha ? "  ← same content as previous" : "")
+      ).join("\n") +
+      `\nRestore a version: checkpointAction=rewind checkpointId=<snapshotId> path="${path}"`
+    )
+  }
+  if (sub === "rewind") {
+    if (!id) throw new Error("checkpointId is required for rewind — use checkpointAction=list to see snapshot ids")
+    if (!path) throw new Error("path is required for rewind — full restore is disabled (as dangerous as `git checkout -- .`). Restore files individually. Use checkpointAction=versions path=<file> to list a file's historical versions.")
+    const s = await rewind(ctx.cwd, id, { path })
+    return `Restored "${path}" (${s.type}) from checkpoint ${id}.\n(The pre-restore state was snapshotted first — you can restore again to go back.)`
+  }
+  if (sub === "cat") {
+    if (!id) throw new Error("checkpointId is required for cat — use checkpointAction=list to see snapshot ids")
+    if (!path) throw new Error("path is required for cat — specify which file to read")
+    return await catFile(ctx.cwd, id, path)
+  }
+  if (sub === "list") {
+    const cps = await listCheckpoints(ctx.cwd)
+    if (cps.length === 0) return "(no checkpoints yet)"
+
+    // Specific id: show the file tree within that snapshot
+    if (id) {
+      const cp = cps.find((c) => c.id === id)
+      if (!cp) throw new Error(`checkpoint ${id} not found`)
+      return formatFileTree(cp)
+    }
+
+    // Overview: list of all snapshots (file names are XML-escaped: they are
+    // untrusted input that flows back into the model's context). F2/D7: fixed
+    // hint line at the tail — the recovery entry for a snapshot after an accident.
+    return cps.map((c) => {
+      const parts = [`${c.id}  ${new Date(c.time).toISOString()}`]
+      if (c.tracked.length) parts.push(`${c.tracked.length} tracked: ${c.tracked.map(escapeXml).join(", ")}`)
+      if (c.untracked.length) parts.push(`${c.untracked.length} untracked: ${c.untracked.map(escapeXml).join(", ")}`)
+      return parts.join("  ")
+    }).join("\n") + "\n(意外丢弃改动？checkpointAction=rewind 可恢复操作前状态)"
+  }
+  throw new Error(`Unknown checkpoint action: ${sub}. Use: list | create | rewind | cat | versions`)
+}
+
+/** Format a checkpoint's file list as a directory tree (directories first, indented display) */
+function formatFileTree(cp) {
+  // File names are XML-escaped: untrusted input that flows back into the model's context
+  const all = [
+    ...(cp.tracked ?? []).map((f) => ({ path: escapeXml(f), type: "" })),
+    ...(cp.untracked ?? []).map((f) => ({ path: escapeXml(f), type: " (untracked)" })),
+  ]
+  if (all.length === 0) return "(empty checkpoint)"
+
+  all.sort((a, b) => a.path.localeCompare(b.path))
+
+  const tree = new Map()
+  for (const { path, type } of all) {
+    const dir = path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "."
+    if (!tree.has(dir)) tree.set(dir, [])
+    tree.get(dir).push({ name: path.slice(dir === "." ? 0 : dir.length + 1), type })
+  }
+
+  const lines = []
+  const dirs = [...tree.keys()].sort()
+  for (const dir of dirs) {
+    if (dir !== "." && !lines.includes(dir + "/")) {
+      const parts = dir.split("/")
+      for (let i = 1; i <= parts.length; i++) {
+        const prefix = parts.slice(0, i).join("/") + "/"
+        if (!lines.includes(prefix)) lines.push(prefix)
+      }
+    }
+  }
+  for (const dir of dirs) {
+    if (dir !== ".") {
+      for (const { name, type } of tree.get(dir)) {
+        lines.push(`  ${dir}/${name}${type}`)
+      }
+    }
+  }
+  for (const { name, type } of tree.get(".") ?? []) {
+    lines.push(name + type)
+  }
+
+  return lines.join("\n")
+}