open-multi-agent-kit 0.96.2 → 0.98.0

package/dist/core/agent-session.js

@@ -17,7 +17,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join as joinPath } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { getVisionRouteModel } from "omk-agent-core";
-import { clampThinkingLevel, cleanupSessionResources, deriveContextPromptCacheKey, getSupportedThinkingLevels, isContextOverflow, modelsAreEqual, resetApiProviders, streamSimple, } from "omk-ai";
+import { clampThinkingLevel, cleanupSessionResources, deriveContextPromptCacheKey, getSupportedThinkingLevels, isBuiltinStreamFn, modelsAreEqual, resetApiProviders, } from "omk-ai";
 import { APP_NAME, VERSION } from "../config.js";
 import { theme } from "../modes/interactive/theme/theme.js";
 import { stripFrontmatter } from "../utils/frontmatter.js";
@@ -72,14 +72,15 @@ function firstTextContent(result) {
     }
     return undefined;
 }
+import { createImmutableMessageSnapshot } from "./agent-session-snapshot.js";
 import { redactCredentialShapedContent } from "./compaction/transaction.js";
 import { selectContextFilesForModel } from "./model-prompt-policy.js";
 import { findExactModelReferenceMatch } from "./model-resolver.js";
 import { computePromptTokenBudget } from "./prompt-budget.js";
 import { classifyPromptCacheTransition } from "./prompt-cache.js";
-import { createPromptSettlementState, reducePromptSettlement, settlePromptIfReady, } from "./prompt-settlement.js";
+import * as promptSettlement from "./prompt-settlement.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
-import { isQuotaExhaustionMessage, isStickySafetyModel, pickFailoverCandidate, resolveProviderResilience, shouldEjectStickySafetyModel, shouldHonorSafetyFailover, stickySafetyBlockMessage, } from "./provider-resilience.js";
+import { isQuotaExhaustionMessage, isStickySafetyModel, isUpstreamUnavailableMessage, pickFailoverCandidate, resolveFailoverCandidates, resolveProviderResilience, sameModelRouteCandidates, shouldEjectStickySafetyModel, shouldHonorSafetyFailover, stickySafetyBlockMessage, } from "./provider-resilience.js";
 import { computeRetryDelayMs, failoverModelKey, isFailoverTriggerError, isRetryableAssistantError, nextRetryAttempt, retryBudgetForAssistantError, } from "./provider-retry.js";
 import { getBiasStepsForCell, parseRouterBiasSnapshot } from "./reasoning-router-bias.js";
 import { classifyTaskV4, deriveRouterFeedbackFeaturesV4, resolveThinkingLevelV4WithUncertainty, TASK_CLASS_THINKING_LEVELS_V4, } from "./reasoning-router-v4.js";
@@ -95,6 +96,7 @@ import { RunResourceLeaseController } from "./run-resource-lease.js";
 import { SessionBashRuntime } from "./session-bash-runtime.js";
 import { SessionBashService } from "./session-bash-service.js";
 import { SessionCompactionService } from "./session-compaction-service.js";
+import { preflightFailureCause, providerFailureCause, runtimeFailureCause, terminationMessage, } from "./session-failure-cause.js";
 import { CURRENT_SESSION_VERSION, getLatestCompactionEntry } from "./session-manager.js";
 import { acquireSessionOwnerLeaseSync } from "./session-owner-lease.js";
 import { assembleSessionSystemPrompt } from "./session-system-prompt.js";
@@ -171,103 +173,6 @@ function toolNameSetsEqual(left, right) {
     return (normalizedLeft.length === normalizedRight.length &&
         normalizedLeft.every((toolName, index) => toolName === normalizedRight[index]));
 }
