@4da/mcp-server 6.2.4 → 6.2.5

package/dist/tools/upgrade-planner.js

@@ -23,29 +23,42 @@
  *   says so (`installedVersion`) and a reinstall is the step when nothing
  *   else about the lockfile's version needs changing.
  */
-import { isMaintenanceNotice } from "../live/maintenance.js";
+import { isActionableVulnerability, isMaintenanceNotice } from "../live/maintenance.js";
 import { computeSemverDistance } from "../live/semver-utils.js";
-import { compareVersions, maxVersion, namesPackage } from "../live/version-compare.js";
-import { formatAppPlan, readAppPlan } from "./app-plan.js";
+import { compareVersions, inEcosystemForm, maxVersion, namesPackage } from "../live/version-compare.js";
+import { formatAppPlan, readAppPlan, scopeAppPlanSteps } from "./app-plan.js";
 import { dirsLabel, driftFor } from "./install-drift-notes.js";
 import { emptyAnswerNote } from "./package-presence.js";
 import { relativeDir } from "./vulnerability-scan-format.js";
-import { liveIntelFor, resolveProjectScope } from "./project-scope.js";
-import { verifyFixPaths } from "./upgrade-planner-fixpaths.js";
-import { discoveryNote } from "../project-tree.js";
+import { appTracksProject, liveIntelFor, resolveProjectScope } from "./project-scope.js";
+import { reconcileDirectTargets, verifyFixPaths } from "./upgrade-planner-fixpaths.js";
+import { groupAdvisories } from "../live/advisory-groups.js";
+import { isDevOnlyCopy, rankedSeverity } from "../live/severity-scope.js";
+import { discoveryNote, exclusionNotes, unreadableNotes } from "../project-tree.js";
+import { vulnerabilityCoverage } from "../live/scan-coverage.js";
+import { uncheckedOfferNote, vetOfferedReleases } from "../live/offered-release.js";
+/** Time the plan spends checking the newer releases its rows offer against their advisories. */
+const OFFER_CHECK_BUDGET_MS = 10_000;
+/** The newer release a registry row would offer (its latest stable), or null when it offers none. */
+function offeredUpgrade(dep) {
+    const latest = dep.latestStableVersion || dep.latestVersion;
+    if (!latest || !dep.currentVersion)
+        return null;
+    return compareVersions(latest, dep.currentVersion, dep.ecosystem) > 0 ? latest : null;
+}
 /** How long a plan waits for its own OSV scan before answering CVE-blind (the scan keeps running). */
 const PLANNER_SCAN_TIMEOUT_MS = 60_000;
 const PROVENANCE_NOTE = "Point-in-time heuristic from local lockfiles plus live registry/OSV lookups. " +
     "Not the 4DA desktop app's cross-project, version-confirmed plan (none was available).";
 export const upgradePlannerTool = {
     name: "upgrade_planner",
-    description: "Ranked dependency upgrade plan for one project — call before upgrading, adding, or auditing any dependency to pick the safest order. `project_path` picks the project (default: the one the server was started in; \"*\" for every project). When the 4DA desktop app has computed its plan, returns that plan's work order (provenance app_plan): per package the ecosystem, each installed version with its minimum clean target, upgrade type (patch/minor/major), the projects that hold it (direct/dev) and the mechanism (manifest_bump, lockfile_or_parent_update, mixed, no_fix); flagged stale past its freshness horizon. Otherwise falls back to a standalone plan from local lockfiles (provenance standalone_heuristic): the smallest version that fixes each vulnerability (direct and transitive), checked against every known advisory of the package, whether a lockfile refresh already reaches it (lockfile_refresh with the command) or a parent blocks it (waiting_on_upstream), deprecation and version distance; it runs the OSV scan itself when none has run. `package` narrows either plan to one package. Privacy: the fallback may query public registries and OSV with package names and versions; it never sends source code.",
+    description: "Ranked dependency upgrade plan for one project — call before upgrading, adding, or auditing any dependency to pick the safest order. `project_path` picks the project (default: the one the server was started in; \"*\" for every project). When the 4DA desktop app has computed its plan, returns that plan's work order (provenance app_plan): per package the ecosystem, each installed version with its minimum clean target, upgrade type (patch/minor/major), the projects that hold it (direct/dev) and the mechanism (manifest_bump, lockfile_or_parent_update, mixed, no_fix); flagged stale past its freshness horizon. Otherwise falls back to a standalone plan from local lockfiles (provenance standalone_heuristic): the smallest version that fixes each vulnerability (direct and transitive), checked against every known advisory of the package, whether a lockfile refresh already reaches it (lockfile_refresh with the command) or a parent blocks it: upgrade_parent with `parentUpgrades` naming the smallest parent release whose requirement admits a clean version (through the direct dependency it arrives by), override_or_replace with the override syntax when no parent release will (deprecated, already latest, or none admits one), waiting_on_upstream when nothing could be read; direct steps carry `upgradeCommands` and are raised to the release that also clears the transitives they pin; a copy bundled inside its owner waits on the owner; dev-only rows are included and labelled `isDev`, as in vulnerability_scan; deprecation and version distance; it runs the OSV scan itself when none has run. When OSV.dev could not answer for every dependency, `vulnerabilityDataAvailable` is false, `vulnerabilityCoverage` counts the unchecked ones and the summary starts with \"NOT CHECKED\": the plan then misses whatever those dependencies carry. `package` narrows either plan to one package. Privacy: the fallback may query public registries and OSV with package names and versions; it never sends source code.",
     inputSchema: {
         type: "object",
         properties: {
             include_dev: {
                 type: "boolean",
-                description: "Include devDependencies. Default: false",
+                description: "Dev-only packages (labelled isDev). Default (unset): vulnerable devDependencies and dev-only transitive packages are planned, as in vulnerability_scan; true also checks every devDependency for newer releases and deprecation; false leaves dev-only packages out and the summary counts them.",
             },
             max_recommendations: {
                 type: "number",
@@ -68,23 +81,32 @@ export const upgradePlannerTool = {
     },
 };
 const RISK_LEVELS = { low: 0, medium: 1, high: 2, critical: 3 };
-/** critical > high > medium > low, then fixable now (direct) before transitive, then non-breaking first (quick wins). */
+/** critical > high > medium > low, then runtime before dev-only, then fixable now (direct) before transitive, then non-breaking first (quick wins). */
 function planOrder(a, b) {
     const riskDiff = RISK_LEVELS[b.risk] - RISK_LEVELS[a.risk];
     if (riskDiff !== 0)
         return riskDiff;
+    if (a.isDev !== b.isDev)
+        return a.isDev ? 1 : -1;
     if (a.scope !== b.scope)
         return a.scope === "direct" ? -1 : 1;
     if (a.breaking !== b.breaking)
         return a.breaking ? 1 : -1;
     return 0;
 }
-function severityToRisk(severities) {
-    if (severities.includes("critical"))
-        return "critical";
-    if (severities.includes("high"))
-        return "high";
-    return "medium";
+/**
+ * The grade a row ranks by: the scope-adjusted severity vulnerability_scan presents (transitive
+ * caps critical at high; dev-only drops one level), over the 4DA app's base urgency (an ungraded
+ * advisory medium, a MAL- record high: severity-scope.ts rankedSeverity). A dev-only medium is low,
+ * as the scan presents it; it used to stay medium. Ranking on the raw grade let dev-only criticals
+ * push a runtime high out of max_recommendations (readiness review 2026-10-17, finding 6).
+ */
+function riskOf(entries) {
+    const tiers = entries.map((v) => rankedSeverity(v));
+    for (const t of ["critical", "high", "medium"])
+        if (tiers.includes(t))
+            return t;
+    return "low";
 }
 /** Distance between the installed and target versions (patch/minor/major), or unknown. */
 function upgradeTypeBetween(current, target) {
@@ -104,8 +126,15 @@ export async function executeUpgradePlanner(db, params, liveIntel) {
     // One brain: the app's plan wins whenever there is one, stale or not (a
     // stale plan is returned flagged, never silently replaced by a heuristic).
     // It covers every project the app tracks, so it is narrowed to this one.
+    // A project the app does not track is not in its plan at all; narrowing the
+    // plan to it gave "0 steps" for a project with 83 vulnerable packages
+    // (audit 6.2.5 D-1). Plan it from its own lockfiles instead.
     const appPlan = readAppPlan(db);
-    if (appPlan.kind === "plan")
+    const untracked = appPlan.kind === "plan" &&
+        scopePath !== null &&
+        scopeAppPlanSteps(appPlan.snapshot.steps, scopePath).length === 0 &&
+        !appTracksProject(db, scopePath);
+    if (appPlan.kind === "plan" && !untracked)
         return formatAppPlan(appPlan, params, scopePath);
     // The live layer already covers the server's own project; only an explicit
     // project_path elsewhere resolves another tree.
@@ -113,7 +142,10 @@ export async function executeUpgradePlanner(db, params, liveIntel) {
         ? liveIntelFor(liveIntel, db, scope)
         : liveIntel;
     const standalone = await executeStandalonePlanner(params, scoped);
-    return { ...standalone, appPlanUnavailable: appPlan.reason, projectScope: scopePath ?? standalone.projectPath };
+    const appPlanUnavailable = appPlan.kind === "plan"
+        ? `the 4DA app does not track ${scopePath}, so its plan does not cover it; this plan is computed from the project's own lockfiles`
+        : appPlan.reason;
+    return { ...standalone, appPlanUnavailable, projectScope: scopePath ?? standalone.projectPath };
 }
 async function executeStandalonePlanner(params, liveIntel) {
     if (!liveIntel || !liveIntel.isInitialized()) {
@@ -127,6 +159,7 @@ async function executeStandalonePlanner(params, liveIntel) {
             breakingChanges: 0,
             waitingOnUpstream: 0,
             lockfileRefreshes: 0,
+            parentUpgradeSteps: 0,
             vulnerabilityDataAvailable: false,
             provenance: { mode: "standalone_heuristic", note: PROVENANCE_NOTE },
         };
@@ -134,16 +167,17 @@ async function executeStandalonePlanner(params, liveIntel) {
     // A long-lived server must not plan from the versions it read at startup:
     // re-resolve if a lockfile (or node_modules) changed. Stat calls only.
     liveIntel.refreshIfLockfilesChanged();
-    const includeDev = params.include_dev ?? false;
+    // Dev dependencies by default, as vulnerability_scan (A8): leaving them out hid 30 of navcal's
+    // 34 vulnerable versions, vitest's critical among them (readiness audit H4).
+    const includeDev = params.include_dev ?? true;
     const only = params.package?.trim();
     const named = (name, ecosystem) => !only || namesPackage(only, name, ecosystem);
     let deps = liveIntel.getResolvedDeps();
-    if (!includeDev)
-        deps = deps.filter((d) => !d.isDev);
     if (only)
         deps = deps.filter((d) => named(d.name, d.ecosystem));
-    // Fetch registry data (live lookups for direct deps; cached where fresh)
-    const registryData = await liveIntel.fetchRegistryHealth(deps);
+    const devDirect = includeDev ? [] : deps.filter((d) => d.isDev);
+    if (!includeDev)
+        deps = deps.filter((d) => !d.isDev);
     const drift = liveIntel.getInstallDrift();
     const root = liveIntel.getProjectRoot() ?? process.cwd();
     // Vulnerability data at the plan's scope, loaded here (bounded) when no scan
@@ -152,7 +186,40 @@ async function executeStandalonePlanner(params, liveIntel) {
     // includes dev dependencies must not read a scan that left them out, so
     // ensureVulnerabilities rescans at the wider scope when needed.
     const vulnResult = (await liveIntel.ensureVulnerabilities(root, PLANNER_SCAN_TIMEOUT_MS, { includeDev })) ?? liveIntel.getVulnerabilities();
-    const vulnerabilityDataAvailable = vulnResult !== null;
+    // include_dev: false: the summary counts the vulnerable devDependencies it left out, when the
+    // scan read them; otherwise how many it did not check (readiness review 2026-10-17, finding 10).
+    const devScanned = devDirect.length > 0 && liveIntel.lastScanIncludesDev();
+    const devVulnerable = new Set((vulnResult?.vulnerabilities ?? []).filter((v) => v.isDirect && v.isDev && !isMaintenanceNotice(v)).map((v) => `${v.ecosystem}\0${v.package}\0${v.currentVersion}`));
+    const devDirectLeftOut = devScanned ? devDirect.filter((d) => devVulnerable.has(`${d.ecosystem}\0${d.name}\0${d.version}`)).length : 0;
+    const devDirectUnchecked = devScanned ? 0 : devDirect.length;
+    // Registry rows (freshness, deprecation) for direct deps. By default a devDependency gets one
+    // only when it is vulnerable: fetching every dev tool's registry document (typescript,
+    // @types/node, vite...) more than doubled navcal's lookups for rows no advisory asks for.
+    // include_dev: true checks every devDependency's freshness too.
+    const vulnerableNames = new Set((vulnResult?.vulnerabilities ?? []).filter((v) => !isMaintenanceNotice(v)).map((v) => `${v.ecosystem}\0${v.package}`));
+    const registryDeps = params.include_dev === undefined ? deps.filter((d) => !d.isDev || vulnerableNames.has(`${d.ecosystem}\0${d.name}`)) : deps;
+    const devFreshnessSkipped = deps.length - registryDeps.length;
+    // Fetch registry data (live lookups for direct deps; cached where fresh)
+    const registryData = await liveIntel.fetchRegistryHealth(registryDeps);
+    // Every newer release a row offers is checked as dependency_check checks one (offered-release.ts):
+    // crossenv 0.0.2-security was sent to 1.0.1, the malware itself (final release audit of 6.2.5).
+    const offerSources = liveIntel.getFixPathSources();
+    const offers = await vetOfferedReleases(offerSources, registryData
+        .filter((d) => offeredUpgrade(d) !== null)
+        .map((d) => ({ key: `${d.ecosystem}\0${d.name}\0${d.currentVersion ?? "unknown"}`, ecosystem: d.ecosystem, name: d.name, installed: d.currentVersion, offered: offeredUpgrade(d) })), OFFER_CHECK_BUDGET_MS);
+    // Complete vulnerability data only: a partial scan (OSV.dev unreachable or
+    // rate limited for some dependencies) ranks what it found and says the rest
+    // is unchecked; it never claims the plan is CVE-aware (6.2.4 said
+    // vulnerabilityDataAvailable: true over 10,568 unchecked dependencies).
+    const scopeTotal = liveIntel.getAuditDeps().filter((d) => includeDev || !isDevOnlyCopy(d)).length;
+    const coverage = vulnerabilityCoverage(vulnResult, {
+        enabled: liveIntel.isEnabled(),
+        expectedTotal: scopeTotal,
+        notLoaded: `the OSV.dev scan did not finish within ${PLANNER_SCAN_TIMEOUT_MS / 1000} s or OSV.dev was unreachable`,
+    });
+    // A project whose only manifests are ones this server does not read (pom.xml) has no data at all (audit 6.2.5 A-6).
+    const nothingReadable = (vulnResult?.totalScanned ?? 0) === 0 && (liveIntel.getDiscovery()?.notCoveredCount ?? 0) > 0;
+    const vulnerabilityDataAvailable = vulnResult !== null && coverage === null && !nothingReadable;
     // Keyed by ecosystem + name + INSTANCE version. A name-only key attached every
     // instance's CVEs to whichever row asked first: the direct anyhow 1.0.104 was
     // charged with RUSTSEC-2026-0190 (fixed in 1.0.103 — it isn't affected) while
@@ -176,13 +243,7 @@ async function executeStandalonePlanner(params, liveIntel) {
             const key = instanceKey(v.ecosystem, v.package, v.currentVersion);
             if (!vulnsByPackage.has(key))
                 vulnsByPackage.set(key, []);
-            vulnsByPackage.get(key).push({
-                severity: v.severity,
-                vulnId: v.vulnId,
-                summary: v.summary,
-                fixedVersion: v.fixedVersion,
-                platformActive: v.platformActive,
-            });
+            vulnsByPackage.get(key).push(v);
         }
     }
     // Build recommendations — direct deps (registry-informed)
@@ -194,14 +255,24 @@ async function executeStandalonePlanner(params, liveIntel) {
         directPackages.add(instanceKey(dep.ecosystem, dep.name, dep.currentVersion));
         const reasons = [];
         let risk = "low";
-        const latestStable = dep.latestStableVersion || dep.latestVersion;
+        const registryLatest = dep.latestStableVersion || dep.latestVersion;
+        // The newest release this row may offer: the registry's latest, unless an advisory affects it or
+        // the registry withdrew it; then the newest release above the installed one that is neither.
+        const offered = offeredUpgrade(dep);
+        const vet = offered ? offers.get(instanceKey(dep.ecosystem, dep.name, dep.currentVersion)) : undefined;
+        const offerNote = offered ? (vet ? vet.note : offerSources ? uncheckedOfferNote(dep.name, offered) : null) : null;
+        const latestStable = vet?.checked && vet.note ? vet.safe : registryLatest;
+        const noSafeUpgrade = Boolean(offered && vet?.checked && vet.note && vet.safe === null);
         let targetVersion = latestStable;
         let platformActive = true;
         let fixable = false;
         // Check vulnerabilities
         const vulns = vulnsByPackage.get(instanceKey(dep.ecosystem, dep.name, dep.currentVersion));
+        // One advisory per alias group: GHSA + PYSEC records of one issue counted twice (django 96 for 51, M1).
+        const groups = groupAdvisories(vulns);
+        const unfixedGroups = groups.filter((g) => !g.members.some((m) => m.fixedVersion));
         if (vulns && vulns.length > 0) {
-            reasons.push(`${vulns.length} known vulnerabilit${vulns.length !== 1 ? "ies" : "y"} (${vulns.map((v) => v.vulnId).join(", ")})`);
+            reasons.push(vulnerabilitiesReason(groups));
             if (vulns.every((v) => !v.platformActive)) {
                 // Code this host never compiles is not this host's exposure: listed,
                 // never ranked as high (openssl topped the plan on Windows).
@@ -210,7 +281,7 @@ async function executeStandalonePlanner(params, liveIntel) {
                 reasons.push("Affected code is gated behind a target not active on this platform");
             }
             else {
-                risk = severityToRisk(vulns.filter((v) => v.platformActive).map((v) => v.severity));
+                risk = riskOf(vulns.filter((v) => v.platformActive));
             }
             // The smallest version that fixes every fixable advisory: each
             // fixedVersion is already the fix on the installed release line.
@@ -218,9 +289,8 @@ async function executeStandalonePlanner(params, liveIntel) {
             if (fixedVersions.length > 0) {
                 targetVersion = maxVersion(fixedVersions, dep.ecosystem);
                 fixable = true;
-                if (fixedVersions.length < vulns.length) {
-                    reasons.push(`${vulns.length - fixedVersions.length} of them have no published fix`);
-                }
+                if (unfixedGroups.length > 0)
+                    reasons.push(noFixReason(unfixedGroups.length));
             }
         }
         // Check deprecation
@@ -229,9 +299,10 @@ async function executeStandalonePlanner(params, liveIntel) {
                 risk = "high";
             reasons.push(dep.deprecationMessage ? `Deprecated: ${dep.deprecationMessage}` : "Package is deprecated");
         }
-        // Check version distance
-        if (dep.versionsBehind) {
-            const d = dep.versionsBehind;
+        // Check version distance: to the release this row may offer, not to a known-affected latest.
+        const behind = latestStable === registryLatest ? dep.versionsBehind : latestStable && dep.currentVersion ? computeSemverDistance(dep.currentVersion, latestStable) : null;
+        if (behind && behind.label !== "up-to-date") {
+            const d = behind;
             if (d.label === "major" && d.major === 0) {
                 // A 0.x bump: breaking under caret rules, though the major number is unchanged.
                 const n = d.minor > 0 ? d.minor : d.patch;
@@ -270,13 +341,20 @@ async function executeStandalonePlanner(params, liveIntel) {
                 const installedVulns = vulnsByPackage.get(instanceKey("npm", dep.name, installed));
                 if (!installedVulns || installedVulns.length === 0)
                     continue;
-                reasons.push(`The installed ${installed} has ${installedVulns.length} known CVE${installedVulns.length !== 1 ? "s" : ""} (${installedVulns.map((v) => v.vulnId).join(", ")})`);
-                risk = higherRisk(risk, severityToRisk(installedVulns.map((v) => v.severity)));
+                const installedGroups = groupAdvisories(installedVulns);
+                reasons.push(`The installed ${installed} has ${installedGroups.length} known CVE${installedGroups.length !== 1 ? "s" : ""} (${installedGroups.map((g) => g.best.vulnId).join(", ")})`);
+                risk = higherRisk(risk, riskOf(installedVulns));
             }
         }
+        // Every newer release is known-affected or withdrawn: the row says so (crossenv: remove it).
+        if (noSafeUpgrade && offerNote)
+            reasons.push(offerNote);
         // Skip if no upgrade needed (no vuln, not deprecated, not behind, no drift => no reasons)
         if (reasons.length === 0)
             continue;
+        // The newer release it would have offered was replaced or could not be checked: said, never silent.
+        if (offerNote && !noSafeUpgrade)
+            reasons.push(offerNote);
         if (dep.declaredRange) {
             reasons.push(`No lockfile: ${dep.currentVersion} is the floor of the declared range "${dep.declaredRange}", not an installed version`);
         }
@@ -299,19 +377,26 @@ async function executeStandalonePlanner(params, liveIntel) {
                 ? "not_built_on_this_host"
                 : vulnerable && !fixable
                     ? "no_fix_available"
-                    : targetVersion
-                        ? "upgrade_direct"
-                        : "no_fix_available";
+                    : !vulnerable && noSafeUpgrade
+                        ? vet?.holding
+                            ? "remove_dependency"
+                            : "hold_current"
+                        : targetVersion
+                            ? "upgrade_direct"
+                            : "no_fix_available";
         const rec = {
             package: dep.name,
             ecosystem: dep.ecosystem,
             currentVersion: dep.currentVersion,
-            targetVersion: reinstallOnly ? dep.currentVersion : targetVersion,
+            // A vulnerable row with no fix names no release (its newest is affected too): the parent_release
+            // vectors' own_target is null there (pr-006, request 2.88.0), and verifyFixPaths names one only
+            // when a release past a last_affected bound is clean.
+            targetVersion: reinstallOnly ? dep.currentVersion : action === "no_fix_available" ? null : targetVersion,
             ...(latestStable && latestStable !== targetVersion ? { latestVersion: latestStable } : {}),
-            upgradeType,
+            upgradeType: action === "no_fix_available" ? "unknown" : upgradeType,
             risk,
             reasons,
-            breaking: upgradeType === "major",
+            breaking: action !== "no_fix_available" && upgradeType === "major",
             isDev: dep.isDev,
             scope: "direct",
             action,
@@ -321,7 +406,15 @@ async function executeStandalonePlanner(params, liveIntel) {
         };
         recommendations.push(rec);
         if (fixable && !reinstallOnly && action === "upgrade_direct" && vulns) {
-            fixPathInputs.set(rec, { fixes: vulns.map((v) => v.fixedVersion).filter((f) => Boolean(f)), sourceDirs: [] });
+            // The manifest directories that declare it: where its upgrade command runs (audit E8).
+            fixPathInputs.set(rec, {
+                fixes: vulns.map((v) => v.fixedVersion).filter((f) => Boolean(f)),
+                sourceDirs: [...new Set(vulns.flatMap((v) => v.sourceDirs ?? []))],
+                unfixed: unfixedGroups.map((g) => ({ id: g.best.vulnId, ids: [...g.ids] })),
+            });
+        }
+        else if (vulnerable && action === "no_fix_available") {
+            fixPathInputs.set(rec, { fixes: [], sourceDirs: [] });
         }
     }
     // Transitive vulnerable packages — previously counted in scan totals but
@@ -329,8 +422,10 @@ async function executeStandalonePlanner(params, liveIntel) {
     // The skip is instance-aware: a transitive instance at a DIFFERENT version
     // than a same-named direct dep is its own finding (anyhow 1.0.102 transitive
     // beside anyhow 1.0.104 direct), not a duplicate of the direct row.
+    let devTransitiveLeftOut = 0;
     if (vulnResult) {
         const transitive = new Map();
+        const devSkipped = new Set();
         for (const v of vulnResult.vulnerabilities) {
             if (v.isDirect)
                 continue;
@@ -340,19 +435,23 @@ async function executeStandalonePlanner(params, liveIntel) {
                 continue;
             if (directPackages.has(instanceKey(v.ecosystem, v.package, v.currentVersion)))
                 continue;
-            if (!includeDev && v.isDev && v.devScopeKnown)
-                continue;
             const key = instanceKey(v.ecosystem, v.package, v.currentVersion);
+            if (!includeDev && isDevOnlyCopy(v)) {
+                devSkipped.add(key);
+                continue;
+            }
             if (!transitive.has(key))
                 transitive.set(key, []);
             transitive.get(key).push(v);
         }
+        devTransitiveLeftOut = [...devSkipped].filter((k) => !transitive.has(k)).length;
         for (const entries of transitive.values()) {
             const first = entries[0];
             const fixedVersions = entries.map((e) => e.fixedVersion).filter((f) => Boolean(f));
             const platformActive = !entries.every((e) => !e.platformActive);
+            const groups = groupAdvisories(entries);
             const reasons = [
-                `${entries.length} known vulnerabilit${entries.length !== 1 ? "ies" : "y"} (${entries.map((e) => e.vulnId).join(", ")})`,
+                vulnerabilitiesReason(groups),
                 "Transitive dependency — not declared in your manifest; the fix arrives via a parent package update or a lockfile refresh",
             ];
             if (!platformActive) {
@@ -365,7 +464,7 @@ async function executeStandalonePlanner(params, liveIntel) {
                 currentVersion: first.currentVersion,
                 targetVersion: target,
                 upgradeType: upgradeTypeBetween(first.currentVersion, target),
-                risk: platformActive ? severityToRisk(entries.filter((e) => e.platformActive).map((e) => e.severity)) : "low",
+                risk: platformActive ? riskOf(entries.filter((e) => e.platformActive)) : "low",
                 reasons,
                 breaking: false,
                 isDev: entries.every((e) => e.isDev),
@@ -374,8 +473,13 @@ async function executeStandalonePlanner(params, liveIntel) {
                 platformActive,
             };
             recommendations.push(rec);
-            if (rec.action === "waiting_on_upstream") {
-                fixPathInputs.set(rec, { fixes: fixedVersions, sourceDirs: [...new Set(entries.flatMap((e) => e.sourceDirs ?? []))] });
+            if (rec.action === "waiting_on_upstream" || rec.action === "no_fix_available") {
+                const unfixed = groups.filter((g) => !g.members.some((m) => m.fixedVersion));
+                fixPathInputs.set(rec, {
+                    fixes: fixedVersions,
+                    sourceDirs: [...new Set(entries.flatMap((e) => e.sourceDirs ?? []))],
+                    unfixed: unfixed.map((g) => ({ id: g.best.vulnId, ids: [...g.ids] })),
+                });
             }
         }
     }
@@ -401,20 +505,39 @@ async function executeStandalonePlanner(params, liveIntel) {
     const limited = filtered.slice(0, maxRecs);
     // Verify the fix path of every vulnerable step the plan returns: a target
     // no advisory affects, and whether a lockfile refresh already reaches it.
-    const unverified = await verifyFixPaths(limited.filter((r) => fixPathInputs.has(r)).map((r) => ({ step: r, ...fixPathInputs.get(r) })), liveIntel);
+    const verifiedInputs = limited.filter((r) => fixPathInputs.has(r)).map((r) => ({ step: r, ...fixPathInputs.get(r) }));
+    const unverified = await verifyFixPaths(verifiedInputs, liveIntel);
+    // A direct bump must not stop at a release that still pins a vulnerable transitive a slightly
+    // newer release clears (express 4.20.0 still pins path-to-regexp 0.1.10; audit H1).
+    await reconcileDirectTargets(limited, verifiedInputs, liveIntel);
     limited.sort(planOrder);
+    // Go module versions carry their `v` in every field, as currentVersion does (audit 7e).
+    for (const r of limited) {
+        r.targetVersion = inEcosystemForm(r.ecosystem, r.targetVersion);
+        if (r.latestVersion !== undefined)
+            r.latestVersion = inEcosystemForm(r.ecosystem, r.latestVersion);
+    }
     const upgrades = limited.filter((r) => r.scope === "direct" && r.action === "upgrade_direct");
     const quickWins = upgrades.filter((r) => !r.breaking).length;
     const breakingChanges = upgrades.filter((r) => r.breaking).length;
     const waitingOnUpstream = limited.filter((r) => r.action === "waiting_on_upstream").length;
     const lockfileRefreshes = limited.filter((r) => r.action === "lockfile_refresh").length;
+    const parentUpgradeSteps = limited.filter((r) => r.action === "upgrade_parent").length;
+    const devOnly = limited.filter((r) => r.isDev).length;
+    const overrides = limited.filter((r) => r.action === "override_or_replace").length;
     const reinstalls = limited.filter((r) => r.action === "reinstall").length;
     const noFix = limited.filter((r) => r.action === "no_fix_available").length;
     const inactive = limited.filter((r) => r.action === "not_built_on_this_host").length;
+    const unverifiedParents = limited.filter((r) => r.action === "upgrade_parent_unverified").length;
+    const removals = limited.filter((r) => r.action === "remove_dependency").length;
+    const holds = limited.filter((r) => r.action === "hold_current").length;
     // Summary
     const parts = [];
+    if (coverage)
+        parts.push(`${coverage.note} This plan ranks only what the checked part showed`);
     parts.push(filtered.length > limited.length
-        ? `Showing ${limited.length} of ${filtered.length} recommendations (raise max_recommendations for the rest)`
+        ? // The counts that follow describe the rows shown, not the whole plan (audit 6.2.5 D-6: 6 waiting shown vs 43 real).
+            `Showing ${limited.length} of ${filtered.length} recommendations (raise max_recommendations for the rest); the counts below are for the ${limited.length} shown`
         : `${limited.length} recommendation${limited.length !== 1 ? "s" : ""}`);
     if (upgrades.length > 0)
         parts.push(`${upgrades.length} upgradable directly (${quickWins} non-breaking, ${breakingChanges} crossing a major version)`);
@@ -422,8 +545,19 @@ async function executeStandalonePlanner(params, liveIntel) {
         parts.push(`${reinstalls} need only a reinstall (node_modules behind the lockfile)`);
     if (lockfileRefreshes > 0)
         parts.push(`${lockfileRefreshes} transitive, fixed by a lockfile refresh (every parent already admits a clean version)`);
+    if (parentUpgradeSteps > 0)
+        parts.push(`${parentUpgradeSteps} transitive, fixed by upgrading the parent that pins it (parentUpgrades names the release)`);
+    if (unverifiedParents > 0) {
+        parts.push(`${unverifiedParents} transitive, a parent release that admits a clean version exists but no release of the declared dependency that brings it in was verified (parentUpgrades says what to check; not counted as fixed)`);
+    }
     if (waitingOnUpstream > 0)
         parts.push(`${waitingOnUpstream} transitive, waiting on upstream`);
+    if (removals > 0)
+        parts.push(`${removals} to remove or replace: no release is clean of the malware or advisories affecting the installed copy`);
+    if (holds > 0)
+        parts.push(`${holds} to keep where ${holds === 1 ? "it is" : "they are"}: every newer release is known-affected or withdrawn`);
+    if (overrides > 0)
+        parts.push(`${overrides} transitive, blocked by a parent that will not move (deprecated, already its latest release, or no release admits a clean version): override the version or replace the parent`);
     if (unverified > 0)
         parts.push(`${unverified} fix target${unverified !== 1 ? "s" : ""} checked only against the installed version's advisories (offline, or OSV or the registry did not answer in time; see fixPathChecked)`);
     if (noFix > 0)
@@ -433,20 +567,36 @@ async function executeStandalonePlanner(params, liveIntel) {
     const criticalCount = limited.filter((r) => r.risk === "critical").length;
     if (criticalCount > 0)
         parts.push(`${criticalCount} critical`);
+    if (devOnly > 0)
+        parts.push(`${devOnly} dev-only (isDev)`);
+    // The population, worded as dependency_health and vulnerability_scan word it (finding 6).
+    if (vulnResult)
+        parts.push(populationNote(vulnResult.vulnerabilities, liveIntel.getAuditDeps(), includeDev, named));
+    if (devDirectLeftOut + devTransitiveLeftOut + devDirectUnchecked > 0) {
+        const left = [];
+        if (devDirectLeftOut > 0)
+            left.push(`${devDirectLeftOut} vulnerable devDependenc${devDirectLeftOut !== 1 ? "ies" : "y"}`);
+        if (devDirectUnchecked > 0)
+            left.push(`${devDirectUnchecked} devDependenc${devDirectUnchecked !== 1 ? "ies" : "y"} not checked for vulnerabilities`);
+        if (devTransitiveLeftOut > 0)
+            left.push(`${devTransitiveLeftOut} dev-only vulnerable transitive cop${devTransitiveLeftOut !== 1 ? "ies" : "y"}`);
+        parts.push(`include_dev: false left out ${left.join(" and ")} (the default, true, plans them)`);
+    }
+    if (devFreshnessSkipped > 0) {
+        parts.push(`${devFreshnessSkipped} devDependenc${devFreshnessSkipped !== 1 ? "ies" : "y"} with no known vulnerability ${devFreshnessSkipped !== 1 ? "were" : "was"} not checked for newer releases or deprecation (include_dev: true checks them)`);
+    }
     if (maintenanceNotices.size > 0) {
         parts.push(`${maintenanceNotices.size} unmaintained-package notice${maintenanceNotices.size !== 1 ? "s" : ""} not ranked (no fix exists; see vulnerability_scan maintenance_notices)`);
     }
     const partial = discoveryNote(liveIntel.getDiscovery());
     if (partial)
         parts.push(partial.replace(/[.]$/, ""));
+    // Ecosystems not read, test fixtures left out, lockfiles that could not be read: never silent.
+    for (const note of [...exclusionNotes(liveIntel.getDiscovery()), ...unreadableNotes(liveIntel.getLockfileProblems())])
+        parts.push(note.replace(/[.]$/, ""));
     const nothing = vulnerabilityDataAvailable ? "nothing to upgrade (no known vulnerability, deprecation, or newer release of a direct dependency)" : "no vulnerability data to plan from";
     if (only && limited.length === 0)
         parts.push(emptyAnswerNote(only, liveIntel, includeDev, nothing));
-    if (!vulnerabilityDataAvailable) {
-        parts.push(liveIntel.isEnabled()
-            ? `No vulnerability data: the OSV scan did not finish within ${PLANNER_SCAN_TIMEOUT_MS / 1000}s or OSV was unreachable, so this plan is CVE-blind. Call again to use the scan once it completes`
-            : "No vulnerability data: offline mode (FOURDA_OFFLINE), so this plan is CVE-blind");
-    }
     return {
         generatedAt: new Date().toISOString(),
         projectPath: liveIntel.getProjectRoot() ?? vulnResult?.projectPath ?? process.cwd(),
@@ -457,7 +607,33 @@ async function executeStandalonePlanner(params, liveIntel) {
         breakingChanges,
         waitingOnUpstream,
         lockfileRefreshes,
+        parentUpgradeSteps,
         vulnerabilityDataAvailable,
+        ...(coverage ? { vulnerabilityCoverage: coverage } : {}),
         provenance: { mode: "standalone_heuristic", note: PROVENANCE_NOTE },
     };
 }
+/**
+ * "Planned over N vulnerable packages (M installed copies) in the full tree of T installed
+ * (K dev-only copies left out)": the same population, counted the same way, as
+ * dependency_health's vulnerableCount and vulnerability_scan's total_vulnerable_packages.
+ */
+function populationNote(vulns, tree, includeDev, named) {
+    const active = vulns.filter((v) => isActionableVulnerability(v) && (includeDev || !isDevOnlyCopy(v)) && named(v.package, v.ecosystem));
+    const packages = new Set(active.map((v) => `${v.ecosystem}\0${v.package}`)).size;
+    const copies = new Set(active.map((v) => `${v.ecosystem}\0${v.package}\0${v.currentVersion}`)).size;
+    const versioned = tree.filter((d) => d.version !== null);
+    const devOnly = versioned.filter((d) => isDevOnlyCopy(d)).length;
+    const total = includeDev ? versioned.length : versioned.length - devOnly;
+    const dev = devOnly > 0 ? (includeDev ? "; dev-only copies included" : `; ${devOnly.toLocaleString("en-US")} dev-only cop${devOnly === 1 ? "y" : "ies"} left out`) : "";
+    return `Planned over ${packages} vulnerable package${packages !== 1 ? "s" : ""} (${copies} installed cop${copies !== 1 ? "ies" : "y"}) in the full tree of ${total.toLocaleString("en-US")} installed${dev ? ` (${dev.slice(2)})` : ""}`;
+}
+/** "N known vulnerabilities (ids)", one per alias group. */
+function vulnerabilitiesReason(groups) {
+    const n = groups.length;
+    return `${n} known vulnerabilit${n !== 1 ? "ies" : "y"} (${groups.map((g) => g.best.vulnId).join(", ")})`;
+}
+/** Before the fix path is checked; verifyFixPaths rewrites it once the target is known (M2). */
+function noFixReason(n) {
+    return `${n} of them ${n === 1 ? "has" : "have"} no published fix`;
+}

package/dist/tools/vulnerability-scan-concise.d.ts

@@ -20,11 +20,18 @@ export interface PackageRow {
     package: string;
     current_version: string;
     severity: SeverityTier;
+    /** Set when the row's grade is a GHSA alias's: the worst record rates nothing itself. */
+    severity_from?: string;
+    /** A malicious-package record (MAL- id or alias, CWE-506) affects this copy. */
+    malware?: true;
     advisories: number;
     ids: string[];
     /** The version to move to: checked against every advisory of the package when fix_checked says so. */
     fixed_version: string | null;
     fix_checked: "all_advisories" | "installed_advisories_only";
+    /** Releases the registry withdrew (yanked, deprecated) that `fixed_version` steps over, and why, in plain words (FX-H5). */
+    withheld?: string[];
+    withheld_note?: string;
     unfixed_advisories?: number;
     is_direct: boolean | null;
     is_dev?: true;
@@ -34,23 +41,55 @@ export interface PackageRow {
 /** One row per package version: worst graded severity, the fix that clears every fixable advisory. */
 export declare function groupByPackage(rows: FormattedVuln[], targets?: FullScan["fix_targets"]): PackageRow[];
 export declare function conciseScanResult(full: FullScan): {
+    summary?: string | undefined;
     scan_time: string;
     project_root: string;
     host_platform: string;
     ecosystems_scanned: string[];
     total_dependencies_scanned: number;
-    total_vulnerable_packages: number;
+    dev_scope?: string | undefined;
+    total_vulnerable_packages: number | null;
     coverage?: {
         complete: false;
         note: string;
+        unchecked_dependencies?: number | undefined;
+        checked_dependencies?: number | undefined;
+        osv_status?: string | undefined;
         lockfiles_not_scanned: number;
+        unreadable_lockfiles?: {
+            path: string;
+            error: string;
+        }[] | undefined;
+        partial_lockfiles?: {
+            path: string;
+            skipped_entries: number;
+            reason: string;
+        }[] | undefined;
+        refused_includes?: {
+            path: string;
+            reason: string;
+        }[] | undefined;
+        not_covered?: {
+            path: string;
+            ecosystem: string;
+        }[] | undefined;
+        not_covered_count?: number | undefined;
+        not_scanned?: {
+            test_fixture_lockfiles: number;
+            dirs: string[];
+        } | undefined;
         unresolved_manifests?: {
             manifest: string;
             declared_ranges: number;
             fix: string;
         }[] | undefined;
     } | undefined;
-    by_severity: import("../live/severity-scope.js").SeverityCounts;
+    by_severity: import("../live/severity-scope.js").SeverityCounts | null;
+    found_in_checked_dependencies?: {
+        note: string;
+        vulnerable_packages: number;
+        by_severity: import("../live/severity-scope.js").SeverityCounts;
+    } | undefined;
     vulnerable_packages: PackageRow[];
     vulnerable_packages_note?: string | undefined;
     recommendations: string[];
@@ -79,6 +118,12 @@ export declare function conciseScanResult(full: FullScan): {
         lockfiles_read: number;
         resolved_at: string | null;
         privacy: string;
+        alias_severity?: {
+            rated_from_alias: number;
+            unresolved: string[];
+            ungraded: string[];
+            note?: string | undefined;
+        } | undefined;
     };
 };
 export {};