@gjsify/cli 0.59.1 → 0.60.0

package/lib/commands/publish.d.ts

@@ -2,6 +2,8 @@ import type { Command } from '../types/index.js';
 import { type Diagnose404Result } from '../utils/publish-diagnose.js';
 import { type ReadbackResult } from '../utils/publish-readback.js';
 import { type WorkspacePin } from '../utils/publish-pins.js';
+import { type HoldReason } from '../utils/publish-hold.js';
+import { type Classification } from '../utils/publish-status.js';
 import { OtpProvider } from '../utils/npm-otp.js';
 interface PublishOptions {
     path?: string;
@@ -12,6 +14,9 @@ interface PublishOptions {
     'tolerate-untrusted-new'?: boolean;
     'verify-timeout'?: number;
     'verify-defer'?: boolean;
+    'hold-timeout'?: number;
+    'report-ledger'?: boolean;
+    ref?: string;
     provenance?: boolean;
     'dry-run'?: boolean;
     json?: boolean;
@@ -60,6 +65,11 @@ export interface PublishWorkspaceInput {
      * success, which is the pre-v0.46.0 behaviour and why this defaults on.
      */
     verifyBudgetMs?: number;
+    /**
+     * How long to wait for an intra-repo pin the registry does not serve before
+     * holding this package. Default {@link DEFAULT_HOLD_WAIT_MS}.
+     */
+    holdWaitMs?: number;
 }
 /** Discriminated result of {@link publishWorkspace}; the caller owns presentation. */
 export type PublishOutcome = {
@@ -101,6 +111,21 @@ export type PublishOutcome = {
     putUrl: string;
     payloadBytes: number;
     readback: ReadbackResult;
+    /** What the unserved version IS (validating / staged / blocked / …). */
+    classification: Classification;
+}
+/**
+ * The tarball was NOT sent, because an intra-repo pin in it names a version
+ * the registry does not serve — an accepted-but-"validating" upload, say.
+ * `ok` is the tolerance, as for `blocked-missing-dependency`.
+ */
+ | {
+    ok: false;
+    action: 'held-unpublished-dependency';
+    name: string;
+    version: string;
+    registry: string;
+    reasons: HoldReason[];
 } | {
     ok: true;
     action: 'republish-tolerated';

package/lib/commands/publish.js

@@ -50,6 +50,8 @@ import { getNpmTrustedToken, hasGithubOidcEnv, OidcExchangeError, OidcUnavailabl
 import { diagnose404, is404DiagnosticCandidate } from '../utils/publish-diagnose.js';
 import { DEFAULT_VERIFY_BUDGET_MS, formatUnconfirmedPublish, probePackageName, verifyPublishedVersion, } from '../utils/publish-readback.js';
 import { collectWorkspacePins, REQUIRED_BLOCK } from '../utils/publish-pins.js';
+import { appendLedger, DEFAULT_HOLD_WAIT_MS, findUnavailablePins, holdsPublish, readLedger, recordUnserved, renderLedgerSummary, summariseReasons, } from '../utils/publish-hold.js';
+import { describeClass, statusTokenFromEnv } from '../utils/publish-status.js';
 import { loadNpmrc } from '../utils/load-npmrc.js';
 import { OtpProvider, withOtpRetry, isOtpChallenge } from '../utils/npm-otp.js';
 import { promptLine } from '../utils/prompt.js';
@@ -90,6 +92,20 @@ export const publishCommand = {
         description: 'Report an unconfirmed read-back and exit 0 instead of 1. ONLY for a caller that re-checks the same set afterwards — `gjsify run npm:publish` passes it because `scripts/verify-published-closure.mjs` sweeps the whole roster at the end of release.yml. Everywhere else an unconfirmed publish must fail the job that made it.',
         type: 'boolean',
         default: false,
+    })
+        .option('hold-timeout', {
+        description: 'Seconds to wait for an intra-repo dependency pin whose exact version the registry does not serve (yet) before HOLDING this package instead of publishing it. A version npm accepted but never serves (status "validating") would make every dependent uninstallable; the write lag measured on v0.46.0 reaches 252s, hence the default. `0` probes once and holds without waiting. A hold exits 1, or 0 under `--verify-defer`.',
+        type: 'number',
+        default: DEFAULT_HOLD_WAIT_MS / 1000,
+    })
+        .option('report-ledger', {
+        description: 'Print the job-summary markdown for the publish ledger named by $GJSIFY_PUBLISH_LEDGER (versions npm accepted but does not serve, packages held because of them, the recovery command) and exit. Pair with `--ref <tag>`.',
+        type: 'boolean',
+        default: false,
+    })
+        .option('ref', {
+        description: 'With --report-ledger: the git ref to put in the printed recovery command.',
+        type: 'string',
     })
         .option('provenance', {
         description: "Pass-through flag — recorded in the payload but no signing happens (gjsify doesn't ship a sigstore signer yet).",
@@ -142,6 +158,17 @@ export const publishCommand = {
         const checkTrustedOnly = args['check-trusted'] === true;
         const trustedFlag = args.trusted;
         const verbose = Boolean(process.env.GJSIFY_PUBLISH_DEBUG);
+        if (args['report-ledger'] === true) {
+            const summary = renderLedgerSummary(readLedger(process.env.GJSIFY_PUBLISH_LEDGER), args.ref ?? '<tag>');
+            if (summary)
+                process.stdout.write(`${summary}\n`);
+            return;
+        }
+        const holdSeconds = args['hold-timeout'] ?? DEFAULT_HOLD_WAIT_MS / 1000;
+        if (!Number.isFinite(holdSeconds) || holdSeconds < 0) {
+            console.error(`gjsify publish: --hold-timeout must be a non-negative number of seconds, got ${JSON.stringify(args['hold-timeout'])}`);
+            return process.exit(2);
+        }
         if (provenance) {
             console.warn('gjsify publish: --provenance recorded but not signed (no sigstore integration yet).');
         }
@@ -250,6 +277,7 @@ export const publishCommand = {
             otpProvider,
             seedOtpFirst: otp !== undefined,
             verifyBudgetMs,
+            holdWaitMs: Math.round(holdSeconds * 1000),
         });
         reportPublishOutcome(outcome, args.json === true, deferUnconfirmed);
     },
@@ -355,6 +383,43 @@ export async function publishWorkspace(input) {
             };
         }
     }
+    // 5b. Do not PUT a tarball whose pin names a VERSION the registry does not
+    //     serve (v0.59.x: adwaita-fonts "Validating" while its dependents shipped).
+    //     Unlike 5 this waits, because a version is late for minutes after its own
+    //     2xx; see publish-hold.ts.
+    const ledgerPath = process.env.GJSIFY_PUBLISH_LEDGER;
+    if (pins.length > 0) {
+        const reasons = await findUnavailablePins({
+            registry: registryClean,
+            pins,
+            ledger: readLedger(ledgerPath),
+            ledgerPath,
+            authorization: headers['authorization'],
+            statusToken: statusTokenFromEnv(process.env),
+            waitBudgetMs: input.holdWaitMs ?? DEFAULT_HOLD_WAIT_MS,
+            log: verbose ? (m) => console.error(m) : undefined,
+        });
+        for (const r of reasons.filter((x) => !holdsPublish(x))) {
+            console.error(`gjsify publish: ${r.block}.${r.name}@${r.version} is not served (${r.detail}) — optional edge, publishing anyway`);
+        }
+        const holding = reasons.filter(holdsPublish);
+        if (holding.length > 0) {
+            appendLedger(ledgerPath, {
+                ev: 'held',
+                name: packed.name,
+                version: packed.version,
+                reasons: holding,
+            });
+            return {
+                ok: false,
+                action: 'held-unpublished-dependency',
+                name: packed.name,
+                version: packed.version,
+                registry: registryClean,
+                reasons: holding,
+            };
+        }
+    }
     // Trusted Publishing (OIDC) path — `--trusted` forces it, `undefined`
     // auto-detects from the GitHub OIDC env. Unused by `gjsify onboard` (local
     // token auth), preserved verbatim for `gjsify publish` in CI.
@@ -529,6 +594,14 @@ export async function publishWorkspace(input) {
                 putUrl: url,
                 payloadBytes: bodyStr.length,
                 readback,
+                classification: await recordUnserved({
+                    ledgerPath,
+                    registry: registryClean,
+                    name: packed.name,
+                    version: packed.version,
+                    verdict: readback.verdict,
+                    statusToken: statusTokenFromEnv(process.env),
+                }),
             };
         }
         return {
@@ -576,6 +649,14 @@ export async function publishWorkspace(input) {
                 putUrl: url,
                 payloadBytes: bodyStr.length,
                 readback,
+                classification: await recordUnserved({
+                    ledgerPath,
+                    registry: registryClean,
+                    name: packed.name,
+                    version: packed.version,
+                    verdict: readback.verdict,
+                    statusToken: statusTokenFromEnv(process.env),
+                }),
             };
         }
         return {
@@ -701,8 +782,31 @@ function reportPublishOutcome(outcome, asJson, deferUnconfirmed = false) {
                 warnUnverified(outcome.name, outcome.version, outcome.registry);
             return;
         }
+        case 'held-unpublished-dependency': {
+            const because = summariseReasons(outcome.reasons);
+            if (asJson) {
+                process.stdout.write(`${JSON.stringify({
+                    ok: false,
+                    action: 'held-unpublished-dependency',
+                    name: outcome.name,
+                    version: outcome.version,
+                    registry: outcome.registry,
+                    reasons: outcome.reasons,
+                    deferred: deferUnconfirmed,
+                }, null, 2)}\n`);
+            }
+            else {
+                process.stderr.write(`~ ${outcome.name}@${outcome.version} (HELD — not published: ${because})\n`);
+            }
+            if (process.env.GITHUB_ACTIONS) {
+                process.stderr.write(`::warning title=Package held::${outcome.name}@${outcome.version} was NOT published: ${because}\n`);
+            }
+            // The sweep defers like an unconfirmed publish: the closure job goes red
+            // on the missing package, and the job summary carries the recovery.
+            return deferUnconfirmed ? undefined : process.exit(1);
+        }
         case 'publish-unconfirmed': {
-            const message = formatUnconfirmedPublish(outcome);
+            const message = `${formatUnconfirmedPublish(outcome)}\n  state: ${describeClass(outcome.classification.cls)} — ${outcome.classification.detail}`;
             if (asJson) {
                 process.stdout.write(`${JSON.stringify({
                     ok: false,
@@ -720,6 +824,8 @@ function reportPublishOutcome(outcome, asJson, deferUnconfirmed = false) {
                     verdictDetail: outcome.readback.verdictDetail,
                     recordedAt: outcome.readback.recordedAt ?? null,
                     deferred: deferUnconfirmed,
+                    class: outcome.classification.cls,
+                    classDetail: outcome.classification.detail,
                 }, null, 2)}\n`);
             }
             else {
@@ -736,7 +842,7 @@ function reportPublishOutcome(outcome, asJson, deferUnconfirmed = false) {
                     const claimed = outcome.claim === 'already-published' ? 'was reported already published' : 'was accepted';
                     process.stderr.write(`::warning title=Publish unconfirmed::${outcome.name}@${outcome.version} ${claimed} ` +
                         `(HTTP ${outcome.putStatus}) but did not resolve on ${outcome.registry} within ` +
-                        `${(outcome.readback.elapsedMs / 1000).toFixed(1)}s [${outcome.readback.verdict}] — ` +
+                        `${(outcome.readback.elapsedMs / 1000).toFixed(1)}s [${outcome.readback.verdict}; ${describeClass(outcome.classification.cls)}] — ` +
                         'the release-closure job must confirm it\n');
                 }
                 return;

package/lib/utils/discover-showcases.js

@@ -7,6 +7,11 @@ import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 function manifestPath() {
+    // Test seam: e2e points this at a fixture catalog (a gjs-only workspace showcase),
+    // since the curated list no longer holds one.
+    const override = process.env.GJSIFY_SHOWCASES_MANIFEST;
+    if (override)
+        return override;
     const here = dirname(fileURLToPath(import.meta.url));
     // `showcases.json` sits at the CLI package root, but its depth below this
     // module depends on how the CLI was loaded: two levels from

package/lib/utils/publish-hold.d.ts

@@ -0,0 +1,89 @@
+import { type DependencyBlock, type WorkspacePin } from './publish-pins.js';
+import { classifyUnserved, type Classification, type UnservedClass } from './publish-status.js';
+/** Wait for a pin this long before holding. Covers the measured 252 s write lag (publish-readback.ts). */
+export declare const DEFAULT_HOLD_WAIT_MS = 300000;
+export interface HoldReason {
+    /** The dependency that is not installable. */
+    name: string;
+    version: string;
+    block: DependencyBlock;
+    /** `held` = the dependency was itself held in this run, so nothing of it was published. */
+    cls: UnservedClass | 'held';
+    detail: string;
+}
+export type LedgerEntry = 
+/** This run PUT the version, npm accepted it, and the packument does not serve it. */
+{
+    ev: 'unserved';
+    name: string;
+    version: string;
+    cls: UnservedClass;
+    detail: string;
+}
+/** This run did NOT publish the package, because of the listed dependencies. */
+ | {
+    ev: 'held';
+    name: string;
+    version: string;
+    reasons: HoldReason[];
+}
+/** A later probe found a version an earlier `unserved` entry recorded now served; it supersedes that entry. */
+ | {
+    ev: 'served';
+    name: string;
+    version: string;
+};
+export declare function appendLedger(path: string | undefined, entry: LedgerEntry): void;
+/** Tolerates a missing file (no entries yet) and skips unparseable lines rather than losing the rest. */
+export declare function readLedger(path: string | undefined): LedgerEntry[];
+/**
+ * The version a rewritten pin asks for, when the spec names exactly one:
+ * `0.59.1`, `^0.59.1`, `~0.59.1`. `undefined` for a range, tag or URL — those are
+ * not decidable against one version and the name-level guard covers them.
+ */
+export declare function pinVersion(spec: string): string | undefined;
+export interface FindUnavailablePinsInput {
+    registry: string;
+    pins: readonly WorkspacePin[];
+    ledger: readonly LedgerEntry[];
+    /** Where a re-probe that finds a ledger-`unserved` version served records it, so later dependents skip the probe. */
+    ledgerPath?: string;
+    /** Forwarded to the packument GETs, as the publish's own read-back does. */
+    authorization?: string;
+    statusToken?: string;
+    /** How long to wait for a pin that may merely be late. 0 = one probe, no waiting. */
+    waitBudgetMs: number;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    log?: (msg: string) => void;
+}
+/**
+ * Every pin whose exact version the registry does not serve (after waiting for
+ * one that may be late), with the reason. Empty = safe to publish.
+ *
+ * Three cheap exits come first, in order: the ledger already knows this version
+ * is unserved or held; one packument probe finds it served (nine in ten); the
+ * status endpoint says it can never be served. Only a pin that is none of those —
+ * possibly just late — pays the wait.
+ */
+export declare function findUnavailablePins(input: FindUnavailablePinsInput): Promise<HoldReason[]>;
+/** Only a `dependencies` edge holds a publish, as in the name-level guard; the rest are reported. */
+export declare const holdsPublish: (reason: HoldReason) => boolean;
+export declare function summariseReasons(reasons: readonly HoldReason[]): string;
+/** Classify a version THIS process PUT and could not read back, and write it to the ledger. */
+export declare function recordUnserved(input: {
+    ledgerPath: string | undefined;
+    registry: string;
+    name: string;
+    version: string;
+    verdict: Parameters<typeof classifyUnserved>[0];
+    statusToken?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<Classification>;
+/**
+ * The job-summary markdown for a ledger: what is unserved and why, what was held
+ * and why, and the exact command that publishes the held set once their
+ * dependencies are installable. `undefined` when nothing needs saying.
+ */
+export declare function renderLedgerSummary(entries: readonly LedgerEntry[], ref: string): string | undefined;

package/lib/utils/publish-hold.js

@@ -0,0 +1,213 @@
+// Do not publish a package whose dependency closure contains a version nobody can install.
+//
+// THE INCIDENT (v0.59.0 / v0.59.1). `@gjsify/adwaita-fonts@0.59.x` was accepted
+// by npm (202) and never served — it sits in "Validating". The sweep published
+// its dependents anyway: `publish-pins.ts` asks whether the NAME exists, and
+// `adwaita-fonts` has existed since 0.5x, so the guard passed. `adwaita-web` and
+// `adwaita-nativescript` 0.59.x went live pinning a version the registry does not
+// serve, and are uninstallable. A name guard cannot see that; a VERSION guard can,
+// at the price the name guard was designed to avoid — a version is eventually
+// consistent for minutes after its own 2xx (see `publish-readback.ts`), so this
+// one WAITS for the pin before it holds, and consults the status endpoint
+// (`publish-status.ts`) so a version that is terminally unavailable does not cost
+// the wait.
+//
+// The sweep is one `gjsify publish` PROCESS per package (`foreach --exec`), so a
+// verdict reached by one process cannot reach the next in memory. The ledger is
+// how it does: a JSONL file named by `GJSIFY_PUBLISH_LEDGER`, appended by every
+// process that finds a version unserved or holds a package. A dependent of a held
+// package then holds at once from the ledger instead of waiting out the budget
+// again — but only for a TERMINAL class; a `validating` entry is re-probed, and a
+// confirmed re-probe appends `served`. The end-of-job summary is rendered from
+// the same file.
+import { appendFileSync, existsSync, readFileSync } from 'node:fs';
+import { REQUIRED_BLOCK } from './publish-pins.js';
+import { verifyPublishedVersion } from './publish-readback.js';
+import { classifyUnserved, describeClass, fetchVersionStatus, isTerminalClass, } from './publish-status.js';
+/** Wait for a pin this long before holding. Covers the measured 252 s write lag (publish-readback.ts). */
+export const DEFAULT_HOLD_WAIT_MS = 300_000;
+/** `verifyPublishedVersion` needs a budget > 0; this makes it exactly one probe. */
+const SINGLE_PROBE_BUDGET_MS = 1;
+export function appendLedger(path, entry) {
+    if (!path)
+        return;
+    appendFileSync(path, `${JSON.stringify(entry)}\n`);
+}
+/** Tolerates a missing file (no entries yet) and skips unparseable lines rather than losing the rest. */
+export function readLedger(path) {
+    if (!path || !existsSync(path))
+        return [];
+    const entries = [];
+    for (const line of readFileSync(path, 'utf-8').split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed.ev === 'unserved' || parsed.ev === 'held' || parsed.ev === 'served')
+                entries.push(parsed);
+        }
+        catch {
+            /* a torn line from a killed process must not hide the entries around it */
+        }
+    }
+    return entries;
+}
+/**
+ * The version a rewritten pin asks for, when the spec names exactly one:
+ * `0.59.1`, `^0.59.1`, `~0.59.1`. `undefined` for a range, tag or URL — those are
+ * not decidable against one version and the name-level guard covers them.
+ */
+export function pinVersion(spec) {
+    const match = /^[\^~]?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)$/.exec(spec.trim());
+    return match?.[1];
+}
+/**
+ * Every pin whose exact version the registry does not serve (after waiting for
+ * one that may be late), with the reason. Empty = safe to publish.
+ *
+ * Three cheap exits come first, in order: the ledger already knows this version
+ * is unserved or held; one packument probe finds it served (nine in ten); the
+ * status endpoint says it can never be served. Only a pin that is none of those —
+ * possibly just late — pays the wait.
+ */
+export async function findUnavailablePins(input) {
+    const reasons = [];
+    const seen = new Map();
+    for (const pin of input.pins) {
+        const version = pinVersion(pin.spec);
+        if (!version) {
+            input.log?.(`gjsify publish: ${pin.name}@${pin.spec} names no single version — not checked for hold`);
+            continue;
+        }
+        const key = `${pin.name}@${version}`;
+        // An optional/peer edge is reported but never holds (see `holdsPublish`),
+        // so it does not earn the wait either: one probe.
+        const cacheKey = pin.block === REQUIRED_BLOCK ? key : `${key}#nowait`;
+        if (!seen.has(cacheKey)) {
+            const probe = pin.block === REQUIRED_BLOCK ? input : { ...input, waitBudgetMs: 0 };
+            seen.set(cacheKey, await judgePin(probe, pin.name, version));
+        }
+        const verdict = seen.get(cacheKey);
+        // One reason per EDGE: the same target in two blocks costs different things
+        // at install time, and the operator should see both.
+        if (verdict)
+            reasons.push({ ...verdict, block: pin.block });
+    }
+    return reasons;
+}
+async function judgePin(input, name, version) {
+    const base = { name, version, block: 'dependencies' };
+    // The LAST entry wins: a `served` entry supersedes the `unserved` one before it.
+    const known = [...input.ledger].reverse().find((e) => e.name === name && e.version === version);
+    if (known?.ev === 'served')
+        return null;
+    // Only a terminal class short-circuits. npm holds EVERY new version in
+    // `validating` for 30–90 s, and the publisher's own read-back runs inside
+    // that window, so a non-terminal entry is stale by the time a dependent
+    // looks (v0.60.0: 92 of 215 packages held on it). Fall through and re-probe.
+    if (known?.ev === 'unserved' && isTerminalClass(known.cls)) {
+        return { ...base, cls: known.cls, detail: known.detail };
+    }
+    if (known?.ev === 'held') {
+        return {
+            ...base,
+            cls: 'held',
+            detail: `was itself held — ${summariseReasons(known.reasons)}`,
+        };
+    }
+    const probeInput = {
+        registry: input.registry,
+        name,
+        version,
+        authorization: input.authorization,
+        fetchImpl: input.fetchImpl,
+        sleep: input.sleep,
+        now: input.now,
+        log: input.log,
+    };
+    let readback = await verifyPublishedVersion({
+        ...probeInput,
+        budgetMs: SINGLE_PROBE_BUDGET_MS,
+    });
+    if (readback.confirmed)
+        return confirmedServed(input, known, name, version);
+    const ask = () => fetchVersionStatus({
+        registry: input.registry,
+        name,
+        version,
+        token: input.statusToken,
+        fetchImpl: input.fetchImpl,
+    });
+    let classification = classifyUnserved(readback.verdict, await ask());
+    if (!classification.terminal && input.waitBudgetMs > 0) {
+        readback = await verifyPublishedVersion({
+            ...probeInput,
+            budgetMs: input.waitBudgetMs,
+        });
+        if (readback.confirmed)
+            return confirmedServed(input, known, name, version);
+        classification = classifyUnserved(readback.verdict, await ask());
+    }
+    return { ...base, cls: classification.cls, detail: classification.detail };
+}
+function confirmedServed(input, known, name, version) {
+    if (known?.ev === 'unserved')
+        appendLedger(input.ledgerPath, { ev: 'served', name, version });
+    return null;
+}
+/** Only a `dependencies` edge holds a publish, as in the name-level guard; the rest are reported. */
+export const holdsPublish = (reason) => reason.block === REQUIRED_BLOCK;
+export function summariseReasons(reasons) {
+    return reasons
+        .map((r) => `${r.name}@${r.version} is ${r.cls === 'held' ? 'held' : describeClass(r.cls)}`)
+        .join('; ');
+}
+/** Classify a version THIS process PUT and could not read back, and write it to the ledger. */
+export async function recordUnserved(input) {
+    const status = await fetchVersionStatus({
+        registry: input.registry,
+        name: input.name,
+        version: input.version,
+        token: input.statusToken,
+        fetchImpl: input.fetchImpl,
+    });
+    const classification = classifyUnserved(input.verdict, status);
+    appendLedger(input.ledgerPath, {
+        ev: 'unserved',
+        name: input.name,
+        version: input.version,
+        cls: classification.cls,
+        detail: classification.detail,
+    });
+    return classification;
+}
+/**
+ * The job-summary markdown for a ledger: what is unserved and why, what was held
+ * and why, and the exact command that publishes the held set once their
+ * dependencies are installable. `undefined` when nothing needs saying.
+ */
+export function renderLedgerSummary(entries, ref) {
+    const served = new Set(entries.filter((e) => e.ev === 'served').map((e) => `${e.name}@${e.version}`));
+    const unserved = entries.filter((e) => e.ev === 'unserved' && !served.has(`${e.name}@${e.version}`));
+    const held = entries.filter((e) => e.ev === 'held');
+    if (unserved.length === 0 && held.length === 0)
+        return undefined;
+    const lines = ['### npm versions that were accepted but are not installable', ''];
+    if (unserved.length > 0) {
+        lines.push('| Package | Version | State | Detail |', '| --- | --- | --- | --- |');
+        for (const e of unserved) {
+            lines.push(`| \`${e.name}\` | ${e.version} | ${describeClass(e.cls)} | ${e.detail} |`);
+        }
+        lines.push('');
+    }
+    if (held.length > 0) {
+        lines.push('### Held — NOT published in this run', '', 'Each package below depends on a version npm does not serve, so publishing it would have shipped a package that cannot be installed.', '', '| Package | Version | Because |', '| --- | --- | --- |');
+        for (const e of held)
+            lines.push(`| \`${e.name}\` | ${e.version} | ${summariseReasons(e.reasons)} |`);
+        lines.push('', 'Once the dependencies above are served by npm (a `validating` version appears on its own, or is approved/released by a maintainer), publish the held set with:', '', '```sh', `gh workflow run release.yml --ref ${ref} -f skip_publish=false -f only='${[...new Set(held.map((e) => e.name))].join(' ')}'`, '```');
+        if (entries.some((e) => e.ev === 'unserved' && (e.cls === 'blocked' || e.cls === 'deleted'))) {
+            lines.push('', 'A `blocked` or `deleted` version is a spent number: re-running the release cannot serve it, the package needs a version bump.');
+        }
+    }
+    return lines.join('\n');
+}

package/lib/utils/publish-status.d.ts

@@ -0,0 +1,83 @@
+import type { ReadbackVerdict } from './publish-readback.js';
+/** The lifecycle states the status endpoint documents. */
+export type VersionStatus = 'published' | 'validating' | 'staged' | 'blocked' | 'deleted';
+export type StatusUnavailableReason = 
+/** No token to ask with — the OIDC-only CI case. */
+'no-credential'
+/** 401: the token is wrong or lacks the scope. */
+ | 'rejected'
+/** 403: the endpoint's per-package rollout gate is closed for this package. */
+ | 'not-enabled'
+/** 404: the version does not exist, OR this token cannot see the package. Indistinguishable by design. */
+ | 'not-found'
+/** 429 / 5xx / timeout / unparseable body. */
+ | 'error';
+export type StatusProbe = {
+    state: 'known';
+    status: VersionStatus;
+} | {
+    state: 'unavailable';
+    reason: StatusUnavailableReason;
+    detail: string;
+};
+export interface FetchVersionStatusInput {
+    registry: string;
+    name: string;
+    version: string;
+    /** A bare npm access token / granular access token. Absent → `no-credential`, no request is sent. */
+    token?: string;
+    probeTimeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * The token to ask the status endpoint with: the dedicated `NPM_STATUS_TOKEN`
+ * first, then a `NODE_AUTH_TOKEN` that is a real token and not the
+ * `XXXXX-XXXXX-XXXXX-XXXXX` literal `actions/setup-node` injects when given a
+ * `registry-url`. Empty string and the placeholder both mean "none".
+ */
+export declare function statusTokenFromEnv(env: Record<string, string | undefined>): string | undefined;
+/** `GET {registry}/-/package/{name}/version/{version}/status`, classified. Never throws. */
+export declare function fetchVersionStatus(input: FetchVersionStatusInput): Promise<StatusProbe>;
+/**
+ * What a version the packument does not serve IS. The first five come from the
+ * registry's own status; the last two are what we can say without it.
+ */
+export type UnservedClass = 
+/** Automated review has not finished; the version will appear — or turn `blocked`. */
+'validating'
+/** Waits for a maintainer to approve it; nothing automatic will change this. */
+ | 'staged'
+/** Failed automated validation. Will never be served. */
+ | 'blocked'
+/** Deleted. Will never be served, and the number cannot be re-used. */
+ | 'deleted'
+/** The registry says `published` but the install document does not carry it yet (write lag). */
+ | 'published-lagging'
+/** The registry has no record of the version: the PUT did not land. */
+ | 'missing'
+/** Not served and the status endpoint could not be asked; the read-back verdict is all there is. */
+ | 'unchecked';
+export interface Classification {
+    cls: UnservedClass;
+    /** One line for the log and the summary. */
+    detail: string;
+    /**
+     * Waiting can no longer change the answer. `validating`, `published-lagging`
+     * and `unchecked` can still resolve on their own; the rest cannot.
+     */
+    terminal: boolean;
+}
+/** `classifyUnserved(...).terminal` for a class read back from the ledger. */
+export declare function isTerminalClass(cls: UnservedClass): boolean;
+/**
+ * Fold the registry's lifecycle status and the read-back verdict into ONE class.
+ *
+ * The status wins when it answered. When it did not, the read-back verdict is
+ * kept in the detail but never promoted to `missing`: `not-published` from the
+ * packument alone is exactly the observation a `validating` version produces, so
+ * "missing — re-publish" would send the operator into a 409. Only a status 404
+ * (the registry itself has no such version) earns `missing`.
+ */
+export declare function classifyUnserved(verdict: ReadbackVerdict, probe: StatusProbe): Classification;
+/** The class as a human label for tables. */
+export declare function describeClass(cls: UnservedClass): string;