@4da/mcp-server 6.2.3 → 6.2.5

package/dist/live/fix-paths.js

@@ -23,26 +23,37 @@
  * package's own registry; package names and versions only. Every lookup is
  * cached, and any failure degrades to the old answer, never to a guess.
  */
+import { isShellSafeCargoTarget, isShellSafeName, isShellSafeVersion } from "./shell-safe.js";
 import { fetchWithTimeout } from "./http-utils.js";
 import { escapeModulePath } from "./go-registry.js";
-import { advisoryRanges, advisoryAffects, isPrereleaseVersion, smallestCleanVersion } from "./osv-ranges.js";
+import { advisoryRanges, advisoryAffects, installableFix, remainsText, isPrereleaseVersion, smallestCleanVersion } from "./osv-ranges.js";
 import * as fs from "node:fs";
-import { readLockfileParents } from "./lockfile-parents.js";
+import * as path from "node:path";
+import { lockfileFormat, readLockfileParents } from "./lockfile-parents.js";
 import { parseCargoLockPackages } from "./lockfile-parsers.js";
+import { compiledRequirements, confinedInclude, requirementOptions } from "./lockfile-parsers-pygo.js";
 import { cargoReqAdmits, npmRangeAdmits } from "./range-satisfies.js";
-import { compareVersions } from "./version-compare.js";
+import { refreshRule, requirementAdmits } from "./refresh-rule.js";
+import { compareVersions, maxVersion } from "./version-compare.js";
 import { CRATES_USER_AGENT } from "./crates-versions.js";
+import { isNpmDeprecated, npmExcludedVersions, sayWithdrawn, withdrawalText, withheldNote } from "./withdrawn-releases.js";
+import { heldSpecsOf, heldText } from "./held-dependencies.js";
+import { withHeldTargets } from "./held-targets.js";
 const TIMEOUT_MS = 15_000;
 const ADVISORY_TTL = 6 * 3600;
 const VERSIONS_TTL = 6 * 3600;
 /** A published version's manifest never changes. */
 const VERSION_DEPS_TTL = 30 * 86_400;
 const MAX_OSV_PAGES = 10;
