@d3ara1n/pi-hashline-edit 0.5.0 → 0.5.1

package/README.md

@@ -1,5 +1,7 @@
 # @d3ara1n/pi-hashline-edit
 
+[![npm version](https://img.shields.io/npm/v/@d3ara1n/pi-hashline-edit)](https://www.npmjs.com/package/@d3ara1n/pi-hashline-edit) [![npm downloads](https://img.shields.io/npm/dm/@d3ara1n/pi-hashline-edit)](https://www.npmjs.com/package/@d3ara1n/pi-hashline-edit) [![license](https://img.shields.io/npm/l/@d3ara1n/pi-hashline-edit)](https://www.npmjs.com/package/@d3ara1n/pi-hashline-edit) [![Explicit Edit Benchmark](https://img.shields.io/endpoint?url=https://huggingface.co/datasets/alexshpunt/explicit-edit-benchmark/resolve/main/badges/d3ara1n-pi-hashline-edit.json&style=flat-square)](https://huggingface.co/spaces/alexshpunt/benchmark-explorer?card=harness%3Ad3ara1n-pi-hashline-edit%40latest)
+
 > Hashline-style file editing for [pi](https://github.com/earendil-works/pi-coding-agent) — line-anchored edits verified by content hash (replacing `oldText`/`newText` matching), plus a location-blind `replace` tool for bulk + regex transforms.
 
 Edits reference lines by `LINE#HASH` anchors (copied from `read`/`grep` output) instead of retyping the code to be changed — eliminating string-not-found loops and whitespace battles at the root.
@@ -24,21 +26,27 @@ Routine local code editing in pi — the common case. If you spend turns fightin
 
 Set `hashlineEdit.enabled = false` (or uninstall) to fall back to the built-in `read`/`edit`/`grep` when you need **remote or custom-storage files** — the overrides read/write/search the local filesystem directly, so pi's custom `ReadOperations`/`GrepOperations` (SSH, etc.) aren't supported. The same switch lets you opt out per-project. All four tools — `read`, `grep`, `edit`, `replace` — are one set governed by this switch: when disabled, `read`/`edit` and plain `grep` calls delegate to the built-ins (`grep` calls using the extended params below still run locally, formatted without anchors) and `replace` refuses (it has no built-in counterpart).
 
-## Model compatibility — field notes
+## Model Compatibility
+
+Hashline replaces the edit protocol the main model was trained on, so real-world reliability depends on the model more than on anything else. Field observations from real sessions, one family per subsection (June 2026, single environment — directional, not benchmarks; vendors iterate fast, re-test on new releases).
+
+### DeepSeek family
+
+**Avoid — silent corruption.** Weak tool-call construction (tested: DeepSeek V4 Flash): ~50% of edits fail on the built-in string-replace, and each fix takes several more rounds — string-replace failures are *divergent*, the model retries from the same wrong memory, but at least they are loud. Hashline's rejected anchors *converge* — a mismatched anchor returns the live content plus a ready-to-resend `LINE#HASH`, so one retry closes the loop — but the raw failure rate is high (~80%), and hashline adds a failure class the built-in edit doesn't have.
+
+`insert_after` semantics invite wrong parameters even when the tool call itself is well-formed: the model fills `body` string-replace-style, copying the anchor line into it (observed on DeepSeek V4 Flash). The toolcall verifies and succeeds, and the line ends up duplicated. Nothing at the tool layer can catch this — the anchor is valid, the model's *intent* was wrong, and no prompt wording cures it (the schema description already forbids the copy). For a weak model, hashline effectively trades loud failures for silent ones: files come out corrupted edit by edit. Keep the plugin off for this profile; if you must run it, review the diff after every edit.
+
+### Kimi family
+
+**Turn the plugin off.** Strong, but not trained on hashline (tested: Kimi K3): built-in string-replace is excellent while hashline draws frequent anchor mistakes. Hashline assumes anchor discipline — copy hashes verbatim from read output, never invent one; a model that hasn't internalized that fabricates anchors no matter how capable. When a strong model keeps hitting anchor errors, the fastest fix is disabling the plugin, not more retries.
 
-Real-world reliability depends on the model more than on anything else. Field observations from real sessions (June 2026, single environment — directional, not benchmarks; vendors iterate fast, re-test on new releases):
+### GLM family
 
-| Model profile | Tested example | Built-in string-replace | hashline-edit | Recommendation |
-|---|---|---|---|---|
-| Weak tool-call construction | DeepSeek V4 Flash | ~50% of edits fail; each fix takes several more `edit` rounds | ~80% of edits fail, but each failure converges in **one** retry | Keep hashline on — fewer total round-trips despite the higher failure rate |
-| Strong, but not trained on hashline | Kimi K3 | Excellent | Frequent anchor mistakes | Turn the plugin off — the built-in `edit` serves this profile better |
-| Strong, follows the schema as given | GLM 5.2 | Occasional not-found / whitespace friction | 100% — the friction disappears | The intended pairing |
+**The intended pairing.** Strong and follows the schema as given (tested: GLM 5.2): the occasional not-found / whitespace friction of built-in string-replace disappears — 100% in testing. Capable models never needed the wording in the first place: GLM used `insert_after` correctly even when the tool description didn't explain the op at all. The mismatch lives in the model, not the tool.
 
-What these numbers actually say:
+### GPT family
 
-- **A high failure rate on weak models is not a hashline problem.** DeepSeek V4 Flash fails at ~50% even on plain string-replace — the root cause is misremembered file content, and no edit protocol fixes that. What changes is the *shape* of a failure: string-replace failures are divergent (the model retries from the same wrong memory, so fixes take multiple rounds), while hashline failures are convergent (a mismatched anchor returns the live content plus a ready-to-resend `LINE#HASH`, so one retry closes the loop without trusting the model's memory).
-- **Strong ≠ automatic win.** Hashline assumes anchor discipline — copy hashes verbatim from read output, never invent one. A model that hasn't internalized that will fabricate anchors no matter how capable it is. If a strong model keeps hitting anchor errors, the fastest fix is disabling the plugin, not more retries.
-- **Some errors are invisible to any edit protocol.** On weak models `insert_after` is sometimes misread as string-replace-style: the model copies the anchor line into `body` (observed on DeepSeek V4 Flash), the toolcall verifies and succeeds, and the line ends up duplicated in the file. Nothing at the tool layer can catch this — the anchor is valid; the model's *intent* was wrong, and no amount of prompt wording cures it (the schema description already forbids the copy). Capable models never needed the wording in the first place: GLM used `insert_after` correctly back when the tool description didn't explain the op at all. The mismatch lives in the model, not the tool.
+**No reservations.** Structured ops are home turf for this family (tested: GPT 5.6 sol/terra/luna): no fabricated or mistyped anchors observed, and `insert_after` was never misused — the anchor-line-into-`body` duplication (see DeepSeek above) never occurred. The few rejected anchors were the *expected* kind: a size-changing `edit` invalidating the hashes of the lines below it between edits — the documented hash-drift tradeoff rather than a model error, and exactly what the self-healing rescan exists to rescue. Even those ran fewer than expected; small-sample observation, take it directionally.
 
 ## Gotchas (vs. the built-in `read`/`edit`)
 
@@ -67,8 +75,68 @@ A separate, location-blind tool for transforms `edit` can't express: replace **a
 - **Shifted-anchor recovery**: a mismatched anchor isn't a dead end. The applicator rescans ±`shiftRadius` lines for the original content — holding the original line number fixed and re-hashing each candidate (`hash(line, candidate) === cited` iff the candidate *is* the original) — and returns a ready-to-resend anchor on a unique hit, the candidate list when ambiguous, or the cited line's live content when nothing matches. The model retries without a re-read in the common drift case.
 - **Atomic batches, all failures collected**: every op in one `edit` is verified against the same snapshot; if any anchor fails, *all* failures (each with its recovery) are returned together and nothing is written — partial writes would shift lines and invalidate the very recovery info just returned.
 - **Chain edits without re-reading**: a successful `edit` returns `Updated anchors` for the lines it produced (and the line that shifted into a deletion gap), so the next edit can cite them directly.
+- **Byte-faithful writes**: `edit` rewrites only the lines you name. CRLF files keep CRLF, and a file whose last line has no terminator does not gain one — the state `splitLines` discards is captured before the edit and restored after it. `read` states the fact in its header (`· no trailing newline`), since the numbered rows cannot show it.
 - **No legacy compatibility on `edit`**: `edit` accepts only structured hashline ops; sending legacy `oldText`/`newText` is rejected at the schema layer (never silently degrades) — so you always know whether hashline is actually in use. Bulk/regex replacement is a *separate* tool, `replace`, not an `edit` mode (see below).
 
+## Why line hashes, not file tags
+
+### The short version
+
+This plugin is a line-hash editor: every line comes back tagged with a content hash that folds in its line number, and you edit by citing that `LINE#HASH`. That is, deliberately, the *original* hashline idea — the one omp shipped in February 2026 and then walked away from. omp's current engine anchors on a **whole-file** hash instead, and has since mid-2026. I looked at that route and stayed on the line-hash one on purpose. What follows is my case for that choice, stated as a tradeoff rather than a verdict — the honest limitations, including the ones that argue for the other route, come right after.
+
+### Where this comes from
+
+The idea that a model should edit by pointing at a **stable, verifiable anchor** instead of retyping code it already saw is not mine — it is can1357's, argued in [*The Harness Problem*](https://blog.can.ac/2026/02/12/the-harness-problem/) (2026-02-12), and omp's first implementation was exactly this shape: every read line tagged with a short per-line content hash, edits expressed as structured `old`/`new` ops. That first design had a real problem, and omp and I fixed it in opposite directions.
+
+**Identical lines collide.** A per-line *content* hash gives every `}`, every `)`, every blank line the same hash — and a hash that is not unique is not an anchor. omp's fix was to stop hashing lines and hash the **whole file** instead: a 4-hex file tag, with no per-line hash in `read` output at all. My fix was to fold the line number into each line's hash, so two identical lines at different positions can never share one — unique by construction, no file-level state required.
+
+That single divergence cascades into everything else. (It also means the picture most people have of "hashline" is the line-hash one: omp's own docs site still describes per-line anchors that its current implementation no longer emits.)
+
+### The case against the file-tag route
+
+I can't speak to omp's motives for the switch — collision-proofing a per-line hash is hard, and the file tag sidesteps it entirely. But the clearest *payoff* I see in a whole-file tag is one my design gives up: **awareness of edits made by anyone else.** If another process touches the file, its whole-file tag changes, the next anchored edit is rejected, and the model is forced to re-read fresh state. For a swarm of agents editing one tree, that is a genuinely good property. It costs three things I wasn't willing to pay:
+
+- **The tag can't tell whether the model actually *read* a line.** A whole-file hash proves the file is byte-for-byte what it was — not that the model ever saw the specific line it is now rewriting. To stop hallucinated edits on never-displayed lines, omp carries a separate `seenLines` guard alongside the tag. A per-line hash *is* the proof of having-seen: you cannot cite `LINE#HASH` without having read that line's content. No side array needed.
+- **It needs out-of-band state.** A 16-bit file tag "is not meaningful outside that store" (omp's own words) — it can collide, so omp keeps a `SnapshotStore`, an LRU of recent file versions, to disambiguate. My hashes are content-derived and self-contained: an anchor is verified by rehashing the current line at that number, at apply time, against nothing but the file on disk. **This plugin has no SnapshotStore, no seenLines array, nothing to keep in sync.** That is the point, not an omission.
+- **The verification is coarse.** A whole-file tag couples every edit to the entire file: an unrelated change *anywhere* invalidates the tag and drags the whole patch through recovery. Line hashes verify only the lines you cite — an unrelated edit elsewhere never blocks you.
+
+### Why a JSON schema, not a text DSL
+
+The other visible difference: omp delivers edits as a **text patch language** (`PUT`/`CUT`/`REM`/`MV` today, `SWAP`/`DEL`/`INS` before that, JSON before *that*). This plugin uses **structured JSON ops**. Two reasons:
+
+- **Validation belongs to the tool, not the model.** A JSON schema rejects a malformed op at the parameter layer before any logic runs. A text DSL puts the burden of emitting exactly-correct syntax back on the model, and the error rate is high enough that the DSL route accretes layer after layer of lenient parsing and heuristic repair to compensate — omp has shipped both, including a documented incident where the repair silently dropped content. The whole reason to anchor by hash was to stop depending on the model reproducing text perfectly; a hand-written DSL quietly reintroduces that dependency on the other side of the call.
+- **The token savings aren't worth it.** A DSL saves a handful of structural characters per op. Against a higher malformed-edit rate and the cost of format churn — omp's patch syntax has broken compatibly five-plus times, stranding third-party ports on dead dialects — that saving is noise.
+
+### Compared by capability
+
+Not by version: omp's later generations refine the same whole-file-tag core, so the real comparison is *line-hash route* vs *file-tag route*.
+
+| Capability | This plugin (line-hash) | omp (file-tag) |
+|---|---|---|
+| Anchor identity | per-line `LINE#HASH`, line number folded in | whole-file 4-hex `#TAG`, bare line numbers |
+| Identical-line collisions | impossible by construction | n/a (no per-line hash); the file tag itself can collide in 16 bits |
+| Out-of-band state | **none** | `SnapshotStore` (LRU) + `seenLines` guard |
+| "Did the model read this line?" | proven by the anchor itself | needs the separate `seenLines` array |
+| Verification granularity | only the cited lines (surgical) | whole file — any drift enters recovery |
+| Concurrent external edits | not a goal; re-read to proceed | detected by design — tag change forces a re-read |
+| Wire format | JSON schema ops | text patch DSL |
+| Malformed edits | rejected at the schema layer | lenient parsing + heuristic repair |
+| Format stability | one schema | ≥5 breaking format generations |
+| Drift recovery | ±15-line rescan → fresh anchor, else re-read | line-remap replay, fail-closed |
+| Expressiveness | fine-grained ops + separate `replace` | syntax blocks, cross-file registers, `REM`/`MV` |
+| Read-time token cost | 2–4 chars per line | none at read time; cost moves to mismatch output |
+
+### Honest limitations
+
+Including the ones that argue *for* the route I didn't take.
+
+- **Hash drift after an edit.** Because the line number is part of the hash, inserting or deleting lines changes every subsequent line's hash. A successful edit hands back fresh anchors for the region it just produced, and the ±15-line rescan rescues nearby drift — but to cite lines well below a size-changing edit, you re-read. That is the price of stateless verification: I keep no snapshot that would track those shifts for you. I consider it a fair trade for having no out-of-band state to corrupt or resync; a clean core matters more to me than saving a read.
+- **No multi-agent story.** If several agents edit one tree, the file-tag route's external-edit detection is a real advantage this design does not have.
+- **Hash transcription is itself error-prone.** Anchoring assumes the model copies the hash verbatim. It doesn't always: *"It sees `483:d4` in the input, writes `483:3a` in the output. Every model does this, including Opus."* ([geometricagi, *AST Edits*](https://geometricagi.github.io/2026/04/02/ast-edits.html), 2026-04-02). This is a failure class the built-in string-replace does not have — see Model Compatibility above; on a model that hasn't internalized anchor discipline, turn the plugin off rather than fight it.
+- **The edit format may not be your bottleneck at all.** An independent benchmark ([nwyin, *edit-bench*](https://nwyin.com/blogs/hashline-vs-replace-edit-bench.html)) found the hashline-vs-replace delta to be language-dependent — a real penalty on Python, neutral on TypeScript, a wash on Rust — and concluded that *"edit format is not the bottleneck"*: model-to-model differences dwarf format-to-format ones. It also found that the whitespace near-miss anchoring is meant to kill barely occurs — fuzzy matching triggered 0 times across 114 successful edits.
+- **A silent success is worse than a loud failure.** Any anchor scheme is only as safe as its implementation. opencode's early hashline port returned `Updated` while writing to the wrong line ([issue #15424](https://github.com/anomalyco/opencode/issues/15424)) — a buggy anchor check manufactures false trust. This plugin's recovery is built to fail closed and hand back live content instead of guessing, but the warning generalizes.
+- **Model dependence is real and not universally in my favor.** omp routes kimi, mimo, deepseek-v4-flash and step-3.7-flash *away* from hashline by default (they miscount anchors or drop the tag header). My own field notes agree on Kimi and disagree on DeepSeek — same model, opposite conclusions in different environments. There is no globally best edit format; there is a model × task × implementation triple.
+
 ## Protocol
 
 `read` output (each line anchored):

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "@d3ara1n/pi-hashline-edit",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "description": "Hashline-style file editing for pi — line-anchored edits verified by content hash, replacing oldText/newText matching",
+  "homepage": "https://github.com/d3ara1n/pi-extensions/tree/main/packages/pi-hashline-edit#readme",
+  "bugs": {
+    "url": "https://github.com/d3ara1n/pi-extensions/issues"
+  },
   "keywords": [
     "pi-package",
     "pi"
   ],
   "main": "src/index.ts",
   "scripts": {
-    "test": "node --test src/core/*.test.ts src/pi/*.test.ts"
+    "test": "node --test src/core/*.test.ts src/pi/*.test.ts",
+    "test:integration": "node --test src/integration/*.test.ts"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"

package/src/core/apply.test.ts

@@ -171,6 +171,37 @@ test("CRLF line endings preserved", () => {
 	if (r.ok) assert.equal(r.text, "A\r\nb\r\n");
 });
 
+test("a file without a final newline keeps not having one", () => {
+	const text = "a\nb";
+	const r = applyEdits(text, [{ op: "replace", start: at(text, 2), body: ["B"] }]);
+	assert.equal(r.ok, true);
+	if (r.ok) assert.equal(r.text, "a\nB");
+});
+
+test("CRLF without a final newline keeps not having one", () => {
+	const text = "a\r\nb";
+	const r = applyEdits(text, [{ op: "replace", start: at(text, 1), body: ["A"] }]);
+	assert.equal(r.ok, true);
+	if (r.ok) assert.equal(r.text, "A\r\nb");
+});
+
+test("appending to a file without a final newline keeps it absent", () => {
+	const text = "a";
+	const r = applyEdits(text, [{ op: "append", body: ["b"] }]);
+	assert.equal(r.ok, true);
+	if (r.ok) assert.equal(r.text, "a\nb");
+});
+
+test("noop is still detected when the file lacks a final newline", () => {
+	// Before the final-newline fix, joinLines appended a terminator, so a
+	// byte-identical body looked like a change and the edit silently rewrote the
+	// file — the noop guard never fired.
+	const text = "a\nb";
+	const r = applyEdits(text, [{ op: "replace", start: at(text, 1), body: ["a"] }]);
+	assert.equal(r.ok, false);
+	if (!r.ok) assert.equal(r.failure.kind, "noop");
+});
+
 // --- shifted-anchor recovery ---
 
 test("shifted recovery: content moved down → found with a fresh anchor", () => {

package/src/core/apply.ts

@@ -30,7 +30,7 @@
  */
 
 import { computeLineHash } from "./hash.ts";
-import { detectLineEnding, joinLines, splitLines } from "./lines.ts";
+import { detectLineEnding, hasFinalNewline, joinLines, splitLines } from "./lines.ts";
 import type { Anchor, AnchorFailure, AnchorRecovery, ApplyResult, Edit } from "./types.ts";
 
 /** Line-level operation: replace the raw lines in the `[lo, hi)` range (0-based, hi exclusive) with newLines. */
@@ -218,7 +218,7 @@ export function applyEdits(text: string, edits: Edit[], hashLen = 4, shiftRadius
 		result = [...result.slice(0, op.lo), ...op.newLines, ...result.slice(op.hi)];
 	}
 
-	const newText = joinLines(result, ending);
+	const newText = joinLines(result, ending, hasFinalNewline(text));
 	if (newText === text) {
 		return {
 			ok: false,

package/src/core/index.ts

@@ -9,5 +9,5 @@
 
 export * from "./types.ts";
 export { computeLineHash, hashFileLines } from "./hash.ts";
-export { splitLines, joinLines, detectLineEnding } from "./lines.ts";
+export { splitLines, joinLines, detectLineEnding, hasFinalNewline } from "./lines.ts";
 export { applyEdits } from "./apply.ts";

package/src/core/lines.test.ts

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { splitLines, joinLines, detectLineEnding } from "./lines.ts";
+import { splitLines, joinLines, detectLineEnding, hasFinalNewline } from "./lines.ts";
 
 test("splitLines edge cases", () => {
 	assert.deepEqual(splitLines(""), []);
@@ -23,6 +23,29 @@ test("joinLines restores line endings", () => {
 	assert.equal(joinLines(["a", "b"], "lf"), "a\nb\n");
 });
 
+test("joinLines preserves the final-newline state when told to", () => {
+	assert.equal(joinLines(["a", "b"], "lf", false), "a\nb");
+	assert.equal(joinLines(["a", "b"], "crlf", false), "a\r\nb");
+	assert.equal(joinLines(["a"], "lf", false), "a");
+	assert.equal(joinLines([], "lf", false), "");
+});
+
+test("hasFinalNewline", () => {
+	assert.equal(hasFinalNewline("a\nb"), false);
+	assert.equal(hasFinalNewline("a\nb\n"), true);
+	assert.equal(hasFinalNewline("a\r\nb"), false);
+	assert.equal(hasFinalNewline("a\r\nb\r\n"), true);
+	assert.equal(hasFinalNewline("a"), false);
+	// no lines, no terminator — rejoining [] yields "" either way
+	assert.equal(hasFinalNewline(""), true);
+});
+
+test("split/join round-trips a document byte for byte", () => {
+	for (const text of ["a", "a\n", "a\nb", "a\nb\n", "a\n\n", "\n", "a\r\nb", "a\r\nb\r\n", ""]) {
+		assert.equal(joinLines(splitLines(text), detectLineEnding(text), hasFinalNewline(text)), text);
+	}
+});
+
 test("detectLineEnding", () => {
 	assert.equal(detectLineEnding("a\nb\n"), "lf");
 	assert.equal(detectLineEnding("a\r\nb\r\n"), "crlf");

package/src/core/lines.ts

@@ -1,12 +1,17 @@
 /**
- * Line text helpers: split/join with CRLF normalization and line-ending
- * detection.
+ * Line text helpers: split/join with CRLF normalization, line-ending detection
+ * and final-newline fidelity.
  *
  * CRLF: splitLines strips the trailing `\r` from each line (hashes are based on
  * clean lines, matching the `\r`-free content the model copies from the
  * display); detectLineEnding records the original ending so joinLines can
  * restore it — guaranteeing a CRLF file keeps its endings after edit.
  *
+ * Final newline: splitLines discards whether the input ended with a terminator
+ * (a trailing newline terminates the last line, it does not create one).
+ * joinLines therefore takes that state as an argument rather than assuming it —
+ * a file that lacked a final newline must not silently gain one.
+ *
  * @module pi-hashline-edit/core
  */
 
@@ -34,9 +39,29 @@ export function detectLineEnding(text: string): LineEnding {
 	return text.includes("\r\n") ? "crlf" : "lf";
 }
 
-/** Join a line array back into text, restoring the given line ending (default LF). Non-empty files end with a newline. */
-export function joinLines(lines: readonly string[], ending: LineEnding = "lf"): string {
+/**
+ * Whether the text ends with a line terminator — the state splitLines discards
+ * and joinLines needs in order to reproduce a document byte for byte.
+ *
+ * The empty string has no lines and no terminator; it reports `true` so that
+ * rejoining its (also empty) line array — which yields `""` either way —
+ * round-trips.
+ */
+export function hasFinalNewline(text: string): boolean {
+	return text === "" || text.endsWith("\n");
+}
+
+/**
+ * Join a line array back into text, restoring the given line ending (default LF)
+ * and final-newline state (default: terminates with a newline, the convention
+ * for freshly created content).
+ *
+ * Reconstructing an *existing* file must pass `hasFinalNewline(originalText)` so
+ * a missing terminator stays missing.
+ */
+export function joinLines(lines: readonly string[], ending: LineEnding = "lf", finalNewline = true): string {
 	if (lines.length === 0) return "";
 	const sep = ending === "crlf" ? "\r\n" : "\n";
-	return lines.join(sep) + sep;
+	const body = lines.join(sep);
+	return finalNewline ? body + sep : body;
 }

package/src/integration/grep-rg.test.ts

@@ -0,0 +1,46 @@
+/**
+ * Explicit real-ripgrep integration coverage. This is excluded from the default
+ * test script and never delegates to Pi's built-in grep/download path.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { access, constants, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { delimiter, join } from "node:path";
+import { makeGrepOverrideWithBackend } from "../pi/grep-tool.ts";
+
+async function findPathRg(): Promise<string | null> {
+  for (const directory of process.env.PATH?.split(delimiter) ?? []) {
+    if (!directory) continue;
+    const candidate = join(directory, "rg");
+    try {
+      await access(candidate, constants.X_OK);
+      return candidate;
+    } catch {}
+  }
+  return null;
+}
+
+const rgPath = await findPathRg();
+
+test("real rg emits anchored matches from a temporary directory", {
+  skip: rgPath === null,
+}, async () => {
+  const directory = await mkdtemp(join(tmpdir(), "hl-grep-integration-"));
+  try {
+    const file = join(directory, "fixture.ts");
+    await writeFile(file, "needle\nother\n");
+    const tool = makeGrepOverrideWithBackend(directory, {
+      findRg: async () => rgPath,
+      delegate: async () => {
+        throw new Error("integration test must not invoke the built-in grep delegate");
+      },
+    });
+
+    const result: any = await tool.execute("0", { pattern: "needle" }, undefined, undefined);
+    assert.match(result.content[0].text, /fixture\.ts · 1 match/);
+    assert.match(result.content[0].text, /1#[0-9A-Z]+│needle/);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});

package/src/pi/execute.test.ts

@@ -49,6 +49,36 @@ test("read execute: text outputs LINE#HASH│content", async () => {
 	});
 });
 
+test("read execute: a missing final newline is stated in the header", async () => {
+	await withDir(async (dir) => {
+		await writeFile(join(dir, "f.txt"), "line1\nline2");
+		const bare: any = await call(makeReadOverride(dir), { path: "f.txt" });
+		assert.match(bare.content[0].text, /f\.txt · 2 lines · no trailing newline/);
+
+		await writeFile(join(dir, "g.txt"), "line1\nline2\n");
+		const terminated: any = await call(makeReadOverride(dir), { path: "g.txt" });
+		assert.doesNotMatch(terminated.content[0].text, /no trailing newline/);
+	});
+});
+
+test("edit execute: a file without a final newline stays byte-exact", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		// The benchmark's literal-1-no-final-newline fixture: no terminator, plus a
+		// word-joiner the model cannot see. Only line 2 may change; the missing
+		// terminator must not turn into a new byte.
+		const text = "guard\nold value\u2060";
+		await writeFile(f, text);
+		await call(makeReadOverride(dir), { path: "f.txt" });
+		const r: any = await call(makeEditOverride(dir), {
+			path: "f.txt",
+			edits: [{ op: "replace", anchor: h(text, 2), body: ["new value\u2060"] }],
+		});
+		assert.equal(r.isError, undefined, "should not be an error");
+		assert.equal(await readFile(f, "utf-8"), "guard\nnew value\u2060");
+	});
+});
+
 test("edit execute: hashline round-trip (read → edit → file changed)", async () => {
 	await withDir(async (dir) => {
 		const f = join(dir, "f.txt");