pi-hashline-edit-pro 4.4.3 → 4.4.4

package/README.md

@@ -1,12 +1,73 @@
 # pi-hashline-edit-pro
 
-[![npm version](https://img.shields.io/npm/v/pi-hashline-edit-pro.svg)](https://www.npmjs.com/package/pi-hashline-edit-pro) [![npm downloads](https://img.shields.io/npm/dm/pi-hashline-edit-pro.svg)](https://www.npmjs.com/package/pi-hashline-edit-pro)
+![pi-hashline-edit-pro banner](https://raw.githubusercontent.com/YuGiMob/pi-hashline-edit-pro/master/assets/banner.svg)
 
-pi-hashline-edit-pro is an extension for [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) that edits files by anchor. Every line a tool shows you is prefixed with a unique 4-character anchor, and you edit by anchor. There are no line numbers and no fuzzy matching, so an edit lands on the line you meant.
+[![npm version](https://img.shields.io/npm/v/pi-hashline-edit-pro.svg)](https://www.npmjs.com/package/pi-hashline-edit-pro) [![npm downloads](https://img.shields.io/npm/dm/pi-hashline-edit-pro.svg)](https://www.npmjs.com/package/pi-hashline-edit-pro) [![Explicit Edit Benchmark](https://img.shields.io/endpoint?url=https://huggingface.co/datasets/alexshpunt/explicit-edit-benchmark/resolve/main/badges/pi-hashline-edit-pro.json&style=flat-square)](https://huggingface.co/spaces/alexshpunt/benchmark-explorer?card=harness%3Api-hashline-edit-pro%40latest)
+
+pi-hashline-edit-pro is an extension for [pi-coding-agent](https://github.com/earendil-works/pi) that edits files by anchor. Every line a tool serves gets a unique 4-character anchor, and you edit by anchor. Edits are never addressed by line number and nothing is fuzzy-matched, so an edit lands on the line you meant.
 
 It is a fork of [pi-hashline-edit](https://github.com/RimuruW/pi-hashline-edit) by RimuruW, extended with 4-character tokenizer-friendly anchors and allocation-based anchor identity.
 
-## Installation
+```text
+read a file; every line comes back as anchor│content:
+
+Dafo│function hello() {
+Emno│  console.log("world");
+HDtm│}
+
+replace one line by its anchor:
+
+{ "remove_from": "Emno", "remove_to": "Emno", "replacement_lines": ["  console.log('hi');"] }
+
+the result is the post-edit diff with fresh anchors, so the next edit needs no re-read.
+```
+
+## Contents
+
+- [Why anchors](#why-anchors)
+- [Install](#install)
+- [Quickstart](#quickstart)
+- [Tools](#tools)
+  - [read](#read)
+  - [replace](#replace)
+  - [insert](#insert)
+  - [anchor_grep](#anchor_grep)
+  - [undo_last_change](#undo_last_change)
+- [Batching](#batching)
+- [Auto-read](#auto-read)
+- [Auto-read all](#auto-read-all)
+- [Configuration](#configuration)
+- [Limits](#limits)
+- [Tool result details](#tool-result-details)
+- [Error and warning codes](#error-and-warning-codes)
+- [Troubleshooting](#troubleshooting)
+- [Privacy and on-disk state](#privacy-and-on-disk-state)
+- [How anchors work](#how-anchors-work)
+- [Benchmark](#benchmark)
+- [Development](#development)
+- [Credits](#credits)
+- [License](#license)
+
+## Why anchors
+
+Line numbers shift when anything above them changes; fuzzy matching can silently pick a similar-looking line. Anchors avoid both problems:
+
+| Dimension | Line numbers or fuzzy matching | Anchors (this extension) |
+| --- | --- | --- |
+| Address | a line number | a 4-character anchor minted for one line |
+| After an edit | downstream numbers shift, so stale numbers can hit the wrong line | untouched lines keep their anchors; only changed lines get new ones |
+| Wrong target | a fuzzy match may land on a similar line | an anchor resolves to exactly one file and line, or the edit is refused |
+| Stale request | can apply silently | refused with `[E_STALE_ANCHOR]` or `[E_RANGE_STALE]`, with fresh anchors returned for the retry |
+
+What "pro" adds over upstream `pi-hashline-edit`: the anchor table is built from pieces that each tokenize as one token (so an anchored row and an edit call stay cheap in tokens), and anchors are allocated per line and never derived from content, so byte-identical lines never share an anchor and an edit cannot re-target a different line.
+
+## Install
+
+Prerequisites:
+
+- [pi-coding-agent](https://github.com/earendil-works/pi) `>= 0.84.0` (`@earendil-works/pi-coding-agent`).
+- Node.js 22.19 or newer, or a Bun build that ships `bun:sqlite`.
+- An SQLite runtime. The extension uses `node:sqlite` on Node 22.19+ and falls back to `bun:sqlite`. The pi release binary's bundled Bun lacks `node:sqlite`, so run pi under Node or a Bun build that ships SQLite. Without a runtime, every tool fails with `[E_STORE_UNAVAILABLE]`.
 
 ```bash
 pi install npm:pi-hashline-edit-pro
@@ -18,9 +79,21 @@ To install from a local checkout:
 pi install /path/to/pi-hashline-edit-pro
 ```
 
-## Usage
+### What changes in your session
+
+| Built-in | Effect |
+| --- | --- |
+| `read` | overridden, returns `anchor│content` rows |
+| `edit` | disabled |
+| `grep` | disabled while `anchor_grep` is enabled |
+| `write` | kept; an auto-read block with fresh anchors is appended to its result |
+| `bash` | untouched |
+
+If anything of yours expects line-numbered `read` output (prompts, skills, hooks), account for the override before installing.
 
-Read a file. Every line comes back as `anchor│content`:
+### Verify
+
+After install, `read` any file and confirm the rows look like this:
 
 ```text
 Dafo│function hello() {
@@ -28,17 +101,54 @@ Emno│  console.log("world");
 HDtm│}
 ```
 
-Replace a line by its anchor:
+Then replace `Emno` and confirm the result is a post-edit diff with fresh anchors.
 
-```json
-{
-  "remove_from": "Emno",
-  "remove_to": "Emno",
-  "replacement_lines": ["  console.log('hi');"]
-}
+### Uninstall
+
+```bash
+pi uninstall npm:pi-hashline-edit-pro
 ```
 
-The result is the post-edit diff with fresh anchors, so you can keep editing without re-reading. Lines you did not touch keep their anchors. After a `write`, an auto-read block gives you the new anchors. The most recent `replace` or `insert` on a file can be reverted, even after a restart.
+## Quickstart
+
+1. Read a file. Every line comes back as `anchor│content`:
+
+   ```text
+   Dafo│function hello() {
+   Emno│  console.log("world");
+   HDtm│}
+   ```
+
+2. Replace a line by its anchor. One edit per call, fields at the top level:
+
+   ```json
+   {
+     "remove_from": "Emno",
+     "remove_to": "Emno",
+     "replacement_lines": ["  console.log('hi');"]
+   }
+   ```
+
+3. Read the post-edit diff. `-anchor│` rows are dead anchors; `+anchor│` and ` anchor│` rows are live, so you can keep editing without re-reading:
+
+   ```text
+   ...
+   -Emno│  console.log("world");
+   +Qwer│  console.log('hi');
+   ...
+   ```
+
+4. Revert the last `replace` or `insert` on the file with `undo_last_change`, whose one argument is the path:
+
+   ```json
+   { "path": "src/hello.ts" }
+   ```
+
+   Undo is single-level and survives restarts.
+
+Nothing commits until an edit call returns: the extension validates the request before touching the file, and refuses the edit when the file's served range changed on disk.
+
+## Tools
 
 The extension registers five tools: `read`, `replace`, `insert`, `anchor_grep`, and `undo_last_change`. The built-in `edit` tool is disabled. `replace` and `insert` take no `path` parameter by default: the file is resolved from the anchors' session ownership alone, so an edit can only land on the file the anchors were served for. Opt in with `/hashline-config` to require `path` in `replace` and `insert` for RPC visibility (for example pimacs.el); anchors still resolve the target and `path` must match.
 
@@ -87,21 +197,18 @@ Example: read showed `Hasu│old` and `arvm│old2`; to replace both:
 
 Single line: use the same anchor for `remove_from` and `remove_to`. `replace_from`/`replace_to` and `from`/`to` work as aliases.
 
-The request is checked before any file I/O, so a bad request never touches the file.
+The extension checks the request before any file I/O, so a bad request never touches the file.
+
+Auto-fixable slips fall into two groups. Fixed silently: a reversed range, stringified array text (even with a trailing JS method call, for example `[…].map(s => s)`), and embedded newlines. Fixed with a warning: a leftover `anchor│` prefix in `replacement_lines` or the anchor fields (a prefix of 4 to 5 letters before `│`, for example `abde│`), and diff-preview rows pasted into the replacement.
 
-Common copy-paste slips are fixed automatically: a leftover `anchor│` prefix in `replacement_lines` or the anchor fields (a prefix of 4 to 5 letters before `│`, for example `abde│`), and diff-preview rows pasted into the replacement are reported as warnings, while a reversed range, stringified array text (even with a trailing JS method call, for example `[…].map(s => s)`), and embedded newlines are corrected silently.
 Content containing a NUL byte (`U+0000`) is rejected with `[E_BAD_SHAPE]` before any file I/O: writing it would make the file binary, so use an empty replacement to delete. This applies to `replace`'s `replacement_lines` and `insert`'s `lines`.
 
-Every line in the removed range must match what was last shown to you. The extension records the `anchor│content` rows it serves (`read` output, `anchor_grep` output, the auto-read block after `write`, the `+anchor│` and ` anchor│` rows of post-edit diffs, the current-range rows of `[E_RANGE_STALE]` feedback, and the context rows of stale-anchor feedback) and verifies the whole range against that record before writing. A line that changed on disk since it was shown, or an anchor that is not owned in this session, refuses the edit with `[E_RANGE_STALE]` or `[E_STALE_ANCHOR]` and returns the current range with fresh anchors, so the retry needs no `read`. An owned anchor enters the served record when its row is shown (after a restart, restored ownership counts as shown), so a file with no owned anchors cannot be edited by anchor at all; call `read` first. An owned line that was never shown — for example beyond an auto-read preview's truncation cap — is refused with `[E_RANGE_STALE]` and returns the current range, so the retry still needs no `read`.
+Every line in the removed range must match what was last shown to you. The extension records the `anchor│content` rows it serves (`read` output, `anchor_grep` output, the auto-read block after `write`, the `+anchor│` and ` anchor│` rows of post-edit diffs, the current-range rows of `[E_RANGE_STALE]` feedback, and the context rows of stale-anchor feedback) and verifies the whole range against that record before writing. A line that changed on disk since it was shown, or an anchor that is not owned in this session, refuses the edit with `[E_RANGE_STALE]` or `[E_STALE_ANCHOR]` and returns the current range with fresh anchors, so the retry needs no `read`. An owned anchor enters the served record when its row is shown (after a restart, restored ownership counts as shown), so a file with no owned anchors cannot be edited by anchor at all; call `read` first. An owned line that was never shown, for example beyond an auto-read preview's truncation cap, is refused with `[E_RANGE_STALE]` and returns the current range, so the retry still needs no `read`.
 
 An edit that produces identical content reports `No changes made` and leaves the anchors alone.
 
 After a successful edit, the diff is capped at 50KB. A row over 50KB is shown as a marker that keeps the row's anchor, and only the rows shown in the capped diff are recorded as served. The same caps apply to the `insert` and `undo_last_change` diffs, to the interactive previews, and to `details.patch`.
 
-Multiple `replace` and `insert` calls on the same file in one assistant message are grouped per file into one batch. The batch unit is the message, not the turn: calls from separate messages in the same turn run solo, one after another. A solo edit commits before its result returns; a batch validates every call against the pre-batch state and commits once, during the batch's last call: earlier calls reply `In batch N` and the batch's last call shows the combined diff, with one undo reverting the whole batch. If the batch aborts, an earlier member's row renders the abort message instead of the placeholder. Nothing commits at turn end. A batch member accepts the same request shapes and auto-fixes as a solo call.
-The hashline tools are sequential in pi, so a message that contains one runs all of its tool calls one at a time in the order given; a `read` or shell `cat` issued before the edit commits can still observe the pre-commit state, so verify in the next message with the post-edit diff or a fresh `read`.
-Batched calls must target disjoint ranges; overlapping ranges, or any failing call, aborts the whole batch unwritten. One `insert` with `direction: "before"` and one with `direction: "after"` may target the same anchor line: the pair composes into a single insertion. A batch member that fails aborts its batch-mates with `[E_OP_ABORTED]`. A call whose anchors resolve nowhere never joins a batch: it runs solo and fails with its own error (`[E_STALE_ANCHOR]`, or `[E_BAD_SHAPE]` when its request cannot be parsed), while the same-file batch in the message still commits. Calls with one stale anchor and a valid co-anchor, or with a `requirePath` path hint, join their file's batch and abort it instead of applying partially. An error that aborts a batch ends with `Aborts batch N.`; an aborted call reads `[E_OP_ABORTED] Batch N aborted: [<kind>] Call Nr <X> errored [<code>]`, naming the failing call and its error code (or `[E_OP_ABORTED] Batch N aborted.` when the failing error carries no code). Anchor capacity is preflighted before writing; if anchor finalization fails after the write, the error states the file was written with one undo available. Verify each batch diff before the next turn's edits on that file.
-
 ### insert
 
 `insert` adds lines after or before an existing line without removing anything. Like `replace`, there is no `path` parameter.
@@ -114,6 +221,12 @@ Batched calls must target disjoint ranges; overlapping ranges, or any failing ca
 
 Nothing is removed and the inserted lines are written exactly as given; the anchor line and every other line stay in place. Inserting nothing (`lines: []`) reports a noop. To seed an empty file, read it and insert after the `anchor│` empty-line row.
 
+Example: add a line after `Emno│`:
+
+```json
+{ "anchor": "Emno", "direction": "after", "lines": ["  // log the greeting"] }
+```
+
 The same safety machinery as `replace` applies: undo is saved before the write (a failed write restores the previous undo record), and line endings and BOMs survive.
 
 ### anchor_grep
@@ -149,8 +262,24 @@ Output is capped at `limit` matched lines, 2000 rows, and 50KB of text, whicheve
 - If the file was modified since the last edit, the undo is refused with `[E_UNDO_STALE]` rather than overwriting those changes, and the record is kept. Once the file matches the edited state again, `undo_last_change` succeeds.
 - If the file was deleted since the last edit, `undo_last_change` restores it from the recorded pre-edit content.
 - Missing-file cleanup never touches the undo record. The per-session prune removes snapshots and served records of files that no longer exist (both are recomputed on the next read), but the undo history survives, even when the file is temporarily absent during a branch switch.
+- Records are keyed by file path, not by session, so in a multi-conversation host any conversation that names the file can revert its most recent edit, even one made by another conversation.
+
+## Batching
+
+Multiple `replace` and `insert` calls on the same file in one assistant message are grouped per file into one batch. The batch unit is the message, not the turn: calls from separate messages in the same turn run on their own, one after another.
+
+- A call outside a batch commits before its result returns.
+- A batch validates every call against the pre-batch state and commits once, during the batch's last call: earlier calls reply `In batch N`, and the batch's last call shows the combined diff, with one undo reverting the whole batch.
+- If a batch aborts, an earlier member's row renders the abort message instead of the placeholder. Nothing commits until the last call succeeds.
+- A batch member accepts the same request shapes and auto-fixes as a standalone call.
+
+Batched calls must target disjoint ranges; overlapping ranges, or any failing call, aborts the whole batch unwritten. One `insert` with `direction: "before"` and one with `direction: "after"` may target the same anchor line: the pair composes into a single insertion. A batch member that fails aborts its batch-mates with `[E_OP_ABORTED]`.
 
-### Auto-read
+A call whose anchors resolve nowhere never joins a batch: it runs on its own and fails with its own error (`[E_STALE_ANCHOR]`, or `[E_BAD_SHAPE]` when its request cannot be parsed), while the same-file batch in the message still commits. Calls with one stale anchor and a valid co-anchor, or with a `requirePath` path hint, are grouped into their file's batch and abort it instead of applying partially. An error that aborts a batch ends with `Aborts batch N.`; an aborted call reads `[E_OP_ABORTED] Batch N aborted: [<kind>] Call Nr <X> errored [<code>]`, naming the failing call and its error code (or `[E_OP_ABORTED] Batch N aborted.` when the failing error carries no code). Anchor capacity is preflighted before writing; if anchor finalization fails after the write, the error states the file was written with one undo available. Verify each batch diff before the next turn's edits on that file.
+
+The hashline tools are sequential in pi, so a message that contains one runs all of its tool calls one at a time in the order given; a `read` or shell `cat` issued before the edit commits can still observe the pre-commit state, so verify in the next message with the post-edit diff or a fresh `read`.
+
+## Auto-read
 
 Auto-read is enabled by default. After a successful `write`, the extension reads the file and appends an `--- Auto-read (hashline anchors) ---` block, so you get fresh `anchor│content` anchors without a separate `read` call.
 
@@ -158,29 +287,19 @@ After `replace`, `insert`, and `undo_last_change`, the result shows the post-edi
 
 Auto-read keeps the same 50KB and 2000-line budget as `read`. Auto-read and Diff context live in `/hashline-config` and persist across sessions. The post-edit diff shows 1 surrounding line by default; change Diff context in `/hashline-config` (0-10, needs Auto-read) to show more or fewer.
 
-### Auto-read all
+## Auto-read all
 
 Auto-read all is off by default and has three modes, selected in `/hashline-config`: `off` injects nothing, `on` discovers every file in the working directory that is not git-ignored (`git ls-files`, falling back to `ripgrep`, then to a directory walk), and `git` uses `git ls-files` only, injecting nothing when the working directory is not a git repository. On the first turn of a session, the extension discovers the files, reads each one, and attaches the resulting `anchor│content` rows to the conversation as one extension message before the model answers. Those anchors are served exactly like `read` output, so the model can `replace` and `insert` immediately without calling `read` first. The message is injected once per session; resumed, forked, and cloned sessions that already contain it skip the injection.
 
 Files are filtered before injection: symlinks, directories, image extensions (including SVG), binary files (a NUL byte in the first 8KB), files over 200KB, any path with a vendored segment (vendor, node_modules, bower_components, third_party, thirdparty, jspm_packages, .venv, venv, site-packages, __pycache__, .tox, .gradle, .terraform, Pods, Carthage, DerivedData, coreui, coreui-icons, case-insensitive), and vendored or generated names and patterns (*.min.js, *.min.css, *.min.mjs, *-min.js, *-min.css, *.bundle.*, *.chunk.*, *.umd.js, *.map, *.lock, package-lock.json, yarn.lock, composer.lock, Gemfile.lock, Cargo.lock, poetry.lock, Pipfile.lock, go.sum, flake.lock, *.generated.*, *.gen.*, *_pb2.py, *.pb.go, *.g.dart, *.freezed.dart, *.designer.cs, *.g.cs, *.snap, .eslintcache, coreui-icons.*, coreui.css) are skipped. The attachment stops at 500 files or at a byte budget derived from the model context window (200KB floor, 2MB ceiling), and it never drops below one file. Skipped and not-attached files are named at the end of the message so the model can `read` them on demand.
 
-Each attached file is shown as `=== path ===` followed by its `anchor│content` rows — edit directly from the attachment with replace and insert, no read needed. Files attach whole.
-A coverage line after the header reports the complete count. A `[files complete: [...] omitted: [...]]` line right after it lists every attached complete file and omitted file in one place — check that line instead of scanning sections.
+Each attached file is shown as `=== path ===` followed by its `anchor│content` rows. Edit directly from the attachment with replace and insert, so no `read` is needed. Files attach whole.
 
-The setting lives in `/hashline-config` as Auto-read all and in `config.json` as `autoReadAll` (`"off"`, `"on"`, or `"git"`; older configs with `true` or `false` are read as `"on"` or `"off"`). Extra folders and files are ignored via `/hashline-config` as Ignore folders/files and via `config.json` as `autoReadAllIgnore` (array of folder names, file names, or globs, for example `["docs", "scratch.md", "*.test.ts"]`). A single-segment entry skips any folder or file with that exact name (case-insensitive); an entry containing glob characters (`*`, `?`, `[`, `]`, `{`, `}`) is matched as a glob against the file name, or against the whole relative path when it also contains a slash, with the same syntax as `anchor_grep`'s `glob`; any other entry with a slash (for example `"src/tmp"`) skips that path. Custom ignores are counted with the vendor/name/pattern skips in the footer.
+A coverage line after the header reports the complete count. A `[files complete: [...] omitted: [...]]` line right after it lists every attached complete file and omitted file in one place. Check that line instead of scanning sections.
 
-## Tool result details
-
-All five tools return machine-readable metadata in `details` alongside the model-visible text.
-
-| Tool | `details` |
-| --- | --- |
-| `read` | `truncation` (set when output was truncated), `snapshotId` (a `v2\|path\|ino\|mtime\|ctime\|size` fingerprint), `nextOffset` (use as the next `offset`), and `metrics` with `truncated` and `next_offset`. |
-| `replace`, `insert` | `diff` (post-edit diff, capped, with current anchors on `+HASH│` and ` HASH│` rows; a same-message batch reports the combined diff on its last call and an empty diff on earlier calls), `patch` (a standard unified patch for external tools, capped like the diff), `patchTruncated` (true when the patch was cut or skipped for a pair over 1MB and can no longer be applied as-is), `firstChangedLine`, `snapshotId`, `classification` (`"noop"` when nothing changed), `batch` (`{ id, size, last, total }` marking same-message batch membership; earlier members also carry `aborted: true` and `abortMessage` after a batch abort), and `metrics`: `edits_attempted`, `edits_noop`, `warnings`, `classification` (`"applied"` or `"noop"`), `changed_lines` (`{ first, last }`), `added_lines`, `removed_lines`. |
-| `undo_last_change` | `diff` (the undo diff with restored anchors), `patch`, `patchTruncated`, and `metrics` in the same shape as `replace`. |
-| `anchor_grep` | `metrics` with `matches` (capped at `limit`), `files`, and `truncated`; `truncation` (the standard pi truncation report) when output was cut; and `linesTruncated` (true when long lines were shown as fragments). |
+The setting lives in `/hashline-config` as Auto-read all and in `config.json` as `autoReadAll` (`"off"`, `"on"`, or `"git"`; older configs with `true` or `false` are read as `"on"` or `"off"`). Extra folders and files are ignored via `/hashline-config` as Ignore folders/files and via `config.json` as `autoReadAllIgnore` (array of folder names, file names, or globs, for example `["docs", "scratch.md", "*.test.ts"]`). A single-segment entry skips any folder or file with that exact name (case-insensitive); an entry containing glob characters (`*`, `?`, `[`, `]`, `{`, `}`) is matched as a glob against the file name, or against the whole relative path when it also contains a slash, with the same syntax as `anchor_grep`'s `glob`; any other entry with a slash (for example `"src/tmp"`) skips that path. Custom ignores are counted with the vendor/name/pattern skips in the footer.
 
-## Settings
+## Configuration
 
 | Command | Description |
 | --- | --- |
@@ -201,35 +320,69 @@ Settings live in `~/.config/pi-hashline-edit-pro/config.json`, created when a se
 }
 ```
 
-On non-Windows platforms the directory honors `XDG_CONFIG_HOME` when set (falling back to `~/.config`); on Windows it always uses `~/.config`.
-
-## How anchors work
-
-Anchors are allocated, never derived. Every line that is served to you, by `read`, `anchor_grep`, the auto-read block after `write`, or a post-edit diff, gets the next free anchor from the session's pool, claimed by walking the table with a large stride (roughly the golden ratio of the anchor space) coprime to it, so consecutively minted anchors land in unrelated regions of the table instead of sharing leading characters. Each session seeds its walk from its own offset (derived from the session key and the process id), so concurrent sessions mint different sequences instead of identical ones: an anchor minted in one session is unknown in another and is rejected with `[E_STALE_ANCHOR]` rather than resolving to a different file. Ownership is exclusive: an anchor is owned by one file's line until it is freed (the line was edited, the file was written or deleted, or you ran `/clear-anchors`). Minting prefers anchors the session has never used; when a bounded fresh-anchor probe finds nothing, freed anchors are recycled after their stale served records are purged, so an anchor is never shared by two live lines. Because ownership is exclusive, an anchor resolves to exactly one file. Two byte-identical lines never share an anchor, and that guarantee sets the file size cap: at most 1,353,139 lines per file, beyond which `read`, `replace`, and `insert` reject with `[E_FILE_TOO_LARGE]` (use `write` for very large files).
+| Key | `/hashline-config` label | Default | Effect |
+| --- | --- | --- | --- |
+| `autoRead` | Auto-read | `true` | Append the auto-read block after `write` and show post-edit diffs. |
+| `autoReadAll` | Auto-read all | `"off"` | Attachment mode: `"off"`, `"on"`, or `"git"`. |
+| `autoReadAllIgnore` | Ignore folders/files | `[]` | Extra folder names, file names, or globs skipped by auto-read all. |
+| `anchorGrepEnabled` | Anchor grep | `true` | Register `anchor_grep` and disable the built-in grep while it is on. |
+| `requirePath` | Require path | `false` | `replace` and `insert` require a `path` argument that must match anchor ownership. |
+| `strictInput` | Strict input | `false` | Reject auto-fixable slips (`[W_BAD_SHAPE]`, `[W_BAD_REF]`, `[W_INVALID_PATCH]`, `[W_BARE_HASH_PREFIX]`) with `[E_BAD_SHAPE]` instead of applying them with a warning. |
+| `diffContextLines` | Diff context | `1` | Surrounding lines in post-edit diffs, 0-10 (needs Auto-read). |
+
+When `PI_HASHLINE_DIR` is unset or empty, non-Windows platforms honor `XDG_CONFIG_HOME` when set (falling back to `~/.config`); on Windows the directory always uses `~/.config`, where `~` is `%USERPROFILE%`. To move the directory explicitly, see [Isolated state](#isolated-state).
+
+## Limits
+
+| Limit | Value | Applies to |
+| --- | --- | --- |
+| Output cap | 2000 lines and 50KB | `read`, auto-read after `write`, post-edit diffs, patches, previews, `details.patch` |
+| Oversized row | 50KB per `anchor│content` row | replaced by an anchor-keeping marker you can still edit through |
+| Line cap | 1,353,139 lines per file | `read`, `replace`, `insert` (`[E_FILE_TOO_LARGE]`) |
+| File size | 100MB | all tools (`[E_FILE_TOO_LARGE]`) |
+| Hash window | first 500 bytes of a line | anchor identity for long lines |
+| Patch guard | 1MB of pre-edit + post-edit text | patch generation is skipped and `patchTruncated` is set |
+| Grep matches | 100 matched lines by default (`limit`) | `anchor_grep` |
+| Grep output | 2000 rows and 50KB | `anchor_grep` |
+| Grep row fragment | 500 bytes | long match and context rows shown as `...` fragments |
+| Auto-read all files | 500 files, 200KB per file | files larger than 200KB and files past the cap are omitted |
+| Auto-read all budget | 200KB floor, 2MB ceiling | total injection size, derived from the model context window |
+| Stale-range feedback | first 100 lines | rows returned with `[E_RANGE_STALE]` |
+| Session anchors | 1,353,139 anchors in use | all tools; the least recently read or edited files are freed when the quota is exhausted (`[W_ANCHOR_RECLAIMED]`) |
+
+`anchor_grep` uses the same 100MB file-size cutoff as `read`. Files over the line cap are skipped silently in directory searches.
 
-The table is curated for tokenizers, not for humans. Every anchor is the concatenation of two 2-character pieces that each encode as a single token, and beside the `│` separator the whole 5-character `anchor│` unit is verified to tokenize as exactly three tokens in each of eight modern open-weights tokenizers (Qwen 3.5, DeepSeek V4, Gemma 4, GLM 5.3 Flash, Tencent Hy4-preview, MiniMax M3, MiMo V2.5, Kimi K3). The shipped table is the intersection that satisfies the criterion on all of them; Nemotron 3 Ultra is the one modern tokenizer excluded. An anchor therefore costs 2 tokens on a read row and 2 in an edit call, with the `│` separator as the third. Anchors are letters only. The table is shipped as `src/hashline/anchor-table.json`.
-
-Each line also carries a content checksum. The line is canonicalized (carriage returns stripped, trailing whitespace trimmed) and hashed with [xxhash-wasm](https://github.com/jungomi/xxhash-wasm). The canonicalization keeps the checksum stable across editor-save cycles that add or remove trailing whitespace. A line over 500 bytes is hashed from its first 500 bytes.
+## Tool result details
 
-Allocated anchors live in a persistent per-file snapshot (`~/.config/pi-hashline-edit-pro/hash-store.sqlite`) keyed by content checksum, so resume-after-restart and cross-session edits reuse ownership instead of minting duplicates. Each session also appends an ownership log (`allocate`/`free`/`clear` events) to a sidecar file under `~/.config/pi-hashline-edit-pro/sessions/`; the fold of that log is the session's source of truth, sidecars whose session file is gone are garbage-collected at startup (never the sidecar of a session that is currently loaded in this process), and the in-memory ownership of a session is released when that session shuts down and rebuilt from its sidecar on next use.
+All five tools return machine-readable metadata in `details` alongside the model-visible text.
 
-When a range is edited, the mapping between old and new content is computed per span: lines whose content is unchanged keep their allocated anchors, anchors of removed lines are freed, and every genuinely new line is minted a fresh anchor. Anchors are never assigned by matching content; only positional survival across an edit preserves one.
+| Tool | `details` |
+| --- | --- |
+| `read` | `truncation` (set when output was truncated), `snapshotId` (a `v2\|path\|ino\|mtime\|ctime\|size` fingerprint), `nextOffset` (use as the next `offset`), and `metrics` with `truncated` and `next_offset`. |
+| `replace`, `insert` | `diff` (post-edit diff, capped, with current anchors on `+anchor│` and ` anchor│` rows; a same-message batch reports the combined diff on its last call and an empty diff on earlier calls), `patch` (a standard unified patch for external tools, capped like the diff), `patchTruncated` (true when the patch was cut or skipped for a pair over 1MB and can no longer be applied as-is), `firstChangedLine`, `snapshotId`, `classification` (`"noop"` when nothing changed), `batch` (`{ id, size, last, total }` marking same-message batch membership; earlier members also carry `aborted: true` and `abortMessage` after a batch abort), and `metrics`: `edits_attempted`, `edits_noop`, `warnings`, `classification` (`"applied"` or `"noop"`), `changed_lines` (`{ first, last }`), `added_lines`, `removed_lines`. |
+| `undo_last_change` | `diff` (the undo diff with restored anchors), `patch`, `patchTruncated`, and `metrics` in the same shape as `replace`. |
+| `anchor_grep` | `metrics` with `matches` (capped at `limit`), `files`, and `truncated`; `truncation` (the standard pi truncation report) when output was cut; and `linesTruncated` (true when long lines were shown as fragments). |
 
-Two guarantees make this safe even with duplicated content:
+`snapshotId`, `firstChangedLine`, and `metrics.warnings` are the three fields external consumers most often read; `snapshotId` is a string fingerprint, `firstChangedLine` is a 1-based line number on the result file, and `metrics.warnings` counts the `[W_*]` notices in `details.warnings`.
 
-- An edited range never borrows an anchor from a line outside it. Lines outside the replaced range keep their anchors unconditionally, even when their content is byte-identical to lines inside the range.
-- "Replace X with X" doesn't rotate the anchor: a line whose content is unchanged after an edit keeps its allocated anchor positionally. Every other line is minted fresh, so an anchor is never assigned by content matching.
+## Error and warning codes
 
-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`.
+Codes starting with `E_` are errors: nothing was written, with one exception. `File was written; anchor finalization failed` means the file was written and one undo reverts it. Codes starting with `W_` are warnings: the call succeeded with an auto-fix notice or an anchor-reclaim notice; check `classification` (`applied` vs `noop`) in `details.metrics` to tell whether bytes changed. `[E_AUTO_READ_ALL]` is informational rather than a failure: the `read` was refused because the file is unchanged since the start-of-session auto-read, so the attached content is still exact.
 
-On POSIX systems, the state directory is restricted to mode `0700` and the SQLite database plus its WAL/SHM sidecars to `0600`. The undo table contains the complete pre-edit and post-edit text for the latest edit to each file, so the store should still be treated as sensitive data.
+Most common, with the fix:
 
-## Error and warning codes
+- `[E_STALE_ANCHOR]`: the anchor is not owned in this session. Call `read` for fresh anchors and retry.
+- `[E_RANGE_STALE]`: a line in the replaced range changed on disk or was never shown. The error already returns the current range with fresh anchors; retry with those.
+- `[E_FILE_TOO_LARGE]`: the file exceeds the 1,353,139-line hashline limit or the 100MB size limit. Use `write` for very large files.
+- `[E_STORE_UNAVAILABLE]`: no SQLite runtime. Run pi under Node 22.19+ or a Bun build that ships `bun:sqlite`.
+- `[E_WRITE_HASH_ECHO]`: a `write` content line contains a copied served row. Remove the anchors and retry.
+- `[E_GREP_TIMEOUT]`: ripgrep timed out after 10 seconds. Narrow `path` or simplify `pattern` and retry.
 
-Codes starting with `E_` are errors: nothing was written — except `File was written; anchor finalization failed`, which means the file was written and one undo reverts it. Codes starting with `W_` are warnings: the call succeeded with an auto-fix notice; check `classification` (`applied` vs `noop`) in `details.metrics` to tell whether bytes changed.
+Full reference:
 
 | Code | Meaning |
 | --- | --- |
+| `[E_CONFIG]` | `PI_HASHLINE_DIR` is nonempty but not an absolute path. |
 | `[E_BAD_SHAPE]` | Request envelope or edit item has unknown, missing, or wrongly-typed fields (for example `replacement_lines` must be an array of strings, one element per line), content contains a NUL byte (`U+0000`), which would make the file binary, or a grep `glob` has invalid bracket or brace syntax. |
 | `[W_BAD_SHAPE]` | Auto-corrected request slip reported as a warning (for example stringified array text that could not be parsed and was kept as one literal line). |
 | `[E_BAD_REF]` | An anchor in `remove_from`/`remove_to` is not a bare 4-character anchor (the anchor table is letters only). |
@@ -237,6 +390,7 @@ Codes starting with `E_` are errors: nothing was written — except `File was wr
 | `[E_STALE_ANCHOR]` | An anchor is not owned in this session (it was never shown to you, or its line was edited or the file was rewritten); call `read` for fresh anchors. |
 | `[W_INVALID_PATCH]` | A `replacement_lines` element is a diff-preview row (`+anchor│`, `-anchor│`, `-    │`). The marker is stripped automatically with a warning. |
 | `[W_BARE_HASH_PREFIX]` | A `replacement_lines` element starts with an `anchor│` prefix. The prefix is stripped automatically with a warning. |
+| `[W_ANCHOR_RECLAIMED]` | The session's anchor quota was exhausted, so all anchors of the listed files (the least recently read or edited) were freed to make room. Read those files again before editing them. |
 | `[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. |
@@ -266,6 +420,66 @@ Codes starting with `E_` are errors: nothing was written — except `File was wr
 - Corrupt store. If the store fails its health check it is renamed to `hash-store.sqlite.corrupt-<timestamp>` and rebuilt automatically.
 - Config directory moved. If `XDG_CONFIG_HOME` is set on a non-Windows platform, the config directory (and the anchor state 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.
 - Windows drives in WSL. Editing a file under a Windows mount (`/mnt/c`, drvfs/9p) can fail with `EPERM` from `fchmod` because those filesystems do not store POSIX modes. Mode preservation is best-effort there, so `replace`, `insert`, and `undo_last_change` still write the edit.
+- Not sure what the extension changed. `read` returns anchored rows and the built-in `edit` is gone; that is expected. See [What changes in your session](#what-changes-in-your-session).
+
+## Privacy and on-disk state
+
+All state lives under the config directory (see [Configuration](#configuration)):
+
+| Path | Contents |
+| --- | --- |
+| `config.json` | The settings from [Configuration](#configuration). |
+| `hash-store.sqlite` (+ `-wal`, `-shm`) | Per-file snapshots of allocated anchors keyed by content checksum, plus the undo table. |
+| `sessions/<key>.registry.jsonl` | The session's anchor ownership log (`allocate`/`free`/`clear` events). |
+
+The undo table contains the complete pre-edit and post-edit text for the latest edit to each file, so treat the store as sensitive data. On POSIX systems the state directory is restricted to mode `0700` and the SQLite database plus its WAL/SHM sidecars to `0600`. Sidecar logs whose session file is gone are garbage-collected at startup (never the sidecar of a session that is currently loaded in this process); the in-memory ownership of a session is released when that session shuts down and rebuilt from its sidecar on next use. Served records live in memory only and are recomputed on the next read.
+
+### Isolated state
+
+Set `PI_HASHLINE_DIR` before starting pi to an absolute directory to override only this extension's state directory on all platforms. An unset or empty value preserves the XDG/home defaults; a nonempty relative value is rejected with `[E_CONFIG]`. Keep the value fixed for the lifetime of the process; the database remains a process-wide singleton.
+
+Config, SQLite (including WAL/SHM and undo history), registry sidecars, and the legacy `hash-store.json` location all follow the override. A fresh directory starts without shared config or history: no data is copied or imported from the default directory. Legacy migration, if needed, reads only `hash-store.json` inside the selected directory. Use a separate, access-restricted directory for each isolation scope; undo contains full file text.
+
+Background snapshot pruning and registry sidecar GC skip `EPERM`/`EACCES` without deleting records or logging each inaccessible path. Unexpected errors remain visible; tool file-access failures and SQLite errors are not silenced.
+
+## How anchors work
+
+### Allocation
+
+Anchors are allocated, never derived. Every line that is served to you, by `read`, `anchor_grep`, the auto-read block after `write`, or a post-edit diff, gets the next free anchor from the session's pool, claimed by walking the table with a stride of 836,286 entries (coprime to the 1,353,139-entry table), so consecutively minted anchors land in unrelated regions of the table instead of sharing leading characters. Each session seeds its walk from its own offset (derived from the session key and the process id), so concurrent sessions mint different sequences instead of identical ones: an anchor minted in one session is unknown in another and is rejected with `[E_STALE_ANCHOR]` rather than resolving to a different file. Ownership is exclusive: an anchor is owned by one file's line until it is freed (the line was edited, the file was written or deleted, you ran `/clear-anchors`, or the session's quota ran out and the file was the least recently read or edited, which frees all of its anchors and reports it in `[W_ANCHOR_RECLAIMED]`). Minting prefers anchors the session has never used; when a bounded fresh-anchor probe finds nothing, freed anchors are recycled after their stale served records are purged, so an anchor is never shared by two live lines. Because ownership is exclusive, an anchor resolves to exactly one file. Two byte-identical lines never share an anchor, and that guarantee sets the file size cap: the pool is the shipped table's 1,353,139 entries (not all 26⁴ letter combinations), so a file can hold at most 1,353,139 lines, beyond which `read`, `replace`, and `insert` reject with `[E_FILE_TOO_LARGE]` (use `write` for very large files).
+
+### Ownership and mapping across edits
+
+When a range is edited, the mapping between old and new content is computed per span: lines whose content is unchanged keep their allocated anchors, anchors of removed lines are freed, and every genuinely new line is minted a fresh anchor. Anchors are never assigned by matching content; only positional survival across an edit preserves one.
+
+Two guarantees make this safe even with duplicated content:
+
+- An edited range never borrows an anchor from a line outside it. Lines outside the replaced range keep their anchors unconditionally, even when their content is byte-identical to lines inside the range.
+- "Replace X with X" doesn't rotate the anchor: a line whose content is unchanged after an edit keeps its allocated anchor positionally. Every other line is minted fresh, so an anchor is never assigned by content matching.
+
+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`.
+
+### The anchor table is built for tokenizers
+
+Every anchor is the concatenation of two 2-character pieces that each encode as a single token, and beside the `│` separator the whole 5-character `anchor│` unit is verified to tokenize as exactly three tokens in each of eight modern open-weights tokenizers (Qwen 3.5, DeepSeek V4, Gemma 4, GLM 5.3 Flash, Tencent Hy4-preview, MiniMax M3, MiMo V2.5, Kimi K3). The shipped table is the intersection that satisfies the criterion on all of them; Nemotron 3 Ultra is the one modern tokenizer excluded. Model names are as published for the 4.4.x table build. An anchor therefore costs 2 tokens on a read row and 2 in an edit call, with the `│` separator as the third. Anchors are letters only. The table is shipped as `src/hashline/anchor-table.json`.
+
+### Line checksums
+
+Each line also carries a content checksum. The line is canonicalized (carriage returns stripped, trailing whitespace trimmed) and hashed with [xxhash-wasm](https://github.com/jungomi/xxhash-wasm). The canonicalization keeps the checksum stable across editor-save cycles that add or remove trailing whitespace. A line over 500 bytes is hashed from its first 500 bytes.
+
+### Persistent state
+
+Allocated anchors live in a persistent per-file snapshot (`~/.config/pi-hashline-edit-pro/hash-store.sqlite`) keyed by content checksum, so resume-after-restart and cross-session edits reuse ownership instead of minting duplicates. Each session also appends an ownership log (`allocate`/`free`/`clear` events) to a sidecar file under `~/.config/pi-hashline-edit-pro/sessions/`; that log is the session's record, sidecars whose session file is gone are garbage-collected at startup (never the sidecar of a session that is currently loaded in this process), and the in-memory ownership of a session is released when that session shuts down and rebuilt from its sidecar on next use.
+
+## Benchmark
+
+pi-hashline-edit-pro is measured on the [Explicit Edit Benchmark](https://github.com/alexshpunt/explicit-edit-benchmark), an open third-party benchmark maintained by [alexshpunt](https://github.com/alexshpunt). The suite has 226 deterministic, byte-exact editing tasks: replacements, insertions, deletions, copies, moves, large files, several file types, and Unicode edge cases. A verifier compares the result file tree byte by byte, so nothing is graded on compilation or behavioral equivalence. Many harnesses are scored on it.
+
+The current release scores 98.7% in the explorer's harness-family view for `pi-hashline-edit-pro`, with 99.6% or better final exactness on every model route.
+
+First exact means the first attempt, with no recovery round, reproduced the expected bytes exactly. Final exact is the same after the benchmark's allowed recovery rounds. Quality is `0.75 × first exact + 0.25 × final exact`, so first-attempt accuracy dominates. The family rollup is the median quality across the complete, eligible model-route configurations scored with this harness; partial and quarantined configurations stay visible in the dataset but do not enter the median.
+
+Per-model and per-version numbers, plus the spread behind the headline value, are in the [benchmark explorer](https://huggingface.co/spaces/alexshpunt/benchmark-explorer?card=harness%3Api-hashline-edit-pro%40latest); raw observations and scoring rules are in the [dataset](https://huggingface.co/datasets/alexshpunt/explicit-edit-benchmark) and the [methodology](https://github.com/alexshpunt/explicit-edit-benchmark/blob/main/docs/methodology.md). Treat the score as one measurement of this suite at one point in time.
 
 ## Development
 
@@ -273,7 +487,9 @@ Requires [Node.js](https://nodejs.org) 22.19 or newer and npm.
 
 ```bash
 npm install
-npm test
+npm test              # full suite
+npm run test:unit     # unit suite (heavy stress and property tests excluded)
+npm run test:coverage # full suite with coverage thresholds
 npm run lint
 npm run typecheck
 ```

package/index.ts

@@ -24,7 +24,7 @@ import {
   setAutoReadAllIgnoreFromText,
 } from "./src/config";
 import { loadHashStore, pruneMissing } from "./src/hash-store";
-import { initRegistry, gcRegistrySidecars, clearRegistry, freeAnchors, sessionKeyFor, withAnchorSession, releaseRegistrySession } from "./src/anchor-registry";
+import { initRegistry, gcRegistrySidecars, clearRegistry, freeAnchors, sessionKeyFor, withAnchorSession, releaseRegistrySession, formatAnchorReclaimNotice, takeReclaimedPaths } from "./src/anchor-registry";
 import { serveRows } from "./src/served";
 import { finalizeTurn, planAssistantMessage } from "./src/batch";
 import { currentEditFlags } from "./src/edit-common";
@@ -217,10 +217,11 @@ export default function (pi: ExtensionAPI): void {
         );
         const fileLines = splitLines(normalized);
         serveRows(absolutePath, fileHashes, fileLines, preview.servedHashes);
+        const reclaimNotice = formatAnchorReclaimNotice(takeReclaimedPaths());
         return {
           content: [
             ...(event.content ?? []),
-            { type: "text", text: `\n\n--- Auto-read (hashline anchors) ---\n${preview.text}` },
+            { type: "text", text: `\n\n--- Auto-read (hashline anchors) ---\n${preview.text}${reclaimNotice !== undefined ? `\n\n${reclaimNotice}` : ""}` },
           ],
         };
       } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "4.4.3",
+  "version": "4.4.4",
   "type": "module",
   "description": "Hash-anchored read/replace/insert/grep tools for pi-coding-agent. Every line gets a unique 4-char tokenizer-friendly anchor that stays stable across edits; stale or ambiguous anchors are rejected, never fuzzy-matched. Undo persists across restarts.",
   "main": "index.ts",

package/prompts/read-guidelines.md

@@ -1,2 +1,3 @@
 - `read`: call again after an edit when you need anchors you lack — post-edit diff `+anchor│`/` anchor│` rows and any served `anchor│content` rows already carry fresh anchors for the changed range.
-- `read`: `E_AUTO_READ_ALL` on an attached file means its content is still exactly as it was when attached at the start of this session.
+- `read`: `E_AUTO_READ_ALL` on an attached file means its content is still exactly as it was when attached at the start of this session.
+- `read`: `[W_ANCHOR_RECLAIMED]` means the session's anchor quota was tight and the listed files' anchors were freed; read a freed file again before editing it.

package/src/anchor-registry.ts

@@ -11,7 +11,7 @@ import { errCode, splitLines } from "./utils";
 import * as Diff from "diff";
 import { lineChecksum } from "./hashline";
 import { getAllocatedState, persistSnapshot, type HashStore } from "./hash-store";
-import { ANCHOR_POOL_EXHAUSTED_PREFIX } from "./constants";
+import { ANCHOR_POOL_EXHAUSTED_PREFIX, ANCHOR_RECLAIM_WARNING_CODE, MAX_RECLAIMED_PATHS_REPORTED } from "./constants";
 
 export type RegistryEvent =
   | { kind: "session"; sessionFile: string }
@@ -153,6 +153,10 @@ interface SessionState {
 	everMinted: AnchorMintedSet;
 	probe: number;
 	allocatedChecksum: Map<string, string>;
+	lastUsedAt: Map<string, number>;
+	usageClock: number;
+	reclaimed: string[];
+	shadow?: boolean;
 }
 
 const SIDECAR_SUFFIX = ".registry.jsonl";
@@ -176,7 +180,7 @@ function newSessionState(seed?: string): SessionState {
 			probe = (probe * 256 + byte) % ANCHOR_COUNT;
 		}
 	}
-	return { owned: new Map(), served: new Map(), everMinted: new Set(), probe, allocatedChecksum: new Map() };
+	return { owned: new Map(), served: new Map(), everMinted: new Set(), probe, allocatedChecksum: new Map(), lastUsedAt: new Map(), usageClock: 0, reclaimed: [] };
 }
 
 function seedServedFromOwned(state: SessionState): void {
@@ -195,9 +199,12 @@ export function foldRegistryEvents(events: RegistryEvent[], seed?: string): Sess
   for (const event of events) {
     if (event.kind === "clear") {
       state.owned.clear();
+      state.lastUsedAt.clear();
     } else if (event.kind === "minted") {
       for (const anchor of event.anchors) state.everMinted.add(anchor);
     } else if (event.kind === "allocate") {
+      state.usageClock += 1;
+      state.lastUsedAt.set(event.path, state.usageClock);
       for (const [anchor, checksum] of event.rows) {
         state.owned.set(anchor, { path: event.path, checksum });
         state.everMinted.add(anchor);
@@ -213,9 +220,15 @@ export function foldRegistryEvents(events: RegistryEvent[], seed?: string): Sess
             state.owned.delete(anchor);
           }
         }
+        state.lastUsedAt.delete(event.path);
       }
     }
   }
+  const ownedPaths = new Set<string>();
+  for (const entry of state.owned.values()) ownedPaths.add(entry.path);
+  for (const path of [...state.lastUsedAt.keys()]) {
+    if (!ownedPaths.has(path)) state.lastUsedAt.delete(path);
+  }
   return state;
 }
 
@@ -468,32 +481,96 @@ function fingerprintIndex(state: SessionState, path: string): Map<string, string
 
 export const MINT_PROBE_LIMIT = 8192;
 
-export function mintAnchor(state: SessionState): string {
-  for (let probe = 0; probe < MINT_PROBE_LIMIT; probe++) {
-    state.probe = (state.probe + HASH_PROBE_STRIDE) % ANCHOR_COUNT;
-    const candidate = anchorAt(state.probe);
-    if (!state.owned.has(candidate) && !state.everMinted.has(candidate)) {
-      return candidate;
+function touchPath(state: SessionState, path: string): void {
+	state.usageClock += 1;
+	state.lastUsedAt.set(path, state.usageClock);
+}
+
+function hasOwnedPath(state: SessionState, path: string): boolean {
+	for (const entry of state.owned.values()) {
+		if (entry.path === path) return true;
+	}
+	return false;
+}
+
+function evictPath(state: SessionState, path: string): string[] {
+	const anchors: string[] = [];
+	for (const [anchor, entry] of [...state.owned]) {
+		if (entry.path === path) {
+			anchors.push(anchor);
+			state.owned.delete(anchor);
+		}
+	}
+	state.served.delete(path);
+	state.lastUsedAt.delete(path);
+	if (anchors.length > 0 && state === current()) {
+		appendEvent({ kind: "free", path, anchors });
+	}
+	return anchors;
+}
+
+export function reclaimAnchorSpace(state: SessionState, protectPath?: string): string | undefined {
+	if (state.shadow) return undefined;
+	let victim: string | undefined;
+	let victimTime = Number.POSITIVE_INFINITY;
+	for (const [, entry] of state.owned) {
+		if (entry.path === protectPath) continue;
+		const time = state.lastUsedAt.get(entry.path) ?? -1;
+		if (time < victimTime) {
+			victimTime = time;
+			victim = entry.path;
+		}
+	}
+	if (victim === undefined) return undefined;
+	evictPath(state, victim);
+	state.reclaimed.push(victim);
+	return victim;
+}
+
+export function mintAnchor(state: SessionState, protectPath?: string): string {
+  for (;;) {
+    for (let probe = 0; probe < MINT_PROBE_LIMIT; probe++) {
+      state.probe = (state.probe + HASH_PROBE_STRIDE) % ANCHOR_COUNT;
+      const candidate = anchorAt(state.probe);
+      if (!state.owned.has(candidate) && !state.everMinted.has(candidate)) {
+        return candidate;
+      }
     }
-  }
-  for (let step = 1; step <= ANCHOR_COUNT; step++) {
-    const candidate = anchorAt((state.probe + step) % ANCHOR_COUNT);
-    if (!state.owned.has(candidate)) {
-      for (const served of state.served.values()) served.delete(candidate);
-      return candidate;
+    for (let step = 1; step <= ANCHOR_COUNT; step++) {
+      const candidate = anchorAt((state.probe + step) % ANCHOR_COUNT);
+      if (!state.owned.has(candidate)) {
+        for (const served of state.served.values()) served.delete(candidate);
+        return candidate;
+      }
     }
+    if (reclaimAnchorSpace(state, protectPath) === undefined) break;
   }
   throw new Error(
     `${ANCHOR_POOL_EXHAUSTED_PREFIX}; use write for very large files.`,
   );
 }
 
+export function takeReclaimedPaths(): string[] {
+	const state = current();
+	if (!state || state.reclaimed.length === 0) return [];
+	return state.reclaimed.splice(0, state.reclaimed.length);
+}
+
+export function formatAnchorReclaimNotice(paths: string[]): string | undefined {
+	const unique = [...new Set(paths)];
+	if (unique.length === 0) return undefined;
+	const shown = unique.slice(0, MAX_RECLAIMED_PATHS_REPORTED);
+	const more = unique.length - shown.length;
+	const list = more > 0 ? `${shown.join(", ")} (+${more} more)` : shown.join(", ");
+	return `${ANCHOR_RECLAIM_WARNING_CODE} The session's anchor quota is nearly exhausted; freed all anchors of ${list}, the files least recently read or edited. Read each freed file again before editing it; for read-heavy work, ask the user to run /clear-anchors or start a new session.`;
+}
+
 export function allocateAnchor(path: string, checksum: string): string {
   const state = current();
   if (!state) {
     throw new Error("[E_REGISTRY] The anchor registry is not initialized; call initRegistry on session_start first.");
   }
-  const anchor = mintAnchor(state);
+  const anchor = mintAnchor(state, path);
   state.everMinted.add(anchor);
   state.owned.set(anchor, { path, checksum });
   appendEvent({ kind: "allocate", path, rows: [[anchor, checksum]] });
@@ -505,26 +582,21 @@ export function allocateAnchor(path: string, checksum: string): string {
 export function freeAnchors(path: string, anchors?: string[]): void {
 	const state = current();
 	if (!state) return;
+	if (!anchors) {
+		evictPath(state, path);
+		return;
+	}
 	const freed: string[] = [];
-	if (anchors) {
-		for (const anchor of anchors) {
-			if (state.owned.has(anchor)) {
-				freed.push(anchor);
-				state.owned.delete(anchor);
-				state.served.get(path)?.delete(anchor);
-			}
+	for (const anchor of anchors) {
+		if (state.owned.has(anchor)) {
+			freed.push(anchor);
+			state.owned.delete(anchor);
+			state.served.get(path)?.delete(anchor);
 		}
-	} else {
-		for (const [anchor, entry] of [...state.owned]) {
-			if (entry.path === path) {
-				freed.push(anchor);
-				state.owned.delete(anchor);
-			}
-		}
-		state.served.delete(path);
 	}
 	if (freed.length > 0) {
-		appendEvent({ kind: "free", path, anchors: anchors ?? undefined });
+		if (!hasOwnedPath(state, path)) state.lastUsedAt.delete(path);
+		appendEvent({ kind: "free", path, anchors });
 	}
 }
 
@@ -534,6 +606,8 @@ export function clearRegistry(): void {
 	state.owned.clear();
 	state.served.clear();
 	state.allocatedChecksum.clear();
+	state.lastUsedAt.clear();
+	state.reclaimed.length = 0;
 	appendEvent({ kind: "clear" });
 }
 
@@ -609,6 +683,10 @@ export function shadowStateFrom(state: SessionState): SessionState {
 		everMinted: new ShadowMintedSet(state.everMinted),
 		probe: state.probe,
 		allocatedChecksum: state.allocatedChecksum,
+		lastUsedAt: new Map(state.lastUsedAt),
+		usageClock: state.usageClock,
+		reclaimed: [],
+		shadow: true,
 	};
 }
 
@@ -721,7 +799,7 @@ export function alignOwnershipWithSpans(
     }
     for (let k = 0; k < span.replacementCount; k++) {
       if (replacement[k] !== undefined) continue;
-      const anchor = mintAnchor(state);
+      const anchor = mintAnchor(state, path);
       const checksum = newChecksums[start + k]!;
       minted.push({ index: start + k, anchor, checksum });
       state.owned.set(anchor, { path, checksum });
@@ -769,7 +847,7 @@ export function alignOwnership(
     if (part.added) {
       for (let k = 0; k < count; k++) {
         const checksum = newChecksums[newIdx + k]!;
-        const anchor = mintAnchor(state);
+        const anchor = mintAnchor(state, path);
         state.everMinted.add(anchor);
         state.owned.set(anchor, { path, checksum });
         minted.push({ index: newIdx + k, anchor, checksum });
@@ -792,7 +870,7 @@ export function alignOwnership(
         const entry = state.owned.get(anchor);
         const checksum = newChecksums[newIdx + k]!;
         if (entry && entry.path !== path) {
-          const fresh = mintAnchor(state);
+          const fresh = mintAnchor(state, path);
           state.owned.set(fresh, { path, checksum });
           anchors[newIdx + k] = fresh;
         } else {
@@ -834,6 +912,7 @@ export async function allocateFileAnchors(
   ensureRegistry();
   const registry = current();
   const shadow = options?.shadow === true;
+  if (!shadow && registry) touchPath(registry, path);
   const lines = splitLines(content);
   const checksums = lines.map(lineChecksum);
   if (options?.previous?.spans) {
@@ -870,7 +949,7 @@ export async function allocateFileAnchors(
           const candidates = reuseIndex.get(checksum) ?? [];
           const taken = reuseTaken.get(checksum) ?? 0;
           reuseTaken.set(checksum, taken + 1);
-          const anchor = taken < candidates.length ? candidates[taken]! : mintAnchor(state);
+          const anchor = taken < candidates.length ? candidates[taken]! : mintAnchor(state, path);
           state.everMinted.add(anchor);
           state.owned.set(anchor, { path, checksum });
           return anchor;
@@ -890,6 +969,7 @@ export async function allocateFileAnchors(
 export function adoptAnchors(path: string, entries: Map<string, string>): void {
 	ensureRegistry();
 	const state = current()!;
+	touchPath(state, path);
 	let served = state.served.get(path);
 	if (!served) {
 		served = new Map();
@@ -967,12 +1047,17 @@ function isClaimedSidecar(sidecar: string): boolean {
   return false;
 }
 
+function isExpectedAccessError(error: unknown): boolean {
+  const code = errCode(error);
+  return code === "EPERM" || code === "EACCES";
+}
+
 export async function gcRegistrySidecars(): Promise<void> {
   let names: string[];
   try {
     names = await readdir(sessionClaimsDir());
   } catch (error) {
-    if (errCode(error) !== "ENOENT") console.error("Failed to list registry sidecars:", error);
+    if (errCode(error) !== "ENOENT" && !isExpectedAccessError(error)) console.error("Failed to list registry sidecars:", error);
     return;
   }
   for (const name of names) {
@@ -982,7 +1067,7 @@ export async function gcRegistrySidecars(): Promise<void> {
         const tmpStat = await stat(tmpPath);
         if (Date.now() - tmpStat.mtimeMs > 60 * 60 * 1000) await rm(tmpPath, { force: true });
       } catch (error) {
-        if (errCode(error) !== "ENOENT") console.error("Failed to inspect registry sidecar:", error);
+        if (errCode(error) !== "ENOENT" && !isExpectedAccessError(error)) console.error("Failed to inspect registry sidecar:", error);
       }
       continue;
     }
@@ -995,8 +1080,12 @@ export async function gcRegistrySidecars(): Promise<void> {
       await stat(sessionFile);
     } catch (error) {
       if (errCode(error) === "ENOENT") {
-        await rm(sidecar, { force: true });
-      } else {
+        try {
+          await rm(sidecar, { force: true });
+        } catch (removeError) {
+          if (!isExpectedAccessError(removeError)) throw removeError;
+        }
+      } else if (!isExpectedAccessError(error)) {
         console.error("Failed to inspect registry sidecar:", error);
       }
     }

package/src/auto-read-all.ts

@@ -11,6 +11,7 @@ import {
 } from "./constants";
 import { normalizeAutoReadAllIgnoreEntry, type AutoReadAllMode } from "./config";
 import { serveRows } from "./served";
+import { formatAnchorReclaimNotice, takeReclaimedPaths } from "./anchor-registry";
 import { readNormFile, safeSnapId } from "./file-reader";
 import { resolveRgPath } from "./grep";
 import { globToRegex } from "./glob";
@@ -438,7 +439,8 @@ export async function buildAutoReadAllInjection(cwd: string, budgetBytes: number
   const coverage = `[coverage: ${completeFiles} complete]`;
   const completeNames = sections.map((section) => section.file);
   const machineList = `[files complete: ${JSON.stringify(completeNames)} omitted: ${JSON.stringify(omitted)}]`;
-  const text = `${HEADER}\n\n${coverage}\n${machineList}\n\n${sectionTexts.join("\n\n")}\n\n${buildFooter(sections.length, discovery, omitted)}`;
+  const reclaimNotice = formatAnchorReclaimNotice(takeReclaimedPaths());
+  const text = `${HEADER}\n\n${coverage}\n${machineList}\n\n${sectionTexts.join("\n\n")}\n\n${buildFooter(sections.length, discovery, omitted)}${reclaimNotice !== undefined ? `\n${reclaimNotice}` : ""}`;
   return { text, files: sections.length, bytes, omitted, completeFiles };
 }
 

package/src/batch.ts

@@ -16,7 +16,7 @@ import {
   type HEdit,
   type PlannedEdit,
 } from "./hashline";
-import { adoptAnchors, servedForPath } from "./anchor-registry";
+import { adoptAnchors, servedForPath, formatAnchorReclaimNotice, takeReclaimedPaths } from "./anchor-registry";
 import { restoreEndings, stripBOM, toLF, type LineEnding } from "./normalize";
 import { assertInsertReq, assertReq, normReq } from "./payload-contract";
 import { saveUndo } from "./replace-undo";
@@ -638,6 +638,8 @@ async function finishBatch(member: PlannedMember, signal?: AbortSignal): Promise
     if (error instanceof Error) error.message = withAbortSuffix(error.message, runtime.display);
     throw error;
   }
+  const reclaimNotice = formatAnchorReclaimNotice(takeReclaimedPaths());
+  if (reclaimNotice !== undefined) warnings.push(reclaimNotice);
   if (composed === base.content) {
     const snapshotId = await safeSnapId(paths.absolutePath, "noop edit");
     return combinedNoop(paths.displayPath, member, runtime, snapshotId);
@@ -700,6 +702,8 @@ async function finishBatch(member: PlannedMember, signal?: AbortSignal): Promise
     const detail = error instanceof Error ? error.message : String(error);
     throw new Error(`${detail} File was written; anchor finalization failed. One undo reverts. Call read for fresh anchors.`);
   }
+  const writeReclaim = formatAnchorReclaimNotice(takeReclaimedPaths());
+  if (writeReclaim !== undefined) warnings.push(writeReclaim);
   const range = changedRange(base.content, composed);
   let added = 0;
   let removed = 0;
@@ -746,6 +750,8 @@ async function finishBatch(member: PlannedMember, signal?: AbortSignal): Promise
 async function combinedNoop(path: string, member: PlannedMember, runtime: BatchState, snapshotId: string | undefined): Promise<TResult> {
   const executed = runtime.applied + runtime.noops;
   const warnings = [...runtime.warnings];
+  const reclaimNotice = formatAnchorReclaimNotice(takeReclaimedPaths());
+  if (reclaimNotice !== undefined) warnings.push(reclaimNotice);
   const noop = buildNoop(
     {
       path,

package/src/commit.ts

@@ -6,6 +6,7 @@ import { saveUndo } from "./replace-undo";
 import { getDiffContextLines } from "./config";
 import { safeSnapId } from "./file-reader";
 import { writeAtomic } from "./fs-write";
+import { formatAnchorReclaimNotice, takeReclaimedPaths } from "./anchor-registry";
 import { servedHashesFromDiff, serveRows } from "./served";
 import { lineHashes } from "./hashline";
 import { spanForEdit } from "./replace";
@@ -27,6 +28,8 @@ export async function commitEdit(pipe: PipelineResult, meta: CommitMeta): Promis
   const { path, absolutePath, mutationTargetPath, signal } = meta;
   const warnings = [...(meta.prefixWarnings ?? []), ...pipe.warnings];
   const editsAttempted = 1;
+  const readReclaim = formatAnchorReclaimNotice(takeReclaimedPaths());
+  if (readReclaim !== undefined) warnings.push(readReclaim);
 
   if (pipe.result === pipe.originalNormalized) {
     const noopSnapshotId = await safeSnapId(absolutePath, "noop edit");
@@ -120,6 +123,8 @@ export async function commitEdit(pipe: PipelineResult, meta: CommitMeta): Promis
     const detail = error instanceof Error ? error.message : String(error);
     throw new Error(`${detail} File was written; anchor finalization failed. One undo reverts. Call read for fresh anchors.`);
   }
+  const writeReclaim = formatAnchorReclaimNotice(takeReclaimedPaths());
+  if (writeReclaim !== undefined) warnings.push(writeReclaim);
   const successInput = {
     path,
     originalNormalized: pipe.originalNormalized,

package/src/constants.ts

@@ -19,6 +19,9 @@ export const NUL_CONTENT_MSG =
 export const ANCHOR_POOL_EXHAUSTED_PREFIX =
   "[E_FILE_TOO_LARGE] The session's anchor pool is exhausted";
 
+export const ANCHOR_RECLAIM_WARNING_CODE = "[W_ANCHOR_RECLAIMED]";
+export const MAX_RECLAIMED_PATHS_REPORTED = 10;
+
 export const AUTO_READ_ALL_CUSTOM_TYPE = "hashline-auto-read-all";
 export const AUTO_READ_ALL_MAX_FILES = 500;
 export const AUTO_READ_ALL_MAX_FILE_BYTES = 200_000;

package/src/edit-common.ts

@@ -163,8 +163,9 @@ export async function resolveEditTargetWithRequirement(input: PathRequirementInp
   return anchorTarget;
 }
 
+const AUTO_FIX_WARNING_CODES = ["[W_BAD_SHAPE]", "[W_BAD_REF]", "[W_INVALID_PATCH]", "[W_BARE_HASH_PREFIX]"];
 export async function throwIfStrictInput(warnings: string[]): Promise<void> {
-  const fixes = warnings.filter((warning) => warning.startsWith("[W_"));
+  const fixes = warnings.filter((warning) => AUTO_FIX_WARNING_CODES.some((code) => warning.startsWith(code)));
   if (fixes.length === 0) return;
   const { strictInput } = await readConfig();
   if (strictInput === true) {

package/src/grep.ts

@@ -14,7 +14,7 @@ import { toCwd, toDisplayPath } from "./paths";
 import { loadP, loadGuide } from "./prompts";
 import { normReq } from "./payload-contract";
 import { abortIf, clipLine, errCode, gutterWidth, isRec, makePrepareArguments, rejectUnknownFields, truncateToBytes, visLines } from "./utils";
-import { withAnchorSession } from "./anchor-registry";
+import { withAnchorSession, formatAnchorReclaimNotice, takeReclaimedPaths } from "./anchor-registry";
 import { serveRows } from "./served";
 import { Text } from "@earendil-works/pi-tui";
 import { expandHint, getResultText, reuseText, type CallT, type FgT } from "./replace-render";
@@ -660,6 +660,8 @@ export function regGrep(pi: ExtensionAPI): void {
           .map((hit) => `=== ${hit.displayPath} ===\n${hit.rows.join("\n")}`)
           .join("\n");
         const notes: string[] = [];
+        const reclaimNotice = formatAnchorReclaimNotice(takeReclaimedPaths());
+        if (reclaimNotice !== undefined) notes.push(reclaimNotice);
         if (rowTruncated) notes.push(`[grep: output truncated at ${DEFAULT_MAX_LINES} rows or ${formatSize(DEFAULT_MAX_BYTES)}; refine the pattern to see more.]`);
         if (limitTruncated) notes.push(`[grep: showing first ${limit} matches; increase limit to see more.]`);
         if (linesReplaced > 0) notes.push(`[grep: ${linesReplaced} line(s) exceed ${formatSize(MAX_GREP_LINE_BYTES)} and are shown as truncated fragments; use read to see the full lines.]`);

package/src/hash-store.ts

@@ -588,7 +588,7 @@ async function statMissing(rows: { path: string }[]): Promise<string[]> {
         } catch (error: unknown) {
           const code = errCode(error);
           if (code !== "ENOENT" && code !== "ENOTDIR") {
-            console.error("Failed to stat hash store path:", row.path, error);
+            if (code !== "EPERM" && code !== "EACCES") console.error("Failed to stat hash store path:", row.path, error);
             return undefined;
           }
           return row.path;

package/src/paths.ts

@@ -16,7 +16,11 @@ function configBase(): string {
 }
 
 export function configDir(): string {
-  return join(configBase(), "pi-hashline-edit-pro");
+  const override = process.env.PI_HASHLINE_DIR;
+  if (override && !isAbsolute(override)) {
+    throw new Error("[E_CONFIG] PI_HASHLINE_DIR must be an absolute path");
+  }
+  return override || join(configBase(), "pi-hashline-edit-pro");
 }
 
 export function configPath(): string {

package/src/read.ts

@@ -19,7 +19,7 @@ import { withReadPrompts, DEFAULT_EDIT_FLAGS, type EditToolFlags } from "./edit-
 import { valAccess } from "./validation";
 import { readConfig } from "./config";
 import { resolveTarget } from "./fs-write";
-import { withAnchorSession, servedForPath, sessionKeyFor } from "./anchor-registry";
+import { withAnchorSession, servedForPath, sessionKeyFor, formatAnchorReclaimNotice, takeReclaimedPaths } from "./anchor-registry";
 import { serveRows } from "./served";
 import { getAutoReadAllSnapshot } from "./auto-read-all-state";
 import { Text } from "@earendil-works/pi-tui";
@@ -258,10 +258,12 @@ export function regRead(pi: ExtensionAPI, flags: EditToolFlags = DEFAULT_EDIT_FL
 				);
 				serveRows(resolvedPath, fileHashes, fileLines, preview.servedHashes);
 				const snapshotId = await safeSnapId(absolutePath, "read");
-				const previewText =
-					hadUtf8DecodeErrors
-						? `${preview.text}\n\n[Non-UTF-8 bytes shown as U+FFFD; editing rewrites the file as UTF-8.]`
-						: preview.text;
+				const reclaimNotice = formatAnchorReclaimNotice(takeReclaimedPaths());
+				const previewText = [
+					preview.text,
+					hadUtf8DecodeErrors ? "[Non-UTF-8 bytes shown as U+FFFD; editing rewrites the file as UTF-8.]" : undefined,
+					reclaimNotice,
+				].filter((part): part is string => part !== undefined).join("\n\n");
 
 				return {
 					content: [{ type: "text", text: previewText }],

package/src/replace-undo.ts

@@ -6,7 +6,7 @@ import { Type } from "typebox";
 import { loadHashStore, persistSnapshot, upsertUndo, getUndoEntry, deleteUndo, type UndoRecord } from "./hash-store";
 import { servedHashesFromDiff, serveRows } from "./served";
 import { lineChecksum } from "./hashline";
-import { freeAnchors, adoptAnchors, withAnchorSession } from "./anchor-registry";
+import { freeAnchors, adoptAnchors, withAnchorSession, formatAnchorReclaimNotice, takeReclaimedPaths } from "./anchor-registry";
 import { resolveInCwd, writeAtomic, type FileIdentity } from "./fs-write";
 import { toLF, stripBOM, restoreEndings, type LineEnding } from "./normalize";
 import { genDiff, genPatch, spansFromHashes } from "./replace-diff";
@@ -237,6 +237,8 @@ export function regUndo(pi: ExtensionAPI, flags: EditToolFlags = DEFAULT_EDIT_FL
           parts.push(
             "Call read for fresh anchors.",
           );
+          const reclaimNotice = formatAnchorReclaimNotice(takeReclaimedPaths());
+          if (reclaimNotice !== undefined) parts.push(reclaimNotice);
 
           const patchResult = genPatch(path, currentNormalized, undo.content);
           return {
@@ -255,7 +257,7 @@ export function regUndo(pi: ExtensionAPI, flags: EditToolFlags = DEFAULT_EDIT_FL
                 classification: "applied",
                 editsAttempted: 1,
                 noopEditsCount: 0,
-                warningsCount: 0,
+                warningsCount: reclaimNotice !== undefined ? 1 : 0,
                 firstChangedLine: restoredRange?.firstChangedLine,
                 lastChangedLine: restoredRange?.lastChangedLine,
                 addedLines: linesRemovedByReplace,