@thincoder/core 0.10.12 → 0.11.1

package/tools/edit-batch.mjs

@@ -3,23 +3,24 @@
  * （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 单行替换 / 零重叠→替换即删 /
+ * 语义：同一 path 的多条编辑**分两类应用**（帧判据单源 = EDIT-HELPERS §7.3 R1–R4）——
+ * 行号条目先全部应用（按 startLine 降序，范围重叠则整批拒），内容条目随后按调用序
+ * 串行累积；跨 path 条目互不影响（并行原子语义）；任一条失败 → 全不写（原子性保留）。
+ * 每条目独立按判定序（EDIT.md §4——分支 0 单行替换 / 零重叠→替换即删 /
  * LCS / 空 new 显式报错；EDIT.md §5（约束——删行形态）：省略 new_string = 删行。顶层 path
  * （args.path）为无自带 path 条目的默认（2026-09-05 用户裁定——条目自带 path 优先——见
- * EDIT.md §5 修订注）。
+ * EDIT.md §5 修订注）。排顺序与累积走 edit-diff 的两个零 IO 纯函数——本档只留 IO（读 / 写 / 回执）。
  */
 import { readFile } from "node:fs/promises"
 import { resolveInCwd, normalizeEOL, joinWithEol, gitDiffOne, autoSyntaxCheck } from "./shared.mjs"
 // edit-batch ↔ edit-diff 循环引用：两侧导入的都是函数声明（提升初始化），
 // 仅在调用期使用——ESM 循环下安全（无模块求值期取值）。
 // 写盘经单一写路径点（§2.13.5）——本档不再直调 fs；回执组装共用 edit-diff 的 composeEditReceipt。
-import { writeThroughPath } from "./write-path.mjs"
+import { writeThroughPath, lineAnchorVerdict, lineAnchorRefusal } from "./write-path.mjs"
 // EDIT.md §6：批量条目判定+应用共用 edit-diff（EDIT.md §4 分支 0 单行替换 + 行级 LCS——零重叠→替换即删）；
 // EDIT.md §5：edits 互斥错误文本随前置校验分支迁出至 edit-diff.mjs。
 // 回执组装共用 edit-diff 的 composeEditReceipt（单点——缺省回执 = base + 写入点上下文）。
