@gjsify/cli 0.64.3-next.261 → 0.64.4

package/lib/actions/build.d.ts

@@ -113,7 +113,8 @@ export declare class BuildAction {
     /**
      * Post-bundle step for a `--app browser` HTML entry: write the processed
      * `index.html` beside the JS bundle, with the entry `<script>`'s `src`
-     * rewritten to point at the built bundle. Mirrors `applyShebang` — kept in
+     * rewritten to point at the built bundle and the page's linked icons copied
+     * to `assets/` beside it. Mirrors `applyShebang` — kept in
      * the CLI (not a Rolldown plugin) because the native rolldown engine
      * exposes no `emitFile`.
      */

package/lib/actions/build.js

@@ -6,10 +6,10 @@ import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals, detectN
 import { pnpPlugin } from '@gjsify/rolldown-plugin-pnp';
 import { basename, dirname, extname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { chmod, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { chmod, copyFile, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { normalizeBundlerOptions, mergeBundlerOptions } from '../utils/normalize-bundler-options.js';
 import { inputSourceDirs, isOutdirInsideSource, libraryOutputLeakError } from '../utils/library-output.js';
-import { detectHtmlEntry, parseHtmlEntry, emitBrowserHtml, htmlOutPathFor } from '../utils/html-entry.js';
+import { collectLinkedAssets, detectHtmlEntry, emitBrowserHtml, htmlOutPathFor, parseHtmlEntry, } from '../utils/html-entry.js';
 import { assertGjsBundleLoadable, assertGjsBundleParses } from '../utils/gjs-bundle-guard.js';
 import { collectEntryPaths, describeJsxConfig, findJsxEntryPoint, jsxConfigMissingError } from '../utils/jsx-config.js';
 import { giSystemProbes } from '../utils/gi-runtime-paths.js';
@@ -489,7 +489,8 @@ export class BuildAction {
     /**
      * Post-bundle step for a `--app browser` HTML entry: write the processed
      * `index.html` beside the JS bundle, with the entry `<script>`'s `src`
-     * rewritten to point at the built bundle. Mirrors `applyShebang` — kept in
+     * rewritten to point at the built bundle and the page's linked icons copied
+     * to `assets/` beside it. Mirrors `applyShebang` — kept in
      * the CLI (not a Rolldown plugin) because the native rolldown engine
      * exposes no `emitFile`.
      */
@@ -502,9 +503,15 @@ export class BuildAction {
             scriptSrc: htmlEntry.scriptSrc,
             jsOutPath,
             outHtmlPath,
+            assets: htmlEntry.assets,
         });
         await mkdir(dirname(outHtmlPath), { recursive: true });
         await writeFile(outHtmlPath, html);
+        for (const { source, target } of new Map(htmlEntry.assets.map((a) => [a.target, a])).values()) {
+            const dest = resolve(dirname(outHtmlPath), target);
+            await mkdir(dirname(dest), { recursive: true });
+            await copyFile(source, dest);
+        }
         if (verbose)
             console.debug(`[gjsify] --app browser: wrote ${outHtmlPath}`);
     }
@@ -667,7 +674,7 @@ export class BuildAction {
                 const htmlSource = await readFile(htmlPath, 'utf-8');
                 const { moduleEntry, scriptTag, scriptSrc } = parseHtmlEntry(htmlPath, htmlSource);
                 userBundler.input = moduleEntry;
-                htmlEntry = { htmlSource, scriptTag, scriptSrc };
+                htmlEntry = { htmlSource, scriptTag, scriptSrc, assets: collectLinkedAssets(htmlPath, htmlSource) };
             }
         }
         const formatRaw = userBundler.output?.format ??

package/lib/commands/publish.d.ts

@@ -5,6 +5,7 @@ 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';
+import { type TransientRetryOptions } from '../utils/transient-retry.js';
 interface PublishOptions {
     path?: string;
     tag?: string;
@@ -16,6 +17,10 @@ interface PublishOptions {
     'verify-defer'?: boolean;
     'hold-timeout'?: number;
     'report-ledger'?: boolean;
+    'fail-on-unsettled'?: boolean;
+    'held-names'?: boolean;
+    'settle-ledger'?: boolean;
+    'settle-timeout'?: number;
     ref?: string;
     provenance?: boolean;
     'dry-run'?: boolean;
@@ -24,6 +29,12 @@ interface PublishOptions {
     'check-trusted'?: boolean;
 }
 export declare const publishCommand: Command<unknown, PublishOptions>;
+/**
+ * Whether a 409 / 403 "previously published" answer counts as success. `--tolerate-republish`
+ * says yes; so does a PUT that was retried after a 5xx, since the first attempt may have landed
+ * and the retry then finds its own version.
+ */
+export declare function acceptsRepublish(status: number, text: string, tolerate: boolean, retriedPut: boolean): boolean;
 /** Input to {@link publishWorkspace} — the token-auth-aware, OTP-shareable publish flow. */
 export interface PublishWorkspaceInput {
     /** Workspace directory to pack + publish. */
@@ -70,6 +81,8 @@ export interface PublishWorkspaceInput {
      * holding this package. Default {@link DEFAULT_HOLD_WAIT_MS}.
      */
     holdWaitMs?: number;
+    /** Retry policy for 5xx/429/network errors on the PUT. Tests pass `{ baseMs: 0 }`. */
+    putRetry?: TransientRetryOptions;
 }
 /** Discriminated result of {@link publishWorkspace}; the caller owns presentation. */
 export type PublishOutcome = {

package/lib/commands/publish.js

@@ -50,11 +50,12 @@ 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 { appendLedger, DEFAULT_HOLD_WAIT_MS, findUnavailablePins, holdsPublish, markHeldPublished, pendingEntries, readLedger, recordUnserved, renderLedgerSummary, settleUnserved, 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';
+import { fetchWithTransientRetry } from '../utils/transient-retry.js';
 export const publishCommand = {
     command: 'publish [path]',
     description: 'Pack + upload the workspace at <path> (default: cwd) to its npm registry. Drop-in for `npm publish` with workspace:^ rewrite handled automatically.',
@@ -102,6 +103,26 @@ export const publishCommand = {
         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('fail-on-unsettled', {
+        description: 'With --report-ledger: exit 1 when any package is still HELD or any accepted version is still unserved, naming them and the recovery command. The end-of-sweep gate: a sweep that left something behind must be red, not a warning.',
+        type: 'boolean',
+        default: false,
+    })
+        .option('held-names', {
+        description: 'Print, one per line, the packages the ledger shows HELD and not yet published, and exit. Feeds the held-package second pass (.github/scripts/retry-held-publish.sh).',
+        type: 'boolean',
+        default: false,
+    })
+        .option('settle-ledger', {
+        description: 'Wait up to --settle-timeout for every version the ledger records as accepted-but-unserved to be served (the longer read-back the sweep defers), record each as served, and exit.',
+        type: 'boolean',
+        default: false,
+    })
+        .option('settle-timeout', {
+        description: 'With --settle-ledger: seconds to wait. Versions poll concurrently, so this is the longest lag tolerated, not a sum. Default 600 (the fatal read-back default; measured lags reach 368 s).',
+        type: 'number',
+        default: DEFAULT_VERIFY_BUDGET_MS / 1000,
     })
         .option('ref', {
         description: 'With --report-ledger: the git ref to put in the printed recovery command.',
@@ -158,10 +179,45 @@ export const publishCommand = {
         const checkTrustedOnly = args['check-trusted'] === true;
         const trustedFlag = args.trusted;
         const verbose = Boolean(process.env.GJSIFY_PUBLISH_DEBUG);
+        const ledgerPath = process.env.GJSIFY_PUBLISH_LEDGER;
+        if (args['held-names'] === true) {
+            for (const e of pendingEntries(readLedger(ledgerPath)).held)
+                process.stdout.write(`${e.name}\n`);
+            return;
+        }
+        if (args['settle-ledger'] === true) {
+            const settleSeconds = args['settle-timeout'] ?? DEFAULT_VERIFY_BUDGET_MS / 1000;
+            if (!Number.isFinite(settleSeconds) || settleSeconds < 0) {
+                console.error(`gjsify publish: --settle-timeout must be a non-negative number of seconds, got ${JSON.stringify(args['settle-timeout'])}`);
+                return process.exit(2);
+            }
+            const npmrc = await loadNpmrc(process.cwd());
+            const served = await settleUnserved({
+                entries: readLedger(ledgerPath),
+                ledgerPath,
+                registryFor: (name) => (process.env.npm_config_registry ?? registryFor(name, npmrc) ?? DEFAULT_REGISTRY).replace(/\/$/, ''),
+                budgetMs: Math.max(1, Math.round(settleSeconds * 1000)),
+                log: verbose ? (m) => console.error(m) : undefined,
+            });
+            for (const key of served)
+                process.stdout.write(`served after settling: ${key}\n`);
+            return;
+        }
         if (args['report-ledger'] === true) {
-            const summary = renderLedgerSummary(readLedger(process.env.GJSIFY_PUBLISH_LEDGER), args.ref ?? '<tag>');
+            const entries = readLedger(ledgerPath);
+            const summary = renderLedgerSummary(entries, args.ref ?? '<tag>');
             if (summary)
                 process.stdout.write(`${summary}\n`);
+            if (args['fail-on-unsettled'] === true) {
+                const { unserved, held } = pendingEntries(entries);
+                const names = [...new Set([...held, ...unserved].map((e) => e.name))];
+                if (names.length > 0) {
+                    const ref = args.ref ?? '<tag>';
+                    console.error(`gjsify publish: ${held.length} package(s) still HELD and ${unserved.length} version(s) still unserved after the second pass: ${names.join(' ')}\n` +
+                        `  recover: re-run THIS run (\`gh run rerun <run-id>\` — keeps the version; never a new dispatch on the next channel, which mints a new one), or for a release: gh workflow run release.yml --ref ${ref} -f skip_publish=false -f only='${names.join(' ')}'`);
+                    return process.exit(1);
+                }
+            }
             return;
         }
         const holdSeconds = args['hold-timeout'] ?? DEFAULT_HOLD_WAIT_MS / 1000;
@@ -277,11 +333,29 @@ export const publishCommand = {
             otpProvider,
             seedOtpFirst: otp !== undefined,
             verifyBudgetMs,
-            holdWaitMs: Math.round(holdSeconds * 1000),
+            holdWaitMs: Math.min(Math.round(holdSeconds * 1000), remainingHoldDeadlineMs()),
         });
         reportPublishOutcome(outcome, args.json === true, deferUnconfirmed);
     },
 };
+/**
+ * Milliseconds left until `GJSIFY_HOLD_DEADLINE` (epoch ms), or Infinity when unset. The
+ * held-package second pass is one `gjsify publish` PROCESS per package, so each would otherwise
+ * pay the full `--hold-timeout` on the same blocker; a shared deadline bounds the whole pass.
+ */
+function remainingHoldDeadlineMs() {
+    const until = Number(process.env.GJSIFY_HOLD_DEADLINE);
+    return Number.isFinite(until) && until > 0 ? Math.max(0, until - Date.now()) : Infinity;
+}
+/**
+ * Whether a 409 / 403 "previously published" answer counts as success. `--tolerate-republish`
+ * says yes; so does a PUT that was retried after a 5xx, since the first attempt may have landed
+ * and the retry then finds its own version.
+ */
+export function acceptsRepublish(status, text, tolerate, retriedPut) {
+    const conflict = status === 409 || (status === 403 && /previously published/i.test(text));
+    return conflict && (tolerate || retriedPut);
+}
 /**
  * Pack + PUT a single workspace to its npm registry, returning a structured
  * outcome instead of writing/exiting. Extracted from the `publish` command so
@@ -465,13 +539,24 @@ export async function publishWorkspace(input) {
     const bodyStr = JSON.stringify(payload);
     // Each attempt clones the base headers and adds `npm-otp` (+ legacy
     // auth-type, matching buildPublishHeaders) when a code is supplied.
-    const doPut = (code) => {
+    //
+    // A transient 5xx/429/network error is retried here, inside the OTP loop (a 401 challenge is
+    // not transient and passes straight through). The first attempt may have LANDED despite its
+    // 5xx, so `retriedPut` makes a later 409 / "previously published" count as success below.
+    let retriedPut = false;
+    const doPut = async (code) => {
         const reqHeaders = { ...headers };
         if (code) {
             reqHeaders['npm-otp'] = code;
             reqHeaders['npm-auth-type'] = 'legacy';
         }
-        return fetch(url, { method: 'PUT', headers: reqHeaders, body: bodyStr });
+        const { response, retried } = await fetchWithTransientRetry(() => fetch(url, { method: 'PUT', headers: reqHeaders, body: bodyStr }), {
+            log: (m) => console.error(`gjsify publish: PUT ${packed.name}@${packed.version}: ${m}`),
+            ...input.putRetry,
+        });
+        if (retried > 0)
+            retriedPut = true;
+        return response;
     };
     const res = await withOtpRetry(doPut, otpProvider, { seedFirstAttempt: input.seedOtpFirst });
     if (verbose) {
@@ -604,6 +689,7 @@ export async function publishWorkspace(input) {
                 }),
             };
         }
+        markHeldPublished(ledgerPath, packed.name, packed.version);
         return {
             ok: true,
             action: 'published',
@@ -633,8 +719,7 @@ export async function publishWorkspace(input) {
     // this is the path a `publish-unconfirmed` re-run always lands on: exempting
     // it would leave the documented remediation reporting a success nothing
     // checked. Cost is one GET, on a path that only runs on a re-publish.
-    const isRepublishConflict = res.status === 409 || (res.status === 403 && /previously published/i.test(text));
-    if (isRepublishConflict && tolerate) {
+    if (acceptsRepublish(res.status, text, tolerate, retriedPut)) {
         const readback = await readBack();
         if (readback && !readback.confirmed) {
             return {
@@ -659,6 +744,7 @@ export async function publishWorkspace(input) {
                 }),
             };
         }
+        markHeldPublished(ledgerPath, packed.name, packed.version);
         return {
             ok: true,
             action: 'republish-tolerated',

package/lib/utils/html-entry.d.ts

@@ -18,6 +18,22 @@ export declare function detectHtmlEntry(input: RolldownOptions['input'] | undefi
  * path, with the module resolved against the HTML file's directory. Throws when there is none.
  */
 export declare function parseHtmlEntry(htmlPath: string, htmlSource: string): ParsedHtmlEntry;
+export interface LinkedAsset {
+    /** The full matched `<link …>` tag text. */
+    linkTag: string;
+    /** The raw `href` attribute value from that tag (as authored in the HTML). */
+    href: string;
+    /** Absolute path to the referenced file. */
+    source: string;
+    /** Where the copy goes, relative to the emitted HTML's directory (`assets/<name>`). */
+    target: string;
+}
+/**
+ * Every `<link>` whose `rel` names an icon and whose `href` is a local path, resolved against
+ * the HTML file's directory, each with a unique `assets/` target. The same file linked twice
+ * shares one target; two files with one basename get `-1`, `-2`, … suffixes.
+ */
+export declare function collectLinkedAssets(htmlPath: string, htmlSource: string): LinkedAsset[];
 export interface EmitBrowserHtmlInput {
     /** The original HTML source. */
     htmlSource: string;
@@ -29,11 +45,13 @@ export interface EmitBrowserHtmlInput {
     jsOutPath: string;
     /** Absolute path the emitted HTML will be written to. */
     outHtmlPath: string;
+    /** The page's linked icons from {@link collectLinkedAssets}; their `href`s point at the copies. */
+    assets?: readonly LinkedAsset[];
 }
 /**
  * The original source with the entry script's `src` rewritten to the built JS bundle, relative
- * to the output HTML's own directory so the page is portable wherever `dist/` is served from.
- * All other markup is preserved.
+ * to the output HTML's own directory so the page is portable wherever `dist/` is served from,
+ * and each linked icon's `href` rewritten to its `assets/` copy. All other markup is preserved.
  */
 export declare function emitBrowserHtml(input: EmitBrowserHtmlInput): string;
 /** Convenience: the emitted HTML filename for a given JS outfile (sibling `index.html`). */

package/lib/utils/html-entry.js

@@ -8,9 +8,11 @@
 // plugin `emitFile`: the native `@gjsify/rolldown-native` engine implements no `emitFile`, so a
 // plugin-based emit would work on the npm engine (Node) and throw under the GJS-bundled CLI.
 // Parsing is regex-based and tolerant on purpose — this is a shell-page rewrite, not a full HTML
-// pipeline. CSS is NOT extracted here: it travels in the JS bundle as a string via
+// pipeline. The page's own icons — a local `<link rel="icon" href>` and its kin — are copied
+// beside the page under `assets/` with the `href` rewritten, as Vite does, so a favicon the HTML
+// names is one the built page serves. CSS is NOT extracted here: it travels in the JS bundle as a string via
 // css-as-string and is injected by the app, the same pattern the `--app gjs` target uses.
-import { basename, dirname, isAbsolute, relative, resolve } from 'node:path';
+import { basename, dirname, extname, isAbsolute, relative, resolve } from 'node:path';
 /**
  * The `.html` path when `input` is a SINGLE html entry (a literal `.html` string, a 1-element
  * array of one, or a 1-key record whose value is one) — else `null`. Multi-entry inputs and
@@ -54,20 +56,65 @@ export function parseHtmlEntry(htmlPath, htmlSource) {
     throw new Error(`gjsify build: ${htmlPath} has no local <script type="module" src="…"> to bundle. ` +
         `Add one pointing at your app entry (e.g. <script type="module" src="./main.ts">).`);
 }
+const LINK_TAG_RE = /<link\b[^>]*>/gi;
+const HREF_ATTR_RE = /\bhref\s*=\s*["']([^"']+)["']/i;
+const REL_ATTR_RE = /\brel\s*=\s*["']([^"']+)["']/i;
+/** `rel` tokens whose `href` is a file the page itself needs; `shortcut icon` splits to `icon`. */
+const ASSET_RELS = new Set(['icon', 'apple-touch-icon', 'mask-icon']);
+/** Hosted (`https://`, `//`), inline (`data:`, `blob:`) or root-relative (`/…`, the server's) hrefs stay as authored. */
+const NOT_LOCAL_HREF_RE = /^(?:[a-z][a-z0-9+.-]*:|\/)/i;
+/**
+ * Every `<link>` whose `rel` names an icon and whose `href` is a local path, resolved against
+ * the HTML file's directory, each with a unique `assets/` target. The same file linked twice
+ * shares one target; two files with one basename get `-1`, `-2`, … suffixes.
+ */
+export function collectLinkedAssets(htmlPath, htmlSource) {
+    const assets = [];
+    const targetBySource = new Map();
+    const taken = new Set();
+    for (const match of htmlSource.matchAll(LINK_TAG_RE)) {
+        const linkTag = match[0];
+        const rel = REL_ATTR_RE.exec(linkTag)?.[1].toLowerCase().split(/\s+/) ?? [];
+        if (!rel.some((token) => ASSET_RELS.has(token)))
+            continue;
+        const href = HREF_ATTR_RE.exec(linkTag)?.[1];
+        if (!href || NOT_LOCAL_HREF_RE.test(href))
+            continue;
+        const path = href.replace(/[?#].*$/, '');
+        const source = isAbsolute(path) ? path : resolve(dirname(htmlPath), path);
+        let target = targetBySource.get(source);
+        if (!target) {
+            const ext = extname(source);
+            const stem = basename(source, ext);
+            target = `assets/${stem}${ext}`;
+            for (let n = 1; taken.has(target); n++)
+                target = `assets/${stem}-${n}${ext}`;
+            taken.add(target);
+            targetBySource.set(source, target);
+        }
+        assets.push({ linkTag, href, source, target });
+    }
+    return assets;
+}
 /**
  * The original source with the entry script's `src` rewritten to the built JS bundle, relative
- * to the output HTML's own directory so the page is portable wherever `dist/` is served from.
- * All other markup is preserved.
+ * to the output HTML's own directory so the page is portable wherever `dist/` is served from,
+ * and each linked icon's `href` rewritten to its `assets/` copy. All other markup is preserved.
  */
 export function emitBrowserHtml(input) {
-    const { htmlSource, scriptTag, scriptSrc, jsOutPath, outHtmlPath } = input;
+    const { htmlSource, scriptTag, scriptSrc, jsOutPath, outHtmlPath, assets = [] } = input;
     let rel = relative(dirname(outHtmlPath), jsOutPath).split(/[\\/]/).join('/');
     if (!rel.startsWith('.'))
         rel = `./${rel}`;
     // Rewrite the src WITHIN the matched tag, then swap that tag back in — so no other `src=`
     // in the document is touched.
     const newTag = scriptTag.replace(SRC_ATTR_RE, (whole) => whole.replace(scriptSrc, rel));
-    return htmlSource.replace(scriptTag, newTag);
+    let html = htmlSource.replace(scriptTag, newTag);
+    for (const { linkTag, href, target } of new Map(assets.map((a) => [a.linkTag, a])).values()) {
+        const newLink = linkTag.replace(HREF_ATTR_RE, (whole) => whole.replace(href, `./${target}`));
+        html = html.split(linkTag).join(newLink);
+    }
+    return html;
 }
 /** Convenience: the emitted HTML filename for a given JS outfile (sibling `index.html`). */
 export function htmlOutPathFor(jsOutPath) {

package/lib/utils/npm-oidc.d.ts

@@ -14,7 +14,7 @@ interface OidcExchangeOptions {
      * `--tolerate-untrusted-new` and the misconfig hints still fire on the first response.
      */
     maxRetries?: number;
-    /** Base backoff in ms for transient retries; doubles each attempt (capped 8s). Default 1000. Tests pass 0. */
+    /** Base backoff in ms for transient retries; doubles each attempt (capped 30s, `Retry-After` honored). Default 1000. Tests pass 0. */
     retryBaseMs?: number;
 }
 export interface OidcExchangeResult {

package/lib/utils/npm-oidc.js

@@ -13,8 +13,7 @@
 //
 // Reference: refs/npm-cli/lib/utils/oidc.js
 // Original: Copyright (c) npm contributors. Artistic-2.0.
-/** HTTP statuses worth retrying — npm-side transient/overload conditions. */
-const TRANSIENT_EXCHANGE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
+import { isTransientStatus, retryDelayMs } from './transient-retry.js';
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 export class OidcUnavailableError extends Error {
     reason;
@@ -146,7 +145,7 @@ export async function exchangeOidcForNpmToken(args) {
         catch (netErr) {
             // Network-level failure (DNS, connection reset, TLS): transient.
             if (attempt < maxRetries) {
-                const delay = Math.min(retryBaseMs * 2 ** attempt, 8000);
+                const delay = retryDelayMs(attempt, retryBaseMs);
                 log?.(`gjsify oidc: network error for ${packageName} (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${delay}ms`);
                 await sleep(delay);
                 continue;
@@ -156,8 +155,9 @@ export async function exchangeOidcForNpmToken(args) {
         const text = await res.text().catch(() => '');
         if (!res.ok) {
             // Only TRANSIENT npm-side failures retry — see `maxRetries`.
-            if (TRANSIENT_EXCHANGE_STATUSES.has(res.status) && attempt < maxRetries) {
-                const delay = Math.min(retryBaseMs * 2 ** attempt, 8000);
+            if (isTransientStatus(res.status) && attempt < maxRetries) {
+                // `Retry-After` wins over the backoff when npm sends one (429/503 during an incident).
+                const delay = retryDelayMs(attempt, retryBaseMs, res.headers.get('retry-after'));
                 log?.(`gjsify oidc: transient ${res.status} ${res.statusText} for ${packageName} (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${delay}ms`);
                 await sleep(delay);
                 continue;

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

@@ -27,7 +27,10 @@ export type LedgerEntry =
     version: string;
     reasons: HoldReason[];
 }
-/** A later probe found a version an earlier `unserved` entry recorded now served; it supersedes that entry. */
+/**
+ * The version is now served; it supersedes an earlier `unserved` OR `held` entry (last entry
+ * wins) — a later probe found it, or the held-package second pass published it.
+ */
  | {
     ev: 'served';
     name: string;
@@ -86,4 +89,41 @@ export declare function recordUnserved(input: {
  * and why, and the exact command that publishes the held set once their
  * dependencies are installable. `undefined` when nothing needs saying.
  */
+type UnservedEntry = Extract<LedgerEntry, {
+    ev: 'unserved';
+}>;
+type HeldEntry = Extract<LedgerEntry, {
+    ev: 'held';
+}>;
+/** One entry per `name@version` — the LAST one — keeping only those still not served. */
+export declare function pendingEntries(entries: readonly LedgerEntry[]): {
+    unserved: UnservedEntry[];
+    held: HeldEntry[];
+};
+/**
+ * Record that a package this run once HELD has now been published, so its dependents stop
+ * holding on it (`judgePin` reads the last entry) and the end-of-job check stops naming it.
+ */
+export declare function markHeldPublished(path: string | undefined, name: string, version: string): void;
+export interface SettleUnservedInput {
+    entries: readonly LedgerEntry[];
+    ledgerPath: string | undefined;
+    /** Registry for a package name (scoped registries differ). */
+    registryFor: (name: string) => string;
+    /** One shared deadline: the entries poll concurrently, so the cost is the longest lag, not the sum. */
+    budgetMs: number;
+    authorization?: string;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    log?: (msg: string) => void;
+}
+/**
+ * Wait for versions npm ACCEPTED but did not serve inside the sweep's 5 s read-back, and append
+ * `served` for each one that shows up. This is the longer read-back the sweep deliberately defers
+ * (publishing.md: lags reach 252–368 s). A TERMINAL class (blocked/deleted/staged/missing) is a
+ * spent number — waiting cannot help, so it is skipped. Returns the names confirmed.
+ */
+export declare function settleUnserved(input: SettleUnservedInput): Promise<string[]>;
 export declare function renderLedgerSummary(entries: readonly LedgerEntry[], ref: string): string | undefined;
+export {};

package/lib/utils/publish-hold.js

@@ -181,15 +181,55 @@ export async function recordUnserved(input) {
     });
     return classification;
 }
+/** One entry per `name@version` — the LAST one — keeping only those still not served. */
+export function pendingEntries(entries) {
+    const last = new Map();
+    for (const e of entries)
+        last.set(`${e.name}@${e.version}`, e);
+    const pending = [...last.values()];
+    return {
+        unserved: pending.filter((e) => e.ev === 'unserved'),
+        held: pending.filter((e) => e.ev === 'held'),
+    };
+}
 /**
- * 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.
+ * Record that a package this run once HELD has now been published, so its dependents stop
+ * holding on it (`judgePin` reads the last entry) and the end-of-job check stops naming it.
  */
+export function markHeldPublished(path, name, version) {
+    const last = [...readLedger(path)].reverse().find((e) => e.name === name && e.version === version);
+    if (last?.ev === 'held')
+        appendLedger(path, { ev: 'served', name, version });
+}
+/**
+ * Wait for versions npm ACCEPTED but did not serve inside the sweep's 5 s read-back, and append
+ * `served` for each one that shows up. This is the longer read-back the sweep deliberately defers
+ * (publishing.md: lags reach 252–368 s). A TERMINAL class (blocked/deleted/staged/missing) is a
+ * spent number — waiting cannot help, so it is skipped. Returns the names confirmed.
+ */
+export async function settleUnserved(input) {
+    const waiting = pendingEntries(input.entries).unserved.filter((e) => !isTerminalClass(e.cls));
+    const confirmed = await Promise.all(waiting.map(async (e) => {
+        const readback = await verifyPublishedVersion({
+            registry: input.registryFor(e.name),
+            name: e.name,
+            version: e.version,
+            budgetMs: input.budgetMs,
+            authorization: input.authorization,
+            fetchImpl: input.fetchImpl,
+            sleep: input.sleep,
+            now: input.now,
+            log: input.log,
+        });
+        if (!readback.confirmed)
+            return undefined;
+        appendLedger(input.ledgerPath, { ev: 'served', name: e.name, version: e.version });
+        return `${e.name}@${e.version}`;
+    }));
+    return confirmed.filter((x) => x !== undefined);
+}
 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');
+    const { unserved, held } = pendingEntries(entries);
     if (unserved.length === 0 && held.length === 0)
         return undefined;
     const lines = ['### npm versions that were accepted but are not installable', ''];
@@ -205,7 +245,7 @@ export function renderLedgerSummary(entries, ref) {
         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'))) {
+        if (unserved.some((e) => 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.');
         }
     }

package/lib/utils/transient-retry.d.ts

@@ -0,0 +1,37 @@
+/** HTTP statuses worth retrying — npm-side transient/overload conditions. */
+export declare const TRANSIENT_STATUSES: ReadonlySet<number>;
+export declare const isTransientStatus: (status: number) => boolean;
+/** Longest single wait, whether it came from the backoff or from a `Retry-After`. */
+export declare const MAX_RETRY_DELAY_MS = 30000;
+/**
+ * Milliseconds a `Retry-After` header asks for: delta-seconds or an HTTP date. `undefined` when
+ * absent or unparseable.
+ */
+export declare function parseRetryAfter(value: string | null | undefined, now?: number): number | undefined;
+/** The wait before retry `attempt` (0-based): `Retry-After` if the server sent one, else doubling backoff; capped. */
+export declare function retryDelayMs(attempt: number, baseMs: number, retryAfter?: string | null): number;
+export interface TransientRetryOptions {
+    /** Retries after the first attempt. Default {@link DEFAULT_TRANSIENT_RETRIES}. */
+    retries?: number;
+    /** Base backoff in ms, doubling per attempt. Default {@link DEFAULT_TRANSIENT_BASE_MS}. Tests pass 0. */
+    baseMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    log?: (msg: string) => void;
+}
+/**
+ * Five retries at 2/4/8/16/30 s: ~60 s of patience per package. Long enough to ride out a blip,
+ * short enough that a real outage fails the sweep in a minute instead of stalling 232 packages
+ * behind it — the failure is then a red job, recovered by a re-run (`--tolerate-republish`).
+ */
+export declare const DEFAULT_TRANSIENT_RETRIES = 5;
+export declare const DEFAULT_TRANSIENT_BASE_MS = 2000;
+export interface TransientRetryResult {
+    response: Response;
+    /** How many retries were spent; >0 means an earlier attempt may have landed. */
+    retried: number;
+}
+/**
+ * Run `doFetch`, retrying a thrown network error or a transient status. Returns the last response
+ * once the budget is spent (the caller interprets the 5xx); rethrows the last network error.
+ */
+export declare function fetchWithTransientRetry(doFetch: () => Promise<Response>, opts?: TransientRetryOptions): Promise<TransientRetryResult>;