fix: detect context-overflow errors separately from retryable failures (#1312)

* fix: detect context-overflow errors separately from retryable failures

Context-overflow errors ("maximum context length", "too many tokens",
"context_length_exceeded", etc.) mean the input is too large for the
model's window. Retrying the same input on another model cannot succeed,
yet today these errors can match generic retryable patterns and burn
fallback attempts on a guaranteed failure.

Add isContextOverflow() as a dedicated, non-retryable classifier so
callers can stop the fallback loop early and surface a clear
"input too large" error. Tool-failure prefixed errors are excluded,
matching isRetryableModelFailure's convention.

* docs: credit context overflow contribution

---------

Co-authored-by: Nico Bailon <nico.bailon@gmail.com>

Author: srcKod

CHANGELOG.md

@@ -13,6 +13,7 @@
   profile examples (#1295).
 
 ### Fixed
+- Add a separate classifier for model context-overflow errors. Thanks to [@srcKod](https://github.com/srcKod) for #1312.
 - Quote only confidently identified leading Windows executable paths in acceptance verification commands. Thanks to [@srcKod](https://github.com/srcKod) for #1294.
 
 ### Changed

src/runs/shared/model-fallback.ts

@@ -424,6 +424,34 @@ export function isRetryableModelFailure(error: string | undefined): boolean {
 	return RETRYABLE_MODEL_FAILURE_PATTERNS.some((pattern) => pattern.test(error));
 }
 
+/**
+ * Context-overflow signals. These are deliberately NOT part of
+ * {@link RETRYABLE_MODEL_FAILURE_PATTERNS}: an overflow means the input was too
+ * large for the model's context window, so retrying the same input on another
+ * model (or the same model again) cannot succeed. Callers should treat overflow
+ * as a terminal, non-retryable failure and surface a clear "input too large"
+ * error instead of burning fallback attempts on a guaranteed failure.
+ */
+const CONTEXT_OVERFLOW_PATTERNS = [
+	/context(?: length| window| limit)? (?:exceed|overflow|too long)/i,
+	/maximum context length/i,
+	/too many tokens/i,
+	/token limit/i,
+	/context_length_exceeded/i,
+	/length_required/i,
+	/maximum.*tokens/i,
+	/prompt.*too long/i,
+	/input.*too long/i,
+	/exceeded.*context/i,
+	/context.*overflow/i,
+];
+
+export function isContextOverflow(error: string | undefined): boolean {
+	if (!error) return false;
+	if (TOOL_FAILURE_PREFIX.test(error.trim())) return false;
+	return CONTEXT_OVERFLOW_PATTERNS.some((pattern) => pattern.test(error));
+}
+
 export function formatModelAttemptNote(attempt: ModelAttemptSummary, nextModel?: string): string {
 	const failure = attempt.error?.trim() || `exit ${attempt.exitCode ?? 1}`;
 	return nextModel

test/unit/model-fallback.test.ts

@@ -3,6 +3,7 @@ import { describe, it } from "node:test";
 import {
 	buildModelCandidates,
 	fuzzyResolveModel,
+	isContextOverflow,
 	isRetryableModelFailure,
 	normalizeModelSegment,
 	resolveEffectiveSubagentModel,
@@ -529,3 +530,29 @@ describe("resolveSubagentModelOverride scope enforcement", () => {
 		);
 	});
 });
+
+describe("isContextOverflow", () => {
+	it("detects common context-overflow error shapes", () => {
+		assert.equal(isContextOverflow("This model's maximum context length is 8192 tokens"), true);
+		assert.equal(isContextOverflow("context length exceeded for the requested prompt"), true);
+		assert.equal(isContextOverflow("too many tokens in the request"), true);
+		assert.equal(isContextOverflow("context_length_exceeded"), true);
+		assert.equal(isContextOverflow("prompt is too long for this model"), true);
+		assert.equal(isContextOverflow("input too long: 40000 tokens"), true);
+	});
+
+	it("does not flag unrelated retryable failures as overflow", () => {
+		assert.equal(isContextOverflow("rate limit exceeded for provider"), false);
+		assert.equal(isContextOverflow("503 service unavailable"), false);
+		assert.equal(isContextOverflow("connection refused"), false);
+	});
+
+	it("does not flag tool failures as overflow", () => {
+		assert.equal(isContextOverflow("bash failed (exit 1): context length exceeded in output"), false);
+	});
+
+	it("returns false for empty or undefined input", () => {
+		assert.equal(isContextOverflow(undefined), false);
+		assert.equal(isContextOverflow(""), false);
+	});
+});