-import { assertEditArgsExclusive, assertEditsContainer, assertEditEntries, validateEditEntry, computeEditEntry, splitLines, EMPTY_NEW_STRING_LINE, EDIT_ENTRY_NO_PATH, EDIT_ABORT_PREFIX, editEntryLabel, deleteTarget, composeEditReceipt } from "./edit-diff.mjs"
+import { assertEditArgsExclusive, assertEditsContainer, assertEditEntries, validateEditEntry, hasLineParams, planEditEntries, applyPlannedEntries, splitLines, EMPTY_NEW_STRING_LINE, EDIT_ENTRY_NO_PATH, editEntryLabel, deleteTarget, composeEditReceipt } from "./edit-diff.mjs"
 
 /**
  * Apply the `edits` array form: multi-file atomic replacement. Throws on any
@@ -31,12 +32,13 @@ export async function applyEditBatch(args, ctx) {
   assertEditArgsExclusive(args)
   assertEditEntries(args.edits) // #325 条目预扫（非对象条目 ⇒ 含下标成形错误；不读盘）
   // 原子：先全量检查（所有文件的替换都可执行）——任一失败全不写。
-  // 2026-09-01 缺陷修复（TOOLS.md §9 ②"同文件多条规则"）：同一 path 的多条编辑
-  // 按序**串行累积应用**——第 n 条基于前 n-1 条已应用后的累积内容做匹配与替换
-  // （原实现每条都基于盘上原始内容计算、写盘循环后置，同文件后者覆盖前者 →
-  // 除最后一条外全部静默丢失）；跨 path 条目互不影响（并行原子语义不变）。
+  // 2026-09-01 缺陷修复（TOOLS.md §9 ②"同文件多条规则"）：同一 path 的多条编辑基于同一份
+  // 累积内容应用，写盘前不得让后者覆盖前者（原实现每条都基于盘上原始内容计算、写盘循环
+  // 后置 → 除最后一条外全部静默丢失）；跨 path 条目互不影响（并行原子语义不变）。
+  // 累积顺序自 2026-11-02 起 = 帧（行号条目降序先应用、内容条目随后）——见下方判定点。
   const groups = new Map() // abs → 每文件一条流水线
-  for (const e of args.edits) {
+  for (let i = 0; i < args.edits.length; i++) {
+    const e = args.edits[i]
     // 2026-09-05 用户裁定：顶层 path + edits 并存合法化——`e.path || args.path`（条目优先；
     // 缺省入口仅在此兜底）；两者皆无 → 原错误文本（措辞补顶层选项）。
     const p = e.path || args.path
@@ -47,39 +49,42 @@ export async function applyEditBatch(args, ctx) {
     let g = groups.get(abs)
     if (!g) {
       const raw = await readFile(abs, "utf8")
-      g = { abs, path: p, raw, content: normalizeEOL(raw), edits: [] }
+      g = { abs, path: p, raw, content: normalizeEOL(raw), edits: [], origIdx: [] }
       groups.set(abs, g)
     }
     g.edits.push(e)
+    g.origIdx.push(i) // 条目在 args.edits 里的原始下标——回显按它回位（EDIT-HELPERS §7.3）
   }
-  const prepared = [] // 每条目一条回显；同文件内按 args 序，跨文件按首次出现分组序（应用/回显语义均正确）
+  // 判定点（§7.3 写死）：组循环**之前**用批前快照判一次——命中即抛、零写（下方第二个循环才写盘）。
+  // 组内不再逐条判：组内漂移由 R2（降序应用）自己算得出来，逐条再判会用同一份快照判出与 R2 相反的结果。
   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_ABORT_PREFIX,
-      })
-      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
+      if (!hasLineParams(e)) continue
+      const startLine = e.line ?? e.startLine
+      const endLine = e.line ?? e.endLine
+      if (lineAnchorVerdict(g.abs, startLine, endLine)) throw new Error(lineAnchorRefusal(g.abs, startLine, endLine))
     }
   }
-  // 全部检查通过——每文件一次写盘（同文件多条：写入串行累积后的最终内容）；
+  // 回显按调用序（EDIT-HELPERS §7.3）：按条目在 `edits` 数组里的**原始下标**回填——跨文件
+  // 交错的批同样如此；按文件分组去排会排成 A、A、B，而模型是按位置对号的，顺序一变它会把
+  // 结果贴到错的那一笔上。
+  const prepared = new Array(args.edits.length)
+  for (const g of groups.values()) {
+    // 帧单源（§7.3 R1–R4）= edit-diff 的两个零 IO 纯函数：排顺序 + 按计划序累积
+    const plan = planEditEntries(g.edits, g.path)
+    if (plan.rejection) throw new Error(plan.rejection)
+    const applied = applyPlannedEntries(g.content, g.edits, plan.order, { path: g.path })
+    g.content = applied.content
+    // 合并快照的 shift = 全组净漂移（公式不变；重排后的取值由 AC11 钉住）
+    g.netShift = applied.results.reduce((n, r) => n + r.lineShift, 0)
+    // results 按组内调用序；g.origIdx[k] = 该结果在 args.edits 里的原始下标
+    applied.results.forEach((r, k) => { prepared[g.origIdx[k]] = { g, ...r } })
+  }
+  // 全部检查通过——每文件一次写盘（同文件多条：写入按帧排好后累积出的最终内容）；
   // recordWrite 每组一条合并快照：startLine = 组内**所有**编辑受影响行的最小值
   // （#2，2026-09-01 交付评审尾巴——原实现取首条 = 调用序第一条，逆序条目时
   // 护栏下界过高、受影响区内的 insert_after 被放行），shift = 全组行数差累积
-  // ——受影响区护栏覆盖组内所有编辑
+  // ——受影响区护栏覆盖组内所有编辑（公式不变；重排后的取值由 AC11 钉住）
   for (const g of groups.values()) {
     const startLine = Math.min(...prepared.filter((p) => p.g === g).map((p) => p.editStartLine))
     // 单一写路径点：默认 = writeFile + 记账；端侧注入 ⇒ 编辑器径（§2.13.5）。
@@ -116,6 +121,8 @@ export async function applyEditBatch(args, ctx) {
 // ---------------------------------------------------------------------------
 // 2026-09-08 edit 语义升级（EDIT.md §2/§3——D1 按行号改 / D2 模糊匹配，落点定死本模块；
 // 条目判定接线在 edit-diff.mjs computeEditEntry——单形态/批量/ACP 桥三通道自动继承；
+// 2026-11-02：排顺序（帧 R1–R4）与累积也上提到 edit-diff（planEditEntries /
+// applyPlannedEntries）——两通道共用同一份排法。
 // 阶段 2 删行形态见 EDIT.md §5（约束）。以下均为纯函数（无 IO）——edit-diff.mjs 调用期导入
 // （ESM 循环引用安全：两侧仅函数声明，提升初始化——同 file.mjs ↔ edit-diff.mjs 先例）。
 

package/tools/edit-diff.mjs

@@ -4,6 +4,8 @@
  * edit 语义（权威 = EDIT.md §2-§5——2026-09-08 语义升级 D1/D2/D3 已并入）：两种定位形态（互斥）——
  * ① 按行号改（D1/F1）：line（单行）/ startLine+endLine（1-based 闭区间）→ 直接替换该
  *    行/行范围为 new_string（无需 old_string——实现落点 edit-batch.mjs applyLineEdit）；
+ *    **先过行号锚护栏**（判据与拒文单源 = write-path.mjs 的 lineAnchorVerdict /
+ *    lineAnchorRefusal——上一笔写之后目标区落在受影响区内即拒）；
  *    阶段 2 删行形态（EDIT.md §5——约束）：省略 new_string = 删除该行/范围（有界意图）；
  * ② 内容定位：old_string = 变化区**当前内容**（单次匹配——匹配档位：逐字 → P15.11 唯一
  *    空白差异窗口 → D2/F2 模糊匹配（行级 normalize 后 ≥90% 行相等——edit-batch.mjs
@@ -35,7 +37,7 @@ import {
 // 仅在调用期使用——ESM 循环下安全（无模块求值期取值）。
 // 写盘经单一写路径点（§2.13.5）——本档不再直调 fs。
 import { appendWriteContext } from "./file.mjs"
-import { writeThroughPath, lastWriteOf, isDirty } from "./write-path.mjs"
+import { writeThroughPath, lastWriteOf, isDirty, lineAnchorVerdict, lineAnchorRefusal } from "./write-path.mjs"
 // D1/D2 落点（EDIT.md §6——edit-batch.mjs）：按行号改 + 模糊匹配纯函数。
 import { applyLineEdit, findFuzzyWindow, FUZZY_MATCH_NOTE } from "./edit-batch.mjs"
 
@@ -357,6 +359,63 @@ export function computeEditEntry(content, entry, opts = {}) {
   return { updated, editStartLine, lineShift, occurrences: entry.replace_all ? occurrences : 1, note }
 }
 
+/**
+ * §7.3 帧（R1–R4）——同档多条 `edits` 的应用顺序：行号条目先全部应用、按 `startLine` 降序
+ * （从下往上改，上方行号不被同批自己顶偏）；内容条目随后按数组序（位置无关寻址无帧问题）。
+ *
+ * **零 IO**（只看条目自身的行号）：两个通道（本地 `edit-batch` ∥ ACP 桥）调同一份排法，
+ * 各自只提供自己的 IO——抄一份组循环就是本机制要根治的形状。
+ *
+ * @returns {{ order: number[]|null, rejection: string|null }} `order` = 数组下标的应用序
+ *   （回显仍按调用序取原位）；`rejection` 非空 = R3 重叠：整批拒、零写。
+ *   `path`（可选）= 拒文里点名的目标档（条目自带 path 优先——顶层 path 不在条目上）。
+ */
+export function planEditEntries(entries, path = null) {
+  const rangeOf = (e) => [e.line ?? e.startLine, e.line ?? e.endLine]
+  const lineIdx = []
+  const contentIdx = []
+  entries.forEach((e, i) => { (hasLineParams(e) ? lineIdx : contentIdx).push(i) })
+  // R3：两条行号条目的范围在快照坐标上重叠 ⇒ 先改哪一条决定结果，模型意图在此矛盾
+  const byStart = [...lineIdx].sort((a, b) => rangeOf(entries[a])[0] - rangeOf(entries[b])[0])
+  for (let i = 1; i < byStart.length; i++) {
+    const prev = rangeOf(entries[byStart[i - 1]])
+    const cur = rangeOf(entries[byStart[i]])
+    if (cur[0] <= prev[1]) {
+      const label = entries[byStart[i]].path ?? entries[byStart[i - 1]].path ?? path ?? "file"
+      return {
+        order: null,
+        rejection:
+          `${EDIT_ABORT_PREFIX}line-number entries L${prev[0]}-L${prev[1]} and L${cur[0]}-L${cur[1]} (${label}) overlap — ` +
+          `two changes to the same region cannot both be anchored on the numbers you read; split them into separate calls`,
+      }
+    }
+  }
+  // R2：降序（同档起始行不会相等——相等即重叠，已在 R3 拒掉）
+  const desc = [...lineIdx].sort((a, b) => rangeOf(entries[b])[0] - rangeOf(entries[a])[0])
+  return { order: [...desc, ...contentIdx], rejection: null }
+}
+
+/**
+ * 按 `planEditEntries` 排出的应用序逐条 `computeEditEntry` 累积——**零 IO**。
+ * `results` 按调用序回到原位（回显顺序不变），元数据形同 `computeEditEntry` 返回。
+ */
+export function applyPlannedEntries(content, entries, order, opts = {}) {
+  let cur = content
+  const results = new Array(entries.length)
+  for (const i of order) {
+    const out = computeEditEntry(cur, entries[i], { ...opts, abortPrefix: opts.abortPrefix ?? EDIT_ABORT_PREFIX })
+    results[i] = {
+      editStartLine: out.editStartLine,
+      lineShift: out.lineShift,
+      occurrences: out.occurrences,
+      note: out.note ?? null,
+      deleted: out.deleted ?? false,
+    }
+    cur = out.updated
+  }
+  return { content: cur, results }
+}
+
 /**
  * 单形态 edit 执行体（自 file.mjs 整段迁出——模块拆分写优先纪律：逻辑体不变）——
  * file.mjs 只留工具壳与转发。
@@ -365,6 +424,15 @@ export async function runSingleEdit(args, ctx) {
   const abs = resolveInCwd(ctx, args.path)
   const raw = await readFile(abs, "utf8")
   const content = normalizeEOL(raw)
+  // 行号锚护栏（判定点写死：读盘之后、computeEditEntry 之前）：行号形才需判——内容形态是
+  // 位置无关寻址，没有可漂移的锚。判据与拒文单源 = write-path.mjs。
+  // 形态校验先于护栏：缺 endLine / 与 old_string 互斥这类错要报自己的句，不该被拒文顶掉。
+  if (hasLineParams(args)) {
+    validateEditEntry(args, { rich: true })
+    const startLine = args.line ?? args.startLine
+    const endLine = args.line ?? args.endLine
+    if (lineAnchorVerdict(abs, startLine, endLine)) throw new Error(lineAnchorRefusal(abs, startLine, endLine))
+  }
   const out = computeEditEntry(content, args, { path: args.path, absPath: abs })
   // 写回按原文行尾（joinWithEol）——normalizeEOL 先行避免 \r\n 污染 split/join
   // 单一写路径点：默认 = writeFile + 记账；端侧注入 ⇒ 编辑器径（§2.13.5）。

package/tools/execute.mjs

@@ -26,9 +26,11 @@
  */
 import { spawn } from "node:child_process"
 import { resolve } from "node:path"
