mixdog 0.9.109 → 0.9.110

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.9.109",
+  "version": "0.9.110",
   "private": false,
   "type": "module",
   "description": "Standalone mixdog coding-agent CLI/TUI workspace.",

package/scripts/run-suite.mjs

@@ -51,6 +51,7 @@ export const SUITES = {
     'pretool-ask-runtime-test.mjs',
     'prompt-input-parity-test.mjs',
     'reactive-compact-persist-smoke.mjs',
+    'reasoning-replay-policy-test.mjs',
     'repl-stream-finalize-test.mjs',
     'result-classification-test.mjs',
     'rg-runner-test.mjs',
@@ -60,6 +61,7 @@ export const SUITES = {
     'session-title-controller-test.mjs',
     'set-effort-config-test.mjs',
     'shell-jobs-windows-hide-test.mjs',
+    'spawn-ws-prewarm-test.mjs',
     'spinner-meta-test.mjs',
     'statusline-agents-test.mjs',
     'statusline-quota-hysteresis-test.mjs',

package/src/rules/shared/01-tool.md

@@ -2,51 +2,52 @@
 
 - Baseline routing assigns each facet directly by the evidence needed to
   determine the complete edit:
-  path/name only→`find`; wildcard/recursive paths→`glob`; exact directory
-  entries→`list`;
+  path/name only→`find`; wildcard/recursive paths→`glob` (including known-root
+  unknown descendants); exact directory entries→`list`;
   source content/value/`path:line`→`grep`; exact symbol/relation→`code_graph`;
   known file/range→`read`;
-  web/current→`search`; returned URL body→`web_fetch`; prior work→`recall`;
+  web/current→`search`; returned URL body→`web_fetch`; prior work→`recall`
+  (history only, never current local state);
   durable compact English memory→`memory`; explicit project change→`cwd`;
   explicit user-requested conversation reset→`session_manage`.
   Use only named tools present in the current tool surface.
   `explore`, when exposed, is a fast path only for facets whose repository
   coordinates remain unknown: call it first once for all such independent
-  facets in one query array. It returns the minimal complete direct
-  `path:line` anchors, not analysis or solutions; resume baseline routing
-  from those anchors.
+  facets in one query array. It returns direct `path:line` anchors, not
+  analysis or solutions; anchors are tool-verified coordinates that END
+  their location facets — never re-locate or second-guess them; resume
+  baseline routing from them.
 - Act only on verified identities (cwd/project/user/tool-returned) — paths,
   module specifiers, symbols, data/record shapes alike; a guessed identity is
-  itself a facet, verified by the cheapest batched probe (one lookup or sample
-  record) before anything depends on it. Within the current project, pass
+  verified by one lookup or sample only when the next call or edit references
+  it. Within the current project, pass
   project-relative paths and omit optional scopes equal to its root; explicit
   paths may be outside cwd only for targets outside the project.
-- A conclusive result ends its facet, and known state — task/brief-supplied
-  facts, returned content, and the effects of your own successful calls — is
-  never re-acquired: never broaden, repeat, or reconfirm. Follow up only when
-  prior output is needed to form the next call; on failure rerun only the
-  failed check.
-  Batch calls iff no call needs another's output (as input or to decide its
-  need/scope) or can change another's inputs/state; otherwise serialize, and
-  drop a call whose deciding evidence already suffices. Before each retrieval
-  batch, deduplicate every facet the task still requires, route each once to
-  the cheapest sufficient tool with all required variants/scopes, and launch
-  every independent call together. Never
-  split one decision across overlapping facets, duplicate/broaden a facet
-  through another tool, add `shell`/`apply_patch` mutation merely to widen
-  retrieval, reserve known work, or cap fanout.
-  Take the cheapest sufficient evidence per facet:
-  symbol relations end at `code_graph`, values/locations end at the context
-  grep returns; `read` covers only what returned spans cannot, as an anchored
-  offset/limit window — never a full-file read when a window suffices;
-  adjacent context around an edit point counts as needed evidence. The moment
-  evidence determines the edit, stop retrieving and patch.
-- Once the edit is determined, finish in one assistant turn: one
-  `apply_patch` per file or cohesive unit, all patches first, then one batched
-  verification `shell` for required postconditions only; runtime waits
-  for every patch and skips the shell if any fails. Retry only failed envelopes.
-  Create or edit text only with `apply_patch`, never `shell`. Earlier `shell`
-  is only for executable/runtime/state evidence unavailable to file tools—an
-  independent facet, batched with the rest.
+- Plan the fewest dependent rounds, then the fewest calls. A conclusive
+  result ends its facet, and known state — task/brief-supplied facts,
+  returned content, your own successful calls' effects — is never
+  re-acquired, broadened, or reconfirmed. Batch calls iff none needs
+  another's output or can change another's inputs/state; otherwise
+  serialize. Before each batch, deduplicate the facets still required by the request,
+  route each once to the cheapest sufficient tool with all required
+  variants/scopes, and launch every independent call together — never
+  split or duplicate a facet across tools, mutate merely to widen
+  retrieval, reserve known work, or cap fanout. Symbol relations end at
+  `code_graph`; values/locations end at the context grep returns; `read`
+  covers only what returned spans cannot, as an anchored offset/limit
+  window. The moment evidence determines the answer, edit, or deliverable,
+  stop retrieving; patch if needed.
+- Once the edit or deliverable is determined, finish in one assistant turn:
+  one `apply_patch` per file or cohesive unit, all patches first, then one
+  batched verification `shell` that runs the real required postconditions
+  on every changed file and produced artifact, never echoes a claim;
+  runtime waits for every patch and skips the shell
+  if any fails. Retry only failed envelopes; rerun a failed check only
+  after a fix that can change its result, else report it unresolved.
+  Hand-authored text is edited only with `apply_patch`; computed artifacts
+  (data/reports/derived values) come from `shell` computation, never
+  hand-transcribed numbers. Earlier `shell` is only for runtime/state
+  evidence unavailable to file tools—an independent facet, batched with
+  the rest.
 - A background `task_id` ends the turn; completion resumes work. Never poll;
   use task control only for recovery or a required blocking result.

package/src/runtime/agent/orchestrator/agent-runtime/title-completion.mjs

@@ -39,7 +39,13 @@ export function createTitleCompletion(deps = {}) {
             config,
         });
         if (!route || typeof route !== 'object') {
-            throw new Error('Session title maintenance route is unresolved.');
+            const error = new Error('Session title maintenance route is unresolved.');
+            // Machine-readable marker: callers (session-title controller)
+            // downgrade this to a one-shot "titling disabled" skip instead of
+            // logging a stack per session (e.g. bench profiles without a
+            // maintainer/default route).
+            error.code = 'MAINTENANCE_ROUTE_UNRESOLVED';
+            throw error;
         }
         const providerName = String(route.provider || '').trim();
         const model = String(route.model || '').trim();

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

