@thincoder/core 0.9.1

package/tools/bash.mjs

@@ -0,0 +1,276 @@
+import {
+  DESC,
+  sanitizeOutput,
+  truncate,
+  makeDecoder,
+  BASH_TIMEOUT_MS,
+} from "./shared.mjs";
+import { spawn, execFileSync } from "node:child_process";
+
+/** Maximum buffer size per stream (stdout / stderr) before truncation */
+const MAX_STREAM_BUF = 2_000_000
+
+/** Keep only output lines matching a regex (bash filter, case-insensitive). */
+function applyLineFilter(output, filter) {
+  let re
+  try { re = new RegExp(filter, "i") } catch (e) { return `Error: filter regex invalid: ${e.message}` }
+  const lines = output.split("\n").filter((l) => re.test(l))
+  if (lines.length === 0) return `(no output lines matched filter "${filter}")`
+  return truncate(lines.join("\n"))
+}
+
+/** POSIX-only constructs that cmd.exe reads literally (and thus breaks). Detected
+ *  so the agent is told IMMEDIATELY instead of chasing a confusing failure — warning
+ *  only, never a block (the approval layer is the real gate, same as destructive-command policy). */
+function posixSyntaxHint(command) {
+  const hits = []
+  if (/\$\([^)]*\)/.test(command)) hits.push("$(...)")
+  if (command.includes("`")) hits.push("backtick")
+  if (/;\s+/.test(command)) hits.push("';' separators (cmd.exe needs && or newline)")
+  if (/2>\s*\/dev\/null|>\s*\/dev\/null|&>\s*\/dev\/null/.test(command)) hits.push("/dev/null (use NUL)")
+  if (/'.*'/.test(command)) hits.push("single quotes (cmd.exe doesn't group)")
+  if (/\$\{[A-Za-z_]/.test(command)) hits.push("${VAR} (use %VAR%)")
+  if (!hits.length) return ""
+  return "[hint: POSIX-only construct(s) detected — " + hits.join(", ") + ". Current shell is cmd.exe; these will NOT work. Use && / NUL / %VAR%, or use the execute tool (node) for complex logic]"
+}
+
+
+// ====================================================================
+// bash — command execution with safety gates
+// ====================================================================
+
+/**
+ * Build environment for child process.
+ * Passes through all parent env vars, with non-interactive overrides (EDITOR/PAGER/TERM).
+ * Sets PYTHONIOENCODING on Windows to override GBK default for Python scripts.
+ */
+function buildBashEnv() {
+  const isWindows = process.platform === "win32"
+  return {
+    ...process.env,
+    GIT_EDITOR: "true",
+    EDITOR: "true",
+    VISUAL: "true",
+    GIT_PAGER: "cat",
+    PAGER: "cat",
+    TERM: "dumb",
+    ...(isWindows ? { PYTHONIOENCODING: "utf-8" } : {}),
+  }
+}
+
+/**
+ * Platform-aware process tree kill.
+ * POSIX: kill process group (spawned with detached=true).
+ * Windows: taskkill /T to reach grandchildren (npm test's subprocesses, etc.).
+ */
+function killProcessTree(child) {
+  if (process.platform === "win32") {
+    try { execFileSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore" }) } catch {}
+  } else {
+    try { process.kill(-child.pid, "SIGKILL") } catch {}
+    try { child.kill("SIGKILL") } catch {} // fallback: kill directly if group kill fails
+  }
+}
+
+/**
+ * Detect destructive git commands and auto-snapshot BEFORE execution.
+ * The scenario: the model writes uncommitted code, then (after breaking things)
+ * runs `git checkout -- .` / `git restore` / `git reset --hard` / `git clean -f` to
+ * roll back — which silently DESTROYS all uncommitted work. The pre-task checkpoint
+ * cannot help (it was taken before the code was written); only a snapshot taken
+ * immediately before the destructive command can.
+ *
+ * This is the defense-in-depth guard: a WIDE match that snapshots before the command
+ * runs — the command itself is NEVER blocked (a determined model bypasses text
+ * matching anyway; the real gate is the approval layer). A snapshot alone is not
+ * enough: the model may retry a variant that slips through the exact matcher
+ * (e.g. `git checkout HEAD -- .`), or run git outside the bash tool. The snapshot
+ * taken here survives all of those paths.
+ *
+ * Matching is intentionally WIDE (false positives are harmless — one extra snapshot;
+ * a missed match is a data-loss disaster).
+ */
+const GIT_DESTRUCTIVE_RE = /\bgit\s+(?:checkout\s+(?:[\w./-]+\s+)?--(?!\w)|checkout\s+\.|restore\s+(?!--help\b)(?!--staged\b(?!.*--worktree))|reset\s+--hard|clean\s+-(?=\S*f)(?!\S*n))/i
+
+/** Returns { id, notice } when a snapshot was taken, else null. Never throws. */
+async function gitGuardSnapshot(command, cwd) {
+  if (!GIT_DESTRUCTIVE_RE.test(command)) return null
+  try {
+    const { isGitRepo, createCheckpoint } = await import("../git/checkpoint.mjs")
+    if (!isGitRepo(cwd)) return null
+    const cp = await createCheckpoint(cwd)
+    if (!cp) return null
+    return {
+      id: cp.id,
+      notice: `[auto-protection] Destructive git command detected — snapshot ${cp.id} created BEFORE execution (${cp.files} file(s): ${cp.tracked.length} tracked, ${cp.untracked.length} untracked). If this command destroyed uncommitted work, restore it: checkpoint action=checkpoint checkpointAction=rewind checkpointId=${cp.id}`,
+    }
+  } catch {
+    return null // protection is best-effort — never block the command
+  }
+}
+
+/**
+ * Run a bash command: spawn, stream stdout/stderr with buffering and decoding,
+ * enforce timeout and signal abort, return formatted result.
+ *
+ * Returns a promise that resolves to the formatted output string (stdout + stderr + status + truncation note).
+ */
+function runBash(command, cwd, { timeout, signal, onOutput, shell }) {
+  return new Promise((resolve) => {
+    // Windows + default cmd: force UTF-8 code page for this child process (each spawn
+    // is an independent cmd, so chcp has no side effects on other shells) — otherwise
+    // cmd emits GBK bytes that the UTF-8 decoder turns into mojibake, and the model
+    // fights encoding errors instead of the actual command (reported UX on win11).
+    const effectiveCommand = process.platform === "win32" && !shell
+      ? `chcp 65001 >nul && ${command}`
+      : command
+    // args MUST be an explicit [] — the two-arg spawn(cmd, options) form is
+    // DEP0190-deprecated (Node 24): the options object would be misread as args.
+    const child = spawn(effectiveCommand, [], {
+      cwd,
+      shell: shell ?? true,
+      windowsHide: true,
+      detached: process.platform !== "win32",
+      stdio: ["ignore", "pipe", "pipe"],
+      env: buildBashEnv(),
+      // 双保险（2026-09-05——裸 spawn 无 signal 教训：abort 只靠 killTree 手动杀——taskkill
+      // best-effort 可能失败/竞态）——Node signal option = 第一道（abort 时自动杀**直接**子
+      // 进程——cmd——语义保证）；killTree 仍是必需兜底（孙进程握管道使 close 不触发——见
+      // L191 注释——spawn 级 kill 不达孙进程）
+      ...(signal ? { signal } : {}),
+    })
+
+    const killTree = () => killProcessTree(child)
+
+    // Separate decoders for stdout / stderr (same encoding in practice, but separate
+    // collection is cleaner and lets the model locate errors via stderr quickly)
+    const outDecoder = makeDecoder()
+    const errDecoder = makeDecoder()
+    let outBuf = ""
+    let errBuf = ""
+    let truncatedNote = ""
+
+    child.stdout.on("data", (d) => {
+      const s = sanitizeOutput(outDecoder(d))
+      if (s) onOutput?.(s)
+      if (outBuf.length < MAX_STREAM_BUF) outBuf += s
+      else if (!truncatedNote) truncatedNote =
+        "\n[... output exceeded 2MB, remainder discarded — redirect to a file if you need the full output]"
+    })
+
+    child.stderr.on("data", (d) => {
+      const s = sanitizeOutput(errDecoder(d))
+      if (s) onOutput?.(s)
+      if (errBuf.length < MAX_STREAM_BUF) errBuf += s
+    })
+
+    const timer = setTimeout(killTree, timeout)
+    if (signal) signal.addEventListener("abort", killTree, { once: true })
+
+    let settled = false
+    let graceTimer = null
+    const finish = (result) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      clearTimeout(graceTimer)
+      // 2026-09-05（advisor 🟡#2）：收尾移除 abort 监听器——ctx.signal 为长生命周期对象，
+      // 残留 once 监听器每次 bash 调用累积（闭包持有 child/输出缓冲直到 abort 才释放）
+      if (signal) signal.removeEventListener("abort", killTree)
+      resolve(result)
+    }
+
+    child.on("error", (error) => {
+      // signal 双保险（2026-09-05）：abort 时 Node signal option 杀直接子进程 → 本事件
+      // 以 AbortError 先触发——**跳过 finish**（不 settled）——exit 事件随后必到（实证
+      // 2ms 内）走 L195 分支带已收集输出收尾（user interrupted——不丢 partial）；
+      // 非 abort 的真 spawn 错误（command not found 等）保持原分支
+      if (error.name === "AbortError") return
+      // spawn 失败形态（2026-09-18 工具失败判据同族残项批）：进程未启动 ⇒ 无退出码（不伪造），
+      // 尾附独占状态位 `(spawn failed)`（判据族第三成员——`webview/lib.js toolFailureStatus`）；
+      // 诊断行 `Command failed: <errno>` 与 `[stdout]:` 段原样保留（诊断面不入判据）。
+      const parts = [
+        `Command failed: ${error.message}`,
+        `[stdout]:\n${outBuf || "(empty)"}`,
+        "(spawn failed)",
+      ]
+      finish(truncate(parts.join("\n\n")))
+    })
+
+    // Shell exited. Normally 'close' follows within milliseconds — but a BACKGROUND
+    // child (start /b, &, nohup …) inherits the stdio pipes, so the pipe stays open
+    // and 'close' never fires: the tool would hang until the timeout. Resolve after
+    // a short grace period instead, returning whatever output was collected.
+    child.on("exit", (code, exitSignal) => {
+      graceTimer = setTimeout(() => {
+        const outFlush = sanitizeOutput(outDecoder(Buffer.alloc(0), true))
+        const errFlush = sanitizeOutput(errDecoder(Buffer.alloc(0), true))
+        if (outFlush) onOutput?.(outFlush)
+        if (errFlush) onOutput?.(errFlush)
+        const status = exitSignal ? `killed: ${exitSignal}` : `exit code ${code}`
+        const parts = [`[stdout]:\n${(outBuf + outFlush).trim() || "(empty)"}`]
+        if ((errBuf + errFlush).trim()) parts.push(`[stderr]:\n${(errBuf + errFlush).trim()}`)
+        parts.push(`(${status})`)
+        parts.push("[background] the shell exited but a child process still holds the output pipe — output may be incomplete; the process may still be running")
+        finish(truncate(parts.join("\n\n") + truncatedNote))
+      }, 1500)
+    })
+
+    child.on("close", (code, exitSignal) => {
+      // Flush decoder tails — also push final bytes to panel
+      const outFlush = sanitizeOutput(outDecoder(Buffer.alloc(0), true))
+      const errFlush = sanitizeOutput(errDecoder(Buffer.alloc(0), true))
+      outBuf += outFlush
+      errBuf += errFlush
+      if (outFlush) onOutput?.(outFlush)
+      if (errFlush) onOutput?.(errFlush)
+
+      // Windows has no POSIX signals — check signal.aborted for user interrupts
+      const status = (exitSignal || signal?.aborted)
+        ? `killed: ${signal?.aborted ? "user interrupted" : "timeout"}`
+        : `exit code ${code}`
+
+      const parts = [`[stdout]:\n${outBuf.trim() || "(empty)"}`]
+      if (errBuf.trim()) parts.push(`[stderr]:\n${errBuf.trim()}`)
+      parts.push(`(${status})`)
+      finish(truncate(parts.join("\n\n") + truncatedNote))
+    })
+  })
+}
+
+// ====================================================================
+// tool definitions
+// ====================================================================
+
+export const bashTool = {
+  name: "bash",
+  description: DESC("bash"),
+  parameters: {
+    type: "object",
+    properties: {
+      command: { type: "string", description: "Shell command to execute" },
+      timeout: { type: "number", description: `Timeout in ms (default ${BASH_TIMEOUT_MS})` },
+      filter: { type: "string", description: "Optional: only return output lines matching this regex (case-insensitive)" },
+    },
+    required: ["command"],
+  },
+  readonly: false,
+  outputPanel: true, // stream stdout/stderr to panel during execution, collapse to summary on completion
+  async execute(args, ctx) {
+    // Git destructive commands are NEVER rejected — the model would bypass the
+    // guard anyway. Instead: snapshot every uncommitted file first, then ALLOW
+    // the command. The snapshot makes the rollback reversible (defense in depth:
+    // the wide matcher also covers variants like `git checkout HEAD -- .`).
+    const guard = await gitGuardSnapshot(args.command, ctx.cwd)
+    const result = await runBash(args.command, ctx.cwd, {
+      timeout: args.timeout ?? BASH_TIMEOUT_MS,
+      signal: ctx.signal,
+      onOutput: ctx.onOutput,
+      shell: ctx.agent?.config?.shell ?? null,
+    })
+    const filtered = args.filter ? applyLineFilter(result, args.filter) : result
+    const hint = posixSyntaxHint(args.command)
+    const body = guard ? `${guard.notice}\n\n${filtered}` : filtered
+    return hint ? `${hint}\n${body}` : body
+  },
+}

