dsh-better-edit 0.6.1 → 0.6.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,21 +1,24 @@
1
- ## [Unreleased]
1
+ ## [0.6.3](https://github.com/Rianico/dsh-better-edit/compare/v0.6.2...v0.6.3) (2026-09-05)
2
2
 
3
- ## [0.6.1] - 2026-09-01
3
+ ### Bug Fixes
4
4
 
5
- ### Fixed
5
+ * **self-heal:** restore hash-anchored read/edit after external takeover ([#43](https://github.com/Rianico/dsh-better-edit/issues/43)) ([#44](https://github.com/Rianico/dsh-better-edit/issues/44)) ([b53fc75](https://github.com/Rianico/dsh-better-edit/commit/b53fc753bcd71f1950bde61ad81e1b7b94758273))
6
+
7
+ ## [0.6.2](https://github.com/Rianico/dsh-better-edit/compare/v0.6.1...v0.6.2) (2026-09-03)
8
+
9
+ ### Bug Fixes
6
10
 
7
- - **hashline:** eliminate remaining P2s for zero-issue review
8
- - **hashline:** make read path per-session reserved for ADR-0013
9
- - **hashline:** polish P2s for ADR-0013 automatic fallback
10
- - **hashline:** implement per-session tombstone and epoch-aware strict pos
11
- - **hashline:** add per-session canons, epoch and strict pos for ADR-0013
12
- - **hashline:** prevent freed anchor reuse (#31)
11
+ * **deps:** upgrade dsh dependencies to 0.1.1-rc.2 ([30e6029](https://github.com/Rianico/dsh-better-edit/commit/30e6029888fa517f20c640b7a38523a8a6148ccd))
13
12
 
14
13
  ### Documentation
15
14
 
16
- - **adr:** clarify single vs multi-session pos-free trade-off
17
- - **adr:** refine ADR-0013 to automatic fallback (no config)
18
- - **adr:** add ADR-0013 pos-free roundtrip with concurrency fallback (#31)
15
+ * **readme:** compact rewrite — pos-free hero, round-trips, tokens ([dc468c5](https://github.com/Rianico/dsh-better-edit/commit/dc468c5ce9799ddf9578d92e715905701b2a95a1))
16
+
17
+ ## [0.6.1](https://github.com/Rianico/dsh-better-edit/compare/v0.6.0...v0.6.1) (2026-09-01)
18
+
19
+ ### Bug Fixes
20
+
21
+ * **hashline:** prevent freed anchor reuse ([#31](https://github.com/Rianico/dsh-better-edit/issues/31)) ([#42](https://github.com/Rianico/dsh-better-edit/issues/42)) ([19724a4](https://github.com/Rianico/dsh-better-edit/commit/19724a4083afcfc104172d5ce71bb6ab198026b7)), closes [GH#41](https://github.com/Rianico/GH/issues/41)
19
22
 
20
23
  ## [0.6.0](https://github.com/Rianico/dsh-better-edit/compare/v0.5.1...v0.6.0) (2026-08-31)
21
24
 
package/README.md CHANGED
@@ -5,7 +5,7 @@
5
5
  <h1 align="center">dsh-better-edit</h1>
6
6
  <p align="center">
7
7
  <strong>A better edit tool for DeepSeek Harness<br>
8
- Powered by hash‑anchored positioning — not by line numbers, not by string replacement, fewer tokens, more context space for real work.</strong>
8
+ Position-free hashes — one read, many edits, fewer tokens, more room for real work.</strong>
9
9
  </p>
10
10
  <p align="center">
11
11
  <strong>English</strong> ·
@@ -15,21 +15,20 @@
15
15
  <p align="center">
16
16
  <a href="#why-you-need-this"><img src="https://img.shields.io/badge/why-hashline-blue?style=flat" alt="why hashline"></a>
17
17
  <a href="#quick-start"><img src="https://img.shields.io/badge/quick_start-30s-brightgreen?style=flat" alt="quick start 30s"></a>
18
- <a href="#comparison"><img src="https://img.shields.io/badge/correctness-23%2F23-success?style=flat" alt="23/23 battery"></a>
18
+ <a href="#benchmark"><img src="https://img.shields.io/badge/correctness-23%2F23-success?style=flat" alt="23/23 battery"></a>
19
19
  </p>
20
20
 
21
21
  <p align="center">
22
22
  <a href="#quick-start">Quick Start</a> •
23
23
  <a href="#why-hashline">Why Hashline</a> •
24
24
  <a href="#tools">Tools</a> •
25
- <a href="#comparison">Comparison</a> •
25
+ <a href="#benchmark">Benchmark</a> •
26
26
  <a href="#how-anchors-work">How Anchors Work</a> •
27
- <a href="#development">Development</a> •
28
- <a href="#acknowledgments">Acknowledgments</a>
27
+ <a href="#development">Development</a>
29
28
  </p>
30
29
 
31
30
  <p align="center">
32
- <img src="https://img.shields.io/badge/version-0.3.1-blue.svg" alt="Version">
31
+ <img src="https://img.shields.io/badge/version-0.6.1-blue.svg" alt="Version">
33
32
  <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License">
34
33
  <img src="https://img.shields.io/badge/DeepSeek_Harness-Plugin-blueviolet.svg" alt="DeepSeek Harness Plugin">
35
34
  <img src="https://img.shields.io/npm/v/dsh-better-edit" alt="npm version">
@@ -44,59 +43,56 @@
44
43
  ---
45
44
 
46
45
  > *"The harness — not the model — is the bottleneck."* — Can Bölük, [*The Harness Problem*](https://stencil.so/blog/the-harness-problem)
47
- >
48
- > **This is the harness fix.** Content hashes replace line numbers — an edit above never shifts the anchor below. Every range is verified against what the agent actually saw. Stale or unseen lines are hard-rejected with fresh anchors to retry — no `read` needed.
49
- >
50
- > **3 tool calls vs 6 · -55.8% tokens · 23/23 correctness.** Same external-drift refactor, same correct file (single stochastic run vs OMP; [full method](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/results/2026-08-17-practical-token-benchmark.md)). Benchmark envelope numbers are deterministic — see [Benchmark](#benchmark).
46
+
47
+ > **This is the harness fix.** Hashes replace line numbers — edits above don't shift anchors below. One `read` serves many `edit`s; drift outside your range passes with a notice, true conflicts retry with fresh anchors — no full `read` needed.
48
+
49
+ > **3 calls vs 6 · -55.8% tokens · 23/23 correctness.** Same external-drift refactor, same file (single stochastic run; [method](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/results/2026-08-17-practical-token-benchmark.md)). Payload numbers are deterministic — see [Benchmark](#benchmark).
51
50
 
52
51
  ## Why you need this
53
52
 
54
- **If you've watched an agent corrupt a file because `line 47` became `line 74` after an insert — this is for you.**
53
+ **If you've watched `line 47 → 74` corrupt a file after an insert — this is for you.**
55
54
 
56
55
  | Before: `str_replace` / line numbers | After: hashline `edit` |
57
56
  | --- | --- |
58
- | Model re-types old code (output billed ~5-6× input) | Sends two 3-char hashes — old text is never echoed |
59
- | One insert above shifts every number below → wrong line lands silently | Anchors are content addresses → edits above don't move anchors below |
60
- | No check that the range matches what was shown | Every line verified against served rows; `[E_RANGE_STALE]`/`[E_RANGE_UNSERVED]` reject before any write, then **reject-and-serve** returns fresh `HASH│content` to retry |
57
+ | Re-types old code (~5-6× billed) | Two `3-char` hashes, old text never echoed |
58
+ | One insert shifts every number → silent wrong line | Content addresses — edits above don't move anchors below |
59
+ | No check against what was shown | Every line verified; `[E_RANGE_STALE]`/`[E_RANGE_UNSERVED]` reject before write, then **reject-and-serve** returns fresh `HASH│content` |
61
60
 
62
61
  > [!TIP]
63
- > **Shining points — honest and measured:**
62
+ > **Shining points — honest:**
64
63
  >
65
- > - **Self-healing, not silent.** External edits never get overwritten — stale ranges are rejected and re-served as fresh `HASH│content` to retry; orphaned serves heal without a full re-read (ADR-0008). Fail-closed, not auto-merge.
66
- > - **Formatter-tolerant.** ASCII-whitespace-insensitive anchors survive `prettier`/`black`/`eslint --fix` between edits (`formatOnSave`, watcher, CI). Linter-only assumption — whitespace inside string literals is not distinguished (ADR-0005).
67
- > - **Chained & batched, no re-read ritual.** Anchors for untouched lines stay valid; diff/echo/reject rows count as serves. `edit` batches up to 32 same-file edits atomically (`[E_BATCH_ABORT]`), ~-40% envelope vs `str_replace` on the pinned 12-edit corpus.
68
- > - **Read guard enforced.** Never edits what it hasn't seen — `[E_RANGE_UNSERVED]`/`[E_RANGE_UNVERIFIED]`/`[E_STALE_ANCHOR]` reject before any write, then `reject-and-serve`.
69
- > - **Fewer round-trips in practice.** Dated run: **3 calls vs 6** for the OMP wrapper on the same external-drift refactor, same correct file; envelope vs `str_replace` is the durable number — reproducible via the upstream battery (same hashline algorithm, [method](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/results/2026-08-17-practical-token-benchmark.md)). Correctness `23/23` deterministic.
70
-
71
- Not for one-line touch-ups (near parity) or brand-new files (`write`). It pays off in long sessions and structural edits — anywhere an edit must not land on the wrong line.
64
+ > - **Position-free.** `read 1..5` → `insert @0` → `edit 10..12` still lands at `10..12`. Anchors are `canon(line)` hashes, not positions (ADR-0013). Exterior drift is a notice, not a re-read.
65
+ > - **Fewer round-trips.** Single-session `1 read → N edits` — no ritual re-reads. Multi-session exterior `A:10..12 / B:20..30` also passes; only overlapping `A∩B≠∅` retries once via `servedRows` (no full `read`). Harness `9/9` green.
66
+ > - **Fewer tokens.** Compact payload `{path, edits:[[from,to,text]]}` + never echoing `old_string`; diff/echo/rejection rows count as serves. Envelope `-40%` pinned 12-edit corpus, session `-55.8%` on external-drift.
67
+ > - **Concurrent-safe, not silent.** `tombstone` per `(session,path)` epoch blocks re-bound `S@3→@3`; `canon` + `hash` + `changed∩[L,R]` makes `pos-free` single-thread and `strict` only on true overlap. One retry vs silent wrong-line.
72
68
 
73
- > Deep dive: <a href="#why-hashline">Why Hashline</a> · <a href="#comparison">Comparison</a> · <a href="benchmark/README.md">Benchmark</a>
69
+ Not for one-line touch-ups (near parity) or new files (`write`). Pays off in long sessions and structural edits.
74
70
 
75
- ## Quick Start — from install to verified edit in 30s
71
+ ## Quick Start — install to verified edit in 30s
76
72
 
77
73
  ### Install (pick one)
78
74
 
79
75
  ```sh
80
76
  npx @deepseek-ai/dsh plugin --profile web add github:Rianico/dsh-better-edit # from github
81
- npx @deepseek-ai/dsh plugin --profile web add dsh-better-edit # from npm
82
- npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-better-edit # from a local checkout
77
+ npx @deepseek-ai/dsh plugin --profile web add dsh-better-edit # from npm
78
+ npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-better-edit # local
83
79
  ```
84
80
 
85
- No config. The profile's next session runs with the hashline tools installed. To verify the layer is active:
81
+ No config. Next session runs with hashline tools. Verify:
86
82
 
87
83
  ```sh
88
- dsh --profile <name> --dump-config # shows a "# == dsh-better-edit" layer
84
+ dsh --profile <name> --dump-config # shows "# == dsh-better-edit" layer
89
85
  ```
90
86
 
91
87
  | Requirement | |
92
88
  | --- | --- |
93
- | Node | `^22.19.0 \|\| >=24.0.0` (dsh's requirement; the store uses `node:sqlite`) |
94
- | Profile | a dsh profile (`dsh plugin` initializes one on first use) |
95
- | Backends | sandboxed / remote filesystems supported (writes go through `ctx.fs`) |
89
+ | Node | `^22.19.0 \|\| >=24.0.0` |
90
+ | Profile | `dsh` profile (`dsh plugin` creates one) |
91
+ | Backends | sandboxed / remote `ctx.fs` |
96
92
 
97
93
  ### See it work
98
94
 
99
- `read` returns every line prefixed by its hash — the hash *is* the line's address:
95
+ `read` serves `HASH│content` — the hash *is* the address:
100
96
 
101
97
  ```text
102
98
  ve7│function hello() {
@@ -104,13 +100,13 @@ szJ│ console.log("world");
104
100
  kQm│}
105
101
  ```
106
102
 
107
- `edit` targets a range of hashes, so edits always land on the lines you meant:
103
+ `edit` by hashes — always lands where you meant:
108
104
 
109
105
  ```json
110
106
  { "path": "src/main.ts", "edits": [["szJ", "szJ", " console.log('hi');"]] }
111
107
  ```
112
108
 
113
- and returns a diff with fresh anchors, so the next edit verifies cleanly with no re-read:
109
+ Returns a diff with fresh anchors — next edit needs no `read`:
114
110
 
115
111
  ```text
116
112
  - szJ │ console.log("world");
@@ -118,434 +114,187 @@ and returns a diff with fresh anchors, so the next edit verifies cleanly with no
118
114
  kQm │ }
119
115
  ```
120
116
 
121
- Chained edits stay cheap — anchors for untouched lines remain valid, diff/echo rows count as serves, and `read` becomes on-demand recovery, not a ritual. Try batching — one `edit` call, same-file, atomic:
117
+ **Position-free in one line:** `read 1..5` → `insert @0` → `edit 10..12` still verifies `10..12` (`resist` mode). **Multi-session honesty:** `A:10..12+1` shifts `B:20..30→21..31` → `B` passes (drift notice); `B:12..13` overlapping `A` → `E_RANGE_STALE` + fresh rows, one retry.
118
+
119
+ Batch atomically — one `edit`, up to 32 same-file ranges:
122
120
 
123
121
  ```json
124
- { "path": "src/main.ts", "edits": [["a1b", "a1b", "new line 1\n"], ["c3d", "c3d", "new line 2"]] }
122
+ { "path": "src/main.ts", "edits": [["a1b","a1b","new line 1\n"], ["c3d","c3d","new line 2"]] }
125
123
  ```
126
124
 
127
- One fails, none write (`[E_BATCH_ABORT]`). Encoding errors `[E_BAD_ENCODING]`/`[E_DECODE_FAILED]` are also emitted.
125
+ One fails → none write (`[E_BATCH_ABORT]`).
128
126
 
129
127
  > [!TIP]
130
- > **Want proof before you install?** The upstream [23/23 tool battery](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/README.md) runs with no LLM — stale edits are rejected before they corrupt a file, on every run. Same hashline algorithm, same verification.
128
+ > **Want proof before you install?** Upstream [23/23 battery](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/README.md) runs no LLM — stale edits are rejected every run. Same algorithm.
131
129
 
132
130
  ### Configuration
133
131
 
134
- Tenancy and prompt guidance are both declared once, read at `agent/session-start`, and need no code changes.
132
+ Tenancy and prompt guidance declare once, read at `agent/session-start`, no code change.
135
133
 
136
- #### Store tenancy — central by default
137
-
138
- The store lives at `$DSH_HOME/plugins/dsh-better-edit/runtime/<name>-<hash8>/` by default (`central`).
139
-
140
- > [!NOTE]
141
- > DB files are **disposable caches** — they are rebuilt automatically on the next `read` (hashes are re-derived from file content). Feel free to `rm -rf` any `runtime/<name>-<hash8>/` or `hash-store.sqlite*` to reclaim disk; no user data is lost (only anchor history and undo snapshots).
142
-
143
- To opt into legacy co-location or a custom root:
134
+ **Store** central by default `$DSH_HOME/plugins/dsh-better-edit/runtime/<name>-<hash8>/` (`ls`-readable + `.wsPath` sidecar). DBs are disposable caches — `rm -rf runtime/<name>-<hash8>/` is safe, rebuilt on next `read`.
144
135
 
145
136
  ```yaml
146
137
  # $DSH_HOME/plugins/dsh-better-edit/config.yaml
147
- storeDir: central # where the store lives: "central" (default, in $DSH_HOME/.../runtime/<name>-<hash8>/) | "workspace" (legacy <ws>/.dsh_better_edit/) | "/abs/path" (custom root)
148
- autoGitignore: false # workspace only: when .git exists but .gitignore lacks .dsh_better_edit/, true = auto-append ".dsh_better_edit/", false = warn once
149
- undo_ttl_s: 604800 # undo history TTL in seconds; -1 = keep forever (default 604800 = 7 days)
150
- storeMaxAgeS: 2592000 # central janitor: max idle age in seconds before a runtime/<name>-<hash8>/ dir is evicted (default 2592000 = 30 days)
151
- storeMaxTotalBytes: 524288000 # central janitor: max total bytes under runtime/ before LRU eviction (default 524288000 = 500 MB)
138
+ storeDir: central # central | workspace | /abs
139
+ autoGitignore: false
140
+ undo_ttl_s: 604800 # 7d, -1 forever
141
+ storeMaxAgeS: 2592000 # 30d janitor
142
+ storeMaxTotalBytes: 524288000 # 500 MB LRU
152
143
  ```
153
144
 
154
- > [!TIP]
155
- > If the file does not exist, a default `config.yaml` with commented defaults is generated on first boot (never overwrites an existing file).
156
-
157
- Env overrides yaml (`env > yaml > central`), malformed falls back to `central` with a warning:
158
-
159
- ```sh
160
- DSH_BETTER_EDIT_STORE_DIR=central|workspace|/abs
161
- DSH_BETTER_EDIT_AUTO_GITIGNORE=true|false # case-insensitive
162
- ```
163
-
164
- `runtime/<name>-<hash8>/` is `ls`-readable with a `.wsPath` sidecar. See `docs/specs/issue-24-store-tenancy.md` for lifecycle (janitor `mtime>storeMaxAgeS` then LRU, WAL checkpoint, `undo` TTL).
165
-
166
- #### Guidance per preset
167
-
168
- The `tool:read` / `tool:edit` / `tool:undo_last_edit` prompt sections are plain-markdown files per agent preset, overridable without touching the plugin:
169
-
170
- ```
171
- $DSH_HOME/plugins/dsh-better-edit/<preset>/<section>.md
172
- ```
173
-
174
- (default home `~/.dsh`, so `~/.dsh/plugins/dsh-better-edit/`). The section table:
175
-
176
- | File | Section | Default order |
177
- | --- | --- | --- |
178
- | `read.md` | `tool:read` | 130 |
179
- | `edit.md` | `tool:edit` | 131 |
180
- | `undo_last_edit.md` | `tool:undo_last_edit` | 133 |
181
-
182
- On first boot the plugin seeds the three shipped presets — `standard/`, `code/`, `minimal/`, `cordis/` — each with the compiled guidance as editable files (plus `order` front-matter). See [Configuration details](#configuring-guidance-per-preset) for reset/restore. Full spec: `docs/specs/issue-24-store-tenancy.md` and guidance docs.
145
+ Env overrides yaml (`DSH_BETTER_EDIT_STORE_DIR`, `DSH_BETTER_EDIT_AUTO_GITIGNORE`).
183
146
 
184
- ##### Reset / restore defaults
185
-
186
- Emptying or deleting an override file restores that section's compiled default guidance and order: the default renders at session-start, and the file re-seeds at next boot.
187
-
188
- - **Reset = delete the file, or empty it AND remove the front-matter fence.** A whitespace-only file with no fence means "I want the default" — the compiled default renders, and the file re-seeds at next boot for any preset dir, shipped or custom.
189
- - **Blank on purpose = keep a valid fence.** Any well-formed `---` fence — even a keyless `---\n---\n`, even an empty body — is a deliberate-intent signal: the file is explicit content and is never reset or re-seeded.
190
- - **Broken fence = fast fail.** A `---` fence that does not parse (missing closing `---`, non-integer `order`, unknown key) is rejected: the malformed text is never injected into the context, the compiled default renders, a warning names the file and the reason, and the file is left untouched on disk for repair.
191
- - **Shipped vs custom.** Shipped preset files (`standard`, `code`, `minimal`, `cordis`) re-seed at boot; a deleted custom-preset override stays absent — absence is no override. Deleting a whole `<preset>/` directory re-seeds all three section files at boot (shipped presets).
192
- - **Reset restores the current bundle defaults** — a plugin upgrade yields new defaults.
193
-
194
- Re-seeding happens at boot, never mid-session.
147
+ **Guidance per preset** — `tool:read` / `tool:edit` / `tool:undo_last_edit` are plain markdown per preset at `$DSH_HOME/plugins/dsh-better-edit/<preset>/<section>.md` (orders `130/131/133`). Delete or empty a file → default re-seeds at next boot; keep a `---` fence to blank on purpose.
195
148
 
196
149
  ## Why Hashline
197
150
 
198
- **Correctness, not just brevity.** Every resolved edit range is verified against the
199
- served rows — what `read`, a post-edit diff, or a rejection echo actually showed the model.
200
- A line inside the range that changed on disk since it was served, or was never served, is
201
- hard-rejected before any file I/O: `[E_RANGE_STALE]` / `[E_RANGE_UNSERVED]` /
202
- `[E_RANGE_UNVERIFIED]`, and the current range is echoed as fresh `HASH│content` rows. The
203
- retry needs no `read`. Served state is session-scoped, so sub-agent serves never validate the main session's edits and vice versa.
204
-
205
- **Content-addressed anchors.** Anchors are derived from line content (ASCII-whitespace
206
- stripped), not position: edit one part of a file and the hashes of the rest stay put, so
207
- chained edits need no re-reads. Re-inserting identical text keeps its hash — "edit X with
208
- X" doesn't rotate the anchor. Anchors are unique by construction — repeated `}` or
209
- `import` lines never share one.
210
-
211
- **Chained edits without re-reading.** Post-edit diff rows, auto-read rows, and rejection
212
- echoes all count as serves. `read` is on-demand recovery, not a per-edit ritual.
213
-
214
- **Stop the loop.** A no-op edit reports `No changes made` and leaves anchors alone; the
215
- same no-op re-sent three times is refused (`[E_NOOP_LOOP]`). `edit` applies up to 32
216
- edits atomically — any stale item aborts the whole batch with `[E_BATCH_ABORT]`.
151
+ **Verified against what was served.** Every resolved line checked against `read`/diff/rejection rows. Stale or unseen → `[E_RANGE_STALE]`/`[E_RANGE_UNSERVED]`/`[E_RANGE_UNVERIFIED]` + fresh `HASH│content`, retry needs no `read`. Session-scoped — sub-agent serves never validate main edits.
217
152
 
218
- ### Token economics: envelope savings
153
+ **Content-addressed.** `canon(line)` strips ASCII whitespace, `xxh32 → 62³=238,328` anchors. Re-inserting identical text keeps its hash; `prettier`/`eslint --fix` between edits doesn't invalidate. Unique by bitset probing — `}`/`import` repeats never collide; cap `238,328` lines (`[E_FILE_TOO_LARGE]`).
219
154
 
220
- The compact JSON contract is primarily a **token-saving envelope change**. It removes repeated field names and escaped wrapper syntax while leaving the verified edit semantics unchanged:
155
+ **No loop, no ritual.** No-op → `No changes made`; same no-op ×3 → `[E_NOOP_LOOP]`. Diff/echo/rejection rows count as serves — `read` is recovery, not ritual.
221
156
 
222
- - `edit` is one uniform payload: `{ "path": path, "edits": [[from, to, replacement], …] }` — `path` hoisted, arity by `edits.length`;
223
- - replacement text is emitted once, and the old text is never repeated in the call.
157
+ ### Token economics
224
158
 
225
- #### Theoretical benchmark — serialized envelopes
159
+ Envelope change: hoist `path`, `edits:[[from,to,text]]`, never repeat `old_string`.
226
160
 
227
- This benchmark counts only the serialized edit payloads, not model reasoning, tool descriptions, reads, retries, or cache traffic. Same hashline algorithm as upstream — numbers reproduced from [`pi-better-edit/benchmarks/results/`](https://github.com/Rianico/pi-better-edit/tree/main/benchmarks/results) (pinned 12-edit corpus, `cl100k_base`):
228
-
229
- | snapshot | `str_replace` | pi/dsh-better-edit: `edit` | pi/dsh-better-edit: `edit` (multi-item) | OMP: per-edit | OMP: one batch |
161
+ | snapshot | `str_replace` | `edit` | `edit` multi | OMP per-edit | OMP batch |
230
162
  | --- | ---: | ---: | ---: | ---: | ---: |
231
- | external pinned 12-edit corpus, current-envelope recount | 1,015 | 609 (**-40.0%**) | 582 (**-42.7%**) | 590 (**-41.9%**) | 480 (**-52.7%**) |
232
- | local 12-edit configuration snapshot | 358 | 272 (**-24.0%**) | 241 (**-32.7%**) | 268 (**-25.1%**) | 180 (**-49.7%**) |
233
-
234
- All percentages are savings against the `str_replace` value in the same row. The external row uses the pinned corpus, current object-root tuple envelopes, and current 3-character anchors. The local row is reproducible with `npm run benchmark` in the upstream repo; correctness is measured separately with the battery.
235
-
236
- #### Practical benchmark — coding-agent session
163
+ | pinned 12-edit corpus | 1,015 | 609 **-40.0%** | 582 **-42.7%** | 590 **-41.9%** | 480 **-52.7%** |
164
+ | local snapshot | 358 | 272 **-24.0%** | 241 **-32.7%** | 268 **-25.1%** | 180 **-49.7%** |
237
165
 
238
- This benchmark measures a real coding-agent loop rather than serialized envelopes. The practical advantage is round-trip efficiency: hashline completed the scenario in **3 tool calls**, versus **6 for OMP**. Upstream runs `pi` with `opencode-go/gpt-5.6-luna` at `high` thinking. Same algorithm downstream — we reference the upstream dated artifact:
166
+ Percent vs `str_replace`. External row pinned corpus, `cl100k_base`; local `npm run benchmark` in upstream.
239
167
 
240
- | engine | tool calls | total tokens | saved vs OMP baseline | final correctness |
168
+ | engine | calls | tokens | saved | ok |
241
169
  | --- | ---: | ---: | ---: | :---: |
242
- | OMP patch wrapper | **6** | 28,467 | 0.0% | ✅ |
243
- | hashline `edit` (multi-item) | **3 (fewest)** | 12,593 | **-55.8%** | ✅ |
170
+ | OMP | **6** | 28,467 | — | ✅ |
171
+ | hashline `edit` | **3** | 12,593 | **-55.8%** | ✅ |
244
172
 
245
- Both engines preserved the external change and produced the expected final file in this sample. This result is one stochastic model run; it must not be read as a universal performance claim. Latest dated artifact: [2026-08-17 practical token benchmark](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/results/2026-08-17-practical-token-benchmark.md) · [hashline library battery](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/results/2026-08-17-hashline-library.md) · [tool battery](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/results/2026-08-17-tool-battery.md).
173
+ Single stochastic run, `opencode-go/gpt-5.6-luna` high. [Artifact](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/results/2026-08-17-practical-token-benchmark.md).
246
174
 
247
- > **Scope & honesty.** These numbers are **payload + round-trip** measures, not throughput claims. The benchmark payload is deterministic; the practical run is stochastic. Dated results live upstream in `benchmarks/results/`; we do not re-run locally because the algorithm is identical.
175
+ > **Scope & honesty.** Payload deterministic; practical run stochastic. We measure **payload + round-trips**, not throughput. Retries are where the gap is largest — see [edge cases](#comparison).
248
176
 
249
177
  ## Tools
250
178
 
251
179
  | Tool | What it does |
252
- | ------ | -------------- |
253
- | `read` | Returns a text file with every line as `HASH│content`. `offset` (1-based), `limit`. Paged output ends with `[Showing lines N-M of T. Use offset=… to continue.]`. Lines >200KB shown as a marker with a `sed` hint — hash anchors need full lines. |
254
- | `read_skill` | Same file read as plain text — no `HASH│` prefixes, no served rows. For skill content (SKILL.md or any file); records no serves, so editing a file read this way starts with a `[E_RANGE_UNSERVED]` serve on the first edit. |
255
- | `edit` | An object-root payload `{ "path": path, "edits": [[remove_from, remove_to, replacement_text], …] }`; the path may be `null` for anchor-based inference. A single item edits one range; several items batch same-file edits atomically (up to 32). Verifies every line of each inclusive range and reject-and-serve returns fresh anchors. |
256
- | `undo_last_edit` | `{ path }` restores the most recent successful edit with its original content, BOM, line endings, and anchors; persisted across restarts. |
257
-
258
- The built-in `write` remains available for full-file replacement. Before it runs, the plugin refuses only a candidate line that begins with the exact `HASH│` anchor served for the same session, canonical path, and line; the file stays unchanged and the response asks for a retry with file content only. It never generically strips hash-like text.
180
+ | --- | --- |
181
+ | `read` | `HASH│content` with `offset`/`limit`; `[Showing N-M of T]` paging; `>200KB` lines show marker |
182
+ | `read_skill` | Plain text, no hashes, no serves — editing after it needs a serve |
183
+ | `edit` | `{path, edits:[[from,to,text]]}` `path:string\|null` inference, `""` deletes, atomic ≤32, verify-then-write |
184
+ | `undo_last_edit` | `{path}` restores last edit (BOM/line endings/anchors), persisted |
259
185
 
260
- `edit` accepts `{ "path": path, "edits": [[remove_from, remove_to, replacement_text], …] }`. The path
261
- position is a non-empty string or `null` for unique anchor-based inference. Each range is inclusive,
262
- and an empty replacement deletes the range. All items are checked before file I/O and applied
263
- atomically to that one file — one item per call is the norm, several same-file items batch in one call.
186
+ `write` stays, but refuses an exact `HASH│` echo for same `session/path/line` before dispatch.
264
187
 
265
188
  ### Error codes
266
189
 
267
190
  | Code | Meaning |
268
191
  | --- | --- |
269
- | `[E_BAD_SHAPE]` | The payload is not the fixed tuple shape, or a tuple member has an unknown, missing, or wrongly-typed value. |
270
- | `[E_BAD_REF]` | An anchor in the inclusive range is not a bare 3-char hash. |
271
- | `[E_STALE_ANCHOR]` | An anchor does not match any line in the current file; call `read` for fresh anchors. |
272
- | `[E_AMBIGUOUS_ANCHOR]` | An anchor matches multiple lines; call `read` for fresh anchors. |
273
- | `[E_INVALID_PATCH]` | A `replacement_text` line is a diff-preview row (`+HASH│`, `-HASH│`, `- │`). The marker is stripped automatically with a warning. |
274
- | `[E_BARE_HASH_PREFIX]` | A `replacement_text` line starts with a hash-like `HASH│` prefix. The prefix is stripped automatically with a warning. |
275
- | `[E_EDIT_HASH_ECHO]` | A `replacement_text` line begins with the exact `HASH│` anchor served for the same session, path, and range-relative line (`E1`). The edit is refused; remove the copied anchors and retry. Nothing was written. |
276
- | `[E_BAD_OP]` | Range start line is after range end line. The pair is swapped automatically with a warning. |
277
- | `[E_WOULD_EMPTY]` | An edit would empty a non-empty file; use `write` instead. |
278
- | `[E_NOT_FOUND]` | The path does not exist. |
279
- | `[E_ACCESS]` | The path is not readable or writable. |
280
- | `[E_NOT_TEXT]` | The path is a directory, binary file, image, or UTF-16/UTF-32 encoded text; hashline editing only supports text files. |
281
- | `[E_NOT_OBSERVED]` | The file has not been observed in this session (read-before-write); call `read` first. |
282
- | `[E_WRITE_HASH_ECHO]` | A built-in `write` candidate copied a `HASH│` preview anchor served for the same session, path, and line. The write is refused before dispatch; remove the entire copied anchor chain and retry. |
283
- | `[E_UNDO_STALE]` | `undo_last_edit` refused: the file was modified or deleted after the last edit. |
284
- | `[E_UNDO_UNAVAILABLE]` | Undo history could not be persisted to the hash store; the `edit` was refused and the file was left unchanged. |
285
- | `[E_FILE_TOO_LARGE]` | The file exceeds the 238,328-line hashline limit. |
286
- | `[E_RANGE_STALE]` | A line inside the resolved edit range changed on disk since it was served (read output, diff, or rejection feedback). The edit is refused and the current range is echoed as fresh `HASH│content` rows; retry with those rows (no `read` needed). |
287
- | `[E_RANGE_UNSERVED]` | A line inside the resolved edit range was never served to the model (paged reads, truncated output). The edit is refused and the current range is echoed as fresh `HASH│content` rows. |
288
- | `[E_RANGE_UNVERIFIED]` | A boundary anchor (`remove_from`/`remove_to`) has no served position or was served at multiple positions, so the range cannot be verified against served state. The edit is refused and the current range is echoed as fresh `HASH│content` rows. |
289
- | `[E_NOOP_LOOP]` | The exact same edit (same path, anchors, and replacement) was re-sent and produced no changes 3 consecutive times — the range already contains the replacement. The edit is refused and the current range is echoed as fresh `HASH│content` rows. |
290
- | `[E_BATCH_ABORT]` | A multi-item `edit` call was rejected as a whole: an item failed validation or served-state verification. Nothing was written; the failing item's current range is echoed as fresh `HASH│content` rows. |
192
+ | `[E_BAD_SHAPE]`/`[E_BAD_REF]` | Bad tuple shape or not bare `3-char` |
193
+ | `[E_STALE_ANCHOR]`/`[E_AMBIGUOUS_ANCHOR]` | No line / multi-line → `read` |
194
+ | `[E_EDIT_HASH_ECHO]`/`[E_WRITE_HASH_ECHO]` | Copied `HASH│` from same session/path/line — strip and retry |
195
+ | `[E_WOULD_EMPTY]`/`[E_NOT_FOUND]`/`[E_ACCESS]`/`[E_NOT_TEXT]`/`[E_FILE_TOO_LARGE]` | Empty guard / missing / access / binary / >238,328 lines |
196
+ | `[E_BAD_OP]`/`[E_INVALID_PATCH]`/`[E_BARE_HASH_PREFIX]` | Swapped range / `+HASH│` patch marker (auto-corrected) |
197
+ | `[E_BAD_ENCODING]`/`[E_DECODE_FAILED]` | Encoding / decode failed |
198
+ | `[E_NOT_OBSERVED]`/`[E_RANGE_STALE]`/`[E_RANGE_UNSERVED]`/`[E_RANGE_UNVERIFIED]` | Served-state miss — echoed fresh `HASH│content` |
199
+ | `[E_UNDO_STALE]`/`[E_UNDO_UNAVAILABLE]` | Undo stale / unavailable |
200
+ | `[E_NOOP_LOOP]`/`[E_BATCH_ABORT]` | 3× same no-op / atomic batch fail → nothing written |
201
+
202
+ Full list in `src/` — every rejection echoes fresh rows, no `read` needed.
291
203
 
292
204
  ## Comparison
293
205
 
294
- ### Capability comparison
295
-
296
- | | **dsh-better-edit** (this) | @oh-my-pi/hashline | `str_replace` (Claude Code / Codex) |
206
+ | | **dsh-better-edit** | @oh-my-pi/hashline | `str_replace` |
297
207
  | --- | --- | --- | --- |
298
- | Layer | dsh tools: `read` / `read_skill` / `edit` / `undo_last_edit` | patch-engine library: `Patcher` / `Patch` / `Filesystem` / `SnapshotStore` | built-in `str_replace` |
299
- | Address format | `HASH│` — 3-char content hash, no line number | `[path#tag]` — full-file content tag + line numbers | text match |
300
- | Whitespace-insensitive anchors | ✅ all ASCII whitespace stripped — survives `prettier`/`black`/`eslint --fix` | ~ n/a (anchors are line numbers) | ❌ |
301
- | Duplicate lines | ✅ unique per line (collision-resolved); ambiguity → `[E_AMBIGUOUS_ANCHOR]` | ~ position-based — repeats fine, position unverified | ❌ first occurrence |
302
- | Verified against what the model saw | ✅ every resolved line, per session — `[E_RANGE_STALE]`/`[E_RANGE_UNSERVED]` reject before write | ~ seen-lines provenance + file-version tag (H7) | ❌ first match wins |
303
- | Stale interior | ✅ reject + fresh anchors (`[E_RANGE_STALE]`) | ~ recovery-with-warning, else `MismatchError` | ❌ may overwrite |
304
- | Blind edit — lines never shown | ✅ hard reject (`[E_RANGE_UNVERIFIED]` / `[E_RANGE_UNSERVED]`) | ~ reject when seen-lines recorded (H7) | ❌ |
305
- | Batch atomicity | ✅ `edit` multi-item — all-or-nothing, `[E_BATCH_ABORT]` | ✅ multi-section preflight (H8) | ❌ |
306
- | Undo (persisted) | ✅ survives restarts | ❌ none | ❌ |
307
- | Sub-agent session isolation | ✅ session-keyed served state | ~ | — |
308
- | Deterministic battery | ✅ 23/23 | ✅ 10/10 library (own seam) | — |
309
- | Runtime | dsh (Node) | Bun ≥ 1.3.14 (TS source) | — |
310
-
311
- > `~` = occasionally / inconsistently. `—` = not specified / not applicable.
312
-
313
- ### Different jobs, same lineage
314
-
315
- Both this plugin and `@oh-my-pi/hashline` descend from the harness-problem insight that
316
- the model should never re-type old code, but they are different layers.
317
-
318
- `@oh-my-pi/hashline` is a **patch-language library**: `[path#tag]` headers bind every hunk
319
- to a full-file content hash, `PUT N.=M:` addresses lines by number, and it ships multi-hunk
320
- documents, a pluggable filesystem for any backend (disk, in-memory, network), and
321
- session-aware 3-way-merge recovery on stale tags. Its payload per edit is lighter and it cannot
322
- be confused by repeated text — the line number is unambiguous.
323
- This plugin is a **dsh tool pair**: `read` hands the model 3-char content hashes, `edit`
324
- takes two of them, and every resolved line is verified against the served state — no line
325
- numbers to renumber, no tag to refetch, a wrong anchor can never land on the wrong line,
326
- and `undo_last_edit` survives restarts. Its trade-offs: a JSON envelope per edit costs a
327
- little payload, and it lives inside dsh (Node) rather than as a standalone patcher (Bun). Pick
328
- hashline-the-library for a cross-backend patch format; pick hashline-the-tool for verified,
329
- content-addressed edits in your agent. Syntax-aware structural edits and file-lifecycle operations
330
- remain outside this verified line-range contract.
331
-
332
- ### What you get
333
-
334
- - **Verified before it writes** — every line of the resolved range is checked against served rows; stale or never-served interiors are hard-rejected (`[E_RANGE_STALE]`/`[E_RANGE_UNSERVED]`/`[E_RANGE_UNVERIFIED]`) and re-served as fresh anchors.
335
- - **Session-keyed** — sub-agent serves never validate the main session's edits and vice versa.
336
- - **Drift notices** — served territory outside the range that changed on disk is reported once per episode, not as a warning.
337
- - **Chained without re-reads** — diff, auto-read, and rejection rows all count as serves.
338
- - **Atomic batch** — up to 32 same-file edits in one `edit` call, all-or-nothing with `[E_BATCH_ABORT]`.
339
- - **Formatter-tolerant** — ASCII-whitespace-insensitive anchors survive re-indents; unique by construction (bitset probing).
340
-
341
- ### Correctness in edge cases
342
-
343
- The battery below measures *behavior*, where the two hashline implementations actually
344
- diverge. These are the real failure modes from the harness-problem literature, and what
345
- each tool does when they hit:
346
-
347
- | Edge case | hashline `edit` (this) | @oh-my-pi/hashline patch |
348
- | --- | --- | --- |
349
- | Wrong address (off-by-one anchor / line number) | **Impossible** — anchors resolve to specific lines; every resolved line is verified against served state, rejected before anything is written | **Possible** — a wrong line number against a current tag applies silently at the wrong place; the tag proves the file version, never the lines |
350
- | File changed on disk after the model's view | Hard reject + fresh anchors echoed (reject-and-serve); retry needs no `read` | Tag mismatch → refuse **or** best-effort 3-way merge onto unknown current content, with an explicit recovery banner |
351
- | An edit above shifts the file | Nothing shifts — anchors are content addresses; the diff serves fresh anchors | **Every edit renumbers** — the format's own #1 rule is "re-ground after every edit"; the model carries the bookkeeping |
352
- | Repeated / identical text | Per-line hashes are unique (collision-resolved); ambiguity → `[E_AMBIGUOUS_ANCHOR]` | Position-based, so repeats don't confuse it — but the position itself is unverified |
353
- | Lines never shown to the model | `[E_RANGE_UNSERVED]` — hard reject with fresh anchors | Undisplayed hunks rejected when seen-lines are recorded — same reliance on the model knowing what it saw |
354
- | Multi-edit batch fails mid-way | `edit` multi-item — atomic, all-or-nothing; the failing item is echoed as fresh serves | Multi-section patches preflighted up front — also atomic |
355
-
356
- > The oh-my-pi payload saving is a lighter wire format; the table above is what that format
357
- > asks the model to hold in its head instead — renumbering, tag-chasing — the
358
- > exact component that fails most with replace-style edits. This plugin's contract is:
359
- > a wrong edit cannot land, and any rejection needs no re-read. Both engines gate the same guarantee — **stale edits are detected, never silently applied** — with different policies when drift is found (recover-with-warning vs fail-closed rejection).
360
-
361
- ### Reproducible benchmark
362
-
363
- The claims above are measured, not asserted. Two deterministic batteries — no LLM in the
364
- loop, no sampling: a run either reproduces or it doesn't.
365
-
366
- **Tool battery — 23 scenarios (2026-08-17):**
367
-
368
- | vs expected verdict | correct | silent data-loss cases |
369
- | --- | --: | --: |
370
- | **dsh-better-edit** (same algorithm as pi-better-edit 1.1.4) | **23/23** | 0 |
371
-
372
- Reproduce via upstream: `npm run eval` in `pi-better-edit` (this plugin shares the hashline algorithm byte-for-byte). Library battery for `@oh-my-pi/hashline` is 10/10 separately.
373
-
374
- Full method, per-scenario tables, and limitations: upstream [benchmarks/README.md](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/README.md)
375
- and [benchmarks/results/](https://github.com/Rianico/pi-better-edit/tree/main/benchmarks/results).
376
-
377
- > See [Configuration](#configuration) under [Quick Start](#quick-start) for guidance overrides and store tenancy.
208
+ | Address | `HASH│` 3-char canon | `[path#tag]` + line | text match |
209
+ | Whitespace-insen. | ✅ | ~ n/a | ❌ |
210
+ | Duplicate lines | ✅ unique | ~ pos | ❌ first |
211
+ | Verified vs served | ✅ every line | ~ file tag | ❌ |
212
+ | Blind edit | ✅ reject | ~ | ❌ |
213
+ | Batch atomic | ✅ | ✅ | ❌ |
214
+ | Undo | ✅ | ❌ | ❌ |
215
+ | Battery | 23/23 | 10/10 | — |
216
+
217
+ `~` partial, `—` n/a. Same lineage — patch library vs dsh tool pair; pick by seam.
218
+
219
+ **Edge cases:** wrong anchor impossible (verified), disk drift → reject+serve, shift above → nothing moves, repeats → unique/ambiguous, unseen → reject, batch → atomic. See upstream [benchmarks](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/README.md).
220
+
221
+ **Battery:** `23/23` tool, `10/10` library (upstream `npm run eval`, same algorithm).
378
222
 
379
223
  ## How Anchors Work
380
224
 
381
- Each line is canonicalized (all ASCII whitespace — spaces, tabs, carriage returns, and
382
- line feeds — stripped) and hashed with [xxhash-wasm](https://github.com/jungomi/xxhash-wasm)
383
- (xxHash32), then mapped to a 3-character string over `A-Za-z0-9` — 62³ = 238,328 possible
384
- anchors. Canonicalization keeps anchors stable across formatting passes and editor-save
385
- cycles: a line that changes only in ASCII whitespace keeps its anchor, so external linting
386
- between edits does not invalidate it. Everything that is not ASCII whitespace stays
387
- significant — string contents, regex classes, comments, quotes, semicolons, and Unicode
388
- whitespace (NBSP) all rotate the anchor. One caveat: ASCII whitespace *inside* string
389
- literals and regexes is stripped too, so a whitespace-only change within a string is
390
- invisible to verification — benign in practice because formatters never alter string
391
- contents. Token-level edits (quote style, semicolons, brace placement) therefore still
392
- reject as stale.
393
-
394
- The alphabet is sized for an LLM consumer — the model tokenizes rather than squinting at
395
- glyphs, so case and digits are all included. The URL-safe specials `-` and `_` are
396
- deliberately excluded: a hash starting with `-` is shape-identical to a diff-preview
397
- deletion row, and `-`/`_` at a line start are markdown-active, inviting mis-copying.
398
-
399
- Anchors are unique by construction. If a line's base hash collides with an already-assigned
400
- hash, the next free hash is allocated from a bitset by probing with a stride coprime to the
401
- hash space (O(1) amortized; the stride is 62² + 62 + 1, so runs of blank lines or repeated
402
- `}` land on anchors that differ in all three characters). Every line therefore gets a
403
- unique anchor; two byte-identical lines never share one. The same guarantee sets the file
404
- size cap: at most 238,328 lines per file, beyond which `read` and `edit` reject with
405
- `[E_FILE_TOO_LARGE]` (use `write` for very large files).
406
-
407
- Hashes live in a persistent per-file store
408
- (`<workspace>/.dsh_better_edit/hash-store.sqlite`, honoring `XDG_CONFIG_HOME` on
409
- non-Windows) that keeps the hashes of unchanged lines across edits.
410
-
411
- ## How It Replaces the Built-in Tools
412
-
413
- dsh's tool registry resolves per scope: an agent sees `agent → preset → global`, and its **own**
414
- layer always wins. The built-in `read`/`edit` live on the agent-preset layer, so a plain global
415
- registration cannot replace them. This plugin:
416
-
417
- 1. Mounts as a host-plane Cordis plugin via its `cordis.patch.yml` bundle patch.
418
- 2. On `agent/session-start`, registers the hashline tools **and** the `tool:read` / `tool:edit`
419
- prompt sections on the agent's own scope layer — they shadow the preset's built-ins for that
420
- agent and unwind automatically when the agent is disposed.
421
- 3. Leaves the built-in `write` in place: a scoped `tools/pre-execute` listener rejects an exact
422
- same-session/path/line served-anchor echo before dispatch, and `tools/post-execute` appends the
423
- hashline auto-read to successful results.
424
-
425
- ## Store
426
-
427
- Hash snapshots, served-state rows, and undo history live in one SQLite store — **central by default** (`$DSH_HOME/plugins/dsh-better-edit/runtime/<name>-<hash8>/hash-store.sqlite`, `ls`-readable with `.wsPath` sidecar). Legacy co-located `<workspace>/.dsh_better_edit/` is still supported via `storeDir: workspace` in `config.yaml` and is copied once on first central open. Parallel sessions in different workspaces keep separate stores (the session cwd is carried through each tool call), so one project's anchors and undo history never leak into another's. Outside a tool call (tests, previews) the store falls back to the shared DeepSeek Harness home (`$DSH_HOME/plugins/dsh-better-edit/hash-store.sqlite`).
428
-
429
- A 7-day TTL prunes served rows; `undo_ttl_s` (default 7d, `-1` forever) prunes undo clones; missing-file snapshots are pruned on throttled `openStore`; corrupt stores are quarantined and rebuilt automatically. The central janitor (`apply` + `agent/session-start` throttled >24h) evicts `mtime>storeMaxAgeS` (default 2592000 s = 30 days) then LRU to `count<100 && sum<500MB`, never deleting live `hash(workspaceCwd)`, with `wal_checkpoint(TRUNCATE)` on close. DB files are disposable caches — safe to delete, rebuilt on next `read`.
225
+ `canon(line)` strips ASCII whitespace → `xxHash32` → `A-Za-z0-9` 3-char (62³). Stable across `prettier`; Unicode/strings stay significant except ASCII whitespace inside strings (linter-only). `stride=62²+62+1` probes bitset → unique; cap `238,328`. Store `hash-store.sqlite` per workspace (central, honoring `XDG_CONFIG_HOME`); 7-day served TTL, janitor `storeMaxAgeS/LRU` + `wal_checkpoint`.
226
+
227
+ ## How It Replaces Built-ins
228
+
229
+ dsh resolves `agent → preset → global`; built-ins live on preset. Plugin via `cordis.patch.yml`: at `agent/session-start` registers `read/edit` on agent layer (shadows, auto-unwinds); `write` stays with `pre-execute` guard + `post-execute` auto-read.
430
230
 
431
231
  ## Project Structure
432
232
 
433
233
  ```
434
234
  dsh-better-edit/
435
- ├── src/
436
- │ ├── hashline/ # hash + served-state core (ported from pi-better-edit)
437
- │ ├── tool-read.ts # read — HASH│content, offset/limit paging
438
- │ ├── tool-edit.ts # edit — {path, edits:[[hash,hash,text]]}, reject-and-serve
439
- │ ├── tool-undo.ts # undo_last_edit
440
- │ ├── sandbox.ts # FsSandboxController mirror (sandbox_permissions/justification)
441
- │ ├── write-hook.ts # auto-read appended to write results
442
- │ ├── served-store.ts # per-workspace SQLite store (node:sqlite)
443
- │ └── workspace.ts # session-cwd AsyncLocalStorage carrier
444
- ├── benchmark/ # frozen 103-line fixture (reference upstream for reproducible numbers)
445
- │ └── corpus/ # frozen 103-line fixture
446
- ├── test/ # ported + regression tests
447
- ├── assets/ # logo + banner
448
- ├── cordis.patch.yml # bundle patch
449
- └── package.json # dsh.bundle manifest
235
+ ├── src/hashline/ # hash + served core
236
+ ├── src/tool-*.ts # read / edit / undo
237
+ ├── src/served-store.ts # SQLite store
238
+ ├── benchmark/corpus/ # 103-line fixture
239
+ ├── test/ # 108 files, 1222 tests
240
+ ├── assets/ # logo + banner
241
+ └── cordis.patch.yml
450
242
  ```
451
243
 
452
244
  ## Development
453
245
 
454
246
  ```sh
455
- npm install
456
- npm run typecheck # tsc --noEmit
457
- npm test # vitest run
458
- npm run build # tsc → lib/
247
+ pnpm install
248
+ pnpm typecheck # tsc --noEmit
249
+ pnpm test # vitest run
250
+ pnpm benchmark # hash probe + session envelope (reads/retries/tokens)
459
251
  ```
460
252
 
461
- ### Releasing (tag-first)
253
+ ## Benchmark
462
254
 
463
- ```sh
464
- npm run release -- 0.3.1 # bump + CHANGELOG move + commit + tag + push → GitHub release
465
- npm publish --registry https://registry.npmjs.org # blocked until the version is tagged
466
- ```
255
+ 103-line file, 12 replacements (8×1 + 4×3/6/10/15), `cl100k_base`. `hashline` vs `str_replace` vs `oh-my-pi` `seq/batch`. Upstream is source of truth — same algorithm byte-for-byte.
467
256
 
468
- `npm run release` bumps `package.json`/lockfile, moves the CHANGELOG `[Unreleased]` section to the
469
- version, commits, tags `vX.Y.Z`, and pushes — the tag push creates the GitHub release from the
470
- changelog. `npm publish` refuses to run until that tag exists (prepublishOnly gate), so every npm
471
- version is always already tagged and released.
257
+ | Criterion | hashline | str_replace | seq / batch |
258
+ | --- | :---: | :---: | :---: |
259
+ | `old_string` echoed | never | every edit | never |
260
+ | 12-edit saved | **31%** | 0% | **42% / 53%** |
261
+ | multi-line saved | **29–47%** | 0% | **40–53%** |
262
+ | 5× output cost | **~1.4× less** | 1× | **~1.7×/~2.1× less** |
263
+ | Verified | 100% | none | tag only |
472
264
 
473
- ## Benchmark
265
+ | Scenario | hashline | str_replace |
266
+ | --- | ---: | ---: |
267
+ | `1×8` | 309 | 324 |
268
+ | `3–15×4` | 393 | 691 |
269
+ | **TOTAL ×12** | **702** | **1015** |
270
+
271
+ Saved **313 (31%)**. Reproduce: upstream `npm run benchmark`. See [`pi-better-edit/benchmark/README.md`](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/README.md).
474
272
 
475
- Measured on the same 103-line file with the same 12 replacements (8 single-line, 4 multi-line of
476
- 3/6/10/15 lines), tokenized with the pinned `js-tiktoken` `cl100k_base`. Three arms emit the same
477
- replacements: this plugin's `edit` (two 3-char anchors via `edits` tuple), a `str_replace` tool (old text echoed
478
- verbatim), and [`@oh-my-pi/hashline`](https://www.npmjs.com/package/@oh-my-pi/hashline) in both of
479
- its modes — one `[path#tag]` section per edit (`seq`) and one multi-hunk batch document (`batch`). Same hashline algorithm, so we reference the upstream reproducible results:
480
-
481
- | Criterion | hashline | str_replace | oh-my-pi seq / batch |
482
- | ----------- | :---: | :---: | :---: |
483
- | Replaced text sent over the wire | ✅ never | ❌ every edit | ✅ never |
484
- | Output tokens saved (12-edit session) | ✅ **31%** | ❌ 0% | ✅ **42% / 53%** |
485
- | Multi-line range savings (3–15 lines) | ✅ **29–47%** | ❌ 0% | ✅ **40–53%** |
486
- | Effective cost at 5× output pricing | ✅ **~1.4× less** | ❌ 1× | ✅ **~1.7× / ~2.1× less** |
487
- | Ranges verified against served state | ✅ 100% | ❌ none | ~ file version only |
488
- | Line numbers the model must track | ✅ none — content anchors | ✅ none — text match | ❌ renumber every edit |
489
- | Deterministic, reproducible locally | ✅ via upstream `npm run benchmark` | — | — |
490
-
491
- | Scenario | Lines | hashline | str_replace | oh-my-pi seq | oh-my-pi batch |
492
- | --- | :---: | :---: | :---: | :---: | :---: |
493
- | single-line ×8 | 1 | 309 | 324 | 241 | — |
494
- | multi-line ×4 | 3–15 | 393 | 691 | 349 | — |
495
- | **TOTAL ×12** | | **702** | **1015** | **590** | **480** |
496
-
497
- Saved vs `str_replace`: hashline **313 (31%)** · oh-my-pi per-edit **425 (42%)** · oh-my-pi batch **535 (53%)**.
498
-
499
- Upstream is the source of truth for reproducibility: [`pi-better-edit/benchmark/README.md`](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/README.md) and [`benchmarks/results/`](https://github.com/Rianico/pi-better-edit/tree/main/benchmarks/results). This plugin shares the hashline algorithm byte-for-byte, so we do not re-run locally.
500
-
501
- > **Scope & honesty.** The benchmark measures **request-payload tokens** — what the model emits per
502
- > edit call — with identical read traffic excluded (it cancels) and identical replacement text.
503
- > It does **not** model transcription failure and retries, which is where the real-world gap is
504
- > largest. The correctness gap behind those numbers is spelled out above in [Correctness in edge cases](#correctness-in-edge-cases).
273
+ > **Scope & honesty.** Benchmark is **request-payload tokens** (reads cancel, replacement text identical). No transcription-failure model — real gap larger; see [edge cases](#comparison).
505
274
 
506
275
  ## Roadmap
507
276
 
508
- **Current state (0.3.1):** hashline `edit` with merged payload `{path, edits:[[hash,hash,text]]}`, whitespace-insensitive anchors, orphan healing, per-workspace store, 674 tests.
277
+ **Current `0.6.1`:** pos-free `resist`/`strict` + tombstone/canons/epoch, per-session `(session,path)` store, `1222` tests, `9/9` harness.
509
278
 
510
279
  <details><summary>Next</summary>
511
280
 
512
- - Verify 0.3.1 live in a dsh session after the orphan-healing + canon changes.
513
- - Keep benchmark reference in sync with upstream releases (algorithm is shared).
514
- - Re-check plugin wiring against the next dsh release (pinned to `0.1.0-rc.6`; dsh is in developer preview and promises breaking changes).
281
+ - Keep `benchmark/run.mjs` in sync with `ADR-0013` (reads/retries/tokens per session)
282
+ - Re-check wiring vs next `dsh` (pinned `0.1.0-rc.6`)
283
+ - `README.zh.md` parity
515
284
 
516
285
  </details>
517
286
 
518
287
  ## Contributing
519
288
 
520
- See [CONTRIBUTING.md](CONTRIBUTING.md) (or just open an [issue](https://github.com/Rianico/dsh-better-edit/issues)).
521
- The most valuable contributions right now are more edge-case tests for the
522
- served-state verification.
289
+ See [CONTRIBUTING.md](CONTRIBUTING.md). Most valuable: more served-state edge-case tests.
523
290
 
524
291
  ## License
525
292
 
526
- MIT License — see [LICENSE](LICENSE) for details. Ported from pi-better-edit.
293
+ MIT — see [LICENSE](LICENSE).
527
294
 
528
295
  ## Acknowledgments
529
296
 
530
- Hash-anchored editing descends from Can Bölük's
531
- [*The Harness Problem*](https://stencil.so/blog/the-harness-problem) — the post that showed the
532
- harness, not the model, is the bottleneck, and that anchored edits beat search-and-replace. This
533
- project stands on the shoulders of:
534
-
535
- - [**pi-hashline-edit**](https://github.com/RimuruW/pi-hashline-edit) by RimuruW — the original
536
- pi-coding-agent extension that introduced hash anchors and the strict-semantics
537
- policy.
538
- - [**pi-hashline-edit-pro**](https://github.com/YuGiMob/pi-hashline-edit-pro) by YuGiMob —
539
- the hardened fork this project is self-maintained from (3-char hashes, collision
540
- resolution, served-state verification, persisted undo).
541
- - [**pi-better-edit**](https://github.com/Rianico/pi-better-edit) — the upstream this project tracks. The hashline core is ported; the tool layer is rewritten on dsh's plugin API.
542
- - [**@oh-my-pi/hashline**](https://www.npmjs.com/package/@oh-my-pi/hashline)
543
- by can1357 — the original oh-my-pi implementation and the hashline patch-language concept.
544
-
545
- Related reading: [Hash anchors + Myers diff + single-token anchors
546
- (dirac.run)](https://dirac.run/posts/hash-anchors-myers-diff-single-token) (a design review of the
547
- O(S+R) → O(R) edit-call saving) and an independent
548
- [hashline-vs-replace benchmark](https://nwyin.com/blogs/hashline-vs-replace-edit-bench.html).
297
+ From Can Bölük's [*The Harness Problem*](https://stencil.so/blog/the-harness-problem). Thanks to [pi-hashline-edit](https://github.com/RimuruW/pi-hashline-edit), [pi-hashline-edit-pro](https://github.com/YuGiMob/pi-hashline-edit-pro), [pi-better-edit](https://github.com/Rianico/pi-better-edit), [@oh-my-pi/hashline](https://www.npmjs.com/package/@oh-my-pi/hashline). Reading: [hash-anchors](https://dirac.run/posts/hash-anchors-myers-diff-single-token).
549
298
 
550
299
  ---
551
300
 
@@ -556,5 +305,5 @@ O(S+R) → O(R) edit-call saving) and an independent
556
305
  ---
557
306
 
558
307
  <p align="center">
559
- <strong>⭐ If hashline editing made your agent edit better, give it a star!</strong>
308
+ <strong>⭐ If hashline made your agent edit better, give it a star!</strong>
560
309
  </p>
package/lib/index.js CHANGED
@@ -1,26 +1,10 @@
1
- /**
2
- * dsh-better-edit — hash-anchored read/edit/batch_edit/undo_last_edit for
3
- * DeepSeek Harness, a dsh port of pi-hashline-edit-lsz.
4
- *
5
- * Cordis host-plane plugin (mounted by the bundle's cordis.patch.yml). On
6
- * `agent/session-start` it registers the hashline tools and prompt sections on
7
- * the AGENT's own scope layer, so they shadow the preset's built-in `read` /
8
- * `edit` for that agent (nearest layer wins in dsh's tool registry) and unwind
9
- * automatically when the agent is disposed. The built-in `write` stays in
10
- * place; scoped pre/post listeners reject copied same-line served anchors
11
- * before dispatch and append a fresh hashline preview after successful writes.
12
- *
13
- * The four `tool:*` guidance sections resolve per agent preset from override
14
- * files in the shared home (see `src/guidance.ts`); deployments without the
15
- * `agentPresets` service keep the compiled defaults unchanged.
16
- * @module dsh-better-edit
17
- */
18
1
  import { ctxFsIO } from "./fs-bridge.js";
19
2
  import { FsSandboxController } from "./sandbox.js";
20
- import { registerReadTool } from "./tool-read.js";
21
- import { registerEditTool } from "./tool-edit.js";
3
+ import { buildReadTool } from "./tool-read.js";
4
+ import { buildEditTool } from "./tool-edit.js";
22
5
  import { registerUndoTool } from "./tool-undo.js";
23
6
  import { registerWriteHook } from "./write-hook.js";
7
+ import { createSelfHealWatcher } from "./self-heal.js";
24
8
  import { initHasher } from "./hashline/hash-assign.js";
25
9
  import { composeSections, ensurePresetGuidance, GUIDANCE_SECTIONS, } from "./guidance.js";
26
10
  import { configDir } from "./store/index.js";
@@ -80,11 +64,24 @@ function installAgentTools(rootCtx, agent) {
80
64
  // exec.agent.session.header.cwd.
81
65
  const io = ctxFsIO(rootCtx.fs, rootCtx);
82
66
  const disposers = [];
83
- disposers.push(registerReadTool(rootCtx, agent.ctx, io));
84
67
  const sandbox = new FsSandboxController(rootCtx);
85
- disposers.push(registerEditTool(rootCtx, agent.ctx, io, sandbox));
68
+ // Keep owned definitions by reference for self-heal identity check
69
+ const hashReadDef = buildReadTool(io);
70
+ disposers.push(agent.ctx.tools.register(hashReadDef));
71
+ const hashEditDef = buildEditTool(io, sandbox);
72
+ disposers.push(agent.ctx.tools.register(hashEditDef));
86
73
  disposers.push(registerUndoTool(rootCtx, agent.ctx, io, sandbox));
87
74
  disposers.push(registerWriteHook(rootCtx, agent.ctx, io));
75
+ const toolsSvc = rootCtx.get("tools");
76
+ disposers.push(createSelfHealWatcher({
77
+ agentId: agent.id,
78
+ rootCtx,
79
+ agent,
80
+ agentCtx: agent.ctx,
81
+ toolsSvc,
82
+ hashReadDef,
83
+ hashEditDef,
84
+ }));
88
85
  // Shadow the preset's built-in tool guidance with the hashline
89
86
  // contract. Same section names on the agent's own layer win over the
90
87
  // preset's; text and order come from the per-preset resolution.
@@ -0,0 +1,101 @@
1
+ /**
2
+ * Self-healing watcher for hash-anchored tools.
3
+ * Restores `read`/`edit` on the agent's own scope layer if an external
4
+ * preset deletes them (e.g. router-standard stage advance).
5
+ * See Rianico/dsh-better-edit#43.
6
+ * @module dsh-better-edit/self-heal
7
+ */
8
+ export function createSelfHealWatcher(options) {
9
+ const { agentId, rootCtx, agent, agentCtx, toolsSvc, hashReadDef, hashEditDef, healMinIntervalMs = 1000, } = options;
10
+ let lastHealAt = 0;
11
+ let healCount = 0;
12
+ let selfHealDisabled = false;
13
+ const stop = agentCtx.on("tools/change", () => {
14
+ try {
15
+ if (selfHealDisabled)
16
+ return;
17
+ // SAFETY: toolsSvc is the DSH tools service — shape is `layers.scoped: Map<agent, {tools}>` per cordis internals; narrow at boundary
18
+ const layer = toolsSvc
19
+ ?.layers?.scoped?.get?.(agent)?.tools;
20
+ if (!layer)
21
+ return;
22
+ const currentRead = layer?.get?.("read") ?? layer?.data?.get?.("read");
23
+ const currentEdit = layer?.get?.("edit") ?? layer?.data?.get?.("edit");
24
+ const readOk = currentRead === hashReadDef;
25
+ const editOk = currentEdit === hashEditDef;
26
+ if (readOk && editOk)
27
+ return;
28
+ const now = Date.now();
29
+ if (now - lastHealAt < healMinIntervalMs)
30
+ return;
31
+ if (healCount >= 2) {
32
+ selfHealDisabled = true;
33
+ try {
34
+ rootCtx.logger.error(`dsh-better-edit: repeated takeover of edit detected; self-heal disabled for agent ${agentId} \u2014 edit will remain built-in for this session \u2014 see Rianico/dsh-better-edit#43`);
35
+ }
36
+ catch {
37
+ // ignore — logger may throw in mock
38
+ }
39
+ return;
40
+ }
41
+ healCount++;
42
+ lastHealAt = now;
43
+ const restoreRead = !readOk;
44
+ const restoreEdit = !editOk;
45
+ const restoreCount = healCount;
46
+ queueMicrotask(() => {
47
+ try {
48
+ // SAFETY: re-read layer inside microtask — same shape as above
49
+ const currentLayer = toolsSvc
50
+ ?.layers?.scoped?.get?.(agent)?.tools;
51
+ if (!currentLayer)
52
+ return;
53
+ if (restoreEdit) {
54
+ try {
55
+ currentLayer?.data?.delete?.("edit");
56
+ }
57
+ catch {
58
+ // ignore — best-effort delete of intruding entry
59
+ }
60
+ try {
61
+ agentCtx.tools.register(hashEditDef);
62
+ }
63
+ catch (e) {
64
+ rootCtx.logger.warn(`dsh-better-edit: self-heal failed for agent ${agentId}: ${e instanceof Error ? e.message : String(e)} \u2014 see Rianico/dsh-better-edit#43`);
65
+ return;
66
+ }
67
+ rootCtx.logger.warn(`dsh-better-edit: restored hash-anchored edit after external takeover \u2014 agent ${agentId} (${restoreCount}/2) \u2014 see Rianico/dsh-better-edit#43`);
68
+ }
69
+ if (restoreRead) {
70
+ try {
71
+ currentLayer?.data?.delete?.("read");
72
+ }
73
+ catch {
74
+ // ignore — best-effort delete of intruding entry
75
+ }
76
+ try {
77
+ agentCtx.tools.register(hashReadDef);
78
+ }
79
+ catch (e) {
80
+ rootCtx.logger.warn(`dsh-better-edit: self-heal failed for agent ${agentId}: ${e instanceof Error ? e.message : String(e)} \u2014 see Rianico/dsh-better-edit#43`);
81
+ return;
82
+ }
83
+ rootCtx.logger.warn(`dsh-better-edit: restored hash-anchored read after external takeover \u2014 agent ${agentId} (${restoreCount}/2) \u2014 see Rianico/dsh-better-edit#43`);
84
+ }
85
+ }
86
+ catch (error) {
87
+ rootCtx.logger.warn(`dsh-better-edit: self-heal failed for agent ${agentId}: ${error instanceof Error ? error.message : String(error)} \u2014 see Rianico/dsh-better-edit#43`);
88
+ }
89
+ });
90
+ }
91
+ catch (error) {
92
+ try {
93
+ rootCtx.logger.warn(`dsh-better-edit: self-heal failed for agent ${agentId}: ${error instanceof Error ? error.message : String(error)} \u2014 see Rianico/dsh-better-edit#43`);
94
+ }
95
+ catch {
96
+ // ignore — logger may throw in mock
97
+ }
98
+ }
99
+ });
100
+ return stop;
101
+ }
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Self-healing watcher for hash-anchored tools.
3
+ * Restores `read`/`edit` on the agent's own scope layer if an external
4
+ * preset deletes them (e.g. router-standard stage advance).
5
+ * See Rianico/dsh-better-edit#43.
6
+ * @module dsh-better-edit/self-heal
7
+ */
8
+ export interface SelfHealOptions {
9
+ agentId: string;
10
+ rootCtx: {
11
+ logger: {
12
+ warn(msg: string): void;
13
+ error(msg: string): void;
14
+ };
15
+ get(service: string): any;
16
+ };
17
+ agent: unknown;
18
+ agentCtx: {
19
+ tools: {
20
+ register(def: unknown): () => void;
21
+ };
22
+ on(event: string, handler: () => void): () => void;
23
+ };
24
+ toolsSvc: unknown;
25
+ hashReadDef: unknown;
26
+ hashEditDef: unknown;
27
+ healMinIntervalMs?: number;
28
+ }
29
+ export declare function createSelfHealWatcher(options: SelfHealOptions): () => void;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-better-edit",
3
- "version": "0.6.1",
3
+ "version": "0.6.3",
4
4
  "type": "module",
5
5
  "description": "Hash-anchored read/edit/undo_last_edit tools for DeepSeek Harness (dsh). Every line gets a unique 3-char hash (A-Za-z0-9) that stays stable across edits; stale or ambiguous anchors are rejected, never fuzzy-matched. Undo persists across restarts.",
6
6
  "main": "lib/index.js",
@@ -84,12 +84,12 @@
84
84
  "@commitlint/cli": "^21.2.2",
85
85
  "@commitlint/config-conventional": "^21.2.2",
86
86
  "@deepseek-ai/cordis": "^4.0.1",
87
- "@deepseek-ai/dsh-agent": "0.1.0-rc.6",
88
- "@deepseek-ai/dsh-fs": "0.1.0-rc.6",
89
- "@deepseek-ai/dsh-home-paths": "0.1.0-rc.6",
90
- "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
91
- "@deepseek-ai/dsh-session": "0.1.0-rc.6",
92
- "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
87
+ "@deepseek-ai/dsh-agent": "0.1.1-rc.2",
88
+ "@deepseek-ai/dsh-fs": "0.1.1-rc.2",
89
+ "@deepseek-ai/dsh-home-paths": "0.1.1-rc.2",
90
+ "@deepseek-ai/dsh-sandbox": "0.1.1-rc.2",
91
+ "@deepseek-ai/dsh-session": "0.1.1-rc.2",
92
+ "@deepseek-ai/dsh-tools": "0.1.1-rc.2",
93
93
  "@semantic-release/changelog": "^7.0.0",
94
94
  "@semantic-release/git": "^11.0.1",
95
95
  "@semantic-release/github": "^12.0.9",