@event4u/agent-config 17.2.1 → 17.4.0

package/src/scripts/_lib/sigstore_provenance.ts

@@ -0,0 +1,177 @@
+/**
+ * Verify a release's two attestations against pinned sigstore trust material,
+ * and bind both to the exact tarball bytes that will be installed.
+ *
+ * WHY THIS REPLACES THE CERTIFICATE-BOUND CHECK. `provenance_verify.ts` checked
+ * the DSSE signature against the certificate a bundle carries and that
+ * certificate's SAN — and nothing about who issued it, so anyone who could
+ * serve the registry answer could mint a self-signed certificate with the
+ * expected SAN and pass. Pinned roots close that; a root fetched at run time
+ * would let the same attacker choose what the bundle is checked against.
+ *
+ * WHAT IS VERIFIED, both attestations required:
+ * - the SLSA provenance bundle: Fulcio chain to the pinned root, the signing
+ *   certificate's validity at the time the transparency log recorded it, a
+ *   Rekor entry and an SCT checked against the pinned logs, the DSSE signature,
+ *   and an identity policy — issuer `token.actions.githubusercontent.com` and a
+ *   SAN that is exactly this repository's `publish-npm.yml` at the tag of the
+ *   version being installed;
+ * - the npm publish attestation: its signature against npm's pinned
+ *   `npm:attestations` keys, and its Rekor entry — a second trust domain,
+ *   verified separately;
+ * - in both payloads, exactly one subject naming this package at this version,
+ *   whose sha512 equals the sha512 of the bytes about to be installed.
+ *
+ * WHAT IT NEVER DOES: fetch trust material (the files are read from the
+ * installed package and their digests checked against the recorded ones), fall
+ * back to the old check or to `npm audit signatures`, or pass anything it could
+ * not verify. Every failure is a reason string, because the caller prints it.
+ *
+ * The sigstore modules are imported lazily: this runs on the unattended upgrade
+ * path only, and nothing else should pay for loading them.
+ */
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { resolvePackageRoot } from './package_root.js';
+import { EXPECTED_REPOSITORY, EXPECTED_WORKFLOW_REF, payload_names_publish } from './provenance_verify.js';
+
+export const SLSA_PROVENANCE_V1 = 'https://slsa.dev/provenance/v1';
+export const NPM_PUBLISH_V01 = 'https://github.com/npm/attestation/tree/main/specs/publish/v0.1';
+export const GITHUB_OIDC_ISSUER = 'https://token.actions.githubusercontent.com';
+export const PACKAGE_PURL_BASE = 'pkg:npm/%40event4u/agent-config';
+
+/** Why verification refused, or `null` when everything held. */
+export type ProvenanceVerdict = string | null;
+
+function asRecord(v: unknown): Record<string, unknown> | null {
+    return v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
+}
+
+function escapeRegExp(s: string): string {
+    return s.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+}
+
+/**
+ * The only SAN accepted: this repository's publish workflow at the release tag
+ * of exactly the version being installed. Anchored at both ends — the library
+ * treats the policy as a pattern, and an unanchored one would accept any SAN
+ * that merely contains it.
+ */
+export function expectedSan(version: string): RegExp {
+    return new RegExp(`^${escapeRegExp(`${EXPECTED_REPOSITORY}/${EXPECTED_WORKFLOW_REF}@refs/tags/${version}`)}$`);
+}
+
+export interface TrustFiles {
+    readonly trustedRoot: unknown;
+    readonly npmKeys: unknown;
+}
+
+/**
+ * Read the pinned trust material and refuse when a file's digest differs from
+ * the recorded one — a release can only be checked against the material it
+ * shipped with, as it shipped.
+ */
+export function readTrustFiles(packageRoot: string = resolvePackageRoot(import.meta.url)): TrustFiles | string {
+    const dir = path.join(packageRoot, 'src', 'config', 'sigstore');
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'trust-material.json'), 'utf-8')) as {
+            files?: Record<string, string>;
+        };
+        const read = (name: string): unknown => {
+            const bytes = fs.readFileSync(path.join(dir, name));
+            const want = manifest.files?.[name];
+            const got = createHash('sha256').update(bytes).digest('hex');
+            if (want !== got) throw new Error(`${name} has sha256 ${got}, the recorded one is ${String(want)}`);
+            return JSON.parse(bytes.toString('utf-8')) as unknown;
+        };
+        return { trustedRoot: read('trusted_root.json'), npmKeys: read('npm_keys.json') };
+    } catch (err) {
+        return `the pinned sigstore trust material is unusable: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}
+
+/** Exactly one subject, naming this package at this version, with this sha512. */
+function subjectMatches(payload: Record<string, unknown> | null, version: string, sha512Hex: string): string | null {
+    const subjects = payload?.['subject'];
+    if (!Array.isArray(subjects) || subjects.length !== 1) return 'it does not name exactly one subject';
+    const subject = asRecord(subjects[0]);
+    if (subject?.['name'] !== `${PACKAGE_PURL_BASE}@${version}`) return `its subject is ${String(subject?.['name'])}, not ${version}`;
+    const digest = asRecord(subject['digest'])?.['sha512'];
+    if (typeof digest !== 'string' || digest.toLowerCase() !== sha512Hex.toLowerCase()) {
+        return 'its subject digest does not match the tarball about to be installed';
+    }
+    return null;
+}
+
+export interface ReleaseToVerify {
+    readonly version: string;
+    /** sha512 of the exact tarball bytes that will be installed, lower-case hex. */
+    readonly tarballSha512Hex: string;
+    /** The registry's attestation document for this version. */
+    readonly attestations: unknown;
+}
+
+export async function verify_release_provenance(
+    release: ReleaseToVerify,
+    trust: TrustFiles | string = readTrustFiles(),
+): Promise<ProvenanceVerdict> {
+    if (typeof trust === 'string') return trust;
+    const list = asRecord(release.attestations)?.['attestations'];
+    if (!Array.isArray(list)) return 'the attestation document carries no attestations';
+    const byType = new Map<string, unknown>();
+    for (const entry of list) {
+        const type = asRecord(entry)?.['predicateType'];
+        if (typeof type === 'string' && !byType.has(type)) byType.set(type, asRecord(entry)?.['bundle']);
+    }
+    for (const type of [SLSA_PROVENANCE_V1, NPM_PUBLISH_V01]) {
+        if (!byType.has(type)) return `the release carries no ${type} attestation`;
+    }
+
+    const { Verifier, toSignedEntity, toTrustMaterial } = await import('@sigstore/verify');
+    const { bundleFromJSON } = await import('@sigstore/bundle');
+    const { PublicKey, TrustedRoot } = await import('@sigstore/protobuf-specs');
+
+    let material: ReturnType<typeof toTrustMaterial>;
+    try {
+        const keys: Record<string, ReturnType<typeof PublicKey.fromJSON>> = {};
+        const listed = asRecord(trust.npmKeys)?.['keys'];
+        for (const k of Array.isArray(listed) ? listed : []) {
+            const key = asRecord(k);
+            if (key?.['keyUsage'] === 'npm:attestations' && typeof key['keyId'] === 'string') {
+                keys[key['keyId']] = PublicKey.fromJSON(key['publicKey']);
+            }
+        }
+        material = toTrustMaterial(TrustedRoot.fromJSON(trust.trustedRoot), keys);
+    } catch (err) {
+        return `the pinned sigstore trust material could not be loaded: ${err instanceof Error ? err.message : String(err)}`;
+    }
+
+    for (const type of [SLSA_PROVENANCE_V1, NPM_PUBLISH_V01]) {
+        let payload: Record<string, unknown> | null;
+        try {
+            const bundle = bundleFromJSON(byType.get(type));
+            const verifier = new Verifier(material, { tlogThreshold: 1, ctlogThreshold: 1, timestampThreshold: 1 });
+            const policy =
+                type === SLSA_PROVENANCE_V1
+                    ? { subjectAlternativeName: expectedSan(release.version), extensions: { issuer: GITHUB_OIDC_ISSUER } }
+                    : undefined;
+            verifier.verify(toSignedEntity(bundle), policy);
+            if (bundle.content.$case !== 'dsseEnvelope') return `the ${type} attestation is not a DSSE envelope`;
+            payload = asRecord(JSON.parse(bundle.content.dsseEnvelope.payload.toString('utf-8')));
+        } catch (err) {
+            const code = asRecord(err)?.['code'];
+            return `the ${type} attestation does not verify${typeof code === 'string' ? ` (${code})` : ''}: ${
+                err instanceof Error ? err.message : String(err)
+            }`;
+        }
+        if (payload?.['predicateType'] !== type) return `the ${type} attestation's statement names another predicate type`;
+        const subject = subjectMatches(payload, release.version, release.tarballSha512Hex);
+        if (subject !== null) return `the ${type} attestation is not for this tarball: ${subject}`;
+        if (type === SLSA_PROVENANCE_V1 && !payload_names_publish(payload)) {
+            return `the signed provenance does not name ${EXPECTED_WORKFLOW_REF} in ${EXPECTED_REPOSITORY}`;
+        }
+    }
+    return null;
+}

