dsh-better-edit 0.6.3 → 0.8.0

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.
Files changed (57) hide show
  1. package/CHANGELOG.md +59 -15
  2. package/README.md +78 -71
  3. package/README.zh.md +83 -83
  4. package/lib/canonical-path.js +4 -1
  5. package/lib/constants.js +5 -1
  6. package/lib/contract.js +127 -33
  7. package/lib/edit-diff.js +1 -5
  8. package/lib/edit-response.js +5 -10
  9. package/lib/encoding.js +23 -6
  10. package/lib/file-encoding-state.js +54 -15
  11. package/lib/file-view.js +42 -53
  12. package/lib/fs-bridge.js +27 -16
  13. package/lib/fs-write.js +1 -1
  14. package/lib/guidance/materialize.js +1 -6
  15. package/lib/guidance/resolve.js +1 -1
  16. package/lib/hash-store.js +133 -43
  17. package/lib/hashline/anchor-pipeline.js +124 -93
  18. package/lib/hashline/hash-assign.js +65 -23
  19. package/lib/hashline/hash.js +6 -6
  20. package/lib/index.js +6 -0
  21. package/lib/mutation/engine.js +89 -31
  22. package/lib/mutation.js +14 -13
  23. package/lib/prompts.js +12 -11
  24. package/lib/read-and-serve.js +105 -19
  25. package/lib/render-text-warning.js +21 -0
  26. package/lib/sandbox.js +2 -5
  27. package/lib/self-heal.js +30 -27
  28. package/lib/session-view.js +161 -24
  29. package/lib/store-config.js +7 -2
  30. package/lib/store-lifecycle.js +7 -2
  31. package/lib/tool-edit.js +10 -6
  32. package/lib/tool-read.js +6 -9
  33. package/lib/tool-str-replace-editor.js +274 -0
  34. package/lib/tool-undo.js +8 -9
  35. package/lib/types/constants.d.ts +2 -0
  36. package/lib/types/contract.d.ts +106 -18
  37. package/lib/types/edit-response.d.ts +4 -0
  38. package/lib/types/encoding.d.ts +1 -1
  39. package/lib/types/file-encoding-state.d.ts +4 -1
  40. package/lib/types/file-view.d.ts +16 -1
  41. package/lib/types/hash-store.d.ts +12 -1
  42. package/lib/types/hashline/anchor-pipeline.d.ts +16 -6
  43. package/lib/types/hashline/hash-assign.d.ts +10 -2
  44. package/lib/types/hashline/index.d.ts +1 -1
  45. package/lib/types/mutation/engine.d.ts +2 -1
  46. package/lib/types/render-text-warning.d.ts +22 -0
  47. package/lib/types/self-heal.d.ts +2 -0
  48. package/lib/types/session-view.d.ts +13 -4
  49. package/lib/types/tool-str-replace-editor.d.ts +27 -0
  50. package/lib/types/undo-edit.d.ts +1 -1
  51. package/lib/types/utils.d.ts +7 -0
  52. package/lib/types/write-hook.d.ts +2 -2
  53. package/lib/undo-edit.js +6 -8
  54. package/lib/utils.js +23 -3
  55. package/lib/workspace-context.js +1 -1
  56. package/lib/write-hook.js +20 -23
  57. package/package.json +63 -57