-import { DESC } from "./shared.mjs"
+import { DESC, LEDGER_PARAM_DESC, PROJECT_PARAM_DESC } from "./shared.mjs"
 import { killProcessTree } from "./process-tree.mjs"
 import { nodeChildEnv } from "./node-child.mjs"
+// 过程档标记（TOOLS.md §6.28）：失败径同标（错误文本也是行内容），解析基准 = 子进程 cwd `baseDir`。
+import { markProcessDocLines } from "./process-doc-mark.mjs"
 
 const MAX_SCRIPT = 50_000
 const MAX_OUTPUT = 50_000
@@ -197,6 +199,9 @@ export const executeTool = {
         maximum: 600000,
         description: `Timeout in milliseconds (default ${DEFAULT_TIMEOUT}, max 600000)`,
       },
+      ledger: { type: "string", description: LEDGER_PARAM_DESC },
+      // 项目声明面（决策 40）：`workdir` 缺位时才被读（定位参数优先）；纯声明，不改执行目录。
+      project: { type: "string", description: PROJECT_PARAM_DESC },
     },
     required: [],
   },
@@ -231,8 +236,9 @@ export const executeTool = {
     }
 
     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
+    // §6.28 单一出口：`filter` 只滤成功输出（原口径），打标接在它的后面；解析基准 = `baseDir`
+    // （= 子进程 cwd），不是 `ctx.cwd`——`workdir` 在场时只有按子进程 cwd 才解得对上。
+    const body = ok && args.filter ? applyFilter(text, args.filter) : text
+    return markProcessDocLines(body, baseDir)
   },
 }