package/src/scripts/_lib/source_id.ts

@@ -0,0 +1,48 @@
+/**
+ * Stable, keyed source ids — `src_` plus 10 hex of an HMAC over the canonical identity.
+ *
+ * `ENC1` tokens are salted per call, so two tokens for one source never compare
+ * equal; a round-scoped `S1…` code is renumbered every round. Neither can key a
+ * ledger. This id can: it is stable across rounds and URL spellings, and keyed
+ * with `secrets.link_encryption_key`, so nobody without the key can confirm a
+ * guessed source by hashing its URL. Without a key there is no id — callers
+ * refuse rather than mint an unkeyed one.
+ */
+
+import * as crypto from 'node:crypto';
+
+import { canonicalize } from '../harvest_reference_tokens.js';
+
+export const SOURCE_ID_PREFIX = 'src_';
+export const SOURCE_ID_RE = /^src_[0-9a-f]{10}$/;
+// Domain-separates this HMAC from any other use of the same key.
+const ID_CONTEXT = 'agent-config/source-id/v1\0';
+
+/**
+ * Repository URLs collapse through `canonicalize`; anything else (an article,
+ * a video, a paper) keeps host, path and query with scheme, credentials,
+ * fragment and a trailing slash dropped. A string that is not a URL is used
+ * trimmed, as written — an opaque reference names itself.
+ */
+export function canonicalSourceIdentity(raw: string): string {
+    const repo = canonicalize(raw);
+    if (repo !== null) return repo;
+    const s = raw.trim();
+    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(s)) return s;
+    let u: URL;
+    try {
+        u = new URL(s);
+    } catch {
+        return s;
+    }
+    const host = u.hostname.toLowerCase().replace(/^www\./, '');
+    const port = u.port === '' ? '' : `:${u.port}`;
+    const pathname = u.pathname.replace(/\/+$/, '');
+    return `${host}${port}${pathname}${u.search}`;
+}
+
+export function sourceId(identity: string, key: string): string {
+    if (!key) throw new Error('no link_encryption_key — a source id is never minted without the key');
+    const mac = crypto.createHmac('sha256', key).update(ID_CONTEXT + canonicalSourceIdentity(identity)).digest('hex');
+    return SOURCE_ID_PREFIX + mac.slice(0, 10);
+}

