@4da/mcp-server 5.0.4 → 6.0.1

package/dist/tools/upgrade-planner.js

@@ -2,9 +2,12 @@
 /**
  * upgrade_planner tool
  *
- * Ranked standalone upgrade recommendations for project dependencies.
- * Combines version freshness, vulnerability data, and deprecation status
- * to produce a prioritized upgrade plan.
+ * One brain (AD-049): when the 4DA app's database holds its persisted Upgrade
+ * Plan (current schema), the tool returns that plan's machine-readable work
+ * order (`provenance.mode: "app_plan"`, flagged `stale` past its horizon) —
+ * see ./app-plan.ts. Only without one does it run the standalone heuristic
+ * below: version freshness, vulnerability data and deprecation status from
+ * the local lockfiles (`provenance.mode: "standalone_heuristic"`).
  *
  * Honesty contract (Phase 0 hardening):
  * - Transitive CVEs are surfaced as `waiting_on_upstream` steps instead of
@@ -14,15 +17,26 @@
  *   standalone plan, not the 4DA app's cross-project, version-confirmed plan.
  * - `projectPath` reports the directory set the dependencies were actually
  *   resolved from, not whatever `process.cwd()` happens to be.
- * - When no vulnerability scan has run, the plan says so instead of silently
- *   producing a CVE-blind ranking.
+ * - When no vulnerability scan has run, the planner runs one (bounded); if it
+ *   cannot finish, the plan says it is CVE-blind instead of ranking silently.
+ * - When node_modules holds a different version than the lockfile, the row
+ *   says so (`installedVersion`) and a reinstall is the step when nothing
+ *   else about the lockfile's version needs changing.
  */
