fix(sse): bound slow keepalive path with absolute last-resort deadline

[maxmad64bis]

⚠️ base-red inherited: #14547

Summary

A handler that never resolves before first byte holds the early-keepalive slow path open forever, pinning the client spinner and concurrency slots. The slow path only ticks keepalives until the handler settles, while legitimate waits (queue, cooldown, park-and-resume, readiness) all fit under a derived bound. At 33 minutes the wrapper now emits the route error frame, closes the stream, aborts the handler, and warns once with correlation.

Related Issues

Related to #12685

Upstream census (2026-09-24)

#	State	Title / maintainer position
#12685	closed	keepalive-only hang; diegosouzapw 2026-09-10 confirmed the frame is internal keepalive, 2026-09-17 closed stale
#9153	closed	per-attempt deadline; diegosouzapw 2026-08-21 viable, in progress
#12741	closed	fail fast on heartbeat-only streams; closed by diegosouzapw 2026-09-10
#4105	closed	clear keepalive timer on abort; diegosouzapw 2026-06-17 merged
#14025	open	readiness budget ignores reasoning effort; no position yet
#14792	open	thread correlationId into chat keepalive; overlaps this diff
#14377	open	strict SSE switches; diegosouzapw 2026-09-22 building opt-out
#13850	open	valid responses keepalives; diegosouzapw 2026-09-22 changes asked

Validation

• Change type: sse
• Focused tests and category gates from the golden path
• npm run lint
• Reconciled with the current active release base; focused checks rerun afterward
• Production-code changes include a new or updated automated test in this PR

Tests Added Or Updated

• tests/unit/early-stream-keepalive.test.ts — 4 new tests: expiry emits the error frame, aborts the deadline controller, and warns once with correlation; resolve under the deadline forwards with no warn; slowPathDeadlineMs <= 0 disables the deadline; client abort before the deadline keeps the existing abort path with no deadline warn.

Coverage Notes

• The 4 new tests cover the added branches in open-sse/utils/earlyStreamKeepalive.ts (timer start, expiry path, opt-out, abort interplay); targeted suites are green (keepalive 22/22); the full suite runs in CI.

Reviewer Notes

• This PR shares src/app/api/v1/chat/completions/route.ts and tests/unit/early-stream-keepalive.test.ts with open fix(api): thread correlationId into chat completions early keepalive #14792. Merge fix(api): thread correlationId into chat completions early keepalive #14792 first, then rebase this one; the overlapping hunks are one-line threading additions on each side.
• The single local commit includes the changelog fragment changelog.d/fixes/14808-keepalive-deadline-last-resort.md.
• The 33-minute bound is derived from in-repo ceilings (queue 300s, cooldown 300s, park 120s, readiness 600s, plus margin). No new setting is exposed; the deadline is an internal default with an explicit opt-out.

Maintainer rework (merge-batch 2026-09-24)

• Unbounded token map fixed (c8b0144). deadlineControllersByToken is keyed by strings, so each request left an entry behind for the life of the process. Now:
  • the entry is released when the keepalive wrapper finishes (fast path, settle, client abort, cancel or deadline expiry) through the new releaseDeadlineController();
  • a FinalizationRegistry backstop covers requests that never reach the wrapper (non-streaming paths);
  • a hard cap of 10,000 entries acts as the last resort.
• New regression test. 20 rounds of fast, slow, expired and client-aborted requests must leave the map at its original size, and a released token must no longer resolve through the header lookup. With the release disabled the test fails with 45 entries left over. With the fix it passes.
• Doc comment restored. The SettledHandler comment had lost one line (the strictNullChecks: false sentence). It is back.
• correlationId: reqId moved in the chat route (73f896b). It now sits on the same line where fix(api): thread correlationId into chat completions early keepalive #14792 adds it, so the two merge into a single property instead of a duplicate key (TS1117).
• Merged the current release/v3.8.51, which includes fix(api): thread correlationId into chat completions early keepalive #14792. The combined state has been checked.
• Gates run:
  • Focused keepalive/route tests are green, including fix(api): thread correlationId into chat completions early keepalive #14792's.
  • typecheck:core and check:open-sse-typecheck are clean.
  • ESLint on the changed files is clean.
  • The JON-562 /v1/messages retention canary passes on this branch. Timeouts had to be raised for that run because the devbox was overloaded; the tip fails the same way under that load.
  • check-file-size flags only open-sse/executors/opencode.ts. That file is identical to the tip, so the failure is inherited from the base.