-/** Bump when the shape of anything this module caches changes. */
-const CACHE_VERSION = 3;
+/** Bump when the shape of anything this module caches changes (10: npm facts carry `heldSpecs`, audit 6.2.5 D-4). */
+const CACHE_VERSION = 10;
+/** How long, and how many, npm documents are kept in memory between the lookups of one plan. */
+const NPM_DOC_MEMORY_MS = 120_000;
+const NPM_DOCS_KEPT = 16;
 export class FixPathSources {
     cache;
     rateLimiter;
+    npmDocs = new Map();
     constructor(cache, rateLimiter) {
         this.cache = cache;
         this.rateLimiter = rateLimiter;
@@ -89,11 +100,11 @@ export class FixPathSources {
     async publishedVersions(ecosystem, name) {
         switch (ecosystem) {
             case "npm":
-                return this.npmVersions(name);
+                return (await this.npmFacts(name))?.versions ?? null;
             case "crates.io":
                 return (await this.cratesSparse(name))?.versions ?? null;
             case "PyPI":
-                return this.pypiVersions(name);
+                return (await this.pypiFacts(name))?.versions ?? null;
             case "Go":
                 return this.goVersions(name);
             default:
@@ -123,7 +134,9 @@ export class FixPathSources {
                 if (!res.ok)
                     return null;
                 const doc = (await res.json());
-                deps = { ...doc.peerDependencies, ...doc.optionalDependencies, ...doc.dependencies };
+                // Not peerDependencies, as in the 4DA app: a peer is resolved from whoever provides it
+                // higher in the tree, so the parent's peer range does not decide which copy a refresh picks.
+                deps = { ...doc.optionalDependencies, ...doc.dependencies };
                 this.cache.set(key, deps, "npm", VERSION_DEPS_TTL);
             }
             catch {
@@ -132,26 +145,145 @@ export class FixPathSources {
         }
         return typeof deps[dep] === "string" ? [deps[dep]] : [];
     }
-    async npmVersions(name) {
-        const key = `fixpath:v${CACHE_VERSION}:npm-versions:${name}`;
+    /**
+     * What every published release of `parent` requires of `dep`, from the
+     * registry: version -> requirements (`reqs: []` when that release does not
+     * depend on it). npm reads dependencies and optionalDependencies of the
+     * abbreviated document (as `parentRequirements`), and, when neither holds
+     * it, peerDependencies, flagged `peer`: npm 7+ installs a missing peer, so
+     * moving a package into peerDependencies is not dropping it (readiness
+     * review 2026-10-17, finding 10). crates.io: the sparse index. Null when
+     * unknown or unsupported. Used to find the smallest parent release that
+     * admits a clean version (audit H1).
+     */
+    async requirementHistory(ecosystem, parent, dep) {
+        if (ecosystem === "crates.io") {
+            const sparse = await this.cratesSparse(parent);
+            if (!sparse)
+                return null;
+            return Object.fromEntries(Object.entries(sparse.reqs).map(([v, deps]) => [v, { reqs: (deps[dep] ?? []).map((d) => d.req), peer: false }]));
+        }
+        if (ecosystem !== "npm")
+            return null;
+        const key = `fixpath:v${CACHE_VERSION}:npm-requirement-history:${parent}:${dep}`;
         const hit = this.cache.get(key);
         if (hit)
             return hit;
-        if (!this.rateLimiter.consume("fixpath-registry"))
+        const doc = await this.npmDocument(parent);
+        if (!doc)
             return null;
-        try {
-            // The abbreviated document: versions without READMEs.
-            const res = await fetchWithTimeout(`https://registry.npmjs.org/${encodeURIComponent(name)}`, { headers: { Accept: "application/vnd.npm.install-v1+json" } }, TIMEOUT_MS);
-            if (!res.ok)
+        const out = {};
+        for (const [version, m] of Object.entries(doc.versions ?? {})) {
+            const req = m?.dependencies?.[dep] ?? m?.optionalDependencies?.[dep];
+            const peer = m?.peerDependencies?.[dep];
+            out[version] =
+                typeof req === "string" ? { reqs: [req], peer: false } : typeof peer === "string" ? { reqs: [peer], peer: true } : { reqs: [], peer: false };
+        }
+        this.cache.set(key, out, "npm", VERSIONS_TTL);
+        return out;
+    }
+    /**
+     * One npm abbreviated document per package, shared by the release facts and the requirement
+     * history of a plan (a parent's document was downloaded twice: NodeGoat's mongodb, ~600
+     * releases). Kept in memory for a short while, at most a few at a time; a failure is not kept.
+     */
+    npmDocument(name) {
+        const now = Date.now();
+        for (const [n, e] of this.npmDocs)
+            if (now - e.at > NPM_DOC_MEMORY_MS)
+                this.npmDocs.delete(n);
+        const hit = this.npmDocs.get(name);
+        if (hit)
+            return hit.doc;
+        if (!this.rateLimiter.consume("fixpath-registry"))
+            return Promise.resolve(null);
+        const doc = (async () => {
+            try {
+                const res = await fetchWithTimeout(`https://registry.npmjs.org/${encodeURIComponent(name)}`, { headers: { Accept: "application/vnd.npm.install-v1+json" } }, TIMEOUT_MS);
+                if (!res.ok)
+                    return null;
+                return (await res.json());
+            }
+            catch {
                 return null;
-            const doc = (await res.json());
-            const versions = Object.keys(doc.versions ?? {});
-            this.cache.set(key, versions, "npm", VERSIONS_TTL);
-            return versions;
+            }
+        })();
+        this.npmDocs.set(name, { at: now, doc });
+        void doc.then((d) => {
+            if (d === null)
+                this.npmDocs.delete(name);
+        });
+        while (this.npmDocs.size > NPM_DOCS_KEPT)
+            this.npmDocs.delete(this.npmDocs.keys().next().value);
+        return doc;
+    }
+    /**
+     * Release facts for a parent or a fix target: what is installable, what is
+     * deprecated or yanked, and the latest release. Null when the registry
+     * could not be read or is not supported.
+     */
+    async releaseFacts(ecosystem, name) {
+        if (ecosystem === "npm")
+            return this.npmFacts(name);
+        const highest = (versions) => versions.filter((v) => !isPrereleaseVersion(v, ecosystem)).sort((a, b) => compareVersions(a, b, ecosystem)).pop() ?? null;
+        if (ecosystem === "crates.io") {
+            const sparse = await this.cratesSparse(name);
+            if (!sparse)
+                return null;
+            const yanked = sparse.yanked ?? [];
+            const withdrawnWhy = Object.fromEntries(yanked.map((v) => [v, withdrawalText("crates.io", v)]));
+            return { versions: sparse.versions, withdrawn: yanked, withdrawnWhy, latest: highest(sparse.versions), deprecatedLatest: null };
         }
-        catch {
+        if (ecosystem === "PyPI") {
+            const facts = await this.pypiFacts(name);
+            return facts ? { ...facts, latest: highest(facts.versions), deprecatedLatest: null } : null;
+        }
+        // Go: `retract` lives in the newest version's go.mod, which is not read (as in the 4DA app).
+        const versions = await this.publishedVersions(ecosystem, name);
+        if (!versions)
+            return null;
+        return { versions, withdrawn: [], withdrawnWhy: {}, latest: highest(versions), deprecatedLatest: null };
+    }
+    /**
+     * npm's abbreviated document: versions without READMEs, with each
+     * version's `deprecated` message. A withdrawn release is never offered as a
+     * fix target: lodash 4.18.0 ("Bad release. Please use lodash@4.17.21
+     * instead.") was recommended by vulnerability_scan (audit B-8, 2026-10-12).
+     * Withdrawn means the app's rule (withdrawn-releases.ts): a deprecated
+     * release with a later clean one on its caret line. A whole-major notice
+     * (glob, tar 6.x) withdraws nothing, or glob 10.4.5 is sent to 12.0.0.
+     */
+    async npmFacts(name) {
+        const key = `fixpath:v${CACHE_VERSION}:npm-facts:${name}`;
+        const hit = this.cache.get(key);
+        if (hit)
+            return hit;
+        const doc = await this.npmDocument(name);
+        if (!doc)
             return null;
+        const versions = doc.versions ?? {};
+        const latest = doc["dist-tags"]?.latest ?? null;
+        const withdrawn = npmExcludedVersions(Object.fromEntries(Object.entries(versions).map(([v, m]) => [v, m?.deprecated])), latest);
+        const out = new Set(withdrawn);
+        const message = (v) => (typeof versions[v]?.deprecated === "string" ? versions[v].deprecated : null);
+        const noticed = Object.keys(versions).filter((v) => !out.has(v) && isNpmDeprecated(versions[v]?.deprecated));
+        const heldSpecs = {};
+        for (const [v, m] of Object.entries(versions)) {
+            const held = heldSpecsOf(m?.dependencies, m?.optionalDependencies);
+            if (Object.keys(held).length > 0)
+                heldSpecs[v] = held;
         }
+        const facts = {
+            versions: Object.keys(versions).filter((v) => !out.has(v)),
+            withdrawn,
+            withdrawnWhy: Object.fromEntries(withdrawn.map((v) => [v, withdrawalText("npm", v, message(v))])),
+            latest,
+            deprecatedLatest: latest && isNpmDeprecated(versions[latest]?.deprecated) ? (message(latest) ?? "deprecated") : null,
+            ...(noticed.length > 0 ? { lineNotices: Object.fromEntries(noticed.map((v) => [v, message(v) ?? "deprecated"])) } : {}),
+            heldSpecs,
+        };
+        this.cache.set(key, facts, "npm", VERSIONS_TTL);
+        return facts;
     }
     /** A crate's sparse-index record: versions and per-version dependency requirements. */
     async cratesSparse(name) {
@@ -165,7 +297,7 @@ export class FixPathSources {
             const res = await fetchWithTimeout(sparseIndexUrl(name), { headers: { "User-Agent": CRATES_USER_AGENT } }, TIMEOUT_MS);
             if (!res.ok)
                 return null;
-            const out = { versions: [], reqs: {} };
+            const out = { versions: [], yanked: [], reqs: {} };
             for (const line of (await res.text()).split("\n")) {
                 if (!line.trim())
                     continue;
@@ -173,6 +305,8 @@ export class FixPathSources {
                     const entry = JSON.parse(line);
                     if (!entry.yanked)
                         out.versions.push(entry.vers);
+                    else
+                        out.yanked.push(entry.vers);
                     const reqs = {};
                     for (const d of entry.deps ?? []) {
                         if (d.kind === "dev")
@@ -193,8 +327,12 @@ export class FixPathSources {
             return null;
         }
     }
-    async pypiVersions(name) {
-        const key = `fixpath:v${CACHE_VERSION}:pypi-versions:${name}`;
+    /**
+     * PyPI's JSON API: every release with files; one whose every file is yanked is withdrawn
+     * (PEP 592, the app's `parse_pypi`). A release with no files cannot be installed and is not listed.
+     */
+    async pypiFacts(name) {
+        const key = `fixpath:v${CACHE_VERSION}:pypi-facts:${name}`;
         const hit = this.cache.get(key);
         if (hit)
             return hit;
@@ -205,12 +343,20 @@ export class FixPathSources {
             if (!res.ok)
                 return null;
             const doc = (await res.json());
-            // A release with files, not all of them yanked.
-            const versions = Object.entries(doc.releases ?? {})
-                .filter(([, files]) => files.length > 0 && files.some((f) => !f.yanked))
-                .map(([v]) => v);
-            this.cache.set(key, versions, "pypi", VERSIONS_TTL);
-            return versions;
+            const out = { versions: [], withdrawn: [], withdrawnWhy: {} };
+            for (const [version, files] of Object.entries(doc.releases ?? {})) {
+                if (!Array.isArray(files) || files.length === 0)
+                    continue;
+                if (files.every((f) => f.yanked === true)) {
+                    out.withdrawn.push(version);
+                    out.withdrawnWhy[version] = withdrawalText("PyPI", version, files.find((f) => f.yanked_reason)?.yanked_reason ?? null);
+                }
+                else {
+                    out.versions.push(version);
+                }
+            }
+            this.cache.set(key, out, "pypi", VERSIONS_TTL);
+            return out;
         }
         catch {
             return null;
@@ -246,26 +392,165 @@ function sparseIndexUrl(name) {
         default: return `https://index.crates.io/${n.slice(0, 2)}/${n.slice(2, 4)}/${n}`;
     }
 }
-/** The minimal clean target for one installed copy, or null when the advisories could not be read. */
-export async function cleanFixTarget(sources, ecosystem, name, perAdvisoryFixes) {
-    if (perAdvisoryFixes.length === 0)
+/**
+ * Whether a checked target may be reported as checked against every advisory (fix_checked
+ * `all_advisories`): its own advisories were read, and, for npm, what it installs at a fixed
+ * version was judged clean (audit 6.2.5 D-4).
+ */
+export function targetCheckedAll(clean) {
+    return !clean.advisoriesUnread && !clean.heldBlocked && clean.heldUnchecked === undefined;
+}
+/** The words for a target's held dependencies (FixTargetResult.heldFrom / heldBlocked / heldUnchecked), or null when there is nothing to say. */
+export function heldNote(clean) {
+    if (clean.heldFrom && clean.heldPast && clean.heldPast.length > 0 && clean.target) {
+        const [first, ...rest] = clean.heldPast;
+        const names = [...new Set(rest.flatMap((p) => p.affected.map((d) => d.name)))];
+        const later = rest.length === 0
+            ? ""
+            : `; ${rest.length === 1 ? rest[0].version : `${rest.length} later releases (${rest[0].version} to ${rest[rest.length - 1].version})`} still bring${rest.length === 1 ? "s" : ""} in an affected ${names.join(", ")}`;
+        return `${heldText(first.version, first.affected)}${later}; so ${clean.target}, the smallest later release on its line whose own advisories and held dependencies are clean`;
+    }
+    if (clean.heldBlocked && clean.target) {
+        const last = clean.heldBlocked.searched[clean.heldBlocked.searched.length - 1];
+        const upTo = last && last !== clean.target ? `up to ${last} ` : "";
+        return `${heldText(clean.target, clean.heldBlocked.affected)}; no release on its line ${upTo}that its own advisories leave clean clears ${clean.heldBlocked.affected.length === 1 ? "it" : "them"}, so ${clean.target} is NOT a clean fix: confirm a release with dependency_check before pinning it`;
+    }
+    if (clean.heldUnchecked !== undefined && clean.target) {
+        return `whether the dependencies ${clean.target} exact-pins or narrowly ranges are affected was NOT CHECKED (${clean.heldUnchecked}): confirm it with dependency_check before pinning it`;
+    }
+    return null;
+}
+/**
+ * The minimal clean target for one installed copy, or null when neither the
+ * advisories nor anything that changes the answer could be read.
+ *
+ * Advisories unreadable, registry readable (audit H5: OSV /v1/query down):
+ * a deprecated or yanked release is still never the target. lodash 4.17.20
+ * went to 4.18.0 ("Bad release") because the whole check was skipped; the
+ * registry facts alone move it to 4.18.1, flagged `advisoriesUnread`.
+ *
+ * With no per-advisory fix at all (advisories that give only `last_affected`,
+ * audit A6), and the installed version known, the registry is asked for the
+ * first published release above the installed one that no known advisory
+ * affects: a fix candidate the advisories never named, flagged
+ * `noAdvisoryFix`, instead of "no fix".
+ */
+export async function cleanFixTarget(sources, ecosystem, name, perAdvisoryFixes, installed) {
+    if (perAdvisoryFixes.length === 0 && !installed)
         return null;
-    const [advisories, published] = await Promise.all([
+    const [advisories, facts] = await Promise.all([
         sources.packageAdvisories(ecosystem, name),
-        sources.publishedVersions(ecosystem, name),
+        sources.releaseFacts(ecosystem, name),
     ]);
+    if (!advisories && !facts && perAdvisoryFixes.length > 0 && WITHDRAWALS_READ.has(ecosystem)) {
+        // Neither OSV's list nor the registry answered: the highest per-advisory fix stands, checked
+        // against the installed version's advisories only, and the answer says the withdrawal check
+        // did not run (lodash 4.18.0, "Bad release", went out with no word of it: final audit 7a).
+        const floor = maxVersion(perAdvisoryFixes, ecosystem) ?? perAdvisoryFixes[0];
+        return { target: floor, basis: "advisory_fixes", floor, floorAffectedBy: [], stillAffectedBy: [], unfixable: [], withheld: [], advisoriesUnread: true, registryUnread: true };
+    }
     if (!advisories)
+        return perAdvisoryFixes.length > 0 && facts ? registryOnlyTarget(ecosystem, perAdvisoryFixes, facts) : null;
+    // Every release the registry lists, the withdrawn ones included so the result can name them;
+    // `excluded` keeps them from ever being the target (FX-H5).
+    const published = facts ? [...facts.versions, ...facts.withdrawn] : null;
+    const excluded = facts?.withdrawn ?? [];
+    const malware = advisories.filter((a) => a.malware).map((a) => a.id);
+    if (perAdvisoryFixes.length > 0) {
+        const clean = smallestCleanVersion({ ecosystem, fixes: perAdvisoryFixes, advisories, published, excluded, installed });
+        if (!clean)
+            return null;
+        if (malware.length > 0)
+            Object.assign(clean, { malware });
+        if (clean.target === null && clean.maliciousLanding)
+            Object.assign(clean, { landingNote: malwareText(name, clean.maliciousLanding) });
+        return withRegistryFacts({ ...clean, ...(facts?.withdrawn.includes(clean.floor) ? { floorWithdrawn: true } : {}) }, ecosystem, perAdvisoryFixes, advisories, facts);
+    }
+    // Only a registry list can show a release past a last_affected bound.
+    if (!published || published.length === 0)
         return null;
-    return smallestCleanVersion({ ecosystem, fixes: perAdvisoryFixes, advisories, published });
+    const clean = smallestCleanVersion({ ecosystem, fixes: [installed], advisories, published, excluded, installed });
+    if (!clean || clean.target === null || clean.target === installed || clean.stillAffectedBy.length > 0)
+        return null;
+    return withRegistryFacts({ ...clean, noAdvisoryFix: true }, ecosystem, [], advisories, facts);
+}
+/**
+ * The registry side of a target: that the registry was not read (so withdrawn releases were
+ * not checked), or the words for each withdrawn release and the installable fix for each
+ * per-advisory fix the registry withdrew (the app's `installable_fix`: the lowest allowed
+ * release above it that the advisories fixed at it do not affect).
+ */
+function withRegistryFacts(clean, ecosystem, fixes, advisories, facts) {
+    // Only the registries whose withdrawals are read (as in the app: Go `retract` and the RubyGems /
+    // Packagist readers are not); for the rest there was nothing to check, so nothing to say.
+    if (!facts)
+        return WITHDRAWALS_READ.has(ecosystem) ? { ...clean, registryUnread: true } : clean;
+    const lineFixes = {};
+    const published = [...facts.versions, ...facts.withdrawn];
+    for (const fix of new Set(fixes)) {
+        if (!facts.withdrawn.includes(fix))
+            continue;
+        const fixedHere = advisories.filter((a) => a.spans.some((s) => s.fixed !== null && compareVersions(s.fixed, fix, ecosystem) === 0));
+        lineFixes[fix] = installableFix({ ecosystem, fix, advisories: fixedHere, published, excluded: facts.withdrawn });
+    }
+    const named = new Set([...clean.withheld, ...Object.values(lineFixes).flatMap((l) => l.withheld)]);
+    const withheldWhy = Object.fromEntries([...named].map((v) => [v, facts.withdrawnWhy[v] ?? withdrawalText(ecosystem, v)]));
+    const notice = clean.target ? facts.lineNotices?.[clean.target] : undefined;
+    return {
+        ...clean,
+        ...(named.size > 0 ? { withheldWhy } : {}),
+        ...(Object.keys(lineFixes).length > 0 ? { lineFixes } : {}),
+        ...(notice ? { targetNotice: lineNoticeText(clean.target, notice) } : {}),
+    };
+}
+/**
+ * With no advisory list: the smallest installable release at or above the
+ * highest per-advisory fix, only when that fix itself is withdrawn or not
+ * published (otherwise the unchecked answer stands as it is). Null when
+ * nothing changes or no installable release qualifies.
+ */
+function registryOnlyTarget(ecosystem, fixes, facts) {
+    if (facts.versions.length === 0)
+        return null;
+    const published = [...facts.versions, ...facts.withdrawn];
+    const clean = smallestCleanVersion({ ecosystem, fixes, advisories: [], published, excluded: facts.withdrawn });
+    if (!clean || (clean.target !== null && clean.target === clean.floor))
+        return null;
+    if (clean.target === null && clean.withheld.length === 0)
+        return null;
+    return withRegistryFacts({ ...clean, floorWithdrawn: facts.withdrawn.includes(clean.floor), advisoriesUnread: true }, ecosystem, fixes, [], facts);
+}
+/** #981 (b): an advisory whose ranges cannot be read leaves the release unknown, never skipped silently. */
+export function unreadableText(ids) {
+    return `the affected ranges of ${ids.join(", ")} cannot be read, so whether any release clears ${ids.length === 1 ? "it" : "them"} is unknown: no release is named`;
+}
+/** The 4DA lead's rule (2026-10-18): no release is offered that brings in an advisory the installed version does not have. */
+export function introducesText(ids) {
+    return `every fixing release brings in ${ids.join(", ")}, which the installed version does not have, so no release is named`;
+}
+/** #981 round 3: an installed copy a malicious advisory affects names no release; the advice is to remove or replace it. */
+export function malwareText(name, ids) {
+    return `${name} is flagged malicious (${ids.join(", ")}): remove or replace ${name}`;
+}
+/** The words for a target that carries a line-wide deprecation notice (FixTargetResult.targetNotice). */
+export function lineNoticeText(version, message) {
+    const quoted = message.length > 120 ? `${message.slice(0, 117)}...` : message;
+    return `${version} is deprecated on npm ("${quoted}"), a notice on its whole line rather than a withdrawn release (no later release on the line is free of it), so it stays the smallest fix without a major upgrade; dependency_check says review for it: tell the user it is deprecated`;
+}
+/** The ecosystems whose registry withdrawals (yanked, deprecated) are read. */
+const WITHDRAWALS_READ = new Set(["npm", "crates.io", "PyPI"]);
+/** `withheldNote` for a checked target: the withdrawn releases passed, in plain words; null when none. */
+export function withheldText(clean, ecosystem) {
+    return withheldNote(clean.withheld, clean.target, clean.withheldWhy ?? {}, ecosystem, clean.stillAffectedBy.length === 0);
 }
 /**
  * Verified targets for many installed copies at once, within a time budget:
  * the copies that could not be checked in time (or offline) are simply
  * absent from the result, and the caller says so. Keyed by `key`.
  */
-export async function verifyFixTargets(sources, items, budgetMs, concurrency = 12) {
+export async function verifyFixTargets(sources, items, budgetMs, concurrency = 12, options = {}) {
     const out = new Map();
-    const todo = items.filter((i) => i.fixes.length > 0);
+    const todo = items.filter((i) => i.fixes.length > 0 || i.installed);
     if (!sources || todo.length === 0)
         return out;
     const deadline = Date.now() + budgetMs;
@@ -278,7 +563,7 @@ export async function verifyFixTargets(sources, items, budgetMs, concurrency = 1
                 timer = setTimeout(() => resolve(null), Math.max(0, deadline - Date.now()));
             });
             try {
-                const clean = await Promise.race([cleanFixTarget(sources, item.ecosystem, item.name, item.fixes).catch(() => null), late]);
+                const clean = await Promise.race([cleanFixTarget(sources, item.ecosystem, item.name, item.fixes, item.installed).catch(() => null), late]);
                 if (clean)
                     out.set(item.key, clean);
             }
@@ -289,99 +574,594 @@ export async function verifyFixTargets(sources, items, budgetMs, concurrency = 1
         }
     };
     await Promise.all(Array.from({ length: Math.min(concurrency, todo.length) }, worker));
+    if (options.heldQuery) {
+        // npm: what each target installs at a fixed version, in one advisory lookup for all of them
+        // (audit 6.2.5 D-4). It gets at least HELD_FLOOR_MS even when the targets used the budget up:
+        // without it a cold scan would downgrade every npm target that holds a dependency.
+        const npm = todo.filter((i) => i.ecosystem === "npm" && out.has(i.key)).map((i) => ({ key: i.key, name: i.name, installed: i.installed, clean: out.get(i.key) }));
+        const held = await withHeldTargets(sources, options.heldQuery, npm, Math.max(deadline, Date.now() + HELD_FLOOR_MS));
+        for (const [key, clean] of held)
+            out.set(key, clean);
+    }
     return out;
 }
-/** One clause for a target that is not the highest per-advisory fix, or null when it is. */
-export function targetNote(clean) {
+/** The least time the held-dependency check of a scan's npm targets gets (verifyFixTargets). */
+const HELD_FLOOR_MS = 3_000;
+/** Said whenever the registry could not be read: withdrawn releases are then not ruled out, never silently. */
+export const REGISTRY_UNREAD_NOTE = "the registry could not be read, so whether it yanked or deprecated this release was not checked";
+/**
+ * One clause for a target that is not the highest per-advisory fix, or null when it is.
+ * Withdrawn releases passed on the way are named in the registry's own words (FX-H5).
+ */
+export function targetNote(clean, ecosystem = "") {
+    if (clean.heldFrom) {
+        // The advisory-side reasoning is about the release the advisories pointed at; the held step follows it.
+        const { heldFrom, heldPast: _past, targetNotice, ...rest } = clean;
+        const base = targetNote({ ...rest, target: heldFrom }, ecosystem);
+        return [base, heldNote(clean), targetNotice ?? null].filter((p) => Boolean(p)).join("; ") || null;
+    }
+    const held = heldNote(clean);
+    if (held) {
+        const { heldBlocked: _b, heldUnchecked: _u, ...rest } = clean;
+        return [targetNote(rest, ecosystem), held].filter((p) => Boolean(p)).join("; ");
+    }
+    const withheld = withheldText(clean, ecosystem);
+    if (clean.advisoriesUnread) {
+        const unchecked = "not checked against the package's other advisories (OSV.dev did not answer)";
+        if (clean.registryUnread)
+            return `${clean.target} is the highest per-advisory fix, ${unchecked}; ${REGISTRY_UNREAD_NOTE}`;
+        // Not "clean": nothing but the installed version's advisories was checked.
+        if (withheld && clean.target)
+            return `${withheld.replace(/ is the smallest clean release$/, " is the smallest installable release past it")}; ${unchecked}`;
+        if (withheld)
+            return `${withheld}; ${unchecked}`;
+        return `${clean.target} is the smallest installable release at or above ${clean.floor}, the highest per-advisory fix, which ${clean.floorWithdrawn ? "is deprecated or yanked on the registry" : "is not a published release"}; ${unchecked}`;
+    }
     const parts = [];
-    if (clean.target && clean.target !== clean.floor) {
-        parts.push(`${clean.target} is the smallest version clear of every advisory a release fixes; ${clean.floor}, the highest per-advisory fix, ${clean.floorAffectedBy.length > 0 ? `is itself affected by ${clean.floorAffectedBy.join(", ")}` : "is not a published release"}`);
+    if (clean.noAdvisoryFix) {
+        parts.push(`no advisory names a fixed version (they give only a last affected one); ${clean.target} is the first published release above the installed version that no known advisory affects`);
+        if (withheld)
+            parts.push(withheld);
+    }
+    else if (clean.target === null) {
+        if (withheld)
+            parts.push(withheld);
+    }
+    else if (clean.target !== clean.floor) {
+        if (clean.floorAffectedBy.length > 0) {
+            parts.push(`${clean.target} is the smallest version clear of every advisory a release fixes; ${clean.floor}, the highest per-advisory fix, is itself affected by ${clean.floorAffectedBy.join(", ")}`);
+            if (withheld)
+                parts.push(withheld);
+        }
+        else if (withheld) {
+            parts.push(withheld);
+        }
+        else {
+            parts.push(`${clean.target} is the smallest version clear of every advisory a release fixes; ${clean.floor}, the highest per-advisory fix, ${clean.floorWithdrawn ? "is deprecated or yanked on the registry" : "is not a published release"}`);
+        }
     }
     if (clean.target && clean.stillAffectedBy.length > 0) {
-        parts.push(`${clean.stillAffectedBy.join(", ")} also affect${clean.stillAffectedBy.length === 1 ? "s" : ""} it and every newer release (no fix published)`);
+        parts.push(`${clean.target} ${remainsText(clean.stillAffectedBy)}: ${clean.stillAffectedBy.length === 1 ? "it affects" : "they affect"} every newer release too`);
     }
+    if (clean.target === null && clean.unreadable && clean.unreadable.length > 0)
+        parts.push(unreadableText(clean.unreadable));
+    if (clean.target === null && clean.landingNote)
+        parts.push(clean.landingNote);
+    if (clean.target === null && clean.introduces && clean.introduces.length > 0)
+        parts.push(introducesText(clean.introduces));
+    if (clean.registryUnread)
+        parts.push(REGISTRY_UNREAD_NOTE);
+    if (clean.targetNotice)
+        parts.push(clean.targetNotice);
     return parts.length > 0 ? parts.join("; ") : null;
 }
-/** The refresh command for one lockfile format. */
-export function refreshCommand(format, name, installed, target) {
+/**
+ * A finding's own fix as the registry still offers it (the app's `installable_fix`): the
+ * advisory's fixed version, or, when the registry withdrew it, the release to take instead
+ * (null: none past it is known), with the withdrawn ones and the plain-words note.
+ */
+export function rowFix(fixed, clean, ecosystem) {
+    const line = fixed && clean?.lineFixes?.[fixed];
+    if (!fixed || !line)
+        return { fixed, withheld: [], note: null };
+    const said = sayWithdrawn(line.withheld, clean.withheldWhy ?? {}, ecosystem);
+    const note = line.fix
+        ? `${said}; ${line.fix} is the smallest release past it that fixes this advisory`
+        : `No installable fix for this advisory: ${said}, and no later release is known to fix it`;
+    return { fixed: line.fix, withheld: line.withheld, note };
+}
+/**
+ * The command that refreshes one transitive copy in place, for the tools it
+ * can be named for (4DA AD-055 ¶4); null for yarn 1 and bun, which have none
+ * (see `manualRefreshSteps`).
+ *
+ * pnpm: at a workspace root (`pnpm-workspace.yaml`), `pnpm update <pkg>`
+ * touches only the root project's tree, so a member's transitive copy stayed
+ * where it was; `-r` reaches every member (measured with pnpm 10.34.6: a
+ * member's mkdirp -> minimist 1.2.5 moved to 1.2.8 only with `-r`). `--depth
+ * Infinity` is the form the fix-path oracle applied (2026-10-10, U04/U10);
+ * pnpm 8.15 to 10.34 also moved a root project's transitive copy without it.
+ */
+export function refreshCommand(format, name, installed, target, workspaceRoot = false) {
+    const ecosystem = format === "cargo" ? "crates.io" : "npm";
+    if (!isShellSafeName(name, ecosystem) || !isShellSafeVersion(installed) || !isShellSafeVersion(target))
+        return null;
     switch (format) {
         case "package-lock":
             return `npm update ${name}`;
         case "pnpm":
-            return `pnpm update ${name}`;
+            return `pnpm update ${workspaceRoot ? "-r " : ""}${name} --depth Infinity`;
         case "yarn-berry":
             return `yarn up -R ${name}`;
         case "yarn":
-            // Yarn 1 has no command that refreshes a transitive copy. Its blocks are keyed
-            // by every spec that resolved to them, and an alias block's first key names
-            // the alias ("string-width-cjs@npm:string-width@^4.2.0"), so name both forms.
-            return `delete every yarn.lock entry that resolves to ${name} (keys "${name}@…" and alias keys "…@npm:${name}@…"), then run yarn install`;
         case "bun":
-            return `delete the ${name} entries from bun.lock, then run bun install`;
+            return null;
         case "cargo":
             return `cargo update -p ${name}@${installed} --precise ${target}`;
     }
 }
+/**
+ * Whether an override (npm `overrides`, pnpm `pnpm.overrides`, yarn `resolutions`) can reach the copy
+ * these blocking parents hold: never when one of them ships it bundled (rule vectors rv-066..rv-068).
+ */
+export function overrideReaches(blocking) {
+    return !blocking.some((b) => b.bundled === true);
+}
+/** The verified in-range refresh of a DECLARED npm-family dependency (DirectFix refresh). */
+function npmDirectRefresh(manager, name) {
+    switch (manager) {
+        case "npm":
+            return `npm update ${name}`;
+        case "pnpm":
+            return `pnpm update ${name} --no-save`;
+        case "yarn1":
+            return `yarn upgrade ${name}`;
+        case "yarn-berry":
+            return `yarn up -R ${name}`;
+    }
+}
+/** How far up from a project directory a workspace lockfile is looked for (the app's MAX_LOCKFILE_ASCENT). */
+const MAX_LOCKFILE_ASCENT = 6;
+/** The npm-family tool whose lockfile holds the project at `dir`, nearest directory first (yarn, pnpm, npm, as the app). */
+function npmManager(dir) {
+    let here = path.resolve(dir);
+    for (let i = 0; i <= MAX_LOCKFILE_ASCENT; i++) {
+        if (fs.existsSync(path.join(here, "yarn.lock"))) {
+            let berry = false;
+            try {
+                berry = fs.readFileSync(path.join(here, "yarn.lock"), "utf-8").split("\n").slice(0, 12).some((l) => l.startsWith("__metadata:"));
+            }
+            catch {
+                berry = false;
+            }
+            return berry ? "yarn-berry" : "yarn1";
+        }
+        if (fs.existsSync(path.join(here, "pnpm-lock.yaml")))
+            return "pnpm";
+        if (fs.existsSync(path.join(here, "package-lock.json")))
+            return "npm";
+        const up = path.dirname(here);
+        if (up === here)
+            break;
+        here = up;
+    }
+    return null;
+}
+function readText(file) {
+    try {
+        return fs.readFileSync(file, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/** The spec `name` is declared with, when exactly one of dependencies / devDependencies / optionalDependencies holds it. */
+export function npmDeclared(packageJson, name) {
+    let pkg;
+    try {
+        pkg = JSON.parse(packageJson);
+    }
+    catch {
+        return null;
+    }
+    const found = ["dependencies", "devDependencies", "optionalDependencies"]
+        .map((s) => pkg?.[s]?.[name])
+        .filter((v) => typeof v === "string");
+    return found.length === 1 ? found[0] : null;
+}
+const PRERELEASE_BASE = /^\d+\.\d+\.\d+-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*$/;
+const FULL_SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+/** The operator a declared npm spec carries: "" for an exact pin, "^" or "~"; null for anything else. */
+function npmOperator(declared) {
+    const d = declared.trim();
+    const digits = (s) => {
+        const parts = s.split(".");
+        return parts.length >= 1 && parts.length <= 3 && parts.every((p) => /^\d+$/.test(p));
+    };
+    // The 4DA lead (2026-10-19): a `^` or `~` on a PRERELEASE base (`^2.0.0-rc.4`, `~1.2.3-beta.1`)
+    // is bounded too: a full X.Y.Z with prerelease identifiers, no build metadata.
+    const base = (s) => digits(s) || PRERELEASE_BASE.test(s);
+    if (d.startsWith("^"))
+        return base(d.slice(1)) ? "^" : null;
+    if (d.startsWith("~"))
+        return base(d.slice(1)) ? "~" : null;
+    const exact = (d.startsWith("=") ? d.slice(1) : d).replace(/^v+/, "");
+    return FULL_SEMVER.test(exact) ? "" : null;
+}
+/** The command that moves a declared npm-family dependency, keeping its operator (quoted: `^` is cmd.exe's escape). */
+export function npmDirectCommand(manager, declared, name, target) {
+    if (!isShellSafeName(name, "npm") || !isShellSafeVersion(target))
+        return null;
+    const op = npmOperator(declared);
+    if (op === null)
+        return null;
+    const spec = op === "" ? `${name}@${target}` : `"${name}@${op}${target}"`;
+    switch (manager) {
+        case "npm":
+            return op === "" ? `npm install ${spec} --save-exact` : `npm install ${spec}`;
+        case "pnpm":
+            return `pnpm up ${spec}`;
+        case "yarn1":
+            return `yarn upgrade ${spec}`;
+        case "yarn-berry":
+            return `yarn up ${spec}`;
+    }
+}
+const unquote = (s) => s.trim().replace(/^["']+|["']+$/g, "");
+const crateKey = (name) => name.trim().toLowerCase().replace(/_/g, "-");
+/** `[dependencies]`, `[dev-dependencies.foo]`, `[target.'cfg(unix)'.build-dependencies]`, ... */
+function cargoTable(header) {
+    const inner = header.replace(/^\[+/, "").replace(/\]+$/, "").trim();
+    let target = null;
+    let rest = inner;
+    if (inner.startsWith("target.")) {
+        const after = inner.slice("target.".length);
+        if (after.startsWith("'") || after.startsWith('"')) {
+            const q = after.slice(1);
+            const close = q.search(/['"]/);
+            if (close < 0)
+                return null;
+            target = q.slice(0, close);
+            rest = q.slice(close + 1).replace(/^\.+/, "");
+        }
+        else {
+            const dot = after.indexOf(".");
+            if (dot < 0)
+                return null;
+            target = after.slice(0, dot);
+            rest = after.slice(dot + 1);
+        }
+    }
+    const dot = rest.indexOf(".");
+    const section = dot < 0 ? rest : rest.slice(0, dot);
+    const key = dot < 0 ? null : unquote(rest.slice(dot + 1));
+    const kind = section === "dependencies" ? "normal" : section === "dev-dependencies" ? "dev" : section === "build-dependencies" ? "build" : null;
+    return kind ? { kind, target, key } : null;
+}
+/** Every declaration of `crate` in a Cargo.toml (by crate name, so a renamed dependency is found through `package = ...`). */
+export function cargoDeclarations(manifest, crate) {
+    const want = crateKey(crate);
+    const found = [];
+    let table = null;
+    const set = (f, field, value) => {
+        if (field === "version")
+            f.req = unquote(value);
+        else if (field === "package")
+            f.pkg = unquote(value);
+        else if (field === "workspace")
+            f.workspace ||= value.trim() === "true";
+        else if (field === "git" || field === "path" || field === "registry")
+            f.otherSource = true;
+    };
+    for (const raw of manifest.split("\n")) {
+        const line = (raw.split("#")[0] ?? "").trim();
+        if (line.startsWith("[")) {
+            table = cargoTable(line);
+            continue;
+        }
+        const eq = line.indexOf("=");
+        if (!table || eq < 0)
+            continue;
+        const k = unquote(line.slice(0, eq));
+        const v = line.slice(eq + 1);
+        let key;
+        let field;
+        if (table.key !== null) {
+            key = table.key;
+            field = k;
+        }
+        else {
+            const dot = k.indexOf(".");
+            if (dot >= 0) {
+                key = unquote(k.slice(0, dot));
+                field = k.slice(dot + 1).trim();
+            }
+            else {
+                key = k;
+                field = null;
+            }
+        }
+        let slot = found.find((d) => d.kind === table.kind && d.target === table.target && d.key === key);
+        if (!slot) {
+            slot = { kind: table.kind, target: table.target, key, f: { req: null, pkg: null, workspace: false, otherSource: false } };
+            found.push(slot);
+        }
+        if (field !== null)
+            set(slot.f, field, v);
+        else if (v.trimStart().startsWith("{")) {
+            const body = v.trim().replace(/^\{/, "").replace(/\}$/, "");
+            for (const kv of body.split(",")) {
+                const at = kv.indexOf("=");
+                if (at >= 0)
+                    set(slot.f, kv.slice(0, at).trim(), kv.slice(at + 1).trim());
+            }
+        }
+        else
+            slot.f.req = unquote(v);
+    }
+    return found
+        .filter((d) => crateKey(d.f.pkg ?? d.key) === want)
+        .map((d) => ({ kind: d.kind, target: d.target, key: d.key, req: d.f.req, workspace: d.f.workspace, otherSource: d.f.otherSource }));
+}
+/** The fix for one Cargo declaration. */
+function cargoDirect(decl, crate, target) {
+    if (decl.otherSource)
+        return null;
+    if (decl.workspace) {
+        return {
+            instruction: `bump ${crate} to ${target} in the workspace root's [workspace.dependencies] (it is inherited here; \`cargo add\` in this crate would replace the inheritance with a local pin)`,
+        };
+    }
+    // Every value spliced below comes from the project's own Cargo.toml or lockfile (C-1).
+    const keyRenamed = crateKey(decl.key) !== crateKey(crate);
+    if (!isShellSafeName(crate, "crates.io") ||
+        !isShellSafeVersion(target) ||
+        (decl.target !== null && !isShellSafeCargoTarget(decl.target)) ||
+        (keyRenamed && !isShellSafeName(decl.key, "crates.io"))) {
+        return { instruction: `bump the ${isShellSafeName(crate, "crates.io") ? crate : "dependency"} requirement in Cargo.toml so it admits the fixed release (no command is named: the declaration holds characters that are unsafe in a command)` };
+    }
+    const r = decl.req?.trim() ?? "";
+    const op = r.startsWith("=") ? "=" : r.startsWith("~") ? "~" : r.startsWith("^") ? "^" : /^\d/.test(r) ? "" : null;
+    if (op === null)
+        return null;
+    let cmd = `cargo add ${op === "" ? `${crate}@${target}` : `"${crate}@${op}${target}"`}`;
+    if (decl.kind === "dev")
+        cmd += " --dev";
+    if (decl.kind === "build")
+        cmd += " --build";
+    // Double quotes: cmd.exe keeps single quotes as part of the argument.
+    if (decl.target)
+        cmd += ` --target "${decl.target}"`;
+    if (crateKey(decl.key) !== crateKey(crate))
+        cmd += ` --rename ${decl.key}`;
+    return { command: cmd };
+}
+/** `go get <module>@v<target>` when go.mod requires the module directly at `installed` and no `replace` points it elsewhere. */
+export function goDirectCommand(goMod, module, installed, target) {
+    if (!isShellSafeName(module, "Go") || !isShellSafeVersion(installed) || !isShellSafeVersion(target))
+        return null;
+    const v = (s) => (s.startsWith("v") ? s : `v${s}`);
+    let inRequire = false;
+    let inReplace = false;
+    let requiredAt = null;
+    for (const raw of goMod.split("\n")) {
+        const line = raw.trim();
+        if (line === "require (")
+            inRequire = true;
+        else if (line === "replace (")
+            inReplace = true;
+        else if (line === ")")
+            inRequire = inReplace = false;
+        const replaced = inReplace ? line : line.startsWith("replace ") ? line.slice("replace ".length) : null;
+        if (replaced !== null && replaced.split(/\s+/)[0] === module)
+            return null;
+        const entry = inRequire ? line : line.startsWith("require ") ? line.slice("require ".length) : null;
+        if (entry !== null && !entry.includes("// indirect")) {
+            const parts = entry.split(/\s+/);
+            if (parts[0] === module)
+                requiredAt = parts[1] ?? null;
+        }
+    }
+    return requiredAt !== null && requiredAt === v(installed) ? `go get ${module}@${v(target)}` : null;
+}
+/** The edit of the requirements line that pins the package with `==` at `installed` (markers, extras kept). */
+export function pypiDirectInstruction(requirements, file, name, installed, target) {
+    const lines = requirements.split("\n");
+    // Compiled output (pip-compile, and `uv pip compile`, whose header the old check missed, or any
+    // file with `# via` annotations) is regenerated from its input: a hand edit is reverted, and an
+    // indirect pin conflicts with its parent (audit 6.2.5 A-4). pypi-advice.ts words the re-compile.
+    if (compiledRequirements(requirements))
+        return null;
+    const norm = (s) => s.toLowerCase().replace(/[_.]/g, "-");
+    const want = norm(name);
+    for (const [i, raw] of lines.entries()) {
+        const line = raw.trim();
+        const at = line.indexOf("==");
+        if (at < 0)
+            continue;
+        const head = line.slice(0, at);
+        const rest = line.slice(at + 2);
+        if (norm((head.split("[")[0] ?? head).trim()) !== want)
+            continue;
+        const endAt = rest.search(/[;\\#\s]/);
+        const end = endAt < 0 ? rest.length : endAt;
+        const version = rest.slice(0, end);
+        const tail = rest.slice(end);
+        const continued = line.endsWith("\\") || line.includes("--hash") || (lines[i + 1]?.trimStart().startsWith("--hash") ?? false);
+        if (continued || version !== installed)
+            continue;
+        return `change \`${line}\` to \`${head}==${target}${tail}\` in ${file}`;
+    }
+    return null;
+}
+/**
+ * The fix for `name` at `installed`, declared in the project at `projectDir`, read from its own
+ * manifest; null when it cannot be named with certainty (see DirectFix).
+ */
+export function directFix(projectDir, ecosystem, name, installed, target) {
+    const read = (file) => readText(path.join(projectDir, file));
+    switch (ecosystem) {
+        case "npm": {
+            const manager = npmManager(projectDir);
+            if (!manager)
+                return null;
+            // yarn's up / upgrade act on the whole workspace: from a member they rewrite siblings too.
+            if ((manager === "yarn1" || manager === "yarn-berry") && !fs.existsSync(path.join(projectDir, "yarn.lock")))
+                return null;
+            const json = read("package.json");
+            const declared = json === null ? null : npmDeclared(json, name);
+            if (declared === null || npmRangeAdmits(declared, installed) !== true)
+                return null;
+            // In an npm workspace member too, run in the member's directory: on lockfiles npm wrote,
+            // `npm update ms` there moved a member's own ^2.1.1 copy (hoisted and nested layouts, npm
+            // 10.9.2, 2026-10-18). An earlier "it does not move" came from a hand-edited fixture lockfile
+            // that carried 1.2.8's integrity under version 1.2.5.
+            // Only a range bounded below the next major (`^`, `~`) is refreshed: a refresh installs the
+            // NEWEST release in range, so a `>=` / `||` / `*` / x-range could jump a major or land on a
+            // withdrawn or held release, and names nothing (fc-059, the app's npm_direct_fix).
+            const op = npmOperator(declared);
+            const bounded = op === "^" || op === "~";
+            if (bounded && npmRangeAdmits(declared, target) === true)
+                return isShellSafeName(name, "npm") ? { command: npmDirectRefresh(manager, name), refresh: true } : null;
+            const command = npmDirectCommand(manager, declared, name, target);
+            return command ? { command } : null;
+        }
+        case "crates.io": {
+            const manifest = read("Cargo.toml");
+            if (manifest === null)
+                return null;
+            const decls = cargoDeclarations(manifest, name);
+            if (decls.length !== 1)
+                return null;
+            const [only] = decls;
+            const admits = only.req !== null ? cargoReqAdmits(only.req, installed) === true : only.workspace;
+            // A workspace-inherited, git, path or alternate-registry entry is never refreshed this way.
+            if (admits && only.req !== null && !only.workspace && !only.otherSource && cargoReqAdmits(only.req, target) === true) {
+                const command = refreshCommand("cargo", name, installed, target);
+                return command ? { command, refresh: true } : null;
+            }
+            return admits ? cargoDirect(only, name, target) : null;
+        }
+        case "Go": {
+            const goMod = read("go.mod");
+            const command = goMod === null ? null : goDirectCommand(goMod, name, installed, target);
+            return command ? { command } : null;
+        }
+        case "PyPI": {
+            // A pin in a file included with `-r` is declared too, and edited there (audit 7g).
+            const files = ["requirements.txt", "requirements-dev.txt", "requirements/base.txt"];
+            for (let i = 0; i < files.length && i < 16; i++) {
+                const body = read(files[i]);
+                if (body === null)
+                    continue;
+                const instruction = pypiDirectInstruction(body, files[i], name, installed, target);
+                if (instruction)
+                    return { instruction };
+                for (const { option, target: inc } of requirementOptions(body)) {
+                    const included = option === "r" ? confinedInclude(path.dirname(path.join(projectDir, files[i])), inc, projectDir) : null;
+                    const rel = included ? path.relative(projectDir, included).replace(/\\/g, "/") : null;
+                    if (rel && !files.includes(rel))
+                        files.push(rel);
+                }
+            }
+            return null;
+        }
+        default:
+            return null;
+    }
+}
+/** For a lockfile with no in-place refresh command (yarn 1, bun): the steps that move the copy. */
+export function manualRefreshSteps(format, name) {
+    // The steps are read and followed; a name a shell would read specially is not echoed into them (C-1).
+    if (!isShellSafeName(name, "npm"))
+        return `refresh this package's ${format === "yarn" ? "yarn.lock" : "bun.lock"} entries by hand: its name contains characters that are unsafe in a command`;
+    // Yarn 1 keys a block by every spec that resolved to it, and an alias block's
+    // first key names the alias ("string-width-cjs@npm:string-width@^4.2.0"), so
+    // name both forms. Deleting the entries and reinstalling is what moved the
+    // copy in the fix-path oracle (case U11).
+    return format === "yarn"
+        ? `delete every yarn.lock entry that resolves to ${name} (keys "${name}@…" and alias keys "…@npm:${name}@…"), then run yarn install`
+        : `delete the ${name} entries from bun.lock, then run bun install`;
+}
+/** Whether a pnpm lockfile sits at a workspace root (`pnpm-workspace.yaml` beside it). */
+function isPnpmWorkspaceRoot(lockfile) {
+    return fs.existsSync(path.join(path.dirname(lockfile), "pnpm-workspace.yaml"));
+}
+/** The refresh command for the project whose lockfile is `lockfile`; null when no command is named for it. */
+export function refreshCommandFor(lockfile, name, installed, target) {
+    let content;
+    try {
+        content = fs.readFileSync(lockfile, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    const format = lockfileFormat(lockfile, content);
+    return format ? refreshCommand(format, name, installed, target, format === "pnpm" && isPnpmWorkspaceRoot(lockfile)) : null;
+}
 /**
  * Whether refreshing `lockfile` moves `name@installed` to a clean version
- * without any parent changing its declared requirement. Null when the
- * lockfile or a requirement cannot be read (the caller keeps "waiting on
- * upstream", the conservative answer).
+ * without any parent changing its declared requirement: `refreshRule` over
+ * every requirement the parents declare (read from the lockfile, else the
+ * parent's registry metadata). Null when the lockfile cannot be read or no
+ * verdict is possible (the caller keeps "waiting on upstream", the
+ * conservative answer).
  */
 export async function refreshVerdict(sources, ecosystem, lockfile, name, installed, target, advisories, published) {
     const parents = readLockfileParents(lockfile, name, installed);
     if (!parents || parents.edges.length === 0)
         return null;
     const isCargo = parents.format === "cargo";
-    const admits = (range, version) => (isCargo ? cargoReqAdmits(range, version) : npmRangeAdmits(range, version));
-    const clean = (v) => !advisories || !advisories.some((a) => advisoryAffects(a, v, ecosystem));
+    const dialect = isCargo ? "cargo" : "npm";
+    // A maintenance notice never makes a copy unclean (#994 review).
+    const clean = (v) => !advisories || !advisories.some((a) => !a.maintenance && advisoryAffects(a, v, ecosystem));
     const releases = (published ?? []).filter((v) => !isPrereleaseVersion(v, ecosystem));
-    const blocking = [];
-    let resolvesTo = null;
     const edgeReqs = await Promise.all(parents.edges.map((edge) => requirementsOf(sources, ecosystem, edge, name)));
+    const reqs = [];
     for (const [i, edge] of parents.edges.entries()) {
         const all = edgeReqs[i];
-        if (all === null || all.length === 0)
-            return null;
+        if (all === null || all.length === 0) {
+            reqs.push({ parent: edge.parent, text: null, dialect, edge }); // not read: the rule cannot count it as admitting
+            continue;
+        }
         // A parent can declare the same crate twice under different names (feature-gated
         // `mio-0_6` / `mio-0_7` aliases): only the requirements this copy satisfies apply.
-        const matching = all.filter((req) => admits(req, installed) === true);
-        const reqs = matching.length > 0 ? [...new Set(matching)] : [...new Set(all)];
-        for (const req of reqs) {
-            if (isCargo) {
-                // `cargo update --precise` moves to exactly the clean target, if every requirement admits it.
-                const ok = admits(req, target);
-                if (ok === null)
-                    return null;
-                if (!ok)
-                    blocking.push({ parent: edge.parent, parentVersion: edge.parentVersion, requirement: req });
-                else
-                    resolvesTo = target;
-                continue;
-            }
-            // npm, pnpm, yarn and bun resolve each requirement to its newest match.
-            if (releases.length > 0) {
+        const asReq = (text) => ({ parent: edge.parent, text, dialect });
+        const matching = all.filter((text) => requirementAdmits(asReq(text), installed) === true);
+        for (const text of new Set(matching.length > 0 ? matching : all))
+            reqs.push({ ...asReq(text), edge });
+    }
+    const rule = refreshRule(installed, target, reqs);
+    if (rule.verdict === "unknown")
+        return null;
+    const blocking = [];
+    const block = (r) => blocking.push({ parent: r.edge.parent, parentVersion: r.edge.parentVersion, requirement: r.text ?? "", ...(r.edge.bundled ? { bundled: true } : {}) });
+    for (const r of reqs)
+        if (requirementAdmits(r, target) === false)
+            block(r);
+    let resolvesTo = null;
+    if (rule.verdict === "refresh" && !rule.inferred) {
+        if (isCargo) {
+            // `cargo update --precise` moves to exactly the clean target, which every requirement admits.
+            resolvesTo = target;
+        }
+        else if (releases.length > 0) {
+            // npm, pnpm, yarn and bun resolve each requirement to its newest match, which must be clean too.
+            for (const r of reqs) {
                 const newest = releases
-                    .filter((v) => admits(req, v) === true)
+                    .filter((v) => requirementAdmits(r, v) === true)
                     .sort((a, b) => compareVersions(b, a, ecosystem))[0];
-                if (!newest || compareVersions(newest, target, ecosystem) < 0 || !clean(newest)) {
-                    blocking.push({ parent: edge.parent, parentVersion: edge.parentVersion, requirement: req });
-                }
-                else if (!resolvesTo || compareVersions(newest, resolvesTo, ecosystem) < 0) {
+                if (!newest || compareVersions(newest, target, ecosystem) < 0 || !clean(newest))
+                    block(r);
+                else if (!resolvesTo || compareVersions(newest, resolvesTo, ecosystem) < 0)
                     resolvesTo = newest;
-                }
-            }
-            else {
-                const ok = admits(req, target);
-                if (ok === null)
-                    return null;
-                if (!ok)
-                    blocking.push({ parent: edge.parent, parentVersion: edge.parentVersion, requirement: req });
             }
         }
     }
-    let command = refreshCommand(parents.format, name, installed, target);
-    if (isCargo && blocking.length === 0) {
+    const refreshFixes = rule.verdict === "refresh" && blocking.length === 0;
+    const named = refreshCommand(parents.format, name, installed, target, parents.format === "pnpm" && isPnpmWorkspaceRoot(lockfile));
+    let command = named ?? manualRefreshSteps(parents.format === "bun" ? "bun" : "yarn", name);
+    if (isCargo && refreshFixes) {
         let content;
         try {
             content = fs.readFileSync(lockfile, "utf-8");
@@ -392,15 +1172,18 @@ export async function refreshVerdict(sources, ecosystem, lockfile, name, install
         const prereqs = await cargoPrecisePrerequisites(sources, content, name, installed, target);
         if (prereqs === null)
             return null;
+        if (prereqs.some((p) => !/^[A-Za-z0-9_-]+(?:@[0-9A-Za-z.+_-]+)?$/.test(p)))
+            return null;
         if (prereqs.length > 0)
             command = `cargo update ${prereqs.map((p) => `-p ${p}`).join(" ")} && ${command}`;
     }
     return {
-        refreshFixes: blocking.length === 0,
+        refreshFixes,
+        inferred: rule.inferred,
         format: parents.format,
         command,
         blocking,
-        resolvesTo: blocking.length === 0 ? resolvesTo : null,
+        resolvesTo: refreshFixes ? resolvesTo : null,
     };
 }
 async function requirementsOf(sources, ecosystem, edge, name) {