autoremediator 0.4.1 → 0.6.0

package/dist/{chunk-GBOD3DV6.js → chunk-ZXPLOIB7.js}

@@ -1,8 +1,8 @@
 // src/remediation/pipeline.ts
 import { generateText as generateText2 } from "ai";
-import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
-import { join as join8 } from "path";
-import semver4 from "semver";
+import { existsSync as existsSync5, readFileSync as readFileSync6 } from "fs";
+import { join as join10 } from "path";
+import semver5 from "semver";
 
 // src/platform/config.ts
 function resolveProvider(options = {}) {
@@ -836,10 +836,15 @@ async function fetchPackageVersions(packageName) {
   const data = await res.json();
   return Object.keys(data.versions);
 }
-async function findSafeUpgradeVersion(packageName, installedVersion, firstPatchedVersion, vulnerableRange) {
+async function resolveSafeUpgradeVersion(packageName, installedVersion, firstPatchedVersion, vulnerableRange) {
   const versions = await fetchPackageVersions(packageName);
-  if (!versions.length) return void 0;
-  const installedMajor = semver2.major(installedVersion);
+  if (!versions.length) {
+    return {
+      candidates: {},
+      majorOnlyFixAvailable: false
+    };
+  }
+  const installed = semver2.parse(installedVersion);
   const candidates = versions.filter((v) => semver2.valid(v) && semver2.gte(v, firstPatchedVersion)).filter((v) => {
     if (!vulnerableRange) return true;
     try {
@@ -848,17 +853,59 @@ async function findSafeUpgradeVersion(packageName, installedVersion, firstPatche
       return true;
     }
   }).sort(semver2.compare);
-  if (!candidates.length) return void 0;
-  const sameMajor = candidates.find(
-    (v) => semver2.major(v) === installedMajor
-  );
-  if (sameMajor) return sameMajor;
-  return candidates[0];
+  if (!candidates.length) {
+    return {
+      candidates: {},
+      majorOnlyFixAvailable: false
+    };
+  }
+  const categorizedCandidates = {};
+  for (const candidate of candidates) {
+    const level = classifyUpgradeLevel(installedVersion, candidate);
+    if (!level) continue;
+    if (!categorizedCandidates[level]) {
+      categorizedCandidates[level] = candidate;
+    }
+  }
+  const safeVersion = categorizedCandidates.patch ?? categorizedCandidates.minor ?? categorizedCandidates.major;
+  if (!safeVersion) {
+    return {
+      candidates: categorizedCandidates,
+      majorOnlyFixAvailable: false
+    };
+  }
+  const upgradeLevel = classifyUpgradeLevel(installedVersion, safeVersion);
+  const majorOnlyFixAvailable = !categorizedCandidates.patch && !categorizedCandidates.minor && Boolean(categorizedCandidates.major);
+  if (!installed || !upgradeLevel) {
+    return {
+      safeVersion,
+      upgradeLevel,
+      candidates: categorizedCandidates,
+      majorOnlyFixAvailable
+    };
+  }
+  return {
+    safeVersion,
+    upgradeLevel,
+    candidates: categorizedCandidates,
+    majorOnlyFixAvailable
+  };
+}
+function classifyUpgradeLevel(installedVersion, candidateVersion) {
+  const installed = semver2.parse(installedVersion);
+  const candidate = semver2.parse(candidateVersion);
+  if (!installed || !candidate) return void 0;
+  if (candidate.major > installed.major) return "major";
+  if (candidate.minor > installed.minor) return "minor";
+  if (candidate.patch > installed.patch || candidate.version === installed.version) {
+    return "patch";
+  }
+  return void 0;
 }
 
 // src/remediation/tools/find-fixed-version.ts
 var findFixedVersionTool = tool4({
-  description: "Query the npm registry to find the lowest published version of a package that is >= the first patched version. Prefer same-major upgrades. Returns undefined if no safe version exists.",
+  description: "Query the npm registry to find the safest published upgrade version for a package that is >= the first patched version. Prefer patch upgrades first, then minor, and only fall back to major when no same-major fix exists.",
   parameters: z4.object({
     packageName: z4.string().describe("The npm package name"),
     installedVersion: z4.string().describe("The currently installed version (exact semver)"),
@@ -873,15 +920,18 @@ var findFixedVersionTool = tool4({
     firstPatchedVersion,
     vulnerableRange
   }) => {
-    const safeVersion = await findSafeUpgradeVersion(
+    const resolution = await resolveSafeUpgradeVersion(
       packageName,
       installedVersion,
       firstPatchedVersion,
       vulnerableRange
     );
+    const { safeVersion, upgradeLevel, candidates, majorOnlyFixAvailable } = resolution;
     if (!safeVersion) {
       return {
+        candidates,
         isMajorBump: false,
+        majorOnlyFixAvailable: false,
         message: `No safe upgrade version found for "${packageName}". The patch-file path will be needed.`
       };
     }
@@ -890,8 +940,11 @@ var findFixedVersionTool = tool4({
     const isMajorBump = safeMajor > installedMajor;
     return {
       safeVersion,
+      upgradeLevel,
+      candidates,
       isMajorBump,
-      message: isMajorBump ? `Found safe version ${safeVersion} for "${packageName}", but it is a major bump from ${installedVersion}. Applying anyway \u2014 consumer should review for breaking changes.` : `Found safe version ${safeVersion} for "${packageName}" (from ${installedVersion}).`
+      majorOnlyFixAvailable,
+      message: isMajorBump ? `Found safe version ${safeVersion} for "${packageName}", but only a major upgrade is available from ${installedVersion}. This should remain blocked unless policy explicitly allows major bumps.` : `Found ${upgradeLevel ?? "safe"} upgrade ${safeVersion} for "${packageName}" (from ${installedVersion}).`
     };
   }
 });
@@ -1016,6 +1069,7 @@ var applyVersionBumpTool = tool5({
         toVersion,
         applied: false,
         dryRun,
+        unresolvedReason: "policy-blocked",
         message: `Policy blocked changes for package "${packageName}".`
       };
     }
@@ -1028,6 +1082,7 @@ var applyVersionBumpTool = tool5({
         toVersion,
         applied: false,
         dryRun,
+        unresolvedReason: "major-bump-required",
         message: `Policy blocked major bump for "${packageName}" (${fromVersion} -> ${toVersion}).`
       };
     }
@@ -1041,6 +1096,7 @@ var applyVersionBumpTool = tool5({
         fromVersion,
         applied: false,
         dryRun,
+        unresolvedReason: "package-json-not-found",
         message: `Could not read package.json at "${pkgPath}".`
       };
     }
@@ -1054,6 +1110,7 @@ var applyVersionBumpTool = tool5({
         fromVersion,
         applied: false,
         dryRun,
+        unresolvedReason: "indirect-dependency",
         message: `"${packageName}" was not found in package.json dependencies (it may be a transitive dep). Cannot auto-bump.`
       };
     }
@@ -1094,6 +1151,7 @@ var applyVersionBumpTool = tool5({
           toVersion,
           applied: false,
           dryRun: false,
+          unresolvedReason: "install-failed",
           message: `${commands.installPreferOffline.join(" ")} failed after updating "${packageName}" to ${toVersion}. Reverted. Error: ${message}`
         };
       }
@@ -1123,6 +1181,7 @@ var applyVersionBumpTool = tool5({
             toVersion,
             applied: false,
             dryRun: false,
+            unresolvedReason: "validation-failed",
             message: `${commands.test.join(" ")} failed after upgrading "${packageName}" to ${toVersion}. Rolled back to ${currentRange}. Error: ${message}`
           };
         }
@@ -1140,18 +1199,219 @@ var applyVersionBumpTool = tool5({
   }
 });
 
-// src/remediation/tools/fetch-package-source.ts
+// src/remediation/tools/apply-package-override.ts
 import { tool as tool6 } from "ai";
 import { z as z6 } from "zod";
-import { mkdir as mkdir2, readdir, readFile, rm as rm2 } from "fs/promises";
 import { join as join6 } from "path";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
 import { execa as execa3 } from "execa";
-var fetchPackageSourceTool = tool6({
-  description: "Download package tarball from npm and extract source files for CVE analysis. Supports custom file patterns (default: *.js, *.ts).",
+import semver4 from "semver";
+var applyPackageOverrideTool = tool6({
+  description: "Apply a package-manager-native package.json override for a vulnerable transitive dependency and reinstall. Uses npm overrides, pnpm.overrides, or yarn resolutions.",
   parameters: z6.object({
-    packageName: z6.string().min(1).describe("The npm package name (e.g., 'lodash', '@scope/package')"),
-    version: z6.string().regex(/^\d+\.\d+\.\d+/, "Must be a valid semver version").describe("Exact package version to download"),
-    filePatterns: z6.array(z6.string()).optional().default(["*.js", "*.ts"]).describe(
+    cwd: z6.string().describe("Absolute path to the consumer project root"),
+    packageManager: z6.enum(["npm", "pnpm", "yarn"]).optional().describe("Package manager used by the target project (auto-detected if omitted)"),
+    packageName: z6.string().describe("The npm package to override"),
+    fromVersion: z6.string().describe("The currently installed vulnerable version"),
+    toVersion: z6.string().describe("The safe target version to override to"),
+    dryRun: z6.boolean().default(false).describe("If true, report changes but do not write"),
+    policy: z6.string().optional().describe("Optional path to .autoremediator policy file"),
+    runTests: z6.boolean().default(false).describe("If true, run test validation after applying the override")
+  }),
+  execute: async ({
+    cwd,
+    packageManager,
+    packageName,
+    fromVersion,
+    toVersion,
+    dryRun,
+    policy,
+    runTests
+  }) => {
+    const pm = packageManager ?? detectPackageManager(cwd);
+    const commands = getPackageManagerCommands(pm);
+    const pkgPath = join6(cwd, "package.json");
+    const loadedPolicy = loadPolicy(cwd, policy);
+    if (!isPackageAllowed(loadedPolicy, packageName)) {
+      return {
+        packageName,
+        strategy: "none",
+        fromVersion,
+        toVersion,
+        applied: false,
+        dryRun,
+        unresolvedReason: "policy-blocked",
+        message: `Policy blocked changes for package "${packageName}".`
+      };
+    }
+    const isMajorBump = semver4.valid(fromVersion) && semver4.valid(toVersion) && semver4.major(toVersion) > semver4.major(fromVersion);
+    if (isMajorBump && !loadedPolicy.allowMajorBumps) {
+      return {
+        packageName,
+        strategy: "none",
+        fromVersion,
+        toVersion,
+        applied: false,
+        dryRun,
+        unresolvedReason: "major-bump-required",
+        message: `Policy blocked major override for "${packageName}" (${fromVersion} -> ${toVersion}).`
+      };
+    }
+    let pkgJson;
+    try {
+      pkgJson = JSON.parse(readFileSync4(pkgPath, "utf8"));
+    } catch {
+      return {
+        packageName,
+        strategy: "none",
+        fromVersion,
+        toVersion,
+        applied: false,
+        dryRun,
+        unresolvedReason: "package-json-not-found",
+        message: `Could not read package.json at "${pkgPath}".`
+      };
+    }
+    const overrideLabel = describeOverrideField(pm);
+    const previousValue = getOverrideValue(pkgJson, pm, packageName);
+    if (dryRun) {
+      return {
+        packageName,
+        strategy: "override",
+        fromVersion,
+        toVersion,
+        applied: false,
+        dryRun: true,
+        message: `[DRY RUN] Would set ${overrideLabel}.${packageName} to "${toVersion}", then run ${commands.installPreferOffline.join(" ")}${runTests ? ` and ${commands.test.join(" ")}` : ""}.`
+      };
+    }
+    return withRepoLock(cwd, async () => {
+      setOverrideValue(pkgJson, pm, packageName, toVersion);
+      writeFileSync2(pkgPath, JSON.stringify(pkgJson, null, 2) + "\n", "utf8");
+      try {
+        const [installCmd, ...installArgs] = commands.installPreferOffline;
+        await execa3(installCmd, installArgs, { cwd, stdio: "pipe" });
+      } catch (err) {
+        restoreOverrideValue(pkgJson, pm, packageName, previousValue);
+        writeFileSync2(pkgPath, JSON.stringify(pkgJson, null, 2) + "\n", "utf8");
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          packageName,
+          strategy: "override",
+          fromVersion,
+          toVersion,
+          applied: false,
+          dryRun: false,
+          unresolvedReason: "override-apply-failed",
+          message: `${commands.installPreferOffline.join(" ")} failed after applying ${overrideLabel} for "${packageName}" to ${toVersion}. Reverted. Error: ${message}`
+        };
+      }
+      if (runTests) {
+        try {
+          const [testCmd, ...testArgs] = commands.test;
+          await execa3(testCmd, testArgs, { cwd, stdio: "pipe" });
+        } catch (err) {
+          restoreOverrideValue(pkgJson, pm, packageName, previousValue);
+          writeFileSync2(pkgPath, JSON.stringify(pkgJson, null, 2) + "\n", "utf8");
+          try {
+            const [rollbackCmd, ...rollbackArgs] = commands.installPreferOffline;
+            await execa3(rollbackCmd, rollbackArgs, { cwd, stdio: "pipe" });
+          } catch {
+          }
+          const message = err instanceof Error ? err.message : String(err);
+          return {
+            packageName,
+            strategy: "override",
+            fromVersion,
+            toVersion,
+            applied: false,
+            dryRun: false,
+            unresolvedReason: "validation-failed",
+            message: `${commands.test.join(" ")} failed after applying ${overrideLabel} for "${packageName}" to ${toVersion}. Reverted. Error: ${message}`
+          };
+        }
+      }
+      return {
+        packageName,
+        strategy: "override",
+        fromVersion,
+        toVersion,
+        applied: true,
+        dryRun: false,
+        message: `Successfully applied ${overrideLabel} for "${packageName}" from ${fromVersion} to ${toVersion}, then ran ${commands.installPreferOffline.join(" ")}${runTests ? ` and passed ${commands.test.join(" ")}` : ""}.`
+      };
+    });
+  }
+});
+function describeOverrideField(packageManager) {
+  if (packageManager === "npm") return "overrides";
+  if (packageManager === "pnpm") return "pnpm.overrides";
+  return "resolutions";
+}
+function getOverrideValue(pkgJson, packageManager, packageName) {
+  if (packageManager === "npm") return pkgJson.overrides?.[packageName];
+  if (packageManager === "pnpm") return pkgJson.pnpm?.overrides?.[packageName];
+  return pkgJson.resolutions?.[packageName];
+}
+function setOverrideValue(pkgJson, packageManager, packageName, version) {
+  if (packageManager === "npm") {
+    pkgJson.overrides = { ...pkgJson.overrides ?? {}, [packageName]: version };
+    return;
+  }
+  if (packageManager === "pnpm") {
+    pkgJson.pnpm = {
+      ...pkgJson.pnpm ?? {},
+      overrides: {
+        ...pkgJson.pnpm?.overrides ?? {},
+        [packageName]: version
+      }
+    };
+    return;
+  }
+  pkgJson.resolutions = { ...pkgJson.resolutions ?? {}, [packageName]: version };
+}
+function restoreOverrideValue(pkgJson, packageManager, packageName, previousValue) {
+  if (packageManager === "npm") {
+    pkgJson.overrides = restoreRecord(pkgJson.overrides, packageName, previousValue);
+    return;
+  }
+  if (packageManager === "pnpm") {
+    pkgJson.pnpm = {
+      ...pkgJson.pnpm ?? {},
+      overrides: restoreRecord(pkgJson.pnpm?.overrides, packageName, previousValue)
+    };
+    if (!pkgJson.pnpm.overrides) {
+      delete pkgJson.pnpm.overrides;
+    }
+    if (Object.keys(pkgJson.pnpm).length === 0) {
+      delete pkgJson.pnpm;
+    }
+    return;
+  }
+  pkgJson.resolutions = restoreRecord(pkgJson.resolutions, packageName, previousValue);
+}
+function restoreRecord(record, key, previousValue) {
+  const nextRecord = { ...record ?? {} };
+  if (previousValue === void 0) {
+    delete nextRecord[key];
+  } else {
+    nextRecord[key] = previousValue;
+  }
+  return Object.keys(nextRecord).length > 0 ? nextRecord : void 0;
+}
+
+// src/remediation/tools/fetch-package-source.ts
+import { tool as tool7 } from "ai";
+import { z as z7 } from "zod";
+import { mkdir as mkdir2, readdir, readFile, rm as rm2 } from "fs/promises";
+import { join as join7 } from "path";
+import { execa as execa4 } from "execa";
+var fetchPackageSourceTool = tool7({
+  description: "Download package tarball from npm and extract source files for CVE analysis. Supports custom file patterns (default: *.js, *.ts).",
+  parameters: z7.object({
+    packageName: z7.string().min(1).describe("The npm package name (e.g., 'lodash', '@scope/package')"),
+    version: z7.string().regex(/^\d+\.\d+\.\d+/, "Must be a valid semver version").describe("Exact package version to download"),
+    filePatterns: z7.array(z7.string()).optional().default(["*.js", "*.ts"]).describe(
       "File patterns to extract (glob patterns, default: *.js, *.ts)"
     )
   }),
@@ -1161,23 +1421,23 @@ var fetchPackageSourceTool = tool6({
     filePatterns
   }) => {
     const tempBaseDir = `/tmp/autoremediator-pkg-${Date.now()}`;
-    const extractDir = join6(tempBaseDir, "out");
+    const extractDir = join7(tempBaseDir, "out");
     try {
       const npmUrl = `https://registry.npmjs.org/${packageName}/-/${packageName.split("/").pop()}-${version}.tgz`;
       await mkdir2(tempBaseDir, { recursive: true });
-      const tarballPath = join6(tempBaseDir, "package.tgz");
-      await execa3("curl", ["-L", "-o", tarballPath, npmUrl]);
+      const tarballPath = join7(tempBaseDir, "package.tgz");
+      await execa4("curl", ["-L", "-o", tarballPath, npmUrl]);
       await mkdir2(extractDir, { recursive: true });
-      await execa3("tar", ["-xzf", tarballPath, "-C", extractDir]);
+      await execa4("tar", ["-xzf", tarballPath, "-C", extractDir]);
       const extractedContents = await readdir(extractDir);
-      const packageRootDir = extractedContents.includes("package") ? join6(extractDir, "package") : extractDir;
+      const packageRootDir = extractedContents.includes("package") ? join7(extractDir, "package") : extractDir;
       const sourceCode = {};
       async function walkDir(dir, relativeBase) {
         try {
           const files = await readdir(dir, { withFileTypes: true });
           for (const file of files) {
-            const fullPath = join6(dir, file.name);
-            const relPath = join6(relativeBase, file.name);
+            const fullPath = join7(dir, file.name);
+            const relPath = join7(relativeBase, file.name);
             if (file.isDirectory()) {
               if (![
                 "node_modules",
@@ -1240,8 +1500,8 @@ var fetchPackageSourceTool = tool6({
 });
 
 // src/remediation/tools/generate-patch.ts
-import { tool as tool7 } from "ai";
-import { z as z7 } from "zod";
+import { tool as tool8 } from "ai";
+import { z as z8 } from "zod";
 import { generateText } from "ai";
 var VULNERABILITY_DESCRIPTIONS = {
   redos: "Regular Expression Denial of Service (ReDoS): The vulnerability is caused by poorly constructed regular expressions that cause excessive backtracking when processing certain inputs. The fix should optimize the regex to avoid catastrophic backtracking or replace it with a safer alternative.",
@@ -1249,18 +1509,18 @@ var VULNERABILITY_DESCRIPTIONS = {
   "path-traversal": "Path Traversal: The vulnerability allows access to files outside intended directories through path traversal sequences (../, etc.). The fix must validate and normalize file paths, use path.resolve() and path.relative() checks.",
   unknown: "Unknown vulnerability type: Analyze the CVE summary carefully and implement the most appropriate fix for the security issue described."
 };
-var generatePatchTool = tool7({
+var generatePatchTool = tool8({
   description: "Generate a unified diff patch for a CVE using LLM analysis of vulnerable source code.",
-  parameters: z7.object({
-    packageName: z7.string().min(1).describe("The npm package name"),
-    vulnerableVersion: z7.string().describe("The vulnerable version string"),
-    cveId: z7.string().regex(/^CVE-\d{4}-\d+$/i).describe("CVE ID (e.g., CVE-2021-23337)"),
-    cveSummary: z7.string().min(10).describe("CVE description and impact"),
-    sourceFiles: z7.record(z7.string()).describe(
+  parameters: z8.object({
+    packageName: z8.string().min(1).describe("The npm package name"),
+    vulnerableVersion: z8.string().describe("The vulnerable version string"),
+    cveId: z8.string().regex(/^CVE-\d{4}-\d+$/i).describe("CVE ID (e.g., CVE-2021-23337)"),
+    cveSummary: z8.string().min(10).describe("CVE description and impact"),
+    sourceFiles: z8.record(z8.string()).describe(
       "Map of file paths to source code contents from fetch-package-source"
     ),
-    vulnerabilityCategory: z7.enum(["redos", "code-injection", "path-traversal", "unknown"]).optional().default("unknown").describe("Category of the vulnerability for better context"),
-    dryRun: z7.boolean().optional().default(false).describe("If true, return analysis without generating patches")
+    vulnerabilityCategory: z8.enum(["redos", "code-injection", "path-traversal", "unknown"]).optional().default("unknown").describe("Category of the vulnerability for better context"),
+    dryRun: z8.boolean().optional().default(false).describe("If true, return analysis without generating patches")
   }),
   execute: async ({
     packageName,
@@ -1447,30 +1707,67 @@ function generateUnifiedDiff(original, fixed, filePath) {
 }
 
 // src/remediation/tools/apply-patch-file.ts
-import { tool as tool8 } from "ai";
-import { z as z8 } from "zod";
-import { existsSync as existsSync3 } from "fs";
+import { tool as tool9 } from "ai";
+import { z as z9 } from "zod";
+import { existsSync as existsSync4 } from "fs";
 import { mkdir as mkdir3, mkdtemp, readFile as readFile2, rm as rm3, writeFile } from "fs/promises";
 import { tmpdir } from "os";
-import { join as join7 } from "path";
-import { execa as execa4 } from "execa";
-var applyPatchFileTool = tool8({
+import { join as join9 } from "path";
+import { execa as execa6 } from "execa";
+
+// src/remediation/strategies/patch-utils.ts
+import { existsSync as existsSync3, mkdirSync, writeFileSync as writeFileSync3, readFileSync as readFileSync5 } from "fs";
+import { join as join8 } from "path";
+import { execa as execa5 } from "execa";
+function validatePatchDiff(patchContent) {
+  if (!patchContent || typeof patchContent !== "string") {
+    return {
+      valid: false,
+      error: "Patch content must be a non-empty string"
+    };
+  }
+  const hasFromLine = /^---\s+\S+/m.test(patchContent);
+  const hasToLine = /^\+\+\+\s+\S+/m.test(patchContent);
+  const hasHunkHeader = /^@@\s+-\d+/m.test(patchContent);
+  if (!hasFromLine) {
+    return {
+      valid: false,
+      error: 'Missing "---" line in patch format'
+    };
+  }
+  if (!hasToLine) {
+    return {
+      valid: false,
+      error: 'Missing "+++" line in patch format'
+    };
+  }
+  if (!hasHunkHeader) {
+    return {
+      valid: false,
+      error: "No hunk headers (@@...) found in patch"
+    };
+  }
+  return { valid: true };
+}
+
+// src/remediation/tools/apply-patch-file.ts
+var applyPatchFileTool = tool9({
   description: "Write generated patch file and apply it using package-manager-native patch flow when available, falling back to patch-package when needed.",
-  parameters: z8.object({
-    packageName: z8.string().min(1).describe("The npm package name"),
-    vulnerableVersion: z8.string().describe("The vulnerable version string"),
-    patchContent: z8.string().min(10).optional().describe("Unified diff patch content from generate-patch"),
-    patches: z8.array(
-      z8.object({
-        filePath: z8.string().min(1),
-        unifiedDiff: z8.string().min(10)
+  parameters: z9.object({
+    packageName: z9.string().min(1).describe("The npm package name"),
+    vulnerableVersion: z9.string().describe("The vulnerable version string"),
+    patchContent: z9.string().min(10).optional().describe("Unified diff patch content from generate-patch"),
+    patches: z9.array(
+      z9.object({
+        filePath: z9.string().min(1),
+        unifiedDiff: z9.string().min(10)
       })
     ).optional().describe("Patch list from generate-patch; first patch is applied"),
-    patchesDir: z8.string().optional().default("./patches").describe("Directory to store patch files"),
-    cwd: z8.string().describe("Project root directory (for package.json)"),
-    packageManager: z8.enum(["npm", "pnpm", "yarn"]).optional().describe("Package manager used by the target project (auto-detected if omitted)"),
-    validateWithTests: z8.boolean().optional().default(true).describe("Run package manager test command to validate patch doesn't break anything"),
-    dryRun: z8.boolean().optional().default(false).describe("If true, report but do not mutate files")
+    patchesDir: z9.string().optional().default("./patches").describe("Directory to store patch files"),
+    cwd: z9.string().describe("Project root directory (for package.json)"),
+    packageManager: z9.enum(["npm", "pnpm", "yarn"]).optional().describe("Package manager used by the target project (auto-detected if omitted)"),
+    validateWithTests: z9.boolean().optional().default(true).describe("Run package manager test command to validate patch doesn't break anything"),
+    dryRun: z9.boolean().optional().default(false).describe("If true, report but do not mutate files")
   }).refine((value) => Boolean(value.patchContent || value.patches && value.patches.length > 0), {
     message: "Either patchContent or patches must be provided"
   }),
@@ -1499,8 +1796,20 @@ var applyPatchFileTool = tool8({
           error: "No patch content provided."
         };
       }
+      const patchValidation = validatePatchDiff(selectedPatch);
+      if (!patchValidation.valid) {
+        return {
+          success: false,
+          packageName,
+          vulnerableVersion,
+          applied: false,
+          dryRun,
+          message: patchValidation.error ?? "Patch content is not a valid unified diff.",
+          error: patchValidation.error ?? "Patch content is not a valid unified diff."
+        };
+      }
       const patchFileName = buildPatchFileName(packageName, vulnerableVersion);
-      const patchFilePath = join7(cwd, patchesDir, patchFileName);
+      const patchFilePath = join9(cwd, patchesDir, patchFileName);
       if (dryRun) {
         return {
           success: true,
@@ -1514,11 +1823,13 @@ var applyPatchFileTool = tool8({
         };
       }
       return withRepoLock(cwd, async () => {
-        const patchesDirPath = join7(cwd, patchesDir);
+        const packageJsonSnapshot = patchModeRequiresPackageJsonSnapshot(pm, cwd) ? await capturePackageJsonSnapshot(cwd) : void 0;
+        const patchesDirPath = join9(cwd, patchesDir);
         await mkdir3(patchesDirPath, { recursive: true });
         await writeFile(patchFilePath, selectedPatch, "utf8");
         let validationResult;
         const patchMode = await resolvePatchMode(pm, cwd);
+        const commands = getPackageManagerCommands(pm);
         const applyResult = patchMode === "patch-package" ? await configurePatchPackagePostinstall(cwd, pm) : await applyNativePatch({
           cwd,
           packageName,
@@ -1527,6 +1838,14 @@ var applyPatchFileTool = tool8({
           patchMode
         });
         if (!applyResult.success) {
+          await cleanupPatchArtifacts({
+            cwd,
+            packageManager: pm,
+            patchFilePath,
+            patchMode,
+            packageJsonSnapshot,
+            rerunInstall: patchMode === "patch-package"
+          });
           return {
             success: false,
             packageName,
@@ -1541,9 +1860,49 @@ var applyPatchFileTool = tool8({
             error: applyResult.error
           };
         }
+        if (patchMode === "patch-package") {
+          try {
+            const [installCmd, ...installArgs] = commands.installPreferOffline;
+            await execa6(installCmd, installArgs, {
+              cwd,
+              stdio: "pipe"
+            });
+          } catch (err) {
+            await cleanupPatchArtifacts({
+              cwd,
+              packageManager: pm,
+              patchFilePath,
+              patchMode,
+              packageJsonSnapshot,
+              rerunInstall: true
+            });
+            const error = err instanceof Error ? err.message : String(err);
+            return {
+              success: false,
+              packageName,
+              vulnerableVersion,
+              applied: false,
+              dryRun: false,
+              message: `Failed to apply patch-package workflow for ${packageName}@${vulnerableVersion}: ${error}`,
+              patchFilePath,
+              patchPath: patchFilePath,
+              patchMode,
+              postinstallConfigured: false,
+              error: `Failed to apply patch-package workflow for ${packageName}@${vulnerableVersion}: ${error}`
+            };
+          }
+        }
         if (validateWithTests) {
           validationResult = await validatePatchWithTests(cwd, pm);
           if (!validationResult.passed) {
+            await cleanupPatchArtifacts({
+              cwd,
+              packageManager: pm,
+              patchFilePath,
+              patchMode,
+              packageJsonSnapshot,
+              rerunInstall: patchMode === "patch-package"
+            });
             const validationError = "Patch validation failed after apply; patch marked unresolved.";
             return {
               success: false,
@@ -1555,7 +1914,7 @@ var applyPatchFileTool = tool8({
               patchFilePath,
               patchPath: patchFilePath,
               patchMode,
-              postinstallConfigured: patchMode === "patch-package",
+              postinstallConfigured: false,
               validation: validationResult,
               error: validationError
             };
@@ -1593,7 +1952,7 @@ async function resolvePatchMode(packageManager, cwd) {
   if (packageManager === "npm") return "patch-package";
   if (packageManager === "pnpm") return "native-pnpm";
   try {
-    const result = await execa4("yarn", ["--version"], {
+    const result = await execa6("yarn", ["--version"], {
       cwd,
       stdio: "pipe"
     });
@@ -1604,12 +1963,17 @@ async function resolvePatchMode(packageManager, cwd) {
     return "patch-package";
   }
 }
+function patchModeRequiresPackageJsonSnapshot(packageManager, cwd) {
+  if (packageManager === "npm") return true;
+  if (packageManager === "pnpm") return false;
+  return true;
+}
 function buildPatchFileName(packageName, vulnerableVersion) {
   const safeName = packageName.replace(/^@/, "").replace(/\//g, "+");
   return `${safeName}+${vulnerableVersion}.patch`;
 }
 async function configurePatchPackagePostinstall(cwd, packageManager) {
-  const pkgJsonPath = join7(cwd, "package.json");
+  const pkgJsonPath = join9(cwd, "package.json");
   let pkgJson;
   try {
     pkgJson = JSON.parse(await readFile2(pkgJsonPath, "utf8"));
@@ -1624,7 +1988,7 @@ async function configurePatchPackagePostinstall(cwd, packageManager) {
     try {
       const commands = getPackageManagerCommands(packageManager);
       const [cmd, ...args] = commands.installDev("patch-package");
-      await execa4(cmd, args, {
+      await execa6(cmd, args, {
         cwd,
         stdio: "pipe"
       });
@@ -1648,6 +2012,32 @@ async function configurePatchPackagePostinstall(cwd, packageManager) {
   await writeFile(pkgJsonPath, JSON.stringify(pkgJson, null, 2) + "\n", "utf8");
   return { success: true };
 }
+async function capturePackageJsonSnapshot(cwd) {
+  const path = join9(cwd, "package.json");
+  try {
+    const content = await readFile2(path, "utf8");
+    return { path, content };
+  } catch {
+    return void 0;
+  }
+}
+async function cleanupPatchArtifacts(params) {
+  const { cwd, packageManager, patchFilePath, patchMode, packageJsonSnapshot, rerunInstall } = params;
+  await rm3(patchFilePath, { force: true }).catch(() => void 0);
+  if (patchMode === "patch-package" && packageJsonSnapshot) {
+    await writeFile(packageJsonSnapshot.path, packageJsonSnapshot.content, "utf8").catch(() => void 0);
+  }
+  if (!rerunInstall) return;
+  try {
+    const commands = getPackageManagerCommands(packageManager);
+    const [installCmd, ...installArgs] = commands.installPreferOffline;
+    await execa6(installCmd, installArgs, {
+      cwd,
+      stdio: "pipe"
+    });
+  } catch {
+  }
+}
 async function applyNativePatch(params) {
   const { cwd, packageName, vulnerableVersion, patchContent, patchMode } = params;
   const packageSpec = `${packageName}@${vulnerableVersion}`;
@@ -1655,7 +2045,7 @@ async function applyNativePatch(params) {
   const createArgs = ["patch", packageSpec];
   let patchDir;
   try {
-    const createResult = await execa4(createCommand, createArgs, {
+    const createResult = await execa6(createCommand, createArgs, {
       cwd,
       stdio: "pipe"
     });
@@ -1673,17 +2063,17 @@ ${createResult.stderr}`);
       error: `Could not determine native patch directory for ${packageSpec}.`
     };
   }
-  const tempPatchDir = await mkdtemp(join7(tmpdir(), "autoremediator-native-patch-"));
-  const tempPatchFile = join7(tempPatchDir, "change.patch");
+  const tempPatchDir = await mkdtemp(join9(tmpdir(), "autoremediator-native-patch-"));
+  const tempPatchFile = join9(tempPatchDir, "change.patch");
   try {
     await writeFile(tempPatchFile, patchContent, "utf8");
-    await execa4("patch", ["-p1", "-i", tempPatchFile], {
+    await execa6("patch", ["-p1", "-i", tempPatchFile], {
       cwd: patchDir,
       stdio: "pipe"
     });
     const commitCommand = patchMode === "native-pnpm" ? "pnpm" : "yarn";
     const commitArgs = patchMode === "native-pnpm" ? ["patch-commit", patchDir] : ["patch-commit", "-s", patchDir];
-    await execa4(commitCommand, commitArgs, {
+    await execa6(commitCommand, commitArgs, {
       cwd,
       stdio: "pipe"
     });
@@ -1700,12 +2090,12 @@ ${createResult.stderr}`);
 function extractPatchDirectory(output) {
   const lines = output.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
   for (const line of lines) {
-    if (existsSync3(line)) {
+    if (existsSync4(line)) {
       return line;
     }
     const tokens = line.split(/\s+/).map((token) => token.replace(/^['"]|['"]$/g, ""));
     for (const token of tokens) {
-      if (token.startsWith("/") && existsSync3(token)) {
+      if (token.startsWith("/") && existsSync4(token)) {
         return token;
       }
     }
@@ -1716,7 +2106,7 @@ async function validatePatchWithTests(cwd, packageManager) {
   try {
     const commands = getPackageManagerCommands(packageManager);
     const [cmd, ...args] = commands.test;
-    const result = await execa4(cmd, args, {
+    const result = await execa6(cmd, args, {
       cwd,
       timeout: 6e4,
       // 60 second timeout
@@ -1727,10 +2117,11 @@ async function validatePatchWithTests(cwd, packageManager) {
       output: result.stdout
     };
   } catch (err) {
-    const errorOutput = err instanceof Error && "stdout" in err ? err.stdout : "";
+    const errorOutput = typeof err === "object" && err !== null && "stdout" in err ? String(err.stdout ?? "") : "";
     const failedTests = extractFailedTests(errorOutput);
     return {
       passed: false,
+      error: failedTests.length > 0 ? `Failed tests: ${failedTests.join(", ")}` : "Package-manager test validation failed.",
       output: errorOutput,
       failedTests
     };
@@ -1743,7 +2134,7 @@ function extractFailedTests(output) {
     // Mocha style
     /●\s+(.+)(?:\n|$)/g,
     // Jest style
-    /FAIL.*?(.+?)(?:\n|$)/g
+    /^FAIL\s+(.+?)(?:\n|$)/gm
     // Generic FAIL
   ];
   for (const pattern of patterns) {
@@ -1770,6 +2161,7 @@ async function runRemediationPipeline(cveId, options = {}) {
   const runTests = options.runTests ?? false;
   const policy = options.policy ?? "";
   const patchesDir = options.patchesDir || "./patches";
+  const constraints = options.constraints ?? {};
   const model = await createModel(options);
   const systemPrompt = loadOrchestrationPrompt({
     cveId,
@@ -1778,7 +2170,8 @@ async function runRemediationPipeline(cveId, options = {}) {
     runTests,
     policy,
     patchesDir,
-    packageManager
+    packageManager,
+    constraints
   });
   const prompt = `Patch vulnerable dependencies affected by ${cveId} in the project at: ${cwd}. Package manager: ${packageManager}.`;
   const collectedResults = [];
@@ -1789,29 +2182,30 @@ async function runRemediationPipeline(cveId, options = {}) {
     ...applyVersionBumpTool,
     execute: async (input) => applyVersionBumpTool.execute({ ...input, dryRun: true })
   } : applyVersionBumpTool;
+  const applyPackageOverrideToolForRun = preview ? {
+    ...applyPackageOverrideTool,
+    execute: async (input) => applyPackageOverrideTool.execute({ ...input, dryRun: true })
+  } : applyPackageOverrideTool;
   const applyPatchFileToolForRun = preview ? {
     ...applyPatchFileTool,
     execute: async (input) => applyPatchFileTool.execute({ ...input, dryRun: true })
   } : applyPatchFileTool;
+  const tools = buildRuntimeTools({
+    applyVersionBumpToolForRun,
+    applyPackageOverrideToolForRun,
+    applyPatchFileToolForRun,
+    constraints
+  });
   const result = await generateText2({
     model,
     system: systemPrompt,
     prompt,
-    tools: {
-      "lookup-cve": lookupCveTool,
-      "check-inventory": checkInventoryTool,
-      "check-version-match": checkVersionMatchTool,
-      "find-fixed-version": findFixedVersionTool,
-      "apply-version-bump": applyVersionBumpToolForRun,
-      "fetch-package-source": fetchPackageSourceTool,
-      "generate-patch": generatePatchTool,
-      "apply-patch-file": applyPatchFileToolForRun
-    },
+    tools,
     maxSteps: 25,
     onStepFinish(stepResult) {
       agentSteps += 1;
-      const { toolResults } = stepResult;
-      for (const tr of toolResults ?? []) {
+      const toolResults = stepResult.toolResults ?? [];
+      for (const tr of toolResults) {
         const toolResult = tr.result;
         if (tr.toolName === "lookup-cve" && toolResult?.data) {
           cveDetails = toolResult.data;
@@ -1822,6 +2216,9 @@ async function runRemediationPipeline(cveId, options = {}) {
         if (tr.toolName === "apply-version-bump") {
           collectedResults.push(toolResult);
         }
+        if (tr.toolName === "apply-package-override") {
+          collectedResults.push(toolResult);
+        }
         if (tr.toolName === "apply-patch-file" && toolResult) {
           const validation = toolResult.validation;
           const message = typeof toolResult.message === "string" ? toolResult.message : typeof toolResult.error === "string" ? toolResult.error : "Patch-file strategy finished.";
@@ -1832,6 +2229,7 @@ async function runRemediationPipeline(cveId, options = {}) {
             patchFilePath: typeof toolResult.patchFilePath === "string" ? toolResult.patchFilePath : typeof toolResult.patchPath === "string" ? toolResult.patchPath : void 0,
             applied: Boolean(toolResult.applied),
             dryRun: Boolean(toolResult.dryRun),
+            unresolvedReason: !Boolean(toolResult.applied) && !Boolean(toolResult.dryRun) ? validation && validation.passed === false ? "patch-validation-failed" : "patch-apply-failed" : void 0,
             message,
             validation: validation && typeof validation.passed === "boolean" ? {
               passed: validation.passed,
@@ -1863,6 +2261,7 @@ async function runLocalRemediationPipeline(cveId, options = {}) {
   const dryRun = (options.dryRun ?? false) || preview;
   const runTests = options.runTests ?? false;
   const policy = options.policy ?? "";
+  const constraints = options.constraints ?? {};
   const collectedResults = [];
   const vulnerablePackages = [];
   let cveDetails = null;
@@ -1938,10 +2337,10 @@ async function runLocalRemediationPipeline(cveId, options = {}) {
     if (affected.ecosystem !== "npm") continue;
     const matches = installedPackages.filter((p) => p.name === affected.name);
     for (const installed of matches) {
-      if (!semver4.valid(installed.version)) continue;
+      if (!semver5.valid(installed.version)) continue;
       let isVulnerable = false;
       try {
-        isVulnerable = semver4.satisfies(installed.version, affected.vulnerableRange, {
+        isVulnerable = semver5.satisfies(installed.version, affected.vulnerableRange, {
           includePrerelease: false
         });
       } catch {
@@ -1957,14 +2356,73 @@ async function runLocalRemediationPipeline(cveId, options = {}) {
     const pkg = vulnerable.installed;
     const firstPatchedVersion = vulnerable.affected.firstPatchedVersion;
     if (pkg.type === "indirect") {
-      collectedResults.push({
+      if (constraints.directDependenciesOnly) {
+        collectedResults.push({
+          packageName: pkg.name,
+          strategy: "none",
+          fromVersion: pkg.version,
+          applied: false,
+          dryRun,
+          unresolvedReason: "constraint-blocked",
+          message: `Constraint blocked remediation for indirect dependency "${pkg.name}".`
+        });
+        continue;
+      }
+      if (constraints.preferVersionBump) {
+        collectedResults.push({
+          packageName: pkg.name,
+          strategy: "none",
+          fromVersion: pkg.version,
+          applied: false,
+          dryRun,
+          unresolvedReason: "constraint-blocked",
+          message: `Constraint prefers version-bump and rejected override remediation for "${pkg.name}".`
+        });
+        continue;
+      }
+      if (!firstPatchedVersion) {
+        collectedResults.push({
+          packageName: pkg.name,
+          strategy: "none",
+          fromVersion: pkg.version,
+          applied: false,
+          dryRun,
+          unresolvedReason: "no-safe-version",
+          message: `No firstPatchedVersion available for ${pkg.name}; cannot resolve deterministic override in local mode.`
+        });
+        continue;
+      }
+      const safeUpgrade2 = await resolveSafeUpgradeVersion(
+        pkg.name,
+        pkg.version,
+        firstPatchedVersion,
+        vulnerable.affected.vulnerableRange
+      );
+      agentSteps += 1;
+      if (!safeUpgrade2.safeVersion) {
+        collectedResults.push({
+          packageName: pkg.name,
+          strategy: "none",
+          fromVersion: pkg.version,
+          applied: false,
+          dryRun,
+          unresolvedReason: "no-safe-version",
+          message: `No safe override version found for ${pkg.name}.`
+        });
+        continue;
+      }
+      const overrideResult = await applyPackageOverrideTool.execute({
+        cwd,
+        packageManager,
         packageName: pkg.name,
-        strategy: "none",
         fromVersion: pkg.version,
-        applied: false,
+        toVersion: safeUpgrade2.safeVersion,
         dryRun,
-        message: `"${pkg.name}" is an indirect dependency; automatic version bump is limited to direct dependencies in local mode.`
+        policy,
+        runTests
       });
+      agentSteps += 1;
+      collectedResults.push(overrideResult);
       continue;
     }
     if (!firstPatchedVersion) {
@@ -1974,16 +2432,18 @@ async function runLocalRemediationPipeline(cveId, options = {}) {
         fromVersion: pkg.version,
         applied: false,
         dryRun,
+        unresolvedReason: "no-safe-version",
         message: `No firstPatchedVersion available for ${pkg.name}; cannot resolve deterministic upgrade in local mode.`
       });
       continue;
     }
-    const safeVersion = await findSafeUpgradeVersion(
+    const safeUpgrade = await resolveSafeUpgradeVersion(
       pkg.name,
       pkg.version,
       firstPatchedVersion,
       vulnerable.affected.vulnerableRange
     );
+    const safeVersion = safeUpgrade.safeVersion;
     agentSteps += 1;
     if (!safeVersion) {
       collectedResults.push({
@@ -1992,6 +2452,7 @@ async function runLocalRemediationPipeline(cveId, options = {}) {
         fromVersion: pkg.version,
         applied: false,
         dryRun,
+        unresolvedReason: "no-safe-version",
         message: `No safe upgrade version found for ${pkg.name}.`
       });
       continue;
@@ -2026,9 +2487,27 @@ async function runLocalRemediationPipeline(cveId, options = {}) {
     }
   };
 }
+function buildRuntimeTools(ctx) {
+  const tools = {
+    "lookup-cve": lookupCveTool,
+    "check-inventory": checkInventoryTool,
+    "check-version-match": checkVersionMatchTool,
+    "find-fixed-version": findFixedVersionTool,
+    "apply-version-bump": ctx.applyVersionBumpToolForRun
+  };
+  if (!ctx.constraints.directDependenciesOnly && !ctx.constraints.preferVersionBump) {
+    tools["apply-package-override"] = ctx.applyPackageOverrideToolForRun;
+  }
+  if (!ctx.constraints.preferVersionBump) {
+    tools["fetch-package-source"] = fetchPackageSourceTool;
+    tools["generate-patch"] = generatePatchTool;
+    tools["apply-patch-file"] = ctx.applyPatchFileToolForRun;
+  }
+  return tools;
+}
 function loadOrchestrationPrompt(ctx) {
-  const promptPath = join8(process.cwd(), ".github", "instructions", "orchestration.instructions.md");
-  if (!existsSync4(promptPath)) {
+  const promptPath = join10(process.cwd(), ".github", "instructions", "orchestration.instructions.md");
+  if (!existsSync5(promptPath)) {
     return `You are autoremediator, an agentic security remediation system for Node.js package dependencies.
 Working directory: ${ctx.cwd}
   Package manager: ${ctx.packageManager}
@@ -2036,6 +2515,8 @@ Dry run: ${ctx.dryRun}
 Run tests: ${ctx.runTests}
 Policy: ${ctx.policy || "undefined"}
 Patches dir: ${ctx.patchesDir}
+Direct dependencies only: ${String(ctx.constraints.directDependenciesOnly ?? false)}
+Prefer version bump: ${String(ctx.constraints.preferVersionBump ?? false)}
 
 Required sequence:
 1. lookup-cve
@@ -2043,24 +2524,25 @@ Required sequence:
 3. check-version-match
 4. find-fixed-version
 5. apply-version-bump
+6. apply-package-override
 
-Fallback sequence (when strategy="none"):
+Fallback sequence (when neither version bump nor override can be applied):
 1. fetch-package-source
 2. generate-patch
 3. apply-patch-file
 
 Always respect dryRun and policy constraints.`;
   }
-  const template = readFileSync4(promptPath, "utf8");
-  return template.replaceAll("{{cveId}}", ctx.cveId).replaceAll("{{cwd}}", ctx.cwd).replaceAll("{{packageManager}}", ctx.packageManager).replaceAll("{{dryRun}}", String(ctx.dryRun)).replaceAll("{{runTests}}", String(ctx.runTests)).replaceAll("{{policy}}", ctx.policy || "undefined").replaceAll("{{patchesDir}}", ctx.patchesDir);
+  const template = readFileSync6(promptPath, "utf8");
+  return template.replaceAll("{{cveId}}", ctx.cveId).replaceAll("{{cwd}}", ctx.cwd).replaceAll("{{packageManager}}", ctx.packageManager).replaceAll("{{dryRun}}", String(ctx.dryRun)).replaceAll("{{runTests}}", String(ctx.runTests)).replaceAll("{{policy}}", ctx.policy || "undefined").replaceAll("{{patchesDir}}", ctx.patchesDir).replaceAll("{{directDependenciesOnly}}", String(ctx.constraints.directDependenciesOnly ?? false)).replaceAll("{{preferVersionBump}}", String(ctx.constraints.preferVersionBump ?? false));
 }
 
 // src/scanner/index.ts
 import { extname } from "path";
-import { readFileSync as readFileSync8 } from "fs";
+import { readFileSync as readFileSync10 } from "fs";
 
 // src/scanner/adapters/npm-audit.ts
-import { readFileSync as readFileSync5 } from "fs";
+import { readFileSync as readFileSync7 } from "fs";
 var CVE_REGEX = /CVE-\d{4}-\d+/gi;
 function normalizeSeverity(raw) {
   if (!raw) return "UNKNOWN";
@@ -2095,12 +2577,12 @@ function parseNpmAuditJsonFromString(content) {
   return findings;
 }
 function parseNpmAuditJsonFile(filePath) {
-  const content = readFileSync5(filePath, "utf8");
+  const content = readFileSync7(filePath, "utf8");
   return parseNpmAuditJsonFromString(content);
 }
 
 // src/scanner/adapters/yarn-audit.ts
-import { readFileSync as readFileSync6 } from "fs";
+import { readFileSync as readFileSync8 } from "fs";
 var CVE_REGEX2 = /CVE-\d{4}-\d+/gi;
 function normalizeSeverity2(raw) {
   if (!raw) return "UNKNOWN";
@@ -2144,12 +2626,12 @@ function parseYarnAuditJsonFromString(content) {
   return findings;
 }
 function parseYarnAuditJsonFile(filePath) {
-  const content = readFileSync6(filePath, "utf8");
+  const content = readFileSync8(filePath, "utf8");
   return parseYarnAuditJsonFromString(content);
 }
 
 // src/scanner/adapters/sarif.ts
-import { readFileSync as readFileSync7 } from "fs";
+import { readFileSync as readFileSync9 } from "fs";
 var CVE_REGEX3 = /CVE-\d{4}-\d+/gi;
 function extractPackageName(result) {
   const pkg = result.properties?.["packageName"];
@@ -2181,7 +2663,7 @@ function parseSarifFromString(content) {
   return findings;
 }
 function parseSarifFile(filePath) {
-  const content = readFileSync7(filePath, "utf8");
+  const content = readFileSync9(filePath, "utf8");
   return parseSarifFromString(content);
 }
 
@@ -2203,7 +2685,7 @@ function inferFormat(filePath) {
   const ext = extname(filePath).toLowerCase();
   if (ext === ".sarif") return "sarif";
   try {
-    const content = readFileSync8(filePath, "utf8");
+    const content = readFileSync10(filePath, "utf8");
     const firstLine = content.split("\n").find((line) => line.trim().startsWith("{"));
     if (firstLine) {
       const parsed = JSON.parse(firstLine);
@@ -2220,8 +2702,8 @@ function uniqueCveIds(findings) {
 }
 
 // src/platform/evidence.ts
-import { mkdirSync, writeFileSync as writeFileSync2 } from "fs";
-import { join as join9 } from "path";
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync4 } from "fs";
+import { join as join11 } from "path";
 function createEvidenceLog(cwd, cveIds, context = {}) {
   return {
     runId: `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
@@ -2251,31 +2733,31 @@ function finalizeEvidence(log) {
   return log;
 }
 function writeEvidenceLog(cwd, log) {
-  const dir = join9(cwd, ".autoremediator", "evidence");
-  mkdirSync(dir, { recursive: true });
-  const filePath = join9(dir, `${log.runId}.json`);
-  writeFileSync2(filePath, JSON.stringify(log, null, 2) + "\n", "utf8");
+  const dir = join11(cwd, ".autoremediator", "evidence");
+  mkdirSync2(dir, { recursive: true });
+  const filePath = join11(dir, `${log.runId}.json`);
+  writeFileSync4(filePath, JSON.stringify(log, null, 2) + "\n", "utf8");
   return filePath;
 }
 
 // src/platform/idempotency.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync2, readFileSync as readFileSync9, writeFileSync as writeFileSync3 } from "fs";
-import { join as join10 } from "path";
+import { existsSync as existsSync6, mkdirSync as mkdirSync3, readFileSync as readFileSync11, writeFileSync as writeFileSync5 } from "fs";
+import { join as join12 } from "path";
 var DEFAULT_INDEX = {
   schemaVersion: "1.0",
   entries: {}
 };
 function indexFilePath(cwd) {
-  return join10(cwd, ".autoremediator", "state", "idempotency.json");
+  return join12(cwd, ".autoremediator", "state", "idempotency.json");
 }
 function entryKey(idempotencyKey, cveId) {
   return `${idempotencyKey}::${cveId.toUpperCase()}`;
 }
 function loadIndex(cwd) {
   const filePath = indexFilePath(cwd);
-  if (!existsSync5(filePath)) return DEFAULT_INDEX;
+  if (!existsSync6(filePath)) return DEFAULT_INDEX;
   try {
-    const parsed = JSON.parse(readFileSync9(filePath, "utf8"));
+    const parsed = JSON.parse(readFileSync11(filePath, "utf8"));
     if (parsed && parsed.schemaVersion === "1.0" && parsed.entries) {
       return parsed;
     }
@@ -2286,8 +2768,8 @@ function loadIndex(cwd) {
 }
 function saveIndex(cwd, index) {
   const filePath = indexFilePath(cwd);
-  mkdirSync2(join10(cwd, ".autoremediator", "state"), { recursive: true });
-  writeFileSync3(filePath, JSON.stringify(index, null, 2) + "\n", "utf8");
+  mkdirSync3(join12(cwd, ".autoremediator", "state"), { recursive: true });
+  writeFileSync5(filePath, JSON.stringify(index, null, 2) + "\n", "utf8");
 }
 function readIdempotentReport(cwd, idempotencyKey, cveId) {
   const index = loadIndex(cwd);
@@ -2307,6 +2789,102 @@ function storeIdempotentReport(cwd, idempotencyKey, cveId, report) {
 }
 
 // src/api.ts
+var PACKAGE_MANAGER_VALUES = ["npm", "pnpm", "yarn"];
+var LLM_PROVIDER_VALUES = ["openai", "anthropic", "local"];
+var PROVENANCE_SOURCE_VALUES = ["cli", "sdk", "mcp", "openapi", "unknown"];
+var OPTION_DESCRIPTIONS = {
+  cveId: "CVE ID, e.g. CVE-2021-23337",
+  inputPath: "Absolute path to the scanner output file",
+  cwd: "Absolute path to the project root (default: process.cwd())",
+  packageManager: "Package manager override (auto-detected by default)",
+  dryRun: "If true, plan changes but write nothing",
+  preview: "If true, enforce non-mutating preview mode",
+  runTests: "Run package-manager test command after applying fix",
+  llmProvider: "LLM provider override",
+  patchesDir: "Directory to write .patch files (default: ./patches)",
+  policy: "Optional path to .autoremediator policy file",
+  requestId: "Request correlation ID",
+  sessionId: "Session correlation ID",
+  parentRunId: "Parent run correlation ID",
+  idempotencyKey: "Idempotency key for replay-safe execution",
+  resume: "Return cached result for matching idempotency key when available",
+  actor: "Actor identity for evidence provenance",
+  source: "Source system for provenance",
+  format: "Scanner format (default: auto)",
+  evidence: "Write evidence JSON to .autoremediator/evidence/ (default: true)",
+  directDependenciesOnly: "Restrict remediation to direct dependencies only",
+  preferVersionBump: "Reject override and patch remediation when version-bump-only policy is required"
+};
+function createConstraintSchemaProperties() {
+  return {
+    directDependenciesOnly: { type: "boolean", description: OPTION_DESCRIPTIONS.directDependenciesOnly },
+    preferVersionBump: { type: "boolean", description: OPTION_DESCRIPTIONS.preferVersionBump }
+  };
+}
+function createRemediateOptionSchemaProperties(options) {
+  const includeDryRun = options?.includeDryRun ?? true;
+  const includePreview = options?.includePreview ?? true;
+  return {
+    cwd: { type: "string", description: OPTION_DESCRIPTIONS.cwd },
+    packageManager: { type: "string", enum: [...PACKAGE_MANAGER_VALUES], description: OPTION_DESCRIPTIONS.packageManager },
+    ...includeDryRun ? { dryRun: { type: "boolean", description: OPTION_DESCRIPTIONS.dryRun } } : {},
+    ...includePreview ? { preview: { type: "boolean", description: OPTION_DESCRIPTIONS.preview } } : {},
+    runTests: { type: "boolean", description: OPTION_DESCRIPTIONS.runTests },
+    llmProvider: { type: "string", enum: [...LLM_PROVIDER_VALUES], description: OPTION_DESCRIPTIONS.llmProvider },
+    patchesDir: { type: "string", description: OPTION_DESCRIPTIONS.patchesDir },
+    policy: { type: "string", description: OPTION_DESCRIPTIONS.policy },
+    requestId: { type: "string", description: OPTION_DESCRIPTIONS.requestId },
+    sessionId: { type: "string", description: OPTION_DESCRIPTIONS.sessionId },
+    parentRunId: { type: "string", description: OPTION_DESCRIPTIONS.parentRunId },
+    idempotencyKey: { type: "string", description: OPTION_DESCRIPTIONS.idempotencyKey },
+    resume: { type: "boolean", description: OPTION_DESCRIPTIONS.resume },
+    actor: { type: "string", description: OPTION_DESCRIPTIONS.actor },
+    source: { type: "string", enum: [...PROVENANCE_SOURCE_VALUES], description: OPTION_DESCRIPTIONS.source },
+    constraints: {
+      type: "object",
+      properties: createConstraintSchemaProperties()
+    }
+  };
+}
+function createScanOptionSchemaProperties() {
+  return {
+    ...createRemediateOptionSchemaProperties(),
+    format: { type: "string", enum: ["npm-audit", "yarn-audit", "sarif", "auto"], description: OPTION_DESCRIPTIONS.format },
+    evidence: { type: "boolean", description: OPTION_DESCRIPTIONS.evidence }
+  };
+}
+function createScanReportSchemaProperties() {
+  return {
+    schemaVersion: { type: "string" },
+    status: { type: "string", enum: ["ok", "partial", "failed"] },
+    generatedAt: { type: "string" },
+    cveIds: { type: "array", items: { type: "string" } },
+    reports: { type: "array", items: { type: "object" } },
+    successCount: { type: "number" },
+    failedCount: { type: "number" },
+    errors: { type: "array", items: { type: "object" } },
+    evidenceFile: { type: "string" },
+    patchCount: { type: "number" },
+    patchValidationFailures: { type: "array", items: { type: "object" } },
+    strategyCounts: {
+      type: "object",
+      additionalProperties: { type: "number" }
+    },
+    dependencyScopeCounts: {
+      type: "object",
+      additionalProperties: { type: "number" }
+    },
+    unresolvedByReason: {
+      type: "object",
+      additionalProperties: { type: "number" }
+    },
+    patchesDir: { type: "string" },
+    correlation: { type: "object" },
+    provenance: { type: "object" },
+    constraints: { type: "object" },
+    idempotencyKey: { type: "string" }
+  };
+}
 function buildRequestId() {
   return `req-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 }
@@ -2340,15 +2918,17 @@ function enforceConstraints(report, constraints) {
         ...result,
         strategy: "none",
         applied: false,
+        unresolvedReason: "constraint-blocked",
         message: `Constraint blocked remediation for indirect dependency "${result.packageName}".`
       };
     }
-    if (constraints.preferVersionBump && result.strategy === "patch-file") {
+    if (constraints.preferVersionBump && result.strategy !== "version-bump" && result.strategy !== "none") {
       return {
         ...result,
         strategy: "none",
         applied: false,
-        message: `Constraint prefers version-bump and rejected patch-file remediation for "${result.packageName}".`
+        unresolvedReason: "constraint-blocked",
+        message: `Constraint prefers version-bump and rejected ${result.strategy} remediation for "${result.packageName}".`
       };
     }
     return result;
@@ -2359,6 +2939,47 @@ function enforceConstraints(report, constraints) {
     constraints
   };
 }
+function buildStrategyCounts(reports) {
+  const counts = {};
+  for (const report of reports) {
+    for (const result of report.results) {
+      counts[result.strategy] = (counts[result.strategy] ?? 0) + 1;
+    }
+  }
+  return Object.keys(counts).length > 0 ? counts : void 0;
+}
+function toDependencyScope(installedType) {
+  return installedType === "direct" ? "direct" : "transitive";
+}
+function buildDependencyScopeCounts(reports) {
+  const counts = {};
+  for (const report of reports) {
+    const packageScopes = /* @__PURE__ */ new Map();
+    for (const vulnerablePackage of report.vulnerablePackages) {
+      const scope = toDependencyScope(vulnerablePackage.installed.type);
+      const current = packageScopes.get(vulnerablePackage.installed.name);
+      if (!current || current !== "direct") {
+        packageScopes.set(vulnerablePackage.installed.name, scope);
+      }
+    }
+    for (const result of report.results) {
+      const scope = packageScopes.get(result.packageName);
+      if (!scope) continue;
+      counts[scope] = (counts[scope] ?? 0) + 1;
+    }
+  }
+  return Object.keys(counts).length > 0 ? counts : void 0;
+}
+function buildUnresolvedReasonCounts(reports) {
+  const counts = {};
+  for (const report of reports) {
+    for (const result of report.results) {
+      if (!result.unresolvedReason) continue;
+      counts[result.unresolvedReason] = (counts[result.unresolvedReason] ?? 0) + 1;
+    }
+  }
+  return Object.keys(counts).length > 0 ? counts : void 0;
+}
 async function remediate(cveId, options = {}) {
   if (!/^CVE-\d{4}-\d+$/i.test(cveId)) {
     throw new Error(
@@ -2480,6 +3101,26 @@ async function remediateFromScan(inputPath, options = {}) {
   } else if (failedCount > 0 && successCount === 0) {
     status = "failed";
   }
+  const strategyCounts = buildStrategyCounts(reports);
+  const dependencyScopeCounts = buildDependencyScopeCounts(reports);
+  const unresolvedByReason = buildUnresolvedReasonCounts(reports);
+  let remediationCount = 0;
+  for (const report of reports) {
+    remediationCount += report.results.length;
+  }
+  evidence.summary = {
+    status,
+    cveCount: cveIds.length,
+    remediationCount,
+    successCount,
+    failedCount,
+    patchCount,
+    patchValidationFailures: patchValidationFailures.length > 0 ? patchValidationFailures : void 0,
+    strategyCounts,
+    dependencyScopeCounts,
+    unresolvedByReason,
+    patchesDir: patchCount > 0 ? patchesDir : void 0
+  };
   finalizeEvidence(evidence);
   const evidenceFile = options.evidence === false ? void 0 : writeEvidenceLog(cwd, evidence);
   return {
@@ -2494,6 +3135,9 @@ async function remediateFromScan(inputPath, options = {}) {
     evidenceFile,
     patchCount,
     patchValidationFailures: patchValidationFailures.length > 0 ? patchValidationFailures : void 0,
+    strategyCounts,
+    dependencyScopeCounts,
+    unresolvedByReason,
     patchesDir: patchCount > 0 ? patchesDir : void 0,
     correlation,
     provenance,
@@ -2518,6 +3162,9 @@ function toCiSummary(report) {
     evidenceFile: report.evidenceFile,
     patchCount: report.patchCount || 0,
     patchValidationFailures: report.patchValidationFailures,
+    strategyCounts: report.strategyCounts,
+    dependencyScopeCounts: report.dependencyScopeCounts,
+    unresolvedByReason: report.unresolvedByReason,
     patchesDir: report.patchesDir,
     correlation: report.correlation,
     provenance: report.provenance,
@@ -2528,13 +3175,83 @@ function toCiSummary(report) {
 function ciExitCode(summary) {
   return summary.failedCount > 0 ? 1 : 0;
 }
+function severityToSarifLevel(severity) {
+  if (severity === "CRITICAL" || severity === "HIGH") return "error";
+  if (severity === "MEDIUM") return "warning";
+  if (severity === "LOW") return "note";
+  return "warning";
+}
+function toSarifOutput(report) {
+  const rules = [];
+  const results = [];
+  const seenRules = /* @__PURE__ */ new Set();
+  for (const r of report.reports) {
+    const severity = r.cveDetails?.severity ?? "UNKNOWN";
+    const level = severityToSarifLevel(severity);
+    const summary = r.cveDetails?.summary ?? r.cveId;
+    if (!seenRules.has(r.cveId)) {
+      seenRules.add(r.cveId);
+      rules.push({
+        id: r.cveId,
+        name: "VulnerableDependency",
+        shortDescription: { text: r.cveId },
+        fullDescription: { text: summary },
+        defaultConfiguration: { level },
+        helpUri: `https://osv.dev/vulnerability/${r.cveId}`,
+        properties: { severity }
+      });
+    }
+    for (const vp of r.vulnerablePackages) {
+      const fixText = vp.affected.firstPatchedVersion ? ` Fix: upgrade to ${vp.affected.firstPatchedVersion}.` : " No fixed version available.";
+      results.push({
+        ruleId: r.cveId,
+        level,
+        message: {
+          text: `${vp.installed.name}@${vp.installed.version} is vulnerable to ${r.cveId}: ${summary}${fixText}`
+        },
+        locations: [
+          {
+            physicalLocation: {
+              artifactLocation: { uri: "package.json", uriBaseId: "%SRCROOT%" }
+            }
+          }
+        ]
+      });
+    }
+  }
+  return {
+    version: "2.1.0",
+    $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Documents/CommitteeSpecifications/2.1.0/sarif-schema-2.1.0.json",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "autoremediator",
+            informationUri: "https://github.com/Rawlings/autoremediator",
+            rules
+          }
+        },
+        results
+      }
+    ]
+  };
+}
 
 export {
   runRemediationPipeline,
+  PACKAGE_MANAGER_VALUES,
+  LLM_PROVIDER_VALUES,
+  PROVENANCE_SOURCE_VALUES,
+  OPTION_DESCRIPTIONS,
+  createConstraintSchemaProperties,
+  createRemediateOptionSchemaProperties,
+  createScanOptionSchemaProperties,
+  createScanReportSchemaProperties,
   remediate,
   planRemediation,
   remediateFromScan,
   toCiSummary,
-  ciExitCode
+  ciExitCode,
+  toSarifOutput
 };
-//# sourceMappingURL=chunk-GBOD3DV6.js.map
+//# sourceMappingURL=chunk-ZXPLOIB7.js.map