Merge pull request #744 from code-yeongyu/fix/429-no-fallback-in-turn-retry

fix(session): degrade fallback-unavailable 429s to in-turn retry

Author: code-yeongyu

.agents/skills/senpi-qa/scripts/lib/mock-loop-hint-429.mjs

@@ -15,6 +15,10 @@
  *                           immediate fallback, bounded probe-back, probe ok
  *                           clears the cooldown and the next turn restores the
  *                           primary.
+ *   no-hint-429-no-chain    No hint AND no usable fallback chain: the turn
+ *                           degrades to bounded same-model in-turn retries on
+ *                           the exponential schedule instead of dying with
+ *                           "Retry failed after 0 attempts".
  *
  * Every wait is bounded by a scripted hint measured in seconds, and every
  * assertion waits on an EVENT (never a fixed sleep), so runs are deterministic.
@@ -36,8 +40,14 @@ const FALLBACK_MARKER = "SENPI-QA-HINT429-FALLBACK-6c1b";
 const IN_TURN_HINT_SECONDS = 8;
 const PROBE_BACK_HINT_MS = 4000;
 const PROBE_BACK_CAP_MS = 1000;
+const NO_CHAIN_BASE_DELAY_MS = 50;
 
-export const HINT_429_SCENARIOS = ["hinted-429-in-turn", "no-hint-429-fast-fallback", "hinted-429-probe-back"];
+export const HINT_429_SCENARIOS = [
+	"hinted-429-in-turn",
+	"no-hint-429-fast-fallback",
+	"hinted-429-probe-back",
+	"no-hint-429-no-chain",
+];
 
 export function isHint429Scenario(name) {
 	return HINT_429_SCENARIOS.includes(name);
@@ -251,15 +261,30 @@ export async function runHint429Scenario({ scenarioName, apiName, evidenceSlug }
 			? { primaryLimitedRequests: 2, rateLimitHeaders: { "retry-after": String(IN_TURN_HINT_SECONDS) }, rateLimitMessage: "primary rate limited" }
 			: scenarioName === "no-hint-429-fast-fallback"
 				? { primaryLimitedRequests: 4, rateLimitMessage: "All tokens rate limited" }
-				: { primaryLimitedRequests: 1, rateLimitHeaders: { "retry-after-ms": String(PROBE_BACK_HINT_MS) }, rateLimitMessage: "primary rate limited" };
+				: scenarioName === "no-hint-429-no-chain"
+					? { primaryLimitedRequests: 2, rateLimitMessage: "All tokens rate limited" }
+					: { primaryLimitedRequests: 1, rateLimitHeaders: { "retry-after-ms": String(PROBE_BACK_HINT_MS) }, rateLimitMessage: "primary rate limited" };
 	const server = await startHint429Server({ ...script, primaryMarker: PRIMARY_MARKER, fallbackMarker: FALLBACK_MARKER });
-	writeMockModelsJson(box.agentDir, server, API_NAME, {}, {
-		models: [{ id: HINT_429_FALLBACK_MODEL_ID }],
-		retry:
-			scenarioName === "hinted-429-probe-back"
-				? retrySettings({ hintedWaitCapMs: PROBE_BACK_CAP_MS, probeBackMaxMs: 3_600_000 })
-				: retrySettings(),
-	});
+	// The no-chain scenario registers NO fallback model and NO chain, so the
+	// shipped default chains cannot resolve for the mock primary either.
+	const mockExtras =
+		scenarioName === "no-hint-429-no-chain"
+			? {
+					retry: {
+						enabled: true,
+						maxRetries: 3,
+						baseDelayMs: NO_CHAIN_BASE_DELAY_MS,
+						provider: { maxRetries: 0, maxRetryDelayMs: 60000 },
+					},
+				}
+			: {
+					models: [{ id: HINT_429_FALLBACK_MODEL_ID }],
+					retry:
+						scenarioName === "hinted-429-probe-back"
+							? retrySettings({ hintedWaitCapMs: PROBE_BACK_CAP_MS, probeBackMaxMs: 3_600_000 })
+							: retrySettings(),
+				};
+	writeMockModelsJson(box.agentDir, server, API_NAME, {}, mockExtras);
 	const client = new HintRpcClient({
 		env: hermeticEnv(box.env),
 		cwd: box.cwd,
@@ -270,6 +295,7 @@ export async function runHint429Scenario({ scenarioName, apiName, evidenceSlug }
 		await client.send({ type: "get_state" }); // ensure the session booted
 		if (scenarioName === "hinted-429-in-turn") await assertInTurn(checks, client, server, texts);
 		else if (scenarioName === "no-hint-429-fast-fallback") await assertFastFallback(checks, client, server, texts);
+		else if (scenarioName === "no-hint-429-no-chain") await assertNoChainDegrade(checks, client, server, texts);
 		else await assertProbeBack(checks, client, server, texts);
 		process.stdout.write(`SENPI_QA_HINT429_TRANSCRIPT ${transcript(scenarioName, server, client)}\n`);
 		checkRealAuthUnchanged(checks, guard);
@@ -357,6 +383,33 @@ async function assertFastFallback(checks, client, server, texts) {
 	);
 }
 
+/** No hint AND no usable chain: bounded same-model in-turn retries instead of a dead turn. */
+async function assertNoChainDegrade(checks, client, server, texts) {
+	texts.push(await runOneTurn(client, `Return ${PRIMARY_MARKER} once the scripted rate limit clears.`));
+	const models = server.requests.map((request) => request.model);
+	checks.ok(
+		"no-hint-429-no-chain: all three attempts stay on the primary model",
+		models.length === 3 && models.every((model) => model === HINT_429_PRIMARY_MODEL_ID),
+		`sequence=${models.join(" -> ") || "none"}`,
+	);
+	checks.ok(
+		"no-hint-429-no-chain: zero fallback switches",
+		client.events.filter((event) => event.type === "retry_fallback_applied").length === 0,
+		`retry_fallback_applied=${client.events.filter((event) => event.type === "retry_fallback_applied").length}`,
+	);
+	const delays = client.events.filter((event) => event.type === "auto_retry_start").map((event) => event.delayMs);
+	checks.ok(
+		"no-hint-429-no-chain: two exponential in-turn waits are scheduled",
+		delays.length === 2 && delays[0] === NO_CHAIN_BASE_DELAY_MS && delays[1] === NO_CHAIN_BASE_DELAY_MS * 2,
+		`delayMs=${delays.join(",") || "none"} expected=${NO_CHAIN_BASE_DELAY_MS},${NO_CHAIN_BASE_DELAY_MS * 2}`,
+	);
+	checks.ok(
+		"no-hint-429-no-chain: the degraded retry recovers on the primary model",
+		texts[0].includes(PRIMARY_MARKER),
+		`text=${texts[0].slice(0, 80)}`,
+	);
+}
+
 /** Tier 2: hint above the shrunk cap -> immediate fallback + bounded probe-back that restores the primary. */
 async function assertProbeBack(checks, client, server, texts) {
 	texts.push(await runOneTurn(client, `Return ${FALLBACK_MARKER} from whichever model can serve this turn.`));

.agents/skills/senpi-qa/scripts/mock-loop.mjs

@@ -26,7 +26,7 @@
  *    startup flag and would try to load the path as a dotenv file before the script runs)
  *   node mock-loop.mjs --with-mcp-tool mcp_fx_tool_1 --tool-args '{"value":"ok"}'
  *   node mock-loop.mjs --scenario transient-recover|budget-exhaust|server-error-fallback|long-retry-after|billing-swap|anthropic-policy-refusal-fallback|kimi-xtml-thinking-recover
- *   node mock-loop.mjs --scenario hinted-429-in-turn|no-hint-429-fast-fallback|hinted-429-probe-back
+ *   node mock-loop.mjs --scenario hinted-429-in-turn|no-hint-429-fast-fallback|hinted-429-probe-back|no-hint-429-no-chain
  *   node mock-loop.mjs --run "prompt" [--api ...] [--evidence SLUG]
  */
 
@@ -628,7 +628,7 @@ if (argv[0] === "--self-test") {
 			"  node mock-loop.mjs --with-truncated-text-tool-leak --api <anthropic-messages|openai-completions>",
 			"  node mock-loop.mjs --with-mcp-tool <tool> [--tool-args JSON]",
 			"  node mock-loop.mjs --scenario <transient-recover|budget-exhaust|server-error-fallback|long-retry-after|billing-swap|anthropic-policy-refusal-fallback|kimi-xtml-thinking-recover|ttsr-collapse|ttsr-leak|ttsr-repetitive-turns> [--api <name>]",
-			"  node mock-loop.mjs --scenario <hinted-429-in-turn|no-hint-429-fast-fallback|hinted-429-probe-back>",
+			"  node mock-loop.mjs --scenario <hinted-429-in-turn|no-hint-429-fast-fallback|hinted-429-probe-back|no-hint-429-no-chain>",
 			"  node mock-loop.mjs --run <prompt> [--api <name>]",
 			`  APIs: ${ALL_APIS.join(", ")}`,
 			"",

packages/coding-agent/CHANGELOG.md

@@ -15,6 +15,12 @@
 
 ### Fixed
 
+- Fixed a 429/rate-limit failure without a retry-after hint killing the turn with "Retry failed after 0 attempts"
+  when no fallback chain was usable for the active model. Such failures now degrade to same-model in-turn retries on
+  the ordinary exponential schedule, hinted waits below the probe-back ceiling retry in-turn clamped to
+  `retry.hintedWaitCapMs`, hour-plus hinted waits name the provider-requested wait in the final error, and retry
+  exhaustion reports the true attempt count ([#744](https://github.com/code-yeongyu/senpi/pull/744)).
+
 ### Removed
 
 ## [2026.8.6] - 2026-08-06

packages/coding-agent/src/core/agent-session.ts

@@ -137,6 +137,8 @@ import { RetryFallbackController } from "./retry-fallback/controller.ts";
 import { SelectorCooldowns } from "./retry-fallback/cooldown.ts";
 import {
 	classifyRateLimitedWait,
+	degradeWithoutFallback,
+	type HintTier,
 	nextInTurnDelayMs,
 	type ProbePhase,
 	probeBackSchedule,
@@ -5758,6 +5760,56 @@ export class AgentSession {
 		};
 	}
 
+	/**
+	 * A 429-class failure with no usable fallback candidate must not fail the
+	 * turn with zero attempts: a provider answering 429 is asking for a retry.
+	 * No-hint and tier2 waits degrade to same-model in-turn retries under the
+	 * normal retry budget (tier2 clamps the hinted wait to the in-turn cap);
+	 * only tier3 hour-plus waits stay terminal, with the requested wait named
+	 * in the final error. Returns the in-turn retry delay, or undefined after
+	 * emitting the terminal auto_retry_end.
+	 */
+	private _degradeRateLimitedWithoutFallback(
+		tier: HintTier,
+		hintMs: number | undefined,
+		message: AssistantMessage,
+		errorMessage: string,
+	): number | undefined {
+		const settings = this.settingsManager.getRetrySettings();
+		const hintSettings = this.settingsManager.getHintPolicySettings();
+		const finishTurn = (attempt: number, finalError: string | undefined) => {
+			const exhaustedChainKey = this._retryFallback.exhaustedChainKey;
+			if (exhaustedChainKey) {
+				this._emit({ type: "retry_fallback_exhausted", chainKey: exhaustedChainKey, lastError: errorMessage });
+			}
+			this._emit({ type: "auto_retry_end", success: false, attempt, finalError });
+			this._retryAttempt = 0;
+			this._resetHintTierState();
+			this._resolveRetry();
+		};
+		const degraded = degradeWithoutFallback(
+			tier,
+			hintMs,
+			this._retryAttempt + 1,
+			settings.baseDelayMs,
+			hintSettings.hintedWaitCapMs,
+		);
+		if (degraded.kind === "fail") {
+			const waitSeconds = Math.ceil(degraded.hintMs / 1000);
+			finishTurn(
+				this._retryAttempt,
+				`Provider requested a ${waitSeconds}s wait before retrying and no usable fallback model is available. ${message.errorMessage ?? ""}`,
+			);
+			return undefined;
+		}
+		this._retryAttempt++;
+		if (this._retryAttempt > settings.maxRetries) {
+			finishTurn(this._retryAttempt - 1, message.errorMessage);
+			return undefined;
+		}
+		return degraded.delayMs;
+	}
+
 	/**
 	 * Handle retryable errors with exponential backoff.
 	 * @returns whether retry continuation started, was blocked by compaction, or was not handled
@@ -5861,29 +5913,15 @@ export class AgentSession {
 				const tier = classifyRateLimitedWait(hintMs, hintSettings);
 				is429TierRouted = true;
 				if (tier === "no-hint-fast-fallback") {
-					// Skip same-model retries entirely; fall back immediately.
+					// Fall back immediately when a candidate exists; otherwise degrade
+					// to same-model in-turn retries instead of failing the turn.
 					switchedFallback = await this._retryFallback.tryFallback("transient", { errorMessage });
 					if (switchedFallback) {
 						this._retryAttempt = 1;
 					} else {
-						const exhaustedChainKey = this._retryFallback.exhaustedChainKey;
-						if (exhaustedChainKey) {
-							this._emit({
-								type: "retry_fallback_exhausted",
-								chainKey: exhaustedChainKey,
-								lastError: errorMessage,
-							});
-						}
-						this._emit({
-							type: "auto_retry_end",
-							success: false,
-							attempt: 0,
-							finalError: message.errorMessage,
-						});
-						this._retryAttempt = 0;
-						this._resetHintTierState();
-						this._resolveRetry();
-						return "not-handled";
+						const degradedDelayMs = this._degradeRateLimitedWithoutFallback(tier, hintMs, message, errorMessage);
+						if (degradedDelayMs === undefined) return "not-handled";
+						hintTierDelayMs = degradedDelayMs;
 					}
 				} else if (tier === "tier1-in-turn") {
 					this._retryAttempt++;
@@ -5978,24 +6016,9 @@ export class AgentSession {
 							this._armProbeBackForDemotedSelector(selector, remainingHintMs);
 						}
 					} else {
-						const exhaustedChainKey = this._retryFallback.exhaustedChainKey;
-						if (exhaustedChainKey) {
-							this._emit({
-								type: "retry_fallback_exhausted",
-								chainKey: exhaustedChainKey,
-								lastError: errorMessage,
-							});
-						}
-						this._emit({
-							type: "auto_retry_end",
-							success: false,
-							attempt: 0,
-							finalError: message.errorMessage,
-						});
-						this._retryAttempt = 0;
-						this._resetHintTierState();
-						this._resolveRetry();
-						return "not-handled";
+						const degradedDelayMs = this._degradeRateLimitedWithoutFallback(tier, hintMs, message, errorMessage);
+						if (degradedDelayMs === undefined) return "not-handled";
+						hintTierDelayMs = degradedDelayMs;
 					}
 				}
 			}

packages/coding-agent/src/core/changes.md

@@ -1,5 +1,37 @@
 # changes
 
+## Degrade fallback-unavailable 429s to in-turn retry (2026-08-06)
+
+### What changed
+
+- A 429-class failure whose hint tier routes to fallback (`no-hint-fast-fallback`, tier2, tier3) no
+  longer fails the turn with `auto_retry_end { attempt: 0 }` when no fallback candidate is usable
+  (no chain for the model, chain exhausted, candidates cooling, or unauthenticated).
+- No-hint failures degrade to same-model in-turn retries on the ordinary `settings.retry`
+  exponential schedule; tier2 hinted waits retry in-turn with the wait clamped to
+  `hintedWaitCapMs`; tier3 (>= `probeBackMaxMs`) waits stay terminal but the final error now names
+  the provider-requested wait in seconds.
+- The pure policy is `degradeWithoutFallback` in `retry-fallback/hint-policy.ts`;
+  `agent-session.ts` routes both former instant-death branches through
+  `_degradeRateLimitedWithoutFallback`, which also reports the TRUE attempt count on budget
+  exhaustion.
+
+### Why
+
+- Providers that send hint-less 429s (e.g. wafer `server_overloaded` bodies that literally say
+  "Please retry shortly") killed the turn on the FIRST 429 for any model without a usable fallback
+  chain, surfacing "Retry failed after 0 attempts". sst/opencode retries such failures in-turn
+  with a visible countdown and openai/codex replays the turn within its stream budget; failing
+  with zero attempts was strictly worse than both.
+
+### Why this cannot be expressed externally
+
+- Retry admission, the retry promise, `_retryAttempt` accounting, and the hint tier router live in
+  `AgentSession._handleRetryableError`; an extension cannot re-enter the continuation path after
+  the fallback controller declines a candidate.
+- Expected merge-conflict zone: `agent-session.ts` `_handleRetryableError` 429 tier routing and the
+  `retry-fallback/hint-policy.ts` tail.
+
 ## Absolute-cap compaction rejection message (2026-08-05)
 
 - `describeCompactionRejection()` for `"per-turn-cap"` now reads "absolute compaction cap reached for

packages/coding-agent/src/core/retry-fallback/hint-policy.ts

@@ -81,3 +81,25 @@ export function nextInTurnDelayMs(
 		demoteToProbeBack: false,
 	};
 }
+
+export type DegradedRateLimitAction = { kind: "in-turn"; delayMs: number } | { kind: "fail"; hintMs: number };
+
+/**
+ * Policy for a 429-class failure when no fallback candidate is usable: no-hint
+ * (and tier1) failures retry in-turn on the exponential schedule, tier2 hints
+ * retry in-turn with the wait clamped to the in-turn cap, and only tier3
+ * (probe-back-max or longer) hinted waits stay terminal.
+ */
+export function degradeWithoutFallback(
+	tier: HintTier,
+	hintMs: number | undefined,
+	attempt: number,
+	baseDelayMs: number,
+	hintedWaitCapMs: number,
+): DegradedRateLimitAction {
+	if (tier === "tier3-fallback-only") return { kind: "fail", hintMs: hintMs ?? 0 };
+	if (tier === "tier2-fallback-probe-back") {
+		return { kind: "in-turn", delayMs: Math.min(hintMs ?? hintedWaitCapMs, hintedWaitCapMs) };
+	}
+	return { kind: "in-turn", delayMs: baseDelayMs * 2 ** (attempt - 1) };
+}

packages/coding-agent/test/suite/retry-fallback-hint-policy.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
 	classifyRateLimitedWait,
+	degradeWithoutFallback,
 	nextInTurnDelayMs,
 	probeBackSchedule,
 } from "../../src/core/retry-fallback/hint-policy.ts";
@@ -434,3 +435,34 @@ describe("nextInTurnDelayMs", () => {
 		expect(result.demoteToProbeBack).toBe(true);
 	});
 });
+
+// ---------------------------------------------------------------------------
+// degradeWithoutFallback
+// ---------------------------------------------------------------------------
+
+describe("degradeWithoutFallback", () => {
+	it("returns exponential in-turn delays for a no-hint 429", () => {
+		expect(degradeWithoutFallback("no-hint-fast-fallback", undefined, 1, BASE, CAP)).toEqual({
+			kind: "in-turn",
+			delayMs: BASE,
+		});
+		expect(degradeWithoutFallback("no-hint-fast-fallback", undefined, 3, BASE, CAP)).toEqual({
+			kind: "in-turn",
+			delayMs: BASE * 4,
+		});
+	});
+
+	it("clamps tier2 hinted waits to the in-turn cap", () => {
+		expect(degradeWithoutFallback("tier2-fallback-probe-back", CAP + 60_000, 1, BASE, CAP)).toEqual({
+			kind: "in-turn",
+			delayMs: CAP,
+		});
+	});
+
+	it("stays terminal for tier3 waits and reports the hint", () => {
+		expect(degradeWithoutFallback("tier3-fallback-only", PROBE_MAX, 1, BASE, CAP)).toEqual({
+			kind: "fail",
+			hintMs: PROBE_MAX,
+		});
+	});
+});