-import { compareSemver, maxSemver } from "../live/semver-utils.js";
+import { 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 { dirsLabel, driftFor } from "./install-drift-notes.js";
+import { emptyAnswerNote } from "./package-presence.js";
+import { relativeDir } from "./vulnerability-scan-format.js";
+/** 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.";
+    "Not the 4DA desktop app's cross-project, version-confirmed plan (none was available).";
 export const upgradePlannerTool = {
     name: "upgrade_planner",
-    description: "Ranked standalone upgrade recommendations for dependencies — call before upgrading, adding, or auditing any dependency to pick the safest order. Prioritizes by vulnerability severity (direct AND transitive), deprecation, and version distance. Splits quick wins (patch/minor) from breaking changes (major) and from transitive CVEs waiting on upstream. Run vulnerability_scan first for a CVE-aware plan. Privacy: live mode may query public registries and OSV with package names and versions; it never sends source code.",
+    description: "Ranked dependency upgrade plan — call before upgrading, adding, or auditing any dependency to pick the safest order. 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), 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.",
     inputSchema: {
         type: "object",
         properties: {
@@ -39,6 +53,10 @@ export const upgradePlannerTool = {
                 enum: ["all", "low", "medium", "high", "critical"],
                 description: "Only show upgrades at or above this risk level. Default: all",
             },
+            package: {
+                type: "string",
+                description: "Plan for this one package only (exact name, any ecosystem). Default: every dependency.",
+            },
         },
     },
 };
@@ -50,7 +68,26 @@ function severityToRisk(severities) {
         return "high";
     return "medium";
 }
-export async function executeUpgradePlanner(_db, params, liveIntel) {
+/** Distance between the installed and target versions (patch/minor/major), or unknown. */
+function upgradeTypeBetween(current, target) {
+    if (!current || !target)
+        return "unknown";
+    const distance = computeSemverDistance(current, target);
+    return !distance || distance.label === "up-to-date" ? "unknown" : distance.label;
+}
+function higherRisk(a, b) {
+    return RISK_LEVELS[b] > RISK_LEVELS[a] ? b : a;
+}
+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).
+    const appPlan = readAppPlan(db);
+    if (appPlan.kind === "plan")
+        return formatAppPlan(appPlan, params);
+    const standalone = await executeStandalonePlanner(params, liveIntel);
+    return { ...standalone, appPlanUnavailable: appPlan.reason };
+}
+async function executeStandalonePlanner(params, liveIntel) {
     if (!liveIntel || !liveIntel.isInitialized()) {
         return {
             generatedAt: new Date().toISOString(),
@@ -65,21 +102,52 @@ export async function executeUpgradePlanner(_db, params, liveIntel) {
             provenance: { mode: "standalone_heuristic", note: PROVENANCE_NOTE },
         };
     }
+    // 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;
+    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);
-    // Vulnerability data from the last scan this session (no network here).
-    const vulnResult = liveIntel.getVulnerabilities();
+    const drift = liveIntel.getInstallDrift();
+    const root = liveIntel.getProjectRoot() ?? process.cwd();
+    // Vulnerability data at the plan's scope, loaded here (bounded) when no scan
+    // has run. Telling the agent to "run vulnerability_scan first" made the first
+    // plan of every session CVE-blind (2026-10-03 agent eval). A plan that
+    // 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;
+    // 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
+    // the actually-vulnerable transitive anyhow 1.0.102 was hidden by the
+    // direct-name skip below. Scan entries are created per scanned instance, so
+    // the instance version is exact.
+    const instanceKey = (ecosystem, name, version) => `${ecosystem}\0${name}\0${version ?? "unknown"}`;
     const vulnsByPackage = new Map();
+    // "X is unmaintained" (RUSTSEC informational) is not a CVE and has nothing
+    // to upgrade to; it was counted as "1 known CVE" on paste, ttf-parser and
+    // five unic-* crates. Counted separately, never ranked.
+    const maintenanceNotices = new Set();
     if (vulnResult) {
         for (const v of vulnResult.vulnerabilities) {
-            if (!vulnsByPackage.has(v.package))
-                vulnsByPackage.set(v.package, []);
-            vulnsByPackage.get(v.package).push({
+            if (!named(v.package, v.ecosystem))
+                continue;
+            if (isMaintenanceNotice(v)) {
+                maintenanceNotices.add(`${v.package}@${v.currentVersion}`);
+                continue;
+            }
+            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,
@@ -92,24 +160,36 @@ export async function executeUpgradePlanner(_db, params, liveIntel) {
     const recommendations = [];
     const directPackages = new Set();
     for (const dep of registryData) {
-        directPackages.add(`${dep.ecosystem}\0${dep.name}`);
+        directPackages.add(instanceKey(dep.ecosystem, dep.name, dep.currentVersion));
         const reasons = [];
         let risk = "low";
-        let targetVersion = dep.latestStableVersion || dep.latestVersion;
+        const latestStable = dep.latestStableVersion || dep.latestVersion;
+        let targetVersion = latestStable;
         let platformActive = true;
+        let fixable = false;
         // Check vulnerabilities
-        const vulns = vulnsByPackage.get(dep.name);
+        const vulns = vulnsByPackage.get(instanceKey(dep.ecosystem, dep.name, dep.currentVersion));
         if (vulns && vulns.length > 0) {
-            risk = severityToRisk(vulns.map((v) => v.severity));
-            reasons.push(`${vulns.length} known CVE${vulns.length !== 1 ? "s" : ""} (${vulns.map((v) => v.vulnId).join(", ")})`);
+            reasons.push(`${vulns.length} known vulnerabilit${vulns.length !== 1 ? "ies" : "y"} (${vulns.map((v) => v.vulnId).join(", ")})`);
             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).
                 platformActive = false;
+                risk = "low";
                 reasons.push("Affected code is gated behind a target not active on this platform");
             }
-            // Use fixed version as target if available
+            else {
+                risk = severityToRisk(vulns.filter((v) => v.platformActive).map((v) => v.severity));
+            }
+            // The smallest version that fixes every fixable advisory: each
+            // fixedVersion is already the fix on the installed release line.
             const fixedVersions = vulns.map((v) => v.fixedVersion).filter((f) => Boolean(f));
-            if (fixedVersions.length > 0 && !targetVersion) {
-                targetVersion = maxSemver(fixedVersions);
+            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`);
+                }
             }
         }
         // Check deprecation
@@ -133,51 +213,89 @@ export async function executeUpgradePlanner(_db, params, liveIntel) {
                 reasons.push(`${d.patch} patch${d.patch !== 1 ? "es" : ""} behind`);
             }
         }
-        // Skip if no upgrade needed (no vuln, not deprecated, not behind => no reasons)
+        // Install drift: node_modules holds another version than this lockfile
+        // row, and until a reinstall the installed copy's advisories are the real
+        // exposure. Without this, a patched, up-to-date lockfile version had no
+        // reasons and the row was skipped, so a vulnerable installed copy never
+        // appeared in the plan at all.
+        const lockfileReasons = reasons.length;
+        const drifted = dep.ecosystem === "npm" ? driftFor(drift, dep.name, dep.currentVersion) : [];
+        let installedVersion;
+        let installFix;
+        if (drifted.length > 0) {
+            installedVersion = [...new Set(drifted.map((r) => r.installedVersion))].join(", ");
+            installFix = drifted[0].fix;
+            const where = dirsLabel(drifted.map((r) => r.dir), (d) => relativeDir(d, root));
+            reasons.push(`node_modules has ${installedVersion}, not the lockfile's ${dep.currentVersion} — run \`${installFix}\` in ${where}`);
+            for (const installed of new Set(drifted.map((r) => r.installedVersion))) {
+                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)));
+            }
+        }
+        // Skip if no upgrade needed (no vuln, not deprecated, not behind, no drift => no reasons)
         if (reasons.length === 0)
             continue;
         // Never recommend a downgrade: when the current version is a prerelease
         // AHEAD of the latest stable (rsa 0.10.0-rc.18 vs stable 0.9.10), the
-        // stable line is not an upgrade target. Fall back to the highest vuln
-        // fix version that IS ahead of current, else no target ("review").
+        // stable line is not an upgrade target.
         if (targetVersion &&
             dep.currentVersion &&
-            compareSemver(dep.currentVersion, targetVersion) >= 0) {
-            const vulnFixesAhead = (vulns ?? [])
-                .map((v) => v.fixedVersion)
-                .filter((f) => Boolean(f))
-                .filter((f) => compareSemver(f, dep.currentVersion) > 0);
-            targetVersion = vulnFixesAhead.length > 0 ? maxSemver(vulnFixesAhead) : null;
+            compareVersions(dep.currentVersion, targetVersion, dep.ecosystem) >= 0) {
+            targetVersion = null;
         }
-        const label = dep.versionsBehind?.label;
-        const upgradeType = !label || label === "up-to-date" ? "unknown" : label;
+        const upgradeType = upgradeTypeBetween(dep.currentVersion, targetVersion);
+        // Drift is the only problem: the lockfile's version is the target, and
+        // reinstalling it is the whole step.
+        const reinstallOnly = drifted.length > 0 && lockfileReasons === 0;
+        const vulnerable = Boolean(vulns && vulns.length > 0);
+        const action = reinstallOnly
+            ? "reinstall"
+            : vulnerable && !platformActive
+                ? "not_built_on_this_host"
+                : vulnerable && !fixable
+                    ? "no_fix_available"
+                    : targetVersion
+                        ? "upgrade_direct"
+                        : "no_fix_available";
         recommendations.push({
             package: dep.name,
             ecosystem: dep.ecosystem,
             currentVersion: dep.currentVersion,
-            targetVersion,
+            targetVersion: reinstallOnly ? dep.currentVersion : targetVersion,
+            ...(latestStable && latestStable !== targetVersion ? { latestVersion: latestStable } : {}),
             upgradeType,
             risk,
             reasons,
-            breaking: dep.versionsBehind?.label === "major",
+            breaking: upgradeType === "major",
             isDev: dep.isDev,
             scope: "direct",
-            action: "upgrade_direct",
+            action,
             platformActive,
+            ...(installedVersion ? { installedVersion, installFix } : {}),
         });
     }
     // Transitive vulnerable packages — previously counted in scan totals but
     // never recommended. Surfaced as waiting_on_upstream with honest labels.
+    // 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.
     if (vulnResult) {
         const transitive = new Map();
         for (const v of vulnResult.vulnerabilities) {
             if (v.isDirect)
                 continue;
-            if (directPackages.has(`${v.ecosystem}\0${v.package}`))
+            if (!named(v.package, v.ecosystem))
+                continue;
+            if (isMaintenanceNotice(v))
+                continue;
+            if (directPackages.has(instanceKey(v.ecosystem, v.package, v.currentVersion)))
                 continue;
             if (!includeDev && v.isDev && v.devScopeKnown)
                 continue;
-            const key = `${v.ecosystem}\0${v.package}`;
+            const key = instanceKey(v.ecosystem, v.package, v.currentVersion);
             if (!transitive.has(key))
                 transitive.set(key, []);
             transitive.get(key).push(v);
@@ -187,33 +305,44 @@ export async function executeUpgradePlanner(_db, params, liveIntel) {
             const fixedVersions = entries.map((e) => e.fixedVersion).filter((f) => Boolean(f));
             const platformActive = !entries.every((e) => !e.platformActive);
             const reasons = [
-                `${entries.length} known CVE${entries.length !== 1 ? "s" : ""} (${entries.map((e) => e.vulnId).join(", ")})`,
+                `${entries.length} known vulnerabilit${entries.length !== 1 ? "ies" : "y"} (${entries.map((e) => e.vulnId).join(", ")})`,
                 "Transitive dependency — not declared in your manifest; the fix arrives via a parent package update or a lockfile refresh",
             ];
             if (!platformActive) {
                 reasons.push("Affected code is gated behind a target not active on this platform");
             }
+            const target = fixedVersions.length > 0 ? maxVersion(fixedVersions, first.ecosystem) : null;
             recommendations.push({
                 package: first.package,
                 ecosystem: first.ecosystem,
                 currentVersion: first.currentVersion,
-                targetVersion: fixedVersions.length > 0 ? maxSemver(fixedVersions) : null,
-                upgradeType: "unknown",
-                risk: severityToRisk(entries.map((e) => e.severity)),
+                targetVersion: target,
+                upgradeType: upgradeTypeBetween(first.currentVersion, target),
+                risk: platformActive ? severityToRisk(entries.filter((e) => e.platformActive).map((e) => e.severity)) : "low",
                 reasons,
                 breaking: false,
                 isDev: entries.every((e) => e.isDev),
                 scope: "transitive",
-                action: "waiting_on_upstream",
+                action: !platformActive ? "not_built_on_this_host" : target ? "waiting_on_upstream" : "no_fix_available",
                 platformActive,
             });
         }
     }
+    // Defensive dedupe: identical (ecosystem, package, version, scope) rows can
+    // still arrive when upstream dep lists carry duplicates. Keep the first.
+    const seenRecs = new Set();
+    const deduped = recommendations.filter((r) => {
+        const key = `${r.ecosystem}\0${r.package}\0${r.currentVersion ?? ""}\0${r.scope}`;
+        if (seenRecs.has(key))
+            return false;
+        seenRecs.add(key);
+        return true;
+    });
     // Filter by risk threshold
     const threshold = params.risk_threshold ?? "all";
     const filtered = threshold === "all"
-        ? recommendations
-        : recommendations.filter((r) => RISK_LEVELS[r.risk] >= RISK_LEVELS[threshold]);
+        ? deduped
+        : deduped.filter((r) => RISK_LEVELS[r.risk] >= RISK_LEVELS[threshold]);
     // Sort: critical > high > medium > low, then fixable-now (direct) before
     // waiting-on-upstream (transitive), then non-breaking first (quick wins).
     filtered.sort((a, b) => {
@@ -228,22 +357,41 @@ export async function executeUpgradePlanner(_db, params, liveIntel) {
     });
     const maxRecs = params.max_recommendations ?? 20;
     const limited = filtered.slice(0, maxRecs);
-    const direct = limited.filter((r) => r.scope === "direct");
-    const quickWins = direct.filter((r) => !r.breaking).length;
-    const breakingChanges = direct.filter((r) => r.breaking).length;
-    const waitingOnUpstream = limited.filter((r) => r.scope === "transitive").length;
+    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 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;
     // Summary
     const parts = [];
-    parts.push(`${limited.length} recommendation${limited.length !== 1 ? "s" : ""}`);
-    if (direct.length > 0)
-        parts.push(`${direct.length} fixable directly (${quickWins} quick win${quickWins !== 1 ? "s" : ""}, ${breakingChanges} breaking)`);
+    parts.push(filtered.length > limited.length
+        ? `Showing ${limited.length} of ${filtered.length} recommendations (raise max_recommendations for the rest)`
+        : `${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)`);
+    if (reinstalls > 0)
+        parts.push(`${reinstalls} need only a reinstall (node_modules behind the lockfile)`);
     if (waitingOnUpstream > 0)
         parts.push(`${waitingOnUpstream} transitive, waiting on upstream`);
+    if (noFix > 0)
+        parts.push(`${noFix} vulnerable with no fixed release yet`);
+    if (inactive > 0)
+        parts.push(`${inactive} vulnerable only in code not built on this host`);
     const criticalCount = limited.filter((r) => r.risk === "critical").length;
     if (criticalCount > 0)
         parts.push(`${criticalCount} critical`);
+    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 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("CVE data not loaded — run vulnerability_scan first for a security-aware plan");
+        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(),

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

@@ -0,0 +1,72 @@
+/**
+ * The default `vulnerability_scan` answer: one row per vulnerable package
+ * version, ranked, bounded, and saying what it left out.
+ *
+ * It used to list one row per advisory. Measured 2026-10-03 on the pre-publish
+ * benchmark: nodejs-goof (290 advisories over 137 package versions) came to
+ * ~25k tokens and hyper-term with devDependencies to ~26k, at or past the 25k
+ * an MCP answer may use in Claude Code before it is cut off, on exactly the
+ * projects where the scan matters most. An agent acts per package ("upgrade
+ * ejs 1.0.0 to 3.1.10"), so a row is a package version: its graded severity,
+ * the smallest version that fixes every fixable advisory on it, and the
+ * advisory count with the first ids. Every advisory is still counted in
+ * `by_severity`; `response_format: "detailed"` lists them one by one.
+ */
+import { type SeverityTier } from "../live/severity-scope.js";
+import type { formatScanResult } from "./vulnerability-scan-format.js";
+type FullScan = ReturnType<typeof formatScanResult>;
+type FormattedVuln = FullScan["vulnerabilities"][number];
+export interface PackageRow {
+    package: string;
+    current_version: string;
+    severity: SeverityTier;
+    advisories: number;
+    ids: string[];
+    fixed_version: string | null;
+    unfixed_advisories?: number;
+    is_direct: boolean | null;
+    is_dev?: true;
+    source_dirs: string[];
+    summary: string;
+}
+/** One row per package version: worst graded severity, the fix that clears every fixable advisory. */
+export declare function groupByPackage(rows: FormattedVuln[]): PackageRow[];
+export declare function conciseScanResult(full: FullScan): {
+    scan_time: string;
+    project_root: string;
+    host_platform: string;
+    ecosystems_scanned: string[];
+    total_dependencies_scanned: number;
+    total_vulnerable_packages: number;
+    by_severity: import("../live/severity-scope.js").SeverityCounts;
+    vulnerable_packages: PackageRow[];
+    vulnerable_packages_note?: string | undefined;
+    recommendations: string[];
+    recommendations_note?: string | undefined;
+    not_listed: {
+        platform_inactive: {
+            count: number;
+            packages: string[];
+        };
+        maintenance_notices: {
+            count: number;
+            packages: string[];
+        };
+        install_drift: {
+            count: number;
+            vulnerable_installed: Record<string, unknown>[];
+        };
+        note: string;
+    };
+    _meta: {
+        source: string;
+        osv_cached: boolean;
+        offline: boolean;
+        relevance: string;
+        severity_rule: string;
+        lockfiles_read: number;
+        resolved_at: string | null;
+        privacy: string;
+    };
+};
+export {};

package/dist/tools/vulnerability-scan-concise.js

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The default `vulnerability_scan` answer: one row per vulnerable package
+ * version, ranked, bounded, and saying what it left out.
+ *
+ * It used to list one row per advisory. Measured 2026-10-03 on the pre-publish
+ * benchmark: nodejs-goof (290 advisories over 137 package versions) came to
+ * ~25k tokens and hyper-term with devDependencies to ~26k, at or past the 25k
+ * an MCP answer may use in Claude Code before it is cut off, on exactly the
+ * projects where the scan matters most. An agent acts per package ("upgrade
+ * ejs 1.0.0 to 3.1.10"), so a row is a package version: its graded severity,
+ * the smallest version that fixes every fixable advisory on it, and the
+ * advisory count with the first ids. Every advisory is still counted in
+ * `by_severity`; `response_format: "detailed"` lists them one by one.
+ */
+import { compareVersions, maxVersion } from "../live/version-compare.js";
+import { SEVERITY_RANK } from "../live/severity-scope.js";
+const MAX_PACKAGES = 40;
+const MAX_RECOMMENDATIONS = 25;
+const IDS_PER_ROW = 3;
+/** One row per package version: worst graded severity, the fix that clears every fixable advisory. */
+export function groupByPackage(rows) {
+    const groups = new Map();
+    for (const v of rows) {
+        const key = `${v.ecosystem}\0${v.package}\0${v.current_version}`;
+        groups.set(key, [...(groups.get(key) ?? []), v]);
+    }
+    const out = [];
+    for (const vulns of groups.values()) {
+        const worst = vulns.reduce((a, b) => (SEVERITY_RANK[b.severity] > SEVERITY_RANK[a.severity] ? b : a));
+        const fixes = vulns.map((v) => v.fixed_version).filter((f) => Boolean(f));
+        const unfixed = vulns.length - fixes.length;
+        const fixed = fixes.length > 0 ? maxVersion(fixes, worst.ecosystem) : null;
+        // Unknown (null) only when no advisory row knows; any direct row makes it direct.
+        const direct = vulns.some((v) => v.is_direct === true) ? true : vulns.some((v) => v.is_direct === null) ? null : false;
+        out.push({
+            package: worst.package,
+            current_version: worst.current_version,
+            severity: worst.severity,
+            advisories: vulns.length,
+            ids: vulns.slice(0, IDS_PER_ROW).map((v) => v.vuln_id),
+            fixed_version: fixed,
+            ...(unfixed > 0 ? { unfixed_advisories: unfixed } : {}),
+            is_direct: direct,
+            ...(vulns.every((v) => v.is_dev) ? { is_dev: true } : {}),
+            source_dirs: [...new Set(vulns.flatMap((v) => v.source_dirs ?? []))],
+            summary: worst.summary.length > 120 ? `${worst.summary.slice(0, 117)}...` : worst.summary,
+        });
+    }
+    // Worst first; at equal severity a direct dependency (you can bump it) first, then the busiest.
+    return out.sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity] ||
+        Number(b.is_direct === true) - Number(a.is_direct === true) ||
+        b.advisories - a.advisories ||
+        a.package.localeCompare(b.package) ||
+        compareVersions(a.current_version, b.current_version, "npm"));
+}
+export function conciseScanResult(full) {
+    const names = (rows) => [...new Set(rows.map((v) => `${v.package}@${v.current_version}`))];
+    const vulnerableDrift = full.install_drift.filter((row) => row.vulnerable_installed === true);
+    const packages = groupByPackage(full.vulnerabilities);
+    const listed = packages.slice(0, MAX_PACKAGES);
+    const recommendations = full.recommendations.slice(0, MAX_RECOMMENDATIONS);
+    const omittedPackages = packages.length - listed.length;
+    const omittedRecommendations = full.recommendations.length - recommendations.length;
+    return {
+        scan_time: full.scan_time,
+        project_root: full.project_root,
+        host_platform: full.host_platform,
+        ecosystems_scanned: full.ecosystems_scanned,
+        total_dependencies_scanned: full.total_dependencies_scanned,
+        total_vulnerable_packages: full.total_vulnerable_packages,
+        // Every listed advisory, before grouping and trimming.
+        by_severity: full.by_severity,
+        vulnerable_packages: listed,
+        ...(omittedPackages > 0
+            ? { vulnerable_packages_note: `Showing the ${listed.length} most severe of ${packages.length} vulnerable package versions; pass severity_filter (e.g. "high") or response_format: "detailed" for the rest.` }
+            : {}),
+        recommendations,
+        ...(omittedRecommendations > 0 ? { recommendations_note: `Showing ${recommendations.length} of ${full.recommendations.length}.` } : {}),
+        not_listed: {
+            platform_inactive: { count: full.platform_inactive_vulnerabilities.length, packages: names(full.platform_inactive_vulnerabilities) },
+            maintenance_notices: { count: full.maintenance_notices.length, packages: names(full.maintenance_notices) },
+            install_drift: { count: full.install_drift.length, vulnerable_installed: vulnerableDrift },
+            note: 'Pass response_format: "detailed" for one row per advisory, these rows, advisory references and resolution provenance.',
+        },
+        _meta: {
+            source: full._meta.source,
+            osv_cached: full._meta.osv_cached,
+            offline: full._meta.offline,
+            relevance: full._meta.relevance,
+            severity_rule: "`severity` is scope-adjusted (transitive caps critical at high; dev-only drops one level) and is the worst of the package version's advisories; detailed rows carry each advisory's own `advisory_severity`.",
+            lockfiles_read: full._meta.resolution.lockfiles.length,
+            resolved_at: full._meta.resolution.resolved_at,
+            privacy: full._meta.privacy,
+        },
+    };
+}