@@ -41,6 +41,8 @@ import {
 } from './anthropic-oauth-credentials.mjs';
 import {
     PROVIDER_FIRST_BYTE_TIMEOUT_MS,
+    PROVIDER_NONSTREAM_TOTAL_TIMEOUT_MS,
+    createTimeoutSignal,
     createPassthroughSignal,
 } from '../stall-policy.mjs';
 import {
@@ -740,7 +742,11 @@ export class AnthropicOAuthProvider {
         // Test seam: injectable request factory for retry-path tests.
         const doRequestImpl = typeof opts._doRequestFn === 'function' ? opts._doRequestFn : doRequest;
 
-        const requestWithRetry = async (accessToken, requestBody = body) => withRetry(async ({ signal: attemptSignal }) => {
+        const requestWithRetry = async (
+            accessToken,
+            requestBody = body,
+            retrySignal = totalSignal,
+        ) => withRetry(async ({ signal: attemptSignal }) => {
             const result = await doRequestImpl(accessToken, attemptSignal, requestBody);
             const status = Number(result?.response?.status || 0);
             const transientStatus = classifyError({ httpStatus: status }) === 'transient';
@@ -772,7 +778,7 @@ export class AnthropicOAuthProvider {
             }
             return result;
         }, {
-            signal: totalSignal,
+            signal: retrySignal,
             maxAttempts: anthropicMaxAttempts(),
             backoffMs: ANTHROPIC_RETRY_BACKOFF_MS,
             retryJitterRatio: ANTHROPIC_RETRY_JITTER_RATIO,
@@ -816,28 +822,69 @@ export class AnthropicOAuthProvider {
         const issueNonStreamingFallback = async (controller, abortReason) => {
             try { controller?.abort?.(abortReason); } catch {}
             try { onStageChange?.('requesting', { transport: 'non-streaming-fallback' }); } catch {}
-            let fallback = await requestWithRetry(creds.accessToken, { ...body, stream: false });
-            if (fallback.response.status === 401) {
-                cleanupCancelHandler(fallback.cancelHandler);
-                try { fallback.controller?.abort?.(); } catch {}
-                creds = await this.ensureAuth({ forceRefresh: true, reason: '401' });
-                fallback = await requestWithRetry(creds.accessToken, { ...body, stream: false });
-            }
-            if (!fallback.response.ok) {
-                const text = await fallback.response.text().catch(() => '');
-                cleanupCancelHandler(fallback.cancelHandler);
-                try { fallback.controller?.abort?.(); } catch {}
-                const fallbackError = new Error(`Anthropic OAuth API ${fallback.response.status}: ${this.scrubTokens(text).slice(0, 200)}`);
-                fallbackError.status = fallback.response.status;
-                fallbackError.httpStatus = fallback.response.status;
-                throw fallbackError;
-            }
+            const timeoutMs = Number(opts._nonStreamingTimeoutMs) > 0
+                ? Number(opts._nonStreamingTimeoutMs)
+                : PROVIDER_NONSTREAM_TOTAL_TIMEOUT_MS;
+            const lifetime = createTimeoutSignal(
+                totalSignal,
+                timeoutMs,
+                'Anthropic OAuth non-streaming fallback',
+            );
+            let fallback = null;
+            let lifetimeAbortHandler = null;
+            const releaseFallback = (reason) => {
+                if (lifetimeAbortHandler) {
+                    try { lifetime.signal.removeEventListener('abort', lifetimeAbortHandler); } catch {}
+                    lifetimeAbortHandler = null;
+                }
+                cleanupCancelHandler(fallback?.cancelHandler);
+                try { fallback?.controller?.abort?.(reason); } catch {}
+                fallback = null;
+            };
+            const requestFallback = async (accessToken) => {
+                const result = await requestWithRetry(
+                    accessToken,
+                    { ...body, stream: false },
+                    lifetime.signal,
+                );
+                fallback = result;
+                lifetimeAbortHandler = () => {
+                    try { result.controller?.abort?.(lifetime.signal.reason); } catch {}
+                };
+                if (lifetime.signal.aborted) {
+                    lifetimeAbortHandler();
+                    const reason = lifetime.signal.reason;
+                    throw reason instanceof Error
+                        ? reason
+                        : new Error('Anthropic OAuth non-streaming fallback aborted');
+                }
+                lifetime.signal.addEventListener('abort', lifetimeAbortHandler, { once: true });
+                return result;
+            };
             try {
+                fallback = await requestFallback(creds.accessToken);
+                if (fallback.response.status === 401) {
+                    releaseFallback('Anthropic OAuth non-streaming fallback refreshing auth');
+                    creds = await this.ensureAuth({ forceRefresh: true, reason: '401' });
+                    fallback = await requestFallback(creds.accessToken);
+                }
+                if (!fallback.response.ok) {
+                    const text = await fallback.response.text().catch(() => '');
+                    const fallbackError = new Error(`Anthropic OAuth API ${fallback.response.status}: ${this.scrubTokens(text).slice(0, 200)}`);
+                    fallbackError.status = fallback.response.status;
+                    fallbackError.httpStatus = fallback.response.status;
+                    throw fallbackError;
+                }
                 const message = await fallback.response.json();
                 return normalizeAnthropicNonStreamingResponse(message, useModel);
+            } catch (err) {
+                if (lifetime.signal.aborted && lifetime.signal.reason instanceof Error) {
+                    throw lifetime.signal.reason;
+                }
+                throw err;
             } finally {
-                cleanupCancelHandler(fallback.cancelHandler);
-                try { fallback.controller?.abort?.('Anthropic non-streaming fallback complete'); } catch {}
+                releaseFallback('Anthropic non-streaming fallback complete');
+                lifetime.cleanup();
             }
         };
 

package/src/runtime/agent/orchestrator/providers/anthropic-sse.mjs

@@ -47,7 +47,13 @@ function _captureMidstreamAbort(state, reason) {
     const reasonName = reason?.name || '';
     if (reasonName === 'AgentStallAbortError' || reasonName === 'StreamStalledAbortError') {
         state.watchdogAbort = reasonName;
-    } else {
+    } else if (reasonName !== 'ProviderTimeoutError' && reasonName !== 'StreamStalledError') {
+        // Internal timeout/stall abort reasons are transport symptoms, not a
+        // caller decision. Recording them as userAbort silently vetoed the
+        // mid-stream retry ladder (_classifyMidstreamSse returns null on
+        // userAbort → the turn surfaced as an instant unlogged failure).
+        // Leaving state untouched keeps them classifiable by the thrown error
+        // itself (EPROVIDERTIMEOUT/ESTREAMSTALL → transient/stall retry).
         state.userAbort = true;
     }
 }

package/src/runtime/agent/orchestrator/providers/anthropic.mjs

@@ -19,6 +19,7 @@ import { readStreamOutcome } from './lib/stream-outcome.mjs';
 import { traceAgentUsage } from '../agent-trace.mjs';
 import {
     PROVIDER_FIRST_BYTE_TIMEOUT_MS,
+    PROVIDER_NONSTREAM_TOTAL_TIMEOUT_MS,
     createTimeoutSignal,
     createPassthroughSignal,
 } from '../stall-policy.mjs';
@@ -327,25 +328,37 @@ export class AnthropicProvider {
             try { streamController.abort?.(abortReason); } catch {}
             try { onStageChange?.('requesting', { transport: 'non-streaming-fallback' }); } catch {}
             const nonStreamingParams = { ...params, stream: false };
-            const message = await withRetry(
-                async ({ signal: attemptSignal }) => this.client.messages.create(nonStreamingParams, {
-                    signal: attemptSignal,
-                    ...(betaHeaders ? { headers: betaHeaders } : {}),
-                }),
-                {
-                    signal: totalSignal,
-                    maxAttempts: anthropicMaxAttempts(),
-                    backoffMs: ANTHROPIC_RETRY_BACKOFF_MS,
-                    retryJitterRatio: ANTHROPIC_RETRY_JITTER_RATIO,
-                    retryJitterMode: 'positive',
-                    perAttemptTimeoutMs: anthropicRequestTimeoutMs(),
-                    perAttemptLabel: `${this.name} Anthropic non-streaming fallback`,
-                    provider: 'anthropic',
-                    model: useModel,
-                    fallbackModel: opts._fallbackTriggered ? undefined : opts.fallbackModel,
-                },
+            const timeoutMs = Number(opts._nonStreamingTimeoutMs) > 0
+                ? Number(opts._nonStreamingTimeoutMs)
+                : PROVIDER_NONSTREAM_TOTAL_TIMEOUT_MS;
+            const lifetime = createTimeoutSignal(
+                totalSignal,
+                timeoutMs,
+                `${this.name} Anthropic non-streaming fallback`,
             );
-            return buildReturnFromParse(normalizeAnthropicNonStreamingResponse(message, useModel));
+            try {
+                const message = await withRetry(
+                    async ({ signal: attemptSignal }) => this.client.messages.create(nonStreamingParams, {
+                        signal: attemptSignal,
+                        ...(betaHeaders ? { headers: betaHeaders } : {}),
+                    }),
+                    {
+                        signal: lifetime.signal,
+                        maxAttempts: anthropicMaxAttempts(),
+                        backoffMs: ANTHROPIC_RETRY_BACKOFF_MS,
+                        retryJitterRatio: ANTHROPIC_RETRY_JITTER_RATIO,
+                        retryJitterMode: 'positive',
+                        perAttemptTimeoutMs: anthropicRequestTimeoutMs(),
+                        perAttemptLabel: `${this.name} Anthropic non-streaming fallback`,
+                        provider: 'anthropic',
+                        model: useModel,
+                        fallbackModel: opts._fallbackTriggered ? undefined : opts.fallbackModel,
+                    },
+                );
+                return buildReturnFromParse(normalizeAnthropicNonStreamingResponse(message, useModel));
+            } finally {
+                lifetime.cleanup();
+            }
         };
 
         const recoverNonStreaming = async (midState, streamingError, streamController) => {

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

@@ -167,7 +167,7 @@ function _pushOutputTextAnnotations(part, citations, citationKeys) {
     }
 }
 
-function _buildOpenAIHttpFallbackHeaders({ auth, cacheKey }) {
+function _buildOpenAIHttpFallbackHeaders({ auth, cacheKey, statelessConversation = false }) {
     if (auth?.type === 'openai-direct') {
         // Public API-key auth: Bearer <OPENAI_API_KEY>, no chatgpt-account-id /
         // originator (mirrors openai-ws-pool _buildHandshakeHeaders' direct
@@ -189,7 +189,7 @@ function _buildOpenAIHttpFallbackHeaders({ auth, cacheKey }) {
         'chatgpt-account-id': auth.account_id || '',
         'x-client-request-id': randomBytes(16).toString('hex'),
     };
-    if (cacheKey) {
+    if (cacheKey && !statelessConversation) {
         const sid = String(cacheKey);
         // Backend-native anchors (see openai-ws-pool _buildHandshakeHeaders):
         // the hyphenated `session-id`/`thread-id` pair; legacy underscore
@@ -252,7 +252,9 @@ export async function sendViaHttpSse({
     //       one still aborts, and
     //   (c) externalSignal (client disconnect / replaced-by-newer-request).
     const totalTimeout = createPassthroughSignal(externalSignal);
-    const headers = _buildOpenAIHttpFallbackHeaders({ auth, cacheKey });
+    const statelessConversation = opts?.statelessConversation === true
+        || _envFlag('MIXDOG_OAI_STATELESS_HTTP', false);
+    const headers = _buildOpenAIHttpFallbackHeaders({ auth, cacheKey, statelessConversation });
     const fetchStartedAt = Date.now();
     const responsesUrl = auth?.type === 'openai-direct'
         ? OPENAI_DIRECT_RESPONSES_URL

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

@@ -313,6 +313,57 @@ function _warmupContinuityTrace({
  *   err.attempts         — 1..HANDSHAKE_MAX_ATTEMPTS
  *   err.retryClassifier  — final classifier string, or null for permanent
  */
+/**
+ * Recovery-only encrypted-reasoning replay policy (codex full-frame parity).
+ *
+ * The request body may carry retained `reasoning` items
+ * (opts.replayEncryptedReasoning; default ON for openai-oauth, kill switch
+ * MIXDOG_OAI_DISABLE_REASONING_REPLAY=1).
+ * Whether they actually go on the wire is decided PER SOCKET ENTRY, once, at
+ * the first frame that entry sends, and stays sticky for its lifetime so the
+ * append-only prefix bookkeeping (entry.lastRequestInput) never mixes
+ * conventions:
+ *
+ *  - fresh entry + reasoning items present  → mid-session reconnect/recovery:
+ *    KEEP them. This is the codex behavior on a broken delta chain — the full
+ *    frame replays retained reasoning so the model does not re-reason the
+ *    whole transcript (client.rs full-request path).
+ *  - fresh entry + no reasoning items       → virgin session: nothing to
+ *    replay; the chain locks to today's wire (subsequent frames strip).
+ *  - entry with prior chain state (pooled reuse / completed warmup) → STRIP:
+ *    re-sending an rs_* item a live server chain already saw is rejected as a
+ *    duplicate.
+ *
+ * `suppress` (rejection safety net) forces the strip convention for the rest
+ * of the send. Returns the body unchanged when nothing needs stripping.
+ */
+export function _applyReasoningReplayPolicy(entry, body, { suppress = false } = {}) {
+    const input = Array.isArray(body?.input) ? body.input : null;
+    if (!entry || !input) return body;
+    const hasReasoning = input.some((item) => item?.type === 'reasoning');
+    if (suppress) {
+        entry.replayReasoning = false;
+    } else if (entry.replayReasoning == null) {
+        entry.replayReasoning = hasReasoning
+            && entry.lastResponseId == null
+            && entry.lastRequestInput == null;
+    }
+    if (!hasReasoning || entry.replayReasoning === true) return body;
+    return { ...body, input: input.filter((item) => item?.type !== 'reasoning') };
+}
+
+/**
+ * Server rejection of a replayed reasoning item (duplicate rs_* inside a
+ * stateful chain). Deliberately narrow: generic transport/5xx errors must not
+ * trip the replay-suppression retry.
+ */
+export function _isReasoningReplayRejection(err) {
+    const msg = String(err?.payload?.message || err?.message || '');
+    if (!msg) return false;
+    if (/\brs_[A-Za-z0-9]/i.test(msg) && /duplicate|already|exists|repeated/i.test(msg)) return true;
+    return /reasoning/i.test(msg) && /duplicate|already exists|repeated|invalid item/i.test(msg);
+}
+
 export async function _acquireWithRetry({
     auth,
     poolKey,
@@ -577,6 +628,10 @@ export async function sendViaWebSocket({
     // backs xAI, whose existing 429 handshake retry behavior must remain.
     const retry429 = traceProvider !== 'openai-oauth';
 
+    // Armed by the rejection safety net below: once a server rejects a
+    // replayed reasoning item, every later attempt of THIS send strips them.
+    let suppressReasoningReplay = false;
+
     for (let attemptIndex = 0; attemptIndex <= MAX_MIDSTREAM_RETRIES; attemptIndex++) {
         const handshakeStart = performance.now();
         let acquired;
@@ -739,6 +794,11 @@ export async function sendViaWebSocket({
         if (carryForwardCache && auth?.type === 'xai' && attemptIndex > 0 && !body.previous_response_id) {
             requestBody = { ...body, previous_response_id: carryForwardCache.lastResponseId };
         }
+        // Recovery-only reasoning replay: decide per entry whether retained
+        // reasoning items ride this chain (see _applyReasoningReplayPolicy).
+        // Must run BEFORE _computeDelta and the post-send bookkeeping so
+        // entry.lastRequestInput always records the post-policy input.
+        requestBody = _applyReasoningReplayPolicy(entry, requestBody, { suppress: suppressReasoningReplay });
         let warmupResult = null;
         // midState is shared between warmup and the main stream so warmup
         // failures (first-byte timeout, send-failure, ws_4000) flow through
@@ -1008,6 +1068,27 @@ export async function sendViaWebSocket({
                     continuation: midState.sawCompleted !== true,
                 });
             } catch { /* stamping is best-effort */ }
+            // Reasoning-replay rejection safety net: a duplicate-rs_ rejection
+            // on a frame that carried replayed reasoning gets ONE strip-and-
+            // retry within the existing attempt budget instead of failing the
+            // recovery turn outright. Unsafe outcomes (live text/tool output)
+            // keep their normal no-replay handling.
+            if (!suppressReasoningReplay
+                && entry.replayReasoning === true
+                && err?.unsafeToRetry !== true
+                && attemptIndex < MAX_MIDSTREAM_RETRIES
+                && _isReasoningReplayRejection(err)) {
+                suppressReasoningReplay = true;
+                firstAttemptError = err;
+                firstAttemptClassifier = 'reasoning_replay_rejected';
+                try { err.midstreamClassifier = 'reasoning_replay_rejected'; } catch {}
+                emitReconnectProgress({
+                    attempt: attemptIndex + 1,
+                    max: MAX_MIDSTREAM_RETRIES,
+                    classifier: 'reasoning_replay_rejected',
+                });
+                continue;
+            }
             const classifier = err?.unsafeToRetry === true
                 ? null
                 : _classifyMidstreamError(err, midState);

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

@@ -19,6 +19,8 @@ import { makeModelCache } from './model-cache.mjs';
 
 import { sendViaWebSocket } from './openai-oauth-ws.mjs';
 import { _combineUsageWithWarmup } from './openai-ws-events.mjs';
+import { acquireWebSocket, releaseWebSocket, hasPooledWebSocket } from './openai-ws-pool.mjs';
+import { _codexWsCompatibilityHeaders } from './openai-codex-metadata.mjs';
 import { resolveOpenAiTransportPolicy } from './openai-transport-policy.mjs';
 import {
     buildStableProviderPromptCacheKey,
@@ -769,6 +771,68 @@ export class OpenAIOAuthProvider {
             throw err;
         }
     }
+    /**
+     * Spawn-time transport prewarm (codex prewarm_websocket parity): open the
+     * session's WS socket while the caller is still assembling the session /
+     * first prompt, so the first real request reuses an already-open pooled
+     * socket instead of paying TLS + upgrade on its critical path.
+     *
+     * Best-effort by contract: every failure returns false and leaves the
+     * lazy per-send handshake untouched. Only runs when the thread-scoped
+     * prompt_cache_key derivation is active — with it disabled the real
+     * cacheKey depends on the built request body (instructions/tools hash),
+     * which does not exist yet at spawn prep, and a mismatched socket would
+     * just be evicted as incompatible on first acquire.
+     */
+    async prewarmWsTransportForSession(opts = {}, seams = {}) {
+        const _acquire = seams._acquire || acquireWebSocket;
+        const _release = seams._release || releaseWebSocket;
+        const _hasPooled = seams._hasPooled || hasPooledWebSocket;
+        const _warmVersion = seams._warmVersion || warmCodexClientVersion;
+        const poolKey = opts.sessionId || null;
+        if (!poolKey) return false;
+        try {
+            const transportPolicy = resolveOpenAiTransportPolicy();
+            if (transportPolicy.transport === 'http'
+                || _envFlag('MIXDOG_OPENAI_OAUTH_FORCE_HTTP_FALLBACK', false)) return false;
+            const threadKeyGate = String(process.env.MIXDOG_OAI_CODEX_THREAD_CACHE_KEY || '').toLowerCase();
+            if (threadKeyGate === '0' || threadKeyGate === 'false') return false;
+            if (_hasPooled(poolKey)) return true;
+            // Identical derivation to buildRequestBody's prompt_cache_key
+            // (thread-scoped branch), so the prewarmed socket's handshake
+            // session_id and pool-compatibility key match the first real send.
+            const cacheKey = buildStableProviderPromptCacheKey('openai-oauth', opts);
+            const [auth] = await Promise.all([this.ensureAuth(), _warmVersion()]);
+            const codexHeaders = _codexWsCompatibilityHeaders({ poolKey, cacheKey, sendOpts: opts, handshake: true });
+            const _t0 = Date.now();
+            const acquired = await _acquire({
+                auth,
+                poolKey,
+                cacheKey,
+                codexHeaders,
+                externalSignal: opts.signal || null,
+            });
+            _release({ entry: acquired.entry, poolKey, keep: true });
+            try {
+                appendAgentTrace({
+                    sessionId: poolKey,
+                    kind: 'spawn_ws_prewarm',
+                    provider: 'openai-oauth',
+                    transport: 'websocket',
+                    payload: { elapsed_ms: Date.now() - _t0, reused: acquired.reused === true },
+                });
+            } catch {}
+            if (process.env.MIXDOG_DEBUG_AGENT) {
+                process.stderr.write(`[agent-trace] spawn-ws-prewarm ok poolKey=${createHash('sha256').update(String(poolKey)).digest('hex').slice(0, 8)} elapsed=${Date.now() - _t0}ms\n`);
+            }
+            return true;
+        } catch (err) {
+            if (process.env.MIXDOG_DEBUG_AGENT) {
+                process.stderr.write(`[agent-trace] spawn-ws-prewarm failed err=${String(err?.message || err).slice(0, 160)}\n`);
+            }
+            return false;
+        }
+    }
     async listModels() {
         // Dynamic lookup via /backend-api/codex/models. Cached 24h.
         // Endpoint returns rich metadata (context_window, reasoning levels,