@skaile/workspaces 5.6.1 → 5.8.0

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

@@ -1,29 +1,30 @@
 import { formatDroppedToolsNotice, filterInProcessMcpServerTools, checkToolPropertyKeys } from '../../chunk-X5O56UO4.js';
-import { scrubPoisonedTranscript, transcriptStoreForRuntime, resolveClaudeConfigDir, claudeEndpointMode, buildClaudeEndpointEnv } from '../../chunk-VBBBZDI7.js';
-import { scopeReconfigureModel } from '../../chunk-EINLFFP6.js';
-import { dispatchCapability } from '../../chunk-NARITJS2.js';
-import { fetchProviderModels } from '../../chunk-27HS2DHB.js';
-import { AuthError, stripRunnerPrivateEnv, classifyClaudeSdkError, reclassifyAuthAsAccountUnavailable, AccountUnavailableError, isLongContextEntitlementRejection, LONG_CONTEXT_CREDITS_API_ERROR } from '../../chunk-XBSQ4KMC.js';
+import { freshBudget, isFirstAttempt, spend, isSpent, decide, isAvailable } from '../../chunk-IZCR27MU.js';
+import { AskSlots } from '../../chunk-EPBKISS5.js';
+import { scrubPoisonedTranscript, transcriptStoreForRuntime, resolveClaudeConfigDir, claudeEndpointMode, buildClaudeEndpointEnv } from '../../chunk-S53LOR7B.js';
+import { dispatchCapability } from '../../chunk-GCICGXDD.js';
+import { fetchProviderModels } from '../../chunk-PTSGWKHR.js';
+import { ReconfigureLedger, AuthError, stripRunnerPrivateEnv, classifyClaudeSdkError, reclassifyAuthAsAccountUnavailable, AccountUnavailableError, isLongContextEntitlementRejection, LONG_CONTEXT_CREDITS_API_ERROR } from '../../chunk-B4X2N7JQ.js';
 import { agentExecRequested, wrapAgentCommand, resolveAgentExec } from '../../chunk-YROR332M.js';
-import { BUILTIN_DRIVER_CATALOG, AgentDriver, getBridgeLogger, entryCredentialValue, registryDriverConfig } from '../../chunk-5B5IZVEP.js';
+import { BUILTIN_DRIVER_CATALOG, AgentDriver, getBridgeLogger, entryCredentialValue, registryDriverConfig } from '../../chunk-AWQYXZVG.js';
 import '../../chunk-6E6PKKAD.js';
-import { withActivityLabelShape } from '../../chunk-DMLDYFDS.js';
-import '../../chunk-FRHE7FFB.js';
-import '../../chunk-TZCQ7ZWQ.js';
+import { withActivityLabelShape } from '../../chunk-F3RDEH5U.js';
+import '../../chunk-B6GIW55K.js';
+import '../../chunk-36AFURKZ.js';
 import '../../chunk-4GY63JU6.js';
-import '../../chunk-BF33SCLY.js';
-import '../../chunk-46OVMT76.js';
+import '../../chunk-GB7WDMH2.js';
+import '../../chunk-PMECEZK3.js';
 import '../../chunk-5BEFNLOR.js';
 import '../../chunk-A2ULN3KX.js';
-import '../../chunk-2W4LBLIN.js';
-import '../../chunk-MFHKHXDE.js';
+import '../../chunk-JAKOMFC6.js';
+import '../../chunk-L5VSIPQD.js';
 import '../../chunk-CPSIPIX7.js';
-import '../../chunk-7ZHLYXTI.js';
+import '../../chunk-BTE2V4IW.js';
 import '../../chunk-RVRB27AN.js';
-import '../../chunk-PA7WLID3.js';
-import '../../chunk-AO7VJ6G6.js';
+import '../../chunk-GTILM2CI.js';
+import '../../chunk-QVNRCDTV.js';
 import '../../chunk-ICSCSM5D.js';
