@thincoder/core 0.10.13 → 0.11.1

package/tool-docs/subagent.md

@@ -8,17 +8,27 @@ ONE tool, NINE actions — pick by what you need:
 - action:'send': STEER a running async subagent mid-flight — id + message (a direction, e.g. "check X, don't fixate on Y"). The child consumes it at its next turn boundary as an ORDINARY user instruction (non-interrupting; its discipline is unchanged — guidance, not a deviation waiver); returns {id,
   status:'delivered', queued}. Only RUNNING async children are targetable — sync/queued/settled/unknown error clearly; if the child settles first, its report carries an 'undelivered' note.
 - action:'escalate' (飞刀): hand an implementation task to a STRONGER model from your consult models; it gets WRITE access and does the work itself, then returns a post-op report (what changed, why, verification). Escalate EARLY, when the task calls for stronger hands (complex refactors, intractable
-  bugs, intricate algorithms — or beyond your comfortable ability). Not available in engineering mode (implementation goes through eng-coder). Default-async at depth 0: ack {id, role:'escalate', status:'running'} returns immediately; the report arrives automatically with its mutations merged into
+  bugs, intricate algorithms — or beyond your comfortable ability). Not available in engineering mode (implementation goes through eng-coder).
+
+  Default-async at depth 0: ack {id, role:'escalate', status:'running'} returns immediately; the report arrives automatically with its mutations merged into
   your bookkeeping (pooled with the other role-domain spawns).
 - action:'cancel': STOP ONE background subagent — the id from the spawn return is REQUIRED (a blanket cancel is unsupported; Ctrl+C stops everything). Running aborts immediately ({id, status:'cancelled'}); queued is removed ({id, status:'cancelled', was:'queued'}; later positions shift). Other
-  children and the session keep running. Cancel is a last resort: verify alarming signals with reliable checks (git/node — not guesses) first, and prefer scoped recovery — a running child's in-flight work dies with it, partial changes stay unmerged and unaudited. Background advisor reviews cancel
+  children and the session keep running. Cancel is a last resort: verify alarming signals with reliable checks (git/node — not guesses) first, and prefer scoped recovery — a running child's in-flight work dies with it, partial changes stay unmerged and unaudited.
+
+  Background advisor reviews cancel
   the same way (pass the review id — no token is issued for a cancelled review).
 - action:'consume-design' (engineering mode, parent side): chain-terminal token consumption — after the delivery is verified and the chain closes out, consume this design's token slot. Selectors — pass exactly ONE: designId (a single slot; optional for a single-design session), designIds (an
-  explicit non-empty list), expired:true (every expired slot), or olderThanDays:N (every slot older than N days). A consumed slot mechanically rejects further spawns for the same designId — new work (deviation fixes included) needs a fresh design review and token. Idempotent
+  explicit non-empty list), expired:true (every expired slot), or olderThanDays:N (every slot older than N days). A consumed slot mechanically rejects further spawns for the same designId — new work (deviation fixes included) needs a fresh design review and token.
+
+  Idempotent
   (unknown/already-consumed = a no-op notice); batch calls report per-slot lines + a `consumed N` count line. Do NOT call while the chain is still open — fix rounds reuse the same slot.
 - action:'design-slots' (engineering mode, parent side): READ-ONLY inventory of this session's approved design token slots — one line per slot (designId, live|expired, ageDays, expiresAt, batch, designToken), oldest first, ending with a total/live/expired count line. Nothing is written. Use it to
   see what still holds a slot before consuming; the expired / olderThanDays selectors act on the same set.
-  Every row carries its designToken value (expired ones included — status marks them; a malformed record shows designToken=—). Pass designId to filter to a single slot (trimmed exact match; unknown = refused with the held id list; empty string = no filter). Take designId + designToken verbatim onto
+  Every row carries its designToken value (expired ones included — status marks them; a malformed record shows designToken=—).
+
+  Pass designId to filter to a single slot (trimmed exact match; unknown = refused with the held id list; empty string = no filter).
+
+  Take designId + designToken verbatim onto
   the eng-coder spawn — the gate checks exact equality.
 - action:'panel': DIAGNOSE + fix the subagent panel (the collapsible blocks the user sees; headless/VS Code degrade to a 'no panel' pool view). view (default): the live blocks (key, role, status: running|done|awaitingDigest) exactly as the user sees them — digested-stuck entries carry digested:true.
   freeze: pass a digested-stuck block key (e.g. 'eng-coder#9' — {action:'panel', freeze:'role#N'}) to reclaim it into the conversation — passes ONLY for awaitingDigest blocks with no live pool entry and no pending report (a still-pending report would break the digestion order — refused).