package/tools/file.mjs

@@ -11,12 +11,13 @@ import {
   joinWithEol,
   majorityEol,
   FFFD_WARNING,
+  LEDGER_PARAM_DESC,
 } 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 { writeThroughPath, clearDirty, clearLastWrite, lineAnchorVerdict, lineAnchorRefusal } from "./write-path.mjs";
 import { specForModel } from "../config.mjs";
 import { createHash } from "node:crypto";
 import { mkdir, readFile, stat } from "node:fs/promises";
@@ -192,6 +193,7 @@ export const writeTool = {
     properties: {
       path: { type: "string", description: "File path (relative to cwd or absolute)" },
       content: { type: "string", description: "Full content to write" },
+      ledger: { type: "string", description: LEDGER_PARAM_DESC },
     },
     required: ["path", "content"],
   },
@@ -231,7 +233,7 @@ export const editTool = {
       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.",
+        description: "Batch form — multiple edits in ONE call, atomic (any failure writes nothing; line-number entries apply first, in descending startLine order, and their ranges must not overlap — overlap refuses the whole batch; content entries then apply in array order). 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: {
@@ -245,6 +247,7 @@ export const editTool = {
           },
         },
       },
+      ledger: { type: "string", description: LEDGER_PARAM_DESC },
     },
     required: [],
   },
