dsh-line-patch 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kingofpowers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,167 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-line-patch
+
+给 DSH 的内置文件工具加一层「锚点补丁」：`read` / `write` / `edit` 的结果末尾多一行 `file_hash`，新增一个 `patch` 工具按「整文件 hash + 行号 + 边界行内容」改文件。不新增读工具，模型仍然用它已经熟悉的 `read`。
+
+## 为什么需要它
+
+内置 `edit` 用字面量 `old_string` 定位，**定位费按输出 token 计价**。本机 308 个会话、891 次 `edit` 的实测数据：
+
+| 指标 | 数值 |
+|---|---|
+| `old_string` 累计 | 285,035 字符 ≈ **81,439 输出 token** |
+| 占 `new_string` 的比例 | **36%** |
+| 引文 >30 行的调用 | 4.6% |
+| `edit` 失败构成 | 未先读 2.9% / 文件已变 2.8% / **原文找不到仅 0.7%** |
+
+也就是说：抄原文这件事吃掉了三成输出，而它换来的定位可靠性只解决 0.7% 的失败。
+
+同时它和 DSH 内置的版本守卫**互补而非重复**：
+
+| 场景 | 内置 stat 版本（本机 provider：`dev:ino:size:mtimeNs:ctimeNs`） | 本插件 file_hash |
+|---|---|---|
+| 内容改了 | 拒绝 ✅ | 拒绝 ✅ |
+| 版本只含 mtime/size 的 provider 上，内容改了而 mtime/size 未变（`cp -p`、备份还原） | **漏判 ❌** | 拒绝 ✅ |
+| 内容没变只是被 touch / 重新构建 | **误伤 ❌**（版本变了） | 放行 ✅（内容一致） |
+
+本机 provider 的版本含 `ctimeNs`，而写文件必然改 ctime，所以「改了内容却版本不变」只会在粗时间戳文件系统或自定义 provider 上出现；`file_hash` 的价值是**不依赖 provider 的版本语义**：内容一样就放行，内容不一样就拒绝。它也正好是 `patch` 能在不重读的前提下自纠的依据（见「失败怎么读」）。
+
+### 为什么不是逐行 hash
+
+0.2.x 给每行加了 `行号/4位hash` 标记。对 agentVillage 那次 2,794 次请求的长会话逐行核算后：
+
+| 项 | 一次性 token | 折算（含缓存命中与上下文驻留） |
+|---|---|---|
+| 读取侧逐行锚点 (+2.55 tok/行，读取量 +9.6%) | +31,264 | **+4.15M 输入当量** |
+| `patch` 省下 `old_string` | −14,004 | −3.80M |
+
+逐行锚点的读税**几乎正好吃掉**补丁的全部收益，而且它在安全性上是冗余的：`patch` 第一步校验整文件 hash，hash 对得上就说明文件与读取时一致（6 位前缀足以覆盖日常改动，概率数字见「已知限制」）。所以 0.3.0 只保留**整文件 6 位 hash**，边界改用**行内内容切片**（前 16 / 末 16 字符），模型照抄即可，读取侧零额外标记。
+
+## 安装
+
+```bash
+dsh plugin --profile desktop add /path/to/dsh-line-patch
+```
+
+改完 `lib/` 后需要重新加载：touch 一下 `~/.dsh/profiles/desktop/cordis.patch.yml` 触发 HMR，或重启宿主。
+
+## 用法
+
+`read` / `write` / `edit` 的结果末尾会多出一行 `file_hash: xxxxxx`（6 位十六进制）：
+
+```text
+read { file_path: "app.py" }
+→ 1: import os
+  2: def main():
+  3:     return 0
+  file_hash: 9f2c1a
+```
+
+然后直接用它改：
+
+```text
+patch {
+  file_path: "app.py",
+  file_hash: "9f2c1a",
+  line_start: 2, start_anchor: "def main():",
+  line_end: 3,   end_anchor: "return 0",
+  replace: "def run():\n    return 1"
+}
+→ patched app.py: lines 2-3 replaced (line shift +0).
+  file_hash: d119fa
+```
+
+- `file_hash` 取自**最近一次** `read`/`write`/`edit` 该文件结果末尾那行，或上一次 `patch` 结果里回的那行；三处都可以连续接龙。
+- `start_anchor` = 起始行的前 16 个字符，`end_anchor` = 结束行的末 16 个字符，**抄 read 结果里 `N: ` 前缀之后的那段文字**（前缀本身不是锚点的一部分）；行短于 16 字符时整行就是锚点。
+- `start_anchor` 是否带缩进决定比较方式：带了按缩进严格比（`if (err) {` ≠ `    if (err) {`，挡「层级看错、行号差一行」）；不带就与折叠空白后的行比较。内部空白与行尾空白始终折叠。**建议总是连缩进一起抄。**
+- `end_anchor` 是行尾切片，前后空白都折叠后按后缀比较（行尾的空白字符不算内容）。
+- 空白行用空字符串 `""` 作锚点；缩进超过 16 列的行，前 16 字符全是空白，工具会提示改从第一个非空白字符开始抄。
+- 单行修改（`line_start == line_end`）两个锚点落在同一行：`start_anchor` 按前缀比，`end_anchor` 允许后缀或前缀。
+- 锚点必须抄满（16 字符，或整行），只抄前几个字符会被 `ANCHOR_TOO_SHORT` 拒绝。
+- 若 16 字符锚点同时命中多行（例如两行都以 `const value = co` 开头），工具会以 `ANCHOR_AMBIGUOUS` 拒绝，并给出**已保证唯一的更长锚点**（可能是整行）——照它再发一次即可，不必重读。start 和 end 各有一个歧义时，各需要一次重发。
+- `replace: ""` 删除该行区间；`line_shift` 给出位移，连续修改不必整段重读。
+- CRLF 文件按原风格写回；末行无换行符的状态保持。
+
+## 失败怎么读
+
+| 错误 | 含义 | 模型该做什么 |
+|---|---|---|
+| `file_hash mismatch` | 文件真被改了 | **重读**（不可省） |
+| `RANGE_INVALID` | 行号超出文件范围 | 改行号重试，**不要重读** |
+| `ANCHOR_TOO_SHORT` | 锚点没抄满，或整段是空白 | 按错误给出的范围重抄，**不要重读** |
+| `ANCHOR_AMBIGUOUS` | 16 字符锚点命中多行 | 照错误给出的更长锚点重发，**不要重读** |
+| `LINE_ANCHOR_MISMATCH` | 文件没变，但该行不是你说的内容 | 错误里会回显该行**真正的锚点**；改锚点或行号重试，**不要重读** |
+| `BAD_ARGUMENT` | 行号不是整数、`replace` 不是字符串、或 `file_hash` 不是 6 位小写十六进制 | 修正参数后重试；若从未见过 `file_hash` 行，说明注解没生效，改用 `edit`/`write` |
+
+只有 `file_hash mismatch` 需要重读；其余错误都在「文件没变」的前提下发生，一轮自纠即可——这正是「一次额外往返 ≈ 一整轮上下文」的价值所在。
+
+## 锚点核实（每轮自动）
+
+每次 `read` 都会把「文件 hash + 版本」登记下来，之后每次模型请求前（`agent/request`）复核一次，只覆盖**最近 3 个用户回合**内的文件：
+
+```
+stat 预筛（微秒级，不读文件）
+├─ 版本没变            → 什么都不做
+└─ 版本变了 → 算 file_hash
+   ├─ 内容相同（touch / 重新构建） → 只补发 fs/observed 刷新策略底账，上下文零改动
+   └─ 内容真变了                    → 把当初那条 read 结果原地替换成「已失效 + 新旧 hash + 请重读」
+```
+
+第二行是关键：内置的 stat 版本守卫会把「内容没变但 mtime 变了」误判为外部修改，这里用内容 hash 纠正它，模型不必因为一次 rebuild 就重读整个文件。
+
+## 实现要点
+
+- 结果标注走宿主全局 waterfall **`tools/post-execute`**：监听 `read`/`write`/`edit`，把 hash 行**并入最后一个 text block**（不新增 block，否则会打断 `dsh-context-archive` 这类要求单 block 的注解插件）；不改写工具本身，也不需要覆盖同名工具（宿主不允许重名注册）。
+- cordis 的 `waterfall` 里 `next()` **不收参数**，最外层监听器的返回值才是宿主应用的结果，所以监听器是 `const d = await next(); return { ...d, content: ... }`。
+- 追加 hash 时插件会按路径**再读一次文件**（页面缓存热），并比对工具自己广播的 `fs/observed` 版本：版本在「工具读取」与「插件复核」之间变过就**不标注**，避免把模型没看过的字节的 hash 交给它。
+- `patch` 的读取与写入走 `ctx.fs`，不直接碰 `node:fs`，沙箱与远端后端仍然有效；相对路径按会话工作目录解析（与内置 fs 工具一致）。
+- 写入复刻内置 `write` 的 intent 舞蹈：`fs/write-intent` waterfall 取意图 → `writeText(intent)` → `emit('fs/observed')`。**裸调 `writeText` 会静默绕过读后写门禁与版本 CAS**。
+
+## 从 0.2.x 升级
+
+0.3.0 是**破坏性改版**：`read_hash` 与 `patch_hash` 两个工具都已删除。
+
+| 0.2.x | 0.3.0 |
+|---|---|
+| `read_hash` 输出 `1/f3c2: 内容` + `file_hash`（16 位） | 用内置 `read`；结果末尾多一行 `file_hash: xxxxxx`（6 位） |
+| `write` / `edit` 不返回 hash | 两者的结果都追加 `file_hash` |
+| `patch_hash` 工具 | `patch` 工具（`file_hash` + `line_start` + `start_anchor` + `line_end` + `end_anchor` + `replace`） |
+| `hash_start` / `hash_end` | `start_anchor` / `end_anchor`（16 字符内容切片） |
+| `total_lines` | 已移除 |
+
+另外，0.3.0 新增了 `engines.dsh: ">=0.2.1-rc.1 <0.3.0"`。这不只是元数据：声明了 `engines.dsh` 之后，插件管理器只按这一条判断，`peerDependencies` 不再兜底——装到范围外的宿主上会被直接拒绝。
+
+## 已验证
+
+0.2.x 在真实宿主上验证过替换、行位移、过期 `file_hash`、`replace: ""` 与 `replaceIfVersion` intent；0.3.0 的 hash 标注、锚点匹配、空白宽容、缩进严格性、短行/空行、EOF/BOF、错误分流由离线测试覆盖。
+
+离线测试：`npm test` — 86 个用例（核心逻辑 55 + 工具胶水 23 + 锚点核实 8），全部通过。测试桩严格按 cordis waterfall 语义实现（`next()` 不收参数、外层返回值即结果），并断言链路被继续、下游决策被组合、注解落在单个 text block 内。
+
+0.3.0 **尚未在真实宿主上做端到端验证**：`tools/post-execute` 的行为是按宿主源码（`dsh-tools` 0.2.1-rc.5）核对的，首次装进 desktop profile 时应当先跑一遍 `read` → `patch`。
+
+## 尚未实现
+
+- `presentCall` / `presentResult` 的 diff 卡片（目前是纯文本渲染）。
+- 只核对「本会话登记过的、3 个用户回合内」的文件；更早的锚点按设计丢弃，不做长期追踪。
+- **无法删除内置 `edit`**：插件不能注销或覆盖已注册的全局工具，所以 `edit` 会继续存在；`patch` 只是新增的另一个选择。
+- 沙箱策略：内置 `write` 会把 `sandbox.resolvePolicy('write', …)` 的结果传给 `writeText`，本插件没有传（沿用 0.2.x 的行为），在「会话级策略严于部署默认」的部署里可能被当成默认策略放行。这是既有问题，未在本次范围内修。
+
+## 已知限制
+
+- 单文件 5 MB 上限：超过上限的文件不标注 hash（模型只会看到「没有 `file_hash` 行」），`patch` 也会拒绝；此时请用 `edit`/`write`。
+- **6 位 hash 是「文件是否变过」的检测器，不是防篡改凭证**。它挡的是没人针对你的改动（并发写、格式化、构建、别人保存）：随机撞车 1/1600 万，可忽略。能写这个文件的人本来也不需要骗过它——那种场景靠 provider 的版本 CAS（含 ctime）与备份，不在这层。需要更长的检测位可调 `FILE_HASH_CHARS`。
+- **锚点只看边界行，且只看 16+16 个字符**。两类行仍无法靠内容区分，只能靠行号：
+  1. 整行内容完全相同的行（多个孤立的 `}`、多个空行、重复的 `export function `）；
+  2. 前 16 字符与末 16 字符都相同、只有中间不同的行——这类现在会被 `ANCHOR_AMBIGUOUS` 拦下并给出更长锚点，除非整行本身就重复。
+
+  整文件 hash 对这两种情况同样无能为力（它只证明「文件没变」）。带缩进一起抄能把「只差缩进」的那类行分开（缩进 ≥16 列的行例外，见上文）。
+- 追加 hash 依赖宿主提供 `tools/post-execute`；宿主没有这个 waterfall 时 `read` 不带 hash，`patch` 也就无法使用（不会静默改错）。
+- 「版本守卫」只在 provider 广播 `fs/observed` 且带版本时生效；不广播的 provider 上插件会直接标注（此时只剩 `patch` 自己的内容 hash 校验）。
+- **带 hash 的 `read` 结果在 Web UI 里会退化成通用文本卡片**（代码高亮/行号卡片需要结果文本以 `</content>` 结尾，追加的一行破坏了该判定）。只影响显示，不影响模型看到的文本。
+- **PTC（`run_code`）模式拿不到这个 hash**：程序侧只收到工具的 `{ isError, value }`，而内置 `read` 的 value schema（`additionalProperties: false`）里没有 hash 字段，插件无法追加。PTC 会话里请直接用 `edit`/`write`。
+- 若文件在「工具读取」与「插件复核」之间被改，插件不标注 hash（见实现要点）；更窄的窗口（插件 stat 之后、写入之前）仍由 provider 版本 CAS 兜底。
+- `fs/write-intent` 不可用时退化为自行构造的 `replaceIfVersion`；再被 provider 忽略时该次写入没有 CAS 保护。
+- 若 `@deepseek-ai/dsh-tools` 无法解析，`defineTool` 退化为恒等函数：工具仍可用，但参数校验交给插件自己（核心逻辑里仍有整数/类型/哈希格式校验）。
+
+## 许可
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# Anchored line-range editing: annotates read/write/edit results with a file hash and adds the patch tool.
+- insert:
+    - id: line-patch
+      name: dsh-line-patch