package/src/scripts/_lib/source_shape.ts

@@ -155,6 +155,10 @@ const ALLOWED_OWNERS: readonly string[] = [
     // looked; this is the answer. Fixing them here rather than by widening the
     // dedup rule is what keeps that rule strict.
     'someone', 'o',
+    // `someone-else/<repo>` is the wrong-repository fixture of the provenance
+    // tests; a committed council prompt quoting those tests verbatim was the
+    // measured false positive (2026-10-24). Same shape as the two above.
+    'someone-else',
     // Vendors whose tools this suite integrates or recommends (rule carve-out).
     'anthropics', 'anthropic', 'microsoft', 'github', 'modelcontextprotocol',
     'cloudflare', 'openai', 'nodejs', 'vitest-dev', 'vercel', 'tailwindlabs',

package/src/scripts/_lib/unattended_gates.ts

@@ -30,9 +30,12 @@ export interface RegistryCandidate {
      * workflow produced the document. Tying it to this package's publish
      * workflow needs the bundle itself, which the packument only points at —
      * so the pointer travels with the candidate and the caller fetches it
-     * (`provenance_verify.provenance_matches_publish`).
+     * (`sigstore_provenance.verify_release_provenance`).
      */
     readonly attestationsUrl: string | null;
+    /** Where npm serves this version's tarball, and the integrity it records for it. */
+    readonly tarballUrl: string | null;
+    readonly integrity: string | null;
 }
 
 function asRecord(v: unknown): Record<string, unknown> | null {
@@ -58,6 +61,8 @@ export function read_candidate(packument: unknown): RegistryCandidate | null {
         provenance: typeof predicate === 'string' && predicate.startsWith('https://slsa.dev/provenance/'),
         impactMap: asRecord(manifest['agentConfig'])?.['impact'] ?? null,
         attestationsUrl: typeof attestations?.['url'] === 'string' ? (attestations['url'] as string) : null,
+        tarballUrl: typeof asRecord(manifest['dist'])?.['tarball'] === 'string' ? (asRecord(manifest['dist'])?.['tarball'] as string) : null,
+        integrity: typeof asRecord(manifest['dist'])?.['integrity'] === 'string' ? (asRecord(manifest['dist'])?.['integrity'] as string) : null,
     };
 }
 

package/src/scripts/adoption_status.ts

@@ -22,7 +22,7 @@
  *
  * CLI:
  *
- *   ./scripts-run src/scripts/adoption_status [--json] [--branch main] [--check-upstream]
+ *   ./scripts-run src/scripts/adoption_status [--json] [--branch main] [--check-upstream] [--fail-on-action]
  *
  * `--check-upstream` reads each ledger row's upstream (`gh pr view` for a pull
  * request, one `curl` for a listing page or registry query) and appends what it
