pi-hashline-edit-pro 6.4.1 → 6.4.2

package/README.md

@@ -219,12 +219,14 @@ 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. 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 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. 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.
 
 `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.
 
+`replace_match` reports `[W_REPLACE_MATCH_WHOLE_RANGE]` when `old_string` is the entire selected range, `[W_REPLACE_MATCH_RETYPE]` when `old_string` retypes a long run of text that `new_string` leaves unchanged, and `[W_REPLACE_MATCH_MULTI]` when `old_string` matched more than one occurrence. In strict-input mode the first two are refused 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`.
 
 ### insert
@@ -339,7 +341,7 @@ Auto-read keeps the same 50KB and 2000-line budget as `read`. Auto-read and Diff
 
 Auto-read all is off by default and has three modes, selected in `/hashline-config`: `off` injects nothing; `outline` attaches an anchor-stamped structural outline per file; and `full` discovers every file in the working directory that is not git-ignored (`git ls-files`, falling back to `ripgrep`, then to a directory walk) and attaches full contents. `Git repos only` is on by default and keeps the whole injection inside a git repository; turn it off to attach files in any directory. On the first turn of a session, the extension discovers the files, reads each one, and attaches the resulting `anchor│content` rows to the conversation as one extension message before the model answers. Those anchors are served exactly like `read` output, so the model can `replace` and `insert` immediately without calling `read` first. The message is injected once per session; resumed, forked, and cloned sessions that already contain it skip the injection.
 
-Files are filtered before injection: symlinks, directories, image extensions (including SVG), binary files (a NUL byte in the first 8KB), files over 200KB, any path with a vendored segment (vendor, node_modules, bower_components, third_party, thirdparty, jspm_packages, .venv, venv, site-packages, __pycache__, .tox, .gradle, .terraform, Pods, Carthage, DerivedData, coreui, coreui-icons, case-insensitive; `resources/views/vendor` is kept so Laravel view overrides stay attached), and vendored or generated names and patterns (*.min.js, *.min.css, *.min.mjs, *-min.js, *-min.css, *.bundle.*, *.chunk.*, *.umd.js, *.map, *.lock, package-lock.json, yarn.lock, composer.lock, Gemfile.lock, Cargo.lock, poetry.lock, Pipfile.lock, go.sum, flake.lock, *.generated.*, *.gen.*, *_pb2.py, *.pb.go, *.g.dart, *.freezed.dart, *.designer.cs, *.g.cs, *.snap, _ide_helper.php, _ide_helper_models.php, .phpstorm.meta.php, .eslintcache, coreui-icons.*, coreui.css) are skipped. The attachment stops at 500 files or at a byte budget derived from the model context window (200KB floor, 2MB ceiling), and it never drops below one file. Skipped and not-attached files are named at the end of the message so the model can `read` them on demand. A model matched by `disableOnModels` skips the injection entirely.
+Files are filtered before injection: symlinks, directories, image extensions (including SVG), binary files (a NUL byte in the first 8KB), files over 200KB, any path with a vendored segment (vendor, node_modules, bower_components, third_party, thirdparty, jspm_packages, .venv, venv, site-packages, __pycache__, .tox, .gradle, .terraform, Pods, Carthage, DerivedData, coreui, coreui-icons, case-insensitive; `resources/views/vendor` is kept so Laravel view overrides stay attached), and vendored or generated names and patterns (*.min.js, *.min.css, *.min.mjs, *-min.js, *-min.css, *.bundle.*, *.chunk.*, *.umd.js, *.map, *.lock, package-lock.json, yarn.lock, composer.lock, Gemfile.lock, Cargo.lock, poetry.lock, Pipfile.lock, go.sum, flake.lock, *.generated.*, *.gen.*, *_pb2.py, *.pb.go, *.g.dart, *.freezed.dart, *.designer.cs, *.g.cs, *.snap, _ide_helper.php, _ide_helper_models.php, .phpstorm.meta.php, .eslintcache, coreui-icons.*, coreui.css) are skipped. The attachment stops at 500 files or at a byte budget derived from the model context window (200KB floor, 2MB ceiling), and it never drops below one file; `full` also caps the budget at 2MB, while `outline` follows the context-derived budget because outlines stay compact. Skipped and not-attached files are named at the end of the message so the model can `read` them on demand. A model matched by `disableOnModels` skips the injection entirely.
 
 Each attached file starts with a header (`=== path ===` in `full` mode, `=== path (language) — lines ===` in `outline` mode) followed by its anchor rows. Edit directly from the attachment with replace and insert, so no `read` is needed. `full` attaches files whole; `outline` attaches each file's structural outline within the budget. In outline mode, multi-line symbols appear as labels with `[limit N]` and single-line symbols appear as their content.
 
