@gjsify/cli 0.44.0 → 0.46.0

package/lib/utils/npm-otp.js

@@ -14,6 +14,15 @@
 import { promptLine } from './prompt.js';
 import { clearCachedOtp, readCachedOtp, writeCachedOtp } from './npm-otp-cache.js';
 const DEFAULT_QUESTION = 'This operation requires a one-time password.\nEnter OTP: ';
+/**
+ * The question for every prompt AFTER the first one in a run.
+ *
+ * A long sweep outlives a TOTP window (npm codes last ~30 s), so it legitimately
+ * asks again — but repeating the first-time wording makes that read as "it did
+ * not take my code" rather than "that code has aged out". The user then retypes
+ * the SAME digits, which is the one answer guaranteed not to work.
+ */
+const RENEW_QUESTION = 'The previous one-time password is no longer valid (npm codes last about 30 seconds).\nEnter a NEW OTP: ';
 /**
  * True when a response is an npm OTP / 2FA challenge (401 + a `www-authenticate`
  * header naming `otp`, or a body mentioning a one-time password / `EOTP`).
@@ -44,6 +53,23 @@ export class OtpProvider {
     cached;
     promptFn;
     registry;
+    /**
+     * Bumped every time a NEW code becomes current. Concurrent callers compare the
+     * epoch they last saw against this one to tell "my code was rejected" from
+     * "somebody already replaced it while I was waiting" — the second needs no
+     * prompt, it needs the other one's code.
+     */
+    generation = 0;
+    /**
+     * The prompt currently on screen, if any. THE fix for a sweep that probes with
+     * concurrency > 1: `promptLine` puts the terminal in RAW mode and echoes each
+     * keystroke by hand (utils/prompt.ts), so two live prompts mean two `data`
+     * listeners on the same stdin and every digit is echoed TWICE. Measured on a
+     * real 703-package sweep at the default concurrency of 4: five prompts stacked
+     * up and the typed code came back as `666644440000999944444444` — four echoes
+     * per keystroke. Whoever arrives second awaits this promise instead.
+     */
+    pending;
     /**
      * @param seed     Initial cached code (from `--otp`), or undefined.
      * @param promptFn How to read a fresh code. Defaults to the TTY-aware
@@ -71,14 +97,46 @@ export class OtpProvider {
     current() {
         return this.cached;
     }
+    /**
+     * How many times a new code has become current. Capture it before an attempt
+     * and hand it back to {@link refresh} / {@link invalidate} so a concurrent
+     * caller neither prompts for a code somebody already typed nor throws that
+     * code away on its own stale rejection.
+     */
+    epoch() {
+        return this.generation;
+    }
     /**
      * Prompt for a fresh code, cache it (in-process + file cache), and return the
      * trimmed input — `''` when nothing was entered, which callers read as "give up".
      */
