@askalf/dario 6.0.12 → 6.0.14

package/dist/provider-cooldown.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Per-provider rate-limit cool-down for the failover chain (DEV-f66b131c).
+ *
+ * The chain used to have no memory. Every 429 was a fresh discovery, so with
+ * BOTH ends capped — a spent Claude 5h window and a 429-ing ChatGPT
+ * subscription — one request walked codex → claude → codex before dropping,
+ * and the next request did it again. 185 such lines in 38 minutes on
+ * 2026-09-02. That is the wrong shape twice over: at the moment quota is the
+ * scarce resource the chain spends TWICE as much of it discovering there is
+ * none, and whatever is cycling when a window rolls over consumes the fresh
+ * window ahead of legitimately queued work.
+ *
+ * Two rules, both enforced here so the request path can stay a straight line:
+ *
+ *   WITHIN a request  — an entry that already declined is never revisited
+ *                       ({@link canAttempt} against the attempted set).
+ *   ACROSS requests   — a 429 cools the entry for a bounded interval, honouring
+ *                       `retry-after` when the upstream sends one.
+ *
+ * When every entry is cooled the caller fails fast with one terminal verdict
+ * instead of a retry storm — see {@link allProvidersCooled}.
+ *
+ * Provider-granular, not entry-granular: a chain names MODELS
+ * (`gpt-5.6-sol,claude-sonnet-5`) but a 429 is a property of the ACCOUNT
+ * behind them, so cooling `codex` also cools every other codex slug in the
+ * chain, which is the correct blast radius.
+ *
+ * The clock is injectable so the whole thing is testable without sleeping.
+ */
+/** Cool-down applied when the upstream gives no `retry-after`. */
+export declare const DEFAULT_COOLDOWN_MS = 60000;
+/**
+ * Ceiling on any cool-down. An upstream is free to say "come back in 4 hours";
+ * honouring that literally would keep a provider parked long after a window
+ * reset we cannot observe. One re-probe per 15 minutes is cheap.
+ */
+export declare const MAX_COOLDOWN_MS: number;
+/** Machine-readable terminal verdict. Distinct from `pool exhausted` (which
+ *  implies a peer exists) and from the billing/credential classes. */
+export declare const ALL_PROVIDERS_RATE_LIMITED = "all-providers-rate-limited";
+/**
+ * `retry-after` as milliseconds. The header is either delta-seconds or an
+ * HTTP-date (RFC 9110 §10.2.3); both are accepted, anything else is null so
+ * the caller falls back to its default rather than trusting a parse it did not
+ * get. A date already in the past yields 0 — "retry now" — not a negative.
+ */
+export declare function parseRetryAfterMs(value: string | null | undefined, now?: number): number | null;
+/** A provider that declined, and for how long it should stay declined. */
+export declare class ProviderCooldowns {
+    private readonly until;
+    private readonly now;
+    private readonly defaultMs;
+    constructor(now?: () => number, defaultMs?: number);
+    /**
+     * Record a 429 (or an equivalent "not right now") for `provider`. Returns the
+     * cool-down actually applied, so the caller can put it in its one log line.
+     * A `retryAfterMs` of 0 is honoured as "retry now" and cools nothing.
+     */
+    note(provider: string, retryAfterMs?: number | null): number;
+    /** Clear on a success — a provider that just served is not rate-limited. */
+    clear(provider: string): void;
+    remainingMs(provider: string): number;
+    isCooled(provider: string): boolean;
+}
+/**
+ * May this request try `provider`? False when it already declined during THIS
+ * request (the codex → claude → codex revisit) or when it is cooling from an
+ * earlier one.
+ */
+export declare function canAttempt(provider: string, attempted: ReadonlySet<string>, cooldowns: ProviderCooldowns): boolean;
+/**
+ * Every named provider is cooling — the fail-fast condition. An EMPTY list is
+ * NOT "all cooled": nothing configured is a configuration answer, not a rate
+ * limit, and must keep its existing message.
+ */
+export declare function allProvidersCooled(providers: readonly string[], cooldowns: ProviderCooldowns): boolean;
+/** Longest remaining cool-down across `providers` — what to put in `retry-after`. */
+export declare function cooldownRetryAfterMs(providers: readonly string[], cooldowns: ProviderCooldowns): number;