-function snapshotContractError(reason) {
-    return new Error(`Finalized message replacement must be a plain serializable snapshot: ${reason}`);
-}
-/**
- * Clone a finalized message replacement into the JSON-compatible snapshot
- * persisted by SessionManager. Undefined remains allowed as ordinary optional
- * message data: JSON omits object properties with undefined values and writes
- * undefined array elements as null.
- */
-function clonePlainSnapshot(value, ancestors = new WeakSet(), copies = new WeakMap()) {
-    if (value === null)
-        return value;
-    switch (typeof value) {
-        case "string":
-        case "boolean":
-        case "undefined":
-            return value;
-        case "number":
-            if (!Number.isFinite(value)) {
-                throw snapshotContractError("non-finite number values are not allowed");
-            }
-            return value;
-        case "bigint":
-            throw snapshotContractError("bigint values are not allowed");
-        case "function":
-        case "symbol":
-            throw snapshotContractError(`${typeof value} values are not allowed`);
-        case "object":
-            break;
-        default:
-            throw snapshotContractError(`${typeof value} values are not allowed`);
-    }
-    if (ancestors.has(value)) {
-        throw snapshotContractError("cyclic values are not allowed");
-    }
-    if (copies.has(value)) {
-        return copies.get(value);
-    }
-    ancestors.add(value);
-    try {
-        if (Array.isArray(value)) {
-            const copy = [];
-            copy.length = value.length;
-            copies.set(value, copy);
-            for (const key of Reflect.ownKeys(value)) {
-                if (key === "length")
-                    continue;
-                if (typeof key !== "string" || !/^(0|[1-9]\d*)$/.test(key) || Number(key) >= value.length) {
-                    throw snapshotContractError("arrays may only contain indexed values");
-                }
-                const descriptor = Object.getOwnPropertyDescriptor(value, key);
-                if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) {
-                    throw snapshotContractError("accessor or non-enumerable properties are not allowed");
-                }
-                copy[Number(key)] = clonePlainSnapshot(descriptor.value, ancestors, copies);
-            }
-            return copy;
-        }
-        const prototype = Object.getPrototypeOf(value);
-        if (prototype !== Object.prototype && prototype !== null) {
-            throw snapshotContractError("non-plain objects are not allowed");
-        }
-        const copy = Object.create(prototype);
-        copies.set(value, copy);
-        for (const key of Reflect.ownKeys(value)) {
-            if (typeof key !== "string") {
-                throw snapshotContractError("symbol-keyed properties are not allowed");
-            }
-            const descriptor = Object.getOwnPropertyDescriptor(value, key);
-            if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) {
-                throw snapshotContractError("accessor or non-enumerable properties are not allowed");
-            }
-            Object.defineProperty(copy, key, {
-                value: clonePlainSnapshot(descriptor.value, ancestors, copies),
-                enumerable: true,
-                configurable: true,
-                writable: true,
-            });
-        }
-        return copy;
-    }
-    finally {
-        ancestors.delete(value);
-    }
-}
-function freezeSnapshot(value, seen = new WeakSet()) {
-    if (value === null || typeof value !== "object" || seen.has(value))
-        return value;
-    seen.add(value);
-    for (const child of Object.values(value)) {
-        freezeSnapshot(child, seen);
-    }
-    return Object.freeze(value);
-}
-function createImmutableMessageSnapshot(message) {
-    return freezeSnapshot(clonePlainSnapshot(message));
-}
 // ============================================================================
 // AgentSession Class
 // ============================================================================
@@ -387,7 +292,7 @@ export class AgentSession {
     _workspaceMutationCount = 0;
     // Model registry for API key resolution
     _modelRegistry;
-    /** Lazy, in-memory only; never shared across sessions or persisted. */
+    /** Lazy provider: representations persist per workspace by default; plans stay session-memory-only. */
     _contextBudgetCacheProvider;
     _contextCacheInvalidationSnapshot;
     // Tool registry for extension getTools/setTools
@@ -599,78 +504,6 @@ export class AgentSession {
         });
         this._appendReplayEvent(event, details);
     }