@@ -406,7 +408,7 @@ When `PI_HASHLINE_DIR` is unset or empty, non-Windows platforms honor `XDG_CONFI
 | Grep output | 2000 rows and 50KB | `grep` |
 | Grep row fragment | 500 bytes | long match and context rows shown as `...` fragments |
 | Auto-read all files | 500 files, 200KB per file | files larger than 200KB and files past the cap are omitted |
-| Auto-read all budget | 200KB floor, 2MB ceiling | total injection size, derived from the model context window |
+| Auto-read all budget | 200KB floor; 2MB ceiling in `full` | total injection size derived from the model context window; `outline` is not capped at 2MB |
 | Stale-range feedback | first 100 lines | rows returned with `[E_RANGE_STALE]` |
 | Session anchors | 1,353,139 anchors in use | all tools; the least recently read or edited files are freed when the quota is exhausted (`[W_ANCHOR_RECLAIMED]`) |
 
@@ -456,11 +458,14 @@ Full reference:
 | `[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. |
 | `[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; copy `old_string` exactly from the served row and retry. |
+| `[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. |
 | `[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_REPLACE_MATCH_MULTI]` | `replace_match` `old_string` matched more than one occurrence in the range and every one was replaced. Narrow the range or send a longer fragment if you meant only one. |
 | `[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. |

package/index.ts

@@ -210,7 +210,7 @@ export default function (pi: ExtensionAPI): void {
     if (modelDisabled(ctx.model, disableOnModels)) return;
     autoReadAllInjected = true;
     try {
-      const injection = await buildAutoReadAllInjection(ctx.cwd, autoReadAllBudget(ctx.model), autoReadAll, autoReadAllIgnore, autoReadAllRequireGit);
+      const injection = await buildAutoReadAllInjection(ctx.cwd, autoReadAllBudget(ctx.model, autoReadAll), autoReadAll, autoReadAllIgnore, autoReadAllRequireGit);
       if (!injection) return;
       if (ctx.hasUI) ctx.ui.notify(`Auto-read all: ${isOutlineAutoReadAll(autoReadAll) ? "outlined" : "attached"} ${injection.files} file(s)`, "info");
       return { message: { customType: AUTO_READ_ALL_CUSTOM_TYPE, content: injection.text, display: false } };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "6.4.1",
+  "version": "6.4.2",
   "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,7 +61,7 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^1.0.3",
+    "@earendil-works/pi-coding-agent": "^1.2.0",
     "@eslint/js": "^10.0.1",
     "@types/node": "^24",
     "@vitest/coverage-v8": "^4.1.11",

package/src/auto-read-all.ts

@@ -433,6 +433,10 @@ export async function buildAutoReadAllInjection(cwd: string, budgetBytes: number
   let bytes = 0;
   let completeFiles = 0;
   for (const file of discovery.files) {
+    if (sections.length > 0 && bytes >= budgetBytes) {
+      omitted.push(file);
+      continue;
+    }
     if (!outline && sections.length > 0) {
       const size = await candidateFileBytes(cwd, file);
       if (size !== undefined && bytes + size > budgetBytes) {
@@ -462,8 +466,9 @@ export async function buildAutoReadAllInjection(cwd: string, budgetBytes: number
   return { text, files: sections.length, bytes, omitted, completeFiles };
 }
 
-export function autoReadAllBudget(model: { contextWindow?: number } | undefined): number {
+export function autoReadAllBudget(model: { contextWindow?: number } | undefined, mode: AutoReadAllMode = "full"): number {
   const contextWindow = typeof model?.contextWindow === "number" && model.contextWindow > 0 ? model.contextWindow : 0;
   const fromContext = Math.floor(contextWindow * 1.5);
-  return Math.min(AUTO_READ_ALL_MAX_BUDGET_BYTES, Math.max(AUTO_READ_ALL_MIN_BUDGET_BYTES, fromContext));
+  const budget = Math.max(AUTO_READ_ALL_MIN_BUDGET_BYTES, fromContext);
+  return mode === "outline" ? budget : Math.min(AUTO_READ_ALL_MAX_BUDGET_BYTES, budget);
 }

package/src/edit-common.ts

@@ -160,7 +160,9 @@ export function withInsertPrompts(base: { description: string; snippet: string;
 
 export function withReplaceMatchPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
   const guidelines = [preferenceGuideline(flags), ...base.guidelines.map((guideline) => guideline.text)];
-  return finalizePrompts(base.description, base.snippet, guidelines, flags);
+  const prompted = finalizePrompts(base.description, base.snippet, guidelines, flags);
+  if (flags.strictInput) prompted.guidelines.push("`replace_match`: strict-input mode rejects an `old_string` that covers the whole range or retypes unchanged text.");
+  return prompted;
 }
 
 function gatedEditOps(ops: string[], flags: EditToolFlags): string[] {
@@ -299,13 +301,13 @@ export async function resolveEditTargetWithRequirement(input: PathRequirementInp
   return anchorTarget;
 }
 
-const AUTO_FIX_WARNING_CODES = ["[W_BAD_SHAPE]", "[W_BAD_REF]", "[W_INVALID_PATCH]", "[W_BARE_HASH_PREFIX]"];
+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]"];
 export async function throwIfStrictInput(warnings: string[]): Promise<void> {
-  const fixes = warnings.filter((warning) => AUTO_FIX_WARNING_CODES.some((code) => warning.startsWith(code)));
+  const fixes = warnings.filter((warning) => STRICT_INPUT_REJECT_CODES.some((code) => warning.startsWith(code)));
   if (fixes.length === 0) return;
   const { strictInput } = await readConfig();
   if (strictInput === true) {
-    throw new Error(`[E_BAD_SHAPE] Strict-input mode rejects auto-fixable input:\n${fixes.join("\n")}`);
+    throw new Error(`[E_BAD_SHAPE] Strict-input mode rejects auto-fixable input and replace_match retyping warnings:\n${fixes.join("\n")}`);
   }
 }
 

package/src/file-kind.ts

@@ -89,7 +89,7 @@ export async function loadFileKindAndText(
   const fileHandle = await fsOpen(filePath, "r");
   try {
     const openedStats = await fileHandle.stat();
-    const identity = { dev: openedStats.dev, ino: openedStats.ino };
+    const identity = { dev: openedStats.dev, ino: openedStats.ino, mtimeMs: openedStats.mtimeMs, size: openedStats.size };
     const buffer = Buffer.alloc(SNIFF_BYTES);
     const { bytesRead } = await fileHandle.read(
       buffer,

package/src/file-reader.ts

@@ -101,8 +101,8 @@ export async function readNormFile(
   const fileHashes = await lineHashes(normalized, resolvedPath, undefined, options?.store, options?.noPersist !== true, options?.allocation === "shadow");
   let identity = file.identity;
   if (!identity) {
-    const { dev, ino } = await stat(resolvedPath);
-    identity = { dev, ino };
+    const { dev, ino, mtimeMs, size } = await stat(resolvedPath);
+    identity = { dev, ino, mtimeMs, size };
   }
   return {
     absolutePath: resolvedPath,

package/src/fs-write.ts

@@ -18,13 +18,18 @@ import { errCode, isModeUnsupported, mapIoError } from "./utils";
 export interface FileIdentity {
   dev: number;
   ino: number;
+  mtimeMs?: number;
+  size?: number;
 }
 
 function sameIdentity(
   actual: FileIdentity,
   expected: FileIdentity,
 ): boolean {
-  return actual.dev === expected.dev && actual.ino === expected.ino;
+  if (actual.dev !== expected.dev || actual.ino !== expected.ino) return false;
+  if (expected.mtimeMs !== undefined && actual.mtimeMs !== expected.mtimeMs) return false;
+  if (expected.size !== undefined && actual.size !== expected.size) return false;
+  return true;
 }
 
 function pathChanged(path: string): Error {

package/src/grep.ts

@@ -633,7 +633,6 @@ export function regGrep(pi: ExtensionAPI, flags: EditToolFlags = DEFAULT_EDIT_FL
         if (limitTruncated) notes.push(`[grep: showing first ${limit} matches; increase limit to see more.]`);
         if (linesReplaced > 0) notes.push(`[grep: ${linesReplaced} line(s) exceed ${formatSize(MAX_GREP_LINE_BYTES)} and are shown as truncated fragments; use read to see the full lines.]`);
         if (poolSkipped > 0) notes.push(`[grep: ${poolSkipped} file(s) skipped because the session's anchor pool is exhausted; narrow the search.]`);
-        if (context > 0 && hits.length > 0) notes.push('[grep: match rows are "line:│", context rows are "line-│".]');
         const truncated = limitTruncated || rowTruncated;
         const truncation: TruncationResult | undefined = rowTruncated
           ? {

package/src/hash-store.ts

@@ -111,9 +111,19 @@ async function selectSqliteEngine(): Promise<{ engine: SqliteEngine; open: (path
   throw new Error(`[E_STORE_UNAVAILABLE] No SQLite runtime available (node:sqlite and bun:sqlite both failed to load): ${detail}`);
 }
 
-const selectedEngine = await selectSqliteEngine();
-const sqliteEngine: SqliteEngine = selectedEngine.engine;
-const openDbFn = selectedEngine.open;
+type EngineSelection = { engine: SqliteEngine; open: (path: string) => RawDb };
+let engineSelection: EngineSelection | undefined;
+let engineSelectionError: unknown;
+try {
+  engineSelection = await selectSqliteEngine();
+} catch (error) {
+  engineSelectionError = error;
+}
+function requireEngine(): EngineSelection {
+  if (engineSelection !== undefined) return engineSelection;
+  if (engineSelectionError instanceof Error) throw engineSelectionError;
+  throw new Error("[E_STORE_UNAVAILABLE] No SQLite runtime available.");
+}
 
 interface Prepared {
   get: (...params: SqlParams) => Record<string, unknown> | undefined;
@@ -151,7 +161,7 @@ let storeEpoch = 0;
 const liveDbs = new Set<RawDb>();
 
 function openDb(storePath: string): { db: RawDb; stmts: Prepared } {
-  const db = openDbFn(storePath);
+  const db = requireEngine().open(storePath);
   liveDbs.add(db);
   try {
     return buildStore(db);
@@ -285,6 +295,7 @@ function shutdownDb(db: RawDb): void {
 async function openStore(storePath: string): Promise<HashStore> {
   if (cachedDb) shutdownHashStore();
   const epoch = storeEpoch;
+  const engine = requireEngine();
   await initHasher();
   await mkdir(hashStoreDir(), { recursive: true, mode: 0o700 });
   if (process.platform !== "win32") {
@@ -362,13 +373,13 @@ async function openStore(storePath: string): Promise<HashStore> {
     }
   }
 
-  return { stmts, engine: sqliteEngine };
+  return { stmts, engine: engine.engine };
 }
 
 export function loadHashStore(): Promise<HashStore> {
   const storePath = hashStorePath();
   if (cachedDb && cachedDb.path === storePath && cachedDb.db.isOpen) {
-    return Promise.resolve({ stmts: cachedDb.stmts, engine: sqliteEngine });
+    return Promise.resolve({ stmts: cachedDb.stmts, engine: requireEngine().engine });
   }
   if (opening && opening.path === storePath) {
     return opening.promise;

package/src/payload-contract.ts

@@ -234,7 +234,7 @@ const replaceMatchToSchema = Type.String({
 });
 const replaceMatchOldStringSchema = Type.String({
   description:
-    "The exact text to find inside the selected line(s), copied from the served row. 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 line(s), copied from the served row: only the fragment that changes, never text that `new_string` leaves unchanged. 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. For a whole-line or whole-range rewrite use `replace` with the same anchors.",
 });
 const replaceMatchNewStringSchema = Type.String({
   description:

package/src/prompts.ts

@@ -9,7 +9,7 @@ export interface Guideline {
 const GUIDELINE_IDS_BY_NAME: Record<string, readonly string[]> = {
   "read-guidelines.md": ["read-reread", "read-outline", "read-match-served"],
   "replace-guidelines.md": ["replace-disjoint", "replace-deletion", "replace-single-line"],
-  "replace-match-guidelines.md": ["replace-match-fragment", "replace-match-wide-range"],
+  "replace-match-guidelines.md": ["replace-match-fragment", "replace-match-wide-range", "replace-match-whole-range"],
   "insert-guidelines.md": ["insert-blank-edges"],
   "copy-guidelines.md": ["copy-single-anchor"],
   "move-guidelines.md": ["move-same-place"],

package/src/replace-match.ts

@@ -1,5 +1,6 @@
 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";
@@ -16,6 +17,8 @@ import {
 } from "./payload-contract";
 import { literalEscapeHints, makePrepareArguments, splitLines } from "./utils";
 import { toLF } from "./normalize";
+import { isFidelitySensitiveChar } from "./edit-fidelity";
+import { countNewlines } from "./line-endings";
 import { MAX_RANGE_STALE_LINES } from "./constants";
 import {
   assertBoundaryLinesServed,
@@ -40,6 +43,7 @@ interface MatchRefs {
 
 export interface MatchPlan {
   editParams: { remove_from: string; remove_to: string; text: string };
+  warnings: string[];
   servedOverride?: ReadonlyMap<string, string>;
 }
 
@@ -61,12 +65,125 @@ function replaceAllOccurrences(text: string, oldText: string, newText: string):
   return count === 0 ? { text, count: 0 } : { text: out + text.slice(cursor), count };
 }
 
-function notFoundMessage(displayPath: string, start: number, end: number, fileHashes: string[], fileLines: string[]): string {
+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;
+
+interface RetypeAnalysis {
+  changed: number;
+  unchanged: number;
+  middle: { oldFragment: string; newFragment: string };
+}
+
+function commonPrefixLength(left: string, right: string): number {
+  const limit = Math.min(left.length, right.length);
+  let index = 0;
+  while (index < limit && left[index] === right[index]) index += 1;
+  return index;
+}
+
+function commonSuffixLength(left: string, right: string, prefix: number): number {
+  const limit = Math.min(left.length, right.length) - prefix;
+  let suffix = 0;
+  while (suffix < limit && left[left.length - 1 - suffix] === right[right.length - 1 - suffix]) suffix += 1;
+  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 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 multiMatchWarning(count: number, start: number, end: number, displayPath: string): string {
+  return `[W_REPLACE_MATCH_MULTI] "old_string" matched ${count} occurrences in ${formatMatchRange(start, end)} of ${displayPath}; every one was replaced. Narrow the range or send a longer fragment if you meant only one.`;
+}
+
+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;
+}
+
+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);
+  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])}.`;
+}
+
+function notFoundMessage(displayPath: string, start: number, end: number, fileHashes: string[], fileLines: string[], rangeText: string, oldText: 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}.]` : "";
-  return `[E_SUBSTRING_NOT_FOUND] "old_string" was not found in ${formatMatchRange(start, end)} of ${displayPath}. Current rows:\n\n${shown}${more}\n\nCopy old_string exactly from the served row (comparison uses LF breaks and excludes the last line's terminator) and retry.`;
+  const nearMiss = nearMissDetail(oldText, rangeText, start);
+  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}`;
 }
 
 export function parseMatchAnchors(req: ReplaceMatchReq): { refs: MatchRefs; warnings: string[] } {
@@ -92,19 +209,30 @@ export function buildReplaceMatchEdit(
   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, count } = replaceAllOccurrences(rangeText, oldText, req.new_string);
   if (count === 0) {
-    throw new Error(notFoundMessage(displayPath, start, end, preload.fileHashes, fileLines));
+    throw new Error(notFoundMessage(displayPath, start, end, preload.fileHashes, fileLines, rangeText, oldText));
   }
   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);
+  }
+  if (count > 1) warnings.push(multiMatchWarning(count, start, end, displayPath));
   return {
     editParams: {
       remove_from: startRef.hash,
       remove_to: endRef.hash,
       text: replacement,
     },
+    warnings,
     ...(servedOverride !== undefined ? { servedOverride } : {}),
   };
 }
@@ -127,7 +255,7 @@ function planReplaceMatchBatchMember(input: BatchPlannerInput): BatchMemberPlan
   });
   return {
     hedit,
-    warnings: [...warnings, ...hints, ...resWarnings],
+    warnings: [...warnings, ...hints, ...resWarnings, ...matchPlan.warnings],
     planned,
     foldedLines: 0,
     ...(matchPlan.servedOverride !== undefined ? { servedOverride: matchPlan.servedOverride } : {}),
@@ -157,6 +285,7 @@ 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,
@@ -237,6 +366,7 @@ 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,
@@ -248,7 +378,7 @@ export function buildReplaceMatchToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLA
             absolutePath,
             mutationTargetPath,
             editAnchors: [plan.editParams.remove_from, plan.editParams.remove_to],
-            prefixWarnings: [...warnings, ...hints],
+            prefixWarnings: [...warnings, ...hints, ...plan.warnings],
             signal,
             verb: "replaced",
             noopNoun: "Replacement",

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

@@ -1,2 +1,3 @@
-- `replace_match`: `old_string` is usually a fragment of the line, not the whole line; every occurrence inside the range is replaced, so scope the range with anchors when only some occurrences should change.
-- `replace_match`: when you intend to change every matching line in a range, anchor the first and last matching lines of that range so one call replaces them all, instead of one call per line.
+- `replace_match`: `old_string` is only the fragment of the line that changes — never the whole line or range, and never text that `new_string` leaves unchanged; every occurrence inside the range is replaced, so scope the range with anchors when only some occurrences should change.
+- `replace_match`: when the same changed fragment appears on every matching line in a range, anchor the first and last matching lines so one call replaces them all instead of one call per line.
+- `replace_match`: when the change covers whole lines or the whole range, use `replace` with the same anchors and the new text.

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), `old_string` is the text to find inside it, and `new_string` replaces every occurrence. `remove_from`/`remove_to` are accepted as aliases.
+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 smallest fragment that contains the change — never text that `new_string` leaves unchanged; for a whole-line or whole-range rewrite use `replace` with the same anchors instead. `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.