package/tools/edit-batch.mjs

@@ -0,0 +1,204 @@
+/**
+ * edit-batch.mjs — edit 工具的数组形态（edits: [...]）：一次多文件原子替换。
+ * （2026-08-31 工具顺手度 §9 ②；2026-09-01 缺陷修复"同文件多条串行累积"；
+ * 2026-09-04 EDIT.md §6——条目级判定+应用迁至 edit-diff.mjs——批量调共用。）
+ *
+ * 语义：同一 path 的多条编辑按序**串行累积应用**——第 n 条基于前 n-1 条已应用后的
+ * 累积内容做匹配与替换；跨 path 条目互不影响（并行原子语义）；任一条失败 →
+ * 全不写（原子性保留）。每条目独立按判定序（EDIT.md §4——分支 0 单行替换 / 零重叠→替换即删 /
+ * LCS / 空 new 显式报错；EDIT.md §5（约束——删行形态）：省略 new_string = 删行。顶层 path
+ * （args.path）为无自带 path 条目的默认（2026-09-05 用户裁定——条目自带 path 优先——见
+ * EDIT.md §5 修订注）。
+ */
+import { readFile } from "node:fs/promises"
+import { resolveInCwd, normalizeEOL, joinWithEol, gitDiffOne, autoSyntaxCheck } from "./shared.mjs"
+// edit-batch ↔ edit-diff 循环引用（#69 后同型）：两侧导入的都是函数声明（提升初始化），
+// 仅在调用期使用——ESM 循环下安全（无模块求值期取值）。
+// 写盘经单一写路径点（§2.13.5）——本档不再直调 fs；回执组装迁 composeEditReceipt（#69）。
+import { writeThroughPath } from "./write-path.mjs"
+// EDIT.md §6：批量条目判定+应用共用 edit-diff（EDIT.md §4 分支 0 单行替换 + 行级 LCS——零重叠→替换即删）；
+// EDIT.md §5：edits 互斥错误文本随前置校验分支迁出至 edit-diff.mjs。
+// #69：回执组装共用 edit-diff 的 composeEditReceipt（回执形态按端注入——缺省 = CLI 形态）。
+import { assertEditArgsExclusive, validateEditEntry, computeEditEntry, splitLines, EMPTY_NEW_STRING_LINE, deleteTarget, composeEditReceipt } from "./edit-diff.mjs"
+
+/**
+ * Apply the `edits` array form: multi-file atomic replacement. Throws on any
+ * failure (atomic — nothing written). Returns the per-entry result text (joined).
+ */
+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 | line/startLine+endLine, new_string}")
+  }
+  assertEditArgsExclusive(args)
+  // 原子：先全量检查（所有文件的替换都可执行）——任一失败全不写。
+  // 2026-09-01 缺陷修复（TOOLS.md §9 ②"同文件多条规则"）：同一 path 的多条编辑
+  // 按序**串行累积应用**——第 n 条基于前 n-1 条已应用后的累积内容做匹配与替换
+  // （原实现每条都基于盘上原始内容计算、写盘循环后置，同文件后者覆盖前者 →
+  // 除最后一条外全部静默丢失）；跨 path 条目互不影响（并行原子语义不变）。
+  const groups = new Map() // abs → 每文件一条流水线
+  for (const e of args.edits) {
+    // 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: p, raw, content: normalizeEOL(raw), edits: [] }
+      groups.set(abs, g)
+    }
+    g.edits.push(e)
+  }
+  const prepared = [] // 每条目一条回显；同文件内按 args 序，跨文件按首次出现分组序（应用/回显语义均正确）
+  for (const g of groups.values()) {
+    g.netShift = 0 // 组内行数差累积（合并快照的 shift = 全组净漂移）
+    for (const e of g.edits) {
+      // 条目级判定+应用（edit-diff——EDIT.md §4 分支 0 单行替换 + 判定序 1/2/3 + 空 new 显式报错 +
+      // >1000 行报错（diff 形态——D1 行号条目走 applyLineEdit，不经 LCS，无此上限））
+      const out = computeEditEntry(g.content, e, {
+        path: g.path,
+        absPath: g.abs,
+        abortPrefix: "edit aborted (atomic — no files written): ",
+      })
+      prepared.push({
+        g,
+        editStartLine: out.editStartLine, // 基于累积内容计算——已天然计入前面条目的行偏移，不再累加
+        lineShift: out.lineShift,
+        occurrences: out.occurrences,
+        note: out.note ?? null, // P15.11——空白差异自动落点标记（成功消息追加）
+        deleted: out.deleted ?? false, // 删行形态（EDIT.md §5）——结果文本用 Deleted 前缀
+      })
+      g.content = out.updated // 串行累积：下一条基于本条应用后的内容
+      g.netShift += out.lineShift
+    }
+  }
+  // 全部检查通过——每文件一次写盘（同文件多条：写入串行累积后的最终内容）；
+  // recordWrite 每组一条合并快照：startLine = 组内**所有**编辑受影响行的最小值
+  // （#2，2026-09-01 交付评审尾巴——原实现取首条 = 调用序第一条，逆序条目时
+  // 护栏下界过高、受影响区内的 insert_after 被放行），shift = 全组行数差累积
+  // ——受影响区护栏覆盖组内所有编辑
+  for (const g of groups.values()) {
+    const startLine = Math.min(...prepared.filter((p) => p.g === g).map((p) => p.editStartLine))
+    // 单一写路径点：默认 = writeFile + 记账；端侧注入 ⇒ 编辑器径（§2.13.5）。
+    await writeThroughPath(g.abs, joinWithEol(normalizeEOL(g.content).split("\n"), g.raw), {
+      op: "write",
+      record: { type: "edit", startLine, shift: g.netShift },
+    })
+  }
+  const results = []
+  for (const p of prepared) {
+    // #4（2026-09-01 交付评审尾巴）：与单文件路径对齐——每条结果附 git diff +
+    // autoSyntaxCheck（同文件多条会重复 diff/检查，换取格式一致、实现零分支）
+    const diff = gitDiffOne(ctx.cwd, p.g.abs)
+    const base = p.deleted
+      ? `Deleted ${deleteTarget(p)} of ${p.g.path}${diff ? "\n" + diff : ""}${await autoSyntaxCheck(p.g.abs)}`
+      : `Edited ${p.g.path}: replaced ${p.occurrences} occurrence(s)${p.note ? ` — ${p.note}` : ""}${diff ? "\n" + diff : ""}${await autoSyntaxCheck(p.g.abs)}`
+    results.push(await composeEditReceipt({
+      abs: p.g.abs,
+      path: p.g.path,
+      writeLine: p.editStartLine,
+      base,
+      deleted: p.deleted === true,
+      occurrences: p.occurrences,
+      note: p.note,
+    }))
+  }
+  return results.join("\n")
+}
+
+// ---------------------------------------------------------------------------
+// 2026-09-08 edit 语义升级（EDIT.md §2/§3——D1 按行号改 / D2 模糊匹配，落点定死本模块；
+// 条目判定接线在 edit-diff.mjs computeEditEntry——单形态/批量/ACP 桥三通道自动继承；
+// 阶段 2 删行形态见 EDIT.md §5（约束）。以下均为纯函数（无 IO）——edit-diff.mjs 调用期导入
+// （ESM 循环引用安全：两侧仅函数声明，提升初始化——同 file.mjs ↔ edit-diff.mjs 先例）。
+
+/**
+ * D2 行级 normalize（EDIT.md §3——匹配档位；阶段 2 normalize 统一基准——双端同算法）：
+ * ① 去首尾空白 + 去行尾空格；② tab → 2 空格；③ 引号**单遍逐字符映射**——ASCII 单引号 /
+ * 弯引号 ‘ ’ “ ” / 反引号 → 直双引号 "（评审 #2 定稿目标字符 = "——与 ASCII 单引号规则
+ * 合并为单遍映射，无顺序依赖——防两端分叉）。**不做行内 \s+ 折叠**——缩进/对齐是结构信息，
+ * 折叠会误匹配文字相似但结构不同的行（统一基准 5——CLI 从未折叠，防误配回归）。仅用于匹配
+ * 比较——替换永远用文件原文窗口。
+ */
+const QUOTE_TO_DOUBLE = {
+  "'": '"', "\u2018": '"', "\u2019": '"', "\u201c": '"', "\u201d": '"', "`": '"',
+}
+export function normalizeEditLine(line) {
+  let out = ""
+  for (const ch of line) {
+    if (ch === "\t") out += "  "
+    else out += QUOTE_TO_DOUBLE[ch] ?? ch
+  }
+  return out.replace(/\s+$/g, "").trim()
+}
+
+/** D2 模糊匹配阈值：行级 normalize 后逐行相等比例 ≥0.9 即匹配（评审 #4 定稿）。 */
+export const FUZZY_MATCH_THRESHOLD = 0.9
+/** D2 成功消息追加 note（双端同句——同 WHITESPACE_VARIANT_NOTE 机制）。 */
+export const FUZZY_MATCH_NOTE = "applied via fuzzy match (≥90% of lines identical after whitespace/indent/quote normalization)"
+
+/**
+ * D2 模糊匹配（P15.11 空白自动落点的推广——逐字/trim 等价都失败后的最后一档）：
+ * 找文件中**唯一**窗口——行数与 old 相同、normalizeEditLine 后逐行相等比例 ≥90% →
+ * 返回 { actual }（actual = 文件窗口原文）；多窗口达标 → null（歧义不猜——走 not-found
+ * 报错引导）；old 含尾换行 → null（终止符语义边界——同 P15.11）。比例向上取整行数：
+ * 需要相等行数 = ceil(m × 0.9)（m=1 即 normalize 后全等——单行细微差异由此命中）。
+ */
+export function findFuzzyWindow(content, old) {
+  if (old.endsWith("\n")) return null
+  const oldLines = old.split("\n")
+  const m = oldLines.length
+  const fileLines = content.split("\n")
+  if (m === 0 || fileLines.length < m) return null
+  const norm = oldLines.map(normalizeEditLine)
+  const need = Math.ceil(m * FUZZY_MATCH_THRESHOLD)
+  let hit = null
+  for (let i = 0; i + m <= fileLines.length; i++) {
+    let eq = 0
+    for (let j = 0; j < m; j++) {
+      if (normalizeEditLine(fileLines[i + j]) === norm[j]) eq++
+    }
+    if (eq < need) continue
+    const actual = fileLines.slice(i, i + m).join("\n")
+    if (actual === old) continue // 逐字已匹配——occurrences=0 前提下不会发生
+    if (hit) return null // 多窗口达标 → 歧义 → 不猜
+    hit = { actual }
+  }
+  return hit
+}
+
+/**
+ * D1 按行号改（EDIT.md §2/§5——F1）：entry 带 line（单行）或 startLine/endLine（1-based
+ * 闭区间）→ 直接按行号替换该行/行范围为 new_string（无需 old_string——互斥校验在
+ * validateEditEntry）。阶段 2 删行形态（EDIT.md §5——裁定 A）：**省略 new_string =
+ * 删除该行/范围**（意图有界——删哪行是显式声明）；显式空串 `new_string: ""` →
+ * EMPTY_NEW_STRING_LINE 显式报错（模板生成 new_string 但落空 ≠ 删行意图——防误删）。
+ * 内容域 = normalizeEOL 后 LF（与 computeEditEntry 同域）；尾随换行随原文件保持（删到
+ * 文件为空 → ""——无剩余行即无终止符）。行号越界 → 明确报错。原子性由调用方保证
+ * （本函数纯计算）。
+ * 返回 { updated, editStartLine, lineShift, occurrences, note, deleted? }（同 computeEditEntry 形态）。
+ */
+export function applyLineEdit(content, entry, opts = {}) {
+  const prefix = opts.abortPrefix ?? ""
+  if (entry.new_string === "") throw new Error(prefix + EMPTY_NEW_STRING_LINE)
+  const lines = splitLines(content)
+  const start = entry.line ?? entry.startLine
+  const end = entry.line ?? entry.endLine
+  if (start > lines.length || end > lines.length) {
+    throw new Error(prefix + `line ${end > lines.length ? end : start} out of range — ${opts.path ?? "file"} has ${lines.length} line(s)`)
+  }
+  const removed = end - start + 1
+  if (entry.new_string === undefined) {
+    // 删行/删范围（EDIT.md §5）——省略 new_string：受影响行整体移除
+    const remaining = [...lines.slice(0, start - 1), ...lines.slice(end)]
+    const updated = remaining.join("\n") + (remaining.length > 0 && content.endsWith("\n") ? "\n" : "")
+    return { updated, editStartLine: start, lineShift: -removed, occurrences: 1, note: null, deleted: true }
+  }
+  const newLines = splitLines(entry.new_string)
+  const updated = [...lines.slice(0, start - 1), ...newLines, ...lines.slice(end)].join("\n") +
+    (content.endsWith("\n") ? "\n" : "")
+  return { updated, editStartLine: start, lineShift: newLines.length - removed, occurrences: 1, note: null }
+}