@prestyj/cli 5.29.0 → 5.30.0

package/dist/tools/edit.js

@@ -85,27 +85,48 @@ const STRINGIFIED_EDITS_ERROR = "`edits` arrived as a JSON-encoded string and co
     "Send `edits` as a real JSON array of objects, never as a string. " +
     "Re-sending the same large payload usually breaks the same way: split the work into " +
     "several `edit` calls carrying one or two smaller edits each.";
-const EditParams = z.object({
+const EditList = z
+    .preprocess(coerceStringifiedEdits, z
+    .array(EditItem, {
+    // Narrow to "an array was expected, a string arrived" so a nested
+    // string-typed mistake (`anchor: "x"`, `replace_all: "true"`) keeps
+    // its own accurate message. Any non-matching issue returns undefined
+    // and falls through to Zod's default.
+    error: (issue) => issue.code === "invalid_type" &&
+        issue.expected === "array" &&
+        typeof issue.input === "string"
+        ? STRINGIFIED_EDITS_ERROR
+        : undefined,
+})
+    .min(1))
+    .describe("One or more edits applied in order. Each edit operates on the result of the previous one.");
+// Multi-file entries take the text form only: a replay test batched all 7
+// files 8/8 times either way, and dropping the anchor/span forms here keeps
+// ~2k chars of duplicated schema out of every request.
+const TextEditItem = EditItem.pick({ old_text: true, new_text: true, replace_all: true });
+const FileEdits = z.object({
     file_path: z.string().describe("The file path to edit"),
     edits: z
-        .preprocess(coerceStringifiedEdits, z
-        .array(EditItem, {
-        // Narrow to "an array was expected, a string arrived" so a nested
-        // string-typed mistake (`anchor: "x"`, `replace_all: "true"`) keeps
-        // its own accurate message. Any non-matching issue returns undefined
-        // and falls through to Zod's default.
-        error: (issue) => issue.code === "invalid_type" &&
-            issue.expected === "array" &&
-            typeof issue.input === "string"
-            ? STRINGIFIED_EDITS_ERROR
-            : undefined,
-    })
-        .min(1))
-        .describe("One or more edits applied in order. Each edit operates on the result of the previous one."),
+        .preprocess(coerceStringifiedEdits, z.array(TextEditItem).min(1))
+        .describe("Text-form edits for this file, applied in order."),
+});
+// `files` lets one call cover a multi-file change. Measured on gpt-6-astra
+// (replay of a 7-file refactor at the point where every file had been read):
+// with it the model sent all 7 files in one call 8/8 times; without it 5/8
+// responses carried every edit and the rest fell back to one file per turn.
+const EditParams = z.object({
+    file_path: z.string().optional().describe("The file path to edit (single-file form)"),
+    edits: EditList.optional(),
+    files: z
+        .array(FileEdits)
+        .min(1)
+        .optional()
+        .describe("Several files in ONE call: one entry per file, each with text-form edits (old_text/new_text). " +
+        "Use instead of file_path/edits when a change spans files."),
     atomic: z
         .boolean()
         .optional()
-        .describe("If true, fail the whole batch when any edit fails — no changes written. " +
+        .describe("If true, fail a file's whole batch when any of its edits fails — that file is left unchanged. " +
         "Default false: partial-apply, keep every successful edit and report failures " +
         "for retry. Use atomic only when later edits depend on earlier ones in a way " +
         "where a half-applied state would be worse than nothing."),
@@ -175,10 +196,11 @@ export function createEditTool(cwd, readFiles, ops = localOperations, planModeRe
             "text edits then run on the result.\n" +
             "Partial-apply by default: failed edits are listed for retry, successful ones are still written — " +
             "re-issue ONLY the listed failures, not the whole batch. " +
-            "Returns a unified diff.",
+            "Returns a unified diff.\n" +
+            "Multi-file: pass `files` (one {file_path, edits} entry per file) to change several files in a single call.",
         parameters: EditParams,
         executionMode: "sequential",
-        async execute({ file_path, edits, atomic = false }) {
+        async execute({ file_path, edits, files, atomic = false }) {
             const goalMode = getActiveGoalMode(goalModeRef);
             if (goalMode !== "off") {
                 return goalModeMutationRestriction("edit", goalMode);
@@ -186,333 +208,385 @@ export function createEditTool(cwd, readFiles, ops = localOperations, planModeRe
             if (isPlanModeActive(planModeRef)) {
                 return planModeRestriction("edit");
             }
-            const resolved = resolvePath(cwd, file_path);
-            await rejectSymlink(resolved);
-            // Workspace write guard: outside cwd/tmp/~/.ezcoder requires user approval.
-            const guard = resolveWriteGuard(cwd, resolved, getWriteGuardSettings?.());
-            if (!guard.allowed) {
-                return `Error: ${guard.reason}`;
-            }
-            // No prior read is required: every old_text, span and anchor is matched
-            // against the live content below, which proves the model knows the text
-            // it replaces (it may have seen it via `cat`, or changed the file itself
-            // with a script). A read that no longer matches disk is forgotten, so the
-            // file counts as unread again: the edit still validates against live
-            // content, but a later full-file `write` needs a fresh read.
-            if (readFiles?.has(resolved) && !(await isFresh(readFiles, resolved, ops))) {
-                readFiles.delete(resolved);
+            const targets = resolveEditTargets(file_path, edits, files);
+            if (!targets.ok)
+                throw new Error(targets.error);
+            if (targets.value.length === 1) {
+                const only = targets.value[0];
+                return editOneFile(only.file_path, only.edits, atomic);
             }
-            const original = await ops.readFile(resolved);
-            const hasCRLF = original.includes("\r\n");
-            const originalNormalized = hasCRLF ? original.replace(/\r\n/g, "\n") : original;
-            // Anchors pin lines in the file AS READ, so they always verify against the
-            // original (pre-edit) line array — earlier edits in the batch don't shift
-            // what an anchor refers to.
-            const originalLines = originalNormalized.split("\n");
-            const fileName = path.basename(resolved);
-            const outcomes = new Array(edits.length);
-            // ── Phase 1: span-form edits (hash-anchored replacement). Spans resolve
-            // against the file AS READ and apply bottom-up so indices stay valid.
-            // Text-form edits then run on the result in phase 2.
-            const isSpanForm = (e) => e.span !== undefined || e.lines !== undefined;
-            const spanResolved = [];
-            for (let i = 0; i < edits.length; i++) {
-                const e = edits[i];
-                if (!isSpanForm(e)) {
-                    if (e.old_text === undefined || e.new_text === undefined) {
-                        outcomes[i] = {
-                            ok: false,
-                            failure: {
-                                reason: "invalid",
-                                detail: "provide either old_text+new_text, or span+lines — this edit has neither",
-                            },
-                        };
-                    }
-                    continue;
+            // Files apply in order, each independently: one file's failure never
+            // rolls back another, and the result says exactly which to re-issue.
+            const parts = [];
+            const diffs = [];
+            let failed = 0;
+            for (const target of targets.value) {
+                try {
+                    const result = await editOneFile(target.file_path, target.edits, atomic);
+                    const content = typeof result === "string" ? result : result.content;
+                    if (typeof result !== "string" && result.details.diff)
+                        diffs.push(result.details.diff);
+                    if (typeof result === "string" && result.startsWith("Error:"))
+                        failed++;
+                    parts.push(`### ${target.file_path}\n${content}`);
+                }
+                catch (error) {
+                    failed++;
+                    parts.push(`### ${target.file_path}\nFAILED — ${error instanceof Error ? error.message : String(error)}`);
                 }
-                if (!e.span || !e.lines || e.old_text !== undefined || e.new_text !== undefined) {
+            }
+            const total = targets.value.length;
+            if (failed === total)
+                throw new Error(`All ${total} files failed; no changes written.\n\n${parts.join("\n\n")}`);
+            const header = failed === 0
+                ? `Edited ${total} files.`
+                : `Edited ${total - failed} of ${total} files. ${failed} failed — re-issue ONLY the failed files (the rest are already done).`;
+            return { content: `${header}\n\n${parts.join("\n\n")}`, details: { diff: diffs.join("\n") } };
+        },
+    };
+    async function editOneFile(file_path, edits, atomic) {
+        const resolved = resolvePath(cwd, file_path);
+        await rejectSymlink(resolved);
+        // Workspace write guard: outside cwd/tmp/~/.ezcoder requires user approval.
+        const guard = resolveWriteGuard(cwd, resolved, getWriteGuardSettings?.());
+        if (!guard.allowed) {
+            return `Error: ${guard.reason}`;
+        }
+        // No prior read is required: every old_text, span and anchor is matched
+        // against the live content below, which proves the model knows the text
+        // it replaces (it may have seen it via `cat`, or changed the file itself
+        // with a script). A read that no longer matches disk is forgotten, so the
+        // file counts as unread again: the edit still validates against live
+        // content, but a later full-file `write` needs a fresh read.
+        if (readFiles?.has(resolved) && !(await isFresh(readFiles, resolved, ops))) {
+            readFiles.delete(resolved);
+        }
+        const original = await ops.readFile(resolved);
+        const hasCRLF = original.includes("\r\n");
+        const originalNormalized = hasCRLF ? original.replace(/\r\n/g, "\n") : original;
+        // Anchors pin lines in the file AS READ, so they always verify against the
+        // original (pre-edit) line array — earlier edits in the batch don't shift
+        // what an anchor refers to.
+        const originalLines = originalNormalized.split("\n");
+        const fileName = path.basename(resolved);
+        const outcomes = new Array(edits.length);
+        // ── Phase 1: span-form edits (hash-anchored replacement). Spans resolve
+        // against the file AS READ and apply bottom-up so indices stay valid.
+        // Text-form edits then run on the result in phase 2.
+        const isSpanForm = (e) => e.span !== undefined || e.lines !== undefined;
+        const spanResolved = [];
+        for (let i = 0; i < edits.length; i++) {
+            const e = edits[i];
+            if (!isSpanForm(e)) {
+                if (e.old_text === undefined || e.new_text === undefined) {
                     outcomes[i] = {
                         ok: false,
                         failure: {
                             reason: "invalid",
-                            detail: "span form requires BOTH span and lines, and must not mix with old_text/new_text",
+                            detail: "provide either old_text+new_text, or span+lines — this edit has neither",
                         },
                     };
-                    continue;
                 }
-                const res = resolveAnchoredEdit(originalLines, e.span);
+                continue;
+            }
+            if (!e.span || !e.lines || e.old_text !== undefined || e.new_text !== undefined) {
+                outcomes[i] = {
+                    ok: false,
+                    failure: {
+                        reason: "invalid",
+                        detail: "span form requires BOTH span and lines, and must not mix with old_text/new_text",
+                    },
+                };
+                continue;
+            }
+            const res = resolveAnchoredEdit(originalLines, e.span);
+            if (!res.ok) {
+                outcomes[i] = { ok: false, failure: { reason: "stale_anchor" } };
+                continue;
+            }
+            spanResolved.push({ index: i, start: res.startIndex, end: res.endIndex, lines: e.lines });
+        }
+        // Reject overlapping spans (keep the first, fail the rest) — overlap means
+        // the model double-addressed the same region and the result is undefined.
+        spanResolved.sort((a, b) => a.start - b.start || a.index - b.index);
+        const spanApplied = [];
+        let lastEnd = -1;
+        for (const s of spanResolved) {
+            if (s.start <= lastEnd) {
+                outcomes[s.index] = { ok: false, failure: { reason: "overlap" } };
+                continue;
+            }
+            spanApplied.push(s);
+            lastEnd = s.end;
+        }
+        const workingLines = [...originalLines];
+        for (let i = spanApplied.length - 1; i >= 0; i--) {
+            const s = spanApplied[i];
+            workingLines.splice(s.start, s.end - s.start + 1, ...s.lines);
+            outcomes[s.index] = { ok: true, source: "span" };
+        }
+        let working = workingLines.join("\n");
+        // ── Phase 2: text-form edits, sequential on the working buffer.
+        for (let i = 0; i < edits.length; i++) {
+            if (outcomes[i] !== undefined)
+                continue; // span-form or invalid, already settled
+            const { old_text, new_text, replace_all, anchor } = edits[i];
+            if (old_text === undefined || new_text === undefined)
+                continue; // settled above
+            // Optional staleness guard (opt-in). Runs BEFORE the fuzzy match ladder:
+            // if the model supplied an anchor and the file drifted since it read it,
+            // reject this edit instead of risking a misplaced fuzzy match. The fuzzy
+            // path below is byte-identical to today when `anchor` is absent.
+            if (anchor) {
+                const res = resolveAnchoredEdit(originalLines, anchor);
                 if (!res.ok) {
                     outcomes[i] = { ok: false, failure: { reason: "stale_anchor" } };
                     continue;
                 }
-                spanResolved.push({ index: i, start: res.startIndex, end: res.endIndex, lines: e.lines });
             }
-            // Reject overlapping spans (keep the first, fail the rest) — overlap means
-            // the model double-addressed the same region and the result is undefined.
-            spanResolved.sort((a, b) => a.start - b.start || a.index - b.index);
-            const spanApplied = [];
-            let lastEnd = -1;
-            for (const s of spanResolved) {
-                if (s.start <= lastEnd) {
-                    outcomes[s.index] = { ok: false, failure: { reason: "overlap" } };
-                    continue;
-                }
-                spanApplied.push(s);
-                lastEnd = s.end;
+            const normalizedOld = hasCRLF ? old_text.replace(/\r\n/g, "\n") : old_text;
+            const normalizedNew = hasCRLF ? new_text.replace(/\r\n/g, "\n") : new_text;
+            const replaceAll = replace_all ?? false;
+            // Identical replacements are explicit no-op successes. They should not
+            // block atomic batches that contain real edits, and all-no-op batches
+            // should report success without writing.
+            if (normalizedOld === normalizedNew) {
+                outcomes[i] = { ok: true };
+                continue;
             }
-            const workingLines = [...originalLines];
-            for (let i = spanApplied.length - 1; i >= 0; i--) {
-                const s = spanApplied[i];
-                workingLines.splice(s.start, s.end - s.start + 1, ...s.lines);
-                outcomes[s.index] = { ok: true, source: "span" };
+            if (normalizedOld.length === 0 ||
+                (!working.includes(normalizedOld) && normalizeForFuzzyMatch(normalizedOld).length === 0)) {
+                outcomes[i] = {
+                    ok: false,
+                    failure: {
+                        reason: "invalid",
+                        detail: "old_text is empty after normalization; provide visible surrounding context.",
+                    },
+                };
+                continue;
             }
-            let working = workingLines.join("\n");
-            // ── Phase 2: text-form edits, sequential on the working buffer.
-            for (let i = 0; i < edits.length; i++) {
-                if (outcomes[i] !== undefined)
-                    continue; // span-form or invalid, already settled
-                const { old_text, new_text, replace_all, anchor } = edits[i];
-                if (old_text === undefined || new_text === undefined)
-                    continue; // settled above
-                // Optional staleness guard (opt-in). Runs BEFORE the fuzzy match ladder:
-                // if the model supplied an anchor and the file drifted since it read it,
-                // reject this edit instead of risking a misplaced fuzzy match. The fuzzy
-                // path below is byte-identical to today when `anchor` is absent.
-                if (anchor) {
-                    const res = resolveAnchoredEdit(originalLines, anchor);
-                    if (!res.ok) {
-                        outcomes[i] = { ok: false, failure: { reason: "stale_anchor" } };
-                        continue;
-                    }
+            // Aider's full fallback ladder, run only when the primary match
+            // returns "not_found". Ambiguous matches deliberately don't fall
+            // through — the model needs to add context, not paraphrase further.
+            // Order mirrors aider/coders/editblock_coder.py:
+            //   1. exact + smart-quote/dash fuzzy (in tryMatch)
+            //   2. indent-flex (model omitted/shortened leading whitespace)
+            //   3. drop spurious leading/trailing blank lines, retry 1+2
+            //   4. dotdotdots (`...` elision with preserved middle)
+            let source = "text";
+            let result = tryMatch(working, normalizedOld, normalizedNew, replaceAll);
+            const tryFallbacks = (oldText) => {
+                const flexed = applyMissingLeadingWhitespace(working, oldText, normalizedNew);
+                if (flexed !== null)
+                    return flexed;
+                // Re-run primary matcher on the stripped variant as a cheap retry.
+                const exact = tryMatch(working, oldText, normalizedNew, replaceAll);
+                if (exact.ok)
+                    return exact.newWorking;
+                return null;
+            };
+            if (!result.ok && result.reason === "not_found") {
+                const indentFlexed = applyMissingLeadingWhitespace(working, normalizedOld, normalizedNew);
+                if (indentFlexed !== null) {
+                    result = { ok: true, newWorking: indentFlexed };
+                    source = "indent_flex";
                 }
-                const normalizedOld = hasCRLF ? old_text.replace(/\r\n/g, "\n") : old_text;
-                const normalizedNew = hasCRLF ? new_text.replace(/\r\n/g, "\n") : new_text;
-                const replaceAll = replace_all ?? false;
-                // Identical replacements are explicit no-op successes. They should not
-                // block atomic batches that contain real edits, and all-no-op batches
-                // should report success without writing.
-                if (normalizedOld === normalizedNew) {
-                    outcomes[i] = { ok: true };
-                    continue;
+            }
+            if (!result.ok && result.reason === "not_found") {
+                const stripped = stripBlankEdges(normalizedOld);
+                if (stripped !== null) {
+                    const candidate = tryFallbacks(stripped);
+                    if (candidate !== null) {
+                        result = { ok: true, newWorking: candidate };
+                        source = "blank_edges";
+                    }
                 }
-                if (normalizedOld.length === 0 ||
-                    (!working.includes(normalizedOld) && normalizeForFuzzyMatch(normalizedOld).length === 0)) {
+            }
+            if (!result.ok && result.reason === "not_found") {
+                if (replaceAll && /^[ \t]*\.\.\.[ \t]*$/m.test(normalizedOld)) {
                     outcomes[i] = {
                         ok: false,
                         failure: {
                             reason: "invalid",
-                            detail: "old_text is empty after normalization; provide visible surrounding context.",
+                            detail: "replace_all does not support ... elision; use complete matching text or separate uniquely anchored edits.",
                         },
                     };
                     continue;
                 }
-                // Aider's full fallback ladder, run only when the primary match
-                // returns "not_found". Ambiguous matches deliberately don't fall
-                // through — the model needs to add context, not paraphrase further.
-                // Order mirrors aider/coders/editblock_coder.py:
-                //   1. exact + smart-quote/dash fuzzy (in tryMatch)
-                //   2. indent-flex (model omitted/shortened leading whitespace)
-                //   3. drop spurious leading/trailing blank lines, retry 1+2
-                //   4. dotdotdots (`...` elision with preserved middle)
-                let source = "text";
-                let result = tryMatch(working, normalizedOld, normalizedNew, replaceAll);
-                const tryFallbacks = (oldText) => {
-                    const flexed = applyMissingLeadingWhitespace(working, oldText, normalizedNew);
-                    if (flexed !== null)
-                        return flexed;
-                    // Re-run primary matcher on the stripped variant as a cheap retry.
-                    const exact = tryMatch(working, oldText, normalizedNew, replaceAll);
-                    if (exact.ok)
-                        return exact.newWorking;
-                    return null;
-                };
-                if (!result.ok && result.reason === "not_found") {
-                    const indentFlexed = applyMissingLeadingWhitespace(working, normalizedOld, normalizedNew);
-                    if (indentFlexed !== null) {
-                        result = { ok: true, newWorking: indentFlexed };
-                        source = "indent_flex";
-                    }
-                }
-                if (!result.ok && result.reason === "not_found") {
-                    const stripped = stripBlankEdges(normalizedOld);
-                    if (stripped !== null) {
-                        const candidate = tryFallbacks(stripped);
-                        if (candidate !== null) {
-                            result = { ok: true, newWorking: candidate };
-                            source = "blank_edges";
-                        }
-                    }
-                }
-                if (!result.ok && result.reason === "not_found") {
-                    if (replaceAll && /^[ \t]*\.\.\.[ \t]*$/m.test(normalizedOld)) {
-                        outcomes[i] = {
-                            ok: false,
-                            failure: {
-                                reason: "invalid",
-                                detail: "replace_all does not support ... elision; use complete matching text or separate uniquely anchored edits.",
-                            },
-                        };
-                        continue;
-                    }
-                    const elided = applyDotdotdots(working, normalizedOld, normalizedNew);
-                    if (elided !== null) {
-                        result = { ok: true, newWorking: elided };
-                        source = "dotdotdot";
-                    }
-                }
-                if (result.ok) {
-                    working = result.newWorking;
-                    outcomes[i] = { ok: true, source };
-                    continue;
-                }
-                if (result.reason === "not_found") {
-                    // Capture the closest-match snippet eagerly against the current
-                    // working buffer; we'll decide whether to render it post-loop based
-                    // on whether other edits in this batch succeeded.
-                    const closest = findClosestSnippet(working, normalizedOld);
-                    outcomes[i] = {
-                        ok: false,
-                        failure: {
-                            reason: "not_found",
-                            closestSnippet: closest?.snippet ?? null,
-                            closestLine: closest?.topLine ?? null,
-                            redactedHint: redactedOldTextHint(normalizedOld),
-                        },
-                    };
-                }
-                else {
-                    const occurrences = result.occurrences ?? 0;
-                    const matches = findOccurrenceLines(working, normalizedOld);
-                    const matchLines = matches.map((m) => `  line ${m.line}: ${m.preview}`).join("\n");
-                    const more = occurrences > matches.length ? `\n  …and ${occurrences - matches.length} more` : "";
-                    outcomes[i] = {
-                        ok: false,
-                        failure: { reason: "ambiguous", occurrences, matchLines, more },
-                    };
+                const elided = applyDotdotdots(working, normalizedOld, normalizedNew);
+                if (elided !== null) {
+                    result = { ok: true, newWorking: elided };
+                    source = "dotdotdot";
                 }
             }
-            const failures = outcomes
-                .map((o, i) => (o.ok || !o.failure ? null : { index: i, failure: o.failure }))
-                .filter((x) => x !== null);
-            const successCount = outcomes.length - failures.length;
-            // Closest-match snippets only get suppressed when successes will ACTUALLY
-            // be persisted (partial-apply with at least one win). In atomic mode we
-            // throw before writing, so the model retries against an unchanged file
-            // and the snippet is its only guidance — keep it.
-            const willPersistSuccesses = successCount > 0 && !atomic;
-            const formatFailureMessage = (f) => {
-                if (f.reason === "stale_anchor") {
-                    return `the file changed since you read it (anchor mismatch) — re-read \`${file_path}\` and retry`;
-                }
-                if (f.reason === "noop") {
-                    return `old_text and new_text are identical in ${fileName} — this edit would be a no-op. Either fix new_text or drop this edit.`;
-                }
-                if (f.reason === "invalid") {
-                    return `invalid edit: ${f.detail}.`;
-                }
-                if (f.reason === "overlap") {
-                    return (`span overlaps another span edit in this batch — the overlapping region was addressed twice. ` +
-                        `Merge the overlapping spans into one edit and retry.`);
-                }
-                if (f.reason === "ambiguous") {
-                    return (`old_text found ${f.occurrences} times in ${fileName}. ` +
-                        "Include more surrounding context to make the match unique, " +
-                        "or set replace_all: true to swap every occurrence.\n" +
-                        "Matches at:\n" +
-                        f.matchLines +
-                        f.more);
-                }
-                const base = `old_text not found in ${fileName}. ` +
-                    "Text must match verbatim — do not paraphrase. " +
-                    "Fix this edit's old_text to match the file exactly (re-read the region below if unsure); " +
-                    "the file is unchanged, so successful edits and prior reads are still valid." +
-                    f.redactedHint;
-                // Build a bounded read suggestion around the closest-match line so the
-                // model can re-read just that region (e.g. ±25 lines) instead of the
-                // whole file. Skipped when willPersistSuccesses — see comment above.
-                const readHint = f.closestLine !== null && !willPersistSuccesses
-                    ? `\nSuggested re-read: \`read file_path="${file_path}" offset=${Math.max(1, f.closestLine - 25)} limit=50\``
+            if (result.ok) {
+                working = result.newWorking;
+                outcomes[i] = { ok: true, source };
+                continue;
+            }
+            if (result.reason === "not_found") {
+                // Capture the closest-match snippet eagerly against the current
+                // working buffer; we'll decide whether to render it post-loop based
+                // on whether other edits in this batch succeeded.
+                const closest = findClosestSnippet(working, normalizedOld);
+                outcomes[i] = {
+                    ok: false,
+                    failure: {
+                        reason: "not_found",
+                        closestSnippet: closest?.snippet ?? null,
+                        closestLine: closest?.topLine ?? null,
+                        redactedHint: redactedOldTextHint(normalizedOld),
+                    },
+                };
+            }
+            else {
+                const occurrences = result.occurrences ?? 0;
+                const matches = findOccurrenceLines(working, normalizedOld);
+                const matchLines = matches.map((m) => `  line ${m.line}: ${m.preview}`).join("\n");
+                const more = occurrences > matches.length ? `\n  …and ${occurrences - matches.length} more` : "";
+                outcomes[i] = {
+                    ok: false,
+                    failure: { reason: "ambiguous", occurrences, matchLines, more },
+                };
+            }
+        }
+        const failures = outcomes
+            .map((o, i) => (o.ok || !o.failure ? null : { index: i, failure: o.failure }))
+            .filter((x) => x !== null);
+        const successCount = outcomes.length - failures.length;
+        // Closest-match snippets only get suppressed when successes will ACTUALLY
+        // be persisted (partial-apply with at least one win). In atomic mode we
+        // throw before writing, so the model retries against an unchanged file
+        // and the snippet is its only guidance — keep it.
+        const willPersistSuccesses = successCount > 0 && !atomic;
+        const formatFailureMessage = (f) => {
+            if (f.reason === "stale_anchor") {
+                return `the file changed since you read it (anchor mismatch) — re-read \`${file_path}\` and retry`;
+            }
+            if (f.reason === "noop") {
+                return `old_text and new_text are identical in ${fileName} — this edit would be a no-op. Either fix new_text or drop this edit.`;
+            }
+            if (f.reason === "invalid") {
+                return `invalid edit: ${f.detail}.`;
+            }
+            if (f.reason === "overlap") {
+                return (`span overlaps another span edit in this batch — the overlapping region was addressed twice. ` +
+                    `Merge the overlapping spans into one edit and retry.`);
+            }
+            if (f.reason === "ambiguous") {
+                return (`old_text found ${f.occurrences} times in ${fileName}. ` +
+                    "Include more surrounding context to make the match unique, " +
+                    "or set replace_all: true to swap every occurrence.\n" +
+                    "Matches at:\n" +
+                    f.matchLines +
+                    f.more);
+            }
+            const base = `old_text not found in ${fileName}. ` +
+                "Text must match verbatim — do not paraphrase. " +
+                "Fix this edit's old_text to match the file exactly (re-read the region below if unsure); " +
+                "the file is unchanged, so successful edits and prior reads are still valid." +
+                f.redactedHint;
+            // Build a bounded read suggestion around the closest-match line so the
+            // model can re-read just that region (e.g. ±25 lines) instead of the
+            // whole file. Skipped when willPersistSuccesses — see comment above.
+            const readHint = f.closestLine !== null && !willPersistSuccesses
+                ? `\nSuggested re-read: \`read file_path="${file_path}" offset=${Math.max(1, f.closestLine - 25)} limit=50\``
+                : "";
+            if (willPersistSuccesses || !f.closestSnippet)
+                return base + readHint;
+            return `${base}${readHint}\nClosest match in file:\n${f.closestSnippet}`;
+        };
+        const formatFailures = () => {
+            if (failures.length === 1 && edits.length === 1) {
+                return formatFailureMessage(failures[0].failure);
+            }
+            return failures
+                .map((f) => `[edit ${f.index + 1}/${edits.length}] ${formatFailureMessage(f.failure)}`)
+                .join("\n\n");
+        };
+        // Atomic-mode failure, OR partial-mode failure where literally nothing
+        // succeeded. Either way nothing should be written and we throw to make
+        // the model retry the whole batch.
+        if (failures.length > 0 && (atomic || successCount === 0)) {
+            // Nothing was written — the file is byte-identical to the last read, so
+            // the read tracker stays valid. We deliberately do NOT invalidate it
+            // here: doing so turned a precise "old_text not found (closest match
+            // below)" error into a misleading "File must be read first" on every
+            // following edit, hiding the real fix from the model. A genuine on-disk
+            // change (formatter/external edit) is caught by the freshness check.
+            const header = atomic && failures.length > 0
+                ? `${failures.length} of ${edits.length} edit${edits.length === 1 ? "" : "s"} failed; no changes written (atomic).\n\n`
+                : edits.length > 1
+                    ? `${failures.length} of ${edits.length} edits failed; no changes written.\n\n`
                     : "";
-                if (willPersistSuccesses || !f.closestSnippet)
-                    return base + readHint;
-                return `${base}${readHint}\nClosest match in file:\n${f.closestSnippet}`;
-            };
-            const formatFailures = () => {
-                if (failures.length === 1 && edits.length === 1) {
-                    return formatFailureMessage(failures[0].failure);
+            throw new Error(header + formatFailures());
+        }
+        // Never replace real secrets with the placeholder the model was shown.
+        const lossError = redactionLossError(originalNormalized, working, fileName);
+        if (lossError)
+            throw new Error(lossError);
+        const relPath = path.relative(cwd, resolved);
+        const diff = generateDiff(originalNormalized, working, relPath);
+        const changed = working !== originalNormalized;
+        // LSP diagnostics for the just-written content. Best-effort enhancement:
+        // any failure (or an opted-out provider) leaves output identical to today.
+        let diagnosticsNote = "";
+        if (changed) {
+            const finalContent = hasCRLF ? working.replace(/\n/g, "\r\n") : working;
+            // Snapshot the pre-mutation on-disk state for /rewind before writing.
+            await onPreFileMutation?.(resolved);
+            await ops.writeFile(resolved, finalContent);
+            await recordWrite(readFiles, resolved, finalContent, ops, "edit");
+            await mutationCallback?.(resolved);
+            // recordWrite refreshed the tracker to the just-written content, so the
+            // next edit (including retries of the skipped ones) validates against an
+            // accurate snapshot. No invalidation — the failure message already
+            // carries the closest match and a bounded re-read hint.
+            if (getDiagnostics) {
+                try {
+                    diagnosticsNote = await getDiagnostics(resolved, finalContent, riskiestSource(outcomes));
                 }
-                return failures
-                    .map((f) => `[edit ${f.index + 1}/${edits.length}] ${formatFailureMessage(f.failure)}`)
-                    .join("\n\n");
-            };
-            // Atomic-mode failure, OR partial-mode failure where literally nothing
-            // succeeded. Either way nothing should be written and we throw to make
-            // the model retry the whole batch.
-            if (failures.length > 0 && (atomic || successCount === 0)) {
-                // Nothing was written — the file is byte-identical to the last read, so
-                // the read tracker stays valid. We deliberately do NOT invalidate it
-                // here: doing so turned a precise "old_text not found (closest match
-                // below)" error into a misleading "File must be read first" on every
-                // following edit, hiding the real fix from the model. A genuine on-disk
-                // change (formatter/external edit) is caught by the freshness check.
-                const header = atomic && failures.length > 0
-                    ? `${failures.length} of ${edits.length} edit${edits.length === 1 ? "" : "s"} failed; no changes written (atomic).\n\n`
-                    : edits.length > 1
-                        ? `${failures.length} of ${edits.length} edits failed; no changes written.\n\n`
-                        : "";
-                throw new Error(header + formatFailures());
-            }
-            // Never replace real secrets with the placeholder the model was shown.
-            const lossError = redactionLossError(originalNormalized, working, fileName);
-            if (lossError)
-                throw new Error(lossError);
-            const relPath = path.relative(cwd, resolved);
-            const diff = generateDiff(originalNormalized, working, relPath);
-            const changed = working !== originalNormalized;
-            // LSP diagnostics for the just-written content. Best-effort enhancement:
-            // any failure (or an opted-out provider) leaves output identical to today.
-            let diagnosticsNote = "";
-            if (changed) {
-                const finalContent = hasCRLF ? working.replace(/\n/g, "\r\n") : working;
-                // Snapshot the pre-mutation on-disk state for /rewind before writing.
-                await onPreFileMutation?.(resolved);
-                await ops.writeFile(resolved, finalContent);
-                await recordWrite(readFiles, resolved, finalContent, ops, "edit");
-                await mutationCallback?.(resolved);
-                // recordWrite refreshed the tracker to the just-written content, so the
-                // next edit (including retries of the skipped ones) validates against an
-                // accurate snapshot. No invalidation — the failure message already
-                // carries the closest match and a bounded re-read hint.
-                if (getDiagnostics) {
-                    try {
-                        diagnosticsNote = await getDiagnostics(resolved, finalContent, riskiestSource(outcomes));
-                    }
-                    catch {
-                        // Diagnostics must never break a successful edit.
-                    }
+                catch {
+                    // Diagnostics must never break a successful edit.
                 }
             }
-            if (failures.length === 0) {
-                if (!changed) {
-                    const summary = edits.length > 1
-                        ? `No changes needed in ${relPath}; ${edits.length} edits were no-ops.`
-                        : `No changes needed in ${relPath}; edit was a no-op.`;
-                    return { content: summary, details: { diff } };
-                }
+        }
+        if (failures.length === 0) {
+            if (!changed) {
                 const summary = edits.length > 1
-                    ? `Successfully applied ${edits.length} edits to ${relPath}.`
-                    : `Successfully replaced text in ${relPath}.`;
-                return { content: summary + diagnosticsNote, details: { diff } };
+                    ? `No changes needed in ${relPath}; ${edits.length} edits were no-ops.`
+                    : `No changes needed in ${relPath}; edit was a no-op.`;
+                return { content: summary, details: { diff } };
             }
-            // Partial success — the loud header is deliberate: the model has to know
-            // that work was saved AND that only the listed edits need to be retried.
-            const noun = failures.length === 1 ? "edit" : "edits";
-            const content = `Applied ${successCount} of ${edits.length} edits to ${relPath}.\n` +
-                `${failures.length} ${noun} skipped — re-issue ONLY these (the rest are already done, do not redo them):\n\n` +
-                formatFailures() +
-                diagnosticsNote;
-            return { content, details: { diff } };
-        },
-    };
+            const summary = edits.length > 1
+                ? `Successfully applied ${edits.length} edits to ${relPath}.`
+                : `Successfully replaced text in ${relPath}.`;
+            return { content: summary + diagnosticsNote, details: { diff } };
+        }
+        // Partial success — the loud header is deliberate: the model has to know
+        // that work was saved AND that only the listed edits need to be retried.
+        const noun = failures.length === 1 ? "edit" : "edits";
+        const content = `Applied ${successCount} of ${edits.length} edits to ${relPath}.\n` +
+            `${failures.length} ${noun} skipped — re-issue ONLY these (the rest are already done, do not redo them):\n\n` +
+            formatFailures() +
+            diagnosticsNote;
+        return { content, details: { diff } };
+    }
+}
+/** Exactly one form: `file_path`+`edits`, or `files`. */
+function resolveEditTargets(file_path, edits, files) {
+    const single = file_path !== undefined || edits !== undefined;
+    if (files !== undefined && single) {
+        return { ok: false, error: "Use either file_path+edits or files, not both." };
+    }
+    if (files !== undefined)
+        return { ok: true, value: files };
+    if (file_path === undefined || edits === undefined) {
+        return {
+            ok: false,
+            error: "Provide file_path and edits (one file), or files (several files).",
+        };
+    }
+    return { ok: true, value: [{ file_path, edits }] };
 }
 //# sourceMappingURL=edit.js.map