@@ -31,34 +41,61 @@ Available roles (exposed per mode; the role is REQUIRED for action:'spawn' — a
 - coder — full implementation; the parent's complete read/write/execute toolset plus verify and advisor self-review. Its report carries a delivery table, one row per requirement (Done / Simplified / Not done — no deferred column). Normal mode: may optionally carry `batchDoc` — binds this spawn's §5
   record-write channel (unbound ⇒ the main agent records §5 on its behalf); when provided the path must resolve to a readable file.
 - eng-coder — engineering mode only (replaces coder): same toolset plus the design-driven methodology overlay; its delivery protocol (implementation → audit → self-fix → advisor re-review → converged delivery) runs fully inside the child. REQUIRES a valid designToken from a passed
-  advisor(type='design') review — pass the exact value from that review, or copy it verbatim from the action:'design-slots' row (the text after designToken=): missing or mismatched = the spawn is refused, and an expired token is refused with expired named (its reply also echoes a designId — pass it:
-  required to pick between concurrent designs, optional for one; echo it back in the delivery report). REQUIRES a batchDoc — the batch record path, the task book this spawn implements (refused without it or when it does not resolve to a readable file).
+  advisor(type='design') review — pass the exact value from that review, or copy it verbatim from the action:'design-slots' row (the text after designToken=): missing or mismatched = the spawn is refused,
+
+  and an expired token is refused with expired named (its reply also echoes a designId — pass it:
+  required to pick between concurrent designs, optional for one;
+
+  echo it back in the delivery report). REQUIRES a batchDoc — the batch record path, the task book this spawn implements (refused without it, when it does not resolve to a readable file, or when that record already has an in-flight spawn).
+
+  One batch record serves one concurrent spawn: wait for the occupant to settle, or cancel it.
 - eng-designer — engineering mode only: the SOLE author of the design documents and of the batch record's design section (requirement docs stay with the main agent). Writes no implementation code, does not edit prompts, does not fire reviews, needs NO designToken. Surveys on its own; may only spawn
   read-only explore children (sync, ≤6 per batch). REQUIRES a batchDoc (same gate as eng-coder).
+- tester — BOTH modes: the readings seat. It runs the verification commands the task book puts in `goal` and hands the readings back as they stand —
+  no verdict, no fix, no document of any kind.
+
+  Tool face = the read-only tools plus `execute` / `bash` (dependency installs, compiles and fixtures included), minus `verify` (a verdict tool).
+
+  Run only, never change is a role contract, not a sandbox — `bash` can write, so a tester that edits anything is treated by the parent as a defect.
+
+Task book (non-engineering roles: explore / plan / coder / tester): four core structured parameters — goal (goal & why), knownFacts (the facts you already verified), acceptance (machine-verifiable criteria), reportFormat (delivery-report format)
 
-Task book (normal-mode roles: explore / plan / coder): four core structured parameters — goal (goal & why), knownFacts (the facts you already verified), acceptance (machine-verifiable criteria), reportFormat (delivery-report format)
 — plus scope (scope & forbidden scope — what to read / what not to touch).
 All five are required: a missing, blank or non-string value is refused with the parameter named.
 A free-text task is an optional supplement, never the whole brief.
+
 Engineering roles (eng-coder / eng-designer) take their task book from the batch record: batchDoc (the record path) and round (initial|fix), plus files / dependsOn for scheduling; the child reads §2 of that record itself — no other task text is passed.
+
 An eng-coder spawn also carries designToken — the write credential (the exact value from the review, or copied verbatim from the action:'design-slots' row, the text after designToken=), and designId when several designs are open: missing or mismatched = the spawn is refused.
 
+A record carries one concurrent spawn at a time: a second spawn on a record still in flight is refused, naming the occupant — sequential hand-offs (design → implementation → fix round) pass, because the previous spawn has settled first.
+
 Pass one parameter per field — contents only (the runtime adds the labels):
 subagent(role="eng-coder", round="initial", batchDoc="<batch record>", designToken="…", files=[…])
 subagent(role="explore", goal="…", knownFacts="…", scope="…", acceptance="…", reportFormat="…")
 
-Mode filtering: normal mode exposes explore/plan/coder; engineering mode exposes explore/eng-designer/eng-coder — off-mode roles are refused mechanically (enums filtered at assembly; the spawn gate re-checks).
+Mode filtering: normal mode exposes explore/plan/coder/tester (eng-coder and eng-designer are refused); engineering mode exposes explore/eng-designer/eng-coder/tester (plan and coder are refused — plan is a normal-mode role, coder is replaced by eng-coder; tester is dispatchable in both modes).
+
+The role enum is filtered per mode at assembly, and the spawn gate refuses out-of-mode roles mechanically.
 
-Async spawn: top-level spawns are async by default — never pass async:false at depth 0 (the spawn returns {id, status:"running"} immediately; the report arrives automatically; if your next step needs it, end the turn and let the digest deliver it — do not poll; the explicit async:false is a
-mechanism parameter, not for model use). Inside subagents (depth>0) spawns are always synchronous. Async spawns are pooled per role domain — 4 concurrent eng-coders plus 4 concurrent other-role spawns by default (agent.poolLimits overrides both); a full domain queues further spawns with a position
+Async spawn: top-level spawns are async by default — never pass async:false at depth 0 (the spawn returns {id, status:"running"} immediately; the report arrives automatically; if your next step needs it, end the turn and let the digest deliver it — do not poll;
+
+  the explicit async:false is a
+mechanism parameter, not for model use). Inside subagents (depth>0) spawns are always synchronous.
+
+  Async spawns are pooled per role domain — 4 concurrent eng-coders plus 4 concurrent other-role spawns by default (agent.poolLimits overrides both); a full domain queues further spawns with a position
 while the other keeps starting.
 
-Task scheduling: declare files (the file paths this task will modify) and dependsOn (ids from prior async returns whose outcome this task needs) to let the scheduler order your spawns. Overlapping-file tasks serialize and dependents start in order: a conflicting/dependent spawn queues
-(position/reason) and auto-starts when the conflict clears / the dependency settles (cancel to drop). A cancelled/failed dependency leaves it queued marked "dependency cancelled" until you decide (AUTO sessions auto-start). Unknown ids error; a consumed id counts as satisfied. Omit both for a plain
+Task scheduling: declare files (the file paths this task will modify) and dependsOn (ids from prior async returns whose outcome this task needs) to let the scheduler order your spawns.
+
+  Overlapping-file tasks serialize and dependents start in order: a conflicting/dependent spawn queues
+(position/reason) and auto-starts when the conflict clears / the dependency settles (cancel to drop).
+
+  A cancelled/failed dependency leaves it queued marked "dependency cancelled" until you decide (AUTO sessions auto-start). Unknown ids error; a consumed id counts as satisfied. Omit both for a plain
 immediate spawn (no scheduler involvement).
 
 Writing the prompt:
 - The child starts with zero context — brief it like a colleague who just walked in: goal, what you already know, the specifics.
 - Put exact paths and commands in — do not make it search for what you already know.
-- Do not delegate understanding: resolve the paths/line numbers the task hinges on first.
+- Do not delegate understanding: resolve the paths and the symbols the task hinges on first.
 - Once it runs, leave that scope to it — don't redo its searches in parallel or finish manually midway.

package/tool-docs/task.md

@@ -1,7 +1,9 @@
 Plan and track a task list for complex multi-step work.
 Each call replaces the entire list.
 Keep exactly one item in_progress at a time; mark items done as you complete them; never mark done if tests fail or work is partial.
+
 Statuses: pending | in_progress | done — synonyms (completed/finished/complete, todo/open/waiting, active/running/working, …) are accepted and normalized with a warning.
 IMPORTANT: title is required and must be a non-empty string — items with empty titles are silently dropped.
+
 For cross-session / project-level tracking, use `/ledger`.
 Returns the updated task list (or the new item's ID on add).

package/tool-docs/team_ledger.md

@@ -5,5 +5,5 @@
 - count：同 query 参数，出 total。
 - add：title 必填（≤200）∥ detail（≤4000）∥ owner（缺省 = 自己）——status 恒 待讨论。
 - update：id 必填；title / detail / owner / status 至少一件；status = 迁移表合法后继（待讨论→待设计 ∥ 待设计→在途 ∥ 在途→待核销 ∥ 待核销→已核销 ∥ 未归档→已废弃）；已归档（已核销 / 已废弃）⇒ 拒；仓不可改。
-- close：id + status（已核销 ∥ 已废弃）——已核销：勾销（待核销）/ 追认核销（待讨论 ∥ 待设计，须正文非空）；已废弃 = 撤回（任意未归档态）。
+- close：id + status（已核销 ∥ 已废弃）——已核销：勾销（只自 待核销；其余现态 400，出路 = 先 PATCH 推进到 待核销）；已废弃 = 撤回（任意未归档态）。
 - 登录态门：未登录 ⇒ 明示「未登录」且零请求；401（token 失效）⇒ 「登录已失效——请重新登录」；不可达 ⇒ 「服务器不可达」（零离线缓存，重试不落旧值）。

package/tool-docs/timer.md

@@ -1,13 +1,20 @@
 Set a timer before you start analyzing code.
 When the timer fires, a system reminder will be injected suggesting you try running code or adding debug logs.
 Use this to enforce a thinking budget: you get N seconds to reason, then the timer reminds you to act.
+
 Beyond a one-shot countdown, three schedule forms are available, one per call (`seconds`, `at`, `every` and `daily` are mutually exclusive — passing more than one is a validation error):
+
 `at` takes a local clock time such as "2026-10-13T09:00" and fires once at that moment — a time already past fires immediately.
 `every` takes a fixed interval in seconds (minimum 60): the first reminder comes N seconds after setting, then every N seconds, until cancelled.
+
 `daily` takes a local "HH:MM" and repeats every day at that time (a time already past today fires tomorrow), until cancelled.
 All times are local to the host.
+
 `cancel` takes the id from the set confirmation and stops that timer; `list` shows every pending timer with its next due time. Repeating timers occupy one pending slot each until cancelled.
 Returns the set confirmation — the reminder fires at the deadline.
+
 Delivery: when the session is idle it is delivered on the spot and starts a turn — the idle wake is available on the CLI / VSC / desktop foregrounds and suspension windows (headless is structurally unsupported).
+
 A user turn gets no delivery: while a session turn is running, an expired timer waits for the next delivery round (suspension window / idle latch); other paths keep the step-boundary behavior.
+
 A pending timer survives across runs; at most 8 timers may be pending at once, and further timer calls are rejected until some expire.

package/tool-docs/verify.md

@@ -1 +1,13 @@
-Generic pre-completion verification gate — language/framework/project agnostic. verify does NOT run any test/verification command for you and does NOT require a test per change. You DECLARE your verification status via the verification argument ({ status: 'passed' | 'failed' | 'skipped', command?, summary?, basis? } — effects per parameter): the declaration is self-reported evidence — verify only mechanically gates on it ('passed' → allowed; 'failed' → blocked; 'skipped' → allowed but needs a reason). 'basis' (optional) is the 'what it stands on' dimension of the declaration — a judgment source, a read file:line coordinate, or an explicit 'unverified' (declaration-only: no format is enforced or machine-checked); a passed / skipped declaration with no basis gets one advisory hint line in the report — never blocking and never changing the gate — while the failed face gets no basis hint (already blocked). Whether/how to verify is described in natural language in the project's AGENTS.md and is decided + executed by you. The report also carries the changed files (git diff), an advisory node --check hint on changed .js/.mjs (not gating), the task list, and a self-review checklist. Call this BEFORE declaring a coding task complete — do not say 'done' until verify passes.
+Generic pre-completion verification gate — language/framework/project agnostic. verify does NOT run any test/verification command for you and does NOT require a test per change.
+
+You DECLARE your verification status via the verification argument ({ status: 'passed' | 'failed' | 'skipped', command?, summary?, basis? } — effects per parameter): the declaration is self-reported evidence —
+
+verify only mechanically gates on it ('passed' → allowed; 'failed' → blocked; 'skipped' → allowed but needs a reason).
+
+'basis' (optional) is the 'what it stands on' dimension of the declaration — a judgment source, the exact words you read at their path, or an explicit 'unverified' (declaration-only: no format is enforced or machine-checked);
+
+a passed / skipped declaration with no basis gets one advisory hint line in the report — never blocking and never changing the gate — while the failed face gets no basis hint (already blocked).
+
+Whether/how to verify is described in natural language in the project's AGENTS.md and is decided + executed by you. The report also carries the changed files (git diff), an advisory node --check hint on changed .js/.mjs (not gating), the task list, and a self-review checklist.
+
+Call this BEFORE declaring a coding task complete — do not say 'done' until verify passes.

package/tool-docs/websearch.md

@@ -1,4 +1,6 @@
-Search the web (DeepSeek Search when a DeepSeek provider is configured; otherwise Tavily with a key, else Bing). Returns result titles, URLs, and snippets — DeepSeek results also carry a date · authority (0–4) · rerank (0–3) line and a long summary. Use for looking up current information, docs, error messages.
+Search the web (DeepSeek Search when a DeepSeek provider is configured; otherwise Tavily with a key, else Bing). Returns result titles, URLs, and snippets — DeepSeek results also carry a date · authority (0–4) · rerank (0–3) line and a long summary.
+
+Use for looking up current information, docs, error messages.
 
 Parameters:
 - query (required): Search query

package/tool-docs/write.md

@@ -9,3 +9,5 @@ Notes:
 - Returns `Wrote N chars to <path>` + git diff + syntax-check note.
 - This overwrites the entire file — use `edit` for targeted changes
 - The file is atomic: it either writes completely or fails
+
+**`ledger`** — the in-flight ledger row this call serves: `"#N"` or `"N"`. In engineering mode the parent agent must pass it — a call that does not say which row it serves is refused.

package/tools/bash.mjs

@@ -3,12 +3,16 @@ import {
   sanitizeOutput,
   truncate,
   makeDecoder,
-  BASH_TIMEOUT_MS,
+   BASH_TIMEOUT_MS,
+  LEDGER_PARAM_DESC,
+  PROJECT_PARAM_DESC,
 } from "./shared.mjs";
 import { spawn } from "node:child_process";
 // 树杀单源（台账 #208② · TOOLS.md §6.14 落位表行 2）：本地副本删除——改用 `./process-tree.mjs`
 // （行为逐字同：win32 `taskkill /T /F` · POSIX 组杀 + 直杀兜底）。
 import { killProcessTree } from "./process-tree.mjs";
+// 过程档标记（TOOLS.md §6.28）：输出里行首路径 token 真解析到盘上的过程档行 ⇒ 行首前缀 + 末尾汇总行。
+import { markProcessDocLines } from "./process-doc-mark.mjs";
 import { resolveShellIdentity } from "../shell-identity.mjs";
 
 /** Maximum buffer size per stream (stdout / stderr) before truncation */
@@ -247,6 +251,9 @@ export const bashTool = {
       timeout: { type: "number", description: `Timeout in ms (default ${BASH_TIMEOUT_MS} for synchronous runs; background runs have no default — an explicit timeout still applies)` },
       async: { type: "boolean", description: "Run in the background (default false): returns an ack at once (bash#<id>, log path) and the result arrives as a digest when the process exits. Depth-0 only." },
       filter: { type: "string", description: "Optional: only return output lines matching this regex (case-insensitive; synchronous runs only)" },
+      ledger: { type: "string", description: LEDGER_PARAM_DESC },
+      // 项目声明面（决策 40）：`bash` 没有定位参数 ⇒ 判据点只能靠声明；纯声明，命令仍在会话 cwd 执行。
+      project: { type: "string", description: PROJECT_PARAM_DESC },
     },
     required: ["command"],
   },
@@ -288,7 +295,10 @@ export const bashTool = {
       shell: ctx.agent?.config?.shell ?? null,
     })
     const filtered = args.filter ? applyLineFilter(result, args.filter) : result
-    const body = guard ? `${guard.notice}\n\n${filtered}` : filtered
+    // §6.28：顺序写死 = **过滤 → 打标 → 汇总 → 外包装**（filter 才照旧匹配原始行，前缀不吃
+    // 过滤命中；`guard.notice` ∥ `hint` 包在标之外）。解析基准 = 子进程 cwd（同步径 = `ctx.cwd`）。
+    const marked = markProcessDocLines(filtered, ctx.cwd)
+    const body = guard ? `${guard.notice}\n\n${marked}` : marked
     return hint ? `${hint}\n${body}` : body
   },
 }

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"],
   },