-    async refresh(question = DEFAULT_QUESTION) {
+    async refresh(question, sinceEpoch) {
+        // Somebody supplied a newer code than this caller last saw. Its own attempt
+        // failed against the OLD code, so the answer is that code, not a prompt.
+        if (sinceEpoch !== undefined && this.generation > sinceEpoch && this.cached) {
+            return this.cached;
+        }
+        // Single-flight: one prompt at a time, ever. Two raw-mode prompts on one
+        // stdin double every echoed keystroke, and the user is being asked twice
+        // for a code that is shared anyway.
+        if (this.pending)
+            return this.pending;
+        // The provider is the only thing that knows whether a code has already
+        // been supplied in this run, so it owns the wording. An explicit
+        // `question` from the caller always wins.
+        this.pending = this.promptOnce(question ?? (this.generation > 0 ? RENEW_QUESTION : DEFAULT_QUESTION));
+        try {
+            return await this.pending;
+        }
+        finally {
+            this.pending = undefined;
+        }
+    }
+    async promptOnce(question) {
         const code = (await this.promptFn(question)).trim();
         if (code) {
             this.cached = code;
+            this.generation++;
             if (this.registry)
                 writeCachedOtp(this.registry, code);
         }
@@ -89,7 +147,13 @@ export class OtpProvider {
      * rejects it, so the NEXT command re-prompts instead of replaying a single-use
      * code the registry already burned.
      */
-    invalidate() {
+    invalidate(sinceEpoch) {
+        // Only the caller whose own code was rejected may clear it. Without this
+        // guard the first rejection in a concurrent burst wipes a code another
+        // worker just typed, and every remaining worker prompts again — the same
+        // stacked-prompt pile-up from the other direction.
+        if (sinceEpoch !== undefined && this.generation !== sinceEpoch)
+            return;
         this.cached = undefined;
         if (this.registry)
             clearCachedOtp(this.registry);
@@ -107,34 +171,45 @@ export class OtpProvider {
  */
 export async function withOtpRetry(doFetch, provider, opts = {}) {
     const maxPrompts = opts.maxPrompts ?? 2;
-    const question = opts.question ?? DEFAULT_QUESTION;
+    // Deliberately NOT defaulted here: `undefined` is what lets the provider pick
+    // between the first-time wording and the "your previous code aged out" one.
+    const question = opts.question;
     const cached = provider.current();
     const seededFirst = opts.seedFirstAttempt === true && cached !== undefined;
+    // Every invalidate/refresh below is scoped to the epoch of the code THIS call
+    // actually tried. Concurrent callers share the provider, so an unscoped
+    // `invalidate()` discards a code a sibling typed a millisecond ago and sends
+    // everyone back to the prompt.
+    let epoch = provider.epoch();
     let res = await doFetch(seededFirst ? cached : undefined);
     if (!(await isOtpChallenge(res)))
         return res;
     // The seeded code was rejected/consumed — drop it so it is not replayed and the
     // cross-invocation cache entry is cleared.
     if (seededFirst)
-        provider.invalidate();
+        provider.invalidate(epoch);
     if (!seededFirst && provider.current() !== undefined) {
+        epoch = provider.epoch();
         res = await doFetch(provider.current());
         if (!(await isOtpChallenge(res)))
             return res;
         // Stale seed, or a sibling command already burned the file-cached single-use
         // code.
-        provider.invalidate();
+        provider.invalidate(epoch);
     }
     for (let i = 0; i < maxPrompts; i++) {
-        const fresh = await provider.refresh(question);
+        // `refresh` with the epoch: if another concurrent caller has already typed a
+        // newer code, this returns THAT code and shows no prompt.
+        const fresh = await provider.refresh(question, epoch);
         if (!fresh)
             return res; // no input — hand the challenge back to the caller
+        epoch = provider.epoch();
         res = await doFetch(fresh);
         if (!(await isOtpChallenge(res)))
             return res;
         // Clear a rejected fresh code before re-prompting, so a wedged sequence never
         // leaves a burned code in the file cache.
-        provider.invalidate();
+        provider.invalidate(epoch);
     }
     return res;
 }

package/lib/utils/onboard-discovery.d.ts

@@ -0,0 +1,68 @@
+import { type Workspace } from '@gjsify/workspace';
+/** One enumeration source and how much it contributed. */
+export interface DiscoverySource {
+    /** `workspaces` (root manifest globs) | `packages` (--packages globs) | `scanned-dirs`. */
+    kind: 'workspaces' | 'packages' | 'scanned-dirs';
+    /** The globs this source used, when it had any. */
+    patterns?: readonly string[];
+    /** How many packages this source contributed AFTER dedupe against earlier sources. */
+    count: number;
+}
+export interface PackageSet {
+    packages: Workspace[];
+    sources: DiscoverySource[];
+}
+/**
+ * The directory the globs and the workspace manifest are resolved against.
+ *
+ * A workspace root wins, because that is what `discoverWorkspaces` needs. When
+ * there is none, the GIT top level is the answer and the cwd is only the last
+ * resort: `--packages '*'` run from anywhere inside a non-workspace monorepo
+ * must mean the same set every time, and resolving it against the cwd would
+ * quietly mean "the packages below wherever I happen to stand".
+ */
+export declare function resolveRepoRoot(cwd: string): string;
+/**
+ * Every `--packages` glob must match at least one directory holding a
+ * `package.json` with a name. Throws with the unmatched patterns otherwise.
+ *
+ * Mirrors `gjsify foreach`'s `--include` rule, and matters more here: foreach's
+ * empty selection runs no scripts, while onboard's empty selection is a sweep
+ * that reports itself complete having examined nothing.
+ */
+export declare function assertEveryPatternMatches(root: string, patterns: readonly string[]): void;
+/**
+ * Collect the publishable package set from every source that applies.
+ *
+ * Order is precedence: a real workspace beats a `--packages` hit beats a scanned
+ * directory, deduped by package NAME, so the manifest a build would use is the
+ * manifest the sweep publishes.
+ */
+export declare function collectOnboardPackages(root: string, cwd: string, options?: {
+    patterns?: readonly string[];
+}): PackageSet;
+/** One-line rendering of where the package set came from. */
+export declare function describeSources(sources: readonly DiscoverySource[]): string;
+/** The `owner/repo` a package's own manifest claims, or null if it claims none. */
+export declare function declaredRepository(ws: Workspace): string | null;
+/**
+ * Refuse to configure a Trusted Publisher for a package whose OWN manifest says
+ * it lives in a different repository.
+ *
+ * This replaces a hardcoded `exclude: ['@girs/*']`, and it is worth more than
+ * the thing it replaces. Measured: `gjsify onboard` in `gjsify/ts-for-gir`
+ * selects 716 packages, ~703 of them the generated `@girs/*` under
+ * `types-dev/*` — which are workspaces there, but are PUBLISHED FROM
+ * `gjsify/types`. Trusting them for `gjsify/ts-for-gir`'s `release.yml` would
+ * point their OIDC exchange at a workflow that never publishes them, i.e. break
+ * the release the sweep exists to protect.
+ *
+ * A name pattern only ever covered the one case somebody had already been bitten
+ * by. The manifest's `repository` is the package's own claim about where it
+ * comes from, so this covers every monorepo that has another project's packages
+ * inside it — vendored, submoduled, or generated.
+ *
+ * Silence is the only safe default in the other direction: a package that
+ * declares NO repository is not evidence of a mismatch, so it passes.
+ */
+export declare function assertRepositoryAgreement(selected: readonly Workspace[], repository: string): void;

package/lib/utils/onboard-discovery.js

@@ -0,0 +1,178 @@
+// Package-set discovery for `gjsify onboard`, and the ONE thing that decides
+// whether the command is a gjsify-repo chore or a monorepo tool.
+//
+// Onboard used to enumerate exactly one way: `discoverWorkspaces` over the root
+// manifest's `workspaces` globs, plus this repo's two carved-out publishable
+// directories. That set is correct HERE and empty in the repo the sweep is most
+// needed for — `gjsify/types` publishes 703 `@girs/*` packages from a root whose
+// only tracked file is `.gitignore`. There is no manifest, so there are no
+// globs, so `discoverWorkspaces` throws before anything is enumerated.
+//
+// So the package set is now built from up to three SOURCES, and every one of
+// them is REPORTED with its count. That reporting is not decoration: a sweep
+// that writes to npm derives its whole blast radius from this list, and the two
+// ways it goes wrong — enumerating nothing, and enumerating the wrong tree —
+// look identical in a summary that only prints a total. `--packages` matching
+// no directory is a HARD ERROR for the same reason `gjsify foreach --include`
+// is: a filter that selects nothing is a typo or a shell-quoting bug, never an
+// intent (and onboard's own history has the sharper version of this — it once
+// reported "127 already done" while `@gjsify/napi` was simply absent from the
+// list it had built).
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { discoverWorkspaces } from '@gjsify/workspace';
+import { join } from 'node:path';
+import { mergePublishables } from './publishable-packages.js';
+import { parseRepoFromGitRemote } from './trust-registry.js';
+import { findWorkspaceRoot } from './workspace-root.js';
+/**
+ * The directory the globs and the workspace manifest are resolved against.
+ *
+ * A workspace root wins, because that is what `discoverWorkspaces` needs. When
+ * there is none, the GIT top level is the answer and the cwd is only the last
+ * resort: `--packages '*'` run from anywhere inside a non-workspace monorepo
+ * must mean the same set every time, and resolving it against the cwd would
+ * quietly mean "the packages below wherever I happen to stand".
+ */
+export function resolveRepoRoot(cwd) {
+    const wsRoot = findWorkspaceRoot(cwd);
+    if (wsRoot)
+        return wsRoot;
+    const git = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' });
+    if (git.status === 0) {
+        const top = git.stdout.trim();
+        if (top && existsSync(top))
+            return top;
+    }
+    return cwd;
+}
+/**
+ * Every `--packages` glob must match at least one directory holding a
+ * `package.json` with a name. Throws with the unmatched patterns otherwise.
+ *
+ * Mirrors `gjsify foreach`'s `--include` rule, and matters more here: foreach's
+ * empty selection runs no scripts, while onboard's empty selection is a sweep
+ * that reports itself complete having examined nothing.
+ */
+export function assertEveryPatternMatches(root, patterns) {
+    const unmatched = patterns.filter((pattern) => {
+        try {
+            return discoverWorkspaces(root, { patterns: [pattern] }).length === 0;
+        }
+        catch {
+            return true;
+        }
+    });
+    if (unmatched.length === 0)
+        return;
+    const lines = [
+        `gjsify onboard: --packages matched no package directory (${unmatched.length} of ${patterns.length} pattern(s)) under ${root}:`,
+    ];
+    for (const pattern of unmatched)
+        lines.push(`  ${JSON.stringify(pattern)}`);
+    lines.push('  Patterns are DIRECTORY globs resolved against the repo root, and only `*` is supported', '  (one path segment). A matched directory needs a package.json with a "name".');
+    throw new Error(lines.join('\n'));
+}
+/**
+ * Collect the publishable package set from every source that applies.
+ *
+ * Order is precedence: a real workspace beats a `--packages` hit beats a scanned
+ * directory, deduped by package NAME, so the manifest a build would use is the
+ * manifest the sweep publishes.
+ */
+export function collectOnboardPackages(root, cwd, options = {}) {
+    const sources = [];
+    const packages = [];
+    const seen = new Set();
+    const take = (kind, found, patterns) => {
+        let added = 0;
+        for (const ws of found) {
+            if (!ws.name || seen.has(ws.name))
+                continue;
+            seen.add(ws.name);
+            packages.push(ws);
+            added++;
+        }
+        sources.push({ kind, patterns, count: added });
+    };
+    // 1. The root manifest's own `workspaces` globs, when the repo has them.
+    if (existsSync(join(root, 'package.json'))) {
+        try {
+            take('workspaces', discoverWorkspaces(root, { includeRoot: true }));
+        }
+        catch {
+            // A root package.json without `workspaces` is not an error here —
+            // `--packages` or the scanned dirs may still carry the whole set.
+        }
+    }
+    // 2. Explicit `--packages` globs — the path for a monorepo that is not an
+    //    npm/yarn workspace. Callers run `assertEveryPatternMatches` first, so
+    //    an empty result here can only mean "everything was already covered".
+    if (options.patterns && options.patterns.length > 0) {
+        take('packages', discoverWorkspaces(root, { patterns: [...options.patterns] }), options.patterns);
+    }
+    // 3. This repo's publishable-but-not-workspace directories. A no-op in any
+    //    repo that does not have them; see publishable-packages.ts for the
+    //    incident that put it here.
+    take('scanned-dirs', mergePublishables([], cwd));
+    return { packages, sources };
+}
+/** One-line rendering of where the package set came from. */
+export function describeSources(sources) {
+    return sources
+        .filter((s) => s.count > 0)
+        .map((s) => (s.patterns ? `${s.kind}(${s.patterns.join(',')})=${s.count}` : `${s.kind}=${s.count}`))
+        .join(' + ');
+}
+/** The `owner/repo` a package's own manifest claims, or null if it claims none. */
+export function declaredRepository(ws) {
+    const repo = ws.manifest.repository;
+    const url = typeof repo === 'string' ? repo : repo?.url;
+    if (typeof url !== 'string' || url.length === 0)
+        return null;
+    return parseRepoFromGitRemote(url);
+}
+/**
+ * Refuse to configure a Trusted Publisher for a package whose OWN manifest says
+ * it lives in a different repository.
+ *
+ * This replaces a hardcoded `exclude: ['@girs/*']`, and it is worth more than
+ * the thing it replaces. Measured: `gjsify onboard` in `gjsify/ts-for-gir`
+ * selects 716 packages, ~703 of them the generated `@girs/*` under
+ * `types-dev/*` — which are workspaces there, but are PUBLISHED FROM
+ * `gjsify/types`. Trusting them for `gjsify/ts-for-gir`'s `release.yml` would
+ * point their OIDC exchange at a workflow that never publishes them, i.e. break
+ * the release the sweep exists to protect.
+ *
+ * A name pattern only ever covered the one case somebody had already been bitten
+ * by. The manifest's `repository` is the package's own claim about where it
+ * comes from, so this covers every monorepo that has another project's packages
+ * inside it — vendored, submoduled, or generated.
+ *
+ * Silence is the only safe default in the other direction: a package that
+ * declares NO repository is not evidence of a mismatch, so it passes.
+ */
+export function assertRepositoryAgreement(selected, repository) {
+    const target = repository.toLowerCase();
+    const foreign = selected
+        .map((ws) => ({ ws, declared: declaredRepository(ws) }))
+        .filter((e) => e.declared !== null && e.declared.toLowerCase() !== target);
+    if (foreign.length === 0)
+        return;
+    const byRepo = new Map();
+    for (const { ws, declared } of foreign) {
+        const list = byRepo.get(declared) ?? [];
+        list.push(ws.name);
+        byRepo.set(declared, list);
+    }
+    const lines = [
+        `gjsify onboard: ${foreign.length} selected package(s) declare a DIFFERENT repository than ${repository}:`,
+    ];
+    for (const [repo, names] of byRepo) {
+        const shown = names.slice(0, 5).join(', ');
+        const more = names.length > 5 ? `, … (+${names.length - 5} more)` : '';
+        lines.push(`  ${repo}: ${names.length} package(s) — ${shown}${more}`);
+    }
+    lines.push("  A Trusted Publisher scoped to the wrong repository points that package's OIDC exchange", '  at a workflow that does not publish it, which breaks the release this sweep protects.', '  Either exclude them (--exclude), select only what belongs here (--include), or point', '  --repository at the repo that actually publishes them.');
+    throw new Error(lines.join('\n'));
+}

package/lib/utils/onboard-probe.d.ts

@@ -1,6 +1,6 @@
 import { type NpmrcConfig } from '@gjsify/npm-registry';
 import type { Workspace } from '@gjsify/workspace';
-import type { TrustRequester } from '../commands/trust.js';
+import type { TrustRequester, TrustRequestResult } from '../commands/trust.js';
 import { type TrustState } from './trust-registry.js';
 /** What a package needs, computed from its published + trust state. */
 export type PkgAction = 'skip' | 'trust' | 'publish-and-trust' | 'blocked';
@@ -24,6 +24,38 @@ export interface ProbeOptions {
     retryOn401?: boolean;
     /** Backoff before the single 401 retry. Default {@link PROBE_RETRY_DELAY_MS}. */
     retryDelayMs?: number;
+    /** Total time to spend waiting out HTTP 429s. Default {@link RATE_LIMIT_MAX_WAIT_MS}. */
+    maxRateLimitWaitMs?: number;
+    /** First backoff for a 429; doubles per attempt. Default {@link RATE_LIMIT_BASE_DELAY_MS}. */
+    rateLimitBaseDelayMs?: number;
+    /**
+     * Cool-down shared across the sweep. Pass ONE instance to every call so a
+     * 429 anywhere holds back everywhere; omit for an isolated request.
+     */
+    gate?: RateLimitGate;
+    /**
+     * Called on every 429 with what npm actually sent and how long we will wait.
+     * The caller decides how loud to be; reporting the FIRST one is enough to
+     * turn "we got throttled" into "npm asked for N seconds" (or into "npm said
+     * nothing, so this delay is ours").
+     */
+    onRateLimit?: (info: {
+        url: string;
+        headers: string;
+        waitMs: number;
+        fromRetryAfter: boolean;
+    }) => void;
+    /**
+     * Called after each state read with what is known SO FAR.
+     *
+     * The probe phase is the silent half of a sweep: 703 packages take minutes
+     * and, until this existed, printed nothing at all between the header and the
+     * plan. The only output in that window was the occasional 2FA prompt, which
+     * makes a working sweep and a wedged one look identical — and the prompt is
+     * the moment a user most needs to know the previous code accomplished
+     * something.
+     */
+    onProgress?: (done: number, total: number, plan: PkgPlan) => void;
     /** Injected delay (tests pass a no-op). Default: real `setTimeout`. */
     sleep?: (ms: number) => Promise<void>;
     /**
@@ -33,6 +65,50 @@ export interface ProbeOptions {
     exists?: (registry: string, name: string) => Promise<boolean | null>;
 }
 export declare const PROBE_RETRY_DELAY_MS = 400;
+/**
+ * A 429 is npm asking to be asked later — never an answer about the package.
+ *
+ * Measured on the real 703-package sweep of `gjsify/types` at the default
+ * concurrency: the first 662 reads answered and the LAST 41 came back `429`, so
+ * the plan said `41 unreadable` for packages whose state nobody had actually
+ * failed to determine. The tail of an alphabetical list is exactly where a
+ * cumulative rate limit lands, which makes the damage look like a property of
+ * those packages.
+ *
+ * Waiting is the whole fix, and it has to be bounded: an unbounded wait turns a
+ * throttled sweep into a hang with no output.
+ */
+/**
+ * A TIME budget, not an attempt count — and generous, because npm tells us
+ * nothing.
+ *
+ * The attempt count was the wrong unit and the real sweep proved it: 4 attempts
+ * with a doubling 2s base is 30 seconds of patience, npm's window is longer than
+ * that, so every in-flight request spent its budget inside one cooldown and
+ * `Done: 502 trusted … 73 failed` — all 73 at the tail, all 429, none of them a
+ * fact about those packages.
+ *
+ * With no `Retry-After` and no rate-limit headers to read (measured), waiting is
+ * the only instrument there is. Five minutes per request is worth it: the
+ * alternative is failing packages that then need another sweep, which is itself
+ * throttled. Bounded all the same, so a throttled sweep still ENDS.
+ */
+export declare const RATE_LIMIT_MAX_WAIT_MS = 300000;
+export declare const RATE_LIMIT_BASE_DELAY_MS = 2000;
+/** Ceiling for a single backoff step, so escalation stays legible. */
+export declare const RATE_LIMIT_MAX_STEP_MS = 60000;
+/**
+ * What npm told us about pacing on a 429 — verbatim, so the answer to "how fast
+ * may we go" comes from the registry rather than from a guess.
+ *
+ * Measured 2026-08-28: npm serves NO `X-RateLimit-*` headers on ordinary
+ * responses, so there is no budget to read ahead of time. `Retry-After` on the
+ * 429 itself is the only channel, and whether npm populates it on the trust
+ * endpoint is exactly what this reports the first time it happens.
+ */
+export declare function describeRateLimitHeaders(headers: Headers | undefined): string;
+/** Seconds to wait per npm's `Retry-After`, or null when it said nothing usable. */
+export declare function retryAfterMs(headers: Headers | undefined): number | null;
 /**
  * Does the registry serve a packument for this name?
  *
@@ -55,6 +131,47 @@ export declare function packumentExists(registry: string, name: string): Promise
 export declare const DEFAULT_PROBE_CONCURRENCY = 4;
 /** Map a classified trust state to the action the onboard sweep should take. */
 export declare function actionForState(state: TrustState): PkgAction;
+/**
+ * A cool-down shared by every in-flight request of a sweep.
+ *
+ * Retrying ONE throttled request in isolation is not enough, and the measured
+ * run shows why: at serial pace `gjsify/types` was already being 429'd, so every
+ * other worker kept hammering the registry through the very window the retry was
+ * waiting out — and the retry budget then expired against a limit nobody had
+ * stopped provoking. `trust failed (HTTP 429)` was the result.
+ *
+ * A 429 anywhere therefore pauses EVERYWHERE. That also makes concurrency safe
+ * to raise: the sweep self-paces down to whatever npm is willing to serve
+ * instead of the operator guessing a number.
+ */
+export declare class RateLimitGate {
+    private until;
+    private readonly now;
+    private readonly sleeper;
+    constructor(opts?: {
+        now?: () => number;
+        sleep?: (ms: number) => Promise<void>;
+    });
+    /** Block while a cool-down is in effect. */
+    wait(): Promise<void>;
+    /** Hold every request back for at least `ms` from now. */
+    penalize(ms: number): void;
+    /** Milliseconds still owed, for tests and for reporting. */
+    remainingMs(): number;
+}
+/**
+ * Issue a request, waiting out an HTTP 429 rather than reporting it as a state.
+ *
+ * Used by BOTH the probe GET and the act-phase trust POST, because a sweep long
+ * enough to be throttled on reads is long enough to be throttled on writes, and
+ * a throttled POST would otherwise be recorded as `trust failed (HTTP 429)` —
+ * a failure attributed to the package instead of to the pacing.
+ *
+ * Bounded on purpose: it returns the last 429 once the budget is spent, so the
+ * caller reports "unreadable" rather than hanging. `Retry-After` wins over the
+ * exponential backoff whenever npm sends a usable one.
+ */
+export declare function requestWaitingOutRateLimit(request: TrustRequester, method: string, url: string, body?: unknown, opts?: ProbeOptions): Promise<TrustRequestResult>;
 /**
  * Read one package's published + trust state through the SHARED trust requester.
  * A surviving `auth-required` means the 401 was not an answerable OTP challenge —