package/dist/provider-cooldown.js

@@ -0,0 +1,120 @@
+/**
+ * Per-provider rate-limit cool-down for the failover chain (DEV-f66b131c).
+ *
+ * The chain used to have no memory. Every 429 was a fresh discovery, so with
+ * BOTH ends capped — a spent Claude 5h window and a 429-ing ChatGPT
+ * subscription — one request walked codex → claude → codex before dropping,
+ * and the next request did it again. 185 such lines in 38 minutes on
+ * 2026-09-02. That is the wrong shape twice over: at the moment quota is the
+ * scarce resource the chain spends TWICE as much of it discovering there is
+ * none, and whatever is cycling when a window rolls over consumes the fresh
+ * window ahead of legitimately queued work.
+ *
+ * Two rules, both enforced here so the request path can stay a straight line:
+ *
+ *   WITHIN a request  — an entry that already declined is never revisited
+ *                       ({@link canAttempt} against the attempted set).
+ *   ACROSS requests   — a 429 cools the entry for a bounded interval, honouring
+ *                       `retry-after` when the upstream sends one.
+ *
+ * When every entry is cooled the caller fails fast with one terminal verdict
+ * instead of a retry storm — see {@link allProvidersCooled}.
+ *
+ * Provider-granular, not entry-granular: a chain names MODELS
+ * (`gpt-5.6-sol,claude-sonnet-5`) but a 429 is a property of the ACCOUNT
+ * behind them, so cooling `codex` also cools every other codex slug in the
+ * chain, which is the correct blast radius.
+ *
+ * The clock is injectable so the whole thing is testable without sleeping.
+ */
+/** Cool-down applied when the upstream gives no `retry-after`. */
+export const DEFAULT_COOLDOWN_MS = 60_000;
+/**
+ * Ceiling on any cool-down. An upstream is free to say "come back in 4 hours";
+ * honouring that literally would keep a provider parked long after a window
+ * reset we cannot observe. One re-probe per 15 minutes is cheap.
+ */
+export const MAX_COOLDOWN_MS = 15 * 60_000;
+/** Machine-readable terminal verdict. Distinct from `pool exhausted` (which
+ *  implies a peer exists) and from the billing/credential classes. */
+export const ALL_PROVIDERS_RATE_LIMITED = 'all-providers-rate-limited';
+/**
+ * `retry-after` as milliseconds. The header is either delta-seconds or an
+ * HTTP-date (RFC 9110 §10.2.3); both are accepted, anything else is null so
+ * the caller falls back to its default rather than trusting a parse it did not
+ * get. A date already in the past yields 0 — "retry now" — not a negative.
+ */
+export function parseRetryAfterMs(value, now = Date.now()) {
+    if (value == null)
+        return null;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return null;
+    if (/^\d+$/.test(trimmed))
+        return Math.min(Number(trimmed) * 1000, MAX_COOLDOWN_MS);
+    const at = Date.parse(trimmed);
+    if (Number.isNaN(at))
+        return null;
+    return Math.min(Math.max(at - now, 0), MAX_COOLDOWN_MS);
+}
+/** A provider that declined, and for how long it should stay declined. */
+export class ProviderCooldowns {
+    until = new Map();
+    now;
+    defaultMs;
+    constructor(now = () => Date.now(), defaultMs = DEFAULT_COOLDOWN_MS) {
+        this.now = now;
+        this.defaultMs = defaultMs;
+    }
+    /**
+     * Record a 429 (or an equivalent "not right now") for `provider`. Returns the
+     * cool-down actually applied, so the caller can put it in its one log line.
+     * A `retryAfterMs` of 0 is honoured as "retry now" and cools nothing.
+     */
+    note(provider, retryAfterMs) {
+        const ms = retryAfterMs == null ? this.defaultMs : Math.min(Math.max(retryAfterMs, 0), MAX_COOLDOWN_MS);
+        this.until.set(provider, this.now() + ms);
+        return ms;
+    }
+    /** Clear on a success — a provider that just served is not rate-limited. */
+    clear(provider) {
+        this.until.delete(provider);
+    }
+    remainingMs(provider) {
+        const at = this.until.get(provider);
+        if (at == null)
+            return 0;
+        const left = at - this.now();
+        if (left <= 0) {
+            // Expired entries are dropped on read; nothing else sweeps this map and
+            // a long-lived proxy would otherwise accumulate one entry per provider
+            // forever (bounded, but pointlessly).
+            this.until.delete(provider);
+            return 0;
+        }
+        return left;
+    }
+    isCooled(provider) {
+        return this.remainingMs(provider) > 0;
+    }
+}
+/**
+ * May this request try `provider`? False when it already declined during THIS
+ * request (the codex → claude → codex revisit) or when it is cooling from an
+ * earlier one.
+ */
+export function canAttempt(provider, attempted, cooldowns) {
+    return !attempted.has(provider) && !cooldowns.isCooled(provider);
+}
+/**
+ * Every named provider is cooling — the fail-fast condition. An EMPTY list is
+ * NOT "all cooled": nothing configured is a configuration answer, not a rate
+ * limit, and must keep its existing message.
+ */
+export function allProvidersCooled(providers, cooldowns) {
+    return providers.length > 0 && providers.every(p => cooldowns.isCooled(p));
+}
+/** Longest remaining cool-down across `providers` — what to put in `retry-after`. */
+export function cooldownRetryAfterMs(providers, cooldowns) {
+    return providers.reduce((max, p) => Math.max(max, cooldowns.remainingMs(p)), 0);
+}