@@ -286,6 +289,7 @@ export const insertAfterTool = {
       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)" },
+      ledger: { type: "string", description: LEDGER_PARAM_DESC },
     },
     required: ["path", "content"],
   },
@@ -296,31 +300,16 @@ export const insertAfterTool = {
     // 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.`
-      )
-    }
+    // structure repeatedly).
+    // 2026-11-02：判据与拒文单源 = tools/write-path.mjs 的 lineAnchorVerdict /
+    // lineAnchorRefusal（与 edit 行号形同一句、同一六行表——INSERT-AFTER.md §3）。
+    // 本工具的边界 = `after_line <= startLine`（插入不读写目标行，比 edit 松一格——
+    // 边界按记账类型分，已在判据内）；after_regex 没有模型给的行号（定位在工具内按当前
+    // 盘面做）⇒ 只判到记账态那一层（dirty 面无快照 ⇒ 第 6 行），与改前同判。
+    const afterLine = Number.isInteger(args.after_line) ? args.after_line : null
+    const hit = lineAnchorVerdict(abs, afterLine, afterLine)
+    if (hit) throw new Error(lineAnchorRefusal(abs, afterLine, afterLine))
+
     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")
@@ -385,6 +374,7 @@ export const hashlineEditTool = {
       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)" },
+      ledger: { type: "string", description: LEDGER_PARAM_DESC },
     },
     required: ["path", "old_hashes", "new_content"],
   },

package/tools/git.mjs

@@ -2,7 +2,9 @@ import {
   DESC,
   truncate,
   runGit,
-  gitFailureMessage
+  gitFailureMessage,
+  LEDGER_PARAM_DESC_GIT,
+  PROJECT_PARAM_DESC,
 } from "./shared.mjs";
 import { spawnGit } from "./git-run.mjs";
 import { resolve } from "node:path";
@@ -86,10 +88,34 @@ export const gitTool = {
       create: { type: "boolean", description: "(switch) create the branch then switch (-c)" },
       dest: { type: "string", description: "(mv) destination path (file or directory)" },
       worktreeAction: { type: "string", enum: ["list", "add", "remove"], description: "(worktree) list / add (path, ref) / remove (path)" },
+      ledger: { type: "string", description: LEDGER_PARAM_DESC_GIT },
+      // 项目声明面（决策 40）：`path` ∥ `workdir` 缺位时才被读（定位参数优先）；纯声明，不改执行目录。
+      project: { type: "string", description: PROJECT_PARAM_DESC },
     },
     required: ["action"],
   },
   readonly: false,
