dsh-better-edit 0.7.1 → 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 (46) hide show
  1. package/CHANGELOG.md +40 -25
  2. package/README.md +72 -66
  3. package/README.zh.md +83 -83
  4. package/lib/canonical-path.js +4 -1
  5. package/lib/contract.js +67 -22
  6. package/lib/edit-diff.js +1 -5
  7. package/lib/encoding.js +22 -5
  8. package/lib/file-encoding-state.js +50 -11
  9. package/lib/file-view.js +28 -41
  10. package/lib/fs-bridge.js +19 -9
  11. package/lib/fs-write.js +1 -1
  12. package/lib/guidance/materialize.js +1 -6
  13. package/lib/guidance/resolve.js +1 -1
  14. package/lib/hash-store.js +12 -20
  15. package/lib/hashline/anchor-pipeline.js +29 -29
  16. package/lib/hashline/hash-assign.js +7 -4
  17. package/lib/hashline/hash.js +3 -3
  18. package/lib/index.js +6 -0
  19. package/lib/mutation/engine.js +11 -14
  20. package/lib/mutation.js +7 -6
  21. package/lib/prompts.js +9 -8
  22. package/lib/read-and-serve.js +22 -11
  23. package/lib/render-text-warning.js +21 -0
  24. package/lib/sandbox.js +2 -5
  25. package/lib/self-heal.js +30 -27
  26. package/lib/session-view.js +5 -1
  27. package/lib/store-config.js +7 -2
  28. package/lib/store-lifecycle.js +7 -2
  29. package/lib/tool-edit.js +5 -2
  30. package/lib/tool-read.js +6 -9
  31. package/lib/tool-str-replace-editor.js +274 -0
  32. package/lib/tool-undo.js +2 -3
  33. package/lib/types/contract.d.ts +104 -17
  34. package/lib/types/file-encoding-state.d.ts +3 -0
  35. package/lib/types/file-view.d.ts +1 -1
  36. package/lib/types/hashline/index.d.ts +1 -1
  37. package/lib/types/render-text-warning.d.ts +22 -0
  38. package/lib/types/self-heal.d.ts +2 -0
  39. package/lib/types/tool-str-replace-editor.d.ts +27 -0
  40. package/lib/types/undo-edit.d.ts +1 -1
  41. package/lib/types/write-hook.d.ts +2 -2
  42. package/lib/undo-edit.js +6 -8
  43. package/lib/utils.js +1 -2
  44. package/lib/workspace-context.js +1 -1
  45. package/lib/write-hook.js +19 -22
  46. package/package.json +63 -57
package/CHANGELOG.md CHANGED
@@ -1,73 +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
+
1
16
  ## [0.7.1](https://github.com/Rianico/dsh-better-edit/compare/v0.7.0...v0.7.1) (2026-09-06)
2
17
 
3
18
  ### Bug Fixes
4
19
 
5
- * **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)
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)
6
21
 
7
22
  ### Documentation
8
23
 
9
- * **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)
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)
10
25
 
11
26
  ## [0.7.0](https://github.com/Rianico/dsh-better-edit/compare/v0.6.3...v0.7.0) (2026-09-06)
12
27
 
13
28
  ### Features
14
29
 
15
- * **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)
16
- * 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)
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)
17
32
 
18
33
  ### Bug Fixes
19
34
 
20
- * **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)
21
- * 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))
22
- * **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)
23
- * **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))
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))
24
39
 
25
40
  ### Documentation
26
41
 
27
- * **absorb:** record v1.6.0 checkpoint 87a17eb after T1-T4 ([8afba98](https://github.com/Rianico/dsh-better-edit/commit/8afba9842628e44a011c266956d8746725295c11))
28
- * migrate CLAUDE.md to AGENTS.md with symlink ([4706b6e](https://github.com/Rianico/dsh-better-edit/commit/4706b6e15f6a0ca627059087e3f05953b7b2ae6e))
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))
29
44
 
30
45
  ## [0.6.3](https://github.com/Rianico/dsh-better-edit/compare/v0.6.2...v0.6.3) (2026-09-05)
31
46
 
32
47
  ### Bug Fixes
33
48
 
34
- * **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))
35
50
 
36
51
  ## [0.6.2](https://github.com/Rianico/dsh-better-edit/compare/v0.6.1...v0.6.2) (2026-09-03)
37
52
 
38
53
  ### Bug Fixes
39
54
 
40
- * **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))
41
56
 
42
57
  ### Documentation
43
58
 
44
- * **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))
45
60
 
46
61
  ## [0.6.1](https://github.com/Rianico/dsh-better-edit/compare/v0.6.0...v0.6.1) (2026-09-01)
47
62
 
48
63
  ### Bug Fixes
49
64
 
50
- * **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)
51
66
 
52
67
  ## [0.6.0](https://github.com/Rianico/dsh-better-edit/compare/v0.5.1...v0.6.0) (2026-08-31)
53
68
 
54
69
  ### Features
55
70
 
56
- * **edit:** render diff card after tool calling ([df7712c](https://github.com/Rianico/dsh-better-edit/commit/df7712cef265dfec424feefb60c19f833d380f9f))
57
- * **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))
58
73
 
59
74
  ### Bug Fixes
60
75
 