package/lib/core.js

@@ -0,0 +1,475 @@
+/**
+ * dsh-line-patch — pure anchoring logic.
+ *
+ * No I/O and no host API lives here: every function takes text in and returns
+ * text out, so the whole editing contract is unit-testable without a Harness.
+ *
+ * The anchors a model copies are *content* slices, not hashes: the first and
+ * last characters of the boundary lines are visible in a normal read, so
+ * nothing has to be recomputed to write them back.
+ */
+import { createHash } from 'node:crypto'
+
+/** Characters kept from a boundary line — enough to identify it, cheap to copy. */
+export const ANCHOR_CHARS = 16
+
+/** Characters kept from the whole-file sha256 — enough to spot a changed file. */
+export const FILE_HASH_CHARS = 6
+
+/**
+ * The hash shown underneath a read/write/edit result.
+ * @param {string|Buffer} content - raw file content.
+ * @returns {string} a 6-character sha256 prefix.
+ */
+export function fileHash(content) {
+  return createHash('sha256').update(content).digest('hex').slice(0, FILE_HASH_CHARS)
+}
+
+/**
+ * Detect the line ending a file is written in so replacements keep it.
+ * @param {string} content - the file text.
+ * @returns {string} '\r\n' or '\n'.
+ */
+export function detectEol(content) {
+  return content.includes('\r\n') ? '\r\n' : '\n'
+}
+
+/**
+ * Split text into lines while keeping each line's own ending.
+ *
+ * Rejoining the result must reproduce the input byte for byte; a final line
+ * without a newline therefore stays without one.
+ * @param {string} content - the file text.
+ * @returns {string[]} lines, each ending in '\n' except possibly the last.
+ */
+export function splitKeepEnds(content) {
+  const out = []
+  let start = 0
+  while (start < content.length) {
+    const nl = content.indexOf('\n', start)
+    if (nl < 0) {
+      out.push(content.slice(start))
+      break
+    }
+    out.push(content.slice(start, nl + 1))
+    start = nl + 1
+  }
+  return out
+}
+
+/** Strip a line's ending terms before comparing or showing it. */
+function bareLine(line) {
+  return line.replace(/[\r\n]+$/, '')
+}
+
+/**
+ * Reduce an anchor or a line to a canonical comparison form.
+ *
+ * Indentation drops away, runs of whitespace collapse to one space, and the
+ * ends are trimmed, so a model may copy an anchor with or without the layout
+ * whitespace around the code.
+ * @param {unknown} text - an anchor candidate or a real line.
+ * @returns {string} whitespace-collapsed text.
+ */
+export function normalizeAnchor(text) {
+  return String(text ?? '').replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * Canonical form that keeps the line's own indentation.
+ *
+ * A model that copies the indentation it was shown gets a stricter comparison:
+ * `if (err) {` and `    if (err) {` are different lines, which is exactly the
+ * pair that a nesting mistake confuses. Inner whitespace still collapses.
+ * @param {unknown} text - an anchor candidate or a real line.
+ * @returns {string} indentation-preserving text.
+ */
+export function normalizeIndented(text) {
+  const raw = String(text ?? '')
+  const lead = raw.match(/^\s+/)?.[0] ?? ''
+  const rest = raw.slice(lead.length).replace(/\s+/g, ' ')
+  return `${lead}${rest}`.replace(/\s+$/, '')
+}
+
+/** Anchors that start with whitespace are compared with indentation kept. */
+function keepsIndent(given) {
+  return /^\s/.test(String(given ?? ''))
+}
+
+/**
+ * The anchor a line offers at its start: its first `ANCHOR_CHARS` characters.
+ *
+ * Whitespace is collapsed and the leading indentation dropped, so this is the
+ * *shortest* anchor the contract accepts — a model that copies the read display
+ * including indentation sends a stricter (indented) one. Used to build anchors
+ * in tests and by callers that need the canonical short form; never for matching.
+ * @param {string} line - the line without its ending.
+ * @returns {string} the start anchor.
+ */
+export function startAnchorOf(line) {
+  return normalizeAnchor(line).slice(0, ANCHOR_CHARS)
+}
+
+/**
+ * The anchor a line offers at its end: its last `ANCHOR_CHARS` characters.
+ *
+ * Whitespace is collapsed the same way; the whitespace itself is not part of a
+ * comparable end anchor.
+ * @param {string} line - the line without its ending.
+ * @returns {string} the end anchor.
+ */
+export function endAnchorOf(line) {
+  return normalizeAnchor(line).slice(-ANCHOR_CHARS)
+}
+
+/**
+ * Does a model-supplied anchor identify this line's start?
+ *
+ * An empty anchor means "this line is blank". A start anchor is a slice of the
+ * line's first characters, so leading whitespace in it *is* the indentation:
+ * when the model carries it, the comparison keeps indentation and `if (err) {`
+ * stops matching `    if (err) {`. A copy without the indentation still matches
+ * the collapsed form — the length contract is enforced by `applyPatch`.
+ * @param {string} line - the line without its ending.
+ * @param {string} given - the anchor the model sent.
+ * @returns {boolean} true when the anchor identifies the line.
+ */
+export function matchesStart(line, given) {
+  const strict = keepsIndent(given)
+  const actual = strict ? normalizeIndented(line) : normalizeAnchor(line)
+  const want = strict ? normalizeIndented(given) : normalizeAnchor(given)
+  if (want.length === 0) return actual.length === 0
+  return actual.startsWith(want)
+}
+
+/**
+ * Does a model-supplied anchor identify this line's end?
+ *
+ * An end anchor is a slice of the line's *last* characters, so whitespace at
+ * its edge is content, not indentation; both sides are compared collapsed.
+ * @param {string} line - the line without its ending.
+ * @param {string} given - the anchor the model sent.
+ * @returns {boolean} true when the anchor identifies the line.
+ */
+export function matchesEnd(line, given) {
+  const actual = normalizeAnchor(line)
+  const want = normalizeAnchor(given)
+  if (want.length === 0) return actual.length === 0
+  return actual.endsWith(want)
+}
+
+/**
+ * Is the anchor as long as the contract requires?
+ *
+ * The model is told to copy a whole anchor (16 characters, or the whole line
+ * when it is shorter). A shorter copy still identifies a line by prefix, which
+ * would quietly turn a 16-character check into a two-character one.
+ * @param {string} line - the line the anchor should identify.
+ * @param {string} given - the anchor the model sent.
+ * @returns {boolean} true when the anchor is shorter than the contract allows.
+ */
+export function anchorTooShort(line, given) {
+  const raw = String(given ?? '')
+  if (raw.length >= ANCHOR_CHARS) return false
+  if (normalizeAnchor(given).length === 0) return false
+  return normalizeAnchor(given) !== normalizeAnchor(line)
+}
+
+/** Render an anchor for an error message, naming the blank case. */
+function shown(anchor) {
+  return anchor.length === 0 ? '(blank)' : JSON.stringify(anchor)
+}
+
+/**
+ * Longest widening this plugin will suggest.
+ *
+ * The read renderer truncates displayed lines at 2,000 characters, so a longer
+ * anchor is text the model never saw and cannot usefully copy back.
+ */
+const SUGGESTION_CHARS = 2000
+
+/** Every 1-based line number whose text matches the anchor on that boundary. */
+function matchingLines(lines, given, boundary) {
+  const found = []
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = bareLine(lines[index])
+    const matched = boundary === 'start' ? matchesStart(line, given) : matchesEnd(line, given)
+    if (matched) found.push(index + 1)
+  }
+  return found
+}
+
+/** Render a short line-number list for an error message. */
+function describeLines(numbers) {
+  const head = numbers.slice(0, 8).join(', ')
+  return numbers.length > 8 ? `lines ${head}, …` : `lines ${head}`
+}
+
+/**
+ * The shortest widening of `given` that matches exactly one line, or null.
+ *
+ * Only the lines that already matched the short anchor can ever match a longer
+ * one, so the search walks those (usually two or three) instead of the whole
+ * file — otherwise a pair of long generated lines would cost O(file × length).
+ * The search stops at `SUGGESTION_CHARS`: past the read display's own truncation
+ * the model has never seen the characters, so a longer suggestion cannot be
+ * copied back and the edit is left to the line number instead.
+ * @param {string[]} lines - the file's lines, endings included.
+ * @param {number[]} matches - 1-based lines the short anchor already matched.
+ * @param {string} full - the named line's normalized text.
+ * @param {string} given - the anchor the model sent.
+ * @param {'start'|'end'} boundary - which end of the line the anchor covers.
+ * @returns {string|null} a unique anchor, or null when none is worth suggesting.
+ */
+function uniqueWidening(lines, matches, full, given, boundary) {
+  const from = Math.max(normalizeAnchor(given).length, ANCHOR_CHARS) + 1
+  const limit = Math.min(full.length, SUGGESTION_CHARS)
+  for (let length = from; length <= limit; length += 1) {
+    const candidate = boundary === 'start' ? full.slice(0, length) : full.slice(-length)
+    let hits = 0
+    for (const number of matches) {
+      const line = bareLine(lines[number - 1])
+      const matched = boundary === 'start' ? matchesStart(line, candidate) : matchesEnd(line, candidate)
+      if (matched) hits += 1
+      if (hits > 1) break
+    }
+    if (hits === 1) return candidate
+  }
+  return null
+}
+
+/**
+ * Would this anchor silently point at more than one line, and can widening fix it?
+ *
+ * Two lines sharing their first (or last) 16 characters are indistinguishable
+ * from those two slices alone; if the line is longer, the model can copy more
+ * of it and be exact, so that is worth one corrective turn. When even the whole
+ * line repeats, no anchor can disambiguate it — the line number is the only
+ * signal, and rejecting would block edits that are in fact unambiguous.
+ * @param {string[]} lines - the file's lines, endings included.
+ * @param {number} lineNumber - the line the model named.
+ * @param {string} given - the anchor the model sent.
+ * @param {'start'|'end'} boundary - which end of the line the anchor covers.
+ * @returns {{matches: number[], suggestion: string}|null} the ambiguity, or null.
+ */
+function ambiguousAnchor(lines, lineNumber, given, boundary) {
+  const matches = matchingLines(lines, given, boundary)
+  if (matches.length <= 1) return null
+  const full = normalizeAnchor(bareLine(lines[lineNumber - 1]))
+  if (full.length <= normalizeAnchor(given).length) return null
+  const suggestion = uniqueWidening(lines, matches, full, given, boundary)
+  // No widening separates them (repeated whole line): the line number is the only
+  // signal, and rejecting would block edits that are in fact unambiguous.
+  if (suggestion === null) return null
+  return { matches, suggestion }
+}
+
+/** A non-empty anchor that carries no characters at all. */
+function isWhitespaceOnly(anchor) {
+  const raw = String(anchor ?? '')
+  return raw.length > 0 && raw.trim().length === 0
+}
+
+/** Normalise every line ending in a replacement to the file's own style. */
+function normalizeEol(text, eol) {
+  const unified = text.replace(/\r\n|[\r\n]/g, '\n')
+  return eol === '\n' ? unified : unified.replace(/\n/g, eol)
+}
+
+/** Count the lines a replacement text occupies. */
+function countLines(text) {
+  if (text.length === 0) return 0
+  const parts = text.split('\n')
+  if (parts.length > 0 && parts[parts.length - 1] === '') parts.pop()
+  return parts.length
+}
+
+/** Reject an argument the tool cannot act on, instead of throwing later. */
+function badArgument(message) {
+  return { ok: false, code: 'BAD_ARGUMENT', message }
+}
+
+/**
+ * Apply an anchored line-range replacement.
+ *
+ * The whole-file hash is checked first: matching it proves the file is exactly
+ * the one the model read, so a later anchor mismatch cannot be a stale read —
+ * the model fixes the anchor or the line number without rereading.
+ * @param {object} input - the guarded edit request.
+ * @param {string} input.content - current file text.
+ * @param {string} input.expectedFileHash - `file_hash` the model was shown.
+ * @param {number} input.lineStart - 1-based first line to replace.
+ * @param {string} input.startAnchor - start anchor of that line.
+ * @param {number} input.lineEnd - 1-based last line to replace (inclusive).
+ * @param {string} input.endAnchor - end anchor of that line.
+ * @param {string} input.replace - replacement text; '' deletes the range.
+ * @returns {{ok: true, content: string, fileHash: string, lineShift: number, removedLines: number}
+ *   | {ok: false, code: string, message: string}}
+ */
+export function applyPatch(input) {
+  const { content, expectedFileHash, lineStart, startAnchor, lineEnd, endAnchor, replace } = input
+
+  if (!Number.isInteger(lineStart) || !Number.isInteger(lineEnd)) {
+    return badArgument(
+      `line_start and line_end must be whole line numbers (got ${String(lineStart)} and ${String(lineEnd)}).`,
+    )
+  }
+  if (typeof replace !== 'string') {
+    return badArgument(`replace must be a string (got ${typeof replace}); pass "" to delete the range.`)
+  }
+  // A hash of the wrong shape is a different mistake from a stale file: saying
+  // "the file changed" would send the model to reread for nothing.
+  if (typeof expectedFileHash !== 'string' || !new RegExp(`^[0-9a-f]{${FILE_HASH_CHARS}}$`).test(expectedFileHash)) {
+    return badArgument(
+      `file_hash must be the ${FILE_HASH_CHARS}-character lowercase hex hash printed on the line under a read/write/edit result ` +
+      `(got ${JSON.stringify(expectedFileHash)}). If you were never shown such a line, this plugin's annotation is not active — use edit or write instead.`,
+    )
+  }
+
+  const actualFileHash = fileHash(content)
+  if (expectedFileHash !== actualFileHash) {
+    return {
+      ok: false,
+      code: 'FILE_HASH_MISMATCH',
+      message: `file_hash mismatch: expected ${expectedFileHash}, actual ${actualFileHash} — the file changed since it was read; read it again.`,
+    }
+  }
+
+  const lines = splitKeepEnds(content)
+  const total = lines.length
+  if (total === 0) {
+    return {
+      ok: false,
+      code: 'RANGE_INVALID',
+      message: 'the file is empty, so there is no line to patch — use the write tool to add content instead.',
+    }
+  }
+  if (lineStart < 1 || lineStart > total) {
+    return {
+      ok: false,
+      code: 'RANGE_INVALID',
+      message: `line_start ${lineStart} is out of range (file has ${total} lines). ` +
+        'The file itself is unchanged — fix the line number and retry; do not reread the file.',
+    }
+  }
+  if (lineEnd < lineStart || lineEnd > total) {
+    return {
+      ok: false,
+      code: 'RANGE_INVALID',
+      message: `line_end ${lineEnd} is out of range (line_start ${lineStart}, file has ${total} lines). ` +
+        'The file itself is unchanged — fix the line number and retry; do not reread the file.',
+    }
+  }
+
+  const startLine = bareLine(lines[lineStart - 1])
+  const startWant = normalizeAnchor(startAnchor)
+  if (isWhitespaceOnly(startAnchor)) {
+    const blankLine = normalizeAnchor(startLine).length === 0
+    return {
+      ok: false,
+      code: 'ANCHOR_TOO_SHORT',
+      message: blankLine
+        ? `start_anchor is only whitespace and line ${lineStart} is blank — pass "" to address a blank line. Do not reread the file.`
+        : `start_anchor is only whitespace — line ${lineStart} is indented past ${ANCHOR_CHARS} characters. ` +
+          `Copy ${ANCHOR_CHARS} characters starting at its first non-blank character (or the whole line). Do not reread the file.`,
+    }
+  }
+  if (anchorTooShort(startLine, startAnchor)) {
+    return {
+      ok: false,
+      code: 'ANCHOR_TOO_SHORT',
+      message: `start_anchor ${shown(startWant)} is too short to identify a line — copy the first ${ANCHOR_CHARS} ` +
+        `characters of line ${lineStart}'s text (the part after the "N: " prefix in the read result; the whole line text when it is shorter). Do not reread the file.`,
+    }
+  }
+  if (!matchesStart(startLine, startAnchor)) {
+    return {
+      ok: false,
+      code: 'LINE_ANCHOR_MISMATCH',
+      message: `start_anchor ${shown(String(startAnchor ?? ''))} does not match line ${lineStart}, ` +
+        `which starts with ${shown(startLine.slice(0, ANCHOR_CHARS))}. ` +
+        'Copy it exactly, including the indentation; then fix start_anchor or line_start and retry — ' +
+        'do not reread the file (file_hash still matches).',
+    }
+  }
+  const startAmbiguity = ambiguousAnchor(lines, lineStart, startAnchor, 'start')
+  if (startAmbiguity) {
+    return {
+      ok: false,
+      code: 'ANCHOR_AMBIGUOUS',
+      message: `start_anchor ${shown(startWant)} matches ${describeLines(startAmbiguity.matches)} — ` +
+        `line ${lineStart} is longer than ${ANCHOR_CHARS} characters, so copy more of it, ` +
+        `for example ${JSON.stringify(startAmbiguity.suggestion)}. Do not reread the file (file_hash still matches).`,
+    }
+  }
+
+  const endLine = bareLine(lines[lineEnd - 1])
+  const endWant = normalizeAnchor(endAnchor)
+  if (isWhitespaceOnly(endAnchor)) {
+    const blankLine = normalizeAnchor(endLine).length === 0
+    return {
+      ok: false,
+      code: 'ANCHOR_TOO_SHORT',
+      message: blankLine
+        ? `end_anchor is only whitespace and line ${lineEnd} is blank — pass "" to address a blank line. Do not reread the file.`
+        : `end_anchor is only whitespace — line ${lineEnd} is padded with trailing whitespace. ` +
+          `Copy the last ${ANCHOR_CHARS} characters before that padding (or the whole line). Do not reread the file.`,
+    }
+  }
+  if (anchorTooShort(endLine, endAnchor)) {
+    return {
+      ok: false,
+      code: 'ANCHOR_TOO_SHORT',
+      message: `end_anchor ${shown(endWant)} is too short to identify a line — copy the last ${ANCHOR_CHARS} ` +
+        `characters of line ${lineEnd}'s text (the part after the "N: " prefix in the read result; the whole line text when it is shorter). Do not reread the file.`,
+    }
+  }
+  // A single-line range carries both anchors on one physical line, so a model
+  // that copied the head into both slots is right, not wrong.
+  const endOk = lineStart === lineEnd
+    ? matchesEnd(endLine, endAnchor) || matchesStart(endLine, endAnchor)
+    : matchesEnd(endLine, endAnchor)
+  if (!endOk) {
+    return {
+      ok: false,
+      code: 'LINE_ANCHOR_MISMATCH',
+      message: `end_anchor ${shown(String(endAnchor ?? ''))} does not match line ${lineEnd}, ` +
+        `which ends with ${shown(endAnchorOf(endLine))}. ` +
+        'Fix end_anchor or line_end and retry; do not reread the file (file_hash still matches).',
+    }
+  }
+  const endAmbiguity = ambiguousAnchor(lines, lineEnd, endAnchor, 'end')
+  if (endAmbiguity) {
+    return {
+      ok: false,
+      code: 'ANCHOR_AMBIGUOUS',
+      message: `end_anchor ${shown(endWant)} matches ${describeLines(endAmbiguity.matches)} — ` +
+        `line ${lineEnd} is longer than ${ANCHOR_CHARS} characters, so copy more of it, ` +
+        `for example ${JSON.stringify(endAmbiguity.suggestion)}. Do not reread the file (file_hash still matches).`,
+    }
+  }
+
+  const eol = detectEol(content)
+  const hadTrailingNewline = content.endsWith('\n')
+  let body = normalizeEol(replace, eol)
+  if (body.length > 0 && !body.endsWith('\n')) body += eol
+
+  const before = lines.slice(0, lineStart - 1)
+  const after = lines.slice(lineEnd)
+  if (after.length === 0 && !hadTrailingNewline) {
+    // Keep the "no trailing newline" shape, but never strip away the only line
+    // a `replace` of just a line terminator asked to insert.
+    const stripped = body.replace(/\r?\n$/, '')
+    if (stripped.length > 0 && countLines(stripped) === countLines(body)) body = stripped
+  }
+
+  const next = before.join('') + body + after.join('')
+  const removedLines = lineEnd - lineStart + 1
+  return {
+    ok: true,
+    content: next,
+    fileHash: fileHash(next),
+    lineShift: countLines(body) - removedLines,
+    removedLines,
+  }
+}

