Gateway 413 body-limit rejection is misclassified as context overflow, wedging the session

[akshaytp1571]

Summary

When the configured provider sits behind a reverse proxy with a request-body limit
(nginx client_max_body_size, for example), a turn that carries a large inline
base64 image fails with 413 Request Entity Too Large. pi-ai's overflow patterns
match any leading HTTP 413 status, so the harness labels the turn
CONTEXT_WINDOW_EXCEEDED and runs compaction. Compaction cannot shrink an inline
image payload, so the retry dies with the same 413. Every subsequent turn ends in
error and the session cannot be continued.

Environment

• dsh 0.2.1-rc.2 (installed npm package), host restarted after the fix below
• Provider reached through a gateway that renders error pages as HTML
• Session log: ~/.dsh/sessions/<cwd>/<sessionId>/session.v4.jsonl.zstd

Reproduction

1. Configure a provider whose gateway caps the request body at roughly 1 MB.
2. Attach a screenshot large enough that the base64 payload crosses that cap.
3. Send any prompt.

Observed: turn/end with kind: "error" and

{
  "code": "CONTEXT_WINDOW_EXCEEDED",
  "message": "413 <html>\n<head><title>413 Request Entity Too Large</title></head>\n<body>\n<center><h1>413 Request Entity Too Large</h1></center>\n<hr><center>nginx</center>\n</body>\n</html>\n"
}

followed by a compaction attempt that fails with the same 413. The turn repeats
indefinitely.

Root cause

packages/llm/llm-pi-ai/src/stream.ts computes piAiOverflow through
isContextOverflow(), which delegates to pi-ai's OVERFLOW_PATTERNS. That list
includes /^(?:[\w -]+ API error \(413\):|413(?:\s|:|$))/i, so any message whose
text begins with 413 is treated as a context overflow regardless of what the
server actually said.

mapStopReason checks the pi-ai overflow result before the harness's own
classifier, and the harness's classifyPiAiError maps 413 to INVALID_REQUEST.
The broad pi-ai rule therefore wins and a request-size failure is reported as a
context-window failure.

Two consequences make this worse than a wrong label:

• Compaction is the wrong remedy. It rewrites text history, but an inline base64
  image is retained verbatim, so the payload size never drops.
• With retryPolicy.maxRetries left high and RATE_LIMIT in retryableCodes,
  the failure loop presents as a hang rather than an error.

Fix

Gate the pi-ai overflow branch on a check that separates a proxy body-limit
rejection from a provider context overflow. A body-limit rejection either renders
an HTML error page or carries no JSON body; a provider overflow reports a
structured error object.

Branch: fix/pi-ai-413-gateway-body-limit on
akshaytp1571/deepseek-harness (commit 69600080), based on f3803c96.

function isGatewayBodyLimitError(errorMessage: string): boolean {
  if (isContextWindowExceededError(errorMessage)) return false
  if (!/(?:^|[^\w])413(?:[^\w]|$)/i.test(errorMessage)) return false
  return /<(?:\/?)(?:html|head|title|body|center|hr)\b/i.test(errorMessage)
    || !/\{[\s\S]*\}/.test(errorMessage)
}

mapStopReason then returns the overflow branch only when the pi-ai overflow is
not a gateway body limit, so a 413 page keeps the harness's own
INVALID_REQUEST classification.

Tests

• packages/llm/llm-pi-ai/tests/convert.spec.ts — nginx HTML 413 and a bare
  413 Request Entity Too Large status line both map to INVALID_REQUEST; a
  structured 413 {"error":{"type":"request_too_large"}} body still maps to
  CONTEXT_WINDOW_EXCEEDED; github-copilot API error (413): {...} keeps its
  existing INVALID_REQUEST mapping.
• packages/llm/llm-pi-ai/tests/adapter.spec.ts — end-to-end, a mocked 413 HTML
  response maps to INVALID_REQUEST.

npx vitest run packages/llm/llm-pi-ai/tests/convert.spec.ts → 83 passed.
npx vitest run packages/llm/llm-pi-ai/tests/adapter.spec.ts --project process-bound → 56 passed.
npx oxlint packages/llm/llm-pi-ai → 0 warnings, 0 errors.
npx tsc -b packages/llm/llm-pi-ai/tsconfig.json → clean.

Suggested follow-ups

• pi-ai's OVERFLOW_PATTERNS 413 rule is broader than any provider contract. A
  provider that legitimately reports context overflow with a bare 413 status line
  and no JSON body would now be classified INVALID_REQUEST.
• The image-offload path (dsh-compaction-image-offload) already exists and keys
  off IMAGE_OFFLOAD_REQUIRED, raised above the route's maxRequestImageBytes.
  A gateway body-limit rejection could raise the same signal so large attachments
  move off the request instead of failing the turn.

Severity and triage

Classification defect, not a crash. No data loss and no incorrect output; the
damage is that a request-size failure is routed to a recovery path that cannot
address it.

Latent rather than universal. The trigger is a gateway that caps the request body
below the payload size, which most self-hosted and corporate proxies do and most
direct provider endpoints do not. A deployment without a body cap never reaches
this code path.

The over-broad pattern is not in this repository. @earendil-works/pi-ai@^1.3.0
owns OVERFLOW_PATTERNS, and its own documentation shows the 413 rule was
written for Anthropic's structured body:

413 {"error":{"type":"request_too_large","message":"Request exceeds the maximum size"}}

It was not written to match a bare status line or an HTML error page, which is
what a proxy emits. The workaround in this report lives in mapStopReason
because that is the only place this repository can intercept the label; the
durable fix is narrowing the pattern in pi-ai to require a structured body.

Note also that the harness's own classifyPiAiError already maps 413 to
INVALID_REQUEST (packages/llm/llm-pi-ai/src/stream.ts), so the two
classifiers in that module disagree about the same input by construction.