@oh-my-pi/pi-coding-agent 6.8.0 → 6.8.2

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [6.8.2] - 2026-01-21
+
+### Fixed
+
+- Improved error messages when multiple text occurrences are found by showing line previews and context
+- Enhanced patch application to better handle duplicate content in context lines
+- Added occurrence previews to help users disambiguate between multiple matches
+- Fixed cache invalidation for streaming edits to prevent stale data
+- Fixed file existence check for prompt templates directory
+- Fixed bash output streaming to prevent premature stream closure
+- Fixed LSP client request handling when signal is already aborted
+- Fixed git apply operations with stdin input handling
+
+### Security
+
+- Updated Anthropic authentication to handle manual code input securely
+
+## [6.8.1] - 2026-01-20
+
+### Fixed
+
+- Fixed unhandled promise rejection when tool execution fails by adding missing `.catch()` to floating `.finally()` chain in `createAbortablePromise`
+
 ## [6.8.0] - 2026-01-20
 
 ### Added

package/examples/extensions/plan-mode.ts

@@ -247,16 +247,16 @@ export default function planModeExtension(pi: ExtensionAPI) {
 		}
 	}
 
-	function togglePlanMode(ctx: ExtensionContext) {
+	async function togglePlanMode(ctx: ExtensionContext) {
 		planModeEnabled = !planModeEnabled;
 		executionMode = false;
 		todoItems = [];
 
 		if (planModeEnabled) {
-			pi.setActiveTools(PLAN_MODE_TOOLS);
+			await pi.setActiveTools(PLAN_MODE_TOOLS);
 			ctx.ui.notify(`Plan mode enabled. Tools: ${PLAN_MODE_TOOLS.join(", ")}`);
 		} else {
-			pi.setActiveTools(NORMAL_MODE_TOOLS);
+			await pi.setActiveTools(NORMAL_MODE_TOOLS);
 			ctx.ui.notify("Plan mode disabled. Full access restored.");
 		}
 		updateStatus(ctx);
@@ -266,7 +266,7 @@ export default function planModeExtension(pi: ExtensionAPI) {
 	pi.registerCommand("plan", {
 		description: "Toggle plan mode (read-only exploration)",
 		handler: async (_args, ctx) => {
-			togglePlanMode(ctx);
+			await togglePlanMode(ctx);
 		},
 	});
 
@@ -294,7 +294,7 @@ export default function planModeExtension(pi: ExtensionAPI) {
 	pi.registerShortcut(Key.shift("p"), {
 		description: "Toggle plan mode",
 		handler: async (ctx) => {
-			togglePlanMode(ctx);
+			await togglePlanMode(ctx);
 		},
 	});
 
@@ -417,7 +417,7 @@ Execute each step in order.`,
 
 				executionMode = false;
 				todoItems = [];
-				pi.setActiveTools(NORMAL_MODE_TOOLS);
+				await pi.setActiveTools(NORMAL_MODE_TOOLS);
 				updateStatus(ctx);
 			}
 			return;
@@ -470,7 +470,7 @@ Execute each step in order.`,
 		if (choice?.startsWith("Execute")) {
 			planModeEnabled = false;
 			executionMode = hasTodos;
-			pi.setActiveTools(NORMAL_MODE_TOOLS);
+			await pi.setActiveTools(NORMAL_MODE_TOOLS);
 			updateStatus(ctx);
 
 			// Simple execution message - context event filters old plan mode messages
@@ -519,7 +519,7 @@ Execute each step in order.`,
 		}
 
 		if (planModeEnabled) {
-			pi.setActiveTools(PLAN_MODE_TOOLS);
+			await pi.setActiveTools(PLAN_MODE_TOOLS);
 		}
 		updateStatus(ctx);
 	});

package/examples/extensions/tools.ts

@@ -31,12 +31,12 @@ export default function toolsExtension(pi: ExtensionAPI) {
 	}
 
 	// Apply current tool selection
-	function applyTools() {
-		pi.setActiveTools(Array.from(enabledTools));
+	async function applyTools() {
+		await pi.setActiveTools(Array.from(enabledTools));
 	}
 
 	// Find the last tools-config entry in the current branch
-	function restoreFromBranch(ctx: ExtensionContext) {
+	async function restoreFromBranch(ctx: ExtensionContext) {
 		allTools = pi.getAllTools();
 
 		// Get entries in current branch only
@@ -55,7 +55,7 @@ export default function toolsExtension(pi: ExtensionAPI) {
 		if (savedTools) {
 			// Restore saved tool selection (filter to only tools that still exist)
 			enabledTools = new Set(savedTools.filter((t: string) => allTools.includes(t)));
-			applyTools();
+			await applyTools();
 		} else {
 			// No saved state - sync with currently active tools
 			enabledTools = new Set(pi.getActiveTools());
@@ -130,16 +130,16 @@ export default function toolsExtension(pi: ExtensionAPI) {
 
 	// Restore state on session start
 	pi.on("session_start", async (_event, ctx) => {
-		restoreFromBranch(ctx);
+		await restoreFromBranch(ctx);
 	});
 
 	// Restore state when navigating the session tree
 	pi.on("session_tree", async (_event, ctx) => {
-		restoreFromBranch(ctx);
+		await restoreFromBranch(ctx);
 	});
 
 	// Restore state after branching
 	pi.on("session_branch", async (_event, ctx) => {
-		restoreFromBranch(ctx);
+		await restoreFromBranch(ctx);
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "6.8.0",
+	"version": "6.8.2",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"ompConfig": {
@@ -40,11 +40,11 @@
 		"prepublishOnly": "bun run generate-template && bun run clean && bun run build"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-agent-core": "6.8.0",
-		"@oh-my-pi/pi-ai": "6.8.0",
-		"@oh-my-pi/pi-git-tool": "6.8.0",
-		"@oh-my-pi/pi-tui": "6.8.0",
-		"@oh-my-pi/pi-utils": "6.8.0",
+		"@oh-my-pi/pi-agent-core": "6.8.2",
+		"@oh-my-pi/pi-ai": "6.8.2",
+		"@oh-my-pi/pi-git-tool": "6.8.2",
+		"@oh-my-pi/pi-tui": "6.8.2",
+		"@oh-my-pi/pi-utils": "6.8.2",
 		"@openai/agents": "^0.3.7",
 		"@sinclair/typebox": "^0.34.46",
 		"ajv": "^8.17.1",

package/src/cli/session-picker.ts

@@ -28,8 +28,11 @@ export async function selectSession(sessions: SessionInfo[]): Promise<string | n
 			}
 		},
 		() => {
-			ui.stop();
-			process.exit(0);
+			if (!resolved) {
+				resolved = true;
+				ui.stop();
+				process.exit(0);
+			}
 		},
 	);
 

package/src/core/agent-session.ts

@@ -454,15 +454,19 @@ export class AgentSession {
 			}
 
 			if (event.message.role === "toolResult") {
-				const { $normative, toolCallId } = event.message as {
+				const { toolName, $normative, toolCallId, details } = event.message as {
 					toolName?: string;
 					toolCallId?: string;
-					details?: unknown;
+					details?: { path?: string };
 					$normative?: Record<string, unknown>;
 				};
 				if ($normative && toolCallId && this.settingsManager.getNormativeRewrite()) {
 					await this._rewriteToolCallArgs(toolCallId, $normative);
 				}
+				// Invalidate streaming edit cache when edit tool completes to prevent stale data
+				if (toolName === "edit" && details?.path) {
+					this._invalidateFileCacheForPath(details.path);
+				}
 			}
 		}
 
@@ -579,11 +583,16 @@ export class AgentSession {
 				this._streamingEditFileCache.set(resolvedPath, normalizeToLF(text));
 			}
 		} catch {
-			// Ignore errors - mark as empty string so we don't retry
-			this._streamingEditFileCache.set(resolvedPath, "");
+			// Don't cache on read errors - let the edit tool handle them
 		}
 	}
 
+	/** Invalidate cache for a file after an edit completes to prevent stale data */
+	private _invalidateFileCacheForPath(path: string): void {
+		const resolvedPath = resolveToCwd(path, this.sessionManager.getCwd());
+		this._streamingEditFileCache.delete(resolvedPath);
+	}
+
 	private _maybeAbortStreamingEdit(event: AgentEvent): void {
 		if (!this.settingsManager.getEditStreamingAbort()) return;
 		if (this._streamingEditAbortTriggered) return;
@@ -2226,7 +2235,7 @@ export class AgentSession {
 								error: message,
 								model: `${candidate.provider}/${candidate.id}`,
 							});
-							await Bun.sleep(delayMs);
+							await abortableSleep(delayMs, this._autoCompactionAbortController.signal);
 						}
 					}
 
@@ -2291,6 +2300,10 @@ export class AgentSession {
 				}, 100);
 			}
 		} catch (error) {
+			if (this._autoCompactionAbortController?.signal.aborted) {
+				this._emit({ type: "auto_compaction_end", result: undefined, aborted: true, willRetry: false });
+				return;
+			}
 			const errorMessage = error instanceof Error ? error.message : "compaction failed";
 			this._emit({
 				type: "auto_compaction_end",

package/src/core/auth-storage.ts

@@ -107,10 +107,12 @@ function toBoolean(value: unknown): boolean | undefined {
 export class AuthStorage {
 	private static readonly codexUsageCacheTtlMs = 60_000; // Cache usage data for 1 minute
 	private static readonly defaultBackoffMs = 60_000; // Default backoff when no reset time available
+	private static readonly cacheCleanupIntervalMs = 300_000; // Clean expired cache every 5 minutes
 
 	/** Provider -> credentials cache, populated from agent.db on reload(). */
 	private data: Map<string, StoredCredential[]> = new Map();
 	private storage: AgentStorage;
+	private lastCacheCleanup = 0;
 	/** Resolved path to agent.db (derived from authPath or used directly if .db). */
 	private dbPath: string;
 	private runtimeOverrides: Map<string, string> = new Map();
@@ -153,6 +155,7 @@ export class AuthStorage {
 		instance.sessionLastCredential = new Map();
 		instance.credentialBackoff = new Map();
 		instance.codexUsageCache = new Map();
+		instance.lastCacheCleanup = 0;
 
 		for (const [provider, creds] of Object.entries(data.credentials)) {
 			instance.data.set(
@@ -557,7 +560,11 @@ export class AuthStorage {
 
 		switch (provider) {
 			case "anthropic":
-				credentials = await loginAnthropic(ctrl);
+				credentials = await loginAnthropic({
+					...ctrl,
+					onManualCodeInput: async () =>
+						ctrl.onPrompt({ message: "Paste the authorization code (or full redirect URL):" }),
+				});
 				break;
 			case "github-copilot":
 				credentials = await loginGitHubCopilot({
@@ -748,6 +755,11 @@ export class AuthStorage {
 		const cacheKey = this.getCodexUsageCacheKey(accountId, normalizedBase);
 		const now = Date.now();
 
+		if (now - this.lastCacheCleanup > AuthStorage.cacheCleanupIntervalMs) {
+			this.lastCacheCleanup = now;
+			this.storage.cleanExpiredCache();
+		}
+
 		// Check in-memory cache first (fastest)
 		const memCached = this.codexUsageCache.get(cacheKey);
 		if (memCached && memCached.expiresAt > now) {

package/src/core/bash-executor.ts

@@ -4,7 +4,7 @@
  * Provides unified bash execution for AgentSession.executeBash() and direct calls.
  */
 
-import { cspawn, Exception } from "@oh-my-pi/pi-utils";
+import { cspawn, Exception, ptree } from "@oh-my-pi/pi-utils";
 import { getShellConfig } from "../utils/shell";
 import { getOrCreateSnapshot, getSnapshotSourceCommand } from "../utils/shell-snapshot";
 import { OutputSink } from "./streaming-output";
@@ -34,7 +34,7 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 	const prefixedCommand = prefix ? `${prefix} ${command}` : command;
 	const finalCommand = `${snapshotPrefix}${prefixedCommand}`;
 
-	const stream = new OutputSink({ onLine: options?.onChunk });
+	const stream = new OutputSink({ onChunk: options?.onChunk });
 
 	const child = cspawn([shell, ...args, finalCommand], {
 		cwd: options?.cwd,
@@ -44,6 +44,7 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 	});
 
 	// Pump streams - errors during abort/timeout are expected
+	// Use preventClose to avoid closing the shared sink when either stream finishes
 	await Promise.allSettled([
 		child.stdout.pipeTo(stream.createWritable()),
 		child.stderr.pipeTo(stream.createWritable()),
@@ -63,7 +64,7 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 		// Exception covers NonZeroExitError, AbortError, TimeoutError
 		if (err instanceof Exception) {
 			if (err.aborted) {
-				const isTimeout = err.message.includes("timed out");
+				const isTimeout = err instanceof ptree.TimeoutError || err.message.toLowerCase().includes("timed out");
 				const annotation = isTimeout
 					? `Command timed out after ${Math.round((options?.timeout ?? 0) / 1000)} seconds`
 					: undefined;
@@ -92,7 +93,7 @@ export async function executeBashWithOperations(
 	operations: BashOperations,
 	options?: BashExecutorOptions,
 ): Promise<BashResult> {
-	const stream = new OutputSink({ onLine: options?.onChunk });
+	const stream = new OutputSink({ onChunk: options?.onChunk });
 	const writable = stream.createWritable();
 	const writer = writable.getWriter();
 

package/src/core/exec.ts

@@ -41,14 +41,16 @@ export async function execCommand(
 		signal: options?.signal,
 		timeout: options?.timeout,
 	});
+	// Read streams before awaiting exit to avoid data loss if streams close
+	const [stdoutText, stderrText] = await Promise.all([proc.stdout.text(), proc.stderr.text()]);
 	try {
 		await proc.exited;
 	} catch {
 		// ChildProcess rejects on non-zero exit; we handle it below
 	}
 	return {
-		stdout: await proc.stdout.text(),
-		stderr: await proc.stderr.text(),
+		stdout: stdoutText,
+		stderr: stderrText,
 		code: proc.exitCode ?? 0,
 		killed: proc.exitReason instanceof ptree.AbortError,
 	};

package/src/core/extensions/types.ts

@@ -757,7 +757,7 @@ export interface ExtensionAPI {
 	getAllTools(): string[];
 
 	/** Set the active tools by name. */
-	setActiveTools(toolNames: string[]): void;
+	setActiveTools(toolNames: string[]): Promise<void>;
 
 	/** Set the current model. Returns false if no API key available. */
 	setModel(model: Model<any>): Promise<boolean>;

package/src/core/hooks/types.ts

@@ -685,12 +685,13 @@ export interface HookAPI {
 	 * @param message.content - Message content (string or TextContent/ImageContent array)
 	 * @param message.display - Whether to show in TUI (true = styled display, false = hidden)
 	 * @param message.details - Optional hook-specific metadata (not sent to LLM)
-	 * @param triggerTurn - If true and agent is idle, triggers a new LLM turn. Default: false.
-	 *                      If agent is streaming, message is queued and triggerTurn is ignored.
+	 * @param options.triggerTurn - If true and agent is idle, triggers a new LLM turn. Default: false.
+	 *                              If agent is streaming, message is queued and triggerTurn is ignored.
+	 * @param options.deliverAs - How to deliver the message: "steer" or "followUp".
 	 */
 	sendMessage<T = unknown>(
 		message: Pick<HookMessage<T>, "customType" | "content" | "display" | "details">,
-		triggerTurn?: boolean,
+		options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" },
 	): void;
 
 	/**

package/src/core/mcp/transports/http.ts

@@ -5,7 +5,7 @@
  * Based on MCP spec 2025-03-26.
  */
 
-import type { JsonRpcResponse, MCPHttpServerConfig, MCPSseServerConfig, MCPTransport } from "../types";
+import type { JsonRpcMessage, JsonRpcResponse, MCPHttpServerConfig, MCPSseServerConfig, MCPTransport } from "../types";
 
 /** Generate unique request ID */
 function generateId(): string {
@@ -167,39 +167,47 @@ export class HttpTransport implements MCPTransport {
 			throw new Error("No response body");
 		}
 
-		let result: T | undefined;
+		const timeout = this.config.timeout ?? 30000;
 
-		for await (const event of readSseEvents(response.body)) {
-			const data = event.data?.trim();
-			if (!data || data === "[DONE]") continue;
-			try {
-				const message = JSON.parse(data) as JsonRpcResponse;
+		const parse = async (): Promise<T> => {
+			for await (const event of readSseEvents(response.body!)) {
+				const data = event.data?.trim();
+				if (!data || data === "[DONE]") continue;
 
-				// Handle our response
-				if ("id" in message && message.id === expectedId) {
-					if (message.error) {
-						throw new Error(`MCP error ${message.error.code}: ${message.error.message}`);
+				try {
+					const message = JSON.parse(data) as JsonRpcMessage;
+
+					if (
+						"id" in message &&
+						(message as JsonRpcResponse).id === expectedId &&
+						("result" in message || "error" in message)
+					) {
+						const response = message as JsonRpcResponse;
+						if (response.error) {
+							throw new Error(`MCP error ${response.error.code}: ${response.error.message}`);
+						}
+						return response.result as T;
+					}
+
+					if ("method" in message && !("id" in message)) {
+						this.onNotification?.(message.method, message.params);
+					}
+				} catch (error) {
+					if (error instanceof Error && error.message.startsWith("MCP error")) {
+						throw error;
 					}
-					result = message.result as T;
-				}
-				// Handle notifications
-				else if ("method" in message && !("id" in message)) {
-					const notification = message as { method: string; params?: unknown };
-					this.onNotification?.(notification.method, notification.params);
-				}
-			} catch (error) {
-				if (error instanceof Error && error.message.startsWith("MCP error")) {
-					throw error;
 				}
-				// Ignore other parse errors
 			}
-		}
 
-		if (result === undefined) {
-			throw new Error("No response received");
-		}
+			throw new Error(`No response received for request ID ${expectedId}`);
+		};
 
-		return result;
+		return Promise.race([
+			parse(),
+			new Promise<never>((_, reject) =>
+				setTimeout(() => reject(new Error(`SSE response timeout after ${timeout}ms`)), timeout),
+			),
+		]);
 	}
 
 	async notify(method: string, params?: Record<string, unknown>): Promise<void> {

package/src/core/prompt-templates.ts

@@ -432,7 +432,7 @@ async function loadTemplatesFromDir(
 			}
 		}
 	} catch (error) {
-		if (!Bun.file(dir).exists()) {
+		if (!(await Bun.file(dir).exists())) {
 			return [];
 		}
 		logger.warn("Failed to scan prompt templates directory", { dir, error: String(error) });

package/src/core/python-gateway-coordinator.ts

@@ -116,8 +116,8 @@ const DEFAULT_ENV_DENYLIST = new Set([
 const CASE_INSENSITIVE_ENV = process.platform === "win32";
 const ACTIVE_ENV_ALLOWLIST = CASE_INSENSITIVE_ENV ? WINDOWS_ENV_ALLOWLIST : DEFAULT_ENV_ALLOWLIST;
 
-const NORMALIZED_ALLOWLIST = new Set(
-	Array.from(ACTIVE_ENV_ALLOWLIST, (key) => (CASE_INSENSITIVE_ENV ? key.toUpperCase() : key)),
+const NORMALIZED_ALLOWLIST = new Map(
+	Array.from(ACTIVE_ENV_ALLOWLIST, (key) => [CASE_INSENSITIVE_ENV ? key.toUpperCase() : key, key] as const),
 );
 const NORMALIZED_DENYLIST = new Set(
 	Array.from(DEFAULT_ENV_DENYLIST, (key) => (CASE_INSENSITIVE_ENV ? key.toUpperCase() : key)),
@@ -168,8 +168,9 @@ function filterEnv(env: Record<string, string | undefined>): Record<string, stri
 		if (value === undefined) continue;
 		const normalizedKey = normalizeEnvKey(key);
 		if (NORMALIZED_DENYLIST.has(normalizedKey)) continue;
-		if (NORMALIZED_ALLOWLIST.has(normalizedKey)) {
-			filtered[key] = value;
+		const canonicalKey = NORMALIZED_ALLOWLIST.get(normalizedKey);
+		if (canonicalKey !== undefined) {
+			filtered[canonicalKey] = value;
 			continue;
 		}
 		if (NORMALIZED_ALLOW_PREFIXES.some((prefix) => normalizedKey.startsWith(prefix))) {

package/src/core/ssh/ssh-executor.ts

@@ -95,7 +95,7 @@ export async function executeSSH(
 				return {
 					exitCode: undefined,
 					cancelled: true,
-					...sink.dump(`SSH command timed out after ${Math.round(options!.timeout! / 1000)} seconds`),
+					...sink.dump(`SSH: ${err.message}`),
 				};
 			}
 			if (err.aborted) {

package/src/core/tools/lsp/client.ts

@@ -741,7 +741,7 @@ export async function sendRequest(
 		signal.addEventListener("abort", abortHandler, { once: true });
 		if (signal.aborted) {
 			abortHandler();
-			return;
+			return promise;
 		}
 	}
 

package/src/core/tools/patch/applicator.ts

@@ -92,17 +92,17 @@ function adjustLinesIndentation(patternLines: string[], actualLines: string[], n
 		}
 	}
 
-	// Build a map from trimmed content to available (pattern index, actual index) pairs
-	// This lets us find context lines and their corresponding actual content
-	const contentToIndices = new Map<string, Array<{ patternIdx: number; actualIdx: number }>>();
-	for (let i = 0; i < Math.min(patternLines.length, actualLines.length); i++) {
-		const trimmed = patternLines[i].trim();
+	// Build a map from trimmed content to actual lines (by content, not position)
+	// This handles fuzzy matches where pattern and actual may not be positionally aligned
+	const contentToActualLines = new Map<string, string[]>();
+	for (const line of actualLines) {
+		const trimmed = line.trim();
 		if (trimmed.length === 0) continue;
-		const arr = contentToIndices.get(trimmed);
+		const arr = contentToActualLines.get(trimmed);
 		if (arr) {
-			arr.push({ patternIdx: i, actualIdx: i });
+			arr.push(line);
 		} else {
-			contentToIndices.set(trimmed, [{ patternIdx: i, actualIdx: i }]);
+			contentToActualLines.set(trimmed, [line]);
 		}
 	}
 
@@ -119,8 +119,8 @@ function adjustLinesIndentation(patternLines: string[], actualLines: string[], n
 	}
 	const avgDelta = deltaCount > 0 ? Math.round(totalDelta / deltaCount) : 0;
 
-	// Track which indices we've used to handle duplicate content correctly
-	const usedIndices = new Set<number>();
+	// Track which actual lines we've used to handle duplicate content correctly
+	const usedActualLines = new Map<string, number>(); // trimmed content -> count used
 
 	return newLines.map((newLine) => {
 		if (newLine.trim().length === 0) {
@@ -128,16 +128,15 @@ function adjustLinesIndentation(patternLines: string[], actualLines: string[], n
 		}
 
 		const trimmed = newLine.trim();
-		const indices = contentToIndices.get(trimmed);
-
-		// Check if this is a context line (same trimmed content exists in pattern)
-		if (indices) {
-			for (const { patternIdx, actualIdx } of indices) {
-				if (!usedIndices.has(patternIdx)) {
-					usedIndices.add(patternIdx);
-					// Use actual file content directly for context lines
-					return actualLines[actualIdx];
-				}
+		const matchingActualLines = contentToActualLines.get(trimmed);
+
+		// Check if this is a context line (same trimmed content exists in actual)
+		if (matchingActualLines && matchingActualLines.length > 0) {
+			const usedCount = usedActualLines.get(trimmed) ?? 0;
+			if (usedCount < matchingActualLines.length) {
+				usedActualLines.set(trimmed, usedCount + 1);
+				// Use actual file content directly for context lines
+				return matchingActualLines[usedCount];
 			}
 		}
 
@@ -599,9 +598,11 @@ function applyCharacterMatch(
 
 	// Check for multiple exact occurrences
 	if (matchOutcome.occurrences && matchOutcome.occurrences > 1) {
+		const previews = matchOutcome.occurrencePreviews?.join("\n\n") ?? "";
+		const moreMsg = matchOutcome.occurrences > 5 ? ` (showing first 5 of ${matchOutcome.occurrences})` : "";
 		throw new ApplyPatchError(
-			`Found ${matchOutcome.occurrences} occurrences of the text in ${path}. ` +
-				`The text must be unique. Please provide more context to make it unique.`,
+			`Found ${matchOutcome.occurrences} occurrences in ${path}${moreMsg}:\n\n${previews}\n\n` +
+				`Add more context lines to disambiguate.`,
 		);
 	}
 
@@ -857,9 +858,22 @@ function computeReplacements(
 		if (hunk.changeContext === undefined && !hunk.hasContextLines && !hunk.isEndOfFile && lineHint === undefined) {
 			const secondMatch = seekSequence(originalLines, pattern, found + 1, false, { allowFuzzy });
 			if (secondMatch.index !== undefined) {
+				// Extract 3-line previews for each match
+				const formatPreview = (startIdx: number) => {
+					const lines = originalLines.slice(startIdx, startIdx + 3);
+					return lines
+						.map((line, i) => {
+							const num = startIdx + i + 1;
+							const truncated = line.length > 60 ? `${line.slice(0, 57)}...` : line;
+							return `  ${num} | ${truncated}`;
+						})
+						.join("\n");
+				};
+				const preview1 = formatPreview(found);
+				const preview2 = formatPreview(secondMatch.index);
 				throw new ApplyPatchError(
-					`Found 2 occurrences of the text in ${path}. ` +
-						`The text must be unique. Please provide more context to make it unique.`,
+					`Found 2 occurrences in ${path}:\n\n${preview1}\n\n${preview2}\n\n` +
+						`Add more context lines to disambiguate.`,
 				);
 			}
 		}

package/src/core/tools/patch/diff.ts

@@ -228,9 +228,11 @@ export function replaceText(content: string, oldText: string, newText: string, o
 	});
 
 	if (matchOutcome.occurrences && matchOutcome.occurrences > 1) {
+		const previews = matchOutcome.occurrencePreviews?.join("\n\n") ?? "";
+		const moreMsg = matchOutcome.occurrences > 5 ? ` (showing first 5 of ${matchOutcome.occurrences})` : "";
 		throw new Error(
-			`Found ${matchOutcome.occurrences} occurrences of the text. ` +
-				`The text must be unique. Please provide more context to make it unique, or use all: true to replace all.`,
+			`Found ${matchOutcome.occurrences} occurrences${moreMsg}:\n\n${previews}\n\n` +
+				`Add more context lines to disambiguate.`,
 		);
 	}
 
@@ -307,8 +309,10 @@ export async function computeEditDiff(
 			});
 
 			if (matchOutcome.occurrences && matchOutcome.occurrences > 1) {
+				const previews = matchOutcome.occurrencePreviews?.join("\n\n") ?? "";
+				const moreMsg = matchOutcome.occurrences > 5 ? ` (showing first 5 of ${matchOutcome.occurrences})` : "";
 				return {
-					error: `Found ${matchOutcome.occurrences} occurrences of the text in ${path}. The text must be unique. Please provide more context to make it unique, or use all: true to replace all.`,
+					error: `Found ${matchOutcome.occurrences} occurrences in ${path}${moreMsg}:\n\n${previews}\n\nAdd more context lines to disambiguate.`,
 				};
 			}