package/CHANGELOG.md CHANGED
@@ -1,44 +1,88 @@
1
+ ## [0.8.0](https://github.com/Rianico/dsh-better-edit/compare/v0.7.1...v0.8.0) (2026-09-09)
2
+
3
+ ### Features
4
+
5
+ * **edit:** accept object-form edits entries ({remove_from, remove_to, replacement_text}), closes [#64](https://github.com/Rianico/dsh-better-edit/issues/64) ([#66](https://github.com/Rianico/dsh-better-edit/issues/66)) ([a14ef4c](https://github.com/Rianico/dsh-better-edit/commit/a14ef4cee1c4d8126f40516624b6811d57041bf8))
6
+ * **str-replace:** add governed editor shadow ([#67](https://github.com/Rianico/dsh-better-edit/issues/67)) ([a015629](https://github.com/Rianico/dsh-better-edit/commit/a0156296ce615069f10acf60e3d96c4dc3fa9e14))
7
+
8
+ ### Bug Fixes
9
+
10
+ * **script:** correct repo inference and headless dispatch for gh-release ([b517646](https://github.com/Rianico/dsh-better-edit/commit/b5176465f8363ff80bb48e96cdfa86e6254f2ebf)), closes [#51](https://github.com/Rianico/dsh-better-edit/issues/51)
11
+
12
+ ### Documentation
13
+
14
+ * **agents:** sync AGENTS.md — remove tag-first releasing, fix git guide and upstream cursor ([d1088d1](https://github.com/Rianico/dsh-better-edit/commit/d1088d1f43f151f80f204fc5189268a5945066f8))
15
+
16
+ ## [0.7.1](https://github.com/Rianico/dsh-better-edit/compare/v0.7.0...v0.7.1) (2026-09-06)
17
+
18
+ ### Bug Fixes
19
+
20
+ - **hashline:** retired hazard GC and stable reuse for anchor-space deadlock ([#59](https://github.com/Rianico/dsh-better-edit/issues/59)) ([2487c43](https://github.com/Rianico/dsh-better-edit/commit/2487c43e6d0ec8e5af15b42495bc4f8d7e3ca89a)), closes [#51](https://github.com/Rianico/dsh-better-edit/issues/51) [#51](https://github.com/Rianico/dsh-better-edit/issues/51) [#51](https://github.com/Rianico/dsh-better-edit/issues/51)
21
+
22
+ ### Documentation
23
+
24
+ - **context:** retired anchor replaces tombstone; add hazard card and epoch glossary ([#58](https://github.com/Rianico/dsh-better-edit/issues/58)) ([287b68e](https://github.com/Rianico/dsh-better-edit/commit/287b68efc97bea940fd881a8ca1e8755b2da311a)), closes [#51](https://github.com/Rianico/dsh-better-edit/issues/51)
25
+
26
+ ## [0.7.0](https://github.com/Rianico/dsh-better-edit/compare/v0.6.3...v0.7.0) (2026-09-06)
27
+
28
+ ### Features
29
+
30
+ - **session-view:** canon-deficit drift instead of hash rotation (Closes [#46](https://github.com/Rianico/dsh-better-edit/issues/46)) ([#50](https://github.com/Rianico/dsh-better-edit/issues/50)) ([44ba1b3](https://github.com/Rianico/dsh-better-edit/commit/44ba1b3ea3c33759c879363a7e18b4d718edd4d9)), closes [#68](https://github.com/Rianico/dsh-better-edit/issues/68)
31
+ - user/model audience split + glossary error codes ([#49](https://github.com/Rianico/dsh-better-edit/issues/49)) ([1559fc5](https://github.com/Rianico/dsh-better-edit/commit/1559fc5d135d006faa86aa656c166a5e3fa3be08)), closes [#48](https://github.com/Rianico/dsh-better-edit/issues/48) [#45](https://github.com/Rianico/dsh-better-edit/issues/45)
32
+
33
+ ### Bug Fixes
34
+
35
+ - **edit:** Gemma-4 tool-call bleed hardening + prompt channel wording (Closes [#47](https://github.com/Rianico/dsh-better-edit/issues/47)) ([#52](https://github.com/Rianico/dsh-better-edit/issues/52)) ([55e8d21](https://github.com/Rianico/dsh-better-edit/commit/55e8d21bcc57e87ee674c4d7484da0cd200e2e03)), closes [#55](https://github.com/Rianico/dsh-better-edit/issues/55)
36
+ - review follow-ups from 1.6.0 absorb (Closes [#55](https://github.com/Rianico/dsh-better-edit/issues/55)) ([#56](https://github.com/Rianico/dsh-better-edit/issues/56)) ([d6a9cbb](https://github.com/Rianico/dsh-better-edit/commit/d6a9cbb5ae071892dd88aefdaa6b9d875aa091e7))
37
+ - **served:** epoch lifecycle belongs to full reads (Closes [#48](https://github.com/Rianico/dsh-better-edit/issues/48)) ([#54](https://github.com/Rianico/dsh-better-edit/issues/54)) ([959f355](https://github.com/Rianico/dsh-better-edit/commit/959f355b0866a6a892dda2a149cc20c6505fc9ad)), closes [#69](https://github.com/Rianico/dsh-better-edit/issues/69)
38
+ - **served:** refresh canons on truncated serve records (Closes [#53](https://github.com/Rianico/dsh-better-edit/issues/53)) ([#57](https://github.com/Rianico/dsh-better-edit/issues/57)) ([1f8601c](https://github.com/Rianico/dsh-better-edit/commit/1f8601cc8b3608bc79acb82130abbe37990aef75))
39
+
40
+ ### Documentation
41
+
42
+ - **absorb:** record v1.6.0 checkpoint 87a17eb after T1-T4 ([8afba98](https://github.com/Rianico/dsh-better-edit/commit/8afba9842628e44a011c266956d8746725295c11))
43
+ - migrate CLAUDE.md to AGENTS.md with symlink ([4706b6e](https://github.com/Rianico/dsh-better-edit/commit/4706b6e15f6a0ca627059087e3f05953b7b2ae6e))
44
+
1
45
  ## [0.6.3](https://github.com/Rianico/dsh-better-edit/compare/v0.6.2...v0.6.3) (2026-09-05)
2
46
 
3
47
  ### Bug Fixes
4
48
 
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))
49
+ - **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
50
 
7
51
  ## [0.6.2](https://github.com/Rianico/dsh-better-edit/compare/v0.6.1...v0.6.2) (2026-09-03)
8
52
 
9
53
  ### Bug Fixes
10
54
 
11
- * **deps:** upgrade dsh dependencies to 0.1.1-rc.2 ([30e6029](https://github.com/Rianico/dsh-better-edit/commit/30e6029888fa517f20c640b7a38523a8a6148ccd))
55
+ - **deps:** upgrade dsh dependencies to 0.1.1-rc.2 ([30e6029](https://github.com/Rianico/dsh-better-edit/commit/30e6029888fa517f20c640b7a38523a8a6148ccd))
12
56
 
13
57
  ### Documentation
14
58
 
15
- * **readme:** compact rewrite — pos-free hero, round-trips, tokens ([dc468c5](https://github.com/Rianico/dsh-better-edit/commit/dc468c5ce9799ddf9578d92e715905701b2a95a1))
59
+ - **readme:** compact rewrite — pos-free hero, round-trips, tokens ([dc468c5](https://github.com/Rianico/dsh-better-edit/commit/dc468c5ce9799ddf9578d92e715905701b2a95a1))
16
60
 
17
61
  ## [0.6.1](https://github.com/Rianico/dsh-better-edit/compare/v0.6.0...v0.6.1) (2026-09-01)
18
62
 
19
63
  ### Bug Fixes
20
64
 
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)
65
+ - **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)
22
66
 
23
67
  ## [0.6.0](https://github.com/Rianico/dsh-better-edit/compare/v0.5.1...v0.6.0) (2026-08-31)
24
68
 
25
69
  ### Features
26
70
 
27
- * **edit:** render diff card after tool calling ([df7712c](https://github.com/Rianico/dsh-better-edit/commit/df7712cef265dfec424feefb60c19f833d380f9f))
28
- * **hashline:** remove boundaryDups auto-fix (Closes [#38](https://github.com/Rianico/dsh-better-edit/issues/38)) ([54d0bc6](https://github.com/Rianico/dsh-better-edit/commit/54d0bc6c9078fbcffa6f7a531e80e005774156a4))
71
+ - **edit:** render diff card after tool calling ([df7712c](https://github.com/Rianico/dsh-better-edit/commit/df7712cef265dfec424feefb60c19f833d380f9f))
72
+ - **hashline:** remove boundaryDups auto-fix (Closes [#38](https://github.com/Rianico/dsh-better-edit/issues/38)) ([54d0bc6](https://github.com/Rianico/dsh-better-edit/commit/54d0bc6c9078fbcffa6f7a531e80e005774156a4))
29
73
 
30
74
  ### Bug Fixes
31
75
 
32
- * **ci:** add neural version check to Verify and Release ([7f85b56](https://github.com/Rianico/dsh-better-edit/commit/7f85b5605e228d19bcde802ce2b10affc90fbde7))
76
+ - **ci:** add neural version check to Verify and Release ([7f85b56](https://github.com/Rianico/dsh-better-edit/commit/7f85b5605e228d19bcde802ce2b10affc90fbde7))
33
77
 
34
78
  ## [0.5.1](https://github.com/Rianico/dsh-better-edit/compare/v0.5.0...v0.5.1) (2026-08-30)
35
79
 
36
80
  ### Bug Fixes
37
81
 
38
- * **encoding:** support non-UTF-8 text files via VS Code model ([#34](https://github.com/Rianico/dsh-better-edit/issues/34)) ([#35](https://github.com/Rianico/dsh-better-edit/issues/35)) ([dd3e553](https://github.com/Rianico/dsh-better-edit/commit/dd3e553a3877e47b08aa2ba6336115e80b5d96f5))
39
- * **lint:** address biome blockers for release ([00b9270](https://github.com/Rianico/dsh-better-edit/commit/00b92704ac4093a627754e698bb1968acdc3d4e8))
40
- * remove unused exitHandlerRegistered ([f6a29f3](https://github.com/Rianico/dsh-better-edit/commit/f6a29f3f1dd694e4bb7c55a98d0eba80bc32a58f))
41
- * **scripts:** map fix to Fixed for Keep a Changelog ([bcd1850](https://github.com/Rianico/dsh-better-edit/commit/bcd18501e280b10d5075108c034de7352ece6922))
82
+ - **encoding:** support non-UTF-8 text files via VS Code model ([#34](https://github.com/Rianico/dsh-better-edit/issues/34)) ([#35](https://github.com/Rianico/dsh-better-edit/issues/35)) ([dd3e553](https://github.com/Rianico/dsh-better-edit/commit/dd3e553a3877e47b08aa2ba6336115e80b5d96f5))
83
+ - **lint:** address biome blockers for release ([00b9270](https://github.com/Rianico/dsh-better-edit/commit/00b92704ac4093a627754e698bb1968acdc3d4e8))
84
+ - remove unused exitHandlerRegistered ([f6a29f3](https://github.com/Rianico/dsh-better-edit/commit/f6a29f3f1dd694e4bb7c55a98d0eba80bc32a58f))
85
+ - **scripts:** map fix to Fixed for Keep a Changelog ([bcd1850](https://github.com/Rianico/dsh-better-edit/commit/bcd18501e280b10d5075108c034de7352ece6922))
42
86
 
43
87
  # Changelog
44
88
 
@@ -150,16 +194,16 @@ Entries link to the originating spec issue in [pi-hashline-edit-lsz](https://git
150
194
  ### Added
151
195
 
152
196
  - Configurable per-preset tool guidance (issues #7, #8; tickets #9–#13): the four `tool:*` prompt sections resolve from plain-markdown override files keyed by agent preset — `$DSH_HOME/plugins/dsh-better-edit/<preset>/<section>.md` — with an optional `order` front-matter. On first boot the plugin seeds each shipped preset (`standard`, `code`, `minimal`, `cordis`) with its guidance as editable files plus a root README documenting the scheme. Per section the chain is `<preset>/<section>.md` → compiled default; files are read once per agent at session-start, so edits apply to new sessions. Deployments without the `agentPresets` service keep the compiled defaults untouched.
153
- Default orders sit at 130–133, above the built-in tool-guidance band (100–116 in the shipped
154
- dsh), so a same-order section merge with unrelated tool guidance cannot occur out of the box; the
155
- seeded preset files expose that `order` as editable front-matter.
197
+ Default orders sit at 130–133, above the built-in tool-guidance band (100–116 in the shipped
198
+ dsh), so a same-order section merge with unrelated tool guidance cannot occur out of the box; the
199
+ seeded preset files expose that `order` as editable front-matter.
156
200
  - Default guidance text simplified per the writing-for-agents principles; the `*_GUIDELINES` constants unified on `*_GUIDANCE`.
157
201
  - Thanks to [@R-LEI2536](https://github.com/R-LEI2536) for requesting configurable per-preset prompts and for the design input that shaped this release (issue [#7](https://github.com/Rianico/dsh-better-edit/issues/7)).
158
202
 
159
203
  ### Changed
160
204
 
161
205
  - Benchmark extended to a third arm, `@oh-my-pi/hashline`: same corpus, same 12 replacements, two modes (per-edit `seq` with renumbered lines + one-document `batch` fixed to original line numbers). Payloads are built from the package's published grammar and validated before counting (the package is Bun-only, so it cannot run under the Node benchmark). Honest result, reported as such: hashline saves 31% vs `str_replace` on the session (43% on multi-line ranges) and remains the plugin's claim; the compact patch language saves 42% per edit / 53% batched — and this README says so. `npm run benchmark` stays byte-deterministic (verified over repeated runs).
162
- - READMEs (English and 中文) refined along ponytail-style lines: "How It Compares" gains an `@oh-my-pi/hashline` column plus a same-lineage/different-jobs comparison; the Benchmark section documents all three arms, adds an honest "regenerate, don't trust" reproducibility note, and widens the scope-and-honesty block with what the payload numbers do *not* capture (renumber/tag-chase cost, block ops, Bun-vs-Node, tool-pair vs patcher library).
206
+ - READMEs (English and 中文) refined along ponytail-style lines: "How It Compares" gains an `@oh-my-pi/hashline` column plus a same-lineage/different-jobs comparison; the Benchmark section documents all three arms, adds an honest "regenerate, don't trust" reproducibility note, and widens the scope-and-honesty block with what the payload numbers do _not_ capture (renumber/tag-chase cost, block ops, Bun-vs-Node, tool-pair vs patcher library).
163
207
  - `package.json` keywords now include `oh-my-pi` alongside `hashline`.
164
208
  - Roadmap gains a first-class decision item: close or justify the gap vs `@oh-my-pi/hashline` (payload-lighter by 42%/53% vs 31%, with block ops / registers / `REM`/`MV` / multi-hunk documents / pluggable fs we do not support — against correctness costs: unverified line numbers, renumber-per-edit, best-effort merge on stale tags, model skill floor). A reference record lives at `../oh-my-pi.md` (workspace-level, outside this repo): the token comparison, the correctness asymmetry, the ability-by-ability status, and the decision rationale.
165
209
 
package/README.md CHANGED
@@ -28,7 +28,7 @@
28
28
  </p>
29
29
 
30
30
  <p align="center">
31
- <img src="https://img.shields.io/badge/version-0.6.1-blue.svg" alt="Version">
31
+ <img src="https://img.shields.io/badge/version-0.7.0-blue.svg" alt="Version">
32
32
  <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License">
33
33
  <img src="https://img.shields.io/badge/DeepSeek_Harness-Plugin-blueviolet.svg" alt="DeepSeek Harness Plugin">
34
34
  <img src="https://img.shields.io/npm/v/dsh-better-edit" alt="npm version">
@@ -42,7 +42,7 @@
42
42
 
43
43
  ---
44
44
 
45
- > *"The harness — not the model — is the bottleneck."* — Can Bölük, [*The Harness Problem*](https://stencil.so/blog/the-harness-problem)
45
+ > _"The harness — not the model — is the bottleneck."_ — Can Bölük, [_The Harness Problem_](https://stencil.so/blog/the-harness-problem)
46
46
 
47
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
48
 
@@ -52,11 +52,11 @@
52
52
 
53
53
  **If you've watched `line 47 → 74` corrupt a file after an insert — this is for you.**
54
54
 
55
- | Before: `str_replace` / line numbers | After: hashline `edit` |
56
- | --- | --- |
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` |
55
+ | Before: `str_replace` / line numbers | After: hashline `edit` |
56
+ | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
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_STALE_RANGE]`/`[E_UNSERVED_RANGE]` reject before write, then **reject-and-serve** returns fresh `HASH│content` |
60
60
 
61
61
  > [!TIP]
62
62
  > **Shining points — honest:**
@@ -64,7 +64,7 @@
64
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
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
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.
67
+ > - **Concurrent-safe, not silent.** `retired anchor` per `(session,path)` epoch blocks re-bound `S@3→@3`; `retired` + `canon` + `hash` + `changed∩[L,R]` makes `pos-free` single-thread and `strict` only on true overlap. One retry vs silent wrong-line.
68
68
 
69
69
  Not for one-line touch-ups (near parity) or new files (`write`). Pays off in long sessions and structural edits.
70
70
 
@@ -84,15 +84,15 @@ No config. Next session runs with hashline tools. Verify:
84
84
  dsh --profile <name> --dump-config # shows "# == dsh-better-edit" layer
85
85
  ```
86
86
 
87
- | Requirement | |
88
- | --- | --- |
89
- | Node | `^22.19.0 \|\| >=24.0.0` |
90
- | Profile | `dsh` profile (`dsh plugin` creates one) |
91
- | Backends | sandboxed / remote `ctx.fs` |
87
+ | Requirement | |
88
+ | ----------- | ---------------------------------------- |
89
+ | Node | `^22.19.0 \|\| >=24.0.0` |
90
+ | Profile | `dsh` profile (`dsh plugin` creates one) |
91
+ | Backends | sandboxed / remote `ctx.fs` |
92
92
 
93
93
  ### See it work
94
94
 
95
- `read` serves `HASH│content` — the hash *is* the address:
95
+ `read` serves `HASH│content` — the hash _is_ the address:
96
96
 
97
97
  ```text
98
98
  ve7│function hello() {
@@ -114,12 +114,18 @@ Returns a diff with fresh anchors — next edit needs no `read`:
114
114
  kQm │ }
115
115
  ```
116
116
 
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.
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_STALE_RANGE` + fresh rows, one retry.
118
118
 
119
119
  Batch atomically — one `edit`, up to 32 same-file ranges:
120
120
 
121
121
  ```json
122
- { "path": "src/main.ts", "edits": [["a1b","a1b","new line 1\n"], ["c3d","c3d","new line 2"]] }
122
+ {
123
+ "path": "src/main.ts",
124
+ "edits": [
125
+ ["a1b", "a1b", "new line 1\n"],
126
+ ["c3d", "c3d", "new line 2"]
127
+ ]
128
+ }
123
129
  ```
124
130
 
125
131
  One fails → none write (`[E_BATCH_ABORT]`).
@@ -135,11 +141,11 @@ Tenancy and prompt guidance declare once, read at `agent/session-start`, no code
135
141
 
136
142
  ```yaml
137
143
  # $DSH_HOME/plugins/dsh-better-edit/config.yaml
138
- storeDir: central # central | workspace | /abs
144
+ storeDir: central # central | workspace | /abs
139
145
  autoGitignore: false
140
- undo_ttl_s: 604800 # 7d, -1 forever
141
- storeMaxAgeS: 2592000 # 30d janitor
142
- storeMaxTotalBytes: 524288000 # 500 MB LRU
146
+ undo_ttl_s: 604800 # 7d, -1 forever
147
+ storeMaxAgeS: 2592000 # 30d janitor
148
+ storeMaxTotalBytes: 524288000 # 500 MB LRU
143
149
  ```
144
150
 
145
151
  Env overrides yaml (`DSH_BETTER_EDIT_STORE_DIR`, `DSH_BETTER_EDIT_AUTO_GITIGNORE`).
@@ -148,9 +154,9 @@ Env overrides yaml (`DSH_BETTER_EDIT_STORE_DIR`, `DSH_BETTER_EDIT_AUTO_GITIGNORE
148
154
 
149
155
  ## Why Hashline
150
156
 
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.
157
+ **Verified against what was served.** Every resolved line checked against `read`/diff/rejection rows. Stale or unseen → `[E_STALE_RANGE]`/`[E_UNSERVED_RANGE]` + fresh `HASH│content`, retry needs no `read`. Session-scoped — sub-agent serves never validate main edits.
152
158
 
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]`).
159
+ **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_LARGE_FILE]`).
154
160
 
155
161
  **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.
156
162
 
@@ -158,17 +164,17 @@ Env overrides yaml (`DSH_BETTER_EDIT_STORE_DIR`, `DSH_BETTER_EDIT_AUTO_GITIGNORE
158
164
 
159
165
  Envelope change: hoist `path`, `edits:[[from,to,text]]`, never repeat `old_string`.
160
166
 
161
- | snapshot | `str_replace` | `edit` | `edit` multi | OMP per-edit | OMP batch |
162
- | --- | ---: | ---: | ---: | ---: | ---: |
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%** |
167
+ | snapshot | `str_replace` | `edit` | `edit` multi | OMP per-edit | OMP batch |
168
+ | --------------------- | ------------: | -------------: | -------------: | -------------: | -------------: |
169
+ | pinned 12-edit corpus | 1,015 | 609 **-40.0%** | 582 **-42.7%** | 590 **-41.9%** | 480 **-52.7%** |
170
+ | local snapshot | 358 | 272 **-24.0%** | 241 **-32.7%** | 268 **-25.1%** | 180 **-49.7%** |
165
171
 
166
172
  Percent vs `str_replace`. External row pinned corpus, `cl100k_base`; local `npm run benchmark` in upstream.
167
173
 
168
- | engine | calls | tokens | saved | ok |
169
- | --- | ---: | ---: | ---: | :---: |
170
- | OMP | **6** | 28,467 | — | ✅ |
171
- | hashline `edit` | **3** | 12,593 | **-55.8%** | ✅ |
174
+ | engine | calls | tokens | saved | ok |
175
+ | --------------- | ----: | -----: | ---------: | :-: |
176
+ | OMP | **6** | 28,467 | — | ✅ |
177
+ | hashline `edit` | **3** | 12,593 | **-55.8%** | ✅ |
172
178
 
173
179
  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).
174
180
 
@@ -176,43 +182,44 @@ Single stochastic run, `opencode-go/gpt-5.6-luna` high. [Artifact](https://githu
176
182
 
177
183
  ## Tools
178
184
 
179
- | Tool | What it does |
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 |
185
+ | Tool | What it does |
186
+ | ---------------- | ----------------------------------------------------------------------------------------------------------- |
187
+ | `read` | `HASH│content` with `offset`/`limit`; `[Showing N-M of T]` paging; `>200KB` lines show marker |
188
+ | `read_skill` | Plain text, no hashes, no serves — editing after it needs a serve |
189
+ | `edit` | `{path, edits:[[from,to,text]]}` `path:string\|null` inference, `""` deletes, atomic ≤32, verify-then-write |
190
+ | `undo_last_edit` | `{path}` restores last edit (BOM/line endings/anchors), persisted |
185
191
 
186
192
  `write` stays, but refuses an exact `HASH│` echo for same `session/path/line` before dispatch.
187
193
 
188
194
  ### Error codes
189
195
 
190
- | Code | Meaning |
191
- | --- | --- |
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 |
196
+ | Code | Meaning |
197
+ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
198
+ | `[E_BAD_PAYLOAD]` | Bad tuple shape (payload must be `{path, edits}` with 3-position tuples) |
199
+ | `[E_STALE_ANCHOR]` | No line (hash/retired/canon miss) / multi-line → `read` |
200
+ | `[E_BAD_ANCHOR]` | Not bare `3-char`, or `replacement_text` carries `HASH│`/diff-preview prefixes — refused, remove and retry |
201
+ | `[E_SERVED_ECHO]` | Copied `HASH│` from same session/path/line — refused, remove and retry |
202
+ | `[E_EMPTY_RANGE]`/`[E_NOT_FOUND]`/`[E_ACCESS]`/`[E_UNSUPPORTED_FILE]`/`[E_LARGE_FILE]` | Empty guard / missing / access / binary / >238,328 lines |
203
+ | `[E_REVERSED_ANCHORS]` | Swapped range — healed with dimmed `[USER]` notice on success, otherwise refused |
204
+ | `[E_BAD_ENCODING]`/`[E_DECODE_FAILED]` | Encoding / decode failed |
205
+ | `[E_NOT_OBSERVED]`/`[E_STALE_RANGE]`/`[E_UNSERVED_RANGE]` | Served-state miss — echoed fresh `HASH│content` |
206
+ | `[E_UNDO_STALE]`/`[E_UNDO_UNAVAILABLE]` | Undo stale / unavailable |
207
+ | `[E_NOOP_LOOP]`/`[E_BATCH_ABORT]` | 3× same no-op / atomic batch fail → nothing written |
201
208
 
202
209
  Full list in `src/` — every rejection echoes fresh rows, no `read` needed.
203
210
 
204
211
  ## Comparison
205
212
 
206
- | | **dsh-better-edit** | @oh-my-pi/hashline | `str_replace` |
207
- | --- | --- | --- | --- |
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 | — |
213
+ | | **dsh-better-edit** | @oh-my-pi/hashline | `str_replace` |
214
+ | ------------------ | -------------------- | ------------------- | ------------- |
215
+ | Address | `HASH│` 3-char canon | `[path#tag]` + line | text match |
216
+ | Whitespace-insen. | ✅ | ~ n/a | ❌ |
217
+ | Duplicate lines | ✅ unique | ~ pos | ❌ first |
218
+ | Verified vs served | ✅ every line | ~ file tag | ❌ |
219
+ | Blind edit | ✅ reject | ~ | ❌ |
220
+ | Batch atomic | ✅ | ✅ | ❌ |
221
+ | Undo | ✅ | ❌ | ❌ |
222
+ | Battery | 23/23 | 10/10 | — |
216
223
 
217
224
  `~` partial, `—` n/a. Same lineage — patch library vs dsh tool pair; pick by seam.
218
225
 
@@ -254,19 +261,19 @@ pnpm benchmark # hash probe + session envelope (reads/retries/tokens)
254
261
 
255
262
  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.
256
263
 
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 |
264
+ | Criterion | hashline | str_replace | seq / batch |
265
+ | ------------------- | :------------: | :---------: | :------------------: |
266
+ | `old_string` echoed | never | every edit | never |
267
+ | 12-edit saved | **31%** | 0% | **42% / 53%** |
268
+ | multi-line saved | **29–47%** | 0% | **40–53%** |
269
+ | 5× output cost | **~1.4× less** | 1× | **~1.7×/~2.1× less** |
270
+ | Verified | 100% | none | tag only |
264
271
 
265
- | Scenario | hashline | str_replace |
266
- | --- | ---: | ---: |
267
- | `1×8` | 309 | 324 |
268
- | `3–15×4` | 393 | 691 |
269
- | **TOTAL ×12** | **702** | **1015** |
272
+ | Scenario | hashline | str_replace |
273
+ | ------------- | -------: | ----------: |
274
+ | `1×8` | 309 | 324 |
275
+ | `3–15×4` | 393 | 691 |
276
+ | **TOTAL ×12** | **702** | **1015** |
270
277
 
271
278
  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).
272
279
 
@@ -274,7 +281,7 @@ Saved **313 (31%)**. Reproduce: upstream `npm run benchmark`. See [`pi-better-ed
274
281
 
275
282
  ## Roadmap
276
283
 
277
- **Current `0.6.1`:** pos-free `resist`/`strict` + tombstone/canons/epoch, per-session `(session,path)` store, `1222` tests, `9/9` harness.
284
+ **Current `0.7.0`:** pos-free `resist`/`strict` + retired anchor/canons/epoch, per-session `(session,path)` store, `1222` tests, `9/9` harness.
278
285
 
279
286
  <details><summary>Next</summary>
280
287
 
@@ -294,7 +301,7 @@ MIT — see [LICENSE](LICENSE).
294
301
 
295
302
  ## Acknowledgments
296
303
 
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).
304
+ 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).
298
305
 
299
306
  ---
300
307