@wardby/cli 0.6.0 → 0.7.0

package/dist/coding/registry/pypi.js

@@ -2,29 +2,24 @@
  * PyPI registry adapter: parses PyPI allowlist syntax (PEP 503 names, PEP
  * 440 specifiers), routes proxy requests against the PEP 691 JSON Simple
  * API plus PEP 658 metadata files, restricts downloads to wheels, and
- * configures pip for the sandboxed worker to use the proxy as its only
- * index with binary-only installs.
+ * configures pip and uv for the sandboxed worker to use the proxy as their
+ * only index with binary-only installs.
  */
 import { clean as pepClean, compare as pepCompare, satisfies as pepSatisfies, validRange } from "@renovatebot/pep440";
 import { unzipSync, strFromU8 } from "fflate";
+import { normalizeUvLock, pypiLockfilePlan } from "./pypi-plan.js";
+import { isPypiProjectName, MAX_EXTRAS, normalizePypiName, parseExtras, requiredDists, requiresDist, } from "./pypi-requirements.js";
 import { AllowlistEntryError, RegistryError, } from "./types.js";
 const UPSTREAM = "https://pypi.org/simple/";
 const SIMPLE_JSON = "application/vnd.pypi.simple.v1+json";
 /** name, an optional `[extras]` group (checked separately), then the specifier. */
 const ENTRY = /^([A-Za-z0-9][A-Za-z0-9._-]*)\s*(?:\[([^\]]*)\])?\s*(.*)$/;
-/** The most extras one allowlist entry or dependency line may name. */
-export const MAX_EXTRAS = 32;
 const WHEEL_METADATA_LIMIT = 64 * 1024 * 1024;
+export { isPypiProjectName, MAX_EXTRAS, normalizePypiName, parseExtras, requiredDists, requiresDist };
 function uploadTime(file) {
     const time = file["upload-time"] ? Date.parse(file["upload-time"]) : NaN;
     return Number.isNaN(time) ? null : new Date(time);
 }
