@mlx-node/server 0.0.7 → 0.0.8

package/dist/endpoints/responses.js

@@ -8,12 +8,16 @@
  * `primeHistory` + `startFromHistory[Stream]`.
  */
 import { randomUUID } from 'node:crypto';
+import { isContextCapacityError } from '@mlx-node/lm';
+import { resetPreservingNativeCacheForWarmReuse } from '../chat-session-warm-reuse.js';
 import { sendBadRequest, sendInternalError, sendNotFound, sendRateLimit, sendStorageTimeout } from '../errors.js';
-import { mapRequest, reconstructMessagesFromChain } from '../mappers/request.js';
+import { mapRequest, reconstructMessagesFromChain, stringifyStoredInputMessages } from '../mappers/request.js';
 import { buildPartialResponse, buildResponseObject, computeOutputText, genId, mapFinishReasonToStatus, } from '../mappers/response.js';
 import { getPendingWritesFor } from '../pending-writes.js';
-import { QueueFullError } from '../session-registry.js';
+import { maybeWarnPromptCacheKeyIneligible, QueueFullError } from '../session-registry.js';
 import { beginSSE, endSSE, writeSSEEvent } from '../streaming.js';
+import { longestSuffixPrefixOverlap } from '../text-recovery.js';
+import { mergeTimingUsageExtensions, resolveServerTuningForUsage } from '../timing.js';
 import { ToolCallTagBuffer } from '../tool-call-buffer.js';
 import { createVisibility, endJson, flushTerminalSSE, markSSEMode, writeFallbackErrorSSE, } from '../transport-visibility.js';
 /**
@@ -23,6 +27,19 @@ import { createVisibility, endJson, flushTerminalSSE, markSSEMode, writeFallback
  * this 30-minute fallback is only used by legacy direct-invocation callers.
  */
 const RESPONSE_TTL_SECONDS = 1800;
+/**
+ * Upper bound for a client-supplied output-token budget. The native
+ * `ChatConfig.max_new_tokens` is `Option<i32>`, and NAPI's
+ * `napi_get_value_int32` silently truncates a JS integer above `i32::MAX`
+ * to a NEGATIVE value — which the core clamp then turns into 0 (a silent
+ * empty completion). Reject anything above this bound at the edge so an
+ * over-large budget 400s instead of producing nothing. Shared with
+ * `/v1/messages` (`messages.ts`).
+ */
+export const MAX_OUTPUT_TOKENS = 2147483647; // i32::MAX — native ChatConfig.max_new_tokens is i32
+function withAdmissionControlledInference(sessionReg, modelWorkCoordinator, fn) {
+    return sessionReg.withExclusive(() => (modelWorkCoordinator ? modelWorkCoordinator.withInference(fn) : fn()));
+}
 /**
  * Upper bound (ms) on how long the recovery path waits for an in-flight
  * `store.store(...)` to land. On timeout we re-probe `getChain` once to
@@ -136,8 +153,9 @@ export function getServerBootId() {
 export function __setServerBootIdForTesting(id) {
     serverBootId = id;
 }
-async function handleNonStreaming(res, result, req, responseId, previousResponseId, visibility) {
+async function handleNonStreaming(res, result, req, responseId, previousResponseId, visibility, serverTiming) {
     const response = buildResponseObject(result, req, responseId, previousResponseId);
+    mergeTimingUsageExtensions(response.usage, result.performance, result.promptTokens, result.numTokens, result.cachedTokens, serverTiming);
     // `chatSession*` has no AbortSignal surface yet, so a mid-decode
     // client disconnect still burns the full decode budget — peer loss
     // is only observable when native decode resolves. Disconnect
@@ -161,7 +179,7 @@ async function handleNonStreaming(res, result, req, responseId, previousResponse
  * on a failed envelope cannot see success-shaped items inside it.
  * `ReasoningOutputItem` has no `status` field and is left alone.
  */
