@herbertgao/pi-extensions 2026.8.4 → 2026.8.5

package/node_modules/pi-lens/dist/clients/read-guard-tool-lines.js

@@ -1,6 +1,6 @@
 import * as nodeFs from "node:fs";
-import { hostWouldApplyOldText, normalizeForGuardMatch, } from "./host-edit-normalize.js";
-import { logReadGuardEvent } from "./read-guard-logger.js";
+import { hostWouldApplyOldText, normalizeForGuardMatch, normalizeToLF, stripBom, } from "./host-edit-normalize.js";
+import { boundedIndexesForCount, createReadGuardEditBatchSummary, logReadGuardEvent, } from "./read-guard-logger.js";
 import { isToolCallEventType } from "./tool-event.js";
 // Track repeated oldtext_not_found failures per (filePath, preview) to escalate messages.
 const recentOldTextFailures = new Map();
@@ -51,6 +51,15 @@ function tokenSimilarity(a, b) {
  * its edit from verbatim text in one turn instead of re-reading blind. Scans a
  * ±window around `nearLine` when known (the first-line locator), else the whole
  * file. Returns the top matches above `minScore`, with their real line numbers.
+ *
+ * Scores in normalized space but returns only `{ line, score }` — the caller
+ * renders the text from a structurally-aligned RAW view so a suggestion can
+ * never quote the normalized projection (#1050). NFKC folds CJK full-width
+ * punctuation (`：`→`:`, `，`→`,`, `；`→`;`) and HOST_UNICODE_DASHES folds
+ * `—`→`-`, so a suggestion rendered from normalized content told the agent to
+ * copy bytes the file does not contain; the host's edit tool then fuzzy-matched
+ * it and wrote the folded form onto the touched line. Normalization here is
+ * comparison-only, exactly as everywhere else in this file.
  */
 function findSimilarLines(content, target, options = {}) {
     const { nearLine, window = 60, max = 3, minScore = 0.5 } = options;
@@ -67,14 +76,26 @@ function findSimilarLines(content, target, options = {}) {
             continue;
         const score = tokenSimilarity(needle, text);
         if (score >= minScore)
-            scored.push({ line: i + 1, text, score });
+            scored.push({ line: i + 1, score });
     }
     scored.sort((a, b) => b.score - a.score);
     return scored.slice(0, max);
 }
-function formatSimilarLines(suggestions) {
+/**
+ * Render did-you-mean rows from the file's real characters rather than the
+ * normalized match space the line numbers were scored in. Taking only
+ * `{ line }` from the scan makes quoting normalized text structurally
+ * impossible (#1050).
+ *
+ * `rawLineAligned` must be `normalizeToLF(stripBom(raw).text)`: the same
+ * STRUCTURAL normalization `normalizeForGuardMatch` applies (so line indices
+ * cross-index 1:1 even for lone-CR or BOM files) but none of its CHARACTER
+ * folding, so full-width punctuation, smart quotes, and NBSP survive.
+ */
+function formatSimilarLines(suggestions, rawLineAligned) {
+    const rawLines = rawLineAligned.split("\n");
     const pad = (n) => String(n).padStart(4, " ");
-    const rows = suggestions.map(({ line, text }) => `      ${pad(line)} │ ${text.trimEnd()}`);
+    const rows = suggestions.map(({ line }) => `      ${pad(line)} │ ${(rawLines[line - 1] ?? "").trimEnd()}`);
     return `\n\nDid you mean one of these current lines?\n${rows.join("\n")}`;
 }
 export function countFileLines(filePath) {
@@ -135,7 +156,7 @@ function getHashlineOperations(input) {
         return [input];
     return [];
 }
-function resolveHashlineEditInput(input, filePath, sessionId) {
+function resolveHashlineEditInput(input, filePath, sessionId, correlationId) {
     const operations = getHashlineOperations(input);
     if (operations.length === 0)
         return undefined;
@@ -175,9 +196,21 @@ function resolveHashlineEditInput(input, filePath, sessionId) {
         errors.push(`operation[${index}] is not a recognized hashline edit`);
     }
     if (errors.length > 0) {
+        const editBatchSummary = createReadGuardEditBatchSummary({
+            requestedIndexes: boundedIndexesForCount(operations.length),
+            requestedTotal: operations.length,
+            rejectedReasons: boundedIndexesForCount(operations.length).map((index) => ({
+                index,
+                code: "preflight_blocked",
+            })),
+            rejectedTotal: operations.length,
+            durationMs: 0,
+            terminalStatus: "blocked",
+        });
         if (filePath) {
             logReadGuardEvent({
                 event: "edit_preflight_blocked",
+                correlationId,
                 sessionId,
                 filePath,
                 metadata: {
@@ -189,6 +222,12 @@ function resolveHashlineEditInput(input, filePath, sessionId) {
                     errors: errors.slice(0, 10),
                 },
             });
+            logReadGuardEvent({
+                event: "edit_batch_summary",
+                correlationId,
+                filePath,
+                metadata: { tool: "edit", editBatchSummary },
+            });
         }
         // Every blocking verdict ends with a single concrete next-action line so
         // the agent recovers in one turn (#328 — uniform recovery-hint discipline).
@@ -197,6 +236,7 @@ function resolveHashlineEditInput(input, filePath, sessionId) {
         return {
             touchedLines: undefined,
             preflightError: `🔴 BLOCKED — Unsupported hashline edit target\n\n${errors.join("\n")}\n\n${retryHint}`,
+            editBatchSummary,
         };
     }
     if (ranges.length === 0)
@@ -205,6 +245,7 @@ function resolveHashlineEditInput(input, filePath, sessionId) {
     if (filePath) {
         logReadGuardEvent({
             event: "touched_lines_detected",
+            correlationId,
             sessionId,
             filePath,
             metadata: {
@@ -287,13 +328,23 @@ function exactOldTextForApply(rawContentLf, oldText, candidate) {
     }
     return undefined;
 }
-function resolveOldTextEdits(edits, filePath, sessionId) {
+function resolveOldTextEdits(edits, filePath, sessionId, correlationId) {
+    const startedAt = Date.now();
+    const requestedIndexes = [];
+    const logBatchEvent = (entry) => logReadGuardEvent({ ...entry, correlationId });
     let rawContent;
     try {
         rawContent = nodeFs.readFileSync(filePath, "utf-8");
     }
     catch {
-        logReadGuardEvent({
+        const editBatchSummary = createReadGuardEditBatchSummary({
+            requestedIndexes: edits.map((edit, index) => edit.originalIndex ?? index),
+            rejectedReasons: edits.map((edit, index) => ({
+                index: edit.originalIndex ?? index,
+                code: "preflight_blocked",
+            })),
+        });
+        logBatchEvent({
             event: "touched_lines_missing",
             sessionId,
             filePath,
@@ -303,7 +354,12 @@ function resolveOldTextEdits(edits, filePath, sessionId) {
                 editCount: edits.length,
             },
         });
-        return { touchedLines: undefined };
+        logBatchEvent({
+            event: "edit_batch_summary",
+            filePath,
+            metadata: { tool: "edit", editBatchSummary },
+        });
+        return { touchedLines: undefined, editBatchSummary };
     }
     const rawContentLf = rawContent.replace(/\r\n/g, "\n");
     const content = normalizeContent(rawContent);
@@ -311,12 +367,16 @@ function resolveOldTextEdits(edits, filePath, sessionId) {
     const failureKinds = [];
     const failedEditIndexes = [];
     const failedOldTextPreviews = [];
+    const rejectedReasons = [];
+    const resolvedIndexes = [];
     const resolvedRanges = [];
     const passedEdits = [];
     let maxFailCount = 0;
     for (let i = 0; i < edits.length; i++) {
         const oldText = edits[i].oldText;
         const editIndex = edits[i].originalIndex ?? i;
+        if (requestedIndexes.length < 100)
+            requestedIndexes.push(editIndex);
         if (!oldText)
             continue;
         let needle = normalizeContent(oldText);
@@ -327,7 +387,7 @@ function resolveOldTextEdits(edits, filePath, sessionId) {
                 needle = normalizeContent(corrected);
                 occurrenceLines = findOccurrenceLines(content, needle);
                 if (occurrenceLines.length > 0) {
-                    logReadGuardEvent({
+                    logBatchEvent({
                         event: "oldtext_indent_corrected",
                         sessionId,
                         filePath,
@@ -343,8 +403,13 @@ function resolveOldTextEdits(edits, filePath, sessionId) {
         if (occurrenceLines.length === 0) {
             const preview = oldText.trimStart().substring(0, 60).replace(/\n/g, "↵");
             failureKinds.push("oldtext_not_found");
-            failedEditIndexes.push(editIndex);
-            failedOldTextPreviews.push(preview);
+            if (failedEditIndexes.length < 100) {
+                failedEditIndexes.push(editIndex);
+                failedOldTextPreviews.push(preview);
+            }
+            if (rejectedReasons.length < 100) {
+                rejectedReasons.push({ index: editIndex, code: "oldtext_not_found" });
+            }
             const failCount = trackOldTextFailure(filePath, preview);
             if (failCount > maxFailCount)
                 maxFailCount = failCount;
@@ -401,11 +466,14 @@ function resolveOldTextEdits(edits, filePath, sessionId) {
             // similarity) so the model can rebuild oldText verbatim in one turn
             // instead of re-reading blind. Skipped on the quote-style path, which
             // already names the precise fix. Anchored near the first-line locator
-            // when known, else scans the whole file.
+            // when known, else scans the whole file. Scored against `content`
+            // (normalized) but RENDERED from a structurally-aligned raw view —
+            // quoting the normalized projection told the agent to copy bytes the
+            // file does not contain (#1050).
             if (!errorMsg.includes("quote style")) {
                 const similarLines = findSimilarLines(content, oldText.replace(/\r\n/g, "\n").split("\n")[0], { nearLine: findFirstLineOfOldText(content, oldText) });
                 if (similarLines.length > 0) {
-                    errorMsg += formatSimilarLines(similarLines);
+                    errorMsg += formatSimilarLines(similarLines, normalizeToLF(stripBom(rawContent).text));
                 }
             }
             errors.push(errorMsg);
@@ -414,7 +482,7 @@ function resolveOldTextEdits(edits, filePath, sessionId) {
             // friction the host wouldn't have); false => a genuine miss. This is the
             // measurement that tells us whether the guard earns its keep (#257).
             const hostMatch = hostWouldApplyOldText(rawContent, oldText);
-            logReadGuardEvent({
+            logBatchEvent({
                 event: "oldtext_not_found",
                 sessionId,
                 filePath,
@@ -434,6 +502,8 @@ function resolveOldTextEdits(edits, filePath, sessionId) {
             const startLine = occurrenceLines[0];
             const endLine = startLine + needle.split("\n").length - 1;
             resolvedRanges.push([startLine, endLine]);
+            if (resolvedIndexes.length < 100)
+                resolvedIndexes.push(editIndex);
             const applyOldText = exactOldTextForApply(rawContentLf, oldText, needle);
             if (applyOldText !== undefined) {
                 passedEdits.push({
@@ -442,7 +512,7 @@ function resolveOldTextEdits(edits, filePath, sessionId) {
                     originalIndex: editIndex,
                 });
             }
-            logReadGuardEvent({
+            logBatchEvent({
                 event: "oldtext_resolved",
                 sessionId,
                 filePath,
@@ -457,12 +527,17 @@ function resolveOldTextEdits(edits, filePath, sessionId) {
         else {
             const preview = oldText.trimStart().substring(0, 60).replace(/\n/g, "↵");
             failureKinds.push("oldtext_duplicate");
-            failedEditIndexes.push(editIndex);
-            failedOldTextPreviews.push(preview);
+            if (failedEditIndexes.length < 100) {
+                failedEditIndexes.push(editIndex);
+                failedOldTextPreviews.push(preview);
+            }
+            if (rejectedReasons.length < 100) {
+                rejectedReasons.push({ index: editIndex, code: "oldtext_duplicate" });
+            }
             const matchSpanLines = needle.split("\n").length;
             const contextBlock = formatOccurrenceContext(content, occurrenceLines, matchSpanLines);
             errors.push(`edits[${editIndex}].oldText ("${preview}") appears ${occurrenceLines.length} times:\n${contextBlock}\nPick the location you want and extend your oldText with the unique line above or below it (shown as context).`);
-            logReadGuardEvent({
+            logBatchEvent({
                 event: "oldtext_duplicate",
                 sessionId,
                 filePath,
@@ -470,8 +545,8 @@ function resolveOldTextEdits(edits, filePath, sessionId) {
                     tool: "edit",
                     source: "edits_without_ranges",
                     editIndex,
+                    occurrenceLines: occurrenceLines.slice(0, 100),
                     occurrenceCount: occurrenceLines.length,
-                    occurrenceLines,
                     oldTextPreview: preview,
                 },
             });
@@ -485,8 +560,19 @@ function resolveOldTextEdits(edits, filePath, sessionId) {
                 "One or more edit targets could not be resolved to exact lines. Re-read the relevant section and retry with the exact content as it appears in the file.",
             ];
         const uniqueFailureKinds = [...new Set(failureKinds)];
-        logReadGuardEvent({
+        const editBatchSummary = createReadGuardEditBatchSummary({
+            requestedIndexes,
+            requestedTotal: edits.length,
+            resolvedIndexes,
+            resolvedTotal: resolvedRanges.length,
+            rejectedReasons,
+            rejectedTotal: Math.max(0, oldTextEditCount - resolvedRanges.length),
+            durationMs: Date.now() - startedAt,
+            terminalStatus: "blocked",
+        });
+        logBatchEvent({
             event: "edit_preflight_blocked",
+            correlationId,
             sessionId,
             filePath,
             metadata: {
@@ -511,14 +597,27 @@ function resolveOldTextEdits(edits, filePath, sessionId) {
         const header = maxFailCount >= 2
             ? `🛑 RE-READ REQUIRED — You have submitted this oldText before and it still does not match.\n\nDo NOT retry from memory. Re-read \`${filePath}\` to get the current content, then rebuild your edit from the verbatim file text.`
             : `🔄 RETRYABLE — Edit target not found`;
+        logBatchEvent({
+            event: "edit_batch_summary",
+            correlationId,
+            filePath,
+            metadata: { tool: "edit", editBatchSummary },
+        });
         return {
             touchedLines: undefined,
             preflightError: `${header}\n\n${failureDetails.join("\n\n")}${appliedNote}`,
             partiallyApplicable: passedEdits.length > 0 ? passedEdits : undefined,
+            editBatchSummary,
         };
     }
     if (resolvedRanges.length === 0) {
-        logReadGuardEvent({
+        const editBatchSummary = createReadGuardEditBatchSummary({
+            requestedIndexes,
+            requestedTotal: edits.length,
+            rejectedTotal: oldTextEditCount,
+            terminalStatus: "blocked",
+        });
+        logBatchEvent({
             event: "touched_lines_missing",
             sessionId,
             filePath,
@@ -528,7 +627,12 @@ function resolveOldTextEdits(edits, filePath, sessionId) {
                 editCount: edits.length,
             },
         });
-        return { touchedLines: undefined };
+        logBatchEvent({
+            event: "edit_batch_summary",
+            filePath,
+            metadata: { tool: "edit", editBatchSummary },
+        });
+        return { touchedLines: undefined, editBatchSummary };
     }
     const starts = resolvedRanges.map(([s]) => s);
     const ends = resolvedRanges.map(([, e]) => e);
@@ -537,7 +641,7 @@ function resolveOldTextEdits(edits, filePath, sessionId) {
         Math.max(...ends),
     ];
     const editRanges = resolvedRanges.length > 1 ? resolvedRanges : undefined;
-    logReadGuardEvent({
+    logBatchEvent({
         event: "touched_lines_detected",
         sessionId,
         filePath,
@@ -549,7 +653,20 @@ function resolveOldTextEdits(edits, filePath, sessionId) {
             totalEditCount: edits.length,
         },
     });
-    return { touchedLines, editRanges, contentMatchValidated: true };
+    const editBatchSummary = createReadGuardEditBatchSummary({
+        requestedIndexes,
+        requestedTotal: edits.length,
+        resolvedIndexes,
+        resolvedTotal: resolvedRanges.length,
+        durationMs: Date.now() - startedAt,
+        terminalStatus: "success",
+    });
+    return {
+        touchedLines,
+        editRanges,
+        contentMatchValidated: true,
+        editBatchSummary,
+    };
 }
 /**
  * Normalises an oldText string for whitespace-only differences that editors routinely
@@ -888,7 +1005,7 @@ export function relocateEditRange(input, from, to) {
     }
     return applied;
 }
-export function getTouchedLinesForGuard(event, filePath, sessionId) {
+export function getTouchedLinesForGuard(event, filePath, sessionId, correlationId) {
     if (isToolCallEventType("edit", event)) {
         // The host standard-edit fields (path, edits[].oldText/newText) are pinned
         // to the SDK's EditToolInput, so a host edit-schema change is a compile
@@ -897,7 +1014,7 @@ export function getTouchedLinesForGuard(event, filePath, sessionId) {
         // edit tools; oldText/newText are probed as optional because range-only
         // edits omit them (refs #3).
         const editInput = event.input;
-        const hashlineResult = resolveHashlineEditInput(editInput, filePath, sessionId);
+        const hashlineResult = resolveHashlineEditInput(editInput, filePath, sessionId, correlationId);
         if (hashlineResult)
             return hashlineResult;
         if (editInput.oldRange) {
@@ -908,6 +1025,7 @@ export function getTouchedLinesForGuard(event, filePath, sessionId) {
             if (filePath) {
                 logReadGuardEvent({
                     event: "touched_lines_detected",
+                    correlationId,
                     sessionId,
                     filePath,
                     metadata: {
@@ -935,14 +1053,14 @@ export function getTouchedLinesForGuard(event, filePath, sessionId) {
                 .filter((edit) => typeof edit.range?.start?.line !== "number" && !!edit.oldText);
             if (rangedEdits.length === 0) {
                 if (filePath) {
-                    return resolveOldTextEdits(editInput.edits, filePath, sessionId);
+                    return resolveOldTextEdits(editInput.edits, filePath, sessionId, correlationId);
                 }
                 return { touchedLines: undefined };
             }
             let oldTextTouchedLines;
             let oldTextEditRanges;
             if (unresolvedOldTextEdits.length > 0 && filePath) {
-                const resolved = resolveOldTextEdits(unresolvedOldTextEdits, filePath, sessionId);
+                const resolved = resolveOldTextEdits(unresolvedOldTextEdits, filePath, sessionId, correlationId);
                 if (resolved.preflightError) {
                     return resolved;
                 }
@@ -970,6 +1088,7 @@ export function getTouchedLinesForGuard(event, filePath, sessionId) {
             if (filePath) {
                 logReadGuardEvent({
                     event: "touched_lines_detected",
+                    correlationId,
                     sessionId,
                     filePath,
                     metadata: {
@@ -990,6 +1109,7 @@ export function getTouchedLinesForGuard(event, filePath, sessionId) {
             const topLevelKeys = Object.keys(editInput);
             logReadGuardEvent({
                 event: "touched_lines_missing",
+                correlationId,
                 sessionId,
                 filePath,
                 metadata: {
@@ -1014,6 +1134,7 @@ export function getTouchedLinesForGuard(event, filePath, sessionId) {
         if (filePath) {
             logReadGuardEvent({
                 event: "touched_lines_detected",
+                correlationId,
                 sessionId,
                 filePath,
                 metadata: {