pi-hashline-edit-pro 6.4.7 → 6.5.0

package/README.md

@@ -219,15 +219,13 @@ After a successful edit, the diff is capped at 50KB. A row over 50KB is shown as
 
 ### replace_match
 
-`replace_match` changes part of a line (or a range of lines) without retyping the rest. `replace_from` and `replace_to` are bare anchors marking the first and last line of the range; use the same anchor for a single line. `old_string` is the exact text to find inside that range, and `new_string` replaces every occurrence of it; every other character stays untouched. Send `old_string` as only the fragment that changes — never include text that `new_string` leaves unchanged — and use `replace` with the same anchors when the change covers whole lines or the whole range; if `old_string` is everything on the line except indentation and trailing punctuation, that is a whole-line change. That makes it the tool for a change the request quotes as a substring: a whole-line `replace` has to reproduce the rest of the line, so a slipped character becomes a wrong byte, while `replace_match` leaves everything the request did not name untouched. It is enabled by default; turn Replace match off in `/hashline-config` to remove the tool.
+`replace_match` changes part of a line — or the same fragment on several lines of a range — without retyping the rest. `replace_from` and `replace_to` are bare anchors from served `anchor│content` rows marking the first and last line of the range searched (the same anchor for a single line). `match` is the exact text to find inside that range, and `replacement` replaces every occurrence of it; every other character stays untouched. Both stay within one line: a single trailing line break is accepted as the line's own terminator and dropped, so the file keeps its separator, while a line break anywhere else is refused with `[E_BAD_SHAPE]` (a `match` that is only that trailing line break leaves nothing to find and is refused; in `replacement` it counts as `""` and deletes the matches). Send `match` as only the fragment that changes — never include text that `replacement` leaves unchanged — and use `replace` with the same anchors when the change covers whole lines; if `match` is an entire single-line range except indentation and trailing punctuation, that is a whole-line change. The anchors bound the search, so `match` only needs to be unique inside the selected range, not file-wide. That makes it the tool for a change the request quotes as a substring: a whole-line `replace` has to reproduce the rest of the lines, so a slipped character becomes a wrong byte, while `replace_match` leaves everything the request did not name untouched. It is enabled by default; turn Replace match off in `/hashline-config` to remove the tool.
 
 `remove_from` and `remove_to` are accepted as aliases for `replace_from` and `replace_to`.
 
-`old_string` is matched against the range's text (LF line breaks, no final terminator) and every non-overlapping occurrence is replaced, left to right. A missing match is refused with `[E_SUBSTRING_NOT_FOUND]` and the current `anchor│content` rows, so the retry needs no `read`. The two boundary anchors are verified against what was last shown; lines strictly inside the range are matched against the file as it currently stands on disk.
+`match` is matched against each selected line's text (LF line breaks) and every non-overlapping occurrence is replaced, left to right — since `match` stays within one line, so does each replacement. A missing match is refused with `[E_SUBSTRING_NOT_FOUND]` and the current `anchor│content` rows, so the retry needs no `read`. The two boundary anchors are verified against what was last shown; lines strictly inside the range are searched as they currently stand on disk.
 
-`replace_match` reports `[W_REPLACE_MATCH_WHOLE_RANGE]` when `old_string` is the entire selected range, and `[W_REPLACE_MATCH_RETYPE]` when `old_string` retypes a long run of text that `new_string` leaves unchanged. Both are refused in strict-input mode with `[E_BAD_SHAPE]`.
-
-In a same-message batch it joins the other calls on its file: the batch validates everything against the pre-batch state and commits once, with one undo. A missing `old_string` fails that call on its own and is left out of the batch; the rest of the batch still commits. The post-edit diff carries fresh anchors, and the edit is undoable with `undo_last_change`.
+In a same-message batch it joins the other calls on its file: the batch validates everything against the pre-batch state and commits once, with one undo. A missing `match` fails that call on its own and is left out of the batch; the rest of the batch still commits. The post-edit diff carries fresh anchors, and the edit is undoable with `undo_last_change`.
 
 ### insert
 