61
- * **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))
62
77
 
63
78
  ## [0.5.1](https://github.com/Rianico/dsh-better-edit/compare/v0.5.0...v0.5.1) (2026-08-30)
64
79
 
65
80
  ### Bug Fixes
66
81
 
67
- * **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))
68
- * **lint:** address biome blockers for release ([00b9270](https://github.com/Rianico/dsh-better-edit/commit/00b92704ac4093a627754e698bb1968acdc3d4e8))
69
- * remove unused exitHandlerRegistered ([f6a29f3](https://github.com/Rianico/dsh-better-edit/commit/f6a29f3f1dd694e4bb7c55a98d0eba80bc32a58f))
70
- * **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))
71
86
 
72
87
  # Changelog
73
88
 
@@ -179,16 +194,16 @@ Entries link to the originating spec issue in [pi-hashline-edit-lsz](https://git
179
194
  ### Added
180
195
 
181
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.
182
- Default orders sit at 130–133, above the built-in tool-guidance band (100–116 in the shipped
183
- dsh), so a same-order section merge with unrelated tool guidance cannot occur out of the box; the
184
- 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.
185
200
  - Default guidance text simplified per the writing-for-agents principles; the `*_GUIDELINES` constants unified on `*_GUIDANCE`.
186
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)).
187
202
 
188
203
  ### Changed
189
204
 
190
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).
191
- - 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).
192
207
  - `package.json` keywords now include `oh-my-pi` alongside `hashline`.
193
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.
194
209
 
package/README.md CHANGED
@@ -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_STALE_RANGE]`/`[E_UNSERVED_RANGE]` 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:**
@@ -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() {
@@ -119,7 +119,13 @@ Returns a diff with fresh anchors — next edit needs no `read`:
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`).
@@ -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,44 +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_PAYLOAD]` | Bad tuple shape (payload must be `{path, edits}` with 3-position tuples) |
193
- | `[E_STALE_ANCHOR]` | No line (hash/retired/canon miss) / multi-line → `read` |
194
- | `[E_BAD_ANCHOR]` | Not bare `3-char`, or `replacement_text` carries `HASH│`/diff-preview prefixes — refused, remove and retry |
195
- | `[E_SERVED_ECHO]` | Copied `HASH│` from same session/path/line — refused, remove and retry |
196
- | `[E_EMPTY_RANGE]`/`[E_NOT_FOUND]`/`[E_ACCESS]`/`[E_UNSUPPORTED_FILE]`/`[E_LARGE_FILE]` | Empty guard / missing / access / binary / >238,328 lines |
197
- | `[E_REVERSED_ANCHORS]` | Swapped range — healed with dimmed `[USER]` notice on success, otherwise refused |
198
- | `[E_BAD_ENCODING]`/`[E_DECODE_FAILED]` | Encoding / decode failed |
199
- | `[E_NOT_OBSERVED]`/`[E_STALE_RANGE]`/`[E_UNSERVED_RANGE]` | Served-state miss — echoed fresh `HASH│content` |
200
- | `[E_UNDO_STALE]`/`[E_UNDO_UNAVAILABLE]` | Undo stale / unavailable |
201
- | `[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 |
202
208
 
203
209
  Full list in `src/` — every rejection echoes fresh rows, no `read` needed.
204
210
 
205
211
  ## Comparison
206
212
 
207
- | | **dsh-better-edit** | @oh-my-pi/hashline | `str_replace` |
208
- | --- | --- | --- | --- |
209
- | Address | `HASH│` 3-char canon | `[path#tag]` + line | text match |
210
- | Whitespace-insen. | ✅ | ~ n/a | ❌ |
211
- | Duplicate lines | ✅ unique | ~ pos | ❌ first |
212
- | Verified vs served | ✅ every line | ~ file tag | ❌ |
213
- | Blind edit | ✅ reject | ~ | ❌ |
214
- | Batch atomic | ✅ | ✅ | ❌ |
215
- | Undo | ✅ | ❌ | ❌ |
216
- | 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 | — |
217
223
 
218
224
  `~` partial, `—` n/a. Same lineage — patch library vs dsh tool pair; pick by seam.
219
225
 
@@ -255,19 +261,19 @@ pnpm benchmark # hash probe + session envelope (reads/retries/tokens)
255
261
 
256
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.
257
263
 
258
- | Criterion | hashline | str_replace | seq / batch |
259
- | --- | :---: | :---: | :---: |
260
- | `old_string` echoed | never | every edit | never |
261
- | 12-edit saved | **31%** | 0% | **42% / 53%** |
262
- | multi-line saved | **29–47%** | 0% | **40–53%** |
263
- | 5× output cost | **~1.4× less** | 1× | **~1.7×/~2.1× less** |
264
- | 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 |
265
271
 
266
- | Scenario | hashline | str_replace |
267
- | --- | ---: | ---: |
268
- | `1×8` | 309 | 324 |
269
- | `3–15×4` | 393 | 691 |
270
- | **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** |
271
277
 
272
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).
273
279
 
@@ -295,7 +301,7 @@ MIT — see [LICENSE](LICENSE).
295
301
 
296
302
  ## Acknowledgments
297
303
 
298
- 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).
299
305
 
300
306
  ---
301
307