@4da/mcp-server 6.2.3 → 6.2.5

package/dist/tools/dependency-check-signals.js

@@ -10,6 +10,8 @@
  * verdict fall through to `proceed`.
  */
 import { compareIn, isPrereleaseIn, versionParts } from "./dependency-check-versions.js";
+import { excludedReleases } from "../live/withdrawn-releases.js";
+import { heldSeverity, heldText } from "../live/held-dependencies.js";
 /** Verdict precedence, strongest first. */
 const PRECEDENCE = ["avoid", "review", "unknown", "wait", "proceed"];
 export const WAIT_DAYS = 3;
@@ -57,40 +59,82 @@ export function introducedDependencies(to, base) {
     const before = new Set(base.dependencies);
     return to.dependencies.filter((d) => !before.has(d)).sort();
 }
-export function advisoriesSignal(item, facts) {
+/**
+ * The advisories signal, with what `to` holds (npm, audit 6.2.5 D-4): a dependency it exact-pins
+ * or narrowly ranges that an advisory affects is installed with it, so it counts as one of `to`'s
+ * own, graded the same way (critical/high: avoid, else review). A held check that could not run
+ * never lets the signal say proceed.
+ */
+export function advisoriesSignal(item, facts, held) {
+    const own = ownAdvisoriesSignal(item, facts);
+    if (!held || (held.status === "checked" && held.affected.length === 0))
+        return own;
+    if (held.status === "unchecked") {
+        const note = `Whether the dependencies ${item.to} exact-pins or narrowly ranges have known advisories was not checked (${held.reason}).`;
+        return {
+            ...own,
+            value: own.value === null ? { held_dependencies_unchecked: held.reason } : { ...own.value, held_dependencies_unchecked: held.reason },
+            effect: own.effect === "avoid" || own.effect === "review" ? own.effect : "unknown",
+            evidence: `${own.evidence} ${note}`,
+        };
+    }
+    const severity = heldSeverity(held.affected);
+    const heldEffect = severity === "critical" || severity === "high" ? "avoid" : "review";
+    const effect = own.effect === "avoid" || heldEffect === "avoid" ? "avoid" : "review";
+    const affected = held.affected.map((d) => ({ package: d.name, spec: d.spec, installs: d.version, advisories: d.ids, severity: d.severity }));
+    const heldNote = `${heldText(item.to, held.affected)}: installing ${item.to} installs ${held.affected.length === 1 ? "it" : "them"}.`;
+    return {
+        id: "advisories",
+        value: own.value === null ? { held_dependencies_affected: affected } : { ...own.value, held_dependencies_affected: affected },
+        effect,
+        // "No known vulnerability affects X." is about X's own advisories; say what it holds instead.
+        evidence: own.effect === "proceed"
+            ? `${own.evidence.replace(`No known vulnerability affects ${item.to}.`, `No advisory of ${item.package} itself affects ${item.to}, but ${heldNote}`)}`
+            : `${own.evidence} ${heldNote}`,
+    };
+}
+function ownAdvisoriesSignal(item, facts) {
     if (!facts.available) {
         return { id: "advisories", value: null, evidence: `OSV.dev could not be reached: ${facts.detail}`, effect: "unknown" };
     }
     const fromIds = new Set(facts.from.map((a) => a.id));
     const toIds = new Set(facts.to.map((a) => a.id));
     const fixed = facts.from.filter((a) => !toIds.has(a.id) && !a.maintenance);
-    const value = { affecting_to: facts.to.map((a) => a.id), fixed_by_this_change: fixed.map((a) => a.id) };
+    // An unmaintained-package notice names no exploitable vulnerability: it is
+    // reported in its own field and never moves the verdict (audit L3, the
+    // same split as vulnerability_scan's `maintenance_notices`).
+    const notices = facts.to.filter((a) => a.maintenance);
+    const value = {
+        affecting_to: facts.to.filter((a) => !a.maintenance).map((a) => a.id),
+        fixed_by_this_change: fixed.map((a) => a.id),
+        ...(notices.length > 0 ? { maintenance_notices: notices.map((a) => a.id) } : {}),
+    };
+    const noticeNote = notices.length > 0
+        ? ` Unmaintained-package notice${notices.length > 1 ? "s" : ""} ${notices.map((a) => a.id).join(", ")} ${notices.length > 1 ? "apply" : "applies"} to ${item.to}${notices.every((a) => fromIds.has(a.id)) ? ` (already on ${item.from})` : ""}: no exploitable vulnerability, listed in maintenance_notices.`
+        : "";
     const fixedNote = fixed.length > 0 ? ` This change fixes ${list(fixed)} affecting ${item.from}.` : "";
     const serious = facts.to.filter((a) => !a.maintenance && (a.severity === "critical" || a.severity === "high"));
     if (serious.length > 0) {
-        return { id: "advisories", value, effect: "avoid", evidence: `${item.to} is affected by ${list(serious)}.${fixedNote}` };
+        return { id: "advisories", value, effect: "avoid", evidence: `${item.to} is affected by ${list(serious)}.${fixedNote}${noticeNote}` };
     }
     const other = facts.to.filter((a) => !a.maintenance);
-    const newNotices = facts.to.filter((a) => a.maintenance && !fromIds.has(a.id));
-    if (other.length > 0 || newNotices.length > 0) {
+    if (other.length > 0) {
         return {
             id: "advisories",
             value,
             effect: "review",
-            evidence: `${item.to} is affected by ${list([...other, ...newNotices])}.${fixedNote}`,
+            evidence: `${item.to} is affected by ${list(other)}.${fixedNote}${noticeNote}`,
         };
     }
-    // Only maintenance notices that `from` already carries can remain here.
-    const carried = facts.to.length > 0 ? ` (maintenance notice${facts.to.length > 1 ? "s" : ""} ${facts.to.map((a) => a.id).join(", ")} already apply to ${item.from})` : "";
     return {
         id: "advisories",
         value,
         effect: "proceed",
-        evidence: `No known advisory affects ${item.to}${carried}.${fixedNote}`,
+        evidence: `No known vulnerability affects ${item.to}.${fixedNote}${noticeNote}`,
     };
 }
 function fmt(a) {
-    return `${a.id} (${a.maintenance ? "unmaintained notice" : a.severity})`;
+    return `${a.id} (${a.maintenance ? "unmaintained notice" : a.severityFrom ? `${a.severity}, per ${a.severityFrom}` : a.severity})`;
 }
 /** At most three named in prose; the full id list is in the signal's `value`. */
 function list(advisories) {
@@ -241,12 +285,32 @@ export function newDependenciesSignal(item, to, base, introduced, created) {
         evidence: `${to.version} adds ${list} since ${base.record.version}.`,
     };
 }
-export function withdrawnSignal(item, to) {
+/**
+ * Yanked, unpublished, retracted: avoid. npm deprecated: avoid when the 4DA rule withdraws it (a
+ * later, non-deprecated stable release exists on its caret line, lodash 4.18.0 "Bad release"),
+ * and when the notice is this release's alone ("Critical bug in 1.0.3"); review when the rule
+ * keeps it and the same notice is on other releases (glob 10.5.0, one of 160 "Old versions of
+ * glob are not supported"): a "please upgrade" notice, not a withdrawn release, and possibly
+ * the only fix on its line (FX-H5, withdrawn-releases.ts). Without the index: every deprecation avoids.
+ */
+export function withdrawnSignal(item, to, index) {
     if (to.withdrawn) {
         return { id: "yanked_or_deprecated", value: { [to.withdrawn]: true }, effect: "avoid", evidence: `${item.to} was ${to.withdrawn} from the registry.` };
     }
     if (to.deprecated) {
-        return { id: "yanked_or_deprecated", value: { deprecated: to.deprecated }, effect: "avoid", evidence: `${item.to} is deprecated: "${to.deprecated}".` };
+        const value = { deprecated: to.deprecated };
+        // The same notice on other releases too: a "please upgrade" notice about the line or the package.
+        const shared = index ? Object.values(index.releases).filter((r) => r.version !== to.version && r.deprecated === to.deprecated).length : 0;
+        if (index && item.ecosystem === "npm" && shared > 0 && !excludedReleases(index).has(to.version)) {
+            return {
+                id: "yanked_or_deprecated",
+                value: { ...value, withdrawn: false },
+                effect: "review",
+                evidence: `${item.to} is deprecated: "${to.deprecated}". The same notice is on ${shared} other release${shared === 1 ? "" : "s"} and no later release on its line is free of one, ` +
+                    `so it is a notice about the line, not a withdrawn release; tell the user it is deprecated.`,
+            };
+        }
+        return { id: "yanked_or_deprecated", value, effect: "avoid", evidence: `${item.to} is deprecated: "${to.deprecated}".` };
     }
     return { id: "yanked_or_deprecated", value: null, effect: "proceed", evidence: `${item.to} is neither yanked nor deprecated.` };
 }
@@ -301,7 +365,14 @@ export function decide(signals) {
             const fixes = signals.find((s) => s.id === "release_age" && /security fix/.test(s.evidence));
             return { verdict, reason: fixes ? fixes.evidence : "No advisory, age, trust, script or new-dependency concern found." };
         }
-        return { verdict, reason: hits.map((s) => `${s.id}: ${s.evidence}`).join(" | ") };
+        // A stronger verdict must not hide what could not be checked: crossenv `latest` (the malware
+        // 1.0.1) read `review` for "major" alone while its advisory lookup had failed (audit 6.2.5 D-10).
+        const unchecked = verdict === "unknown" ? [] : signals.filter((s) => s.effect === "unknown");
+        const reason = hits.map((s) => `${s.id}: ${s.evidence}`).join(" | ");
+        return {
+            verdict,
+            reason: unchecked.length > 0 ? `${reason} | NOT CHECKED: ${unchecked.map((s) => `${s.id}: ${s.evidence}`).join(" | ")}` : reason,
+        };
     }
     return { verdict: "unknown", reason: "No signal could be evaluated." };
 }

package/dist/tools/dependency-check-versions.d.ts

@@ -76,13 +76,38 @@ export interface RangeCheck {
     newest_safe_outside_range?: string | null;
     /** When `from` is given: the smallest safe release above it (the minimal fixing upgrade). */
     smallest_safe_upgrade?: string | null;
+    /**
+     * Releases in range that no advisory affects but the registry withdrew (yanked; npm
+     * deprecated with a later clean release on its line), below the smallest safe pick (all of
+     * them when none is safe), and why in plain words (FX-H5).
+     */
+    withheld?: string[];
+    withheld_note?: string;
+    /**
+     * npm (audit 6.2.5 D-4): releases left out of the safe ones because a dependency they exact-pin
+     * or narrowly range is affected, or because that could not be checked; and why, in words.
+     */
+    held_excluded?: number;
+    held_note?: string;
 }
+/**
+ * The releases in range that the package's own advisories leave safe, ascending: what checkRange
+ * would call safe before held dependencies are judged. dependency_check judges the held
+ * dependencies of the smallest and newest of these (audit 6.2.5 D-4).
+ */
+export declare function ownSafeInRange(input: {
+    ecosystem: CheckEcosystem;
+    index: PackageReleaseIndex;
+    range: string;
+    advisories: AdvisoryRanges[];
+}): string[];
 /**
  * The releases a constraint admits, judged against every advisory OSV.dev
- * lists for the package. Withdrawn (yanked / unpublished / retracted) and
- * deprecated releases are not candidates; neither are prereleases, unless
- * the constraint admits nothing else. Maintenance notices do not make a
- * release unsafe.
+ * lists for the package. Withdrawn releases (yanked / unpublished /
+ * retracted, and npm deprecations the 4DA rule withdraws: withdrawn-releases.ts)
+ * are not candidates; neither are prereleases, unless the constraint admits
+ * nothing else. A whole-line npm deprecation notice (glob 10.x, tar 6.x)
+ * withdraws nothing. Maintenance notices do not make a release unsafe.
  */
 export declare function checkRange(input: {
     ecosystem: CheckEcosystem;
@@ -91,4 +116,12 @@ export declare function checkRange(input: {
     basis: RangeCheck["basis"];
     advisories: AdvisoryRanges[];
     from?: string;
+    /**
+     * npm: a release whose held dependencies (exact pins, narrow ranges) are affected or could not
+     * be judged is not safe either (audit 6.2.5 D-4), and `heldNote` says why when any is left out.
+     */
+    held?: {
+        unsafe: (version: string) => boolean;
+        note: string;
+    };
 }): RangeCheck;

package/dist/tools/dependency-check-versions.js

@@ -15,10 +15,11 @@
  * "v1" for a Go major. Pure functions, no I/O.
  */
 import { cargoReqAdmits, npmRangeAdmits } from "../live/range-satisfies.js";
-import { advisoryAffects, isPrereleaseVersion } from "../live/osv-ranges.js";
+import { advisoriesAffecting, isPrereleaseVersion } from "../live/osv-ranges.js";
 import { compareVersions, parsePep440 } from "../live/version-compare.js";
 import { parseSemverPrecedence } from "../live/semver-precedence.js";
 import { GO_VERSION, goVersion } from "../live/go-releases.js";
+import { excludedReleases, withheldNote } from "../live/withdrawn-releases.js";
 const FULL_SEMVER = /^v?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 /** Read a `to` value; null when it is neither a version nor a constraint this ecosystem understands. */
 export function parseTarget(ecosystem, raw) {
@@ -174,22 +175,39 @@ export function lineOf(ecosystem, version) {
         return `v${p.major}`;
     return p.major === 0 ? `0.${p.minor}.x` : `${p.major}.x`;
 }
+/** The installable releases a constraint admits, ascending; prereleases only when it admits nothing else. */
+function rangeCandidates(ecosystem, installable, range) {
+    const admitted = installable.filter((v) => rangeAdmits(ecosystem, range, v) === true);
+    const stable = admitted.filter((v) => !isPrereleaseIn(ecosystem, v));
+    return { candidates: (stable.length > 0 ? stable : admitted).sort((a, b) => compareIn(ecosystem, a, b)), stable };
+}
+/**
+ * The releases in range that the package's own advisories leave safe, ascending: what checkRange
+ * would call safe before held dependencies are judged. dependency_check judges the held
+ * dependencies of the smallest and newest of these (audit 6.2.5 D-4).
+ */
+export function ownSafeInRange(input) {
+    const excluded = excludedReleases(input.index);
+    const installable = Object.values(input.index.releases).filter((r) => !excluded.has(r.version)).map((r) => r.version);
+    return rangeCandidates(input.ecosystem, installable, input.range).candidates.filter((v) => advisoriesAffecting(input.advisories, v, input.ecosystem).length === 0);
+}
 /**
  * The releases a constraint admits, judged against every advisory OSV.dev
- * lists for the package. Withdrawn (yanked / unpublished / retracted) and
- * deprecated releases are not candidates; neither are prereleases, unless
- * the constraint admits nothing else. Maintenance notices do not make a
- * release unsafe.
+ * lists for the package. Withdrawn releases (yanked / unpublished /
+ * retracted, and npm deprecations the 4DA rule withdraws: withdrawn-releases.ts)
+ * are not candidates; neither are prereleases, unless the constraint admits
+ * nothing else. A whole-line npm deprecation notice (glob 10.x, tar 6.x)
+ * withdraws nothing. Maintenance notices do not make a release unsafe.
  */
 export function checkRange(input) {
     const { ecosystem, index, range, basis } = input;
-    const installable = Object.values(index.releases).filter((r) => !r.withdrawn && !r.deprecated).map((r) => r.version);
-    const admitted = installable.filter((v) => rangeAdmits(ecosystem, range, v) === true);
-    const stable = admitted.filter((v) => !isPrereleaseIn(ecosystem, v));
-    const candidates = (stable.length > 0 ? stable : admitted).sort((a, b) => compareIn(ecosystem, a, b));
-    const real = input.advisories.filter((a) => !a.maintenance);
-    const affecting = (v) => real.filter((a) => advisoryAffects(a, v, ecosystem)).map((a) => a.id);
-    const safe = candidates.filter((v) => affecting(v).length === 0);
+    const excluded = excludedReleases(index);
+    const installable = Object.values(index.releases).filter((r) => !excluded.has(r.version)).map((r) => r.version);
+    const { candidates, stable } = rangeCandidates(ecosystem, installable, range);
+    // The same predicate every tool runs on a release it offers (osv-ranges.ts advisoriesAffecting).
+    const affecting = (v) => advisoriesAffecting(input.advisories, v, ecosystem);
+    const ownSafe = candidates.filter((v) => affecting(v).length === 0);
+    const safe = input.held ? ownSafe.filter((v) => !input.held.unsafe(v)) : ownSafe;
     const out = {
         range,
         basis,
@@ -202,12 +220,29 @@ export function checkRange(input) {
     if (candidates.length > 0 && safe.length === 0) {
         out.affecting_all = [...new Set(candidates.flatMap(affecting))].filter((id) => candidates.every((v) => affecting(v).includes(id))).slice(0, 10);
         const outside = installable
-            .filter((v) => !isPrereleaseIn(ecosystem, v) && affecting(v).length === 0)
+            .filter((v) => !isPrereleaseIn(ecosystem, v) && affecting(v).length === 0 && !input.held?.unsafe(v))
             .sort((a, b) => compareIn(ecosystem, a, b));
         out.newest_safe_outside_range = outside[outside.length - 1] ?? null;
     }
     if (input.from) {
         out.smallest_safe_upgrade = safe.find((v) => compareIn(ecosystem, v, input.from) > 0) ?? null;
     }
+    if (input.held && safe.length < ownSafe.length) {
+        out.held_excluded = ownSafe.length - safe.length;
+        out.held_note = input.held.note;
+    }
+    // The withdrawn releases that would otherwise have been the smallest safe pick (FX-H5).
+    const pick = input.from ? out.smallest_safe_upgrade : out.smallest_safe_in_range;
+    const withheld = [...excluded.keys()]
+        .filter((v) => rangeAdmits(ecosystem, range, v) === true &&
+        (stable.length === 0 || !isPrereleaseIn(ecosystem, v)) &&
+        (!input.from || compareIn(ecosystem, v, input.from) > 0) &&
+        (!pick || compareIn(ecosystem, v, pick) < 0) &&
+        affecting(v).length === 0)
+        .sort((a, b) => compareIn(ecosystem, a, b));
+    if (withheld.length > 0) {
+        out.withheld = withheld;
+        out.withheld_note = withheldNote(withheld, pick ?? null, Object.fromEntries(excluded), ecosystem);
+    }
     return out;
 }

package/dist/tools/dependency-check.d.ts

@@ -37,7 +37,8 @@
  */
 import type { FourDADatabase } from "../db.js";
 import type { LiveIntelligence } from "../live/index.js";
-import { type Signal, type Verdict } from "./dependency-check-signals.js";
+import type { VulnerabilityEntry } from "../live/types.js";
+import { type AdvisoryRef, type Signal, type Verdict } from "./dependency-check-signals.js";
 import { type RangeCheck } from "./dependency-check-versions.js";
 export interface DependencyCheckParams {
     items?: unknown;
@@ -92,6 +93,8 @@ interface ItemResult {
     reason: string;
     signals: Signal[];
     range_check?: RangeCheck;
+    /** Unmaintained-package notices on `to`: reported, never part of the verdict (audit L3). */
+    maintenance_notices?: string[];
 }
 export declare function executeDependencyCheck(_db: FourDADatabase | null, params: DependencyCheckParams, liveIntel: LiveIntelligence | null, opts?: {
     now?: Date;
@@ -111,4 +114,11 @@ export declare function executeDependencyCheck(_db: FourDADatabase | null, param
         };
     };
 }>;
+/**
+ * One reference per vulnerability: OSV lists GHSA and RUSTSEC/PYSEC records
+ * for the same issue, each naming the other in `aliases`. They were counted
+ * twice ("6 advisories" for tokio 1.18.0's three, audit A9). The kept record
+ * of an alias group is its most severe, so merging never softens a verdict.
+ */
+export declare function refs(entries: VulnerabilityEntry[] | undefined): AdvisoryRef[];
 export {};

package/dist/tools/dependency-check.js

@@ -36,10 +36,12 @@
  * `.info` is read from it. OSV receives name + version, as vulnerability_scan
  * already does, and the package name for its advisory list.
  */
+import { groupAdvisories } from "../live/advisory-groups.js";
 import { isMaintenanceNotice } from "../live/maintenance.js";
 import { goPathMajor, goVersionMajor } from "../live/upgrade-go.js";
 import { advisoriesSignal, decide, installScriptSignal, introducedDependencies, newDependenciesSignal, publishTrustSignal, releaseAgeSignal, selectBaseline, upgradeTypeSignal, withdrawnSignal, WAIT_DAYS, } from "./dependency-check-signals.js";
-import { checkRange, compareIn, isPrereleaseIn, lineOf, parseTarget, rangeAdmits } from "./dependency-check-versions.js";
+import { checkRange, compareIn, isPrereleaseIn, lineOf, ownSafeInRange, parseTarget, rangeAdmits } from "./dependency-check-versions.js";
+import { HeldJudge, heldRangeCandidates } from "./dependency-check-held.js";
 const MAX_ITEMS = 25;
 /** First-publish lookups for newly introduced dependencies, per call (each is a registry read). */
 const MAX_NEW_DEP_LOOKUPS = 40;
@@ -57,7 +59,7 @@ export const dependencyCheckTool = {
         "Is this dependency version safe to write? Call BEFORE you write any version into a manifest or lockfile: adding, pinning, upgrading, bumping or downgrading a package, or choosing a version (npm, crates.io, PyPI, Go). Pass the exact version you intend to write, or the constraint you were given (\"7.x\", \"^1.20\", \"~=3.1\", \"v1\") to get the smallest and newest safe release in it. Write only a version that came back `proceed`. Your memory of which release is safe is out of date; this reads the registry and OSV.dev now.",
         "",
         "Per item: `verdict` (proceed | wait | review | avoid | unknown), a one-line `reason`, `signals` (each with `id`, `value`, `evidence`, `effect`), and `range_check` when `to` is a constraint or an exact `to` has an advisory: `smallest_safe_in_range`, `newest_safe_in_range`, `safe_versions`, `smallest_safe_upgrade` (above `from`). For a constraint the verdict is for the version it picks: the smallest safe upgrade above `from`, else the newest safe release.",
-        "- advisories: OSV advisories affecting `to` (high/critical -> avoid, other -> review) and those this change fixes on `from`.",
+        "- advisories: OSV advisories affecting `to` (high/critical -> avoid, other -> review) and those this change fixes on `from`. npm: a dependency `to` exact-pins, or narrowly ranges with no clean release in reach, is installed with it, so its advisories count the same (`held_dependencies_affected`), and such releases are never among the safe ones.",
         "- release_age: under 3 days -> wait, unless `to` fixes an advisory affecting `from`, or every release on its line past the hold has an advisory and no safe one is past it (then proceed; tell the user its age).",
         "- yanked_or_deprecated: yanked, unpublished, retracted (Go) or deprecated -> avoid.",
         "- publish_trust (npm, crates.io): trusted publisher / provenance dropped -> review. install_script_added (npm): new install script -> review. new_dependencies (npm, crates.io): a new runtime dependency under 30 days old -> review. Not applicable elsewhere, and said so.",
@@ -109,7 +111,7 @@ export async function executeDependencyCheck(_db, params, liveIntel, opts = {})
     const indexes = await fetchIndexes(requested.map(provisional), sources, new Set(requested.filter(needsFullList).map(lookupKey)));
     // Constraints are judged against the package's whole advisory list.
     const advisoryLists = await packageAdvisoryLists(fixSources, requested.filter((r) => r.target.kind === "range" || r.target.kind === "exact_or_series"));
-    const items = requested.map((r) => resolveTarget(r, indexes.get(lookupKey(r)), advisoryLists.get(lookupKey(r)), now));
+    let items = requested.map((r) => resolveTarget(r, indexes.get(lookupKey(r)), advisoryLists.get(lookupKey(r)), now));
     // Go dates come from per-version .info: read them for versions chosen from the list
     // (a constraint, "latest", or `v2.0.0` listed as `v2.0.0+incompatible`).
     const goRedo = items.filter((i) => {
@@ -121,34 +123,72 @@ export async function executeDependencyCheck(_db, params, liveIntel, opts = {})
             indexes.set(key, lookup);
         await settleGoPicks(goRedo, indexes, sources.Go, now);
     }
+    // npm: what a release installs at a fixed version comes with it (audit 6.2.5 D-4: express 4.20.0
+    // exact-pins an affected qs). Judge `to` and, for a constraint, the smallest and newest safe
+    // releases in it, then pick again among the releases that hold nothing affected.
+    const held = new HeldJudge(fixSources, (deps) => liveIntel.queryAdvisories(deps));
+    const isNpm = (i) => i.ecosystem === "npm" && !i.unresolved;
+    await held.judge(items.filter(isNpm).map((item) => {
+        const lookup = indexes.get(lookupKey(item));
+        const advisories = advisoryLists.get(lookupKey(item));
+        const ownSafe = item.rangeCheck && lookup?.status === "ok" && advisories
+            ? ownSafeInRange({ ecosystem: "npm", index: lookup.data, range: item.rangeCheck.range, advisories })
+            : [];
+        return { pkg: item.package, versions: [item.to, ...heldRangeCandidates(ownSafe, (v) => !item.from || compareIn("npm", v, item.from) > 0)] };
+    }));
+    items = items.map((item, i) => {
+        if (!isNpm(item) || item.rangeCheck?.basis !== "requested")
+            return item;
+        const filter = held.rangeFilter(item.package);
+        const r = requested[i];
+        return filter ? resolveTarget(r, indexes.get(lookupKey(r)), advisoryLists.get(lookupKey(r)), now, filter) : item;
+    });
+    // The pick may have moved to a release judged only through its range: judge it too (normally a no-op).
+    await held.judge(items.filter(isNpm).map((item) => ({ pkg: item.package, versions: [item.to] })));
+    const heldAt = (item) => (item.ecosystem === "npm" ? held.at(item.package, item.to) : undefined);
     const osvDeps = items
         .filter((i) => !i.unresolved)
         .flatMap((item) => [item.to, item.from].filter((v) => Boolean(v)).map((version) => osvDep(item, version)));
     const scan = await liveIntel.queryAdvisories(osvDeps);
+    // Unrated (Go) records carry their GHSA alias's grade from the scanner, as in every tool (severityFrom).
     const byInstance = new Map();
     for (const v of scan.vulnerabilities) {
         const key = instanceKey(v.ecosystem, v.package, v.currentVersion);
         byInstance.set(key, [...(byInstance.get(key) ?? []), v]);
     }
+    // A pre-install check needs a current answer: an expired cached one (OSV failed) can predate
+    // the advisory that matters, and read as `proceed` (audit 6.2.5 B-2).
     const advisoriesFor = (item) => scan.offline
         ? { available: false, detail: "lookup failed or was rate limited" }
-        : {
-            available: true,
-            to: refs(byInstance.get(instanceKey(item.ecosystem, item.package, item.to))),
-            from: item.from ? refs(byInstance.get(instanceKey(item.ecosystem, item.package, item.from))) : [],
-        };
-    // An exact `to` an advisory affects: the safe releases on its own line.
-    const affectedExact = items.filter((i) => !i.unresolved && !i.rangeCheck && advisoriesFor(i).available && hasRealAdvisory(advisoriesFor(i)));
+        : (scan.staleAnswers ?? 0) > 0
+            ? { available: false, detail: `no current answer, only an expired cached one (${scan.staleReason ?? "the fresh query failed"})` }
+            : {
+                available: true,
+                to: refs(byInstance.get(instanceKey(item.ecosystem, item.package, item.to))),
+                from: item.from ? refs(byInstance.get(instanceKey(item.ecosystem, item.package, item.from))) : [],
+            };
+    // An exact `to` an advisory affects (its own, or one it holds): the safe releases on its own line.
+    const affectedExact = items.filter((i) => !i.unresolved &&
+        !i.rangeCheck &&
+        ((advisoriesFor(i).available && hasRealAdvisory(advisoriesFor(i))) || (i.ecosystem === "npm" && held.affected(i.package, i.to))));
     const moreLists = await packageAdvisoryLists(fixSources, affectedExact.filter((i) => !advisoryLists.has(lookupKey(i))));
     for (const [k, v] of moreLists)
         advisoryLists.set(k, v);
-    for (const item of affectedExact) {
+    const lines = affectedExact.flatMap((item) => {
         const lookup = indexes.get(lookupKey(item));
         const advisories = advisoryLists.get(lookupKey(item));
         const line = lineOf(item.ecosystem, item.to);
-        if (lookup.status !== "ok" || !advisories || !line)
-            continue;
-        item.rangeCheck = checkRange({ ecosystem: item.ecosystem, index: lookup.data, range: line, basis: "same_line", advisories, from: item.from });
+        return lookup.status === "ok" && advisories && line ? [{ item, index: lookup.data, advisories, line }] : [];
+    });
+    await held.judge(lines
+        .filter((l) => l.item.ecosystem === "npm")
+        .map((l) => ({
+        pkg: l.item.package,
+        versions: heldRangeCandidates(ownSafeInRange({ ecosystem: "npm", index: l.index, range: l.line, advisories: l.advisories }), (v) => !l.item.from || compareIn("npm", v, l.item.from) > 0),
+    })));
+    for (const { item, index, advisories, line } of lines) {
+        const filter = item.ecosystem === "npm" ? held.rangeFilter(item.package) : undefined;
+        item.rangeCheck = checkRange({ ecosystem: item.ecosystem, index, range: line, basis: "same_line", advisories, from: item.from, ...(filter ? { held: filter } : {}) });
     }
     const holdWaivers = await findHoldWaivers(items, indexes, advisoryLists, fixSources, sources.Go, advisoriesFor, now);
     // Phase 2: first-publish dates of newly introduced dependencies.
@@ -168,12 +208,16 @@ export async function executeDependencyCheck(_db, params, liveIntel, opts = {})
     });
     const results = plans.map((p) => {
         const extra = p.item.rangeCheck ? { range_check: p.item.rangeCheck } : {};
+        const noticesOf = (s) => {
+            const ids = s.value?.maintenance_notices;
+            return ids && ids.length > 0 ? { maintenance_notices: ids } : {};
+        };
         if (p.blocked) {
             // No release metadata: only the advisory lookup can still speak, and
             // only a negative finding is worth more than "unknown".
             if (p.item.unresolved)
                 return { ...head(p.item), verdict: "unknown", reason: p.blocked, signals: [], ...extra };
-            const advisories = advisoriesSignal(p.item, advisoriesFor(p.item));
+            const advisories = advisoriesSignal(p.item, advisoriesFor(p.item), heldAt(p.item));
             const negative = advisories.effect === "avoid" || advisories.effect === "review";
             return {
                 ...head(p.item),
@@ -181,12 +225,13 @@ export async function executeDependencyCheck(_db, params, liveIntel, opts = {})
                 reason: withAlternatives(negative ? `advisories: ${advisories.evidence} | ${p.blocked}` : p.blocked, p.item, negative),
                 signals: [advisories],
                 ...extra,
+                ...noticesOf(advisories),
             };
         }
         const { item, index } = p;
         const to = index.releases[item.to];
         const base = selectBaseline(index, item);
-        const advisories = advisoriesSignal(item, advisoriesFor(item));
+        const advisories = advisoriesSignal(item, advisoriesFor(item), heldAt(item));
         const createdForItem = new Map();
         for (const name of p.introduced ?? []) {
             const fact = created.get(`${item.ecosystem}\0${name}`);
@@ -199,12 +244,12 @@ export async function executeDependencyCheck(_db, params, liveIntel, opts = {})
             publishTrustSignal(item, to, base),
             installScriptSignal(item, to, item.from ? index.releases[item.from] ?? null : null),
             newDependenciesSignal(item, to, base, p.introduced, createdForItem),
-            withdrawnSignal(item, to),
+            withdrawnSignal(item, to, index),
             upgradeTypeSignal(item),
         ];
         const decided = decide(signals);
         const unsafe = decided.verdict === "avoid" || decided.verdict === "review";
-        return { ...head(item), verdict: decided.verdict, reason: withAlternatives(decided.reason, item, unsafe), signals, ...extra };
+        return { ...head(item), verdict: decided.verdict, reason: withAlternatives(decided.reason, item, unsafe), signals, ...extra, ...noticesOf(advisories) };
     });
     return finish(checkedAt, results, { offline: scan.offline, osvCached: scan.cached });
 }
@@ -218,10 +263,15 @@ function withAlternatives(reason, item, unsafe) {
         const ids = rc.affecting_all ?? [];
         const all = ids.length ? `: ${ids.slice(0, 3).join(", ")}${ids.length > 3 ? ` and ${ids.length - 3} more` : ""} affect every one` : "";
         const outside = rc.newest_safe_outside_range ? ` Newest safe release outside it: ${rc.newest_safe_outside_range}.` : "";
-        return `${reason} | No release ${where} is free of known advisories${all}.${outside}`;
+        const withheld = rc.withheld_note ? ` ${rc.withheld_note}.` : "";
+        return `${reason} | No release ${where} is free of known advisories${all}.${withheld}${outside}`;
     }
     const upgrade = rc.smallest_safe_upgrade && rc.smallest_safe_upgrade !== rc.smallest_safe_in_range ? `, smallest above ${item.from} ${rc.smallest_safe_upgrade}` : "";
-    const safe = `Safe ${where}: smallest ${rc.smallest_safe_in_range}${upgrade}, newest ${rc.newest_safe_in_range}.`;
+    // FX-H5: a withdrawn release the pick steps over is named, in the registry's words.
+    const withheld = rc.withheld_note ? ` ${rc.withheld_note}.` : "";
+    // audit 6.2.5 D-4: releases passed over for what they hold are counted, never dropped silently.
+    const heldOut = rc.held_excluded ? ` ${rc.held_excluded} release${rc.held_excluded === 1 ? "" : "s"} clear of ${item.package}'s own advisories left out: ${rc.held_note}.` : "";
+    const safe = `Safe ${where}: smallest ${rc.smallest_safe_in_range}${upgrade}, newest ${rc.newest_safe_in_range}.${withheld}${heldOut}`;
     if (rc.basis === "same_line" && !unsafe)
         return reason;
     return `${reason} | ${safe}`;
@@ -242,7 +292,7 @@ function needsFullList(r) {
  * the proxy lists it), "latest" (newest stable, not withdrawn), or the
  * version a constraint recommends.
  */
-function resolveTarget(r, lookup, advisories, now) {
+function resolveTarget(r, lookup, advisories, now, held) {
     const base = provisional(r);
     if (lookup.status !== "ok")
         return base;
@@ -275,7 +325,7 @@ function resolveTarget(r, lookup, advisories, now) {
         // Without the advisory list no release can be called safe; judge the newest one on its own advisories.
         return { ...base, to: newestOf(r.ecosystem, admitted), requested: r.raw };
     }
-    const rangeCheck = checkRange({ ecosystem: r.ecosystem, index, range, basis: "requested", advisories, from: r.from });
+    const rangeCheck = checkRange({ ecosystem: r.ecosystem, index, range, basis: "requested", advisories, from: r.from, ...(held ? { held } : {}) });
     const safe = rangeCheck.safe_versions;
     const settled = (v) => {
         const at = index.releases[v]?.publishedAt;
@@ -490,13 +540,15 @@ function osvDep(item, version) {
         sourceDirs: [],
     };
 }
-function refs(entries) {
-    const seen = new Set();
-    return (entries ?? []).flatMap((v) => {
-        if (seen.has(v.vulnId))
-            return [];
-        seen.add(v.vulnId);
-        return [{ id: v.vulnId, severity: v.severity, summary: v.summary, maintenance: isMaintenanceNotice(v) }];
+/**
+ * One reference per vulnerability: OSV lists GHSA and RUSTSEC/PYSEC records
+ * for the same issue, each naming the other in `aliases`. They were counted
+ * twice ("6 advisories" for tokio 1.18.0's three, audit A9). The kept record
+ * of an alias group is its most severe, so merging never softens a verdict.
+ */
+export function refs(entries) {
+    return groupAdvisories(entries).map(({ best: v }) => {
+        return { id: v.vulnId, severity: v.severity, summary: v.summary, maintenance: isMaintenanceNotice(v), ...(v.severityFrom ? { severityFrom: v.severityFrom } : {}) };
     });
 }
 const instanceKey = (eco, name, version) => `${eco}\0${eco === "PyPI" ? normalizePypi(name) : name}\0${version}`;