@@ -30,10 +30,19 @@
  * report exactly as before, and stderr names that mode plus every row whose
  * `Last read` date is missing or older than the sheet's re-read threshold.
  *
+ * With `--check-upstream`, a row whose sheet and upstream disagree in a way that
+ * needs a person also carries an action (`sheet-behind`, `needs-response`,
+ * `listing-lost`, `listing-stale`) next to its unchanged verdict, and the report
+ * names the next act. A submission is done when its entry is live, not when it
+ * was sent, so `--fail-on-action` turns any action into a non-zero exit for the
+ * daily watcher. Without `--check-upstream` there is nothing to judge and the
+ * flag is reported on stderr and ignored.
+ *
  * Exit codes:
  *
  *   0 — printed successfully (status itself does not gate the exit).
  *   1 — IO error reading the registry-submissions sheet.
+ *   2 — `--check-upstream --fail-on-action` and at least one row needs an action.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -243,25 +252,29 @@ interface Args {
     json: boolean;
     branch: string;
     checkUpstream: boolean;
+    failOnAction: boolean;
 }
 
 export function parse_args(argv: string[]): Args {
     let json = false;
     let branch = 'main';
     let checkUpstream = false;
+    let failOnAction = false;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === '--json') {
             json = true;
         } else if (a === '--check-upstream') {
             checkUpstream = true;
+        } else if (a === '--fail-on-action') {
+            failOnAction = true;
         } else if (a === '--branch') {
             branch = argv[++i] ?? '';
         } else if (a !== undefined && a.startsWith('--branch=')) {
             branch = a.slice('--branch='.length);
         }
     }
-    return { json, branch, checkUpstream };
+    return { json, branch, checkUpstream, failOnAction };
 }
 
 export function main(argv: string[] = process.argv.slice(2)): number {
@@ -293,10 +306,21 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         for (const u of unread) {
             process.stderr.write(`  row ${u.id} ${u.registry}: ${u.label}\n`);
         }
+        if (args.failOnAction) {
+            process.stderr.write(
+                '--fail-on-action ignored: actions are judged only with --check-upstream\n',
+            );
+        }
         return 0;
     }
 
-    const verdicts = judge_upstream(rows, live_upstream_reader, today);
+    const verdicts = judge_upstream(
+        rows,
+        live_upstream_reader,
+        today,
+        _releasedServer(),
+        parse_reread_threshold(registryText),
+    );
     if (args.json) {
         const base = JSON.parse(render_json(registryCounts, reports, ci, args.branch)) as Record<
             string,
@@ -308,7 +332,32 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         process.stdout.write(render_text(registryCounts, reports, ci, args.branch) + '\n');
         process.stdout.write(render_upstream_text(verdicts, unread) + '\n');
     }