package/dist/proxy.js

@@ -28,6 +28,7 @@ import { RequestQueue, QueueFullError, QueueTimeoutError, DEFAULT_MAX_CONCURRENT
 import { redactSecrets } from './redact.js';
 import { BAKED_BASE_MODELS, withLongContextVariants, buildOpenAIModelsList, getModelCatalog, getCachedBases, resolveAliasAgainst, prewarmModelCatalog, retryModelCatalogNow, isSuspendedModel } from './model-catalog.js';
 import { classifyUpstreamRejection, diagnosticSnippet } from './upstream-rejection.js';
+import { ProviderCooldowns, canAttempt, allProvidersCooled, cooldownRetryAfterMs, parseRetryAfterMs, ALL_PROVIDERS_RATE_LIMITED, } from './provider-cooldown.js';
 const ANTHROPIC_API = 'https://api.anthropic.com';
 const DEFAULT_PORT = 3456;
 const MAX_BODY_BYTES = 10 * 1024 * 1024; // 10 MB — generous for large prompts, prevents abuse
@@ -1328,6 +1329,10 @@ export async function startProxy(opts = {}) {
     // Per-alias request counts for GET /codex — the pool has requestCount per
     // account; the codex accounts had nothing until now.
     const codexRequestCounts = new Map();
+    // Rate-limit memory for the failover chain (DEV-f66b131c). Process-wide and
+    // deliberately NOT per-request: the point is that request #269 does not
+    // re-discover the limit #267 already found. Cleared on any success.
+    const providerCooldowns = new ProviderCooldowns();
     // Overage-guard (v4.1, dario#288). Resolved from opts with built-in
     // defaults (enabled=true, behavior='halt', cooldown=30min, notifyOs=true)
     // so an opts-less proxy still gets protection. The notifier is wired
@@ -1828,9 +1833,14 @@ export async function startProxy(opts = {}) {
      * a silently swapped model family is precisely the surprise this project
      * exists to avoid.
      */
-    const tryCodexPoolFallback = async (req, res, body, fallbackModels, shape, why) => {
+    const tryCodexPoolFallback = async (req, res, body, fallbackModels, shape, why, attempted) => {
         if (fallbackModels.length === 0)
             return false;
+        // Never a second codex attempt in the same request, and never one while it
+        // is cooling from an earlier 429. This is the revisit the 20:13:40 log
+        // sequence shows: codex -> claude -> codex, all inside request #267.
+        if (!canAttempt('codex', attempted, providerCooldowns))
+            return false;
         if (!(await hasAnyCodexAccount().catch(() => false)))
             return false;
         const stored = await selectCodexAccount().catch(() => null);
@@ -1852,6 +1862,7 @@ export async function startProxy(opts = {}) {
             return false;
         console.log(`[dario] #${requestCount} ${why} → codex account ${creds.alias} as ${fallbackModel}`);
         requestCount++;
+        attempted.add('codex');
         // If an api-key backend could ALSO serve this request, let the subscription
         // decline a 429/5xx rather than answer with it, and report not-served so the
         // caller falls through to that backend. This helper's contract has always
@@ -1862,7 +1873,15 @@ export async function startProxy(opts = {}) {
         // With NO next option, do not defer: the real upstream error is more useful
         // to the client than replacing it with a generic 503.
         const hasNextOption = openaiBackend !== null && shape === 'openai';
-        return await forwardToCodex(req, res, fallbackBody, creds, corsOrigin, { ...SECURITY_HEADERS, 'x-dario-pool-fallback': fallbackModel }, upstreamTimeoutMs, verbose, shape, fetch, hasNextOption);
+        const served = await forwardToCodex(req, res, fallbackBody, creds, corsOrigin, { ...SECURITY_HEADERS, 'x-dario-pool-fallback': fallbackModel }, upstreamTimeoutMs, verbose, shape, fetch, hasNextOption, undefined, 
+        // Only a rate limit cools the provider. A 5xx or a transport failure is
+        // an outage, not quota — cooling it would park a provider that may be
+        // back on the next request, which is the opposite of the fix.
+        (d) => { if (d.status === 429)
+            providerCooldowns.note('codex', d.retryAfterMs); });
+        if (served)
+            providerCooldowns.clear('codex');
+        return served;
     };
     /**
      * Mid-flight 429, no peer account left to retry — the pool is genuinely
@@ -1885,8 +1904,8 @@ export async function startProxy(opts = {}) {
      * bug structurally impossible to reintroduce: a future third call site gets
      * this by construction, not by remembering to copy six lines correctly.
      */
-    const attemptPoolFallbackOn429 = async (req, res, body, isOpenAI) => {
-        if (await tryCodexPoolFallback(req, res, body, poolFallbackModels, isOpenAI ? 'openai' : 'anthropic', 'pool exhausted mid-flight (429, no peer)')) {
+    const attemptPoolFallbackOn429 = async (req, res, body, isOpenAI, attempted) => {
+        if (await tryCodexPoolFallback(req, res, body, poolFallbackModels, isOpenAI ? 'openai' : 'anthropic', 'pool exhausted mid-flight (429, no peer)', attempted)) {
             return true;
         }
         if (isOpenAI && poolFallbackModel && openaiBackend) {
@@ -2434,6 +2453,10 @@ export async function startProxy(opts = {}) {
             // form gives the declared type without seeding a narrowing.
             let poolAccount = null;
             let accessToken = '';
+            // Providers this ONE request has already asked. Paired with the
+            // process-wide cool-downs: the set stops a revisit inside the request,
+            // the cool-downs stop the next request repeating the discovery.
+            const attemptedProviders = new Set();
             /**
              * Take a Claude pool account for this request. Returns false when it has
              * already answered the client (empty or fully drained pool with no viable
@@ -2464,6 +2487,35 @@ export async function startProxy(opts = {}) {
                         message: 'all accounts are rate-limited or in auth cool-down; retry shortly',
                     }));
             };
+            /**
+             * Terminal verdict for DEV-f66b131c: every provider that could serve this
+             * request is inside a 429 cool-down, so there is nothing left to try and
+             * no reason to spend an upstream attempt proving it. ONE log line and one
+             * response — the defect being fixed is a three-line-per-request storm.
+             *
+             * 429 rather than the 503 `writePoolUnavailable` gives, and distinct from
+             * `pool exhausted` (which implies a peer exists): this IS a rate limit, it
+             * self-clears, and `retry-after` says when. The
+             * `x-dario-upstream-rejection` marker is the same channel the billing and
+             * credential classes use, so the platform-side sustained-fallback tracker
+             * reads one field for all of them.
+             */
+            const writeAllProvidersRateLimited = (providers) => {
+                const retryAfterSec = Math.max(1, Math.ceil(cooldownRetryAfterMs(providers, providerCooldowns) / 1000));
+                console.log(`[dario] #${requestCount} ${ALL_PROVIDERS_RATE_LIMITED} (${providers.join('+')}) — no attempt made, retry in ${retryAfterSec}s`);
+                res.writeHead(429, {
+                    ...JSON_HEADERS,
+                    'retry-after': String(retryAfterSec),
+                    'x-dario-upstream-rejection': ALL_PROVIDERS_RATE_LIMITED,
+                });
+                res.end(JSON.stringify({
+                    error: {
+                        type: 'rate_limit_error',
+                        message: `All configured providers (${providers.join(', ')}) are rate-limited; retry in ${retryAfterSec}s.`,
+                    },
+                    reason: ALL_PROVIDERS_RATE_LIMITED,
+                }));
+            };
             const selectPoolAccount = () => {
                 if (upstreamApiKey) {
                     // Per-token API-key mode: no OAuth, no pool selection. `poolAccount`
@@ -2752,8 +2804,19 @@ export async function startProxy(opts = {}) {
                         const claudeTarget = pickClaudeTarget(poolFallbackModels, codexModels, getCachedBases(), (m) => resolveClaudeAlias(applyModelAlias(m, modelAliases) ?? m));
                         const claudeTargetModel = claudeTarget?.model ?? null;
                         const canDefer = claudeTarget !== null && pool.size > 0 && !upstreamApiKey;
+                        // DEV-f66b131c: an account still inside its 429 cool-down is not
+                        // asked again. Skipping straight to the Claude half of the chain is
+                        // the whole saving — the doomed attempt was spending quota on BOTH
+                        // accounts to rediscover a limit the previous request already found.
+                        const codexAvailable = canAttempt('codex', attemptedProviders, providerCooldowns);
+                        if (!codexAvailable && !canDefer) {
+                            // Nothing else in the chain can pick this up, so an attempt could
+                            // only rediscover the limit. One verdict, no upstream request.
+                            writeAllProvidersRateLimited(['codex']);
+                            return;
+                        }
                         const codexReq = requestCount;
-                        const served = await forwardToCodex(req, res, body, codexCreds, corsOrigin, SECURITY_HEADERS, upstreamTimeoutMs, verbose, isOpenAI ? 'openai' : 'anthropic', fetch, canDefer, 
+                        const served = codexAvailable && await forwardToCodex(req, res, body, codexCreds, corsOrigin, SECURITY_HEADERS, upstreamTimeoutMs, verbose, isOpenAI ? 'openai' : 'anthropic', fetch, canDefer, 
                         // Before this hook a codex request left no trace: nothing in
                         // /analytics, nothing in the request log, no per-account count.
                         // The dock (and anyone reading /analytics) saw a proxy that
@@ -2780,9 +2843,26 @@ export async function startProxy(opts = {}) {
                                 status: o.status, latency_ms: o.latencyMs, in_tokens: o.inputTokens, out_tokens: o.outputTokens,
                                 claim: CODEX_CLAIM, bucket: 'subscription', account: o.alias, stream: o.stream,
                             });
-                        });
-                        if (served)
+                        }, 
+                        // Cool codex on a rate limit only — a 5xx or an unreachable backend
+                        // is an outage, and parking a provider for that would keep it out
+                        // of the chain while it was already coming back.
+                        (d) => { if (d.status === 429)
+                            providerCooldowns.note('codex', d.retryAfterMs); });
+                        if (served) {
+                            // A provider that just served is not rate-limited.
+                            providerCooldowns.clear('codex');
+                            return;
+                        }
+                        if (codexAvailable)
+                            attemptedProviders.add('codex');
+                        // Both ends of the chain limited — the case this ticket is about.
+                        // Fail fast with the machine-readable verdict instead of handing the
+                        // request on to a Claude pool that is itself cooling.
+                        if (providerCooldowns.isCooled('codex') && providerCooldowns.isCooled('claude')) {
+                            writeAllProvidersRateLimited(['codex', 'claude']);
                             return;
+                        }
                         const swapped = buildPoolFallbackBody(body, claudeTargetModel);
                         if (!swapped) {
                             res.writeHead(503, { 'Content-Type': 'application/json', ...SECURITY_HEADERS });
@@ -2836,7 +2916,12 @@ export async function startProxy(opts = {}) {
             // response carries `x-dario-pool-fallback` — a substituted model must
             // never be silent. GPT-bound requests never reach here (the routing
             // block above already forwarded them; they don't need the pool).
-            if (!upstreamApiKey && !poolAccount && await tryCodexPoolFallback(req, res, body, poolFallbackModels, isOpenAI ? 'openai' : 'anthropic', 'pool exhausted')) {
+            // Selection returns null only for an empty pool or all-account auth-cooldown.
+            // Genuine rate limits return an account and are cooled from the upstream 429.
+            if (!upstreamApiKey && !poolAccount) {
+                attemptedProviders.add('claude');
+            }
+            if (!upstreamApiKey && !poolAccount && await tryCodexPoolFallback(req, res, body, poolFallbackModels, isOpenAI ? 'openai' : 'anthropic', 'pool exhausted', attemptedProviders)) {
                 return;
             }
             // `isOpenAI` is REQUIRED here and was not, before v6.0.0 — the selector's
@@ -2864,6 +2949,12 @@ export async function startProxy(opts = {}) {
             // would fall through to the Claude path with no account and an empty
             // bearer token, turning a clean 503 into a confusing upstream 401.
             if (!upstreamApiKey && !poolAccount) {
+                // A chain where every entry is cooling is a rate limit, not a
+                // misconfiguration — say so in the machine-readable way, once.
+                if (allProvidersCooled(poolFallbackModels.length > 0 ? ['codex', 'claude'] : ['claude'], providerCooldowns)) {
+                    writeAllProvidersRateLimited(poolFallbackModels.length > 0 ? ['codex', 'claude'] : ['claude']);
+                    return;
+                }
                 console.log(`[dario] #${requestCount} pool exhausted and no fallback provider could serve ${poolFallbackModels.join(', ') || '(none configured)'}`);
                 writePoolUnavailable();
                 return;
@@ -3658,7 +3749,16 @@ export async function startProxy(opts = {}) {
                         // attemptPoolFallbackOn429 below, so the file goes back to having
                         // exactly ONE copy of this logic instead of two near-identical ones
                         // — which is the exact shape of bug this incident already was.
-                        if (await attemptPoolFallbackOn429(req, res, body, isOpenAI)) {
+                        // The Claude half is out of quota for this request AND for the next
+                        // one — cool it here, honouring the upstream `retry-after` when it
+                        // sent one, so the following request does not re-walk the chain.
+                        attemptedProviders.add('claude');
+                        providerCooldowns.note('claude', parseRetryAfterMs(upstream.headers.get('retry-after')));
+                        if (await attemptPoolFallbackOn429(req, res, body, isOpenAI, attemptedProviders)) {
+                            return;
+                        }
+                        if (allProvidersCooled(['codex', 'claude'], providerCooldowns)) {
+                            writeAllProvidersRateLimited(['codex', 'claude']);
                             return;
                         }
                         const enriched = enrich429(peekedBody, upstream.headers);
@@ -3776,7 +3876,14 @@ export async function startProxy(opts = {}) {
                     // translation (OpenAI-shape clients) went into finalBody, never back
                     // into body. See attemptPoolFallbackOn429's doc comment for why this
                     // is one shared function rather than an inline copy.
-                    if (await attemptPoolFallbackOn429(req, res, body, isOpenAI)) {
+                    // Same bookkeeping as the other mid-flight site — see there.
+                    attemptedProviders.add('claude');
+                    providerCooldowns.note('claude', parseRetryAfterMs(upstream.headers.get('retry-after')));
+                    if (await attemptPoolFallbackOn429(req, res, body, isOpenAI, attemptedProviders)) {
+                        return;
+                    }
+                    if (allProvidersCooled(['codex', 'claude'], providerCooldowns)) {
+                        writeAllProvidersRateLimited(['codex', 'claude']);
                         return;
                     }
                     const errBody = await upstream.text().catch(() => '');
@@ -3813,6 +3920,8 @@ export async function startProxy(opts = {}) {
                 // so its consecutive-failure counter resets. dario#234.
                 if (poolAccount && upstream.status >= 200 && upstream.status < 300) {
                     pool.clearAuthFailure(poolAccount.alias);
+                    // Served — whatever cooled this provider has passed.
+                    providerCooldowns.clear('claude');
                 }
                 break;
             } // end dispatchLoop: while (true)

package/dist/serving-probe.d.ts

@@ -1,120 +1,35 @@
-/**
- * serving-probe.ts — the "can dario actually serve a request?" check.
- *
- * WHY THIS EXISTS (dario#905, dario#921)
- *
- * dario's existing health surfaces are both STRUCTURAL — they inspect state,
- * they never prove anything end-to-end:
- *
- *   /livez   the HTTP server is accepting connections. Always 200.
- *   /health  credentials/pool look sane: token not expired, refresh not broken,
- *            accounts not all in auth-cooldown, queue snapshot attached.
- *
- * Neither can catch the failure class that actually took a user down for ~14h
- * across four episodes (#905): dario looking perfectly healthy from the outside
- * while every real request failed. The reporter's remediation was an external
- * watchdog that sends a real inference call and restarts the service when it
- * doesn't come back — i.e. the user had to write the liveness check dario
- * should own. This module is that check, brought in-house.
- *
- * It also covers a class /health provably cannot see: an account whose token is
- * unexpired and refreshable (so `status: healthy`) but whose accountUuid has
- * drifted, so upstream 401s every request. Structural inspection says fine;
- * only a round-trip says otherwise.
- *
- * WHAT IT PROVES, AND WHAT IT DELIBERATELY DOES NOT
- *
- * The probe is a minimal `POST /v1/messages` (max_tokens 1) sent DIRECTLY to
- * api.anthropic.com with the same auth the request path uses — pool bearer, or
- * `x-api-key` in upstream-API-key mode. That proves: a token can be acquired,
- * the network path is up, and upstream accepts our credential.
- *
- * It deliberately does NOT go through dario's own proxy path:
- *   - No recursion, no self-deadlock, no port/auth assumptions.
- *   - It must not take a concurrency slot. A probe that queues behind real
- *     traffic would report "unhealthy" during a legitimate burst and hand a
- *     watchdog a reason to restart a busy-but-fine dario. Slot exhaustion is
- *     covered instead by `queue.saturatedSince` (request-queue.ts), which is
- *     free, needs no tokens, and cannot false-positive on a short burst.
- *
- * So: the probe covers the credential/network axis, the queue snapshot covers
- * the concurrency axis. Neither claims to cover the transform path.
- *
- * COST AND EXPOSURE
- *
- * A probe is a real billed request. Three guards, all load-bearing:
- *   1. OPT-IN. Only runs when a caller explicitly asks (`/health?probe=1`).
- *      A plain /health never spends a token — existing docker healthchecks and
- *      uptime monitors keep their current cost profile, which is zero.
- *   2. TRUSTED CALLERS ONLY. proxy.ts honours `?probe=1` only for callers that
- *      already pass shouldDiscloseHealthInternals. A world-readable /health
- *      behind a Cloudflare tunnel bypass must not be a button the internet can
- *      press to spend the operator's tokens.
- *   3. CACHED + SINGLE-FLIGHTED. Results are reused for `ttlMs` (default 60s)
- *      and concurrent callers share one in-flight request, so a monitor polling
- *      every second still costs at most one probe per minute.
- *
- * VERDICT SEMANTICS — why 429 is NOT a failure
- *
- * `ok` answers "would a restart or an alert help?", not "did the call return
- * 200". Rate-limited (429) and upstream-overloaded (529) are healthy states:
- * dario is working, the answer is legitimately "not right now", and a watchdog
- * that restarts on them just thrashes. That is the same lesson /livez already
- * encodes in proxy.ts — a shared-refresh-family outage once had dario restart
- * -looping for 4h+ because the healthcheck keyed on a condition a restart
- * cannot fix. Auth rejection, 5xx, network failure and timeout DO set ok=false.
- */
-/** Cheapest family, and the one doctor's own probe already uses. */
 export declare const DEFAULT_PROBE_MODEL = "claude-haiku-4-5";
 export declare const DEFAULT_PROBE_TTL_MS = 60000;
 export declare const DEFAULT_PROBE_TIMEOUT_MS = 15000;
-/**
- * Why the round-trip ended the way it did. Carried on both verdicts so an
- * operator reading a green probe can still tell "served" from "rate-limited".
- */
-export type ProbeReason = 'served' | 'rate-limited' | 'upstream-overloaded' | 'no-token' | 'auth-rejected' | 'upstream-error' | 'timeout' | 'network-error';
+export type ProbeReason = 'served' | 'billing-required' | 'rate-limited' | 'upstream-overloaded' | 'no-token' | 'auth-rejected' | 'upstream-error' | 'timeout' | 'network-error';
 export interface ProbeResult {
-    /** False only for conditions where dario is the problem — see module header. */
     ok: boolean;
     reason: ProbeReason;
-    /** Epoch ms the round-trip completed. */
     checkedAt: number;
-    /** Wall time of the round-trip, including token acquisition. */
     latencyMs: number;
     model: string;
-    /** Upstream HTTP status, when upstream answered at all. */
     status?: number;
-    /** Short failure detail. Never carries a token or a raw body. */
     detail?: string;
 }
 export interface ProbeDeps {
     fetchImpl?: typeof fetch;
-    /** OAuth bearer source. Ignored when upstreamApiKey is set. */
     getToken?: () => Promise<string>;
-    /** Per-token API mode — forwarded as x-api-key, mirroring request-path auth. */
     upstreamApiKey?: string;
     now?: () => number;
     model?: string;
     timeoutMs?: number;
     ttlMs?: number;
 }
-/**
- * Map an upstream HTTP status onto a verdict. Pure, so the whole policy
- * ("which statuses mean dario is broken") is testable without a network.
- */
+export declare function classifyProbeResponse(status: number, body?: string): {
+    ok: boolean;
+    reason: ProbeReason;
+    detail?: string;
+};
+/** Backward-compatible status-only classifier; body-aware callers use classifyProbeResponse. */
 export declare function classifyProbeStatus(status: number): {
     ok: boolean;
     reason: ProbeReason;
 };
-/**
- * The cached verdict, refreshing it when stale. Never throws — a health
- * surface that can 500 is worse than useless, so every failure path becomes a
- * `ok: false` verdict with a reason instead of an exception.
- *
- * Concurrent callers past the TTL share one in-flight probe; the loser of the
- * race gets the same result rather than sending a second billed request.
- */
 export declare function getServingProbe(deps?: ProbeDeps): Promise<ProbeResult>;
-/** Age of the cached verdict, for the `ageMs` field callers see. */
 export declare function probeAgeMs(result: ProbeResult, now: number): number;
 export declare function _resetServingProbeForTest(): void;