-/** A valid PyPI project name (PEP 508): ASCII letters and digits, with
- *  `.`, `_` and `-` allowed only between them. */
-const PROJECT_NAME = /^(?:[A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9._-]*[A-Za-z0-9])$/;
-export function isPypiProjectName(name) {
-    return PROJECT_NAME.test(name);
-}
 function decoded(segment) {
     try {
         return decodeURIComponent(segment);
@@ -35,12 +30,12 @@ function decoded(segment) {
 }
 function projectName(segment) {
     const name = decoded(segment);
-    if (!PROJECT_NAME.test(name))
+    if (!isPypiProjectName(name))
         throw new RegistryError(400, "wardby_bad_request", "not a valid Python project name");
     return normalizePypiName(name);
 }
-export function normalizePypiName(name) {
-    return name.toLowerCase().replace(/[-_.]+/g, "-");
+function isSdist(filename) {
+    return /\.(?:tar\.gz|zip)$/.test(filename);
 }
 /** Version from a wheel ("name-1.0-py3-none-any.whl") or sdist ("name-1.0.tar.gz") filename. */
 function versionOf(filename) {
@@ -49,139 +44,15 @@ function versionOf(filename) {
     const sdist = filename.match(/^.+?-(\d[^-]*)\.(?:tar\.gz|zip)$/);
     return sdist ? sdist[1] : null;
 }
-/** Normalized (PEP 685), sorted, de-duplicated extras from the text inside
- *  `[...]`, or null when any is not a valid extra name (PEP 508: the same
- *  shape as a project name), the list is empty, or it names too many. */
-export function parseExtras(list) {
-    const items = list.split(",").map((item) => item.trim());
-    if (items.length > MAX_EXTRAS || items.some((item) => !PROJECT_NAME.test(item)))
-        return null;
-    return [...new Set(items.map(normalizePypiName))].sort();
-}
-/** The string literals a marker compares `extra` to with `==` or `===`
- *  (either operand order), normalized; null when the marker never mentions
- *  `extra`. Tokenized, so a quoted value never counts as a clause. Fails
- *  closed: when `extra` appears in any shape this does not fully recognise
- *  (`extra in "a b"`, `extra.x`, a bare `extra`, an unbalanced quote), the
- *  line is gated on no extra at all, so it is never followed. */
-function markerExtras(marker) {
-    if (!/\bextra\b/.test(marker))
-        return null;
-    const tokens = marker.match(/"[^"]*"|'[^']*'|===|==|!=|<=|>=|~=|[A-Za-z_][A-Za-z0-9_.]*|\S/g) ?? [];
-    const isLiteral = (token) => token !== undefined && token.length >= 2 && (token[0] === '"' || token[0] === "'");
-    const isEquals = (token) => token === "==" || token === "===";
-    // A lone quote (unterminated string) means the marker cannot be read.
-    if (tokens.some((token) => token === '"' || token === "'"))
-        return [];
-    const found = [];
-    let recognised = 0;
-    for (let i = 0; i < tokens.length; i++) {
-        if (tokens[i] !== "extra")
-            continue;
-        let value = null;
-        if (isEquals(tokens[i + 1]) && isLiteral(tokens[i + 2]))
-            value = tokens[i + 2].slice(1, -1);
-        else if (isEquals(tokens[i - 1]) && isLiteral(tokens[i - 2]))
-            value = tokens[i - 2].slice(1, -1);
-        if (value === null)
-            return [];
-        recognised++;
-        if (PROJECT_NAME.test(value))
-            found.push(normalizePypiName(value));
-    }
-    // `extra` only inside quoted values: not a clause, but not one this reads either.
-    return recognised === 0 ? [] : found;
-}
-const REQUIREMENT = /^([A-Za-z0-9][A-Za-z0-9._-]*)\s*(?:\[([^\]]*)\])?/;
-// Splits each Requires-Dist value only at its first `;` (the marker), which is
-// all wheel METADATA needs: no `name @ url` with a `;` in the URL, no comments
-// or line continuations as in a requirements file.
-function requirementLines(metadataText) {
-    let self = null;
-    const lines = [];
-    for (const line of metadataText.split(/\r?\n/)) {
-        // The headers end at the first truly empty line; the description
-        // follows. A whitespace-only line is a folded header's continuation.
-        if (line === "")
-            break;
-        if (line.startsWith("Name:")) {
-            const name = line.slice("Name:".length).trim();
-            if (self === null && PROJECT_NAME.test(name))
-                self = normalizePypiName(name);
-            continue;
-        }
-        if (!line.startsWith("Requires-Dist:"))
-            continue;
-        const value = line.slice("Requires-Dist:".length).trim();
-        const match = value.match(REQUIREMENT);
-        if (!match || !PROJECT_NAME.test(match[1]))
-            continue;
-        const semicolon = value.indexOf(";", match[0].length);
-        lines.push({
-            name: normalizePypiName(match[1]),
-            // A malformed extras list still installs the package, just none of its extras.
-            extras: match[2] === undefined ? [] : (parseExtras(match[2]) ?? []),
-            gate: semicolon === -1 ? null : markerExtras(value.slice(semicolon + 1)),
-        });
-    }
-    return { self, lines };
-}
-/**
- * The dependencies a wheel's METADATA declares for an install of the package
- * with `extras`: every line without an `extra == "…"` marker clause, plus the
- * lines whose marker names one of `extras` (other marker clauses are ignored,
- * so a requested extra's lines are included on every platform). A line gated
- * on any other extra is skipped. Each dependency carries the extras its line
- * asks of it (`uvicorn[standard]`); a line naming the package itself
- * (`celery[redis]; extra == "all"`) adds those extras to this install
- * instead. Names and extras are validated and normalized.
- *
- * Policy, not pip: a plain install (no `extras`) follows no extras at all,
- * neither its own (a self-referencing line) nor its dependencies' — each
- * dependency comes back bare, so extras are followed only along a chain that
- * starts at an allowlist entry naming extras.
- */
-export function requiredDists(metadataText, extras = []) {
-    const { self, lines } = requirementLines(metadataText);
-    const requested = new Set(extras.map(normalizePypiName));
-    const plain = requested.size === 0;
-    const included = (line) => line.gate === null || line.gate.some((extra) => requested.has(extra));
-    for (let grew = !plain; grew;) {
-        grew = false;
-        for (const line of lines) {
-            if (line.name !== self || !included(line))
-                continue;
-            for (const extra of line.extras) {
-                if (requested.size >= MAX_EXTRAS || requested.has(extra))
-                    continue;
-                requested.add(extra);
-                grew = true;
-            }
-        }
-    }
-    const out = new Map();
-    for (const line of lines) {
-        if (line.name === self || !included(line))
-            continue;
-        const merged = out.get(line.name) ?? new Set();
-        if (!plain)
-            for (const extra of line.extras)
-                if (merged.size < MAX_EXTRAS)
-                    merged.add(extra);
-        out.set(line.name, merged);
-    }
-    return [...out].map(([name, merged]) => ({ name, extras: [...merged].sort() }));
-}
-/** Dependency names a METADATA declares for a plain install (no extras). */
-export function requiresDist(metadataText) {
-    return requiredDists(metadataText).map((dependency) => dependency.name);
-}
 export const pypiAdapter = {
     id: "pypi",
     osvEcosystem: "PyPI",
     upstreamHosts: ["pypi.org", "files.pythonhosted.org"],
     collectExclude: [".venv", "venv", "__pycache__"],
     dependenciesInMetadata: false,
+    // uv records the proxy's URLs in a uv.lock it writes through it.
+    lockfiles: { names: ["uv.lock"], normalize: (content, registryUrl) => normalizeUvLock(content, registryUrl) },
+    lockfilePlan: pypiLockfilePlan,
     parseAllowlistEntry(raw) {
         const match = raw.trim().match(ENTRY);
         if (!match)
@@ -251,29 +122,37 @@ export const pypiAdapter = {
             });
             versions.set(version, entry);
         }
-        // Keep only what renderMetadata and resolveFileMetadata read: wheels,
-        // with the PEP 691 file fields pip uses.
+        // Keep only what renderMetadata and resolveFileMetadata read: wheels and
+        // sdists, with the PEP 691 file fields pip and uv use. An sdist is listed
+        // (so a uv.lock written through the proxy keeps it, as one written
+        // against PyPI does) but never served: downloads are wheels only, and
+        // PIP_ONLY_BINARY / UV_NO_BUILD keep both clients off it. Its metadata
+        // file is never offered.
         const raw = {
             name: index.name,
             files: index.files
-                .filter((file) => file.filename.endsWith(".whl") && !file.yanked)
-                .map((file) => ({
-                filename: file.filename,
-                url: file.url,
-                ...(file.hashes ? { hashes: file.hashes } : {}),
-                ...(file["upload-time"] ? { "upload-time": file["upload-time"] } : {}),
-                ...(file.size !== undefined ? { size: file.size } : {}),
-                ...(file["core-metadata"] !== undefined ? { "core-metadata": file["core-metadata"] } : {}),
-                ...(file["dist-info-metadata"] !== undefined ? { "dist-info-metadata": file["dist-info-metadata"] } : {}),
-                ...(file["requires-python"] !== undefined ? { "requires-python": file["requires-python"] } : {}),
-            })),
+                .filter((file) => (file.filename.endsWith(".whl") || isSdist(file.filename)) && !file.yanked)
+                .map((file) => {
+                const wheel = file.filename.endsWith(".whl");
+                return {
+                    filename: file.filename,
+                    url: file.url,
+                    ...(file.hashes ? { hashes: file.hashes } : {}),
+                    ...(file["upload-time"] ? { "upload-time": file["upload-time"] } : {}),
+                    ...(file.size !== undefined ? { size: file.size } : {}),
+                    ...(wheel && file["core-metadata"] !== undefined ? { "core-metadata": file["core-metadata"] } : {}),
+                    ...(wheel && file["dist-info-metadata"] !== undefined
+                        ? { "dist-info-metadata": file["dist-info-metadata"] }
+                        : {}),
+                    ...(file["requires-python"] !== undefined ? { "requires-python": file["requires-python"] } : {}),
+                };
+            }),
         };
         return { name: normalizePypiName(index.name), versions, raw };
     },
     renderMetadata(meta, keep, keptFiles, proxyBase) {
         const index = meta.raw;
         const files = index.files
-            .filter((file) => file.filename.endsWith(".whl"))
             .filter((file) => keep.has(versionOf(file.filename) ?? "") && keptFiles.has(file.filename))
             .map((file) => ({
             ...file,
@@ -327,6 +206,13 @@ export const pypiAdapter = {
                 PIP_CACHE_DIR: cacheDir,
                 PIP_DISABLE_PIP_VERSION_CHECK: "1",
                 PIP_NO_INPUT: "1",
+                // uv reads none of pip's settings: without these it goes straight to pypi.org,
+                // which the sandbox can't reach. UV_NO_BUILD refuses sdists from the index (the
+                // wheels-only rule) and still builds the project itself.
+                UV_DEFAULT_INDEX: index.toString(),
+                UV_NO_BUILD: "1",
+                UV_CACHE_DIR: `${cacheDir}/uv`,
+                UV_PYTHON_DOWNLOADS: "never",
             },
             files: [],
         };

package/dist/coding/registry/refusal-hints.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared wording for package refusals served by the registry proxy. Pure (no provider imports) so the
+ * proxy, the run report, and the PR banner all read one table.
+ */
+export declare const PACKAGE_NOT_ALLOWED = "wardby_package_not_allowed";
+export declare const PACKAGE_NOT_ALLOWED_PENDING = "wardby_package_not_allowed_pending";
+export declare const GRAPH_LIMIT = "wardby_graph_limit";
+export declare const GRAPH_INCOMPLETE = "wardby_graph_incomplete";
+export interface WalkProgress {
+    walked: number;
+    queued: number;
+}
+export declare function notAllowedMessage(name: string, ecosystem: string, hasAllowlist: boolean): string;
+export declare function notAllowedPendingMessage(name: string, ecosystem: string, progress: WalkProgress): string;
+export declare function graphLimitMessage(name: string, ecosystem: string, limit: number): string;
+export declare function graphIncompleteMessage(name: string, ecosystem: string, progress: WalkProgress): string;
+/** Static guidance for a stored refusal code (get_run `hint`); undefined for unknown codes. */
+export declare function refusalHint(code: string): string | undefined;
+/** Short parenthetical for the PR banner; undefined for unknown codes. */
+export declare function refusalMeaning(code: string): string | undefined;

package/dist/coding/registry/refusal-hints.js

@@ -0,0 +1,61 @@
+/**
+ * Shared wording for package refusals served by the registry proxy. Pure (no provider imports) so the
+ * proxy, the run report, and the PR banner all read one table.
+ */
+export const PACKAGE_NOT_ALLOWED = "wardby_package_not_allowed";
+export const PACKAGE_NOT_ALLOWED_PENDING = "wardby_package_not_allowed_pending";
+export const GRAPH_LIMIT = "wardby_graph_limit";
+export const GRAPH_INCOMPLETE = "wardby_graph_incomplete";
+function packages(count) {
+    return `${count.toLocaleString("en-US")} package${count === 1 ? "" : "s"}`;
+}
+export function notAllowedMessage(name, ecosystem, hasAllowlist) {
+    const why = hasAllowlist
+        ? `${name} (${ecosystem}) is not on this agent's allowlist, and no allowlisted package this run resolved depends on it (a package added to the project directly must itself be allowlisted)`
+        : `${name} (${ecosystem}) is not allowed: this agent has no allowlist for ${ecosystem}`;
+    return `${why}. The agent's owner must allowlist it; retrying will not help.`;
+}
+export function notAllowedPendingMessage(name, ecosystem, progress) {
+    return (`${name} (${ecosystem}) is not on this agent's allowlist, and was not found among the allowlisted packages' dependencies after ` +
+        `${packages(progress.walked)}, at least ${progress.queued.toLocaleString("en-US")} more queued. ` +
+        `It may still be reachable, but the walk was cut short; retrying rarely helps. ` +
+        `The agent's owner must allowlist ${name} directly.`);
+}
+export function graphLimitMessage(name, ecosystem, limit) {
+    return (`${name} (${ecosystem}) wasn't reached before this run's dependency graph walk hit its limit of ${packages(limit)} ` +
+        `(REGISTRY_MAX_GRAPH_PACKAGES); retrying will not help. ` +
+        `The agent's owner must allowlist ${name} directly, or the operator can raise the limit.`);
+}
+export function graphIncompleteMessage(name, ecosystem, progress) {
+    return (`${name} (${ecosystem}) is still being checked against the allowed packages' dependency graph after ${packages(progress.walked)}, ` +
+        `${progress.queued.toLocaleString("en-US")} still queued; the walk timed out before checking it (usually a slow upstream for that package, or another request's walk running out of time). Please try again shortly.`);
+}
+const OWNER = "The agent's owner must allowlist the package directly; retrying will not help.";
+const HINTS = {
+    [PACKAGE_NOT_ALLOWED]: `The package is not on the agent's allowlist and no allowlisted package the run resolved depends on it. ${OWNER}`,
+    [PACKAGE_NOT_ALLOWED_PENDING]: `The dependency walk ended before reaching the package. Retrying rarely helps. ${OWNER}`,
+    [GRAPH_LIMIT]: `The run's dependency graph walk hit REGISTRY_MAX_GRAPH_PACKAGES before reaching the package, so it may not be in the graph at all. Retrying will not help. The agent's owner must allowlist the package directly, or the operator can raise the limit.`,
+    [GRAPH_INCOMPLETE]: "The walk reached the package but timed out before checking its versions, usually a slow upstream. Try again shortly.",
+    wardby_version_filtered: "Every version the agent may use is newer than the release-age limit, outside the allowlisted range, or has a blocking advisory. Pin an older version, or the agent's owner can change the allowlist or policy.",
+    wardby_file_not_allowed: "The registry serves wheels only, and the allowed versions of this package publish only source distributions. Use a version or package that ships a wheel, or ask the agent's owner.",
+};
+/** What each refusal code means to someone reading the PR, without the registry's internals. */
+const MEANINGS = {
+    [PACKAGE_NOT_ALLOWED]: "not on the allowlist, or only reachable through a refused package; the owner must allowlist it",
+    [PACKAGE_NOT_ALLOWED_PENDING]: "not reached before the dependency walk stopped; the owner must allowlist it",
+    [GRAPH_LIMIT]: "not reached before the run's dependency graph walk hit its package limit; the owner must allowlist it directly",
+    [GRAPH_INCOMPLETE]: "still being checked against the allowed packages' dependency graph; retry shortly",
+    wardby_version_filtered: "withheld: newer than the release-age limit, or a high-severity advisory",
+    wardby_file_not_allowed: "no wheel to install: only source distributions, which the registry does not serve",
+    wardby_lockfile_integrity_mismatch: "the lock file's integrity does not match the registry's",
+    wardby_upstream_error: "the upstream registry failed (transient)",
+    wardby_audit_unavailable: "the advisory check was unavailable (transient)",
+};
+/** Static guidance for a stored refusal code (get_run `hint`); undefined for unknown codes. */
+export function refusalHint(code) {
+    return Object.hasOwn(HINTS, code) ? HINTS[code] : undefined;
+}
+/** Short parenthetical for the PR banner; undefined for unknown codes. */
+export function refusalMeaning(code) {
+    return Object.hasOwn(MEANINGS, code) ? MEANINGS[code] : undefined;
+}

package/dist/coding/registry/refusal-wording.d.ts

@@ -0,0 +1,11 @@
+import type { RegistryRefusalSummary } from "./report.js";
+/** Untrusted names stay bounded code spans with mentions and markup defused. */
+export declare function codeSpan(value: string): string;
+/**
+ * The ⛔ blocked status (or, with `blocked: false`, the ⚠️ warning) for a run's refusals, as GitHub/Jira
+ * Markdown or, with `slack`, as Slack mrkdwn (already escaped).
+ */
+export declare function packageRefusalWording(refusals: readonly RegistryRefusalSummary[], opts?: {
+    blocked?: boolean;
+    slack?: boolean;
+}): string;

package/dist/coding/registry/refusal-wording.js

@@ -0,0 +1,56 @@
+/** Fixed operator guidance from structured registry codes, never registry free text. */
+import { GRAPH_INCOMPLETE, GRAPH_LIMIT, PACKAGE_NOT_ALLOWED, PACKAGE_NOT_ALLOWED_PENDING } from "./refusal-hints.js";
+const HELP_URL = "https://github.com/wardby/wardby/blob/main/help/coding-packages.md";
+const HELP_LABEL = "Help: package allowlist";
+const ALLOWLIST = new Set([PACKAGE_NOT_ALLOWED, PACKAGE_NOT_ALLOWED_PENDING, GRAPH_LIMIT]);
+/** Upstream or check failures that usually pass: a later run may succeed unchanged. */
+const TRANSIENT = new Set([
+    GRAPH_INCOMPLETE,
+    "wardby_upstream_error",
+    "wardby_upstream_unavailable",
+    "wardby_audit_unavailable",
+    "wardby_download_idle",
+]);
+/** Untrusted names stay bounded code spans with mentions and markup defused. */
+export function codeSpan(value) {
+    // eslint-disable-next-line no-control-regex -- stripping untrusted control characters.
+    const withoutControls = value.replace(/[`\u0000-\u001f\u007f<>]/g, " ");
+    const safe = withoutControls.replace(/\s+/g, " ").replace(/@/g, "@​").slice(0, 120);
+    return `\`${safe}\``;
+}
+/**
+ * The ⛔ blocked status (or, with `blocked: false`, the ⚠️ warning) for a run's refusals, as GitHub/Jira
+ * Markdown or, with `slack`, as Slack mrkdwn (already escaped).
+ */
+export function packageRefusalWording(refusals, opts = {}) {
+    const blocked = opts.blocked ?? true;
+    const bold = (text) => (opts.slack ? `*${text}*` : `**${text}**`);
+    const distinct = [...new Map(refusals.map((r) => [JSON.stringify([r.ecosystem, r.name, r.reason]), r])).values()];
+    const lines = distinct.slice(0, 10).map((r) => {
+        const code = /^wardby_[a-z_]+$/.exec(r.reason)?.[0] === r.reason ? ` (\`${r.reason}\`)` : "";
+        const guidance = ALLOWLIST.has(r.reason)
+            ? "not on this agent's allowlist; add it to `codingProfile.packageAllowlist`"
+            : r.reason === "wardby_version_filtered"
+                ? "no version passed the release-age, advisory or malware checks; wait or adjust `packagePolicy.minReleaseAgeDays`, accept an advisory in `packagePolicy.acceptedAdvisories`, or upgrade. Never bypass malware checks"
+                : r.reason === "wardby_lockfile_entry_unsupported"
+                    ? "the lock file installs it from git or a URL, which the registry cannot verify; depend on a registry version instead"
+                    : TRANSIENT.has(r.reason)
+                        ? "the registry could not finish checking it (a slow or failing upstream); mention `@wardby` again to retry"
+                        : "refused by the package registry; review the package policy and registry error before retrying";
+        return `- ${codeSpan(r.ecosystem)} ${codeSpan(r.name)}: ${guidance}${code}`;
+    });
+    if (distinct.length > 10)
+        lines.push(`- ${distinct.length - 10} more refused packages.`);
+    const text = [
+        blocked
+            ? `⛔ ${bold("Blocked by the package registry: no changes were made.")} Coding sub-runs couldn't install:`
+            : `⚠️ ${bold("Dependency install incomplete.")} Coding sub-runs couldn't install:`,
+        ...lines,
+        "",
+        "To unblock: use `update_agent` to update `codingProfile.packageAllowlist` or `codingProfile.packagePolicy` as appropriate (needs `packages:approve` or `agents:admin`), then mention `@wardby` again. ",
+    ].join("\n");
+    // Slack's three control characters; the names cannot hold < or > (codeSpan), but may hold &.
+    return opts.slack
+        ? `${text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")}<${HELP_URL}|${HELP_LABEL}>`
+        : `${text}[${HELP_LABEL}](${HELP_URL})`;
+}

package/dist/coding/registry/report.d.ts

@@ -1,9 +1,3 @@
-/**
- * The one summary of a run's RegistryFetch rows, shared by get_run and the
- * coding executor's PR-body report so both deduplicate identically: served
- * packages collapse on ecosystem + name + version (a retried download is one
- * package), refusals on ecosystem + name + reason.
- */
 export interface RegistryFetchRow {
     ecosystem: string;
     name: string;
@@ -13,24 +7,92 @@ export interface RegistryFetchRow {
     sizeBytes: number | null;
     /** `-/plan` for a refusal a lockfile plan recorded (see PLAN_FETCH_FILENAME). */
     filename?: string | null;
+    /** The coding run that recorded it; needed when rows of several runs are summarized together. */
+    runId?: string;
 }
 /** The `filename` a lockfile plan records its refusals under. */
 export declare const PLAN_REFUSAL_FILENAME = "-/plan";
+/**
+ * The `filename` of a refusal recorded only from an index listing: the
+ * registry answered a metadata request whose kept versions have no file the
+ * client may download (a PyPI project published only as an sdist, or whose
+ * every wheel is too new). The installer may only have looked at the name
+ * (a resolver exploring candidates, a dependency under a marker that does not
+ * apply), so such a refusal is weaker evidence than a refused download.
+ *
+ * The rule, the same for every ecosystem: a listing-only refusal is cleared
+ * like any refusal of a whole name, by any version of that name served after
+ * it in the same run (summarizeRegistryFetches). One left standing (nothing
+ * of that name was served) is marked `listingOnly`. It is reported to the
+ * agent (`wardby-packages`, GET /registry/-/refusals) and in get_run, and:
+ * - a coding sub-run failed: it counts toward ⛔ "Blocked by the package
+ *   registry" and Slack `run_blocked` like any refusal (blockingRefusals in
+ *   core/host-status.ts);
+ * - the run made no changes (and none failed): it is a ⚠️ line on the status,
+ *   never ⛔ or `run_blocked` (a package whose only release has nothing but
+ *   too-new wheels can be why);
+ * - a pull request resulted: it adds nothing, neither to the description's
+ *   install warning and package section nor to the status (warningRefusals).
+ */
+export declare const LISTING_REFUSAL_FILENAME = "-/listing";
+/** The refusals a pull request description or a not-blocked status warns
+ *  about: all but listing-only ones (see LISTING_REFUSAL_FILENAME). */
+export declare function warningRefusals<T extends {
+    listingOnly?: boolean;
+}>(refusals: readonly T[]): T[];
 /** Distinct refusals lockfile plans recorded (ecosystem + name + version +
  *  reason), however often the lockfile was planned. */
 export declare function countPlanRefusals(rows: readonly RegistryFetchRow[]): number;
+/** A served row's `reason` when serving it waived blocking advisories the
+ *  run's packagePolicy.acceptedAdvisories lists: this prefix, then the
+ *  waived advisory ids joined by ", ". */
+export declare const ACCEPTED_ADVISORIES_PREFIX = "accepted advisories: ";
+/** The served-row reason recording these waived advisory ids, or undefined
+ *  when none were waived (the row then has no reason, as before). */
+export declare function acceptedAdvisoriesReason(ids: readonly string[]): string | undefined;
+/** The waived advisory ids a served row's reason records (empty for any
+ *  other reason, or none). */
+export declare function parseAcceptedAdvisories(reason: string | null | undefined): string[];
 export interface RegistryPackageSummary {
     ecosystem: string;
     name: string;
     version: string;
     /** Bytes served (RegistryFetch.sizeBytes); null when not recorded. */
     size: number | null;
+    /** Blocking advisories waived to serve it (the run's accepted set);
+     *  absent when none were. */
+    acceptedAdvisories?: string[];
 }
-export interface RegistryRefusalSummary {
+export type RegistryRefusalSummary = {
     ecosystem: string;
     name: string;
     reason: string;
-}
+    /** Static guidance for the code (shared with the proxy message and the PR banner); absent for unknown codes. */
+    hint?: string;
+    /** Every row behind it was an index listing's (LISTING_REFUSAL_FILENAME); absent otherwise. */
+    listingOnly?: true;
+};
+/**
+ * Rows must be in the order they were recorded (createdAt ascending): a
+ * refusal followed by a served row for the same package in the same run
+ * (`runId`; rows without one count as one run) no longer counts, since that
+ * run's install went on to get it (npm retrying a temporary
+ * `wardby_upstream_error`, an audit that was briefly unavailable). A package
+ * served to a sibling sub-run never clears another run's refusal. A refusal
+ * of one version is cleared only by that version being served; a refusal of
+ * the whole name (no version) by any version of it. A refusal recorded after
+ * the package was served still counts. Cleared refusals are left out of every
+ * surface (get_run, the PR warning, the status comments, Slack), because each
+ * of them tells the user the install did not finish, which is then untrue.
+ *
+ * Known limits: order is by record time, and a served row is recorded when
+ * its download finishes (no start time is stored), so a download that started
+ * before a concurrent refusal of the same version in the same run, and
+ * finished after it, clears it; rows in the same millisecond have no
+ * tiebreaker. Matching is per version, not per file, so serving any file of
+ * a PyPI release clears a refused file of that release (another platform's
+ * too-new wheel).
+ */
 export declare function summarizeRegistryFetches(rows: readonly RegistryFetchRow[]): {
     packages: RegistryPackageSummary[];
     packageRefusals: RegistryRefusalSummary[];

package/dist/coding/registry/report.js

@@ -1,5 +1,41 @@
+/**
+ * The one summary of a run's RegistryFetch rows, shared by get_run and the
+ * coding executor's PR-body report so both deduplicate identically: served
+ * packages collapse on ecosystem + name + version (a retried download is one
+ * package), refusals on ecosystem + name + reason.
+ */
+import { ACCEPTED_ADVISORY_ID } from "./allowlist.js";
+import { refusalHint } from "./refusal-hints.js";
 /** The `filename` a lockfile plan records its refusals under. */
 export const PLAN_REFUSAL_FILENAME = "-/plan";
+/**
+ * The `filename` of a refusal recorded only from an index listing: the
+ * registry answered a metadata request whose kept versions have no file the
+ * client may download (a PyPI project published only as an sdist, or whose
+ * every wheel is too new). The installer may only have looked at the name
+ * (a resolver exploring candidates, a dependency under a marker that does not
+ * apply), so such a refusal is weaker evidence than a refused download.
+ *
+ * The rule, the same for every ecosystem: a listing-only refusal is cleared
+ * like any refusal of a whole name, by any version of that name served after
+ * it in the same run (summarizeRegistryFetches). One left standing (nothing
+ * of that name was served) is marked `listingOnly`. It is reported to the
+ * agent (`wardby-packages`, GET /registry/-/refusals) and in get_run, and:
+ * - a coding sub-run failed: it counts toward ⛔ "Blocked by the package
+ *   registry" and Slack `run_blocked` like any refusal (blockingRefusals in
+ *   core/host-status.ts);
+ * - the run made no changes (and none failed): it is a ⚠️ line on the status,
+ *   never ⛔ or `run_blocked` (a package whose only release has nothing but
+ *   too-new wheels can be why);
+ * - a pull request resulted: it adds nothing, neither to the description's
+ *   install warning and package section nor to the status (warningRefusals).
+ */
+export const LISTING_REFUSAL_FILENAME = "-/listing";
+/** The refusals a pull request description or a not-blocked status warns
+ *  about: all but listing-only ones (see LISTING_REFUSAL_FILENAME). */
+export function warningRefusals(refusals) {
+    return refusals.filter((refusal) => refusal.listingOnly !== true);
+}
 /** Distinct refusals lockfile plans recorded (ecosystem + name + version +
  *  reason), however often the lockfile was planned. */
 export function countPlanRefusals(rows) {
@@ -11,21 +47,92 @@ export function countPlanRefusals(rows) {
     }
     return keys.size;
 }
+/** A served row's `reason` when serving it waived blocking advisories the
+ *  run's packagePolicy.acceptedAdvisories lists: this prefix, then the
+ *  waived advisory ids joined by ", ". */
+export const ACCEPTED_ADVISORIES_PREFIX = "accepted advisories: ";
+/** The served-row reason recording these waived advisory ids, or undefined
+ *  when none were waived (the row then has no reason, as before). */
+export function acceptedAdvisoriesReason(ids) {
+    return ids.length > 0 ? `${ACCEPTED_ADVISORIES_PREFIX}${ids.join(", ")}` : undefined;
+}
+/** The waived advisory ids a served row's reason records (empty for any
+ *  other reason, or none). */
+export function parseAcceptedAdvisories(reason) {
+    if (!reason?.startsWith(ACCEPTED_ADVISORIES_PREFIX))
+        return [];
+    return reason
+        .slice(ACCEPTED_ADVISORIES_PREFIX.length)
+        .split(",")
+        .map((id) => id.trim())
+        .filter((id) => ACCEPTED_ADVISORY_ID.test(id));
+}
+/**
+ * Rows must be in the order they were recorded (createdAt ascending): a
+ * refusal followed by a served row for the same package in the same run
+ * (`runId`; rows without one count as one run) no longer counts, since that
+ * run's install went on to get it (npm retrying a temporary
+ * `wardby_upstream_error`, an audit that was briefly unavailable). A package
+ * served to a sibling sub-run never clears another run's refusal. A refusal
+ * of one version is cleared only by that version being served; a refusal of
+ * the whole name (no version) by any version of it. A refusal recorded after
+ * the package was served still counts. Cleared refusals are left out of every
+ * surface (get_run, the PR warning, the status comments, Slack), because each
+ * of them tells the user the install did not finish, which is then untrue.
+ *
+ * Known limits: order is by record time, and a served row is recorded when
+ * its download finishes (no start time is stored), so a download that started
+ * before a concurrent refusal of the same version in the same run, and
+ * finished after it, clears it; rows in the same millisecond have no
+ * tiebreaker. Matching is per version, not per file, so serving any file of
+ * a PyPI release clears a refused file of that release (another platform's
+ * too-new wheel).
+ */
 export function summarizeRegistryFetches(rows) {
     const packages = new Map();
+    // Each refusal with the run + version pairs it still stands for (version "" = the whole name).
     const refusals = new Map();
     for (const row of rows) {
         if (row.outcome === "served" && row.version) {
             const key = `${row.ecosystem}\0${row.name}\0${row.version}`;
-            if (!packages.has(key))
-                packages.set(key, { ecosystem: row.ecosystem, name: row.name, version: row.version, size: row.sizeBytes });
+            let summary = packages.get(key);
+            if (!summary) {
+                summary = { ecosystem: row.ecosystem, name: row.name, version: row.version, size: row.sizeBytes };
+                packages.set(key, summary);
+            }
+            // Every file of the version (a retry, a wheel and its metadata) may
+            // record the waiver; the package lists each advisory once.
+            const accepted = parseAcceptedAdvisories(row.reason);
+            if (accepted.length > 0)
+                summary.acceptedAdvisories = [...new Set([...(summary.acceptedAdvisories ?? []), ...accepted])];
+            for (const [refusalKey, refusal] of refusals) {
+                if (refusal.summary.ecosystem !== row.ecosystem || refusal.summary.name !== row.name)
+                    continue;
+                refusal.versions.delete(`${row.runId ?? ""}\0`);
+                refusal.versions.delete(`${row.runId ?? ""}\0${row.version}`);
+                if (refusal.versions.size === 0)
+                    refusals.delete(refusalKey);
+            }
         }
         else if (row.outcome === "refused") {
             const reason = row.reason ?? "refused";
             const key = `${row.ecosystem}\0${row.name}\0${reason}`;
-            if (!refusals.has(key))
-                refusals.set(key, { ecosystem: row.ecosystem, name: row.name, reason });
+            let refusal = refusals.get(key);
+            if (!refusal) {
+                const hint = refusalHint(reason);
+                refusal = {
+                    summary: { ecosystem: row.ecosystem, name: row.name, reason, ...(hint ? { hint } : {}) },
+                    versions: new Set(),
+                    listing: true,
+                };
+                refusals.set(key, refusal);
+            }
+            refusal.versions.add(`${row.runId ?? ""}\0${row.version ?? ""}`);
+            refusal.listing &&= row.filename === LISTING_REFUSAL_FILENAME;
         }
     }
-    return { packages: [...packages.values()], packageRefusals: [...refusals.values()] };
+    return {
+        packages: [...packages.values()],
+        packageRefusals: [...refusals.values()].map(({ summary, listing }) => listing ? { ...summary, listingOnly: true } : summary),
+    };
 }