-function buildFailedTerminal(partial, outputItems, reason, usage) {
+function buildFailedTerminal(partial, outputItems, reason, usage, errorMessage) {
     const normalized = outputItems.map((item) => {
         if (item.type === 'message') {
             const prev = item.status;
@@ -178,16 +196,25 @@ function buildFailedTerminal(partial, outputItems, reason, usage) {
         }
         return item;
     });
+    // Only the `reason: 'error'` path carries a diagnostic message —
+    // client_abort / stream_exhausted / finish_reason_error are caller
+    // or finite-state conditions, not server faults worth surfacing.
+    const error = errorMessage ? { type: 'server_error', message: errorMessage, code: null, param: null } : null;
     return {
         ...partial,
         status: 'failed',
         output: normalized,
         output_text: computeOutputText(normalized),
+        error,
         incomplete_details: { reason },
         usage,
     };
 }
-async function handleStreamingNative(res, chatStream, req, responseId, previousResponseId, wasCommitted, httpReq, visibility) {
+async function handleStreamingNative(res, chatStream, req, responseId, previousResponseId, wasCommitted, httpReq, visibility, serverTiming) {
+    // `runSessionStreaming` completed the exact token/capacity preflight before
+    // handing us this iterator. Commit SSE immediately instead of entering the
+    // generator here: its first `next()` also starts image processing/prefill and
+    // may not resolve until the first generated token.
     beginSSE(res);
     // Commit to SSE wire format synchronously so the outer catch
     // branches on `responseMode` (not `headersSent`) and routes an
@@ -206,6 +233,13 @@ async function handleStreamingNative(res, chatStream, req, responseId, previousR
     let messageText = '';
     let hasEmittedMessage = false;
     let hasEmittedReasoning = false;
+    // Tracks whether the reasoning output item's `response.output_item.done`
+    // has already been emitted. We close it eagerly on the reasoning→text
+    // transition (before opening the message item) so OpenAI Responses
+    // clients can populate their `thinkingSignature` via the `done`
+    // event's `currentBlock?.type === 'thinking'` guard. The terminal and
+    // failure paths check this flag to avoid double-emitting.
+    let hasClosedReasoning = false;
     let suppressedMessageIndex = -1;
     const tagBuffer = new ToolCallTagBuffer();
     // Terminal response is captured in the done branch but emitted AFTER
@@ -213,6 +247,14 @@ async function handleStreamingNative(res, chatStream, req, responseId, previousR
     // `session.turns` once the producer's finally has run.
     let completedResponse = null;
     let sawDone = false;
+    // Lifted from the final stream event so the outer handler can set
+    // `X-Cached-Tokens` and promote the `X-Session-Cache` header to
+    // `prefix_hit` when tier-2 reuse actually happened. See
+    // `StreamingHandlerOutcome.cachedTokens` for the full rationale.
+    // Starts `undefined` — the field is only populated if the native
+    // terminal chunk carries `cachedTokens`. Today it never does; a
+    // future native plumbing change can lift it through.
+    let cachedTokens;
     // Fault state. `thrownError` sticks on a generator throw;
     // `clientAborted` sticks on any `close`/`error` from `httpReq`, `res`,
     // or `res.socket`. Either flips the post-loop block to the failure
@@ -286,18 +328,22 @@ async function handleStreamingNative(res, chatStream, req, responseId, previousR
                         delta: remainingText,
                     });
                 }
-                // Close reasoning item if open
-                if (hasEmittedReasoning && reasoningItemId) {
+                // Close reasoning item if still open (already closed eagerly on
+                // reasoning→text transition for most turns — this branch covers
+                // the reasoning-only shape where no text deltas ever arrived).
+                if (hasEmittedReasoning && !hasClosedReasoning && reasoningItemId) {
+                    hasClosedReasoning = true;
+                    const finalReasoningText = event.thinking ?? reasoningText;
                     writeSSEEvent(res, 'response.reasoning_summary_text.done', {
                         item_id: reasoningItemId,
                         output_index: outputItems.length - (hasEmittedMessage ? 1 : 0) - 1,
                         summary_index: 0,
-                        text: event.thinking ?? reasoningText,
+                        text: finalReasoningText,
                     });
                     const reasoningItem = {
                         id: reasoningItemId,
                         type: 'reasoning',
-                        summary: [{ type: 'summary_text', text: event.thinking ?? reasoningText }],
+                        summary: [{ type: 'summary_text', text: finalReasoningText }],
                     };
                     const riIndex = outputItems.findIndex((i) => i.id === reasoningItemId);
                     if (riIndex >= 0) {
@@ -347,10 +393,38 @@ async function handleStreamingNative(res, chatStream, req, responseId, previousR
                         delta: finalText,
                     });
                 }
-                else if (tagBuffer.suppressed && !hasToolCalls && finalText && hasEmittedMessage) {
-                    // Recovery: text was already being streamed but got cut off by a false-alarm
-                    // <tool_call> tag. Emit the unsent portion as a delta.
-                    const unsent = finalText.slice(messageText.length);
+                else if (tagBuffer.suppressed &&
+                    !hasToolCalls &&
+                    finalText &&
+                    hasEmittedMessage &&
+                    !messageText.includes(finalText)) {
+                    // Recovery: streaming text was cut off by a false-alarm `<tool_call>` tag.
+                    //
+                    // The previous `finalText.slice(messageText.length)` is wrong: when the
+                    // streamed text contains post-</think> whitespace (or any prefix the
+                    // native side trimmed via `split_at_think_end` / `parse_tool_calls`),
+                    // `messageText.length` indexes into the streamed buffer while
+                    // `finalText` starts at the post-trim cleaned position — the two
+                    // prefixes diverge (e.g. messageText=`"\n\n"`, finalText=`"<tool_call>..."`)
+                    // and a length-based slice chops `<t` off `<tool_call>`, emitting
+                    // `"ool_call>\n<function=..."` as visible text.
+                    //
+                    // Find the longest streamed-suffix == finalText-prefix overlap and emit
+                    // whatever finalText has BEYOND that overlap.
+                    //
+                    // The `!messageText.includes(finalText)` guard distinguishes:
+                    //   (a) duplicate-trim case: streamed "Let me check. " + closed
+                    //       non-ok tool_call → finalText="Let me check." (trimmed). The
+                    //       trimmed text IS a substring of the streamed text → skip
+                    //       (otherwise we'd duplicate "Let me check.").
+                    //   (b) unclosed-tool case: streamed `\n\n` + unclosed
+                    //       `<tool_call>...` → finalText=`<tool_call>...`. The malformed
+                    //       tag is NOT a substring of the streamed whitespace → emit
+                    //       (this is the original `<t`-strip bug we're fixing).
+                    // Length-based guards (`finalText.length > messageText.length`)
+                    // misclassify case (b) when the streamed whitespace is long.
+                    const overlap = longestSuffixPrefixOverlap(messageText, finalText);
+                    const unsent = finalText.slice(overlap);
                     if (unsent) {
                         messageText += unsent;
                         writeSSEEvent(res, 'response.output_text.delta', {
@@ -361,16 +435,29 @@ async function handleStreamingNative(res, chatStream, req, responseId, previousR
                         });
                     }
                 }
-                // Emit any unsent suffix when final text is longer than what was streamed
-                if (hasEmittedMessage && finalText && finalText.length > messageText.length && !tagBuffer.suppressed) {
-                    const unsent = finalText.slice(messageText.length);
-                    messageText += unsent;
-                    writeSSEEvent(res, 'response.output_text.delta', {
-                        item_id: messageItemId,
-                        output_index: outputItems.findIndex((i) => i.id === messageItemId),
-                        content_index: 0,
-                        delta: unsent,
-                    });
+                // Emit any unsent suffix when final text extends past what was
+                // streamed. Same divergence concern as above (post-</think> trim
+                // can leave `messageText` longer than the matching prefix of
+                // `finalText`), so we use the same overlap-based slice instead of
+                // a length-based one. When the overlap covers all of `finalText`
+                // (i.e. nothing more to emit) `unsent` is empty and we skip.
+                //
+                // The `!messageText.includes(finalText)` guard skips the
+                // duplicate-trim case where finalText is a substring of the
+                // streamed text (e.g. native `.trim()` shrinkage). See the
+                // companion comment above for the case-distinction rationale.
+                if (hasEmittedMessage && finalText && !tagBuffer.suppressed && !messageText.includes(finalText)) {
+                    const overlap = longestSuffixPrefixOverlap(messageText, finalText);
+                    const unsent = finalText.slice(overlap);
+                    if (unsent) {
+                        messageText += unsent;
+                        writeSSEEvent(res, 'response.output_text.delta', {
+                            item_id: messageItemId,
+                            output_index: outputItems.findIndex((i) => i.id === messageItemId),
+                            content_index: 0,
+                            delta: unsent,
+                        });
+                    }
                 }
                 // Recovery: text was never emitted during streaming but final has text
                 // (possible if all text arrived in the final event only)
@@ -493,12 +580,27 @@ async function handleStreamingNative(res, chatStream, req, responseId, previousR
                 // then the post-loop block handles emission + persistence.
                 const promptTokens = event.promptTokens ?? 0;
                 const reasoningTokens = event.reasoningTokens ?? 0;
+                cachedTokens = event.cachedTokens;
                 const usage = {
                     input_tokens: promptTokens,
                     output_tokens: event.numTokens,
                     output_tokens_details: { reasoning_tokens: reasoningTokens },
                     total_tokens: promptTokens + event.numTokens,
                 };
+                // Round 5 Fix #3: SSE headers flush before the native prefix
+                // verifier has reported cached-token counts, so streaming
+                // `X-Session-Cache` is documented as non-authoritative. The
+                // authoritative signal for streaming clients is this in-band
+                // `usage.input_tokens_details.cached_tokens` field on the
+                // terminal `response.completed` event — identical shape to
+                // the upstream OpenAI Responses API. Populated only when the
+                // native dispatch reports a non-zero reuse count so consumers
+                // cheaply distinguish "feature not active" from "active with
+                // zero reuse".
+                if (cachedTokens != null && cachedTokens > 0) {
+                    usage.input_tokens_details = { cached_tokens: cachedTokens };
+                }
+                mergeTimingUsageExtensions(usage, event.performance, promptTokens, event.numTokens, cachedTokens, serverTiming);
                 const finalOutput = outputItems.filter((_, idx) => idx !== suppressedMessageIndex);
                 completedResponse = {
                     ...partial,
@@ -538,6 +640,39 @@ async function handleStreamingNative(res, chatStream, req, responseId, previousR
                 });
             }
             else {
+                // Transition from reasoning to assistant text: close the reasoning
+                // output item BEFORE emitting any `response.output_item.added` for
+                // the message. OpenAI Responses clients (e.g. pi-mono) maintain a
+                // single `currentBlock` state — opening the message item while the
+                // reasoning item is still "in progress" overwrites that state, so
+                // the later `output_item.done` for reasoning fails its
+                // `currentBlock?.type === 'thinking'` guard and never sets
+                // `thinkingSignature`. Without the signature the next turn cannot
+                // echo the reasoning item back, and any thinking-model agent loses
+                // its chain of thought on each turn. Must run before the first
+                // message write on this branch.
+                if (hasEmittedReasoning && !hasClosedReasoning && reasoningItemId) {
+                    hasClosedReasoning = true;
+                    const riIndex = outputItems.findIndex((i) => i.id === reasoningItemId);
+                    writeSSEEvent(res, 'response.reasoning_summary_text.done', {
+                        item_id: reasoningItemId,
+                        output_index: riIndex,
+                        summary_index: 0,
+                        text: reasoningText,
+                    });
+                    const reasoningItem = {
+                        id: reasoningItemId,
+                        type: 'reasoning',
+                        summary: [{ type: 'summary_text', text: reasoningText }],
+                    };
+                    if (riIndex >= 0) {
+                        outputItems[riIndex] = reasoningItem;
+                    }
+                    writeSSEEvent(res, 'response.output_item.done', {
+                        output_index: riIndex >= 0 ? riIndex : 0,
+                        item: reasoningItem,
+                    });
+                }
                 // Text delta with tool_call tag buffering
                 const { safeText, tagFound, cleanPrefix } = tagBuffer.push(event.text);
                 if (tagFound) {
@@ -618,6 +753,12 @@ async function handleStreamingNative(res, chatStream, req, responseId, previousR
         // error would escape into the outer JSON error path with SSE
         // headers already on the wire.
         thrownError = err instanceof Error ? err : new Error(String(err));
+        // Surface the message to stderr even on the failure path — without
+        // this the native side (e.g. `Tokenizer encoded <turn|> to N
+        // tokens; expected 1`) is invisible to operators since the SSE
+        // `response.failed` payload only carries `incomplete_details.reason`
+        // and never the underlying exception text.
+        console.error(`[responses] native dispatch failed for ${req.model} (response ${responseId}):`, thrownError.message);
     }
     finally {
         if (httpReq) {
@@ -670,7 +811,7 @@ async function handleStreamingNative(res, chatStream, req, responseId, previousR
         // adopt under an unseen responseId.
         await flushTerminalSSE(res, 'response.completed', { response: terminal }, visibility);
         endSSE(res);
-        return { terminalToPersist: terminal, failureMode: null };
+        return { terminalToPersist: terminal, failureMode: null, cachedTokens };
     }
     // Failure epilogue. Close any dangling message items BEFORE the
     // terminal so clients tracking `output_index` see matching closes.
@@ -727,9 +868,10 @@ async function handleStreamingNative(res, chatStream, req, responseId, previousR
             item: closedMessageItem,
         });
     }
-    if (!sawDone && hasEmittedReasoning && reasoningItemId != null) {
+    if (!sawDone && hasEmittedReasoning && !hasClosedReasoning && reasoningItemId != null) {
         // No `status` field on reasoning items — just emit closes so
         // client-side output_index bookkeeping stays consistent.
+        hasClosedReasoning = true;
         writeSSEEvent(res, 'response.reasoning_summary_text.done', {
             item_id: reasoningItemId,
             output_index: outputItems.findIndex((i) => i.id === reasoningItemId),
@@ -748,13 +890,16 @@ async function handleStreamingNative(res, chatStream, req, responseId, previousR
             writeSSEEvent(res, 'response.output_item.done', { output_index: riIndex, item: reasoningItem });
         }
     }
-    const failedTerminal = buildFailedTerminal(partial, finalOutput, reason, usage);
+    const failedTerminal = buildFailedTerminal(partial, finalOutput, reason, usage, reason === 'error' && thrownError ? thrownError.message : null);
     await flushTerminalSSE(res, 'response.failed', { response: failedTerminal }, visibility);
     endSSE(res);
     // No terminalToPersist on an uncommitted turn: a later continuation
     // that cold-replayed this record would silently resurrect failed
-    // output as authoritative history.
-    return { terminalToPersist: null, failureMode: reason };
+    // output as authoritative history. `cachedTokens` is meaningless on
+    // the failure path but returned verbatim to keep the type shape
+    // uniform — consumers already treat a non-null `failureMode` as the
+    // authoritative "do not use these numbers" signal.
+    return { terminalToPersist: null, failureMode: reason, cachedTokens };
 }
 // ---------------------------------------------------------------------------
 // Session routing
@@ -979,9 +1124,50 @@ export function validateAndCanonicalizeHistoryToolOrder(messages, apiSurface = '
  * back to reset + cold re-prime on multi-message input. The caller
  * is responsible for rejecting partial tool-result submissions
  * against a fan-out (`handleCreateResponse` fan-out gate).
+ *
+ * `isFreshSession` is the MISS / HIT signal from `SessionRegistry`:
+ * `true` when `lookup.hit === false` (a truly new session minted via
+ * `newSession()`), `false` when a tier-1 or tier-2 warm lease was
+ * handed out. On a MISS we must wipe the shared native model's
+ * leftover `cached_token_history` + KV caches before re-priming, or
+ * a previous UNRELATED request's cache could silently get reused as
+ * a prefix (cross-request cache-affinity side channel). On a HIT we
+ * must NOT wipe — the whole point of the warm lease is that
+ * `verify_cache_prefix_direct` can recover the reused prefix on the
+ * next `chat_session_start_sync`. The HIT branch calls the
+ * server-private `resetPreservingNativeCacheForWarmReuse(session)`
+ * helper from `../chat-session-warm-reuse.js` instead of the public
+ * `reset()` to thread this distinction down to the JS-side state
+ * clear. The helper lives inside `@mlx-node/server` and is never
+ * re-exported from either `@mlx-node/lm` or `@mlx-node/server`'s
+ * public surface, so downstream consumers cannot discover or invoke
+ * it.
  */
-async function runSessionNonStreaming(session, messages, newInputMessages, config) {
+async function runSessionNonStreaming(session, messages, newInputMessages, config, isFreshSession) {
     if (session.turns === 0) {
+        // Fresh JS session does NOT imply a fresh native cache — the
+        // underlying `SessionCapableModel` is shared across every
+        // `ChatSession` lifetime via `ModelRegistry`, and its native
+        // `cached_token_history` + KV caches persist across requests.
+        // After the native refactor moved the unconditional cache wipe
+        // out of `chat_session_start_sync` into the miss branch of
+        // `verify_cache_prefix_direct`, a MISS path that runs
+        // `primeHistory() + startFromHistory()` on a fresh session would
+        // inherit the PREVIOUS request's native cache and silently reuse
+        // whatever prefix happened to overlap — a cross-request
+        // cache-affinity side channel. Only registry HITS (tier-1 /
+        // tier-2) are authorized for cache reuse, and a leased session
+        // almost always has `turns > 0` so this branch is nearly always
+        // a MISS. The `isFreshSession` flag is the authoritative signal
+        // — on `false` we still need to clear JS-side state so
+        // `primeHistory()` accepts the replay, but we keep the native
+        // cache intact so the prefix verifier can recover it.
+        if (isFreshSession) {
+            await session.reset();
+        }
+        else {
+            await resetPreservingNativeCacheForWarmReuse(session);
+        }
         session.primeHistory(messages);
         const initialTurns = session.turns;
         const result = await session.startFromHistory(config);
@@ -1010,7 +1196,12 @@ async function runSessionNonStreaming(session, messages, newInputMessages, confi
                 throw new Error('tool message missing toolCallId');
             }
             const initialTurns = session.turns;
-            const result = await session.sendToolResult(last.toolCallId, last.content, { config });
+            // Forward the structured `isError` field through to the native
+            // renderer so the wire-format `[tool error]` marker stays in sync
+            // with the Anthropic `tool_result.is_error === true` source field
+            // (the structured channel is the authoritative signal — see
+            // `ChatMessage.isError` rustdoc).
+            const result = await session.sendToolResult(last.toolCallId, last.content, { config, isError: last.isError });
             return { result, committed: session.turns > initialTurns };
         }
         // Non-user / non-tool single-message continuation (assistant /
@@ -1021,20 +1212,57 @@ async function runSessionNonStreaming(session, messages, newInputMessages, confi
     // re-prime. `initialTurns` MUST be captured AFTER `session.reset()`
     // zeroes `turns`, otherwise the committed check reads stale.
     // Amortized: the caller re-keys this session under the new
-    // responseId on success.
-    await session.reset();
+    // responseId on success. On a tier-1 / tier-2 HIT that landed here
+    // (full-history replay is NOT a single-message delta, so even a
+    // warm session falls through to this branch), we MUST keep the
+    // native KV cache so the native `verify_cache_prefix_direct` can
+    // recover the reused prefix — wiping it would neutralize the
+    // entire warm-lease feature on multi-message hits. On a MISS we
+    // still wipe to prevent cross-request cache-affinity leakage.
+    if (isFreshSession) {
+        await session.reset();
+    }
+    else {
+        await resetPreservingNativeCacheForWarmReuse(session);
+    }
     session.primeHistory(messages);
     const initialTurns = session.turns;
     const result = await session.startFromHistory(config);
     return { result, committed: session.turns > initialTurns };
 }
 /** Streaming counterpart to {@link runSessionNonStreaming}. */
-async function runSessionStreaming(session, messages, newInputMessages, config, signal) {
+async function runSessionStreaming(session, messages, newInputMessages, config, signal, isFreshSession) {
+    // Preserve the startFromHistoryStream precondition outside the lazy
+    // generator. Without this guard an accepted `input: []` request would commit
+    // SSE and only then throw when iteration begins; the former eager-first-item
+    // path surfaced the same deterministic error before selecting wire format.
+    if (messages.length === 0) {
+        throw new Error('ChatSession: startFromHistoryStream() requires a primed history');
+    }
     if (session.turns === 0) {
+        // Fresh/replay requests carry their complete canonical history in
+        // `messages`. Validate it before reset so context overflow cannot mutate
+        // native state and still receives a JSON 400 before SSE begins.
+        const constrainedConfig = await session.preflightContextCapacity(messages, config);
+        // See `runSessionNonStreaming` for the full rationale. A fresh
+        // JS session inherits the shared native model's KV cache from
+        // prior requests; without an explicit `reset()` here the native
+        // prefix verifier can silently reuse a previous request's cache
+        // on any prompt-prefix overlap (a cross-request cache-affinity
+        // side channel). On MISS (`isFreshSession === true`) we wipe
+        // native cache + JS state. On tier-1 / tier-2 HIT we keep the
+        // native cache so the prefix verifier can recover the reused
+        // prefix, while still clearing JS-side state for `primeHistory`.
+        if (isFreshSession) {
+            await session.reset();
+        }
+        else {
+            await resetPreservingNativeCacheForWarmReuse(session);
+        }
         session.primeHistory(messages);
         const initialTurns = session.turns;
         return {
-            stream: session.startFromHistoryStream(config, signal),
+            stream: session.startFromHistoryStream(constrainedConfig, signal),
             wasCommitted: () => session.turns > initialTurns,
         };
     }
@@ -1045,10 +1273,14 @@ async function runSessionStreaming(session, messages, newInputMessages, config,
     if (newInputMessages.length === 1) {
         const last = newInputMessages[0];
         if (last.role === 'user') {
+            // Tier-2 prompt-cache hits may carry only this new message in the HTTP
+            // request while the leased ChatSession owns the prior conversation.
+            // Preflight against that authoritative private history, not `messages`.
+            const constrainedConfig = await session.preflightPendingContextCapacity(last, config);
             const initialTurns = session.turns;
             const images = last.images ?? undefined;
             return {
-                stream: session.sendStream(last.content, images ? { images, config, signal } : { config, signal }),
+                stream: session.sendStream(last.content, images ? { images, config: constrainedConfig, signal } : { config: constrainedConfig, signal }),
                 wasCommitted: () => session.turns > initialTurns,
             };
         }
@@ -1056,9 +1288,18 @@ async function runSessionStreaming(session, messages, newInputMessages, config,
             if (!last.toolCallId) {
                 throw new Error('tool message missing toolCallId');
             }
+            const constrainedConfig = await session.preflightPendingContextCapacity(last, config);
             const initialTurns = session.turns;
             return {
-                stream: session.sendToolResultStream(last.toolCallId, last.content, { config, signal }),
+                // Forward the structured `isError` field through to the native
+                // renderer so the streaming wire-format `[tool error]` marker
+                // stays in sync with the Anthropic `tool_result.is_error === true`
+                // source field — same contract as the non-streaming path above.
+                stream: session.sendToolResultStream(last.toolCallId, last.content, {
+                    config: constrainedConfig,
+                    signal,
+                    isError: last.isError,
+                }),
                 wasCommitted: () => session.turns > initialTurns,
             };
         }
@@ -1067,12 +1308,22 @@ async function runSessionStreaming(session, messages, newInputMessages, config,
     }
     // Multi-message (or single non-user/non-tool) hot path: same reset +
     // cold re-prime as the non-streaming variant. `initialTurns` must be
-    // captured AFTER reset.
-    await session.reset();
+    // captured AFTER reset. On tier-1 / tier-2 HIT (warm lease that
+    // cannot use the delta API because the input spans multiple
+    // messages), keep the native KV cache so the prefix verifier can
+    // reuse it on the replayed `chat_session_start_sync`; on MISS, wipe
+    // to block cross-request cache-affinity leakage.
+    const constrainedConfig = await session.preflightContextCapacity(messages, config);
+    if (isFreshSession) {
+        await session.reset();
+    }
+    else {
+        await resetPreservingNativeCacheForWarmReuse(session);
+    }
     session.primeHistory(messages);
     const initialTurns = session.turns;
     return {
-        stream: session.startFromHistoryStream(config, signal),
+        stream: session.startFromHistoryStream(constrainedConfig, signal),
         wasCommitted: () => session.turns > initialTurns,
     };
 }
@@ -1106,7 +1357,7 @@ function buildResponseRecord(response, newInputMessages, previousResponseId, mod
         model: response.model,
         status: response.status,
         instructions: response.instructions ?? undefined,
-        inputJson: JSON.stringify(newInputMessages),
+        inputJson: stringifyStoredInputMessages(newInputMessages),
         outputJson: JSON.stringify(response.output),
         outputText: response.output_text,
         usageJson: JSON.stringify(response.usage),
@@ -1161,7 +1412,8 @@ function readStoredModelIdentity(record) {
 // ---------------------------------------------------------------------------
 // Public handler
 // ---------------------------------------------------------------------------
-export async function handleCreateResponse(res, body, registry, store, httpReq, responseRetentionSec) {
+export async function handleCreateResponse(res, body, registry, store, httpReq, responseRetentionSec, idleSweeper, modelWorkCoordinator) {
+    const handlerStartedAt = Date.now();
     // Validate required fields
     if (body == null || typeof body !== 'object') {
         sendBadRequest(res, 'Request body must be a JSON object', 'body');
@@ -1179,6 +1431,22 @@ export async function handleCreateResponse(res, body, registry, store, httpReq,
         sendBadRequest(res, 'Field "input" must be a string or an array', 'input');
         return;
     }
+    // A present `max_output_tokens` must be an integer in `[1, i32::MAX]`.
+    // `null` / missing means "no explicit limit" and is fine. Mirrors the
+    // Anthropic `/v1/messages` guard on `max_tokens`. Rejecting here (rather
+    // than forwarding through the mapper) keeps a nonpositive budget from
+    // reaching native chat, where a negative `i32` would size a cache /
+    // allocation as a huge `usize`; core still clamps nonpositive to 0 as
+    // a backstop. The upper bound matters because NAPI truncates a JS
+    // integer above `i32::MAX` to a NEGATIVE `i32` (then clamped to 0 → a
+    // silent empty completion) — reject it as a 400 instead.
+    if (body.max_output_tokens != null &&
+        (!Number.isInteger(body.max_output_tokens) ||
+            body.max_output_tokens <= 0 ||
+            body.max_output_tokens > MAX_OUTPUT_TOKENS)) {
+        sendBadRequest(res, `Field "max_output_tokens" must be an integer between 1 and ${MAX_OUTPUT_TOKENS}`, 'max_output_tokens');
+        return;
+    }
     // Per-request retention override: `metadata.retention_seconds` lets a
     // client pin a single row to a longer (VIP / onboarding) or shorter
     // (one-shot PII) lifetime than the server-wide default. Bounds
@@ -1243,6 +1511,39 @@ export async function handleCreateResponse(res, body, registry, store, httpReq,
     // early-return path. These flags keep it a no-op when already run.
     let cleanupPerformed = false;
     let leaseReleased = false;
+    // Idle-sweeper bracket flags. Hoisted to outer function scope so
+    // the `finalizeIdleRequest` helper below can see them even though
+    // the `beginRequest()` call lives inside the inner `try`.
+    // Pre-dispatch validation failures (early returns that never called
+    // `beginRequest`) observe `idleRequestStarted === false` and skip
+    // the matching `endRequest()` entirely. `idleRequestEnded` is the
+    // `done` flag that guarantees the decrement fires exactly once
+    // regardless of which of the several finalize paths — outer
+    // `finally`, `res.once('finish')`, `res.once('close')`,
+    // `res.once('error')` — wins the race.
+    //
+    // Listeners are attached EAGERLY at `beginRequest()` time (not
+    // lazily from the outer `finally`) to close the round-4 leak where
+    // a terminal socket event fired *before* the outer `finally` ran:
+    // the lazy attach saw `writableEnded === false && writableFinished
+    // === false` at check time, attached listeners on a socket whose
+    // final event had already been emitted, and `endRequest()` then
+    // never fired, leaving `inFlight` pinned above zero and the
+    // sweeper permanently armed.
+    let idleRequestStarted = false;
+    let idleRequestEnded = false;
+    let idleListenersAttached = false;
+    const finalizeIdleRequest = () => {
+        if (!idleRequestStarted)
+            return;
+        if (idleRequestEnded)
+            return;
+        idleRequestEnded = true;
+        idleSweeper?.endRequest();
+    };
+    const onFinalizeEvent = () => {
+        finalizeIdleRequest();
+    };
     try {
         // Initial snapshot of the live binding. On a continuation we
         // re-read after `await store.getChain()` and reject if the
@@ -1751,8 +2052,37 @@ export async function handleCreateResponse(res, body, registry, store, httpReq,
         // adopt when `failureMode === 'client_abort'` regardless of how
         // `committed` / `safeToSuppress` landed.
         let streamFailureMode = null;
+        // Bracket native-model dispatch with the idle-sweeper counter.
+        // Must happen AFTER request validation / store lookup but BEFORE
+        // any native prefill or decode runs — so the pending-drain timer
+        // is cancelled in time to avoid racing the allocator with a live
+        // decode, and the post-dispatch `endRequest` arms a fresh drain
+        // only after every native stream byte has been emitted.
+        // Only inference traffic participates; `/v1/models`, health, and
+        // CORS preflights intentionally do not touch the counter.
+        //
+        // Attach the terminal-event listeners BEFORE any `await` — this
+        // is the round-4 fix for a sweeper leak where a fast terminal
+        // event (e.g. `endJson()` rejecting after the socket already
+        // emitted `close`) fired before the outer `finally` got a chance
+        // to attach its listeners, leaving `inFlight` pinned above zero.
+        // `finalizeIdleRequest` is the idempotency barrier — whichever
+        // of the listener events, the outer `finally`, or a pre-dispatch
+        // path fires first wins and the rest are no-ops.
+        idleSweeper?.beginRequest();
+        idleRequestStarted = true;
+        res.once('finish', onFinalizeEvent);
+        res.once('close', onFinalizeEvent);
+        res.once('error', onFinalizeEvent);
+        idleListenersAttached = true;
         try {
-            await sessionReg.withExclusive(async () => {
+            const mutexQueuedAt = Date.now();
+            const runInference = () => withAdmissionControlledInference(sessionReg, modelWorkCoordinator, async () => {
+                const serverTiming = {
+                    server_queue_ms: Date.now() - mutexQueuedAt,
+                    server_pre_inference_ms: Date.now() - handlerStartedAt,
+                    ...resolveServerTuningForUsage(),
+                };
                 // Hot-swap race guard inside the mutex.
                 //
                 // `withExclusive` can park this waiter behind a long-running
@@ -1801,36 +2131,132 @@ export async function handleCreateResponse(res, body, registry, store, httpReq,
                 // `send` / `sendToolResult` entry points cover exactly that
                 // shape. A single `assistant` / `system` continuation cannot
                 // be advanced incrementally against the warm KV cache and
-                // must be handled via reset + cold re-prime. Consuming a warm
-                // lease only to immediately `session.reset()` would destroy
-                // the cached prefix for no benefit (and mislabel the turn as
-                // `hit` when the client actually paid a full cold-replay
-                // prefill), so detect the case up front and force a fresh
-                // session lookup by passing `null` into `getOrCreate`. The
-                // subsequent `ResponseStore` reconstruction + `primeHistory` +
-                // `startFromHistory*` path below handles the rebuild. Multi-
-                // message continuations are left to the existing reset + cold
-                // re-prime fall-through inside `runSession*` (see comments
-                // there).
-                const hotPathIneligible = previousResponseId != null &&
-                    newInputMessages.length === 1 &&
-                    newInputMessages[0].role !== 'user' &&
-                    newInputMessages[0].role !== 'tool';
-                const lookup = hotPathIneligible
-                    ? sessionReg.getOrCreate(null, requestedInstructions)
-                    : sessionReg.getOrCreate(previousResponseId ?? null, requestedInstructions);
+                // must be handled via reset + cold re-prime. That branch is
+                // still VALID — it just routes through `runSession*`'s
+                // `session.turns === 0` fall-through (`primeHistory` +
+                // `startFromHistory*`) instead of the `send` / `sendToolResult`
+                // delta path. Crucially, a tier-1 HIT on this branch is still
+                // useful: `resetPreservingNativeCacheForWarmReuse(session)` keeps
+                // the warm native KV cache, and the subsequent
+                // `chat_session_start_sync` -> `verify_cache_prefix_direct`
+                // recovers the reused prefix even across a full-history
+                // replay. So we must NOT rewrite `previousResponseId` to null
+                // to force a cold-replay lookup — the tier-1 lease is exactly
+                // what makes warm reuse work. (Pre-Round 5 this branch passed
+                // `null` to force a miss, but that was wrong: it threw away a
+                // usable warm lease AND mislabeled the turn as `cold_replay`
+                // when the native prefix verifier was about to reuse the
+                // entire previous-turn prefix.) The hot-path-ineligibility
+                // condition (single non-user/non-tool continuation) is no
+                // longer consulted at lookup time — it's just the natural
+                // fall-through to the `session.turns === 0 || multi-message`
+                // cold-re-prime branch in `runSession*`, which correctly
+                // preserves the warm native cache on HIT via
+                // `resetPreservingNativeCacheForWarmReuse(session)`.
+                // Normalize the caller-supplied `prompt_cache_key` into the
+                // `string | null` shape the registry expects. `undefined` and
+                // missing both map to `null`; an explicit empty string is
+                // preserved distinct from `null` so the registry's tier-2
+                // scan treats "no key" and "empty key" as different tenants
+                // (prevents an unkeyed client from accidentally colliding
+                // with one that explicitly empty-keyed).
+                const promptCacheKey = typeof body.prompt_cache_key === 'string' ? body.prompt_cache_key : null;
+                // Precedence gate: when `previous_response_id` is present, tier-2
+                // (prompt-cache-key) lookup is DISABLED — even if the request is
+                // hot-path ineligible (single `assistant` / `system` continuation).
+                // The documented precedence is "prev-id wins; tier-1 miss falls
+                // through to FRESH, not tier-2", and that rule has to hold whether
+                // we take the hot path or the ineligible cold-replay branch. If we
+                // let the ineligible branch fall through to tier-2, a mis-routed
+                // prev-id request could lease an UNRELATED warm session that
+                // happens to share `prompt_cache_key`, then cold-replay on top of
+                // it — which `session.reset()` + `primeHistory()` would destroy,
+                // corrupting an unrelated chain. Force `null` for the cache key on
+                // both branches whenever a prev-id is set; tier-2 only runs for
+                // requests with no prev-id at all.
+                const effectivePromptCacheKey = previousResponseId != null ? null : promptCacheKey;
+                // Integrator nudge: if the caller supplied a non-empty
+                // `prompt_cache_key` but tier-2 prerequisites are missing
+                // (env gate off or key below the min-length floor) the turn
+                // silently cold-starts. Emit a once-per-distinct-raw-key
+                // stderr warning so `X-Session-Cache: fresh` on every request
+                // can be diagnosed without reading source. Gated on
+                // `effectivePromptCacheKey` (not raw `promptCacheKey`) so a
+                // request that suppresses the key via `previous_response_id`
+                // precedence does not also log a misleading "key ignored"
+                // message — that case is documented precedence, not a
+                // misconfiguration.
+                if (effectivePromptCacheKey !== null) {
+                    maybeWarnPromptCacheKeyIneligible(effectivePromptCacheKey);
+                }
+                const lookup = sessionReg.getOrCreate(previousResponseId ?? null, requestedInstructions, effectivePromptCacheKey);
                 const session = lookup.session;
                 // `X-Session-Cache` observability header: classify this turn as
-                // `fresh` (no `previous_response_id` on the request), `hit`
-                // (warm-cache lease consumed), or `cold_replay` (request carried
-                // `previous_response_id` but the warm entry was missing / expired
-                // / instructions-mismatched / already leased, OR the request
-                // shape is ineligible for the hot path — the endpoint will
-                // rebuild the session from the `ResponseStore` below). Set
-                // before any `writeHead` / SSE `beginSSE` so both JSON and SSE
-                // responses carry it. See `endpoints/messages.ts` for the
-                // matching always-`fresh` emission on `/v1/messages`.
-                const sessionCacheStatus = previousResponseId == null ? 'fresh' : lookup.hit && !hotPathIneligible ? 'hit' : 'cold_replay';
+                // `fresh` (no `previous_response_id` on the request and tier-2
+                // prompt-cache-key did not hit), `hit` (prev-id warm-cache
+                // lease consumed on tier 1), `prefix_hit` (tier-2 warm-cache
+                // lease consumed — only promoted from `fresh` later once the
+                // native `cachedTokens > 0` confirms real prefix reuse), or
+                // `cold_replay` (request carried `previous_response_id` but
+                // the warm entry was missing / expired / instructions-
+                // mismatched / already leased, OR the request shape is
+                // ineligible for the hot path — the endpoint will rebuild the
+                // session from the `ResponseStore` below). Set before any
+                // `writeHead` / SSE `beginSSE` so both JSON and SSE responses
+                // carry it. See `endpoints/messages.ts` for the matching
+                // emission on `/v1/messages`.
+                //
+                // The `prefix_hit` promotion and the companion
+                // `X-Cached-Tokens: N` header both depend on the native
+                // ChatResult's `cachedTokens` field, which is only authoritative
+                // AFTER the native dispatch completes. We therefore emit the
+                // initial `fresh` / `hit` / `cold_replay` value here and let
+                // the post-dispatch branch below promote a `fresh`+tier2-hit
+                // classification to `prefix_hit` once the cached-tokens count
+                // is known.
+                const tier2Hit = previousResponseId == null && lookup.hit;
+                // Optimistic pre-dispatch classification. SSE flushes headers on
+                // `beginSSE` inside `handleStreamingNative`, so the streaming
+                // path has exactly one shot to commit the header value — before
+                // the dispatch runs, i.e. BEFORE the native prefix verifier has
+                // reported whether any tokens were actually reused.
+                //
+                // For non-streaming we still commit optimistically to
+                // `prefix_hit` on tier-2 hit and demote to `fresh` post-dispatch
+                // if `cachedTokens === 0` (template drift, tokenizer change,
+                // image-set change, etc.) — `res.end` has not fired yet so the
+                // header is still settable.
+                //
+                // For streaming we deliberately do NOT promote to `prefix_hit`
+                // on tier-2 hit. Once SSE headers flush they cannot be
+                // corrected, and a false-positive `prefix_hit` would contradict
+                // consumers that read `cachedTokens` from the terminal event.
+                // Approach B (this path): emit `fresh` on streaming even when
+                // tier-2 found a warm session — the cache reuse still happens,
+                // only the observability header is conservative. A future
+                // refactor can thread `cached_tokens` through the native
+                // streaming `start` chunk so the server knows authoritatively
+                // before `beginSSE()` flushes, at which point streaming can
+                // commit `prefix_hit` too (Approach A). Until then,
+                // `prefix_hit` is a non-streaming-only signal.
+                const isStreaming = mappedBody.stream === true;
+                // Prev-id branch classification. A tier-1 HIT is labeled `hit`
+                // regardless of whether the request is hot-path-eligible: the
+                // warm native KV cache is reused in both paths (the cheap
+                // `send` / `sendToolResult` delta on the eligible branch; the
+                // full-history `primeHistory` + `startFromHistory*` replay on
+                // the ineligible branch, where `resetPreservingNativeCacheForWarmReuse`
+                // keeps the cache alive for `verify_cache_prefix_direct` to
+                // recover). Only a registry MISS on the prev-id branch
+                // downgrades to `cold_replay` (no warm cache to reuse, the
+                // request must rebuild from `ResponseStore`).
+                let sessionCacheStatus = previousResponseId == null
+                    ? tier2Hit && !isStreaming
+                        ? 'prefix_hit'
+                        : 'fresh'
+                    : lookup.hit
+                        ? 'hit'
+                        : 'cold_replay';
                 res.setHeader('X-Session-Cache', sessionCacheStatus);
                 // Multi-tool-call fan-out gate.
                 //
@@ -2067,10 +2493,10 @@ export async function handleCreateResponse(res, body, registry, store, httpReq,
                     // (JSON error, SSE `error` frame, or socket destroy).
                     let handlerError = null;
                     if (mappedBody.stream) {
-                        const outcome = await runSessionStreaming(session, messages, newInputMessages, config, streamSignal);
+                        const outcome = await runSessionStreaming(session, messages, newInputMessages, config, streamSignal, !lookup.hit);
                         const streamingWasCommitted = () => outcome.wasCommitted();
                         try {
-                            const handlerOutcome = await handleStreamingNative(res, outcome.stream, mappedBody, responseId, previousResponseId, streamingWasCommitted, httpReq, visibility);
+                            const handlerOutcome = await handleStreamingNative(res, outcome.stream, mappedBody, responseId, previousResponseId, streamingWasCommitted, httpReq, visibility, serverTiming);
                             streamFailureMode = handlerOutcome.failureMode;
                             if (handlerOutcome.terminalToPersist != null && store && body.store !== false) {
                                 // Initiate the write SYNCHRONOUSLY inside the mutex so
@@ -2294,9 +2720,30 @@ export async function handleCreateResponse(res, body, registry, store, httpReq,
                         // `handleNonStreaming` (short-circuits `endJson` and
                         // signals the outer persist gate) plus this documented
                         // limitation.
-                        const outcome = await runSessionNonStreaming(session, messages, newInputMessages, config);
+                        const outcome = await runSessionNonStreaming(session, messages, newInputMessages, config, !lookup.hit);
+                        // Prefix-cache observability headers for the non-streaming
+                        // path. `res.end` has not fired yet (the handler's
+                        // `endJson` call below is what flushes), so `setHeader`
+                        // still lands on the wire. We re-classify the
+                        // `X-Session-Cache` header here so a tier-2 lookup that
+                        // did NOT actually produce native prefix reuse
+                        // (`cachedTokens === 0`) gets demoted from the optimistic
+                        // `prefix_hit` back to `fresh` — matching the plan's
+                        // contract that `prefix_hit` only fires when the registry
+                        // served a match via `promptCacheKey` AND the ChatResult
+                        // reports `cachedTokens > 0`. The companion
+                        // `X-Cached-Tokens: N` header reports the exact count for
+                        // operators and downstream telemetry whenever reuse
+                        // happened.
+                        if (tier2Hit && outcome.result.cachedTokens === 0) {
+                            sessionCacheStatus = 'fresh';
+                            res.setHeader('X-Session-Cache', sessionCacheStatus);
+                        }
+                        if (outcome.result.cachedTokens > 0) {
+                            res.setHeader('X-Cached-Tokens', String(outcome.result.cachedTokens));
+                        }
                         try {
-                            const handlerOutcome = await handleNonStreaming(res, outcome.result, mappedBody, responseId, previousResponseId, visibility);
+                            const handlerOutcome = await handleNonStreaming(res, outcome.result, mappedBody, responseId, previousResponseId, visibility, serverTiming);
                             if (store && body.store !== false) {
                                 // Same in-lock-initiate / off-lock-await split as the
                                 // streaming branch. The non-streaming handler only
@@ -2531,7 +2978,21 @@ export async function handleCreateResponse(res, body, registry, store, httpReq,
                     // stream path completed cleanly and the adopted session
                     // is genuinely reachable via the responseId.
                     if (committed && (handlerError == null || safeToSuppress) && streamFailureMode === null) {
-                        sessionReg.adopt(responseId, session, requestedInstructions);
+                        // Adopt under the SAME `effectivePromptCacheKey` that was
+                        // used for `getOrCreate` above — not the raw
+                        // `promptCacheKey` from the request body. When a request
+                        // carries `previous_response_id` (tier-1 path), tier-2 is
+                        // deliberately disabled on the lookup side by forcing
+                        // `effectivePromptCacheKey = null`; the adopt side must
+                        // follow the same rule or a mixed-mode request
+                        // (`previous_response_id=rA + prompt_cache_key=K`) would
+                        // store the adopted session under `K` even though the
+                        // lookup was resolved via `rA`. A subsequent keyless/
+                        // prev-idless request with `prompt_cache_key=K` would then
+                        // tier-2 hit and lease rA's chain session — a cross-chain
+                        // corruption the precedence rule was explicitly designed
+                        // to prevent. Keep adopt's key aligned with lookup's key.
+                        sessionReg.adopt(responseId, session, requestedInstructions, effectivePromptCacheKey);
                     }
                     // Rethrow handler errors when the client hasn't seen a
                     // terminal yet, regardless of commit state. The outer
@@ -2560,9 +3021,15 @@ export async function handleCreateResponse(res, body, registry, store, httpReq,
                     // already received — or no output at all if the terminal
                     // already landed.
                     if (visibility.responseMode === null) {
-                        // Headers never went out. Safe to emit a clean 500 JSON
-                        // error.
-                        sendInternalError(res, message);
+                        // Capacity failures are deterministic request errors, raised
+                        // before native cache mutation. Keep them out of the generic
+                        // 500 path so clients can compact/truncate and retry.
+                        if (isContextCapacityError(err)) {
+                            sendBadRequest(res, message);
+                        }
+                        else {
+                            sendInternalError(res, message);
+                        }
                     }
                     else if (visibility.responseMode === 'json') {
                         // We already wrote `Content-Type: application/json` and
@@ -2602,6 +3069,7 @@ export async function handleCreateResponse(res, body, registry, store, httpReq,
                     }
                 }
             });
+            await runInference();
         }
         catch (err) {
             // Admission-control rejection from the per-model queue cap
@@ -2765,11 +3233,16 @@ export async function handleCreateResponse(res, body, registry, store, httpReq,
         // never ran (early-return validation failure, or an exception
         // raised inside the outer `try` block between lease
         // acquisition and the `withExclusive` call), make sure the
-        // abort listeners are detached and the dispatch lease is
+        // abort listeners + idle-sweeper listeners are detached, the
+        // in-flight counter is decremented, and the dispatch lease is
         // released here. `runPostDispatchCleanup` is safe to re-invoke
-        // — the `abortListenersAttached` check and
-        // `releaseDispatchLease`'s `inFlight < 0` floor make it a
-        // no-op when the happy-path already fired it.
+        // — the `abortListenersAttached` / `idleListenersAttached` /
+        // `leaseReleased` flags make every sub-step idempotent on a
+        // second pass. `finalizeIdleRequest` inside the helper is also
+        // guarded by `idleRequestEnded`, so the decrement fires exactly
+        // once regardless of which path wins the race between the
+        // eagerly-attached terminal listener firing, the happy-path
+        // cleanup on `withExclusive` return, and this outer fallback.
         if (!cleanupPerformed) {
             runPostDispatchCleanup();
         }
@@ -2793,6 +3266,23 @@ export async function handleCreateResponse(res, body, registry, store, httpReq,
             }
             abortListenersAttached = false;
         }
+        // Drop the idle-sweeper's finalize listeners AND decrement the
+        // in-flight counter. Post-dispatch cleanup runs AFTER
+        // `handleStreamingNative` / `handleNonStreaming` have awaited
+        // their terminal `res.end()` — the native dispatch is done at
+        // this point, so the sweeper can safely arm a new pending
+        // drain. Firing here (rather than only in the outer `finally`)
+        // means the post-commit persist wait does not keep `inFlight`
+        // pinned above zero on a wedged store. `finalizeIdleRequest`
+        // is idempotent via the `done` flag so a subsequent fire from
+        // the outer finally / a stray listener is a no-op.
+        if (idleListenersAttached) {
+            res.removeListener('finish', onFinalizeEvent);
+            res.removeListener('close', onFinalizeEvent);
+            res.removeListener('error', onFinalizeEvent);
+            idleListenersAttached = false;
+        }
+        finalizeIdleRequest();
         // Release the dispatch lease on the ORIGINAL model object the
         // lease was acquired against (not a re-read of `body.model`,
         // which may have been hot-swapped while we held the mutex). A