-    return 0;
+    const code = upstream_exit_code(verdicts, args.failOnAction);
+    if (code !== 0) {
+        // On a runner the `::error::` prefix turns each line into an annotation
+        // naming the row, so the red job says what to do without opening the log.
+        const prefix = process.env.GITHUB_ACTIONS === 'true' ? '::error title=adoption_status::' : 'action: ';
+        for (const line of action_lines(verdicts)) {
+            process.stderr.write(prefix + line + '\n');
+        }
+    }
+    return code;
+}
+
+/** `name` and `version` the registry should carry, from package.json. */
+function _releasedServer(): ReleasedServer | undefined {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf-8')) as {
+            mcpName?: unknown;
+            version?: unknown;
+        };
+        if (typeof pkg.mcpName === 'string' && typeof pkg.version === 'string') {
+            return { name: pkg.mcpName, version: pkg.version };
+        }
+    } catch {
+        // Without a readable package.json there is nothing to compare against.
+    }
+    return undefined;
 }
 
 // --- upstream reading --------------------------------------------------------
@@ -325,7 +374,15 @@ export interface LedgerRow {
 }
 
 export type UpstreamReading =
-    | { ok: true; state: 'open' | 'closed' | 'merged' | 'listed' | 'not-listed'; at?: string }
+    | {
+          ok: true;
+          state: 'open' | 'closed' | 'merged' | 'listed' | 'not-listed';
+          at?: string;
+          /** `gh pr view` reviewDecision, e.g. `CHANGES_REQUESTED`; pull requests only. */
+          reviewDecision?: string;
+          /** Server name → the version the registry marks latest; registry queries only. */
+          latestVersions?: Record<string, string>;
+      }
     | { ok: false; reason: string };
 
 export type UpstreamReader = (row: LedgerRow) => UpstreamReading;
@@ -340,11 +397,25 @@ export type UpstreamVerdict =
     | 'unreachable'
     | 'no-upstream';
 
