@skaile/workspaces 3.7.3 → 3.8.1

package/dist/bridge/drivers/claude-sdk.js

@@ -2,7 +2,7 @@ import { scrubPoisonedTranscript, resolveClaudeConfigDir, SUPPORTED_CLOUDS, buil
 import { dispatchCapability } from '../../chunk-RRVQAE5D.js';
 import { fetchProviderModels } from '../../chunk-V34ZEXSE.js';
 import { AuthError, classifyClaudeSdkError, reclassifyAuthAsAccountUnavailable, AccountUnavailableError } from '../../chunk-GAH4YRCI.js';
-import { BUILTIN_DRIVER_CATALOG, AgentDriver, getBridgeLogger } from '../../chunk-ML6OHA3S.js';
+import { BUILTIN_DRIVER_CATALOG, AgentDriver, getBridgeLogger } from '../../chunk-5YIGODSZ.js';
 import '../../chunk-6E6PKKAD.js';
 import '../../chunk-AZPXCHDK.js';
 import '../../chunk-F3HNW354.js';
@@ -159,7 +159,12 @@ if (typeof globalThis.require === "undefined") {
   }
 }
 function freshRetryBudget() {
-  return { staleResume: false, poison: false, auth: false, queryEnded: false };
+  return { staleResume: false, poison: false, auth: false, queryEnded: false, limit: false };
+}
+function isSeatCapacityFailure(detail, subtype) {
+  if (detail.category !== "rate_limit") return false;
+  if (subtype === "error_max_budget_usd") return false;
+  return detail.statusCode !== 529;
 }
 var QueryEndedBeforeTurnError = class extends Error {
   constructor(message) {
@@ -178,6 +183,23 @@ function firstMessageStallMs() {
   const value = Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_FIRST_MESSAGE_STALL_MS;
   return Math.min(value, turnStallMs());
 }
+var CLI_AUTH_RENDER_MARKERS = [
+  "failed to authenticate",
+  "api error:",
+  "authentication_error",
+  "not logged in",
+  "please run /login",
+  "oauth authentication is currently not supported"
+];
+function isCliAuthRenderText(text) {
+  const lower = text.toLowerCase();
+  return CLI_AUTH_RENDER_MARKERS.some((marker) => lower.includes(marker));
+}
+var DEFAULT_ERROR_RESULT_GRACE_MS = 5e3;
+function errorResultGraceMs() {
+  const raw = Number(process.env.SKAILE_ERROR_RESULT_GRACE_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_ERROR_RESULT_GRACE_MS;
+}
 var RECYCLE_TURNS_FRACTION = 0.8;
 var MIN_RECYCLE_HEADROOM = 5;
 var PushableInputStream = class {
@@ -241,6 +263,16 @@ var ClaudeSdkDriver = class extends AgentDriver {
   emittedSanitizedLen = 0;
   /** Set once the streaming text of the current message classifies as a self-healable auth render. */
   suppressingAuthStream = false;
+  /**
+   * The auth render this attempt dropped on the promise that a self-heal would
+   * retry — the evidence {@link handleResultErrorPayload} otherwise lacks when
+   * the SDK reports the same 401 as an `is_error` result with an empty
+   * `errors[]`. Written only through {@link stashSuppressedAuthRender}, which
+   * applies a stricter test than suppression does; see its docblock. Cleared at
+   * both ends of {@link runPrompt}, so it can only ever describe the turn that
+   * is failing.
+   */
+  suppressedAuthRenderText = null;
   /** Active query — stays alive between turns (streaming input mode). */
   query = null;
   /**
@@ -282,6 +314,12 @@ var ClaudeSdkDriver = class extends AgentDriver {
   lastSdkMessageAt = 0;
   /** Armed while a turn is in flight; trips when the SDK goes silent for too long. */
   turnStallTimer = null;
+  /**
+   * Armed only while an `is_error` result waits for its follow-up iterator
+   * throw; fails the turn if that throw never lands. Cleared at every turn
+   * start and settle site so it can never fire into a later turn.
+   */
+  errorResultGraceTimer = null;
   /**
    * Mirror of the in-flight {@link prompt} call's auth retry budget: `false`
    * while the `onAuthError` self-heal is still available, `true` once it has
@@ -292,6 +330,52 @@ var ClaudeSdkDriver = class extends AgentDriver {
    * reset elsewhere — the next call's set is the only legitimate transition.
    */
   authSelfHealUsed = false;
+  /**
+   * Mirror of the in-flight turn's seat-failover budget — same contract as
+   * {@link authSelfHealUsed}, for the `onLimitBlocked` path.
+   */
+  limitFailoverUsed = false;
+  /**
+   * Set when THIS attempt saw an upstream usage-limit rejection: either the
+   * SDK's `rate_limit_event` telemetry with `status: "rejected"`, or an error
+   * result the classifier calls `rate_limit`.
+   *
+   * The telemetry is the load-bearing half. A subscription ceiling arrives as
+   * `{"status":"rejected","type":"five_hour"}` followed by an error result
+   * whose text ("You've hit your session limit · resets 9:50am") matches none
+   * of the classifier's rate-limit keywords — so without this flag the
+   * rejection classifies as `unknown` and no failover is reachable at all.
+   *
+   * Reset at the top of every {@link runPrompt} attempt, so the replay after a
+   * failover observes its own outcome rather than inheriting the first one's.
+   */
+  limitRejectionSeen = false;
+  /**
+   * True when {@link handleResultErrorPayload} rejected this turn ONLY so the
+   * seat-failover branch could run — a turn that, before this existed, would
+   * have emitted its error and resolved. If the failover then declines, the
+   * rejection is undone so a limit block with no peer available looks exactly
+   * as it always has downstream (one error event, one `agent_end`, a resolved
+   * promise) rather than also drawing the runner's fatal "prompt failed".
+   */
+  limitTurnRejectedForFailover = false;
+  /**
+   * Whether this attempt already reported a provider rejection. One upstream
+   * failure routinely reaches the driver twice — `rejected` telemetry followed
+   * by the error result, or an `is_error` result followed by the iterator throw
+   * carrying the real text — and these observations feed counters, so counting
+   * one rejection twice would overstate the seat's pressure.
+   */
+  providerResponseReported = false;
+  /** Limit-window metadata from this attempt's rejection telemetry, if any. */
+  lastLimitInfo = null;
+  /**
+   * The `agent-event: error` {@link failTurn} withheld because a recovery
+   * (auth self-heal or seat failover) was about to run. The recovery emits it
+   * if it declines, and drops it if it retries — so a recovered turn shows the
+   * user nothing and a failed one shows exactly one error.
+   */
+  deferredTurnError = null;
   /** Tracks whether a session has been started (for continue: true). */
   hasSession = false;
   /** Session ID from the SDK — used for streamInput messages. */
@@ -422,8 +506,14 @@ var ClaudeSdkDriver = class extends AgentDriver {
   async runPrompt(message, _budget) {
     if (!this.sdk) await this.start();
     this.authSelfHealUsed = _budget.auth;
+    this.limitFailoverUsed = _budget.limit;
+    this.limitRejectionSeen = false;
+    this.limitTurnRejectedForFailover = false;
+    this.providerResponseReported = false;
+    this.lastLimitInfo = null;
+    this.deferredTurnError = null;
     let retrying = false;
-    const isFirstAttempt = !_budget.staleResume && !_budget.poison && !_budget.auth && !_budget.queryEnded;
+    const isFirstAttempt = !_budget.staleResume && !_budget.poison && !_budget.auth && !_budget.queryEnded && !_budget.limit;
     if (isFirstAttempt) {
       this._lastTokens = null;
       this._lastContextTokens = null;
@@ -432,7 +522,9 @@ var ClaudeSdkDriver = class extends AgentDriver {
     this.prevText = "";
     this.emittedSanitizedLen = 0;
     this.suppressingAuthStream = false;
+    this.suppressedAuthRenderText = null;
     this.turnCompleted = false;
+    this.disarmErrorResultGrace();
     if (this.query && (this.inputStream == null || this.inputStream.ended || this.shouldRecycleQuery())) {
       this.recycleQueryForNextTurn();
     }
@@ -447,6 +539,7 @@ var ClaudeSdkDriver = class extends AgentDriver {
         await this.startQuery(message);
       }
     } catch (err) {
+      this.disarmErrorResultGrace();
       this.turnResolve = null;
       this.turnReject = null;
       this.running = false;
@@ -476,20 +569,40 @@ var ClaudeSdkDriver = class extends AgentDriver {
           return this.runPrompt(message, { ..._budget, poison: true });
         }
       }
-      const isAuthError = err instanceof AuthError && !_budget.auth;
-      if (isAuthError && this.config.onAuthError) {
+      const authOwns = err instanceof AuthError && !_budget.auth && this.config.onAuthError != null;
+      if (authOwns) {
         if (await this.attemptAuthSelfHeal(err)) {
           retrying = true;
           return this.runPrompt(message, { ..._budget, auth: true });
         }
+      } else if (!_budget.limit && this.limitRejectionSeen && this.config.onLimitBlocked) {
+        if (await this.attemptLimitFailover(err)) {
+          if (this.abortController?.signal.aborted) {
+            this.log.info("aborted during the seat failover; not replaying the prompt");
+            this.emitAgentEnd();
+            return;
+          }
+          retrying = true;
+          return this.runPrompt(message, { ..._budget, limit: true });
+        }
+        if (this.limitTurnRejectedForFailover) {
+          this.emitAgentEnd();
+          return;
+        }
       }
       throw err;
     } finally {
       if (!retrying) {
         this.disarmTurnStallWatchdog();
+        this.disarmErrorResultGrace();
         this.turnResolve = null;
         this.turnReject = null;
         this.running = false;
+        this.limitRejectionSeen = false;
+        this.limitTurnRejectedForFailover = false;
+        this.lastLimitInfo = null;
+        this.deferredTurnError = null;
+        this.suppressedAuthRenderText = null;
       }
     }
   }
@@ -536,6 +649,42 @@ var ClaudeSdkDriver = class extends AgentDriver {
       this.turnStallTimer = null;
     }
   }
+  /**
+   * Bound the wait for the follow-up throw an `is_error` result implies. The
+   * throw carries the real, richly-classified error, so the deferral stays —
+   * this only caps it, turning a permanently pending turn into a bounded
+   * failure. Never arms onto an already-settled turn: an auth / account / limit
+   * payload has run `failTurn` by the time this is reached, and the same guard
+   * is re-checked inside the callback because the throw normally lands in
+   * between. Note 2026-06-08-claude-sdk-error-result-handling.
+   */
+  armErrorResultGrace(detail, context) {
+    this.disarmErrorResultGrace();
+    if (this.turnCompleted || this.turnReject == null) return;
+    this.errorResultGraceTimer = setTimeout(() => {
+      this.errorResultGraceTimer = null;
+      if (this.turnCompleted || this.turnReject == null) return;
+      this.log.error("is_error result never produced its follow-up throw; failing the turn", {
+        subtype: context.subtype,
+        terminalReason: context.terminalReason,
+        category: detail.category
+      });
+      const message = "The model reported an error but sent no details. The conversation is intact \u2014 send your message again.";
+      this.failTurn(new Error(message), { ...detail, message });
+    }, errorResultGraceMs());
+    this.errorResultGraceTimer.unref?.();
+  }
+  /**
+   * The retry helpers that null `turnResolve`/`turnReject` before recursing
+   * need no call: they run only from `runPrompt`'s catch, which is reached only
+   * because `failTurn` or `rejectTurnSilently` rejected — and both disarm first.
+   */
+  disarmErrorResultGrace() {
+    if (this.errorResultGraceTimer) {
+      clearTimeout(this.errorResultGraceTimer);
+      this.errorResultGraceTimer = null;
+    }
+  }
   /**
    * The SDK went silent mid-turn. Tear the query down so the *next* prompt
    * starts a fresh one (a live-but-deaf query would otherwise swallow every
@@ -803,18 +952,60 @@ var ClaudeSdkDriver = class extends AgentDriver {
       this.running = false;
       return true;
     }
+    this.emitDeferredTurnError({ type: "error", error: err.message, detail: err.detail });
+    return false;
+  }
+  /**
+   * Side-effects of the seat-failover path: ask the host to re-resolve the AI
+   * provider config behind this session. On `switched: true` drop the query and
+   * return `true` (the caller recurses onto a fresh CLI); otherwise emit the
+   * deferred error and return `false`. Mirrors {@link attemptAuthSelfHeal} —
+   * this performs the state mutation, the caller owns the control flow.
+   *
+   * Dropping `this.query` is the whole point of the retry, not bookkeeping: a
+   * resident CLI caches "blocked until <reset>" and short-circuits the next
+   * prompt locally with no API attempt at all (skaile-ai/workspaces#566), so a
+   * rewritten credentials file alone would change nothing. Only a fresh spawn
+   * clears it. `sessionId` / `hasSession` are preserved so the new query
+   * resumes the same conversation.
+   */
+  async attemptLimitFailover(err) {
+    this.log.warn("turn blocked by an upstream usage limit; invoking onLimitBlocked", {
+      configId: this.config.aiProviderConfigId,
+      limitType: this.lastLimitInfo?.limitType,
+      resetsAt: this.lastLimitInfo?.resetsAt
+    });
+    let outcome;
     try {
-      this.emit("agent-event", {
-        type: "error",
-        error: err.message,
-        detail: err.detail
+      outcome = await this.config.onLimitBlocked({
+        configId: this.config.aiProviderConfigId ?? "",
+        ...this.lastLimitInfo ?? {}
+      });
+    } catch (failoverErr) {
+      this.log.warn("onLimitBlocked callback threw; surfacing the original limit error", {
+        error: failoverErr instanceof Error ? failoverErr.message : String(failoverErr)
       });
-    } catch (emitErr) {
-      this.log.warn(
-        "agent-event listener threw during deferred auth-error surfacing; suppressing",
-        { error: emitErr instanceof Error ? emitErr.message : String(emitErr) }
-      );
     }
+    if (outcome?.switched === true) {
+      this.log.info("switched AI provider config; respawning the CLI and replaying the prompt", {
+        configId: outcome.configId
+      });
+      this.query = null;
+      this.endInputStream();
+      this.turnResolve = null;
+      this.turnReject = null;
+      this.running = false;
+      return true;
+    }
+    this.log.info("no alternative AI provider config available; surfacing the limit error", {
+      reason: outcome?.reason
+    });
+    const detail = err?.detail;
+    this.emitDeferredTurnError({
+      type: "error",
+      error: err instanceof Error ? err.message : String(err),
+      ...detail ? { detail } : {}
+    });
     return false;
   }
   /**
@@ -1261,6 +1452,12 @@ var ClaudeSdkDriver = class extends AgentDriver {
       category: detail.category,
       retryable: detail.retryable
     });
+    if (detail.category === "auth") {
+      this.reportProviderResponse({ status: 401 });
+    } else if (isSeatCapacityFailure(detail)) {
+      this.limitRejectionSeen = true;
+      this.reportProviderResponse({ status: 429, ...this.lastLimitInfo ?? {} });
+    }
     const surfaced = detail.category === "auth" ? new AuthError(detail) : detail.category === "account" ? new AccountUnavailableError(detail) : error;
     this.failTurn(surfaced, detail);
   }
@@ -1276,15 +1473,20 @@ var ClaudeSdkDriver = class extends AgentDriver {
     if (this.turnCompleted) return;
     this.turnCompleted = true;
     this.disarmTurnStallWatchdog();
+    this.disarmErrorResultGrace();
     if (this.turnResolve) {
       this.turnResolve();
       this.turnResolve = null;
       this.turnReject = null;
     }
+    this.emitAgentEnd();
+  }
+  /** Emit the turn-end signal, swallowing a throwing listener. */
+  emitAgentEnd() {
     try {
       this.emit("agent-event", { type: "agent_end" });
     } catch (emitErr) {
-      this.log.warn("agent-event listener threw during completeTurn; suppressing", {
+      this.log.warn("agent-event listener threw while ending the turn; suppressing", {
         error: emitErr instanceof Error ? emitErr.message : String(emitErr)
       });
     }
@@ -1302,6 +1504,7 @@ var ClaudeSdkDriver = class extends AgentDriver {
    */
   rejectTurnSilently(err) {
     this.disarmTurnStallWatchdog();
+    this.disarmErrorResultGrace();
     this.turnCompleted = true;
     if (this.turnReject) {
       const reject = this.turnReject;
@@ -1344,29 +1547,63 @@ var ClaudeSdkDriver = class extends AgentDriver {
    */
   failTurn(err, detail) {
     this.disarmTurnStallWatchdog();
+    this.disarmErrorResultGrace();
+    const hadPendingTurn = this.turnReject != null;
     if (this.turnReject) {
       this.turnReject(err);
       this.turnResolve = null;
       this.turnReject = null;
     }
     this.turnCompleted = true;
+    const event = {
+      type: "error",
+      error: err.message,
+      ...detail ? { detail } : {}
+    };
     const willSelfHeal = err instanceof AuthError && !this.authSelfHealUsed && this.config.onAuthError != null;
-    if (willSelfHeal) {
+    if (hadPendingTurn && willSelfHeal) {
       this.log.info("deferring auth-error event; self-heal will attempt refresh");
+      this.deferredTurnError = event;
+      return;
+    }
+    if (hadPendingTurn && this.willFailoverOnLimit()) {
+      this.log.info("deferring limit error event; seat failover will be attempted");
+      this.deferredTurnError = event;
       return;
     }
+    this.emitTurnErrorEvent(event);
+  }
+  /**
+   * Whether a usage-limit block on the current attempt still has a seat
+   * failover available. Evaluated identically by {@link failTurn} (to decide
+   * whether to withhold the error event) and by {@link handleResultErrorPayload}
+   * (to decide whether to reject the turn at all) — one predicate so the two
+   * can never disagree and strand a deferred event.
+   */
+  willFailoverOnLimit() {
+    return this.limitRejectionSeen && !this.limitFailoverUsed && this.config.onLimitBlocked != null;
+  }
+  /** Emit one `agent-event: error`, swallowing a throwing listener. */
+  emitTurnErrorEvent(event) {
     try {
-      this.emit("agent-event", {
-        type: "error",
-        error: err.message,
-        ...detail ? { detail } : {}
-      });
+      this.emit("agent-event", event);
     } catch (emitErr) {
-      this.log.warn("agent-event listener threw during failTurn; suppressing", {
+      this.log.warn("agent-event listener threw while surfacing a turn error; suppressing", {
         error: emitErr instanceof Error ? emitErr.message : String(emitErr)
       });
     }
   }
+  /**
+   * Emit the error {@link failTurn} withheld, exactly once. Called by a
+   * recovery path that decided NOT to retry, so every failure produces one
+   * downstream error event and a recovered one produces none. `fallback` covers
+   * the paths that reject without going through `failTurn`.
+   */
+  emitDeferredTurnError(fallback) {
+    const event = this.deferredTurnError ?? fallback;
+    this.deferredTurnError = null;
+    this.emitTurnErrorEvent(event);
+  }
   // ---------------------------------------------------------------------------
   // Message handling
   // ---------------------------------------------------------------------------
@@ -1383,9 +1620,17 @@ var ClaudeSdkDriver = class extends AgentDriver {
     }
   }
   /**
-   * Surface subscription rate-limit telemetry as a structured warning log.
+   * Surface subscription rate-limit telemetry as a structured warning log, and
+   * — on `status: "rejected"` — arm the seat failover and report the rejection
+   * to the host for per-seat health attribution.
+   *
    * Returns `true` when the message was a rate-limit event (and fully handled),
    * so the caller can stop dispatching.
+   *
+   * This used to only log. That is what left a session pinned to a parked seat:
+   * the rejection was fully handled here and nothing propagated, so the
+   * platform's re-resolution — which was ready and working — was reachable only
+   * through a token refresh that happened to be due (skaile-ai/platform#2976).
    */
   handleRateLimitEvent(msg) {
     const maybeRateLimit = msg;
@@ -1397,15 +1642,45 @@ var ClaudeSdkDriver = class extends AgentDriver {
         utilization: info.utilization,
         resetsAt: info.resetsAt
       });
+      if (info.status === "rejected") {
+        this.limitRejectionSeen = true;
+        this.lastLimitInfo = {
+          ...info.rateLimitType ? { limitType: info.rateLimitType } : {},
+          ...typeof info.resetsAt === "number" ? { resetsAt: info.resetsAt } : {},
+          ...typeof info.utilization === "number" ? { utilization: info.utilization } : {}
+        };
+        this.reportProviderResponse({ status: 429, ...this.lastLimitInfo });
+      }
       return true;
     }
     return false;
   }
+  /**
+   * Report an observed 401 / 429 to the host so the owning AI provider config's
+   * live health counters can be bumped (skaile-ai/workspaces#368). Strictly
+   * fire-and-forget: a throwing host callback must never fail the turn that
+   * produced the observation.
+   */
+  reportProviderResponse(observation) {
+    if (!this.config.onProviderResponse || this.providerResponseReported) return;
+    this.providerResponseReported = true;
+    try {
+      this.config.onProviderResponse({
+        ...observation,
+        ...this.config.aiProviderConfigId ? { configId: this.config.aiProviderConfigId } : {}
+      });
+    } catch (err) {
+      this.log.warn("onProviderResponse threw; suppressing", {
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
   handleAssistantMessage(msg) {
     this.captureAssistantContext(msg);
     const agentMsg = this.mapAssistantMessage(msg);
     if (this.isSuppressibleAuthRender(agentMsg)) {
       this.log.info("suppressing SDK auth-error assistant text; self-heal will retry");
+      this.stashSuppressedAuthRender(this.assistantTextOf(agentMsg));
       this.prevText = "";
       this.emittedSanitizedLen = 0;
       this.suppressingAuthStream = false;
@@ -1425,14 +1700,37 @@ var ClaudeSdkDriver = class extends AgentDriver {
     this.prevText = "";
     this.emittedSanitizedLen = 0;
     this.suppressingAuthStream = false;
+    this.suppressedAuthRenderText = null;
     this.emit("agent-event", { type: "message_end", message: agentMsg });
   }
   // True when this assistant text is the SDK's render of a 401 about to be self-healed.
   isSuppressibleAuthRender(msg) {
-    if (this.authSelfHealUsed || this.config.onAuthError == null) return false;
+    if (!this.authSelfHealAvailable()) return false;
     if (msg.toolCalls && msg.toolCalls.length > 0) return false;
-    const text = typeof msg.content === "string" ? msg.content : msg.content.filter((b) => b.type === "text" && typeof b.text === "string").map((b) => b.text).join("");
-    return this.textIsAuthRender(text);
+    return this.textIsAuthRender(this.assistantTextOf(msg));
+  }
+  /** Whether a 401 on this attempt can still be self-healed and retried. */
+  authSelfHealAvailable() {
+    return !this.authSelfHealUsed && this.config.onAuthError != null;
+  }
+  /**
+   * Stash a dropped auth render as evidence for {@link handleResultErrorPayload}.
+   *
+   * Deliberately stricter than the suppression predicate. Suppression only hides
+   * a message, but this text can reach the result path and construct an
+   * `AuthError` — which refreshes a credential, bumps that seat's health
+   * counters, and replays the turn. `classifyClaudeSdkError` buckets a bare
+   * "401" or "unauthorized" as auth, so ordinary prose about authentication
+   * qualifies; requiring a marker only the CLI itself emits keeps that prose out.
+   */
+  stashSuppressedAuthRender(text) {
+    if (!this.authSelfHealAvailable()) return;
+    if (!isCliAuthRenderText(text)) return;
+    this.suppressedAuthRenderText = text;
+  }
+  /** Flatten an assistant message's text blocks; non-text blocks contribute nothing. */
+  assistantTextOf(msg) {
+    return typeof msg.content === "string" ? msg.content : msg.content.filter((b) => b.type === "text" && typeof b.text === "string").map((b) => b.text).join("");
   }
   // Cheap substring pre-filter keeps the full classifier off the hot path of
   // every assistant message / stream delta; only auth-shaped text pays for it.
@@ -1453,7 +1751,10 @@ var ClaudeSdkDriver = class extends AgentDriver {
         this.suppressingAuthStream = true;
         this.log.info("suppressing SDK auth-error stream; self-heal will retry");
       }
-      if (this.suppressingAuthStream) return;
+      if (this.suppressingAuthStream) {
+        this.stashSuppressedAuthRender(this.prevText);
+        return;
+      }
       const safe = streamingSafeSanitize(this.prevText);
       const sanitizedDelta = safe.slice(this.emittedSanitizedLen);
       this.emittedSanitizedLen = safe.length;
@@ -1577,11 +1878,16 @@ var ClaudeSdkDriver = class extends AgentDriver {
   /**
    * Classify + route an `is_error` result payload: auth-shaped errors throw
    * via `failTurn`; populated non-auth errors surface a normal `error` event;
-   * empty errors defer to the consumer-error catch.
+   * empty errors defer to the consumer-error catch under a bounded grace timer.
+   *
+   * An empty `errors[]` falls back to the auth render this attempt suppressed:
+   * handed nothing, the classifier can only answer `unknown`, stranding a 401
+   * the render path already recognised on the same text.
    */
   handleResultErrorPayload(msg, errors) {
+    const effectiveErrors = errors.length === 0 && this.suppressedAuthRenderText != null ? [this.suppressedAuthRenderText] : errors;
     const rawDetail = classifyClaudeSdkError({
-      errors,
+      errors: effectiveErrors,
       terminalReason: msg.terminal_reason,
       subtype: msg.subtype,
       oauthCredential: this.usingOauthCredential
@@ -1591,20 +1897,35 @@ var ClaudeSdkDriver = class extends AgentDriver {
       subtype: msg.subtype,
       terminalReason: msg.terminal_reason,
       errorsCount: errors.length,
+      fromSuppressedAuthRender: effectiveErrors !== errors,
       category: detail.category,
       retryable: detail.retryable
     });
-    const errorText = errors.join("; ") || `Agent stopped: ${msg.subtype}`;
+    if (detail.category === "auth") {
+      this.reportProviderResponse({ status: 401 });
+    } else if (isSeatCapacityFailure(detail, msg.subtype)) {
+      this.limitRejectionSeen = true;
+      this.reportProviderResponse({ status: 429, ...this.lastLimitInfo ?? {} });
+    }
+    const errorText = effectiveErrors.join("; ") || `Agent stopped: ${msg.subtype}`;
     if (detail.category === "auth") {
       this.failTurn(new AuthError({ ...detail, message: errorText }), detail);
     } else if (detail.category === "account") {
       this.failTurn(new AccountUnavailableError({ ...detail, message: errorText }), detail);
+    } else if (this.willFailoverOnLimit()) {
+      this.limitTurnRejectedForFailover = true;
+      this.failTurn(new Error(errorText), detail);
     } else if (errors.length > 0) {
       this.emit("agent-event", {
         type: "error",
         error: errorText,
         detail
       });
+    } else {
+      this.armErrorResultGrace(detail, {
+        subtype: msg.subtype,
+        terminalReason: msg.terminal_reason
+      });
     }
   }
   // ---------------------------------------------------------------------------