mixdog 0.9.12 → 0.9.14

package/src/runtime/agent/orchestrator/providers/gemini-stream.mjs

@@ -39,6 +39,30 @@ export function geminiTruncatedStreamError(message) {
     );
 }
 
+// CC-rule safety stamp for Gemini stream failures (provider-stall audit):
+// once text has been relayed to the live gateway or a leaked tool call was
+// dispatched, replaying the request would double-render/double-execute — the
+// outer withRetry() in gemini.mjs wraps the WHOLE stream, and a bare
+// EGEMINITIMEOUT classifies transient, so without these markers a mid-stream
+// stall after visible output was silently retried. Visible-text stalls also
+// gain streamStalled + partialContent so the loop's partial-final path can
+// keep the streamed output instead of dropping the turn.
+export function stampGeminiStreamFailure(err, { relayedText = '', textLeakGuard = null } = {}) {
+    if (!err || typeof err !== 'object') return err;
+    const leaked = (textLeakGuard?.getLeakedToolCalls?.() || []).length > 0;
+    const visible = relayedText.length > 0;
+    try {
+        if (visible) { err.liveTextEmitted = true; err.unsafeToRetry = true; }
+        if (leaked) { err.emittedToolCall = true; err.unsafeToRetry = true; }
+        if (visible && !leaked && err.code === 'EGEMINITIMEOUT') {
+            err.streamStalled = true;
+            if (typeof err.partialContent !== 'string') err.partialContent = relayedText;
+            if (err.pendingToolUse === undefined) err.pendingToolUse = false;
+        }
+    } catch { /* best-effort */ }
+    return err;
+}
+
 /**
  * Aggregate streamed GenerateContentResponse chunks into one response object
  * (same shape as a non-streaming generateContent JSON body).
@@ -220,6 +244,7 @@ export async function consumeGeminiRestStreamResponse(response, { signal, onStre
     let idleTimedOut = false;
     let idleTimer = null;
     let idleReject = null;
+    let relayedText = '';
 
     let firstByteTimer = setTimeout(() => {
         try { reader.cancel('first byte timeout'); } catch {}
@@ -309,6 +334,7 @@ export async function consumeGeminiRestStreamResponse(response, { signal, onStre
                 try { onStreamDelta?.(); } catch {}
                 if (onTextDelta || textLeakGuard) {
                     const t = geminiChunkText(parsed);
+                    if (t) relayedText += t;
                     relayGeminiStreamText(t, { onTextDelta, textLeakGuard });
                 }
             }
@@ -328,12 +354,15 @@ export async function consumeGeminiRestStreamResponse(response, { signal, onStre
                         try { onStreamDelta?.(); } catch {}
                         if (onTextDelta || textLeakGuard) {
                             const t = geminiChunkText(parsed);
+                            if (t) relayedText += t;
                             relayGeminiStreamText(t, { onTextDelta, textLeakGuard });
                         }
                     } catch { /* skip malformed tail */ }
                 }
             }
         }
