@aria-cli/tools 1.0.9 → 1.0.11

package/src/executors/apply-patch.ts

@@ -1,1035 +0,0 @@
-/**
- * @aria/tools - Apply Patch executor
- *
- * Parses and applies unified diff patches with:
- * - Path traversal protection (SECURITY-CRITICAL)
- * - Atomic writes (all-or-nothing application)
- * - Fuzzy hunk matching (offset tolerance)
- * - CRLF normalization
- */
-
-import * as crypto from "node:crypto";
-import * as fs from "node:fs/promises";
-import * as fsSync from "node:fs";
-import * as nodePath from "node:path";
-import type { ToolContext, ToolResult } from "../types.js";
-import { success, fail, getErrorMessage, isPathWithinBase } from "./utils.js";
-import { recordFrgMutation } from "./frg-freshness.js";
-import { recordSearchMutation } from "./search-freshness.js";
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export interface ApplyPatchInput {
-  /** Unified diff format patch content */
-  patch: string;
-  /** Working directory for relative paths in the patch */
-  cwd?: string;
-}
-
-/** A single hunk within a file diff */
-interface Hunk {
-  /** Original file start line (1-based) */
-  oldStart: number;
-  /** Number of lines in original */
-  oldCount: number;
-  /** Modified file start line (1-based) */
-  newStart: number;
-  /** Number of lines in modified */
-  newCount: number;
-  /** Lines in the hunk: each prefixed with ' ', '+', or '-' */
-  lines: string[];
-}
-
-/** A diff for a single file */
-interface FileDiff {
-  /** Original file path (null for new files) */
-  oldPath: string | null;
-  /** Modified file path (null for deleted files) */
-  newPath: string | null;
-  /** Hunks to apply */
-  hunks: Hunk[];
-}
-
-/** What to do with a file after applying hunks */
-interface FileAction {
-  /** Source path for move operations */
-  sourcePath?: string;
-  /** Target absolute path */
-  resolvedPath: string;
-  /** Action type */
-  type: "create" | "modify" | "delete" | "move";
-  /** New content (for create/modify) */
-  content?: string;
-}
-
-function getErrnoCode(err: unknown): string | undefined {
-  if (typeof err !== "object" || err === null) {
-    return undefined;
-  }
-  const withCode = err as { code?: unknown };
-  return typeof withCode.code === "string" ? withCode.code : undefined;
-}
-
-// Maximum fuzzy offset when searching for hunk context
-const MAX_FUZZ_OFFSET = 3;
-const BEGIN_PATCH = "*** Begin Patch";
-const END_PATCH = "*** End Patch";
-const ADD_FILE = "*** Add File: ";
-const DELETE_FILE = "*** Delete File: ";
-const UPDATE_FILE = "*** Update File: ";
-const MOVE_TO = "*** Move to: ";
-const END_OF_FILE = "*** End of File";
-
-// ============================================================================
-// Unified Diff Parser
-// ============================================================================
-
-/**
- * Parse a unified diff string into an array of file diffs.
- * Handles standard unified diff and git-style diffs.
- */
-export function parseUnifiedDiff(patch: string): FileDiff[] {
-  // Normalize CRLF to LF
-  const normalized = patch.replace(/\r\n/g, "\n");
-  const lines = normalized.split("\n");
-  const diffs: FileDiff[] = [];
-  let i = 0;
-
-  while (i < lines.length) {
-    const line = lines[i]!;
-
-    // Look for --- header
-    if (line.startsWith("--- ")) {
-      // Check for binary diff markers before this point
-      // (we check later too, but early check is good)
-      const nextLine = lines[i + 1];
-      if (!nextLine || !nextLine.startsWith("+++ ")) {
-        i++;
-        continue;
-      }
-
-      const oldPath = parseDiffPath(line.slice(4));
-      const newPath = parseDiffPath(nextLine.slice(4));
-      i += 2;
-
-      // Parse hunks for this file
-      const hunks: Hunk[] = [];
-      while (i < lines.length) {
-        const hunkLine = lines[i]!;
-        if (hunkLine.startsWith("@@ ")) {
-          const hunk = parseHunkHeader(hunkLine);
-          if (!hunk) {
-            throw new Error(`Invalid hunk header: ${hunkLine}`);
-          }
-          i++;
-
-          // Collect hunk lines
-          const hunkLines: string[] = [];
-          let oldSeen = 0;
-          let newSeen = 0;
-          while (i < lines.length) {
-            const l = lines[i]!;
-            const prefix = l[0];
-            if (prefix === " " || prefix === "+" || prefix === "-") {
-              hunkLines.push(l);
-              if (prefix === " " || prefix === "-") oldSeen++;
-              if (prefix === " " || prefix === "+") newSeen++;
-              i++;
-              // Unified diff hunks define old/new line counts explicitly.
-              // Stop when we consumed the declared line counts so a following
-              // file header ("--- ...") is not misread as hunk content.
-              if (oldSeen >= hunk.oldCount && newSeen >= hunk.newCount) {
-                break;
-              }
-            } else if (l === "\") {
-              // Skip this marker — we handle trailing newlines via content
-              i++;
-            } else {
-              break;
-            }
-          }
-
-          if (i < lines.length) {
-            const next = lines[i]!;
-            const nextPrefix = next[0];
-            const looksLikeHunkLine =
-              nextPrefix === " " ||
-              (nextPrefix === "+" && !next.startsWith("+++ ")) ||
-              (nextPrefix === "-" && !next.startsWith("--- "));
-            if (looksLikeHunkLine) {
-              throw new Error(
-                `Malformed hunk: expected old/new counts ${hunk.oldCount}/${hunk.newCount} but found extra hunk lines`,
-              );
-            }
-          }
-
-          if (oldSeen !== hunk.oldCount || newSeen !== hunk.newCount) {
-            throw new Error(
-              `Malformed hunk: expected old/new counts ${hunk.oldCount}/${hunk.newCount} but found ${oldSeen}/${newSeen}`,
-            );
-          }
-
-          hunks.push({ ...hunk, lines: hunkLines });
-        } else if (hunkLine.startsWith("--- ") || hunkLine.startsWith("diff ") || hunkLine === "") {
-          // Start of next file diff or blank line separator
-          break;
-        } else {
-          // Skip git diff metadata lines (index, mode, etc.)
-          i++;
-        }
-      }
-
-      if (hunks.length > 0 || oldPath === null || newPath === null) {
-        diffs.push({ oldPath, newPath, hunks });
-      }
-    } else if (line.startsWith("Binary files") || line.startsWith("GIT binary patch")) {
-      throw new Error(`Binary diffs are not supported: ${line}`);
-    } else {
-      i++;
-    }
-  }
-
-  return diffs;
-}
-
-function buildCountedHunk(lines: string[]): Hunk {
-  let oldCount = 0;
-  let newCount = 0;
-  for (const line of lines) {
-    if (line.startsWith(" ") || line.startsWith("-")) oldCount++;
-    if (line.startsWith(" ") || line.startsWith("+")) newCount++;
-  }
-  return {
-    oldStart: 1,
-    oldCount,
-    newStart: 1,
-    newCount,
-    lines,
-  };
-}
-
-function parseHeaderPath(line: string, prefix: string): string {
-  const raw = line.slice(prefix.length).trim();
-  if (!raw) {
-    throw new Error(`Missing file path after header: ${prefix.trim()}`);
-  }
-  return raw;
-}
-
-function parseBeginPatchFormat(patch: string): FileDiff[] {
-  const lines = normalizePatchText(patch).split("\n");
-  if ((lines[0] ?? "").trim() !== BEGIN_PATCH) {
-    throw new Error("Invalid apply_patch envelope: missing *** Begin Patch");
-  }
-
-  const diffs: FileDiff[] = [];
-  let i = 1;
-
-  while (i < lines.length) {
-    const line = lines[i] ?? "";
-
-    if (line === END_PATCH) {
-      return diffs;
-    }
-    if (line.trim() === "") {
-      i++;
-      continue;
-    }
-
-    if (line.startsWith(ADD_FILE)) {
-      const newPath = parseHeaderPath(line, ADD_FILE);
-      i++;
-      const addLines: string[] = [];
-      while (i < lines.length) {
-        const current = lines[i] ?? "";
-        if (current.startsWith("*** ")) break;
-        if (!current.startsWith("+")) {
-          throw new Error(`Invalid add-file line (must start with '+'): ${current}`);
-        }
-        addLines.push(current);
-        i++;
-      }
-      diffs.push({
-        oldPath: null,
-        newPath,
-        hunks: [buildCountedHunk(addLines)],
-      });
-      continue;
-    }
-
-    if (line.startsWith(DELETE_FILE)) {
-      const oldPath = parseHeaderPath(line, DELETE_FILE);
-      diffs.push({ oldPath, newPath: null, hunks: [] });
-      i++;
-      continue;
-    }
-
-    if (line.startsWith(UPDATE_FILE)) {
-      const oldPath = parseHeaderPath(line, UPDATE_FILE);
-      i++;
-
-      let newPath = oldPath;
-      if ((lines[i] ?? "").startsWith(MOVE_TO)) {
-        newPath = parseHeaderPath(lines[i]!, MOVE_TO);
-        i++;
-      }
-
-      const hunks: Hunk[] = [];
-      let currentHunkLines: string[] = [];
-      while (i < lines.length) {
-        const current = lines[i] ?? "";
-        if (current.startsWith("*** ")) break;
-
-        if (current.startsWith("@@")) {
-          if (currentHunkLines.length > 0) {
-            hunks.push(buildCountedHunk(currentHunkLines));
-            currentHunkLines = [];
-          }
-          i++;
-          continue;
-        }
-
-        if (current === END_OF_FILE) {
-          i++;
-          continue;
-        }
-
-        if (current.startsWith(" ") || current.startsWith("+") || current.startsWith("-")) {
-          currentHunkLines.push(current);
-          i++;
-          continue;
-        }
-
-        throw new Error(`Invalid update-file line: ${current}`);
-      }
-
-      if (currentHunkLines.length > 0) {
-        hunks.push(buildCountedHunk(currentHunkLines));
-      }
-
-      if (hunks.length === 0 && oldPath === newPath) {
-        throw new Error(`Update section has no hunks: ${oldPath}`);
-      }
-
-      diffs.push({ oldPath, newPath, hunks });
-      continue;
-    }
-
-    throw new Error(`Invalid apply_patch section header: ${line}`);
-  }
-
-  throw new Error("Invalid apply_patch envelope: missing *** End Patch");
-}
-
-function normalizePatchText(patch: string): string {
-  return patch.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
-}
-
-function parsePatchInput(patch: string): FileDiff[] {
-  const normalized = normalizePatchText(patch).trimStart();
-  if (normalized.startsWith(BEGIN_PATCH)) {
-    return parseBeginPatchFormat(normalized);
-  }
-  return parseUnifiedDiff(normalized);
-}
-
-/**
- * Parse a file path from a --- or +++ line.
- * Strips a/ or b/ git-style prefixes.
- * Returns null for /dev/null (new file or deleted file).
- */
-function parseDiffPath(raw: string): string | null {
-  // Remove trailing timestamp (e.g., "2024-01-01 00:00:00.000000000 +0000")
-  const path = raw.replace(/\t.*$/, "").trim();
-
-  if (path === "/dev/null") {
-    return null;
-  }
-
-  // Strip git-style a/ or b/ prefix
-  if (path.startsWith("a/") || path.startsWith("b/")) {
-    return path.slice(2);
-  }
-
-  return path;
-}
-
-/**
- * Parse a hunk header line: @@ -oldStart,oldCount +newStart,newCount @@
- */
-function parseHunkHeader(line: string): Omit<Hunk, "lines"> | null {
-  const match = line.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
-  if (!match) return null;
-
-  return {
-    oldStart: parseInt(match[1]!, 10),
-    oldCount: match[2] !== undefined ? parseInt(match[2], 10) : 1,
-    newStart: parseInt(match[3]!, 10),
-    newCount: match[4] !== undefined ? parseInt(match[4], 10) : 1,
-  };
-}
-
-// ============================================================================
-// Path Validation (SECURITY-CRITICAL)
-// ============================================================================
-
-/**
- * Validate all paths in a parsed diff against path traversal attacks.
- *
- * SECURITY: This is the primary defense against malicious patches that
- * attempt to write outside the working directory.
- */
-function validatePatchPaths(
-  diffs: FileDiff[],
-  cwd: string,
-): { valid: true; resolved: Map<string, string> } | { valid: false; error: string } {
-  const resolved = new Map<string, string>();
-
-  for (const diff of diffs) {
-    const paths = [diff.oldPath, diff.newPath].filter((p): p is string => p !== null);
-
-    for (const rawPath of paths) {
-      if (resolved.has(rawPath)) continue;
-
-      // 1. Reject absolute paths
-      if (nodePath.isAbsolute(rawPath)) {
-        return {
-          valid: false,
-          error: `Absolute path not allowed in patch: ${rawPath}`,
-        };
-      }
-
-      // 2. Reject paths with .. components
-      const segments = rawPath.split(/[/\\]/);
-      if (segments.includes("..")) {
-        return {
-          valid: false,
-          error: `Path traversal (..) not allowed in patch: ${rawPath}`,
-        };
-      }
-
-      // 3. Reject system paths (even though relative shouldn't reach these,
-      //    defense-in-depth against creative path construction)
-      const systemPrefixes = ["/dev/", "/proc/", "/sys/", "/etc/"];
-      for (const prefix of systemPrefixes) {
-        if (rawPath.startsWith(prefix) || rawPath === prefix.slice(0, -1)) {
-          return {
-            valid: false,
-            error: `System path not allowed in patch: ${rawPath}`,
-          };
-        }
-      }
-
-      // 4. Resolve relative to cwd
-      const fullPath = nodePath.resolve(cwd, rawPath);
-
-      // 5. Verify the resolved path is within cwd
-      // Resolve symlinks on cwd to handle platforms where /tmp -> /private/tmp
-      let realCwd = cwd;
-      try {
-        realCwd = fsSync.realpathSync(cwd);
-      } catch {
-        // Fall back to original cwd if it doesn't exist yet
-      }
-
-      // Resolve symlinks on the target path (walk up to nearest existing ancestor)
-      let realPath = fullPath;
-      try {
-        realPath = fsSync.realpathSync(fullPath);
-      } catch {
-        // Path may not exist yet — walk up to find nearest existing ancestor
-        let current = fullPath;
-        let suffix = "";
-        while (current !== nodePath.dirname(current)) {
-          const parent = nodePath.dirname(current);
-          suffix = suffix
-            ? nodePath.join(nodePath.basename(current), suffix)
-            : nodePath.basename(current);
-          try {
-            const realAncestor = fsSync.realpathSync(parent);
-            realPath = nodePath.join(realAncestor, suffix);
-            break;
-          } catch {
-            current = parent;
-          }
-        }
-      }
-
-      if (!isPathWithinBase(realPath, realCwd)) {
-        return {
-          valid: false,
-          error: `Resolved path escapes working directory: ${rawPath} -> ${realPath} (cwd: ${realCwd})`,
-        };
-      }
-
-      resolved.set(rawPath, realPath);
-    }
-  }
-
-  return { valid: true, resolved };
-}
-
-// ============================================================================
-// Windows Drive Letter Detection
-// ============================================================================
-
-/**
- * Check if a path looks like a Windows drive letter (e.g., C:\, D:/)
- */
-function isWindowsDrivePath(p: string): boolean {
-  return /^[a-zA-Z]:[/\\]/.test(p);
-}
-
-// ============================================================================
-// Hunk Application
-// ============================================================================
-
-/**
- * Apply hunks to file content.
- * Uses fuzzy matching with a configurable offset tolerance.
- *
- * Returns the modified content or an error describing what went wrong.
- */
-function applyHunks(
-  originalContent: string,
-  hunks: Hunk[],
-  filePath: string,
-): { ok: true; content: string } | { ok: false; error: string } {
-  // Normalize CRLF
-  const normalized = originalContent.replace(/\r\n/g, "\n");
-  let lines = normalized.split("\n");
-
-  // Track cumulative offset from insertions/deletions
-  let lineOffset = 0;
-
-  for (let hunkIdx = 0; hunkIdx < hunks.length; hunkIdx++) {
-    const hunk = hunks[hunkIdx]!;
-
-    // Extract context and removal lines (lines that must exist in original)
-    const expectedLines: string[] = [];
-    const newLines: string[] = [];
-
-    for (const line of hunk.lines) {
-      const prefix = line[0];
-      const content = line.slice(1);
-      if (prefix === " ") {
-        expectedLines.push(content);
-        newLines.push(content);
-      } else if (prefix === "-") {
-        expectedLines.push(content);
-      } else if (prefix === "+") {
-        newLines.push(content);
-      }
-    }
-
-    // Find the position where context matches
-    const expectedStart = hunk.oldStart - 1 + lineOffset; // Convert 1-based to 0-based
-    let matchPos = -1;
-
-    // Try exact position first, then fuzzy within tolerance
-    for (let offset = 0; offset <= MAX_FUZZ_OFFSET; offset++) {
-      for (const dir of [0, 1, -1]) {
-        const tryPos = expectedStart + offset * (dir === 0 ? 0 : dir);
-        if (dir === 0 && offset > 0) continue; // Skip duplicate 0-offset
-
-        if (tryPos < 0 || tryPos + expectedLines.length > lines.length) continue;
-
-        let matches = true;
-        for (let j = 0; j < expectedLines.length; j++) {
-          if (lines[tryPos + j] !== expectedLines[j]) {
-            matches = false;
-            break;
-          }
-        }
-
-        if (matches) {
-          matchPos = tryPos;
-          break;
-        }
-      }
-      if (matchPos >= 0) break;
-    }
-
-    if (matchPos < 0) {
-      // Fallback: global scan for context (used by relaxed patch formats where line numbers may be approximate)
-      const candidates: number[] = [];
-      for (let pos = 0; pos + expectedLines.length <= lines.length; pos++) {
-        let matches = true;
-        for (let j = 0; j < expectedLines.length; j++) {
-          if (lines[pos + j] !== expectedLines[j]) {
-            matches = false;
-            break;
-          }
-        }
-        if (matches) candidates.push(pos);
-      }
-
-      if (candidates.length === 1) {
-        matchPos = candidates[0]!;
-      } else {
-        // Build a helpful error message
-        const contextPreview = expectedLines.slice(0, 3).join("\n  ");
-        const ambiguity =
-          candidates.length > 1
-            ? `Context matched ${candidates.length} locations; provide more surrounding lines.`
-            : "Context not found.";
-        return {
-          ok: false,
-          error:
-            `Hunk ${hunkIdx + 1} failed to apply to ${filePath} ` +
-            `(expected at line ${hunk.oldStart}, searched ±${MAX_FUZZ_OFFSET} lines). ` +
-            `${ambiguity}\n  ${contextPreview}`,
-        };
-      }
-    }
-
-    // Apply: replace the matched range with the new lines
-    lines = [
-      ...lines.slice(0, matchPos),
-      ...newLines,
-      ...lines.slice(matchPos + expectedLines.length),
-    ];
-
-    // Update offset for subsequent hunks
-    lineOffset += newLines.length - expectedLines.length;
-  }
-
-  return { ok: true, content: lines.join("\n") };
-}
-
-// ============================================================================
-// Atomic Patch Application
-// ============================================================================
-
-/**
- * Apply all file diffs atomically.
- * Writes to temp files first, then renames on success.
- * On any failure, cleans up all temp files.
- */
-async function applyPatchAtomic(
-  diffs: FileDiff[],
-  resolvedPaths: Map<string, string>,
-): Promise<ToolResult> {
-  const actions: FileAction[] = [];
-  const tempFiles: string[] = [];
-  let totalAdded = 0;
-  let totalRemoved = 0;
-
-  try {
-    // Phase 1: Compute all file actions (read + apply hunks)
-    for (const diff of diffs) {
-      const isNewFile = diff.oldPath === null;
-      const isDeleteFile = diff.newPath === null;
-      const sourcePath = diff.oldPath ? resolvedPaths.get(diff.oldPath) : undefined;
-      const targetPath = diff.newPath ? resolvedPaths.get(diff.newPath) : undefined;
-
-      if (isDeleteFile) {
-        // Deletion: mark for removal
-        if (!sourcePath) {
-          return fail(`Patch references missing delete source path: ${diff.oldPath}`);
-        }
-        let sourceStat: fsSync.Stats;
-        try {
-          sourceStat = await fs.stat(sourcePath);
-        } catch (err) {
-          return fail(`Cannot delete missing path: ${sourcePath}: ${getErrorMessage(err)}`);
-        }
-        if (sourceStat.isDirectory()) {
-          return fail(`Patch delete targets a directory (unsupported): ${sourcePath}`);
-        }
-        actions.push({ resolvedPath: sourcePath, type: "delete" });
-
-        // Count removed lines
-        for (const hunk of diff.hunks) {
-          for (const line of hunk.lines) {
-            if (line.startsWith("-")) totalRemoved++;
-          }
-        }
-        continue;
-      }
-
-      if (isNewFile) {
-        if (!targetPath) {
-          return fail(`Patch references missing create target path: ${diff.newPath}`);
-        }
-        // New file: build content from additions
-        const contentLines: string[] = [];
-        for (const hunk of diff.hunks) {
-          for (const line of hunk.lines) {
-            if (line.startsWith("+")) {
-              contentLines.push(line.slice(1));
-              totalAdded++;
-            }
-          }
-        }
-        const content = contentLines.join("\n") + "\n";
-        actions.push({ resolvedPath: targetPath, type: "create", content });
-      } else {
-        if (!sourcePath || !targetPath) {
-          return fail(
-            `Patch references missing update source/target paths: ${diff.oldPath} -> ${diff.newPath}`,
-          );
-        }
-        // Modify existing file
-        let originalContent: string;
-        try {
-          originalContent = await fs.readFile(sourcePath, "utf-8");
-        } catch (err) {
-          return fail(`Cannot read file for patching: ${sourcePath}: ${getErrorMessage(err)}`);
-        }
-
-        const result = applyHunks(originalContent, diff.hunks, diff.newPath!);
-        if (!result.ok) {
-          return fail(result.error);
-        }
-
-        // Count additions and removals
-        for (const hunk of diff.hunks) {
-          for (const line of hunk.lines) {
-            if (line.startsWith("+")) totalAdded++;
-            else if (line.startsWith("-")) totalRemoved++;
-          }
-        }
-
-        actions.push({
-          sourcePath,
-          resolvedPath: targetPath,
-          type: sourcePath === targetPath ? "modify" : "move",
-          content: result.content,
-        });
-      }
-    }
-
-    // Phase 2: Write all changes to temp files
-    for (const action of actions) {
-      if (action.type === "delete") continue;
-
-      const dir = nodePath.dirname(action.resolvedPath);
-      const base = nodePath.basename(action.resolvedPath);
-      const suffix = crypto.randomBytes(6).toString("hex");
-      const tempPath = nodePath.join(dir, `.${base}.patch-${suffix}`);
-
-      // Ensure parent directory exists (needed for new files)
-      await fs.mkdir(dir, { recursive: true });
-
-      await fs.writeFile(tempPath, action.content!, "utf-8");
-      tempFiles.push(tempPath);
-    }
-
-    // Phase 3: Atomic rename — all temp files to final destinations
-    // Back up targets and deletion sources for rollback on failure
-    const targetBackups = new Map<string, string>();
-    const sourceRemovalBackups = new Map<string, string>();
-    const appliedTargets: string[] = [];
-    const removedSources: string[] = [];
-
-    const backupTargetIfExists = async (targetPath: string): Promise<void> => {
-      if (targetBackups.has(targetPath)) {
-        return;
-      }
-      const backupSuffix = crypto.randomBytes(6).toString("hex");
-      const backupPath = targetPath + `.patch-backup-${backupSuffix}`;
-      try {
-        await fs.copyFile(targetPath, backupPath);
-        targetBackups.set(targetPath, backupPath);
-      } catch (err) {
-        const code = getErrnoCode(err);
-        if (code === "ENOENT") {
-          return;
-        }
-        throw err;
-      }
-    };
-
-    const backupSourceRemovalPath = async (sourcePath: string): Promise<void> => {
-      if (sourceRemovalBackups.has(sourcePath)) {
-        return;
-      }
-      const backupSuffix = crypto.randomBytes(6).toString("hex");
-      const backupPath = sourcePath + `.patch-source-backup-${backupSuffix}`;
-      await fs.copyFile(sourcePath, backupPath);
-      sourceRemovalBackups.set(sourcePath, backupPath);
-    };
-
-    const unlinkSourcePath = async (sourcePath: string): Promise<void> => {
-      try {
-        await fs.unlink(sourcePath);
-        removedSources.push(sourcePath);
-      } catch (err) {
-        const code = getErrnoCode(err);
-        // If the path is already gone, desired end-state (removed) is satisfied.
-        if (code === "ENOENT") {
-          return;
-        }
-        throw err;
-      }
-    };
-
-    try {
-      // Backup all existing target files that may be overwritten.
-      for (const action of actions) {
-        if (action.type === "delete") continue;
-        await backupTargetIfExists(action.resolvedPath);
-      }
-
-      // Backup all files that will be removed (delete + move source path).
-      for (const action of actions) {
-        if (action.type === "delete") {
-          await backupSourceRemovalPath(action.resolvedPath);
-          continue;
-        }
-        if (
-          action.type === "move" &&
-          action.sourcePath &&
-          action.sourcePath !== action.resolvedPath
-        ) {
-          await backupSourceRemovalPath(action.sourcePath);
-        }
-      }
-
-      let tempIdx = 0;
-      for (const action of actions) {
-        if (action.type === "delete") continue;
-
-        const tempPath = tempFiles[tempIdx]!;
-        await fs.rename(tempPath, action.resolvedPath);
-        appliedTargets.push(action.resolvedPath);
-        tempIdx++;
-      }
-
-      // Apply delete/move source removals as part of the same transaction.
-      for (const action of actions) {
-        if (action.type === "delete") {
-          await unlinkSourcePath(action.resolvedPath);
-        } else if (
-          action.type === "move" &&
-          action.sourcePath &&
-          action.sourcePath !== action.resolvedPath
-        ) {
-          await unlinkSourcePath(action.sourcePath);
-        }
-      }
-    } catch (renameErr) {
-      // Rollback: restore backup-backed targets, remove newly-created targets
-      for (let idx = appliedTargets.length - 1; idx >= 0; idx--) {
-        const target = appliedTargets[idx]!;
-        const backup = targetBackups.get(target);
-        try {
-          if (backup) {
-            await fs.rename(backup, target);
-          } else {
-            await fs.unlink(target);
-          }
-        } catch {
-          /* best-effort */
-        }
-      }
-
-      // Rollback removed source paths (delete/move) in reverse order.
-      for (let idx = removedSources.length - 1; idx >= 0; idx--) {
-        const sourcePath = removedSources[idx]!;
-        const backup = sourceRemovalBackups.get(sourcePath);
-        if (!backup) continue;
-        try {
-          await fs.rename(backup, sourcePath);
-          sourceRemovalBackups.delete(sourcePath);
-        } catch {
-          /* best-effort */
-        }
-      }
-
-      // Clean up any remaining backup files
-      for (const backup of targetBackups.values()) {
-        try {
-          await fs.unlink(backup);
-        } catch {
-          /* best-effort */
-        }
-      }
-      for (const backup of sourceRemovalBackups.values()) {
-        try {
-          await fs.unlink(backup);
-        } catch {
-          /* best-effort */
-        }
-      }
-      // Clean up any remaining temp files
-      for (const tempPath of tempFiles) {
-        try {
-          await fs.unlink(tempPath);
-        } catch {
-          /* best-effort */
-        }
-      }
-      throw renameErr; // Will be caught by outer try/catch
-    }
-
-    // Success — clean up backups
-    for (const backup of targetBackups.values()) {
-      try {
-        await fs.unlink(backup);
-      } catch {
-        /* best-effort */
-      }
-    }
-    for (const backup of sourceRemovalBackups.values()) {
-      try {
-        await fs.unlink(backup);
-      } catch {
-        /* best-effort */
-      }
-    }
-
-    // Build summary
-    const filesChanged = actions.length;
-    const created = actions.filter((a) => a.type === "create").length;
-    const modified = actions.filter((a) => a.type === "modify").length;
-    const deleted = actions.filter((a) => a.type === "delete").length;
-    const moved = actions.filter((a) => a.type === "move").length;
-
-    const parts: string[] = [];
-    if (created > 0) parts.push(`${created} created`);
-    if (modified > 0) parts.push(`${modified} modified`);
-    if (moved > 0) parts.push(`${moved} moved`);
-    if (deleted > 0) parts.push(`${deleted} deleted`);
-
-    const summary =
-      `Patch applied: ${filesChanged} file${filesChanged !== 1 ? "s" : ""} ` +
-      `(${parts.join(", ")}), +${totalAdded}/-${totalRemoved} lines`;
-
-    for (const action of actions) {
-      if (action.type === "delete") {
-        recordFrgMutation(action.resolvedPath, "delete");
-        recordSearchMutation(action.resolvedPath, "delete");
-      } else {
-        recordFrgMutation(action.resolvedPath, "write", action.content);
-        recordSearchMutation(action.resolvedPath, "write", action.content);
-        if (
-          action.type === "move" &&
-          action.sourcePath &&
-          action.sourcePath !== action.resolvedPath
-        ) {
-          recordFrgMutation(action.sourcePath, "delete");
-          recordSearchMutation(action.sourcePath, "delete");
-        }
-      }
-    }
-
-    return success(summary, {
-      filesChanged,
-      created,
-      modified,
-      moved,
-      deleted,
-      linesAdded: totalAdded,
-      linesRemoved: totalRemoved,
-      files: actions.map((a) => ({
-        path: a.type === "move" ? `${a.sourcePath} -> ${a.resolvedPath}` : a.resolvedPath,
-        action: a.type,
-      })),
-    });
-  } catch (err) {
-    // Cleanup: remove all temp files on failure
-    for (const tempPath of tempFiles) {
-      try {
-        await fs.unlink(tempPath);
-      } catch {
-        // Best-effort cleanup
-      }
-    }
-    return fail(`Patch application failed: ${getErrorMessage(err)}`);
-  }
-}
-
-// ============================================================================
-// Main Executor
-// ============================================================================
-
-/**
- * Execute the apply_patch tool.
- *
- * Parses a unified diff, validates all paths for security,
- * and applies changes atomically.
- */
-export async function executeApplyPatch(
-  input: ApplyPatchInput,
-  ctx: ToolContext,
-): Promise<ToolResult> {
-  try {
-    if (!input.patch || input.patch.trim() === "") {
-      return fail("Patch content is empty");
-    }
-
-    // Size guard: reject patches > 1MB to prevent memory exhaustion
-    const MAX_PATCH_SIZE = 1_048_576; // 1MB
-    if (input.patch.length > MAX_PATCH_SIZE) {
-      return fail(`Patch too large: ${input.patch.length} bytes (max: ${MAX_PATCH_SIZE})`);
-    }
-
-    // Determine working directory
-    const cwd = input.cwd ? nodePath.resolve(ctx.workingDir, input.cwd) : ctx.workingDir;
-
-    // SECURITY: Validate cwd is within the working directory
-    if (input.cwd) {
-      let realCwd: string;
-      try {
-        realCwd = fsSync.realpathSync(cwd);
-      } catch {
-        return fail(`Working directory does not exist: ${cwd}`);
-      }
-      let realWorkingDir: string;
-      try {
-        realWorkingDir = fsSync.realpathSync(ctx.workingDir);
-      } catch {
-        return fail(`Base working directory does not exist: ${ctx.workingDir}`);
-      }
-      if (!isPathWithinBase(realCwd, realWorkingDir)) {
-        return fail(`cwd must be within the working directory: ${input.cwd}`);
-      }
-    }
-
-    // Verify cwd exists and is a directory
-    try {
-      const stat = await fs.stat(cwd);
-      if (!stat.isDirectory()) {
-        return fail(`Working directory is not a directory: ${cwd}`);
-      }
-    } catch {
-      return fail(`Working directory does not exist: ${cwd}`);
-    }
-
-    // Step 1: Parse patch input (unified diff or apply_patch envelope)
-    let diffs: FileDiff[];
-    try {
-      diffs = parsePatchInput(input.patch);
-    } catch (err) {
-      return fail(`Failed to parse patch: ${getErrorMessage(err)}`);
-    }
-
-    if (diffs.length === 0) {
-      return fail("No file diffs found in patch");
-    }
-
-    // Step 2: Validate paths (SECURITY-CRITICAL)
-    // Check for Windows drive letters in paths (cross-platform safety)
-    for (const diff of diffs) {
-      for (const p of [diff.oldPath, diff.newPath]) {
-        if (p !== null && isWindowsDrivePath(p)) {
-          return fail(`Absolute path not allowed in patch: ${p}`);
-        }
-      }
-    }
-
-    const validation = validatePatchPaths(diffs, cwd);
-    if (!validation.valid) {
-      return fail(validation.error);
-    }
-
-    // Step 3: Apply atomically
-    return await applyPatchAtomic(diffs, validation.resolved);
-  } catch (err) {
-    return fail(`apply_patch failed: ${getErrorMessage(err)}`);
-  }
-}