@khanhicetea/pi-better-tool 0.1.0 → 0.2.1

package/README.md

@@ -10,9 +10,10 @@ The built-in `edit` tool requires `edits[].oldText` to match **exactly and uniqu
 Could not find edits[1] in /code/app.go. The oldText must match exactly including all whitespace and newlines.
 ```
 
-That failure wastes a whole loop: the model has to `read` the file again, guess a larger context, and retry — sometimes failing again. `pi-better-tool` keeps the refusal (writing the wrong occurrence would be worse) but returns **recovery context** so the next call succeeds without re-reading:
+That failure wastes a whole loop: the model has to `read` the file again, guess a larger context, and retry — sometimes failing again. `pi-better-tool` resolves only ambiguity supported by verified evidence and otherwise returns **recovery context** so the next call succeeds without re-reading:
 
-- **Ambiguous match (2+ occurrences)** — every occurrence's line number plus the **minimum prefix/suffix context** that makes each occurrence unique, rendered as ready-to-use `oldText` snippets.
+- **Ambiguous literal match after a bounded read** — when exactly one occurrence was fully visible in the latest successful, byte-verified `read` of the same file, edit selects that occurrence. Its success message reports the selected/read ranges and up to four remaining occurrences with effective prefix/suffix context and retryable snippets.
+- **Other ambiguous matches (2+ occurrences)** — bounded occurrence line numbers plus the **minimum prefix/suffix context** that makes the first few occurrences unique, rendered as ready-to-use `oldText` snippets when they fit safely.
 - **Text not found** — the closest matching region (fuzzy line similarity), a line-by-line comparison against your `oldText`, the exact file bytes to retry with, and likely causes (tabs vs spaces, indentation, case).
 
 ## Install
@@ -85,16 +86,17 @@ No changes were written — the file was not modified.
 
 ## Behavior
 
-Happy-path semantics are **identical** to the built-in `edit` tool:
+Normal unique-match semantics are **identical** to the built-in `edit` tool. The one intentional extension is conservative read-based selection for repeated literal text:
 
 - same schema (`path` + `edits[{oldText,newText}]`), including the compatibility shim for models that send `edits` as a JSON string, a single edit object, or legacy top-level `oldText`/`newText`
 - same matching engine ported from pi's `edit-diff.ts`: exact match first, fuzzy fallback (trailing whitespace, smart quotes, dashes, unicode spaces), uniqueness checked in fuzzy-normalized space, all edits matched against the original content, overlap/empty/no-change detection
 - same BOM and CRLF handling
 - same success result shape (`details.diff` / `details.patch` / `details.firstChangedLine`), and no custom renderers — the built-in diff renderer is inherited
+- read-based selection fails closed unless the newest same-file read is still in active context, its stored output exactly matches the current bytes and built-in read formatting, and exactly one complete literal occurrence lies inside the visible range; fuzzy/Unicode-equivalent ambiguity, same-line ambiguity, stale reads, and broad reads containing multiple occurrences still refuse
 
-Failure behavior is the difference: errors carry the recovery context described above, and nothing is written on failure (edits remain atomic).
+Failure behavior is the other difference: errors carry the recovery context described above, and nothing is written on failure (edits remain atomic).
 
-Diagnostics degrade gracefully: files over ~2 MB skip the analysis and return the plain built-in-style error; repeated blocks that cannot be disambiguated within 12 context lines get a guidance note instead of snippets.
+Diagnostics degrade gracefully: files over ~2 MB skip the analysis and return the plain built-in-style error; repeated blocks that cannot be disambiguated within 12 context lines get a guidance note instead of snippets. Complete diagnostic output is bounded below pi's 50 KB / 2,000-line tool-output limit. Oversized exact snippets are omitted with a line range instead of being presented as copyable text, and low-confidence or non-unique closest matches require verification before retrying.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@khanhicetea/pi-better-tool",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"description": "Better built-in tools for pi: an edit tool override that returns recovery context (closest match + disambiguation snippets) instead of bare failures",
 	"type": "module",
 	"license": "MIT",

package/src/apply.ts

@@ -77,6 +77,14 @@ export interface FuzzyFindResult {
 
 export type AnalyzeResult = { ok: true; analysis: EditAnalysis } | { ok: false; failure: EditFailure };
 
+export interface AnalyzeOptions {
+	/**
+	 * Exact offsets chosen for otherwise-ambiguous edits. Offsets are accepted
+	 * only when they point at the literal oldText in the matching base.
+	 */
+	ambiguousSelections?: ReadonlyMap<number, number>;
+}
+
 export function normalizeEdits(edits: EditOp[]): EditOp[] {
 	return edits.map((edit) => ({
 		oldText: normalizeToLF(edit.oldText),
@@ -124,10 +132,13 @@ function rangeOf(spans: LineSpan[], matchIndex: number, matchLength: number): Li
 	};
 }
 
-export function analyzeEdits(normalizedContent: string, rawEdits: EditOp[]): AnalyzeResult {
+export function analyzeEdits(normalizedContent: string, rawEdits: EditOp[], options: AnalyzeOptions = {}): AnalyzeResult {
 	const edits = normalizeEdits(rawEdits);
 	for (let i = 0; i < edits.length; i++) {
-		if (edits[i].oldText.length === 0) {
+		// Fuzzy normalization can erase whitespace-only needles. Allowing an
+		// empty normalized needle makes String#indexOf match at offset zero and
+		// turns an intended replacement into an insertion.
+		if (edits[i].oldText.length === 0 || normalizeForFuzzyMatch(edits[i].oldText).length === 0) {
 			return { ok: false, failure: { kind: "empty-old-text", editIndex: i } };
 		}
 	}
@@ -146,17 +157,31 @@ export function analyzeEdits(normalizedContent: string, rawEdits: EditOp[]): Ana
 			return { ok: false, failure: { kind: "not-found", editIndex: i } };
 		}
 		const occurrences = countFuzzyOccurrences(fuzzyBase, edit.oldText);
+		let selectedMatch = matchResult;
 		if (occurrences > 1) {
 			const occurrenceOffsets = findAllOccurrences(fuzzyBase, normalizeForFuzzyMatch(edit.oldText));
-			return {
-				ok: false,
-			failure: { kind: "ambiguous", editIndex: i, occurrenceOffsets },
+			const selectedOffset = options.ambiguousSelections?.get(i);
+			if (
+				selectedOffset === undefined ||
+				base.slice(selectedOffset, selectedOffset + edit.oldText.length) !== edit.oldText
+			) {
+				return {
+					ok: false,
+					failure: { kind: "ambiguous", editIndex: i, occurrenceOffsets },
+				};
+			}
+			selectedMatch = {
+				found: true,
+				index: selectedOffset,
+				matchLength: edit.oldText.length,
+				usedFuzzyMatch: false,
+				contentForReplacement: base,
 			};
 		}
 		replacements.push({
 			editIndex: i,
-			matchIndex: matchResult.index,
-			matchLength: matchResult.matchLength,
+			matchIndex: selectedMatch.index,
+			matchLength: selectedMatch.matchLength,
 			newText: edit.newText,
 		});
 	}

package/src/diagnostics.ts

@@ -11,14 +11,17 @@
  *   a per-line comparison, and the exact file bytes to retry with
  */
 
+import { formatSize, truncateHead } from "@earendil-works/pi-coding-agent";
 import type { EditFailure, EditOp, LineRange } from "./apply.ts";
 import { normalizeEdits } from "./apply.ts";
 import { findClosestRegion, lineSimilarity, probeMatchCauses } from "./similarity.ts";
 import {
 	countFuzzyOccurrences,
+	findAllOccurrences,
 	getLineSpans,
 	lineAt,
 	normalizeForFuzzyMatch,
+	normalizeToLF,
 	type LineSpan,
 } from "./text.ts";
 
@@ -30,8 +33,14 @@ const MAX_TOTAL_CONTEXT_LINES = 12;
 const MAX_LISTED_OCCURRENCES = 8;
 /** Occurrences that get a ready-to-use disambiguation snippet. */
 const MAX_SNIPPET_OCCURRENCES = 3;
-/** Max lines shown inside a snippet. */
+/** Max lines/bytes shown inside a copyable snippet. */
 const MAX_SNIPPET_LINES = 60;
+const MAX_SNIPPET_BYTES = 12 * 1024;
+/** Hard model-context bound for the complete tool error. */
+const MAX_OUTPUT_LINES = 1_500;
+const MAX_OUTPUT_BYTES = 48 * 1024;
+/** Minimum score at which a unique closest region may be suggested directly. */
+const MIN_DIRECT_RETRY_SCORE = 0.75;
 /** Max non-equal alignment ops rendered. */
 const MAX_DIFF_OPS_SHOWN = 12;
 
@@ -46,6 +55,13 @@ export interface Expansion {
 	endLine: number;
 }
 
+export interface AutoDisambiguation {
+	editIndex: number;
+	oldText: string;
+	chosenRange: LineRange;
+	readRange: LineRange;
+}
+
 export interface FormatFailureOptions {
 	path: string;
 	/** LF-normalized, BOM-stripped file content. */
@@ -55,7 +71,65 @@ export interface FormatFailureOptions {
 	failure: EditFailure;
 }
 
+const MAX_SUCCESS_RESOLUTIONS = 4;
+const MAX_REMAINING_OCCURRENCES = 4;
+const MAX_SUCCESS_SNIPPET_BYTES = 2_500;
+
+/** Add verified read-based selections and retryable remaining candidates to a successful edit result. */
+export function formatAutoDisambiguationSuccess(
+	baseMessage: string,
+	newContent: string,
+	resolutions: AutoDisambiguation[],
+): string {
+	if (resolutions.length === 0) return baseMessage;
+	const lines = [baseMessage, ""];
+	const shownResolutions = resolutions.slice(0, MAX_SUCCESS_RESOLUTIONS);
+
+	for (const resolution of shownResolutions) {
+		lines.push(
+			`Auto-disambiguated edits[${resolution.editIndex}] to ${describeLines(resolution.chosenRange.start, resolution.chosenRange.end)} because it was the only occurrence fully contained in the latest verified read of ${describeLines(resolution.readRange.start, resolution.readRange.end)}.`,
+		);
+		const oldText = normalizeToLF(resolution.oldText);
+		const offsets = findAllOccurrences(newContent, oldText);
+		if (offsets.length === 0) {
+			lines.push("No exact occurrences of the original oldText remain after this edit.", "");
+			continue;
+		}
+
+		lines.push(`Remaining exact occurrences of the original oldText (${Math.min(offsets.length, MAX_REMAINING_OCCURRENCES)} shown${offsets.length > MAX_REMAINING_OCCURRENCES ? `, ${offsets.length - MAX_REMAINING_OCCURRENCES} more omitted` : ""}):`);
+		const fuzzyContent = normalizeForFuzzyMatch(newContent);
+		const spans = getLineSpans(newContent);
+		for (const [index, offset] of offsets.slice(0, MAX_REMAINING_OCCURRENCES).entries()) {
+			const range = rangeFromOffset(spans, offset, oldText.length);
+			const expansion = findMinimalUniqueExpansion(newContent, fuzzyContent, spans, range);
+			if (!expansion) {
+				lines.push(`  ${index + 1}. ${describeLines(range.start, range.end)} — no unique prefix/suffix found within ${MAX_TOTAL_CONTEXT_LINES} context lines.`);
+				continue;
+			}
+			const where = `effective context: ${plural(expansion.prefixLines, "line")} before, ${plural(expansion.suffixLines, "line")} after`;
+			if (!isSnippetRenderable(expansion.text) || Buffer.byteLength(expansion.text, "utf8") > MAX_SUCCESS_SNIPPET_BYTES) {
+				lines.push(`  ${index + 1}. ${describeLines(range.start, range.end)} — ${where}; snippet omitted, read lines ${expansion.startLine}-${expansion.endLine}.`);
+				continue;
+			}
+			lines.push(`  ${index + 1}. ${describeLines(range.start, range.end)} — ${where}:`);
+			lines.push(...renderSnippet(expansion.text));
+		}
+		lines.push("Use one fenced snippet byte-for-byte as oldText if you want to edit another occurrence.", "");
+	}
+	if (resolutions.length > shownResolutions.length) {
+		lines.push(`${resolutions.length - shownResolutions.length} more auto-disambiguated edits were applied; details omitted.`);
+	}
+	return lines.join("\n").trimEnd();
+}
+
 export function formatEditFailure(opts: FormatFailureOptions): string {
+	const message = formatEditFailureUnbounded(opts);
+	const bounded = truncateHead(message, { maxBytes: MAX_OUTPUT_BYTES, maxLines: MAX_OUTPUT_LINES });
+	if (!bounded.truncated) return message;
+	return `${bounded.content}\n\n[Diagnostic output truncated to ${formatSize(bounded.outputBytes)} / ${bounded.outputLines} lines. Any incomplete snippet is not retryable; read the referenced range first.]`;
+}
+
+function formatEditFailureUnbounded(opts: FormatFailureOptions): string {
 	const { path, normalizedContent, edits, failure } = opts;
 	const total = edits.length;
 
@@ -129,11 +203,12 @@ function formatAmbiguous(opts: FormatFailureOptions, failure: Extract<EditFailur
 	lines.push("");
 
 	lines.push(
-		"Retry with a disambiguated oldText: pick ONE occurrence below and reuse its snippet exactly. Each snippet already includes the minimum surrounding context that makes it unique:",
+		"Disambiguated oldText candidates are shown below when they fit safely. A fenced snippet can be reused exactly; an omitted snippet must be read from its referenced range first:",
 	);
 
 	let shown = 0;
 	let missingExpansionNote = false;
+	let omittedSnippet = false;
 	for (let i = 0; i < listed.length && shown < MAX_SNIPPET_OCCURRENCES; i++) {
 		const offset = listed[i];
 		const range = rangeFromOffset(fuzzySpans, offset, fuzzyOld.length);
@@ -142,11 +217,18 @@ function formatAmbiguous(opts: FormatFailureOptions, failure: Extract<EditFailur
 			missingExpansionNote = true;
 			continue;
 		}
-		shown++;
 		const where = `minimum context: ${plural(expansion.prefixLines, "line")} before, ${plural(expansion.suffixLines, "line")} after`;
 		lines.push("");
+		if (!isSnippetRenderable(expansion.text)) {
+			omittedSnippet = true;
+			lines.push(
+				`Occurrence ${i + 1} (${describeLines(range.start, range.end)}) — ${where}. Exact unique snippet omitted because it exceeds the safe output limit; read lines ${expansion.startLine}-${expansion.endLine}.`,
+			);
+			continue;
+		}
+		shown++;
 		lines.push(`Occurrence ${i + 1} (${describeLines(range.start, range.end)}) — ${where}:`);
-		lines.push(...renderSnippet(expansion.text, `lines ${expansion.startLine}-${expansion.endLine}`));
+		lines.push(...renderSnippet(expansion.text));
 	}
 
 	if (missingExpansionNote) {
@@ -155,12 +237,12 @@ function formatAmbiguous(opts: FormatFailureOptions, failure: Extract<EditFailur
 			`Some occurrences could not be auto-disambiguated within ${MAX_TOTAL_CONTEXT_LINES} context lines (likely near-identical repeated blocks). Extend oldText manually with distinguishing lines from the occurrences listed above.`,
 		);
 	}
-	if (shown === 0 && !missingExpansionNote) {
+	if (shown === 0 && !missingExpansionNote && !omittedSnippet) {
 		lines.push("", "Extend oldText with more surrounding lines until it matches exactly one location.");
 	}
 	lines.push("");
 	lines.push(
-		"Tip: use the snippet byte-for-byte as the new oldText, and make newText the snippet with your change applied (the snippet may span whole lines).",
+		"Tip: only fenced snippets above are byte-for-byte retryable. Make newText from the chosen snippet with your intended change applied.",
 	);
 	return lines.join("\n");
 }
@@ -290,12 +372,34 @@ function formatNotFound(opts: FormatFailureOptions, oldText: string): string {
 			}
 		}
 		lines.push("");
-		lines.push(
-			`Exact file content at ${describeLines(closest.startLine, closest.endLine)} — retry using this text as oldText (then apply your change to newText):`,
-		);
-		lines.push(...snippetFromLines(normalizedContent, closest.startLine, closest.endLine));
+		const candidate = textFromLines(normalizedContent, closest.startLine, closest.endLine);
+		const uniqueCandidate = verifyUniqueSnippet(normalizeForFuzzyMatch(normalizedContent), candidate);
+		const safelyRenderable = isSnippetRenderable(uniqueCandidate ?? candidate);
+		const directRetry =
+			!closest.truncated &&
+			closest.score >= MIN_DIRECT_RETRY_SCORE &&
+			uniqueCandidate !== null &&
+			safelyRenderable;
+		if (directRetry) {
+			lines.push(
+				`Exact file content at ${describeLines(closest.startLine, closest.endLine)} (unique under edit matching) — retry using this text as oldText (then apply your change to newText):`,
+			);
+			lines.push(...renderSnippet(uniqueCandidate));
+		} else {
+			const reasons = [
+				closest.truncated ? "only part of oldText was compared" : undefined,
+				closest.score < MIN_DIRECT_RETRY_SCORE ? "similarity confidence is too low" : undefined,
+				uniqueCandidate === null ? "the candidate is not unique under edit matching" : undefined,
+				!safelyRenderable ? "the exact candidate exceeds the safe output limit" : undefined,
+			].filter((reason): reason is string => reason !== undefined);
+			lines.push(
+				`Candidate file content at ${describeLines(closest.startLine, closest.endLine)} is not safe for a direct retry (${reasons.join("; ")}). Read and verify this range before editing.`,
+			);
+			if (safelyRenderable) lines.push(...renderSnippet(uniqueCandidate ?? candidate));
+		}
+
 	} else {
-		lines.push("No similar region was found in the file (best similarity below threshold).");
+		lines.push("No reliable similar region was found within the bounded diagnostic search.");
 		lines.push("If you expected this text to exist, read the file around the expected location and retry.");
 	}
 
@@ -316,29 +420,22 @@ function truncateLine(line: string): string {
 // Snippet rendering
 // ---------------------------------------------------------------------------
 
-function snippetFromLines(content: string, startLine: number, endLine: number): string[] {
+function textFromLines(content: string, startLine: number, endLine: number): string {
 	const spans = getLineSpans(content);
-	const raw = content.slice(spans[startLine - 1].start, spans[endLine - 1].end);
-	const text = raw.endsWith("\n") ? raw.slice(0, -1) : raw;
-	return renderSnippet(text, `lines ${startLine}-${endLine}`);
+	return content.slice(spans[startLine - 1].start, spans[endLine - 1].end);
 }
 
-function renderSnippet(text: string, where: string): string[] {
-	const fence = fenceFor(text);
-	const allLines = text.split("\n");
-	if (allLines.length <= MAX_SNIPPET_LINES) {
-		return [fence, text, fence];
+function isSnippetRenderable(text: string): boolean {
+	return text.split("\n").length <= MAX_SNIPPET_LINES && Buffer.byteLength(text, "utf8") <= MAX_SNIPPET_BYTES;
+}
+
+/** Render only complete snippets. Callers must check isSnippetRenderable first. */
+function renderSnippet(text: string): string[] {
+	if (!isSnippetRenderable(text)) {
+		return ["[Exact snippet omitted because it exceeds the safe output limit; read the referenced range first.]" ];
 	}
-	const head = allLines.slice(0, MAX_SNIPPET_LINES - 10);
-	const tail = allLines.slice(-10);
-	const skipped = allLines.length - head.length - tail.length;
-	return [
-		fence,
-		...head,
-		`… (${skipped} middle lines snipped — see ${where}; re-read that range if you need the full text)`,
-		...tail,
-		fence,
-	];
+	const fence = fenceFor(text);
+	return [fence, text, fence];
 }
 
 /** Choose a fence longer than any backtick run inside the snippet. */

package/src/index.ts

@@ -2,10 +2,9 @@
  * pi-better-tool — better built-in tools for the pi coding agent.
  *
  * Currently ships one override:
- * - `edit` — identical matching semantics to the built-in edit tool, but
- *   failures return recovery context (closest matching region, per-occurrence
- *   minimal disambiguation snippets) so the agent can retry immediately
- *   without re-reading the file.
+ * - `edit` — built-in-compatible exact replacement with richer recovery
+ *   context and conservative read-based resolution when a recent verified
+ *   read contains exactly one of several literal occurrences.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -13,9 +12,15 @@ import { registerBetterEditTool } from "./tool.ts";
 
 export { registerBetterEditTool, executeBetterEdit, prepareEditArguments, betterEditSchema } from "./tool.ts";
 export type { BetterEditInput } from "./tool.ts";
-export { formatEditFailure, findMinimalUniqueExpansion, fenceFor } from "./diagnostics.ts";
+export {
+	formatAutoDisambiguationSuccess,
+	formatEditFailure,
+	findMinimalUniqueExpansion,
+	fenceFor,
+} from "./diagnostics.ts";
+export type { AutoDisambiguation } from "./diagnostics.ts";
 export { analyzeEdits, applyAnalysis } from "./apply.ts";
-export type { EditFailure, EditOp, EditAnalysis } from "./apply.ts";
+export type { AnalyzeOptions, EditFailure, EditOp, EditAnalysis } from "./apply.ts";
 
 export default function (pi: ExtensionAPI) {
 	registerBetterEditTool(pi);

package/src/read-evidence.ts

@@ -0,0 +1,150 @@
+import {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	formatSize,
+	truncateHead,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { normalizeToLF } from "./text.ts";
+
+export interface ReadEvidence {
+	/** 0-based, end-exclusive offsets in LF-normalized, BOM-stripped content. */
+	startOffset: number;
+	endOffset: number;
+	/** 1-based inclusive range actually shown to the model. */
+	startLine: number;
+	endLine: number;
+}
+
+interface ReadCall {
+	path: string;
+	offset?: number;
+	limit?: number;
+}
+
+interface StoredToolResult {
+	toolCallId: string;
+	toolName: string;
+	isError: boolean;
+	content: Array<{ type: string; text?: string }>;
+}
+
+/**
+ * Find the newest successful read of targetPath still present in the active
+ * model context. The returned range is accepted only when the stored tool
+ * output exactly matches what the built-in read tool would produce from the
+ * current file bytes. This makes stale or custom read output fail closed.
+ */
+export async function findLatestReadEvidence(
+	sessionManager: Pick<ExtensionContext["sessionManager"], "buildContextEntries"> | undefined,
+	targetPath: string,
+	normalizedContent: string,
+	resolvePath: (path: string) => Promise<string>,
+): Promise<ReadEvidence | null> {
+	if (!sessionManager) return null;
+	const entries = sessionManager.buildContextEntries();
+	const calls = new Map<string, ReadCall>();
+
+	for (const entry of entries) {
+		if (entry.type !== "message" || entry.message.role !== "assistant") continue;
+		for (const item of entry.message.content) {
+			if (item.type !== "toolCall" || item.name !== "read") continue;
+			const args = item.arguments as Record<string, unknown>;
+			if (typeof args.path !== "string") continue;
+			calls.set(item.id, {
+				path: args.path,
+				offset: typeof args.offset === "number" ? args.offset : undefined,
+				limit: typeof args.limit === "number" ? args.limit : undefined,
+			});
+		}
+	}
+
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		if (entry.type !== "message" || entry.message.role !== "toolResult") continue;
+		const result = entry.message as StoredToolResult;
+		if (result.toolName !== "read" || result.isError) continue;
+		const call = calls.get(result.toolCallId);
+		if (!call) continue;
+
+		let readPath: string;
+		try {
+			readPath = await resolvePath(call.path);
+		} catch {
+			continue;
+		}
+		if (readPath !== targetPath) continue;
+
+		// This is the latest successful read of this file. If it cannot be
+		// verified, do not silently fall back to older, potentially stale intent.
+		return evidenceFromBuiltinRead(normalizedContent, call, result.content);
+	}
+	return null;
+}
+
+function evidenceFromBuiltinRead(
+	content: string,
+	call: ReadCall,
+	blocks: Array<{ type: string; text?: string }>,
+): ReadEvidence | null {
+	if (blocks.length !== 1 || blocks[0].type !== "text" || typeof blocks[0].text !== "string") return null;
+	if (call.offset !== undefined && (!Number.isInteger(call.offset) || call.offset < 1)) return null;
+	if (call.limit !== undefined && (!Number.isInteger(call.limit) || call.limit < 1)) return null;
+	const actualOutput = normalizeToLF(blocks[0].text);
+	const allLines = content.split("\n");
+	const startIndex = call.offset ? Math.max(0, call.offset - 1) : 0;
+	if (startIndex >= allLines.length) return null;
+
+	let selectedContent: string;
+	let userLimitedLines: number | undefined;
+	if (call.limit !== undefined) {
+		const endIndex = Math.min(startIndex + call.limit, allLines.length);
+		selectedContent = allLines.slice(startIndex, endIndex).join("\n");
+		userLimitedLines = endIndex - startIndex;
+	} else {
+		selectedContent = allLines.slice(startIndex).join("\n");
+	}
+
+	const truncation = truncateHead(selectedContent);
+	if (truncation.firstLineExceedsLimit) return null;
+
+	let expectedOutput = truncation.content;
+	let visibleLines = truncation.outputLines;
+	if (truncation.truncated) {
+		const startLine = startIndex + 1;
+		const endLine = startLine + truncation.outputLines - 1;
+		const nextOffset = endLine + 1;
+		if (truncation.truncatedBy === "lines") {
+			expectedOutput += `\n\n[Showing lines ${startLine}-${endLine} of ${allLines.length}. Use offset=${nextOffset} to continue.]`;
+		} else {
+			expectedOutput += `\n\n[Showing lines ${startLine}-${endLine} of ${allLines.length} (${formatSize(DEFAULT_MAX_BYTES)} limit). Use offset=${nextOffset} to continue.]`;
+		}
+	} else if (userLimitedLines !== undefined && startIndex + userLimitedLines < allLines.length) {
+		const remaining = allLines.length - (startIndex + userLimitedLines);
+		const nextOffset = startIndex + userLimitedLines + 1;
+		expectedOutput += `\n\n[${remaining} more lines in file. Use offset=${nextOffset} to continue.]`;
+		visibleLines = userLimitedLines;
+	}
+
+	if (actualOutput !== expectedOutput || visibleLines <= 0 || visibleLines > DEFAULT_MAX_LINES) return null;
+
+	const startLine = startIndex + 1;
+	const endLine = startLine + visibleLines - 1;
+	const startOffset = offsetAtLine(content, startLine);
+	const endOffset = offsetAtLine(content, endLine + 1);
+	return { startOffset, endOffset, startLine, endLine };
+}
+
+/** Offset of a 1-based line; the line after EOF maps to content.length. */
+function offsetAtLine(content: string, line: number): number {
+	if (line <= 1) return 0;
+	let currentLine = 1;
+	let offset = 0;
+	while (currentLine < line) {
+		const newline = content.indexOf("\n", offset);
+		if (newline === -1) return content.length;
+		offset = newline + 1;
+		currentLine++;
+	}
+	return offset;
+}

package/src/similarity.ts

@@ -1,7 +1,6 @@
 /**
- * Fuzzy line similarity used to locate the region of the file that a failed
- * oldText *almost* matched, so the tool can show the model the actual bytes
- * instead of forcing a full re-read.
+ * Bounded fuzzy line similarity used to locate the region of a file that a
+ * failed oldText almost matched.
  */
 
 import { toFuzzyLines } from "./text.ts";
@@ -19,7 +18,7 @@ export interface AlignOp {
 export interface ClosestRegion {
 	startLine: number;
 	endLine: number;
-	/** 0..1 mean line similarity. */
+	/** 0..1 order-preserving, one-to-one line similarity. */
 	score: number;
 	ops: AlignOp[];
 	equalCount: number;
@@ -28,146 +27,151 @@ export interface ClosestRegion {
 	truncated: boolean;
 }
 
+interface PreparedLine {
+	text: string;
+	grams: Map<string, number>;
+	gramCount: number;
+}
+
+function prepareLine(text: string): PreparedLine {
+	const grams = new Map<string, number>();
+	for (let i = 0; i + 1 < text.length; i++) {
+		const gram = text.slice(i, i + 2);
+		grams.set(gram, (grams.get(gram) ?? 0) + 1);
+	}
+	return { text, grams, gramCount: Math.max(0, text.length - 1) };
+}
+
 /** Dice coefficient over character bigrams; 1.0 for identical strings. */
 export function lineSimilarity(a: string, b: string): number {
-	if (a === b) return 1;
-	if (a.length < 2 || b.length < 2) return 0;
-	const gramsA = bigramCounts(a);
-	const gramsB = bigramCounts(b);
-	let overlap = 0;
-	let total = 0;
-	for (const count of gramsA.values()) total += count;
-	for (const count of gramsB.values()) total += count;
-	for (const [gram, countA] of gramsA) {
-		const countB = gramsB.get(gram);
-		if (countB) overlap += Math.min(countA, countB);
-	}
-	return (2 * overlap) / total;
+	return preparedSimilarity(prepareLine(a), prepareLine(b));
 }
 
-function bigramCounts(s: string): Map<string, number> {
-	const counts = new Map<string, number>();
-	for (let i = 0; i + 1 < s.length; i++) {
-		const gram = s.slice(i, i + 2);
-		counts.set(gram, (counts.get(gram) ?? 0) + 1);
+function preparedSimilarity(a: PreparedLine, b: PreparedLine): number {
+	if (a.text === b.text) return 1;
+	if (a.gramCount === 0 || b.gramCount === 0) return 0;
+	const [small, large] = a.grams.size <= b.grams.size ? [a.grams, b.grams] : [b.grams, a.grams];
+	let overlap = 0;
+	for (const [gram, count] of small) {
+		const other = large.get(gram);
+		if (other) overlap += Math.min(count, other);
 	}
-	return counts;
+	return (2 * overlap) / (a.gramCount + b.gramCount);
 }
 
 const MAX_COMPARE_LINES = 300;
-const PREFILTER_FILE_LINES = 2000;
+const MAX_SEARCH_FILE_LINES = 10_000;
+const MAX_CANDIDATE_WINDOWS = 24;
 const MIN_SCORE = 0.3;
 const MATCH_THRESHOLD = 0.75;
 
+interface CandidateWindow {
+	start: number;
+	size: number;
+	positionalScore: number;
+}
+
 /**
  * Find the window of file lines most similar to oldText.
- * Compares window sizes of len-1, len, len+1 so a single extra/missing line
- * still lands the search on the right region.
+ *
+ * The first pass ranks every window using cheap positional similarity. Only a
+ * small bounded set of candidates receives the more expensive sequence score.
+ * The sequence score is order-preserving and one-to-one, so repeated query
+ * lines cannot all claim the same file line.
  */
 export function findClosestRegion(content: string, oldText: string): ClosestRegion | null {
 	const allQLines = toFuzzyLines(oldText);
 	const cLines = toFuzzyLines(content);
-	if (allQLines.length === 0 || cLines.length === 0) return null;
+	if (allQLines.length === 0 || cLines.length === 0 || cLines.length > MAX_SEARCH_FILE_LINES) return null;
 
 	const truncated = allQLines.length > MAX_COMPARE_LINES;
 	const q = truncated ? allQLines.slice(0, MAX_COMPARE_LINES) : allQLines;
 	const L = q.length;
-
-	const sizes = [...new Set([L - 1, L, L + 1].filter((s) => s >= 1 && s <= cLines.length))];
-	const bigFile = cLines.length > PREFILTER_FILE_LINES;
-
-	let bestScore = -1;
-	let bestStart = -1;
-	let bestSize = L;
-
-	for (const w of sizes) {
-		for (let s = 0; s + w <= cLines.length; s++) {
-			if (bigFile && !prefilter(cLines, q, s, w, L)) continue;
-			const score = scoreWindow(cLines, q, s, w, L);
-			if (score > bestScore) {
-				bestScore = score;
-				bestStart = s;
-				bestSize = w;
+	const sizes = [...new Set([L - 1, L, L + 1].filter((size) => size >= 1 && size <= cLines.length))];
+	const preparedQ = q.map(prepareLine);
+	const preparedContent = cLines.map(prepareLine);
+	const candidates: CandidateWindow[] = [];
+
+	for (const size of sizes) {
+		for (let start = 0; start + size <= cLines.length; start++) {
+			const pairs = Math.min(L, size);
+			let sum = 0;
+			for (let i = 0; i < pairs; i++) {
+				sum += preparedSimilarity(preparedQ[i], preparedContent[start + i]);
 			}
+			keepCandidate(candidates, { start, size, positionalScore: sum / Math.max(L, size) });
 		}
 	}
 
-	if (bestStart < 0 || bestScore < MIN_SCORE) return null;
+	let bestScore = -1;
+	let best: CandidateWindow | undefined;
+	for (const candidate of candidates) {
+		const window = preparedContent.slice(candidate.start, candidate.start + candidate.size);
+		const score = sequenceSimilarity(preparedQ, window);
+		if (score > bestScore || (score === bestScore && candidate.positionalScore > (best?.positionalScore ?? -1))) {
+			bestScore = score;
+			best = candidate;
+		}
+	}
+	if (!best || bestScore < MIN_SCORE) return null;
 
-	const windowLines = cLines.slice(bestStart, bestStart + bestSize);
-	const ops = alignLines(q, windowLines, bestStart);
-	const equalCount = ops.filter((op) => op.type === "equal").length;
+	const windowLines = cLines.slice(best.start, best.start + best.size);
+	const ops = alignLines(q, windowLines, best.start);
 	return {
-		startLine: bestStart + 1,
-		endLine: bestStart + bestSize,
+		startLine: best.start + 1,
+		endLine: best.start + best.size,
 		score: bestScore,
 		ops,
-		equalCount,
+		equalCount: ops.filter((op) => op.type === "equal").length,
 		totalOldLines: L,
 		truncated,
 	};
 }
 
-function scoreWindow(cLines: string[], q: string[], start: number, w: number, L: number): number {
-	// Positional score: strict index-by-index pairing (handles indentation /
-	// trailing-whitespace drift).
-	const pairs = Math.min(L, w);
-	let positionalSum = 0;
-	for (let i = 0; i < pairs; i++) {
-		positionalSum += lineSimilarity(q[i], cLines[start + i]);
-	}
-	const positional = positionalSum / Math.max(L, w);
-
-	// Bag score: best match per oldText line anywhere in the window (handles a
-	// single inserted/removed line in the middle that breaks positional pairing).
-	let bagSum = 0;
-	for (let i = 0; i < L; i++) {
-		let best = 0;
-		for (let j = start; j < start + w; j++) {
-			const sim = lineSimilarity(q[i], cLines[j]);
-			if (sim > best) best = sim;
-			if (best === 1) break;
-		}
-		bagSum += best;
+function keepCandidate(candidates: CandidateWindow[], candidate: CandidateWindow): void {
+	if (candidates.length < MAX_CANDIDATE_WINDOWS) {
+		candidates.push(candidate);
+		candidates.sort((a, b) => a.positionalScore - b.positionalScore);
+		return;
 	}
-	return Math.max(positional, (bagSum / L) * 0.95);
+	if (candidate.positionalScore <= candidates[0].positionalScore) return;
+	candidates[0] = candidate;
+	candidates.sort((a, b) => a.positionalScore - b.positionalScore);
 }
 
-function prefilter(cLines: string[], q: string[], s: number, w: number, L: number): boolean {
-	const mid = Math.floor(L / 2);
-	const probes: Array<[number, number]> = [
-		[s, 0],
-		[s, L - 1],
-		[s, mid],
-		[s + w - 1, L - 1],
-		[s + w - 1, 0],
-		[s + w - 1, mid],
-		[s + Math.floor(w / 2), mid],
-	];
-	for (const [ci, qi] of probes) {
-		if (ci >= 0 && ci < cLines.length && qi >= 0 && qi < L) {
-			if (lineSimilarity(cLines[ci], q[qi]) >= 0.45) return true;
+/** Weighted LCS: lines are matched at most once and in source order. */
+function sequenceSimilarity(query: PreparedLine[], window: PreparedLine[]): number {
+	let previous = new Float64Array(window.length + 1);
+	for (let i = 1; i <= query.length; i++) {
+		const current = new Float64Array(window.length + 1);
+		for (let j = 1; j <= window.length; j++) {
+			const matched = previous[j - 1] + preparedSimilarity(query[i - 1], window[j - 1]);
+			current[j] = Math.max(previous[j], current[j - 1], matched);
 		}
+		previous = current;
 	}
-	return false;
+	return previous[window.length] / Math.max(query.length, window.length);
 }
 
 /**
- * LCS-style alignment between oldText lines and the best window.
- * Lines with similarity >= MATCH_THRESHOLD count as equal; adjacent
- * old-only/file-only runs are merged into "changed" pairs.
+ * LCS-style alignment between oldText lines and the best window. Lines with
+ * similarity >= MATCH_THRESHOLD count as equal; adjacent insert/delete pairs
+ * are merged into changed operations for compact diagnostics.
  */
 function alignLines(q: string[], w: string[], wOffset: number): AlignOp[] {
 	const n = q.length;
 	const m = w.length;
+	const preparedQ = q.map(prepareLine);
+	const preparedW = w.map(prepareLine);
+	const similarities = Array.from({ length: n }, (_, i) =>
+		Array.from({ length: m }, (_, j) => preparedSimilarity(preparedQ[i], preparedW[j])),
+	);
 	const dp: number[][] = Array.from({ length: n + 1 }, () => new Array<number>(m + 1).fill(0));
 	for (let i = n - 1; i >= 0; i--) {
 		for (let j = m - 1; j >= 0; j--) {
-			if (lineSimilarity(q[i], w[j]) >= MATCH_THRESHOLD) {
-				dp[i][j] = dp[i + 1][j + 1] + 1;
-			} else {
-				dp[i][j] = Math.max(dp[i + 1][j], dp[i][j + 1]);
-			}
+			dp[i][j] = similarities[i][j] >= MATCH_THRESHOLD
+				? dp[i + 1][j + 1] + 1
+				: Math.max(dp[i + 1][j], dp[i][j + 1]);
 		}
 	}
 
@@ -175,54 +179,32 @@ function alignLines(q: string[], w: string[], wOffset: number): AlignOp[] {
 	let i = 0;
 	let j = 0;
 	while (i < n && j < m) {
-		if (lineSimilarity(q[i], w[j]) >= MATCH_THRESHOLD) {
+		if (similarities[i][j] >= MATCH_THRESHOLD) {
 			raw.push({ type: "equal", fileLine: wOffset + j + 1, fileText: w[j], oldLine: i + 1, oldText: q[i] });
 			i++;
 			j++;
 		} else if (dp[i + 1][j] > dp[i][j + 1]) {
-			// Strictly better to skip the oldText line; on ties prefer skipping
-			// the file line so inserted file lines surface as file-only ops.
-			raw.push({ type: "old-only", oldLine: i + 1, oldText: q[i] });
-			i++;
+			raw.push({ type: "old-only", oldLine: i + 1, oldText: q[i++] });
 		} else {
-			raw.push({ type: "file-only", fileLine: wOffset + j + 1, fileText: w[j] });
-			j++;
+			raw.push({ type: "file-only", fileLine: wOffset + j + 1, fileText: w[j++] });
 		}
 	}
-	while (i < n) {
-		raw.push({ type: "old-only", oldLine: i + 1, oldText: q[i] });
-		i++;
-	}
-	while (j < m) {
-		raw.push({ type: "file-only", fileLine: wOffset + j + 1, fileText: w[j] });
-		j++;
-	}
+	while (i < n) raw.push({ type: "old-only", oldLine: i + 1, oldText: q[i++] });
+	while (j < m) raw.push({ type: "file-only", fileLine: wOffset + j + 1, fileText: w[j++] });
 
-	// Merge adjacent old-only/file-only runs into pairwise "changed" ops.
 	const merged: AlignOp[] = [];
 	for (let k = 0; k < raw.length; k++) {
 		const op = raw[k];
-		if (op.type === "old-only") {
-			const next = raw[k + 1];
-			if (next && next.type === "file-only") {
-				merged.push({ type: "changed", fileLine: next.fileLine, fileText: next.fileText, oldLine: op.oldLine, oldText: op.oldText });
-				k++;
-				continue;
-			}
-			merged.push(op);
-			continue;
-		}
-		if (op.type === "file-only") {
-			const next = raw[k + 1];
-			if (next && next.type === "old-only") {
-				merged.push({ type: "changed", fileLine: op.fileLine, fileText: op.fileText, oldLine: next.oldLine, oldText: next.oldText });
-				k++;
-				continue;
-			}
+		const next = raw[k + 1];
+		if (op.type === "old-only" && next?.type === "file-only") {
+			merged.push({ type: "changed", fileLine: next.fileLine, fileText: next.fileText, oldLine: op.oldLine, oldText: op.oldText });
+			k++;
+		} else if (op.type === "file-only" && next?.type === "old-only") {
+			merged.push({ type: "changed", fileLine: op.fileLine, fileText: op.fileText, oldLine: next.oldLine, oldText: next.oldText });
+			k++;
+		} else {
 			merged.push(op);
-			continue;
 		}
-		merged.push(op);
 	}
 	return merged;
 }
@@ -230,20 +212,15 @@ function alignLines(q: string[], w: string[], wOffset: number): AlignOp[] {
 /** Cheap probes for common causes of a failed match. */
 export function probeMatchCauses(content: string, oldText: string): string[] {
 	const causes: string[] = [];
-	const stripWS = (s: string) => s.replace(/\s+/g, "");
+	const stripWS = (value: string) => value.replace(/\s+/g, "");
 	if (stripWS(content).includes(stripWS(oldText))) {
-		causes.push(
-			"whitespace mismatch: the text matches when ALL whitespace is removed — check tabs vs spaces and indentation width",
-		);
+		causes.push("whitespace mismatch: the text matches when ALL whitespace is removed — check tabs vs spaces and indentation width");
 	} else if (content.toLowerCase().includes(oldText.toLowerCase())) {
 		causes.push("letter-case mismatch: the text matches case-insensitively");
 	}
 	const fileHasTabs = content.includes("\t");
 	const oldHasTabs = oldText.includes("\t");
-	if (fileHasTabs && !oldHasTabs) {
-		causes.push("the file contains tab characters but your oldText uses spaces");
-	} else if (!fileHasTabs && oldHasTabs) {
-		causes.push("your oldText contains tab characters but the file uses spaces");
-	}
+	if (fileHasTabs && !oldHasTabs) causes.push("the file contains tab characters but your oldText uses spaces");
+	else if (!fileHasTabs && oldHasTabs) causes.push("your oldText contains tab characters but the file uses spaces");
 	return causes;
 }

package/src/tool.ts

@@ -7,8 +7,9 @@
  * not find edits[1]" error that forces the model to re-read the file and
  * guess at larger context, failures include recovery context:
  *
- * - ambiguous oldText → occurrence line numbers + the minimal prefix/suffix
- *   context that disambiguates each occurrence, as copy-paste-ready snippets
+ * - ambiguous literal oldText → if the latest verified read of the file shows
+ *   exactly one occurrence, select it and report up to four retryable remaining
+ *   candidates; otherwise return occurrence line numbers + minimal context
  * - not-found oldText → closest matching region with a per-line comparison
  *   and the exact file bytes to retry with
  */
@@ -22,13 +23,27 @@ import {
 	type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { constants } from "node:fs";
-import { access as fsAccess, readFile as fsReadFile, writeFile as fsWriteFile } from "node:fs/promises";
+import { access as fsAccess, readFile as fsReadFile, realpath as fsRealpath, writeFile as fsWriteFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { type Static, Type } from "typebox";
-import { analyzeEdits, applyAnalysis, type EditOp } from "./apply.ts";
-import { formatEditFailure } from "./diagnostics.ts";
-import { detectLineEnding, normalizeToLF, restoreLineEndings, splitBom } from "./text.ts";
+import { analyzeEdits, applyAnalysis, fuzzyFindText, normalizeEdits, type EditOp } from "./apply.ts";
+import {
+	formatAutoDisambiguationSuccess,
+	formatEditFailure,
+	type AutoDisambiguation,
+} from "./diagnostics.ts";
+import { findLatestReadEvidence } from "./read-evidence.ts";
+import {
+	detectLineEnding,
+	findAllOccurrences,
+	getLineSpans,
+	lineAt,
+	normalizeToLF,
+	restoreLineEndings,
+	splitBom,
+} from "./text.ts";
 
 const replaceEditSchema = Type.Object({
 	oldText: Type.String({
@@ -48,14 +63,29 @@ export const betterEditSchema = Type.Object({
 
 export type BetterEditInput = Static<typeof betterEditSchema>;
 
-function resolveToCwd(filePath: string, cwd: string): string {
-	let path = filePath;
-	if (path === "~") {
-		path = homedir();
-	} else if (path.startsWith("~/")) {
-		path = resolve(homedir(), path.slice(2));
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+
+/** Match pi's built-in path normalization for tool arguments. */
+function normalizeToolPath(input: string): string {
+	let path = input.replace(UNICODE_SPACES, " ");
+	if (path.startsWith("@")) path = path.slice(1);
+
+	if (process.platform === "win32" && path.startsWith("/") && !path.startsWith("//") && !path.includes("\\")) {
+		const match = path.match(/^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i);
+		if (match) path = `${match[1].toUpperCase()}:\\${match[2]?.replaceAll("/", "\\") ?? ""}`;
 	}
-	return resolve(cwd, path);
+
+	if (path === "~") return homedir();
+	if (path.startsWith("~/") || (process.platform === "win32" && path.startsWith("~\\"))) {
+		return join(homedir(), path.slice(2));
+	}
+	if (/^file:\/\//.test(path)) return fileURLToPath(path);
+	return path;
+}
+
+function resolveToCwd(filePath: string, cwd: string): string {
+	const path = normalizeToolPath(filePath);
+	return isAbsolute(path) ? resolve(path) : resolve(cwd, path);
 }
 
 function isSingleEditInput(value: unknown): value is { oldText: string; newText: string } {
@@ -114,7 +144,7 @@ export interface BetterEditSuccess {
 export async function executeBetterEdit(
 	input: BetterEditInput,
 	signal: AbortSignal | undefined,
-	ctx: Pick<ExtensionContext, "cwd">,
+	ctx: Pick<ExtensionContext, "cwd"> & Partial<Pick<ExtensionContext, "sessionManager">>,
 ): Promise<BetterEditSuccess> {
 	const edits: EditOp[] = input.edits ?? [];
 	if (!Array.isArray(edits) || edits.length === 0) {
@@ -150,7 +180,56 @@ export async function executeBetterEdit(
 		const originalEnding = detectLineEnding(content);
 		const normalizedContent = normalizeToLF(content);
 
-		const result = analyzeEdits(normalizedContent, edits);
+		const selections = new Map<number, number>();
+		const resolutions: AutoDisambiguation[] = [];
+		let result = analyzeEdits(normalizedContent, edits, { ambiguousSelections: selections });
+		let readEvidence: Awaited<ReturnType<typeof findLatestReadEvidence>> | undefined;
+		const normalizedEdits = normalizeEdits(edits);
+		const exactBase = normalizedEdits.every(
+			(edit) => !fuzzyFindText(normalizedContent, edit.oldText).usedFuzzyMatch,
+		);
+
+		while (!result.ok && result.failure.kind === "ambiguous" && exactBase) {
+			const editIndex = result.failure.editIndex;
+			if (selections.has(editIndex)) break;
+			const edit = normalizedEdits[editIndex];
+			const exactOffsets = findAllOccurrences(normalizedContent, edit.oldText);
+			// Fuzzy-equivalent aliases cannot be mapped safely to original offsets.
+			if (exactOffsets.length !== result.failure.occurrenceOffsets.length) break;
+
+			if (readEvidence === undefined) {
+				const canonicalTarget = await fsRealpath(absolutePath);
+				readEvidence = await findLatestReadEvidence(
+					ctx.sessionManager,
+					canonicalTarget,
+					normalizedContent,
+					async (readPath) => fsRealpath(resolveToCwd(readPath, ctx.cwd)),
+				);
+			}
+			if (!readEvidence) break;
+
+			const candidates = exactOffsets.filter(
+				(offset) =>
+					offset >= readEvidence!.startOffset &&
+					offset + edit.oldText.length <= readEvidence!.endOffset,
+			);
+			if (candidates.length !== 1) break;
+
+			const selectedOffset = candidates[0];
+			const spans = getLineSpans(normalizedContent);
+			selections.set(editIndex, selectedOffset);
+			resolutions.push({
+				editIndex,
+				oldText: edit.oldText,
+				chosenRange: {
+					start: lineAt(spans, selectedOffset) + 1,
+					end: lineAt(spans, selectedOffset + Math.max(1, edit.oldText.length) - 1) + 1,
+				},
+				readRange: { start: readEvidence.startLine, end: readEvidence.endLine },
+			});
+			result = analyzeEdits(normalizedContent, edits, { ambiguousSelections: selections });
+		}
+
 		if (!result.ok) {
 			throw new Error(
 				formatEditFailure({
@@ -185,7 +264,11 @@ export async function executeBetterEdit(
 			content: [
 				{
 					type: "text",
-					text: `Successfully replaced ${edits.length} block(s) in ${input.path}.`,
+					text: formatAutoDisambiguationSuccess(
+						`Successfully replaced ${edits.length} block(s) in ${input.path}.`,
+						newContent,
+						resolutions,
+					),
 				},
 			],
 			details: {
@@ -202,7 +285,7 @@ export function registerBetterEditTool(pi: ExtensionAPI): void {
 		name: "edit",
 		label: "edit",
 		description:
-			"Edit a single file using exact text replacement. Every edits[].oldText must match a unique, non-overlapping region of the original file. If two changes affect the same block or nearby lines, merge them into one edit instead of emitting overlapping edits. Do not include large unchanged regions just to connect distant changes. On failure the error includes recovery context (closest matching region or per-occurrence disambiguation snippets) so you can retry immediately without re-reading the file.",
+			"Edit a single file using exact text replacement. Every edits[].oldText should match a unique, non-overlapping region of the original file. When literal text is repeated, edit may safely select it only if exactly one occurrence was fully shown by the latest verified read of that file; the success result then includes up to four remaining disambiguated candidates. If two changes affect the same block or nearby lines, merge them into one edit instead of emitting overlapping edits. Do not include large unchanged regions just to connect distant changes. On failure the error includes recovery context (closest matching region or per-occurrence disambiguation snippets) so you can retry immediately without re-reading the file.",
 		promptSnippet:
 			"Make precise file edits with exact text replacement; failures return recovery context (closest match or disambiguation snippets)",
 		promptGuidelines: [
@@ -210,6 +293,7 @@ export function registerBetterEditTool(pi: ExtensionAPI): void {
 			"When changing multiple separate locations in one file, use one edit call with multiple entries in edits[] instead of multiple edit calls",
 			"Each edits[].oldText is matched against the original file, not after earlier edits are applied. Do not emit overlapping or nested edits. Merge nearby changes into one edit.",
 			"Keep edits[].oldText as small as possible while still being unique in the file. Do not pad with large unchanged regions.",
+			"When edit safely auto-disambiguates repeated text from the latest verified read, its success message lists up to four remaining occurrences with effective prefix/suffix context for an optional follow-up edit.",
 			"When an edit call fails, the error message already contains recovery context: the closest matching region with exact file bytes (not-found) or each occurrence with a ready-to-use disambiguated oldText (ambiguous match). Retry the edit using that text directly instead of re-reading the file.",
 		],
 		parameters: betterEditSchema,