package/lib/index.js

@@ -0,0 +1,472 @@
+/**
+ * dsh-line-patch — anchored file editing for DeepSeek Harness.
+ *
+ * The plugin adds no read tool. Instead every `read`, `write` and `edit`
+ * result is annotated with a short `file_hash` line, and one new `patch` tool
+ * replaces a line range only when that hash and both boundary anchors still
+ * match. A model therefore keeps using the filesystem tools it already knows.
+ *
+ * Nothing here touches `node:fs`: reads and writes go through `ctx.fs` so the
+ * mounted filesystem (sandbox, remote, policy gate) stays authoritative.
+ */
+import { ANCHOR_CHARS, FILE_HASH_CHARS, applyPatch, fileHash } from './core.js'
+
+/** Plugin name used by loader diagnostics. */
+export const name = 'line-patch'
+
+/**
+ * `defineTool` types and validates arguments in the host. When the package is
+ * absent — a plain `node --test` checkout — the identity fallback keeps the
+ * module loadable so the pure logic and tool glue stay testable offline.
+ */
+const { defineTool } = await import('@deepseek-ai/dsh-tools')
+  .catch(() => {
+    console.warn('[line-patch] @deepseek-ai/dsh-tools not resolvable; running without argument validation')
+    return { defineTool: definition => definition }
+  })
+
+/** The tool registry and the filesystem service must be ready before `patch` registers. */
+export const inject = ['tools', 'fs']
+
+/** Built-in tools whose result carries the file hash. */
+const ANNOTATED_TOOLS = new Set(['read', 'write', 'edit'])
+
+/** Largest file this plugin will read to compute a hash. */
+const MAX_FILE_BYTES = 5 * 1024 * 1024
+
+/** How many user turns an anchor stays eligible for revalidation. */
+const ANCHOR_TURNS = 3
+
+/** Cap on tracked anchors so a read-heavy turn cannot grow the registry without bound. */
+const MAX_ANCHORS = 32
+
+const PATCH_DESCRIPTION = [
+  'Replace an inclusive line range after verifying the whole file and both boundary lines.',
+  `file_hash is the ${FILE_HASH_CHARS}-character hash printed under the most recent read/write/edit result for this file, or under a previous patch result.`,
+  `start_anchor is the first ${ANCHOR_CHARS} characters of line_start's text — the part after the "N: " prefix a read result prints — and end_anchor the last ${ANCHOR_CHARS} characters of line_end's text. Use the whole line text when it is shorter than ${ANCHOR_CHARS}; never include the "N: " prefix.`,
+  'Keep the indentation in start_anchor: one that carries it is compared strictly, which separates nested lines that look alike. Whitespace at either edge is otherwise collapsed.',
+  'replace is the new text; pass an empty string to delete the range.',
+  'If file_hash matches but an anchor does not, fix the anchor or the line number and retry without rereading the file.',
+  'If no read/write/edit result showed a file_hash line (a >5 MB file, or run_code/PTC mode where tool text is not visible), this tool cannot be used — fall back to edit or write.',
+].join(' ')
+
+/**
+ * Resolve the filesystem service or explain why the plugin cannot run.
+ * @param {object} ctx - the plugin context.
+ * @returns {object} the `ctx.fs` service.
+ */
+function requireFs(ctx) {
+  const fs = ctx?.fs
+  if (!fs || typeof fs.resolve !== 'function' || typeof fs.readText !== 'function') {
+    throw new Error('line-patch requires the ctx.fs service; mount @deepseek-ai/dsh-fs-local (or another provider).')
+  }
+  return fs
+}
+
+/**
+ * The working directory the tool ran in, when the host can provide one.
+ *
+ * Built-in fs tools resolve relative paths against the agent's working
+ * directory; without it `fs.resolve` falls back to the provider default and a
+ * relative path would hash — and later patch — a different file.
+ * @param {object} ctx - the plugin context.
+ * @param {object} exec - the tool execution being finalized.
+ * @returns {Promise<string|undefined>} the working directory, when known.
+ */
+async function workingDirectoryOf(ctx, exec) {
+  // The built-ins skip the lookup entirely for an agentless call; doing the same
+  // avoids a pointless throw on every root-level tool dispatch.
+  if (exec?.agent === undefined) return undefined
+  try {
+    const service = typeof ctx.get === 'function' ? ctx.get('workingDirectory') : ctx.workingDirectory
+    if (service && typeof service.ensure === 'function') return await service.ensure(exec?.agent, exec?.signal)
+  } catch {
+    // No working-directory service, or the step was aborted: fall back to the provider default.
+  }
+  return undefined
+}
+
+/**
+ * Read a file that fits the plugin's single-call budget, resolved the same way
+ * the built-in fs tools resolve it.
+ * @param {object} ctx - the plugin context.
+ * @param {string} filePath - model-supplied path.
+ * @param {object} [exec] - the tool execution carrying the agent and signal.
+ * @returns {Promise<{target: object, content: string, version: string}>} the read result.
+ */
+async function readWholeFile(ctx, filePath, exec) {
+  const fs = requireFs(ctx)
+  const signal = exec?.signal
+  const cwd = await workingDirectoryOf(ctx, exec)
+  const target = await fs.resolve(filePath, cwd === undefined ? { signal } : { cwd, signal })
+  const info = await fs.stat(target, signal)
+  if (!info) throw new Error(`file not found: ${filePath}`)
+  if (info.type !== 'file') throw new Error(`not a regular file: ${filePath}`)
+  if (typeof info.size === 'number' && info.size > MAX_FILE_BYTES) {
+    throw new Error(`file is larger than the ${MAX_FILE_BYTES} byte limit: ${filePath}`)
+  }
+  const content = await fs.readText(target, signal)
+  return { target, content, version: info.version }
+}
+
+/**
+ * Record the model-facing anchor so later turns can revalidate it.
+ * @param {object} registry - the plugin's anchor registry.
+ * @param {object} entry - anchor facts.
+ */
+function rememberAnchor(registry, entry) {
+  const key = entry.targetKey ?? entry.path
+  registry.anchors.set(key, entry)
+  registry.order.push(key)
+  while (registry.order.length > MAX_ANCHORS) {
+    const dropped = registry.order.shift()
+    if (dropped !== undefined && dropped !== key) registry.anchors.delete(dropped)
+  }
+}
+
+/**
+ * Replace the tool result that carried a now-void anchor with a notice.
+ *
+ * The surface is append-only, so "editing history" means appending a
+ * replacement event that shadows the original sequence.
+ * @param {object} registry - the plugin's anchor registry.
+ * @param {object} anchor - the anchor whose read result is stale.
+ * @param {string} freshHash - the file hash as it is now.
+ */
+function replaceStaleRead(registry, anchor, freshHash) {
+  const session = anchor.session ?? registry.session
+  if (!session || typeof session.append !== 'function' || typeof anchor.seq !== 'number') return
+  const event = session.eventAt?.(anchor.seq)
+  const data = event?.data
+  if (!data || !data.message) return
+  const text = `[line-patch] ${anchor.displayPath} was modified after it was read ` +
+    `(file_hash ${anchor.fileHash} -> ${freshHash}). The content and line numbers above are void; ` +
+    'read it again before patching.'
+  try {
+    session.append(
+      'tool/result',
+      { ...data, message: { ...data.message, content: [{ type: 'text', text }] } },
+      { surfaceOp: { op: 'replace', startSeq: anchor.seq, endSeq: anchor.seq }, sourceEventSeqs: [anchor.seq] },
+    )
+  } catch {
+    // A already-shadowed or foreign sequence is not ours to rewrite; the patch-time hashes still protect.
+  }
+}
+
+/**
+ * Re-check every live anchor against the file it came from.
+ *
+ * `stat` is the cheap prefilter: an unchanged stat version means nothing moved
+ * and no read happens. A changed version then splits into the two cases that
+ * matter — same content (refresh bookkeeping, keep the model's anchors) and
+ * different content (void the old result).
+ * @param {object} ctx - the plugin context.
+ * @param {object} registry - the plugin's anchor registry.
+ * @param {object} actor - the request's step context, used as the observation owner.
+ */
+async function revalidateAnchors(ctx, registry, actor) {
+  const fs = ctx?.fs
+  if (!fs || registry.anchors.size === 0) return
+  for (const [key, anchor] of [...registry.anchors]) {
+    if (registry.turn - anchor.turn > ANCHOR_TURNS) {
+      registry.anchors.delete(key)
+      continue
+    }
+    const target = anchor.target ?? { targetKey: key }
+    let info
+    try {
+      info = await fs.stat(target)
+    } catch {
+      continue
+    }
+    if (!info) {
+      registry.anchors.delete(key)
+      continue
+    }
+    if (info.version === anchor.version) continue
+    let content
+    try {
+      content = await fs.readText(target)
+    } catch {
+      continue
+    }
+    const fresh = fileHash(content)
+    if (fresh === anchor.fileHash) {
+      // Byte-identical: a rebuild or a touch moved the stat, not the content.
+      anchor.version = info.version
+      try {
+        ctx.emit('fs/observed', target, { kind: 'present', version: info.version }, actor)
+      } catch {
+        // no observation gate mounted
+      }
+      continue
+    }
+    replaceStaleRead(registry, anchor, fresh)
+    registry.anchors.delete(key)
+  }
+}
+
+/**
+ * What this result should carry, or null when it should carry nothing.
+ *
+ * Runs before the rest of the `tools/post-execute` chain. Reading the file
+ * again here is what makes the hash describe the file itself rather than the
+ * tool's (possibly partial) view. Registering the anchor is left to the caller,
+ * because a blocked result must not become a tracked read.
+ * @param {object} ctx - the plugin context.
+ * @param {object} registry - the plugin's anchor registry.
+ * @param {object} exec - the tool execution being finalized.
+ * @param {object} result - its outcome.
+ * @returns {Promise<{line: string, anchor: object|null}|null>} the annotation.
+ */
+async function annotationFor(ctx, registry, exec, result) {
+  const toolName = exec?.name
+  if (!ANNOTATED_TOOLS.has(toolName) || result?.isError) return null
+  if (!Array.isArray(result.content) || !result.content.some(block => block?.type === 'text')) return null
+  const filePath = exec.arguments?.file_path
+  if (typeof filePath !== 'string') return null
+
+  let read
+  try {
+    read = await readWholeFile(ctx, filePath, exec)
+  } catch {
+    // A path this plugin cannot hash (binary view, oversized file, vanished) simply gets no hash.
+    return null
+  }
+  // The hook re-reads the file after the tool did. If the stat version moved in
+  // between, the hash would attest content the model never saw — annotate
+  // nothing and let the next read produce a fresh pair.
+  const observedKey = read.target.targetKey ?? read.target.key
+  if (observedKey !== undefined && registry.observed.has(observedKey)
+    && registry.observed.get(observedKey) !== read.version) {
+    return null
+  }
+  const hash = fileHash(read.content)
+  const anchor = toolName === 'read'
+    ? {
+        targetKey: read.target.targetKey ?? read.target.key ?? filePath,
+        displayPath: filePath,
+        fileHash: hash,
+        version: read.version,
+        turn: registry.turn,
+        target: read.target,
+        session: registry.session,
+        callId: exec.callId,
+      }
+    : null
+  return { line: `file_hash: ${hash}`, anchor }
+}
+
+/** Does this content already end with a hash line (a second loaded instance)? */
+function alreadyAnnotated(content) {
+  const last = Array.isArray(content) ? content.at(-1) : undefined
+  if (last?.type !== 'text' || typeof last.text !== 'string') return false
+  return /(?:^|\n)file_hash: [0-9a-f]+$/.test(last.text)
+}
+
+/**
+ * Append the hash line *inside* the last text block.
+ *
+ * A result with two text blocks breaks plugins that annotate single-block
+ * results (dsh-context-archive requires `content.length === 1`), so the new
+ * line joins the existing block instead of becoming a block of its own.
+ * @param {object[]} content - the result content blocks.
+ * @param {string} line - the annotation line.
+ * @returns {object[]} the content blocks to return.
+ */
+function appendAnnotation(content, line) {
+  const blocks = Array.isArray(content) ? [...content] : []
+  const last = blocks.at(-1)
+  if (last?.type === 'text' && typeof last.text === 'string') {
+    const separator = last.text.endsWith('\n') ? '' : '\n'
+    blocks[blocks.length - 1] = { ...last, text: `${last.text}${separator}${line}` }
+    return blocks
+  }
+  return [...blocks, { type: 'text', text: line }]
+}
+
+/**
+ * Register the `patch` tool plus the hash annotation and anchor bookkeeping.
+ * @param {import('@deepseek-ai/cordis').Context} ctx - the plugin context.
+ */
+export function apply(ctx) {
+  const registry = { anchors: new Map(), order: [], turn: 0, session: undefined, observed: new Map() }
+
+  /** Record an observation so `fs/write-intent` sees this file as read. */
+  const observe = (target, version, actor) => {
+    try {
+      ctx.emit('fs/observed', target, { kind: 'present', version }, actor)
+    } catch {
+      // The gate is optional; a bare provider simply has no listener.
+    }
+  }
+
+  // A tool-mediated write refreshes its own observation, so the anchor it
+  // invalidates must not later read back as an "external" change. The same
+  // table tells the annotator whether the file moved between the tool's own
+  // observation and the hook's verifying read.
+  try {
+    ctx.on('fs/observed', (target, observation) => {
+      if (!target || observation?.kind !== 'present') return
+      const key = target.targetKey ?? target.key
+      if (key !== undefined) {
+        registry.observed.set(key, observation.version)
+        while (registry.observed.size > MAX_ANCHORS * 2) {
+          const oldest = registry.observed.keys().next().value
+          registry.observed.delete(oldest)
+        }
+      }
+      const anchor = registry.anchors.get(key)
+      if (anchor && anchor.version !== observation.version) registry.anchors.delete(key)
+    })
+  } catch {
+    // Hosts without the observation gate simply skip this bookkeeping.
+  }
+
+  // Every read/write/edit result is annotated here; `read` also registers the
+  // anchor that the per-request revalidation later checks.
+  try {
+    ctx.on('tools/post-execute', (...args) => {
+      const next = typeof args.at(-1) === 'function' ? args.at(-1) : undefined
+      const [exec, result] = args
+      // Cordis waterfall: `next()` takes no arguments and returns the downstream
+      // decision; the outermost listener's RETURN VALUE is what the host applies.
+      return annotationFor(ctx, registry, exec, result)
+        .catch(() => null)
+        .then(async annotation => {
+          const downstream = next ? await next() : { kind: 'accept' }
+          // Never argue with a block, a value replacement (the host forbids value
+          // and content together), or a result that already carries a hash.
+          if (!annotation || !downstream || downstream.kind !== 'accept') return downstream
+          if (Object.hasOwn(downstream, 'value')) return downstream
+          const base = Array.isArray(downstream.content) ? downstream.content : result.content ?? []
+          if (alreadyAnnotated(base)) return downstream
+          // Only an accepted read becomes a tracked anchor; a blocked one must not
+          // later be rewritten into a "file changed" notice.
+          if (annotation.anchor) rememberAnchor(registry, annotation.anchor)
+          return { ...downstream, content: appendAnnotation(base, annotation.line) }
+        })
+    })
+  } catch {
+    // Without the waterfall the model simply sees no file_hash; `patch` is then unusable, not wrong.
+  }
+
+  // One session/event listener carries three facts the revalidation needs: the
+  // live session, the user-turn counter, and the sequence of our own results.
+  try {
+    ctx.on('session/event', (session, event) => {
+      if (session) registry.session = session
+      if (!event) return
+      if (event.type === 'turn/start') {
+        registry.turn += 1
+        return
+      }
+      if (event.type !== 'tool/result') return
+      const callId = event.data?.message?.toolCallId
+      if (typeof callId !== 'string') return
+      for (const anchor of registry.anchors.values()) {
+        if (anchor.callId === callId && typeof anchor.seq !== 'number') {
+          anchor.seq = event.seq
+          anchor.session = session
+        }
+      }
+    })
+  } catch {
+    // A host without session events still gets a working patch; anchors just never expire by age.
+  }
+
+  // `agent/request` runs with an open step and before the model call: the one
+  // place where a surface replacement is legal and still useful.
+  try {
+    ctx.on('agent/request', (...args) => {
+      const next = typeof args.at(-1) === 'function' ? args.at(-1) : undefined
+      const stepContext = args[0]
+      const settled = revalidateAnchors(ctx, registry, stepContext).catch(() => {})
+      return next ? settled.then(() => next()) : settled
+    })
+  } catch {
+    // Without the hook, anchors are only checked at patch time.
+  }
+
+  ctx.tools.register(defineTool({
+    name: 'patch',
+    description: PATCH_DESCRIPTION,
+    parameters: {
+      file_path: { type: 'string', required: true, description: 'Path to edit, resolved by the filesystem backend.' },
+      file_hash: { type: 'string', required: true, description: `The ${FILE_HASH_CHARS}-character hash printed under the latest read/write/edit result for this file, or under a previous patch result.` },
+      line_start: { type: 'number', required: true, description: '1-based first line to replace.' },
+      start_anchor: { type: 'string', required: true, description: `First ${ANCHOR_CHARS} characters of line_start's text — after the "N: " prefix a read result prints — indentation included (the whole line text when it is shorter).` },
+      line_end: { type: 'number', required: true, description: '1-based last line to replace, inclusive. Equal to line_start for one line.' },
+      end_anchor: { type: 'string', required: true, description: `Last ${ANCHOR_CHARS} characters of line_end's text — after the "N: " prefix; whitespace at either edge is collapsed before comparing (the whole line text when it is shorter).` },
+      replace: { type: 'string', required: true, description: 'Replacement text. An empty string deletes the range.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          path: { type: 'string', required: true },
+          replaced: { type: 'array', required: true, items: { type: 'number' } },
+          line_shift: { type: 'integer', required: true },
+          new_file_hash: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: `patched ${value.path}: lines ${value.replaced[0]}-${value.replaced[1]} replaced ` +
+          `(line shift ${value.line_shift >= 0 ? '+' : ''}${value.line_shift}).\n` +
+          `file_hash: ${value.new_file_hash}`,
+      }],
+      presentationMeta: (args, value) => ({ replaced: value.replaced, path: value.path }),
+    },
+    async execute(args, exec) {
+      const fs = requireFs(ctx)
+      const { target, content, version } = await readWholeFile(ctx, args.file_path, exec)
+      const result = applyPatch({
+        content,
+        expectedFileHash: args.file_hash,
+        lineStart: args.line_start,
+        startAnchor: args.start_anchor,
+        lineEnd: args.line_end,
+        endAnchor: args.end_anchor,
+        replace: args.replace,
+      })
+      if (!result.ok) {
+        const error = new Error(result.message)
+        error.code = result.code
+        throw error
+      }
+
+      // Mirror the built-in write tool: ask the policy gate for the intent, then
+      // hand it to the provider so the version CAS (and read-before-write) apply.
+      const fallback = { kind: 'replaceIfVersion', version }
+      let intent = fallback
+      try {
+        const decided = await ctx.waterfall('fs/write-intent', target, exec, () => fallback)
+        if (decided) intent = decided
+      } catch {
+        intent = fallback
+      }
+
+      const outcome = await fs.writeText(target, result.content, intent, exec.signal)
+      observe(target, outcome?.version ?? version, exec)
+
+      rememberAnchor(registry, {
+        targetKey: target.targetKey ?? target.key ?? String(args.file_path),
+        displayPath: String(args.file_path),
+        fileHash: result.fileHash,
+        version: outcome?.version ?? version,
+        turn: registry.turn,
+        target,
+        // No callId: a patch result is never rewritten, it is only bookkeeping.
+      })
+
+      return {
+        path: fs.processPath ? fs.processPath(target) : String(args.file_path),
+        replaced: [args.line_start, args.line_end],
+        line_shift: result.lineShift,
+        new_file_hash: result.fileHash,
+      }
+    },
+  }))
+}

package/package.json

@@ -1,6 +1,59 @@
-{
-  "name": "dsh-line-patch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "dsh-line-patch",
+  "version": "0.3.0",
+  "description": "Anchored line patching for DeepSeek Harness: read/write/edit results carry a short file hash, and patch rewrites a line range only when that hash and both boundary-line anchors still match.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kingofpowers/dsh-line-patch.git"
+  },
+  "homepage": "https://github.com/kingofpowers/dsh-line-patch#readme",
+  "bugs": {
+    "url": "https://github.com/kingofpowers/dsh-line-patch/issues"
+  },
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "dsh",
+    "cordis",
+    "edit",
+    "patch",
+    "hash",
+    "anchor"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "manifestVersion": 1
+  },
+  "engines": {
+    "dsh": ">=0.2.1-rc.1 <0.3.0",
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": "*"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "check": "node --check lib/core.js && node --check lib/index.js"
+  },
+  "license": "MIT",
+  "author": "kingofpowers",
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    }
+  }
+}