+    } catch (err) {
+        throw stampGeminiStreamFailure(err, { relayedText, textLeakGuard });
     } finally {
         clearFirstByteTimer();
         if (idleTimer) clearTimeout(idleTimer);
@@ -344,7 +373,15 @@ export async function consumeGeminiRestStreamResponse(response, { signal, onStre
 
     const aggregated = aggregateGeminiStreamChunks(allChunks);
     const finishReason = aggregated.candidates?.[0]?.finishReason || null;
-    assertGeminiStreamCompleted({ sawStreamChunk, finishReason, label });
+    // Truncation (no finishReason) after visible output must carry the same
+    // safety stamps as an in-loop failure — assert throws OUTSIDE the catch
+    // above, so stamp here too (review High: transient TRUNCATED_STREAM would
+    // otherwise replay/double-render live text via withRetry).
+    try {
+        assertGeminiStreamCompleted({ sawStreamChunk, finishReason, label });
+    } catch (err) {
+        throw stampGeminiStreamFailure(err, { relayedText, textLeakGuard });
+    }
     return aggregated;
 }
 
@@ -355,6 +392,7 @@ export async function consumeGeminiSdkStream(streamResult, { signal, onStreamDel
     let firstByteReject = null;
     let firstByteTimer = null;
     let inFlightReject = null;
+    let relayedText = '';
 
     const armFirstByteTimer = () => {
         if (firstByteTimer) clearTimeout(firstByteTimer);
@@ -468,6 +506,7 @@ export async function consumeGeminiSdkStream(streamResult, { signal, onStreamDel
             try { onStreamDelta?.(); } catch {}
             if (onTextDelta || textLeakGuard) {
                 const t = geminiChunkText(step.value);
+                if (t) relayedText += t;
                 relayGeminiStreamText(t, { onTextDelta, textLeakGuard });
             }
         }
@@ -480,7 +519,7 @@ export async function consumeGeminiSdkStream(streamResult, { signal, onStreamDel
             const reason = signal.reason;
             throw reason instanceof Error ? reason : new Error(`${label} aborted`);
         }
-        throw err;
+        throw stampGeminiStreamFailure(err, { relayedText, textLeakGuard });
     } finally {
         clearFirstByteTimer();
         if (idleTimer) clearTimeout(idleTimer);
@@ -515,6 +554,12 @@ export async function consumeGeminiSdkStream(streamResult, { signal, onStreamDel
         raw = response?.candidates ? response : (response?.response || response);
     }
     const finishReason = raw?.candidates?.[0]?.finishReason || null;
-    assertGeminiStreamCompleted({ sawStreamChunk, finishReason, label });
+    // Same stamping as the REST consumer: truncation after visible output
+    // must not classify transient (review High).
+    try {
+        assertGeminiStreamCompleted({ sawStreamChunk, finishReason, label });
+    } catch (err) {
+        throw stampGeminiStreamFailure(err, { relayedText, textLeakGuard });
+    }
     return raw;
 }

package/src/runtime/agent/orchestrator/providers/openai-compat-stream.mjs

@@ -402,8 +402,19 @@ export async function consumeCompatChatCompletionStream(stream, { signal, label,
         // trailing text is never lost.
         if (leakGuard.enabled) flushLeak();
     } catch (err) {
-        // Any mid-stream failure after live text was relayed is non-retryable.
-        if (emittedText) throw markErrorLiveTextEmitted(err);
+        // Any mid-stream failure after live text was relayed is non-retryable —
+        // but the streamed partial must still ride on the error (CC rule: once
+        // output is visible, keep it and finalize with a notice instead of
+        // discarding the turn). The loop's partial-final path consumes these.
+        if (emittedText) {
+            markErrorLiveTextEmitted(err);
+            try {
+                err.partialContent = content;
+                err.pendingToolUse = toolAcc.size > 0 || leakedCalls.length > 0;
+                err.partialModel = model || undefined;
+            } catch { /* best-effort */ }
+            throw err;
+        }
         // Partial-final recovery: on a mid-stream stall, attach the
         // streamed partial state so the loop can accept a wedged FINAL no-tool
         // summary as partial-final success. pendingToolUse gates out any
@@ -425,7 +436,19 @@ export async function consumeCompatChatCompletionStream(stream, { signal, label,
     }
     if (!stopReason) {
         const err = truncatedCompatStreamError(label, 'no finish_reason');
-        if (emittedText) markErrorLiveTextEmitted(err);
+        if (emittedText) {
+            // Truncation after visible output: preserve the partial (CC-style)
+            // instead of surfacing a bare terminal error. streamStalled lets
+            // the loop's partial-final acceptance path pick it up; liveText
+            // marking still blocks any retry/replay.
+            markErrorLiveTextEmitted(err);
+            try {
+                err.streamStalled = true;
+                err.partialContent = content;
+                err.pendingToolUse = toolAcc.size > 0 || leakedCalls.length > 0;
+                err.partialModel = model || undefined;
+            } catch { /* best-effort */ }
+        }
         throw err;
     }
     const message = {
@@ -796,7 +819,22 @@ export async function consumeCompatResponsesStream(stream, {
     }
     if (!state.completed) {
         const err = truncatedCompatStreamError(label, 'no response.completed');
-        if (state.emittedText) markErrorLiveTextEmitted(err);
+        if (state.emittedText) {
+            // Truncation after visible output: keep the streamed partial
+            // (CC rule) so the loop can finalize it as partial-final instead
+            // of dropping the turn. liveText marking still blocks replay.
+            markErrorLiveTextEmitted(err);
+            try {
+                err.streamStalled = true;
+                err.partialContent = state.content || '';
+                err.pendingToolUse = state.emittedToolCall === true
+                    || leakedCalls.length > 0
+                    || (state.pendingCalls && state.pendingCalls.size > 0)
+                    || (Array.isArray(state.toolCalls) && state.toolCalls.length > 0)
+                    || state.toolInFlight === true;
+                err.partialModel = state.model || undefined;
+            } catch { /* best-effort */ }
+        }
         throw err;
     }
     const unresolved = state.toolCalls.find(t => t._pendingItemId);

package/src/runtime/agent/orchestrator/providers/openai-compat-xai.mjs

@@ -149,7 +149,7 @@ export function useXaiResponsesWebSocket(opts, config) {
     return !['0', 'false', 'off', 'http', 'https', 'responses-http', 'sdk'].includes(transport);
 }
 
-function _envFlag(name, fallback = true) {
+export function _envFlag(name, fallback = true) {
     const raw = process.env[name];
     if (raw == null || raw === '') return fallback;
     return !['0', 'false', 'off', 'no'].includes(String(raw).toLowerCase());

package/src/runtime/agent/orchestrator/providers/openai-compat.mjs

@@ -9,7 +9,7 @@ import {
 } from './openai-compat-stream.mjs';
 import { enrichModels, getModelMetadataSync } from './model-catalog.mjs';
 import { sanitizeModelList } from './model-list-sanitize.mjs';
-import { appendAgentTrace, traceAgentUsage } from '../agent-trace.mjs';
+import { appendAgentTrace, grokCacheChainTraceFields, traceAgentUsage } from '../agent-trace.mjs';
 import {
     PROVIDER_FIRST_BYTE_TIMEOUT_MS,
     PROVIDER_GENERATE_TOTAL_TIMEOUT_MS,
@@ -46,6 +46,7 @@ import {
     useXaiResponsesWebSocket,
     useXaiResponsesWebSocketWarmup,
     _shouldFallbackXaiWsToHttp,
+    _envFlag,
     withXaiResponsesCacheLane,
     writeCompatCacheTrace,
     traceXaiResponsesCacheContext,
@@ -543,6 +544,11 @@ export class OpenAICompatProvider {
         if (response.usage) {
             const inputTokens = Number(response.usage.input_tokens ?? response.usage.prompt_tokens ?? 0);
             const cachedTokens = extractCompatCachedTokens(response.usage);
+            const cacheChain = grokCacheChainTraceFields(
+                opts.providerState,
+                previousResponseId,
+                continuationResetReason,
+            );
             traceAgentUsage({
                 sessionId: opts.sessionId || opts.session?.id || null,
                 iteration: Number.isFinite(Number(opts.iteration)) ? Number(opts.iteration) : null,
@@ -556,9 +562,17 @@ export class OpenAICompatProvider {
                 responseId: response.id || null,
                 rawUsage: response.usage,
                 provider: 'xai',
+                requestPrevResponseId: cacheChain.requestPrevResponseId,
+                chainContinuous: cacheChain.chainContinuous,
+                continuationResetReason: cacheChain.continuationResetReason,
             });
         }
-        const nextPreviousResponseId = streamed.stopReason === 'length' ? null : response.id;
+        // Keep the response chain across `length` stops: a max-output cutoff
+        // is still a committed response server-side, so chaining from its id
+        // preserves prefix cache. (Previously reset to null defensively; no
+        // provider requirement found — chain_continuous trace will surface
+        // any rejection as a provider-side drop.)
+        const nextPreviousResponseId = response.id;
         const searchSources = collectCompatResponseSearchSources(response);
         return {
             content: streamed.content,
@@ -671,12 +685,19 @@ export class OpenAICompatProvider {
                 traceProvider: 'xai',
                 logSuppressedReasoningDeltas: false,
                 warmupBody,
+                // Mirror openai-oauth fast fallback: when the HTTP fallback is
+                // enabled (outer catch → _shouldFallbackXaiWsToHttp), a first
+                // acquire/first-byte failure should skip remaining WS
+                // handshake retries instead of burning the retry budget
+                // before HTTP starts.
+                fastFallback: _envFlag('MIXDOG_XAI_WS_HTTP_FALLBACK', true),
             });
         });
         const result = scheduled.value;
         cacheLane = cacheLane || scheduled.laneMeta;
         const responseId = result.responseId || previousResponseId || null;
-        const nextPreviousResponseId = result.stopReason === 'length' ? null : responseId;
+        // Same rationale as the HTTP path above: `length` stop keeps the chain.
+        const nextPreviousResponseId = responseId;
         const rawUsage = result.usage?.raw || result.usage || null;
         const traceParams = result.__warmup?.requestBody || params;
         writeXaiResponsesCacheTrace({

package/src/runtime/agent/orchestrator/providers/openai-oauth-http-sse.mjs

@@ -636,6 +636,12 @@ export async function sendViaHttpSse({
     };
 
     try {
+        // Arm the idle watchdog BEFORE the first read: a 200 response with an
+        // open-but-silent body (no SSE events at all) previously hung on bare
+        // reader.read() until the outer agent watchdog (CC/codex/opencode all
+        // bound the first read). meaningful() re-arms it per delta thereafter;
+        // an empty-partial stall classifies stream_stalled → retry/fallback.
+        _armSemanticIdle();
         while (true) {
             if (totalTimeout.signal?.aborted) {
                 _clearSemanticIdle();

package/src/runtime/agent/orchestrator/providers/openai-oauth-ws.mjs

@@ -28,6 +28,7 @@ import {
     traceAgentFetch,
     traceAgentSse,
     traceAgentUsage,
+    grokCacheChainTraceFields,
     appendAgentTrace,
 } from '../agent-trace.mjs';
 import {
@@ -421,10 +422,14 @@ export async function _acquireWithRetry({
     externalSignal,
     _acquire = acquireWebSocket,
     _sleepFn = _defaultSleep,
+    maxAttempts = HANDSHAKE_MAX_ATTEMPTS,
 } = {}) {
     let lastErr = null;
     let lastClassifier = null;
-    for (let attempt = 1; attempt <= HANDSHAKE_MAX_ATTEMPTS; attempt++) {
+    const attemptCap = Number.isFinite(maxAttempts) && maxAttempts > 0
+        ? Math.min(maxAttempts, HANDSHAKE_MAX_ATTEMPTS)
+        : HANDSHAKE_MAX_ATTEMPTS;
+    for (let attempt = 1; attempt <= attemptCap; attempt++) {
         if (externalSignal?.aborted) {
             const reason = externalSignal.reason;
             throw reason instanceof Error ? reason : new Error('OpenAI OAuth WS acquire aborted');
@@ -449,14 +454,14 @@ export async function _acquireWithRetry({
                 throw err;
             }
             // Transient but exhausted: surface with tagging.
-            if (attempt >= HANDSHAKE_MAX_ATTEMPTS) {
+            if (attempt >= attemptCap) {
                 if (err && typeof err === 'object') {
                     try { err.attempts = attempt; } catch {}
                     try { err.retryClassifier = classifier; } catch {}
                 }
                 try {
                     if (!process.env.MIXDOG_QUIET_PROVIDER_LOG) process.stderr.write(
-                        `[openai-oauth-ws] handshake failed after ${attempt}/${HANDSHAKE_MAX_ATTEMPTS} attempts: ${err?.message || err}\n`,
+                        `[openai-oauth-ws] handshake failed after ${attempt}/${attemptCap} attempts: ${err?.message || err}\n`,
                     );
                 } catch {}
                 throw err;
@@ -465,13 +470,13 @@ export async function _acquireWithRetry({
             const backoff = _backoffFor(attempt);
             try {
                 if (!process.env.MIXDOG_QUIET_PROVIDER_LOG) process.stderr.write(
-                    `[openai-oauth-ws] worker retry ${attempt}/${HANDSHAKE_MAX_ATTEMPTS} (transient: ${classifier}, backoff ${backoff}ms)\n`,
+                    `[openai-oauth-ws] worker retry ${attempt}/${attemptCap} (transient: ${classifier}, backoff ${backoff}ms)\n`,
                 );
             } catch {}
             try {
                 onRetry?.({
                     attempt,
-                    max: HANDSHAKE_MAX_ATTEMPTS,
+                    max: attemptCap,
                     classifier,
                     backoffMs: backoff,
                     error: err,
@@ -530,6 +535,12 @@ export async function sendViaWebSocket({
     traceProvider = 'openai-oauth',
     logSuppressedReasoningDeltas = true,
     warmupBody = null,
+    // Fast-fallback: when the caller has HTTP/SSE fallback enabled, cap the
+    // handshake acquire retry loop to a single attempt so a first
+    // acquire/first-byte failure surfaces immediately instead of burning the
+    // full exponential-backoff budget (measured 16.4s) before the caller can
+    // race HTTP. WS-only callers leave this false → full HANDSHAKE_MAX_ATTEMPTS.
+    fastFallback = false,
     // Test seams (undefined in production). Let the unit test drive the
     // retry state machine without opening real sockets or touching the
     // handshake-retry layer.
@@ -608,6 +619,12 @@ export async function sendViaWebSocket({
                 // one is either torn down or in an unknown state.
                 forceFresh: forceFresh || attemptIndex > 0,
                 externalSignal,
+                // Fast-fallback caps the handshake acquire loop at 1 attempt so
+                // the caller can race HTTP immediately instead of waiting out
+                // the full backoff budget. Only the FIRST midstream attempt is
+                // capped — a midstream retry (attemptIndex>0) is already past
+                // the fallback decision and keeps the normal budget.
+                maxAttempts: (fastFallback && attemptIndex === 0) ? 1 : HANDSHAKE_MAX_ATTEMPTS,
                 onRetry: (info) => {
                     handshakeRetries += 1;
                     if (info?.classifier) handshakeRetryClassifiers.push(info.classifier);
@@ -880,7 +897,16 @@ export async function sendViaWebSocket({
             _stampTool(err);
             const classifier = _classifyMidstreamError(err, midState);
             const retryLimit = classifier ? _midstreamRetryLimit(classifier) : 0;
-            if (classifier && attemptIndex < retryLimit) {
+            // Fast-fallback: a first-byte timeout on the FIRST attempt means the
+            // socket opened but the server never ACKed — race HTTP now instead
+            // of burning a midstream retry (fresh acquire + first-byte window).
+            // Only suppresses the first_byte_timeout bucket on attemptIndex 0;
+            // ws_1006/1011 mid-stream drops still retry (a live socket that died
+            // is cheaper to re-acquire than to cold-fall-back).
+            const fastFallbackSkipRetry = fastFallback
+                && attemptIndex === 0
+                && (classifier === 'first_byte_timeout' || err?.firstByteTimeout === true);
+            if (classifier && attemptIndex < retryLimit && !fastFallbackSkipRetry) {
                 // Retry-eligible: stash the first-attempt error, emit progress,
                 // and loop. The subsequent acquire uses forceFresh so no socket
                 // is shared between attempts.
@@ -949,6 +975,12 @@ export async function sendViaWebSocket({
         // calls: the next request is previous input + server output items
         // + tool results, and _computeDelta strips the first two parts so the
         // WebSocket frame only sends the true new tail.
+        // Captured BEFORE the overwrite below: chain-continuity trace must
+        // compare the request's prev_id against what the entry held when the
+        // request was BUILT, not the id we just received (review Low).
+        const priorEntryResponseId = typeof entry?.lastResponseId === 'string' && entry.lastResponseId.length > 0
+            ? entry.lastResponseId
+            : null;
         if (result.responseId && keepResponseChain) {
             entry.lastResponseId = result.responseId;
             entry.lastRequestSansInput = _stableStringify(_sansInput(requestBody));
@@ -981,6 +1013,24 @@ export async function sendViaWebSocket({
 
         const requestedServiceTier = body?.service_tier || null;
         const responseServiceTier = result.serviceTier || result.usage?.raw?.service_tier || null;
+        const sentPrevResponseId = typeof frame?.previous_response_id === 'string' && frame.previous_response_id.length > 0
+            ? frame.previous_response_id
+            : (typeof body?.previous_response_id === 'string' && body.previous_response_id.length > 0
+                ? body.previous_response_id
+                : null);
+        // Compare against the entry's PRE-request lastResponseId (captured
+        // above, before line ~979 overwrites it with the new response id):
+        // the WS delta path chains from entry state, so stale providerState
+        // OR the post-overwrite id would both mis-report continuity.
+        const cacheChain = traceProvider === 'xai'
+            ? (priorEntryResponseId
+                ? {
+                    requestPrevResponseId: sentPrevResponseId,
+                    chainContinuous: sentPrevResponseId !== null && sentPrevResponseId === priorEntryResponseId,
+                    continuationResetReason: null,
+                }
+                : grokCacheChainTraceFields(sendOpts?.providerState, sentPrevResponseId, null))
+            : null;
         traceAgentUsage({
             sessionId: poolKey,
             iteration,
@@ -994,6 +1044,11 @@ export async function sendViaWebSocket({
             rawUsage: result.usage?.raw || null,
             provider: traceProvider,
             serviceTier: responseServiceTier,
+            ...(cacheChain ? {
+                requestPrevResponseId: cacheChain.requestPrevResponseId,
+                chainContinuous: cacheChain.chainContinuous,
+                continuationResetReason: cacheChain.continuationResetReason,
+            } : {}),
         });
         const requestHasPreviousResponseId = typeof frame.previous_response_id === 'string' && frame.previous_response_id.length > 0;
         const transportCacheKeyHash = cacheKey

package/src/runtime/agent/orchestrator/providers/openai-oauth.mjs

@@ -809,6 +809,10 @@ export class OpenAIOAuthProvider {
         const iteration = Number.isFinite(Number(opts.iteration)) ? Number(opts.iteration) : null;
         const sendWs = typeof opts._sendViaWebSocketFn === 'function' ? opts._sendViaWebSocketFn : sendViaWebSocket;
         const sendHttp = typeof opts._sendViaHttpSseFn === 'function' ? opts._sendViaHttpSseFn : sendViaHttpSse;
+        // Fast-fallback is only meaningful when HTTP/SSE fallback is actually
+        // configured for this provider; WS-only paths keep the full handshake
+        // retry budget. This mirrors _shouldUseOpenAIHttpFallback's `enabled`.
+        const httpFallbackEnabled = _envFlag('MIXDOG_OPENAI_OAUTH_HTTP_FALLBACK', true);
         const _t1 = Date.now();
         const recordLiveModel = (result) => {
             if (result?.model && !_codexCatalogHas(result.model)) {
@@ -912,6 +916,13 @@ export class OpenAIOAuthProvider {
             useModel,
             displayModel: _displayCodexModel,
             forceFresh,
+            // Fast-fallback: when HTTP/SSE fallback is enabled, cap the WS
+            // handshake acquire loop at ONE attempt so a first
+            // acquire/first-byte failure aborts the remaining backoff retries
+            // and lets HTTP start immediately (skip-retries, no concurrent race
+            // → no double token spend). WS-only paths (fallback disabled) keep
+            // the full retry budget.
+            fastFallback: httpFallbackEnabled,
             // codex-parity prewarm (generate:false full frame on a fresh
             // socket, wire-verified 2026-07-03). DEFAULT ON: R19(off) vs
             // R20(on) A/B shows prewarm removes ALL early-session zero-cache
@@ -987,6 +998,26 @@ export class OpenAIOAuthProvider {
                 return this.send(messages, model, tools, { ...opts, _modelRetry: true });
             }
             if (_shouldUseOpenAIHttpFallback(err, externalSignal)) {
+                // Fast-path trace: the WS handshake acquire/first-byte failed on
+                // its FIRST attempt while fast-fallback was armed, so the
+                // remaining backoff retries were skipped and HTTP starts now.
+                // err.attempts===1 means the capped single-attempt path fired.
+                if (httpFallbackEnabled && Number(err?.attempts) === 1) {
+                    appendAgentTrace({
+                        sessionId: poolKey,
+                        iteration,
+                        kind: 'ws_fallback_fast',
+                        provider: 'openai-oauth',
+                        model: useModel,
+                        transport: 'websocket',
+                        elapsed_ms: Date.now() - _t1,
+                        payload: {
+                            elapsed_ms: Date.now() - _t1,
+                            classifier: err?.retryClassifier || err?.midstreamClassifier || null,
+                            code: err?.code || null,
+                        },
+                    });
+                }
                 try {
                     return await dispatchHttp(
                         err?.retryClassifier || err?.midstreamClassifier || err?.code || err?.message || 'ws_failed',

package/src/runtime/agent/orchestrator/providers/openai-ws-stream.mjs

@@ -25,6 +25,7 @@ import {
     PROVIDER_WS_INTER_CHUNK_TIMEOUT_MS,
     PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS,
     PROVIDER_SSE_IDLE_WATCHDOG_ENABLED,
+    PROVIDER_WS_FIRST_MEANINGFUL_TIMEOUT_MS,
     streamStalledError,
 } from '../stall-policy.mjs';
 import { customToolCallFromResponseItem } from './custom-tool-wire.mjs';
@@ -225,6 +226,13 @@ export async function _streamResponse({
     const socket = entry.socket;
     const preResponseCreatedMs = _positiveInt(_timeouts?.preResponseCreatedMs, WS_PRE_RESPONSE_CREATED_MS);
     const interChunkMs = _positiveInt(_timeouts?.interChunkMs, WS_INTER_CHUNK_MS);
+    // First-MEANINGFUL-frame deadline. Distinct from preResponseCreatedMs (a
+    // short pre-created byte-silence window that resetIdle clears on the FIRST
+    // frame of any kind): this timer is cleared only by a meaningful response
+    // event (response.created or the first content/tool-arg delta), so a server
+    // that ACKs with keepalive/metadata-only frames — resetting inter-chunk idle
+    // forever — still trips a stall before the agent watchdog's first-byte abort.
+    const firstMeaningfulMs = _positiveInt(_timeouts?.firstMeaningfulMs, PROVIDER_WS_FIRST_MEANINGFUL_TIMEOUT_MS);
     const _streamingStart = Date.now();
     let _firstDeltaEmitted = false;
     let content = '';
@@ -444,6 +452,12 @@ export async function _streamResponse({
     let semanticIdleTimer = null;
     const semanticIdleMs = PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS;
     const semanticIdleEnabled = PROVIDER_SSE_IDLE_WATCHDOG_ENABLED && semanticIdleMs > 0;
+    // First-meaningful-frame watchdog timer + one-shot latch. Armed alongside
+    // the pre-stream watchdog; cleared exactly once by the first meaningful
+    // response event (response.created / first content or tool-arg delta).
+    let firstMeaningfulTimer = null;
+    let firstMeaningfulSeen = false;
+    const firstMeaningfulEnabled = firstMeaningfulMs > 0;
 
     return new Promise((resolve, reject) => {
         // Pre-stream watchdog: the timer fires if the server never sends a
@@ -516,6 +530,37 @@ export async function _streamResponse({
                 idleTimer = null;
             }
         };
+        // First-meaningful-frame watchdog: fires if no meaningful response event
+        // (response.created / first content or tool-arg delta) arrives within
+        // firstMeaningfulMs, even while keepalive/metadata frames keep the
+        // inter-chunk idle timer fresh. On expiry treat the stream as stalled →
+        // named streamStalledError routes through the existing mid-stream
+        // retry/fallback path (fires before the 300s agent first-byte abort).
+        const armFirstMeaningfulWatchdog = () => {
+            if (!firstMeaningfulEnabled) return;
+            if (firstMeaningfulTimer) clearTimeout(firstMeaningfulTimer);
+            firstMeaningfulTimer = setTimeout(() => {
+                if (process.env.MIXDOG_DEBUG_AGENT) {
+                    process.stderr.write(`[agent-trace] ws-timeout kind=first-meaningful afterMs=${firstMeaningfulMs}\n`);
+                }
+                traceWsTimeout('first_meaningful_timeout', firstMeaningfulMs);
+                terminalError = streamStalledError('Responses WS', firstMeaningfulMs, { emittedToolCall: !!midState?.emittedToolCall });
+                try { terminalError.wsCloseCode = 4000; } catch {}
+                try { socket.close(4000, 'first_meaningful_timeout'); } catch {}
+                finish();
+            }, firstMeaningfulMs);
+            try { firstMeaningfulTimer.unref?.(); } catch {}
+        };
+        // Cleared exactly once, only by a meaningful response event — NOT by
+        // keepalive/metadata frames (which never call this).
+        const clearFirstMeaningfulWatchdog = () => {
+            if (firstMeaningfulSeen) return;
+            firstMeaningfulSeen = true;
+            if (firstMeaningfulTimer) {
+                clearTimeout(firstMeaningfulTimer);
+                firstMeaningfulTimer = null;
+            }
+        };
         const resetInterChunk = () => {
             if (interChunkTimer) clearTimeout(interChunkTimer);
             interChunkTimer = setTimeout(() => {
@@ -568,11 +613,16 @@ export async function _streamResponse({
         };
         // Meaningful-output progress bump: called by the same delta cases that
         // call onStreamDelta (text/reasoning/tool args). Arms the semantic idle.
-        const bumpSemanticIdle = () => { resetSemanticIdle(); };
+        // Also clears the first-meaningful-frame watchdog: the first content /
+        // tool-arg delta is the meaningful signal that satisfies it (response
+        // .created is cleared explicitly in its own case). Keepalive/metadata
+        // frames never reach here, so they cannot satisfy the watchdog.
+        const bumpSemanticIdle = () => { clearFirstMeaningfulWatchdog(); resetSemanticIdle(); };
         const cleanup = () => {
             if (idleTimer) clearTimeout(idleTimer);
             if (interChunkTimer) { clearTimeout(interChunkTimer); interChunkTimer = null; }
             if (semanticIdleTimer) { clearTimeout(semanticIdleTimer); semanticIdleTimer = null; }
+            if (firstMeaningfulTimer) { clearTimeout(firstMeaningfulTimer); firstMeaningfulTimer = null; }
             if (keepaliveTimer) { clearInterval(keepaliveTimer); keepaliveTimer = null; }
             if (messageHandler) socket.off('message', messageHandler);
             if (closeHandler) socket.off('close', closeHandler);
@@ -639,7 +689,11 @@ export async function _streamResponse({
                     if (event.response?.id) responseId = event.response.id;
                     // Server ack (first event). resetIdle() at the top of
                     // messageHandler already cleared the pre-stream watchdog and
-                    // armed the single idle timer — no extra bookkeeping here.
+                    // armed the single idle timer. response.created is a
+                    // MEANINGFUL frame, so it also satisfies the
+                    // first-meaningful watchdog (keepalive/metadata frames do
+                    // NOT reach this case, so they never clear it).
+                    clearFirstMeaningfulWatchdog();
                     break;
                 case 'response.output_text.delta':
                     try {
@@ -1065,6 +1119,7 @@ export async function _streamResponse({
         socket.on('close', closeHandler);
         socket.on('error', errorHandler);
         armPreStreamWatchdog();
+        armFirstMeaningfulWatchdog();
         // Periodic client-side WS ping while the stream is active. The server's
         // server closes with 1011 "keepalive ping timeout" when it thinks the
         // peer is silent during long reasoning windows where no data frames

package/src/runtime/agent/orchestrator/providers/retry-classifier.mjs

@@ -28,11 +28,18 @@ import {
 // HTTP statuses considered transient — safe to retry with backoff.
 //   408 — request timeout
 //   500/502/503/504 — server errors (overload / bad gateway / timeout)
-//   429 is deliberately excluded: rate-limit/quota windows are deterministic
-//   for the current call and must surface immediately instead of sleeping until
-//   an outer watchdog reports a misleading timeout.
+//   429 is excluded from blanket transient retry, but withRetry() honors a
+//   SHORT Retry-After header (< SHORT_RETRY_AFTER_MAX_MS) the way Claude Code
+//   does (refs/claude-code withRetry.ts SHORT_RETRY_THRESHOLD_MS = 20s):
+//   brief throttle windows retry once the server-stated wait elapses; long or
+//   headerless 429s still surface immediately (quota windows are
+//   deterministic — sleeping into an outer watchdog just relabels the error).
 const TRANSIENT_STATUSES = new Set([408, 500, 502, 503, 504])
 
+// Max server-stated Retry-After we are willing to sleep on a 429 before
+// surfacing it. Mirrors Claude Code's 20s short-retry threshold.
+const SHORT_RETRY_AFTER_MAX_MS = 20_000
+
 // HTTP statuses that mean "permanent: stop retrying, surface to caller".
 //   401/403 — auth issue
 //   404 — not found
@@ -296,6 +303,26 @@ function _classifyMidstreamWs(err, state, attemptIndex, policy) {
   if (err?.wsSendFailed || state.wsSendFailed) {
     return _allowMidstream('ws_send_failed', attemptIndex, policy)
   }
+  // Stall / local-close-4000 must be classified as RETRYABLE before the
+  // pre-`response.created` deny gate below. A first-meaningful-frame timeout
+  // fires with sawResponseCreated=false + close 4000 + StreamStalledError, so
+  // without this the pre-created gate would return null (terminal) and the
+  // stall would never route through the mid-stream retry / transport fallback.
+  {
+    const name = err?.name || ''
+    const closeCode = Number(err?.wsCloseCode || state.wsCloseCode || 0)
+    if (name === 'AgentStallAbortError' || state.watchdogAbort === 'AgentStallAbortError') {
+      return _allowMidstream('agent_stall', attemptIndex, policy)
+    }
+    if (name === 'StreamStalledAbortError' || name === 'StreamStalledError'
+      || err?.code === 'ESTREAMSTALL' || err?.streamStalled === true
+      || state.watchdogAbort === 'StreamStalledAbortError') {
+      // A stall AFTER a tool emit is unsafe to replay (double side-effect).
+      if (err?.unsafeToRetry === true) return null
+      return _allowMidstream('stream_stalled', attemptIndex, policy)
+    }
+    if (closeCode === 4000) return _allowMidstream('ws_4000', attemptIndex, policy)
+  }
   if (!state.sawResponseCreated) {
     const closeCode = Number(err?.wsCloseCode || state.wsCloseCode || 0)
     if (closeCode !== 1011 && closeCode !== 1012) return null
@@ -572,7 +599,16 @@ export async function withRetry(fn, opts = {}) {
         || caught?.providerQuota === true
         || caught?.quotaExceeded === true
       if (unsafeToRetry) throw caught
-      if (status === 429) throw caught
+      if (status === 429) {
+        // CC-style short Retry-After: a brief server-stated throttle window
+        // is worth one sleep-and-retry (prompt cache stays warm). Long or
+        // absent Retry-After surfaces immediately as before.
+        const ra = retryAfterMsFromError(caught)
+        if (ra == null || ra > SHORT_RETRY_AFTER_MAX_MS || attempt === maxAttempts - 1) throw caught
+        nextDelayMs = Math.max(0, ra)
+        nextDelayReason = 'retry-after'
+        continue
+      }
       if (kind !== 'transient') throw caught
       // Last attempt failed transiently — propagate to caller.
       if (attempt === maxAttempts - 1) throw caught