Two gates, not oneA correct CONTEXT_WINDOW_EXCEEDED classification only opens recovery. The summary request must still fit its route and replace the selected range with a complete smaller checkpoint.

Classification decides whether recovery runs.

Recognized pathCONTEXT_WINDOW_EXCEEDEDprune → compact → retry

The compaction listener receives its exact machine code.

Missed path in rc.7INVALID_REQUESTfail → manual recovery

The same physical overflow bypasses the listener.

Read the body, not only the provider code.

{
  "message": "Input token exceed the limit",
  "type": "api_error",
  "code": "quota_limit_reached"
}
Do not widen blindly.

quota_limit_reached can also describe account or monthly usage limits. Match the context wording narrowly and retain the raw response beside the normalized error.

Budget the next request before sending it.

history tokens+tool and system tokens+requested output<model context window

Price the recovery request separately.

Conversationsystem + tools + visible history+ requested output

This is the envelope the provider rejected.

Compactionsystem + tools + selected replay+ instruction + summary output

A recovery label does not make this envelope smaller.

A smaller model is a capacity transition.

Pre-step checklast durable route: 1Mold threshold

rc.2 pressure handling reads the latest Session request header.

Request buildpending route: 200Knew denominator

The smaller capacity is recorded after pre-step, before the provider call.

Compact before the downgrade.If prompt plus requested output cannot fit 200K with headroom, compact while the approved 1M route can still read the Session—or continue in a new Session with a concise handoff.

Stop a stable failure fingerprint.

trigger + route + replaceGeneration
+ selected start:end + token count
+ finish reason + normalized error
No adaptive change, no repeat.

Expand the balanced range, reduce retention, change the approved summary route, or terminate durably. Never weaken the complete-and-smaller checkpoint invariant.

Recover in a bounded order.

  1. 01Capture

    Save the raw body, normalized code, model, adapter, and request ID.

  2. 02Lower output

    Reduce maxTokens only if the history still leaves usable headroom.

  3. 03Compact once

    Try /compact once. Stop if its summarizer also exceeds context.

  4. 04Continue cleanly

    Open a new Session with a concise handoff and links to retained evidence.

Regression needs a positive and a negative.

Must classifyInput token exceed the limitCONTEXT_WINDOW_EXCEEDED
Must not classifyMonthly usage quota exceededusage or account limit

Acceptance gates.

Primary evidence.

Keep the complete runbook.

The canonical guide includes capture fields, request arithmetic, failure fingerprints, decision branches, and twelve convergence checks.

Read the full overflow runbook