mixdog 0.9.36 → 0.9.38

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

@@ -26,6 +26,7 @@ import { makeInvalidToolArgsMarker } from './openai-compat-stream.mjs';
 import { createLeakGuard, createToolCallDedupe, dedupeToolCallList } from './anthropic-leaked-toolcall.mjs';
 import { customToolCallFromResponseItem } from './custom-tool-wire.mjs';
 import { CODEX_OAUTH_ORIGINATOR, CODEX_RESPONSES_URL, _displayCodexModel } from './openai-oauth.mjs';
+import { createActiveToolItemTracker } from './tool-stream-state.mjs';
 
 // Public OpenAI Responses API endpoint for the api-key `openai` provider.
 // The openai-direct WS transport hits the same origin (openai-ws-pool
@@ -297,7 +298,15 @@ export async function sendViaHttpSse({
             try {
                 _streamAbortReason.partialContent = content;
                 _streamAbortReason.partialToolCalls = toolCalls.length ? toolCalls.slice() : undefined;
-                _streamAbortReason.pendingToolUse = pendingCalls.size > 0 || emittedToolCallIds.size > 0;
+                // Shared active tool-item tracker (tool-stream-state.mjs) closes
+                // the custom-tool gap: a stall mid custom_tool_call_input.delta
+                // never lands in pendingCalls, so without activeToolItems/_toolInFlight
+                // a tool-bearing turn would look text-only and be wrongly accepted
+                // as a partial-final.
+                _streamAbortReason.pendingToolUse = pendingCalls.size > 0
+                    || emittedToolCallIds.size > 0
+                    || activeToolItems.size > 0
+                    || _toolInFlight === true;
                 _streamAbortReason.partialModel = model || undefined;
             } catch { /* best-effort enrichment */ }
             try { reader.cancel(_streamAbortReason).catch(() => {}); } catch {}
@@ -313,6 +322,15 @@ export async function sendViaHttpSse({
     let ttftMs = null;
     const toolCalls = [];
     const pendingCalls = new Map();
+    // Active tool-item / alias tracking shared with the WS + compat Responses
+    // streams (tool-stream-state.mjs). Mark on output_item.added / arg-input
+    // deltas, clear on output_item.done; _toolInFlight latches tool work the
+    // moment a call's input starts streaming (before it lands in pendingCalls).
+    const _toolTracker = createActiveToolItemTracker();
+    const activeToolItems = _toolTracker.items;
+    const markActiveToolItem = _toolTracker.mark;
+    const clearActiveToolItem = _toolTracker.clear;
+    let _toolInFlight = false;
     const reasoningItems = [];
     const citations = [];
     const citationKeys = new Set();
@@ -486,10 +504,12 @@ export async function sendViaHttpSse({
                 break;
             case 'response.output_item.added':
                 if (event.item?.type === 'function_call') {
+                    markActiveToolItem(event.item);
                     pendingCalls.set(event.item.id || '', {
                         name: event.item.name || '',
                         callId: event.item.call_id || '',
                     });
+                    _toolInFlight = true;
                 } else if (event.item?.type === 'tool_search_call') {
                     // Mark tool_search as in-flight the moment the item is
                     // added, mirroring function_call above, so the semantic
@@ -506,9 +526,21 @@ export async function sendViaHttpSse({
                             kind: 'tool_search',
                         });
                     }
+                    markActiveToolItem(event.item);
+                    _toolInFlight = true;
+                } else if (event.item?.type === 'custom_tool_call') {
+                    // Custom tool calls surface no pendingCalls entry, so mark
+                    // the item active at added-time (mirroring function_call /
+                    // tool_search_call above). The later custom_tool_call_input.delta
+                    // still marks too, but a stall between added and the first
+                    // input delta must already read as pendingToolUse.
+                    markActiveToolItem(event.item);
+                    _toolInFlight = true;
                 }
                 break;
             case 'response.function_call_arguments.delta':
+                markActiveToolItem(null, event.item_id);
+                _toolInFlight = true;
                 meaningful();
                 break;
             case 'response.function_call_arguments.done': {
@@ -530,6 +562,8 @@ export async function sendViaHttpSse({
                 break;
             }
             case 'response.custom_tool_call_input.delta':
+                markActiveToolItem(null, event.item_id);
+                _toolInFlight = true;
                 meaningful();
                 break;
             case 'response.output_item.done': {
@@ -546,11 +580,23 @@ export async function sendViaHttpSse({
                             emitToolCall(tc);
                         }
                     }
+                    // Drop the resolved function item from pendingCalls before
+                    // recomputing _toolInFlight (mirrors tool_search_call below
+                    // and the compat path) — otherwise a completed call keeps
+                    // pendingCalls.size > 0 and the latch never clears, so a
+                    // later max-output cutoff is misread as a tool in flight.
+                    pendingCalls.delete(item.id || '');
+                    clearActiveToolItem(item, item.id || '');
+                    _toolInFlight = pendingCalls.size > 0 || activeToolItems.size > 0;
                 } else if (item.type === 'tool_search_call') {
                     pendingCalls.delete(item.id || '');
                     pushToolSearchCall(item);
+                    clearActiveToolItem(item, item.id || '');
+                    _toolInFlight = pendingCalls.size > 0 || activeToolItems.size > 0;
                 } else if (item.type === 'custom_tool_call') {
                     pushCustomToolCall(item);
+                    clearActiveToolItem(item, item.id || '');
+                    _toolInFlight = pendingCalls.size > 0 || activeToolItems.size > 0;
                     meaningful();
                 }
                 break;
@@ -636,6 +682,20 @@ export async function sendViaHttpSse({
                 } else if (event.response.status === 'incomplete') {
                     const reason = _incompleteReasonFromEvent(event);
                     if (_isMaxOutputIncompleteReason(reason)) {
+                        // Max-output cutoff with a function/custom/tool_search
+                        // still in flight means the tool arguments were
+                        // truncated — do NOT mark a clean completion (mirrors
+                        // the compat Responses path), or partial args surface as
+                        // a successful tool call. Throw a stream-stalled
+                        // pendingToolUse error so the loop gates/retries.
+                        if (pendingCalls.size > 0 || activeToolItems.size > 0 || _toolInFlight === true) {
+                            const err = _stampToolSafety(new Error('OpenAI OAuth HTTP fallback response.done incomplete (max_output_tokens) with tool call in flight'));
+                            err.streamStalled = true;
+                            err.pendingToolUse = true;
+                            err.partialContent = content;
+                            err.partialModel = model || undefined;
+                            throw err;
+                        }
                         completed = true;
                         stopReason = 'length';
                         break;
@@ -652,6 +712,17 @@ export async function sendViaHttpSse({
             case 'response.incomplete': {
                 const reason = _incompleteReasonFromEvent(event);
                 if (_isMaxOutputIncompleteReason(reason)) {
+                    // See response.done incomplete above: a max-output cutoff
+                    // while a tool is in flight is a truncated tool call, not a
+                    // clean length completion.
+                    if (pendingCalls.size > 0 || activeToolItems.size > 0 || _toolInFlight === true) {
+                        const err = _stampToolSafety(new Error('OpenAI OAuth HTTP fallback response.incomplete (max_output_tokens) with tool call in flight'));
+                        err.streamStalled = true;
+                        err.pendingToolUse = true;
+                        err.partialContent = content;
+                        err.partialModel = model || undefined;
+                        throw err;
+                    }
                     completed = true;
                     stopReason = 'length';
                     break;

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

@@ -895,7 +895,26 @@ export async function sendViaWebSocket({
                 // Delta opt-in still chains via entry.lastResponseId above.
             }
 
-            const delta = _computeDelta({ entry, body: requestBody, traceProvider });
+            // Warmup writes the same prefix with generate:false, but the first
+            // real response must still be a FULL generating frame. Reusing the
+            // warmup response_id here would make _computeDelta reduce the frame
+            // input to [] when the warmup input matches, and a generate:false
+            // warmup is not a chainable response to continue from — so the first
+            // real turn would generate from an empty frame. Keep the warmup state
+            // for cache/trace, but compute the main frame as cold (full input +
+            // instructions).
+            const deltaEntry = warmupResult
+                ? {
+                    ...entry,
+                    lastResponseId: null,
+                    lastRequestSansInput: null,
+                    lastRequestInput: null,
+                    lastResponseItems: null,
+                    lastInputLen: 0,
+                    lastInputPrefixHash: null,
+                }
+                : entry;
+            const delta = _computeDelta({ entry: deltaEntry, body: requestBody, traceProvider });
             ({ mode, frame } = delta);
             deltaReason = delta.reason || null;
             strippedResponseItems = delta.strippedResponseItems || 0;
@@ -1063,7 +1082,11 @@ export async function sendViaWebSocket({
         // own, so retaining the anchor cannot corrupt the cache — it only adds
         // a delta fast-path when the items DO match.
         const keepResponseChain = !!result.responseId;
-        const keepSocket = true;
+        // Normally the socket is pooled for reuse. But an early tool-call settle
+        // (result.closeSocket) means the stream resolved before
+        // response.completed/done arrived: the server may still emit those as
+        // orphan frames, so the socket must be discarded, not reused.
+        const keepSocket = !result.closeSocket;
 
         // Update cache state for the next iteration in this session. openai-oauth
         // keeps the previous response anchor even when the model emitted tool
@@ -1300,7 +1323,7 @@ export async function sendViaWebSocket({
         } catch {}
 
         releaseWebSocket({ entry, poolKey, keep: keepSocket });
-        const { responseId: _ignored, responseItems: _responseItemsIgnored, ...out } = result;
+        const { responseId: _ignored, responseItems: _responseItemsIgnored, closeSocket: _closeSocketIgnored, ...out } = result;
         if (includeResponseId && result.responseId) out.responseId = result.responseId;
         if (warmupResult) {
             try {

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

@@ -410,16 +410,6 @@ function convertMessagesToResponsesInput(messages, opts = {}) {
     for (const m of messages) {
         if (!m || m.role === 'system') continue;
         if (m.role === 'tool') {
-            if (Array.isArray(m.nativeToolSearch?.openaiTools)) {
-                out.push({
-                    type: 'tool_search_output',
-                    call_id: m.toolCallId || '',
-                    status: 'completed',
-                    execution: 'client',
-                    tools: m.nativeToolSearch.openaiTools,
-                });
-                continue;
-            }
             const { output, mediaContent } = splitToolContentForOpenAIResponses(m.content);
             if (customToolCallNameById.has(m.toolCallId || '')) {
                 out.push({
@@ -449,14 +439,7 @@ function convertMessagesToResponsesInput(messages, opts = {}) {
             // reasoning in `input` triggers "Duplicate item".
             if (m.content) out.push(wireMessage('assistant', normalizeContentForOpenAIResponses(m.content, { role: 'assistant' })));
             for (const tc of m.toolCalls) {
-                if (tc.nativeType === 'tool_search_call' || tc.name === 'load_tool' || tc.name === 'tool_search') {
-                    out.push({
-                        type: 'tool_search_call',
-                        call_id: tc.id,
-                        execution: 'client',
-                        arguments: tc.arguments || {},
-                    });
-                } else if (isCustomToolCallRecord(tc)) {
+                if (isCustomToolCallRecord(tc)) {
                     if (tc.id) customToolCallNameById.set(tc.id, tc.name || '');
                     out.push({
                         type: 'custom_tool_call',
@@ -468,7 +451,7 @@ function convertMessagesToResponsesInput(messages, opts = {}) {
                     out.push({
                         type: 'function_call',
                         call_id: tc.id,
-                        name: tc.name,
+                        name: tc.name === 'tool_search' ? 'load_tool' : tc.name,
                         arguments: JSON.stringify(tc.arguments),
                     });
                 }
@@ -487,8 +470,8 @@ function convertMessagesToResponsesInput(messages, opts = {}) {
 function toOpenAIResponsesTool(t) {
     if (t?.name === 'load_tool' || t?.name === 'tool_search') {
         return {
-            type: 'tool_search',
-            execution: 'client',
+            type: 'function',
+            name: 'load_tool',
             description: t.description,
             parameters: t.inputSchema,
         };
@@ -923,13 +906,14 @@ 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,
+            // Default refs-style recovery: keep using WS first. A transient
+            // first-byte / mid-stream stall closes the bad socket and retries on
+            // a fresh WS entry; only after the bounded WS retry budget is
+            // exhausted does openai-oauth fall back to HTTP/SSE. This preserves
+            // the hot WS/cache path for temporary blips while still preventing
+            // TUI-level hangs. Operators can opt into immediate HTTP fallback
+            // for diagnostics with MIXDOG_OPENAI_OAUTH_FAST_HTTP_FALLBACK=1.
+            fastFallback: httpFallbackEnabled && _envFlag('MIXDOG_OPENAI_OAUTH_FAST_HTTP_FALLBACK', false),
             // 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

package/src/runtime/agent/orchestrator/providers/openai-transport-policy.mjs

@@ -3,20 +3,20 @@
  * Responses-API transport policy switch (OpenAI OAuth/direct + xAI/compat).
  *
  * One env knob, MIXDOG_OAI_TRANSPORT, selects among the transport modes:
- *   - 'ws-delta'  (DEFAULT): WS transport, refs-compatible delta ON.
+ *   - 'ws-delta'  WS-only transport, refs-compatible delta ON.
  *   - 'ws-full'   WS transport, delta OFF (always full frames).
  *   - 'http-sse'  force the HTTP/SSE transport directly (delta is WS-only, so
  *                 it stays off).
- *   - 'auto'      compatibility spelling for the default ws-delta route.
+ *   - 'auto'      WS-first route with HTTP/SSE fallback on websocket failure.
  *
- * No mode performs an implicit HTTP fallback: explicit modes pin their
- * transport. Delta is selected solely via MIXDOG_OAI_TRANSPORT=ws-delta
- * (or by leaving the env unset).
+ * Default/unset behaves like 'auto': prefer WS/delta for cache hotness, but
+ * fall back to HTTP/SSE after bounded websocket failures. Explicit ws-* modes
+ * pin WS for experiments; http-sse pins HTTP.
  */
 
 // Normalize the transport mode token. Underscores/spaces and a few common
 // spellings collapse to the canonical modes. Unknown/empty → null so the
-// caller falls back to the default 'ws-delta'.
+// caller falls back to the default 'auto'.
 export function _normalizeTransportMode(raw) {
     const v = String(raw || '').trim().toLowerCase().replace(/[\s_]+/g, '-');
     switch (v) {
@@ -27,7 +27,7 @@ export function _normalizeTransportMode(raw) {
         case 'http-sse': case 'httpsse': case 'http': case 'sse': case 'http/sse':
             return 'http-sse';
         case 'auto':
-            return 'ws-delta';
+            return 'auto';
         default:
             return null;
     }
@@ -63,9 +63,9 @@ export const RESPONSES_TRANSPORT_CAPABILITIES = Object.freeze({
 export function _gateTransportMode(mode, caps) {
     let m = mode;
     // Delta unsupported → keep WS transport but force full frames.
-    if (m === 'ws-delta' && !caps.delta) m = 'ws-full';
+    if ((m === 'auto' || m === 'ws-delta') && !caps.delta) m = caps.ws ? 'ws-full' : (caps.http ? 'http-sse' : 'auto');
     // WS unsupported → prefer HTTP, else defer to auto.
-    if ((m === 'ws-full' || m === 'ws-delta') && !caps.ws) m = caps.http ? 'http-sse' : 'ws-delta';
+    if ((m === 'auto' || m === 'ws-full' || m === 'ws-delta') && !caps.ws) m = caps.http ? 'http-sse' : 'auto';
     // HTTP unsupported → prefer full-frame WS, else defer to auto.
     if (m === 'http-sse' && !caps.http) m = caps.ws ? 'ws-full' : 'auto';
     return m;
@@ -76,8 +76,8 @@ export function _gateTransportMode(mode, caps) {
  * per-provider capabilities.
  * @param {Record<string,string|undefined>} [env=process.env]
  * @param {{ws?:boolean,http?:boolean,delta?:boolean}} [capabilities=FULL_RESPONSES_TRANSPORT_CAPS]
- * @returns {{ mode: 'ws-full'|'ws-delta'|'http-sse',
- *             requestedMode: 'ws-full'|'ws-delta'|'http-sse',
+ * @returns {{ mode: 'auto'|'ws-full'|'ws-delta'|'http-sse',
+ *             requestedMode: 'auto'|'ws-full'|'ws-delta'|'http-sse',
  *             transport: 'auto'|'ws'|'http',
  *             allowHttpFallback: boolean,
  *             delta: { force: boolean, refs: boolean, optIn: boolean },
@@ -85,7 +85,7 @@ export function _gateTransportMode(mode, caps) {
  */
 export function resolveResponsesTransportPolicy(env = process.env, capabilities = FULL_RESPONSES_TRANSPORT_CAPS) {
     const caps = { ...FULL_RESPONSES_TRANSPORT_CAPS, ...(capabilities || {}) };
-    const requestedMode = _normalizeTransportMode(env?.MIXDOG_OAI_TRANSPORT) || 'ws-delta';
+    const requestedMode = _normalizeTransportMode(env?.MIXDOG_OAI_TRANSPORT) || 'auto';
     const mode = _gateTransportMode(requestedMode, caps);
     let transport;
     let delta;
@@ -98,6 +98,7 @@ export function resolveResponsesTransportPolicy(env = process.env, capabilities
             transport = 'ws';
             delta = DELTA_OFF;      // explicit full frames
             break;
+        case 'auto':
         case 'ws-delta':
             transport = 'ws';
             // Reachable only when caps.delta is true (else gated to ws-full).
@@ -112,9 +113,11 @@ export function resolveResponsesTransportPolicy(env = process.env, capabilities
         mode,
         requestedMode,
         transport,
-        // No mode performs an implicit HTTP fallback; explicit http-sse pins the
-        // HTTP transport instead. Kept as a field so existing callers gate off.
-        allowHttpFallback: false,
+        // Codex refs behavior: default/auto is WS-first but not WS-only. If the
+        // websocket path stalls/fails before emitting live output, callers may
+        // replay the request over HTTP/SSE. Explicit ws-* modes remain pinned
+        // for transport experiments; explicit http-sse bypasses WS entirely.
+        allowHttpFallback: requestedMode === 'auto' && caps.http,
         delta,
         capabilities: caps,
     };

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

@@ -195,8 +195,11 @@ const TRANSPORT_ONLY_FRAME_FIELDS = new Set(['stream', 'background']);
 // identical byte-for-byte: `type` always leads, then the body's codex
 // struct-order keys follow verbatim. A delta send passes previousResponseId
 // (inserted immediately before `input`, matching codex's refs position) and
-// inputOverride (the stripped tail); an empty instructions string is dropped
-// in that case because the server resolves it from previous_response_id.
+// inputOverride (the stripped tail). `instructions` MUST still be resent on
+// previous_response_id frames: per the OpenAI Responses API, the previous
+// response's top-level instructions are NOT carried over to the chained
+// response, so dropping them here strips the system/lead prompt from every
+// continuation turn. Only an empty instructions string is omitted.
 // Full/warmup frames pass the body unchanged and keep every key in place.
 // omitTransportFields is used by wire-parity/prewarm helpers to drop stream/background.
 export function _buildResponseCreateFrame(body, { previousResponseId = null, inputOverride, omitTransportFields = false } = {}) {

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

@@ -15,6 +15,10 @@ import { codexOriginator, codexUserAgent, codexVersionHeader } from './codex-cli
 import {
     PROVIDER_WS_ACQUIRE_TIMEOUT_MS,
     PROVIDER_WS_HANDSHAKE_TIMEOUT_MS,
+    PROVIDER_WS_PING_ENABLED,
+    PROVIDER_WS_PING_INTERVAL_MS,
+    PROVIDER_WS_PONG_TIMEOUT_MS,
+    PROVIDER_WS_LIVENESS_STALE_MS,
     resolveTimeoutMs,
 } from '../stall-policy.mjs';
 
@@ -36,6 +40,10 @@ export const WS_IDLE_MS = resolveTimeoutMs(
 );
 const WS_HANDSHAKE_TIMEOUT_MS = PROVIDER_WS_HANDSHAKE_TIMEOUT_MS;
 const WS_ACQUIRE_TIMEOUT_MS = PROVIDER_WS_ACQUIRE_TIMEOUT_MS;
+const WS_PING_INTERVAL_MS = PROVIDER_WS_PING_INTERVAL_MS;
+const WS_PONG_TIMEOUT_MS = PROVIDER_WS_PONG_TIMEOUT_MS;
+const WS_LIVENESS_STALE_MS = PROVIDER_WS_LIVENESS_STALE_MS;
+const WS_PING_ENABLED = PROVIDER_WS_PING_ENABLED;
 
 // WS socket pool buckets are keyed by `poolKey` (the per-call sessionId)
 // to isolate parallel agent invocations — each gets its own socket so
@@ -263,6 +271,10 @@ function _getPoolArr(poolKey) {
 }
 
 function _removeFromPool(poolKey, entry) {
+    // Always tear down per-entry timers so evicting a socket never leaks an
+    // idle-close or liveness-ping interval.
+    _clearIdle(entry);
+    _clearLiveness(entry);
     if (!poolKey) return;
     const arr = _wsPool.get(poolKey);
     if (!arr) return;
@@ -293,6 +305,70 @@ function _isOpen(entry) {
     return entry?.socket?.readyState === WebSocket.OPEN;
 }
 
+function _clearLiveness(entry) {
+    if (entry?.pingTimer) {
+        clearInterval(entry.pingTimer);
+        entry.pingTimer = null;
+    }
+}
+
+// Force a dead/half-open socket out of the pool. close() alone can hang on a
+// wedged socket, so follow with terminate() to guarantee FD release.
+function _evictDead(poolKey, entry) {
+    try { entry.socket.close(1000, 'ws_liveness_dead'); } catch {}
+    try { entry.socket.terminate?.(); } catch {}
+    _removeFromPool(poolKey, entry);
+}
+
+// Send one ws-level ping and resolve true iff a pong lands within timeoutMs.
+// Never rejects. On any success it refreshes lastAliveAt so the caller/loop
+// treats the socket as fresh.
+function _pingProbe(entry, timeoutMs) {
+    return new Promise((resolve) => {
+        const socket = entry?.socket;
+        if (!socket || socket.readyState !== WebSocket.OPEN) { resolve(false); return; }
+        let done = false;
+        const finish = (alive) => {
+            if (done) return;
+            done = true;
+            clearTimeout(timer);
+            try { socket.removeListener('pong', onPong); } catch {}
+            resolve(alive);
+        };
+        const onPong = () => { entry.lastAliveAt = Date.now(); finish(true); };
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        try { timer.unref?.(); } catch {}
+        try {
+            socket.on('pong', onPong);
+            socket.ping();
+        } catch {
+            finish(false);
+        }
+    });
+}
+
+// While an entry sits idle in the pool, ping it every WS_PING_INTERVAL_MS.
+// A missed pong (or a socket that is no longer OPEN) evicts the entry so it can
+// never be handed out dead. Busy entries are skipped — an in-flight turn has
+// its own inter-chunk/semantic-idle watchdogs.
+function _armLiveness(poolKey, entry) {
+    _clearLiveness(entry);
+    entry.pingTimer = setInterval(async () => {
+        if (entry.busy || entry.closing || entry.probing) return;
+        if (!_isOpen(entry)) { _evictDead(poolKey, entry); return; }
+        // Recent activity ⇒ assume live, skip the probe this tick.
+        if (Date.now() - (entry.lastAliveAt || 0) < WS_LIVENESS_STALE_MS) return;
+        entry.probing = true;
+        try {
+            const alive = await _pingProbe(entry, WS_PONG_TIMEOUT_MS);
+            if (!alive && !entry.busy) _evictDead(poolKey, entry);
+        } finally {
+            entry.probing = false;
+        }
+    }, WS_PING_INTERVAL_MS);
+    try { entry.pingTimer.unref?.(); } catch {}
+}
+
 // Awaited frame send. Asserts the socket is OPEN and resolves only after
 // the underlying transport reports the buffered write succeeded (or fails)
 // via the WebSocket send callback. Raw `socket.send(JSON.stringify(...))`
@@ -596,15 +672,36 @@ export async function acquireWebSocket({ auth, poolKey, cacheKey, codexHeaders,
         for (let i = arr.length - 1; i >= 0; i--) {
             if (!_isOpen(arr[i]) || arr[i].closing) {
                 _clearIdle(arr[i]);
+                _clearLiveness(arr[i]);
                 arr.splice(i, 1);
             }
         }
         if (arr.length === 0) _wsPool.delete(poolKey);
-        // Reuse any idle open entry (cache-warm path).
-        const idle = arr.find(e => !e.busy);
-        if (idle) {
+        // Reuse an idle open entry (cache-warm path). An entry with no observed
+        // activity within the freshness window is ping-probed under a short
+        // bound before hand-out; a dead one is evicted and the scan retries the
+        // next idle entry so a busy caller is never handed a wedged socket.
+        let idle;
+        while ((idle = arr.find(e => !e.busy))) {
             _clearIdle(idle);
+            _clearLiveness(idle);
+            // Reserve the entry BEFORE awaiting the probe: _pingProbe yields the
+            // event loop, so without this a second concurrent acquire could scan
+            // the same still-idle entry and both would take it. Marking busy up
+            // front makes the find() above skip it; on probe failure it is
+            // evicted (removed from arr) so the loop continues cleanly.
             idle.busy = true;
+            if (WS_PING_ENABLED && Date.now() - (idle.lastAliveAt || 0) >= WS_LIVENESS_STALE_MS) {
+                const alive = await _pingProbe(idle, WS_PONG_TIMEOUT_MS);
+                if (!alive) {
+                    if (process.env.MIXDOG_DEBUG_AGENT) {
+                        process.stderr.write(`[agent-trace] acquire-evict-dead poolKey=${poolKey} reason=missed_pong elapsed=${Date.now() - _acqStart}ms\n`);
+                    }
+                    _evictDead(poolKey, idle);
+                    continue;
+                }
+            }
+            idle.lastAliveAt = Date.now();
             // Defensive: pre-existing pooled entries created before the
             // prefix-hash field was introduced may not have it set. Normalize
             // to null so the first delta check reads a deterministic value
@@ -646,6 +743,11 @@ export async function acquireWebSocket({ auth, poolKey, cacheKey, codexHeaders,
                 ephemeral: true,
                 sessionToken: ephSessionToken,
             };
+            entry.lastAliveAt = Date.now();
+            entry.pingTimer = null;
+            entry.probing = false;
+            socket.on('pong', () => { entry.lastAliveAt = Date.now(); });
+            socket.on('message', () => { entry.lastAliveAt = Date.now(); });
             socket.on('close', () => { entry.closing = true; });
             return { entry, reused: false };
         }
@@ -674,6 +776,11 @@ export async function acquireWebSocket({ auth, poolKey, cacheKey, codexHeaders,
         ephemeral: false,
         sessionToken,
     };
+    entry.lastAliveAt = Date.now();
+    entry.pingTimer = null;
+    entry.probing = false;
+    socket.on('pong', () => { entry.lastAliveAt = Date.now(); });
+    socket.on('message', () => { entry.lastAliveAt = Date.now(); });
     if (poolKey && !forceFresh) _getPoolArr(poolKey).push(entry);
     socket.on('close', () => {
         entry.closing = true;
@@ -690,7 +797,12 @@ export function releaseWebSocket({ entry, poolKey, keep }) {
         _removeFromPool(poolKey, entry);
         return;
     }
+    // Mark activity at release, then arm both the idle-close timer and the
+    // periodic liveness ping so a socket that dies while pooled is evicted
+    // before the next acquire can hand it out.
+    entry.lastAliveAt = Date.now();
     _scheduleIdleClose(poolKey, entry);
+    if (WS_PING_ENABLED) _armLiveness(poolKey, entry);
 }
 
 // Drain-complete fence — set true once _closeAllPooledSockets runs so any
@@ -706,6 +818,10 @@ export function _closeAllPooledSockets(reason = 'shutdown') {
     _drainComplete = true;
     for (const arr of _wsPool.values()) {
         for (const entry of arr) {
+            // Tear down per-entry timers before dropping the map, otherwise the
+            // idle-close and liveness-ping intervals outlive the drained pool.
+            _clearIdle(entry);
+            _clearLiveness(entry);
             try { entry.socket.close(1000, reason); } catch {}
         }
     }