-import '../../chunk-JMKB7IB4.js';
+import '../../chunk-UMVKJM4Q.js';
 import { mergeRegistries, parseModelRef, isEntryEnabled, resolveEntryBaseUrl } from '../../chunk-MJHSLODD.js';
 import '../../chunk-C3CAXQMA.js';
 import { createLogger } from '../../chunk-BOFL7GIF.js';
@@ -305,9 +306,6 @@ if (typeof globalThis.require === "undefined") {
   }
 }
 var LIVE_SET_MODEL_TIMEOUT_MS = 5e3;
-function freshRetryBudget() {
-  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;
@@ -357,10 +355,6 @@ function apiErrorExcerpt(text) {
   ).replace(/\b(access_token|api_key|token|key|sig|signature)=[^\s&"]+/gi, "$1=[redacted]").replace(/\b(sk-ant-|sk-)[A-Za-z0-9_-]{6,}/g, "[redacted]").replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, "[redacted]");
   return masked.length > API_ERROR_EXCERPT_MAX ? `${masked.slice(0, API_ERROR_EXCERPT_MAX)}\u2026` : masked;
 }
-var STALE_RESUME_PATTERN = /No conversation found with session ID/i;
-function isPoisonedHistoryError(message) {
-  return /invalid_request_error/i.test(message) && /media[_ ]?type|could not process image|image exceeds|cache_control/i.test(message);
-}
 function snapshotProcessEnv() {
   const env = {};
   for (const [k, v] of Object.entries(process.env)) {
@@ -559,10 +553,6 @@ var ClaudeSdkDriver = class extends AgentDriver {
    * {@link shouldRecycleQuery}; reset on every fresh spawn.
    */
   lastNumTurns = null;
-  /** What the resident query runs; `null` until the first spawn. */
-  liveQueryConfig = null;
-  /** A config change the resident query cannot take live: respawn at the next turn. */
-  recycleForConfig = false;
   /**
    * The capability tool set the resident query's `skaile-capabilities` server
    * was built from ({@link capabilityToolsKey}); `null` without capability hooks.
@@ -571,8 +561,8 @@ var ClaudeSdkDriver = class extends AgentDriver {
    * respawn rebuilds the server — see {@link capabilityToolsChanged}.
    */
   liveCapabilityToolsKey = null;
-  /** In-flight {@link syncLiveQueryConfig} chain, so switches apply in order. */
-  liveConfigSync = null;
+  /** Owns the desired config, drift and ordering of live reconfigures. */
+  reconfig;
   /** {@link LIVE_SET_MODEL_TIMEOUT_MS}, as a field so tests can shorten it. */
   setModelTimeoutMs = LIVE_SET_MODEL_TIMEOUT_MS;
   /**
@@ -607,30 +597,24 @@ var ClaudeSdkDriver = class extends AgentDriver {
    */
   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
-   * been spent. Read by {@link failTurn} to decide whether to defer the
-   * `agent-event: error` emission for a self-healable auth error.
+   * The in-flight turn's recovery budget: which one-shot recoveries (stale
+   * resume, poison scrub, auth refresh, limit failover, query-ended replay) have
+   * been spent. Owned by the recovery policy; the single source for "was this
+   * kind already spent?" and "is it still available?".
    *
    * Set unconditionally at the top of every {@link runPrompt} attempt; never
-   * 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;
-  /**
-   * Mirror of the in-flight turn's stale-resume retry budget — same contract as
-   * {@link authSelfHealUsed}, for the "No conversation found" fresh-session retry.
+   * reset elsewhere — the next attempt's set is the only legitimate transition.
    */
-  staleResumeRetryUsed = false;
+  recoveryBudget = freshBudget();
   /**
-   * Mirror of the in-flight turn's poisoned-transcript scrub budget — same
-   * contract as {@link authSelfHealUsed}.
+   * The recovery policy's answer for the failure that rejected this attempt,
+   * recorded where the failure was classified ({@link failTurn}, or the
+   * dispatch-failure site in {@link consumeMessages}). {@link failTurn} defers
+   * the error event on it and {@link runPrompt}'s catch carries it out — the
+   * policy is never consulted a second time for the same failure. `null` until
+   * a failure is recorded; cleared at every attempt start and turn end.
    */
-  poisonScrubUsed = false;
+  recoveryDecision = null;
   /**
    * Set when THIS attempt saw an upstream usage-limit rejection: either the
    * SDK's `rate_limit_event` telemetry with `status: "rejected"`, or an error
@@ -775,6 +759,13 @@ var ClaudeSdkDriver = class extends AgentDriver {
   constructor(config) {
     super();
     this.config = config;
+    this.reconfig = new ReconfigureLedger({
+      config: () => this.config,
+      isLive: () => this.query != null,
+      isIdle: () => !this.running,
+      applyLive: (delta, live) => this.applyLive(delta, live),
+      log: this.log
+    });
   }
   get runtimeSessionId() {
     return this.sessionId || void 0;
@@ -786,76 +777,35 @@ var ClaudeSdkDriver = class extends AgentDriver {
    * applies at the start of the next one, as omp does). A change it cannot take
    * live (thinking/effort, a model on another registry entry, a rejected or
    * timed-out `setModel`) recycles the query at the next turn boundary, so the
-   * fresh CLI resumes with the new config.
+   * fresh CLI resumes with the new config. The {@link ReconfigureLedger} owns
+   * the scope rule, ordering and drift; {@link applyLive} is this driver's hook.
    */
   reconfigure(patch) {
-    if (patch.model !== void 0) {
-      const scope = scopeReconfigureModel({
-        model: patch.model,
-        modelRef: this.config.modelRef,
-        registry: this.config.registry,
-        roles: this.config.roles
-      });
-      if (scope.ok) {
-        this.config.model = patch.model;
-        if (scope.modelRef !== void 0) this.config.modelRef = scope.modelRef;
-      } else {
-        this.log.warn("model change refused; keeping the current model", {
-          model: patch.model,
-          providerId: scope.providerId
-        });
-      }
-    }
-    if (patch.thinking !== void 0) this.config.thinking = patch.thinking;
-    if (patch.effort !== void 0) this.config.effort = patch.effort;
-    if (this.query && !this.running) void this.syncLiveQueryConfig();
-  }
-  /** Whether the driver config moved away from what the resident query runs. */
-  liveConfigDrifted() {
-    const live = this.liveQueryConfig;
-    if (!this.query || !live) return false;
-    const { model, modelRef, thinking, effort } = this.config;
-    return model !== live.model || modelRef !== live.modelRef || thinking !== live.thinking || effort !== live.effort;
-  }
-  /** Queue {@link applyConfigToLiveQuery} behind any switch still in flight. */
-  syncLiveQueryConfig() {
-    const next = (this.liveConfigSync ?? Promise.resolve()).then(
-      () => this.applyConfigToLiveQuery()
-    );
-    this.liveConfigSync = next;
-    void next.finally(() => {
-      if (this.liveConfigSync === next) this.liveConfigSync = null;
-    });
-    return next;
+    return this.reconfig.reconfigure(patch);
   }
-  /** Bring the resident query in line with the driver config. Never rejects. */
-  async applyConfigToLiveQuery() {
+  /** Bring the resident query in line with a drifted config. Never rejects. */
+  async applyLive(delta, live) {
     const query = this.query;
-    const live = this.liveQueryConfig;
-    if (!query || !live || this.recycleForConfig || !this.liveConfigDrifted()) return;
-    const { model, modelRef, thinking, effort } = this.config;
-    const recycle = (reason, data = {}) => {
-      this.recycleForConfig = true;
+    if (!query) return "respawn";
+    const respawn = (reason, data = {}) => {
       this.log.info("config change needs a fresh query; recycling at the next turn", {
         reason,
         ...data
       });
+      return "respawn";
     };
     try {
-      if (thinking !== live.thinking || effort !== live.effort) {
-        recycle("thinking_or_effort");
-        return;
+      if (delta.thinking !== void 0 || delta.effort !== void 0) {
+        return respawn("thinking_or_effort");
       }
       const endpoint = this.resolveEndpoint();
       if (endpoint.providerId !== live.providerId) {
-        recycle("provider_changed", { from: live.providerId, to: endpoint.providerId });
-        return;
+        return respawn("provider_changed", { from: live.providerId, to: endpoint.providerId });
       }
-      const providerModel = endpoint.model || model || "sonnet";
+      const providerModel = endpoint.model || this.config.model || "sonnet";
       if (providerModel !== live.providerModel) {
         if (this.inputStream == null || this.inputStream.ended || this.shouldRecycleQuery()) {
-          recycle("query_due_for_recycle");
-          return;
+          return respawn("query_due_for_recycle");
         }
         let timer;
         try {
@@ -871,17 +821,18 @@ var ClaudeSdkDriver = class extends AgentDriver {
         } finally {
           clearTimeout(timer);
         }
-        if (this.query !== query) return;
+        if (this.query !== query) return "applied";
         this.log.info("switched the resident query's model", {
           from: live.providerModel,
           to: providerModel
         });
+        live.providerModel = providerModel;
       }
-      Object.assign(live, { model, modelRef, providerModel });
+      return "applied";
     } catch (err) {
-      if (this.query === query) {
-        recycle("set_model_failed", { error: err instanceof Error ? err.message : String(err) });
-      }
+      return respawn("set_model_failed", {
+        error: err instanceof Error ? err.message : String(err)
+      });
     }
   }
   getModel() {
@@ -920,7 +871,9 @@ var ClaudeSdkDriver = class extends AgentDriver {
    */
   prompt(message) {
     this.supersedePendingQuestion();
-    const queuedPrompt = this.promptTail.then(() => this.runPrompt(message, freshRetryBudget()));
+    const queuedPrompt = this.promptTail.then(
+      () => this.runPrompt(message, freshBudget())
+    );
     this.promptTail = queuedPrompt.then(
       () => void 0,
       () => void 0
@@ -933,13 +886,11 @@ var ClaudeSdkDriver = class extends AgentDriver {
    * Retries recurse here rather than through {@link prompt}, so they cannot
    * enqueue behind themselves and deadlock.
    */
-  async runPrompt(message, _budget) {
+  async runPrompt(message, budget) {
     if (this.killed) throw new Error(KILLED_TURN_MESSAGE);
     if (!this.sdk) await this.start();
-    this.authSelfHealUsed = _budget.auth;
-    this.limitFailoverUsed = _budget.limit;
-    this.staleResumeRetryUsed = _budget.staleResume;
-    this.poisonScrubUsed = _budget.poison;
+    this.recoveryBudget = budget;
+    this.recoveryDecision = null;
     this.limitRejectionSeen = false;
     this.limitTurnRejectedForFailover = false;
     this.providerResponseReported = false;
@@ -948,8 +899,8 @@ var ClaudeSdkDriver = class extends AgentDriver {
     this.deferredTurnError = null;
     this.heldFailoverResult = null;
     let retrying = false;
-    const isFirstAttempt = !_budget.staleResume && !_budget.poison && !_budget.auth && !_budget.queryEnded && !_budget.limit;
-    if (isFirstAttempt) {
+    const isFirstAttempt2 = isFirstAttempt(budget);
+    if (isFirstAttempt2) {
       this._lastTokens = null;
       this._lastContextTokens = null;
       this._lastModelUsage = null;
@@ -963,8 +914,8 @@ var ClaudeSdkDriver = class extends AgentDriver {
     this.lastApiErrorRender = null;
     this.turnCompleted = false;
     this.disarmErrorResultGrace();
-    if (this.liveConfigSync || this.liveConfigDrifted()) await this.syncLiveQueryConfig();
-    if (this.query && (this.inputStream == null || this.inputStream.ended || this.recycleForConfig || this.shouldRecycleQuery() || this.capabilityToolsChanged())) {
+    await this.reconfig.flushBeforeTurn();
+    if (this.query && (this.inputStream == null || this.inputStream.ended || this.reconfig.needsRespawn || this.shouldRecycleQuery() || this.capabilityToolsChanged())) {
       this.recycleQueryForNextTurn();
     }
     const turnPromise = new Promise((resolve, reject) => {
@@ -989,35 +940,33 @@ var ClaudeSdkDriver = class extends AgentDriver {
       await turnPromise;
     } catch (err) {
       if (this.killed) throw err;
-      if (!_budget.queryEnded && err instanceof QueryEndedBeforeTurnError) {
+      const decision = this.recoveryDecision;
+      const attempt = decision && "attempt" in decision ? decision.attempt : null;
+      if (attempt === "query_ended_replay") {
         this.log.warn("turn was enqueued into an ending query; replaying on a fresh one");
         this.retractUnfinishedText();
         retrying = true;
-        return this.runPrompt(message, { ..._budget, queryEnded: true });
+        return this.runPrompt(message, spend(budget, attempt));
       }
-      const errMsg = err instanceof Error ? err.message : String(err);
-      const isStaleResume = !_budget.staleResume && STALE_RESUME_PATTERN.test(errMsg);
-      if (isStaleResume) {
+      if (attempt === "stale_resume") {
         this.prepareStaleResumeRetry();
         retrying = true;
-        return this.runPrompt(message, { ..._budget, staleResume: true });
+        return this.runPrompt(message, spend(budget, attempt));
       }
-      const isPoisonedHistory = !_budget.poison && isPoisonedHistoryError(errMsg);
-      const poisonSessionId = this.config.resumeSessionId || this.sessionId;
-      if (isPoisonedHistory && poisonSessionId) {
-        if (await this.attemptPoisonScrubRetry(poisonSessionId)) {
+      if (attempt === "poison_scrub") {
+        const poisonSessionId = this.config.resumeSessionId || this.sessionId;
+        if (poisonSessionId && await this.attemptPoisonScrubRetry(poisonSessionId)) {
           retrying = true;
-          return this.runPrompt(message, { ..._budget, poison: true });
+          return this.runPrompt(message, spend(budget, attempt));
         }
       }
-      const authOwns = err instanceof AuthError && !_budget.auth && this.config.onAuthError != null;
-      if (authOwns) {
+      if (attempt === "auth_refresh" && err instanceof AuthError) {
         if (await this.attemptAuthSelfHeal(err)) {
           this.retractUnfinishedText();
           retrying = true;
-          return this.runPrompt(message, { ..._budget, auth: true });
+          return this.runPrompt(message, spend(budget, attempt));
         }
-      } else if (!_budget.limit && this.limitRejectionSeen && this.config.onLimitBlocked) {
+      } else if (attempt === "limit_failover") {
         if (await this.attemptLimitFailover(err)) {
           if (this.abortController?.signal.aborted) {
             this.log.info("aborted during the seat failover; not replaying the prompt");
@@ -1030,7 +979,7 @@ var ClaudeSdkDriver = class extends AgentDriver {
           this.heldFailoverResult = null;
           this.retractUnfinishedText();
           retrying = true;
-          return this.runPrompt(message, { ..._budget, limit: true });
+          return this.runPrompt(message, spend(budget, attempt));
         }
         if (this.limitTurnRejectedForFailover) {
           this.emitAgentEnd();
@@ -1050,6 +999,7 @@ var ClaudeSdkDriver = class extends AgentDriver {
         this.limitTurnRejectedForFailover = false;
         this.lastLimitInfo = null;
         this.deferredTurnError = null;
+        this.recoveryDecision = null;
         this.heldFailoverResult = null;
         this.failoverUsageCarry = null;
         this.suppressedAuthRenderText = null;
@@ -1788,12 +1738,11 @@ var ClaudeSdkDriver = class extends AgentDriver {
     };
     if (apiKey) queryArgs.apiKey = apiKey;
     this.query = query(queryArgs);
-    this.recycleForConfig = false;
-    this.liveQueryConfig = {
+    this.reconfig.setSnapshot({
       ...spawnConfig,
       providerId: endpoint.providerId,
       providerModel: String(options.model)
-    };
+    });
     this.consumeMessages().catch((err) => {
       this.log.error("message loop terminated unexpectedly", err);
     });
@@ -1829,6 +1778,7 @@ var ClaudeSdkDriver = class extends AgentDriver {
         resolve,
         originalInput: input,
         questionTexts,
+        slots: new AskSlots(questionTexts),
         answers: {}
       };
       opts.signal.addEventListener(
@@ -1848,11 +1798,11 @@ var ClaudeSdkDriver = class extends AgentDriver {
   answerQuestion(answer, question) {
     const pending = this.pendingQuestion;
     if (!pending) return false;
-    const key = question !== void 0 && pending.questionTexts.includes(question) ? question : pending.questionTexts.find((q) => !Object.hasOwn(pending.answers, q));
-    if (key !== void 0) {
-      pending.answers[key] = answer;
+    const { slot, complete } = pending.slots.answer(question);
+    if (slot !== void 0) {
+      pending.answers[slot] = answer;
     }
-    if (pending.questionTexts.every((q) => Object.hasOwn(pending.answers, q))) {
+    if (complete) {
       this.pendingQuestion = null;
       this.lastSdkMessageAt = Date.now();
       pending.resolve({
@@ -2064,11 +2014,11 @@ var ClaudeSdkDriver = class extends AgentDriver {
         this.endInputStream();
         const neverDispatched = !this.turnCompleted && this.turnReject != null && !this.firstSdkMessageSeen && !this.abortController?.signal.aborted;
         if (neverDispatched) {
-          this.rejectTurnSilently(
-            new QueryEndedBeforeTurnError(
-              "The model process ended before this turn was dispatched."
-            )
+          const neverDispatchedErr = new QueryEndedBeforeTurnError(
+            "The model process ended before this turn was dispatched."
           );
+          this.recoveryDecision = this.decideRecovery(neverDispatchedErr);
+          this.rejectTurnSilently(neverDispatchedErr);
         } else {
           this.completeTurn();
         }
@@ -2101,7 +2051,7 @@ var ClaudeSdkDriver = class extends AgentDriver {
       errors: [error.message],
       oauthCredential: this.usingOauthCredential
     });
-    const detail = rawDetail.category === "auth" && this.authSelfHealUsed ? reclassifyAuthAsAccountUnavailable(rawDetail) : rawDetail;
+    const detail = rawDetail.category === "auth" && isSpent(this.recoveryBudget, "auth_refresh") ? reclassifyAuthAsAccountUnavailable(rawDetail) : rawDetail;
     this.log.error("consumer error", {
       message: error.message,
       category: detail.category,
@@ -2192,13 +2142,15 @@ var ClaudeSdkDriver = class extends AgentDriver {
    * caller transitions even if the listener chain misbehaves; the emit is
    * wrapped in try/catch so a listener failure cannot leak out.
    *
-   * Self-heal deferral: when the failure is an {@link AuthError} and the auth
-   * self-heal budget is still available (`!authSelfHealUsed`) AND the caller
-   * wired an `onAuthError` callback, the downstream `agent-event: error`
-   * emission is deferred. The rejected turn promise still travels to
-   * {@link prompt}'s catch block where the self-heal runs; if the retry
-   * succeeds the user never sees a 401, if the retry fails the second
-   * `failTurn` call (now with `authSelfHealUsed === true`) emits the error
+   * Recovery deferral: the recovery policy is asked ONCE per failure
+   * ({@link decideRecovery}) — unless the caller already decided and passes its
+   * answer as `decided` — and the answer is recorded on the turn. When it names
+   * an attempt, the downstream `agent-event: error` emission is deferred: the
+   * rejected turn promise still travels to {@link runPrompt}'s catch, which
+   * carries out that recorded attempt. If the attempt succeeds the user never
+   * sees the failure (a 401 self-heal, a seat switch, a stale-resume replay);
+   * if it declines, the catch emits the held-back error exactly once. A retry
+   * that fails again is decided afresh against the spent budget, so it emits
    * normally. This stops the historical "401 flashes in the UI even though
    * self-heal worked" misbehaviour where the bridge emitted the error event
    * before the retry decision was known.
@@ -2207,7 +2159,7 @@ var ClaudeSdkDriver = class extends AgentDriver {
    * § "Runner-side handling on 401" (the AI 401 mediation path that
    * exposed this hang).
    */
-  failTurn(err, detail) {
+  failTurn(err, detail, decided) {
     this.disarmTurnStallWatchdog();
     this.disarmErrorResultGrace();
     const hadPendingTurn = this.turnReject != null;
@@ -2222,54 +2174,43 @@ var ClaudeSdkDriver = class extends AgentDriver {
       error: err.message,
       ...detail ? { detail } : {}
     };
-    const willSelfHeal = err instanceof AuthError && !this.authSelfHealUsed && this.config.onAuthError != null;
-    if (hadPendingTurn && willSelfHeal) {
-      this.log.info("deferring auth-error event; self-heal will attempt refresh");
-      this.deferredTurnError = event;
-      return;
-    }
-    if (hadPendingTurn && this.willRetryStaleResume(err.message)) {
-      this.log.info("deferring stale-resume error event; retrying on a fresh session");
-      this.deferredTurnError = event;
-      return;
-    }
-    if (hadPendingTurn && this.willFailoverOnLimit()) {
-      this.log.info("deferring limit error event; seat failover will be attempted");
-      this.deferredTurnError = event;
-      return;
-    }
-    if (hadPendingTurn && this.willAttemptPoisonScrub(err.message)) {
-      this.log.info("deferring poisoned-history error event; a transcript scrub will be attempted");
-      this.deferredTurnError = event;
-      return;
+    if (hadPendingTurn) {
+      const decision = decided ?? this.decideRecovery(err);
+      this.recoveryDecision = decision;
+      if ("attempt" in decision) {
+        this.log.info("deferring turn error event; recovery attempt pending", {
+          attempt: decision.attempt
+        });
+        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.
+   * Ask the recovery policy what to do about `err`. Called once per failure, by
+   * the code that classifies it; the answer is recorded in
+   * {@link recoveryDecision} and acted on by {@link runPrompt}'s catch.
    */
-  willFailoverOnLimit() {
-    return this.limitRejectionSeen && !this.limitFailoverUsed && this.config.onLimitBlocked != null;
-  }
-  /**
-   * Whether `message` is a lost-transcript resume failure that `runPrompt` will
-   * still retry on a fresh session. The same test `runPrompt`'s catch applies,
-   * so a deferred error is always followed by the retry that drops it.
-   */
-  willRetryStaleResume(message) {
-    return !this.staleResumeRetryUsed && STALE_RESUME_PATTERN.test(message);
+  decideRecovery(err) {
+    return decide(
+      {
+        message: err.message,
+        authError: err instanceof AuthError,
+        limitRejected: this.limitRejectionSeen,
+        queryEnded: err instanceof QueryEndedBeforeTurnError
+      },
+      this.recoveryBudget,
+      this.recoveryWiring()
+    );
   }
-  /**
-   * Whether `runPrompt`'s catch will attempt a transcript scrub for `message`.
-   * The scrub may still find nothing, so unlike {@link willRetryStaleResume}
-   * the deferred error is not always dropped: `runPrompt` flushes it then.
-   */
-  willAttemptPoisonScrub(message) {
-    return !this.poisonScrubUsed && isPoisonedHistoryError(message) && Boolean(this.config.resumeSessionId || this.sessionId);
+  /** Which host callbacks and session state a recovery could use right now. */
+  recoveryWiring() {
+    return {
+      onAuthError: this.config.onAuthError != null,
+      onLimitBlocked: this.config.onLimitBlocked != null,
+      resumableSessionId: Boolean(this.config.resumeSessionId || this.sessionId)
+    };
   }
   /** Emit one `agent-event: error`, swallowing a throwing listener. */
   emitTurnErrorEvent(event) {
@@ -2532,12 +2473,7 @@ var ClaudeSdkDriver = class extends AgentDriver {
    * why that is forced: `_devlog/notes/2026-06-08-auth-error-text-suppress.md`.
    */
   isSuppressibleAuthRenderText(text) {
-    if (!this.authSelfHealAvailable()) return false;
-    return this.textIsAuthRender(text) && isCliAuthRenderText(text);
-  }
-  /** Whether a 401 on this attempt can still be self-healed and retried. */
-  authSelfHealAvailable() {
-    return !this.authSelfHealUsed && this.config.onAuthError != null;
+    return this.textIsAuthRender(text) && isCliAuthRenderText(text) && isAvailable(this.recoveryBudget, "auth_refresh", this.recoveryWiring());
   }
   /**
    * Stash a dropped auth render as evidence for {@link handleResultErrorPayload}.
@@ -2550,7 +2486,7 @@ var ClaudeSdkDriver = class extends AgentDriver {
    * qualifies; requiring a marker only the CLI itself emits keeps that prose out.
    */
   stashSuppressedAuthRender(text) {
-    if (!this.authSelfHealAvailable()) return;
+    if (!isAvailable(this.recoveryBudget, "auth_refresh", this.recoveryWiring())) return;
     if (!isCliAuthRenderText(text)) return;
     this.suppressedAuthRenderText = text;
   }
@@ -2752,7 +2688,7 @@ var ClaudeSdkDriver = class extends AgentDriver {
       subtype: msg.subtype,
       oauthCredential: this.usingOauthCredential
     });
-    const detail = rawDetail.category === "auth" && this.authSelfHealUsed ? reclassifyAuthAsAccountUnavailable(rawDetail) : rawDetail;
+    const detail = rawDetail.category === "auth" && isSpent(this.recoveryBudget, "auth_refresh") ? reclassifyAuthAsAccountUnavailable(rawDetail) : rawDetail;
     this.log.error("turn ended with error", {
       subtype: msg.subtype,
       terminalReason: msg.terminal_reason,
@@ -2775,7 +2711,9 @@ var ClaudeSdkDriver = class extends AgentDriver {
       });
     }
     const errorText = effectiveErrors.join("; ") || `Agent stopped: ${msg.subtype}`;
-    if (this.turnReject != null && this.willRetryStaleResume(errorText)) {
+    const failure = detail.category === "auth" ? new AuthError({ ...detail, message: errorText }) : detail.category === "account" ? new AccountUnavailableError({ ...detail, message: errorText }) : new Error(errorText);
+    const decision = this.decideRecovery(failure);
+    if (this.turnReject != null && "attempt" in decision && decision.attempt === "stale_resume") {
       const detached = this.query;
       this.query = null;
       this.endInputStream();
@@ -2783,16 +2721,14 @@ var ClaudeSdkDriver = class extends AgentDriver {
         detached?.close();
       } catch {
       }
-      this.failTurn(new Error(errorText), detail);
+      this.failTurn(new Error(errorText), detail, decision);
       return true;
     }
-    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()) {
+    if (detail.category === "auth" || detail.category === "account") {
+      this.failTurn(failure, detail, decision);
+    } else if ("attempt" in decision && decision.attempt === "limit_failover") {
       this.limitTurnRejectedForFailover = true;
-      this.failTurn(new Error(errorText), detail);
+      this.failTurn(failure, detail, decision);
     } else if (errors.length > 0) {
       this.emit("agent-event", {
         type: "error",