pi-hashline-edit-pro 2.0.1 → 2.1.1

package/README.md

@@ -1,35 +1,21 @@
 # pi-hashline-edit-pro
 
-A [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) extension that replaces the built-in `read` and `edit` tools with a hash-anchored editing workflow. Every line of a file is tagged with a unique 3-character content hash; `replace` targets lines by those hashes instead of raw text, so stale context is caught and rejected before it reaches the file.
+Hash-anchored `read` and `replace` tools for [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent). Every line of a file gets a unique 3-character hash, and you edit by hash. No line numbers, no fuzzy matching, no edits landing on the wrong line.
 
-Fork of [pi-hashline-edit](https://github.com/RimuruW/pi-hashline-edit) by RimuruW, extending it with 3-character hashes and collision resolution — see [Hashing](#hashing).
+Fork of [pi-hashline-edit](https://github.com/RimuruW/pi-hashline-edit) by RimuruW, extended with 3-character hashes and collision resolution.
 
-## Features
+## What you get
 
-- **Hash-anchored reads.** `read` returns every line as `HASH│content`.
-- **Precise edits.** `replace` targets a line range by hash. Mismatched anchors fail loudly with `[E_STALE_ANCHOR]` — never a silent "close enough" relocation.
-- **Stable anchors.** Editing one part of a file leaves the hashes of untouched lines unchanged, so anchors from earlier reads stay valid.
-- **Autocorrection with warnings.** Unambiguous copy-paste mistakes — hash prefixes, diff-preview rows, reversed ranges — are fixed automatically and reported.
-- **Safe writes.** Atomic temp-file-then-rename writes preserve permissions, BOMs, line endings, symlinks, and hard links.
-- **Auto-read.** Fresh anchors are appended to the result of every `write` that changes the file; after `replace` and `undo_last_replace`, the post-edit diff is shown instead.
-
-## Installation
-
-From npm:
-
-```bash
-pi install npm:pi-hashline-edit-pro
-```
-
-From a local checkout:
-
-```bash
-pi install /path/to/pi-hashline-edit-pro
-```
+- **Read with anchors.** Every line comes back as `HASH│content`. The hash is the line's address.
+- **Edit by hash.** `replace` targets a range of hashes, so edits always land on the lines you meant.
+- **Anchors that stay put.** Edit one part of a file and the hashes of the rest stay the same. Read once, keep editing.
+- **Fresh anchors, automatically.** After every `write` you get the new anchors. After every `replace` you get the diff with the new hashes.
+- **Undo when you need it.** The last replace on a file can be reverted, even after a restart.
+- **Safe writes.** Permissions, line endings, BOMs, symlinks, and hard links survive every edit.
 
 ## Quick start
 
-1. Read a file. Every line comes back with a hash prefix (no line numbers — the hash is the address):
+1. Read a file:
 
 ```text
 ve7│function hello() {
@@ -47,37 +33,47 @@ kQm│}
 }
 ```
 
-3. Keep editing. Anchors for untouched lines remain valid across edits, so hashes from earlier reads keep working; changed lines get fresh anchors, which auto-read appends after each `write`.
+3. Keep editing. Anchors for lines you didn't touch stay valid, and auto-read hands you fresh anchors after each change.
 
-## The `read` tool
+## Installation
 
-Returns a text file with every line prefixed by `HASH│content`. The hash is a 3-character content hash from the alphabet `A-Za-z0-9` (e.g. `aB3`).
+```bash
+pi install npm:pi-hashline-edit-pro
+```
 
-Optional parameters:
+From a local checkout:
+
+```bash
+pi install /path/to/pi-hashline-edit-pro
+```
+
+## The read tool
+
+`read` returns a text file with every line prefixed by `HASH│content`. The hash is 3 characters from `A-Za-z0-9` (for example `aB3`).
 
 | Parameter | Description |
 | --- | --- |
 | `offset` | Start reading from this line number (1-indexed). |
 | `limit` | Maximum number of lines to return. |
 
-Paged output ends with a continuation hint, e.g. `[Showing lines 1-50 of 120. Use offset=51 to continue.]`.
+Paged output ends with a continuation hint, for example `[Showing lines 1-50 of 120. Use offset=51 to continue.]`.
 
-Lines up to 200KB are displayed in full; larger lines are replaced by a marker with a bash inspection hint (`sed -n 'Np' <path> | head -c 204800`) since hash anchors require full lines.
+Lines up to 200KB are shown in full. Larger lines are replaced by a marker with a bash inspection hint (`sed -n 'Np' <path> | head -c 204800`), because hash anchors need full lines.
 
 Edge cases:
 
-- **Images** (JPEG, PNG, GIF, WebP) are passed through as visual attachments and don't participate in the hashline protocol.
-- **Binary and directory paths** are rejected with a descriptive error.
-- **UTF-16/UTF-32 encoded text** (detected via BOM) is rejected with `[E_NOT_TEXT]` — editing such a file would decode it as `U+FFFD` garbage and rewrite it as corrupted UTF-8.
-- **Empty files** are returned as a single empty-line hash (`HASH│`); use `replace` on that hash to insert content.
-- **BOMs** are stripped for display; **non-UTF-8 bytes** are shown as `U+FFFD` (editing such a file rewrites it as UTF-8, with a warning).
-- **Files over 238,328 lines** are rejected with `[E_FILE_TOO_LARGE]` (see [Hashing](#hashing)).
+- Images (JPEG, PNG, GIF, WebP) come back as visual attachments.
+- Binary files and directories are rejected with a descriptive error.
+- UTF-16 and UTF-32 text (detected via BOM) is rejected, since editing it would corrupt the file.
+- Empty files come back as a single empty-line hash (`HASH│`); use `replace` on that hash to insert content.
+- BOMs are stripped for display. Non-UTF-8 bytes are shown as `U+FFFD`; editing such a file rewrites it as UTF-8, with a warning.
+- Files over 238,328 lines are rejected with `[E_FILE_TOO_LARGE]`.
 
-## The `replace` tool
+## The replace tool
 
-The built-in `edit` tool is disabled — `replace` is the only edit path; call it with the hash anchors from `read` output.
+The built-in `edit` tool is disabled. `replace` is the only edit path, and it takes the hash anchors from `read` output.
 
-Exactly one edit per call, with `hash_bounds` and `new_content` at the top level of the request:
+One edit per call, with `hash_bounds` and `new_content` at the top level:
 
 ```json
 {
@@ -92,59 +88,39 @@ Exactly one edit per call, with `hash_bounds` and `new_content` at the top level
 | `hash_bounds` | Pair of 3-char hashes from `read` output marking the first and last line of the range to replace (inclusive). |
 | `new_content` | Replacement content as a single string with `\n` line separators; a trailing newline is the last line's ending, not an extra empty line. Use `""` to delete the range. |
 
-Behavior:
+Notes:
 
-- **Validation before any file I/O.** Unknown fields, missing fields, wrong types, and malformed anchors are rejected with `[E_BAD_SHAPE]` / `[E_BAD_REF]`. The edit applies against the pre-edit snapshot, so all hashes in the request come from one consistent file state.
-- **Autocorrections** (all accompanied by a warning unless noted):
-  - A `HASH│` prefix accidentally left on a `new_content` line is stripped.
-  - Diff-preview rows (`+HASH│…`, `-HASH│…`, `-   │…`) pasted into `new_content` have their markers stripped. Numbered deletion rows (`-1    foo`) and unified-diff lines are written literally — never silently altered.
-  - A reversed range (start hash after end hash) is swapped and applied.
-  - A duplicated boundary line — the classic `}`, `});`, or `} else {` pasted twice — is silently removed; the duplicate never reaches the file.
-  - `file_path` is accepted as an alias for `path`.
-- **Response.** With auto-read enabled (the default), a successful edit returns the post-edit diff — the same `+HASH│` / `-   │` / ` HASH│` rows the user sees — instead of the summary. With auto-read disabled, the edit reports `Successfully replaced in {path}. Added X line(s), removed Y line(s).` plus any warnings, and no diff is shown to the model. Warnings are appended in both modes. An edit that produces identical content reports `No changes made` and never rotates anchors. The post-edit diff is exposed to the host UI via `details.diff` — the TUI always shows it — and reaches the model-visible text only while auto-read is on.
-- **Undo.** Every successful replace is undoable once via `undo_last_replace` — see [Undo](#undo).
+- The request is checked before any file I/O, so a bad request never touches the file.
+- Common copy-paste slips are fixed automatically and reported: a leftover `HASH│` prefix in `new_content` or `hash_bounds`, diff-preview rows pasted into the replacement, a reversed range, or a boundary line pasted twice. `file_path` works as an alias for `path` in all three tools.
+- An edit that produces identical content reports `No changes made` and leaves the anchors alone.
+- After a successful edit you get the post-edit diff with fresh anchors, so you can keep editing without re-reading.
 
-## Anchor stability
-
-Hashes are stored in a persistent per-file store (`~/.config/pi-hashline-edit-pro/hash-store.sqlite`) that preserves the hashes of unchanged lines across edits. When a range is replaced, the runtime maps the old content onto the new content and copies hashes for lines that survived; only genuinely new lines get fresh hashes.
-
-Two guarantees make this safe even with duplicated content:
+## Undo
 
-- **An edited range never borrows a hash from a line outside it.** Lines outside the replaced range keep their hashes unconditionally, even when their content is byte-identical to lines inside the range.
-- **Re-inserted identical text keeps its hash.** If replacement content matches a line that was just removed, the removed line's hash is reused — "replace X with X" doesn't rotate the anchor.
+`undo_last_replace` reverts the most recent successful `replace` on a file, restoring the exact previous content, BOM and line endings included, plus the previous anchors.
 
-A no-op replace never changes the file, so anchors remain valid. On first run after upgrading from an older version, the previous `hash-store.json` is imported once and renamed to `hash-store.json.bak`.
+- History is per-file and single-level: only the most recent replace can be reverted.
+- History is persisted and survives session restarts. A failed `write` does not clear it.
+- Every applied replace is undoable: the undo record is saved before the edit is written.
+- A successful `write` clears the history for that file.
+- If the file was modified or deleted since the last replace, the undo is refused rather than overwriting those changes.
 
 ## Auto-read
 
-Enabled by default. After a successful `write` that changes the file, the extension reads the file and appends an `--- Auto-read (hashline anchors) ---` block to the result, so the model gets immediate `HASH│content` anchors without a separate `read` call.
+Enabled by default. After a successful `write` that changes the file, the extension reads the file and appends an `--- Auto-read (hashline anchors) ---` block to the result, so you get fresh `HASH│content` anchors without a separate `read` call.
 
-- A no-op `replace` produces no diff — the file is unchanged, so existing anchors remain valid.
-- After `replace` / `undo_last_replace`, the success summary is replaced by the post-edit diff (the same `+HASH│` / `-   │` / ` HASH│` rows used for replace) plus any warnings, so the model sees the change like a git diff instead of line counts; no anchor block is appended — the diff rows themselves are the fresh anchors (`+HASH│` and ` HASH│` rows carry the current hashes, and unchanged lines keep their previous hashes), so follow-up edits can anchor on the diff directly; call `read` when you want the full file's anchors.
-- With auto-read disabled, `replace` / `undo_last_replace` results keep the plain summary in the model-visible text — no diff and no anchor block reach the model (the post-edit diff is still shown to the user).
-- After `write`, the block dumps from the top of the file. For files over 2000 lines, the dump is truncated with a pagination hint — use `read` with `offset` to continue.
-- Auto-read keeps a 50KB display budget: lines over 50KB are skipped with a marker instead of their content (use `read` for lines up to 200KB).
+- After `replace` and `undo_last_replace`, the result shows the post-edit diff. The `+HASH│` and ` HASH│` rows carry the current hashes, so follow-up edits can anchor on the diff directly. Call `read` when you want the full file's anchors.
+- After `write`, the block dumps from the top of the file. For files over 2000 lines, the dump is truncated with a pagination hint; use `read` with `offset` to continue.
+- Auto-read keeps a 50KB display budget. Lines over 50KB are skipped with a marker instead of their content (use `read` for lines up to 200KB).
 - Toggle at runtime with `/toggle-auto-read`; the setting persists across sessions.
-- If the auto-read itself fails (e.g. the file was deleted between the write and the read), a short `--- Auto-read failed: ... ---` notice is appended instead of the anchor block, so the model knows the anchors are missing.
 
-## Undo
-
-`undo_last_replace` reverts the most recent successful `replace` on a file, restoring the exact previous content — BOM and line endings included — and the previous anchors.
-
-- History is per-file and single-level: only the most recent replace can be reverted.
-- History is persisted in the hash store (`~/.config/pi-hashline-edit-pro/hash-store.sqlite`) and survives session restarts; a failed `write` does not clear it.
-- **Undo is a precondition, not a convenience.** The undo record is persisted *before* the edit is written; if it cannot be persisted, the `replace` is refused with `[E_UNDO_UNAVAILABLE]` and the file is not touched, so every applied edit is undoable. If the file write itself then fails, the previous undo record is restored, so a refused edit never destroys earlier undo history.
-- A successful `write` clears the history for that file.
-- With auto-read enabled, the model sees the post-edit diff after an undo, just like a replace; with auto-read disabled it sees the plain summary. No anchors are appended after an undo — call `read` to get fresh anchors for follow-up edits.
-- **Safety guard.** If the file was modified or deleted since the last replace, `undo_last_replace` refuses with `[E_UNDO_STALE]` rather than overwriting those changes.
-
-## Commands and configuration
+## Settings
 
 | Command | Description |
 | --- | --- |
 | `/toggle-auto-read` | Toggle automatic hashline anchors after write and post-edit diffs after replace and undo_last_replace operations. Persists across sessions. |
 
-Settings live in `~/.config/pi-hashline-edit-pro/config.json`, created automatically when a setting is toggled:
+Settings live in `~/.config/pi-hashline-edit-pro/config.json`, created automatically when a setting is toggled. On non-Windows platforms, the config directory honors `XDG_CONFIG_HOME` when set (falling back to `~/.config`); on Windows it always uses `~/.config`:
 
 ```json
 {
@@ -152,17 +128,34 @@ Settings live in `~/.config/pi-hashline-edit-pro/config.json`, created automatic
 }
 ```
 
+## How anchors work
+
+Each line is canonicalized (carriage returns stripped, trailing whitespace trimmed) and hashed with [xxhash-wasm](https://github.com/jungomi/xxhash-wasm) (xxHash32), then mapped to a 3-character string over `A-Za-z0-9`, which gives 62³ = 238,328 possible anchors. The canonicalization keeps anchors stable across editor-save cycles that add or remove trailing whitespace.
+
+The alphabet is sized for an LLM consumer: the model tokenizes rather than squinting at glyphs, so case and digits are all included. The URL-safe specials `-` and `_` are deliberately excluded. A hash starting with `-` is shape-identical to a diff-preview deletion row, and `-`/`_` at a line start are markdown-active, inviting mis-copying and false autocorrections.
+
+Unique anchors by construction. If a line's base hash collides with an already-assigned hash, the next free hash is allocated from a bitset by probing with a stride coprime to the hash space (O(1) amortized). The stride is `62² + 62 + 1`, so consecutive collisions, runs of blank lines, repeated `}`, land on anchors that differ in all three characters instead of sharing a prefix. Every line in a file therefore gets a unique anchor; two byte-identical lines (repeated `}`, repeated `import` statements) never share one. The same guarantee sets the file size cap: at most 238,328 lines per file, beyond which `read` and `replace` reject with `[E_FILE_TOO_LARGE]` (use `write` for very large files).
+
+Hashes live in a persistent per-file store (`~/.config/pi-hashline-edit-pro/hash-store.sqlite`) that keeps the hashes of unchanged lines across edits. When a range is replaced, the runtime maps the old content onto the new content and copies hashes for lines that survived; only genuinely new lines get fresh hashes.
+
+Two guarantees make this safe even with duplicated content:
+
+- An edited range never borrows a hash from a line outside it. Lines outside the replaced range keep their hashes unconditionally, even when their content is byte-identical to lines inside the range.
+- Re-inserted identical text keeps its hash. If replacement content matches a line that was just removed, the removed line's hash is reused. "Replace X with X" doesn't rotate the anchor.
+
+A no-op replace never changes the file, so anchors remain valid. On first run after upgrading from an older version, the previous `hash-store.json` is imported once and renamed to `hash-store.json.bak`.
+
 ## Error codes
 
 | Code | Meaning |
 | --- | --- |
-| `[E_BAD_SHAPE]` | Request envelope or edit item has unknown, missing, or wrongly-typed fields (e.g. `new_content` must be a string with `\n` line separators). |
+| `[E_BAD_SHAPE]` | Request envelope or edit item has unknown, missing, or wrongly-typed fields (for example `new_content` must be a string with `\n` line separators). |
 | `[E_BAD_REF]` | An anchor in `hash_bounds` is not a bare 3-char hash. |
 | `[E_STALE_ANCHOR]` | An anchor does not match any line in the current file; call `read` for fresh anchors. |
 | `[E_AMBIGUOUS_ANCHOR]` | An anchor matches multiple lines; call `read` for fresh anchors. |
-| `[E_INVALID_PATCH]` | A `new_content` line is a diff-preview row (`+HASH│`, `-HASH│`, `-   │`) — the marker is stripped automatically with a warning. |
-| `[E_BARE_HASH_PREFIX]` | A `new_content` line starts with a hash-like `HASH│` prefix — the prefix is stripped automatically with a warning. |
-| `[E_BAD_OP]` | Range start line is after range end line — the pair is swapped automatically with a warning. |
+| `[E_INVALID_PATCH]` | A `new_content` line is a diff-preview row (`+HASH│`, `-HASH│`, `-   │`). The marker is stripped automatically with a warning. |
+| `[E_BARE_HASH_PREFIX]` | A `new_content` line starts with a hash-like `HASH│` prefix. The prefix is stripped automatically with a warning. |
+| `[E_BAD_OP]` | Range start line is after range end line. The pair is swapped automatically with a warning. |
 | `[E_WOULD_EMPTY]` | An edit would empty a non-empty file; use `write` instead. |
 | `[E_NOT_FOUND]` | The path does not exist. |
 | `[E_ACCESS]` | The file is not readable or writable. |
@@ -171,30 +164,12 @@ Settings live in `~/.config/pi-hashline-edit-pro/config.json`, created automatic
 | `[E_UNDO_UNAVAILABLE]` | Undo history could not be persisted to the hash store; the `replace` was refused and the file was left unchanged. |
 | `[E_FILE_TOO_LARGE]` | The file exceeds the 238,328-line hashline limit. |
 
-## Hashing
-
-Each line is canonicalized (carriage returns stripped, trailing whitespace trimmed) and hashed with [xxhash-wasm](https://github.com/jungomi/xxhash-wasm) (xxHash32), then mapped to a 3-character string over `A-Za-z0-9` — 62³ = 238,328 possible anchors. The canonicalization keeps anchors stable across editor-save cycles that add or remove trailing whitespace.
-
-The alphabet is sized for an LLM consumer: the model tokenizes rather than squinting at glyphs, so case and digits are all included. The URL-safe specials `-` and `_` are deliberately excluded — a hash starting with `-` is shape-identical to a diff-preview deletion row, and `-`/`_` at a line start are markdown-active, inviting mis-copying and false autocorrections.
-
-**Unique anchors by construction.** If a line's base hash collides with an already-assigned hash, the next free hash is allocated from a bitset by probing with a stride coprime to the hash space (O(1) amortized). The stride is `62² + 62 + 1`, so consecutive collisions — runs of blank lines, repeated `}` — land on anchors that differ in all three characters instead of sharing a prefix. Every line in a file therefore gets a unique anchor — two byte-identical lines (repeated `}`, repeated `import` statements) never share one. The same guarantee sets the file size cap: at most 238,328 lines per file, beyond which `read` and `replace` reject with `[E_FILE_TOO_LARGE]` (use `write` for very large files).
-
-## Design decisions
-
-- **Stale anchors fail, per line.** A hash mismatch means that line's content changed since the last `read`. The error says so and, when only one anchor of a pair is stale, shows the current lines around the still-valid anchor so the range can be re-located without a full re-read. Mismatched anchors are never silently relocated to a "close enough" line — correctness over convenience.
-- **Autocorrection only when the intent is unambiguous**, and always visible: hash-prefix and diff-row stripping produce a warning; the boundary-duplication fix is silent because the duplicate never reaches the file. Literal content is never silently altered when the intent is ambiguous (numbered deletion rows and unified-diff lines are written verbatim).
-- **Byte-exact preservation.** UTF-8 BOMs, CRLF, LF, and CR-only line endings, file permissions, and trailing newlines survive edits and undo; files with mixed line endings are normalized to a single line ending on edit.
-- **Atomic and ordered writes.** Files are written via temp-file-then-rename; symlink chains are resolved so the target is updated without replacing the symlink; hard-linked files are updated in place; concurrent edits to the same underlying file serialize through a per-target mutation queue.
-- **One edit per call.** The request shape stays `{path, hash_bounds, new_content}` from schema through validation to application; there is no batching dialect.
-
 ## Troubleshooting
 
-- **Stale anchors.** `[E_STALE_ANCHOR]` / `[E_AMBIGUOUS_ANCHOR]` mean the file changed since the anchors were read, or an earlier `read` never happened. Call `read` for fresh anchors and retry.
-- **Reset the hash store.** Anchors live in `~/.config/pi-hashline-edit-pro/hash-store.sqlite` (with `-wal`/`-shm` sidecars). Quit pi, delete those three files, and the store is rebuilt on the next session. Anchor history is lost, but no project files are touched.
-- **Upgrading.** A hash-allocation change clears the hash store once on the first run after upgrade — anchors are rebuilt on the next read and undo history is lost, but no project files are touched.
-- **Corrupt store.** If the store fails its health check it is renamed to `hash-store.sqlite.corrupt-<timestamp>` (plus `-wal`/`-shm` variants) and rebuilt automatically; the quarantined files can be deleted once a healthy store exists.
-- **Legacy migration.** On first run after upgrading from an older version, the previous `hash-store.json` is imported once and renamed to `hash-store.json.bak`, which can be deleted. Legacy snapshots containing duplicate hashes are skipped and rebuilt on the next read.
-- **`[E_UNDO_UNAVAILABLE]`.** The edit was refused because the undo record could not be written — check disk space and that the config directory is writable, then retry.
+- Stale anchors. `[E_STALE_ANCHOR]` or `[E_AMBIGUOUS_ANCHOR]` mean the file changed since the anchors were read. Call `read` for fresh anchors and retry.
+- Reset the hash store. Anchors live in `~/.config/pi-hashline-edit-pro/hash-store.sqlite` (with `-wal`/`-shm` sidecars). Quit pi, delete those three files, and the store is rebuilt on the next session. Anchor history is lost, but no project files are touched.
+- Corrupt store. If the store fails its health check it is renamed to `hash-store.sqlite.corrupt-<timestamp>` and rebuilt automatically.
+- Config directory moved. On non-Windows platforms, if `XDG_CONFIG_HOME` is set, the config directory (and the hash store inside it) lives at `$XDG_CONFIG_HOME/pi-hashline-edit-pro` instead of `~/.config/pi-hashline-edit-pro`. An existing store is not migrated automatically. To keep anchor and undo history, move the old `hash-store.sqlite` files (plus `-wal`/`-shm` sidecars) into the new directory before the first run.
 
 ## Development
 
@@ -211,8 +186,8 @@ Set `PI_HASHLINE_DEBUG=1` to show an "active" notification at session start.
 
 ## Credits
 
-- [RimuruW](https://github.com/RimuruW) — original `pi-hashline-edit` and the strict-semantics policy
-- [can1357](https://github.com/can1357) — original [oh-my-pi](https://github.com/can1357/oh-my-pi) implementation and the hashline concept
+- [RimuruW](https://github.com/RimuruW), original `pi-hashline-edit` and the strict-semantics policy
+- [can1357](https://github.com/can1357), original [oh-my-pi](https://github.com/can1357/oh-my-pi) implementation and the hashline concept
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "2.0.1",
+  "version": "2.1.1",
   "type": "module",
   "description": "Strict hashline read/replace tool for pi-coding-agent with hash-anchored edits (3-char, 62-symbol, perfect hashing)",
   "main": "index.ts",
@@ -49,7 +49,8 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage --coverage.thresholds.lines=90 --coverage.thresholds.statements=90 --coverage.thresholds.functions=85 --coverage.thresholds.branches=80",
     "lint": "eslint \"src/**/*.ts\" \"index.ts\" \"test/**/*.ts\"",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm test"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",

package/src/file-reader.ts

@@ -51,6 +51,7 @@ export interface ReadNormOptions {
   preloadedFile?: LFile;
   maxLines?: number;
   store?: HashStore;
+  noPersist?: boolean;
 }
 
 export async function readNormFile(
@@ -83,7 +84,7 @@ export async function readNormFile(
     }
   }
 
-  const fileHashes = await lineHashes(normalized, resolvedPath, undefined, options?.store);
+  const fileHashes = await lineHashes(normalized, resolvedPath, undefined, options?.store, options?.noPersist !== true);
   return {
     absolutePath: resolvedPath,
     normalized,

package/src/hash-store.ts

@@ -4,6 +4,7 @@ import { DatabaseSync } from "node:sqlite";
 import { hashStorePath, hashStoreDir, legacyHashStorePath } from "./paths";
 import { errCode, splitLines } from "./utils";
 import { initHasher, contentChecksum } from "./hashline/hasher";
+import { HASH_RE } from "./hashline/alphabet";
 import { HASH_STORE_VERSION, HASH_STORE_BUSY_TIMEOUT } from "./constants";
 type SqlParams = (string | number)[];
 
@@ -35,15 +36,19 @@ interface LegacySnapshot {
   hashes: string[];
 }
 
+function isValidHashList(value: unknown): value is string[] {
+  if (!Array.isArray(value)) return false;
+  for (const hash of value) {
+    if (typeof hash !== "string" || !HASH_RE.test(hash)) return false;
+  }
+  return true;
+}
+
 function isValidSnapshot(value: unknown): value is LegacySnapshot {
   if (typeof value !== "object" || value === null) return false;
   const v = value as Record<string, unknown>;
   if (typeof v.content !== "string") return false;
-  if (!Array.isArray(v.hashes)) return false;
-  for (const h of v.hashes) {
-    if (typeof h !== "string") return false;
-  }
-  return true;
+  return isValidHashList(v.hashes);
 }
 
 export function isCorruptionError(error: unknown): boolean {
@@ -355,6 +360,7 @@ export function getSnapshot(
   store: HashStore,
   path: string,
   content: string,
+  deleteCorrupt = true,
 ): string[] | undefined {
   const checksum = contentChecksum(content);
   const lineCount = splitLines(content).length;
@@ -362,10 +368,11 @@ export function getSnapshot(
   if (!row) return undefined;
   try {
     const parsed = JSON.parse(row.hashes as string);
-    return Array.isArray(parsed) && parsed.every((h) => typeof h === "string")
-      ? (parsed as string[])
-      : undefined;
+    if (isValidHashList(parsed)) return parsed;
+    if (deleteCorrupt) store.stmts.deleteOne(path);
+    return undefined;
   } catch {
+    if (deleteCorrupt) store.stmts.deleteOne(path);
     return undefined;
   }
 }
@@ -397,7 +404,7 @@ export function getUndoEntry(store: HashStore, path: string): UndoRecord | undef
   if (!row) return undefined;
   try {
     const parsed = JSON.parse(row.hashes as string);
-    if (!Array.isArray(parsed) || !parsed.every((h) => typeof h === "string")) {
+    if (!isValidHashList(parsed)) {
       store.stmts.undoDelete(path);
       return undefined;
     }

package/src/hashline/alphabet.ts

@@ -0,0 +1,12 @@
+export const HASH_LEN = 3;
+
+export const ALPH =
+	"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+
+const ALPH_SAFE = ALPH.replace(/-/g, "\\-");
+
+export const ALPH_RE = new RegExp(`^[${ALPH_SAFE}]+$`);
+
+export const HASH_CLASS = `[${ALPH_SAFE}]{${HASH_LEN}}`;
+
+export const HASH_RE = new RegExp(`^${HASH_CLASS}$`);

package/src/hashline/hash.ts

@@ -6,19 +6,13 @@ import {
   upsertSnapshot,
 } from "../hash-store";
 import { xxh32, contentChecksum, initHasher } from "./hasher";
-export { initHasher };
+import { HASH_LEN, ALPH, ALPH_RE, HASH_CLASS } from "./alphabet";
+export { initHasher, HASH_LEN, ALPH_RE, HASH_CLASS };
 
-export const HASH_LEN = 3;
 export const ANCHOR_LEN = HASH_LEN;
 
 export const HASH_SEP = "│";
 
-const ALPH =
-	"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
-const ALPH_SAFE = ALPH.replace(/-/g, "\\-");
-const ALPH_RE = new RegExp(`^[${ALPH_SAFE}]+$`);
-export const HASH_CLASS = `[${ALPH_SAFE}]{${HASH_LEN}}`;
-
 export const HASH_SPACE = ALPH.length ** HASH_LEN;
 export const MAX_HASH_LINES = HASH_SPACE;
 
@@ -138,7 +132,7 @@ export async function lineHashes(
 
   let cached: string[] | undefined;
   try {
-    cached = getSnapshot(hashStore, path, content);
+    cached = getSnapshot(hashStore, path, content, persist !== false);
   } catch (error) {
     console.error("Failed to read hash store snapshot:", error);
   }
@@ -290,5 +284,3 @@ function mapStableHashes(
 
   return newHashes;
 }
-
-export { ALPH_RE };

package/src/hashline/resolve.ts

@@ -1,5 +1,5 @@
 import { abortIf, rejectUnknownFields, lastNonEmpty, firstNonEmpty, clipLine } from "../utils";
-import { HL_BARE_PREFIX_RE, HL_PREFIX_PLUS_RE, HL_PREFIX_MINUS_RE } from "./hash";
+import { HASH_CLASS, HL_BARE_PREFIX_RE, HL_PREFIX_PLUS_RE, HL_PREFIX_MINUS_RE } from "./hash";
 import { parseHashRef, parseText, type Anchor } from "./parse";
 import { NEW_CONTENT_NOT_STRING_MSG } from "../constants";
 
@@ -161,13 +161,32 @@ function assertItem(edit: Record<string, unknown>): void {
   }
 }
 
-export function resEdit(edit: HTEdit): HEdit {
+const ANCHOR_ROW_RE = new RegExp(`^([+-]?)(${HASH_CLASS})│`);
+
+export function resEdit(edit: HTEdit, warnings?: string[]): HEdit {
   assertItem(edit as Record<string, unknown>);
 
   const replaceLines = parseText(edit.new_content);
+  const bounds = edit.hash_bounds.map((ref) => {
+    const trimmed = ref.trim();
+    const match = trimmed.match(ANCHOR_ROW_RE);
+    if (match) {
+      let message: string;
+      if (match[1] === "+") {
+        message = `[E_BAD_REF] Autocorrected: stripped diff-preview marker copied from the diff preview in hash_bounds entry "${trimmed}".`;
+      } else if (match[1] === "-") {
+        message = `[E_BAD_REF] Autocorrected: stripped leading "-" marker in hash_bounds entry "${trimmed}".`;
+      } else {
+        message = `[E_BAD_REF] Autocorrected: stripped "HASH│" prefix copied from read output in hash_bounds entry "${trimmed}".`;
+      }
+      warnings?.push(message);
+      return match[2]!;
+    }
+    return ref;
+  }) as [string, string];
   return {
     content_lines: replaceLines,
-    hash_bounds: [parseHashRef(edit.hash_bounds[0]), parseHashRef(edit.hash_bounds[1])],
+    hash_bounds: [parseHashRef(bounds[0]), parseHashRef(bounds[1])],
   };
 }
 

package/src/paths.ts

@@ -7,8 +7,16 @@ function homeBase(): string {
   return envHome && envHome.length > 0 ? envHome : homedir();
 }
 
+function configBase(): string {
+  if (process.platform !== "win32") {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    if (xdg && xdg.length > 0) return xdg;
+  }
+  return join(homeBase(), ".config");
+}
+
 export function configDir(): string {
-  return join(homeBase(), ".config", "pi-hashline-edit-pro");
+  return join(configBase(), "pi-hashline-edit-pro");
 }
 
 export function configPath(): string {

package/src/read.ts

@@ -12,7 +12,7 @@ import { loadFileKindAndText } from "./file-kind";
 import { readNormFile } from "./file-reader";
 import { lineHashes, fmtRegion, HASH_SEP, MAX_HASH_LINES } from "./hashline";
 import { toCwd } from "./paths";
-import { abortIf } from "./utils";
+import { abortIf, isRec, normalizeFilePath } from "./utils";
 import { fileSnap } from "./file-reader";
 import { visLines } from "./utils";
 import { loadP, loadGuide } from "./prompts";
@@ -154,6 +154,12 @@ export function regRead(pi: ExtensionAPI): void {
 		description: R_DESC,
 		promptSnippet: R_SNIPPET,
 		promptGuidelines: readGuide(),
+		prepareArguments: (args: unknown) => {
+			if (!isRec(args)) return args as any;
+			const record = { ...args };
+			normalizeFilePath(record);
+			return record;
+		},
 		parameters: Type.Object({
 			path: Type.String({
 				description: "Path to the file to read (relative or absolute)",
@@ -204,8 +210,12 @@ export function regRead(pi: ExtensionAPI): void {
 				fileHashes,
 				absolutePath,
 			);
-			const snapshot = await fileSnap(absolutePath);
-
+			let snapshotId: string | undefined;
+			try {
+				snapshotId = (await fileSnap(absolutePath)).snapshotId;
+			} catch (error) {
+				console.error("Failed to compute snapshot for read:", error);
+			}
 			const previewText =
 				hadUtf8DecodeErrors
 					? `${preview.text}\n\n[Non-UTF-8 bytes shown as U+FFFD; editing rewrites the file as UTF-8.]`
@@ -215,7 +225,7 @@ export function regRead(pi: ExtensionAPI): void {
 				content: [{ type: "text", text: previewText }],
 				details: {
 					truncation: preview.truncation,
-					snapshotId: snapshot.snapshotId,
+					snapshotId,
 					...(preview.nextOffset !== undefined
 						? { nextOffset: preview.nextOffset }
 						: {}),

package/src/replace-normalize.ts

@@ -1,11 +1,4 @@
-import { isRec } from "./utils";
-
-export function normalizeFilePath(record: Record<string, unknown>): void {
-  if (typeof record.path !== "string" && typeof record.file_path === "string") {
-    record.path = record.file_path;
-    delete record.file_path;
-  }
-}
+import { isRec, normalizeFilePath } from "./utils";
 
 export function normReq(input: unknown): unknown {
   if (!isRec(input)) {

package/src/replace-render.ts

@@ -163,62 +163,8 @@ function trimEmpty(lines: string[]): string[] {
 	return lines.slice(start, end);
 }
 
-function isSectionBoundary(line: string): boolean {
-	return (
-		line === "--- Anchors ---" ||
-		line === "Warnings:" ||
-		line === "Structure outline:" ||
-		/^--- Range \d+ ---$/.test(line)
-	);
-}
-
 export function fmtResultMd(text: string): string {
-	const lines = text.split("\n");
-	const sections: string[] = [];
-	let plainLines: string[] = [];
-
-	const flush = () => {
-		const trimmed = trimEmpty(plainLines);
-		if (trimmed.length > 0) {
-			sections.push(trimmed.join("\n"));
-		}
-		plainLines = [];
-	};
-
-	let index = 0;
-	while (index < lines.length) {
-		const line = lines[index]!;
-
-		if (line.startsWith("--- Anchors ")) {
-			flush();
-			const title = line.replace(/^---\s*/, "").replace(/\s*---$/, "");
-			index++;
-			const bodyLines: string[] = [];
-			while (
-				index < lines.length &&
-				!isSectionBoundary(lines[index]!)
-			) {
-				bodyLines.push(lines[index]!);
-				index++;
-			}
-			sections.push(
-				[
-					`#### ${title}`,
-					"```text",
-					...trimEmpty(bodyLines),
-					"```",
-				].join("\n"),
-			);
-			continue;
-		}
-
-		plainLines.push(line);
-		index++;
-	}
-
-	flush();
-
-	return sections.join("\n\n");
+	return trimEmpty(text.split("\n")).join("\n");
 }
 
 export function mkMdTheme(theme: MdTheme) {

package/src/replace-undo.ts

@@ -7,7 +7,7 @@ import { contentChecksum } from "./hashline/hasher";
 import { resolveTarget, writeAtomic } from "./fs-write";
 import { toCwd } from "./paths";
 import { toLF, stripBOM, genDiff, restoreEndings, type LineEnding } from "./replace-diff";
-import { cntDiff, splitLines, errCode } from "./utils";
+import { cntDiff, splitLines, errCode, isRec, normalizeFilePath } from "./utils";
 import { loadP, loadGuide } from "./prompts";
 import { buildMetrics } from "./replace-response";
 import { changedRange } from "./hashline";
@@ -91,6 +91,12 @@ export function regReplaceUndo(pi: ExtensionAPI): void {
     description: loadP("../prompts/undo-last-replace.md"),
     promptSnippet: loadP("../prompts/undo-last-replace-snippet.md"),
     promptGuidelines: loadGuide("../prompts/undo-last-replace-guidelines.md"),
+    prepareArguments: (args: unknown) => {
+      if (!isRec(args)) return args as any;
+      const record = { ...args };
+      normalizeFilePath(record);
+      return record;
+    },
     parameters: Type.Object({
       path: Type.String({
         description: "Path to the file to undo",

package/src/replace.ts

@@ -12,8 +12,8 @@ import {
   type LineEnding,
 } from "./replace-diff";
 import { readNormFile } from "./file-reader";
-import { normReq, normalizeFilePath } from "./replace-normalize";
-import { isRec, rejectUnknownFields, abortIf } from "./utils";
+import { normReq } from "./replace-normalize";
+import { isRec, rejectUnknownFields, abortIf, normalizeFilePath } from "./utils";
 import { resolveTarget, writeAtomic } from "./fs-write";
 import { applyEdit,
   lineHashes,
@@ -175,14 +175,18 @@ export async function execPipeline(
 
   const path = params.path;
 
-  const edit = resEdit({
-    hash_bounds: params.hash_bounds,
-    new_content: params.new_content,
-  });
+  const editWarnings: string[] = [];
+  const edit = resEdit(
+    {
+      hash_bounds: params.hash_bounds,
+      new_content: params.new_content,
+    },
+    editWarnings,
+  );
 
   const hashStore = options?.store ?? await loadHashStore();
   const { normalized: originalNormalized, bom, originalEnding, fileHashes: originalHashes, hadUtf8DecodeErrors, absolutePath } = await readNormFile(
-    path, cwd, { signal: options?.signal, accessMode: options?.accessMode, maxLines: MAX_HASH_LINES, store: hashStore },
+    path, cwd, { signal: options?.signal, accessMode: options?.accessMode, maxLines: MAX_HASH_LINES, store: hashStore, noPersist: options?.noPersist },
   );
 
   const anchorResult = applyEdit(
@@ -207,8 +211,7 @@ export async function execPipeline(
         hashes: originalHashes,
         removedHashes,
       }, hashStore, noPersist !== true);
-  const warnings = [...(anchorResult.warnings ?? [])];
-
+  const warnings = [...editWarnings, ...(anchorResult.warnings ?? [])];
   const { totalAddedLines, totalRemovedLines } = countLineChanges(
     edit, originalHashes, isNoop, anchorResult.autoFixes?.length ?? 0,
   );

package/src/utils.ts

@@ -2,8 +2,11 @@ export function isRec(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-export function has(record: Record<string, unknown>, key: string): boolean {
-	return Object.hasOwn(record, key);
+export function normalizeFilePath(record: Record<string, unknown>): void {
+  if (typeof record.path !== "string" && typeof record.file_path === "string") {
+    record.path = record.file_path;
+    delete record.file_path;
+  }
 }
 
 export function splitLines(text: string): string[] {