pi-hashline-edit-pro 6.4.8 → 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
 
@@ -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.8",
+  "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",

package/src/edit-common.ts

@@ -92,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 {
@@ -157,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[] {
@@ -299,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]!;

package/src/payload-contract.ts

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
 import { isRec, normalizeRequest, rejectUnknownFields, assertNoNul } from "./utils";
 import { TEXT_ENDING_NOTE, TEXT_NOT_STRING_MSG, NEW_CONTENT_NOT_STRING_MSG } from "./constants";
+import { toLF } from "./normalize";
 
 const textSchema = Type.String({
   description:
@@ -166,25 +167,44 @@ export function assertTransferReq(request: unknown): asserts request is Transfer
   }
 }
 
-const MATCH_KS = new Set(["path", "replace_from", "replace_to", "old_string", "new_string"]);
+const MATCH_KS = new Set(["path", "replace_from", "replace_to", "match", "replacement"]);
 
 export interface ReplaceMatchReq {
   path?: string;
   replace_from: string;
   replace_to: string;
-  old_string: string;
-  new_string: string;
+  match: string;
+  replacement: string;
+}
+
+export function singleLineFragment(field: "match" | "replacement", raw: string): string {
+  const text = toLF(raw);
+  const fragment = text.endsWith("\n") ? text.slice(0, -1) : text;
+  const lineBreak = fragment.indexOf("\n");
+  if (lineBreak >= 0) {
+    const column = [...fragment.slice(0, lineBreak)].length + 1;
+    throw new Error(
+      `[E_BAD_SHAPE] ${field} must stay within one line, but the value contains a line break at column ${column}. A trailing line break is accepted as the line's own terminator; text on another line belongs to replace.`,
+    );
+  }
+  if (field === "match" && fragment.length === 0) {
+    throw new Error('[E_BAD_SHAPE] Replace-match request field "match" must be a non-empty string holding the exact text to find.');
+  }
+  return fragment;
 }
 
 export function assertReplaceMatchReq(request: unknown): asserts request is ReplaceMatchReq {
   if (!isRec(request)) {
     throw new Error("[E_BAD_SHAPE] Replace-match request must be an object.");
   }
+  if ("old_string" in request || "new_string" in request) {
+    throw new Error('[E_BAD_SHAPE] Replace-match request no longer accepts "old_string"/"new_string"; use "match" for the text to find and "replacement" for the new text.');
+  }
   rejectUnknownFields(request, MATCH_KS, "Replace-match request");
   if (request.path !== undefined && typeof request.path !== "string") {
     throw new Error('[E_BAD_SHAPE] Replace-match request field "path" must be a string when provided.');
   }
-  for (const key of ["replace_from", "replace_to", "old_string", "new_string"] as const) {
+  for (const key of ["replace_from", "replace_to", "match", "replacement"] as const) {
     if (typeof (request as Record<string, unknown>)[key] !== "string") {
       throw new Error(`[E_BAD_SHAPE] Replace-match request requires a "${key}" string.`);
     }
@@ -193,13 +213,12 @@ export function assertReplaceMatchReq(request: unknown): asserts request is Repl
   if (within.replace_from.length === 0 || within.replace_to.length === 0) {
     throw new Error('[E_BAD_SHAPE] Replace-match request requires non-empty "replace_from" and "replace_to" anchors.');
   }
-  if (within.old_string.length === 0) {
-    throw new Error('[E_BAD_SHAPE] Replace-match request field "old_string" must be a non-empty string holding the exact text to find.');
-  }
-  assertNoNul([within.new_string]);
+  singleLineFragment("match", within.match);
+  singleLineFragment("replacement", within.replacement);
+  assertNoNul([within.replacement]);
 }
 
-export function getReplaceMatchInput(args: unknown): { path?: string; replace_from: string; replace_to: string; old_string: string; new_string: string } | null {
+export function getReplaceMatchInput(args: unknown): { path?: string; replace_from: string; replace_to: string; match: string; replacement: string } | null {
   let normalized: unknown;
   try {
     normalized = normalizeRequest(args, "replace");
@@ -210,8 +229,8 @@ export function getReplaceMatchInput(args: unknown): { path?: string; replace_fr
   if (
     typeof normalized.replace_from !== "string" ||
     typeof normalized.replace_to !== "string" ||
-    typeof normalized.old_string !== "string" ||
-    typeof normalized.new_string !== "string"
+    typeof normalized.match !== "string" ||
+    typeof normalized.replacement !== "string"
   ) {
     return null;
   }
@@ -219,8 +238,8 @@ export function getReplaceMatchInput(args: unknown): { path?: string; replace_fr
     ...(typeof normalized.path === "string" ? { path: normalized.path } : {}),
     replace_from: normalized.replace_from,
     replace_to: normalized.replace_to,
-    old_string: normalized.old_string,
-    new_string: normalized.new_string,
+    match: normalized.match,
+    replacement: normalized.replacement,
   };
 }
 
@@ -230,15 +249,15 @@ const replaceMatchFromSchema = Type.String({
 });
 const replaceMatchToSchema = Type.String({
   description:
-    "4-char anchor of the LAST line of the range searched; same as replace_from for a single line.",
+    "4-char anchor of the LAST line of the range searched; same as `replace_from` for a single line.",
 });
-const replaceMatchOldStringSchema = Type.String({
+const replaceMatchMatchSchema = Type.String({
   description:
-    "The exact text to find inside the selected line(s), copied from the served row: only the fragment that changes, never text that `new_string` leaves unchanged. If `old_string` is everything on the line except indentation and trailing punctuation, that is a whole-line match: use `replace` instead. Every occurrence inside the range is replaced; the text around each match is left untouched. Matching uses LF line breaks and excludes the last line's terminator.",
+    "The exact text to find inside the selected lines, copied from the served row: only the fragment that changes, never text that `replacement` leaves unchanged. It must stay within one line and hold text: a single trailing line break is accepted as the line's own terminator, a line break anywhere else is refused, and a value that is only a line break leaves nothing to find and is refused. Every occurrence inside the range is replaced; the text around each match is left untouched. If `match` is an entire single-line range except indentation and trailing punctuation, that is a whole-line match: use `replace` instead.",
 });
-const replaceMatchNewStringSchema = Type.String({
+const replaceMatchReplacementSchema = Type.String({
   description:
-    `The exact replacement for every matched occurrence. "" deletes the matches. ${TEXT_ENDING_NOTE} The rest of the range is kept byte-for-byte.`,
+    `The exact replacement for every matched occurrence within the range. "" deletes the matches. It must stay within one line: a single trailing line break is accepted and dropped (a value that is only a line break counts as ""), and a line break anywhere else is refused. The rest of each line is kept byte-for-byte.`,
 });
 const replaceMatchPathRequiredSchema = Type.String({
   description:
@@ -249,8 +268,8 @@ export const replaceMatchToolSchema = Type.Object(
   {
     replace_from: replaceMatchFromSchema,
     replace_to: replaceMatchToSchema,
-    old_string: replaceMatchOldStringSchema,
-    new_string: replaceMatchNewStringSchema,
+    match: replaceMatchMatchSchema,
+    replacement: replaceMatchReplacementSchema,
   },
   { additionalProperties: true },
 );
@@ -262,8 +281,8 @@ export function buildReplaceMatchToolSchema(requirePath: boolean): typeof replac
       path: replaceMatchPathRequiredSchema,
       replace_from: replaceMatchFromSchema,
       replace_to: replaceMatchToSchema,
-      old_string: replaceMatchOldStringSchema,
-      new_string: replaceMatchNewStringSchema,
+      match: replaceMatchMatchSchema,
+      replacement: replaceMatchReplacementSchema,
     },
     { additionalProperties: true },
   ) as typeof replaceMatchToolSchema;

package/src/replace-match.ts

@@ -1,10 +1,9 @@
 import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { constants } from "node:fs";
-import * as Diff from "diff";
 import { execPipeline, noteAnchorError, previewFromPipe, previewError, type ReplaceDetails } from "./replace";
 import { commitEdit } from "./commit";
 import { readNormFile, type NormFile } from "./file-reader";
-import { fmtRegion, MAX_HASH_LINES, parseHashRef, parsePayloadText, planEdit, preserveDeletionSeparators, resEdit, resolveAnchorLine, stripAnchorRow, type Anchor } from "./hashline";
+import { fmtRegion, MAX_HASH_LINES, parseHashRef, planEdit, preserveDeletionSeparators, resEdit, resolveAnchorLine, stripAnchorRow, type Anchor } from "./hashline";
 import { servedForPath, withAnchorSession } from "./anchor-registry";
 import { batchMemberFor, executeBatchMember, noteBatchFailure, registerBatchPlanner, type BatchMemberPlan, type BatchPlannerInput } from "./batch";
 import { loadP, loadGuidelines } from "./prompts";
@@ -13,13 +12,13 @@ import {
   buildReplaceMatchToolSchema,
   getReplaceMatchInput,
   normReq,
+  singleLineFragment,
   type ReplaceMatchReq,
 } from "./payload-contract";
 import { literalEscapeHints, makePrepareArguments, splitLines } from "./utils";
-import { toLF, type LineEnding } from "./normalize";
-import { isFidelitySensitiveChar } from "./edit-fidelity";
-import { countNewlines, splitWithEndings } from "./line-endings";
+import { type LineEnding } from "./normalize";
 import { MAX_RANGE_STALE_LINES } from "./constants";
+import { formatCharEscape, isFidelitySensitiveChar } from "./edit-fidelity";
 import {
   assertBoundaryLinesServed,
   DEFAULT_EDIT_FLAGS,
@@ -43,73 +42,43 @@ interface MatchRefs {
 
 export interface MatchPlan {
   editParams: { remove_from: string; remove_to: string; text: string };
-  warnings: string[];
   contentSeparators: (LineEnding | undefined)[];
   servedOverride?: ReadonlyMap<string, string>;
 }
 
-function formatMatchRange(start: number, end: number): string {
-  return start === end ? `line ${start}` : `lines ${start}-${end}`;
-}
-
 function replaceAllOccurrences(
-  text: string,
-  oldText: string,
-  newText: string,
-): { text: string; separators: (LineEnding | undefined)[]; count: number } {
+  line: string,
+  matchText: string,
+  replacementText: string,
+): { text: string; count: number } {
   const parts: string[] = [];
-  const inserted: Array<{ start: number; end: number }> = [];
-  let length = 0;
-  const append = (chunk: string, fromNewText: boolean): void => {
-    if (fromNewText) inserted.push({ start: length, end: length + chunk.length });
-    parts.push(chunk);
-    length += chunk.length;
-  };
   let cursor = 0;
   let count = 0;
   for (;;) {
-    const found = text.indexOf(oldText, cursor);
+    const found = line.indexOf(matchText, cursor);
     if (found < 0) break;
-    append(text.slice(cursor, found), false);
-    append(newText, true);
-    cursor = found + oldText.length;
+    parts.push(line.slice(cursor, found), replacementText);
+    cursor = found + matchText.length;
     count += 1;
   }
-  if (count === 0) return { text, separators: [], count: 0 };
-  append(text.slice(cursor), false);
-  const replacement = parts.join("");
-  const parsed = splitWithEndings(replacement);
-  const separators: (LineEnding | undefined)[] = [];
-  let offset = 0;
-  let insertedIndex = 0;
-  for (let index = 0; index < parsed.lines.length; index++) {
-    offset += parsed.lines[index]!.length;
-    const ending = parsed.endings[index];
-    if (ending === undefined) continue;
-    while (insertedIndex < inserted.length && inserted[insertedIndex]!.end <= offset) insertedIndex += 1;
-    const fromNewText = insertedIndex < inserted.length && offset >= inserted[insertedIndex]!.start && offset < inserted[insertedIndex]!.end;
-    separators.push(fromNewText ? ending : undefined);
-    offset += ending.length;
-  }
-  return { text: replacement, separators, count };
+  if (count === 0) return { text: line, count: 0 };
+  parts.push(line.slice(cursor));
+  return { text: parts.join(""), count };
 }
 
-const RETYPE_DIFF_MAX_CHARS = 20_000;
-const RETYPE_MAX_EDIT_LENGTH = 2000;
-const RETYPE_MIN_UNCHANGED_CHARS = 40;
-const RETYPE_MIN_UNCHANGED_MULTILINE = 20;
-const RETYPE_EXAMPLE_MAX_CHARS = 40;
-const WHOLE_RANGE_MIN_CHARS = 40;
-const WHOLE_RANGE_MIN_LINES = 2;
-const NEAR_MISS_MIN_OLD_CHARS = 20;
-const NEAR_MISS_MATCH_RATIO = 0.8;
+function linesToPayloadText(lines: string[]): string {
+  if (lines.length === 0) return "";
+  const joined = lines.join("\n");
+  return lines[lines.length - 1] === "" ? `${joined}\n` : joined;
+}
 
-interface RetypeAnalysis {
-  changed: number;
-  unchanged: number;
-  middle: { oldFragment: string; newFragment: string };
+function fileInheritedEndings(lineCount: number): (LineEnding | undefined)[] {
+  return new Array<LineEnding | undefined>(lineCount).fill(undefined);
 }
 
+const NEAR_MISS_MIN_MATCH_CHARS = 20;
+const NEAR_MISS_MATCH_RATIO = 0.8;
+
 function commonPrefixLength(left: string, right: string): number {
   const limit = Math.min(left.length, right.length);
   let index = 0;
@@ -124,91 +93,50 @@ function commonSuffixLength(left: string, right: string, prefix: number): number
   return suffix;
 }
 
-function analyzeRetype(oldText: string, newText: string): RetypeAnalysis {
-  const prefix = commonPrefixLength(oldText, newText);
-  const suffix = commonSuffixLength(oldText, newText, prefix);
-  const middle = {
-    oldFragment: oldText.slice(prefix, oldText.length - suffix),
-    newFragment: newText.slice(prefix, newText.length - suffix),
-  };
-  if (oldText.length + newText.length <= RETYPE_DIFF_MAX_CHARS) {
-    const parts = Diff.diffChars(oldText, newText, { maxEditLength: RETYPE_MAX_EDIT_LENGTH }) as Array<{ added?: boolean; removed?: boolean; value: string }> | undefined;
-    if (parts !== undefined) {
-      let changed = 0;
-      let removed = 0;
-      for (const part of parts) {
-        if (part.added === true) changed += part.value.length;
-        else if (part.removed === true) {
-          changed += part.value.length;
-          removed += part.value.length;
-        }
-      }
-      return { changed, unchanged: oldText.length - removed, middle };
-    }
-  }
-  return { changed: middle.oldFragment.length + middle.newFragment.length, unchanged: prefix + suffix, middle };
-}
-
-function retypeSuggestion(analysis: RetypeAnalysis): string {
-  const { oldFragment, newFragment } = analysis.middle;
-  if (oldFragment.length === 0 && newFragment.length === 0) return "Send only the fragment that changes instead.";
-  if (oldFragment.length === 0) return "Send the added text with insert instead.";
-  if (
-    oldFragment.length > RETYPE_EXAMPLE_MAX_CHARS ||
-    newFragment.length > RETYPE_EXAMPLE_MAX_CHARS ||
-    oldFragment.includes("\n") ||
-    newFragment.includes("\n")
-  ) {
-    return "Send only the fragment that changes instead.";
-  }
-  return `Send old_string ${JSON.stringify(oldFragment)} and new_string ${JSON.stringify(newFragment)} instead.`;
+function charAt(text: string, index: number): string | undefined {
+  if (index >= text.length) return undefined;
+  return String.fromCodePoint(text.codePointAt(index)!);
 }
 
-function retypeWarning(oldText: string, newText: string): string | undefined {
-  const analysis = analyzeRetype(oldText, newText);
-  if (analysis.changed === 0) return undefined;
-  const minUnchanged = oldText.includes("\n") ? RETYPE_MIN_UNCHANGED_MULTILINE : RETYPE_MIN_UNCHANGED_CHARS;
-  if (analysis.unchanged < minUnchanged) return undefined;
-  const lineCount = oldText.split("\n").length;
-  return `[W_REPLACE_MATCH_RETYPE] "old_string" retypes ${analysis.unchanged} unchanged character(s) across ${lineCount} line(s). ${retypeSuggestion(analysis)}`;
-}
-
-function wholeRangeWarning(oldText: string, rangeText: string, lineCount: number, start: number, end: number, startHash: string, endHash: string): string | undefined {
-  if (oldText !== rangeText) return undefined;
-  if (lineCount < WHOLE_RANGE_MIN_LINES && oldText.length < WHOLE_RANGE_MIN_CHARS) return undefined;
-  return `[W_REPLACE_MATCH_WHOLE_RANGE] "old_string" is the entire selected range (${formatMatchRange(start, end)}); the anchors already identify it. Use replace with remove_from "${startHash}", remove_to "${endHash}" and the new text, or send only the fragment that changes.`;
+function codePointStart(text: string, index: number): number {
+  if (index <= 0 || index >= text.length) return index;
+  const before = text.charCodeAt(index - 1);
+  const at = text.charCodeAt(index);
+  return before >= 0xd800 && before <= 0xdbff && at >= 0xdc00 && at <= 0xdfff ? index - 1 : index;
 }
 
 function describeChar(char: string | undefined): string {
   if (char === undefined) return "the end of the text";
   const codePoint = char.codePointAt(0)!;
-  const shown = JSON.stringify(char);
-  return isFidelitySensitiveChar(char) || codePoint < 0x20 || codePoint > 0x7e
-    ? `${shown} (U+${codePoint.toString(16).toUpperCase().padStart(4, "0")})`
-    : shown;
+  return isFidelitySensitiveChar(char) || codePoint > 0x7e ? `"${formatCharEscape(char)}"` : JSON.stringify(char);
 }
 
-function nearMissDetail(oldText: string, rangeText: string, start: number): string | undefined {
-  if (oldText.length < NEAR_MISS_MIN_OLD_CHARS && !oldText.includes("\n")) return undefined;
-  const prefix = commonPrefixLength(oldText, rangeText);
-  const suffix = commonSuffixLength(oldText, rangeText, prefix);
-  const comparable = Math.min(oldText.length, rangeText.length);
+function nearMissDetail(matchText: string, lineText: string, line: number): string | undefined {
+  if (matchText.length < NEAR_MISS_MIN_MATCH_CHARS) return undefined;
+  const prefix = commonPrefixLength(matchText, lineText);
+  const suffix = commonSuffixLength(matchText, lineText, prefix);
+  const comparable = Math.min(matchText.length, lineText.length);
   if (prefix + suffix < Math.floor(comparable * NEAR_MISS_MATCH_RATIO)) return undefined;
-  const lineOffset = countNewlines(rangeText.slice(0, prefix));
-  const column = prefix - rangeText.lastIndexOf("\n", prefix - 1);
-  return `the first mismatch is at line ${start + lineOffset}, col ${column}: the file has ${describeChar(rangeText[prefix])} where old_string has ${describeChar(oldText[prefix])}.`;
+  const fileStart = codePointStart(lineText, prefix);
+  const matchStart = codePointStart(matchText, prefix);
+  const column = [...lineText.slice(0, fileStart)].length + 1;
+  return `the first mismatch is at line ${line}, col ${column}: the file has ${describeChar(charAt(lineText, fileStart))} where match has ${describeChar(charAt(matchText, matchStart))}.`;
 }
 
-function notFoundMessage(displayPath: string, start: number, end: number, fileHashes: string[], fileLines: string[], rangeText: string, oldText: string): string {
+function formatMatchRange(start: number, end: number): string {
+  return start === end ? `line ${start}` : `lines ${start}-${end}`;
+}
+
+function notFoundMessage(displayPath: string, start: number, end: number, fileHashes: string[], fileLines: string[], rangeText: string, matchText: string): string {
   const rangeLength = end - start + 1;
   const shownCount = Math.min(rangeLength, MAX_RANGE_STALE_LINES);
   const shown = fmtRegion(fileHashes.slice(start - 1, start - 1 + shownCount), fileLines.slice(start - 1, start - 1 + shownCount));
-  const more = rangeLength > shownCount ? `\n[The range has ${rangeLength} lines; showing the first ${shownCount}.]` : "";
-  const nearMiss = nearMissDetail(oldText, rangeText, start);
+  const more = rangeLength > shownCount ? `\n[The range has ${rangeLength} lines; showing the first ${shownCount}. Call read with offset=${start + shownCount} to see the rest.]` : "";
+  const nearMiss = start === end ? nearMissDetail(matchText, rangeText, start) : undefined;
   const advice = nearMiss !== undefined
-    ? `${nearMiss} That looks like a retyped copy of the range; send only the fragment that changes (copy it from the served row), or use replace with the same anchors.`
-    : "Copy only the fragment that changes from the served row (comparison uses LF breaks and excludes the last line's terminator) and retry; for a whole-line or whole-range rewrite use replace with the same anchors.";
-  return `[E_SUBSTRING_NOT_FOUND] "old_string" was not found in ${formatMatchRange(start, end)} of ${displayPath}. Current rows:\n\n${shown}${more}\n\n${advice}`;
+    ? `${nearMiss} That looks like a retyped copy of the line; send only the fragment that changes (copy it from the served row), or use replace with the same anchor.`
+    : "Copy only the fragment that changes from the served row (a trailing line break is accepted and dropped) and retry; for a whole-line rewrite use replace with the same anchors.";
+  return `[E_SUBSTRING_NOT_FOUND] "match" was not found in ${formatMatchRange(start, end)} of ${displayPath}. Current rows:\n\n${shown}${more}\n\n${advice}`;
 }
 
 export function parseMatchAnchors(req: ReplaceMatchReq): { refs: MatchRefs; warnings: string[] } {
@@ -225,6 +153,8 @@ export function buildReplaceMatchEdit(
   displayPath: string,
   served?: ReadonlyMap<string, string>,
 ): MatchPlan {
+  const matchText = singleLineFragment("match", req.match);
+  const replacementText = singleLineFragment("replacement", req.replacement);
   const fileLines = splitLines(preload.normalized);
   const fromLine = resolveAnchorLine(refs.from, fileLines, preload.fileHashes, displayPath);
   const toLine = resolveAnchorLine(refs.to, fileLines, preload.fileHashes, displayPath);
@@ -232,33 +162,26 @@ export function buildReplaceMatchEdit(
   const end = Math.max(fromLine, toLine);
   assertBoundaryLinesServed(fileLines, preload.fileHashes, served, start, end, displayPath);
   const rangeLines = fileLines.slice(start - 1, end);
-  const rangeText = `${rangeLines.join("\n")}${rangeLines[rangeLines.length - 1] === "" ? "\n" : ""}`;
-  const oldText = toLF(req.old_string);
-  const newText = toLF(req.new_string);
-  const { text: replacement, separators: replacementSeparators, count } = replaceAllOccurrences(rangeText, oldText, req.new_string);
+  let count = 0;
+  const replacementLines = rangeLines.map((line) => {
+    const result = replaceAllOccurrences(line, matchText, replacementText);
+    count += result.count;
+    return result.text;
+  });
   if (count === 0) {
-    throw new Error(notFoundMessage(displayPath, start, end, preload.fileHashes, fileLines, rangeText, oldText));
+    throw new Error(notFoundMessage(displayPath, start, end, preload.fileHashes, fileLines, linesToPayloadText(rangeLines), matchText));
   }
-  const contentSeparators = parsePayloadText(replacement).lines.map((_, index) => replacementSeparators[index]);
+  const replacement = linesToPayloadText(replacementLines);
   const startRef = fromLine <= toLine ? refs.from : refs.to;
   const endRef = fromLine <= toLine ? refs.to : refs.from;
   const servedOverride = trustRangeServed(fileLines, preload.fileHashes, served, start, end);
-  const warnings: string[] = [];
-  const retype = retypeWarning(oldText, newText);
-  if (retype !== undefined) {
-    warnings.push(retype);
-  } else {
-    const wholeRange = wholeRangeWarning(oldText, rangeText, rangeLines.length, start, end, startRef.hash, endRef.hash);
-    if (wholeRange !== undefined) warnings.push(wholeRange);
-  }
   return {
     editParams: {
       remove_from: startRef.hash,
       remove_to: endRef.hash,
       text: replacement,
     },
-    warnings,
-    contentSeparators,
+    contentSeparators: fileInheritedEndings(replacementLines.length),
     ...(servedOverride !== undefined ? { servedOverride } : {}),
   };
 }
@@ -267,7 +190,7 @@ function planReplaceMatchBatchMember(input: BatchPlannerInput): BatchMemberPlan
   const req = normReq(input.member.args, "replace");
   assertReplaceMatchReq(req);
   const { refs, warnings } = parseMatchAnchors(req);
-  const hints = [...literalEscapeHints([req.old_string], "old_string"), ...literalEscapeHints([req.new_string], "new_string")];
+  const hints = [...literalEscapeHints([req.match], "match"), ...literalEscapeHints([req.replacement], "replacement")];
   const preload = { normalized: input.base.content, fileHashes: input.base.hashes } as NormFile;
   const matchPlan = buildReplaceMatchEdit(req, refs, preload, input.displayPath, input.served);
   const resWarnings: string[] = [];
@@ -281,11 +204,10 @@ function planReplaceMatchBatchMember(input: BatchPlannerInput): BatchMemberPlan
   });
   return {
     hedit,
-    warnings: [...warnings, ...hints, ...resWarnings, ...matchPlan.warnings],
+    warnings: [...warnings, ...hints, ...resWarnings],
     contentSeparators: matchPlan.contentSeparators,
     planned,
     foldedLines: 0,
-    ...(matchPlan.servedOverride !== undefined ? { servedOverride: matchPlan.servedOverride } : {}),
   };
 }
 
@@ -312,7 +234,6 @@ export async function replaceMatchPreview(request: unknown, cwd: string, signal?
       signal,
     });
     const plan = buildReplaceMatchEdit(req, refs, preload, targetPath, servedForPath(preload.absolutePath));
-    await throwIfStrictInput(plan.warnings);
     const pipe = await execPipeline(targetPath, plan.editParams, cwd, {
       accessMode: constants.R_OK,
       noPersist: true,
@@ -367,7 +288,7 @@ export function buildReplaceMatchToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLA
           if (member) noteBatchFailure(member, error);
           throw error;
         }
-        const hints = [...literalEscapeHints([req.old_string], "old_string"), ...literalEscapeHints([req.new_string], "new_string")];
+        const hints = [...literalEscapeHints([req.match], "match"), ...literalEscapeHints([req.replacement], "replacement")];
         const targetPath = await resolveEditTargetWithRequirement({
           removeFrom: req.replace_from,
           removeTo: req.replace_to,
@@ -394,7 +315,6 @@ export function buildReplaceMatchToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLA
             await noteAnchorError(mutationTargetPath, error);
             throw error;
           }
-          await throwIfStrictInput(plan.warnings);
           const pipe = await execPipeline(targetPath, plan.editParams, ctx.cwd, {
             accessMode: constants.R_OK | constants.W_OK,
             signal,
@@ -407,7 +327,7 @@ export function buildReplaceMatchToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLA
             absolutePath,
             mutationTargetPath,
             editAnchors: [plan.editParams.remove_from, plan.editParams.remove_to],
-            prefixWarnings: [...warnings, ...hints, ...plan.warnings],
+            prefixWarnings: [...warnings, ...hints],
             signal,
             verb: "replaced",
             noopNoun: "Replacement",

package/tool-prompts/read-guidelines.md

@@ -1,3 +1,3 @@
 - `read`: call again after an edit when you need anchors you lack — post-edit diff `+`/` ` rows and served `anchor│content` rows already carry fresh anchors for the changed range.
 - `read`: an auto-read-all outline row shows a symbol label, or a single-line symbol's content; its `[limit N]` is the span to request.
-- `read`: `replace_match` needs both boundary lines served; copy `old_string` from a served row or read the lines first.
+- `read`: `replace_match` needs both boundary lines served; copy `match` from a served row or read the lines first.

package/tool-prompts/replace-match-guidelines.md

@@ -1,3 +1,3 @@
-- `replace_match`: `old_string` is only the fragment that changes — never text that `new_string` leaves unchanged; every occurrence inside the range is replaced, so scope the range when only some lines should change.
-- `replace_match`: if `old_string` is everything on the line except indentation and trailing punctuation, that match is the whole line — use `replace`. A shorter fragment repeated on several lines (a value, a name) is the intended multi-line use.
-- `replace_match`: when the change covers whole lines or the whole range, use `replace` with the same anchors and the exact text.
+- `replace_match`: `match` is only the fragment that changes — never text that `replacement` leaves unchanged; every occurrence inside the range is replaced, so narrow the anchors when only some lines should change.
+- `replace_match`: the anchors bound the range searched, and `match`/`replacement` must each stay within one line — a trailing line break is the line's terminator, an interior one belongs to `replace`, and a lone break cannot be a `match`.
+- `replace_match`: when the change covers the whole line, use `replace` with the same anchor and the exact text.

package/tool-prompts/replace-match-snippet.md

@@ -1 +1 @@
-Replace part of a line or range by anchor: every `old_string` occurrence inside `replace_from`/`replace_to` becomes `new_string`; the rest of the line stays untouched
+Replace part of a line or range by anchor: every `match` occurrence inside the range becomes `replacement`; the rest of each line stays untouched

package/tool-prompts/replace-match.md

@@ -1,3 +1,3 @@
-Replace part of a line (or a range of lines) without retyping the rest. `replace_from`/`replace_to` are bare anchors from served `anchor│content` rows marking the range's first and last line (the same anchor for one line), and `old_string` is the exact text to find inside that range. Send only the fragment that changes — never text that `new_string` leaves unchanged. If `old_string` is everything on the line except indentation and trailing punctuation, that is a whole-line rewrite: use `replace` with the same anchors. The same short fragment on several lines (a value, a name) may be replaced in one call. `remove_from`/`remove_to` are accepted as aliases.
+Replace 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, while a line break anywhere else is refused; a lone line break leaves nothing to find in `match` and counts as `""` in `replacement`. Send only the fragment that changes — never text that `replacement` leaves unchanged. The anchors bound the search, so `match` only needs to be unique inside the selected range, not file-wide; when only one occurrence on a range should change, narrow `replace_from`/`replace_to` instead of lengthening the fragment. If `match` is an entire single-line range except indentation and trailing punctuation, that is a whole-line rewrite: use `replace` with the same anchors. `remove_from`/`remove_to` are accepted as aliases.
 
-The two boundary anchors must still match what was last shown; lines strictly inside the range are matched against the file as it is on disk.
+The two boundary anchors must still match what was last shown; lines strictly inside the range are searched as they are on disk.