+  /**
+   * 动作级只读分类（决策 37 · 2026-11-03 笔-账绑定批——**本钩子是单源**）。
+   * 消费面两处：`thincoder-core/agent/dispatch-gates.mjs` 的 `readonlyActionOf(tool, "git", args)`
+   * （planMode 门 ∥ 权限短路 ∥ 写门的 `git` 写型/只读判定）——三面（CLI ∥ desktop ∥ vscode）同答案。
+   * 名单与 `thincoder-vscode/src/tools/index.mjs` 原端装饰体逐条同形（该覆写随本钩子同笔删除）：
+   * 六项平铺 + 六条子动作分支。`checkpoint` 的 `list` ∥ `cat` 判只读——`checkpoint list` 有 F6 清理副作用
+   * （`lazyClearIfCommitted` 可能删除整个 checkpoint 目录），但清的是 commit 后已失去意义的过期快照 ⇒
+   * 保留只读分类免审批（`docs/core/design/CHECKPOINT.md` F6/D3 设计意图）。
+   * 缺此钩子的面回落到核名面谓词（无 `git` 分支 ⇒ false ⇒ 写型 ⇒ 要号），fail-closed，不出洞。
+   */
+  isReadonlyAction(args) {
+    if (!args || typeof args.action !== "string") return false
+    if (["diff", "status", "log", "show", "ls-remote", "blame"].includes(args.action)) return true
+    if (args.action === "checkpoint") return ["list", "cat"].includes(args.checkpointAction)
+    if (args.action === "tag") return args.tagAction === "list"
+    if (args.action === "branch") return args.branchAction === "list"
+    if (args.action === "stash") return args.stashAction === "list"
+    if (args.action === "remote") return args.remoteAction === "list"
+    if (args.action === "worktree") return args.worktreeAction === "list"
+    return false // add/rm/commit/push/fetch/pull/reset/revert/merge/cherry-pick/checkout/restore + tag/branch/stash 写操作
+  },
   async execute(args, ctx) {
     // workdir: run git in a subdirectory (monorepo / multi-repo). Shadow ctx.cwd so
     // every action + snapshotBefore + checkpoint resolves against the workdir.

package/tools/ops.mjs

@@ -7,7 +7,7 @@
  * wait_for 条件族 +`bash id:N done`。list ∥ 既有条件面零变。批 browser-async-fix（#1045）：kill id
  * 路由先 bg 后 browser（同一 id 命名空间）∥ wait_for 条件族 +`browser id:N done`。
  */
-import { DESC, resolveInCwd, truncate } from "./shared.mjs"
+import { DESC, resolveInCwd, truncate, LEDGER_PARAM_DESC } from "./shared.mjs"
 // 单一写路径点（编辑器编辑径注入缝——CORE-UNIFICATION §2.13.5）：路径操作也经它落盘
 // （默认径 = 既有 cp / rename / EXDEV 回退语义，零行为变）。
 import { writeThroughPath } from "./write-path.mjs"
@@ -26,6 +26,7 @@ export const fileOpsTool = {
       action: { type: "string", enum: ["move", "copy", "rename"], description: "move | copy | rename" },
       source: { type: "string", description: "Source path, relative to cwd or absolute" },
       dest: { type: "string", description: "Destination path" },
+      ledger: { type: "string", description: LEDGER_PARAM_DESC },
     },
     required: ["action", "source", "dest"],
   },

package/tools/patch.mjs

@@ -4,9 +4,10 @@ import {
   resolveInCwd,
   normalizeEOL,
   detectFileEol,
-  majorityEol
+  majorityEol,
+  LEDGER_PARAM_DESC
 } from "./shared.mjs";
-import { writeThroughPath, TMP_SUFFIX, markDirty } from "./write-path.mjs";
+import { writeThroughPath, TMP_SUFFIX, markDirty, clearLastWrite } from "./write-path.mjs";
 import { spawnGit } from "./git-run.mjs";
 import { mkdir, readFile, lstat, unlink } from "node:fs/promises";
 import { existsSync } from "node:fs";
@@ -175,6 +176,7 @@ export const applyPatchTool = {
     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 (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>)." },
+      ledger: { type: "string", description: LEDGER_PARAM_DESC },
     },
     required: ["patch"],
   },
