@aria-cli/tools 1.0.0

package/src/executors/apply-patch.ts

@@ -0,0 +1,1015 @@
+/**
+ * @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";
+
+// ============================================================================
+// 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`;
+
+    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)}`);
+  }
+}