@@ -422,7 +420,7 @@ When `PI_HASHLINE_DIR` is unset or empty, non-Windows platforms honor `XDG_CONFI
 
 All eight tools return machine-readable metadata in `details` alongside the model-visible text.
 
-All eight tools also declare an `outputSchema` and return `structuredContent`, so codemode scripts receive anchors, line numbers, diffs, and errors as data instead of parsing the rendered text. For `read`, `text` is the raw file content of the served window and `lines` carries the anchored rows, so a script parses the file without anchor prefixes. The model still receives `content`. Every structured result is either `{ ok: true, kind, ... }` or `{ ok: false, kind: "error", error: { code, message } }`; a failed call is still a tool error (`isError: true`) and also carries `structuredContent`, so a script can branch on the code without matching the message.
+All eight tools also declare an `outputSchema` and return `structuredContent`, so codemode scripts receive anchors, line numbers, diffs, and errors as data instead of parsing the rendered text. In a codemode session `tools.read()` resolves to the file's text, like the built-in `read`; pass `anchors: true` to receive `{ text, lines, notices }`, where `text` is the raw file content of the served window and `lines` carries the anchored rows. The model still receives `content`. Every structured result is either `{ ok: true, kind, ... }` or `{ ok: false, kind: "error", error: { code, message } }`; a failed call is still a tool error (`isError: true`) and also carries `structuredContent`, so a script can branch on the code without matching the message.
 
 `read` returns `{ kind: "read", path, text, lines, totalLines, startLine, nextOffset, truncated, blockedByLongLine, hadUtf8DecodeErrors, notices }`, where `text` is the raw file content of the served window (no anchors, no footers) and each entry of `lines` is `{ line, text, anchor, rendered }` for a row that was served (`text` there is what was shown, so an oversized line appears as its marker while keeping its anchor). `notices` carries non-file notes such as the UTF-8 rewrite note and `[W_ANCHOR_RECLAIMED]`. An image read returns `{ type: "image", data, mimeType, note }`.
 
@@ -459,20 +457,18 @@ 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 `text` must be a string holding the exact text), content contains a NUL byte (`U+0000`), which would make the file binary, or a grep `glob` has invalid bracket or brace syntax. |
+| `[E_BAD_SHAPE]` | Request envelope or edit item has unknown, missing, or wrongly-typed fields (for example `text` must be a string holding the exact text), content contains a NUL byte (`U+0000`), which would make the file binary, a grep `glob` has invalid bracket or brace syntax, or a `replace_match` string spans lines: `match`/`replacement` contains a line break after the optional trailing one. |
 | `[W_BAD_SHAPE]` | Auto-corrected request slip reported as a warning (for example legacy 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). |
-| `[E_SUBSTRING_NOT_FOUND]` | `replace_match` did not find `old_string` in the selected range. The current `anchor│content` rows are returned, and when `old_string` looks like a retyped copy of the range the message names the first mismatching line and column; copy only the fragment that changes from the served row and retry, or use `replace` for a whole-line rewrite. |
+| `[E_SUBSTRING_NOT_FOUND]` | `replace_match` did not find `match` in the selected range. The current `anchor│content` rows are returned, and when `match` looks like a retyped copy of a single-line range the message names the first mismatching column; copy only the fragment that changes from the served row and retry, or use `replace` for a whole-line rewrite. |
 | `[W_BAD_REF]` | A pasted `anchor│` or diff-preview marker was stripped from an anchor field with a warning. |
 | `[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 `text` line is a diff-preview row (`+anchor│`, `-anchor│`, `-    │`). The marker is stripped automatically with a warning. |
 | `[W_BARE_HASH_PREFIX]` | A `text` line starts with an `anchor│` prefix. The prefix is stripped automatically with a warning. |
-| `[W_REPLACE_MATCH_WHOLE_RANGE]` | `replace_match` `old_string` is the entire selected range. The anchors already identify it; use `replace` with the same anchors, or send only the changed fragment. Refused in strict-input mode. |
-| `[W_REPLACE_MATCH_RETYPE]` | `replace_match` `old_string` retypes a long run of text that `new_string` leaves unchanged. Send only the fragment that changes; refused in strict-input mode. |
 | `[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. |
-| `[H_LITERAL_ESCAPE]` | A payload field contains literal escaped text such as `\uXXXX`, `\n`, `\t`, `\r`, or `\"` (one hint per distinct escape, up to three). The file receives those backslash characters as written, because escapes in the tool call are decoded once when the call is parsed (`\uXXXX` → the character), so a doubled escape (`\\uXXXX`) lands literally. The hint is one line: `text: "\u200b" written as literal text (Kq3f│ col 31); resend with U+200B if unintended.` names the field, the escape, and up to three affected anchors with their columns, then the fix; when more than three rows carry it, it gives `on 10 rows; undo_last_change + resend with U+200B if unintended.` instead of the anchor list. |
-| `[H_UNICODE_LOST]` | The new text is missing an invisible or look-alike character (for example `U+200B`, `U+2060`, `U+00A0`, or a smart quote) that a replaced row has, or that a context row sharing a long run with an inserted line has. The edit applied as sent; the one-line hint names the character, its column, and the reference anchor, for example `[H_UNICODE_LOST] U+2060 missing at col 31; Kq3f│ has it; resend with U+2060 if unintended.` When another look-alike character (including `U+FFFD`) takes its place, the hint reports the substitute with `[H_UNICODE_SWAPPED]` wording. |
-| `[H_UNICODE_SWAPPED]` | The new text uses a different invisible or look-alike character than the line it matches (for example `U+200D` where that line has `U+200B`, or an ASCII stand-in such as `.` for `。` or a space for `U+00A0`). The edit applied as sent; the one-line hint names both code points, the column, and the reference anchor, for example `[H_UNICODE_SWAPPED] U+200D at col 21 where Kq3f│ has U+200B; resend with U+200B if unintended.` The substitute may also be `U+FFFD`, for example where a row has `U+00A0`. |
+| `[H_LITERAL_ESCAPE]` | A payload field contains literal escaped text such as `\uXXXX`, `\n`, `\t`, `\r`, or `\"` (one hint per distinct escape, up to three). The file receives those backslash characters as written, because escapes in the tool call are decoded once when the call is parsed (`\uXXXX` → the character), so a doubled escape (`\\uXXXX`) lands literally. The hint is one line: `text: "\u200b" written as literal text (Kq3f│ col 31).` names the field, the escape, and up to three affected anchors with their columns; when more than three rows carry it, it gives `on 10 rows; undo_last_change if unintended.` instead of the anchor list. |
+| `[H_UNICODE_LOST]` | The new text is missing an invisible or look-alike character (for example `U+200B`, `U+2060`, `U+00A0`, or a smart quote) that a replaced row has, or that a context row sharing a long run with an inserted line has. The edit applied as sent; the one-line hint names the live anchor of the offending result row, when one can be identified, and the character as its JSON escape, for example `[H_UNICODE_LOST] Zbbb│ missing "\u2060"; Kq3f│ has it at col 31.` The column is attributed to the row that had the character: `; Kq3f│ has it at col N` while that row's anchor is still valid, otherwise `; the replaced row had it at col N`, and a dead anchor is never named. When another look-alike character (including `U+FFFD`) takes its place, the hint reports the substitute with `[H_UNICODE_SWAPPED]` wording. |
+| `[H_UNICODE_SWAPPED]` | The new text uses a different invisible or look-alike character than the line it matches (for example `U+200D` where that line has `U+200B`, or an ASCII stand-in such as `.` for `。` or a space for `U+00A0`). The edit applied as sent; the one-line hint names the live anchor of the offending result row with both characters as JSON escapes, for example `[H_UNICODE_SWAPPED] Zbbb│ has "\u200d" at col 21; expected "\u200b".` A surviving reference row appears as `; Kq3f│ has "\u200b"`; a replaced row's dead anchor is never named. The substitute may also be `U+FFFD`, for example where a row has `U+00A0`. |
 | `[H_TRAILING_WHITESPACE]` | The new text differs from the replaced line only in trailing whitespace. Anchor checksums trim trailing whitespace, so the change does not invalidate the anchor; the one-line hint names the old and new trailing-whitespace counts and the column, for example `[H_TRAILING_WHITESPACE] 1 trailing whitespace character at col 7; Kq3f│ had 0.` |
 | `[H_INDENT_MISMATCH]` | The new line has fewer leading whitespace characters than a structurally similar row (a reference row near the anchor line for an insert, or the replaced line). The edit applied as sent; the one-line hint names both counts and the reference anchor, for example `[H_INDENT_MISMATCH] new line has 0 leading whitespace characters; Kq3f│ has 2.` Copied or moved blocks are not checked, because their indentation comes from the source lines. |
 | `[H_SEPARATOR_MOVED]` | An insert landed its text directly against the anchor line, and the blank line that separated the anchor from its neighbor was displaced to the other side of the inserted text. The edit applied as sent; the one-line hint names the anchor and which side lost the blank line, for example `[H_SEPARATOR_MOVED] blank separator above Kq3f│ was displaced; add a blank line before Kq3f│ if unintended.` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "6.4.7",
+  "version": "6.5.0",
   "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",
@@ -61,15 +61,15 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^1.2.0",
+    "@earendil-works/pi-coding-agent": "^1.3.0",
     "@eslint/js": "^10.0.1",
-    "@types/node": "^24",
-    "@vitest/coverage-v8": "^4.1.11",
-    "eslint": "^10.9.1",
-    "typebox": "^1.3.7",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.68.0",
-    "vitest": "^4.1.11"
+    "@types/node": "^24.19.2",
+    "@vitest/coverage-v8": "^5.0.5",
+    "eslint": "^10.13.0",
+    "typebox": "^1.4.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.2",
+    "vitest": "^5.0.5"
   },
   "allowScripts": {
     "@google/genai@1.52.0": true,

package/src/anchor-registry.ts

@@ -6,8 +6,8 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { sessionClaimsDir } from "./paths";
 import { contentChecksum } from "./hashline/hasher";
 import { ANCHOR_COUNT, anchorAt } from "./hashline/alphabet";
-import { HASH_PROBE_STRIDE } from "./hashline/hash";
-import { errCode, isRec, splitLines } from "./utils";
+import { HASH_PROBE_STRIDE, MAX_HASH_LINES } from "./hashline/hash";
+import { assertLineCount, errCode, isRec, splitLines, spliceAll } from "./utils";
 import * as Diff from "diff";
 import { lineChecksum } from "./hashline";
 import { getAllocatedState, persistSnapshot, type HashStore } from "./hash-store";
@@ -46,6 +46,7 @@ interface OwnedAnchorMap {
 }
 
 interface AnchorMintedSet {
+  readonly size: number;
   has(anchor: string): boolean;
   add(anchor: string): unknown;
   [Symbol.iterator](): IterableIterator<string>;
@@ -125,9 +126,12 @@ class ShadowOwnedMap implements OwnedAnchorMap {
 class ShadowMintedSet implements AnchorMintedSet {
   private readonly parent: AnchorMintedSet;
   private readonly added = new Set<string>();
+  private extra = 0;
+  private parentSize: number;
 
   constructor(parent: AnchorMintedSet) {
     this.parent = parent;
+    this.parentSize = parent.size;
   }
 
   has(anchor: string): boolean {
@@ -135,10 +139,22 @@ class ShadowMintedSet implements AnchorMintedSet {
   }
 
   add(anchor: string): this {
+    if (!this.added.has(anchor) && !this.parent.has(anchor)) this.extra += 1;
     this.added.add(anchor);
     return this;
   }
 
+  get size(): number {
+    if (this.parent.size !== this.parentSize) {
+      this.parentSize = this.parent.size;
+      this.extra = 0;
+      for (const anchor of this.added) {
+        if (!this.parent.has(anchor)) this.extra += 1;
+      }
+    }
+    return this.parentSize + this.extra;
+  }
+
   *[Symbol.iterator](): IterableIterator<string> {
     yield* this.parent;
     for (const anchor of this.added) {
@@ -555,16 +571,19 @@ export function reclaimAnchorSpace(state: SessionState, protectPath?: string): s
 
 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;
+    if (state.everMinted.size < ANCHOR_COUNT) {
+      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)) {
+        state.probe = (state.probe + step) % ANCHOR_COUNT;
         for (const served of state.served.values()) served.delete(candidate);
         return candidate;
       }
@@ -861,7 +880,7 @@ export function alignOwnershipWithSpans(
       state.everMinted.add(settled[k]!);
       state.owned.set(settled[k]!, { path, checksum: newChecksums[start + k]! });
     }
-    anchors.splice(start, spanLength, ...settled);
+    spliceAll(anchors, start, spanLength, settled);
     offset += span.replacementCount - spanLength;
   }
   const rows: [string, string][] = minted.map((m) => [m.anchor, m.checksum]);
@@ -963,8 +982,9 @@ export async function allocateFileAnchors(
   ensureRegistry();
   const registry = current();
   const shadow = options?.shadow === true;
-  if (!shadow && registry) touchPath(registry, path);
   const lines = splitLines(content);
+  assertLineCount(lines.length, path, MAX_HASH_LINES);
+  if (!shadow && registry) touchPath(registry, path);
   const checksums = lines.map(lineChecksum);
   if (options?.previous?.spans) {
     const prevChecksums = splitLines(options.previous.content).map(lineChecksum);
@@ -1058,6 +1078,10 @@ export function resetRegistryForTests(): void {
   registries.clear();
 }
 
+export function lastUsedAtForTests(path: string): number | undefined {
+  return current()?.lastUsedAt.get(path);
+}
+
 async function readSidecarWindow(sidecar: string): Promise<{ text: string; filled: boolean }> {
   const handle = await open(sidecar, "r");
   const buffer = Buffer.alloc(SIDECAR_HEADER_BYTES);

package/src/batch.ts

@@ -28,7 +28,7 @@ import { saveUndo } from "./replace-undo";
 import { buildChanged, buildNoop, type RMetrics, type TResult } from "./replace-response";
 import { toEditVerb, withStructuredText, type EditStructured } from "./structured";
 import { serveRows, servedHashesFromDiff } from "./served";
-import { abortIf, assertByteLimit, assertLineLimit, errCode, isRec, mapIoError, splitLines } from "./utils";
+import { abortIf, assertByteLimit, assertLineLimit, errCode, isRec, mapIoError, splitLines, spliceAll } from "./utils";
 
 export interface PlannedMember {
   batchKey: number;
@@ -793,7 +793,7 @@ function composeBatchLines(baseContent: string, pieces: BatchPiece[]): string {
   const lines = splitLines(baseContent);
   const baseLineCount = lines.length;
   const descending = [...pieces].sort((a, b) => b.start - a.start);
-  for (const piece of descending) lines.splice(piece.start - 1, piece.end - piece.start + 1, ...piece.newLines);
+  for (const piece of descending) spliceAll(lines, piece.start - 1, piece.end - piece.start + 1, piece.newLines);
   let composed = lines.join("\n");
   if (lines.length > 0 && (baseContent.endsWith("\n") || lines[lines.length - 1] === "")) {
     composed += "\n";

package/src/copy-move.ts

@@ -23,7 +23,7 @@ import { formatAnchorReclaimNotice, servedForPath, takeReclaimedPaths, withAncho
 import { batchMemberFor, batchServedFor, ensureBatchBase, executeBatchMember, noteBatchFailure, pendingBatchMemberFor, registerBatchPlanner, type BatchBase, type BatchMemberPlanner, type PlannedMember } from "./batch";
 import { loadP, loadGuidelines } from "./prompts";
 import { assertTransferReq, normReq, type TransferReq } from "./payload-contract";
-import { abortIf, assertByteLimit, isRec, splitLines } from "./utils";
+import { abortIf, anchorCarryIndex, assertByteLimit, isRec, splitLines } from "./utils";
 import { toDisplayPath } from "./paths";
 import { getDiffContextLines } from "./config";
 import { resolveInCwd, writeAtomic } from "./fs-write";
@@ -145,7 +145,7 @@ export function buildTransferEdit(input: {
           : [...sourceLines, fileLines[anchorLine - 1]!],
       },
       foldedAnchorLines: 1,
-      anchorCarry: refs.direction === "after" ? 0 : sourceLines.length,
+      anchorCarry: anchorCarryIndex(refs.direction, sourceLines.length),
       endingOverrides: refs.direction === "after"
         ? [undefined, ...sourceEndings]
         : [...sourceEndings, undefined],
@@ -319,14 +319,14 @@ async function prepareCrossTransfer(input: {
       ? offsetEndings(1, sourceEndings)
       : sourceEndings;
   if (kind === "copy") {
-    return { sourcePreload, destinationPreload, sourceDisplay, destinationDisplay, destinationEdit, destinationFolded, ...(destinationFolded === 1 ? { anchorCarry: refs.direction === "after" ? 0 : moved.length } : {}), endingOverrides };
+    return { sourcePreload, destinationPreload, sourceDisplay, destinationDisplay, destinationEdit, destinationFolded, ...(destinationFolded === 1 ? { anchorCarry: anchorCarryIndex(refs.direction, moved.length) } : {}), endingOverrides };
   }
   const sourceEdit: HTEdit = {
     remove_from: sourcePreload.fileHashes[sourceStart - 1]!,
     remove_to: sourcePreload.fileHashes[sourceEnd - 1]!,
     text: [],
   };
-  return { sourcePreload, destinationPreload, sourceDisplay, destinationDisplay, destinationEdit, destinationFolded, ...(destinationFolded === 1 ? { anchorCarry: refs.direction === "after" ? 0 : moved.length } : {}), sourceEdit, endingOverrides };
+  return { sourcePreload, destinationPreload, sourceDisplay, destinationDisplay, destinationEdit, destinationFolded, ...(destinationFolded === 1 ? { anchorCarry: anchorCarryIndex(refs.direction, moved.length) } : {}), sourceEdit, endingOverrides };
 }
 
 function pairEntry(pipe: PipelineResult, separators: LineEnding[] | undefined): UndoEntry {
@@ -584,6 +584,7 @@ async function executeCrossFile(
       signal,
       preloadedNorm: prepared.destinationPreload,
       endingOverrides: prepared.endingOverrides,
+      ...(prepared.anchorCarry !== undefined ? { anchorCarry: prepared.anchorCarry } : {}),
     });
     if (kind === "copy") {
       return commitEdit(destinationPipe, {
@@ -827,6 +828,7 @@ export async function transferPreview(kind: TransferKind, request: unknown, cwd:
         served: plan.servedOverride,
         endingOverrides: plan.endingOverrides,
         signal,
+        ...(plan.anchorCarry !== undefined ? { anchorCarry: plan.anchorCarry } : {}),
       });
       return previewFromPipe(pipe);
     }
@@ -837,6 +839,7 @@ export async function transferPreview(kind: TransferKind, request: unknown, cwd:
       preloadedNorm: prepared.destinationPreload,
       endingOverrides: prepared.endingOverrides,
       signal,
+      ...(prepared.anchorCarry !== undefined ? { anchorCarry: prepared.anchorCarry } : {}),
     });
     if (kind === "copy") return previewFromPipe(destinationPipe);
     const sourcePipe = await execPipeline(sourcePath, prepared.sourceEdit!, cwd, {
@@ -1017,6 +1020,7 @@ export function buildTransferToolDef(kind: TransferKind, flags: EditToolFlags =
               preloadedNorm: preload,
               served: plan.servedOverride,
               endingOverrides: plan.endingOverrides,
+              ...(plan.anchorCarry !== undefined ? { anchorCarry: plan.anchorCarry } : {}),
             });
             return commitEdit(pipe, {
               path: pipe.path,

package/src/edit-common.ts

@@ -53,10 +53,14 @@ function preferenceGuideline(flags: EditToolFlags): string {
 const SHARED_EDIT_OPS = ["replace", "replace_match", "insert", "copy", "move"];
 const SHARED_PAYLOAD_OPS = ["replace", "replace_match", "insert"];
 const SHARED_DIFF_OPS = ["replace", "replace_match", "insert", "copy", "move", "undo_last_change"];
-const RESULT_CONTRACT_GUIDELINE =
-  'When called from a codemode script, failures resolve to `{ ok: false, kind: "error", error: { code, message } }`; branch on `ok` instead of `try`/`catch`.';
+const SHARED_SCRIPT_OPS = ["read", "replace", "replace_match", "insert", "copy", "move", "grep", "undo_last_change"];
+
+function resultContractGuideline(flags: EditToolFlags): string {
+  const tools = operationNames(SHARED_SCRIPT_OPS, flags);
+  return `${tools}: when called from a codemode script, failures resolve to \`{ ok: false, kind: "error", error: { code, message } }\`; branch on \`ok\` instead of \`try\`/\`catch\`.`;
+}
 const READ_SCRIPT_GUIDELINE =
-  '`read`: a codemode script receives `{ text, lines, notices }`; `text` is the raw file content of the served window and `lines[].anchor` is the editable anchor. An image read resolves to an image block.';
+  '`read` in a codemode script resolves to the file\'s text, like the built-in `read`; pass `anchors: true` to receive `{ text, lines, notices }` with the raw file content and `lines[].anchor` for chained edits. An image read resolves to an image block.';
 const GREP_SCRIPT_GUIDELINE =
   '`grep`: a codemode script receives `{ text, results }`; each `results[].lines[]` entry carries the matching line\'s `anchor` and `text`, so a result is editable without a fresh read.';
 function editScriptGuideline(flags: EditToolFlags): string {
@@ -88,7 +92,7 @@ function batchGuideline(flags: EditToolFlags): string {
   const tools = operationNames(SHARED_EDIT_OPS, flags);
   const outcome = flags.autoRead ? "diff" : "result";
   const script = flags.codemode ? ` ${SCRIPT_BATCH_GUIDELINE}` : "";
-  return `${tools}: same-file calls in one message commit as one batch; earlier calls reply \`In batch N (queued)\`, the last shows the combined ${outcome}, and one undo reverts all. A request-invalid call (anchors, shape, or \`old_string\`) fails alone; a failure while the batch runs aborts it.${script}`;
+  return `${tools}: same-file calls in one message commit as one batch; earlier calls reply \`In batch N (queued)\`, the last shows the combined ${outcome}, and one undo reverts all. A request-invalid call (anchors, shape, or \`match\`) fails alone; a failure while the batch runs aborts it.${script}`;
 }
 
 function diffGuideline(flags: EditToolFlags): string {
@@ -137,7 +141,7 @@ function readGuidelineApplies(guideline: Guideline, flags: EditToolFlags): boole
 
 export function withReadPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
   const preference = preferenceGuideline(flags);
-  const script = flags.codemode ? [READ_SCRIPT_GUIDELINE, RESULT_CONTRACT_GUIDELINE] : [];
+  const script = flags.codemode ? [READ_SCRIPT_GUIDELINE, resultContractGuideline(flags)] : [];
   const applicable = base.guidelines.filter((guideline) => readGuidelineApplies(guideline, flags));
   if (flags.autoReadAllActive) {
     const rewritten = applicable.filter((guideline) => guideline.id !== READ_REREAD_ID).map((guideline) => guideline.text);
@@ -153,10 +157,8 @@ export function withInsertPrompts(base: { description: string; snippet: string;
   return { description: base.description, snippet: base.snippet, guidelines: base.guidelines.map((guideline) => guideline.text) };
 }
 
-export function withReplaceMatchPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
-  const guidelines = base.guidelines.map((guideline) => guideline.text);
-  if (flags.strictInput) guidelines.push("`replace_match`: strict-input mode rejects an `old_string` that covers the whole range or retypes unchanged text.");
-  return { description: base.description, snippet: base.snippet, guidelines };
+export function withReplaceMatchPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, _flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
+  return { description: base.description, snippet: base.snippet, guidelines: base.guidelines.map((guideline) => guideline.text) };
 }
 
 function gatedEditOps(ops: string[], flags: EditToolFlags): string[] {
@@ -295,7 +297,7 @@ export async function resolveEditTargetWithRequirement(input: PathRequirementInp
   return anchorTarget;
 }
 
-const STRICT_INPUT_REJECT_CODES = ["[W_BAD_SHAPE]", "[W_BAD_REF]", "[W_INVALID_PATCH]", "[W_BARE_HASH_PREFIX]", "[W_REPLACE_MATCH_WHOLE_RANGE]", "[W_REPLACE_MATCH_RETYPE]"];
+const STRICT_INPUT_REJECT_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) => STRICT_INPUT_REJECT_CODES.some((code) => warning.startsWith(code)));
   if (fixes.length === 0) return;

package/src/edit-fidelity.ts

@@ -76,8 +76,12 @@ export function isFidelitySensitiveChar(char: string): boolean {
   return char === REPLACEMENT_CHAR || INVISIBLE_RE.test(char) || LOOKALIKE_SPACE_RE.test(char) || LOOKALIKE_DASH_RE.test(char) || LOOKALIKE_QUOTE_RE.test(char) || LOOKALIKE_PUNCT_RE.test(char);
 }
 
-function formatCodePoint(char: string): string {
-  return `U+${char.codePointAt(0)!.toString(16).toUpperCase().padStart(4, "0")}`;
+export function formatCharEscape(char: string): string {
+  const codePoint = char.codePointAt(0);
+  if (codePoint === undefined) return "";
+  if (codePoint <= 0xffff) return `\\u${codePoint.toString(16).padStart(4, "0")}`;
+  const pair = codePoint - 0x10000;
+  return `\\u${(0xd800 + (pair >> 10)).toString(16).padStart(4, "0")}\\u${(0xdc00 + (pair & 0x3ff)).toString(16).padStart(4, "0")}`;
 }
 
 function plural(count: number, noun: string): string {
@@ -89,11 +93,16 @@ interface ReferenceRow {
   index: number;
 }
 
-function hiddenCharHint(char: string, reference: ReferenceRow, anchor: string | undefined): string {
+function hiddenCharHint(char: string, reference: ReferenceRow, liveAnchor: string | undefined, referenceAnchor: string | undefined): string {
   const column = [...reference.line].indexOf(char) + 1;
-  const codePoint = formatCodePoint(char);
-  const referenceNote = anchor === undefined ? "" : `; ${anchor}${HASH_SEP} has it`;
-  return `[H_UNICODE_LOST] ${codePoint} missing at col ${column}${referenceNote}; resend with ${codePoint} if unintended.`;
+  const escape = formatCharEscape(char);
+  const located = referenceAnchor === undefined
+    ? `the replaced row had it at col ${column}`
+    : `${referenceAnchor}${HASH_SEP} has it at col ${column}`;
+  if (liveAnchor === undefined) {
+    return `[H_UNICODE_LOST] "${escape}" missing; ${located}.`;
+  }
+  return `[H_UNICODE_LOST] ${liveAnchor}${HASH_SEP} missing "${escape}"; ${located}.`;
 }
 
 function withCharsRestored(line: string, chars: readonly string[], replacementFor: (char: string) => string): string {
@@ -122,6 +131,7 @@ interface SwappedChar {
 interface SwapCandidate {
   reference: ReferenceRow;
   swapped: SwappedChar;
+  liveAnchor?: string;
 }
 
 function containsSensitiveChar(line: string): boolean {
@@ -134,6 +144,14 @@ function normalizeSensitiveChars(line: string): string {
   return normalized;
 }
 
+function sensitiveStripped(line: string): string {
+  let visible = "";
+  for (const char of line) {
+    if (!isFidelitySensitiveChar(char)) visible += char;
+  }
+  return visible;
+}
+
 function isLookalikeSwap(oldChar: string, newChar: string): boolean {
   if (isFidelitySensitiveChar(oldChar) && isFidelitySensitiveChar(newChar)) return true;
   return LOOKALIKE_SUBSTITUTES[newChar] === oldChar;
@@ -150,21 +168,46 @@ function sharesFidelityClass(left: string, right: string): boolean {
   );
 }
 
-function findSubstitute(char: string, reference: ReferenceRow, payload: readonly string[]): string | undefined {
+interface SubstituteMatch {
+  value: string;
+  payloadIndex: number;
+  column: number;
+}
+
+interface SubstituteRank {
+  echo: boolean;
+  aligned: boolean;
+  distance: number;
+}
+
+function preferSubstitute(candidate: SubstituteRank, best: SubstituteRank | undefined): boolean {
+  if (best === undefined) return true;
+  if (candidate.echo !== best.echo) return candidate.echo;
+  if (candidate.aligned !== best.aligned) return candidate.aligned;
+  return candidate.distance < best.distance;
+}
+
+function findSubstitute(char: string, reference: ReferenceRow, payload: readonly string[]): SubstituteMatch | undefined {
   const referenceChars = [...reference.line];
   const column = referenceChars.indexOf(char);
-  for (const line of payload) {
+  const visibleReference = sensitiveStripped(reference.line);
+  let best: SubstituteMatch | undefined;
+  let bestRank: SubstituteRank | undefined;
+  for (let index = 0; index < payload.length; index += 1) {
+    const line = payload[index]!;
     const candidateChars = [...line];
-    if (candidateChars.length !== referenceChars.length) continue;
-    const candidate = candidateChars[column];
-    if (candidate !== undefined && candidate !== char && sharesFidelityClass(char, candidate)) return candidate;
-  }
-  for (const line of payload) {
-    for (const candidate of line) {
-      if (candidate !== char && sharesFidelityClass(char, candidate)) return candidate;
+    const echo = sensitiveStripped(line) === visibleReference;
+    const sameLength = candidateChars.length === referenceChars.length;
+    for (let at = 0; at < candidateChars.length; at += 1) {
+      const candidate = candidateChars[at]!;
+      if (candidate === char || !sharesFidelityClass(char, candidate)) continue;
+      const rank = { echo, aligned: sameLength && at === column, distance: Math.abs(at - column) };
+      if (!preferSubstitute(rank, bestRank)) continue;
+      bestRank = rank;
+      best = { value: candidate, payloadIndex: index, column: at + 1 };
     }
   }
-  return undefined;
+  return best;
 }
 
 function swappedCharPair(oldLine: string, newLine: string): SwappedChar | undefined {
@@ -193,10 +236,15 @@ function swappedCandidate(line: string, matches: IndexedLine[], spanStart: numbe
   return candidates.find((candidate) => candidate.reference.index >= spanStart && candidate.reference.index <= spanEnd) ?? candidates[0];
 }
 
-function swappedCharHint(swapped: SwappedChar, anchor: string | undefined): string {
-  const label = anchor === undefined ? "the replaced line" : `${anchor}${HASH_SEP}`;
-  const expected = formatCodePoint(swapped.oldChar);
-  return `[H_UNICODE_SWAPPED] ${formatCodePoint(swapped.newChar)} at col ${swapped.column} where ${label} has ${expected}; resend with ${expected} if unintended.`;
+function swappedCharHint(swapped: SwappedChar, liveAnchor: string | undefined, referenceAnchor: string | undefined): string {
+  const newEscape = formatCharEscape(swapped.newChar);
+  const oldEscape = formatCharEscape(swapped.oldChar);
+  if (liveAnchor === undefined) {
+    const label = referenceAnchor === undefined ? "the replaced line" : `${referenceAnchor}${HASH_SEP}`;
+    return `[H_UNICODE_SWAPPED] "${newEscape}" at col ${swapped.column} where ${label} has "${oldEscape}".`;
+  }
+  const referenceNote = referenceAnchor === undefined ? `; expected "${oldEscape}"` : `; ${referenceAnchor}${HASH_SEP} has "${oldEscape}"`;
+  return `[H_UNICODE_SWAPPED] ${liveAnchor}${HASH_SEP} has "${newEscape}" at col ${swapped.column}${referenceNote}.`;
 }
 
 function trailingWhitespaceHint(oldLine: string, newLine: string, anchor: string | undefined): string {
@@ -327,18 +375,6 @@ function literalEscapeHintRows(
   return rows;
 }
 
-function actualEscapeName(escape: string): string {
-  const hex = /^\\u([0-9a-fA-F]{4})$/.exec(escape)?.[1];
-  if (hex !== undefined) return `U+${hex.toUpperCase()}`;
-  if (escape.length === 2) {
-    if (escape[1] === "n") return "a line break";
-    if (escape[1] === "r") return "a carriage return";
-    if (escape[1] === "t") return "a tab";
-    if (escape[1] === '"') return "a double quote";
-  }
-  return "the character";
-}
-
 export function annotateLiteralEscapeHints(
   hints: string[],
   resultContent: string,
@@ -353,10 +389,10 @@ export function annotateLiteralEscapeHints(
     const rows = literalEscapeHintRows(resultContent, spans, resultHashes, escape);
     if (rows.length === 0) return hint;
     if (rows.length > MAX_LITERAL_ESCAPE_ROWS) {
-      return `${hint} on ${plural(rows.length, "row")}; undo_last_change + resend with ${actualEscapeName(escape)} if unintended.`;
+      return `${hint} on ${plural(rows.length, "row")}; undo_last_change if unintended.`;
     }
     const locations = rows.map((row) => `${resultHashes[row.index]!}${HASH_SEP} col ${literalEscapeColumn(row.line, escape)}`).join(", ");
-    return `${hint} (${locations}); resend with ${actualEscapeName(escape)} if unintended.`;
+    return `${hint} (${locations}).`;
   });
 }
 
@@ -404,6 +440,8 @@ export function fidelityHints(
     return sensitiveIndex;
   };
   let offset = 0;
+  const removedByAnySpan = (index: number): boolean =>
+    spans.some((candidate) => index >= candidate.start && index <= candidate.end);
   for (const span of [...spans].sort((a, b) => a.start - b.start)) {
     const removedCount = span.end >= span.start ? span.end - span.start + 1 : 0;
     const removed = removedCount > 0 ? oldLines.slice(span.start, span.end + 1) : [];
@@ -416,10 +454,31 @@ export function fidelityHints(
         ? removed.map((line, index) => ({ line, index: span.start + index }))
         : referenceRows(oldLines, span.start, span.end);
       const insertGate = carried === undefined ? null : (gramSet(payload, SIMILARITY_RUN, true) ?? new Set<string>());
+      const resultIndexForPayload = (payloadIndex: number): number =>
+        span.start + offset + (carried !== undefined && payloadIndex >= carried ? payloadIndex + 1 : payloadIndex);
+      const referenceSurvives = (reference: ReferenceRow): boolean =>
+        (carried !== undefined && reference.index === span.start && inserted[carried] === oldLines[reference.index]) ||
+        !removedByAnySpan(reference.index);
+      const liveAnchorForPayload = (payloadIndex: number): string | undefined =>
+        resultHashes?.[resultIndexForPayload(payloadIndex)];
+      const payloadIndexSharingRun = (line: string): number => {
+        const grams = gramSet([sensitiveStripped(line)], SIMILARITY_RUN);
+        return grams === undefined ? -1 : payload.findIndex((candidate) => sharesRun(sensitiveStripped(candidate), grams, SIMILARITY_RUN));
+      };
+      const liveAnchorForReference = (reference: ReferenceRow): string | undefined => {
+        const shared = payloadIndexSharingRun(reference.line);
+        if (shared >= 0) return liveAnchorForPayload(shared);
+        if (carried !== undefined || removed.length !== payload.length) return undefined;
+        const payloadIndex = reference.index - span.start;
+        return payloadIndex >= 0 && payloadIndex < payload.length ? liveAnchorForPayload(payloadIndex) : undefined;
+      };
+      const referenceAnchorFor = (reference: ReferenceRow): string | undefined =>
+        referenceSurvives(reference) ? originalHashes?.[reference.index] : undefined;
       const swapKeys = new Set<string>();
       const swaps: SwapCandidate[] = [];
       let candidates: Map<string, IndexedLine[]> | undefined;
-      for (const line of payload) {
+      for (let payloadIndex = 0; payloadIndex < payload.length; payloadIndex += 1) {
+        const line = payload[payloadIndex]!;
         if (!containsSensitiveChar(line)) continue;
         candidates ??= sensitiveLines();
         const matches = [...(candidates.get(normalizeSensitiveChars(line)) ?? []), ...references];
@@ -428,7 +487,7 @@ export function fidelityHints(
         const key = `${candidate.reference.index}:${candidate.swapped.oldChar}`;
         if (swapKeys.has(key)) continue;
         swapKeys.add(key);
-        swaps.push(candidate);
+        swaps.push({ ...candidate, liveAnchor: liveAnchorForPayload(payloadIndex) });
       }
       const missing = new Map<string, ReferenceRow>();
       for (const reference of references) {
@@ -449,17 +508,17 @@ export function fidelityHints(
         const substitute = findSubstitute(char, reference, payload);
         if (substitute !== undefined) {
           seen.add(`swap:${reference.index}:${char}`);
-          hints.push(swappedCharHint({ oldChar: char, newChar: substitute, column: [...reference.line].indexOf(char) + 1 }, originalHashes?.[reference.index]));
+          hints.push(swappedCharHint({ oldChar: char, newChar: substitute.value, column: substitute.column }, liveAnchorForPayload(substitute.payloadIndex), referenceAnchorFor(reference)));
           continue;
         }
-        hints.push(hiddenCharHint(char, reference, originalHashes?.[reference.index]));
+        hints.push(hiddenCharHint(char, reference, liveAnchorForReference(reference), referenceAnchorFor(reference)));
       }
       for (const candidate of swaps) {
         if (hints.length >= MAX_FIDELITY_HINTS) break;
         const key = `swap:${candidate.reference.index}:${candidate.swapped.oldChar}`;
         if (seen.has(key)) continue;
         seen.add(key);
-        hints.push(swappedCharHint(candidate.swapped, originalHashes?.[candidate.reference.index]));
+        hints.push(swappedCharHint(candidate.swapped, candidate.liveAnchor, referenceAnchorFor(candidate.reference)));
       }
       const indentReferenceFor = (payloadIndex: number): ReferenceRow | undefined => {
         if (options?.indentHints === false) return undefined;
@@ -482,8 +541,6 @@ export function fidelityHints(
         }
         return undefined;
       };
-      const resultIndexForPayload = (payloadIndex: number): number =>
-        span.start + offset + (carried !== undefined && payloadIndex >= carried ? payloadIndex + 1 : payloadIndex);
       for (let index = 0; index < payload.length; index += 1) {
         if (hints.length >= MAX_FIDELITY_HINTS) break;
         const payloadLine = payload[index]!;