@@ -234,7 +236,13 @@ export const applyPatchTool = {
     const summary = planned.map((p) => `  ${p.isNew ? "created " : "modified"} ${p.path}`).join("\n")
     // Mark every touched file dirty — insert_after must not run on stale line numbers.
     // 整批记账（dirty）= apply_patch 的批级语义（两段式全成功后一次落账——与改前逐字同）。
-    for (const p of planned) markDirty(p.abs)
+    // 2026-11-02：落 dirty 同时清写入快照——apply_patch 不记快照，留着旧 `startLine` 就是
+    // 陈旧的锚：行号锚护栏第 2 行（dirty ∧ 快照在场）会拒，而第 4 行会拿旧值判「目标区在之前
+    // ⇒ 放行」——两种结果都不该由一笔没更新快照的写来决定（EDIT-HELPERS §7.1）。
+    for (const p of planned) {
+      markDirty(p.abs)
+      clearLastWrite(p.abs)
+    }
     const syntaxChecks = await Promise.all(planned.map(async (p) => {
       const r = await autoSyntaxCheck(p.abs)
       return r ? `${p.path}:${r.replace("Syntax: ", "")}` : ""
@@ -256,6 +264,7 @@ export const deleteTool = {
     properties: {
       path: { type: "string", description: "File or empty-directory path (relative to cwd or absolute)" },
       force: { type: "boolean", description: "Allow deleting git-tracked files (default false)" },
+      ledger: { type: "string", description: LEDGER_PARAM_DESC },
     },
     required: ["path"],
   },

package/tools/process-doc-mark.mjs

@@ -0,0 +1,139 @@
+/**
+ * process-doc-mark.mjs — 工具输出里的过程档标记（单源小档；机制 = `docs/core/design/TOOLS.md` §6.28）。
+ *
+ * 依赖面说清楚：本档**不**是零依赖叶档——谓词都来自判据单源 `../declaration.mjs`，而它的静态闭包
+ * 经 `memory/file-walk.mjs` 达 `memory/schema.mjs`（`node:sqlite`）。因此端壳里静态引本档 = 把那条链拉进静态闭包；
+ * 当前端装配面本已静态可达同一链（`setup-tooltable.mjs` → 核 `agent-tools/verify.mjs` → `conventions.mjs`），
+ * 零新增风险，但别把它当零依赖档随手引。
+ *
+ * 一句话：输出里**判定得出**来源档落在索引排除集（batches 段 ∥ `_archive` 前缀）的行，
+ * 行首加 `[process doc: not a design basis]`（原行整体后随）；其余行一个字节不动。**不是门**——
+ * 不拦、不筛、不改命中集，只加可读信息。
+ *
+ * 两套判据、一份文案、一个谓词、一个 helper：
+ * - `grep` 面按命中行的**档**判（消费面直调 `isProcessDocPath`——grep 自己已有 `h.file`，本档不参与拼装）；
+ * - 命令面（`bash` 同步 ∥ `bash` 后台摘要 ∥ `execute` ∥ VSC 端 `bash`）的输出是任意文本，只能按
+ *   **行首路径 token 真解析到盘上**判（`markProcessDocLines`）——解析不到 = 判不了 = 不动输出。
+ *
+ * 判据单源 = `../declaration.mjs` 的 `isExcludedRelPath`（面① 前缀 ∪ 面⑥ 段序列）：本档零新排除名单、
+ * 零新谓词。第三参必须传 `decl.root`——`isExcludedRelPath` 内 `resolve(base, s)` 对绝对参恒等，
+ * 再由 `relative(root, …)` 换成根相对面，面① 前缀才判得住（只被面① 命中的 `_archive` 靠这一点）。
+ *
+ * 零 console 噪声：本档不调用 `console`。判据只走 `declarationForTarget` → `loadProjectDeclaration`，
+ * 后者按档缓存，只在声明档不可用 / 读不出时 warn（既有降级面，非本档新增）。
+ */
+import { existsSync } from "node:fs"
+import { isAbsolute, resolve } from "node:path"
+import { declarationForTarget, isExcludedRelPath } from "../declaration.mjs"
+
+/** 逐字文案（33 字符 · 全 ASCII · 方括号闭合）：工具输出面全英文，同一行混中英破坏「一词一物」。 */
+export const PROCESS_DOC_MARK = "[process doc: not a design basis]"
+
+/** 末尾汇总行（仅命令面）：N = 本次输出被判为过程档的行数；N = 0 不加（`grep` 面不加此形）。 */
+export const processDocSummary = (n) =>
+  `[process doc: ${n} of this output's lines come from process docs — not a design basis]`
+
+/** 行首 token 的字符帽（步骤 ①）：超过即成不了路径，该行跳过不解析。 */
+const MAX_TOKEN_CHARS = 260
+
+/**
+ * 档判据（一次调用内按档记忆：`Map<absoluteFile, boolean>`）。
+ * @param {string} absFile 档的绝对路径（grep 面 = 命中行的 `h.file`；命令面 = 盘上解析出的绝对路径）
+ * @param {Map<string, boolean>} [cache] 记忆表（缺省自建——不传就没有跳调用的记忆）
+ * @returns {boolean} 所属档在索引排除集内 ⇒ true；出辖（祖先链无 manifest）⇒ false（无档类可判）
+ */
+export function isProcessDocPath(absFile, cache) {
+  const key = String(absFile ?? "")
+  if (!key) return false
+  const memo = cache instanceof Map ? cache : new Map() // 缺省自建：一次调用内按档记忆
+  if (memo.has(key)) return memo.get(key)
+  const decl = declarationForTarget(key) // null = 出辖（场景：会话锚在无 manifest 的目录里跑检索）
+  const marked = decl ? isExcludedRelPath(key, decl, decl.root) : false
+  memo.set(key, marked)
+  return marked
+}
+
+/** 剥两侧成对引号（步骤 ①）——行首字段被引起来的输出很常见。 */
+function stripPairedQuotes(s) {
+  if (s.length < 2) return s
+  const first = s[0]
+  const last = s[s.length - 1]
+  if ((first === '"' && last === '"') || (first === "'" && last === "'")) return s.slice(1, -1)
+  return s
+}
+
+/**
+ * 行首路径 token（步骤 ①–③）。判不了 ⇒ null（调用方原样保留该行）。
+ * @param {string} line 输出行
+ * @returns {string|null}
+ */
+function headPathToken(line) {
+  const head = /^\S+/.exec(String(line ?? "").trimStart())
+  if (!head) return null // 空行 / 纯空白行
+  const raw = stripPairedQuotes(head[0])
+  if (!raw || raw.length > MAX_TOKEN_CHARS) return null
+  // ② 剥尾：内层 `grep` ∥ `rg` ∥ `findstr` 的 `path:12: text` 形与尾随冒号一并剥掉
+  const token = raw.replace(/[:\-]\d+[:\-]?$/, "").replace(/:+$/, "")
+  if (!token) return null
+  // ③ 预筛：不含 `/` `\` `.` 的字段不做盘上解析（`[stdout]:` ∥ `(exit code 0)` ∥ 纯数字过不了这一关）
+  if (!/[/\\.]/.test(token)) return null
+  return token
+}
+
+/**
+ * 盘上解析（步骤 ④）：驱动绝对形 → MSYS 形 → 相对基准 `base`，取**第一个在盘上存在**者。
+ * 三支都不存在 ⇒ null（= 判不了）。UNC（`\\server\share\…`）走驱动绝对形一支。
+ * @param {string} token 行进字段（已剥尾）
+ * @param {string} [base] 解析基准：`bash` 同步 = `ctx.cwd` ∥ 后台径 = entry 记下的 `cwd` ∥ `execute` = `baseDir`
+ * @returns {string|null}
+ */
+function resolveOnDisk(token, base) {
+  const candidates = []
+  if (/^[A-Za-z]:[\\/]/.test(token) || token.startsWith("\\\\")) {
+    candidates.push(token) // 驱动绝对形 ∥ UNC
+  } else {
+    // MSYS 形（`/c/teamcode/…`）在 win32 上 `isAbsolute` 也为真，会落成当前盘的 `/c/…`
+    // ⇒ 必须显式把首段 `^/([A-Za-z])/` 映射为 `X:/`，否则这一支恒不命中。
+    const msys = /^\/([A-Za-z])(\/.*)?$/.exec(token)
+    if (msys) candidates.push(`${msys[1].toUpperCase()}:${msys[2] ?? "/"}`)
+    else if (isAbsolute(token)) candidates.push(token) // POSIX 绝对形（`resolve` 对绝对参恒等，同一支）
+  }
+  if (base) candidates.push(resolve(String(base), token))
+  for (const c of candidates) if (existsSync(c)) return c
+  return null
+}
+
+/**
+ * 命令面打标（§6.28「命令输出面」六步，`bash` ∥ `execute` ∥ VSC 端 `bash` 共用）：
+ * 逐行取行首 token → 真解析到盘上 → 判归属 → 命中者行首加前缀（行其余部分原样）。
+ * N > 0 ⇒ 正文之后追加一行汇总；N = 0 ⇒ **原样返回入参**（一个字节不动，无空汇总行）。
+ *
+ * 纪律：不许按「看起来像路径」打标——解析不到盘上就不标（误标比不标更坏）。
+ *
+ * @param {string} text 输出文本
+ * @param {string} [base] 解析基准（见 `resolveOnDisk`）
+ * @returns {string}
+ */
+export function markProcessDocLines(text, base) {
+  const src = String(text ?? "")
+  if (!src) return src
+  const fileCache = new Map() // 档 → boolean
+  const tokenCache = new Map() // token → boolean（一次调用内按 token 记忆；不设解析上限）
+  let n = 0
+  const out = src.split("\n").map((line) => {
+    const token = headPathToken(line)
+    if (!token) return line
+    let marked = tokenCache.get(token)
+    if (marked === undefined) {
+      const abs = resolveOnDisk(token, base)
+      marked = abs ? isProcessDocPath(abs, fileCache) : false
+      tokenCache.set(token, marked)
+    }
+    if (!marked) return line
+    n += 1
+    return `${PROCESS_DOC_MARK} ${line}`
+  })
+  if (n === 0) return src
+  const body = out.join("\n")
+  return `${body}${body.endsWith("\n") ? "" : "\n"}${processDocSummary(n)}`
+}