sequant 2.9.0 → 2.11.0

package/dist/src/lib/cli-ui/run-renderer-types.d.ts

@@ -4,7 +4,7 @@
  * The renderer is event-driven: a `ProgressEvent` flows in and the renderer
  * decides whether to update the live zone, append an event line, or both.
  */
-export type ProgressEventKind = "start" | "complete" | "failed";
+export type ProgressEventKind = "start" | "complete" | "failed" | "waiting";
 /** Raw event from batch-executor `emitProgressLine` / `onProgress` callbacks. */
 export interface ProgressEvent {
     issue: number;
@@ -19,15 +19,34 @@ export interface ProgressEvent {
      * cell as `loop N/M` (#624 Item 3).
      */
     iteration?: number;
+    /**
+     * `"waiting"` (#804): display message for an in-progress auto-wait.
+     */
+    text?: string;
+    /**
+     * `"waiting"` (#804): epoch ms at which the auto-wait ends. Absent on the
+     * terminal notice, which returns the phase to `running`.
+     */
+    wakeAtMs?: number;
 }
 /** Per-phase status tracked inside the renderer state machine. */
 export interface PhaseState {
     name: string;
-    status: "pending" | "running" | "done" | "failed";
+    /**
+     * `"waiting"` (#804) is a *paused* running phase, not a terminal state: the
+     * phase spawn has failed on an exhausted rate-limit window and the executor
+     * is sleeping until it reopens. It returns to `"running"` on wake.
+     */
+    status: "pending" | "running" | "done" | "failed" | "waiting";
     startedAt?: number;
     durationMs?: number;
     /** Loop iteration label (e.g. "loop 2/3"). */
     loopIteration?: number;
+    /**
+     * #804: epoch ms at which an in-progress auto-wait ends. Set only while
+     * `status === "waiting"`; cleared on resume.
+     */
+    wakeAtMs?: number;
     /**
      * #624 Item 4: normalized signature of the most recent failure for THIS
      * phase (ANSI-stripped, lowercased, first 80 chars, trimmed). Per-phase so
@@ -98,6 +117,8 @@ export interface IssueSummary {
     loopTriggered?: boolean;
     prNumber?: number;
     prUrl?: string;
+    /** Set when PR creation was skipped for lack of commits ahead of base (#920). */
+    prSkippedReason?: string;
     failureReason?: string;
     qaVerdict?: string;
     unmetCount?: number;
@@ -191,11 +212,6 @@ export interface RenderOptions {
      * tracks the configured maximum instead of being hardcoded. Defaults to 3.
      */
     maxLoopIterations?: number;
-    /**
-     * When true, `renderSummary` is rendered even if no issues were registered.
-     * Default: false (matches existing displaySummary behaviour).
-     */
-    alwaysRenderSummary?: boolean;
     /**
      * #647: inject a `log-update` instance (typically built via
      * `createLogUpdate(stream)` against a custom stream). Used by the

package/dist/src/lib/cli-ui/run-renderer.d.ts

@@ -88,6 +88,8 @@ export declare class NonTTYRenderer extends BaseRenderer {
     private readonly columnsOverride?;
     private readonly maxLoopIterations;
     private lastEventAt;
+    /** #860 AC-6: `issue:phase` keys whose auto-wait start line was emitted. */
+    private readonly announcedWaits;
     constructor(options: RenderOptions);
     private getColumns;
     private startHeartbeat;
@@ -95,6 +97,14 @@ export declare class NonTTYRenderer extends BaseRenderer {
     tickHeartbeatNow(): void;
     private tickHeartbeat;
     protected afterEvent(event: ProgressEvent, state: IssueState): void;
+    /**
+     * Announce auto-wait transitions (#860 AC-6). Only the first notice of a
+     * wait and the terminal notice that ends it produce lines — the ~15s ticks
+     * in between are absorbed here (the periodic signal is `tickHeartbeat`).
+     * Before this, waiting events fell through `emitEventLine`'s failure branch
+     * and printed a spurious `✘` line per tick.
+     */
+    private emitWaitTransitionLine;
     private emitEventLine;
     /** Append a single `\n`-terminated line with `[HH:MM:SS]` prefix. */
     private emitLine;

package/dist/src/lib/cli-ui/run-renderer.js

@@ -19,6 +19,7 @@ import chalk from "chalk";
 import logUpdate from "log-update";
 import stringWidth from "string-width";
 import { formatElapsedTime, formatTimestamp } from "./format.js";
+import { formatResetTime } from "../errors.js";
 import { pipelineHasFailed } from "../workflow/status-derivation.js";
 const DEFAULT_LIVE_TICK_MS = 1000;
 const DEFAULT_NON_TTY_HEARTBEAT_MS = 60_000;
@@ -229,6 +230,23 @@ class BaseRenderer {
             state.subStatus = undefined;
             return;
         }
+        // #804 AC-7: an auto-wait pauses a phase rather than ending it. Presence of
+        // `wakeAtMs` distinguishes an in-progress wait from the terminal notice
+        // that resumes it, so the live zone never strands a "waiting" cell.
+        if (event.event === "waiting") {
+            if (event.wakeAtMs !== undefined) {
+                phase.status = "waiting";
+                phase.wakeAtMs = event.wakeAtMs;
+                state.subStatus = event.text;
+            }
+            else {
+                if (phase.status === "waiting")
+                    phase.status = "running";
+                phase.wakeAtMs = undefined;
+                state.subStatus = undefined;
+            }
+            return;
+        }
         if (event.event === "complete") {
             phase.status = "done";
             if (event.durationSeconds !== undefined) {
@@ -329,6 +347,8 @@ export class NonTTYRenderer extends BaseRenderer {
     columnsOverride;
     maxLoopIterations;
     lastEventAt;
+    /** #860 AC-6: `issue:phase` keys whose auto-wait start line was emitted. */
+    announcedWaits = new Set();
     constructor(options) {
         super(options);
         this.heartbeatMs =
@@ -367,15 +387,53 @@ export class NonTTYRenderer extends BaseRenderer {
             return;
         const parts = running.map((s) => {
             const elapsedSec = s.startedAt !== undefined ? (this.now() - s.startedAt) / 1000 : 0;
+            // #860 AC-6: a phase paused on an auto-wait names its wake time instead
+            // of masquerading as ordinary running time — this heartbeat is the only
+            // periodic signal a non-TTY (background) run gets during a multi-hour
+            // wait, and without the wake time it is indistinguishable from a hang.
+            const waiting = s.phases.find((p) => p.name === s.currentPhase && p.status === "waiting");
+            if (waiting?.wakeAtMs !== undefined) {
+                const leftSec = Math.max(0, (waiting.wakeAtMs - this.now()) / 1000);
+                return `#${s.issueNumber} ${s.currentPhase} ⏸ rate-limit window — resuming at ${formatResetTime(waiting.wakeAtMs)} (${formatElapsedTime(leftSec)} left)`;
+            }
             return `#${s.issueNumber} ${s.currentPhase} (${formatElapsedTime(elapsedSec)})`;
         });
         this.emitLine(`⏱ still running: ${parts.join(", ")}`);
     }
     afterEvent(event, state) {
         super.afterEvent(event, state);
+        // #860 AC-6: waiting notices are liveness, not progress. The wait emits a
+        // tick every ~15s, so counting them as events would hold `lastEventAt`
+        // fresh forever and silence the heartbeat for the entire multi-hour wait.
+        if (event.event === "waiting") {
+            this.emitWaitTransitionLine(event);
+            return;
+        }
         this.lastEventAt = this.now();
         this.emitEventLine(event, state);
     }
+    /**
+     * Announce auto-wait transitions (#860 AC-6). Only the first notice of a
+     * wait and the terminal notice that ends it produce lines — the ~15s ticks
+     * in between are absorbed here (the periodic signal is `tickHeartbeat`).
+     * Before this, waiting events fell through `emitEventLine`'s failure branch
+     * and printed a spurious `✘` line per tick.
+     */
+    emitWaitTransitionLine(event) {
+        const key = `${event.issue}:${event.phase}`;
+        const c = colorize(this.noColor);
+        if (event.wakeAtMs !== undefined) {
+            if (this.announcedWaits.has(key))
+                return;
+            this.announcedWaits.add(key);
+            this.emitLine(`${c.yellow("⏸")} #${event.issue} ${event.phase} ${event.text ?? `rate-limit window — resuming at ${formatResetTime(event.wakeAtMs)}`}`);
+        }
+        else {
+            if (!this.announcedWaits.delete(key))
+                return;
+            this.emitLine(`${c.cyan("▸")} #${event.issue} ${event.phase} ${event.text ?? "auto-wait complete — resuming"}`);
+        }
+    }
     emitEventLine(event, state) {
         const c = colorize(this.noColor);
         const phase = state.phases.find((p) => p.name === event.phase);
@@ -1135,6 +1193,10 @@ export class TTYRenderer extends BaseRenderer {
                     return c.green(`${p.name} ✔${p.durationMs ? ` ${formatElapsedTime(p.durationMs / 1000)}` : ""}`);
                 if (p.status === "failed")
                     return c.red(`${p.name} ✘`);
+                // #804: a paused phase reads as `qa waiting 14:33`, so the wake time
+                // is visible in the live zone itself, not only the sub-status line.
+                if (p.status === "waiting")
+                    return c.yellow(`${p.name} waiting${p.wakeAtMs ? ` ${formatResetTime(p.wakeAtMs)}` : ""}`);
                 if (p.status === "running")
                     return c.cyan(`${p.name} running`);
                 // #672 AC-3: pending cells render as `name –` (en dash) so the live
@@ -1270,7 +1332,13 @@ function renderSummaryDetail(r, ctx) {
             .map((p) => (p.success ? c.green(p.name) : c.red(p.name)))
             .join(" → ");
         const pr = r.prNumber ? ` · PR #${r.prNumber}` : "";
-        return { summary: `${phaseSeq}${pr}`, extras: [] };
+        // #920: a phase-restricted run (no PR, no failure) still needs the reason
+        // stated — otherwise a passing spec-only run looks indistinguishable from
+        // one where PR creation was simply never attempted for no stated reason.
+        const extras = !r.prNumber && r.prSkippedReason
+            ? [c.dim(`PR skipped — ${r.prSkippedReason}`)]
+            : [];
+        return { summary: `${phaseSeq}${pr}`, extras };
     }
     // Failed → multi-line detail.
     const reason = r.failureReason ?? "failure";

package/dist/src/lib/errors.d.ts

@@ -145,15 +145,65 @@ export interface RateLimitInfoLike {
     hasChargeableSavedPaymentMethod?: boolean;
 }
 /**
- * True when the rate-limit info represents a billing/credits failure (which a
- * retry cannot fix), rather than a transient throttle.
+ * True when the rate-limit info describes an exhausted *window* that will
+ * reopen at a known future time: a recognized window `rateLimitType` plus a
+ * `resetsAt` still in the future (#860 AC-1).
+ *
+ * This is the discriminator between "subscription window closed until 07:00"
+ * and "account needs credits". The fields that would answer that directly
+ * (`canUserPurchaseCredits`, `hasChargeableSavedPaymentMethod`) are absent
+ * from every real captured payload, so the window shape is the proxy — and
+ * any unrecognized shape returns false (fail closed, #860 AC-3).
+ *
+ * Explicitly informational statuses (`allowed` / `allowed_warning`) are never
+ * waitable. The driver retains marker-carrying warnings as failure-grade
+ * (pre-#732 semantics, unchanged), so a stale "you are nearing your limit"
+ * warning can be misattributed to an unrelated phase failure — classifying it
+ * waitable would upgrade that misattribution from a cheap immediate halt to a
+ * multi-hour sleep. The 26 real captures carry no `status` field at all, so
+ * absent status stays waitable; only a status that affirmatively says
+ * "not a rejection" is excluded.
+ */
+export declare function isWaitableWindow(info: RateLimitInfoLike, now?: number): boolean;
+/**
+ * Vocabulary-drift telemetry for the #860 fail-closed path: returns a hint
+ * string when a payload was terminal ONLY because its `rateLimitType` is not
+ * in the recognized window allowlist — i.e. it carries `out_of_credits` plus a
+ * live future `resetsAt` and a *present but unrecognized* window type, and no
+ * explicit `credits_required`. If Anthropic renames or adds a window type,
+ * the halt message names the rejected type instead of silently reading as an
+ * ordinary wallet failure. A missing `rateLimitType` is NOT drift evidence
+ * (API-account payloads may legitimately omit it), so no hint fires there.
+ */
+export declare function unrecognizedWindowHint(info: RateLimitInfoLike, now?: number): string | null;
+/**
+ * True when the rate-limit info represents a billing/credits failure (which
+ * waiting cannot fix), rather than a transient throttle or an exhausted
+ * window.
+ *
+ * Narrowed by #860: a subscription plan hitting its five-hour cap with
+ * overage disabled emits `overageDisabledReason: "out_of_credits"` *plus* a
+ * window type and a live `resetsAt` — a pause, not a wallet failure. That
+ * shape is excluded here so it classifies as a retryable {@link RateLimitError}
+ * and `--auto-wait` (#804) can act on it. An explicit
+ * `errorCode: "credits_required"` stays terminal even alongside window
+ * evidence — it is the SDK's direct "purchase needed" signal (#860 AC-2).
+ * Anything short of the full recognized window shape remains terminal
+ * (fail closed, #860 AC-3).
  */
-export declare function isBillingFailure(info: RateLimitInfoLike): boolean;
+export declare function isBillingFailure(info: RateLimitInfoLike, now?: number): boolean;
 /**
  * True when the rate-limit info represents an actual failure (rejection or
  * billing), as opposed to an informational `allowed` / `allowed_warning`
  * event. The driver uses this to avoid mis-attributing a stale warning event
  * to an unrelated phase failure.
+ *
+ * Built on the raw billing *markers*, not the #860-narrowed classification:
+ * the captured five-hour payloads cannot prove they carried
+ * `status: "rejected"`, so narrowing here could silently drop the very events
+ * #860 exists to keep (they'd fall back to a metadata-less assistant error and
+ * auto-wait would stay inert). Retention semantics are unchanged; only the
+ * billing-vs-waitable *classification* narrowed.
  */
 export declare function isRateLimitFailureInfo(info: RateLimitInfoLike): boolean;
 /**
@@ -162,6 +212,20 @@ export declare function isRateLimitFailureInfo(info: RateLimitInfoLike): boolean
  * displayed: values below ~1e12 are seconds, otherwise milliseconds.
  */
 export declare function resetsAtToMs(resetsAt: number): number;
+/**
+ * Format a Unix timestamp (seconds or ms) as a local time string.
+ *
+ * Bare `HH:MM` when the reset falls on the current local calendar day;
+ * date-qualified `MM-DD HH:MM` otherwise. Also used for #804's auto-wait wake
+ * time (a wake is `resetsAt + buffer`, already in ms, which `resetsAtToMs`
+ * passes through unchanged) so both render in one convention.
+ *
+ * Multi-day windows
+ * (`rateLimitType: seven_day*`) can reset days out — a bare `HH:MM` there reads
+ * as "later today" and misleads the user (#732 QA follow-up), so the date is
+ * included whenever the reset is not today.
+ */
+export declare function formatResetTime(resetsAt: number): string;
 /**
  * Build a user-facing message from rate-limit info, naming the real cause:
  * - billing/credits → "Out of credits" (enriched with purchasable vs hard
@@ -169,14 +233,22 @@ export declare function resetsAtToMs(resetsAt: number): number;
  * - transient throttle → "Rate limited — resets at HH:MM" (date-qualified as
  *   "MM-DD HH:MM" when the reset is not today; reset time omitted entirely when
  *   `resetsAt` is absent)
+ *
+ * `now` feeds the #860 waitable-window classification so message and error
+ * type are derived against the same instant (and tests can pin the clock).
+ * A waitable window renders through the rate-limited branch — its reset time
+ * is the actionable fact; "Out of credits" would misname a pause as a wallet
+ * failure.
  */
-export declare function formatRateLimitMessage(info: RateLimitInfoLike): string;
+export declare function formatRateLimitMessage(info: RateLimitInfoLike, now?: number): string;
 /**
  * Construct the appropriate typed error from structured rate-limit info.
  * Billing/credits failures become a non-retryable {@link BillingError};
- * transient throttles become a retryable {@link RateLimitError}.
+ * transient throttles AND exhausted-but-reopening windows (#860) become a
+ * retryable {@link RateLimitError}. `now` pins the waitable-window check to
+ * one instant across message and classification.
  */
-export declare function createRateLimitError(info: RateLimitInfoLike): RateLimitError | BillingError;
+export declare function createRateLimitError(info: RateLimitInfoLike, now?: number): RateLimitError | BillingError;
 /**
  * Map of error type names to their constructors.
  * Used for deserialization from logs.

package/dist/src/lib/errors.js

@@ -107,21 +107,122 @@ export class BillingError extends SequantError {
     }
 }
 /**
- * True when the rate-limit info represents a billing/credits failure (which a
- * retry cannot fix), rather than a transient throttle.
+ * Recognized rate-limit *window* vocabulary — limit types whose exhaustion is
+ * a pause that reopens at `resetsAt`, not a wallet state. `five_hour` is the
+ * subscription session window; `seven_day` is prefix-matched because the SDK
+ * emits model-qualified variants (`seven_day*`, see {@link formatResetTime}).
+ *
+ * Deliberately an allowlist (#860 AC-3): this encodes an inference about
+ * Anthropic's payload vocabulary, so an unlisted type (e.g. `overage`) must
+ * fail closed to the terminal billing path rather than into a five-hour sleep.
+ */
+const WAITABLE_WINDOW_TYPE_RE = /^(five_hour|seven_day)/;
+/**
+ * True when the rate-limit info describes an exhausted *window* that will
+ * reopen at a known future time: a recognized window `rateLimitType` plus a
+ * `resetsAt` still in the future (#860 AC-1).
+ *
+ * This is the discriminator between "subscription window closed until 07:00"
+ * and "account needs credits". The fields that would answer that directly
+ * (`canUserPurchaseCredits`, `hasChargeableSavedPaymentMethod`) are absent
+ * from every real captured payload, so the window shape is the proxy — and
+ * any unrecognized shape returns false (fail closed, #860 AC-3).
+ *
+ * Explicitly informational statuses (`allowed` / `allowed_warning`) are never
+ * waitable. The driver retains marker-carrying warnings as failure-grade
+ * (pre-#732 semantics, unchanged), so a stale "you are nearing your limit"
+ * warning can be misattributed to an unrelated phase failure — classifying it
+ * waitable would upgrade that misattribution from a cheap immediate halt to a
+ * multi-hour sleep. The 26 real captures carry no `status` field at all, so
+ * absent status stays waitable; only a status that affirmatively says
+ * "not a rejection" is excluded.
+ */
+export function isWaitableWindow(info, now = Date.now()) {
+    if (info.status === "allowed" || info.status === "allowed_warning") {
+        return false;
+    }
+    if (typeof info.rateLimitType !== "string")
+        return false;
+    if (!WAITABLE_WINDOW_TYPE_RE.test(info.rateLimitType))
+        return false;
+    if (typeof info.resetsAt !== "number")
+        return false;
+    return resetsAtToMs(info.resetsAt) > now;
+}
+/**
+ * Vocabulary-drift telemetry for the #860 fail-closed path: returns a hint
+ * string when a payload was terminal ONLY because its `rateLimitType` is not
+ * in the recognized window allowlist — i.e. it carries `out_of_credits` plus a
+ * live future `resetsAt` and a *present but unrecognized* window type, and no
+ * explicit `credits_required`. If Anthropic renames or adds a window type,
+ * the halt message names the rejected type instead of silently reading as an
+ * ordinary wallet failure. A missing `rateLimitType` is NOT drift evidence
+ * (API-account payloads may legitimately omit it), so no hint fires there.
+ */
+export function unrecognizedWindowHint(info, now = Date.now()) {
+    if (info.errorCode === "credits_required")
+        return null;
+    if (info.overageDisabledReason !== "out_of_credits")
+        return null;
+    if (info.status === "allowed" || info.status === "allowed_warning") {
+        return null;
+    }
+    if (typeof info.rateLimitType !== "string")
+        return null;
+    if (WAITABLE_WINDOW_TYPE_RE.test(info.rateLimitType))
+        return null;
+    if (typeof info.resetsAt !== "number")
+        return null;
+    if (resetsAtToMs(info.resetsAt) <= now)
+        return null;
+    return `unrecognized window type "${info.rateLimitType}" with a future reset — treated as terminal (auto-wait recognizes five_hour/seven_day)`;
+}
+/**
+ * True when the info carries an explicit billing/credits marker, regardless
+ * of whether a live window would make it waitable. This is the pre-#860
+ * `isBillingFailure` predicate, kept for failure-*detection* sites
+ * ({@link isRateLimitFailureInfo}) whose retention semantics must not narrow.
  */
-export function isBillingFailure(info) {
+function hasBillingMarkers(info) {
     return (info.errorCode === "credits_required" ||
         info.overageDisabledReason === "out_of_credits");
 }
+/**
+ * True when the rate-limit info represents a billing/credits failure (which
+ * waiting cannot fix), rather than a transient throttle or an exhausted
+ * window.
+ *
+ * Narrowed by #860: a subscription plan hitting its five-hour cap with
+ * overage disabled emits `overageDisabledReason: "out_of_credits"` *plus* a
+ * window type and a live `resetsAt` — a pause, not a wallet failure. That
+ * shape is excluded here so it classifies as a retryable {@link RateLimitError}
+ * and `--auto-wait` (#804) can act on it. An explicit
+ * `errorCode: "credits_required"` stays terminal even alongside window
+ * evidence — it is the SDK's direct "purchase needed" signal (#860 AC-2).
+ * Anything short of the full recognized window shape remains terminal
+ * (fail closed, #860 AC-3).
+ */
+export function isBillingFailure(info, now = Date.now()) {
+    if (info.errorCode === "credits_required")
+        return true;
+    return (info.overageDisabledReason === "out_of_credits" &&
+        !isWaitableWindow(info, now));
+}
 /**
  * True when the rate-limit info represents an actual failure (rejection or
  * billing), as opposed to an informational `allowed` / `allowed_warning`
  * event. The driver uses this to avoid mis-attributing a stale warning event
  * to an unrelated phase failure.
+ *
+ * Built on the raw billing *markers*, not the #860-narrowed classification:
+ * the captured five-hour payloads cannot prove they carried
+ * `status: "rejected"`, so narrowing here could silently drop the very events
+ * #860 exists to keep (they'd fall back to a metadata-less assistant error and
+ * auto-wait would stay inert). Retention semantics are unchanged; only the
+ * billing-vs-waitable *classification* narrowed.
  */
 export function isRateLimitFailureInfo(info) {
-    return info.status === "rejected" || isBillingFailure(info);
+    return info.status === "rejected" || hasBillingMarkers(info);
 }
 /**
  * Normalize a `resetsAt` timestamp to milliseconds. The SDK does not pin the
@@ -135,12 +236,16 @@ export function resetsAtToMs(resetsAt) {
  * Format a Unix timestamp (seconds or ms) as a local time string.
  *
  * Bare `HH:MM` when the reset falls on the current local calendar day;
- * date-qualified `MM-DD HH:MM` otherwise. Multi-day windows
+ * date-qualified `MM-DD HH:MM` otherwise. Also used for #804's auto-wait wake
+ * time (a wake is `resetsAt + buffer`, already in ms, which `resetsAtToMs`
+ * passes through unchanged) so both render in one convention.
+ *
+ * Multi-day windows
  * (`rateLimitType: seven_day*`) can reset days out — a bare `HH:MM` there reads
  * as "later today" and misleads the user (#732 QA follow-up), so the date is
  * included whenever the reset is not today.
  */
-function formatResetTime(resetsAt) {
+export function formatResetTime(resetsAt) {
     const ms = resetsAtToMs(resetsAt);
     const d = new Date(ms);
     const hh = String(d.getHours()).padStart(2, "0");
@@ -163,16 +268,27 @@ function formatResetTime(resetsAt) {
  * - transient throttle → "Rate limited — resets at HH:MM" (date-qualified as
  *   "MM-DD HH:MM" when the reset is not today; reset time omitted entirely when
  *   `resetsAt` is absent)
+ *
+ * `now` feeds the #860 waitable-window classification so message and error
+ * type are derived against the same instant (and tests can pin the clock).
+ * A waitable window renders through the rate-limited branch — its reset time
+ * is the actionable fact; "Out of credits" would misname a pause as a wallet
+ * failure.
  */
-export function formatRateLimitMessage(info) {
-    if (isBillingFailure(info)) {
+export function formatRateLimitMessage(info, now = Date.now()) {
+    if (isBillingFailure(info, now)) {
+        // #860 drift telemetry: when the ONLY reason this is terminal is an
+        // unrecognized window type, say so — the message is the one channel that
+        // reaches run output, logs, and `PhaseResult.error` on every display path.
+        const hint = unrecognizedWindowHint(info, now);
+        const suffix = hint ? ` (${hint})` : "";
         if (info.canUserPurchaseCredits === true) {
-            return "Out of credits — purchasable";
+            return `Out of credits — purchasable${suffix}`;
         }
         if (info.canUserPurchaseCredits === false) {
-            return "Out of credits — hard limit";
+            return `Out of credits — hard limit${suffix}`;
         }
-        return "Out of credits";
+        return `Out of credits${suffix}`;
     }
     if (info.resetsAt !== undefined) {
         return `Rate limited — resets at ${formatResetTime(info.resetsAt)}`;
@@ -182,10 +298,12 @@ export function formatRateLimitMessage(info) {
 /**
  * Construct the appropriate typed error from structured rate-limit info.
  * Billing/credits failures become a non-retryable {@link BillingError};
- * transient throttles become a retryable {@link RateLimitError}.
+ * transient throttles AND exhausted-but-reopening windows (#860) become a
+ * retryable {@link RateLimitError}. `now` pins the waitable-window check to
+ * one instant across message and classification.
  */
-export function createRateLimitError(info) {
-    const message = formatRateLimitMessage(info);
+export function createRateLimitError(info, now = Date.now()) {
+    const message = formatRateLimitMessage(info, now);
     const metadata = {
         resetsAt: info.resetsAt,
         rateLimitType: info.rateLimitType,
@@ -194,7 +312,7 @@ export function createRateLimitError(info) {
         canUserPurchaseCredits: info.canUserPurchaseCredits,
         hasChargeableSavedPaymentMethod: info.hasChargeableSavedPaymentMethod,
     };
-    return isBillingFailure(info)
+    return isBillingFailure(info, now)
         ? new BillingError(message, metadata)
         : new RateLimitError(message, metadata);
 }