+/**
+ * Reported next to the verdict, never instead of it: the verdict says what the
+ * upstream reads, the action says the sheet and that reading disagree in a way a
+ * person has to resolve.
+ */
+export type ActionVerdict = 'sheet-behind' | 'needs-response' | 'listing-lost' | 'listing-stale' | 'read-overdue';
+
 export interface RowVerdict {
     id: string;
     registry: string;
     verdict: UpstreamVerdict;
     detail: string;
+    action?: ActionVerdict;
+    next?: string;
+}
+
+export interface ReleasedServer {
+    name: string;
+    version: string;
 }
 
 export interface UnreadFinding {
@@ -451,6 +522,8 @@ export function judge_upstream(
     rows: LedgerRow[],
     reader: UpstreamReader,
     today: string,
+    released?: ReleasedServer,
+    thresholdDays: number = DEFAULT_REREAD_THRESHOLD_DAYS,
 ): RowVerdict[] {
     return rows.map((row): RowVerdict => {
         const base = { id: row.id, registry: row.registry };
@@ -459,27 +532,116 @@ export function judge_upstream(
         }
         const r = reader(row);
         if (!r.ok) {
-            return { ...base, verdict: 'unreachable', detail: r.reason };
-        }
-        switch (r.state) {
-            case 'closed':
-                return { ...base, verdict: 'answered-closed', detail: `closed ${r.at ?? 'date unknown'}` };
-            case 'merged':
-                return { ...base, verdict: 'answered-merged', detail: `merged ${r.at ?? 'date unknown'}` };
-            case 'listed':
-            case 'not-listed':
-                return { ...base, verdict: r.state, detail: row.ref };
-            case 'open': {
-                const age = row.date === '' ? null : _daysBetween(row.date, today);
-                if (row.status === 'submitted' && age !== null && age >= STALLED_AFTER_DAYS) {
-                    return { ...base, verdict: 'stalled', detail: `open ${age} days, no answer` };
-                }
-                return { ...base, verdict: 'open', detail: age === null ? 'open' : `open ${age} days` };
+            const out = { ...base, verdict: 'unreachable' as const, detail: r.reason };
+            // One outage never reds the watcher; a listing nobody has been able to read
+            // for longer than the sheet's own threshold does, or it could vanish unseen.
+            const age = row.lastRead === '' ? null : _daysBetween(row.lastRead, today);
+            const live = row.status === 'accepted' || row.status === 'submitted';
+            if (live && (age === null || age > thresholdDays)) {
+                return {
+                    ...out,
+                    action: 'read-overdue',
+                    next: `read the upstream another way (a headless browser) and set Last read; unread ${age === null ? 'ever' : `for ${age} days`}`,
+                };
             }
+            return out;
         }
+        const out = { ...base, ..._verdictOf(row, r, today) };
+        const action = _actionFor(row, r, released);
+        // Spread only when present: the JSON writer prints an undefined value as `null`.
+        return action === null ? out : { ...out, ...action };
     });
 }
 
+function _verdictOf(
+    row: LedgerRow,
+    r: Extract<UpstreamReading, { ok: true }>,
+    today: string,
+): { verdict: UpstreamVerdict; detail: string } {
+    switch (r.state) {
+        case 'closed':
+            return { verdict: 'answered-closed', detail: `closed ${r.at ?? 'date unknown'}` };
+        case 'merged':
+            return { verdict: 'answered-merged', detail: `merged ${r.at ?? 'date unknown'}` };
+        case 'listed':
+        case 'not-listed':
+            return { verdict: r.state, detail: row.ref };
+        case 'open': {
+            const age = row.date === '' ? null : _daysBetween(row.date, today);
+            if (row.status === 'submitted' && age !== null && age >= STALLED_AFTER_DAYS) {
+                return { verdict: 'stalled', detail: `open ${age} days, no answer` };
+            }
+            return { verdict: 'open', detail: age === null ? 'open' : `open ${age} days` };
+        }
+    }
+}
+
+/**
+ * The cases where the sheet and the live upstream disagree in a way that needs a
+ * person. `rejected` and `stalled` rows are left alone: the sheet already says
+ * the attempt ended, and an unreadable upstream is never an action, so a network
+ * outage cannot red the watcher.
+ */
+function _actionFor(
+    row: LedgerRow,
+    r: Extract<UpstreamReading, { ok: true }>,
+    released: ReleasedServer | undefined,
+): { action: ActionVerdict; next: string } | null {
+    const awaiting = row.status === 'submitted' || row.status === 'pending';
+    if (awaiting && (r.state === 'closed' || r.state === 'merged')) {
+        return {
+            action: 'sheet-behind',
+            next: `update the ledger row: the upstream ${r.state} ${r.at ?? 'on an unknown date'} while the sheet says ${row.status}`,
+        };
+    }
+    // Row 4's path after its first CI publish: the entry went live, the sheet still waits.
+    if (awaiting && r.state === 'listed') {
+        return {
+            action: 'sheet-behind',
+            next: `update the ledger row: the listing reads listed while the sheet says ${row.status}`,
+        };
+    }
+    if (r.state === 'open' && r.reviewDecision === 'CHANGES_REQUESTED') {
+        return { action: 'needs-response', next: `answer the review on ${row.ref}` };
+    }
+    if (row.status === 'accepted' && r.state === 'not-listed') {
+        return { action: 'listing-lost', next: `re-check or re-submit the listing at ${row.ref}` };
+    }
+    if (
+        row.status === 'accepted' &&
+        row.kind === 'registry-query' &&
+        r.state === 'listed' &&
+        released !== undefined &&
+        r.latestVersions !== undefined
+    ) {
+        const live = r.latestVersions[released.name];
+        if (live === undefined) {
+            return {
+                action: 'listing-lost',
+                next: `re-check or re-submit the listing: the registry answer carries no ${released.name}`,
+            };
+        }
+        if (live !== released.version) {
+            return {
+                action: 'listing-stale',
+                next: `publish ${released.version} to the registry: it carries ${live} for ${released.name}`,
+            };
+        }
+    }
+    return null;
+}
+
+/** The rows `--fail-on-action` reds on, one line each: row, action, next act. */
+export function action_lines(verdicts: RowVerdict[]): string[] {
+    return verdicts
+        .filter((v) => v.action !== undefined)
+        .map((v) => `row ${v.id} ${v.action} (${v.registry}) — ${v.next ?? ''}`);
+}
+
+export function upstream_exit_code(verdicts: RowVerdict[], failOnAction: boolean): number {
+    return failOnAction && verdicts.some((v) => v.action !== undefined) ? 2 : 0;
+}
+
 export function upstream_mode_note(checked: boolean): string {
     return checked
         ? 'upstream: read live (--check-upstream)'
@@ -508,6 +670,14 @@ export function render_upstream_text(verdicts: RowVerdict[], unread: UnreadFindi
     for (const u of unread) {
         lines.push(`  row ${u.id.padEnd(3)} ${u.label} ${u.registry}`);
     }
+    const actions = action_lines(verdicts);
+    if (actions.length > 0) {
+        lines.push('');
+        lines.push('Actions needed (a submission is done only once it is live):');
+        for (const a of actions) {
+            lines.push(`  ${a}`);
+        }
+    }
     return lines.join('\n');
 }
 
@@ -521,14 +691,14 @@ function _readPullRequest(ref: string): UpstreamReading {
     }
     const proc = spawnSync(
         'gh',
-        ['pr', 'view', m[2] as string, '--repo', m[1] as string, '--json', 'state,closedAt,mergedAt'],
+        ['pr', 'view', m[2] as string, '--repo', m[1] as string, '--json', 'state,closedAt,mergedAt,reviewDecision'],
         { encoding: 'utf8', timeout: 20_000 },
     );
     if (proc.status !== 0) {
         const snip = sanitize_text(_pyStrip(proc.stderr ?? '')).slice(0, 80);
         return { ok: false, reason: `gh exit=${proc.status}: ${snip}` };
     }
-    let d: { state?: string; closedAt?: string; mergedAt?: string };
+    let d: { state?: string; closedAt?: string; mergedAt?: string; reviewDecision?: string };
     try {
         d = JSON.parse(proc.stdout) as typeof d;
     } catch {
@@ -536,7 +706,10 @@ function _readPullRequest(ref: string): UpstreamReading {
     }
     if (d.state === 'MERGED') return { ok: true, state: 'merged', at: sanitize_text(d.mergedAt ?? '').slice(0, 10) };
     if (d.state === 'CLOSED') return { ok: true, state: 'closed', at: sanitize_text(d.closedAt ?? '').slice(0, 10) };
-    if (d.state === 'OPEN') return { ok: true, state: 'open' };
+    if (d.state === 'OPEN') {
+        const review = sanitize_text(d.reviewDecision ?? '').slice(0, 40);
+        return review === '' ? { ok: true, state: 'open' } : { ok: true, state: 'open', reviewDecision: review };
+    }
     return { ok: false, reason: `unknown pull-request state ${sanitize_text(String(d.state)).slice(0, 40)}` };
 }
 
@@ -574,9 +747,21 @@ export function read_url(
         if (code === '404') return { ok: true, state: 'not-listed' };
         return { ok: false, reason: `HTTP ${code} from ${ref}` };
     }
-    let body: { metadata?: { count?: unknown } };
+    return read_registry_answer(out.slice(0, cut), ref);
+}
+
+const _REGISTRY_META_KEY = 'io.modelcontextprotocol.registry/official';
+
+/**
+ * Shape read live from `GET /v0/servers?search=` on 2026-10-24:
+ * `{servers: [{server: {name, version}, _meta: {"<key>": {isLatest}}}], metadata: {count}}`.
+ * A search returns every published version, so only the one flagged `isLatest`
+ * names what a client installs.
+ */
+export function read_registry_answer(text: string, ref: string): UpstreamReading {
+    let body: { metadata?: { count?: unknown }; servers?: unknown };
     try {
-        body = JSON.parse(out.slice(0, cut)) as typeof body;
+        body = JSON.parse(text) as typeof body;
     } catch {
         return { ok: false, reason: `registry answer from ${ref} not parseable as JSON` };
     }
@@ -584,7 +769,26 @@ export function read_url(
     if (typeof n !== 'number') {
         return { ok: false, reason: 'registry answer has no metadata.count' };
     }
-    return { ok: true, state: n > 0 ? 'listed' : 'not-listed' };
+    if (n === 0) {
+        return { ok: true, state: 'not-listed' };
+    }
+    const latestVersions: Record<string, string> = {};
+    let flagged = false;
+    for (const entry of Array.isArray(body.servers) ? body.servers : []) {
+        const e = entry as {
+            server?: { name?: unknown; version?: unknown };
+            _meta?: Record<string, { isLatest?: unknown } | undefined>;
+        };
+        const name = e.server?.name;
+        const version = e.server?.version;
+        if (typeof name !== 'string' || typeof version !== 'string') continue;
+        if (e._meta?.[_REGISTRY_META_KEY]?.isLatest !== true) continue;
+        flagged = true;
+        latestVersions[sanitize_text(name).slice(0, 200)] = sanitize_text(version).slice(0, 40);
+    }
+    // No `isLatest` flag anywhere means the answer is not the shape read above;
+    // comparing against an empty map would report a live listing as lost.
+    return flagged ? { ok: true, state: 'listed', latestVersions } : { ok: true, state: 'listed' };
 }
 
 /** Reads the real upstream: `gh` for a pull request, `curl` otherwise. */