[pacocartones]

Summary

• The retryable chat_admission_busy 503 advertised a fixed Retry-After of 1 s (structural path) or 2 s (byte-stage path) while the heavyweight lease it waits on is held for the entire SSE lifetime. Clients that honor the header (Codex CLI, agent fan-out) re-sent the same ~1 MiB /v1/responses body every second into a gate that could not have cleared, producing the queue_timeout retry storm even after OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT was raised.
• ChatAdmissionController now tracks the acquisition time of every live heavy lease and derives the hint from observed occupancy: the larger of the queue window the waiter already exhausted and the age of the youngest live lease (time since capacity last turned over), rounded up and capped at 60 s. Both 503 builders floor it at the historical 1 s / 2 s, so an idle gate answers exactly as before. The youngest lease is used rather than the oldest to avoid a pessimistic hint when several slots are in flight; the 60 s cap is a constant to keep the surface small and can be made tunable if preferred.
• Scope: only the Retry-After defect the maintainer marked as standing. No change to the OMNIROUTE_CHAT_ADMISSION_QUEUE_MS default posture (deliberately left for the maintainer's decision), thresholds, status, error code, reason or routing. Troubleshooting guide entry updated.

Related Issues

• Closes fix(resilience): heavy /v1/responses still 503 chat_admission_busy after MAX_HEAVY is raised — QUEUE_MS and Retry-After: 1 are far shorter than SSE occupancy #12135
• Related to [BUG] chat_admission_busy error when running models in parallel across 2+ terminals (opencode) #12102, fix(sse): scale chat admission by ingest byte budget instead of a fixed request count #11548, fix(chat-admission): clarify local 503 source #12223

Validation

• Change type: Backend (resilience / chat admission middleware)
• Focused tests and category gates from the golden path: new test file 7/7; 15 neighbouring admission test files 132/132; node scripts/check/check-complexity-ratchets.mjs --base-ref origin/release/v3.8.51 (no regression); npm run check:changelog-integrity OK; npm run typecheck:core 0
• npm run lint — repository-wide eslint exit 0 (run with --pass-on-unpruned-suppressions; the literal command reports only pre-existing unused global suppressions on this base)
• Reconciled with the current active release base release/v3.8.51; focused checks rerun afterward
• Production-code changes include a new or updated automated test in this PR
• SonarQube is temporarily opt-in while the private project has no quota; it is not a PR gate.

Mutation: with the source change reverted, 5 of the 7 new tests fail (actual Retry-After 1/2 against expected 5, 45, 7, 60, 30).

Tests Added Or Updated

• tests/unit/heavy-admission-retry-after-12135.test.ts (new, 7 tests, mock timers): (a) queue_timeout Retry-After is at least the exhausted queue window; (b) structural and byte-stage 503s reflect observed lease age, using the youngest live lease; (c) the hint is capped at 60 s; (d) an idle gate keeps the historical 1 s / 2 s floors; (e) with the count cap raised, a third heavy /v1/responses request queues and is admitted when a lease frees inside queueMs. On the base: 2 pass / 5 fail; with the fix: 7 pass.

Coverage Notes

• src/shared/middleware/chatBodyAdmission.ts: retryAfterSeconds, lease-time tracking in tryAcquireHeavy, and all four 503 emission sites are exercised by the new test; the existing admission suites (chat-body-admission*.test.ts, probe-10268-structural-503.test.ts, chat-admission-visibility-11244.test.ts, with-chat-admission-10786.test.ts, per-connection-admission-9654.test.ts, and others) still pass unchanged, covering the untouched paths.
• src/shared/middleware/chatAdmissionResponses.ts: the new retryAfterHeader floor is covered by test (d) and by chat-admission-rejection-reason.test.ts (a call without a hint keeps Retry-After: 1).