mixdog 0.9.40 → 0.9.43

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

@@ -7,10 +7,10 @@
  * the public functions so external callers keep their existing import path.
  */
 import { readFileSync, existsSync, statSync } from 'fs';
-import { join } from 'path';
+import { join, resolve } from 'path';
 import { createServer } from 'http';
 import { randomBytes, createHash } from 'crypto';
-import { writeJsonAtomicSync } from '../../../shared/atomic-file.mjs';
+import { writeJsonAtomicSync, withFileLock } from '../../../shared/atomic-file.mjs';
 import { resolvePluginData } from '../../../shared/plugin-paths.mjs';
 import { getLlmDispatcher } from '../../../shared/llm/http-agent.mjs';
 
@@ -33,6 +33,7 @@ export const TOKEN_URL = assertSafeTokenURL(process.env.ANTHROPIC_OAUTH_TOKEN_UR
 export const DEFAULT_CREDENTIALS_PATH = join(resolvePluginData(), 'anthropic-oauth-credentials.json');
 export const CLAUDE_CODE_CLIENT_ID = process.env.ANTHROPIC_OAUTH_CLIENT_ID || '9d1c250a-e61b-44d9-88ed-5944d1962f5e';
 export const TOKEN_REFRESH_SKEW_MS = 5 * 60_000;
+export const ANTHROPIC_OAUTH_REFRESH_DISABLED_ENV = 'MIXDOG_ANTHROPIC_OAUTH_REFRESH_DISABLED';
 const CLAUDE_AI_AUTHORIZE_URL = 'https://claude.com/cai/oauth/authorize';
 const ALL_OAUTH_SCOPES = [
     'org:create_api_key',
@@ -52,7 +53,10 @@ const OAUTH_SUCCESS_REDIRECT_URL = process.env.ANTHROPIC_OAUTH_SUCCESS_REDIRECT_
 const OAUTH_LOGIN_TIMEOUT_MS = 5 * 60_000;
 const OAUTH_TOKEN_TIMEOUT_MS = 30_000;
 
-export const DEFAULT_CLI_VERSION = '2.1.77';
+// Anthropic's token edge validates the Claude Code client identity. Keep this
+// fallback aligned with the current official CLI while retaining the env
+// override for seats where Claude Code is updated ahead of Mixdog.
+export const DEFAULT_CLI_VERSION = '2.1.207';
 
 export function resolveCliVersion() {
     return process.env.MIXDOG_CLI_VERSION
@@ -67,10 +71,9 @@ function _pushUnique(list, value) {
 }
 
 export function credentialCandidates() {
-    const paths = [];
-    _pushUnique(paths, process.env.ANTHROPIC_OAUTH_CREDENTIALS_PATH);
-    _pushUnique(paths, DEFAULT_CREDENTIALS_PATH);
-    return paths;
+    const explicit = process.env.ANTHROPIC_OAUTH_CREDENTIALS_PATH;
+    if (explicit) return [resolve(explicit)];
+    return [DEFAULT_CREDENTIALS_PATH];
 }
 
 // Fallback expiry from the access_token's JWT `exp` claim (epoch ms) when the
@@ -109,6 +112,11 @@ function _loadCredentialsFile(path) {
     }
 }
 
+export function loadCredentialsFromPath(path) {
+    if (!path) return null;
+    return _loadCredentialsFile(resolve(path));
+}
+
 // Cross-process safe credential save. Lockfile (O_EXCL) prevents two Mixdog
 // refreshers from clobbering each other; atomic rename guarantees readers see
 // either the old or new file, never a half-written one. Used so refresh_token
@@ -205,17 +213,52 @@ export function _normalizeExpiresAt(value) {
     return value < 1e12 ? value * 1000 : value;
 }
 
-export function _scrubTokens(text) {
-    return String(text || '')
-        .replace(/Bearer [A-Za-z0-9._\-]+/g, 'Bearer [REDACTED]')
+export function _scrubTokens(text, secretValues = []) {
+    let scrubbed = String(text || '')
+        .replace(/Bearer [A-Za-z0-9._\-]+/gi, 'Bearer [REDACTED]')
         .replace(/sk-ant-[A-Za-z0-9._\-]+/g, '[REDACTED]')
         .replace(/"access[Tt]oken"\s*:\s*"[^"]+"/g, '"accessToken":"[REDACTED]"')
         .replace(/"refresh[Tt]oken"\s*:\s*"[^"]+"/g, '"refreshToken":"[REDACTED]"')
         .replace(/"access_token"\s*:\s*"[^"]+"/g, '"access_token":"[REDACTED]"')
         .replace(/"refresh_token"\s*:\s*"[^"]+"/g, '"refresh_token":"[REDACTED]"');
+    // Token services sometimes echo submitted values in non-JSON diagnostics.
+    // Scrub the exact request secrets as a final guard without logging them.
+    for (const secret of secretValues) {
+        if (typeof secret === 'string' && secret) {
+            scrubbed = scrubbed.split(secret).join('[REDACTED]');
+        }
+    }
+    return scrubbed;
 }
 
-export async function refreshOAuthCredentials(creds) {
+function _tokenEndpointError(operation, status, text, secretValues = []) {
+    const safeDetail = _scrubTokens(text, secretValues)
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 500);
+    const detail = safeDetail ? `: ${safeDetail}` : '';
+    const compatibility = status === 403
+        ? (
+            ` Anthropic returned HTTP 403 for a request sent as claude-cli/${resolveCliVersion()}.`
+            + ' Possible causes include OAuth client compatibility, account or scope policy,'
+            + ' an intercepting proxy/VPN/WAF, or regional endpoint restrictions.'
+            + ' Verify the account has Claude Code access and the required scopes;'
+            + ' update Mixdog or set MIXDOG_CLI_VERSION to the installed official Claude Code version;'
+            + ' then retry sign-in via /providers without an intercepting network layer if applicable.'
+        )
+        : '';
+    return new Error(`${operation} ${status}${detail}.${compatibility}`);
+}
+
+export function isAnthropicOAuthRefreshDisabled() {
+    return process.env[ANTHROPIC_OAUTH_REFRESH_DISABLED_ENV] === '1';
+}
+
+function _refreshLockPath(path) {
+    return `${resolve(path)}.anthropic-oauth-refresh.lock`;
+}
+
+async function _refreshOAuthCredentialsUnlocked(creds) {
     if (!creds?.refreshToken) {
         throw new Error('Anthropic OAuth refresh token not available. Open /providers in mixdog to sign in again.');
     }
@@ -248,7 +291,15 @@ export async function refreshOAuthCredentials(creds) {
         try { json = text ? JSON.parse(text) : null; } catch { /* handled below */ }
         if (!res.ok) {
             const isInvalidGrant = text.includes('invalid_grant') || json?.error === 'invalid_grant';
-            throw Object.assign(new Error(`token refresh ${res.status}: ${_scrubTokens(text).slice(0, 200)}`), { isInvalidGrant });
+            throw Object.assign(
+                _tokenEndpointError(
+                    'token refresh',
+                    res.status,
+                    text,
+                    [creds.refreshToken, creds.accessToken],
+                ),
+                { isInvalidGrant },
+            );
         }
 
         const accessToken = json?.access_token || json?.accessToken;
@@ -294,6 +345,130 @@ export async function refreshOAuthCredentials(creds) {
     }
 }
 
+export async function refreshOAuthCredentials(creds) {
+    if (isAnthropicOAuthRefreshDisabled()) {
+        throw new Error(
+            'Anthropic OAuth refresh is disabled in this process; '
+            + 'host credential preflight must provide a fresh snapshot.',
+        );
+    }
+    const credentialPath = resolve(
+        creds?.path
+        || process.env.ANTHROPIC_OAUTH_CREDENTIALS_PATH
+        || DEFAULT_CREDENTIALS_PATH,
+    );
+    return withFileLock(_refreshLockPath(credentialPath), async () => {
+        const disk = _loadCredentialsFile(credentialPath);
+        // A waiter that started with the prior generation must consume the
+        // winner's persisted rotation, not replay the single-use token.
+        if (disk?.accessToken && creds?.accessToken
+            && disk.accessToken !== creds.accessToken
+            && (!disk.expiresAt || disk.expiresAt > Date.now())) {
+            return disk;
+        }
+        return _refreshOAuthCredentialsUnlocked(
+            disk || { ...creds, path: credentialPath },
+        );
+    }, {
+        timeoutMs: 120_000,
+        staleMs: 120_000,
+        secret: true,
+    });
+}
+
+/**
+ * Serialize host-side refresh, establish a bounded access-token lease, and
+ * optionally write an owner-only snapshot while the lease lock is still held.
+ * The returned object deliberately contains metadata only, never token bytes.
+ */
+export async function preflightAnthropicOAuthCredentials({
+    credentialsPath = null,
+    minimumValidityMs = TOKEN_REFRESH_SKEW_MS,
+    snapshotPath = null,
+    refreshFn = refreshOAuthCredentials,
+    now = () => Date.now(),
+    lockTimeoutMs = 120_000,
+} = {}) {
+    if (isAnthropicOAuthRefreshDisabled()) {
+        throw new Error('Anthropic OAuth host preflight cannot run while refresh is disabled.');
+    }
+    const requiredMs = Number(minimumValidityMs);
+    if (!Number.isFinite(requiredMs) || requiredMs < 0) {
+        throw new Error('Anthropic OAuth host preflight minimumValidityMs must be a non-negative number.');
+    }
+    const pinnedPath = resolve(
+        credentialsPath
+        || process.env.ANTHROPIC_OAUTH_CREDENTIALS_PATH
+        || DEFAULT_CREDENTIALS_PATH,
+    );
+    const initial = _loadCredentialsFile(pinnedPath);
+    if (!initial?.path || !initial.accessToken) {
+        throw new Error(
+            `Anthropic OAuth host preflight found no credentials at ${pinnedPath}. `
+            + 'Open /providers in mixdog to sign in.',
+        );
+    }
+
+    return withFileLock(_refreshLockPath(pinnedPath), async () => {
+        let leased = _loadCredentialsFile(pinnedPath);
+        if (!leased?.path || !leased.accessToken) {
+            throw new Error('Anthropic OAuth credentials disappeared during host preflight.');
+        }
+
+        const validAfter = now() + requiredMs;
+        let refreshed = false;
+        if (!leased.expiresAt || leased.expiresAt < validAfter) {
+            if (!leased.refreshToken) {
+                throw new Error(
+                    'Anthropic OAuth host preflight cannot establish the required lease: '
+                    + 'refresh token is unavailable.',
+                );
+            }
+            // The public refresh function owns this same lock. Call its
+            // unlocked exchange only because preflight already owns it;
+            // injected test exchanges run under the identical ownership.
+            const next = refreshFn === refreshOAuthCredentials
+                ? await _refreshOAuthCredentialsUnlocked(leased)
+                : await refreshFn(leased);
+            const persisted = _loadCredentialsFile(pinnedPath);
+            if (!persisted?.accessToken || persisted.accessToken !== next?.accessToken) {
+                throw new Error('Anthropic OAuth host preflight refresh was not persisted.');
+            }
+            leased = persisted;
+            refreshed = true;
+        }
+
+        const remainingMs = leased.expiresAt ? leased.expiresAt - now() : 0;
+        if (remainingMs < requiredMs) {
+            throw new Error(
+                `Anthropic OAuth host preflight cannot satisfy the ${Math.ceil(requiredMs / 1000)}s `
+                + `credential lease (provider granted ${Math.max(0, Math.floor(remainingMs / 1000))}s).`,
+            );
+        }
+
+        if (snapshotPath) {
+            const raw = JSON.parse(readFileSync(leased.path, 'utf-8'));
+            // Containers need only the leased access token. Never distribute
+            // the rotating refresh credential, even into disposable storage.
+            if (raw?.claudeAiOauth) {
+                delete raw.claudeAiOauth.refreshToken;
+                delete raw.claudeAiOauth.refresh_token;
+            }
+            _saveCredentialsFile(snapshotPath, raw);
+        }
+        return {
+            expiresAt: leased.expiresAt,
+            remainingMs,
+            refreshed,
+            snapshotWritten: Boolean(snapshotPath),
+        };
+    }, {
+        timeoutMs: lockTimeoutMs,
+        staleMs: 120_000,
+        secret: true,
+    });
+}
+
 // --- Login flow (PKCE loopback, export for setup UI / CLI) ---
 
 function _oauthGeneratePKCE() {
@@ -358,7 +533,12 @@ async function exchangeAuthorizationCode({ pkce, code, state, redirectUri }) {
     });
     if (!tokenRes.ok) {
         const text = await tokenRes.text().catch(() => '');
-        throw new Error(`[anthropic-oauth] token exchange ${tokenRes.status}: ${_scrubTokens(text).slice(0, 500)}`);
+        throw _tokenEndpointError(
+            '[anthropic-oauth] token exchange',
+            tokenRes.status,
+            text,
+            [cleanCode, pkce.verifier, state],
+        );
     }
     const json = await tokenRes.json();
     const accessToken = json?.access_token || json?.accessToken;

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

@@ -27,6 +27,7 @@ import {
 import { sanitizeToolPairs, sanitizeAnthropicContentPairs, foldUserTextIntoToolResultTail } from '../session/context-utils.mjs';
 import {
     TOKEN_REFRESH_SKEW_MS,
+    isAnthropicOAuthRefreshDisabled,
     resolveCliVersion,
     loadCredentials,
     hasAnthropicOAuthCredentials,
@@ -342,7 +343,7 @@ function toAnthropicMessages(messages) {
         const m = messages[idx];
         if (m.role === 'system') continue;
 
-        if (m.role === 'assistant' && (m.toolCalls?.length || m.assistantBlocks?.length)) {
+        if (m.role === 'assistant' && (m.toolCalls?.length || m.assistantBlocks?.length || m.thinkingBlocks?.length)) {
             let content;
             if (m.assistantBlocks?.length) {
                 content = m.assistantBlocks.slice();
@@ -358,7 +359,7 @@ function toAnthropicMessages(messages) {
                     }
                 }
                 if (m.content) content.push({ type: 'text', text: m.content });
-                for (const tc of m.toolCalls) {
+                for (const tc of m.toolCalls || []) {
                     content.push({
                         type: 'tool_use',
                         id: tc.id,
@@ -703,6 +704,12 @@ export class AnthropicOAuthProvider {
         const expiring = this.credentials.expiresAt
             && this.credentials.expiresAt < Date.now() + TOKEN_REFRESH_SKEW_MS;
         if (forceRefresh || expiring) {
+            if (isAnthropicOAuthRefreshDisabled()) {
+                throw new Error(
+                    'Anthropic OAuth credentials require refresh, but refresh is disabled '
+                    + 'in this container. Host credential preflight must provide a fresh snapshot.',
+                );
+            }
             this.credentials = await this._refreshCredentials({ force: forceRefresh, reason });
         }
 
@@ -710,6 +717,12 @@ export class AnthropicOAuthProvider {
     }
 
     async _refreshCredentials({ force = false, reason = 'preemptive' } = {}) {
+        if (isAnthropicOAuthRefreshDisabled()) {
+            throw new Error(
+                'Anthropic OAuth refresh is disabled in this container; '
+                + 'host credential preflight must provide a fresh snapshot.',
+            );
+        }
         const currentToken = this.credentials?.accessToken || null;
         const disk = loadCredentials();
         const validAfter = Date.now() + (force ? 0 : TOKEN_REFRESH_SKEW_MS);

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

@@ -111,6 +111,7 @@ export async function parseSSEStream(response, signal, abortStream, onStreamDelt
     let toolCalls = [];
     let usage = { inputTokens: 0, outputTokens: 0, cachedTokens: 0, cacheWriteTokens: 0, raw: null };
     let stopReason = null;
+    let stopDetails;
     let buffer = '';
     let idleTimedOut = false;
     let firstMessageTimedOut = false;
@@ -546,6 +547,18 @@ export async function parseSSEStream(response, signal, abortStream, onStreamDelt
                         if (event.delta?.stop_reason) {
                             stopReason = event.delta.stop_reason;
                         }
+                        if (event.delta && (event.delta.stop_details != null || event.delta.category != null)) {
+                            const details = event.delta.stop_details;
+                            stopDetails = details && typeof details === 'object' && !Array.isArray(details)
+                                ? {
+                                    ...details,
+                                    ...(event.delta.category != null ? { category: event.delta.category } : {}),
+                                }
+                                : {
+                                    ...(details != null ? { value: details } : {}),
+                                    ...(event.delta.category != null ? { category: event.delta.category } : {}),
+                                };
+                        }
                         if (event.usage) {
                             usage.outputTokens = event.usage.output_tokens || 0;
                             usage.raw = { ...(usage.raw || {}), ...event.usage };
@@ -615,6 +628,7 @@ export async function parseSSEStream(response, signal, abortStream, onStreamDelt
             toolCalls: toolCalls.length ? toolCalls : undefined,
             usage,
             stopReason,
+            stopDetails,
             hasThinkingContent,
             contentBlockTypes: Array.from(contentBlockTypes),
             // Ordered extended-thinking blocks (verbatim thinking text +

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

@@ -347,7 +347,7 @@ function toAnthropicMessages(messages) {
     for (let idx = 0; idx < messages.length; idx++) {
         const m = messages[idx];
         if (m.role === 'system') continue;
-        if (m.role === 'assistant' && (m.toolCalls?.length || m.assistantBlocks?.length)) {
+        if (m.role === 'assistant' && (m.toolCalls?.length || m.assistantBlocks?.length || m.thinkingBlocks?.length)) {
             let content;
             if (m.assistantBlocks?.length) {
                 content = m.assistantBlocks.slice();
@@ -362,7 +362,7 @@ function toAnthropicMessages(messages) {
                     }
                 }
                 if (m.content) content.push({ type: 'text', text: m.content });
-                for (const tc of m.toolCalls) {
+                for (const tc of m.toolCalls || []) {
                     content.push({
                         type: 'tool_use',
                         id: tc.id,

package/src/runtime/agent/orchestrator/providers/media-normalization.mjs

@@ -1,3 +1,5 @@
+import { createHash } from 'node:crypto';
+
 const DEFAULT_IMAGE_MIME = 'image/png';
 
 function cleanMimeType(value) {
@@ -96,6 +98,9 @@ function contentParts(content) {
     if (content && typeof content === 'object' && Array.isArray(content.content)) {
         return content.content;
     }
+    if (content && typeof content === 'object'
+        && (imageUrlFromPart(content) || imageFileIdFromPart(content)
+            || imageFileUriFromPart(content) || geminiInlineInfo(content))) return [content];
     return null;
 }
 
@@ -108,9 +113,61 @@ function jsonFallbackFromPart(block) {
 }
 
 export function contentHasImage(content) {
+    return contentImageCount(content) > 0;
+}
+
+export function contentImageCount(content) {
+    return contentImageDescriptors(content).length;
+}
+
+function positiveDimension(...values) {
+    for (const value of values) {
+        const number = Number(value);
+        if (Number.isFinite(number) && number > 0) return number;
+    }
+    return null;
+}
+
+function imageIdentity(kind, value, mimeType = '') {
+    return createHash('sha256')
+        .update(`${kind}\0${mimeType}\0`)
+        .update(String(value || ''))
+        .digest('hex');
+}
+
+function imageDescriptor(part) {
+    if (!part || typeof part !== 'object') return null;
+    const info = imageInfo(part);
+    const inline = geminiInlineInfo(part);
+    const url = imageUrlFromPart(part);
+    const fileId = imageFileIdFromPart(part);
+    const fileUri = imageFileUriFromPart(part);
+    if (!info && !inline && !url && !fileId && !fileUri) return null;
+    const imageUrl = part.image_url && typeof part.image_url === 'object' ? part.image_url : null;
+    const source = part.source && typeof part.source === 'object' ? part.source : null;
+    const inlineData = part.inlineData || part.inline_data;
+    const dimensions = part.dimensions && typeof part.dimensions === 'object' ? part.dimensions : null;
+    const width = positiveDimension(part.width, dimensions?.width, imageUrl?.width, source?.width, inlineData?.width);
+    const height = positiveDimension(part.height, dimensions?.height, imageUrl?.height, source?.height, inlineData?.height);
+    const detail = String(part.detail ?? imageUrl?.detail ?? source?.detail ?? inlineData?.detail ?? 'auto').toLowerCase();
+    if (info || inline) {
+        const raw = info || inline;
+        return {
+            identity: imageIdentity('inline', raw.data, raw.mimeType),
+            width,
+            height,
+            detail,
+        };
+    }
+    if (fileId) return { identity: imageIdentity('file-id', fileId), width, height, detail };
+    if (fileUri) return { identity: imageIdentity('file-uri', fileUri.fileUri, fileUri.mimeType), width, height, detail };
+    return { identity: imageIdentity('url', url), width, height, detail };
+}
+
+export function contentImageDescriptors(content) {
     const parts = contentParts(content);
-    if (!parts) return false;
-    return parts.some((part) => !!imageUrlFromPart(part) || !!imageFileIdFromPart(part) || !!imageFileUriFromPart(part) || !!geminiInlineInfo(part));
+    if (!parts) return [];
+    return parts.map(imageDescriptor).filter(Boolean);
 }
 
 export function contentToText(content, fallback = '') {

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

@@ -51,6 +51,11 @@ import {
     createActiveToolItemTracker,
     hasCompleteToolCall as sharedHasCompleteToolCall,
 } from './tool-stream-state.mjs';
+import {
+    enableSessionTransportTracking,
+    disableSessionTransportTracking,
+    markSessionTransportActivity,
+} from '../session/manager/runtime-liveness.mjs';
 
 // Facade re-exports: the delta/matching helpers and usage/event helpers below
 // were extracted to openai-ws-delta.mjs / openai-ws-events.mjs (no behavior
@@ -92,6 +97,11 @@ export const WS_PRE_RESPONSE_CREATED_MS = (() => {
 // including metadata/keepalive, proves the socket is live.
 export const WS_INTER_CHUNK_MS = PROVIDER_WS_INTER_CHUNK_TIMEOUT_MS;
 const X_CODEX_TURN_STATE_HEADER = 'x-codex-turn-state';
+const WS_TRACE_ENABLED = process.env.MIXDOG_WS_TRACE === '1';
+
+function _writeWsLifecycleTrace(lifecycle) {
+    process.stderr.write(`[ws-trace] t=${new Date().toISOString()} lifecycle=${lifecycle}\n`);
+}
 
 function _responseItemKey(item, fallbackIndex = 0) {
     if (!item || typeof item !== 'object') return `primitive:${fallbackIndex}`;
@@ -239,6 +249,7 @@ export async function _streamResponse({
 }) {
     const errLabel = _wsErrLabel(traceProvider);
     const socket = entry.socket;
+    enableSessionTransportTracking(state?.sessionId);
     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
@@ -471,6 +482,9 @@ export async function _streamResponse({
     let messageHandler = null;
     let closeHandler = null;
     let errorHandler = null;
+    let traceOpenHandler = null;
+    let tracePingHandler = null;
+    let tracePongHandler = null;
     // SEMANTIC idle timer: distinct from the inter-chunk
     // timer, which resets on EVERY frame (rate_limits/metadata/keepalive keep
     // the socket "alive"). This timer resets ONLY on meaningful output deltas
@@ -668,6 +682,7 @@ export async function _streamResponse({
         // frames never reach here, so they cannot satisfy the watchdog.
         const bumpSemanticIdle = () => { clearFirstMeaningfulWatchdog(); resetSemanticIdle(); };
         const cleanup = () => {
+            disableSessionTransportTracking(midState.sessionId);
             if (idleTimer) clearTimeout(idleTimer);
             if (interChunkTimer) { clearTimeout(interChunkTimer); interChunkTimer = null; }
             if (semanticIdleTimer) { clearTimeout(semanticIdleTimer); semanticIdleTimer = null; }
@@ -676,6 +691,9 @@ export async function _streamResponse({
             if (messageHandler) socket.off('message', messageHandler);
             if (closeHandler) socket.off('close', closeHandler);
             if (errorHandler) socket.off('error', errorHandler);
+            if (traceOpenHandler) socket.off('open', traceOpenHandler);
+            if (tracePingHandler) socket.off('ping', tracePingHandler);
+            if (tracePongHandler) socket.off('pong', tracePongHandler);
             if (abortHandler && externalSignal) externalSignal.removeEventListener('abort', abortHandler);
         };
         const finish = () => {
@@ -755,6 +773,15 @@ export async function _streamResponse({
             const text = typeof data === 'string' ? data : data.toString('utf-8');
             const event = _parseEvent(text);
             if (!event) return;
+            if (WS_TRACE_ENABLED) {
+                const type = typeof event.type === 'string' ? event.type : '';
+                const empty = type.endsWith('.delta')
+                    && (event.delta == null || event.delta === '');
+                process.stderr.write(
+                    `[ws-trace] t=${new Date().toISOString()} type=${type} bytes=${Buffer.byteLength(text)} empty=${empty}\n`,
+                );
+            }
+            markSessionTransportActivity(midState.sessionId);
             _traceWsHeaderKeys(entry, event, midState, traceProvider, model);
             _captureTurnStateFromEvent(entry, event);
             if (event.error) {
@@ -780,12 +807,9 @@ export async function _streamResponse({
                     // first-meaningful watchdog (keepalive/metadata frames do
                     // NOT reach this case, so they never clear it).
                     clearFirstMeaningfulWatchdog();
-                    // Arm the semantic idle/stall timer from response.created
-                    // too: it otherwise only arms on the first meaningful delta
-                    // (bumpSemanticIdle), so a created+keepalive-only stream that
-                    // never emits a delta would stall unbounded until the outer
-                    // watchdog. Arming here bounds that gap.
-                    resetSemanticIdle();
+                    // Do not arm semantic idle until actual model progress.
+                    // Transport-only reasoning heartbeats are bounded by the
+                    // outer first-visible ceiling instead.
                     break;
                 case 'response.output_text.delta':
                     try {
@@ -814,14 +838,12 @@ export async function _streamResponse({
                 case 'response.reasoning_summary_text.delta':
                     if (event.type === 'response.reasoning_text.delta') reasoningTextDeltaCount += 1;
                     else reasoningSummaryTextDeltaCount += 1;
-                    // Reasoning text is live model progress — refresh
-                    // lastStreamDeltaAt so stream-watchdog does not flag a
-                    // long reasoning span as a stall. The local WS idle timer
-                    // was already reset by resetIdle() at the top of
-                    // messageHandler. Reasoning is still suppressed from user
-                    // content (no `content +=` here).
-                    try { onStreamDelta?.(); } catch {}
-                    bumpSemanticIdle();
+                    // Only non-empty reasoning text is model progress. Empty
+                    // deltas remain transport activity via resetIdle() above.
+                    if (event.delta) {
+                        try { onStreamDelta?.(); } catch {}
+                        bumpSemanticIdle();
+                    }
                     break;
                 case 'response.output_item.added':
                     if (event.item?.type === 'function_call') {
@@ -1184,25 +1206,24 @@ export async function _streamResponse({
                         && event.type.startsWith('response.reasoning')
                         && event.type.endsWith('.delta')) {
                         reasoningOtherDeltaCount += 1;
-                        // These ARE live model progress (reviewer Medium): a
-                        // provider that emits only these reasoning variants for a
-                        // long span would otherwise trip the SEMANTIC idle abort.
-                        // Refresh both the watchdog and the semantic idle timer,
-                        // matching the named reasoning_text.delta case above.
-                        try { onStreamDelta?.(); } catch {}
-                        bumpSemanticIdle();
+                        // Only non-empty reasoning deltas are model progress;
+                        // empty variants remain transport activity only.
+                        if (event.delta) {
+                            try { onStreamDelta?.(); } catch {}
+                            bumpSemanticIdle();
+                        }
                     }
-                    // response.in_progress is a server lifecycle heartbeat during
-                    // long tool/generation latency — reset semantic idle so it is
-                    // not counted as silence (resetIdle already ran at the top).
+                    // response.in_progress is transport activity only;
+                    // resetIdle() already kept the socket alive above.
                     else if (event.type === 'response.in_progress') {
-                        resetSemanticIdle();
+                        // No semantic/model progress.
                     }
                     // Other trace-only events fall through.
                     break;
             }
         };
         closeHandler = (code, reason) => {
+            if (WS_TRACE_ENABLED) _writeWsLifecycleTrace('close');
             if (done) return;
             midState.wsCloseCode = code;
             if (!terminalError) {
@@ -1219,6 +1240,7 @@ export async function _streamResponse({
             finish();
         };
         errorHandler = (err) => {
+            if (WS_TRACE_ENABLED) _writeWsLifecycleTrace('error');
             if (done) return;
             const wrapped = err instanceof Error ? err : new Error(String(err));
             if (terminalError) {
@@ -1268,6 +1290,15 @@ export async function _streamResponse({
         socket.on('message', messageHandler);
         socket.on('close', closeHandler);
         socket.on('error', errorHandler);
+        if (WS_TRACE_ENABLED) {
+            traceOpenHandler = () => _writeWsLifecycleTrace('open');
+            tracePingHandler = () => _writeWsLifecycleTrace('ping');
+            tracePongHandler = () => _writeWsLifecycleTrace('pong');
+            socket.on('open', traceOpenHandler);
+            socket.on('ping', tracePingHandler);
+            socket.on('pong', tracePongHandler);
+            if (socket.readyState === WebSocket.OPEN) _writeWsLifecycleTrace('open');
+        }
         armPreStreamWatchdog();
         armFirstMeaningfulWatchdog();
         // Periodic client-side WS ping while the stream is active. The server's
@@ -1280,6 +1311,7 @@ export async function _streamResponse({
         keepaliveTimer = setInterval(() => {
             try {
                 if (socket.readyState !== WebSocket.OPEN) return;
+                if (WS_TRACE_ENABLED) _writeWsLifecycleTrace('ping');
                 socket.ping();
             } catch {}
         }, 10_000);