mixdog 1.3.5 → 1.4.1

package/src/runtime/agent/orchestrator/providers/openai-ws-stream/event-switch.mjs

@@ -27,11 +27,22 @@ export function createWsEventSwitch({
     // already cleared the pre-stream watchdog and armed the single idle timer.
     // response.created is a MEANINGFUL frame, so it also satisfies the
     // first-meaningful watchdog (keepalive/metadata frames never reach here,
-    // so they never clear it). Semantic idle is not armed until actual model
-    // progress; transport-only reasoning heartbeats are bounded by the outer
-    // first-visible ceiling instead.
+    // so they never clear it). It is still metadata, not model output: it
+    // neither ends the first-output phase nor arms the semantic idle, and the
+    // agent sees it as transport.
     watchdogs.clearFirstMeaningful();
-    progress('semantic');
+    progress('transport');
+  }
+
+  // A tool item starting is model output: it resets the semantic-idle timer so
+  // long server-side tool latency after item-added (before any arg delta) is
+  // not mistaken for a silent stall. An empty reasoning or message item is
+  // progress only once the model has produced output; before that the silent
+  // thinking follows it.
+  function onItemAdded() {
+    const kind = response.toolInFlight ? 'tool' : watchdogs.semanticSeen() ? 'semantic' : null;
+    if (kind) watchdogs.bumpSemantic();
+    progress(kind ?? 'transport');
   }
 
   function onOutputTextDelta(delta) {
@@ -84,11 +95,7 @@ export function createWsEventSwitch({
       case 'response.output_item.added':
         response.noteItemAdded(event.item);
         reportStreamItemStart(onStreamItemStart, responsesItemStart(event.item));
-        // Item lifecycle is genuine progress: reset the semantic-idle timer so
-        // long server-side tool latency after item-added (before any arg
-        // delta) is not mistaken for a silent stall.
-        watchdogs.resetSemantic();
-        progress(response.toolInFlight ? 'tool' : 'semantic');
+        onItemAdded();
         break;
       case 'response.function_call_arguments.delta':
       case 'response.custom_tool_call_input.delta':
@@ -115,9 +122,10 @@ export function createWsEventSwitch({
         const kind = response.completeOutputItem(event.item);
         // A stream that names the phase only on the finished message.
         if (event.item?.type === 'message') reportStreamItemStart(onStreamItemStart, responsesItemStart(event.item));
-        // Item-done is genuine lifecycle progress — reset semantic idle so
-        // latency before the next item/args does not stall.
-        watchdogs.resetSemantic();
+        // A completed item (reasoning, message, tool call) is model output —
+        // it ends the first-output phase and resets semantic idle so latency
+        // before the next item/args does not stall.
+        watchdogs.bumpSemantic();
         progress(kind);
         break;
       }

package/src/runtime/agent/orchestrator/providers/openai-ws-stream.mjs

@@ -24,11 +24,13 @@ import {
   PROVIDER_SSE_IDLE_WATCHDOG_ENABLED,
   PROVIDER_WS_FIRST_MEANINGFUL_TIMEOUT_MS,
   PROVIDER_WS_SEMANTIC_IDLE_TIMEOUT_MS,
+  providerFirstOutputTimeoutMs,
 } from '../stall-policy.mjs';
 import { _wsErrLabel, WS_MAX_INCOMING_FRAME_BYTES } from './openai-ws-pool.mjs';
 import { createWsResponseState } from './openai-ws-response-state.mjs';
 import { createWsTextRelay } from './openai-ws-text-relay.mjs';
 import { createWsStreamWatchdogs } from './openai-ws-watchdogs.mjs';
+import { streamFirstOutputWindow } from './lib/first-output-window.mjs';
 import {
   enableSessionTransportTracking,
   disableSessionTransportTracking,
@@ -85,6 +87,7 @@ function resolveStreamTimeouts(_timeouts) {
     interChunkMs: _positiveInt(_timeouts?.interChunkMs, WS_INTER_CHUNK_MS),
     maxIncomingFrameBytes: _positiveInt(_timeouts?.maxIncomingFrameBytes, WS_MAX_INCOMING_FRAME_BYTES),
     firstMeaningfulMs: _positiveInt(_timeouts?.firstMeaningfulMs, PROVIDER_WS_FIRST_MEANINGFUL_TIMEOUT_MS),
+    firstOutputMs: _positiveInt(_timeouts?.firstOutputMs, providerFirstOutputTimeoutMs(semanticIdleMs)),
     semanticIdleMs,
     semanticIdleEnabled: PROVIDER_SSE_IDLE_WATCHDOG_ENABLED && semanticIdleMs > 0,
   };
@@ -112,7 +115,8 @@ export async function _streamResponse({
   if (socket?.readyState === WebSocket.OPEN) {
     markSessionTransportActivity(state?.sessionId);
   }
-  const { maxIncomingFrameBytes, ...timeouts } = resolveStreamTimeouts(_timeouts);
+  const { maxIncomingFrameBytes, firstOutputMs, ...timeouts } = resolveStreamTimeouts(_timeouts);
+  const firstOutput = streamFirstOutputWindow({ sessionId: state?.sessionId, onStreamDelta, timeoutMs: firstOutputMs });
   const streamingStart = Date.now();
   // Mid-stream retry classifier needs to distinguish "stream died before we
   // even saw response.created" from "stream died after we had a partial
@@ -182,6 +186,7 @@ export async function _streamResponse({
       streamingStart,
       currentModel: () => response.model,
       timeouts,
+      firstOutput,
       attachPartialState,
       fail,
     });
@@ -256,6 +261,7 @@ export async function _streamResponse({
     if (!handlers.attach()) return;
     watchdogs.armPreStream();
     watchdogs.armFirstMeaningful();
+    watchdogs.armFirstOutput();
     // No proactive client ping: Codex's Responses WebSocket uses the library
     // default (automatic pong replies, no periodic client ping). Incoming
     // frames remain bounded by the 300s stream idle timeout.

package/src/runtime/agent/orchestrator/providers/openai-ws-watchdogs.mjs

@@ -1,14 +1,18 @@
 /**
- * openai-ws-watchdogs.mjs — the four timers that bound one Responses WS
+ * openai-ws-watchdogs.mjs — the five timers that bound one Responses WS
  * stream, and what each one proves when it fires:
  *
  *   pre-stream      — no server event at all after response.create (a wedged
  *                     post-upgrade socket); cleared by ANY frame.
  *   first-meaningful — no response.created / content / tool-arg delta, even
  *                     while keepalive frames keep arriving; cleared once.
+ *   first-output    — no semantic output (reasoning, text, tool call) within
+ *                     the first-output window; metadata, empty items and
+ *                     keepalives never clear or extend it; cleared once.
  *   inter-chunk     — byte silence mid-stream; reset by EVERY frame.
- *   semantic idle   — deltas then silence (keepalives only); reset only by
- *                     meaningful output and item lifecycle.
+ *   semantic idle   — deltas then silence (keepalives only); armed by the
+ *                     first semantic output, then reset by meaningful output
+ *                     and item lifecycle.
  *
  * Every expiry hands a tagged error to `fail`, which owns terminalError, the
  * socket close and the settle; the timers never touch the Promise.
@@ -23,6 +27,8 @@ import { streamStalledError } from '../stall-policy.mjs';
  * @param {number} deps.streamingStart
  * @param {() => string} deps.currentModel
  * @param {{ preResponseCreatedMs: number, firstMeaningfulMs: number, interChunkMs: number, semanticIdleMs: number, semanticIdleEnabled: boolean }} deps.timeouts
+ * @param {ReturnType<typeof import('./lib/first-output-window.mjs').streamFirstOutputWindow>} deps.firstOutput
+ *   the logical request's first-output window
  * @param {(err: Error) => Error} deps.attachPartialState
  * @param {(err: Error, closeReason: string) => void} deps.fail
  */
@@ -32,6 +38,7 @@ export function createWsStreamWatchdogs({
   streamingStart,
   currentModel,
   timeouts,
+  firstOutput,
   attachPartialState,
   fail,
 }) {
@@ -90,23 +97,25 @@ export function createWsStreamWatchdogs({
       fail(err, 'inter_chunk_timeout');
     }, interChunkMs);
   };
+  // A semantic stall (first-output or idle window): partial-final recovery
+  // attaches the streamed partial state so a wedged FINAL no-tool summary can
+  // be accepted as partial-final success by the loop. pendingToolUse gates
+  // out mid-flight tools.
+  const failStalled = (event, timeoutMs) => {
+    traceWsTimeout(event, timeoutMs);
+    const err = streamStalledError('Responses WS', timeoutMs, {
+      emittedToolCall: !!midState?.emittedToolCall,
+    });
+    attachPartialState(err);
+    try {
+      err.wsCloseCode = 4000;
+    } catch {}
+    fail(err, event);
+  };
   const resetSemanticIdle = () => {
     if (!semanticIdleEnabled) return;
     if (semanticIdleTimer) clearTimeout(semanticIdleTimer);
-    semanticIdleTimer = setTimeout(() => {
-      traceWsTimeout('semantic_idle_timeout', semanticIdleMs);
-      const err = streamStalledError('Responses WS', semanticIdleMs, {
-        emittedToolCall: !!midState?.emittedToolCall,
-      });
-      // Partial-final recovery: attach streamed partial state so a wedged
-      // FINAL no-tool summary can be accepted as partial-final success by
-      // the loop. pendingToolUse gates out mid-flight tools.
-      attachPartialState(err);
-      try {
-        err.wsCloseCode = 4000;
-      } catch {}
-      fail(err, 'semantic_idle_timeout');
-    }, semanticIdleMs);
+    semanticIdleTimer = setTimeout(() => failStalled('semantic_idle_timeout', semanticIdleMs), semanticIdleMs);
     try {
       semanticIdleTimer.unref?.();
     } catch {}
@@ -164,24 +173,41 @@ export function createWsStreamWatchdogs({
         firstMeaningfulTimer.unref?.();
       } catch {}
     },
+    /** Fires if the logical request produces no semantic output by its
+     *  first-output deadline. Metadata (response.created / in_progress), empty
+     *  item lifecycle and keepalive frames never clear or extend it, and the
+     *  shorter semantic idle does not run before the first output, so a model
+     *  may think silently past the idle window. A request that already had
+     *  output has none: its stream runs under the semantic idle from its
+     *  first frame (resetIdle). */
+    armFirstOutput() {
+      if (!firstOutput.outputSeen && semanticIdleEnabled && firstOutput.timeoutMs > 0) {
+        firstOutput.arm(() => failStalled('first_output_timeout', firstOutput.timeoutMs));
+      }
+    },
     /** Called on EVERY parsed server event: any frame proves the socket is
      *  live. Also clears the pre-stream watchdog in case the first event is
-     *  not response.created. */
+     *  not response.created, and starts the semantic idle (once) for a
+     *  request that already had output. */
     resetIdle() {
       clearPreStream();
       resetInterChunk();
+      if (firstOutput.outputSeen && !semanticIdleTimer) resetSemanticIdle();
     },
-    /** Meaningful-output progress: text/reasoning/tool-arg deltas. The
-     *  first one also satisfies the first-meaningful watchdog. */
+    /** Meaningful-output progress: text/reasoning/tool output. The first one
+     *  also satisfies the first-meaningful watchdog and ends the first-output
+     *  phase. */
     bumpSemantic() {
       clearFirstMeaningful();
+      firstOutput.noteOutput();
       resetSemanticIdle();
     },
-    /** Item lifecycle progress (added/done) without a delta. */
-    resetSemantic: resetSemanticIdle,
+    /** Whether the model has produced semantic output on this stream. */
+    semanticSeen: () => firstOutput.outputSeen,
     /** response.created is meaningful on its own. */
     clearFirstMeaningful,
     clearAll() {
+      firstOutput.clear();
       if (idleTimer) clearTimeout(idleTimer);
       if (interChunkTimer) {
         clearTimeout(interChunkTimer);

package/src/runtime/agent/orchestrator/providers/provider-error-kind.mjs

@@ -5,6 +5,7 @@
 // to the older fields (httpStatus, responseFailed, providerError, SDK error
 // bodies, RPC status strings). Message text is consulted only for untyped
 // errors and only for unambiguous wordings.
+import { TIMEOUT_PHASE, isFirstByteTimeout } from '../../../shared/provider-timeout-phase.mjs';
 
 export const PROVIDER_ERROR_KINDS = Object.freeze([
   'overloaded',
@@ -391,6 +392,13 @@ const CODE_KINDS = new Map(
   }).flatMap(([kind, codes]) => codes.map((code) => [code, kind]))
 );
 const RESOURCE_EXHAUSTED = 'resource_exhausted';
+
+/** True when `code` is one of the provider error codes this module classifies
+ *  (rate/usage limits, quota, overload, server/transient, context length,
+ *  model not found, auth, policy, …): a known vocabulary word, never free text. */
+function isKnownProviderErrorCode(code) {
+  return typeof code === 'string' && (CODE_KINDS.has(code) || code === RESOURCE_EXHAUSTED);
+}
 // When several typed codes are present (an envelope type plus a specific
 // code), the most specific verdict wins.
 const KIND_RANK = [
@@ -435,7 +443,7 @@ const GATEWAY_ERROR_TYPE_CODES = Object.freeze({
 });
 
 /** The typed code a gateway `error_type` names, or null for an absent/unmapped one. */
-export function gatewayErrorTypeCode(errorType) {
+function gatewayErrorTypeCode(errorType) {
   const key = typeof errorType === 'string' ? errorType.trim().toLowerCase() : '';
   return key && Object.hasOwn(GATEWAY_ERROR_TYPE_CODES, key) ? GATEWAY_ERROR_TYPE_CODES[key] : null;
 }
@@ -718,6 +726,62 @@ export function providerErrorKind(err, options = {}) {
   return describe(kind, code || undefined);
 }
 
+// ── Retry reason, without server text ───────────────────────────────────────
+// A server error's free text can echo request content (prompt, tokens,
+// account ids), so neither the retry trace nor the reconnect status carries
+// it: only a fixed reason class derived from typed status/code, and a code
+// only when it is a known provider error code (an identifier-shaped value can
+// still be private, e.g. an account id in a `code` field).
+const SERVER_ERROR_CODES = new Set([
+  'server_error',
+  'api_error',
+  'internal',
+  'internal_error',
+  'unavailable',
+  'service_unavailable',
+]);
+// Responses failure codes the WS retry classifier acts on beyond the shared
+// provider vocabulary.
+const WS_RETRY_ERROR_CODES = new Set(['auth_context_expired', 'auth_expired']);
+
+/** The typed error code when it is a known provider error code; null otherwise. */
+export function safeRetryErrorCode(err) {
+  const code = providerErrorKind(err).code;
+  return isKnownProviderErrorCode(code) || WS_RETRY_ERROR_CODES.has(code) ? code : null;
+}
+
+const STALL_ERROR_NAMES = new Set(['StreamStalledError', 'StreamStalledAbortError']);
+
+/**
+ * One of rate_limited / overloaded / server_error / auth / first_response_timeout /
+ * stalled / other. The timeout classes read our own typed timeout stamps
+ * (name, code, timeoutPhase), never message text.
+ */
+export function retryReasonClass(err) {
+  const { kind, status } = providerErrorKind(err);
+  const code = safeRetryErrorCode(err);
+  if (kind === 'rate_limited' || kind === 'quota_exhausted' || status === 429) return 'rate_limited';
+  if (kind === 'overloaded' || status === 529) return 'overloaded';
+  if (kind === 'auth' || kind === 'permission' || status === 401 || status === 403) return 'auth';
+  // A token-refresh timeout is a sign-in problem, not a slow model.
+  if (err?.timeoutPhase === TIMEOUT_PHASE.AUTH) return 'auth';
+  if ((status >= 500 && status < 600) || (code && SERVER_ERROR_CODES.has(code))) return 'server_error';
+  if (err?.timeoutPhase === TIMEOUT_PHASE.IDLE || STALL_ERROR_NAMES.has(err?.name) || err?.code === 'ESTREAMSTALL') {
+    return 'stalled';
+  }
+  // `firstByteTimeout` is the stamp the Anthropic first-message and OpenAI
+  // WS/HTTP first-event watchdogs put on their errors.
+  if (
+    isFirstByteTimeout(err) ||
+    err?.firstByteTimeout === true ||
+    err?.name === 'ProviderTimeoutError' ||
+    err?.code === 'EPROVIDERTIMEOUT'
+  ) {
+    return 'first_response_timeout';
+  }
+  return 'other';
+}
+
 /** Kinds whose refusal no wait or replay can change: quota, plan and billing. */
 export const QUOTA_KINDS = new Set(['quota_exhausted', 'entitlement', 'billing']);
 /** Kinds that are deterministic refusals of this request (never replayed as-is). */

package/src/runtime/agent/orchestrator/providers/quota-reading.mjs

@@ -13,6 +13,8 @@ import {
 } from '../../../shared/provider-accounts.mjs';
 import { fetchOAuthUsageSnapshot } from './oauth-usage.mjs';
 import { getProvider } from './registry.mjs';
+import { modelProxyClientMode } from '../../../shared/model-proxy-mode.mjs';
+import { getModelProxyChannel } from './model-proxy-channel.mjs';
 
 const forcedReading = (routeInfo, providerObj) =>
   fetchOAuthUsageSnapshot(routeInfo, providerObj, () => {}, { force: true }).catch(() => null);
@@ -40,15 +42,15 @@ function readingServesModel(reading, model, useCredits) {
   return measured.length > 0 && measured.every((window) => window.usedPct < 100);
 }
 
-export async function providerQuotaUsable(providerName, model = '', { provider = getProvider(providerName) } = {}) {
+/** The model-independent, account-wide measurement: one forced usage reading
+ *  per roster account (or the single credential). Null for a provider that
+ *  reports no exhausted quota. */
+export async function measureProviderQuota(providerName, { provider } = {}) {
   // Only an account-pooled provider reports exhausted quota at all.
-  if (!ACCOUNT_PROVIDERS.includes(providerName)) return true;
+  if (!ACCOUNT_PROVIDERS.includes(providerName)) return null;
+  if (provider === undefined) provider = getProvider(providerName);
   const pool = readProviderAccountPool(providerName);
   const useCredits = pool.useCredits === true;
-  // Only this reading counts as evidence: an account whose forced reading
-  // failed or measured nothing for this model stays exhausted however its
-  // older record reads; the pool's own choice (selection, blocks) decides
-  // among the rest.
   if (pool.accounts.length > 0) {
     const readings = await Promise.all(
       pool.accounts.map((row) =>
@@ -58,13 +60,37 @@ export async function providerQuotaUsable(providerName, model = '', { provider =
         )
       )
     );
-    const unproven = new Set(
-      pool.accounts.filter((_, index) => !readingServesModel(readings[index], model, useCredits)).map((row) => row.id)
-    );
-    if (unproven.size === pool.accounts.length) return false;
-    return chooseProviderAccount(readProviderAccountPool(providerName), unproven, Date.now(), model) !== null;
+    return {
+      providerName,
+      useCredits,
+      accounts: pool.accounts.map((row, index) => ({ id: row.id, reading: readings[index] })),
+    };
   }
   // No roster: the single credential's fresh meter decides.
   const reading = await forcedReading({ provider: providerName, model: '' }, provider);
-  return readingServesModel(reading, model, useCredits);
+  return { providerName, useCredits, accounts: null, reading };
+}
+
+/** Whether `model` can be served per `measurement` (from measureProviderQuota).
+ *  Only the measurement counts as evidence: an account whose forced reading
+ *  failed or measured nothing for this model stays exhausted however its
+ *  older record reads; the pool's own choice (selection, blocks) decides
+ *  among the rest. */
+export function quotaMeasurementServesModel(measurement, model = '') {
+  if (!measurement) return true;
+  const { providerName, useCredits, accounts } = measurement;
+  if (!accounts) return readingServesModel(measurement.reading, model, useCredits);
+  const unproven = new Set(
+    accounts.filter((row) => !readingServesModel(row.reading, model, useCredits)).map((row) => row.id)
+  );
+  if (unproven.size === accounts.length) return false;
+  return chooseProviderAccount(readProviderAccountPool(providerName), unproven, Date.now(), model) !== null;
+}
+
+export async function providerQuotaUsable(providerName, model = '', { provider } = {}) {
+  // The PC owns the accounts in proxy mode; do not resolve a server provider.
+  if (modelProxyClientMode()) {
+    return (await getModelProxyChannel().request({ provider: providerName, method: 'quotaUsable', model })) === true;
+  }
+  return quotaMeasurementServesModel(await measureProviderQuota(providerName, { provider }), model);
 }

package/src/runtime/agent/orchestrator/providers/registry.mjs

@@ -70,6 +70,17 @@ let _initChain = Promise.resolve();
 let _inFlightPromise = null;
 let _inFlightSig = null;
 let _lastAppliedSig = null;
+// Settles when an initialization by the owning runtime first applies.
+let _markProvidersInitialized;
+const _providersInitialized = new Promise((resolve) => {
+  _markProvidersInitialized = resolve;
+});
+
+/** Read-only readiness: resolves once the owning runtime's provider
+ *  initialization has applied a config (never starts one). */
+export function providersInitialized() {
+  return _providersInitialized;
+}
 // Provider instances are process-global inside the daemon. Catalog
 // readers use this revision to share one raw model snapshot while still
 // rebuilding their cheap route/config projection after auth/config changes.
@@ -223,7 +234,14 @@ async function instantiateProvider(name, Ctor, cfg, proxyChannel = null) {
   return createAccountPoolProvider(name, () => wrapProviderAdmission(new Ctor(cfg), name));
 }
 
+let _initProvidersCalls = 0;
+/** Test seam: how many times initProviders was called in this process. */
+export function _initProvidersCallCountForTest() {
+  return _initProvidersCalls;
+}
+
 export async function initProviders(config, { signal = null } = {}) {
+  _initProvidersCalls += 1;
   throwIfAborted(signal);
   // Remote mode: provider availability and config are the PC's, never this
   // server's credential probes. No connected client fails here, clearly.
@@ -263,6 +281,7 @@ export async function initProviders(config, { signal = null } = {}) {
       if (_lastAppliedSig !== sig) _providerCatalogRevision += 1;
       _lastAppliedSig = sig;
       settle();
+      _markProvidersInitialized();
       return v;
     },
     (err) => {
@@ -452,6 +471,13 @@ function _scheduleOAuthSelfHeal(name) {
 // by its replacement account. When that account is not connected the lookup
 // misses like any other unconnected provider.
 const RETIRED_PROVIDER_ALIASES = Object.freeze({ 'opencode-go': 'opencode-go-oauth' });
+
+/** The instance registered under `name` right now, or null — a read-only
+ *  lookup (no lazy registration, unlike getProvider). */
+export function registeredProvider(name) {
+  return providers.get(name) || null;
+}
+
 export function getProvider(requestedName) {
   const name = Object.hasOwn(RETIRED_PROVIDER_ALIASES, requestedName)
     ? RETIRED_PROVIDER_ALIASES[requestedName]
@@ -658,6 +684,18 @@ export function refreshProviderCatalogsOnStartup() {
   return _startupCatalogRefreshPromise;
 }
 
+// Force-refresh only the named providers' catalogs, each bounded like the full
+// refresh. It leaves the 24h window, the catalog revision and every other
+// provider's cache alone.
+export function refreshProviderCatalogsFor(names) {
+  const pending = [];
+  for (const [name, provider] of availableProviderEntries()) {
+    const refreshFn = names.includes(name) ? providerCatalogRefreshFn(provider) : null;
+    if (refreshFn) pending.push(boundedCatalogRefresh(name, provider, refreshFn, 'catalog refresh'));
+  }
+  return Promise.allSettled(pending);
+}
+
 // Refresh the complete catalog at most once per 24h process window. The timer
 // above calls this automatically when the window expires; callers may bypass
 // that window after an explicit auth/config/model-refresh action.

package/src/runtime/agent/orchestrator/providers/retry-executor.mjs

@@ -4,7 +4,7 @@ import { PROVIDER_RETRY_JITTER_RATIO, createTimeoutSignal } from '../stall-polic
 import { readStreamOutcome } from './lib/stream-outcome.mjs';
 import { recycleLlmDispatcher } from '../../../shared/llm/http-agent.mjs';
 import { noteErrorUsage } from './lib/note-error-usage.mjs';
-import { retryReasonText, retryStatusLine } from '../../../shared/err-text.mjs';
+import { retryStatusLine, retryTimeoutText } from '../../../shared/err-text.mjs';
 import {
   TERMINAL_EDGE_STATUSES,
   boundedCauseChain,
@@ -13,7 +13,14 @@ import {
   isToolInputCut,
   retryAfterMsFromError,
 } from './retry-classification.mjs';
-import { DETERMINISTIC_KINDS, QUOTA_KINDS, errorHeaderValue, providerErrorKind } from './provider-error-kind.mjs';
+import {
+  DETERMINISTIC_KINDS,
+  QUOTA_KINDS,
+  errorHeaderValue,
+  providerErrorKind,
+  retryReasonClass,
+  safeRetryErrorCode,
+} from './provider-error-kind.mjs';
 import { adviceGatedRetry } from './retry-midstream.mjs';
 import {
   ModelFallbackTriggeredError,
@@ -35,7 +42,9 @@ export function createStreamSafetyStamps() {
       try {
         e.liveTextEmitted = true;
         e.unsafeToRetry = true;
-      } catch {}
+      } catch {
+        // the error object may be frozen; the live-text stamp is advisory
+      }
     }
     return e;
   };
@@ -44,7 +53,9 @@ export function createStreamSafetyStamps() {
       try {
         e.emittedToolCall = true;
         e.unsafeToRetry = true;
-      } catch {}
+      } catch {
+        // the error object may be frozen; the tool-call stamp is advisory
+      }
     }
     return e;
   };
@@ -313,6 +324,19 @@ function retryWaitMs(
   return retryAfterJitterRatio > 0 ? jitterDelayMs(wait, retryAfterJitterRatio, 'positive') : wait;
 }
 
+/** Fixed status phrases for a caller-classified retry reason. */
+const RETRY_REASON_TEXT = Object.freeze({
+  rate_limited: 'Rate limited by the provider',
+  overloaded: 'Provider overloaded',
+  server_error: 'Provider server error',
+  auth: 'Provider rejected the sign-in',
+  other: 'Connection interrupted',
+});
+
+// Timeout classes read our own typed timeout stamps (retryTimeoutText), so
+// their phrases carry the wait window.
+const TIMEOUT_REASON_CLASSES = new Set(['first_response_timeout', 'stalled']);
+
 /**
  * Display-only 'reconnecting' stage for one retry wait, so it reads as a
  * reconnect instead of a silent spinner. `attempt` is the attempt about to run
@@ -321,20 +345,28 @@ function retryWaitMs(
  */
 export function emitProviderRetryStage(
   onStageChange,
-  { attempt, maxAttempts, lastErr, delayMs, classifier = null, extra = null }
+  { attempt, maxAttempts, lastErr, delayMs, classifier = null, extra = null, reasonClass = null, providerLabel = null }
 ) {
   if (typeof onStageChange !== 'function') return;
   try {
-    const reason = retryReasonText(lastErr);
+    // The reason is a fixed phrase for a class (the caller's, else derived from
+    // the error's typed status/code), never the error's own text; an
+    // unrecognized class reads as `other`.
+    const cls = reasonClass == null ? retryReasonClass(lastErr) : reasonClass;
+    const fixedClass = Object.hasOwn(RETRY_REASON_TEXT, cls) || TIMEOUT_REASON_CLASSES.has(cls) ? cls : 'other';
+    const reason = TIMEOUT_REASON_CLASSES.has(fixedClass)
+      ? retryTimeoutText(lastErr, fixedClass, providerLabel)
+      : RETRY_REASON_TEXT[fixedClass];
     const waitMs = Math.max(0, Number(delayMs) || 0);
     onStageChange('reconnecting', {
       ...extra,
+      reasonClass: fixedClass,
       attempt,
       max: maxAttempts,
       waitMs,
       retryAt: Date.now() + waitMs,
       reason,
-      classifier: classifier || lastErr?.retryClassifier || lastErr?.code || null,
+      classifier: classifier || lastErr?.retryClassifier || safeRetryErrorCode(lastErr),
       message: retryStatusLine({ reason, attempt, maxAttempts, delayMs: waitMs }),
     });
   } catch {

package/src/runtime/agent/orchestrator/providers/statusline-route-meta.mjs

@@ -34,6 +34,12 @@ export function recordGatewayUsageEvent(summary) {
   return requireRouteMeta().recordGatewayUsageEvent(summary);
 }
 
+/** Resolves once every recorded usage event has been written; nothing was
+ *  recorded while the module is not loaded. */
+export function settleGatewayUsageWrites() {
+  return routeMeta ? routeMeta.settleGatewayUsageWrites() : Promise.resolve();
+}
+
 export function summarizeGatewayUsage(routeInfo, providerOut, compact = null, durationMs = null) {
   return requireRouteMeta().summarizeGatewayUsage(routeInfo, providerOut, compact, durationMs);
 }