-    _terminationMessage(value, fallback) {
-        const redacted = redactSensitiveText(value?.trim() || fallback)
-            .replace(/\0/g, "")
-            .slice(0, 512);
-        return redacted || fallback;
-    }
-    _providerFailureCause(message) {
-        const text = message.errorMessage ?? "";
-        if (isContextOverflow(message, this.model?.contextWindow ?? 0)) {
-            return { area: "provider", code: "context_overflow" };
-        }
-        // Fable/Claude often emit stop_reason=refusal on benign turns (false positive).
-        // Match broadly so we never mislabel these as provider.protocol.
-        if (/stop_reason\s*=\s*(refusal|sensitive)|content\/safety stop|safety stop|provider\.refusal|kind=provider_refusal/i.test(text)) {
-            return { area: "provider", code: "refusal" };
-        }
-        // Quota/billing exhaustion is checked BEFORE the generic 401/403 auth
-        // patterns: "403 ... usage limit for this billing cycle" is transient per
-        // cycle and must fail over, not terminate the turn as an auth error.
-        if (isQuotaExhaustionMessage(text) || /rate.?limit|too many requests|429/i.test(text)) {
-            return { area: "provider", code: "rate_limit" };
-        }
-        if (/auth|unauthori[sz]ed|forbidden|invalid.?api.?key|no api key|401|403|\/login/i.test(text)) {
-            return { area: "provider", code: "auth" };
-        }
-        // Kimi/K3 + OpenAI-compat: orphan tool results after dropped error assistants.
-        // Sanitize-and-retry (transform-messages drops orphans), not a hard tool fatal.
-        if (/tool_call_id\s+is\s+not\s+found|tool_call_id\s+not\s+found|unknown\s+tool_call_id/i.test(text)) {
-            return { area: "provider", code: "protocol" };
-        }
-        if (/tool.+timed? out|tool.+timeout/i.test(text))
-            return { area: "tool", code: "timeout" };
-        if (/\btool\b/i.test(text) && !/tool_call_id/i.test(text))
-            return { area: "tool", code: "fatal" };
-        if (/network|fetch failed|connection|socket|websocket|timed? out|timeout|dns|econn|^terminated$/i.test(text)) {
-            return { area: "provider", code: "network" };
-        }
-        return { area: "provider", code: "protocol" };
-    }
-    _classifyPreflightCause(message) {
-        if (!this.model || /no model|model selected|model is required/i.test(message)) {
-            return { area: "configuration", code: "invalid" };
-        }
-        if (isQuotaExhaustionMessage(message)) {
-            return { area: "provider", code: "rate_limit" };
-        }
-        if (/auth|api key|unauthori[sz]ed|forbidden|401|403|\/login/i.test(message)) {
-            return { area: "provider", code: "auth" };
-        }
-        if (/context.+overflow|context window|too many tokens/i.test(message)) {
-            return { area: "provider", code: "context_overflow" };
-        }
-        if (/duplicate.?result/i.test(message))
-            return { area: "transcript", code: "duplicate_result" };
-        if (/orphan.?result/i.test(message))
-            return { area: "transcript", code: "orphan_result" };
-        if (/duplicate.?call/i.test(message))
-            return { area: "transcript", code: "duplicate_call_id" };
-        if (/transcript|missing.?result/i.test(message))
-            return { area: "transcript", code: "missing_result" };
-        if (/compaction/i.test(message))
-            return { area: "compaction", code: "failed" };
-        if (/fsync/i.test(message))
-            return { area: "persistence", code: "fsync_failed" };
-        if (/lock/i.test(message))
-            return { area: "persistence", code: "lock_failed" };
-        if (/append|persist|write/i.test(message))
-            return { area: "persistence", code: "append_failed" };
-        if (/tool/i.test(message))
-            return { area: "tool", code: "fatal" };
-        return { area: "internal", code: "unclassified" };
-    }
     _classifyRunTermination(runId, event) {
         const timestamp = new Date().toISOString();
         let assistant;
@@ -699,11 +532,11 @@ export class AgentSession {
         }
         else if (assistant.stopReason === "aborted") {
             cause = this._userAbortRequested ? { area: "user", code: "abort" } : { area: "provider", code: "abort" };
-            message = this._terminationMessage(assistant.errorMessage, this._userAbortRequested ? "The user aborted the run." : "The provider aborted the run.");
+            message = terminationMessage(assistant.errorMessage, this._userAbortRequested ? "The user aborted the run." : "The provider aborted the run.");
         }
         else if (assistant.stopReason === "error") {
-            cause = this._providerFailureCause(assistant);
-            message = this._terminationMessage(assistant.errorMessage, "The provider request failed.");
+            cause = providerFailureCause(assistant, this.model?.contextWindow ?? 0);
+            message = terminationMessage(assistant.errorMessage, "The provider request failed.");
         }
         else {
             cause = { area: "completed" };
@@ -733,24 +566,8 @@ export class AgentSession {
         this._lastTermination = termination;
         this._emit({ type: "session_termination", termination });
     }
-    _runtimeFailureCause(error) {
-        if (this._pendingRuntimeTerminationCause)
-            return this._pendingRuntimeTerminationCause;
-        const code = typeof error === "object" && error !== null && "code" in error ? Reflect.get(error, "code") : undefined;
-        if (typeof code === "string" &&
-            new Set(["EACCES", "EDQUOT", "EFBIG", "EIO", "EISDIR", "EMFILE", "ENFILE", "ENOSPC", "EPERM", "EROFS"]).has(code)) {
-            return { area: "persistence", code: "append_failed" };
-        }
-        const message = error instanceof Error ? error.message : String(error);
-        if (/compaction.+stale|session changed during compaction/i.test(message)) {
-            return { area: "compaction", code: "stale" };
-        }
-        if (/compaction/i.test(message))
-            return { area: "compaction", code: "failed" };
-        return { area: "internal", code: "unclassified" };
-    }
     _publishRuntimeFailure(error) {
-        const cause = this._runtimeFailureCause(error);
+        const cause = this._pendingRuntimeTerminationCause ?? runtimeFailureCause(error);
         const runId = this._activeRunId ?? `runtime-${randomUUID()}`;
         const timestamp = new Date().toISOString();
         let message = "The AgentSession runtime failed before completing the run.";
@@ -915,7 +732,7 @@ export class AgentSession {
         throw new Error(formatNoApiKeyFoundMessage(model.provider));
     }
     async _getCompactionRequestAuth(model) {
-        if (this.agent.streamFn === streamSimple) {
+        if (isBuiltinStreamFn(this.agent.streamFn)) {
             return this._getRequiredRequestAuth(model);
         }
         const result = await this._modelRegistry.getApiKeyAndHeaders(model);
@@ -1130,6 +947,11 @@ export class AgentSession {
         }
         else if (event.type === "agent_end") {
             await this._extensionRunner.emit({ type: "agent_end", messages: event.messages });
+            // `agent_end` fires once per attempt. Extensions that release per-run
+            // state need the boundary no retry follows, so mark it explicitly.
+            if (!this._willRetryAfterAgentEnd(event)) {
+                await this._extensionRunner.emit({ type: "agent_settled", messages: event.messages });
+            }
         }
         else if (event.type === "turn_start") {
             this._turnMetricsState = {
@@ -1694,12 +1516,12 @@ export class AgentSession {
             }
         }
         catch (error) {
-            outcome =
-                this._userAbortRequested || (error instanceof Error && /abort/i.test(error.message)) ? "aborted" : "failed";
+            outcome = "failed";
             this._publishRuntimeFailure(error);
             throw error;
         }
         finally {
+            outcome = promptSettlement.resolvePromptSettlementOutcome(outcome, this._lastTermination?.kind);
             if (resourceLease !== null) {
                 // Generation-safe: a stale release after another run acquired the
                 // lease is a no-op instead of clobbering the newer cap (§8.1).
@@ -1720,15 +1542,15 @@ export class AgentSession {
      */
     _emitPromptSettledIfReady(input) {
         try {
-            let state = createPromptSettlementState(input.promptRunId, input.startedAtEpochMs);
-            state = reducePromptSettlement(state, { kind: "terminal", outcome: input.outcome });
+            let state = promptSettlement.createPromptSettlementState(input.promptRunId, input.startedAtEpochMs);
+            state = promptSettlement.reducePromptSettlement(state, { kind: "terminal", outcome: input.outcome });
             if (this.isStreaming) {
-                state = reducePromptSettlement(state, { kind: "tool", delta: 1 });
+                state = promptSettlement.reducePromptSettlement(state, { kind: "tool", delta: 1 });
             }
             if (this.agent.hasQueuedMessages()) {
-                state = reducePromptSettlement(state, { kind: "continuation", delta: 1 });
+                state = promptSettlement.reducePromptSettlement(state, { kind: "continuation", delta: 1 });
             }
-            const settled = settlePromptIfReady(state, Date.now());
+            const settled = promptSettlement.settlePromptIfReady(state, Date.now());
             if (settled.event !== null) {
                 input.resourceObservations?.record("prompt_settled_v1", settledObservationFacts(settled.event));
                 this._emit(settled.event);
@@ -2017,7 +1839,7 @@ export class AgentSession {
             // Emit input event for extension interception (before skill/template expansion)
             let currentImages = options?.images;
             if (this._extensionRunner.hasHandlers("input")) {
-                const inputResult = await this._extensionRunner.emitInput(currentText, currentImages, options?.source ?? "interactive", this.isStreaming ? options?.streamingBehavior : undefined);
+                const inputResult = await this._extensionRunner.emitInput(currentText, currentImages, options?.source ?? "interactive", this.isStreaming || this.isRetrying ? options?.streamingBehavior : undefined);
                 if (inputResult.action === "handled") {
                     preflightResult?.(true);
                     return;
@@ -2034,8 +1856,8 @@ export class AgentSession {
                 expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
             }
             expandedText = redactSensitiveText(expandedText);
-            // If streaming, queue via steer() or followUp() based on option
-            if (this.isStreaming) {
+            // While a run or its retry backoff owns the session, queue instead of starting a competing top-level prompt.
+            if (this.isStreaming || this.isRetrying) {
                 if (!options?.streamingBehavior) {
                     throw new Error("Agent is already processing. Specify streamingBehavior ('steer' or 'followUp') to queue the message.");
                 }
@@ -2143,14 +1965,14 @@ export class AgentSession {
         catch (error) {
             preflightResult?.(false);
             const rawMessage = error instanceof Error ? error.message : String(error);
-            const cause = this._classifyPreflightCause(rawMessage);
+            const cause = preflightFailureCause(rawMessage, Boolean(this.model));
             const timestamp = new Date().toISOString();
             this._publishTermination(classifySessionTermination({
                 sessionId: this.sessionId,
                 runId: `preflight-${randomUUID()}`,
                 timestamp,
                 source: "observed",
-                message: this._terminationMessage(rawMessage, "Prompt preflight failed."),
+                message: terminationMessage(rawMessage, "Prompt preflight failed."),
                 cause,
                 sideEffects: "none",
                 ...(this.model ? { provider: this.model.provider, model: this.model.id } : {}),
@@ -2532,7 +2354,7 @@ export class AgentSession {
     }
     async _cycleAvailableModel(direction) {
         const resilience = resolveProviderResilience(this.settingsManager.getProviderResilienceSettings());
-        const raw = await this._modelRegistry.getAvailable();
+        const raw = this._modelRegistry.getAvailable();
         // Hard-kill sticky safety models from the cycle list (Fable must not re-enter via hotkey).
         const availableModels = resilience.blockStickySafetyModels
             ? raw.filter((m) => !isStickySafetyModel(m.id, m.provider))
@@ -2736,8 +2558,8 @@ export class AgentSession {
     /**
      * Context-pressure band 0..3 from the projected token estimate over the
      * model context window (reuses estimateProjectedContextTokens). 0..<0.5,
-     * 1..<0.75, 2..<0.9, 3..>=0.9. Inert under DEFAULT_WEIGHTS (no pressure
-     * coefficient); computed for future calibrated weight presets.
+     * 1..<0.75, 2..<0.9, 3..>=0.9. The released default pressure coefficient
+     * is 1 and participates only after the classifier has prompt evidence.
      */
     _computePressureBucket() {
         const contextWindow = this.model?.contextWindow ?? 0;
@@ -2986,6 +2808,25 @@ export class AgentSession {
         });
         return model;
     }
+    /**
+     * Authenticated failover candidates for compaction summarization, in
+     * resilience-chain order, excluding the primary compaction model itself.
+     * Used when the primary model's quota is exhausted (same-model retry is
+     * useless until reset; another provider can still save the compaction).
+     */
+    _compactionFailoverModels(primary) {
+        const candidates = resolveFailoverCandidates(this.settingsManager.getProviderResilienceSettings());
+        const available = this._modelRegistry.getAvailable();
+        const models = [];
+        for (const candidate of candidates) {
+            if (candidate.provider === primary.provider && candidate.id === primary.id)
+                continue;
+            const resolved = available.find((m) => m.provider === candidate.provider && m.id === candidate.id);
+            if (resolved)
+                models.push(resolved);
+        }
+        return models;
+    }
     /**
      * Manually compact the session context.
      * Aborts current agent operation first.
@@ -3046,7 +2887,7 @@ export class AgentSession {
             }
             else {
                 // Generate compaction result
-                const result = await compact(preparation, compactionModel, apiKey, headers, customInstructions, this._compactionAbortController.signal, this.thinkingLevel, this.agent.streamFn, this.settingsManager.getRetrySettings(), this._summarizationRetryCallbacks({ source: "compaction", reason: "manual" }));
+                const result = await compact(preparation, compactionModel, apiKey, headers, customInstructions, this._compactionAbortController.signal, this.thinkingLevel, this.agent.streamFn, this.settingsManager.getRetrySettings(), this._summarizationRetryCallbacks({ source: "compaction", reason: "manual" }), this._compactionFailoverModels(compactionModel));
                 summary = result.summary;
                 firstKeptEntryId = result.firstKeptEntryId;
                 tokensBefore = result.tokensBefore;
@@ -3089,13 +2930,15 @@ export class AgentSession {
                 compactionCode = "aborted";
             else if (stale)
                 compactionCode = "stale";
+            else if (isQuotaExhaustionMessage(message))
+                compactionCode = "quota_exhausted";
             const timestamp = new Date().toISOString();
             this._publishTermination(classifySessionTermination({
                 sessionId: this.sessionId,
                 runId: `compaction-${randomUUID()}`,
                 timestamp,
                 source: "observed",
-                message: this._terminationMessage(message, "Manual compaction failed."),
+                message: terminationMessage(message, "Manual compaction failed."),
                 cause: { area: "compaction", code: compactionCode },
                 sideEffects: committedCompaction ? "confirmed" : "none",
                 ...(this.model ? { provider: this.model.provider, model: this.model.id } : {}),
@@ -3142,7 +2985,7 @@ export class AgentSession {
     /**
      * Effective context window for the upcoming turn.
      * Image-bearing turns with a text-only session model are auto-routed to the
-     * vision model (gpt-5.6-luna, 400K) — that window is the real limit. Text-only
+     * vision model (gpt-5.6-luna, 1M) — that window is the real limit. Text-only
      * turns keep the session model's (typically much larger) window.
      */
     _effectiveTurnContextWindow(pendingMessages, sessionWindow) {
@@ -3305,7 +3148,7 @@ export class AgentSession {
             const compactionModel = this._resolveCompactionModel(this.model);
             let apiKey;
             let headers;
-            if (this.agent.streamFn === streamSimple) {
+            if (isBuiltinStreamFn(this.agent.streamFn)) {
                 const authResult = await this._modelRegistry.getApiKeyAndHeaders(compactionModel);
                 if (!authResult.ok || !authResult.apiKey) {
                     const providerLabel = compactionModel.provider;
@@ -3377,7 +3220,7 @@ export class AgentSession {
             }
             else {
                 // Generate compaction result
-                const compactResult = await compact(preparation, compactionModel, apiKey, headers, undefined, this._autoCompactionAbortController.signal, this.thinkingLevel, this.agent.streamFn, this.settingsManager.getRetrySettings(), this._summarizationRetryCallbacks({ source: "compaction", reason }));
+                const compactResult = await compact(preparation, compactionModel, apiKey, headers, undefined, this._autoCompactionAbortController.signal, this.thinkingLevel, this.agent.streamFn, this.settingsManager.getRetrySettings(), this._summarizationRetryCallbacks({ source: "compaction", reason }), this._compactionFailoverModels(compactionModel));
                 summary = compactResult.summary;
                 firstKeptEntryId = compactResult.firstKeptEntryId;
                 tokensBefore = compactResult.tokensBefore;
@@ -3992,6 +3835,41 @@ export class AgentSession {
         // setModel itself blocks sticky targets, not sources — safe.
         await this.setModel(next);
     }
+    /**
+     * Rotate to another authenticated provider route serving the SAME model
+     * family (e.g. openrouter/stealth/ox-alpha ↔ opencode-go/ox-alpha-free ↔
+     * opencode/x-preview-f-free). Used when the current route fails with an
+     * upstream availability error — same-model retry would hammer a dead
+     * endpoint while the identical model is one route away. Visited and
+     * unauthenticated routes are marked in {@link _refusedModels} so repeat
+     * failures advance the rotation within the turn.
+     */
+    async _maybeRotateModelRoutes() {
+        const current = this.model;
+        if (!current)
+            return undefined;
+        const candidates = sameModelRouteCandidates(current, this._modelRegistry.getAvailable());
+        for (const candidate of candidates) {
+            const key = failoverModelKey(candidate.provider, candidate.id);
+            if (this._refusedModels.has(key))
+                continue;
+            const next = this._modelRegistry.find(candidate.provider, candidate.id);
+            if (!next || !this._modelRegistry.hasConfiguredAuth(next)) {
+                this._refusedModels.add(key);
+                continue;
+            }
+            try {
+                await this.setModel(next);
+                // The old route just failed upstream — keep it out of this turn's retries.
+                this._refusedModels.add(failoverModelKey(current.provider, current.id));
+                return `${next.provider}/${next.id}`;
+            }
+            catch {
+                this._refusedModels.add(key);
+            }
+        }
+        return undefined;
+    }
     /**
      * Content/safety stops (stop_reason=refusal) are often false positives on coding turns
      * for Fable AND Claude Opus/Sonnet. Retrying the same model usually reprints the refusal —
@@ -4053,12 +3931,19 @@ export class AgentSession {
         if (attempt === undefined)
             return false;
         this._retryAttempt = attempt;
+        // Upstream-unavailable (gateway 5xx / dropped stream): rotate to another
+        // authenticated route of the SAME model family so the retry lands on a
+        // live endpoint instead of hammering the dead one.
+        const rotatedTo = isUpstreamUnavailableMessage(message.errorMessage)
+            ? await this._maybeRotateModelRoutes()
+            : undefined;
         // Content/safety stop (Fable/Opus/Sonnet): switch model BEFORE delay so retry is not same-model refusal.
         const failoverTo = await this._maybeFailoverFromSafetyStop(message);
+        const switchedVia = failoverTo ? `failover ${failoverTo}` : rotatedTo ? `route ${rotatedTo}` : undefined;
         // Safety stops are usually immediate false positives — short delay after failover, full backoff otherwise.
-        const delayMs = computeRetryDelayMs(settings.baseDelayMs, attempt, failoverTo !== undefined);
-        const errorMessage = failoverTo
-            ? `${message.errorMessage || "content/safety stop"} → failover ${failoverTo}`
+        const delayMs = computeRetryDelayMs(settings.baseDelayMs, attempt, switchedVia !== undefined);
+        const errorMessage = switchedVia
+            ? `${message.errorMessage || "content/safety stop"} → ${switchedVia}`
             : message.errorMessage || "Unknown error";
         this._emit({
             type: "auto_retry_start",